@osolmaz/pi-workflows 0.12.1 → 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
@@ -417,9 +434,29 @@ 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 `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.
 
@@ -442,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.
 
@@ -463,7 +500,7 @@ Serial mode is the default. It runs one review session for all four review areas
 
 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 3 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.
+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.
 
@@ -477,40 +514,51 @@ Only bounded final assistant text and safe operational facts leave a live child
 
 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 sessions, and parallel mode still uses five. Prompts, review areas, strict result validation, verdicts, and final notification stay unchanged. The workflow sends the final report through a final notification with `triggerTurn: false`, so the origin model does not produce another response. 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.
+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 the shared plan-change workflow, Autoimplement, and a fresh check. A repeated issue with unchanged target evidence stops as blocked. Omit `repair.approval` for the 10-minute autonomous default. Use `approval.mode: "required"` to wait for an explicit answer or `approval.mode: "skip"` to continue without asking.
+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.
+
+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. Each accepted check must provide one concise report and choose `continue`, `repair` when authorized, or `stop`. The
+`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
@@ -559,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
@@ -588,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
@@ -598,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
@@ -617,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
@@ -657,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/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.1"
+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.1",
+  "version": "0.13.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

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/skills/autoplan/SKILL.md

@@ -37,13 +37,14 @@ When this skill is loaded inside an active workflow step, do not start another w
 Outside Pi, or when the workflow is unavailable:
 
 1. Frame the problem, observable success criteria, scope, constraints, and interfaces under our control.
-2. Devise the most elegant long-term production-ready solution within that scope.
+2. Record two through four distinct practical candidates. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
 3. Describe the holy grail separately. Name every dependency outside our authority.
-4. Choose the right option without asking the user to decide between them.
+4. Choose the right option without asking the user to decide between them. Record one rejection reason for every other explicit candidate.
    - Choose the ideal when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
    - Otherwise choose the strongest practical in-scope solution with a clear path toward the ideal.
    - Do not block only because the ideal requires an upstream or external change.
 5. Write a detailed implementation plan. For each step, state what changes, where it changes, and how to verify it.
-6. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
+6. Present one short plain assistant message with the chosen plan, its main steps, and a one-line gist and rejection reason for every other candidate. Call it selected for approval when a later human decision still applies.
+7. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
 
-When revising a plan, preserve the previous plan and new evidence. State whether the plan changed and why. Do not implement unless the user also requested implementation.
+When revising a plan, preserve the previous plan and new evidence. Record whether the previous plan remains a candidate or why new evidence rejects it. State whether the final plan changed and why. “All plans” means the explicit candidate records, never hidden model reasoning. Do not implement unless the user also requested implementation.