@osolmaz/pi-workflows 0.12.1 → 0.13.1

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
@@ -79,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
@@ -96,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
@@ -156,8 +167,15 @@ While a run is on screen, the footer status bar shows a compact
 
 `presentationPrompt` is optional. When present, pi-workflows uses it after the
 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.
+Without it, pi-workflows does not request a separate final response. If the
+model writes text after submitting its last agent step, that text stays visible.
+Shell-only and machine-consumed workflows remain 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
 
@@ -193,8 +211,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:
 
@@ -217,14 +236,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
@@ -281,20 +301,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
 
@@ -330,7 +352,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:
 
@@ -338,12 +360,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
@@ -353,12 +375,16 @@ 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.
-- `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
+  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, 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. P2-only work is
   verified without another reviewer round. A five-minute CI wait routes to
   additional useful local testing. New evidence can route through autoplan

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

@@ -1,7 +1,15 @@
+import { type ChangeVerificationInput, type ChangeVerificationResult, type VerificationCheck } from "./change-verification.workflow.js";
+import { parsePreparedWorkspace, type PreparedWorkspace, type WorkspaceMode, type WorkspacePreparationInput } from "./workspace-preparation.workflow.js";
 export type AutodocInput = {
     task: string;
     plan?: unknown;
     repository?: string;
+    baseBranch?: string;
+    scope?: string;
+    workspaceMode?: WorkspaceMode;
+    directDefaultBranchAuthorized?: boolean;
+    preparedWorkspace?: PreparedWorkspace;
+    verificationChecks?: VerificationCheck[];
     documents?: string[];
     evidence?: unknown;
 };
@@ -16,13 +24,18 @@ export type DocumentedPlan = {
         digests: Record<string, string>;
         evidence: unknown;
     };
-    verification: unknown;
+    verification: ChangeVerificationResult | {
+        route: "ready";
+        reason: string;
+    };
+    workspace?: PreparedWorkspace;
 };
 export type AutodocBlocked = {
     status: "blocked";
     task: string;
     reason: string;
     evidence: unknown;
+    sourceNode?: string;
 };
 export declare const autodocWorkflow: import("../workflows/types.js").WorkflowDefinition<AutodocInput, {
     readonly ready: {
@@ -33,17 +46,191 @@ export declare const autodocWorkflow: import("../workflows/types.js").WorkflowDe
         readonly from: "blocked";
         readonly validate: (value: unknown) => AutodocBlocked;
     };
-}, import("../workflows/types.js").WorkflowIncludeMap> & {
+}, {
+    readonly workspace: import("../workflows/types.js").WorkflowIncludeDefinition<import("../workflows/types.js").WorkflowDefinition<WorkspacePreparationInput, {
+        readonly ready: {
+            readonly from: "ready";
+            readonly validate: typeof parsePreparedWorkspace;
+        };
+        readonly blocked: {
+            readonly from: "blocked";
+            readonly validate: (value: unknown) => {
+                route: "ready" | "propose" | "blocked";
+                selectedMode?: import("./workspace-preparation.workflow.js").PreparedWorkspaceMode;
+                preparedWorkspace?: PreparedWorkspace;
+                repository: string;
+                baseBranch: string;
+                baseRevision?: string;
+                currentBranch?: string;
+                preExistingChangedPaths: string[];
+                reason: string;
+                evidence: string[];
+            };
+        };
+    }, import("../workflows/types.js").WorkflowIncludeMap> & {
+        nodes: {
+            readonly inspect: import("../workflows/types.js").FunctionActionNodeDefinition;
+            readonly propose: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+            readonly apply: import("../workflows/types.js").FunctionActionNodeDefinition;
+            readonly ready: import("../workflows/types.js").ComputeNodeDefinition;
+            readonly blocked: import("../workflows/types.js").ComputeNodeDefinition;
+        };
+        includes?: import("../workflows/types.js").WorkflowIncludeMap;
+        exits?: {
+            readonly ready: {
+                readonly from: "ready";
+                readonly validate: typeof parsePreparedWorkspace;
+            };
+            readonly blocked: {
+                readonly from: "blocked";
+                readonly validate: (value: unknown) => {
+                    route: "ready" | "propose" | "blocked";
+                    selectedMode?: import("./workspace-preparation.workflow.js").PreparedWorkspaceMode;
+                    preparedWorkspace?: PreparedWorkspace;
+                    repository: string;
+                    baseBranch: string;
+                    baseRevision?: string;
+                    currentBranch?: string;
+                    preExistingChangedPaths: string[];
+                    reason: string;
+                    evidence: string[];
+                };
+            };
+        };
+    }>;
+    readonly verification: import("../workflows/types.js").WorkflowIncludeDefinition<import("../workflows/types.js").WorkflowDefinition<ChangeVerificationInput, {
+        readonly ready: {
+            readonly from: "ready";
+            readonly validate: (value: unknown) => ChangeVerificationResult;
+        };
+        readonly blocked: {
+            readonly from: "blocked";
+            readonly validate: (value: unknown) => ChangeVerificationResult;
+        };
+    }, import("../workflows/types.js").WorkflowIncludeMap> & {
+        nodes: {
+            readonly selectChecks: import("../workflows/types.js").ComputeNodeDefinition;
+            readonly planChecks: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+            readonly runCandidate: import("../workflows/types.js").FunctionActionNodeDefinition;
+            readonly runBase: import("../workflows/types.js").FunctionActionNodeDefinition;
+            readonly classify: import("../workflows/types.js").ComputeNodeDefinition;
+            readonly repairGuard: import("../workflows/types.js").ComputeNodeDefinition;
+            readonly mechanicalRepair: import("../workflows/types.js").FunctionActionNodeDefinition;
+            readonly semanticRepair: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+            readonly judge: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+            readonly ready: import("../workflows/types.js").ComputeNodeDefinition;
+            readonly blocked: import("../workflows/types.js").ComputeNodeDefinition;
+        };
+        includes?: import("../workflows/types.js").WorkflowIncludeMap;
+        exits?: {
+            readonly ready: {
+                readonly from: "ready";
+                readonly validate: (value: unknown) => ChangeVerificationResult;
+            };
+            readonly blocked: {
+                readonly from: "blocked";
+                readonly validate: (value: unknown) => ChangeVerificationResult;
+            };
+        };
+    }>;
+}> & {
     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 workspaceGuard: import("../workflows/types.js").ComputeNodeDefinition;
+        readonly inspectDocumentation: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+        readonly updateDocumentation: import("../workflows/types.js").SubmittedAgentNodeDefinition;
         readonly finalize: import("../workflows/types.js").ComputeNodeDefinition;
         readonly blocked: import("../workflows/types.js").ComputeNodeDefinition;
     };
-    includes?: import("../workflows/types.js").WorkflowIncludeMap;
+    includes?: {
+        readonly workspace: import("../workflows/types.js").WorkflowIncludeDefinition<import("../workflows/types.js").WorkflowDefinition<WorkspacePreparationInput, {
+            readonly ready: {
+                readonly from: "ready";
+                readonly validate: typeof parsePreparedWorkspace;
+            };
+            readonly blocked: {
+                readonly from: "blocked";
+                readonly validate: (value: unknown) => {
+                    route: "ready" | "propose" | "blocked";
+                    selectedMode?: import("./workspace-preparation.workflow.js").PreparedWorkspaceMode;
+                    preparedWorkspace?: PreparedWorkspace;
+                    repository: string;
+                    baseBranch: string;
+                    baseRevision?: string;
+                    currentBranch?: string;
+                    preExistingChangedPaths: string[];
+                    reason: string;
+                    evidence: string[];
+                };
+            };
+        }, import("../workflows/types.js").WorkflowIncludeMap> & {
+            nodes: {
+                readonly inspect: import("../workflows/types.js").FunctionActionNodeDefinition;
+                readonly propose: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+                readonly apply: import("../workflows/types.js").FunctionActionNodeDefinition;
+                readonly ready: import("../workflows/types.js").ComputeNodeDefinition;
+                readonly blocked: import("../workflows/types.js").ComputeNodeDefinition;
+            };
+            includes?: import("../workflows/types.js").WorkflowIncludeMap;
+            exits?: {
+                readonly ready: {
+                    readonly from: "ready";
+                    readonly validate: typeof parsePreparedWorkspace;
+                };
+                readonly blocked: {
+                    readonly from: "blocked";
+                    readonly validate: (value: unknown) => {
+                        route: "ready" | "propose" | "blocked";
+                        selectedMode?: import("./workspace-preparation.workflow.js").PreparedWorkspaceMode;
+                        preparedWorkspace?: PreparedWorkspace;
+                        repository: string;
+                        baseBranch: string;
+                        baseRevision?: string;
+                        currentBranch?: string;
+                        preExistingChangedPaths: string[];
+                        reason: string;
+                        evidence: string[];
+                    };
+                };
+            };
+        }>;
+        readonly verification: import("../workflows/types.js").WorkflowIncludeDefinition<import("../workflows/types.js").WorkflowDefinition<ChangeVerificationInput, {
+            readonly ready: {
+                readonly from: "ready";
+                readonly validate: (value: unknown) => ChangeVerificationResult;
+            };
+            readonly blocked: {
+                readonly from: "blocked";
+                readonly validate: (value: unknown) => ChangeVerificationResult;
+            };
+        }, import("../workflows/types.js").WorkflowIncludeMap> & {
+            nodes: {
+                readonly selectChecks: import("../workflows/types.js").ComputeNodeDefinition;
+                readonly planChecks: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+                readonly runCandidate: import("../workflows/types.js").FunctionActionNodeDefinition;
+                readonly runBase: import("../workflows/types.js").FunctionActionNodeDefinition;
+                readonly classify: import("../workflows/types.js").ComputeNodeDefinition;
+                readonly repairGuard: import("../workflows/types.js").ComputeNodeDefinition;
+                readonly mechanicalRepair: import("../workflows/types.js").FunctionActionNodeDefinition;
+                readonly semanticRepair: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+                readonly judge: import("../workflows/types.js").SubmittedAgentNodeDefinition;
+                readonly ready: import("../workflows/types.js").ComputeNodeDefinition;
+                readonly blocked: import("../workflows/types.js").ComputeNodeDefinition;
+            };
+            includes?: import("../workflows/types.js").WorkflowIncludeMap;
+            exits?: {
+                readonly ready: {
+                    readonly from: "ready";
+                    readonly validate: (value: unknown) => ChangeVerificationResult;
+                };
+                readonly blocked: {
+                    readonly from: "blocked";
+                    readonly validate: (value: unknown) => ChangeVerificationResult;
+                };
+            };
+        }>;
+    };
     exits?: {
         readonly ready: {
             readonly from: "finalize";