@anhlp/alp-client 0.0.0-beta.1

package/dist/supervise.js

@@ -0,0 +1,81 @@
+// packages/client/src/supervise.js
+import { mkdir, unlink, writeFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { ensureDaemon, lockAlive, readLock } from "./index.js";
+import { installedProgram, serviceFor, startService } from "./service.js";
+var holdFile = (home) => path.join(home, "state", "alpd.held");
+async function holdDaemon(home, by = "alp daemon stop") {
+  await mkdir(path.dirname(holdFile(home)), { recursive: true, mode: 448 });
+  await writeFile(holdFile(home), JSON.stringify({ by, at: (/* @__PURE__ */ new Date()).toISOString() }) + "\n", { mode: 384 });
+}
+async function releaseHold(home) {
+  await unlink(holdFile(home)).catch(() => {
+  });
+}
+async function daemonHeld(home) {
+  return stat(holdFile(home)).then(() => true, () => false);
+}
+async function whenReady(home, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const lock = await readLock(home);
+    if (lockAlive(lock) && lock.ready) return lock.socket;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`alpd did not become ready within ${timeoutMs / 1e3} s; see ${path.join(home, "logs")}`);
+}
+async function startDaemon({ home, entry, env = process.env, timeoutMs = 15e3 }) {
+  await releaseHold(home);
+  const lock = await readLock(home);
+  if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
+  const service = serviceFor({ home, env });
+  if (service && await installedProgram(service)) {
+    await startService(service);
+    return whenReady(home, timeoutMs);
+  }
+  return ensureDaemon({ home, entry, env, timeoutMs });
+}
+function superviseDaemon({ home, entry, env = process.env, intervalMs = 5e3, misses = 2, log = () => {
+} }) {
+  let stopped = false;
+  let missed = 0;
+  let starting;
+  const start = (reason) => {
+    starting ??= startDaemon({ home, entry: typeof entry === "function" ? entry() : entry, env }).then(() => log(`alpd ${reason}`), (error) => log(`could not start alpd: ${error?.message ?? error}`)).finally(() => {
+      starting = void 0;
+      missed = 0;
+    });
+    return starting;
+  };
+  const check = async () => {
+    if (stopped || starting) return;
+    if (lockAlive(await readLock(home))) {
+      missed = 0;
+      return;
+    }
+    if (await daemonHeld(home)) {
+      missed = 0;
+      return;
+    }
+    if (++missed >= misses && !stopped) await start("was down; started it again");
+  };
+  const initial = start("started with Paseo");
+  const timer = setInterval(() => {
+    void check();
+  }, intervalMs);
+  timer.unref?.();
+  const stop = () => {
+    stopped = true;
+    clearInterval(timer);
+    return starting ?? Promise.resolve();
+  };
+  stop.started = initial;
+  return stop;
+}
+export {
+  daemonHeld,
+  holdDaemon,
+  releaseHold,
+  startDaemon,
+  superviseDaemon
+};

package/dist/websocket.d.ts

@@ -0,0 +1,51 @@
+/** A URL fit for an error message: no credentials, query or fragment, which may carry a token. @param {string} url */
+export function redactUrl(url: string): string;
+/**
+ * Wraps an open WebSocket in an ALP transport. The transport owns the socket from then on.
+ * @param {WebSocketLike} socket
+ * @param {WebSocketTransportOptions} [options]
+ * @returns {AlpTransport}
+ */
+export function createWebSocketTransport(socket: WebSocketLike, { maxFrame, maxBufferedBytes }?: WebSocketTransportOptions): AlpTransport;
+/**
+ * Opens a WebSocket to `url` and resolves with its transport once it is open. The socket comes
+ * from `createSocket`, else `new WebSocket(url, protocols)` with the injected or global WebSocket.
+ * Errors name the URL without its credentials, query or fragment.
+ * @param {string} url
+ * @param {ConnectWebSocketOptions} [options]
+ * @returns {Promise<AlpTransport>}
+ */
+export function connectWebSocket(url: string, { WebSocket: Implementation, protocols, createSocket, signal, timeoutMs, ...options }?: ConnectWebSocketOptions): Promise<AlpTransport>;
+/** Close codes this transport sends when the peer breaks the protocol. */
+export const CLOSE_CODE: Readonly<{
+    unsupportedData: 4003;
+    tooLarge: 4009;
+}>;
+export type AlpTransport = import("./rpc/client.js").AlpTransport;
+export type TransportClose = import("./rpc/client.js").TransportClose;
+export type AbortSignalLike = import("./rpc/client.js").AbortSignalLike;
+export type WebSocketLike = {
+    readonly readyState: number;
+    readonly bufferedAmount?: number;
+    binaryType?: string;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?(type: string, listener: (event: any) => void): void;
+    removeEventListener?(type: string, listener: (event: any) => void): void;
+    onopen?: ((event: any) => void) | null;
+    onmessage?: ((event: any) => void) | null;
+    onerror?: ((event: any) => void) | null;
+    onclose?: ((event: any) => void) | null;
+};
+export type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+export type WebSocketTransportOptions = {
+    maxFrame?: number;
+    maxBufferedBytes?: number;
+};
+export type ConnectWebSocketOptions = WebSocketTransportOptions & {
+    WebSocket?: WebSocketConstructor;
+    protocols?: string | string[];
+    createSocket?: (url: string, protocols?: string | string[]) => WebSocketLike;
+    signal?: AbortSignalLike;
+    timeoutMs?: number;
+};

package/dist/websocket.js

@@ -0,0 +1,190 @@
+// packages/client/src/websocket.js
+import { MAX_FRAME } from "@anhlp/alp-protocol";
+import { AlpClientError } from "./rpc/errors.js";
+import { utf8Length } from "./rpc/framing.js";
+import { timerDelay } from "./rpc/timers.js";
+var CONNECTING = 0;
+var OPEN = 1;
+var CLOSE_CODE = Object.freeze({ unsupportedData: 4003, tooLarge: 4009 });
+var CLOSE_AFTER_ERROR_MS = 250;
+var MAX_CLOSE_REASON = 123;
+function redactUrl(url) {
+  const match = /^([a-z][a-z0-9+.-]*:\/\/)(?:[^/?#\\]*@)?([^/?#\\@]*)([^?#]*)/i.exec(String(url));
+  return match ? `${match[1]}${match[2]}${match[3]}` : "<websocket>";
+}
+function scrubbed(error, url) {
+  const text = error instanceof Error ? error.message : String(error ?? "");
+  const message = (text.split(String(url)).join(redactUrl(url)) || "WebSocket error").replace(/[a-z][a-z0-9+.-]*:\/\/[^\s'"<>]+/gi, (found) => redactUrl(found));
+  const clean = new Error(message);
+  if (error instanceof Error && error.name) clean.name = error.name;
+  return clean;
+}
+function closeReason(reason) {
+  let cut = reason;
+  while (utf8Length(cut) > MAX_CLOSE_REASON) cut = cut.slice(0, -1);
+  return cut;
+}
+function release(socket, code, reason) {
+  if (socket.readyState !== CONNECTING && socket.readyState !== OPEN) return;
+  try {
+    if (code === void 0) socket.close();
+    else socket.close(code, closeReason(reason ?? ""));
+    return;
+  } catch {
+  }
+  try {
+    socket.close();
+  } catch {
+  }
+}
+function absorbErrors(socket) {
+  if (typeof socket.addEventListener === "function") socket.addEventListener("error", () => {
+  });
+}
+function listen(socket, type, listener) {
+  if (typeof socket.addEventListener === "function") {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  const key = (
+    /** @type {'onopen' | 'onmessage' | 'onerror' | 'onclose'} */
+    `on${type}`
+  );
+  const previous = socket[key];
+  socket[key] = (event) => {
+    previous?.(event);
+    listener(event);
+  };
+  return () => {
+    socket[key] = previous ?? null;
+  };
+}
+var errorOf = (event) => {
+  const message = event?.error instanceof Error && event.error.message || typeof event?.message === "string" && event.message || "WebSocket error";
+  return event?.error instanceof Error && event.error.message ? event.error : new Error(message);
+};
+function createWebSocketTransport(socket, { maxFrame = MAX_FRAME, maxBufferedBytes = 4 * MAX_FRAME } = {}) {
+  if (socket.readyState !== OPEN) throw new AlpClientError("WebSocket is not open", { reason: "disconnected" });
+  absorbErrors(socket);
+  try {
+    socket.binaryType = "arraybuffer";
+  } catch {
+  }
+  const messages = /* @__PURE__ */ new Set();
+  const closes = /* @__PURE__ */ new Set();
+  let ended;
+  const detach = [];
+  let failed;
+  let failTimer;
+  const end = (close) => {
+    if (ended) return;
+    ended = close;
+    if (failTimer !== void 0) clearTimeout(failTimer);
+    for (const remove of detach.splice(0)) remove();
+    messages.clear();
+    const listeners = [...closes];
+    closes.clear();
+    for (const listener of listeners) listener(close);
+  };
+  const violate = (message, code) => {
+    const error = new AlpClientError(message, { reason: "protocol" });
+    release(socket, code, message);
+    end({ error });
+  };
+  detach.push(listen(socket, "message", (event) => {
+    if (ended) return;
+    const data = event?.data;
+    if (typeof data !== "string") return violate("Binary WebSocket messages are not ALP frames", CLOSE_CODE.unsupportedData);
+    if (utf8Length(data) > maxFrame) return violate(`ALP frame exceeds ${maxFrame} bytes`, CLOSE_CODE.tooLarge);
+    for (const line of data.includes("\n") ? data.split("\n") : [data]) {
+      if (ended) return;
+      if (line.trim()) for (const listener of [...messages]) listener(line);
+    }
+  }));
+  detach.push(listen(socket, "close", (event) => end({ error: failed, code: typeof event?.code === "number" ? event.code : void 0, reason: typeof event?.reason === "string" && event.reason ? event.reason : void 0 })));
+  detach.push(listen(socket, "error", (event) => {
+    if (failed) return;
+    failed = errorOf(event);
+    failTimer = setTimeout(() => end({ error: failed }), CLOSE_AFTER_ERROR_MS);
+    release(socket);
+  }));
+  return {
+    get state() {
+      return ended || socket.readyState !== OPEN ? "closed" : "open";
+    },
+    send(frame) {
+      if (ended || socket.readyState !== OPEN) throw new AlpClientError("WebSocket is not open", { reason: "send_failed" });
+      if ((socket.bufferedAmount ?? 0) + utf8Length(frame) > maxBufferedBytes) throw new AlpClientError(`WebSocket send buffer is over ${maxBufferedBytes} bytes`, { reason: "send_failed" });
+      socket.send(frame);
+    },
+    onMessage(listener) {
+      if (ended) return () => false;
+      messages.add(listener);
+      return () => messages.delete(listener);
+    },
+    onClose(listener) {
+      if (ended) return () => false;
+      closes.add(listener);
+      return () => closes.delete(listener);
+    },
+    close() {
+      release(socket, 1e3, "client closed");
+      end({ code: 1e3, reason: "client closed" });
+    }
+  };
+}
+function connectWebSocket(url, { WebSocket: Implementation, protocols, createSocket, signal, timeoutMs = 15e3, ...options } = {}) {
+  const where = redactUrl(url);
+  let delay;
+  try {
+    delay = timerDelay(timeoutMs);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  if (signal?.aborted) return Promise.reject(new AlpClientError(`Connecting to ${where} was aborted`, { reason: "aborted", cause: signal.reason }));
+  const Constructor = Implementation ?? /** @type {any} */
+  globalThis.WebSocket;
+  if (!createSocket && typeof Constructor !== "function") return Promise.reject(new TypeError("No WebSocket implementation: pass options.WebSocket or options.createSocket"));
+  let socket;
+  try {
+    socket = createSocket ? createSocket(url, protocols) : protocols === void 0 ? new Constructor(url) : new Constructor(url, protocols);
+  } catch (error) {
+    return Promise.reject(new AlpClientError(`Could not connect to ${where}`, { reason: "disconnected", cause: scrubbed(error, url) }));
+  }
+  absorbErrors(socket);
+  return new Promise((resolve, reject) => {
+    const detach = [];
+    let timer;
+    const settle = () => {
+      for (const remove of detach.splice(0)) remove();
+      if (timer !== void 0) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const fail = (error) => {
+      settle();
+      release(socket);
+      reject(error);
+    };
+    const onAbort = () => fail(new AlpClientError(`Connecting to ${where} was aborted`, { reason: "aborted", cause: signal?.reason }));
+    const open = () => {
+      settle();
+      try {
+        resolve(createWebSocketTransport(socket, options));
+      } catch (error) {
+        reject(error);
+      }
+    };
+    if (socket.readyState === OPEN) return open();
+    detach.push(listen(socket, "open", open));
+    detach.push(listen(socket, "error", (event) => fail(new AlpClientError(`Could not connect to ${where}`, { reason: "disconnected", cause: scrubbed(errorOf(event), url) }))));
+    detach.push(listen(socket, "close", (event) => fail(new AlpClientError(`Could not connect to ${where}`, { reason: "disconnected", data: { code: event?.code, reason: event?.reason || void 0 } }))));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (delay !== void 0) timer = setTimeout(() => fail(new AlpClientError(`Connecting to ${where} timed out after ${timeoutMs} ms`, { reason: "timeout" })), delay);
+  });
+}
+export {
+  CLOSE_CODE,
+  connectWebSocket,
+  createWebSocketTransport,
+  redactUrl
+};

package/package.json

@@ -0,0 +1,168 @@
+{
+  "name": "@anhlp/alp-client",
+  "version": "0.0.0-beta.1",
+  "type": "module",
+  "description": "ALP client: portable JSON-RPC SDK, WebSocket and Node IPC transports, daemon discovery and setup",
+  "files": [
+    "src",
+    "dist",
+    "NOTICE"
+  ],
+  "exports": {
+    "./acp-probe": {
+      "alp-source": {
+        "types": "./src/acp-probe.js",
+        "default": "./src/acp-probe.js"
+      },
+      "types": "./dist/acp-probe.d.ts",
+      "default": "./src/acp-probe.js"
+    },
+    "./antigravity-probe": {
+      "alp-source": {
+        "types": "./src/antigravity-probe.js",
+        "default": "./src/antigravity-probe.js"
+      },
+      "types": "./dist/antigravity-probe.d.ts",
+      "default": "./src/antigravity-probe.js"
+    },
+    "./command": {
+      "alp-source": {
+        "types": "./src/command.js",
+        "default": "./src/command.js"
+      },
+      "types": "./dist/command.d.ts",
+      "default": "./src/command.js"
+    },
+    "./doctor": {
+      "alp-source": {
+        "types": "./src/doctor.js",
+        "default": "./src/doctor.js"
+      },
+      "types": "./dist/doctor.d.ts",
+      "default": "./src/doctor.js"
+    },
+    "./index": {
+      "alp-source": {
+        "types": "./src/index.js",
+        "default": "./src/index.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    ".": {
+      "alp-source": {
+        "types": "./src/index.js",
+        "default": "./src/index.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./ipc": {
+      "alp-source": {
+        "types": "./src/ipc.js",
+        "default": "./src/ipc.js"
+      },
+      "types": "./dist/ipc.d.ts",
+      "default": "./src/ipc.js"
+    },
+    "./library-test": {
+      "alp-source": {
+        "types": "./src/library-test.js",
+        "default": "./src/library-test.js"
+      },
+      "types": "./dist/library-test.d.ts",
+      "default": "./src/library-test.js"
+    },
+    "./mcp-probe": {
+      "alp-source": {
+        "types": "./src/mcp-probe.js",
+        "default": "./src/mcp-probe.js"
+      },
+      "types": "./dist/mcp-probe.d.ts",
+      "default": "./src/mcp-probe.js"
+    },
+    "./portable": {
+      "alp-source": {
+        "types": "./src/portable.js",
+        "default": "./src/portable.js"
+      },
+      "types": "./dist/portable.d.ts",
+      "default": "./src/portable.js"
+    },
+    "./prompt": {
+      "alp-source": {
+        "types": "./src/prompt.js",
+        "default": "./src/prompt.js"
+      },
+      "types": "./dist/prompt.d.ts",
+      "default": "./src/prompt.js"
+    },
+    "./render": {
+      "alp-source": {
+        "types": "./src/render.js",
+        "default": "./src/render.js"
+      },
+      "types": "./dist/render.d.ts",
+      "default": "./src/render.js"
+    },
+    "./service": {
+      "alp-source": {
+        "types": "./src/service.js",
+        "default": "./src/service.js"
+      },
+      "types": "./dist/service.d.ts",
+      "default": "./src/service.js"
+    },
+    "./setup": {
+      "alp-source": {
+        "types": "./src/setup.js",
+        "default": "./src/setup.js"
+      },
+      "types": "./dist/setup.d.ts",
+      "default": "./src/setup.js"
+    },
+    "./supervise": {
+      "alp-source": {
+        "types": "./src/supervise.js",
+        "default": "./src/supervise.js"
+      },
+      "types": "./dist/supervise.d.ts",
+      "default": "./src/supervise.js"
+    },
+    "./websocket": {
+      "alp-source": {
+        "types": "./src/websocket.js",
+        "default": "./src/websocket.js"
+      },
+      "types": "./dist/websocket.d.ts",
+      "default": "./src/websocket.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "@anhlp/alp-core": "0.0.0-beta.1",
+    "@anhlp/alp-protocol": "0.0.0-beta.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-workspace.mjs client",
+    "test": "node ../../scripts/test-package.mjs client",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phucanh08/alp.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/phucanh08/alp/tree/main/packages/client#readme",
+  "bugs": {
+    "url": "https://github.com/phucanh08/alp/issues"
+  }
+}

package/src/acp-probe.js

@@ -0,0 +1,46 @@
+import { stdioSession } from './mcp-probe.js';
+
+/**
+ * Starts an ACP provider once and runs initialize (ALPD §46), for `alp provider test`
+ * and the settings screen. It reports who the agent says it is and what it supports;
+ * a provider that needs a login usually says so here, in authMethods. With `discover`,
+ * it also opens a session in `cwd`, as Paseo does, to read the models and modes the agent
+ * offers (ALPD §65); an agent that offers none leaves them out.
+ * @param {{ command: string, args?: string[], env?: Record<string, string>, label?: string, id?: string }} provider
+ * @param {{ cwd?: string, timeoutMs?: number, discover?: boolean }} [options]
+ * @returns {Promise<{ protocolVersion: number, agent?: { name?: string, title?: string, version?: string }, loadSession: boolean, mcpHttp: boolean, authMethods: string[],
+ *   models?: Array<{ id: string, label: string, description?: string }>, currentModel?: string, modes?: Array<{ id: string, label: string, description?: string }>, currentMode?: string }>}
+ */
+export async function probeAcp(provider, { cwd, timeoutMs = 20_000, discover = false } = {}) {
+  const session = stdioSession({ command: provider.command, args: provider.args ?? [], env: provider.env ?? {} }, cwd, timeoutMs);
+  try {
+    const result = await session.request('initialize', {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: 'alp', title: 'ALP', version: '1' },
+    });
+    if (result.protocolVersion !== 1) throw new Error(`${provider.label ?? provider.id} speaks ACP version ${result.protocolVersion}; ALP speaks version 1`);
+    const info = result.agentInfo;
+    const offered = discover ? await session.request('session/new', { cwd, mcpServers: [] }) : undefined;
+    const choices = list => Array.isArray(list) ? list.filter(item => typeof (item?.modelId ?? item?.id) === 'string')
+      .map(item => ({ id: item.modelId ?? item.id, label: typeof item.name === 'string' && item.name ? item.name : item.modelId ?? item.id, ...(typeof item.description === 'string' && item.description ? { description: item.description } : {}) })) : undefined;
+    const config = offered?.configOptions?.find(option => option.category === 'model' && option.type === 'select');
+    const modeConfig = offered?.configOptions?.find(option => option.category === 'mode' && option.type === 'select');
+    const flatten = options => options?.flatMap(option => option.options ?? [option]).map(option => ({ ...option, id: option.value }));
+    const modelState = offered?.models ?? (config ? { availableModels: flatten(config.options), currentModelId: config.currentValue } : undefined);
+    const modeState = offered?.modes ?? (modeConfig ? { availableModes: flatten(modeConfig.options), currentModeId: modeConfig.currentValue } : undefined);
+    const models = choices(modelState?.availableModels);
+    const modes = choices(modeState?.availableModes);
+    return {
+      ...(models ? { models, ...(typeof modelState.currentModelId === 'string' ? { currentModel: modelState.currentModelId } : {}) } : {}),
+      ...(modes ? { modes, ...(typeof modeState.currentModeId === 'string' ? { currentMode: modeState.currentModeId } : {}) } : {}),
+      protocolVersion: result.protocolVersion,
+      ...(info ? { agent: { ...(info.name ? { name: info.name } : {}), ...(info.title ? { title: info.title } : {}), ...(info.version ? { version: info.version } : {}) } } : {}),
+      loadSession: Boolean(result.agentCapabilities?.loadSession),
+      mcpHttp: Boolean(result.agentCapabilities?.mcpCapabilities?.http),
+      authMethods: (result.authMethods ?? []).map(method => method?.name ?? method?.id).filter(Boolean),
+    };
+  } finally {
+    await session.close();
+  }
+}

package/src/antigravity-probe.js

@@ -0,0 +1,106 @@
+import { spawn } from 'node:child_process';
+
+const DEFAULT_ANTIGRAVITY_MODELS = [
+  { id: 'gemini-3.8-flash-high', label: 'Gemini 3.8 Flash (High)' },
+  { id: 'gemini-3.8-flash-medium', label: 'Gemini 3.8 Flash (Medium)' },
+  { id: 'gemini-3.8-flash-low', label: 'Gemini 3.8 Flash (Low)' },
+  { id: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro' },
+  { id: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash' },
+  { id: 'claude-sonnet-4-6', label: 'Claude Sonnet 4.6 (Thinking)' },
+  { id: 'claude-opus-4-6-thinking', label: 'Claude Opus 4.6 (Thinking)' },
+  { id: 'gpt-oss-120b-medium', label: 'GPT-OSS 120B (Medium)' },
+];
+
+const ANTIGRAVITY_MODES = [
+  {
+    id: 'full-access',
+    label: 'Full access',
+    description: 'Antigravity runs with full access (--dangerously-skip-permissions).',
+  },
+];
+
+function runCommand(command, args, { env = process.env, cwd, timeoutMs = 20_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`${command} ${args.join(' ')} timed out after ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+
+    child.stdout.on('data', chunk => { stdout += chunk.toString(); });
+    child.stderr.on('data', chunk => { stderr += chunk.toString(); });
+
+    child.on('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    child.on('close', code => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(new Error(`${command} exited with code ${code}: ${stderr.trim() || stdout.trim()}`));
+    });
+  });
+}
+
+/**
+ * Probes Antigravity CLI for version, status and available models.
+ * @param {{ command?: string, args?: string[], env?: Record<string, string>, label?: string, id?: string, readOnlyMode?: 'instructions' | 'reject' }} [provider]
+ * @param {{ cwd?: string, timeoutMs?: number }} [options]
+ */
+export async function probeAntigravity(provider = {}, { cwd, timeoutMs = 20_000 } = {}) {
+  const command = provider.command || 'agy';
+  const args = provider.args ?? [];
+  const env = { ...process.env, ...(provider.env ?? {}) };
+
+  // Check version
+  let version = '';
+  try {
+    const res = await runCommand(command, [...args, '--version'], { env, cwd, timeoutMs: Math.min(timeoutMs, 5000) });
+    version = res.stdout.trim().split('\n')[0] ?? '';
+  } catch (error) {
+    throw new Error(`Antigravity command '${command}' is not available: ${error.message}`);
+  }
+
+  // Probe models
+  let models = [];
+  try {
+    const res = await runCommand(command, [...args, 'models'], { env, cwd, timeoutMs });
+    for (const line of res.stdout.trim().split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      const [id, label] = line.split('\t');
+      if (id && label) {
+        models.push({ id: id.trim(), label: label.trim() });
+      } else if (id) {
+        models.push({ id: id.trim(), label: id.trim() });
+      }
+    }
+  } catch {
+    models = [...DEFAULT_ANTIGRAVITY_MODELS];
+  }
+
+  if (!models.length) {
+    models = [...DEFAULT_ANTIGRAVITY_MODELS];
+  }
+
+  return {
+    version,
+    agent: { name: 'antigravity', title: 'Antigravity', version },
+    models,
+    currentModel: models[0]?.id,
+    modes: provider.readOnlyMode === 'instructions' ? [...ANTIGRAVITY_MODES, {
+      id: 'read-only', label: 'Read only (instructions)',
+      description: 'For new sessions: prompt-only read-only behavior. agy still runs with full access; no OS sandbox enforces this mode.',
+    }] : ANTIGRAVITY_MODES,
+    currentMode: 'full-access',
+  };
+}

package/src/command.js

@@ -0,0 +1,18 @@
+import { spawn } from 'node:child_process';
+
+/** Runs a command; resolves with its exit code and output, never rejects. */
+export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 15_000 } = {}) {
+  return new Promise(resolve => {
+    let child;
+    // Windows cannot exec a script by its shebang; a JavaScript command runs under this Node, as the Codex transport does.
+    const script = process.platform === 'win32' && /\.[cm]?js$/i.test(command);
+    try { child = spawn(script ? process.execPath : command, script ? [command, ...args] : args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] }); }
+    catch (error) { resolve({ code: -1, stdout: '', stderr: error.message }); return; }
+    let stdout = '', stderr = '';
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+    child.on('error', error => { clearTimeout(timer); resolve({ code: -1, stdout, stderr: error.message }); });
+    child.on('close', code => { clearTimeout(timer); resolve({ code: code ?? -1, stdout, stderr }); });
+  });
+}

package/src/doctor.d.ts

@@ -0,0 +1,13 @@
+export type DoctorCheck = {
+  id: string;
+  status: 'ok' | 'info' | 'warn' | 'fail';
+  summary: string;
+  details?: string[];
+  hint?: string;
+  fix?: { describe: string; apply(): Promise<string> };
+};
+export type CommandResult = { code: number; stdout: string; stderr: string };
+export type CommandRunner = (command: string, args: string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }) => Promise<CommandResult>;
+export const runCommand: CommandRunner;
+export function diagnose(options?: { home?: string; project?: string; env?: NodeJS.ProcessEnv; run?: CommandRunner; sandbox?: boolean; daemonEntry?: string; timeoutMs?: number }): Promise<DoctorCheck[]>;
+export function repair(checks: DoctorCheck[]): Promise<Array<{ id: string; result: string }>>;