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";
import { COMMIT_MESSAGE_MAX, COMMIT_PATHS_MAX, VAULT_PREFIXES } from "../src/git.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" }),
  }),
  git_status: () => Type.Object({
    root: Type.String({ description: "Name of a root that has git" }),
  }),
  git_commit: () => Type.Object({
    root: Type.String({ description: "Name of a root that has git" }),
    message: Type.String({ description: `Commit message, one to ${COMMIT_MESSAGE_MAX} characters: what changed and why` }),
    paths: Type.Array(Type.String({ description: "File path relative to the root" }), { description: `The files to commit, relative to the root; at most ${COMMIT_PATHS_MAX}`, minItems: 1, maxItems: COMMIT_PATHS_MAX }),
  }),
  git_pull: () => Type.Object({
    root: Type.String({ description: "Name of a root that has git" }),
  }),
  git_push: () => Type.Object({
    root: Type.String({ description: "Name of a root that has git" }),
  }),
  reserve_id: () => Type.Object({
    root: Type.String({ description: "Name of a root that follows the record protocol" }),
    prefix: Type.Union(VAULT_PREFIXES.map((p) => Type.Literal(p)), { description: `Record prefix: ${VAULT_PREFIXES.join(", ")}` }),
    title: Type.String({ description: "What the record will be about, one line" }),
  }),
};

// The envelope's first line names the requester by the name the binding
// gives that Discord user; the connector writes it, the user cannot. A
// prompt that does not start with an envelope leaves the requester unset,
// and git_commit then refuses.
const ENVELOPE_REQUESTER = /^\[discord [^\n]*? requester="([^"\n\]]{1,100})"[^\n]*\]\n/;
export function requesterOf(prompt) {
  const m = typeof prompt === "string" ? prompt.match(ENVELOPE_REQUESTER) : null;
  return m ? m[1] : null;
}

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.git ? `${r.name} (writable, git on ${r.git.branch})` : r.write ? `${r.name} (writable)` : r.name)).join(", ");
  const gitRoots = config.roots.filter((r) => r.git).map((r) => r.name).join(", ");

  pi.on("before_agent_start", async (event) => {
    tools.setRequester(requesterOf(event.prompt));
  });
  pi.on("agent_start", async () => {
    tools.resetBudget();
  });

  for (const name of enabledToolNames(config)) {
    const d = TOOL_DESCRIPTIONS[name];
    const suffix = name.startsWith("web_") ? "" : name.startsWith("git_") || name === "reserve_id" ? ` Roots with git: ${gitRoots}.` : ` Declared roots: ${rootNames}.`;
    pi.registerTool({
      name,
      label: d.label,
      description: `${d.description}${suffix}`,
      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 };
      },
    });
  }
}