@sayknow-cli/coding-agent 0.4.6 → 0.5.0

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

@@ -935,6 +935,24 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "registry:C53",
+		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
+		"sourceKind": "registry",
+		"decision": "include",
+		"sdkId": "model.profile.set",
+		"adapterMappings": {
+			"telegram": "generic_safe",
+			"discord": "generic_safe",
+			"slack": "generic_safe",
+			"mcp": "generic_safe",
+			"acp": "generic_safe",
+			"daemonCli": "generic_safe"
+		},
+		"testIds": [
+			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
+		]
+	},
 	{
 		"sourceId": "registry:G01",
 		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
@@ -1511,6 +1529,60 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "registry:Q26",
+		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
+		"sourceKind": "registry",
+		"decision": "include",
+		"sdkId": "turn.prompt_status",
+		"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:Q27",
+		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
+		"sourceKind": "registry",
+		"decision": "include",
+		"sdkId": "models.profiles.list",
+		"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:Q28",
+		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
+		"sourceKind": "registry",
+		"decision": "include",
+		"sdkId": "skill.invoke_status",
+		"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",
@@ -2294,6 +2366,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:getDeepInterviewAskStage",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal AskTool schema-selection accessor, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:peekQueueInvoker",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -2612,6 +2695,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:getToolForExecution",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal accessor/plumbing, not a user-facing control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:registerForegroundBashBackgroundRequestHandler",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -2827,6 +2921,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:restoreFromMemoryGuardCheckpoint",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal owner-recovery staged restore builder after durable claims/fencing, never a user-facing SDK operation",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:promoteRecoveryHydrationAfterOwnershipReadyFence",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -2860,6 +2965,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:buildPreparedDisplaySessionContext",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal accessor/plumbing, not a user-facing control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:convertMessagesToLlm",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -3663,6 +3779,24 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:activateModelProfileForControl",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "include",
+		"sdkId": "model.profile.set",
+		"adapterMappings": {
+			"telegram": "generic_safe",
+			"discord": "generic_safe",
+			"slack": "generic_safe",
+			"mcp": "generic_safe",
+			"acp": "generic_safe",
+			"daemonCli": "generic_safe"
+		},
+		"testIds": [
+			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
+		]
+	},
 	{
 		"sourceId": "agent_session:getConfiguredModelChain",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -4430,6 +4564,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:createBtwConversationScope",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal privacy-scoped side-chat snapshot factory, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:runEphemeralTurn",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

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

@@ -116,6 +116,7 @@ const controls = [
 	["retry.last", "Retry the last interrupted or failed turn."],
 	["retry.now", "Immediately retry pending backoff."],
 	["bash.background", "Move active managed bash to the background."],
+	["model.profile.set", "Activate a model profile for the current session."],
 ] as const;
 
 const globals = [
@@ -154,6 +155,15 @@ const queries = [
 	["resource.body", "Read a bounded resource continuation."],
 	["artifact.read", "Read a bounded artifact range."],
 	["runtime.jobs.list", "List managed jobs."],
+	[
+		"turn.prompt_status",
+		"Read the authoritative reconciliation status of a submitted prompt by command/turn IDs or clientRef.",
+	],
+	["models.profiles.list", "List the effective built-in and configured model profiles for this session."],
+	[
+		"skill.invoke_status",
+		"Read the authoritative reconciliation status of a skill.invoke by command/turn IDs or clientRef.",
+	],
 ] as const;
 
 const reverse = [
@@ -191,6 +201,8 @@ function controlDisposition(id: string): Record<Adapter, AdapterDisposition> {
 
 function controlErrors(id: string): string[] {
 	const errors: Record<string, string[]> = {
+		C01: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
+		C09: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C06: ["action_claimed"],
 		C07: ["action_claimed", "terminal_uncertain"],
 		C08: ["action_claimed", "terminal_uncertain"],
@@ -224,14 +236,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"].includes(id))
+	if (["Q04", "Q05", "Q06", "Q07", "Q08", "Q11", "Q12", "Q13", "Q20", "Q21", "Q22", "Q23", "Q27"].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"].includes(id))
+	if (["Q23", "Q24", "Q25", "Q26", "Q27", "Q28"].includes(id))
 		return dispositions({ telegram: "prohibited", discord: "prohibited", slack: "prohibited" });
 	return dispositions();
 }
@@ -263,7 +275,12 @@ export const OPERATIONS: readonly Operation[] = [
 			kind: "global" as const,
 			description,
 			idempotency: "idempotent" as const,
-			errorCodes: id === "G02" ? ["endpoint_credential_forbidden"] : ["invalid_request"],
+			errorCodes:
+				id === "G02"
+					? ["endpoint_credential_forbidden"]
+					: ["G03", "G04", "G05"].includes(id)
+						? ["invalid_request", "unknown_model_profile", "model_profile_registry_error"]
+						: ["invalid_request"],
 			adapterDispositions:
 				id === "G02"
 					? dispositions({
@@ -286,7 +303,10 @@ export const OPERATIONS: readonly Operation[] = [
 			kind: "query" as const,
 			description,
 			idempotency: "idempotent" as const,
-			errorCodes: ["invalid_request", "resource_gone"],
+			errorCodes:
+				id === "Q27"
+					? ["invalid_request", "resource_gone", "model_profile_registry_error"]
+					: ["invalid_request", "resource_gone"],
 			continuityClass: queryContinuityClass(id),
 			adapterDispositions: queryDisposition(id),
 			testIds: ["packages/coding-agent/test/sdk-operation-inventory.test.ts"],

package/src/sdk/session-directory.ts

@@ -38,7 +38,11 @@ export type ResolveManagedSessionScopeResult =
 				| "network_unsupported"
 				| "sessions_root_unavailable"
 				| "binding_conflict"
-				| "binding_invalid";
+				| "binding_invalid"
+				| "atomic_unavailable"
+				| "durability_not_provable"
+				| "durability_failed"
+				| "invalid_request";
 			message: string;
 	  };
 

package/src/sdk/session.ts

@@ -22,6 +22,7 @@ import {
 	type ToolResultMessage,
 } from "@sayknow-cli/ai";
 import {
+	codexToolWireName,
 	getOpenAICodexTransportDetails,
 	prewarmOpenAICodexResponses,
 } from "@sayknow-cli/ai/providers/openai-codex-responses";
@@ -46,8 +47,8 @@ import { loadCapability } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
 import {
-	formatModelString,
 	defaultModelPerProvider,
+	formatModelString,
 	parseModelPattern,
 	resolveAllowedModels,
 	resolveModelChainWithAuth,
@@ -94,6 +95,7 @@ import type { FileSlashCommand } from "../extensibility/slash-commands";
 import type { HindsightSessionState } from "../hindsight/state";
 import { initializeLocalRoot, LocalProtocolHandler, type LocalProtocolOptions } from "../internal-urls";
 import { resolveMemoryBackend } from "../memory-backend";
+import btwUserPrompt from "../prompts/system/btw-user.md" with { type: "text" };
 import asyncResultTemplate from "../prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
 import { MCPManager } from "../runtime-mcp";
@@ -151,6 +153,7 @@ import {
 	ReadTool,
 	ResolveTool,
 	SearchTool,
+	setConfiguredImageModel,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
@@ -168,6 +171,7 @@ import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-
 import { buildWorkspaceTree, type WorkspaceTree } from "../workspace-tree";
 import {
 	attachLifecycleStartupCapability,
+	lifecycleMcpStartupTimeoutOption,
 	lifecycleStartupCapabilityOption,
 	type SdkStartupCapability,
 } from "./startup-capability";
@@ -428,6 +432,13 @@ export interface CreateAgentSessionOptions {
 	goalToolAllowedOps?: readonly ("create" | "get" | "complete" | "resume" | "drop" | "pause")[];
 	/** Optional per-session allowlist for tools exposed through search_tool_bm25. */
 	discoverableToolAllowedNames?: readonly string[];
+	/**
+	 * Discoverable built-in tools that must stay in the initial active set even when
+	 * `tools.discoveryMode === "all"` would otherwise hide them behind `search_tool_bm25`.
+	 * Used for coordination tools (e.g. `irc`) that a subagent must be able to use
+	 * immediately without first spending a discovery round-trip to find them.
+	 */
+	alwaysActiveToolNames?: readonly string[];
 	/** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
 	agentRegistry?: AgentRegistry;
 	/** Parent task ID prefix for nested artifact naming (e.g., "6-Extensions") */
@@ -1021,6 +1032,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const lifecycleStartupCapability = (
 		options as CreateAgentSessionOptions & { [lifecycleStartupCapabilityOption]?: SdkStartupCapability }
 	)[lifecycleStartupCapabilityOption];
+	// ACP lifecycle launches carry their own MCP startup budget; every other
+	// consumer keeps the manager's short default ceiling.
+	const lifecycleMcpStartupTimeoutMs = (
+		options as CreateAgentSessionOptions & { [lifecycleMcpStartupTimeoutOption]?: number }
+	)[lifecycleMcpStartupTimeoutOption];
 	const isCanonicalSubSession =
 		(options.taskDepth ?? 0) > 0 || Boolean(options.parentTaskPrefix) || Boolean(options.currentAgentType);
 	if (isCanonicalSubSession && options.mcpConfigPath !== undefined) {
@@ -1160,14 +1176,27 @@ 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 === "antigravity" ||
+			imageProvider === "alibaba" ||
+			imageProvider === "custom"
 		) {
-			setPreferredImageProvider(imageProvider);
+			setPreferredImageProvider(imageProvider === "custom" ? "auto" : imageProvider);
+			setConfiguredImageModel({
+				provider: imageProvider,
+				model: imageModel ?? null,
+				customUrl: imageCustomUrl,
+				customKey: imageCustomKey,
+				customKeyEnv: imageCustomKeyEnv,
+			});
 		}
 
 		const sessionManager =
@@ -1511,6 +1540,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			isManagedSessionDestination: () => sessionManager.isManagedDestination(),
 			getActiveSkillState: () => session?.getActiveSkillState(),
 			getActiveSkillPhase: () => session?.getActiveSkillPhase(),
+			getDeepInterviewAskStage: () => session?.getDeepInterviewAskStage(),
 			getHindsightSessionState: () => session?.getHindsightSessionState(),
 			get model() {
 				return agent?.state.model ?? model;
@@ -1528,6 +1558,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			goalToolAllowedOps: options.goalToolAllowedOps,
 			discoverableToolAllowedNames: options.discoverableToolAllowedNames,
 			getToolByName: name => session?.getToolByName(name),
+			getToolForExecution: name => session?.getToolForExecution(name),
 			agentRegistry,
 			getSessionSpawns: () => options.spawns ?? "*",
 			getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
@@ -1592,13 +1623,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// which collapses to the parent's dir for subagents (they adopt the
 		// parent's ArtifactManager) so one lookup hits everything.
 		const getArtifactsDir = () => sessionManager.getArtifactsDir();
+		const localProtocolOptions = options.localProtocolOptions ?? {
+			getArtifactsDir,
+			isManagedDestination: () => sessionManager.isManagedDestination(),
+			getManagedLegacyLocalMigrationSource: () => sessionManager.getManagedLegacyLocalMigrationSource(),
+			getSessionId: () => sessionManager.getSessionId(),
+		};
 		if (!options.parentTaskPrefix) {
 			setActiveSkills(skills);
 			setActiveRules([...rulebookRules, ...alwaysApplyRules]);
 			if (asyncJobManager) AsyncJobManager.setInstance(asyncJobManager);
 		}
+		await initializeLocalRoot(localProtocolOptions);
 		if (options.localProtocolOptions) {
-			await initializeLocalRoot(options.localProtocolOptions);
 			disposeLocalProtocolOverride = LocalProtocolHandler.installOverride(options.localProtocolOptions);
 		}
 		toolSession.getArtifactsDir = getArtifactsDir;
@@ -1692,7 +1729,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		const preExactCustomToolNames = customTools.map(tool => tool.name);
 		if (explicitMcpConfigPath !== undefined) {
-			const owned = new MCPManager(cwd, null, { toolsOnly: true });
+			const owned = new MCPManager(cwd, null, {
+				toolsOnly: true,
+				...(lifecycleMcpStartupTimeoutMs !== undefined
+					? { maxStartupTimeoutMs: lifecycleMcpStartupTimeoutMs }
+					: {}),
+			});
 			owned.setAuthStorage(authStorage);
 			mcpManager = owned;
 			ownsMcpManager = true;
@@ -1851,9 +1893,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						spawnedBySkc,
 						sdkHostModeSupported: options.sdkHostModeSupported,
 						ensureProviderDaemon: options.ensureNotificationProviderDaemon,
-						runEphemeralTurn: async (promptText, signal) => {
+						runBtwTurn: async (question, signal) => {
 							if (!session) throw new Error("Ephemeral turns are unavailable.");
-							const { replyText } = await session.runEphemeralTurn({ promptText, signal });
+							const { replyText } = await session.runEphemeralTurn({
+								purpose: "btw",
+								turn: { question, scope: session.createBtwConversationScope(btwUserPrompt) },
+								signal,
+							});
 							return { replyText };
 						},
 					});
@@ -2166,7 +2212,18 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				const previousPromptMetadataModel = promptMetadataModel;
 				promptMetadataModel = candidateModel;
 				try {
-					return buildSystemPromptToolMetadata(tools);
+					const activeModel = candidateModel ?? agent?.state.model ?? model;
+					// Codex renames reserved tool names on the wire; the prompt must
+					// refer to the tools by the names the model actually receives.
+					const overrides =
+						activeModel?.api === "openai-codex-responses"
+							? Object.fromEntries(
+									Array.from(tools.keys())
+										.filter(name => codexToolWireName(name) !== name)
+										.map(name => [name, { wireName: codexToolWireName(name) }]),
+								)
+							: {};
+					return buildSystemPromptToolMetadata(tools, overrides);
 				} finally {
 					promptMetadataModel = previousPromptMetadataModel;
 				}
@@ -2326,6 +2383,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// from the initial set unless they were explicitly requested or restored from persistence.
 		// The model finds them via search_tool_bm25 and activates them on demand.
 		if (effectiveDiscoveryMode === "all") {
+			const alwaysActiveDiscoveredBuiltinNames = new Set(
+				(options.alwaysActiveToolNames ?? []).map(name => name.toLowerCase()),
+			);
 			const essentialBuiltinNames = new Set(computeEssentialBuiltinNames(settings));
 			const allowedDiscoveredBuiltinNames = options.discoverableToolAllowedNames
 				? new Set(options.discoverableToolAllowedNames.map(name => name.toLowerCase()))
@@ -2334,6 +2394,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				const tool = toolRegistry.get(name);
 				if (!tool?.loadMode) return true; // not a built-in — leave MCP/custom/extension to existing logic
 				if (tool.loadMode === "essential") return true;
+				if (alwaysActiveDiscoveredBuiltinNames.has(name)) return true;
 				return essentialBuiltinNames.has(name);
 			});
 			explicitlyRequestedDiscoveredBuiltinToolNames = selectRestorableDiscoveredBuiltinToolNames(

package/src/sdk/startup-capability.ts

@@ -1,3 +1,8 @@
+import {
+	isModelProfileError,
+	type ModelProfileErrorCode,
+	type ModelProfileErrorDetails,
+} from "../config/model-profile-contract";
 export type SdkStartupPhase = "registration" | "startup";
 
 export type SdkStartupReason = "disabled" | "ineligible" | "factory_absent" | "runner_absent" | "pending" | "failed";
@@ -6,6 +11,8 @@ export interface SdkStartupFailure {
 	phase: SdkStartupPhase;
 	reason: SdkStartupReason;
 	message: string;
+	code?: ModelProfileErrorCode;
+	details?: ModelProfileErrorDetails;
 }
 
 export type SdkStartupResult = { status: "started" } | { status: "failed"; failure: SdkStartupFailure };
@@ -15,6 +22,12 @@ const MAX_MESSAGE_BYTES = 512;
 
 /** Internal symbols for lifecycle-only SDK startup construction and bus wiring. */
 export const lifecycleStartupCapabilityOption: unique symbol = Symbol("lifecycleStartupCapability");
+/**
+ * Internal option carrying the startup budget for ACP lifecycle MCP launches.
+ * Only set when the lifecycle request actually supplies `mcpServers`, so the
+ * longer ceiling never leaks to ordinary CLI/SDK `mcpConfigPath` consumers.
+ */
+export const lifecycleMcpStartupTimeoutOption: unique symbol = Symbol("lifecycleMcpStartupTimeout");
 const lifecycleStartupCapabilityOnApi: unique symbol = Symbol("lifecycleStartupCapabilityOnApi");
 
 export function attachLifecycleStartupCapability(api: object, capability: SdkStartupCapability): void {
@@ -134,7 +147,8 @@ export function normalizeSdkStartupFailure(
 							? "SDK startup did not complete before readiness cutoff."
 							: FALLBACK_MESSAGE;
 	const message = sanitizeSdkStartupMessage(error, knownSecrets);
-	return { phase, reason, message: message === FALLBACK_MESSAGE ? fallback : message };
+	const profileError = isModelProfileError(error) ? { code: error.code, details: error.details } : {};
+	return { phase, reason, message: message === FALLBACK_MESSAGE ? fallback : message, ...profileError };
 }
 
 /** Collect process-scoped credentials without exposing a raw-secret API. */

package/src/sdk/transport/auth-preface.ts

@@ -0,0 +1,82 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import type * as net from "node:net";
+
+const PREFACE_LIMIT_BYTES = 4 * 1024;
+const PREFACE_TIMEOUT_MS = 1_000;
+const VERSION = "skc-sdk-transport/1";
+
+type AuthFailureCode =
+	| "auth_missing"
+	| "auth_malformed"
+	| "auth_invalid"
+	| "auth_oversize"
+	| "auth_timeout"
+	| "unsupported_version";
+
+export class AuthPrefaceError extends Error {
+	constructor(readonly code: AuthFailureCode) {
+		super(code);
+		this.name = "AuthPrefaceError";
+	}
+}
+
+function digest(token: string): Buffer {
+	return createHash("sha256").update(token).digest();
+}
+
+function validToken(received: string, expected: string): boolean {
+	return timingSafeEqual(digest(received), digest(expected));
+}
+
+function failureFrame(): string {
+	return `${JSON.stringify({ type: "transport_error", code: "auth_failed" })}\n`;
+}
+
+/** Consumes the one-shot socket authentication preface and leaves later bytes readable. */
+export async function authenticatePreface(socket: net.Socket, token: string): Promise<Buffer> {
+	return await new Promise<Buffer>((resolve, reject) => {
+		let buffer = Buffer.alloc(0);
+		let settled = false;
+		const finish = (error?: AuthPrefaceError, remainder = Buffer.alloc(0)): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			socket.removeListener("data", onData);
+			socket.removeListener("end", onEnd);
+			socket.removeListener("error", onSocketError);
+			if (error) {
+				socket.end(failureFrame(), () => reject(error));
+				return;
+			}
+			socket.pause();
+			resolve(remainder);
+		};
+		const fail = (code: AuthFailureCode): void => finish(new AuthPrefaceError(code));
+		const onSocketError = (): void => fail("auth_missing");
+		const onEnd = (): void => fail(buffer.length === 0 ? "auth_missing" : "auth_malformed");
+		const onData = (chunk: Buffer): void => {
+			buffer = Buffer.concat([buffer, chunk]);
+			const newline = buffer.indexOf(0x0a);
+			if (newline < 0) {
+				if (buffer.length > PREFACE_LIMIT_BYTES) fail("auth_oversize");
+				return;
+			}
+			if (newline > PREFACE_LIMIT_BYTES) return fail("auth_oversize");
+			const line = buffer.subarray(0, newline).toString("utf8");
+			const remainder = buffer.subarray(newline + 1);
+			const prefix = `${VERSION} token=`;
+			if (!line.startsWith(prefix)) {
+				return fail(line.startsWith("skc-sdk-transport/") ? "unsupported_version" : "auth_malformed");
+			}
+			const received = line.slice(prefix.length);
+			if (received.length === 0 || /\s/.test(received)) return fail("auth_malformed");
+			if (!validToken(received, token)) return fail("auth_invalid");
+			finish(undefined, remainder);
+		};
+		const timeout = setTimeout(() => fail("auth_timeout"), PREFACE_TIMEOUT_MS);
+		socket.on("data", onData);
+		socket.once("end", onEnd);
+		socket.once("error", onSocketError);
+		socket.resume();
+	});
+}

package/src/sdk/transport/index.ts

@@ -0,0 +1,18 @@
+export {
+	DEFAULT_PENDING_CEILING_BYTES,
+	MIN_PENDING_CEILING_BYTES,
+	REQUEST_FRAME_BYTES,
+} from "./relay";
+export { startSocketServe } from "./socket";
+export { startStdioServe } from "./stdio";
+
+export type ServeOptions = {
+	url: string;
+	token: string;
+	pendingCeilingBytes: number;
+};
+
+export type ServeHandle = {
+	close(): Promise<void>;
+	readonly done: Promise<void>;
+};