feat(discord): read-only tools for the Discord Sage through a Mosaic pi extension confined to declared roots (#1509)

A binding may declare `tools` with named roots. pi starts with --no-builtin-tools and the package's own extension, allowlisting list_dir, read_file and search. src/tools.mjs holds the rules: names not paths, per-segment lstat walk, one checked descriptor read that refuses symlinks, swaps, FIFOs, hard links and oversize files, credential shapes refusing the whole read, and a per-message call budget. The engine settles on agent_end and records tool calls in the turn record. Jason's rulings R1-R7 in the brief, section 7. rev-code-02 approved round 2 (comment 26276) on tree 43f0329b after four round 1 fixes. Suite 48/48, node tests 116. Not pushed. Co-Authored-By: Claude Opus 5 <[email protected]>
2026-09-14 19:52:21 -05:00
parent c4fc8e7d7f
commit 1ac812d3d5
24 changed files with 1269 additions and 44 deletions
@@ -0,0 +1,66 @@
+// pi extension: the Discord Sage's read-only tools. Loaded by the connector
+// with `--no-builtin-tools --extension <this file> --tools list_dir,read_file,search`
+// so pi exposes exactly these three tools and none of its own.
+//
+// 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_NAMES, TOOL_DESCRIPTIONS, READ_MAX_LINES, loadToolsConfig, createToolSet } 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" })),
+  }),
+};
+
+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.name).join(", ");
+
+  pi.on("agent_start", async () => {
+    tools.resetBudget();
+  });
+
+  for (const name of TOOL_NAMES) {
+    const d = TOOL_DESCRIPTIONS[name];
+    pi.registerTool({
+      name,
+      label: d.label,
+      description: `${d.description} Declared roots: ${rootNames}.`,
+      promptSnippet: d.snippet,
+      parameters: PARAMS[name](),
+      async execute(_toolCallId, params) {
+        const r = tools.call(name, params);
+        return { content: [{ type: "text", text: r.text }], details: r.details };
+      },
+    });
+  }
+}