@gajae-code/coding-agent 0.13.0 → 0.13.2

package/src/sdk/host/websocket-transport.lifecycle.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { SdkClient } from "../client/client";
 import { SessionSdkSessionRuntime, type SessionSdkTransport } from "./session-runtime";
 import { createSdkWebSocketTransport, type SdkWebSocketTransportDependencies } from "./websocket-transport";
 
@@ -39,11 +40,117 @@ describe("SDK WebSocket transport lifecycle", () => {
 		const endpoints = await Promise.all([transport.start(), transport.start(), transport.start()]);
 		expect(new Set(endpoints.map(endpoint => endpoint.url)).size).toBe(1);
 		const endpointPath = path.join(stateRoot, "sdk", "concurrent-start.json");
-		expect(JSON.parse(await fs.readFile(endpointPath, "utf8")).url).toBe(endpoints[0]?.url);
+		expect(JSON.parse(await fs.readFile(endpointPath, "utf8"))).toMatchObject({
+			sessionId: "concurrent-start",
+			url: endpoints[0]?.url,
+		});
 		await transport.stop();
 		await expect(fs.stat(endpointPath)).rejects.toMatchObject({ code: "ENOENT" });
 		await fs.rm(stateRoot, { recursive: true, force: true });
 	});
+	test("publishes a complete mode-600 endpoint through one atomic rename", async () => {
+		const stateRoot = await tempStateRoot();
+		const endpointPath = path.join(stateRoot, "sdk", "atomic-publication.json");
+		const renameEntered = Promise.withResolvers<void>();
+		const releaseRename = Promise.withResolvers<void>();
+		const transport = await createSdkWebSocketTransport({
+			sessionId: "atomic-publication",
+			stateRoot,
+			token: "secret-token",
+			filesystem: {
+				mkdir: fs.mkdir,
+				writeFile: fs.writeFile,
+				chmod: fs.chmod,
+				rename: async (from, to) => {
+					expect(to).toBe(endpointPath);
+					expect((await fs.stat(from)).mode & 0o777).toBe(0o600);
+					expect(JSON.parse(await fs.readFile(from, "utf8"))).toMatchObject({
+						sessionId: "atomic-publication",
+						token: "secret-token",
+					});
+					renameEntered.resolve();
+					await releaseRename.promise;
+					await fs.rename(from, to);
+				},
+				readFile: fs.readFile,
+				rm: fs.rm,
+			},
+		});
+		const start = transport.start();
+		try {
+			await renameEntered.promise;
+			await expect(fs.stat(endpointPath)).rejects.toMatchObject({ code: "ENOENT" });
+			expect((await fs.readdir(path.dirname(endpointPath))).filter(file => file.endsWith(".tmp"))).toHaveLength(1);
+			releaseRename.resolve();
+			await start;
+			expect(JSON.parse(await fs.readFile(endpointPath, "utf8"))).toMatchObject({
+				sessionId: "atomic-publication",
+				token: "secret-token",
+			});
+		} finally {
+			releaseRename.resolve();
+			await start.catch(() => undefined);
+			await transport.stop().catch(() => undefined);
+			await fs.rm(stateRoot, { recursive: true, force: true });
+		}
+	});
+	test("six isolated roots publish unique endpoints that accept metadata and prompt controls", async () => {
+		const roots = await Promise.all(Array.from({ length: 6 }, () => tempStateRoot()));
+		const transports = await Promise.all(
+			roots.map((stateRoot, index) =>
+				createSdkWebSocketTransport({
+					sessionId: `isolated-lane-${index + 1}`,
+					stateRoot,
+					token: `token-${index + 1}`,
+				}),
+			),
+		);
+		const frameDisposers = transports.map(transport =>
+			transport.onFrame((connectionId, frame) => {
+				if (frame.type !== "query_request" && frame.type !== "control_request") return;
+				void transport.sendFrame(connectionId, {
+					type: frame.type === "query_request" ? "query_response" : "control_response",
+					id: frame.id,
+					ok: true,
+					result: frame.type === "query_request" ? { sessionId: transport.sessionId } : { accepted: true },
+				});
+			}),
+		);
+		const clients: SdkClient[] = [];
+		try {
+			const endpoints = await Promise.all(transports.map(transport => transport.start()));
+			expect(new Set(endpoints.map(endpoint => endpoint.url)).size).toBe(6);
+			await Promise.all(
+				roots.map(async (stateRoot, index) => {
+					const sessionId = `isolated-lane-${index + 1}`;
+					const record = JSON.parse(await fs.readFile(path.join(stateRoot, "sdk", `${sessionId}.json`), "utf8"));
+					expect(record).toMatchObject({ sessionId, url: endpoints[index]?.url, token: `token-${index + 1}` });
+					await probeWebSocketEndpoint(endpoints[index]!.url, `token-${index + 1}`);
+				}),
+			);
+			const connected = await Promise.all(
+				endpoints.map((endpoint, index) => SdkClient.connect(endpoint.url, `token-${index + 1}`)),
+			);
+			clients.push(...connected);
+			await Promise.all(
+				connected.flatMap((client, index) => [
+					expect(client.query("session.metadata")).resolves.toMatchObject({
+						ok: true,
+						result: { sessionId: `isolated-lane-${index + 1}` },
+					}),
+					expect(client.control("turn.prompt", { text: `probe lane ${index + 1}` })).resolves.toMatchObject({
+						ok: true,
+						result: { accepted: true },
+					}),
+				]),
+			);
+		} finally {
+			await Promise.all(clients.map(client => client.close()));
+			for (const dispose of frameDisposers) dispose?.();
+			await Promise.all(transports.map(transport => transport.stop().catch(() => undefined)));
+			await Promise.all(roots.map(root => fs.rm(root, { recursive: true, force: true })));
+		}
+	});
 
 	test("start waits for a pending stop before publishing a probeable replacement endpoint", async () => {
 		const stateRoot = await tempStateRoot();
@@ -80,7 +187,7 @@ describe("SDK WebSocket transport lifecycle", () => {
 		try {
 			const first = await transport.start();
 			const stopPromise = transport.stop();
-			await Bun.sleep(0);
+			for (let attempt = 0; attempt < 100 && !stopEntered; attempt += 1) await Bun.sleep(1);
 			expect(stopEntered).toBe(true);
 			let secondResolved = false;
 			const secondPromise = transport.start().then(endpoint => {
@@ -120,6 +227,8 @@ describe("SDK WebSocket transport lifecycle", () => {
 				chmod: async () => {
 					throw Object.assign(new Error("chmod injected failure"), { code: "EACCES" });
 				},
+				rename: real.rename,
+				readFile: real.readFile,
 				rm: real.rm,
 			},
 		};
@@ -137,6 +246,85 @@ describe("SDK WebSocket transport lifecycle", () => {
 		await fs.rm(stateRoot, { recursive: true, force: true });
 	});
 
+	test("failed duplicate startup preserves a canonical endpoint it did not publish", async () => {
+		const stateRoot = await tempStateRoot();
+		const endpointPath = path.join(stateRoot, "sdk", "duplicate-cleanup.json");
+		await fs.mkdir(path.dirname(endpointPath), { recursive: true });
+		const canonicalEndpoint = JSON.stringify({
+			version: 1,
+			sessionId: "duplicate-cleanup",
+			url: "ws://127.0.0.1:12345/",
+			token: "canonical-token",
+			pid: process.pid,
+		});
+		await fs.writeFile(endpointPath, canonicalEndpoint, { mode: 0o600 });
+		const transport = await createSdkWebSocketTransport({
+			sessionId: "duplicate-cleanup",
+			stateRoot,
+			token: "duplicate-token",
+			filesystem: {
+				mkdir: fs.mkdir,
+				writeFile: async () => {
+					throw Object.assign(new Error("duplicate startup failed"), { code: "EIO" });
+				},
+				chmod: fs.chmod,
+				rename: fs.rename,
+				readFile: fs.readFile,
+				rm: fs.rm,
+			},
+		});
+		try {
+			await expect(transport.start()).rejects.toMatchObject({ code: "endpoint_write_failed" });
+			expect(await fs.readFile(endpointPath, "utf8")).toBe(canonicalEndpoint);
+		} finally {
+			await transport.stop();
+			await fs.rm(stateRoot, { recursive: true, force: true });
+		}
+	});
+
+	test("serializes a successor publication behind an owner endpoint cleanup", async () => {
+		const stateRoot = await tempStateRoot();
+		const sessionId = "serialized-cleanup";
+		const endpointPath = path.join(stateRoot, "sdk", `${sessionId}.json`);
+		const readEntered = Promise.withResolvers<void>();
+		const releaseRead = Promise.withResolvers<void>();
+		const owner = await createSdkWebSocketTransport({
+			sessionId,
+			stateRoot,
+			token: "owner-token",
+			filesystem: {
+				mkdir: fs.mkdir,
+				writeFile: fs.writeFile,
+				chmod: fs.chmod,
+				rename: fs.rename,
+				readFile: (async (...args: Parameters<typeof fs.readFile>) => {
+					readEntered.resolve();
+					await releaseRead.promise;
+					return await fs.readFile(...args);
+				}) as typeof fs.readFile,
+				rm: fs.rm,
+			},
+		});
+		const successor = await createSdkWebSocketTransport({ sessionId, stateRoot, token: "successor-token" });
+		try {
+			await owner.start();
+			const stop = owner.stop();
+			await readEntered.promise;
+			const start = successor.start();
+			await Bun.sleep(20);
+			expect(JSON.parse(await fs.readFile(endpointPath, "utf8"))).toMatchObject({ token: "owner-token" });
+			releaseRead.resolve();
+			await stop;
+			await start;
+			expect(JSON.parse(await fs.readFile(endpointPath, "utf8"))).toMatchObject({ token: "successor-token" });
+		} finally {
+			releaseRead.resolve();
+			await owner.stop().catch(() => undefined);
+			await successor.stop().catch(() => undefined);
+			await fs.rm(stateRoot, { recursive: true, force: true });
+		}
+	});
+
 	test("endpoint removal failures are typed and do not prevent server release", async () => {
 		const stateRoot = await tempStateRoot();
 		let rmCalls = 0;
@@ -146,6 +334,8 @@ describe("SDK WebSocket transport lifecycle", () => {
 				mkdir: real.mkdir,
 				writeFile: real.writeFile,
 				chmod: real.chmod,
+				rename: real.rename,
+				readFile: real.readFile,
 				rm: async (...args: Parameters<typeof real.rm>) => {
 					rmCalls += 1;
 					if (rmCalls === 1) throw Object.assign(new Error("rm injected failure"), { code: "EIO" });

package/src/sdk/host/websocket-transport.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { withFileLock } from "../../config/file-lock";
 import type { SessionSdkTransport } from "./session-runtime";
 import type { SdkFrame } from "./types";
 
@@ -8,7 +9,7 @@ type SocketData = { connectionId: string };
 type Socket = { readonly data: SocketData; send(message: string): void; close(): void; terminate?(): void };
 
 export interface SdkWebSocketTransportDependencies {
-	readonly filesystem?: Pick<typeof fs, "mkdir" | "writeFile" | "chmod" | "rm">;
+	readonly filesystem?: Pick<typeof fs, "mkdir" | "writeFile" | "chmod" | "rename" | "readFile" | "rm">;
 	readonly serve?: typeof Bun.serve;
 }
 type SdkServer = ReturnType<typeof Bun.serve<SocketData>>;
@@ -70,6 +71,7 @@ export async function createSdkWebSocketTransport(
 	let started = false;
 	let startPromise: Promise<{ url: string }> | undefined;
 	let stopPromise: Promise<void> | undefined;
+	let publishedEndpoint: string | undefined;
 
 	const stopServer = async (current: SdkServer): Promise<void> => {
 		try {
@@ -96,10 +98,18 @@ export async function createSdkWebSocketTransport(
 		if (current) await stopServer(current);
 	};
 
-	const removeEndpoint = async (): Promise<void> => {
+	const removePublishedEndpoint = async (): Promise<void> => {
+		if (publishedEndpoint === undefined) return;
 		try {
+			const endpoint = await filesystem.readFile(endpointFile, "utf8");
+			if (endpoint !== publishedEndpoint) return;
 			await filesystem.rm(endpointFile, { force: true });
+			publishedEndpoint = undefined;
 		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				publishedEndpoint = undefined;
+				return;
+			}
 			throw asLifecycleError("endpoint_remove_failed", "SDK endpoint file removal failed.", error);
 		}
 	};
@@ -140,6 +150,7 @@ export async function createSdkWebSocketTransport(
 			if (started && server) return { url: endpointUrl(server) };
 
 			const pending = (async (): Promise<{ url: string }> => {
+				const tempEndpointFile = `${endpointFile}.${randomUUID()}.tmp`;
 				let localServer: SdkServer | undefined;
 				const failures: unknown[] = [];
 				try {
@@ -195,26 +206,39 @@ export async function createSdkWebSocketTransport(
 					});
 					server = localServer;
 					const url = endpointUrl(localServer);
-					try {
-						await filesystem.writeFile(
-							endpointFile,
-							JSON.stringify({
-								version: 1,
-								sessionId: input.sessionId,
-								url,
-								token: input.token,
-								pid: process.pid,
-							}),
-							"utf8",
-						);
-					} catch (error) {
-						throw asLifecycleError("endpoint_write_failed", "SDK endpoint file publication failed.", error);
-					}
-					try {
-						await filesystem.chmod(endpointFile, 0o600);
-					} catch (error) {
-						throw asLifecycleError("endpoint_chmod_failed", "SDK endpoint file permission update failed.", error);
-					}
+					const endpoint = JSON.stringify({
+						version: 1,
+						sessionId: input.sessionId,
+						url,
+						token: input.token,
+						pid: process.pid,
+					});
+					await withFileLock(endpointFile, async () => {
+						try {
+							await filesystem.writeFile(tempEndpointFile, endpoint, {
+								encoding: "utf8",
+								mode: 0o600,
+								flag: "wx",
+							});
+						} catch (error) {
+							throw asLifecycleError("endpoint_write_failed", "SDK endpoint file publication failed.", error);
+						}
+						try {
+							await filesystem.chmod(tempEndpointFile, 0o600);
+						} catch (error) {
+							throw asLifecycleError(
+								"endpoint_chmod_failed",
+								"SDK endpoint file permission update failed.",
+								error,
+							);
+						}
+						try {
+							await filesystem.rename(tempEndpointFile, endpointFile);
+						} catch (error) {
+							throw asLifecycleError("endpoint_write_failed", "SDK endpoint file publication failed.", error);
+						}
+						publishedEndpoint = endpoint;
+					});
 					started = true;
 					return { url };
 				} catch (error) {
@@ -227,9 +251,11 @@ export async function createSdkWebSocketTransport(
 						failures.push(cleanupError);
 					}
 					try {
-						await removeEndpoint();
+						await filesystem.rm(tempEndpointFile, { force: true });
 					} catch (cleanupError) {
-						failures.push(cleanupError);
+						failures.push(
+							asLifecycleError("endpoint_remove_failed", "SDK endpoint temp file removal failed.", cleanupError),
+						);
 					}
 					started = false;
 					server = undefined;
@@ -255,12 +281,10 @@ export async function createSdkWebSocketTransport(
 				if (startPromise) await startPromise.catch(() => undefined);
 				const failures: unknown[] = [];
 				try {
-					await closeServer();
-				} catch (error) {
-					failures.push(error);
-				}
-				try {
-					await removeEndpoint();
+					await withFileLock(endpointFile, async () => {
+						await closeServer();
+						await removePublishedEndpoint();
+					});
 				} catch (error) {
 					failures.push(error);
 				}

package/src/sdk/index.ts

@@ -25,3 +25,4 @@ export * from "./prompt-status";
 export type { ActiveProviderConnectionKind, ActiveProviderDescriptor } from "./providers";
 export * from "./session";
 export * from "./session-directory";
+export * from "./turn-result";

package/src/sdk/mcp/server.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import { getAgentDir } from "@gajae-code/utils";
 import { ensureBroker } from "../broker/ensure";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
-import { SdkClient, SdkClientError } from "../client/client";
+import { SdkClient, SdkClientError, type SdkSentRecord } from "../client/client";
 import { readSdkBrokerDiscovery, SdkDiscoveryError } from "../client/discovery";
 import { validateAdapterControl, validateAdapterSecretFields } from "../protocol/adapter-validation";
 import { adapterDispositionError, findOperation } from "../protocol/operation-registry";
@@ -327,11 +327,24 @@ export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
 				const broker = await readSdkBrokerDiscovery(agentDir);
 				if (!broker) return { ok: false, error: { code: "not_found", message: "SDK broker not found" } };
 				client = await connect(broker.url, broker.token);
-				const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
-				const response = await client.global(operation, input, {
-					idempotencyKey,
-					...(timeoutMs === undefined ? {} : { timeoutMs }),
-				});
+				let response: unknown;
+				try {
+					const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
+					response = await client.global(operation, input, {
+						idempotencyKey,
+						...(timeoutMs === undefined ? {} : { timeoutMs }),
+					});
+				} catch (error) {
+					if (
+						isLifecycleOperation(operation) &&
+						error instanceof SdkClientError &&
+						error.code === "uncertain_after_send" &&
+						error.details &&
+						typeof error.details === "object"
+					)
+						response = await client.lookupLifecycle(error.details as SdkSentRecord);
+					else throw error;
+				}
 				return isLifecycleOperation(operation) ? redactLifecycleCredentials(response) : response;
 			} catch (error) {
 				return resultError(error);

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

@@ -1534,7 +1534,7 @@
 		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
 		"sourceKind": "registry",
 		"decision": "include",
-		"sdkId": "turn.prompt_status",
+		"sdkId": "turn.result",
 		"adapterMappings": {
 			"telegram": "prohibited",
 			"discord": "prohibited",

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

@@ -155,15 +155,10 @@ 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.",
-	],
+	["turn.result", "Read the authoritative durable result of a submitted turn 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.",
-	],
+	["skill.invoke_status", "Legacy alias for the authoritative turn result query."],
+
 	["providers.list/active", "List active providers."],
 	["session.checkpoint", "Resolve a durable transcript checkpoint into a connection-owned replay cursor."],
 ] as const;
@@ -240,6 +235,7 @@ 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", "Q30"].includes(id))
 		return "retained_revision";
+
 	if (id === "Q24") return "content_addressed";
 	return "scalar_snapshot";
 }
@@ -306,10 +302,10 @@ export const OPERATIONS: readonly Operation[] = [
 			description,
 			idempotency: "idempotent" as const,
 			errorCodes:
-				id === "Q27"
-					? ["invalid_request", "resource_gone", "model_profile_registry_error"]
-					: id === "Q29"
-						? ["invalid_request", "resource_gone", "internal"]
+				id === "Q29"
+					? ["invalid_request", "resource_gone", "internal"]
+					: id === "Q27"
+						? ["invalid_request", "resource_gone", "model_profile_registry_error"]
 						: ["invalid_request", "resource_gone"],
 			continuityClass: queryContinuityClass(id),
 			adapterDispositions: queryDisposition(id),

package/src/sdk/session.ts

@@ -116,8 +116,7 @@ import {
 } from "../sdk/bus/config";
 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";
@@ -1710,7 +1709,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				// (serviceTier === undefined) would be resurrected to the startup value.
 				return agent ? agent.serviceTier : initialServiceTier;
 			},
-			isFastForSubagentProvider: provider => session?.isFastForSubagentProvider(provider) ?? false,
+			isFastForSubagentProvider: (provider, supportsServiceTier) =>
+				session?.isFastForSubagentProvider(provider, supportsServiceTier) ?? false,
 			getAgentId: () => resolvedAgentId,
 			bashAllowedPrefixes: options.bashAllowedPrefixes,
 			bashRestrictionProfile: options.bashRestrictionProfile,
@@ -2119,7 +2119,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			shouldHostSdk(notificationCfg, isTopLevelSdkSession) && (options.sdkHostModeSupported ?? true);
 		const notificationAdapterService = createLazyService({
 			id: "sdk.notifications.adapters",
-			enabled: () => notificationsExtensionEligible,
+			enabled: () => notificationsExtensionEligible || sdkHostEligible,
 			initialize: async () => ({
 				value: (await import("../sdk/bus")).createNotificationsExtension,
 			}),
@@ -2130,7 +2130,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					if (lifecycleStartupCapability) attachLifecycleStartupCapability(api, lifecycleStartupCapability);
 					if (lifecycleStartupCapability && process.env.GJC_SDK_TEST_FACTORY_FAILURE === cwd)
 						throw new Error(process.env.GJC_SDK_TEST_FACTORY_SECRET ?? "Lifecycle factory test failure.");
-					if (notificationsExtensionEligible) {
+					if (notificationsExtensionEligible || sdkHostEligible) {
 						const createNotificationsExtension = await notificationAdapterService.get("session-extension");
 						createNotificationsExtension(api, {
 							settings,
@@ -2148,15 +2148,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 								return { replyText };
 							},
 						});
-					} else if (sdkHostEligible) {
-						registerSdkOnlyNotificationCommand(api);
-						createSdkSessionRuntimeExtension(api, {
-							agentDir,
-							brokerRegistrationRequired: lifecycleStartupCapability !== undefined,
-							createTransport: input => createSdkWebSocketTransport(input),
-							settings,
-							configOverrides: new Map(),
-						});
 					}
 				} catch (error) {
 					lifecycleStartupCapability?.settleFailure(

package/src/sdk/turn-result.ts

@@ -0,0 +1,53 @@
+/** Canonical durable turn-result DTOs. */
+export const TURN_RESULT_VERSION = 1 as const;
+export const TURN_RESULT_CONTENT_MAX_BYTES = 16_384;
+export const TURN_RESULT_ERROR_MESSAGE_MAX_LENGTH = 512;
+export type TurnResultSelector =
+	| { kind: "prompt" | "skill"; clientRef: string }
+	| { kind: "prompt" | "skill"; commandId: string; turnId: string };
+export type TurnResultStatus = "unknown" | "accepted" | "in_flight" | "terminal_ok" | "failed";
+export interface TurnResultContent {
+	version: typeof TURN_RESULT_VERSION;
+	type: "text";
+	text: string;
+	byteLength: number;
+	truncated: boolean;
+}
+export interface TurnResultError {
+	code: string;
+	message: string;
+}
+export interface TurnResultPage {
+	status: TurnResultStatus;
+	kind?: "prompt" | "skill";
+	commandId?: string;
+	turnId?: string;
+	clientRef?: string;
+	acceptedAt?: number;
+	startedAt?: number;
+	terminalAt?: number;
+	content?: TurnResultContent;
+	error?: TurnResultError;
+}
+export function sanitizeTurnResultContent(text: unknown): TurnResultContent | undefined {
+	if (typeof text !== "string") return undefined;
+	const bytes = new TextEncoder().encode(text);
+	const truncated = bytes.length > TURN_RESULT_CONTENT_MAX_BYTES;
+	let bounded = text;
+	if (truncated) {
+		let end = 0;
+		for (const character of text) {
+			const next = end + new TextEncoder().encode(character).length;
+			if (next > TURN_RESULT_CONTENT_MAX_BYTES) break;
+			end = next;
+		}
+		bounded = new TextDecoder().decode(bytes.slice(0, end));
+	}
+	return {
+		version: TURN_RESULT_VERSION,
+		type: "text",
+		text: bounded,
+		byteLength: new TextEncoder().encode(bounded).length,
+		truncated,
+	};
+}