@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/{notifications → sdk/bus}/topic-registry.ts

@@ -31,6 +31,10 @@ export interface TopicRecord {
 	userNameUpdateId?: number;
 	/** Stable repo/branch identity used when topic names are user-owned or customized. */
 	identityKey?: string;
+	/** Last SDK event generation durably consumed by the notification daemon. */
+	replayGeneration?: number;
+	/** Last SDK event sequence durably consumed within replayGeneration. */
+	replaySeq?: number;
 }
 
 /** Serialisable shape persisted to disk. */
@@ -71,6 +75,13 @@ export class TopicRegistry {
 				typeof raw.userNameUpdateId === "number" &&
 				Number.isSafeInteger(raw.userNameUpdateId) &&
 				raw.userNameUpdateId >= 0;
+			const hasValidReplayCursor =
+				typeof raw.replayGeneration === "number" &&
+				Number.isSafeInteger(raw.replayGeneration) &&
+				raw.replayGeneration >= 1 &&
+				typeof raw.replaySeq === "number" &&
+				Number.isSafeInteger(raw.replaySeq) &&
+				raw.replaySeq >= 0;
 			const record: TopicRecord = {
 				topicId: raw.topicId,
 				identitySent: raw.identitySent === true,
@@ -80,6 +91,7 @@ export class TopicRegistry {
 				...(hasValidUserAuthority && raw.nameReconcilePending === true ? { nameReconcilePending: true } : {}),
 				...(hasValidUserAuthority ? { userNameUpdateId: raw.userNameUpdateId } : {}),
 				...(typeof raw.identityKey === "string" ? { identityKey: raw.identityKey } : {}),
+				...(hasValidReplayCursor ? { replayGeneration: raw.replayGeneration, replaySeq: raw.replaySeq } : {}),
 			};
 			this.topics.set(sessionId, record);
 			this.byTopic.set(record.topicId, sessionId);
@@ -154,6 +166,26 @@ export class TopicRegistry {
 		return true;
 	}
 
+	/** Last durably consumed SDK event cursor for reconnect replay. */
+	replayCursor(sessionId: string): { generation: number; seq: number } | undefined {
+		const record = this.topics.get(sessionId);
+		return record?.replayGeneration !== undefined && record.replaySeq !== undefined
+			? { generation: record.replayGeneration, seq: record.replaySeq }
+			: undefined;
+	}
+
+	/** Advance the durable reconnect cursor without allowing stale responses to move it backwards. */
+	markReplayCursor(sessionId: string, generation: number, seq: number): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record) return false;
+		const currentGeneration = record.replayGeneration ?? 0;
+		const currentSeq = record.replaySeq ?? 0;
+		if (generation < currentGeneration || (generation === currentGeneration && seq <= currentSeq)) return false;
+		record.replayGeneration = generation;
+		record.replaySeq = seq;
+		return true;
+	}
+
 	/** Whether daemon identity reconciliation should apply `name`. */
 	needsRename(sessionId: string, name: string): boolean {
 		const record = this.topics.get(sessionId);

package/src/sdk/cli/index.ts

@@ -0,0 +1 @@
+export * from "./session-cli";

package/src/sdk/cli/session-cli.ts

@@ -0,0 +1,275 @@
+import * as fs from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { getAgentDir } from "@gajae-code/utils";
+import { ensureBroker } from "../broker/ensure";
+import {
+	listSdkSessionEndpoints,
+	readSdkBrokerDiscovery,
+	readSdkSessionEndpoint,
+	SdkClient,
+	SdkClientError,
+	SdkDiscoveryError,
+} from "../client";
+import { validateAdapterControl } from "../protocol/adapter-validation";
+import { adapterDispositionError, findOperation, type OperationKind } from "../protocol/operation-registry";
+
+export type SdkSessionCliAction = "list" | "control" | "query" | "global";
+
+export interface SdkSessionCliArgs {
+	action?: string;
+	sessionId?: string;
+	operation?: string;
+	query?: string;
+	jsonInput?: string;
+	jsonInputFile?: string;
+	idempotencyKey?: string;
+	jsonInputStdin?: boolean;
+	confirm?: boolean;
+	cursor?: string;
+	showEndpointCredential?: boolean;
+	yes?: boolean;
+	repo?: string;
+	agentDir?: string;
+}
+
+type JsonRecord = Record<string, unknown>;
+const SECRET_FIELD = /(?:secret|token|password|credential|authorization|api[_-]?key)/i;
+
+class SdkSessionCliError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly exitCode: 1 | 2,
+	) {
+		super(message);
+	}
+}
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function parseInput(raw: string | undefined, source: string): JsonRecord {
+	if (raw === undefined) return {};
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (!value || typeof value !== "object" || Array.isArray(value))
+			throw new SdkSessionCliError("invalid_input", `${source} must be a JSON object.`, 2);
+		return value as JsonRecord;
+	} catch (error) {
+		if (error instanceof SdkSessionCliError) throw error;
+		throw new SdkSessionCliError("invalid_json", `${source} must contain valid JSON.`, 2);
+	}
+}
+
+function containsSecretField(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsSecretField);
+	if (!value || typeof value !== "object") return false;
+	return Object.entries(value).some(([key, nested]) => SECRET_FIELD.test(key) || containsSecretField(nested));
+}
+
+async function inputFromArgs(args: SdkSessionCliArgs): Promise<JsonRecord> {
+	const sources = [
+		args.jsonInput !== undefined,
+		args.jsonInputFile !== undefined,
+		args.jsonInputStdin === true,
+	].filter(Boolean).length;
+	if (sources > 1) throw new SdkSessionCliError("usage", "Use only one JSON input source.", 2);
+	if (args.jsonInput !== undefined) {
+		const input = parseInput(args.jsonInput, "--json-input");
+		if (containsSecretField(input))
+			throw new SdkSessionCliError(
+				"secret_field_forbidden",
+				"Secret values must use --json-input-file or --json-input-stdin.",
+				2,
+			);
+		return input;
+	}
+	if (args.jsonInputFile !== undefined) {
+		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		try {
+			stat = await fs.stat(args.jsonInputFile);
+		} catch {
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+		}
+		if (!stat.isFile() || (stat.mode & 0o077) !== 0)
+			throw new SdkSessionCliError(
+				"input_file_permissions",
+				"--json-input-file must be a regular file with 0600 permissions.",
+				2,
+			);
+		try {
+			return parseInput(await fs.readFile(args.jsonInputFile, "utf8"), "--json-input-file");
+		} catch (error) {
+			if (error instanceof SdkSessionCliError) throw error;
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+		}
+	}
+	return args.jsonInputStdin ? parseInput(await Bun.stdin.text(), "--json-input-stdin") : {};
+}
+
+function requireValue(value: string | undefined, flag: string): string {
+	if (!value) throw new SdkSessionCliError("usage", `${flag} is required.`, 2);
+	return value;
+}
+
+function isEndpointOperation(operation: string): boolean {
+	return operation === "session.get_endpoint";
+}
+
+function cliOperationError(kind: OperationKind, operation: string): { code: string; message: string } | undefined {
+	const row = findOperation(kind, operation);
+	const error = adapterDispositionError("daemonCli", kind, operation);
+	if (!error) return undefined;
+	if (row?.adapterDispositions.daemonCli === "prohibited")
+		return {
+			code: error.code,
+			message: `${operation} is unavailable through the ordinary CLI; provider mode is out of scope this phase.`,
+		};
+	return error;
+}
+
+function isLifecycleOperation(operation: string): boolean {
+	return (
+		operation === "session.create" ||
+		operation === "session.fork" ||
+		operation === "session.resume" ||
+		operation === "session.close" ||
+		operation === "session.delete"
+	);
+}
+
+async function confirmEndpointCredentialOutput(): Promise<boolean> {
+	const prompt = createInterface({ input: process.stdin, output: process.stderr });
+	try {
+		return (await prompt.question("Print the endpoint credential to stdout? [y/N] ")).trim().toLowerCase() === "y";
+	} finally {
+		prompt.close();
+	}
+}
+
+async function connectBroker(agentDir: string): Promise<SdkClient> {
+	await ensureBroker({ agentDir });
+	const discovery = await readSdkBrokerDiscovery(agentDir);
+	if (!discovery) throw new SdkSessionCliError("broker_unavailable", "SDK broker discovery is unavailable.", 1);
+	return await SdkClient.connect(discovery.url, discovery.token);
+}
+
+async function connectSession(repo: string, sessionId: string): Promise<SdkClient> {
+	const endpoint = await readSdkSessionEndpoint(repo, sessionId);
+	if (!endpoint)
+		throw new SdkSessionCliError("session_unavailable", `SDK endpoint for session ${sessionId} is unavailable.`, 1);
+	return await SdkClient.connect(endpoint.url, endpoint.token);
+}
+
+function brokerAbsent(error: unknown): boolean {
+	if (error instanceof SdkSessionCliError) return error.code === "broker_unavailable";
+	const details = error instanceof SdkClientError ? error.details : error;
+	const code = (details as { code?: unknown } | undefined)?.code;
+	return (
+		code === "ENOENT" ||
+		code === "ECONNREFUSED" ||
+		/(?:ENOENT|ECONNREFUSED|connection refused)/i.test(error instanceof Error ? error.message : "")
+	);
+}
+
+async function runList(repo: string, agentDir: string): Promise<unknown> {
+	try {
+		const client = await connectBroker(agentDir);
+		try {
+			return await client.global("session.list", {});
+		} finally {
+			await client.close();
+		}
+	} catch (error) {
+		if (!brokerAbsent(error)) throw error;
+		const { endpoints, warnings } = await listSdkSessionEndpoints(repo);
+		return {
+			sessions: endpoints.map(({ sessionId, path }) => ({ sessionId, path })),
+			warnings: [
+				{ code: "broker_unavailable", message: "Listed endpoint files because the broker is unavailable." },
+				...warnings,
+			],
+		};
+	}
+}
+
+/** Runs the pure-SDK `gjc daemon session` command family. */
+export async function runSdkSessionCli(
+	args: SdkSessionCliArgs,
+	writeOutput: (value: unknown) => void = writeJson,
+	setExitCode: (exitCode: 1 | 2) => void = exitCode => {
+		process.exitCode = exitCode;
+	},
+): Promise<void> {
+	try {
+		const action = args.action;
+		if (action !== "list" && action !== "control" && action !== "query" && action !== "global")
+			throw new SdkSessionCliError("usage", "Expected one of: list, control, query, global.", 2);
+		const repo = args.repo ?? process.cwd();
+		const agentDir = args.agentDir ?? getAgentDir();
+		if (action === "list") {
+			writeOutput(await runList(repo, agentDir));
+			return;
+		}
+		const operation = action === "query" ? requireValue(args.query, "--query") : requireValue(args.operation, "--op");
+		const kind: OperationKind = action === "query" ? "query" : action === "global" ? "global" : "control";
+		const dispositionError = cliOperationError(kind, operation);
+		if (dispositionError) throw new SdkSessionCliError(dispositionError.code, dispositionError.message, 1);
+		if (isEndpointOperation(operation)) {
+			if (!args.showEndpointCredential)
+				throw new SdkSessionCliError(
+					"endpoint_credential_forbidden",
+					"session.get_endpoint requires --show-endpoint-credential.",
+					1,
+				);
+			if (process.stdout.isTTY && !args.yes && !(await confirmEndpointCredentialOutput()))
+				throw new SdkSessionCliError(
+					"endpoint_credential_confirmation_required",
+					"Endpoint credential output was not confirmed.",
+					1,
+				);
+		}
+		const input = await inputFromArgs(args);
+		if (kind === "control") {
+			const invalid = validateAdapterControl(operation, input);
+			if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
+		}
+		if (action === "global") {
+			const idempotencyKey = args.idempotencyKey;
+			if (isLifecycleOperation(operation) && !idempotencyKey)
+				throw new SdkSessionCliError("invalid_input", "--idempotency-key is required for lifecycle operations.", 2);
+			const client = await connectBroker(agentDir);
+			try {
+				writeOutput(await client.global(operation, input, { idempotencyKey }));
+			} finally {
+				await client.close();
+			}
+			return;
+		}
+		const sessionId = requireValue(args.sessionId, "<sessionId>");
+		const client = await connectSession(repo, sessionId);
+		try {
+			if (action === "control")
+				writeOutput(await client.control(operation, input, { confirm: args.confirm === true }));
+			else writeOutput(await client.query(operation, input, args.cursor));
+		} finally {
+			await client.close();
+		}
+	} catch (error) {
+		const cliError =
+			error instanceof SdkSessionCliError
+				? error
+				: error instanceof SdkClientError
+					? new SdkSessionCliError(error.code, error.message, 1)
+					: error instanceof SdkDiscoveryError
+						? new SdkSessionCliError(error.code, error.message, 1)
+						: new SdkSessionCliError(
+								"operation_failed",
+								error instanceof Error ? error.message : "SDK operation failed.",
+								1,
+							);
+		writeOutput({ ok: false, error: { code: cliError.code, message: cliError.message } });
+		setExitCode(cliError.exitCode);
+	}
+}

package/src/sdk/client/client.ts

@@ -0,0 +1 @@
+export * from "@gajae-code/bridge-client";

package/src/sdk/client/discovery.ts

@@ -0,0 +1,108 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { type BrokerDiscovery, readBrokerDiscovery as readBrokerFile } from "../broker/discovery";
+
+export interface SdkSessionEndpoint {
+	sessionId: string;
+	url: string;
+	token: string;
+	path: string;
+}
+
+export interface SdkDiscoveryWarning {
+	code: "discovery_error";
+	path: string;
+	message: string;
+}
+
+export interface SdkSessionEndpointList {
+	endpoints: SdkSessionEndpoint[];
+	warnings: SdkDiscoveryWarning[];
+}
+
+export class SdkDiscoveryError extends Error {
+	readonly code = "discovery_error";
+	constructor(
+		readonly path: string,
+		message: string,
+	) {
+		super(message);
+		this.name = "SdkDiscoveryError";
+	}
+}
+
+function endpointDirectory(repo: string): string {
+	return path.join(repo, ".gjc", "state", "sdk");
+}
+
+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 };
+	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)
+		throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
+	return { sessionId, url: endpoint.url, token: endpoint.token, path: file };
+}
+
+function discoveryError(file: string, error: unknown): SdkDiscoveryError {
+	if (error instanceof SdkDiscoveryError) return error;
+	return new SdkDiscoveryError(file, "Unable to read SDK discovery record.");
+}
+
+/** Lists endpoint files and returns individual malformed or unreadable records as warnings. */
+export async function listSdkSessionEndpoints(repo: string): Promise<SdkSessionEndpointList> {
+	const directory = endpointDirectory(repo);
+	let entries: Array<{ name: string; isFile(): boolean }>;
+	try {
+		entries = (await fs.readdir(directory, { withFileTypes: true })) as Array<{ name: string; isFile(): boolean }>;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { endpoints: [], warnings: [] };
+		throw discoveryError(directory, error);
+	}
+	const results = await Promise.all(
+		entries
+			.filter(entry => entry.isFile() && entry.name.endsWith(".json"))
+			.map(async entry => {
+				const sessionId = entry.name.slice(0, -".json".length);
+				const file = path.join(directory, entry.name);
+				try {
+					return { endpoint: parseEndpoint(sessionId, file, JSON.parse(await fs.readFile(file, "utf8"))) };
+				} catch (error) {
+					return { warning: discoveryError(file, error) };
+				}
+			}),
+	);
+	return {
+		endpoints: results.flatMap(result => (result.endpoint ? [result.endpoint] : [])),
+		warnings: results.flatMap(result =>
+			result.warning
+				? [{ code: result.warning.code, path: result.warning.path, message: result.warning.message }]
+				: [],
+		),
+	};
+}
+
+/** Resolves one per-session SDK endpoint discovery file. */
+export async function readSdkSessionEndpoint(repo: string, sessionId: string): Promise<SdkSessionEndpoint | null> {
+	if (!sessionId || sessionId.includes(path.sep) || sessionId.includes("/")) return null;
+	const file = path.join(endpointDirectory(repo), `${sessionId}.json`);
+	try {
+		return parseEndpoint(sessionId, file, JSON.parse(await fs.readFile(file, "utf8")));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw discoveryError(file, error);
+	}
+}
+
+/** Reads the agent-global broker discovery record. */
+export async function readSdkBrokerDiscovery(agentDir: string): Promise<BrokerDiscovery | null> {
+	try {
+		return await readBrokerFile(agentDir);
+	} catch (error) {
+		const file = path.join(agentDir, "sdk", "broker.json");
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw discoveryError(file, error);
+	}
+}

package/src/sdk/client/index.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./discovery";