@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/harness-control-plane/receipts.ts

@@ -0,0 +1,216 @@
+/**
+ * Harness receipt schemas + validators (M7).
+ *
+ * Receipts are NEW schemas that FOLLOW the .gjc/state + ultragoal-ledger patterns
+ * (atomic, append-indexed, immutable) — not drop-in reuse. Every receipt carries a
+ * canonical-JSON sha256 over its content (excluding the hash field) plus referenced
+ * artifact hashes; validators recompute and FAIL CLOSED on tamper/mismatch.
+ *
+ * Families:
+ *   - vanish            captures dirty/unknown delta before any restart/fallback (data-loss gate)
+ *   - prompt-acceptance proves single-flight acceptance (idle pre-state -> ack -> next agent_start)
+ *   - validation        records a verification command result for a specific commit
+ *   - completion        the finalize gate: receipt-valid + commit + PR/issue + validations
+ */
+import { createHash } from "node:crypto";
+import type { GitDelta, ReceiptFamily, RecoveryClassification } from "./types";
+
+export interface ReceiptSubject {
+	workspace: string;
+	branch: string | null;
+	head: string | null;
+	commit: string | null;
+}
+
+export interface ReceiptEnvelope<E = Record<string, unknown>> {
+	receiptId: string;
+	schemaVersion: number;
+	sessionId: string;
+	family: ReceiptFamily;
+	valid: boolean;
+	createdAt: string;
+	source: string;
+	subject: ReceiptSubject;
+	evidence: E;
+	/** Hashes of out-of-line artifacts (diff patches, validation logs) folded into the receipt hash. */
+	artifactHashes: Record<string, string>;
+	sha256: string;
+}
+
+export const RECEIPT_SCHEMA_VERSION = 1 as const;
+
+/** Deterministic stringify with sorted keys (stable hash basis). */
+function canonicalJson(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const obj = value as Record<string, unknown>;
+	const keys = Object.keys(obj).sort();
+	return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+
+export function sha256Hex(input: string): string {
+	return createHash("sha256").update(input).digest("hex");
+}
+
+/** Hash basis = canonical JSON of the receipt without `sha256`. */
+function hashBasis(receipt: Omit<ReceiptEnvelope<unknown>, "sha256">): string {
+	return canonicalJson(receipt);
+}
+
+export interface BuildReceiptInput<E> {
+	receiptId: string;
+	sessionId: string;
+	family: ReceiptFamily;
+	source: string;
+	subject: ReceiptSubject;
+	evidence: E;
+	artifactHashes?: Record<string, string>;
+	createdAt?: string;
+	valid?: boolean;
+}
+
+export function buildReceipt<E>(input: BuildReceiptInput<E>): ReceiptEnvelope<E> {
+	const base: Omit<ReceiptEnvelope<E>, "sha256"> = {
+		receiptId: input.receiptId,
+		schemaVersion: RECEIPT_SCHEMA_VERSION,
+		sessionId: input.sessionId,
+		family: input.family,
+		valid: input.valid ?? true,
+		createdAt: input.createdAt ?? new Date().toISOString(),
+		source: input.source,
+		subject: input.subject,
+		evidence: input.evidence,
+		artifactHashes: input.artifactHashes ?? {},
+	};
+	return { ...base, sha256: sha256Hex(hashBasis(base)) };
+}
+
+export interface ValidationOutcome {
+	valid: boolean;
+	reasons: string[];
+}
+
+/** Recompute the hash and run structural family checks. Fail-closed. */
+export function validateReceipt(receipt: ReceiptEnvelope<unknown>): ValidationOutcome {
+	const reasons: string[] = [];
+	const { sha256, ...rest } = receipt;
+	if (sha256Hex(hashBasis(rest)) !== sha256) reasons.push("hash-mismatch");
+	if (receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION) reasons.push("schema-version-mismatch");
+	const familyReasons = validateFamily(receipt);
+	reasons.push(...familyReasons);
+	return { valid: reasons.length === 0, reasons };
+}
+
+// ---- Family evidence shapes ---------------------------------------------------
+
+export interface VanishEvidence {
+	classification: RecoveryClassification;
+	gitDelta: GitDelta;
+	gitStatusPorcelain: string;
+	untrackedManifest: { path: string; size: number; sha256: string }[];
+	preservation: "snapshot" | "stash" | "block";
+	stashRef: string | null;
+	snapshotComplete: boolean;
+	forbiddenActions: string[];
+}
+
+export interface PromptAcceptanceEvidence {
+	promptSha256: string;
+	rpcCommandId: string;
+	preSubmitState: { isStreaming: boolean; steeringQueueDepth: number; followupQueueDepth: number };
+	preSubmitCursor: number;
+	agentStartCursor: number;
+	acceptedAt: string;
+	singleFlight: true;
+}
+
+export interface ValidationEvidence {
+	command: string;
+	exactCommand: string;
+	cwd: string;
+	exitStatus: number;
+	pass: boolean;
+	commitUnderTest: string | null;
+}
+
+export interface CompletionEvidence {
+	finalCommit: string;
+	branch: string;
+	prUrl: string | null;
+	issueArtifact: string | null;
+	requiredValidationReceiptIds: string[];
+	finalLifecycle: string;
+	finalizedAt: string;
+	blockers: string[];
+}
+
+function validateFamily(receipt: ReceiptEnvelope<unknown>): string[] {
+	switch (receipt.family) {
+		case "vanish":
+			return validateVanish(receipt.evidence as VanishEvidence);
+		case "prompt-acceptance":
+			return validatePromptAcceptance(receipt.evidence as PromptAcceptanceEvidence);
+		case "validation":
+			return validateValidation(receipt.evidence as ValidationEvidence);
+		case "completion":
+			return validateCompletion(receipt.evidence as CompletionEvidence);
+		default:
+			return [`unknown-family:${receipt.family}`];
+	}
+}
+
+function validateVanish(e: VanishEvidence): string[] {
+	const reasons: string[] = [];
+	if (!e || typeof e.gitDelta !== "string") return ["vanish-missing-evidence"];
+	const protectedDelta = e.gitDelta === "dirty" || e.gitDelta === "unknown";
+	if (protectedDelta) {
+		// Hard data-loss invariant: a dirty/unknown delta must be preserved (never blocked-away),
+		// and the destructive actions must be explicitly forbidden.
+		if (e.preservation === "block") reasons.push("vanish-dirty-must-preserve-not-block");
+		for (const action of ["restart-clean", "delete", "reset"]) {
+			if (!Array.isArray(e.forbiddenActions) || !e.forbiddenActions.includes(action)) {
+				reasons.push(`vanish-must-forbid-${action}`);
+			}
+		}
+	}
+	if (e.preservation === "snapshot" && !e.snapshotComplete) reasons.push("vanish-snapshot-incomplete");
+	if (e.preservation === "stash" && !e.stashRef) reasons.push("vanish-stash-missing-ref");
+	return reasons;
+}
+
+function validatePromptAcceptance(e: PromptAcceptanceEvidence): string[] {
+	const reasons: string[] = [];
+	if (!e) return ["acceptance-missing-evidence"];
+	if (e.singleFlight !== true) reasons.push("acceptance-not-single-flight");
+	if (e.preSubmitState?.isStreaming) reasons.push("acceptance-pre-state-streaming");
+	if ((e.preSubmitState?.steeringQueueDepth ?? 1) !== 0) reasons.push("acceptance-steering-queue-nonempty");
+	if ((e.preSubmitState?.followupQueueDepth ?? 1) !== 0) reasons.push("acceptance-followup-queue-nonempty");
+	if (!(e.agentStartCursor > e.preSubmitCursor)) reasons.push("acceptance-agent-start-not-after-cursor");
+	return reasons;
+}
+
+function validateValidation(e: ValidationEvidence): string[] {
+	if (!e || typeof e.exactCommand !== "string") return ["validation-missing-evidence"];
+	return e.pass ? [] : ["validation-failed"];
+}
+
+function validateCompletion(e: CompletionEvidence): string[] {
+	const reasons: string[] = [];
+	if (!e) return ["completion-missing-evidence"];
+	if (!e.finalCommit) reasons.push("completion-missing-commit");
+	if (!e.prUrl && !e.issueArtifact) reasons.push("completion-missing-pr-or-issue");
+	if (!Array.isArray(e.requiredValidationReceiptIds) || e.requiredValidationReceiptIds.length === 0) {
+		reasons.push("completion-missing-validation-receipts");
+	}
+	if (Array.isArray(e.blockers) && e.blockers.length > 0) reasons.push("completion-has-blockers");
+	return reasons;
+}
+
+/** Classifications that MUST have a valid `vanish` receipt before the action proceeds. */
+export function requiresVanishBeforeAction(classification: RecoveryClassification): boolean {
+	return (
+		classification === "restart-clean" ||
+		classification === "restart-preserve-delta" ||
+		classification === "fallback-codex-exec"
+	);
+}

package/src/harness-control-plane/rpc-adapter.ts

@@ -0,0 +1,276 @@
+/**
+ * gajae-code RPC adapter + single-flight acceptance.
+ *
+ * The gajae-code harness is driven via `gjc --mode rpc` (see docs/rpc.md). Acceptance
+ * is a PROTOCOL FACT, not an echo: a prompt is `accepted` only when the RPC command is
+ * acked AND the next `agent_start` event arrives after the pre-submit cursor within the
+ * timeout, with an idle + empty-queue pre-state. Ack alone never means accepted.
+ *
+ * The acceptance logic ({@link singleFlightAccept}) is decoupled from the transport via
+ * the {@link HarnessRpc} interface so it is unit-testable with a fake, while
+ * {@link GajaeCodeRpc} provides the real `gjc --mode rpc` subprocess implementation
+ * (exercised by the M10 e2e suite).
+ */
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+export interface RpcStateSnapshot {
+	isStreaming: boolean;
+	steeringQueueDepth: number;
+	followupQueueDepth: number;
+}
+
+/** Abstract handle to a live gajae-code RPC session. */
+export interface HarnessRpc {
+	getState(): Promise<RpcStateSnapshot>;
+	/** Send a prompt; resolves with the RPC command id and whether it was acked. Does NOT await agent_start. */
+	sendPrompt(prompt: string): Promise<{ commandId: string; ack: boolean }>;
+	/** Monotonic count of events observed so far (the acceptance cursor). */
+	eventCursor(): number;
+	/** Resolve when an `agent_start` event arrives strictly after `afterCursor`, else null on timeout. */
+	waitForAgentStart(afterCursor: number, timeoutMs: number): Promise<{ cursor: number } | null>;
+	close(): Promise<void>;
+	/** Subscribe to parsed event frames (non-ready, non-response), fired AFTER the cursor advances. Returns unsubscribe. */
+	onEventFrame?(listener: (frame: Record<string, unknown>) => void): () => void;
+	/** Whether the underlying RPC subprocess is still alive. */
+	isLive?(): boolean;
+	/** ISO timestamp of the last observed event frame, or null. */
+	lastFrameAt?(): string | null;
+}
+
+export interface AcceptanceResult {
+	accepted: boolean;
+	reason: string;
+	commandId: string | null;
+	preSubmitCursor: number;
+	agentStartCursor: number | null;
+	preSubmitState: RpcStateSnapshot;
+}
+
+/**
+ * Single-flight acceptance: idle + empty-queue pre-state, ack, then the NEXT
+ * `agent_start` after the pre-submit cursor within `timeoutMs`.
+ */
+export async function singleFlightAccept(
+	rpc: HarnessRpc,
+	prompt: string,
+	timeoutMs: number,
+): Promise<AcceptanceResult> {
+	const pre = await rpc.getState();
+	const preSubmitCursor = rpc.eventCursor();
+	if (pre.isStreaming || pre.steeringQueueDepth > 0 || pre.followupQueueDepth > 0) {
+		return {
+			accepted: false,
+			reason: "pre-state-not-idle",
+			commandId: null,
+			preSubmitCursor,
+			agentStartCursor: null,
+			preSubmitState: pre,
+		};
+	}
+	const { commandId, ack } = await rpc.sendPrompt(prompt);
+	if (!ack) {
+		return {
+			accepted: false,
+			reason: "no-ack",
+			commandId,
+			preSubmitCursor,
+			agentStartCursor: null,
+			preSubmitState: pre,
+		};
+	}
+	const started = await rpc.waitForAgentStart(preSubmitCursor, timeoutMs);
+	if (!started) {
+		return {
+			accepted: false,
+			reason: "no-agent-start-within-timeout",
+			commandId,
+			preSubmitCursor,
+			agentStartCursor: null,
+			preSubmitState: pre,
+		};
+	}
+	return {
+		accepted: true,
+		reason: "protocol-ack-single-flight",
+		commandId,
+		preSubmitCursor,
+		agentStartCursor: started.cursor,
+		preSubmitState: pre,
+	};
+}
+
+interface PendingResponse {
+	resolve: (value: Record<string, unknown>) => void;
+	reject: (error: Error) => void;
+}
+
+/**
+ * Real adapter: spawns `gjc --mode rpc --session-dir <dir>` and speaks the JSONL
+ * protocol from docs/rpc.md. Verified end-to-end in the M10 suite.
+ */
+export class GajaeCodeRpc implements HarnessRpc {
+	#proc: ChildProcessWithoutNullStreams;
+	#buffer = "";
+	#cursor = 0;
+	#pending = new Map<string, PendingResponse>();
+	#agentStartCursors: number[] = [];
+	#waiters: {
+		afterCursor: number;
+		resolve: (v: { cursor: number } | null) => void;
+		timer: ReturnType<typeof setTimeout>;
+	}[] = [];
+	#frameListeners: ((frame: Record<string, unknown>) => void)[] = [];
+	#lastFrameAt: string | null = null;
+	#alive = true;
+
+	constructor(opts: { sessionDir: string; command?: string[]; cwd?: string; env?: NodeJS.ProcessEnv }) {
+		const base = opts.command ?? ["gjc", "--mode", "rpc"];
+		const args = [...base.slice(1), "--session-dir", opts.sessionDir];
+		this.#proc = spawn(base[0], args, {
+			cwd: opts.cwd,
+			env: opts.env ?? process.env,
+			stdio: ["pipe", "pipe", "pipe"],
+		}) as ChildProcessWithoutNullStreams;
+		this.#proc.stdout.setEncoding("utf8");
+		this.#proc.stdout.on("data", chunk => this.#onData(chunk as string));
+		this.#proc.on("exit", () => {
+			this.#alive = false;
+		});
+		this.#proc.on("error", () => {
+			this.#alive = false;
+		});
+	}
+
+	#onData(chunk: string): void {
+		this.#buffer += chunk;
+		let idx = this.#buffer.indexOf("\n");
+		while (idx >= 0) {
+			const line = this.#buffer.slice(0, idx).trim();
+			this.#buffer = this.#buffer.slice(idx + 1);
+			if (line) this.#onFrame(line);
+			idx = this.#buffer.indexOf("\n");
+		}
+	}
+
+	#onFrame(line: string): void {
+		let frame: Record<string, unknown>;
+		try {
+			frame = JSON.parse(line) as Record<string, unknown>;
+		} catch {
+			return;
+		}
+		const type = frame.type;
+		if (type === "response") {
+			const id = typeof frame.id === "string" ? frame.id : undefined;
+			if (id && this.#pending.has(id)) {
+				const pending = this.#pending.get(id);
+				this.#pending.delete(id);
+				pending?.resolve(frame);
+			}
+			return;
+		}
+		if (type === "ready") return;
+		// Any other frame is a session/agent event: advance the cursor.
+		this.#cursor += 1;
+		this.#lastFrameAt = new Date().toISOString();
+		if (type === "agent_start") {
+			const cursor = this.#cursor;
+			this.#agentStartCursors.push(cursor);
+			this.#waiters = this.#waiters.filter(w => {
+				if (cursor > w.afterCursor) {
+					clearTimeout(w.timer);
+					w.resolve({ cursor });
+					return false;
+				}
+				return true;
+			});
+		}
+		// Fire-and-forget frame listeners (owner maps + emits). Never await; never let a listener kill the reader.
+		for (const listener of this.#frameListeners) {
+			try {
+				listener(frame);
+			} catch {
+				// swallow listener errors
+			}
+		}
+	}
+
+	#send(command: Record<string, unknown>): Promise<Record<string, unknown>> {
+		const id = randomUUID();
+		return new Promise((resolve, reject) => {
+			this.#pending.set(id, { resolve, reject });
+			this.#proc.stdin.write(`${JSON.stringify({ id, ...command })}\n`, err => {
+				if (err) {
+					this.#pending.delete(id);
+					reject(err);
+				}
+			});
+		});
+	}
+
+	onEventFrame(listener: (frame: Record<string, unknown>) => void): () => void {
+		this.#frameListeners.push(listener);
+		return () => {
+			this.#frameListeners = this.#frameListeners.filter(l => l !== listener);
+		};
+	}
+
+	isLive(): boolean {
+		return this.#alive;
+	}
+
+	lastFrameAt(): string | null {
+		return this.#lastFrameAt;
+	}
+
+	async getState(): Promise<RpcStateSnapshot> {
+		const res = await this.#send({ type: "get_state" });
+		const data = (res.data ?? {}) as Record<string, unknown>;
+		return {
+			isStreaming: Boolean(data.isStreaming),
+			steeringQueueDepth: typeof data.queuedMessageCount === "number" ? data.queuedMessageCount : 0,
+			followupQueueDepth: 0,
+		};
+	}
+
+	async sendPrompt(prompt: string): Promise<{ commandId: string; ack: boolean }> {
+		const id = randomUUID();
+		const ackPromise = new Promise<Record<string, unknown>>((resolve, reject) => {
+			this.#pending.set(id, { resolve, reject });
+			this.#proc.stdin.write(`${JSON.stringify({ id, type: "prompt", message: prompt })}\n`, err => {
+				if (err) {
+					this.#pending.delete(id);
+					reject(err);
+				}
+			});
+		});
+		const res = await ackPromise;
+		return { commandId: id, ack: res.success === true };
+	}
+
+	eventCursor(): number {
+		return this.#cursor;
+	}
+
+	waitForAgentStart(afterCursor: number, timeoutMs: number): Promise<{ cursor: number } | null> {
+		const existing = this.#agentStartCursors.find(c => c > afterCursor);
+		if (existing !== undefined) return Promise.resolve({ cursor: existing });
+		return new Promise(resolve => {
+			const timer = setTimeout(() => {
+				this.#waiters = this.#waiters.filter(w => w.timer !== timer);
+				resolve(null);
+			}, timeoutMs);
+			this.#waiters.push({ afterCursor, resolve, timer });
+		});
+	}
+
+	async close(): Promise<void> {
+		try {
+			this.#proc.stdin.end();
+		} catch {
+			// ignore
+		}
+		this.#proc.kill();
+	}
+}

package/src/harness-control-plane/seams.ts

@@ -0,0 +1,39 @@
+/**
+ * v1 seams (M11). The control plane is harness-agnostic by design, but v1 ships ONLY the
+ * gajae-code adapter. Other harnesses and transports are explicit, designed-not-built seams
+ * that fail closed with a clear `seam_unsupported_in_v1` signal rather than silently degrading.
+ */
+import type { Harness } from "./types";
+
+export const SUPPORTED_HARNESSES: readonly Harness[] = ["gajae-code"];
+
+export const DEFERRED_SEAMS = [
+	"codex-adapter",
+	"omx-adapter",
+	"remote-transport",
+	"global-daemon",
+	"capability-token-auth",
+	"web-viewer",
+	"fleet-control-plane",
+	"rich-tui-coview",
+] as const;
+
+export type DeferredSeam = (typeof DEFERRED_SEAMS)[number];
+
+export function isHarnessSupported(harness: string): harness is Harness {
+	return (SUPPORTED_HARNESSES as readonly string[]).includes(harness);
+}
+
+export interface UnsupportedSeamResult {
+	ok: false;
+	error: string;
+	evidence: { seam: true; name: string; supported: readonly Harness[]; deferred: readonly string[] };
+}
+
+export function unsupportedSeam(name: string): UnsupportedSeamResult {
+	return {
+		ok: false,
+		error: `seam_unsupported_in_v1:${name}`,
+		evidence: { seam: true, name, supported: SUPPORTED_HARNESSES, deferred: DEFERRED_SEAMS },
+	};
+}