@agentprojectcontext/apx 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.6.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/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);
+  },
+};

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

@@ -0,0 +1,107 @@
+import { readAgents } from "../../../core/parser.js";
+import { getRuntime, RUNTIME_IDS } from "../../runtimes/index.js";
+import { buildAgentSystem, confirmedProperty, resolveProject } from "../helpers.js";
+
+function resolveProjectForAgent(projects, project, slug) {
+  if (project) return resolveProject(projects, project);
+
+  const defaultProject = projects.get(0);
+  if (defaultProject && readAgents(defaultProject.path).find((a) => a.slug === slug)) {
+    return defaultProject;
+  }
+
+  const matches = [];
+  for (const entry of projects.list()) {
+    const p = projects.get(entry.id);
+    if (readAgents(p.path).find((a) => a.slug === slug)) matches.push(p);
+  }
+  if (matches.length === 1) return matches[0];
+  if (defaultProject) return defaultProject;
+  return resolveProject(projects, project);
+}
+
+export default {
+  name: "call_runtime",
+  schema: {
+    type: "function",
+    function: {
+      name: "call_runtime",
+      description: "Spawn an external CLI runtime (Claude Code, Codex, OpenCode, Aider) impersonating an APC agent.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          agent: { type: "string", description: "APC agent slug from AGENTS.md, not runtime name" },
+          runtime: {
+            type: "string",
+            enum: ["claude-code", "codex", "opencode", "aider"],
+            description: "external CLI runtime",
+          },
+          prompt: { type: "string" },
+          timeout_s: { type: "integer", description: "seconds before SIGTERM; default 300" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact runtime command"),
+        },
+        required: ["agent", "runtime", "prompt"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async ({ project, agent: slug, runtime, prompt, timeout_s = 300, confirmed = false }) => {
+    requirePermission("call_runtime", { dangerous: true, confirmed });
+
+    const p = resolveProjectForAgent(projects, project, slug);
+    const agent = readAgents(p.path).find((a) => a.slug === slug);
+    if (!agent) {
+      const directory = projects.list().map((entry) => ({
+        project: entry.name,
+        kind: entry.id === 0 ? "default" : "project",
+        path: entry.path,
+        agents: readAgents(projects.get(entry.id).path).map((a) => a.slug),
+      }));
+      return { error: `agent "${slug}" not found in selected project`, directory };
+    }
+
+    let rt;
+    try {
+      rt = getRuntime(runtime);
+    } catch (e) {
+      return { error: `${e.message}. Available runtimes: ${RUNTIME_IDS.join(", ")}` };
+    }
+
+    const r = await rt.run({
+      system: buildAgentSystem(p, agent),
+      prompt,
+      cwd: p.path,
+      timeoutMs: timeout_s * 1000,
+    });
+
+    p.logMessage({
+      agent_slug: slug,
+      channel: "runtime",
+      direction: "in",
+      author: "user",
+      body: prompt,
+      meta: { runtime, invoked_by: "super_agent_tool" },
+    });
+    p.logMessage({
+      agent_slug: slug,
+      channel: "runtime",
+      direction: "out",
+      author: slug,
+      body: r.output || "",
+      meta: {
+        runtime,
+        exit_code: r.exitCode,
+        external_session_path: r.externalSessionPath || null,
+        invoked_by: "super_agent_tool",
+      },
+    });
+
+    return {
+      runtime,
+      exit_code: r.exitCode,
+      output: (r.output || "").slice(0, 4000),
+      truncated: (r.output || "").length > 4000,
+      external_session_path: r.externalSessionPath || null,
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/edit-file.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import { confirmedProperty, resolveProject, safePathJoin } from "../helpers.js";
+
+export default {
+  name: "edit_file",
+  schema: {
+    type: "function",
+    function: {
+      name: "edit_file",
+      description: "Edit a UTF-8 text file inside default or a project by replacing one exact string with another.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          path: { type: "string", description: "relative path inside the project" },
+          search: { type: "string", description: "exact text to replace" },
+          replace: { type: "string", description: "replacement text" },
+          all: { type: "boolean", description: "replace all matches; default false replaces one match" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact file edit"),
+        },
+        required: ["path", "search", "replace"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => ({ project, path, search, replace, all = false, confirmed = false }) => {
+    requirePermission("edit_file", { dangerous: true, confirmed });
+    if (!path) throw new Error("edit_file: path required");
+    if (!search) throw new Error("edit_file: search required");
+
+    const p = resolveProject(projects, project);
+    const target = safePathJoin(p.path, path);
+    if (!fs.existsSync(target)) throw new Error(`file not found: ${path}`);
+    const before = fs.readFileSync(target, "utf8");
+    const matches = before.split(search).length - 1;
+    if (matches === 0) throw new Error("search text not found");
+    if (!all && matches > 1) {
+      throw new Error(`search text appears ${matches} times; set all=true or use a more specific search`);
+    }
+
+    const after = all ? before.split(search).join(replace) : before.replace(search, replace);
+    fs.writeFileSync(target, after, "utf8");
+    return { ok: true, path: target, replacements: all ? matches : 1 };
+  },
+};

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

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readVaultAgents, VAULT_DIR } from "../../../core/parser.js";
+import { addImportedAgent, ensureAgentDir, regenerateAgentsMd } from "../../../core/scaffold.js";
+import { confirmedProperty, projectMeta, resolveProject } from "../helpers.js";
+
+export default {
+  name: "import_agent",
+  schema: {
+    type: "function",
+    function: {
+      name: "import_agent",
+      description: "Import an agent template from the APX vault into default or a registered project.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id/name/path; omit or use 'default' for ~/.apx/projects/default" },
+          agent: { type: "string", description: "agent slug from list_vault_agents" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact import"),
+        },
+        required: ["agent"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => ({ project, agent: slug, confirmed = false }) => {
+    requirePermission("import_agent", { dangerous: true, confirmed });
+    if (!slug) throw new Error("import_agent: agent required");
+
+    const vaultPath = path.join(VAULT_DIR, `${slug}.md`);
+    if (!fs.existsSync(vaultPath)) {
+      const available = readVaultAgents().map((a) => a.slug).join(", ") || "(none)";
+      throw new Error(`agent "${slug}" not found in vault. Available: ${available}`);
+    }
+
+    const p = resolveProject(projects, project || "default");
+    addImportedAgent(p.path, slug);
+    ensureAgentDir(p.path, slug);
+    regenerateAgentsMd(p.path);
+    projects.rebuild(p.id);
+
+    return {
+      ok: true,
+      agent: slug,
+      project: projectMeta(projects, p),
+      source: vaultPath,
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/list-agents.js

@@ -0,0 +1,36 @@
+import { readAgents } from "../../../core/parser.js";
+import { agentRow, resolveProject } from "../helpers.js";
+
+export default {
+  name: "list_agents",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_agents",
+      description: "List agents. If project is omitted, returns all agents grouped by project, including default.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id, name, path, or substring; omit to list all projects" },
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => ({ project } = {}) => {
+    const p = resolveProject(projects, project, { allowMulti: true });
+    if (p) return readAgents(p.path).map(agentRow);
+    return projects.list().map((entry) => {
+      const e = projects.get(entry.id);
+      return {
+        project: {
+          id: entry.id,
+          kind: entry.id === 0 ? "default" : "project",
+          name: entry.name,
+          path: entry.path,
+        },
+        agents: readAgents(e.path).map(agentRow),
+      };
+    });
+  },
+};