@trevonistrevon/pi-loop 0.6.3 → 0.6.4

package/src/tools/loop-tools.ts

@@ -2,8 +2,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { formatTrigger } from "../loop-format.js";
 import { parseInterval } from "../loop-parse.js";
-import type { LoopEntry, Trigger } from "../types.js";
-import { textResult } from "./tool-result.js";
+import type { LoopEntry, Trigger, WorkflowDefinition } from "../types.js";
+import { renderToolCall, renderToolResult, toolArg } from "../ui/tool-renderer.js";
+import { validateWorkflowDefinition } from "../workflow-reducer.js";
+import { displayRows, textResult } from "./tool-result.js";
 
 interface LoopStoreLike {
   list(): LoopEntry[];
@@ -14,9 +16,18 @@ interface LoopStoreLike {
     taskBacklog?: boolean;
     readOnly?: boolean;
     maxFires?: number;
+    dynamic?: Partial<NonNullable<LoopEntry["dynamic"]>>;
+    workflow?: WorkflowDefinition;
   }): LoopEntry;
   pause(id: string): LoopEntry | undefined;
   updateDynamic(id: string, fields: { prompt?: string; dynamic: Partial<NonNullable<LoopEntry["dynamic"]>> }): LoopEntry | undefined;
+  transitionWorkflow(id: string, input: { outcome: string; evidence?: string; activeTaskId?: string }): {
+    entry?: LoopEntry;
+    applied: boolean;
+    error?: string;
+    terminal?: "completed" | "paused";
+  };
+  setWorkflowActiveTask(id: string, taskId?: string): LoopEntry | undefined;
   getDeletionTombstone(id: string): { reason: string; pendingCount?: number } | undefined;
   delete(id: string): boolean;
 }
@@ -48,6 +59,9 @@ export interface LoopToolsOptions {
   updateWidget: () => void;
   maybeBootstrapTaskLoop: (entry: LoopEntry) => Promise<boolean>;
   isTaskSystemReady: () => boolean;
+  onDynamicLoopActivated?: (entry: LoopEntry) => void;
+  createWorkflowTask?: (entry: LoopEntry) => Promise<string | undefined>;
+  completeWorkflowTask?: (taskId: string) => Promise<boolean>;
 }
 
 function validateTrigger(trigger: Trigger): string | null {
@@ -111,6 +125,57 @@ function resolveNextWakeAt(nextInterval?: string): { nextWakeAt?: number; error?
   return { nextWakeAt: Date.now() + parsedDelayMs };
 }
 
+function parseWorkflowDefinition(input: string): { definition?: WorkflowDefinition; error?: string } {
+  try {
+    const parsed = JSON.parse(input) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { error: "Workflow definition must be a JSON object" };
+    }
+    const definition = parsed as WorkflowDefinition;
+    const validationError = validateWorkflowDefinition(definition);
+    return validationError ? { error: validationError } : { definition };
+  } catch {
+    return { error: "Workflow definition must be valid JSON" };
+  }
+}
+
+const WORKFLOW_DEFINITION_EXAMPLE =
+  '{"version":1,"initialState":"investigate","states":{"investigate":{"prompt":"Investigate the issue.","on":{"found":"done"}},"done":{"prompt":"Report completion.","terminal":"completed"}}}';
+
+function formatWorkflowDefinitionError(error: string | undefined): string {
+  return `Workflow definition rejected: ${error ?? "unknown validation error"}\n` +
+    "Required fields: version: 1, initialState, and states.\n" +
+    `Example definition:\n${WORKFLOW_DEFINITION_EXAMPLE}\n` +
+    "Next: correct the JSON and call WorkflowCreate again.";
+}
+
+function formatWorkflowSummary(entry: LoopEntry, heading: string): string {
+  const workflow = entry.workflow!;
+  const state = workflow.definition.states[workflow.currentState];
+  const outcomes = Object.keys(state?.on ?? {});
+  let message = `${heading}\nGoal: ${entry.prompt}\nCurrent state: ${workflow.currentState}`;
+  if (state?.prompt) message += `\nInstruction: ${state.prompt}`;
+  if (workflow.activeTaskId) {
+    message += `\nActive task: #${workflow.activeTaskId}`;
+  } else if (state?.task) {
+    message += "\nTask: no task was created for this state";
+  } else {
+    message += "\nTask: none configured for this state";
+  }
+
+  if (state?.terminal) {
+    message += `\nTerminal: ${state.terminal}`;
+    return message;
+  }
+  if (outcomes.length === 0) {
+    return `${message}\nNeeds attention: this state has no declared outcomes, so it cannot advance.`;
+  }
+
+  message += `\nChoose outcome: ${outcomes.join(", ")}`;
+  message += `\nNext: WorkflowTransition({ id: "${entry.id}", outcome: "${outcomes[0]}", evidence: "..." })`;
+  return message;
+}
+
 function formatDynamicUpdateResult(id: string, iteration: number | undefined, nextWakeAt: number | undefined): string {
   const mode = nextWakeAt === undefined
     ? "Next wake: when idle"
@@ -178,11 +243,16 @@ export function registerLoopTools(options: LoopToolsOptions): void {
     updateWidget,
     maybeBootstrapTaskLoop,
     isTaskSystemReady,
+    onDynamicLoopActivated,
+    createWorkflowTask,
+    completeWorkflowTask,
   } = options;
 
   pi.registerTool({
     name: "LoopCreate",
     label: "LoopCreate",
+    renderCall: renderToolCall("Loop", (args) => `create · ${String(toolArg(args, "prompt") ?? "scheduled work").slice(0, 56)}`),
+    renderResult: renderToolResult,
     description: `Create a scheduled repeating task (loop) that runs a prompt on a timer or when an event fires.
 
 Use this tool whenever the user asks to:
@@ -275,7 +345,15 @@ Recurring loops persist across fires. A completed iteration, unchanged result, o
       }
 
       const validationError = validateTrigger(trigger);
-      if (validationError) return Promise.resolve(textResult(validationError));
+      if (validationError) {
+        return Promise.resolve(textResult(validationError, {
+          kind: "loop",
+          action: "create",
+          tone: "error",
+          summary: "Loop was not created",
+          expanded: [validationError],
+        }));
+      }
 
       const entry = getStore().create(trigger, prompt, {
         recurring: recurring ?? (inferred !== "event"),
@@ -316,7 +394,224 @@ Recurring loops persist across fires. A completed iteration, unchanged result, o
         (entry.taskBacklog ? "Backlog worker: enabled\n" : "") +
         (bootstrapped ? "Backlog: initial wake queued for existing pending tasks\n" : "") +
         (isTaskSystemReady() ? "" : "Task system: not ready yet — autoTask may not fire until native fallback or pi-tasks becomes available\n") +
-        `ID: ${entry.id} (persists until explicitly canceled or a configured stop condition is met)`
+        `ID: ${entry.id} (persists until explicitly canceled or a configured stop condition is met)`,
+        {
+          kind: "loop",
+          action: "create",
+          tone: "success",
+          summary: `Loop #${entry.id} active · ${triggerDesc}`,
+          expanded: [
+            `Goal: ${entry.prompt}`,
+            `Trigger: ${triggerDesc}`,
+            entry.autoTask ? "Auto-task: enabled" : "Auto-task: off",
+          ],
+        },
+      ));
+    },
+  });
+
+  pi.registerTool({
+    name: "WorkflowCreate",
+    label: "WorkflowCreate",
+    renderCall: renderToolCall("Workflow", (args) => `create · ${String(toolArg(args, "goal") ?? "workflow").slice(0, 56)}`),
+    renderResult: renderToolResult,
+    description: `Create an opt-in task-driven workflow loop from a JSON state definition.
+
+Use this when work has named phases and explicit outcomes, such as investigate → fix → validate. Use LoopCreate for ordinary scheduled/event work and TaskCreate for a normal flat backlog.
+
+The definition requires version: 1, initialState, and states. Each state has a prompt, optional on outcome-to-state map, optional maxAttempts, and an optional terminal value of completed or paused.`,
+    promptGuidelines: [
+      "Use WorkflowCreate only for explicit multi-phase work with stable named outcomes; ordinary reminders, polling, and task backlogs should remain loops or tasks.",
+      "Pass `definition` as valid JSON. Give each non-terminal state a concise prompt and explicit outcome names, for example `root_cause_found` or `tests_pass`.",
+      "After each workflow wake, call WorkflowTransition with the workflow `id` and one declared `outcome`; include concise `evidence` whenever a branch is chosen.",
+    ],
+    parameters: Type.Object({
+      goal: Type.String({ description: "Overall workflow goal" }),
+      definition: Type.String({ description: "Workflow JSON: version, initialState, and named states" }),
+      maxFires: Type.Optional(Type.Number({ description: "Maximum workflow wakes before automatic expiry (default: 30)", default: 30 })),
+    }),
+    async execute(_toolCallId, params) {
+      const parsed = parseWorkflowDefinition(params.definition);
+      if (!parsed.definition) {
+        const message = formatWorkflowDefinitionError(parsed.error);
+        return textResult(message, {
+          kind: "workflow",
+          action: "create",
+          tone: "error",
+          summary: "Workflow definition rejected",
+          expanded: [parsed.error ?? "unknown validation error", "Expand the tool result for a valid definition skeleton."],
+        });
+      }
+
+      let entry = getStore().create({ type: "dynamic" }, params.goal, {
+        recurring: true,
+        maxFires: params.maxFires ?? 30,
+        dynamic: { goal: params.goal, state: parsed.definition.initialState, iteration: 0 },
+        workflow: parsed.definition,
+      });
+      const taskId = await createWorkflowTask?.(entry);
+      if (taskId) entry = getStore().setWorkflowActiveTask(entry.id, taskId) ?? entry;
+      getTriggerSystem().add(entry);
+      updateWidget();
+      onDynamicLoopActivated?.(entry);
+      return textResult(
+        `${formatWorkflowSummary(entry, `Workflow #${entry.id} created — ${entry.status}`)}\n` +
+        "Wake: the state instruction will be delivered when the agent becomes idle.",
+        {
+          kind: "workflow",
+          action: "create",
+          tone: "success",
+          summary: `Workflow #${entry.id} active · ${parsed.definition.initialState}${taskId ? ` · task #${taskId}` : ""}`,
+          expanded: [
+            `Goal: ${entry.prompt}`,
+            `State: ${parsed.definition.initialState}`,
+            `Outcome: ${Object.keys(parsed.definition.states[parsed.definition.initialState]?.on ?? {}).join(", ") || "none"}`,
+            "Wake: delivered when the agent becomes idle",
+          ],
+        },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "WorkflowTransition",
+    label: "WorkflowTransition",
+    renderCall: renderToolCall("Workflow", (args) => `transition · #${String(toolArg(args, "id") ?? "?")} → ${String(toolArg(args, "outcome") ?? "?")}`),
+    renderResult: renderToolResult,
+    description: `Advance an opt-in workflow using one declared outcome.
+
+Use exactly once after completing the current workflow state. The outcome must be declared in the current state's on map. Include evidence for the branch decision. This tool validates the transition, records it, and queues the next state; it completes or pauses terminal workflows automatically.`,
+    promptGuidelines: [
+      "WorkflowTransition uses `id`, not `loopId`.",
+      "Use an exact outcome name declared by the current state. Do not invent an outcome; inspect the wake message or WorkflowList first.",
+      "Include `evidence` that justifies the transition, especially for completion, regression, or blocked outcomes.",
+    ],
+    parameters: Type.Object({
+      id: Type.String({ description: "Workflow loop ID" }),
+      outcome: Type.String({ description: "Declared outcome for the current workflow state" }),
+      evidence: Type.Optional(Type.String({ description: "Concise evidence supporting this transition" })),
+      activeTaskId: Type.Optional(Type.String({ description: "Optional task ID now active in the destination state" })),
+    }),
+    async execute(_toolCallId, params) {
+      const store = getStore();
+      const sourceTaskId = store.get(params.id)?.workflow?.activeTaskId;
+      const result = store.transitionWorkflow(params.id, {
+        outcome: params.outcome,
+        evidence: params.evidence,
+        activeTaskId: params.activeTaskId,
+      });
+      if (!result.applied || !result.entry) {
+        const current = store.get(params.id);
+        if (current?.workflow) {
+          return textResult(
+            `Workflow #${params.id} did not transition\n` +
+            `Reason: ${result.error ?? "unknown transition error"}\n` +
+            formatWorkflowSummary(current, `Workflow #${params.id} remains — ${current.status}`),
+            {
+              kind: "workflow",
+              action: "transition",
+              tone: "error",
+              summary: `Workflow #${params.id} remains in ${current.workflow.currentState}`,
+              expanded: [result.error ?? "unknown transition error"],
+            },
+          );
+        }
+        return textResult(result.error ?? `Workflow loop #${params.id} did not transition`);
+      }
+
+      const entry = result.entry;
+      getTriggerSystem().remove(entry.id);
+      const sourceTaskClosed = sourceTaskId ? await completeWorkflowTask?.(sourceTaskId) : undefined;
+      if (result.terminal === "completed") {
+        store.delete(entry.id);
+        updateWidget();
+        return textResult(
+          `Workflow #${entry.id} completed and deleted\n` +
+          `Final transition: ${entry.workflow?.lastTransition?.from ?? "?"} → ${entry.workflow?.currentState ?? "?"}\n` +
+          "Next: no further workflow transition is needed.",
+          {
+            kind: "workflow",
+            action: "transition",
+            tone: "success",
+            summary: `Workflow #${entry.id} completed${sourceTaskClosed ? ` · task #${sourceTaskId} closed` : ""}`,
+            expanded: [
+              `Final transition: ${entry.workflow?.lastTransition?.from ?? "?"} → ${entry.workflow?.currentState ?? "?"}`,
+              sourceTaskId ? `Source task #${sourceTaskId}: ${sourceTaskClosed ? "completed" : "not completed"}` : "Source task: none",
+            ],
+          },
+        );
+      }
+      if (result.terminal === "paused") {
+        store.pause(entry.id);
+        updateWidget();
+        return textResult(
+          `Workflow #${entry.id} paused\n` +
+          `Final state: ${entry.workflow?.currentState ?? "?"}\n` +
+          "Next: inspect it with WorkflowList before deciding whether to resume or delete it.",
+          {
+            kind: "workflow",
+            action: "transition",
+            tone: "warning",
+            summary: `Workflow #${entry.id} paused · ${entry.workflow?.currentState ?? "?"}`,
+            expanded: [
+              sourceTaskId ? `Source task #${sourceTaskId}: ${sourceTaskClosed ? "completed" : "not completed"}` : "Source task: none",
+              "Inspect WorkflowList before resuming or deleting this workflow.",
+            ],
+          },
+        );
+      }
+
+      const taskId = await createWorkflowTask?.(entry);
+      const updatedEntry = taskId ? store.setWorkflowActiveTask(entry.id, taskId) ?? entry : entry;
+      getTriggerSystem().add(updatedEntry);
+      updateWidget();
+      const from = updatedEntry.workflow?.lastTransition?.from ?? "?";
+      const to = updatedEntry.workflow?.currentState ?? "?";
+      return textResult(
+        `Workflow #${updatedEntry.id} advanced: ${from} → ${to}\n` +
+        formatWorkflowSummary(updatedEntry, `Workflow #${updatedEntry.id} — ${updatedEntry.status}`),
+        {
+          kind: "workflow",
+          action: "transition",
+          tone: "success",
+          summary: `Workflow #${updatedEntry.id} · ${from} → ${to}${taskId ? ` · task #${taskId}` : ""}`,
+          expanded: [
+            `Instruction: ${updatedEntry.workflow?.definition.states[to]?.prompt ?? ""}`,
+            `Outcome: ${Object.keys(updatedEntry.workflow?.definition.states[to]?.on ?? {}).join(", ") || "none"}`,
+            sourceTaskId ? `Source task #${sourceTaskId}: ${sourceTaskClosed ? "completed" : "not completed"}` : "Source task: none",
+          ],
+        },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "WorkflowList",
+    label: "WorkflowList",
+    renderCall: renderToolCall("Workflow", () => "status"),
+    renderResult: renderToolResult,
+    description: "List opt-in workflow loops with their current state, active task, and declared outcomes. Use this before WorkflowTransition when the current state is unclear.",
+    parameters: Type.Object({}),
+    execute() {
+      const workflows = getStore().list().filter((entry) => entry.workflow);
+      if (workflows.length === 0) {
+        return Promise.resolve(textResult(
+          "No workflow loops configured.\n" +
+          "Next: use WorkflowCreate for explicit state-and-outcome work, or LoopCreate for an ordinary schedule.",
+          { kind: "workflow", action: "list", tone: "info", summary: "No workflows", expanded: ["Use WorkflowCreate for state-and-outcome work."] },
+        ));
+      }
+
+      const lines = workflows.map((entry) => formatWorkflowSummary(entry, `Workflow #${entry.id} — ${entry.status}`));
+      return Promise.resolve(textResult(
+        `${workflows.length} workflow${workflows.length === 1 ? "" : "s"} configured\n\n${lines.join("\n\n")}`,
+        {
+          kind: "workflow",
+          action: "list",
+          tone: "info",
+          summary: `${workflows.length} workflow${workflows.length === 1 ? "" : "s"} · ${workflows.filter((entry) => entry.status === "active").length} active`,
+          expanded: displayRows(workflows.map((entry) => `#${entry.id} · ${entry.status} · ${entry.workflow?.currentState ?? "?"} · ${entry.prompt}`)),
+        },
       ));
     },
   });
@@ -324,13 +619,19 @@ Recurring loops persist across fires. A completed iteration, unchanged result, o
   pi.registerTool({
     name: "LoopList",
     label: "LoopList",
+    renderCall: renderToolCall("Loop", () => "status"),
+    renderResult: renderToolResult,
     description: `List all active scheduled loops with their IDs, triggers, and next-fire times.
 
 Use this before creating new loops to avoid duplicates, or to find IDs for LoopDelete.`,
     parameters: Type.Object({}),
     execute() {
       const loops = getStore().list();
-      if (loops.length === 0) return Promise.resolve(textResult("No loops configured. Use LoopCreate to set up a schedule."));
+      if (loops.length === 0) {
+        return Promise.resolve(textResult("No loops configured. Use LoopCreate to set up a schedule.", {
+          kind: "loop", action: "list", tone: "info", summary: "No loops", expanded: ["Use LoopCreate to set up a schedule."],
+        }));
+      }
 
       const lines: string[] = [];
       for (const entry of loops) {
@@ -346,16 +647,25 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
         }
         if (entry.autoTask) line += " [auto-task]";
         if (entry.taskBacklog) line += " [backlog-worker]";
+        if (entry.workflow) line += ` [workflow:${entry.workflow.currentState}]`;
         lines.push(line);
       }
 
-      return Promise.resolve(textResult(lines.join("\n")));
+      return Promise.resolve(textResult(lines.join("\n"), {
+        kind: "loop",
+        action: "list",
+        tone: "info",
+        summary: `${loops.length} loop${loops.length === 1 ? "" : "s"} · ${loops.filter((entry) => entry.status === "active").length} active`,
+        expanded: displayRows(lines),
+      }));
     },
   });
 
   pi.registerTool({
     name: "LoopUpdate",
     label: "LoopUpdate",
+    renderCall: renderToolCall("Loop", (args) => `update · #${String(toolArg(args, "id") ?? "?")} · ${String(toolArg(args, "status") ?? "continue")}`),
+    renderResult: renderToolResult,
     description: `Update progress for a dynamic loop.
 
 Use this exactly once after each dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval whenever any work remains, "completed" only when the overall goal and done criteria are satisfied, or "paused" when genuinely blocked. Do not use LoopDelete to finish an iteration.`,
@@ -372,22 +682,44 @@ Use this exactly once after each dynamic loop wake. Mark status as "continue" wi
       const store = getStore();
       const triggerSystem = getTriggerSystem();
       const entry = store.get(params.id);
-      if (!entry) return Promise.resolve(textResult(`Loop #${params.id} not found`));
+      if (!entry) {
+        return Promise.resolve(textResult(`Loop #${params.id} not found`, {
+          kind: "loop", action: "update", tone: "error", summary: `Loop #${params.id} not found`, expanded: ["Use LoopList to find valid loop IDs."],
+        }));
+      }
       if (entry.trigger.type !== "dynamic" || !entry.dynamic) {
-        return Promise.resolve(textResult(`Loop #${params.id} is not a dynamic loop`));
+        return Promise.resolve(textResult(`Loop #${params.id} is not a dynamic loop`, {
+          kind: "loop", action: "update", tone: "error", summary: `Loop #${params.id} is not dynamic`, expanded: ["Use LoopUpdate only for dynamic loops."],
+        }));
       }
 
       const message = params.status === "continue"
         ? continueDynamicLoop(params, entry as LoopEntry & { dynamic: NonNullable<LoopEntry["dynamic"]> }, store, triggerSystem)
         : stopDynamicLoop(params, store, triggerSystem);
       updateWidget();
-      return Promise.resolve(textResult(message));
+      const tone = params.status === "paused" ? "warning" : "success";
+      const summary = params.status === "completed"
+        ? `Loop #${params.id} completed`
+        : params.status === "paused"
+          ? `Loop #${params.id} paused`
+          : `Loop #${params.id} updated`;
+      return Promise.resolve(textResult(message, {
+        kind: "loop",
+        action: "update",
+        tone,
+        summary,
+        expanded: params.status === "continue"
+          ? [`State: ${params.state ?? entry.dynamic.state ?? "unchanged"}`, `Next wake: ${params.nextInterval ?? "when idle"}`]
+          : [],
+      }));
     },
   });
 
   pi.registerTool({
     name: "LoopDelete",
     label: "LoopDelete",
+    renderCall: renderToolCall("Loop", (args) => `${String(toolArg(args, "action") ?? "delete")} · #${String(toolArg(args, "id") ?? "?")}`),
+    renderResult: renderToolResult,
     description: `Delete or pause a loop by its ID.
 
 Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.
@@ -404,21 +736,39 @@ Do not use this after a normal loop fire, an unchanged check, an empty iteration
         const entry = getStore().pause(id);
         if (!entry) {
           const tombstone = getStore().getDeletionTombstone(id);
-          if (tombstone) return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
-          return Promise.resolve(textResult(`Loop #${id} not found`));
+          if (tombstone) {
+            return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone), {
+              kind: "loop", action: "pause", tone: "warning", summary: `Loop #${id} was already removed`, expanded: [formatDeletionTombstone(id, tombstone)],
+            }));
+          }
+          return Promise.resolve(textResult(`Loop #${id} not found`, {
+            kind: "loop", action: "pause", tone: "error", summary: `Loop #${id} not found`, expanded: ["Use LoopList to find valid loop IDs."],
+          }));
         }
         getTriggerSystem().remove(id);
         updateWidget();
-        return Promise.resolve(textResult(`Loop #${id} paused`));
+        return Promise.resolve(textResult(`Loop #${id} paused`, {
+          kind: "loop", action: "pause", tone: "warning", summary: `Loop #${id} paused`, expanded: ["Use LoopList to inspect paused loops."],
+        }));
       }
 
       getTriggerSystem().remove(id);
       const deleted = getStore().delete(id);
       updateWidget();
-      if (deleted) return Promise.resolve(textResult(`Loop #${id} deleted`));
+      if (deleted) {
+        return Promise.resolve(textResult(`Loop #${id} deleted`, {
+          kind: "loop", action: "delete", tone: "success", summary: `Loop #${id} deleted`, expanded: [],
+        }));
+      }
       const tombstone = getStore().getDeletionTombstone(id);
-      if (tombstone) return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
-      return Promise.resolve(textResult(`Loop #${id} not found`));
+      if (tombstone) {
+        return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone), {
+          kind: "loop", action: "delete", tone: "warning", summary: `Loop #${id} was already removed`, expanded: [formatDeletionTombstone(id, tombstone)],
+        }));
+      }
+      return Promise.resolve(textResult(`Loop #${id} not found`, {
+        kind: "loop", action: "delete", tone: "error", summary: `Loop #${id} not found`, expanded: ["Use LoopList to find valid loop IDs."],
+      }));
     },
   });
 }

package/src/tools/monitor-tools.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { LoopEntry, MonitorEntry, Trigger } from "../types.js";
-import { textResult } from "./tool-result.js";
+import { renderToolCall, renderToolResult, toolArg } from "../ui/tool-renderer.js";
+import { displayRows, textResult } from "./tool-result.js";
 
 interface MonitorManagerLike {
   list(): MonitorEntry[];
@@ -39,6 +40,8 @@ export function registerMonitorTools(options: MonitorToolsOptions): void {
   pi.registerTool({
     name: "MonitorCreate",
     label: "MonitorCreate",
+    renderCall: renderToolCall("Monitor", (args) => `start · ${String(toolArg(args, "description") ?? toolArg(args, "command") ?? "monitor").slice(0, 56)}`),
+    renderResult: renderToolResult,
     description: `Run a shell command in the background and get notified when it finishes. The core tool for async/parallel work.
 
 Fire off a build check, CI monitor, experiment, script, or any slow command — then keep working. Output streams back as "monitor:output" events. When the process exits, "monitor:done" fires (or "monitor:error" on failure).
@@ -71,7 +74,9 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
     }),
     execute(_toolCallId, params) {
       if (getMonitorManager().list().filter((m) => m.status === "running").length >= 25) {
-        return Promise.resolve(textResult("Maximum of 25 running monitors reached. Stop some before creating new ones."));
+        return Promise.resolve(textResult("Maximum of 25 running monitors reached. Stop some before creating new ones.", {
+          kind: "monitor", action: "create", tone: "error", summary: "Monitor limit reached", expanded: ["Stop a running monitor before starting another."],
+        }));
       }
 
       const entry = getMonitorManager().create(params.command, params.description, params.timeout);
@@ -97,7 +102,18 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
       return Promise.resolve(textResult(
         `Monitor #${entry.id} started: ${entry.command.slice(0, 60)}\n` +
         `Output stream: monitor:output (monitorId: ${entry.id})\n` +
-        `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}${onDoneMsg}`
+        `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}${onDoneMsg}`,
+        {
+          kind: "monitor",
+          action: "create",
+          tone: "success",
+          summary: `Monitor #${entry.id} running · ${params.description ?? entry.command.slice(0, 48)}`,
+          expanded: [
+            `Command: ${entry.command}`,
+            `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}`,
+            params.onDone ? "Completion wake: enabled" : "Completion wake: off",
+          ],
+        },
       ));
     },
   });
@@ -105,11 +121,17 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
   pi.registerTool({
     name: "MonitorList",
     label: "MonitorList",
+    renderCall: renderToolCall("Monitor", () => "status"),
+    renderResult: renderToolResult,
     description: "List all monitors with their status, command, exit code, output line count, and last 5 lines of buffered output.",
     parameters: Type.Object({}),
     execute() {
       const monitors = getMonitorManager().list();
-      if (monitors.length === 0) return Promise.resolve(textResult("No monitors."));
+      if (monitors.length === 0) {
+        return Promise.resolve(textResult("No monitors.", {
+          kind: "monitor", action: "list", tone: "info", summary: "No monitors", expanded: ["Use MonitorCreate for long-running background work."],
+        }));
+      }
 
       const lines: string[] = [];
       for (const m of monitors) {
@@ -128,13 +150,22 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
         }
       }
 
-      return Promise.resolve(textResult(lines.join("\n")));
+      const running = monitors.filter((monitor) => monitor.status === "running").length;
+      return Promise.resolve(textResult(lines.join("\n"), {
+        kind: "monitor",
+        action: "list",
+        tone: "info",
+        summary: `${monitors.length} monitor${monitors.length === 1 ? "" : "s"} · ${running} running`,
+        expanded: displayRows(lines),
+      }));
     },
   });
 
   pi.registerTool({
     name: "MonitorStop",
     label: "MonitorStop",
+    renderCall: renderToolCall("Monitor", (args) => `stop · #${String(toolArg(args, "monitorId") ?? "?")}`),
+    renderResult: renderToolResult,
     description: `Stop a running monitor. Sends SIGTERM, waits 5s, then SIGKILL.
 
 Use MonitorList to find the monitor ID, then stop it with this tool.`,
@@ -144,8 +175,14 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
     async execute(_toolCallId, params) {
       const stopped = await getMonitorManager().stop(params.monitorId);
       updateWidget();
-      if (stopped) return textResult(`Monitor #${params.monitorId} stopped`);
-      return textResult(`Monitor #${params.monitorId} not found or not running`);
+      if (stopped) {
+        return textResult(`Monitor #${params.monitorId} stopped`, {
+          kind: "monitor", action: "stop", tone: "success", summary: `Monitor #${params.monitorId} stopped`, expanded: [],
+        });
+      }
+      return textResult(`Monitor #${params.monitorId} not found or not running`, {
+        kind: "monitor", action: "stop", tone: "error", summary: `Monitor #${params.monitorId} unavailable`, expanded: ["Use MonitorList to find running monitor IDs."],
+      });
     },
   });
 }