feat(discord): writes on write-marked roots, web fetch and search, held prompts (#1509)

Row 23. write_file and edit_file for roots marked write: true under the same fence as reads; web_fetch (https only, public addresses, pinned connection, capped body) and web_search through SearXNG; extension renamed to tools.mjs. Engine holds a prompt while pi is busy and sends it as its own run, so a second message mid-turn no longer folds into the first (live defect). fake-pi models the real follow-up folding. Suite 52/52, node tests 129. rev-code-02 APPROVED round 3, comment 26362, tree dbd2ce9a. Records: QUEUE rows 23-24, CURRENT, BUILD-LOG phase, SESSIONS, row 24 brief (git verbs, D5-D7 ruled). Co-Authored-By: Claude Fable 5.1 <[email protected]>
2026-09-18 07:27:50 -05:00
parent 1ac812d3d5
commit 1685deb423
24 changed files with 1519 additions and 113 deletions
@@ -0,0 +1,86 @@
+// pi extension: the Discord Sage's tools. Loaded by the connector with
+// `--no-builtin-tools --extension <this file> --tools <enabled names>` so pi
+// exposes exactly the tools the binding enables and none of its own: the
+// three reads always, write_file and edit_file only when a root is marked
+// write: true, web_fetch and web_search only with a web key
+// (enabledToolNames in ../src/tools.mjs decides, in one place).
+//
+// Every decision lives in ../src/tools.mjs; this file only registers the
+// tools with pi and reads its configuration from the one environment
+// variable the engine sets (MOSAIC_DISCORD_TOOLS, JSON). A missing or
+// invalid value throws here, which fails the pi start and therefore the
+// connector: nothing is defaulted, nothing is read from anywhere else.
+//
+// The per-message budget resets on agent_start, the event pi emits once per
+// prompt run, so a follow-up message gets a fresh budget.
+
+import { Type } from "typebox";
+import { TOOLS_ENV, TOOL_DESCRIPTIONS, READ_MAX_LINES, loadToolsConfig, createToolSet, enabledToolNames } from "../src/tools.mjs";
+
+const PARAMS = {
+  list_dir: () => Type.Object({
+    root: Type.String({ description: "Name of a declared root" }),
+    path: Type.Optional(Type.String({ description: "Folder path relative to the root; empty for the root itself" })),
+  }),
+  read_file: () => Type.Object({
+    root: Type.String({ description: "Name of a declared root" }),
+    path: Type.String({ description: "File path relative to the root" }),
+    offset: Type.Optional(Type.Integer({ description: "First line to return, 1-based", minimum: 1 })),
+    limit: Type.Optional(Type.Integer({ description: `Number of lines, at most ${READ_MAX_LINES}`, minimum: 1, maximum: READ_MAX_LINES })),
+  }),
+  search: () => Type.Object({
+    root: Type.String({ description: "Name of a declared root" }),
+    text: Type.String({ description: "Fixed string to find, case-insensitive" }),
+    path: Type.Optional(Type.String({ description: "Subfolder or file relative to the root; empty for the whole root" })),
+  }),
+  write_file: () => Type.Object({
+    root: Type.String({ description: "Name of a root that allows writes" }),
+    path: Type.String({ description: "File path relative to the root; the parent folder must exist" }),
+    text: Type.String({ description: "The whole new content of the file" }),
+  }),
+  edit_file: () => Type.Object({
+    root: Type.String({ description: "Name of a root that allows writes" }),
+    path: Type.String({ description: "File path relative to the root" }),
+    old: Type.String({ description: "Exact text to replace; must occur exactly once" }),
+    new: Type.String({ description: "Replacement text" }),
+  }),
+  web_fetch: () => Type.Object({
+    url: Type.String({ description: "Absolute https url of a public page" }),
+  }),
+  web_search: () => Type.Object({
+    query: Type.String({ description: "Search words, as you would type them" }),
+  }),
+};
+
+export default function (pi) {
+  const raw = process.env[TOOLS_ENV];
+  if (typeof raw !== "string" || raw.length === 0) throw new Error(`${TOOLS_ENV} is not set; the connector sets it from the binding's tools key`);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${TOOLS_ENV} is not valid JSON: ${err.message}`);
+  }
+  const config = loadToolsConfig(parsed);
+  const tools = createToolSet(config);
+  const rootNames = config.roots.map((r) => (r.write ? `${r.name} (writable)` : r.name)).join(", ");
+
+  pi.on("agent_start", async () => {
+    tools.resetBudget();
+  });
+
+  for (const name of enabledToolNames(config)) {
+    const d = TOOL_DESCRIPTIONS[name];
+    pi.registerTool({
+      name,
+      label: d.label,
+      description: name.startsWith("web_") ? d.description : `${d.description} Declared roots: ${rootNames}.`,
+      promptSnippet: d.snippet,
+      parameters: PARAMS[name](),
+      async execute(_toolCallId, params) {
+        const r = await tools.call(name, params);
+        return { content: [{ type: "text", text: r.text }], details: r.details };
+      },
+    });
+  }
+}