testeiya 0.2.0

package/src/extensions/tool-gate.ts

@@ -0,0 +1,220 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI, ExtensionFactory } from "@oh-my-pi/pi-coding-agent";
+
+/**
+ * Tool gate — deferred loading for MCP tool schemas.
+ *
+ * Every MCP tool stays registered, but only a read-first subset is *active*
+ * (its schema reaches the model). The rest are listed by exact name in a
+ * byte-stable `<deferred_tools>` block appended to the system prompt, and the
+ * `enable_tools` tool activates any of them for the rest of the session via
+ * `pi.setActiveTools()`. Mirrors the deferred-tool pattern shipped by the
+ * Claude API (`defer_loading` + tool search) and VS Code's virtual tools.
+ *
+ * Active-set selection per server, first match wins:
+ *   1. `toolGate.activeTools[server]` config globs (matched against original
+ *      MCP tool names) — explicit pinning, replaces all heuristics.
+ *   2. Testomat.io servers — curated read set (entity list/get/search +
+ *      analytics + ping).
+ *   3. Any other server — tools without a mutating verb token in the name,
+ *      capped at SERVER_BUDGET (search/list/get-shaped names kept first).
+ *
+ * The deferred block is computed from the base classification only — session
+ * `enable_tools` activations never change it, so the system prompt stays
+ * byte-identical across turns and the prompt cache is preserved.
+ */
+export function createToolGateExtension(
+  runtime: ToolGateRuntime,
+  config?: ToolGateConfig
+): ExtensionFactory {
+  return ((pi: ExtensionAPI) => {
+    const sessionEnabled = new Set<string>();
+    let lastLogged = "";
+
+    pi.registerTool({
+      name: "enable_tools",
+      label: "Enable Tools",
+      description:
+        "Activate deferred MCP tools listed in <deferred_tools>. Pass their " +
+        "exact names; they stay active for the rest of the session. Call this " +
+        "before your first use of any deferred tool.",
+      parameters: Type.Object({
+        tools: Type.Array(Type.String(), {
+          minItems: 1,
+          description: "Exact tool names from the <deferred_tools> block.",
+        }),
+      }),
+      async execute(_toolCallId, params) {
+        const requested = (params as { tools: string[] }).tools;
+        const known = new Set(pi.getAllTools());
+        const unknown = requested.filter((name) => !known.has(name));
+        if (unknown.length > 0) {
+          return textResult(
+            `Unknown tool(s): ${unknown.join(", ")}. Use exact names from <deferred_tools>.`
+          );
+        }
+        for (const name of requested) sessionEnabled.add(name);
+        await applyGate();
+        console.log(`[tool-gate] enabled: ${requested.join(", ")}`);
+        return textResult(
+          `Enabled: ${requested.join(", ")}. Available from your next step.`
+        );
+      },
+    });
+
+    pi.on("before_agent_start", async (event: any) => {
+      let block: string | null;
+      try {
+        block = await applyGate();
+      } catch (err) {
+        console.error("[tool-gate] gate failed:", err);
+        return undefined;
+      }
+      if (!block) return undefined;
+      return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+    });
+
+    async function applyGate(): Promise<string | null> {
+      const mcpTools = (runtime.mcpManager?.getTools?.() ?? []) as McpToolInfo[];
+      if (mcpTools.length === 0) return null;
+
+      const byServer = new Map<string, McpToolInfo[]>();
+      for (const tool of mcpTools) {
+        const server = tool.mcpServerName ?? "unknown";
+        let list = byServer.get(server);
+        if (!list) {
+          list = [];
+          byServer.set(server, list);
+        }
+        list.push(tool);
+      }
+
+      const active = new Set<string>();
+      const deferredByServer = new Map<string, string[]>();
+      const servers = [...byServer.entries()].sort(([a], [b]) => a.localeCompare(b));
+      for (const [server, tools] of servers) {
+        const activeNames = selectActive(server, tools, config);
+        const deferredNames: string[] = [];
+        for (const tool of tools) {
+          if (activeNames.has(tool.name)) {
+            active.add(tool.name);
+          } else {
+            deferredNames.push(tool.name);
+          }
+        }
+        if (deferredNames.length > 0) {
+          deferredByServer.set(server, deferredNames.sort());
+        }
+      }
+
+      const mcpNames = new Set(mcpTools.map((tool) => tool.name));
+      const nonMcp = pi.getAllTools().filter((name) => !mcpNames.has(name));
+      const enabled = [...sessionEnabled].filter((name) => mcpNames.has(name));
+      await pi.setActiveTools([...new Set([...nonMcp, ...active, ...enabled])]);
+
+      const activeCount = new Set([...active, ...enabled]).size;
+      const summary = `${activeCount}/${mcpTools.length}`;
+      if (summary !== lastLogged) {
+        lastLogged = summary;
+        console.log(
+          `[tool-gate] mcp tools: ${activeCount} active, ${mcpTools.length - activeCount} deferred`
+        );
+      }
+
+      if (deferredByServer.size === 0) return null;
+      return deferredBlock(deferredByServer);
+    }
+  }) as ExtensionFactory;
+}
+
+const SERVER_BUDGET = 15;
+
+const TESTOMATIO_ACTIVE_RE =
+  /^(?:(?:tests|suites|runs|testruns|plans|requirements)_(?:list|get|search)|analytics_(?:tests|stats)|system_ping)$/;
+
+const MUTATING_VERBS = new Set([
+  "create", "update", "delete", "remove", "add", "set", "upload", "link",
+  "unlink", "write", "send", "execute", "exec", "push", "post", "put", "patch",
+  "move", "archive", "unarchive", "assign", "unassign", "transition", "comment",
+  "merge", "close", "reopen", "cancel", "approve", "reject", "invite", "import",
+  "clone", "fork", "deploy", "trigger", "run", "start", "stop", "restart",
+  "kill", "insert", "edit", "modify", "rename", "revoke", "grant", "publish",
+  "submit", "apply", "sync", "reset", "clear", "purge", "flush", "mark",
+  "complete", "resolve", "vote", "watch", "invoke",
+]);
+
+const READ_PRIORITY = ["search", "list", "get", "read", "find", "query", "status"];
+
+function selectActive(
+  server: string,
+  tools: McpToolInfo[],
+  config?: ToolGateConfig
+): Set<string> {
+  const overrides = config?.activeTools?.[server];
+  if (overrides && overrides.length > 0) {
+    const globs = overrides.map((pattern) => new Bun.Glob(pattern));
+    const matched = tools.filter((tool) =>
+      globs.some((glob) => glob.match(tool.mcpToolName))
+    );
+    return new Set(matched.map((tool) => tool.name));
+  }
+  if (server.startsWith("testomatio")) {
+    const matched = tools.filter((tool) => TESTOMATIO_ACTIVE_RE.test(tool.mcpToolName));
+    return new Set(matched.map((tool) => tool.name));
+  }
+  const readTools = tools.filter((tool) => !isMutating(tool.mcpToolName));
+  readTools.sort(byReadPriority);
+  return new Set(readTools.slice(0, SERVER_BUDGET).map((tool) => tool.name));
+}
+
+function isMutating(mcpToolName: string): boolean {
+  return tokensOf(mcpToolName).some((token) => MUTATING_VERBS.has(token));
+}
+
+function byReadPriority(a: McpToolInfo, b: McpToolInfo): number {
+  const diff = readScore(a) - readScore(b);
+  if (diff !== 0) return diff;
+  return a.mcpToolName.localeCompare(b.mcpToolName);
+}
+
+function readScore(tool: McpToolInfo): number {
+  const tokens = tokensOf(tool.mcpToolName);
+  const index = READ_PRIORITY.findIndex((verb) => tokens.includes(verb));
+  if (index === -1) return READ_PRIORITY.length;
+  return index;
+}
+
+function tokensOf(mcpToolName: string): string[] {
+  return mcpToolName.toLowerCase().split(/[_\-.]/);
+}
+
+function deferredBlock(deferredByServer: Map<string, string[]>): string {
+  const lines: string[] = [];
+  for (const [server, names] of deferredByServer) {
+    lines.push(`${server}: ${names.join(", ")}`);
+  }
+  return (
+    "<deferred_tools>\n" +
+    'These MCP tools are registered but their schemas are not loaded. To use one, first call enable_tools({tools: ["<exact name>"]}) — it stays active for the rest of the session — then call it.\n' +
+    lines.join("\n") +
+    "\n</deferred_tools>"
+  );
+}
+
+function textResult(text: string): { content: Array<{ type: "text"; text: string }> } {
+  return { content: [{ type: "text", text }] };
+}
+
+export interface ToolGateRuntime {
+  mcpManager?: { getTools?: () => unknown[] } | null;
+}
+
+export interface ToolGateConfig {
+  activeTools?: Record<string, string[]>;
+}
+
+interface McpToolInfo {
+  name: string;
+  mcpToolName: string;
+  mcpServerName?: string;
+}

package/src/extensions/webui/ask-channel.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-connection registry of in-flight `ask_question` calls.
+ *
+ * `ask_question`'s `execute()` blocks on `wait(toolCallId)`, so the agent loop
+ * is genuinely parked while the user picks an option — mirroring the SDK's
+ * built-in `ask`/`await` tools, which also block inside `execute`. The
+ * WebSocket connection calls `answer(toolCallId, value)` when the user clicks
+ * a pill; that resolves the pending promise, the chosen option becomes the
+ * tool result, and the SAME turn continues.
+ *
+ * Without this the tool returned immediately, the loop kept running, and the
+ * model emitted filler text ("Awaiting selection…", "Blocked until…") instead
+ * of actually stopping.
+ */
+const DISMISSED =
+  "[The user dismissed this question without picking an option. Ask again only if you still need the answer; otherwise continue.]";
+
+export class AskChannel {
+  private pending = new Map<string, (value: string) => void>();
+
+  wait(toolCallId: string, signal?: AbortSignal): Promise<string> {
+    const { promise, resolve } = Promise.withResolvers<string>();
+    this.pending.set(toolCallId, resolve);
+    if (!signal) return promise;
+    if (signal.aborted) {
+      this.settle(toolCallId, DISMISSED);
+      return promise;
+    }
+    signal.addEventListener("abort", () => this.settle(toolCallId, DISMISSED), {
+      once: true,
+    });
+    return promise;
+  }
+
+  answer(toolCallId: string, value: string): boolean {
+    return this.settle(toolCallId, value);
+  }
+
+  cancelAll(): void {
+    for (const id of Array.from(this.pending.keys())) {
+      this.settle(id, DISMISSED);
+    }
+  }
+
+  private settle(toolCallId: string, value: string): boolean {
+    const resolve = this.pending.get(toolCallId);
+    if (!resolve) return false;
+    this.pending.delete(toolCallId);
+    resolve(value);
+    return true;
+  }
+}

package/src/extensions/webui/index.ts

@@ -0,0 +1,184 @@
+/**
+ * Web-UI-only Pi extension.
+ *
+ * Bundles everything that only makes sense when the agent is driving the
+ * web chat UI:
+ *   - Custom tools: render_result, render_list, query_result, render_tree,
+ *     render_item, render_chart, ask_question (the web UI renders these as
+ *     rich cards; render_* return an ack to the model and the card payload
+ *     via `details.widget` — see widget-result.ts).
+ *   - A tool_result middleware that caches each MCP `*_list`/`*_search`
+ *     result by its tool call id (rows slimmed of code/description bodies)
+ *     and replaces large ones in model context with a compact digest
+ *     `{call_id, total, fields, sample}`; `render_result` shows the cached
+ *     rows to the user, `query_result` computes over them. A "UI notice"
+ *     (carrying the call id) tells the model both moves.
+ *
+ * Loaded only when `createTesteiyaSession({ mode: "web" })`. In TUI mode
+ * none of this exists: Pi's built-in `ask` tool (gated behind `hasUI`)
+ * handles questioning the user natively.
+ */
+
+import type { ExtensionAPI, ExtensionFactory } from "@oh-my-pi/pi-coding-agent";
+
+import { createRenderListTool } from "./tools/render-list.js";
+import { createRenderResultTool, type CachedList } from "./tools/render-result.js";
+import { createQueryResultTool } from "./tools/query-result.js";
+import { renderTreeTool } from "./tools/render-tree.js";
+import { renderItemTool } from "./tools/render-item.js";
+import { renderChartTool } from "./tools/render-chart.js";
+import { createAskQuestionTool } from "./tools/ask-question.js";
+import { createUiWidgetTool } from "./tools/ui-widget.js";
+import type { AskChannel } from "./ask-channel.js";
+import type { WidgetCommandChannel } from "./widget-channel.js";
+
+export { AskChannel } from "./ask-channel.js";
+export { WidgetCommandChannel } from "./widget-channel.js";
+
+const LIST_RESULT_RE = /_(testruns|runs|tests|suites|plans)_(?:list|search)$/;
+const CACHE_CAP = 50;
+// Slimmed results at or below this size stay inline — a digest would save
+// nothing and just force an extra query_result round-trip.
+const DIGEST_THRESHOLD = 2000;
+const SLIM_FIELDS = ["code", "description"];
+
+const RENDER_TOOLS = new Set([
+  "render_result",
+  "render_list",
+  "render_tree",
+  "render_item",
+  "render_chart",
+]);
+
+const RENDER_NOTICE =
+  "\n\n[UI notice — not part of the data]\n" +
+  "This content was just rendered to the user as a rich card in the chat UI. " +
+  "They can see it fully. " +
+  "Do NOT restate the data in your text reply — a 1–2 sentence summary is enough.";
+
+const CHART_NOTICE =
+  "\n\n[UI notice — not part of the data]\n" +
+  "Chart rendered inline in the chat. A chart only shows the shape — also show " +
+  "the rows behind it: render_result({call_id}) for the query that produced them.";
+
+const WIDGET_NOTICE =
+  "\n\n[UI notice — not part of the data]\n" +
+  "This is the result of a widget command you ran. The widget the user is " +
+  "looking at has already updated to reflect it. Do NOT restate the returned " +
+  "data as a table or list — reply with a short insight only.";
+
+export function createWebUIExtension(
+  channel: AskChannel,
+  widgetChannel: WidgetCommandChannel
+): ExtensionFactory {
+  return ((pi: ExtensionAPI) => {
+    const listCache = new Map<string, CachedList>();
+
+    pi.registerTool(createRenderResultTool(listCache));
+    pi.registerTool(createRenderListTool(listCache));
+    pi.registerTool(createQueryResultTool(listCache));
+    pi.registerTool(renderTreeTool);
+    pi.registerTool(renderItemTool);
+    pi.registerTool(renderChartTool);
+    pi.registerTool(createAskQuestionTool(channel));
+    pi.registerTool(createUiWidgetTool(widgetChannel));
+
+    pi.on("tool_result", async (event: any) => {
+      if (event?.isError) return undefined;
+      const name = event?.toolName;
+      if (typeof name !== "string") return undefined;
+
+      let content = Array.isArray(event.content) ? event.content : [];
+      let notice: string | null = null;
+      if (name === "render_chart") notice = CHART_NOTICE;
+      else if (RENDER_TOOLS.has(name)) notice = RENDER_NOTICE;
+      else if (name === "ui_widget") notice = WIDGET_NOTICE;
+      else {
+        const kind = listKind(name);
+        if (kind && typeof event?.toolCallId === "string") {
+          content = content.map((item: any) =>
+            cacheListResult(item, kind, event.toolCallId, listCache)
+          );
+          notice = listNotice(event.toolCallId);
+        }
+      }
+      if (!notice) return undefined;
+
+      return {
+        content: [...content, { type: "text", text: notice }],
+      };
+    });
+  }) as ExtensionFactory;
+}
+
+function listNotice(callId: string): string {
+  return (
+    "\n\n[UI notice — not part of the data]\n" +
+    "The full result is cached server-side under this call id; the user has " +
+    "NOT seen it. Show it: " +
+    `render_result({call_id: "${callId}", title, columns?}). ` +
+    `Compute over it (counts, filters, joins): query_result({call_id: "${callId}", fn}). ` +
+    "Never re-type rows or paste them into your reply."
+  );
+}
+
+function listKind(toolName: unknown): string | null {
+  if (typeof toolName !== "string") return null;
+  return LIST_RESULT_RE.exec(toolName)?.[1] ?? null;
+}
+
+// Slims each row (the full `code`/`description` bodies are tens of thousands
+// of tokens the model never needs for listing — `*_get` exists for one item),
+// caches the result under its call id for `render_result`/`query_result`, and
+// substitutes a compact digest for anything past DIGEST_THRESHOLD so raw rows
+// never enter model context.
+function cacheListResult(
+  item: any,
+  kind: string,
+  callId: string,
+  cache: Map<string, CachedList>
+): any {
+  if (item?.type !== "text" || typeof item.text !== "string") return item;
+  try {
+    const parsed = JSON.parse(item.text);
+    if (!Array.isArray(parsed?.data)) return item;
+    const omitted: string[] = [];
+    for (const row of parsed.data) {
+      if (!row || typeof row !== "object") continue;
+      for (const field of SLIM_FIELDS) {
+        if (!(field in row)) continue;
+        delete row[field];
+        if (!omitted.includes(field)) omitted.push(field);
+      }
+    }
+    const total = parsed.meta?.total ?? parsed.data.length;
+    cache.set(callId, { kind, rows: parsed.data, total });
+    if (cache.size > CACHE_CAP) {
+      const oldest = cache.keys().next().value;
+      if (oldest) cache.delete(oldest);
+    }
+    const slimmed = JSON.stringify(parsed);
+    if (slimmed.length <= DIGEST_THRESHOLD) return { ...item, text: slimmed };
+    const digest = {
+      call_id: callId,
+      kind,
+      total,
+      returned: parsed.data.length,
+      fields: fieldsOf(parsed.data),
+      omitted_fields: omitted,
+      sample: parsed.data.slice(0, 2),
+    };
+    return { ...item, text: JSON.stringify(digest) };
+  } catch {
+    return item;
+  }
+}
+
+function fieldsOf(rows: unknown[]): string[] {
+  const fields = new Set<string>();
+  for (const row of rows.slice(0, 20)) {
+    if (!row || typeof row !== "object") continue;
+    for (const key of Object.keys(row)) fields.add(key);
+  }
+  return [...fields];
+}

package/src/extensions/webui/tools/ask-question.ts

@@ -0,0 +1,88 @@
+import { Type } from "@sinclair/typebox";
+import type { ToolDefinition } from "@oh-my-pi/pi-coding-agent";
+import type { AskChannel } from "../ask-channel.js";
+
+/**
+ * `ask_question` — a web-UI-only question tool.
+ *
+ * The UI renders the question as text and each option as a clickable pill
+ * button (the `tool-input-available` event drives the render). `execute`
+ * then BLOCKS on the connection's `AskChannel` until the user clicks an
+ * option — the agent loop stays parked the whole time, exactly like Pi's
+ * built-in `ask` tool (which blocks on `ui.select`). The clicked option is
+ * returned as the tool result, so the same turn continues with the answer.
+ *
+ * This blocking is what stops the model from streaming filler text
+ * ("Awaiting selection…") after the call: it is never re-invoked until the
+ * answer exists.
+ */
+export function createAskQuestionTool(channel: AskChannel): ToolDefinition {
+  return {
+    name: "ask_question",
+    label: "Ask the user",
+    description:
+      "Present a question to the user with a set of clickable options. " +
+      "Use this WHENEVER you need the user to make a choice (yes/no, " +
+      "which-of-these, pick-a-project, confirm-an-action, etc.). By default " +
+      "the options render as single-choice pill buttons; clicking one returns " +
+      "that option's text as this tool's result. Set multiSelect:true to " +
+      "render checkboxes instead so the user can pick several items at once " +
+      "(the result is the chosen labels, one per line) — use this to let the " +
+      "user choose WHICH of many items to act on, e.g. 'pick which of these " +
+      "test cases to generate'. The UI always also offers a free-form field, " +
+      "so the result may be the user's own typed answer instead of any " +
+      "option, and a picked option may be followed by a 'Note: <comment>' " +
+      "line the user attached — treat whatever text comes back as the " +
+      "user's answer. The call blocks until the user answers — do not write " +
+      "any 'waiting' text.",
+    parameters: Type.Object({
+      question: Type.String({
+        description:
+          "The question or prompt to show the user (e.g. 'Which project should I pull tests from?').",
+      }),
+      options: Type.Array(Type.String(), {
+        description:
+          "1–50 option labels the user can pick from. There is no length " +
+          "limit per option — options can be multi-line. In single-select " +
+          "mode (default) clicking an option returns that exact string " +
+          "(including any markdown/description you put in it) as this tool's " +
+          "result. For any question where the natural answer is 'yes/proceed' " +
+          "(open-ended follow-ups like 'Want me to generate these?'), still " +
+          "pass at least one option such as 'Yes, proceed' so the user can " +
+          "one-click confirm.",
+        minItems: 1,
+        maxItems: 50,
+      }),
+      multiSelect: Type.Optional(
+        Type.Boolean({
+          description:
+            "When true, the options render as checkboxes with a Submit " +
+            "button and the user can pick several at once. The result is the " +
+            "selected option labels joined by newlines (one per line); a " +
+            "label may be followed by a 'Note: <comment>' line, and the " +
+            "user may append their own free-typed item.",
+        })
+      ),
+      recommended: Type.Optional(
+        Type.Array(Type.Integer(), {
+          description:
+            "Only used when multiSelect is true: 0-based indices of options " +
+            "that start checked (the recommended subset). The user can " +
+            "uncheck or check more before submitting.",
+        })
+      ),
+    }),
+    async execute(toolCallId, params, signal, _onUpdate, _ctx) {
+      const p = params as {
+        question: string;
+        options: string[];
+        multiSelect?: boolean;
+      };
+      console.log(
+        `[ask_question]${p.multiSelect ? " (multi)" : ""} "${p.question}" → [${p.options.join(" | ")}]`
+      );
+      const answer = await channel.wait(toolCallId, signal);
+      return { content: [{ type: "text", text: answer }] };
+    },
+  };
+}

package/src/extensions/webui/tools/query-result.ts

@@ -0,0 +1,79 @@
+import { Type } from "@sinclair/typebox";
+import vm from "node:vm";
+import type { ToolDefinition } from "@oh-my-pi/pi-coding-agent";
+import type { CachedList } from "./render-result.js";
+
+const MAX_RESULT = 8000;
+
+/**
+ * `query_result` — compute over cached `*_list`/`*_search` results without
+ * pulling their rows into model context. The model writes a JS function
+ * (guided by the digest's `fields`/`sample`) that receives one row array per
+ * referenced call id; only its return value comes back as the tool result.
+ */
+export function createQueryResultTool(cache: Map<string, CachedList>): ToolDefinition {
+  return {
+    name: "query_result",
+    label: "Query Result",
+    description:
+      "Compute over previously fetched *_list/*_search results — counts, " +
+      "filters, grouping, joins — without re-reading their rows. `fn` is a " +
+      "pure JS function receiving one row array per `call_id`; its return " +
+      "value is the tool result. Use the digest's `fields`/`sample` to " +
+      "write it. To show rows to the user use render_result/render_list.",
+    parameters: Type.Object({
+      call_id: Type.Union([Type.String(), Type.Array(Type.String())], {
+        description:
+          "Call id(s) of cached *_list/*_search results (from their UI notices).",
+      }),
+      fn: Type.String({
+        description:
+          "Pure JS function source, e.g. \"rows => rows.filter(r => " +
+          "r.status === 'passed').length\", or \"(all, failed) => …\" for " +
+          "several call ids. Sandboxed: no imports, no IO, 1s limit.",
+      }),
+    }),
+    async execute(_toolCallId, params) {
+      const p = params as { call_id: string | string[]; fn: string };
+      const ids = Array.isArray(p.call_id) ? p.call_id : [p.call_id];
+      const inputs: Array<unknown[]> = [];
+      for (const id of ids) {
+        const entry = cache.get(id);
+        if (!entry) {
+          const known = [...cache.keys()].slice(-5).join(", ") || "none";
+          return textResult(
+            `call_id "${id}" is not a cached list result (recent: ${known}).`
+          );
+        }
+        inputs.push(entry.rows);
+      }
+
+      let result: unknown;
+      try {
+        const sandbox: { __inputs: Array<unknown[]>; __result?: unknown } = {
+          __inputs: inputs,
+        };
+        vm.runInNewContext(`__result = (${p.fn})(...__inputs)`, sandbox, {
+          timeout: 1000,
+        });
+        result = sandbox.__result;
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return textResult(`fn failed: ${reason}`);
+      }
+
+      let json = JSON.stringify(result) ?? "undefined";
+      if (json.length > MAX_RESULT) {
+        json =
+          json.slice(0, MAX_RESULT) +
+          `… (+${json.length - MAX_RESULT} more chars — narrow the fn's return value)`;
+      }
+      console.log(`[query_result] calls=${ids.join(",")} → ${json.length} chars`);
+      return textResult(json);
+    },
+  };
+}
+
+function textResult(text: string): { content: Array<{ type: "text"; text: string }> } {
+  return { content: [{ type: "text", text }] };
+}

package/src/extensions/webui/tools/render-chart.ts

@@ -0,0 +1,53 @@
+import { Type } from "@sinclair/typebox";
+import type { ToolDefinition } from "@oh-my-pi/pi-coding-agent";
+import { widgetResult } from "./widget-result.js";
+
+/**
+ * `render_chart` — display a chart in the chat. Server-side a no-op echo;
+ * the UI renders it with the same recharts components as `chart` blocks.
+ * Point names matching run statuses (passed/failed/…) auto-use status colors.
+ */
+export const renderChartTool: ToolDefinition = {
+  name: "render_chart",
+  label: "Render Chart",
+  description:
+    "Display a chart in the chat UI. Use for any aggregate — counts, pass " +
+    "rate, distribution, trend, comparison.",
+  parameters: Type.Object({
+    type: Type.Union(
+      [
+        Type.Literal("bar"),
+        Type.Literal("line"),
+        Type.Literal("area"),
+        Type.Literal("pie"),
+      ],
+      { description: "bar to compare, line/area over time, pie for share." }
+    ),
+    title: Type.String({
+      description: "What the chart shows, including filter and window.",
+    }),
+    data: Type.Array(Type.Object({}, { additionalProperties: true }), {
+      description:
+        "One object per point: {name, value}, or {name, <seriesKey>: number, …} " +
+        "with `series` for multiple series. Status names (passed/failed/…) get " +
+        "status colors automatically.",
+      minItems: 1,
+    }),
+    series: Type.Optional(
+      Type.Array(
+        Type.Object({ key: Type.String(), label: Type.Optional(Type.String()) }),
+        { description: "Series keys for multi-series rows. Omit for {name, value}." }
+      )
+    ),
+  }),
+  async execute(_toolCallId, params) {
+    const p = params as { type?: string; title?: string; data?: unknown[] };
+    console.log(
+      `[render_chart] ${p.type} "${p.title ?? ""}" points=${p.data?.length ?? 0}`
+    );
+    return widgetResult(
+      `Rendered a ${p.type} chart "${p.title ?? ""}" (${p.data?.length ?? 0} points).`,
+      params
+    );
+  },
+};