@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/runtime-mcp/tool-bridge.ts

@@ -43,6 +43,13 @@ export interface MCPToolOptions {
 	 * owning manager/runtime. Resolved per call so late registration still applies.
 	 */
 	inputHandler?: () => MCPInputRequestHandler | undefined;
+	/**
+	 * Exact MCP session control: false while the owning manager has this server
+	 * suspended. Checked alongside `#sessionControlInvalidated` so a wrapper that
+	 * outlives a resume/reconnect still fails locally instead of reaching the
+	 * transport for a server this session no longer has active.
+	 */
+	isAvailable?: () => boolean;
 }
 
 function connectionForTool(target: MCPToolTarget): MCPServerConnection {
@@ -235,6 +242,7 @@ export function parseMCPToolName(name: string): { serverName: string; toolName:
  * CustomTool wrapping an MCP tool with an active connection.
  */
 export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
+	// Exact MCP stale wrappers fail before transport RPC.
 	readonly name: string;
 	readonly label: string;
 	readonly description: string;
@@ -247,6 +255,14 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 	private connection: MCPServerConnection;
 	#noReplay = false;
 	#inputHandlerResolver: (() => MCPInputRequestHandler | undefined) | undefined;
+	#isAvailable: (() => boolean) | undefined;
+	#sessionControlInvalidated = false;
+	invalidateForSessionControl(): void {
+		this.#sessionControlInvalidated = true;
+	}
+	#isAvailableForSessionControl(): boolean {
+		return !this.#sessionControlInvalidated && this.#isAvailable?.() !== false;
+	}
 
 	#callOptions(signal?: AbortSignal): MCPRequestOptions {
 		const inputHandler = this.#inputHandlerResolver?.();
@@ -272,6 +288,7 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		this.connection = resolvedConnection;
 		this.#noReplay = options?.noReplay === true;
 		this.#inputHandlerResolver = options?.inputHandler;
+		this.#isAvailable = options?.isAvailable;
 		this.name = createMCPToolName(resolvedConnection.name, tool.name);
 		this.label = `${resolvedConnection.name}/${tool.name}`;
 		this.description = tool.description ?? `MCP tool from ${resolvedConnection.name}`;
@@ -299,6 +316,15 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		const args = normalizeToolArgs(params);
 		const provider = this.connection._source?.provider;
 		const providerName = this.connection._source?.providerName;
+		if (!this.#isAvailableForSessionControl()) {
+			return buildErrorResult(
+				new Error("MCP server is suspended for this session"),
+				this.connection.name,
+				this.tool.name,
+				provider,
+				providerName,
+			);
+		}
 
 		try {
 			const result = await callTool(this.connection, this.tool.name, args, this.#callOptions(signal));
@@ -308,6 +334,15 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 			if (this.reconnect && isRetriableConnectionError(error)) {
 				const newConn = await reconnectWithAbort(this.reconnect, signal);
 				if (newConn) {
+					if (!this.#isAvailableForSessionControl()) {
+						return buildErrorResult(
+							new Error("MCP server is suspended for this session"),
+							this.connection.name,
+							this.tool.name,
+							provider,
+							providerName,
+						);
+					}
 					if (this.#noReplay)
 						return buildErrorResult(error, this.connection.name, this.tool.name, provider, providerName);
 					// Rebind so subsequent calls on this instance use the fresh connection
@@ -350,6 +385,14 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 	readonly #fallbackProviderName: string | undefined;
 	#noReplay = false;
 	#inputHandlerResolver: (() => MCPInputRequestHandler | undefined) | undefined;
+	#isAvailable: (() => boolean) | undefined;
+	#sessionControlInvalidated = false;
+	invalidateForSessionControl(): void {
+		this.#sessionControlInvalidated = true;
+	}
+	#isAvailableForSessionControl(): boolean {
+		return !this.#sessionControlInvalidated && this.#isAvailable?.() !== false;
+	}
 
 	#callOptions(signal?: AbortSignal): MCPRequestOptions {
 		const inputHandler = this.#inputHandlerResolver?.();
@@ -386,6 +429,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		this.#fallbackProviderName = source?.providerName;
 		this.#noReplay = options?.noReplay === true;
 		this.#inputHandlerResolver = options?.inputHandler;
+		this.#isAvailable = options?.isAvailable;
 	}
 
 	renderCall(args: unknown, _options: RenderResultOptions, theme: Theme) {
@@ -407,6 +451,15 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		const args = normalizeToolArgs(params);
 		const provider = this.#fallbackProvider;
 		const providerName = this.#fallbackProviderName;
+		if (!this.#isAvailableForSessionControl()) {
+			return buildErrorResult(
+				new Error("MCP server is suspended for this session"),
+				this.serverName,
+				this.tool.name,
+				provider,
+				providerName,
+			);
+		}
 
 		try {
 			const connection = await untilAborted(signal, () => this.getConnection());
@@ -425,6 +478,15 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 				if (this.reconnect && isRetriableConnectionError(callError)) {
 					const newConn = await reconnectWithAbort(this.reconnect, signal);
 					if (newConn) {
+						if (!this.#isAvailableForSessionControl()) {
+							return buildErrorResult(
+								new Error("MCP server is suspended for this session"),
+								this.serverName,
+								this.tool.name,
+								provider,
+								providerName,
+							);
+						}
 						if (this.#noReplay)
 							return buildErrorResult(callError, this.serverName, this.tool.name, provider, providerName);
 						const retryProvider = newConn._source?.provider ?? provider;
@@ -453,6 +515,15 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 			rethrowIfAborted(connError, signal);
 			if (this.reconnect) {
 				const newConn = await reconnectWithAbort(this.reconnect, signal);
+				if (newConn && !this.#isAvailableForSessionControl()) {
+					return buildErrorResult(
+						new Error("MCP server is suspended for this session"),
+						this.serverName,
+						this.tool.name,
+						provider,
+						providerName,
+					);
+				}
 				if (newConn && !this.#noReplay) {
 					try {
 						const result = await callTool(newConn, this.tool.name, args, this.#callOptions(signal));

package/src/runtime-mcp/transports/http.ts

@@ -8,6 +8,7 @@
  * no sessions, no standalone stream, no replay. See ../protocol.ts.
  */
 import { logger, readSseJson, Snowflake } from "@gajae-code/utils";
+import { isResourceOwnerDisposalActive, registerResourceOwner } from "../../runtime/process-lifecycle";
 import type {
 	JsonRpcError,
 	JsonRpcMessage,
@@ -30,6 +31,51 @@ import {
 import { fetchPluginMcpRequest, isPluginMcpPublicNetworkBound } from "../plugin-network-boundary";
 import { buildModernMcpHeaders, type MCPModernClientContext, type MCPProtocolEra, withModernMeta } from "../protocol";
 
+/**
+ * Postmortem release of live HTTP/SSE MCP sessions.
+ *
+ * A stdio server dies with the agent because it is a `spawnOwnedProcess` child, but an
+ * HTTP/SSE server is a separate, already-running process that only learns a client is gone
+ * from the session-termination `DELETE`. A signal kill (`SIGINT`/`SIGTERM`/`SIGHUP`) or a
+ * fatal exit bypasses session dispose, so without this sweep the server keeps the
+ * `Mcp-Session-Id` and everything hanging off it for every agent run that ever died -
+ * unbounded growth on the server side. Mirrors the LSP/Python/browser owners.
+ */
+const liveHttpTransports = new Set<HttpTransport>();
+let httpTransportOwnerRelease: (() => void) | undefined;
+/** Exit must not wait on a wedged endpoint; the per-request timeout is up to 30s. */
+const POSTMORTEM_CLOSE_TIMEOUT_MS = 2_000;
+
+function trackHttpTransport(transport: HttpTransport): void {
+	liveHttpTransports.add(transport);
+	httpTransportOwnerRelease ??= registerResourceOwner("mcp:http-transports", closeLiveHttpTransports);
+}
+
+function untrackHttpTransport(transport: HttpTransport): void {
+	if (!liveHttpTransports.delete(transport) || liveHttpTransports.size > 0) return;
+	// Nothing left to release: drop the registration so a long-lived host does not
+	// retain dead transports through the owner map.
+	httpTransportOwnerRelease?.();
+	httpTransportOwnerRelease = undefined;
+}
+
+async function closeLiveHttpTransports(): Promise<void> {
+	await Promise.all(
+		[...liveHttpTransports].map(async transport => {
+			try {
+				await transport.releaseForPostmortem(AbortSignal.timeout(POSTMORTEM_CLOSE_TIMEOUT_MS));
+			} catch (error) {
+				logger.debug("MCP HTTP postmortem release failed", { error });
+			}
+		}),
+	);
+}
+
+/** Live HTTP/SSE MCP transports awaiting postmortem release. Exposed for leak assertions/tests. */
+export function liveHttpTransportCount(): number {
+	return liveHttpTransports.size;
+}
+
 /** Best-effort JSON parse of an error body for structured era classification. */
 function tryParseJsonBody(text: string): unknown {
 	try {
@@ -101,7 +147,11 @@ export class HttpTransport implements MCPTransport {
 	 */
 	async connect(): Promise<void> {
 		if (this.#connected) return;
+		if (isResourceOwnerDisposalActive()) {
+			throw new Error("Cannot connect MCP HTTP transport during process resource disposal");
+		}
 		this.#connected = true;
+		trackHttpTransport(this);
 	}
 
 	#fetch(init: BunFetchRequestInit): Promise<Response> {
@@ -601,11 +651,8 @@ export class HttpTransport implements MCPTransport {
 		}
 	}
 
-	async close(): Promise<void> {
-		const wasConnected = this.#connected;
-		this.#connected = false;
-
-		// Abort all SSE/background readers and wait for them to settle.
+	/** Abort every SSE/background reader. Does not wait for them to settle. */
+	#abortStreams(): void {
 		for (const controller of this.#streamControllers) {
 			controller.abort();
 		}
@@ -613,30 +660,66 @@ export class HttpTransport implements MCPTransport {
 			this.#sseConnection.abort();
 			this.#sseConnection = null;
 		}
+	}
+
+	/**
+	 * Send session termination (legacy era only; the modern era has no protocol
+	 * session to terminate). This DELETE is the only signal an already-running
+	 * HTTP/SSE server gets that its session may be dropped.
+	 */
+	async #terminateSession(signal?: AbortSignal): Promise<void> {
+		if (this.#era === "modern") return;
+		const sessionId = this.#sessionId;
+		if (!sessionId) return;
+		// Claim the server session before awaiting the wire request. Graceful close
+		// and postmortem disposal can overlap during shutdown; only the caller that
+		// detached this id may emit its termination DELETE.
+		this.#sessionId = null;
+		try {
+			const timeout = this.config.timeout ?? 30000;
+			const headers: Record<string, string> = {
+				...this.config.headers,
+				"Mcp-Session-Id": sessionId,
+			};
+
+			const timeoutSignal = AbortSignal.timeout(timeout);
+			await this.#fetch({
+				method: "DELETE",
+				headers,
+				signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal,
+			});
+		} catch {
+			// Ignore termination errors
+		}
+	}
+
+	/**
+	 * Terminate the server-side session on a signal or fatal exit, without the
+	 * reader drain `close()` does: postmortem runs inside the signal handler,
+	 * where an aborted SSE body read is never observed by JS, so awaiting the
+	 * readers there never settles and the DELETE stays unreachable. `onClose` is
+	 * deliberately not fired - the manager reacts to it by reconnecting, which
+	 * would open a fresh server session on the way out.
+	 */
+	async releaseForPostmortem(signal: AbortSignal): Promise<void> {
+		untrackHttpTransport(this);
+		this.#connected = false;
+		this.#abortStreams();
+		await this.#terminateSession(signal);
+	}
+
+	async close(): Promise<void> {
+		untrackHttpTransport(this);
+		const wasConnected = this.#connected;
+		this.#connected = false;
+
+		// Abort all SSE/background readers and wait for them to settle.
+		this.#abortStreams();
 		await Promise.allSettled(Array.from(this.#streamReaders));
 
 		if (!wasConnected && !this.#sessionId) return;
 
-		// Send session termination if we have a session (legacy era only;
-		// the modern era has no protocol session to terminate)
-		if (this.#era !== "modern" && this.#sessionId) {
-			try {
-				const timeout = this.config.timeout ?? 30000;
-				const headers: Record<string, string> = {
-					...this.config.headers,
-					"Mcp-Session-Id": this.#sessionId,
-				};
-
-				await this.#fetch({
-					method: "DELETE",
-					headers,
-					signal: AbortSignal.timeout(timeout),
-				});
-			} catch {
-				// Ignore termination errors
-			}
-			this.#sessionId = null;
-		}
+		await this.#terminateSession();
 
 		this.onClose?.();
 		this.onClose = undefined;

package/src/sdk/acp/adapter.ts

@@ -9,6 +9,7 @@ import {
 	type SessionReconcileUncertainTarget,
 	validateSessionReconcileUncertainTarget,
 } from "../lifecycle/service";
+import { ACP_PROMPT_INACTIVITY_TIMEOUT_MS } from "../prompt-watchdog";
 import {
 	validateAdapterControl,
 	validateAdapterSecretFields,
@@ -19,11 +20,47 @@ import { type SessionAttachment, type SessionRouter, SessionRouterError } from "
 import { ACP_SESSION_RECONNECT, SESSION_ABORT_TIMEOUT_MS } from "../session-reconnect";
 import type { SessionLifecycleMcpServer } from "./mcp";
 
+/**
+ * Registration rounds one provider activation may spend chasing a moving attachment.
+ *
+ * The activation loop restarts whenever the Router attachment changes identity while it
+ * is registering, because the leases it just took belong to a connection that no longer
+ * exists. One reconnect costs one restart, so a handful covers any churn that is actually
+ * converging; beyond that the attachment is rotating faster than registration completes
+ * and another round only re-takes leases that will be invalidated again. Bounding this is
+ * what turns "many session hosts contend for one agent dir" from an unbounded spin into a
+ * reported failure (issue #5658).
+ */
+export const PROVIDER_ACTIVATION_MAX_ATTEMPTS = 8;
+
+/**
+ * Wall-clock budget for the same loop.
+ *
+ * The attempt cap alone bounds rounds, not time: every round is a `#requestSession` round
+ * trip per provider, so under lease contention attempts are slow rather than fast-spinning
+ * and eight of them can still outlast the caller. The budget is sized to a third of
+ * {@link ACP_PROMPT_INACTIVITY_TIMEOUT_MS} so a prompt stalled in provider preflight fails
+ * with this error — which names the contended capability — with room to spare before the
+ * ACP prompt watchdog reports the same stall as undifferentiated silence.
+ *
+ * It gates *starting* another round, never interrupting one in flight: a single slow but
+ * healthy registration keeps whatever time it needs, and only a retry decided after the
+ * deadline is refused.
+ */
+export const PROVIDER_ACTIVATION_BUDGET_MS = Math.floor(ACP_PROMPT_INACTIVITY_TIMEOUT_MS / 3);
+
 type JsonObject = Record<string, unknown>;
 function object(value: unknown): JsonObject | undefined {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as JsonObject) : undefined;
 }
 
+function preservePromptFailureMetadata(target: Error, source: JsonObject | undefined): void {
+	if (!source) return;
+	const providerCode = source.providerCode ?? object(source.transportFailure)?.providerCode;
+	if (providerCode !== undefined) Object.assign(target, { providerCode });
+	if (source.phase !== undefined) Object.assign(target, { phase: source.phase });
+}
+
 function providerErrorCode(error: unknown): string | undefined {
 	if (error instanceof AcpSdkAdapterError || error instanceof SdkClientError || error instanceof ReverseLeaseError)
 		return error.code;
@@ -445,10 +482,16 @@ export class AcpSdkAdapter {
 		const envelope = object(response);
 		if (envelope?.ok === false) {
 			const error = object(envelope.error);
-			throw new AcpSdkAdapterError(
+			const adapterError = new AcpSdkAdapterError(
 				typeof error?.code === "string" ? error.code : "request_failed",
 				typeof error?.message === "string" ? error.message : "SDK session request failed.",
 			);
+			// Prompt failures may carry the bounded classifier computed by the host. Keep
+			// those fields on the adapter error so the ACP boundary can project them instead
+			// of reconstructing a bare `{ code, details }` pair. `acpRequestFailure` performs
+			// the final safe-token validation before anything reaches the wire.
+			preservePromptFailureMetadata(adapterError, error);
+			throw adapterError;
 		}
 		return envelope?.result ?? response;
 	}
@@ -464,13 +507,19 @@ export class AcpSdkAdapter {
 		const sessionId = this.#sessionId;
 		if (!attachment || !sessionId || !attachment.isCurrent())
 			throw new SessionRouterError("pre_send", "SDK session attachment is stale.");
-		const response = await router.request(
-			sessionId,
-			{ ...frame, id: randomUUID() },
-			attachment.generation,
-			attachment,
-			options,
-		);
+		let response: Record<string, unknown>;
+		try {
+			response = await router.request(
+				sessionId,
+				{ ...frame, id: randomUUID() },
+				attachment.generation,
+				attachment,
+				options,
+			);
+		} catch (error) {
+			if (error instanceof SdkClientError) preservePromptFailureMetadata(error, object(error.details));
+			throw error;
+		}
 		if (!attachment.isCurrent())
 			throw new SessionRouterError("ambiguous", "SDK session attachment changed while awaiting command response.");
 		return raw ? response : this.#unwrapSessionResponse(response);
@@ -600,7 +649,12 @@ export class AcpSdkAdapter {
 		}
 
 		const activation = (async () => {
-			for (;;) {
+			const startedAt = Date.now();
+			// Exhaustion is checked here, outside the try below, so the throw cannot be caught
+			// by the same `continue` branch that spent the budget.
+			for (let attempt = 1; ; attempt++) {
+				if (attempt > PROVIDER_ACTIVATION_MAX_ATTEMPTS || Date.now() - startedAt >= PROVIDER_ACTIVATION_BUDGET_MS)
+					throw this.#providerActivationExhausted(attempt - 1, startedAt);
 				const attachment = this.#attachment;
 				const connectionId = attachment?.connectionId;
 				try {
@@ -652,6 +706,33 @@ export class AcpSdkAdapter {
 		}
 	}
 
+	/**
+	 * Names what the exhausted activation loop was still fighting over, so a stalled
+	 * preflight is attributable to a capability instead of surfacing as generic silence.
+	 */
+	#providerActivationExhausted(attempts: number, startedAt: number): AcpSdkAdapterError {
+		const elapsedMs = Date.now() - startedAt;
+		const contended = this.#providers
+			.filter(provider => !this.#leases.has(provider.capability))
+			.map(provider => provider.capability);
+		const detail =
+			contended.length > 0
+				? `still unleased: ${contended.join(", ")}`
+				: "the SDK session attachment changed identity on every attempt";
+		logger.error("acp_provider_activation_exhausted", {
+			sessionId: this.#sessionId,
+			attempts,
+			elapsedMs,
+			contended,
+			leaseCount: this.#leases.size,
+		});
+		return new AcpSdkAdapterError(
+			"provider_activation_exhausted",
+			`SDK provider activation did not converge after ${attempts} attempts over ${Math.round(elapsedMs / 1_000)}s ` +
+				`(${detail}). The session host is contending for provider leases it cannot hold.`,
+		);
+	}
+
 	#assertGenericDisposition(kind: "control" | "global", sdkId: string): void {
 		const operation = OPERATIONS.find(candidate => candidate.kind === kind && candidate.sdkId === sdkId);
 		if (!operation) throw new AcpSdkAdapterError("unknown_operation", `Unknown SDK ${kind}: ${sdkId}`);

package/src/sdk/acp/final-text.ts

@@ -31,10 +31,27 @@ export function acpFinalTextFromMessage(message: unknown): BoundedAcpFinalText {
 	return boundAcpFinalText(parts.join(""));
 }
 
+/**
+ * Assistant-content presence is trimmed everywhere in the prompt pipeline: whitespace carries no
+ * assistant content. The ACP retry gate, prompt reconciliation
+ * (`sdk/bus/prompt-reconciliation.ts`) and terminal publication must agree, otherwise a terminal
+ * the retry gate treats as "no output" can still publish a whitespace chunk alongside the retry's
+ * real answer (review P2 on #5628).
+ */
+export function hasAcpFinalTextContent(value: string): boolean {
+	return value.trim().length > 0;
+}
+
 export function resolveAcpFinalText(streamed: string, finalText: string): AcpFinalTextResolution {
 	const final = boundAcpFinalText(finalText);
-	if (!final.text || streamed === final.text || streamed.includes(final.text)) return { kind: "none", final };
+	if (!hasAcpFinalTextContent(final.text) || streamed === final.text || streamed.includes(final.text))
+		return { kind: "none", final };
 	if (!streamed) return { kind: "emit", final, text: final.text };
-	if (final.text.startsWith(streamed)) return { kind: "emit", final, text: final.text.slice(streamed.length) };
+	if (final.text.startsWith(streamed)) {
+		// A pure-whitespace delta is the same defect class as whitespace-only final text: it adds no
+		// assistant content, so it must not reach consumers either.
+		const tail = final.text.slice(streamed.length);
+		return hasAcpFinalTextContent(tail) ? { kind: "emit", final, text: tail } : { kind: "none", final };
+	}
 	return { kind: "divergent", final };
 }