@oalo-ai/cli 0.0.0-stage → 0.1.0

package/src/mcp/tools.js

@@ -0,0 +1,773 @@
+import { readToken } from "../config.js";
+import { listModels, listRows, getRow, pushRows, deleteRows, routes, toRows, writeTokenFor, createModel, promoteModel, parseFields } from "../data.js";
+
+/**
+ * Curated MCP tools over BuilderChannel.
+ *
+ * BuilderChannel exposes ~442 events. Mapping them 1:1 would be unusable: the
+ * schemas alone would flood an agent's context and wreck tool selection. So a
+ * small task-shaped set covers the common work, and `oalo_call` stays as a
+ * gated passthrough for the long tail.
+ *
+ * Every `event`/params pairing below was read off the handler's own pattern
+ * match, so required params are the real ones, not guesses.
+ */
+
+const S = (props, required = []) => ({
+  type: "object",
+  properties: props,
+  required,
+  additionalProperties: false,
+});
+
+export const TOOLS = [
+  {
+    name: "oalo_describe",
+    description:
+      "Overview of this OALO workspace: apps, chatbots, and loops. Call this first: everything else needs an id from here.",
+    inputSchema: S({}),
+    composite: true,
+  },
+  {
+    name: "oalo_list_apps",
+    description: "List the apps in this workspace.",
+    inputSchema: S({}),
+    event: "list_apps",
+  },
+  {
+    name: "oalo_list_bots",
+    description: "List the chatbots in this workspace, with their public ids.",
+    inputSchema: S({}),
+    event: "chat:bots:list",
+  },
+  {
+    name: "oalo_get_bot",
+    description:
+      "Full configuration for one chatbot: persona, frame, retrieval settings, guardrails.",
+    inputSchema: S({ id: { type: "string", description: "Bot id" } }, ["id"]),
+    event: "chat:bots:get",
+  },
+  {
+    name: "oalo_list_flows",
+    description: "List a bot's conversational flows.",
+    inputSchema: S({ bot_id: { type: "string" } }, ["bot_id"]),
+    event: "chat:bots:flows:list",
+  },
+  {
+    name: "oalo_get_flow",
+    description: "One flow's full graph: nodes and edges.",
+    inputSchema: S({ id: { type: "string", description: "Flow id" } }, ["id"]),
+    event: "chat:bots:flows:get",
+  },
+  {
+    name: "oalo_node_catalog",
+    description:
+      "The exact JSON contract for a chat flow or a loop: every node type, the keys each one reads (required, defaults, allowed values), what each outputs, and the edge, condition and {{reference}} rules. Read this before writing or editing a flow or loop graph instead of guessing keys.",
+    inputSchema: S({ surface: { type: "string", enum: ["flow", "loop"] } }, ["surface"]),
+    route: (args) => ({
+      event: args.surface === "loop" ? "loops:node_catalog" : "chat:flows:node_catalog",
+      params: {},
+    }),
+  },
+  {
+    name: "oalo_save_flow",
+    description:
+      "Create or update a flow. MUTATES the live workspace. Call oalo_get_flow first: `graph` REPLACES the stored graph wholesale, so send every node and edge you want to keep, not a patch. Pass the `version` you read back as `base_version`. Without it a concurrent edit is silently overwritten; with it you get a `conflict` error and should re-read and merge. `strict` defaults to true here: the save is refused (code `invalid_graph`, with findings) while the graph has any error-level lint finding. Check with oalo_lint_flow first.",
+    inputSchema: S(
+      {
+        bot_id: { type: "string", description: "Numeric id or public bot id (bot_...)" },
+        id: { type: "string", description: "Omit to create a new flow" },
+        name: { type: "string" },
+        description: { type: "string" },
+        enabled: { type: "boolean", description: "Omit to keep an existing flow's state. A new flow saved without it starts off." },
+        // The server reads params["graph"], NOT top-level nodes/edges. Getting
+        // this wrong writes an EMPTY graph over a real flow without erroring.
+        graph: {
+          type: "object",
+          description: "The whole graph. Replaces what is stored.",
+          properties: {
+            nodes: { type: "array", items: { type: "object" } },
+            edges: { type: "array", items: { type: "object" } },
+            entry: { type: ["string", "null"], description: "Entry node id" },
+          },
+        },
+        // The server now accepts `version` as a fallback, so echoing the read
+        // field back works too. Still sent explicitly here: `base_version` wins
+        // when both are present, and being explicit says what it means.
+        base_version: {
+          type: "number",
+          description: "The `version` field from oalo_get_flow. Enables the conflict check.",
+        },
+        strict: {
+          type: "boolean",
+          description: "Refuse the save on any error-level lint finding (default true). false only blocks structural damage.",
+        },
+      },
+      ["bot_id"],
+    ),
+    event: "chat:bots:flows:upsert",
+    defaults: { strict: true },
+    mutates: true,
+  },
+  {
+    name: "oalo_lint_flow",
+    description:
+      "Check a flow without saving anything. Pass `graph` (+ `bot_id` so tool checks see that bot's tools) to check a DRAFT before oalo_save_flow, or `flow_id` to check a saved flow. Returns findings with severity error / warning / info, each with the node, what is wrong and how to fix it.",
+    inputSchema: S({
+      graph: { type: "object", description: "A draft graph {nodes, edges, entry}." },
+      bot_id: { type: "string", description: "With graph: the bot whose tools the flow calls." },
+      flow_id: { type: "string", description: "Check a saved flow instead." },
+    }),
+    event: "chat:flows:lint",
+  },
+  {
+    name: "oalo_lint_loop",
+    description:
+      "Check a loop without saving anything. Pass `nodes` + `edges` (and `name`) to check a DRAFT, or only `name` to check a saved loop. Tool checks use the org tool catalog.",
+    inputSchema: S({
+      name: { type: "string" },
+      nodes: { type: "array", items: { type: "object" } },
+      edges: { type: "array", items: { type: "object" } },
+      entry: { type: "string" },
+    }),
+    event: "loops:lint",
+  },
+  {
+    name: "oalo_flow_runs",
+    description:
+      "Recent flow runs on a bot, newest first: what actually executed, and where it stopped. Pass flow_id for one flow's runs. With run_id: that run step by step, with each step's input and output. Read-only.",
+    inputSchema: S(
+      {
+        bot_id: { type: "string", description: "Numeric id or public bot id (bot_...)" },
+        flow_id: { type: "string" },
+        run_id: { type: "number", description: "One run's steps (bot_id is then not needed)" },
+        limit: { type: "number", description: "At most 100" },
+      },
+      [],
+    ),
+    route: ({ run_id, ...p }) => (run_id != null ? { event: "chat:flows:get_run", params: { run_id } } : { event: "chat:flows:list_runs", params: p }),
+  },
+  {
+    name: "oalo_list_functions",
+    description: "Custom WASM functions (tools) defined in this workspace.",
+    inputSchema: S({}),
+    event: "fn:list_org",
+  },
+  {
+    name: "oalo_list_loops",
+    description: "Automation loops for this org. Loops are org-scoped, not per-app.",
+    inputSchema: S({}),
+    event: "loops:list_for_org",
+  },
+  {
+    name: "oalo_get_loop",
+    description:
+      "One loop's full definition by name: settings, `entry`, `nodes`, `edges`, and the `version` to send back as `base_version` when saving. Pass `app_id` only for a loop pinned to one app.",
+    inputSchema: S({ name: { type: "string" }, app_id: { type: "string" } }, ["name"]),
+    event: "loops:get",
+  },
+  {
+    name: "oalo_save_loop",
+    description:
+      "Create or update a loop by name. MUTATES the live workspace. Call oalo_get_loop first: the save REPLACES the whole definition, so send every node, edge and setting you want to keep. `nodes`, `edges` and `entry` sit at the TOP LEVEL (not under `graph`). Pass the `version` you read as `base_version`: without it a concurrent edit is overwritten. `strict` defaults to true: the save is refused (code `invalid_graph`, with findings) while any error-level lint finding remains. Check with oalo_lint_loop first; the contract is oalo_node_catalog surface=loop. Triggers are separate: oalo_loop_triggers.",
+    inputSchema: S(
+      {
+        name: { type: "string", description: "snake_case; the loop's identity" },
+        create: { type: "boolean", description: "true for a new loop (loops:create), else an update" },
+        description: { type: "string" },
+        enabled: { type: "boolean", description: "Omit to keep an existing loop's state. A new loop saved without it starts off." },
+        nodes: { type: "array", items: { type: "object" } },
+        edges: { type: "array", items: { type: "object" } },
+        entry: { type: "string", description: "The node runs start at (optional)" },
+        cron: { type: "string", description: "Run on this UTC schedule (optional)" },
+        max_iterations: { type: "number" },
+        max_cost_usd: { type: "number" },
+        session_mode: { type: "string", enum: ["recursive", "persistent"] },
+        provider: { type: "string", enum: ["anthropic", "opencode"] },
+        model: { type: "string" },
+        base_version: { type: "number", description: "The `version` from oalo_get_loop. Enables the conflict check." },
+        strict: { type: "boolean", description: "Refuse the save on any error-level lint finding (default true)." },
+      },
+      ["name", "nodes"],
+    ),
+    route: (args) => {
+      const { create, ...params } = args;
+      return { event: create ? "loops:create" : "loops:update", params: { strict: true, ...params } };
+    },
+    mutates: true,
+  },
+  {
+    name: "oalo_loop_triggers",
+    description:
+      "What starts a loop. action=catalog lists the trigger types and every event with its input fields; action=list shows a loop's triggers; action=add attaches one (`type` event|scheduled|exit|date_field|widget_submit|api, plus `event`, `cron`, `filter`, `batch_size` or `widget_id`; for api, `description`, `input` and `output`, so an app can call the loop at POST /api/workflows/v1/<name>/run). `event` takes a catalog event, an `app.*` name (fine before the app first sends it), `data.<table>.created|updated` (fires once `oalo data events <table>` is on) or `source.<name>.received`; action=remove detaches one by `trigger_id`; action=set_enabled turns one on or off (`trigger_id`, `enabled`) and keeps it. add, remove and set_enabled MUTATE the workspace.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["catalog", "list", "add", "remove", "set_enabled"] },
+        name: { type: "string", description: "The loop (list, add, remove, set_enabled)" },
+        type: { type: "string", enum: ["event", "scheduled", "exit", "date_field", "widget_submit", "api"] },
+        event: { type: "string" },
+        cron: { type: "string" },
+        filter: { type: "object", description: "Top-level payload equality, e.g. {\"channel\": \"instagram\"}" },
+        batch_size: { type: "number" },
+        widget_id: { type: "string" },
+        description: { type: "string", description: "api: what the call does, for the app's developer" },
+        input: { type: "object", description: "api: the fields the app sends, name to a type or {type, required, description}" },
+        output: { type: "object", description: "api: the fields the Output step returns" },
+        trigger_id: { type: "string" },
+        enabled: { type: "boolean", description: "set_enabled: on or off" },
+      },
+      ["action"],
+    ),
+    route: ({ action, ...params }) => ({ event: `loops:triggers:${action}`, params }),
+    mutates: true,
+  },
+  {
+    name: "oalo_test_loop",
+    description:
+      "Test a loop and get each step's output. Every step runs, but steps that send messages or change records (email, WhatsApp, SMS, CRM, bookings) are simulated: their output says what they would have done. Custom tools and AI steps run for real. Works on a loop that is off. Input: `sample` \"latest\" uses the loop's most recent real event, \"example\" builds one from its trigger's fields, or pass `input` yourself (an event envelope {type, contact_id, payload}, or the fields a scheduled loop's first step reads); none for a manual or scheduled loop. Waits for the run, up to 3 minutes. Test after every change, before turning a loop on.",
+    inputSchema: S(
+      {
+        name: { type: "string" },
+        sample: { type: "string", enum: ["latest", "example"] },
+        input: { type: "object" },
+        app_id: { type: "string", description: "Only for a loop pinned to one app: that app's id" },
+      },
+      ["name"],
+    ),
+    event: "loops:test",
+    timeoutMs: () => 200_000,
+  },
+  {
+    name: "oalo_set_loop_enabled",
+    description:
+      "Turn a loop on or off without sending its definition. MUTATES the live workspace: a loop that is on runs for real whenever its triggers fire. A new or changed loop stays off until the person says to turn it on; turning one off is safe when asked.",
+    inputSchema: S({ name: { type: "string" }, enabled: { type: "boolean" }, app_id: { type: "string", description: "Only for a loop pinned to one app" } }, ["name", "enabled"]),
+    event: "loops:set_enabled",
+    mutates: true,
+  },
+  {
+    name: "oalo_run_loop_now",
+    description:
+      "Start a loop run now, for real, without waiting for its trigger. MUTATES: its steps send real messages and change real records. To check what a loop does, use oalo_test_loop instead; run one now only when the person asks.",
+    inputSchema: S({ name: { type: "string" }, app_id: { type: "string" }, env: { type: "string", enum: ["dev", "prod"] } }, ["name"]),
+    event: "loops:run_now",
+    mutates: true,
+  },
+  {
+    name: "oalo_delete_loop",
+    description: "Delete a loop. MUTATES the live workspace and can't be undone: it stops firing, and runs in progress finish. Only when the person asks; to stop a loop, turning it off (oalo_set_loop_enabled) keeps it.",
+    inputSchema: S({ name: { type: "string" }, app_id: { type: "string" } }, ["name"]),
+    event: "loops:delete",
+    mutates: true,
+  },
+  {
+    name: "oalo_set_flow_enabled",
+    description:
+      "Turn a chat flow on or off without sending its graph. `flow` is its name or id. MUTATES the live workspace: a flow that is on can start in real conversations (and a call_other_flow step only runs a flow that is on). A new or changed customer-facing flow stays off until the person says to turn it on; a manual helper flow you created for a call_other_flow step must be on to work.",
+    inputSchema: S({ bot_id: { type: "string", description: "The bot's public id" }, flow: { type: "string" }, enabled: { type: "boolean" } }, ["bot_id", "flow", "enabled"]),
+    event: "chat:bots:flows:set_enabled",
+    mutates: true,
+  },
+  {
+    name: "oalo_delete_flow",
+    description: "Delete a chat flow by name or id. MUTATES the live workspace and can't be undone. Only when the person asks; turning it off (oalo_set_flow_enabled) keeps it. Check first that no other flow calls it (call_other_flow).",
+    inputSchema: S({ bot_id: { type: "string", description: "The bot's public id" }, flow: { type: "string" } }, ["bot_id", "flow"]),
+    event: "chat:bots:flows:delete",
+    mutates: true,
+  },
+  {
+    name: "oalo_loop_runs",
+    description:
+      "What a loop actually did. Without run_id: recent runs, newest first (status, trigger, cost, error, final output); `name` narrows to one loop. With run_id: that run step by step, with each step's input and output, and its events. Read this when a loop misbehaved or did nothing. Test runs are included unless hide_tests is true. Read-only.",
+    inputSchema: S({
+      name: { type: "string", description: "Only this loop's runs" },
+      run_id: { type: "number", description: "One run's steps" },
+      limit: { type: "number", description: "At most this many runs (default and cap 100)" },
+      hide_tests: { type: "boolean" },
+      app_id: { type: "string", description: "Only a loop pinned to this app (two apps can each have a loop of one name)" },
+    }),
+    route: ({ run_id, name, limit, hide_tests, app_id }) =>
+      run_id != null
+        ? { event: "loops:get_run", params: { run_id } }
+        : { event: "loops:list_runs_for_org", params: { ...(name ? { name } : {}), ...(app_id ? { app_id } : {}), ...(limit ? { limit } : {}), ...(hide_tests ? { hide_rehearsals: true } : {}) } },
+  },
+  {
+    name: "oalo_get_conversation",
+    description:
+      "One conversation, whole: its messages, the tools the bot called, and the flow runs in it with their steps. Use it to see why a flow did what it did in a real conversation (ids from oalo_flow_runs or the inbox). It holds real customers' messages: read only what the task needs, and don't copy their details elsewhere. Read-only.",
+    inputSchema: S({ id: { type: "string", description: "The conversation id" } }, ["id"]),
+    event: "chat:bots:conversations:get",
+  },
+  {
+    name: "oalo_widgets",
+    description:
+      "The workspace's widgets: the forms and components a flow shows (a flow node names one by id) and that can have their own link. action=list (id, name, kind, fields); get (one, with its full field list); templates (what can be copied in); copy (from a template's `template_key`, or another widget's `source_id`); create (`name`, `kind`, `fields` [{name, type, label, required}], `events`, `upsert_contact`, `target_table`, custom_html/custom_css/component_source); update (`id` plus what changes; `fields` REPLACES the whole list, so get it first and send it all back); assign (`id`, `bot_id`: lets that bot's chat and flows use it). Submitting a widget fires widget.submitted, which can start loops. copy, create, update and assign MUTATE the workspace.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["list", "get", "templates", "copy", "create", "update", "assign"] },
+        id: { type: "string" },
+        bot_id: { type: "string" },
+        template_key: { type: "string" },
+        source_id: { type: "string" },
+        name: { type: "string" },
+        kind: { type: "string" },
+        fields: { type: "array", items: { type: "object" } },
+        events: { type: "array", items: { type: "string" } },
+        upsert_contact: { type: "boolean" },
+        target_table: { type: "string" },
+        active: { type: "boolean" },
+        custom_html: { type: "string" },
+        custom_css: { type: "string" },
+        component_source: { type: "string" },
+      },
+      ["action"],
+    ),
+    route: ({ action, id, bot_id, ...rest }) => {
+      if (action === "list") return { event: "widgets:list", params: {} };
+      if (action === "templates") return { event: "widgets:templates", params: {} };
+      if (action === "get") return { event: "widgets:get", params: { id } };
+      if (action === "assign") return { event: "widgets:assign", params: { widget_id: id, bot_id } };
+      if (action === "copy") return { event: "widgets:copy", params: rest.source_id ? { source_id: rest.source_id, ...(rest.name ? { name: rest.name } : {}) } : { template_key: rest.template_key, ...(rest.name ? { name: rest.name } : {}) } };
+      if (action === "update") return { event: "widgets:update", params: { id, ...rest } };
+      return { event: "widgets:create", params: rest };
+    },
+    mutates: true,
+  },
+  {
+    name: "oalo_wa_templates",
+    description:
+      "WhatsApp message templates: the approved messages a loop sends outside WhatsApp's 24-hour reply window (a send_whatsapp step names one). action=channels lists the workspace's WhatsApp numbers; list shows every template with its approval status (or one channel's with `channel_id`); create saves a draft (`channel_id`, `name` lowercase_with_underscores, `language` e.g. es or en_US, `category` MARKETING|UTILITY|AUTHENTICATION, `components` in Meta's format); submit sends a draft (`template_id`) to Meta for review. Submitting is seen by Meta and can't be taken back: ask the person first. create and submit MUTATE.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["channels", "list", "create", "submit"] },
+        channel_id: { type: "string" },
+        template_id: { type: "string" },
+        name: { type: "string" },
+        language: { type: "string" },
+        category: { type: "string", enum: ["MARKETING", "UTILITY", "AUTHENTICATION"] },
+        components: { type: "array", items: { type: "object" } },
+      },
+      ["action"],
+    ),
+    route: ({ action, ...p }) =>
+      action === "channels"
+        ? { event: "chat:bots:wa_templates:channels", params: {} }
+        : action === "list"
+          ? p.channel_id
+            ? { event: "chat:bots:wa_templates:for_channel", params: { channel_id: p.channel_id } }
+            : { event: "chat:bots:wa_templates", params: {} }
+          : action === "submit"
+            ? { event: "chat:bots:wa_templates:submit", params: { template_id: p.template_id } }
+            : { event: "chat:bots:wa_templates:create", params: { ...p, submit: false } },
+    mutates: true,
+  },
+  {
+    name: "oalo_pipelines",
+    description:
+      "Sales pipelines and their stages, which loop steps that move deals refer to. action=list (every pipeline with its stage ids); create_pipeline (`name`, optional `stages` [names]); create_stage (`pipeline_id`, `name`, optional `position`, `win_probability` 0-100, `is_won`, `is_lost`). The create actions MUTATE.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["list", "create_pipeline", "create_stage"] },
+        pipeline_id: { type: "string" },
+        name: { type: "string" },
+        stages: { type: "array", items: { type: "string" } },
+        position: { type: "number" },
+        win_probability: { type: "number" },
+        is_won: { type: "boolean" },
+        is_lost: { type: "boolean" },
+      },
+      ["action"],
+    ),
+    route: ({ action, ...p }) =>
+      action === "list"
+        ? { event: "opportunities:pipelines", params: {} }
+        : action === "create_pipeline"
+          ? { event: "opportunities:create_pipeline", params: { name: p.name, ...(p.stages ? { stages: p.stages } : {}) } }
+          : { event: "opportunities:create_stage", params: p },
+    mutates: true,
+  },
+  {
+    name: "oalo_loop_docs",
+    description:
+      "Loop documents: named markdown notes kept per app that loops read and write as they run (a running summary, a list built up over runs). action=list (`app_id`); read (`app_id`, `name`: content and version); write (`app_id`, `name`, `content`, `mode` replace|append; pass the `expected_version` you read to a replace so a newer write isn't overwritten); delete (`app_id`, `name`: the document and its history, for good; only when the person asks). App ids: oalo_list_apps. write and delete MUTATE.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["list", "read", "write", "delete"] },
+        app_id: { type: "string" },
+        name: { type: "string" },
+        content: { type: "string" },
+        mode: { type: "string", enum: ["replace", "append"] },
+        expected_version: { type: "number" },
+        description: { type: "string" },
+      },
+      ["action", "app_id"],
+    ),
+    route: ({ action, ...p }) => ({ event: { list: "loops:list_docs", read: "loops:get_doc", write: "loops:write_doc", delete: "loops:delete_doc" }[action], params: p }),
+    mutates: true,
+  },
+  {
+    name: "oalo_app_logs",
+    description:
+      "What an app's own processes printed, per env (dev is the preview, prod the live app): its server (`web`), Procfile workers, the `release` command, and OALO's own notes (`oalo`: what started, what exited and with what status). The last 2,000 lines per env are kept. Read this first when an app doesn't start or misbehaves. It can hold secrets or customers' details the app printed: never repeat those. Read-only.",
+    inputSchema: S(
+      {
+        app: { type: "string", description: "The app's slug (oalo_list_apps)" },
+        env: { type: "string", enum: ["dev", "prod"] },
+        process: { type: "string", description: "Only this process: web, a worker's name, release or oalo" },
+        limit: { type: "number", description: "Recent lines, default 200" },
+      },
+      ["app"],
+    ),
+    event: "logs:get",
+  },
+  {
+    name: "oalo_releases",
+    description:
+      "An app's live releases. action=history lists the commits it has had live, newest first. action=rollback makes the release before the current one live again (or `to`, a sha from the history): it is built and checked like any live deploy, and a failing one leaves the current release live. A rollback builds like a live deploy, so the call can take up to about half an hour. Rolling back changes what live visitors get: only when the person asks. rollback MUTATES.",
+    inputSchema: S(
+      { app: { type: "string" }, action: { type: "string", enum: ["history", "rollback"] }, to: { type: "string" } },
+      ["app", "action"],
+    ),
+    route: ({ action, ...p }) => ({ event: `release:${action}`, params: p }),
+    // Past CodeBuild's 30 minutes, the same wait as `oalo deploy --rollback`.
+    timeoutMs: () => 35 * 60_000,
+    timeoutHint: "The rollback may still be running on the workspace: call oalo_releases with action=history to see which release is live before trying again.",
+    mutates: true,
+  },
+  {
+    name: "oalo_generate_tool",
+    description:
+      "Write a code tool from a description and add it to the workspace's tools, where loops (function_call) and bots can use it. Describe its inputs, what it returns and any APIs it calls. Pass `regenerate_tool_id` to change an existing tool instead. The code is compiled and checked before it is saved. Takes up to a few minutes. To change a tool's code yourself, use oalo_get_tool_source and oalo_save_tool_source. MUTATES the workspace.",
+    inputSchema: S({ description: { type: "string" }, regenerate_tool_id: { type: "number" } }, ["description"]),
+    event: "loops:generate_tool_wait",
+    timeoutMs: () => 330_000,
+    mutates: true,
+  },
+  {
+    name: "oalo_tool_templates",
+    description:
+      "Ready-made tools to bring in instead of writing one. action=list shows the templates (weighted split, math, ...); install adds one (`template`, optional `bot_id` to give it to a bot, `config`); copy brings a built-in or platform tool into the workspace's tools by `tool_name` (names from oalo_list_functions) so loops can call it. install and copy MUTATE.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["list", "install", "copy"] },
+        template: { type: "string" },
+        tool_name: { type: "string" },
+        bot_id: { type: "string" },
+        config: { type: "object" },
+      },
+      ["action"],
+    ),
+    route: ({ action, ...p }) =>
+      action === "list"
+        ? { event: "tools:templates", params: {} }
+        : action === "copy"
+          ? { event: "loops:copy_tool", params: { tool_name: p.tool_name } }
+          : { event: "tools:install_template", params: { template: p.template, ...(p.bot_id ? { bot_id: p.bot_id } : {}), ...(p.config ? { config: p.config } : {}) } },
+    mutates: true,
+  },
+  {
+    name: "oalo_test_conversation",
+    description:
+      "Run a scripted test conversation with a bot and get the transcript: the bot's replies per message, flow state (where a flow is and what it waits for), the path of flow steps, every step with its status and output (`steps`), and the cost. Use it after saving a flow to check it behaves. `channel` makes the bot act as that channel (whatsapp/instagram/sms = text mode); on whatsapp and sms the test customer arrives with a fictional phone on file, as a real one does. With `flow`, the bot can also start that flow again on a later message, even while it is off. The conversation is a hidden preview and nothing is sent to customers, but the bot's tools and flows run for real (contact details are saved, handoffs happen). Takes a while: each message waits until the bot settles.",
+    inputSchema: S(
+      {
+        bot_id: { type: "string", description: "Numeric id or public bot id (bot_...)" },
+        messages: { type: "array", items: { type: "string" }, description: "What the customer says, in order (at most 20)" },
+        flow: { type: "string", description: "A flow name: the first message starts it (works on a flow that is off)" },
+        channel: { type: "string", enum: ["web", "whatsapp", "instagram", "sms", "embed"] },
+        turn_timeout_s: { type: "number", description: "Per message, default 90, at most 300" },
+      },
+      ["bot_id", "messages"],
+    ),
+    event: "chat:bots:qa_run",
+    timeoutMs: (args) => ((args.messages?.length || 1) * ((Number(args.turn_timeout_s) || 90) + 15) + 30) * 1000,
+  },
+  {
+    name: "oalo_rehearse_inbound",
+    description:
+      "Rehearse inbound WhatsApp conversations end to end and get a report per scenario: what the customer was sent, which thread and bot it ended on, the triage loop runs and their steps, pass/fail checks and, when nothing was sent, why. A fictional 555-01XX customer writes to one of the workspace's numbers through the real inbound path (routing, triage, moves, the bot's reply). Nothing is sent to WhatsApp, the threads stay out of the Inbox and the team gets no notices; LLM calls are real. `suite: true` runs the standard scenarios (new customer, known contact with a thread open on another number, returning the same day, after 24 hours, deal won earlier, writes again after opting out, handed to a teammate, with a teammate writing from another number). Takes minutes.",
+    inputSchema: S(
+      {
+        suite: { type: "boolean", description: "Run the standard scenarios" },
+        scenarios: {
+          type: "array",
+          items: { type: "object" },
+          description: 'Instead of the suite: [{"name", "messages": [...], "number", "known_contact", "opted_out", "open_thread": {"bot_id", "number", "hours_ago", "tags", "assigned"}, "expect": {"reply", "bot_id"}}]',
+        },
+        number: { type: "string", description: "phone_number_id the customer writes to (suite); default the workspace's default number" },
+        responder_bot_id: { type: "string", description: "The bot that should end up answering (suite): its public id, bot_..., as oalo_list_bots shows it" },
+        turn_timeout_s: { type: "number", description: "Per message, default 120, at most 300" },
+      },
+      [],
+    ),
+    event: "chat:bots:rehearse",
+    timeoutMs: (args) => ((args.scenarios?.length || 8) * 3 * ((Number(args.turn_timeout_s) || 120) + 15) + 60) * 1000,
+  },
+  {
+    name: "oalo_get_tool_source",
+    description:
+      "A tool's code and schemas by `tool_id` (ids from oalo_list_functions or oalo_bot_tools). Returns source_js, input/output schemas, `editable` (only code tools are) and `source_hash` to send back as base_source_hash when saving.",
+    inputSchema: S({ tool_id: { type: "number" } }, ["tool_id"]),
+    event: "fn:source",
+  },
+  {
+    name: "oalo_save_tool_source",
+    description:
+      "Save a code tool's exact JavaScript (no AI rewrite). MUTATES the live workspace: every bot using the tool runs the new code. The code is compiled first, so code that doesn't build is refused and the old version keeps running. Only what you send changes (description and schemas keep their stored values when omitted; enabled is never touched). Send the `source_hash` you read as `base_source_hash`, or a concurrent edit is overwritten. The entry point is `function main(input) { ... return {...}; }`.",
+    inputSchema: S(
+      {
+        tool_id: { type: "number" },
+        source_js: { type: "string" },
+        base_source_hash: { type: "string" },
+        description: { type: "string" },
+        input_schema: { type: "object" },
+        output_schema: { type: "object" },
+      },
+      ["tool_id", "source_js"],
+    ),
+    event: "fn:save_source",
+    mutates: true,
+  },
+  {
+    name: "oalo_bot_tools",
+    description:
+      "Which tools a bot can call. action=list shows every tool the bot could reach with `allowlisted` true/false; action=allow / disallow adds or removes one tool (by `tool` name or id) from the bot's list. A flow's computation step fails at run time on a tool that isn't allowed. allow/disallow MUTATE the workspace.",
+    inputSchema: S(
+      {
+        action: { type: "string", enum: ["list", "allow", "disallow"] },
+        bot_id: { type: "string", description: "Numeric id or public bot id (bot_...)" },
+        tool: { type: "string", description: "allow/disallow: the tool's name or numeric id" },
+      },
+      ["action", "bot_id"],
+    ),
+    run: async (oalo, { action, bot_id, tool }) => {
+      const tools = (await oalo.call("chat:bots:tools:list", { bot_id }))?.tools ?? [];
+      if (action === "list") return { tools };
+      const target = tools.find((t) => t.name === tool || String(t.id) === String(tool));
+      if (!target) throw new Error(`no tool ${JSON.stringify(tool)} is reachable by this bot`);
+      const allowed = new Set(tools.filter((t) => t.allowlisted).map((t) => t.id));
+      if (action === "allow") allowed.add(target.id);
+      else allowed.delete(target.id);
+      await oalo.call("chat:bots:tools:set_allowlist", { bot_id, tool_ids: [...allowed] });
+      return { tool: target.name, allowlisted: action === "allow", count: allowed.size };
+    },
+    mutates: true,
+  },
+  {
+    name: "oalo_knowledge_search",
+    description: "Semantic search over a bot's knowledge graph.",
+    inputSchema: S({ bot_id: { type: "string" }, query: { type: "string" } }, [
+      "bot_id",
+      "query",
+    ]),
+    event: "kg:search",
+  },
+  {
+    name: "oalo_jobs",
+    description:
+      "Background job snapshot including recent failures. Check here when something ran but produced nothing.",
+    inputSchema: S({}),
+    event: "jobs:snapshot",
+  },
+  {
+    name: "oalo_emit",
+    description:
+      "Fire a domain event (form.submitted, order.created, whatsapp.inbound, ...) through the real event bus, to test that a loop's trigger and payload filter are wired. Unlike running a loop directly, this goes through the trigger. The loops it fires run for real and can send email or WhatsApp to real contacts, so call with dry_run=true first: that returns the loops that would fire and changes nothing. Event types and their payload fields: oalo_loop_triggers action=catalog. Admins and members with Developer access only. Events are tagged as coming from the CLI and posted to the team feed.",
+    inputSchema: S(
+      {
+        type: { type: "string", description: "Event type, e.g. form.submitted" },
+        payload: { type: "object", description: "The event payload (its fields are in the trigger catalog)" },
+        contact_id: { type: "string", description: "An existing contact the event is about (never creates one)" },
+        dry_run: { type: "boolean", description: "List the loops that would fire, emit nothing" },
+      },
+      ["type"],
+    ),
+    event: "cli_api:emit",
+    mutates: true,
+  },
+  {
+    name: "oalo_docs",
+    description:
+      "OALO's platform documentation, from this workspace's box. With slug: the full page as markdown. With q: pages ranked for the words, each with a matching line. With neither: every page's slug and summary. Read the relevant page before building on a feature you don't know (data models, sync, flows, loops, commerce, channels, tokens). Read-only.",
+    inputSchema: S({
+      slug: { type: "string", description: "A page, e.g. data-models or sync-api-reference" },
+      q: { type: "string", description: "Words to search for" },
+      audience: { type: "string", enum: ["developer", "trainer"], description: "With neither slug nor q: only pages for this reader" },
+    }),
+    route: ({ slug, q, audience }) =>
+      slug ? { event: "docs:get", params: { slug } } : { event: "docs:list", params: q ? { q } : audience ? { audience } : {} },
+  },
+  // ── Data: models and rows (oalo data). Reads use the saved data token over
+  // the Sync API; row writes use a table-limited write token made as the person;
+  // creating and promoting models goes over this channel as the person.
+  {
+    name: "oalo_list_models",
+    description:
+      "The workspace's data models (tables): fields and types, whether rows are shared or owned per app user (owner_field). Call this before reading or writing rows, and before creating a model, to reuse one that exists. Every workspace has two schemas with the same models: dev (a sandbox) and prod (what live apps read).",
+    inputSchema: S({ env: { type: "string", enum: ["dev", "prod"], description: "Which schema (default dev). Models are the same in both." } }),
+    run: async (_oalo, { env }, ctx) => listModels(readSide(ctx, env)),
+  },
+  {
+    name: "oalo_create_model",
+    description:
+      "Define a new data model (table) in both dev and prod. Fields live in each row's JSON document; every model also gets id, owner_id, availability and product_id. Use owner_field when each app user owns their rows (a member sees only their own); leave it out for shared content everyone sees. Field types: string text integer float boolean datetime date json list references:<table>. Check oalo_list_models first. MUTATES the workspace (creates tables); follows the person's dashboard access.",
+    inputSchema: S(
+      {
+        name: { type: "string", description: "snake_case table name, e.g. orders_mirror" },
+        fields: {
+          type: "array",
+          description: "Fields, e.g. [{\"name\":\"total\",\"type\":\"float\"}] or [\"total:float\", \"email\"]",
+          items: { anyOf: [{ type: "string" }, { type: "object", properties: { name: { type: "string" }, type: { type: "string" } }, required: ["name"] }] },
+        },
+        owner_field: { type: "string", description: "Field holding the owning app user's id. Omit for shared rows." },
+      },
+      ["name", "fields"],
+    ),
+    run: async (oalo, { name, fields, owner_field }) =>
+      createModel(oalo, {
+        name,
+        fields: fields.flatMap((f) => (typeof f === "string" ? parseFields([f]) : [{ name: f.name, type: f.type || "string" }])),
+        ownedBy: owner_field,
+      }),
+    mutates: true,
+  },
+  {
+    name: "oalo_read_rows",
+    description:
+      "Read rows from a model. With id: one row. Otherwise a page in write order: pass since=<next_since> from the previous page to continue while has_more is true. Each row is {id, document, owner_id, availability, product_id, seqnum, ...}; the fields are in document. Read-only.",
+    inputSchema: S(
+      {
+        table: { type: "string" },
+        id: { type: "string", description: "One row by id" },
+        env: { type: "string", enum: ["dev", "prod"], description: "Which schema (default dev)" },
+        since: { type: "integer", description: "Continue after this seqnum (next_since of the previous page)" },
+        limit: { type: "integer", description: "Rows per page (default 500, max 5000)" },
+      },
+      ["table"],
+    ),
+    run: async (_oalo, { table, id, env, since, limit }, ctx) => {
+      const c = readSide(ctx, env);
+      return id ? getRow(c, table, id) : listRows(c, table, { since, limit });
+    },
+  },
+  {
+    name: "oalo_query_metrics",
+    description:
+      "Count, sum or average over the workspace's data: a model's rows, events, or contacts, filtered, grouped by a field, or over time. Use it to answer a question about numbers (how many orders this week, revenue by plan, new contacts per day) instead of reading rows and adding them up. A model's fields are checked: oalo_list_models lists them. Model rows count at when they were created (stamped by the server). Read-only.",
+    inputSchema: S({
+      source: { type: "string", enum: ["model", "event", "contact"], description: "Default model (give table)." },
+      table: { type: "string" },
+      env: { type: "string", enum: ["prod", "dev"], description: "A model's live (default) or dev data." },
+      event: { type: "string", description: "An event type such as order.created; leave it out for every type." },
+      measure: { type: "string", enum: ["count", "sum", "avg", "min", "max", "distinct"], description: "Default count. sum, avg, min and max read field as a number." },
+      field: { type: "string" },
+      by: { type: "string", description: "Group by this field. Contacts group by status, source or custom_fields.<name>." },
+      every: { type: "string", enum: ["day", "week", "month"] },
+      time: { type: "string", description: "Model rows: created (default), changed, or a date field." },
+      days: { type: "integer", description: "The window, ending now. Leave it out for all time." },
+      compare: { type: "boolean", description: "Also the window before (needs days)." },
+      where: { type: "array", description: "Filters {field, op, value}; op: eq neq in gt gte lt lte set unset contains.", items: { type: "object" } },
+    }),
+    route: (args) => ({ event: "metrics:query", params: { query: args } }),
+  },
+  {
+    name: "oalo_list_dashboards",
+    description: "The workspace's dashboards (Insights > Dashboards): names, widget counts, and whether one shows on an app. Read it before oalo_save_dashboard_widget. Read-only.",
+    inputSchema: S({}),
+    event: "dashboards:list",
+  },
+  {
+    name: "oalo_save_dashboard_widget",
+    description:
+      "Put a chart on a dashboard so it stays and updates by itself: the way to answer \"add a chart\", \"track X\" or \"put Y on the dashboard\". Adds the widget, or replaces the one with the same title; the dashboard is made when none has that name (app attaches a new one to an app). The query runs first: one that fails is refused with the reason, a saved one returns its numbers. kind: number (compare adds the window before), line (query.every), bars (query.by), table, funnel (query.steps: event types in order, and days). MUTATES what everyone with access sees; say which dashboard you used.",
+    inputSchema: S(
+      {
+        dashboard: { type: "string", description: "The dashboard's name. Default Overview." },
+        app: { type: "string", description: "An app's slug, for a dashboard made now." },
+        title: { type: "string", description: "In the person's words, like \"Orders per week\"." },
+        kind: { type: "string", enum: ["number", "line", "bars", "table", "funnel"] },
+        width: { type: "integer", enum: [1, 2, 3] },
+        query: { type: "object", description: "The same fields as oalo_query_metrics, or for a funnel {steps, days}." },
+      },
+      ["title", "kind", "query"],
+    ),
+    route: ({ dashboard, app, title, kind, width, query }) => ({
+      event: "dashboards:put_widget",
+      params: { dashboard, app, widget: { title, kind, query, ...(width ? { width } : {}) } },
+    }),
+  },
+  {
+    name: "oalo_write_rows",
+    description:
+      "Upsert and/or soft-delete rows in a model. Upserts match by id: pass each row with an id (from id_field) so sending it again updates it instead of adding a copy. Fields go flat in the row ({\"id\":\"42\",\"total\":9.5}) or as {id, document:{...}}. Any number of rows; they are sent 1,000 at a time and the rate limit is waited out. Writes sync to every app on that schema at once. env is required: write to dev, check with oalo_read_rows, then oalo_promote_model copies dev to prod. Writing to prod needs confirm=true because live apps see it immediately. The first write to a table creates a write token limited to it, as the person. MUTATES data.",
+    inputSchema: S(
+      {
+        table: { type: "string" },
+        env: { type: "string", enum: ["dev", "prod"] },
+        upsert: { type: "array", items: { type: "object" }, description: "Rows to create or update" },
+        id_field: { type: "string", description: "Which field holds each row's id (default id)" },
+        delete: { type: "array", items: { type: "string" }, description: "Ids to soft-delete (they leave synced apps)" },
+        confirm: { type: "boolean", description: "Required for env=prod" },
+      },
+      ["table", "env"],
+    ),
+    run: async (oalo, { table, env, upsert = [], id_field = "id", delete: ids = [], confirm }, ctx) => {
+      if (env === "prod" && confirm !== true) {
+        throw new Error("writing to prod changes what live apps show right away. Write to dev first, or pass confirm=true after the person agrees.");
+      }
+      if (!upsert.length && !ids.length) throw new Error("nothing to do: pass upsert rows and/or delete ids");
+      const { rows, missing } = toRows(upsert, { idField: id_field });
+      if (missing.length) {
+        throw new Error(`${missing.length} row(s) have no ${id_field} (first: index ${missing[0].index}). Give every row an id so a re-send updates it.`);
+      }
+      const token = await writeTokenFor(ctx.url, [table], oalo);
+      const cfg = { serverUrl: ctx.url, token, env };
+      const result = { table, env };
+      if (rows.length) Object.assign(result, await pushRows(cfg, table, rows));
+      if (ids.length) result.deletes = await deleteRows(cfg, table, ids);
+      return result;
+    },
+    mutates: true,
+  },
+  {
+    name: "oalo_promote_model",
+    description:
+      "Copy a model's rows from dev to prod (upsert by id), so live apps get them. Rows in prod with the same id are overwritten by the dev copy. Run it after checking the dev rows, and only when the person wants the data live. MUTATES live data.",
+    inputSchema: S({ table: { type: "string" } }, ["table"]),
+    run: async (oalo, { table }) => promoteModel(oalo, table),
+    mutates: true,
+  },
+  {
+    name: "oalo_sync_routes",
+    description:
+      "The Sync API's own description: every REST endpoint under /api/sync/v1, the token scopes (read, write, read:<table>, write:<table>), query params, headers (Idempotency-Key, If-Unmodified-Since-Ms) and rate limits. Use it when writing code that calls the Sync API from an app's server. Read-only.",
+    inputSchema: S({}),
+    run: async (_oalo, _args, ctx) => routes(readSide(ctx)),
+  },
+  {
+    name: "oalo_call",
+    description:
+      "Escape hatch: call any BuilderChannel event directly. The curated tools above cover normal work; use this only for something they do not reach. To find an event and its params, call event 'cli_api:events' with params {\"q\": \"<text>\"}: it lists the events you may call and the param shapes each accepts. May mutate, so check the event name before calling.",
+    inputSchema: S(
+      {
+        event: { type: "string", description: "Channel event name" },
+        params: { type: "object", description: "Event params" },
+      },
+      ["event"],
+    ),
+    raw: true,
+  },
+];
+
+export const BY_NAME = Object.fromEntries(TOOLS.map((t) => [t.name, t]));
+
+/** The read side for data tools: the saved data token, on one schema. */
+function readSide(ctx, env = "dev") {
+  // The project may name no workspace; then the channel connected to the most
+  // recently saved one, and its data token is the one to use.
+  const token = ctx?.cfg?.token || (ctx?.url && readToken({ serverUrl: ctx.url, appId: null }, "sync"));
+  if (!token) {
+    throw new Error("no data token saved for this workspace. Ask the person to run `oalo login --server <workspace url>`.");
+  }
+  return { serverUrl: ctx.url, token, env };
+}