@agentprojectcontext/apx 1.25.0 → 1.27.2

package/src/host/daemon/api/pairing.js

@@ -0,0 +1,194 @@
+// QR-based pairing for companion clients (APX Deck app, etc.).
+//
+// Flow:
+//   1. `apx pair` CLI hits POST /pair/init from localhost. Daemon mints a
+//      short-lived pairing_id (90 s TTL) and prints a QR with
+//      { url, pid, fp } so the device can identify the daemon.
+//   2. Device scans QR, POSTs { pairing_id, label } to /pair/confirm.
+//      Daemon validates the nonce, generates a per-client token via
+//      the token store, returns { token, daemon_url, fingerprint }.
+//   3. CLI is polling GET /pair/status/:pairing_id and shows "paired ✓"
+//      once the nonce is consumed.
+//
+// Endpoints under /pair/* are exempt from the bearer auth middleware
+// (see api/shared.js — UNAUTHENTICATED_PREFIXES). /pair/init enforces
+// its own localhost-only check; /pair/confirm is gated by the nonce.
+// /pair/list and /pair/revoke ARE authenticated — they expose paired
+// device info, so they sit behind the auth middleware via a small
+// trick: we register them on a sub-router with its own auth check.
+
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+
+const PAIRING_TTL_MS = 90_000;
+
+// Reachable base URLs a device on the LAN can hit. When the daemon binds to
+// the wildcard (0.0.0.0/::) we enumerate non-internal IPv4s; when it binds to
+// a concrete host we use that. Loopback is always last (only useful for the
+// host itself / adb reverse). Used to build the scan-to-login QR.
+function reachableUrls({ host, port }) {
+  const p = port || 7430;
+  const urls = [];
+  if (host && host !== "0.0.0.0" && host !== "::" && host !== "127.0.0.1") {
+    urls.push(`http://${host}:${p}`);
+  }
+  if (host === "0.0.0.0" || host === "::" || !host) {
+    for (const list of Object.values(os.networkInterfaces())) {
+      for (const i of list || []) {
+        if (i.family === "IPv4" && !i.internal) urls.push(`http://${i.address}:${p}`);
+      }
+    }
+  }
+  urls.push(`http://127.0.0.1:${p}`);
+  return [...new Set(urls)];
+}
+
+// pairing_id → { expires_at, confirmed_at, device_label, client_id }
+const sessions = new Map();
+
+function isLocalhost(req) {
+  // Express sets req.ip respecting trust proxy; for the daemon we trust
+  // only the raw socket address.
+  const addr = req.socket?.remoteAddress || req.ip || "";
+  return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
+}
+
+function purgeExpired(now = Date.now()) {
+  for (const [id, s] of sessions) {
+    // Keep confirmed sessions around briefly so the CLI can read status.
+    const cutoff = s.confirmed_at ? s.confirmed_at + 30_000 : s.expires_at;
+    if (cutoff < now) sessions.delete(id);
+  }
+}
+
+export function register(app, ctx) {
+  const { tokenStore, config } = ctx;
+  if (!tokenStore) {
+    // Pairing requires the multi-token store; if running with legacy
+    // single-token mode just don't register the routes. Devices can fall
+    // back to the master token via env var.
+    return;
+  }
+
+  // ── POST /pair/init ───────────────────────────────────────────────
+  // Localhost-only. Returns { pairing_id, expires_at }. No body needed.
+  app.post("/pair/init", (req, res) => {
+    if (!isLocalhost(req)) {
+      return res.status(403).json({ error: "pair/init: localhost only" });
+    }
+    purgeExpired();
+    const pairing_id = randomUUID();
+    const now = Date.now();
+    const expires_at = now + PAIRING_TTL_MS;
+    sessions.set(pairing_id, {
+      expires_at,
+      confirmed_at: null,
+      device_label: null,
+      client_id: null,
+    });
+    res.json({
+      pairing_id,
+      expires_at: new Date(expires_at).toISOString().replace(/\.\d{3}Z$/, "Z"),
+      ttl_ms: PAIRING_TTL_MS,
+      fingerprint: tokenStore.masterFingerprint(),
+      daemon: {
+        host: config?.host || "127.0.0.1",
+        port: config?.port || 7430,
+      },
+      // Base URLs a LAN device can reach; the web builds `<url>/#pair=<pid>`
+      // so a phone can scan a QR and land already authenticating.
+      lan_urls: reachableUrls({ host: config?.host, port: config?.port }),
+    });
+  });
+
+  // ── POST /pair/confirm ────────────────────────────────────────────
+  // App side. Body: { pairing_id, label?, fingerprint? }. Returns the
+  // new client token. Nonce is one-shot.
+  app.post("/pair/confirm", (req, res) => {
+    purgeExpired();
+    const { pairing_id, label, fingerprint, kind } = req.body || {};
+    if (!pairing_id || typeof pairing_id !== "string") {
+      return res.status(400).json({ error: "pair/confirm: pairing_id required" });
+    }
+    const s = sessions.get(pairing_id);
+    if (!s) {
+      return res.status(404).json({ error: "pair/confirm: unknown or expired pairing_id" });
+    }
+    if (s.confirmed_at) {
+      return res.status(409).json({ error: "pair/confirm: already confirmed" });
+    }
+    if (Date.now() > s.expires_at) {
+      sessions.delete(pairing_id);
+      return res.status(410).json({ error: "pair/confirm: pairing_id expired" });
+    }
+    // Optional: device echoes back the fingerprint it saw on the QR.
+    // We don't reject mismatches (the daemon is the only one minting
+    // them anyway), but we surface it back so the device can decide.
+    const expectedFp = tokenStore.masterFingerprint();
+
+    const client = tokenStore.addClient(label || "device", kind || "device");
+    s.confirmed_at = Date.now();
+    s.device_label = client.label;
+    s.client_id = client.id;
+
+    res.json({
+      token: client.token,
+      client_id: client.id,
+      label: client.label,
+      kind: client.kind,
+      daemon_url: `http://${config?.host || "127.0.0.1"}:${config?.port || 7430}`,
+      fingerprint: expectedFp,
+      fingerprint_match:
+        typeof fingerprint === "string" ? fingerprint === expectedFp : null,
+    });
+  });
+
+  // ── GET /pair/status/:pairing_id ──────────────────────────────────
+  // For the CLI to poll while showing the QR. Returns pending|confirmed
+  // |expired. Never leaks the token.
+  app.get("/pair/status/:pairing_id", (req, res) => {
+    purgeExpired();
+    const s = sessions.get(req.params.pairing_id);
+    if (!s) return res.json({ status: "unknown" });
+    if (s.confirmed_at) {
+      return res.json({
+        status: "confirmed",
+        device_label: s.device_label,
+        client_id: s.client_id,
+        confirmed_at: new Date(s.confirmed_at).toISOString().replace(/\.\d{3}Z$/, "Z"),
+      });
+    }
+    if (Date.now() > s.expires_at) return res.json({ status: "expired" });
+    return res.json({
+      status: "pending",
+      expires_at: new Date(s.expires_at).toISOString().replace(/\.\d{3}Z$/, "Z"),
+    });
+  });
+
+  // ── GET /pair/list ────────────────────────────────────────────────
+  // Authenticated (auth middleware exempts /pair/*, so we re-check by
+  // hand here — only the master or an existing client can list peers).
+  app.get("/pair/list", (req, res) => {
+    if (!checkBearer(req, tokenStore)) return res.status(401).json({ error: "unauthorized" });
+    res.json({ clients: tokenStore.list() });
+  });
+
+  // ── DELETE /pair/revoke/:id ───────────────────────────────────────
+  app.delete("/pair/revoke/:id", (req, res) => {
+    if (!checkBearer(req, tokenStore)) return res.status(401).json({ error: "unauthorized" });
+    const ok = tokenStore.revoke(req.params.id);
+    if (!ok) return res.status(404).json({ error: "no such client" });
+    res.json({ revoked: req.params.id });
+  });
+}
+
+function checkBearer(req, tokenStore) {
+  const auth = req.get("authorization") || "";
+  const provided = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+  return tokenStore.has(provided);
+}
+
+// Exposed for tests.
+export function _resetSessionsForTest() {
+  sessions.clear();
+}

package/src/host/daemon/api/plugins.js

@@ -0,0 +1,19 @@
+// Daemon plugin status surface.
+//   GET /plugins              status of every loaded plugin
+//   GET /plugins/:id/status   single plugin
+export function register(app, { plugins }) {
+  app.get("/plugins", (_req, res) => {
+    if (!plugins) return res.json({});
+    res.json(plugins.status());
+  });
+
+  app.get("/plugins/:id/status", (req, res) => {
+    if (!plugins) return res.status(404).end();
+    const inst = plugins.get(req.params.id);
+    if (!inst)
+      return res
+        .status(404)
+        .json({ error: `plugin ${req.params.id} not loaded` });
+    res.json(inst.status?.() || {});
+  });
+}

package/src/host/daemon/api/projects.js

@@ -0,0 +1,35 @@
+// Project lifecycle endpoints.
+//   GET    /projects               list registered projects
+//   POST   /projects               register a project by path
+//   DELETE /projects/:id           unregister
+//   POST   /projects/:id/rebuild   force a context rebuild from disk
+export function register(app, { projects, registries, addProjectGlobally }) {
+  app.get("/projects", (_req, res) => res.json(projects.list()));
+
+  app.post("/projects", (req, res) => {
+    const { path: p } = req.body || {};
+    if (!p) return res.status(400).json({ error: "path required" });
+    try {
+      const entry = projects.register(p);
+      addProjectGlobally(entry.path);
+      registries.ensure(entry);
+      res.status(201).json({ id: entry.id, path: entry.path });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.delete("/projects/:id", (req, res) => {
+    const ok = projects.unregister(req.params.id);
+    res.status(ok ? 204 : 404).end();
+  });
+
+  app.post("/projects/:id/rebuild", (req, res) => {
+    try {
+      const result = projects.rebuild(req.params.id);
+      res.json({ ok: true, ...result });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+}

package/src/host/daemon/api/routines.js

@@ -0,0 +1,84 @@
+// Per-project scheduled tasks. Storage lives in ~/.apx/projects/<id>/routines.json
+// (never inside the repo's .apc/).
+//
+//   GET    /projects/:pid/routines
+//   GET    /projects/:pid/routines/:name
+//   POST   /projects/:pid/routines
+//   DELETE /projects/:pid/routines/:name
+//   POST   /projects/:pid/routines/:name/enable
+//   POST   /projects/:pid/routines/:name/disable
+//   POST   /projects/:pid/routines/:name/run
+import {
+  listRoutines,
+  getRoutine,
+  upsertRoutine,
+  deleteRoutine,
+  setEnabled as setRoutineEnabled,
+  runRoutineNow,
+} from "../routines.js";
+
+export function register(app, { projects, registries, plugins, project, config }) {
+  app.get("/projects/:pid/routines", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    res.json(listRoutines(p.storagePath));
+  });
+
+  app.get("/projects/:pid/routines/:name", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const r = getRoutine(p.storagePath, req.params.name);
+    if (!r) return res.status(404).json({ error: "routine not found" });
+    res.json(r);
+  });
+
+  app.post("/projects/:pid/routines", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    try {
+      // Accepts every field including the pipeline extensions
+      // (pre_commands, post_commands, skip_prompt_on).
+      const r = upsertRoutine(p.storagePath, req.body || {});
+      res.status(201).json(r);
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.delete("/projects/:pid/routines/:name", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const ok = deleteRoutine(p.storagePath, req.params.name);
+    res.status(ok ? 204 : 404).end();
+  });
+
+  app.post("/projects/:pid/routines/:name/enable", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    setRoutineEnabled(p.storagePath, req.params.name, true);
+    res.json({ ok: true });
+  });
+
+  app.post("/projects/:pid/routines/:name/disable", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    setRoutineEnabled(p.storagePath, req.params.name, false);
+    res.json({ ok: true });
+  });
+
+  app.post("/projects/:pid/routines/:name/run", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const r = getRoutine(p.storagePath, req.params.name);
+    if (!r) return res.status(404).json({ error: "routine not found" });
+    try {
+      const result = await runRoutineNow(
+        { project: p, projects, plugins, registries, globalConfig: config },
+        r
+      );
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+}

package/src/host/daemon/api/run.js

@@ -0,0 +1,55 @@
+// POST /run { cmd, cwd?, project?, timeout_ms? }
+// Bash one-shot. `cwd` defaults to the project path (by id), then the first
+// non-default registered project, then process.cwd().
+import path from "node:path";
+import { execFile } from "node:child_process";
+
+export function register(app, { projects }) {
+  app.post("/run", (req, res) => {
+    const {
+      cmd,
+      cwd: cwdOverride,
+      project: projectRef,
+      timeout_ms = 30000,
+    } = req.body || {};
+    if (!cmd) return res.status(400).json({ error: "cmd required" });
+
+    let cwd = cwdOverride || null;
+    if (!cwd) {
+      let entry = null;
+      if (projectRef !== undefined && projectRef !== null) {
+        const all = projects.list();
+        const ref = String(projectRef);
+        entry = all.find(
+          (p) => String(p.id) === ref || p.path === path.resolve(ref)
+        );
+      }
+      if (!entry) {
+        const all = projects.list().filter((p) => p.id !== 0);
+        entry = all[0] || projects.get(0);
+      }
+      cwd = entry ? entry.path : process.cwd();
+    }
+
+    const timeout = Math.min(
+      Math.max(parseInt(timeout_ms, 10) || 30000, 1000),
+      300000
+    );
+
+    execFile(
+      "bash",
+      ["-c", cmd],
+      { cwd, timeout, maxBuffer: 4 * 1024 * 1024 },
+      (err, stdout, stderr) => {
+        const exit_code = err?.code ?? (err ? 1 : 0);
+        res.json({
+          ok: !err || exit_code === 0,
+          exit_code,
+          stdout: stdout || "",
+          stderr: stderr || "",
+          cwd,
+        });
+      }
+    );
+  });
+}

package/src/host/daemon/api/runtimes.js

@@ -0,0 +1,219 @@
+// External runtime adapters (claude-code, codex, opencode, aider, …) +
+// session-resume that reads back what a runtime left on disk.
+//
+//   GET  /runtimes
+//   GET  /env/detect
+//   POST /projects/:pid/agents/:slug/runtime
+//   GET  /projects/:pid/sessions/:id/resume?summarize=true
+import fs from "node:fs";
+import path from "node:path";
+import { readAgents } from "../../../core/parser.js";
+import { readSessionFrontmatter } from "../../../core/session-store.js";
+import { buildAgentSystem } from "../../../core/agent-system.js";
+import { getRuntime, RUNTIME_IDS } from "../runtimes/index.js";
+import { detectAll } from "../env-detect.js";
+import {
+  buildApfHint,
+  createRuntimeSession,
+  closeRuntimeSession,
+  extractApfResult,
+} from "../apc-runtime-context.js";
+import { runSuperAgent, isSuperAgentEnabled } from "../super-agent.js";
+
+export function register(app, { projects, registries, plugins, project, config }) {
+  app.get("/runtimes", (_req, res) =>
+    res.json({ runtimes: RUNTIME_IDS })
+  );
+
+  app.get("/env/detect", async (_req, res) => {
+    const detected = await detectAll();
+    res.json(detected);
+  });
+
+  app.post("/projects/:pid/agents/:slug/runtime", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { runtime, prompt, timeoutMs } = req.body || {};
+    if (!runtime || !prompt)
+      return res.status(400).json({ error: "runtime and prompt required" });
+
+    const agents = readAgents(p.path);
+    const agent = agents.find((a) => a.slug === req.params.slug);
+    if (!agent) return res.status(404).json({ error: "agent not found" });
+
+    let rt;
+    try {
+      rt = getRuntime(runtime);
+    } catch (e) {
+      return res.status(400).json({ error: e.message });
+    }
+
+    let projectName = path.basename(p.path);
+    try {
+      const meta = JSON.parse(
+        fs.readFileSync(path.join(p.path, ".apc", "project.json"), "utf8")
+      );
+      if (meta.name) projectName = meta.name;
+    } catch {}
+
+    const session = createRuntimeSession({
+      projectRoot: p.path,
+      storageRoot: p.storagePath,
+      agentSlug: agent.slug,
+      runtime,
+      title: req.body?.title,
+      taskRef: req.body?.task_ref || "",
+    });
+
+    const system = buildAgentSystem(p, agent, {
+      invocation: "runtime",
+      runtime,
+      extraParts: [
+        buildApfHint({
+          projectName,
+          projectPath: p.path,
+          agentSlug: agent.slug,
+          sessionId: session.id,
+        }),
+      ],
+    });
+
+    try {
+      const r = await rt.run({
+        system,
+        prompt,
+        cwd: p.path,
+        timeoutMs: timeoutMs || 5 * 60 * 1000,
+      });
+
+      const apfResult =
+        extractApfResult(r.output) || (r.output || "").slice(0, 200);
+      closeRuntimeSession({
+        filePath: session.path,
+        externalSessionPath: r.externalSessionPath || null,
+        exitCode: r.exitCode,
+        result: apfResult,
+      });
+
+      p.logMessage({
+        agent_slug: agent.slug,
+        channel: "runtime",
+        direction: "in",
+        author: "user",
+        body: prompt,
+        meta: { runtime, apc_session: session.id },
+      });
+      p.logMessage({
+        agent_slug: agent.slug,
+        channel: "runtime",
+        direction: "out",
+        type: "agent",
+        actor_id: agent.slug,
+        actor_kind: "agent",
+        author: agent.slug,
+        body: r.output || "",
+        meta: {
+          runtime,
+          exit_code: r.exitCode,
+          external_session_path: r.externalSessionPath || null,
+          session_id: r.sessionId || null,
+          apc_session: session.id,
+        },
+      });
+      projects.rebuild(p.id);
+
+      res.json({
+        runtime,
+        exit_code: r.exitCode,
+        output: r.output,
+        stderr: r.stderr,
+        external_session_path: r.externalSessionPath || null,
+        session_id: r.sessionId || null,
+        apc_session: session.id,
+      });
+    } catch (e) {
+      try {
+        closeRuntimeSession({
+          filePath: session.path,
+          exitCode: -1,
+          result: `error: ${e.message.slice(0, 200)}`,
+        });
+      } catch {}
+      res.status(500).json({ error: e.message, apc_session: session.id });
+    }
+  });
+
+  // ---- Session resume — reads APC session file + (optionally) external transcript ----
+  app.get("/projects/:pid/sessions/:id/resume", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { id } = req.params;
+
+    const sessionRoots = [
+      path.join(p.storagePath || p.path, "agents"),
+      path.join(p.path, ".apc", "agents"),
+    ];
+    let sessionFile = null;
+    let agentSlug = null;
+    for (const agentsDir of sessionRoots) {
+      if (!fs.existsSync(agentsDir)) continue;
+      for (const slug of fs.readdirSync(agentsDir)) {
+        const f = path.join(agentsDir, slug, "sessions", `${id}.md`);
+        if (fs.existsSync(f)) {
+          sessionFile = f;
+          agentSlug = slug;
+          break;
+        }
+      }
+      if (sessionFile) break;
+    }
+    if (!sessionFile)
+      return res.status(404).json({ error: `session ${id} not found` });
+
+    const session = readSessionFrontmatter(sessionFile);
+    const out = {
+      id,
+      agent: agentSlug,
+      session_path: sessionFile,
+      frontmatter: session?.fm || {},
+      external_transcript: null,
+      summary: null,
+    };
+
+    const externalPath = session?.fm?.external_session_path;
+    if (externalPath && fs.existsSync(externalPath)) {
+      const stat = fs.statSync(externalPath);
+      const raw = fs.readFileSync(externalPath, "utf8");
+      out.external_transcript = {
+        path: externalPath,
+        size: stat.size,
+        tail: raw.length > 32 * 1024 ? raw.slice(-32 * 1024) : raw,
+      };
+    }
+
+    if (req.query.summarize === "true" && isSuperAgentEnabled(config)) {
+      try {
+        const prompt =
+          `Summarize what happened in this APC session in 4 concrete bullets.\n\n` +
+          `Frontmatter:\n${JSON.stringify(out.frontmatter, null, 2)}\n\n` +
+          (out.external_transcript
+            ? `External transcript (last ${out.external_transcript.tail.length} chars):\n${out.external_transcript.tail}`
+            : `(no external transcript)`);
+        const sa = await runSuperAgent({
+          globalConfig: config,
+          projects,
+          plugins,
+          registries,
+          prompt,
+          channel: "api",
+          contextNote: `Resume request for session ${id}.`,
+        });
+        out.summary = sa.text;
+      } catch (e) {
+        out.summary = `(super-agent failed: ${e.message})`;
+      }
+    }
+
+    res.json(out);
+  });
+}