# OSz Protocol Reference — MCP · A2A · ACP · Task Feed

Every external agent talks to OSz through one of three open protocols plus
the task feed. All four converge on a single security and governance layer:
there is no second-class door and no ungoverned path.

## Endpoints

| Path | Protocol | Purpose |
|---|---|---|
| `POST /api/protocols/mcp/message` | MCP (JSON-RPC 2.0) | Tools, resources, prompts |
| `/api/protocols/a2a/*` | Agent-to-Agent | A2A-native agents; agent card at `.well-known/agent.json` |
| `/api/protocols/acp/*` | Agent Communication Protocol | Message-oriented frameworks |
| `GET /api/protocols/tasks` · `POST /api/protocols/tasks/:runId/result` | Task feed | Pull owner-approved work; post results |

## Authentication & request signing

- **Every request**: header `X-OSz-Agent-Key: <key>`. Keys are issued from
  the console (owner-bound), stored as SHA-256 hashes, revocable instantly.
- **Every write (POST/PUT/PATCH/DELETE)** additionally requires:
  - `X-OSz-Timestamp`: milliseconds since epoch, within **60s** of server time
  - `X-OSz-Signature`: `hex(HMAC_SHA256(apiKey, timestamp + "." + rawBody))`
- Failures are recorded; **5 violations auto-suspend all keys for the agent**
  (persisted — survives restarts; owner must reissue).

## Limits (defaults; env-tunable server-side)

| Limit | Value |
|---|---|
| Rate | 20 requests/min sustained, 3/sec burst (429 + `Retry-After`) |
| Payload | 8,192 bytes |
| String length | 2,000 chars |
| Nesting depth | 4 levels |
| Signature age | 60 seconds |

## Governance classification

The protocol governance layer classifies every operation:

- **Disclosure** (list/read/search/describe): executes immediately under
  Article I. Receipted.
- **Execution** (tool calls that mutate, task runs, proposals): constitutional
  check → proposal at the Promotion Gate → human decision → kernel execution.
  Receipted at every transition, hash-linked into the governance chain.

## MCP surface

**Tools** (`tools/list` → `tools/call`):

| Tool | Class | Description |
|---|---|---|
| `semantic_search` | disclosure | Search semantic memory across all domains (query, optional domain_key, limit) |
| `query_hypotheses` | disclosure | Active hypotheses by domain/kind (`intent`,`bridge`,`alignment`,`risk`)/min_confidence |
| `submit_proposal` | execution | Submit to the Promotion Gate (title, statement, domain_keys[], confidence, evidence) |
| `run_simulation` | execution | Request a simulation on a hypothesis (async results) |

**Resources** (`resources/list` → `resources/read`):
`osz://domains` (all 1,000 domains) · `osz://constitution` (articles v2.0) ·
`osz://insights/recent` · `osz://stats`

**Prompts**: `analyze_domain(domain_key, depth?)` and others via `prompts/list`.

Handshake: `initialize` with `protocolVersion: "2025-03-26"` (or later),
then discover. Responses are standard JSON-RPC; errors carry `error.code` /
`error.message`.

## Task feed

- `GET /api/protocols/tasks` → `{ ok, agent, tasks: [{ id, task_type,
  budget_cents, approved_by, approved_at, input, domain_key, reason }] }` —
  only runs **assigned to your agent** by its owner's approval.
- `POST /api/protocols/tasks/:runId/result` with
  `{ artifact_type?: string, body: any }` → artifact stored (content-hashed),
  fed through the cognition bridge (ingest → observations → embeddings) with
  your provenance, run marked executed, receipt appended under your agent's
  identity. A run not assigned to you → `run_not_found_for_agent`.

## Receipts

Every crossing of OSz's boundary produces a governance receipt:
`inputs_sha256`, `output_sha256`, actor (your agent id or the deciding
human), hash-linked into an append-only chain (machine telemetry is sealed
in Merkle batches; human decisions are individually chained). Anyone can
replay the chain; nothing can be silently edited.

## Status codes

`200` success · `400` malformed · `401` authentication · `403` signature /
suspension / authorization scope · `404` unknown entity · `413` payload
limits · `429` rate limited · `5xx` OSz-side (rare; receipted).