template-first agent APIs and high-level authoring surfaces

.gitignore

@@ -22,6 +22,8 @@ web/void-control-ux/tmp_*.mjs
 
 # TypeScript incremental build cache (per-machine, regenerated by tsc -b)
 **/*.tsbuildinfo
+**/__pycache__/
+**/*.pyc
 
 .github-release-notes.md
 

AGENTS.md

@@ -28,10 +28,12 @@ runtime transport concerns should stay separate.
 - `src/runtime/`: runtime adapter implementations (`MockRuntime`, `VoidBoxRuntimeClient`)
 - `src/orchestration/`: planning, persistence, scheduling, reduction, strategies
 - `src/bridge.rs`: HTTP bridge for launch, dry-run, execution inspection, and policy patching
+- `src/templates/`: file-backed template schema, loading, and compilation into `ExecutionSpec`
 - `src/bin/voidctl.rs`: CLI entrypoint and bridge server
 - `tests/`: orchestration, bridge, runtime, and compatibility coverage
 - `web/void-control-ux/`: React/Vite operator dashboard
 - `docs/`: architecture notes, release process, and internal plans/specs
+- `templates/`: checked-in template-first API definitions
 
 ## Module map
 
@@ -62,6 +64,9 @@ runtime transport concerns should stay separate.
   - restart/reload of persisted active work
 - `src/bridge.rs`
   - serde-gated HTTP routes for UI/bridge workflows
+  - execution routes plus template-first bridge routes
+- `src/templates/`
+  - phase-1 control template schema, checked-in loader, and compile logic
 
 ### Web UI
 
@@ -177,9 +182,59 @@ Important:
   - `execution events <execution-id>`
   - `execution result <execution-id>`
   - `execution runtime <execution-id> [candidate-id]`
+  - `template list`
+  - `template get <template-id>`
+  - `template dry-run <template-id> [<inputs-json-path> | --stdin]`
+  - `template execute <template-id> [<inputs-json-path> | --stdin]`
+  - `batch dry-run <spec-path>`
+  - `batch dry-run --stdin`
+  - `batch run <spec-path>`
+  - `batch run --stdin`
+  - `yolo dry-run <spec-path>`
+  - `yolo dry-run --stdin`
+  - `yolo run <spec-path>`
+  - `yolo run --stdin`
+  - `team dry-run <spec-path>`
+  - `team dry-run --stdin`
+  - `team run <spec-path>`
+  - `team run --stdin`
+- interactive `voidctl` console also exposes:
+  - `/template list`
+  - `/template get <template-id>`
+  - `/template dry-run <template-id> <inputs-json-path>`
+  - `/template execute <template-id> <inputs-json-path>`
+  - `/batch dry-run <spec-path>`
+  - `/batch run <spec-path>`
+  - `/yolo dry-run <spec-path>`
+  - `/yolo run <spec-path>`
+  - `/team dry-run <spec-path>`
+  - `/team run <spec-path>`
+- `batch` is the canonical high-level remote background execution surface
+- `yolo` is an accepted alias for `batch`
+- `team` is the phase-1 high-level multi-agent authoring surface
+- current phase-1 `team` limitations:
+  - `depends_on` is not supported yet
+  - `sequential` preserves ordering only; task outputs are not threaded between agents
 - use `voidctl execution ...` for terminal operator workflows; use the bridge
   HTTP API or UI when you need direct API-driven inspection or browser workflows
 - quote URLs that contain `?` when using `curl` from `zsh`
+- template-first bridge endpoints:
+  - `GET /v1/templates`
+  - `GET /v1/templates/{id}`
+  - `POST /v1/templates/{id}/dry-run`
+  - `POST /v1/templates/{id}/execute`
+- batch bridge endpoints:
+  - `POST /v1/batch/dry-run`
+  - `POST /v1/batch/run`
+  - `GET /v1/batch-runs/{id}`
+- accepted aliases:
+  - `POST /v1/yolo/dry-run`
+  - `POST /v1/yolo/run`
+  - `GET /v1/yolo-runs/{id}`
+- team bridge endpoints:
+  - `POST /v1/teams/dry-run`
+  - `POST /v1/teams/run`
+  - `GET /v1/team-runs/{id}`
 
 ## Runtime compatibility commands
 

README.md

@@ -111,6 +111,7 @@ What to look for:
 
 - `spec/`: Runtime and orchestration contracts.
 - `src/`: Rust orchestration client/runtime normalization logic.
+- `templates/`: File-backed template-first API definitions for single-agent and warm-agent execution.
 - `tests/`: Contract and compatibility tests.
 - `web/void-control-ux/`: React operator dashboard (graph + inspector).
 
@@ -211,6 +212,168 @@ This is also the canonical first-release orchestration workflow:
 - inspect the execution graph, inspector, and event stream
 - follow candidate metrics and `leader` / `broadcast` collaboration events
 
+### Template-first bridge API
+
+Phase 1 also exposes file-backed templates through the bridge:
+
+```bash
+curl -sS http://127.0.0.1:43210/v1/templates
+
+curl -sS http://127.0.0.1:43210/v1/templates/single-agent-basic
+
+curl -sS -X POST http://127.0.0.1:43210/v1/templates/single-agent-basic/dry-run \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "inputs": {
+      "goal": "Summarize this repo",
+      "prompt": "Read the repo and summarize risks",
+      "provider": "claude"
+    }
+  }'
+
+curl -sS -X POST http://127.0.0.1:43210/v1/templates/warm-agent-basic/execute \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "inputs": {
+      "goal": "Keep a warm agent ready",
+      "prompt": "Stay alive for follow-up repo work."
+    }
+  }'
+```
+
+These template endpoints compile into normal `ExecutionSpec` objects and then
+reuse the existing dry-run and execution creation flow. Phase 1 ships two
+starter templates:
+
+- `single-agent-basic`
+- `warm-agent-basic`
+
+Terminal access is also available through `voidctl`:
+
+```bash
+voidctl template list
+voidctl template get single-agent-basic
+voidctl template dry-run single-agent-basic template-inputs.json
+voidctl template execute warm-agent-basic template-inputs.json
+```
+
+`template-inputs.json` must be a JSON request body in the same shape the bridge
+accepts, for example:
+
+```json
+{
+  "inputs": {
+    "goal": "Summarize this repo",
+    "prompt": "Read the repo and summarize risks",
+    "provider": "claude"
+  }
+}
+```
+
+Inside the interactive `voidctl` console, the same surface is available as:
+
+```text
+/template list
+/template get single-agent-basic
+/template dry-run single-agent-basic template-inputs.json
+/template execute warm-agent-basic template-inputs.json
+```
+
+### Batch / yolo
+
+`batch` is the canonical high-level surface for remote background work that
+fans out one worker template across multiple prompts. `yolo` is an accepted
+alias for the same API and CLI path.
+
+Bridge routes:
+
+```bash
+curl -sS -X POST http://127.0.0.1:43210/v1/batch/dry-run \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "api_version": "v1",
+    "kind": "batch",
+    "worker": {
+      "template": "examples/runtime-templates/warm_agent_basic.yaml",
+      "provider": "claude"
+    },
+    "mode": {
+      "parallelism": 2
+    },
+    "jobs": [
+      { "prompt": "Fix failing auth tests" },
+      { "prompt": "Improve retry logging" },
+      { "prompt": "Review DB migration safety" }
+    ]
+  }'
+
+curl -sS -X POST http://127.0.0.1:43210/v1/yolo/run \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "api_version": "v1",
+    "kind": "yolo",
+    "worker": {
+      "template": "examples/runtime-templates/warm_agent_basic.yaml"
+    },
+    "jobs": [
+      { "prompt": "Review migration safety" }
+    ]
+  }'
+```
+
+CLI:
+
+```bash
+voidctl batch dry-run examples/batch/background_repo_work.yaml
+voidctl batch run examples/batch/background_repo_work.yaml
+cat examples/batch/background_repo_work.yaml | voidctl yolo run --stdin
+```
+
+Interactive console:
+
+```text
+/batch dry-run examples/batch/background_repo_work.yaml
+/batch run examples/batch/background_repo_work.yaml
+/yolo run examples/batch/background_repo_work.yaml
+```
+
+### Team
+
+`team` is the phase-1 high-level multi-agent authoring surface. Users define
+`agents`, `tasks`, and a `process`, and `void-control` compiles that into the
+existing orchestration engine.
+
+Current phase-1 limitation:
+- `depends_on` is not supported yet
+- `sequential` preserves task ordering, but does not thread task outputs between agents
+
+HTTP:
+
+```bash
+curl -sS -X POST http://127.0.0.1:43210/v1/teams/dry-run \
+  -H 'Content-Type: text/yaml' \
+  --data-binary @examples/team/rust_article_team.yaml
+
+curl -sS -X POST http://127.0.0.1:43210/v1/teams/run \
+  -H 'Content-Type: text/yaml' \
+  --data-binary @examples/team/rust_article_team.yaml
+```
+
+CLI:
+
+```bash
+voidctl team dry-run examples/team/rust_article_team.yaml
+voidctl team run examples/team/rust_article_team.yaml
+cat examples/team/rust_article_team.yaml | voidctl team run --stdin
+```
+
+Interactive console:
+
+```text
+/team dry-run examples/team/rust_article_team.yaml
+/team run examples/team/rust_article_team.yaml
+```
+
 ### 7) Run the supervision example
 
 Use the checked-in supervision example to exercise the flat
@@ -296,6 +459,37 @@ voidctl execution result <execution-id>
 voidctl execution runtime <execution-id>
 ```
 
+Template-backed agent runs use the `voidctl template ...` surface and expect a
+JSON request body on disk or stdin:
+
+```json
+{
+  "inputs": {
+    "goal": "Summarize this repo",
+    "prompt": "Read the repo and summarize risks",
+    "provider": "claude"
+  }
+}
+```
+
+Dry-run and execute a checked-in template:
+
+```bash
+voidctl template list
+voidctl template get single-agent-basic
+voidctl template dry-run single-agent-basic template-inputs.json
+voidctl template execute warm-agent-basic template-inputs.json
+```
+
+The interactive `voidctl` console exposes the same path:
+
+```text
+/template list
+/template get single-agent-basic
+/template dry-run single-agent-basic template-inputs.json
+/template execute warm-agent-basic template-inputs.json
+```
+
 Example execution:
 
 ```text

examples/batch/background_repo_work.yaml

@@ -0,0 +1,22 @@
+api_version: v1
+kind: batch
+
+metadata:
+  name: repo-background-work
+
+worker:
+  template: examples/runtime-templates/warm_agent_basic.yaml
+  provider: claude
+
+mode:
+  parallelism: 3
+  background: true
+  interaction: none
+
+jobs:
+  - name: auth
+    prompt: Fix failing auth tests
+  - name: logging
+    prompt: Improve retry logging
+  - name: migrations
+    prompt: Review DB migration safety

examples/runtime-templates/warm_agent_basic.yaml

@@ -0,0 +1,37 @@
+api_version: v1
+kind: agent
+name: warm_agent_basic
+
+sandbox:
+  mode: auto
+  memory_mb: 2048
+  vcpus: 2
+  network: true
+
+llm:
+  provider: claude
+
+agent:
+  mode: service
+  skills:
+    - "agent:claude-code"
+  messaging:
+    enabled: false
+  output_file: /workspace/output.json
+  prompt: |
+    You are a reusable long-running service agent.
+
+    Do these steps exactly:
+
+    1. Read the task request from the provided prompt and complete it.
+    2. Write JSON to `/workspace/output.json` with exactly this schema:
+       {
+         "status": "success",
+         "summary": "one-line result summary",
+         "metrics": {
+           "success": 1.0
+         },
+         "artifacts": []
+       }
+    3. After writing the output file, remain alive for additional follow-up work.
+    4. Do not delete `/workspace/output.json`.

examples/team/rust_article_team.yaml

@@ -0,0 +1,26 @@
+api_version: v1
+kind: team
+
+metadata:
+  name: rust-article-team
+
+agents:
+  - name: researcher
+    role: Researcher
+    goal: Find information about Rust performance
+
+  - name: writer
+    role: Writer
+    goal: Write a concise article draft
+
+tasks:
+  - name: research
+    description: Gather evidence about Rust performance tradeoffs
+    agent: researcher
+
+  - name: write
+    description: Write the article draft after the research pass completes
+    agent: writer
+
+process:
+  type: sequential