@ryanfw/prompt-orchestration-pipeline 1.2.12 → 1.3.1

package/README.md

@@ -24,11 +24,13 @@ This framework is designed for AI Engineers and Systems Integrators who need to
 Running long-duration AI tasks locally can be fragile. A single script crash or API timeout can waste hours of execution and dollars in token costs.
 *   **Process Isolation**: Every pipeline runs in its own dedicated child process. If one agent crashes, your orchestrator stays alive.
 *   **Resumability**: Pause, stop, and resume jobs from any specific task. Fix a bug in step 5 and restart exactly where you left off.
+*   **Run Control**: Tasks can pause for human approval, skip downstream work, or add follow-up tasks to the current run.
 *   **Atomic State**: Every stage transition is saved to disk instantly. You never lose progress.
 
 ### 2. Gain Radical Observability
 "Black box" agents are impossible to debug. POP provides deep visibility into the "thought process" of your pipelines.
 *   **Real-Time Dashboard**: Watch jobs progress stage-by-stage via a built-in UI (Server-Sent Events).
+*   **Gate Decisions**: Approve or reject waiting jobs directly from the job detail view.
 *   **Granular Logging**: Every input, output, and internal thought is captured in dedicated log files.
 *   **Cost Tracking**: See exact token usage and cost breakdown for every task and model call.
 
@@ -48,6 +50,7 @@ Switch models globally or per-task without rewriting your logic.
     *   **Moonshot** (Kimi)
     *   **Zhipu** (GLM-4)
     *   **Claude Code** (CLI integration)
+*   **CLI Agents**: Tasks can also drive tool-using CLI coding agents (Claude, Codex, OpenCode) via the injected `runAgent()` helper — for file-aware, multi-turn work alongside single LLM calls. See the [Task Development Guide](docs/pop-task-guide.md#agent-api).
 
 ---
 
@@ -79,6 +82,7 @@ The system comprises three main runtime containers:
 Inside the **Pipeline Runner**, the logic is structured into:
 
 *   **Task Runner**: The engine that drives a specific task (e.g., "Research") through the standardized lifecycle.
+*   **Run Control Contract**: A task can write `tasks/{taskName}/control.json` to append tasks, skip pending tasks, or create an approval gate after it succeeds.
 *   **LLM Layer**: A unified abstraction for all model providers, handling retries, cost calculation, and normalization.
 *   **Symlink Bridge**: A specialized component that ensures every task has deterministic access to `node_modules` and shared utilities, regardless of where it is defined on disk.
 *   **Status Writer**: An atomic file-writer that updates `tasks-status.json` safely, preventing data corruption.
@@ -175,3 +179,33 @@ Drop a JSON file into `pipelines/pipeline-data/pending/`:
 ```
 
 The Orchestrator will pick it up, move it to `current/`, and start processing.
+
+---
+
+## Building a Custom Frontend
+
+The orchestrator exposes a documented HTTP/SSE API at `http://localhost:<port>/api/*` that any frontend can consume. See **[HTTP/SSE Protocol Reference](docs/http-api.md)** for the full contract.
+
+Custom frontends should run against a configured fixed port, usually the default `4000` or an explicit `--port` value. Treat bind failures or port conflicts as startup failures; the protocol does not provide dynamic port discovery.
+
+### Integration Modes
+
+**Subprocess mode** (recommended): Run the orchestrator as a child process via `pipeline-orchestrator start`. The orchestrator runs in its own process — if it crashes, your application stays alive. This is the default and recommended approach.
+
+**Programmatic mode**: Import `startServer` or `startOrchestrator` directly to embed the server in your process. This is simpler but forfeits process isolation — a crash in the orchestrator will take down your host process.
+
+### Cross-Origin Access
+
+By default, the server only accepts same-origin requests. To allow a custom frontend on a different origin:
+
+```bash
+pipeline-orchestrator start --cors-origins "https://my-app.example,views://mainview"
+```
+
+For desktop webviews that report `Origin: null`, add `--cors-allow-null-origin`. Prefer allowlisting the concrete origin (e.g. `views://mainview`) when possible.
+
+### Protocol Versioning
+
+The API follows a client-robustness contract: clients must ignore unknown JSON fields and unknown SSE event types. This means additive changes (new routes, new event types, new fields) are backward-compatible. Breaking changes (removing or renaming fields, changing types) require a `protocolVersion` bump and are documented in `docs/http-api.md`.
+
+Capability negotiation is not built. Custom frontends should use the documented protocol and `GET /api/meta` instead of expecting negotiated feature flags or per-client capability exchange.

package/docs/http-api.md

@@ -0,0 +1,240 @@
+# HTTP/SSE Protocol Reference
+
+This document is the authoritative reference for the Prompt Orchestration Pipeline HTTP API and Server-Sent Events stream. A consumer should be able to build a client from this document alone.
+
+## Transport
+
+- **Protocol**: HTTP/1.1 + Server-Sent Events (SSE). The API does not use WebSocket.
+- **Default port**: `4000` (configurable via `--port`).
+- **Port contract**: Custom frontends should connect to a configured fixed port. Bind failures or port conflicts are startup failures; the protocol does not provide dynamic port discovery.
+- **Bind address**: `127.0.0.1` (loopback only). The server does not listen on non-loopback interfaces.
+- **Trust model**: localhost. The `Host` header must resolve to a loopback address (`localhost`, `127.0.0.1`, or `[::1]`). Requests with a non-loopback `Host` are rejected with `403 forbidden_host`.
+- **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`.
+
+## Response Envelope
+
+Every JSON response uses the shape:
+
+```json
+{ "ok": true, "data": { ... } }
+```
+
+or on error:
+
+```json
+{ "ok": false, "code": "<error_code>", "message": "<human-readable message>" }
+```
+
+### Error Codes
+
+| Code | HTTP Status | Meaning |
+|------|-------------|---------|
+| `job_not_found` / `JOB_NOT_FOUND` / `NOT_FOUND` | 404 | Job or resource does not exist |
+| `job_running` / `JOB_RUNNING` | 409 | Job is currently executing |
+| `conflict` / `BAD_REQUEST` (409) | 409 | Action conflicts with current state |
+| `spawn_failed` / `SPAWN_FAILED` | 500 | Failed to spawn a pipeline runner |
+| `task_not_found` / `TASK_NOT_FOUND` | 404 | Task does not exist in the job |
+| `task_not_pending` / `TASK_NOT_PENDING` | 422 | Task is not in a pending state |
+| `dependencies_not_satisfied` / `DEPENDENCIES_NOT_SATISFIED` | 412 | Task dependencies are incomplete |
+| `unsupported_lifecycle` / `UNSUPPORTED_LIFECYCLE` | 501 | Lifecycle action not supported |
+| `concurrency_limit_reached` | 409 | Max concurrent job slots occupied |
+| `unknown_error` | 500 | Unspecified server error |
+| `network_error` | — | Client-side network failure (never from server) |
+| `malformed_response` | — | Client-side parse failure (never from server) |
+| `forbidden_host` | 403 | `Host` header is not loopback |
+| `forbidden_origin` | 403 | Cross-origin mutation rejected |
+| `status_unavailable` | 500 | Job status file unreadable |
+| `no_pending_gate` | 409 | Job has no pending gate decision |
+| `FS_ERROR` | 500 | Filesystem operation failed |
+| `BAD_REQUEST` | 400 | Malformed request body |
+| `NOT_FOUND` | 404 | Route or resource not found |
+
+## Routes
+
+All routes are prefixed with `/api`. The server also serves a bundled SPA from `/` for non-API paths.
+
+### Jobs
+
+| Method | Path | Request Body | Response |
+|--------|------|-------------|----------|
+| `GET` | `/api/jobs` | — | `{ ok, data: JobSummary[] }` |
+| `GET` | `/api/jobs/:jobId` | — | `{ ok, data: JobDetail }` |
+| `POST` | `/api/jobs/:jobId/gate` | `{ action: "approve" \| "reject", note?: string }` | `{ ok, jobId, action, spawned }` (202) |
+| `POST` | `/api/jobs/:jobId/restart` | `{ fromTask?: string, singleTask?: boolean, continueAfter?: boolean, options?: { clearTokenUsage?: boolean } }` | `{ ok, message? }` |
+| `POST` | `/api/jobs/:jobId/stop` | — | `{ ok, message? }` |
+| `POST` | `/api/jobs/:jobId/rescan` | — | `{ ok, message? }` |
+| `POST` | `/api/jobs/:jobId/tasks/:taskId/start` | — | `{ ok, message? }` |
+
+### Job Files
+
+| Method | Path | Query Params | Response |
+|--------|------|-------------|----------|
+| `GET` | `/api/jobs/:jobId/tasks/:taskId/files` | `?type=artifacts\|logs\|tmp` (default: `artifacts`) | `{ ok, data: string[] }` |
+| `GET` | `/api/jobs/:jobId/tasks/:taskId/file` | `?type=...&filename=...` | `{ ok, data: string, mime: string }` |
+
+### Pipelines
+
+| Method | Path | Request Body | Response |
+|--------|------|-------------|----------|
+| `GET` | `/api/pipelines` | — | `{ ok, data: { slug, name, description }[] }` |
+| `GET` | `/api/pipelines/:slug` | — | `{ ok, data: PipelineDetail }` |
+| `POST` | `/api/pipelines` | `{ name: string, description?: string }` | `{ ok, data: { slug, name, description } }` (201) |
+| `GET` | `/api/pipelines/:slug/artifacts` | — | `{ ok, data: Artifact[] }` |
+| `GET` | `/api/pipelines/:slug/tasks/:taskId/analysis` | — | `{ ok, data: AnalysisResult }` |
+| `GET` | `/api/pipelines/:slug/schemas/:filename` | — | `{ ok, data: string }` (schema content) |
+
+### Analysis and Task Planning
+
+| Method | Path | Request Body | Response |
+|--------|------|-------------|----------|
+| `POST` | `/api/pipelines/:slug/analyze` | — | SSE stream: `started` → `complete` |
+| `POST` | `/api/ai/task-plan` | — | SSE stream: `started` → `complete` |
+
+These endpoints return `Content-Type: text/event-stream` (route-local SSE). See [Route-Local SSE Streams](#route-local-sse-streams).
+
+### Tasks
+
+| Method | Path | Request Body | Response |
+|--------|------|-------------|----------|
+| `POST` | `/api/tasks/create` | `{ slug: string, taskId: string, content: string }` | `{ ok, data: { slug, taskId } }` (201) |
+
+### Upload
+
+| Method | Path | Request Body | Response |
+|--------|------|-------------|----------|
+| `POST` | `/api/upload/seed` | JSON seed object or `multipart/form-data` (with optional `.zip`) | `{ ok, data: { jobId } }` (201) |
+
+### System
+
+| Method | Path | Response |
+|--------|------|----------|
+| `GET` | `/api/state` | `{ ok, data: StateSnapshot }` |
+| `GET` | `/api/meta` | `{ ok, data: { name, version, protocolVersion } }` |
+| `GET` | `/api/concurrency` | `{ ok, data: ConcurrencyStatus }` |
+
+#### `/api/meta` Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Package name from `package.json` |
+| `version` | `string` | Package version from `package.json` |
+| `protocolVersion` | `number` | Protocol version integer; bumped only on breaking changes (see [Protocol Versioning](#protocol-versioning)) |
+
+#### `/api/concurrency` Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `limit` | `number` | Max concurrent jobs |
+| `runningCount` | `number` | Currently running jobs |
+| `availableSlots` | `number` | Remaining slot capacity |
+| `queuedCount` | `number` | Queued jobs waiting for a slot |
+| `activeJobs` | `Array<{ jobId, pid, acquiredAt, source }>` | Jobs occupying slots |
+| `queuedJobs` | `Array<{ jobId, queuedAt, name, pipeline }>` | Jobs waiting in queue |
+| `staleSlots` | `Array<{ jobId, reason }>` | Slots that appear stale |
+
+### SSE Stream (Global)
+
+| Method | Path | Query Params | Response |
+|--------|------|-------------|----------|
+| `GET` | `/api/events` | `?jobId=<id>` (optional filter) | SSE stream |
+| `GET` | `/api/sse` | `?jobId=<id>` (optional filter) | SSE stream (legacy alias) |
+
+## SSE Event Stream
+
+### Connection
+
+Connect to `GET /api/events` (or the legacy `GET /api/sse`). The server responds with:
+
+```
+Content-Type: text/event-stream
+Cache-Control: no-cache
+Connection: keep-alive
+```
+
+On connect, the server sends an initial comment: `: connected\n\n`.
+
+### Keep-Alive
+
+The server sends a keep-alive comment every **8 seconds**:
+
+```
+: keep-alive
+```
+
+Clients should treat a gap longer than the keep-alive interval as a potential disconnect.
+
+### Event Types
+
+| 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 |
+| `heartbeat` | `{ ok, timestamp }` | Application-level heartbeat (distinct from the keep-alive comment) |
+
+### Job Filtering
+
+Pass `?jobId=<id>` to receive only events whose data contains a matching `jobId` field. Without the parameter, all events are received.
+
+### SSE Framing
+
+Each event follows the standard SSE format:
+
+```
+event: <type>
+data: <JSON>
+
+```
+
+Events are separated by a blank line (`\n\n`).
+
+### Route-Local SSE Streams
+
+Two endpoints return route-local SSE streams (not from the global `/api/events` stream):
+
+**`POST /api/pipelines/:slug/analyze`**
+
+```
+event: started
+data: {"slug":"<slug>"}
+
+event: complete
+data: {"slug":"<slug>"}
+
+```
+
+Returns `409` if an analysis lock is already held for the pipeline.
+
+**`POST /api/ai/task-plan`**
+
+```
+event: started
+data: {"ok":true,"message":"task planning is not implemented in TypeScript yet"}
+
+event: complete
+data: {"ok":true}
+
+```
+
+## Client Robustness Rules
+
+1. **Ignore unknown JSON fields.** When parsing a JSON response, ignore any fields not documented here. New fields may be added in minor versions.
+2. **Ignore unknown SSE event types.** When processing the SSE stream, ignore any event type not documented here. New event types may be added in minor versions.
+
+Capability negotiation is not built into this protocol. Clients discover compatibility through the documented contract and `GET /api/meta`, not through negotiated feature flags or per-client capability exchange.
+
+## SSE Event Evolution
+
+- **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.
+
+## Protocol Versioning
+
+The `protocolVersion` integer returned by `GET /api/meta` is the protocol's semver indicator:
+
+- It is **bumped** only when `docs/http-api.md` is updated for a breaking protocol change.
+- It is **not** bumped for additive changes (new routes, new event types, new response fields) because the robustness rules make those backward-compatible.
+
+The version is defined in `src/ui/server/endpoints/meta-endpoint.ts` as `PROTOCOL_VERSION`.

package/docs/pop-task-guide.md

@@ -192,6 +192,49 @@ const response = await llm.deepseek.chat({
 
 ---
 
+## Agent API
+
+Available via the `runAgent` function passed to stages. It runs a CLI coding
+agent (the harness adapter) from inside a standard JavaScript task — the same
+machinery behind pipeline `agent:` entries, but callable mid-task with a prompt
+you build programmatically from upstream data.
+
+```js
+export const inference = async ({ runAgent, io, data, flags }) => {
+  const result = await runAgent({
+    harness: "claude",        // "claude" | "codex" | "opencode"
+    prompt: "Read 'context.md', then write a summary to 'summary.md'.",
+    // model?: string         // optional, passed through to the CLI
+    // io?: boolean           // default true: bridge POP read/write artifacts
+    // timeoutMs?: number     // optional wall-clock cap
+    // captureDiff?: boolean  // capture a git diff as 'agent.patch'
+  });
+
+  if (!result.ok) {
+    throw new Error(`Agent failed: ${result.error}`);
+  }
+
+  // result: { ok, finalMessage, artifactsWritten, usage?, costUsd?, sessionId? }
+  const summary = await io.readArtifact("summary.md");
+  return { output: { summary }, flags };
+};
+```
+
+By default (`io` is `true`) the agent shares the task's file I/O: it can call the
+`read_artifact` / `write_artifact` tools to read and write the same artifacts the
+task sees, and its `agent-result.md` is written automatically. Token usage and
+cost flow into the job status like any other LLM call.
+
+**`runAgent` vs `llm`**: use `llm.<provider>.chat()` for a single request/response
+LLM call; use `runAgent()` when you need a tool-using CLI agent that reads and
+writes files over multiple turns.
+
+**`runAgent` vs an `agent:` pipeline entry**: an `agent:` entry takes a static
+prompt from `pipeline.json`. `runAgent()` lets a JavaScript task compose the
+prompt from seed/stage data and post-process the result in later stages.
+
+---
+
 ## Validation API
 
 Available via `validators` object in stages that need schema validation.
@@ -236,6 +279,82 @@ Pipeline jobs start from a seed file in `pending/`:
 
 ---
 
+## Pipeline Task Entries
+
+Pipeline definitions can use simple string entries or object entries. String entries are still the shortest form:
+
+```json
+{
+  "tasks": ["research", "analysis", "synthesis"]
+}
+```
+
+Use object entries when multiple run steps should share one task implementation, when a step needs per-entry config, or when a step should pause for review after it succeeds:
+
+```json
+{
+  "tasks": [
+    "plan",
+    { "name": "implement-step-1", "task": "implementation-step", "config": { "step": 1 } },
+    { "name": "review", "gate": { "message": "Approve review before merge" } }
+  ],
+  "taskConfig": {
+    "implement-step-1": { "maxAttempts": 2 }
+  }
+}
+```
+
+Object entry fields:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | Yes | Unique task name for this run. |
+| `task` | No | Task registry key. Defaults to `name`. |
+| `config` | No | Per-entry config merged over `taskConfig[name]`; entry config wins on conflicts. |
+| `gate` | No | `true` or `{ "message": "...", "artifacts": ["..."] }` to pause after this task succeeds. |
+
+---
+
+## Run Control Files
+
+A task can control the rest of its run by writing `control.json` in its task directory before the stage lifecycle returns success. Use `io.getTaskDir()` to locate the directory:
+
+```js
+export const integration = async ({ io, flags }) => {
+  await Bun.write(`${io.getTaskDir()}/control.json`, JSON.stringify({
+    patch: {
+      add: [
+        { name: "implement-step-2", task: "implementation-step", config: { step: 2 } }
+      ]
+    },
+    skip: [
+      { task: "optional-review", reason: "No review required for this run" }
+    ],
+    pause: {
+      message: "Approve generated implementation plan",
+      artifacts: ["output.json"]
+    }
+  }, null, 2));
+
+  return { output: {}, flags };
+};
+```
+
+Supported directives:
+
+| Directive | Purpose |
+|-----------|---------|
+| `patch.add` | Adds new task entries to the current run's per-run `pipeline.json`. |
+| `patch.insertAfter` | Optional insertion point; defaults to the task that wrote the control file. |
+| `skip` | Marks later pending tasks as `skipped`; skipped tasks count as dependency-satisfied. |
+| `pause` | Puts the job in `waiting` and shows Approve gate / Reject gate controls in the UI. |
+
+Validation is strict. Invalid JSON, duplicate added names, unknown task registry keys, invalid skip targets, or invalid insertion points fail the emitting task with `ControlValidationError`. These failures happen after task execution succeeds and do not burn task retry attempts.
+
+Run mutations are durable but not event-sourced. The source of truth is `tasks-status.json` plus the per-run `pipeline.json`; `events.jsonl` is an append-only audit trail.
+
+---
+
 ## Context Object Reference
 
 Each stage receives:
@@ -244,6 +363,7 @@ Each stage receives:
 {
   io,                    // File I/O (may be null)
   llm,                   // LLM client
+  runAgent,              // Run a CLI agent harness (see Agent API)
   validators,            // { validateWithSchema }
   flags,                 // Control flags
   meta: { taskName, workDir, jobId },
@@ -316,4 +436,3 @@ Each stage receives:
   2. Return `{ output, flags }` from every stage
   3. Custom helper functions are valid JavaScript but will not be called by the pipeline—only use them if called from within a valid stage
   4. Most simple tasks need only: `ingestion` → `promptTemplating` → `inference`
-  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.2.12",
+  "version": "1.3.1",
   "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",
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "docs/pop-task-guide.md",
+    "docs/http-api.md",
     "README.md",
     "LICENSE"
   ],
@@ -68,7 +69,11 @@
     "react-syntax-highlighter": "^15.6.1",
     "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
-    "tslib": "^2.8.1"
+    "tslib": "^2.8.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opencode-ai/sdk": "^1.17.4",
+    "zod": "^3.25.0",
+    "local-llm-cli-adapter": "github:ryan-mahoney/local-llm-cli-adapter#2ea1aa2d8e8dbe43eb845eb4730b08a02618f476"
   },
   "devDependencies": {
     "@eslint/js": "^9.37.0",

package/src/cli/__tests__/index.test.ts

@@ -11,7 +11,10 @@ import {
   handleSubmit,
   parseTaskIndex,
   serializeTaskIndex,
+  buildUiCorsEnv,
+  program,
 } from "../index.ts";
+import pkg from "../../../package.json";
 
 // ─── helpers ─────────────────────────────────────────────────────────────────
 
@@ -418,3 +421,30 @@ describe("serializeTaskIndex", () => {
     expect(serializeTaskIndex(map).endsWith("\n")).toBe(true);
   });
 });
+
+// ─── buildUiCorsEnv ─────────────────────────────────────────────────────────
+
+describe("buildUiCorsEnv", () => {
+  it("maps corsOrigins and corsAllowNullOrigin to env vars", () => {
+    const result = buildUiCorsEnv({ port: "4000", corsOrigins: "a,b", corsAllowNullOrigin: true });
+    expect(result).toEqual({ PO_CORS_ORIGINS: "a,b", PO_CORS_ALLOW_NULL_ORIGIN: "1" });
+  });
+
+  it("returns empty object when no CORS options provided", () => {
+    const result = buildUiCorsEnv({ port: "4000" });
+    expect(result).toEqual({});
+  });
+
+  it("maps only corsOrigins when corsAllowNullOrigin is false", () => {
+    const result = buildUiCorsEnv({ port: "4000", corsOrigins: "https://app.example" });
+    expect(result).toEqual({ PO_CORS_ORIGINS: "https://app.example" });
+  });
+});
+
+// ─── version ────────────────────────────────────────────────────────────────
+
+describe("CLI version", () => {
+  it("uses the real CLI program version from package.json (AC-15)", () => {
+    expect(program.version()).toBe(pkg.version);
+  });
+});

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import { updatePipelineJson } from "./update-pipeline-json.ts";
 import { analyzeTaskFile } from "./analyze-task.ts";
 import { submitJobWithValidation, PipelineOrchestrator } from "../api/index.ts";
 import type { Registry } from "./types.ts";
+import pkg from "../../package.json";
 
 // ─── init ─────────────────────────────────────────────────────────────────────
 
@@ -28,9 +29,24 @@ export async function handleInit(root: string): Promise<void> {
 
 // ─── start ────────────────────────────────────────────────────────────────────
 
+export interface StartOptions {
+  root?: string;
+  port: string;
+  corsOrigins?: string;
+  corsAllowNullOrigin?: boolean;
+}
+
+export function buildUiCorsEnv(opts: StartOptions): Record<string, string> {
+  const env: Record<string, string> = {};
+  if (opts.corsOrigins) env["PO_CORS_ORIGINS"] = opts.corsOrigins;
+  if (opts.corsAllowNullOrigin) env["PO_CORS_ALLOW_NULL_ORIGIN"] = "1";
+  return env;
+}
+
 export async function handleStart(
   root: string | undefined,
-  port: string
+  port: string,
+  opts?: StartOptions,
 ): Promise<void> {
   const rawRoot = root ?? process.env["PO_ROOT"];
   if (!rawRoot) {
@@ -60,6 +76,9 @@ export async function handleStart(
   );
   delete uiEnv["PO_UI_PORT"];
 
+  const corsEnv = opts ? buildUiCorsEnv(opts) : {};
+  Object.assign(uiEnv, corsEnv);
+
   const orchEnv: Record<string, string> = Object.fromEntries(
     Object.entries({ ...process.env, NODE_ENV: "production", PO_ROOT: absoluteRoot }).filter(
       (entry): entry is [string, string] => entry[1] !== undefined
@@ -408,12 +427,12 @@ async function handleRunJob(jobId: string): Promise<void> {
 
 // ─── Commander program ────────────────────────────────────────────────────────
 
-const program = new Command();
+export const program = new Command();
 
 program
   .name("pipeline-orchestrator")
   .description("Prompt Orchestration Pipeline CLI")
-  .version("0.17.5");
+  .version(pkg.version);
 
 program
   .command("init")
@@ -428,8 +447,10 @@ program
   .description("Start the UI server and orchestrator")
   .option("--root <path>", "Root directory")
   .option("--port <port>", "UI server port", "4000")
-  .action(async (opts: { root?: string; port: string }) => {
-    await handleStart(opts.root, opts.port);
+  .option("--cors-origins <origins>", "Comma-separated list of allowed CORS origins")
+  .option("--cors-allow-null-origin", "Allow requests with Origin: null")
+  .action(async (opts: StartOptions) => {
+    await handleStart(opts.root, opts.port, opts);
   });
 
 program

package/src/config/__tests__/models.test.ts

@@ -15,8 +15,8 @@ import {
 } from "../models";
 import type { ModelConfigEntry } from "../models";
 
-const MODEL_COUNT = 50;
-const PROVIDER_COUNT = 8;
+const MODEL_COUNT = 51;
+const PROVIDER_COUNT = 9;
 
 describe("ModelAlias", () => {
   it(`has exactly ${MODEL_COUNT} entries`, () => {
@@ -54,6 +54,20 @@ describe("MODEL_CONFIG", () => {
     }
   });
 
+  it("opencode:default has zero pricing", () => {
+    const config = getModelConfig("opencode:default");
+    expect(config).not.toBeNull();
+    expect(config!.tokenCostInPerMillion).toBe(0);
+    expect(config!.tokenCostOutPerMillion).toBe(0);
+  });
+
+  it("contains exactly one key with the opencode: prefix", () => {
+    const opencodeKeys = Object.keys(MODEL_CONFIG).filter((k) =>
+      k.startsWith("opencode:"),
+    );
+    expect(opencodeKeys).toEqual(["opencode:default"]);
+  });
+
   it("all entries have non-negative costs", () => {
     for (const [alias, entry] of Object.entries(MODEL_CONFIG)) {
       expect(entry.tokenCostInPerMillion).toBeGreaterThanOrEqual(0);
@@ -91,7 +105,7 @@ describe("VALID_MODEL_ALIASES", () => {
 
 describe("DEFAULT_MODEL_BY_PROVIDER", () => {
   it(`has entries for all ${PROVIDER_COUNT} providers`, () => {
-    const providers = ["openai", "anthropic", "gemini", "deepseek", "moonshot", "claude-code", "zai", "alibaba"];
+    const providers = ["openai", "anthropic", "gemini", "deepseek", "moonshot", "claude-code", "zai", "alibaba", "opencode"];
     expect(Object.keys(DEFAULT_MODEL_BY_PROVIDER).length).toBe(PROVIDER_COUNT);
     for (const provider of providers) {
       expect(provider in DEFAULT_MODEL_BY_PROVIDER).toBe(true);
@@ -245,7 +259,7 @@ describe("FUNCTION_NAME_BY_ALIAS", () => {
 
 describe("PROVIDER_FUNCTIONS", () => {
   it(`has entries for all ${PROVIDER_COUNT} providers`, () => {
-    const providers = ["openai", "anthropic", "gemini", "deepseek", "moonshot", "claude-code", "zai", "alibaba"];
+    const providers = ["openai", "anthropic", "gemini", "deepseek", "moonshot", "claude-code", "zai", "alibaba", "opencode"];
     for (const provider of providers) {
       expect(provider in PROVIDER_FUNCTIONS).toBe(true);
     }