@agentprojectcontext/apx 1.30.2 → 1.31.1

package/src/host/daemon/super-agent-tools/tools/discover-tools.js

@@ -0,0 +1,67 @@
+// discover_tools — lazy tool discovery + activation.
+//
+// Roby (and any super-agent surface) only carries a small "base" set of tool
+// schemas on lightweight channels (Telegram/desktop/deck) to stay under
+// cheap-tier TPM caps. The rest (browser/Puppeteer, fetch, web_search, runtime,
+// voice, …) exist but are NOT sent to the model by default. This tool is how
+// the model reveals and activates them on demand:
+//
+//   discover_tools()                              → catalog of NOT-loaded tools
+//   discover_tools({ category: "browser" })       → activate a whole category
+//   discover_tools({ names: ["browser_navigate"] })→ activate specific tools
+//
+// Activation pushes the requested schemas into the per-turn tool session; the
+// agent loop (run-agent.js) merges them into the live schema set so the NEXT
+// model call can actually invoke them. Handlers for every tool already exist —
+// gating is purely about which schemas the model sees.
+
+export default {
+  name: "discover_tools",
+  schema: {
+    type: "function",
+    function: {
+      name: "discover_tools",
+      description:
+        "Discover and activate additional tools that are not loaded by default. " +
+        "Call with NO arguments to get the catalog of available-but-not-loaded tools " +
+        "(name + 1-line description, grouped by category). Call with `category` (e.g. " +
+        "\"browser\", \"fetch\") or `names` (exact tool names) to ACTIVATE those tools — " +
+        "they become callable starting on your next step. Use this whenever the tool you " +
+        "need (browser automation, HTTP fetch, web search, runtime delegation, voice, …) " +
+        "isn't in your current tool list.",
+      parameters: {
+        type: "object",
+        properties: {
+          category: {
+            type: "string",
+            description:
+              "Activate every not-loaded tool in this category (e.g. \"browser\", \"fetch\", \"search\").",
+          },
+          names: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Exact tool names to activate, e.g. [\"browser_navigate\", \"browser_screenshot\"].",
+          },
+        },
+      },
+    },
+  },
+  makeHandler: (ctx) => ({ category, names } = {}) => {
+    const session = ctx?.toolSession;
+    // No lazy session (full channels, or direct handler use in tests): every
+    // tool is already exposed, so there's nothing to discover or activate.
+    if (!session) {
+      return {
+        ok: true,
+        loaded_all: true,
+        note: "En este canal todas las tools ya están cargadas; no hace falta discover_tools.",
+      };
+    }
+    const wantsActivate =
+      (Array.isArray(names) && names.length > 0) ||
+      (typeof category === "string" && category.trim() !== "");
+    if (!wantsActivate) return session.catalogResponse();
+    return session.activate({ names, category });
+  },
+};

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

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { readVaultAgents, VAULT_DIR } from "../../../../core/parser.js";
 import { addImportedAgent, ensureAgentDir } from "../../../../core/scaffold.js";
+import { ensureAgentRuntimeDir } from "../../../../core/agent-memory.js";
 import { confirmedProperty, projectMeta, resolveProject } from "../helpers.js";
 
 export default {
@@ -35,6 +36,7 @@ export default {
     const p = resolveProject(projects, project || "default");
     addImportedAgent(p.path, slug);
     ensureAgentDir(p.path, slug);
+    ensureAgentRuntimeDir(p, slug);
     projects.rebuild(p.id);
 
     return {

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

@@ -1,6 +1,6 @@
 import fs from "node:fs";
-import path from "node:path";
 import { resolveProject } from "../helpers.js";
+import { agentMemoryPath, readAgentMemory } from "../../../../core/agent-memory.js";
 
 export default {
   name: "read_agent_memory",
@@ -21,8 +21,9 @@ export default {
   },
   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") };
+    const file = agentMemoryPath(p, agent);
+    const body = readAgentMemory(p, agent);
+    if (!body && !fs.existsSync(file)) return { error: `no memory.md for agent ${agent}` };
+    return { body, path: file };
   },
 };

package/src/host/daemon/super-agent.js

@@ -1,5 +1,5 @@
 // Super-agent: daemon-level action agent for Telegram, TUI, desktop, routines.
-import { schemasForChannel, makeToolHandlers } from "./super-agent-tools/index.js";
+import { createToolSession, buildLazyToolsBlock, makeToolHandlers } from "./super-agent-tools/index.js";
 import { listSkills } from "./skills-loader.js";
 import {
   runAgent,
@@ -79,6 +79,15 @@ export async function runSuperAgent({
     }
   }
 
+  // Per-turn tool session. Lightweight channels (telegram/desktop/deck) start
+  // on the small "base" set and expand on demand via discover_tools; full
+  // channels (routine/api/web/code/terminal) get the whole registry up front.
+  // The session also enforces role gating ("*" = unrestricted, [] = none,
+  // array = allowlist) on BOTH the initial set and any later activation, so a
+  // limited sender can't discover its way past the gate.
+  // noTools callers (summarize/ask) get no session — text only.
+  const toolSession = noTools ? null : createToolSession(channel, { allowedTools });
+
   const system = buildSuperAgentSystem({
     globalConfig,
     projects,
@@ -90,23 +99,12 @@ export async function runSuperAgent({
     systemSuffix,
     memoryBlock,
     activeThreadsBlock,
+    // Compact "tools you can activate" block (names only, no schemas). Empty on
+    // full channels and tool-free callers, where it's omitted from the prompt.
+    lazyToolsBlock: buildLazyToolsBlock(toolSession),
   });
 
-  // Pick the schema subset for this channel: chit-chat surfaces get a small
-  // "core" set (~700 tokens) to fit cheap-tier TPM caps; routines get the
-  // full registry. The model can still call load_skill / read more on demand.
-  // noTools callers (summarize/ask) get an empty set — text only.
-  let toolSchemas = noTools ? [] : schemasForChannel(channel);
-  // Role gating: restrict the visible tools for limited senders (e.g. guests
-  // on Telegram). "*" = unrestricted; [] = no tools; array = allowlist.
-  if (allowedTools !== "*" && Array.isArray(allowedTools)) {
-    if (allowedTools.length === 0) {
-      toolSchemas = [];
-    } else {
-      const allow = new Set(allowedTools);
-      toolSchemas = toolSchemas.filter((t) => allow.has(t?.function?.name || t?.name));
-    }
-  }
+  const toolSchemas = noTools ? [] : toolSession.initialSchemas;
 
   return runAgent({
     globalConfig,
@@ -116,7 +114,7 @@ export async function runSuperAgent({
     overrideModel,
     toolSchemas,
     makeToolHandlers,
-    toolHandlerCtx: { projects, plugins, registries, globalConfig, channel },
+    toolHandlerCtx: { projects, plugins, registries, globalConfig, channel, toolSession },
     onEvent,
     signal,
     onToken,

package/src/interfaces/cli/commands/agent.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { findApfRoot, readAgents, readVaultAgents, readVaultAgent, VAULT_DIR, SLUG_RE } from "../../../core/parser.js";
 import { writeAgentFile, writeVaultAgentFile, removeVaultAgent, restoreVaultAgent, addImportedAgent, ensureAgentDir } from "../../../core/scaffold.js";
+import { ensureAgentRuntimeDir, agentMemoryPath } from "../../../core/agent-memory.js";
 import { http } from "../http.js";
 
 // ── ANSI ──────────────────────────────────────────────────────────────────────
@@ -49,6 +50,7 @@ export async function cmdAgentAdd(args) {
 
   writeAgentFile(root, slug, fields);
   ensureAgentDir(root, slug);
+  ensureAgentRuntimeDir(root, slug);
   await nudgeDaemon(root);
 
   console.log(`Added agent ${slug}`);
@@ -207,10 +209,11 @@ export async function cmdAgentImport(args) {
     addImportedAgent(root, slug);
     console.log(`\n  ${bold(slug)} imported from vault ${tag("↑ vault")}\n`);
     console.log(gray(`  definition: ${vaultPath}`));
-    console.log(gray(`  memory:     ${path.join(root, ".apc", "agents", slug, "memory.md")} (project-local)`));
+    console.log(gray(`  memory:     ${agentMemoryPath(root, slug)} (runtime-local)`));
     console.log();
   }
 
   ensureAgentDir(root, slug);
+  ensureAgentRuntimeDir(root, slug);
   await nudgeDaemon(root);
 }

package/src/interfaces/cli/commands/memory.js

@@ -1,7 +1,6 @@
 import fs from "node:fs";
-import path from "node:path";
 import { findApfRoot } from "../../../core/parser.js";
-import { ensureAgentDir } from "../../../core/scaffold.js";
+import { agentMemoryPath, readAgentMemory, writeAgentMemory, ensureAgentRuntimeDir } from "../../../core/agent-memory.js";
 import { http } from "../http.js";
 
 function requireRoot() {
@@ -23,12 +22,11 @@ export async function cmdMemory(args) {
   const slug = args._[0];
   if (!slug) throw new Error("apx memory: missing <agent-slug>");
   const root = requireRoot();
-  const memPath = path.join(root, ".apc", "agents", slug, "memory.md");
+  const memPath = agentMemoryPath(root, slug);
 
   if (args.flags.replace) {
     const newBody = readStdinSync();
-    ensureAgentDir(root, slug);
-    fs.writeFileSync(memPath, newBody);
+    writeAgentMemory(root, slug, newBody);
     await nudgeDaemon(root);
     console.log(`replaced memory for ${slug} (${Buffer.byteLength(newBody)} bytes)`);
     return;
@@ -36,23 +34,24 @@ export async function cmdMemory(args) {
 
   if (args.flags.append && args.flags.append !== true) {
     const note = String(args.flags.append);
-    ensureAgentDir(root, slug);
-    let body = fs.existsSync(memPath) ? fs.readFileSync(memPath, "utf8") : "";
+    ensureAgentRuntimeDir(root, slug);
+    let body = readAgentMemory(root, slug);
     if (!/##\s+Recent context/i.test(body)) {
       body += body.endsWith("\n") ? "\n## Recent context\n" : "\n\n## Recent context\n";
     }
     const today = new Date().toISOString().slice(0, 10);
     body = body.replace(/(##\s+Recent context\s*\n)/i, `$1- ${today}: ${note}\n`);
-    fs.writeFileSync(memPath, body);
+    writeAgentMemory(root, slug, body);
     await nudgeDaemon(root);
     console.log(`appended to ${slug} memory: ${note}`);
     return;
   }
 
-  if (!fs.existsSync(memPath)) {
+  const body = readAgentMemory(root, slug);
+  if (!body && !fs.existsSync(memPath)) {
     throw new Error(`no memory for "${slug}" — agent dir not yet created`);
   }
-  process.stdout.write(fs.readFileSync(memPath, "utf8"));
+  process.stdout.write(body);
 }
 
 function readStdinSync() {