melchizedek-agents 0.9.6 → 0.16.0

package/DOCUMENTATION.md

@@ -26,7 +26,7 @@ see [`QUICKSTART.md`](./QUICKSTART.md).
 config/agents/            YOUR syndicate definitions (the engine's input)
 config/agents/examples/   the starter pack — shipped example syndicates
 lib/loadSyndicate.ts      YAML → validated config (+ variable binding)
-lib/dispatch.ts           plan-dispatch route resolution (§6, A2A-only)
+lib/dispatch.ts           plan-dispatch route resolution (§6)
 lib/toolRegistry.ts       tool name → live ADK tool instance
 lib/models/claudeLlm.ts   Claude adapter registered into the ADK registry
 lib/models/ollamaLlm.ts   open-weight local adapter (Ollama, keyless)
@@ -35,8 +35,12 @@ scripts/demo_mcp_server.ts   demo MCP server (library catalog, SSE)
 lib/session/…             Supabase-backed session service
 lib/memory/…              pgvector long-term memory service
 lib/observability/…       OpenTelemetry run tracing
-scripts/syndicate_chat.ts CLI REPL / one-shot runner (compiles the graph)
-scripts/a2a_server.ts     HTTP JSON-RPC service mode (same compiler)
+lib/runtime/syndicateTurn.ts  THE turn runner: every surface below calls it
+lib/a2a/app.ts            the A2A server as a library (createA2AApp)
+lib/a2a/remoteAgent.ts    A2A client: remote agents as subagents
+scripts/syndicate_chat.ts CLI REPL / one-shot runner
+scripts/a2a_server.ts     the A2A server bin (melchizedek-serve)
+db/schema.sql             the base schema (sessions, memory, expiry)
 db/hardening.sql          deny-by-default RLS for the Supabase tables
 tests/agents.test.ts      compiles every shipped syndicate; opt-in live check
 ```
@@ -56,6 +60,8 @@ Minimal complete example:
 syndicate_name: "My Council"
 memory_system: "session-only"     # internal-only | session-only | long-term
 
+# guards: [my_guard]              # [optional] post-answer guards, by name
+
 variables:                        # bound into {{placeholders}} at load
   headline_count: 5               # current_date is injected automatically
 
@@ -85,17 +91,23 @@ Field reference:
 
 | Field | Where | Meaning |
 |---|---|---|
-| `syndicate_name` | root | Display name; also namespaces memory user keys. |
-| `memory_system` | root | `internal-only` (nothing persists), `session-only` (transcript persists in Supabase), `long-term` (adds fact distillation + vector recall). |
+| `syndicate_name` | root | Display name. On the CLI it also namespaces memory user keys; on the A2A server memory is keyed by the caller's silo across every long-term syndicate that server serves. |
+| `memory_system` | root | `internal-only` (nothing persists — on the server too: its transcripts stay in process memory), `session-only` (transcript persists in Supabase), `long-term` (adds fact distillation + vector recall). |
 | `variables` | root | Key/values bound into `{{placeholders}}` anywhere in instructions. `current_date` is always injected; CLI `--bind key=value` overrides. |
 | `memory_extraction_rules` | root | Domain rules appended to the shared fact-extraction prompt for THIS syndicate only (requires `memory_system: "long-term"`). The extraction prompt is global — anything domain-specific belongs here, never edited into it. Unset, the prompt renders byte-identical to before the slot existed (§4). |
-| `dispatch` | root | Switches the syndicate from DELEGATE to PLAN-DISPATCH routing (§6). `default_route` (required) names the fail-static subagent; `route_key` / `reason_key` name the router's JSON properties (defaults `route` / `reason`). A2A-only. |
+| `memory_extraction_model` | root | The model that distils this syndicate's turns into memory records (long-term only); any model id. Default: the deployment's `MEMORY_EXTRACTION_MODEL`. |
+| `memory_retention_days` | root | Days a fact in this syndicate's namespace is kept; the server deletes older facts when it loads the syndicate and daily after. Requires `memory_namespace` (never applied to the shared default namespace). |
+| `dispatch` | root | Switches the syndicate from DELEGATE to PLAN-DISPATCH routing (§6). `default_route` (required) names the fail-static subagent; `route_key` / `reason_key` name the router's JSON properties (defaults `route` / `reason`). Honoured by every surface (the CLI, the server, the worker, evals). |
+| `guards` | root | Optional list of post-answer guard NAMES (`lib/guards/index.ts`). Each runs after the answering turn and before the reply publishes, receiving the final text plus every tool-result text of that turn, and rewrites in place rather than re-asking the model; its notes land in the `[STATUS]` stream. Guards declared by a syndicate reached through `yaml_reference:` count too — the server resolves the union via `collectGuards()`. Resolved by name, never by module path, so adding one is a deliberate act in code; **the published registry ships one, `science`** (citation checks for `research.yaml`); `registerGuard()` adds your own from code, and an unregistered name is warned about and skipped. |
 | `name` / `model` / `instruction` | agent | The agent triple. Any Gemini id, `claude-*`, or `ollama/*` for open-weight local models (see §5). |
 | `description` | subagent | **The delegation API.** The orchestrator reads this when deciding to hand off — write it like a function signature ("Use this subagent to…, pass it…"). |
 | `tools` | agent | Names resolved by the tool registry (§3). Long-term memory agents add `preload_memory` / `load_memory`. |
 | `generateContentConfig` | agent | Temperature, output caps, thinking budget/level. |
 | `outputSchema` | agent | Structured-JSON contract. **Constraint:** an agent holding `outputSchema` cannot also hold transfer powers — the ADK deadlocks it. Keep schema-holders as leaf agents (see `critic.yaml`'s header comment for the war story). |
 | `yaml_reference` | subagent | Mount another syndicate file as a nested subagent. |
+| `a2a_agent_url` | subagent | A REMOTE agent over A2A (§6): the orchestrator delegates to it with one `request` argument; in plan-dispatch it can be a route. No `model`/`instruction` — the remote agent has its own. Credentials come from `A2A_AGENT_TOKENS`, never YAML. |
+| `max_steps` | root | Cap on model calls per turn, counted across every agent the turn reaches (orchestrator, subagents, nested syndicates). Exceeding it fails the turn with `STEP_LIMIT`. |
+| `includeContents` / `outputKey` / `globalInstruction` / `disallowTransferToParent` / `disallowTransferToPeers` | agent | Passed through to ADK's LlmAgent. `includeContents: none` makes an agent see only the current message. |
 | `mcp_server_url` | subagent | Discover this subagent's tools from a remote MCP server at load time (§3). SSRF-guarded; `ALLOW_PRIVATE_MCP=true` permits localhost for development. |
 
 Validation happens at load: missing names, legacy option blocks, and
@@ -119,6 +131,8 @@ instance:
 | `load_memory` | ADK built-in | Explicit tool call to search the fact store (deliberate recall). |
 | `generate_image` | FunctionTool | Calls the Gemini image model directly, saves the result under `outputs/`, returns the path. A FunctionTool because binary `inlineData` cannot survive the AgentTool text boundary. |
 | `inspect_image` | FunctionTool | **Blind visual inventory** of a file under `outputs/`: subjects with exact counts, composition, light, palette, medium cues, artifacts — zero quality judgments. Its signature accepts *only* a file path, so an orchestrator cannot leak expectations into the observation (see `image_production.yaml`). |
+| `task_add` / `task_list` / `task_get` / `task_update` | FunctionTool | A to-do list and job queue. Default: a single-user JSON file (`MELCHIZEDEK_TASKS_FILE`, default `outputs/tasks.json`), so every caller of a shared endpoint shares one list. With `DATABASE_URL` (migration 0009) each caller has its own list, scoped by the caller's scope key, and any number of workers take jobs safely. |
+| `task_queue` | FunctionTool | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. |
 
 **MCP tools** are the exception to the registry: a subagent with
 `mcp_server_url:` in its YAML gets its tools from a remote MCP server at
@@ -154,93 +168,33 @@ Two Supabase tables carry the two kinds of remembering:
   history); recall is cosine similarity re-ranked by keys and dates.
   Full pipeline: [`lib/memory/README.md`](./lib/memory/README.md).
 
-Provision both in the Supabase SQL Editor:
-
-```sql
--- 1. Enable pgvector
-CREATE EXTENSION IF NOT EXISTS vector;
-
--- 2. Sessions
-CREATE TABLE adk_sessions (
-  id TEXT PRIMARY KEY,
-  app_name TEXT NOT NULL,
-  user_id TEXT NOT NULL,
-  state JSONB DEFAULT '{}'::jsonb,
-  events JSONB DEFAULT '[]'::jsonb,
-  last_update_time BIGINT,
-  expire_at TIMESTAMPTZ,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
--- 3. Memory facts (structured records: date, source, status, index keys
---    live beside the embedding — see lib/memory/README.md)
-CREATE TABLE adk_memory_facts (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_key TEXT NOT NULL,
-  fact TEXT NOT NULL,
-  embedding vector(768),
-  tag TEXT,
-  fact_date DATE,
-  source TEXT,
-  status TEXT NOT NULL DEFAULT 'active',
-  keys TEXT[] NOT NULL DEFAULT '{}',
-  superseded_by UUID,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
--- 4. Indexes: similarity, entity keys, dates
-CREATE INDEX ON adk_memory_facts USING ivfflat (embedding vector_cosine_ops)
-WITH (lists = 100);
-CREATE INDEX adk_memory_facts_keys_idx ON adk_memory_facts USING gin (keys);
-CREATE INDEX adk_memory_facts_date_idx ON adk_memory_facts (user_key, fact_date);
-
--- 5. Cosine-similarity RPC (returns the structured columns so the
---    service can re-rank by keys/dates and relabel superseded records).
---    filter_user_key is REQUIRED: a NULL key would return every user's facts.
-CREATE OR REPLACE FUNCTION match_memory_facts (
-  query_embedding vector(768),
-  filter_user_key text,
-  match_count int DEFAULT 10
-) RETURNS TABLE (
-  id UUID,
-  user_key TEXT,
-  fact TEXT,
-  tag TEXT,
-  fact_date DATE,
-  source TEXT,
-  status TEXT,
-  keys TEXT[],
-  created_at TIMESTAMPTZ,
-  similarity float
-)
-LANGUAGE plpgsql
-AS $$
-BEGIN
-  IF filter_user_key IS NULL THEN
-    RAISE EXCEPTION 'filter_user_key is required';
-  END IF;
-  RETURN QUERY
-  SELECT
-    adk_memory_facts.id,
-    adk_memory_facts.user_key,
-    adk_memory_facts.fact,
-    adk_memory_facts.tag,
-    adk_memory_facts.fact_date,
-    adk_memory_facts.source,
-    adk_memory_facts.status,
-    adk_memory_facts.keys,
-    adk_memory_facts.created_at,
-    1 - (adk_memory_facts.embedding <=> query_embedding) AS similarity
-  FROM adk_memory_facts
-  WHERE adk_memory_facts.user_key = filter_user_key
-  ORDER BY adk_memory_facts.embedding <=> query_embedding
-  LIMIT match_count;
-END;
-$$;
+Install both, with their indexes, the recall function and the nightly
+session expiry, from the one canonical file:
+
+```bash
+npx melchizedek-db print     # paste into the Supabase SQL Editor (clone: npm run db -- print)
+npx melchizedek-db apply     # or apply with psql, DATABASE_URL set
+npx melchizedek-db status    # schema version, hardening, session counts
+```
+
+That runs the migrations in [`db/migrations/`](./db/migrations/) and then
+[`db/hardening.sql`](./db/hardening.sql). Both are idempotent, so re-running
+them is also the upgrade path from any earlier layout.
+
+The tables go in the `public` schema by default. To keep them out of reach of
+a REST layer (Supabase exposes `public`), install into a private schema and
+run the server with the same setting:
+
+```bash
+MELCHIZEDEK_DB_SCHEMA=melchizedek npx melchizedek-db apply   # or: apply --schema melchizedek
+MELCHIZEDEK_DB_SCHEMA=melchizedek DATABASE_URL=... npx melchizedek-a2a
 ```
 
+A private schema needs `DATABASE_URL` (the pg driver); supabase-js storage
+reaches only exposed schemas, so the server refuses that combination. Moving an
+existing `public` install is a data migration, not a setting: keep `public`
+there.
+
 Then run [`db/hardening.sql`](./db/hardening.sql) (RLS deny-by-default;
 see §8). Upgrading an existing project to the structured columns:
 [`db/memory_v2.sql`](./db/memory_v2.sql). `npm run db:purge` clears both
@@ -260,10 +214,17 @@ extraction model rephrases on each pass. Two mechanisms in
 `lib/memory/supabaseMemoryService.ts` prevent the store from filling
 with restatements:
 
-- A per-session **high-water mark** (`eventsToIngest`) distils only the
-  turns added since the last ingestion. It is in-process on purpose — a
-  restart re-reads one session once, absorbed by the check below, which
-  is why it needs no table of its own.
+- A per-session **processed marker** (`eventsToIngest`) distils only the
+  turns added since the last ingestion. It is stored in
+  `melchizedek_memory_ingest` (migration 0007) and advances in the same
+  transaction as the facts (`melchizedek_memory_commit`, which also retires
+  superseded rows), so a restart re-extracts nothing and a failure leaves
+  facts, supersessions and marker as they were. A custom store without the
+  commit keeps the marker in process memory.
+- At boot the server compares the embedding column's size
+  (`melchizedek_memory_dimensions()`) with the configured embedder and
+  refuses a mismatch: changing the embedding model is a re-embed, never a
+  dropped table.
 - A **similarity probe** before each insert (`isSemanticDuplicate`,
   `MEMORY_DEDUP_SIMILARITY = 0.93`) drops restatements, reusing the same
   `match_memory_facts` RPC the supersession path calls. It requires the
@@ -299,6 +260,8 @@ accordingly — model optionality is a single YAML line per agent:
 | `claude-*` | Anthropic | `lib/models/claudeLlm.ts` | `ANTHROPIC_API_KEY` | ✅ server tool |
 | `gpt-*`, o-series | OpenAI | `lib/models/gptLlm.ts` (Responses API) | `OPENAI_API_KEY` | ✅ web_search tool |
 | `grok-*` | xAI | `lib/models/grokLlm.ts` (Responses API) | `XAI_API_KEY` | ✅ Agent Tools search |
+| `ollama/*` | Local Ollama | `lib/models/ollamaLlm.ts` | none | ⚠ omitted + warning |
+| *any cloud id whose direct key is absent* | the id's own provider, via a gateway | `lib/models/gatewayLlm.ts` (chat completions) | `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` | ⚠ omitted + reported |
 
 The xAI adapter carries the deepest capability surface: `grok-4.5`
 requests pin `reasoning.effort: "medium"` (`lib/config.ts`), SSE
@@ -307,7 +270,64 @@ partial delta events stream, one aggregated event persists with usage),
 structured outputs ride `outputSchema` → `text.format`, and two
 xAI-only tools — `x_search` and `collections_search` (§3) — turn on
 live X search and hosted-document RAG. All verified live on grok-4.5.
-| `ollama/*` | Local Ollama | `lib/models/ollamaLlm.ts` | none | ⚠ omitted + warning |
+
+**Which keys do I need?** `npm run doctor` (the `melchizedek-doctor` bin)
+reads every syndicate YAML, resolves each agent's model under your `.env`,
+and prints one table — agent, model, provider, which declared server-side
+tools that path runs natively (✓) or drops (✗), and whether the path is
+funded — with one verdict per syndicate and the variables that would
+unlock the most. Read-only; no key value is ever printed. Every
+starter-pack file opens with a `# tier:` header (`keyless`, one provider
+such as `gemini`, or `multi-provider`) the doctor checks against the
+models. `GOOGLE_GENAI_API_KEY` alone runs fourteen of the nineteen examples.
+
+**One key instead of several — the gateway fallback.** Direct adapters
+are canonical: the native features above exist only on a provider's own
+endpoint. But with `MODEL_GATEWAY=vercel` (or `openrouter`) and
+`MODEL_GATEWAY_API_KEY` set, any cloud model id whose direct key is
+*absent* is served through that gateway's OpenAI-compatible endpoint
+(`lib/models/gateway.ts` owns the rule). A present provider key always
+wins for its own ids, Ollama never routes through a gateway, and adding a
+direct key later restores that provider's native search with no YAML
+change. Through the gateway every server-side sentinel (`web_search`,
+`google_search`, `x_search`, `collections_search`) is dropped — the doctor
+and the startup log say so per agent, and the span records
+`llm.transport = gateway:<id>` and `llm.capability.dropped` while
+`llm.provider` keeps the upstream attribution. Tool calling, structured
+output, `reasoning_effort` and streaming work unchanged. Optional dials:
+`MODEL_GATEWAY_BASE_URL` (a self-hosted proxy speaking the same dialect),
+`MODEL_GATEWAY_MODEL_MAP` (`from=to,…` wire-name overrides; the mapper
+already turns `claude-sonnet-4-6` into `anthropic/claude-sonnet-4.6`). The
+A2A `X-API-Key` never selects the gateway — the gateway key is server
+environment only.
+
+**Cloud platforms and proxies (ADR 0023).** The model id picks the provider;
+`<PROVIDER>_PLATFORM` picks how it is reached. Keys in the environment against
+the vendor's public API stay the default.
+
+| Path | Set | Credential |
+|---|---|---|
+| Gemini on Vertex AI | `GEMINI_PLATFORM=vertex` (or genai's `GOOGLE_GENAI_USE_VERTEXAI=true`), `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` | Google Application Default Credentials |
+| Claude on Bedrock | `ANTHROPIC_PLATFORM=bedrock`, `AWS_REGION` | the AWS credential chain; needs `@anthropic-ai/bedrock-sdk` |
+| Claude on Vertex AI | `ANTHROPIC_PLATFORM=vertex`, `ANTHROPIC_VERTEX_PROJECT_ID` (or `GOOGLE_CLOUD_PROJECT`), `CLOUD_ML_REGION` | Google ADC; needs `@anthropic-ai/vertex-sdk` |
+| GPT on Azure OpenAI | `OPENAI_PLATFORM=azure`, `AZURE_OPENAI_ENDPOINT` | `AZURE_OPENAI_API_KEY`, else Entra ID through `@azure/identity` |
+| A proxy in front of Anthropic or OpenAI | `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` | the provider's key |
+
+`ANTHROPIC_MODEL_MAP`, `OPENAI_MODEL_MAP` and `GEMINI_MODEL_MAP` (JSON, YAML id
+→ platform id) translate ids a platform names differently: a Bedrock inference
+profile, a Vertex AI version suffix, an Azure deployment name. Unlisted ids pass
+through. The A2A `credentials` plug point may return, per request, an API key
+or a partial endpoint (`baseURL`, `apiKey`, a `token` source, `project`,
+`location`, `region`, `models`) merged over the environment's. Memory
+extraction and embeddings follow the Gemini platform, so a Vertex AI
+deployment needs no AI Studio key.
+
+Native web search is not sent on Bedrock, Claude-on-Vertex or Azure (Gemini
+grounding is kept on Vertex AI); the capability report, the startup log and
+the doctor say so per agent. `npm run doctor` prints one `endpoint` line per
+configured platform with its credential source and anything missing. These
+paths are tested against mocked SDK clients and have **not** been run against
+the live clouds from this repository.
 
 `lib/models/registry.ts` is the single routing seam:
 `registerAvailableProviders()` registers every adapter whose key is
@@ -357,7 +377,8 @@ route through `lib/models/ollamaLlm.ts` to a local Ollama daemon over
 its OpenAI-compatible API (`OLLAMA_BASE_URL`, default
 `http://localhost:11434/v1`). No key is required, and a syndicate whose
 *every* agent is `ollama/*` runs with no `.env` at all —
-`config/agents/examples/tutor.yaml` (single agent) and `council.yaml` (council)
+`config/agents/examples/tutor.yaml` (single agent), `council.yaml` (council)
+and `assistant.yaml` (conversation, summaries, a task list, background jobs)
 are the worked examples. The adapter translates ADK content to
 OpenAI-style messages, including tool calls (so delegation works),
 image parts as data URIs (so `ollama/qwen3-vl:8b` can see), and JSON
@@ -374,13 +395,288 @@ itself; delegation is exercised through AgentTool function calls.
 
 ## 6. A2A service mode
 
-`npm run start:a2a` serves a syndicate as a stateless JSON-RPC
-agent-to-agent endpoint (Express): an agent card describing the service,
-`message/send` for turns, bearer-token auth via `A2A_SERVER_SECRET`, and
-rate limiting. With `PUBLIC_URL` set (a real deployment), the server
-refuses to start without the secret and refuses to run against an
-unhardened database unless explicitly overridden. `demo/a2a_demo.mjs` is
-a complete client.
+`npm run start:a2a -- <file>.yaml` (package: `npx melchizedek-serve
+<file>.yaml`) serves a syndicate as an A2A 1.0 agent that also accepts A2A
+0.3 clients (most platforms still speak 0.3; a request without an
+`A2A-Version` header is treated as 0.3, per the spec): an agent card listing
+both versions' endpoints, JSON-RPC and REST transports, and the task
+lifecycle. In your own Express
+app, mount `(await createA2AApp(options)).app` instead — same server, same
+options. `demo/a2a_demo.mjs` is a complete client.
+
+#### Routes
+
+| Route | Auth | Purpose |
+|---|---|---|
+| `GET /healthz` | none | liveness — always 200 while the process runs |
+| `GET /readyz` | none | readiness — 503 while draining for shutdown |
+| `GET /metrics` | `A2A_METRICS_TOKEN` | Prometheus text: tasks by agent, outcome and caller; model calls; tokens by kind; task duration; tasks in flight. Absent unless the token is set |
+| `GET /.well-known/agent-card.json` | bearer | the default syndicate's card |
+| `POST /a2a/jsonrpc`, `/a2a/rest` | bearer | the default syndicate |
+| `GET /<agentId>/.well-known/agent-card.json` | bearer | another syndicate's card; its URLs point at `/<agentId>/a2a/...` |
+| `POST /<agentId>/a2a/jsonrpc`, `/<agentId>/a2a/rest` | bearer | another syndicate (`A2A_SERVED_AGENTS` restricts which) |
+| `DELETE /memory` | bearer | erase everything stored for the calling scope: facts, sessions (with subagent rows) and ledger rows, with per-store counts; `?all=1` covers every memory namespace |
+
+"bearer" means the credential `A2A_AUTH` asks for (below); with no
+`A2A_SERVER_SECRET` and no authenticator the server binds `127.0.0.1` only.
+In BYOK mode every task route also needs `X-API-Key`. The card declares
+what is required in `securitySchemes`.
+
+#### Who the caller is, and whose data it is
+
+`A2A_AUTH` picks a built-in authenticator (`lib/a2a/identity.ts`, export
+`melchizedek-agents/a2a/identity`), and the authenticator decides the
+scope key every session and memory is stored under:
+
+- **`secret`** (default): every caller presents `A2A_SERVER_SECRET`, and
+  the calling backend names its end user in `X-User-Id`.
+- **`callers`**: one bearer token per calling backend. `A2A_CALLERS` lists
+  `name:sha256[:scope]` entries separated by `;`, so the configuration holds
+  only token hashes. A caller owns its scope (its name, unless one is given),
+  and an `X-User-Id` it sends nests beneath it. The scope does not depend on
+  any model key. Mint a caller with
+  `npx melchizedek-serve --new-caller <name> [--scope <scope>] [--token-file <path>]`.
+  While `A2A_SERVER_SECRET` is still set it keeps working beside the tokens,
+  with its old scoping, so callers move over one at a time.
+- **`jwt`**: a JWT from your identity provider: `A2A_JWT_JWKS_URL` (or an
+  HS256 `A2A_JWT_SECRET`), with `A2A_JWT_ISSUER` and `A2A_JWT_AUDIENCE`
+  required and `exp` checked. The scope is the `sub` claim
+  (`A2A_JWT_SCOPE_CLAIM`), under `A2A_JWT_TENANT_CLAIM` when set.
+  `X-User-Id` is ignored: the token is the user.
+- **`header`**: a gateway in front authenticates users and names them in
+  `A2A_TRUSTED_USER_HEADER`. Requires `A2A_SERVER_SECRET`, which only the
+  gateway may hold, so no other client can set the header.
+
+In code, spread an authenticator into the factory:
+`createA2AApp({ ...callerTokens(parseCallers(spec)), keyMode: 'byok', … })`,
+or pass your own `resolveRequest`.
+
+#### Budgets, the task record, and the ledger
+
+- **Budgets** (`A2A_BUDGETS`, option `policy: budgets(config)`): daily limits
+  per UTC day on tasks, model calls and tokens, per caller (`perCaller`, with
+  overrides by name in `callers`) and per scope (`perScope`, one end user).
+  Example: `{"perCaller":{"tokens":5000000},"callers":{"reports":{"tasks":100}},"perScope":{"tasks":50}}`.
+  A task over budget ends `rejected` with the reason, before it takes a slot.
+  The counts live in the `melchizedek_usage` table (`db/migrations/0004_usage.sql`)
+  when Postgres or Supabase is configured, else in process memory. A store
+  that cannot be read refuses the task.
+- **One record per task** (option `onTaskEnd`): agent, caller, a hash of the
+  scope, status, reason, duration, model calls and tokens.
+  `A2A_LOG_FORMAT=json` prints every server line as JSON, this record included.
+- **Rate limit**: with an authenticator it counts per caller (an operator's
+  backend) or per scope (an end user); under the shared secret, per IP.
+- **The telemetry ledger is redacted before it is written**:
+  `TELEMETRY_REDACT=secret` (default) removes key-shaped credentials; add
+  `email`, `phone`, `card` (Luhn-checked) or `ssn`, or plug in your own with
+  `setTelemetryRedactor(fn)`. Sessions and memory are not redacted; use
+  `DELETE /memory` there.
+
+#### Who pays
+
+`A2A_KEY_MODE` (option `keyMode`), whatever the authenticator:
+
+- **`server`** (default): the server's own provider keys pay for every
+  model call (or your `credentials` plug point supplies a key per request).
+- **`byok`**: the caller's `X-API-Key` funds agents on the provider named
+  by `X-Provider`; agents on other providers, tools and memory extraction
+  still run on the server's keys. Under `A2A_AUTH=secret` only, the key's
+  hash also scopes the data (`a2a-<hash>`, with `X-User-Id` beneath it).
+  That was the only behaviour before 0.16. A deployment holding data from
+  then keeps reaching it with `byok`, or by moving to `A2A_AUTH=callers`
+  with each caller's scope set to its existing `a2a-<hash>` silo.
+
+#### Headers
+
+| Header | Meaning |
+|---|---|
+| `Authorization: Bearer <token>` | the server secret, this caller's token, or a JWT, per `A2A_AUTH` |
+| `X-User-Id` | the end user this request is for (`[A-Za-z0-9._-]{1,64}`); sessions and memory are stored under it (under a caller token, beneath the caller's scope; ignored with a JWT). Authenticate your users before sending it. |
+| `X-API-Key` | BYOK mode only: the caller's model key (see above) |
+| `X-Provider` | BYOK mode only: which provider `X-API-Key` belongs to (default `google`) |
+| `X-Surface`, `X-Surface-Guild`, `-Channel`, `-User` | optional, telemetry only |
+
+#### Sessions
+
+`message.contextId` names the conversation — it goes **inside** `message`.
+Calls with the same value continue one session; a `contextId` beside
+`message` is ignored and every call starts fresh. Sessions are durable with
+Supabase and expire seven days after the last turn (a nightly prune from
+`db/migrations/0001_base.sql` deletes them). A syndicate declaring `memory_system: internal-only` keeps its
+transcripts in process memory even when Supabase is configured.
+
+#### Tasks, streaming, cancel
+
+(Method names below are 0.3's; 1.0 clients use `SendMessage`,
+`GetTask`, `SendStreamingMessage`, `CancelTask` and the 1.0 enum spellings.)
+`message/send` blocks until the turn finishes unless the request sets
+`configuration.blocking: false`; then poll `tasks/get`. `message/stream`
+emits `[STATUS]` progress updates (tool calls, the chosen route, guard
+notes) and the answer as the final status message. With
+`A2A_STREAM_TEXT=true` (`streamText` in code) it also streams the answer as
+the model writes it, as chunks of an artifact named `answer`: the first
+chunk opens it, later chunks append, text the agent wrote before calling a
+tool is withdrawn (an empty replacement), and the artifact is closed
+(`lastChunk`) with the text the user actually receives, which the final
+status message repeats. A syndicate with `guards:` never streams, because a
+guard reads the whole answer before any of it leaves; the dispatch
+classifier never streams either. One conversation runs one turn at a time:
+a second message on a busy `contextId` waits for the first turn (up to
+`A2A_TURN_LOCK_WAIT_MS`, default 30 s) and is then `rejected` with "still
+running". The lock is in-process by default and a Postgres advisory lock
+with `DATABASE_URL`, so it holds across instances. `tasks/cancel` stops a running task, including the model call
+in flight, and the task ends `canceled`. Final states: `completed`,
+`failed` (the message names the stage and the provider's reason),
+`canceled`, `rejected` (a file part, an empty message, or the server at
+capacity). Message parts may be `text` or `data` (sent to the model as
+JSON); `file` parts are refused.
+
+#### Approval gates (`require_approval`)
+
+A tool can run only after a person approves the exact call
+([ADR 0028](./wiki/decisions/0028-approval-gates.md)). The agent lists it:
+
+```yaml
+orchestrator:
+  name: Desk
+  tools: [send_email]
+  require_approval: [send_email]   # names from this agent's own tools
+```
+
+When the model calls it, nothing runs: the task ends `input-required`, final.
+Its status message says what is waiting ("Desk wants to run
+send_email({...})") and carries a data part
+`{ type: 'approval_request', approval_id, agent, tool, args }`. Answer on the
+same conversation (same `contextId`; the same `taskId` works too) with the text
+`approve` or `reject`, or a data part
+`{ "approval": { "id": "<approval_id>", "approved": true } }`. Approved, the
+call runs with the arguments shown; rejected, the model is told and answers
+without it. A message that is not an answer gets the same request back,
+without a model call. ADK pins the call and its arguments, so an approval
+cannot run a different call.
+
+Gates are allowed on the orchestrator and on the subagents of a
+plan-dispatch syndicate, which run as the turn's own agent. A delegated
+subagent runs inside a tool call, where a pause cannot reach the caller, so a
+gate there is a load error, as is any gate inside a nested `yaml_reference`
+syndicate. Only function tools from the registry can be gated, not MCP tools
+or native-search sentinels. In code, `runSyndicateTurn` returns
+`status: 'input-required'` with `approval`, and the next turn's part
+`approvalResponsePart(approval.id, approved)` answers it.
+
+#### Limits
+
+| Setting | Default |
+|---|---|
+| `A2A_RATE_LIMIT_MAX` per `A2A_RATE_LIMIT_WINDOW_MS`, per client IP (POSTs) | 60 per 15 min |
+| `A2A_AUTH_FAILURE_MAX` failed logins per IP per 15 min, then blocked | 30 |
+| `A2A_TASK_TIMEOUT_MS` per task | 15 min |
+| `A2A_MAX_CONCURRENT_TASKS` | unlimited |
+| `max_steps` (YAML): model calls per turn, subagents included | none |
+| `A2A_BODY_LIMIT` | 1 MB |
+| `A2A_SHUTDOWN_GRACE_MS`: SIGTERM waits for running tasks | 25 s |
+
+The rate limit and the failed-login limit count in the process by default,
+so each replica keeps its own window. With `A2A_REDIS_URL` set (and the
+optional `redis` package installed) both count in Redis, one window across
+every replica; in code, pass `limitStore` with
+`redisRateLimitStore({ command })` from `melchizedek-agents/a2a/limits`, which
+takes any client's raw-command function (node-redis `sendCommand`, ioredis
+`call`). Budgets need no Redis: they are Postgres counters.
+
+#### What is per-process
+
+The per-agent config cache (a config change needs a restart), the
+rate-limit counters and the concurrency count always live in the process. Tasks do too unless `DATABASE_URL` is set: then
+Postgres holds sessions, memory, A2A tasks and budget counters, and several
+replicas are safe behind one load balancer (rate limits and the concurrency
+cap then apply per replica, unless `A2A_REDIS_URL` shares the rate limits).
+With Postgres, a running task is leased to the
+instance running it (renewed every 20 s; `taskLeaseMs`, default 60 s): if
+that instance dies, another marks the task `failed` ("the server running
+this task stopped") instead of a client polling it forever, and one turn
+runs at a time per conversation across replicas. With Supabase only, or no
+store, run one replica.
+
+#### Posture at boot
+
+Without `A2A_SERVER_SECRET` the server binds `127.0.0.1` only; binding
+another `HOST` requires the secret or `ALLOW_UNAUTHENTICATED=true`. With
+`PUBLIC_URL` set it refuses to start without the secret, with the
+`.env.example` placeholder as the secret, or against an unhardened
+database (unless `ALLOW_UNHARDENED_DB=true`). With durable storage it reads
+`melchizedek_schema_version` and refuses to start on a database behind the
+migrations it ships, naming `melchizedek-db apply` (or
+`ALLOW_SCHEMA_MISMATCH=true` to start anyway); a database ahead of it only
+warns, so a rolling deploy can migrate first. Storage through supabase-js
+(Supabase credentials without `DATABASE_URL`) logs a deprecation notice:
+set `DATABASE_URL` to the database's Postgres connection string.
+Conversation content is not printed to stdout unless
+`OTEL_CONSOLE_SPANS=true`.
+
+#### Calling remote agents
+
+A subagent with `a2a_agent_url: https://other-team.example/billing` is a
+REMOTE agent, speaking A2A 1.0 or 0.3 (the card decides): the orchestrator
+delegates to it as to a local subagent (one `request` argument), and in
+plan-dispatch it can be a route. Its card and
+endpoint pass the SSRF guard (`ALLOW_PRIVATE_A2A=true` for local hosts);
+credentials come from `A2A_AGENT_TOKENS`, a JSON map of host → bearer
+token or host → headers, sent only over https (or to loopback). The same
+local conversation keeps talking to the same remote conversation.
+
+#### Deploying
+
+`Dockerfile` builds the compiled server and runs it as a non-root user with
+a health check; `compose.yaml` adds optional Ollama and Phoenix (traces).
+`npx melchizedek-db print|apply|status` installs and checks the database.
+Set `PUBLIC_URL`, `A2A_SERVER_SECRET` and the provider keys from your
+secret manager; give the orchestrator's stop timeout at least
+`A2A_SHUTDOWN_GRACE_MS`.
+
+#### The agent registry
+
+A file is the default home of a syndicate. The registry is for a definition
+an operator changes without a redeploy: `registry:<id>` loads it, and so does
+a bare id listed in `A2A_REGISTRY_AGENTS`. It lives in two tables (migration
+`0005_agent_registry.sql`):
+
+- `adk_agent_registry` — one row per id, the active definition. The server
+  reads only this table.
+- `adk_agent_registry_versions` — every definition an id has held, numbered
+  per id, with its config hash, author, note and publish time. It is
+  append-only: updates and deletes are refused.
+
+The database records a version on every write to the active table, whoever
+makes it, so history does not depend on the tool. Writing a definition an id
+already held re-activates that version rather than duplicating it, which is
+how a rollback works.
+
+```bash
+npx melchizedek-registry publish config/agents/desk.yaml desk --note "tighter triage"
+npx melchizedek-registry versions desk        # * marks the active version
+npx melchizedek-registry diff desk 3          # v3 against the active version
+npx melchizedek-registry rollback desk 3 --note "v4 misroutes refunds"
+npx melchizedek-registry retire desk --yes    # stop serving; history stays
+```
+
+`publish` and `rollback` validate against the same schema the loader uses
+before anything is written. The author recorded is
+`MELCHIZEDEK_REGISTRY_AUTHOR`, else the local user name; a direct write
+records the database role. `registry:<id>@<version>` loads one stored
+version (as the boot syndicate or from code), so a version can be tried
+before it is activated; the HTTP routes accept only active ids. A running
+server caches each agent for its lifetime: **restart it after a publish or
+a rollback.** The library is `melchizedek-agents/registry`.
+
+A syndicate is versioned as a unit. `publish` reads every nested
+`yaml_reference` the definition reaches (nested ones of nested ones too) from
+the agents root, validates each, and stores them with it under
+`bundled_references`; the server loads nested syndicates of that version from
+the bundle, never from files that may have changed since. Change a nested file
+and the parent changes only when it is published again. `--no-bundle` stores
+the references bare, to resolve from files at run time; a version published
+before bundling existed behaves that way too.
 
 ### Plan-dispatch routing (`dispatch:`) — the second orchestration method
 
@@ -527,22 +823,46 @@ interface, register it behind a model-id prefix.
 subagent. `scripts/demo_mcp_server.ts` is a complete server to copy —
 tool definitions, SSE wiring, and persistent state in ~250 lines.
 
+**Teach your coding agent the framework**: `skills/` holds six Agent
+Skills (the open SKILL.md standard — a directory per skill, `name` and
+`description` frontmatter) that give Claude Code, Codex, Cursor,
+OpenCode or Gemini CLI the catalog of syndicates and the procedures in
+this document: `melchizedek` (find and run, delegate a task),
+`melchizedek-author`, `melchizedek-serve`, `melchizedek-memory`,
+`melchizedek-models`, `melchizedek-scribe`. `npx melchizedek-skills
+install` copies them into `.claude/skills/` and `.agents/skills/` of the
+current project (`--for claude,codex,cursor,opencode,gemini,agents,all`,
+`--global`, `--dir <path>`, `--only <names>`, `--force`, `--dry-run`;
+`npm run skills:install` in a clone). The installer (`lib/skills.ts`)
+copies only from the package's own `skills/` directory, follows no
+symlinks, and never overwrites a differing file without `--force`. Each
+SKILL.md body was written by the Scribe syndicate
+(`config/agents/examples/scribe.yaml`) from a brief of facts and reviewed
+by a person; `skills/README.md` records the procedure.
+
 ## 8. Security notes
 
 - **Secrets** live in `.env` only; `.env.example` documents every
-  variable. Nothing in the repo ships a key.
+  variable and ships no values (placeholders are ignored if copied in).
+  Nothing in the repo ships a key. Report vulnerabilities per SECURITY.md.
 - **Database**: default Supabase leaves `public`-schema tables readable
   by the anon key over REST. `db/hardening.sql` enables deny-by-default
   RLS and revokes anon/authenticated privileges on every table it finds:
   `adk_sessions`, `adk_memory_facts`, and — where they exist — the
-  optional `adk_telemetry` sink and `adk_agent_registry` (an unprotected
-  registry is worst of all: agent definitions writable with the anon key
+  optional `adk_telemetry` sink and `adk_agent_registry` with its version
+  history (an unprotected registry is worst of all: agent definitions writable with the anon key
   means anyone can rewrite the instructions your server boots). The A2A
   server verifies hardening at boot and is fatal on public deployments
   without it. Note `service_role` bypasses RLS by design — the hardening
   constrains the API surface, not the trusted server.
-- **A2A**: bearer auth + rate limiting are built in; set
-  `A2A_SERVER_SECRET` before exposing anything.
+- **A2A**: bearer auth, a failed-login limiter and a request rate limit
+  are built in; without `A2A_SERVER_SECRET` the server binds loopback only.
+  See §6 for the posture checks at boot.
+- **Outbound fetches** (`web_extract`, MCP servers, remote A2A agents) pass
+  one SSRF guard (`lib/net/addressGuard.ts`): local names and non-public
+  addresses in every encoding are refused, and names are resolved and
+  refused when any address is non-public. DNS rebinding between the check
+  and the connection is the remaining, stated limit.
 - **Image tools** write only under `outputs/`, and `inspect_image` reads
   only from there.
 - **MCP** is an outbound trust decision: `mcpToolFactory` blocks