# AI Delivery Coordination

AI Delivery Coordination is a TypeScript control plane for multi-party delivery. It stores delivery membership, pipeline DAG state, claim leases, artifact pointers, approvals, gates, notices, audit events, costs, alerts, security incidents, idempotency records and transactional outbox events.

The runtime is Node.js 22 with a pnpm workspace:

```text
apps/api        Hono REST, session auth, SSE and dashboard hosting
apps/dashboard  React operator dashboard
apps/mcp        real @modelcontextprotocol/sdk stdio participant server
apps/cli        REST-first CLI and local binding init
apps/executor   relay, scheduler/reaper and Redis Streams worker entrypoints
packages/contracts  shared Zod request, status and error schemas
packages/domain         pure delivery state, DAG and domain errors
packages/application    command/query services and transport adapters
packages/infrastructure database, auth, outbox, Redis and worker adapters
migrations      reviewable PostgreSQL migration source
```

## Security and storage

Every request is scoped to a Team. API Keys use `coord_sk_<key_id>.<secret>` and are stored as Argon2id hashes. Dashboard login exchanges an API Key for an HttpOnly SameSite session; session writes also require the CSRF header. `COORDINATION_JWT_SECRET` or `COORDINATION_JWT_SECRET_FILE` is mandatory and must contain at least 32 bytes.

API Key creation and rotation disclose the secret only in the first response. An idempotent replay returns a redacted result; key material is never stored in audit, outbox, or idempotency records.

Production requires `COORDINATION_MODE=production` and a PostgreSQL URL. SQLite is only for one-process standalone/dev/test. Run migrations explicitly; API startup only checks the recorded revision and never performs implicit DDL. Redis is a wake-up transport, while PostgreSQL remains the job and audit source of truth.

## Development

```bash
corepack enable
pnpm install
pnpm --filter @ai-delivery-coordination/application db:migrate
pnpm typecheck
pnpm test
pnpm build
```

Standalone example:

```bash
COORDINATION_MODE=standalone \
COORDINATION_DATABASE_URL=sqlite+better-sqlite3:///data/coordination.db \
COORDINATION_JWT_SECRET="$(openssl rand -hex 32)" \
pnpm --filter @ai-delivery-coordination/application db:migrate
```

Start services with `pnpm start:api`, or use `docker/docker-compose.yml` for Postgres, Redis, migration, API, relay, scheduler and worker. The container runs as a non-root user and receives its JWT secret through a Docker secret.

## Participant contract

The participant skill lives at `.agents/skills/coordination-participant`. MCP credentials are read only from `COORDINATION_API_KEY` and `COORDINATION_TEAM_ID`; they are never tool arguments or log fields. The participant loop is:

```text
get_delivery_status -> list_claimable_nodes -> claim_node
-> local work -> register_artifact_ref -> report_node_status(done)
```

All public writes are under `/api/v1/teams/{team_id}/...`, require `Idempotency-Key`, and aggregate updates require `If-Match` (MCP/CLI use `expected_version`). Errors share `code`, `message`, `request_id`, and `details`.

The control plane intentionally does not execute LLMs or agents and does not include memory stores, Git/PR automation, Langfuse, artifact proxying, or legacy Python runtime paths.