causly-server 0.0.0-stage → 1.5.0

package/tools/supabaseOps.js

@@ -0,0 +1,94 @@
+const SUPABASE_API = "https://api.supabase.com/v1";
+
+function getToken() {
+  const token = process.env.SUPABASE_ACCESS_TOKEN;
+  if (!token) {
+    throw new Error(
+      "SUPABASE_ACCESS_TOKEN not set. Run `npm run setup` to configure it, or add it manually to your .env file: SUPABASE_ACCESS_TOKEN=sbp_..."
+    );
+  }
+  return token;
+}
+
+async function supabaseFetch(path, options = {}) {
+  const token = getToken();
+  const res = await fetch(`${SUPABASE_API}${path}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(options.body ? { "Content-Type": "application/json" } : {}),
+      ...options.headers,
+    },
+  });
+
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+
+  if (!res.ok) {
+    const message = data?.message || res.statusText;
+    throw new Error(`Supabase API error (${res.status}): ${message}`);
+  }
+
+  return data;
+}
+
+/** List organizations the authenticated account belongs to. Needed to create a new project. */
+export async function supabaseListOrganizations() {
+  const data = await supabaseFetch("/organizations");
+  return { organizations: data.map((o) => ({ id: o.id, name: o.name })) };
+}
+
+/** List projects for the authenticated account. */
+export async function supabaseListProjects() {
+  const data = await supabaseFetch("/projects");
+  return {
+    projects: data.map((p) => ({
+      id: p.id,
+      name: p.name,
+      region: p.region,
+      status: p.status,
+      organization_id: p.organization_id,
+    })),
+  };
+}
+
+/** Get details of a single project by its ref/ID. */
+export async function supabaseGetProject({ project_ref }) {
+  const data = await supabaseFetch(`/projects/${project_ref}`);
+  return { id: data.id, name: data.name, region: data.region, status: data.status };
+}
+
+/**
+ * Create a new Supabase project. Requires an organization_id
+ * (use supabase_list_organizations to find it) and a database password.
+ */
+export async function supabaseCreateProject({ name, organization_id, db_pass, region = "ap-south-1", plan = "free" }) {
+  const data = await supabaseFetch("/projects", {
+    method: "POST",
+    body: JSON.stringify({ name, organization_id, db_pass, region, plan }),
+  });
+  return { id: data.id, name: data.name, region: data.region, status: data.status };
+}
+
+/** Delete a Supabase project. */
+export async function supabaseDeleteProject({ project_ref }) {
+  await supabaseFetch(`/projects/${project_ref}`, { method: "DELETE" });
+  return { project_ref, deleted: true };
+}
+
+/**
+ * Run raw SQL against a project's database — the way to create tables,
+ * alter schema, seed data, or run arbitrary queries.
+ */
+export async function supabaseRunSql({ project_ref, query }) {
+  const data = await supabaseFetch(`/projects/${project_ref}/database/query`, {
+    method: "POST",
+    body: JSON.stringify({ query }),
+  });
+  return { project_ref, result: data };
+}

package/tools/telegramOps.js

@@ -0,0 +1,153 @@
+// Telegram Bot API tools. No new dependencies; a bot token is all that is needed.
+//
+//   telegram_get_me        check the bot token, show the bot's name
+//   telegram_get_updates   recent messages sent to the bot (also how you find a chat id)
+//   telegram_get_chat      details of one chat
+//   telegram_notify        send a message to YOUR chat (TELEGRAM_CHAT_ID): alerts, "lead replied"
+//   telegram_send_message  send a message to any chat (HIGH risk, needs confirm: true)
+//
+// Credentials: TELEGRAM_BOT_TOKEN (from @BotFather). TELEGRAM_CHAT_ID is the chat that
+// telegram_notify writes to; get it by messaging your bot and calling telegram_get_updates.
+import { UNTRUSTED_NOTICE } from "./webOps.js";
+
+const API = "https://api.telegram.org";
+const MAX_TEXT = 4096;
+const clamp = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+const CHAT_ID = /^(-?\d{1,20}|@[A-Za-z][A-Za-z0-9_]{4,31})$/;
+
+function token(env = process.env) {
+  const t = env.TELEGRAM_BOT_TOKEN;
+  if (!t) throw new Error("Telegram is not set up. Missing: TELEGRAM_BOT_TOKEN (create a bot with @BotFather and add the token to .env).");
+  return t;
+}
+
+const scrub = (text, t) => String(text).split(t).join("[REDACTED]");
+
+/** One Bot API call. Errors never contain the bot token. */
+async function call(method, params, deps = {}) {
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const t = token();
+  let res;
+  try {
+    res = await fetchFn(`${API}/bot${t}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(params ?? {}),
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch (err) {
+    throw new Error(`Could not reach Telegram: ${scrub(err.message, t)}`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (data.ok) return data.result;
+
+  const why = scrub(data.description || `HTTP ${res.status}`, t);
+  const code = data.error_code ?? res.status;
+  if (code === 401) throw new Error("Telegram rejected the bot token. Check TELEGRAM_BOT_TOKEN.");
+  if (code === 409) throw new Error("This bot has a webhook set, which blocks reading updates here. Remove the webhook (deleteWebhook) to use telegram_get_updates.");
+  if (code === 403) throw new Error(`Telegram refused: ${why}. For a person, they must open the bot and press Start first; for a group or channel, add the bot to it.`);
+  if (code === 429) {
+    const wait = data.parameters?.retry_after;
+    throw new Error(`Telegram rate limit hit${wait ? `; retry in ${wait}s` : ""}.`);
+  }
+  throw new Error(`Telegram error: ${why}`);
+}
+
+function checkChatId(id, label = "chat_id") {
+  const s = String(id ?? "").trim();
+  if (!CHAT_ID.test(s)) throw new Error(`${label} must be a number like 123456789 (groups are negative) or a channel like @mychannel.`);
+  return s;
+}
+
+function checkText(text) {
+  const s = String(text ?? "");
+  if (!s.trim()) throw new Error("text is required.");
+  if (s.length > MAX_TEXT) throw new Error(`text is ${s.length} characters; Telegram allows ${MAX_TEXT}. Shorten it or send it in parts.`);
+  return s;
+}
+
+const PARSE_MODES = ["HTML", "MarkdownV2"];
+
+async function send({ chat_id, text, reply_to_message_id, parse_mode, silent }, deps) {
+  const body = {
+    chat_id,
+    text: checkText(text),
+    disable_web_page_preview: true,
+    ...(silent ? { disable_notification: true } : {}),
+    ...(reply_to_message_id !== undefined ? { reply_parameters: { message_id: Number(reply_to_message_id), allow_sending_without_reply: true } } : {}),
+  };
+  if (parse_mode !== undefined) {
+    if (!PARSE_MODES.includes(parse_mode)) throw new Error("parse_mode must be HTML or MarkdownV2 (leave it out for plain text).");
+    body.parse_mode = parse_mode;
+  }
+  const m = await call("sendMessage", body, deps);
+  return { sent: true, chat_id: m.chat?.id, message_id: m.message_id, date: new Date(m.date * 1000).toISOString() };
+}
+
+// ---------------------------------------------------------------- tools
+
+export async function getMe(_input = {}, deps = {}) {
+  const me = await call("getMe", {}, deps);
+  return {
+    id: me.id,
+    username: me.username,
+    name: me.first_name,
+    can_join_groups: me.can_join_groups,
+    notify_chat_configured: Boolean(process.env.TELEGRAM_CHAT_ID),
+  };
+}
+
+const person = (u) => (u ? { id: u.id, ...(u.username ? { username: u.username } : {}), name: [u.first_name, u.last_name].filter(Boolean).join(" ") } : undefined);
+
+function simplifyUpdate(u) {
+  const m = u.message ?? u.channel_post;
+  if (!m) return { update_id: u.update_id, kind: "other" };
+  return {
+    update_id: u.update_id,
+    kind: u.message ? "message" : "channel_post",
+    message_id: m.message_id,
+    chat: { id: m.chat.id, type: m.chat.type, ...(m.chat.title ? { title: m.chat.title } : {}), ...(m.chat.username ? { username: m.chat.username } : {}) },
+    from: person(m.from),
+    date: new Date(m.date * 1000).toISOString(),
+    text: m.text ?? m.caption ?? (m.photo ? "[photo]" : m.document ? "[document]" : m.voice ? "[voice message]" : "[non-text message]"),
+  };
+}
+
+export async function getUpdates({ limit = 20, offset } = {}, deps = {}) {
+  const params = { limit: clamp(Math.trunc(Number(limit)) || 20, 1, 100), timeout: 0, allowed_updates: ["message", "channel_post"] };
+  if (offset !== undefined) params.offset = Math.trunc(Number(offset));
+  const raw = await call("getUpdates", params, deps);
+  const updates = raw.map(simplifyUpdate);
+  return {
+    count: updates.length,
+    updates,
+    ...(raw.length ? { next_offset: raw[raw.length - 1].update_id + 1 } : {}),
+    hint: "Pass next_offset as offset to mark these as read; they will not be returned again. Without offset they stay in the queue (kept for 24 hours).",
+    notice: UNTRUSTED_NOTICE,
+  };
+}
+
+export async function getChat({ chat_id } = {}, deps = {}) {
+  const c = await call("getChat", { chat_id: checkChatId(chat_id) }, deps);
+  return {
+    id: c.id,
+    type: c.type,
+    ...(c.title ? { title: c.title } : {}),
+    ...(c.username ? { username: c.username } : {}),
+    ...(c.first_name ? { name: [c.first_name, c.last_name].filter(Boolean).join(" ") } : {}),
+    ...(c.description ? { description: String(c.description).slice(0, 500) } : {}),
+    notice: UNTRUSTED_NOTICE,
+  };
+}
+
+/** Message to the owner's own chat. Cannot reach anyone else, so no confirmation is needed. */
+export async function notify({ text, silent, parse_mode } = {}, deps = {}) {
+  const chat = process.env.TELEGRAM_CHAT_ID;
+  if (!chat) throw new Error("TELEGRAM_CHAT_ID is not set. Message your bot, call telegram_get_updates to see your chat id, and add it to .env.");
+  return send({ chat_id: checkChatId(chat, "TELEGRAM_CHAT_ID"), text, silent, parse_mode }, deps);
+}
+
+/** Message to any chat. HIGH risk: the wrapper requires confirm: true. */
+export async function sendMessage({ chat_id, text, reply_to_message_id, parse_mode, silent, confirm } = {}, deps = {}) {
+  return send({ chat_id: checkChatId(chat_id), text, reply_to_message_id, parse_mode, silent }, deps);
+}

package/tools/terminal.js

@@ -0,0 +1,124 @@
+// Small interactive prompts for `causly-server setup` and `keys set`.
+// In a real terminal: raw key input, so a pasted secret shows as * and never echoes.
+// Piped input (scripts, CI): plain lines, so `echo $KEY | causly-server keys set NAME` works.
+
+export class Cancelled extends Error {
+  constructor() {
+    super("Cancelled.");
+    this.name = "Cancelled";
+  }
+}
+
+export function createTerminal({ input = process.stdin, output = process.stdout } = {}) {
+  const tty = Boolean(input.isTTY && typeof input.setRawMode === "function");
+
+  // ---- non-interactive: queue of lines
+  const queue = [];
+  const waiters = [];
+  let ended = false;
+  let pending = "";
+  const pushLine = (line) => {
+    const w = waiters.shift();
+    if (w) w(line);
+    else queue.push(line);
+  };
+  const onData = (chunk) => {
+    pending += chunk;
+    let i;
+    while ((i = pending.search(/\r?\n/)) !== -1) {
+      pushLine(pending.slice(0, i));
+      pending = pending.slice(pending.indexOf("\n", i) + 1);
+    }
+  };
+  const onEnd = () => {
+    ended = true;
+    if (pending) pushLine(pending);
+    pending = "";
+    while (waiters.length) waiters.shift()(null);
+  };
+  let piped = false;
+  const startPiped = () => {
+    if (piped) return;
+    piped = true;
+    input.setEncoding?.("utf8");
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.resume?.();
+  };
+  const nextLine = () => {
+    startPiped();
+    if (queue.length) return Promise.resolve(queue.shift());
+    if (ended) return Promise.resolve(null);
+    return new Promise((resolve) => waiters.push(resolve));
+  };
+
+  // ---- interactive: one raw-mode read
+  const readRaw = (secret) =>
+    new Promise((resolve, reject) => {
+      let value = "";
+      input.setRawMode(true);
+      input.setEncoding?.("utf8");
+      input.resume();
+      const finish = (fn, arg) => {
+        input.removeListener("data", onKey);
+        input.setRawMode(false);
+        input.pause?.();
+        output.write("\n");
+        fn(arg);
+      };
+      const onKey = (chunk) => {
+        const s = String(chunk);
+        if (s.startsWith("\u001b")) return; // arrow keys and other escape sequences
+        for (const ch of s) {
+          if (ch === "\r" || ch === "\n") return finish(resolve, value);
+          if (ch === "\u0003") return finish(reject, new Cancelled()); // Ctrl+C
+          if (ch === "\u0004" && !value) return finish(reject, new Cancelled()); // Ctrl+D on an empty line
+          if (ch === "\u007f" || ch === "\b") {
+            if (value) {
+              value = value.slice(0, -1);
+              output.write("\b \b");
+            }
+            continue;
+          }
+          if (ch < " ") continue;
+          value += ch;
+          output.write(secret ? "*" : ch);
+        }
+      };
+      input.on("data", onKey);
+    });
+
+  const ask = async (question, { secret = false } = {}) => {
+    output.write(question);
+    if (tty) return readRaw(secret);
+    const line = await nextLine();
+    output.write("\n");
+    if (line === null) throw new Cancelled();
+    return line;
+  };
+
+  return {
+    interactive: tty,
+    write: (text) => output.write(text),
+    line: (question) => ask(question),
+    secret: (question) => ask(question, { secret: true }),
+    /** Yes/no. Enter picks the default. */
+    async confirm(question, defaultYes = true) {
+      const a = (await ask(`${question} ${defaultYes ? "(Y/n) " : "(y/N) "}`)).trim().toLowerCase();
+      if (!a) return defaultYes;
+      return a === "y" || a === "yes";
+    },
+    /** Reads whatever is piped in (first line), for `keys set` in scripts. */
+    async readPipedLine() {
+      const line = await nextLine();
+      return line === null ? "" : line;
+    },
+    close() {
+      if (piped) {
+        input.removeListener("data", onData);
+        input.removeListener("end", onEnd);
+        input.pause?.();
+      }
+    },
+  };
+}

package/tools/terraformOps.js

@@ -0,0 +1,171 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as githubOps from "./githubOps.js";
+
+const execFileAsync = promisify(execFile);
+
+async function runTerraform(args, cwd, timeout_ms = 120000) {
+  try {
+    const { stdout, stderr } = await execFileAsync("terraform", args, {
+      cwd,
+      timeout: timeout_ms,
+      maxBuffer: 1024 * 1024 * 20,
+    });
+    return { stdout, stderr, exit_code: 0 };
+  } catch (err) {
+    return {
+      stdout: err.stdout || "",
+      stderr: err.stderr || err.message,
+      exit_code: err.code ?? 1,
+    };
+  }
+}
+
+/** Initialize a Terraform working directory (downloads providers/modules). */
+export async function terraformInit({ dir, upgrade = false }) {
+  const args = ["init", "-no-color"];
+  if (upgrade) args.push("-upgrade");
+  return runTerraform(args, dir);
+}
+
+/** Validate the configuration's syntax and internal consistency. */
+export async function terraformValidate({ dir }) {
+  return runTerraform(["validate", "-no-color", "-json"], dir);
+}
+
+/** Format .tf files to canonical style. */
+export async function terraformFmt({ dir, check = false }) {
+  const args = ["fmt", "-no-color"];
+  if (check) args.push("-check");
+  return runTerraform(args, dir);
+}
+
+/** Show an execution plan: what Terraform would change. */
+export async function terraformPlan({ dir, var_file, out }) {
+  const args = ["plan", "-no-color", "-input=false"];
+  if (var_file) args.push(`-var-file=${var_file}`);
+  if (out) args.push(`-out=${out}`);
+  return runTerraform(args, dir, 300000);
+}
+
+/** Apply changes to reach the desired state. HIGH risk — requires confirm: true. */
+export async function terraformApply({ dir, var_file, plan_file, confirm }) {
+  const args = ["apply", "-no-color", "-input=false", "-auto-approve"];
+  if (plan_file) {
+    args.push(plan_file);
+  } else if (var_file) {
+    args.push(`-var-file=${var_file}`);
+  }
+  return runTerraform(args, dir, 600000);
+}
+
+/** Destroy all resources managed by this configuration. HIGH risk — requires confirm: true. */
+export async function terraformDestroy({ dir, var_file, confirm }) {
+  const args = ["destroy", "-no-color", "-input=false", "-auto-approve"];
+  if (var_file) args.push(`-var-file=${var_file}`);
+  return runTerraform(args, dir, 600000);
+}
+
+/** Show the current state or a saved plan, human-readable or as JSON. */
+export async function terraformShow({ dir, target, json = false }) {
+  const args = ["show", "-no-color"];
+  if (json) args.push("-json");
+  if (target) args.push(target);
+  return runTerraform(args, dir);
+}
+
+/** Read output values from the root module's state. */
+export async function terraformOutput({ dir, name, json = true }) {
+  const args = ["output", "-no-color"];
+  if (json) args.push("-json");
+  if (name) args.push(name);
+  return runTerraform(args, dir);
+}
+
+/** Manage Terraform workspaces (environments like dev/staging/prod). action: 'list' | 'new' | 'select' | 'delete' (defaults to list). */
+export async function terraformWorkspace({ dir, action = "list", name }) {
+  if (action === "list") return runTerraform(["workspace", "list", "-no-color"], dir);
+  if (action === "new") return runTerraform(["workspace", "new", "-no-color", name], dir);
+  if (action === "select") return runTerraform(["workspace", "select", "-no-color", name], dir);
+  if (action === "delete") return runTerraform(["workspace", "delete", "-no-color", name], dir);
+  throw new Error(`Unknown workspace action: ${action}`);
+}
+
+/** List all resources tracked in the current state. */
+export async function terraformStateList({ dir, filter }) {
+  const args = ["state", "list", "-no-color"];
+  if (filter) args.push(filter);
+  return runTerraform(args, dir);
+}
+
+/** Show detailed attributes of a single resource in the state. */
+export async function terraformStateShow({ dir, address }) {
+  return runTerraform(["state", "show", "-no-color", address], dir);
+}
+
+/** Move a resource to a new address within the state (rename/refactor without destroy+recreate). HIGH risk — requires confirm: true. */
+export async function terraformStateMv({ dir, source, destination, confirm }) {
+  return runTerraform(["state", "mv", "-no-color", source, destination], dir);
+}
+
+/** Remove a resource from the state without destroying the real infrastructure (stops Terraform managing it). HIGH risk — requires confirm: true. */
+export async function terraformStateRm({ dir, address, confirm }) {
+  return runTerraform(["state", "rm", "-no-color", address], dir);
+}
+
+/** Download and print the raw remote state as JSON — useful for backend/state-drift inspection. */
+export async function terraformStatePull({ dir }) {
+  return runTerraform(["state", "pull"], dir);
+}
+
+/** Import an existing real-world resource into Terraform state, so it becomes managed by this config. HIGH risk — requires confirm: true. */
+export async function terraformImport({ dir, address, resource_id, var_file, confirm }) {
+  const args = ["import", "-no-color", "-input=false"];
+  if (var_file) args.push(`-var-file=${var_file}`);
+  args.push(address, resource_id);
+  return runTerraform(args, dir, 300000);
+}
+
+/** Mark a resource as tainted, forcing it to be destroyed and recreated on the next apply. HIGH risk — requires confirm: true. */
+export async function terraformTaint({ dir, address, confirm }) {
+  return runTerraform(["taint", "-no-color", address], dir);
+}
+
+/** Remove the tainted mark from a resource, so it will not be forcibly recreated. */
+export async function terraformUntaint({ dir, address }) {
+  return runTerraform(["untaint", "-no-color", address], dir);
+}
+
+/** Generate a visual dependency graph of resources in DOT format. */
+export async function terraformGraph({ dir }) {
+  return runTerraform(["graph"], dir);
+}
+
+/** List the providers required by the configuration and their resolved versions. */
+export async function terraformProviders({ dir }) {
+  return runTerraform(["providers"], dir);
+}
+
+/**
+ * CI/CD hook: run `terraform plan`, format a concise Markdown summary, and post it
+ * as a comment on a GitHub pull request — so reviewers see the infra diff before approving.
+ * HIGH risk — requires confirm: true.
+ */
+export async function terraformPlanComment({ dir, var_file, owner, repo, pull_number, confirm }) {
+  const args = ["plan", "-no-color", "-input=false", "-detailed-exitcode"];
+  if (var_file) args.push(`-var-file=${var_file}`);
+  const planResult = await runTerraform(args, dir, 300000);
+
+  // -detailed-exitcode: 0 = no changes, 1 = error, 2 = changes present. Both 0 and 2 are "success" runs.
+  const hadError = planResult.exit_code !== 0 && planResult.exit_code !== 2;
+
+  const status = hadError ? "❌ Plan failed" : planResult.exit_code === 0 ? "✅ No changes" : "📋 Plan has changes";
+  const body =
+    `### Terraform Plan — ${status}\n\n` +
+    "<details><summary>Show plan output</summary>\n\n```\n" +
+    (hadError ? planResult.stderr : planResult.stdout).slice(0, 60000) +
+    "\n```\n</details>";
+
+  const comment = await githubOps.githubAddComment({ owner, repo, issue_number: pull_number, body });
+  return { plan_exit_code: planResult.exit_code, had_error: hadError, comment_url: comment.html_url };
+}

package/tools/toolWrapper.js

@@ -0,0 +1,60 @@
+import crypto from "crypto";
+import { checkApproval } from "./security.js";
+import { logActivity } from "./logger.js";
+import { checkWorkspace } from "./workspace.js";
+import { emitBoundaryAttestReceipt } from "./boundaryAttest.js";
+import { reloadEnvIfChanged } from "./envLoader.js";
+import { setupHint } from "./services.js";
+
+function reportAttestationFailure(toolName, operationId, err) {
+  console.error(`BoundaryAttest error for ${toolName} (${operationId}): ${err.message}`);
+}
+
+export function createToolWrapper({
+  approvalCheck = checkApproval,
+  workspaceCheck = checkWorkspace,
+  activityLogger = logActivity,
+  receiptEmitter = emitBoundaryAttestReceipt,
+  operationIdFactory = () => crypto.randomUUID(),
+  attestationErrorReporter = reportAttestationFailure,
+  envRefresher = reloadEnvIfChanged,
+  errorHinter = setupHint,
+} = {}) {
+  return function wrap(toolName, handler) {
+    return async (input) => {
+      try { envRefresher(); } catch { /* a settings-file problem must never block a tool */ }
+      const operationId = operationIdFactory();
+      const attest = (evidence) => {
+        try { receiptEmitter({ toolName, input, operationId, ...evidence }); }
+        catch (err) { attestationErrorReporter(toolName, operationId, err); }
+      };
+      const workspace = workspaceCheck(toolName, input);
+      if (!workspace.allowed) {
+        activityLogger(toolName, input, "BLOCKED", workspace.reason, null, operationId);
+        attest({ status: "BLOCKED", error: workspace.reason });
+        return { content: [{ type: "text", text: `Blocked: ${workspace.reason}` }], isError: true };
+      }
+      const approval = approvalCheck(toolName, input);
+      if (!approval.allowed) {
+        activityLogger(toolName, input, "BLOCKED", approval.reason, null, operationId);
+        attest({ status: "BLOCKED", error: approval.reason });
+        return { content: [{ type: "text", text: `Blocked: ${approval.reason}` }], isError: true };
+      }
+      const startedAt = Date.now();
+      try {
+        const result = await handler(input);
+        activityLogger(toolName, input, "SUCCESS", "", Date.now() - startedAt, operationId);
+        attest({ status: "SUCCESS", result });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        activityLogger(toolName, input, "ERROR", err.message, Date.now() - startedAt, operationId);
+        attest({ status: "ERROR", error: err.message });
+        let hint = null;
+        try { hint = errorHinter(err.message); } catch { /* hint is optional */ }
+        return { content: [{ type: "text", text: `Error: ${err.message}${hint ? `\n${hint}` : ""}` }], isError: true };
+      }
+    };
+  };
+}
+
+export const wrap = createToolWrapper();