A local-first multi-agent app development platform, built on PenguinHarness
/**
* Session — a continuous conversation context under the same Agent and Workspace.
*
* Human is the SDK's input/output boundary: there is no "Human
* implementation/interface".
* - Input: the OmniMessage list (Prompt) passed to `run(newMessages, opts?)`, plus the abort
* signal `signal` and the per-call approval callback `approve` in `opts`;
* - Output: `run` streams OmniMessage via an async generator.
*
* Approval is a **within-turn interaction**: as soon as a tool_call finishes streaming, `approve`
* is requested immediately, and it executes if allowed. Approvals for multiple tools happen one
* at a time, but execution doesn't block the generation/approval of subsequent tools (execution
* can overlap). GenerativeModel maintains history across turns/Tasks. A Task ends when a turn no
* longer produces a tool_call (final reply).
*
* Rendering tool calls is not Session/core's responsibility: the CLI / Web frontend renders it
* from the streamed OmniMessage on its own.
* Docs: /docs/agent-loop; /docs/interfaces § "The Human boundary".
*/
import {
abortEvent,
buildBackgroundTaskDoneMessage,
mcpConnectEnd,
sessionMeta,
userText,
} from "./omnimessage/index.js";
import type {
OmniMessage,
SessionMetaMessage,
SessionMetaPayload,
StopReason,
} from "./omnimessage/index.js";
import { stripLeadingMarkerBlocks } from "./omnimessage/markers/index.js";
import type { ModelRef } from "./state/project-config.js";
import { sameModelRef } from "./state/project-config.js";
import { imagesToScratchpadPaths } from "./internal/session-support.js";
import { runStopHooks } from "./hooks/stop-hook.js";
import type { HookSubagentSpawner, SessionHooks, StopHook } from "./hooks/stop-hook.js";
import { runPreToolUseHooks } from "./hooks/tool-hook.js";
import type { PreToolUseHook } from "./hooks/tool-hook.js";
import { runUserPromptHooks } from "./hooks/prompt-hook.js";
import type { UserPromptHook, UserPromptHookResult } from "./hooks/prompt-hook.js";
import { pumpOpener } from "./internal/merge-queue.js";
import type {
ApproveFn,
RunCutoff,
BackgroundCommandInfo,
BackgroundSubagentInfo,
SubagentMessageOptions,
SubagentMessageOutcome,
BackgroundTaskDoneEvent,
EnvironmentInterface,
LLMInterface,
ThinkingLevelName,
ToolDetachResult,
ToolPermission,
} from "./interfaces/index.js";
import { vetoForToolCall, withCommandPolicy } from "./internal/command-policy.js";
import type { CommandPolicySource } from "./internal/command-policy.js";
import { generateTitleWithLLM } from "./internal/session-title.js";
import type { SessionTitleResult } from "./internal/session-title.js";
import { compactAvailability, ContextEngine } from "./engine/context-engine.js";
import type {
CompactAvailability,
CompactionSettings,
EngineInitialState,
OpenContextOptions,
OpenedContext,
RunOptions,
SwitchFailurePolicy,
TraceSink,
} from "./engine/context-engine.js";
/**
* A context as the composition layer opens it for a Session: the engine's
* {@link OpenedContext}, plus the hooks that context runs with. Hook packages are read when
* a model context opens, like the rest of the Agent State, so a rotation brings its own
* set; the engine never sees them. Nor does it see whether the context's model has vision:
* the image fold is the Session's own.
*/
export interface SessionOpenedContext extends OpenedContext {
/** The opened context's hooks, replacing the Session's whole set. Absent = the Session keeps the ones it has (an embedder that registered in-process hooks and rotates without re-reading any). */
hooks?: SessionHooks;
/** Whether the opened context's model accepts image input (see SessionConfig.modelHasVision). Absent = as before. */
modelHasVision?: boolean;
}
/**
* What `SessionConfig.openNextContext` is called with: the engine's options, plus the model a
* switch in flight opens the context on (see {@link Session.switchModel}) — absent for every
* other rotation, which keeps the model the closing context ran on. The opener resolves the
* reference against the Project config as it is on disk.
*/
export interface SessionOpenContextOptions extends OpenContextOptions {
modelRef?: ModelRef;
}
export interface SessionConfig {
/** Session metadata: the first context's runtime configuration (session_id / provider / model_id / model_context_window / system_prompt / agent_state / workspace / source) — a context a compaction or a model switch opens brings its own through `openNextContext`; the toolset travels separately as the first run's tool_list_ready event. */
meta: SessionMetaPayload;
/**
* Opens the Session's FIRST context, lazily at the start of the first run: resolves the
* toolset — the Environment's first listTools connects any configured MCP Servers — and
* builds that context's LLM. The records it produces on the way — the
* `mcp_connect_begin` / `mcp_connect_end` pair around a connect, then the
* `tool_list_ready` carrying the toolset — are published through `opts.emit` and stream
* live from `run`: the same shape as `openNextContext`, because opening the first context
* and opening a later one are one procedure in the composition layer. Kept out of
* Session construction so creating a Session is instant and the connect wait streams as
* visible events instead. An aborted attempt is cancelled via `cancelBootstrap` — the
* next run calls this again and reconnects from scratch.
*/
bootstrap: (opts: OpenContextOptions) => Promise<{ llm: LLMInterface }>;
/** Cancels an in-flight bootstrap on user abort (the composition layer wires Environment.cancelMcpConnect). */
cancelBootstrap?: () => void;
environment: EnvironmentInterface;
trace?: TraceSink;
/** Maximum LLM turns per 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 brings its own. */
maxTurns?: number;
/**
* Opens a fresh model context after compaction (see ContextEngineDeps.openNextContext): the new
* LLM object, with the session_meta and engine settings of the context it opened — the
* composition layer assembles them from the Agent State as it is then — and the records it
* produced while opening (its MCP connect pair and tool_list_ready, through `opts.emit`).
* The Session adopts the meta as its current one (`metaMessage`); the engine yields the
* records live, writes meta and records at the head of the rotated Trace file, and seeds
* the new LLM's cumulative session counts itself. Context compaction is unavailable if not
* provided. The hooks it answers with become the Session's (see
* {@link SessionOpenedContext}).
*/
openNextContext?: (
opts: SessionOpenContextOptions,
) => SessionOpenedContext | Promise<SessionOpenedContext>;
/**
* Factory for the bare LLM used by out-of-band, one-off requests (same Model/credential as
* the session; no tools, no system prompt, thinking off): used for meta-requests such as
* `generateTitle`; if not provided, `generateTitle` returns null.
*/
createBareLLM?: () => LLMInterface;
/** The first context's compaction settings (defaults are filled in by the composition layer); only takes effect when provided together with `openNextContext`, and a context that one opens brings its own. */
compaction?: CompactionSettings;
/** Live compaction settings, re-read at every compaction checkpoint (see ContextEngineDeps.readCompaction): what lets a threshold, mode or prompt edited on disk reach the conversation that is running. Session-lifetime, so a rotation does not replace it. */
readCompaction?: () => CompactionSettings | Promise<CompactionSettings>;
/** Session resume: `session_meta` is already in the original Trace file, so it isn't written again on the first run (avoids duplication). */
metaAlreadyWritten?: boolean;
/** Session resume: the engine's initial state derived from Trace replay (carry-over / accumulated stats, etc.). */
initialEngineState?: EngineInitialState;
/** Session resume: the full historical messages of the current context (for rendering, including interrupted turns and their markers), for frontend display. */
resumedHistory?: OmniMessage[];
/**
* This Session's scratchpad directory: where an input image is saved when it becomes an
* `[attached image: <path>]` line instead of riding the request as an image. The model
* reads it back with read_file, and the Web turns the path into a
* thumbnail again. Always set — each input path decides on its own whether to use it.
*/
imagesDir: string;
/**
* Whether the first context's model accepts image input (from ModelEntry.vision). Prompts and
* steering messages fold their images only while the running context's model has none — a
* context `openNextContext` opens brings its own answer (SessionOpenedContext.modelHasVision).
*/
modelHasVision: boolean;
/**
* The composition layer's half of an in-session model switch (see {@link Session.switchModel});
* absent = the Session's model cannot be switched.
*/
modelSwitch?: ModelSwitchSupport;
/**
* The first context's hooks — one list per hook point, and the spawner that honors a stop
* hook's `subagent` answer (see hooks/stop-hook.ts). Absent = none. A context
* `openNextContext` opens may bring its own.
*/
hooks?: SessionHooks;
/**
* Project sandbox command policy (`[command_policy]` of `.project_config.toml`), as a
* SOURCE answering with the running context's policy: command policy is strict-tier —
* the composition layer reads it from disk once per context open, so an edit applies at
* the next rotation. `run` wraps the injected approval callback with it — the refusal
* happens at the approval boundary, above every approval mode and below no Human
* implementation.
* Absent, or a source yielding nothing = the factory rule set applies;
* `{ enabled: false }` opts out. Docs: /docs/configuration § "Command policy".
*/
commandPolicy?: CommandPolicySource;
}
/** `Session.run` options: the engine's per-call options. */
export type SessionRunOptions = RunOptions;
/** Why a model switch was refused before its first event (see {@link ModelSwitchRefusedError}). */
export type ModelSwitchRefusal =
/** The target pair names no entry in the Project config on disk. */
| "model_not_configured"
/** The target is configured but its client cannot be constructed (a missing credential foremost), or this Session has no switch support. */
| "model_unavailable"
/** The Session has a context to close but no compaction configured to close it with. */
| "compaction_not_configured";
/**
* A model switch refused before anything was sent or recorded: no event was produced and the
* Session is exactly where it was. `Session.switchModel` throws it for the refusals `reason`
* enumerates, so a host maps each to its own code (the server's 409s) and treats anything
* else a switch throws as a failure.
*/
export class ModelSwitchRefusedError extends Error {
constructor(
readonly reason: ModelSwitchRefusal,
message: string,
) {
super(message);
this.name = "ModelSwitchRefusedError";
}
}
/**
* What the composition layer provides for {@link Session.switchModel}: the Session owns the
* policy, the Agent owns the Project config, the credentials and the assembly.
*/
export interface ModelSwitchSupport {
/**
* Validates a switch target before anything is sent or recorded: resolves it against the
* Project config as it is on disk and constructs its client, so a pair that is not
* configured, or has no credential, is refused here (a {@link ModelSwitchRefusedError})
* exactly where Session creation would have failed.
*/
validate(ref: ModelRef): Promise<void>;
/**
* Re-assembles the Session's not-yet-opened first context on `ref` — the switch of a Session
* that never ran, which has no context to close. The Environment is re-equipped for it, and
* what comes back is what a rotation's opener returns minus the LLM, which the first run's
* bootstrap builds as usual.
*/
reassembleInitialContext(ref: ModelRef): Promise<Omit<SessionOpenedContext, "llm">>;
}
/** `Session.switchModel` options: the target's paired reference, the abort signal for the compaction request, and what a summarize that cannot complete means. */
export interface ModelSwitchOptions {
provider: string;
modelId: string;
signal?: AbortSignal;
/**
* What to do when the summarize compaction that closes the running context cannot complete:
* `"stay"` (default) keeps today's rule — the switch fails and the Session stays on the model
* it is on, leaving the context untouched — while `"discard"` drops the context without sending
* anything and completes the switch on the target (see `ContextEngine.switchContext`). The
* second one is the only way out of a model that cannot answer at all — an exhausted quota, a
* rejected credential — since the summarize request would be that same model's.
*/
onCompactionFailure?: SwitchFailurePolicy;
}
/**
* Awaits `work` unless `signal` aborts first — the abort side never cancels `work`
* (deliberate: see the bootstrap single-flight). Settles immediately when the signal is
* already aborted.
*/
function raceAbort<T>(
work: Promise<T>,
signal: AbortSignal | undefined,
): Promise<{ value: T } | "aborted"> {
if (!signal) return work.then((value) => ({ value }));
if (signal.aborted) return Promise.resolve("aborted");
return new Promise((resolve, reject) => {
const onAbort = (): void => resolve("aborted");
signal.addEventListener("abort", onAbort, { once: true });
work.then(
(value) => {
signal.removeEventListener("abort", onAbort);
resolve({ value });
},
(err: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(err instanceof Error ? err : new Error(String(err)));
},
);
});
}
/**
* Caps on captured title material (chars per side); accumulation stops once exceeded. The
* assistant body is capped tighter: a title only needs the opening of the answer, and hosts
* may start generating as soon as this much body text has streamed (see the Web server's
* early trigger) — a long answer would otherwise overrun the material.
*/
const TITLE_USER_MATERIAL_LIMIT = 2000;
const TITLE_ASSISTANT_MATERIAL_LIMIT = 1000;
/**
* A background-task completion event as the harness user message that reports it: the
* `[background_task_done]` block carries the structured facts, the body the display text —
* what settled, then the tail of its yet-undelivered output. `sender: "harness"` marks the
* non-human origin in the Trace.
*
* Built at DELIVERY time, not queue time, because the message must record how it reached the
* conversation and a queued event does not know that yet: the engine's mid-run drain stamps
* `delivery: "steering"` (injected into an already-started Task — the render and stats layers
* keep it inside that turn), while the host's idle take leaves the field off (the notice is
* the new task's own starting input and keeps its independent turn). The two deliveries are
* positionally identical in the Trace, so only this recorded stamp can tell them apart.
*/
function backgroundDoneNotice(event: BackgroundTaskDoneEvent, delivery?: "steering"): OmniMessage {
const what = event.kind === "command" ? "Background command" : "Background subagent";
const idField = event.kind === "command" ? "process_id" : "subagent_id";
const verb =
event.status === "completed" ? "finished" : event.status === "stopped" ? "stopped" : "failed";
const detail = event.detail ? ` — ${event.detail}` : "";
const head = `${what} ${verb}: \`${event.label}\` (${idField} ${event.id})${detail}`;
const body = event.output.trim() ? `${head}\n\n${event.output}` : head;
return userText(
buildBackgroundTaskDoneMessage(
{
kind: event.kind,
id: event.id,
status: event.status,
detail: event.detail,
...(delivery ? { delivery } : {}),
},
body,
),
"harness",
);
}
/**
* Accumulates title material: the body text of complete text messages from the main session
* (no origin) — thinking and tool calls naturally don't count — and stops once the cap is hit.
*/
function appendTitleText(
base: string,
msg: OmniMessage,
role: "user" | "assistant",
limit: number,
): string {
if (base.length >= limit) return base;
if (msg.origin && msg.origin.length > 0) return base;
const p = msg.payload as { type?: string; role?: string; text?: string };
if (msg.type !== "model_msg" || p.type !== "text" || p.role !== role || !p.text) return base;
return base ? `${base}\n${p.text}` : p.text;
}
export class Session {
readonly sessionId: string;
readonly workspaceDir: string;
/** Session resume: the full historical messages of the current context (for rendering); undefined for a non-resumed Session. */
readonly resumedHistory?: OmniMessage[];
/** Built by the first run's bootstrap (`ensureReady`); null until then — the sync delegates below answer conservatively before it exists. */
private engine: ContextEngine | null = null;
/**
* Inputs of a run aborted mid-bootstrap, carried into the next run: the engine did not
* exist yet to deliver them — dropping them would silently lose the user's message.
* Prepended on the next run so the model finally sees them.
*/
private carryOverInput: OmniMessage[] = [];
/**
* Serialized envelopes of carried inputs the ABORT path already wrote to the Trace
* (the aborted turn is recorded: input + connect pair + abort). The next run's engine
* re-delivers those inputs but must not re-write them — consumed one-shot by the
* skip-wrapper handed to the engine at construction.
*/
private carryOverPersisted: string[] = [];
/** The aborted attempt's yielded records (connect pair + abort event), stashed by ensureReady for the caller's Trace write. */
private abortedBootstrapRecords: OmniMessage[] = [];
private readonly bootstrap: SessionConfig["bootstrap"];
private readonly cancelBootstrap: (() => void) | undefined;
/**
* Engine dependencies, kept so ensureReady can construct the engine late — minus what only
* that moment knows: the LLM and its records (the bootstrap provides them), and the first
* context's session_meta (the Session's own `meta` as it stands then).
*/
private readonly engineDeps: Omit<
ConstructorParameters<typeof ContextEngine>[0],
"llm" | "toolList" | "bootstrapRecords" | "sessionMeta"
>;
private readonly environment: EnvironmentInterface;
private readonly trace?: TraceSink;
/** session_meta of the context that is running: the first context's at construction, re-stamped by each context `openNextContext` opens (see `metaMessage`); `provider` / `modelId` read from it. */
private meta: SessionMetaMessage;
private readonly createBareLLM?: () => LLMInterface;
/** The Session's thinking level — buffered here until the engine exists, engine state afterwards (see the `thinkingLevel` accessors). */
private level?: ThinkingLevelName;
private readonly imagesDir: string;
/** Whether the running context's model views images itself (see SessionConfig.modelHasVision); follows each context `openNextContext` opens. */
private modelHasVision: boolean;
private readonly modelSwitch: ModelSwitchSupport | undefined;
/** The model a switch in flight opens the next context on: what the opener is told (see `switchModel`). */
private switchTarget: ModelRef | undefined;
/**
* The hooks of the context that is running, and the spawner for a stop hook's subagent
* answer: the first context's at construction, replaced whole by each context
* `openNextContext` opens with a set of its own (see `adoptHooks`). Every consult reads
* these fields when it happens, so a rotation in the middle of a `run` call hands the
* rest of that call to the new context's hooks.
*/
private stopHooks: readonly StopHook[] = [];
private preToolUseHooks: readonly PreToolUseHook[] = [];
private userPromptHooks: readonly UserPromptHook[] = [];
private spawnSubagent: HookSubagentSpawner | undefined;
private readonly commandPolicy?: CommandPolicySource;
private metaWritten = false;
/**
* The image fold, bound to this Session's scratchpad — Session is the layer that knows both
* the directory and the model's capability, so it binds the conversion once and each input
* path calls it under its own rule (see `modelHasVision`). The body reads `imagesDir` at call
* time, so field ordering in the constructor doesn't matter.
*/
private readonly foldImages = (messages: OmniMessage[]): Promise<OmniMessage[]> =>
imagesToScratchpadPaths(messages, this.imagesDir);
/** Title material (used by `generateTitle` as the default): the user input and model body text of the first Task that contains user text. */
private titleUserText = "";
private titleAssistantText = "";
/** Material-frozen flag: becomes true once the first Task containing user text finishes; subsequent runs stop accumulating. */
private titleMaterialFrozen = false;
/**
* Background-task completion events not yet delivered. Single source of truth for
* delivery: a running Task's engine drains it at every input-assembly boundary (yield +
* Trace write + request input); an idle Session fires `noticeListener` so the host can
* take the queue (`takeBackgroundNotices`) and submit it as an ordinary task — whichever
* consumes first, each notice is delivered exactly once. With neither, the next run's
* start drains it. The queue holds raw EVENTS: the harness user message is built by the
* consuming path, which is when the delivery mode is known (see backgroundDoneNotice —
* the engine drain stamps `delivery: steering`, the host take does not).
*/
private pendingNotices: BackgroundTaskDoneEvent[] = [];
/** Idle-arrival signal for the host (see `onBackgroundNotice`); null until a host subscribes. */
private noticeListener: (() => void) | null = null;
/** Live background-subagent message subscriber (see `onBackgroundMessage`); null until a host subscribes — messages are display copies and drop without one. */
private bgMessageListener: ((msg: OmniMessage) => void) | null = null;
constructor(config: SessionConfig) {
this.sessionId = config.meta.session_id;
this.workspaceDir = config.meta.workspace;
this.environment = config.environment;
this.trace = config.trace;
this.meta = sessionMeta(config.meta);
this.metaWritten = config.metaAlreadyWritten ?? false;
if (config.resumedHistory) this.resumedHistory = config.resumedHistory;
if (config.createBareLLM) this.createBareLLM = config.createBareLLM;
this.imagesDir = config.imagesDir;
this.modelHasVision = config.modelHasVision;
this.modelSwitch = config.modelSwitch;
if (config.hooks) this.adoptHooks(config.hooks);
if (config.commandPolicy) this.commandPolicy = config.commandPolicy;
this.bootstrap = config.bootstrap;
this.cancelBootstrap = config.cancelBootstrap;
// The engine itself is built by ensureReady() on the first run, once the bootstrap has
// produced the LLM: everything else it needs is captured here.
this.engineDeps = {
environment: config.environment,
...(config.trace ? { trace: config.trace } : {}),
...(config.maxTurns !== undefined ? { maxTurns: config.maxTurns } : {}),
// Context compaction: the new-context factory + resolved settings; the engine writes the
// context's session_meta (and tool_list_ready) at the start of the new Trace file after
// splitting. The factory is wrapped so the opener is told the model a switch in flight is
// moving to, and the Session follows the opened context (see `adoptContext`).
...(config.openNextContext
? {
openNextContext: async (opts: OpenContextOptions): Promise<OpenedContext> => {
const { hooks, modelHasVision, ...opened } = await config.openNextContext!({
...opts,
...(this.switchTarget ? { modelRef: this.switchTarget } : {}),
});
this.adoptContext(opened.sessionMeta, modelHasVision, hooks);
return opened;
},
}
: {}),
...(config.compaction ? { compaction: config.compaction } : {}),
...(config.readCompaction ? { readCompaction: config.readCompaction } : {}),
...(config.initialEngineState ? { initialState: config.initialEngineState } : {}),
// The engine assembles one input of its own — a steering message with images — and folds
// it through the same converter `runTask` uses, failures included: a scratchpad that
// can't be written to ends the run rather than dropping the attachment and carrying on.
// The picture usually arrives BECAUSE the run is going the wrong way, so continuing
// without it spends the rest of the Task heading further that way. A model that takes
// images is answered `null` — the model can change with the context, so the question is
// asked each time.
foldInputImages: async (messages) => (this.modelHasVision ? null : this.foldImages(messages)),
// Background completion notices: the engine pulls from the Session's queue at every
// input-assembly boundary (see pendingNotices for the exactly-once contract). This is
// the steering delivery path — the notice joins a Task that already exists — so the
// built message carries the `delivery: steering` stamp.
backgroundNotices: {
drain: () => this.pendingNotices.splice(0).map((e) => backgroundDoneNotice(e, "steering")),
pending: () => this.pendingNotices.length,
},
};
// Completion events of run_in_background launches flow from the Environment into the
// notice queue (events fired before this attach are buffered by the Environment).
config.environment.setBackgroundTaskListener?.((event) => this.handleBackgroundDone(event));
// Live-forwarded background-subagent messages flow straight to the host's subscriber —
// display copies only (the child's own Trace is the durable record), so with no
// subscriber they are simply dropped.
config.environment.setBackgroundMessageListener?.((msg) => this.bgMessageListener?.(msg));
}
/**
* Runs the named package's host-triggered `user_prompt` hook (`trigger: "host"`) — hooks
* run in core and nowhere else; the host calls this when it accepts a user prompt for the
* flow the package owns (the server does for a goal start, with `extras: { budget }`).
* The Session supplies its own id, Trace path and scratchpad directory; the answer's
* `context` is the text the host sends right behind the user's message, stamped
* `sender: "harness"`. Returns null when the package is not installed or names no such
* command (the host's cue to refuse the flow); an empty answer is `{}`. No `hook` event
* is recorded — the expansion message is the record.
*/
async runUserPromptHook(
name: string,
prompt: string,
extras?: Record<string, string | number | boolean>,
): Promise<UserPromptHookResult | null> {
const hook = this.userPromptHooks.find((h) => h.name === name && h.trigger === "host");
if (!hook) return null;
const tracePath = this.trace?.currentPath?.();
const result = await hook.run({
sessionId: this.sessionId,
...(tracePath !== undefined ? { tracePath } : {}),
scratchpadDir: this.imagesDir,
prompt,
...(extras !== undefined ? { extras } : {}),
});
return result ?? {};
}
/** Takes a context's hooks as the Session's own, whole: a point the set does not list has none. */
private adoptHooks(hooks: SessionHooks): void {
this.stopHooks = hooks.stop ?? [];
this.preToolUseHooks = hooks.preToolUse ?? [];
this.userPromptHooks = hooks.userPrompt ?? [];
this.spawnSubagent = hooks.spawnSubagent;
}
/**
* The user-prompt consult of one Prompt (the engine's `RunOptions.userPrompt` seam): runs
* the hooks due on every Prompt against the text of the user's own in `input`, and
* returns their records. Null — nothing to consult — when no such hook is installed or
* the input carries no user text without a sender: an input the harness, the server or a
* parent agent wrote is not a Prompt the user submitted.
*/
private async consultUserPromptHooks(
input: OmniMessage[],
signal?: AbortSignal,
): Promise<{ records: OmniMessage[] } | null> {
const hooks = this.userPromptHooks.filter((h) => h.trigger !== "host");
if (hooks.length === 0) return null;
const texts: string[] = [];
for (const msg of input) {
if (msg.type !== "model_msg" || (msg.origin && msg.origin.length > 0)) continue;
const p = msg.payload as { type?: string; role?: string; text?: string; sender?: string };
if (p.type !== "text" || p.role !== "user" || typeof p.text !== "string") continue;
if (p.sender !== undefined && p.sender !== "user") continue;
texts.push(p.text);
}
if (texts.length === 0) return null;
const text = texts.join("\n");
const tracePath = this.trace?.currentPath?.();
return runUserPromptHooks(hooks, {
sessionId: this.sessionId,
...(tracePath !== undefined ? { tracePath } : {}),
scratchpadDir: this.imagesDir,
// The user's own words: a skill invocation or an origin note in front of them is the
// host's framing, the same reading the goal start gives its objective.
prompt: stripLeadingMarkerBlocks(text).trim() || text,
...(signal ? { signal } : {}),
});
}
/**
* Runs a Task to completion and streams out OmniMessage. `newMessages` is this call's Prompt
* (only the newly added input); `opts` carries the abort signal `signal` and the per-call
* approval callback `approve` (the engine calls it once per tool_call within a turn).
* On the first run, `session_meta` is written to the Trace first.
*
* A single `run` automatically drives the whole ReAct loop: consuming the LLM stream,
* approving and executing tools one at a time, feeding results back for the next turn,
* until a turn no longer produces a tool_call (Task ends) or it's aborted.
* Docs: /docs/agent-loop § "The loop at a glance".
*
* A Prompt carrying text of the user's own is first put to the user-prompt hooks (see
* hooks/prompt-hook.ts): each `context` they answer follows the Prompt as a user text
* stamped `sender: "harness"` — yielded, since the host has not seen it, written to the
* Trace and sent with the Prompt in the Task's first request.
*
* When the Task ends, the Session's stop hooks are consulted (see hooks/stop-hook.ts):
* every answer is recorded as a `hook` event on the stream and in the Trace, and the first
* `continue` drives another Task inside this same call — its input is yielded first, as a
* user text message, since a plain run never yields its own input and hosts render the
* injected one from the stream. No `continue`, a cutoff (abort, LLM failure, the
* max_turns cap) or an aborted signal ends the call; the return value is the last Task's
* cutoff, exactly as for a single Task.
*/
async *run(
newMessages: OmniMessage[],
opts?: SessionRunOptions,
): AsyncGenerator<OmniMessage, RunCutoff | null> {
// The sandbox command policy is applied here, at the Human boundary itself: the
// injected callback is wrapped so a vetoed command is refused before the host is ever
// asked, which is what makes the policy outrank every approval mode — no host, and no
// approval mode, gets a say. Wrapped once for every Task of this call; a child Session
// wraps its own forwarded callback again, harmlessly. With no callback at all the
// engine denies everything anyway, so there is nothing to guard.
if (opts?.approve) {
opts = { ...opts, approve: withCommandPolicy(opts.approve, this.commandPolicy) };
}
// Pre-tool-use hooks ride the engine's consult seam (RunOptions.preToolUse): the
// engine records their events in stream order and applies the first decision before
// the approval callback. One rule is enforced here, where the command policy lives:
// a hook `allow` never overrides the policy — hook packages sit in agent-writable
// state, the policy is Project-owned security config — so a policy-vetoed allow is
// downgraded to no decision and the approval chain (policy outermost) answers.
// The hooks are read at each consult rather than captured here: a compaction inside
// this call opens a context with hooks of its own, and the calls after it are theirs.
{
const signal = opts?.signal;
opts = {
...opts,
preToolUse: async (tc) => {
const hooks = this.preToolUseHooks;
if (hooks.length === 0) return null;
const p = tc.payload;
const tracePath = this.trace?.currentPath?.();
const outcome = await runPreToolUseHooks(hooks, {
sessionId: this.sessionId,
...(tracePath !== undefined ? { tracePath } : {}),
toolName: p.name,
toolCallId: p.tool_call_id,
argumentsJson: p.arguments,
...(signal ? { signal } : {}),
});
if (
outcome.decision === "allow" &&
vetoForToolCall(p.name, p.arguments, this.commandPolicy?.()) !== null
) {
return { ...outcome, decision: null };
}
return outcome;
},
};
}
const approve = opts?.approve;
// User-prompt hooks ride the engine's consult seam too (RunOptions.userPrompt), for the
// call's own Prompt only: a Task a stop hook continues into starts from the hook's
// input, which no user submitted.
let taskOpts: SessionRunOptions | undefined = {
...opts,
userPrompt: (prompt, signal) => this.consultUserPromptHooks(prompt, signal),
};
let input = newMessages;
for (;;) {
// Manual iteration (not for-await) so the engine's return value — how the Task ended —
// is read: a cutoff means the model never finished, which no `continue` may override.
const it = this.runTask(input, taskOpts);
taskOpts = opts;
let cutoff: RunCutoff | null = null;
for (;;) {
const res = await it.next();
if (res.done) {
cutoff = res.value;
break;
}
yield res.value;
}
if (this.stopHooks.length === 0) return cutoff;
const tracePath = this.trace?.currentPath?.();
const spawn = this.spawnSubagent;
const outcome = await runStopHooks(
this.stopHooks,
{
sessionId: this.sessionId,
...(tracePath !== undefined ? { tracePath } : {}),
...(opts?.signal ? { signal: opts.signal } : {}),
},
spawn ? (request) => spawn(request, approve) : undefined,
);
for (const ev of outcome.events) {
await this.writeTrace(ev, "hook event");
yield ev;
}
// A user's interruption outranks every hook: after a cutoff, or with the signal
// already aborted between Tasks, a `continue` is recorded but never run — an aborted
// engine would only hold the injected input as carry-over and leak it into the
// user's next message.
if (outcome.next === null || cutoff !== null || opts?.signal?.aborted) return cutoff;
input = [userText(outcome.next, "harness")];
yield input[0]!;
}
}
/** The single-Task path: every Task of a `run` call — a hook-continued one included — runs one of these. */
private async *runTask(
newMessages: OmniMessage[],
opts?: RunOptions,
): AsyncGenerator<OmniMessage, RunCutoff | null> {
// Folded before Trace and title material, so the path lines are what gets recorded.
if (!this.modelHasVision) newMessages = await this.foldImages(newMessages);
// A previously aborted bootstrap dropped these before the engine existed: they lead
// this run's input (already folded by their own run), so the model finally sees them
// and the engine's run-start write persists them.
if (this.carryOverInput.length > 0) {
newMessages = [...this.carryOverInput, ...newMessages];
this.carryOverInput = [];
}
const ready = yield* this.ensureReady(opts?.signal);
if (!ready) {
// Aborted mid-bootstrap: the attempt is cancelled (cancelBootstrap) and the next
// run reconnects from scratch. The aborted turn still leaves a Trace — the input,
// the aborted connect pair and the abort event — so the analysis page shows the
// interruption and a reload (or restart) does not lose the message. The engine
// doesn't exist, so the Session writes them itself; inputs already persisted by a
// previous aborted attempt are skipped (repeat aborts record each exactly once),
// and the next successful run's engine skips re-writing them (carryOverPersisted).
for (const m of newMessages) {
const serialized = JSON.stringify(m);
if (this.carryOverPersisted.includes(serialized)) continue;
if (await this.writeTrace(m, "aborted-run input")) {
this.carryOverPersisted.push(serialized);
}
}
for (const m of this.abortedBootstrapRecords) {
await this.writeTrace(m, "aborted bootstrap record");
}
this.abortedBootstrapRecords = [];
// Carry the merged list, so repeated aborts keep accumulating exactly once each.
this.carryOverInput = newMessages;
return { kind: "abort", errorCode: "user_abort" };
}
// Self-captures title material (the title is derived from the first-turn
// conversation text): while material isn't frozen yet, collect this call's user text and
// the produced model text; freezes once the first Task containing user text finishes, so
// the title reflects the start of the conversation.
const capture = !this.titleMaterialFrozen;
if (capture) {
for (const m of newMessages) {
this.titleUserText = appendTitleText(
this.titleUserText,
m,
"user",
TITLE_USER_MATERIAL_LIMIT,
);
}
}
// Manual iteration (not for-await) so the engine's return value — how the run ended —
// propagates to this generator's own return.
const it = this.engine!.run(newMessages, opts);
let cutoff: RunCutoff | null = null;
for (;;) {
const res = await it.next();
if (res.done) {
cutoff = res.value;
break;
}
const msg = res.value;
if (capture) {
this.titleAssistantText = appendTitleText(
this.titleAssistantText,
msg,
"assistant",
TITLE_ASSISTANT_MATERIAL_LIMIT,
);
}
yield msg;
}
if (capture && this.titleUserText.trim()) this.titleMaterialFrozen = true;
return cutoff;
}
/**
* First-run bootstrap: writes `session_meta`, opens the first context and builds the
* engine — streaming the phase as it happens. The bootstrap publishes its records
* through `emit` — with MCP Servers configured, the `mcp_connect_begin` /
* `mcp_connect_end` pair around the connect + discovery wait (overall status +
* per-server outcomes; the wall time is the pair's timestamp difference), then the
* `tool_list_ready` carrying the resolved toolset (split out of session_meta precisely
* so the meta never has to wait for this phase) — and a merge queue turns them into
* live yields here while it runs: the same pump the engine's post-compaction opener
* uses, because opening the first context and opening a later one are one procedure.
*
* The records are yielded live, but their Trace writes are DEFERRED to the engine
* (ContextEngineDeps.bootstrapRecords / toolList): the engine writes them right after
* this run's input, so the connect phase belongs to the new turn in the Trace — after
* the user's message — instead of dangling before it (their earlier timestamps keep the
* file chronological, since the input message was created before the connect began).
*
* Returns false when `signal` aborts mid-bootstrap: the attempt is CANCELLED
* (`cancelBootstrap` → the provider aborts pending connects and resets — the next run
* reconnects from scratch), a connect the abort cut short is closed with a
* `status: "aborted"` end, and a standard abort event follows. The records are stashed
* (abortedBootstrapRecords) for the caller, which writes the turn to the Trace itself —
* input first, then the records — since no engine exists to do it; the input is also
* carried (carryOverInput) so the next run delivers it to the model without re-writing
* it. No-op returning true once the engine exists; a rejected bootstrap (unreadable
* resume history, LLM construction) throws to the caller, and a later run retries with
* a fresh attempt.
*/
private async *ensureReady(signal?: AbortSignal): AsyncGenerator<OmniMessage, boolean> {
await this.ensureMetaWritten();
if (this.engine) return true;
const records: OmniMessage[] = [];
const { queue, result: work } = pumpOpener((emit) => this.bootstrap({ emit }));
for (;;) {
const res = await raceAbort(queue.next(), signal);
if (res === "aborted") {
this.cancelBootstrap?.();
// The cancelled attempt settles on its own (rejection expected); anything it
// publishes after this point is dropped, exactly as its return value is.
work.catch(() => {});
// Stashed (not written here) so the caller can put the run's INPUT first — the
// Trace stays chronological: input, records, abort.
this.abortedBootstrapRecords = [...records];
// A connect the abort cut short never published its end: close the pair.
const hasType = (t: string): boolean =>
records.some((m) => (m.payload as { type?: string }).type === t);
if (hasType("mcp_connect_begin") && !hasType("mcp_connect_end")) {
const end = mcpConnectEnd({ status: "aborted", results: [] });
yield end;
this.abortedBootstrapRecords.push(end);
}
const aborted = abortEvent("user_abort");
yield aborted;
this.abortedBootstrapRecords.push(aborted);
return false;
}
if (res.value === null) break;
records.push(res.value);
yield res.value;
}
const { llm } = await work;
// The opener's toolset record rides as the engine's `toolList` (first-run write +
// rotation rewrite); the connect pair — everything else — as bootstrapRecords.
const toolsMsg = records.findLast(
(m) => (m.payload as { type?: string }).type === "tool_list_ready",
);
const connectRecords = records.filter((m) => m !== toolsMsg);
// One-shot skip list: inputs carried from an aborted bootstrap were already written
// to the Trace by the abort path — the engine re-delivers them (model context) but
// must not re-write them. Exact-envelope match, each consumed once.
const persisted = this.carryOverPersisted;
this.carryOverPersisted = [];
const baseTrace = this.engineDeps.trace;
const trace: TraceSink | undefined =
baseTrace && persisted.length > 0
? {
write: async (msg) => {
const at = persisted.indexOf(JSON.stringify(msg));
if (at >= 0) {
persisted.splice(at, 1);
return;
}
await baseTrace.write(msg);
},
...(baseTrace.rotate ? { rotate: () => baseTrace.rotate!() } : {}),
}
: baseTrace;
this.engine = new ContextEngine({
...this.engineDeps,
...(trace !== undefined ? { trace } : {}),
llm,
sessionMeta: this.meta,
...(toolsMsg !== undefined ? { toolList: toolsMsg } : {}),
bootstrapRecords: connectRecords,
});
// A level assigned before the first run was buffered on the Session: hand it to the
// engine now that it exists, ahead of the first turn request.
if (this.level !== undefined) this.engine.setThinkingLevel(this.level);
return true;
}
/**
* Queues a steering message for the running Task: the engine delivers it between turns as
* a standalone `[user_steering]` user message — sent with the next request input alongside
* that turn's tool outputs, or alone as the continuation input when the turn produced no
* tool calls — so the model sees it without the loop being interrupted. `input` is an
* OmniMessage list, the same shape `run` takes a Prompt in: its user text becomes the
* block's body, and its images ride behind that message just as a Prompt's do; on a model
* without vision they become `[attached image: …]` path lines inside the block instead (see
* the engine's steeringMessages). Returns false when no Task is running — the host should
* then submit the message as a normal task instead. Delivery is independent of approval
* mode; anything still queued when the run exits (abort included) is discarded.
*/
steer(input: OmniMessage[]): boolean {
// No engine yet = no running Task to steer (the first run's bootstrap hasn't finished).
return this.engine?.steer(input) ?? false;
}
/**
* Withdraws a steering input queued via `steer` before the engine delivers it: `input` is
* the exact list that was passed to `steer` (matched by identity). Returns false when it
* is no longer queued — already delivered to the model, or the run exited — so the host
* reports "already delivered" instead of silently pretending the recall worked.
*/
unsteer(input: OmniMessage[]): boolean {
return this.engine?.unsteer(input) ?? false;
}
/**
* Skips the in-progress reconnect backoff and fires the next retry immediately (the
* user's "retry now" on the reconnect countdown): the attempt counter is unchanged —
* the skipped wait does not consume an extra attempt. Returns false (a benign no-op)
* when no reconnect wait is in progress; idempotent under races with the timer/abort.
* Mirrors `steer` as a mid-run nudge (no message of its own — the effect surfaces as
* the next `request_begin` arriving early).
*/
skipReconnectWait(): boolean {
// No engine yet = no reconnect wait can be in progress.
return this.engine?.skipReconnectWait() ?? false;
}
/** The running context's model: its provider group (paired with `modelId` to form the model reference). The first context's at construction; a model switch moves it. */
get provider(): string {
return this.meta.payload.provider;
}
/** The running context's model: its upstream model_id (the request id sent to AgentHub). */
get modelId(): string {
return this.meta.payload.model_id;
}
/**
* Follows a context the composition layer opened (or re-assembled): `metaMessage`,
* `provider` and `modelId` answer from its session_meta, the Prompt fold from its vision
* answer, and its hooks replace the Session's. What it did not bring stays as it was.
*/
private adoptContext(
meta: OmniMessage | undefined,
modelHasVision: boolean | undefined,
hooks: SessionHooks | undefined,
): void {
if (meta) this.meta = meta as SessionMetaMessage;
if (modelHasVision !== undefined) this.modelHasVision = modelHasVision;
if (hooks) this.adoptHooks(hooks);
}
/**
* Switches the model this Session runs on, in place: the running context is closed on the
* model it ran on, and the next one opens on the target. A context with completed turns is
* closed by a compaction — always **summarize**, whatever the Agent's `compaction.mode`
* says, because the summary is what the new model continues from. That compaction is an
* ordinary `manual` one: an ordinary request on the old model, extending the prefix the
* provider has cached. The model is recorded by the new context's `session_meta` alone; its
* Trace file opens at once, headed by that record — what a resume reads the model from —
* and the record is yielded last, so the stream names the model too. Only callable at a Task
* boundary, like `compact()`. Not the `/model` handoff, which opens a NEW Session.
*
* Before any event: the model the Session is already on is a no-op, and a target that
* cannot be switched to is refused with a {@link ModelSwitchRefusedError} naming why
* (anything else thrown is a failure). A Session that never ran has no context to close:
* its first context is re-assembled on the target, silently, and the first run opens it.
* One resumed after a restart builds its engine first, as `compact()` does. How the context
* is then closed and the next one opened is `ContextEngine.switchContext`; on which model,
* the opener is told here.
*
* Returns the terminal status: `completed` — the Session is on the target, and children
* spawned from here inherit it; anything else — the switch was stopped or its compaction
* failed (the events say how) and the Session stays on the model it was on. That last part is
* what `opts.onCompactionFailure: "discard"` changes for a failed compaction: the context is
* dropped and the switch completes, which is how a Session leaves a model whose requests all
* fail (see `ModelSwitchOptions`).
*/
async *switchModel(opts: ModelSwitchOptions): AsyncGenerator<OmniMessage, StopReason> {
const target: ModelRef = { provider: opts.provider, model_id: opts.modelId };
if (sameModelRef(target, { provider: this.provider, model_id: this.modelId })) {
return "completed";
}
if (!this.modelSwitch) {
throw new ModelSwitchRefusedError(
"model_unavailable",
"Switching the model is not available for this Session.",
);
}
await this.modelSwitch.validate(target);
if (!this.engine && !this.metaWritten) {
// Never ran: no context to close and nothing recorded — the first context is simply
// assembled again, on the target, and the first run writes that context's meta.
const { hooks, modelHasVision, ...first } =
await this.modelSwitch.reassembleInitialContext(target);
this.adoptContext(first.sessionMeta, modelHasVision, hooks);
if (first.compaction) this.engineDeps.compaction = first.compaction;
if (first.maxTurns !== undefined) this.engineDeps.maxTurns = first.maxTurns;
return "completed";
}
if (this.compactability() === "unsupported") {
throw new ModelSwitchRefusedError(
"compaction_not_configured",
"Context compaction is not configured for this Session, so its model cannot be switched.",
);
}
if (!(yield* this.ensureEngine(opts.signal))) return "aborted";
this.switchTarget = target;
try {
const status = yield* this.engine!.switchContext(
opts.signal,
opts.onCompactionFailure === undefined
? undefined
: { onCompactionFailure: opts.onCompactionFailure },
);
// Input an aborted bootstrap left with the Session rides on like the engine's pending
// input: its text alone, in memory (the original stays where the abort wrote it).
if (status === "completed") {
this.carryOverInput = this.carryOverInput.filter(
(m) => (m.payload as { type?: string }).type === "text",
);
}
return status;
} finally {
this.switchTarget = undefined;
}
}
/**
* User-initiated request to compact context (e.g. a CLI command): reuses the automatic
* compaction flow but skips the threshold check (reason=manual). Only callable at Task
* boundaries (between runs); streams out paired `compaction` events. The summarize digest
* becomes the prefix of the next `run`'s input (merged with the next user Prompt). A no-op
* if compaction isn't configured.
* Docs: /docs/agent-loop § "Compaction".
*/
async *compact(opts?: { signal?: AbortSignal }): AsyncGenerator<OmniMessage> {
// Nothing compactable and no engine: stay a strict no-op, without bootstrapping — a
// session that never ran must not leave trace records (meta / tool_list_ready) behind,
// or an untouched session would look resumable.
if (!this.engine && this.compactability() !== "ok") return;
if (!(yield* this.ensureEngine(opts?.signal))) return;
yield* this.engine!.compact(opts);
}
/**
* Builds the engine outside a run, for a compaction or a model switch. A Session resumed
* after a restart is the case: its history is real and already on disk, and the engine
* simply has not been built yet (that happens on the first run). The bootstrap injects the
* replayed history into the LLM, so the compaction request folds the actual conversation —
* rather than the call silently doing nothing and leaving the user waiting for a banner that
* never arrives. A no-op returning true once the engine exists.
*
* Returns false when `signal` aborted the bootstrap: no engine exists to write the attempt's
* records, so the Session writes them itself (as runTask does), keeping the interruption
* visible in the Trace.
*/
private async *ensureEngine(signal?: AbortSignal): AsyncGenerator<OmniMessage, boolean> {
if (yield* this.ensureReady(signal)) return true;
for (const m of this.abortedBootstrapRecords) {
await this.writeTrace(m, "aborted bootstrap record");
}
this.abortedBootstrapRecords = [];
return false;
}
/**
* Whether compaction is possible, and why not if not (see ContextEngine.compactability).
* When the result isn't `ok`, `compact()` is a no-op and yields no messages — callers should
* give feedback based on this rather than triggering a silent, fruitless compaction.
*/
compactability(): CompactAvailability {
if (this.engine) return this.engine.compactability();
// No engine yet: it is built by the first run's bootstrap (ensureReady). For a Session
// created in this process that genuinely means an empty context, but a Session **resumed**
// after a process restart already carries what the Trace replay recovered — answer from
// that, or a user who just restarted the client is told their whole conversation has
// nothing to compact (the server renders this reason as a 409 `nothing_to_compact`).
const init = this.engineDeps.initialState;
return compactAvailability({
configured: Boolean(this.engineDeps.compaction && this.engineDeps.openNextContext),
sessionTurns: init?.sessionTurns ?? 0,
fromCompaction: init?.fromCompaction ?? false,
});
}
/** Writes `session_meta` to the Trace before the first run/compaction; best-effort — failure doesn't interrupt the run. */
private async ensureMetaWritten(): Promise<void> {
if (this.metaWritten) return;
await this.writeTrace(this.meta, "session_meta");
this.metaWritten = true;
}
/** Best-effort `session_meta` Trace write (warn-and-continue stance): a failure logs and never interrupts the run. */
private async writeTrace(msg: OmniMessage, label: string): Promise<boolean> {
if (!this.trace) return false;
try {
await this.trace.write(msg);
return true;
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[trace] ${label} write failed: ${message}\n`);
return false;
}
}
/**
* Out-of-band, one-off request that generates a short title from the first-turn conversation
* text: sends one request using the bare LLM for the session's Model (no
* tools, no system prompt, thinking off), **without writing history or Trace**. Material
* defaults to the first Task text self-captured by the Session (user input and model body
* text collected during run; thinking and tool calls don't count), so callers don't need to
* supply it; `material` can override this (e.g. when a host generates a title for a
* sub-session — the material is that sub-session's own conversation). `title` is null if the
* material is empty, the request fails, or the composition layer didn't supply a bare LLM
* factory. Token consumption is returned via `usage` for the host to account for.
* Docs: /docs/agent-loop § "Side channels".
*/
async generateTitle(args?: {
/** Material override; defaults to the Session's self-captured material. */
material?: { userText: string; assistantText: string };
signal?: AbortSignal;
}): Promise<SessionTitleResult> {
if (!this.createBareLLM) return { title: null, usage: null };
const material = args?.material ?? {
userText: this.titleUserText,
assistantText: this.titleAssistantText,
};
return generateTitleWithLLM(this.createBareLLM(), {
...material,
...(args?.signal ? { signal: args.signal } : {}),
});
}
/**
* The Session's thinking level — the SOFT-limited runtime parameter as plain state: an
* assignment rides the very next LLM request (mid-context, even mid-Task), unlike the
* prompt, toolset and model, which never change between a context's open and its close —
* and nothing records it in the Trace. The live value is engine state
* (`ContextEngine.setThinkingLevel`), buffered on the Session until the engine exists;
* contexts keep their opening base (the creation option, else the Agent config) for
* compaction requests and as the fallback while nothing was ever assigned. The cost of
* the softness is the provider's cached context — changing the level invalidates the
* cached messages — so a host lets the user know at the picker that compacting first is
* recommended (the Web menu note, the CLI `/thinking` reply).
* Callers: the Web App's in-chat picker (PATCH), the CLI's `--thinking` / `/thinking`.
*/
get thinkingLevel(): ThinkingLevelName | undefined {
return this.level;
}
set thinkingLevel(level: ThinkingLevelName) {
this.level = level;
this.engine?.setThinkingLevel(level);
}
/**
* A tool's permission level (what the read-only approval mode auto-approves by);
* undefined for unknown tools. Strict-tier: answers from the running context's toolset —
* rebuilt at every rotation — so a permission edit applies when the next context opens.
*/
toolPermission(name: string): ToolPermission | undefined {
return this.environment.toolPermission(name);
}
/** The running context's session_meta message — the first context's until a compaction opens another (used e.g. by host tools to forward nested-session metadata to a parent session). */
get metaMessage(): OmniMessage {
return this.meta;
}
/**
* Background command processes owned by this Session's Environment (exec_commands
* promoted past their yield window): the host UI's process list. Empty for
* environments that don't track any.
*/
listBackgroundCommands(): BackgroundCommandInfo[] {
return this.environment.listBackgroundCommands?.() ?? [];
}
/** Refreshes the listen-port probes behind `BackgroundCommandInfo.serviceUrl` (see EnvironmentInterface.probeBackgroundCommandServices). No-op for environments without it. */
async probeBackgroundCommandServices(): Promise<void> {
await this.environment.probeBackgroundCommandServices?.();
}
/** Kills one of this Session's background command processes (whole process group); false when the id is unknown. */
killBackgroundCommand(processId: string): boolean {
return this.environment.killBackgroundCommand?.(processId) ?? false;
}
/**
* Asks one of this Session's EXECUTING tool calls to continue as a background task, so the
* turn can close (see EnvironmentInterface.detachToolCall). Not an abort: the call ends
* `completed` with a registry handle and its work keeps running. An environment without the
* method has no call to detach.
*/
detachToolCall(toolCallId: string): ToolDetachResult {
return this.environment.detachToolCall?.(toolCallId) ?? "not_running";
}
/** Whether a background subagent of this Session is mid-round (see EnvironmentInterface.hasRunningBackgroundSubagents). */
hasRunningBackgroundSubagents(): boolean {
return this.environment.hasRunningBackgroundSubagents?.() ?? false;
}
/** All live subagent child sessions of this Session's Environment, for a host UI's subagents panel (see EnvironmentInterface.listBackgroundSubagents). */
listBackgroundSubagents(): BackgroundSubagentInfo[] {
return this.environment.listBackgroundSubagents?.() ?? [];
}
/**
* Host-initiated message to one child session by its Session id — the user's input on the
* child, whatever its state: steering while it runs, a follow-up run while it is idle, a
* revival when it is no longer live (see EnvironmentInterface.sendToBackgroundSubagent).
* The human (panel) and the model (input_subagent) converge on the same channel.
*/
async sendToBackgroundSubagent(
childSessionId: string,
messages: OmniMessage[],
opts?: SubagentMessageOptions,
): Promise<SubagentMessageOutcome> {
return (
(await this.environment.sendToBackgroundSubagent?.(childSessionId, messages, opts)) ?? "gone"
);
}
/** Host-initiated abort of one child session's current run — the session survives for follow-ups (see EnvironmentInterface.abortBackgroundSubagentRun). */
abortBackgroundSubagentRun(childSessionId: string): boolean {
return this.environment.abortBackgroundSubagentRun?.(childSessionId) ?? false;
}
/** Host-initiated pin of one live child session's thinking level — the child's own `thinkingLevel`, applied from its next LLM request (see EnvironmentInterface.setBackgroundSubagentThinkingLevel); false when the child is not live. */
setBackgroundSubagentThinkingLevel(childSessionId: string, level: ThinkingLevelName): boolean {
return this.environment.setBackgroundSubagentThinkingLevel?.(childSessionId, level) ?? false;
}
/** Attaches the host's session-lifetime fallback approval sink for child sessions (see EnvironmentInterface.setSubagentApprovalFallback). */
setSubagentApprovalFallback(approve: ApproveFn): void {
this.environment.setSubagentApprovalFallback?.(approve);
}
/** Attaches the single listener for subagent run-state changes; the host re-reads `listBackgroundSubagents` on each ping (see EnvironmentInterface.setSubagentStateListener). */
onSubagentState(listener: () => void): void {
this.environment.setSubagentStateListener?.(listener);
}
/** Attaches the single listener for background-task state changes; the host re-reads `listBackgroundCommands` / `listBackgroundSubagents` on each ping (see EnvironmentInterface.setBackgroundStateListener). */
onBackgroundState(listener: () => void): void {
this.environment.setBackgroundStateListener?.(listener);
}
/** Queues a background completion event; a running Task delivers it at the next boundary, otherwise the host is signaled (see pendingNotices). */
private handleBackgroundDone(event: BackgroundTaskDoneEvent): void {
this.pendingNotices.push(event);
if (!(this.engine?.isTaskRunning ?? false)) this.noticeListener?.();
}
/**
* Subscribes the host's idle-arrival signal for background completion notices: called
* (without payload) whenever a notice is queued while no Task is running. The host then
* takes the queue with `takeBackgroundNotices` and submits it as an ordinary task — a host
* that never subscribes still gets delivery on the next run's start. One listener; a later
* call replaces the earlier one.
*/
onBackgroundNotice(listener: () => void): void {
this.noticeListener = listener;
}
/**
* Takes the queued background completion notices (harness user messages) for submission as
* a task's input — the notices become that task's starting input, so they carry no
* `delivery` stamp and keep their independent turn in every render layer. Empties the
* queue — the caller owns delivery of what it took; anything queued after this call is
* signaled/drained separately.
*/
takeBackgroundNotices(): OmniMessage[] {
return this.pendingNotices.splice(0).map((e) => backgroundDoneNotice(e));
}
/** Whether completion notices are still queued (hosts use it to keep a Session's runtime entry alive until they are delivered). */
hasPendingBackgroundNotices(): boolean {
return this.pendingNotices.length > 0;
}
/**
* Subscribes the host to live-forwarded background-subagent messages (origin-tagged, the
* same stream a foreground collect window would relay): the server publishes them to the
* session's event channel so the frontend sees a background child working in real time.
* One listener; a later call replaces the earlier one.
*/
onBackgroundMessage(listener: (msg: OmniMessage) => void): void {
this.bgMessageListener = listener;
}
/**
* Releases runtime resources held by the Session: kills long-running command sessions
* managed by the Environment. The host calls this when the Session ends (CLI exit, Web
* session close) to avoid leaking background processes into the host process's lifetime.
* Optional, idempotent.
*/
dispose(): void {
this.environment.dispose?.();
}
}