A local-first multi-agent app development platform, built on PenguinHarness
/**
* context_engine — orchestrates the ReAct loop.
*
* context_engine only handles OmniMessage, orchestrating the flow of events between the
* Human, LLM, and Environment interfaces, and writes every observable action to Trace.
* The initial version keeps a linear message history.
*
* Human is the SDK's input/output boundary: there is no "Human implementation/interface".
* Input is the Prompt list passed to `run`, plus the abort signal `signal` and the
* per-tool approval callback `approve` in `RunOptions`; output is the OmniMessage stream
* produced by `run`.
*
* Docs: packages/docs/content/agent-loop.{zh,en}.md (site path /docs/agent-loop) documents
* the turn lifecycle, carry-over, reconnect and compaction implemented here.
*
* Approval is an **in-turn interaction** and tool calls are **async/incremental** (see
* comment #24):
* - A single `run` call automatically runs the entire ReAct loop (no more resuming in batches);
* - Each tool_call is emitted as soon as its stream completes → `await approve` → if
* allowed, it runs via Environment;
* - Execution **does not block** continued consumption of the LLM stream or approval of
* the next tool (executions can overlap), but approvals still happen one at a time;
* - partial/complete `tool_call_output` is yielded in **completion order**;
* - once all tool outputs for the turn are ready, they become the next turn's LLM input;
* the Task ends once a turn produces no more tool_call.
*
* Implementation note: an internal queue merges "the LLM event stream + N concurrent tool
* output streams" into a single yield sequence. GenerativeModel is a stateful object
* (AgentHub maintains the history); each turn the engine only hands it the "new" messages:
* the user Prompt on the first turn, and the previous turn's tool_call_output afterward.
*/
import {
abortEvent,
approvalDecision,
assistantText,
compactionBegin,
compactionEnd,
addTokenCounts,
emptyTokenCounts,
isCompleteModelMessage,
isModelMessage,
isSessionMeta,
partialText,
requestBegin,
requestEnd,
subagentEvent,
toolCallOutput,
userText,
} from "../omnimessage/index.js";
import {
buildContextSummaryText,
buildTurnAbortedBlock,
extractSummary,
buildTurnRetriedBlock,
transcribeText,
transcribeThinking,
transcribeToolCall,
transcribeToolCallOutput,
transcribeUserInput,
unwrapSyntheticBlock,
userSteeringText,
} from "../omnimessage/markers/index.js";
import type {
ErrorCode,
ApprovalDecision,
CompactionMode,
CompactionReason,
OmniMessage,
StopReason,
TextPayload,
TextSender,
ThinkingPayload,
TokenCounts,
TokenUsagePayload,
ToolCallOutputPayload,
ToolCallPayload,
} from "../omnimessage/index.js";
import type {
RunCutoff,
ApproveFn,
PreToolUseFn,
PreToolUseOutcome,
UserPromptFn,
UserPromptOutcome,
EnvironmentInterface,
LLMInterface,
LLMOutcome,
ThinkingLevelName,
} from "../interfaces/index.js";
import { MergeQueue, pumpOpener } from "../internal/merge-queue.js";
/** Trace sink: `write` a complete/event/meta message; `rotate` starts a new file (compaction splits files). */
export interface TraceSink {
write(msg: OmniMessage): Promise<void>;
/** Optional: start a new Trace file (index+1), used to record the new model context after compaction. */
rotate?(): Promise<void>;
/** Optional: absolute path of the file the next `write` lands in (what stop hooks read the conversation from). */
currentPath?(): string;
}
/**
* Resolved context compaction settings (defaults filled in by the composition layer).
* Docs: /docs/agent-loop § "Compaction".
*/
export interface CompactionSettings {
/** Context token threshold (uses the most recent token_usage's request.total); <=0 disables it. */
maxContextLength: number;
/** Session cumulative turn threshold (counted per LLM Request, across Tasks); <=0 means no limit. */
maxSessionTurns: number;
mode: CompactionMode;
/** Prompt used for summarize compaction. */
prompt: string;
}
/**
* A model context opened by {@link ContextEngineDeps.openNextContext} after a completed compaction:
* the fresh LLM object, plus what the opener re-read for it — the `session_meta` the rotated
* Trace file opens with (so that file's head describes the context it records) and the
* per-context engine settings. Every optional field absent means "the previous context's
* stays": an opener that could not re-read the Agent State returns the LLM alone.
*/
export interface OpenedContext {
llm: LLMInterface;
sessionMeta?: OmniMessage;
/** Maximum LLM turns per Task in this context; -1 removes the cap. */
maxTurns?: number;
/** Compaction settings of this context (thresholds, mode, Prompt). */
compaction?: CompactionSettings;
}
/** What {@link ContextEngineDeps.openNextContext} is called with. */
export interface OpenContextOptions {
/**
* Publishes a record the opener produces while opening — the `mcp_connect_begin` /
* `mcp_connect_end` pair bracketing its MCP connect, and the `tool_list_ready` carrying the
* context's toolset. The engine yields each one live, in call order, and writes them at the
* head of the rotated Trace file right after the context's `session_meta`, so the new file
* is self-contained; an opener that emits nothing leaves the previous context's toolset
* record in place there.
*/
emit: (msg: OmniMessage) => void;
}
/**
* What a model switch does when the summarize compaction that closes its old context cannot
* complete (see {@link ContextEngine.switchContext}).
*
* - `"stay"` (default) — the switch fails and the Session keeps the model it is on. A context is
* dropped on purpose or not at all, never as a side effect of a failed request.
* - `"discard"` — the context is dropped **without sending anything** and the switch completes on
* the target. This is the way out of a model that cannot answer at all: the summarize request is
* one of that model's own requests, so a model that is out of quota or whose credential was
* rejected cannot summarize itself, and the user would otherwise be unable to leave it inside
* the Session (a model switch is the only way to change it in place). What it costs is the
* summary: the conversation's working memory is gone (the Transcript, the Trace files and the
* Session itself stay), and the next context opens with the carried text alone.
*/
export type SwitchFailurePolicy = "stay" | "discard";
/** Result of one compaction run: a StopReason terminal state (completed / aborted / retryable — abandoned, made up at the next trigger / fatal — needs a config change first); carries the summary message when summarize succeeds. */
interface CompactionResult {
status: StopReason;
summary?: OmniMessage;
/** The failure's classified cause and detail (mirrors the compaction_end's error pair) — present on `retryable` / `fatal` ends. */
errorCode?: ErrorCode;
errorMessage?: string;
/**
* Whether at least one summarize attempt was **committed** by AgentHub (only a `completed`
* attempt commits — a `retryable` attempt ends an incomplete stream and fatal/aborted
* throw or cut off before a clean end). The carry rule at every caller is a two-case binary on
* this flag (issue #85): committed → the input the caller folded in (mid-Task tool outputs,
* or the carry-over a manual `compact()` folds in) now lives in the old LLM object's history
* and must never be resent — strict providers reject the duplicates as stale tool_results;
* not committed → the folded input is untouched and is resent exactly as before. When
* nothing was folded in (idle/boundary compaction), the committed branch is vacuous —
* dropping zero outputs, clearing an empty carry — so no separate "was anything absorbed"
* signal is needed. Zero committed attempts also implies zero synthesized repairs (repairs
* only answer a committed rejection's tool calls).
*/
committed: boolean;
}
/**
* Options for `run`.
* Docs: /docs/agent-loop § "Inputs and outputs".
*/
export interface RunOptions {
/** Abort signal (e.g. Ctrl-C). */
signal?: AbortSignal;
/** Per-tool approval callback; defaults to denying everything (conservative, to avoid accidental approval when unattended). */
approve?: ApproveFn;
/** Pre-tool-use hook consult, called before `approve` for each complete tool_call; its events are recorded on the stream, its decision applied (see {@link PreToolUseFn}). */
preToolUse?: PreToolUseFn;
/** User-prompt hook consult, called once with this call's Prompt after it is written and before the first request; its records follow the Prompt on the stream and in the Trace, and the user texts among them join the request input (see {@link UserPromptFn}). */
userPrompt?: UserPromptFn;
}
/**
* Engine initial state (used for Session resumption): derived by replaying Trace, so the
* resumed engine behaves the same as before the process
* exited. Not passed when creating a normal new Session.
*/
export interface EngineInitialState {
/** Pending input (carry-over): resent alongside new input on the first `run` after resumption (synthetic placeholders exist only in memory, never written to Trace). */
carryOver?: OmniMessage[];
/** Summary recovered from a completed summarize compaction: used as the prefix of the next `run` input (merged with the user Prompt). */
pendingSummary?: OmniMessage;
/** The summary the resumed context opened with, when it is already on the context's own file and no turn has completed since (see ResumeResult.openingSummary). */
openingSummary?: OmniMessage;
/** Carried-over Session cumulative turn count. */
sessionTurns?: number;
/**
* The resumed context was opened by a **completed** compaction (the Trace's last record is a
* completed `compaction_end`), so it is legitimately empty. Restores `fromCompaction`, which
* is what keeps `compactability()` answering "just compacted" rather than "nothing said yet"
* after a restart — both have zero turns and are not the same message to a user.
*/
fromCompaction?: boolean;
/** Carried-over Session cumulative token counts (the engine resumes its own accumulator from them). */
sessionTokens?: TokenCounts;
/** Most recent token_usage's request.total (the context usage figure, keeps compaction threshold checks continuous). */
lastRequestTotal?: number;
/** Recovered from a completed compaction: the context is already closed, so rotate the Trace file (index+1, writing session_meta) before the first write. */
pendingTraceRotation?: boolean;
}
export interface ContextEngineDeps {
llm: LLMInterface;
environment: EnvironmentInterface;
/** Optional Trace writer; the writer is responsible for filtering out streaming partial_* messages. */
trace?: TraceSink;
/** Engine initial state (derived by replaying Trace on Session resumption). */
initialState?: EngineInitialState;
/** Maximum LLM turns for a single Task in the first context; -1 removes the cap. Omitted means -1 too — the agent-config default and the SDK fallback agree (unlimited). A context `openNextContext` opens may bring its own. */
maxTurns?: number;
/**
* Maximum automatic retries for LLM timeout/reconnect within a single run. Defaults
* to 5: with the default backoff (2s base, 30s ceiling) that is 2+4+8+16+30 ≈ 60s of
* total patience — transient provider failures (restarts, rate limits) get a real
* recovery window instead of five retries burning out in about a second (issue #218).
*/
maxReconnects?: number;
/**
* Absolute ceiling on the attempts a single turn may make, counting every attempt whether
* or not it received anything. Defaults to 20. It only binds once received content has
* reset the consecutive ladder (`maxReconnects`) at least once, and exists solely to keep
* that reset from turning an endpoint that streams a few tokens and drops into an endless
* retry loop.
*/
maxTurnAttempts?: number;
/**
* Exponential backoff base (ms): the wait before reconnect retry N is
* `base × 2^(N−1)`, capped at `reconnectBackoffMaxMs` (see reconnectDelayMs).
* Defaults to 2000.
*/
reconnectBackoffMs?: number;
/** Ceiling (ms) for a single reconnect backoff wait. Defaults to 30000. */
reconnectBackoffMaxMs?: number;
/**
* Maximum retries for a failing compaction request — one budget for every failure kind:
* the transport statuses (see RETRY_STATUSES) and a committed response that isn't a usable
* summary (empty, or tool calls) all draw from it; only `fatal` stops without retrying.
* Defaults to the shared `maxReconnects`: a compaction request is an ordinary LLM request
* and deserves the same patience (issue #170 — the earlier tighter budget made a
* struggling provider fail compaction fast, and a session whose every turn re-triggers
* compaction is stuck). Failure stays graceful either way: the original context is kept
* and compaction retries at the next trigger.
*/
compactionMaxReconnects?: number;
/**
* Opens a fresh model context after compaction: the new LLM object, plus whatever the
* opener re-read for the new context — its session_meta and its engine settings (see
* {@link OpenedContext}) — and, through `opts.emit`, the records it produced while opening
* (see {@link OpenContextOptions}). May rebuild the toolset and connect MCP servers, hence
* possibly async and possibly slow; the engine yields the emitted records live meanwhile.
* Session token continuity is the engine's own bookkeeping — it seeds the returned LLM's
* `sessionTokens` itself. Context compaction is unavailable if this is not provided.
*/
openNextContext?: (opts: OpenContextOptions) => OpenedContext | Promise<OpenedContext>;
/** The first context's compaction settings; only takes effect if provided together with `openNextContext`. A context `openNextContext` opens may bring its own. */
compaction?: CompactionSettings;
/**
* Live compaction settings, re-read at every point the engine consults them for a decision:
* the post-request checkpoint (threshold and turn count), and the start of a compaction
* (mode and prompt). This is what takes compaction configuration out of the strict tier —
* an edit saved to the Agent's config reaches a running Session at its next checkpoint
* instead of waiting for a rotation.
*
* Refreshes an existing baseline; it never creates one. An embedder that supplies only
* `compaction` keeps today's fixed-per-context behaviour, and one that supplies neither has
* no compaction at all — so whether compaction is *configured* stays a constant of the
* Session, which is what `compactability()` may answer synchronously.
*
* The provider is expected to be cheap enough to call once per checkpoint (the Agent's caches
* by the config file's identity on disk). A read that throws leaves the previous settings in
* force and is logged once: a config file that briefly cannot be read must not end a run.
*/
readCompaction?: () => CompactionSettings | Promise<CompactionSettings>;
/**
* The first context's session_meta message: written at the start of each Trace file a
* compaction's rotation opens, until an `openNextContext` result brings the meta of the context
* it opened — from then on that one is written, so every file's head describes its own
* context.
*/
sessionMeta?: OmniMessage;
/**
* The first context's tool_list_ready event (the resolved toolset). Written once right
* after the first run's input (following `bootstrapRecords`), and again right after
* sessionMeta on each Trace file a compaction's rotation opens — until an `openNextContext`
* emits the records of the context it opened, which take its place there — so every
* file's tool record stays self-contained. Held here alone; deliberately NOT part of
* `bootstrapRecords`, so the one message isn't carried twice.
*/
toolList?: OmniMessage;
/**
* The first run's mcp_connect begin/end pair (empty without MCP), written once right
* AFTER that run's input messages — followed by `toolList` — so the connect phase lands
* inside the new turn in the Trace, after the user's message (their timestamps precede
* the write; the file stays chronologically consistent because the input message was
* created before the connect began). Streaming already yielded them live before the
* engine existed. Present (possibly empty) marks "first-run records still owed". Owed
* only while the first context runs: when that context is replaced before any run wrote
* them (a compaction or a model switch on a Session just resumed, whose engine was built
* outside a run), they are dropped with it — and the first-run write of `toolList` with
* them — rather than landing behind the next run's input, in the next context's file.
*/
bootstrapRecords?: OmniMessage[];
/**
* Input adapter for a session whose model has no vision: folds image messages into text
* lines appended to the input's user text. Absent = the model takes images directly. `run`'s
* Prompt is folded by the caller before it reaches the engine; this hook exists for the one
* input the engine assembles itself — steering (see `steeringMessages`). A `null` answer
* leaves the input as it is too: the caller's model can change between contexts (a model
* switch), and only the caller knows whether the one running now takes images.
*
* Expected to settle rather than reject: it runs mid-Task, and Session's binding already
* degrades a failure into text saying the images were dropped.
*/
foldInputImages?: (messages: OmniMessage[]) => Promise<OmniMessage[] | null>;
/**
* Background-task completion notices (harness user messages the Session queues when a
* `run_in_background` task settles — see Session's notice queue). Pull seam: the engine
* drains at every input-assembly point — run start included — yielding each message to the
* output stream and writing it to Trace (like steering, this text never reached the
* consumer any other way); `pending` is the boundary peek that keeps a discard/summary
* from ending the run while notices still wait. This drain IS the steering delivery path:
* the source builds each message with `delivery: steering` on its block, marking it as
* injected into an already-started Task rather than a task-starting input (only the host's
* idle take produces the unstamped form). Absent = no notice source (tests, standalone
* embedders).
*/
backgroundNotices?: { drain(): OmniMessage[]; pending(): number };
}
const isImageMessage = (m: OmniMessage): boolean =>
(m.payload as { type?: string }).type === "image_url";
/** Whether a message carries steering of its own — an image, a video, or text that isn't blank. */
const carriesSteering = (m: OmniMessage): boolean => {
const p = m.payload as { type?: string; text?: string };
return (
p.type === "image_url" ||
p.type === "video_url" ||
(p.type === "text" && (p.text ?? "").trim().length > 0)
);
};
/** Whether compaction is possible; when not `ok`, `compact()` is a no-op and yields no messages (see ContextEngine.compactability). */
export type CompactAvailability = "ok" | "unsupported" | "empty" | "just_compacted";
/** The context facts the availability rule reads (see `compactAvailability`). */
export interface CompactabilityState {
/** Whether the compaction capability is configured at all (settings + the new-context LLM factory). */
configured: boolean;
/** Completed turns in the **current** context (reset by compaction, restored from Trace on resume). */
sessionTurns: number;
/** Whether the current context was opened by a completed compaction rather than by the user. */
fromCompaction: boolean;
}
/**
* The compaction-availability rule, stated once.
*
* Two callers answer the same question from different vantage points and must not drift apart:
* a live `ContextEngine` reads its own counters, while a `Session` resumed after a process
* restart has no engine yet (it is built by the first run's bootstrap) and answers from the
* state its Trace replay recovered. Duplicating the rule is how "restart the client and it
* claims there is nothing to compact" happens.
*/
export function compactAvailability(state: CompactabilityState): CompactAvailability {
if (!state.configured) return "unsupported";
if (state.sessionTurns > 0) return "ok";
// Both remaining cases have zero turns and mean completely different things to the user.
return state.fromCompaction ? "just_compacted" : "empty";
}
/**
* Corrective note prepended to the re-sent compaction Prompt after a committed-but-unusable
* response (empty summary, or tool calls — issues #83/#170). The unusable
* response is committed on the live LLM object and can only be *appended* to (rewriting the
* prefix would invalidate the provider's prompt cache at the moment the context is largest —
* the same invariant that pins the toolset, issue #84); without an explicit correction the
* model sees its own bad output as the freshest example and copies it verbatim on every
* retry (issue #170: deepseek-v4-flash kept writing the body after `[/summary]`).
* Exported for unit tests.
*/
export const SUMMARY_RETRY_GUIDANCE =
"Your previous reply was not a usable summary. Reply again with text only, no tool " +
"calls, in exactly this format and nothing after it:\n\n" +
"[summary]put the summary text here...[/summary]";
/** Result of executing one LLM turn (the return value of runTurn). */
interface TurnResult {
/** All tool outputs for this turn, reordered to match the original tool_call order (for the next turn's LLM input). */
toolOutputs: OmniMessage[];
/** tool_calls issued by the model this turn (in original order, real requests only). */
toolCalls: OmniMessage<ToolCallPayload>[];
/** Complete thinking/text segments produced by the model this turn (including partial segments finalized on interruption), for carry-over flattening. */
assistantSegments: OmniMessage[];
/**
* Whether this attempt received anything at all from the LLM stream. It is what the
* reconnect loop resets its ladder on: one message is proof the connection was established
* and the model was producing. Deliberately wider than the collected arrays — a drop
* mid-tool-call synthesizes a tool_call that is never dispatched and so never reaches
* `toolCalls`, yet those bytes did arrive.
*/
receivedContent: boolean;
/** Terminal state of this turn's LLM request (completed / failed / aborted / timeout / malformed). */
outcome: LLMOutcome;
}
/**
* A turn's retry bookkeeping, threaded into `runTurn` so its `request_end` can announce the
* next attempt's planned backoff. `attempts` counts every attempt the turn has made so far
* (the ordinal hosts render, and what the absolute ceiling measures); `consecutive` counts
* only the tail of them that came back having received nothing — the backoff rung, and what
* `maxReconnects` measures. The two diverge as soon as an attempt receives content: see the
* reconnect loop in runToCompletion.
*/
interface TurnRetryState {
attempts: number;
consecutive: number;
}
/**
* LLM outcomes that reconnect in-run: exactly `retryable`. The classification lives in the
* LLM interface (see LLMOutcome) — transport drops, timeouts, 408/429/5xx, malformed
* responses and everything unclassifiable come back `retryable`, while definitive provider
* rejections and credential failures come back `fatal` and the turn loop aborts on them
* before consulting this set.
*
* Both loops retry the same set on the same backoff ladder, and by default with the same
* budget: compaction runs on `compactionMaxReconnects`, which follows `maxReconnects` unless
* set explicitly (issue #170 — a compaction request is an ordinary LLM request and gets the
* turn loop's patience; compaction additionally routes a committed-but-unusable summary
* through the same budget, see summarizeContext).
*
* One rule is the turn loop's alone: received content resets its ladder. Compaction cannot
* borrow it precisely because of that extra class — its budget also covers responses that
* were committed but unusable (an empty summary, or tool calls), where "produced content" is
* not evidence of progress at all, and resetting on it would turn issue #83's guard into a
* loop that re-asks a model already answering wrong, at maximum context, forever.
*/
const RETRY_STATUSES: readonly StopReason[] = ["retryable"];
/**
* Delay before reconnect attempt N (1-based): exponential growth from `base` with a hard
* ceiling `max` — `min(base × 2^(N−1), max)`. With the defaults (2s base, 30s ceiling,
* 5 reconnects) the ladder is 2s, 4s, 8s, 16s, 30s ≈ 60s of total patience: one shared
* schedule serves every retryable class. The base is sized for the slow ones — transient
* provider failures (restarts, rate limits) need seconds, not milliseconds, to
* recover, and the old 250ms base burned the whole ladder in ~7.75s (issue #218); it also
* keeps every planned wait at or above the hosts' 2s countdown floor (the Web App's
* COUNTDOWN_MIN_MS), so no retry ever looks like a silent stall. Transport blips pay at
* most one visible 2s wait — an acceptable trade for retries the user can see.
*/
export function reconnectDelayMs(base: number, max: number, attempt: number): number {
return Math.min(base * 2 ** (attempt - 1), max);
}
export class ContextEngine {
/** Per-context settings: the first context's from the deps, then whatever each opened context brings (see `startNewContext`). */
private maxTurns: number;
/** Compaction settings in force. Baseline per context (deps, then each opened context), and re-read from `deps.readCompaction` at every checkpoint in between. */
private compaction: CompactionSettings | undefined;
/** Whether a `readCompaction` failure has already been reported; one line per Session, not one per checkpoint. */
private compactionReadWarned = false;
private readonly maxReconnects: number;
private readonly maxTurnAttempts: number;
private readonly reconnectBackoffMs: number;
private readonly reconnectBackoffMaxMs: number;
private readonly compactionMaxReconnects: number;
/** Interruption cleanup: content to resend generated when the previous run was aborted, held on the engine across runs. */
private pendingCarryOver: OmniMessage[] = [];
/** Current LLM object; swapped for the one `openNextContext` returns after a successful compaction (a fresh model context). */
private llm: LLMInterface;
/**
* session_meta of the current context, written at the head of the Trace file the deferred
* rotation opens (see `write`): the first context's at construction, then whatever meta each
* `openNextContext` result brings — a context that brought none keeps the previous one.
*/
private contextMeta: OmniMessage | undefined;
/**
* The records written right after `contextMeta` at that rotation — the context's toolset
* record and, when it connected MCP servers, the connect pair before it: the first context's
* `toolList` at construction, then what each `openNextContext` emitted — a context that emitted
* nothing keeps the previous records.
*/
private contextRecords: OmniMessage[];
/** Session cumulative turn count: counted per LLM Request that produces token_usage, across Tasks; reset to zero after compaction completes. */
private sessionTurns = 0;
/** Whether the current context was produced by a compaction (`startNewContext`); this flag becomes meaningless once a new completed turn occurs. */
private fromCompaction = false;
/**
* The Session's current thinking level — the soft-limited runtime parameter as
* engine-owned state: `setThinkingLevel` (fed by the `Session.thinkingLevel` setter) moves it
* mid-context, and every subsequent request carries it as the per-request override — a
* turn and a compaction alike. Undefined = no pin: the LLM object's construction default
* (the context's opening base) applies.
*/
private thinkingLevel?: ThinkingLevelName;
/** Most recent token_usage's request.total, i.e. the current context usage figure. */
private lastRequestTotal = 0;
/** The Session-cumulative token series — engine-owned: accumulated from each token_usage's request counts and stamped onto the message before it is yielded or written (the LLM's lifetime is one context; the engine's is the Session). */
private lastSessionTokens: TokenCounts = emptyTokenCounts();
/** Summary produced by a Task-boundary compaction: used as the prefix of the next `run` input (merged with the next user Prompt). */
private pendingSummary: OmniMessage | null = null;
/**
* The summary the running context opened with, until a turn completes on it. It is the only
* record of the conversation before the compaction, so a model switch away from such a
* context writes it at the head of the next context's file (see `switchContext`).
*/
private openingSummary: OmniMessage | null = null;
/** Bootstrap records still owed to the Trace (written after the first run's input); see ContextEngineDeps.bootstrapRecords. */
private pendingBootstrapRecords: OmniMessage[] | null = null;
/**
* Set to true once compaction completes: Trace rotation is deferred until the next
* message that needs writing (see `write`) — so that if no further messages follow the
* compaction, we don't create an empty file containing only session_meta. A model switch is
* the one exception: it performs the rotation at once (see `switchContext`).
*/
private pendingTraceRotation = false;
/**
* Steering queue: user messages sent mid-run (`steer`). Drained at every next-input
* assembly — after each turn (delivered as standalone `[user_steering]` user messages
* alongside that turn's tool outputs, or alone as the continuation input when the turn
* produced no tool calls) and after a completed mid-run compaction (so steering that
* arrived during the compaction request is delivered, never swallowed). Only accepts
* entries while a run is in flight; the queue is discarded **only when the run exits**
* — abort, LLM failure, or a plain race with completion (the abort event / task end
* already hands control back to the user, and silently replaying stale steering into a
* later Task would be more surprising than losing it; hosts get `steer() === false`
* after that point and fall back to a normal task).
*/
private steeringQueue: OmniMessage[][] = [];
/** Whether a `run` is currently in flight (gates `steer`; compaction does not count). */
private taskRunning = false;
/** Whether a `run` is in flight (the Session's notice routing keys on this: a running task delivers notices at the next boundary; an idle one goes through the host). */
get isTaskRunning(): boolean {
return this.taskRunning;
}
/** Background notices still waiting at the source (boundary peek; see ContextEngineDeps.backgroundNotices). */
private pendingNoticeCount(): number {
return this.deps.backgroundNotices?.pending() ?? 0;
}
/**
* Drains queued background-task notices into the stream: each is yielded and written to
* Trace (mid-run input the consumer has never seen, same rationale as deliverSteering),
* and returned for the caller to append to the next request input. Delivered BEFORE
* steering at every assembly point — the user's own words come last.
*/
private async *deliverBackgroundNotices(): AsyncGenerator<OmniMessage, OmniMessage[]> {
const messages = this.deps.backgroundNotices?.drain() ?? [];
for (const msg of messages) {
yield msg;
await this.write(msg);
}
return messages;
}
constructor(private readonly deps: ContextEngineDeps) {
this.pendingBootstrapRecords = deps.bootstrapRecords ?? null;
this.maxTurns = deps.maxTurns ?? -1;
this.maxReconnects = deps.maxReconnects ?? 5;
this.maxTurnAttempts = deps.maxTurnAttempts ?? 20;
this.reconnectBackoffMs = deps.reconnectBackoffMs ?? 2000;
this.reconnectBackoffMaxMs = deps.reconnectBackoffMaxMs ?? 30_000;
this.compactionMaxReconnects = deps.compactionMaxReconnects ?? this.maxReconnects;
this.compaction = deps.compaction;
this.llm = deps.llm;
this.contextMeta = deps.sessionMeta;
this.contextRecords = deps.toolList ? [deps.toolList] : [];
// Session resumption: apply the initial state derived from replay.
const init = deps.initialState;
if (init) {
this.pendingCarryOver = init.carryOver ?? [];
this.pendingSummary = init.pendingSummary ?? null;
// A resumed context that has not completed a turn still opens with its summary: the one
// already on its own file, or the one a closed file left pending.
this.openingSummary = init.openingSummary ?? this.pendingSummary;
this.sessionTurns = init.sessionTurns ?? 0;
this.fromCompaction = init.fromCompaction ?? false;
this.lastSessionTokens = init.sessionTokens ?? emptyTokenCounts();
this.lastRequestTotal = init.lastRequestTotal ?? 0;
this.pendingTraceRotation = init.pendingTraceRotation ?? false;
}
}
/** Moves the Session's thinking level mid-context (see the `thinkingLevel` field); applies from the next request, turn or compaction. */
setThinkingLevel(level: ThinkingLevelName): void {
this.thinkingLevel = level;
}
/**
* Runs a Task to completion, streaming out OmniMessage. `newMessages` is this call's
* Prompt (only the newly added input, not the full history — history is maintained by the
* stateful GenerativeModel); `opts.signal` is the abort signal, `opts.approve` is the
* per-tool approval callback.
* Docs: /docs/agent-loop § "The loop at a glance".
*/
async *run(
newMessages: OmniMessage[],
opts?: RunOptions,
): AsyncGenerator<OmniMessage, RunCutoff | null> {
// Steering window: only while this generator is being driven. The finally also covers
// abort/failure exits — anything still queued is discarded (see steeringQueue).
this.taskRunning = true;
try {
// The return value says how the run ended (yield* propagates it): null = ran to
// completion; a RunCutoff = ended early, with the terminal record's error pair.
return yield* this.runToCompletion(newMessages, opts);
} finally {
this.taskRunning = false;
this.steeringQueue = [];
}
}
/**
* Queues a steering message for the running Task: it is delivered with the next request
* input as a standalone `[user_steering]` user message — alongside that turn's tool
* outputs, or alone as the continuation input when the turn produced no tool calls.
* `input` is an OmniMessage list, the shape `run` takes a Prompt in: its user text becomes
* the block's body and its images ride behind that text, exactly as a Prompt carries them;
* on a model without vision they are folded into path lines at delivery (see
* deliverSteering). Returns false when no Task is running (the host should then submit the
* message as a normal task instead).
*
* An input with neither text nor images queues nothing and still returns true: `false` is
* specifically "send this as a normal task", which would be the wrong advice for an empty
* one. Every host guards against this already; the check is here so an empty
* `[user_steering]` block can't reach the model through a host that forgets.
*/
steer(input: OmniMessage[]): boolean {
if (!this.taskRunning) return false;
if (!input.some(carriesSteering)) return true;
this.steeringQueue.push(input);
return true;
}
/**
* Withdraws a queued steering input that has not been delivered yet. `input` is the exact
* list previously passed to `steer` (matched by identity — the host that queued it is the
* one recalling it, and it holds the reference). Returns false when the entry is no longer
* in the queue: it was already drained into the next request input (or the run exited),
* which the host surfaces as "already delivered" rather than an error.
*/
unsteer(input: OmniMessage[]): boolean {
const i = this.steeringQueue.indexOf(input);
if (i < 0) return false;
this.steeringQueue.splice(i, 1);
return true;
}
/**
* Drains the steering queue into standalone `[user_steering]` user messages (one per
* queued entry, in arrival order, each followed by its images), yielding every message to
* the output stream and writing it to Trace — steering is real user input: unlike a normal
* Prompt (which the render layer already holds locally) this text never reached the
* consumer, and replay attributes it positionally to the next turn's input like any other
* user message. Returns the messages for the caller to append to the next request input;
* an empty queue is a no-op.
*/
private async *deliverSteering(): AsyncGenerator<OmniMessage, OmniMessage[]> {
if (this.steeringQueue.length === 0) return [];
const drained = this.steeringQueue;
this.steeringQueue = [];
const messages: OmniMessage[] = [];
for (const input of drained) messages.push(...(await this.steeringMessages(input)));
for (const msg of messages) {
yield msg;
await this.write(msg);
}
return messages;
}
/**
* One queued steering input -> the messages carrying it: its user text collected into the
* `[user_steering]`-wrapped message, followed by everything else it held — the images, on a
* vision model. That is the shape a Prompt uses, so every consumer down the line — LLM
* client, Trace, replay — already knows it.
*
* When `deps.foldInputImages` is given, the input goes through it **before** the wrapping so
* the images land inside the block: `parseUserSteeringText` only recognizes a text that is
* exactly one block, and anything appended after the closing tag would cost the message its
* steering identity — every render layer would read it as a new Task.
*/
private async steeringMessages(input: OmniMessage[]): Promise<OmniMessage[]> {
// No images, no fold: an image-free steering message is the same message either way.
const folded = input.some(isImageMessage) ? await this.deps.foldInputImages?.(input) : null;
const messages = folded ?? input;
const texts: string[] = [];
// The delivered [user_steering] message keeps the queued input's sender: a parent agent
// steering its child (input_subagent) records as "parent_agent" in the child's Trace,
// while human steering keeps the field absent — origin stays a structural fact.
let sender: TextSender | undefined;
const rest: OmniMessage[] = [];
for (const msg of messages) {
const p = msg.payload as { type?: string; role?: string; text?: string; sender?: TextSender };
if (p.type === "text" && p.role === "user") {
texts.push(p.text ?? "");
sender ??= p.sender;
} else rest.push(msg);
}
// `foldInputImages` is public API, so a third-party adapter can return something else, and
// both ways it can break lose the picture: an image that survived the fold goes to the one
// model known to refuse it, and no text at all means the images were dropped rather than
// written down as paths. Name the contract instead of delivering a steering message that
// lost what it was sent to carry.
if (folded && (rest.some(isImageMessage) || texts.length === 0)) {
throw new Error("foldInputImages must return the input's images folded into a user text.");
}
return [userText(userSteeringText(texts.join("\n\n")), sender), ...rest];
}
/** The actual Task loop behind `run` (split out so run's finally can close the steering window on every exit path). */
private async *runToCompletion(
newMessages: OmniMessage[],
opts?: RunOptions,
): AsyncGenerator<OmniMessage, RunCutoff | null> {
const signal = opts?.signal;
// Default approval policy: deny (conservative). CLI/Web will inject a real callback (interactive or permission-mode based).
const approve: ApproveFn = opts?.approve ?? (async () => "deny");
const preToolUse = opts?.preToolUse;
// Merge the Task-boundary compaction summary (the new context's first input, merged with
// this Prompt), the carry-over left over from the last interruption, and this call's new
// input, to form this Request's input.
const summary = this.pendingSummary;
this.pendingSummary = null;
const carryOver = this.pendingCarryOver;
this.pendingCarryOver = [];
const prefix = summary ? [summary, ...carryOver] : carryOver;
let input = prefix.length ? [...prefix, ...newMessages] : newMessages;
// Input is written to Trace (Prompt record, incl. audit trail) but not replayed to
// the render layer. carry-over is not written to Trace: real messages (tool outputs etc.)
// are already written when produced; synthetic content (flatten text, backfilled
// placeholders) is **sent to the model only, never persisted** — Trace records only real
// messages, and resumption replay best-effort reconstructs from original messages.
// Exception: the compaction summary, which is the new
// context's first input record, is written as usual.
if (summary) await this.write(summary);
for (const msg of newMessages) await this.write(msg);
// User-prompt hooks (RunOptions.userPrompt, wired by the Session from the Agent's
// installed hook packages): consulted once per Prompt, here, so what they answer lands
// right behind the user's message — on the stream, in the Trace and in the request
// input alike. A throw collapses to nothing to add: a broken hook must not cost the
// user their Prompt.
if (opts?.userPrompt && !signal?.aborted) {
let expanded: UserPromptOutcome | null = null;
try {
expanded = await opts.userPrompt(newMessages, signal);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[penguin] userPrompt consult threw: ${message}; ignoring.\n`);
}
const contexts: OmniMessage[] = [];
for (const record of expanded?.records ?? []) {
yield record;
await this.write(record);
if (isModelMessage(record)) contexts.push(record);
}
if (contexts.length > 0) input = [...input, ...contexts];
}
if (this.pendingBootstrapRecords) {
// First run only: the connect pair, then the toolset record, follow the input into
// the Trace (see ContextEngineDeps.bootstrapRecords for the ordering rationale).
for (const msg of this.pendingBootstrapRecords) await this.write(msg);
this.pendingBootstrapRecords = null;
if (this.deps.toolList) await this.write(this.deps.toolList);
}
if (signal?.aborted) {
// Aborted before the Request was issued: the input is held **as-is** as carry-over
// (trailing-input semantics: input the Request never got to send is kept unchanged)
// — not flattened, so replay matches in-process behavior and
// multimodal input isn't lost. The message is already written to Trace, so it won't be
// rewritten on the next send.
this.pendingCarryOver = input;
yield* this.emitAbort("user_abort");
return { kind: "abort", errorCode: "user_abort" };
}
let turnCount = 0;
// Each turn's LLM input: the first turn is the Prompt, later turns are the previous turn's
// tool outputs. Background notices that arrived while the session sat idle (and were not
// taken by the host as their own task input) ride the first request, behind the Prompt.
let nextInput: OmniMessage[] = input;
const startNotices = yield* this.deliverBackgroundNotices();
if (startNotices.length > 0) nextInput = [...nextInput, ...startNotices];
for (;;) {
// max_turns guard: emit a length notice and stop once exceeded. A non-positive cap
// (-1 per the config contract "must be > 0 or -1") disables the guard entirely —
// same convention as maxSessionTurns in shouldCompact (issue #55: -1 used to trip
// `0 >= -1` and stop before the first turn).
if (this.maxTurns > 0 && turnCount >= this.maxTurns) {
// This turn's pending input (usually the previous turn's tool outputs) was never
// submitted to the LLM: hold it as carry-over, to be resent merged with new input on
// the next `run` (same as interruption-cleanup case A) — the previous turn's assistant
// tool_call has already been committed by AgentHub, so discarding its paired output and
// sending a fresh message would be rejected by the provider as an unanswered tool_use
// (400, see issue #33).
this.pendingCarryOver = nextInput;
yield* this.emitMaxTurns();
return { kind: "max_turns" };
}
turnCount += 1;
// This turn's input. The safety invariant behind resending it: **no retryable attempt
// is ever committed to AgentHub's history**. AgentHub appends a turn to `_history` only
// after its stream has been consumed to the end and validated, so every abnormal exit —
// whether the stream was cut, the payload failed to parse, or the request was rejected
// outright — leaves history untouched.
// Nothing can therefore be duplicated or left as an unanswered tool_use by a reconnect;
// that is what makes it safe to resend this turn's input unchanged, appending a
// `[turn_retried]` block carrying what the failed attempt already produced — the model
// continues from there instead of re-running tools; the tag is distinct from the
// user-interruption `[turn_aborted]`. (The one attempt that IS committed — a fully
// delivered response whose finish_reason arrived — is forced to `completed` in
// GenerativeModel precisely so it never reaches this loop.)
const failedTurns: TurnResult[] = [];
let attemptInput = nextInput;
// Two counters, because the ladder and the ceiling answer different questions (see
// TurnRetryState): `attempts` is every attempt this turn has made, `consecutive` only
// the tail that received nothing. Both live and die with the turn.
let attempts = 0;
let consecutive = 0;
let turn: TurnResult;
for (;;) {
// Both LLM and Environment handle errors internally and guarantee a complete, closed
// output with no thrown exceptions; the engine doesn't handle exceptions —
// it decides retry/resend purely from `outcome`. The retry count so far is threaded
// in so the turn's request_end can announce the planned backoff (retry_in_ms) —
// the counter lives in this loop while the event is built inside the turn.
turn = yield* this.runTurn(
attemptInput,
approve,
signal,
{ attempts, consecutive },
preToolUse,
);
attempts += 1;
// User interruption (the LLM stream was aborted, outcome=aborted, or `signal` fired
// during tool execution): stop and hand control back to the user.
if (signal?.aborted || turn.outcome.status === "aborted") {
this.pendingCarryOver = this.buildCarryOver(attemptInput, turn);
yield* this.emitAbort("user_abort");
return { kind: "abort", errorCode: "user_abort" };
}
// `fatal` stops the run: a definitive provider rejection, a dead credential, or a
// deterministic client-side rejection — the identical request can never succeed, so
// the ladder would only delay the actionable message the outcome already carries.
// No abort event: abort marks a user interruption, and the already-written
// request_end (status `fatal`, `error_message`, no `retry_in_ms`) is the terminal
// record frontends and observability read.
if (turn.outcome.status === "fatal") {
this.pendingCarryOver = this.buildCarryOver(attemptInput, turn);
return {
kind: "llm_failure",
...(turn.outcome.errorCode !== undefined ? { errorCode: turn.outcome.errorCode } : {}),
...(turn.outcome.errorMessage !== undefined
? { errorMessage: turn.outcome.errorMessage }
: {}),
};
}
// Completed normally.
if (turn.outcome.status === "completed") break;
// `retryable` remains: reconnect automatically within the same run. The class is
// deliberately wide — the LLM interface sends every unclassifiable error here,
// because its fatal detector is an allowlist and a gateway phrasing a transient
// fault its own way (`Upstream HTTP/2 stream failed (upstream_http2_stream_error)`)
// must keep its retries; the concrete failure rides on errorMessage.
//
// When retries are exhausted or the backoff is interrupted, the retry input is held
// as-is as carry-over (the original input is already written to Trace, so it isn't
// rewritten). The frontend surfaces the retry process and count via
// request_end(retryable) followed by the next request_begin.
failedTurns.push(turn);
attemptInput = this.withRetriedTurns(nextInput, failedTurns);
// Received content resets the ladder. An attempt the stream sent anything to had a
// working connection and a model writing into it, so its drop is a fresh transport
// fault — not the n-th piece of evidence that this endpoint is unreachable. A socket
// that dies twice in one turn shouldn't add up to a reason to stop while
// `[turn_retried]` carries the accumulated output into every retry and the turn keeps
// inching forward. What bounds this is the ceiling below, not the ladder: an endpoint
// that streams a few tokens and drops, every single time, would otherwise be retried
// forever.
if (turn.receivedContent) consecutive = 0;
// Exhausted: give up without an abort event — abort marks a user interruption,
// and the last failure's request_end (status `retryable` with no `retry_in_ms`,
// since no retry is planned) is the terminal record frontends and observability
// read; `attempt` and `error_message` ride on it.
if (consecutive >= this.maxReconnects || attempts >= this.maxTurnAttempts) {
this.pendingCarryOver = attemptInput;
return {
kind: "llm_failure",
...(turn.outcome.errorCode !== undefined ? { errorCode: turn.outcome.errorCode } : {}),
...(turn.outcome.errorMessage !== undefined
? { errorMessage: turn.outcome.errorMessage }
: {}),
};
}
consecutive += 1;
if (!(await this.backoff(consecutive, signal))) {
this.pendingCarryOver = attemptInput;
yield* this.emitAbort("backoff_interrupted");
return { kind: "abort", errorCode: "backoff_interrupted" };
}
}
// Compaction checkpoint: after every LLM Request produces token_usage. This also
// applies mid-Task — when runTurn returns, all of this turn's
// tool results are ready and paired with their tool_call.
const midTask = turn.toolOutputs.length > 0;
// The checkpoint is where compaction configuration is consulted, so it is where it is
// re-read: the threshold and turn count `compactionTrigger` compares against, and the
// `mode` picked from the same settings immediately below, are the values on disk right
// now rather than the ones this context opened with.
await this.refreshCompaction();
const compactionReason = this.compactionTrigger();
if (compactionReason) {
const mode = this.compaction!.mode;
if (mode === "discard") {
// Once discarded, the current Task can't continue: defer until the Task really
// ends (mid-Task, or steering/notices still queued that must continue the loop).
// The queues are only peeked here — delivery happens at the input assembly below.
if (!midTask && this.steeringQueue.length === 0 && this.pendingNoticeCount() === 0) {
yield* this.discardContext(compactionReason);
return null;
}
} else {
const result = yield* this.summarizeContext(
compactionReason,
midTask ? turn.toolOutputs : [],
signal,
);
if (result.status === "completed") {
// Boundary check against the **live** queues: steering or a background notice
// may have arrived during the multi-second compaction request and must not be
// swallowed (no await sits between this check and the return, so the window
// cannot reopen).
if (!midTask && this.steeringQueue.length === 0 && this.pendingNoticeCount() === 0) {
// Task boundary: the summary is merged with the next user Prompt as the new
// context's first input.
this.pendingSummary = result.summary!;
return null;
}
// Mid-Task: the summary itself becomes the new LLM object's first input (this
// turn's tool results were already folded into the compaction request and absorbed
// into the summary); continuation relies on the model's own next-step plan written
// into the summary, with no hardcoded continuation instruction appended. Queued
// steering (including anything that arrived during the compaction request) is
// delivered right after the summary as standalone [user_steering] user turns.
await this.write(result.summary!);
const injected = [
...(yield* this.deliverBackgroundNotices()),
...(yield* this.deliverSteering()),
];
nextInput = [result.summary!, ...injected];
continue;
}
// failed or aborted: keep the original context and Trace index — the compaction is
// made up later, at the next trigger or a manual /compact (no fallback to
// discard). Mid-Task the run ends through the interruption flow: this turn's
// pending state is held as carry-over under the same two-case binary as everywhere
// (issue #85) — a committed attempt consumed the turn's outputs into history, so
// only the repair stash summarizeContext left in pendingCarryOver still needs
// resending; otherwise the outputs are untouched and are appended behind the stash
// as case-A carry-over. The next run resends that carry-over merged with the
// user's message, exactly like any interrupted turn, and the still-standing
// threshold re-triggers the compaction there. The abort also discards the steering
// queue (run's finally — control goes back to the user).
if (midTask) {
if (!result.committed) {
this.pendingCarryOver = [
...this.pendingCarryOver,
...this.buildCarryOver(attemptInput, turn),
];
}
// Only the user interruption is an abort; a failed compaction's terminal
// record is the compaction_end (status + error_message) already written.
if (result.status === "aborted") {
yield* this.emitAbort("compaction_interrupted");
return { kind: "abort", errorCode: "compaction_interrupted" };
}
return {
kind: "compaction_failure",
...(result.errorCode !== undefined ? { errorCode: result.errorCode } : {}),
...(result.errorMessage !== undefined ? { errorMessage: result.errorMessage } : {}),
};
}
// Task boundary: the final reply has already streamed out. A user abort hands
// control straight back; a failure falls through — queued steering may still
// continue the loop, and the assembly below otherwise ends the run.
if (result.status === "aborted") return null;
}
}
// Next-input assembly — the injection delivery point: queued background notices
// (harness user messages) and steering ([user_steering] user messages) ride alongside
// this turn's tool outputs (or alone as the continuation input when the turn produced
// no tool calls, instead of ending the Task — subject to the max-turns guard at the
// top of the loop). Notices first; the user's own words come last. The whole batch is
// user-side and reaches AgentHub as ONE user message (streamGenerate merges a
// request's input into a single UniMessage), so injections never put two adjacent
// user messages on the wire — the per-message granularity exists only in the
// OmniMessage stream and the Trace.
const injected = [
...(yield* this.deliverBackgroundNotices()),
...(yield* this.deliverSteering()),
];
// No tool_call this turn and nothing injected -> the Task ends (the final reply has
// already been streamed out). A compaction stash, if any, rides the next run.
if (!midTask && injected.length === 0) return null;
// Anything a failed boundary compaction stashed (synthesized repair outputs from
// rejected attempts) rides the very next request, ahead of the turn outputs so
// tool_results stay contiguous and first.
const stashed = this.pendingCarryOver;
this.pendingCarryOver = [];
nextInput = [...stashed, ...turn.toolOutputs, ...injected];
if (nextInput.length === 0) return null;
}
}
/**
* User-initiated compaction request (e.g. a CLI command): reuses the automatic compaction
* flow without checking thresholds (reason=manual). Only callable at a Task boundary (between
* runs); streams out paired compaction events. No-op when compaction is not configured.
*
* Carry-over left over from an interruption is cleaned up here too: summarize folds it into
* the compaction request (structured tool outputs keep their pairing with the already
* committed tool_call, otherwise the compaction request itself would be rejected by the
* provider as an unanswered tool_use, see issue #33; flatten text is absorbed into the
* summary); discard drops the structured outputs paired with the old context, keeping only the
* self-contained flatten text.
*/
/**
* Whether compaction is possible, and the **reason** when it isn't.
*
* `compact()` is a no-op and **yields no messages** in these cases; if the UI treats invoking
* it as a successful start, it ends up waiting forever for a compaction banner that never
* arrives — that's exactly how "/compact does nothing after an interruption" happens. Callers
* (Web / CLI) should give feedback upfront based on this.
*
* - `unsupported`: compaction capability is not configured;
* - `empty`: the current context hasn't completed a single turn (`sessionTurns` only
* increments when `token_usage` arrives — a turn only counts once the request finishes
* normally, so it's still 0 right after the first request is interrupted);
* - `just_compacted`: no new conversation since the last compaction. Both cases have
* `sessionTurns` === 0, but they mean two completely different things to the user and must
* not be conflated.
*
* The rule itself lives in `compactAvailability` so that a Session resumed after a restart —
* which has no engine yet — answers identically from its replayed state.
*/
compactability(): CompactAvailability {
return compactAvailability({
configured: Boolean(this.compaction && this.deps.openNextContext),
sessionTurns: this.sessionTurns,
fromCompaction: this.fromCompaction,
});
}
async *compact(opts?: {
signal?: AbortSignal | undefined;
/** Compacts in this mode whatever the settings say (a model switch always summarizes). */
mode?: CompactionMode;
}): AsyncGenerator<OmniMessage, StopReason | undefined> {
// The manual entry into a compaction, and the second place the live settings decide
// something: the `mode` below, and the prompt summarizeContext reads from them.
await this.refreshCompaction();
if (!this.compaction || !this.deps.openNextContext) return;
// The current context has no completed LLM turns: nothing to compact, return immediately.
// This also guards against two /compact calls in a row — the new context is empty right
// after the previous compaction, so running again would overwrite the not-yet-consumed
// pendingSummary with an "empty summary," permanently losing the only record of the prior
// conversation.
if (this.sessionTurns === 0) return;
if ((opts?.mode ?? this.compaction.mode) === "discard") {
this.pendingCarryOver = this.pendingCarryOver.filter(
(m) => (m.payload as { type?: string }).type !== "tool_call_output",
);
yield* this.discardContext("manual");
return "completed";
}
// The carry seam is a clean binary on whether the compaction committed anything to
// AgentHub (PR #87 review):
// - nothing committed (every attempt retryable/fatal/aborted): the fold
// never reached the model context — restore the prior carry-over **verbatim**. Zero
// committed attempts also means zero synthesized repairs, so there is no stash to
// interleave with (pinned by tests);
// - something committed: the carry-over is **consumed** — it lives in the committed
// history now and must never be resent; only the repair stash (unanswered tool_call
// pairing left by a final rejection, already in pendingCarryOver) remains pending.
const folded = this.pendingCarryOver;
this.pendingCarryOver = [];
const result = yield* this.summarizeContext("manual", folded, opts?.signal);
if (result.status === "completed") {
this.pendingSummary = result.summary!;
} else if (!result.committed) {
this.pendingCarryOver = folded;
}
// committed but not completed: the carry-over is deliberately not restored.
return result.status;
}
/**
* A model switch's rotation: closes the running context and opens the next one at once.
* Which model the next context runs on is the opener's business (`openNextContext`, which
* the Session owns); the engine only closes and opens. Callable at a Task boundary, with
* compaction configured, like `compact()`.
*
* - A context with completed turns is closed by `compact()`, always in **summarize** mode:
* the summary is what the next model continues from. It is an ordinary compaction request
* on the running LLM object — the same model, prompt, toolset and parameters, one appended
* user turn — so it extends the prefix the provider has cached. Short of `completed`, the
* context stays as it was — unless `opts.onCompactionFailure` says otherwise (see below).
* - A context with none has nothing to summarize and is simply replaced: no request and no
* event pair. Its pending text rides on in memory. Nothing is written until the next
* context is open, so an opener that throws leaves the Trace as it was.
*
* The next context's Trace file is then opened at once rather than at its first message:
* its `session_meta` is the durable record of the switch — a resume reads the model from
* the latest file — and the summary the context opens with follows it. That meta is yielded
* last. Returns the terminal status.
*
* `opts.onCompactionFailure` decides what a summarize that cannot complete means: `"stay"`
* (the default, and what a caller that passes nothing gets) leaves the Session on its model,
* while `"discard"` drops the context and switches anyway — the paired `discard` events say so
* on the stream and in the Trace, right after the `fatal`/`retryable` end of the failed
* summarize. Only a **failure** degrades: `aborted` is the user stopping the switch, and a
* switch that could not start a compaction at all is not a compaction failure either.
*/
async *switchContext(
signal?: AbortSignal,
opts?: { onCompactionFailure?: SwitchFailurePolicy },
): AsyncGenerator<OmniMessage, StopReason> {
if (this.sessionTurns > 0) {
const status = yield* this.compact({ signal, mode: "summarize" });
const degraded =
status !== "completed" &&
opts?.onCompactionFailure === "discard" &&
(status === "fatal" || status === "retryable");
if (degraded) {
// The failed summarize already wrote its Prompt and its event pair to the old Trace, so
// what is being given up stays visible; the drop itself sends nothing (the discard path
// needs no model), which is exactly what makes an unusable model leavable. The carry
// rule is the switch's own: text alone, since tool outputs pair with tool calls only the
// context left behind holds and images stay behind with them.
this.pendingCarryOver = this.pendingCarryOver.filter(
(m) => (m.payload as { type?: string }).type === "text",
);
yield* this.discardContext("manual");
} else if (status !== "completed") {
return status ?? "fatal";
}
} else {
yield* this.startNewContext();
// A switch carries text alone: tool outputs pair with tool calls only the context left
// behind holds, and images stay behind with them.
this.pendingCarryOver = this.pendingCarryOver.filter(
(m) => (m.payload as { type?: string }).type === "text",
);
}
// The eager open: session_meta and the opener's records head the new file, then the summary.
await this.rotateIfPending();
if (this.openingSummary) await this.write(this.openingSummary);
if (this.pendingSummary) {
// On the file now: from here it is pending input, which a run sends without writing.
this.pendingCarryOver = [this.pendingSummary, ...this.pendingCarryOver];
this.pendingSummary = null;
}
if (this.contextMeta) yield this.contextMeta;
return "completed";
}
/**
* The wait the engine WILL apply before retrying this failure in-run, or undefined when
* it won't (a non-retryable status, or `reconnectsSoFar` has reached `cap` — an abort
* follows instead). Announced on the failure's `request_end` as `retry_in_ms` so the
* frontend can render a live countdown; shares `reconnectDelayMs` with `backoff`, so the
* announced wait and the actual sleep cannot drift. The caps differ by loop: the turn
* loop passes `maxReconnects`, the compaction loop `compactionMaxReconnects`; `retries` must
* match what the calling loop actually does, or the announced countdown is a lie.
*/
private plannedRetryDelayMs(
outcome: LLMOutcome,
reconnectsSoFar: number,
cap: number,
retries: readonly StopReason[],
): number | undefined {
if (!retries.includes(outcome.status)) return undefined;
if (reconnectsSoFar >= cap) return undefined;
return reconnectDelayMs(
this.reconnectBackoffMs,
this.reconnectBackoffMaxMs,
reconnectsSoFar + 1,
);
}
/** Resolves the in-progress backoff wait early ("retry now"); null when no wait is in progress. */
private wakeBackoff: (() => void) | null = null;
/**
* Skips the in-progress reconnect backoff and fires the next retry immediately (the
* user's "retry now" on the countdown): resolves the current wait as if its timer had
* elapsed — the attempt counter is untouched, so the skipped wait never consumes an
* extra attempt. Returns false (a benign no-op) when no reconnect wait is in progress;
* idempotent under races — the wait settles exactly once whether the timer, a user
* abort, or this skip lands first. Wakes whichever loop is waiting (the turn loop's
* reconnect backoff, or a compaction retry's). Mirrors `steer` as the second
* mid-run nudge hosts can reach through the Session.
*/
skipReconnectWait(): boolean {
const wake = this.wakeBackoff;
if (!wake) return false;
wake();
return true;
}
/**
* Exponential backoff before a reconnect retry (`reconnectDelayMs` of the configured
* base/ceiling; attempt numbering starts at 1); returns false if the user interrupts
* during the backoff — the abort listener also fires mid-wait, so even a 30s ceiling
* wait hands control back immediately — letting the caller proceed to interruption
* cleanup. A "retry now" skip (`skipReconnectWait`) resolves the wait early as true,
* proceeding straight to the retry.
*/
private backoff(attempt: number, signal?: AbortSignal): Promise<boolean> {
const ms = reconnectDelayMs(this.reconnectBackoffMs, this.reconnectBackoffMaxMs, attempt);
return new Promise<boolean>((resolve) => {
if (signal?.aborted) {
resolve(false);
return;
}
// Settles exactly once: the timer, a user abort, and a "retry now" skip may race —
// whichever lands first wins, the rest become no-ops (no double-fire).
let settled = false;
const settle = (proceed: boolean): void => {
if (settled) return;
settled = true;
clearTimeout(timer);
signal?.removeEventListener("abort", onAbort);
this.wakeBackoff = null;
resolve(proceed);
};
const onAbort = (): void => settle(false);
const timer = setTimeout(() => settle(true), ms);
signal?.addEventListener("abort", onAbort, { once: true });
this.wakeBackoff = () => settle(true);
});
}
/**
* Runs one LLM turn: consumes the LLM stream, approving each complete tool_call immediately;
* "allow" runs it concurrently (without blocking further stream consumption/approval), "deny"
* feeds back an aborted output. partial/complete tool_call_output is yielded in completion
* order. Returns all of this turn's tool outputs (for the next turn) and whether it was
* interrupted midway.
* Docs: /docs/agent-loop § "Lifecycle of a turn".
*/
private async *runTurn(
input: OmniMessage[],
approve: ApproveFn,
signal?: AbortSignal,
/** This turn's retry bookkeeping from the caller's reconnect loop: lets request_end announce the NEXT attempt's planned backoff (and announce none once a budget is spent). */
retry: TurnRetryState = { attempts: 0, consecutive: 0 },
preToolUse?: PreToolUseFn,
): AsyncGenerator<OmniMessage, TurnResult> {
const queue = new MergeQueue();
// Tool outputs are collected in **completion order** (for streaming yield to the frontend);
// the tool_calls' **original order** is recorded separately, and reordered back to original
// order when fed into the next LLM turn (async tool calls: feedback order is preserved).
const toolOutputs: OmniMessage[] = [];
const toolCalls: OmniMessage<ToolCallPayload>[] = [];
const callOrder: string[] = [];
// This turn's complete thinking/text segments produced by the model (including partial
// segments finalized on interruption), for carry-over flatten.
const assistantSegments: OmniMessage[] = [];
// This turn's LLM terminal state: taken from streamGenerate's generator return value.
let outcome: LLMOutcome = { status: "completed" };
// Set by the first message the stream yields (see TurnResult.receivedContent).
let receivedContent = false;
// Driver task: consumes the LLM stream + approves one at a time + dispatches tool
// execution. It is itself a producer.
queue.addProducer();
const drive = (async () => {
try {
// Request boundary events (replayability): start is
// emitted when the request is issued, stop carries the terminal state at completion —
// replay mechanically determines from these whether the turn was committed by AgentHub.
const startEvt = requestBegin();
queue.push(startEvt);
await this.write(startEvt);
// Iterate manually to capture the generator's **return value** (LLMOutcome); LLM
// guarantees it never throws.
const level = this.thinkingLevel;
const gen = this.llm.streamGenerate({
newMessages: input,
...(signal ? { signal } : {}),
...(level !== undefined ? { thinkingLevel: level } : {}),
});
for (;;) {
const res = await gen.next();
if (res.done) {
outcome = res.value;
// Non-completed outcomes carry the failure detail onto the event: a retried
// request never produces an abort, so this is the only place observability
// (the errors panel) can learn the real reason (e.g. a quota code). When the
// engine will retry in-run, the planned backoff rides along as retry_in_ms
// (the frontend's live countdown); absent on final failures and completions.
// Mirrors the reconnect loop exactly, or the announced countdown is a lie: an
// attempt that received content restarts the ladder at its first rung, and either
// budget running out means no retry is planned at all.
const retryInMs =
retry.attempts + 1 >= this.maxTurnAttempts
? undefined
: this.plannedRetryDelayMs(
outcome,
receivedContent ? 0 : retry.consecutive,
this.maxReconnects,
RETRY_STATUSES,
);
const stopEvt = requestEnd(outcome.status, {
...(outcome.errorCode !== undefined ? { errorCode: outcome.errorCode } : {}),
...(outcome.errorMessage !== undefined ? { errorMessage: outcome.errorMessage } : {}),
// The authoritative attempt ordinal (1-based, within this retry run): the
// turn's TOTAL attempt count, which never rewinds when received content resets
// the backoff ladder — hosts render "attempt N", and a counter that went
// backwards mid-turn would read as a lost attempt. A clean first-try completion
// stays unstamped so the common case adds no noise.
...(outcome.status !== "completed" || retry.attempts > 0
? { attempt: retry.attempts + 1 }
: {}),
...(retryInMs !== undefined ? { retryInMs } : {}),
});
queue.push(stopEvt);
await this.write(stopEvt);
break;
}
const msg = res.value;
receivedContent = true;
// token_usage means "this Request completed normally": record the context usage /
// Session cumulative counts — stamped onto the message BEFORE it is yielded or
// written, so the stream and the Trace carry the Session series rather than the
// LLM's per-request stand-in — and increment the Session turn count (counted per
// LLM Request, across Tasks; used for compaction threshold checks).
if (this.observeTokenUsage(msg)) {
this.sessionTurns += 1;
// A turn completed: the summary the context opened with is history now.
this.openingSummary = null;
}
queue.push(msg);
await this.write(msg);
// Collect complete thinking/text segments (including partial segments finalized on
// interruption), for carry-over flatten.
if (
isCompleteModelMessage(msg) &&
(msg.payload.type === "thinking" || msg.payload.type === "text")
) {
assistantSegments.push(msg);
}
// Approve as soon as each real, complete tool_call finishes streaming. A tool_call
// synthesized to close out an interruption carries a non-"completed" stop_reason (see
// finishInterrupted): its arguments weren't fully emitted, and it exists only
// for structural closure and observability — it isn't dispatched for execution, isn't
// added to this turn's ledger, and gets no paired output backfilled: such a tool_call
// was never committed to history by AgentHub, so there's nothing to pair. This turn
// must then end with a non-completed outcome (only interruption closure produces such
// a tool_call): a retryable outcome is cleaned up by
// reconnect resending the flatten carry-over, while the run-ending ones
// (aborted/fatal) exit directly.
if (isCompleteModelMessage(msg) && msg.payload.type === "tool_call") {
const tc = msg as OmniMessage<ToolCallPayload>;
if (tc.payload.stop_reason !== "completed") continue;
const toolCallId = tc.payload.tool_call_id;
callOrder.push(toolCallId);
toolCalls.push(tc);
// Already interrupted: stop dispatching new tools, but keep consuming until the LLM
// returns its outcome (the LLM will close out quickly and return aborted).
if (signal?.aborted) continue;
// Pre-tool-use hooks (RunOptions.preToolUse, wired by the Session from the
// Agent's installed hook packages): consulted before the approval boundary,
// every answer recorded as a `hook` event in stream order. A throw collapses
// to no opinion — a broken hook must not decide anything.
let hooked: PreToolUseOutcome | null = null;
if (preToolUse) {
try {
hooked = await preToolUse(tc);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[penguin] preToolUse consult threw: ${message}; ignoring.\n`);
}
if (hooked) {
for (const ev of hooked.events) {
queue.push(ev);
await this.write(ev);
}
}
if (signal?.aborted) continue;
}
// The approval callback is injected externally (RunOptions.approve): any throw
// collapses to deny (conservative), so the exception never escapes the engine —
// otherwise it would propagate through session.run without building carry-over,
// leaving the already-committed tool_use unanswered. A hook decision skips the
// callback: deny refuses without asking, allow approves without asking (the
// Session already gave the command policy the last word on an allow).
let decision: ApprovalDecision;
if (hooked?.decision === "deny" || hooked?.decision === "allow") {
decision = hooked.decision;
} else {
try {
decision = await approve(tc);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[penguin] approve callback threw: ${message}; denying.\n`);
decision = "deny";
}
}
if (signal?.aborted) continue;
// approve is a callback; context_engine emits its decision as an approval_decision
// OmniMessage: pushed to the stream for frontend rendering, and written to Trace.
const decisionMsg = approvalDecision(decision, toolCallId);
queue.push(decisionMsg);
await this.write(decisionMsg);
if (decision !== "allow") {
// Denied: feed back an aborted output immediately, so the already-committed
// tool_use never dangles. One fixed line either way — the wording names the
// decider ("forbidden" is the command policy's answer, via the Session
// wrapper; a hook deny names the hook and carries its reason), and the
// approval_decision event above carries the decision itself.
const denied = toolCallOutput({
output:
hooked?.decision === "deny"
? `Tool call denied by the ${hooked.name ?? "pre_tool_use"} hook${hooked.reason ? `: ${hooked.reason}` : ""}.`
: decision === "forbidden"
? "Tool call denied by policy."
: "Tool call denied by user.",
toolCallId,
stopReason: "aborted",
});
queue.push(denied);
await this.write(denied);
toolOutputs.push(denied);
continue;
}
// Approved: run concurrently, without blocking further consumption of the LLM
// stream or approval of the next tool.
queue.addProducer();
void this.executeOne(tc, queue, toolOutputs, signal, approve).finally(() => {
queue.removeProducer();
});
}
}
} finally {
queue.removeProducer();
}
})();
// Single consumer: yield merged messages one at a time until all producers are done and
// the queue is drained.
for (;;) {
const msg = await queue.next();
if (msg === null) break;
yield msg;
}
// Wait for the driver task to fully finish (state settles).
await drive;
// Feed into the next turn: reordered to the original tool_call order (each tool_call has
// exactly one output, see the executeOne invariant).
const byId = new Map<string, OmniMessage>();
for (const out of toolOutputs) {
const id = (out.payload as { tool_call_id?: string }).tool_call_id;
if (id !== undefined) byId.set(id, out);
}
const orderedOutputs: OmniMessage[] = [];
const seen = new Set<string>();
for (const id of callOrder) {
if (seen.has(id)) continue; // Dedupe: feed back exactly one output per tool_call_id, to preserve pairing
seen.add(id);
const out = byId.get(id);
if (out) orderedOutputs.push(out);
}
return { toolOutputs: orderedOutputs, toolCalls, assistantSegments, receivedContent, outcome };
}
/**
* Executes a single approved tool: streams its partial/complete tool_call_output (through the
* queue), and collects the complete tool_call_output into toolOutputs.
*
* Environment is contracted to handle all errors internally: it guarantees exactly one
* complete `tool_call_output` to close out and never throws. But since
* EnvironmentInterface can be injected by consumers via a public API, if a contract-violating
* exception escapes, this fire-and-forget promise would take down the process with an
* unhandled rejection, and the missing output would leave the already-committed tool_use
* unanswered (the next request gets rejected by the provider) — so a boundary safety net is
* kept here, collapsing a contract-violating exception into a failed output. This guarantees
* exactly one complete output per tool enters toolOutputs, keeping tool_use and tool_result
* paired.
*/
private async executeOne(
toolCall: OmniMessage<ToolCallPayload>,
queue: MergeQueue,
toolOutputs: OmniMessage[],
signal?: AbortSignal,
approve?: ApproveFn,
): Promise<void> {
let completed = false;
try {
for await (const out of this.deps.environment.executeTool({
toolCall,
...(signal ? { signal } : {}),
// Pass through the parent approval callback: run_subagent uses this so the child
// Session inherits the parent Agent's approval mode.
...(approve ? { approve } : {}),
})) {
queue.push(out);
// Nested-session messages carrying an origin: forwarded to the frontend as a stream;
// their content is not written to the parent Trace (the child Session has its own
// Trace). When a direct child session's (origin length 1) session_meta arrives, write a
// subagent pointer event to the parent Trace (recording only the child Session id), so
// reopening the session can recursively expand child Traces — pointers for grandchild
// sessions are recorded by the child Trace itself, so only depth 1 is recognized here.
// Never fed back — a child session's tool_call_output has no pairing with the parent's
// tool_call, and feeding it back by mistake would be rejected by the Provider.
if (out.origin && out.origin.length > 0) {
if (isSessionMeta(out) && out.origin.length === 1) {
await this.write(subagentEvent(out.origin[0]!));
}
continue;
}
await this.write(out);
if (isCompleteModelMessage(out) && out.payload.type === "tool_call_output") {
toolOutputs.push(out);
completed = true;
}
}
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (completed) {
// Thrown only after the complete output was ready: pairing is intact, so just warn.
process.stderr.write(`[penguin] environment threw after tool output: ${message}\n`);
return;
}
const failed = toolCallOutput({
output: `[tool error] ${message}`,
toolCallId: toolCall.payload.tool_call_id,
stopReason: "fatal",
});
queue.push(failed);
await this.write(failed);
toolOutputs.push(failed);
}
}
/** Max turns reached: emits a failed notice (streaming fragments + complete text) for CLI/frontend rendering. */
private async *emitMaxTurns(): AsyncGenerator<OmniMessage> {
// Reduce leading newlines: avoid stacking extra newlines before the text (comment #15).
const text = `[reached max turns (${this.maxTurns}); stopping]`;
const partials = [
partialText("start"),
partialText("delta", text),
partialText("stop", "", "fatal"),
];
for (const partial of partials) {
yield partial;
await this.write(partial);
}
const note = assistantText(text, "fatal");
yield note;
await this.write(note);
}
// -------------------------------------------------------------------------
// Context compaction
// -------------------------------------------------------------------------
/**
* Re-reads the live compaction settings, if the host supplies a provider. Called at every
* point the engine is about to decide something from them — the post-request checkpoint and
* the two entries into a compaction — so a threshold, turn count, mode or prompt edited on
* disk applies to the conversation that is running.
*
* Only refreshes an existing baseline: a Session with no `compaction` in its deps has no
* compaction capability, and a provider must not conjure one mid-run (see
* ContextEngineDeps.readCompaction). A read that throws keeps the settings already in force
* and warns once — the alternative, failing the run because a config file was momentarily
* unreadable, is worse than compacting at the previous threshold.
*/
private async refreshCompaction(): Promise<void> {
if (!this.compaction || !this.deps.readCompaction) return;
try {
this.compaction = await this.deps.readCompaction();
} catch (e) {
if (this.compactionReadWarned) return;
this.compactionReadWarned = true;
const message = e instanceof Error ? e.message : String(e);
process.stderr.write(
`[penguin] compaction settings could not be re-read: ${message}; keeping the settings in force.\n`,
);
}
}
/**
* Checks the compaction threshold: triggers once context usage (the most recent
* token_usage's request.total) or the Session cumulative turn count **reaches** the threshold
* (>=) — e.g. maxSessionTurns=1 compacts as soon as turn 1 completes, without waiting for the
* next Task; when both are configured, either reaching its threshold triggers compaction.
* Never triggers when compaction is not configured.
* Docs: /docs/agent-loop § "Compaction".
*/
private compactionTrigger(): CompactionReason | null {
const settings = this.compaction;
if (!settings || !this.deps.openNextContext) return null;
if (settings.maxContextLength > 0 && this.lastRequestTotal >= settings.maxContextLength) {
return "context";
}
if (settings.maxSessionTurns > 0 && this.sessionTurns >= settings.maxSessionTurns) {
return "turns";
}
return null;
}
/**
* Records context usage from a token_usage event and stamps the engine-authored session
* series onto it; returns whether the message is a token_usage. The engine is the single
* author of `token_usage.session`: the LLM reports per-request usage only (its lifetime is
* one model context), and this method — on the turn path and the compaction path alike —
* accumulates the request counts and overwrites the payload's `session` before the
* message is yielded or written.
*/
private observeTokenUsage(msg: OmniMessage): boolean {
if (msg.type !== "event_msg") return false;
const payload = msg.payload as Partial<TokenUsagePayload>;
if (payload.type !== "token_usage") return false;
if (payload.request) {
this.lastRequestTotal = payload.request.total;
this.lastSessionTokens = addTokenCounts(this.lastSessionTokens, payload.request);
(payload as TokenUsagePayload).session = this.lastSessionTokens;
}
return true;
}
/**
* `discard` compaction: sends no compaction request, simply discards the old context —
* swaps in a new LLM object and splits a new Trace file, with the next turn's input used
* unchanged as the new object's first input. Only runs at a Task boundary (deferred by the
* caller while mid-Task).
*/
private async *discardContext(reason: CompactionReason): AsyncGenerator<OmniMessage> {
yield* this.emitCompactionBegin(reason, "discard");
yield* this.emitCompactionEnd(reason, "discard", "completed");
yield* this.startNewContext();
}
/**
* `summarize` compaction: appends the compaction Prompt to the **old** LLM object (first
* folding in all of this turn's tool results when mid-Task, to keep tool_use/tool_result
* pairing), then extracts the `[summary]` and wraps it as `[context_summary]` user text. The
* compaction request carries the session's toolset **unchanged** — the request prefix must
* stay byte-identical to ordinary turns so the provider's prompt cache remains valid;
* compaction runs exactly when the context is largest, where re-billing the whole
* transcript uncached costs tens of times more (issue #84 — this is why tools are *not*
* omitted and no `tool_choice` override is used). The
* compaction request's raw messages are not pushed to the Human output stream, with two
* exceptions between the paired compaction events: every attempt's `token_usage` (so the
* frontend stats and the server's usage records count the compaction's true spend,
* rejected attempts included), and the thinking and summary text being generated, as
* ordinary `partial_thinking`/`thinking` and `partial_text`/`text` messages (issue #290 —
* see runCompactionRequest); everything is written to the old Trace as before. Compaction
* succeeds only with a **valid summary** — non-empty extracted
* text and no tool calls in the response. Everything short of that is one kind of failure,
* handled exactly like an ordinary LLM request's (issue #170): an unusable committed
* response (empty summary, or tool calls — answered with synthesized failed outputs and
* retried behind a corrective note, see the loop body) and the retryable failures all
* reconnect under the one `compactionMaxReconnects` budget
* (defaulting to the turn loop's budget and ladder — see RETRY_STATUSES); only `fatal` stops
* without retrying. Once the budget is exhausted the compaction fails; on failure/abort, the original
* context and Trace index are kept — it does not fall back to discard. The first **committed**
* attempt absorbs `pendingToolOutputs` into the old context's history (issue #85): later
* resends carry only the repairs and the Prompt, and the result's `committed` flag tells
* the caller the folded input must not be resent even though the compaction did not complete.
* Docs: /docs/agent-loop § "Compaction".
*/
private async *summarizeContext(
reason: CompactionReason,
pendingToolOutputs: OmniMessage[],
signal?: AbortSignal,
): AsyncGenerator<OmniMessage, CompactionResult> {
// Already refreshed: both entries into a compaction — the post-request checkpoint and
// `compact()` — re-read the live settings before choosing the mode that lands here, so the
// prompt below comes from the same read as that decision rather than a second one.
const settings = this.compaction!;
yield* this.emitCompactionBegin(reason, "summarize");
// Compaction request input: this turn's tool results (mid-Task) or leftover interruption
// carry-over, appended to the old object together with the compaction Prompt as one user
// turn — keeping tool_use/tool_result pairing intact, since an unanswered tool_use would
// get the compaction request itself rejected (issue #33). The compaction exchange is
// written to the old Trace (traceable but not pushed to the user); tool results were
// already written when executed and aren't recorded again, while carry-over's
// not-yet-written synthetic content (flatten text, backfilled placeholders) and the
// compaction Prompt are written now.
const prompt = userText(settings.prompt);
// The resend base: shrinks to the Prompt alone once an attempt commits — the folded turn
// input then lives in the old LLM object's history, and resending it would make strict
// providers reject the request over duplicate/stale tool_results (issue #85).
let base = [...pendingToolOutputs, prompt];
let input = base;
await this.write(prompt);
// Whether the folded input was absorbed into the old object's history — true once any
// attempt was committed by AgentHub (only `completed` commits: a retryable failure ends
// an incomplete stream, and fatal/aborted throw or cut off before a clean end — none of
// those reach the stateful commit). Returned as
// `committed`: the callers' two-case carry rule branches on it.
let committed = false;
// Synthesized outputs answering the latest unusable attempt's tool calls, not yet carried
// by a committed request: prepended to the retry input, and stashed as carry-over should
// the compaction be abandoned first (see stashRepairs).
let pendingRepairs: OmniMessage[] = [];
// One retry budget for every failure: an unusable committed response (empty summary /
// tool calls) counts exactly like a retryable failure (issue #170) — same counter, same
// exponential ladder — and only `fatal` stops without retrying.
let reconnects = 0;
// The compaction_end event's share of the RetryDetail block (also what the server's
// error record carries): the final attempt ordinal, and the last failure's detail.
let attempts = 0;
let lastError: string | undefined;
let lastErrorCode: ErrorCode | undefined;
for (;;) {
if (signal?.aborted) {
this.stashRepairs(pendingRepairs);
yield* this.emitCompactionEnd(
reason,
"summarize",
"aborted",
attempts > 0 ? { attempt: attempts } : undefined,
);
return { status: "aborted", committed };
}
const attempt = yield* this.runCompactionRequest(input, signal, reconnects);
attempts += 1;
// Every attempt's token_usage is pushed to the Human output stream (already written to
// Trace in runCompactionRequest, so it's only yielded here, never rewritten): the frontend
// stats and the server's usage records then carry the compaction's true spend — failed
// attempts burn real tokens (issue #170), and surfacing only the adopted attempt's usage
// understated the cost center.
if (attempt.usage) yield attempt.usage;
// A committed-but-unusable response (empty summary or tool calls): its retry input must
// be rebuilt below — repairs + corrective note + Prompt — instead of resent unchanged.
let unusable = false;
if (attempt.status === "completed") {
// The attempt was committed by AgentHub, so whatever its input carried — including
// repairs synthesized for a previous rejection — is now in history and must not be
// resent. The first commit absorbs the folded turn input: the base shrinks to the
// Prompt alone.
committed = true;
base = [prompt];
pendingRepairs = [];
// A completed response counts as a compaction success only when it is a **usable
// summary**: the extracted text is non-empty and the response called no tool. The
// extraction itself stays lenient (output without a [summary] tag is used verbatim),
// but committing an empty `[context_summary]` would discard the whole context and
// lose the task state, and a tool-calling response is not a summary at all — with the
// session's tools offered (prefix-cache invariant), a model deciding to use one is a
// live possibility, not just a hallucination (issue #83).
const summaryText = extractSummary(attempt.text);
if (summaryText !== "" && attempt.toolCalls.length === 0) {
const summary = userText(buildContextSummaryText(summaryText));
yield* this.emitCompactionEnd(reason, "summarize", "completed", { attempt: attempts });
yield* this.startNewContext();
this.openingSummary = summary;
return { status: "completed", summary, committed };
}
// Not a summary — one more failed attempt, sharing the reconnect budget below. Tool
// calls were never dispatched, yet the assistant turn holding them IS
// committed on the live LLM object — leaving them unanswered would get every
// subsequent request rejected by the provider (unanswered tool_use, issue #33): the
// exact state this file's other safety nets exist to prevent. Answer each call with a
// synthesized failed output (the same shape executeOne uses), written to Trace so
// resume replays the identical pairing, and prepended to the retry input so the
// provider sees tool_use/tool_result paired. The empty-text case needs no repair:
// that committed turn is plain assistant text/thinking, and re-sending the compaction
// Prompt on top of it is structurally sound.
unusable = true;
// An unusable summary is a malformed response for this request's purpose.
lastErrorCode = "malformed";
lastError =
attempt.toolCalls.length > 0
? "the response called tools instead of writing a summary"
: "the response contained no usable summary";
pendingRepairs = attempt.toolCalls.map((tc) =>
toolCallOutput({
output: "[tool error] the compaction request expects a summary, not tool calls",
toolCallId: tc.payload.tool_call_id,
stopReason: "fatal",
}),
);
for (const repair of pendingRepairs) await this.write(repair);
} else if (attempt.status === "aborted") {
this.stashRepairs(pendingRepairs);
yield* this.emitCompactionEnd(reason, "summarize", "aborted", { attempt: attempts });
return { status: "aborted", committed };
} else if (attempt.status === "fatal") {
// `fatal` never retries: a definitive rejection or a dead credential doesn't heal
// on a ladder. The compaction ends `fatal` too — the next trigger will hit the
// same wall until a config or credential change; the original context is kept and
// the error detail rides the compaction_end for the host to surface.
this.stashRepairs(pendingRepairs);
yield* this.emitCompactionEnd(reason, "summarize", "fatal", {
attempt: attempts,
...(attempt.errorCode !== undefined ? { errorCode: attempt.errorCode } : {}),
...(attempt.errorMessage !== undefined ? { errorMessage: attempt.errorMessage } : {}),
});
return {
status: "fatal",
committed,
...(attempt.errorCode !== undefined ? { errorCode: attempt.errorCode } : {}),
...(attempt.errorMessage !== undefined ? { errorMessage: attempt.errorMessage } : {}),
};
} else {
// Retryable failure: keep its cause and detail as the last error of record.
lastError = attempt.errorMessage;
lastErrorCode = attempt.errorCode;
}
// One failure path for everything else — unusable summaries and retryable failures
// (never committed by AgentHub) — treated like an
// ordinary LLM request's failures: the same budget (defaulting to the shared
// maxReconnects, issue #170) and the same exponential ladder. An unusable attempt's
// request_end carries status completed, for which no retry_in_ms is announced — the
// backoff wait still happens.
if (reconnects >= this.compactionMaxReconnects) {
// Retries exhausted on retryable failures (transport faults and unusable
// summaries alike): the compaction ends `retryable` — abandoned this time, and
// the standing trigger makes it up at the next opportunity.
this.stashRepairs(pendingRepairs);
yield* this.emitCompactionEnd(reason, "summarize", "retryable", {
attempt: attempts,
...(lastErrorCode !== undefined ? { errorCode: lastErrorCode } : {}),
...(lastError !== undefined ? { errorMessage: lastError } : {}),
});
return {
status: "retryable",
committed,
...(lastErrorCode !== undefined ? { errorCode: lastErrorCode } : {}),
...(lastError !== undefined ? { errorMessage: lastError } : {}),
};
}
reconnects += 1;
const ok = await this.backoff(reconnects, signal);
if (!ok) {
this.stashRepairs(pendingRepairs);
yield* this.emitCompactionEnd(reason, "summarize", "aborted", { attempt: attempts });
return { status: "aborted", committed };
}
if (unusable) {
// Rebuild from the (shrunken) base rather than appending: everything the unusable
// attempt's input carried is committed — the live object's history can only grow, so
// the retry appends the fresh repairs, a corrective note, and the Prompt. The note
// (written to Trace like the Prompt, and only when a retry actually follows) is what
// breaks the copy-my-own-mistake loop: the model's freshest example is its committed
// bad output, and rewriting history to hide it would invalidate the provider's
// prompt cache (issue #84) — correcting forward is the one cache-safe option
// (issue #170). Retryable failures skip this: nothing was committed, so their input
// is resent unchanged (any pending repairs included).
const guidance = userText(SUMMARY_RETRY_GUIDANCE);
await this.write(guidance);
input = [...pendingRepairs, guidance, ...base];
}
}
}
/**
* Holds synthesized repair outputs as carry-over when a summarize compaction is abandoned
* (failed/aborted) while the latest rejected attempt's tool calls are still unanswered: the
* next run's first request (or the next manual compaction, which folds carry-over in) sends
* them ahead of everything else, completing the tool_use/tool_result pairing on the live
* LLM object that the provider would otherwise reject every subsequent request over. The
* repairs were already written to Trace at synthesis time, and carry-over is never re-written
* to Trace at send time, so no duplicate Trace entries arise.
*/
private stashRepairs(repairs: OmniMessage[]): void {
if (repairs.length === 0) return;
this.pendingCarryOver = [...repairs, ...this.pendingCarryOver];
}
/**
* Issues one compaction request — an ordinary LLM Request through the same object and the
* same frozen config as every other turn (the toolset is deliberately identical: a changed
* tool list would change the request prefix and invalidate the provider's prompt cache at
* the moment the context is largest, issue #84). Consumes the old LLM object's streamed
* output; raw model messages are **not pushed to the Human output stream** (`token_usage`
* is captured and handed back via the return value for summarizeContext to yield), with
* one exception: the thinking and the text being generated ride the stream as their own
* ordinary `partial_thinking`/`thinking` and `partial_text`/`text` messages (issue #290)
* so the frontend can show the compaction request working while it runs — readers already
* treat model messages between the paired compaction events as compaction-internal, and
* history rebuild reads the identical content back from the span's complete assistant
* messages. Complete
* messages and events are written to the old Trace; complete text segments are collected as
* the compaction output, and `toolCalls` collects the response's real tool requests (never
* dispatched — summarizeContext rejects such a response as not-a-summary and answers each
* call with a synthesized failed output).
* Token usage is counted into the Session
* cumulative totals (accumulated and stamped onto every token_usage via observeTokenUsage).
*/
private async *runCompactionRequest(
input: OmniMessage[],
signal?: AbortSignal,
/** Transport retries already performed by the compaction loop (its request_end announces the next planned backoff too). */
reconnectsSoFar = 0,
): AsyncGenerator<
OmniMessage,
{
status: StopReason;
text: string;
toolCalls: OmniMessage<ToolCallPayload>[];
usage: OmniMessage | null;
/** Classified cause and error detail (LLMOutcome) on non-completed statuses — become compaction_end.error_code / error_message when this failure ends the compaction. */
errorCode?: ErrorCode;
errorMessage?: string;
}
> {
// The compaction request is itself an ordinary Request, emitting paired request events —
// written to the (old) Trace only, not pushed to the stream, keeping the compaction process
// invisible to Human.
await this.write(requestBegin());
// The Session's pinned thinking level, read live and carried exactly as a turn carries it
// (see the `thinkingLevel` field): the level is the soft-limited per-request parameter, so
// one Session never has two levels in flight at once. Were this request left on the level
// the context opened at while the turns around it run on the pin, a provider that reads the
// level as a thinking mode would see the mode change mid-conversation — and DeepSeek
// rejects a request whose current tool-call chain replays a turn that carries no chain of
// thought. The strict-tier prefix this request does hold identical to a turn's is its
// system prompt and toolset; the level is a request parameter, not part of either.
const level = this.thinkingLevel;
const gen = this.llm.streamGenerate({
newMessages: input,
...(signal ? { signal } : {}),
...(level !== undefined ? { thinkingLevel: level } : {}),
});
let text = "";
const toolCalls: OmniMessage<ToolCallPayload>[] = [];
let usage: OmniMessage | null = null;
// Whether this attempt streamed any partial_text / partial_thinking content: real LLM
// objects stream the summary (and the thinking ahead of it) as partial fragments
// (forwarded verbatim), and the complete message that follows must then stay off the
// stream or consumers would see the content twice; an implementation that yields only
// complete messages streams those instead. Tracked per kind, so a model that streams its
// thinking but delivers its text whole still gets that text forwarded once.
let sawPartialText = false;
let sawPartialThinking = false;
for (;;) {
const res = await gen.next();
if (res.done) {
// Same failure-detail + planned-backoff pass-through as the turn loop's
// request_end, under the compaction cap. Compaction request events are written to
// the old Trace only (never streamed), so retry_in_ms lands in the Trace record —
// no live countdown renders for compaction; the frontend only sees the
// compaction event pair. A rejected summary ends `completed`, for which
// plannedRetryDelayMs yields nothing — rejection resends are immediate (see
// summarizeContext), so no wait is ever announced for them.
const retryInMs = this.plannedRetryDelayMs(
res.value,
reconnectsSoFar,
this.compactionMaxReconnects,
RETRY_STATUSES,
);
await this.write(
requestEnd(res.value.status, {
...(res.value.errorMessage !== undefined
? { errorMessage: res.value.errorMessage }
: {}),
// Same stamping rule as the turn loop; for compaction the ordinal counts every
// retry kind (transport and unusable-summary alike share one budget).
...(res.value.status !== "completed" || reconnectsSoFar > 0
? { attempt: reconnectsSoFar + 1 }
: {}),
...(retryInMs !== undefined ? { retryInMs } : {}),
}),
);
return {
status: res.value.status,
text,
toolCalls,
usage,
...(res.value.errorCode !== undefined ? { errorCode: res.value.errorCode } : {}),
...(res.value.errorMessage !== undefined ? { errorMessage: res.value.errorMessage } : {}),
};
}
const msg = res.value;
// Stamped with the Session series before the write, exactly like a turn's (runTurn).
if (this.observeTokenUsage(msg)) usage = msg;
await this.write(msg);
// Streamed compaction progress (issue #290): the request's thinking and the summary's
// own text ride the output stream between the paired compaction events —
// partial_thinking / partial_text fragments verbatim (all three phases, so the server's
// live tail opens and closes its fragment and a join mid-compaction is seeded with the
// accumulated prefix), or the complete thinking / text when no partial of that kind
// carried content (implementations that yield only complete messages) — never both,
// so consumers see each character once. The request's other raw messages (the
// compaction Prompt, request events) stay Trace-only as before. Rejected attempts
// stream too: the frontend shows whatever the compaction request is really producing,
// and history rebuild reads the same content back from the span's complete assistant
// messages.
{
const p = msg.payload as { type?: string; text?: string; thinking?: string };
if (p.type === "partial_text") {
if (typeof p.text === "string" && p.text !== "") sawPartialText = true;
yield msg;
} else if (p.type === "partial_thinking") {
if (typeof p.thinking === "string" && p.thinking !== "") sawPartialThinking = true;
yield msg;
}
}
if (isCompleteModelMessage(msg)) {
if (msg.payload.type === "text") {
const body = (msg.payload as TextPayload).text;
text += body;
if (!sawPartialText && body !== "") yield msg;
} else if (msg.payload.type === "thinking") {
// Forwarded for the banner only — the thinking is never summary material (the
// extraction reads `text` alone) — and a fidelity-only blank body has nothing to
// show.
const body = (msg.payload as ThinkingPayload).thinking;
if (!sawPartialThinking && body !== "") yield msg;
} else if (msg.payload.type === "tool_call") {
// Same filter as the turn loop: a tool_call synthesized to close out an interruption
// carries a non-completed stop_reason — it is structural closure, not a real request,
// and gets no paired output.
const tc = msg as OmniMessage<ToolCallPayload>;
if (tc.payload.stop_reason === "completed") toolCalls.push(tc);
}
}
}
}
/**
* Opens a new model context after successful compaction: swaps in the LLM object
* `openNextContext` returns (seeding it with the Session cumulative token counts), adopts
* whatever the opened context brings — its session_meta and toolset records for the rotated
* Trace file's head, its engine settings — and resets the Session turn count and context
* usage counter. The records the opener emits while opening (its MCP connect pair, its
* tool_list_ready) are yielded live as they come, so a slow connect is never a silent gap.
* Trace **does not** split files immediately — that's deferred until the next message that
* needs writing, when it rotates and opens with the context's session_meta and records (see
* `write`), avoiding an empty file if no further messages follow the compaction; a model
* switch opens the file right after this returns instead (see `switchContext`).
*/
private async *startNewContext(): AsyncGenerator<OmniMessage> {
// The opener publishes records through a callback; a merge queue turns them into this
// generator's live yields while the opener is still running.
const { queue, result: opening } = pumpOpener((emit) => this.deps.openNextContext!({ emit }));
const records: OmniMessage[] = [];
for (;;) {
const msg = await queue.next();
if (msg === null) break;
records.push(msg);
yield msg;
}
// An opener that throws (the Agent State could not be assembled) propagates out of the
// run with the engine untouched: the old context stays current and no rotation is
// pending, so the next trigger compacts again from a consistent state.
const opened = await opening;
this.pendingTraceRotation = true;
this.llm = opened.llm;
if (opened.sessionMeta) this.contextMeta = opened.sessionMeta;
if (records.length > 0) this.contextRecords = records;
if (opened.maxTurns !== undefined) this.maxTurns = opened.maxTurns;
// The new context's baseline. A `readCompaction` provider re-reads the same file at the
// next checkpoint and agrees with it; what this settles is the Session that has no
// provider, where the rotation is still the only way compaction settings change.
if (opened.compaction) this.compaction = opened.compaction;
this.sessionTurns = 0;
this.lastRequestTotal = 0;
// First-run records no run has written yet describe the context this one replaces: they
// are dropped with it rather than written into this context's file.
this.pendingBootstrapRecords = null;
// Lets compactability() distinguish "just compacted" from "hasn't chatted yet" — both have
// sessionTurns === 0, but they mean two completely different things to the user (being told
// "no completed conversation turns yet" right after compacting is as good as saying nothing).
this.fromCompaction = true;
}
/** Yields and records a compaction start event (carrying reason/mode/current context usage/Session cumulative turns). */
private async *emitCompactionBegin(
reason: CompactionReason,
mode: CompactionMode,
): AsyncGenerator<OmniMessage> {
const msg = compactionBegin({
reason,
mode,
context: this.lastRequestTotal,
turns: this.sessionTurns,
});
yield msg;
await this.write(msg);
}
/** Yields and records a compaction stop event (carrying the result status — non-completed means compaction was abandoned — plus its share of the RetryDetail block: final attempt ordinal, and the last error detail on failures). */
private async *emitCompactionEnd(
reason: CompactionReason,
mode: CompactionMode,
status: StopReason,
detail?: { attempt?: number; errorCode?: ErrorCode; errorMessage?: string },
): AsyncGenerator<OmniMessage> {
const msg = compactionEnd({ reason, mode, status, ...detail });
yield msg;
await this.write(msg);
}
/** User interruption: emits an abort event carrying the machine-readable cause. Cleanup/resending is managed centrally by `run` via carry-over; the LLM history is never touched again. */
private async *emitAbort(
errorCode: "user_abort" | "backoff_interrupted" | "compaction_interrupted",
): AsyncGenerator<OmniMessage> {
const msg = abortEvent(errorCode);
yield msg;
await this.write(msg);
}
/**
* Builds the interruption resend content (carry-over, interruption cleanup)
* based on the LLM's terminal state. Used only for the **exit** cleanup of the statuses that
* end the run: `aborted` and `fatal` (a retried `retryable` does not reach here, and neither
* does reconnect retry: retry input is assembled by withRetriedTurns, appending
* `[turn_retried]` with the failed attempt's output, distinct from the user-interruption
* `[turn_aborted]`):
* - Model output completed (case A, outcome=completed): AgentHub already committed an
* assistant turn containing `tool_call`, so it can only be resent as a structured
* `tool_call_output` to pair with it (cannot flatten, or the already-committed tool_call
* would be left unanswered and rejected).
* - Model output incomplete (case B): the `tool_call_output` in this turn's input (paired
* with the previous completed turn) is kept as-is; the text input and this turn's
* thinking/text/tool call/result are flattened into a single `[turn_aborted]` plain-text
* user message.
* Docs: /docs/agent-loop § "Interruption and carry-over".
*/
private buildCarryOver(attemptInput: OmniMessage[], turn: TurnResult): OmniMessage[] {
if (turn.outcome.status === "completed") {
// Case A: every **committed** tool_call must have a paired output. If execution was
// interrupted and some tool_calls were committed but never dispatched/completed, backfill
// an interrupted-state placeholder for each, avoiding an unanswered tool_use in the next
// turn that the provider would reject.
const haveIds = new Set(
turn.toolOutputs.map((o) => (o.payload as { tool_call_id?: string }).tool_call_id),
);
const backfill = turn.toolCalls
.filter((tc) => !haveIds.has(tc.payload.tool_call_id))
.map((tc) =>
toolCallOutput({
output: "[interrupted: tool aborted by user]",
toolCallId: tc.payload.tool_call_id,
stopReason: "aborted",
}),
);
// Placeholders are sent to the model only and not written to Trace (synthetic carry-over
// isn't persisted); resumption replay re-synthesizes placeholders as needed to guarantee
// pairing (pairing fallback). Real outputs were already
// written when produced.
return backfill.length ? [...turn.toolOutputs, ...backfill] : turn.toolOutputs;
}
return this.flattenCarryOver(
attemptInput,
turn.assistantSegments,
turn.toolCalls,
turn.toolOutputs,
);
}
/**
* Case B: flattens this attempt's input and its produced content into carry-over. Structured
* `tool_call_output` in the input (paired with the previous completed turn) is kept as-is;
* everything else (text input, model thinking/text, this attempt's tool calls/results) is
* transcribed into a single `[turn_aborted]` plain-text user message (includes all
* completed and incomplete messages, including partial thinking/text). If the input text is
* itself already a `[turn_aborted]` block (from a previous attempt or a previous run's
* carry-over), its content is unwrapped and merged in, keeping a single-level structure.
*
* TODO(multimodal): only text input is currently kept — `image_url` / `inline_data` input is
* lost during flatten (the `[turn_aborted]` structure has no corresponding transcription yet);
* multimodal carry-over support to be added later.
*/
private flattenCarryOver(
attemptInput: OmniMessage[],
assistantSegments: OmniMessage[],
toolCalls: OmniMessage<ToolCallPayload>[],
toolOutputs: OmniMessage[],
): OmniMessage[] {
const structured = attemptInput.filter(
(m) => (m.payload as { type?: string }).type === "tool_call_output",
);
const textInputs = attemptInput.filter((m) => (m.payload as { type?: string }).type === "text");
const flattened = userText(
this.buildTurnAbortedText(textInputs, assistantSegments, toolCalls, toolOutputs),
);
// flatten is sent to the model only and not written to Trace (synthetic carry-over isn't
// persisted): resumption replay resends the discarded turn's **original input** as-is
// (best-effort), with no dependency on this synthetic message.
return [...structured, flattened];
}
/** Transcribes the interrupted turn's input, model thinking/text, and tool calls/results into a single `[turn_aborted]` plain-text block. */
private buildTurnAbortedText(
textInputs: OmniMessage[],
assistantSegments: OmniMessage[],
toolCalls: OmniMessage<ToolCallPayload>[],
toolOutputs: OmniMessage[],
): string {
const lines: string[] = [];
for (const m of textInputs) {
const t = (m.payload as TextPayload).text;
// If this text is itself already a synthetic block — a previous run's `[turn_aborted]`,
// or this turn's reconnect-appended `[turn_retried]` — extract its inner lines and merge
// them in directly, avoiding layered nesting / unbounded growth (keeping a single-level
// structure).
const inner = unwrapSyntheticBlock(t);
if (inner !== null) {
if (inner) lines.push(inner);
} else {
lines.push(transcribeUserInput(t));
}
}
lines.push(...transcribeTurnLines(assistantSegments, toolCalls, toolOutputs));
return buildTurnAbortedBlock(lines);
}
/**
* Assembles the reconnect retry input: the original input is kept as-is (structure and
* multimodal content preserved), with a `[turn_retried]` text appended at the end carrying
* each failed attempt's thinking/text and tool calls/results produced so far; if nothing has
* been produced yet, it's just the original input. The synthetic message is sent to the model
* only and not written to Trace (same rule as flatten carry-over).
* Docs: /docs/agent-loop § "Automatic reconnect".
*/
private withRetriedTurns(input: OmniMessage[], failedTurns: TurnResult[]): OmniMessage[] {
const lines = failedTurns.flatMap((t) =>
transcribeTurnLines(t.assistantSegments, t.toolCalls, t.toolOutputs),
);
if (lines.length === 0) return input;
return [...input, userText(buildTurnRetriedBlock(lines))];
}
/**
* Performs the deferred Trace rotation when one is pending: splits the file and opens it with
* the current context's session_meta and records (its MCP connect pair, if any, and its
* toolset). Best-effort like every Trace write. Reached through `write` by the first message
* after a compaction, and directly by `switchContext`, which opens the file at once.
*/
private async rotateIfPending(): Promise<void> {
const trace = this.deps.trace;
if (!trace || !this.pendingTraceRotation) return;
this.pendingTraceRotation = false;
try {
if (trace.rotate) await trace.rotate();
if (this.contextMeta) await trace.write(this.contextMeta);
for (const record of this.contextRecords) await trace.write(record);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[trace] rotate failed: ${message}\n`);
}
}
/**
* Trace writes are **best-effort**: observability should never interrupt the ReAct
* loop, so write failures only warn rather than throw. The first write after compaction first
* performs the deferred Trace rotation (see `rotateIfPending`).
*/
private async write(msg: OmniMessage): Promise<void> {
await this.rotateIfPending();
if (!this.deps.trace) return;
try {
await this.deps.trace.write(msg);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[trace] write failed: ${message}\n`);
}
}
}
/** Transcribes the model's produced thinking/text and tool calls/results into tagged lines (shared by `[turn_aborted]`/`[turn_retried]`). */
function transcribeTurnLines(
assistantSegments: OmniMessage[],
toolCalls: OmniMessage<ToolCallPayload>[],
toolOutputs: OmniMessage[],
): string[] {
const lines: string[] = [];
// The model's produced thinking/text (including partial segments finalized on interruption),
// written in production order.
for (const seg of assistantSegments) {
const p = seg.payload as { type?: string };
if (p.type === "thinking") {
lines.push(transcribeThinking((seg.payload as ThinkingPayload).thinking));
} else if (p.type === "text") {
lines.push(transcribeText((seg.payload as TextPayload).text));
}
}
for (const tc of toolCalls) {
const p = tc.payload;
lines.push(transcribeToolCall(p.name, p.tool_call_id, p.arguments));
}
for (const out of toolOutputs) {
const p = out.payload as ToolCallOutputPayload;
lines.push(transcribeToolCallOutput(p.tool_call_id, p.stop_reason ?? "completed", p.output));
}
return lines;
}