@gajae-code/coding-agent 0.17.2 → 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" }> & {
@@ -49,6 +100,12 @@ export class PromptDeadlineManager {
 	readonly #getMaxMs: () => number;
 	readonly #now: () => number;
 	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;
@@ -56,12 +113,55 @@ export class PromptDeadlineManager {
 		getMaxMs: () => number;
 		now?: () => number;
 		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);

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/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,
@@ -286,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;
@@ -612,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;
@@ -653,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);
@@ -1519,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);
 		}