@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/docs/http-api.md

@@ -12,6 +12,41 @@ This document is the authoritative reference for the Prompt Orchestration Pipeli
 - **CORS**: Opt-in via `--cors-origins <comma-separated-origins>` and `--cors-allow-null-origin`. When no origins are configured, no `Access-Control-*` headers are emitted. Cross-origin mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) to `/api/*` are rejected before dispatch when the origin is not allowed.
 - **Content type**: All JSON responses use `Content-Type: application/json`. SSE streams use `Content-Type: text/event-stream`.
 
+## Canonical Job Status
+
+Job `status` values returned by `/api/jobs` and `/api/jobs/:id` are drawn
+from the canonical `JobStatus` enum:
+
+| Value | Meaning |
+|-------|---------|
+| `pending` | Queued, not yet started |
+| `running` | One or more tasks are executing |
+| `waiting` | Paused on a human gate (approve/reject) |
+| `complete` | All terminal tasks finished successfully (persisted `state: "done"` is mapped to this value on read) |
+| `failed` | A task or gate failed (persisted `state: "failed"` and legacy `status: "error"` both surface as this value) |
+
+The canonical vocabulary is the only vocabulary the server emits. The
+reader tolerates legacy spellings (`done`, `error`, `completed`) on
+input, but the wire `status` is always one of the five values above.
+
+### Interrupted runners
+
+When a pipeline runner process dies before its job reaches a terminal
+state (crash, OOM, `SIGKILL`, or the orchestrator dying alongside it),
+the orchestrator marks the orphaned `running` task and the job `failed`
+durably — on runner exit when the orchestrator observed the child, and
+on the next orchestrator startup via a single boot sweep over
+`current/` for jobs orphaned while the orchestrator was down (including
+detached resume runners from `/restart` and `/tasks/:taskId/start`).
+The persisted states stay the existing `failed`; the distinction from a
+task-logic failure is carried by `tasks[taskId].errorContext.kind =
+"runner-interrupted"` when a running task is attributable, or by root
+`errorContext.kind = "runner-interrupted"` when only the job-level
+status remained `running` (with `code`, `signal`, `source`). Recovery stays
+a client action via `POST /api/jobs/:jobId/restart` or
+`POST /api/jobs/:jobId/tasks/:taskId/start`; the orchestrator does not
+auto-respawn.
+
 ## Response Envelope
 
 Every JSON response uses the shape:
@@ -168,11 +203,21 @@ Clients should treat a gap longer than the keep-alive interval as a potential di
 
 | Event | Data Shape | Description |
 |-------|-----------|-------------|
-| `state:change` | `{ jobId, changeType, ... }` | A job's state has changed |
-| `state:summary` | `{ changeCount }` | Summary of accumulated state changes |
-| `job:created` | `JobSummary` | A new job was detected |
-| `job:updated` | `JobSummary` | An existing job was updated |
+| `state:change` | `{ jobId, path }` | A job's state file changed; the `jobId` is derived from the changed path |
+| `state:summary` | `{ changeCount }` | Summary of accumulated state changes when no per-job change is prioritized |
+| `job:created` | `JobSummary` | A new job was detected (summary granularity; see Caveat below) |
+| `job:updated` | `JobSummary` | An existing job was updated (summary granularity; see Caveat below) |
+| `job:removed` | `{ jobId }` | A job was removed from a watched location |
 | `heartbeat` | `{ ok, timestamp }` | Application-level heartbeat (distinct from the keep-alive comment) |
+| `seed:uploaded` | `{}` | A seed was uploaded; clients should refetch the job list |
+
+The keep-alive comment (`: keep-alive`) sent on a fixed interval is **not** an application event;
+clients must not treat it as one. Unknown event types and unknown fields within a known event
+are tolerated by the contract; clients should ignore them. `task:updated`, `status:changed`,
+bare `state`, and `message` are **not** part of the browser-facing contract and are not
+emitted on `/api/events`. `job:created` and `job:updated` carry summary-granularity
+`JobSummary` data; deep per-task detail (costs, files, per-stage state) continues to arrive
+via the existing `state:change` → refetch path.
 
 ### Job Filtering
 
@@ -230,6 +275,37 @@ Capability negotiation is not built into this protocol. Clients discover compati
 - **Adding a new event type** is a **minor** change (given the robustness rule above).
 - **Changing an existing event's payload shape** (removing or renaming a field, changing a field's type) is a **breaking** change.
 
+## Breaking Changes
+
+The changes below are observable to external HTTP/API consumers. They
+are documented here because the spec does not yet ship a real
+schema/version discriminator (deferred to #32). A dated entry is
+added for every change so consumers can grep for the cutover.
+
+### 2026-06-19 — Canonical job status and name-keyed task ids
+
+The persisted `JobState` vocabulary (`done`) and the legacy HTTP
+`status` field (`error`) are both mapped to the canonical `JobStatus`
+enum on read. Task ids are now name-keyed on the server and the
+browser; an unnamed array entry falls back to a zero-based
+`task-${index}` (e.g. `task-0`, `task-1`) so server and browser agree.
+
+| Surface | Before | After |
+|---------|--------|-------|
+| `GET /api/jobs`, `GET /api/jobs/:id` → `status` | `"error"` | `"failed"` |
+| `GET /api/jobs`, `GET /api/jobs/:id` → `status` | `"done"` | `"complete"` |
+| `PipelineOrchestrator.getStatus(...)` → `state` | `"done"` | `"complete"` |
+| `PipelineOrchestrator.listJobs()` → `state` (per job) | mixed (`done` vs `complete`) | always `"complete"` |
+| `tasks` keys (server and browser) | mixed (`task-0`/`task-1` split) | name-keyed; `task-${index}` only for unnamed array entries |
+
+Legacy spellings (`done`, `error`, `completed`) are still **accepted**
+on input by `normalizeJobStatus` / `normalizeJobView` so a mixed
+deploy or stale on-disk file does not mis-render. The server **never
+emits** `done` / `error` as a job status.
+
+This is the only external break signal shipped with this change.
+A durable schema/version discriminator is tracked in #32.
+
 ## Protocol Versioning
 
 The `protocolVersion` integer returned by `GET /api/meta` is the protocol's semver indicator:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
   "main": "src/ui/server/index.ts",
@@ -42,9 +42,6 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@babel/parser": "^7.28.5",
-    "@babel/traverse": "^7.28.5",
-    "@babel/types": "^7.28.5",
     "@radix-ui/react-progress": "^1.1.7",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.15",