@estebanforge/pi-antigravity-bridge 1.3.3 → 1.4.0

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;
+	}
+}

package/src/config.ts

@@ -22,11 +22,27 @@ const CONFIG_PATH = path.join(
 	"config.json",
 );
 
+/** Which turn engine drives turns. "stream-json" is the tested default;
+ *  "acp" is the official-server engine, opt-in (plan §9.5). */
+export type Engine = "stream-json" | "acp";
 export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
 export type BridgeTools = "none" | "mcp" | "all";
 
+export interface AcpConfig {
+	/** Path to agy_acp_server.par. Empty = env AGY_ACP_BIN > PATH. */
+	bin: string;
+	/** Single policy today: auto-approve request_permission in-connection
+	 *  (parity with skipPermissions). Kept as a key so future policies do not
+	 *  change the config shape. */
+	permissions: "auto";
+}
+
 export interface AgyConfig {
+	/** Turn engine. Switching requires a pi restart (drivers wire at load). */
+	engine: Engine;
+	/** Official-server ACP engine options (used when engine = "acp"). */
+	acp: AcpConfig;
 	mode: AgyMode;
 	/** Auto-approve all agy tool permission requests (--dangerously-skip-permissions).
 	 *  Required for non-interactive use: without it, any `run_command` triggers an
@@ -73,6 +89,7 @@ export interface AgyConfig {
 }
 
 const DEFAULTS: AgyConfig = {
+	engine: "stream-json",
 	mode: "accept-edits",
 	skipPermissions: true,
 	defaultModel: "flash",
@@ -80,6 +97,7 @@ const DEFAULTS: AgyConfig = {
 	bridgeTools: "mcp",
 	digest: false,
 	systemPrompt: true,
+	acp: { bin: "", permissions: "auto" },
 };
 
 /** Load config merged over defaults. Env vars override the file when set. */
@@ -99,6 +117,11 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	// The naive OR `env === "plan" || file.mode === "plan"` would ignore an
 	// explicit AGY_MODE=accept-edits when the file says plan, violating the
 	// documented precedence. Check env first.
+	// Engine: narrow to the known set; anything else (incl. the pre-1.3.2
+	// "sqlite" value) falls back to the tested default.
+	const engineRaw = String(process.env.AGY_ENGINE ?? file.engine ?? DEFAULTS.engine).toLowerCase();
+	const engine: Engine = engineRaw === "acp" ? "acp" : "stream-json";
+
 	const mode: AgyMode =
 		process.env.AGY_MODE !== undefined
 			? process.env.AGY_MODE === "plan"
@@ -137,7 +160,17 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		? ["1", "true", "on"].includes(envSys.toLowerCase())
 		: file.systemPrompt ?? DEFAULTS.systemPrompt;
 
+	const fileAcp = (typeof file.acp === "object" && file.acp !== null ? file.acp : {}) as Partial<AcpConfig>;
+	const acp: AcpConfig = {
+		bin:
+			process.env.AGY_ACP_BIN ??
+			(typeof fileAcp.bin === "string" ? fileAcp.bin : DEFAULTS.acp.bin),
+		permissions: "auto",
+	};
+
 	return {
+		engine,
+		acp,
 		mode,
 		skipPermissions,
 		defaultModel,

package/src/diff-render.ts

@@ -188,3 +188,18 @@ function capLines(diff: string, max: number): string {
 	const dropped = lines.length - max;
 	return `${lines.slice(0, max).join("\n")}\n[... ${dropped} more diff lines]`;
 }
+
+/** Format an in-memory before/after pair as a line-numbered diff with pi's
+ *  own generateDiffString. No git subprocess: the ACP engine supplies
+ *  oldText/newText directly in tool_call content[] (Gate C), so the provider
+ *  renders the native diff without touching the repo. Exported for the
+ *  provider; TurnDiffContext keeps the git-sourced path for stream-json. */
+export function formatInlineDiff(
+	oldContent: string,
+	newContent: string,
+	maxDiffLines: number = DEFAULT_MAX_DIFF_LINES,
+): string {
+	if (oldContent === newContent) return "";
+	const { diff } = generateDiffString(oldContent, newContent);
+	return capLines(diff, maxDiffLines);
+}

package/src/driver-types.ts

@@ -0,0 +1,144 @@
+// Engine-agnostic turn-driver contract.
+//
+// Both turn engines (legacy stream-json driver in `driver.ts`, ACP driver in
+// `acp/driver.ts`) implement `TurnDriver`, and everything above them — the
+// provider's stream loop, the G9 round-trip store, the extension wiring —
+// depends on this interface only. Types live here so the legacy module can be
+// deleted (phase 4) without breaking imports.
+//
+// The ACP driver implements the same surface with protocol-native mechanics:
+// no process recycle on profile drift, teardown-based abort (Gate D), and
+// `session/load` resume. See docs/ACP-ADOPTION-PLAN.md section 9.
+
+export type DriverState = "idle" | "starting" | "ready" | "running" | "dead";
+
+export interface DriverProfile {
+	cwd: string;
+	model: string;
+	effort?: string;
+	mode: string;
+	skipPermissions: boolean;
+}
+
+export interface DriverTurnRequest extends DriverProfile {
+	/** Existing conversation/session to resume. Legacy: agy conversation id via
+	 *  `--conversation`. ACP: sessionId via `session/load` (falls back to
+	 *  `session/new` when the server no longer knows it). */
+	conversationId?: string | null;
+	prompt: string;
+	/** Image blocks riding with the prompt. ACP forwards them as typed
+	 *  content blocks (probe 2026-09-03: 64x64 two-tone PNG answered
+	 *  correctly); the legacy CLI prompt is text-only and ignores them. */
+	images?: Array<{ data: string; mimeType: string }>;
+	/** ACP only: pi-side context delivered as a native `embeddedContext`
+	 *  resource block instead of inline prompt text (G1 on ACP). Legacy
+	 *  embeds the digest in the prompt string and ignores this. */
+	contextBlock?: { uri: string; text: string };
+	signal?: AbortSignal;
+	/** Overall turn cap in minutes (default 10). Fractional values are valid
+	 *  (tests use sub-minute caps). */
+	timeoutMin?: number;
+	/** Stdout-inactivity cap in minutes (default 5). */
+	inactivityMin?: number;
+}
+
+export type AgyUsage = {
+	input_tokens?: number;
+	output_tokens?: number;
+	thinking_tokens?: number;
+	cache_read_tokens?: number;
+	total_tokens?: number;
+};
+
+export type DriverActivity =
+	| { type: "text"; delta: string }
+	/** Legacy emits a token count only; ACP carries the actual thought text in
+	 *  `delta`. The provider renders whichever is present. */
+	| { type: "thought"; tokens?: number; delta?: string }
+	| { type: "tool_start"; stepId?: number; name: string; args: Record<string, unknown> }
+	| {
+			type: "tool_done";
+			stepId?: number;
+			name: string;
+			args: Record<string, unknown>;
+			output?: string;
+			durationSeconds?: number;
+			/** ACP only: the server's native edit diff from `tool_call`
+			 *  content[] ({type:"diff", path, oldText?, newText}). Legacy never
+			 *  sets it; the provider renders it without any git subprocess. */
+			diff?: { path: string; oldText?: string; newText: string };
+	  }
+	| { type: "tool_error"; stepId?: number; name: string; message: string }
+	| { type: "usage"; usage: AgyUsage }
+	/** Synthetic: injected by the provider when the MCP bridge receives a call
+	 *  (G9). Parks the turn: output is expected to stall while pi executes the
+	 *  tool, so the driver suspends its idle/overall timers. */
+	| { type: "bridge_call"; callId: string; name: string; args: Record<string, unknown> };
+
+export interface TurnOutcome {
+	conversationId?: string;
+	status: "OK" | "ERROR" | "UNKNOWN";
+	response: string;
+	error?: string;
+	usage?: AgyUsage;
+	finished: boolean;
+	aborted: boolean;
+}
+
+export interface TurnHandle {
+	id: string;
+	/** Resolves when the turn settles (result event, exit, abort, recycle). */
+	outcome: Promise<TurnOutcome>;
+	/** Pull the next activity. Resolves null once the activity stream closes. */
+	next(): Promise<DriverActivity | null>;
+	/** Inject a synthetic activity (bridge inbox). No-op after settle. */
+	pushExternal(activity: DriverActivity): void;
+}
+
+export interface DriverSnapshot {
+	state: DriverState;
+	pid?: number;
+	conversationId?: string;
+	stats: {
+		spawns: number;
+		turns: number;
+		reused: number;
+		recycles: number;
+		lastRecycleReason?: string;
+		recycleReasons: Record<string, number>;
+	};
+	lifecycle: string[];
+	/** Present on ACP snapshots; absent on legacy. */
+	engine?: "acp";
+	acp?: {
+		sessionId?: string;
+		prompts: number;
+		sessionsCreated: number;
+		sessionsLoaded: number;
+		kills: number;
+		/** null = never probed on this server process. */
+		cancelSupported: boolean | null;
+		serverVersion?: string;
+		/** Connections beyond the first this driver process made = server
+		 *  restarts (Gate D kills + stale-exit replacements). */
+		reconnects: number;
+		/** From the initialize handshake agentInfo block. */
+		agentName?: string;
+		agentTitle?: string;
+	};
+}
+
+/** The engine contract. Everything above the driver depends on this interface
+ *  only; `AgyDriver` and `AcpDriver` both implement it. */
+export interface TurnDriver {
+	readonly state: DriverState;
+	readonly activeHandle: TurnHandle | null;
+	run(request: DriverTurnRequest): Promise<TurnHandle>;
+	/** Re-attach to the active turn (pi toolUse continuation). */
+	reentry(): TurnHandle | null;
+	/** Resume turn timers after a parked G9 round-trip settles. */
+	kickIdle(): void;
+	set onTurnEnd(fn: ((outcome: TurnOutcome) => void) | undefined);
+	snapshot(): DriverSnapshot;
+	close(reason: "recycle" | "shutdown", cause?: string): Promise<void>;
+}