@gajae-code/coding-agent 0.2.5 → 0.3.1

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

@@ -0,0 +1,148 @@
+/**
+ * Per-session control endpoint — a Unix domain socket served by the RuntimeOwner so
+ * stateless `gjc harness` CLI calls can route owner-routed primitives (submit, observe,
+ * recover, retire) to the live owner. One JSON request line in, one JSON response line out.
+ *
+ * The owner is the only listener; clients connect per call. When no socket is reachable
+ * the caller falls back to the no-owner behavior (read-only observe, owner-not-live submit).
+ *
+ * FIFO fallback (for platforms/paths where AF_UNIX is unavailable or path-length limited)
+ * is a documented seam tracked as an ADR follow-up.
+ */
+
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as path from "node:path";
+import { MAX_UNIX_SOCKET_PATH_BYTES } from "./storage";
+
+export interface EndpointRequest {
+	verb: string;
+	input: Record<string, unknown>;
+}
+
+export type EndpointHandler = (req: EndpointRequest) => Promise<unknown>;
+
+function frame(value: unknown): string {
+	return `${JSON.stringify(value)}\n`;
+}
+
+export class ControlServer {
+	#server: net.Server | null = null;
+	constructor(
+		readonly socketPath: string,
+		private readonly handler: EndpointHandler,
+	) {}
+
+	async listen(): Promise<void> {
+		await fs.mkdir(path.dirname(this.socketPath), { recursive: true });
+		if (Buffer.byteLength(this.socketPath) > MAX_UNIX_SOCKET_PATH_BYTES) {
+			throw new Error(`socket_path_too_long:${this.socketPath}`);
+		}
+		await fs.rm(this.socketPath, { force: true });
+		await new Promise<void>((resolve, reject) => {
+			const server = net.createServer(socket => this.#onConnection(socket));
+			server.once("error", reject);
+			server.listen(this.socketPath, () => {
+				server.removeListener("error", reject);
+				this.#server = server;
+				resolve();
+			});
+		});
+	}
+
+	#onConnection(socket: net.Socket): void {
+		socket.setEncoding("utf8");
+		let buffer = "";
+		let handled = false;
+		socket.on("data", (chunk: string) => {
+			if (handled) return;
+			buffer += chunk;
+			const idx = buffer.indexOf("\n");
+			if (idx < 0) return;
+			handled = true;
+			const line = buffer.slice(0, idx).trim();
+			void this.#dispatch(line)
+				.then(response => {
+					socket.end(frame(response));
+				})
+				.catch((error: unknown) => {
+					socket.end(frame({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+				});
+		});
+	}
+
+	async #dispatch(line: string): Promise<unknown> {
+		const req = JSON.parse(line) as EndpointRequest;
+		if (!req || typeof req.verb !== "string") throw new Error("bad_request");
+		return this.handler({ verb: req.verb, input: req.input ?? {} });
+	}
+
+	async close(): Promise<void> {
+		const server = this.#server;
+		this.#server = null;
+		if (server) {
+			await new Promise<void>(resolve => server.close(() => resolve()));
+		}
+		await fs.rm(this.socketPath, { force: true });
+	}
+}
+
+export class EndpointUnreachableError extends Error {
+	constructor(
+		readonly socketPath: string,
+		readonly reason = "unreachable",
+	) {
+		super(`endpoint_${reason}:${socketPath}`);
+		this.name = "EndpointUnreachableError";
+	}
+}
+
+/** Call the owner's control endpoint. Rejects with {@link EndpointUnreachableError} when no owner listens or responds. */
+export function callEndpoint(socketPath: string, req: EndpointRequest, timeoutMs = 5_000): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		const socket = net.connect(socketPath);
+		let buffer = "";
+		let settled = false;
+		const done = (fn: () => void): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			fn();
+		};
+		const timer = setTimeout(
+			() => done(() => reject(new EndpointUnreachableError(socketPath, "timeout"))),
+			timeoutMs,
+		);
+		socket.setEncoding("utf8");
+		socket.on("connect", () => socket.write(frame(req)));
+		socket.on("data", (chunk: string) => {
+			buffer += chunk;
+			const idx = buffer.indexOf("\n");
+			if (idx >= 0) {
+				const line = buffer.slice(0, idx).trim();
+				done(() => {
+					try {
+						resolve(JSON.parse(line));
+					} catch {
+						reject(new EndpointUnreachableError(socketPath, "bad_frame"));
+					}
+				});
+			}
+		});
+		socket.on("error", (error: NodeJS.ErrnoException) => {
+			done(() => {
+				if (
+					error.code === "ENOENT" ||
+					error.code === "ECONNREFUSED" ||
+					error.code === "ECONNRESET" ||
+					error.code === "EPIPE"
+				) {
+					reject(new EndpointUnreachableError(socketPath, error.code.toLowerCase()));
+				} else {
+					reject(error);
+				}
+			});
+		});
+	});
+}

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

@@ -0,0 +1,222 @@
+/**
+ * Evidence-gated finalizer (M8).
+ *
+ * `completed: true` ONLY when: every required validation receipt is valid for the commit
+ * under test, the final commit exists on the branch, a PR/issue artifact exists, and the
+ * completion receipt validates with no blockers. Never "the agent said done".
+ *
+ * External effects (running validation commands, git, gh) are injected via {@link FinalizeChecks}
+ * so the gate predicate is unit-testable; {@link defaultFinalizeChecks} provides the real
+ * implementation exercised by the M10 e2e suite.
+ */
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import {
+	buildReceipt,
+	type CompletionEvidence,
+	type ReceiptEnvelope,
+	type ReceiptSubject,
+	type ValidationEvidence,
+	validateReceipt,
+} from "./receipts";
+import { readReceiptIndex, writeReceiptImmutable } from "./storage";
+
+export interface ValidationCommandSpec {
+	name: string;
+	command: string;
+}
+
+export interface ValidationRun {
+	exactCommand: string;
+	cwd: string;
+	exitStatus: number;
+	pass: boolean;
+}
+
+export interface FinalizeChecks {
+	runValidation(spec: ValidationCommandSpec): Promise<ValidationRun>;
+	resolveCommit(): Promise<string | null>;
+	commitOnBranch(commit: string, branch: string): Promise<boolean>;
+	prOrIssue(): Promise<{ prUrl: string | null; issueArtifact: string | null }>;
+}
+
+export interface FinalizeOptions {
+	root: string;
+	sessionId: string;
+	workspace: string;
+	branch: string;
+	requireTests?: boolean;
+	requireCommit?: boolean;
+	requirePr?: boolean;
+	validationCommands?: ValidationCommandSpec[];
+	checks: FinalizeChecks;
+	clock?: () => number;
+}
+
+export interface FinalizeResult {
+	completed: boolean;
+	receiptPath: string | null;
+	validation: { name: string; valid: boolean; exitStatus: number }[];
+	commitHash: string | null;
+	prUrl: string | null;
+	issueArtifact: string | null;
+	blockers: string[];
+}
+
+function receiptId(prefix: string): string {
+	return `${prefix}-${Date.now()}-${randomBytes(4).toString("hex")}`;
+}
+
+export async function runFinalize(opts: FinalizeOptions): Promise<FinalizeResult> {
+	const now = () => new Date(opts.clock ? opts.clock() : Date.now()).toISOString();
+	const blockers: string[] = [];
+	const validation: FinalizeResult["validation"] = [];
+	const validationReceiptIds: string[] = [];
+
+	const commit = await opts.checks.resolveCommit();
+	const subject: ReceiptSubject = { workspace: opts.workspace, branch: opts.branch, head: commit, commit };
+
+	// 1. Validation receipts.
+	for (const spec of opts.validationCommands ?? []) {
+		const run = await opts.checks.runValidation(spec);
+		const evidence: ValidationEvidence = {
+			command: spec.name,
+			exactCommand: run.exactCommand,
+			cwd: run.cwd,
+			exitStatus: run.exitStatus,
+			pass: run.pass,
+			commitUnderTest: commit,
+		};
+		const receipt = buildReceipt<ValidationEvidence>({
+			receiptId: receiptId("val"),
+			sessionId: opts.sessionId,
+			family: "validation",
+			source: "finalizer",
+			subject,
+			evidence,
+			createdAt: now(),
+			valid: run.pass,
+		});
+		await writeReceiptImmutable(opts.root, opts.sessionId, "validation", receipt.receiptId, receipt);
+		const outcome = validateReceipt(receipt);
+		validation.push({ name: spec.name, valid: outcome.valid, exitStatus: run.exitStatus });
+		validationReceiptIds.push(receipt.receiptId);
+		if (opts.requireTests && !outcome.valid) blockers.push(`validation-failed:${spec.name}`);
+	}
+	if (opts.requireTests && (opts.validationCommands?.length ?? 0) === 0) {
+		blockers.push("validation-required-but-none-run");
+	}
+
+	// 2. Commit on branch.
+	if (opts.requireCommit) {
+		if (!commit) blockers.push("missing-commit");
+		else if (!(await opts.checks.commitOnBranch(commit, opts.branch))) blockers.push("commit-not-on-branch");
+	}
+
+	// 3. PR / issue artifact.
+	const artifact = await opts.checks.prOrIssue();
+	if (opts.requirePr && !artifact.prUrl && !artifact.issueArtifact) blockers.push("missing-pr-or-issue");
+
+	// B4: cross-validate the persisted validation receipts (validity + commit freshness) before completion.
+	if (blockers.length === 0) {
+		const persisted = await readReceiptIndex(opts.root, opts.sessionId, "validation");
+		for (const id of validationReceiptIds) {
+			const entry = persisted.find(e => e.receiptId === id);
+			if (!entry) {
+				blockers.push(`missing-validation-receipt:${id}`);
+				continue;
+			}
+			const receipt = JSON.parse(await readFile(entry.path, "utf8")) as ReceiptEnvelope<ValidationEvidence>;
+			if (!validateReceipt(receipt).valid) blockers.push(`validation-receipt-invalid:${id}`);
+			else if (commit && receipt.evidence.commitUnderTest !== commit) blockers.push(`validation-stale-commit:${id}`);
+		}
+	}
+
+	if (blockers.length > 0) {
+		return {
+			completed: false,
+			receiptPath: null,
+			validation,
+			commitHash: commit,
+			prUrl: artifact.prUrl,
+			issueArtifact: artifact.issueArtifact,
+			blockers,
+		};
+	}
+
+	// 4. Completion receipt + predicate.
+	const completion: CompletionEvidence = {
+		finalCommit: commit ?? "",
+		branch: opts.branch,
+		prUrl: artifact.prUrl,
+		issueArtifact: artifact.issueArtifact,
+		requiredValidationReceiptIds: validationReceiptIds,
+		finalLifecycle: "completed",
+		finalizedAt: now(),
+		blockers: [],
+	};
+	const receipt = buildReceipt<CompletionEvidence>({
+		receiptId: receiptId("done"),
+		sessionId: opts.sessionId,
+		family: "completion",
+		source: "finalizer",
+		subject,
+		evidence: completion,
+		createdAt: now(),
+	});
+	const outcome = validateReceipt(receipt);
+	const entry = await writeReceiptImmutable(opts.root, opts.sessionId, "completion", receipt.receiptId, receipt);
+	return {
+		completed: outcome.valid,
+		receiptPath: entry.path,
+		validation,
+		commitHash: commit,
+		prUrl: artifact.prUrl,
+		issueArtifact: artifact.issueArtifact,
+		blockers: outcome.valid ? [] : outcome.reasons,
+	};
+}
+
+function git(workspace: string, args: string[]): string | null {
+	try {
+		return execFileSync("git", args, {
+			cwd: workspace,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+
+/** Real checks: git for commit/branch, gh for PR, Bun.spawn for validation commands. */
+export function defaultFinalizeChecks(workspace: string): FinalizeChecks {
+	return {
+		async runValidation(spec) {
+			const proc = Bun.spawnSync(["bash", "-lc", spec.command], { cwd: workspace, stdout: "pipe", stderr: "pipe" });
+			const exitStatus = proc.exitCode ?? 1;
+			return { exactCommand: spec.command, cwd: workspace, exitStatus, pass: exitStatus === 0 };
+		},
+		async resolveCommit() {
+			return git(workspace, ["rev-parse", "HEAD"]);
+		},
+		async commitOnBranch(commit, branch) {
+			const merged = git(workspace, ["branch", "--contains", commit, "--format=%(refname:short)"]);
+			if (!merged) return false;
+			return merged.split("\n").some(b => b.trim() === branch);
+		},
+		async prOrIssue() {
+			try {
+				const out = execFileSync("gh", ["pr", "view", "--json", "url", "-q", ".url"], {
+					cwd: workspace,
+					encoding: "utf8",
+					stdio: ["ignore", "pipe", "ignore"],
+				}).trim();
+				return { prUrl: out || null, issueArtifact: null };
+			} catch {
+				return { prUrl: null, issueArtifact: null };
+			}
+		},
+	};
+}

package/src/harness-control-plane/frame-mapper.ts

@@ -0,0 +1,286 @@
+/**
+ * Pure mapping from `gjc --mode rpc` event frames (docs/rpc.md) to bounded owner event kinds
+ * and {@link ObservedSignal}s. The owner feeds raw frames through this mapper and emits the
+ * result via its single-writer #emit — the mapper itself performs NO IO and NO appends.
+ *
+ * Hard rule: evidence is BOUNDED — only ids, names, categories, statuses, cursors, timestamps,
+ * and short codes/messages. Never assistant text, message deltas, command output, or raw args.
+ */
+import type { ObservedSignal } from "./types";
+
+export interface MappedFrame {
+	/** Owner event kind (rpc_*). */
+	kind: string;
+	/** Bounded observed signal, or null when the frame carries no user-facing signal. */
+	signal: ObservedSignal | null;
+	/** Bounded evidence — ids/names/statuses/cursors/timestamps/short codes only. */
+	evidence: Record<string, unknown>;
+	/** Severity for the emitted event. */
+	severity: "info" | "warn" | "critical";
+	/** Never-drop frames (must be enqueued in order, never coalesced away). */
+	semantic: boolean;
+	/** Coalescing key for high-frequency non-semantic frames (message id / tool id); null otherwise. */
+	coalesceKey: string | null;
+}
+
+const TEST_RE = /\b(bun test|npm test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|ava)\b/i;
+const TOOL_STATUS_CODES = new Set([
+	"aborted",
+	"blocked",
+	"cancelled",
+	"complete",
+	"completed",
+	"error",
+	"failed",
+	"ok",
+	"pending",
+	"running",
+	"skipped",
+	"success",
+	"timeout",
+]);
+
+export function isTestRunnerTool(toolName?: unknown, command?: unknown): boolean {
+	const name = typeof toolName === "string" ? toolName : "";
+	const cmd = typeof command === "string" ? command : "";
+	if (/test/i.test(name) && name !== "edit" && name !== "read") return true;
+	return TEST_RE.test(cmd);
+}
+
+function str(v: unknown): string | undefined {
+	return typeof v === "string" ? v : undefined;
+}
+function num(v: unknown): number | undefined {
+	return typeof v === "number" ? v : undefined;
+}
+function boundedMessage(v: unknown): string | undefined {
+	const s = typeof v === "string" ? v : undefined;
+	return s === undefined ? undefined : s.slice(0, 200);
+}
+function boundedStatus(v: unknown): string | undefined {
+	if (typeof v !== "string") return undefined;
+	const status = v.trim().toLowerCase();
+	return TOOL_STATUS_CODES.has(status) ? status : undefined;
+}
+function recordObject(v: unknown): Record<string, unknown> | undefined {
+	return v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+/** Extract a tool command from real AgentSessionEvent `args` or a flat fixture frame. Bounded use only — never persisted. */
+function toolCommand(frame: Record<string, unknown>): string | undefined {
+	const args = recordObject(frame.args);
+	const c = args?.command ?? args?.cmd ?? args?.commandLine;
+	if (typeof c === "string") return c;
+	return str(frame.command) ?? str(frame.commandLine);
+}
+/** Derive a tool status, honoring real `isError` booleans as well as bounded status strings. */
+function toolStatus(frame: Record<string, unknown>): string | undefined {
+	if (frame.isError === true) return "error";
+	const flatStatus = boundedStatus(frame.status);
+	if (flatStatus) return flatStatus;
+	for (const candidate of [frame.result, frame.partialResult]) {
+		const result = recordObject(candidate);
+		if (!result) continue;
+		if (result.isError === true) return "error";
+		const status = boundedStatus(result.status) ?? boundedStatus(recordObject(result.details)?.status);
+		if (status) return status;
+	}
+	return undefined;
+}
+
+/**
+ * Map a single RPC frame. Returns null for frames that carry no observability value
+ * (or that the adapter handles itself: `ready`, `response`).
+ */
+export function mapRpcFrame(frame: Record<string, unknown>): MappedFrame | null {
+	const type = str(frame.type);
+	if (!type || type === "ready" || type === "response") return null;
+
+	switch (type) {
+		case "agent_start":
+			return {
+				kind: "rpc_agent_started",
+				signal: "SessionStart",
+				evidence: {},
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			};
+		case "turn_start":
+			return {
+				kind: "rpc_turn_started",
+				signal: "prompt-accepted",
+				evidence: {},
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			};
+		case "turn_end":
+			return {
+				kind: "rpc_turn_ended",
+				signal: null,
+				evidence: {},
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "message_start":
+		case "message_update":
+		case "message_end":
+			return {
+				kind: "rpc_message_activity",
+				signal: null,
+				evidence: { phase: type, messageId: str(frame.messageId) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: `message:${str(frame.messageId) ?? "msg"}`,
+			};
+		case "tool_execution_start": {
+			const toolName = str(frame.toolName);
+			const test = isTestRunnerTool(toolName, toolCommand(frame));
+			return {
+				kind: "rpc_tool_started",
+				signal: test ? "test-running" : "tool-call",
+				evidence: { toolId: str(frame.toolCallId) ?? null, toolName: toolName ?? null },
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			};
+		}
+		case "tool_execution_update": {
+			const toolName = str(frame.toolName);
+			const test = isTestRunnerTool(toolName, toolCommand(frame));
+			return {
+				kind: "rpc_tool_updated",
+				signal: test ? "test-running" : null,
+				evidence: { toolId: str(frame.toolCallId) ?? null, status: toolStatus(frame) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: `tool:${str(frame.toolCallId) ?? "tool"}`,
+			};
+		}
+		case "tool_execution_end": {
+			const toolName = str(frame.toolName);
+			const test = isTestRunnerTool(toolName, toolCommand(frame));
+			const status = toolStatus(frame);
+			return {
+				kind: "rpc_tool_ended",
+				signal: test ? "test-running" : "tool-call",
+				evidence: {
+					toolId: str(frame.toolCallId) ?? null,
+					toolName: toolName ?? null,
+					status: status ?? null,
+					exitCode: num(frame.exitCode) ?? null,
+				},
+				severity: status === "error" ? "warn" : "info",
+				semantic: true,
+				coalesceKey: null,
+			};
+		}
+		case "host_tool_call":
+		case "host_tool_cancel":
+			return {
+				kind: "rpc_host_tool",
+				signal: "tool-call",
+				evidence: { toolName: str(frame.toolName) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "host_uri_request":
+		case "host_uri_cancel":
+			return {
+				kind: "rpc_host_uri",
+				signal: "tool-call",
+				evidence: { operation: str(frame.operation) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "auto_compaction_start":
+		case "auto_compaction_end":
+			return {
+				kind: "rpc_compaction",
+				signal: null,
+				evidence: { phase: type },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "auto_retry_start":
+		case "auto_retry_end":
+			return {
+				kind: "rpc_retry",
+				signal: null,
+				evidence: { phase: type, reason: boundedMessage(frame.reason) ?? null },
+				severity: "warn",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "ttsr_triggered":
+			return {
+				kind: "rpc_ttsr",
+				signal: "error",
+				evidence: { reason: boundedMessage(frame.reason) ?? null },
+				severity: "warn",
+				semantic: true,
+				coalesceKey: null,
+			};
+		case "todo_reminder":
+		case "todo_auto_clear":
+			return {
+				kind: "rpc_todo",
+				signal: null,
+				evidence: { phase: type },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "extension_ui_request":
+			return {
+				kind: "rpc_extension_request",
+				signal: "tool-call",
+				evidence: { method: str(frame.method) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			};
+		case "extension_error":
+			return {
+				kind: "rpc_extension_error",
+				signal: "error",
+				evidence: {
+					code: str(frame.error) ? boundedMessage(frame.error) : null,
+					extensionPath: str(frame.extensionPath) ?? null,
+				},
+				severity: "critical",
+				semantic: true,
+				coalesceKey: null,
+			};
+		case "agent_end": {
+			const failed =
+				Boolean(frame.error) ||
+				frame.aborted === true ||
+				str(frame.outcome) === "failed" ||
+				str(frame.outcome) === "aborted";
+			return failed
+				? {
+						kind: "rpc_agent_failed",
+						signal: "error",
+						evidence: { outcome: str(frame.outcome) ?? "failed" },
+						severity: "critical",
+						semantic: true,
+						coalesceKey: null,
+					}
+				: {
+						kind: "rpc_agent_completed",
+						signal: "completed",
+						evidence: { outcome: "completed" },
+						severity: "info",
+						semantic: true,
+						coalesceKey: null,
+					};
+		}
+		default:
+			return null;
+	}
+}