@osolmaz/pi-workflows 0.1.0

package/docs/workflows.md

@@ -0,0 +1,311 @@
+# Workflow authoring reference
+
+This document is the authoring reference for pi-workflows definitions. It
+covers the file format, every node type, edge routing, the step contract the
+model sees, and how runs behave at runtime. For the on-disk run format, see
+[run-bundles.md](run-bundles.md).
+
+## Workflow files
+
+A workflow is a TypeScript module whose default export is `defineWorkflow(...)`.
+Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
+`.workflow.mjs`) from two directories, in precedence order:
+
+1. `.pi/workflows/` in the project (highest precedence on name collisions)
+2. `~/.pi/agent/workflows/` globally
+
+The workflow's command name is the file stem, so `.pi/workflows/triage.workflow.ts`
+runs as `/workflow triage`. A direct path also works: `/workflow ./somewhere/x.workflow.ts`.
+Files are loaded with [jiti](https://github.com/unjs/jiti), so plain TypeScript
+works without a build step, and `import ... from "@osolmaz/pi-workflows"` resolves to
+the engine that loaded the file.
+
+```typescript
+import { agent, compute, defineWorkflow } from "@osolmaz/pi-workflows";
+
+export default defineWorkflow({
+  name: "example",
+  title: ({ input }) => `example: ${(input as { task?: string }).task}`,
+  presentationPrompt: "Present the final answer clearly and concisely.",
+  startAt: "ask",
+  maxSteps: 50,
+  nodes: {
+    ask: agent({
+      prompt: ({ input }) => `Answer: ${(input as { task?: string }).task}`,
+      expectedOutput: `{ "answer": "text" }`,
+    }),
+    finish: compute({ run: ({ outputs }) => outputs.ask }),
+  },
+  edges: [{ from: "ask", to: "finish" }],
+});
+```
+
+Top-level fields:
+
+| Field                | Type                   | Notes                                                                                                                                                                                                              |
+| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`               | `string`               | Required. Used in run ids and the step contract. `cancel`, `list`, `pause`, and `resume` are reserved for `/workflow` subcommands.                                                                                 |
+| `title`              | `string` or function   | Optional run title, resolved once at start from `{ input, workflowName }`. Async resolution is bounded (30s) and cancellable.                                                                                      |
+| `presentationPrompt` | `string` or function   | Optional instructions for a normal assistant response after the run. A function receives `{ state, finalOutput, signal }` and may return a prompt or `undefined`. See [Result presentation](#result-presentation). |
+| `startAt`            | `string`               | Required. Id of the first node.                                                                                                                                                                                    |
+| `nodes`              | `Record<string, node>` | Required, non-empty. Node ids must match `[A-Za-z_][A-Za-z0-9_-]*`.                                                                                                                                                |
+| `edges`              | `WorkflowEdge[]`       | Required. See routing below.                                                                                                                                                                                       |
+| `maxSteps`           | `number`               | Optional loop bound, default 100. The run fails when exceeded.                                                                                                                                                     |
+
+`defineWorkflow` validates the shape eagerly (node ids, edge shapes, function
+fields) and validates the graph (unknown targets, duplicate outgoing edges,
+unreachable nodes) when a run starts.
+
+## Node context
+
+Every node callback receives the same context object:
+
+```typescript
+type WorkflowNodeContext = {
+  input: unknown; // the run input
+  outputs: Record<string, unknown>; // accepted output per finished node id
+  results: Record<string, WorkflowNodeResult>; // full result records, including failures
+  state: WorkflowRunState; // the live run state (read-only by convention)
+  signal: AbortSignal; // aborted on node timeout or run cancellation
+};
+```
+
+`outputs` only contains nodes that finished with outcome `ok`. When a node runs
+more than once (a loop), the latest result wins. A failed retry removes the
+node's earlier output from `outputs`.
+
+Long-running compute, action, and checkpoint callbacks should observe
+`context.signal` (pass it to `fetch`/`spawn`, or check `signal.aborted` between
+steps). When the node times out or the run is cancelled, the engine stops
+waiting immediately, but only cooperative callbacks stop doing work.
+
+## Node types
+
+### agent
+
+Sends a prompt into the current pi conversation and waits for the model to
+submit output through the `workflow` tool.
+
+```typescript
+agent({
+  prompt: ({ outputs }) => `Review this: ${JSON.stringify(outputs.implement)}`,
+  expectedOutput: `{ "verdict": "clean" | "issues_found" }`,
+  validate: (output) => output, // optional; throw to reject the submission
+  timeoutMs: 30 * 60_000, // optional; default 15 minutes
+  statusDetail: "reviewing", // optional; shown in widget and viewer
+});
+```
+
+The engine appends a step contract to the prompt (see below). When the model
+calls the tool, the output passes through normalization (a JSON string is
+parsed tolerantly) and then `validate`. If `validate` throws, the tool call
+returns an error and the model can retry within the same step. If the agent
+ends its turn without submitting, the extension nudges it, twice by default,
+then fails the step.
+
+### compute
+
+Runs a TypeScript function inline. Use it for pure data shaping.
+
+```typescript
+compute({ run: ({ outputs }) => ({ merged: { ...outputs } }) });
+```
+
+### action
+
+Performs a side effect. Two forms exist. The function form runs arbitrary
+TypeScript:
+
+```typescript
+action({ run: async ({ input }) => await deployPreview(input) });
+```
+
+The shell form (`shell` is a synonym that requires `exec`) runs a command owned
+by the runtime, so the workflow author decides exactly what executes, with a
+timeout and captured output:
+
+```typescript
+shell({
+  exec: ({ input }) => ({
+    command: "git",
+    args: ["status", "--porcelain"],
+    cwd: "/path/to/repo",
+    timeoutMs: 10_000,
+    allowNonZeroExit: false,
+  }),
+  parse: (result) => ({ dirty: result.stdout.trim().length > 0 }),
+});
+```
+
+Without `parse`, the node output is the full `ShellActionResult` (`stdout`,
+`stderr`, `exitCode`, `signal`, `durationMs`). A non-zero exit fails the node
+unless `allowNonZeroExit` is set. Captured stdout and stderr are each capped
+(default 1,000,000 characters, configurable with `maxOutputChars`) so verbose
+commands cannot exhaust memory. Both action forms record a receipt (command,
+exit code, duration) in the step record for auditability, including when the
+command fails.
+
+### checkpoint
+
+Ends the run in a `waiting` state for human review. Runs after a checkpoint do
+not resume automatically; the checkpoint output is the run's final output.
+Because nothing resumes past a checkpoint, graph validation rejects outgoing
+edges from checkpoint nodes.
+
+```typescript
+checkpoint({
+  summary: "human decides how to proceed",
+  run: ({ outputs }) => outputs.reconcile, // optional; default output is { summary }
+});
+```
+
+### decision
+
+`decision` is sugar over `agent` for constrained choices. It builds the prompt
+suffix listing the choices, sets `expectedOutput`, and validates that the
+submitted object carries one of the allowed values in the decision field
+(default `route`).
+
+```typescript
+const choices = ["y", "n"] as const;
+
+decision({
+  choices,
+  question: ({ outputs }) => `Same as proposed? ${JSON.stringify(outputs.propose)}`,
+});
+```
+
+Pair it with `decisionEdge`, which builds the matching `switch` edge and makes
+a missing case a compile-time error:
+
+```typescript
+decisionEdge({ from: "compare", choices, cases: { y: "implement", n: "reconcile" } });
+```
+
+## Edges and routing
+
+Each node has at most one outgoing edge. A plain edge is unconditional:
+
+```typescript
+{ from: "a", to: "b" }
+```
+
+A `switch` edge routes on a JSON path evaluated against the node's result:
+
+```typescript
+{ from: "review", switch: { on: "$.route", cases: { clean: "done", issues_found: "fix" } } }
+```
+
+Path roots:
+
+- `$.field` and `$output.field` read from the node's accepted output.
+- `$result.field` reads from the result record. `$result.outcome` is the main
+  use, with values `ok`, `failed`, `timed_out`, or `cancelled`, which lets a
+  workflow route failures to a recovery node instead of failing the run.
+
+A missing case for the resolved value fails the run with a routing error. A
+node with no outgoing edge (or no matching failure route) ends the run:
+`completed` on success, `failed`/`timed_out`/`cancelled` otherwise.
+
+## The step contract
+
+Every `agent` prompt ends with a step contract block naming the workflow, the
+step id, the attempt id, and the expected output shape:
+
+```
+---
+Workflow step contract (workflow: autoimplement, step: review, attempt: 6f9d…)
+
+Complete this step by calling the `workflow` tool exactly once with:
+{"step": "review", "attempt": "6f9d…", "output": <your result>}
+Expected output: { "route": "clean" | "issues_found", "reason": "short justification" }
+The step is complete only after the workflow tool accepts the output.
+If the tool reports a validation error, correct the output and call it again.
+```
+
+The `workflow` tool takes `{ step, attempt, output }`. Submissions are
+rejected (with a reason the model sees) when no step is pending, the step id
+is wrong, the attempt id belongs to an earlier attempt of the same node (loops
+revisit node ids, so each attempt gets a fresh id), or `validate` throws.
+Acceptance resolves the step and the engine advances; the next agent prompt
+arrives as a new user message in the same conversation.
+
+## Result presentation
+
+Workflow nodes produce structured JSON for routing and persistence. When a
+person should see a normal prose response after the run, add
+`presentationPrompt` at the top level:
+
+```typescript
+export default defineWorkflow({
+  name: "report",
+  presentationPrompt: ({ state, finalOutput }) =>
+    state.status === "waiting"
+      ? `Explain this recommendation and ask the user to decide: ${JSON.stringify(finalOutput)}`
+      : "Summarize the completed result and any remaining limitations.",
+  // ...startAt, nodes, and edges
+});
+```
+
+After the final run state has been persisted, the Pi extension sends the
+presentation instructions and bounded final result to the model as a hidden
+follow-up message. The next visible message is a normal assistant response.
+Returning `undefined`, returning an empty string, or omitting
+`presentationPrompt` produces no follow-up. Cancelled runs are never
+presented. Async prompt builders have 30 seconds to finish and receive an
+`AbortSignal` that fires on timeout, session shutdown, or when a new workflow
+or normal user turn starts; stale presentations are discarded. Once a presentation message has
+been queued, another workflow cannot start until that assistant response
+settles, so results cannot interleave.
+
+Presentation is outside the workflow graph: it cannot route to another node,
+change the run status, or alter the run bundle. If prompt generation or message
+delivery fails, the extension reports a warning and leaves the finished run
+unchanged. Opting in adds one hidden custom message and one assistant response
+to the normal Pi session; it adds no other persistent data and uses no Pi
+internals.
+
+## Runtime behavior
+
+Runs execute one node at a time. Every transition is persisted to the run
+bundle before the engine moves on, which is what makes the live viewer
+possible. Defaults worth knowing:
+
+- Node timeout is 15 minutes unless the node sets `timeoutMs`. A timed-out
+  node has outcome `timed_out` and can be routed with `$result.outcome`.
+- `maxSteps` (workflow-level, default 100) bounds loops built from cycles in
+  the graph.
+- `/workflow pause` requests a pause: the current step finishes normally,
+  then the run holds at the step boundary (`paused: true` in the run state,
+  `run_paused` in the trace) until `/workflow resume` or `/workflow cancel`.
+  Pausing never interrupts a node mid-flight.
+- Interrupting a turn (escape) auto-pauses the run: the pending agent step is
+  held without nudges and the engine pauses at the next boundary. Node
+  timeouts keep ticking while held, so a long-abandoned step still times out.
+  `/workflow resume` re-delivers the pending step prompt.
+- `/workflow cancel` aborts the current node and marks the run `cancelled`.
+  When no run is live but the widget still shows a parked or finished run,
+  the same command clears the widget.
+- One workflow runs per session at a time.
+- Agent nudges: if the model ends its turn without submitting the pending
+  step, it gets a reminder, twice by default, then the step fails.
+
+## Using the engine outside pi
+
+The engine is pi-agnostic. `WorkflowEngine` takes any `AgentStepExecutor`, so
+tests (and other hosts) can script agent steps:
+
+```typescript
+import { WorkflowEngine, type AgentStepExecutor } from "@osolmaz/pi-workflows";
+
+const executor: AgentStepExecutor = {
+  async runAgentStep(request) {
+    const accepted = await request.accept({ answer: "42" });
+    if (!accepted.ok) throw new Error(accepted.error);
+    return { output: accepted.value };
+  },
+};
+
+const engine = new WorkflowEngine({ executor, outputRoot: "/tmp/runs" });
+const { state } = await engine.run(workflow, { task: "..." });
+```

package/examples/workflows/autoimplement.workflow.ts

@@ -0,0 +1,92 @@
+import { agent, compute, decision, decisionEdge, defineWorkflow } from "@osolmaz/pi-workflows";
+
+type AutoimplementInput = {
+  task?: string;
+};
+
+const reviewChoices = ["clean", "issues_found"] as const;
+
+/**
+ * Implement, verify, then loop a self-review until it comes back clean. The
+ * decision edge routes `issues_found` back to the fix step, and the engine's
+ * maxSteps guard bounds the loop.
+ */
+export default defineWorkflow({
+  name: "autoimplement",
+  title: ({ input }) => {
+    const task = (input as AutoimplementInput).task;
+    return task ? `autoimplement: ${task.slice(0, 60)}` : undefined;
+  },
+  presentationPrompt:
+    "Summarize what was implemented, what verification passed, and any remaining limitation. Be concise and direct.",
+  maxSteps: 20,
+  startAt: "implement",
+  nodes: {
+    implement: agent({
+      timeoutMs: 60 * 60_000,
+      statusDetail: "implementing",
+      prompt: ({ input }) => {
+        const task =
+          (input as AutoimplementInput).task ?? "the plan discussed so far in this conversation";
+        return [
+          `Implement ${task} end-to-end.`,
+          "Aim for the most elegant, long-term production-ready solution without gold-plating.",
+        ].join("\n");
+      },
+      expectedOutput: `{ "summary": "what was implemented", "files": ["changed file", "changed file"] }`,
+    }),
+    verify: agent({
+      timeoutMs: 30 * 60_000,
+      statusDetail: "verifying",
+      prompt: () =>
+        [
+          "Verify the implementation.",
+          "Run the test suite plus any relevant builds, linters, or local smoke tests.",
+          "Do not run destructive commands.",
+        ].join("\n"),
+      expectedOutput: `{ "passed": true | false, "details": "what was run and what happened" }`,
+    }),
+    review: decision({
+      choices: reviewChoices,
+      question: ({ outputs }) =>
+        [
+          "Critically review your implementation as a strict reviewer.",
+          "Look for correctness bugs, missed requirements, and failing checks.",
+          "Pick `issues_found` if anything must be fixed, otherwise `clean`.",
+          "",
+          `Verification: ${JSON.stringify(outputs.verify)}`,
+        ].join("\n"),
+    }),
+    fix: agent({
+      timeoutMs: 30 * 60_000,
+      statusDetail: "fixing",
+      prompt: ({ outputs }) =>
+        [
+          "Fix the issues you found in review, then stop.",
+          "",
+          `Review: ${JSON.stringify(outputs.review)}`,
+        ].join("\n"),
+      expectedOutput: `{ "fixed": "what was changed" }`,
+    }),
+    finalize: compute({
+      run: ({ outputs }) => ({
+        implementation: outputs.implement,
+        verification: outputs.verify,
+        review: outputs.review,
+      }),
+    }),
+  },
+  edges: [
+    { from: "implement", to: "verify" },
+    { from: "verify", to: "review" },
+    decisionEdge({
+      from: "review",
+      choices: reviewChoices,
+      cases: {
+        clean: "finalize",
+        issues_found: "fix",
+      },
+    }),
+    { from: "fix", to: "verify" },
+  ],
+});

package/examples/workflows/autoresearch.workflow.ts

@@ -0,0 +1,139 @@
+import { agent, compute, decision, decisionEdge, defineWorkflow } from "@osolmaz/pi-workflows";
+
+type AutoresearchInput = {
+  /** What to search for, e.g. "a feature separating group A from group B". */
+  goal?: string;
+  /** Loop directory for the three artifacts; created if missing. */
+  dir?: string;
+};
+
+const assessChoices = ["continue", "plateau", "dead_end"] as const;
+
+/**
+ * An iterative feature-search loop in the style of karpathy/autoresearch.
+ * The discipline lives in three artifacts kept in one directory: a harness
+ * that never changes during the search, a single feature file that changes
+ * every experiment, and a journal that records every run whether it worked
+ * or not. Each loop iteration is one generation of candidates; the assess
+ * decision keeps looping until a kept result plateaus or a diverse
+ * generation all fails.
+ */
+export default defineWorkflow({
+  name: "autoresearch",
+  title: ({ input }) => {
+    const goal = (input as AutoresearchInput).goal;
+    return goal ? `autoresearch: ${goal.slice(0, 60)}` : undefined;
+  },
+  presentationPrompt:
+    "Report the research conclusion in plain language: the winner and its numbers, or the strongest negative result, plus the journal path.",
+  maxSteps: 40,
+  startAt: "setup",
+  nodes: {
+    setup: agent({
+      timeoutMs: 20 * 60_000,
+      statusDetail: "setting up harness",
+      prompt: ({ input }) => {
+        const { goal, dir } = input as AutoresearchInput;
+        return [
+          `Set up an autoresearch loop for: ${goal ?? "the research goal discussed so far in this conversation"}.`,
+          `Create the loop directory (${dir ?? "pick a sensible project-local directory"}) with three artifacts:`,
+          "",
+          "1. A harness that is FROZEN after the first run. It loads the dataset",
+          "   once, calls the candidate feature on every item, and prints the",
+          "   metrics that decide keep-or-discard (for a two-group separation:",
+          "   AUC, edge margin, and leave-one-out accuracy with a refit",
+          "   threshold). Held-out items are printed but never used for selection.",
+          "2. A feature file with one function of a fixed signature. This is the",
+          "   ONLY file that changes between experiments; state the input",
+          "   contract in its docstring.",
+          "3. A program.md recording the goal, the input contract, what is in",
+          "   and out of bounds, the keep criterion, and the rule that every run",
+          "   is journaled. Start an empty journal file next to it.",
+          "",
+          "Run the harness once on a trivial baseline feature to prove the",
+          "plumbing works, then journal that baseline as experiment 0.",
+        ].join("\n");
+      },
+      expectedOutput: `{ "dir": "loop directory", "keepCriterion": "what counts as a keeper", "baseline": "baseline numbers" }`,
+    }),
+    experiment: agent({
+      timeoutMs: 30 * 60_000,
+      statusDetail: "running experiments",
+      prompt: ({ outputs }) =>
+        [
+          "Run the next generation of experiments in the loop directory.",
+          "",
+          "One experiment is one edit to the feature file followed by one",
+          "harness run. Batch cheap candidates: when testing many ideas in one",
+          "generation, evaluate them all in one sweep process. The harness",
+          "stays frozen; if a bug forces a change, rerun every kept result and",
+          "journal the change.",
+          "",
+          "Decide the next edit from what the numbers said, not the original",
+          "plan. Chase the failure case closest to the boundary. Vary the",
+          "current winner before trusting it: a result that survives only one",
+          "parameterization is a tuned cliff, a plateau across neighboring",
+          "parameters is a finding. Never select on held-out items.",
+          "",
+          "Journal every candidate — negatives with the same care as",
+          "positives — as: idea in one line, the numbers, keep or discard,",
+          "and what to try next.",
+          "",
+          `Setup: ${JSON.stringify(outputs.setup)}`,
+        ].join("\n"),
+      expectedOutput: `{ "generation": "what was tried", "best": "best numbers so far", "kept": true | false, "next": "most informative next experiment, if any" }`,
+    }),
+    assess: decision({
+      choices: assessChoices,
+      statusDetail: "assessing progress",
+      question: ({ outputs }) =>
+        [
+          "Assess the search after this generation.",
+          "",
+          "- `continue`: there is an informative next experiment to run.",
+          "- `plateau`: a kept result is stable across neighboring parameter",
+          "  choices and further edits only trade margin sideways.",
+          "- `dead_end`: a generation of diverse candidates all failed, so the",
+          "  signal is not where the program said it would be.",
+          "",
+          `Latest generation: ${JSON.stringify(outputs.experiment)}`,
+        ].join("\n"),
+    }),
+    conclude: agent({
+      timeoutMs: 15 * 60_000,
+      statusDetail: "writing conclusions",
+      prompt: ({ outputs }) =>
+        [
+          "Finish the journal with a conclusions section: the winning feature",
+          "and its numbers (or the strongest negative result), the plateau",
+          "evidence, and the negative results that stop future re-litigation.",
+          "Only after the journal is complete, promote the winner out of the",
+          "loop directory into the real analysis code, if there is one.",
+          "",
+          `Assessment: ${JSON.stringify(outputs.assess)}`,
+          `Latest generation: ${JSON.stringify(outputs.experiment)}`,
+        ].join("\n"),
+      expectedOutput: `{ "outcome": "plateau" | "dead_end", "winner": "winning feature and numbers, or null", "journal": "path to the finished journal" }`,
+    }),
+    finalize: compute({
+      run: ({ outputs }) => ({
+        setup: outputs.setup,
+        conclusions: outputs.conclude,
+      }),
+    }),
+  },
+  edges: [
+    { from: "setup", to: "experiment" },
+    { from: "experiment", to: "assess" },
+    decisionEdge({
+      from: "assess",
+      choices: assessChoices,
+      cases: {
+        continue: "experiment",
+        plateau: "conclude",
+        dead_end: "conclude",
+      },
+    }),
+    { from: "conclude", to: "finalize" },
+  ],
+});

package/examples/workflows/branch.workflow.ts

@@ -0,0 +1,63 @@
+import { agent, checkpoint, decision, decisionEdge, defineWorkflow } from "@osolmaz/pi-workflows";
+
+type BranchInput = {
+  task?: string;
+};
+
+const classifyChoices = ["continue", "checkpoint"] as const;
+
+/**
+ * decision() + decisionEdge() constrained-choice classification, then a
+ * deterministic branch. Analogous to the acpx branch example.
+ */
+export default defineWorkflow({
+  name: "branch",
+  presentationPrompt: ({ state }) =>
+    state.status === "waiting"
+      ? "Explain briefly why the task needs clarification, then ask the user one concrete clarification question."
+      : "Tell the user in one concise sentence how the workflow recommends proceeding.",
+  startAt: "classify",
+  nodes: {
+    classify: decision({
+      choices: classifyChoices,
+      question: ({ input }) => {
+        const task =
+          (input as BranchInput).task ??
+          "Investigate a flaky test and decide whether the request is clear enough to continue.";
+        return [
+          "Read the task below.",
+          "Pick `continue` if it is concrete and scoped.",
+          "Pick `checkpoint` if it is ambiguous or needs clarification.",
+          "",
+          `Task: ${task}`,
+        ].join("\n");
+      },
+    }),
+    continue_lane: agent({
+      prompt: ({ outputs }) =>
+        [
+          "We are on the continue path.",
+          `Decision: ${JSON.stringify(outputs.classify)}`,
+          "Summarize in one sentence how you would proceed.",
+        ].join("\n"),
+      expectedOutput: `{ "summary": "short explanation" }`,
+    }),
+    checkpoint_lane: checkpoint({
+      summary: "needs clarification",
+      run: ({ outputs }) => ({
+        route: "checkpoint",
+        summary: (outputs.classify as { reason?: string }).reason ?? "Needs clarification.",
+      }),
+    }),
+  },
+  edges: [
+    decisionEdge({
+      from: "classify",
+      choices: classifyChoices,
+      cases: {
+        continue: "continue_lane",
+        checkpoint: "checkpoint_lane",
+      },
+    }),
+  ],
+});

package/examples/workflows/echo.workflow.ts

@@ -0,0 +1,23 @@
+import { agent, defineWorkflow } from "@osolmaz/pi-workflows";
+
+type EchoInput = {
+  task?: string;
+};
+
+/** Smallest possible workflow: one agent step that submits a JSON reply. */
+export default defineWorkflow({
+  name: "echo",
+  presentationPrompt:
+    "Give the user the concise reply from the workflow result, with no extra commentary.",
+  startAt: "reply",
+  nodes: {
+    reply: agent({
+      prompt: ({ input }) => {
+        const request = (input as EchoInput).task ?? "Summarize this repository in one sentence.";
+        return `Answer the following request concisely.\n\nRequest: ${request}`;
+      },
+      expectedOutput: `{ "reply": "your concise answer" }`,
+    }),
+  },
+  edges: [],
+});