@jterrats/open-orchestra 0.3.1 → 0.4.1

package/docs/runtime-llm-flow.md

@@ -6,8 +6,9 @@ agent today.
 That means Claude, Codex, Cursor, VS Code, Windsurf, or another LLM starts the
 work, reads the relevant project instructions, and calls `orchestra` commands to
 coordinate tasks, roles, skills, handoffs, reviews, evidence, gates, and model
-routing metadata. Open Orchestra does not yet spawn real provider-backed
-subagents by itself.
+routing metadata. When a workflow role is configured with a non-`none`
+provider, `orchestra workflow run` also invokes the configured provider for
+that phase and records phase artifacts plus model provenance.
 
 ## Startup Flow
 
@@ -81,23 +82,89 @@ Generic LLM runtime:
 ```text
 Act as the parent agent. Use Open Orchestra commands as the source of truth for
 tasks, roles, skills, workflow templates, evidence, reviews, and gates. Ask the
-user before changing architecture or spending budget. Treat provider execution
-as future capability unless the project exposes an approved adapter.
+user before changing architecture or spending budget. Use provider-backed
+workflow execution only when the workflow config has approved routing.
 ```
 
 ## Model Routing
 
-Current model routing is metadata and policy plumbing. These commands inspect
-or update routing state, but they do not yet execute real provider-backed
-subagents:
+Model routing controls which provider/model each role uses during autonomous
+workflow phases. The default `none` provider keeps the deterministic workflow
+behavior. Configure a role or default route to `fake` for local structured
+execution tests, or to `openai` to use the OpenAI Responses API through the
+native provider adapter. Use `anthropic` to route phases to Claude models
+through the Anthropic Messages API.
 
 ```bash
 node bin/orchestra.js model providers --json
 node bin/orchestra.js model set-role --role qa --provider fake --model fake-model
+OPENAI_API_KEY=... node bin/orchestra.js model set-role --role architect --provider openai --model gpt-5.2
+ANTHROPIC_API_KEY=... node bin/orchestra.js model set-role --role qa --provider anthropic --model claude-sonnet-4-20250514
 node bin/orchestra.js model provenance list --json
 node bin/orchestra.js budget check --json
+node bin/orchestra.js workflow run --task STORY-001 --gates phase
 ```
 
+The OpenAI adapter reads `OPENAI_API_KEY` from the environment and optionally
+`OPENAI_BASE_URL` for an HTTPS-compatible endpoint. API keys must not be stored
+in workflow config, evidence, docs, or committed files.
+
+The Anthropic adapter reads `ANTHROPIC_API_KEY` from the environment and
+optionally `ANTHROPIC_BASE_URL` for an HTTPS-compatible endpoint. It uses
+`ANTHROPIC_VERSION` when provided, otherwise the default API version is
+`2023-06-01`. JSON-mode requests add an explicit JSON-only instruction because
+Claude Messages API responses are normalized through text content rather than
+OpenAI-style JSON schema response formatting.
+
+## Runtime Execution
+
+Runtime execution is separate from model provider routing. `ModelProvider`
+adapters call vendor APIs directly and therefore require provider API keys.
+Runtime execution adapters prepare work for an already-authenticated runtime
+such as Claude CLI, Codex CLI, Cursor, VS Code, or Windsurf.
+
+Use runtime execution when the user wants the active CLI/IDE agent to perform
+the work and does not want Orchestra to call OpenAI, Anthropic, or another
+vendor API directly:
+
+```bash
+node bin/orchestra.js runtime adapters --json
+node bin/orchestra.js runtime brief --task STORY-001 --runtime claude-cli
+node bin/orchestra.js runtime delegate-plan --task STORY-001 --runtime claude-cli --roles architect,developer,qa
+node bin/orchestra.js runtime handoff --task STORY-001 --runtime claude-cli --artifact .agent-workflow/runs/STORY-001-runtime-claude-cli-delegation.md
+```
+
+Runtime briefs and delegation packets are written under `.agent-workflow/runs/`
+and record provenance events. They are brief-only control artifacts in this
+release; Orchestra does not launch arbitrary runtime processes or silently fall
+back to vendor APIs.
+
+Runtime policy can force executor selection without API keys:
+
+```json
+{
+  "runtimePolicy": {
+    "defaults": { "executor": "generic-runtime" },
+    "byRole": { "developer": { "executor": "codex-cli" } },
+    "byTask": { "STORY-001": { "executor": "claude-cli" } },
+    "delegation": {
+      "mode": "runtime-native",
+      "allowDirectProviderApi": false
+    }
+  }
+}
+```
+
+If a runtime does not support native subagents, Orchestra renders a delegation
+packet in `brief-only` mode and requires user approval before any other
+execution strategy. Direct provider API calls remain forbidden by runtime
+execution packets.
+
+Provider policy can restrict real adapters with `allowedProviders` and
+`blockedProviders`. Cross-vendor fallback is blocked by default; enable
+`allowVendorFallbackWithoutApproval` only after recording the required approval
+for cost, privacy, and capability risk.
+
 Future multi-model delegation should route by role capability, risk, budget,
 latency, and required evidence. For example, a parent agent could keep planning
 local, route security review to a stronger security model, route Playwright
@@ -106,8 +173,12 @@ budget fallback.
 
 ## Current Limits
 
-- Open Orchestra has fake/provider-routing primitives, not real autonomous
-  provider execution.
+- Provider-backed workflow execution has a fake adapter for deterministic tests,
+  an OpenAI adapter for the Responses API, and an Anthropic adapter for the
+  Claude Messages API. Additional vendors need explicit implementation and
+  approval.
+- Runtime execution adapters render briefs and delegation packets, but they do
+  not yet launch external CLI/IDE processes non-interactively.
 - It records delegation decisions, but it does not automatically spawn
   subagents yet.
 - Parallel independent CLI commands are expected to work, but dependent commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "bin": {
     "orchestra": "bin/orchestra.js"