@agentprojectcontext/apx 1.24.0 → 1.27.1

package/src/{cli → interfaces/cli}/commands/identity.js

@@ -1,8 +1,5 @@
 import readline from "node:readline";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import { readIdentity, writeIdentity } from "../../core/identity.js";
+import { readIdentity, writeIdentity } from "../../../core/identity.js";
 
 function ask(rl, question, defaultVal) {
   return new Promise((resolve) => {
@@ -13,46 +10,6 @@ function ask(rl, question, defaultVal) {
   });
 }
 
-function askYN(rl, question, defaultYes = false) {
-  const hint = defaultYes ? "Y/n" : "y/N";
-  return new Promise((resolve) => {
-    rl.question(`${question} [${hint}]: `, (ans) => {
-      const a = ans.trim().toLowerCase();
-      if (!a) return resolve(defaultYes);
-      resolve(a === "y" || a === "yes");
-    });
-  });
-}
-
-const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
-
-function setupClaudePermissions() {
-  try {
-    let existing = {};
-    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
-      existing = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf8"));
-    }
-    const updated = {
-      ...existing,
-      permissions: {
-        ...(existing.permissions || {}),
-        allow: [
-          ...(existing.permissions?.allow || []),
-          "Bash(*)",
-          "Read(*)",
-          "Write(*)",
-          "Edit(*)",
-        ].filter((v, i, arr) => arr.indexOf(v) === i),
-      },
-    };
-    fs.mkdirSync(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
-    fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(updated, null, 2) + "\n");
-    return true;
-  } catch (e) {
-    return e.message;
-  }
-}
-
 // apx identity           — show
 // apx identity set       — interactive or --name/--owner/--context/--language flags
 // apx identity wizard    — full onboarding (called on first run)
@@ -65,14 +22,16 @@ export async function cmdIdentity(args) {
       console.log("No identity configured. Run: apx identity wizard");
       return;
     }
-    const { readConfig } = await import("../../core/config.js");
+    const { readConfig } = await import("../../../core/config.js");
     const cfg = readConfig();
     console.log("");
     console.log(`  Agent name  : ${id.agent_name}`);
     console.log(`  Personality : ${id.personality || "(not set)"}`);
     console.log(`  Owner       : ${id.owner_name}`);
     console.log(`  Context     : ${id.owner_context || "(not set)"}`);
-    console.log(`  Language    : ${cfg.user?.language || "en"}  (set via: apx config set user.language <code>)`);
+    console.log(`  Language    : ${cfg.user?.language || "en"}  (apx config set user.language <code>)`);
+    if (cfg.user?.locale) console.log(`  Locale      : ${cfg.user.locale}`);
+    if (cfg.user?.timezone) console.log(`  Timezone    : ${cfg.user.timezone}`);
     console.log(`  Last wakeup : ${id.last_wakeup || "(never)"}`);
     console.log(`  File        : ~/.apx/identity.json`);
     console.log("");
@@ -124,25 +83,9 @@ export async function runWizard() {
   const owner_name    = await ask(rl, "  Your name", existing.owner_name || "");
   const owner_context = await ask(rl, "  Context for the agent (what you build / work on — added to every system prompt)", existing.owner_context || "");
 
-  console.log("\n  Claude Code permissions");
-  console.log("  APX can configure Claude Code to allow terminal commands without prompts.");
-  console.log("  This adds Bash(*), Read(*), Write(*), Edit(*) to ~/.claude/settings.json\n");
-
-  const setupPerms = await askYN(rl, "  Set up Claude Code terminal permissions now?", false);
-
   rl.close();
 
   const id = writeIdentity({ agent_name, personality, owner_name, owner_context, last_wakeup: null });
   console.log(`\n  Identity saved to ~/.apx/identity.json`);
-
-  if (setupPerms) {
-    const result = setupClaudePermissions();
-    if (result === true) {
-      console.log(`  Claude Code permissions updated at ~/.claude/settings.json`);
-    } else {
-      console.log(`  Could not update Claude Code settings: ${result}`);
-    }
-  }
-
-  console.log(`  ${id.agent_name} is ready. Restart the daemon to send a wake-up message.\n`);
+  console.log(`  ${id.agent_name} is ready. Run ${"apx daemon reload"} after daemon changes.\n`);
 }

package/src/{cli → interfaces/cli}/commands/init.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { initApf } from "../../core/scaffold.js";
+import { initApf } from "../../../core/scaffold.js";
 
 export function cmdInit(args) {
   const dir = args._[0] || ".";

package/src/{cli → interfaces/cli}/commands/mcp.js

@@ -1,15 +1,61 @@
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
+import { findApfRoot } from "../../../core/parser.js";
+
+const VALID_SCOPES = new Set(["shared", "runtime", "global", "all"]);
+
+// Resolve --scope flag for add/remove (write ops). Default: shared when cwd is
+// inside an APC project, else global.
+function resolveWriteScope(flags) {
+  if (flags?.scope) {
+    const s = String(flags.scope).toLowerCase();
+    if (s === "all") {
+      throw new Error("--scope all is only valid for `list` and `check`");
+    }
+    if (!VALID_SCOPES.has(s)) {
+      throw new Error(`unknown --scope "${flags.scope}" (use shared|runtime|global)`);
+    }
+    return s;
+  }
+  return findApfRoot() ? "shared" : "global";
+}
+
+// Resolve --scope flag for list (read op). Default: 'all'.
+function resolveListScope(flags) {
+  if (!flags?.scope) return "all";
+  const s = String(flags.scope).toLowerCase();
+  if (!VALID_SCOPES.has(s)) {
+    throw new Error(`unknown --scope "${flags.scope}" (use shared|runtime|global|all)`);
+  }
+  return s;
+}
+
+// Source id (in entry.source) → user-facing scope
+function sourceToScope(source) {
+  if (source === "apc") return "shared";
+  if (source === "runtime") return "runtime";
+  if (source === "global") return "global";
+  return source; // claude, cursor, vscode, roo, gemini — surfaced verbatim
+}
 
 export async function cmdMcpList(args = {}) {
+  const scope = resolveListScope(args?.flags);
   const pid = await resolveProjectId(args?.flags?.project);
   const mcps = await http.get(`/projects/${pid}/mcps`);
-  if (mcps.length === 0) {
-    console.log("(no MCPs registered for this project)");
+  const filtered = scope === "all"
+    ? mcps
+    : mcps.filter((m) => sourceToScope(m.source) === scope);
+
+  if (filtered.length === 0) {
+    if (scope === "all") {
+      console.log("(no MCPs registered for this project)");
+    } else {
+      console.log(`(no MCPs in scope "${scope}" for this project)`);
+    }
     return;
   }
   console.log("NAME".padEnd(24) + " EN " + "SOURCE".padEnd(8) + " TRANSPORT  COMMAND/URL");
-  for (const m of mcps) {
+  for (const m of filtered) {
     const target = m.transport === "http"
       ? m.url
       : (m.command || "") + (m.args?.length ? " " + m.args.join(" ") : "");
@@ -42,23 +88,25 @@ export async function cmdMcpAdd(args) {
     }
   }
 
+  const scope = resolveWriteScope(args.flags);
   const pid = await resolveProjectId(args?.flags?.project);
-  const result = await http.post(`/projects/${pid}/mcps`, {
+  const result = await http.post(`/projects/${pid}/mcps?scope=${encodeURIComponent(scope)}`, {
     name,
     command,
     args: mcpArgs,
     env,
     enabled: true,
   });
-  console.log(`Added MCP "${result.name}"`);
+  console.log(`Added MCP "${result.name}" (scope: ${scope})`);
 }
 
 export async function cmdMcpRemove(args) {
   const name = args._[0];
   if (!name) throw new Error("apx mcp remove: missing <name>");
+  const scope = resolveWriteScope(args.flags);
   const pid = await resolveProjectId(args?.flags?.project);
-  await http.delete(`/projects/${pid}/mcps/${name}`);
-  console.log(`Removed MCP "${name}"`);
+  await http.delete(`/projects/${pid}/mcps/${name}?scope=${encodeURIComponent(scope)}`);
+  console.log(`Removed MCP "${name}" (scope: ${scope})`);
 }
 
 export async function cmdMcpEnable(args) {
@@ -75,7 +123,16 @@ async function toggleEnabled(args, enabled) {
   const all = await http.get(`/projects/${pid}/mcps`);
   const m = all.find((x) => x.name === name);
   if (!m) throw new Error(`MCP "${name}" not registered`);
-  await http.post(`/projects/${pid}/mcps`, {
+  // Write back to the scope it lives in so we don't accidentally shadow it.
+  const scope = args?.flags?.scope
+    ? resolveWriteScope(args.flags)
+    : sourceToScope(m.source);
+  if (!VALID_SCOPES.has(scope) || scope === "all") {
+    throw new Error(
+      `MCP "${name}" comes from foreign source "${m.source}" — toggle it in that IDE's config directly.`
+    );
+  }
+  await http.post(`/projects/${pid}/mcps?scope=${encodeURIComponent(scope)}`, {
     name: m.name,
     command: m.command,
     args: m.args,
@@ -117,7 +174,9 @@ export async function cmdMcpCheck(args = {}) {
 
   console.log("Source files:");
   for (const s of data.sources) {
-    console.log(`  ${s.present ? "✓" : "·"} ${s.id.padEnd(8)} ${s.file}`);
+    const marker = s.present ? "✓" : "·";
+    const scope = s.scope ? `(${s.scope})`.padEnd(10) : "".padEnd(10);
+    console.log(`  ${marker} ${s.id.padEnd(8)} ${scope} ${s.file}`);
   }
   console.log("");
 
@@ -137,7 +196,7 @@ export async function cmdMcpCheck(args = {}) {
   }
 
   if (data.conflicts && data.conflicts.length) {
-    console.log("\n⚠️  Conflicts (APC rule: first source wins):");
+    console.log("\n⚠️  Conflicts (priority: runtime > apc > IDE configs > global):");
     for (const c of data.conflicts) {
       console.log(`  ${c.name}: kept "${c.winner}", ignored "${c.loser}"`);
     }

package/src/{cli → interfaces/cli}/commands/memory.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { findApfRoot } from "../../core/parser.js";
-import { ensureAgentDir } from "../../core/scaffold.js";
+import { findApfRoot } from "../../../core/parser.js";
+import { ensureAgentDir } from "../../../core/scaffold.js";
 import { http } from "../http.js";
 
 function requireRoot() {

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

@@ -0,0 +1,136 @@
+import { readConfig, writeConfig } from "../../../core/config.js";
+import {
+  probeAllProviders,
+  resolveActiveModel,
+  fallbackOrder,
+  modelForProvider,
+  DEFAULT_FALLBACK_ORDER,
+} from "../../../core/agent/model-router.js";
+
+function parseValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function setNested(obj, keyPath, value) {
+  const parts = keyPath.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i];
+    if (!cur[p] || typeof cur[p] !== "object") cur[p] = {};
+    cur = cur[p];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+function ensureFallback(cfg) {
+  cfg.super_agent = cfg.super_agent || {};
+  cfg.super_agent.model_fallback = cfg.super_agent.model_fallback || {};
+  if (!Array.isArray(cfg.super_agent.model_fallback.order) || !cfg.super_agent.model_fallback.order.length) {
+    cfg.super_agent.model_fallback.order = [...DEFAULT_FALLBACK_ORDER];
+  }
+  cfg.super_agent.model_fallback.models = cfg.super_agent.model_fallback.models || {};
+  cfg.engines = cfg.engines || {};
+  for (const p of ["groq", "openrouter"]) {
+    cfg.engines[p] = cfg.engines[p] || {};
+  }
+  return cfg;
+}
+
+export async function cmdModel(args = {}) {
+  const sub = args._[0] || "status";
+  const cfg = ensureFallback(readConfig());
+
+  if (sub === "status" || sub === "show") {
+    const probes = await probeAllProviders(cfg, cfg.super_agent.model_fallback.health_timeout_ms);
+    let active = null;
+    try {
+      active = await resolveActiveModel(cfg);
+    } catch {
+      /* no model */
+    }
+
+    console.log("Model router");
+    console.log(`  primary:   ${cfg.super_agent.model || "(not set)"}`);
+    console.log(`  fallback:  ${cfg.super_agent.model_fallback.enabled !== false ? "on" : "off"}`);
+    console.log(`  order:     ${fallbackOrder(cfg).join(" → ")}`);
+    if (active) {
+      console.log(`  active:    ${active.modelId}${active.fromFallback ? " (fallback)" : ""}`);
+    }
+    console.log("");
+    for (const p of probes) {
+      const key = cfg.engines?.[p.provider]?.api_key ? "key:config" : "(no key)";
+      const mark = p.ok ? "✓" : "✗";
+      console.log(`  ${mark} ${p.provider.padEnd(12)} ${String(p.model).slice(0, 40).padEnd(42)} ${p.ok ? "up" : p.reason || "down"}  ${key}`);
+    }
+    console.log("");
+    console.log("Keys → ~/.apx/config.json engines.{groq,openrouter}.api_key");
+    console.log("Or env: GROQ_API_KEY, OPENROUTER_API_KEY");
+    return;
+  }
+
+  if (sub === "order" || sub === "set-order") {
+    const providers = args._.slice(1).map(String).map((s) => s.toLowerCase());
+    if (!providers.length) {
+      throw new Error(`usage: apx model order ${DEFAULT_FALLBACK_ORDER.join(" ")}`);
+    }
+    cfg.super_agent.model_fallback.order = providers;
+    writeConfig(cfg);
+    console.log(`fallback order: ${providers.join(" → ")}`);
+    return;
+  }
+
+  if (sub === "key" || sub === "set-key") {
+    const provider = String(args._[1] || "").toLowerCase();
+    const key = args._.slice(2).join(" ").trim();
+    if (!provider || !key) {
+      throw new Error("usage: apx model key <groq|openrouter|openai> <api-key>");
+    }
+    if (!cfg.engines[provider]) cfg.engines[provider] = {};
+    cfg.engines[provider].api_key = key;
+    writeConfig(cfg);
+    console.log(`engines.${provider}.api_key set (${key.slice(0, 6)}…)`);
+    console.log("Run: apx daemon reload");
+    return;
+  }
+
+  if (sub === "set") {
+    const provider = String(args._[1] || "").toLowerCase();
+    const modelId = args._.slice(2).join(" ").trim();
+    if (!provider || !modelId) {
+      throw new Error("usage: apx model set <provider> <provider:model-id>");
+    }
+    cfg.super_agent.model_fallback.models[provider] = modelId;
+    writeConfig(cfg);
+    console.log(`model_fallback.models.${provider} = ${modelId}`);
+    return;
+  }
+
+  if (sub === "test") {
+    const routing = await resolveActiveModel(cfg);
+    console.log(`resolved: ${routing.modelId} (${routing.provider})`);
+    if (routing.fromFallback) console.log("(via fallback — primary provider down or skipped)");
+    return;
+  }
+
+  if (sub === "enable") {
+    cfg.super_agent.model_fallback.enabled = true;
+    writeConfig(cfg);
+    console.log("model fallback: enabled");
+    return;
+  }
+
+  if (sub === "disable") {
+    cfg.super_agent.model_fallback.enabled = false;
+    writeConfig(cfg);
+    console.log("model fallback: disabled");
+    return;
+  }
+
+  throw new Error(`unknown model subcommand: ${sub}. Try: status | order | key | set | test | enable | disable`);
+}
+
+export { modelForProvider, fallbackOrder };

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

@@ -0,0 +1,170 @@
+// `apx pair` — QR-based pairing for companion clients (Deck app, etc.).
+//
+// Calls the daemon's /pair/init endpoint (localhost-only on the daemon
+// side), renders the QR in the terminal, then polls /pair/status until
+// the device confirms. No state lives in the CLI — the daemon owns
+// pairing_id lifetime and the issued client token.
+
+import os from "node:os";
+import qrcode from "qrcode-terminal";
+import { http } from "../http.js";
+
+const c = {
+  reset:  "\x1b[0m",
+  bold:   "\x1b[1m",
+  dim:    "\x1b[2m",
+  green:  "\x1b[32m",
+  red:    "\x1b[31m",
+  cyan:   "\x1b[36m",
+  gray:   "\x1b[90m",
+};
+const fmt = {
+  bold:  (s) => `${c.bold}${s}${c.reset}`,
+  dim:   (s) => `${c.dim}${s}${c.reset}`,
+  green: (s) => `${c.green}${s}${c.reset}`,
+  red:   (s) => `${c.red}${s}${c.reset}`,
+  cyan:  (s) => `${c.cyan}${s}${c.reset}`,
+  gray:  (s) => `${c.gray}${s}${c.reset}`,
+};
+
+// Pick a LAN IP the phone can reach. The daemon binds to 127.0.0.1 by
+// default, which a device on the same WiFi cannot hit — but in our
+// dev setup we tunnel via `adb reverse tcp:7430 tcp:7430`, so the QR
+// pointing at 127.0.0.1 works through the USB bridge. For pure WiFi
+// pairing, the user should bind APX_HOST=0.0.0.0 and we'll emit the
+// LAN IP here instead.
+function pickHostForQr({ host, port }) {
+  if (host && host !== "0.0.0.0" && host !== "::" && host !== "127.0.0.1") {
+    return host;
+  }
+  // When daemon binds to wildcard, prefer the first non-internal IPv4.
+  if (host === "0.0.0.0" || host === "::") {
+    const ifaces = os.networkInterfaces();
+    for (const list of Object.values(ifaces)) {
+      for (const i of list || []) {
+        if (i.family === "IPv4" && !i.internal) return i.address;
+      }
+    }
+  }
+  // Fallback: loopback (works over `adb reverse`).
+  return host || "127.0.0.1";
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// `apx pair`  → companion devices via the APX Deck app (QR = JSON payload).
+export async function cmdPair(args = {}) {
+  return runPairing(args, "deck");
+}
+
+// `apx pair web` → a browser on the LAN. QR = a plain URL (`<base>/#pair=<pid>`)
+// so the phone's native camera opens the web already authenticating. Also
+// prints the link in plain text so you can share it (Telegram, chat) and the
+// recipient just taps it.
+export async function cmdPairWeb(args = {}) {
+  return runPairing(args, "web");
+}
+
+async function runPairing(args, channel) {
+  void (args.flags?.label || args._?.[0] || ""); // label is chosen by the device on confirm
+
+  // 1. Ask daemon for a pairing nonce.
+  let init;
+  try {
+    init = await http.post("/pair/init", {});
+  } catch (e) {
+    console.error(fmt.red(`pair init failed: ${e.message}`));
+    process.exit(1);
+  }
+
+  const ttlSec = Math.round((init.ttl_ms || 90_000) / 1000);
+  const qrHost = pickHostForQr({ host: init.daemon?.host, port: init.daemon?.port });
+  const qrPort = init.daemon?.port || 7430;
+  const baseUrl = `http://${qrHost}:${qrPort}`;
+  const webLink = `${baseUrl}/#pair=${init.pairing_id}`;
+
+  // 2. QR payload differs per channel — no mixing.
+  //    deck: JSON {v,url,pid,fp} that the Deck app parses.
+  //    web : the scan-to-login URL the browser understands.
+  const qrData = channel === "web"
+    ? webLink
+    : JSON.stringify({ v: 1, url: baseUrl, pid: init.pairing_id, fp: init.fingerprint });
+  const title = channel === "web" ? "APX pairing (web)" : "APX pairing (deck)";
+
+  console.log("");
+  console.log(`  ${fmt.bold(title)}  ${fmt.gray("·")}  ${fmt.dim(`expires in ${ttlSec}s`)}`);
+  console.log("");
+  qrcode.generate(qrData, { small: true }, (qr) => {
+    console.log(qr);
+  });
+
+  if (channel === "web") {
+    console.log(`  ${fmt.gray("scan with the phone camera — opens the web already linked")}`);
+    console.log(`  ${fmt.gray("link:")} ${fmt.cyan(webLink)}`);
+    console.log(`  ${fmt.gray("code:")} ${fmt.bold(init.pairing_id)}  ${fmt.dim("(or paste it in the web pairing screen)")}`);
+  } else {
+    console.log(`  ${fmt.gray("scan with APX Deck app on the device")}`);
+    console.log(`  ${fmt.gray("url:")} ${fmt.cyan(baseUrl)}   ${fmt.gray("fp:")} ${fmt.dim(init.fingerprint)}`);
+  }
+  console.log("");
+
+  // 3. Poll /pair/status until confirmed or expired.
+  const reRun = channel === "web" ? "apx pair web" : "apx pair";
+  const deadline = Date.now() + (init.ttl_ms || 90_000) + 5_000;
+  while (Date.now() < deadline) {
+    await sleep(1500);
+    try {
+      const s = await http.get(`/pair/status/${init.pairing_id}`);
+      if (s.status === "confirmed") {
+        console.log(`  ${fmt.green("●")} ${fmt.bold("paired")} ${fmt.gray("·")} ${s.device_label || ""}`);
+        console.log(`    ${fmt.gray("client_id:")} ${s.client_id}`);
+        console.log(`    ${fmt.dim("token stored on the device; CLI keeps using ~/.apx/daemon.token")}`);
+        console.log("");
+        return;
+      }
+      if (s.status === "expired" || s.status === "unknown") {
+        console.log(`  ${fmt.red("○")} pairing expired — re-run ${fmt.bold(reRun)}`);
+        process.exit(1);
+      }
+    } catch (e) {
+      // Transient errors are fine; keep polling.
+    }
+  }
+  console.log(`  ${fmt.red("○")} pairing expired — re-run ${fmt.bold(reRun)}`);
+  process.exit(1);
+}
+
+export async function cmdPairList() {
+  const { clients } = await http.get("/pair/list");
+  if (!clients.length) {
+    console.log(`\n  ${fmt.dim("no paired devices")}\n`);
+    return;
+  }
+  console.log("");
+  console.log(`  ${fmt.bold("paired devices")}  ${fmt.gray(`(${clients.length})`)}`);
+  console.log("");
+  for (const c of clients) {
+    const seen = c.last_seen ? fmt.dim(`last seen ${c.last_seen}`) : fmt.dim("never seen");
+    console.log(`  ${fmt.cyan(c.id.slice(0, 8))}  ${c.label.padEnd(20)}  ${fmt.gray(`…${c.token_suffix}`)}  ${seen}`);
+  }
+  console.log("");
+}
+
+export async function cmdPairRevoke(args = {}) {
+  const id = args._?.[0];
+  if (!id) {
+    console.error(fmt.red("usage: apx pair revoke <client_id_prefix>"));
+    process.exit(1);
+  }
+  // Allow short prefix: resolve via /pair/list.
+  const { clients } = await http.get("/pair/list");
+  const match = clients.find((c) => c.id === id || c.id.startsWith(id));
+  if (!match) {
+    console.error(fmt.red(`no paired device matches "${id}"`));
+    process.exit(1);
+  }
+  await http.delete(`/pair/revoke/${match.id}`);
+  console.log(`  ${fmt.green("●")} revoked ${match.label} ${fmt.gray(`(${match.id.slice(0, 8)})`)}`);
+}