@estebanforge/pi-antigravity-bridge 1.3.3 → 1.4.1

package/src/acp/events.ts

@@ -0,0 +1,250 @@
+// ACP `session/update` payload → DriverActivity mapping + stopReason mapping.
+//
+// Pure functions, no I/O: unit-tested against the captured probe transcripts
+// (probe-logs/acp-traffic-run5.jsonl, run6-restart-load-tools.jsonl).
+//
+// Shapes verified live against agy_acp_server 20260818_01_RC01:
+//   session/update params = { sessionId, update: { sessionUpdate: <discriminator>, ... } }
+//   - agent_message_chunk  { content: { type: "text", text } }         (pure deltas)
+//   - agent_thought_chunk  { content: { type: "text", text } }          (thought TEXT)
+//   - user_message_chunk   { content: { type: "text", text } }          (load replay only)
+//   - tool_call            { toolCallId, title, kind, status, content?, locations?, rawInput? }
+//   - tool_call_update     { toolCallId, status: completed|failed, rawOutput? }
+//   - plan                 { entries: [...] }
+//   - available_commands_update { availableCommands: [...] }
+// Usage: ABSENT on RC01 (Gate B) — mapped defensively should a future build add it.
+
+/** Map one `update` object to a driver-level event, or null when the update
+ *  carries nothing the driver consumes (plan/commands are doctor/phase-2
+ *  material; user_message_chunk is load replay and must never reach pi as
+ *  live text). */
+/** Native edit diff carried in tool_call content[] (run 6: edits arrive AS
+ *  DIFFS: {type:"diff", path, newText, optional oldText}). The provider
+ *  formats it in memory — no git subprocess needed on the ACP engine. */
+export interface AcpEditDiff {
+	path: string;
+	oldText?: string;
+	newText: string;
+}
+
+export type MappedUpdate =
+	| { kind: "text"; delta: string }
+	| { kind: "thought"; delta: string }
+	| { kind: "tool_start"; toolCallId: string; name: string; args: Record<string, unknown>; diff?: AcpEditDiff }
+	| { kind: "tool_done"; toolCallId: string; output?: string; diff?: AcpEditDiff }
+	| { kind: "tool_error"; toolCallId: string; message: string }
+	| { kind: "replay_user" }
+	| null;
+
+export function mapUpdate(update: unknown): MappedUpdate {
+	if (typeof update !== "object" || update === null) return null;
+	const u = update as Record<string, unknown>;
+	const kind = u.sessionUpdate;
+	if (typeof kind !== "string") return null;
+	switch (kind) {
+		case "agent_message_chunk":
+			return { kind: "text", delta: chunkText(u.content) };
+		case "agent_thought_chunk":
+			return { kind: "thought", delta: chunkText(u.content) };
+		case "user_message_chunk":
+			return { kind: "replay_user" };
+		case "tool_call": {
+			const id = stringField(u.toolCallId);
+			if (!id) return null;
+			return {
+				kind: "tool_start",
+				toolCallId: id,
+				name: metaToolName(u._meta) ?? toolName(u.title, u.kind),
+				args: rawArguments(u.rawInput),
+				// Edits carry their native diff HERE, on the pending tool_call
+				// frame (run 6:10) — the completed update carries only display
+				// text. contentDiff on the update stays as a future-build
+				// fallback.
+				diff: contentDiff(u.content),
+			};
+		}
+		case "tool_call_update": {
+			const id = stringField(u.toolCallId);
+			if (!id) return null;
+			if (u.status === "failed") {
+				// RC01 echo (run 6, finding 7): after an allow, the APPROVED call
+				// id reports failed with this sentinel while the real work runs
+				// under a different id that reports its own lifecycle. Track
+				// effects, not ids: drop the echo instead of rendering a bogus
+				// failure next to a successful edit.
+				const raw = stringField(u.rawOutput);
+				if (raw?.includes("approved but never executed")) return null;
+				return { kind: "tool_error", toolCallId: id, message: raw ?? "tool failed" };
+			}
+			if (u.status === "completed") {
+				// content[] first (edits carry their diff there); rawOutput alone is
+				// often just the server's display title, not the result (probe
+				// 2026-09-03: completed MCP call, rawOutput "Call bridge_echo").
+				const diff = contentDiff(u.content);
+				return {
+					kind: "tool_done",
+					toolCallId: id,
+					output: contentText(u.content) ?? stringField(u.rawOutput),
+					...(diff ? { diff } : {}),
+				};
+			}
+			return null; // in_progress or unknown status: nothing to render yet
+		}
+		default:
+			// plan / available_commands_update / current_mode_update: consumed by
+			// the driver snapshot / future phases, not mapped to activities.
+			return null;
+	}
+}
+
+/** MCP tools wrap their args in an `arguments` envelope
+ *  ({arguments:{...}}); native tools carry them directly (probe 2026-09-03:
+ *  bridge_echo rawInput {arguments:{text}}, edit_file rawInput {file_path}). */
+function rawArguments(rawInput: unknown): Record<string, unknown> {
+	const rec = recordField(rawInput);
+	const args = rec.arguments;
+	return typeof args === "object" && args !== null && !Array.isArray(args)
+		? (args as Record<string, unknown>)
+		: rec;
+}
+
+/** Clean tool name for MCP tools: the title is "<server>_<tool>" (e.g.
+ *  "pi-bridge_bridge_echo") and the real name hides in _meta.mcp.tool. */
+function metaToolName(meta: unknown): string | undefined {
+	const mcp = recordField(recordField(meta).mcp);
+	const tool = mcp.tool;
+	return typeof tool === "string" && tool.length > 0 ? tool : undefined;
+}
+
+/** First diff entry of a completed tool call: edits carry their native diff
+ *  in content[] as {type:"diff", path, newText, optional oldText} (run 6). */
+function contentDiff(content: unknown): AcpEditDiff | undefined {
+	if (!Array.isArray(content)) return undefined;
+	for (const entry of content) {
+		const e = recordField(entry);
+		if (e.type !== "diff") continue;
+		const path = stringField(e.path);
+		const newText = stringField(e.newText);
+		if (!path || newText === undefined) continue;
+		const oldText = stringField(e.oldText);
+		return oldText !== undefined ? { path, oldText, newText } : { path, newText };
+	}
+	return undefined;
+}
+
+/** Display text of a completed tool call. content[] entries wrap their
+ *  payload ({type:"content", content:{type:"text", text}}); diff entries
+ *  carry no text and are skipped. */
+function contentText(content: unknown): string | undefined {
+	if (!Array.isArray(content)) return undefined;
+	const parts: string[] = [];
+	for (const entry of content) {
+		const inner = recordField(recordField(entry).content ?? entry);
+		if (typeof inner.text === "string" && inner.text.length > 0) parts.push(inner.text);
+	}
+	return parts.length > 0 ? parts.join("\n") : undefined;
+}
+
+/** Extract the text of a content block ({type:"text", text}). */
+function chunkText(content: unknown): string {
+	if (typeof content === "object" && content !== null) {
+		const c = content as Record<string, unknown>;
+		if (typeof c.text === "string") return c.text;
+	}
+	return "";
+}
+
+function stringField(v: unknown): string | undefined {
+	return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function recordField(v: unknown): Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v)
+		? (v as Record<string, unknown>)
+		: {};
+}
+
+/** Derive a tool name from the title ("Run create_file?", "Running edit_file")
+ *  with the kind as fallback. Titles observed live: "Run create_file?",
+ *  "Running edit_file", "Running view_file". */
+export function toolName(title: unknown, kind: unknown): string {
+	if (typeof title === "string") {
+		const m = /(?:Run|Running)\s+([A-Za-z_][\w.]*)/i.exec(title);
+		if (m) return m[1] as string;
+	}
+	return typeof kind === "string" && kind.length > 0 ? kind : "tool";
+}
+
+/** Map a `session/prompt` result stopReason to a TurnOutcome shape.
+ *  Verified live: `end_turn`. Schema enumerates cancelled / max_tokens /
+ *  max_turn_requests / refusal. `cancelled` is unreachable on RC01 (no
+ *  cancel method) but mapped for the day upstream ships it. */
+export function mapStopReason(stopReason: unknown): {
+	status: "OK" | "ERROR";
+	aborted: boolean;
+	error?: string;
+} {
+	switch (stopReason) {
+		case "end_turn":
+			return { status: "OK", aborted: false };
+		case "cancelled":
+			return { status: "OK", aborted: true };
+		case "max_tokens":
+			return { status: "OK", aborted: false, error: "ACP: response hit the token cap" };
+		case "refusal":
+			return { status: "ERROR", aborted: false, error: "ACP: the model refused the request" };
+		case "max_turn_requests":
+			return { status: "ERROR", aborted: false, error: "ACP: turn exceeded the request limit" };
+		default:
+			return { status: "OK", aborted: false };
+	}
+}
+
+/** Defensive accumulation with the cumulative-resend port. RC01 streams pure
+ *  deltas (verified: mid-token splits across the run-5 stress streams), so on
+ *  a compliant server the resend branch stays inert; it exists because the
+ *  same backend's private protocol exhibited exactly this failure mode.
+ *
+ *  Two guards keep a misflip from corrupting the rest of the turn:
+ *  - the flip requires the accumulated text to be at least FLIP_MIN_CHARS,
+ *    because short prefixes ("**", "\n", "#") are trivially extended by
+ *    ordinary markdown deltas;
+ *  - in cumulative mode, a frame that no longer extends the accumulator is
+ *    evidence of a misflip: fall back to append mode instead of slicing. */
+const FLIP_MIN_CHARS = 32;
+
+export class TextAccumulator {
+	#acc = "";
+	#cumulative: boolean | undefined;
+
+	/** Returns the delta to emit, or null when nothing new should be emitted. */
+	append(delta: string): string | null {
+		if (this.#cumulative === undefined) this.#cumulative = false;
+		else if (
+			!this.#cumulative &&
+			this.#acc.length >= FLIP_MIN_CHARS &&
+			delta.length > this.#acc.length &&
+			delta.startsWith(this.#acc)
+		) {
+			this.#cumulative = true;
+		}
+		if (this.#cumulative) {
+			if (!delta.startsWith(this.#acc)) {
+				// Misflip evidence: back to deltas.
+				this.#cumulative = false;
+				this.#acc += delta;
+				return delta;
+			}
+			if (delta.length <= this.#acc.length) return null; // duplicate frame
+			const emit = delta.slice(this.#acc.length);
+			this.#acc = delta;
+			return emit;
+		}
+		this.#acc += delta;
+		return delta;
+	}
+
+	get text(): string {
+		return this.#acc;
+	}
+}

package/src/acp/jsonrpc.ts

@@ -0,0 +1,185 @@
+// Newline-delimited JSON-RPC 2.0 session over a stdio transport.
+//
+// Transport-agnostic by design: the caller supplies a `send` sink (writes one
+// serialized frame + newline to the child's stdin) and feeds incoming bytes to
+// `feed()`. Everything ACP-specific lives in connection.ts.
+//
+// Semantics verified live against agy_acp_server (20260818_01_RC01):
+//   - requests are correlated by numeric id; responses reject the pending
+//     promise on JSON-RPC `error` results;
+//   - server-to-client REQUESTS (session/request_permission, fs/*, terminal/*)
+//     arrive as messages with both `method` and `id` and are answered through
+//     the handler registered via setRequestHandler;
+//   - notifications (session/update, auth_required) carry no id;
+//   - malformed lines are counted and dropped, never fatal (the parseAgyLine
+//     lesson: a chatty banner must not kill the reader loop);
+//   - `abortAll()` rejects every pending request (Gate D teardown: no promise
+//     survives a killed connection).
+
+export interface JsonRpcErrorShape {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+export interface JsonRpcIncoming {
+	id?: number | string | null;
+	method?: string;
+	params?: unknown;
+	result?: unknown;
+	error?: JsonRpcErrorShape;
+}
+
+export type SendFn = (frame: string) => void;
+
+export interface JsonRpcSessionOptions {
+	send: SendFn;
+	/** Server-to-client request (has method + id). Return the result value, or
+	 *  throw to answer with a JSON-RPC error. */
+	onRequest?: (method: string, params: unknown) => Promise<unknown>;
+	/** Server-to-client notification (method, no id). */
+	onNotification?: (method: string, params: unknown) => void;
+	/** Unparseable line (logged, never fatal). */
+	onParseError?: (line: string) => void;
+	/** Default timeout for requests without an explicit one (ms). 0 = none. */
+	defaultTimeoutMs?: number;
+}
+
+interface Pending {
+	resolve: (value: unknown) => void;
+	reject: (err: Error) => void;
+	timer?: ReturnType<typeof setTimeout>;
+	method: string;
+}
+
+export class JsonRpcSession {
+	#send: SendFn;
+	#opts: JsonRpcSessionOptions;
+	#pending = new Map<number, Pending>();
+	#nextId = 1;
+	#aborted = false;
+	#lineBuf = "";
+	parseErrors = 0;
+
+	constructor(opts: JsonRpcSessionOptions) {
+		this.#opts = opts;
+		this.#send = opts.send;
+	}
+
+	/** Feed raw transport bytes. Stdio chunks are NOT newline-aligned: bytes
+	 *  are buffered and only complete lines are parsed (a frame split across a
+	 *  64KB pipe boundary must never be dropped). */
+	feed(chunk: string): void {
+		this.#lineBuf += chunk;
+		const lines = this.#lineBuf.split("\n");
+		this.#lineBuf = lines.pop() ?? "";
+		for (const raw of lines) {
+			const line = raw.trim();
+			if (!line) continue;
+			let msg: JsonRpcIncoming;
+			try {
+				msg = JSON.parse(line) as JsonRpcIncoming;
+			} catch {
+				this.parseErrors += 1;
+				this.#opts.onParseError?.(line.slice(0, 200));
+				continue;
+			}
+			this.#handleMessage(msg);
+		}
+	}
+
+	#handleMessage(msg: JsonRpcIncoming): void {
+		// Response to one of our requests.
+		if (msg.method === undefined && msg.id !== undefined && msg.id !== null) {
+			const id = Number(msg.id);
+			const pending = this.#pending.get(id);
+			if (!pending) return; // late response to an aborted request: drop
+			this.#pending.delete(id);
+			if (pending.timer) clearTimeout(pending.timer);
+			if (msg.error) {
+				pending.reject(new JsonRpcResponseError(msg.error));
+			} else {
+				pending.resolve(msg.result);
+			}
+			return;
+		}
+		if (msg.method === undefined) return;
+		// Server-to-client request: must be answered with the same id. The
+		// handler is always invoked through Promise.resolve() so a synchronous
+		// throw can never escape into the reader loop.
+		if (msg.id !== undefined && msg.id !== null) {
+			const id = msg.id;
+			const handler = this.#opts.onRequest;
+			if (!handler) {
+				this.#sendError(id, -32601, `client does not support method: ${msg.method}`);
+				return;
+			}
+			void Promise.resolve()
+				.then(() => handler(msg.method as string, msg.params))
+				.then((result) => {
+					if (this.#aborted) return;
+					this.#send(JSON.stringify({ jsonrpc: "2.0", id, result: result ?? {} }));
+				})
+				.catch((err: unknown) => {
+					if (this.#aborted) return;
+					const message = err instanceof Error ? err.message : String(err);
+					this.#sendError(id, -32000, message);
+				});
+			return;
+		}
+		// Notification.
+		this.#opts.onNotification?.(msg.method, msg.params);
+	}
+
+	#sendError(id: number | string, code: number, message: string): void {
+		if (this.#aborted) return;
+		this.#send(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
+	}
+
+	/** Send a request. Resolves with the result value; rejects on error
+	 *  responses (JsonRpcResponseError), timeouts, or abortAll(). */
+	request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown> {
+		if (this.#aborted) return Promise.reject(new Error("connection aborted"));
+		const id = this.#nextId++;
+		const effective = timeoutMs ?? this.#opts.defaultTimeoutMs ?? 0;
+		return new Promise<unknown>((resolve, reject) => {
+			const pending: Pending = { resolve, reject, method };
+			if (effective > 0) {
+				pending.timer = setTimeout(() => {
+					this.#pending.delete(id);
+					reject(new Error(`ACP request timed out after ${effective}ms: ${method}`));
+				}, effective);
+			}
+			this.#pending.set(id, pending);
+			this.#send(JSON.stringify({ jsonrpc: "2.0", id, method, params: params ?? {} }));
+		});
+	}
+
+	/** Reject every pending request (Gate D teardown). The transport is going
+	 *  away; nothing will ever be written again. */
+	abortAll(reason: string): void {
+		this.#aborted = true;
+		for (const [id, pending] of this.#pending) {
+			if (pending.timer) clearTimeout(pending.timer);
+			pending.reject(new Error(`${reason} (request: ${pending.method})`));
+			this.#pending.delete(id);
+		}
+	}
+
+	get pendingCount(): number {
+		return this.#pending.size;
+	}
+}
+
+/** A JSON-RPC `error` result, preserving code + data (the -32602 `loc` paths
+ *  and the -32601 method name are correction oracles; see the reference doc). */
+export class JsonRpcResponseError extends Error {
+	readonly code: number;
+	readonly data: unknown;
+	constructor(error: JsonRpcErrorShape) {
+		super(error.message);
+		this.name = "JsonRpcResponseError";
+		this.code = error.code;
+		this.data = error.data;
+	}
+}