@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/sdk/session.ts

@@ -59,6 +59,7 @@ import { loadCapability, reset as resetCapabilities } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
 import type { SourceMeta } from "../capability/types";
 import { AUTOROUTING_INACTIVE_WARNING } from "../config/autorouting-contract";
+import { ModelProfileCredentialError, resolveMissingSessionModelRecovery } from "../config/model-profile-activation";
 import { resolveModelProfileName } from "../config/model-profile-contract";
 import { resolveProfileBindings } from "../config/model-profiles";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
@@ -144,7 +145,7 @@ import {
 	createOptionalRuntimeServices,
 	type OptionalRuntimeServicesOverrides,
 } from "../runtime/optional-runtime-services";
-import { loadAllMCPConfigs, MCPManager } from "../runtime-mcp";
+import { isMCPStartupTimeoutError, loadAllMCPConfigs, MCPManager } from "../runtime-mcp";
 import type { MCPLoadResult } from "../runtime-mcp/manager";
 import type { MCPServerConfig } from "../runtime-mcp/types";
 import {
@@ -1516,6 +1517,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	let processCwdClaimed = false;
 	let hasRegistered = false;
 	let asyncJobManager: AsyncJobManager | undefined;
+	let asyncJobManagerOwned = false;
 	let asyncJobManagerAdmitted = false;
 	let priorAsyncJobManager: AsyncJobManager | undefined;
 	let cleanupOwnedMcpManager: (() => Promise<void>) | undefined;
@@ -1967,9 +1969,22 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const persistedProfileOwnsDefault = acceptedPersistedProfileName
 			? resolveProfileBindings(persistedProfiles.get(acceptedPersistedProfileName)!).defaultSelector !== undefined
 			: false;
-		const startupActiveModelProfile =
+		let startupActiveModelProfile =
 			acceptedInheritedProfileName ??
 			(!hasExplicitModel && acceptedPersistedProfileName ? acceptedPersistedProfileName : undefined);
+		let savedDefaultWasUnresolved = false;
+		let deferredMissingSessionRecovery = false;
+		let retainedRecoveryBindingsAfterLateRestore = false;
+		let recoveredSessionDefault:
+			| {
+					entries: string[];
+					profileName: string;
+					activeIndex: number;
+					thinkingLevel?: ThinkingLevel;
+					explicitThinkingLevel: boolean;
+					skips: Array<{ selector: string; reason: string }>;
+			  }
+			| undefined;
 		// If session has data, restore its configured default chain rather than the
 		// scalar runtime model, which may be a stale fallback from the prior run.
 		if (!hasExplicitModel && !model && hasExistingSession && defaultModelEntries.length > 0) {
@@ -1993,6 +2008,33 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				if (model && preferredCredentialProvider && model.provider !== preferredCredentialProvider) {
 					model = undefined;
 				}
+				savedDefaultWasUnresolved = !model;
+				if (!model && resumeModelBehavior !== "useCurrentDefault") {
+					try {
+						const recovery = await resolveMissingSessionModelRecovery({
+							modelRegistry,
+							settings,
+							defaultEntries: defaultModelEntries,
+							skips: restoredDefaultResolution.skips,
+							savedDefault: existingSession.models.default,
+							credentialSessionId,
+							...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
+						});
+						deferredMissingSessionRecovery = true;
+						if (
+							recovery?.model &&
+							(!preferredCredentialProvider || recovery.model.provider === preferredCredentialProvider)
+						) {
+							model = recovery.model;
+							recoveredSessionDefault = recovery;
+							startupActiveModelProfile = undefined;
+							modelFallbackMessage =
+								"Saved session model is no longer registered; restored the durable default preset instead.";
+						}
+					} catch {
+						deferredMissingSessionRecovery = true;
+					}
+				}
 				if (!model) modelFallbackMessage = `Could not restore model ${defaultModelEntries.join(" -> ")}`;
 			});
 		}
@@ -2028,6 +2070,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			thinkingLevel = restoredThinkingLevel;
 		}
 
+		if (
+			thinkingLevel === undefined &&
+			(restoredThinkingLevel === undefined || restoredThinkingLevel === ThinkingLevel.Inherit) &&
+			recoveredSessionDefault?.explicitThinkingLevel
+		) {
+			thinkingLevel = recoveredSessionDefault.thinkingLevel;
+		}
+
 		if (thinkingLevel === undefined && !hasExplicitModel && defaultRoleSpec.explicitThinkingLevel) {
 			thinkingLevel = defaultRoleSpec.thinkingLevel;
 		}
@@ -2296,6 +2346,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						},
 					})
 				: options.inheritedAsyncJobManager;
+		asyncJobManagerOwned = backgroundJobsEnabled === true && !options.parentTaskPrefix;
 
 		let promptMetadataModel: Model | undefined;
 		const getActiveModelString = (): string | undefined => {
@@ -3128,10 +3179,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				// consumed (publication happens before the starter can run), which is
 				// acceptable only because deferral never carries plugin-bundle servers.
 				gjcProducersComplete = false;
-				logger.warn("GJC plugin MCP connect failed", {
-					path: `mcp:${server}`,
-					error: safeErrorForLog(err),
-				});
+				if (!isMCPStartupTimeoutError(err)) {
+					logger.warn("GJC plugin MCP connect failed", {
+						path: `mcp:${server}`,
+						error: safeErrorForLog(err),
+					});
+				}
 			}
 			const connectedPluginNames = new Set(result.connectedServers.filter(name => pluginNames.has(name)));
 			// Retain while any conventional server is still live: "connecting"
@@ -3493,6 +3546,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 									if (!session) throw new Error("Terminal abort session is not initialized.");
 									return session.abortPromptAndWait(handle, seamOptions);
 								},
+								pendingToolExecutions: handle => {
+									if (!session) throw new Error("Terminal abort session is not initialized.");
+									return session.pendingToolExecutions(handle);
+								},
 							},
 							ensureProviderDaemon: options.ensureNotificationProviderDaemon,
 							runBtwTurn: async (question, signal) => {
@@ -3583,6 +3640,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 									if (!session) throw new Error("Terminal abort session is not initialized.");
 									return session.abortPromptAndWait(handle, seamOptions);
 								},
+								pendingToolExecutions: handle => {
+									if (!session) throw new Error("Terminal abort session is not initialized.");
+									return session.pendingToolExecutions(handle);
+								},
 							},
 						});
 					}
@@ -3701,6 +3762,103 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			extensionsResult.runtime.pendingProviderRegistrations = [];
 		}
 
+		// A startup extension can register the saved model after the initial
+		// recovery lookup. Reconsider the saved chain against that completed
+		// catalog before retaining a durable runtime fallback.
+		if (savedDefaultWasUnresolved && defaultModelEntries.length > 0) {
+			const restoredAfterExtensions = await resolveModelChainWithAuth(
+				defaultModelEntries,
+				modelRegistry,
+				settings,
+				credentialSessionId,
+				{
+					managedFallback: defaultModelEntries.length > 1,
+					canonicalSessionId: providerSessionId,
+					...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
+				},
+			);
+			if (
+				restoredAfterExtensions.model &&
+				(!preferredCredentialProvider || restoredAfterExtensions.model.provider === preferredCredentialProvider)
+			) {
+				model = restoredAfterExtensions.model;
+				retainedRecoveryBindingsAfterLateRestore = savedDefaultWasUnresolved;
+				if (options.thinkingLevel !== undefined) {
+					thinkingLevel = resolveThinkingLevelForModel(model, options.thinkingLevel);
+				} else if (restoredThinkingLevel !== undefined && restoredThinkingLevel !== ThinkingLevel.Inherit) {
+					thinkingLevel = resolveThinkingLevelForModel(model, restoredThinkingLevel);
+				} else {
+					thinkingLevel = restoredAfterExtensions.explicitThinkingLevel
+						? restoredAfterExtensions.thinkingLevel
+						: undefined;
+					if (thinkingLevel === undefined && !hasExplicitModel && defaultRoleSpec.explicitThinkingLevel)
+						thinkingLevel = defaultRoleSpec.thinkingLevel;
+					if (thinkingLevel === undefined && hasExplicitDefaultThinkingLevel)
+						thinkingLevel = settings.get("defaultThinkingLevel");
+					if (thinkingLevel === undefined && model.thinking?.defaultLevel !== undefined)
+						thinkingLevel = model.thinking.defaultLevel;
+					if (thinkingLevel === undefined) thinkingLevel = settings.get("defaultThinkingLevel");
+					thinkingLevel = resolveThinkingLevelForModel(model, thinkingLevel);
+				}
+				recoveredSessionDefault = undefined;
+				startupActiveModelProfile =
+					acceptedInheritedProfileName ??
+					(!hasExplicitModel && acceptedPersistedProfileName ? acceptedPersistedProfileName : undefined);
+				modelFallbackMessage = undefined;
+			} else if (deferredMissingSessionRecovery) {
+				const hadProvisionalRecovery = recoveredSessionDefault !== undefined;
+				let lateRecoveryAccepted = false;
+				try {
+					const recovery = await resolveMissingSessionModelRecovery({
+						modelRegistry,
+						settings,
+						defaultEntries: defaultModelEntries,
+						skips: restoredAfterExtensions.skips,
+						savedDefault: existingSession.models.default,
+						credentialSessionId,
+						...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
+					});
+					if (
+						recovery?.model &&
+						(!preferredCredentialProvider || recovery.model.provider === preferredCredentialProvider)
+					) {
+						model = recovery.model;
+						if (options.thinkingLevel !== undefined) {
+							thinkingLevel = resolveThinkingLevelForModel(model, options.thinkingLevel);
+						} else if (restoredThinkingLevel !== undefined && restoredThinkingLevel !== ThinkingLevel.Inherit) {
+							thinkingLevel = resolveThinkingLevelForModel(model, restoredThinkingLevel);
+						} else {
+							const recoveredLevel = recovery.explicitThinkingLevel
+								? recovery.thinkingLevel
+								: defaultRoleSpec.explicitThinkingLevel
+									? defaultRoleSpec.thinkingLevel
+									: hasExplicitDefaultThinkingLevel
+										? settings.get("defaultThinkingLevel")
+										: (model.thinking?.defaultLevel ?? settings.get("defaultThinkingLevel"));
+							thinkingLevel = resolveThinkingLevelForModel(model, recoveredLevel);
+						}
+						recoveredSessionDefault = recovery;
+						startupActiveModelProfile = undefined;
+						modelFallbackMessage =
+							"Saved session model is no longer registered; restored the durable default preset instead.";
+						lateRecoveryAccepted = true;
+					}
+				} catch (error) {
+					if (!(error instanceof ModelProfileCredentialError)) throw error;
+				}
+				// A completed extension catalog can make the saved selector registered
+				// again without making it callable. Do not retain the provisional durable
+				// fallback in that case: the saved model remains authoritative for the
+				// normal unavailable-model path below.
+				if (!lateRecoveryAccepted && hadProvisionalRecovery) {
+					model = undefined;
+					recoveredSessionDefault = undefined;
+					startupActiveModelProfile = undefined;
+					modelFallbackMessage = `Could not restore model ${defaultModelEntries.join(" -> ")}`;
+				}
+			}
+		}
+
 		let startupCredentialModelRejected = false;
 		if (startupModelReference && (startupCredentialSelector || startupCredentialProviderMismatch)) {
 			const validated =
@@ -4788,6 +4946,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			providerSessionState: options.providerSessionState,
 		});
 		session.setActiveModelProfile(startupActiveModelProfile);
+		if (retainedRecoveryBindingsAfterLateRestore) session.markStartupRecoveryBindingsRequired();
+		if (recoveredSessionDefault)
+			session.installRecoveredDefaultFallbackChain(
+				recoveredSessionDefault.entries,
+				recoveredSessionDefault.profileName,
+				recoveredSessionDefault.activeIndex,
+				recoveredSessionDefault.skips,
+			);
 		session.configWarnings.push(...contextFileWarnings);
 		// Determined once, here, where settings are already available. Keep the
 		// durable warning for interactive and print consumers; ACP delivery is
@@ -5082,7 +5248,18 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						let hasErrors = false;
 						if (exact) {
 							const result = await exact.manager.discoverAndConnect({ configPath: exact.configPath });
-							const resultTools = result.tools as CustomTool[];
+							// A slash control may commit while the deferred startup flight is
+							// loading. Re-read the manager's fenced publication rather than
+							// replaying the stale startup snapshot into the session registry. A
+							// deferred manager can still be waiting to publish its first catalog,
+							// though; only that explicit unpublished state may use the discovery
+							// result. Empty published/fenced catalogs are authoritative and must
+							// not replay stale tools across an exact control.
+							const catalog = exact.manager.getToolCatalogSnapshot();
+							const resultTools =
+								catalog.publication === "unpublished"
+									? (result.tools as CustomTool[])
+									: (catalog.tools as CustomTool[]);
 							const toolNames = resultTools.map(tool => tool.name);
 							const collidingToolNames = findDeferredExactMcpToolNameCollisions(
 								toolNames,
@@ -5196,15 +5373,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			} else {
 				if (hasRegistered) agentRegistry.unregister(resolvedAgentId);
 				// Admission happens before session construction. Any later startup
-				// failure must remove THIS manager's endpoint mapping and restore
-				// the prior global only when this manager is still global: otherwise
-				// a retry under the same endpoint is falsely rejected and an orphan
-				// redirects global-manager consumers away from the live session
-				// (review thread P1).
-				if (asyncJobManagerAdmitted && asyncJobManager) {
-					AsyncJobManager.unregisterManager(asyncJobManager);
-					if (AsyncJobManager.instance() === asyncJobManager) {
-						AsyncJobManager.setInstance(priorAsyncJobManager);
+				// failure must eventually release THIS manager's endpoint mapping
+				// through disposal and restore the prior global only when this manager
+				// is still global: otherwise a retry under the same endpoint is falsely
+				// rejected and an orphan redirects global-manager consumers away from
+				// the live session (review thread P1).
+				if (asyncJobManagerOwned && asyncJobManager) {
+					if (asyncJobManagerAdmitted) {
+						if (AsyncJobManager.instance() === asyncJobManager) {
+							AsyncJobManager.setInstance(priorAsyncJobManager);
+						}
 					}
 					await asyncJobManager.dispose({ timeoutMs: 100 });
 				}

package/src/sdk/startup-capability.ts

@@ -161,7 +161,7 @@ export function normalizeSdkStartupFailure(
 }
 
 /** Collect process-scoped credentials without exposing a raw-secret API. */
-function lifecycleKnownSecrets(): string[] {
+export function lifecycleKnownSecrets(): string[] {
 	return Object.entries(process.env)
 		.filter(([name, value]) => value && /(?:token|secret|password|credential|api[_-]?key|auth)/iu.test(name))
 		.map(([, value]) => value!);

package/src/sdk/transport/relay.ts

@@ -3,6 +3,7 @@ import type { Readable, Writable } from "node:stream";
 export const REQUEST_FRAME_BYTES = 256 * 1024;
 export const DEFAULT_PENDING_CEILING_BYTES = 8 * 1024 * 1024;
 export const MIN_PENDING_CEILING_BYTES = REQUEST_FRAME_BYTES;
+export const DEFAULT_UPSTREAM_HELLO_TIMEOUT_MS = 10_000;
 
 export type RelayDirection = "downstream->ws" | "ws->downstream";
 export type TransportError = {
@@ -34,6 +35,19 @@ export type RelayWebSocket = {
 	removeEventListener(type: string, listener: (event: RelayWebSocketEvent) => void): void;
 };
 
+/** The upstream host's hello marks the point at which downstream frames may be sent. */
+function isServerHello(text: string): boolean {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return false;
+	}
+	return Boolean(
+		parsed && typeof parsed === "object" && !Array.isArray(parsed) && (parsed as { type?: unknown }).type === "hello",
+	);
+}
+
 export type RelayOptions = {
 	url: string;
 	token: string;
@@ -112,6 +126,14 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 	let pendingToDownstream = 0;
 	let writingWs = false;
 	let writingDownstream = false;
+	// Capability authority belongs to the downstream client. Buffer its hello and
+	// requests until the upstream's (possibly minimal) hello has arrived, then
+	// forward the exact bytes unchanged in order.
+	let upstreamHelloReceived = false;
+	let preHelloToWs: Buffer[] = [];
+	let preHelloToWsBytes = 0;
+	let upstreamHelloTimer: ReturnType<typeof setTimeout> | undefined;
+	let openingSettled = false;
 
 	const settle = (error?: Error): void => {
 		if (completed) return;
@@ -121,6 +143,8 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 	};
 	void finished.promise.catch(() => undefined);
 	const detach = (): void => {
+		if (upstreamHelloTimer !== undefined) clearTimeout(upstreamHelloTimer);
+		upstreamHelloTimer = undefined;
 		options.downstream.removeListener("data", onData);
 		options.downstream.removeListener("end", onEnd);
 		options.downstream.removeListener("error", onDownstreamError);
@@ -213,7 +237,14 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 			downstreamBytes = 0;
 			if (options.validateDownstreamFrame && !options.validateDownstreamFrame(line.toString("utf8")))
 				return fail({ type: "transport_error", code: "protocol_error", direction: "downstream->ws" });
-			enqueue(toWs, "downstream->ws", line);
+			if (!upstreamHelloReceived) {
+				if (preHelloToWsBytes + line.length > options.pendingCeilingBytes) {
+					fail({ type: "transport_error", code: "pending_overflow", direction: "downstream->ws" });
+					return;
+				}
+				preHelloToWs.push(line);
+				preHelloToWsBytes += line.length;
+			} else enqueue(toWs, "downstream->ws", line);
 			if (closed) return;
 			start = newline + 1;
 			newline = chunk.indexOf(0x0a, start);
@@ -233,20 +264,54 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 			fail({ type: "transport_error", code: "protocol_error", direction: "ws->downstream" });
 			return;
 		}
+		if (!upstreamHelloReceived && isServerHello(event.data)) {
+			upstreamHelloReceived = true;
+			if (upstreamHelloTimer !== undefined) clearTimeout(upstreamHelloTimer);
+			upstreamHelloTimer = undefined;
+			const queued = preHelloToWs;
+			preHelloToWs = [];
+			preHelloToWsBytes = 0;
+			for (const frame of queued) enqueue(toWs, "downstream->ws", frame);
+		}
 		enqueue(toDownstream, "ws->downstream", Buffer.concat([Buffer.from(event.data, "utf8"), Buffer.from("\n")]));
 	};
-	const onClose = (): void => void close();
-	const onWebSocketError = (): void => void close(new Error("upstream_error"));
+	const onClose = (): void => {
+		if (!openingSettled) {
+			openingSettled = true;
+			opened.reject(new Error("upstream_closed"));
+		}
+		void close();
+	};
+	const onWebSocketError = (): void => {
+		if (!openingSettled) {
+			openingSettled = true;
+			opened.reject(new Error("upstream_error"));
+		}
+		void close(new Error("upstream_error"));
+	};
 	const onOpen = (): void => {
+		if (openingSettled) return;
+		openingSettled = true;
 		cleanupOpening();
+		if (!upstreamHelloReceived) {
+			upstreamHelloTimer = setTimeout(() => {
+				if (!upstreamHelloReceived && !closed)
+					fail({ type: "transport_error", code: "protocol_error", direction: "ws->downstream" });
+			}, DEFAULT_UPSTREAM_HELLO_TIMEOUT_MS);
+			upstreamHelloTimer.unref?.();
+		}
 		opened.resolve();
 	};
 	const onOpenError = (): void => {
+		if (openingSettled) return;
+		openingSettled = true;
 		cleanupOpening();
 		opened.reject(new Error("upstream_error"));
 	};
 	const onAbort = (): void => {
 		const error = new RelayOpenAbortedError();
+		if (openingSettled) return;
+		openingSettled = true;
 		cleanupOpening();
 		opened.reject(error);
 		void close(error);
@@ -258,6 +323,9 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 	};
 	ws.addEventListener("open", onOpen, { once: true });
 	ws.addEventListener("error", onOpenError, { once: true });
+	ws.addEventListener("message", onMessage);
+	ws.addEventListener("close", onClose);
+	ws.addEventListener("error", onWebSocketError);
 	options.signal?.addEventListener("abort", onAbort, { once: true });
 	try {
 		await opened.promise;
@@ -265,9 +333,6 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 		await close(error instanceof Error ? error : new Error(String(error)));
 		throw error;
 	}
-	ws.addEventListener("message", onMessage);
-	ws.addEventListener("close", onClose);
-	ws.addEventListener("error", onWebSocketError);
 	options.downstream.on("data", onData);
 	options.downstream.once("end", onEnd);
 	options.downstream.once("error", onDownstreamError);