@kontextmind/kxm 0.7.94 → 0.7.96

package/docs/reference/http-api.md

@@ -0,0 +1,203 @@
+# Hub HTTP API reference
+
+This page lists every route the KXM [hub](../glossary.md#hub) serves: method, path, the credential it requires, what it does and the errors you are most likely to see. It also covers the Runtime supervisor's local API. KXM's own clients (the CLI, the Pi extension and the Claude Code plugin) are the supported way to use these routes; request and response shapes follow KXM releases and carry no separate compatibility promise beyond the `/v1` prefix.
+
+## Conventions
+
+| Topic | Rule |
+|---|---|
+| Base URL | `http://127.0.0.1:7331` by default (`KXM_HOST`, `KXM_PORT`) |
+| Request bodies | JSON objects with `content-type: application/json` (`unsupported_media_type`, 415), at most 256 KiB (`payload_too_large`, 413) |
+| Errors | `{ "error": "<message>", "code": "<code>", "requestId": "<id>" }`, sometimes with hints such as `nextAction` or `assignedCoordinatorName`. A 500 says only `internal server error` |
+| Request IDs | Send `x-request-id` (letters, digits, `.`, `_`, `-`, up to 80) to have it echoed; otherwise the hub assigns one |
+| Rate limit | All routes but `/health` and `/ready` count per agent ID, else per address. Headers `x-ratelimit-limit`, `x-ratelimit-remaining`; over the limit, 429 `rate_limited` with `retry-after` |
+| Unknown routes | 404 `route_not_found` |
+| Limits | Field lengths and ranges are in [Protocol limits](configuration.md#protocol-limits) |
+
+## Authentication
+
+Each route requires one of these credential classes. Send tokens as `Authorization: Bearer <token>`; never put a token in a URL.
+
+| Class | What to send | Notes |
+|---|---|---|
+| None | Nothing | Public health probes only |
+| Admin | The admin token (`KXM_AUTH_TOKEN` on the hub) | A loopback hub with no admin token at all accepts any caller |
+| Admin, configured | The admin token | Answers 503 `admin_auth_not_configured` when the hub has no admin token, even on loopback |
+| Project | The project's token, or the admin token for a project with no token of its own | Admission for agent registration and Runtime sync |
+| Agent | The project token plus `x-kxm-agent-id` and `x-kxm-agent-key` from registration | The agent key rotates on every registration (401 `invalid_agent_identity` when stale) |
+| Agent or admin | Agent headers for your own project, or the admin token with an explicit `project` | Admin calls may name a caller in `x-kxm-caller-id` |
+| Signed | HMAC-SHA256 of the raw body in `x-hub-signature-256` (or `x-hub-signature`) as `sha256=<hex>`, plus a delivery ID | No bearer token; the secret is the workflow definition's |
+
+A wrong or missing token is 401 `invalid_auth`. The [trust model](../concepts/trust-model.md) explains which person or process holds each credential.
+
+## Health and operations
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `GET` | `/health` | None | Liveness: `{ "ok": true, "agents": <online count> }` |
+| `GET` | `/ready` | None | Storage readiness: `{ "ok", "storage": "sqlite" or "memory" }`; 503 when storage is unhealthy |
+| `GET` | `/metrics` | Admin | Prometheus text: requests, errors, messages, workflows, leases, sync and Runtime heartbeat counters |
+| `GET` | `/v1/ops/snapshot?project=<p>` | Admin, configured | Metadata for one project: agents, up to 16 open messages, up to 8 runs with stage progress, home Runtimes, recent plan summaries (120 characters) |
+| `GET` | `/v1/ops/events?project=<p>` | Admin, configured | Server-sent events: an `ops` event naming the topic (`agents`, `messages`, `workflows`) whenever it changes; 15-second heartbeats |
+
+Operations routes carry no message bodies. `kxm dash` and `kxm tenant status` use them. See [Monitoring](../operations/monitoring.md).
+
+## Agents and presence
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/v1/agents/register` | Project | Register or resume `name` in `project` with `purpose`, optional `model` and `host`. Returns the agent and a new `agentKey` (201 new, 200 resumed) |
+| `GET` | `/v1/agents` | Agent | Agents in your project; `?includeOffline=true` adds registered offline agents |
+| `POST` | `/v1/agents/<agentId>/heartbeat` | Agent | Renew your presence lease (clients send one every 10 seconds) |
+| `DELETE` | `/v1/agents/<agentId>` | Agent | Mark yourself offline (204) |
+
+Key errors: `duplicate_agent_name` (409, the name is online in the project), `invalid_agent_identity` (401). Presence (`online`, `stale`, `offline`) is computed from the hub's clock with a 30-second lease; agents never report their own presence.
+
+## Messages and events
+
+A message is a durable request between two agents in one project. The sequence below shows one agent session on the wire.
+
+```mermaid
+sequenceDiagram
+  participant A as Agent A
+  participant H as Hub
+  participant B as Agent B
+  A->>H: POST /v1/agents/register (project token)
+  H-->>A: agent record and agent key
+  A->>H: GET /v1/events?agentId=A (SSE stream)
+  B->>H: POST /v1/messages (target A)
+  H-->>A: event: message
+  A->>H: POST /v1/messages/:id/ack
+  A->>H: POST /v1/messages/:id/reply
+  H-->>B: event: reply
+  A->>H: POST /v1/agents/:id/heartbeat (every 10 s)
+```
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/v1/messages` | Agent | Send a request: `target`, `content`, optional `delivery`, `correlationId`, `idempotencyKey`, `workflowContext`, `ttlMs`, `maxHops`, `allowOffline`. 202 new; 200 with `idempotent: true` for an exact retry |
+| `GET` | `/v1/messages/<id>` | Agent | Read a message you sent or received |
+| `POST` | `/v1/messages/<id>/ack` | Agent | Recipient marks a queued message `delivered` |
+| `POST` | `/v1/messages/<id>/reply` | Agent | Recipient replies with `content`; the sender gets a `reply` event |
+| `DELETE` | `/v1/messages/<id>` | Agent | Sender cancels a queued or delivered message |
+| `GET` | `/v1/events?agentId=<id>` | Agent | Server-sent events for that agent: `ready`, then `message`, `reply`, `cancelled`, `expired` and `presence`. Pushes unacknowledged messages again on connect |
+
+`GET /v1/events` with `presenceOnly=true` sends only `presence` events and is reserved for dashboard observers (`presence_stream_forbidden` otherwise).
+
+Key errors: `target_not_found` (404), `self_target` and `hop_limit_reached` (400), `idempotency_conflict` (409), `message_not_found` (404), `message_forbidden` (403, not your message), `duplicate_reply` and `invalid_message_state` (409). A request with `workflowContext` adds the `workflow_context_*` and `workflow_evidence_*` codes listed under [`kxm_send`](tools.md#kxm_send).
+
+> [!IMPORTANT]
+> Delivery is at least once. A message stays `queued` or `delivered` until it is replied to, cancelled or expires. Whenever the recipient connects, including after a hub or agent restart, the hub pushes its `queued` messages again with the same message ID until the recipient acknowledges them. A `delivered` (acknowledged) message is not pushed again. Make side effects idempotent.
+
+The hub tracks acknowledgement with a per-recipient cursor that moves to the highest acknowledged message, so a queued message older than one the recipient already acknowledged is not pushed again either.
+
+## Workflows, journal and improvements
+
+These routes serve the coordinator of a [webhook workflow run](workflow-definitions.md#webhook-workflow-definitions). Every agent route answers 403 `workflow_forbidden`, with `assignedCoordinatorName` and `nextAction: use_assigned_coordinator`, to any agent other than the run's coordinator.
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `GET` | `/v1/workflows` | Agent | Runs in your project assigned to you |
+| `GET` | `/v1/workflows/<runId>` | Agent | One run and its journal |
+| `POST` | `/v1/workflows/<runId>/checkpoints` | Agent | Record the active stage's result: `stageId`, `status`, `summary`, `evidence`, `evidenceRefs`, optional `outcome` |
+| `POST` | `/v1/workflows/<runId>/waits` | Agent | Park the active stage until a signed signal: `stageId`, `signalKey`, `summary`, optional evidence and `timeoutMs` (202) |
+| `POST` | `/v1/workflows/<runId>/journal` | Agent | Add a journal entry: `category`, `area` or `stageId`, `summary`, optional `severity`, `details`, `evidence`, `relatedEntryIds` (201) |
+| `POST` | `/v1/workflows/<runId>/degradations` | Admin, configured | Approve the policy's lower peer minimum for the current attempt: `stageId`, `requirementKey`, `reason` (201 new, 200 repeat) |
+| `GET` | `/v1/improvements` | Agent | Improvement report for your project: `reports` by area and ranked cross-run `signals` |
+| `POST` | `/v1/journal/<entryId>/promotion` | Admin | Move a promotable journal entry to `approved`, `rejected` or `quarantined` with `reason` and `evidenceRefs`; recorded as decided by `kxm-admin` |
+
+Key errors: `workflow_not_found` (404), `workflow_stage_out_of_order`, `workflow_terminal`, `workflow_not_running` (409), `workflow_evidence_incomplete`, `workflow_provenance_invalid`, `invalid_workflow_evidence_refs`, `weakened_reproduction`, `plan_hash_required` (400), `invalid_journal_category`, `invalid_improvement_area`, `journal_evidence_required` (400), `workflow_degradation_forbidden` (400, the policy declares no degradation) and `workflow_degradation_conflict` (409, a different reason was already approved). The agent tools that call these routes are described in [Workflow tools](tools.md#workflow-tools).
+
+## Webhooks and signals
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/v1/webhooks/<definitionId>` | Signed with the definition's start secret | Start a run and prompt the coordinator (status codes below) |
+| `POST` | `/v1/webhooks/<definitionId>/runs/<runId>/signals/<signalKey>` | Signed with the signal secret, else the start secret | Report an external result for a waiting stage: `status` (`passed`, `warning`, `failed`), `summary`, `evidence`. 202 when the coordinator is resumed, 200 otherwise |
+
+A start answers 202 for a new run, 200 with `duplicate: true` for a known delivery ID, and 204 when the event or filter does not match.
+
+The delivery ID comes from `x-atlassian-webhook-identifier`, `x-github-delivery` or `x-kxm-delivery-id`, in that order, and is required. The event comes from `x-github-event`, else the payload's `webhookEvent` or `event` field.
+
+A start with a known delivery ID returns the existing run even if the body differs. A signal with a known delivery ID returns the original receipt when the body matches and 409 `workflow_signal_delivery_conflict` when it does not. Deduplication lasts as long as the run is retained.
+
+Key errors: `webhook_not_found` (404), `webhook_signature_missing`, `webhook_signature_unsupported`, `webhook_signature_invalid` (401), `workflow_target_unavailable` (409, the coordinator never registered), `workflow_not_waiting`, `workflow_signal_mismatch` (409, the run waits for another key) and `workflow_signal_context_mismatch` (409, evidence names another run, stage or signal). See [Webhook workflows](../guides/webhook-workflows.md).
+
+## Context and state
+
+All context routes take a `project` in the body. An agent may name only its own project (`context_isolation_violation`, 403).
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/v1/context/get` | Agent or admin | Assemble a context packet for `role` and `task`; returns `packet` and `audit` |
+| `POST` | `/v1/context/recall` | Agent or admin | Search records by `query`, `kinds`, `limit`; returns metadata with `relevance` |
+| `POST` | `/v1/context/state` | Agent or admin | Read one state `key`, optionally `asOf` a timestamp |
+| `POST` | `/v1/context/state/propose` | Agent, or admin configured | Propose a state change (201 `proposalId`). An agent proposes as a peer, capped at `evidence` authority; the admin proposes as a human |
+| `POST` | `/v1/context/state/promote` | Admin, configured | Promote `proposalId` with `evidence`; the promoter cannot be the proposer |
+| `POST` | `/v1/context/episode` | Agent or admin | Error, lesson, observation and experiment entries, optionally for one `workflowRunId` |
+| `POST` | `/v1/context/explain` | Agent or admin | Lineage, evidence references and sources behind one item `id` |
+| `POST` | `/v1/context/wiki/compile` | Agent or admin | Compile the project's knowledge wiki pages with an audit and lint result |
+
+Key errors: `invalid_context_request` (400), `state_proposer_mismatch` (403, `proposedBy` names someone else), `state_proposal_not_found` (404), `state_proposal_not_promotable` and `state_promotion_invalid` (400). The hub logs sizes, never the task or query text. See [Context and memory](../guides/context-and-memory.md).
+
+## Leases
+
+A lease gives one agent exclusive, fenced use of a named resource in its project, such as a branch. The hub prefixes the name with the caller's project, so two projects never contend.
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/v1/leases/<name>/acquire` | Agent | Take or renew the lease; optional `ttlMs` (5 seconds to 10 minutes, default 5 minutes). Returns the lease and its `fencingToken` |
+| `POST` | `/v1/leases/<name>/renew` | Agent | Extend it; requires your `fencingToken` |
+| `POST` | `/v1/leases/<name>/release` | Agent | Release it; requires your `fencingToken` |
+
+The fencing token increases only when a new holder takes over an expired lease. Refusals are `lease_held`, `lease_expired`, `lease_superseded` (409, with the current lease) and `lease_not_found` (404). Treat any refusal as "stop writing", not "retry". No bundled tool or command calls these routes yet.
+
+## Runtime sync
+
+A Runtime supervisor is a machine client, not an agent. It reports presence and pushes run summaries with the project token.
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| `POST` | `/v1/runtime/presence` | Project | Heartbeat a `runtimeId` and optional `host` for `project` (201 first time, 200 after) |
+| `POST` | `/v1/sync/events` | Project | Push up to 100 `kxm.sync-event.v1` events for `project` from `runtimeId`. Returns a per-event outcome and each run's cursor |
+
+Each event is accepted once per project, run and sequence. Identical bytes are a `duplicate`; different bytes under a used sequence are a `conflict` (`sync_<reason>`) and raise a security alert. An event from another Runtime is `rejected` with `sync_runtime_mismatch`, a malformed one with `sync_event_invalid`. A batch over 100 events is 413 `sync_batch_too_large`. See [Runtime sync](../operations/runtime-sync.md).
+
+## Runtime supervisor local API
+
+> [!NOTE]
+> Internal. The supervisor serves this API on `127.0.0.1` at a port chosen at start, for the `kxm run`, `kxm runs` and `kxm runtime` commands on the same machine. Do not expose it.
+
+Every route except `/healthz` requires `Authorization: Bearer` with the supervisor token from `supervisor.token` in the Runtime directory under the [user state root](config-reference.md#state-outside-the-project). Run routes take `projectRoot` (an absolute path) as a query parameter.
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/healthz?nonce=<n>` | Liveness plus a keyed proof of the token, so a client can tell the real supervisor from a process on a reused port |
+| `POST` | `/v1/shutdown` | Stop the supervisor |
+| `GET` | `/v1/sync/status` | Outbox state per project: pending, acknowledged and refused rows, refusal codes, next attempt |
+| `POST` | `/v1/sync/retry` | Re-queue durably refused outbox rows for `projectRoot` (`kxm runtime sync-retry`) |
+| `POST` | `/v1/runs` | Create a run: `projectRoot`, `workflowId`, `prompt`, optional `commandId` |
+| `GET` | `/v1/runs/<runId>` | The run projected from its events, with drive state |
+| `GET` | `/v1/runs/<runId>/events?after=<n>` | Up to 500 run events after a sequence |
+| `POST` | `/v1/runs/<runId>/drive` | Drive a run with `mode` `simulated` or `live`: 202 with a `driveId` to poll; 409 `run_busy` or `run_handoff_required` |
+| `GET` | `/v1/runs/<runId>/drive` | The open drive session and up to 20 drive receipts |
+| `POST` | `/v1/runs/<runId>/cancel` | Request cancellation; idempotent per `commandId` |
+| `POST` | `/v1/runs/<runId>/signal` | Recovery for a blocked run: `action` `retry`, `unblock`, `fail` or `cancel` (default `unblock`) |
+| `POST` | `/v1/runs/<runId>/wait` | Acknowledges only; it records nothing yet |
+| `GET` | `/v1/drives/<driveId>` | One drive receipt, re-verified against the run's events |
+| `GET` | `/v1/projects/<projectId>/runs` | Up to 50 runs of the bound project, each folded from its events |
+
+A bad token is `runtime_auth_failed`; a missing parameter is `runtime_request_invalid`. The drive route accepts both modes. `kxm runs drive` drives live, with real harness calls, unless you pass `--simulated`.
+
+## Web Studio server
+
+`kxm studio serve` runs a separate local server, on `127.0.0.1:4242` by default, with `/`, `/health`, `GET /api/layout` and `POST /api/mutate`. It answers every route with `Access-Control-Allow-Origin: *`, so any web page in a local browser can read the layout. The mutate route requires a bearer session token only when one resolves; with none it accepts any caller. It accepts an allowlisted command name but executes nothing. See [`kxm studio serve`](cli-reference.md#kxm-studio-serve).
+
+## Related
+
+- [Agent tools](tools.md): the `kxm_*` tools built on these routes
+- [Environment variables and limits](configuration.md): hub settings and protocol limits
+- [Trust model](../concepts/trust-model.md): credentials and what each can reach
+- [Webhook workflows](../guides/webhook-workflows.md): signing starts and signals
+- [Monitoring](../operations/monitoring.md): health, readiness and metrics in practice
+- [CLI reference](cli-reference.md): the commands that call these routes

package/docs/reference/tools.md

@@ -0,0 +1,370 @@
+# Agent tools reference
+
+KXM gives every [agent](../glossary.md#agent) the same 19 `kxm_*` tools for peer messaging, durable workflows and project context. The Claude Code plugin publishes them over MCP, the Pi extension registers the same set, and the operator CLI offers many of the same operations. This page lists each tool's parameters, limits, results and errors, then the Pi slash commands and the Claude Code session hook.
+
+## One catalog, three surfaces
+
+One catalog in the plugin source defines every tool once: its name, JSON Schema parameters and implementation. The MCP server, the Pi extension and the CLI read that catalog, and KXM's tests fail if any of them drifts from it.
+
+```mermaid
+flowchart LR
+  CAT["Tool catalog<br/>19 kxm_* tools"] --> MCP["Claude Code plugin<br/>MCP server, stdio"]
+  CAT --> PI["Pi extension<br/>registered tools"]
+  CAT --> CLI["kxm peer and<br/>kxm workflow commands"]
+  MCP -- "HTTP as a registered agent" --> HUB[("KXM hub")]
+  PI -- "HTTP as a registered agent" --> HUB
+  CLI -- "HTTP as a short-lived agent" --> HUB
+```
+
+| Tool | Group | Changes state | CLI command |
+|---|---|---|---|
+| `kxm_list` | Peers | No | `kxm peer list` |
+| `kxm_send` | Peers | Yes | `kxm peer send` |
+| `kxm_get` | Peers | No | `kxm peer get` |
+| `kxm_fanout` | Peers | Yes | `kxm peer fanout` |
+| `kxm_await` | Peers | No | `kxm peer await` |
+| `kxm_cancel` | Peers | Yes | `kxm peer cancel` |
+| `kxm_inbox` | Peers | No | `kxm peer inbox` (always empty from the CLI) |
+| `kxm_reply` | Peers | Yes | `kxm peer reply` |
+| `kxm_workflow_list` | Workflows | No | None; `kxm workflow list` reads the local database instead |
+| `kxm_workflow_get` | Workflows | No | None; `kxm workflow get` reads the local database instead |
+| `kxm_workflow_checkpoint` | Workflows | Yes | `kxm workflow checkpoint` |
+| `kxm_workflow_record` | Workflows | Yes | `kxm workflow record` |
+| `kxm_workflow_wait` | Workflows | Yes | `kxm workflow wait` |
+| `kxm_improvement_report` | Workflows | No | None |
+| `kxm_context` | Context | No | `kxm context get` (admin token in `KXM_AUTH_TOKEN`) |
+| `kxm_recall` | Context | No | `kxm context recall` (admin token) |
+| `kxm_state` | Context | No | `kxm context state` (admin token) |
+| `kxm_episode` | Context | No | `kxm context episode` (admin token) |
+| `kxm_promote` | Context | Yes (proposal only) | None; `kxm context promote` applies a proposal |
+
+The workflow tools act on hub [webhook workflow runs](workflow-definitions.md#webhook-workflow-definitions). Runs created by `kxm run` belong to the Runtime; inspect those with `kxm runs status`.
+
+## Common behavior
+
+### Identity and credentials
+
+Each tool call acts as the calling session's registered agent in one hub project. The Claude Code MCP server authenticates with a project token only: `auth_token` from the plugin settings, else this project's token saved in `hub-env.json`, and never the admin token. The Pi extension uses `KXM_AUTH_TOKEN`, then the admin token that hub auto-start resolved or generated for the hub it started, then the saved admin token. See [Agent settings](configuration.md#agent-settings).
+
+### Tool policy
+
+A session token or Runtime attempt token can restrict which tools run. KXM checks `KXM_ATTEMPT_TOKEN` first, then `KXM_SESSION_TOKEN`, then the `session.token` file in the user configuration directory; with none of them, every tool is allowed. A denied call fails with `tool_policy_denied`, and an invalid or expired token blocks every tool.
+
+| Policy field | Effect |
+|---|---|
+| `deny` | Names that never run. Wins over `allow` |
+| `allow` | When non-empty, only these names run |
+| `preset: read-only` | Blocks `kxm_send`, `kxm_fanout`, `kxm_cancel`, `kxm_reply`, `kxm_workflow_checkpoint`, `kxm_workflow_record`, `kxm_workflow_wait` and `kxm_promote` |
+
+A name matches as the full tool name, the name without `kxm_`, `*`, or a trailing-`*` prefix such as `kxm_workflow_*`. Under an attempt token, `kxm_promote` also needs an explicit `allow` entry (`attempt_token_admin_denied`).
+
+### Results and errors
+
+Every tool returns its result as JSON text; Pi also attaches the same value as structured details. Errors reach the model as text that names the next step:
+
+| Error text | Harness | Fix |
+|---|---|---|
+| `KXM has no project token for project <p> on this machine` | Claude Code | Set `auth_token` with `/plugin configure kxm@kxm`, or [give the project a token](../start/quickstart-claude-code.md#give-the-project-a-token-on-the-running-hub) on the hub |
+| `KXM hub unreachable at <url> (<cause>)` | Claude Code | Start the hub with `kxm hub start`, or correct `server_url` |
+| `KXM hub rejected the project token for project <p>` | Claude Code | Enter that project's token from the hub's `KXM_PROJECT_TOKENS` |
+| `kxm hub is not connected; check KXM_SERVER_URL and /kxm hub` | Pi | Start the hub or fix `KXM_SERVER_URL`, then restart the session |
+| `tool_policy_denied: …` | Both | Lift the policy; see [Troubleshooting](../operations/troubleshooting.md) |
+| Hub refusal, for example `stage review is not currently active` | Both | Pi appends `[code=<code> …]`; Claude Code shows the message only |
+
+The hub's error codes are listed with each tool below and in the [HTTP API reference](http-api.md).
+
+## Peer tools
+
+Peer tools send and answer [requests](../glossary.md#message) between agents in the same project. A request is durable: it survives restarts of the hub and of either agent, and delivery is at least once. See [Peer messaging](../guides/peer-messaging.md) for patterns.
+
+### `kxm_list`
+
+Lists agents in this project with presence computed from the hub's clock.
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `includeOffline` | Boolean | `false` | Also list registered agents whose presence lease expired |
+
+Returns `{ "agents": [...] }`. Each agent has `id`, `name`, `purpose`, `project`, `connectedAt`, `lastSeenAt`, `leaseExpiresAt` and `presence` (`online`, `stale` or `offline`), plus `model` and `host` when the agent declared them. The list includes the caller. Agent keys are never returned.
+
+### `kxm_send`
+
+Sends one focused request to one peer.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `target` | String, required | 80 characters | Peer name (case-insensitive) or agent ID |
+| `content` | String, required | 32,000 characters | The request and the expected response |
+| `delivery` | `followUp`, `steer`, `nextTurn` | `followUp` | See [Delivery modes](configuration.md#delivery-modes) |
+| `correlationId` | String | 128 characters | Groups related requests. With `workflowContext` it must equal the run ID, and defaults to it |
+| `idempotencyKey` | String | 128 characters | An exact retry returns the original message |
+| `workflowContext` | Object | None | `runId`, `stageId`, `requirementKey`, `attempt` (1 to 20); marks the reply as peer evidence |
+| `ttlMs` | Number | 1,000 to 604,800,000; hub default 24 hours | How long the request stays valid |
+| `allowOffline` | Boolean | `false` | Queue for a registered peer that is offline |
+
+Returns `{ "messageId", "status", "target" }`.
+
+Key errors: `target_not_found` (no online peer by that name or ID), `self_target`, `idempotency_conflict` (the key was used for a different request). With `workflowContext`: `workflow_context_forbidden` (you are not the run's coordinator), `workflow_context_inactive` (not the active stage), `workflow_context_attempt_mismatch`, `workflow_evidence_policy_missing` (the requirement takes no peer evidence), `workflow_evidence_producer_forbidden` (the target is not eligible), and `workflow_context_correlation_mismatch`.
+
+### `kxm_get`
+
+Reads a request's current state and reply without waiting.
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `messageId` | String, required | A request you sent or received |
+
+Returns the message record: `id`, `from`, `fromName`, `to`, `toName`, `content`, `delivery`, `status`, `createdAt`, `expiresAt`, and when present `reply`, `deliveredAt`, `repliedAt`, `error`, `correlationId` and `workflowContext`. Status is `queued`, `delivered`, `replied`, `cancelled` or `expired`. Errors: `message_not_found`, `message_forbidden` (you are neither sender nor recipient).
+
+### `kxm_fanout`
+
+Sends the same request to one to three peers independently and waits for their replies.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `targets` | Array of strings, required | 1 to 3 | Duplicates, compared case-insensitively, are merged |
+| `content` | String, required | 32,000 characters | Sent unchanged to every target |
+| `correlationId` | String | 128 characters | As for `kxm_send` |
+| `idempotencyKeyPrefix` | String | None | Each target's key derives from the prefix, correlation ID and target |
+| `workflowContext` | Object | None | Shared by every request; each target must be eligible |
+| `ttlMs` | Number | 1,000 to 604,800,000 | Request lifetime |
+| `timeoutMs` | Number | 100 to 1,800,000; default 30 minutes | Local wait only; never cancels a request |
+
+Every request uses `followUp` delivery. Returns `{ "responses": [...] }` with one entry per target:
+
+- Finished: `target`, `messageId`, `status` (`replied`, `cancelled` or `expired`), and `reply` or `error`.
+- Still running when the wait ends: `status: "pending"`, `messageId`, `messageStatus`, `expiresAt` and `waitStatus` (`timed_out` or `aborted`). Check it later with `kxm_get`, or repeat the exact call.
+- Failed to send: `status: "error"` and `error`. One failed target does not fail the others.
+
+### `kxm_await`
+
+Waits for a sent request to finish.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `messageId` | String, required | None | A request you sent |
+| `timeoutMs` | Number | 100 to 60,000; default 60,000 | Larger values are capped at 60 seconds |
+
+Returns the message record once it is `replied`, `cancelled` or `expired`. When the wait ends first, the call fails with `timed out waiting for <messageId>`; the request is still pending, so check it later with `kxm_get`. For long external work, use `kxm_workflow_wait` instead.
+
+### `kxm_cancel`
+
+Cancels a request you sent that has not been answered.
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `messageId` | String, required | A queued or delivered request you sent |
+
+Returns the message record with `status: "cancelled"`. Cancelling an already cancelled request returns it unchanged. Errors: `message_forbidden` (you did not send it), `invalid_message_state` (it already has a reply or expired). Cancelling stops KXM processing only; it cannot undo files or external effects the peer already changed.
+
+### `kxm_inbox`
+
+Lists inbound requests that still need a reply. It takes no parameters.
+
+- **Claude Code:** returns `{ "messages": [...] }` from the session's inbox, which fills from the hub's event stream while the session is registered. Before returning, it re-reads each request and drops those already answered, cancelled or expired. This is pull mode; see [Pushed channel mode and pull mode](../../plugins/kxm/README.md#pushed-channel-mode-and-pull-mode).
+- **Pi:** always returns an empty list. The extension turns each inbound request into a model turn instead.
+- **CLI:** always returns an empty list, because a one-shot command holds no inbox.
+
+### `kxm_reply`
+
+Sends the final reply to an inbound request.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `messageId` | String, required | None | A request addressed to you |
+| `content` | String, required | 32,000 characters | The result, with evidence and remaining risks |
+
+Returns `{ "messageId", "status": "replied", "recipient" }`. Errors: `message_forbidden` (not addressed to you), `duplicate_reply`, `invalid_message_state` (cancelled or expired).
+
+> [!IMPORTANT]
+> Replying to a workflow run's coordinator prompt while the run is still `running` fails the run. Pass every checkpoint, or call `kxm_workflow_wait`, before you reply.
+
+In Pi you rarely call `kxm_reply`: the extension sends the settled final response as the reply automatically, truncated to 32,000 characters with a note if it is longer.
+
+## Workflow tools
+
+Workflow tools are for the coordinator a webhook workflow run is assigned to. Only that agent can read, checkpoint, wait on or journal the run; any other agent gets `workflow_forbidden`, with the assigned coordinator's name. See [Webhook workflows](../guides/webhook-workflows.md) for the coordinator procedure.
+
+### `kxm_workflow_list`
+
+Lists the webhook workflow runs in this project assigned to you, in any status, until the hub purges them. It takes no parameters and returns `{ "runs": [...] }`.
+
+### `kxm_workflow_get`
+
+Reads one run and its journal.
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `runId` | String, required | A run assigned to you |
+
+Returns `{ "run", "journal" }`. The run holds `status` (`running`, `waiting`, `completed` or `failed`), `currentStage`, every stage's instructions, required evidence, attempts and evidence, any active `waiting` state, and typed transitions. Errors: `workflow_not_found`, `workflow_forbidden`.
+
+### `kxm_workflow_checkpoint`
+
+Records the result of the active stage.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `runId` | String, required | None | The run |
+| `stageId` | String, required | None | Must be the current stage |
+| `status` | `passed`, `warning`, `failed`, required | None | The stage outcome |
+| `summary` | String, required | 4,000 characters | Changes, verification and remaining risks |
+| `evidence` | Object of strings | 64 keys; values 1,000 characters | Keyed by required evidence name |
+| `evidenceRefs` | Object | 32 requirements; 1 to 16 message IDs each | `{ "<requirement>": { "messageIds": [...] } }` for peer-reply requirements; only on `passed` |
+
+Evidence keys are compared after trimming, collapsing whitespace and lowercasing. A `passed` checkpoint must cover every required key; a key with a peer-reply policy is satisfied only by verified `evidenceRefs`, never by an evidence string. A `warning` or `failed` checkpoint consumes an attempt and asks you to fix and retry; when the attempts reach the stage's `maxAttempts`, the run fails. A stage can route outcomes or escalate instead; see [Transitions and outcome keys](workflow-definitions.md#transitions-and-outcome-keys).
+
+Returns `{ "run", "retry", "completed", "instruction" }`. The instruction tells you to retry, continue with the next stage, or finish.
+
+Key errors: `workflow_evidence_incomplete` (lists `missingRequirements`), `workflow_stage_out_of_order`, `workflow_terminal`, `workflow_provenance_invalid` (a cited message does not match the run, stage, requirement, attempt or eligible producer), `invalid_workflow_evidence_refs`, `weakened_reproduction`, `plan_hash_required`. The [provenance guide](../guides/provenance-gates.md) explains peer evidence.
+
+### `kxm_workflow_record`
+
+Adds an entry to the run's learning journal.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `runId` | String, required | None | The run |
+| `category` | String, required | None | `plan`, `decision`, `contradiction`, `error`, `lesson`, `observation`, `hypothesis`, `experiment`, `state-change` or `skill-candidate` |
+| `area` | String | The stage's area | `harness`, `gates`, `implementation`, `workflow`, `documentation`, `security` or `other`; required unless `stageId` names a stage that declares one |
+| `stageId` | String | None | Binds the entry to that stage; the hub derives the attempt |
+| `severity` | `info`, `warning`, `error` | `info` | |
+| `summary` | String, required | 1,000 characters | |
+| `details` | String | 8,000 characters | |
+| `evidence` | Array of strings | 32 items of 1,000 characters | Required for `lesson` and `skill-candidate` |
+| `relatedEntryIds` | Array of strings | 16 | Entries in the same run |
+
+Returns `{ "entry" }`. Errors: `invalid_journal_category`, `invalid_improvement_area`, `journal_evidence_required`, `invalid_journal_relation`, `invalid_journal_severity`. The journal covers hub webhook runs only; a Runtime run ID fails with `workflow_not_found`.
+
+### `kxm_workflow_wait`
+
+Parks the active stage until a signed external callback reports its result, so long work (CI, review, a merge) does not hold a model turn.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `runId` | String, required | None | The run |
+| `stageId` | String, required | None | Must be the current stage |
+| `signalKey` | String, required | 128 characters | Letters, digits, `.`, `_`, `:` and `-`, starting with a letter or digit, for example `github-pr-42-checks` |
+| `summary` | String, required | 4,000 characters | What is running and what result is expected |
+| `evidence` | Object of strings | As for checkpoints | Saved now and merged with the callback's evidence |
+| `evidenceRefs` | Object | As for checkpoints | Peer evidence verified now |
+| `timeoutMs` | Number | 1,000 to 2,592,000,000; default 24 hours | When the wait expires, the run fails |
+
+Returns `{ "run", "instruction" }` with the run in `waiting` status. Then reply to settle your turn: a reply while the run waits does not fail it. The callback (for example from `kxm gate github watch` or `kxm gate signal`) checkpoints the stage and, when work remains, sends you a fresh request. Errors: `invalid_signal_key`, `workflow_not_running`, `workflow_stage_out_of_order`, `workflow_wait_invalid`.
+
+### `kxm_improvement_report`
+
+Summarizes learning across this project's webhook workflow runs. It takes no parameters.
+
+Returns `{ "reports", "signals", "entries" }`. Each report covers one improvement area with counts of errors, contradictions and lessons and up to 10 priority entries. `signals` holds up to 20 duplicates merged across runs, security signals first, then scored by frequency × severity × run-attempt cost × evidence confidence, with redacted text. The report proposes; it changes no workflow or policy. See [Continuous improvement](../guides/continuous-improvement.md).
+
+## Context tools
+
+Context tools read the project's durable context and propose state changes. `project` is optional on every context tool and must equal your own project (`context_isolation_violation` otherwise). See [Context and memory](../guides/context-and-memory.md) for what the packet contains.
+
+### `kxm_context`
+
+Builds a token-budgeted context packet for a role and task. Call it before planning.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `role` | String, required | 64 characters | `repro`, `planner`, `critic`, `implementer`, `verifier`, or a custom role |
+| `task` | String, required | 2,000 characters | What the role is trying to do; drives relevance ranking |
+| `workflowRunId`, `stageId` | String | None | Recorded in the audit and hub log only; they do not filter the packet |
+| `budgetTokens` | Integer | 512 to 200,000 | Defaults: `repro` and `verifier` 8,000, `critic` 12,000, `planner` and `implementer` 16,000, custom roles 32,000 |
+| `includeKinds` | Array | All kinds | Any of `evidence`, `state`, `episode`, `knowledge`, `skill` |
+
+Returns `{ "packet", "audit" }`. Superseded and rejected records are excluded. Selection draws on the whole project whether or not you pass `workflowRunId` and `stageId`. The audit echoes your request, including the `task` text, under `audit.request`, then selected IDs, provenance counts, token estimate and relevance numbers. Only the hub's log records sizes instead of the task text.
+
+### `kxm_recall`
+
+Searches durable context records.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `query` | String | 500 characters | An empty query returns every record, ordered by ID |
+| `kinds` | Array of strings | All | Item kinds to include |
+| `limit` | Integer | 1 to 100; default 25 | |
+
+Returns `{ "items", "unresolvedGaps" }`. Exact-phrase matches rank first, then token relevance, then ID. Each item is bounded metadata with a numeric `relevance`, never a summary.
+
+### `kxm_state`
+
+Reads one temporal state key.
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `key` | String, required | 200 characters |
+| `asOf` | ISO-8601 timestamp | The value in force at that time |
+
+Returns `{ "state", "key" }`, with `state` set to `null` when the key has no value.
+
+### `kxm_episode`
+
+Reads episodes (`error`, `lesson`, `observation` and `experiment` journal entries) from this project's workflow runs, oldest first, at most 50.
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `workflowRunId` | String | Limit to one run |
+
+Returns `{ "episodes": [...] }`.
+
+### `kxm_promote`
+
+Proposes a change to one authoritative state key. Despite its name, it only proposes: nothing changes until an operator promotes the proposal with [`kxm context promote`](cli-reference.md#kxm-context-promote), which needs the admin token and a promoter other than the proposer.
+
+| Parameter | Type | Default or limit | Notes |
+|---|---|---|---|
+| `key` | String, required | 200 characters | The state key |
+| `summary` | String, required | 4,000 characters | The proposed value and why |
+| `authority` | `evidence`, `hypothesis`, required | None | An agent's proposal is peer origin, so `evidence` at most |
+| `confidence` | `verified`, `probable`, `uncertain`, required | None | |
+| `evidenceRefs` | Array of strings, required | 1 to 32 | Context item or journal references backing it |
+
+Returns `{ "proposalId" }`. Blocked by the `read-only` preset; under an attempt token it needs an explicit grant.
+
+## Pi extension commands
+
+The Pi extension connects the session to the hub at start, registers the 19 tools, and adds two slash commands. It also keeps a `kxm` status line and `kxm-work` and `kxm-progress` widgets, refreshed after every turn.
+
+In Pi:
+
+```text
+/kxm
+/kxm status
+/kxm progress
+```
+
+| Command | Effect |
+|---|---|
+| `/kxm`, `/kxm brief` | Refreshes the status line and work widget; in the Pi TUI, also opens the task picker described below |
+| `/kxm status` | Recomputes the session brief and shows its status line |
+| `/kxm progress`, `/kxm workflow`, `/workflow` | Shows the active workflow run's stage progress, roles and model metrics from local state, or `kxm: no active workflow run found in state.` |
+| `/kxm hub` | Probes the hub's `/health` at `KXM_SERVER_URL` and shows this agent's name and the online agent count |
+| `/kxm memory` | Shows the project memory brief by running `kxm memory brief` (or `$KXM_BIN`) |
+| `/kxm help` | Lists the subcommands. Any unknown subcommand shows the same help |
+
+The task picker, `Continue KXM work?`, lists recent tasks and plans and puts the chosen prompt in the editor. It also appears when a Pi TUI session starts, begins a new session or forks, unless `KXM_SESSION_BRIEF=off`.
+
+Inbound requests arrive as a displayed message that starts a model turn: `steer` at the next decision boundary, `followUp` (and `nextTurn`, which an unattended worker cannot wait on) after the current work. The final response is returned as the reply. If the model provider fails, the request stays `delivered` so a supervised worker can recover it. The extension also registers model providers; see [Harness routing](harness-routing.md) and [Nous providers](../guides/nous-providers.md).
+
+## Claude Code plugin
+
+The plugin's MCP server serves exactly the 19 tools above over stdio. When the project directory has `.kxm/`, a project token resolves and the tool policy allows `kxm_inbox` and `kxm_reply`, it registers with the hub at startup so peers can reach the session before its first tool call; otherwise it registers on the first call. Its instructions tell Claude to call `kxm_context` before planning and to answer peer requests with `kxm_reply`.
+
+The plugin also adds:
+
+- **A SessionStart hook**, `node ${CLAUDE_PLUGIN_ROOT}/dist/claude-hook.js session-start`, with a 5-second limit. Only in a directory with `.kxm/`, it adds the hub state, up to three active runs, the open request count, where to start, any fix hints, and the project memory brief. It is read-only, needs no `kxm` on `PATH`, and never fails the session.
+- **Pushed channel delivery**, where peer requests arrive as `<channel source="kxm" message_id="…">` events, with pull mode through `kxm_inbox` as the fallback.
+- **Five settings** (`server_url`, `auth_token`, `agent_name`, `agent_purpose`, `project`), described in [Claude Code plugin settings](config-reference.md#claude-code-plugin-settings).
+
+The [plugin README](../../plugins/kxm/README.md) covers installation, the hook's exact output, channel mode and troubleshooting.
+
+## Related
+
+- [Peer messaging](../guides/peer-messaging.md): request patterns, fanout and pull mode
+- [Webhook workflows](../guides/webhook-workflows.md): the coordinator procedure the workflow tools serve
+- [Peer provenance and quorum gates](../guides/provenance-gates.md): `workflowContext` and `evidenceRefs`
+- [Context and memory](../guides/context-and-memory.md): packets, recall, state and promotion
+- [Hub HTTP API](http-api.md): the routes these tools call
+- [Environment variables and limits](configuration.md): credentials, delivery modes and protocol limits