@chllming/wave-orchestration 0.5.1

package/docs/reference/runtime-config/README.md

@@ -0,0 +1,85 @@
+# Runtime Configuration Reference
+
+This directory is the canonical reference for executor configuration in Wave `0.5.x`.
+
+Use it when you need the full supported surface for:
+
+- `wave.config.json`
+- `lanes.<lane>.executors`
+- `executors.profiles.<profile>`
+- per-agent `### Executor` blocks inside a wave file
+
+## Naming Conventions
+
+- `wave.config.json` uses camelCase keys such as `profileName`, `addDirs`, `settingsJson`, and `allowedHttpHookUrls`.
+- Wave markdown `### Executor` blocks use snake_case after the runtime prefix, such as `codex.profile_name`, `codex.add_dirs`, `claude.settings_json`, and `claude.allowed_http_hook_urls`.
+
+## Resolution Order
+
+Executor id selection resolves in this order:
+
+1. agent `### Executor` `id`
+2. agent `### Executor` `profile` -> `executors.profiles.<profile>.id`
+3. `lanes.<lane>.runtimePolicy.defaultExecutorByRole`
+4. launcher `--executor`
+5. `executors.default`
+
+Runtime settings resolve in layers:
+
+1. `executors.<runtime>` global defaults
+2. `lanes.<lane>.executors.<runtime>` lane overrides
+3. `executors.profiles.<profile>` or `lanes.<lane>.executors.profiles.<profile>`
+4. agent `### Executor`
+
+Merge behavior:
+
+- scalar values override from later layers
+- list values merge for profile plus agent resolution on top of the lane base
+- lane executor overrides replace the corresponding global runtime fields before profile and agent resolution
+- a lane profile with the same name as a global profile replaces that profile definition for the lane
+
+## Common Fields
+
+These fields are shared across runtimes:
+
+| Surface | `wave.config.json` / profile key | Wave `### Executor` key | Notes |
+| --- | --- | --- | --- |
+| Executor id | `id` in profile only | `id` | Runtime id: `codex`, `claude`, `opencode`, `local` |
+| Profile selection | n/a | `profile` | Selects `executors.profiles.<name>` |
+| Model | `model` in profile, `executors.claude.model`, `executors.opencode.model` | `model` | Codex uses shared `model` from profile or agent only |
+| Fallbacks | `fallbacks` in profile | `fallbacks` | Runtime ids used for retry-time reassignment |
+| Tags | `tags` in profile | `tags` | Stored in resolved executor state for policy and traces |
+| Budget turns | `budget.turns` in profile | `budget.turns` | Seeds Claude `maxTurns` and OpenCode `steps` when runtime-specific values are absent |
+| Budget minutes | `budget.minutes` in profile | `budget.minutes` | Caps attempt timeout |
+
+## Runtime Pages
+
+- [codex.md](./codex.md)
+- [claude.md](./claude.md)
+- [opencode.md](./opencode.md)
+
+## Generated Artifacts
+
+Wave writes runtime artifacts here:
+
+- live runs: `.tmp/<lane>-wave-launcher/executors/wave-<n>/<agent-slug>/`
+- dry-run previews: `.tmp/<lane>-wave-launcher/dry-run/executors/wave-<n>/<agent-slug>/`
+
+Common files:
+
+- `launch-preview.json`: resolved invocation lines, env vars, and retry mode
+- `claude-system-prompt.txt`: generated Claude harness prompt overlay
+- `claude-settings.json`: generated Claude settings overlay when inline settings data is present
+- `opencode-agent-prompt.txt`: generated OpenCode harness prompt overlay
+- `opencode.json`: generated OpenCode runtime config overlay
+
+## Recommended Validation Path
+
+Use dry-run before relying on a new runtime configuration:
+
+```bash
+pnpm exec wave doctor
+pnpm exec wave launch --lane main --dry-run --no-dashboard
+```
+
+Then inspect the generated preview and overlay files under `.tmp/<lane>-wave-launcher/dry-run/executors/`.

package/docs/reference/runtime-config/claude.md

@@ -0,0 +1,105 @@
+# Claude Runtime Configuration
+
+Wave launches Claude headlessly with `claude -p --no-session-persistence`.
+
+## Supported Configuration
+
+| Behavior | `wave.config.json` / profile key | Wave `### Executor` key | Launch effect |
+| --- | --- | --- | --- |
+| Command | `executors.claude.command`, `executors.profiles.<name>.claude.command` | `claude.command` | Selects the executable |
+| Default model | `executors.claude.model`, `executors.profiles.<name>.model` | `model` | Adds `--model <name>` |
+| Agent | `executors.claude.agent`, `executors.profiles.<name>.claude.agent` | `claude.agent` | Adds `--agent <name>` |
+| Prompt mode | `executors.claude.appendSystemPromptMode` | n/a | Uses `--append-system-prompt-file` or `--system-prompt-file` |
+| Permission mode | `executors.claude.permissionMode`, `executors.profiles.<name>.claude.permissionMode` | `claude.permission_mode` | Adds `--permission-mode <mode>` |
+| Permission prompt tool | `executors.claude.permissionPromptTool`, `executors.profiles.<name>.claude.permissionPromptTool` | `claude.permission_prompt_tool` | Adds `--permission-prompt-tool <tool>` |
+| Max turns | `executors.claude.maxTurns`, `executors.profiles.<name>.claude.maxTurns` | `claude.max_turns` | Adds `--max-turns <n>` |
+| MCP config | `executors.claude.mcpConfig`, `executors.profiles.<name>.claude.mcpConfig` | `claude.mcp_config` | Adds repeated `--mcp-config <path>` |
+| Strict MCP mode | `executors.claude.strictMcpConfig`, `executors.profiles.<name>.claude.strictMcpConfig` | n/a | Adds `--strict-mcp-config` |
+| Base settings file | `executors.claude.settings`, `executors.profiles.<name>.claude.settings` | `claude.settings` | Passed through `--settings` when no inline overlay is generated, or used as the base for the generated overlay |
+| Inline settings JSON | `executors.claude.settingsJson`, `executors.profiles.<name>.claude.settingsJson` | `claude.settings_json` | Merged into generated settings overlay |
+| Inline hooks JSON | `executors.claude.hooksJson`, `executors.profiles.<name>.claude.hooksJson` | `claude.hooks_json` | Written under top-level `hooks` in the generated settings overlay |
+| Allowed HTTP hook URLs | `executors.claude.allowedHttpHookUrls`, `executors.profiles.<name>.claude.allowedHttpHookUrls` | `claude.allowed_http_hook_urls` | Written under top-level `allowedHttpHookUrls` in the generated settings overlay |
+| Output format | `executors.claude.outputFormat`, `executors.profiles.<name>.claude.outputFormat` | `claude.output_format` | Adds `--output-format text|json|stream-json` |
+| Allowed tools | `executors.claude.allowedTools`, `executors.profiles.<name>.claude.allowedTools` | `claude.allowed_tools` | Adds repeated `--allowedTools <tool>` |
+| Disallowed tools | `executors.claude.disallowedTools`, `executors.profiles.<name>.claude.disallowedTools` | `claude.disallowed_tools` | Adds repeated `--disallowedTools <tool>` |
+
+## Overlay Behavior
+
+Wave always writes `claude-system-prompt.txt` for the harness runtime instructions.
+
+Wave writes `claude-settings.json` only when at least one inline overlay input is present:
+
+- `settingsJson`
+- `hooksJson`
+- `allowedHttpHookUrls`
+
+Merge order:
+
+1. base `claude.settings` JSON file, if provided
+2. inline `settingsJson`
+3. inline `hooksJson` under top-level `hooks`
+4. inline `allowedHttpHookUrls` under top-level `allowedHttpHookUrls`
+
+If no inline overlay data is present, Wave passes the base `claude.settings` file directly through `--settings` without generating `claude-settings.json`.
+
+## Example: `wave.config.json`
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "deep-review": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "turns": 10,
+          "minutes": 30
+        },
+        "claude": {
+          "agent": "reviewer",
+          "permissionMode": "plan",
+          "allowedTools": ["Read"],
+          "disallowedTools": ["Edit"]
+        }
+      }
+    },
+    "claude": {
+      "command": "claude",
+      "appendSystemPromptMode": "append",
+      "outputFormat": "text",
+      "settingsJson": {
+        "permissions": {
+          "allow": ["Read"]
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: Wave `### Executor`
+
+````md
+### Executor
+
+- id: claude
+- model: claude-sonnet-4-6
+- claude.permission_mode: plan
+- claude.max_turns: 4
+- claude.settings_json: {"permissions":{"allow":["Read"]}}
+- claude.hooks_json: {"Stop":[{"command":"echo stop"}]}
+- claude.allowed_http_hook_urls: https://example.com/hooks
+- claude.output_format: json
+- claude.allowed_tools: Read
+- claude.disallowed_tools: Edit
+````
+
+## Dry-Run Output
+
+For a dry run, inspect:
+
+- `claude-system-prompt.txt`
+- `claude-settings.json`, when generated
+- `launch-preview.json`
+
+`launch-preview.json` shows the final `claude -p` invocation and whether `--settings`, `--allowedTools`, `--disallowedTools`, `--mcp-config`, or `--system-prompt-file` were included.

package/docs/reference/runtime-config/codex.md

@@ -0,0 +1,81 @@
+# Codex Runtime Configuration
+
+Wave launches Codex with `codex exec` and pipes the generated task prompt through stdin.
+
+## Supported Configuration
+
+| Behavior | `wave.config.json` / profile key | Wave `### Executor` key | Launch effect |
+| --- | --- | --- | --- |
+| Command | `executors.codex.command`, `executors.profiles.<name>.codex.command` | `codex.command` | Selects the executable |
+| Sandbox | `executors.codex.sandbox`, `executors.profiles.<name>.codex.sandbox` | `codex.sandbox` | Sets `--sandbox`; if absent on a selected Codex agent, launcher `--codex-sandbox` can supply the runtime default |
+| CLI profile | `executors.codex.profileName`, `executors.profiles.<name>.codex.profileName` | `codex.profile_name` | Adds `--profile <name>` |
+| Inline config overrides | `executors.codex.config`, `executors.profiles.<name>.codex.config` | `codex.config` | Adds repeated `-c key=value` |
+| Search | `executors.codex.search`, `executors.profiles.<name>.codex.search` | `codex.search` | Adds `--search` |
+| Images | `executors.codex.images`, `executors.profiles.<name>.codex.images` | `codex.images` | Adds repeated `--image <path>` |
+| Extra directories | `executors.codex.addDirs`, `executors.profiles.<name>.codex.addDirs` | `codex.add_dirs` | Adds repeated `--add-dir <path>` |
+| JSON mode | `executors.codex.json`, `executors.profiles.<name>.codex.json` | `codex.json` | Adds `--json` |
+| Ephemeral session | `executors.codex.ephemeral`, `executors.profiles.<name>.codex.ephemeral` | `codex.ephemeral` | Adds `--ephemeral` |
+| Model | `executors.profiles.<name>.model` | `model` | Adds `--model <name>` |
+
+## Notes
+
+- There is no `executors.codex.model` key today. Use profile `model` or per-agent `model`.
+- `codex.images`, `codex.add_dirs`, and `codex.config` accept either a string array in `wave.config.json` or a comma-separated list in a wave file.
+- Relative paths are passed to Codex relative to the repository root because Wave launches the executor from the repo workspace.
+
+## Example: `wave.config.json`
+
+```json
+{
+  "executors": {
+    "default": "codex",
+    "profiles": {
+      "implement-fast": {
+        "id": "codex",
+        "model": "gpt-5-codex",
+        "fallbacks": ["claude", "opencode"],
+        "budget": {
+          "turns": 12,
+          "minutes": 45
+        },
+        "codex": {
+          "profileName": "review",
+          "config": ["model_reasoning_effort=medium"],
+          "search": true
+        }
+      }
+    },
+    "codex": {
+      "command": "codex",
+      "sandbox": "danger-full-access",
+      "json": false,
+      "ephemeral": false
+    }
+  }
+}
+```
+
+## Example: Wave `### Executor`
+
+````md
+### Executor
+
+- id: codex
+- model: gpt-5-codex
+- codex.profile_name: review
+- codex.config: model_reasoning_effort=high,model_verbosity=low
+- codex.search: true
+- codex.images: docs/mock-ui.png
+- codex.add_dirs: ../shared,../infra
+- codex.json: true
+- codex.ephemeral: true
+````
+
+## Dry-Run Output
+
+For a dry run, inspect:
+
+- `launch-preview.json` for the final `codex exec` command
+- any referenced prompt file under `.tmp/<lane>-wave-launcher/dry-run/prompts/`
+
+The preview records the exact `--profile`, repeated `-c`, `--image`, and `--add-dir` flags that Wave would use in a live launch.

package/docs/reference/runtime-config/opencode.md

@@ -0,0 +1,93 @@
+# OpenCode Runtime Configuration
+
+Wave launches OpenCode with `opencode run` and points `OPENCODE_CONFIG` at a generated overlay.
+
+## Supported Configuration
+
+| Behavior | `wave.config.json` / profile key | Wave `### Executor` key | Launch effect |
+| --- | --- | --- | --- |
+| Command | `executors.opencode.command`, `executors.profiles.<name>.opencode.command` | `opencode.command` | Selects the executable |
+| Default model | `executors.opencode.model`, `executors.profiles.<name>.model` | `model` | Adds `--model <name>` |
+| Agent name | `executors.opencode.agent`, `executors.profiles.<name>.opencode.agent` | `opencode.agent` | Selects the injected agent name used with `--agent <name>` |
+| Single attachment | `executors.opencode.attach`, `executors.profiles.<name>.opencode.attach` | `opencode.attach` | Adds `--attach <path>` |
+| Multiple files | `executors.opencode.files`, `executors.profiles.<name>.opencode.files` | `opencode.files` | Adds repeated `--file <path>` |
+| Output format | `executors.opencode.format`, `executors.profiles.<name>.opencode.format` | `opencode.format` | Adds `--format default|json` |
+| Step limit | `executors.opencode.steps`, `executors.profiles.<name>.opencode.steps` | `opencode.steps` | Stored in the generated agent config |
+| Instructions | `executors.opencode.instructions`, `executors.profiles.<name>.opencode.instructions` | `opencode.instructions` | Merged into top-level `instructions` in the generated overlay |
+| Permission JSON | `executors.opencode.permission`, `executors.profiles.<name>.opencode.permission` | `opencode.permission` | Stored in the generated agent config |
+| Config overlay JSON | `executors.opencode.configJson`, `executors.profiles.<name>.opencode.configJson` | `opencode.config_json` | Deep-merged into the generated `opencode.json` |
+
+## Overlay Behavior
+
+Wave always writes:
+
+- `opencode-agent-prompt.txt`
+- `opencode.json`
+
+Merge order for `opencode.json`:
+
+1. inline `configJson` from config, profile, and agent resolution
+2. generated `$schema` if the merged config does not already define one
+3. merged top-level `instructions`
+4. generated or merged `agent.<resolved-name>` entry that points to `opencode-agent-prompt.txt`
+
+Wave then exports `OPENCODE_CONFIG=<generated-path>` for the run.
+
+## Example: `wave.config.json`
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "ops-triage": {
+        "id": "opencode",
+        "model": "anthropic/claude-sonnet-4-20250514",
+        "budget": {
+          "turns": 8,
+          "minutes": 20
+        },
+        "opencode": {
+          "instructions": ["Keep findings concise."],
+          "permission": {
+            "task": "ask"
+          },
+          "configJson": {
+            "plugins": ["./plugins/runtime.mjs"]
+          }
+        }
+      }
+    },
+    "opencode": {
+      "command": "opencode",
+      "format": "default"
+    }
+  }
+}
+```
+
+## Example: Wave `### Executor`
+
+````md
+### Executor
+
+- id: opencode
+- model: anthropic/claude-sonnet-4-20250514
+- opencode.agent: docs-runner
+- opencode.attach: docs/plans/current-state.md
+- opencode.files: README.md,docs/plans/current-state.md
+- opencode.format: json
+- opencode.steps: 6
+- opencode.instructions: Keep shared-plan edits concise.
+- opencode.permission: {"task":"ask"}
+- opencode.config_json: {"plugins":["./plugins/runtime.mjs"]}
+````
+
+## Dry-Run Output
+
+For a dry run, inspect:
+
+- `opencode-agent-prompt.txt`
+- `opencode.json`
+- `launch-preview.json`
+
+`launch-preview.json` shows the final `opencode run` command and the exported `OPENCODE_CONFIG` path.

package/docs/research/agent-context-sources.md

@@ -0,0 +1,57 @@
+---
+title: "Agent Context Sources"
+summary: "Primary external sources used as inspiration for harness design, long-running agents, blackboard coordination, and repository-context evaluation."
+---
+
+# Agent Context Sources
+
+This repository does not commit converted paper/article caches. Keep any hydrated local copies under `docs/research/agent-context-cache/` or another ignored cache directory.
+
+## Harnesses and Long-Running Agents
+
+- [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/)
+- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned](https://arxiv.org/abs/2603.05344)
+- [VeRO: An Evaluation Harness for Agents to Optimize Agents](https://arxiv.org/abs/2602.22480)
+- [EvoClaw: Evaluating AI Agents on Continuous Software Evolution](https://arxiv.org/abs/2603.13428)
+
+## Blackboard and Shared Workspaces
+
+- [LLM-Based Multi-Agent Blackboard System for Information Discovery in Data Science](https://arxiv.org/abs/2510.01285)
+- [Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture](https://arxiv.org/abs/2507.01701)
+- [DOVA: Deliberation-First Multi-Agent Orchestration for Autonomous Research Automation](https://arxiv.org/abs/2603.13327)
+- [SYMPHONY: Synergistic Multi-agent Planning with Heterogeneous Language Model Assembly](https://arxiv.org/abs/2601.22623)
+- [Silo-Bench: A Scalable Environment for Evaluating Distributed Coordination in Multi-Agent LLM Systems](https://arxiv.org/abs/2603.01045)
+- [An Open Agent Architecture](https://cdn.aaai.org/Symposia/Spring/1994/SS-94-03/SS94-03-001.pdf)
+
+## Repo Context and Evaluation
+
+- [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/html/2602.11988v1)
+- [VeRO: An Evaluation Harness for Agents to Optimize Agents](https://arxiv.org/abs/2602.22480)
+- [EvoClaw: Evaluating AI Agents on Continuous Software Evolution](https://arxiv.org/abs/2603.13428)
+- [Silo-Bench: A Scalable Environment for Evaluating Distributed Coordination in Multi-Agent LLM Systems](https://arxiv.org/abs/2603.01045)
+
+## Adjacent Context and Memory
+
+- [Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers](https://arxiv.org/abs/2603.07670)
+- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+- [Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex/)
+- [Prompt guidance for GPT-5](https://developers.openai.com/api/docs/guides/prompt-guidance/)
+- [Codex Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide/)
+- [Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
+- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
+- [Context Engineering for AI Agents in Open-Source Software](https://arxiv.org/abs/2510.21413)
+- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)
+- [Toolformer: Language Models Can Teach Themselves to Use Tools](https://arxiv.org/abs/2302.04761)
+- [Plan-and-Solve Prompting](https://arxiv.org/abs/2305.04091)
+- [Augmenting Language Models with Long-Term Memory](https://arxiv.org/abs/2306.07174)
+- [MemGPT: Towards LLMs as Operating Systems](https://arxiv.org/abs/2310.08560)
+- [Lost in the Middle: How Language Models Use Long Contexts](https://direct.mit.edu/tacl/article/doi/10.1162/tacl_a_00638/119630/Lost-in-the-Middle-How-Language-Models-Use-Long)
+- [ReSum: Unlocking Long-Horizon Search Intelligence via Context Summarization](https://arxiv.org/abs/2509.13313)
+
+## Notes
+
+- Use these sources as inspiration and comparison points, not as canonical repo policy.
+- Context7 bundles should be narrow and task-scoped.
+- Cached local exports belong in ignored paths only.