@osolmaz/pi-workflows 0.3.0 → 0.5.0

package/docs/plans/2026-08-13-session-addressed-workflow-notifications-plan.md

@@ -0,0 +1,95 @@
+---
+title: Route workflow reports to their starting session
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-13
+---
+
+# Route workflow reports to their starting session
+
+Pi Workflows must not send one workflow's report into an unrelated conversation. A workflow started in one Pi session must report only to that session, even when another session or the standalone host executes part of the run.
+
+## Requirements
+
+- Record the starting Pi session as the origin of each interactive workflow run.
+- Keep execution events separate from user-facing notifications.
+- Store each notification durably and address it to one Pi session.
+- Deliver a notification only when its target session is open.
+- Keep undelivered notifications until the target session opens again.
+- Prevent unrelated sessions from claiming session-bound runs.
+- Permit a detached host to execute a run without changing its report target.
+- Give workflow authors a runtime-owned notification node instead of using an agent step to relay text.
+- Migrate active path-based runs and existing queue rows without guessing their origin.
+- Remove project-wide hidden-message broadcasts and the shared project watermark.
+
+## Data model
+
+Queue records gain an optional `origin_session_id`. Interactive runs set it from `ctx.sessionManager.getSessionId()`. Controller-created detached runs leave it empty. A session runner can claim a record only when the origin is empty or matches its current session. The standalone host can claim either form.
+
+A `workflow_notifications` table is the durable outbox:
+
+| Field                       | Meaning                                             |
+| --------------------------- | --------------------------------------------------- |
+| `notification_id`           | Stable unique delivery ID                           |
+| `run_id`                    | Workflow run that created the notification          |
+| `node_id`                   | Node that created it                                |
+| `attempt_id`                | Latest node attempt that requested it               |
+| `notification_index`        | Stable one-based occurrence of this node in the run |
+| `target_session_id`         | Exact Pi session that may receive it                |
+| `kind`                      | `progress` or `final`                               |
+| `content`                   | Bounded plain-text report                           |
+| `created_at`                | Creation time                                       |
+| `delivery_claim_token`      | Current delivery owner, or null                     |
+| `delivery_claim_expires_at` | Delivery lease deadline, or null                    |
+| `delivered_at`              | Delivery time, or null while pending                |
+
+`(run_id, node_id, notification_index)` is unique. A crash retry reuses the same logical index, even though it gets a new attempt ID. A later loop iteration gets the next index. Delivery polling claims pending rows with a short lease before it writes to a session. This prevents two Pi processes that open the same session from sending the same notification concurrently. If a process stops, another process can reclaim the row after the lease expires. A stable notification ID is included in the custom session entry so the same session can detect a delivery completed before a crash.
+
+The existing `run_events` table remains an execution audit feed. It does not inject conversation messages. The obsolete `session_watermarks` table is no longer used.
+
+## Workflow API
+
+Add a `notify(...)` node. Its message callback returns plain text. The engine calls a host-provided notification sink and persists the resulting receipt as the node output. The node does not ask the model to relay a message and does not depend on the runner's active conversation.
+
+The built-in monitor uses `notify` for progress and final reports. Its check agent still decides whether a report is needed, but delivery always targets the origin session.
+
+## Migration
+
+For each active run with a queue row and no origin:
+
+1. Read `session/binding.json` from its run bundle.
+2. If the binding exists, set `origin_session_id` to its `piSessionId`.
+3. If no binding exists, keep the run detached.
+4. Never infer an origin from the working directory.
+
+Existing lifecycle events are not converted into notifications. This prevents old completion events from appearing in unrelated sessions after the update.
+
+## Non-goals
+
+- Do not modify Pi core or Pi session files directly.
+- Do not broadcast workflow reports to all sessions in a project.
+- Do not keep compatibility aliases for the shared project watermark behavior.
+- Do not make closed Pi sessions execute workflow steps.
+
+## Acceptance criteria
+
+- Two open Pi sessions in the same directory cannot receive each other's workflow reports.
+- A report executed by the standalone host is delivered after the origin session opens.
+- A report remains pending while its origin session is closed.
+- A session-bound run is not claimed by a different interactive session.
+- Duplicate polling and process restart do not duplicate a delivered notification.
+- Monitor progress and final reports use the notification outbox.
+- Existing active runs gain their recorded binding as origin when available.
+- Pi starts with the released package in OnurPi.
+
+## Verification
+
+- `npm run check`
+- `npm run test:e2e`
+- `npm run slophammer`
+- `git diff --check`
+- `npx -y @simpledoc/simpledoc check`
+- `cargo fmt --check --manifest-path tui/Cargo.toml`
+- `cargo clippy --manifest-path tui/Cargo.toml --all-targets --all-features -- -D warnings`
+- `cargo test --manifest-path tui/Cargo.toml`
+- `pi-reviewer --base main`
+- Start two isolated RPC Pi sessions in one directory and prove that only the matching session receives a targeted notification.

package/docs/run-bundles.md

@@ -123,7 +123,11 @@ Identity and pointers, kept in sync with the state on every snapshot:
   "runId": "20260729T023912Z-autoimplement-3f2a9c1b",
   "workflowName": "autoimplement",
   "runTitle": "autoimplement: fix the flaky test",
-  "workflowPath": "/repo/.pi/workflows/autoimplement.workflow.ts",
+  "workflowSource": {
+    "kind": "file",
+    "path": "/repo/.pi/workflows/autoimplement.workflow.ts",
+    "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
+  },
   "startedAt": "2026-07-29T02:39:12.412Z",
   "finishedAt": "2026-07-29T02:41:03.977Z",
   "status": "completed",
@@ -138,6 +142,11 @@ Identity and pointers, kept in sync with the state on every snapshot:
 }
 ```
 
+`workflowSource` identifies the definition used by the run. User workflow
+files use an absolute path and SHA-256 hash. Package-provided workflows use a
+stable identity such as `{ "kind": "builtin", "id": "monitor", "revision": "1" }`.
+A built-in identity does not contain an installation path.
+
 `paths.artifacts` is declared from bundle creation so a live session-event
 patch can safely reference a newly written artifact before the next workflow
 state projection. The directory itself is created only when needed.
@@ -167,9 +176,10 @@ instead of failing. Resume is a named operation with strict rules:
    `state.traceSeq` and the trace agree again before any new event.
 3. Completed nodes replay from the projection. The in-flight node reruns with
    a fresh attempt; a `run_resumed` trace event marks the boundary.
-4. `state.workflowHash` pins the workflow source from run start. Resume
-   refuses a hash mismatch unless forced, and a forced resume records the
-   mismatch in the `run_resumed` payload.
+4. `state.workflowSource` pins the workflow source from run start. File
+   sources require the same hash. Built-in sources require the same catalog
+   id and revision. Resume refuses a mismatch unless forced, and a forced
+   resume records the mismatch in the `run_resumed` payload.
 
 Continuation runs (answering a checkpoint) are new bundles, not resumed ones.
 They link back through `state.parentRunId`, carry the parent's outputs,
@@ -189,6 +199,11 @@ The full run projection (`WorkflowRunState` in
   "traceSeq": 17,
   "runId": "20260729T023912Z-autoimplement-3f2a9c1b",
   "workflowName": "autoimplement",
+  "workflowSource": {
+    "kind": "file",
+    "path": "/repo/.pi/workflows/autoimplement.workflow.ts",
+    "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
+  },
   "startedAt": "…",
   "updatedAt": "…",
   "status": "running",
@@ -199,6 +214,9 @@ The full run projection (`WorkflowRunState` in
 }
 ```
 
+- `workflowSource` is the canonical source identity. Resuming a file requires
+  the same hash. Resuming a built-in requires the same catalog revision. A
+  mismatch refuses the resume instead of loading another definition.
 - `status` is one of `running`, `waiting`, `completed`, `failed`, `timed_out`,
   or `cancelled`. A controller host records an abandoned bundle as `failed`
   with a final `run_interrupted` trace event. Before doing that, recovery checks

package/docs/workflows.md

@@ -16,7 +16,14 @@ Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
 3. Workflows built into Pi Workflows
 
 Pi Workflows includes a built-in `monitor` workflow. A project or global file
-named `monitor.workflow.ts` replaces it.
+named `monitor.workflow.ts` replaces it. The package registers each built-in in
+a process-local catalog with a stable reference such as `builtin:monitor` and
+an explicit revision. Built-ins are imported with the engine when a Pi process
+starts. They are not read from the package directory when a run starts or
+resumes. Updating the package on disk cannot mix a new built-in with that
+process's old engine; reload or restart Pi to use the new built-in. A revision
+mismatch refuses resume. Project and global workflow files still reload on
+each run and use their path and SHA-256 hash as their source identity.
 
 The workflow's command name is the file stem, so `.pi/workflows/triage.workflow.ts`
 runs as `/workflow triage`. A direct path also works: `/workflow ./somewhere/x.workflow.ts`.
@@ -110,10 +117,9 @@ 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
 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, any open Pi session stays current: a per-session watermark over
-the shared run event feed produces catch-up summaries and quiet context
-updates.
+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
+and never enter another conversation in the same project.
 
 ## Node types
 
@@ -127,7 +133,10 @@ agent({
   prompt: ({ outputs }) => `Review this: ${JSON.stringify(outputs.implement)}`,
   expectedOutput: `{ "verdict": "clean" | "issues_found" }`,
   validate: (output) => output, // optional; throw to reject the submission
-  timeoutMs: 30 * 60_000, // optional; default 15 minutes
+  timeoutMs: ({ input }) =>
+    (input as { timeoutMinutes?: number }).timeoutMinutes
+      ? (input as { timeoutMinutes: number }).timeoutMinutes * 60_000
+      : 30 * 60_000, // optional number or context callback; default 15 minutes
   statusDetail: "reviewing", // optional; shown in widget and viewer
 });
 ```
@@ -137,7 +146,15 @@ 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.
+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.
 
 ### compute
 
@@ -147,6 +164,26 @@ Runs a TypeScript function inline. Use it for pure data shaping.
 compute({ run: ({ outputs }) => ({ merged: { ...outputs } }) });
 ```
 
+### notify
+
+Queues a durable plain-text message for the Pi session that started the run.
+The runner does not write the message into its own conversation. A standalone
+host can execute this node, and the message still waits for the origin session.
+
+```typescript
+notify({
+  kind: "progress", // or "final"
+  message: ({ outputs }) => String(outputs.check),
+});
+```
+
+The runtime gives each logical execution of a notification node a stable index.
+A retry after a crash reuses that index, so it cannot queue the same message
+twice. Re-entering the node later in a loop gets the next index. A workflow
+with a `notify` node must be an interactive queued run with an origin session.
+Controller child workflows are detached and must report through their
+controller resource instead.
+
 ### action
 
 Performs a side effect. Two forms exist. The function form runs arbitrary
@@ -276,7 +313,8 @@ one looping workflow run. Its input is:
   "everyMinutes": 30,
   "reportWhen": "Checks fail or the state changes materially",
   "stopWhen": "The pull request is merged or closed",
-  "maxChecks": 1000
+  "maxChecks": 1000,
+  "checkTimeoutMinutes": 60
 }
 ```
 
@@ -286,8 +324,10 @@ separate agent node so its structured check result is validated before the user
 sees the message. The next check can read the previous accepted observation.
 
 Intervals must be whole minutes from 1 through 1,440. `maxChecks` defaults to
-1,000 and cannot exceed 1,000. The workflow also has a finite step limit and
-bounded observation and report sizes.
+1,000 and cannot exceed 1,000. `checkTimeoutMinutes` is optional and applies to
+check and report agent nodes. It must be from 5 through 1,440 minutes. Its
+default is the larger of 60 minutes and `everyMinutes`. The workflow also has
+a finite step limit and bounded observation and report sizes.
 
 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
@@ -344,8 +384,9 @@ 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. Cancelled runs are never
-presented. Async prompt builders have 30 seconds to finish and receive an
+`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
 `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
@@ -364,8 +405,10 @@ 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
 possible. Defaults worth knowing:
 
-- Node timeout is 15 minutes unless the node sets `timeoutMs`. A timed-out
-  node has outcome `timed_out` and can be routed with `$result.outcome`.
+- Node timeout is 15 minutes unless the node sets `timeoutMs` to a positive
+  number or context callback. A timed-out node has outcome `timed_out` and can
+  be routed with `$result.outcome`. A timed-out agent node also aborts its Pi
+  turn, and late output for that attempt is rejected.
 - `maxSteps` (workflow-level, default 100) bounds loops built from cycles in
   the graph.
 - `/workflow pause` requests a pause: the current step finishes normally,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/src/builtins/catalog.ts

@@ -0,0 +1,32 @@
+import { BuiltinWorkflowCatalog } from "../workflows/catalog.js";
+import monitorWorkflow from "./monitor.workflow.js";
+
+export const builtinWorkflowCatalog = new BuiltinWorkflowCatalog([
+  {
+    id: "monitor",
+    revision: "2",
+    definition: monitorWorkflow,
+    legacySources: [
+      {
+        workflowHash: "7a22158da94d18ec1c9fe42e70d72017a4e0620d5e5142ae839d0cd6eea55c06",
+        revision: "2",
+        pathSuffixes: [
+          "/src/builtins/monitor.workflow.ts",
+          "/dist/builtins/monitor.workflow.js",
+          "/src/workflows/monitor.workflow.ts",
+          "/dist/workflows/monitor.workflow.js",
+        ],
+      },
+      {
+        workflowHash: "352fc09c88922c7375281b52f049c1039d05441ce37f2082f5ff07fea66d5318",
+        revision: "2",
+        pathSuffixes: ["/dist/builtins/monitor.workflow.js"],
+      },
+      {
+        workflowHash: "dc601e2323a8213f5d52fa555e804ae8ed0846f809b3a1e9e5073a3c9c3a114e",
+        revision: "2",
+        pathSuffixes: ["/dist/builtins/monitor.workflow.js"],
+      },
+    ],
+  },
+]);

package/src/builtins/monitor.workflow.ts

@@ -1,8 +1,11 @@
-import { agent, compute, defineWorkflow, shell } from "../workflows/index.js";
+import { agent, compute, defineWorkflow, notify, shell } from "../workflows/definition.js";
 import type { WorkflowNodeContext } from "../workflows/types.js";
 
 const MIN_INTERVAL_MINUTES = 1;
 const MAX_INTERVAL_MINUTES = 24 * 60;
+const MIN_CHECK_TIMEOUT_MINUTES = 5;
+const MAX_CHECK_TIMEOUT_MINUTES = 24 * 60;
+const DEFAULT_MIN_CHECK_TIMEOUT_MINUTES = 60;
 const DEFAULT_MAX_CHECKS = 1_000;
 const MAX_CHECKS = 1_000;
 const MAX_OBSERVATION_CHARS = 8_000;
@@ -17,6 +20,7 @@ type MonitorInput = {
   reportWhen?: string;
   stopWhen?: string;
   maxChecks?: number;
+  checkTimeoutMinutes?: number;
 };
 
 type MonitorConfig = {
@@ -25,6 +29,7 @@ type MonitorConfig = {
   reportWhen: string;
   stopWhen: string;
   maxChecks: number;
+  checkTimeoutMinutes: number;
 };
 
 type MonitorRoute = "continue_quiet" | "continue_report" | "stop_quiet" | "stop_report";
@@ -81,6 +86,17 @@ function prepareInput(input: unknown): MonitorConfig {
   if (!Number.isInteger(maxChecks) || maxChecks <= 0 || maxChecks > MAX_CHECKS) {
     throw new Error(`maxChecks must be an integer from 1 through ${MAX_CHECKS}`);
   }
+  const checkTimeoutMinutes =
+    value.checkTimeoutMinutes ?? Math.max(DEFAULT_MIN_CHECK_TIMEOUT_MINUTES, value.everyMinutes);
+  if (
+    !Number.isInteger(checkTimeoutMinutes) ||
+    checkTimeoutMinutes < MIN_CHECK_TIMEOUT_MINUTES ||
+    checkTimeoutMinutes > MAX_CHECK_TIMEOUT_MINUTES
+  ) {
+    throw new Error(
+      `checkTimeoutMinutes must be an integer from ${MIN_CHECK_TIMEOUT_MINUTES} through ${MAX_CHECK_TIMEOUT_MINUTES}`,
+    );
+  }
   return {
     task,
     everyMinutes: value.everyMinutes,
@@ -93,6 +109,7 @@ function prepareInput(input: unknown): MonitorConfig {
         ? "The user cancels the monitor or it reaches its maximum check count."
         : requireBoundedString(value.stopWhen, "stopWhen", 4_000),
     maxChecks,
+    checkTimeoutMinutes,
   };
 }
 
@@ -100,6 +117,10 @@ function configFrom(outputs: Record<string, unknown>): MonitorConfig {
   return outputs.prepare as MonitorConfig;
 }
 
+function agentTimeoutMs({ outputs }: WorkflowNodeContext): number {
+  return configFrom(outputs).checkTimeoutMinutes * 60_000;
+}
+
 function completedChecks(context: WorkflowNodeContext): number {
   return context.state.steps.filter((step) => step.nodeId === "check" && step.outcome === "ok")
     .length;
@@ -129,22 +150,9 @@ function validateCheck(output: unknown): MonitorCheck {
   };
 }
 
-function validateReportAck(output: unknown): { reported: true } {
-  const value = requireRecord(output, "report acknowledgement");
-  if (value.reported !== true) {
-    throw new Error("report acknowledgement must set reported to true");
-  }
-  return { reported: true };
-}
-
-function reportPrompt(outputs: Record<string, unknown>): string {
+function reportMessage(outputs: Record<string, unknown>): string {
   const check = outputs.check as MonitorCheck;
-  return [
-    "Write one concise normal assistant message to the user with this monitoring update:",
-    check.report ?? check.observation,
-    "Do not add unrelated detail.",
-    "After writing the update, submit the acknowledgement required by the workflow step contract.",
-  ].join("\n\n");
+  return check.report ?? check.observation;
 }
 
 export default defineWorkflow({
@@ -190,6 +198,7 @@ export default defineWorkflow({
     }),
     check: agent({
       statusDetail: "checking monitored target",
+      timeoutMs: agentTimeoutMs,
       prompt: (context) => {
         const config = configFrom(context.outputs);
         const previous = context.outputs.check as MonitorCheck | undefined;
@@ -210,17 +219,15 @@ export default defineWorkflow({
         '{ "route": "continue_quiet" | "continue_report" | "stop_quiet" | "stop_report", "observation": "current factual state", "report": "required for report routes", "reason": "short reason" }',
       validate: (output) => validateCheck(output),
     }),
-    report_continue: agent({
-      statusDetail: "reporting monitor update",
-      prompt: ({ outputs }) => reportPrompt(outputs),
-      expectedOutput: '{ "reported": true }',
-      validate: (output) => validateReportAck(output),
+    report_continue: notify({
+      statusDetail: "queueing monitor update",
+      message: ({ outputs }) => reportMessage(outputs),
+      kind: "progress",
     }),
-    report_stop: agent({
-      statusDetail: "reporting final monitor update",
-      prompt: ({ outputs }) => reportPrompt(outputs),
-      expectedOutput: '{ "reported": true }',
-      validate: (output) => validateReportAck(output),
+    report_stop: notify({
+      statusDetail: "queueing final monitor update",
+      message: ({ outputs }) => reportMessage(outputs),
+      kind: "final",
     }),
     sleep: shell({
       statusDetail: "waiting for next monitor check",

package/src/controllers/index.ts

@@ -23,6 +23,7 @@ export { createResultHelpers, requeue, requeueAfter, settled } from "./results.j
 export {
   SqliteControllerStore,
   type RunEventRecord,
+  type WorkflowNotificationRecord,
   type WorkflowRunQueueRecord,
 } from "./sqlite.js";
 export {