@gajae-code/coding-agent 0.15.6 → 0.16.1

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

@@ -0,0 +1,259 @@
+/**
+ * Local interactive-master CLI surface.
+ *
+ * `gjc sdk spawn` is legal only inside a live master session: the master's Bash
+ * tool threads the transient capability only through a strict direct spawn
+ * command, and the Broker still verifies it against the live effective host
+ * before any effect.
+ * No output path may echo the task or capability.
+ */
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { getAgentDir } from "@gajae-code/utils";
+import { type IndexedSession, isSessionAuthorityEligible, SessionIndex } from "../broker/session-index";
+import { SdkClientError } from "../client";
+import { dispatchSpawnGlobal } from "../lifecycle/broker-client";
+
+const MASTER_CAPABILITY_ENV = "GJC_MASTER_CAPABILITY";
+const MASTER_SESSION_ENV = "GJC_SESSION_ID";
+const SPAWN_TIMEOUT_MS = 120_000;
+
+export class SdkMasterCliError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly exitCode: 1 | 2 = 1,
+	) {
+		super(message);
+		this.name = "SdkMasterCliError";
+	}
+}
+
+export interface SdkSpawnArgs {
+	cwd?: string;
+	prompt?: string;
+	model?: string;
+	profile?: string;
+	agentDir?: string;
+	idempotencyKey?: string;
+	json?: boolean;
+}
+
+/** The allowlisted spawn result projection rendered to the operator. */
+export interface SdkSpawnRendered {
+	code: string;
+	claimId?: string;
+	sessionId?: string;
+	substrateKind?: string;
+	seed?: { phase?: string; clientRef?: string; commandId?: string; turnId?: string; status?: string };
+	idempotencyKey?: string;
+	error?: { code: string; message: string };
+}
+
+export interface SdkSpawnDependencies {
+	env: Record<string, string | undefined>;
+	dispatch: (agentDir: string, input: Record<string, unknown>, idempotencyKey: string) => Promise<unknown>;
+	resolveAttestationEpoch: (agentDir: string, ownerSessionId: string) => Promise<string | undefined>;
+}
+
+async function brokerSpawnDispatch(
+	agentDir: string,
+	input: Record<string, unknown>,
+	idempotencyKey: string,
+): Promise<unknown> {
+	return await dispatchSpawnGlobal(agentDir, input, idempotencyKey, SPAWN_TIMEOUT_MS);
+}
+
+/**
+ * Select the newest retained master attestation for an owner session.
+ *
+ * `listSessionIdentities()` can retain both the direct-role row and one or
+ * more endpoint generations. Its iteration order is a projection detail, not
+ * authority ordering, so selecting the first matching row can resurrect an
+ * older epoch after a master relaunch. The broker's monotonically increasing
+ * `indexSeq` is the authoritative retained ordering.
+ */
+export function selectNewestMasterAttestationEpoch(
+	rows: readonly IndexedSession[],
+	ownerSessionId: string,
+): string | undefined {
+	const processIdentity = (row: IndexedSession): string | undefined => row.hostIncarnation ?? row.processIncarnation;
+	const matchesAttestation = (
+		left: NonNullable<IndexedSession["masterRole"]>,
+		right: NonNullable<IndexedSession["masterRole"]>,
+	) =>
+		left.version === right.version &&
+		left.ownerSessionId === right.ownerSessionId &&
+		left.launchPid === right.launchPid &&
+		left.launchProcessIncarnation === right.launchProcessIncarnation &&
+		left.role === right.role &&
+		left.attestationEpoch === right.attestationEpoch;
+	const hasDirectAttestation = (effective: IndexedSession): boolean =>
+		rows.some(
+			row =>
+				row.sessionId === effective.sessionId &&
+				row.endpointGeneration === 0 &&
+				row.pid === effective.masterRole?.launchPid &&
+				processIdentity(row) === effective.masterRole?.launchProcessIncarnation &&
+				row.masterRole !== undefined &&
+				effective.masterRole !== undefined &&
+				matchesAttestation(row.masterRole, effective.masterRole),
+		);
+	let newest: { indexSeq: number; epoch: string } | undefined;
+	for (const row of rows) {
+		const attestation = row.masterRole;
+		if (
+			!Number.isSafeInteger(row.indexSeq) ||
+			attestation === undefined ||
+			attestation.version !== 2 ||
+			attestation.role !== "master" ||
+			attestation.ownerSessionId !== ownerSessionId ||
+			row.endpointGeneration <= 0 ||
+			row.live !== true ||
+			row.terminal ||
+			row.terminalUncertain ||
+			!isSessionAuthorityEligible(row) ||
+			attestation.launchPid !== row.pid ||
+			attestation.launchProcessIncarnation !== processIdentity(row) ||
+			!hasDirectAttestation(row) ||
+			typeof attestation.attestationEpoch !== "string" ||
+			attestation.attestationEpoch.length === 0 ||
+			attestation.attestationEpoch.length > 512 ||
+			!/^[A-Za-z0-9_-]+$/u.test(attestation.attestationEpoch)
+		)
+			continue;
+		if (newest === undefined || row.indexSeq > newest.indexSeq)
+			newest = { indexSeq: row.indexSeq, epoch: attestation.attestationEpoch };
+	}
+	return newest?.epoch;
+}
+
+async function indexAttestationEpoch(agentDir: string, ownerSessionId: string): Promise<string | undefined> {
+	const index = await new SessionIndex(agentDir).open();
+	return selectNewestMasterAttestationEpoch(index.listSessionIdentities(), ownerSessionId);
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function opaque(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 && value.length <= 512 ? value : undefined;
+}
+
+/** Projects an arbitrary Broker response onto the allowlisted render shape. */
+export function safeSpawnRender(response: unknown): { rendered: SdkSpawnRendered; exitCode: 0 | 1 } {
+	const outer = record(response);
+	if (outer?.ok === true) {
+		const result = record(outer.result);
+		const seed = record(result?.seed);
+		return {
+			rendered: {
+				code: opaque(result?.code) ?? "spawn_accepted",
+				...(opaque(result?.claimId) === undefined ? {} : { claimId: opaque(result?.claimId) }),
+				...(opaque(result?.sessionId) === undefined ? {} : { sessionId: opaque(result?.sessionId) }),
+				...(opaque(result?.substrateKind) === undefined ? {} : { substrateKind: opaque(result?.substrateKind) }),
+				...(seed === undefined
+					? {}
+					: {
+							seed: {
+								...(opaque(seed.phase) === undefined ? {} : { phase: opaque(seed.phase) }),
+								...(opaque(seed.clientRef) === undefined ? {} : { clientRef: opaque(seed.clientRef) }),
+								...(opaque(seed.commandId) === undefined ? {} : { commandId: opaque(seed.commandId) }),
+								...(opaque(seed.turnId) === undefined ? {} : { turnId: opaque(seed.turnId) }),
+								...(opaque(seed.status) === undefined ? {} : { status: opaque(seed.status) }),
+							},
+						}),
+			},
+			exitCode: 0,
+		};
+	}
+	const error = record(outer?.error);
+	const code = opaque(error?.code) ?? "spawn_failed";
+	const retryIdempotencyKey = code === "uncertain_after_send" ? opaque(error?.idempotencyKey) : undefined;
+	// Error messages are Broker-typed and never quote request input; an uncertain
+	// post-send result may additionally expose its non-secret replay key.
+	const message =
+		typeof error?.message === "string" && error.message.length <= 512 ? error.message : "session.spawn failed";
+	return {
+		rendered: {
+			code,
+			...(retryIdempotencyKey === undefined ? {} : { idempotencyKey: retryIdempotencyKey }),
+			error: { code, message },
+		},
+		exitCode: 1,
+	};
+}
+
+export function renderSpawnTable(rendered: SdkSpawnRendered): string {
+	const lines = [`Result: ${rendered.code}`];
+	if (rendered.claimId) lines.push(`Claim: ${rendered.claimId}`);
+	if (rendered.sessionId) lines.push(`Child session: ${rendered.sessionId}`);
+	if (rendered.substrateKind) lines.push(`Substrate: ${rendered.substrateKind}`);
+	if (rendered.seed?.phase) lines.push(`Seed phase: ${rendered.seed.phase}`);
+	if (rendered.seed?.status) lines.push(`Seed status: ${rendered.seed.status}`);
+	if (rendered.error) lines.push(`Error: ${rendered.error.code}: ${rendered.error.message}`);
+	if (rendered.idempotencyKey) lines.push(`Retry idempotency key: ${rendered.idempotencyKey}`);
+
+	return lines.join("\n");
+}
+
+/**
+ * Runs one local master spawn. A caller-provided idempotency key replays the
+ * matching durable claim; otherwise each invocation receives a fresh key.
+ */
+export async function runSdkSpawn(
+	args: SdkSpawnArgs,
+	dependencies: Partial<SdkSpawnDependencies> = {},
+): Promise<{ rendered: SdkSpawnRendered; exitCode: 0 | 1 }> {
+	const deps: SdkSpawnDependencies = {
+		env: dependencies.env ?? process.env,
+		dispatch: dependencies.dispatch ?? brokerSpawnDispatch,
+		resolveAttestationEpoch: dependencies.resolveAttestationEpoch ?? indexAttestationEpoch,
+	};
+	if (!args.cwd) throw new SdkMasterCliError("invalid_input", "sdk spawn requires --cwd <dir>.", 2);
+	if (!args.prompt) throw new SdkMasterCliError("invalid_input", "sdk spawn requires --prompt <task>.", 2);
+	const capability = deps.env[MASTER_CAPABILITY_ENV];
+	const ownerSessionId = deps.env[MASTER_SESSION_ENV];
+	if (!capability || !ownerSessionId)
+		throw new SdkMasterCliError(
+			"master_context_required",
+			"sdk spawn is available only inside a live interactive master session.",
+			1,
+		);
+	const agentDir = args.agentDir ?? getAgentDir();
+	const attestationEpoch = await deps.resolveAttestationEpoch(agentDir, ownerSessionId);
+	if (!attestationEpoch)
+		throw new SdkMasterCliError(
+			"master_context_required",
+			"No master role attestation exists for this session; relaunch with gjc --master.",
+			1,
+		);
+	const idempotencyKey = args.idempotencyKey ?? randomUUID();
+	try {
+		const response = await deps.dispatch(
+			agentDir,
+			{
+				task: args.prompt,
+				masterCapability: capability,
+				ownerSessionId,
+				attestationEpoch,
+				cwd: args.cwd === undefined ? undefined : path.resolve(args.cwd),
+				...(args.model === undefined ? {} : { modelId: args.model }),
+				...(args.profile === undefined ? {} : { modelPreset: args.profile }),
+			},
+			idempotencyKey,
+		);
+		return safeSpawnRender(response);
+	} catch (error) {
+		if (error instanceof SdkClientError && error.code === "uncertain_after_send") {
+			return safeSpawnRender({
+				ok: false,
+				error: { code: error.code, message: error.message, idempotencyKey },
+			});
+		}
+		throw error;
+	}
+}

package/src/sdk/cli/rows.ts

@@ -1,5 +1,5 @@
 /**
- * Versioned DTO rows for `gjc sdk session` semantic verbs (row DTO v1, DR-12).
+ * Versioned DTO rows for `gjc sdk session` semantic verbs (row DTO v2, DR-12).
  *
  * Every semantic verb renders its output through these rows so machine
  * consumers get one deterministic, versioned envelope per verb. Credentials
@@ -8,7 +8,7 @@
  * rendering.
  */
 
-export const SESSION_ROWS_VERSION = 1;
+export const SESSION_ROWS_VERSION = 2;
 
 export type SdkSessionActivityState = "active" | "idle";
 
@@ -19,7 +19,7 @@ export interface SdkSessionActivityV1 {
 
 export interface SdkSessionRowV1 {
 	sessionId: string;
-	locator: { repo: string; stateRoot: string };
+	locator: { cwd: string; worktreeRoot: string | null; stateRoot: string };
 	endpointGeneration: number;
 	/** Process-bound incarnation of the hosting process (C1); absent for legacy-provenance rows. */
 	hostIncarnation?: string;
@@ -41,16 +41,20 @@ export interface SdkSessionRowV1 {
 	ambiguous?: boolean;
 }
 
-export interface SdkCheckpointRecordV1 {
+export interface SdkRingPositionV1 {
 	revision: number;
 	generation: number;
 	seq: number;
 }
 
+export interface SdkCheckpointRecordV1 extends SdkRingPositionV1 {
+	idle: boolean;
+}
+
 export interface SdkRetentionGapV1 {
 	code: "retention_gap";
 	missing?: { from: number; to: number };
-	resync?: SdkCheckpointRecordV1;
+	resync?: SdkRingPositionV1;
 }
 
 /** One tail item: a retained transcript entry or a live event-ring event. */
@@ -58,6 +62,8 @@ export interface SdkTailItemV1 {
 	/** "transcript" for retained transcript entries, otherwise the event-ring kind. */
 	kind: string;
 	id?: string;
+	/** Durable revision at emission; (revision,generation,seq) is unique per session. generation:seq alone is revision-local. */
+	revision?: number;
 	generation?: number;
 	seq?: number;
 	payload: unknown;
@@ -98,12 +104,15 @@ function optionalFiniteNumber(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
-function locatorOf(row: Record<string, unknown>): { repo: string; stateRoot: string } {
+function locatorOf(row: Record<string, unknown>): { cwd: string; worktreeRoot: string | null; stateRoot: string } {
 	const locator = isRecord(row.locator) ? row.locator : {};
-	return {
-		repo: optionalString(locator.repo) ?? "unknown",
-		stateRoot: optionalString(locator.stateRoot) ?? "unknown",
-	};
+	const cwd = optionalString(locator.cwd);
+	const stateRoot = optionalString(locator.stateRoot);
+	const worktreeRoot = locator.worktreeRoot;
+	if (!cwd || !stateRoot || (worktreeRoot !== null && optionalString(worktreeRoot) === undefined)) {
+		throw new Error("session row has an invalid locator v2");
+	}
+	return { cwd, worktreeRoot: worktreeRoot === null ? null : optionalString(worktreeRoot)!, stateRoot };
 }
 
 function activityOf(row: Record<string, unknown>): SdkSessionActivityV1 | undefined {
@@ -162,6 +171,7 @@ export function toCheckpointRecordV1(value: unknown): SdkCheckpointRecordV1 | un
 	const revision = value.revision;
 	const generation = value.generation;
 	const seq = value.seq;
+	const idle = value.idle;
 	if (
 		typeof revision !== "number" ||
 		!Number.isSafeInteger(revision) ||
@@ -171,10 +181,11 @@ export function toCheckpointRecordV1(value: unknown): SdkCheckpointRecordV1 | un
 		generation < 0 ||
 		typeof seq !== "number" ||
 		!Number.isSafeInteger(seq) ||
-		seq < 0
+		seq < 0 ||
+		typeof idle !== "boolean"
 	)
 		return undefined;
-	return { revision, generation, seq };
+	return { revision, generation, seq, idle };
 }
 
 export function toRetentionGapV1(value: unknown): SdkRetentionGapV1 | undefined {
@@ -186,15 +197,28 @@ export function toRetentionGapV1(value: unknown): SdkRetentionGapV1 | undefined
 		if (typeof from === "number" && Number.isSafeInteger(from) && typeof to === "number" && Number.isSafeInteger(to))
 			gap.missing = { from, to };
 	}
-	const resync = toCheckpointRecordV1(value.resync);
-	if (resync !== undefined) gap.resync = resync;
+	if (isRecord(value.resync)) {
+		const { revision, generation, seq } = value.resync;
+		if (
+			typeof revision === "number" &&
+			Number.isSafeInteger(revision) &&
+			revision >= 0 &&
+			typeof generation === "number" &&
+			Number.isSafeInteger(generation) &&
+			generation >= 0 &&
+			typeof seq === "number" &&
+			Number.isSafeInteger(seq) &&
+			seq >= 0
+		)
+			gap.resync = { revision, generation, seq };
+	}
 	return gap;
 }
 
 /** Projects a transcript entry or ring event into a tail item with dedupe keys. */
 export function toTailItemV1(
 	value: unknown,
-	fallback: { kind: string; generation?: number; seq?: number },
+	fallback: { kind: string; revision?: number; generation?: number; seq?: number },
 ): SdkTailItemV1 {
 	if (!isRecord(value)) return { kind: fallback.kind, payload: stripSecretFields(value) };
 	const kind = optionalString(value.kind) ?? fallback.kind;
@@ -204,10 +228,12 @@ export function toTailItemV1(
 	const item: SdkTailItemV1 = {
 		kind,
 		...(payloadId !== undefined ? { id: payloadId } : id !== undefined ? { id } : {}),
+		...(typeof value.revision === "number" ? { revision: value.revision } : {}),
 		...(typeof value.generation === "number" ? { generation: value.generation } : {}),
 		...(typeof value.seq === "number" ? { seq: value.seq } : {}),
 		payload: stripSecretFields(payload),
 	};
+	if (fallback.revision !== undefined && item.revision === undefined) item.revision = fallback.revision;
 	if (fallback.generation !== undefined && item.generation === undefined) item.generation = fallback.generation;
 	if (fallback.seq !== undefined && item.seq === undefined) item.seq = fallback.seq;
 	return item;