@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/sdk/host/surface-policy.ts

@@ -16,6 +16,17 @@ export function hasSdkWorkflowGateCapability(workflowGate: unknown): boolean {
 const UNINSTALLED_CONTROL_OPERATIONS = new Set(["auth.login", "host_tools.register", "host_uri.register"]);
 /** Advertised only when the context carries a real durable workflow-gate bridge. */
 const WORKFLOW_GATE_CONTROL_OPERATIONS = new Set(["workflow.gate_answer", "workflow.plan_approve"]);
+/** Lifecycle mutations are Broker-owned and never advertised on generic session controls. */
+const BROKER_LIFECYCLE_CONTROL_OPERATIONS = new Set([
+	"session.new",
+	"session.fork",
+	"session.resume",
+	"session.switch",
+	"session.branch",
+	"session.handoff",
+	"session.close",
+	"session.delete",
+]);
 
 const CONTROL_BINDINGS: Readonly<Record<string, string | undefined>> = {
 	"model.cycle": "cycleModel",
@@ -34,14 +45,7 @@ const CONTROL_BINDINGS: Readonly<Record<string, string | undefined>> = {
 	"retry.abort": "sdkControl",
 	"bash.execute": "sdkControl",
 	"bash.abort": "sdkControl",
-	"session.new": "sdkControl",
-	"session.fork": "sdkControl",
-	"session.resume": "sdkControl",
-	"session.close": "sdkControl",
-	"session.switch": "sdkControl",
-	"session.branch": "sdkControl",
 	"session.rename": "sdkControl",
-	"session.handoff": "sdkControl",
 	"session.export_html": "sdkControl",
 	"runtime.reload": "sdkControl",
 	"service_tier.set": "sdkControl",
@@ -49,7 +53,6 @@ const CONTROL_BINDINGS: Readonly<Record<string, string | undefined>> = {
 	"queue.message.move": "sdkControl",
 	"queue.message.update": "sdkControl",
 	"extension.set_enabled": "sdkControl",
-	"session.delete": "sdkControl",
 	"session.cwd.move": "sdkControl",
 	"retry.last": "sdkControl",
 	"retry.now": "sdkControl",
@@ -90,6 +93,7 @@ export function createSdkSurfacePolicy(options: SdkSurfacePolicyOptions): SdkSur
 			OPERATIONS.filter(
 				operation =>
 					operation.kind === kind &&
+					!BROKER_LIFECYCLE_CONTROL_OPERATIONS.has(operation.sdkId) &&
 					!UNINSTALLED_CONTROL_OPERATIONS.has(operation.sdkId) &&
 					(!WORKFLOW_GATE_CONTROL_OPERATIONS.has(operation.sdkId) || options.workflowGateAvailable) &&
 					(!required[operation.sdkId] || hasBinding(required[operation.sdkId]!)),

package/src/sdk/host/types.ts

@@ -19,7 +19,7 @@ export interface HostEndpointAdapters {
 	sessionId: string;
 	stateRoot: string;
 	token: string;
-	sendFrame: (connectionId: string, frame: SdkFrame) => void | Promise<void>;
+	sendFrame: (connectionId: string, frame: SdkFrame) => "written" | "dropped" | Promise<"written" | "dropped">;
 	onFrame: (handler: (connectionId: string, frame: SdkFrame) => void) => undefined | (() => void);
 }
 

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

@@ -61,6 +61,7 @@ describe("SDK WebSocket transport lifecycle", () => {
 				mkdir: fs.mkdir,
 				writeFile: fs.writeFile,
 				chmod: fs.chmod,
+				stat: fs.stat,
 				rename: async (from, to) => {
 					expect(to).toBe(endpointPath);
 					expect((await fs.stat(from)).mode & 0o777).toBe(0o600);
@@ -72,7 +73,6 @@ describe("SDK WebSocket transport lifecycle", () => {
 					await releaseRename.promise;
 					await fs.rename(from, to);
 				},
-				readFile: fs.readFile,
 				rm: fs.rm,
 			},
 		});
@@ -227,8 +227,8 @@ describe("SDK WebSocket transport lifecycle", () => {
 				chmod: async () => {
 					throw Object.assign(new Error("chmod injected failure"), { code: "EACCES" });
 				},
+				stat: real.stat,
 				rename: real.rename,
-				readFile: real.readFile,
 				rm: real.rm,
 			},
 		};
@@ -268,8 +268,8 @@ describe("SDK WebSocket transport lifecycle", () => {
 					throw Object.assign(new Error("duplicate startup failed"), { code: "EIO" });
 				},
 				chmod: fs.chmod,
+				stat: fs.stat,
 				rename: fs.rename,
-				readFile: fs.readFile,
 				rm: fs.rm,
 			},
 		});
@@ -282,76 +282,48 @@ describe("SDK WebSocket transport lifecycle", () => {
 		}
 	});
 
-	test("serializes a successor publication behind an owner endpoint cleanup", async () => {
+	test("retains a replacement endpoint while concurrent readers finish", 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,
+		const endpointPath = path.join(stateRoot, "sdk", "replacement.json");
+		const transport = await createSdkWebSocketTransport({
+			sessionId: "replacement",
 			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,
-			},
+			token: "token",
 		});
-		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" });
+			await transport.start();
+			const replacement = JSON.stringify({ sessionId: "replacement", url: "ws://127.0.0.1:1", token: "successor" });
+			const displaced = `${endpointPath}.displaced`;
+			await fs.rename(endpointPath, displaced);
+			await fs.writeFile(endpointPath, replacement, { mode: 0o600 });
+			const readers = Promise.all(Array.from({ length: 16 }, async () => await fs.readFile(endpointPath, "utf8")));
+			await transport.stop();
+			expect(await readers).toEqual(Array(16).fill(replacement));
+			expect(await fs.readFile(endpointPath, "utf8")).toBe(replacement);
+			await fs.rm(displaced, { force: true });
 		} finally {
-			releaseRead.resolve();
-			await owner.stop().catch(() => undefined);
-			await successor.stop().catch(() => undefined);
+			await transport.stop().catch(() => undefined);
 			await fs.rm(stateRoot, { recursive: true, force: true });
 		}
 	});
 
-	test("endpoint removal failures are typed and do not prevent server release", async () => {
+	test("endpoint identity uncertainty is typed and retains the endpoint", async () => {
 		const stateRoot = await tempStateRoot();
-		let rmCalls = 0;
-		const real = fs;
-		const dependencies: SdkWebSocketTransportDependencies = {
-			filesystem: {
-				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" });
-					return await real.rm(...args);
-				},
-			},
-		};
+		const endpointPath = path.join(stateRoot, "sdk", "identity-uncertain.json");
 		const transport = await createSdkWebSocketTransport({
-			sessionId: "rm-failure",
+			sessionId: "identity-uncertain",
 			stateRoot,
 			token: "token",
-			...dependencies,
 		});
-		await transport.start();
-		await expect(transport.stop()).rejects.toMatchObject({ code: "endpoint_remove_failed" });
-		await fs.rm(stateRoot, { recursive: true, force: true });
+		try {
+			await transport.start();
+			await fs.rm(endpointPath);
+			await fs.mkdir(endpointPath);
+			await expect(transport.stop()).rejects.toMatchObject({ code: "endpoint_remove_failed" });
+			await expect(fs.stat(endpointPath)).resolves.toBeDefined();
+		} finally {
+			await fs.rm(stateRoot, { recursive: true, force: true });
+		}
 	});
 
 	test("runtime stop releases the transport even when host stop fails", async () => {

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

@@ -1,7 +1,7 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { withFileLock } from "../../config/file-lock";
+import { exactUnlink, type NativeExactFileIdentity } from "@gajae-code/natives";
 import type { SessionSdkTransport } from "./session-runtime";
 import type { SdkFrame } from "./types";
 
@@ -9,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" | "rename" | "readFile" | "rm">;
+	readonly filesystem?: Pick<typeof fs, "mkdir" | "writeFile" | "chmod" | "rename" | "rm" | "stat">;
 	readonly serve?: typeof Bun.serve;
 }
 type SdkServer = ReturnType<typeof Bun.serve<SocketData>>;
@@ -68,10 +68,10 @@ export async function createSdkWebSocketTransport(
 	let server: SdkServer | undefined;
 	const sockets = new Map<string, Socket>();
 	const endpointFile = path.join(input.stateRoot, "sdk", `${input.sessionId}.json`);
+	let endpointIdentity: NativeExactFileIdentity | undefined;
 	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 {
@@ -98,18 +98,34 @@ export async function createSdkWebSocketTransport(
 		if (current) await stopServer(current);
 	};
 
-	const removePublishedEndpoint = async (): Promise<void> => {
-		if (publishedEndpoint === undefined) return;
+	const removeEndpoint = async (): Promise<void> => {
+		if (!endpointIdentity) 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;
+			const removal = exactUnlink(endpointFile, endpointIdentity);
+			if (removal.ok) {
+				endpointIdentity = undefined;
+				return;
+			}
+			if (
+				removal.code === "cleanup_pending" &&
+				removal.payloadDurable === true &&
+				!removal.retainedSuccessorPath &&
+				!removal.retainedUnknownPath
+			) {
+				endpointIdentity = undefined;
 				return;
 			}
+			if (removal.retainedSuccessorPath) return;
+			if (removal.code === "identity_mismatch") {
+				try {
+					if ((await filesystem.stat(endpointFile, { bigint: true })).isFile()) return;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+					throw error;
+				}
+			}
+			throw new Error(`SDK endpoint identity-bound removal failed: ${removal.code ?? "unknown"}`);
+		} catch (error) {
 			throw asLifecycleError("endpoint_remove_failed", "SDK endpoint file removal failed.", error);
 		}
 	};
@@ -151,6 +167,8 @@ export async function createSdkWebSocketTransport(
 
 			const pending = (async (): Promise<{ url: string }> => {
 				const tempEndpointFile = `${endpointFile}.${randomUUID()}.tmp`;
+				const endpointQuarantineName = `.gjc-delete-endpoint-${randomUUID()}-${path.basename(endpointFile)}`;
+				let endpointSource: string | undefined;
 				let localServer: SdkServer | undefined;
 				const failures: unknown[] = [];
 				try {
@@ -206,39 +224,49 @@ export async function createSdkWebSocketTransport(
 					});
 					server = localServer;
 					const url = endpointUrl(localServer);
-					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;
-					});
+					try {
+						endpointSource = JSON.stringify({
+							version: 1,
+							sessionId: input.sessionId,
+							url,
+							token: input.token,
+							pid: process.pid,
+						});
+						await filesystem.writeFile(tempEndpointFile, endpointSource, {
+							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);
+					}
+					let publishedEndpointIdentity: NativeExactFileIdentity;
+					try {
+						const metadata = await filesystem.stat(tempEndpointFile, { bigint: true });
+						if (endpointSource === undefined) throw new Error("SDK endpoint source was not prepared.");
+						publishedEndpointIdentity = {
+							dev: metadata.dev,
+							ino: metadata.ino,
+							nlink: metadata.nlink,
+							size: metadata.size,
+							mtimeNs: metadata.mtimeNs,
+							sha256: createHash("sha256").update(endpointSource).digest("hex"),
+							quarantineName: endpointQuarantineName,
+						};
+					} catch (error) {
+						throw asLifecycleError("endpoint_write_failed", "SDK endpoint file identity capture failed.", error);
+					}
+					try {
+						await filesystem.rename(tempEndpointFile, endpointFile);
+					} catch (error) {
+						throw asLifecycleError("endpoint_write_failed", "SDK endpoint file publication failed.", error);
+					}
+					endpointIdentity = publishedEndpointIdentity;
 					started = true;
 					return { url };
 				} catch (error) {
@@ -257,6 +285,11 @@ export async function createSdkWebSocketTransport(
 							asLifecycleError("endpoint_remove_failed", "SDK endpoint temp file removal failed.", cleanupError),
 						);
 					}
+					try {
+						await removeEndpoint();
+					} catch (cleanupError) {
+						failures.push(cleanupError);
+					}
 					started = false;
 					server = undefined;
 					const combined = combineLifecycleErrors(
@@ -281,10 +314,12 @@ export async function createSdkWebSocketTransport(
 				if (startPromise) await startPromise.catch(() => undefined);
 				const failures: unknown[] = [];
 				try {
-					await withFileLock(endpointFile, async () => {
-						await closeServer();
-						await removePublishedEndpoint();
-					});
+					await closeServer();
+				} catch (error) {
+					failures.push(error);
+				}
+				try {
+					await removeEndpoint();
 				} catch (error) {
 					failures.push(error);
 				}

package/src/sdk/index.ts

@@ -10,8 +10,8 @@ export {
 	UnknownModelProfileError,
 } from "../config/model-profile-contract";
 export * as bus from "./bus";
-export * from "./client";
 export * as host from "./host";
+export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";
 export type {
 	Q10CurrentThinkingLevel,
@@ -23,6 +23,7 @@ export type {
 } from "./models";
 export * from "./prompt-status";
 export type { ActiveProviderConnectionKind, ActiveProviderDescriptor } from "./providers";
+export * as router from "./router";
 export * from "./session";
 export * from "./session-directory";
 export * from "./turn-result";

package/src/sdk/lifecycle/broker-client.ts

@@ -0,0 +1,53 @@
+import { logger } from "@gajae-code/utils";
+import { ensureBroker } from "../broker/ensure";
+import { SdkClient } from "../client/client";
+import { readSdkBrokerDiscovery } from "../client/discovery";
+import {
+	type SessionLifecycleClient,
+	type SessionLifecycleClientRequestOptions,
+	type SessionLifecycleOperation,
+	SessionLifecycleService,
+} from "./service";
+
+/** SDK-core Broker client that keeps Broker credentials inside the lifecycle boundary. */
+export class AgentDirSessionLifecycleClient implements SessionLifecycleClient {
+	readonly #agentDir: string;
+
+	constructor(agentDir: string) {
+		this.#agentDir = agentDir;
+	}
+
+	async global(
+		operation: SessionLifecycleOperation,
+		input: Record<string, unknown>,
+		options: SessionLifecycleClientRequestOptions,
+	): Promise<unknown> {
+		await ensureBroker({ agentDir: this.#agentDir });
+		const discovery = await readSdkBrokerDiscovery(this.#agentDir);
+		if (!discovery) throw new Error("SDK broker discovery is unavailable.");
+		const client = await SdkClient.connect(discovery.url, discovery.token, {
+			...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+		});
+		let result: unknown;
+		try {
+			result = await client.global(operation, input, {
+				...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
+				...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+			});
+		} finally {
+			try {
+				await client.close();
+			} catch (error) {
+				logger.warn("SDK lifecycle client cleanup failed", {
+					operation,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+		return result;
+	}
+}
+
+export function createBrokerSessionLifecycleService(agentDir: string): SessionLifecycleService {
+	return new SessionLifecycleService(new AgentDirSessionLifecycleClient(agentDir));
+}