@sema-agent/core 5.20.0 → 5.21.0

package/dist/engine/harness/types.d.ts

@@ -2,6 +2,7 @@ import type { PromptEpochDescriptor } from "../../prompt-assembly/epoch.js";
 import type { DocumentContent, ImageContent, Model, SimpleStreamOptions, TextContent, Transport } from "../llm/index.js";
 import type { AfterToolCallResult, AgentEvent, AgentMessage, AgentTool, BeforeToolCallResult, QueueMode, ThinkingLevel } from "../loop/types.js";
 import type { AgentCoreRuntimeDeps } from "../loop/runtime-deps.js";
+/** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */
 export type Result<TValue, TError> = {
     ok: true;
     value: TValue;
@@ -9,48 +10,138 @@ export type Result<TValue, TError> = {
     ok: false;
     error: TError;
 };
+/** Create a successful {@link Result}. */
 export declare function ok<TValue, TError>(value: TValue): Result<TValue, TError>;
+/** Create a failed {@link Result}. */
 export declare function err<TValue, TError>(error: TError): Result<TValue, TError>;
+/** Normalize unknown thrown values into Error instances before using them as typed error causes. */
 export declare function toError(error: unknown): Error;
+/**
+ * Skill loaded from a `SKILL.md` file or provided by an application.
+ *
+ * [c209-C] R2 C8 delivery reality: in this repo skill disclosure does NOT enter the system prompt —
+ * `name`+`description` ride the first user turn as a `<system-reminder>` `<skills>` listing frame
+ * (+ boundary drift deltas), and bodies come back through the `Skill` tool. This harness-level
+ * resource type is the vendored seam the runner maps `TaskSpec.skills` onto.
+ */
 export interface Skill {
+    /** Stable skill name used for lookup and model-visible listings. */
     name: string;
+    /** Short model-visible description of when to use the skill. */
     description: string;
+    /** Full skill instructions. */
     content: string;
+    /** Absolute path to the skill file. Used for model-visible location and resolving relative references. */
     filePath: string;
+    /** Exclude this skill from model-visible skill lists while still allowing explicit application invocation. */
     disableModelInvocation?: boolean;
 }
+/** Prompt template that can be formatted into a prompt for explicit invocation. */
 export interface PromptTemplate {
+    /** Stable template name used for lookup or application command routing. */
     name: string;
+    /** Optional description for command lists or autocomplete. */
     description?: string;
+    /** Template content. Argument placeholders are formatted by `formatPromptTemplateInvocation`. */
     content: string;
 }
+/** Resources made available to explicit invocation methods and system-prompt callbacks. */
 export interface AgentHarnessResources<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
+    /** Prompt templates available for explicit invocation. */
     promptTemplates?: TPromptTemplate[];
+    /** Skills available to the model and explicit skill invocation. */
     skills?: TSkill[];
 }
+/** Curated provider request options owned by the harness and snapshotted per turn. */
 export interface AgentHarnessStreamOptions {
+    /** Preferred transport forwarded to the stream function. */
     transport?: Transport;
+    /** Provider request timeout in milliseconds. */
     timeoutMs?: number;
+    /** Maximum provider retry attempts. */
     maxRetries?: number;
+    /** Optional cap for provider-requested retry delays. */
     maxRetryDelayMs?: number;
+    /** Additional request headers merged with auth and lifecycle headers. */
     headers?: Record<string, string>;
+    /** Provider metadata forwarded with requests. */
     metadata?: SimpleStreamOptions["metadata"];
+    /** Provider cache retention hint. */
     cacheRetention?: SimpleStreamOptions["cacheRetention"];
 }
+/** Per-request stream option patch returned by provider hooks. */
 export interface AgentHarnessStreamOptionsPatch extends Omit<Partial<AgentHarnessStreamOptions>, "headers" | "metadata"> {
+    /** Header patch. `undefined` values delete keys; explicit `headers: undefined` clears all headers. */
     headers?: Record<string, string | undefined>;
+    /** Metadata patch. `undefined` values delete keys; explicit `metadata: undefined` clears all metadata. */
     metadata?: Record<string, unknown>;
 }
+/** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */
 export type FileKind = "file" | "directory" | "symlink";
-export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported" | "already_exists" | "timeout" | "transport_lost" | "unknown";
+/** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported"
+/** Exclusive create refused because the path already exists ({@link FileSystem.writeFileExclusive},
+ *  POSIX `O_EXCL` shape). Discriminable so a caller can distinguish "lost the create race" from a
+ *  write failure and give honest guidance instead of overwriting. */
+ | "already_exists"
+/** A remote fs RPC exceeded its liveness/idle bound (a hung provider call) — retryable by the caller per
+ *  the op's idempotency. Mirrors `RemoteExecutionError` code `"timeout"` so a remote `FileSystem` op can
+ *  surface a hang as a typed, retryable error instead of `"unknown"` (core src/core/remote-env.ts contract;
+ *  VENDOR.md mod #6 / service[45]/[49] class-fix). */
+ | "timeout"
+/** The transport carrying a remote fs op dropped mid-session (SSH channel death, ADB device offline) —
+ *  retryable after reconnect. Mirrors `RemoteExecutionErrorCode` `"transport_lost"`, same precedent as
+ *  `"timeout"` above (VENDOR.md mod #9 / service[63] SSH/ADB adapters), so a retry whitelist can see it
+ *  instead of an opaque `"unknown"`. */
+ | "transport_lost" | "unknown";
+/** Error returned by {@link FileSystem} file operations. */
 export declare class FileError extends Error {
+    /** Backend-independent error code. */
     code: FileErrorCode;
+    /** Absolute addressed path associated with the failure, when available. */
     path?: string;
     constructor(code: FileErrorCode, message: string, path?: string, cause?: Error);
 }
-export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "callback_error" | "transport_lost" | "suspended" | "auth_failed" | "unknown";
+/** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */
+export type ExecutionErrorCode = "aborted" | "timeout"
+/** The shell binary/config could not be resolved BEFORE spawning — the command never started. */
+ | "shell_unavailable"
+/** CONTRACT (2026-07-13, TB cwd-poison batch): spawn_error MUST mean the command NEVER STARTED (the
+ *  OS-level spawn itself failed: dead cwd, missing binary, EMFILE/ENOMEM…). The Bash tool reroutes
+ *  spawn_error + shell_unavailable to a STRUCTURAL error (throw → isError:true) and runs a dead-cwd
+ *  diagnosis on them; an env that maps "command ran and failed" onto spawn_error breaks that
+ *  semantics. Remote env implementers: map post-start failures to exit codes / transport_lost. */
+ | "spawn_error" | "callback_error"
+/** The transport carrying a remote exec dropped mid-session (SSH channel death without exit-status, ADB
+ *  device offline) — the command's outcome is UNKNOWN (it may have kept running); retry only per the op's
+ *  idempotency, after reconnect. Mirrors `RemoteExecutionErrorCode` `"transport_lost"` (VENDOR.md mod #9 /
+ *  service[63] SSH/ADB adapters). */
+ | "transport_lost"
+/** The workspace is (or became) SUSPENDED — its VM is paused, so the command NEVER STARTED and never
+ *  will until the task is resumed. Mirrors `RemoteExecutionErrorCode` `"suspended"`, same precedent as
+ *  `"timeout"`/`"transport_lost"` (RB-439-a): without it a paused-workspace refusal collapsed into
+ *  `"unknown"`, and the model was told the same generic sentence it gets for an unclassified provider
+ *  fault — so it re-issued the command instead of asking for a resume. Not retryable in place. */
+ | "suspended"
+/** Authentication to the remote target was PERMANENTLY rejected (revoked token, refused key) — the
+ *  command never started, and every retry will fail the same way (and may lock the account). Mirrors
+ *  `RemoteExecutionErrorCode` `"auth_failed"`; deliberately NOT a mirror of `auth_transient`, which an
+ *  adapter retries internally per its own bounded policy rather than surfacing as an exec outcome. */
+ | "auth_failed" | "unknown";
+/** Error returned by {@link ExecutionEnv.exec}. */
 export declare class ExecutionError extends Error {
+    /** Backend-independent error code. */
     code: ExecutionErrorCode;
+    /**
+     * TB triple-fake-green report (2026-07-13) — output produced BEFORE the failure, for the
+     * ran-then-cut codes (`timeout` / `aborted` / `callback_error`; the last is a command that
+     * started and was then killed because a host-side output callback failed — its completion was
+     * never observed, but its captured output is real work). CC anchor (2.1.206 BashTask settle): a
+     * timed-out command keeps ALL captured stdout/stderr and only APPENDS a "Command timed out after
+     * X" line — discarding 600s of build logs forces the model to rerun blind. Optional: envs that
+     * cannot capture partial output simply omit these; never-started codes
+     * (spawn_error/shell_unavailable) have no output by definition.
+     */
     partialStdout?: string;
     partialStderr?: string;
     constructor(code: ExecutionErrorCode, message: string, cause?: Error, partial?: {
@@ -58,73 +149,158 @@ export declare class ExecutionError extends Error {
         stderr?: string;
     });
 }
+/** Stable compaction error codes returned by compaction helpers. */
 export type CompactionErrorCode = "aborted" | "summarization_failed" | "invalid_session" | "unknown";
+/** Error returned by compaction helpers. */
 export declare class CompactionError extends Error {
+    /** Backend-independent error code. */
     code: CompactionErrorCode;
     constructor(code: CompactionErrorCode, message: string, cause?: Error);
 }
 export type SessionErrorCode = "not_found" | "invalid_session" | "invalid_entry" | "invalid_fork_target" | "storage" | "conflict" | "unknown";
+/** Error thrown by session storage, repositories, and session tree operations. */
 export declare class SessionError extends Error {
+    /** Session subsystem error code. */
     code: SessionErrorCode;
     constructor(code: SessionErrorCode, message: string, cause?: Error);
 }
 export type AgentHarnessErrorCode = "busy" | "invalid_state" | "invalid_argument" | "session" | "hook" | "auth" | "compaction" | "unknown";
+/** Public AgentHarness failure with a stable top-level classification. */
 export declare class AgentHarnessError extends Error {
     code: AgentHarnessErrorCode;
     constructor(code: AgentHarnessErrorCode, message: string, cause?: Error);
 }
+/** Metadata for one filesystem object in a {@link FileSystem}. */
 export interface FileInfo {
+    /** Basename of {@link path}. */
     name: string;
+    /** Absolute, syntactically normalized addressed path in the execution environment. Symlinks are not followed. */
     path: string;
+    /** Object kind. Symlink targets are not followed; use {@link FileSystem.canonicalPath} explicitly. */
     kind: FileKind;
+    /** Size in bytes for the addressed filesystem object. */
     size: number;
+    /** Modification time as milliseconds since Unix epoch. */
     mtimeMs: number;
 }
+/** Options for {@link Shell.exec}. */
 export interface ExecutionEnvExecOptions {
+    /** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */
     cwd?: string;
+    /** Additional environment variables for the command. Values override the environment defaults. Defaults to no overrides. */
     env?: Record<string, string>;
+    /** Timeout in seconds. Implementations should return a timeout error when the command exceeds this duration. Defaults to no timeout. */
     timeout?: number;
+    /** Abort signal used to terminate the command. Defaults to no abort signal. */
     abortSignal?: AbortSignal;
+    /** Called with stdout chunks as they are produced. */
     onStdout?: (chunk: string) => void;
+    /** Called with stderr chunks as they are produced. */
     onStderr?: (chunk: string) => void;
+    /**
+     * VENDORED EDIT (design/116 detach, 飞轮 [C]): when fired mid-run, an env that supports detach ADOPTS the
+     * running child as a background process (its handle never leaves the env) and settles the exec with a
+     * `detached` marker instead of killing it. Envs without detach support ignore this (the exec runs on).
+     */
     detachSignal?: AbortSignal;
+    /**
+     * RB-198 F1 (form-one audit, CC 220 `Zry`/`WZi.#m` parity) — when this command's OWN timeout
+     * fires, an env that supports detach ADOPTS the running child as a background process (the same
+     * mechanism `detachSignal` uses) instead of killing it, settling the exec with
+     * `detached: {shellId, cause:"timeout"}` — a non-idempotent long command survives its own timeout
+     * instead of being SIGKILLed mid-flight and forcing a blind re-run. The CALLER decides eligibility
+     * (bash-specific command-shape knowledge the env itself does not have — same division of labor as
+     * `detachSignal` being caller-fired); a `false`/absent value keeps the pre-existing kill-on-timeout
+     * behavior. Envs without detach support ignore this (opt-in, backward compatible).
+     */
     autoBackgroundOnTimeout?: boolean;
 }
+/**
+ * Filesystem capability used by the harness.
+ *
+ * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by file operations are addressed paths
+ * in the filesystem namespace, but are not canonicalized through symlinks unless returned by {@link canonicalPath}.
+ *
+ * Operation methods must never throw or reject. All filesystem failures, including unexpected backend failures, must be
+ * encoded in the returned {@link Result}. Implementations must preserve this invariant.
+ */
 export interface FileSystem {
+    /** Current working directory for relative paths. */
     cwd: string;
+    /** Return an absolute addressed path without requiring it to exist and without resolving symlinks. */
     absolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Join path segments in the filesystem namespace without requiring the result to exist. */
     joinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Read a UTF-8 text file. */
     readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Read UTF-8 text lines. Implementations should stop once `maxLines` lines have been read. */
     readTextLines(path: string, options?: {
         maxLines?: number;
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
+    /** Read a binary file. */
     readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** Create or overwrite a file, creating parent directories when supported. Implementation note
+     *  (RB-221 [1937]): the Node env replaces the file as a WHOLE (same-directory staging + fsync +
+     *  rename; `aborted` ⇒ target untouched), falling back to an in-place rewrite where rename cannot
+     *  apply (cross-device, symlink chains, non-regular targets, read-only parent dir). Atomicity is an
+     *  implementation quality, NOT an interface-level contract — a remote/transport env may only have a
+     *  plain in-place write. */
     writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /**
+     * OPTIONAL atomic exclusive create (KNOWN-ISSUES Edit-as-create TOCTOU close-out): create `path` with
+     * `content` ONLY when nothing exists there, in ONE atomic backend step (POSIX `O_CREAT|O_EXCL` / Node
+     * `wx` flag shape). An existing file fails with {@link FileError} code `"already_exists"` and is never
+     * truncated or overwritten. Parent directories are created when supported, same as {@link writeFile}.
+     *
+     * Degradation contract: an env whose backend has NO exclusive-create primitive (e.g. a remote transport
+     * that can only exists+write in two round-trips) MUST leave this `undefined` rather than emulate it —
+     * a two-step emulation re-opens the very TOCTOU window this method exists to close, behind an
+     * atomic-looking face. Callers that find it `undefined` fall back to their own explicit non-atomic
+     * emulation and own the residual race.
+     */
     writeFileExclusive?(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Create or append to a file, creating parent directories when supported. */
     appendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** Return metadata for the addressed path without following symlinks. */
     fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+    /** List direct children of a directory without following symlinks. */
     listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+    /** Return the canonical path for an existing path, resolving symlinks where supported. */
     canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /**
+     * VENDORED EDIT (design/72 §2.1, additive/backward-compatible): read a symlink's raw target (one
+     * hop, NOT followed). Optional — an env that omits it falls back to best-effort canonicalization
+     * for a DANGLING leaf symlink (a symlink whose target doesn't exist yet, which `canonicalPath`'s
+     * `realpath` can't resolve). Needed so a sensitive-path guard / containment check sees the real
+     * target of `write_file innocent.txt` where `innocent.txt -> .git/hooks/payload`.
+     */
     readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
     exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** Create a directory. Defaults: `recursive: true`, no abort signal. */
     createDir(path: string, options?: {
         recursive?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
+    /** Remove a file or directory. Defaults: `recursive: false`, `force: false`, no abort signal. */
     remove(path: string, options?: {
         recursive?: boolean;
         force?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
+    /** Create a temporary directory and return its absolute path. Defaults: `prefix: "tmp-"`, no abort signal. */
     createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** Create a temporary file and return its absolute path. Defaults: `prefix: ""`, `suffix: ""`, no abort signal. */
     createTempFile(options?: {
         prefix?: string;
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /** Release filesystem resources. Must be best-effort and must not throw or reject. */
     cleanup(): Promise<void>;
 }
+/** Result payload for {@link Shell.exec}. */
 export interface ExecResult {
     stdout: string;
     stderr: string;
@@ -134,33 +310,74 @@ export interface ExecResult {
         cause?: "timeout";
     };
 }
+/** Shell execution capability used by the harness. */
 export interface Shell {
+    /** Execute a shell command in {@link FileSystem.cwd} unless `options.cwd` is provided. */
     exec(command: string, options?: ExecutionEnvExecOptions): Promise<Result<ExecResult, ExecutionError>>;
+    /** Release shell resources. Must be best-effort and must not throw or reject. */
     cleanup(): Promise<void>;
 }
+/** Filesystem and process execution environment used by the harness. */
 export interface ExecutionEnv extends FileSystem, Shell {
+    /**
+     * design/164 件四 — the environment's PLATFORM LIFETIME in milliseconds: how long this sandbox/VM is
+     * allowed to exist before the platform reclaims it, counted from {@link lifetimeStartedAt}. Declared by
+     * the ADAPTER, never by the task: sandbox lifetimes are a platform fact (minutes to a day, depending on
+     * the backend and tier), so the engine holds no number of its own and a local Node environment simply
+     * omits the field (⇒ unbounded, the pre-164 behavior).
+     *
+     * The engine reads it at every clean turn boundary: once `anchor + lifetimeMs − ENV_LIFETIME_SUSPEND_MARGIN_MS`
+     * has passed, the run either suspends into a durable checkpoint (`reason: "env_lifetime"`) or, when the
+     * deployment cannot suspend durably, stops LOUDLY with `env.lifetime_expired` — instead of being killed
+     * mid-turn by the platform with no record of where it got to.
+     *
+     * Must be a finite, positive number of ms; anything else is refused at the door (`config.env_lifetime_invalid`)
+     * rather than folded to a default, because an unevaluable lifetime is not a lifetime.
+     */
     readonly lifetimeMs?: number;
+    /**
+     * design/164 件四 — epoch ms at which this environment's {@link lifetimeMs} started running: the moment
+     * the PLATFORM created the sandbox, which is the only honest anchor. Self-reported because the engine
+     * cannot observe it: an env handed to the Runner may have been created long before this task (a shared
+     * static env), and a resumed sandbox carries the age of its original creation.
+     *
+     * Omitted ⇒ the engine falls back to the instant its own `executionEnvFactory` returned the env, which is
+     * accurate only for an env minted FOR this run. An env that declares `lifetimeMs` WITHOUT this anchor and
+     * was NOT minted by the factory (a caller-owned static env) leaves the engine no way to age it — the
+     * lifetime is then reported as unarmable through `onError` and NOT enforced, because the only guess
+     * available (task start) overestimates the remaining lifetime, i.e. errs toward the failure this whole
+     * mechanism exists to prevent.
+     */
     readonly lifetimeStartedAt?: number;
 }
+/** Base fields shared by append-only session tree entries. */
 export interface SessionTreeEntryBase {
+    /** Entry discriminator used for JSONL persistence and typed narrowing. */
     type: string;
+    /** Stable entry id unique within a session file. */
     id: string;
+    /** Parent entry id, or null for a root entry. */
     parentId: string | null;
+    /** ISO timestamp string used for persistence and sorting. */
     timestamp: string;
 }
+/** Persisted transcript message entry. */
 export interface MessageEntry extends SessionTreeEntryBase {
     type: "message";
     message: AgentMessage;
 }
+/** Persisted thinking-level selection marker. */
 export interface ThinkingLevelChangeEntry extends SessionTreeEntryBase {
     type: "thinking_level_change";
     thinkingLevel: string;
 }
+/** Persisted model selection marker. */
 export interface ModelChangeEntry extends SessionTreeEntryBase {
     type: "model_change";
     provider: string;
     modelId: string;
 }
+/** Persisted summary that replaces older transcript history in context. */
 export interface CompactionEntry<T = unknown> extends SessionTreeEntryBase {
     type: "compaction";
     summary: string;
@@ -169,11 +386,13 @@ export interface CompactionEntry<T = unknown> extends SessionTreeEntryBase {
     details?: T;
     fromHook?: boolean;
 }
+/** Persisted harness/application marker that is not replayed into model context. */
 export interface CustomEntry<T = unknown> extends SessionTreeEntryBase {
     type: "custom";
     customType: string;
     data?: T;
 }
+/** Persisted harness/application message that can be replayed into model context. */
 export interface CustomMessageEntry<T = unknown> extends SessionTreeEntryBase {
     type: "custom_message";
     customType: string;
@@ -181,44 +400,105 @@ export interface CustomMessageEntry<T = unknown> extends SessionTreeEntryBase {
     details?: T;
     display: boolean;
 }
+/** Append-only label update for another session entry. */
 export interface LabelEntry extends SessionTreeEntryBase {
     type: "label";
     targetId: string;
     label: string | undefined;
 }
+/** Persisted session metadata marker. */
 export interface SessionInfoEntry extends SessionTreeEntryBase {
     type: "session_info";
     name?: string;
 }
+/** Append-only marker that changes the active visible leaf. */
 export interface LeafEntry extends SessionTreeEntryBase {
     type: "leaf";
     targetId: string | null;
 }
+/**
+ * Prompt-epoch pin (campaign S3, prompt-assembly protocol §9.2) — a FIRST-CLASS typed entry (not a
+ * forgeable generic `custom` entry): which prompt-pack artifact this session is pinned to. Written
+ * at session start (before the first conversation entry) and on legacy migration; every compaction
+ * RESTATES the then-current descriptor inside its own `details.promptEpoch` (same-CAS atomicity,
+ * bounded-tail recoverable). Fields mirror `PromptEpochDescriptor` (src/prompt-assembly/epoch.ts).
+ */
 export interface PromptEpochEntry extends SessionTreeEntryBase, PromptEpochDescriptor {
     type: "prompt_epoch";
 }
+/**
+ * design/150 (RB-25 终态): the listing ANNOUNCED name-sets as a FIRST-CLASS typed entry — which
+ * agent roster / skills / model catalog the model has actually been told about on this branch.
+ * SNAPSHOT semantics (not deltas): the nearest entry on the branch IS the announced state — rosters
+ * are bounded, so replay is a single read, never text parsing of engine-minted transcript frames.
+ * Written best-effort at every listing COMMIT point (first-frame delivery / intact boundary
+ * survival); the checkpoint mirror (`CheckpointState.announcedListings`) and the transcript-probe
+ * replay remain as the second/third rungs of the resume-seed ladder for pre-entry sessions.
+ * Present-only arms — an absent arm means "no announcement recorded for that face", same Q5
+ * discipline as the checkpoint mirror.
+ */
 export interface AnnouncedListingEntry extends SessionTreeEntryBase {
     type: "announced_listing";
     agents?: string[];
     skills?: string[];
     models?: string[];
 }
+/**
+ * REF-D3/D4 merge target: the active EnterWorktree session (M22 live-CC anchor, codex 终审 1.255 F2 —
+ * plain strings only, no closures, so it survives a durable suspend into `CheckpointState.activeWorktree`
+ * verbatim). Canonical definition — `tools/worktree.ts` (the tool pair that owns this durably) re-exports
+ * this type rather than declaring its own copy: the harness layer must never import FROM `tools/`
+ * (that would invert the layering), so the shared shape lives here and the tool-level module points back
+ * at it.
+ *
+ *  `entered`: true when the session ENTERED a pre-existing worktree via `path` instead of creating one —
+ *  ExitWorktree then never removes it ("ExitWorktree will not remove a worktree entered this way").
+ *  Absent/false = created by EnterWorktree (removable per the normal rules).
+ */
 export interface ActiveWorktreeSession {
     worktreeDir: string;
     originalCwd: string;
     baseSha: string;
     entered?: boolean;
 }
+/**
+ * REF-D3/D4 merge target: the session's WORKSPACE STATE container (nests {@link ActiveWorktreeSession}) —
+ * see {@link WorkspaceStateEntry} for the durable-entry narrative this type also backs.
+ */
 export interface WorkspaceState {
+    /** The canonical task root these paths were recorded against (the rebase base). */
     taskRoot: string;
+    /** The tracked logical cwd at settle; ABSENT ⇒ the task root (no tracked `cd` outstanding). */
     handsCwd?: string;
+    /** The active EnterWorktree session at settle; ABSENT ⇒ none. */
     activeWorktree?: ActiveWorktreeSession;
 }
+/**
+ * design/155 (cli [1580]): the session's WORKSPACE STATE at a task settle — the tracked logical cwd
+ * and the active EnterWorktree session. Ordinary continuation turns (a new task on the same
+ * `spec.sessionId`) have NO checkpoint seed, so without this entry both refs silently reset to the
+ * task root every turn (cd doesn't stick, ExitWorktree no-ops, the worktree leaks). Restore ladder
+ * (same rung doctrine as the announced-listing, design/150 RB-25): the checkpoint seed stays FIRST on
+ * a durable resume (cut atomically with the leaf); the branch-nearest entry of this type is the
+ * SECOND rung (plain continuations); fresh defaults last. SNAPSHOT semantics — nearest wins; a
+ * settle that returned to the default state writes a CLEAR entry (`handsCwd`/`activeWorktree` both
+ * absent) so a stale earlier snapshot cannot shadow it. Paths are recorded against `taskRoot` and
+ * rebased on read when the continuing task runs under a different root.
+ */
 export interface WorkspaceStateEntry extends SessionTreeEntryBase, WorkspaceState {
     type: "workspace_state";
 }
+/** Bounded cap for {@link normalizeWorkspaceState} paths (a sha is capped by its hex shape check). */
 export declare const WORKSPACE_STATE_MAX_PATH_CHARS = 4096;
+/**
+ * design/155: strict shape gate for the workspace-state snapshot — the SINGLE normalization the
+ * read walk, the public append, and the import-validate door all use (same posture as
+ * {@link normalizeAnnouncedListing}). Returns a shaped copy carrying ONLY the known keys, or
+ * undefined when the value is not structurally valid.
+ */
 export declare function normalizeWorkspaceState(value: unknown): WorkspaceState | undefined;
+/** Bounded caps for {@link normalizeAnnouncedListing} — a roster is dozens of names, never thousands;
+ *  a "name" is a short identifier, never a document. Oversize ⇒ structurally invalid (forgery signal). */
 export declare const ANNOUNCED_LISTING_MAX_NAMES = 500;
 export declare const ANNOUNCED_LISTING_MAX_NAME_CHARS = 200;
 export declare function normalizeCompactionStateCarrier(v: unknown): {
@@ -228,6 +508,14 @@ export declare function normalizeCompactionStateCarrier(v: unknown): {
         modelId: string;
     } | null;
 };
+/**
+ * RB-128 (2026-07-25, defect probe): the SAME two values also arrive as first-class entries, and those
+ * had no door at all — so RB-121 gated the weaker of two channels. `buildSessionContext` runs the carrier
+ * seed BEFORE the entry scan, which means an ungated `thinking_level_change` / `model_change` OVERRIDES the
+ * gated carrier: the property RB-121's own doc claims ("an imported entry could name any string as the
+ * branch's thinking level and any provider/model as its active model") stayed true through the other door.
+ * Same shapes, one predicate, both channels.
+ */
 export declare function isValidThinkingLevelChange(e: {
     thinkingLevel?: unknown;
 }): boolean;
@@ -235,12 +523,17 @@ export declare function isValidModelChange(e: {
     provider?: unknown;
     modelId?: unknown;
 }): boolean;
+/** RB-128: a `label` / `session_info.name` that is not a string reaches `.trim()` inside
+ *  `BaseSessionStorage`'s CONSTRUCTOR — and the file backend validates BEFORE constructing any storage, so
+ *  the poison lands on disk and every later `open()` throws a raw `TypeError` (not even a `SessionError`).
+ *  Unrecoverable through the API, which is why this belongs at the import door. */
 export declare function isOptionalDisplayString(v: unknown, max?: number): boolean;
 export declare function normalizeAnnouncedListing(v: unknown): {
     agents?: string[];
     skills?: string[];
     models?: string[];
 } | undefined;
+/** All persisted session tree entry variants. */
 export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | WorkspaceStateEntry;
 export interface SessionContext {
     messages: AgentMessage[];
@@ -253,6 +546,11 @@ export interface SessionContext {
 export interface SessionMetadata {
     id: string;
     createdAt: string;
+    /** F7 fork-GC seam (1.175 known-limitation closed 2026-07-11): the PARENT session this one was forked
+     *  from, stamped by every `SessionRepo.fork` implementation. Durable fork sessions have no core GC
+     *  path by design — a deployment's retention/reap (service, design/109 family) reads this to identify
+     *  fork lineage (e.g. reap forks whose parent is gone/expired). Absent on a non-forked session and on
+     *  forked sessions persisted before this field shipped. */
     forkedFrom?: string;
 }
 export interface JsonlSessionMetadata extends SessionMetadata {
@@ -260,12 +558,24 @@ export interface JsonlSessionMetadata extends SessionMetadata {
     path: string;
     parentSessionPath?: string;
 }
+/**
+ * Optimistic-lock options for session writes (F2). A durable backend uses `expectedLeafId` to make
+ * the write conditional — preventing cross-instance split-brain, where two stateless runners that
+ * both woke the same session append to the same parent and one branch is silently abandoned.
+ */
 export interface SessionWriteOptions {
+    /**
+     * Apply only if the current branch leaf still equals this value; on mismatch the storage throws
+     * `SessionError("conflict")`. Omit (the default) to write unconditionally. `null` means "expect an
+     * empty session". A durable backend turns this into a compare-and-set (e.g. a `(session_id, seq)`
+     * unique-key insert); the in-process base storage checks it against its in-memory leaf.
+     */
     expectedLeafId?: string | null;
 }
 export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetadata> {
     getMetadata(): Promise<TMetadata>;
     getLeafId(): Promise<string | null>;
+    /** Persist a leaf entry that records the active session-tree leaf. */
     setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;
     createEntryId(): Promise<string>;
     appendEntry(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
@@ -276,6 +586,21 @@ export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetad
     getLabel(id: string): Promise<string | undefined>;
     getPathToRoot(leafId: string | null): Promise<SessionTreeEntry[]>;
     getEntries(): Promise<SessionTreeEntry[]>;
+    /**
+     * Campaign S3 / RB-14 seam (blackboard [975] joint verdict): OPTIONAL epoch anchor for
+     * bounded-tail backends. A durable backend that loads only `firstKeptEntryId..leaf` cannot show
+     * the branch walk an epoch carrier when a rewind cuts BEFORE the latest compaction's restatement
+     * (window: firstKept ≤ cut < compactionEntry) — `Session.getPromptEpoch()` falls back to this
+     * method when the loaded branch has no carrier. Implementations return the descriptor from the
+     * nearest carrier BELOW the load floor (a `prompt_epoch` entry or a compaction restatement), or
+     * undefined when none exists (a genuinely pre-epoch session). File/in-memory backends need not
+     * implement it (their walks see the full tree).
+     */
+    /** RB-104 (2026-07-25, defect probe): the bounded-window root this storage was woken with (F3), or
+     *  null/absent for a full-tree load. Optional — a backend that never bounds its wake omits it. Callers
+     *  use it to tell a LEGITIMATE headless window (its head's parent lives below the declared floor) apart
+     *  from a CORRUPT log (a head whose parent is simply missing); the two look identical byte-wise and
+     *  must not be treated alike. `BaseSessionStorage` implements it for the bundled backends. */
     getFloorId?(): string | null;
     getEpochAnchor?(): Promise<{
         epoch: number;
@@ -285,10 +610,26 @@ export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetad
         activatedBy: "session_start" | "compaction" | "legacy_migration";
     } | undefined>;
 }
+/**
+ * Options for `buildContext`/`buildSessionContext` — the read-side window awareness seam.
+ * `windowTokens` arms a DEFENSIVE re-clamp of the compaction summary's retained invoked-skills
+ * area against the CURRENT model's window (the area was budgeted at compaction time against the
+ * model active THEN; a later, smaller-window model must not inherit an area that alone overflows
+ * its window). `charsPerToken` is the structural coefficient for that clamp (default 4). Absent ⇒
+ * legacy behavior, byte-identical context.
+ */
 export interface BuildContextOptions {
     windowTokens?: number;
     charsPerToken?: number;
 }
+/**
+ * The session CONTRACT the harness consumes (`Session`) — dependency inversion: the substrate defines the
+ * interface it needs; the application provides the implementation. Replaces a vendored→first-party
+ * `import type { Session }` coupling — the vendored harness no longer reaches into `engine/session/session.ts`
+ * for a concrete type, so the substrate is self-contained for the planned de-vendoring. The first-party
+ * `class Session` `implements Session`. (Named `Session`, not `Session`, so it coexists with the public,
+ * constructable `class Session` without a breaking public-API change.)
+ */
 export interface Session<TMetadata extends SessionMetadata = SessionMetadata> {
     getMetadata(): Promise<TMetadata>;
     getStorage(): SessionStorage<TMetadata>;
@@ -307,18 +648,31 @@ export interface Session<TMetadata extends SessionMetadata = SessionMetadata> {
     appendCustomMessageEntry(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: unknown): Promise<string>;
     appendLabel(targetId: string, label: string | undefined): Promise<string>;
     appendSessionName(name: string): Promise<string>;
+    /** design/150 (RB-25): persist the listing announced name-sets as a first-class
+     *  {@link AnnouncedListingEntry} (snapshot semantics; see `Session.appendAnnouncedListing`). */
     appendAnnouncedListing(snapshot: {
         agents?: readonly string[];
         skills?: readonly string[];
         models?: readonly string[];
     }): Promise<string>;
+    /** design/150 (RB-25): nearest announced-listing snapshot on the active branch (first rung of the
+     *  resume-seed ladder); undefined ⇒ pre-entry session. */
     getAnnouncedListing(): Promise<{
         agents?: string[];
         skills?: string[];
         models?: string[];
     } | undefined>;
+    /** design/155: persist the settle-time workspace state (tracked cwd + active worktree) as a
+     *  first-class {@link WorkspaceStateEntry} (snapshot semantics; see `Session.appendWorkspaceState`). */
     appendWorkspaceState(state: WorkspaceState): Promise<string>;
+    /** design/155: nearest workspace-state snapshot on the active branch (the continuation rung of the
+     *  cwd/worktree restore ladder — the checkpoint seed stays first); undefined ⇒ no snapshot visible. */
     getWorkspaceState(): Promise<WorkspaceState | undefined>;
+    /** The branch's current prompt-epoch descriptor (semantics: `Session.getPromptEpoch`). OPTIONAL on
+     *  the interface (typecheck 车 2026-07-24): the built-in `Session` class always implements it;
+     *  optionality keeps external `Session` implementers compatible. The consumer (`maybeCompact`'s
+     *  epoch restatement) calls it with `?.()` — an implementer without it degrades to the pre-epoch
+     *  path (no restatement), never a crash. */
     getPromptEpoch?(): Promise<import("../../prompt-assembly/epoch.js").PromptEpochDescriptor | undefined>;
 }
 export interface SessionCreateOptions {
@@ -335,7 +689,27 @@ export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata
     list(options?: TListOptions): Promise<TMetadata[]>;
     delete(metadata: TMetadata): Promise<void>;
     fork(source: TMetadata, options: SessionForkOptions & TCreateOptions): Promise<Session<TMetadata>>;
+    /**
+     * 2c session-sync (service [266]②): the FULL durable entry log for `sessionId`, oldest-first, with
+     * `id`/`parentId` VERBATIM and BYPASSING any compaction floor — NOT `getEntries()`, which on a durable
+     * backend that woke with a bounded F3 window returns only the tail (silently truncating pre-floor history).
+     * Optional — a backend that supports cross-backend session export/migration implements it.
+     */
     exportEntries?(sessionId: string): Promise<SessionTreeEntry[]>;
+    /**
+     * 2c session-sync: write a verbatim entry log (produced by {@link exportEntries} on another backend) into
+     * `sessionId`, re-stamping ownership to `owner` (from the caller's authenticated principal — never trusted
+     * from the bundle). The log MUST be passed through `validateEntriesForImport` first (the single fail-closed
+     * invariant gate); a durable backend persists THAT function's output, it does not re-implement the checks.
+     * Optional.
+     *
+     * design/171 §6.4 — `options.preserveActorAssertions` is the OPERATOR-level trusted-import
+     * declaration, threaded verbatim into the validator: default (absent/false) strips `actor`
+     * attribution from imported history (an importer is not an ingress); `true` = the operator vouches
+     * for the source (same-deployment migration) and well-formed assertions survive. A backend that
+     * implements this method forwards the flag to its `validateEntriesForImport` call — the gate that
+     * actually persists decides, so a pre-validated array cannot be silently re-stripped.
+     */
     importEntries?(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
         preserveActorAssertions?: boolean;
     }): Promise<void>;
@@ -380,7 +754,9 @@ export interface ContextEvent {
     messages: AgentMessage[];
 }
 export interface TurnBoundaryEvent {
+    /** Fires between model-request boundaries, after session flush, before the context rebuild. */
     type: "turn_boundary";
+    /** The model that will run the next turn (authoritative under a mid-task model switch). */
     model: Model;
 }
 export interface BeforeProviderRequestEvent {
@@ -444,25 +820,52 @@ export interface ResourcesUpdateEvent<TSkill extends Skill = Skill, TPromptTempl
 }
 export type AgentHarnessOwnEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> = QueueUpdateEvent | SavePointEvent | AbortEvent | SettledEvent | BeforeAgentStartEvent<TSkill, TPromptTemplate> | ContextEvent | TurnBoundaryEvent | BeforeProviderRequestEvent | BeforeProviderPayloadEvent | AfterProviderResponseEvent | ToolCallEvent | ToolResultEvent | SessionBeforeCompactEvent | SessionCompactEvent | ModelSelectEvent | ThinkingLevelSelectEvent | ResourcesUpdateEvent<TSkill, TPromptTemplate>;
 export type AgentHarnessEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> = AgentEvent | AgentHarnessOwnEvent<TSkill, TPromptTemplate>;
+/** Hook result for mutating the initial prompt run before the agent starts. */
 export interface BeforeAgentStartResult {
+    /** Replacement messages for the prompt run. */
     messages?: AgentMessage[];
+    /** Replacement system prompt for the prompt run. */
     systemPrompt?: string;
 }
+/** Hook result for replacing the full context message list before provider conversion. */
 export interface ContextResult {
     messages: AgentMessage[];
 }
+/** Hook result for patching provider request options before payload construction. */
 export interface BeforeProviderRequestResult {
     streamOptions?: AgentHarnessStreamOptionsPatch;
 }
+/** Hook result for replacing the provider payload after construction. */
 export interface BeforeProviderPayloadResult {
     payload: unknown;
 }
+/**
+ * Hook result for blocking a tool call before execution, or rewriting its arguments.
+ *
+ * `block: true` blocks the call (`reason` becomes the error text). `updatedInput` (without `block`)
+ * rewrites the args the tool executes with — re-validated against the tool schema by the loop before
+ * execution (design/37). `block` wins over `updatedInput`.
+ *
+ * REF-D23 — this IS the loop's `BeforeToolCallResult`, not a hand-kept structural match of it. The
+ * `beforeToolCall` callback in agent-harness.ts returns the hook result verbatim, so the two shapes
+ * were never allowed to differ; the earlier "keep in sync" note asked a human to maintain by hand
+ * what the type system can state.
+ */
 export type ToolCallResult = BeforeToolCallResult;
+/**
+ * Hook patch for a completed tool result before it is persisted/emitted.
+ *
+ * REF-D23 — same relationship as {@link ToolCallResult}: this IS the loop's `AfterToolCallResult`.
+ * The `afterToolCall` callback forwards the hook result verbatim, so a field added on the loop side
+ * reaches the harness hook surface without a second edit here.
+ */
 export type ToolResultPatch = AfterToolCallResult;
+/** Hook result for cancelling or replacing a planned compaction. */
 export interface SessionBeforeCompactResult {
     cancel?: boolean;
     compaction?: CompactResult;
 }
+/** Typed return values expected from AgentHarness hook handlers by event type. */
 export type AgentHarnessEventResultMap = {
     before_agent_start: BeforeAgentStartResult | undefined;
     context: ContextResult | undefined;
@@ -482,22 +885,31 @@ export type AgentHarnessEventResultMap = {
     abort: undefined;
     settled: undefined;
 };
+/** Queued messages removed by an abort operation. */
 export interface AbortResult {
     clearedSteer: AgentMessage[];
     clearedFollowUp: AgentMessage[];
 }
+/** Compaction data supplied by hooks or returned from compaction preparation. */
 export interface CompactResult {
     summary: string;
     firstKeptEntryId: string;
     tokensBefore: number;
     details?: unknown;
 }
+/** Settings that control automatic context compaction. */
 export interface CompactionSettings {
     enabled: boolean;
     reserveTokens: number;
     keepRecentTokens: number;
+    /** design/145 §1 — window-safety clamp tolerance for an independent (smaller-window) compaction
+     *  model: when the summarization input would be clamp-truncated by MORE than this ratio, the
+     *  summary call becomes a candidate to fall back to the MAIN model (which is always window-safe).
+     *  0 = any truncation is a fallback candidate; 1 = never fall back (the pre-145 clamp-only
+     *  behavior). Default 0.10. */
     clampTolerance?: number;
 }
+/** Prepared compaction inputs exposed to hooks before a summary is generated. */
 export interface CompactionPreparation {
     firstKeptEntryId: string;
     messagesToSummarize: AgentMessage[];
@@ -508,15 +920,21 @@ export interface CompactionPreparation {
     fileOps: FileOperations;
     settings: CompactionSettings;
 }
+/** File operations accumulated from summarized transcript ranges. */
 export interface FileOperations {
     read: Set<string>;
     written: Set<string>;
     edited: Set<string>;
 }
+/** Construction options for AgentHarness. */
 export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate, TTool extends AgentTool = AgentTool> {
     env: ExecutionEnv;
     session: Session;
     tools?: TTool[];
+    /**
+     * Concrete resources available to explicit invocation methods and system-prompt callbacks.
+     * Applications own loading/reloading resources and should call `setResources()` with new values.
+     */
     resources?: AgentHarnessResources<TSkill, TPromptTemplate>;
     systemPrompt?: string | ((context: {
         env: ExecutionEnv;
@@ -526,6 +944,12 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
         activeTools: TTool[];
         resources: AgentHarnessResources<TSkill, TPromptTemplate>;
     }) => string | Promise<string>);
+    /**
+     * Campaign S4 (ADDITIVE): physical system blocks for block-aware Brains. Static per leg (same
+     * freeze semantics as a string `systemPrompt`). When present it MUST correspond to the same
+     * bytes as `systemPrompt` (the M13 projection duty is on the producer — prepare-task). Brains
+     * that ignore it read `systemPrompt` and lose nothing.
+     */
     systemBlocks?: Array<{
         text: string;
         cacheControlBoundary: boolean;
@@ -535,19 +959,57 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
         headers?: Record<string, string>;
     } | undefined>;
     runtime?: AgentCoreRuntimeDeps;
+    /** Curated stream/provider request options. Snapshotted at turn start. */
     streamOptions?: AgentHarnessStreamOptions;
     model: Model;
     thinkingLevel?: ThinkingLevel;
     activeToolNames?: string[];
     steeringMode?: QueueMode;
     followUpMode?: QueueMode;
+    /** design/119 #2: per-request output-token cap forwarded to the provider (`options.maxTokens`). */
     maxOutputTokens?: number;
+    /**
+     * design/130 P1: per-CALL dynamic output cap, evaluated by the loop immediately before EACH
+     * provider call. A number return overrides `maxOutputTokens` for that call only; undefined
+     * leaves the static chain untouched. Must be cheap (hot path).
+     */
     maxOutputTokensPerCall?: () => number | undefined;
+    /**
+     * 1.296 件A: per-CALL advisory stall watchdogs, evaluated by the loop immediately before EACH
+     * provider call and forwarded as `StreamOptions.stallTimeouts` (brain construction-time config
+     * wins when present — advisory, not an override). undefined return ⇒ nothing supplied.
+     */
     stallTimeoutsPerCall?: () => import("../llm/types.js").StallTimeouts | undefined;
+    /**
+     * Abort-classification seam for the loop's abort short-circuit tool results, forwarded verbatim
+     * to the loop config (`AgentLoopConfig.abortResultDetails`, see its JSDoc for the contract): a
+     * non-undefined return value becomes the minted result's `details` (e.g. `{ code: "gate.parked" }`
+     * when the host's durable approval gate parked the batch). Evaluated at mint time; the abort
+     * texts themselves never change.
+     */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /**
+     * service [398] C2: the loop's recovery/terminal trace sink, forwarded to `runAgentLoop`'s trace
+     * parameter (previously test-only — never passed in production, so the loop's six self-heal
+     * recoveries were invisible outside display:false nudge messages). Must not throw; hot path.
+     */
     loopTrace?: (step: import("../loop/agent-loop.js").LoopStep) => void;
+    /**
+     * design/131 (service [404] 拍): per-task resilience intent flags, forwarded to every provider
+     * call (`StreamOptions.resilience`) so the deployment's decorator stack (degrading / failover /
+     * breaker) can stand aside for this task. Absent ⇒ today's behavior.
+     */
     resilience?: import("../llm/types.js").ResilienceOptions;
+    /** design/120 P1: parallel-batch tool concurrency cap forwarded to the loop (default 10). */
     maxToolConcurrency?: number;
+    /**
+     * design/120 P2: opt in to in-stream tool execution (safe tool calls start while the model is
+     * still streaming). Default OFF. The harness forwards this to the loop ONLY when no `tool_call`
+     * hook handler is registered at run start (snapshot per prompt()) — a policy/approval gate on
+     * that hook could durably suspend, which has no stable leaf mid-stream. Hosts that register a
+     * suspending `tool_call` handler mid-run after opting in get undefined behavior (documented
+     * contract, see AgentLoopConfig.streamingToolExecution).
+     */
     streamingToolExecution?: boolean;
 }
 export type { AgentHarness } from "./agent-harness.js";