@agentprojectcontext/apx 1.0.3

package/src/cli/commands/session.js

@@ -0,0 +1,387 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findApfRoot, readAgents } from "../../core/parser.js";
+import { ensureAgentDir } from "../../core/scaffold.js";
+import { generateSessionId } from "../../core/session-store.js";
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+const STALE_HOURS = 1;
+
+function requireRoot() {
+  const root = findApfRoot();
+  if (!root) throw new Error("not inside an APC project (run `apx init` first)");
+  return root;
+}
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+function readStdinSync() {
+  const chunks = [];
+  const buf = Buffer.alloc(65536);
+  try {
+    while (true) {
+      const bytes = fs.readSync(0, buf, 0, buf.length);
+      if (!bytes) break;
+      chunks.push(buf.slice(0, bytes).toString("utf8"));
+    }
+  } catch {}
+  return chunks.join("");
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith("---\n")) return { fm: {}, bodyStart: 0 };
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return { fm: {}, bodyStart: 0 };
+  const fmText = text.slice(4, end);
+  const fm = {};
+  for (const line of fmText.split("\n")) {
+    const m = line.match(/^([a-zA-Z_]+):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return { fm, bodyStart: end + 4 };
+}
+
+function setFrontmatterField(text, field, value) {
+  if (!text.startsWith("---\n")) return text;
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return text;
+  const fmText = text.slice(4, end);
+  const lines = fmText.split("\n");
+  let found = false;
+  const out = lines.map((line) => {
+    if (line.match(new RegExp(`^${field}:`))) {
+      found = true;
+      return `${field}: ${value}`;
+    }
+    return line;
+  });
+  if (!found) out.push(`${field}: ${value}`);
+  return `---\n${out.join("\n")}\n---${text.slice(end + 4)}`;
+}
+
+function listAllSessions(root) {
+  const agentsDir = path.join(root, ".apc", "agents");
+  if (!fs.existsSync(agentsDir)) return [];
+  const out = [];
+  for (const slug of fs.readdirSync(agentsDir)) {
+    const dir = path.join(agentsDir, slug, "sessions");
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith(".md")) continue;
+      const filepath = path.join(dir, f);
+      const body = fs.readFileSync(filepath, "utf8");
+      const { fm } = parseFrontmatter(body);
+      out.push({
+        agent: slug,
+        filename: f,
+        path: filepath,
+        id: fm.id || f.replace(/\.md$/, ""),
+        title: fm.title || "(no title)",
+        status: fm.status || "",
+        started: fm.started || "",
+        completed: fm.completed || "",
+        result: fm.result || "",
+        task_ref: fm.task_ref || "",
+      });
+    }
+  }
+  return out;
+}
+
+function findSessionById(root, id) {
+  for (const s of listAllSessions(root)) {
+    if (s.id === id || s.filename.replace(/\.md$/, "") === id) return s;
+  }
+  return null;
+}
+
+function statusEmoji(status) {
+  if (/Completada|complete/i.test(status)) return "✅";
+  if (/En progreso|in.progress/i.test(status)) return "🔄";
+  if (/stale|Cerrada/i.test(status)) return "⚠️";
+  return "❓";
+}
+
+function hoursSince(iso) {
+  if (!iso) return Infinity;
+  const t = Date.parse(iso);
+  if (isNaN(t)) return Infinity;
+  return (Date.now() - t) / 3600_000;
+}
+
+// ---------------------------------------------------------------------
+
+export function cmdSessionNew(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx session new: missing <agent-slug>");
+  const title = args.flags.title === true ? null : args.flags.title;
+  if (!title) throw new Error("apx session new: --title required");
+
+  const root = requireRoot();
+  const agents = readAgents(root);
+  if (!agents.find((a) => a.slug === slug)) {
+    throw new Error(`agent "${slug}" not found in AGENTS.md`);
+  }
+
+  ensureAgentDir(root, slug);
+  const id = generateSessionId(root, slug);
+  const filename = `${id}.md`;
+  const filepath = path.join(root, ".apc", "agents", slug, "sessions", filename);
+
+  const taskRef = args.flags["task-ref"] === true ? "" : (args.flags["task-ref"] || "");
+  let body = "";
+  if (args.flags.body === "-") body = readStdinSync();
+  else if (args.flags.body && args.flags.body !== true) body = String(args.flags.body);
+
+  const started = nowIso();
+  const content =
+    `---\n` +
+    `id: ${id}\n` +
+    `agent: ${slug}\n` +
+    `title: ${title}\n` +
+    `description: \n` +
+    `task_ref: ${taskRef}\n` +
+    `status: open\n` +
+    `date: ${started.slice(0, 10)}\n` +
+    `started: ${started}\n` +
+    `completed: \n` +
+    `---\n\n` +
+    `# ${title}\n\n${body}\n`;
+
+  fs.writeFileSync(filepath, content);
+  console.log(`✅ Session created: ${id}`);
+  console.log(`   Agent: ${slug}`);
+  console.log(`   Title: ${title}`);
+  console.log(`   File: ${path.relative(process.cwd(), filepath)}`);
+}
+
+export function cmdSessionList(args) {
+  const root = requireRoot();
+  const slug = args._[0];
+  const limit = args.flags.last ? parseInt(args.flags.last, 10) : null;
+
+  let sessions = listAllSessions(root);
+  if (slug) sessions = sessions.filter((s) => s.agent === slug);
+  sessions.sort((a, b) => b.filename.localeCompare(a.filename));
+  if (limit) sessions = sessions.slice(0, limit);
+
+  if (sessions.length === 0) {
+    console.log("(no sessions)");
+    return;
+  }
+
+  console.log(
+    `${"ID".padEnd(16)} ${"S".padEnd(2)} ${"AGENT".padEnd(12)} TITLE`
+  );
+  console.log(
+    `${"─".repeat(14).padEnd(16)} ${"─".repeat(1).padEnd(2)} ${"─".repeat(10).padEnd(12)} ${"─".repeat(40)}`
+  );
+  for (const s of sessions) {
+    console.log(
+      `${s.id.padEnd(16)} ${statusEmoji(s.status).padEnd(2)} ${s.agent.padEnd(12)} ${s.title.slice(0, 60)}`
+    );
+  }
+}
+
+export function cmdSessionGet(args) {
+  const id = args._[0];
+  if (!id) throw new Error("apx session get: missing <id>");
+  const root = requireRoot();
+  const s = findSessionById(root, id);
+  if (!s) throw new Error(`session "${id}" not found`);
+  if (args.flags.body) {
+    process.stdout.write(fs.readFileSync(s.path, "utf8"));
+    return;
+  }
+  console.log(`id:        ${s.id}`);
+  console.log(`agent:     ${s.agent}`);
+  console.log(`title:     ${s.title}`);
+  console.log(`status:    ${s.status}`);
+  console.log(`started:   ${s.started}`);
+  console.log(`completed: ${s.completed}`);
+  console.log(`task_ref:  ${s.task_ref}`);
+  console.log(`result:    ${s.result}`);
+  console.log(`file:      ${path.relative(process.cwd(), s.path)}`);
+}
+
+export function cmdSessionUpdate(args) {
+  const id = args._[0];
+  if (!id) throw new Error("apx session update: missing <id>");
+  const root = requireRoot();
+  const s = findSessionById(root, id);
+  if (!s) throw new Error(`session "${id}" not found`);
+
+  let text = fs.readFileSync(s.path, "utf8");
+  const fields = ["status", "result", "title", "task_ref", "completed"];
+  let touched = [];
+  for (const k of fields) {
+    if (args.flags[k] !== undefined && args.flags[k] !== true) {
+      text = setFrontmatterField(text, k, args.flags[k]);
+      touched.push(k);
+    }
+  }
+  if (touched.length === 0) throw new Error("apx session update: no fields provided");
+  fs.writeFileSync(s.path, text);
+  console.log(`updated ${s.id}: ${touched.join(", ")}`);
+}
+
+export function cmdSessionClose(args) {
+  const id = args._[0];
+  if (!id) throw new Error("apx session close: missing <id>");
+  const root = requireRoot();
+  const s = findSessionById(root, id);
+  if (!s) throw new Error(`session "${id}" not found`);
+
+  let text = fs.readFileSync(s.path, "utf8");
+  text = setFrontmatterField(text, "status", "✅ Completada");
+  text = setFrontmatterField(text, "completed", nowIso());
+  if (args.flags.result && args.flags.result !== true) {
+    text = setFrontmatterField(text, "result", String(args.flags.result));
+  }
+  fs.writeFileSync(s.path, text);
+  console.log(`✅ Session ${s.id} closed`);
+}
+
+export function cmdSessionCheck() {
+  const root = requireRoot();
+  const sessions = listAllSessions(root).filter((s) =>
+    /En progreso/i.test(s.status)
+  );
+
+  if (sessions.length === 0) {
+    console.log("✅ No active sessions. Safe to proceed.");
+    process.exit(0);
+  }
+
+  let active = 0;
+  let stale = [];
+  for (const s of sessions) {
+    const h = hoursSince(s.started);
+    if (h >= STALE_HOURS) {
+      stale.push({ ...s, hours: h });
+    } else {
+      console.log(`🔄 ACTIVE: ${s.id} (${s.hours = h.toFixed(1)}h ago)`);
+      console.log(`   Agent: ${s.agent}`);
+      console.log(`   Title: ${s.title}`);
+      active++;
+    }
+  }
+  if (stale.length) {
+    console.log(`\nStale sessions (>${STALE_HOURS}h, can be auto-closed):`);
+    for (const s of stale) {
+      console.log(`⚠️  ${s.id} (${s.hours.toFixed(1)}h) — ${s.agent} — ${s.title}`);
+    }
+    console.log(`   → Run: apx session close-stale`);
+  }
+  if (active === 0) {
+    console.log("✅ Safe to proceed (only stale sessions).");
+    process.exit(0);
+  }
+  console.log("\n⛔ Another agent is working. Wait or coordinate.");
+  process.exit(1);
+}
+
+export async function cmdSessionResume(args) {
+  const id = args._[0];
+  if (!id) throw new Error("apx session resume: missing <session-id>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  const summarize = args.flags.summary || args.flags.summarize ? "true" : "false";
+  const result = await http.get(
+    `/projects/${pid}/sessions/${id}/resume?summarize=${summarize}`
+  );
+
+  console.log(`# session ${id} (agent: ${result.agent})`);
+  console.log(`path: ${result.session_path}`);
+  console.log("");
+  console.log("## frontmatter");
+  for (const [k, v] of Object.entries(result.frontmatter || {})) {
+    if (v) console.log(`${k}: ${v}`);
+  }
+  console.log("");
+  if (result.external_transcript) {
+    const t = result.external_transcript;
+    console.log(`## external transcript`);
+    console.log(`path: ${t.path}`);
+    console.log(`size: ${t.size} bytes`);
+    if (args.flags.full) {
+      console.log("");
+      console.log("--- tail ---");
+      process.stdout.write(t.tail);
+    } else {
+      console.log(`(use --full to print the last ${t.tail.length} chars)`);
+    }
+  } else if (result.frontmatter?.external_session_path) {
+    console.log(`## external transcript: ${result.frontmatter.external_session_path}`);
+    console.log("(file no longer exists on disk)");
+  } else {
+    console.log("## external transcript: (none — runtime didn't report one)");
+  }
+  if (result.summary) {
+    console.log("");
+    console.log("## summary (super-agent)");
+    console.log(result.summary);
+  } else if (summarize === "true") {
+    console.log("");
+    console.log("## summary: (failed — super-agent not configured?)");
+  }
+}
+
+export function cmdSessionCloseStale() {
+  const root = requireRoot();
+  const sessions = listAllSessions(root).filter((s) =>
+    /En progreso/i.test(s.status)
+  );
+  let closed = 0;
+  for (const s of sessions) {
+    const h = hoursSince(s.started);
+    if (h < STALE_HOURS) continue;
+    let text = fs.readFileSync(s.path, "utf8");
+    text = setFrontmatterField(
+      text,
+      "status",
+      `⚠️ Cerrada automáticamente (stale >${STALE_HOURS}h)`
+    );
+    text = setFrontmatterField(text, "completed", nowIso());
+    text = setFrontmatterField(
+      text,
+      "result",
+      `Auto-closed by apx (stale >${h.toFixed(1)}h without completion)`
+    );
+    fs.writeFileSync(s.path, text);
+    console.log(`⚠️  Closed stale: ${s.id} (${h.toFixed(1)}h old)`);
+    closed++;
+  }
+  if (closed === 0) console.log("No stale sessions found.");
+  else console.log(`Closed ${closed} stale session(s).`);
+}
+
+export async function cmdSessionCompact(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx session compact: missing <agent-slug>");
+  const convId = args.flags.conversation === true ? null : (args.flags.conversation || null);
+  const model = args.flags.model === true ? null : (args.flags.model || null);
+
+  const pid = await resolveProjectId(args?.flags?.project);
+
+  const url = convId
+    ? `/projects/${pid}/agents/${slug}/conversations/${convId}/compact`
+    : `/projects/${pid}/agents/${slug}/compact`;
+
+  const body = model ? { model } : {};
+
+  console.log(`Compacting conversation for ${slug}${convId ? ` (${convId})` : " (latest)"}...`);
+  const result = await http.post(url, body);
+
+  console.log(`✅ Compacted ${result.compacted_turns} turns → ${result.filename}`);
+  console.log(`   Kept last ${result.kept_turns} turns verbatim`);
+  console.log(`   Model: ${result.model}`);
+  if (result.usage) {
+    const u = result.usage;
+    console.log(`   Tokens: ${u.input_tokens ?? u.prompt_tokens ?? "?"} in / ${u.output_tokens ?? u.completion_tokens ?? "?"} out`);
+  }
+  console.log("");
+  console.log("Summary:");
+  console.log("─".repeat(60));
+  console.log(result.summary);
+}

package/src/cli/commands/skills.js

@@ -0,0 +1,153 @@
+// apx skills — install the APX skill into AI IDE rule files.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import readline from "node:readline";
+import { findApfRoot } from "../../core/parser.js";
+import { IDE_TARGETS, installIdeSkills, installGlobalSkills } from "../../core/scaffold.js";
+
+// ---------------------------------------------------------------------------
+// Prompt helper
+// ---------------------------------------------------------------------------
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// apx skills add [<target>...] [--global] [--project]
+// ---------------------------------------------------------------------------
+
+export async function cmdSkillsAdd(args) {
+  const forceGlobal = !!args.flags.global;
+  const forceProject = !!args.flags.project;
+  const hasTargets = args._.length > 0;
+
+  // If neither flag given and no specific targets, ask the user.
+  let scope;
+  if (forceGlobal) {
+    scope = "global";
+  } else if (forceProject || hasTargets) {
+    scope = "project";
+  } else {
+    console.log("Where do you want to install the APX skill?\n");
+    console.log("  [g] Global  — ~/.claude/skills/, ~/.cursor/skills/, ~/.agents/skills/");
+    console.log("               Works across all your projects (recommended for first install).");
+    console.log("  [p] Project — .claude/skills/apx/, .cursor/rules/apx.mdc, .windsurf/rules/apx.md, etc.");
+    console.log("               Scoped to this project only.\n");
+    const answer = await ask("Choice [g/p] (default: g): ");
+    scope = answer === "p" || answer === "project" ? "project" : "global";
+  }
+
+  if (scope === "global") {
+    const results = installGlobalSkills();
+    const home = os.homedir();
+    console.log("");
+    for (const r of results) {
+      const short = r.file.replace(home, "~");
+      console.log(`  ${r.status.padEnd(10)}  ${short}`);
+    }
+    console.log("\n  Loaded by: Claude Code, Cursor, Codex (OpenAI), Antigravity, and skills.sh-compatible tools.");
+    console.log("  Activates automatically when working in a project with AGENTS.md or .apc/");
+    return;
+  }
+
+  // Project scope
+  const root = findApfRoot();
+  if (!root) throw new Error("not inside an APC project (run `apx init` first)");
+
+  const requested = hasTargets ? args._.map((s) => s.toLowerCase()) : null;
+  if (requested) {
+    const unknown = requested.filter((id) => !IDE_TARGETS.some((t) => t.id === id));
+    if (unknown.length) {
+      throw new Error(
+        `unknown target(s): ${unknown.join(", ")}\nAvailable: ${IDE_TARGETS.map((t) => t.id).join(", ")}`
+      );
+    }
+  }
+
+  const results = installIdeSkills(root, requested);
+  console.log("");
+  const width = Math.max(...results.map((r) => r.label.length));
+  for (const r of results) {
+    console.log(`  ${r.label.padEnd(width)}  ${r.status.padEnd(16)}  ${r.file}`);
+  }
+  const notes = IDE_TARGETS.filter((t) => t.note && (!requested || requested.includes(t.id)));
+  if (notes.length) {
+    console.log("");
+    for (const t of notes) console.log(`  note: ${t.note}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apx skills list
+// ---------------------------------------------------------------------------
+
+export async function cmdSkillsList() {
+  const root = findApfRoot();
+  const skillsDir = root ? path.join(root, ".apc", "skills") : null;
+  const files = skillsDir && fs.existsSync(skillsDir)
+    ? fs.readdirSync(skillsDir).filter((f) => f.endsWith(".md"))
+    : [];
+
+  if (files.length === 0) {
+    console.log("(no skills installed in .apc/skills/)");
+    return;
+  }
+  for (const f of files) console.log(f.replace(/\.md$/, ""));
+}
+
+// ---------------------------------------------------------------------------
+// apx skills status
+// ---------------------------------------------------------------------------
+
+export async function cmdSkillsStatus() {
+  const root = findApfRoot();
+
+  // Global
+  const SKILL_SLUGS = ["apx", "apc-context"];
+  console.log("Global skills:");
+  const GLOBAL_DIRS = [
+    { label: "Claude Code / Cursor compat", dir: path.join(os.homedir(), ".claude", "skills") },
+    { label: "Cursor (primary)",            dir: path.join(os.homedir(), ".cursor", "skills") },
+    { label: "Codex",                       dir: path.join(os.homedir(), ".codex",  "skills") },
+    { label: "Antigravity / others",        dir: path.join(os.homedir(), ".agents", "skills") },
+  ];
+  const gw = Math.max(...GLOBAL_DIRS.map((d) => d.label.length));
+  const sw = Math.max(...SKILL_SLUGS.map((s) => s.length));
+  for (const { label, dir } of GLOBAL_DIRS) {
+    for (const slug of SKILL_SLUGS) {
+      const dest = path.join(dir, slug, "SKILL.md");
+      console.log(`  ${label.padEnd(gw)}  ${slug.padEnd(sw)}  ${fs.existsSync(dest) ? "installed" : "not installed"}`);
+    }
+  }
+
+  // Project-scoped
+  if (root) {
+    console.log("\nProject skills (this project only):");
+    const width = Math.max(...IDE_TARGETS.map((t) => t.label.length));
+    for (const t of IDE_TARGETS) {
+      const dest = path.join(root, t.file);
+      let status;
+      if (!fs.existsSync(dest)) {
+        status = "not installed";
+      } else if (t.guard) {
+        const txt = fs.readFileSync(dest, "utf8");
+        status = txt.includes(t.guard) ? "installed" : "file exists (no apx block)";
+      } else {
+        status = "installed";
+      }
+      console.log(`  ${t.label.padEnd(width)}  ${status}`);
+    }
+    console.log(`  ${"Codex / Antigravity".padEnd(width)}  reads AGENTS.md (automatic)`);
+  }
+
+  console.log("\n  Tip: run `apx skills add` for an interactive install.");
+  console.log("  Claude Desktop has no project-file support (use apx-mcp instead).");
+}

package/src/cli/commands/telegram.js

@@ -0,0 +1,48 @@
+import { http } from "../http.js";
+
+export async function cmdTelegramSend(args) {
+  const text = args._[0];
+  if (!text) throw new Error("apx telegram send: missing <text>");
+  const chat_id = args.flags.chat === true ? undefined : args.flags.chat;
+  const result = await http.post("/telegram/send", { chat_id, text });
+  console.log(`✅ sent (message_id=${result.message_id})`);
+}
+
+export async function cmdTelegramStatus() {
+  const s = await http.get("/telegram/status");
+  console.log(`enabled: ${s.enabled}`);
+  if (!s.channels || s.channels.length === 0) {
+    console.log("(no channels configured)");
+    return;
+  }
+  for (const c of s.channels) {
+    console.log("");
+    console.log(`channel:             ${c.name}`);
+    console.log(`  polling:           ${c.polling}`);
+    console.log(`  bot_token:         ${c.bot_token_present ? "✓" : "✗"} (source: ${c.bot_token_source || "—"})`);
+    console.log(`  chat_id:           ${c.chat_id || "(unset)"}`);
+    console.log(`  project:           ${c.project || "(first registered)"}`);
+    console.log(`  route_to_agent:    ${c.route_to_agent || "(none → super-agent fallback)"}`);
+    console.log(`  respond_w/engine:  ${c.respond_with_engine}`);
+    console.log(`  offset:            ${c.offset}`);
+    console.log(`  last_update_at:    ${c.last_update_at || "(never)"}`);
+    console.log(`  last_error:        ${c.last_error || "(none)"}`);
+  }
+}
+
+export function cmdTelegramSetup() {
+  console.log(`Edit ~/.apx/config.json — telegram section:
+
+  "telegram": {
+    "enabled": true,
+    "bot_token": "<your bot token from @BotFather>",
+    "chat_id": "<numeric chat id where outbound goes>",
+    "poll_interval_ms": 1500,
+    "route_to_agent": "<slug>",          // optional: who auto-replies
+    "respond_with_engine": true          // false → only log inbound
+  }
+
+Then restart the daemon (apx daemon stop && any apx command will auto-start it).
+You can verify with: apx telegram status
+`);
+}

package/src/cli/http.js

@@ -0,0 +1,102 @@
+// Tiny HTTP client to talk to the APX daemon. Auto-starts the daemon if down.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DEFAULT_PORT = parseInt(process.env.APX_PORT || "7430", 10);
+const DEFAULT_HOST = process.env.APX_HOST || "127.0.0.1";
+
+function baseUrl() {
+  return `http://${DEFAULT_HOST}:${DEFAULT_PORT}`;
+}
+
+async function ping(timeoutMs = 400) {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    const res = await fetch(`${baseUrl()}/health`, { signal: ctrl.signal });
+    clearTimeout(t);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function findDaemonEntry() {
+  const candidates = [
+    path.resolve(__dirname, "..", "daemon", "index.js"),
+    path.resolve(__dirname, "..", "node_modules", "apx-daemon", "src", "index.js"),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+async function autoStart({ silent = false } = {}) {
+  const entry = findDaemonEntry();
+  if (!entry) {
+    throw new Error(
+      "apx daemon not installed and not found at ../daemon/src/index.js. Install with `npm i -g apx-daemon` or run from the apc monorepo."
+    );
+  }
+  const logPath = path.join(os.homedir(), ".apx", "daemon.log");
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const out = fs.openSync(logPath, "a");
+  const child = spawn(process.execPath, [entry], {
+    detached: true,
+    stdio: ["ignore", out, out],
+    env: { ...process.env },
+  });
+  child.unref();
+  if (!silent) process.stderr.write("apx: starting daemon...\n");
+  // Wait up to 4s for /health
+  for (let i = 0; i < 20; i++) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (await ping(200)) return true;
+  }
+  throw new Error("apx daemon failed to start within 4s — check ~/.apx/daemon.log");
+}
+
+export async function ensureDaemon(opts = {}) {
+  if (await ping()) return;
+  await autoStart(opts);
+}
+
+async function request(method, path, body, opts = {}) {
+  if (opts.autoStart !== false) await ensureDaemon();
+  else if (!(await ping())) {
+    throw new Error(`apx daemon not running (no response on ${baseUrl()})`);
+  }
+  const res = await fetch(`${baseUrl()}${path}`, {
+    method,
+    headers: body ? { "content-type": "application/json" } : {},
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    if (!res.ok) throw new Error(`${method} ${path} → ${res.status}: ${text}`);
+    return text;
+  }
+  if (!res.ok) {
+    const msg = json?.error || `${method} ${path} → ${res.status}`;
+    throw new Error(msg);
+  }
+  return json;
+}
+
+export const http = {
+  get: (p, opts) => request("GET", p, undefined, opts),
+  post: (p, body, opts) => request("POST", p, body, opts),
+  put: (p, body, opts) => request("PUT", p, body, opts),
+  patch: (p, body, opts) => request("PATCH", p, body, opts),
+  delete: (p, opts) => request("DELETE", p, undefined, opts),
+  baseUrl,
+  ping,
+};