@gajae-code/coding-agent 0.11.11 → 0.12.0

package/src/sdk/bus/kind-aware-reconciliation.ts

@@ -0,0 +1,242 @@
+/**
+ * Kind-aware invocation reconciliation (prompt | skill) with optional durable store.
+ * Preserves Q26 admit/first-terminal/capacity/TTL semantics; indexes and caps are per-kind.
+ */
+import {
+	PROMPT_RECONCILIATION_ACTIVE_CAPACITY,
+	PROMPT_RECONCILIATION_TERMINAL_CAPACITY,
+	PROMPT_RECONCILIATION_TERMINAL_TTL_MS,
+	type PromptCorrelation,
+	type PromptReconciliationStatus,
+	sanitizePromptFailure,
+	type TurnPromptReconciliation,
+} from "./prompt-reconciliation";
+import type { DurableReconciliationRecord, ReconciliationKind, ReconciliationStore } from "./reconciliation-store";
+
+export type { ReconciliationKind };
+
+export interface KindCorrelation extends PromptCorrelation {
+	kind: ReconciliationKind;
+}
+
+export interface KindAwareReconciliation {
+	admit(kind: ReconciliationKind, clientRef?: string): void;
+	releaseAdmission(kind: ReconciliationKind, clientRef?: string): void;
+	noteAccepted(
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation,
+		clientRef?: string,
+		extra?: { skillName?: string },
+	): Promise<void>;
+	noteTransition(
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	): Promise<void>;
+	lookup(
+		kind: ReconciliationKind,
+		selector: { commandId?: string; turnId?: string; clientRef?: string },
+	): TurnPromptReconciliation;
+	cleanup(): void;
+	activeCount(kind: ReconciliationKind): number;
+	/** Hydrate from durable store (call once at session host start). */
+	hydrateFromStore(): Promise<void>;
+}
+
+export function createKindAwareReconciliation(
+	options: { now?: () => number; store?: ReconciliationStore | null } = {},
+): KindAwareReconciliation {
+	const now = options.now ?? Date.now;
+	const store = options.store ?? null;
+	const records = new Map<string, DurableReconciliationRecord>();
+	const clientRefIndex = new Map<string, string>(); // `${kind}\0${clientRef}` -> key
+	const reservedClientRefs = new Map<ReconciliationKind, Set<string>>();
+	const reservations: Array<{ kind: ReconciliationKind; clientRef?: string }> = [];
+
+	const keyOf = (kind: ReconciliationKind, correlation: PromptCorrelation) =>
+		`${kind}:${correlation.commandId}:${correlation.turnId}`;
+	const refKey = (kind: ReconciliationKind, clientRef: string) => `${kind}\0${clientRef}`;
+
+	const reservedFor = (kind: ReconciliationKind) => {
+		let set = reservedClientRefs.get(kind);
+		if (!set) {
+			set = new Set();
+			reservedClientRefs.set(kind, set);
+		}
+		return set;
+	};
+
+	const remove = (key: string) => {
+		const record = records.get(key);
+		if (!record) return;
+		records.delete(key);
+		if (record.clientRef !== undefined) {
+			const rk = refKey(record.kind, record.clientRef);
+			if (clientRefIndex.get(rk) === key) clientRefIndex.delete(rk);
+		}
+	};
+
+	const cleanup = () => {
+		const at = now();
+		for (const [key, record] of records)
+			if (record.terminalAt !== undefined && record.terminalAt + PROMPT_RECONCILIATION_TERMINAL_TTL_MS <= at)
+				remove(key);
+		for (const kind of ["prompt", "skill"] as const) {
+			const terminalEntries = [...records.entries()].filter(
+				([, record]) => record.kind === kind && record.terminalAt !== undefined,
+			);
+			if (terminalEntries.length <= PROMPT_RECONCILIATION_TERMINAL_CAPACITY) continue;
+			terminalEntries.sort((a, b) => (a[1].terminalAt as number) - (b[1].terminalAt as number));
+			for (const [key] of terminalEntries.slice(0, terminalEntries.length - PROMPT_RECONCILIATION_TERMINAL_CAPACITY))
+				remove(key);
+		}
+	};
+
+	const activeCount = (kind: ReconciliationKind) => {
+		let count = 0;
+		for (const record of records.values()) if (record.kind === kind && record.terminalAt === undefined) count++;
+		return count;
+	};
+
+	const reservationCount = (kind: ReconciliationKind) => reservations.filter(r => r.kind === kind).length;
+
+	const consumeReservation = (kind: ReconciliationKind, clientRef?: string) => {
+		const index = reservations.findIndex(r => r.kind === kind && r.clientRef === clientRef);
+		if (index === -1) return;
+		reservations.splice(index, 1);
+		if (clientRef !== undefined && !reservations.some(r => r.kind === kind && r.clientRef === clientRef))
+			reservedFor(kind).delete(clientRef);
+	};
+
+	const persist = async () => {
+		if (!store) return;
+		await store.transact(() => [...records.values()].map(r => ({ ...r })));
+	};
+
+	const admit = (kind: ReconciliationKind, clientRef?: string) => {
+		cleanup();
+		const reserved = reservedFor(kind);
+		if (clientRef !== undefined && (clientRefIndex.has(refKey(kind, clientRef)) || reserved.has(clientRef)))
+			throw Object.assign(
+				new Error("A submission with this clientRef is already retained; never reuse a clientRef for retry."),
+				{ code: "client_ref_conflict" },
+			);
+		if (activeCount(kind) + reservationCount(kind) >= PROMPT_RECONCILIATION_ACTIVE_CAPACITY)
+			throw Object.assign(new Error("Too many active submissions; reconcile or await terminal state."), {
+				code: "reconciliation_capacity",
+			});
+		reservations.push({ kind, clientRef });
+		if (clientRef !== undefined) reserved.add(clientRef);
+	};
+
+	const releaseAdmission = (kind: ReconciliationKind, clientRef?: string) => {
+		consumeReservation(kind, clientRef);
+	};
+
+	const noteAccepted = async (
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation,
+		clientRef?: string,
+		extra?: { skillName?: string },
+	) => {
+		cleanup();
+		consumeReservation(kind, clientRef);
+		const at = now();
+		const key = keyOf(kind, correlation);
+		const record: DurableReconciliationRecord = {
+			kind,
+			commandId: correlation.commandId,
+			turnId: correlation.turnId,
+			...(clientRef !== undefined ? { clientRef } : {}),
+			status: "accepted",
+			acceptedAt: at,
+			...(extra?.skillName ? { skillName: extra.skillName } : {}),
+		};
+		records.set(key, record);
+		if (clientRef !== undefined) clientRefIndex.set(refKey(kind, clientRef), key);
+		await persist();
+	};
+
+	const noteTransition = async (
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	) => {
+		if (!correlation) return;
+		const record = records.get(keyOf(kind, correlation));
+		if (!record || record.terminalAt !== undefined) return;
+		if (frame.type === "agent_start") {
+			if (record.status === "accepted") {
+				record.status = "in_flight";
+				record.startedAt = now();
+				await persist();
+			}
+			return;
+		}
+		record.terminalAt = now();
+		if (frame.type === "agent_failed") {
+			record.status = "failed";
+			record.error = sanitizePromptFailure(frame.error);
+		} else {
+			record.status = "terminal_ok";
+		}
+		cleanup();
+		await persist();
+	};
+
+	const lookup = (
+		kind: ReconciliationKind,
+		selector: { commandId?: string; turnId?: string; clientRef?: string },
+	): TurnPromptReconciliation => {
+		cleanup();
+		const key =
+			selector.clientRef !== undefined
+				? clientRefIndex.get(refKey(kind, selector.clientRef))
+				: selector.commandId !== undefined && selector.turnId !== undefined
+					? keyOf(kind, { commandId: selector.commandId, turnId: selector.turnId })
+					: undefined;
+		const record = key === undefined ? undefined : records.get(key);
+		if (!record) return { status: "unknown" };
+		const identity = {
+			commandId: record.commandId,
+			turnId: record.turnId,
+			...(record.clientRef !== undefined ? { clientRef: record.clientRef } : {}),
+			acceptedAt: record.acceptedAt,
+		};
+		if (record.status === "accepted") return { status: "accepted", ...identity };
+		if (record.status === "in_flight")
+			return { status: "in_flight", ...identity, startedAt: record.startedAt as number };
+		const terminal = {
+			...identity,
+			...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+			terminalAt: record.terminalAt as number,
+		};
+		if (record.status === "terminal_ok") return { status: "terminal_ok", ...terminal };
+		return { status: "failed", ...terminal, error: record.error ?? sanitizePromptFailure(undefined) };
+	};
+
+	const hydrateFromStore = async () => {
+		if (!store) return;
+		const loaded = await store.load();
+		records.clear();
+		clientRefIndex.clear();
+		for (const record of loaded) {
+			const key = keyOf(record.kind, record);
+			records.set(key, record);
+			if (record.clientRef !== undefined) clientRefIndex.set(refKey(record.kind, record.clientRef), key);
+		}
+	};
+
+	return {
+		admit,
+		releaseAdmission,
+		noteAccepted,
+		noteTransition,
+		lookup,
+		cleanup,
+		activeCount,
+		hydrateFromStore,
+	};
+}
+
+export type { PromptReconciliationStatus };

package/src/sdk/bus/prompt-reconciliation.ts

@@ -12,7 +12,8 @@
  * - Terminal records are retained for TERMINAL_TTL_MS and bounded to
  *   TERMINAL_CAPACITY, evicted oldest-terminal-first by terminalAt; only then
  *   does a lookup honestly report `unknown`.
- * - The durability floor is the live session process: restart means `unknown`.
+ * - Process-local durability floor is the live session process: restart means `unknown`.
+ *   Session-scoped durable retention (kind-aware store) is provided by reconciliation-store.ts (#3032).
  * - The clientRef index is session-runtime scoped; a ref conflicts only while
  *   retained and must never be reused as a retry mechanism.
  * - Terminal transitions settle once: the first terminal outcome wins.

package/src/sdk/bus/reconciliation-store.ts

@@ -0,0 +1,224 @@
+/**
+ * Session-scoped durable store for kind-aware invocation reconciliation (#3032/#3035).
+ *
+ * Path is always a private sibling of the transcript, never under artifactsDir:
+ *   <dirname(sessionFile)>/.sdk-reconciliation/<safeSessionId>.json
+ *
+ * Safe session ids only: /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+ * Atomic write: temp + fsync + rename + 0600. Corrupt → quarantine + empty.
+ * Non-terminal records settle to failed/process_restart on bootstrap (recon incomplete).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { PromptCorrelation, PromptReconciliationStatus } from "./prompt-reconciliation";
+
+export const RECONCILIATION_STORE_VERSION = 1;
+export const RECONCILIATION_SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const RECONCILIATION_DIR_NAME = ".sdk-reconciliation";
+
+export type ReconciliationKind = "prompt" | "skill";
+
+export interface DurableReconciliationRecord extends PromptCorrelation {
+	kind: ReconciliationKind;
+	clientRef?: string;
+	status: PromptReconciliationStatus;
+	error?: { code: string; message: string };
+	acceptedAt: number;
+	startedAt?: number;
+	terminalAt?: number;
+	/** Skill-only safe token; never skill args bodies. */
+	skillName?: string;
+}
+
+export interface ReconciliationStoreDocument {
+	version: typeof RECONCILIATION_STORE_VERSION;
+	sessionId: string;
+	records: DurableReconciliationRecord[];
+}
+
+export interface ReconciliationStoreFs {
+	mkdir(directory: string, options: { recursive: true; mode: number }): Promise<unknown>;
+	readFile(file: string, encoding: "utf8"): Promise<string>;
+	writeFile(file: string, data: string, options: { mode: number }): Promise<void>;
+	rename(from: string, to: string): Promise<void>;
+	unlink(file: string): Promise<void>;
+	open(
+		file: string,
+		flags: string,
+	): Promise<{
+		sync(): Promise<void>;
+		close(): Promise<void>;
+		writeFile(data: string, encoding: "utf8"): Promise<void>;
+	}>;
+}
+
+const nodeFs: ReconciliationStoreFs = {
+	mkdir: fs.mkdir,
+	readFile: fs.readFile,
+	writeFile: fs.writeFile,
+	rename: fs.rename,
+	unlink: fs.unlink,
+	open: fs.open as ReconciliationStoreFs["open"],
+};
+
+export function isSafeReconciliationSessionId(sessionId: string): boolean {
+	return RECONCILIATION_SESSION_ID_PATTERN.test(sessionId);
+}
+
+/** Derive private store path; throws if sessionId is unsafe (path escape). */
+export function reconciliationStorePath(sessionFile: string, sessionId: string): string {
+	if (!isSafeReconciliationSessionId(sessionId))
+		throw Object.assign(new Error("Unsafe session id for reconciliation store path."), {
+			code: "invalid_input",
+		});
+	return path.join(path.dirname(sessionFile), RECONCILIATION_DIR_NAME, `${sessionId}.json`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseDocument(raw: string, expectedSessionId: string): ReconciliationStoreDocument {
+	const value = JSON.parse(raw) as unknown;
+	if (!isRecord(value) || value.version !== RECONCILIATION_STORE_VERSION)
+		throw new Error("invalid reconciliation store version");
+	if (value.sessionId !== expectedSessionId) throw new Error("session id mismatch");
+	if (!Array.isArray(value.records)) throw new Error("invalid records");
+	return value as unknown as ReconciliationStoreDocument;
+}
+
+/**
+ * Settle non-terminal durable records after process death: failed/process_restart.
+ * Meaning: reconciliation incomplete — not proof of agent failure.
+ */
+export function settleProcessRestart(
+	records: DurableReconciliationRecord[],
+	now: number,
+): DurableReconciliationRecord[] {
+	return records.map(record => {
+		if (record.terminalAt !== undefined) return record;
+		return {
+			...record,
+			status: "failed",
+			terminalAt: now,
+			error: { code: "process_restart", message: "Reconciliation incomplete after process restart." },
+		};
+	});
+}
+
+export interface ReconciliationStore {
+	readonly path: string | null;
+	readonly sessionId: string;
+	/** Serialize mutations; reload not required for single-process host (in-memory + write). */
+	transact(mutator: (records: DurableReconciliationRecord[]) => DurableReconciliationRecord[]): Promise<void>;
+	load(): Promise<DurableReconciliationRecord[]>;
+	/** Snapshot currently held in memory after last load/transact. */
+	snapshot(): DurableReconciliationRecord[];
+	delete(): Promise<void>;
+}
+
+export function createReconciliationStore(options: {
+	sessionFile: string | null | undefined;
+	sessionId: string;
+	fs?: ReconciliationStoreFs;
+	now?: () => number;
+}): ReconciliationStore {
+	const fileFs = options.fs ?? nodeFs;
+	const now = options.now ?? Date.now;
+	const sessionId = options.sessionId;
+	const filePath =
+		options.sessionFile && isSafeReconciliationSessionId(sessionId)
+			? reconciliationStorePath(options.sessionFile, sessionId)
+			: null;
+
+	let memory: DurableReconciliationRecord[] = [];
+	let chain: Promise<void> = Promise.resolve();
+
+	const writeAtomic = async (document: ReconciliationStoreDocument): Promise<void> => {
+		if (!filePath) return;
+		const directory = path.dirname(filePath);
+		await fileFs.mkdir(directory, { recursive: true, mode: 0o700 });
+		const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await fileFs.writeFile(temporary, `${JSON.stringify(document)}\n`, { mode: 0o600 });
+			try {
+				const handle = await fileFs.open(temporary, "r+");
+				try {
+					await handle.sync();
+				} finally {
+					await handle.close();
+				}
+			} catch {
+				// fsync optional on some fs seams
+			}
+			await fileFs.rename(temporary, filePath);
+		} catch (error) {
+			await fileFs.unlink(temporary).catch(() => {});
+			throw Object.assign(error instanceof Error ? error : new Error("reconciliation persist failed"), {
+				code: "reconciliation_persist_failed",
+			});
+		}
+	};
+
+	const load = async (): Promise<DurableReconciliationRecord[]> => {
+		if (!filePath) {
+			memory = [];
+			return memory;
+		}
+		try {
+			const raw = await fileFs.readFile(filePath, "utf8");
+			const document = parseDocument(raw, sessionId);
+			memory = settleProcessRestart(document.records, now());
+			// Persist settled state so restart is sticky.
+			if (memory.some((r, i) => r !== document.records[i]))
+				await writeAtomic({ version: RECONCILIATION_STORE_VERSION, sessionId, records: memory });
+			return memory;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				memory = [];
+				return memory;
+			}
+			// Corrupt → quarantine
+			try {
+				await fileFs.rename(filePath, `${filePath}.corrupt.${now()}`);
+			} catch {
+				// ignore
+			}
+			memory = [];
+			return memory;
+		}
+	};
+
+	const transact = async (
+		mutator: (records: DurableReconciliationRecord[]) => DurableReconciliationRecord[],
+	): Promise<void> => {
+		const run = async () => {
+			const next = mutator(memory.map(r => ({ ...r })));
+			memory = next;
+			await writeAtomic({ version: RECONCILIATION_STORE_VERSION, sessionId, records: memory });
+		};
+		const pending = chain.then(run, run);
+		chain = pending.then(
+			() => undefined,
+			() => undefined,
+		);
+		await pending;
+	};
+
+	const deleteStore = async (): Promise<void> => {
+		memory = [];
+		if (!filePath) return;
+		await fileFs.unlink(filePath).catch(error => {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		});
+	};
+
+	return {
+		path: filePath,
+		sessionId,
+		transact,
+		load,
+		snapshot: () => memory.map(r => ({ ...r })),
+		delete: deleteStore,
+	};
+}

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

@@ -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":

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

@@ -19,7 +19,7 @@ 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;

package/src/sdk/host/host.ts

@@ -9,6 +9,13 @@ 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;
@@ -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;

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

@@ -46,6 +46,11 @@ export interface SessionSurface {
 	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. */
@@ -127,6 +132,7 @@ const names = [
 	"runtime.jobs.list",
 	"turn.prompt_status",
 	"models.profiles.list",
+	"skill.invoke_status",
 ];
 
 export class QueryHandlers {
@@ -156,6 +162,7 @@ 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.");
@@ -517,6 +524,54 @@ export class QueryHandlers {
 		return { id: request.id, ok: true, page };
 	}
 
+	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.");