@estebanforge/pi-antigravity-bridge 1.2.6 → 1.3.0

package/src/stream-events.ts

@@ -0,0 +1,123 @@
+// agy stream-json NDJSON event types + parser.
+//
+// `agy --input-format stream-json --output-format stream-json` emits one JSON
+// object per line on stdout: `init` (conversation binding), `step_update`
+// (user_input / agent_response / checkpoint / tool steps), `result` (terminal).
+// Shapes captured from live output and cross-checked against
+// tianzuo/pi-antigravity lib/events.ts (MIT). Unknown event kinds parse as
+// {kind:"unknown"} so a future agy release degrades instead of crashing the
+// reader loop.
+
+export interface AgyUsage {
+	input_tokens?: number;
+	output_tokens?: number;
+	thinking_tokens?: number;
+	cache_read_tokens?: number;
+	total_tokens?: number;
+}
+
+export type AgyStepState = "ACTIVE" | "DONE" | "ERROR" | string;
+export type AgyStepType = "user_input" | "checkpoint" | "agent_response" | "tool" | (string & {});
+
+export interface AgyToolInfo {
+	name?: string;
+	parameters?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+export interface AgyStepUpdate {
+	step_index?: number;
+	state?: AgyStepState;
+	step_type?: AgyStepType;
+	conversation_id?: string;
+	tool_name?: string;
+	tool_info?: AgyToolInfo;
+	response_text?: string;
+	/** Live agy (1.1.13+): agent_response deltas arrive here, not in response_text. */
+	text_delta?: string;
+	thought_text?: string;
+	thinking_tokens?: number;
+	thinking_signature?: string;
+	duration_seconds?: number;
+	error_message?: string;
+	usage?: AgyUsage;
+	[key: string]: unknown;
+}
+
+export interface AgyResult {
+	status?: string;
+	response?: string;
+	error?: string;
+	usage?: AgyUsage;
+	conversation_id?: string;
+	[key: string]: unknown;
+}
+
+export type ParsedAgyEvent =
+	| { kind: "init"; conversationId?: string; usage?: AgyUsage }
+	| { kind: "step"; step: AgyStepUpdate }
+	| { kind: "result"; result: AgyResult }
+	| { kind: "unknown"; raw: unknown };
+
+/** Parse one stdout line. Never throws; bad JSON / non-objects become "unknown". */
+export function parseAgyLine(line: string): ParsedAgyEvent {
+	const trimmed = line.trim();
+	if (!trimmed) return { kind: "unknown", raw: null };
+	let obj: unknown;
+	try {
+		obj = JSON.parse(trimmed);
+	} catch {
+		return { kind: "unknown", raw: trimmed.slice(0, 200) };
+	}
+	if (typeof obj !== "object" || obj === null) return { kind: "unknown", raw: obj };
+	const rec = obj as Record<string, unknown>;
+	if (rec.event === "init" && typeof rec.init === "object" && rec.init !== null) {
+		const init = rec.init as Record<string, unknown>;
+		return {
+			kind: "init",
+			conversationId:
+				typeof init.conversation_id === "string" ? init.conversation_id : undefined,
+			usage: isUsage(init.usage) ? init.usage : undefined,
+		};
+	}
+	if (rec.event === "step_update" && typeof rec.step_update === "object" && rec.step_update !== null) {
+		return { kind: "step", step: rec.step_update as AgyStepUpdate };
+	}
+	if (rec.event === "result" && typeof rec.result === "object" && rec.result !== null) {
+		return { kind: "result", result: rec.result as AgyResult };
+	}
+	// Tolerate top-level shorthand: some agy builds put the payload at the root.
+	if (rec.event === "init") {
+		return {
+			kind: "init",
+			conversationId: typeof rec.conversation_id === "string" ? rec.conversation_id : undefined,
+			usage: isUsage(rec.usage) ? (rec.usage as AgyUsage) : undefined,
+		};
+	}
+	if (typeof rec.step_type === "string") return { kind: "step", step: rec as AgyStepUpdate };
+	if (typeof rec.status === "string") return { kind: "result", result: rec as AgyResult };
+	return { kind: "unknown", raw: obj };
+}
+
+function isUsage(u: unknown): u is AgyUsage {
+	return typeof u === "object" && u !== null;
+}
+
+/** Map agy usage onto pi-ai's Usage (cost stays zero: subscription quota). */
+export function toPiUsage(
+	u: AgyUsage | undefined,
+	piUsage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		totalTokens: number;
+		cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
+	},
+): void {
+	if (!u) return;
+	piUsage.input = u.input_tokens ?? piUsage.input;
+	piUsage.output = u.output_tokens ?? piUsage.output;
+	piUsage.cacheRead = u.cache_read_tokens ?? piUsage.cacheRead;
+	piUsage.totalTokens = u.total_tokens ?? piUsage.input + piUsage.output;
+}

package/docs/PI-INVOKETOOL-PATCH.md

@@ -1,254 +0,0 @@
-# The `pi.invokeTool` local patch
-
-> Status: **local, not upstream.** This is a patch to the installed `pi` package
-> that adds one method, `pi.invokeTool(name, args)`, to the extension API. It is
-> what lets the pi-antigravity-bridge expose pi's tools to agy over MCP. It is
-> small, self-contained, and gated by a runtime capability check, so pi runs
-> that lack it are unaffected. An upstream PR is the durable fix (planned).
-
-> **Self-applied by the extension.** As of v1.0.0, on first load with the patch
-> missing the bridge **asks you once** whether to apply it (`src/patcher.ts`); if
-> you decline it stays silent and won't ask again until `/agy patch apply`, so
-> you normally never touch these files by hand. The edits below are documented
-> for reference, auditing, and manual recovery. Auto-applier facts:
-> - Targets the **running** pi's `dist/` (located via `realpath(process.argv[1])`
->   and verified by anchor presence), never a sibling extension's decoy copy.
-> - Idempotent and two-phase: validates all anchors before writing, so a pi
->   version that moved the code aborts cleanly with nothing written. The facade
->   file is written **last**, so a crashed/partial patch leaves
->   `hasInvokeTool()` false (safe degraded), never a half-wired chain.
-> - Originals backed up under
->   `~/.pi/agent/antigravity-bridge/pi-patch-backup/<version>-<ts>-<pid>/`.
-> - `/agy patch status|apply|restore` inspects, forces, or rolls it back; restore
->   is version-guarded (refuses across pi versions, no silent downgrade).
-> - Takes effect only after a **full pi restart** (not `/reload`): pi caches its
->   compiled native-ESM core per process.
-
-This document is written for an LLM (or human) that needs to understand exactly
-what was changed, where, and why, without re-deriving it from the codebase.
-
-## What it adds
-
-One new method on pi's `ExtensionAPI`:
-
-```ts
-pi.invokeTool(name: string, args?: Record<string, unknown>, options?: {
-  toolCallId?: string;
-  signal?: AbortSignal;
-  onUpdate?: (update: unknown) => void;
-}): Promise<{ content: unknown[]; details: unknown; isError?: boolean }>
-```
-
-It looks up a registered tool by name and runs its `execute()` **out-of-band**
-(not inside an agent turn), returning the same `{ content, details, isError? }`
-shape the agent itself produces. Upstream pi already exposes tool *metadata*
-(`pi.getAllTools()`) but not tool *execution*; this is the missing sibling.
-
-## Why the bridge needs it
-
-The bridge hosts an MCP server inside pi's process. agy connects to it and asks
-"what tools do you have?" (`tools/list`) and "run this tool" (`tools/call`).
-`tools/list` is served by the already-public `pi.getAllTools()`. `tools/call`
-must actually execute a pi tool, which requires the primitive this patch adds.
-Without it, the bridge can advertise pi's tools but cannot run them, so it
-detects the missing capability at load time and skips the MCP server entirely
-(see `hasInvokeTool()` in `src/mcp-server.ts`).
-
-## The delegation chain (why there are 6 sites)
-
-pi's extension API is a facade. A call travels:
-
-```
-pi.invokeTool()                       (facade, built in loader.js)
-  -> runner.invokeTool()              (ExtensionRunner, runner.js)
-    -> runner.runtime.invokeTool()    (shared runtime object)
-      -> AgentSession.invokeTool()    (the actions bundle wires this in bindCore)
-        -> _toolRegistry.get(name).execute(...)
-```
-
-`bindCore` copies session methods onto a shared `runtime` object that all
-extension APIs reference. That indirection is why a single method must be wired
-at **six** places: the implementation, the actions-bundle binding, the runner's
-copy, the runner's delegating method, the facade method, and the type.
-
-Since pi 0.84.3 there is a **seventh edit**, not part of the chain but the
-switch that makes the chain reachable: the entry redirect in
-`bundle/cli.js` (see Site 7).
-
-## Where it goes (paths are relative to the pi package root)
-
-pi ships **compiled** (`dist/`); there is no `src/` to edit. Find the package
-root:
-
-```bash
-node -e "console.log(require('path').dirname(require.resolve('@earendil-works/pi-coding-agent/package.json')))"
-# typical: ~/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent
-```
-
-All paths below are under `<package>/dist/`. Developed against pi `^0.82.1`;
-anchors verified against `0.84.3` (the `loader.js` facade switched to a local
-`assertActive()` guard in 0.84.3).
-
-### Site 1 — `core/agent-session.js`: the implementation on `AgentSession`
-
-Added immediately after `getToolDefinition(name) { ... }`:
-
-```js
-    /**
-     * LOCAL PATCH (pi-antigravity-bridge): invoke a registered tool by name
-     * out-of-band and return its result. The tool wrapper synthesizes ctx via
-     * its ctxFactory when none is passed. Not upstream pi (yet).
-     */
-    async invokeTool(name, args = {}, options = {}) {
-        const tool = this._toolRegistry.get(name);
-        if (!tool) {
-            throw new Error(`invokeTool: tool "${name}" not found in registry`);
-        }
-        const toolCallId = options.toolCallId ?? `invokeTool:${name}:${Date.now()}`;
-        return tool.execute(toolCallId, args, options.signal ?? undefined, options.onUpdate);
-    }
-```
-
-`_toolRegistry` is `Map<string, AgentTool>` and already exists on `AgentSession`.
-Stored tools are **wrapped** (`wrapRegisteredTools(..., runner)` in
-`tool-definition-wrapper.js`); their `execute` is
-`(toolCallId, params, signal, onUpdate, ctx) => definition.execute(..., ctx ?? ctxFactory?.())`.
-By passing only four args (no `ctx`), the wrapper synthesizes a valid
-`ExtensionContext` via the runner's `createContext()`. No per-turn agent state
-is required; this is what makes out-of-band execution safe.
-
-### Site 2 — `core/agent-session.js`: the `bindCore` actions bundle (CRITICAL)
-
-Inside the object literal passed to `runner.bindCore({ ... })`, immediately
-after `refreshTools: () => this._refreshToolRegistry(),`:
-
-```js
-            invokeTool: (name, args, options) => this.invokeTool(name, args, options),
-```
-
-**This is the easy site to miss.** `bindCore` is the only place session methods
-are wired onto the shared `runtime` object. Without this line,
-`actions.invokeTool` is `undefined`, so site 3 assigns `undefined`, and the
-facade throws `runtime.invokeTool is not a function`.
-
-### Site 3 — `core/extensions/runner.js`: copy onto the shared runtime
-
-In `bindCore`, immediately after `this.runtime.refreshTools = actions.refreshTools;`:
-
-```js
-        this.runtime.invokeTool = actions.invokeTool;
-```
-
-### Site 4 — `core/extensions/runner.js`: the delegating method
-
-On `ExtensionRunner`, immediately after the `getActiveTools() { ... }` method:
-
-```js
-    invokeTool(name, args, options) {
-        this.assertActive();
-        return this.runtime.invokeTool(name, args, options);
-    }
-```
-
-### Site 5 — `core/extensions/loader.js`: the facade method
-
-In the `api` object literal returned to extensions, immediately after the
-`getAllTools() { ... }` entry:
-
-```js
-        invokeTool(name, args, options) {
-            assertActive();
-            return runtime.invokeTool(name, args, options);
-        },
-```
-
-### Site 6 — `core/extensions/types.d.ts`: the type declaration
-
-On the `ExtensionAPI` interface, immediately after `getAllTools(): ToolInfo[];`:
-```ts
-    /**
-     * LOCAL PATCH (pi-antigravity-bridge): invoke a registered tool by name
-     * out-of-band and return { content, details, isError? }. ctx is synthesized.
-     */
-    invokeTool(name: string, args?: Record<string, unknown>, options?: { toolCallId?: string; signal?: AbortSignal; onUpdate?: (update: unknown) => void }): Promise<{ content: unknown[]; details: unknown; isError?: boolean }>;
-```
-
-### Site 7 — `bundle/cli.js`: the entry redirect (pi 0.84.3+)
-
-pi 0.84.3 points its `bin` at `dist/bundle/cli.js`, a bundled runtime with its
-own embedded copy of the core. A process launched from the bundle never loads
-`dist/core/*`, so the six sites above stay inert. The fix is a full-file
-replacement of the tiny bundle entry with a shim that loads the still-shipped
-modular `dist/cli.js`:
-
-```js
-#!/usr/bin/env node
-// LOCAL PATCH (pi-antigravity-bridge): redirect pi's bundled entry to the
-// modular runtime under dist/, where the invokeTool patch sites take effect.
-// Restore via /agy patch restore. See docs/PI-INVOKETOOL-PATCH.md.
-import "../cli.js";
-```
-
-Tradeoff: pi starts through the modular runtime, giving up the bundle's faster
-startup. The patcher validates before writing that the file really is the
-bundled entry (it imports `chunks/`) and that `dist/cli.js` exists; on pre-bundle
-pi the file is absent and this site is skipped entirely.
-
-## How to apply
-
-**You usually don't.** On first load, the extension asks you once whether to
-apply the patch (`src/patcher.ts`); see the note at the top of this document.
-The manual steps below are for reference, auditing, or recovering without the
-extension loaded.
-
-The patch is plain edits to the six compiled files above (plus the entry
-redirect on pi 0.84.3+). Because pi ships no `src/`, there is nothing to
-recompile. (The old "clear jiti's cache" step is a
-no-op on pi 0.82.1+ (including 0.84.3), which sets `moduleCache: false` in its
-extension loader, so jiti never writes an fs cache.)
-
-A `pi` reinstall or update overwrites `dist/` and **removes the patch**, but the
-extension re-applies it on the next start (then prompts you to restart pi).
-Durable fix: merge it upstream.
-
-## How to verify
-
-1. The facade has the method:
-
-   ```bash
-   pi -e /path/to/some-ext.ts --list-models   # ext logs typeof pi.invokeTool
-   # expect: "function"
-   ```
-
-2. It executes a real tool. Quickest: a tiny extension that on `session_start`
-   calls `pi.invokeTool("read", { path: <some file> })` and prints the result,
-   run via `pi -e that-ext.ts --mode rpc` (RPC mode fires `session_start`
-   without a model turn). The returned `content` should hold the file text.
-   (Note: print/`-p` mode hangs on a remote default model before `session_start`
-   fires; RPC mode avoids that.)
-
-## Capability gate (how the bridge stays safe without it)
-
-`src/mcp-server.ts` checks at load time:
-
-```ts
-export function hasInvokeTool(pi: ExtensionAPI): boolean {
-  return typeof (pi as unknown as { invokeTool?: unknown }).invokeTool === "function";
-}
-```
-
-If false, `startMcpServer()` returns `{ ok: false }` immediately and the bridge
-runs exactly as it did before this feature existed: provider + `AskAntigravity`
-tool, no MCP server. So an unpatched pi, or a pi updated past the patch, degrades
-gracefully rather than crashing.
-
-## Scope and risk
-
-- Adds one read-only-by-convention method. Does not modify existing behavior,
-  tool registration, the agent loop, or tool results.
-- Calls the existing wrapped `execute` with a synthesized ctx; tools that depend
-  on live per-turn agent state (an active abort signal, the current message)
-  get a quiescent ctx. This is fine for the stateless tools the bridge exposes
-  (memory, codegraph, search, delegations) and is the same synthesis pi itself
-  uses for out-of-band tool execution.
-- No new dependencies; no changes to persisted state or session format.