buzz/crates/buzz-acp/TASKS.md

Local task runner

buzz-acp run runs one prepared task in one fresh agent process and ACP session, then exits. Scripts and automation can use it without starting a conversational buzz-acp service or sending a chat message.

buzz-acp run --task ./task.json
cat task.json | buzz-acp run --task -

Put command options after run. Use the normal trusted launch settings for identity, relay, adapter, model, effort, permissions, prompts, MCP tools, and memory. buzz-acp run --help lists them. The working directory is the launch working directory, not the task file's parent. The task cannot change it.

Task document, version 1

Supply exactly one UTF-8 JSON object, at most 1 MiB including whitespace:

{
  "version": 1,
  "taskId": "example-001",
  "agentPubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
  "prompt": "Inspect the current workspace. Report your findings using the task's specified destination.",
  "maxDurationMs": 120000
}

The example public key is illustrative; use the public key of the configured agent. Never put a private key in a task document.

Field	Contract
version	Integer 1. Other versions fail before agent launch.
taskId	Nonblank string, 1–256 UTF-8 bytes, no control characters. Correlation only, not a claim or deduplication key.
agentPubkey	Exactly 64 lowercase hexadecimal characters. Must equal the configured agent's public key.
prompt	Nonblank prepared task string. Include relevant context, original evidence, and reporting instructions here.
maxDurationMs	Positive unsigned 64-bit integer. The shorter of this limit and the trusted --max-turn-duration cap wins.

All fields are required. Unknown fields, duplicate fields, wrong types, trailing JSON documents, and malformed JSON are rejected. File/stdin input has a ten-second read limit. Close stdin after the document. The input limit is separate from the execution deadline.

Launch configuration is the authority for credentials, executable, tools, permissions, and relay. A document is executable task input, not a sandboxed message: only feed tasks that are trusted to use that agent's capabilities. The identity check prevents accidental execution by another agent; it does not verify the document's author. File/stdin input does not need a signature.

Session behavior

• Load normal base, persona, and team instructions. Add the task-session context instead of a conversational session description. Modern adapters receive standing instructions through session setup; legacy adapters receive them with the first prompt. --no-base-prompt and custom base files still work.
• Load enabled core memory for the resolved owner and identity before session creation. --no-memory skips this. No owner means no memory namespace. The normal three-second fetch bound applies. Confirmed absence supplies the normal onboarding hint; a failed read supplies no hint, not a false empty-memory claim.
• Apply model, supported effort and permission settings through the existing session setup. Unsupported settings retain the existing adapter fallback behavior. Pass configured identity and relay to the child and MCP tools; keep the inherited authorization and other launch environment. The shared runtime prepares Git identity, scoped credentials, and signing helpers for both task and conversational sessions. Temporary key material lives until adapter cleanup is complete.
• Submit one prepared task, allowing multiple model/tool exchanges. There is no initial-message turn, heartbeat turn, conversation history, automatic channel context, or second task. Context must be supplied or fetched with tools.
• Do not start ordinary relay subscriptions, a standing pool, presence, typing, a setup listener, observer publication, or an isolated-turn socket. Inherited service-only options cannot enable these features. Shared option parsing still validates launch settings.
• Do not discover, borrow, stop, or reconfigure an existing host. Memory, files, credentials, and external side effects may be shared with concurrent sessions. Session isolation is not a security sandbox or a concurrency lock.
• Do not automatically publish final text. Use task reporting instructions and tools. Do not retry the task after failure, timeout, or uncertain execution.

Launch configuration preparation (including prompt-file reads) has a separate ten-second bound. A blocked configuration read reports configuration_timeout with exit 2; SIGINT/SIGTERM during that read reports cancelled with exit 130/143 and a null taskId. No adapter is started during this phase.

The execution deadline covers adapter startup, memory loading, session setup, and the task turn. SIGINT/SIGTERM cancel the invocation. If a prompt is active, allow up to five seconds for cooperative cancellation, then kill and reap the child, with a further five-second reap bound. Startup and setup cancellation do not wait for a session to become ready. On Unix, cleanup kills the process group, including ordinary descendants. Processes that deliberately escape that group are outside this guarantee. On non-Unix platforms cleanup uses the existing ACP direct-child cleanup; descendant containment is not promised.

Terminal output

For each attempted invocation, stdout contains one JSON line (except help/version output). Diagnostics and child stderr stay on stderr. No prompt, private key, agent final text, or raw adapter error is included in the terminal record.

{"version":1,"taskId":"example-001","status":"completed","stopReason":"end_turn"}

taskId is null until the document is validated. status is one of completed, failed, invalid, timed_out, or cancelled. stopReason is present only for normal completion: end_turn, max_tokens, max_turn_requests, or refusal. Failures include a stable, sanitized error code when available, such as agent_identity_mismatch, invalid_task_json, or agent_spawn_failed.

Exit	Meaning
0	Turn returned normally. Inspect stopReason; this is not proof of task success.
1	Startup/execution failure, adapter cancellation, or terminal-output failure.
2	Invalid arguments, launch configuration, or task input/read.
124	Execution deadline exceeded.
130	SIGINT; bounded cleanup ran.
143	SIGTERM; bounded cleanup ran.

A killed host or broken stdout can leave no terminal record. A record is not a persistent result ledger. Launching the same task twice can execute it twice.

Future work

URL input and task-server retrieval are not implemented. URL-shaped sources are rejected, not fetched. A future design can GET a supplied URL and validate the same task document, with explicit authentication, size/time bounds, and redirect rules. This project adds no HTTP task endpoint or job queue.

Shared runtime ownership

runtime::AgentRuntime prepares shared capabilities and owns their lifetime. Both entry points obtain adapter configuration and prompt context from it; add new shared capabilities there rather than in either entry point. Session creation, tool configuration, model/effort/permissions, and legacy prompt framing use the existing pool code. Mode-specific code owns task input and terminal output or conversational intake and scheduling, not agent equipment.

Build and verification

. ./bin/activate-hermit
cargo build --release -p buzz-acp
cargo test -p buzz-acp

tests/run_task.rs invokes the actual binary with a deterministic ACP peer. It checks stdin/file parity, fresh process/session setup, legacy and modern standing instructions, tools, identity, model/effort/permissions, memory reads and opt-out, invalid input, clean JSON, deadlines, signals, and Unix descendant cleanup. These checks do not require a model provider or production relay.