@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/docs/workflows.md

@@ -2,8 +2,8 @@
 
 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).
+model sees, and how runs behave at runtime. For durable state, see
+[SQLITE_STATE.md](SQLITE_STATE.md).
 
 ## Workflow files
 
@@ -15,8 +15,8 @@ Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
 2. `~/.pi/agent/workflows/` globally
 3. Workflows built into Pi Workflows
 
-Pi Workflows includes built-in `autoplan`, `autodoc`, `autoimplement`,
-`plan-approval`, `sanity-check`, and `monitor` workflows. `autoplan` is the current name for the
+Pi Workflows includes built-in `plain-summary`, `autoplan`, `autodoc`,
+`autoimplement`, `plan-approval`, `sanity-check`, and `monitor` workflows. `autoplan` is the current name for the
 planning workflow that was first released as `autodevise`; the old command and
 export are not retained. A project or global file named `monitor.workflow.ts`
 replaces the built-in monitor. The package registers each built-in in
@@ -105,11 +105,11 @@ Function actions receive `WorkflowActionContext`, which adds
 
 Every interactive `/workflow` run is tracked in the project run queue (see
 [CONTROLLERS.md](CONTROLLERS.md) for the store). The session that starts a run
-claims it and owns it while it executes; every bundle write proves the claim
+claims it and owns it while it executes; every owner-only SQLite write proves the claim
 first (write fencing).
 
 Closing the Pi session mid-run no longer cancels the run. The engine **parks**:
-it stops without a terminal event, releases the claim, and leaves the bundle
+it stops without a terminal event, releases the claim, and leaves the run
 resumable. When a runner is available again (a reopened Pi session or the
 standalone host), the run **resumes** at the node it stopped on. Completed
 nodes replay from the recorded state; only the interrupted node and everything
@@ -124,9 +124,11 @@ pi-workflows host --project /path/to/project
 ```
 
 The host claims parked runs, resumes them, and reconciles durable controllers.
-Conversation nodes execute in headless `pi --mode rpc` children that load a
-small bridge extension; the model sees the same `workflow` tool contract as an
-in-session run. The host is a foreground process: start it in a terminal and
+Agent nodes that submit through the workflow tool execute in headless
+`pi --mode rpc` children that load a small bridge extension. An agent node with
+`expectedOutput: assistantMessage()` parks before prompting and waits for the
+origin Pi session because its result must be a visible assistant message. A
+detached run without an origin session fails clearly. The host is a foreground process: start it in a terminal and
 stop it with Ctrl-C. A second host for the same project refuses to start, and
 a host that dies has its orphaned children reaped by the next one. While the host works, reports enter a durable outbox addressed to the Pi
 session that started the run. They remain pending while that session is closed
@@ -136,8 +138,9 @@ and never enter another conversation in the same project.
 
 ### agent
 
-Sends a prompt into the current pi conversation and waits for the model to
-submit output through the `workflow` tool.
+Sends a prompt to the model. `expectedOutput` selects one of two output forms.
+
+The existing string form waits for a `workflow submit` call:
 
 ```typescript
 agent({
@@ -152,14 +155,28 @@ agent({
 });
 ```
 
-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. If an agent node times out or the workflow is cancelled,
-the extension also aborts its active Pi turn. The model cannot continue to use
-tools after the engine has closed that attempt.
+The assistant-message form waits for one normal visible response and uses its
+exact text as the node output:
+
+```typescript
+agent({
+  prompt: ({ outputs }) => `Explain this plainly: ${JSON.stringify(outputs.review)}`,
+  expectedOutput: assistantMessage(),
+});
+```
+
+`assistantMessage()` has no default character limit. Authors can opt in with
+`assistantMessage({ maxChars: 2_000 })`. It cannot be combined with `validate`
+because an invalid response is already visible and must not be retried.
+
+For submitted output, the engine appends the existing workflow-tool contract.
+The output passes through tolerant JSON normalization and then `validate`.
+Rejected submissions can retry in the same step. If the model settles without
+submitting, the extension nudges it twice by default and then fails the step.
+For assistant-message output, the engine appends a normal-response contract,
+waits for `agent_settled`, rejects empty, failed, aborted, or tool-only results,
+and never suppresses the visible text. Timeout and cancellation abort either
+form's active Pi turn.
 
 `timeoutMs` can be a finite positive number, `null`, or a function of the normal
 node context that returns either value. Omit it to use the 15-minute engine
@@ -259,10 +276,10 @@ schema, limits, estimation, and error rules.
 
 ### checkpoint
 
-Ends the run in a `waiting` state for human review. The checkpoint bundle is
+Ends the run in a `waiting` state for human review. The checkpoint run is
 terminal, so no process keeps running while the run waits. The human answers
 with `/workflow answer <json>` (or plain text), which starts a **continuation
-run**: a new run with its own bundle and trace, linked to the checkpointed run
+run**: a new run with its own state and events, linked to the checkpointed run
 through `parentRunId`. The continuation receives the answer as its input,
 carries forward every output the parent produced (including the checkpoint's),
 and continues routing along the checkpoint's outgoing edge. Outgoing edges
@@ -291,6 +308,10 @@ const choices = defineHumanChoices({
 humanDecision({
   audience: "operator",
   choices,
+  onTimeout: {
+    afterMs: 10 * 60_000,
+    response: { choice: "continue" },
+  },
   request: ({ outputs }) => ({
     title: "Approve plan",
     subject: outputs.plan,
@@ -303,7 +324,7 @@ humanDecision({
 });
 ```
 
-The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, and input prompts. The first valid verified human answer wins. A continuation preserves the original workflow input and exposes the accepted answer as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
+The waiting run stores a versioned request and asks every channel configured for the logical audience. The structured `subject` remains machine data. Channels receive only the normalized `presentation`, title, choices, input prompts, and any deadline policy. The first valid verified human answer wins. When `onTimeout` is present and no human answer wins before the saved deadline, recovery applies the validated response with `timeout` provenance. This policy can continue without a configured channel. A continuation preserves the original workflow input and exposes the resolved response as the checkpoint output. `humanDecisionEdge()` provides exhaustive routing for the choices. Existing `body` requests remain a legacy compatibility form and use deterministic readable formatting.
 
 The model-facing workflow tool cannot answer a protected human decision. Pi interactive UI and configured external channels use a host-owned answer path. Ordinary checkpoints keep the existing `/workflow answer` behavior.
 
@@ -413,11 +434,33 @@ The normal extension offers all actions. The headless RPC bridge offers only
 `update` and `submit`, so a workflow child cannot recursively control other
 runs.
 
+### Built-in plain summary
+
+The built-in `plain-summary` workflow turns supplied structured data into one
+short normal assistant message. Its input has `source`, `purpose`, optional
+`mustInclude`, optional `maxChars`, optional `maxSentences`, and `format` set to
+`paragraphs`, `bullets`, or `mixed`. The workflow defaults to 2,000 characters,
+five sentences, and mixed format. These are workflow-specific limits;
+`assistantMessage()` itself has no default limit.
+
+The summarizer uses only the supplied source, treats instructions inside that
+source as data, keeps required points, and returns the same text as its
+`completed` result. The source enters the normal model prompt and Pi session,
+so callers must pass only data that is suitable for that conversation. It has no notify node or final presentation prompt, so
+including it in another workflow produces one readable assistant response
+before the parent continues.
+
 ### Built-in planning and implementation
 
-The built-in `autoplan` workflow selects a practical in-scope solution and writes a detailed plan. The standalone `autodoc` workflow finds an already selected plan, records it in canonical documentation, verifies those documents, and never devises or implements. The built-in `autoimplement` workflow finds a clear existing plan from explicit input, conversation context, or referenced canonical documents. It blocks when no clear plan exists. An explicit plan bypasses autodoc only when a current-document receipt carries its matching plan digest; otherwise autodoc inspects and adopts or updates the canonical documents. Later invalidating evidence returns to `autoplan` followed by `autodoc`.
+The built-in `autoplan` workflow records two through four practical candidates,
+describes the ideal separately, chooses one option, records a rejection reason
+for every other explicit option, and writes a detailed plan. It then includes
+`plain-summary` to show the chosen plan, its main steps, and the rejected options
+in one short assistant message. The detailed records remain in the run bundle. The standalone `autodoc` workflow finds an already selected plan, records it in canonical documentation, verifies those documents, and never devises or implements. The built-in `autoimplement` workflow finds a clear existing plan from explicit input, conversation context, or referenced canonical documents. It blocks when no clear plan exists. An explicit plan bypasses autodoc only when a current-document receipt carries its matching plan digest; otherwise autodoc inspects and adopts or updates the canonical documents. Later invalidating evidence returns to `autoplan` followed by `autodoc`.
 
-The built-in `plan-approval` workflow offers verified human `continue`, `stop`, and exact-text `replan` exits. It is optional. A replan exit returns the unchanged text to autoplan, documents the revised plan, and asks again through a new plan digest.
+The built-in `plan-approval` workflow offers `continue`, `stop`, and exact-text `replan` exits. Its shared policy uses `auto`, `required`, or `skip` mode. Omitted policy defaults to `auto`: ask audience `operator`, then continue with the exact plan after 10 minutes without an answer. Required mode waits for a human. Skip mode creates no decision. Stop and replan always require a human answer.
+
+The internal plan-change workflow composes Autoplan, Autodoc, plan approval, and bounded replanning. Autoimplement and Monitor use it whenever they create or change a plan. Existing supplied or discovered plans bypass the gate. A plan selected by Monitor enters Autoimplement without another decision for the same digest.
 
 Autoimplement runs independent commands through bounded command batches. A batch is an ordinary function action that calls the public `runCommandBatch` helper. Each command has a stable ID, executable, arguments, absolute working directory, timeout, and output limit. Results stay separate and return in input order. One command uses the same path with concurrency one.
 
@@ -436,7 +479,7 @@ Autoimplement uses batches for pi-reviewer, pending CI watches, and local verifi
 
 Autoimplement inspects every pull request before it waits for CI. It accepts only supported pending `gh pr checks --watch` or `gh run watch` descriptors and binds each one to the validated pull request as `gh pr checks <PR URL> --watch`. Repository and pull-request overrides are rejected. One watch lasts at most five minutes. A failed or timed-out watch affects only its pull request. When checks remain pending, the model runs more useful local tests before checking CI again. Autoimplement does not invent an ETA.
 
-The action abort signal stops active command process groups and prevents queued commands from starting. Accepted outputs use the existing trace and artifacts. An interrupted unaccepted batch runs again because batch commands are read-only or isolated local checks. Progress updates contain metadata only and never control routing. Truncated reviewer or CI output cannot count as clean. See [Run independent commands in bounded batches](plans/2026-08-20-bounded-command-batches-plan.md) for the complete contract and implementation plan.
+The action abort signal stops active command process groups and prevents queued commands from starting. Accepted outputs use immutable events and content-addressed blobs. An interrupted unaccepted batch runs again because batch commands are read-only or isolated local checks. Progress updates contain metadata only and never control routing. Truncated reviewer or CI output cannot count as clean. See [Run independent commands in bounded batches](plans/2026-08-20-bounded-command-batches-plan.md) for the complete contract and implementation plan.
 
 A model-generated blocker from implementation or a safe later stage does not end autoimplement by itself. A separate blocker-challenge agent checks the task, approved plan, current result, evidence, scope, authority, earlier attempts, and practical alternatives. It confirms a blocker only when the blocker exists now, is outside the granted authority, has no safe path forward, has an empty next action, and includes concrete evidence and checked alternatives. A rejected blocker must name the next practical action and routes through the existing redesign workflow before implementation and verification continue.
 
@@ -453,44 +496,69 @@ The built-in `sanity-check` workflow reviews a pull request or local contributio
 }
 ```
 
-Serial mode is the default. It runs one temporary read-only Pi session for all four review areas, then one temporary session to verify and combine the findings. Parallel mode runs four focused review sessions at the same time, then one verification session. Serial mode uses two model sessions. Parallel mode uses five. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review.
+Serial mode is the default. It runs one review session for all four review areas, then one verification session. Parallel mode runs four focused review sessions at the same time, then one verification session. Serial mode uses two model sessions. Parallel mode uses five. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review.
+
+The workflow collects pull request intent and repository diff evidence before model review. It bounds evidence and review results before prompt construction and marks truncated input. Every review must cite evidence and give the strongest case for accepting the current design. The verification session removes unsupported claims, requires exact file and symbol references, resolves supported conflicts, and returns `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+
+Sanity Check revision 4 creates child sessions directly through the documented Pi SDK. A private built-in runner uses `createAgentSession` with `SessionManager.inMemory`, one independent context per child, and only the verified built-in `read`, `grep`, `find`, and `ls` tools. Child sessions load no skills, prompt templates, themes, or context files. They create no Pi session file.
+
+The parent Pi process keeps its normal configured extensions enabled. The child runner resolves enabled user extension paths, excludes Pi Workflows and project extensions by default, and preflights the remaining paths without creating a session. It admits only the extension that registers the exact configured provider, plus any behavior extension on an explicit private allowlist. It rejects competing provider owners, workflow tools or commands, and extensions that replace a built-in read-only tool. The admitted paths are frozen for the group, and each child loads only those explicit paths without a second discovery pass.
+
+Each child owns a separate `ModelRuntime`, provider instance, extension runtime, resource loader, and in-memory session. The runner loads validated model and ordinary credential snapshots into per-child in-memory stores without writing them back. A provider extension uses its existing provider-owned credential store in place; Pi Workflows does not copy, print, migrate, or persist those credentials.
+
+A complete explicit provider, model, and thinking override wins. Otherwise, the runner uses the configured process defaults. It passes the exact cached model and thinking level to the child, then verifies the actual provider, model, thinking level, authentication, extension state, active tools, and tool sources before prompting. A missing or different dispatch is terminal. The runner never silently falls back to OpenRouter, Kimi, a local model, or another provider or model. It does not promise to inherit a model selected temporarily in the origin Pi TUI.
 
-The workflow collects pull request intent and repository diff evidence before model review. It bounds serialized evidence and review results before prompt construction and marks truncated input. Every review must cite evidence and give the strongest case for accepting the current design. The verification session removes unsupported claims, requires exact file and symbol references, resolves supported conflicts, and returns `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+Children do not receive the `workflow` tool, workflow commands, parent run identifiers, update channels, or workflow callbacks. Prompts that invoke extension slash commands are rejected. The parent Sanity Check action remains the only workflow owner. These controls block normal child model and extension bindings from inspecting or changing workflow state. Extensions still run as trusted code in the parent Node process, so this is not an OS sandbox against direct filesystem or network access.
 
-Child sessions have only `read`, `grep`, `find`, and `ls`. They do not load discovered extensions, skills, or repository context files, cannot mutate the repository, and do not save Pi session files. The workflow sends the final report through a final notification with `triggerTurn: false`, so the origin model does not produce another response. See [the Sanity Check plan](plans/2026-08-21-sanity-check-plan.md) for the selected implementation and test boundaries.
+Only bounded final assistant text and safe operational facts leave a live child session. Pi Workflows does not persist child prompts, reasoning, intermediate messages, tool arguments, tool results, message history, credentials, or extension-private state. Timeout and cancellation abort and settle active work before the runner disposes the session, shuts down extensions, and releases provider resources.
+
+The workflow publishes aggregate and per-agent `pi-workflows.progress.v1` tracks under `agents/review/*` and `agents/verification/*`. Progress contains role, the verified actual model when known, state, elapsed facts, and safe phases such as `thinking` or `tool: read`. The Pi widget shows the aggregate plus failed and active children within its ten-line limit. `piw` shows every durable child track and its samples. Both views use existing progress records, so no child workflow run or new persisted schema is needed.
+
+Serial mode still uses two child sessions, and parallel mode still uses five. Review prompts, review areas, strict result validation, verdicts, and progress stay unchanged. After verification, an assistant-message agent shows the full bounded report verbatim. A mismatch stops before summary generation. The graph then includes `plain-summary`, which shows a short plain-language explanation with the verdict and the most important next action. The detailed response always settles before the summary starts. A final compute node returns the original strict result, so presentation cannot change the verdict. Sanity Check uses no final notification or root `presentationPrompt`.
+
+The CLI, JSON or RPC stream, temporary prompt file, standard-output cap, subprocess fallback, shared child runtime, and blanket child-extension ban are not retained. See [the Sanity Check plan](plans/2026-08-21-sanity-check-plan.md) for the selected implementation and test boundaries.
 
 ### Built-in monitor
 
-The built-in `monitor` workflow turns a plain request for repeated checks into
-one looping workflow run. Its input is:
+The built-in `monitor` workflow turns a plain request to finish and monitor an
+authorized goal into one looping workflow run. It accepts only `task`,
+`stopWhen`, `everyMinutes`, and `maxChecks`:
 
 ```json
 {
-  "task": "Check pull request 123",
-  "stopWhen": "The pull request is merged or closed",
-  "repair": {
-    "authorized": true,
-    "scope": "the current repository"
-  }
+  "task": "Finish pull request 123 within the recorded repository and delivery authority.",
+  "stopWhen": "The pull request is merged or safe continuation is blocked.",
+  "everyMinutes": 30
 }
 ```
 
-The first check runs immediately. Omit `repair` for observation-only monitoring. An authorized repair routes through outer `autoplan`, `autodoc`, optional `plan-approval`, `autoimplement`, and internal redesign before the monitor checks the target again. A repeated issue with unchanged target evidence stops as blocked. Add `repair.approval` with a named audience and bounded replan limit only when the operator wants a human decision before implementation.
+The first `observe` step runs immediately and is read-only. It inspects the real
+target with normal tools and chooses `wait`, `act`, or `stop`. `wait` means that
+useful target work is moving or an external event must finish. `act` states one
+safe action that existing authority permits. `stop` means that the goal is
+complete or cannot continue safely.
 
-`everyMinutes` defaults to 30. Each accepted check must provide one concise report and choose `continue`, `repair` when authorized, or `stop`. The
+An `advance` or `recover` action runs directly in a separate normal-tools step.
+A `repair` action composes the shared plan-change workflow and Autoimplement.
+Monitor observes again immediately after every action. It stops instead of
+repeating a completed repair when the same stable failure and target state
+return. The timer is reachable only from `wait`.
+
+`everyMinutes` defaults to 30. Every accepted observation provides one concise
+report that separates Monitor state, goal state, and target work state. The
 runtime queues that report as a workflow notification with `triggerTurn:
-false`, so it does not cause an assistant reply. A check can also provide
-independent progress tracks. The regular Pi model running the check observes
-the target and submits those facts. Pi Workflows validates the counts and
-calculates rates, confidence, and ETA deterministically. The target does not
-need a Pi Workflows dependency or reporting protocol.
+false`, so it does not cause an assistant reply. An observation can also provide
+independent progress tracks. The regular Pi model observes the target and
+submits those facts. Pi Workflows validates counts and calculates rates,
+confidence, and ETA deterministically. The target does not need a Pi Workflows
+dependency or reporting protocol.
 
 Intervals must be whole minutes from 1 through 1,440. When `stopWhen` is
 omitted, the monitor stops only after an explicit user request. `maxChecks`
-defaults to the disclosed safety ceiling of 1,000 and cannot exceed it. Callers
-omit `maxChecks` unless the user requests a fixed count. `checkTimeoutMinutes`
-is from 5 through 1,440 and defaults to the larger of 60 and `everyMinutes`.
-See [MONITOR.md](MONITOR.md) for the check and progress schemas.
+defaults to the disclosed observation safety limit of 1,000 and cannot exceed
+it. Callers omit `maxChecks` unless the user requests a fixed count. Unknown
+fields fail before a run is created. See [MONITOR.md](MONITOR.md) for the
+observation, action, and progress schemas.
 
 The interval uses the existing shell action to launch the current Node
 executable with a timer. This works on every platform supported by Pi. The node
@@ -539,8 +607,8 @@ and [Deferred workflow turns](DEFERRED_TURNS.md) for the successor-turn contract
 
 ## Result presentation
 
-Workflow nodes produce structured JSON for routing and persistence. When a
-person should see a normal prose response after the run, add
+Workflow nodes normally produce structured values for routing and persistence.
+When a person should see a normal prose response only after the root run, add
 `presentationPrompt` at the top level:
 
 ```typescript
@@ -568,8 +636,14 @@ or normal user turn starts; stale presentations are discarded. Once a presentati
 been queued, another workflow cannot start until that assistant response
 settles, so results cannot interleave.
 
+An agent with `expectedOutput: assistantMessage()` is different. Its visible
+assistant response is the node output, can appear before later nodes, and also
+works inside an included workflow. A root `presentationPrompt` would add a
+second response, so workflows that end with assistant-message output normally
+omit it.
+
 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
+change the run status, or alter the SQLite run state. 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
@@ -578,7 +652,7 @@ 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
+database transaction 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` to a positive
@@ -597,7 +671,7 @@ possible. Defaults worth knowing:
   `/workflow resume` re-delivers the pending step prompt.
 - A model-started workflow is persisted as `queued` with its final run ID before the start tool
   returns. Activation waits for the initiating agent turn to settle, then moves through `starting`
-  and `running`. `workflow status` and `workflow cancel` accept the run ID before a run bundle
+  and `running`. `workflow status` and `workflow cancel` accept the run ID before a SQLite run state
   exists.
 - If deferred activation fails, the queue stores a bounded safe error, releases the session
   reservation, and creates one deferred-turn intent for the initiating session. A workflow that
@@ -637,7 +711,7 @@ if (run.state !== "succeeded") {
 }
 ```
 
-Child workflow completion queues the parent resource again. A running child left by a stopped host is recorded as a failed run bundle with a `run_interrupted` event. The controller treats that child attempt as interrupted, and the next parent reconciliation starts another immutable attempt. Consequential external mutations should use the controller effect API so uncertain results are observed before retry.
+Child workflow completion queues the parent resource again. A running child left by a stopped host is recorded as a failed SQLite run state with a `run_interrupted` event. The controller treats that child attempt as interrupted, and the next parent reconciliation starts another immutable attempt. Consequential external mutations should use the controller effect API so uncertain results are observed before retry.
 
 See [CONTROLLERS.md](CONTROLLERS.md) for controller definitions and the full recovery contract.
 

package/examples/workflows/approved-plan.workflow.ts

@@ -1,58 +1,31 @@
-import { compute, defineWorkflow, includeWorkflow, includedResult } from "@osolmaz/pi-workflows";
-import autodoc from "../../src/builtins/autodoc.workflow.js";
-import autoplan from "../../src/builtins/autoplan.workflow.js";
-import planApproval from "../../src/builtins/plan-approval.workflow.js";
+import { compute, defineWorkflow, includeWorkflow } from "@osolmaz/pi-workflows";
+import planChange from "../../src/builtins/plan-change.workflow.js";
 
 export default defineWorkflow({
   name: "approved-plan-example",
-  startAt: "design",
-  maxSteps: 80,
+  startAt: "start",
+  maxSteps: 100,
   includes: {
-    design: includeWorkflow(autoplan, {
-      input: ({ input, outputs }) => {
-        const prior = outputs.design as { exit?: string; output?: { plan?: unknown } } | undefined;
-        const answer = outputs.approval as
-          | { exit?: string; output?: { instructions?: string } }
-          | undefined;
-        return {
-          problem: (input as { task: string }).task,
-          ...(prior?.exit === "ready" ? { previousPlan: prior.output?.plan } : {}),
-          ...(answer?.exit === "replan" ? { newEvidence: answer.output?.instructions } : {}),
-        };
-      },
-    }),
-    documentation: includeWorkflow(autodoc, {
-      input: ({ input, outputs }) => {
-        const result = includedResult(autoplan, outputs.design);
-        if (result.exit !== "ready") throw new Error("design is not ready");
-        return { task: (input as { task: string }).task, plan: result.output.plan };
-      },
-    }),
-    approval: includeWorkflow(planApproval, {
-      input: ({ input, outputs }) => {
-        const result = includedResult(autodoc, outputs.documentation);
-        if (result.exit !== "ready") throw new Error("documentation is not ready");
-        return {
-          task: (input as { task: string }).task,
-          plan: result.output.plan,
-          planDigest: result.output.planDigest,
+    planChange: includeWorkflow(planChange, {
+      input: ({ input }) => ({
+        task: (input as { task: string }).task,
+        approval: {
+          mode: "auto" as const,
           audience: "operator",
-        };
-      },
+          timeoutMinutes: 10,
+          maxReplans: 3,
+        },
+      }),
     }),
   },
   nodes: {
-    done: compute({ run: ({ outputs }) => ({ status: "approved", approval: outputs.approval }) }),
-    stopped: compute({ run: ({ outputs }) => ({ status: "stopped", approval: outputs.approval }) }),
-    blocked: compute({ run: ({ outputs }) => ({ status: "blocked", outputs }) }),
+    start: compute({ run: () => ({ route: "plan" }) }),
+    done: compute({ run: ({ outputs }) => ({ status: "ready", plan: outputs.planChange }) }),
+    blocked: compute({ run: ({ outputs }) => ({ status: "blocked", plan: outputs.planChange }) }),
   },
   edges: [
-    { from: "design.ready", to: "documentation" },
-    { from: "design.blocked", to: "blocked" },
-    { from: "documentation.ready", to: "approval" },
-    { from: "documentation.blocked", to: "blocked" },
-    { from: "approval.continue", to: "done" },
-    { from: "approval.stop", to: "stopped" },
-    { from: "approval.replan", to: "design" },
+    { from: "start", to: "planChange" },
+    { from: "planChange.ready", to: "done" },
+    { from: "planChange.blocked", to: "blocked" },
   ],
 });

package/examples/workflows/plain-summary.workflow.ts

@@ -0,0 +1 @@
+export { plainSummaryWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.12.0"
+version = "0.13.0"
 min_herdr_version = "0.7.0"
 description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -69,9 +69,9 @@
     "jiti": "^2.7.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.10",
-    "@earendil-works/pi-coding-agent": "^0.80.10",
-    "@earendil-works/pi-tui": "^0.80.10",
+    "@earendil-works/pi-ai": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^26.1.1",
     "@vitest/coverage-istanbul": "^4.1.10",
@@ -83,9 +83,9 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": ">=0.84.2 <0.85.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.2 <0.85.0",
+    "@earendil-works/pi-tui": ">=0.84.2 <0.85.0",
     "typebox": "*"
   },
   "engines": {

package/plugins/herdr/viewer.mjs

@@ -1,22 +1,12 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
 
 const runId = process.env.PI_WORKFLOWS_RUN_ID ?? "";
-const runDir = process.env.PI_WORKFLOWS_RUN_DIR ?? "";
 
 if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/u.test(runId)) {
   fail("PI_WORKFLOWS_RUN_ID is missing or invalid.");
 }
-if (!path.isAbsolute(runDir) || path.basename(runDir) !== runId) {
-  fail("PI_WORKFLOWS_RUN_DIR must be the absolute bundle directory for the selected run.");
-}
-if (!fs.existsSync(path.join(runDir, "manifest.json"))) {
-  fail(`Workflow bundle not found: ${runDir}`);
-}
-
 const paneId = process.env.HERDR_PANE_ID ?? "";
 if (!/^[A-Za-z0-9]+:p[A-Za-z0-9]+$/u.test(paneId)) {
   fail("HERDR_PANE_ID is missing or invalid.");
@@ -33,7 +23,7 @@ if (labeled.status !== 0) {
   fail(`Could not label the Herdr viewer pane: ${bounded(labeled.stderr) || "unknown error"}`);
 }
 
-const viewer = spawn("piw", [runDir], { stdio: "inherit" });
+const viewer = spawn("piw", [runId], { stdio: "inherit" });
 for (const signal of ["SIGINT", "SIGTERM"]) {
   process.on(signal, () => viewer.kill(signal));
 }

package/schemas/human-decision-accepted-v1.schema.json

@@ -8,9 +8,11 @@
     "schema",
     "decisionId",
     "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
+    "revision",
     "response",
-    "source",
-    "idempotencyKey",
+    "provenance",
     "acceptedAt",
     "answerDigest"
   ],
@@ -18,6 +20,9 @@
     "schema": { "const": "pi-workflows.human-decision-accepted.v1" },
     "decisionId": { "type": "string" },
     "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "revision": { "type": "integer", "minimum": 1 },
     "response": {
       "type": "object",
       "additionalProperties": false,
@@ -27,6 +32,7 @@
         "input": { "type": "object", "additionalProperties": { "type": "string" } }
       }
     },
+    "provenance": { "enum": ["human", "timeout"] },
     "source": {
       "type": "object",
       "additionalProperties": false,
@@ -40,5 +46,11 @@
     "idempotencyKey": { "type": "string" },
     "acceptedAt": { "type": "string", "format": "date-time" },
     "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
-  }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "provenance": { "const": "human" } } },
+      "then": { "required": ["source", "idempotencyKey"] }
+    }
+  ]
 }

package/schemas/human-decision-continuation-v1.schema.json

@@ -4,11 +4,20 @@
   "title": "pi-workflows human decision continuation v1",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schema", "decisionId", "requestDigest", "parentRunId", "runId", "createdAt"],
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "provenance",
+    "parentRunId",
+    "runId",
+    "createdAt"
+  ],
   "properties": {
     "schema": { "const": "pi-workflows.human-decision-continuation.v1" },
     "decisionId": { "type": "string" },
     "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "provenance": { "enum": ["human", "timeout"] },
     "parentRunId": { "type": "string" },
     "runId": { "type": "string" },
     "createdAt": { "type": "string", "format": "date-time" }

package/schemas/human-decision-delivery-v1.schema.json

@@ -9,7 +9,9 @@
     "attemptId",
     "decisionId",
     "requestDigest",
+    "presentationDigest",
     "channel",
+    "phase",
     "state",
     "createdAt"
   ],
@@ -18,10 +20,16 @@
     "attemptId": { "type": "string" },
     "decisionId": { "type": "string" },
     "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
     "channel": { "type": "string" },
+    "phase": { "enum": ["intent", "part", "complete"] },
     "state": { "enum": ["intent", "confirmed", "failed", "unknown"] },
     "createdAt": { "type": "string", "format": "date-time" },
     "finishedAt": { "type": "string", "format": "date-time" },
+    "recipientIndex": { "type": "integer", "minimum": 1 },
+    "partIndex": { "type": "integer", "minimum": 1 },
+    "partCount": { "type": "integer", "minimum": 1, "maximum": 20 },
+    "contentDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
     "messageCount": { "type": "integer", "minimum": 0 },
     "errorCode": { "type": "string" }
   }

package/schemas/human-decision-receipt-v1.schema.json

@@ -8,8 +8,12 @@
     "schema",
     "decisionId",
     "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
+    "revision",
     "nodeId",
     "response",
+    "provenance",
     "acceptedAt",
     "answerDigest"
   ],
@@ -17,6 +21,9 @@
     "schema": { "const": "pi-workflows.human-decision-receipt.v1" },
     "decisionId": { "type": "string" },
     "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "revision": { "type": "integer", "minimum": 1 },
     "nodeId": { "type": "string" },
     "response": {
       "type": "object",
@@ -27,6 +34,7 @@
         "input": { "type": "object", "additionalProperties": { "type": "string" } }
       }
     },
+    "provenance": { "enum": ["human", "timeout"] },
     "acceptedAt": { "type": "string", "format": "date-time" },
     "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
   }