@genesislcap/ai-assistant 15.24.2 → 15.26.0

package/dist/ai-assistant.d.ts

@@ -405,6 +405,141 @@ export declare class AgentPicker extends GenesisElement {
 
 export { AgentPickerMode }
 
+/**
+ * The stateful-agent contract: which agent is active, whether a flow or a user pin holds routing,
+ * and the `onActivate` / `onDeactivate` lifecycle around a swap. Either driver can own one.
+ *
+ * Knows nothing about routing, tool surfaces or transcripts — whether an agent is terminal, the
+ * continuation tool, the handoff marker in history all stay with the orchestrator, which is the
+ * only thing with agents to route between.
+ *
+ * @beta
+ */
+export declare class AgentSession {
+    private readonly deps;
+    /**
+     * Aborted on disposal. Threaded into `AgentLifecycleContext.signal` so long-running
+     * `onActivate` work can bail if the session disconnects.
+     */
+    private readonly lifecycleAbortController;
+    private active?;
+    /**
+     * Sticky user pick from the picker (or the host's `setAgent` API). Only changes on explicit
+     * user action. Survives flow completion: when a stateful agent releases, the user-pin stays put
+     * and routing falls back to it on the next turn.
+     */
+    private pinned;
+    /**
+     * Transient flow lock — set when a stateful agent activates, cleared on release. While
+     * non-null, routing precedence goes to this agent and the picker is locked. Independent of
+     * the user pin so completing a flow doesn't wipe the user's sticky choice.
+     */
+    private flowOwner;
+    /**
+     * Per-agent restored state for a rehydrated session, keyed by agent name. Primed by the host on
+     * restore; each entry is passed to that agent's `onActivate` as `ctx.restored` on its next
+     * activation, then deleted so a later re-activation starts fresh.
+     */
+    private restoredStates;
+    constructor(deps: AgentSessionDeps);
+    /** The active agent, or `undefined` before the first activation and after a release. */
+    getActive(): AgentConfig | undefined;
+    /** The sticky user pin, or `null` for automatic routing. */
+    getPinned(): string | null;
+    /** The transient flow lock, or `null` when no flow holds routing. */
+    getFlowOwner(): string | null;
+    /**
+     * The name routing is locked to, flow lock first. A flow in progress outranks the user's
+     * sticky pick for the duration of the flow; neither being set means automatic routing.
+     */
+    getLockedName(): string | null;
+    /** Set the sticky user pin. `null` returns to automatic routing. */
+    setPinned(name: string | null): void;
+    /**
+     * Set the flow-owner lock directly — used to restore state on driver reconstruction
+     * (agents-array changes, pop-in/pop-out), not to steer routing. Writes without firing hooks or
+     * reporting a transition, because the flow it names is already running.
+     */
+    setFlowOwner(name: string | null): void;
+    /** Prime per-agent restored state for a rehydrated session. Replaces any pending entries. */
+    primeRestoredStates(snapshots: Record<string, unknown>): void;
+    /** Whether a restored snapshot is waiting for this agent's next activation. */
+    hasRestoredState(agentName: string): boolean;
+    /**
+     * Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`
+     * first, then incoming `onActivate`. Both are awaited so heavy activation work (a machine
+     * restore, say) completes before the agent's first turn runs, and a throw from either is logged
+     * rather than propagated — an agent whose hook fails still activates.
+     *
+     * Re-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no
+     * handoff is recorded. That guard matters because a per-turn re-resolve calls through here.
+     */
+    activate(agent: AgentConfig): Promise<AgentTransition>;
+    /**
+     * Release the active agent: fire `onDeactivate` and drop the flow lock.
+     *
+     * The user pin is intentionally **not** cleared — someone who explicitly picked this agent
+     * should stay on it after the flow ends, so the next message starts a fresh flow on the same
+     * agent rather than routing through the classifier.
+     *
+     * Returns `undefined` when there was no active agent, so a caller can skip its events.
+     */
+    release(): Promise<AgentTransition | undefined>;
+    /**
+     * Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session
+     * teardown, so machines release resources cleanly. The session is not reusable afterwards: the
+     * abort signal stays aborted, so a later `activate` would hand its hook a dead signal.
+     *
+     * `onDeactivate` runs **before** the abort, deliberately: teardown that needs to flush state
+     * would otherwise be handed an already-aborted signal and have to skip its own work. The cost is
+     * that an `onActivate` still in flight keeps running until `onDeactivate` finishes — both hold
+     * the same signal. Acceptable because the two are sequenced by `activate`, so overlap only
+     * happens if a hook resolves before the work it started; a hook that must stop immediately
+     * should own its own cancellation.
+     */
+    dispose(): Promise<void>;
+    /**
+     * The one place `onDeactivate` is invoked. `reason` only reaches the warning text, which is what
+     * tells a log reader which path fired.
+     */
+    private fireDeactivate;
+}
+
+/**
+ * Callbacks an {@link AgentSession} needs from its owner.
+ *
+ * @beta
+ */
+export declare interface AgentSessionDeps {
+    /**
+     * The debug-log session key, read per call rather than captured: a driver's key is assigned
+     * after construction on some paths, so a value captured here would pin the wrong one.
+     */
+    sessionKey: () => string;
+}
+
+/**
+ * What changed when an agent was activated or released.
+ *
+ * Returned rather than dispatched: the host listens on the `OrchestratingDriver`, not on the
+ * `ChatDriver` that owns the session, so a self-dispatching session would need telling which
+ * target to fire on.
+ *
+ * @beta
+ */
+export declare interface AgentTransition {
+    /** The agent that was active before, if any. */
+    previousAgent?: AgentConfig;
+    /** True when the activation was a real swap rather than a re-apply of the same agent. */
+    switched: boolean;
+    /**
+     * Set when the flow-owner lock changed, to the value it changed *to* (`null` on release).
+     * `undefined` means unchanged — distinct from `null`, so a caller can tell "cleared" from
+     * "not touched" without re-reading.
+     */
+    flowOwnerChangedTo?: string | null;
+}
+
 /**
  * Union of all available animation names, derived from {@link ANIMATION_DEFS}.
  *
@@ -622,8 +757,12 @@ export declare interface AiDriver extends EventTarget {
     /**
      * Prime per-agent restored state for a session being rehydrated. Each entry
      * (keyed by agent name) is handed to that agent's `onActivate`/`init` as
-     * `ctx.restored` on its next activation, then consumed. Optional — only
-     * multi-agent drivers that own agent activation implement it.
+     * `ctx.restored` on its next activation, then consumed.
+     *
+     * Implemented by every driver since GENC-1580 — each owns an `AgentSession` — so "only
+     * multi-agent drivers implement it" is no longer true. Still declared optional: this interface
+     * is exported and `@beta`, so requiring it would break any third party implementing it. The `?`
+     * comes off with the `installAgent` rename, which is the ticket's one breaking release.
      */
     primeRestoredAgentState?(snapshots: Record<string, unknown>): void;
     /**
@@ -641,10 +780,33 @@ export declare interface AiDriver extends EventTarget {
      * The live `AgentConfig` currently active in the driver — the instance whose
      * `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live
      * state. Prefer this over looking the agent up in the host's `agents` array,
-     * which may mint fresh, never-activated configs. Optional — only drivers that
-     * retain the active config implement it.
+     * which may mint fresh, never-activated configs.
+     *
+     * `undefined` means no agent is active (before the first activation, after a release), which is
+     * a different statement from the driver not being able to answer. Both drivers implement it
+     * since GENC-1580; see {@link AiDriver.primeRestoredAgentState} for why the `?` stays for now.
      */
     getActiveAgent?(): AgentConfig | undefined;
+    /**
+     * Pin routing to an agent by name, or `null` for automatic routing. A pin is sticky: it
+     * survives a stateful flow completing, so the next turn starts fresh on the same agent.
+     *
+     * On a driver with nothing to route between this is recorded rather than acted on — the pick
+     * belongs to the session, which outlives the question of which driver holds it.
+     *
+     * Added to the interface in GENC-1580 — it was previously reached by narrowing to
+     * `OrchestratingDriver` with `instanceof`. Optional, so adding it breaks no implementor.
+     */
+    setPinnedAgent?(name: string | null): void;
+    /**
+     * Set the transient flow lock — used to restore state on driver reconstruction (agents-array
+     * changes, pop-in/pop-out), **not** to steer routing; that is
+     * {@link AiDriver.setPinnedAgent}'s job. Writes without firing lifecycle hooks, because the
+     * flow it names is already running.
+     *
+     * Added to the interface in GENC-1580, as for {@link AiDriver.setPinnedAgent}.
+     */
+    setFlowOwner?(name: string | null): void;
     /**
      * Headroom the next turn could need, and which agent set that requirement
      * (GENC-1582). `undefined` when no agent the turn could land on declares a
@@ -1411,10 +1573,8 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * (`callPhaseEpoch < currentPhaseEpoch`), with an `agentEnd` backstop.
      */
     private currentPhaseEpoch;
-    /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
-    private foldStack;
-    /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
-    private consecutiveFoldOps;
+    /** Tool folds: the open-fold stack, the no-progress counter, and the tool-surface swap. */
+    private readonly folds;
     /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
     private consecutiveUnknownToolCalls;
     /**
@@ -1616,6 +1776,21 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private readonly condenseBatchCalls;
     /** Session identity used to file meta events onto the shared debug-log timeline. */
     private readonly sessionKey;
+    /** See {@link ChatDriverConfig.deferAgentRelease}. */
+    private readonly deferAgentRelease;
+    /**
+     * The stateful-agent contract for this driver: active agent, user pin, flow lock, restored
+     * state, and the `onActivate` / `onDeactivate` hooks (§7.1).
+     *
+     * **Public because `OrchestratingDriver` reaches through to it.** The orchestrator decorates a
+     * config before installing it (the cross-agent continuation tool), so it cannot route through
+     * {@link ChatDriver.activateAgent} and must drive the session itself — and one shared session is
+     * the point: two would let `getActiveAgent()` disagree between the outer and inner driver.
+     * `@internal` rather than private so that reach is legal without six delegating one-liners.
+     *
+     * @internal
+     */
+    readonly agentSession: AgentSession;
     /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
     private readonly activityBus;
     /**
@@ -1689,7 +1864,7 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * interaction is instead settled by `resolveInteraction` (user response or
      * timeout), which also stamps history and reverts the chat-input override.
      */
-    dispose(): void;
+    dispose(): Promise<void>;
     /**
      * Stop the current turn (user "stop" button). Aborts the in-flight provider
      * request immediately; if a tool is mid-execution it runs to completion and
@@ -1710,15 +1885,6 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * cached history would otherwise gain a stray marker on remount).
      */
     private completeAbortedTurn;
-    /**
-     * Build the `done` loop result, carrying the typed failure reason when the turn
-     * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
-     * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
-     * `failureReason` is simply present on a failure and absent on success. Omitted
-     * (rather than set to `undefined`) so a happy-path result stays byte-identical to
-     * the historical `{ reason: 'done' }`.
-     */
-    private turnDone;
     /**
      * End the turn on a terminal failure: fail upward when this driver is a sub-agent, speak
      * to the user when it is not, and hand the reason to the caller either way.
@@ -1793,8 +1959,55 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      */
     private loopEndDetail;
     /**
-     * Swap in a new agent's configuration. Called by OrchestratingDriver before
-     * each specialist turn so the shared driver runs with the right tools and prompt.
+     * Make `config` the active agent, firing its lifecycle hooks — `onDeactivate` on the outgoing
+     * agent, then `onActivate` on this one — before installing it.
+     *
+     * This is the entry point a host should use. {@link ChatDriver.applyAgent} installs a config
+     * *without* firing hooks, which is right for the two callers that need it (the orchestrator,
+     * which fires them through the shared session, and `invokeSubAgent`, where a child's config is
+     * not an activation) and wrong for everyone else.
+     *
+     * @beta
+     */
+    activateAgent(config: AgentConfig): Promise<void>;
+    /**
+     * {@inheritDoc AiDriver.getActiveAgent}
+     *
+     * @beta
+     */
+    getActiveAgent(): AgentConfig | undefined;
+    /** {@inheritDoc AiDriver.primeRestoredAgentState} */
+    primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    /**
+     * Record the sticky agent pin. See {@link AiDriver.setPinnedAgent} for the contract.
+     *
+     * Recorded, not acted on: this driver has one agent and nothing to route between, so a pin
+     * changes no behaviour here. It is still honoured as state, because the session outlives the
+     * question of which driver is holding it — a host that pins before an orchestrator is built
+     * would otherwise lose the pick.
+     *
+     * @beta
+     */
+    setPinnedAgent(name: string | null): void;
+    /**
+     * Record the transient flow lock. See {@link AiDriver.setFlowOwner} for the contract.
+     *
+     * Recorded, not acted on, for the same reason as {@link ChatDriver.setPinnedAgent}.
+     *
+     * @beta
+     */
+    setFlowOwner(name: string | null): void;
+    /**
+     * Install `config` as the active agent **without firing lifecycle hooks**.
+     *
+     * Prefer {@link ChatDriver.activateAgent} unless you are deliberately skipping the hooks. Two
+     * callers are: `OrchestratingDriver`, which fires them through the shared
+     * {@link ChatDriver.agentSession} and then installs a decorated config, and `invokeSubAgent`,
+     * where the child driver's config is a tool surface rather than an activation.
+     *
+     * Renamed to `installAgent` in a follow-up (GENC-1580) — see `docs/migration-GENC-1580.md`.
+     * Until then the name says less than it should, so do not add a third caller to this path
+     * without checking which of the two above it resembles.
      */
     applyAgent(config: AgentConfig): void;
     /**
@@ -1832,12 +2045,6 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * throw all yield empty fields — attribution is diagnostic, never load-bearing.
      */
     private resolveStatusForProvider;
-    /**
-     * Resolve a per-turn config input that is either a static value or a function
-     * of the turn context — the value-or-resolver shape shared by `provider`,
-     * `temperature`, and `toolChoice`. Returns undefined when the input is unset.
-     */
-    private resolveTurnInput;
     /**
      * Returns the early-stop result set by `completeSubAgent`, if any.
      * Called by a parent `ChatDriver` after running this instance as a sub-agent.
@@ -1875,6 +2082,15 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Consumed by the orchestrator to trigger the auto-pin release path.
      */
     getAgentReleaseRequested(): boolean;
+    /**
+     * Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,
+     * so the next turn starts clean and the persister does not serialize a flow that is over.
+     *
+     * No-op when the owner handles release ({@link ChatDriverConfig.deferAgentRelease}). The flag is
+     * cleared here rather than only at the next `sendMessage`, so the signal cannot be acted on twice
+     * and release a later agent that never asked.
+     */
+    private releaseIfRequested;
     /**
      * Return the per-turn snapshots captured so far. Used by the host's debug
      * log exporter to show what the LLM saw on each turn — system prompt, tool
@@ -1975,6 +2191,11 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * unaffected — which is what makes the elision recoverable.
      */
     getHistoryForPersistence(): ChatMessage[];
+    /**
+     * {@inheritDoc AiDriver.getSuggestions}
+     *
+     * @beta
+     */
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     /**
      * Whether `compact()` would do anything right now — a summarizable run of older
@@ -2124,36 +2345,6 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Used by OrchestratingDriver after an agent handoff.
      */
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
-    /** Extract ToolFold metadata from a handler, or undefined if it isn't a fold facade. */
-    private getFold;
-    /**
-     * Search all currently registered fold facades (and their nested folds recursively)
-     * to find which fold contains a given tool name. Returns the immediate parent fold name.
-     */
-    private findFoldContaining;
-    /**
-     * If an open fold is hiding a previously-available tool, return the name of
-     * the fold to close to start getting it back. Only exclusive folds hide tools
-     * (they replace the tool set on open rather than extending it), so a base tool
-     * that was visible before the fold opened now sits in a fold-stack frame's
-     * `previousHandlers` but not in the live handler map. Only the top fold's
-     * `close_` tool is active, so that's always the actionable next step — even
-     * when the tool lives further down the stack, closing repeatedly walks back to
-     * it. Returns null when no open fold accounts for the tool.
-     */
-    private foldHidingTool;
-    /**
-     * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
-     * the current tool set. Also injects the close tool. Does NOT touch the fold stack.
-     */
-    private applyFoldToolSet;
-    /** Open a fold: push a stack frame, swap the tool set, return the response message. */
-    private openFold;
-    private pushFoldFrame;
-    /** Close the top fold: pop the stack frame, restore the previous tool set. */
-    private closeFold;
-    /** Build the fold-awareness suffix appended to the system prompt each LLM call. */
-    private buildFoldSystemPromptSuffix;
     private runToolLoop;
     /**
      * Append prose the DRIVER wrote rather than the model — a failure notice, a limit explanation,
@@ -2237,6 +2428,19 @@ export declare interface ChatDriverConfig {
      * reversible change.
      */
     budgetExhaustedMessage?: string;
+    /**
+     * Leave acting on `releaseAgent` to the owner of this driver.
+     *
+     * Set by `OrchestratingDriver` for its inner driver, which performs the release itself after the
+     * turn so it can fire the host-facing `agent-released` / `agent-changed` / `flow-owner-changed`
+     * events. Both drivers share one `AgentSession`, so releasing here first would empty it and make
+     * the orchestrator's own release a silent no-op — leaving the host with a locked picker and a
+     * stale active agent.
+     *
+     * Left unset, a driver releases its own agent, which is what a bare `ChatDriver` needs: nothing
+     * else is watching the flag.
+     */
+    deferAgentRelease?: boolean;
     /**
      * Overrides the transcript sentence shown when the upstream PROVIDER refuses the account
      * (GENC-1506) — see `TURN_FAILURE_EXITS.providerRefused.copy`.
@@ -3353,8 +3557,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
     /**
      * Aggregated USD cost across every chat turn in this session.
      *
-     * Read-only (unlike previously): it is a projection of `sessionUsage`, and a
-     * host assigning it would have set a figure the next transcript change overwrites.
+     * Read-only: a projection of `sessionUsage`, so an assigned figure would be overwritten by
+     * the next transcript change.
      */
     get sessionCostUsd(): number;
     /**
@@ -3545,14 +3749,9 @@ export declare class FoundationAiAssistant extends GenesisElement {
     showingSplash: boolean;
     private driver?;
     /**
-     * This element's driver as an orchestrator, or `undefined` when the session is
-     * running a bare `ChatDriver`.
-     *
-     * The five call sites that used to test the type themselves now read this
-     * (§11.2 constraint 3 of `docs/code-health.md`): the agent pin, the flow-owner
-     * lock, the wire-up in `wireDriver`, and the two `driverKind` diagnostics. The
-     * type test itself lives in `asOrchestrator`, shared with the session
-     * persister.
+     * This element's driver as an orchestrator, or `undefined` when the session is running a bare
+     * `ChatDriver`. The only place in this element that narrows the type; the test itself lives in
+     * `asOrchestrator`, shared with the session persister.
      */
     private get orchestrator();
     private driverCleanup?;
@@ -3681,8 +3880,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get activeInteractionRow(): ChatMessage[];
     agentsChanged(): void;
-    /** Returns a stable fingerprint for an agents array based on agent names and tool handler keys. */
-    private getAgentsKey;
     /**
      * Pure factory — creates a ChatDriver or OrchestratingDriver based on the
      * current agent configuration. Does not wire event listeners or register in
@@ -3804,10 +4001,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * history no longer shrinks the totals.
      */
     private syncUsageTotals;
-    /**
-     * Runs side effects that were previously in `messagesChanged()`.
-     * Called from the `messages` setter after dispatching to the store.
-     */
+    /** Transcript side effects, called from the `messages` setter after it dispatches to the store. */
     private handleMessagesUpdate;
     showLoadingIndicatorChanged(): void;
     private scrollToBottom;
@@ -4628,10 +4822,16 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     private readonly classifierRetries;
     private readonly sessionKey;
     /**
-     * Aborted on driver disposal. Threaded into `AgentLifecycleContext.signal`
-     * so long-running `onActivate` work can bail if the session disconnects.
+     * The stateful-agent contract (§7.1): active agent, user pin, flow lock, restored state, and
+     * the `onActivate` / `onDeactivate` hooks.
+     *
+     * **The inner driver's session, not one of our own.** One session is the invariant: two would
+     * let the outer and inner driver disagree about which agent is active, and the inner one would
+     * never be activated at all, because this driver installs a *decorated* config through
+     * `applyAgent` rather than going via `ChatDriver.activateAgent`. This driver keeps the routing
+     * decisions; the session owns the lifecycle.
      */
-    private readonly lifecycleAbortController;
+    private get agentSession();
     /**
      * Set by `cancel()` for the duration of a `sendMessage` run. Breaks the
      * handoff loop so we don't classify or start another agent turn after the
@@ -4650,28 +4850,12 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      */
     private userMessageAppended;
     /**
-     * Sticky user pick from the picker (or the host's `setAgent` API). Only
-     * changes on explicit user action. Survives flow completion: when a stateful
-     * agent releases, the user-pin stays put and routing falls back to it on
-     * the next turn.
-     */
-    private pinnedAgentName;
-    /**
-     * Transient flow lock — set when a stateful agent's `onActivate` fires,
-     * cleared by `releaseActiveAgent`. While non-null, routing precedence goes
-     * to this agent and the picker is locked. Independent of
-     * `pinnedAgentName` so completing a flow doesn't wipe the user's sticky
-     * choice.
-     */
-    private flowOwnerAgentName;
-    /**
-     * Per-agent restored state for a rehydrated session, keyed by agent name.
-     * Primed by the host on restore; each entry is passed to that agent's
-     * `onActivate` as `ctx.restored` on its next activation, then deleted so a
-     * later re-activation starts fresh.
+     * The active agent, or `undefined` before the first activation and after a release.
+     *
+     * Kept as an accessor over `agentSession` rather than removed: it is a public member of an
+     * exported class, so nothing in this package reading it is not the same as nothing reading it.
      */
-    private restoredAgentStates;
-    activeAgent?: AgentConfig;
+    get activeAgent(): AgentConfig | undefined;
     constructor(providerRegistry: AIProviderRegistry, agents: AgentConfig[], options?: {
         sessionKey?: string;
         maxHandoffs?: number;
@@ -4912,7 +5096,11 @@ declare type ProviderRefusedDetail = NonNullable<Extract<ChatDriverResult, {
     reason: 'done';
 }>['providerRefused']>;
 
-/** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
+/**
+ * Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver.
+ *
+ * @beta
+ */
 export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
 
 /** Resolved context-headroom thresholds for the active model. */
@@ -5799,11 +5987,9 @@ export declare interface TurnSnapshot {
     /** Name of the agent active when this LLM call ran. */
     agentName?: string;
     /**
-     * The agent's resolved system prompt sent to the LLM, verbatim. NOTE: this is
-     * now the *bare* prompt — the fold-surface suffix and the malformed/empty retry
-     * nudge no longer mutate it (they kept it byte-unstable and busted prompt
-     * caching), so they moved to {@link TurnSnapshot.tailContext}. To reconstruct
-     * exactly what the model saw, read both fields.
+     * The agent's resolved system prompt sent to the LLM, verbatim — the **bare** prompt. The
+     * fold-surface suffix and the retry nudges live in {@link TurnSnapshot.tailContext} instead, to
+     * keep this byte-stable for prompt caching; read both fields to reconstruct what the model saw.
      */
     systemPrompt?: string;
     /**