melchizedek-agents 0.17.0 → 0.19.0

package/DOCUMENTATION.md

@@ -28,8 +28,10 @@ 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)
 lib/toolRegistry.ts       tool name → live ADK tool instance
-lib/models/claudeLlm.ts   Claude adapter registered into the ADK registry
+lib/models/claudeAdapter.ts  Claude on the engine's model contract
+lib/models/claudeLlm.ts   that adapter behind the ADK shim, in the ADK registry
 lib/models/ollamaLlm.ts   open-weight local adapter (Ollama, keyless)
+lib/models/chatCompletionsAdapter.ts  the chat-completions wire on the model contract
 lib/tools/mcpToolFactory.ts  MCP client: remote tools → live ADK tools
 scripts/demo_mcp_server.ts   demo MCP server (library catalog, SSE)
 lib/session/…             Supabase-backed session service
@@ -52,6 +54,21 @@ subagents as `AgentTool`s and tool names through the registry → the ADK
 on session end, the memory service distills the transcript into tagged
 facts, embeds them (768-d), and stores them for future recall.
 
+The compiler (`lib/compile.ts`) first builds a runtime-neutral `AgentSpec`
+per agent; `lib/compileAdk.ts` turns it into the `LlmAgent`, and
+`lib/compileNative.ts` into the engine's own loop's agent. ADK runs every
+turn by default. `MELCHIZEDEK_RUNTIME=native`, or `runtime: 'native'` on
+`runSyndicateTurn`, runs a single-agent, delegating or plan-dispatch
+syndicate on the native loop with the same result and the same stored
+events, `context:` compaction and `mode: task` included
+([ADR 0078](./wiki/decisions/0078-native-compaction-ports-adk-compactor.md)),
+and a `workflow:` syndicate on the engine's own scheduler, its pause and
+resume included
+([ADR 0095](./wiki/decisions/0095-native-workflow-turn-drains-through-the-adk-reader.md));
+what it does not run yet throws `UnsupportedOnRuntimeError` before any
+model call
+([ADR 0073](./wiki/decisions/0073-one-agent-spec-and-a-runtime-flag.md)).
+
 ## 2. The syndicate YAML
 
 Minimal complete example:
@@ -72,11 +89,9 @@ orchestrator:
     You are the Conductor… (persona, objective, workflow contract)
   tools:
     - "google_search"             # names resolved via lib/toolRegistry.ts
+  reasoning: medium               # none | low | medium | high, or { budget_tokens: 4096 }
   generateContentConfig:
     maxOutputTokens: 4096
-    thinkingConfig:
-      thinkingLevel: "MEDIUM"     # or thinkingBudget on older models
-      includeThoughts: true
 
 subagents:
   - name: "Researcher"
@@ -104,19 +119,22 @@ Field reference:
 | `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. |
+| `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). Unset, each adapter keeps its own default. |
+| `generateContentConfig` | agent | Temperature, output caps. Its `thinkingConfig` and `reasoningEffort` are the older, provider-specific spelling of `reasoning`; setting either next to `reasoning` is a load error. |
 | `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. |
+| `fallback_model` | any agent | A model, ideally on another provider, that answers when this agent's model fails provider-side (5xx, 429, a connection reset, after its own retries) before producing any output, or while that provider's circuit is open: after `MODEL_BREAKER_THRESHOLD` consecutive provider failures (default 5; 0 disables) the provider is skipped for `MODEL_BREAKER_COOLDOWN_MS` (default 30 s). A 4xx and a canceled turn are never redirected, and a stream that already produced text is never replayed elsewhere ([ADR 0044](./wiki/decisions/0044-fallback-model-and-circuit-breaker.md)). |
+| `mcp_tools` | subagent | The MCP server's tools this agent may use; any other tool the server lists is not exposed. On a dispatch route `require_approval` may name them ([ADR 0041](./wiki/decisions/0041-tool-vendors-get-least-privilege.md)). |
 | `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. |
 | `openapi` | any agent | HTTP APIs as tools, each from an OpenAPI 3 spec file (§3, OpenAPI tools): `spec`, and optionally `operations` (default: the GET operations only), `auth` (from environment variables), `base_url`, `prefix`. |
 | `code_execution` | any Gemini agent | `"gemini"`: the model writes Python and Gemini runs it in Google's server-side sandbox, returning the output to the model; nothing runs on this host. For arithmetic, data and checks a model gets wrong in its head. Gemini models only ([ADR 0033](./wiki/decisions/0033-context-task-code.md)). |
 | `context` | orchestrator | Compacts a long conversation: when the last request's prompt passed `compact_after_tokens`, earlier turns become one summary (written by `summary_model`, default the agent's own) and the last `keep_recent_events` stay verbatim. The full history stays stored; only what the model reads shrinks. The orchestrator of a delegate syndicate only: a dispatch route already reads a bounded projection, a workflow node sees only its input. |
 | `mode` | workflow node | `"task"`: the agent works with its tools until it calls `finish_task`, whose arguments (matching its `outputSchema`) become the node's output. Workflow nodes only. |
-| `examples` | any agent | Few-shot exchanges, `[{ input, output }]` (up to 20), added to every request's instruction by ADK's `ExampleTool`; the model never calls it. Keeps worked examples out of the prose of `instruction`. |
-| `skills` | any agent | Agent Skills (a directory of SKILL.md folders) the agent holds the way a coding harness does: every skill's name and description is appended to its instruction at compile time; `load_skill` reads one in full with the names of its files, `load_skill_resource` reads one file. `scripts: local` adds `run_skill_script`, which runs a skill's own scripts on this machine, each after a person approves (the `require_approval` pause); `tools:` names registry tools a skill's `allowed-tools` may unlock once loaded. Worked example: `examples/harness.yaml`; engine: `lib/tools/skillToolset.ts`. |
+| `examples` | any agent | Few-shot exchanges, `[{ input, output }]` (up to 20), added to every request's instruction as a few-shot block, the one ADK's `ExampleTool` wrote (an Instruction tool, `lib/tools/examples.ts`); the model never calls it. Keeps worked examples out of the prose of `instruction`. |
+| `skills` | any agent | Agent Skills (a directory of SKILL.md folders) the agent holds the way a coding harness does: every skill's name and description is appended to its instruction at compile time; `load_skill` reads one in full with the names of its files, `load_skill_resource` reads one file. `scripts: local` adds `run_skill_script`, which runs a skill's own scripts on this machine, each after a person approves (the `require_approval` pause), with PATH, HOME, the temp directory and the locale but none of the server's keys, plus the variable names listed under `env:` (or `secret_env:` for a secret-shaped name, ADR 0086), and stdout and stderr each cut at 20,000 characters; `tools:` names registry tools a skill's `allowed-tools` may unlock once loaded. Worked example: `examples/harness.yaml`; engine: `lib/tools/skillToolset.ts` over `lib/tools/skills/`, the same on both runtimes. |
 
 Validation happens at load: missing names, legacy option blocks, and
 malformed agents fail with pointed errors before any model is called.
@@ -126,28 +144,37 @@ skipped with a warning at compile time.
 ## 3. Tools
 
 Registered in `lib/toolRegistry.ts` — one map from YAML name to ADK tool
-instance:
+instance. A **Contract** is the engine's own Tool (`lib/tools/tool.ts`),
+defined once with `defineTool` and handed to the ADK runtime as a
+`FunctionTool` by `toFunctionTool` (`lib/tools/adkTool.ts`). An
+**Instruction tool** is the engine's own too: it declares no function and
+only writes into each request's instruction, reaching the ADK runtime
+through `toAdkInstructionTool`. A **server-side tool** is an own marker
+(`lib/tools/nativeTools.ts`) that names the provider's tool and declares no
+function; the ADK runtime runs its sentinel (`toAdkNativeTool`), and every
+adapter recognises it by marker ([ADR 0062](./wiki/decisions/0062-server-side-tools-as-markers.md)):
 
 | Name | Kind | Does |
 |---|---|---|
 | `web_search` | Provider-agnostic | Live web search via the agent model's NATIVE search: Gemini grounding, Anthropic `web_search` server tool, OpenAI Responses `web_search`, xAI Agent Tools `web_search`. On local `ollama/*` models, and on `kimi-*` (Moonshot's model-side search retires 2026-10-20; its successor is a REST API, not a request field), the tool is omitted with a one-time warning (keyless stays keyless). On grok-* agents, optional server-side domain filters via `XAI_WEB_SEARCH_ALLOWED_DOMAINS` / `_EXCLUDED_DOMAINS` in `.env` (max 5, mutually exclusive; xAI accepts no date bounds — those are `x_search`-only). Prefer this in new YAMLs. |
-| `web_extract` | FunctionTool | Deterministic page reading: fetches 1–5 agent-chosen URLs and returns clean page text (no LLM summarization). Keyless — works on every provider including local `ollama/*`. Per-page char budget (default 15k, `WEB_EXTRACT_CHAR_LIMIT`); long pages return a head+tail window with an `offset` continuation call served from a 15-minute cache. SSRF-guarded (http(s) only, private/link-local hosts refused, redirects re-checked). Block pages (bot checks, paywall stubs, JS shells) are detected code-side and returned as labeled `Error:` blocks, never as content. Pair with `web_search`: search to find, extract to read past the headline. |
+| `web_extract` | Contract | Deterministic page reading: fetches 1–5 agent-chosen URLs and returns clean page text (no LLM summarization). Keyless — works on every provider including local `ollama/*`. Per-page char budget (default 15k, `WEB_EXTRACT_CHAR_LIMIT`); long pages return a head+tail window with an `offset` continuation call served from a 15-minute cache. SSRF-guarded (http(s) only, private/link-local hosts refused, redirects re-checked). Block pages (bot checks, paywall stubs, JS shells) are detected code-side and returned as labeled `Error:` blocks, never as content. Pair with `web_search`: search to find, extract to read past the headline. |
 | `x_search` | xAI-only | Live search over X (Twitter) posts via xAI Agent Tools. Self-gates to `grok-*` agents; a silent no-op on every other provider, so mixed-provider YAMLs stay safe. Optional server-side constraints in `.env`: `XAI_X_SEARCH_FROM_DATE`/`_TO_DATE` (inclusive `YYYY-MM-DD`) and `_ALLOWED_HANDLES`/`_EXCLUDED_HANDLES` (max 20, mutually exclusive — allowlist wins). |
 | `collections_search` | xAI-only | Semantic search over xAI **Collections** — hosted document stores (PDFs/text/CSVs) uploaded at console.x.ai — server-side RAG with `collections://…` citations. Which collections: `XAI_COLLECTION_IDS` in `.env` (optional `XAI_COLLECTIONS_MAX_RESULTS`). Declared with no ids → omitted with a warning; non-xAI providers → silent no-op. |
 | `url_context` | Gemini built-in | Gemini reads the pages at URLs in the conversation, server-side (Google fetches them, not this host). On any other provider it is a no-op the doctor reports as dropped; use `web_extract` there. |
 | `google_search` | ADK built-in | Live web search — Gemini agents only (legacy alias; use `web_search`). |
-| `preload_memory` | ADK built-in | Silently injects similarity-matched facts into every request (ambient recall). |
-| `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. |
-| `ask_user` | LongRunningFunctionTool | Asks the person one question (optionally with `options`) and ends the turn `input-required`; the next message on the conversation is the call's result. Orchestrator or plan-dispatch route only (§6, Questions). |
-| `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. |
+| `preload_memory` | Instruction tool | Silently injects similarity-matched facts into every request's instruction (ambient recall). The model never calls it. |
+| `load_memory` | Contract | Explicit tool call to search the fact store (deliberate recall). Both memory tools read the caller's own silo only and send the model what ADK's tools of the same names sent ([ADR 0059](./wiki/decisions/0059-memory-on-the-engines-own-interfaces.md)). |
+| `generate_image` | Contract | Calls the Gemini image model directly, saves the result under `outputs/`, returns the path. A function tool because binary `inlineData` cannot survive the AgentTool text boundary. |
+| `inspect_image` | Contract | **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` | Contract | 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. |
+| `ask_user` | Contract, long-running | Asks the person one question (optionally with `options`) and ends the turn `input-required`; the next message on the conversation is the call's result. Orchestrator or plan-dispatch route only (§6, Questions). |
+| `task_queue` | Contract | 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
 load time. `lib/tools/mcpToolFactory.ts` dials the server over SSE,
-lists its tools, and wraps each one as a live `FunctionTool` — the
+lists its tools, and makes each one an own Tool (`loadMcpTools`), which
+the ADK runtime runs as a `FunctionTool` (`createMcpTools`) — the
 agent's reach is decided by the server, not compiled in.
 `config/agents/examples/librarian.yaml` plus the demo catalog server
 (`npm run mcp:demo`, `scripts/demo_mcp_server.ts`) are the worked
@@ -158,8 +185,10 @@ treat any remote MCP server as an untrusted tool vendor whose results
 are data, never instructions.
 
 **OpenAPI tools** turn any HTTP API with an OpenAPI 3 spec into an
-agent's tools, with no tool code (`lib/tools/openapiTools.ts`, on ADK's
-`OpenAPIToolset`; [ADR 0032](./wiki/decisions/0032-openapi-tools.md)):
+agent's tools, with no tool code (`lib/tools/openapiTools.ts`, on the
+engine's own parser and caller in `lib/tools/openapi/`;
+[ADR 0032](./wiki/decisions/0032-openapi-tools.md),
+[ADR 0067](./wiki/decisions/0067-openapi-calls-on-the-engines-own-caller.md)):
 
 ```yaml
 orchestrator:
@@ -180,11 +209,18 @@ writes is exposed only by naming it, and a named operation can be listed
 under `require_approval` (as written under `operations`) so a person
 approves each call. `auth` names an environment variable, never a value
 (`bearer_env`, or `api_key` with `in: header | query` and `name`); an unset
-variable fails the compile, and a static token is applied to the request,
+variable fails the compile, and so does one of the framework's own settings
+(the database URL, a provider key, an `A2A_` secret: anything `.env.example`
+documents), since the YAML chooses the host it goes to.
+`OPENAPI_CREDENTIAL_ENVS`, when set, is the exact list of variables an `auth`
+may name. A refused or unset variable fails the compile, and a static token is applied to the request,
 never stored in session state. Every server must be http(s) and pass the
 SSRF guard: its literal rules when the agent compiles, the full check with
 DNS before each call; `ALLOW_PRIVATE_OPENAPI=true` permits private hosts for
-local development. A response over 20,000 characters is cut and says so; a
+local development. Redirects are followed one hop at a time, each hop held
+to the guard, and a hop to another origin carries no credential. A
+credential's value never appears in an error the model reads. Only OpenAPI
+3.x specs are read. A response over 20,000 characters is cut and says so; a
 network failure comes back to the model as an error. Specs are files, never
 URLs: save the spec beside the YAML and review it like code (trim it to the
 operations the agent needs, and write each `summary` for the model). Worked
@@ -223,7 +259,11 @@ 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.
+them is also the upgrade path from any earlier layout. `apply` runs the whole
+install as one transaction under an advisory lock: if any statement fails,
+nothing is changed, and two applies started together run one after the other.
+Rolling back a migration that succeeded is a restore from backup (§6), since
+the migrations only move forward.
 
 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
@@ -301,12 +341,12 @@ accordingly — model optionality is a single YAML line per agent:
 | Model id | Provider | Adapter | Key | Native `web_search` |
 |---|---|---|---|---|
 | `gemini-*` | Google Gemini | ADK-native (`TracedGemini`) | `GOOGLE_GENAI_API_KEY` | ✅ grounding |
-| `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 |
-| `kimi-*` | Moonshot AI (Kimi) | `lib/models/kimiLlm.ts` (chat completions) | `MOONSHOT_API_KEY` | ⚠ omitted + warning |
-| `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 |
+| `claude-*` | Anthropic | `lib/models/claudeAdapter.ts` (Messages API; `ClaudeLlm` is its ADK shim) | `ANTHROPIC_API_KEY` | ✅ server tool |
+| `gpt-*`, o-series | OpenAI | `lib/models/gptLlm.ts` around `gptAdapter.ts` (Responses API) | `OPENAI_API_KEY` | ✅ web_search tool |
+| `grok-*` | xAI | `lib/models/grokLlm.ts` around `grokAdapter.ts` (Responses API) | `XAI_API_KEY` | ✅ Agent Tools search |
+| `kimi-*` | Moonshot AI (Kimi) | `lib/models/kimiLlm.ts` around `kimiAdapter.ts` (chat completions) | `MOONSHOT_API_KEY` | ⚠ omitted + warning |
+| `ollama/*` | Local Ollama | `lib/models/ollamaLlm.ts` around `ollamaAdapter.ts` (chat completions) | none | ⚠ omitted + warning |
+| *any cloud id whose direct key is absent* | the id's own provider, via a gateway | `lib/models/gatewayLlm.ts` around `gatewayAdapter.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
@@ -316,8 +356,9 @@ 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.
 
-**Moonshot AI (Kimi).** `kimi-*` ids route to `lib/models/kimiLlm.ts`, a
-subclass of the chat-completions base, against `https://api.moonshot.ai/v1`
+**Moonshot AI (Kimi).** `kimi-*` ids route to `lib/models/kimiLlm.ts`, the
+ADK shim around `KimiAdapter` (`lib/models/kimiAdapter.ts`, on the
+chat-completions base), against `https://api.moonshot.ai/v1`
 (`MOONSHOT_BASE_URL` for a proxy). Get a key at platform.moonshot.ai; the
 `.cn` console serves mainland China. The family (USD per 1M tokens, October
 2026): `kimi-k3`, the flagship — 2.8T-parameter open-weight MoE, 1M context,
@@ -338,11 +379,12 @@ document it; K2.6 is unstable on `$ref`/`oneOf`), SSE streaming, images as
 base64 (Moonshot takes no public image URLs), MCP tools (they are function
 tools to the model), `reasoning_content` surfaced as THINKING. Reasoning:
 K3 takes a top-level `reasoning_effort` (`low` | `high` | `max`); the adapter
-pins `DEFAULT_KIMI_REASONING_EFFORT` (`high`, `lib/config.ts`) unless
-`generateContentConfig.reasoningEffort` says otherwise, and maps `none` to
-`low` because K3 cannot stop thinking. K2.x models take a `thinking:
-{ type }` switch instead: `reasoningEffort: "none"` or `thinkingBudget: 0`
-sends `disabled`, and any effort value is dropped from the body. What does
+pins `DEFAULT_KIMI_REASONING_EFFORT` (`high`, `lib/config.ts`) unless the
+agent's `reasoning:` says otherwise (`medium` is sent as `high`, which K3
+has in its place), and maps `none` to `low` because K3 cannot stop
+thinking. K2.x models take a `thinking: { type }` switch instead:
+`reasoning: none` sends `disabled`, and any effort value is dropped from
+the body. What does
 not: native `web_search` (dropped with a warning; `web_extract` works, and
 Moonshot's standalone `POST /v1/tools/search`, billed per call, could back
 a client-side tool), and thinking carried across a tool loop (Moonshot asks
@@ -426,13 +468,64 @@ prompt to every available provider, printing input, thinking (qwen3
 `<think>` blocks, Claude extended thinking, GPT reasoning summaries,
 Grok reasoning, Kimi reasoning_content), output, and a per-request token/latency trace; add
 `-- --search` to watch four native web searches plus the local
-omission. Providers without keys are skipped, never fatal.
+omission. Providers without keys are skipped, never fatal. Each agent
+runs as a one-agent syndicate through `runSyndicateTurn`, so
+`MELCHIZEDEK_RUNTIME=native npm run demo:models` runs the same demo on
+the engine's own loop.
 
 Reasoning/thinking: scratchpads from every provider are surfaced as
-dimmed THINKING output and kept out of session history. On Claude,
-`generateContentConfig.thinkingConfig.thinkingBudget` enables
-Anthropic extended thinking (thinking + tool use on the same Claude
-agent is not supported yet).
+dimmed THINKING output and kept out of session history. On Claude, any
+`reasoning:` other than `none` (or the older
+`generateContentConfig.thinkingConfig.thinkingBudget`) enables Anthropic
+extended thinking, tools included: the signed thinking blocks ride on the
+response's parts as `providerState` and are replayed verbatim within the
+turn's tool loop (ADR 0046). GPT's reasoning ids (o-series, `gpt-5*`) and
+`grok-4.5`, `grok-4.6` and `grok-4.7` do the same with their encrypted
+reasoning items.
+Their requests send `store: false`, so the vendor keeps no copy of the
+response (ADR 0050).
+
+The engine's own model contract is `lib/models/contract.ts` (ADR 0048),
+importable as `melchizedek-agents/models/contract`. It defines the message
+format, request, response stream and adapter interface of the native
+runtime (ADR 0045), with no `@google/*` in its import graph, and the
+adapters move onto it in stages. `wiki/models/model-contract.md` gives
+each field's purpose and its mapping onto every provider's wire. While ADK
+runs the turn, an adapter on the contract runs behind `AdkShim`
+(`melchizedek-agents/models/adkShim`), an ADK `BaseLlm` that charges each
+call against `max_steps`, passes the turn's abort signal and opens the
+`llm.request` span, as the ADK-path adapters do (ADR 0053).
+GPT and Grok run on the contract already: `GptLlm` and `GrokLlm` are that
+shim around `GptAdapter` (`melchizedek-agents/models/gptAdapter`) and
+`GrokAdapter` (`melchizedek-agents/models/grokAdapter`), and keep the token
+counts and server-side tool record the ledger has always had for them
+(ADR 0056).
+Gemini has two adapters on the contract:
+`melchizedek-agents/models/geminiAdapter` (`GeminiAdapter`, on
+`@google/genai` with no ADK) and, until that one passes its live parity
+run, `melchizedek-agents/models/adkGeminiAdapter` (`AdkGeminiAdapter`,
+a temporary wrapper that runs the request through `TracedGemini`, now in
+`melchizedek-agents/models/tracedGemini`).
+`resolveAdapter(modelId, { apiKey, keyProvider, endpoint, gemini })` in
+`melchizedek-agents/models/registry` returns any id's contract adapter
+from the same prefix table, gateway rule, BYOK scoping and endpoints as
+`resolveModel`, with no ADK registry (ADR 0060). A Gemini id gets
+`AdkGeminiAdapter` unless `GEMINI_ADAPTER=engine` (or `gemini: 'engine'`)
+asks for `GeminiAdapter`. `resolveAdapterWithFallback` wraps an agent's
+model and `fallback_model` in a `FallbackAdapter`.
+
+`melchizedek-agents/model` is the model layer on its own, with no
+`@google/adk` in its import graph (ADR 0068): the contract's types,
+`ClaudeAdapter`, `GptAdapter`, `GrokAdapter`, `KimiAdapter`,
+`OllamaAdapter`, `GatewayAdapter`, `GeminiAdapter`, the
+`ChatCompletionsAdapter` base, `resolveAdapter`,
+`resolveAdapterWithFallback`, `FallbackAdapter` and the circuit breaker's
+helpers. A project that only calls models installs the package without ADK
+and imports from there. Its `resolveAdapter` gives a Gemini id
+`GeminiAdapter`; asking it for `adk` (`gemini: 'adk'` or
+`GEMINI_ADAPTER=adk`) throws and names `melchizedek-agents/models/registry`,
+whose `resolveAdapter` keeps the ADK default above. `AdkGeminiAdapter`, the
+ADK shims, `TracedGemini` and `resolveModel` are not in it.
 
 Every model request also emits an `llm.request` OpenTelemetry span
 (provider, model, input/output/thinking tokens, latency). Scripts print it
@@ -451,7 +544,14 @@ full-text `search` column; `adk_telemetry` — one row per `llm.request` /
 root span; and `adk_payloads` — full prompts and responses per model call,
 kept by policy (`TELEMETRY_PAYLOADS=off|errors|sample|all`,
 `TELEMETRY_PAYLOAD_SAMPLE`, `TELEMETRY_PAYLOAD_TTL_DAYS`) and expired by
-`melchizedek_prune_telemetry()`. The view `adk_turns_production` excludes
+`melchizedek_prune_telemetry()`. A row from a failed call's `llm.request`
+span holds the request in the model contract's shape (`model`, `system`,
+`messages`, `tools`, …), whichever adapter made the call; a row from ADK's
+own `call_llm` span holds ADK's request. On the native runtime the loop
+opens `agent.invoke <name>`, `model.call` and `tool.execute <name>` spans
+where ADK opens `invoke_agent`, `call_llm` and `execute_tool`, and the ledger
+reads both (ADR 0076); a clean call's row then comes from `model.call` and
+holds the request and the adapter's response in the contract's shapes. The view `adk_turns_production` excludes
 eval and classifier turns. Operate it with `npm run telemetry:stats`,
 `telemetry:prune` and `telemetry:replay` (the exporter spools failed
 batches to `outputs/telemetry-deadletter.ndjson`).
@@ -499,7 +599,7 @@ options. `demo/a2a_demo.mjs` is a complete client.
 | `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), ledger rows and A2A tasks, including conversations whose sessions have expired, with per-store counts; `?all=1` covers every memory namespace |
+| `DELETE /memory` | bearer | erase everything stored for the calling scope: facts, sessions (with subagent rows), ledger rows, A2A tasks and the third-party tokens held for its tools, including conversations whose sessions have expired, 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.
@@ -545,9 +645,30 @@ or pass your own `resolveRequest`.
   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.
+- **One record per task** (option `onTaskEnd`): task id, trace id, agent,
+  caller, a hash of the scope, status, reason, duration, model calls and
+  tokens. The trace id is the one the turn's spans and its ledger row carry,
+  and the audit trail's `task.end` row names both ids, so one id joins the
+  log, the ledger, the audit trail and your tracing backend. A request
+  carrying a W3C `traceparent` header is linked, not joined: the turn's root
+  span links to the caller's span and records `caller.trace_id`, and the
+  record carries `callerTraceId`. The turn keeps a trace id of its own, since
+  ledger attribution and erasure key on it and a caller must not choose it.
   `A2A_LOG_FORMAT=json` prints every server line as JSON, this record included.
+- **The audit trail** (`melchizedek_audit`, `db/migrations/0012_audit_log.sql`;
+  option `audit`, supplied by `postgresStorage`): one row per failed
+  authentication (`auth.failure`), task outcome (`task.end`), erasure
+  (`memory.erase`) and tool credential stored, refreshed, revoked or erased
+  (`credential.put`, `.refresh`, `.revoke`, `.erase`, naming the provider and
+  app, never a token), with the caller's name, the source address, the agent and
+  task ids, and a hash of the scope. Never a scope key and never conversation
+  content. A trigger refuses UPDATE and DELETE; rows leave only through
+  `SELECT melchizedek_prune_audit(<days>)`, which you schedule (pg_cron, or a
+  job) for the retention your evidence needs, since the source address is
+  personal data. A failed write is logged once and each event is printed to
+  stderr as JSON until writes recover. A database owner can still alter the
+  table; ship the rows to a store you do not administer when the evidence must
+  survive that.
 - **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**:
@@ -556,6 +677,31 @@ or pass your own `resolveRequest`.
   `setTelemetryRedactor(fn)`. Sessions and memory are not redacted; use
   `DELETE /memory` there.
 
+#### Where your data goes
+
+What a deployment sends where, how long it is kept, and the setting that
+changes it. "Your Postgres" is the database `DATABASE_URL` (or Supabase)
+names; nothing is kept by the framework anywhere else.
+
+| Data | Goes to | Kept | Change it with |
+|---|---|---|---|
+| The prompt: the user's message, the conversation, tool results | The model provider of each agent that runs (the model-id prefix) | The provider's policy | The `model:` lines in the YAML; `ollama/` ids stay on your machine |
+| Tool calls (`web_search`, `web_extract`, OpenAPI, MCP) | The tool's own host | That host's policy | The agent's `tools:`, `openapi:`, `mcp_server_url` / `mcp_tools` |
+| Sessions (conversation history) | Your Postgres, `adk_sessions` | 7 days after the last message | `ttlDays` (`postgresStorage`) |
+| Long-term memory facts | Your Postgres, `adk_memory_facts`; **the transcript is also sent to the extraction and embedding providers, Gemini by default whatever the agents run on** (the server warns at boot when they differ) | Until erased, or `memory_retention_days` | `MEMORY_EXTRACTION_MODEL`, `MEMORY_EMBEDDING_PROVIDER`, `memory_retention_days` |
+| The ledger: each turn's input, output and tool results (key-shaped secrets redacted) | Your Postgres, `adk_turns`, `adk_telemetry` | **Until you prune it**: schedule `melchizedek_prune_telemetry(<days>)` | `TELEMETRY_REDACT`, the prune's `turn_days` |
+| Sampled full model requests | Your Postgres, `adk_payloads` | 30 days | `TELEMETRY_PAYLOADS`, `TELEMETRY_PAYLOAD_TTL_DAYS` |
+| Traces, when `OTEL_EXPORTER_OTLP_ENDPOINT` is set | Your OTLP collector, conversation content included with key-shaped secrets redacted (`off` drops it) | Your collector's policy | `OTEL_EXPORT_CONTENT` (`redacted`, `off`, `raw`) |
+| Third-party OAuth tokens held for tools, per end user (when `postgresStorage({ credentials })` is used) | Your Postgres, `melchizedek_tool_credentials`, sealed with AES-256-GCM under `MELCHIZEDEK_CREDENTIAL_KEY`, which never reaches the database (migration 0013) | Until revoked or erased | The provider config; the key |
+| The audit trail (no content) | Your Postgres, `melchizedek_audit` | Until `melchizedek_prune_audit(<days>)` | The prune schedule |
+| The task record (no content) | stdout | Your log platform's policy | `A2A_LOG_FORMAT` |
+
+`DELETE /memory` erases a user from every Postgres store above except the
+audit trail, which holds no content, only a hash of the scope. It does not
+reach a provider's own retention: read each provider's data terms, and the
+business associate or data processing agreement you need with it, before
+sending it regulated data.
+
 #### Who pays
 
 `A2A_KEY_MODE` (option `keyMode`), whatever the authenticator:
@@ -679,6 +825,59 @@ subagent or a workflow node listing it is a load error. In code,
 `runSyndicateTurn` returns `status: 'input-required'` with `input`
 (`node`, `message`, `payload`), and the next message's text answers it.
 
+#### OAuth consent for tools
+
+A tool that acts for the person against a third-party API reads their
+delegated token with `ctx.accessToken(provider)` from the sealed credential
+store ([ADR 0072](./wiki/decisions/0072-tool-credentials-sealed-per-user.md)).
+When they have not granted the provider yet, the turn pauses for their
+consent ([ADR 0085](./wiki/decisions/0085-oauth-consent-pauses-on-adks-credential-request.md)).
+This runs on the native runtime:
+
+```ts
+import { createA2AApp } from 'melchizedek-agents/a2a';
+import { oauthConsent } from 'melchizedek-agents/tools/oauthConsent';
+
+const consent = oauthConsent({
+  providers: {
+    github: {
+      authorizationUrl: 'https://github.com/login/oauth/authorize',
+      tokenUrl: 'https://github.com/login/oauth/access_token',
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+      scopes: ['repo'],
+    },
+  },
+  redirectUri: 'https://agents.example.com/oauth/callback', // as registered at the provider
+  credentials: store, // storage.credentials, or credentialStore(...)
+});
+await createA2AApp({ /* … */ toolCredentials: { store, consent } });
+```
+
+1. **The pause.** The task ends `input-required` with the link in its status
+   message and a data part `{ type: 'consent_request', consent_id, agent,
+   provider, authorization_url, state, scopes }`.
+2. **The grant.** The person opens the link and consents. The provider
+   redirects their browser to the callback, which the server mounts at the
+   redirect URI's path. The callback exchanges the code with PKCE and stores
+   the grant, sealed.
+3. **The resume.** Their next message on the conversation runs the paused
+   call again. A message sent before the grant gets the same request back,
+   without a model call.
+
+The callback refuses these, and stores nothing:
+
+- a state that is replayed, tampered with or older than ten minutes;
+- a provider's `error`;
+- a caller who is authenticated as another user.
+
+No token, code, client secret or verifier is written to a page, an event, a
+log line or the model's context. The pending flows live in the process: run
+one replica, or route the callback to the instance that paused the call. In
+code, `runSyndicateTurn({ …, toolCredentials })` returns
+`status: 'input-required'` with `consent`. On the ADK runtime an open consent
+request throws `UnsupportedOnRuntimeError`.
+
 #### Limits
 
 | Setting | Default |
@@ -687,9 +886,13 @@ subagent or a workflow node listing it is a load error. In code,
 | `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_MAX_CONCURRENT_PER_SCOPE`: tasks at once for one end user | 4 |
+| `A2A_MAX_CONCURRENT_PER_CALLER`: tasks at once for one caller | unlimited |
+| `max_steps` (YAML): model calls per turn, subagents included | 50 |
+| `A2A_TRUST_PROXY`: proxies in front (required with `PUBLIC_URL`) | none trusted |
 | `A2A_BODY_LIMIT` | 1 MB |
 | `A2A_SHUTDOWN_GRACE_MS`: SIGTERM waits for running tasks | 25 s |
+| `A2A_SHUTDOWN_DELAY_MS`: of that, `/readyz` fails while requests are still served | 5 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
@@ -719,7 +922,11 @@ 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
+database (unless `ALLOW_UNHARDENED_DB=true`), and until the deployment
+states its posture: `A2A_AUTH` (prefer `callers` or `jwt`; `secret` lets any
+holder of the secret act as any user), `A2A_SERVED_AGENTS` (a list, or `*`
+for every agent) and `A2A_TRUST_PROXY` (the number of proxies in front, or
+`false`). The refusal names each one missing. 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
@@ -745,9 +952,14 @@ local conversation keeps talking to the same remote conversation.
 `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`.
+Set `PUBLIC_URL`, `A2A_SERVER_SECRET`, `A2A_AUTH`, `A2A_SERVED_AGENTS`,
+`A2A_TRUST_PROXY` and the provider keys from your secret manager; give the orchestrator's stop timeout at least
+`A2A_SHUTDOWN_GRACE_MS`. On SIGTERM the server first fails `/readyz` and
+keeps serving for `A2A_SHUTDOWN_DELAY_MS` so the load balancer deregisters
+it, then closes the listener and drains running tasks for the rest of the
+grace period; point the readiness probe at `/readyz`, which also fails while
+durable storage does not answer. `MELCHIZEDEK_DOTENV=off` makes every bin
+ignore `.env` files and run on its environment alone.
 
 #### Backups
 
@@ -1016,18 +1228,25 @@ the deadline cap the whole graph as they cap any turn.
 and remote `a2a_agent_url` subagents are refused inside a workflow by
 the schema, and a workflow cannot be another syndicate's `yaml_reference`
 (ADK cannot yet make a `Workflow` a subagent; nested, only its
-orchestrator runs). The record is [ADR 0030](./wiki/decisions/0030-workflow-graphs.md);
-the contract is `lib/workflow.ts`, on ADK's `Workflow`.
+orchestrator runs). An `ask_user` tool on a node agent is refused too:
+use an `ask_user` node. The record is [ADR 0030](./wiki/decisions/0030-workflow-graphs.md);
+the contract is `lib/workflow.ts`, on ADK's `Workflow`, and on the native
+runtime `lib/workflow/turn.ts`, on the engine's own scheduler
+([ADR 0095](./wiki/decisions/0095-native-workflow-turn-drains-through-the-adk-reader.md)).
+On native, a conversation paused inside an agent node or a map item
+(which only ADK resumes) fails the next turn with `RESUME_UNSUPPORTED`.
 
 ## 7. Extending the framework
 
-**Call ADK directly (no syndicate)**: the YAML layer is a convenience,
+**Call a model directly (no syndicate)**: the YAML layer is a convenience,
 never a requirement. `scripts/direct_call.ts` (`npm run demo:direct`) is
-the canonical minimal block — `LlmAgent` + `Runner` +
-`InMemorySessionService` straight from `@google/adk`, ~30 lines you can
-copy into any repo that has `@google/adk` installed. Add
-`registerAvailableProviders()` from `lib/models/registry.ts` and the
-same block runs `claude-*` / `gpt-*` / `grok-*` / `kimi-*` / `ollama/*` ids too.
+the canonical minimal block on the engine's model contract:
+`resolveAdapter(modelId)` from `melchizedek-agents/model`, then
+`adapter.generate({ model, system, messages, stream })`, reading partial
+and final responses. The id's prefix picks the provider (`gemini-*`,
+`claude-*`, `gpt-*`, `grok-*`, `kimi-*`, `ollama/*`), the key comes from
+the environment, and nothing in that entry loads `@google/adk`. A turn
+with tools, sessions and telemetry is `runSyndicateTurn`.
 
 **Add a syndicate**: create `config/agents/<name>.yaml` — copy the
 closest starter-pack file from `config/agents/examples/` or start from
@@ -1035,15 +1254,20 @@ closest starter-pack file from `config/agents/examples/` or start from
 <name>`. No code changes. The loader checks the root first, then
 `examples/`, so your syndicate and the starter pack never collide.
 
-**Add a tool**: implement a `FunctionTool` in `lib/tools/`, register the
-name in `lib/toolRegistry.ts`, reference it from YAML. The two image
-tools are the worked examples — including why binary data forces
-FunctionTools over subagents, and how a tool signature can enforce an
-epistemic rule (the blind inventory).
-
-**Add a provider**: follow `claudeLlm.ts` (SDK-based, key-gated) or
-`ollamaLlm.ts` (fetch-based, keyless) — implement the ADK LLM
-interface, register it behind a model-id prefix.
+**Add a tool**: write a `defineTool` contract in `lib/tools/` (name,
+description, zod schema, execute), register the name in
+`lib/toolRegistry.ts` (or call `registerTool` from your own code),
+reference it from YAML. The contract runs on either runtime; see
+`wiki/tools/tool-contracts.md`. The two image tools are the worked
+examples — including why binary data forces function tools over
+subagents, and how a tool signature can enforce an epistemic rule (the
+blind inventory).
+
+**Add a provider**: follow `claudeAdapter.ts` (SDK-based, key-gated, a
+`ModelAdapter` on the engine's model contract, run under ADK by its shim
+`claudeLlm.ts`) or, for a chat-completions API, `ollamaAdapter.ts`
+(fetch-based, keyless: a `ChatCompletionsAdapter` subclass, run under ADK
+by its shim `ollamaLlm.ts`), and register it behind a model-id prefix.
 
 **Point an agent at an MCP server**: set `mcp_server_url:` on a
 subagent. `scripts/demo_mcp_server.ts` is a complete server to copy —

package/README.md

@@ -101,7 +101,7 @@ const result = await runSyndicateTurn({
 console.log(result.status, result.text);
 ```
 
-`runSyndicateTurn` is the same runtime the server, CLI, and eval harness use. To read syndicates from somewhere else, pass `loadSyndicate(file, { agentsDir })` or set `MELCHIZEDEK_AGENTS_DIR`. To serve inside your own Express app, mount `(await createA2AApp({ defaultSyndicate: 'mine.yaml', serverSecret })).app`.
+`runSyndicateTurn` is the same runtime the server, CLI, and eval harness use. It runs on Google ADK by default; `runtime: 'native'` (or `MELCHIZEDEK_RUNTIME=native`) runs a single-agent, delegating, plan-dispatch or workflow syndicate on the engine's own loop and scheduler instead. To read syndicates from somewhere else, pass `loadSyndicate(file, { agentsDir })` or set `MELCHIZEDEK_AGENTS_DIR`. To serve inside your own Express app, mount `(await createA2AApp({ defaultSyndicate: 'mine.yaml', serverSecret })).app`.
 
 The example syndicates ship inside the package at `node_modules/melchizedek-agents/config/agents/examples/`; copy one out as a starting point.
 
@@ -116,6 +116,44 @@ registerTool('myCustomTool', defineTool({ /* ... */ }));
 registerGuard(myGuardInstance);
 ```
 
+### The Model Adapters Alone
+
+`melchizedek-agents/model` is the engine's model layer on its own: one message format for every provider, an adapter per provider, `resolveAdapter` over the same model-id prefixes the YAML uses, and `FallbackAdapter`. It loads no `@google/adk`, so a project that only calls models can leave ADK out. npm 7 and later install peer dependencies by default; skip them with:
+
+```bash
+npm install melchizedek-agents --legacy-peer-deps
+```
+
+```typescript
+import { ClaudeAdapter, OllamaAdapter, resolveAdapter } from 'melchizedek-agents/model';
+import type { ModelAdapter, ModelRequest } from 'melchizedek-agents/model';
+
+async function ask(adapter: ModelAdapter, text: string): Promise<string> {
+  const request: ModelRequest = {
+    model: adapter.model,
+    system: 'Answer in one sentence.',
+    messages: [{ role: 'user', parts: [{ type: 'text', text }] }],
+  };
+  for await (const response of adapter.generate(request)) {
+    if (response.partial) continue; // deltas while the model writes
+    if (response.error) throw new Error(response.error.message);
+    return response.parts.map((p) => (p.type === 'text' ? p.text : '')).join('');
+  }
+  return '';
+}
+
+// Claude: the key comes from ANTHROPIC_API_KEY in the environment.
+console.log(await ask(new ClaudeAdapter({ model: 'claude-sonnet-4-6' }), 'What is A2A?'));
+
+// Ollama: a local model, no key (OLLAMA_BASE_URL, else http://localhost:11434/v1).
+console.log(await ask(new OllamaAdapter({ model: 'ollama/qwen3:8b' }), 'What is A2A?'));
+
+// Or by id, with the same routing as a syndicate's `model:` field.
+const adapter = resolveAdapter('ollama/qwen3:8b');
+```
+
+A Gemini id resolves to the engine's `GeminiAdapter` here. The ADK-backed Gemini adapter, the ADK shims and `resolveModel` stay under `melchizedek-agents/models/*`, which need ADK.
+
 ### CLI & Server Utilities
 
 - `npx melchizedek-chat --syndicate <name>`: Interactive CLI REPL for any syndicate.
@@ -164,6 +202,9 @@ See `config/agents/syndicateSchema.yaml` for the annotated schema reference.
 - [`DOCUMENTATION.md`](./DOCUMENTATION.md) — Full reference: architecture, syndicate YAML, tools, memory, providers, A2A, extending, security.
 - [`AGENT_SETUP.md`](./AGENT_SETUP.md) — A paste-ready prompt that walks your coding agent (Claude Code, Cursor, Codex) through setup.
 - [`skills/README.md`](./skills/README.md) — The bundled `SKILL.md` suite.
+- [`VERSIONING.md`](./VERSIONING.md) — What an upgrade may break, deprecation, and which versions get fixes.
+- [`SUPPORT.md`](./SUPPORT.md) — Where to ask, and what to expect: a single-maintainer project with no SLA.
+- [`SECURITY.md`](./SECURITY.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 ## License