## 1. Project Overview & Quickstart (agent-dispatch/overview)

# overview

Open-source repository agent-dispatch/overview

### Repository Details
- **Repository:** [agent-dispatch/overview](https://github.com/agent-dispatch/overview)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (agent-dispatch/docs)

## File: docs/agent-core-runtime-design.md

# AgentDispatch: Agent Core Runtime Design

**Status:** Draft v0.1  
**Scope:** Core runtime only  
**Audience:** Founders, runtime engineers, SDK/CLI/MCP implementers  
**Last updated:** 2026-05-09

---

## 1. Summary

AgentDispatch is a runtime-agnostic task delegation platform that lets an agent offload long-running work to isolated remote workers through a unified SDK, CLI, and MCP interface.

This document focuses on the **agent core runtime**: the control-plane and execution model that accepts a task, allocates an isolated worker, runs the task, streams progress, persists state, and returns outputs.

The design goal is to make remote delegation feel as simple as a function call while preserving the properties needed for production use:

- isolation
- resumability
- observability
- deterministic lifecycle control
- transport independence
- backend portability

---

## 2. Problem Statement

Today, agent systems can reason well but struggle to safely offload work that is:

- long-running
- stateful
- expensive
- dependent on tools or credentials
- likely to outlive a single interactive session
- risky to run on the caller’s local machine

Typical failure modes:

- local runtime state is polluted or non-reproducible
- agent work dies when the initiating process exits
- tool execution and agent orchestration are tightly coupled
- background jobs have weak lifecycle tracking
- there is no clean handoff between SDK, CLI, and MCP clients
- logs and artifacts are fragmented or lost
- worker backends are hardcoded to one environment

AgentDispatch should provide a general runtime layer that lets a caller say, in effect:

> Run this agent task elsewhere, in an isolated environment, and give me a stable handle for observing, controlling, and retrieving the result.

---

## 3. Goals

### Primary goals

1. **Unified submission model** across SDK, CLI, and MCP.
2. **Isolated execution** on remote workers with explicit lifecycle.
3. **Asynchronous task handles** with polling, streaming, cancellation, and resumption.
4. **Runtime agnosticism** across worker backends.
5. **Durable task state** independent of the client process.
6. **First-class outputs**: logs, structured result, artifacts, status timeline, metrics.
7. **Composable agent execution** so one agent can delegate work to another runtime-managed worker.

### Secondary goals

1. Cost and quota controls.
2. Retry and recovery semantics.
3. Human-debuggable operational model.
4. Support for both ephemeral and reusable worker sessions.

---

## 4. Non-goals

For this first design pass, the runtime will **not** fully specify:

- UI/dashboard product details
- billing system implementation
- marketplace or multi-tenant monetization features
- fine-grained secret-management product UX
- full workflow DAG orchestration
- model-specific prompting strategy inside the worker
- every provider-specific backend implementation detail

---

## 5. Related Systems / Prior Art

### Crabbox

Crabbox is strongly adjacent prior art.

What Crabbox provides, based on its docs:

- CLI-driven remote execution
- broker/control plane
- ephemeral or warm remote boxes
- lease lifecycle
- worker provisioning across providers
- sync, SSH execution, logs, telemetry, cleanup

Crabbox is closest to an **ephemeral remote workspace broker**.

### What AgentDispatch should borrow from Crabbox

- explicit lease/session model
- separation of control plane from worker
- isolated remote execution as a default
- durable run state outside the runner
- usage, expiry, cleanup, and cost guardrails
- artifacts/logs/telemetry retained in the platform

### How AgentDispatch differs

AgentDispatch should be broader than a remote testbox system. It should treat the worker as a **general task execution runtime** rather than only a repo-synced shell box.

AgentDispatch must additionally support:

- agent-native task contracts, not just shell commands
- SDK/CLI/MCP as equal front doors
- long-running async task handles
- transport-agnostic clients
- richer execution modes: agent task, shell task, container task, future workflow task
- nested delegation patterns where agents dispatch tasks to runtime-managed workers

### Design takeaway

Crabbox is a useful reference for the **runtime/control-plane substrate**, but AgentDispatch should define a more general task abstraction above that substrate.

### Amazon Bedrock AgentCore Runtime

Amazon Bedrock AgentCore Runtime is the preferred first concrete adapter for AgentDispatch.

What AgentCore Runtime provides:

- serverless hosting for agents and tools
- containerized agent runtime deployment
- runtime versions and stable endpoints
- isolated per-session microVM execution
- session stickiness through runtime session IDs
- synchronous, streaming, and asynchronous agent invocation patterns
- command execution inside an active runtime session
- IAM SigV4 and OAuth-oriented authentication paths
- persistent filesystem state across stop/resume cycles
- built-in scaling, infrastructure management, and runtime isolation

AgentCore Runtime should be treated as a **managed agent execution backend**, not as the AgentDispatch product itself.

AgentDispatch should still own:

- cross-surface task API across SDK, CLI, and MCP
- durable dispatch handles
- normalized task state machine
- task lineage and ownership
- result and artifact catalog
- backend-neutral scheduling policy
- user-visible lifecycle semantics

The AgentCore adapter maps those AgentDispatch primitives onto AgentCore runtime ARNs, endpoints, qualifiers, runtime session IDs, invocation streams, command streams, and session stop operations.

---

## 6. Design Principles

1. **Control plane / data plane separation**  
   Control logic, state, auth, quotas, and coordination live centrally. Workers stay simple.

2. **Durable handles over live coupling**  
   A task should continue even if the initiating client disconnects.

3. **Transport-neutral API**  
   The same runtime concepts should map cleanly to SDK calls, CLI commands, and MCP tools.

4. **Execution-mode pluggability**  
   The runtime should not assume every task is a shell command or every worker is an SSH VM.

5. **Observable by default**  
   Logs, events, timestamps, artifacts, and resource signals are first-class.

6. **Idempotent control operations**  
   Submit, attach, cancel, retry, and fetch-result operations should be safe to repeat.

7. **Ephemeral by default, reusable when explicit**  
   Most tasks should run in short-lived isolated workers, but explicit reusable sessions should exist.

---

## 7. Core Concepts

### 7.1 Task

A **Task** is the unit submitted by a client.

It includes:

- task ID
- type
- input payload
- execution requirements
- identity/ownership
- lifecycle status
- outputs and metadata

Examples of task types:

- `agent.run`
- `command.run`
- `container.run`
- `workflow.step` (future)

### 7.2 Session / Lease

A **Session** is a bound execution environment allocated to one or more tasks.

Two modes:

- **ephemeral**: created for one task and destroyed after completion
- **reusable**: explicitly kept warm and reused across tasks

This concept is similar to Crabbox leases, but generalized beyond SSH boxes.

### 7.3 Worker

A **Worker** is the actual compute environment that executes the task.

Possible worker forms:

- AgentCore Runtime endpoint
- VM over SSH
- container runner
- serverless sandbox
- hosted code-execution sandbox
- future specialized agent worker

### 7.4 Runtime Backend

A **Runtime Backend** targets, provisions, or manages workers.

Examples:

- AWS AgentCore Runtime adapter
- local debug backend
- Docker backend
- VM backend
- sandbox provider backend
- Kubernetes backend

### 7.5 Dispatch Handle

A **Dispatch Handle** is the stable identifier returned to the caller.

It supports:

- get status
- stream events
- fetch logs
- fetch artifacts
- cancel
- retry
- await result

### 7.6 Artifact

An **Artifact** is any persisted output beyond inline logs.

Examples:

- file bundles
- screenshots
- structured JSON results
- traces
- test reports

---

## 8. High-Level Architecture

```text
Client Surface
  - SDK
  - CLI
  - MCP
       |
       v
Dispatch API Layer
  - auth
  - validation
  - idempotency
  - request normalization
       |
       v
Runtime Control Plane
  - task state machine
  - scheduler
  - session/lease manager
  - backend adapter manager
  - event/log/artifact registry
  - quota/cost policy
       |
       v
Execution Gateway
  - start task
  - attach to worker
  - stream events
  - collect outputs
  - heartbeat
       |
       v
Worker Backend Adapters
  - AWS AgentCore Runtime
  - VM/SSH
  - container
  - sandbox
  - local debug
       |
       v
Workers
  - isolated task environments
```

### Architectural split

- **Client Surface** translates user intent into runtime requests.
- **Dispatch API Layer** provides the canonical external API.
- **Runtime Control Plane** owns durable state and orchestration.
- **Execution Gateway** speaks backend-specific execution protocols.
- **Workers** execute user tasks and emit outputs.

---

## 9. Request Model

A normalized task submission request should look conceptually like this:

```json
{
  "task_type": "agent.run",
  "input": {
    "instruction": "Investigate failing CI and propose a patch",
    "context": {
      "repo": "github.com/org/repo",
      "ref": "main"
    }
  },
  "execution": {
    "mode": "ephemeral",
    "backend": "aws-agentcore",
    "backend_ref": {
      "region": "us-west-2",
      "runtime_arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/00000000-0000-0000-0000-000000000000:1",
      "qualifier": "DEFAULT"
    },
    "timeout_seconds": 3600,
    "max_retries": 1,
    "resources": {
      "cpu": 2,
      "memory_mb": 4096
    }
  },
  "artifacts": {
    "capture_logs": true,
    "capture_result": true,
    "capture_files": true
  },
  "metadata": {
    "project": "agentdispatch",
    "submitted_by": "cli"
  }
}
```

SDK, CLI, and MCP should all compile to this internal request shape.

---

## 10. Runtime State Machine

### Task states

```text
queued
  -> scheduling
  -> provisioning
  -> starting
  -> running
  -> completing
  -> succeeded

queued|scheduling|provisioning|starting|running
  -> cancelling
  -> cancelled

provisioning|starting|running|completing
  -> failed

failed
  -> retrying
  -> queued
```

### Session states

```text
requested
  -> provisioning
  -> ready
  -> attached
  -> releasing
  -> released

provisioning|ready|attached
  -> expired
  -> failed
```

### Why separate Task from Session

A task is user intent. A session is execution environment.

This separation allows:

- multiple tasks on one reusable session
- task retry on a fresh session
- backend portability
- better observability and cost accounting

---

## 11. End-to-End Flow

### 11.1 Submit

1. Client submits task through SDK, CLI, or MCP.
2. API layer authenticates and validates.
3. Request is normalized into canonical runtime form.
4. Control plane creates task record in `queued`.
5. Client receives dispatch handle immediately.

### 11.2 Schedule

1. Scheduler evaluates backend selection.
2. Quota/cost/policy checks run.
3. Control plane either:
   - reuses an existing warm session, or
   - provisions a new one.

### 11.3 Provision

1. Backend adapter provisions or allocates worker.
2. Session transitions to `ready`.
3. Execution gateway attaches and prepares runtime context.

For the AWS AgentCore adapter, v1 should start with a pre-existing AgentCore Runtime endpoint ARN and create or reuse an AgentCore runtime session ID. Runtime creation, version rollout, and endpoint management can be added after the invocation path is stable.

### 11.4 Run

1. Task starts on worker.
2. Worker emits lifecycle events and logs.
3. Control plane persists status transitions.
4. Heartbeats track liveness.
5. Client may attach live or disconnect safely.

For AgentCore, `agent.run` maps to `InvokeAgentRuntime`. `command.run` maps to `InvokeAgentRuntimeCommand` against the same runtime session so deterministic commands can run in the same container, filesystem, and environment as the agent.

### 11.5 Complete

1. Worker returns structured result and exit status.
2. Artifacts are uploaded/persisted.
3. Task transitions to terminal state.
4. Session is released unless explicitly reusable.

---

## 12. Execution Modes

The runtime should support multiple execution contracts.

### 12.1 Agent task mode

The worker launches an agent runtime with:

- instruction
- context payload
- tools/policies
- output contract

This is the primary mode for AgentDispatch.

In the AWS AgentCore adapter, the deployed container exposes the AgentCore application contract and AgentDispatch passes the normalized task input as the invocation payload.

### 12.2 Command mode

The worker runs a shell command or script.

Useful for:

- CI-like tasks
- build/test jobs
- debugging
- migration from simpler remote-exec systems

In the AWS AgentCore adapter, command mode uses AgentCore command execution inside an active runtime session and translates streamed command events into AgentDispatch log and completion events. Required tools such as `git`, package managers, or language runtimes must exist in the deployed container image or be installed during session setup.

### 12.3 Container mode

The worker launches a containerized payload with resource constraints.

Useful for stronger packaging and backend consistency.

### 12.4 Reusable interactive mode

The runtime provisions a durable session and allows multiple task attachments.

Useful for:

- long debugging sessions
- incremental agent workflows
- user-inspected warm environments

---

## 13. API Surface

The exact transport may vary, but the logical operations should be:

### Task APIs

- `CreateTask`
- `GetTask`
- `ListTasks`
- `CancelTask`
- `RetryTask`
- `AwaitTask`

### Session APIs

- `CreateSession`
- `GetSession`
- `ListSessions`
- `ReleaseSession`

### Streaming / observability APIs

- `StreamTaskEvents`
- `GetTaskLogs`
- `ListTaskArtifacts`
- `GetTaskResult`

### Backend / admin APIs

- `ListBackends`
- `GetCapacity`
- `GetUsage`
- `GetHealth`

### Mapping examples

- **SDK**: `dispatch.createTask(...)`
- **CLI**: `agentdispatch run ...`
- **MCP**: `dispatch_task`, `get_task_status`, `get_task_result`

---

## 14. MCP, CLI, and SDK Alignment

A major product requirement is that these are not separate systems.

They should all map onto the same runtime primitives.

| Surface | User mental model | Runtime primitive |
| --- | --- | --- |
| SDK | async function / future | task handle |
| CLI | command invocation + attach | task + optional session |
| MCP | remote tool call with durable continuation | task handle + polling/stream |

### Important implication

MCP calls are often synchronous from the caller’s perspective, but the runtime should expose an async backbone underneath. If a task outlives a tool timeout, MCP should still return a durable handle and allow follow-up retrieval.

That is one of the key product differentiators.

---

## 15. Scheduling and Backend Selection

The scheduler chooses where a task runs.

Inputs:

- requested backend or `auto`
- task type
- resource requirements
- tenant policy
- cost caps
- warm session availability
- backend health/capacity
- affinity hints

Selection strategies:

- **direct request**: user chooses backend
- **policy-based**: org policy constrains backend
- **auto-fit**: scheduler picks the preferred healthy backend that satisfies constraints
- **affinity reuse**: prefer existing warm session when safe

For v1, `auto` should prefer `aws-agentcore` when the requested task type and account configuration are compatible. The local debug backend remains the fallback for development and adapter tests.

---

## 16. Durability Model

The control plane, not the worker, is the source of truth.

Persisted centrally:

- task metadata
- task status transitions
- session metadata
- logs offsets / references
- artifact metadata
- result payload summary
- retry history
- ownership / auth scope

Workers should be treated as disposable.

This mirrors one of the best ideas from Crabbox: **durable evidence remains in the platform, not on the box**.

---

## 17. Observability Model

Every task should emit:

- status events
- timestamps
- structured logs
- stdout/stderr when applicable
- heartbeat/liveness signals
- resource telemetry when available
- artifact inventory
- final result summary

Recommended event examples:

- `task.queued`
- `task.scheduled`
- `session.provisioning`
- `session.ready`
- `task.started`
- `task.progress`
- `task.log`
- `task.artifact.created`
- `task.succeeded`
- `task.failed`
- `task.cancelled`

Observability storage may use:

- relational state store for metadata
- object storage for logs/artifacts
- append-only event stream for live subscriptions

For the AWS AgentCore adapter:

- invocation response chunks map to `task.progress` or `task.log`
- command `contentStart`, `contentDelta`, and `contentStop` events map to start, log, and completion events
- AgentCore asynchronous processing should be represented as an AgentDispatch task that remains `running` after the initial invocation returns
- AgentCore health/ping status can inform liveness, but AgentDispatch task state remains the user-visible source of truth

---

## 18. Failure Handling

### Failure classes

1. **submission failure**: invalid request, auth failure, quota rejection
2. **scheduling failure**: no capacity, policy denial, backend unavailable
3. **provisioning failure**: worker creation/boot failure
4. **runtime failure**: task exits non-zero, agent exception, timeout
5. **transport failure**: client disconnect, stream interruption
6. **finalization failure**: artifact upload or cleanup failure

### Recovery policies

- submission failures: no retry unless request changes
- provisioning failures: safe automatic retry on new worker
- runtime failures: retry only if task contract allows it
- disconnects: task keeps running
- cleanup failures: background janitor reclaims leaked sessions

### Design choice

AgentDispatch should distinguish:

- **task failed**
- **worker failed**
- **platform failed**

Those are operationally different and should remain distinct in user-visible status.

---

## 19. Security Model

### Core rules

- provider credentials stay in the control plane, not on clients
- workers receive only scoped execution credentials
- tasks execute in isolated environments
- task ownership scopes access to logs/results/artifacts
- cancellation/control requires authorization on the task handle

### Isolation levels

Potential tiers:

1. process isolation
2. container isolation
3. VM isolation
4. dedicated machine isolation

The runtime should allow backend-specific guarantees, but surface them as capability levels to callers.

For the AWS AgentCore adapter, the control plane should use scoped IAM permissions for invocation, command execution, session listing, and session stop operations. AgentDispatch should not expose AWS credentials to SDK, CLI, or MCP callers.

---

## 20. Cost and Quota Guardrails

The runtime should enforce:

- max concurrent tasks
- max warm sessions
- max runtime per task
- per-task cost cap
- tenant monthly budget cap
- backend allow/deny policy

This is another area where Crabbox’s lease TTL and spend-guardrail approach is good prior art.

---

## 21. Minimal Viable Runtime

A realistic MVP should support:

### Front doors

- CLI
- TypeScript SDK
- MCP tools

### Task types

- `agent.run`
- `command.run`

### Backends

- local debug backend
- AWS AgentCore Runtime adapter as the first remote backend

### Core capabilities

- create task
- get task status
- stream logs/events
- cancel task
- collect result
- artifact upload/download
- automatic cleanup
- reusable session optional but not required in v1

### Recommended MVP position

Build the runtime around **AgentCore-backed ephemeral sessions first**, because that gives AgentDispatch a production-grade isolated agent backend without first building its own VM or container provisioning stack.

The first adapter should assume:

- a deployed AgentCore Runtime endpoint ARN is supplied in configuration
- AgentDispatch generates and stores runtime session IDs
- `agent.run` invokes the endpoint with the normalized payload
- `command.run` uses command execution in the same session
- AgentDispatch persists logs, task state, result summaries, and artifact metadata outside AgentCore
- runtime deployment and endpoint/version management are post-MVP concerns

---

## 22. AWS AgentCore Runtime Adapter

### Adapter responsibility

The AWS AgentCore adapter is responsible for translating AgentDispatch runtime operations into Bedrock AgentCore data-plane calls.

It should implement:

- session ID creation and reuse
- `agent.run` invocation
- `command.run` invocation
- stream-to-event translation
- cancellation through session stop where applicable
- backend capability reporting
- AWS error normalization

It should not own:

- AgentDispatch task identity
- user-facing task status
- cross-backend scheduling policy
- durable artifact catalog
- SDK/CLI/MCP API semantics

### Primitive mapping

| AgentDispatch primitive | AgentCore primitive |
| --- | --- |
| Runtime backend | AgentCore adapter configuration |
| Worker | AgentCore Runtime endpoint/version |
| Session | AgentCore runtime session ID |
| `agent.run` task | `InvokeAgentRuntime` |
| `command.run` task | `InvokeAgentRuntimeCommand` |
| Stream event | invocation or command stream chunk |
| Cancel/release | stop runtime session |
| Backend capability | region, runtime ARN, qualifier, protocol, command support |

### Required configuration

The adapter should be configured with:

- AWS region
- AgentCore Runtime ARN
- endpoint qualifier, defaulting to `DEFAULT`
- invocation protocol
- maximum task duration
- command execution enabled/disabled flag
- IAM role or credential source for control-plane use

### Session semantics

AgentDispatch should generate a runtime session ID for each ephemeral task unless the request explicitly targets a reusable session.

Session IDs must be persisted because they are needed to:

- attach follow-up invocations to the same AgentCore microVM
- run deterministic commands in the same environment as the agent
- stop or clean up the session
- correlate AgentCore-side behavior with AgentDispatch task state

AgentCore can preserve filesystem state across stop/resume cycles, but AgentDispatch should still copy durable results and artifacts into its own artifact store before marking a task complete.

### Streaming semantics

The adapter should normalize AgentCore streams into AgentDispatch events.

For agent invocations:

- streamed model or agent output becomes `task.progress`
- stdout/stderr-like diagnostic output becomes `task.log`
- final payload becomes `result_json`

For command invocations:

- command start becomes `task.progress`
- stdout/stderr deltas become `task.log`
- command stop becomes `task.succeeded` or `task.failed` depending on exit code and timeout status

### Asynchronous task semantics

AgentCore supports agents that return quickly and continue background work while reporting busy status through health/ping behavior.

AgentDispatch should model that as:

1. submit task and receive dispatch handle immediately
2. invoke AgentCore
3. keep the AgentDispatch task `running` while the AgentCore session reports busy or while the adapter can observe continued work
4. collect final result or timeout according to AgentDispatch policy
5. persist final status independently of the client connection

This preserves the AgentDispatch product promise: async task handles are durable even when the initiating client is MCP-bound or disconnects.

### Packaging assumptions

The first AgentCore worker image should include:

- AgentDispatch-compatible agent entrypoint
- supported agent framework dependencies
- command-mode dependencies needed by expected workflows
- artifact export helper
- health/ping behavior compatible with long-running tasks
- logging conventions that the adapter can parse or forward

### Known constraints

- AgentCore is an agent hosting runtime, not a complete AgentDispatch task database.
- AgentCore sessions require stable runtime session IDs for affinity; generated IDs should satisfy the AgentCore minimum length requirement.
- Long-running behavior is bounded by AgentCore runtime limits, including extended execution limits and idle-session termination behavior.
- Command execution depends on tools available inside the deployed container image.
- Runtime deployment, version promotion, and endpoint management add operational complexity and should not block the first invocation adapter.

---

## 23. Open Questions

1. Should the first reusable abstraction be **session** or **lease**?  
   `session` is broader and more product-neutral.

2. Should task payloads be fully opaque to the runtime, or partially typed by task type?  
   Recommendation: typed envelope, partially opaque body.

3. Should v1 create AgentCore runtimes, or only invoke pre-existing runtime endpoints?  
   Recommendation: invoke pre-existing endpoints first; add deployment/version management later.

4. Do we need nested delegation visibility in v1?  
   Recommendation: yes, at least parent-task ID and lineage metadata.

5. Should logs stream through the control plane, directly from worker, or hybrid?  
   Recommendation: hybrid, with control-plane durability and optional direct low-latency streams.

6. Should MCP expose long-running task handles as first-class resources?  
   Recommendation: yes.

7. How should AgentDispatch collect file artifacts from AgentCore sessions?  
   Recommendation: require an explicit artifact export contract in the worker image for v1.

---

## 24. Proposed V1 Data Model

### Task

```text
Task {
  id
  owner
  org
  parent_task_id?
  task_type
  input_json
  execution_json
  backend_selected
  backend_ref_json?
  session_id?
  status
  created_at
  started_at?
  ended_at?
  error_code?
  error_message?
  result_json?
}
```

### Session

```text
Session {
  id
  owner
  backend
  mode
  status
  worker_ref
  external_session_ref?
  capabilities_json
  expires_at?
  created_at
  released_at?
}
```

### Artifact

```text
Artifact {
  id
  task_id
  kind
  uri
  size_bytes
  content_type
  created_at
}
```

### Event

```text
Event {
  id
  task_id
  sequence
  type
  payload_json
  created_at
}
```

---

## 25. Recommended Implementation Plan

### Phase 1: canonical runtime contract

- define task/session/event schemas
- implement control-plane state machine
- implement CLI + SDK + MCP request normalization

### Phase 2: AWS AgentCore invocation adapter

- backend adapter interface
- configured AgentCore Runtime ARN support
- runtime session ID creation and persistence
- `InvokeAgentRuntime` task execution path
- stream/log/result persistence

### Phase 3: command mode and lifecycle control

- `InvokeAgentRuntimeCommand` execution path
- command stream event normalization
- cancellation through runtime session stop
- retries within AgentDispatch policy
- artifact retrieval

### Phase 4: reusable sessions and deployment management

- warm sessions
- affinity reuse
- AgentCore runtime deployment/version/endpoint management
- better cost/capacity routing

---

## 26. Recommendation

For AgentDispatch, the **core runtime should be defined first as a durable task-control plane**, not merely as remote command execution.

That means the primary abstraction is:

> a durable dispatched task with a stable handle and managed execution lifecycle

not:

> a shell command on a remote machine

Crabbox is excellent prior art for isolated worker provisioning, lifecycle, and control-plane ownership. AgentDispatch should adopt those strengths while generalizing the abstraction upward from **leased box** to **dispatched agent task**.

---

## 27. One-Sentence Product Framing

AgentDispatch is a control plane for durable agent task execution: submit work from an SDK, CLI, or MCP client, run it on isolated remote workers, and retrieve logs, artifacts, and results through a stable async handle.

---

## File: docs/agentcore-quickstart.md

# AgentCore Quickstart

This quickstart shows the V1 AgentDispatch flow: an MCP-capable lead agent calls AgentDispatch, AgentDispatch spawns or selects an AWS AgentCore runtime session, and the caller receives a durable task handle plus cloud-agent connection metadata. For A2A runtimes, the lead agent then talks to the cloud subagent through A2A using the returned AgentCore details.

## Repositories

Install the published packages for local use:

```bash
npm install -g @agent-dispatch/cli
npm install @agent-dispatch/core @agent-dispatch/mcp-server @agent-dispatch/store-sqlite @agent-dispatch/adapter-aws-agentcore
```

Or clone the repos when developing the packages themselves:

```bash
git clone https://github.com/agent-dispatch/core
git clone https://github.com/agent-dispatch/store-sqlite
git clone https://github.com/agent-dispatch/adapter-aws-agentcore
git clone https://github.com/agent-dispatch/mcp-server
git clone https://github.com/agent-dispatch/cli
```

## AWS Prerequisites

Session mode requires:

- AWS credentials available through the AWS SDK default provider chain.
- An existing AgentCore Runtime ARN.
- IAM permission for `bedrock-agentcore:InvokeAgentRuntime`, `bedrock-agentcore:InvokeAgentRuntimeCommand`, `bedrock-agentcore:GetAgentCard`, and `bedrock-agentcore:StopRuntimeSession`.

Runtime mode additionally requires:

- A prebuilt ECR image for `@agent-dispatch/worker-agentcore` or a compatible worker.
- An AgentCore execution role ARN.
- AgentCore control-plane permissions to create endpoint/runtime resources and delete them after completion.

## Build The Reference Worker Image

Clone and build the AgentDispatch AgentCore worker:

```bash
git clone https://github.com/agent-dispatch/worker-agentcore
cd worker-agentcore

AWS_REGION=us-west-2 \
ECR_REPOSITORY=agentdispatch-worker-agentcore \
IMAGE_TAG=latest \
npm run image:push:ecr
```

The command prints an ECR image URI like:

```text
123456789012.dkr.ecr.us-west-2.amazonaws.com/agentdispatch-worker-agentcore:latest
```

Use that URI as `target.details.ecrImageUri` when testing runtime mode.

## Configure AgentDispatch

Create `agentdispatch.config.json`:

```json
{
  "stateDir": ".agentdispatch",
  "accounts": {
    "dev-aws": {
      "provider": "aws",
      "region": "us-west-2",
      "credentialSource": "aws-sdk-default"
    }
  },
  "backends": {
    "aws-agentcore": {
      "provider": "aws",
      "capability": "agent-runtime",
      "adapter": "aws-agentcore",
      "account": "dev-aws",
      "details": {
        "runtimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/00000000-0000-0000-0000-000000000000:1",
        "qualifier": "DEFAULT",
        "protocol": "a2a"
      }
    }
  },
  "runtimes": {
    "research-agent": {
      "provider": "aws",
      "account": "dev-aws",
      "capability": "agent-runtime",
      "backend": "aws-agentcore",
      "protocol": "a2a",
      "target": {
        "mode": "session",
        "protocol": "a2a"
      },
      "framework": "strands",
      "model": {
        "provider": "bedrock",
        "modelId": "anthropic.claude-3-5-sonnet"
      },
      "runtimeTools": {
        "enabled": ["web-search"]
      }
    }
  },
  "defaults": {
    "runtime": "research-agent"
  }
}
```

The CLI can generate this file:

```bash
agentdispatch init \
  --region us-west-2 \
  --runtime-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/00000000-0000-0000-0000-000000000000:1
```

Validate local config before dispatching real work:

```bash
agentdispatch doctor --config agentdispatch.config.json
agentdispatch-mcp --config agentdispatch.config.json --check
```

## Configure The Cloud Worker Framework

`framework` is not a cloud-provider concept. It is the agent loop that runs inside your AgentCore runtime image. For OpenClaw, Hermes Agent, Strands, LangChain, or an internal runner, configure the worker process with command-backed framework adapters:

```bash
AGENTDISPATCH_AGENT_FRAMEWORK=openclaw
AGENTDISPATCH_FRAMEWORK_COMMAND_OPENCLAW="openclaw run --stdin-json"
```

For multiple frameworks in one runtime image:

```bash
AGENTDISPATCH_FRAMEWORK_COMMANDS='{
  "openclaw": "openclaw run --stdin-json",
  "hermes": {
    "command": "hermes-agent run --stdin-json",
    "timeoutSeconds": 1800,
    "env": {
      "HERMES_MODE": "subagent"
    }
  }
}'
```

In `runtime` target mode, pass those variables through `target.details.environmentVariables` so AgentDispatch sets them when creating the AgentCore runtime resource. In `session` target mode, set them on the prebuilt AgentCore runtime image before registering the runtime ARN.

## Run The MCP Server

```bash
agentdispatch-mcp --config agentdispatch.config.json
```

Configure your MCP client to launch that command over stdio.

## Dispatch A Long-Running Task

For a direct CLI smoke test, define only the task. Routing falls back to `defaults` in `agentdispatch.config.json`:

```bash
agentdispatch run \
  --config agentdispatch.config.json \
  --instruction "Run a long-running investigation and return a concise result." \
  --context-json '{"repo":"github.com/agent-dispatch/core"}' \
  --wait
```

For deterministic shell execution in the same AgentCore session:

```bash
agentdispatch run \
  --config agentdispatch.config.json \
  --command 'echo agentdispatch-smoke' \
  --wait
```

The agent calls:

```json
{
  "tool": "spawn_cloud_agent",
  "arguments": {
    "runtime": "research-agent",
    "instruction": "Run a long-running investigation and return artifacts.",
    "context": {
      "repo": "github.com/agent-dispatch/core"
    }
  }
}
```

`spawn_cloud_agent` is the simple agent-facing tool. It resolves provider, account profile, backend, capability, task type, target, protocol, model, framework, and runtime tool defaults from config. If `defaults.runtime` is set, the agent can omit the `runtime` field. The lower-level `dispatch_task` tool remains available for explicit routing:

```json
{
  "provider": "aws",
  "account_profile": "dev-aws",
  "capability": "agent-runtime",
  "task_type": "agent.run",
  "target": {
    "mode": "session"
  },
  "input": {
    "instruction": "Run a long-running investigation and return artifacts.",
    "context": {
      "repo": "github.com/agent-dispatch/core"
    }
  }
}
```

The AWS adapter forwards `input.instruction` as both the AgentDispatch envelope and a top-level `prompt` alias. That means an existing AgentCore app using a starter-toolkit-style entrypoint such as `payload.get("prompt")` can run without adopting the AgentDispatch worker contract immediately.

Expected immediate response:

```json
{
  "taskId": "task_...",
  "status": "queued",
  "provider": "aws",
  "accountProfile": "dev-aws",
  "capability": "agent-runtime",
  "backend": "aws-agentcore",
  "cloudAgent": {
    "protocol": "a2a",
    "sessionId": "ad-f7221e93f25499a0a1fc0160f63c7621",
    "providerRefs": {
      "region": "us-west-2",
      "runtimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/...",
      "qualifier": "DEFAULT",
      "runtimeSessionId": "ad-f7221e93f25499a0a1fc0160f63c7621",
      "runtimeUrl": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/.../invocations/"
    },
    "invocation": {
      "type": "aws.agentcore.invoke_agent_runtime",
      "runtimeUrl": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/.../invocations/",
      "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/...",
      "qualifier": "DEFAULT",
      "runtimeSessionId": "ad-f7221e93f25499a0a1fc0160f63c7621",
      "sessionHeaderName": "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id",
      "sessionHeaderValue": "ad-f7221e93f25499a0a1fc0160f63c7621",
      "contentType": "application/json",
      "accept": "application/json",
      "payloadFormat": "a2a.jsonrpc.message-send"
    },
    "a2a": {
      "transport": "json-rpc-2.0-http",
      "messageMethod": "message/send",
      "agentCardPath": "/.well-known/agent-card.json",
      "agentCardOperation": "GetAgentCard",
      "endpointUrl": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/.../invocations/",
      "agentCardUrl": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/.../invocations/.well-known/agent-card.json"
    }
  },
  "poll": {
    "statusTool": "get_task_status",
    "logsTool": "get_task_logs",
    "resultTool": "get_task_result"
  }
}
```

The agent can then call:

- `get_task_status` with the task ID
- `get_task_logs` with the task ID and optional cursor
- `get_task_result` after the task reaches a terminal state
- A2A follow-up calls using `cloudAgent.invocation.runtimeSessionId` and `cloudAgent.a2a.messageMethod`
- `cancel_task` to request cancellation and AgentCore session stop

## Verify End To End

Run the deterministic local smoke path first. It does not call AWS; it verifies MCP stdio-compatible transport, config bootstrap, adapter routing, SQLite persistence, logs, and result retrieval:

```bash
cd mcp-server
npm run typecheck
npm test -- --run
npm run build
```

Run the AWS adapter unit and live-test surface:

```bash
cd adapter-aws-agentcore
npm run typecheck
npm test -- --run
npm run build
```

Live AgentCore tests are opt-in because they invoke real AWS resources. Session-mode `agent.run` requires an existing runtime ARN:

```bash
cd adapter-aws-agentcore
export AGENTDISPATCH_LIVE_AGENTCORE=1
export AGENTDISPATCH_LIVE_AGENTCORE_AGENT_RUN=1
export AGENTDISPATCH_AWS_REGION=us-west-2
export AGENTDISPATCH_AGENTCORE_RUNTIME_ARN=arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/00000000-0000-0000-0000-000000000000:1
export AGENTDISPATCH_AGENTCORE_PROTOCOL=a2a
npm test -- --run test/live.test.ts
```

For the repo-level live proof path, use [Live AWS verification](./live-aws-verification.md). It runs the same live-preflight surface through the CLI and can optionally submit a real cloud task with `AGENTDISPATCH_LIVE_DISPATCH=1`.

Runtime-mode live testing also needs a pushed worker image and execution role:

```bash
export AGENTDISPATCH_LIVE_AGENTCORE_RUNTIME_MODE=true
export AGENTDISPATCH_AGENTCORE_RUNTIME_ECR_IMAGE_URI=123456789012.dkr.ecr.us-west-2.amazonaws.com/agentdispatch-worker-agentcore:latest
export AGENTDISPATCH_AGENTCORE_EXECUTION_ROLE_ARN=arn:aws:iam::123456789012:role/AgentDispatchAgentCoreExecutionRole
npm test -- --run test/live.test.ts
```

## Optional Runtime Mode

Use runtime mode when the task requires a fresh deployed worker image:

```bash
IMAGE_URI="123456789012.dkr.ecr.us-west-2.amazonaws.com/agentdispatch-worker-agentcore:latest"
EXECUTION_ROLE_ARN="arn:aws:iam::123456789012:role/AgentDispatchAgentCoreExecutionRole"

agentdispatch run \
  --config agentdispatch.config.json \
  --target-mode runtime \
  --target-details-json "{\"ecrImageUri\":\"$IMAGE_URI\",\"executionRoleArn\":\"$EXECUTION_ROLE_ARN\"}" \
  --instruction "Run in a fresh AgentCore runtime." \
  --wait
```

```json
{
  "provider": "aws",
  "account_profile": "dev-aws",
  "capability": "agent-runtime",
  "task_type": "agent.run",
  "target": {
    "mode": "runtime",
    "details": {
      "ecrImageUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/agentdispatch-worker:latest",
      "executionRoleArn": "arn:aws:iam::123456789012:role/AgentDispatchAgentCoreExecutionRole"
    }
  },
  "input": {
    "instruction": "Run in a fresh AgentCore runtime."
  }
}
```

AgentDispatch creates runtime resources, runs the task, persists task state/logs/results/artifacts outside AgentCore, and deletes runtime resources by default.

## AgentCore Runtime Compatibility Notes

AgentCore Runtime containers use protocol-specific service contracts. HTTP containers listen on port `8080`, expose `POST /invocations` for invocation payloads, and expose `GET /ping` for health. A2A containers listen on port `9000` at the root path and expose Agent Card discovery at `/.well-known/agent-card.json`.

The reference `@agent-dispatch/worker-agentcore` image defaults to A2A for AgentDispatch runtime-mode deployments. It returns `{"status":"Healthy"}` from `/ping`, serves the Agent Card path, and accepts JSON-RPC `message/send` on `/`. For HTTP envelope mode, run it with `AGENTDISPATCH_WORKER_PROTOCOL=http PORT=8080`.

References:

- [Deploy A2A servers in AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html)
- [Invoke an AgentCore Runtime agent](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-invoke-agent.html)
- [Use isolated sessions for agents](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-sessions.html)
- [Understand the AgentCore Runtime service contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html)

AgentCore command execution streams `contentStart`, `contentDelta`, and `contentStop` chunks. AgentDispatch maps these to provider-neutral progress/log events and a command exit result.

Runtime sessions are isolated microVM-backed execution contexts. Reusing a `runtimeSessionId` lets `InvokeAgentRuntime` and `InvokeAgentRuntimeCommand` operate in the same session; AgentDispatch creates one session ID per task for isolation and cancellation.

---

## File: docs/aws-agentcore-adapter.md

# AWS AgentCore Adapter

The AWS adapter implements `provider: aws` and `capability: agent-runtime`.

## Session Mode

Session mode creates a new AgentCore runtime session against a configured runtime ARN. It is the default V1 path for long-running work.

- `agent.run` maps to `InvokeAgentRuntime`.
- `command.run` maps to `InvokeAgentRuntimeCommand`.
- Cancellation maps to `StopRuntimeSession`.
- `protocol: "a2a"` maps `agent.run` to an A2A JSON-RPC `message/send` payload and returns AgentCore connection metadata for native follow-up interaction.

For `agent.run`, AgentDispatch sends its durable task envelope and also includes a top-level `prompt` alias when the caller provides `input.prompt` or `input.instruction`. This supports existing AgentCore starter-toolkit wrappers that expose an entrypoint reading `payload.get("prompt")`, while preserving the richer AgentDispatch payload for workers that understand `taskType`, `input`, and `metadata`.

The compatibility payload shape is:

```json
{
  "taskType": "agent.run",
  "input": {
    "instruction": "Research the latest market signals",
    "context": {}
  },
  "metadata": {},
  "prompt": "Research the latest market signals",
  "context": {}
}
```

For an A2A runtime, the initial `agent.run` payload is:

```json
{
  "jsonrpc": "2.0",
  "id": "task_...",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "kind": "text", "text": "Research the latest market signals" }],
      "messageId": "task_..."
    },
    "metadata": {
      "taskType": "agent.run",
      "input": {},
      "context": {}
    }
  }
}
```

The MCP response includes `cloudAgent.a2a` and `cloudAgent.invocation`, so the lead agent can retrieve the Agent Card with `GetAgentCard` and continue A2A `message/send` calls against the same `runtimeSessionId`.

For runtime mode with `protocol: "a2a"`, the adapter keeps the runtime resources alive by default because the spawned cloud agent is expected to receive follow-up A2A calls. Set `target.details.cleanupAfterTask: true` to restore immediate cleanup behavior.

## Runtime Mode

Runtime mode creates AgentCore runtime resources from a prebuilt ECR image and execution role ARN, creates an endpoint, runs the task, and deletes runtime resources by default.

Runtime creation is heavier than session mode and is intended for tasks requiring a fresh deployed worker artifact.

## Persistence

AgentDispatch persists task state, events, logs, result summaries, artifact metadata, runtime refs, session refs, and cleanup status outside AgentCore.

## AgentCore Runtime Notes

AgentCore Runtime is a good fit for AgentDispatch V1 because it supports isolated per-session microVM execution, long-running agent workloads, large payloads, framework-agnostic containers, and direct invocation through AWS SDK clients. The adapter should continue to treat AgentCore as a backend implementation detail: MCP calls remain provider-neutral and reference named account profiles rather than raw AWS credentials.

---

## File: docs/contributor-issue-bank.md

# Contributor Issue Bank

Use this bank to seed launch-day GitHub issues. Each entry names a target repo, labels, scope, acceptance criteria, and verification commands so a contributor can start without reverse-engineering the architecture.

Link each published issue back to this page and the [Contributor map](./contributor-map.md). Do not use these issues to claim live AWS dispatch has been verified. Live cloud claims require the [Live AWS verification](./live-aws-verification.md) path with `AGENTDISPATCH_LIVE_DISPATCH=1`.

## Adapter Issues

| Title | Target repo | Labels |
| --- | --- | --- |
| Add a local child-process adapter prototype | `adapter-template` or new `adapter-local-process` | `good first issue`, `adapter`, `provider-local` |
| Add a Kubernetes Job adapter design spike | `adapter-template` or new `adapter-kubernetes` | `good first issue`, `adapter`, `kubernetes` |
| Add a GCP Cloud Run Jobs adapter design spike | `adapter-template` or new `adapter-gcp-cloud-run` | `good first issue`, `adapter`, `gcp` |
| Add an Azure Container Apps Jobs adapter design spike | `adapter-template` or new `adapter-azure-container-apps` | `good first issue`, `adapter`, `azure` |

### Add A Local Child-Process Adapter Prototype

Target repo: `adapter-template` or new `adapter-local-process`

Labels: `good first issue`, `adapter`, `provider-local`

Goal: Create a local adapter prototype that runs an AgentDispatch task as a child process while preserving the provider-neutral adapter contract.

Why: This gives contributors a no-cloud adapter path for testing routing, task lifecycle, logs, artifacts, and cancellation without AWS credentials.

Scope:

- Start from `agent-dispatch/adapter-template`.
- Map `provider + capability + task_type + target.mode` to a local command target.
- Keep command, args, cwd, and env allowlist in adapter config or `target.details`.
- Do not pass raw secrets through MCP tool payloads.
- Emit normalized task events for start, log, result, error, and cancellation.

Acceptance criteria:

- A sample config can dispatch a command such as `node worker.js`.
- Logs are captured as AgentDispatch task events.
- Exit code, stdout summary, and stderr summary are represented in the task result or error.
- Cancellation terminates the child process.
- README documents the adapter boundary and local-only security caveats.

Verification:

```bash
npm test
npm run typecheck
npm run build
AGENTDISPATCH_VERIFY_INSTALL=1 npm --prefix agentdispatch-docs run verify:local-e2e
```

### Add A Kubernetes Job Adapter Design Spike

Target repo: `adapter-template` or new `adapter-kubernetes`

Labels: `good first issue`, `adapter`, `kubernetes`

Goal: Design the first Kubernetes Job adapter shape for AgentDispatch.

Why: Kubernetes is the most portable cloud-neutral runtime target. A design spike helps contributors agree on config shape before implementation.

Scope:

- Define how `target.mode = "job"` maps to Kubernetes Job creation.
- Identify required config: namespace, image, service account, env allowlist, resource limits, cleanup policy, and log collection.
- Define provider refs for namespace, job name, pod name, and container name.
- Document how logs, artifacts, cancellation, and cleanup should work.
- Keep Kubernetes client details inside the adapter package.

Acceptance criteria:

- A design doc or README section describes the mapping from AgentDispatch runtime model to Kubernetes resources.
- The proposal avoids new MCP tool names.
- The proposal keeps credentials outside MCP payloads.
- Open questions are listed for artifacts, service exposure, and auth.

Verification:

```bash
npm test
npm run typecheck
npm run build
```

### Add A GCP Cloud Run Jobs Adapter Design Spike

Target repo: `adapter-template` or new `adapter-gcp-cloud-run`

Labels: `good first issue`, `adapter`, `gcp`

Goal: Create a design spike for a GCP Cloud Run Jobs adapter.

Why: Cloud Run Jobs are a natural target for long-running agent tasks on GCP while keeping the AgentDispatch MCP surface stable.

Scope:

- Map provider `gcp`, capability `job-runner`, and `target.mode = "job"` to Cloud Run Jobs.
- Define config for project, region, job name, service account, env allowlist, timeout, and log sink.
- Define provider refs for execution ID and log URL.
- Describe how live preflight would check project, region, IAM, and job reachability.

Acceptance criteria:

- Design doc names the exact Cloud Run APIs and provider refs.
- Live preflight is described as adapter-owned.
- No raw GCP credentials are passed through MCP tool payloads.
- Implementation steps are small enough for follow-up issues.

Verification:

```bash
npm test
npm run typecheck
npm run build
```

### Add An Azure Container Apps Jobs Adapter Design Spike

Target repo: `adapter-template` or new `adapter-azure-container-apps`

Labels: `good first issue`, `adapter`, `azure`

Goal: Create a design spike for an Azure Container Apps Jobs adapter.

Why: Azure Container Apps Jobs can run durable task workloads while AgentDispatch keeps the same `spawn_cloud_agent` contract.

Scope:

- Map provider `azure`, capability `job-runner`, and `target.mode = "job"` to Container Apps Jobs.
- Define config for subscription, resource group, environment, job name, identity, timeout, and logs.
- Define provider refs for execution name and Azure resource IDs.
- Describe live preflight checks for identity, region, resource existence, and permissions.

Acceptance criteria:

- Design doc names the Azure resource model and provider refs.
- Provider-specific SDK usage stays inside the adapter.
- Credential handling stays outside MCP payloads.
- Follow-up implementation tasks are listed.

Verification:

```bash
npm test
npm run typecheck
npm run build
```

## Worker Issues

| Title | Target repo | Labels |
| --- | --- | --- |
| Add a command-backed worker example | `worker-agentcore` | `good first issue`, `worker`, `examples` |
| Add a LangGraph worker integration sketch | `worker-agentcore` | `good first issue`, `worker`, `langgraph` |
| Add an OpenAI Agents worker integration sketch | `worker-agentcore` | `good first issue`, `worker`, `openai-agents` |

### Add A Command-Backed Worker Example

Target repo: `worker-agentcore`

Labels: `good first issue`, `worker`, `examples`

Goal: Add a worker example that runs a configured command and returns normalized logs and result metadata.

Why: This creates a simple bridge for existing scripts and makes AgentDispatch easier to try before adopting a full agent framework.

Scope:

- Add an example worker command runner under the worker package docs or examples.
- Show how the command receives an instruction and optional context.
- Normalize stdout, stderr, exit code, duration, and result summary.
- Document security boundaries and safe defaults.

Acceptance criteria:

- README or example docs show a complete command-backed worker flow.
- The example does not require live AWS to understand.
- Tests cover success and non-zero exit behavior if code is added.

Verification:

```bash
npm test
npm run typecheck
npm run build
```

### Add A LangGraph Worker Integration Sketch

Target repo: `worker-agentcore`

Labels: `good first issue`, `worker`, `langgraph`

Goal: Document or prototype how a LangGraph worker can run behind AgentDispatch without changing the MCP tool contract.

Why: Framework-specific worker examples help agent builders understand where their runtime code belongs.

Scope:

- Describe request input, graph invocation, streaming/log events, result shape, and error mapping.
- Keep framework code in the worker boundary, not the provider adapter.
- Show how A2A, HTTP, or MCP follow-up metadata would be returned if supported.

Acceptance criteria:

- The integration sketch includes a minimal handler shape.
- Logs and final output map to AgentDispatch task events.
- The docs clearly state that provider adapters remain framework-neutral.

Verification:

```bash
npm test
npm run typecheck
npm run build
```

### Add An OpenAI Agents Worker Integration Sketch

Target repo: `worker-agentcore`

Labels: `good first issue`, `worker`, `openai-agents`

Goal: Document or prototype how an OpenAI Agents worker can run as an AgentDispatch cloud-side worker.

Why: This gives OpenAI Agents users a clear path to run long-lived work behind the same `spawn_cloud_agent` primitive.

Scope:

- Define input mapping from AgentDispatch instruction/context to the worker.
- Define log/result/error normalization.
- Keep OpenAI-specific code in the worker boundary.
- Document environment variables without exposing secrets in MCP payloads.

Acceptance criteria:

- The integration sketch includes a minimal worker handler.
- The handler can return a final text result and structured metadata.
- The docs include security and environment configuration notes.

Verification:

```bash
npm test
npm run typecheck
npm run build
```

## Architecture Issues

| Title | Target repo | Labels |
| --- | --- | --- |
| Design provider-neutral artifact browsing | `core`, `mcp-server`, `store-sqlite` | `architecture`, `artifacts` |
| Design provider-neutral live preflight evidence | `core`, `mcp-server`, `cli`, provider adapters | `architecture`, `preflight` |
| Add an examples index for launch demos | `docs`, `website` | `docs`, `examples`, `launch` |

### Design Provider-Neutral Artifact Browsing

Target repos: `core`, `mcp-server`, `store-sqlite`

Labels: `architecture`, `artifacts`

Goal: Design a provider-neutral way to list and retrieve task artifacts.

Why: Long-running cloud subagents need to return more than final text. Repos, reports, traces, screenshots, and data extracts should be discoverable without provider-specific tool names.

Scope:

- Define artifact metadata in core.
- Define store queries for artifact list and retrieval.
- Define MCP tools or result fields for artifact discovery.
- Define provider refs for cloud-owned artifact locations.

Acceptance criteria:

- The design keeps provider-specific storage details behind adapter/provider refs.
- The MCP surface remains provider-neutral.
- Backward compatibility for existing task results is described.
- Follow-up implementation issues are listed by repo.

Verification:

```bash
npm test
npm run typecheck
npm run build
AGENTDISPATCH_VERIFY_INSTALL=1 npm --prefix agentdispatch-docs run verify:local-e2e
```

### Design Provider-Neutral Live Preflight Evidence

Target repos: `core`, `mcp-server`, `cli`, provider adapters

Labels: `architecture`, `preflight`

Goal: Design a common evidence model for live provider preflight checks.

Why: AgentDispatch needs credible launch claims across providers without making every adapter invent a separate proof format.

Scope:

- Define common fields for credential source, account, region, runtime reachability, permissions, and timestamp.
- Keep provider-specific diagnostic fields under adapter-owned details.
- Align CLI, SDK, MCP, and docs wording around preflight versus dispatch.
- Preserve the current live AWS report claim boundary.

Acceptance criteria:

- The model distinguishes local config checks, live preflight, and real dispatch.
- The model can represent AWS AgentCore today and future GCP/Azure/Kubernetes checks.
- Docs explain what public claims are allowed for each proof level.

Verification:

```bash
npm test
npm run typecheck
npm run build
npm --prefix agentdispatch-docs run status:release
```

### Add An Examples Index For Launch Demos

Target repos: `docs`, `website`

Labels: `docs`, `examples`, `launch`

Goal: Create an examples index that helps new users pick a demo path in under one minute.

Why: The repo already has strong architecture docs. A compact examples index improves first-run conversion for lead-agent builders and contributors.

Scope:

- List local no-cloud demo.
- List AWS AgentCore live preflight path.
- List planned adapter and worker demos.
- Link the lead-agent prompt kit and launch announcement kit.

Acceptance criteria:

- The index has one command per demo path.
- It clearly marks which demos require real cloud credentials.
- It links to verification docs and release status.

Verification:

```bash
npm --prefix agentdispatch-docs test
npm --prefix agentdispatch-docs run status:release
```

---

## File: docs/contributor-map.md

# Contributor Map

Use this map when you want to help but do not yet know which AgentDispatch repo owns the work.

## Pick A Lane

| You want to work on | Start here | Good first issue |
| --- | --- | --- |
| MCP tool behavior | [`mcp-server`](https://github.com/agent-dispatch/mcp-server) | Improve `spawn_cloud_agent`, preflight, status, logs, result, or cancellation ergonomics. |
| Provider-neutral runtime model | [`core`](https://github.com/agent-dispatch/core) | Tighten task lifecycle, adapter contracts, target routing, or capability metadata. |
| AWS AgentCore behavior | [`adapter-aws-agentcore`](https://github.com/agent-dispatch/adapter-aws-agentcore) | Improve error normalization, live preflight, session/runtime mode coverage, or protocol metadata. |
| Cloud-side worker behavior | [`worker-agentcore`](https://github.com/agent-dispatch/worker-agentcore) | Add framework adapters, worker health checks, A2A/HTTP protocol coverage, or artifact export helpers. |
| CLI experience | [`cli`](https://github.com/agent-dispatch/cli) | Improve `init`, `doctor`, `run`, polling, A2A follow-up, or config diagnostics. |
| TypeScript app integration | [`sdk-js`](https://github.com/agent-dispatch/sdk-js) | Improve typed client APIs, MCP handoff examples, or transport helpers. |
| Durable local state | [`store-sqlite`](https://github.com/agent-dispatch/store-sqlite) | Improve task/event/log/artifact queries or migration behavior. |
| New provider adapters | [`adapter-template`](https://github.com/agent-dispatch/adapter-template) | Start a local, Kubernetes, GCP Cloud Run, or Azure Container Apps adapter. |
| Docs, launch, website, profile | [`docs`](https://github.com/agent-dispatch/docs), [`website`](https://github.com/agent-dispatch/website), [`.github`](https://github.com/agent-dispatch/.github) | Improve quickstarts, verification evidence, launch copy, profile assets, or examples. |

## Good First Paths

- [New provider adapter](https://github.com/agent-dispatch/.github/issues/new?template=good_first_adapter.yml)
- [Worker framework integration](https://github.com/agent-dispatch/.github/issues/new?template=good_first_worker.yml)
- [Architecture improvement](https://github.com/agent-dispatch/.github/issues/new?template=architecture_request.yml)
- [Contributor issue bank](./contributor-issue-bank.md) for ready-to-open adapter, worker, and architecture issues with acceptance criteria.

## Architecture Rules

- Keep MCP tools provider-neutral.
- Keep cloud-provider SDKs and provider-specific checks inside adapter packages.
- Keep agent framework integrations in worker-side code, not in cloud backend adapters.
- Keep raw cloud credentials out of MCP payloads.
- Preserve the stable routing shape: `provider + capability + task_type + target.mode`.

## Verification Rules

For package-local changes:

```bash
npm test
npm run typecheck
npm run build
```

For cross-repo behavior:

```bash
AGENTDISPATCH_VERIFY_INSTALL=1 npm --prefix agentdispatch-docs run verify:local-e2e
```

For live cloud claims, use [Live AWS verification](./live-aws-verification.md). Do not say live AWS dispatch has been verified unless the live dispatch path succeeds with real credentials and a real AgentCore runtime ARN.

---

## File: docs/examples.md

# Examples

Use this page to choose the right AgentDispatch demo path. The examples are ordered from no-cloud proof to real AWS dispatch evidence.

## Paths

| Path | Needs cloud credentials | Proves |
| --- | --- | --- |
| Local no-cloud demo | No | CLI config, `doctor`, MCP server startup, and the `spawn_cloud_agent` handoff shape. |
| Published npm canary | No | Public package install, imports, CLI binary, and MCP binary. |
| Use-case playbook | No | Copyable task prompts for common background-agent workflows. |
| Lead-agent prompt kit | No | Copy-paste prompts for Claude Code, Codex, OpenClaw, Hermes, and MCP-capable agents. |
| Live AWS preflight | Yes | AWS credentials, region, runtime reachability, and adapter-owned preflight. |
| Live AWS dispatch | Yes | A real cloud task submitted to an AgentCore runtime. |

## Local No-Cloud Demo

Run this from the multi-repo workspace:

```bash
npm --prefix agentdispatch-docs run demo:local
```

This creates a temporary config, runs `agentdispatch doctor`, starts the MCP server with `--check`, and prints a planned `spawn_cloud_agent` payload.

Use this when recording a launch demo without live AWS credentials. Pair it with the [local demo transcript](./local-demo-transcript.md).

To retain demo artifacts for a launch post or PR:

```bash
npm --prefix agentdispatch-docs run demo:record
```

That writes a sanitized transcript, raw command output, and JSON report. Use `AGENTDISPATCH_DEMO_RECORD_DIR=/path/to/output` when you want stable artifact paths.

Claim boundary:

- You can say local CLI config, local doctor, MCP startup, and handoff shape work.
- You cannot say live AWS AgentCore dispatch has been verified.

## Published Npm Canary

Run this from the docs repo:

```bash
npm run smoke:published
```

This installs the public `@agent-dispatch/*` packages into a fresh consumer and verifies public imports plus the published `agentdispatch` and `agentdispatch-mcp` binaries.

Use this before posting install commands publicly.

Claim boundary:

- You can say the currently published npm packages install and expose the expected bins.
- You cannot use this as proof that unpublished local changes are available on npm.

## Lead-Agent Prompt Kit

Use the [lead agent prompt kit](./lead-agent-prompt-kit.md) when testing AgentDispatch through a real MCP-capable lead agent.

For concrete tasks to delegate, use the [use-case playbook](./use-cases.md).

Recommended first prompt:

```text
Use the AgentDispatch MCP tools. First call check_cloud_agent_runtime for runtime research-agent. If it is ready, call spawn_cloud_agent with a short repository-audit instruction, then poll get_task_status, get_task_logs, and get_task_result.
```

Use this when validating the human workflow and demo narration.

Claim boundary:

- You can say the prompts describe the intended MCP workflow.
- You cannot say an external lead-agent client completed a live dispatch unless you actually ran it and retained evidence.

## Live AWS Preflight

Run this only with real AWS credentials and a real AgentCore runtime ARN:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_RUNTIME=research-agent \
AGENTDISPATCH_LIVE_REPORT=./agentdispatch-live-aws-report.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

This performs adapter-owned AWS checks without submitting a task.

Claim boundary:

- You can say live AWS preflight passed if the command succeeds and writes the report.
- You cannot say live AWS dispatch has been verified until the dispatch path succeeds.

## Live AWS Dispatch

Run this only when a real cloud task is allowed:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_RUNTIME=research-agent \
AGENTDISPATCH_LIVE_DISPATCH=1 \
AGENTDISPATCH_LIVE_REPORT=./agentdispatch-live-aws-dispatch-report.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

This submits a real task through the configured AgentCore runtime and writes a JSON evidence report.

Claim boundary:

- You can say live AWS dispatch was verified only when the report claim says `Live AWS dispatch verified against a real AgentCore runtime.`
- Keep the report with release evidence before making public live-cloud claims.

## Release Status

Before a push, release, launch post, or demo recording, run:

```bash
npm --prefix agentdispatch-docs run status:release
```

This summarizes repo cleanliness, commits ahead of `origin/main`, launch gates, and live AWS evidence state.

## Related Docs

- [Verification matrix](./verification-matrix.md)
- [Live AWS verification](./live-aws-verification.md)
- [Use cases](./use-cases.md)
- [Release status](./release-status.md)
- [Release runbook](./release-runbook.md)
- [Contributor issue bank](./contributor-issue-bank.md)

---

## File: docs/future-provider-adapters.md

# Future Provider Adapter Guide

AgentDispatch must add providers without changing MCP tools. New providers implement the `BackendAdapter` interface from `@agent-dispatch/core` and are selected by the routing key:

```text
provider + capability + task_type + target.mode
```

## Adapter Checklist

An adapter must:

- declare `provider` and `capabilities()`
- resolve a provider-neutral `DispatchRequest` into a provider-specific `RuntimeTarget`
- provision any runtime/session/job/service resources needed by the target mode
- start the task and return provider-neutral refs/results/artifacts
- emit provider-neutral `RuntimeEvent` values
- implement cancellation
- implement cleanup
- keep provider-specific fields inside adapter config, `target.details`, or `providerRefs`

The SDK and MCP server must not import provider-specific types.

## Framework Adapters Are Separate

Do not model Strands, LangChain, LangGraph, CrewAI, or OpenAI Agents as cloud backend adapters. Those are worker-side agent framework adapters. A cloud adapter provisions and invokes an execution target; the worker selects the agent framework from payload/config and returns normalized events, results, and artifacts.

This separation keeps the routing key stable:

```text
provider + capability + task_type + target.mode
```

and lets the same AWS AgentCore runtime image support multiple deep-agent frameworks without adding provider-specific MCP tools.

## Capability Examples

AWS:

- `agent-runtime`: AgentCore
- `service-deploy`: ECS, App Runner, Lambda, or EKS
- `job-runner`: Batch, ECS task, or Lambda

GCP:

- `agent-runtime`: Cloud Run service or Vertex AI Agent Engine
- `service-deploy`: Cloud Run
- `job-runner`: Cloud Run Jobs

Azure:

- `agent-runtime`: Container Apps or Azure AI Foundry agent runtime
- `service-deploy`: Container Apps or App Service
- `job-runner`: Container Apps Jobs

Kubernetes:

- `agent-runtime`: Deployment plus Service
- `service-deploy`: Deployment, Service, and Ingress
- `job-runner`: Job or CronJob

Local:

- `agent-runtime`: child process
- `job-runner`: local process or Docker container

## Account Profiles

Credentials are configured outside MCP calls:

```json
{
  "accounts": {
    "prod-gcp": {
      "provider": "gcp",
      "projectId": "my-project",
      "region": "us-central1",
      "credentialSource": "gcloud-default"
    },
    "prod-azure": {
      "provider": "azure",
      "subscriptionId": "...",
      "tenantId": "...",
      "region": "eastus",
      "credentialSource": "azure-default"
    }
  }
}
```

MCP calls reference `account_profile`; they never pass raw credentials.

## Testing Expectations

Every adapter should:

- import `assertBackendAdapterContract` from `@agent-dispatch/core`
- test supported capabilities and target modes
- test provider error normalization
- test cancellation and cleanup
- test provider refs are returned without leaking credentials
- include live tests behind an explicit environment gate

Example live-test gate:

```bash
AGENTDISPATCH_LIVE_GCP=1 npm test
```

No future provider should require a new MCP tool. If a provider cannot fit the existing `dispatch_task` shape, update the core provider model first rather than adding provider-specific tool names.

---

## File: docs/launch-announcement-kit.md

# AgentDispatch Launch Announcement Kit

Use this when announcing AgentDispatch publicly. The strongest message is architectural and specific: one MCP tool for durable cloud subagents, AWS AgentCore first, provider-neutral adapters next.

## One-Line Positioning

```text
AgentDispatch lets any MCP-capable lead agent spawn durable cloud subagents without hardcoding itself to one cloud provider.
```

## Short Description

```text
AgentDispatch is a provider-neutral MCP control plane for long-running agent work. A local lead agent calls `spawn_cloud_agent`, gets back a durable `task_id`, then polls status, logs, results, and cloud-agent handoff metadata for A2A, MCP, AG-UI, or HTTP follow-up.

V1 targets AWS Bedrock AgentCore Runtime. The contract is designed so GCP, Azure, Kubernetes, local runners, and other runtimes can become adapter packages without changing the MCP tool surface.
```

## X / Threads

Single post:

```text
Launching AgentDispatch:

One MCP tool for durable cloud subagents.

spawn_cloud_agent(...)
→ task_id for polling
→ logs/results/artifacts
→ cloud_agent metadata for A2A/MCP/HTTP follow-up

V1: AWS AgentCore
Design: provider-neutral adapters

https://github.com/agent-dispatch
```

Thread:

```text
1/ Local coding agents are good orchestrators. Long-running work needs a different execution plane.

AgentDispatch gives any MCP-capable lead agent one primitive:
spawn_cloud_agent(...)
```

```text
2/ The lead agent gets durable handles back:

- task_id
- status/log/result polling
- cancellation/cleanup
- cloud_agent metadata for A2A, MCP, AG-UI, or HTTP follow-up
```

```text
3/ V1 runs on AWS Bedrock AgentCore Runtime.

The public contract is provider-neutral, so new infrastructure becomes an adapter package, not a new MCP tool every agent has to learn.
```

```text
4/ The goal is simple:

Keep cloud credentials and provider SDK logic outside prompts.
Keep lead-agent tool calls stable.
Let background agent work survive local session restarts.

https://github.com/agent-dispatch
```

## LinkedIn

```text
I am launching AgentDispatch, an open-source provider-neutral MCP control plane for durable cloud-agent work.

Local lead agents such as Claude Code, Codex, OpenClaw, Hermes, or custom orchestrators are strong planners, but long-running work should not be tied to a local context window.

AgentDispatch gives them one stable tool:

spawn_cloud_agent(...)

The response includes a durable task_id for status/log/result polling and cloud_agent metadata for A2A, MCP, AG-UI, or HTTP follow-up when the runtime supports it.

V1 targets AWS Bedrock AgentCore Runtime. The contract is adapter-based from day one so GCP, Azure, Kubernetes, local runners, and workflow runners can plug in later without changing the agent-facing MCP surface.

The local verification gate already tests package installs, typechecks, builds, docs/profile/website validation, package-consumption smoke tests, CLI config generation, CLI doctor, and MCP server checks. Live AWS dispatch remains explicitly opt-in because it depends on real account state and runtime ARNs. Use the verification matrix for exact claim boundaries.

GitHub: https://github.com/agent-dispatch
```

## Hacker News

Title options:

```text
Show HN: AgentDispatch - spawn durable cloud subagents from any MCP-capable agent
```

```text
Show HN: A provider-neutral MCP control plane for cloud subagents
```

Post body:

```text
AgentDispatch lets local MCP-capable agents spawn durable cloud subagents through one stable tool: spawn_cloud_agent.

The lead agent gets a task_id for polling status/logs/results and cloud_agent metadata for A2A/MCP/HTTP follow-up. Provider-specific credentials and SDK behavior stay in adapter packages rather than prompt payloads.

V1 targets AWS Bedrock AgentCore Runtime. The core contract is provider-neutral so GCP, Azure, Kubernetes, local runners, and workflow runners can be added as adapters.

The repo is split into core, MCP server, SDK, CLI, SQLite store, AWS AgentCore adapter, reference worker, adapter template, docs, website, and org profile repos.

Local E2E is covered by a multi-repo verification gate. Live AWS dispatch is separate and opt-in because it depends on real AWS credentials and runtime ARNs.
```

## Reddit / Discord

```text
I am working on AgentDispatch, an OSS MCP control plane for delegating long-running work from local agents to cloud subagents.

The core idea:
- Lead agent calls spawn_cloud_agent
- AgentDispatch routes to a provider adapter
- The lead agent gets task_id + polling tools + cloud-agent handoff metadata
- Provider credentials stay outside tool payloads

AWS AgentCore is the first runtime path, but the adapter contract is intentionally provider-neutral.

I am looking for feedback from:
- MCP users
- cloud runtime builders
- agent framework authors
- people interested in GCP/Azure/Kubernetes/local adapters

Repo: https://github.com/agent-dispatch
```

## Demo Narration

Use this with the [local demo transcript](./local-demo-transcript.md):

```text
First I install the CLI and create an AgentDispatch config.

The config names the runtime and protocol, but the lead agent does not need raw cloud credentials in the prompt.

Then I run doctor, which validates local configuration without touching live AWS state.

Next I run the MCP server check. This proves a lead agent can connect to AgentDispatch.

In a real agent session, the lead agent calls spawn_cloud_agent with the task instruction. It gets back a task_id for polling plus cloud_agent metadata for follow-up.

Live AWS dispatch is opt-in because it depends on account credentials, quotas, runtime ARNs, and possible cost.
```

For a deterministic terminal path before recording, run `npm --prefix agentdispatch-docs run demo:local` from the multi-repo workspace.

To retain the demo transcript and report, run `npm --prefix agentdispatch-docs run demo:record` and keep the generated artifacts with the launch notes.

For a single menu of no-cloud, npm, prompt-kit, live preflight, and live dispatch demo paths, use the [examples index](./examples.md).

Before publishing the post, use the [launch evidence](./launch-evidence.md) workflow to retain the local E2E report, release status JSON, npm evidence, and any live AWS report. At minimum, run `npm --prefix agentdispatch-docs run status:release` so the launch claim matches the local repo state and live AWS evidence boundary.

For copy-paste prompts that work across Claude Code, Codex, OpenClaw, Hermes, and any MCP-capable agent, use the [lead agent prompt kit](./lead-agent-prompt-kit.md).

For concrete background-task examples to include in demos or posts, use the [use cases](./use-cases.md) playbook.

For contributor conversion after the announcement, seed the first issues from the [contributor issue bank](./contributor-issue-bank.md).

## What Not To Claim

Avoid these claims unless live evidence exists:

- Do not say live AWS dispatch has been verified unless `verify:aws-live` or an actual live `spawn_cloud_agent` succeeded.
- Do not call every future provider implemented; say the contract is ready for adapter packages.
- Do not imply raw credentials are handled by the agent; account profiles and provider credential chains are outside MCP payloads.
- Do not claim autonomous production maturity; the credible claim is a tested local control plane, stable MCP surface, and adapter boundary.
- Use [Verification matrix](./verification-matrix.md) to keep local and live-cloud claims separate.
- Use [Live AWS verification](./live-aws-verification.md) and keep its JSON evidence report before making any public live-cloud claim.
- Use the [Release runbook](./release-runbook.md) before announcing a new npm release or provenance claim.

## Links

- Organization: <https://github.com/agent-dispatch>
- Website: <https://agent-dispatch.github.io/website>
- MCP server: <https://github.com/agent-dispatch/mcp-server>
- CLI: <https://github.com/agent-dispatch/cli>
- Docs: <https://github.com/agent-dispatch/docs>
- Launch evidence: <https://github.com/agent-dispatch/docs/blob/main/docs/launch-evidence.md>
- Release runbook: <https://github.com/agent-dispatch/docs/blob/main/docs/release-runbook.md>
- Local demo transcript: <https://github.com/agent-dispatch/docs/blob/main/docs/local-demo-transcript.md>
- Lead agent prompt kit: <https://github.com/agent-dispatch/docs/blob/main/docs/lead-agent-prompt-kit.md>

---

## File: docs/launch-evidence.md

# Launch Evidence

Use this page before a public push, release note, launch post, or demo recording. The goal is to keep every public claim tied to retained evidence instead of memory from a terminal run.

## Local E2E Evidence

For the complete no-cloud launch gate, run:

```bash
AGENTDISPATCH_LAUNCH_EVIDENCE_DIR=./agentdispatch-launch-evidence \
npm --prefix agentdispatch-docs run verify:launch
```

That runs local E2E, npm version drift, publish dry-run, security audit, published package canary, and release-status capture, then writes all JSON reports into the evidence directory.

Run the local gate with an evidence report path:

```bash
AGENTDISPATCH_VERIFY_INSTALL=1 \
AGENTDISPATCH_LOCAL_E2E_REPORT=./agentdispatch-local-e2e-report.json \
npm --prefix agentdispatch-docs run verify:local-e2e
```

That writes a JSON report with:

- `ok: true`
- package names and local versions
- the local verification claim
- the list of covered checks
- the list of things the local gate does not prove

The local evidence report proves the current workspace passed package installs, unit tests, typechecks, builds, local tarball consumption, CLI init, CLI doctor, MCP server check, docs validation, profile validation, website validation/build, and the no-cloud local demo.

It does not prove live AWS AgentCore preflight, live AWS AgentCore dispatch, or that unpublished local versions are already available on npm.

## Demo Recording Evidence

For no-cloud demo narration or launch posts, record the local demo:

```bash
AGENTDISPATCH_DEMO_RECORD_DIR=./agentdispatch-local-demo-recording \
npm --prefix agentdispatch-docs run demo:record
```

That writes:

- `local-demo.transcript.txt` with temporary paths sanitized
- `local-demo.raw.txt` with exact command output
- `local-demo.report.json` with the demo claim boundary and artifact paths

Use the transcript for recording a short terminal demo or for PR review. Do not use it as proof of live AWS dispatch.

## CI Evidence

The docs repo `Local E2E` workflow runs the local gate, npm version drift check, security audit, published package canary, and release-status capture. Successful runs upload an `agentdispatch-launch-evidence` artifact containing:

- `agentdispatch-local-e2e-report.json`
- `agentdispatch-npm-status-report.json`
- `agentdispatch-publish-dry-run-report.json`
- `agentdispatch-security-audit-report.json`
- `agentdispatch-published-smoke-report.json`
- `agentdispatch-release-status.json`
- `agentdispatch-launch-summary.md`
- `agentdispatch-push-plan.md`

Use this artifact when launch notes need a reproducible CI link instead of local terminal output. The Markdown summary is the easiest file to attach to a release note or launch checklist review.

## Release Status Evidence

After the local report exists, run:

```bash
npm --prefix agentdispatch-docs run status:release
```

The output should include:

```text
Retained local E2E report found: yes
Retained published canary report found: yes
Retained npm version report found: yes
Retained publish dry-run report found: yes
Retained security audit report found: yes
Local launch claim ready from repo state: yes
Live AWS dispatch claim ready: no
```

The retained local E2E line and clean repo-state line are enough for a local launch claim. The npm and security lines support install and dependency-health claims. The live AWS line must remain `no` until the live AWS verification path writes a successful dispatch report.

For automation or release notes, capture JSON:

```bash
npm --prefix agentdispatch-docs run status:release -- --json > agentdispatch-release-status.json
```

To render a human-readable summary from a retained evidence directory:

```bash
AGENTDISPATCH_LAUNCH_EVIDENCE_DIR=./agentdispatch-launch-evidence \
npm --prefix agentdispatch-docs run status:launch-summary
```

To render a push and npm publish plan from the current workspace:

```bash
AGENTDISPATCH_PUSH_PLAN_REPORT=./agentdispatch-push-plan.md \
npm --prefix agentdispatch-docs run status:push-plan
```

## npm Evidence

Before telling users to install from npm, run both npm checks:

```bash
AGENTDISPATCH_NPM_STATUS_REPORT=./agentdispatch-npm-status-report.json \
npm --prefix agentdispatch-docs run status:npm

AGENTDISPATCH_PUBLISH_DRY_RUN_REPORT=./agentdispatch-publish-dry-run-report.json \
npm --prefix agentdispatch-docs run status:publish -- --strict

AGENTDISPATCH_SECURITY_REPORT=./agentdispatch-security-audit-report.json \
npm --prefix agentdispatch-docs run status:security -- --strict

AGENTDISPATCH_PUBLISHED_SMOKE_REPORT=./agentdispatch-published-smoke-report.json \
npm --prefix agentdispatch-docs run smoke:published
```

`status:npm` tells you whether local package versions are synced, pending publication, missing on npm, or unexpectedly behind npm. `status:publish` runs `npm publish --dry-run --json` from each public package directory and verifies the tarball metadata is for the intended scoped package instead of a parent workspace package. `smoke:published` installs the currently published packages in a fresh consumer and verifies public imports plus the CLI and MCP binaries.
`status:security` runs `npm audit` across the workspace and reports high or critical findings separately from the default local E2E gate.

If `status:npm` reports `pending-publish`, do not imply the unpublished local changes are already available through npm.

## Live AWS Evidence

For live preflight evidence:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_LIVE_REPORT=./agentdispatch-live-aws-report.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

For live dispatch evidence:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_LIVE_DISPATCH=1 \
AGENTDISPATCH_LIVE_REPORT=./agentdispatch-live-aws-dispatch-report.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

Only the second command can support this claim:

```text
Live AWS dispatch verified against a real AgentCore runtime.
```

## Launch-Safe Claim Table

| Evidence | Safe claim |
| --- | --- |
| `agentdispatch-local-e2e-report.json` has `ok: true` | The current workspace passes the local multi-repo AgentDispatch gate. |
| `status:release` says `Local launch claim ready from repo state: yes` | The checked-out repos are present and clean. |
| `status:npm` has no `local-behind-npm` or `check-failed` entries | Local package versions are not older than npm and registry lookup succeeded. |
| `status:security` has no high, critical, or check-failed entries | The workspace has no high or critical npm audit findings at the time of the registry check. |
| `smoke:published` succeeds | The currently published npm packages install and expose expected imports and bins. |
| `verify:aws-live` succeeds without `AGENTDISPATCH_LIVE_DISPATCH=1` | AWS live preflight passed for the configured account/runtime. |
| `verify:aws-live` succeeds with `AGENTDISPATCH_LIVE_DISPATCH=1` | Live AWS dispatch worked against a real AgentCore runtime. |

## What To Keep

Keep these artifacts with the launch notes:

- `agentdispatch-local-e2e-report.json`
- `agentdispatch-release-status.json`
- `agentdispatch-npm-status-report.json`
- `agentdispatch-security-audit-report.json`
- `agentdispatch-published-smoke-report.json`
- `agentdispatch-launch-summary.md`
- `agentdispatch-push-plan.md`
- `agentdispatch-live-aws-report.json`, if live preflight was run
- `agentdispatch-live-aws-dispatch-report.json`, if live dispatch was run

Do not commit account-specific live AWS reports if they contain private runtime names, account IDs, regions, or operational metadata that should stay private.

---

## File: docs/lead-agent-prompt-kit.md

# Lead Agent Prompt Kit

Use this kit to connect Claude Code, Codex, OpenClaw, Hermes, or any MCP-capable lead agent to AgentDispatch. The goal is copy-paste adoption: configure the MCP server once, then ask the lead agent to preflight, spawn, poll, and retrieve cloud-agent work through the stable AgentDispatch tool surface.

Do not claim live AWS dispatch is verified unless `AGENTDISPATCH_LIVE_DISPATCH=1` or an equivalent live `spawn_cloud_agent` call has succeeded against a real AgentCore runtime.

For task-specific prompts, use the [Use cases](./use-cases.md) playbook.

## MCP Setup

Create an AgentDispatch config first:

```bash
npm install -g @agent-dispatch/cli

agentdispatch init \
  --region us-west-2 \
  --runtime-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/research-agent \
  --protocol a2a

agentdispatch doctor --config ./agentdispatch.config.json
```

Then add the MCP server to the lead agent:

```json
{
  "mcpServers": {
    "agentdispatch": {
      "command": "npx",
      "args": [
        "-y",
        "@agent-dispatch/mcp-server",
        "--config",
        "/absolute/path/agentdispatch.config.json"
      ]
    }
  }
}
```

For local verification without live AWS credentials, run:

```bash
npx -y @agent-dispatch/mcp-server \
  --config /absolute/path/agentdispatch.config.json \
  --check
```

## Safe Local Demo Prompt

Use this when you want the lead agent to demonstrate AgentDispatch without claiming live cloud dispatch:

```text
Use the AgentDispatch MCP server to inspect the available tools and explain how you would spawn background work.

Do not claim live AWS dispatch succeeded unless a real AgentCore runtime call succeeds. For this local demo, show the planned spawn_cloud_agent payload, explain the task_id polling flow, and identify which steps require live AWS credentials.
```

Expected agent behavior:

- Mention `spawn_cloud_agent` as the main dispatch primitive.
- Explain that `get_task_status`, `get_task_logs`, and `get_task_result` are used after dispatch.
- Keep live AWS claims separate from local MCP and CLI checks.

## Runtime Preflight Prompt

Use this before any real cloud dispatch:

```text
Use AgentDispatch to run a runtime readiness check for the configured cloud agent before spawning work.

Call check_cloud_agent_runtime for the default or named runtime. Summarize provider, region, runtime reachability, credential readiness, protocol support, and any blocking issue. Do not call spawn_cloud_agent until the preflight result is ready and the user confirms live dispatch.
```

The lead agent should call `check_cloud_agent_runtime` and report whether the runtime is ready. Preflight is useful evidence, but it is not proof that live dispatch completed.

## Background Repo Audit Prompt

Use this when live dispatch is approved and a real runtime is configured:

```text
Use AgentDispatch to spawn a cloud agent for a background repository audit.

Instruction for the cloud agent:
Audit this repository for production-readiness gaps. Focus on installability, package boundaries, tests, public docs, security defaults, and launch-readiness claims. Return prioritized findings with file paths and concrete fixes.

Use protocol a2a if available. After spawning, keep working locally while the cloud task runs. Poll status, collect logs, retrieve the final result, and summarize the result with any follow-up actions.
```

The expected tool sequence is:

```text
check_cloud_agent_runtime
spawn_cloud_agent
get_task_status
get_task_logs
get_task_result
```

## Poll And Result Prompt

Use this after a task has been spawned:

```text
Use AgentDispatch to continue the existing cloud task.

Task id: <task_id>

Poll get_task_status until the task reaches a terminal state or needs user action. Retrieve recent logs with get_task_logs. If complete, call get_task_result and summarize the output, artifacts, provider refs, and cloud_agent handoff metadata.
```

## A2A Follow-Up Prompt

Use this when the spawned cloud agent returns A2A handoff metadata:

```text
Use the AgentDispatch cloud_agent metadata from the completed or running task to continue with the remote agent through A2A.

Send this follow-up message:
<message>

Preserve the task_id and provider refs in your summary. If A2A metadata is missing, explain which handoff protocol is available instead.
```

## Client Notes

Claude Code:

```text
Install the AgentDispatch MCP server with the npx config above. Ask Claude Code to preflight with check_cloud_agent_runtime, then spawn with spawn_cloud_agent only after live dispatch is approved.
```

Codex:

```text
Use the same MCP server config. Ask Codex to keep local edits moving while AgentDispatch handles a background audit, package smoke, or documentation review task.
```

OpenClaw:

```text
Register AgentDispatch as an MCP server for delegation. Treat spawn_cloud_agent as the handoff boundary and task_id polling as durable state.
```

Hermes:

```text
Use AgentDispatch for long-running cloud work and preserve returned cloud_agent metadata for A2A, MCP, AG-UI, or HTTP follow-up.
```

Any MCP-capable agent:

```text
Prefer spawn_cloud_agent for normal work. Use check_cloud_agent_runtime before live dispatch. Use get_task_status, get_task_logs, and get_task_result after dispatch. Do not put raw cloud credentials into prompts.
```

## Claim Boundary

Local checks prove package wiring, CLI config shape, MCP startup, docs/profile/website validation, and smoke behavior. Live AWS preflight proves the configured account and runtime can be checked. Only `AGENTDISPATCH_LIVE_DISPATCH=1` or an equivalent successful live `spawn_cloud_agent` proves live cloud dispatch end to end.

---

## File: docs/live-aws-verification.md

# Live AWS Verification

Use this page only after the local gate passes. The local gate proves package wiring, CLI startup, MCP server startup, SQLite persistence, docs validation, website validation, and package-consumption smoke tests without touching AWS. Live verification proves the configured AWS AgentCore path against real account state.

## What This Proves

`npm --prefix agentdispatch-docs run verify:aws-live` runs `agentdispatch doctor --aws-live --json` through the local CLI build when available, or the published CLI otherwise.

For a session-mode runtime, the live preflight proves:

- the selected runtime profile exists and routes through the `aws-agentcore` adapter
- AWS credentials resolve through the SDK default provider chain
- the configured region is reachable
- the configured AgentCore runtime ARN is real and reachable
- the runtime reports a status that AgentDispatch can inspect before dispatch

With `AGENTDISPATCH_LIVE_DISPATCH=1`, the script also submits a real `agentdispatch run --wait` task and waits for a terminal AgentDispatch result.

Successful runs write a JSON evidence file. By default it is `agentdispatch-live-aws-report.json` in the current directory. Override it with `AGENTDISPATCH_LIVE_REPORT=/absolute/path/live-aws-report.json`.

## What This Does Not Prove

Preflight alone does not prove the cloud worker can complete an arbitrary task. It does not upload worker images, create IAM roles, change quotas, or guarantee that a runtime image contains your requested framework tools.

Only the `AGENTDISPATCH_LIVE_DISPATCH=1` path, or an equivalent successful `spawn_cloud_agent` call against the same runtime, proves live cloud dispatch end to end.

## Prerequisites

You need:

- AWS credentials available to the AWS SDK default provider chain
- a real AgentCore Runtime ARN, not the sample placeholder
- the matching AWS region in the config or `AWS_REGION`
- IAM permission for `bedrock-agentcore:GetAgentRuntime`
- IAM permission for invocation when running the dispatch step
- a runtime image whose protocol matches the AgentDispatch runtime config, such as `a2a` or `http`

For session mode, the config must point at an existing runtime:

```json
{
  "backends": {
    "aws-agentcore": {
      "provider": "aws",
      "capability": "agent-runtime",
      "adapter": "aws-agentcore",
      "account": "dev-aws",
      "details": {
        "runtimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/11111111-1111-1111-1111-111111111111:1",
        "qualifier": "DEFAULT",
        "protocol": "a2a"
      }
    }
  }
}
```

## Preflight Command

Run this from the parent multi-repo workspace:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_RUNTIME=research-agent \
AGENTDISPATCH_LIVE_REPORT=./agentdispatch-live-aws-report.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

Expected successful ending:

```text
Live AWS preflight passed.
Set AGENTDISPATCH_LIVE_DISPATCH=1 to also submit a real cloud task.
```

The report records the target runtime, region, protocol, doctor checks, whether dispatch was requested, and the claim supported by the run. It does not include AWS secret values.

If the script fails before calling AWS, fix the named local config issue first. If it fails during `doctor --aws-live`, use the failed check name and message from the JSON report to decide whether the problem is credentials, region, permissions, runtime ARN, or runtime readiness.

## Real Dispatch Command

This submits a real cloud task, may incur AWS cost, and writes task state under the configured `stateDir`:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_RUNTIME=research-agent \
AGENTDISPATCH_LIVE_DISPATCH=1 \
AGENTDISPATCH_LIVE_INSTRUCTION="AgentDispatch live smoke: respond with a short success message and no external side effects." \
AGENTDISPATCH_LIVE_REPORT=./agentdispatch-live-aws-dispatch-report.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

Successful output includes the initial task handle, streamed logs if the runtime emits any, and the final AgentDispatch result JSON.

For launch evidence, keep the generated report with the release checklist. The report claim should read `Live AWS dispatch verified against a real AgentCore runtime.` before making a public live-dispatch claim.

## GitHub Actions Evidence

The docs repo includes a manual `Live AWS Verification` workflow. Configure these repository secrets before running it:

- `AGENTDISPATCH_CONFIG_JSON`: the full AgentDispatch config JSON
- `AGENTDISPATCH_AWS_REGION`: AWS region for credential configuration
- `AWS_ROLE_ARN`: optional OIDC role to assume
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`: optional static credentials when OIDC is not used
- `AGENTDISPATCH_LIVE_INSTRUCTION`: optional custom smoke instruction

Run the workflow manually, choose the runtime profile, and set `live_dispatch=true` only when you want to submit a real cloud task. Successful runs upload `agentdispatch-live-aws-report.json` as the workflow artifact.

## Troubleshooting

- `runtime was not found`: set `AGENTDISPATCH_RUNTIME` to a configured runtime profile or update `defaults.runtime`.
- `sample placeholder AgentCore runtime ARN`: replace the generated example ARN with a real runtime ARN.
- `AWS credentials could not be resolved`: configure `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`, SSO, or another SDK-supported credential source.
- `runtime was not reachable`: check region, runtime ARN, `bedrock-agentcore:GetAgentRuntime`, and whether the AgentCore runtime still exists.
- dispatch times out after preflight passes: inspect the AgentCore runtime logs and confirm the worker image implements the configured protocol.
- report file is missing: the script did not reach a successful preflight, or the `AGENTDISPATCH_LIVE_REPORT` path was not writable.

## Launch Claim Rule

Do not claim live AWS dispatch has been verified unless the real dispatch command above, or an equivalent live `spawn_cloud_agent` call, has succeeded against a real runtime. Local E2E and live preflight are valuable but narrower claims.

---

## File: docs/local-demo-transcript.md

# AgentDispatch Local Demo Transcript

This transcript is the launch-demo path that works without live AWS credentials. It proves the CLI, config shape, package wiring, and MCP server startup locally. Live AWS AgentCore dispatch remains a separate opt-in step because it needs real account credentials and a runtime ARN.

## 90-Second Flow

Run the executable local demo from the multi-repo workspace:

```bash
npm --prefix agentdispatch-docs run demo:local
```

For launch notes, recorded narration, or a pull-request artifact, capture a sanitized transcript plus JSON report:

```bash
npm --prefix agentdispatch-docs run demo:record
```

Set `AGENTDISPATCH_DEMO_RECORD_DIR=/path/to/output` when you want deterministic artifact paths. Without it, the recorder writes to a temporary directory and prints the transcript, raw output, and report paths.

Or run the commands manually:

```bash
npm install -g @agent-dispatch/cli

agentdispatch init \
  --region us-west-2 \
  --runtime-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/research-agent \
  --protocol a2a

agentdispatch doctor --config ./agentdispatch.config.json

npx -y @agent-dispatch/mcp-server \
  --config ./agentdispatch.config.json \
  --check
```

Expected local shape:

```text
Wrote ./agentdispatch.config.json
AgentDispatch doctor passed
MCP server check passed
```

Then connect a lead agent with:

```json
{
  "mcpServers": {
    "agentdispatch": {
      "command": "npx",
      "args": [
        "-y",
        "@agent-dispatch/mcp-server",
        "--config",
        "/absolute/path/agentdispatch.config.json"
      ]
    }
  }
}
```

Ask the lead agent:

```text
Use AgentDispatch to spawn a cloud agent for this repository audit.
Keep working locally while it runs, then poll the result.
```

For client-specific copy, use the [lead agent prompt kit](./lead-agent-prompt-kit.md).

The agent-facing call is:

```json
{
  "tool": "spawn_cloud_agent",
  "arguments": {
    "runtime": "research-agent",
    "instruction": "Audit this repository while I keep working locally.",
    "protocol": "a2a",
    "context": {
      "repo": "agent-dispatch",
      "priority": "background"
    }
  }
}
```

## Full Local Verification

From the multi-repo workspace:

```bash
AGENTDISPATCH_VERIFY_INSTALL=1 npm --prefix agentdispatch-docs run verify:local-e2e
```

This gate installs each package cleanly, overlays local package tarballs into downstream packages, runs tests, typechecks, builds, validates docs/profile/website assets, smoke-tests package consumption, creates a config with the built CLI, and checks the built MCP server.

Successful local output ends with:

```text
AgentDispatch local end-to-end verification passed.
Note: live AWS AgentCore dispatch is intentionally not run by this local gate.
```

## Live AWS Add-On

After configuring real AWS credentials and an AgentCore runtime ARN:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
npm --prefix agentdispatch-docs run verify:aws-live
```

To submit a real cloud task after live preflight passes:

```bash
AGENTDISPATCH_CONFIG=/absolute/path/agentdispatch.config.json \
AGENTDISPATCH_LIVE_DISPATCH=1 \
npm --prefix agentdispatch-docs run verify:aws-live
```