@signalridge/pi-workflows 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## Unreleased
+- **Semantic workflow tiers:** tasks, synthesis, and an optional run default can request only `small`, `medium`, or `large`; model and thinking policy stays inside pi-subagents. The release requires `@signalridge/pi-subagents >=0.16.0-signalridge.1` and the v3 `workflowTiers` capability.
+
+- Persist restore recovery as one validated run-level atomic event, with bounded task/synthesis rotations, terminal-record reconciliation, and legacy-prefix migration.
+- Add deterministic bounded recovery IDs and per-run duplicate replay quarantine; legacy schema-v2 atomic records without an ID are normalized once without weakening generation checks, and durable-append retries remain exactly-once.
+- Require the protocol's owner-scoped quiescence capability and keep terminal cleanup in `stopping` until managed sessions and dispatches have actually settled; retry transient recovery and lifecycle journal appends.
+- Quiesce managed agents that answer a spawn request after stop or branch replacement, preventing a late dispatch from being published as a false terminal workflow.
+- Preserve exact terminal cleanup targets across retries and fail closed when legacy peers cannot prove dispatch quiescence.
+- Keep observed terminal lifecycle facts ahead of synthetic stop/failure facts while journal retries or durable prefixes remain unresolved; a permanently blocked journal stays nonterminal.
+- Owner-quiesce late spawn responses during branch replacement and report any late target that cannot settle instead of treating dispatch completion as proof.
+
+- Require and verify pi-subagents protocol v3 before managed workflow dispatch, including the owner-scoped `ownedStop` capability; workflow cleanup fails closed instead of falling back to unowned stop.
+- Recover unreconciled dispatches, settle stop/failure cleanup, and expose bounded run details.
+- Bound synthesis instructions and aggregate input to 48,000 characters.
+- Replay current-attempt interrupted records as one journaled attempt generation without creating failed task facts; stale records are ignored after replay.
+- Fail stopped-task workflows conservatively and report/quarantine incomplete branch quiescence instead of accepting late lifecycle events.
+- Keep protocol discovery nonblocking and defer the missing-companion diagnostic until a workflow tool call.
+- Bound interrupted-attempt recovery to three generations per node, including synthesis, and fail safely beyond the limit instead of retrying an outer workflow indefinitely.
+- Supersede every unreconciled task and synthesis dispatch during restore, including dispatches without agent IDs, before resuming lifecycle listeners.
+- Require attempt-scoped owners for managed stop/quiescence, track dispatches without agent IDs during branch changes, and quarantine stale responses before they can mutate the restored run.
+- Keep foreground wait cancellation separate from managed child cancellation; session shutdown only aborts the caller's outstanding RPC wait.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 signalridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @signalridge/pi-workflows
+
+Declarative DAG orchestration for Pi. The `workflow` tool validates phases, task dependencies, cycles, bounded synthesis input, and optional `small`/`medium`/`large` semantic tiers, then submits ready tasks through the additive `subagents:rpc:spawn-managed` event-bus protocol. `pi-subagents` remains the only owner of model, thinking, queue, concurrency, tools, skills, cwd, isolation, retry, and session policy.
+
+## Install
+
+`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=0.16.0-signalridge.1` with protocol v3 managed-spawn support. They are separate Pi packages: the peer dependency documents the requirement but intentionally does not auto-load or duplicate the subagent extension.
+
+```bash
+pi install npm:@signalridge/pi-subagents
+pi install npm:@signalridge/pi-workflows
+```
+
+## Use from this checkout
+
+From the repository root, load both local package directories once:
+
+```bash
+pi -e ./packages/pi-subagents
+pi -e ./packages/pi-workflows
+```
+
+Pi activates each package from its own `pi.extensions` manifest. The dotfiles migration configures these two local paths together; do not add a second source for either package.
+
+At `session_start`, this extension sends `subagents:rpc:ping` and verifies protocol version 3 plus the `managedSpawn`, `lifecycleOwner`, owner-scoped `ownedStop`, `ownedQuiescence`, and `workflowTiers` capabilities. The package floor and capability check prevent older v3 peers from receiving tiered requests they cannot validate. If the fork is missing, old, or duplicated incorrectly, workflow execution returns a diagnostic naming the required packages instead of dispatching agents. The legacy unowned stop RPC remains available to older external callers, but workflow cleanup never falls back to it.
+
+## Tools and command
+
+- `workflow`: run a foreground or background workflow.
+- `workflow_control`: `list`, `get`, `pause`, `resume`, or `stop` a run. `get` returns bounded task and synthesis details including status, agent ID, compactions, and result/error previews.
+- `/workflows`: TUI run list/detail navigator. Live agent conversation navigation remains in pi-subagents FleetView.
+
+State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries, which do not enter model context. Results and synthesis instructions are capped before journaling or dispatch. Interrupted runs reset unreconciled dispatches to a recoverable state and reuse their managed spawn keys; completed task facts are not dispatched again. A task failure stops remaining owned agents, journals their terminal callbacks, blocks dependents, and settles the workflow as failed.
+Restore rotation is journaled atomically per run (`run_recovery`) so a failed append leaves no partial generation; older multi-entry recovery prefixes remain replayable and are migrated with independent `attempt_recovery` entries.
+Each atomic recovery also carries a deterministic bounded `recoveryId` derived from its branch/run and attempt rotations. Replay treats an exact normalized duplicate as a no-op, quarantines same-ID conflicts, and accepts older schema-v2 atomic entries without an ID only through deterministic legacy normalization.
+Managed lifecycle calls are owner-scoped to the exact `{ runId, nodeId, attemptId }` generation. Branch replacement stops/quiesces owned agents and tracks in-flight dispatch RPCs; if a peer cannot settle, the run is quarantined conservatively and late lifecycle or spawn replies are ignored. Foreground `AbortSignal`s cancel only the caller's wait. The session signal may cancel an outstanding RPC wait during shutdown, but neither signal is used to cancel a managed child; explicit stop/quiescence owns child cancellation.
+
+
+Interrupted-attempt recovery is intentionally bounded to three generations per task, including synthesis. Normal interruptions retry with a fresh managed attempt; if the same node is interrupted repeatedly beyond that bound, the workflow fails safely instead of creating an unbounded outer retry loop.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@signalridge/pi-workflows",
+  "version": "0.2.0",
+  "description": "Declarative DAG workflows backed by pi-subagents managed spawning.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "workflow",
+    "dag"
+  ],
+  "piExtension": {
+    "lifecycle": "stable"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@signalridge/pi-subagents": ">=0.16.0-signalridge.1"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "@signalridge/pi-subagents-protocol": "^0.1.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signalridge/pi-extensions",
+    "directory": "packages/pi-workflows"
+  },
+  "homepage": "https://github.com/signalridge/pi-extensions/tree/main/packages/pi-workflows",
+  "bugs": {
+    "url": "https://github.com/signalridge/pi-extensions/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest run test --config vitest.config.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "check": "bun run lint && bun run typecheck && bun run test",
+    "format": "biome check --write ."
+  }
+}