@herbertgao/pi-subagents 0.17.1 → 0.18.0

package/src/workflow/saved.ts

@@ -0,0 +1,230 @@
+/**
+ * saved.ts — resolve `SubagentWorkflow({ name })` to a script on disk.
+ *
+ * A saved workflow is a plain `.js` file whose contents are exactly what
+ * `script` would have carried. Nothing is parsed here: `extractMeta` still runs
+ * over the source at the call site, so a saved file and an inline one fail the
+ * same way on a bad `meta` block.
+ *
+ * Roots mirror `loadCustomAgents` rather than inventing a fourth convention —
+ * project `.pi` is the authority, the shared `.agents` workspace is an extra
+ * read location, and the user's agent dir is the fallback:
+ *
+ *   1. <cwd>/.pi/workflows/<name>.js
+ *   2. <cwd>/.agents/workflows/<name>.js
+ *   3. getAgentDir()/workflows/<name>.js   (default ~/.pi/agent/workflows)
+ *
+ * Precedence is expressed as first-hit-wins here, not last-write-wins as in the
+ * agent loader, because a name resolves to one file — there is no map to
+ * overwrite.
+ *
+ * Symlinks are rejected through `safeReadFile`, and the name is whitelisted
+ * before it is ever joined to a path: `name` arrives from a model, and
+ * `../../etc/passwd` must not become a readable workflow.
+ *
+ * ## Not every `.js` in the folder is a workflow
+ *
+ * These are ordinary directories. `.agents/workflows/` is shared across tools
+ * and the user's agent dir is theirs to fill; either may hold a build artifact,
+ * a config, or a scratch script. A file is only treated as a workflow if it
+ * carries the `export const meta =` declaration every workflow opens with.
+ *
+ * Nothing is ever executed to decide this — the check is a regex over the
+ * source, and even the real parse only evaluates the `meta` object literal in
+ * an empty vm. What the filter buys is honesty: a listing that offers `utils.js`
+ * as a runnable workflow invites the model to try it, and naming it should say
+ * "that is not a workflow" rather than produce a parser error about a block the
+ * author never intended to write.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { isAbsolute, join } from "node:path"
+import { getAgentDir } from "@earendil-works/pi-coding-agent"
+import { isSymlink, isUnsafeName, safeReadFile } from "../memory.js"
+import { hasMetaDeclaration } from "./meta.js"
+import { MAX_SCRIPT_LENGTH } from "./runtime.js"
+
+/** Extension a saved workflow file carries. */
+const WORKFLOW_EXTENSION = ".js"
+
+/** The roots a `name` is looked up in, highest priority first. */
+export function savedWorkflowRoots(cwd: string): string[] {
+  return [
+    join(cwd, ".pi", "workflows"),
+    join(cwd, ".agents", "workflows"),
+    join(getAgentDir(), "workflows"),
+  ]
+}
+
+export type SavedWorkflow =
+  | { ok: true; script: string; path: string }
+  | { ok: false; message: string }
+
+/**
+ * Read the saved workflow called `name`.
+ *
+ * Failure carries the roots that were searched and, when there are any, the
+ * names that do exist — a model that guessed the name can correct itself from
+ * the error instead of spending a turn asking.
+ */
+export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
+  const trimmed = name.trim()
+  if (isUnsafeName(trimmed)) {
+    return {
+      ok: false,
+      message:
+        `"${name}" is not a usable workflow name. Use letters, digits, dots, hyphens and underscores only ` +
+        "— a path is what `scriptPath` is for.",
+    }
+  }
+
+  const roots = savedWorkflowRoots(cwd)
+  for (const root of roots) {
+    if (isSymlink(root)) continue // reject a symlinked root entirely, as skill-loader does
+    const path = join(root, `${trimmed}${WORKFLOW_EXTENSION}`)
+    const script = safeReadFile(path)
+    if (script === undefined) continue
+    // Found the file, so stop looking — a shadowing name that turns out not to
+    // be a workflow is worth reporting, not worth silently reaching past.
+    if (!hasMetaDeclaration(script)) {
+      return {
+        ok: false,
+        message:
+          `"${path}" is not a workflow script — it has no \`export const meta = { name, description }\` ` +
+          "declaration. Nothing was run.",
+      }
+    }
+    return { ok: true, script, path }
+  }
+
+  const known = listSavedWorkflows(cwd)
+  return {
+    ok: false,
+    message:
+      `No saved workflow named "${trimmed}". Looked in: ${roots.join(", ")}. ` +
+      (known.length > 0
+        ? `Available: ${known.join(", ")}.`
+        : "Save one as `<name>.js` in one of those directories, or pass `script`/`scriptPath` instead."),
+  }
+}
+
+/**
+ * Resolve a reference — a saved name, or a path — to source.
+ *
+ * The one place that decides what a reference means, so the tool's `name` /
+ * `scriptPath` parameters and a script's nested `workflow()` cannot drift apart
+ * on precedence or on what counts as a workflow.
+ */
+export function resolveWorkflowSource(
+  ref: { name?: string; scriptPath?: string },
+  cwd: string,
+): SavedWorkflow {
+  const path = ref.scriptPath?.trim()
+  if (path !== undefined && path !== "") {
+    const resolved = isAbsolute(path) ? path : join(cwd, path)
+    try {
+      return {
+        ok: true,
+        script: readFileSync(resolved, "utf-8"),
+        path: resolved,
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        message: `Could not read workflow script "${resolved}": ${err instanceof Error ? err.message : String(err)}`,
+      }
+    }
+  }
+  const name = ref.name?.trim()
+  if (name !== undefined && name !== "") return readSavedWorkflow(name, cwd)
+  return {
+    ok: false,
+    message: "A workflow reference needs a `name` or a `scriptPath`.",
+  }
+}
+
+/** Every saved workflow name, de-duplicated across roots and sorted. */
+export function listSavedWorkflows(cwd: string): string[] {
+  const names = new Set<string>()
+  for (const root of savedWorkflowRoots(cwd)) {
+    if (!existsSync(root) || isSymlink(root)) continue
+    let entries: string[]
+    try {
+      entries = readdirSync(root)
+    } catch {
+      continue // an unreadable root is not worth failing a lookup over
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(WORKFLOW_EXTENSION)) continue
+      const name = entry.slice(0, -WORKFLOW_EXTENSION.length)
+      if (isUnsafeName(name)) continue
+      if (isWorkflowFile(join(root, entry))) names.add(name)
+    }
+  }
+  return [...names].sort()
+}
+
+/**
+ * Whether the file at `path` is a workflow rather than some other script.
+ *
+ * Size-guarded before reading: the listing runs over a whole directory, and a
+ * file too large to be a workflow at all should not be pulled into memory just
+ * to check its first line.
+ */
+function isWorkflowFile(path: string): boolean {
+  try {
+    if (statSync(path).size > MAX_SCRIPT_LENGTH) return false
+  } catch {
+    return false
+  }
+  const source = safeReadFile(path)
+  return source !== undefined && hasMetaDeclaration(source)
+}
+
+/**
+ * Resolve which source a `SubagentWorkflow` call runs.
+ *
+ * `scriptPath` wins over `script`, which wins over `name` — Claude Code's
+ * order — and at least one is required: a call with none is a mistake worth
+ * naming rather than an empty run. Lives beside {@link resolveWorkflowSource}
+ * because that is the function it defers to once precedence is settled, so the
+ * two cannot disagree about what a reference means.
+ */
+export function resolveWorkflowScript(
+  params: { script?: string; scriptPath?: string; name?: string },
+  cwd: string,
+):
+  | { ok: true; script: string; scriptPath?: string }
+  | { ok: false; message: string } {
+  const path = params.scriptPath?.trim()
+  if (path !== undefined && path !== "") {
+    const resolved = resolveWorkflowSource({ scriptPath: path }, cwd)
+    return resolved.ok
+      ? { ok: true, script: resolved.script, scriptPath: resolved.path }
+      : resolved
+  }
+  const script = params.script
+  if (script !== undefined && script.trim() !== "") return { ok: true, script }
+
+  // A saved workflow is the same source by another route, so it reports its
+  // file as `scriptPath`: the "edit the file and re-run" loop then works on a
+  // named workflow without the author having to find where it lives. Shared
+  // with a script's nested `workflow()`, so one definition decides what a
+  // reference means.
+  const name = params.name?.trim()
+  if (name !== undefined && name !== "") {
+    const saved = resolveWorkflowSource({ name }, cwd)
+    return saved.ok
+      ? { ok: true, script: saved.script, scriptPath: saved.path }
+      : saved
+  }
+
+  const known = listSavedWorkflows(cwd)
+  return {
+    ok: false,
+    message:
+      "Provide `script` (inline source), `scriptPath` (a file to read), or `name` (a saved workflow). " +
+      "`scriptPath` takes precedence, then `script`, then `name`." +
+      (known.length > 0 ? ` Saved workflows: ${known.join(", ")}.` : ""),
+  }
+}

package/src/workflow/task.ts

@@ -0,0 +1,333 @@
+/**
+ * task.ts — the background record one workflow run lives in.
+ *
+ * A `SubagentWorkflow` tool call returns a task id immediately and the run continues
+ * without it, so the run's state cannot live in the tool call's closure: the
+ * inline card, the completion notification and (later) the `/agents → Workflows` dialog
+ * all read it after `execute` has returned. This is that record, shaped after
+ * Claude Code's `local_workflow` task so the fields line up with what the
+ * renderers already expect.
+ *
+ * The progress log is append-only and collapses by index (see `progress.ts`),
+ * so every derived counter here is recomputed from the log rather than
+ * incremented as entries arrive — a re-emitted agent entry replaces its
+ * predecessor, and adding its tokens on top would double-count them.
+ */
+
+import { randomUUID } from "node:crypto"
+import { escapeXml } from "../xml.js"
+import type { WorkflowJournalEntry } from "./journal.js"
+import type { WorkflowMeta } from "./meta.js"
+import {
+  collapse,
+  elapsedMs,
+  stats,
+  type WorkflowEntry,
+  type WorkflowRunStatus,
+} from "./progress.js"
+import type { WorkflowControl, WorkflowRunResult } from "./runtime.js"
+
+/** `wf_` + hex, matching Claude Code's `^wf_[a-z0-9-]{6,}$` run ids. */
+export function workflowRunId(): string {
+  return `wf_${randomUUID().replace(/-/g, "").slice(0, 12)}`
+}
+
+export interface WorkflowTask {
+  /** Discriminator, alongside Claude Code's `local_agent` / `local_bash`. */
+  type: "local_workflow"
+  id: string
+  status: WorkflowRunStatus
+  script: string
+  /** Where the script can be edited and re-run from. */
+  scriptPath?: string
+  args?: unknown
+  meta?: WorkflowMeta
+  workflowName?: string
+  /** The `tool_use_id` of the call that started this, when one did. */
+  toolCallId?: string
+
+  /**
+   * Pause, skip and retry, once the run is up.
+   *
+   * Absent before the runtime hands it over and after the run settles — the
+   * dialog treats "no control" as "those keys do nothing", which is the same
+   * thing it does for a run that has finished.
+   */
+  control?: WorkflowControl
+  /** When the current pause started, so `totalPausedMs` can be closed out. */
+  pausedAt?: number
+
+  /** Where this run records its own settled calls, for a later resume. */
+  journalPath?: string
+  /** A previous run's journal, when this call asked to resume one. */
+  replay?: readonly WorkflowJournalEntry[]
+  /** The run id this one resumed, for the result line that says so. */
+  resumedFrom?: string
+  /** How many agents came back from {@link replay} instead of being spawned. */
+  replayedCount: number
+
+  /** The append-only event log, in emission order. */
+  workflowProgress: WorkflowEntry[]
+  /** Bumped once per applied batch, so a renderer can tell nothing changed. */
+  progressVersion: number
+  agentCount: number
+  /**
+   * Agents that have settled successfully, recomputed with the other counters.
+   *
+   * Cached rather than derived on read because the fleet list asks five times a
+   * second: deriving it there would walk the whole append-only log on every
+   * tick, which for a thousand-agent run is real work in the render loop.
+   */
+  doneCount: number
+  totalTokens: number
+  totalToolCalls: number
+  logs: string[]
+
+  abortController: AbortController
+  startTime: number
+  endTime?: number
+  /** Excluded from the elapsed clock the header shows. */
+  totalPausedMs: number
+
+  /** The script's return value, once the run produced one. */
+  value?: unknown
+  error?: string
+}
+
+export function createWorkflowTask(init: {
+  id: string
+  script: string
+  scriptPath?: string
+  args?: unknown
+  meta?: WorkflowMeta
+  toolCallId?: string
+  startTime?: number
+  journalPath?: string
+  replay?: readonly WorkflowJournalEntry[]
+  resumedFrom?: string
+}): WorkflowTask {
+  return {
+    type: "local_workflow",
+    id: init.id,
+    status: "running",
+    script: init.script,
+    scriptPath: init.scriptPath,
+    args: init.args,
+    meta: init.meta,
+    workflowName: init.meta?.name,
+    toolCallId: init.toolCallId,
+    journalPath: init.journalPath,
+    replay: init.replay,
+    resumedFrom: init.resumedFrom,
+    replayedCount: 0,
+    workflowProgress: [],
+    progressVersion: 0,
+    agentCount: 0,
+    doneCount: 0,
+    totalTokens: 0,
+    totalToolCalls: 0,
+    logs: [],
+    abortController: new AbortController(),
+    startTime: init.startTime ?? Date.now(),
+    totalPausedMs: 0,
+  }
+}
+
+/**
+ * Apply one batch of progress entries.
+ *
+ * Batched rather than per-entry because that is how the worker emits them, and
+ * because every counter below is an O(log) recompute — doing it once per fan-out
+ * frame instead of once per agent is the difference that keeps a 200-agent run
+ * cheap to render.
+ */
+export function updateWorkflowProgressBatch(
+  task: WorkflowTask,
+  entries: readonly WorkflowEntry[],
+): void {
+  if (entries.length === 0) return
+  task.workflowProgress.push(...entries)
+  task.progressVersion++
+
+  const { agents, logs } = collapse(task.workflowProgress)
+  task.logs = logs
+  // `agentCount` is what the runtime has scheduled, which can lead what the log
+  // has seen — never let a recompute walk it backwards.
+  task.agentCount = Math.max(task.agentCount, agents.length)
+
+  let totalTokens = 0
+  let totalToolCalls = 0
+  let done = 0
+  for (const agent of agents) {
+    totalTokens += agent.tokens ?? 0
+    totalToolCalls += agent.toolCalls ?? 0
+    // Counted off the collapsed agents, so a re-emitted row counts once.
+    if (agent.state === "done") done++
+  }
+  task.totalTokens = totalTokens
+  task.totalToolCalls = totalToolCalls
+  task.doneCount = done
+}
+
+/**
+ * Hold the run, and stop its clock.
+ *
+ * The elapsed figure every surface shows subtracts `totalPausedMs`, so a run
+ * left paused overnight does not come back reading as a twelve-hour run.
+ */
+export function pauseWorkflowTask(
+  task: WorkflowTask,
+  now = Date.now(),
+): boolean {
+  if (task.status !== "running" || task.control === undefined) return false
+  task.control.pause()
+  task.status = "paused"
+  task.pausedAt = now
+  return true
+}
+
+/** Let it go again, banking however long it was held. */
+export function resumeWorkflowTask(
+  task: WorkflowTask,
+  now = Date.now(),
+): boolean {
+  if (task.status !== "paused" || task.control === undefined) return false
+  task.control.resume()
+  task.status = "running"
+  task.totalPausedMs =
+    (task.totalPausedMs ?? 0) + Math.max(0, now - (task.pausedAt ?? now))
+  task.pausedAt = undefined
+  return true
+}
+
+/** Settle a task from the run's own result. */
+export function completeWorkflowTask(
+  task: WorkflowTask,
+  result: WorkflowRunResult,
+): void {
+  // Banked before the status moves off "paused": a run that finished while held
+  // still spent that time held, and the elapsed figure has to say so.
+  if (task.pausedAt !== undefined) {
+    task.totalPausedMs =
+      (task.totalPausedMs ?? 0) + Math.max(0, Date.now() - task.pausedAt)
+    task.pausedAt = undefined
+  }
+  // Nothing left to control, and holding the handle would let the dialog offer
+  // pause on a run that has already stopped.
+  task.control = undefined
+  task.status = result.status
+  task.meta ??= result.meta
+  task.workflowName ??= result.meta.name
+  task.agentCount = Math.max(task.agentCount, result.agentCount)
+  task.replayedCount = result.replayedCount
+  task.value = result.value
+  task.error = result.error
+  task.endTime = Date.now()
+}
+
+/**
+ * Settle a task that never produced a result — a script rejected before the
+ * worker started (bad `meta`, oversized source, non-JSON `args`).
+ */
+export function failWorkflowTask(task: WorkflowTask, error: string): void {
+  task.control = undefined
+  task.pausedAt = undefined
+  task.status = "failed"
+  task.error = error
+  task.endTime = Date.now()
+}
+
+/** The run's outcome as text, for the notification and the LLM-facing result. */
+export function workflowResultText(task: WorkflowTask): string {
+  if (task.error !== undefined) return task.error
+  if (task.value === undefined) return "No output."
+  if (typeof task.value === "string") return task.value
+  return JSON.stringify(task.value, null, 2)
+}
+
+/**
+ * Resolve a `resumeFromRunId` against the runs this session has seen.
+ *
+ * Same-session only, and deliberately so: the journal lives beside the
+ * session's task files, and a run id from another session would silently find
+ * nothing to replay — reporting that as "resumed" would be a lie the caller
+ * could not see through. An unknown id is an error rather than a cold start,
+ * because a caller that asked to resume is expecting not to pay.
+ */
+export function resolveResumeTarget(
+  runId: string | undefined,
+  tasks: ReadonlyMap<string, WorkflowTask>,
+):
+  | undefined
+  | { ok: true; runId: string; journalPath: string; scriptPath: string }
+  | { ok: false; message: string } {
+  const id = runId?.trim()
+  if (id === undefined || id === "") return undefined
+
+  const prior = tasks.get(id)
+  if (prior === undefined) {
+    const known = [...tasks.keys()]
+    return {
+      ok: false,
+      message:
+        `No workflow run "${id}" in this session. ` +
+        (known.length > 0
+          ? `Runs this session: ${known.join(", ")}.`
+          : "Nothing has run yet — call this without `resumeFromRunId`."),
+    }
+  }
+  if (prior.status === "running") {
+    return {
+      ok: false,
+      message: `Workflow "${id}" is still running. Stop it from /agents → Workflows before resuming it.`,
+    }
+  }
+  if (prior.journalPath === undefined) {
+    return {
+      ok: false,
+      message: `Workflow "${id}" has no journal to resume from.`,
+    }
+  }
+  return {
+    ok: true,
+    runId: id,
+    journalPath: prior.journalPath,
+    // The persisted copy, which is what `scriptPath` holds when the call had
+    // no file of its own.
+    scriptPath: prior.scriptPath ?? "",
+  }
+}
+
+/** `<task-notification>`, in the same shape a finished background agent sends. */
+export function formatWorkflowNotification(
+  task: WorkflowTask,
+  now = Date.now(),
+): string {
+  const totals = stats(task.workflowProgress, task.agentCount)
+  const status =
+    task.status === "completed"
+      ? "Done"
+      : task.status === "killed"
+        ? "Stopped"
+        : `Error: ${task.error ?? "unknown"}`
+  const result = workflowResultText(task)
+  return [
+    `<task-notification>`,
+    `<task-id>${task.id}</task-id>`,
+    task.toolCallId
+      ? `<tool-use-id>${escapeXml(task.toolCallId)}</tool-use-id>`
+      : null,
+    task.scriptPath ? `<script>${escapeXml(task.scriptPath)}</script>` : null,
+    `<status>${escapeXml(status)}</status>`,
+    `<summary>Workflow "${escapeXml(task.workflowName ?? task.id)}" ${task.status} — ${totals.done}/${totals.total} agents${
+      task.replayedCount > 0
+        ? `, ${task.replayedCount} replayed from ${escapeXml(task.resumedFrom ?? "an earlier run")}`
+        : ""
+    }</summary>`,
+    `<result>${escapeXml(result.length > 4000 ? `${result.slice(0, 4000)}\n...(truncated)` : result)}</result>`,
+    `<usage><total_tokens>${task.totalTokens}</total_tokens><tool_uses>${task.totalToolCalls}</tool_uses><duration_ms>${elapsedMs(task, now)}</duration_ms></usage>`,
+    `</task-notification>`,
+  ]
+    .filter(Boolean)
+    .join("\n")
+}