@agentprojectcontext/apx 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/src/core/config.js

@@ -46,6 +46,8 @@ const DEFAULT_CONFIG = {
     name: "apx",
     model: "",                          // e.g. "ollama:llama3.2:3b"
     system: "",                         // optional override; defaults baked into super-agent.js
+    permission_mode: "automatico",       // total | automatico | permiso
+    allowed_tools: [],                   // used by permission_mode="permiso"
   },
   engines: {
     anthropic: { api_key: "" },

package/src/core/mascot.js

@@ -4,9 +4,7 @@
 const R = "\x1b[0m";
 const B = "\x1b[1m";
 const W = "\x1b[97m";       // bright white
-const K = "\x1b[30m";       // black
 const BK = "\x1b[40m";      // bg black
-const BW = "\x1b[47m";      // bg white
 const CY = "\x1b[36m";
 const YE = "\x1b[33m";
 const GR = "\x1b[32m";
@@ -34,10 +32,10 @@ const MOODS = {
   wave: {
     color: CY,
     lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}     👋`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
-      `  ${BK}${W} █  ◕   ◕  █ ${R}`,
-      `  ${BK}${W} █   ╰▽╯   █ ${R}`,
+      `   ${BK}${W}  ▄███████▄  ${R}   ${DI}/)${R}`,
+      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}  ${DI}//${R}`,
+      `  ${BK}${W} █  ◕   ◕  █ ${R} ${DI}//${R}`,
+      `  ${BK}${W} █   ╰▽╯   █ ${R}${DI}/${R}`,
       `   ${BK}${W}  ▀███████▀  ${R}`,
       `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
     ],
@@ -76,7 +74,7 @@ const MOODS = {
   excited: {
     color: BL,
     lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}  ${BL}⬆${R}`,
+      `   ${BK}${W}  ▄███████▄  ${R}  ${BL}↑${R}`,
       `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
       `  ${BK}${W} █  ★   ★  █ ${R}`,
       `  ${BK}${W} █   ╰◡╯   █ ${R}`,

package/src/daemon/api.js

@@ -1,6 +1,7 @@
 // Express REST API for APX. See APC docs reference/apx-daemon.
 import fs from "node:fs";
 import path from "node:path";
+import { execFile } from "node:child_process";
 import express from "express";
 import { readApfMcps, writeApfMcps, SOURCES } from "./mcp-sources.js";
 import { callEngine, ENGINE_IDS } from "./engines/index.js";
@@ -887,6 +888,167 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     res.json({ ok: true, project_only: cfg });
   });
 
+  // ---- Run (bash execution) -----------------------------------------
+  // POST /run  { cmd, cwd?, project?, timeout_ms? }
+  // Executes a shell command and returns stdout + stderr.
+  // `cwd` defaults to the project path (by id or first registered), or process.cwd().
+  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" });
+
+    // Resolve working directory
+    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,
+      });
+    });
+  });
+
+  // ---- Top-level memory shortcuts -----------------------------------
+  // GET  /memory?project=<id>          → reads default agent memory.md
+  // POST /memory?project=<id>  { body } → writes it
+  //
+  // Targets the *first non-default agent* of the resolved project,
+  // or falls back to a bare memory.md in .apc/ root.
+
+  function resolveTopProject(query) {
+    const ref = query?.project;
+    if (ref !== undefined && ref !== null) {
+      const all = projects.list();
+      const r = String(ref);
+      return projects.get(all.find((p) => String(p.id) === r || p.path === path.resolve(r))?.id);
+    }
+    const all = projects.list().filter((p) => p.id !== 0);
+    return all.length ? projects.get(all[0].id) : projects.get(0);
+  }
+
+  function resolveMemoryPath(p) {
+    const agentsDir = path.join(p.path, ".apc", "agents");
+    if (fs.existsSync(agentsDir)) {
+      const slugs = fs.readdirSync(agentsDir).filter((s) => {
+        const mp = path.join(agentsDir, s, "memory.md");
+        return fs.statSync(path.join(agentsDir, s)).isDirectory();
+      });
+      if (slugs.length) return path.join(agentsDir, slugs[0], "memory.md");
+    }
+    return path.join(p.path, ".apc", "memory.md");
+  }
+
+  app.get("/memory", (req, res) => {
+    const p = resolveTopProject(req.query);
+    if (!p) return res.status(404).json({ error: "no project registered" });
+    const memPath = resolveMemoryPath(p);
+    const body = fs.existsSync(memPath) ? fs.readFileSync(memPath, "utf8") : "";
+    res.json({ project_id: p.id, path: memPath, body });
+  });
+
+  app.post("/memory", (req, res) => {
+    const p = resolveTopProject(req.query);
+    if (!p) return res.status(404).json({ error: "no project registered" });
+    const { body } = req.body || {};
+    if (typeof body !== "string") return res.status(400).json({ error: "body must be string" });
+    const memPath = resolveMemoryPath(p);
+    fs.mkdirSync(path.dirname(memPath), { recursive: true });
+    fs.writeFileSync(memPath, body);
+    try { projects.rebuild(p.id); } catch {}
+    res.json({ ok: true, path: memPath, bytes: Buffer.byteLength(body, "utf8") });
+  });
+
+  // ---- Top-level file shortcuts -------------------------------------
+  // GET  /files?path=<rel>&project=<id>          → read file contents
+  // POST /files?project=<id>  { path, content }  → write file
+
+  app.get("/files", (req, res) => {
+    const p = resolveTopProject(req.query);
+    if (!p) return res.status(404).json({ error: "no project registered" });
+    const rel = req.query.path;
+    if (!rel) {
+      // List top-level files of the project
+      try {
+        const entries = fs.readdirSync(p.path).map((name) => {
+          const full = path.join(p.path, name);
+          const stat = fs.statSync(full);
+          return { name, type: stat.isDirectory() ? "dir" : "file", size: stat.isDirectory() ? null : stat.size };
+        });
+        return res.json({ project_id: p.id, cwd: p.path, entries });
+      } catch (e) {
+        return res.status(500).json({ error: e.message });
+      }
+    }
+    const abs = path.resolve(p.path, rel);
+    if (!abs.startsWith(path.resolve(p.path))) return res.status(403).json({ error: "path escapes project root" });
+    if (!fs.existsSync(abs)) return res.status(404).json({ error: "not found" });
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) {
+      const entries = fs.readdirSync(abs).map((name) => {
+        const s = fs.statSync(path.join(abs, name));
+        return { name, type: s.isDirectory() ? "dir" : "file", size: s.isDirectory() ? null : s.size };
+      });
+      return res.json({ project_id: p.id, path: rel, type: "dir", entries });
+    }
+    const content = fs.readFileSync(abs, "utf8");
+    res.json({ project_id: p.id, path: rel, type: "file", size: stat.size, content });
+  });
+
+  app.post("/files", (req, res) => {
+    const p = resolveTopProject(req.query);
+    if (!p) return res.status(404).json({ error: "no project registered" });
+    const { path: rel, content } = req.body || {};
+    if (!rel) return res.status(400).json({ error: "path required" });
+    if (typeof content !== "string") return res.status(400).json({ error: "content must be string" });
+    const abs = path.resolve(p.path, rel);
+    if (!abs.startsWith(path.resolve(p.path))) return res.status(403).json({ error: "path escapes project root" });
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    res.json({ ok: true, path: rel, bytes: Buffer.byteLength(content, "utf8") });
+  });
+
+  // ---- Top-level MCP shortcuts --------------------------------------
+  // GET  /mcp?project=<id>                        → list MCPs
+  // POST /mcp/run  { project?, name, tool, params } → call MCP tool
+
+  app.get("/mcp", (req, res) => {
+    const p = resolveTopProject(req.query);
+    if (!p) return res.status(404).json({ error: "no project registered" });
+    res.json(registries.for(p).list());
+  });
+
+  app.post("/mcp/run", async (req, res) => {
+    const { project: projectRef, name, tool, params } = req.body || {};
+    if (!name) return res.status(400).json({ error: "name required" });
+    if (!tool) return res.status(400).json({ error: "tool required" });
+    const p = resolveTopProject({ project: projectRef });
+    if (!p) return res.status(404).json({ error: "no project registered" });
+    try {
+      const result = await registries.for(p).call(name, tool, params);
+      res.json({ ok: true, result });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
   // ---- Admin --------------------------------------------------------
   app.post("/admin/shutdown", (_req, res) => {
     res.json({ ok: true });

package/src/daemon/index.js

@@ -44,6 +44,32 @@ function writePid() {
   } catch {}
 }
 
+function pidIsAlive(pid) {
+  if (!pid || pid === process.pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function claimSingleton() {
+  try {
+    if (fs.existsSync(PID_PATH)) {
+      const pid = parseInt(fs.readFileSync(PID_PATH, "utf8"), 10);
+      if (pidIsAlive(pid)) {
+        log(`fatal: apx-daemon already running with pid ${pid}`);
+        process.exit(1);
+      }
+      fs.unlinkSync(PID_PATH);
+    }
+  } catch (e) {
+    log(`fatal: cannot claim daemon pid file: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 function clearPid() {
   try {
     if (fs.existsSync(PID_PATH)) fs.unlinkSync(PID_PATH);
@@ -71,6 +97,7 @@ class RegistryCache {
 
 async function main() {
   ensureHome();
+  claimSingleton();
 
   const cfg = readConfig();
   const host = effectiveHost(cfg);
@@ -95,7 +122,6 @@ async function main() {
 
   const plugins = new PluginManager({ projects, config: cfg, log, registries });
   plugins.initAll();
-  plugins.startAll();
 
   const scheduler = new RoutineScheduler({
     projects,
@@ -103,7 +129,6 @@ async function main() {
     globalConfig: cfg,
     log,
   });
-  scheduler.start();
 
   const startedAt = Date.now();
   const app = buildApi({
@@ -130,10 +155,20 @@ async function main() {
     writePid();
     log(`apx-daemon ${PKG.version} listening on http://${host}:${port}`);
     log(`projects: ${projects.list().length} | plugins: ${Object.keys(plugins.status()).join(", ") || "(none)"}`);
+    plugins.startAll();
+    scheduler.start();
     // Fire wake-up message after a short delay so plugins (Telegram) are ready
     setTimeout(() => triggerWakeup(cfg, log), 3000);
   });
 
+  server.on("error", (e) => {
+    log(`fatal: listen ${host}:${port} failed: ${e.message}`);
+    plugins.stopAll();
+    registries.shutdown();
+    clearPid();
+    process.exit(1);
+  });
+
   function shutdown(signal) {
     log(`received ${signal}, shutting down...`);
     scheduler.stop();

package/src/daemon/super-agent-tools/helpers.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function projectMeta(projects, entry) {
+  const meta = projects.list().find((p) => p.id === entry.id);
+  return {
+    id: entry.id,
+    name: meta?.name || path.basename(entry.path),
+    path: entry.path,
+  };
+}
+
+export function resolveProject(projects, target, { allowMulti = false } = {}) {
+  if (target === undefined || target === null || target === "") {
+    if (allowMulti) return null;
+    const defaultProject = projects.get(0);
+    if (defaultProject) return defaultProject;
+    const all = projects.list();
+    if (all.length === 1) return projects.get(all[0].id);
+    throw new Error(`multiple projects registered (${all.length}); specify project=<id|name|path>`);
+  }
+
+  const tgt = String(target);
+  if (tgt.toLowerCase() === "default") {
+    const defaultProject = projects.get(0);
+    if (!defaultProject) throw new Error("default project not available");
+    return defaultProject;
+  }
+
+  if (typeof target === "number" || /^\d+$/.test(tgt)) {
+    const entry = projects.get(parseInt(tgt, 10));
+    if (!entry) throw new Error(`project id ${target} not found`);
+    return entry;
+  }
+
+  const all = projects.list();
+  const byPath = all.find((p) => p.path === path.resolve(tgt));
+  if (byPath) return projects.get(byPath.id);
+
+  const byName = all.find((p) => p.name === tgt);
+  if (byName) return projects.get(byName.id);
+
+  const tgtLow = tgt.toLowerCase();
+  const fuzzy = all.filter(
+    (p) => p.name.toLowerCase().includes(tgtLow) || p.path.toLowerCase().includes(tgtLow)
+  );
+  if (fuzzy.length === 1) return projects.get(fuzzy[0].id);
+  if (fuzzy.length > 1) {
+    throw new Error(`project "${tgt}" is ambiguous; matches: ${fuzzy.map((p) => p.name).join(", ")}`);
+  }
+  throw new Error(`project "${tgt}" not found`);
+}
+
+export function safePathJoin(root, sub = ".") {
+  const target = path.resolve(root, sub || ".");
+  const rootResolved = path.resolve(root);
+  if (target !== rootResolved && !target.startsWith(rootResolved + path.sep)) {
+    throw new Error(`path "${sub}" escapes the project root`);
+  }
+  return target;
+}
+
+export function skillsFromFields(fields = {}) {
+  if (Array.isArray(fields.Skills)) return fields.Skills;
+  return (fields.Skills || "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+export function agentRow(agent) {
+  return {
+    slug: agent.slug,
+    role: agent.fields.Role || null,
+    model: agent.fields.Model || null,
+    language: agent.fields.Language || null,
+    description: agent.fields.Description || null,
+    skills: skillsFromFields(agent.fields),
+  };
+}
+
+export function buildAgentSystem(project, agent) {
+  const parts = [];
+  if (agent.fields.Description) parts.push(agent.fields.Description);
+  if (agent.fields.Role) parts.push(`Role: ${agent.fields.Role}`);
+  if (agent.fields.Language) parts.push(`Default language: ${agent.fields.Language}`);
+
+  const memPath = path.join(project.path, ".apc", "agents", agent.slug, "memory.md");
+  if (fs.existsSync(memPath)) parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
+
+  const apxSkill = path.join(project.path, ".apc", "skills", "apx.md");
+  if (fs.existsSync(apxSkill)) parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8"));
+
+  for (const skill of skillsFromFields(agent.fields)) {
+    const skillPath = path.join(project.path, ".apc", "skills", `${skill}.md`);
+    if (fs.existsSync(skillPath)) parts.push(`## Skill: ${skill}\n` + fs.readFileSync(skillPath, "utf8"));
+  }
+
+  return parts.join("\n\n");
+}
+
+export function createPermissionGuard(globalConfig = {}) {
+  const permissionMode = globalConfig.super_agent?.permission_mode || "automatico";
+  const allowedTools = new Set(globalConfig.super_agent?.allowed_tools || []);
+
+  return function requirePermission(tool, { dangerous = false, confirmed = false } = {}) {
+    if (permissionMode === "total") return;
+    if (permissionMode === "permiso" && !allowedTools.has(tool) && !confirmed) {
+      throw new Error(`requires_confirmation: permission_mode=permiso blocks ${tool}`);
+    }
+    if (permissionMode === "automatico" && dangerous && !confirmed) {
+      throw new Error(`requires_confirmation: permission_mode=automatico requires confirmation for ${tool}`);
+    }
+  };
+}
+
+export function confirmedProperty(description) {
+  return {
+    type: "boolean",
+    description: description || "true only after explicit user confirmation for this exact action",
+  };
+}

package/src/daemon/super-agent-tools/index.js

@@ -0,0 +1,52 @@
+import listProjects from "./tools/list-projects.js";
+import listAgents from "./tools/list-agents.js";
+import listVaultAgents from "./tools/list-vault-agents.js";
+import importAgent from "./tools/import-agent.js";
+import addProject from "./tools/add-project.js";
+import listMcps from "./tools/list-mcps.js";
+import readAgentMemory from "./tools/read-agent-memory.js";
+import listFiles from "./tools/list-files.js";
+import readFile from "./tools/read-file.js";
+import writeFile from "./tools/write-file.js";
+import editFile from "./tools/edit-file.js";
+import runShell from "./tools/run-shell.js";
+import tailMessages from "./tools/tail-messages.js";
+import searchMessages from "./tools/search-messages.js";
+import callAgent from "./tools/call-agent.js";
+import callMcp from "./tools/call-mcp.js";
+import callRuntime from "./tools/call-runtime.js";
+import sendTelegram from "./tools/send-telegram.js";
+import setIdentity from "./tools/set-identity.js";
+import { createPermissionGuard } from "./helpers.js";
+
+const TOOLS = [
+  listProjects,
+  listAgents,
+  listVaultAgents,
+  importAgent,
+  addProject,
+  listMcps,
+  readAgentMemory,
+  listFiles,
+  readFile,
+  writeFile,
+  editFile,
+  runShell,
+  tailMessages,
+  searchMessages,
+  callAgent,
+  callMcp,
+  callRuntime,
+  sendTelegram,
+  setIdentity,
+];
+
+export const TOOL_SCHEMAS = TOOLS.map((tool) => tool.schema);
+
+export function makeToolHandlers(ctx) {
+  const toolCtx = {
+    ...ctx,
+    requirePermission: createPermissionGuard(ctx.globalConfig || {}),
+  };
+  return Object.fromEntries(TOOLS.map((tool) => [tool.name, tool.makeHandler(toolCtx)]));
+}

package/src/daemon/super-agent-tools/tools/add-project.js

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { readConfig, addProject as addProjectInConfig } from "../../../core/config.js";
+import { confirmedProperty, projectMeta } from "../helpers.js";
+
+export default {
+  name: "add_project",
+  schema: {
+    type: "function",
+    function: {
+      name: "add_project",
+      description: "Register an existing APC project path with the APX daemon. The path must contain AGENTS.md and .apc/project.json.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "absolute or relative filesystem path to an APC project" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact project registration"),
+        },
+        required: ["path"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => ({ path: projectPath, confirmed = false }) => {
+    requirePermission("add_project", { dangerous: true, confirmed });
+    if (!projectPath) throw new Error("add_project: path required");
+
+    const cfg = readConfig();
+    const result = addProjectInConfig(cfg, projectPath);
+    const p = projects.register(result.project.path);
+    return {
+      ok: true,
+      added: result.added,
+      project: projectMeta(projects, p),
+      normalized_path: path.resolve(projectPath),
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/call-agent.js

@@ -0,0 +1,45 @@
+import { callEngine } from "../../engines/index.js";
+import { readAgents } from "../../../core/parser.js";
+import { buildAgentSystem, resolveProject } from "../helpers.js";
+
+export default {
+  name: "call_agent",
+  schema: {
+    type: "function",
+    function: {
+      name: "call_agent",
+      description: "Run a one-shot prompt through a project agent's configured LLM engine.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          agent: { type: "string", description: "agent slug" },
+          prompt: { type: "string" },
+        },
+        required: ["agent", "prompt"],
+      },
+    },
+  },
+  makeHandler: ({ projects, globalConfig }) => async ({ project, agent: slug, prompt }) => {
+    const p = resolveProject(projects, project);
+    const agent = readAgents(p.path).find((a) => a.slug === slug);
+    if (!agent) throw new Error(`agent ${slug} not found`);
+    if (!agent.fields.Model) throw new Error(`agent ${slug} has no model`);
+
+    const result = await callEngine({
+      modelId: agent.fields.Model,
+      system: buildAgentSystem(p, agent),
+      messages: [{ role: "user", content: prompt }],
+      config: p.config || globalConfig,
+    });
+    p.logMessage({
+      agent_slug: slug,
+      channel: "engine",
+      direction: "out",
+      author: slug,
+      body: result.text,
+      meta: { invoked_by: "super_agent_tool", usage: result.usage },
+    });
+    return { text: result.text, usage: result.usage };
+  },
+};

package/src/daemon/super-agent-tools/tools/call-mcp.js

@@ -0,0 +1,30 @@
+import { confirmedProperty, resolveProject } from "../helpers.js";
+
+export default {
+  name: "call_mcp",
+  schema: {
+    type: "function",
+    function: {
+      name: "call_mcp",
+      description: "Call a tool on an MCP server registered in default or a project. Args is a JSON object.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          mcp: { type: "string", description: "MCP server name" },
+          tool: { type: "string", description: "tool name on that MCP" },
+          args: { type: "object", description: "arguments object" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact MCP call"),
+        },
+        required: ["mcp", "tool"],
+      },
+    },
+  },
+  makeHandler: ({ projects, registries, requirePermission }) => async ({ project, mcp, tool, args = {}, confirmed = false }) => {
+    requirePermission("call_mcp", { dangerous: true, confirmed });
+    const p = resolveProject(projects, project);
+    if (!registries) throw new Error("MCP registry unavailable");
+    const registry = registries.for ? registries.for(p) : registries.ensure(p);
+    return registry.call(mcp, tool, args);
+  },
+};