DSH plugin jobs: output rings, offsets, and JobView
Background output problems are rarely "it writes too slowly"; they are usually a cursor treated as shared state or an output event mistaken for a data push. DSH plugin's output ring uses absolute byte offsets as its only coordinate: writes land whole, offsets never move once assigned, and reads split into consuming and non-consuming paths.
ID, kind, and status each do one job
The id is a namespace; access control comes from owner authorization.(source)
JobId is a branded <kind>-<short-uuid> where the kind is followed by 16 lowercase hex characters of a UUID. The reference is explicit: access control depends on owner authorization, not on id secrecy. So never treat an id as a capability credential — it is only a label.
JobKind derives from a merge-extensible map, and the registry treats each value as an opaque id namespace. JobStatus has exactly five values: running, stopping, completed, killed, failed.
Producer-specific facts land in two places: JobView.progress while running, JobView.detail after settlement. So "progress" in a list and "final cause" are not the same data — do not mix them.
Owned jobs leave two log records
job/registered and job/settled are durable facts, but they can be incomplete.(source)
Jobs with an owner publish these two records into the owning Session, and the globally unique jobId both pairs them and gates the running job. The SDK forwards these log-only records through session.event without depending on output reads.
Read the semantics of the timestamp carefully: it describes registry commit time, not CPU time and not an exact OS process boundary. Without a settlement record, the interval is simply incomplete.
producerReported means the producer reported a terminal state by resolving done; it is false on forced teardown or promise rejection. It does not independently confirm resources were released — an easy misread, so never treat it as proof that cleanup finished.
Three timing facts belong in your checklist:
job/settledmay arrive afterturn/end;- an SDK run result covers only its own observation window, so consumers needing later settlement must keep the Session subscription or read persisted history;
- app teardown may stop event routing or close write handles before the last settlement is stored, and consumers must not invent an end timestamp.
The producer owns resources; the runtime owns identity
run() is the dividing line: it may fail before, and no prechecks happen after.(source)
JobSpec declares identity, owning session, an optional pull-based output source, and a launcher. The runtime completes prechecks, calls run() with a JobHandle, then commits the registration — no failing step follows. The producer owns execution resources; the runtime owns identity, access, lifecycle state, and the output ring.
outputLimitBytes is frequently misread: it caps UTF-8 bytes per complete model-facing completion notice or output read, including controller state metadata. It is unrelated to ring retention — it constrains the consumer-side model surface and never constrains observers.
owner is strict: it must be the live Agent currently registered under that id, and destroying it cancels and awaits the job. Omitting owner creates an unowned job visible to any caller until the service is disposed.
JobHooks has only two members: cancel(reason?) must be synchronous, idempotent, and eventually settle done, with throws propagating; done resolves after the producer releases resources rather than merely when the work finishes, and must never reject — the runtime turns a rejection into failed. If teardown cancellation throws, the runtime may force-fail only the registry record without claiming the work stopped.
The output ring: absolute offsets, whole-block landing, sealed settlement
Offsets are the only coordinate; your read path decides whether bytes repeat or vanish.(source)
Each job owns a bounded ring. A pull source is pumped into it, JobHandle.append pushes whole blocks, and the model consumes it through the registry-held cursor (JobRegistry.read) while any number of observers read at absolute byte offsets (JobRegistry.readAt) without interfering.
JobChunk has four fields: at, text, optional channel, and optional gapBefore. at is the absolute offset of the first byte and never moves once assigned; gapBefore says bytes immediately preceding this block were lost, whether from the producer or from retention.
JobChannel marks stdout, stderr, and log. Note that log is producer narration that reaches observers only and never enters the model's consuming read — good for "what I am doing," bad for content the model must see.
Settlement seals the stream and trims retention to the settled cap; the ring has no separate lifecycle. JobOutputRead.next is always a block boundary, because appends land whole and trimming only advances the block start. The reference flags one risk: if a provider returns a partial block, consumers concatenating by block silently duplicate text.
Spill files retained by a pull source are job metadata (JobView.output.spillPaths, refreshed on every pump read), not per-chunk metadata. So even after the ring evicts bytes and the gap block itself, the model's lost-output notice can still name that file.
Consumers see exactly one JobView
Model tools, browser rosters, and observation streams read one projection, not three field sets.(source)
JobView is a read-only projection, a fresh object per call and never live registry state. owner carries the session id defining the access boundary; the registry resolves the live Agent behind it for lifecycle cleanup but never hands that object out.
Field duties: progress is the producer's live line, cleared at settlement; detail is the terminal cause, merging the recorded kill reason; output gives three coordinates — total is the next block start (0 when nothing was written), and earliest is the oldest retained byte, revealing over-trimming precisely when it exceeds zero.
list, get, read, readAt, kill, and wait all take the caller's SessionId: omit the caller and only unowned jobs are visible; pass a session and that session's jobs are visible too. That rule explains both "I lost my job" reports — the job did not vanish, the caller identity was missing.
Events announce, never push payload
An output event is a signal; you still fetch the bytes yourself.(source)
The registry announces each commit through one filtered stream. Lifecycle events (registered, progress, stopping, removed) carry the projection after the commit they announce; settled additionally marks cause and awaited, where the latter says whether this settlement released a wait caller so the announcer can skip the copy already delivered.
output events carry only the id and the new total. Observers schedule readAt from their own cursor, and the registry never pushes payload. That leaves "how much and from where" entirely to the consumer — and means you cannot reconstruct content from events.
Verification: write beyond ring capacity
Cover three things: offset continuity, locating data after eviction, and sealing at settlement.(source)
appendthree text blocks, record eachat, and assert each start equals the running total of prior lengths.- Read once with
readAt(0), assertnextequals the currenttotal, and read again to confirm the same block is not returned twice. - Write past ring capacity and assert
earliestis greater than zero andreadAt(0)reportslossy. - Check
output.spillPathsand assert the gap still resolves to the full stream file even when the gap block itself was evicted. - Consume with
readup to settlement and assertresultappears only on the first read after settlement. appendafter settlement and assert the write is recorded and discarded rather than throwing and breaking teardown.
If step 2 repeats data, the consumer probably treated next as "bytes already read" and added the block length instead of using the returned value.
For how jobs connect to subprocess handles, see subprocess spawn spec; for the foreground boundary, see shell resolve split.
One line to close: an id is not a credential, the two log records can be incomplete, offsets never move while reads split into consuming and non-consuming, output events only signal, and settlement seals the ring.
FAQ
No. DSH plugin access control relies on owner authorization, not id secrecy. DSH plugin builds JobId as a branded kind plus short uuid, so knowing an id does not grant permission to operate.
Yes. DSH plugin states job/settled may arrive after turn/end. In DSH plugin a finished turn does not mean owned jobs stopped, so late consumers must keep the subscription or read persisted history.
No. DSH plugin's readAt is non-consuming. DSH plugin lets any number of observers read the same ring at absolute byte offsets without interference; only the registry-held model cursor consumes.
No. DSH plugin's output event carries only the id and the new total. DSH plugin has observers schedule readAt from their own cursor, and the registry never pushes a payload.
Related Terms
- JobId
- JobId is a branded kind-plus-short-uuid identifier, where the kind precedes 16 lowercase hex characters from a UUID.— packages/jobs/jobs/src/types.ts
- JobStatus
- JobStatus is the job lifecycle state: running, stopping, completed, killed, or failed.— packages/jobs/jobs/src/types.ts
- JobChunk
- JobChunk is one ring block: absolute offset at, text, optional channel, and an optional gapBefore gap flag.— packages/jobs/jobs/src/types.ts
- JobView
- JobView is the single read-only projection every reader consumes, shared by model tools, browser rosters, and observation streams.— packages/jobs/jobs/src/types.ts
Sources
- DeepSeek Harness reference - Jobs runtime· deepseek-ai
- packages/jobs/jobs/src/types.ts· deepseek-ai