melchizedek-agents 0.19.0 → 1.0.0

package/DOCUMENTATION.md

@@ -1,7 +1,7 @@
 # melchizedek-agents — reference documentation
 
 The framework in one sentence: **a syndicate is a YAML file describing an
-agent graph; the runtime compiles it into live Google-ADK agents with
+agent graph; the engine compiles it into agents on its own loop, with
 tools, sessions, and memory attached.** This document is the reference
 for that file format and the machinery around it. For a guided first run,
 see [`QUICKSTART.md`](./QUICKSTART.md).
@@ -27,13 +27,14 @@ 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)
-lib/toolRegistry.ts       tool name → live ADK tool instance
+lib/toolRegistry.ts       tool name → the engine's own Tool
 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
+lib/tools/mcpToolFactory.ts  MCP client: remote tools → the engine's own Tools
 scripts/demo_mcp_server.ts   demo MCP server (library catalog, SSE)
+lib/runtime/native/…      the native loop: steps, delegation, compaction, interrupts
+lib/workflow/…            the workflow scheduler for `workflow:` syndicates
 lib/session/…             Supabase-backed session service
 lib/memory/…              pgvector long-term memory service
 lib/observability/…       OpenTelemetry run tracing
@@ -48,27 +49,42 @@ tests/agents.test.ts      compiles every shipped syndicate; opt-in live check
 ```
 
 Execution flow: `loadSyndicate` reads and validates the YAML and binds
-`{{variables}}` → the runner builds an `LlmAgent` per agent, wiring
-subagents as `AgentTool`s and tool names through the registry → the ADK
-`Runner` executes the turn, persisting events to the session service →
-on session end, the memory service distills the transcript into tagged
-facts, embeds them (768-d), and stores them for future recall.
+`{{variables}}` → the compiler builds each agent on the engine's own
+loop, wiring subagents as delegation tools and tool names through the
+registry → the loop runs the turn, calling each agent's model through its
+adapter on the engine's model contract and persisting events to the
+session service → 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
+per agent, and `lib/compileNative.ts` turns it into the native loop's
+agent. The native runtime is the only runtime
+([ADR 0107](./wiki/decisions/0107-release-1-0-0-removes-adk.md)): it owns the
+loop, the model contract and its adapters, the tools, the sessions and
+the workflow scheduler, and runs a single-agent, delegating,
+plan-dispatch or `workflow:` syndicate, `context:` compaction
 ([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
+`mode: task`, and pause and resume included
+([ADR 0095](./wiki/decisions/0095-native-workflow-turn-drains-through-the-adk-reader.md)).
+Two configurations it refuses with `UnsupportedOnRuntimeError` before any
+model call: a `transformAgent` hook (it transformed ADK agents), and an
+`ask_user` tool on a workflow node (use an `ask_user` node)
 ([ADR 0073](./wiki/decisions/0073-one-agent-spec-and-a-runtime-flag.md)).
 
+1.0.0 removed Google ADK
+([ADR 0045](./wiki/decisions/0045-own-runtime-behind-the-seam.md),
+[ADR 0107](./wiki/decisions/0107-release-1-0-0-removes-adk.md)).
+`MELCHIZEDEK_RUNTIME=native` (or `runtime: 'native'` on
+`runSyndicateTurn`) changes nothing; `adk` throws `RuntimeRemovedError`,
+naming 1.0.0, at the startup of the A2A server, the chat and the worker,
+and from `runSyndicateTurn` before the session is touched; any other value
+is a configuration error. The engine stores the same event JSON ADK wrote,
+so a session written before 1.0.0 resumes, and `npx melchizedek-doctor`
+prints the runtime in use and where the choice came from. Upgrading from
+0.x: read the 1.0.0 "Breaking — read before upgrading" section of
+[`CHANGELOG.md`](./CHANGELOG.md).
+
 ## 2. The syndicate YAML
 
 Minimal complete example:
@@ -114,18 +130,18 @@ Field reference:
 | `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). |
 | `workflow` | root | Switches the syndicate to a WORKFLOW (§6): a graph whose nodes are its agents plus declared `join`, `map`, `tool` and `ask_user` nodes, and whose `edges` say what runs after what and on which route. The orchestrator is a node like any other; nothing delegates. Cannot be combined with `dispatch`. Contract: `lib/workflow.ts`; worked example: `examples/pipeline.yaml`. |
-| `retries` | root | Self-correction, on by default ([ADR 0034](./wiki/decisions/0034-self-correction.md)): `model_errors` (default 2) retries a model reply ADK marks malformed (`MALFORMED_FUNCTION_CALL`) instead of failing the turn; `tool_errors` (default 3) answers a tool that threw with structured reflection guidance and caps its retries. `0` turns either off. Every retry is a model call under `max_steps`. |
+| `retries` | root | Self-correction, on by default ([ADR 0034](./wiki/decisions/0034-self-correction.md)): `model_errors` (default 2) retries a model reply marked malformed (`MALFORMED_FUNCTION_CALL`) instead of failing the turn; `tool_errors` (default 3) answers a tool that threw with structured reflection guidance and caps its retries. `0` turns either off. Every retry is a model call under `max_steps`. |
 | `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`. |
 | `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). |
+| `outputSchema` | agent | Structured-JSON contract. **Constraint:** an agent holding `outputSchema` cannot also hold transfer powers — structured output does not combine with delegation on one agent. 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. |
+| `includeContents` / `outputKey` / `globalInstruction` / `disallowTransferToParent` / `disallowTransferToPeers` | agent | Passed through to the agent (the names are ADK's `LlmAgent` fields). `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. |
@@ -134,7 +150,7 @@ Field reference:
 | `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 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. |
+| `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/`. |
 
 Validation happens at load: missing names, legacy option blocks, and
 malformed agents fail with pointed errors before any model is called.
@@ -143,16 +159,14 @@ skipped with a warning at compile time.
 
 ## 3. Tools
 
-Registered in `lib/toolRegistry.ts` — one map from YAML name to ADK tool
-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
+Registered in `lib/toolRegistry.ts` — one map from YAML name to tool. A
+**Contract** is the engine's own Tool (`lib/tools/tool.ts`), defined once
+with `defineTool`; the native loop runs it as it is. An **Instruction
+tool** is the engine's own too: it declares no function and only writes
+into each request's instruction. 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)):
+function, and every adapter recognises it by marker
+([ADR 0062](./wiki/decisions/0062-server-side-tools-as-markers.md)):
 
 | Name | Kind | Does |
 |---|---|---|
@@ -161,7 +175,7 @@ adapter recognises it by marker ([ADR 0062](./wiki/decisions/0062-server-side-to
 | `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`). |
+| `google_search` | Gemini built-in | Live web search — Gemini agents only (legacy alias; use `web_search`). |
 | `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. |
@@ -173,8 +187,7 @@ adapter recognises it by marker ([ADR 0062](./wiki/decisions/0062-server-side-to
 **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 makes each one an own Tool (`loadMcpTools`), which
-the ADK runtime runs as a `FunctionTool` (`createMcpTools`) — the
+lists its tools, and makes each one an own Tool (`loadMcpTools`) — 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
@@ -228,8 +241,8 @@ example: `config/agents/examples/weather.yaml`, two keyless Open-Meteo specs
 in `examples/specs/`.
 
 > **Schema dialects, handled for you.** The factory emits Gemini-style
-> UPPERCASE schema types (`'OBJECT'`, `'STRING'`, …) because the ADK is
-> Gemini-native; every non-Gemini adapter normalizes them back to
+> UPPERCASE schema types (`'OBJECT'`, `'STRING'`, …), the `@google/genai`
+> dialect; every non-Gemini adapter normalizes them back to
 > standard lowercase JSON-Schema at request-build time
 > (`lib/models/schemaNormalize.ts`). MCP tools therefore work on any
 > provider's agents — Gemini, Claude, GPT, Grok, or Kimi.
@@ -340,13 +353,13 @@ 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/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 |
+| `gemini-*` | Google Gemini | `lib/models/geminiAdapter.ts` (`@google/genai`) | `GOOGLE_GENAI_API_KEY` | ✅ grounding |
+| `claude-*` | Anthropic | `lib/models/claudeAdapter.ts` (Messages API) | `ANTHROPIC_API_KEY` | ✅ server tool |
+| `gpt-*`, o-series | OpenAI | `lib/models/gptAdapter.ts` (Responses API) | `OPENAI_API_KEY` | ✅ web_search tool |
+| `grok-*` | xAI | `lib/models/grokAdapter.ts` (Responses API) | `XAI_API_KEY` | ✅ Agent Tools search |
+| `kimi-*` | Moonshot AI (Kimi) | `lib/models/kimiAdapter.ts` (chat completions) | `MOONSHOT_API_KEY` | ⚠ omitted + warning |
+| `ollama/*` | Local Ollama | `lib/models/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/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
@@ -356,9 +369,8 @@ 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`, the
-ADK shim around `KimiAdapter` (`lib/models/kimiAdapter.ts`, on the
-chat-completions base), against `https://api.moonshot.ai/v1`
+**Moonshot AI (Kimi).** `kimi-*` ids route to `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,
@@ -455,11 +467,12 @@ 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
-present (Ollama needs none) into the ADK's LLM registry, so the YAML
-string finds its provider; missing keys produce clear skip messages,
-and only the providers a syndicate actually declares are required.
+`lib/models/registry.ts` is the single routing seam: `resolveAdapter`
+turns the YAML's model string into its provider's adapter, and
+`logProviderStatuses()` reports which providers have a key
+(Ollama needs none) and, given a log function, logs a line per provider;
+it registers nothing. Missing keys produce clear skip messages, and only
+the providers a syndicate actually declares are required.
 Mixed graphs are supported — each agent picks its own provider, one
 line each. `config/agents/examples/claude.yaml` is the minimal Claude example;
 `config/agents/examples/model_zoo.yaml` declares one lightweight agent per
@@ -469,9 +482,7 @@ prompt to every available provider, printing input, thinking (qwen3
 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. 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.
+runs as a one-agent syndicate through `runSyndicateTurn`.
 
 Reasoning/thinking: scratchpads from every provider are surfaced as
 dimmed THINKING output and kept out of session history. On Claude, any
@@ -488,44 +499,33 @@ 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`).
+runtime (ADR 0045), with no `@google/*` in its import graph, and every
+provider's adapter implements it. `wiki/models/model-contract.md` gives
+each field's purpose and its mapping onto every provider's wire. The
+native loop calls the adapters directly, charging each call against
+`max_steps`, passing the turn's abort signal and opening the
+`llm.request` span (ADR 0053).
+Gemini's adapter is `GeminiAdapter`
+(`melchizedek-agents/models/geminiAdapter`, on `@google/genai`)
+([ADR 0100](./wiki/decisions/0100-gemini-row-asserted-on-the-engine-adapter.md)).
 `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,
+from the prefix table, with the gateway rule, BYOK scoping and endpoints;
+`resolveModel` returns the same `ModelAdapter` for a BYOK path (ADR 0060).
+Every Gemini id gets `GeminiAdapter`: `GEMINI_ADAPTER=engine` (or
+`gemini: 'engine'`) changes nothing, and `adk` throws, naming 1.0.0.
+`resolveAdapterWithFallback` wraps an agent's model and `fallback_model`
+in a `FallbackAdapter`.
+
+`melchizedek-agents/model` is the model layer on its own (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.
+helpers. A project that only calls models imports from there. Its
+`resolveAdapter` gives a Gemini id `GeminiAdapter`; `resolveModel` is not
+in it.
 
 Every model request also emits an `llm.request` OpenTelemetry span
 (provider, model, input/output/thinking tokens, latency). Scripts print it
@@ -546,24 +546,24 @@ kept by policy (`TELEMETRY_PAYLOADS=off|errors|sample|all`,
 `TELEMETRY_PAYLOAD_SAMPLE`, `TELEMETRY_PAYLOAD_TTL_DAYS`) and expired by
 `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
+`messages`, `tools`, …), whichever adapter made the call. The native loop
+opens `agent.invoke <name>`, `model.call` and `tool.execute <name>` spans;
+a clean call's row comes from `model.call` and holds the request and the
+adapter's response in the contract's shapes. Rows written before 1.0.0
+under ADK's `invoke_agent`, `call_llm` and `execute_tool` spans hold ADK's
+request, and the ledger still reads them (ADR 0076). 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`).
 
 **Open-weight local models**: `ollama/*` ids (e.g. `ollama/qwen3:8b`)
-route through `lib/models/ollamaLlm.ts` to a local Ollama daemon over
+route through `lib/models/ollamaAdapter.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), `council.yaml` (council)
 and `assistant.yaml` (conversation, summaries, a task list, background jobs)
-are the worked examples. The adapter translates ADK content to
+are the worked examples. The adapter translates the contract's messages to
 OpenAI-style messages, including tool calls (so delegation works),
 image parts as data URIs (so `ollama/qwen3-vl:8b` can see), and JSON
 response mode; reasoning models' `<think>…</think>` scratchpads are
@@ -784,11 +784,12 @@ same conversation (same `contextId`; the same `taskId` works too) with the text
 `{ "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.
+without a model call. The paused call and its arguments are pinned, 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
+plan-dispatch syndicate, which run as the turn's own agent, and on the
+agent nodes of a workflow (§6). 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
@@ -831,8 +832,7 @@ 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:
+consent ([ADR 0085](./wiki/decisions/0085-oauth-consent-pauses-on-adks-credential-request.md)):
 
 ```ts
 import { createA2AApp } from 'melchizedek-agents/a2a';
@@ -875,8 +875,7 @@ 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`.
+`status: 'input-required'` with `consent`.
 
 #### Limits
 
@@ -1090,9 +1089,9 @@ emitted the bare tool name in place of a 2,599-character answer.
 Plan-dispatch has no relay turn to fail, and the classifier's output
 shrinks from a whole relayed answer to ~15 tokens of JSON.
 
-**Why the classifier is tool-less.** ADK refuses to combine
-`outputSchema` with AgentTool delegation on one agent (see
-`config/agents/examples/critic.yaml` — an orchestrator holding both deadlocks).
+**Why the classifier is tool-less.** Structured output does not combine
+with delegation on one agent (see `config/agents/examples/critic.yaml`,
+whose header tells how an orchestrator holding both deadlocked on ADK).
 That constraint shapes the method: the classifier is a leaf, and the
 hand-off happens in code, where it can be logged, traced, and streamed
 to the user as progress.
@@ -1100,8 +1099,9 @@ to the user as progress.
 **Sessions.** Every *route* runs in the shared `<contextId>` session, so
 one transcript accumulates across routes and long-term memory ingests
 real answers instead of a relay copy of them. Sharing the session is
-necessary but not sufficient: ADK renders an event by comparing
-`event.author` against the agent now running, and under plan-dispatch
+necessary but not sufficient: a stored event is rendered by comparing
+`event.author` against the agent now running (ADK's rule, which the native
+loop keeps), and under plan-dispatch
 every route is its own root agent, so the whole history fails that
 comparison and `convertForeignEvent` rewrites it to `role: "user"`
 prefixed "For context:". A route reading the raw shared session
@@ -1128,11 +1128,11 @@ traffic before any prompt, and the memory service's `serializeEvents` walks
 ~90% of every byte stored (`thoughtSignature` alone 73.3%), so they are
 stripped from the SERIALIZED COPY — the live in-memory session keeps them,
 or the agent's own tool loop breaks mid-turn. An elided tool result keeps
-its `id` and `name` and gains a size marker, because ADK pairs calls to
-responses by id and throws on a widowed half. 21.72 MB → 4.88 MB; existing
+its `id` and `name` and gains a size marker, because the loop pairs
+calls to responses by id and a widowed half breaks the history. 21.72 MB → 4.88 MB; existing
 rows shrink retroactively on their next write. Note the constraint this
 rests on: dropping the signature is safe only because stored events are
-never replayed to a model. The quadratic upload is untouched — `appendEvent`
+never replayed to a model. The quadratic upload is untouched — `append`
 still rewrites the whole array per event — and is the next lever if row size
 returns.
 
@@ -1159,9 +1159,9 @@ contract lives in `lib/dispatch.ts`.
 specialist runs, so an A2A client can show a waiting user what is
 happening. The `reason` field is written for that reader, not for logs.
 
-Implemented in `scripts/a2a_server.ts`; like `yaml_reference`, it is
-A2A-only — the CLI runner (`scripts/syndicate_chat.ts`) still compiles
-every syndicate in DELEGATE mode.
+Implemented in `runSyndicateTurn`, so every surface honours it: the A2A
+server, the CLI runner (`scripts/syndicate_chat.ts`), the worker and the
+evals.
 
 ### Workflows (`workflow:`) — the third orchestration method
 
@@ -1199,7 +1199,11 @@ the list of results); `tool: <registry name>` (runs the tool with the
 node input as its arguments); `ask_user: "<question>"` (below). An entry
 named after an agent carries modifiers only: `route_key`, `retry`
 (`max_attempts`, `initial_delay`, `max_delay`, `backoff_factor`, in
-seconds) and `timeout` (seconds), which any node may carry.
+seconds; `jitter`, the backoff's randomness, 0 for none; `exceptions`,
+the error names to retry on, every error when absent) and `timeout`
+(seconds), which any node but a `map` may carry. A map's items run under
+the mapped agent's own `retry` and `timeout`, so a `map` entry refuses
+both and the load error names the agent's entry instead.
 
 **The pause.** An `ask_user` node ends the turn `input-required`
 (`result.input`: the node, the question, and what it was asked about).
@@ -1224,17 +1228,35 @@ again (the attempt is recorded in `answer.nodeErrors`), and a node that
 gives up fails the turn with `NODE_FAILED` naming it. `max_steps` and
 the deadline cap the whole graph as they cap any turn.
 
-**Not yet.** Approval gates (`require_approval`, `skills.scripts: local`)
-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). 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`.
+**Approval gates.** A tool in a node agent's `require_approval` pauses
+that node, and the graph with it: the turn ends `input-required` with
+`result.approval`, as any approval does, and the next message, the
+person's decision, resumes the node's own run, which runs or refuses the
+pinned call once and walks on. Any other message repeats the request and
+runs nothing. Skill scripts (`skills.scripts: local`) on a node agent
+pause the same way, each `run_skill_script` call waiting for its approval,
+with the minimal script environment of ADR 0086. The schema refuses a gate or skill scripts on an agent a `map`
+node runs.
+
+**Nested.** A `yaml_reference` to a workflow syndicate runs the whole
+graph, under the entry's name and description, wherever it appears: as a
+DELEGATE subagent its last output is the tool's answer; as a plan-dispatch
+route it is the turn's answer, and the conversation keeps the message and
+that answer; as a node of another workflow it is the node's output. The
+graph's events are kept in the entry's own session, as for any subagent.
+A nested workflow may not have an `ask_user` node (a pause inside it
+cannot reach the caller); it is refused by name, as is a `map` over one.
+
+**Not yet.** Remote `a2a_agent_url` subagents are refused inside a
+workflow by the schema. An `ask_user` tool on a node agent is refused
+too: use an `ask_user` node. The records are [ADR 0030](./wiki/decisions/0030-workflow-graphs.md),
+[ADR 0098](./wiki/decisions/0098-workflow-subagent-and-node-approvals.md) and
+[ADR 0106](./wiki/decisions/0106-nested-workflow-routes-nodes-and-node-skill-scripts.md);
+the turn is `lib/workflow/turn.ts`, on the engine's own scheduler
+([ADR 0095](./wiki/decisions/0095-native-workflow-turn-drains-through-the-adk-reader.md)),
+and `lib/workflow.ts` holds the `workflow:` block's contract. A conversation paused inside an agent node on anything
+but an approval, or inside a map item, fails the next turn with
+`RESUME_UNSUPPORTED`.
 
 ## 7. Extending the framework
 
@@ -1245,7 +1267,7 @@ the canonical minimal block on the engine's model contract:
 `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
+the environment. A turn
 with tools, sessions and telemetry is `runSyndicateTurn`.
 
 **Add a syndicate**: create `config/agents/<name>.yaml` — copy the
@@ -1257,17 +1279,16 @@ closest starter-pack file from `config/agents/examples/` or start from
 **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
+reference it from YAML. The native loop runs the contract as it is; 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.
+`ModelAdapter` on the engine's model contract) or, for a chat-completions
+API, `ollamaAdapter.ts` (fetch-based, keyless: a `ChatCompletionsAdapter`
+subclass), 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/QUICKSTART.md

@@ -82,9 +82,10 @@ after answering:
 npm run syndicate:critic -- "In two sentences, why did the Library of Alexandria decline?"
 ```
 
-The syndicate layer itself is optional. `scripts/direct_call.ts` launches
-a single ADK agent with no YAML at all — conventional, code-first agent
-calling, and the block to copy when embedding an agent in your own code:
+The syndicate layer itself is optional. `scripts/direct_call.ts` makes
+a single model call with no YAML at all — the engine's model contract on
+its own (`melchizedek-agents/model`), and the block to copy when embedding
+a model call in your own code:
 
 ```bash
 npm run demo:direct -- "In one sentence: what is an agent?"
@@ -180,23 +181,22 @@ Everything above runs inside a clone. When your syndicates deserve their
 own repo, the same engine is a typed dependency:
 
 ```bash
-npm install melchizedek-agents @google/adk@2.2.0
+npm install melchizedek-agents
 npx melchizedek-init                         # config/agents/conversational.yaml + .env; --list for others
 npx melchizedek-doctor                       # which keys it needs, and whether it is ready
 ```
 
 ```typescript
-import { InMemorySessionService } from '@google/adk';
-import { loadSyndicate, registerAvailableProviders, runSyndicateTurn } from 'melchizedek-agents';
+import { InProcessSessionService, loadSyndicate, logProviderStatuses, runSyndicateTurn } from 'melchizedek-agents';
 
-registerAvailableProviders();                 // registers every model whose key is present
+logProviderStatuses(console.log);             // reports which providers have a key
 const config = loadSyndicate('mine.yaml');    // reads <your-repo>/config/agents/mine.yaml
 
 const result = await runSyndicateTurn({
   config,
   parts: [{ text: 'Hello' }],
   appName: 'my-app', userId: 'u1', sessionId: 'c1',
-  sessionService: new InMemorySessionService(),
+  sessionService: new InProcessSessionService(),
 });
 console.log(result.text);
 ```
@@ -222,8 +222,12 @@ console.log(result.text);
   `config/agents/`.
 - Deeper imports are available as subpaths — `melchizedek-agents/models/registry`,
   `melchizedek-agents/tools/webExtractTool`, `melchizedek-agents/memory`,
-  and friends — all typed. `@google/adk` installs alongside as a peer:
-  your app owns the ADK version.
+  and friends — all typed.
+- **One engine, no ADK.** Every turn runs on the engine's own agent loop;
+  1.0.0 removed Google ADK, and `MELCHIZEDEK_RUNTIME=adk` is an error.
+  Upgrading from 0.x: read the 1.0.0 "Breaking — read before upgrading"
+  section of [`CHANGELOG.md`](./CHANGELOG.md).
+  `npx melchizedek-doctor` prints which runtime is in use.
 - **Your coding agent can learn all of this.** The package ships a
   six-skill suite (`skills/`, the open SKILL.md standard) covering the
   catalog, authoring, serving, memory, models, and the Scribe: