@mmerterden/multi-agent-pipeline 20.29.0 → 20.33.0

package/pipeline/scripts/toolkit-tools.mjs

@@ -0,0 +1,625 @@
+#!/usr/bin/env node
+/**
+ * @file toolkit-tools.mjs  -  the multi-agent-toolkit MCP server's tools, for
+ * a client that is not an MCP host: list them, and call one with arguments its
+ * own inputSchema accepts.
+ *
+ * The server is the one the user registered with Claude Code: the
+ * `mcpServers` entry whose name contains "toolkit" in ~/.claude.json, else in
+ * ~/.claude/settings.json (the lookup doctor.mjs makes). It is started as a
+ * stdio child with that entry's command, arguments and environment on top of
+ * this process's, so every guard the toolkit honours from the environment
+ * (MULTI_AGENT_UNATTENDED, its URL policy) applies unchanged, and a tool's own
+ * confirm or preview behaviour stays the tool's. One child per client, started
+ * on first use and closed with it.
+ *
+ * Each tool carries `risk` from its own annotations: readOnlyHint is read,
+ * destructiveHint is high, anything else is low.
+ *
+ * Calls are denied by default. A tool may be called only when it declares
+ * readOnlyHint and its inputSchema takes nothing that names a place: no
+ * property whose name speaks of a path, URL, file, directory, output, project
+ * or root, and no uri format, at any depth. Everything else is listed with
+ * `allowed: false` and refused with `tool-not-allowed`, because a read-only
+ * tool that is handed a location reads whatever the location points at (a
+ * local file, a loopback service). Arguments may not carry `confirm`, which
+ * would skip a tool's own preview.
+ *
+ * The child always runs with MULTI_AGENT_UNATTENDED=1 and
+ * MCP_TOOLKIT_URL_POLICY=strict, set after the registration's own environment
+ * so neither can be overridden. A registration whose package spec has no exact
+ * version (bare, a dist-tag such as `@latest`, or a range) is pinned to
+ * MA_TOOLKIT_VERSION, else prefs.global.office.toolkitVersion, else the
+ * version the release ships beside the office page (office/toolkit.json, the
+ * one it was checked against), and refused when none is set.
+ *
+ * No tool that is not read-only is allowed today. Opening one up means routing
+ * it through the server's two-step confirm, never a direct call.
+ *
+ * Arguments are checked against the tool's inputSchema before the call (the
+ * subset the toolkit's schemas use: type, enum, const, required, properties,
+ * additionalProperties, items, min/max, minLength/maxLength, pattern). A key
+ * the schema does not declare is refused at any depth, whatever
+ * additionalProperties says, and so is a `confirm` key. An unknown tool or
+ * invalid arguments never reach the server. Results come back as text
+ * (redacted), JSON (redacted, as text) and images (base64, image types only,
+ * size-capped); a tool's error message is redacted too.
+ *
+ * Usage:
+ *   toolkit-tools.mjs list
+ *   toolkit-tools.mjs call <name> '<json arguments>'
+ *
+ * MA_TOOLKIT_MCP sets the server as JSON {command, args, env} (tests).
+ *
+ * Exit: 0 printed, 1 refused or failed, 2 usage.
+ *
+ * @module pipeline/scripts/toolkit-tools
+ */
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { clearTimeout, setTimeout } from "node:timers";
+import { createRedactor } from "./transcript-index.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const START_TIMEOUT_MS = 60_000;
+const CALL_TIMEOUT_MS = 180_000;
+const MAX_LINE_BYTES = 16 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+
+export class ToolError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.code = code;
+    this.extra = extra;
+  }
+}
+
+const readJson = (p) => {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/** The registered toolkit server, or null. */
+export function toolkitEntry(env = process.env) {
+  if (env.MA_TOOLKIT_MCP) {
+    try {
+      const e = JSON.parse(env.MA_TOOLKIT_MCP);
+      if (e && typeof e.command === "string") return e;
+    } catch {
+      return null;
+    }
+  }
+  const home = env.HOME || homedir();
+  for (const p of [join(home, ".claude.json"), join(home, ".claude", "settings.json")]) {
+    const j = readJson(p);
+    const key = j?.mcpServers && Object.keys(j.mcpServers).find((k) => /toolkit/i.test(k));
+    if (key && typeof j.mcpServers[key]?.command === "string") return j.mcpServers[key];
+  }
+  return null;
+}
+
+/**
+ * Families refused whatever their schema says: `web` tools share a browser
+ * whose page may already point at a local file or service, and `context`
+ * tools search an index built from whatever files were indexed.
+ */
+const DENIED_CATEGORIES = new Set(["web", "context"]);
+
+/** Property names that hand a tool a location to read or write. */
+const LOCATION_NAME =
+  /(path|url|uri|href|link|file|dir|folder|output|out_?dir|project|root|cwd|workspace|location|endpoint|host|address|socket|device|bundle|archive|repo)/i;
+const LOCATION_FORMAT = /^(uri|uri-reference|iri|iri-reference|url|hostname|idn-hostname)$/i;
+
+/** The location-shaped properties anywhere in a schema, by name or format. */
+export function locationProperties(schema, prefix = "") {
+  const out = [];
+  if (!schema || typeof schema !== "object") return out;
+  for (const [k, v] of Object.entries(schema.properties ?? {})) {
+    const at = prefix ? `${prefix}.${k}` : k;
+    if (LOCATION_NAME.test(k) || LOCATION_FORMAT.test(String(v?.format ?? ""))) out.push(at);
+    out.push(...locationProperties(v, at));
+    if (v?.items) out.push(...locationProperties(v.items, `${at}[]`));
+  }
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    for (const alt of Array.isArray(schema[key]) ? schema[key] : []) {
+      out.push(...locationProperties(alt, prefix));
+    }
+  }
+  if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+    out.push(...locationProperties(schema.additionalProperties, `${prefix}*`));
+  }
+  return out;
+}
+
+/**
+ * Whether a tool may be called from this client, and why not. Only a
+ * read-only tool that takes no location is allowed.
+ */
+export function callPolicy(tool) {
+  if (DENIED_CATEGORIES.has(categoryOf(String(tool?.name ?? "")))) {
+    return {
+      allowed: false,
+      reason:
+        "this family reads state shared with other sessions (a browser, an index of files); call it from a terminal session",
+    };
+  }
+  if (tool?.annotations?.readOnlyHint !== true || riskOf(tool) !== "read") {
+    return {
+      allowed: false,
+      reason: "only tools that declare readOnlyHint, and nothing destructive, can be called here",
+    };
+  }
+  const where = locationProperties(tool.inputSchema);
+  if (where.length) {
+    return {
+      allowed: false,
+      reason: `the tool takes a location (${where.slice(0, 3).join(", ")}); call it from a terminal session`,
+    };
+  }
+  return { allowed: true, reason: null };
+}
+
+/** Environment the toolkit child cannot override: unattended guards, strict URL policy. */
+export const FORCED_ENV = Object.freeze({
+  MULTI_AGENT_UNATTENDED: "1",
+  MCP_TOOLKIT_URL_POLICY: "strict",
+});
+
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+const RUNNERS = new Set(["npx", "bunx", "pnpx"]);
+
+/**
+ * The package specs a registration hands to a package runner (npx, bunx,
+ * pnpx, `npm exec`, `pnpm dlx`): the first positional argument, or each
+ * `-p` / `--package` value. A registration that runs a local file has none.
+ */
+export function packageSpecs(entry) {
+  const cmd = basename(String(entry?.command ?? ""));
+  const args = Array.isArray(entry?.args) ? entry.args.map(String) : [];
+  let rest;
+  if (RUNNERS.has(cmd)) rest = args;
+  else if (cmd === "npm" && (args[0] === "exec" || args[0] === "x")) rest = args.slice(1);
+  else if (cmd === "pnpm" && args[0] === "dlx") rest = args.slice(1);
+  else return [];
+  const specs = [];
+  let named = false;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "-p" || a === "--package") {
+      if (rest[i + 1] !== undefined) specs.push(rest[++i]);
+      named = true;
+    } else if (a.startsWith("--package=")) {
+      specs.push(a.slice("--package=".length));
+      named = true;
+    } else if (a === "--") {
+      if (!named && rest[i + 1] !== undefined) specs.push(rest[i + 1]);
+      break;
+    } else if (!a.startsWith("-")) {
+      if (!named) specs.push(a);
+      break;
+    }
+  }
+  return specs;
+}
+
+/** The name and version of a spec: `@scope/name@1.2.3`, `name@^1`, `name`. */
+function splitSpec(spec) {
+  const at = spec.lastIndexOf("@");
+  return at > 0 ? [spec.slice(0, at), spec.slice(at + 1)] : [spec, null];
+}
+
+/**
+ * Whether a registration would resolve its package anew on every start: a
+ * spec without an exact version (bare, a dist-tag such as latest or next, or
+ * a range) is unpinned.
+ */
+export function unpinned(entry) {
+  return packageSpecs(entry).some((s) => !SEMVER.test(splitSpec(s)[1] ?? ""));
+}
+
+/**
+ * The registration with every unpinned spec set to `<name>@<version>`, or
+ * null when it is unpinned and no exact version is known. The version comes
+ * from MA_TOOLKIT_VERSION, else prefs.global.office.toolkitVersion, else
+ * office/toolkit.json beside the page (MA_OFFICE_PAGE's directory, or the
+ * office directory next to this script's).
+ */
+export function pinnedEntry(entry, env = process.env) {
+  if (!unpinned(entry)) return entry;
+  const prefs = readJson(join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json"));
+  const version =
+    env.MA_TOOLKIT_VERSION || prefs?.global?.office?.toolkitVersion || shippedToolkitVersion(env);
+  if (typeof version !== "string" || !SEMVER.test(version)) return null;
+  const loose = new Set(packageSpecs(entry).filter((s) => !SEMVER.test(splitSpec(s)[1] ?? "")));
+  const pin = (a) => {
+    if (typeof a !== "string") return a;
+    if (loose.has(a)) return `${splitSpec(a)[0]}@${version}`;
+    if (a.startsWith("--package=") && loose.has(a.slice(10))) {
+      return `--package=${splitSpec(a.slice(10))[0]}@${version}`;
+    }
+    return a;
+  };
+  return { ...entry, args: Array.isArray(entry.args) ? entry.args.map(pin) : entry.args };
+}
+
+/** The toolkit version the release ships beside the office page, or undefined. */
+export function shippedToolkitVersion(env = process.env) {
+  const dir = env.MA_OFFICE_PAGE
+    ? dirname(env.MA_OFFICE_PAGE)
+    : join(import.meta.dirname, "..", "office");
+  const v = readJson(join(dir, "toolkit.json"))?.toolkitVersion;
+  return typeof v === "string" && SEMVER.test(v) ? v : undefined;
+}
+
+/** The exact toolkit version the Tools window starts, or null when none is known. */
+export function activeToolkitVersion(env = process.env) {
+  const registered = toolkitEntry(env);
+  const entry = registered ? pinnedEntry(registered, env) : null;
+  const spec = entry ? packageSpecs(entry)[0] : null;
+  const v = spec ? splitSpec(spec)[1] : null;
+  return typeof v === "string" && SEMVER.test(v) ? v : null;
+}
+
+/** read, low or high, from the tool's own annotations. */
+export function riskOf(tool) {
+  const a = tool?.annotations ?? {};
+  if (a.destructiveHint === true) return "high";
+  if (a.readOnlyHint === true) return "read";
+  return "low";
+}
+
+/** The tool's category: the prefix before its first underscore. */
+export const categoryOf = (name) => (name.includes("_") ? name.split("_")[0] : "other");
+
+/**
+ * Every reason `value` does not satisfy `schema`, for the subset of JSON
+ * Schema the toolkit's input schemas use. Unknown keywords are ignored; the
+ * server validates again.
+ */
+export function schemaErrors(schema, value, path = "", opts = {}) {
+  if (!schema || typeof schema !== "object") return [];
+  const at = path || "/";
+  const errors = [];
+  const types = schema.type === undefined ? null : [].concat(schema.type);
+  const typeOf = (v) =>
+    v === null ? "null" : Array.isArray(v) ? "array" : Number.isInteger(v) ? "integer" : typeof v;
+  if (types) {
+    const t = typeOf(value);
+    const ok = types.some((x) => x === t || (x === "number" && t === "integer"));
+    if (!ok) return [`${at} must be ${types.join(" or ")}`];
+  }
+  if (
+    Array.isArray(schema.enum) &&
+    !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))
+  ) {
+    errors.push(`${at} must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+  }
+  if ("const" in schema && JSON.stringify(schema.const) !== JSON.stringify(value)) {
+    errors.push(`${at} must be ${JSON.stringify(schema.const)}`);
+  }
+  if (typeof value === "string") {
+    if (Number.isInteger(schema.minLength) && value.length < schema.minLength)
+      errors.push(`${at} is too short`);
+    if (Number.isInteger(schema.maxLength) && value.length > schema.maxLength)
+      errors.push(`${at} is too long`);
+    if (typeof schema.pattern === "string") {
+      try {
+        if (!new RegExp(schema.pattern, "u").test(value))
+          errors.push(`${at} does not match its pattern`);
+      } catch {
+        // A pattern this engine cannot compile is left to the server.
+      }
+    }
+  }
+  if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum)
+      errors.push(`${at} is below ${schema.minimum}`);
+    if (typeof schema.maximum === "number" && value > schema.maximum)
+      errors.push(`${at} is above ${schema.maximum}`);
+  }
+  if (Array.isArray(value)) {
+    if (Number.isInteger(schema.maxItems) && value.length > schema.maxItems)
+      errors.push(`${at} has too many items`);
+    if (Number.isInteger(schema.minItems) && value.length < schema.minItems)
+      errors.push(`${at} has too few items`);
+    if (schema.items && typeof schema.items === "object") {
+      value.forEach((v, i) => errors.push(...schemaErrors(schema.items, v, `${path}/${i}`, opts)));
+    }
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const props = schema.properties ?? {};
+    for (const k of Array.isArray(schema.required) ? schema.required : []) {
+      if (!(k in value)) errors.push(`${path}/${k} is required`);
+    }
+    for (const [k, v] of Object.entries(value)) {
+      if (Object.hasOwn(props, k)) errors.push(...schemaErrors(props[k], v, `${path}/${k}`, opts));
+      else if (opts.strict) errors.push(`${path}/${k} is not declared by the tool's inputSchema`);
+      else if (schema.additionalProperties === false) errors.push(`${path}/${k} is not allowed`);
+      else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        errors.push(...schemaErrors(schema.additionalProperties, v, `${path}/${k}`, opts));
+      }
+    }
+  }
+  return errors;
+}
+
+/** Every `confirm` key in an argument value, at any depth, as JSON pointers. */
+export function confirmPaths(value, path = "") {
+  if (Array.isArray(value)) return value.flatMap((v, i) => confirmPaths(v, `${path}/${i}`));
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([k, v]) => [
+    ...(k === "confirm" ? [`${path}/confirm`] : []),
+    ...confirmPaths(v, `${path}/${k}`),
+  ]);
+}
+
+/**
+ * A stdio MCP client for the toolkit, started lazily, one per caller.
+ *
+ * @param {{env?: object}} [opts]
+ */
+export function createToolkitClient({ env = process.env } = {}) {
+  let child = null;
+  let ready = null;
+  let nextId = 1;
+  let buf = "";
+  let tools = null;
+  const pending = new Map();
+
+  const failAll = (err) => {
+    for (const p of pending.values()) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    pending.clear();
+  };
+
+  const rpc = (method, params, timeoutMs) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new ToolError("timeout", `the toolkit did not answer ${method} in time`));
+      }, timeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+
+  const start = () => {
+    if (ready) return ready;
+    const registered = toolkitEntry(env);
+    if (!registered) {
+      return Promise.reject(
+        new ToolError("not-registered", "multi-agent-toolkit is not registered as an MCP server"),
+      );
+    }
+    const entry = pinnedEntry(registered, env);
+    if (!entry) {
+      return Promise.reject(
+        new ToolError(
+          "unpinned",
+          "no exact toolkit version is known: the release ships it in office/toolkit.json beside the page, which reinstalling (node install.js) restores; MA_TOOLKIT_VERSION or prefs.global.office.toolkitVersion override it",
+        ),
+      );
+    }
+    ready = new Promise((resolve, reject) => {
+      child = spawn(entry.command, Array.isArray(entry.args) ? entry.args : [], {
+        env: { ...env, ...(entry.env ?? {}), ...FORCED_ENV },
+        stdio: ["pipe", "pipe", "ignore"],
+      });
+      child.on("error", (e) => {
+        ready = null;
+        reject(
+          new ToolError("not-started", `the toolkit could not start (${e.code ?? e.message})`),
+        );
+      });
+      child.on("exit", () => {
+        ready = null;
+        tools = null;
+        failAll(new ToolError("exited", "the toolkit exited"));
+      });
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (d) => {
+        buf += d;
+        if (buf.length > MAX_LINE_BYTES) {
+          buf = "";
+          return;
+        }
+        let nl;
+        while ((nl = buf.indexOf("\n")) !== -1) {
+          const line = buf.slice(0, nl);
+          buf = buf.slice(nl + 1);
+          let msg;
+          try {
+            msg = JSON.parse(line);
+          } catch {
+            continue;
+          }
+          const p = msg && pending.get(msg.id);
+          if (!p) continue;
+          pending.delete(msg.id);
+          clearTimeout(p.timer);
+          if (msg.error) {
+            const why = createRedactor().clean(String(msg.error.message ?? "the tool failed"));
+            p.reject(new ToolError("tool-error", why.slice(0, 2000)));
+          } else p.resolve(msg.result);
+        }
+      });
+      rpc(
+        "initialize",
+        {
+          protocolVersion: "2025-06-18",
+          capabilities: {},
+          clientInfo: { name: "multi-agent-contract-server", version: CONTRACT_VERSION },
+        },
+        START_TIMEOUT_MS,
+      )
+        .then(() => {
+          child.stdin.write(
+            JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n",
+          );
+          resolve();
+        })
+        .catch((e) => {
+          ready = null;
+          reject(e);
+        });
+    });
+    return ready;
+  };
+
+  /** Every tool with its category, risk, description and inputSchema. */
+  async function listTools() {
+    if (tools) return tools;
+    await start();
+    const all = [];
+    let cursor;
+    for (let page = 0; page < 20; page++) {
+      const r = await rpc("tools/list", cursor ? { cursor } : {}, START_TIMEOUT_MS);
+      for (const t of Array.isArray(r?.tools) ? r.tools : []) {
+        if (typeof t?.name !== "string" || !TOOL_NAME.test(t.name)) continue;
+        all.push({
+          name: t.name,
+          title: typeof t.title === "string" ? t.title : (t.annotations?.title ?? null),
+          category: categoryOf(t.name),
+          description: typeof t.description === "string" ? t.description : "",
+          risk: riskOf(t),
+          ...callPolicy(t),
+          inputSchema:
+            t.inputSchema && typeof t.inputSchema === "object" ? t.inputSchema : { type: "object" },
+        });
+      }
+      cursor = r?.nextCursor;
+      if (!cursor) break;
+    }
+    tools = all.sort((a, b) => (a.name < b.name ? -1 : 1));
+    return tools;
+  }
+
+  /** Call one tool after checking its arguments; the result redacted. */
+  async function callTool(name, args) {
+    if (typeof name !== "string" || !TOOL_NAME.test(name))
+      throw new ToolError("unknown-tool", "no such tool");
+    const tool = (await listTools()).find((t) => t.name === name);
+    if (!tool) throw new ToolError("unknown-tool", "no such tool");
+    if (!tool.allowed) throw new ToolError("tool-not-allowed", tool.reason);
+    const input = args ?? {};
+    const confirms = confirmPaths(input);
+    if (confirms.length) {
+      throw new ToolError("invalid-arguments", "confirm is not accepted here", {
+        errors: confirms.map(
+          (p) => `${p} is not allowed: a tool's own preview is never skipped from here`,
+        ),
+      });
+    }
+    const errors = schemaErrors(tool.inputSchema, input, "", { strict: true });
+    if (errors.length)
+      throw new ToolError(
+        "invalid-arguments",
+        "the arguments do not match the tool's inputSchema",
+        { errors },
+      );
+    const r = await rpc("tools/call", { name, arguments: input }, CALL_TIMEOUT_MS);
+    return renderResult(tool, r);
+  }
+
+  function close() {
+    failAll(new ToolError("closed", "the client was closed"));
+    if (child && child.exitCode === null) child.kill("SIGTERM");
+    child = null;
+    ready = null;
+    tools = null;
+  }
+
+  return {
+    listTools,
+    callTool,
+    close,
+    get started() {
+      return Boolean(child);
+    },
+  };
+}
+
+/** A tools/call result as text, JSON text and images, every text redacted. */
+export function renderResult(tool, result) {
+  const R = createRedactor();
+  const content = [];
+  for (const c of Array.isArray(result?.content) ? result.content : []) {
+    if (c?.type === "text") content.push({ kind: "text", text: R.clean(String(c.text ?? "")) });
+    else if (c?.type === "image" && IMAGE_TYPES.has(c.mimeType) && typeof c.data === "string") {
+      if (c.data.length * 0.75 <= MAX_IMAGE_BYTES)
+        content.push({ kind: "image", mime: c.mimeType, data: c.data });
+      else content.push({ kind: "text", text: "[image too large to show]" });
+    } else if (c?.type === "resource" && typeof c.resource?.text === "string") {
+      content.push({ kind: "text", text: R.clean(c.resource.text) });
+    } else if (c?.type)
+      content.push({ kind: "text", text: `[${String(c.type)} content not shown]` });
+  }
+  if (result?.structuredContent && typeof result.structuredContent === "object") {
+    content.push({
+      kind: "json",
+      text: R.clean(JSON.stringify(result.structuredContent, null, 2)),
+    });
+  }
+  return {
+    contractVersion: CONTRACT_VERSION,
+    tool: tool.name,
+    risk: tool.risk,
+    isError: result?.isError === true,
+    content,
+  };
+}
+
+async function main(argv) {
+  const [cmd, name, raw] = argv;
+  const client = createToolkitClient();
+  try {
+    let out;
+    if (cmd === "list" && !name) {
+      out = {
+        contractVersion: CONTRACT_VERSION,
+        version: activeToolkitVersion(),
+        tools: await client.listTools(),
+      };
+    } else if (cmd === "call" && name) {
+      let args = {};
+      if (raw !== undefined) {
+        try {
+          args = JSON.parse(raw);
+        } catch {
+          throw new ToolError("invalid-arguments", "the arguments are not JSON");
+        }
+      }
+      out = await client.callTool(name, args);
+    } else {
+      process.stderr.write("usage: toolkit-tools.mjs list | call <name> '<json arguments>'\n");
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return 0;
+  } catch (err) {
+    if (!(err instanceof ToolError)) throw err;
+    process.stderr.write(`toolkit-tools: ${err.message}\n`);
+    for (const e of err.extra?.errors ?? []) process.stderr.write(`  ${e}\n`);
+    return 1;
+  } finally {
+    client.close();
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("toolkit-tools", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/transcript-index.mjs

@@ -139,9 +139,12 @@ const TOKEN_CHAR = /[A-Za-z0-9_\-./+=:@~%]/;
  * `text` cut to `limit` characters, backed off to the start of a token that
  * the cut would split, so no half-credential survives on the boundary.
  */
+// The " ..." ending counts toward the limit, so a cut text is never longer
+// than the field that holds it.
 function cut(text, limit) {
   if (text.length <= limit) return text;
-  let end = limit;
+  if (limit < 5) return text.slice(0, limit);
+  let end = limit - 4;
   while (end > 0 && TOKEN_CHAR.test(text[end]) && TOKEN_CHAR.test(text[end - 1])) end--;
   return `${text.slice(0, end).trimEnd()} ...`;
 }

package/pipeline/scripts/uninstall.mjs

@@ -997,6 +997,7 @@ export async function main() {
     rmIfExists(join(CLAUDE, "multi-agent-refs"));
     rmIfExists(join(CLAUDE, ".pipeline-swap"));
     rmIfExists(join(CLAUDE, "schemas"));
+    rmIfExists(join(CLAUDE, "office"));
     if (!rmManifestFiles(CLAUDE, KEEP_IN_LIB)) {
       // An install that predates the manifest wiped lib/ and templates/ on
       // every run, so their shipped names are the pipeline's. The top-level
@@ -1053,6 +1054,7 @@ export async function main() {
     rmIfExists(join(COP, "scripts"));
     // Pipeline-managed trees the installer lays down alongside scripts/.
     rmIfExists(join(COP, "schemas"));
+    rmIfExists(join(COP, "office"));
     rmDirExcept(join(COP, "lib"), KEEP_IN_LIB);
     rmIfExists(join(COP, ".pipeline-version"));
     const skills = join(COP, "skills");
@@ -1164,6 +1166,7 @@ export async function main() {
     rmIfExists(join(CODEX, "scripts"));
     rmDirExcept(join(CODEX, "lib"), KEEP_IN_LIB);
     rmIfExists(join(CODEX, "schemas"));
+    rmIfExists(join(CODEX, "office"));
     rmIfExists(join(CODEX, "rules"));
     rmIfExists(join(CODEX, ".pipeline-version"));