@herbertgao/pi-subagents 0.17.1 → 0.18.0

package/src/ui/workflow-menu.ts

@@ -0,0 +1,226 @@
+/**
+ * workflow-menu.ts — `/agents → Workflows`, and the run inspector behind it.
+ *
+ * The same shape `schedule-menu.ts` has for `/agents → Scheduled jobs`: the
+ * submenu and the overlay it opens live here, and everything they need arrives
+ * as {@link WorkflowMenuDeps} rather than through a closure. The inspector is
+ * reached from two places — this menu and a `workflow` row in the fleet list —
+ * and both go through `showWorkflowDialog`, so the two entry points cannot
+ * drift apart on what the keys do.
+ *
+ * Lives in the agents menu rather than as a top-level `/workflows` command: it
+ * is one more view of the same fleet, and a second command name would only add
+ * a collision surface (pi renames duplicate commands to `/workflows:1` and
+ * `/workflows:2`, which breaks the bare name for both).
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent"
+import type { AgentRecord } from "../types.js"
+import {
+  pauseWorkflowTask,
+  resumeWorkflowTask,
+  type WorkflowTask,
+} from "../workflow/task.js"
+import { WorkflowDialog } from "./workflow-dialog.js"
+
+/** Everything the menu and the inspector need from the extension around them. */
+export interface WorkflowMenuDeps {
+  /**
+   * Live runs by id, read on every use rather than snapshotted: a run that
+   * settled and was swept between render and keypress must be a no-op, not a
+   * crash.
+   */
+  tasks: ReadonlyMap<string, WorkflowTask>
+  /** The record behind an agent id, or undefined once it has been swept. */
+  getRecord(id: string): AgentRecord | undefined
+  /** The conversation overlay `c` opens on an agent row. */
+  viewAgentConversation(
+    ctx: ExtensionCommandContext,
+    record: AgentRecord,
+  ): Promise<void>
+  /**
+   * The session context, for the fleet-list entry point — that one is a
+   * keypress in a list that holds no `ctx` of its own. Undefined between
+   * sessions, which is a no-op rather than an error.
+   */
+  getCtx(): ExtensionCommandContext | undefined
+}
+
+/**
+ * Open the inspector for a workflow run.
+ *
+ * All six controls are wired: `onKill` aborts the run's controller, while
+ * pause/resume and per-agent skip/retry go through `task.control`, the handle
+ * `runWorkflow` hands back. `onOpenAgent` is the odd one out — it opens the
+ * child's conversation rather than changing the run. The dialog derives its key
+ * hints from the actions it is handed, so the footer advertises exactly what
+ * works — see `WorkflowDialogActions`.
+ */
+export async function showWorkflowDialog(
+  ctx: ExtensionCommandContext,
+  task: WorkflowTask,
+  deps: WorkflowMenuDeps,
+): Promise<void> {
+  // Overlaid on the same terms as the conversation viewer, because they are
+  // reached the same way: both are rows of the fleet list, and opening one
+  // must not behave unlike opening the other. Inline, the frame would render
+  // into the conversation and stay in the scrollback after it closed.
+  const { VIEWPORT_HEIGHT_PCT } = await import("./conversation-viewer.js")
+  /**
+   * This dialog's own overlay, so `c` can hide it while the conversation is
+   * up. Overlays stack, so the viewer would render *over* it either way —
+   * but the two frames size themselves to different content, and the taller
+   * one's edges show around the shorter. Hidden, there is nothing to peek
+   * out, and un-hiding puts the focus back on the dialog when the viewer
+   * closes.
+   */
+  let overlay: { setHidden(hidden: boolean): void } | undefined
+  await ctx.ui.custom<undefined>(
+    (tui, theme, _keybindings, done) =>
+      new WorkflowDialog(
+        tui,
+        // Re-read on every render: the run is in the background, so the
+        // dialog has to follow it rather than snapshot it at open time.
+        () => ({
+          progress: task.workflowProgress,
+          task: {
+            status: task.status,
+            workflowName: task.workflowName,
+            startTime: task.startTime,
+            endTime: task.endTime,
+            totalPausedMs: task.totalPausedMs,
+          },
+          meta: task.meta,
+          agentCount: task.agentCount,
+        }),
+        theme,
+        done,
+        {
+          onKill: () => {
+            if (task.abortController.signal.aborted) return
+            task.abortController.abort()
+            ctx.ui.notify(
+              `Stopped workflow "${task.meta?.name ?? task.id}".`,
+              "info",
+            )
+          },
+          onPause: () => {
+            if (pauseWorkflowTask(task)) {
+              // Named rather than implied: "paused" on a run whose agents are
+              // still finishing reads as a stronger promise than it is.
+              ctx.ui.notify(
+                "Paused — running agents finish, no new ones start.",
+                "info",
+              )
+            }
+          },
+          onResume: () => {
+            if (resumeWorkflowTask(task)) ctx.ui.notify("Resumed.", "info")
+          },
+          onSkipAgent: (index) => {
+            if (task.control?.skip(index) !== true) {
+              ctx.ui.notify(
+                "Nothing to skip — that agent has already finished.",
+                "info",
+              )
+            }
+          },
+          onRetryAgent: (index) => {
+            if (task.control?.retry(index) !== true) {
+              // The window is exactly "while it is running": before that
+              // there is nothing to stop, after it the script has its answer.
+              ctx.ui.notify("Only a running agent can be retried.", "info")
+            }
+          },
+          onOpenAgent: (recordId) => {
+            const record = deps.getRecord(recordId)
+            // A run's children are records like any other, so they are swept
+            // ten minutes after they finish — the row outlives the
+            // conversation it points at, and saying why beats an overlay that
+            // opens empty.
+            if (record === undefined) {
+              ctx.ui.notify(
+                "No conversation left — agent records are dropped ten minutes after they finish.",
+                "info",
+              )
+              return
+            }
+            overlay?.setHidden(true)
+            // Caught before the `finally`, so a viewer that fails to open
+            // still un-hides the dialog and cannot surface as an unhandled
+            // rejection out of a detached promise.
+            void deps
+              .viewAgentConversation(ctx, record)
+              .catch((err) =>
+                ctx.ui.notify(
+                  `Could not open the conversation: ${err instanceof Error ? err.message : String(err)}`,
+                  "warning",
+                ),
+              )
+              .finally(() => overlay?.setHidden(false))
+          },
+        },
+      ),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "90%",
+        maxHeight: `${VIEWPORT_HEIGHT_PCT}%`,
+      },
+      onHandle: (handle) => {
+        overlay = handle
+      },
+    },
+  )
+}
+
+/**
+ * Open a run from the fleet list.
+ *
+ * The list hands back an id rather than a task, so a run that settled and was
+ * swept between render and keypress is a no-op instead of a crash. `esc` in the
+ * dialog closes it and control returns to the list — which is why the promise
+ * is handed back: the list puts the cursor back on the run rather than dropping
+ * the reader at `main`.
+ */
+export function openWorkflowFromFleet(
+  id: string,
+  deps: WorkflowMenuDeps,
+): Promise<void> | void {
+  const task = deps.tasks.get(id)
+  const ctx = deps.getCtx()
+  if (task === undefined || ctx === undefined) return
+  return showWorkflowDialog(ctx, task, deps)
+}
+
+/** `/agents → Workflows` — list this session's runs, open one. */
+export async function showWorkflowsMenu(
+  ctx: ExtensionCommandContext,
+  deps: WorkflowMenuDeps,
+): Promise<void> {
+  const tasks = [...deps.tasks.values()].sort(
+    (a, b) => b.startTime - a.startTime,
+  )
+  if (tasks.length === 0) {
+    ctx.ui.notify("No workflows in this session.", "info")
+    return
+  }
+  if (tasks.length === 1) {
+    await showWorkflowDialog(ctx, tasks[0], deps)
+    return
+  }
+  // More than one: pick first. Newest at the top, since that is almost
+  // always the one being asked about. `select` deals in plain strings and
+  // hands back the string, so the label has to be unique or `indexOf` maps
+  // the second run of a workflow onto the first — the run id makes it so.
+  const labels = tasks.map(
+    (task) =>
+      `${task.meta?.name ?? task.id} — ${task.status}, ${task.agentCount} agent${
+        task.agentCount === 1 ? "" : "s"
+      } · ${task.id}`,
+  )
+  const picked = await ctx.ui.select("Workflows", labels)
+  const index = picked !== undefined ? labels.indexOf(picked) : -1
+  if (index >= 0) await showWorkflowDialog(ctx, tasks[index], deps)
+}

package/src/workflow/collisions.ts

@@ -0,0 +1,122 @@
+/**
+ * collisions.ts — deciding what to do when another extension already offers a
+ * workflow tool.
+ *
+ * Workflows are on by default, so this extension can be the *second*
+ * orchestrator in a session rather than the only one. Two workflow tools in one
+ * spec is worse than either alone: the model has to guess which to call, and
+ * pays for both descriptions to find out. The other extension was installed
+ * deliberately; a default of ours should not compete with it.
+ *
+ * ## What counts as a conflict
+ *
+ * An exact name match against {@link FOREIGN_WORKFLOW_TOOL_NAMES}, from a tool
+ * that is not ours. Exact and not a substring on purpose: `Workflow` is a
+ * common word in tool names that have nothing to do with orchestration
+ * (`github_workflow_run`, `list_workflows`), and silently disabling the feature
+ * against one of those would be a bug nobody could see.
+ *
+ * Two shapes, both decided here:
+ *
+ * 1. **A foreign tool took our name.** Registration is first-wins across
+ *    extensions (`getAllRegisteredTools` skips a name it already has), and the
+ *    winner also overwrites a built-in of the same name. Nothing throws, and
+ *    there is no tool-conflict diagnostic the way there is for shortcuts. Ours
+ *    never reached the registry, so there is nothing to withdraw — but the rest
+ *    of the feature (the menu, the CLI flag) is still live and would drive a
+ *    tool the model cannot call. It comes down with it.
+ * 2. **A foreign tool sits beside ours** under a different name, typically
+ *    Claude Code's bare `Workflow`. Both are registered and both are offered.
+ *    That one the caller can actually withdraw — `withdraw` says so.
+ *
+ * Only one direction of case 1 is detectable. If ours registered first, the
+ * other extension's tool is the one dropped, and pi exposes no way to see a
+ * tool that lost — the registry keeps winners only.
+ *
+ * Split from the acting half deliberately: everything here is a pure function
+ * of the tool list, so the policy can be tested without a host that can be made
+ * to register a competing extension. The caller owns `getAllTools`, the notify
+ * and the `setActiveTools` — see `resolveWorkflowCollisions` in index.ts.
+ */
+
+import { SUBAGENT_TOOL_NAMES } from "../agent-runner.js"
+
+/**
+ * Tool names that mean "another extension already orchestrates subagents".
+ *
+ * Our own name, because pi resolves a duplicate registration silently, and
+ * Claude Code's bare `Workflow`, because a port of that tool is what a second
+ * workflow extension most likely calls itself.
+ */
+export const FOREIGN_WORKFLOW_TOOL_NAMES: ReadonlySet<string> = new Set([
+  SUBAGENT_TOOL_NAMES.WORKFLOW,
+  "Workflow",
+])
+
+/** The fields of a registered tool this decision reads. */
+export interface RegisteredToolInfo {
+  name: string
+  description?: string
+  sourceInfo?: { source?: string }
+}
+
+export type WorkflowCollision =
+  /** Nobody else is offering one. Carry on. */
+  | { kind: "none" }
+  /**
+   * A foreign tool took our name, but the user pinned `workflowsEnabled: true`.
+   * Nothing changes — pi has already dropped our registration — but it is worth
+   * reporting, because pi resolved it silently.
+   */
+  | { kind: "report"; message: string }
+  /**
+   * Stand down for this session. `withdraw` is false in case 1, where ours
+   * never reached the registry and there is nothing to take out of the active
+   * set.
+   */
+  | { kind: "standDown"; message: string; withdraw: boolean }
+
+/**
+ * Decide, from the registered tools alone.
+ *
+ * `ownDescription` identifies our own registration: this extension does not
+ * know its install path, and the description is the one field that is certainly
+ * ours. `pinned` is an explicit `workflowsEnabled` — a default yields to
+ * evidence, a choice does not.
+ */
+export function decideWorkflowCollision(input: {
+  tools: readonly RegisteredToolInfo[]
+  ownDescription: string
+  pinned: boolean
+}): WorkflowCollision {
+  const foreign = input.tools.find(
+    (tool) =>
+      FOREIGN_WORKFLOW_TOOL_NAMES.has(tool.name) &&
+      tool.description !== input.ownDescription,
+  )
+  if (foreign === undefined) return { kind: "none" }
+
+  const source = foreign.sourceInfo?.source ?? "unknown source"
+  const tookOurName = foreign.name === SUBAGENT_TOOL_NAMES.WORKFLOW
+
+  if (input.pinned) {
+    if (!tookOurName) return { kind: "none" }
+    return {
+      kind: "report",
+      message:
+        `Another extension (${source}) already registers a "${SUBAGENT_TOOL_NAMES.WORKFLOW}" tool. ` +
+        "Pi keeps the first registration, so this extension's workflow tool is not offered to the " +
+        "model. Disable one of the two.",
+    }
+  }
+
+  return {
+    kind: "standDown",
+    message:
+      `Another extension (${source}) already provides a "${foreign.name}" tool, so this extension's ` +
+      "workflows are disabled for this session to avoid offering the model two orchestrators. " +
+      'Set `"workflowsEnabled": true` in .pi/subagents.json to keep both.',
+    // Case 1: ours never reached the registry, so there is nothing to withdraw.
+    withdraw: !tookOurName,
+  }
+}

package/src/workflow/entry.ts

@@ -0,0 +1,47 @@
+/**
+ * entry.ts — what a finished workflow leaves behind in the session transcript.
+ *
+ * A workflow started from `--subagents-workflow-file` has no tool call to hang
+ * its result card on, so it appends a custom session entry instead. That entry
+ * has to survive a reload, which is why this is a plain-JSON snapshot rather
+ * than the live {@link WorkflowTask}: the task holds an `AbortController`, the
+ * script source and the run's control handle, none of which belongs in a
+ * session file.
+ *
+ * Deliberately free of any renderer import. The card this data renders through
+ * lives in `ui/workflow-card.ts` (`renderWorkflowEntryCard`), so the shape a
+ * session file stores does not depend on the code that draws it.
+ */
+
+import type { WorkflowMeta } from "./meta.js"
+import type { WorkflowEntry, WorkflowRunStatus } from "./progress.js"
+import type { WorkflowTask } from "./task.js"
+
+/** `customType` of the session entry a flag-launched workflow renders through. */
+export const WORKFLOW_ENTRY_TYPE = "subagents:workflow"
+
+/** The persisted snapshot of a settled run. */
+export interface WorkflowEntryData {
+  name: string
+  status: WorkflowRunStatus
+  startTime: number
+  endTime?: number
+  progress: WorkflowEntry[]
+  agentCount: number
+  totalTokens: number
+  meta?: WorkflowMeta
+}
+
+/** Snapshot a settled task for {@link WORKFLOW_ENTRY_TYPE}. */
+export function workflowEntryData(task: WorkflowTask): WorkflowEntryData {
+  return {
+    name: task.workflowName ?? task.id,
+    status: task.status,
+    startTime: task.startTime,
+    endTime: task.endTime,
+    progress: task.workflowProgress,
+    agentCount: task.agentCount,
+    totalTokens: task.totalTokens,
+    ...(task.meta !== undefined ? { meta: task.meta } : {}),
+  }
+}