@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/sdk/prompt-deadline-manager.ts

@@ -1,3 +1,4 @@
+import { logger } from "@gajae-code/utils";
 import type { KindAwareReconciliation } from "./bus/kind-aware-reconciliation";
 import type { InvocationCorrelation, InvocationReconciliation } from "./host/session-runtime";
 import {
@@ -16,6 +17,56 @@ const MAX_UNCERTAINTY_RETRIES = 3;
 const EXPIRY_RETRY_DELAY_MS = 1_000;
 const UNCERTAINTY_RETRY_DELAY_MS = 1_000;
 
+/**
+ * Hard real-time bound on the best-effort durability hook, shared with
+ * `prompt-deadline-flush` so the manager's race and the flush's own abort
+ * signal cannot drift apart.
+ */
+export const DEADLINE_FLUSH_TIMEOUT_MS = 10_000;
+
+/**
+ * Run a best-effort durability flush under a hard real-time bound that ALWAYS
+ * settles, and never let its result reach the caller.
+ *
+ * Shared by both expiry paths — this manager and the notification bus's own
+ * terminalization (#5583) — so there is one bound, one abort, and one warning,
+ * with no drift between them. A rejection is swallowed; a `run` that never
+ * settles is abandoned after `timeoutMs` with its signal aborted so any git
+ * subprocess dies. The signal alone is not sufficient: `git.withRepoLock`
+ * awaits its predecessor before honouring it, so a hung predecessor in the
+ * per-repo write chain is cut only by this outer race.
+ */
+export async function runBoundedDeadlineFlush(
+	run: (signal: AbortSignal) => unknown,
+	timeoutMs: number = DEADLINE_FLUSH_TIMEOUT_MS,
+): Promise<void> {
+	const controller = new AbortController();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	// An async wrapper so a `run` that throws synchronously becomes a rejection.
+	const flushed = (async () => {
+		await run(controller.signal);
+	})();
+	// The abandoned promise may still reject long after we stop awaiting it.
+	flushed.catch(() => {});
+	try {
+		const bound = new Promise<"timeout">(resolve => {
+			timer = setTimeout(() => resolve("timeout"), timeoutMs);
+			// Never let a pending bound keep the process alive.
+			(timer as unknown as { unref?: () => void }).unref?.();
+		});
+		if ((await Promise.race([flushed.then(() => "flushed" as const), bound])) === "timeout") {
+			controller.abort(new Error(`prompt deadline flush exceeded ${timeoutMs}ms`));
+			logger.warn(
+				`sdk: prompt deadline flush exceeded its ${timeoutMs}ms bound; abandoning it and continuing teardown`,
+			);
+		}
+	} catch {
+		// A failing flush never changes the deadline outcome.
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
 type DeadlineReconciliation = InvocationReconciliation | KindAwareReconciliation;
 
 export type PromptDeadlineOutcome = Extract<SdkPromptTerminalOutcome, { kind: "failed" }> & {
@@ -48,20 +99,69 @@ export class PromptDeadlineManager {
 	readonly #getLeaseMs: () => number;
 	readonly #getMaxMs: () => number;
 	readonly #now: () => number;
-	readonly #onExpired?: (correlation: InvocationCorrelation) => void;
+	readonly #onExpired?: (correlation: InvocationCorrelation, outcome?: PromptDeadlineOutcome) => void;
+	readonly #onDeadlineExceeded?: (
+		correlation: InvocationCorrelation,
+		signal: AbortSignal,
+		isCurrent?: () => boolean,
+	) => void | Promise<void>;
+	readonly #deadlineFlushTimeoutMs: number;
 
 	constructor(options: {
 		reconciliation: DeadlineReconciliation;
 		getLeaseMs: () => number;
 		getMaxMs: () => number;
 		now?: () => number;
-		onExpired?: (correlation: InvocationCorrelation) => void;
+		onExpired?: (correlation: InvocationCorrelation, outcome?: PromptDeadlineOutcome) => void;
+		/**
+		 * Best-effort durability hook for the single path that genuinely retires a
+		 * prompt as `prompt_deadline_exceeded` (#5583). Awaited after the durable
+		 * pending claim but BEFORE the durable terminal, so a crash in that window
+		 * leaves the record pending and recovery retries the prompt; a
+		 * rejection is swallowed and never changes the deadline outcome. Not called
+		 * when a real terminal transition or a real failure won the race, nor when
+		 * renewed progress supersedes this expiry instance. The hook receives an
+		 * abort signal that fires when it outruns `deadlineFlushTimeoutMs`, plus a
+		 * generation fence for irreversible worktree adoption.
+		 */
+		onDeadlineExceeded?: (
+			correlation: InvocationCorrelation,
+			signal: AbortSignal,
+			isCurrent?: () => boolean,
+		) => void | Promise<void>;
+		/**
+		 * Hard bound on `onDeadlineExceeded`. Measured with a real timer, not
+		 * `now`, because it guards real subprocesses — which is also why it is a
+		 * constructor option: a fake clock cannot shorten it for tests.
+		 */
+		deadlineFlushTimeoutMs?: number;
 	}) {
 		this.#reconciliation = options.reconciliation;
 		this.#getLeaseMs = options.getLeaseMs;
 		this.#getMaxMs = options.getMaxMs;
 		this.#now = options.now ?? Date.now;
 		this.#onExpired = options.onExpired;
+		this.#onDeadlineExceeded = options.onDeadlineExceeded;
+		this.#deadlineFlushTimeoutMs = options.deadlineFlushTimeoutMs ?? DEADLINE_FLUSH_TIMEOUT_MS;
+	}
+
+	/** Run the durability hook under the shared bound; see `runBoundedDeadlineFlush`. */
+	async #runDeadlineFlush(
+		correlation: InvocationCorrelation,
+		lease: PromptDeadlineLease,
+		generation: number,
+	): Promise<void> {
+		const hook = this.#onDeadlineExceeded;
+		if (hook === undefined) return;
+		const key = leaseKey(correlation);
+		await runBoundedDeadlineFlush(
+			signal =>
+				hook(correlation, signal, () => {
+					const current = this.#leases.get(key);
+					return current === lease && current.generation === generation;
+				}),
+			this.#deadlineFlushTimeoutMs,
+		);
 	}
 
 	#clearTimer(key: string): void {
@@ -165,16 +265,48 @@ export class PromptDeadlineManager {
 			provenance: "deadline",
 			evidence: {},
 		}) as PromptDeadlineOutcome;
+		let winner: SdkPromptTerminalOutcome = outcome;
 		try {
-			await this.#reconciliation.claimPendingOutcome("prompt", correlation, outcome);
+			const claimed = await this.#reconciliation.claimPendingOutcome("prompt", correlation, outcome);
+			if (claimed !== undefined) winner = claimed;
 		} catch {
 			// claim may fail if already claimed (e.g., cancellation won); ignore.
 		}
+		// A real terminal may win between lookup and this claim. Its existing
+		// pending outcome is authoritative: release this expiry fence without
+		// running the deadline-only durability hook or publishing a deadline result.
+		if (winner.kind !== "failed" || winner.code !== "prompt_deadline_exceeded" || winner.provenance !== "deadline") {
+			this.#expiring.delete(key);
+			this.#expiryRetries.delete(key);
+			return;
+		}
 		// Re-verify the captured lease is still authoritative after the claim
 		// await (exact-head review P2): fresh attributable progress during the
 		// claim must cancel this expiry instance instead of surfacing an exceeded
 		// outcome for a prompt that is demonstrably alive.
 		if (this.#backOffIfSuperseded(key, lease, generation)) return;
+		// Durability BEFORE the durable terminal (#5583, #5623 review round 4). The
+		// claim above is already the durable pending marker, so a process death
+		// anywhere in this window leaves the record PENDING and restart recovery
+		// retries the prompt — work that was never autosaved is never reported as
+		// finished. Running the flush after `finalizeOutcome` instead made the
+		// autosave the one step a crash could silently skip, which is the whole
+		// durability guarantee of this change. The cost is that the durable terminal
+		// is delayed by at most the flush's bound.
+		//
+		// The wait is BOUNDED, not just guarded (#5623 review round 2): a hook that
+		// never settles — a blocking git lock, a credential prompt — would leave the
+		// finalize, `#onExpired` and `clear` below unreachable, stranding the prompt
+		// with neither a terminal nor an owner. A try/catch cannot rescue a promise
+		// that never settles, so the flush is raced against a real timer and
+		// abandoned if it outruns it.
+		await this.#runDeadlineFlush(correlation, lease, generation);
+		// Fence again AFTER the flush (#5623 review round 2): the flush is an await
+		// like any other here, and up to ten seconds long, so progress can land and
+		// renew the lease while it runs. A renewed prompt must not be terminalized as
+		// deadline-exceeded by this stale pass; `#backOffIfSuperseded` reschedules on
+		// the way out, so it keeps a live deadline.
+		if (this.#backOffIfSuperseded(key, lease, generation)) return;
 		try {
 			await this.#reconciliation.finalizeOutcome("prompt", correlation, outcome, () => {
 				const current = this.#leases.get(key);
@@ -197,7 +329,7 @@ export class PromptDeadlineManager {
 		// accepted/in-flight invocation without an owner, retry, or deadline
 		// recovery path.
 		try {
-			this.#onExpired?.(correlation);
+			this.#onExpired?.(correlation, outcome);
 		} catch {}
 		this.#expiryRetries.delete(key);
 		this.clear(correlation);

package/src/sdk/prompt-failure.ts

@@ -3,7 +3,12 @@
  * Provider error text is retained only in the local diagnostic log; wire and
  * persisted reconciliation details expose a fixed redacted message.
  */
-import type { SdkPromptFailureCategory, SdkPromptFailurePhase, SdkPromptTerminalOutcome } from "./prompt-status";
+import type {
+	SdkPromptFailureCategory,
+	SdkPromptFailurePhase,
+	SdkPromptFailureRetryability,
+	SdkPromptTerminalOutcome,
+} from "./prompt-status";
 
 export const PROMPT_FAILURE_CODE_MAX = 64;
 const LOCAL_FAILURE_LOG_MAX = 16_384;
@@ -79,6 +84,43 @@ export function promptFailureCategory(
 	return "unknown";
 }
 
+/**
+ * Whether the bounded category says an identical re-submission could still
+ * succeed. Read off the category alone, so it cannot drift from the sets above.
+ *
+ * `provider_transport` is the only transient class: every classifier in
+ * `PROVIDER_TRANSPORT_CODES` (and the 5xx range) describes the link to the
+ * provider failing, never a judgement about the request, so the same bytes may
+ * well succeed on a second attempt. That is exactly the class the shipped
+ * first-turn gate (`isStartupReadinessFailure`, issue #5574) already treats as
+ * re-submittable, so the wire signal and the internal gate stay in agreement.
+ *
+ * Everything else is terminal for this turn: `provider_rejected` is the provider
+ * judging this request (quota, refusal, 4xx) and re-sending it reproduces the
+ * rejection; `deadline` means the turn's budget is spent, which a re-submit does
+ * not restore; `agent_runtime` is a local fault that re-running the same prompt
+ * re-enters. `unknown` stays `unknown` — the module's standing contract is to
+ * preserve uncertain attribution rather than guess a recovery for it.
+ *
+ * This is advisory classification for the caller, not a retry gate: nothing in
+ * this repo's retry paths consults it.
+ */
+export function promptFailureRetryability(category: SdkPromptFailureCategory): SdkPromptFailureRetryability {
+	if (category === "provider_transport") return "transient";
+	if (category === "unknown") return "unknown";
+	return "terminal";
+}
+
+/**
+ * Whether a value is a safe bounded classifier token — the same rule
+ * `sanitizePromptFailure` and `assistantFailureCode` apply before retaining one.
+ * Anything else is provider text rather than a classifier and must not be
+ * forwarded to a caller.
+ */
+export function isSafePromptFailureCode(value: unknown): value is string {
+	return typeof value === "string" && value.length <= PROMPT_FAILURE_CODE_MAX && /^[A-Za-z0-9._-]+$/.test(value);
+}
+
 /**
  * Phase- and category-aware safe wording. A post-start failure is never
  * described as a submission rejection; the wording says only what the bounded

package/src/sdk/prompt-status.ts

@@ -75,6 +75,14 @@ export type SdkPromptFailureCategory =
 	| "agent_runtime"
 	| "deadline"
 	| "unknown";
+/**
+ * Whether the failure class says an identical re-submission could still succeed.
+ * Derived from `SdkPromptFailureCategory` alone (see `promptFailureRetryability`)
+ * so a consumer never has to re-implement the category matrix or parse a message.
+ * `unknown` is preserved rather than collapsed into `terminal`: an uncertain
+ * attribution is not evidence that the turn is unrecoverable.
+ */
+export type SdkPromptFailureRetryability = "transient" | "terminal" | "unknown";
 export type SdkPromptTerminalOutcome =
 	| { kind: "stopped"; reason: SdkPromptStopReason; provenance: "agent" | "client_cancel" }
 	| {

package/src/sdk/prompt-tool-boundary.ts

@@ -0,0 +1,121 @@
+/**
+ * Bounded wait for an in-flight dispatched tool call to reach its boundary
+ * before an expired prompt deadline force-terminates the run (#5637).
+ *
+ * Terminal fencing aborts the run's cancellation domain FIRST and only proves
+ * settlement afterwards (`RunResourceLedger.waitForSettlement` resolves once the
+ * run is sealed and its tracked `kind: "tool"` resources have settled), so a
+ * tool that was mid-write when the deadline expired observes the aborted signal
+ * DURING its write and leaves a torn artifact behind. Waiting for that call's
+ * own `tool_execution_end` — under a short, finite grace — turns the kill into a
+ * boundary abort. When the grace is exhausted the run is force-terminated
+ * exactly as before, and the fact that a tool was still executing is returned as
+ * structured evidence rather than dropped.
+ *
+ * Deliberately dependency-light and clock-injectable: the contended bus module
+ * takes only a call, and the behaviour is testable without a live transport.
+ */
+
+/**
+ * Hard bound on how long deadline expiry will wait for an in-flight tool call to
+ * reach its boundary before force-terminating. This guards a real subprocess, so
+ * it is a real timer rather than the lease clock — and a parameter rather than a
+ * bare module constant, so a test may shorten it explicitly instead of a fake
+ * clock silently shortening it for production code too.
+ */
+export const TOOL_CALL_BOUNDARY_GRACE_MS = 5_000;
+
+/**
+ * Re-check interval for the pending set while the grace runs.
+ *
+ * The authoritative source of "is a tool running?" is the run resource ledger,
+ * a SYNCHRONOUS snapshot with no completion signal of its own, so the wait has
+ * to look again rather than being told. `whenIdle` only wakes the check early
+ * when the event-derived view happens to drain first. Bounded by the grace, so
+ * this costs at most `graceMs / pollMs` array reads on the rare expiry-with-a-
+ * tool-running path and nothing at all on the idle path.
+ */
+export const TOOL_CALL_BOUNDARY_POLL_MS = 25;
+
+export type ToolBoundaryOutcome = "idle" | "settled" | "forced";
+
+export interface ToolBoundaryWaitResult {
+	outcome: ToolBoundaryOutcome;
+	waitedMs: number;
+	/**
+	 * Non-empty ONLY for "forced": the dispatched tool calls still running when
+	 * the grace expired. Ids only — never tool arguments, output or paths.
+	 */
+	pendingToolCallIds: string[];
+}
+
+/**
+ * Shared result for the common case of no dispatched tool running at expiry.
+ * Frozen because it is handed to every idle caller: the deadline path must stay
+ * byte-identical to its pre-#5637 behaviour, which includes allocating nothing
+ * and arming no timer.
+ */
+export const IDLE_TOOL_BOUNDARY_RESULT: ToolBoundaryWaitResult = Object.freeze({
+	outcome: "idle" as const,
+	waitedMs: 0,
+	pendingToolCallIds: Object.freeze([]) as unknown as string[],
+});
+
+/**
+ * Wait for the pending dispatched tool calls to drain, bounded by `graceMs`.
+ *
+ * Never composed with an abort signal: at the only call site nothing has been
+ * aborted yet, and a signal that was already aborted would make this wait
+ * unreachable — which is precisely the mid-tool kill being fixed.
+ */
+export async function waitForToolCallBoundary(input: {
+	pending: () => readonly string[];
+	/**
+	 * Resolves when the event-derived view of the pending set drains. A wake-up
+	 * HINT only: `pending()` is re-read before the wait is allowed to settle,
+	 * because the authoritative source may still hold a call this signal knows
+	 * nothing about. Expected never to reject.
+	 */
+	whenIdle: () => Promise<void>;
+	graceMs?: number;
+	pollMs?: number;
+	now?: () => number;
+}): Promise<ToolBoundaryWaitResult> {
+	const now = input.now ?? Date.now;
+	// Idle prompts pay nothing: no timer, no allocation, no extra microtask turn
+	// beyond the caller's own await.
+	if (input.pending().length === 0) return IDLE_TOOL_BOUNDARY_RESULT;
+	const graceMs = Math.max(0, input.graceMs ?? TOOL_CALL_BOUNDARY_GRACE_MS);
+	const pollMs = Math.max(1, input.pollMs ?? TOOL_CALL_BOUNDARY_POLL_MS);
+	const startedAt = now();
+	let graceTimer: ReturnType<typeof setTimeout> | undefined;
+	let pollTimer: ReturnType<typeof setInterval> | undefined;
+	try {
+		const settled = new Promise<"settled">(resolve => {
+			// `pending()` is the single arbiter of settlement; the idle signal and
+			// the poll only decide WHEN it is consulted.
+			const check = () => {
+				if (input.pending().length === 0) resolve("settled");
+			};
+			// The loser of the race is abandoned rather than cancelled, so a rejection
+			// from it must be swallowed here or it surfaces as an unhandled rejection
+			// and takes the host down. A rejected idle simply leaves the poll and the
+			// grace timer as the arbiters.
+			void input.whenIdle().then(check, () => {});
+			pollTimer = setInterval(check, pollMs);
+			pollTimer?.unref?.();
+		});
+		const forced = new Promise<"forced">(resolve => {
+			graceTimer = setTimeout(() => resolve("forced"), graceMs);
+			// Never hold the process open for a tool that will not come back.
+			graceTimer?.unref?.();
+		});
+		const outcome = await Promise.race([settled, forced]);
+		return outcome === "settled"
+			? { outcome: "settled", waitedMs: now() - startedAt, pendingToolCallIds: [] }
+			: { outcome: "forced", waitedMs: now() - startedAt, pendingToolCallIds: [...input.pending()] };
+	} finally {
+		clearTimeout(graceTimer);
+		clearInterval(pollTimer);
+	}
+}

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2144,6 +2144,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "slash_command:mcp",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "exclude",
+		"rationale": "interactive exact-config MCP status and session control command; terminal-only handleTui surface is not dispatched through ACP or the public SDK",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "slash_command:agents",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
@@ -2188,6 +2199,24 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "slash_command:fork",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "include",
+		"sdkId": "session.branch",
+		"adapterMappings": {
+			"telegram": "prohibited",
+			"discord": "prohibited",
+			"slack": "prohibited",
+			"mcp": "prohibited",
+			"acp": "prohibited",
+			"daemonCli": "prohibited"
+		},
+		"testIds": [
+			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
+		]
+	},
 	{
 		"sourceId": "slash_command:provider",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
@@ -3202,6 +3231,28 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:getExactMcpStatusSnapshot",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal exact-config MCP status accessor used only by the terminal-only /mcp command; its capability is granted only to root interactive --mcp-config sessions, not a public SDK query",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
+	{
+		"sourceId": "agent_session:controlExactMcpServer",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal session-local exact-config MCP suspend/resume/reconnect mutation used only by the terminal-only /mcp command; runtime suppression is not persistent user authority or a public SDK control",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:getSelectedMCPToolNames",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -3891,6 +3942,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:submitUserMessage",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "public in-process embedder lifecycle API; direct handle surface, not an SDK transport operation",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:clearQueue",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -4182,6 +4244,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:pendingToolExecutions",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal read-only run-resource-ledger view, threaded via terminalAbortSeams so the prompt deadline can find a tool-call boundary; not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:abortPromptAndWait",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -4466,6 +4539,39 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:installRecoveredDefaultFallbackChain",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal recovered fallback-chain installation during session startup, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
+	{
+		"sourceId": "agent_session:markStartupRecoveryBindingsRequired",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal startup recovery binding marker, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
+	{
+		"sourceId": "agent_session:hasRecoveredDefaultFallbackChain",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal recovered fallback-chain state query, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:seedDefaultFallbackResolution",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/router/replay-retention-gap-cache.ts

@@ -0,0 +1,27 @@
+/**
+ * Retention-gap concessions are durable stream facts, but a Router can observe
+ * many streams over its lifetime. Keep the warning memo bounded while retaining
+ * enough recent coordinates to suppress reconnect/poll duplicates.
+ */
+export const REPLAY_CONCESSION_CACHE_LIMIT = 1_024;
+
+/**
+ * Records one stream/gap coordinate in an LRU memo.
+ *
+ * `undefined` means this is the first observation; a number is the duplicate
+ * count after the coordinate was already observed.
+ */
+export function rememberReplayRetentionGap(cache: Map<string, number>, key: string): number | undefined {
+	const previous = cache.get(key);
+	if (previous !== undefined) {
+		cache.delete(key);
+		cache.set(key, previous + 1);
+		return previous + 1;
+	}
+	cache.set(key, 0);
+	if (cache.size > REPLAY_CONCESSION_CACHE_LIMIT) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== undefined) cache.delete(oldest);
+	}
+	return undefined;
+}

package/src/sdk/router/session-router.ts

@@ -25,6 +25,7 @@ import {
 	readSdkSessionEndpoint,
 	type SdkSessionEndpoint,
 } from "../client/discovery";
+import { SESSION_HOST_OBSERVER_CAPABILITY, TURN_STREAM_CAPABILITY } from "../host/host";
 import {
 	type ActivatedPreparedSession,
 	type PreparedSessionActivationClient,
@@ -33,6 +34,7 @@ import {
 } from "../session-activation";
 import type { SessionBindingAuthority } from "../session-authority";
 import { ACP_SESSION_RECONNECT, SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
+import { rememberReplayRetentionGap } from "./replay-retention-gap-cache";
 
 export type { SessionBindingAuthority, SessionEndpointAuthority } from "../session-authority";
 
@@ -285,6 +287,8 @@ export interface SessionRouterOptions {
 	agentDir: string;
 	/** Limits attachment to exact ids selected by a Broker-scoped operation. */
 	sessionIds?: readonly string[];
+	/** Marks default SDK clients as notification-only observers; demanding by default. */
+	observer?: boolean;
 	deps?: SessionRouterDeps;
 	/** Runtime-specific identity validation; Router supplies a conservative fallback. */
 	correlateFrame?: SessionRouterFrameCorrelator;
@@ -611,6 +615,7 @@ type AdoptedSession = {
 export class SessionRouter {
 	readonly #agentDir: string;
 	readonly #sessionIds: ReadonlySet<string> | undefined;
+	readonly #observer: boolean;
 	readonly #deps: SessionRouterDeps;
 	readonly #correlateFrame: SessionRouterFrameCorrelator;
 	readonly #index: SessionIndex;
@@ -627,6 +632,8 @@ export class SessionRouter {
 	>();
 	readonly #reviving = new Set<string>();
 	readonly #notificationReceipts = new Map<string, NotificationCleanupReceipt>();
+	/** Recent retention-gap coordinates already reported at warning level. */
+	readonly #concededReplayGaps = new Map<string, number>();
 	#stopTimer: (() => void) | undefined;
 	#reconcileTail: Promise<void> = Promise.resolve();
 	#reconcilePending: { readonly runEpoch: number; force: boolean } | undefined;
@@ -650,6 +657,7 @@ export class SessionRouter {
 	constructor(options: SessionRouterOptions) {
 		this.#agentDir = options.agentDir;
 		this.#sessionIds = options.sessionIds === undefined ? undefined : new Set(options.sessionIds);
+		this.#observer = options.observer === true;
 		this.#deps = options.deps ?? {};
 		this.#correlateFrame = options.correlateFrame ?? fallbackCorrelation;
 		this.#index = this.#deps.createIndex?.(options.agentDir) ?? new DefaultSessionIndex(options.agentDir);
@@ -1516,7 +1524,10 @@ export class SessionRouter {
 				endpointMtimeMs,
 			});
 		} else {
-			const defaultClient = new SdkClient(endpoint.url, endpoint.token, { ...ACP_SESSION_RECONNECT });
+			const defaultClient = new SdkClient(endpoint.url, endpoint.token, {
+				...ACP_SESSION_RECONNECT,
+				...(this.#observer ? { capabilities: [SESSION_HOST_OBSERVER_CAPABILITY, TURN_STREAM_CAPABILITY] } : {}),
+			});
 			transport = defaultClient;
 			connection = defaultClient.connect().then(() => defaultClient);
 		}
@@ -2203,6 +2214,24 @@ export class SessionRouter {
 			`chat daemon replay barrier failed (${reason}); rebuilding session ${attached.sessionId} at generation ${attached.generation} from seq ${attached.cursor.seq}.`,
 		);
 	}
+
+	#logReplayRetentionGap(
+		attached: AttachedSession,
+		gap: Readonly<{ fromSeq: number; toSeq: number }>,
+		recoveredNote: string,
+	): void {
+		const key = JSON.stringify([attached.sessionId, attached.generation, gap.fromSeq, gap.toSeq]);
+		const repeat = rememberReplayRetentionGap(this.#concededReplayGaps, key);
+		if (repeat !== undefined) {
+			logger.debug(
+				`chat daemon replay retention gap repeated (sequences ${gap.fromSeq}-${gap.toSeq}); suppressed warning ${repeat} for session ${attached.sessionId} generation ${attached.generation}.`,
+			);
+			return;
+		}
+		logger.warn(
+			`chat daemon replay conceded a retention gap (sequences ${gap.fromSeq}-${gap.toSeq} are gone from the host${recoveredNote}); session ${attached.sessionId} generation ${attached.generation} resumes at seq ${gap.toSeq + 1}.`,
+		);
+	}
 	#failDelivery(attached: AttachedSession, seq: number, error: unknown): void {
 		const previous = this.#undelivered.get(attached.sessionId);
 		const attempts = previous?.generation === attached.generation && previous.seq === seq ? previous.attempts + 1 : 1;
@@ -2503,9 +2532,7 @@ export class SessionRouter {
 				held.splice(0, held.length, ...carried);
 				const recoveredNote =
 					recovered.length > 0 ? `, ${recovered.length} of them recovered from live delivery` : "";
-				logger.warn(
-					`chat daemon replay conceded a retention gap (sequences ${gap.fromSeq}-${gap.toSeq} are gone from the host${recoveredNote}); session ${attached.sessionId} generation ${attached.generation} resumes at seq ${gap.toSeq + 1}.`,
-				);
+				this.#logReplayRetentionGap(attached, gap, recoveredNote);
 				for (const entry of recovered) this.#rememberRecoveredFrame(attached, entry.seq, entry.frame);
 				if (!(await this.#deliverRecoveredFrames(attached))) return;
 				if (gap.toSeq > attached.cursor.seq) attached.cursor.seq = gap.toSeq;