Module worker_context 

Automatic context rollover for subagent workers.

A worker is one brief followed by hundreds of assistant / tool_result rounds, and before this its context only ever grew: every round re-read the whole history at the cache-read price, and a worker that reached the window died on a terminal “prompt is too long”. The foreground rollover (continuation) does not fit workers: its successor keeps user requests (a worker has one), it seals evicted history into the session’s memory backend, and it needs a frontend to acknowledge the new head.

This is the worker’s host-only variant. The decision is the foreground’s policy engine unchanged (assess_context, ContextThresholds, target_tokens, successor_budget); only the successor and where evicted history goes differ:

• the successor keeps the brief (message 0) verbatim, later orchestrator instructions verbatim (within a share of the target), a host-written note, and the most recent rounds as a contiguous suffix cut at an assistant message that no tool call/result group straddles. Assistant messages are never edited, so signed thinking blocks travel verbatim;
• the evicted messages are written as a plain-text transcript into the worker’s archive directory (<handle>.window-<N>.md, 0600), the same place, permissions and retention as the finalize archive. The worker can grep/read it; nothing goes to the memory backend.

See docs/design/subagent-rollover.md.

Structs

RolloverPlan

A rollover ready to apply: write transcript to transcript_path, then replace the history with successor.

TranscriptRef

An earlier window’s transcript, as recorded in the note’s metadata.

WorkerContext

A worker runtime’s rollover wiring. Active only with both halves: config on, and a sink to preserve what is evicted. Without a sink nothing is evicted (nothing may be lost), so the worker behaves as before.

WorkerContextSettings

What config says about worker rollover. Set on every worker runtime by apply_subagent_runtime_policy; inert until a transcript sink is attached.

WorkerPolicy

A resolved worker policy for one model window.

WorkerRolloverReport

What one rollover did (observer, notice, status).

WorkerTranscriptSink

Where one worker’s evicted history goes. Attached per spawn: the archive directory and the worker’s handle id.

Functions

carried_marker

The host metadata to carry onto a message that replaces a rolled history (cold resume), so later rollovers keep numbering and listing earlier windows. None when history never rolled over.

hard_capacity_budget

At hard capacity the configured target may leave the successor little room to grow (a window whose reserves put hard capacity below the rollover band reaches it first; see WorkerPolicy::hard_capacity_has_room for one that cannot hold the target at all). Aim for two thirds of the history room the next round leaves, so the successor both fits and can grow.

plan_is_productive

Whether plan is worth applying: it must shrink the history estimate by more than [MIN_SHRINK_TOKENS] and keep every tool call paired as it was.

plan_rollover

Plan a rollover of messages into budget (message tokens, estimator units). transcript_path(window) names the file the evicted window is saved to. None when nothing can be evicted (no assistant round before the last one, or no valid cut); the caller treats that as no-shrink.

render_transcript

Plain text of every evicted message, in order, for grep and ranged read. Thinking is omitted (private reasoning; signed blocks cannot be re-sent out of their turn anyway); images and documents are named only.

roll_over

Apply one worker rollover: plan it, refuse one that cannot shrink the context or would start where the next round triggers another rollover (the pressure band below hard capacity, the hard-capacity line at it), save the evicted messages, and return the successor with its report. hard_capacity is Some(line) for a rollover at hard capacity, where line is the footprint at which the next round is at hard capacity (context_window - required_next_round). Ok(None) = no-shrink (the caller defers like the foreground’s unproductive rollover). An error writing the transcript means no rollover: nothing is evicted that was not saved.

transcript_path

<dir>/<stem>.window-<window>.md.

unpaired_tool_ids

Tool ids with a call but no result after it, or a result with no call before it. A valid history has none; a successor must add none.

window_state

The current window (1 before any rollover) and every recorded earlier transcript, from the host metadata on messages: the rollover note, or the single message of a cold resume (which carries it on message 0).

Type Aliases

RolloverObserver

Called after every successful worker rollover (the spawn path updates the worker’s state and its subagent panel line).