@osolmaz/pi-workflows 0.14.0 → 0.15.0

package/README.md

@@ -5,9 +5,9 @@
 </p>
 
 pi-workflows is a workflow extension for the [Pi coding agent](https://pi.dev).
-It lets you define multi-step agent workflows as TypeScript graphs, trigger
-them at any point in a Pi conversation with `/workflow`, and watch them run
-live in a standalone terminal viewer.
+It lets you define multi-step agent workflows as TypeScript graphs and trigger
+them at any point in a Pi conversation with `/workflow`. A standalone terminal
+viewer shows each run live.
 
 Agent steps run inside your current Pi conversation, so the model keeps
 everything it already knows from the discussion. A submitted agent step
@@ -41,7 +41,7 @@ The Pi package includes the extension and six optional skills:
 - `autoplan` selects the best practical solution and writes an implementation plan.
 - `autodoc` records an existing plan in canonical documentation.
 - `autoimplement` implements an existing plan and verifies the result.
-- `sanity-check` reviews whether a contribution is necessary, focused, and well supported.
+- `sanity-check` reviews whether a contribution is necessary, and whether it is focused and well supported.
 
 Pi discovers these skills when it loads the package. Use `pi config` to disable
 the extension, all bundled skills, or one skill independently. The equivalent
@@ -96,7 +96,6 @@ import { agent, defineWorkflow } from "@osolmaz/pi-workflows";
 
 export default defineWorkflow({
   name: "echo",
-  presentationPrompt: "Give the user the concise reply from the workflow result.",
   startAt: "reply",
   nodes: {
     reply: agent({
@@ -115,32 +114,20 @@ Then, from any Pi conversation:
 ```
 
 `/workflow` with no arguments lists discovered workflows. `/workflow pause`
-lets the current step finish and then holds the run before the next node,
-which is useful when you want to interject in the conversation mid-workflow.
-`/workflow resume` continues it. Pressing escape to interrupt a turn pauses
-the workflow automatically, so the run never nudges the model while you have
-taken the conversation back. `/workflow resume` then re-delivers the pending
-step prompt. `/workflow cancel` stops the active run. If the last run already
-ended (for example parked at a checkpoint), it clears the leftover widget
-instead. Trailing text becomes `{ task: "..." }`, and `--input-json
-{"key": "value"}` passes arbitrary input. The names `answer`, `cancel`,
-`list`, `pause`, `resume`, and `status` are reserved and rejected as workflow
-names.
+stops the worker and parks the run at its last durable boundary. `/workflow
+resume` starts a new worker generation from that boundary. `/workflow cancel`
+stops the active run; `/workflow cancel <run-id>` can also cancel a named stale
+run when no live owner holds it. A checkpoint waits until `/workflow answer
+<json-or-text>` supplies its input.
+
+Trailing text becomes `{ task: "..." }`, and `--input-json {"key": "value"}`
+passes arbitrary input. The names `answer`, `cancel`, `list`, `pause`, `resume`,
+and `status` are reserved and rejected as workflow names.
 
 A workflow can also expose [settings that change during a
 run](docs/2026-08-25-workflow-settings.md) and queue [normal follow-up work
 after completion](docs/2026-08-25-workflow-follow-ups.md).
 
-While a run is on screen, the footer status bar shows a compact
-`wf <name> [status] <node>` indicator alongside the widget.
-
-`presentationPrompt` is optional. After each top-level interactive run ends,
-pi-workflows gives the model one normal terminal decision turn with the exact
-stored input, result, terminal reason, and restart history. A presentation
-prompt adds instructions for the human-readable response. Presentation and
-factual fallback share one durable turn intent, so only one decision turn is
-sent. Waiting checkpoints and controller child runs do not create this turn.
-
 Use `expectedOutput: assistantMessage()` when a normal assistant response must
 be a node inside the graph rather than a presentation after the run. Its exact
 visible text becomes the node output after the turn settles. The helper has no
@@ -183,26 +170,18 @@ trace, pause state, and cancellation state. See
 
 ## Agent-managed workflows
 
-The model can use the same `workflow` tool to list, start, restart, inspect,
-pause, resume, cancel, and answer workflows. `restart` takes a terminal run ID,
-reuses its exact workflow reference and input, and creates a new immutable run.
-Submitted-step contracts use the tool's
-`submit` action, while assistant-step contracts require a normal assistant
-response instead. Slash commands and model actions share one lifecycle
-implementation.
-
-A model-started workflow is saved before the tool reports it as queued, so the
-returned run ID works with `workflow status` and `workflow cancel` before
-execution starts. pi-workflows waits for the current agent turn to settle
-before activation. A terminal decision turn can reserve at most one restart,
-Monitor run, or other workflow start. Activation waits for that turn to settle.
-If activation fails, pi-workflows saves the failure and sends one decision turn
-so the model can correct the cause safely.
-
-Restart is never automatic. Explicit cancellation is not restartable through
-the shortcut. A chain permits at most three restarts and rejects a repeated
-terminal fingerprint. Pi Workflows uses Pi's current conversation for the
-continuation decision and does not capture or persist an original user message.
+The model can use the `workflow` tool to list, start, inspect, pause, resume,
+cancel, and answer ordinary checkpoints. It cannot answer a protected human
+decision. A person must answer that request through `/workflow answer` in the
+origin Pi session. The model uses `update` for durable progress from the current
+attempt and `submit` for structured step output. Assistant-message steps require
+a normal visible assistant response instead. The extension sends all lifecycle
+mutations to the host and reports success only after the host commits them.
+
+A model-started workflow is saved before the tool reports it as accepted, so
+the returned run ID works with `workflow status` and `workflow cancel`
+immediately. Duplicate host commands and step submissions adopt their stored
+receipts instead of repeating a committed transition.
 
 pi-workflows includes a [monitor](docs/MONITOR.md) workflow for plain-language
 requests such as:
@@ -221,14 +200,15 @@ target again after repair and stops when the same issue and target evidence
 return without progress. Project and global workflows can replace the built-in
 `monitor` by using the same file name.
 
-A monitor occupies the session's one active workflow slot. If its Pi runner
-stops during the shell wait, the run parks and repeats that wait node when a
-runner resumes it.
+A monitor occupies the session's one active workflow slot. If its worker or the
+host stops during the shell wait, the run parks and repeats that idempotent wait
+node when the host resumes it.
 
-Because the workflow runs in your current conversation, you can have a long
-discussion first and then trigger a workflow that builds on it. The
-`autoplan` example does exactly that. It frames the problem and scope, devises
-an elegant production-ready solution, and compares it with the holy grail. It
+Because interactive agent steps run in the origin conversation, you can have a
+long discussion first and then trigger a workflow that builds on it. The
+`autoplan` example does exactly that. It frames the problem and scope, then
+devises an elegant production-ready solution and compares it with the holy
+grail. It
 then selects the best practical in-scope solution without asking the user to
 resolve the gap. The ideal can win when it is feasible, but work outside the
 current authority cannot block a valid practical solution. The workflow keeps
@@ -248,48 +228,18 @@ pi-workflows runs          # plain list of recent runs
 pi-workflows view --once   # print a snapshot and exit (good for scripts)
 ```
 
-The run detail view draws the workflow as a boxed graph, like the replay
-viewer in [openclaw/acpx](https://github.com/openclaw/acpx), whose flows the
-pi-workflows workflow model was originally ported from. Included nodes use
-hierarchical labels such as `implementation › redesign › plan`, and each card
-shows its step name plus node type, status, attempts, and timing in compact
-symbol rows. Node types have distinct semantic colors, active cards use a
-heavy border, branches carry their case labels, the taken path is highlighted,
-and loops route through a gutter on the right back into their target from
-above. `←/→` scrubs backwards and forwards through the recorded steps and
-re-derives every node's status as of that step, with the selected step's full
-output shown below. Scrubbing to the end snaps back to following the run live.
+The run detail view draws the workflow as a boxed graph. `←/→` replays the
+recorded steps with each step's full output, and scrubbing to the end snaps
+back to following the run live.
 
-```
-  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-  ┃            review            ┃
-  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
-  ┃ ● agent            ◐ running ┃
-  ┃ ↻ 2                    ◷ 12s ┃
-  ┃ ◇ clean                     ┃
-  ┃ ◇ issues_found              ┃
-  ┃ … reviewing implementation  ┃
-  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-The Rust `piw` viewer under `tui/` adds a Catppuccin interface, selectable
-themes, centered active-node following, draggable browser and inspector sizes,
-detailed trace and conversation inspection, temporal replay, and reconnecting
-remote viewing. Cards have one fixed graph-wide size, so streaming, selection,
-timer ticks, and replay never move nodes or edges. Live conversation capture
-shows text, thinking, tool calls, and tool execution as they happen, then
-reconciles settled messages to verbatim Pi entries. See
+The Rust `piw` viewer under `tui/` is the full interactive terminal UI, with
+selectable themes, detailed trace and conversation inspection, temporal
+replay, and reconnecting remote viewing. See
 [the piw guide](docs/tui-viewer.md).
 
-Inside Pi, a compact widget above the editor shows one line per workflow node.
-The first glyph is the node status. The second glyph is the node type: `●`
-agent, `ƒ` compute, `!` notification, `$` shell action, `*` function action, or
-`◆` checkpoint. Repeated visits, runtime details, and timing appear on the same
-line when they apply. Pi's current theme highlights the full active-node line,
-while status glyphs keep every state readable without color. Long workflows are
-windowed around the active node. Scroll the list with `shift+↑` / `shift+↓`.
-It snaps back to following the active node whenever the workflow advances a
-step. Use `piw` when you need the full boxed graph and its edges.
+Inside Pi, a compact widget above the editor shows one line per workflow node,
+with glyphs for node status and type. Scroll it with `shift+↑` / `shift+↓`.
+Use `piw` when you need the full boxed graph and its edges.
 
 ## Herdr integration
 
@@ -300,10 +250,8 @@ pi-workflows also ships as a [Herdr](https://herdr.dev) plugin. After installing
 pi-workflows herdr sync
 ```
 
-Run the same command after a pi-workflows update. It finds the package that
-provides the running CLI and repairs a Herdr link when npm moved that package.
-`pi-workflows herdr setup` remains an alias for existing installations. Use
-`--json` for versioned machine-readable output.
+Run the same command after a pi-workflows update. `pi-workflows herdr setup`
+remains an alias for existing installations.
 
 When Pi runs inside Herdr, the workflow widget shows a `Ctrl+Shift+R piw`
 shortcut. The shortcut opens the exact SQLite run state and lets you choose a
@@ -320,16 +268,16 @@ is also available through the [Herdr plugin marketplace](https://herdr.dev/plugi
 A workflow is a graph of named nodes with exactly one entry point. Each node
 finishes with an output, and edges decide what runs next.
 
-An `agent` node sends a prompt into the Pi conversation as a compact
+An `agent` node sends a prompt into the origin Pi conversation as a compact
 [workflow step message](docs/WORKFLOW_STEP_MESSAGES.md). By default, it waits
 for structured output through the `workflow` tool. With
 `expectedOutput: assistantMessage()`, it waits for a normal visible assistant
 response and uses the exact text as its output. A `compute` node runs a pure
 TypeScript function. A `notify` node writes a durable message for the Pi
-session that started the run. An `action` node performs a side effect, either a
-TypeScript function (`action({ run })`) or a runtime-owned shell command
-(`shell({ exec, parse })`). A `checkpoint` node ends the run in a `waiting`
-state so a human can pick it up. On top of `agent`, the `decision` helper asks
+session that started the run. An `action` or `shell` node must declare an
+`idempotentEffect(...)` or `manualEffect(...)` recovery contract before it can
+perform a side effect. A `checkpoint` node ends the run in a `waiting` state so
+a human can pick it up. On top of `agent`, the `decision` helper asks
 the model to pick from a fixed set of choices and validates the answer, and
 `decisionEdge` routes on the result with compile-time case checking.
 
@@ -341,7 +289,7 @@ and [docs/SQLITE_STATE.md](docs/SQLITE_STATE.md) for the on-disk run format.
 
 ## Controllers
 
-Controllers keep long-running automation aligned with current external state. They store desired state in `spec`, report observed state through conditions and `status`, and reconcile a deduplicated resource key whenever an event or retry makes it ready.
+Controllers keep long-running automation aligned with current external state. They store desired state in `spec` and report observed state through conditions and `status`, then reconcile a deduplicated resource key whenever an event or retry makes it ready.
 
 Put `*.controller.ts` files in `.pi/controllers/` or `~/.pi/agent/controllers/`. Import the API from `@osolmaz/pi-workflows/controllers`:
 
@@ -367,21 +315,36 @@ Apply and inspect resources from Pi:
 /controller reconcile example item-1
 ```
 
-The standalone CLI provides read-only views with `pi-workflows controllers` and `pi-workflows controller <controller> <key>`. See [docs/CONTROLLERS.md](docs/CONTROLLERS.md) for reconciliation, queue, effect, and child workflow semantics.
+The extension resolves controller initialization in a child process, then sends the declarative resource to the global host. Controller reconciliation also runs in supervised children. The standalone CLI provides read-only views with `pi-workflows controllers` and `pi-workflows controller <controller> <key>`. See [docs/CONTROLLERS.md](docs/CONTROLLERS.md) for reconciliation, queue, effect, and child workflow semantics.
 
 ## Always-on workflows
 
-Runs do not depend on the Pi window. Every `/workflow` run is claimed through a durable queue, so closing Pi mid-run **parks** the run instead of cancelling it. Another interactive session cannot claim it. Reopening the exact session that started the run resumes it, and a standalone host can also resume it without changing where reports go. A checkpointed run waits durably until you answer it with `/workflow answer <json>`, which continues the graph in a linked run.
+Every workflow enters one durable global queue. The extension starts the
+package-owned host on demand. Closing Pi does not stop a compute, action, or
+shell node. When a run reaches an interactive agent, assistant-message, or
+human-decision step, the host parks it and saves a request for the origin Pi
+session. Reopening that session presents the same request once. A protected
+human decision does not start a model turn; a person answers it with
+`/workflow answer`.
 
-Workflow reports use a durable session-addressed outbox. A report waits while its starting session is closed and is delivered only to that session when it opens again. Runs in the same database do not broadcast messages to each other's conversations.
+The host also reconciles controllers. Controller child workflows without an
+origin session can use headless `pi --mode rpc` agent steps. A child that needs
+a visible assistant response must have an origin-session binding.
 
-For runs that must continue while Pi is closed, keep the standalone host running:
+Use the CLI to inspect or control the on-demand process:
 
 ```bash
-pi-workflows host --project /path/to/project
+pi-workflows host start
+pi-workflows host status
+pi-workflows host stop
+pi-workflows host run  # stay attached; stop with Ctrl-C
 ```
 
-The host claims parked runs and reconciles controllers without a Pi session. Conversation nodes execute in headless `pi --mode rpc` children that expose the same `workflow` tool contract. The host runs in the foreground, so stop it with Ctrl-C. A crashed host's leftovers are reaped by the next one. See [docs/workflows.md](docs/workflows.md#durable-runs-parking-and-resume) for the model and [docs/SQLITE_STATE.md](docs/SQLITE_STATE.md) for the on-disk rules.
+These commands manage one host for the complete user database, not one host per
+project. They do not install an operating-system service. A new host reaps exact
+orphan process identities and resumes safe work from committed state. See
+[docs/workflows.md](docs/workflows.md#durable-runs-parking-and-resume) and
+[docs/WORKFLOW_HOST.md](docs/WORKFLOW_HOST.md).
 
 ## Examples
 
@@ -404,8 +367,8 @@ workflow examples. Copy any of them into `.pi/workflows/` to use them:
 - `autoimplement` finds a clear existing plan, prepares a safe branch or
   worktree before mutation, documents it when needed, and verifies the current
   change against eligible base-branch failures. It writes and runs the exact
-  pi-reviewer command, tracks P0 through P2, handles PR comments and CI, and
-  finalizes the PR. P0 and P1 fixes require another review, while P2-only work
+  pi-reviewer command and tracks P0 through P2 findings, then handles PR
+  comments and CI and finalizes the PR. P0 and P1 fixes require another review, while P2-only work
   is verified without another reviewer round. A five-minute CI wait routes to
   additional useful local testing, and new evidence can route through autoplan
   and autodoc before implementation resumes.
@@ -426,6 +389,11 @@ The controller example at `examples/controllers/pull-request.controller.ts`
 shows child repair work and check polling. It also uses expected-head guards
 and recoverable merge effects.
 
+## Origins
+
+The workflow model was originally ported from
+[openclaw/acpx](https://github.com/openclaw/acpx) flows.
+
 ## License
 
 [MIT](LICENSE)

package/dist/builtins/autoimplement.workflow.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { runCommandBatch, } from "../workflows/command-batch.js";
-import { action, agent, compute, defineWorkflow, includeWorkflow, includedResult, } from "../workflows/definition.js";
+import { action, agent, compute, defineWorkflow, includeWorkflow, includedResult, manualEffect, } from "../workflows/definition.js";
 import { digest } from "../workflows/human-decision.js";
 import { allowSettingsPath, workflowSettings } from "../workflows/settings.js";
 import autodocWorkflow, {} from "./autodoc.workflow.js";
@@ -1413,6 +1413,7 @@ export const autoimplementWorkflow = defineWorkflow({
             run: selectReviewCommands,
         }),
         runReview: action({
+            effect: manualEffect("pi-workflows.autoimplement.review"),
             statusDetail: "running pi-reviewer commands",
             timeoutMs: (context) => {
                 const selected = latestOutput(context, ["selectReviewCommands"]);
@@ -1517,6 +1518,7 @@ export const autoimplementWorkflow = defineWorkflow({
             validate: parseCiInspectionForPublished,
         }),
         trackCi: action({
+            effect: manualEffect("pi-workflows.autoimplement.track-ci"),
             statusDetail: "tracking pending CI commands",
             timeoutMs: (context) => {
                 const inspected = latestOutput(context, ["inspectCi"]);