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, the SetSpark
// record verbs only with a setspark 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";
import { SETSPARK_TOOL_NAMES, RECORD_TYPES, LIST_MAX, FILTERS_MAX, DOCUMENT_MAX_CHARS } from "../src/setspark.mjs";

const recordType = () => Type.Union(RECORD_TYPES.map((t) => Type.Literal(t)), { description: `Record type: ${RECORD_TYPES.join(", ")}` });
const recordId = (what) => Type.String({ description: `${what} id, such as WI-101`, pattern: "^[A-Z]{2,5}-[0-9]{1,8}$" });

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" }),
  }),
  record_list: () => Type.Object({
    record_type: recordType(),
    filters: Type.Optional(Type.Record(Type.String(), Type.String(), { description: `Exact property values to match, at most ${FILTERS_MAX}, such as {"status": "active"}` })),
    limit: Type.Optional(Type.Integer({ description: `Records per page, at most ${LIST_MAX}`, minimum: 1, maximum: LIST_MAX })),
    offset: Type.Optional(Type.Integer({ description: "Records to skip, for the next page", minimum: 0 })),
  }),
  record_get: () => Type.Object({
    id: recordId("Record"),
  }),
  record_create: () => Type.Object({
    record_type: recordType(),
    record: Type.Record(Type.String(), Type.Any(), { description: "The record's properties; title is required, the service allocates the id" }),
  }),
  record_update: () => Type.Object({
    id: recordId("Record"),
    revision: Type.Integer({ description: "The revision you read with record_get", minimum: 1 }),
    fields: Type.Record(Type.String(), Type.Any(), { description: "The properties to change and their new values" }),
  }),
  resolve_id: () => Type.Object({
    query: Type.String({ description: "An exact record id or part of a title" }),
  }),
  open_approval_request: () => Type.Object({
    decision_id: recordId("Decision"),
    proposal_version: Type.Integer({ description: "The decision's proposal version, from record_get", minimum: 1 }),
    proposal_digest: Type.String({ description: "The decision's proposal digest, from record_get" }),
  }),
  get_approval_request: () => Type.Object({
    request_id: Type.Integer({ description: "The request id from open_approval_request", minimum: 1 }),
  }),
  create_document: () => Type.Object({
    collection: Type.String({ description: "Outline collection name" }),
    title: Type.String({ description: "Document title" }),
    text: Type.Optional(Type.String({ description: `Markdown body, at most ${DOCUMENT_MAX_CHARS} characters` })),
    source: Type.Optional(Type.String({ description: "Where the content came from, one line" })),
  }),
};

// The envelope's first line names the requester by the name the binding
// gives that Discord user, the author's id and the message id; the
// connector writes it, the user cannot. A prompt that does not start with
// an envelope leaves them unset, and git_commit and the SetSpark writes
// then refuse.
const ENVELOPE = /^\[discord [^\n]*\]\n/;
const field = (line, name, re) => {
  const m = line.match(new RegExp(` ${name}=${re}(?= |\\])`));
  return m ? m[1] : null;
};
export function turnOf(prompt) {
  const m = typeof prompt === "string" ? prompt.match(ENVELOPE) : null;
  if (!m) return { requester: null, turnId: null, authorId: null };
  const line = m[0];
  return {
    requester: field(line, "requester", '"([^"\\n\\]]{1,100})"'),
    authorId: field(line, "author", "([0-9]{15,20})"),
    turnId: field(line, "message", "([0-9]{15,20})"),
  };
}
export function requesterOf(prompt) {
  return turnOf(prompt).requester;
}

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.setTurn(turnOf(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_") || SETSPARK_TOOL_NAMES.includes(name) ? "" : 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 };
      },
    });
  }
}