melchizedek-agents 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -6,6 +6,258 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 0.20.0 — 2026-10-08
+
+Release 0.20.0: the native runtime is the default, and `@google/adk` is an
+optional peer (ADR 0102).
+
+### Breaking — read before upgrading
+
+- **Breaking: the native runtime is the default (WS5-1, ADR 0102).** A
+  turn with no `runtime` option and no `MELCHIZEDEK_RUNTIME` now runs on the
+  engine's own loop and scheduler (`DEFAULT_RUNTIME` is `native`), on every
+  surface: `runSyndicateTurn`, the A2A server, the bins, the wiki agents.
+  It stores the events the ADK runtime stores, and every session ADK wrote
+  resumes under it (`tests/sessionFixtures.test.ts`, ADR 0045's stop rule),
+  so a deployment that upgrades keeps its conversations. **To stay on ADK**
+  for this release: install `@google/adk@~2.2.0` beside the package and set
+  `MELCHIZEDEK_RUNTIME=adk` (or pass `runtime: 'adk'`); a conversation can
+  move between the runtimes either way. What differs on native: approval
+  gates on workflow nodes run on native only (ADR 0098); `context:`
+  compaction, `mode: task` and workflows run on the engine's ports of ADK's
+  compactor, task mode and scheduler (ADR 0078, ADR 0081, ADR 0087, ADR
+  0095); a Gemini agent is not shown the reflection tool and stores no
+  `turnComplete` (ADR 0097, ADR 0100); self-correction's reflection call on
+  Gemini 3 is signed (ADR 0103); a caller's `transformAgent` is ADK-only,
+  and an `ask_user` tool listed on a workflow agent node (rather than an
+  `ask_user` node) is refused, each with `UnsupportedOnRuntimeError` before
+  any model call (ADR 0073, ADR 0092). **1.0.0
+  removes the adk runtime** (ADR 0045).
+- **Breaking: `@google/adk` is an optional peer dependency.** npm no longer
+  installs it with the package; nothing on the native runtime loads it, and
+  `lib/adkPeer.ts` is the one module that tries to. Without it, everything
+  only ADK runs fails with the new `AdkNotInstalledError`, which names the
+  package and the install command: `MELCHIZEDEK_RUNTIME=adk`,
+  `compileGraph` / `compileSubagent` / `compileWorkflow`, `retryPlugins`,
+  `GEMINI_ADAPTER=adk`, a wiki agent on adk, and the ADK face of a tool, a
+  model shim or a session store (their `runAsync`, `generateContentAsync`,
+  `appendEvent`). The engine's classes that extend ADK's (the
+  `FunctionTool`s in the tool registry, the model shims, the session
+  stores) still construct and still carry their own Tool, adapter or store;
+  with ADK installed they are ADK's own classes, as before. An install of
+  ADK that fails to load for another reason is still an error. A
+  TypeScript consumer without ADK sees ADK's types in the declarations as
+  unresolved (use `skipLibCheck`). The package now uses a top-level
+  `await` to load the peer, so it cannot be `require()`d from CommonJS.
+- **Breaking: a Gemini id gets the engine's `GeminiAdapter` by default
+  (ADR 0100).** `resolveAdapter` from `melchizedek-agents/models/registry`
+  and `geminiAdapterChoice()` default to `engine`; `GEMINI_ADAPTER=adk`
+  (or `{ gemini: 'adk' }`) keeps `AdkGeminiAdapter` for this release, with
+  `@google/adk` installed. The adk runtime keeps `TracedGemini`.
+- **Breaking: `registerTool` refuses the framework's reserved names.**
+  `adk_request_confirmation`, `adk_request_credential`,
+  `adk_request_input`, `adk_handle_model_error`, `transfer_to_agent`,
+  `set_model_response`, `finish_task`, and `ask_user` unless it is the
+  framework's own tool, are refused as the registry name or the tool's own
+  name, with `{ override: true }` too: a tool under one of them would be
+  read as the framework's interrupt, delegation or answer.
+  `RESERVED_TOOL_NAMES` is exported from `melchizedek-agents/tools`.
+- **Breaking: a workflow `map:` node refuses `retry` and `timeout`
+  (ADR 0103).** Neither runtime ever applied them: each item of a map runs
+  under the mapped agent's own node entry, as ADK runs it. A YAML that set
+  them on the map entry loaded and silently ignored them; it is now refused
+  at load with `workflow.nodes.<Map>.retry — retry on a map node is not
+  applied: each item runs under its agent's own retry; set it on
+  nodes.<Agent>` (and the same for `timeout`). Move the keys to the mapped
+  agent's entry. No shipped example or template sets them.
+
+### Added and changed
+
+- **The doctor prints the runtime (ADR 0102).** `melchizedek-doctor` opens
+  with a `runtime` line: the runtime in use, where it came from
+  (`MELCHIZEDEK_RUNTIME` or the default) and whether `@google/adk` is
+  installed, with its version. `--check` also fails when
+  `MELCHIZEDEK_RUNTIME=adk` is set without ADK, or holds a value no turn
+  accepts. `runDoctor()` returns it as `runtime`, and `runtimeReport` is
+  exported from `lib/doctor.ts`.
+- **New exports.** From the barrel and `melchizedek-agents/runtime`:
+  `describeRuntime` (the runtime and its source), `RuntimeSource`,
+  `AdkNotInstalledError`, `adkInstalled`, `InProcessSessionService` (a
+  session store that needs no ADK) and `asAdkSessionService` /
+  `asSessionService`; the barrel also exports `DEFAULT_RUNTIME` and
+  `RuntimeName`. A turn without ADK takes
+  `sessionService: asAdkSessionService(new InProcessSessionService())`.
+  The exports map does not change.
+- **CI consumes the packed tarball twice**: without `@google/adk` a shipped
+  example's turn runs on native, and with it the same turn runs on adk.
+
+- **The native loop's security gate (WS5-5, ADR 0101).** A model's answer is
+  now held to the model contract before either runtime stores it:
+  `modelResponseToLlmResponse` in `melchizedek-agents/models/genaiMapping`
+  drops a part the contract does not allow (an unknown kind, `null`, a text
+  part whose text is not a string, a tool result) and coerces a tool call's
+  name, id and arguments (`{}` for none, `{ raw }` otherwise); the new
+  `contractModelResponse` export is that check. A call's arguments or a
+  tool's result nested deeper than 64 levels is replaced by a short note
+  (`TOO_DEEP_ARGUMENTS`; on the native runtime `TOO_DEEP_RESULT`), where it
+  used to fail that turn and every later one on the session. A
+  `yaml_reference` chain that reaches itself, or goes past 16 levels, now
+  fails the compile with an Error naming the chain, on both runtimes; it
+  used to overflow the stack and stop the process. On the native runtime a
+  call id `__proto__` opens its approval as any id does, a credential
+  request in an event the user wrote is not pending, a resumed OAuth call
+  is the one the agent made, and a replayed grant runs nothing.
+  `wiki/operations/native-loop-security.md` is the threat model;
+  `tests/nativeFuzz.test.ts` fuzzes the loop.
+- **On the native runtime, self-correction's reflection call is signed on
+  Gemini (ADR 0103).** When a Gemini 3 model calls the reserved
+  `adk_handle_model_error` tool, or answers `MALFORMED_FUNCTION_CALL`, the
+  reflection call stored in its place now carries the replaced call's
+  `thoughtSignature`, or Gemini's documented placeholder
+  (`skip_thought_signature_validator`) when there was none, so the next
+  request no longer fails with Gemini's "missing a thought_signature" 400.
+  On Gemini 2.x only a carried signature is added. The ADK runtime is
+  unchanged: ADK's plugin still stores the call unsigned. The stored event
+  differs from ADK's by that one field. `PLACEHOLDER_THOUGHT_SIGNATURE` is
+  still exported from `melchizedek-agents/models/geminiAdapter`.
+
+- **A workflow node's `retry` takes `exceptions` and `jitter` (ADR 0103).**
+  `retry: { exceptions: [NodeTimeoutError] }` retries only a failure whose
+  error class or `name` is listed; `jitter` sets the backoff's randomness
+  (0 = none, default 1). Both runtimes honour them: the ADK runtime hands
+  them to ADK's `retryConfig`, the native scheduler applies them as ADK's
+  `retry_utils` does. `syndicate.schema.json` is regenerated; the `exports`
+  map is unchanged.
+
+- **The capability matrix's Gemini column is asserted on the engine's own
+  Gemini adapter (WS3-6, ADR 0100).** Every Gemini cell is now evidence
+  `test`, checked against the request `GeminiAdapter` sends through the
+  real `@google/genai` client, as every other column is; `npm run doctor --
+  --matrix` says so. On the native runtime a Gemini agent's stored events no
+  longer carry `turnComplete`, as the ADK runtime's never have; nothing reads
+  the field. A Gemini answer that ran code through the engine's adapter
+  (`GEMINI_ADAPTER=engine`, or `GeminiAdapter` behind the shim) now stores
+  the `executableCode` and `codeExecutionResult` parts as ADK's Gemini stores
+  them, where the session held none before; `partsToGenai` in
+  `melchizedek-agents/models/genaiMapping` is the mapping that writes them
+  out. `scripts/gemini_engine_check.ts` is the live check gate G3 runs:
+  grounding, code execution, a function tool beside server-side tools, and a
+  two-turn session, with `GeminiAdapter` on both runtimes. `GeminiAdapter`
+  becomes the default in 0.20.0 (see Breaking above).
+
+- **A workflow syndicate can be a subagent, and a workflow node can carry
+  an approval gate (WS4-7, ADR 0098).** A DELEGATE syndicate's
+  `yaml_reference` to a `workflow:` syndicate now runs the whole graph as
+  the subagent tool, under the entry's name and description, on both
+  runtimes: the graph's last output is the tool's answer. Before, only the
+  nested syndicate's orchestrator ran. A nested workflow with an
+  `ask_user` node is now refused by name at compile time (its pause could
+  not reach the caller); as a dispatch route or a workflow node, a
+  workflow syndicate is still its orchestrator alone. `require_approval`
+  on a workflow node's agent now validates (except on an agent a `map`
+  node runs): on the native runtime the gated call pauses the node and the
+  turn ends `input-required` with `result.approval`, and the person's
+  decision runs or refuses the pinned call once and walks on; another
+  message repeats the request. On the ADK runtime a gated workflow throws
+  `UnsupportedOnRuntimeError` before any model call, because ADK's resume
+  restarts the node and never runs the call. `melchizedek-agents/compile`
+  adds the `workflow` kind to `SpecTool`, and exports
+  `compileWorkflowSpec` and the `WorkflowSpec` type.
+- **A Gemini agent on the native runtime is no longer shown the reflection
+  tool (WS4-6b, ADR 0097).** With `retries.model_errors` on (the default),
+  native declared `adk_handle_model_error` to every model. ADK's own Gemini
+  never sends it, and a Gemini 3 model that called it on native failed its
+  next step with Gemini's missing `thought_signature` 400 (a workflow
+  node then failed the turn `NODE_FAILED`). Native now sends a Gemini model
+  the same tools as ADK; a model on any other provider, or a Gemini adapter
+  a resolver returns behind `adkShim`, is still told of the tool, as on ADK.
+  ADK turns are unchanged.
+
+## 0.19.0 — 2026-10-08
+
+The native runtime ships in this release as an opt-in: set
+`MELCHIZEDEK_RUNTIME=native` or pass `runtime: 'native'` to `runSyndicateTurn`.
+`adk` stays the default (ADR 0099). The `@google/adk` peer dependency is
+unchanged.
+
+### Breaking — read before upgrading
+
+- **Breaking: a skill script no longer inherits the server's environment
+  (ADR 0086).** An approved `run_skill_script` starts from PATH,
+  HOME/USERPROFILE, TMPDIR/TEMP/TMP, LANG, LC_*, TZ, the user's name and
+  the Windows essentials, and nothing else: provider keys, `DATABASE_URL`
+  and the server's bearer secrets no longer reach it. A script that relied
+  on an inherited variable must now name it in the agent's YAML, under the
+  new `skills.env` (names only), or under `skills.secret_env` when the
+  name looks like a secret (KEY, TOKEN, SECRET, PASSWORD, AUTH, DATABASE,
+  …), which `skills.env` refuses. Both need `scripts: local`. A script's
+  stdout and stderr are each cut at 20,000 characters, ending with
+  `[stdout truncated: N more characters not shown (the limit is 20000)]`.
+  The same on both runtimes. `LocalScriptExecutor` takes `envNames`,
+  `sourceEnv` and `maxOutputChars`; `lib/tools/skills/env.ts` is new. The
+  `exports` map is unchanged.
+- **Breaking for subclasses of `OpenAiCompatibleLlm`: the chat-completions
+  adapters move onto the model contract (ADR 0057).** New modules under
+  `melchizedek-agents/models/`:
+  - `chatCompletionsAdapter`: `ChatCompletionsAdapter`, the base that turns a
+    `ModelRequest` into a chat-completions body and a completion (JSON or
+    SSE) into contract responses; `ChatCompletionsRequest` and
+    `OlderSpelling`; `chatUsage` and `sumUsage` (usage in the contract's
+    meaning); `splitThinkBlocks`, `ThinkStreamSplitter`,
+    `REASONING_CONTENT_KIND` and `ENGINE_CALL_ID_PREFIX`.
+  - `ollamaAdapter` (`OllamaAdapter`), `kimiAdapter` (`KimiAdapter`, and
+    `isKimiK3`, `wantsReasoningReplay`, `MOONSHOT_BASE_URL`, which
+    `models/kimiLlm` still exports) and `gatewayAdapter` (`GatewayAdapter`).
+
+  `OpenAiCompatibleLlm` is now an `AdkShim` whose constructor takes the
+  adapter, and its protected hooks (`endpointUrl`, `headers`,
+  `wireModelName`, `extraBodyFields`, `httpError`, `noAnswerError` and the
+  rest) move to `ChatCompletionsAdapter`, on contract types. A provider of
+  your own subclasses `ChatCompletionsAdapter` and runs under ADK as
+  `adkShim(adapter)` or as an `OpenAiCompatibleLlm` subclass. `OllamaLlm`,
+  `KimiLlm` and `GatewayLlm` keep their constructors, ids, error codes and
+  wording, and the shape of what they yield: usage counts the reasoning in
+  `candidatesTokenCount` as before, so the ledger's counts are unchanged.
+  `models/openAiCompatibleLlm` adds `olderSpellingOf` and
+  `chatUsageMetadata`. `AdkShim` gains a protected `toModelRequest` seam
+  beside `toLlmResponse` (ADR 0056); the chat shims override both.
+
+  What reaches the provider changes only where the contract maps a field
+  the old classes ignored or spelled as written:
+  - `stopSequences` are sent as `stop`.
+  - A function-calling mode is honoured: `NONE` sends no tools; the gateway
+    sends `ANY` as `tool_choice: required` or the named tool, and Kimi and
+    Ollama weaken it to auto (`llm.tool_choice.weakened` on the span).
+  - The older spelling's reasoning follows ADR 0047's mapping, as
+    `reasoning:` already did: `thinkingConfig.thinkingBudget` alone now
+    travels as its level (`0` is `none`), `reasoningEffort: medium` on
+    `kimi-k3` is sent as `high`, and `minimal` as each model's `none`.
+    A word that is no level (`max`, `xhigh`) is still sent as written.
+  - A tool call stored without an id is sent with one, matched to its
+    result, where the result's `tool_call_id` was empty.
+  - The no-answer hints name `reasoning: none` (the older spelling too).
+  - Every error a chat shim yields carries its retry verdict
+    (`customMetadata['error.retryable']`, `false` where there was none) and
+    `turnComplete`. A call cut off by a cancelled turn is never retryable,
+    even when its last status was a 503, so no fallback answers a
+    cancellation.
+- **Breaking for subclasses of `GptLlm`: the vendor hooks move to
+  `GptAdapter` (ADR 0056).** `providerId()`, `baseURL()`, `apiKeyFromEnv()`,
+  `missingKeyMessage()`, `clientOptions()`, `reasoningParam()`,
+  `replaysReasoning()` and `endpoint()` are overridden on a `GptAdapter`
+  subclass now, as `GrokAdapter` does, and a `GptLlm` subclass returns it
+  from `protected static createAdapter(options)`. Code that only constructs
+  or registers `GptLlm` and `GrokLlm`, or imports their exported functions,
+  is unaffected.
+- **Breaking for one import path: `toFunctionTool` moves to
+  `melchizedek-agents/tools/adkTool` (ADR 0051).**
+  `melchizedek-agents/tools/toolContract` no longer exports it, so that
+  module loads nothing from `@google/adk`. Import it from
+  `melchizedek-agents`, which still exports it, or from the new subpath.
+  The `exports` map is unchanged.
+
+### Changes
+
 - **Workflow syndicates run on the native runtime (WS4-6, ADR 0095).**
   A `workflow:` syndicate no longer throws `UnsupportedOnRuntimeError` on
   `runtime: 'native'` (or `MELCHIZEDEK_RUNTIME=native`): the engine's own
@@ -52,7 +304,6 @@ the starter pack and the templates), not the repo's full history.
   `pendingQuestion` ignores an `ask_user` call in an event the user
   authored. A message that forges one no longer turns the next message
   into its answer, on either runtime.
-
 - **The native runtime sends a request, and reads a thrown failure, as
   ADK does (WS2-12, ADR 0084).** On `runtime: 'native'` (or
   `MELCHIZEDEK_RUNTIME=native`) a request goes out under the resolved
@@ -65,20 +316,6 @@ the starter pack and the templates), not the repo's full history.
   turn-level test suites run on both runtimes. `npm run parity` now runs
   its turns on the runtime `MELCHIZEDEK_RUNTIME` names. The `exports` map
   is unchanged.
-- **Breaking: a skill script no longer inherits the server's environment
-  (ADR 0086).** An approved `run_skill_script` starts from PATH,
-  HOME/USERPROFILE, TMPDIR/TEMP/TMP, LANG, LC_*, TZ, the user's name and
-  the Windows essentials, and nothing else: provider keys, `DATABASE_URL`
-  and the server's bearer secrets no longer reach it. A script that relied
-  on an inherited variable must now name it in the agent's YAML, under the
-  new `skills.env` (names only), or under `skills.secret_env` when the
-  name looks like a secret (KEY, TOKEN, SECRET, PASSWORD, AUTH, DATABASE,
-  …), which `skills.env` refuses. Both need `scripts: local`. A script's
-  stdout and stderr are each cut at 20,000 characters, ending with
-  `[stdout truncated: N more characters not shown (the limit is 20000)]`.
-  The same on both runtimes. `LocalScriptExecutor` takes `envNames`,
-  `sourceEnv` and `maxOutputChars`; `lib/tools/skills/env.ts` is new. The
-  `exports` map is unchanged.
 - **The skills harness no longer builds on ADK (ADR 0083).** An agent's
   `skills:` block loads, reads and runs skills through the engine's own
   modules (`lib/tools/skills/`), the same on `runtime: 'adk'` and
@@ -210,7 +447,6 @@ the starter pack and the templates), not the repo's full history.
   - The audit trail gains `credential.put`, `credential.refresh`,
     `credential.revoke` and `credential.erase` (`AuditEventName`), with the
     provider and app and never a token.
-
 - **The ledger reads the native loop's spans (ADR 0076).** The native loop
   (not yet selectable, WS2-10) opens `agent.invoke <name>`, `model.call` and
   `tool.execute <name>` spans in scope `melchizedek.runtime`, and a native
@@ -344,7 +580,6 @@ the starter pack and the templates), not the repo's full history.
   server-side name is no longer treated as that tool. An MCP tool's nested
   schemas no longer carry `default`, `propertyNames`, `$schema` or a boolean
   `additionalProperties`. `propertyNames` was refused by the Gemini API.
-
 - **The engine parses OpenAPI specs itself (ADR 0063).** A new module,
   `melchizedek-agents/tools/openapi/parse` (through the existing
   `./tools/*` pattern), exports `parseOpenApiSpec` and
@@ -386,59 +621,6 @@ the starter pack and the templates), not the repo's full history.
   quadratically on a long run of slashes (CodeQL js/polynomial-redos).
   They now share `trimTrailingSlashes` (new module
   `melchizedek-agents/models/urls`). Results are unchanged.
-- **Breaking for subclasses of `OpenAiCompatibleLlm`: the chat-completions
-  adapters move onto the model contract (ADR 0057).** New modules under
-  `melchizedek-agents/models/`:
-  - `chatCompletionsAdapter`: `ChatCompletionsAdapter`, the base that turns a
-    `ModelRequest` into a chat-completions body and a completion (JSON or
-    SSE) into contract responses; `ChatCompletionsRequest` and
-    `OlderSpelling`; `chatUsage` and `sumUsage` (usage in the contract's
-    meaning); `splitThinkBlocks`, `ThinkStreamSplitter`,
-    `REASONING_CONTENT_KIND` and `ENGINE_CALL_ID_PREFIX`.
-  - `ollamaAdapter` (`OllamaAdapter`), `kimiAdapter` (`KimiAdapter`, and
-    `isKimiK3`, `wantsReasoningReplay`, `MOONSHOT_BASE_URL`, which
-    `models/kimiLlm` still exports) and `gatewayAdapter` (`GatewayAdapter`).
-
-  `OpenAiCompatibleLlm` is now an `AdkShim` whose constructor takes the
-  adapter, and its protected hooks (`endpointUrl`, `headers`,
-  `wireModelName`, `extraBodyFields`, `httpError`, `noAnswerError` and the
-  rest) move to `ChatCompletionsAdapter`, on contract types. A provider of
-  your own subclasses `ChatCompletionsAdapter` and runs under ADK as
-  `adkShim(adapter)` or as an `OpenAiCompatibleLlm` subclass. `OllamaLlm`,
-  `KimiLlm` and `GatewayLlm` keep their constructors, ids, error codes and
-  wording, and the shape of what they yield: usage counts the reasoning in
-  `candidatesTokenCount` as before, so the ledger's counts are unchanged.
-  `models/openAiCompatibleLlm` adds `olderSpellingOf` and
-  `chatUsageMetadata`. `AdkShim` gains a protected `toModelRequest` seam
-  beside `toLlmResponse` (ADR 0056); the chat shims override both.
-
-  What reaches the provider changes only where the contract maps a field
-  the old classes ignored or spelled as written:
-  - `stopSequences` are sent as `stop`.
-  - A function-calling mode is honoured: `NONE` sends no tools; the gateway
-    sends `ANY` as `tool_choice: required` or the named tool, and Kimi and
-    Ollama weaken it to auto (`llm.tool_choice.weakened` on the span).
-  - The older spelling's reasoning follows ADR 0047's mapping, as
-    `reasoning:` already did: `thinkingConfig.thinkingBudget` alone now
-    travels as its level (`0` is `none`), `reasoningEffort: medium` on
-    `kimi-k3` is sent as `high`, and `minimal` as each model's `none`.
-    A word that is no level (`max`, `xhigh`) is still sent as written.
-  - A tool call stored without an id is sent with one, matched to its
-    result, where the result's `tool_call_id` was empty.
-  - The no-answer hints name `reasoning: none` (the older spelling too).
-  - Every error a chat shim yields carries its retry verdict
-    (`customMetadata['error.retryable']`, `false` where there was none) and
-    `turnComplete`. A call cut off by a cancelled turn is never retryable,
-    even when its last status was a 503, so no fallback answers a
-    cancellation.
-- **Breaking for subclasses of `GptLlm`: the vendor hooks move to
-  `GptAdapter` (ADR 0056).** `providerId()`, `baseURL()`, `apiKeyFromEnv()`,
-  `missingKeyMessage()`, `clientOptions()`, `reasoningParam()`,
-  `replaysReasoning()` and `endpoint()` are overridden on a `GptAdapter`
-  subclass now, as `GrokAdapter` does, and a `GptLlm` subclass returns it
-  from `protected static createAdapter(options)`. Code that only constructs
-  or registers `GptLlm` and `GrokLlm`, or imports their exported functions,
-  is unaffected.
 - **Fix: a message could stall the server in the memory search.**
   `stripHarnessBlocks` (run on every memory query and extraction
   transcript) matched an unclosed `[System Context:` marker with a pattern
@@ -490,12 +672,6 @@ the starter pack and the templates), not the repo's full history.
   `melchizedek-agents/models/claudeModels` adds `ClaudeReasoning`,
   `claudeReasoningOf`, `claudeReasoningFromConfig` and
   `adaptiveThinkingFor`. The `exports` map is unchanged.
-- **Breaking for one import path: `toFunctionTool` moves to
-  `melchizedek-agents/tools/adkTool` (ADR 0051).**
-  `melchizedek-agents/tools/toolContract` no longer exports it, so that
-  module loads nothing from `@google/adk`. Import it from
-  `melchizedek-agents`, which still exports it, or from the new subpath.
-  The `exports` map is unchanged.
 - **The session services serve both runtimes from the same rows, and
   change behaviour in five places (ADR 0058).** `SupabaseSessionService`,
   `PostgresSessionService` and `ProjectedSessionService` also implement

package/DOCUMENTATION.md

@@ -56,11 +56,17 @@ 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
+`lib/compileNative.ts` into the engine's own loop's agent. Since 0.20.0
+the native loop runs every turn by default
+([ADR 0102](./wiki/decisions/0102-native-default-and-optional-adk-peer.md)):
+`@google/adk` is an optional peer, needed only when
+`MELCHIZEDEK_RUNTIME=adk`, or `runtime: 'adk'` on `runSyndicateTurn`,
+selects ADK's Runner, which 1.0.0 removes; without it that choice fails
+before the session is touched, naming the package, and
+`npx melchizedek-doctor` prints the runtime in use and whether ADK is
+installed. The native loop runs a single-agent, delegating or
+plan-dispatch syndicate with the same result and the same stored events
+the ADK runtime writes, `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
@@ -788,7 +794,8 @@ without a model call. ADK pins the call and its arguments, so an approval
 cannot run a different call.
 
 Gates are allowed on the orchestrator and on the subagents of a
-plan-dispatch syndicate, which run as the turn's own agent. A delegated
+plan-dispatch syndicate, which run as the turn's own agent, and on the
+agent nodes of a workflow on the native runtime (§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
@@ -1199,7 +1206,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 +1235,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);
+**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. Gates on workflow nodes run on the native runtime only: on
+ADK, `runSyndicateTurn` refuses such a workflow with
+`UnsupportedOnRuntimeError` before any model call, because ADK's resume
+starts the node afresh and never runs the pinned call. The schema refuses
+a gate on an agent a `map` node runs.
+
+**As a subagent.** A DELEGATE syndicate's `yaml_reference` to a workflow
+syndicate runs the whole graph as the subagent tool, under the entry's
+name and description: the graph's last output is the tool's answer, and
+its events are kept in the subagent's own session, as for any subagent.
+A nested workflow may not have an `ask_user` node (a pause inside a tool
+call cannot reach the caller); it is refused by name. As a dispatch route
+or a workflow node, a workflow syndicate is still its orchestrator alone.
+
+**Not yet.** Skill scripts (`skills.scripts: local`) and 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) and
+[ADR 0098](./wiki/decisions/0098-workflow-subagent-and-node-approvals.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`.
+On native, a conversation paused inside an agent node on anything but an
+approval, or inside a map item (which only ADK resumes), fails the next
+turn with `RESUME_UNSUPPORTED`.
 
 ## 7. Extending the framework
 

package/QUICKSTART.md

@@ -180,14 +180,13 @@ 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               # @google/adk only for MELCHIZEDEK_RUNTIME=adk
 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, asAdkSessionService, loadSyndicate, registerAvailableProviders, runSyndicateTurn } from 'melchizedek-agents';
 
 registerAvailableProviders();                 // registers every model whose key is present
 const config = loadSyndicate('mine.yaml');    // reads <your-repo>/config/agents/mine.yaml
@@ -196,7 +195,7 @@ const result = await runSyndicateTurn({
   config,
   parts: [{ text: 'Hello' }],
   appName: 'my-app', userId: 'u1', sessionId: 'c1',
-  sessionService: new InMemorySessionService(),
+  sessionService: asAdkSessionService(new InProcessSessionService()),
 });
 console.log(result.text);
 ```
@@ -222,8 +221,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.
+- **Native by default; ADK optional.** Since 0.20.0 every turn runs on the
+  engine's own loop. `@google/adk` is an optional peer: install it
+  (`npm install @google/adk@~2.2.0`) and set `MELCHIZEDEK_RUNTIME=adk` to
+  run on ADK, which 1.0.0 removes; your app then owns the ADK version.
+  `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:

package/README.md

@@ -73,11 +73,12 @@ Install into your existing project:
 npm install melchizedek-agents
 ```
 
+`@google/adk` is an optional peer since 0.20.0: install it beside the package (`npm install @google/adk@~2.2.0`) only to run on the `adk` runtime.
+
 Define your agents in `./config/agents/mine.yaml`, then run turns programmatically:
 
 ```typescript
-import { InMemorySessionService } from '@google/adk';
-import { loadSyndicate, registerAvailableProviders, runSyndicateTurn } from 'melchizedek-agents';
+import { InProcessSessionService, asAdkSessionService, loadSyndicate, registerAvailableProviders, runSyndicateTurn } from 'melchizedek-agents';
 
 // 1. Register a provider for every key that is set
 registerAvailableProviders();
@@ -92,7 +93,7 @@ const result = await runSyndicateTurn({
   appName: 'my-app',
   userId: 'user-42',
   sessionId: 'conversation-7', // same id, same conversation
-  sessionService: new InMemorySessionService(),
+  sessionService: asAdkSessionService(new InProcessSessionService()),
   events: {
     onProgress: (line) => console.log('…', line)
   },
@@ -101,7 +102,7 @@ const result = await runSyndicateTurn({
 console.log(result.status, result.text);
 ```
 
-`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`.
+`runSyndicateTurn` is the same runtime the server, CLI, and eval harness use. Since 0.20.0 it runs every syndicate on the engine's own loop and scheduler (the `native` runtime) by default. `MELCHIZEDEK_RUNTIME=adk` (or `runtime: 'adk'`) runs it on Google ADK instead, with `@google/adk` installed, until 1.0.0 removes that runtime; `npx melchizedek-doctor` prints the runtime in use and whether ADK is installed ([ADR 0102](./wiki/decisions/0102-native-default-and-optional-adk-peer.md)). 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.
 
@@ -118,11 +119,7 @@ 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
-```
+`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`. Since 0.20.0 ADK is an optional peer, so `npm install melchizedek-agents` leaves it out; the other peers (redis, the cloud SDKs) are optional too.
 
 ```typescript
 import { ClaudeAdapter, OllamaAdapter, resolveAdapter } from 'melchizedek-agents/model';

package/config/agents/syndicateSchema.yaml

@@ -154,6 +154,9 @@ dispatch:
 #     Each:    { map: "MySubagent", max_parallel: 4 }   # one run per list item
 #     Lookup:  { tool: "web_extract" }             # a registry tool as a node
 #     Review:  { retry: { max_attempts: 2, initial_delay: 1 }, timeout: 120 }
+#     # retry also takes max_delay, backoff_factor, jitter (0 = none) and
+#     # exceptions: [NodeTimeoutError] (retry only on these error names).
+#     # A map node takes neither retry nor timeout: set them on its agent.
 #     Confirm: { ask_user: "Publish? Reply yes, or say what to change." }
 #   max_concurrency: 4
 

package/dist/lib/adkPeer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * lib/adkPeer.ts — @google/adk as an optional peer (ADR 0102).
+ *
+ * WHY this file exists:
+ *   From 0.20.0 the native runtime is the default, and @google/adk is needed
+ *   only for MELCHIZEDEK_RUNTIME=adk and the features only ADK runs. Until
+ *   1.0.0 removes ADK (ADR 0045), the engine's objects still carry an ADK
+ *   face: the tool registry holds FunctionTools that carry their own Tool,
+ *   the model shims are BaseLlm classes that carry their contract adapter,
+ *   and the durable session stores are ADK BaseSessionServices as well as
+ *   the engine's SessionService. Those classes extend ADK's at load time.
+ *
+ *   This module is the one place the package loads ADK. It tries once, when
+ *   it is first imported, and every other module takes ADK's values from
+ *   here, never from '@google/adk' directly (a type-only import is fine):
+ *   - When ADK is installed, each export below IS ADK's own value, so the
+ *     ADK runtime, `instanceof` and ADK's registry behave exactly as before.
+ *   - When it is not, the base classes are stand-ins: they construct as
+ *     ADK's do (a tool's name, a model's id, a toolset's filter) and carry
+ *     ADK's own Symbol.for marks, so the engine reads them as it reads ADK's,
+ *     and every method only ADK calls throws AdkNotInstalledError, which
+ *     names the package. Everything else (`Runner`, `LlmAgent`, the plugins)
+ *     is reached through requireAdk(feature), which throws the same error.
+ *
+ *   A package that is installed but fails to load for another reason (a
+ *   missing dependency of its own, a syntax error) is not "absent": that
+ *   error is rethrown, so nothing hides a broken install.
+ *
+ * The load is a top-level await of a dynamic import: an ES module cannot
+ * load another synchronously, and the exported classes must exist before
+ * any subclass is defined.
+ */
+import type * as AdkModule from '@google/adk';
+/** The package this module loads. */
+export declare const ADK_PACKAGE = "@google/adk";
+/** @google/adk's module namespace, as its types describe it. */
+export type Adk = typeof AdkModule;
+/** ADK's module when it is installed, else undefined. */
+export declare const adk: Adk | undefined;
+/** Whether @google/adk is installed and loaded. */
+export declare function adkInstalled(): boolean;
+/** The installed @google/adk version, read from its package.json, or undefined when it is not installed. */
+export declare function adkVersion(): Promise<string | undefined>;
+/** A feature only ADK runs was used without @google/adk installed. */
+export declare class AdkNotInstalledError extends Error {
+    readonly feature: string;
+    constructor(feature: string);
+}
+/** ADK's module, or AdkNotInstalledError naming `feature` when it is not installed. */
+export declare function requireAdk(feature: string): Adk;
+export declare const BaseTool: Adk['BaseTool'];
+export type BaseTool = AdkModule.BaseTool;
+export declare const FunctionTool: Adk['FunctionTool'];
+export type FunctionTool<TParameters extends AdkModule.ToolInputParameters = undefined> = AdkModule.FunctionTool<TParameters>;
+export declare const BaseToolset: Adk['BaseToolset'];
+export type BaseToolset = AdkModule.BaseToolset;
+export declare const BaseLlm: Adk['BaseLlm'];
+export type BaseLlm = AdkModule.BaseLlm;
+export declare const Gemini: Adk['Gemini'];
+export type Gemini = AdkModule.Gemini;
+export declare const BaseSessionService: Adk['BaseSessionService'];
+export type BaseSessionService = AdkModule.BaseSessionService;
+export declare const GOOGLE_SEARCH: Adk['GOOGLE_SEARCH'];