@osolmaz/pi-workflows 0.15.3 → 0.16.0

package/docs/tui-viewer.md

@@ -9,11 +9,11 @@ a recorded Pi conversation, themes, and remote viewing.
 
 The viewer uses the [incremental and virtualized viewer design](plans/2026-08-28-piw-incremental-viewer-plan.md).
 
-The run browser reads small metadata rows. It does not load trace, step, session, settings, or follow-up payloads. The local viewer checks SQLite `data_version` on its timer. When the value is unchanged, the timer does not scan runs or read payloads.
+The run browser subscribes to small host-owned metadata views. It does not load trace, step, session, settings, or follow-up payloads. The host publishes a new bounded view only when its content changes.
 
-The selected run contains bounded pages. Step, trace, session-entry, and session-event pages contain at most 256 rows. Replay can jump to any position. The viewer loads the page that contains that position and keeps only the current windows. A compact graph projection keeps the latest attempt for each node and the taken transitions up to the replay point.
+The selected run contains bounded pages. Step, trace, session-entry, session-event, settings, follow-up, and update pages have both a row limit and a byte budget. Replay can jump to any position. The viewer loads the page that contains that position and keeps only the current windows. A session-event page includes the replay checkpoint immediately before its first event. A compact graph projection keeps the latest attempt for each node and the taken transitions up to the replay point.
 
-Local page reads run outside input and drawing through one overwrite-only request slot. A newer selection replaces pending work. A failed first read leaves the run browser usable. A failed refresh keeps the last good view and marks it stale.
+Large values use host content references. `piw` fetches them in bounded chunks when the user opens the related detail, verifies the byte count and SHA-256 digest, and then shows the complete text or JSON value. Page and content requests run outside input and drawing through the shared client protocol. A newer page selection replaces the previous request, including when the user returns to an earlier page. A failed first read leaves the run browser usable. A failed refresh keeps the last good view and marks it stale.
 
 ## Install
 
@@ -26,17 +26,15 @@ cargo install pi-workflows
 
 ## Modes
 
-- `piw` browses `~/.pi/agent/workflows/state.sqlite` through a read-only SQLite connection.
-- `piw <runId>` opens one run from that database.
-- `piw serve [--bind 127.0.0.1:9377]` exposes database-backed run views over the
-  [live replay protocol](live-replay-protocol.md). Only
-  loopback addresses are accepted; use an SSH tunnel for remote viewing.
+- `piw` connects to the local package-owned workflow host. If the socket is absent, it runs the installed `pi-workflows host start` command.
+- `piw <runId>` opens one host-owned run view.
+- `piw <runId> --once` waits for that run, renders one complete 120 × 40 plain-text frame, and exits. It returns a nonzero status for host, protocol, missing-run, or snapshot-timeout failures.
+- `piw serve [--bind 127.0.0.1:9377]` relays each WebSocket connection to one host socket over the [live client protocol](live-replay-protocol.md). Only loopback addresses are accepted; use an SSH tunnel for remote viewing.
 - `piw --connect ws://…` reads from another `piw serve` process.
 - `piw --theme <name>` selects a theme for this invocation.
 - `piw --list-themes` prints the built-in theme names.
 
-Direct database mode and connected mode use the same semantic run view.
-The protocol is the network form of that view.
+Local and remote modes use the same semantic run view and the same protocol. `piw` has no SQLite mode or database schema copy.
 
 ## Herdr
 
@@ -211,11 +209,9 @@ listing and selected-run subscription after the server returns. Cached content
 stays visible but is labeled reconnecting or disconnected, never current.
 Revision gaps force a bounded snapshot.
 
-`piw serve` keeps one loaded projection and one graph scene for each watched run. The first watcher loads it. Later watchers reuse it. The last unwatch or disconnect releases it. Clients keep separate revision and page cursors, so one client's replay jump does not move another client. A lagged client gets a bounded snapshot instead of an unbounded patch backlog.
+`piw serve` is a frame relay. It keeps no run projection or client activity after either side closes. Clients keep separate revision and page cursors, so one client's replay jump does not move another client. A lagged client gets a bounded snapshot instead of an unbounded patch backlog.
 
-Expanded prompt and output fields come from content-addressed SQLite blobs.
-The local reader uses query-only mode. Remote snapshots carry the same bounded
-semantic view and do not expose a filesystem path.
+The host resolves expanded prompt and output fields from durable content. Local and remote snapshots carry the same bounded semantic view and do not expose a database path.
 
 ## Interaction
 

package/docs/workflows.md

@@ -126,6 +126,8 @@ pi-workflows host run
 `host run` stays attached. The other commands start, inspect, or stop the
 on-demand process. No command installs an operating-system service.
 
+The extension, CLI, and `piw` use the same version-1 client protocol over a Unix socket or Windows named pipe. The host sends byte-bounded run-list and run-view pages. Clients collect a complete run list for one revision and reject stale run pages whose cursor or revision no longer matches. The host reads only the selected history ranges and reuses an unchanged subscribed view after a lightweight revision check. It waits for a slow socket to drain and removes every subscription when its client unsubscribes. Large values stay available through verified content chunks. Host-generated aggregate values are saved and linked to the run before the host advertises them.
+
 A worker verifies the root and all mounted source identities before it loads
 workflow modules. It then checks the resolved mounted-source map and executes
 from committed state through a host-backed store. A source mismatch parks the
@@ -193,7 +195,10 @@ For submitted output, the engine appends the existing workflow-tool contract.
 The host checks the durable transport identifiers, stores a `validating`
 submission, and starts a supervised worker. In that worker, the output passes
 through tolerant JSON normalization and then `validate`. The tool reports
-success only after this check accepts the output. Rejected submissions return
+success only after this check accepts the output. If the tool turn is aborted,
+the client stops waiting but does not cancel the durable host command. A retry
+uses a new transport request ID with the same durable submission identity and
+adopts the stored result. Rejected submissions return
 the validation error and can retry in the same step. If the model settles
 without submitting, the durable request stays pending until it receives valid
 output, times out, or is cancelled. For assistant-message output, the engine appends a normal-response contract,
@@ -795,3 +800,41 @@ const engine = new WorkflowEngine({
 });
 const { state } = await engine.run(workflow, { task: "..." });
 ```
+
+## Test the installed package
+
+The installed-package end-to-end test packs this repository and installs the
+archive with production dependencies in a temporary consumer project. It then
+starts the repository-pinned base Pi with only that Pi Workflows installation.
+The test checks command isolation, host startup, widget and status changes,
+pause, resume, completion, and `piw <runId> --once` output.
+
+Run the deterministic phase without a model call:
+
+```bash
+npm run test:e2e:live -- --runtime-only
+```
+
+A real-model phase is manual. Supply the exact Pi provider and model as separate
+values. The runner does not select a default or accept model fallback:
+
+```bash
+npm run test:e2e:live -- \
+  --provider openai \
+  --model gpt-5.6-luna
+```
+
+For subscription authentication, use a dedicated Pi profile that has no other
+extensions or resources:
+
+```bash
+npm run test:e2e:live -- \
+  --profile ~/.config/pi-workflows-e2e/openai-codex \
+  --provider openai-codex \
+  --model gpt-5.6-luna
+```
+
+The profile and normal provider environment remain operator-owned. The runner
+does not read, copy, print, or save credentials. It uses one guarded temporary
+root and removes that root after success or failure. Use `--keep` only when you
+need the isolated files for diagnosis.

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.15.3"
+version = "0.16.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.15.3",
+  "version": "0.16.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -24,6 +24,7 @@
     "examples",
     "docs",
     "schemas",
+    "protocol",
     "plugins/herdr",
     "herdr-plugin.toml",
     "README.md",
@@ -39,6 +40,10 @@
       "types": "./dist/extension/index.d.ts",
       "default": "./dist/extension/index.js"
     },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
     "./controllers": {
       "types": "./dist/controllers/index.d.ts",
       "default": "./dist/controllers/index.js"
@@ -62,11 +67,13 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:live": "node scripts/live-e2e.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "better-sqlite3": "^13.0.2",
-    "jiti": "^2.7.0"
+    "jiti": "^2.7.0",
+    "tsx": "^4.23.13"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.84.2",
@@ -77,7 +84,6 @@
     "@vitest/coverage-istanbul": "^4.1.10",
     "oxfmt": "^0.59.0",
     "oxlint": "^1.74.0",
-    "tsx": "^4.23.1",
     "typebox": "^1.3.6",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"

package/protocol/client.v1.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/blob/main/protocol/client.v1.schema.json",
+  "title": "Pi Workflows client protocol version 1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "type", "connectionId", "packageVersion"],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "hello" },
+        "connectionId": { "$ref": "#/$defs/opaqueId" },
+        "packageVersion": { "type": "string", "minLength": 1 }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "type",
+        "requestId",
+        "clientId",
+        "operation",
+        "idempotencyKey",
+        "payload"
+      ],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "request" },
+        "requestId": { "$ref": "#/$defs/opaqueId" },
+        "clientId": { "$ref": "#/$defs/opaqueId" },
+        "operation": {
+          "enum": [
+            "run.start",
+            "run.pause",
+            "run.resume",
+            "run.cancel",
+            "run.status",
+            "run.list",
+            "checkpoint.answer",
+            "decision.answer",
+            "interaction.submit",
+            "interaction.update",
+            "notification.claim",
+            "notification.deliver",
+            "turn.claim",
+            "turn.resolve",
+            "controller.list",
+            "controller.get",
+            "controller.apply",
+            "controller.reconcile",
+            "controller.delete",
+            "host.status",
+            "host.stop",
+            "view.runs.watch",
+            "view.runs.page",
+            "view.run.get",
+            "view.run.watch",
+            "view.run.unwatch",
+            "view.page",
+            "view.content",
+            "view.session.watch",
+            "activity.report",
+            "state.status",
+            "state.verify",
+            "state.backup",
+            "state.prune"
+          ]
+        },
+        "idempotencyKey": { "$ref": "#/$defs/opaqueId" },
+        "runId": { "$ref": "#/$defs/opaqueId" },
+        "expectedRevision": { "$ref": "#/$defs/revision" },
+        "payload": {}
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "type", "requestId", "outcome"],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "response" },
+        "requestId": { "$ref": "#/$defs/opaqueId" },
+        "outcome": {
+          "enum": [
+            "accepted",
+            "adopted",
+            "rejected",
+            "conflict",
+            "notFound",
+            "claimLost",
+            "unavailable"
+          ]
+        },
+        "revision": { "$ref": "#/$defs/revision" },
+        "receipt": {},
+        "error": { "type": "string", "minLength": 1 }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "type", "subscriptionId", "event", "payload"],
+      "properties": {
+        "schema": { "const": "pi-workflows.client.v1" },
+        "type": { "const": "event" },
+        "subscriptionId": { "$ref": "#/$defs/opaqueId" },
+        "event": {
+          "enum": [
+            "runs",
+            "run_snapshot",
+            "run_patch",
+            "run_page",
+            "session_snapshot",
+            "unavailable"
+          ]
+        },
+        "revision": { "$ref": "#/$defs/revision" },
+        "runId": { "$ref": "#/$defs/opaqueId" },
+        "payload": {}
+      }
+    }
+  ],
+  "$defs": {
+    "opaqueId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 0
+    }
+  }
+}

package/protocol/fixtures/client-v1.json

@@ -0,0 +1,23 @@
+{
+  "valid": [
+    "{\"connectionId\":\"connection-1\",\"packageVersion\":\"0.15.3\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"hello\"}",
+    "{\"clientId\":\"client-1\",\"idempotencyKey\":\"key-1\",\"operation\":\"host.status\",\"payload\":{},\"requestId\":\"request-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"request\"}",
+    "{\"clientId\":\"client-1\",\"idempotencyKey\":\"key-runs-page\",\"operation\":\"view.runs.page\",\"payload\":{\"cursor\":2,\"revision\":\"3:10:20\"},\"requestId\":\"request-runs-page\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"request\"}",
+    "{\"clientId\":\"client-1\",\"idempotencyKey\":\"key-run-get\",\"operation\":\"view.run.get\",\"payload\":{},\"requestId\":\"request-run-get\",\"runId\":\"run-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"request\"}",
+    "{\"clientId\":\"client-1\",\"expectedRevision\":7,\"idempotencyKey\":\"key-page\",\"operation\":\"view.page\",\"payload\":{\"cursor\":299,\"kind\":\"steps\"},\"requestId\":\"request-page\",\"runId\":\"run-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"request\"}",
+    "{\"clientId\":\"client-1\",\"idempotencyKey\":\"key-content\",\"operation\":\"view.content\",\"payload\":{\"offset\":0,\"path\":\"artifacts/sha256/abc.json\"},\"requestId\":\"request-content\",\"runId\":\"run-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"request\"}",
+    "{\"outcome\":\"accepted\",\"receipt\":{\"live\":true},\"requestId\":\"request-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"response\"}",
+    "{\"outcome\":\"accepted\",\"receipt\":{\"large\":100000000000000000000,\"𐀀\":2,\"\":1},\"requestId\":\"request-canonical\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"response\"}",
+    "{\"event\":\"run_snapshot\",\"payload\":{\"revision\":7,\"runId\":\"run-1\",\"schema\":\"pi-workflows.run-view.v1\"},\"revision\":3,\"runId\":\"run-1\",\"schema\":\"pi-workflows.client.v1\",\"subscriptionId\":\"subscription-run\",\"type\":\"event\"}",
+    "{\"event\":\"session_snapshot\",\"payload\":{\"run\":null,\"schema\":\"pi-workflows.session-view.v1\",\"sessionId\":\"session-1\"},\"revision\":1,\"schema\":\"pi-workflows.client.v1\",\"subscriptionId\":\"subscription-1\",\"type\":\"event\"}"
+  ],
+  "invalid": [
+    "{\"schema\":\"pi-workflows.client.v1\",\"type\":\"hello\",\"connectionId\":\"connection-1\",\"packageVersion\":\"0.15.3\"}",
+    "{\"connectionId\":\"connection-1\",\"extra\":true,\"packageVersion\":\"0.15.3\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"hello\"}",
+    "{\"clientId\":\"client-1\",\"idempotencyKey\":\"key-1\",\"operation\":\"unknown\",\"payload\":{},\"requestId\":\"request-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"request\"}",
+    "{\"extra\":true,\"outcome\":\"accepted\",\"requestId\":\"request-1\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"response\"}",
+    "{\"outcome\":\"accepted\",\"receipt\":{\"large\":1e+20},\"requestId\":\"request-canonical\",\"schema\":\"pi-workflows.client.v1\",\"type\":\"response\"}",
+    "{\"event\":\"unknown\",\"payload\":{},\"schema\":\"pi-workflows.client.v1\",\"subscriptionId\":\"subscription-1\",\"type\":\"event\"}",
+    "{\"outcome\":\"accepted\",\"requestId\":\"request-1\",\"schema\":\"pi-workflows.client.v2\",\"type\":\"response\"}"
+  ]
+}

package/src/client/activity.ts

@@ -0,0 +1,6 @@
+export const ORIGIN_ACTIVITY_REFRESH_MS = 1_000;
+export const ORIGIN_ACTIVITY_LEASE_MS = 4_000;
+
+if (ORIGIN_ACTIVITY_REFRESH_MS >= ORIGIN_ACTIVITY_LEASE_MS) {
+  throw new Error("Origin activity refresh period must be shorter than its lease");
+}