@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/src/sdk/client/discovery.ts

@@ -6,6 +6,8 @@ export interface SdkSessionEndpoint {
 	sessionId: string;
 	url: string;
 	token: string;
+	pid?: number;
+	stale?: boolean;
 	path: string;
 }
 
@@ -38,12 +40,26 @@ function endpointDirectory(repo: string): string {
 function parseEndpoint(sessionId: string, file: string, value: unknown): SdkSessionEndpoint {
 	if (!value || typeof value !== "object")
 		throw new SdkDiscoveryError(file, "SDK endpoint discovery record must be an object.");
-	const endpoint = value as { version?: unknown; url?: unknown; token?: unknown };
+	const endpoint = value as { version?: unknown; url?: unknown; token?: unknown; pid?: unknown; stale?: unknown };
 	if (typeof endpoint.version === "number" && endpoint.version > 1)
 		throw new SdkDiscoveryError(file, "Unsupported SDK endpoint discovery state version.");
-	if (typeof endpoint.url !== "string" || typeof endpoint.token !== "string" || !endpoint.url || !endpoint.token)
+	if (typeof endpoint.url !== "string" || !endpoint.url)
 		throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
-	return { sessionId, url: endpoint.url, token: endpoint.token, path: file };
+	const stale = typeof endpoint.stale === "boolean" ? endpoint.stale : undefined;
+	const pid =
+		typeof endpoint.pid === "number" && Number.isInteger(endpoint.pid) && endpoint.pid > 0 ? endpoint.pid : undefined;
+	if (endpoint.token !== undefined && typeof endpoint.token !== "string")
+		throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
+	const token = endpoint.token ?? "";
+	if (!token && stale !== true) throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
+	return {
+		sessionId,
+		url: endpoint.url,
+		token,
+		...(pid === undefined ? {} : { pid }),
+		...(stale === undefined ? {} : { stale }),
+		path: file,
+	};
 }
 
 function discoveryError(file: string, error: unknown): SdkDiscoveryError {

package/src/sdk/client/liveness.ts

@@ -0,0 +1,49 @@
+import type { SdkSessionEndpoint } from "./discovery";
+
+export type SdkEndpointLiveness = "live" | "stale" | "dead" | "unknown";
+
+export interface SdkEndpointSelectionError {
+	code:
+		| "endpoint_stale"
+		| "endpoint_dead"
+		| "endpoint_unknown"
+		| "no_live_endpoint"
+		| "multiple_live_endpoints"
+		| "not_found";
+}
+
+export function classifyEndpoint(endpoint: SdkSessionEndpoint): SdkEndpointLiveness {
+	if (endpoint.stale === true) return "stale";
+	if (!Number.isInteger(endpoint.pid) || endpoint.pid === undefined || endpoint.pid <= 0) return "unknown";
+	try {
+		process.kill(endpoint.pid, 0);
+		return "live";
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ESRCH") return "dead";
+		return code === "EPERM" ? "live" : "unknown";
+	}
+}
+
+export function selectLiveEndpoint(
+	records: readonly SdkSessionEndpoint[],
+	explicitSessionId?: string,
+): SdkSessionEndpoint | SdkEndpointSelectionError {
+	if (explicitSessionId !== undefined) {
+		const endpoint = records.find(record => record.sessionId === explicitSessionId);
+		if (!endpoint) return { code: "not_found" };
+		switch (classifyEndpoint(endpoint)) {
+			case "live":
+				return endpoint;
+			case "stale":
+				return { code: "endpoint_stale" };
+			case "dead":
+				return { code: "endpoint_dead" };
+			case "unknown":
+				return { code: "endpoint_unknown" };
+		}
+	}
+	const live = records.filter(record => classifyEndpoint(record) === "live");
+	if (live.length === 1) return live[0]!;
+	return { code: live.length === 0 ? "no_live_endpoint" : "multiple_live_endpoints" };
+}

package/src/sdk/host/control/dispatch.ts

@@ -137,7 +137,7 @@ function invoke(
 ): Promise<ControlValue> | ControlValue {
 	switch (operation) {
 		case "turn.prompt":
-			return surface.prompt(text(input), input.images);
+			return surface.prompt(text(input), input.images, input.clientRef as string | undefined);
 		case "turn.steer":
 			return surface.steer(text(input));
 		case "turn.follow_up":
@@ -158,7 +158,11 @@ function invoke(
 		case "workflow.plan_approve":
 			return surface.approvePlan(text(input, "id"), input.choice, input.expectedSessionId as string | undefined);
 		case "skill.invoke":
-			return surface.invokeSkill(text(input, "name"), input.args);
+			return surface.invokeSkill(
+				text(input, "name"),
+				input.args,
+				typeof input.clientRef === "string" ? input.clientRef : undefined,
+			);
 		case "mode.plan.set":
 			return surface.setPlanMode(input.on as boolean);
 		case "mode.goal.operate":
@@ -167,6 +171,8 @@ function invoke(
 			return surface.replaceTodo(input.items);
 		case "model.set":
 			return surface.setModel(text(input, "id"), input.thinkingLevel);
+		case "model.profile.set":
+			return surface.setModelProfile(text(input, "id"));
 		case "model.cycle":
 			return surface.cycleModel();
 		case "thinking.set":

package/src/sdk/host/control/operations.ts

@@ -6,7 +6,7 @@ export type ControlInput = Record<string, unknown>;
  * AgentSession and its controllers without exposing those concrete types here.
  */
 export interface ControlSurface {
-	prompt(text: string, images?: ControlValue): Promise<ControlValue> | ControlValue;
+	prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
 	steer(text: string): Promise<ControlValue> | ControlValue;
 	followUp(text: string): Promise<ControlValue> | ControlValue;
 	abort(): Promise<ControlValue> | ControlValue;
@@ -19,11 +19,12 @@ export interface ControlSurface {
 		idempotencyKey?: string,
 	): Promise<ControlValue> | ControlValue;
 	approvePlan(id: string, choice: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
-	invokeSkill(name: string, args: ControlValue): Promise<ControlValue> | ControlValue;
+	invokeSkill(name: string, args: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
 	setPlanMode(on: boolean): Promise<ControlValue> | ControlValue;
 	operateGoal(op: string, objective?: string): Promise<ControlValue> | ControlValue;
 	replaceTodo(items: ControlValue): Promise<ControlValue> | ControlValue;
 	setModel(id: string, thinkingLevel?: ControlValue): Promise<ControlValue> | ControlValue;
+	setModelProfile(id: string): Promise<ControlValue> | ControlValue;
 	cycleModel(): Promise<ControlValue> | ControlValue;
 	setThinking(level: ControlValue): Promise<ControlValue> | ControlValue;
 	cycleThinking(): Promise<ControlValue> | ControlValue;

package/src/sdk/host/host.ts

@@ -9,16 +9,23 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
 	/** Best-effort diagnostic observation of accepted control/query frames. */
 	onRequest?: SdkRequestObserver;
+	/** Runs before a control response is sent; identity transitions use sendTerminal. */
+	beforeControlResponse?: (
+		connectionId: string,
+		request: SdkFrame,
+		response: SdkFrame,
+		sendTerminal: () => Promise<void>,
+	) => void | Promise<void>;
 	/** Runs only after a successful control response has been sent to the client. */
 	afterControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame) => void | Promise<void>;
 	installProviderDefinitions?: (capability: string, definitions: unknown) => void;
 	onProviderDefinitionsRemoved?: (capability: string) => void;
 	onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
 	/** Best-effort capabilities mirrored from the native transport for out-of-band consumers. */
-	connectionCapabilities?: (connectionId: string) => ReadonlySet<string>;
+	connectionCapabilities?: (connectionId: string) => ReadonlySet<string> | undefined;
 }
 
-const TOOL_ACTIVITY_V1 = "tool_activity_v1";
+const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 const CAP_GATED_FRAME_KINDS = new Set(["tool_activity", "reasoning_summary"]);
 const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 
@@ -36,6 +43,14 @@ function errorFrame(connectionId: string, frame: SdkFrame, error: unknown): SdkF
 				? candidate.code
 				: "internal";
 	const message = typeof candidate?.message === "string" ? candidate.message : "SDK host operation failed.";
+	if (frame.type === "control_request") {
+		return {
+			type: "control_response",
+			id: typeof frame.id === "string" ? frame.id : "",
+			ok: false,
+			error: { code, message },
+		};
+	}
 	return {
 		type: "reverse_response",
 		id: typeof frame.id === "string" ? frame.id : "",
@@ -214,7 +229,14 @@ export class SessionSdkHost {
 					const result = await this.#options.control?.(connectionId, frame);
 					if (result !== undefined) {
 						const response = { type: "control_response", ...(result as SdkFrame) };
-						await this.#send(connectionId, response);
+						let terminalSent = false;
+						const sendTerminal = async (): Promise<void> => {
+							if (terminalSent) return;
+							terminalSent = true;
+							await this.#send(connectionId, response);
+						};
+						await this.#options.beforeControlResponse?.(connectionId, frame, response, sendTerminal);
+						await sendTerminal();
 						await this.#options.afterControlResponse?.(connectionId, frame, response);
 					}
 					break;
@@ -231,13 +253,9 @@ export class SessionSdkHost {
 					const sinceGeneration = rawGeneration;
 					const sinceSeq = rawSeq;
 					const replay = this.events.replay(sinceSeq, sinceGeneration);
-					const capabilities = Array.isArray(frame.capabilities)
-						? new Set(
-								frame.capabilities.filter((capability): capability is string => typeof capability === "string"),
-							)
-						: (this.#options.connectionCapabilities?.(connectionId) ?? EMPTY_CAPABILITIES);
+					const capabilities = this.#options.connectionCapabilities?.(connectionId) ?? EMPTY_CAPABILITIES;
 					const events = replay.events.filter(
-						event => !CAP_GATED_FRAME_KINDS.has(String(event.kind)) || capabilities.has(TOOL_ACTIVITY_V1),
+						event => !CAP_GATED_FRAME_KINDS.has(String(event.kind)) || capabilities.has(TOOL_ACTIVITY_CAPABILITY),
 					);
 					await this.#send(connectionId, {
 						type: "event_replay_result",

package/src/sdk/host/query/handlers.ts

@@ -1,3 +1,4 @@
+import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../../prompt-status.js";
 import {
 	assertCursorSelector,
 	type CursorEnvelope,
@@ -43,6 +44,15 @@ export interface SessionSurface {
 		| Promise<{ bytes: Uint8Array; totalBytes: number } | undefined>;
 
 	getJobs(): unknown | Promise<unknown>;
+	/** Q26 keyed lookup of a submitted prompt's authoritative reconciliation status. */
+	getPromptStatus?(selector: { commandId?: string; turnId?: string; clientRef?: string }): unknown | Promise<unknown>;
+	getSkillInvokeStatus?(selector: {
+		commandId?: string;
+		turnId?: string;
+		clientRef?: string;
+	}): unknown | Promise<unknown>;
+	/** Q27 effective model-profile catalog from the live session registry. */
+	getModelProfiles?(): unknown[] | Promise<unknown[]>;
 	/** Query rows backed by the session's installed binding map. */
 	installedQueries?: ReadonlySet<string>;
 }
@@ -66,7 +76,7 @@ export interface QueryResponse {
 	ok: boolean;
 	page?: QueryPage;
 	result?: unknown;
-	error?: { code: string; message: string; restartQuery?: boolean };
+	error?: { code: string; message: string; restartQuery?: boolean; details?: unknown };
 }
 
 const sources: Record<string, { resource: string; method: keyof SessionSurface; mvcc: boolean }> = {
@@ -92,6 +102,7 @@ const sources: Record<string, { resource: string; method: keyof SessionSurface;
 	Q21: { resource: "queue", method: "getQueueMessages", mvcc: true },
 	Q22: { resource: "extensions", method: "getExtensions", mvcc: true },
 	Q25: { resource: "jobs", method: "getJobs", mvcc: false },
+	Q27: { resource: "modelProfiles", method: "getModelProfiles", mvcc: true },
 };
 const names = [
 	"transcript.list",
@@ -119,6 +130,9 @@ const names = [
 	"resource.body",
 	"artifact.read",
 	"runtime.jobs.list",
+	"turn.prompt_status",
+	"models.profiles.list",
+	"skill.invoke_status",
 ];
 
 export class QueryHandlers {
@@ -147,13 +161,19 @@ export class QueryHandlers {
 				);
 			if (query === "Q02") return await this.#transcriptBody(request);
 			if (query === "Q23") return await this.#resourceBody(request);
+			if (query === "Q26") return await this.#promptStatus(request);
+			if (query === "Q28") return await this.#skillInvokeStatus(request);
 			if (query === "Q24") return await this.#artifact(request);
+			if (query === "Q27" && request.input && Object.keys(request.input).length > 0)
+				return this.#error(request, "invalid_request", false, "models.profiles.list does not accept input fields.");
+			if (query === "Q27" && typeof this.surface.getModelProfiles !== "function")
+				return this.#error(request, "unavailable", false, "models.profiles.list is unavailable for this session.");
 			const source = sources[query];
 			if (!source) return this.#error(request, "invalid_request");
 			return await this.#pageSource(request, query, source);
 		} catch (error) {
 			if (error instanceof CursorError) return this.#error(request, error.code, error.restartQuery, error.message);
-			if (isTypedError(error)) return this.#error(request, error.code, false, error.message);
+			if (isTypedError(error)) return this.#error(request, error.code, false, error.message, error.details);
 			return this.#error(request, "internal", false, error instanceof Error ? error.message : String(error));
 		}
 	}
@@ -504,8 +524,108 @@ export class QueryHandlers {
 		return { id: request.id, ok: true, page };
 	}
 
-	#error(request: QueryRequest, code: string, restartQuery = false, message = code): QueryResponse {
-		return { id: request.id, ok: false, error: { code, message, ...(restartQuery ? { restartQuery: true } : {}) } };
+	async #skillInvokeStatus(request: QueryRequest): Promise<QueryResponse> {
+		if (request.cursor)
+			return this.#error(request, "invalid_request", false, "skill.invoke_status does not support cursors.");
+		const input = request.input ?? {};
+		for (const key of Object.keys(input))
+			if (key !== "commandId" && key !== "turnId" && key !== "clientRef")
+				return this.#error(
+					request,
+					"invalid_request",
+					false,
+					`skill.invoke_status does not accept selector field "${key}".`,
+				);
+		const commandId = typeof input.commandId === "string" && input.commandId ? input.commandId : undefined;
+		const turnId = typeof input.turnId === "string" && input.turnId ? input.turnId : undefined;
+		const rawClientRef = typeof input.clientRef === "string" ? input.clientRef : undefined;
+		const trimmedClientRef = rawClientRef?.trim();
+		if (rawClientRef !== undefined && (!trimmedClientRef || trimmedClientRef.length > PROMPT_CLIENT_REF_MAX_LENGTH))
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"clientRef must be a non-empty string of at most 128 characters.",
+			);
+		const clientRef = trimmedClientRef || undefined;
+		if ((commandId === undefined) !== (turnId === undefined))
+			return this.#error(request, "invalid_request", false, "commandId and turnId must be provided together.");
+		if (commandId !== undefined && clientRef !== undefined)
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"Provide exactly one selector: a commandId/turnId pair or a clientRef.",
+			);
+		if (commandId === undefined && clientRef === undefined)
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"skill.invoke_status requires a commandId/turnId pair or a clientRef.",
+			);
+		if (typeof this.surface.getSkillInvokeStatus !== "function")
+			return this.#error(request, "unavailable", false, "skill.invoke_status is unavailable for this session.");
+		const result = await this.surface.getSkillInvokeStatus(
+			clientRef !== undefined ? { clientRef } : { commandId: commandId!, turnId: turnId! },
+		);
+		return { id: request.id, ok: true, result };
+	}
+
+	async #promptStatus(request: QueryRequest): Promise<QueryResponse> {
+		if (request.cursor)
+			return this.#error(request, "invalid_request", false, "turn.prompt_status does not support cursors.");
+		const input = request.input ?? {};
+		for (const key of Object.keys(input))
+			if (key !== "commandId" && key !== "turnId" && key !== "clientRef")
+				return this.#error(
+					request,
+					"invalid_request",
+					false,
+					`turn.prompt_status does not accept selector field "${key}".`,
+				);
+		const commandId = typeof input.commandId === "string" && input.commandId ? input.commandId : undefined;
+		const turnId = typeof input.turnId === "string" && input.turnId ? input.turnId : undefined;
+		const rawClientRef = typeof input.clientRef === "string" ? input.clientRef : undefined;
+		const trimmedClientRef = rawClientRef?.trim();
+		if (rawClientRef !== undefined && (!trimmedClientRef || trimmedClientRef.length > PROMPT_CLIENT_REF_MAX_LENGTH))
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"clientRef must be a non-empty string of at most 128 characters.",
+			);
+		const clientRef = trimmedClientRef || undefined;
+		if ((commandId === undefined) !== (turnId === undefined))
+			return this.#error(request, "invalid_request", false, "commandId and turnId must be provided together.");
+		if (commandId !== undefined && clientRef !== undefined)
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"Provide exactly one selector: a commandId/turnId pair or a clientRef.",
+			);
+		if (commandId === undefined && clientRef === undefined)
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"turn.prompt_status requires a commandId/turnId pair or a clientRef.",
+			);
+		if (typeof this.surface.getPromptStatus !== "function")
+			return this.#error(request, "unavailable", false, "turn.prompt_status is unavailable for this session.");
+		const result = await this.surface.getPromptStatus(
+			clientRef !== undefined ? { clientRef } : { commandId: commandId!, turnId: turnId! },
+		);
+		return { id: request.id, ok: true, result };
+	}
+
+	#error(request: QueryRequest, code: string, restartQuery = false, message = code, details?: unknown): QueryResponse {
+		return {
+			id: request.id,
+			ok: false,
+			error: { code, message, ...(restartQuery ? { restartQuery: true } : {}), ...(details ? { details } : {}) },
+		};
 	}
 }
 function selectorFor(queryId: string, input: Record<string, unknown> | undefined): CursorSelector {
@@ -521,7 +641,7 @@ function idOf(value: unknown): string | undefined {
 function lastId(value: unknown): string | undefined {
 	return Array.isArray(value) ? idOf(value.at(-1)) : undefined;
 }
-function isTypedError(error: unknown): error is { code: string; message: string } {
+function isTypedError(error: unknown): error is { code: string; message: string; details?: unknown } {
 	return Boolean(
 		error &&
 			typeof error === "object" &&

package/src/sdk/index.ts

@@ -1,3 +1,14 @@
+export {
+	MODEL_PROFILE_DISCOVERY_QUERY,
+	MODEL_PROFILE_ERROR_DETAIL_MAX_BYTES,
+	type ModelProfileCatalogItem,
+	type ModelProfileErrorCode,
+	type ModelProfileErrorDetails,
+	ModelProfileRegistryError,
+	type ModelProfileRegistryErrorDetails,
+	type UnknownModelProfileDetails,
+	UnknownModelProfileError,
+} from "../config/model-profile-contract";
 export * as bus from "./bus";
 export * from "./client";
 export * as host from "./host";
@@ -10,5 +21,6 @@ export type {
 	Q10ThinkingEffort,
 	Q10ThinkingMode,
 } from "./models";
+export * from "./prompt-status";
 export * from "./session";
 export * from "./session-directory";

package/src/sdk/lifecycle-session.ts

@@ -1,6 +1,7 @@
 import type { AgentSession } from "../session/agent-session";
 import { type CreateAgentSessionOptions, createAgentSession } from "./session";
 import {
+	lifecycleMcpStartupTimeoutOption,
 	lifecycleStartupCapabilityOption,
 	SdkStartupCapability,
 	type SdkStartupFailure,
@@ -15,17 +16,32 @@ export type CreateLifecycleAgentSessionResult =
 	  }
 	| { capability: SdkStartupCapability; rollback: SdkStartupRollbackTracker; failure: SdkStartupFailure };
 
+/** Options accepted by lifecycle-only session construction. */
+export type CreateLifecycleAgentSessionOptions = CreateAgentSessionOptions & {
+	/**
+	 * Startup budget for ACP lifecycle MCP launches, in milliseconds. Set only
+	 * when the lifecycle request supplies `mcpServers`; ordinary consumers keep
+	 * the manager's short default ceiling.
+	 */
+	mcpStartupTimeoutMs?: number;
+};
+
 /** Internal lifecycle-only session construction with an owner-bound SDK startup result. */
 export async function createLifecycleAgentSession(
-	options: CreateAgentSessionOptions = {},
+	options: CreateLifecycleAgentSessionOptions = {},
 ): Promise<CreateLifecycleAgentSessionResult> {
 	const rollback = new SdkStartupRollbackTracker();
 	const capability = new SdkStartupCapability(rollback);
 	try {
+		const { mcpStartupTimeoutMs, ...sessionOptions } = options;
 		const internalOptions = {
-			...options,
+			...sessionOptions,
 			[lifecycleStartupCapabilityOption]: capability,
-		} as CreateAgentSessionOptions & { [lifecycleStartupCapabilityOption]: SdkStartupCapability };
+			...(mcpStartupTimeoutMs !== undefined ? { [lifecycleMcpStartupTimeoutOption]: mcpStartupTimeoutMs } : {}),
+		} as CreateAgentSessionOptions & {
+			[lifecycleStartupCapabilityOption]: SdkStartupCapability;
+			[lifecycleMcpStartupTimeoutOption]?: number;
+		};
 		const result = await createAgentSession(internalOptions);
 		if (!result.session.extensionRunner)
 			capability.settleFailure(capability.normalizeFailure("registration", "runner_absent"));

package/src/sdk/mcp/server.ts

@@ -301,9 +301,16 @@ export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
 export async function runSdkMcpStdio(options: SdkMcpServerOptions = {}): Promise<void> {
 	const server = createSdkMcpServer(options);
 	let buffer = "";
+	const inflight = new Set<Promise<void>>();
 	process.stdin.setEncoding("utf8");
-	await new Promise<void>(resolve => {
-		process.stdin.on("data", (chunk: string) => {
+
+	const track = (work: Promise<void>): void => {
+		inflight.add(work);
+		void work.finally(() => inflight.delete(work));
+	};
+
+	await new Promise<void>((resolve, reject) => {
+		const onData = (chunk: string) => {
 			buffer += chunk;
 			let index = buffer.indexOf("\n");
 			while (index >= 0) {
@@ -311,22 +318,43 @@ export async function runSdkMcpStdio(options: SdkMcpServerOptions = {}): Promise
 				buffer = buffer.slice(index + 1);
 				index = buffer.indexOf("\n");
 				if (!line) continue;
-				void (async () => {
-					let request: JsonRpcRequest;
-					try {
-						request = JSON.parse(line) as JsonRpcRequest;
-					} catch {
-						process.stdout.write(
-							`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse_error" } })}\n`,
-						);
-						return;
-					}
-					const response = await server.handleJsonRpc(request);
-					// JSON-RPC notifications (no id) receive no response.
-					if (request.id !== undefined) process.stdout.write(`${JSON.stringify(response)}\n`);
-				})();
+				track(
+					(async () => {
+						let request: JsonRpcRequest;
+						try {
+							request = JSON.parse(line) as JsonRpcRequest;
+						} catch {
+							process.stdout.write(
+								`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse_error" } })}\n`,
+							);
+							return;
+						}
+						const response = await server.handleJsonRpc(request);
+						// JSON-RPC notifications (no id) receive no response.
+						if (request.id !== undefined) process.stdout.write(`${JSON.stringify(response)}\n`);
+					})(),
+				);
 			}
-		});
-		process.stdin.on("end", () => resolve());
+		};
+		const onEnd = () => {
+			process.stdin.off("data", onData);
+			process.stdin.off("end", onEnd);
+			process.stdin.off("error", onError);
+			resolve();
+		};
+		const onError = (error: Error) => {
+			process.stdin.off("data", onData);
+			process.stdin.off("end", onEnd);
+			process.stdin.off("error", onError);
+			reject(error);
+		};
+		process.stdin.on("data", onData);
+		process.stdin.on("end", onEnd);
+		process.stdin.on("error", onError);
 	});
+
+	// Stdin EOF must not drop in-flight tools/call handlers (WS connect/query).
+	// Awaiting them also prevents the process from exiting before responses flush,
+	// and lets clients close so the event loop can drain deterministically.
+	await Promise.allSettled([...inflight]);
 }

package/src/sdk/prompt-status.ts

@@ -0,0 +1,97 @@
+/**
+ * Public DTO contract for Q26 `turn.prompt_status` and the `clientRef`
+ * correlation field on `turn.prompt`.
+ *
+ * Semantics:
+ * - `turn.prompt` remains ordered and non-idempotent. An envelope
+ *   `idempotencyKey` is ignored for replay/conflict purposes on ordered
+ *   operations (no replay cache, no `idempotency_conflict`).
+ * - `clientRef` is a caller-chosen correlation key (trimmed, non-empty,
+ *   1..PROMPT_CLIENT_REF_MAX_LENGTH chars; one fresh value per logical prompt)
+ *   mapped to the generated commandId/turnId at preflight acceptance so a
+ *   caller can reconcile after a lost acknowledgement frame.
+ * - The clientRef index is scoped to one live session runtime: identical refs
+ *   may coexist in different sessions, lookups never cross sessions, a ref
+ *   conflicts only while its record is retained (`client_ref_conflict`), and
+ *   after terminal TTL/capacity eviction a ref may be admitted again with the
+ *   prior outcome unknown — callers MUST NOT reuse a clientRef as a retry
+ *   mechanism and MUST treat `unknown` as uncertainty, not proof of
+ *   non-execution.
+ * - The durability floor is the live session process: after restart or
+ *   retained-record eviction, a lookup honestly reports `unknown`.
+ * - 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.
+ */
+
+export const PROMPT_CLIENT_REF_MAX_LENGTH = 128;
+
+export interface TurnPromptImageInput {
+	data: string;
+	mimeType?: string;
+}
+
+/** Public input contract for ordered `turn.prompt`. */
+export interface TurnPromptInput {
+	text: string;
+	images?: TurnPromptImageInput[];
+	clientRef?: string;
+}
+
+/** Terminal outcome is preserved exactly; active records never age into terminal. */
+export type PromptReconciliationStatus = "accepted" | "in_flight" | "terminal_ok" | "failed";
+
+/** Exactly one selector per lookup. */
+export type TurnPromptStatusSelector = { clientRef: string } | { commandId: string; turnId: string };
+
+interface TurnPromptReconciliationIdentity {
+	commandId: string;
+	turnId: string;
+	clientRef?: string;
+	/** Epoch milliseconds of preflight acceptance. */
+	acceptedAt: number;
+}
+
+export interface TurnPromptReconciliationAccepted extends TurnPromptReconciliationIdentity {
+	status: "accepted";
+}
+
+export interface TurnPromptReconciliationInFlight extends TurnPromptReconciliationIdentity {
+	status: "in_flight";
+	/** Epoch milliseconds of the agent_start transition. */
+	startedAt: number;
+}
+
+export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconciliationIdentity {
+	status: "terminal_ok";
+	startedAt?: number;
+	/** Epoch milliseconds of the terminal transition. */
+	terminalAt: number;
+}
+
+export interface TurnPromptReconciliationFailed extends TurnPromptReconciliationIdentity {
+	status: "failed";
+	startedAt?: number;
+	terminalAt: number;
+	/** Bounded, sanitized failure detail (code safe-token ≤64, message ≤512). */
+	error: { code: string; message: string };
+}
+
+export interface TurnPromptReconciliationUnknown {
+	status: "unknown";
+}
+
+export type TurnPromptReconciliation =
+	| TurnPromptReconciliationAccepted
+	| TurnPromptReconciliationInFlight
+	| TurnPromptReconciliationTerminalOk
+	| TurnPromptReconciliationFailed
+	| TurnPromptReconciliationUnknown;
+
+/** Result of a successful `turn.prompt` preflight acknowledgement. */
+export interface TurnPromptAcceptedResult {
+	commandId: string;
+	turnId: string;
+	accepted: true;
+	clientRef?: string;
+}