stack/packages/discord/extension/tools.mjs

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