@anhlp/alp-runtime 0.0.0-stage → 0.10.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @anhlp/alp-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Viewer-neutral orchestration and normalized native provider adapters.
+
+Build: `npm run build --workspace=@anhlp/alp-runtime`. Test: `npm run test --workspace=@anhlp/alp-runtime`.
+
+Public imports use the package root and its explicitly exported subpaths. See [architecture, provider extension, compatibility and release instructions](../../docs/modular-monorepo.md).

package/dist/acp-transport.d.ts

@@ -0,0 +1,107 @@
+import { type PermissionProfile } from '@anhlp/alp-core/permissions';
+/**
+ * ACP agents (ALPD §46): a generic transport for any agent that speaks the Agent Client
+ * Protocol v1 over stdio, such as Gemini CLI or opencode. It maps the runtime's
+ * normalized protocol (thread/start, turn/start, item and turn notifications) to ACP's
+ * initialize, session/new, session/prompt and session/update.
+ *
+ * What ACP does not have, ALP does without: instructions go in the first prompt, mail
+ * waits for the turn to end (no steer), and a session resumes only when the agent can
+ * load one. ALP's tools reach the agent as an MCP server ("alp") that the agent starts:
+ * a small bridge process connected back to this transport by a local socket.
+ */
+export type AcpProvider = {
+    id: string;
+    label: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    models?: Array<{
+        id: string;
+        label?: string;
+        description?: string;
+    }>;
+    additionalModels?: Array<{
+        id: string;
+        label?: string;
+        description?: string;
+    }>;
+    enabled?: boolean;
+};
+type Listener = (method: string, params: any) => void;
+type RequestHandler = (method: string, params: any) => Promise<unknown>;
+/** What ALP decides about an ACP agent's permission request. */
+export type AcpPermission = {
+    kind: string;
+    title: string;
+    command?: string;
+    paths: string[];
+    alpTool: boolean;
+};
+/** What an ACP permission request asks for: its tool kind, the command it runs, and the paths it touches. */
+export declare function acpPermission(toolCall: any, tools: string[]): AcpPermission;
+/**
+ * Whether ALP lets an ACP agent use a tool: ALP's tools always; then the profile's
+ * Bash rules for a command; then the session's mode. Read-only allows reading;
+ * workspace-write also changing files inside the workspace and running commands, which
+ * only the agent's own sandbox, if it has one, contains; full access allows everything.
+ * 'mode' is beyond the mode: the profile decides whether ALP asks the user.
+ */
+export declare function acpDecision(request: AcpPermission, mode: string, profile: PermissionProfile | null | undefined, workdir: string): 'allow' | 'deny' | 'rule' | 'mode';
+/** The text ALP shows the user when an ACP agent asks for a permission. */
+export declare function acpWhat(request: AcpPermission): string;
+/** Maps an ACP agent over stdio to the normalized runtime protocol. */
+export declare class AcpTransport {
+    private readonly provider;
+    private readonly cwd;
+    private readonly env;
+    private child?;
+    private exit;
+    private sequence;
+    private pending;
+    private listeners;
+    private failures;
+    private requestHandler?;
+    private closed;
+    private capabilities;
+    private sessionId;
+    private config;
+    /** Instructions go with the first prompt of a new session; a loaded one has them already. */
+    private instructionsSent;
+    private loading;
+    private activeTurn?;
+    /** The running prompt; a cancelled one still answers before the next starts. */
+    private prompting?;
+    /** Text of the running turn's current message; a tool call starts the next one. */
+    private message?;
+    private messages;
+    private toolCalls;
+    /** Permission questions of the running turn, answered cancelled when it is cancelled. */
+    private questions;
+    private bridge?;
+    private tools;
+    constructor(provider: AcpProvider, cwd: string, env: NodeJS.ProcessEnv);
+    initialize(): Promise<void>;
+    onNotification(listener: Listener): () => boolean;
+    onFailure(listener: (error: Error) => void): () => boolean;
+    onRequest(handler: RequestHandler): void;
+    request(method: string, params: any): Promise<any>;
+    /** Picks the session's model when ALP was given one and the agent offers a choice. */
+    private chooseModel;
+    private endTurn;
+    private closeMessage;
+    private update;
+    /** The agent asks before using a tool; ALP's runtime decides, and the answer picks one of the agent's options. */
+    private permission;
+    private receive;
+    private call;
+    private write;
+    /** Starts the socket ALP's MCP bridge connects to, and returns the server entry for the agent. */
+    private openBridge;
+    private serveBridge;
+    private toolCall;
+    private emit;
+    private fail;
+    close(): Promise<void>;
+}
+export {};

package/dist/acp-transport.js

@@ -0,0 +1,464 @@
+// packages/runtime/src/acp-transport.ts
+import { spawn, execFile } from "node:child_process";
+import { randomBytes, randomUUID } from "node:crypto";
+import { rmSync } from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { commandDecision, unwrapShell } from "@anhlp/alp-core/permissions";
+var BRIDGE = `
+const net = require('node:net');
+const readline = require('node:readline');
+const socket = net.connect(process.env.ALP_BRIDGE_SOCKET);
+const waiting = new Map();
+let sequence = 0;
+let buffer = '';
+socket.setEncoding('utf8');
+socket.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');
+socket.on('data', data => {
+  buffer += data;
+  for (let index; (index = buffer.indexOf('\\n')) >= 0;) {
+    const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+    try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}
+  }
+});
+socket.on('close', () => process.exit(0));
+socket.on('error', () => process.exit(1));
+const ask = message => new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });
+const send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');
+readline.createInterface({ input: process.stdin }).on('line', async line => {
+  let message; try { message = JSON.parse(line); } catch { return; }
+  if (message.id === undefined || message.id === null) return;
+  try {
+    if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });
+    if (message.method === 'ping') return send({ id: message.id, result: {} });
+    if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }
+    if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }
+    send({ id: message.id, error: { code: -32601, message: 'Method not found' } });
+  } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }
+});
+process.stdin.on('end', () => process.exit(0));
+`;
+var READERS = ["read", "search", "think", "fetch"];
+var inside = (file, root) => {
+  const relative = path.relative(root, file);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+function acpPermission(toolCall, tools) {
+  const raw = toolCall?.rawInput;
+  const kind = typeof toolCall?.kind === "string" ? toolCall.kind : "other";
+  const title = typeof toolCall?.title === "string" ? toolCall.title : "";
+  const command = kind === "execute" ? typeof raw?.command === "string" ? raw.command : Array.isArray(raw?.command) ? raw.command.join(" ") : title || void 0 : void 0;
+  const paths = (Array.isArray(toolCall?.locations) ? toolCall.locations : []).map((location) => location?.path).filter((value) => typeof value === "string");
+  const named = `${title} ${typeof toolCall?.name === "string" ? toolCall.name : ""}`;
+  const alpTool = !["execute", "edit", "delete", "move"].includes(kind) && tools.some((tool) => new RegExp(`\\b${tool}\\b`).test(named));
+  return { kind, title, ...command ? { command } : {}, paths, alpTool };
+}
+function acpDecision(request, mode, profile, workdir) {
+  if (request.alpTool) return "allow";
+  const rule = request.command !== void 0 && profile ? commandDecision(profile, request.command) : void 0;
+  if (rule === "deny") return "deny";
+  if (rule === "allow") return "allow";
+  if (rule === "ask") return "rule";
+  if (mode === "full-access" || READERS.includes(request.kind)) return "allow";
+  if (mode === "workspace-write") {
+    const outside = request.paths.some((file) => !inside(path.resolve(workdir, file), workdir) && !inside(path.resolve(file), os.tmpdir()));
+    if (!outside) return "allow";
+  }
+  return "mode";
+}
+function acpWhat(request) {
+  if (request.command !== void 0) return `run \`${unwrapShell(request.command).slice(0, 400)}\``;
+  return `${request.kind === "other" ? "use" : request.kind} ${request.title ? `\`${request.title.slice(0, 300)}\`` : "a tool"}${request.paths.length ? ` (${request.paths.slice(0, 5).join(", ")})` : ""}`;
+}
+function acpServers(servers, http) {
+  return Object.entries(servers).map(([name, server]) => {
+    if (server.url) {
+      if (!http) throw new Error(`MCP server '${name}' is HTTP, which this ACP agent does not take; use a stdio server`);
+      return { type: "http", name, url: server.url, headers: Object.entries(server.http_headers ?? {}).map(([key, value]) => ({ name: key, value: String(value) })) };
+    }
+    return { name, command: server.command, args: server.args ?? [], env: Object.entries(server.env ?? {}).map(([key, value]) => ({ name: key, value: String(value) })) };
+  });
+}
+var AcpTransport = class {
+  constructor(provider, cwd, env) {
+    this.provider = provider;
+    this.cwd = cwd;
+    this.env = env;
+  }
+  child;
+  exit = Promise.resolve();
+  sequence = 0;
+  pending = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  failures = /* @__PURE__ */ new Set();
+  requestHandler;
+  closed = false;
+  capabilities = {};
+  sessionId = "";
+  config;
+  /** Instructions go with the first prompt of a new session; a loaded one has them already. */
+  instructionsSent = false;
+  loading = false;
+  activeTurn;
+  /** The running prompt; a cancelled one still answers before the next starts. */
+  prompting;
+  /** Text of the running turn's current message; a tool call starts the next one. */
+  message;
+  messages = 0;
+  toolCalls = /* @__PURE__ */ new Map();
+  /** Permission questions of the running turn, answered cancelled when it is cancelled. */
+  questions = /* @__PURE__ */ new Set();
+  bridge;
+  tools = [];
+  async initialize() {
+    if (/\.(cmd|bat|ps1)$/i.test(this.provider.command)) throw new Error(`${this.provider.label}: the command must be a native executable, not a shell launcher`);
+    const child = spawn(this.provider.command, this.provider.args, { cwd: this.cwd, env: { ...this.env, ...this.provider.env }, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    this.child = child;
+    this.exit = new Promise((resolve) => {
+      child.once("close", () => resolve());
+      child.once("error", () => resolve());
+    });
+    child.stderr.on("data", () => {
+    });
+    child.stdin.on("error", (error) => this.fail(error));
+    child.on("error", (error) => this.fail(new Error(`${this.provider.label} did not start: ${error.message}`)));
+    child.on("close", (code) => {
+      if (!this.closed) this.fail(new Error(`${this.provider.label} exited (${code})`));
+    });
+    createInterface({ input: child.stdout }).on("line", (line) => this.receive(line));
+    const result = await this.call("initialize", {
+      protocolVersion: 1,
+      // The agent reads, writes and runs commands with its own tools; ALP answers its permission requests.
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: "alp", title: "ALP", version: "0.0.0" }
+    }, 3e4);
+    if (result?.protocolVersion !== 1) throw new Error(`${this.provider.label} speaks ACP version ${result?.protocolVersion}; ALP speaks version 1`);
+    this.capabilities = result.agentCapabilities ?? {};
+  }
+  onNotification(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  onFailure(listener) {
+    this.failures.add(listener);
+    return () => this.failures.delete(listener);
+  }
+  onRequest(handler) {
+    this.requestHandler = handler;
+  }
+  async request(method, params) {
+    if (this.closed) throw new Error("Runtime is closed");
+    if (method === "thread/start" || method === "thread/resume") {
+      this.config = params;
+      this.tools = params.dynamicTools ?? [];
+      const mcpServers = [...acpServers(params.mcpServers ?? {}, Boolean(this.capabilities.mcpCapabilities?.http)), ...this.tools.length ? [await this.openBridge()] : []];
+      if (method === "thread/resume") {
+        if (!this.capabilities.loadSession) throw new Error(`${this.provider.label} cannot resume a session: it does not support session/load`);
+        this.loading = true;
+        try {
+          await this.call("session/load", { sessionId: params.threadId, cwd: params.cwd, mcpServers }, 12e4);
+        } finally {
+          this.loading = false;
+        }
+        this.sessionId = params.threadId;
+        this.instructionsSent = true;
+      } else {
+        const result = await this.call("session/new", { cwd: params.cwd, mcpServers }, 12e4);
+        this.sessionId = result.sessionId;
+        await this.chooseModel(result.models, result.configOptions);
+      }
+      return { thread: { id: this.sessionId, turns: [] }, cwd: params.cwd, model: params.model, reasoningEffort: params.thinking };
+    }
+    if (method === "turn/start") {
+      if (!this.sessionId) throw new Error(`${this.provider.label} session is not open`);
+      if (this.prompting) await Promise.race([this.prompting, new Promise((resolve) => setTimeout(resolve, 1e4).unref())]);
+      if (this.closed) throw new Error("Runtime is closed");
+      const turnId = randomUUID();
+      this.activeTurn = turnId;
+      this.message = void 0;
+      const prompt = (params.input ?? []).filter((part) => typeof part?.text === "string").map((part) => ({ type: "text", text: part.text }));
+      if (!this.instructionsSent && this.config?.developerInstructions) {
+        prompt.unshift({ type: "text", text: `Instructions from ALP, which runs you. Follow them for this whole session.
+
+${this.config.developerInstructions}` });
+        this.instructionsSent = true;
+      }
+      this.prompting = this.call("session/prompt", { sessionId: this.sessionId, prompt }).then(
+        (result) => this.endTurn(turnId, result?.stopReason),
+        (error) => this.endTurn(turnId, "error", error instanceof Error ? error.message : String(error))
+      ).finally(() => {
+        if (this.activeTurn === void 0 || this.activeTurn === turnId) this.prompting = void 0;
+      });
+      return { turn: { id: turnId } };
+    }
+    if (method === "turn/steer") throw new Error(`${this.provider.label} takes no messages during a turn; ALP delivers them when it ends`);
+    if (method === "turn/interrupt") {
+      if (this.sessionId) this.write({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId: this.sessionId } });
+      for (const answer of this.questions) answer({ outcome: { outcome: "cancelled" } });
+      this.questions.clear();
+      return {};
+    }
+    if (method === "session/configure") return {};
+    if (method === "thread/delete") return {};
+    throw new Error(`${this.provider.label} does not support '${method}'`);
+  }
+  /** Picks the session's model when ALP was given one and the agent offers a choice. */
+  async chooseModel(models, configOptions) {
+    const wanted = this.config?.model?.includes("/") ? this.config.model.slice(this.config.model.indexOf("/") + 1) : void 0;
+    if (!wanted) return;
+    const config = configOptions?.find((option) => option.category === "model" && option.type === "select");
+    if (config) {
+      if (config.currentValue === wanted) return;
+      const options = (config.options ?? []).flatMap((option) => option.options ?? [option]);
+      if (!options.some((option) => option.value === wanted)) throw new Error(`${this.provider.label} has no model '${wanted}'`);
+      await this.call("session/set_config_option", { sessionId: this.sessionId, configId: config.id, value: wanted }, 3e4);
+      return;
+    }
+    if (models?.currentModelId === wanted) return;
+    if (!Array.isArray(models?.availableModels)) throw new Error(`${this.provider.label} does not let ALP choose its model; use acp:${this.provider.id} alone`);
+    if (!models.availableModels.some((model) => model?.modelId === wanted)) throw new Error(`${this.provider.label} has no model '${wanted}'`);
+    await this.call("session/set_model", { sessionId: this.sessionId, modelId: wanted }, 3e4);
+  }
+  endTurn(turnId, stopReason, error) {
+    if (this.closed || this.activeTurn !== turnId) return;
+    this.closeMessage();
+    this.activeTurn = void 0;
+    this.toolCalls.clear();
+    const status = stopReason === "end_turn" ? "completed" : stopReason === "cancelled" ? "interrupted" : "failed";
+    this.emit("turn/completed", {
+      threadId: this.sessionId,
+      turn: { id: turnId, status, ...status === "failed" ? { error: { message: error ?? `${this.provider.label} stopped: ${stopReason}` } } : {} }
+    });
+  }
+  closeMessage() {
+    if (this.message?.text) this.emit("item/completed", { threadId: this.sessionId, item: { type: "agentMessage", id: this.message.id, text: this.message.text } });
+    this.message = void 0;
+  }
+  update(update) {
+    if (this.loading || !this.activeTurn || !update) return;
+    const kind = update.sessionUpdate;
+    if (kind === "agent_message_chunk") {
+      const text = update.content?.type === "text" && typeof update.content.text === "string" ? update.content.text : "";
+      if (!text) return;
+      this.message ??= { id: `acp-${this.activeTurn}-${++this.messages}`, text: "" };
+      this.message.text += text;
+      this.emit("item/agentMessage/delta", { threadId: this.sessionId, itemId: this.message.id, delta: text });
+      return;
+    }
+    if (kind === "tool_call" || kind === "tool_call_update") {
+      const id = String(update.toolCallId ?? "");
+      if (!id) return;
+      let call = this.toolCalls.get(id);
+      if (!call) {
+        const request = acpPermission(update, this.tools.map((tool) => tool.name));
+        call = { command: request.command ?? `${request.kind}: ${request.title}`, alp: request.alpTool };
+        this.toolCalls.set(id, call);
+        this.closeMessage();
+        if (!call.alp) this.emit("item/started", { threadId: this.sessionId, item: { type: "commandExecution", id, command: call.command, cwd: this.cwd, status: "inProgress", aggregatedOutput: "" } });
+      }
+      if ((update.status === "completed" || update.status === "failed") && !call.alp) {
+        const output = (Array.isArray(update.content) ? update.content : []).map((part) => part?.type === "content" && part.content?.type === "text" ? part.content.text : part?.type === "diff" ? `diff ${part.path}` : "").filter(Boolean).join("\n");
+        this.emit("item/completed", { threadId: this.sessionId, item: { type: "commandExecution", id, command: call.command, cwd: this.cwd, status: update.status, exitCode: update.status === "failed" ? 1 : 0, aggregatedOutput: output } });
+      }
+      return;
+    }
+    if (kind === "usage_update" && typeof update.used === "number") {
+      const last = { totalTokens: update.used };
+      this.emit("thread/tokenUsage/updated", { threadId: this.sessionId, turnId: this.activeTurn, tokenUsage: { last, total: last, ...typeof update.size === "number" ? { modelContextWindow: update.size } : {} } });
+    }
+  }
+  /** The agent asks before using a tool; ALP's runtime decides, and the answer picks one of the agent's options. */
+  async permission(params) {
+    const options = Array.isArray(params?.options) ? params.options : [];
+    const pick = (...kinds) => kinds.map((kind) => options.find((option2) => option2?.kind === kind)).find(Boolean);
+    if (!this.activeTurn || !this.requestHandler) return { outcome: { outcome: "cancelled" } };
+    const request = acpPermission(params?.toolCall, this.tools.map((tool) => tool.name));
+    const question = new Promise((resolve) => this.questions.add(resolve));
+    const answer = await Promise.race([this.requestHandler("item/acp/permission", request), question]);
+    if (answer?.outcome) return answer;
+    const option = answer?.allow ? pick("allow_once", "allow_always") : pick("reject_once", "reject_always");
+    return option ? { outcome: { outcome: "selected", optionId: option.optionId } } : { outcome: { outcome: "cancelled" } };
+  }
+  receive(line) {
+    if (line.length > 16 * 1024 * 1024) {
+      this.fail(new Error(`${this.provider.label} sent a frame over the size limit`));
+      return;
+    }
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (message.method && message.id !== void 0) {
+      const answer = message.method === "session/request_permission" ? this.permission(message.params) : Promise.reject(Object.assign(new Error(`ALP does not offer '${message.method}'`), { code: -32601 }));
+      answer.then(
+        (result) => {
+          if (!this.closed) this.write({ jsonrpc: "2.0", id: message.id, result });
+        },
+        (error) => {
+          if (!this.closed) this.write({ jsonrpc: "2.0", id: message.id, error: { code: error?.code ?? -32603, message: error instanceof Error ? error.message : String(error) } });
+        }
+      );
+    } else if (message.id !== void 0) {
+      const waiter = this.pending.get(message.id);
+      if (!waiter) return;
+      this.pending.delete(message.id);
+      clearTimeout(waiter.timer);
+      if (message.error) {
+        const auth = message.error.code === -32e3 || /auth/i.test(String(message.error.message ?? ""));
+        waiter.reject(new Error(auth ? `${this.provider.label} needs you to sign in first: run it once in a terminal and log in (${message.error.message ?? "authentication required"})` : `${this.provider.label}: ${message.error.message ?? "request failed"}`));
+      } else waiter.resolve(message.result);
+    } else if (message.method === "session/update" && message.params?.sessionId === this.sessionId) {
+      this.update(message.params.update);
+    }
+  }
+  call(method, params, timeout) {
+    if (this.closed) return Promise.reject(new Error("Runtime is closed"));
+    const id = ++this.sequence;
+    return new Promise((resolve, reject) => {
+      const timer = timeout ? setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${this.provider.label} did not answer ${method} within ${timeout / 1e3} s`));
+      }, timeout) : void 0;
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.write({ jsonrpc: "2.0", id, method, params });
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+  write(value) {
+    if (this.closed || !this.child) throw new Error("Runtime is closed");
+    this.child.stdin.write(`${JSON.stringify(value)}
+`);
+  }
+  /** Starts the socket ALP's MCP bridge connects to, and returns the server entry for the agent. */
+  async openBridge() {
+    if (!this.bridge) {
+      const token = randomBytes(16).toString("hex");
+      const name = `alp-acp-${randomBytes(6).toString("hex")}`;
+      const socket = process.platform === "win32" ? `\\\\.\\pipe\\${name}` : path.join(os.tmpdir(), `${name}.sock`);
+      const connections = /* @__PURE__ */ new Set();
+      const server = net.createServer((connection) => {
+        connections.add(connection);
+        connection.once("close", () => connections.delete(connection));
+        this.serveBridge(connection, token);
+      });
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socket, () => resolve());
+      });
+      this.bridge = { server, socket, token, connections };
+    }
+    const electron = process.versions.electron ? [{ name: "ELECTRON_RUN_AS_NODE", value: "1" }] : [];
+    return { name: "alp", command: process.execPath, args: ["-e", BRIDGE], env: [{ name: "ALP_BRIDGE_SOCKET", value: this.bridge.socket }, { name: "ALP_BRIDGE_TOKEN", value: this.bridge.token }, ...electron] };
+  }
+  serveBridge(connection, token) {
+    let trusted = false;
+    connection.setEncoding("utf8");
+    connection.on("error", () => {
+    });
+    const reply = (value) => {
+      if (!connection.destroyed) connection.write(`${JSON.stringify(value)}
+`);
+    };
+    createInterface({ input: connection }).on("line", async (line) => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        connection.destroy();
+        return;
+      }
+      if (!trusted) {
+        if (message.token !== token) {
+          connection.destroy();
+          return;
+        }
+        trusted = true;
+        return;
+      }
+      if (message.op === "list") {
+        reply({ id: message.id, tools: this.tools.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema ?? { type: "object" } })) });
+        return;
+      }
+      if (message.op === "call") reply({ id: message.id, result: await this.toolCall(String(message.name), message.arguments ?? {}) });
+    });
+  }
+  async toolCall(tool, args) {
+    if (!this.requestHandler || !this.activeTurn || !this.tools.some((candidate) => candidate.name === tool)) {
+      return { content: [{ type: "text", text: this.activeTurn ? `Unknown ALP tool '${tool}'` : "ALP tools are unavailable between turns" }], isError: true };
+    }
+    const callId = `acp-tool-${randomUUID()}`;
+    const item = { type: "dynamicToolCall", id: callId, callId, tool, arguments: args };
+    this.closeMessage();
+    this.emit("item/started", { threadId: this.sessionId, item: { ...item, status: "inProgress" } });
+    const result = await this.requestHandler("item/tool/call", { threadId: this.sessionId, turnId: this.activeTurn, callId, namespace: null, tool, arguments: args }).catch((error) => ({ success: false, contentItems: [{ type: "inputText", text: error instanceof Error ? error.message : String(error) }] }));
+    const ok = result?.success !== false;
+    this.emit("item/completed", { threadId: this.sessionId, item: { ...item, status: ok ? "completed" : "failed", success: ok, contentItems: result?.contentItems ?? [] } });
+    return { content: (result?.contentItems ?? []).map((part) => ({ type: "text", text: part.text ?? JSON.stringify(part) })), isError: !ok };
+  }
+  emit(method, params) {
+    for (const listener of this.listeners) listener(method, params);
+  }
+  fail(error) {
+    if (this.closed) return;
+    for (const waiter of this.pending.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(error);
+    }
+    this.pending.clear();
+    for (const listener of this.failures) listener(error);
+    void this.close();
+  }
+  async close() {
+    if (this.closed) return this.exit;
+    this.closed = true;
+    for (const waiter of this.pending.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error("Runtime closed"));
+    }
+    this.pending.clear();
+    this.listeners.clear();
+    this.failures.clear();
+    for (const answer of this.questions) answer({ outcome: { outcome: "cancelled" } });
+    this.questions.clear();
+    if (this.bridge) {
+      this.bridge.server.close();
+      for (const connection of this.bridge.connections) connection.destroy();
+      if (process.platform !== "win32") try {
+        rmSync(this.bridge.socket, { force: true });
+      } catch {
+      }
+    }
+    const child = this.child;
+    if (!child) return;
+    child.stdin.end();
+    const timer = setTimeout(() => {
+      if (process.platform === "win32" && child.pid) execFile("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true }, () => {
+      });
+      else child.kill("SIGKILL");
+    }, 1500);
+    let deadline;
+    try {
+      await Promise.race([this.exit, new Promise((resolve) => {
+        deadline = setTimeout(resolve, 4e3);
+      })]);
+    } finally {
+      clearTimeout(timer);
+      clearTimeout(deadline);
+    }
+  }
+};
+export {
+  AcpTransport,
+  acpDecision,
+  acpPermission,
+  acpWhat
+};

package/dist/antigravity-transport.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Antigravity provider definition for ALP.
+ */
+export type AntigravityProvider = {
+    id: string;
+    label: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    models?: Array<{
+        id: string;
+        label?: string;
+        description?: string;
+    }>;
+    additionalModels?: Array<{
+        id: string;
+        label?: string;
+        description?: string;
+    }>;
+    enabled?: boolean;
+    /** Explicit opt-in: read-only is a prompt constraint, never a native sandbox. */
+    readOnlyMode?: 'instructions' | 'reject';
+};
+type Listener = (method: string, params: any) => void;
+type RequestHandler = (method: string, params: any) => Promise<unknown>;
+export declare function encodePrompt(text: string): string;
+/**
+ * AntigravityTransport runs the Antigravity CLI (agy) over its stream-json protocol.
+ * Emits line-delimited JSON events and parses stdout line by line.
+ */
+export declare class AntigravityTransport {
+    private readonly command;
+    private readonly cwd;
+    private readonly env;
+    private readonly provider?;
+    private child?;
+    private lines?;
+    private exit;
+    private listeners;
+    private failures;
+    private requestHandler?;
+    private closed;
+    private conversationId;
+    private config;
+    private activeTurn?;
+    private messageText;
+    private messages;
+    private instructionsSent;
+    private tools;
+    private bridge?;
+    private readyPromise?;
+    private resolveReady?;
+    private rejectReady?;
+    private external?;
+    private externalStarting?;
+    private readonly startupAbort;
+    constructor(command?: string, cwd?: string, env?: NodeJS.ProcessEnv, provider?: AntigravityProvider | undefined);
+    initialize(): Promise<void>;
+    onNotification(listener: Listener): () => void;
+    onFailure(listener: (error: Error) => void): () => void;
+    onRequest(handler: RequestHandler): void;
+    request(method: string, params: any): Promise<any>;
+    private startProcess;
+    private receiveLine;
+    private handleStepUpdate;
+    private handleResult;
+    private endTurn;
+    private openBridge;
+    /** One stable launcher; each child inherits its own socket/token from agy.
+     * No session endpoint or credential is written to the global configuration.
+     * Leave the launcher installed: removing it would break concurrent sessions.
+     */
+    private registerMcpServer;
+    private serveBridge;
+    private toolCall;
+    private emit;
+    private fail;
+    close(): Promise<void>;
+}
+export {};