@agentprojectcontext/apx 1.6.0 → 1.8.0

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

@@ -0,0 +1,120 @@
+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 = {}, { implicitConfirmation = false } = {}) {
+  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 } = {}) {
+    const ok = confirmed || implicitConfirmation;
+    if (permissionMode === "total") return;
+    if (permissionMode === "permiso" && !allowedTools.has(tool) && !ok) {
+      throw new Error(`requires_confirmation: permission_mode=permiso blocks ${tool}`);
+    }
+    if (permissionMode === "automatico" && dangerous && !ok) {
+      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,56 @@
+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 setPermissionMode from "./tools/set-permission-mode.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,
+  setPermissionMode,
+];
+
+export const TOOL_SCHEMAS = TOOLS.map((tool) => tool.schema);
+
+export function makeToolHandlers(ctx) {
+  const toolCtx = {
+    ...ctx,
+    requirePermission: createPermissionGuard(ctx.globalConfig || {}, {
+      implicitConfirmation: !!ctx.implicitConfirmation,
+    }),
+  };
+  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),
+      };
+    });
+  },
+};

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

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveProject, safePathJoin } from "../helpers.js";
+
+export default {
+  name: "list_files",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_files",
+      description: "List files and subdirectories inside default or a project.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          path: { type: "string", description: "relative path inside the project; default '.'" },
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => ({ project, path: sub = "." } = {}) => {
+    const p = resolveProject(projects, project);
+    const target = safePathJoin(p.path, sub);
+    if (!fs.existsSync(target)) return { error: `path not found: ${sub}` };
+    if (!fs.statSync(target).isDirectory()) return { error: `${sub} is not a directory` };
+
+    return fs.readdirSync(target).map((name) => {
+      const full = path.join(target, name);
+      const stat = fs.statSync(full);
+      return {
+        name,
+        type: stat.isDirectory() ? "dir" : "file",
+        size: stat.size,
+      };
+    });
+  },
+};

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

@@ -0,0 +1,48 @@
+import { resolveProject } from "../helpers.js";
+
+export default {
+  name: "list_mcps",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_mcps",
+      description: "List MCPs. If project is omitted, returns all MCPs grouped by project, including default.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "project id/name/path; omit to list all projects" },
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: ({ projects, registries }) => ({ project } = {}) => {
+    const row = (m) => ({
+      name: m.name,
+      source: m.source,
+      transport: m.transport,
+      enabled: !!m.enabled,
+      command: m.command,
+      url: m.url,
+    });
+
+    const p = resolveProject(projects, project, { allowMulti: true });
+    if (p) {
+      if (!registries) throw new Error("MCP registry unavailable");
+      return registries.for(p).list().map(row);
+    }
+
+    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,
+        },
+        mcps: registries ? registries.for(e).list().map(row) : [],
+      };
+    });
+  },
+};

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

@@ -0,0 +1,20 @@
+export default {
+  name: "list_projects",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_projects",
+      description: "List the APX default project and every registered APC project. Returns id, kind, name, path, and agent count.",
+      parameters: { type: "object", properties: {}, required: [] },
+    },
+  },
+  makeHandler: ({ projects }) => () => {
+    return projects.list().map((p) => ({
+      id: p.id,
+      kind: p.id === 0 ? "default" : "project",
+      name: p.name,
+      path: p.path,
+      agents: p.agents,
+    }));
+  },
+};

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

@@ -0,0 +1,18 @@
+import { readVaultAgents, VAULT_DIR } from "../../../core/parser.js";
+import { agentRow } from "../helpers.js";
+
+export default {
+  name: "list_vault_agents",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_vault_agents",
+      description: "List reusable agent templates from the APX vault (~/.apx/agents). These can be imported into default or a project.",
+      parameters: { type: "object", properties: {}, required: [] },
+    },
+  },
+  makeHandler: () => () => ({
+    vault: VAULT_DIR,
+    agents: readVaultAgents().map(agentRow),
+  }),
+};