pi-spark 0.14.3 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.14.3",
+  "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/registry.ts

@@ -1,6 +1,6 @@
-import { defineActionFor, registerComposedTool } from "../../utils/tools";
+import { defineActionFor, registerComposedTool } from "../../utils/tool";
 
-import type { Action } from "../../utils/tools";
+import type { Action } from "../../utils/tool";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 interface PiActionContext {

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

@@ -10,6 +10,7 @@ interface FetchDetails {
 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.",

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

@@ -10,6 +10,7 @@ interface SearchDetails {
 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:

package/src/features/web/registry.ts

@@ -1,7 +1,7 @@
-import { defineActionFor, registerComposedTool } from "../../utils/tools";
+import { defineActionFor, registerComposedTool } from "../../utils/tool";
 
 import type { ExaClient } from "./client";
-import type { Action } from "../../utils/tools";
+import type { Action } from "../../utils/tool";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 interface WebActionContext {

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;
+  }
+}

package/src/utils/tools.ts

@@ -1,118 +0,0 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
-
-import { joinTextContent } from "./format";
-
-import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import type { Static, TObject, TProperties, TSchema } from "typebox";
-
-interface ActionDetails {
-  action: string;
-}
-
-/**
- * One action of a composed tool. 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`. `C` is the per-call context the host feature builds via
- * `ComposedToolConfig.createContext`.
- */
-export interface Action<C, 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)[];
-  promptGuidelines?: string[];
-  /** Styled segments shown after the `<tool> <action>` prefix in the call line. */
-  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>>;
-}
-
-/**
- * Build an identity helper bound to a context type `C`. Each feature creates one
- * (`const defineAction = defineActionFor<MyContext>()`) so its actions infer their own field and
- * details types while sharing a single 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,
-  });
-
-  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) {
-      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 new Text(segments.join(" "), 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 ${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);
-    },
-  });
-}