@gajae-code/coding-agent 0.10.2 → 0.11.1

package/src/sdk/broker/discovery.ts

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { processIncarnation } from "./process-incarnation";
+import { assertSupportedStateVersion, SDK_STATE_VERSION } from "./state-version";
+
+export const BROKER_HEARTBEAT_TTL_MS = 15_000;
+export interface BrokerDiscovery {
+	version: typeof SDK_STATE_VERSION;
+	protocolVersion: 3;
+	packageGeneration: string;
+	ownerId: string;
+	pid: number;
+	incarnation: string;
+	host: "127.0.0.1";
+	port: number;
+	url: string;
+	token: string;
+	startedAt: number;
+	heartbeatAt: number;
+}
+export type RedactedBrokerDiscovery = Omit<BrokerDiscovery, "token"> & { token: "[redacted]" };
+export type BrokerDiscoveryWrite = Omit<BrokerDiscovery, "incarnation"> & { incarnation?: string };
+export const brokerDiscoveryPath = (agentDir: string) => path.join(agentDir, "sdk", "broker.json");
+export const newBrokerToken = () => randomBytes(32).toString("hex");
+export const brokerProcessIncarnation = processIncarnation;
+export function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+async function syncFile(file: string): Promise<void> {
+	const handle = await fs.open(file, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+	let handle: fs.FileHandle;
+	try {
+		handle = await fs.open(directory, "r");
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (process.platform === "win32" && (code === "EPERM" || code === "EACCES")) return;
+		throw error;
+	}
+	try {
+		await handle.sync();
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (process.platform !== "win32" || (code !== "EPERM" && code !== "EACCES")) throw error;
+	} finally {
+		await handle.close();
+	}
+}
+export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite): Promise<void> {
+	const incarnation = discovery.incarnation ?? brokerProcessIncarnation(discovery.pid);
+	if (!incarnation) throw new Error(`Broker process incarnation is unavailable for pid ${discovery.pid}.`);
+	const record: BrokerDiscovery = { ...discovery, incarnation };
+	const file = brokerDiscoveryPath(agentDir);
+	const dir = path.dirname(file);
+	await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+	await fs.chmod(dir, 0o700);
+	const temp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		await fs.writeFile(temp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+		await fs.chmod(temp, 0o600);
+		await syncFile(temp);
+		await fs.rename(temp, file);
+		await syncDirectory(dir);
+	} finally {
+		await fs.rm(temp, { force: true });
+	}
+}
+export async function readBrokerDiscovery(
+	agentDir: string,
+	ttlMs = BROKER_HEARTBEAT_TTL_MS,
+): Promise<BrokerDiscovery | null> {
+	try {
+		const raw: unknown = JSON.parse(await fs.readFile(brokerDiscoveryPath(agentDir), "utf8"));
+		if (!raw || typeof raw !== "object") return null;
+		assertSupportedStateVersion(brokerDiscoveryPath(agentDir), raw);
+		const d = raw as BrokerDiscovery;
+		if (
+			d.version !== SDK_STATE_VERSION ||
+			d.protocolVersion !== 3 ||
+			d.host !== "127.0.0.1" ||
+			!d.token ||
+			!Number.isSafeInteger(d.pid) ||
+			d.pid <= 0 ||
+			typeof d.incarnation !== "string" ||
+			d.incarnation.length === 0 ||
+			!Number.isFinite(d.heartbeatAt)
+		)
+			return null;
+		if (!isPidAlive(d.pid)) return null;
+		const incarnation = brokerProcessIncarnation(d.pid);
+		if (!incarnation || incarnation !== d.incarnation || Date.now() - d.heartbeatAt > ttlMs) return null;
+		return d;
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT" || e instanceof SyntaxError) return null;
+		throw e;
+	}
+}
+export function redactBrokerDiscovery(discovery: BrokerDiscovery): RedactedBrokerDiscovery {
+	return { ...discovery, token: "[redacted]" };
+}

package/src/sdk/broker/ensure.ts

@@ -0,0 +1,307 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type BrokerDiscovery, brokerProcessIncarnation, readBrokerDiscovery } from "./discovery";
+import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
+export interface EnsureBrokerSettings {
+	agentDir: string;
+	heartbeatTtlMs?: number;
+	/**
+	 * Environment for the spawned detached broker. Defaults to `process.env`; tests
+	 * that pre-start an isolated broker pass the same sanitized child env so the
+	 * broker and the child that attaches to it share one owned root.
+	 */
+	env?: NodeJS.ProcessEnv;
+}
+
+const DISCOVERY_TIMEOUT_MS = 10_000;
+// Bounded grace windows for reaping a spawned broker on failure, mirroring the
+// owned-process teardown convention (SIGTERM -> grace -> SIGKILL -> hard cap).
+const REAP_GRACEFUL_MS = 2_000;
+const REAP_SIGKILL_CAP_MS = 2_000;
+export interface FixtureBrokerLease {
+	close(): Promise<void>;
+}
+
+export interface StartedFixtureBroker {
+	discovery: BrokerDiscovery;
+	lease: FixtureBrokerLease;
+}
+
+interface BrokerOwner {
+	stop(): Promise<void>;
+	canReuse(discovery: BrokerDiscovery | null): boolean;
+	markReady(discovery: BrokerDiscovery): boolean;
+}
+type EnsureInitiator = "discovery" | "fixture-lease";
+type EnsureOutcome =
+	| { kind: "external-discovery"; discovery: BrokerDiscovery }
+	| { kind: "prior-local-owner"; discovery: BrokerDiscovery; owner: BrokerOwner }
+	| { kind: "local-started-discovery"; discovery: BrokerDiscovery }
+	| { kind: "local-started-fixture"; discovery: BrokerDiscovery; owner: BrokerOwner };
+interface EnsureInFlight {
+	initiator: EnsureInitiator;
+	promise: Promise<EnsureOutcome>;
+	discovery: Promise<BrokerDiscovery>;
+}
+const owners = new Map<string, BrokerOwner>();
+const ensureInFlight = new Map<string, EnsureInFlight>();
+const reapErrorGuards = new WeakSet<ChildProcess>();
+interface ReapTiming {
+	gracefulMs: number;
+	killVerifyMs: number;
+}
+const DEFAULT_REAP_TIMING: ReapTiming = {
+	gracefulMs: REAP_GRACEFUL_MS,
+	killVerifyMs: REAP_SIGKILL_CAP_MS,
+};
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Terminate and reap a detached broker this process spawned, targeting the exact
+ * owned {@link ChildProcess} (never by name). SIGTERM escalates to SIGKILL after
+ * a bounded grace window; a child still alive after SIGKILL is surfaced rather
+ * than silently orphaned. Reaping is idempotent once the child has exited.
+ *
+ * Termination is proven only by an observed exit — an `exit`/`close` event or a
+ * non-null `exitCode`/`signalCode`. A still-live child can emit `error` during
+ * teardown (e.g. a transient signal-delivery failure); that is diagnostic only
+ * and never counts as exit, so the escalation cannot be skipped mid-shutdown.
+ */
+async function reapSpawnedBroker(child: ChildProcess, timing: ReapTiming = DEFAULT_REAP_TIMING): Promise<void> {
+	// A spawn failure (e.g. ENOENT) never created a kernel process: pid is
+	// undefined and there is nothing to signal or await. The `error` event is the
+	// only signal and is diagnostic here — termination trivially holds, so do not
+	// run out the TERM/KILL windows or report a stuck child that never existed.
+	if (child.pid === undefined) return;
+	// Reaping owns repeated teardown diagnostics too. Keep exactly one error
+	// listener for the retained child so a later signal-delivery error cannot
+	// become an unhandled EventEmitter error after the spawn listener is consumed.
+	if (!reapErrorGuards.has(child)) {
+		child.on("error", () => {});
+		reapErrorGuards.add(child);
+	}
+
+	// Awaits an authoritative exit signal, never a transient `error`. Resolves on
+	// an `exit`/`close` event or when the codes are already set; the caller
+	// re-checks the codes after the race, so resolution alone is never proof.
+	const awaitVerifiedExit = (): Promise<void> => {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		if (child.exitCode !== null || child.signalCode !== null) resolve();
+		else {
+			child.once("exit", () => resolve());
+			child.once("close", () => resolve());
+		}
+		return promise;
+	};
+	// Observed exit is authoritative: only non-null exit/signal codes prove the
+	// child is gone, regardless of which event (if any) resolved the wait.
+	const hasExited = (): boolean => child.exitCode !== null || child.signalCode !== null;
+	const signal = (sig: NodeJS.Signals): void => {
+		if (hasExited()) return;
+		try {
+			child.kill(sig);
+		} catch {
+			// already exited between the liveness check and the kill
+		}
+	};
+	if (hasExited()) return;
+	signal("SIGTERM");
+	await Promise.race([awaitVerifiedExit(), sleep(timing.gracefulMs)]);
+	if (hasExited()) return;
+	signal("SIGKILL");
+	await Promise.race([awaitVerifiedExit(), sleep(timing.killVerifyMs)]);
+	if (hasExited()) return;
+	// SIGKILL is uninterruptible; a child still alive past this bounded wait is a
+	// kernel-level stuck state. Surface it rather than silently orphaning the spawn.
+	throw new Error(`Detached SDK broker (pid ${child.pid}) did not exit after SIGKILL during reap.`);
+}
+
+function registerBrokerOwner(
+	agentDir: string,
+	child: ChildProcess,
+	timing: ReapTiming = DEFAULT_REAP_TIMING,
+): BrokerOwner {
+	const incarnation = child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
+	let state: "starting" | "ready" | "cleanup-unverified" = "starting";
+	const matches = (discovery: BrokerDiscovery | null): boolean =>
+		Boolean(
+			discovery &&
+				child.pid !== undefined &&
+				incarnation &&
+				discovery.pid === child.pid &&
+				discovery.incarnation === incarnation,
+		);
+	const owner: BrokerOwner = {
+		async stop(): Promise<void> {
+			try {
+				await reapSpawnedBroker(child, timing);
+			} catch (error) {
+				state = "cleanup-unverified";
+				throw error;
+			}
+			if (owners.get(agentDir) === owner) owners.delete(agentDir);
+		},
+		canReuse(discovery): boolean {
+			return state === "ready" && matches(discovery);
+		},
+		markReady(discovery): boolean {
+			if (!matches(discovery)) return false;
+			state = "ready";
+			return true;
+		},
+	};
+	owners.set(agentDir, owner);
+	return owner;
+}
+function brokerSpawnEnvironment(command: SdkInternalSpawnCommand, override?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const environment = { ...(override ?? command.env) };
+	delete environment.BUN_OPTIONS;
+	if (command.kind === "bun-source") {
+		delete environment.PI_COMPILED;
+		delete environment.GJC_COMPILED;
+	}
+	return environment;
+}
+
+function fixtureLeaseUnavailable(): Error {
+	return new Error("fixture_broker_lease_unavailable");
+}
+
+function createFixtureLease(owner: BrokerOwner): FixtureBrokerLease {
+	let closeAttempt: Promise<void> | undefined;
+	let closed = false;
+	return {
+		close(): Promise<void> {
+			if (closed) return Promise.resolve();
+			if (closeAttempt) return closeAttempt;
+			closeAttempt = owner.stop().then(
+				() => {
+					closed = true;
+				},
+				(error: unknown) => {
+					closeAttempt = undefined;
+					throw error;
+				},
+			);
+			return closeAttempt;
+		},
+	};
+}
+
+async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: EnsureInitiator): Promise<EnsureOutcome> {
+	const priorOwner = owners.get(settings.agentDir);
+	const existing = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+	if (initiator === "fixture-lease" && (priorOwner || existing)) throw fixtureLeaseUnavailable();
+	if (priorOwner) {
+		// A retained cleanup failure fences every discovery record. Only a ready
+		// record bound to this exact child incarnation may be reused.
+		if (priorOwner.canReuse(existing)) return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
+		await priorOwner.stop();
+		const discoveredAfterCleanup = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (discoveredAfterCleanup) return { kind: "external-discovery", discovery: discoveredAfterCleanup };
+	} else if (existing) {
+		return { kind: "external-discovery", discovery: existing };
+	}
+
+	const command = resolveSdkInternalSpawnCommand("broker-internal");
+	const child = spawn(command.file, [...command.args, "--agent-dir", settings.agentDir], {
+		detached: true,
+		stdio: "ignore",
+		env: brokerSpawnEnvironment(command, settings.env),
+		...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
+	});
+	child.unref();
+	let spawnError: Error | undefined;
+	child.once("error", error => {
+		spawnError = error;
+	});
+	const owner = registerBrokerOwner(settings.agentDir, child);
+	const deadline = Date.now() + DISCOVERY_TIMEOUT_MS;
+	let discoveryError: unknown;
+	while (Date.now() < deadline) {
+		if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
+		try {
+			const discovered = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+			if (discovered) {
+				if (owner.markReady(discovered)) {
+					return initiator === "fixture-lease"
+						? { kind: "local-started-fixture", discovery: discovered, owner }
+						: { kind: "local-started-discovery", discovery: discovered };
+				}
+				await owner.stop();
+				return { kind: "external-discovery", discovery: discovered };
+			}
+		} catch (error) {
+			discoveryError = error;
+		}
+		await sleep(50);
+	}
+	const exitedBeforeDiscovery = child.exitCode !== null || child.signalCode !== null;
+	const failure = spawnError
+		? new Error(`Failed to spawn detached SDK broker: ${spawnError.message}`)
+		: exitedBeforeDiscovery
+			? new Error(
+					`Detached SDK broker exited before discovery (code=${child.exitCode}, signal=${child.signalCode}).`,
+				)
+			: discoveryError
+				? discoveryError
+				: new Error("Timed out waiting for detached SDK broker discovery.");
+	try {
+		await owner.stop();
+	} catch (cleanupError) {
+		throw new AggregateError([failure, cleanupError], "SDK broker discovery and spawned broker cleanup both failed.");
+	}
+	throw failure;
+}
+
+function startEnsure(settings: EnsureBrokerSettings, initiator: EnsureInitiator): EnsureInFlight {
+	const promise = ensureBrokerOnce(settings, initiator);
+	const discovery = promise.then(outcome => outcome.discovery);
+	void discovery.catch(() => {});
+	const entry = { initiator, promise, discovery };
+	ensureInFlight.set(settings.agentDir, entry);
+	const clear = (): void => {
+		if (ensureInFlight.get(settings.agentDir) === entry) ensureInFlight.delete(settings.agentDir);
+	};
+	void promise.then(clear, clear);
+	return entry;
+}
+
+/** Starts the detached broker entrypoint when discovery has no live owner. */
+export function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
+	const inFlight = ensureInFlight.get(settings.agentDir) ?? startEnsure(settings, "discovery");
+	return inFlight.discovery;
+}
+
+/** Starts one fresh fixture broker and returns its sole exact-child close lease. */
+export function startFixtureBrokerWithLeaseForTest(settings: EnsureBrokerSettings): Promise<StartedFixtureBroker> {
+	if (ensureInFlight.has(settings.agentDir)) return Promise.reject(fixtureLeaseUnavailable());
+	const inFlight = startEnsure(settings, "fixture-lease");
+	return inFlight.promise.then(outcome => {
+		if (outcome.kind !== "local-started-fixture") throw fixtureLeaseUnavailable();
+		return { discovery: outcome.discovery, lease: createFixtureLease(outcome.owner) };
+	});
+}
+
+/** Test hook: returns a stop handle for the detached broker this process spawned. */
+export function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined {
+	return owners.get(agentDir);
+}
+/** Test hook: drives the detached-broker reap on a controllable child surface. */
+export function reapSpawnedBrokerForTest(child: ChildProcess, timing: ReapTiming = DEFAULT_REAP_TIMING): Promise<void> {
+	return reapSpawnedBroker(child, timing);
+}
+/** Test hook: resolves the complete broker environment without spawning. */
+export function brokerSpawnEnvironmentForTest(
+	command: SdkInternalSpawnCommand,
+	override?: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+	return brokerSpawnEnvironment(command, override);
+}
+/** Test hook: installs an exact controllable owner to exercise replacement fencing. */
+export function registerBrokerOwnerForTest(
+	agentDir: string,
+	child: ChildProcess,
+	timing: ReapTiming = DEFAULT_REAP_TIMING,
+): BrokerOwner {
+	return registerBrokerOwner(agentDir, child, timing);
+}

package/src/sdk/broker/identity.ts

@@ -0,0 +1,42 @@
+import { createHmac, randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+
+const MODE = 0o600;
+
+export function brokerIdentityPath(agentDir: string): string {
+	return path.join(agentDir, "sdk", "broker.identity");
+}
+
+export async function getBrokerIdentityKey(agentDir: string): Promise<string> {
+	const file = brokerIdentityPath(agentDir);
+	await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+	try {
+		const key = (await fs.readFile(file, "utf8")).trim();
+		if (/^[0-9a-f]{64}$/i.test(key)) return key;
+		throw new Error(`Invalid broker identity key at ${file}`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		const key = randomBytes(32).toString("hex");
+		try {
+			await fs.writeFile(file, `${key}\n`, { encoding: "utf8", mode: MODE, flag: "wx" });
+			await fs.chmod(file, MODE);
+			return key;
+		} catch (writeError) {
+			if ((writeError as NodeJS.ErrnoException).code !== "EEXIST") throw writeError;
+			return getBrokerIdentityKey(agentDir);
+		}
+	}
+}
+
+export async function deriveIdempotencyIdentity(
+	agentDir: string,
+	operation: string,
+	callerKey: string,
+	canonicalTargetHash: string,
+): Promise<string> {
+	const key = await getBrokerIdentityKey(agentDir);
+	return createHmac("sha256", Buffer.from(key, "hex"))
+		.update(`3|${operation}|${callerKey}|${canonicalTargetHash}`)
+		.digest("hex");
+}

package/src/sdk/broker/index.ts

@@ -0,0 +1,8 @@
+export * from "./broker";
+export * from "./discovery";
+export * from "./ensure";
+export * from "./identity";
+export * from "./lifecycle";
+export * from "./lifecycle-ledger";
+export * from "./session-index";
+export * from "./transport";

package/src/sdk/broker/internal-source-marker-2178.txt

@@ -0,0 +1 @@
+gjc-sdk-broker-internal-source-marker-2178

package/src/sdk/broker/internal-source.bunfig.toml

@@ -0,0 +1 @@
+# Product-owned empty Bun configuration for isolated SDK-internal source children.