melchizedek-agents 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,1007 @@ Consumers of the package read this file; it records changes to the
 **published API surface** (the exports map in `package.json`, the bins,
 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
+  scheduler walks the graph, and `runSyndicateTurn` returns the same
+  result, stored events, progress lines, `answer.nodeErrors`, text deltas
+  and ledger rows as on ADK. An `ask_user` node pauses the turn
+  `input-required` with `result.input`, and the next message resumes it,
+  also in a session ADK paused. Two new outcomes on native: a session
+  paused inside an agent node or a map item (which only ADK resumes) fails
+  the turn with error code `RESUME_UNSUPPORTED` instead of starting the
+  graph again, and an `ask_user` tool on a workflow node's agent in a
+  config that skipped validation throws `UnsupportedOnRuntimeError`
+  before any model call (the schema refuses it on both runtimes). A
+  native workflow turn traces `workflow.invoke`, `node.execute` and
+  `tool.execute` spans, so each model call's ledger row names its node's
+  agent. ADK turns are unchanged.
+- **Ollama structured output enforces the schema (ADR 0096).** An
+  `ollama/` agent with an `outputSchema` now sends `response_format:
+  json_schema` with the schema in its strict form, as Kimi and the gateway
+  do, where it sent `json_object` and the schema was not enforced. JSON
+  mode without a schema still sends `json_object`. Ollama 0.5.0 or later is
+  required for the schema to hold: an older server ignores it and answers
+  in free text. The capability matrix and `npm run doctor` now report
+  Ollama's structured output as supported.
+- **A Gemini `MALFORMED_FUNCTION_CALL` from a contract adapter is
+  retried (WS2-15, ADR 0088).** `modelResponseToLlmResponse`
+  (`melchizedek-agents/models/genaiMapping`) now sets `finishReason` to an
+  error's code when the code is one of Gemini's finish reasons, as ADK's
+  Gemini reports both. Self-correction (`retries.model_errors`) then
+  retries a malformed function call on both runtimes, where it used to fail
+  the turn on native and behind a shim. A stored Gemini error event can
+  carry its own finish reason (`RECITATION`, say) where it carried
+  `SAFETY` or `OTHER`.
+- **On native, a custom ADK model class from `resolveModel` is refused
+  (WS2-15, ADR 0088).** A `compile.resolveModel` that returns an ADK
+  `BaseLlm` which is neither a shim nor ADK's Gemini now makes a
+  `runtime: 'native'` turn throw `UnsupportedOnRuntimeError` before any
+  model call. This covers an agent's model, a subagent's,
+  `fallback_model` and `summary_model`. Native used to run the registry's
+  model for that id instead. To run such a model on native, return its
+  `ModelAdapter`, or `adkShim(adapter)` from
+  `melchizedek-agents/models/adkShim`. ADK turns are unchanged.
+- **A user-authored `ask_user` call is no question (WS2-15, ADR 0088).**
+  `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
+  model's own id, as ADK's `LlmAgent` sends it, so a `resolveModel` that
+  answers a YAML id with a model under another id (a gateway stand-in, an
+  alias) gets that model's thinking and reasoning replay. A model that
+  throws no longer throws out of `runSyndicateTurn`: the turn fails on
+  ADK's `UNKNOWN_ERROR` event (or a JSON error body's code), and a thrown
+  provider-side failure is answered by `fallback_model`, as on ADK. The
+  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.
+- **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
+  `'native'`. A model sees the same tools, parameters, results and error
+  texts as before. Breaking for code that imports
+  `melchizedek-agents/tools/skillToolset` directly:
+  `HarnessSkillToolset` is now an engine Toolset rather than ADK's
+  `SkillToolset`, so wrap it with `toAdkToolset`
+  (`melchizedek-agents/tools/adkTool`) before handing it to an ADK
+  `LlmAgent`. `LeanLoadSkillTool` and `GatedRunSkillScriptTool` are now
+  engine Tools (`execute(args, ctx)`), not ADK `BaseTool`s. Frontmatter
+  YAML is read by the `yaml` package, so a timestamp stays a string and
+  `<<` merge keys are not merged. A SKILL.md over 1 MiB and a resource
+  file over 8 MiB are not loaded. `lib/tools/tool.ts` adds `Toolset`,
+  `ToolsetContext`, `isOwnToolset`, `toolsetOf` and an optional
+  `Tool.contents` hook. The `exports` map is unchanged.
+- **OAuth consent for tool credentials (ADR 0085).** On the native
+  runtime, `runSyndicateTurn` takes `toolCredentials: { store, consent }`
+  (both optional additions). `store` is the sealed credential store of ADR
+  0072, and `consent` is `oauthConsent({ providers, redirectUri,
+  credentials })` from `melchizedek-agents/tools/oauthConsent`.
+  - When a call's provider is not granted, `ctx.accessToken(provider)`
+    asks for consent by itself, or a tool calls the new
+    `ctx.requestCredential(provider)`. The turn ends `input-required` with
+    `result.consent` (`id`, `agent`, `provider`, `authUri`, `state`,
+    `scopes`), stored as ADK's own `adk_request_credential` call with no
+    secret in it.
+  - The person's next message, after the grant is stored, runs the paused
+    call again. Until then, a message repeats the request and runs nothing.
+  - `createA2AApp` takes the same `toolCredentials` (plus `callbackLimit`
+    and `requireCallerIdentity`, default true: the callback refuses a
+    browser that does not carry the flow's user's identity). It publishes a `consent_request` data part
+    beside `approval_request` and `input_request`, and mounts the consent
+    callback at the path of the redirect URI. The callback completes the
+    authorization-code flow with PKCE S256 and stores the grant.
+  - New exports, all through existing entries: `./a2a` gains
+    `consentCallback`. `./runtime` gains `pendingConsent`,
+    `credentialResponsePart`, `describeConsent`, `CREDENTIAL_REQUEST` and
+    the types `PendingConsent` and `ToolCredentials`. `./tools/*` gains the
+    new module `oauthConsent`.
+  - Also additive: `RouteDecision.decidedBy` gains `'consent'`, the audit
+    trail gains the `consent.callback` event, and `ToolContext` gains
+    `requestCredential`.
+  - On the ADK runtime, an open consent request throws
+    `UnsupportedOnRuntimeError`.
+  - No change to the `exports` map.
+- **A question is answered on the native runtime (ADR 0079).** On
+  `runtime: 'native'` (or `MELCHIZEDEK_RUNTIME=native`), a plain-text
+  message that answers an open `ask_user` call no longer throws
+  `UnsupportedOnRuntimeError`: it becomes the call's response and the agent
+  that asked resumes, in plan-dispatch the route, as on ADK. Both runtimes
+  store the same events, so a question opened on either is answered on the
+  other; `result.input` and the A2A `input_request` part are unchanged. No
+  change to the `exports` map.
+- **`mode: task` runs on the native runtime (ADR 0081).** It no longer
+  throws `UnsupportedOnRuntimeError`: the agent's requests declare
+  `finish_task` as ADK's do, and its answers are stored as ADK stores them.
+  A `workflow:` syndicate, where task-mode nodes live, is still refused on
+  native. `code_execution: gemini` runs on native with the same stored
+  events as on ADK. No change to the exports map.
+- **An approval resumes on the native runtime (ADR 0077).** On
+  `runtime: 'native'`, a message carrying `approvalResponsePart(id, …)` runs
+  or refuses the pinned call before the agent's next step, as on ADK, and
+  stores the same events: an approval opened on either runtime resumes on
+  the other. An answer whose pinned call does not bind (changed arguments,
+  a request the user authored) throws ADK's `IntentMismatchError` text on
+  both runtimes. No change to the `exports` map.
+- **`createA2AApp` takes the engine's own stores (ADR 0080).**
+  `A2AAppOptions.storage.sessionService` accepts the engine's
+  `SessionService` as well as ADK's `BaseSessionService`, and
+  `storage.memoryService` the engine's `MemoryService` as well as ADK's
+  `BaseMemoryService`; a store or service you pass today works unchanged.
+  Without durable storage, sessions live in the engine's
+  `InProcessSessionService` instead of ADK's `InMemorySessionService`, with
+  the durable stores' meaning (no `app:` or `user:` state shared across
+  sessions). `resolveModel` returns what `CompileOptions.resolveModel`
+  returns, the same type as before. The `melchizedek-serve` bin no longer
+  imports `@google/adk`; ADK's logger follows the level the engine sets.
+  No change to the `exports` map, `runSyndicateTurn`, or the A2A surface.
+- **`context:` compaction runs on the native runtime (ADR 0078).** A
+  syndicate whose orchestrator sets `context:` no longer throws
+  `UnsupportedOnRuntimeError` under `runtime: 'native'`
+  (or `MELCHIZEDEK_RUNTIME=native`): the native loop compacts as the ADK
+  runtime does, stores the same compacted event, and charges and traces the
+  summary call the same way, so a compacted session continues on either
+  runtime. No change to the exports map; `ContextConfig` and
+  `DEFAULT_KEEP_RECENT_EVENTS` stay exported from
+  `melchizedek-agents/compile` under the same names.
+- **A turn can run on the native runtime (ADR 0073).** `runSyndicateTurn`
+  takes an optional `runtime` (`'adk'` or `'native'`). Without it,
+  `MELCHIZEDEK_RUNTIME` decides (`adk` or `native`), and without that, `adk`,
+  so nothing changes unless you ask. On `native` a single-agent, DELEGATE
+  or plan-dispatch syndicate runs on the engine's own loop, with
+  self-correction from `retries:` and the same root span, and returns the
+  same result shape; what native does not run yet (compaction, workflows,
+  task mode, `transformAgent`, answering a question) throws `UnsupportedOnRuntimeError` before any model call. Additions under the existing `exports` map:
+  - `melchizedek-agents/runtime` exports `RuntimeName`, `RUNTIMES`,
+    `DEFAULT_RUNTIME`, `chooseRuntime`, `runtimeSetting` and
+    `UnsupportedOnRuntimeError`.
+  - `melchizedek-agents/compile` exports `AgentSpec`, `SpecTool`,
+    `compileSpec` and `compileSubagentSpec`, the runtime-neutral half of the
+    compiler. `compileGraph` and `compileSubagent` build the same `LlmAgent`
+    as before.
+  - `melchizedek-agents/wiki/agentRun`: `runWikiAgent` follows the same
+    flag, and takes `runtime` and (native only) `adapterFor`.
+  - `.env.example` lists `MELCHIZEDEK_RUNTIME` and `GEMINI_ADAPTER`.
+- **Third-party tokens for tools, sealed per end user (ADR 0072).** Apply
+  migration `0013_tool_credentials.sql` (`npx melchizedek-db apply`, or
+  `print` into the SQL editor) before using it. New, all under the existing
+  `exports` map:
+  - `melchizedek-agents/tools/auth`: the `CredentialStore` interface (`put`,
+    `get` with refresh, `revoke`, `eraseUser`), `OAuthProvider` (`refresh`,
+    `revoke` hooks), `ToolCredentialError`, `toolAccessToken` and
+    `pinnedCredentialStore`.
+  - `melchizedek-agents/tools/credentialStore`: `credentialStore({ rows,
+    cipher, providers, audit })` and `memoryCredentialRows()`.
+  - `melchizedek-agents/tools/credentialCipher`: the `CredentialCipher` plug
+    point, `aesGcmCipher` (AES-256-GCM) and `credentialCipherFromEnv`, which
+    reads the new `MELCHIZEDEK_CREDENTIAL_KEY` (32 bytes, base64 or hex).
+  - `storage/postgres`: `postgresStorage({ credentials: { cipher, providers }
+    })` adds `storage.credentials`; `postgresCredentialRows` and
+    `postgresCredentialStore` are exported.
+  - `tools/tool`: `ToolContext.accessToken(provider)`, a valid token for the
+    run's own app and user, present when `createToolContext` is given
+    `credentials`. No built-in tool uses it yet.
+  - `EraseCounts` gains `credentials`: `melchizedek_erase_scope` and
+    `DELETE /memory` remove the user's tokens too. A custom `storage.erase`
+    that builds its own counts adds the field.
+  - 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
+  run writes the same `adk_turns`, `adk_telemetry` and `adk_payloads` rows as
+  an ADK run. `melchizedek-agents/observability/lineage` exports
+  `ADK_SPAN_SCOPE`, `RUNTIME_SPAN_SCOPE`, `agentOfSpanName`,
+  `isToolSpanName` and `isModelCallSpan`. In `observability/tracer`,
+  `agentForSpan` also walks up to an `agent.invoke` span, tool time also
+  sums `tool.execute` spans, and the console exporter keeps the
+  `melchizedek.runtime` scope quiet as it keeps ADK's
+  (`OTEL_CONSOLE_ALL_SPANS=true` prints both). In
+  `observability/supabaseSpanExporter`, `isPayloadSpan` also takes a
+  `model.call` span that carries `llm.payload.*`, and `toPayloadRow` reads
+  `adk.invocation_id` before the turn's.
+- **New entry `melchizedek-agents/model`: the model layer without ADK
+  (ADR 0068).** A new path in the `exports` map, so the version is 0.19.0.
+  It exports the model contract's types, `ClaudeAdapter`, `GptAdapter`,
+  `GrokAdapter`, `ChatCompletionsAdapter`, `KimiAdapter`, `OllamaAdapter`,
+  `GatewayAdapter`, `GeminiAdapter`, `resolveAdapter`,
+  `resolveAdapterWithFallback`, `geminiAdapterSetting`, `FallbackAdapter`,
+  `isProviderError`, the circuit breaker's helpers (`breakerSettings`,
+  `circuitOpen`, `recordFailure`, `recordSuccess`, `resetCircuits`) and the
+  prefix table (`PROVIDERS`, `providerForModel`, `providerKeyPresent`), and
+  loads no `@google/adk`: install with `--legacy-peer-deps` to leave ADK out.
+  - 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` is
+    unchanged (`AdkGeminiAdapter` by default until gate G3).
+  - New module `melchizedek-agents/models/adapterResolver` (through
+    `./models/*`): `adapterResolver`, `routeFor`, `scopedKey`,
+    `normalizeProvider`, `geminiAdapterSetting` and the resolver types.
+    `models/registry` still exports `geminiAdapterChoice`,
+    `GeminiAdapterChoice` and `ResolveAdapterOptions`.
+  - New module `melchizedek-agents/tools/xaiSearchParams` holds
+    `xaiWebSearchParamsFromEnv`, `xSearchParamsFromEnv`,
+    `collectionIdsFromEnv` and `collectionsMaxResultsFromEnv`, which
+    `tools/webSearchTool`, `tools/xSearchTool` and
+    `tools/collectionsSearchTool` still re-export.
+- **Kimi forces a tool where Moonshot allows it** (checked live on
+  2026-10-08). `kimi-k3` sends `toolChoice: 'required'` as asked and a
+  named tool as `tool_choice: "required"` (Moonshot refuses a named tool
+  while K3 thinks, and K3 always thinks); `kimi-k2.6` sends both forced
+  modes as asked when `reasoning` is `none`, and weakens them to auto
+  otherwise. Other Kimi ids keep weakening both to auto. A weakened choice
+  is still marked `llm.tool_choice.weakened` on the span. In the
+  chat-completions base, a subclass's `toolChoiceModes` now also receives
+  the request's reasoning.
+- **Fix: `kimi-k2.7-code` with `reasoning: none`.** It sends no thinking
+  field (the model thinks at its default) instead of
+  `thinking: { type: 'disabled' }`, which Moonshot refuses for K2.7 Code
+  and its highspeed variant. `kimi-k2.6` still sends `disabled`.
+- **The genai mapping exports two more readers (ADR 0066).**
+  `melchizedek-agents/models/genaiMapping` adds `toolChoiceOf` (an agent's
+  function-calling mode as a `ToolChoice`, and `VALIDATED` as strict tools)
+  and `samplingOf` (the sampling fields the contract carries). These are
+  additions under the existing `exports` map. The native loop
+  (`lib/runtime/native/`: one model step, and the agent loop around it,
+  ADR 0071) is not in the `exports` map and runs no turn yet.
+- **OpenAPI tools make their own calls (ADR 0067).** Each operation is
+  the engine's own Tool, and the ADK runtime runs it through
+  `toFunctionTool`; ADK's `RestApiTool` and `OpenAPIToolset` are no longer
+  used. An API receives the same request as before. What a consumer sees:
+  - `tools/openapiTools`: `buildOpenApiTools` returns `FunctionTool`s
+    (it returned `BaseTool`s), and gains `buildOpenApiOwnTools` (own Tools,
+    for either runtime) and `openApiOperationId`. `boundResult` is
+    deprecated in favour of `capResult` (`tools/tool`).
+  - The new module `tools/openapi/call` holds the caller: `buildRequest`,
+    `callOperation`, `hostProblem`, `OPENAPI_REDIRECTS`, `redactSecrets`
+    and `MAX_RESPONSE_BYTES`.
+  - `require_approval` on an OpenAPI operation uses the gate every
+    registry tool uses, so the approval hint and the pending and rejected
+    texts are ADK's FunctionTool texts. `requireApprovalOnBaseTool`
+    (`compile`) is deprecated and no longer used.
+  - A credential's value is replaced with `[redacted]` in every error an
+    OpenAPI tool returns; at most 8 MiB of a response is read; an operation
+    whose spec requires a credential is not called when the entry sets no
+    `auth`, and returns an error saying so.
+  - A spec that is not OpenAPI 3.x (Swagger 2.0, or no `openapi` version)
+    fails the compile with a readable error, and `~1` and `~0` in a
+    `$ref` are unescaped.
+- **`GeminiAdapter` covers Gemini's own features (ADR 0065).** In
+  `melchizedek-agents/models/geminiAdapter` (which `resolveAdapter`
+  returns only with `GEMINI_ADAPTER=engine` until gate G3):
+  - Code execution (`executableCode`, `codeExecutionResult`) and
+    server-side `toolCall` / `toolResponse` parts ride whole on the next
+    output part as `providerState` of the new kind `CARRIED_PARTS_KIND`
+    (`carried_parts`, payload `CarriedParts`), and are replayed before it
+    within the current turn.
+  - `toolConfig.includeServerSideToolInvocations` is sent when native
+    tools sit beside function declarations, on the Gemini API only.
+  - Grounding citations carry the answer span each supports, and
+    urlContext's retrieved pages are cited.
+  - Call ids minted by the genai mapping (`genai-noid-`) stay off the wire,
+    as `adk-` ids do. `MINTED_CALL_ID_PREFIX` now lives in
+    `models/geminiState` and is still exported by `models/genaiMapping`.
+  - The adapter reads only `request.signal`; it no longer falls back to the
+    turn's signal (ADR 0053: the caller passes it).
+  - New option `placeholderSignatures` (default
+    `PLACEHOLDER_SIGNATURES_BY_DEFAULT`, false) sends Gemini's documented
+    placeholder `PLACEHOLDER_THOUGHT_SIGNATURE` on an unsigned current-turn
+    call.
+- **Fix: Gemini on Vertex AI.** The compiler asks every agent's config for
+  `includeServerSideToolInvocations`, which `@google/genai` refuses on a
+  Vertex AI client before sending anything ("only supported in Gemini
+  Developer API mode"), so every Gemini call with `GEMINI_PLATFORM=vertex`
+  failed. `TracedGemini` now leaves the flag off on Vertex AI and keeps it
+  on the Gemini API.
+- **Web sources for Claude, GPT and Grok.** When one of these models
+  searches the web, its events now carry `groundingMetadata`, so a turn's
+  grounding and the A2A server's web-sources lines list the pages it used,
+  as they already did for Gemini. Before, only Gemini's answers showed
+  their sources.
+- **Server-side tools are markers, and MCP, remote-agent and examples tools
+  are the engine's own (ADR 0062).** All additions, under the existing
+  `exports` map:
+  - `melchizedek-agents/tools/tool` gains `NativeToolMarker`,
+    `nativeToolMarker`, `nativeToolMarkerOf`, `isNativeToolMarker` and the
+    `NATIVE_TOOL` symbol. The new module `tools/nativeTools` holds the
+    markers for `web_search`, `x_search`, `url_context`,
+    `collections_search` and `google_search`;
+  - `tools/adkTool` gains `toAdkNativeTool` and `toAdkTool`, and
+    `registerTool` takes a marker;
+  - `tools/mcpToolFactory` gains `loadMcpTools` (own Tools) and
+    `mcpToolParameters`;
+  - `a2a/remote` gains `remoteAgentOwnTool`;
+  - the new module `tools/examples` holds an agent's `examples:` as an
+    InstructionTool that writes ADK's ExampleTool block word for word.
+
+  `nativeToolOf`, `wantsWebSearch` and the other sentinel checks now read
+  the marker, not the class. A tool that only declares nothing under a
+  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
+  `parseOpenApiDocument`. They read an OpenAPI 3 spec into
+  `OpenApiOperation`s, each with its arguments and the `ToolDeclaration`
+  the model receives. `openapi:` tools keep their names and declarations:
+  the parser follows ADK's rules, and `buildOpenApiTools` builds the
+  same ADK tools from it. A spec is now bounded. A file over 4 MiB, more
+  than 100 YAML aliases, more than a million values once its `$ref`s are
+  resolved, or nesting deeper than 128 levels fails the compile with a
+  readable error, as does a spec that is not an object. `toSnake` and
+  `namesTool` are still exported from `tools/openapiTools`.
+- **JSON mode without a schema is on the model contract (ADR 0061).**
+  `ModelRequest` (`melchizedek-agents/models/contract`) gains
+  `outputFormat?: 'json'`. An agent with
+  `generateContentConfig.responseMimeType: "application/json"` and no
+  schema sends its provider's JSON mode again on GPT and Grok
+  (`text.format: { type: 'json_object' }`, as before they moved onto the
+  contract), and keeps it on Kimi, Ollama, the gateway and Gemini, on the
+  ADK runtime and on the contract. Claude, whose Messages API has no JSON
+  mode, sends nothing for it, as before. `OlderSpelling.jsonMode`
+  (`models/chatCompletionsAdapter`, new in this release) is removed:
+  the chat-completions adapters read `outputFormat` instead.
+- **The engine's own registry (ADR 0060).** `melchizedek-agents/models/registry`
+  adds `resolveAdapter(modelId, { apiKey, keyProvider, endpoint, gemini })`,
+  which returns any model id's `ModelAdapter` on the engine's contract from
+  the same prefix table, gateway fallback, BYOK scoping and endpoints as
+  `resolveModel`, with no ADK `LLMRegistry`; `resolveAdapterWithFallback`,
+  which wraps a model and its fallback in a `FallbackAdapter`;
+  `geminiAdapterChoice` and the types `ResolveAdapterOptions` and
+  `GeminiAdapterChoice`. A Gemini id gets `AdkGeminiAdapter` unless
+  `GEMINI_ADAPTER=engine` (or `gemini: 'engine'`) selects `GeminiAdapter`.
+  `TracedGemini` moves to the new module `melchizedek-agents/models/tracedGemini`;
+  `models/registry` still exports it. `registerAvailableProviders`,
+  `resolveModel`, `providerStatuses` and the doctor are unchanged.
+- **Base URLs lose their trailing slashes in one pass.** The Kimi
+  adapter, the gateway, the endpoints module and the embeddings provider
+  trimmed a base URL with a regular expression that backtracked
+  quadratically on a long run of slashes (CodeQL js/polynomial-redos).
+  They now share `trimTrailingSlashes` (new module
+  `melchizedek-agents/models/urls`). Results are unchanged.
+- **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
+  that rescanned the rest of the text once per marker, so a message of
+  many such markers took seconds per search (16 s for 800,000 characters).
+  The pattern now stops at any bracket and scans the text once.
+- **Memory and its tools are the engine's own (ADR 0059).** Additions
+  only; the `exports` map is unchanged.
+  - `load_memory` and `preload_memory` are the engine's own tools, in the
+    new module `melchizedek-agents/tools/memoryTools` (`loadMemoryTool`,
+    `preloadMemoryTool`). A model reads the same declaration, the same
+    memory note and the same recalled block as with ADK's tools. Two
+    differences: a call without a string `query` returns the readable
+    error instead of searching, and a failed call's error reads
+    `Error in tool 'load_memory': …`, as every own tool's does.
+    `require_approval` can now gate `load_memory`. Neither the preload
+    tool nor the memory service's search logs the user's query any more;
+    the search logs only its length.
+  - `melchizedek-agents/tools/tool`: `ToolContext` gains `userContent` and
+    `searchMemory(query)`, which searches the run's own silo only.
+    `createToolContext` takes `memory` and `userContent`. A `Tool` may have
+    `instruction(ctx)`, text for the system instruction of each request.
+    New: `InstructionTool` (a tool that only writes into the instruction),
+    `isInstructionTool` and `instructionToolOf`.
+  - `melchizedek-agents/tools/adkTool` gains `toAdkInstructionTool`, and
+    `registerTool` takes an `InstructionTool`.
+  - `SupabaseVectorMemoryService` implements the engine's `MemoryService`
+    (`ingest`, `search`) as well as ADK's `BaseMemoryService`, whose
+    methods behave as before. `namespacedMemoryService` takes either and
+    pins `search` and `ingest` too.
+- **Claude runs on the engine's model contract (ADR 0055).** New module
+  `melchizedek-agents/models/claudeAdapter`: `ClaudeAdapter`, a
+  `ModelAdapter` that reads a `ModelRequest` and yields `ModelResponse`s on
+  the Messages API (`anthropicTools`, `ClaudeModelRequest`,
+  `THINKING_STATE_KIND`, `STRUCTURED_OUTPUT_TOOL`, `ANTHROPIC_PROVIDER`).
+  `ClaudeLlm` keeps its name, options, `supportedModels`,
+  `registerClaudeLlm()`, `buildAnthropicTools()` and `THINKING_STATE_KIND`,
+  and is now that adapter behind the ADK shim, a subclass of `AdkShim`.
+  Request bodies are unchanged. What does change on a Claude call:
+  - its events carry `finishReason`, and `groundingMetadata` when Claude
+    searched the web (see the web-sources entry above);
+  - a failed tool's `tool_result` carries `is_error: true`;
+  - a setup error (`MISSING_API_KEY`, `ENDPOINT_MISCONFIGURED`,
+    `SDK_NOT_INSTALLED`) carries `customMetadata['error.retryable']: false`;
+  - tool schemas come from `contractToolDeclaration`: `nullable` becomes a
+    type that admits null, string integer bounds become integers, and
+    `$schema` is left out.
+  `AdkShim` gains a protected `toModelRequest(llmRequest, options)` hook.
+  `melchizedek-agents/models/claudeModels` adds `ClaudeReasoning`,
+  `claudeReasoningOf`, `claudeReasoningFromConfig` and
+  `adaptiveThinkingFor`. 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
+  the engine's own `SessionService` (`create`, `get`, `list`, `delete`,
+  `append`) beside ADK's `BaseSessionService`, and
+  `ProjectedSessionService` accepts a store with either interface. The
+  import paths are unchanged. Through ADK's methods, to match that
+  interface:
+  - `listSessions` without a `userId` lists every user's sessions of the
+    app on the Supabase service too, as it already did on Postgres and as
+    ADK's contract says. Before, it filtered on a user named `undefined`.
+    Nothing in the engine calls it; check your own callers.
+  - `createSession` for an id that exists returns the conversation on the
+    Supabase service, as on Postgres, instead of resetting it to no events.
+    A create drops `temp:` keys from the initial state.
+  - `lastUpdateTime` and `last_update_time` are the appended event's
+    timestamp, as in ADK's own store, instead of the clock at append.
+  - On Postgres, appending an event whose id the session already holds
+    replaces that event's row instead of adding a second one.
+  - A listing with no `order` comes back in creation order, and one with
+    an `order` breaks ties by id, on both services. A `numRecentEvents`
+    below one is ignored.
+
+  No schema change. The bridge between the two interfaces
+  (`lib/runtime/adkSessionBridge.ts`) is internal and not in the exports
+  map.
+- **GPT and Grok run on the engine's model contract (ADR 0048, ADR 0056).**
+  New modules `melchizedek-agents/models/gptAdapter` (`GptAdapter`, the
+  Responses API as a `ModelAdapter`, with `responsesInput`,
+  `responsesFunctionTools`, `responsesUsage`, `responsesServerTools`,
+  `streamErrorDecision` and `isOpenAiReasoningModel`) and
+  `melchizedek-agents/models/grokAdapter` (`GrokAdapter`,
+  `GROK_REASONING_IDS`, `XAI_BASE_URL`). `GptLlm` and `GrokLlm` keep their
+  names, constructors, `supportedModels` and exports, and are now the ADK
+  shim around these adapters. The ledger, the turn's token charge and
+  `adk_turns.tool_calls` count GPT and Grok calls as before: output tokens
+  include reasoning, and server-side searches stay on the event's
+  `customMetadata`. `AdkShim` gains a protected `toLlmResponse(response)`
+  hook for that. What changes on the wire and in the events:
+  - `grok-4.6` takes `reasoning.effort` and replays its encrypted reasoning,
+    as `grok-4.5` and `grok-4.7` do.
+  - A failure a stream reports (`response.failed`, an `error` event, or an
+    SSE frame named `error`) carries a retry verdict when it names a
+    retryable status or the code `server_error`, `rate_limit_exceeded` or
+    `vector_store_timeout`, so the fallback model answers it.
+  - An aborted stream ends in an error final instead of the text so far.
+  - A user-turn image given by an https URL reaches GPT and Grok, and a PDF
+    goes as `input_file`; `top_p` is sent beside `temperature`; a call
+    without an id gets one minted from its position, shared with its result.
+  - JSON mode without a schema (`responseMimeType: 'application/json'`
+    alone) and the older spelling's `xhigh` and `max` effort words have no
+    contract field and are no longer sent to GPT or Grok.
+  - Final events carry `finishReason`, as every shimmed adapter's do.
+- **The engine's own event, session and memory interfaces (ADR 0052).**
+  Internal modules for the native runtime, not in the exports map, so
+  nothing a consumer imports changes: `lib/runtime/events.ts` (`TurnEvent`,
+  the stored ADK Event JSON typed, with a parse that keeps every field and
+  ADK's `isFinal`), `lib/runtime/sessions.ts` (`SessionService` and an
+  in-process store) and `lib/runtime/memoryService.ts` (`MemoryService`).
+  Stored sessions and the session services are unchanged.
+- **The skills say what `reasoning:` does on each Claude generation (ADR 0049).**
+  `melchizedek-models`, `melchizedek-author`, their briefs, `DOCUMENTATION.md`
+  and `syndicateSchema.yaml` say that later Claude models take `reasoning:` as
+  adaptive thinking at an effort, with `none` as the model's off switch, or
+  `low` effort on Opus 5 and 5.5, Fable and Mythos. The 1,024 floor holds on
+  Claude 4.6 and earlier only, and the non-streaming limit on a
+  `budget_tokens` above about 19,000 holds on every Claude model.
+- **Tools are the engine's own (ADR 0051).** New module
+  `melchizedek-agents/tools/tool`:
+  - `Tool`: `name`, `declaration()` (the model contract's
+    `ToolDeclaration`) and `execute(args, ctx)`.
+  - `ToolContext`: ids, a `state` view whose writes land in
+    `stateDelta`, `actions.skipSummarization`, `requestConfirmation` and
+    `confirmation`, and the abort `signal`. `createToolContext()` and
+    `toToolContext()` build one.
+  - `requireApproval(tool)`, the `longRunning` marker with
+    `LONG_RUNNING_NOTE` and `isLongRunning`, `capResult` and
+    `MAX_RESULT_CHARS` (20,000, the limit OpenAPI and MCP results already
+    use), and `toolOf(value)`, which finds the Tool behind a registry entry.
+
+  `defineTool` returns a Tool that is still a `ToolContract`. Its
+  `execute` validates the arguments before the handler runs, and the
+  handler gets a complete `ToolContext`; `executeContract` validates such
+  a Tool once. `defineTool` takes `longRunning` and `maxResultChars`.
+  `toolContract` also exports `asTool`, `DefinedTool` and `ToolSpec`.
+  `toFunctionTool` takes a Tool or a contract, and `registerTool` takes a
+  contract, any Tool or an ADK tool.
+- **Every registry tool that declares a function is a Tool**, wrapped for
+  the ADK runtime by `toFunctionTool`, except ADK's `load_memory`. The ADK
+  runtime runs the same `FunctionTool`s, with the same approval
+  interrupts and texts. `generate_image`, `inspect_image` and `ask_user`
+  become contracts (`generateImageContract`, `inspectImageContract`):
+  - `generate_image` and `inspect_image` now return the readable error for
+    arguments their schema refuses, instead of calling Gemini;
+  - an `ask_user` call with invalid arguments returns the error to the
+    model instead of pausing the turn on it.
+- **Tool schemas: defaults are optional, and records keep their values.**
+  On every surface (the declaration, the ADK `FunctionTool` and the MCP
+  `tools/list` entry), a zod schema is exported for its input side
+  (`io: 'input'`), so a field with a default is no longer listed as
+  required. A record's value schema (`additionalProperties`) is kept on
+  both paths, and its `propertyNames: { type: 'string' }`, which says
+  nothing in JSON, is left out: a live Gemini call refuses that keyword
+  with a 400 and accepts the value schema. `toGeminiSchema` walks by schema keyword, so a property named
+  `additionalProperties` or `default` keeps its schema. `models/schemaNormalize`
+  exports `zodInputJsonSchema`, `zodToolParameters` and `mapSchemaNodes`,
+  and `contractToolDeclaration` reads an own Tool's `declaration()`.
+- **Claude requests follow the model generation (ADR 0049).** `ClaudeLlm`
+  reads a per-generation table from the model id. Before, every `claude-*`
+  id got a thinking budget and a forced tool, which the current models refuse
+  with a 400. Now:
+  - Claude 4.6 and earlier keep the thinking budget.
+  - Later models get adaptive thinking with `output_config.effort` from
+    `reasoning:` (or `reasoningEffort`), and a summarized thinking display.
+    `none` becomes each model's own off switch at `low` effort, or `low`
+    effort where the model has none.
+  - Structured output is `output_config.format` from Opus 4.8, Sonnet 5 and
+    Haiku 5.5 on. Forced tool use is a 400 on Fable 5.1, Opus 5.5 and
+    Sonnet 5.5.
+  - Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 bind thinking to the
+    conversation. Their requests set `drop_block` under the
+    `thinking-binding-controls-2026-08-01` beta, so a turn resumed from
+    storage no longer fails on a history that changed in storage.
+  - An image URL that names no type is typed by its extension. Claude on
+    Bedrock and Vertex AI drops URL images, since those platforms take base64
+    only, and the capability matrix says so.
+  - `melchizedek-agents/models/claudeModels` exports `claudeGeneration`,
+    `adaptiveThinking`, `requestedEffort`, `claudeUrlImagesOn` and
+    `THINKING_BINDING_BETA`.
+- **`reasoning:` sets how hard an agent reasons, on any provider (ADR 0047).**
+  Write `none`, `low`, `medium` or `high`, or `{ budget_tokens: <int> }`, on
+  the orchestrator or a subagent. The compiler sends each provider the field
+  it reads:
+  - Gemini 3: a thinking level.
+  - Claude and Gemini 2.x: a thinking budget of 0, 2,048, 8,192 or 16,384
+    tokens.
+  - GPT, Grok, Kimi, Ollama and the gateway: an effort word.
+  `generateContentConfig.thinkingConfig` and `reasoningEffort` remain
+  valid as the older spelling. Setting either beside `reasoning` on the same
+  agent is a load error. Agents that set neither are unchanged.
+- **GPT and Grok honour an effort.** `GptLlm` sends `reasoning.effort` when
+  the agent sets one (`reasoning:`, or `generateContentConfig.reasoningEffort`),
+  and `GrokLlm` sends it in place of its pinned `medium`. Before, both ignored
+  it. `reasoningParam` takes the request as an optional argument.
+- **The model zoo and every template use `reasoning:`.** What each agent
+  asks of its provider is unchanged: the templates' `includeThoughts: false`
+  was already the default, and the zoo's Claude agent keeps its 2,048-token
+  budget as `low`.
+- **The shipped skills teach `reasoning:`.** `melchizedek-author` and
+  `melchizedek-models` (and their briefs) set reasoning with `reasoning:`, show
+  what each level becomes per provider and per Claude model generation, and
+  describe `generateContentConfig.thinkingConfig` and `reasoningEffort` as the
+  older spelling that still loads. The author skill's `assets/minimal.yaml` sets it.
+- `lib/compile.ts` exports `reasoningConfig`, `withReasoning` and
+  `REASONING_BUDGETS`. The `AgentYamlConfig` type gains `reasoning`, and
+  `GenerateContentConfig` gains `reasoningEffort`.
+- **Thinking with tool use works on Claude (ADR 0046).** The adapter writes
+  the signed `thinking` / `redacted_thinking` blocks into a `providerState`
+  field on the part they preceded and replays them verbatim within the
+  turn's tool loop, so a thinking Claude agent can use tools and delegate.
+  A step continuing another provider's or Claude model's tool call runs
+  without thinking.
+  New module `melchizedek-agents/models/providerState` (`ProviderState`,
+  `providerStateOf`, `withProviderState`): the convention every adapter
+  uses for provider-opaque reasoning state. The final event no longer
+  carries `customMetadata['anthropic.thinking']`; the same blocks are on
+  the part.
+- **Claude agents see images.** `ClaudeLlm` sends a user-turn `inlineData`
+  part as a base64 image block (`image/png` when it names no type) and an
+  `https` `fileData` part as a URL image block, in the parts' order. Before,
+  it dropped both. JPEG, PNG, GIF and WebP are sent; any other type, or a
+  non-https URL, is dropped with `llm.image.dropped` on the span and a
+  one-time warning naming the type. Images inside tool results are not sent,
+  as on GPT. The capability matrix marks Anthropic image input supported.
+- **The engine's own model contract (ADR 0048).** New module
+  `melchizedek-agents/models/contract`, types only: `Message`, `Part`,
+  `ToolDeclaration`, `NativeTool`, `ModelRequest`, `ModelResponse`,
+  `ModelAdapter`, `ProviderCapabilities` and their parts. The native
+  runtime and every model adapter will speak it, and no adapter uses it
+  yet. `ReasoningLevel` and `ReasoningSetting` are defined there now.
+  `melchizedek-agents/loadSyndicate` re-exports them unchanged.
+- **Tool declarations in the contract's shape.** `models/schemaNormalize`
+  exports `contractToolDeclaration(tool, { strict? })`, which builds a
+  contract `ToolDeclaration` from an ADK tool or straight from a
+  `defineTool` contract's zod schema; `nativeToolOf(tool)`, which names the
+  `NativeTool` a server-side tool or Gemini's code executor stands for; and
+  `toContractJsonSchema(schema, { strict? })`. Gemini's dialect (uppercase
+  types, int64 bounds as strings, `nullable`) is converted once, at any
+  depth, and the strict form reaches every nested object. Nothing calls
+  them yet; `toolDeclarationFor`, `toLowercaseJsonSchema` and
+  `toStrictJsonSchema` are unchanged.
+- **genai `Content` maps to and from the model contract (ADR 0048).** New
+  module `melchizedek-agents/models/genaiMapping`: `contentsToMessages` and
+  `messagesToContents`, `contentToMessage` and `messageToContent`,
+  `partToGenai`, `llmRequestToModelRequest`, `modelResponseToLlmResponse`,
+  `reasoningOf`, `systemText`, `usageToMetadata`, `usageFromMetadata` and
+  `isMintedCallId`, the constants `GEMINI_PROVIDER`,
+  `THOUGHT_SIGNATURE_KIND`, `GENAI_PART_KIND` and `MINTED_CALL_ID_PREFIX`,
+  and the types `ContractHistory`, `GenaiHistory` and
+  `ModelRequestOptions`. A stored event's
+  content round-trips to the same JSON: a Gemini `thoughtSignature` becomes
+  `providerState` of kind `thought_signature`, a call without an id gets a
+  `genai-noid-` id that is left off again on the way back, and a part the
+  contract cannot hold (Gemini code execution, ADK's confirmation request)
+  rides whole as `providerState` of kind `genai_part`. A failed final keeps
+  its retry verdict as `customMetadata['error.retryable']` and
+  `['error.status']`, which is what `FallbackLlm` reads. Nothing calls it yet;
+  no adapter or stored shape changes.
+- **Thinking with tool use works on GPT and Grok (ADR 0050).** On
+  reasoning ids (o-series, `gpt-5*`, `grok-4.5`, `grok-4.7`), the Responses
+  adapters write each run of encrypted reasoning items on the part after it
+  and replay them before that part within the turn's tool loop, for the same
+  provider and model only. These requests now send `store: false` and
+  `include: ['reasoning.encrypted_content']`, so OpenAI and xAI no longer
+  keep the response server-side, as they did by default. The guarded 400
+  retry also drops the `include` and the replayed items.
+  `buildResponsesInput` takes an optional `replay` argument;
+  `models/gptLlm` exports `REASONING_STATE_KIND`, and `models/providerState`
+  exports `currentTurnStart`.
+- **Kimi keeps its reasoning across tool steps (ADR 0046).** On `kimi-k3`,
+  `kimi-k2.6` and `kimi-k2.7-code`, the adapter stores each response's
+  `reasoning_content` on the part that follows it and sends it back on that
+  assistant message within the turn's tool loop, for the same model only,
+  as Moonshot asks. A tool loop's later steps bill the replayed reasoning
+  as input. `OpenAiCompatibleLlm` gains the opt-in hook
+  `replaysReasoningContent()` (off by default; Ollama and the gateway keep
+  it off) and exports `REASONING_CONTENT_KIND`; `models/kimiLlm` exports
+  `wantsReasoningReplay`. `currentTurnStart` returns -1 when no user
+  content opens the turn, so every content is then the current turn's.
+- **The fallback model on the engine's own contract (ADR 0044, ADR 0048).**
+  New module `melchizedek-agents/models/fallbackAdapter`: `FallbackAdapter`,
+  a `ModelAdapter` around a primary and a fallback adapter, with
+  `FallbackAdapterOptions` and `isProviderError`. It applies ADR 0044's
+  rules to a failed final's `error.retryable` and `status`, and hands the
+  fallback the request with its own model id and the caller's `reasoning`
+  unchanged. Nothing uses it yet. The breaker's state moves to the new
+  module `melchizedek-agents/models/circuitBreaker` (`circuitOpen`,
+  `recordFailure`, `recordSuccess`, `resetCircuits`, `breakerSettings`, and
+  `setBreakerClock` for tests), shared by both wrappers, so a provider
+  tripped on one path is skipped on the other. `models/fallback` still
+  exports `circuitOpen` and `resetCircuits`, and `FallbackLlm` behaves as
+  before.
+- **Any adapter on the model contract runs under ADK (ADR 0053).** New module
+  `melchizedek-agents/models/adkShim`: `AdkShim`, an ADK `BaseLlm` that
+  wraps one `ModelAdapter` and maps ADK's request and responses through
+  `models/genaiMapping`; `adkShim(adapter, model?)`; `adkShimClass(supportedModels,
+  createAdapter)`, a class ADK's `LLMRegistry` can register; and the types
+  `AdkShimOptions` and `ModelAdapterFactory`. The shim charges each call
+  against the turn's `max_steps`, refuses a call on a spent or stopped turn
+  with the same response the ADK-path adapters give, hands the adapter the
+  turn's abort signal, and opens the `llm.request` span, so an adapter on
+  the contract does none of these itself. `connect()` is refused. Nothing
+  registers it yet; no adapter or stored shape changes.
+- **An elided tool result's size is stored the same on every server.**
+  `trimEventForStorage` writes it with en-US digit grouping (`2,563 chars
+  dropped before storage — …`), where it followed the server's locale
+  (`2.563` in German). An en-US server stores the same bytes as before, and
+  rows already stored are untouched.
+- The capability matrix's Ollama and gateway `thinking_with_tools` note names
+  `reasoning:` as the lever (ADR 0047), compiled to `reasoningEffort`.
+- **The shipped skills cover Kimi.** `melchizedek-models` adds `kimi-*` to
+  Moonshot AI in its routing table, `MOONSHOT_API_KEY` to its key list and
+  `kimi-k3` to its verified ids; `melchizedek` adds the key and `kimi-*` to
+  its `Model not found` line. Their briefs match.
+- **`wiki_relate` appends.** A new assertion goes at the end of
+  `.graph/relations.json` and every stored record keeps its place and bytes,
+  where each write used to re-sort the whole file. A store that does not
+  parse is refused rather than overwritten. `melchizedek-agents/wiki/entities`
+  exports `appendRelation(wikiRoot, record)`, which returns `false` for a
+  duplicate, and `saveRelations` writes records in the order given instead of
+  sorting them.
+- **Fix: `fallback_model:` answers for Claude, GPT, Grok, Kimi, Ollama and
+  gateway primaries (ADR 0044).** In 0.18.0 `FallbackLlm` saw a failure only when
+  the primary threw, which only Gemini does. The other adapters yield an
+  error response, so their fallback never answered, and the failed call was
+  recorded as a success, which reset the provider's circuit breaker. Their
+  error responses now carry `customMetadata['error.retryable']` (and
+  `'error.status'` when the failure had an HTTP status), set from
+  `lib/models/retry.ts`'s classification, and `FallbackLlm` reads them: a
+  retryable error before any output is counted on the breaker and answered
+  by the fallback, a non-retryable one is passed on, and only a call that
+  produced content counts as a success. Error codes and messages are
+  unchanged, except that key-shaped text is now removed from the message.
+  A failure GPT or Grok report inside an open stream carries a verdict too,
+  from the event (see GPT and Grok on the model contract). The retry policy now counts
+  HTTP 529, Anthropic's "overloaded", as retryable, so an overloaded Claude
+  primary is answered by its fallback. New
+  module `melchizedek-agents/models/errorResponse`: `providerErrorResponse`,
+  `withRetryVerdict`, `isRetryableErrorResponse`, `errorDecision`,
+  `statusDecision`, `errorText`, `ERROR_RETRYABLE_KEY`, `ERROR_STATUS_KEY`.
+- **A Gemini adapter on the model contract, not yet wired.** New module
+  `melchizedek-agents/models/geminiAdapter`: `GeminiAdapter` implements
+  `ModelAdapter` (ADR 0048) on `@google/genai` directly, with no ADK, on the
+  Gemini API or Vertex AI (`lib/models/endpoints.ts`). Schemas go as
+  lowercase JSON Schema (`parametersJsonSchema`, `responseJsonSchema`).
+  `reasoning:` maps through `reasoningConfig`. Thought signatures ride on
+  the part as `providerState` and are replayed within the turn. Every
+  failure is a final response. A `clientFactory` option takes an injected
+  client. Nothing registers the adapter yet: Gemini ids are still served by
+  `TracedGemini`, unchanged. `REASONING_BUDGETS` and `reasoningConfig` move
+  to the new module `melchizedek-agents/models/reasoning`, so the adapter
+  maps `reasoning:` without importing the compiler or ADK;
+  `melchizedek-agents/compile` still exports both.
+- **A temporary Gemini adapter on the contract, over ADK's Gemini.** New
+  module `melchizedek-agents/models/adkGeminiAdapter`: `AdkGeminiAdapter`
+  (and `AdkGeminiAdapterOptions`) implements `ModelAdapter` by mapping the
+  request to an `LlmRequest` and running it through `TracedGemini` with its
+  retries. Every failure is a final response: a failed call is
+  `GEMINI_ERROR` with its status and retry verdict. Like every contract
+  adapter (ADR 0053) it opens no `llm.request` span and charges nothing;
+  behind `AdkShim` the span has `TracedGemini`'s attributes, with the
+  failed call's code as `GEMINI_ERROR` where `TracedGemini` records the
+  HTTP status. It serves Gemini on the native runtime until `GeminiAdapter`
+  passes its live parity run, and is removed after that. Nothing registers
+  it yet.
+  - `models/genaiMapping` adds the reverse directions:
+    `modelRequestToLlmRequest`, `llmResponseToModelResponse` (with the type
+    `ModelResponseOptions`) and `nativeToolsWithoutGeminiTool`.
+  - `TracedGemini` gains `generateWithRetries(llmRequest, stream?,
+    abortSignal?)`, the call that `generateContentAsync` wraps in its span.
+    Its spans are unchanged.
+  - `traceLlmGeneration`'s `LlmCallMeta` gains `request`: a `ModelRequest`,
+    or a function that returns one. `llmRequest` is deprecated and still
+    recorded when `request` is absent. Every adapter in the package and
+    `AdkShim` now pass `request`, so a failed call's `llm.payload.request`, and the
+    `adk_payloads.request` row made from it, hold the request in the model
+    contract's shape (`model`, `system`, `messages`, `tools`, …) instead of
+    ADK's (`contents`, `config`, `toolsDict`). The span's other attributes
+    are unchanged.
+  - `GEMINI_PROVIDER` and `THOUGHT_SIGNATURE_KIND` are defined once, in the
+    new module `melchizedek-agents/models/geminiState`. `models/genaiMapping`
+    and `models/geminiAdapter` still export both, with the same values.
+
 ## 0.18.0 — 2026-10-06
 
 ### Breaking — read before upgrading