@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/sdk/mcp/server.ts

@@ -3,12 +3,7 @@ import { getAgentDir } from "@gajae-code/utils";
 import { ensureBroker } from "../broker/ensure";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
 import { SdkClient, SdkClientError } from "../client/client";
-import {
-	listSdkSessionEndpoints,
-	readSdkBrokerDiscovery,
-	readSdkSessionEndpoint,
-	SdkDiscoveryError,
-} from "../client/discovery";
+import { readSdkBrokerDiscovery, SdkDiscoveryError } from "../client/discovery";
 import { validateAdapterControl, validateAdapterSecretFields } from "../protocol/adapter-validation";
 import { adapterDispositionError, findOperation } from "../protocol/operation-registry";
 
@@ -30,6 +25,7 @@ export interface SdkMcpServerOptions {
 	agentDir?: string;
 	connect?: (url: string, token: string) => Promise<SdkClient>;
 }
+const MAX_SESSION_LIST_PAGES = 10_000;
 
 export const SDK_MCP_TOOL_NAMES = [
 	"gjc_session_control",
@@ -169,34 +165,111 @@ function textResult(
 	return { content: [{ type: "text", text: JSON.stringify(payload) }], isError };
 }
 
-/** Creates the model-facing MCP adapter using only SDK discovery records and v3 WebSockets. */
+/** Creates the model-facing MCP adapter; session targeting is broker-bound (C10). */
 export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
-	const repo = options.repo ?? process.cwd();
 	const agentDir = options.agentDir ?? getAgentDir();
 	const connect = options.connect ?? ((url, token) => SdkClient.connect(url, token));
 
+	/**
+	 * Connects to the agent broker, starting one when absent (mirrors the
+	 * lifecycle bootstrap path). The broker is the sole session authority; the
+	 * MCP server never reads endpoint discovery files itself.
+	 */
+	async function brokerClient(): Promise<SdkClient> {
+		await ensureBroker({ agentDir });
+		const broker = await readSdkBrokerDiscovery(agentDir);
+		if (!broker) throw new SdkClientError("not_found", "SDK broker not found");
+		return await connect(broker.url, broker.token);
+	}
+
+	/** Extracts a broker `result` envelope, converting an explicit error frame into a typed throw. */
+	function brokerResult(value: unknown): Record<string, unknown> {
+		if (isObject(value) && value.ok === false) {
+			const error = isObject(value.error) ? value.error : {};
+			const code = typeof error.code === "string" ? error.code : "unavailable";
+			const message = typeof error.message === "string" ? error.message : "SDK broker request failed";
+			throw new SdkClientError(code, message, value.error);
+		}
+		return isObject(value) && isObject(value.result) ? value.result : {};
+	}
+
+	function arrayOf(value: unknown): unknown[] {
+		return Array.isArray(value) ? value : [];
+	}
+	/**
+	 * Exhausts broker `session.list` cursor pagination (default page limit 100)
+	 * to one full snapshot. The broker remains the sole session authority; this
+	 * only aggregates its indexed truth across pages.
+	 */
+	async function paginatedBrokerSessionList(
+		client: SdkClient,
+	): Promise<{ sessions: Record<string, unknown>[]; warnings: unknown[] }> {
+		const sessions: Record<string, unknown>[] = [];
+		let warnings: unknown[] = [];
+		let cursor: string | undefined;
+		for (let pageCount = 0; pageCount < MAX_SESSION_LIST_PAGES; pageCount++) {
+			const listed = brokerResult(await client.global("session.list", cursor === undefined ? {} : { cursor }));
+			sessions.push(...arrayOf(listed.sessions).filter(isObject));
+			if (Array.isArray(listed.warnings)) warnings = listed.warnings;
+			const nextCursor =
+				typeof listed.continuationCursor === "string" && listed.continuationCursor.length > 0
+					? listed.continuationCursor
+					: undefined;
+			if (!nextCursor) return { sessions, warnings };
+			cursor = nextCursor;
+		}
+		throw new SdkClientError("protocol_error", "session.list exceeded the page budget.");
+	}
+
+	/**
+	 * Resolves one session through broker `session.list` + `session.get_endpoint`
+	 * (C10): the broker's liveness and ambiguity truth decides reachability, and
+	 * only the broker mints the endpoint credential.
+	 */
 	async function withSession(sessionId: string, action: (client: SdkClient) => Promise<unknown>): Promise<unknown> {
+		let broker: SdkClient | undefined;
 		let client: SdkClient | undefined;
 		try {
-			const endpoint = await readSdkSessionEndpoint(repo, sessionId);
-			if (!endpoint)
-				return { ok: false, error: { code: "not_found", message: `SDK session not found: ${sessionId}` } };
-			client = await connect(endpoint.url, endpoint.token);
+			broker = await brokerClient();
+			const { sessions } = await paginatedBrokerSessionList(broker);
+			const row = sessions.find(item => item.sessionId === sessionId) as Record<string, unknown> | undefined;
+			if (!row) return { ok: false, error: { code: "not_found", message: `SDK session not found: ${sessionId}` } };
+			if (row.ambiguous === true)
+				return {
+					ok: false,
+					error: { code: "ambiguous_session", message: "session id maps to more than one state root" },
+				};
+			if (row.live !== true)
+				return { ok: false, error: { code: "endpoint_stale", message: "session endpoint is not live" } };
+			const endpoint = brokerResult(await broker.global("session.get_endpoint", { sessionId }));
+			const url = typeof endpoint.url === "string" && endpoint.url ? endpoint.url : undefined;
+			const token = typeof endpoint.token === "string" ? endpoint.token : "";
+			if (!url)
+				return { ok: false, error: { code: "unavailable", message: "SDK broker returned an invalid endpoint" } };
+			client = await connect(url, token);
 			return await action(client);
 		} catch (error) {
 			return resultError(error);
 		} finally {
 			await client?.close();
+			await broker?.close();
 		}
 	}
 
 	async function callTool(name: string, args: Arguments = {}): Promise<unknown> {
 		if (name === "gjc_session_list") {
+			let broker: SdkClient | undefined;
 			try {
-				const { endpoints, warnings } = await listSdkSessionEndpoints(repo);
-				return { ok: true, sessions: endpoints.map(({ sessionId }) => ({ sessionId })), warnings };
+				broker = await brokerClient();
+				const { sessions, warnings } = await paginatedBrokerSessionList(broker);
+				const listed = sessions.flatMap(item =>
+					typeof item.sessionId === "string" && item.sessionId ? [{ sessionId: item.sessionId }] : [],
+				);
+				return { ok: true, sessions: listed, warnings };
 			} catch (error) {
 				return resultError(error);
+			} finally {
+				await broker?.close();
 			}
 		}
 		if (name === "gjc_session_control") {
@@ -301,7 +374,7 @@ export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
 /**
  * Runs the SDK MCP server over stdio (newline-delimited JSON-RPC), the shipped
  * `gjc mcp-serve sdk` entrypoint. Pure SDK client: session control/query flows
- * through discovery records and v3 WebSockets only.
+ * through the broker and v3 WebSockets only.
  */
 export async function runSdkMcpStdio(options: SdkMcpServerOptions = {}): Promise<void> {
 	const server = createSdkMcpServer(options);

package/src/sdk/prompt-status.ts

@@ -24,6 +24,12 @@
  * - Q26 tracks prompts accepted through the SDK control surface (which always
  *   carries a requesting connection); submissions without a delivery owner are
  *   outside the reconciliation contract and hold no reservation.
+ * - A terminal outcome settles once: the first terminal transition wins. A late
+ *   `agent_failed` (arriving on a different delivery path than the one that
+ *   claimed the terminal) may still attach its bounded, sanitized reason to an
+ *   already-terminal record that has none, surfaced as `error` on `terminal_ok`.
+ *   It never changes status, `terminalAt`, retention order, or the clientRef
+ *   index, and the first recorded reason always wins over a later frame.
  */
 
 export const PROMPT_CLIENT_REF_MAX_LENGTH = 128;
@@ -79,6 +85,8 @@ export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconcilia
 	/** Epoch milliseconds of the terminal transition. */
 	terminalAt: number;
 	outcome?: SdkPromptTerminalOutcome;
+	/** Present when a late `agent_failed` supplied the only failure reason. */
+	error?: { code: string; message: string };
 }
 
 export interface TurnPromptReconciliationFailed extends TurnPromptReconciliationIdentity {

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

@@ -1601,6 +1601,24 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "registry:Q30",
+		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
+		"sourceKind": "registry",
+		"decision": "include",
+		"sdkId": "session.checkpoint",
+		"adapterMappings": {
+			"telegram": "prohibited",
+			"discord": "prohibited",
+			"slack": "prohibited",
+			"mcp": "generic_safe",
+			"acp": "generic_safe",
+			"daemonCli": "generic_safe"
+		},
+		"testIds": [
+			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
+		]
+	},
 	{
 		"sourceId": "registry:R01",
 		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
@@ -3947,6 +3965,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:getConfiguredModelChainState",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal model-profile transaction snapshot, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:setConfiguredModelChain",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -3980,6 +4009,28 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:getDefaultFallbackRuntimeState",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal model-profile transaction snapshot, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
+	{
+		"sourceId": "agent_session:restoreDefaultFallbackRuntimeState",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal rollback compensation, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:getSessionDefaultModelSelector",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -4024,6 +4075,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:restoreModelSelectionForRollback",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal rollback compensation, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:setModelTemporaryForControl",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/protocol/operation-registry.ts

@@ -165,6 +165,7 @@ const queries = [
 		"Read the authoritative reconciliation status of a skill.invoke by command/turn IDs or clientRef.",
 	],
 	["providers.list/active", "List active providers."],
+	["session.checkpoint", "Resolve a durable transcript checkpoint into a connection-owned replay cursor."],
 ] as const;
 
 const reverse = [
@@ -237,14 +238,14 @@ function revision(id: string): string | undefined {
 }
 function queryContinuityClass(id: string): QueryContinuityClass {
 	if (["Q01", "Q02"].includes(id)) return "stable_prefix";
-	if (["Q04", "Q05", "Q06", "Q07", "Q08", "Q11", "Q12", "Q13", "Q20", "Q21", "Q22", "Q23", "Q27"].includes(id))
+	if (["Q04", "Q05", "Q06", "Q07", "Q08", "Q11", "Q12", "Q13", "Q20", "Q21", "Q22", "Q23", "Q27", "Q30"].includes(id))
 		return "retained_revision";
 	if (id === "Q24") return "content_addressed";
 	return "scalar_snapshot";
 }
 
 function queryDisposition(id: string): Record<Adapter, AdapterDisposition> {
-	if (["Q23", "Q24", "Q25", "Q26", "Q27", "Q28", "Q29"].includes(id))
+	if (["Q23", "Q24", "Q25", "Q26", "Q27", "Q28", "Q29", "Q30"].includes(id))
 		return dispositions({ telegram: "prohibited", discord: "prohibited", slack: "prohibited" });
 	return dispositions();
 }

package/src/sdk/session.ts

@@ -41,6 +41,8 @@ import {
 import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElapsedMs } from "../async";
 import { loadCapability } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
+import { resolveModelProfileName } from "../config/model-profile-contract";
+import { resolveProfileBindings } from "../config/model-profiles";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
 import {
 	formatModelString,
@@ -115,6 +117,7 @@ import {
 import { NotificationSessionController } from "../sdk/bus/session-control";
 import { shouldHostSdk } from "../sdk/host";
 import { createSdkSessionRuntimeExtension, registerSdkOnlyNotificationCommand } from "../sdk/host/session-runtime";
+import { createSdkWebSocketTransport } from "../sdk/host/websocket-transport";
 import type { SecretObfuscator } from "../secrets";
 import { AgentSession, type ForkContextSeed } from "../session/agent-session";
 import { resolveAuthBrokerConfig } from "../session/auth-broker-config";
@@ -325,6 +328,8 @@ export interface CreateAgentSessionOptions {
 	/** Raw model pattern string (e.g. from --model CLI flag) to resolve after extensions load.
 	 * Used when model lookup is deferred because extension-provided models aren't registered yet. */
 	modelPattern?: string;
+	/** Active profile inherited by a nested SDK/subagent session. */
+	activeModelProfile?: string;
 	/** Thinking selector. Default: from settings, else unset */
 	thinkingLevel?: ThinkingLevel;
 	/** Runtime substitution metadata for the initial model_change session event. */
@@ -337,6 +342,8 @@ export interface CreateAgentSessionOptions {
 	/** Optional provider-facing session identifier for prompt caches and sticky auth selection.
 	 * Keeps persisted session files isolated while reusing provider-side caches. */
 	providerSessionId?: string;
+	/** Optional credential-selection session identity, distinct from provider transport/cache identity. */
+	credentialSessionId?: string;
 	/** Runtime credential selector for multi-account auth pools. */
 	credentialSelector?: { provider?: string; selector: AuthCredentialSelector; raw: string };
 
@@ -1287,31 +1294,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 		applyConfiguredSearchTimeout(settings);
 
-		const imageProvider = settings.get("providers.image");
-		const imageModel = settings.get("providers.imageModel");
-		const imageCustomUrl = settings.get("providers.imageCustomUrl");
-		const imageCustomKey = settings.get("providers.imageCustomKey");
-		const imageCustomKeyEnv = settings.get("providers.imageCustomKeyEnv");
-		if (
-			imageProvider === "auto" ||
-			imageProvider === "openai" ||
-			imageProvider === "gemini" ||
-			imageProvider === "openrouter" ||
-			imageProvider === "antigravity" ||
-			imageProvider === "alibaba" ||
-			imageProvider === "custom"
-		) {
-			const { setConfiguredImageModel, setPreferredImageProvider } = await import("../tools/image-gen");
-			setPreferredImageProvider(imageProvider === "custom" ? "auto" : imageProvider);
-			setConfiguredImageModel({
-				provider: imageProvider,
-				model: imageModel ?? null,
-				customUrl: imageCustomUrl,
-				customKey: imageCustomKey,
-				customKeyEnv: imageCustomKeyEnv,
-			});
-		}
-
 		const sessionManager =
 			options.sessionManager ??
 			(await logger.time("sessionManager", async () => {
@@ -1323,6 +1305,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// session_id upstream, where session-owning transports reject the extra
 		// downstreams (owner_busy) and degrade those turns to uncached HTTP.
 		const providerSessionId = options.providerSessionId ?? logicalSessionId;
+		const credentialSessionId = options.credentialSessionId ?? providerSessionId;
 		const modelApiKeyAvailability = new Map<string, boolean>();
 		const getModelAvailabilityKey = (candidate: Model): string =>
 			`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
@@ -1345,7 +1328,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return false;
 			}
 			const key = await modelRegistry
-				.getApiKey(candidate, providerSessionId, { credentialSelector })
+				.getApiKey(candidate, credentialSessionId, { credentialSelector })
 				.catch(error => {
 					if (credentialSelector) {
 						logger.debug("Credential selector did not match model availability candidate", {
@@ -1395,6 +1378,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const modelMatchPreferences = {
 			usageOrder: settings.getStorage()?.getModelUsageOrder(),
 		};
+		const persistedProfiles = modelRegistry.getModelProfiles();
+		const resolvedInheritedProfileName = options.activeModelProfile
+			? resolveModelProfileName(options.activeModelProfile, persistedProfiles)
+			: undefined;
+		const acceptedInheritedProfileName =
+			resolvedInheritedProfileName && persistedProfiles.has(resolvedInheritedProfileName)
+				? resolvedInheritedProfileName
+				: undefined;
+		const inheritedProfileOwnsDefault = acceptedInheritedProfileName
+			? resolveProfileBindings(persistedProfiles.get(acceptedInheritedProfileName)!).defaultSelector !== undefined
+			: false;
+		const settingsProfileAliasIntent: { aliasIntent: "preset-equivalent" } | undefined = inheritedProfileOwnsDefault
+			? { aliasIntent: "preset-equivalent" }
+			: undefined;
 		const allowedModels = await logger.time("resolveAllowedModels", () =>
 			resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
 		);
@@ -1403,20 +1400,41 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				settings,
 				matchPreferences: modelMatchPreferences,
 				modelRegistry,
+				...(settingsProfileAliasIntent ?? {}),
+				sessionId: providerSessionId,
+				credentialSessionId,
 			}),
 		);
 		let model = options.model;
 		let modelFallbackMessage: string | undefined;
 		const resumeModelBehavior = settings.get("session.resumeModelBehavior");
-		const persistedDefaultChain = existingSession.configuredModelChains.default?.entries;
+		const persistedDefaultChain = existingSession.configuredModelChains.default;
 		const defaultModelEntries =
 			resumeModelBehavior === "useCurrentDefault"
 				? []
-				: persistedDefaultChain && persistedDefaultChain.length > 0
-					? persistedDefaultChain
+				: persistedDefaultChain?.entries && persistedDefaultChain.entries.length > 0
+					? persistedDefaultChain.entries
 					: existingSession.models.default
 						? [existingSession.models.default]
 						: [];
+		const persistedProfileName =
+			persistedDefaultChain?.origin === "profile-activation" ? persistedDefaultChain.identity : undefined;
+		const resolvedPersistedProfileName = persistedProfileName
+			? resolveModelProfileName(persistedProfileName, persistedProfiles)
+			: undefined;
+		const acceptedPersistedProfileName =
+			resolvedPersistedProfileName &&
+			persistedProfiles.has(resolvedPersistedProfileName) &&
+			(!acceptedInheritedProfileName || acceptedInheritedProfileName === resolvedPersistedProfileName) &&
+			resumeModelBehavior !== "useCurrentDefault"
+				? resolvedPersistedProfileName
+				: undefined;
+		const persistedProfileOwnsDefault = acceptedPersistedProfileName
+			? resolveProfileBindings(persistedProfiles.get(acceptedPersistedProfileName)!).defaultSelector !== undefined
+			: false;
+		const startupActiveModelProfile =
+			acceptedInheritedProfileName ??
+			(!hasExplicitModel && acceptedPersistedProfileName ? acceptedPersistedProfileName : 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) {
@@ -1425,8 +1443,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					defaultModelEntries,
 					modelRegistry,
 					settings,
-					providerSessionId,
-					{ managedFallback: defaultModelEntries.length > 1 },
+					credentialSessionId,
+					{
+						managedFallback: defaultModelEntries.length > 1,
+						canonicalSessionId: providerSessionId,
+						...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
+					},
 				);
 				model = restoredDefaultResolution.model;
 				if (!model) modelFallbackMessage = `Could not restore model ${defaultModelEntries.join(" -> ")}`;
@@ -1671,6 +1693,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			trackEvalExecution: (execution, abortController) =>
 				session ? session.trackEvalExecution(execution, abortController) : execution,
 			getSessionId: () => sessionManager.getSessionId?.() ?? null,
+			getCredentialSessionId: () => session?.credentialSessionId ?? credentialSessionId,
 			getMcpManager: () => mcpManager ?? options.inheritedMcpManager,
 			isManagedSessionDestination: () => sessionManager.isManagedDestination(),
 			getActiveSkillState: () => session?.getActiveSkillState(),
@@ -1771,6 +1794,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			isManagedDestination: () => sessionManager.isManagedDestination(),
 			getManagedLegacyLocalMigrationSource: () => sessionManager.getManagedLegacyLocalMigrationSource(),
 			getSessionId: () => sessionManager.getSessionId(),
+			getCredentialSessionId: () => credentialSessionId,
 		};
 		if (!options.parentTaskPrefix) {
 			setActiveSkills(skills);
@@ -1782,6 +1806,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			disposeLocalProtocolOverride = LocalProtocolHandler.installOverride(options.localProtocolOptions);
 		}
 		toolSession.getArtifactsDir = getArtifactsDir;
+		// Live parent profile accessor for task/subagent dispatch: profile-owned
+		// persisted model overrides may resolve through preset-equivalent aliases
+		// only while an active profile claims them (see task/executor.ts).
+		(toolSession as ToolSession & { getActiveModelProfile?: () => string | undefined }).getActiveModelProfile = () =>
+			session?.getActiveModelProfile();
 		toolSession.getAuthorizedArtifactsDirs = () => {
 			const manager = sessionManager.getArtifactManager();
 			return manager ? [manager.dir] : [];
@@ -1806,9 +1835,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const pluginMcpToolNames: string[] = [];
 		let deferredExactMcpConfig: { manager: MCPManager; configPath: string } | undefined;
 
-		// Add image tools when the active model or configured image providers can generate images.
+		// Add image tools when an image role model is configured.
 		const { getImageGenTools } = await import("../tools/image-gen");
-		const imageGenTools = await logger.time("getImageGenTools", () => getImageGenTools(modelRegistry, model));
+		const imageGenTools = await logger.time("getImageGenTools", () => getImageGenTools(modelRegistry, settings));
 		if (imageGenTools.length > 0) {
 			customTools.push(...(imageGenTools as unknown as CustomTool[]));
 		}
@@ -2121,8 +2150,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						});
 					} else if (sdkHostEligible) {
 						registerSdkOnlyNotificationCommand(api);
-						const { createSdkWebSocketTransport } = await import("../sdk/host/websocket-transport");
 						createSdkSessionRuntimeExtension(api, {
+							agentDir,
+							brokerRegistrationRequired: lifecycleStartupCapability !== undefined,
 							createTransport: input => createSdkWebSocketTransport(input),
 							settings,
 							configOverrides: new Map(),
@@ -2196,6 +2226,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			};
 			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences, {
 				modelRegistry,
+				sessionId: logicalSessionId,
+				credentialSessionId,
 			});
 			if (resolved) {
 				model = resolved;
@@ -2283,6 +2315,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const getSessionContext = () => ({
 			sessionManager: createReadonlySessionManager(sessionManager),
 			modelRegistry,
+			get credentialSessionId() {
+				return session.credentialSessionId;
+			},
 			model: agent.state.model,
 			isIdle: () => !session.isStreaming,
 			hasQueuedMessages: () => session.queuedMessageCount > 0,
@@ -2312,6 +2347,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const customToolContext = (): CustomToolContext => ({
 				sessionManager: createReadonlySessionManager(sessionManager),
 				modelRegistry,
+				get credentialSessionId() {
+					return session?.credentialSessionId ?? credentialSessionId;
+				},
 				model: agent?.state.model,
 				isIdle: () => !session?.isStreaming,
 				hasQueuedMessages: () => (session?.queuedMessageCount ?? 0) > 0,
@@ -2843,14 +2881,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getApiKey: async provider => {
 				// Read agent.sessionId at call time so credential selection stays aligned
 				// with metadataResolver after /new, fork, resume, or branch switches.
-				const key = await modelRegistry.getApiKeyForProvider(provider, agent.providerSessionId ?? agent.sessionId);
+				const key = await modelRegistry.getApiKeyForProvider(
+					provider,
+					options.credentialSessionId ?? agent.providerSessionId ?? agent.sessionId,
+				);
 				if (!key) {
 					throw new Error(`No API key found for provider "${provider}"`);
 				}
 				return key;
 			},
 			getAuthCredentialType: provider =>
-				modelRegistry.getSessionCredentialType(provider, agent.providerSessionId ?? agent.sessionId),
+				modelRegistry.getSessionCredentialType(
+					provider,
+					options.credentialSessionId ?? agent.providerSessionId ?? agent.sessionId,
+				),
 			streamFn: async (streamModel, context, streamOptions) => {
 				const requestStartedAt = performance.now();
 				let stream: Awaited<ReturnType<typeof streamSimple>>;
@@ -2858,15 +2902,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					stream = await streamSimple(streamModel, context, {
 						...streamOptions,
 						onAuthError: async (provider, oldKey, error) => {
+							const credentialSessionId =
+								options.credentialSessionId ?? agent.providerSessionId ?? agent.sessionId;
 							await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, {
 								signal: streamOptions?.signal,
-								sessionId: agent.sessionId,
+								sessionId: credentialSessionId,
 							});
 							logger.debug("Retrying provider request after credential invalidation", {
 								provider,
 								error: error instanceof Error ? error.message : String(error),
 							});
-							return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
+							return modelRegistry.getApiKeyForProvider(provider, credentialSessionId);
 						},
 					});
 				} catch (error) {
@@ -3028,10 +3074,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			agentId: resolvedAgentId,
 			agentRegistry,
 			providerSessionId: options.providerSessionId,
+			credentialSessionId: options.credentialSessionId,
 			providerCacheSessionId: providerSessionId,
 			forkContextSeed: options.forkContextSeed,
 			providerSessionState: options.providerSessionState,
 		});
+		session.setActiveModelProfile(startupActiveModelProfile);
 		session.configWarnings.push(...contextFileWarnings);
 		hasSession = true;
 		if (asyncJobManager) {
@@ -3081,7 +3129,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (codexTransport.websocketPreferred) {
 				void (async () => {
 					try {
-						const codexPrewarmApiKey = await modelRegistry.getApiKey(codexModel, providerSessionId);
+						const codexPrewarmApiKey = await modelRegistry.getApiKey(codexModel, credentialSessionId);
 						if (!codexPrewarmApiKey) return;
 						await logger.time("prewarmOpenAICodexResponses", prewarmOpenAICodexResponses, codexModel, {
 							apiKey: codexPrewarmApiKey,

package/src/sdk/transport/index.ts

@@ -10,6 +10,7 @@ export type ServeOptions = {
 	url: string;
 	token: string;
 	pendingCeilingBytes: number;
+	validateDownstreamFrame?: (frame: string) => boolean;
 };
 
 export type ServeHandle = {

package/src/sdk/transport/relay.ts

@@ -44,6 +44,7 @@ export type RelayOptions = {
 	onTransportError: (error: TransportError) => void;
 	webSocketFactory?: (url: string) => RelayWebSocket;
 	signal?: AbortSignal;
+	validateDownstreamFrame?: (frame: string) => boolean;
 };
 
 type QueuedFrame = { bytes: Buffer; accounted: boolean };
@@ -193,6 +194,8 @@ export async function startRelayPair(options: RelayOptions): Promise<RelayPair>
 				return fail({ type: "transport_error", code: "protocol_error", direction: "downstream->ws" });
 			if (line.length > REQUEST_FRAME_BYTES)
 				return fail({ type: "transport_error", code: "frame_oversize", direction: "downstream->ws" });
+			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 (closed) return;
 			newline = downstreamBuffer.indexOf(0x0a);