zidane

Wire-level cutoff for SessionContentBlock's compact-summary markers.

Elision is MONOTONE across every marker in the session: a turn whose id appears in ANY marker's replacesTurnIds never reaches the wire again — the summary that absorbed it stands in for it permanently. (Honoring only the newest marker would resurrect the older marker's replaced turns whenever a re-compaction failed to subsume it, e.g. after a PTL head-drop. That showed up as a session re-compacting an unchanged 866k-token wire on every turn.)

Per marker:

1. A marker turn never passes through verbatim (providers don't know the compact-summary block type).
2. An ACTIVE marker — one not itself replaced by a newer marker — renders as a synthesized plain user-text turn carrying its summary, positioned at the slot of its first replaced turn so the summary appears CHRONOLOGICALLY where the content it summarizes used to live:
   • older unreplaced turns (PTL head-drops) come first
   • then the synthesized summary
   • then later unreplaced turns (preserved tail + new prompts) A marker with no surviving replaced slot (empty or dangling replacesTurnIds) renders at its own chronological position.
3. A SUBSUMED marker (its id is in a newer marker's replaced set — i.e. its summary text fed the newer summary) contributes only elision: its replaced turns stay gone, its text does not render.
4. Every other turn passes through by reference, including turns no marker replaced (PTL head-drops stay visible verbatim until a later compaction absorbs them — the runner compacts the WIRE view, so they are always at the head of the next scope).

If no marker exists, the input array is returned unchanged.

Note on role-alternation: when the marker is immediately followed by a new user turn (the common case — user submits a prompt right after compacting), the wire output ends in […, synthetic_user, new_user]. Anthropic folds adjacent same-role messages server-side; other providers tolerate them via their own normalization passes. The harness does NOT fold them here — keeping them separate preserves the per-turn turnId tags that the TUI's select-turn mode relies on.

Pure: a fresh array is returned only when a marker is found. Input turns are never mutated. New SessionTurns allocated: the synthetic markers, plus a copy of every preserved assistant turn older than the newest marker whose replayable thinking was stripped (see withoutReplayedThinking). The output is WIRE-shaped, not display-shaped: hosts rendering a transcript should read the session turns, not this view.

Render the byte-stable <persisted-output> stub the model sees in place of the original tool_result.

Format choices:

• XML wrapper because models reliably parse it as structural.
• Byte count + path in attributes so the model can decide whether to read_file the persisted blob without scanning the preview.
• Preview always shows the head — how shell cuts its own output is irrelevant here because the model has the full path if it needs the tail.
• No timestamps, no random UUIDs inside the stub: every byte must be reproducible from the inputs, otherwise re-emission on subsequent turns would bust the prompt cache.

Exported for tests (asserting the byte-stable contract) and for SDK consumers wiring their own persistence middleware against the same surface.

Build the synthetic turns to append after a compact-summary marker.

Returns a PostCompactAttachments envelope; the caller is responsible for session.appendTurns([summaryTurn, ...result.turns]). The two synthetic turns are always emitted together (or both omitted when nothing was restored) so the tool_use ↔ tool_result adjacency invariant holds regardless of caller code path.

Failure isolation: a single file's read failure never blocks the rest of restoration — that file is skipped silently and processing continues. The returned restoredFiles count reflects what actually landed in the synthesized turns.

Remove every persisted blob belonging to a session. Called by the chat layer from its session-delete path so closing a session frees the disk footprint alongside the SQLite row.

Idempotent — missing directory (session never persisted anything) is a no-op, not an error. Wraps the rm -rf so a permissions blip on one blob doesn't propagate to the caller; the chat layer can't usefully recover from "couldn't unlink a result file" mid-delete.

Paths whose earlier reads were NEWLY made stale by this batch's successful mutations — i.e. the prior transcript holds a read_file of the path that is more recent than the path's last successful mutation. Reads older than that mutation were already noticed when it landed, so repeated edits to the same file yield exactly one notice per read→edit transition, not one per edit.

Pure; mirrors applyStaleReadElision's detection exactly (same tool names, same success markers) so the two policies never drift on WHAT counts as stale — only on how the staleness is represented.

Map ONE command-output block to its LIVE transcript event — the in-memory mirror of commandBlocksToContent's persisted shape (whose replay side lives in eventsFromTurns). One definition shared by the command emit flush and the ctx.appendNote host impl so live rendering can never drift from reloaded rendering — the exact drift that shipped custom blocks rendering only after a reload.

Precedence matches the persisted side: custom > detail > markdown.

Summarizes older turns of a conversation with one provider call.

Retries with a shortened head on prompt_too_long and retries transient provider errors a limited number of times. Does not modify opts.turns.

Throws CompactInvalidInputError when the inputs cannot be compacted, CompactPromptTooLongError when the retry budget runs out, and rethrows aborts from opts.signal unchanged.

Human-readable terminal sink. Renders each record as <ISO timestamp> <LEVEL> <message> <attrs as kv pairs>.

Honors process.stderr by default so log lines don't interleave with the agent's stdout-bound output (chat responses, JSON results).

Inspect a session's trailing turn to classify whether the run was interrupted mid-tool-call. Pure / synchronous — does not modify the input.

Pair with filterUnresolvedToolUses on the resume path: filter first so the result reflects the post-cleanup state (a turn whose orphans were stripped reads as 'completed', not 'interrupted').

Effective context window — what the next user turn can actually pack before the provider reserves space for the assistant's reply. Equals rawWindow - OUTPUT_RESERVE_TOKENS, clamped to >= 1 so a tiny (or absurd) window doesn't yield zero / negative thresholds.

Pass null through unchanged so callers can pipe a raw window lookup directly without an intermediate check.

Guarantee a message list ends with a role: 'user' message, appending a synthetic directive when it doesn't.

Why: Anthropic's API (and several OpenAI-compat reasoning models — opus 4.7, the o-series translation layers on Bedrock/Vertex) rejects requests whose final message is role: 'assistant' with "This model does not support assistant message prefill. The conversation must end with a user message."

Triggers in zidane:

• Compaction over a session whose last turn is the agent's response (the common case — autocompact fires right after agent.run()).
• Schema enforcement after an assistant text turn (no tool_use, so ensureToolResultPairing doesn't synthesize a user tail).
• context:transform hooks that strip the trailing user turn.

The pair-repair pass ensureToolResultPairing already covers the orphan-tool_use case via mode 2; this helper closes the plain-text assistant-tail case. They compose: run pair-repair first, then this pass, so an assistant turn with orphan tool_uses gets its synthetic tool_result user turn AND this pass is a no-op (the synthetic turn is already user-role).

Empty input passes through unchanged — the caller's "nothing to send" guard is responsible for that case; we don't materialize a conversation out of an empty list.

Idempotent: returns the input reference unchanged when the list is already user-terminated (or empty).

Defensive repair pass that rewrites a message list so it satisfies the wire-level tool_use ↔ tool_result adjacency contract every modern provider enforces.

Anthropic 400s on orphans with 'tool_use' ids were found without 'tool_result' blocks immediately after (and its inverse, tool_result must be preceded by a tool_call with the same toolCallId). OpenAI's Chat Completions API rejects most mismatches with a 400 too.

Six repair modes — modeled after Anthropic's Claude Code defenses:

Repair, not drop. Dropping orphan blocks would (a) silently rewrite history the model had reasoned over and (b) cascade — dropping an assistant tool_call would orphan its tool_result, which would then get dropped too, removing any trace of "what the model tried to do" from the transcript. This pass preserves the model's tool_use shape and patches the dangling result with an is_error placeholder so the model sees "I tried X, the result was lost" and can retry intelligently.

Adjacency contract: tool_result blocks must live in the user message IMMEDIATELY following the assistant message that emitted the matching tool_use. The pass enforces strict adjacency — a tool_result two messages downstream of its tool_call is still an orphan.

Idempotent: returns the input reference unchanged when no repairs were necessary. Re-running on already-repaired output is a no-op.

Pure: does not mutate input messages or their content arrays — every repair allocates a fresh array / object.

Approximate token count for text: text.length (UTF-16 code units, not bytes) divided by BYTES_PER_TOKEN, rounded up. Mirrors Claude Code's BYTES_PER_TOKEN = 4 heuristic — acceptable for budget arithmetic (sizing summarization scopes, enforcing per-file caps in restoration).

A rough estimate. Use a real tokenizer when exact counts matter (cost reporting, hard caps); this is for budget gates where being off by some percent is fine.

Pure. Exported so callers (TUI, SDK consumers) can do their own pre-budgeting against the same heuristic the harness uses internally.

Drop ASSISTANT turns whose every tool_call block is unresolved (no matching tool_result block anywhere later in the transcript). Tool_call blocks with at least one matching tool_result are kept — modes 1/3 of ensureToolResultPairing handle the partial-pair case at wire-send time.

Use case: session resume. A turn that emitted three tool_use blocks but never persisted the matching tool_result turn (process death, crash, kill -9) leaves the transcript with an orphan that Anthropic rejects on the FIRST API call after reload. Dropping the whole assistant turn — not just the orphan blocks — preserves text-only turns that legitimately carry reasoning the model wants to see again.

Does NOT mint fresh ids: re-id'ing on every resume would cause exponential transcript growth across repeated resumes of an interrupted session.

Pure: returns the input reference unchanged when no turn was dropped.

Render a one-line token summary suitable for spawn-end markers, child tool-result text, and any other per-run "what did this cost?" surface.

in 52413 (cache 50000) / 4075 out

The in total includes cached reads and cache-creation tokens (see effectiveInputTokens); the (cache N) parenthetical breaks out the cached portion so the user can tell at a glance how much was reused vs new. The parenthetical is omitted when its value is zero, so non-caching providers and brand-new runs read simply as in N / M out.

Output-side caching is not a concept any current provider exposes — Anthropic's cacheRead / cacheCreation are both input-billed. If a future provider ships an output cache, extend TokenUsageLike with output-cache fields and add a parallel (cache N) slot on the out side here; today the right side is always plain ${N} out.

True when an HTTP transport's auth headers already include an explicit Authorization. Used by the bootstrap escape-hatch: a user who provided their own bearer token shouldn't be auto-promoted to OAuth on a 401.

Case-insensitive — Node normalizes outgoing headers to lowercase but users hand-write Authorization in configs.

Run the full interactive OAuth flow for config. Only supports sse and streamable-http transports — stdio MCP servers don't speak OAuth.

Throws on:

• Wrong transport.
• Abort signal.
• Browser-side error (user denied, server rejected, etc.).
• Code exchange failure.
• Post-exchange connect failure.

Always closes the loopback callback server before returning, success or failure.

Decide-and-persist for a single tool result. Pure decision + filesystem side-effect; returns the new wire-level output string when substitution happened, otherwise tells the caller to leave the result alone.

Atomicity: the local fallback writes through <path>.tmp + rename so a concurrent read (or a crash mid-write) never sees a half-written blob. A routed write (input.writeBlob, e.g. a sandbox writeFile) is not atomic; see the field doc for why that's safe here.

Text-only ToolResultContent[] results are flattened and persisted as text. Mixed structured content still bypasses persistence because the inline image/document bytes are the point of the call and a mixed result is not representable as a single .txt file without dropping media.

The provider for config: carries its pre-registered client (config.oauth) and scope when it has one. Every host builds its providers through this, so a static client is honored by bootstrap, token refresh, Test and Sign in alike.

The secret comes from the config (${VAR} expanded) or, failing that, from the credential store, where a host UI saved it.

Fold older artifact layouts into the session-first one (<userDir>/sessions/<sessionId>/<kind>/).

Two source layouts are folded in:

1. pre-6.x <userDir>/<sessionId>/{tasks,mcp-warnings}/ — one top-level entry per session, so a few hundred sessions bury credentials.json under noise. This is what is actually on users' disks.
2. kind-first <userDir>/{tasks,mcp-warnings}/<sessionId>/ — a shape that only ever existed in dev builds between the two designs. Handled so a contributor who ran one doesn't end up with artifacts in three places.

tool-results/<sessionId>/ is deliberately NOT a source: those blobs are referenced by absolute path from inside session transcripts and re-read by the model, so relocating them without rewriting every transcript would strand them. See resolvePersistDir and resolveLegacyPersistDir.

Sync + best-effort by design. It runs on the chat bootstrap path, so it must not make startup fail on a read-only or half-permissioned storage dir; every filesystem call is individually guarded and failures are counted, not thrown. renameSync within one directory tree can't hit EXDEV, so the moves are atomic metadata updates, not copies.

Idempotent and cheap to re-run: one readdirSync of the user dir, plus one of each kind-first root that still exists. A migrated tree has no sources left to match, so there's no "migration done" marker to keep in sync — the filesystem shape IS the marker.

Conflicts are left alone: if the destination already exists, the source stays put and counts as failed rather than having its contents merged or clobbered. Nothing is ever deleted except an emptied source shell (rmdirSync, which refuses non-empty dirs), so an unexpected layout survives for the operator to inspect.

Note that a pending conflict is re-counted on EVERY sweep: nothing but session-delete can resolve it (both copies are live data), so each boot legitimately re-observes it and reports failed: 1. The effects stay idempotent — nothing moves, nothing is removed — only the counter repeats.

Known mixed-version race, accepted: a still-running pre-migration process holds its tasksDir at the old path and this sweep renames it away. Open write streams keep working (the inode moves with the rename), but log paths already quoted in that session's turns go stale, and the old process's defensive mkdir may recreate the source dir — which the next boot re-migrates. Task logs are ephemeral debug output, so a liveness heuristic isn't worth the complexity.

Normalize AgentOptions.provider into a non-empty provider list.

In multi-provider setups every provider needs a non-blank, unique name — model entries reference providers by Provider.name, so a blank or duplicate name would make the reference ambiguous (and surface as a baffling duplicate provider name "" otherwise). A single provider has no such constraint: its name plays no role in target resolution. Throws at agent construction rather than at run time.

Canonicalize a shell command so semantically-identical invocations collapse to one streak key:

• strip a leading cd <path> && (or cd <path>;) prefix — the model often re-prefixes the same command with a cd into the project root.
• strip a trailing verify-tail of the shape & sleep N ; <anything> or ; sleep N && <anything> that the model appends to poll a just-started process (… & sleep 2 ; curl localhost).
• collapse runs of whitespace to single spaces and trim.

Conservative on purpose: it does NOT reorder flags or parse the command — it only removes the two wrappers we actually saw inflate distinct-looking retries of the same core command, plus whitespace noise.

Single source of truth for whether a signature-bearing reasoning block (thinking / redacted_thinking) may be forwarded to a provider. The wire builders (toAnthropic, the OpenAI and Google message shapers) and the host-facing sanitizeHistoryForProvider apply this same policy — keeping them one function means the sanitizer can never drift from what the wire actually sends.

Rules, each driven by an API constraint hit in production:

• target anthropic:

  • redacted_thinking → keep (native Anthropic block; must be echoed).
  • thinking tagged openai, google or google-vertex → drop (OpenAI encrypted_content and Gemini thought signatures are not valid Anthropic HMACs; 400s).
  • unsigned thinking → drop (ThinkingBlockParam requires a signature; unsigned blocks come from non-signing producers).
  • signed but UNTAGGED thinking (pre-tagging sessions) → keep: it is most plausibly legacy Anthropic output, and the signature-400 recovery converges if it is not.

• target openai or a Gemini-wire scope (google, google-vertex, a googleCompatible route's):

  • redacted_thinking → drop (Anthropic-only block type).
  • thinking tagged anthropic → drop (an Anthropic HMAC is valid nowhere else).
  • thinking signed by any other producer, or signed but UNTAGGED → strip-signature: there is no signature-error recovery on these paths, so forwarding a possibly-foreign signature risks an unrecoverable 400. The reasoning text survives; only the opaque signature is withheld. Gemini's are kept only for the route that issued them.

Re-mint tool-call ids that collide with ids already present in the transcript (or with an earlier sibling in the same turn), BEFORE the turn is persisted and its tools dispatched.

Why this exists: some providers/serving stacks emit non-globally-unique tool_use ids (per-turn counters like call_0, retry-replay duplicates, Kimi-K2.6 on Fireworks). The wire-time pairing pass (ensureToolResultPairing) can only STRIP such duplicates — which erases the model's tool calls and results from the wire view, stalls progress, and re-accumulates repairs quadratically because the persisted session keeps the corrupted ids. Re-minting at persist time keeps the pairing intact instead: the call, its execution, and its tool_result all carry the fresh id, so the pairing pass has nothing to strip on any later turn.

Fresh ids are ${oldId}_r{n} with n bumped until unique — deterministic shape, Anthropic-wire-safe charset (given a safe input id), and visibly traceable back to the original.

Alignment contract: toolCalls and the tool_call blocks inside content are two views of the same emission and MUST be in the same order (true for every provider — both are built from one source array). Occurrences are matched positionally per old id so intra-turn duplicates map to distinct fresh ids on both views.

Pure: returns the input references unchanged when no id collides.

Locate the shipped docs/ directory (docs/EXTENSIONS.md + siblings).

The docs ship via package.json files, so an installed consumer has <root>/node_modules/zidane/docs and the repo itself has <repo>/docs. Returns the first existing candidate, or null (the skill then falls back to the literal node_modules/zidane/docs hint, which the model's file tools can still attempt from cwd).

Path of the pre-session-first blob directory (<userDir>/tool-results/<sessionId>/), or undefined when the id doesn't match a shape zidane ever minted.

These blobs are deliberately NOT migrated — a persisted stub carries the blob's absolute path inside the session transcript and the model re-reads it with read_file, so moving the bytes without rewriting every transcript strands them (see resolvePersistDir). They keep resolving where they are; this resolver exists so session delete still reclaims them. Same positive id match, same reason.

Path of the pre-6.x per-session artifact shell (<userDir>/<sessionId>/), or undefined when the id doesn't match a shape zidane ever minted.

Session delete sweeps this alongside the session subtree: when migrateSessionArtifactDirs hits its conflict branch (the target already existed), the shell is deliberately left in place and counted as failed — and nothing else ever removes it, so deleting the session is the one moment both copies are provably garbage. The positive id match is what keeps an exotic host-minted id from resolving to a root like tasks/.

Resolve the per-session MCP diagnostic directory under <userDir>/sessions/<sessionId>/mcp-warnings/.

Warning logs are cache/session artifacts like background task logs: useful for debugging, safe to delete, and cleaned up with the session.

Resolve a run's model selection into an ordered, de-duplicated fallback chain of provider+model targets. targets[0] is the primary.

Expansion rules:

• undefined → each provider's meta.defaultModel, in provider order.
• string → that model id on every provider, in provider order.
• array → entries in order; a { provider, model } entry resolves to that one provider (throws on unknown names), while bare strings and provider-less objects fan out across all providers.

Resolve the per-session persistence directory under <userDir>/sessions/<sessionId>/tool-results/.

The chat layer calls this at session activation and forwards the result via behavior.persistDir. Exposed as a public helper so SDK consumers pick the same layout — single source of truth for "where do blobs live".

NOTE for anyone tempted to migrate old blobs into this path: don't. A persisted stub embeds the blob's ABSOLUTE path in the session transcript (see the path="…" attribute built in buildPersistedStub) and the MODEL re-reads it by calling read_file on that path. Moving the bytes without rewriting every transcript strands them mid-conversation. Blobs written under the old <userDir>/tool-results/<sessionId>/ therefore stay put and keep resolving forever; only new writes land here, and session delete sweeps both (see resolveLegacyPersistDir).

Resolve the root of a session's artifact subtree (<userDir>/sessions/<sessionId>/).

This is what session delete removes: one recursive remove reclaims every artifact kind at once, so adding a kind never touches the delete path.

Resolve the per-session background-tasks directory under <userDir>/sessions/<sessionId>/tasks/.

The chat layer calls this at session activation and forwards the result via behavior.tasksDir. Created on first write; cleanup is the session-delete path's job — and since it lives inside the session's own subtree, that cleanup is the same recursive remove that takes everything else.

Host-facing history sanitizer — applies reasoningWireAction to a turn set BEFORE it is handed to an agent targeting target. The in-loop wire builders already enforce the same policy per call, so this is for hosts that seed history from an external durable store (or hydrate pre-provenance-tagging sessions) and want the poison removed from their source of truth in one call instead of re-deriving block semantics.

Returns new turn objects only where something changed (unchanged turns pass through by reference). A turn whose content empties keeps the same neutral marker the wire repair uses, so role boundaries stay intact.

Convert a raw read-state map into a deduped, path-ranked list ready for restoration. Multiple entries for the same path (different (offset, limit, maxBytes) slices) collapse to one — keeping the most recent mtimeMs.

Keys are the absolute paths readStateKey writes, and paths come back absolute, so every execution context reads them the same way. Entries outside cwd are dropped: they belong to another workspace.

Pure. Most callers want selectFilesFromSession, which wraps getReadState(session) + this function in one call so the host doesn't have to reach into the tools layer.

Session-aware convenience: extract recently-read files directly from a Session via its per-session read-state map.

Hosts (TUI / SDK consumers) typically have a Session and a cwd (the active agent's handle.cwd) on hand — this wrapper saves them from reaching into src/tools/read-state.ts directly. Returns an empty list when no read state has been recorded yet (fresh session, or behavior.dedupReads === false).

Equivalent to:

const state = getReadState(session)
return state ? selectFilesFromReadState(state, cwd) : []

Pick the top maxFiles from files (descending by mtimeMs), dropping any whose path appears in excludePaths.

Stable for equal mtimes — files with the same timestamp retain their input order. Pure.

Decide whether auto-compaction should fire for the latest turn.

Order of checks is deliberate: cheapest / most common skips first (disabled is one boolean read; unknown-window is the predictable miss for custom models), invariant violations next, then the actual threshold math. already-compacting runs last so the diagnostic surfaces correctly when the predicate is called inside an existing compaction window.

Partition turns into (toSummarize, preserved) according to scope.

Throws CompactInvalidInputError on degenerate inputs so the caller doesn't pay for a doomed provider call:

• empty turns
• scope: 'tail' with keepTurns >= turns.length (nothing to summarize)
• scope: { from | up_to } with an anchor id that isn't in turns
• the resulting toSummarize slice contains no text-bearing content (only system turns or empty content)

Pure. Returns references to the original SessionTurn objects — the caller can compare by identity (=== Object.is) to confirm.

Start a one-shot OAuth callback server. The returned handle's redirectUri should be passed to the authorization server as the redirect_uri query parameter; promise resolves once the user finishes the browser flow.

Always await handle.close() in a finally block — even on success, the server stays open until told to shut down (so it can serve the "you can close this tab" page).

Replace every attachment block in turns with a short text marker ([image], [audio], [video] or [document]).

Covers two shapes:

• Top-level image, audio, video and document content blocks.
• The same block types inside tool_result.output array form (multimodal tool results — e.g. an MCP browser screenshot).

Unconditional by design: even on vision-capable models, the summary call doesn't benefit from raw image bytes (the model can't refer to them after the summary lands), and stripping uniformly avoids prompt_too_long on image-heavy sessions.

Returns a fresh array; input turns / blocks are never mutated.

Build a synthetic SessionTurn carrying a single compact-summary block, ready to append to a session.

The turn's role is 'user' so it sits at a conversational boundary the way the model expects. The caller is responsible for session.appendTurns([turn]). The id defaults to crypto.randomUUID() (override via input.id for durable-execution replay stability).

Typical use after running compactConversation:

const result = await compactConversation({ provider, turns })
const turn = summaryToTurn({
  summary: result.summary,
  replacesTurnIds: result.summarizedTurnIds,
  model: result.model,
  usage: result.usage,
})
await session.appendTurns([turn])

Shrink turns for a prompt_too_long retry and return a fresh array.

Drops whole rounds from the head until the remaining slice is at most HALF the byte size of the input (always dropping at least one round). Halving is the load-bearing property: the retry budget is small (3 by default), so shrinkage must be geometric, not linear. Dropping a single round per retry would never converge on a very long session where each round is a rounding error against the overflow, and compaction would fail with prompt_too_long after 3 retries even though a smaller prompt would have succeeded.

A round is a contiguous [user, assistant?, tool_results?] group.

Adjacency-safe: only whole rounds are dropped, so the result still respects every provider's tool_use ↔ tool_result adjacency rule.

Returns turns unchanged when only one round (or less) remains — the caller is expected to interpret that as "cannot shrink further" and give up the retry loop.

UTF-8 byte length, matching Buffer.byteLength(text, 'utf-8') for well-formed strings but without pulling node:buffer for a one-liner. A high+low surrogate pair counts as a single 4-byte sequence (not 2 × 3-byte). A lone surrogate is not handled like Buffer does. Cheap to call in hot loops.

Pure. Identical bytes for identical input across every JS runtime.

Inject the zidane-extension skill into an already-merged SkillsConfig.

Call this on the FINAL merged skills object (after folding extension / preset skills): composePresets is last-wins on catalog, so injecting earlier would be silently dropped whenever an extension also contributes skills.

Adds the skill to the catalog and, when an enabled allowlist is in force, force-includes the name so the allowlist filter can't hide it (mirrors how extension-contributed skill names are force-included). When skills are fully disabled (enabled === false), the edit session still gets just this skill.

Normalize a JSON Schema (e.g. from zod v4's z.toJSONSchema()) for use as a ToolSpec.inputSchema.

Strips the $schema key that some providers reject.

Thrown by the loop when consecutive resumeOnMaxTokens resumes keep producing output-cap (finishReason: 'length') turns with no visible text and no tool calls — the degenerate reasoning spin: on providers that don't accept prior reasoning back, each resume restarts reasoning from scratch on a synthetic "Please continue.", burns the full output budget, and makes zero progress. Unlike a text-producing truncation (which keeps the generous internal resume bound and, on exhaustion, still ends the run cleanly), this loop does not assemble an answer, so it fails fast with a real error instead of silently "completing".

The run is finalized as 'error' and the error re-throws so a caller's try/catch can branch on err instanceof AgentLengthResumeExhaustedError without string-sniffing.

Raised when the caller's inputs make compaction meaningless before any API call is attempted. Common cases:

• empty turns
• keepTurns >= turns.length (no older content to summarize)
• 'from' / 'up_to' anchor id not found in turns
• the resolved toSummarize slice has no text-bearing content

Synchronous — thrown from compactConversation() before the provider call so the caller can recover without a network round-trip.

Hysteresis floor that chat hosts pass as minGrowthFraction to shouldAutoCompact, which itself applies no floor when the input is omitted. After a successful compaction lands, the next compaction is suppressed until input usage grows by at least this fraction of the effective context window beyond the post-compact baseline.

0.1 = 10% of the window. Picked so the immediate post-compact bounce (summary turn + restored attachments + re-emitted system prefix) never re-fires the trigger by itself, but a meaningful chunk of new work (one or two large tool reads) does. Tune via the predicate's minGrowthFraction input if a host needs different ergonomics.

Default per-value size budget: 64 KiB of JSON.

Deliberately far below any backend's hard ceiling (journal-entry limits run to tens of MiB) because this is a design guard, not a protocol limit. Durable tool state is for flags, ids, counters, and cursors; a value that doesn't fit in 64 KiB is a payload, and payloads belong in the tool result or in storage the tool owns. Raise it on the store if you disagree — but know that everything here is rewritten on every commit.

Reserved output budget subtracted from the raw context window when computing the effective ceiling for compaction / warning thresholds.

Aligned with Claude Code's COMPACT_MAX_OUTPUT_TOKENS = 20_000 — covers p99.99 of summary + response output. A turn that consumed N input tokens leaves effectiveWindow - N headroom for the next prompt's response; once headroom shrinks below the threshold, auto-compaction fires.

Byte-stable prefix every buildPersistedStub output starts with. Exported so wire-level passes (tail compaction) can recognize a persisted stub and preserve its path attribute rather than replacing the stub with their own — losing the pointer to the on-disk blob.

Bound to the literal opening of the XML tag; changing the stub format requires updating this constant in lockstep (and shipping a migration for in-flight sessions).

Bytes of head content included in the inline preview block. 2 KiB matches Claude Code's PREVIEW_SIZE_BYTES — enough for the model to identify the content class (error output / structured data / log shape) and decide whether to call read_file on the persisted path for the full payload.

Tail-priority preview (matching shell's truncation strategy) was considered but rejected: most "what is this?" decisions get made from the head, and the path is in the stub for the rare case where the tail matters.

Canonical tool_result text emitted when a single tool call is cancelled mid-flight via agent.cancelTool(callId) (typically the TUI's "cancel this tool" affordance). Distinguished from INTERRUPT_MESSAGE_FOR_TOOL_USE (run-wide user abort) and TOOL_USE_SKIPPED_MESSAGE (steered) so the model — and downstream consumers — can tell the three apart by string match.

Always paired with isError: true on the wire so the model treats the call as failed rather than as a successful response. The remaining tool calls in the batch continue running, in contrast with a full-run abort.

Loop-native auto-compaction config (AgentBehavior.autoCompact).

Distinct from compactStrategy (wire-only tail elision of tool_result text). Auto-compaction is the heavy lever: when the last turn's input usage crosses AutoCompactConfig.threshold of the effective context window, the loop runs a real LLM summary (compactConversation) over the older turns, appends a compact-summary marker + restoration turns to the session mid-run, and the next turn's wire view is the summary plus the preserved tail. It mutates the session (durable summary turn), whereas compactStrategy never touches session.turns.

The two compose: compactStrategy: 'tail' trims tool-output bytes every turn; autoCompact summarizes the narrative when the window fills.

Inputs to shouldAutoCompact.

Kept as a struct so the call site reads as the predicate it is, and so future inputs (per-session opt-out, recent-compaction cooldown, …) land without re-threading every consumer.

Identity a nested spawn lifecycle event (child:spawn:*) adds to the spawned agent's record.

child:spawn:* events describe a spawn fired BY a subagent (the spawned agent sits at depth ≥ 2). Their payload is the spawned agent's own record — id / depth / task / callId are the grandchild's, exactly as its spawner's spawn:* saw them — so one handler can serve both families. Unlike the other child:* events there is deliberately NO childId: on those, childId + depth name the agent that originated the event, and here depth already belongs to the spawned agent. The spawner is named by parentChildId instead (its depth is depth - 1).

Geometric thinking-budget taper: full budget through afterTurn, then multiplied by factor each subsequent turn, clamped to floor.

Emits several distinct budgets on the way down, and on Anthropic each distinct thinking.budget_tokens value is a full prompt-cache re-bill (the budget is part of the cache key — measured, see AgentBehavior.thinkingDecay). Prefer StepThinkingDecay when caching is on.

Single-step thinking-budget taper: full budget through afterTurn, then floor for the remainder of the run.

Exactly ONE budget change per run, so exactly one prompt-cache invalidation — the cache-aware schedule. Distinguished from GeometricThinkingDecay by the absence of factor.

Input shape for summaryToTurn. Designed to align with the fields of CompactResult so a caller can spread the runner's output with a single replacesTurnIds rename — no field-by-field unpacking required.

Primitive shape (no CompactResult import) keeps this module free of dependencies on the runner — compact.ts imports from here, not the other way around.

Pluggable client-side context compactor — see AgentBehavior.compactStrategy. The loop invokes this in place of the built-in tail elision when compactStrategy is a function.

Contract:

• Operates on the wire-level message list — the post-alias / post- sanitize / post-context:transform view the provider will see. The framework treats the returned array as the new wire payload; ctx.session / ctx.turns are never modified.
• Must preserve tool_use ↔ tool_result adjacency. Stranding a tool_use without its matching tool_result (or vice versa) will trip the loop's pair-repair pass and either repair the violation or throw (strictToolPairing).
• The trailing user message must remain — providers reject assistant-tail wire payloads. If unsure, leave the last user turn intact and operate on the prefix only.
• May return the input verbatim (e.g. when the total stays under the host's threshold).
• Sync or async. The loop awaits the result, so a long-running LLM summarizer will block the next turn — keep latency in mind.

ctx.threshold and ctx.keepTurns are forwarded from behavior.compactThreshold / behavior.compactKeepTurns so hosts can reuse the same knobs the built-in tail mode uses. ctx.totalBytes is the pre-compaction total — the same number the tail mode uses to gate its threshold check, exposed so the function can short-circuit on under-threshold inputs without recomputing.

What to summarize and what to preserve verbatim.

• 'full' — summarize everything, no preserved tail.
• 'tail' — summarize everything before the last keepTurns turns.
• { kind: 'from', turnId } — summarize from the anchor turn onward.
• { kind: 'up_to', turnId } — summarize up to (and including) the anchor.

Per-tool argument hasher used by AgentBehavior.dedupTools.

Returning a non-empty string activates dedup with that string as the cache key. Returning undefined (or '' / non-string) opts THIS call out — the tool runs normally and no state is recorded. See dedupTools for the full contract.

Per-tool dedup configuration. Two equivalent forms:

• Hasher only: a bare function. The framework runs in 'replay' mode — identical re-calls replay the prior result.
• Config object: explicit hasher plus a mode:
  • 'replay' (default) — replay the cached result on identical re- calls. Cheap loop, but doesn't BREAK the loop — the model keeps seeing the same tool_result and keeps trying.
  • 'block-after' — replay identical calls until the total count reaches threshold, then refuse with Blocked: <reason> via tool:gate. Designed to break tight loops where the model fixates on a single failing call. The block lands on the Nth identical call (i.e. once the total count reaches threshold); the cap is sticky — every subsequent identical call also blocks until a different input resets the counter.

reason is the model-visible refusal text. The framework formats the final tool_result as Blocked: <reason> (see tool:gate docs). Strings are used verbatim; the callback form receives the input and the (now-blocking) repeat count so it can produce per-invocation messaging like Blocked: 4 identical "shell" calls — try a different approach. Default reason is generic but actionable.

Classification of a single repair the pairing pass performed. Surfaced via EnsureToolResultPairingOptions.onRepair so consumers can wire telemetry, debug logs, or strict-mode rejection without re-implementing the walk.

Each entry corresponds to one of the corruption modes documented on ensureToolResultPairing.

Function that opens a span. Caller-provided so we stay tracer-agnostic.

parentContext carries opaque trace metadata propagated from another agent (typically a W3C { traceparent, tracestate } carrier received on agent:start.tracingContext after a parent agent's tracer injected it on spawn:before). Implementations that integrate with OTel should extract the carrier into a Context and use it as the parent when opening the span; implementations that don't care about cross-agent linkage can ignore the third argument entirely.

Classification of a session's tail state for resume purposes.

• 'clean' — the trailing turn is a user message (the model would respond next), or the transcript is empty. Safe to resume by appending a fresh user prompt.
• 'interrupted' — the trailing turn is an assistant message that has at least one tool_call block with no matching tool_result anywhere later. The run was almost certainly killed between persisting the assistant turn and persisting its tool-results turn. Hosts that want Claude-Code-style auto-resume can detect this and inject a "Continue from where you left off." user message before the next run.
• 'completed' — the trailing turn is an assistant message with no orphan tool_calls. The model considers itself done. Hosts that want to resume must supply a new prompt; auto-continuation here would be a non-sequitur.