@osolmaz/pi-workflows 0.2.0 → 0.3.0

package/docs/workflows.md

@@ -9,10 +9,14 @@ model sees, and how runs behave at runtime. For the on-disk run format, see
 
 A workflow is a TypeScript module whose default export is `defineWorkflow(...)`.
 Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
-`.workflow.mjs`) from two directories, in precedence order:
+`.workflow.mjs`) from these sources, in precedence order:
 
 1. `.pi/workflows/` in the project (highest precedence on name collisions)
 2. `~/.pi/agent/workflows/` globally
+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.
 
 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`.
@@ -44,7 +48,7 @@ Top-level fields:
 
 | Field                | Type                   | Notes                                                                                                                                                                                                              |
 | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`               | `string`               | Required. Used in run ids and the step contract. `cancel`, `list`, `pause`, and `resume` are reserved for `/workflow` subcommands.                                                                                 |
+| `name`               | `string`               | Required. Used in run ids and the step contract. `answer`, `cancel`, `list`, `pause`, `resume`, and `status` are reserved for `/workflow` subcommands.                                                             |
 | `title`              | `string` or function   | Optional run title, resolved once at start from `{ input, workflowName }`. Async resolution is bounded (30s) and cancellable.                                                                                      |
 | `presentationPrompt` | `string` or function   | Optional instructions for a normal assistant response after the run. A function receives `{ state, finalOutput, signal }` and may return a prompt or `undefined`. See [Result presentation](#result-presentation). |
 | `startAt`            | `string`               | Required. Id of the first node.                                                                                                                                                                                    |
@@ -79,6 +83,38 @@ Long-running compute, action, and checkpoint callbacks should observe
 steps). When the node times out or the run is cancelled, the engine stops
 waiting immediately, but only cooperative callbacks stop doing work.
 
+## Durable runs, parking, and resume
+
+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
+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
+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
+downstream rerun. Resume repairs a torn trace tail, drops trace events the
+state projection never recorded, and refuses to continue if the workflow
+source changed since the run started (a forced resume records the mismatch).
+
+The standalone host runs without any Pi session:
+
+```bash
+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
+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.
+
 ## Node types
 
 ### agent
@@ -147,10 +183,15 @@ command fails.
 
 ### checkpoint
 
-Ends the run in a `waiting` state for human review. Runs after a checkpoint do
-not resume automatically; the checkpoint output is the run's final output.
-Because nothing resumes past a checkpoint, graph validation rejects outgoing
-edges from checkpoint nodes.
+Ends the run in a `waiting` state for human review. The checkpoint bundle 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
+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
+from checkpoint nodes are allowed exactly so continuations have somewhere to
+go; step accounting carries over, so `maxSteps` bounds the whole chain.
 
 ```typescript
 checkpoint({
@@ -207,6 +248,57 @@ A missing case for the resolved value fails the run with a routing error. A
 node with no outgoing edge (or no matching failure route) ends the run:
 `completed` on success, `failed`/`timed_out`/`cancelled` otherwise.
 
+## Model workflow control
+
+The model sees one `workflow` tool. Its `action` field supports:
+
+- `list` for discovered workflow names and sources.
+- `start` with a workflow name or path and structured input.
+- `status` for the active run or a supplied run ID.
+- `pause`, `resume`, and `cancel` for the active run.
+- `answer` with checkpoint input and an optional run ID.
+- `submit` for the current workflow step contract.
+
+A model-started run is queued until the model's current turn settles. The first
+workflow prompt then starts a new turn. This keeps the requesting turn outside
+the workflow's first attempt and prevents an early missing-submission reminder.
+The normal extension offers all actions. The headless RPC bridge offers only
+`submit`, so a workflow child cannot recursively control other runs.
+
+### Built-in monitor
+
+The built-in `monitor` workflow turns a plain request for repeated checks into
+one looping workflow run. Its input is:
+
+```json
+{
+  "task": "Check pull request 123",
+  "everyMinutes": 30,
+  "reportWhen": "Checks fail or the state changes materially",
+  "stopWhen": "The pull request is merged or closed",
+  "maxChecks": 1000
+}
+```
+
+The first check runs immediately. Each accepted check records a bounded current
+observation and chooses whether to continue, report, or stop. A report uses a
+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.
+
+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
+and command timeouts are higher than the maximum interval. Cancelling the
+workflow aborts the timer process immediately. If the owning Pi process or
+standalone host stops during the wait, normal parking rules abort the shell node
+and resume later by running that wait again from the beginning.
+
+A monitor uses the session's single active workflow slot. It does not provide
+cron syntax, calendar scheduling, OS notifications, or a background service.
+
 ## The step contract
 
 Every `agent` prompt ends with a step contract block naming the workflow, the
@@ -217,16 +309,17 @@ step id, the attempt id, and the expected output shape:
 Workflow step contract (workflow: autoimplement, step: review, attempt: 6f9d…)
 
 Complete this step by calling the `workflow` tool exactly once with:
-{"step": "review", "attempt": "6f9d…", "output": <your result>}
+{"action": "submit", "step": "review", "attempt": "6f9d…", "output": <your result>}
 Expected output: { "route": "clean" | "issues_found", "reason": "short justification" }
 The step is complete only after the workflow tool accepts the output.
 If the tool reports a validation error, correct the output and call it again.
 ```
 
-The `workflow` tool takes `{ step, attempt, output }`. Submissions are
-rejected (with a reason the model sees) when no step is pending, the step id
-is wrong, the attempt id belongs to an earlier attempt of the same node (loops
-revisit node ids, so each attempt gets a fresh id), or `validate` throws.
+The `workflow` tool uses `{ action: "submit", step, attempt, output }` for step
+results. Submissions are rejected (with a reason the model sees) when no step
+is pending, the step id is wrong, the attempt id belongs to an earlier attempt
+of the same node (loops revisit node ids, so each attempt gets a fresh id), or
+`validate` throws.
 Acceptance resolves the step and the engine advances; the next agent prompt
 arrives as a new user message in the same conversation.
 
@@ -290,6 +383,33 @@ possible. Defaults worth knowing:
 - Agent nudges: if the model ends its turn without submitting the pending
   step, it gets a reminder, twice by default, then the step fails.
 
+## Workflows started by controllers
+
+A controller can start a workflow as a finite child job with `ctx.workflows.ensure()`. The request key is stable across reconciliation passes, and the input fingerprint prevents one key from being reused for different work.
+
+```typescript
+const run = await ctx.workflows.ensure({
+  requestKey: `repair:${resource.metadata.generation}`,
+  workflow: "repair-pull-request",
+  input: { repository: resource.spec.repository, number: resource.spec.number },
+});
+
+if (run.state !== "succeeded") {
+  return ctx.requeueAfter(5_000, {
+    workflowRun: {
+      requestId: run.requestId,
+      ...(run.runId ? { runId: run.runId } : {}),
+      state: run.state,
+      attempt: run.attempt,
+    },
+  });
+}
+```
+
+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.
+
+See [CONTROLLERS.md](CONTROLLERS.md) for controller definitions and the full recovery contract.
+
 ## Using the engine outside pi
 
 The engine is pi-agnostic. `WorkflowEngine` takes any `AgentStepExecutor`, so

package/examples/controllers/pull-request.controller.ts

@@ -0,0 +1,215 @@
+import {
+  conditionFalse,
+  conditionTrue,
+  conditionUnknown,
+  defineController,
+  type ChildWorkflowRecord,
+} from "@osolmaz/pi-workflows/controllers";
+
+type PullRequestSpec = {
+  apiBaseUrl: string;
+  repository: string;
+  number: number;
+  expectedHeadSha: string;
+  repairWorkflow: string;
+  mergeApproved: boolean;
+};
+
+type PullRequestStatus = {
+  phase: "observing" | "repairing" | "waiting" | "ready" | "merged" | "blocked";
+  observedHeadSha?: string;
+};
+
+type PullRequest = {
+  merged: boolean;
+  merge_commit_sha?: string | null;
+  head: { sha: string };
+};
+
+type CommitStatus = {
+  state: "error" | "failure" | "pending" | "success";
+};
+
+export default defineController<PullRequestSpec, PullRequestStatus>({
+  name: "pull-request",
+  initialStatus: () => ({ phase: "observing" }),
+
+  async reconcile(ctx, resource) {
+    const client = new GitHubClient(resource.spec.apiBaseUrl, resource.spec.repository);
+    const pullRequest = await client.pullRequest(resource.spec.number, ctx.signal);
+    const observed = { observedHeadSha: pullRequest.head.sha };
+
+    if (pullRequest.merged) {
+      return ctx.settled({
+        controllerStatus: { phase: "merged", ...observed },
+        conditions: [conditionTrue("Ready", "Merged")],
+        workflowRun: null,
+      });
+    }
+    if (pullRequest.head.sha !== resource.spec.expectedHeadSha) {
+      return ctx.settled({
+        controllerStatus: { phase: "blocked", ...observed },
+        conditions: [conditionFalse("Ready", "HeadChanged")],
+      });
+    }
+
+    const child = await ctx.workflows.ensure({
+      requestKey: `repair:${resource.metadata.generation}:${pullRequest.head.sha}`,
+      workflow: resource.spec.repairWorkflow,
+      input: {
+        repository: resource.spec.repository,
+        number: resource.spec.number,
+        expectedHeadSha: pullRequest.head.sha,
+      },
+    });
+    const workflowRun = workflowReference(child);
+    if (child.state === "failed") {
+      return ctx.settled({
+        controllerStatus: { phase: "blocked", ...observed },
+        conditions: [conditionFalse("Ready", "RepairFailed", child.error)],
+        workflowRun,
+      });
+    }
+    if (child.state !== "succeeded") {
+      return ctx.requeueAfter(5_000, {
+        controllerStatus: { phase: "repairing", ...observed },
+        conditions: [conditionUnknown("Ready", "RepairRunning")],
+        workflowRun,
+      });
+    }
+
+    const checks = await client.commitStatus(pullRequest.head.sha, ctx.signal);
+    if (checks.state !== "success") {
+      return ctx.requeueAfter(30_000, {
+        controllerStatus: { phase: "waiting", ...observed },
+        conditions: [conditionUnknown("Ready", "ChecksPending", checks.state)],
+        workflowRun,
+      });
+    }
+    if (!resource.spec.mergeApproved) {
+      return ctx.settled({
+        controllerStatus: { phase: "ready", ...observed },
+        conditions: [conditionFalse("Ready", "ApprovalRequired")],
+        workflowRun,
+      });
+    }
+
+    const effect = await ctx.effects.ensure({
+      key: `merge:${resource.metadata.generation}:${pullRequest.head.sha}`,
+      kind: "github-merge",
+      request: {
+        repository: resource.spec.repository,
+        number: resource.spec.number,
+        expectedHeadSha: pullRequest.head.sha,
+      },
+      observe: async (signal) => {
+        const latest = await client.pullRequest(resource.spec.number, signal);
+        return latest.merged
+          ? {
+              state: "applied",
+              ...(latest.merge_commit_sha ? { externalRef: latest.merge_commit_sha } : {}),
+            }
+          : { state: "not_applied" };
+      },
+      apply: async (signal) =>
+        await client.merge(resource.spec.number, pullRequest.head.sha, signal),
+    });
+    if (effect.state === "rejected") {
+      return ctx.settled({
+        controllerStatus: { phase: "blocked", ...observed },
+        conditions: [conditionFalse("Ready", "MergeRejected", effect.error)],
+        workflowRun,
+      });
+    }
+    if (effect.state === "indeterminate") {
+      return ctx.requeueAfter(10_000, {
+        controllerStatus: { phase: "waiting", ...observed },
+        conditions: [conditionUnknown("Ready", "MergeUncertain", effect.error)],
+        workflowRun,
+      });
+    }
+    return ctx.requeue({
+      controllerStatus: { phase: "waiting", ...observed },
+      conditions: [conditionUnknown("Ready", "MergeSubmitted")],
+      workflowRun,
+    });
+  },
+});
+
+class GitHubClient {
+  private readonly baseUrl: URL;
+  private readonly owner: string;
+  private readonly repository: string;
+
+  constructor(baseUrl: string, repository: string) {
+    this.baseUrl = new URL(baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    const parts = repository.split("/");
+    if (parts.length !== 2 || parts.some((part) => part.length === 0)) {
+      throw new Error(`Invalid repository: ${repository}`);
+    }
+    this.owner = parts[0] as string;
+    this.repository = parts[1] as string;
+  }
+
+  async pullRequest(number: number, signal: AbortSignal): Promise<PullRequest> {
+    return await this.request<PullRequest>(`pulls/${number}`, { signal });
+  }
+
+  async commitStatus(sha: string, signal: AbortSignal): Promise<CommitStatus> {
+    return await this.request<CommitStatus>(`commits/${encodeURIComponent(sha)}/status`, {
+      signal,
+    });
+  }
+
+  async merge(number: number, headSha: string, signal: AbortSignal) {
+    const response = await this.rawRequest(`pulls/${number}/merge`, {
+      method: "PUT",
+      signal,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ sha: headSha }),
+    });
+    const body = (await response.json()) as {
+      merged?: boolean;
+      message?: string;
+      sha?: string;
+    };
+    if (!response.ok || body.merged !== true) {
+      return { state: "rejected" as const, error: body.message ?? `HTTP ${response.status}` };
+    }
+    return {
+      state: "applied" as const,
+      ...(body.sha !== undefined ? { externalRef: body.sha } : {}),
+    };
+  }
+
+  private async request<T>(path: string, init: RequestInit): Promise<T> {
+    const response = await this.rawRequest(path, init);
+    if (!response.ok) {
+      throw new Error(`GitHub request failed with HTTP ${response.status}`);
+    }
+    return (await response.json()) as T;
+  }
+
+  private async rawRequest(path: string, init: RequestInit): Promise<Response> {
+    const url = new URL(
+      `repos/${encodeURIComponent(this.owner)}/${encodeURIComponent(this.repository)}/${path}`,
+      this.baseUrl,
+    );
+    return await fetch(url, {
+      ...init,
+      headers: {
+        accept: "application/vnd.github+json",
+        ...init.headers,
+      },
+    });
+  }
+}
+
+function workflowReference(child: ChildWorkflowRecord) {
+  return {
+    requestId: child.requestId,
+    ...(child.runId !== undefined ? { runId: child.runId } : {}),
+    state: child.state,
+    attempt: child.attempt,
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.2.0",
-  "description": "Workflow engine, JSON control-flow tool, and live terminal viewer for the pi coding agent",
+  "version": "0.3.0",
+  "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
   ],
@@ -34,6 +34,10 @@
     "./extension": {
       "types": "./dist/extension/index.d.ts",
       "default": "./dist/extension/index.js"
+    },
+    "./controllers": {
+      "types": "./dist/controllers/index.d.ts",
+      "default": "./dist/controllers/index.js"
     }
   },
   "publishConfig": {
@@ -53,10 +57,13 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "better-sqlite3": "^13.0.2",
     "jiti": "^2.7.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.10",
     "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^26.1.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "oxfmt": "^0.59.0",
@@ -67,6 +74,7 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },