@agentprojectcontext/apx 1.5.0 → 1.7.0

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),
+  }),
+};

package/src/daemon/super-agent-tools/tools/read-agent-memory.js

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveProject } from "../helpers.js";
+
+export default {
+  name: "read_agent_memory",
+  schema: {
+    type: "function",
+    function: {
+      name: "read_agent_memory",
+      description: "Read an agent memory.md file from default or a project.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          agent: { type: "string", description: "agent slug" },
+        },
+        required: ["agent"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => ({ project, agent }) => {
+    const p = resolveProject(projects, project);
+    const file = path.join(p.path, ".apc", "agents", agent, "memory.md");
+    if (!fs.existsSync(file)) return { error: `no memory.md for agent ${agent}` };
+    return { body: fs.readFileSync(file, "utf8") };
+  },
+};

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

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import { resolveProject, safePathJoin } from "../helpers.js";
+
+export default {
+  name: "read_file",
+  schema: {
+    type: "function",
+    function: {
+      name: "read_file",
+      description: "Read a text file inside default or a project. Returns first 64KB.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          path: { type: "string", description: "relative path inside the project" },
+        },
+        required: ["path"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => ({ project, path }) => {
+    if (!path) throw new Error("read_file: path required");
+    const p = resolveProject(projects, project);
+    const target = safePathJoin(p.path, path);
+    if (!fs.existsSync(target)) return { error: `file not found: ${path}` };
+    const stat = fs.statSync(target);
+    if (!stat.isFile()) return { error: `${path} is not a file` };
+    return {
+      content: fs.readFileSync(target, "utf8").slice(0, 64 * 1024),
+      truncated: stat.size > 64 * 1024,
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/run-shell.js

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import { confirmedProperty, resolveProject, safePathJoin } from "../helpers.js";
+
+function run(command, { cwd, timeoutMs }) {
+  return new Promise((resolve) => {
+    const child = spawn("sh", ["-lc", command], { cwd, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, timedOut, stdout, stderr });
+    });
+  });
+}
+
+export default {
+  name: "run_shell",
+  schema: {
+    type: "function",
+    function: {
+      name: "run_shell",
+      description: "Run a shell command in default or a project working directory. Direct command execution tool.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          cwd: { type: "string", description: "relative working directory inside the selected project; default '.'" },
+          command: { type: "string" },
+          timeout_s: { type: "integer", description: "seconds before SIGTERM; default 60" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact shell command"),
+        },
+        required: ["command"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async ({ project, cwd = ".", command, timeout_s = 60, confirmed = false }) => {
+    requirePermission("run_shell", { dangerous: true, confirmed });
+    if (!command) throw new Error("run_shell: command required");
+
+    const p = resolveProject(projects, project);
+    const workingDir = safePathJoin(p.path, cwd);
+    const result = await run(command, {
+      cwd: workingDir,
+      timeoutMs: Math.max(1, Math.min(timeout_s, 600)) * 1000,
+    });
+    return {
+      exit_code: result.code,
+      signal: result.signal,
+      timed_out: result.timedOut,
+      stdout: result.stdout.slice(0, 12000),
+      stderr: result.stderr.slice(0, 12000),
+      truncated: result.stdout.length > 12000 || result.stderr.length > 12000,
+      cwd: workingDir,
+    };
+  },
+};

package/src/daemon/super-agent-tools/tools/search-messages.js

@@ -0,0 +1,32 @@
+import { searchProjectMessages } from "../../../core/messages-store.js";
+import { resolveProject } from "../helpers.js";
+
+export default {
+  name: "search_messages",
+  schema: {
+    type: "function",
+    function: {
+      name: "search_messages",
+      description: "Full-text search inside project messages.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          query: { type: "string" },
+        },
+        required: ["query"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => ({ project, query }) => {
+    if (!query) throw new Error("search_messages: query required");
+    const p = resolveProject(projects, project);
+    return searchProjectMessages(p.path, query, 25).map((m) => ({
+      ts: m.ts,
+      channel: m.channel,
+      direction: m.direction,
+      author: m.author,
+      body: m.body,
+    }));
+  },
+};

package/src/daemon/super-agent-tools/tools/send-telegram.js

@@ -0,0 +1,30 @@
+import { confirmedProperty } from "../helpers.js";
+
+export default {
+  name: "send_telegram",
+  schema: {
+    type: "function",
+    function: {
+      name: "send_telegram",
+      description: "Send a Telegram message via the daemon's Telegram plugin.",
+      parameters: {
+        type: "object",
+        properties: {
+          channel: { type: "string", description: "telegram channel name; omit for default" },
+          chat_id: { type: "string", description: "destination chat id; omit to use channel default" },
+          text: { type: "string" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact outbound message"),
+        },
+        required: ["text"],
+      },
+    },
+  },
+  makeHandler: ({ plugins, requirePermission }) => async ({ channel, chat_id, text, confirmed = false }) => {
+    requirePermission("send_telegram", { dangerous: true, confirmed });
+    if (!plugins) throw new Error("plugins unavailable");
+    const telegram = plugins.get("telegram");
+    if (!telegram) throw new Error("telegram plugin not loaded");
+    const result = await telegram.send({ channel, chat_id, text, author: "apx" });
+    return { ok: true, message_id: result.message_id };
+  },
+};

package/src/daemon/super-agent-tools/tools/set-identity.js

@@ -0,0 +1,35 @@
+import { readIdentity, writeIdentity } from "../../../core/identity.js";
+import { confirmedProperty } from "../helpers.js";
+
+export default {
+  name: "set_identity",
+  schema: {
+    type: "function",
+    function: {
+      name: "set_identity",
+      description: "Update daemon identity fields. Persists to ~/.apx/identity.json.",
+      parameters: {
+        type: "object",
+        properties: {
+          agent_name: { type: "string", description: "new agent name" },
+          owner_name: { type: "string", description: "owner name" },
+          personality: { type: "string", description: "comma-separated personality traits" },
+          language: { type: "string", description: "preferred language" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact identity update"),
+        },
+      },
+    },
+  },
+  makeHandler: ({ requirePermission }) => ({ agent_name, owner_name, personality, language, confirmed = false } = {}) => {
+    requirePermission("set_identity", { dangerous: true, confirmed });
+    const fields = {};
+    if (agent_name) fields.agent_name = agent_name;
+    if (owner_name) fields.owner_name = owner_name;
+    if (personality) fields.personality = personality;
+    if (language) fields.language = language;
+    if (Object.keys(fields).length === 0) {
+      return { ok: true, identity: readIdentity() };
+    }
+    return { ok: true, identity: writeIdentity(fields) };
+  },
+};

package/src/daemon/super-agent-tools/tools/tail-messages.js

@@ -0,0 +1,37 @@
+import { readProjectMessages } from "../../../core/messages-store.js";
+import { resolveProject } from "../helpers.js";
+
+export default {
+  name: "tail_messages",
+  schema: {
+    type: "function",
+    function: {
+      name: "tail_messages",
+      description: "Tail project messages. Optional filter by channel and/or agent slug.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          channel: { type: "string", description: "e.g. telegram, engine, a2a, runtime, heartbeat" },
+          agent: { type: "string", description: "agent slug" },
+          limit: { type: "integer", description: "max rows; default 20" },
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => ({ project, channel, agent, limit = 20 } = {}) => {
+    const p = resolveProject(projects, project);
+    return readProjectMessages(p.path, {
+      channel,
+      agent_slug: agent,
+      limit: Math.min(limit, 100),
+    }).map((m) => ({
+      ts: m.ts,
+      channel: m.channel,
+      direction: m.direction,
+      author: m.author,
+      body: m.body,
+    }));
+  },
+};

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

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import { confirmedProperty, resolveProject, safePathJoin } from "../helpers.js";
+
+export default {
+  name: "write_file",
+  schema: {
+    type: "function",
+    function: {
+      name: "write_file",
+      description: "Create or overwrite a UTF-8 text file inside default or a project.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string" },
+          path: { type: "string", description: "relative path inside the project" },
+          content: { type: "string" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact file write"),
+        },
+        required: ["path", "content"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => ({ project, path: sub, content, confirmed = false }) => {
+    requirePermission("write_file", { dangerous: true, confirmed });
+    if (!sub) throw new Error("write_file: path required");
+    const p = resolveProject(projects, project);
+    const target = safePathJoin(p.path, sub);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, "utf8");
+    return { ok: true, path: target, bytes: Buffer.byteLength(content, "utf8") };
+  },
+};