@sema-agent/core 5.20.0 → 5.21.0

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -3,12 +3,53 @@ import type { BackgroundShellCapability, BackgroundShellId, BackgroundPoll, Back
 import { BackgroundShellError } from "../../core/background-shell.js";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "../../core/scheduler.js";
 import { SchedulerError } from "../../core/scheduler.js";
+/** Convert user-facing timeout seconds into a positive, timer-safe millisecond delay. */
 export declare function resolveExecTimeoutMs(timeoutSeconds: unknown): number | undefined;
+/** service [377] review finding (win32): `where bash.exe` can resolve to `System32\bash.exe` — the
+ *  WSL LAUNCHER, not a native shell. Running it drops into a Linux subsystem where Windows cwd/paths
+ *  do not exist; silently adopting it is exactly the "wrong shell, false green" failure D1 forbids.
+ *  Filter it (and the WindowsApps alias) out of PATH discovery; Git-Bash candidates are tried first. */
 export declare function isWslBashLauncher(p: string): boolean;
+/** Shell discovery for the platform (service [377] ask ①: exported as the single SDK source so a host
+ *  adapter does not mirror the platform logic). Explicit `customShellPath` wins (missing → err);
+ *  win32 = Git-Bash discovery (ProgramFiles → PATH, WSL launcher filtered) with fail-loud
+ *  `shell_unavailable` (never a silent cmd.exe fallback); POSIX = /bin/bash → PATH bash → sh. */
 export declare function getShellConfig(customShellPath?: string): Promise<Result<{
     shell: string;
     args: string[];
 }, ExecutionError>>;
+/** RB-235 ([1937] BB2): the spool-reclaim decision, extracted PURE so every rule is unit-pinnable.
+ *  Both reclaim sites (foreground `reclaimSpool`, background `syncSpool`) route through this one
+ *  function so they cannot drift apart.
+ *
+ *  The hazard: `truncateSync(path, 0)` while the writer is LIVE races its O_APPEND appends — a
+ *  buffered write landing between the caller's stat and the truncate is destroyed whole
+ *  (stdio-block granularity) and NO reader-side counter ever sees it (`truncated` /
+ *  `bytesDroppedBeforeCursor` / `bytesFromStart` all undercount by exactly the raced amount). An
+ *  earlier narrowing kept the truncate but moved it to the HARD cap, so live truncations became rare
+ *  instead of routine; an external black-box audit of that build still measured whole 8192-byte
+ *  blocks disappearing, so rarity was never the fix. Ruled 2026-08-03: drop truncate-under-a-live-
+ *  writer entirely.
+ *
+ *  The rule, in one line: **the file of a writer that can still append is append-only.** While the
+ *  writer lives, only the reader's cursor moves; physical reclamation happens after it is terminal.
+ *   - writer LIVE                                  → never reclaim (no window exists to lose bytes in);
+ *   - writer TERMINAL + fully consumed             → truncate at the ROTATE mark (race-free);
+ *   - writer TERMINAL + reader behind at HARD cap  → truncate, byte-accounting the unread remainder
+ *     (`skippedBytes` → recordSkippedBytes, the honest `[... N bytes truncated ...]` disclosure).
+ *
+ *  Cost, stated honestly: a live producer that outruns the reader is no longer capped on disk — its
+ *  spool grows for as long as it runs (bounded by the exec timeout / background hard wall, reclaimed
+ *  in full at its death). Capping it would mean destroying bytes we cannot count, which is the defect
+ *  itself; no portable Node syscall releases the consumed prefix of a file another process is
+ *  appending to. The reader stays bounded regardless — `skipAhead` drops the un-retainable middle and
+ *  accounts every skipped byte. The same unbounded-while-live posture already holds for the retain
+ *  lane (design/128) and for the detached-descendant residual (RB-26), and matches the CC anchor's
+ *  shape (named temp files, no rotation at all) with the file never outliving its writer.
+ *
+ *  RESIDUAL, unchanged by this rule: `writerLive` describes the DIRECT child. A detached descendant
+ *  holding the same fd can still append after the child is reaped, so a terminal-writer truncate can
+ *  in principle race it — the documented RB-26 posture, and undetectable from this side of the fd. */
 export declare function decideSpoolReclaim(args: {
     size: number;
     cursor: number;
@@ -21,6 +62,13 @@ export declare function decideSpoolReclaim(args: {
     reclaim: true;
     skippedBytes: number;
 };
+/** design/128 T1-1 / codex 1.236 复审 R2: open the spool file pair ALL-OR-NOTHING — a failure opening the
+ *  second file must close the first fd before rethrowing (the caller's catch only clears its references, so
+ *  a half-open pair would leak fdOut for the env's lifetime). `wx` + 0600 (never follow / never reuse an
+ *  existing path). Exported for direct fault-injection tests (pre-create a path → EEXIST). `a` (not
+ *  `w`): O_APPEND makes every child/descendant write an atomic append at the current end — which is
+ *  what lets the foreground quota rotation truncate a fully-consumed file to zero and have the next
+ *  write land at offset 0 (a plain-fd writer would keep its own offset and leave an unreadable hole). */
 export declare function openSpoolPair(base: string): {
     outPath: string;
     errPath: string;
@@ -35,14 +83,30 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     private readonly bgShells;
     private bgCounter;
     private readonly retainBackgroundProcesses;
+    /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
     private bgSpoolDir?;
     readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
     constructor(options: {
         cwd: string;
         shellPath?: string;
         shellEnv?: NodeJS.ProcessEnv;
+        /** VENDORED EDIT (D1, security): how much of `process.env` the shell child inherits. Default `"scrub"` =
+         *  fail-closed (drop secret-pattern keys, keep PATH/build/locale). `"all"` = full inherit (trusted env);
+         *  `string[]` = strict allowlist. `shellEnv`/per-exec `env` always pass through. */
         inheritEnv?: "all" | "scrub" | string[];
+        /** design/105: inject a resident scheduler daemon backend (the shell daemon). Absent ⇒ scheduling INERT. */
         scheduler?: SchedulerCapability;
+        /**
+         * design/128 T1-1 — deliver-a-living-service mode (default false). When true, background processes
+         * OUTLIVE the run: `disposeBackgroundShells()` becomes a no-op (the runner's every-exit-path dispose
+         * included) and background stdio is spooled to env-owned temp files (0600, `wx`, unpredictable path)
+         * so the child never dies of EPIPE after the host exits. DEPLOYMENT-declared at env construction —
+         * no TaskSpec/model-facing switch exists. The 2h bg-timeout reaper and `killBackground` still work
+         * while the host lives; after host exit, cleanup is the deployment's responsibility (e.g. the TB
+         * container teardown). v1 covers processes spawned via `execBackground` only (a detach-adopted
+         * foreground exec keeps pipe stdio — best-effort survival). Incompatible with durable-suspend
+         * deployments (their pre-suspend dispose becomes a no-op too — do not combine).
+         */
         retainBackgroundProcesses?: boolean;
     });
     get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
@@ -60,8 +124,22 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** RB-221 ([1937]): whole-file replace via same-directory staging + fsync + rename (CC 2.1.220 `Q5`,
+     *  pretty220.js:60808). The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
+     *  (Esc during a large Write — ctx.signal reaches here directly), ENOSPC, or a crash left the target as
+     *  a torn prefix of the NEW content with the original unrecoverable. Post-fix contract: the target is
+     *  either fully old or fully new; `aborted` means it was never touched. Known semantic change (same as
+     *  CC): rename breaks a hard link — the other link keeps the old content. */
     writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** RB-221 ([1937]): the historical single-step in-place overwrite — kept for targets where
+     *  staging+rename would change node identity (symlink chains, non-regular files) and as the
+     *  CC-parity fallback for filesystems where the rename cannot work. NOT atomic by design. */
     private writeFileInPlace;
+    /** Atomic exclusive create ({@link FileSystem.writeFileExclusive}): Node `wx` flag = one
+     *  `open(O_CREAT|O_EXCL)` syscall — an existing file returns FileError `"already_exists"` and is left
+     *  untouched. The EEXIST→already_exists mapping lives HERE, on the exclusive-open step only — a parent
+     *  `mkdir` can also throw EEXIST (parent path component is a regular file) and that is NOT "the target
+     *  already exists" (fable review). Parent directories are created like writeFile. */
     writeFileExclusive(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     appendFile(path: string, content: string | Uint8Array): Promise<Result<void, FileError>>;
     fileInfo(path: string): Promise<Result<FileInfo, FileError>>;
@@ -81,13 +159,29 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
         prefix?: string;
         suffix?: string;
     }): Promise<Result<string, FileError>>;
+    /** design/116 detach: adopt a RUNNING foreground child as a background shell. Pre-fills the bg tails with
+     *  the output captured so far (so TaskOutput's first read has the full history), attaches fresh data/close
+     *  handlers, and arms the default bg timeout. Returns undefined when the live-shell limit is hit (detach
+     *  refused; the exec keeps running in the foreground). */
     private adoptRunningChild;
     spawnBackground(command: string, options?: BackgroundSpawnOptions): Promise<Result<{
         shellId: BackgroundShellId;
     }, BackgroundShellError>>;
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /** design/128 T1-1: incrementally read a retained shell's spool files into the in-memory tails, so
+     *  pollBackground serves the same cursor semantics whether stdio came over pipes or spool files.
+     *  Bounded single read per stream per poll (the tail keeps only its rolling window anyway).
+     *  codex R3 F-C: reads are positioned by spool.fileCursor (the FILE offset — rotation truncates
+     *  the file), while poll slicing keeps using the logical stream totalBytes; the two advance in
+     *  lockstep here but are NOT interchangeable after a rotation. */
     private syncSpool;
+    /** codex R3 F-D + [1105]: reclaim an EPHEMERAL spool (detach-adopted, or any non-retain bg
+     *  spawn — the whole unix bg lane is spool-backed now) — fold the final residue into the tails,
+     *  unlink both files, and drop the spool reference (later syncs become no-ops). Idempotent;
+     *  never touches design/128 retain-lane spools (no `ephemeral` flag). A still-writing detached
+     *  descendant keeps its fd into the unlinked inode (RB-26 posture — no EPIPE, auto-reclaim at
+     *  its exit). */
     private reclaimEphemeralSpool;
     disposeBackgroundShells(opts?: {
         except?: readonly BackgroundShellId[];

package/dist/engine/harness/agent-harness.d.ts

@@ -2,26 +2,66 @@ import type { ActorAssertion, AssistantMessage, ImageContent, Model } from "../l
 import type { AgentMessage, AgentTool, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
 import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentHarnessOptions, AgentHarnessOwnEvent, AgentHarnessResources, AgentHarnessStreamOptions, ExecutionEnv, PromptTemplate, Skill } from "./types.js";
+/** [c209-C] codex 收口 C1/C2 — engine-provenance metadata a caller can stamp on the user message it
+ *  mints (see the field docs on {@link UserMessage}). Threaded from `prompt`/`steer`/`followUp`/
+ *  `nextTurn` options into the persisted message so derived views (auto-mode window, compaction
+ *  serializer) work from METADATA, never from reminder-shape guessing. */
 export interface UserMessageProvenance {
+    /** Exact char length of the engine-prepended prefix on `text` (first-frame reminders etc.).
+     *  Sugar for the single segment `[0, chars)` — when `engineSegments` is also supplied, segments win. */
     enginePrefixChars?: number;
+    /** [c209-C] R4: engine-trusted `[start, end)` UTF-16 segments of `text` — the general form of
+     *  `enginePrefixChars` for engine frames that are NOT a pure head (a resume continuation keeps
+     *  issue order, so a trusted frame may follow an untrusted fenced one). See UserMessage.engineSegments. */
     engineSegments?: ReadonlyArray<EngineSegment>;
+    /** The ENTIRE message is engine-minted guidance (nudges/finalize/attachment bundles), not user speech.
+     *  [c209-C] R4: mutually exclusive with `provenance` — on a double-stamp, `provenance` wins (see below). */
     engineMinted?: true;
+    /** [c209-C] R3: engine-injected note whose content must stay VISIBLE in derived views (diagnostics,
+     *  task notifications, steering, recall) but never under user authority — see UserMessage.provenance. */
     provenance?: "engine-note";
+    /** RB-30 terminal fix — an OPAQUE payload the engine rides on this queued message (the runner's
+     *  task-notification frame). Never serialized, never interpreted by the harness: if the message is
+     *  still undrained at agent_end, the payload is handed back through `onUndrainedEngineNotes` so
+     *  the runner can pend it per session (the final-drain stranding window closes losslessly). */
     enginePayload?: unknown;
+    /** design/171 §5.2 — WHO spoke this message (shared-session multiplayer attribution). Threaded
+     *  verbatim onto {@link UserMessage.actor}: metadata only, never authority, never on the provider
+     *  wire. The model-facing speaker envelope is rendered INTO `text` by the caller (the single
+     *  projection point `projectHumanInput`) BEFORE the frame wrapping — the harness never rewrites
+     *  text, so annotation stays adjacent to the frame it attributes. */
     actor?: ActorAssertion;
 }
+/**
+ * Harness-level recovery wiring (design/118 ④b/⑤). The loop's prompt-too-long seam wants a
+ * replacement TRANSCRIPT; at the harness level the correct policy is a SESSION-persisted reduction
+ * (e.g. a forced compaction) — otherwise the next turn's `createTurnState()` rebuilds the context
+ * from the session and the in-memory shrink evaporates. So the harness contract is: `recover`
+ * persists the reduction to the session and returns whether anything shrank; the harness then
+ * rebuilds the turn state FROM the session and hands the loop the rebuilt transcript.
+ */
 export interface HarnessLoopRecovery {
     truncatedOutput?: LoopTruncatedOutputRecovery;
     malformedToolUse?: LoopMalformedToolUseRecovery;
     thinkingOnly?: LoopThinkingOnlyRecovery;
+    /** design/128-follow-up (TB 尸检 T1-4): recover from a DEGENERATE-REPETITION cutoff instead of ending the
+     *  run — the brain already cut the stream and stamped the turn errored; when `detect` matches, the loop
+     *  nudges "don't repeat that, take a different approach" and runs another turn, bounded to `maxContinues`
+     *  CONSECUTIVE times (default 2). The cut-off turn stays in the transcript (its salvaged text is real
+     *  context). `detect` is injected by the caller (core owns the brain's DEGENERATE_MESSAGE constant). */
     degenerateOutput?: {
         detect: (message: AssistantMessage) => boolean;
         maxContinues?: number;
     };
     promptTooLong?: {
+        /** Persist a context reduction to the SESSION; return true if anything shrank. Must not throw. */
         recover: (attempt: number) => Promise<boolean>;
+        /** Override the loop's default prompt-too-long classifier. */
         detect?: (message: AssistantMessage) => boolean;
+        /** Max recovery retries per turn (loop default: 2). */
         maxRetries?: number;
+        /** M1 CC-withhold parity: hold the failure's stream events until the recovery outcome is
+         *  known (loop default: true). See LoopPromptTooLongRecovery.withholdErrorEvents. */
         withholdErrorEvents?: boolean;
     };
 }
@@ -29,17 +69,38 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     readonly env: ExecutionEnv;
     private session;
     private phase;
+    /** design/74 R3-A: a one-way soft-stop flag. When set, `shouldStopAfterTurn` returns true at the next turn
+     *  boundary so the loop exits CLEANLY (emit `agent_end` + return) WITHOUT an abort/interrupt — the path a
+     *  resource-slice suspend needs (an abort would trip the orphan-[INTERRUPTED] reconcile = corrupt resume). */
     private _stopAfterTurn;
     private runAbortController?;
     private runPromise?;
     private pendingSessionWrites;
     private model;
     private thinkingLevel;
+    /** RB-30 terminal fix — runner-set sink for engine-note payloads left undrained at agent_end. */
     onUndrainedEngineNotes?: (payloads: unknown[]) => void;
+    /** design/176 — runner-set sink fired at the CONSUMPTION boundary, once per engine-note payload,
+     *  in consumption order (steer/followUp drain and the turn-open nextTurn splice — the two points
+     *  where a queued frame actually enters the model's input). The runner uses it to record the
+     *  inbound peer hop chain of the message the model is about to see; writing at ENQUEUE time
+     *  instead would let an outbound send inherit the chain of a message the model has not read yet.
+     *  Advisory (swallow-guarded at the call sites via the runner's own closure); never re-entered
+     *  for the same payload — consumption deletes the sidecar entry in the same step. */
     onEngineNoteConsumed?: (payload: unknown) => void;
+    /** RB-30 codex F1/F2: shared recovery sweep — collects engine-note payloads from the given queues
+     *  in DELIVERY order (steer before followUp, each queue forward — the live loop serves steering
+     *  first, so the recovered redelivery must not present "later" frames ahead of "now/next"),
+     *  removes those entries, and hands the payloads to the runner sink. Called from BOTH terminal
+     *  paths: the natural agent_end AND abort() (which clears the queues before agent_end would see
+     *  them — the hard-abort race that round-1 shipped would have lost). */
+    /** RB-30 R2 belt-and-braces: runner-callable idempotent recovery for exit paths that reach
+     *  neither agent_end nor abort() (a pre-prompt throw after prepare). Swept entries are removed,
+     *  so a double call is a no-op. */
     recoverUndrainedEngineNotes(): void;
     private sweepUndrainedEngineNotes;
     private systemPrompt;
+    /** S4: physical system blocks (static per leg, additive — see AgentHarnessOptions.systemBlocks). */
     private systemBlocks;
     private streamOptions;
     private getApiKeyAndHeaders?;
@@ -61,12 +122,24 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private followUpQueueMode;
     private nextTurnQueue;
     private loopRecovery?;
+    /** roadmap #5 (CC Stop hook): the runner-wired stop gate — see {@link setStopGate}. */
     private stopGate?;
     private handlers;
     constructor(options: AgentHarnessOptions<TSkill, TPromptTemplate, TTool>);
     private getHandlers;
     private emitOwn;
     private emitAny;
+    /**
+     * Emit a hook event to its registered handlers and return a single result.
+     *
+     * **Last-write-wins:** handlers run in registration order; each non-`undefined` result overwrites
+     * the previous one, and the LAST non-`undefined` result is returned (`undefined` = abstain, keeps
+     * the prior winner). Handlers do NOT compose — registering two handlers that both return a result
+     * for the same event silently drops all but the last. A handler that throws aborts the whole emit
+     * (errors are not swallowed). Callers that need ordered, composable semantics for one event (e.g.
+     * the design/37 two-phase tool gate: collect arg rewrites, then adjudicate policy) must funnel that
+     * logic through a SINGLE handler rather than relying on multiple handlers + this fold.
+     */
     private emitHook;
     private emitBeforeProviderRequest;
     private emitBeforeProviderPayload;
@@ -77,7 +150,19 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private createStreamFn;
     private drainQueuedMessages;
     private createLoopConfig;
+    /**
+     * design/118 ④b/⑤: wire (or clear) the loop's recovery chains. The runner calls this after
+     * construction — truncated-output auto-continue and the prompt-too-long recover policy are
+     * PROFILE decisions (the harness only relays them to the loop).
+     */
     setLoopRecovery(recovery: HarnessLoopRecovery | undefined): void;
+    /**
+     * roadmap #5 (CC Stop hook): wire (or clear) the stop gate — consulted ONLY when the run would
+     * otherwise end (no tool calls, steer + followUp queues dry). Non-empty return = the run
+     * continues with those messages injected; empty = the run ends. Policy (the Hooks.stop call,
+     * consecutive-block cap, reason formatting) lives in the runner; the harness only supplies the
+     * drain-point timing.
+     */
     setStopGate(gate: (() => Promise<AgentMessage[]>) | undefined): void;
     private validateToolNames;
     private flushPendingSessionWrites;
@@ -87,7 +172,19 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     prompt(text: string, options?: {
         images?: ImageContent[];
     } & UserMessageProvenance): Promise<AssistantMessage>;
+    /** [920] R2-③: an empty/whitespace-only injection with no images carries ZERO information — it
+     *  must not mint a user frame (strict endpoints reject empty user content, and an empty follow-up would
+     *  pointlessly extend the run by one turn). No-op, not a throw: injection callers are fire-and-
+     *  forget lanes (wakeups, reminders) and a shell bug upstream must not crash the run. */
     private static emptyInjection;
+    /** REF-B6 — the ONE injection enqueue behind steer()/followUp()/nextTurn(): the [920] R2-③ empty-injection
+     *  short circuit, the user frame, the RB-30 engine-payload SIDECAR (a WeakMap entry, never a message field —
+     *  pre-prompt exits recover these too), the queue push, and the broadcast. All three lanes ship in ONE
+     *  `queue_update` event (see emitQueueUpdate), so they are one protocol contract and must stay one
+     *  implementation: [920] R2-③ and RB-30 each had to be patched in three places.
+     *
+     *  The idle check is deliberately NOT here: its message differs per lane, and nextTurn() legitimately has
+     *  none (queueing the NEXT prompt while idle is exactly what it is for). */
     private enqueueInjection;
     steer(text: string, options?: {
         images?: ImageContent[];
@@ -112,9 +209,28 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     setResources(resources: AgentHarnessResources<TSkill, TPromptTemplate>): Promise<void>;
     getStreamOptions(): AgentHarnessStreamOptions;
     setStreamOptions(streamOptions: AgentHarnessStreamOptions): Promise<void>;
+    /** RB-31 (design/148 S2) — swap the system prompt (+ physical blocks) for the NEXT turn snapshot,
+     *  the setTools-mirror seam: a compaction-boundary center adoption changes the stable prefix at a
+     *  legal boundary only (the running turn keeps its snapshot; createTurnState picks this up).
+     *  Blocks and prompt swap ATOMICALLY here; the existing blocksSafe guard still verifies equality
+     *  per snapshot, so a mismatched pair degrades to the single-block face, never a divergent wire. */
     setSystemPrompt(prompt: string, blocks?: AgentHarnessOptions<TSkill, TPromptTemplate, TTool>["systemBlocks"]): void;
     setTools(tools: TTool[], activeToolNames?: string[]): Promise<void>;
+    /**
+     * design/74 R3-A: request a CLEAN stop at the next turn boundary. Unlike {@link abort} (a hard
+     * AbortController cancel that — with no `suspendRef` — drives the orphan-[INTERRUPTED] session reconcile),
+     * this sets a one-way flag the loop reads via its `shouldStopAfterTurn` callback: the current turn finishes
+     * its tool calls, the loop emits `agent_end`, and returns. The runner uses it for a resource-slice suspend
+     * so the suspended session is left clean (resumable), never reconciled as interrupted. Idempotent.
+     */
     requestStopAfterTurn(): void;
+    /**
+     * VENDOR.md mod #5 (fixed at de-vendoring, design/118 ⑤): drain session writes queued during an
+     * ABORTED run. The harness intentionally does NOT flush on the abort path — the caller's interrupt
+     * reconcile must append its synthetic tool_results first (closing the open tool_call batch), then
+     * call this, so queued writes always land on a legal transcript. Safe to call anytime; no-op when
+     * the queue is empty.
+     */
     flushQueuedSessionWrites(): Promise<void>;
     abort(): Promise<AbortResult>;
     waitForIdle(): Promise<void>;

package/dist/engine/harness/agent-harness.js

@@ -584,20 +584,9 @@ export class AgentHarness {
             else if (write.type === "thinking_level_change") {
                 await this.session.appendThinkingLevelChange(write.thinkingLevel);
             }
-            else if (write.type === "custom") {
-                await this.session.appendCustomEntry(write.customType, write.data);
-            }
-            else if (write.type === "custom_message") {
-                await this.session.appendCustomMessageEntry(write.customType, write.content, write.display, write.details);
-            }
-            else if (write.type === "label") {
-                await this.session.appendLabel(write.targetId, write.label);
-            }
-            else if (write.type === "session_info") {
-                await this.session.appendSessionName(write.name ?? "");
-            }
-            else if (write.type === "leaf") {
-                await this.session.getStorage().setLeafId(write.targetId);
+            else {
+                const unreachable = write;
+                throw new AgentHarnessError("invalid_argument", `flushPendingSessionWrites: unhandled queued write type ${unreachable.type}`);
             }
             this.pendingSessionWrites.shift();
         }

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

@@ -1,13 +1,28 @@
 import type { ImageContent, Message, TextContent } from "../llm/index.js";
 import type { AgentMessage, BashExecutionMessage, CompactionSummaryMessage, CustomMessage } from "../loop/types.js";
 export type { BashExecutionMessage, CompactionSummaryMessage, CustomMessage, } from "../loop/types.js";
+/** Harness-only transcript entries that can be normalized into LLM messages. */
 export type HarnessMessage = AgentMessage | BashExecutionMessage | CustomMessage | CompactionSummaryMessage;
 export declare function asAgentMessage(message: HarnessMessage): AgentMessage;
 export declare const COMPACTION_SUMMARY_PREFIX = "This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.\n\n<summary>\n";
 export declare const COMPACTION_SUMMARY_SUFFIX = "\n</summary>\n\nRecent messages are preserved verbatim below. Continue the conversation from where it left off without asking the user any further questions. Resume directly \u2014 do not acknowledge the summary, do not recap what was happening, do not preface with \"I'll continue\" or similar. Pick up the last task as if the break never happened.";
+/** Render a shell execution record as user-visible context text for the model. */
 export declare function bashExecutionToText(msg: BashExecutionMessage): string;
+/** Build a persisted compaction summary message from the repository timestamp string.
+ *  `elidedMessages` (RB-398-b①): the render-time count of messages this summary stands in for —
+ *  drives the wrapper's scale disclosure; omitted ⇒ the wrapper stays byte-identical. */
 export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, elidedMessages?: number): CompactionSummaryMessage;
+/** Build a custom transcript message that can be shown and replayed into context. */
 export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown, timestamp: string): CustomMessage;
+/** Prefix stamped on a salvaged block so readers (model, summaries, humans) see it is a normalization
+ *  product, not authored content. */
 export declare const NORMALIZED_CONTENT_PREFIX = "[invalid content block normalized to text]";
+/**
+ * Fail-soft salvage for a possibly-poisoned LLM message ([868] 件b): any structurally-invalid
+ * `content` shape (bare object as the whole field, or a typeless/unknown-type block in the array) is
+ * normalized to a prefixed text block. Legal messages are returned BY REFERENCE, untouched. Shared by
+ * `convertToLlm` (provider leg) and `serializeConversation` (compaction leg) — one helper, two mouths.
+ */
 export declare function normalizeLlmMessageContent<T extends Message>(message: T): T;
+/** Convert harness transcript messages into the LLM-facing message sequence. */
 export declare function convertToLlm(messages: AgentMessage[]): Message[];