@gajae-code/coding-agent 0.18.1 → 0.18.6

package/dist/types/sdk/broker/lifecycle.d.ts

@@ -4,7 +4,7 @@ import type { SessionWorkLease } from "../../session/session-work-lease";
 import type { SessionLifecycleMcpServer } from "../acp/mcp";
 import { type SdkStartupFailure, type SdkStartupRollbackResult } from "../startup-capability";
 import type { Broker, BrokerCleanupEvidence, BrokerResponse } from "./broker";
-import type { LifecycleDurableEffectsReceipt, LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
+import type { LifecycleDurableEffectsReceipt, LifecycleEffectIntent, LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
 import { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, parseDarwinProcessIncarnation, processIncarnation } from "./process-incarnation";
 import { type SdkInternalSpawnCommand } from "./runtime";
 import { type IndexedSession } from "./session-index";
@@ -52,6 +52,10 @@ export declare function setLifecycleHostPlatformForTest(platform: NodeJS.Platfor
 export declare function readyThenExitToleranceEnabledForTest(): boolean;
 export declare function hasValidLifecycleDeadlines(value: LifecycleDeadlines, now?: number): boolean;
 type Input = Record<string, unknown>;
+type LifecycleEffectIntentWithDeadline = LifecycleEffectIntent & {
+    lifecycleCleanupDeadlineAt?: number;
+    admissionCleanupDeadlineAt?: number;
+};
 export declare const isCanonicalSessionId: (value: string) => boolean;
 export interface SessionLifecycleWorktreeTarget {
     enabled: true;
@@ -260,6 +264,7 @@ export interface LifecycleExecutionOutcome {
     startupFailure?: LifecycleStartupFailureReceipt;
     deferredArtifactCleanup?: () => Promise<void>;
 }
+export declare function classifyLateAdmissionSpawnFailure(response: BrokerResponse, effectIntent: LifecycleEffectIntentWithDeadline | undefined, now: number, messageSource: BrokerResponse): BrokerResponse;
 /** Returns the response together with every durable lifecycle fact needed for truthful replay. */
 export declare function executeLifecycle(broker: Broker, operation: string, input: Input, identity: string, cleanup?: CleanupEvidence): Promise<LifecycleExecutionOutcome>;
 /**

package/dist/types/sdk/broker/recovery-backoff.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded exponential backoff tracker for broker recovery failures per agent dir.
+ * Tracks repeated recovery failures and implements exponential backoff with a cap
+ * to prevent repeated spawns from destabilizing the system.
+ */
+/** Configuration for recovery backoff behavior. */
+export interface RecoveryBackoffConfig {
+    /** Initial backoff delay in milliseconds (default: 1000ms). */
+    initialDelayMs: number;
+    /** Maximum backoff delay in milliseconds (default: 30000ms = 30s). */
+    maxDelayMs: number;
+    /** Backoff multiplier applied each retry (default: 2). */
+    multiplier: number;
+    /** Maximum number of recovery attempts per session (default: 5). */
+    maxAttempts: number;
+}
+/** State for a single agent dir's recovery backoff. */
+export interface RecoveryBackoffState {
+    /** Timestamp of the last recovery failure. */
+    lastFailureAt: number;
+    /** Current backoff delay in milliseconds. */
+    currentDelayMs: number;
+    /** Number of consecutive failures. */
+    failureCount: number;
+    /** Whether recovery has been permanently stopped due to max attempts. */
+    stopped: boolean;
+}
+/** Manages per-agent-dir recovery backoff state. */
+export declare class RecoveryBackoffTracker {
+    #private;
+    constructor(config?: Partial<RecoveryBackoffConfig>);
+    /** Test hook: inject a custom clock. */
+    setClockForTest(clock: {
+        now(): number;
+    }): void;
+    /**
+     * Check if recovery should proceed now, considering backoff.
+     * Returns true if sufficient time has elapsed since the last failure.
+     */
+    canAttemptRecovery(agentDir: string): boolean;
+    /**
+     * Record a recovery failure and update backoff state.
+     * Returns true if recovery should continue to be attempted, false if max attempts reached.
+     */
+    recordFailure(agentDir: string): boolean;
+    /**
+     * Record a successful recovery and reset backoff state.
+     */
+    recordSuccess(agentDir: string): void;
+    /**
+     * Get the current backoff state for an agent dir (for testing/diagnostics).
+     */
+    getState(agentDir: string): RecoveryBackoffState | undefined;
+    /**
+     * Get milliseconds until the next recovery attempt can proceed.
+     */
+    getBackoffWaitMs(agentDir: string): number;
+    /**
+     * Reset all backoff state (for testing).
+     */
+    resetForTest(): void;
+}

package/dist/types/sdk/broker/runtime.d.ts

@@ -1,4 +1,4 @@
-export type SdkInternalAction = "broker-internal" | "session-host-internal" | "stderr-drain-internal";
+export type SdkInternalAction = "broker-internal" | "broker-trampoline-internal" | "session-host-internal" | "stderr-drain-internal";
 export type SdkInternalSpawnCommand = {
     kind: "bun-source";
     file: string;
@@ -40,6 +40,14 @@ export interface SdkInternalRuntimeDescriptorTestOptions {
  * must not hide behind it.
  */
 export declare function sdkInternalRuntimeImage(): string | undefined;
+/** Identity of a runtime image: enough to detect replacement at the same path. */
+export interface SdkInternalRuntimeImageIdentity {
+    path: string;
+    dev: number;
+    ino: number;
+    mtimeMs: number;
+    size: number;
+}
 /**
  * Whether a published runtime image is still a regular file on disk. A resident broker keeps
  * answering requests after the executable it was started from is deleted (a
@@ -50,6 +58,18 @@ export declare function sdkInternalRuntimeImage(): string | undefined;
  * its bound: a false retirement kills a healthy broker.
  */
 export declare function isSdkInternalRuntimeImagePresent(file: string): Promise<boolean>;
+/**
+ * Capture the runtime image identity (dev, ino, mtimeMs, size) at startup.
+ * Used to detect if the binary at the same path has been replaced.
+ */
+export declare function captureRuntimeImageIdentity(file: string): Promise<SdkInternalRuntimeImageIdentity | undefined>;
+/**
+ * Check if the runtime image has been replaced since startup.
+ * Returns `true` if the path is gone, its dev/ino differ from the startup identity,
+ * or its size or modification time changed (an in-place rewrite keeps the inode).
+ * Returns `false` (inconclusive) if the file exists and matches, or on any error.
+ */
+export declare function isSdkInternalRuntimeImageReplaced(startupIdentity: SdkInternalRuntimeImageIdentity | undefined): Promise<boolean>;
 /** Resolve the production descriptor from the statically imported marker and current Bun runtime evidence. */
 export declare function resolveSdkInternalSpawnCommand(action: SdkInternalAction): SdkInternalSpawnCommand;
 /** Test hook: injects runtime evidence without weakening the production marker authority. */

package/dist/types/sdk/broker/startup-budget.d.ts

@@ -8,6 +8,8 @@ export declare const MIN_PREPARATION_TIMEOUT_MS = 1000;
 export declare const MAX_PREPARATION_TIMEOUT_MS = 120000;
 /** Bounded workspace install window; independent of child semantic readiness. */
 export declare const DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS = 30000;
+/** Non-worktree broker pre-spawn cap, also limited by the admission window remaining since receipt. */
+export declare const DEFAULT_BROKER_PRESPAWN_PREPARATION_TIMEOUT_MS = 30000;
 export declare function isValidReadinessTimeoutMs(value: unknown): value is number;
 export declare function isValidPreparationTimeoutMs(value: unknown): value is number;
 export declare const READINESS_TIMEOUT_INVALID_MESSAGE = "readinessTimeoutMs must be an integer between 4000 and 60000.";
@@ -51,7 +53,9 @@ export declare function lifecycleStartupBudgetMs(requestedReadinessTimeoutMs: nu
  *
  * Worktree launches add independent preparation budgets so git add / install cannot
  * cut the caller while the broker still owns the request. One-arg
- * {@link lifecycleStartupBudgetMs} stays queue+readiness for no-worktree callers.
+ * {@link lifecycleStartupBudgetMs} stays queue+readiness for no-worktree callers:
+ * broker-derived pre-spawn work uses only the unspent admission window from receipt,
+ * and the fresh readiness window ends within that unchanged caller budget.
  */
 export declare function lifecycleRequestTimeoutMs(operation: string, input: Record<string, unknown>): number | undefined;
 /**

package/dist/types/sdk/bus/index.d.ts

@@ -602,6 +602,7 @@ export declare function shouldAwaitNotificationStartup(event: {
         origin: string;
     };
 }): boolean;
+export declare function boundedCorrelatedAgentEndFrame(frame: Record<string, unknown>): Record<string, unknown>;
 export declare function createNotificationsExtension(api: ExtensionAPI, options?: {
     settings?: Settings;
     ensureTelegramDaemon?: (input: {

package/dist/types/sdk/bus/telegram-daemon-contract.d.ts

@@ -292,7 +292,7 @@ export declare const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * Generation 193 gates streamed content on negotiated observer capabilities,
  * so existing owners are replaced before exposing the new observer path.
  */
-export declare const DAEMON_GENERATION = 197;
+export declare const DAEMON_GENERATION = 200;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7
  * requires durable publication receipts and acknowledged attachment dispatch,

package/dist/types/sdk/bus/telegram-daemon.d.ts

@@ -1181,4 +1181,5 @@ export declare class TelegramNotificationDaemon {
     run(): Promise<void>;
     /** True when a signal-driven stop or an owner-scoped control request asks the loop to exit. */
     private controlStopRequested;
+    private checkControlStopRequested;
 }

package/dist/types/sdk/cli/diagnostics-cli.d.ts

@@ -0,0 +1,18 @@
+/** Isolated `gjc sdk diagnostics` parser and renderer.
+ *
+ * Reached from the inert entry before any effectful branch, so this module must
+ * stay a pure leaf: no command registry, session CLI, runtime globals, managed
+ * owner admission, malloc guard, evidence publisher, broker client, directory
+ * resolver or logger import. Help and usage never resolve a root or open a file,
+ * and every outcome is a fixed bounded string with a fixed exit code.
+ *
+ * Observation itself must never start, ensure, retire, restart or recover a
+ * broker. The read-only observation facade (DESIGN §B3) is wired: `observe()`
+ * below routes to it and to nothing else, so this command can report only what a
+ * supporting broker publishes to the read-only reader. An unsupported runtime
+ * tuple, a missing or mismatched native artifact and an old broker without a
+ * published generation all still fail closed with the fixed `unsupported`
+ * outcome.
+ */
+/** Run `gjc sdk diagnostics <argv…>`; argv excludes the `sdk diagnostics` prefix. */
+export declare function runDiagnosticsCli(argv: readonly string[]): Promise<void>;

package/dist/types/sdk/diagnostics/observe-broker.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Observation-only broker diagnostics facade (SPEC "Result contract").
+ *
+ * The publication is read ONLY through the approved read-only native lease
+ * (`loadDiagnosticNativeReadOnly` -> `openDiagnosticSnapshot` -> bounded read ->
+ * revalidate -> close), so every ancestor ACL/owner/mode and filesystem check of the
+ * earlier slices governs this route too. Ordinary discovery is deliberately not used: it
+ * would bypass that gate. An unsupported runtime tuple or artifact resolves to
+ * `unsupported` BEFORE any publication access. The facade then opens exactly ONE client
+ * connection with no reconnect attempts, asks the broker for its published diagnostics
+ * and returns a detached frozen snapshot. It never ensures, starts, recovers, retires or spawns
+ * anything, never touches the session index, ledger or evidence store, and never hands
+ * the caller a token, socket coordinate, path, pid or environment value.
+ */
+/** Allowed unavailability reasons; messages are fixed literals keyed by the enum. */
+export type BrokerObservationUnavailableReason = "absent" | "stale" | "incompatible" | "authentication_failed" | "unsupported" | "generation_mismatch" | "transport_unavailable" | "timeout" | "invalid_response" | "unsafe_discovery";
+export interface BrokerObservationBuild {
+    readonly packageVersion: string;
+    readonly buildId: string | null;
+}
+export interface BrokerObservationSuccess {
+    readonly schema: "gjc.broker-observation";
+    readonly version: 1;
+    readonly ok: true;
+    readonly observedAt: string;
+    readonly broker: {
+        readonly generation: string;
+        readonly build: BrokerObservationBuild;
+        readonly diagnosticProtocol: 1;
+    };
+}
+export interface BrokerObservationUnavailable {
+    readonly schema: "gjc.broker-observation";
+    readonly version: 1;
+    readonly ok: false;
+    readonly observedAt: string;
+    readonly unavailable: {
+        readonly reason: BrokerObservationUnavailableReason;
+        readonly message: string;
+    };
+}
+export type BrokerObservation = BrokerObservationSuccess | BrokerObservationUnavailable;
+export interface ObserveExistingBrokerOptions {
+    readonly agentDir: string;
+    readonly expectedGeneration?: string;
+    readonly timeoutMs?: number;
+}
+/** The broker's published diagnostics operation. */
+export declare const BROKER_DIAGNOSTICS_OPERATION = "broker.diagnostics";
+/** The only diagnostic protocol this client understands. */
+export declare const BROKER_DIAGNOSTIC_PROTOCOL = 1;
+/** Contract timeout: default 2000 ms, accepted range 1..10000 ms. */
+export declare const OBSERVATION_TIMEOUT_DEFAULT_MS = 2000;
+export declare const OBSERVATION_TIMEOUT_MIN_MS = 1;
+export declare const OBSERVATION_TIMEOUT_MAX_MS = 10000;
+export declare function setObservationClockForTest(clock: (() => number) | null): void;
+/**
+ * Test-only observers for the native stage boundary. Production installs none, and the
+ * hooks never change a branch, a budget or an outcome: they only report what the
+ * observation did (`onNativeOpen`) and give a test a point to disturb the environment
+ * between the first publication read and the connection (`afterInitialRead`), which is how
+ * the pre-socket identity recheck is proven instead of argued.
+ */
+export interface ObservationTestHooks {
+    onNativeOpen?: (info: {
+        agentDir: string;
+        budgetMs: number;
+    }) => void;
+    afterInitialRead?: () => void;
+    /** Reports that the retained lease was released, on every exit path. */
+    onLeaseClosed?: () => void;
+    /**
+     * Decorates the retained lease so a test can identify the real operation phases and make
+     * a chosen phase refuse or throw. Production installs none.
+     */
+    wrapLease?: (lease: DiagnosticSnapshotLease) => DiagnosticSnapshotLease;
+    /** Replaces the loader result so loader-stage outcomes can be observed deterministically. */
+    loaderOverride?: () => DiagnosticNativeLoad;
+}
+/** Minimal shapes this facade relies on from the approved read-only loader. */
+interface DiagnosticSnapshotRead {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+    readonly bytes?: Uint8Array | null;
+}
+interface DiagnosticSnapshotStatus {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+}
+interface DiagnosticSnapshotLease {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+    read(): DiagnosticSnapshotRead;
+    revalidate(): DiagnosticSnapshotStatus;
+    close(): void;
+}
+type DiagnosticNativeLoad = {
+    ok: true;
+    value: {
+        openDiagnosticSnapshot(agentDir: string, budgetMs: number): DiagnosticSnapshotLease;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function setObservationTestHooksForTest(hooks: ObservationTestHooks | null): void;
+/** Malformed arguments are a typed caller error, never an observed unavailability. */
+export declare class DiagnosticOptionsError extends Error {
+    readonly code: "invalid_arguments";
+    readonly field: string;
+    constructor(field: string);
+}
+export type ObservationOptionsVerdict = {
+    ok: true;
+    value: {
+        agentDir: string;
+        expectedGeneration?: string;
+        timeoutMs: number;
+    };
+} | {
+    ok: false;
+    error: {
+        code: "invalid_arguments";
+        field: string;
+    };
+};
+/** Validate the caller's options against the exact contract. Pure and total. */
+export declare function validateObservationOptions(options: unknown): ObservationOptionsVerdict;
+/** Whether the endpoint is the canonical owned loopback endpoint with an in-range port. */
+export declare function canonicalLoopbackEndpoint(url: string): boolean;
+/**
+ * Parse verdicts for the publication bytes. A publication that is well formed but
+ * carries no diagnostic capability is NOT malformed: an old broker like that is
+ * `unsupported`, never `invalid_response` and never `absent`.
+ */
+export type PublicationVerdict = {
+    kind: "ok";
+    value: ObservedPublication;
+} | {
+    kind: "no-capability";
+} | {
+    kind: "malformed";
+};
+/** The publication fields this route reads; every other field is ignored, never trusted. */
+export interface ObservedPublication {
+    readonly url: string;
+    readonly token: string;
+    readonly ownerId: string;
+    readonly pid: number;
+    readonly incarnation: string | null;
+    readonly agentRoot: string | null;
+    readonly generation: string;
+    readonly diagnosticProtocol: number;
+}
+/** Parse the publication bytes the native lease returned. Strict, bounded, total. */
+export declare function parsePublicationVerdict(bytes: Uint8Array): PublicationVerdict;
+/** Convenience wrapper for callers that only need the accepted shape. */
+export declare function parsePublication(bytes: Uint8Array): ObservedPublication | null;
+/** The exact answered payload this client accepts; unknown fields are refused. */
+interface AnsweredDiagnostics {
+    readonly generation: string;
+    readonly build: BrokerObservationBuild;
+    readonly identity: {
+        readonly ownerId: string;
+        readonly pid: number;
+        readonly agentRoot: string;
+    };
+}
+/** Strictly validate the broker's answer, mapping every refusal onto the reason enum. */
+export declare function parseAnsweredDiagnostics(response: unknown): {
+    kind: "ok";
+    value: AnsweredDiagnostics;
+} | {
+    kind: "unavailable";
+    reason: BrokerObservationUnavailableReason;
+};
+/** Two publication observations describe the same authority. */
+export declare function sameAuthority(first: ObservedPublication, second: ObservedPublication): boolean;
+/** The broker's answer agrees with the publication on generation and identity. */
+export declare function answerMatchesAuthority(answer: AnsweredDiagnostics, publication: ObservedPublication): boolean;
+/**
+ * Observe an already running broker. Never starts, ensures, recovers or retires one.
+ */
+export declare function observeExistingBroker(options: ObserveExistingBrokerOptions | unknown): Promise<BrokerObservation>;
+export {};

package/dist/types/sdk/host/control/operations.d.ts

@@ -20,7 +20,7 @@ export type ControlInput = Record<string, unknown>;
  */
 export interface ControlSurface {
     prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-    steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
+    steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
     followUp(text: string): Promise<ControlValue> | ControlValue;
     abort(): Promise<ControlValue> | ControlValue;
     /** Terminal abort: stop the current root turn (and optionally exact owned work). */

package/dist/types/sdk/host/session-runtime.d.ts

@@ -3,6 +3,7 @@ import { type Settings } from "../../config/settings";
 import type { ExtensionAPI, ExtensionContext } from "../../extensibility/extensions";
 import type { AgentEndEvent } from "../../extensibility/shared-events";
 import { ensureBroker } from "../broker/ensure";
+import { captureRuntimeImageIdentity } from "../broker/runtime";
 import { type MasterRoleAttestationV2, SessionIndex, type SessionLocatorV2 } from "../broker/session-index";
 import type { SdkPromptTerminalOutcome } from "../prompt-status";
 import { type ReceiptState } from "../receipt-state";
@@ -286,6 +287,12 @@ export interface CreateSdkSessionRuntimeOptions {
     onFailureDiagnosticKeyCountForTests?: (count: number) => void;
     /** Test-only observation after a resolved invocation completion is reconciled. */
     onInvocationCompletionReconciledForTests?: (kind: InvocationKind, correlation: InvocationCorrelation) => void;
+    /** Test hook: provides a function to inject a controlled clock for broker recovery backoff assertions. */
+    setRecoveryBackoffClockForTest?: (inject: (clock: {
+        now(): number;
+    }) => void) => void;
+    /** Test hook: inject mock runtime image identity and replacement detection for broker recovery tests. */
+    setRuntimeImageIdentityForTest?: (register: (captureFn: () => Awaited<ReturnType<typeof captureRuntimeImageIdentity>> | undefined, isReplacedFn: () => Promise<boolean>) => void) => void;
 }
 export interface InvocationCorrelation {
     commandId: string;

package/dist/types/sdk/index.d.ts

@@ -1,6 +1,7 @@
 export { MODEL_PROFILE_DISCOVERY_QUERY, MODEL_PROFILE_ERROR_DETAIL_MAX_BYTES, type ModelProfileCatalogItem, type ModelProfileErrorCode, type ModelProfileErrorDetails, ModelProfileRegistryError, type ModelProfileRegistryErrorDetails, type UnknownModelProfileDetails, UnknownModelProfileError, } from "../config/model-profile-contract";
 export type { QueuedInputAdmission, QueuedInputDelivery, QueuedInputExecution, QueuedInputQueuePolicy, QueuedInputRemovalReason, QueuedInputSubmission, QueuedInputTerminal, SendUserMessageOptions, TrackedSendUserMessageOptions, } from "../session/agent-session";
 export * as bus from "./bus";
+export * from "./diagnostics/observe-broker";
 export * as host from "./host";
 export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";

package/dist/types/sdk/prompt-watchdog.d.ts

@@ -65,7 +65,7 @@ export declare const ACP_PROMPT_INFERENCE_TIMEOUT_MS: number;
 export declare class PromptActivity {
     #private;
     /** Folds one inbound frame's lifecycle event into the in-flight tool and model state. */
-    observe(eventType: string | undefined, toolCallId: string | undefined, messageRole: string | undefined): void;
+    observe(eventType: string | undefined, toolCallId: string | undefined, messageRole: string | undefined, messageHasToolCall?: boolean): void;
     /** True while at least one started tool call has not reported an end. */
     get running(): boolean;
     /** True while a dispatched model call has not produced the first frame of its response. */

package/dist/types/sdk/router/session-router.d.ts

@@ -177,6 +177,8 @@ export interface SessionRouterOptions {
     agentDir: string;
     /** Limits attachment to exact ids selected by a Broker-scoped operation. */
     sessionIds?: readonly string[];
+    /** Dynamically limits attachment to sessions currently owned by the caller. */
+    attachFilter?: (sessionId: string) => boolean;
     /** Marks default SDK clients as notification-only observers; demanding by default. */
     observer?: boolean;
     deps?: SessionRouterDeps;

package/dist/types/sdk/session.d.ts

@@ -188,6 +188,12 @@ export interface CreateAgentSessionOptions {
      * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
      */
     deferMemoryBackendStartup?: boolean;
+    /**
+     * Skip optional model-catalog discovery during lifecycle startup. ACP hosts must
+     * publish their endpoint before unrelated provider credential refreshes begin.
+     * @internal lifecycle-only startup guard.
+     */
+    deferOptionalModelRefresh?: boolean;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
     /** Skip Python kernel availability check and prelude warmup */
@@ -297,6 +303,13 @@ export interface CreateAgentSessionResult {
      */
     gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
+/**
+ * Start optional provider/model discovery only when it is safe to add work to
+ * the caller's startup graph. Lifecycle hosts deliberately skip this during
+ * construction: discovery preflights every configured provider and may refresh
+ * an unrelated OAuth credential while several hosts are opening the same DB.
+ */
+export declare function startOptionalModelRefresh(modelRegistry: Pick<ModelRegistry, "refreshInBackground">, credentialSessionId: string | undefined, deferred: boolean): boolean;
 export interface DeferredMcpConfigStartupResult {
     loadedToolCount: number;
     hasErrors: boolean;

package/dist/types/session/agent-session.d.ts

@@ -1111,7 +1111,11 @@ export declare class AgentSession {
     get sessionWorkLease(): SessionWorkLease;
     /** Stable resource ownership identifier for the active prompt run. */
     get activePromptHandle(): string | undefined;
-    /** All messages including custom types like BashExecutionMessage */
+    /**
+     * All messages including custom types like BashExecutionMessage. Request-scoped
+     * ephemeral copies are retained only in `agent.state.messages` to keep the provider
+     * cache prefix stable; they are never part of this public view.
+     */
     get messages(): AgentMessage[];
     get transcriptPromptGeneration(): number;
     static restoreFromMemoryGuardCheckpoint(input: AgentSessionMemoryGuardRestoreInput): Promise<AgentMemoryGuardRestoreResult>;