pi-spark 0.14.2 → 0.14.4

package/README.md

@@ -55,11 +55,11 @@ The `pi` tool lets the pi coding agent inspect and manipulate itself (~740 token
 
 - `models` lists and searches the model catalog.
 - `name` sets or updates the current session's name.
-- `whoami` shows the current pi state with session name, active model with metadata, and thinking level.
+- `whoami` shows the current pi state, including session name, active model, and thinking level.
 
 The `web` tool gives the agent live web access, backed by the free [Exa MCP](https://exa.ai/mcp) (~350 tokens). No separate MCP setup or API key is needed.
 
-- `search` finds current information across the web and returns clean, ready-to-use content.
+- `search` finds current information across the web and returns ready-to-use content.
 - `fetch` reads the full content of known URLs as clean markdown, and can batch several URLs in one call.
 
 ![Agent tools](./assets/screenshot-tools.png)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Pi package that polishes your daily experience and keeps you at the frontier of agentic workflows.",
   "keywords": [
     "pi-coding-agent",

package/src/features/pi/actions/models.ts

@@ -25,35 +25,34 @@ export const modelsAction = defineAction({
   fields: {
     query: Type.Optional(Type.String({
       description:
-        "For \"models\": filter models with a Liqe (Lucene-like) query. Bare terms match any " +
+        "For \"models\": Filter models with a Liqe (Lucene-like) query. Bare terms match any " +
         "field, and unquoted terms are case-insensitive substrings. The syntax supports " +
         "AND/OR/NOT, grouping, wildcards, and numeric comparisons; quote values containing " +
         "special characters (e.g., id:\"deepseek/deepseek-v4\"). Filterable fields are id, name, " +
         "provider, api, reasoning (boolean), input (modalities), cost.input and cost.output " +
         "(USD per 1M tokens), contextWindow, maxTokens, thinkingLevels, and available " +
-        "(boolean, true when auth is configured). The catalog is large, so include " +
-        "available:true unless every model is needed (e.g., \"claude available:true\", " +
-        "\"provider:openrouter cost.input:<1\").",
+        "(boolean, true when auth is configured). Examples: \"claude available:true\", " +
+        "\"provider:openrouter cost.input:<1\".",
     })),
-    offset: Type.Optional(Type.Number({ description: "For \"models\": start from this model number (1-indexed)." })),
+    offset: Type.Optional(Type.Number({ description: "For \"models\": Start from this model number (1-indexed)." })),
     limit: Type.Optional(Type.Number({ description: "For \"models\": Return at most this many models." })),
   },
   promptGuidelines: [
     "Use the pi tool's \"models\" action when you need metadata of pi models; include available:true in the query unless unavailable models are needed.",
   ],
-  renderCall(args, theme) {
-    let text = `${theme.bold(theme.fg("toolTitle", "pi"))} ${theme.fg("accent", "models")}`;
+  renderParams(args, theme) {
+    const params: string[] = [];
 
     const query = args.query?.trim();
-    if (query) text += theme.fg("muted", ` ${query}`);
+    if (query) params.push(theme.fg("muted", query));
 
     if (args.offset !== undefined || args.limit !== undefined) {
       const start = args.offset ?? 1;
       const end = args.limit !== undefined ? start + args.limit - 1 : "end";
-      text += theme.fg("warning", ` ${start}-${end}`);
+      params.push(theme.fg("warning", `${start}-${end}`));
     }
 
-    return new Text(text, 0, 0);
+    return params;
   },
   renderResult(result, { expanded }, theme, context) {
     const details = result.details as ModelsDetails | undefined;
@@ -139,7 +138,7 @@ export const modelsAction = defineAction({
     // Convert from 1-indexed offset to 0-indexed array access.
     const startIndex = args.offset ? Math.max(0, args.offset - 1) : 0;
     if (startIndex >= total) {
-      throw new Error(`Offset ${args.offset} is beyond the end of the list (${total} models total).`);
+      throw new Error(`Offset ${args.offset} is beyond the end of the list (${total} models total)`);
     }
 
     const endIndex = args.limit !== undefined ? Math.min(startIndex + args.limit, total) : total;

package/src/features/pi/actions/name.ts

@@ -1,4 +1,4 @@
-import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { sanitizeText } from "../../../utils/format";
@@ -34,19 +34,11 @@ export const nameAction = defineAction({
   promptGuidelines: [
     "Use the pi tool's \"name\" action to give the current session a concise, recognizable name, especially after a long, vague, or pasted opening prompt, or after a substantial shift in the conversation's focus.",
   ],
-  renderCall(args, theme) {
-    const name = sanitizeText(args.name ?? "");
+  renderParams(args, theme) {
+    const name = theme.fg("muted", sanitizeText(args.name ?? ""));
     const reason = sanitizeText(args.reason ?? "");
 
-    const container = new Container();
-    container.addChild(new Text(`${theme.bold(theme.fg("toolTitle", "pi"))} ${theme.fg("accent", "name")} ${theme.fg("muted", name)}`, 0, 0));
-
-    if (reason) {
-      container.addChild(new Spacer(1));
-      container.addChild(new Text(theme.fg("muted", reason), 0, 0));
-    }
-
-    return container;
+    return [reason ? name + theme.fg("muted", "\n\n" + reason) : name];
   },
   renderResult() {
     // "name" has no success UI; errors are rendered by the registry's fallback.
@@ -54,7 +46,7 @@ export const nameAction = defineAction({
   },
   async execute(args, { pi }) {
     const name = sanitizeText(args.name);
-    if (!name) throw new Error("Session name was empty after normalization; provide a short, non-empty phrase.");
+    if (!name) throw new Error("Session name was empty after normalization; provide a short, non-empty phrase");
 
     const previous = pi.getSessionName() ?? null;
     if (previous === name) {

package/src/features/pi/actions/whoami.ts

@@ -15,7 +15,7 @@ interface WhoamiDetails {
 
 export const whoamiAction = defineAction({
   name: "whoami",
-  summary: "shows the current pi state with session name, active model with metadata, and thinking level",
+  summary: "shows the current pi state, including session name, active model, and thinking level",
   fields: {},
   promptGuidelines: [
     "Use the pi tool's \"whoami\" action when you need the current session's name or the active model and thinking level.",

package/src/features/pi/registry.ts

@@ -1,117 +1,28 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { defineActionFor, registerComposedTool } from "../../utils/tool";
 
-import { joinTextContent } from "../../utils/format";
+import type { Action } from "../../utils/tool";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import type { Static, TObject, TProperties, TSchema } from "typebox";
-
-const DESCRIPTION_INTRO =
-  "Inspect and adjust the current pi session and model state. This tool groups self-management " +
-  "actions over the running pi instance:";
-
-const DESCRIPTION_OUTRO = "Use this tool to read or change pi's own state instead of guessing.";
-
-const GENERAL_GUIDELINE =
-  "The pi tool operates only on pi's own session and model state; it does not read or modify the " +
-  "user's project, files, or task.";
-
-interface ActionDetails {
-  action: string;
-}
-
-interface ActionContext {
+interface PiActionContext {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
 }
 
-/**
- * One self-management action of the pi tool, owning its fields, execution, and rendering. The
- * registry merges every action's `fields` into one flat object schema (provider-safe, unlike a
- * discriminated union; see the StringEnum note in pi's extension docs) and dispatches by `action`.
- */
-interface Action<F extends TProperties = TProperties, D extends ActionDetails = ActionDetails> {
-  name: D["action"];
-  summary: string;
-  fields: F;
-  /** Fields required at runtime, since the flat schema makes every action's fields optional. */
-  required?: (keyof F & string)[];
-  /** Guideline bullets contributed to the tool's system-prompt guidelines. */
-  promptGuidelines?: string[];
-  renderCall?: NonNullable<ToolDefinition<TObject<F>, D>["renderCall"]>;
-  renderResult?: NonNullable<ToolDefinition<TObject<F>, D>["renderResult"]>;
-  execute(args: Static<TObject<F>>, context: ActionContext, signal: AbortSignal | undefined): Promise<AgentToolResult<D>>;
-}
-
-/** Identity helper that preserves per-action field and details inference at the definition site. */
-export function defineAction<F extends TProperties, D extends ActionDetails>(action: Action<F, D>): Action<F, D> {
-  return action;
-}
-
-/**
- * Compose the actions into a single flat-schema tool and register it as `pi`. Actions are
- * heterogeneous, so the collection is typed loosely here; type safety lives at each `defineAction`.
- */
-export function registerPiTool(pi: ExtensionAPI, actions: Action<any, any>[]): void {
-  const byName = new Map<string, Action<any, any>>();
-  const mergedFields: TProperties = {};
-
-  for (const action of actions) {
-    if (byName.has(action.name)) throw new Error(`Duplicate pi action "${action.name}".`);
-    byName.set(action.name, action);
+export const defineAction = defineActionFor<PiActionContext>();
 
-    for (const [key, schema] of Object.entries(action.fields)) {
-      if (key === "action") throw new Error(`pi action "${action.name}" must not define a field named "action".`);
-      if (key in mergedFields) throw new Error(`pi action "${action.name}" redefines field "${key}"; field names must be unique across actions.`);
-      mergedFields[key] = Type.Optional(schema as TSchema);
-    }
-  }
-
-  const summaries = actions.map((action) => `"${action.name}" ${action.summary}`).join("; ");
-
-  const parameters = Type.Object({
-    action: StringEnum(actions.map((action) => action.name), { description: "The pi action to run." }),
-    ...mergedFields,
-  });
-
-  pi.registerTool({
+export function registerPiTool(pi: ExtensionAPI, actions: Action<PiActionContext, any, any>[]): void {
+  registerComposedTool<PiActionContext>(pi, {
     name: "pi",
     label: "pi",
-    description: `${DESCRIPTION_INTRO} ${summaries}. ${DESCRIPTION_OUTRO}`,
+    descriptionIntro:
+      "Inspect and adjust the current pi session and model state. This tool groups " +
+      "self-management actions over the running pi instance:",
+    descriptionOutro: "Use this tool to read or change pi's own state instead of guessing.",
     promptSnippet: "Inspect and adjust the current pi session and model state",
-    promptGuidelines: [GENERAL_GUIDELINE, ...actions.flatMap((action) => action.promptGuidelines ?? [])],
-    parameters,
-    renderCall(args, theme, context) {
-      const action = byName.get(args.action);
-      if (action?.renderCall) return action.renderCall(args, theme, context);
-
-      return new Text(`${theme.bold(theme.fg("toolTitle", "pi"))} ${theme.fg("accent", args.action)}`, 0, 0);
-    },
-    renderResult(result, options, theme, context) {
-      const details = result.details as ActionDetails | undefined;
-
-      if (context.isError || !details) {
-        const output = joinTextContent(result.content);
-        return new Text(context.isError && output ? theme.fg("error", "\n" + output) : "", 0, 0);
-      }
-
-      const action = byName.get(details.action);
-      if (action?.renderResult) return action.renderResult(result as AgentToolResult<ActionDetails>, options, theme, context);
-
-      return new Text(joinTextContent(result.content), 0, 0);
-    },
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const action = byName.get(params.action);
-      if (!action) throw new Error(`Unknown pi action "${params.action}".`);
-
-      for (const field of action.required ?? []) {
-        if ((params as Record<string, unknown>)[field] === undefined) {
-          throw new Error(`The "${params.action}" action requires "${field}".`);
-        }
-      }
-
-      return action.execute(params as never, { pi, ctx }, signal);
-    },
+    generalGuidelines: [
+      "The pi tool operates only on pi's own session and model state; it does not read or modify the user's project, files, or task.",
+    ],
+    actions,
+    createContext: (ctx) => ({ pi, ctx }),
   });
 }

package/src/features/web/actions/fetch.ts

@@ -0,0 +1,47 @@
+import { Type } from "typebox";
+
+import { defineAction } from "../registry";
+import { renderWebResult } from "../render";
+
+interface FetchDetails {
+  action: "fetch";
+}
+
+export const fetchAction = defineAction({
+  name: "fetch",
+  summary: "reads the full content of known URLs as clean markdown",
+  showTiming: true,
+  fields: {
+    urls: Type.Optional(Type.Array(Type.String(), {
+      description: "For \"fetch\": List the URLs to read. Batch multiple URLs in one call.",
+    })),
+    maxCharacters: Type.Optional(Type.Number({
+      description: "For \"fetch\": Extract at most this many characters per page (default 3000).",
+    })),
+  },
+  promptGuidelines: [
+    "Use the web tool's \"fetch\" action to read full content from known URLs, batching multiple URLs in one call, especially when search highlights are insufficient.",
+  ],
+  renderParams(args, theme) {
+    const params: string[] = [];
+
+    if (args.urls && args.urls.length > 0) params.push(theme.fg("muted", args.urls.join(", ")));
+    if (args.maxCharacters !== undefined) params.push(theme.fg("warning", `<= ${args.maxCharacters} chars`));
+
+    return params;
+  },
+  renderResult(result, { expanded }, theme) {
+    return renderWebResult(result, expanded, theme);
+  },
+  async execute(args, { exa }, signal) {
+    if (!(args.urls && args.urls.length > 0)) {
+      throw new Error("The \"fetch\" action requires a non-empty \"urls\" array");
+    }
+
+    const requestArgs: Record<string, unknown> = { urls: args.urls };
+    if (args.maxCharacters !== undefined) requestArgs.maxCharacters = args.maxCharacters;
+
+    const content = await exa.call("web_fetch_exa", requestArgs, signal);
+    return { content, details: { action: "fetch" } satisfies FetchDetails };
+  },
+});

package/src/features/web/actions/search.ts

@@ -0,0 +1,50 @@
+import { Type } from "typebox";
+
+import { defineAction } from "../registry";
+import { renderWebResult } from "../render";
+
+interface SearchDetails {
+  action: "search";
+}
+
+export const searchAction = defineAction({
+  name: "search",
+  summary: "finds current information across the web and returns ready-to-use content",
+  showTiming: true,
+  fields: {
+    query: Type.Optional(Type.String({
+      description:
+        "For \"search\": Provide the search query. Use a semantically rich description of the " +
+        "ideal page, not just keywords. Optionally include category:<type> (company, people) " +
+        "to focus results.",
+    })),
+    numResults: Type.Optional(Type.Number({
+      description: "For \"search\": Return at most this many search results (default 10).",
+    })),
+  },
+  promptGuidelines: [
+    "Use the web tool's \"search\" action for current information, news, facts, people, or companies; describe the ideal page rather than keywords (e.g., \"blog post comparing React and Vue performance\").",
+  ],
+  renderParams(args, theme) {
+    const params: string[] = [];
+
+    const query = args.query?.trim();
+    if (query) params.push(theme.fg("muted", query));
+    if (args.numResults !== undefined) params.push(theme.fg("warning", `${args.numResults} results`));
+
+    return params;
+  },
+  renderResult(result, { expanded }, theme) {
+    return renderWebResult(result, expanded, theme);
+  },
+  async execute(args, { exa }, signal) {
+    const query = args.query?.trim();
+    if (!query) throw new Error("The \"search\" action requires a non-empty \"query\"");
+
+    const requestArgs: Record<string, unknown> = { query };
+    if (args.numResults !== undefined) requestArgs.numResults = args.numResults;
+
+    const content = await exa.call("web_search_exa", requestArgs, signal);
+    return { content, details: { action: "search" } satisfies SearchDetails };
+  },
+});

package/src/features/web/client.ts

@@ -38,8 +38,8 @@ export class ExaClient {
       throw new Error(`Exa request failed: ${text}`);
     }
 
-    if (result.isError) throw new Error(`Exa request failed: no content returned.`);
-    if (content.length === 0) throw new Error(`No content returned.`);
+    if (result.isError) throw new Error(`Exa request failed: no content returned`);
+    if (content.length === 0) throw new Error(`No content returned`);
 
     return content;
   }

package/src/features/web/config.ts

@@ -1,5 +1,3 @@
 import * as z from "zod";
 
 export const webConfigSchema = z.object({});
-
-export type WebConfig = z.infer<typeof webConfigSchema>;

package/src/features/web/index.ts

@@ -1,20 +1,16 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { keyText } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
-
 import { ExaClient } from "./client";
+import { fetchAction } from "./actions/fetch";
+import { searchAction } from "./actions/search";
+import { registerWebTool } from "./registry";
 import { loadConfig } from "../../config";
-import { joinTextContent } from "../../utils/format";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-const ACTIONS = {
-  search: { tool: "web_search_exa", fields: ["query", "numResults"] as const },
-  fetch: { tool: "web_fetch_exa", fields: ["urls", "maxCharacters"] as const },
-} as const;
-
-const COLLAPSED_MAX_LINES = 10;
+/** Web actions exposed by the web tool, ordered to match the description (search before fetch). */
+const ACTIONS = [
+  searchAction,
+  fetchAction,
+];
 
 export function registerWeb(pi: ExtensionAPI): void {
   const exa = new ExaClient();
@@ -23,100 +19,7 @@ export function registerWeb(pi: ExtensionAPI): void {
     const config = loadConfig(ctx).web;
     if (!config) return;
 
-    pi.registerTool({
-      name: "web",
-      label: "web",
-      description:
-        "Access the live web via Exa: \"search\" finds current information across the web and " +
-        "returns clean, ready-to-use content; \"fetch\" reads the full content of known URLs " +
-        "as clean markdown.",
-      promptSnippet: "Search the web and fetch page content via Exa",
-      promptGuidelines: [
-        "Use the web tool's \"search\" action for current information, news, facts, people, or companies; describe the ideal page rather than keywords (e.g., \"blog post comparing React and Vue performance\").",
-        "Use the web tool's \"fetch\" action to read full content from known URLs, batching multiple URLs in one call, especially when search highlights are insufficient.",
-      ],
-      parameters: Type.Object({
-        action: StringEnum(["search", "fetch"], {
-          description: "The web action to run.",
-        }),
-        query: Type.Optional(Type.String({
-          description:
-            "For \"search\": the search query. Use a semantically rich description of the ideal " +
-            "page, not just keywords. Optionally include category:<type> (company, people) to " +
-            "focus results."
-        })),
-        numResults: Type.Optional(Type.Number({
-          description: "For \"search\": number of search results (default 10).",
-        })),
-        urls: Type.Optional(Type.Array(Type.String(), {
-          description: "For \"fetch\": URLs to read. Batch multiple URLs in one call.",
-        })),
-        maxCharacters: Type.Optional(Type.Number({
-          description: "For \"fetch\": maximum characters to extract per page (default 3000).",
-        })),
-      }),
-      renderCall(args, theme) {
-        let text = `${theme.bold(theme.fg("toolTitle", "web"))} ${theme.fg("success", args.action)}`;
-
-        if (args.action === "search") {
-          const query = args.query?.trim();
-          if (query) text += ` ${theme.fg("muted", query)}`;
-          if (args.numResults !== undefined) text += ` ${theme.fg("warning", `${args.numResults} results`)}`;
-        } else if (args.action === "fetch") {
-          if (args.urls && args.urls.length > 0) text += ` ${theme.fg("muted", `${args.urls.join(", ")}`)}`;
-          if (args.maxCharacters !== undefined) text += ` ${theme.fg("warning", `<= ${args.maxCharacters} chars`)}`;
-        }
-
-        return new Text(text, 0, 0);
-      },
-      renderResult(result, { expanded }, theme, context) {
-        const container = new Container();
-        container.addChild(new Spacer(1));
-
-        const text = joinTextContent(result.content);
-
-        if (context.isError) {
-          container.addChild(new Text(theme.fg("error", text || "Web request failed."), 0, 0));
-          return container;
-        }
-
-        const lines = text.length > 0 ? text.split("\n") : [];
-        if (lines.length === 0) {
-          container.addChild(new Text(theme.fg("muted", "(no content returned)"), 0, 0));
-          return container;
-        }
-
-        const maxLines = expanded ? lines.length : Math.min(lines.length, COLLAPSED_MAX_LINES);
-        container.addChild(new Text(theme.fg("muted", lines.slice(0, maxLines).join("\n")), 0, 0));
-
-        const hidden = lines.length - maxLines;
-        if (hidden > 0) {
-          container.addChild(new Text(theme.fg("dim", `... (${hidden} more lines, ${keyText("app.tools.expand")} to expand)`), 0, 0));
-        }
-
-        return container;
-      },
-      async execute(_toolCallId, params, signal) {
-        const action = ACTIONS[params.action as keyof typeof ACTIONS];
-        if (!action) throw new Error(`Unknown web action "${params.action}".`);
-
-        if (params.action === "search" && !params.query?.trim()) {
-          throw new Error("The \"search\" action requires a non-empty \"query\".");
-        }
-        if (params.action === "fetch" && !(params.urls && params.urls.length > 0)) {
-          throw new Error("The \"fetch\" action requires a non-empty \"urls\" array.");
-        }
-
-        const args: Record<string, unknown> = {};
-        for (const field of action.fields) {
-          const value = (params as Record<string, unknown>)[field];
-          if (value !== undefined) args[field] = value;
-        }
-
-        const content = await exa.call(action.tool, args, signal);
-        return { content, details: { action: params.action } };
-      },
-    });
+    registerWebTool(pi, exa, ACTIONS);
   });
 
   pi.on("session_shutdown", () => {

package/src/features/web/registry.ts

@@ -0,0 +1,22 @@
+import { defineActionFor, registerComposedTool } from "../../utils/tool";
+
+import type { ExaClient } from "./client";
+import type { Action } from "../../utils/tool";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+interface WebActionContext {
+  exa: ExaClient;
+}
+
+export const defineAction = defineActionFor<WebActionContext>();
+
+export function registerWebTool(pi: ExtensionAPI, exa: ExaClient, actions: Action<WebActionContext, any, any>[]): void {
+  registerComposedTool<WebActionContext>(pi, {
+    name: "web",
+    label: "web",
+    descriptionIntro: "Access the live web via Exa:",
+    promptSnippet: "Search the web and fetch page content via Exa",
+    actions,
+    createContext: () => ({ exa }),
+  });
+}

package/src/features/web/render.ts

@@ -0,0 +1,34 @@
+import { keyText } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+
+import { joinTextContent } from "../../utils/format";
+
+import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
+
+const COLLAPSED_MAX_LINES = 10;
+
+/**
+ * Render a web result's text content with collapse-to-expand behavior. Shared by the `search` and
+ * `fetch` actions, which both return plain text content. Errors are handled by the registry's
+ * fallback renderer, so this only covers the success path.
+ */
+export function renderWebResult(result: AgentToolResult<unknown>, expanded: boolean, theme: Theme): Container {
+  const container = new Container();
+  container.addChild(new Spacer(1));
+
+  const text = joinTextContent(result.content);
+  const lines = text.length > 0 ? text.split("\n") : [];
+
+  if (lines.length === 0) {
+    container.addChild(new Text(theme.fg("muted", "No content returned."), 0, 0));
+    return container;
+  }
+
+  const maxLines = expanded ? lines.length : Math.min(lines.length, COLLAPSED_MAX_LINES);
+  container.addChild(new Text(theme.fg("muted", lines.slice(0, maxLines).join("\n")), 0, 0));
+
+  const hidden = lines.length - maxLines;
+  if (hidden > 0) container.addChild(new Text(theme.fg("dim", `... (${hidden} more lines, ${keyText("app.tools.expand")} to expand)`), 0, 0));
+
+  return container;
+}

package/src/utils/format.ts

@@ -28,6 +28,11 @@ export function formatCost(cost: number): string {
   return `$${cost.toFixed(2)}`;
 }
 
+/** Format a duration in ms as `1.2s`, like the built-in bash tool. */
+export function formatDuration(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
 export function formatCwd(cwd: string, home: string): string {
   const resolvedCwd = resolve(cwd);
   const resolvedHome = resolve(home);

package/src/utils/tool.ts

@@ -0,0 +1,209 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { formatDuration, joinTextContent } from "./format";
+
+import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import type { Static, TObject, TProperties, TSchema } from "typebox";
+
+interface ActionDetails {
+  action: string;
+}
+
+/**
+ * One action of a composed tool. The registry merges all actions' `fields` into one flat schema
+ * (provider-safe, unlike a discriminated union) and dispatches by `action`; `C` is the per-call
+ * context from `createContext`.
+ */
+export interface Action<C, F extends TProperties = TProperties, D extends ActionDetails = ActionDetails> {
+  name: D["action"];
+  summary: string;
+  fields: F;
+  /** Fields required at runtime (the flat schema makes all fields optional). */
+  required?: (keyof F & string)[];
+  promptGuidelines?: string[];
+  /** Show bash-style elapsed/took timing for this action. */
+  showTiming?: boolean;
+  /** Styled segments shown after the `<tool> <action>` prefix. */
+  renderParams?: (args: Static<TObject<F>>, theme: Theme) => string[];
+  renderResult?: NonNullable<ToolDefinition<TObject<F>, D>["renderResult"]>;
+  execute(args: Static<TObject<F>>, context: C, signal: AbortSignal | undefined): Promise<AgentToolResult<D>>;
+}
+
+/** Identity helper bound to context `C`, so actions infer their field/details types while sharing one context shape. */
+export function defineActionFor<C>() {
+  return <F extends TProperties, D extends ActionDetails>(action: Action<C, F, D>): Action<C, F, D> => action;
+}
+
+interface ComposedToolConfig<C> {
+  name: string;
+  label: string;
+  descriptionIntro: string;
+  descriptionOutro?: string;
+  promptSnippet: string;
+  generalGuidelines?: string[];
+  actions: Action<C, any, any>[];
+  createContext(ctx: ExtensionContext): C;
+}
+
+export function registerComposedTool<C>(pi: ExtensionAPI, config: ComposedToolConfig<C>): void {
+  const byName = new Map<string, Action<C, any, any>>();
+  const mergedFields: TProperties = {};
+
+  for (const action of config.actions) {
+    if (byName.has(action.name)) throw new Error(`Duplicate "${config.name}" action "${action.name}"`);
+    byName.set(action.name, action);
+
+    for (const [key, schema] of Object.entries(action.fields)) {
+      if (key === "action") throw new Error(`"${config.name}" action "${action.name}" must not define a field named "action"`);
+      if (key in mergedFields) throw new Error(`"${config.name}" action "${action.name}" redefines field "${key}"; field names must be unique across actions`);
+      mergedFields[key] = Type.Optional(schema as TSchema);
+    }
+  }
+
+  const summaries = config.actions.map((action) => `"${action.name}" ${action.summary}`).join("; ");
+  const description = config.descriptionOutro
+    ? `${config.descriptionIntro} ${summaries}. ${config.descriptionOutro}`
+    : `${config.descriptionIntro} ${summaries}.`;
+
+  const parameters = Type.Object({
+    action: StringEnum(config.actions.map((action) => action.name), { description: `The ${config.name} action to run.` }),
+    ...mergedFields,
+  });
+
+  const activeTiming = new ActiveTiming();
+  const noTiming = new NoTiming();
+  // Resolve per-action timing from the stable call args, so error results (no details) still settle.
+  const timingFor = (action: string | undefined): Timing => (byName.get(action ?? "")?.showTiming ? activeTiming : noTiming);
+
+  const renderActionResult: NonNullable<ToolDefinition["renderResult"]> = (result, options, theme, context) => {
+    const details = result.details as ActionDetails | undefined;
+
+    if (context.isError || !details) {
+      const output = joinTextContent(result.content);
+      return new Text(context.isError && output ? theme.fg("error", "\n" + output) : "", 0, 0);
+    }
+
+    const action = byName.get(details.action);
+    if (action?.renderResult) return action.renderResult(result as AgentToolResult<ActionDetails>, options, theme, context as never);
+
+    return new Text(joinTextContent(result.content), 0, 0);
+  };
+
+  pi.registerTool({
+    name: config.name,
+    label: config.label,
+    description,
+    promptSnippet: config.promptSnippet,
+    promptGuidelines: [...(config.generalGuidelines ?? []), ...config.actions.flatMap((action) => action.promptGuidelines ?? [])],
+    parameters,
+    renderCall(args, theme, context) {
+      const segments = [theme.bold(theme.fg("toolTitle", config.name)), theme.fg("accent", args.action)];
+      const params = byName.get(args.action)?.renderParams?.(args, theme);
+      if (params) segments.push(...params);
+
+      return timingFor(context.args.action).renderCall(new Text(segments.join(" "), 0, 0), theme, context);
+    },
+    renderResult(result, options, theme, context) {
+      const inner = renderActionResult(result, options, theme, context);
+
+      return timingFor(context.args.action).renderResult(inner, options, theme, context);
+    },
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const action = byName.get(params.action);
+      if (!action) throw new Error(`Unknown ${config.name} action "${params.action}"`);
+
+      for (const field of action.required ?? []) {
+        if ((params as Record<string, unknown>)[field] === undefined) {
+          throw new Error(`The "${params.action}" action requires "${field}"`);
+        }
+      }
+
+      return action.execute(params as never, config.createContext(ctx), signal);
+    },
+  });
+}
+
+/** A tuple type without its first element. */
+type DropFirst<T extends readonly unknown[]> = T extends readonly [unknown, ...infer R] ? R : never;
+
+/** A renderer's params after the leading args/result. */
+type RenderCallTail = DropFirst<Parameters<NonNullable<ToolDefinition["renderCall"]>>>;
+type RenderResultTail = DropFirst<Parameters<NonNullable<ToolDefinition["renderResult"]>>>;
+
+/**
+ * Bash-style timing for a tool row: a live "Elapsed" ticker while running, a final "Took" once
+ * settled. `renderCall`/`renderResult` wrap the built component in place of the args/result.
+ */
+interface Timing {
+  renderCall(inner: Component, ...rest: RenderCallTail): Component;
+  renderResult(inner: Component, ...rest: RenderResultTail): Component;
+}
+
+/** Per-row timing state, kept in `ToolRenderContext.state` so the timing classes stay stateless. */
+interface TimingState {
+  startedAt?: number;
+  endedAt?: number;
+  interval?: ReturnType<typeof setInterval>;
+}
+
+class ActiveTiming implements Timing {
+  renderCall(inner: Component, ...[theme, context]: RenderCallTail): Component {
+    const state = context.state as TimingState;
+    if (context.executionStarted && state.startedAt === undefined) {
+      state.startedAt = Date.now();
+      delete state.endedAt;
+    }
+
+    // Result is in: renderResult owns the timing line, so just settle here.
+    if (!context.isPartial) {
+      this.settle(state);
+      return inner;
+    }
+
+    // Still running, no result yet: show a live "Elapsed" line, ticking once a second.
+    if (state.startedAt === undefined) return inner;
+
+    state.interval ??= setInterval(() => context.invalidate(), 1000);
+    return this.withTimingLine(inner, "Elapsed", Date.now() - state.startedAt, theme);
+  }
+
+  renderResult(inner: Component, ...[options, theme, context]: RenderResultTail): Component {
+    const state = context.state as TimingState;
+    if (!options.isPartial || context.isError) this.settle(state);
+    if (state.startedAt === undefined) return inner;
+
+    const label = options.isPartial ? "Elapsed" : "Took";
+    const endTime = state.endedAt ?? Date.now();
+    return this.withTimingLine(inner, label, endTime - state.startedAt, theme);
+  }
+
+  private settle(state: TimingState): void {
+    if (state.startedAt !== undefined) state.endedAt ??= Date.now();
+    if (state.interval) {
+      clearInterval(state.interval);
+      delete state.interval;
+    }
+  }
+
+  private withTimingLine(content: Component, label: string, ms: number, theme: Theme): Container {
+    const container = new Container();
+    container.addChild(content);
+
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(`${theme.fg("muted", `${label} ${formatDuration(ms)}`)}`, 0, 0));
+
+    return container;
+  }
+}
+
+class NoTiming implements Timing {
+  renderCall(inner: Component): Component {
+    return inner;
+  }
+  renderResult(inner: Component): Component {
+    return inner;
+  }
+}