@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/docs/workflows.md

@@ -16,7 +16,7 @@ Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
 3. Workflows built into Pi Workflows
 
 Pi Workflows includes built-in `autoplan`, `autodoc`, `autoimplement`,
-`plan-approval`, and `monitor` workflows. `autoplan` is the current name for the
+`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
@@ -161,11 +161,13 @@ 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.
 
-`timeoutMs` can be a finite positive number or a function of the normal node
-context. A timeout function can use prepared outputs to select a deadline for
-this run. It has 30 seconds to return a value. Computed timeout functions are
-runtime code, so definition snapshots omit them; fixed numeric timeouts remain
-in the snapshot.
+`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
+default. Set it to `null` to disable only the wall-clock deadline; cancellation,
+parking, claim loss, shutdown, and the node's abort signal still work. A timeout
+function can use prepared outputs to select a policy for this run. It has 30
+seconds to return. Computed timeout functions are runtime code, so definition
+snapshots omit them. Snapshots keep fixed numbers and fixed `null` values.
 
 ### compute
 
@@ -289,6 +291,10 @@ const choices = defineHumanChoices({
 humanDecision({
   audience: "operator",
   choices,
+  onTimeout: {
+    afterMs: 10 * 60_000,
+    response: { choice: "continue" },
+  },
   request: ({ outputs }) => ({
     title: "Approve plan",
     subject: outputs.plan,
@@ -301,7 +307,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.
 
@@ -415,14 +421,64 @@ runs.
 
 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 `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.
+
+Autoimplement gives `implement` an eight-hour deadline. When a supported
+long-running agent node times out, one shared read-only fallback inspects the
+current repository, accepted workflow outputs, and relevant pull-request state.
+It then retries the timed-out stage or routes to verification, review, CI,
+delivery, the existing redesign workflow, or blocked. The fallback can run at
+most three times in one Autoimplement run. Its own failure or timeout is
+terminal. Cancellation remains immediate and never enters fallback. A repeated
+effect step first checks what already exists and performs only missing work.
+This graph fallback starts after the timed-out turn ends and is separate from
+successor-turn delivery.
+
+Autoimplement uses batches for pi-reviewer, pending CI watches, and local verification commands from independent repositories. It keeps model turns, fixes, pushes, comment changes, merges, and releases in their existing order. Reviewer commands are tied to the repository, base branch, pushed head, and relevant dependency fingerprint. A later review round includes only repositories whose head or dependency fingerprint changed. P0 or P1 work still requires another review. P2-only work can be addressed and verified without another reviewer run only because of that P2 work.
+
+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.
 
-Autoimplement writes and runs the exact Pi Reviewer command. It records P0 through P2 by review round. P0 or P1 work requires another review. P2-only work can be addressed and verified without another reviewer run. CI tracking commands are also explicit. One CI watch lasts at most five minutes, after which the model runs more useful local tests before checking CI again.
+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.
 
 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.
 
 Autoimplement can run the blocker challenge at most three times in one run. Each later challenge receives the earlier challenge results. Reaching the limit stops with the normal workflow safety-limit reason. Explicit human stops, cancellation, exhausted workflow or replan limits, protected authorization gaps, and an independent blocked result from redesign remain direct stops. These hard boundaries do not enter the blocker challenge.
 
+### Built-in sanity check
+
+The built-in `sanity-check` workflow reviews a pull request or local contribution before implementation, approval, or merge. It checks whether the change is needed, duplicates existing code, should use a simpler design, adds unnecessary data models or public plugin and SDK APIs, or has scope and test problems.
+
+```json
+{
+  "mode": "serial",
+  "baseRef": "origin/main"
+}
+```
+
+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 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.
+
+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.
+
+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.
+
+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 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.
+
 ### Built-in monitor
 
 The built-in `monitor` workflow turns a plain request for repeated checks into
@@ -439,7 +495,7 @@ one looping workflow run. Its input is:
 }
 ```
 
-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 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.
 
 `everyMinutes` defaults to 30. Each accepted check must provide one concise report and choose `continue`, `repair` when authorized, or `stop`. The
 runtime queues that report as a workflow notification with `triggerTurn:
@@ -496,9 +552,10 @@ use the same card and keep the active attempt id.
 
 Headless RPC execution receives the same complete prompt without TUI metadata.
 Workflow notifications use a separate message type with `triggerTurn: false`,
-so a notification does not start an assistant response. See
-[WORKFLOW_STEP_MESSAGES.md](WORKFLOW_STEP_MESSAGES.md) for the message contract
-and renderer rules.
+so a notification does not start an assistant response. Deferred successor turns
+use an internal turn-intent contract instead of the notification outbox. See
+[WORKFLOW_STEP_MESSAGES.md](WORKFLOW_STEP_MESSAGES.md) for the step-message contract
+and [Deferred workflow turns](DEFERRED_TURNS.md) for the successor-turn contract.
 
 ## Result presentation
 
@@ -521,9 +578,11 @@ After the final run state has been persisted, the Pi extension sends the
 presentation instructions and bounded final result to the model as a hidden
 follow-up message. The next visible message is a normal assistant response.
 Returning `undefined`, returning an empty string, or omitting
-`presentationPrompt` produces no follow-up. Failed, timed-out, and cancelled
-runs are never presented; the extension reports their persisted status and
-error directly. Async prompt builders have 30 seconds to finish and receive an
+`presentationPrompt` produces no presentation. Failed, timed-out, and cancelled
+runs are never presented. When one of those outcomes would otherwise strand an
+agent after a workflow-caused turn abort or asynchronous crash, the extension
+uses the deferred-turn contract to send one factual fallback after settlement.
+Async prompt builders have 30 seconds to finish and receive an
 `AbortSignal` that fires on timeout, session shutdown, or when a new workflow
 or normal user turn starts; stale presentations are discarded. Once a presentation message has
 been queued, another workflow cannot start until that assistant response
@@ -561,13 +620,17 @@ possible. Defaults worth knowing:
   and `running`. `workflow status` and `workflow cancel` accept the run ID before a run bundle
   exists.
 - If deferred activation fails, the queue stores a bounded safe error, releases the session
-  reservation, and sends one follow-up turn to the initiating model. The model can correct the
-  cause and make a new explicit start call. Pi Workflows does not retry blindly.
-- `/workflow cancel` aborts the current node and marks the run `cancelled`.
-  When no run is live but the widget still shows a parked or finished run,
-  the same command clears the widget.
+  reservation, and creates one deferred-turn intent for the initiating session. A workflow that
+  reports `started` and then crashes before its first prompt follows the same path. The model gets
+  one factual follow-up after settlement and can make a new explicit start call. Pi Workflows does
+  not retry blindly.
+- An agent-issued `workflow cancel` aborts the current node and the current Pi turn, then creates
+  one deferred-turn intent. The next natural workflow message resolves it when possible; otherwise
+  one factual fallback starts after settlement. Direct `/workflow cancel` remains quiet because it
+  is explicit user control. When no run is live but the widget still shows a parked or finished run,
+  the command clears the widget.
 - One workflow runs per session at a time.
-- After the workflow tool accepts an agent-step submission, the extension removes any assistant tail text from the rest of that agent run. The next workflow message or notification is the visible continuation. Explicit final presentation remains a separate opt-in response.
+- After the workflow tool accepts an agent-step submission, the extension removes any assistant tail text from the rest of that agent run. The next workflow message is the visible continuation. A deferred intent makes a workflow prompt, presentation, and factual fallback compete to provide one successor turn, so an abort cannot produce two continuation turns.
 - Agent nudges: if the model ends its turn without submitting the pending
   step, it gets a reminder, twice by default, then the step fails.
 

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/command-batch.workflow.ts

@@ -0,0 +1,50 @@
+import {
+  action,
+  compute,
+  defineWorkflow,
+  runCommandBatch,
+  type CommandBatchRequest,
+} from "@osolmaz/pi-workflows";
+
+type Input = {
+  cwd: string;
+};
+
+export default defineWorkflow({
+  name: "command-batch",
+  input: (value): Input => value as Input,
+  startAt: "prepare",
+  nodes: {
+    prepare: compute({
+      run: ({ input }) =>
+        ({
+          maxConcurrency: 2,
+          items: [
+            {
+              id: "first",
+              command: "printf",
+              args: ["%s", "first"],
+              cwd: (input as Input).cwd,
+              timeoutMs: 10_000,
+              maxOutputChars: 10_000,
+            },
+            {
+              id: "second",
+              command: "printf",
+              args: ["%s", "second"],
+              cwd: (input as Input).cwd,
+              timeoutMs: 10_000,
+              maxOutputChars: 10_000,
+            },
+          ],
+        }) satisfies CommandBatchRequest,
+    }),
+    run: action({
+      run: async (context) =>
+        await runCommandBatch(context.outputs.prepare as CommandBatchRequest, {
+          signal: context.signal,
+        }),
+    }),
+  },
+  edges: [{ from: "prepare", to: "run" }],
+});

package/examples/workflows/sanity-check.workflow.ts

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

package/herdr-plugin.toml

@@ -1,8 +1,8 @@
 id = "osolmaz.pi-workflows"
-name = "Pi Workflows"
-version = "0.11.2"
+name = "pi-workflows"
+version = "0.12.1"
 min_herdr_version = "0.7.0"
-description = "Open the active Pi Workflows run in piw from a managed Herdr pane."
+description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]
 
 [[panes]]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "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/schemas/decision-presentation-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/decision-presentation-v1.schema.json",
-  "title": "Pi Workflows decision presentation v1",
+  "title": "pi-workflows decision presentation v1",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "summary", "blocks"],

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

@@ -1,16 +1,18 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v1.schema.json",
-  "title": "Pi Workflows accepted human decision v1",
+  "title": "pi-workflows accepted human decision v1",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "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-answer-attempt-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-answer-attempt-v1.schema.json",
-  "title": "Pi Workflows human decision answer attempt v1",
+  "title": "pi-workflows human decision answer attempt v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-cancellation-v1.schema.json",
-  "title": "Pi Workflows human decision cancellation v1",
+  "title": "pi-workflows human decision cancellation v1",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "decisionId", "requestDigest", "cancelledAt", "reason"],

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

@@ -1,14 +1,23 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-continuation-v1.schema.json",
-  "title": "Pi Workflows human decision continuation v1",
+  "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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-delivery-v1.schema.json",
-  "title": "Pi Workflows human decision delivery v1",
+  "title": "pi-workflows human decision delivery v1",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -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

@@ -1,15 +1,19 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-receipt-v1.schema.json",
-  "title": "Pi Workflows redacted human decision receipt v1",
+  "title": "pi-workflows redacted human decision receipt v1",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "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}$" }
   }

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

@@ -1,20 +1,24 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-request-v1.schema.json",
-  "title": "Pi Workflows human decision request v1",
+  "title": "pi-workflows human decision request v1",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "schema",
     "decisionId",
     "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
     "runId",
     "workflowName",
     "nodeId",
     "attemptId",
     "audience",
     "title",
-    "body",
+    "subject",
+    "presentation",
+    "revision",
     "choices",
     "createdAt"
   ],
@@ -22,13 +26,19 @@
     "schema": { "const": "pi-workflows.human-decision-request.v1" },
     "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$" },
     "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}$" },
     "runId": { "type": "string" },
     "workflowName": { "type": "string" },
     "nodeId": { "type": "string" },
     "attemptId": { "type": "string" },
     "audience": { "type": "string" },
     "title": { "type": "string", "minLength": 1 },
-    "body": true,
+    "subject": true,
+    "presentation": {
+      "$ref": "decision-presentation-v1.schema.json"
+    },
+    "revision": { "type": "integer", "minimum": 1 },
     "choices": {
       "type": "object",
       "minProperties": 1,
@@ -54,6 +64,16 @@
       }
     },
     "createdAt": { "type": "string", "format": "date-time" },
-    "expiresAt": { "type": "string", "format": "date-time" }
-  }
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "defaultResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    }
+  },
+  "dependentRequired": { "defaultResponse": ["expiresAt"] }
 }