@agentprojectcontext/apx 1.65.3 → 1.67.0

package/src/interfaces/acp/jsonrpc.js

@@ -0,0 +1,180 @@
+// Newline-delimited JSON-RPC 2.0 connection — the ACP stdio framing.
+//
+// Per the ACP transport spec (agentclientprotocol.com, transports.mdx):
+// messages are individual JSON-RPC requests/notifications/responses, UTF-8,
+// delimited by "\n", never containing embedded newlines. Both peers can act
+// as caller and callee (the agent calls `session/request_permission` on the
+// client), so this connection is symmetric: it dispatches incoming requests
+// to registered handlers AND tracks ids of our own outgoing requests.
+//
+// Hand-rolled on purpose — the repo rule is no new npm dependencies, and the
+// framing is small enough that a library would cost more than it saves.
+
+export const JSONRPC_ERROR_CODES = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+});
+
+export class JsonRpcError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    if (data !== undefined) this.data = data;
+  }
+}
+
+export class JsonRpcConnection {
+  /**
+   * @param {{ input: import("node:stream").Readable,
+   *           output: import("node:stream").Writable,
+   *           onError?: (err: Error) => void }} opts
+   */
+  constructor({ input, output, onError = null }) {
+    this.output = output;
+    this.onError = onError;
+    this.handlers = new Map();
+    this.pending = new Map(); // id → {resolve, reject} for our outgoing requests
+    this.nextId = 0;
+    this.buffer = "";
+    this.closed = false;
+    this._closeResolvers = [];
+
+    input.setEncoding?.("utf8");
+    input.on("data", (chunk) => this._onData(String(chunk)));
+    input.on("end", () => this._close());
+    input.on("close", () => this._close());
+    input.on("error", () => this._close());
+  }
+
+  /** Register a handler for an incoming method (request or notification). */
+  method(name, handler) {
+    this.handlers.set(name, handler);
+    return this;
+  }
+
+  /** Resolves when the peer closes its side of the pipe. */
+  whenClosed() {
+    if (this.closed) return Promise.resolve();
+    return new Promise((resolve) => this._closeResolvers.push(resolve));
+  }
+
+  /** Send a one-way notification to the peer. */
+  notify(method, params) {
+    this._send({ jsonrpc: "2.0", method, params });
+  }
+
+  /** Send a request to the peer and await its response. */
+  request(method, params) {
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => {
+      if (this.closed) return reject(new Error("connection closed"));
+      this.pending.set(id, { resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  _close() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const { reject } of this.pending.values()) {
+      reject(new Error("connection closed"));
+    }
+    this.pending.clear();
+    for (const resolve of this._closeResolvers) resolve();
+    this._closeResolvers = [];
+  }
+
+  _send(msg) {
+    if (this.closed) return;
+    try {
+      this.output.write(JSON.stringify(msg) + "\n");
+    } catch (e) {
+      this.onError?.(e);
+    }
+  }
+
+  _onData(text) {
+    this.buffer += text;
+    let idx;
+    while ((idx = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        this._send({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: JSONRPC_ERROR_CODES.PARSE_ERROR, message: "parse error" },
+        });
+        continue;
+      }
+      // Fire-and-forget: a long-running request (session/prompt) must not
+      // block later frames — `session/cancel` has to be processed while the
+      // prompt handler is still awaiting the daemon stream.
+      this._dispatch(msg).catch((e) => this.onError?.(e));
+    }
+  }
+
+  async _dispatch(msg) {
+    if (!msg || typeof msg !== "object") return;
+
+    if (typeof msg.method === "string") {
+      const hasId = msg.id !== undefined && msg.id !== null;
+      const handler = this.handlers.get(msg.method);
+      if (!handler) {
+        if (hasId) {
+          this._send({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: {
+              code: JSONRPC_ERROR_CODES.METHOD_NOT_FOUND,
+              message: `method not found: ${msg.method}`,
+            },
+          });
+        }
+        return;
+      }
+      try {
+        const result = await handler(msg.params ?? {});
+        if (hasId) this._send({ jsonrpc: "2.0", id: msg.id, result: result ?? null });
+      } catch (e) {
+        if (hasId) {
+          this._send({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: {
+              code: typeof e?.code === "number" ? e.code : JSONRPC_ERROR_CODES.INTERNAL_ERROR,
+              message: e?.message || "internal error",
+              ...(e?.data !== undefined ? { data: e.data } : {}),
+            },
+          });
+        } else {
+          this.onError?.(e);
+        }
+      }
+      return;
+    }
+
+    // Response to one of our outgoing requests.
+    if (msg.id !== undefined && this.pending.has(msg.id)) {
+      const { resolve, reject } = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      if (msg.error) {
+        reject(
+          Object.assign(new Error(msg.error.message || "remote error"), {
+            code: msg.error.code,
+            data: msg.error.data,
+          })
+        );
+      } else {
+        resolve(msg.result);
+      }
+    }
+  }
+}

package/src/interfaces/acp/session.js

@@ -0,0 +1,205 @@
+// ACP session plumbing — daemon HTTP client, project resolution for a
+// session's cwd, and the small mapping helpers between APX daemon stream
+// events and ACP wire shapes.
+//
+// The daemon client is deliberately NOT the CLI's http.js: that module pins
+// its base URL to env vars at import time, while tests (and future embeddings)
+// need a per-instance {baseUrl, token}. The NDJSON reader mirrors
+// src/interfaces/cli/http.js streamRequest so both surfaces parse the daemon
+// stream identically.
+
+import path from "node:path";
+import { findApfRoot } from "#core/apc/parser.js";
+
+/**
+ * Minimal daemon HTTP client bound to an injected base URL + token.
+ * `token` may be a string or a () => string (re-read per request so a daemon
+ * restart with a rotated token keeps working mid-session).
+ */
+export function createDaemonClient({ baseUrl, token = "", ensureReady = null }) {
+  const authHeaders = () => {
+    const t = typeof token === "function" ? token() : token;
+    return t ? { authorization: `Bearer ${t}` } : {};
+  };
+
+  async function request(method, p, body) {
+    if (ensureReady) await ensureReady();
+    const res = await fetch(`${baseUrl}${p}`, {
+      method,
+      headers: {
+        ...(body ? { "content-type": "application/json" } : {}),
+        ...authHeaders(),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      /* non-JSON body — handled below */
+    }
+    if (!res.ok) throw new Error(json?.error || `${method} ${p} → ${res.status}`);
+    return json;
+  }
+
+  /**
+   * POST to an NDJSON stream endpoint. Awaits `onEvent` per event so a
+   * confirmation round-trip naturally back-pressures the stream. Returns the
+   * `result` of the `{type:"final"}` event, or null when aborted early.
+   */
+  async function streamPost(p, body, onEvent, { signal } = {}) {
+    if (ensureReady) await ensureReady();
+    const res = await fetch(`${baseUrl}${p}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders() },
+      body: JSON.stringify(body),
+      signal,
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {}
+      throw new Error(json?.error || `POST ${p} → ${res.status}`);
+    }
+    if (!res.body?.getReader) {
+      throw new Error("streaming response is not supported by this Node.js runtime");
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let finalResult = null;
+
+    if (signal) {
+      signal.addEventListener("abort", () => reader.cancel().catch(() => {}), { once: true });
+    }
+
+    const handleLine = async (line) => {
+      if (!line.trim()) return;
+      const event = JSON.parse(line);
+      if (event.type === "final") finalResult = event.result;
+      if (event.type === "error") throw new Error(event.error || "stream error");
+      await onEvent?.(event);
+    };
+
+    while (true) {
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch {
+        break; // abort/cancel — treat as clean end, caller checks its own flag
+      }
+      if (chunk.done) break;
+      buffer += decoder.decode(chunk.value, { stream: true });
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() || "";
+      for (const line of lines) await handleLine(line);
+    }
+
+    buffer += decoder.decode();
+    if (buffer.trim()) {
+      try {
+        await handleLine(buffer);
+      } catch {}
+    }
+
+    return finalResult;
+  }
+
+  return {
+    baseUrl,
+    get: (p) => request("GET", p),
+    post: (p, body) => request("POST", p, body),
+    streamPost,
+  };
+}
+
+/**
+ * Resolve the APC project for an ACP session's cwd — same contract as the
+ * mcp-server surface: walk up to the .apc root, match a registered daemon
+ * project by path, register it when unknown.
+ */
+export async function resolveProjectForCwd(client, cwd) {
+  const root = findApfRoot(cwd || process.cwd());
+  if (!root) {
+    throw new Error(
+      `No APC project found at or above: ${cwd}. Run \`apx init\` in the workspace first.`
+    );
+  }
+  const projects = await client.get("/projects");
+  const match = (projects || []).find(
+    (p) => path.resolve(p.path) === path.resolve(root)
+  );
+  if (match) return match;
+  return client.post("/projects", { path: root });
+}
+
+/** Flatten an ACP prompt (ContentBlock[]) into the text the daemon expects. */
+export function extractPromptText(blocks) {
+  if (typeof blocks === "string") return blocks;
+  if (!Array.isArray(blocks)) return "";
+  const parts = [];
+  for (const block of blocks) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+    } else if (block.type === "resource_link" && block.uri) {
+      // Baseline capability: resource links arrive as URIs; surface them to
+      // the model as plain references (we don't fetch on the agent side).
+      parts.push(String(block.uri));
+    }
+  }
+  return parts.join("\n").trim();
+}
+
+// Best-effort mapping from APX tool names (snake_case verbs) to ACP ToolKind.
+const KIND_RULES = [
+  [/^(search|find)_/, "search"],
+  [/^(read|list|get|show)_/, "read"],
+  [/^(edit|write|update|set|create|add|remember|import)_?/, "edit"],
+  [/^(delete|remove)_/, "delete"],
+  [/(shell|exec|run|call)/, "execute"],
+  [/(fetch|http|web|download)/, "fetch"],
+];
+
+export function toolKindFor(toolName) {
+  const name = String(toolName || "").toLowerCase();
+  for (const [re, kind] of KIND_RULES) {
+    if (re.test(name)) return kind;
+  }
+  return "other";
+}
+
+/** Compact text summary of a tool result for tool_call_update content. */
+export function summarizeToolResult(result, max = 2000) {
+  let text;
+  if (result == null) text = "";
+  else if (typeof result === "string") text = result;
+  else {
+    try {
+      text = JSON.stringify(result, null, 2);
+    } catch {
+      text = String(result);
+    }
+  }
+  return text.length > max ? text.slice(0, max - 1) + "…" : text;
+}
+
+let sessionCounter = 0;
+
+/** Per-connection session state. History feeds `previousMessages` so multi-turn
+ * ACP sessions keep context without any daemon-side session storage. */
+export function createSession({ id, project, cwd }) {
+  sessionCounter += 1;
+  return {
+    id,
+    project,
+    cwd,
+    history: [], // [{role: "user"|"assistant", content: string}]
+    activeTurn: null, // { abort: AbortController, cancelled: boolean }
+    seq: sessionCounter,
+  };
+}

package/src/interfaces/cli/commands/acp.js

@@ -0,0 +1,10 @@
+// apx acp — serve the APX super-agent over the Agent Client Protocol on the
+// current stdio. ACP clients (Zed, JetBrains, marimo, …) spawn this command
+// as a subprocess and speak JSON-RPC over stdin/stdout, so the command must
+// never print to stdout itself; all human-facing output goes to stderr.
+
+export async function cmdAcp() {
+  const { startStdioAcpServer } = await import("#interfaces/acp/index.js");
+  process.stderr.write("apx acp: Agent Client Protocol server on stdio (ctrl-c to stop)\n");
+  await startStdioAcpServer();
+}

package/src/interfaces/cli/commands/artifact.js

@@ -1,9 +1,20 @@
 import fs from "node:fs";
 import { spawn } from "node:child_process";
 import path from "node:path";
+import open from "open";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
+// Emit an OSC 8 terminal hyperlink when stdout is a TTY that likely supports
+// it (iTerm2, modern VS Code, kitty, WezTerm, …). Falls back to the raw URL
+// elsewhere so the link is always at least copy-pasteable.
+function hyperlink(url, label = url) {
+  if (process.stdout.isTTY) {
+    return `\x1b]8;;${url}\x07${label}\x1b]8;;\x07`;
+  }
+  return label === url ? url : `${label} (${url})`;
+}
+
 // First two bytes of an executable script. Used as a hint when the file
 // doesn't have the exec bit but clearly intends to run (shebang line).
 const SHEBANG = "#!";
@@ -142,3 +153,107 @@ export async function cmdArtifactRun(args) {
     });
   });
 }
+
+// `apx artifact preview <name> [--open] [--share] [--no-watch]`
+//
+// Asks the daemon to spin up an ephemeral local web server that renders the
+// artifact (HTML / React / static) and prints an interactive localhost link.
+// The page auto-reloads when the artifact file changes (unless --no-watch).
+// With --open the link is opened in the default browser; with --share a public
+// tunnel URL is created too.
+export async function cmdArtifactPreview(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx artifact preview: missing <name>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  const watch = args.flags["no-watch"] ? false : true;
+
+  let view;
+  try {
+    view = await http.post(
+      `/projects/${pid}/artifacts/${encodeURIComponent(name)}/preview`,
+      { watch }
+    );
+  } catch (e) {
+    throw new Error(`could not preview "${name}": ${e.message}`);
+  }
+
+  console.log(`preview ready — ${view.kind} artifact "${view.name}"`);
+  console.log(`  local:  ${hyperlink(view.url)}`);
+  if (view.watch) console.log("  (auto-reloads on change — edit the artifact and the tab refreshes)");
+  console.log(`  stop:   apx artifact stop ${view.id}`);
+
+  if (args.flags.share) {
+    await sharePreview(view.id, { open: !!args.flags.open });
+  } else if (args.flags.open) {
+    await open(view.url);
+    console.log("  opened in your browser.");
+  } else {
+    console.log(`  open:   apx artifact preview ${name} --open`);
+  }
+}
+
+// Shared helper: open a tunnel for an existing preview id and print the URL.
+async function sharePreview(previewId, { open: doOpen = false } = {}) {
+  let tunnel;
+  try {
+    tunnel = await http.post(`/previews/${previewId}/tunnel`, {});
+  } catch (e) {
+    throw new Error(`could not create tunnel: ${e.message}`);
+  }
+  console.log(`  public: ${hyperlink(tunnel.url)}  (${tunnel.provider})`);
+  console.log("  ⚠ anyone with this URL can reach the preview while it's open.");
+  if (doOpen) {
+    await open(tunnel.url);
+    console.log("  opened public URL in your browser.");
+  }
+}
+
+// `apx artifact share <name> [--open] [--no-watch]`
+// Convenience: preview + tunnel in one shot.
+export async function cmdArtifactShare(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx artifact share: missing <name>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  const watch = args.flags["no-watch"] ? false : true;
+
+  const view = await http.post(
+    `/projects/${pid}/artifacts/${encodeURIComponent(name)}/preview`,
+    { watch }
+  );
+  console.log(`sharing ${view.kind} artifact "${view.name}"`);
+  console.log(`  local:  ${hyperlink(view.url)}`);
+  await sharePreview(view.id, { open: !!args.flags.open });
+  console.log(`  stop:   apx artifact stop ${view.id}`);
+}
+
+// `apx artifact previews` — list running preview servers.
+export async function cmdArtifactPreviews(args = {}) {
+  const rows = await http.get(`/previews`);
+  if (!rows.length) {
+    console.log("(no running previews)");
+    return;
+  }
+  console.log("ID".padEnd(10) + "NAME".padEnd(24) + "KIND".padEnd(8) + "URL");
+  for (const r of rows) {
+    console.log(
+      r.id.padEnd(10) +
+      String(r.name).slice(0, 22).padEnd(24) +
+      String(r.kind).padEnd(8) +
+      r.url + (r.tunnel ? `  → ${r.tunnel.url}` : "")
+    );
+  }
+}
+
+// `apx artifact stop <id> | --all` — stop preview server(s).
+export async function cmdArtifactStop(args) {
+  if (args.flags.all) {
+    const rows = await http.get(`/previews`);
+    for (const r of rows) await http.delete(`/previews/${r.id}`);
+    console.log(`stopped ${rows.length} preview(s)`);
+    return;
+  }
+  const id = args._[0];
+  if (!id) throw new Error("apx artifact stop: missing <id> (or --all)");
+  await http.delete(`/previews/${encodeURIComponent(id)}`);
+  console.log(`stopped preview ${id}`);
+}

package/src/interfaces/cli/commands/setup.js

@@ -8,6 +8,7 @@ import http from "node:http";
 import readline from "node:readline";
 import { spawnSync } from "node:child_process";
 import { readConfig, writeConfig } from "#core/config/index.js";
+import { ENGINE_PRESETS } from "#core/engines/presets.js";
 import { mascot } from "#core/mascot.js";
 import { setupClaudePermissions } from "../claude-permissions.js";
 import { PERMISSION_MODES, DEFAULT_PERMISSION_MODE } from "#core/constants/permissions.js";
@@ -59,6 +60,8 @@ async function fetchOllamaModels(baseUrl) {
 }
 
 // ── Provider definitions ──────────────────────────────────────────────────────
+// Model lists come from the shared catalog (#core/engines/presets.js) so the CLI
+// and the web admin panel never drift. Ollama stays dynamic (fetched at runtime).
 const PROVIDERS = [
   {
     id: "anthropic",
@@ -66,7 +69,7 @@ const PROVIDERS = [
     needsKey: true,
     keyLabel: "Anthropic API key",
     keyHint: "sk-ant-...",
-    models: ["claude-sonnet-4-5", "claude-haiku-4-5", "claude-opus-4-5"],
+    models: ENGINE_PRESETS.anthropic.known_models,
   },
   {
     id: "openai",
@@ -74,7 +77,7 @@ const PROVIDERS = [
     needsKey: true,
     keyLabel: "OpenAI API key",
     keyHint: "sk-...",
-    models: ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
+    models: ENGINE_PRESETS.openai.known_models,
   },
   {
     id: "ollama",
@@ -88,7 +91,7 @@ const PROVIDERS = [
     needsKey: true,
     keyLabel: "Gemini API key",
     keyHint: "AIza...",
-    models: ["gemini-3.5-flash", "gemini-3.1-pro-preview", "gemini-2.5-flash"],
+    models: ENGINE_PRESETS.gemini.known_models,
   },
 ];