@agentprojectcontext/apx 1.6.0 → 1.7.0

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