@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/README.md

@@ -11,11 +11,11 @@ live in a standalone terminal viewer.
 
 The workflow model is a port of [openclaw/acpx](https://github.com/openclaw/acpx)
 flows into pi itself. Agent steps run inside your current pi conversation, so
-the model keeps everything it already knows from the discussion. The model
-completes each step by calling a JSON `workflow` tool, which gives the engine
-structured, validated output to route on. See the
-[design philosophy](docs/DESIGN_PHILOSOPHY.md) for the principles behind the
-engine and its public parts. Running steps can publish durable [workflow
+the model keeps everything it already knows from the discussion. A submitted
+agent calls the JSON `workflow` tool with structured output. An assistant agent
+writes a normal visible response that becomes the node output. See the [design
+philosophy](docs/DESIGN_PHILOSOPHY.md) for the principles behind the engine and
+its public parts. Running steps can publish durable [workflow
 updates](docs/WORKFLOW_UPDATES.md), including progress counts and ETA data.
 Agent instructions use compact [workflow step
 messages](docs/WORKFLOW_STEP_MESSAGES.md), and the built-in
@@ -40,13 +40,14 @@ Or try the npm package without installing it:
 pi -e npm:@osolmaz/pi-workflows
 ```
 
-The Pi package includes the extension and five optional skills:
+The Pi package includes the extension and six optional skills:
 
 - `pi-workflows` teaches the agent how to operate and author workflows.
 - `monitor` starts and operates the built-in monitor workflow.
 - `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.
 
 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
@@ -78,6 +79,17 @@ The npm package also includes the simpler `pi-workflows` snapshot viewer. To
 link that command from a clone, run `npm install && npm run build && npm link`,
 or run it in place with `npx tsx src/viewer/cli.ts`.
 
+All live workflow and controller state uses one local database:
+
+```text
+~/.pi/agent/workflows/state.sqlite
+```
+
+Runs, decisions, queues, claims, controllers, session capture, notifications,
+channel transport state, effects, and large text values share that database.
+Reads are read-only. Every write checks its actor, expected revision, and owner
+lease when required. See [SQLite state](docs/SQLITE_STATE.md).
+
 ## Herdr integration
 
 pi-workflows also ships as a [Herdr](https://herdr.dev) plugin. After installing
@@ -95,7 +107,7 @@ plan](docs/plans/2026-08-20-herdr-plugin-sync-plan.md) defines update and
 recovery behavior.
 
 When Pi runs inside Herdr, a workflow widget shows `Ctrl+Shift+R piw`. When the widget has hidden rows, this call to action shares the existing scroll-controls line instead of taking another line.
-The shortcut opens the exact run bundle and lets you choose a split, tab, or new
+The shortcut opens the exact SQLite run state and lets you choose a split, tab, or new
 workspace. `/piw` opens the same menu, and `/piw right`, `/piw below`, `/piw
 left`, `/piw above`, `/piw tab`, or `/piw workspace` selects a placement
 directly. If a viewer for that run already exists, pi-workflows focuses it
@@ -158,6 +170,12 @@ structured run ends to request one normal, human-readable assistant response.
 Workflows without it remain silent after their final structured output, which
 keeps shell-only and machine-consumed workflows model-free.
 
+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
+default character limit; a workflow can set one explicitly with
+`assistantMessage({ maxChars: 2_000 })`.
+
 ## Compose workflows
 
 A workflow can import another workflow and connect its named exits without copying its nodes:
@@ -192,8 +210,9 @@ Direct imports check child input and exit names in TypeScript. Names and paths r
 ## Agent-managed workflows
 
 The model can use the same `workflow` tool to list, start, inspect, pause,
-resume, cancel, and answer workflows. Step contracts use the tool's `submit`
-action. Slash commands and model actions share one lifecycle implementation.
+resume, cancel, and answer workflows. Submitted-step contracts use the tool's
+`submit` action. Assistant-step contracts require a normal assistant response
+instead. Slash commands and model actions share one lifecycle implementation.
 
 pi-workflows includes a `monitor` workflow for plain-language requests such as:
 
@@ -216,14 +235,15 @@ discussion first and then trigger a workflow that builds on it. The
 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 ends
-with a detailed implementation plan. `autoplan` replaces the earlier
-`autodevise` name; the old command and export are not retained.
+current authority cannot block a valid practical solution. The workflow keeps
+the detailed implementation plan and shows one short assistant response with
+the selected plan and a gist of every rejected option. `autoplan` replaces the
+earlier `autodevise` name; the old command and export are not retained.
 
 ## Watching a run
 
-Runs persist to `~/.pi/agent/workflows/runs/` as they execute. The viewer
-tails that directory and re-renders on every state change:
+Runs persist in `~/.pi/agent/workflows/state.sqlite` as they execute. The
+viewer reads that database and re-renders on every state change:
 
 ```bash
 pi-workflows view          # interactive picker, live updates
@@ -280,20 +300,22 @@ full boxed graph and its edges.
 ## Node types
 
 A workflow is a graph of named nodes with exactly one entry point. Each node
-finishes with a JSON output, and edges decide what runs next.
-
-An `agent` node sends a prompt into the pi conversation and waits for the
-model to submit its output through the `workflow` tool. 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
+finishes with an output, and edges decide what runs next.
+
+An `agent` node sends a prompt into the pi conversation. 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
 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.
 
 See [docs/workflows.md](docs/workflows.md) for the full authoring reference
-and [docs/run-bundles.md](docs/run-bundles.md) for the on-disk run format.
+and [docs/SQLITE_STATE.md](docs/SQLITE_STATE.md) for the on-disk run format.
 
 ## Controllers
 
@@ -329,7 +351,7 @@ The standalone CLI provides read-only views with `pi-workflows controllers` and
 
 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. 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.
 
-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 directory do not broadcast messages to each other's conversations.
+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.
 
 For runs that must continue while Pi is closed, keep the standalone host running:
 
@@ -337,12 +359,12 @@ For runs that must continue while Pi is closed, keep the standalone host running
 pi-workflows host --project /path/to/project
 ```
 
-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. It is a foreground process — 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/run-bundles.md](docs/run-bundles.md) for the on-disk rules.
+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. It is a foreground process — 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.
 
 ## Examples
 
-The [examples/workflows/](examples/workflows/) directory mirrors the acpx
-example set. Copy any of them into `.pi/workflows/` to use them:
+The [examples/workflows/](examples/workflows/) directory contains complete
+workflow examples. Copy any of them into `.pi/workflows/` to use them:
 
 - `echo` is the smallest possible workflow, one agent step.
 - `branch` classifies a task with a `decision` and routes to either a
@@ -352,9 +374,12 @@ example set. Copy any of them into `.pi/workflows/` to use them:
   while they run.
 - `two-turn` chains three agent steps that build on each other's outputs in
   the same conversation.
+- `plain-summary` turns structured source data into one short visible assistant
+  response. It is also a built-in workflow that other workflows can include.
 - `autoplan` turns the current problem into a chosen practical solution and
   a detailed implementation plan, using the ideal end state as guidance rather
-  than an out-of-scope requirement.
+  than an out-of-scope requirement. It also shows a short assistant response
+  with the selected plan and each rejected option.
 - `autoimplement` finds a clear existing plan, documents it when needed,
   implements and verifies it, writes and runs the exact pi-reviewer command,
   tracks P0 through P2, handles PR comments and CI, and
@@ -365,8 +390,8 @@ example set. Copy any of them into `.pi/workflows/` to use them:
 - `human-decision` shows a reusable verified-human gate with a structured
   machine subject, a separate readable operator presentation, plain choices,
   and exact replan text.
-- `approved-plan` composes autoplan, autodoc, and the reusable plan-approval
-  workflow without copying their internal nodes.
+- `approved-plan` includes the shared plan-change workflow, which composes
+  autoplan, autodoc, the configurable plan decision, and bounded replanning.
 - `autoresearch` runs an iterative feature-search loop in the style of
   [karpathy/autoresearch](https://github.com/karpathy/autoresearch): setup
   creates a frozen evaluation harness, one editable feature file, and a

package/dist/builtins/autodoc.workflow.d.ts

@@ -36,10 +36,10 @@ export declare const autodocWorkflow: import("../workflows/types.js").WorkflowDe
 }, import("../workflows/types.js").WorkflowIncludeMap> & {
     nodes: {
         readonly prepare: import("../workflows/types.js").ComputeNodeDefinition;
-        readonly locatePlan: import("../workflows/types.js").AgentNodeDefinition;
-        readonly inspectDocumentation: import("../workflows/types.js").AgentNodeDefinition;
-        readonly updateDocumentation: import("../workflows/types.js").AgentNodeDefinition;
-        readonly verifyDocumentation: import("../workflows/types.js").AgentNodeDefinition;
+        readonly locatePlan: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+        readonly inspectDocumentation: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+        readonly updateDocumentation: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+        readonly verifyDocumentation: import("../workflows/types.js").SubmittedAgentNodeDefinition;
         readonly finalize: import("../workflows/types.js").ComputeNodeDefinition;
         readonly blocked: import("../workflows/types.js").ComputeNodeDefinition;
     };