melchizedek-agents 0.19.0 → 1.0.0

package/.env.example

@@ -19,11 +19,10 @@ GOOGLE_GENAI_API_KEY=
 # keep their task list and job queue. Default: outputs/tasks.json.
 # MELCHIZEDEK_TASKS_FILE=outputs/tasks.json
 
-# ── Optional: runtime (ADR 0045) ──────────────────────────────────────────────
-# Which runtime runs a turn's agents: adk (default) or native (the engine's own loop).
-# MELCHIZEDEK_RUNTIME=adk
-# Which adapter serves a Gemini model id on the native path: adk (default) or engine.
-# GEMINI_ADAPTER=adk
+# ── Runtime (ADR 0107) ────────────────────────────────────────────────────────
+# Every turn runs on the engine's own loop. MELCHIZEDEK_RUNTIME and
+# GEMINI_ADAPTER need no value: native and engine are the only ones, and adk
+# (removed in 1.0.0) stops the server at startup.
 
 # ── Optional: MCP (Model Context Protocol) ────────────────────────────────────
 # ALLOW_PRIVATE_MCP: set to "true" to permit mcp_server_url values pointing at

package/AGENT_SETUP.md

@@ -119,9 +119,9 @@ One-shot mode (answers and exits — this is also how you'll script it):
 npm run syndicate:critic -- "In two sentences, why did the Library of Alexandria decline?"
 ```
 
-And the floor of the whole framework — one agent, no syndicate, plain
-ADK. `scripts/direct_call.ts` is the ~30-line block you'll copy when an
-agent belongs inside your own code rather than behind a YAML:
+And the floor of the whole framework — one model call, no syndicate, no
+agent framework. `scripts/direct_call.ts` is the short block you'll copy when a
+model call belongs inside your own code rather than behind a YAML:
 
 ```bash
 npm run demo:direct -- "In one sentence: what is an agent?"

package/CHANGELOG.md

@@ -6,6 +6,498 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 1.0.0 — 2026-10-08
+
+Release 1.0.0: Google ADK is gone (ADR 0107). Every turn runs on the
+engine's own agent loop and workflow scheduler, which have been the default
+since 0.20.0; the ADK runtime, the ADK peer dependency and everything that
+existed only for them are removed. What a conversation stores does not
+change: sessions written by ADK, or by 0.x on either runtime, resume.
+
+### Breaking — read before upgrading
+
+- **Breaking: the ADK runtime is removed.** `native` is the only runtime.
+  `MELCHIZEDEK_RUNTIME=adk` is a startup error: `createA2AApp` (the A2A
+  server), `melchizedek-chat` and `melchizedek-worker` throw the new
+  `RuntimeRemovedError`, which names 1.0.0 and the fix, and
+  `runSyndicateTurn` throws it for `runtime: 'adk'` before the session is
+  touched. `melchizedek-doctor` reports it as a problem (`--check` fails).
+  `MELCHIZEDEK_RUNTIME=native` is still accepted and changes nothing.
+  `RuntimeName` is `'native'`; `RUNTIMES` is `['native']`.
+- **Breaking: `@google/adk` is no longer used.** It is gone from
+  `peerDependencies`, `peerDependenciesMeta` and `devDependencies`, and
+  nothing in the package loads it: uninstall it. The package has no
+  top-level `await` any more, so it loads from CommonJS through `require()`
+  again (Node's `require(esm)`: on by default from Node 22.12, behind
+  `--experimental-require-module` on 22.6–22.11). `@google/genai` stays a
+  dependency, used only by the Gemini adapter, the image tools and memory
+  embeddings.
+- **Breaking: `runSyndicateTurn` takes the engine's session and memory
+  interfaces.** `sessionService` is a `SessionService`
+  (`lib/runtime/sessions.ts`: `create`, `get`, `list`, `delete`, `append`)
+  and `memoryService` a `MemoryService` (`lib/runtime/memoryService.ts`:
+  `ingest`, `search`), no longer ADK's `BaseSessionService` and
+  `BaseMemoryService`. The parameter names, the option keys and the result
+  are unchanged. `ingestTurnMemory` takes the same two interfaces and calls
+  `memoryService.ingest`. `TurnEvents.onEvent` receives a `TurnEvent` (the
+  JSON ADK's `Event` carried). `transformAgent` transformed ADK agents: any
+  value is refused with `UnsupportedOnRuntimeError` before the session is
+  touched.
+- **Breaking: the stores and the memory service lose their ADK methods.**
+  `InProcessSessionService`, `PostgresSessionService`,
+  `SupabaseSessionService` and `ProjectedSessionService` are the engine's
+  `SessionService` only: `createSession`, `getSession`, `listSessions`,
+  `deleteSession` and `appendEvent` are gone (use `create`, `get`, `list`,
+  `delete`, `append(session, event)`). `ProjectedSessionService` takes an
+  engine store. `SupabaseVectorMemoryService` drops `addSessionToMemory`
+  and `searchMemory` (use `ingest(session, { extractionRules,
+  extractionModel })` and `search`); `namespacedMemoryService` pins `search`
+  and `ingest`. The A2A app's `storage.sessionService` and
+  `storage.memoryService` take the engine's interfaces. The stored rows are
+  unchanged.
+- **Breaking: `GEMINI_ADAPTER=adk` is an error.** Every Gemini id runs on
+  the engine's `GeminiAdapter`. `GEMINI_ADAPTER=engine` (or
+  `{ gemini: 'engine' }`) is accepted and changes nothing; `adk` throws an
+  error naming 1.0.0. `GeminiAdapterChoice` is `'engine'`.
+- **Breaking: removed exports.** From `melchizedek-agents`:
+  `AdkNotInstalledError`, `adkInstalled`, `asAdkSessionService`,
+  `asSessionService`, `compileGraph`, `compileSubagent`, `compileWorkflow`,
+  `CompiledWorkflow`, `toFunctionTool`, `registerAvailableProviders`,
+  `GatewayLlm`. From `melchizedek-agents/runtime`: the same runtime names,
+  and `retryPlugins` (self-correction is the loop's own, from `retries:`).
+  From `melchizedek-agents/compile`: `compileGraph`, `compileSubagent`,
+  `requireApprovalOn`, `requireApprovalOnBaseTool` (gate an own Tool with
+  `requireApproval`), and `CompileOptions.nodeConfig`. From
+  `melchizedek-agents/models/registry`: `registerAvailableProviders`,
+  `GatewayLlm`, `TracedGemini`. These subpaths resolved to deleted files and
+  are gone: `melchizedek-agents/models/adkShim`, `models/adkGeminiAdapter`,
+  `models/tracedGemini`, `models/claudeLlm`, `models/gptLlm`,
+  `models/grokLlm`, `models/kimiLlm`, `models/ollamaLlm`, `models/gatewayLlm`,
+  `models/openAiCompatibleLlm`, `models/fallback`, `tools/adkTool`,
+  `tools/webSearchTool`, `tools/urlContextTool`, `tools/xSearchTool`,
+  `tools/collectionsSearchTool` (the server-side tools are the markers in
+  `melchizedek-agents/tools/nativeTools`). `lib/workflow.ts` keeps the
+  `workflow:` block's contract; `compileWorkflow`, `assembleWorkflow`,
+  `toRetryConfig` and `nodeSettings` are gone. The exports map's paths are
+  unchanged.
+- **Breaking: tools are the engine's own, and ADK tools are refused.** The
+  registry holds the engine's `Tool`, `InstructionTool`, `NativeToolMarker`
+  and `Toolset` (`lib/tools/tool.ts`), with no ADK `FunctionTool` around
+  them. `webExtractTool`, `generateImageTool`, `inspectImageTool`,
+  `xApiSearchTool`, `remoteAgentTool()`, `createMcpTools()` and
+  `buildOpenApiTools()` return own `Tool`s (`declaration()`,
+  `execute(args, ctx)`). `registerTool` refuses an ADK tool (anything with
+  `runAsync`) with an error that names 1.0.0 and `defineTool`, and refuses
+  an object that is not a tool. `toFunctionTool`'s replacement: define the
+  tool with `defineTool` (a zod schema and `execute(args, ctx)`) and
+  register it; a `defineTool` contract is the engine's `Tool`.
+  `runWikiAgent` (`melchizedek-agents/wiki/agentRun`) takes `tools: Tool[]`.
+- **Breaking: a model resolver returns an id or a `ModelAdapter`.**
+  `CompileOptions.resolveModel` returns `string | ModelAdapter | undefined`
+  (`melchizedek-agents/model`), and the registry's `resolveModel` returns
+  the engine's `ModelAdapter`, with the same BYOK scoping. A resolver that
+  returns an ADK model class is refused with `UnsupportedOnRuntimeError`
+  before any model call. `registerAvailableProviders` is replaced by
+  `logProviderStatuses(log?)`, which returns and logs the provider statuses
+  and registers nothing: a model id resolves when an agent first calls it.
+  `modelExtractor`'s `resolve` seam returns a `ModelAdapter`.
+- **Breaking: a resolver's plain `{ model, apiKey }` object is refused.**
+  Anything `resolveModel` returns that is neither a model id string, a
+  `ModelAdapter` (an object with `generate()` and a string `model`) nor
+  `undefined` is refused with `UnsupportedOnRuntimeError` when the agent is
+  compiled, before any model call; the message names 1.0.0 and the type of
+  what came back, never its contents. Before, the engine passed such an
+  object over and resolved the agent's YAML id on the environment's key, so a
+  BYOK caller ran on the operator's key. A BYOK resolver returns an adapter,
+  for example `new ClaudeAdapter({ model, apiKey })` from
+  `melchizedek-agents/model`.
+- **Breaking: an ADK tool is refused everywhere.** An object with
+  `runAsync` is refused with an error naming 1.0.0 and `defineTool` wherever
+  it arrives: `registerTool`, a compiled agent's tool list, a workflow tool
+  node, a Toolset's `getTools()` and `extraTools` on a model request. Before,
+  the last two skipped it silently.
+- **Breaking: `createA2AApp` stops on `GEMINI_ADAPTER=adk`** at startup with
+  the 1.0.0 error, as it does on `MELCHIZEDEK_RUNTIME=adk`, instead of
+  failing at the first Gemini call.
+- **Breaking: dead model and tool exports removed.**
+  `melchizedek-agents/models/errorResponse` drops `providerErrorResponse` and
+  `isRetryableErrorResponse` (use `withRetryVerdict(response,
+  errorDecision(err))` and read `customMetadata['error.retryable']`);
+  `models/schemaNormalize` drops `toolDeclarationFor` (use
+  `contractToolDeclaration`); `models/claudeAdapter` drops
+  `ClaudeModelRequest` and its `claudeReasoning`; `models/chatCompletionsAdapter`
+  drops `ChatCompletionsRequest` and `OlderSpelling` (adapters take
+  `ModelRequest`). `melchizedek-agents/tools/toolContract` drops
+  `toolCallContextFrom`, and `melchizedek-agents/tools/tool` drops
+  `OWN_TOOL`; `toolOf`, `instructionToolOf` and `toolsetOf` no longer look
+  inside a wrapper. `nativeToolOf` recognises only the engine's own marker.
+  Kimi K3 no longer sends `reasoning_effort: max`, which had no contract
+  level and was reachable only through the removed older spelling.
+- **Breaking: the doctor's runtime report has no `adk` field.**
+  `runtimeReport()` returns the runtime and its source, or the problem.
+
+### Migration
+
+1. `npm uninstall @google/adk`, and unset `MELCHIZEDEK_RUNTIME=adk` and
+   `GEMINI_ADAPTER=adk` wherever they are set.
+2. Replace `new InMemorySessionService()` and
+   `asAdkSessionService(new InProcessSessionService())` with
+   `new InProcessSessionService()` (or your Postgres or Supabase store), and
+   call `create` / `get` / `append(session, event)` where you called
+   `createSession` / `getSession` / `appendEvent`.
+3. Replace a custom `BaseMemoryService` with a `MemoryService`
+   (`ingest`, `search`).
+4. Replace ADK `FunctionTool`s and `toFunctionTool(...)` with `defineTool`
+   contracts, and register them with `registerTool`.
+5. Replace `registerAvailableProviders()` with `logProviderStatuses()`.
+6. A custom `resolveModel` returns a model id or a `ModelAdapter`
+   (`resolveAdapter` from `melchizedek-agents/model`), not an ADK `BaseLlm`.
+   A resolver that returned a plain `{ model, apiKey }` object returns an
+   adapter built with that key instead (`new ClaudeAdapter({ model, apiKey })`
+   or the provider's own adapter class); the plain object is refused.
+7. Run turns through `runSyndicateTurn` where you compiled ADK agents with
+   `compileGraph`, `compileSubagent` or `compileWorkflow`.
+
+### Fixed
+
+- **Server-side tool calls are recorded again.** A GPT or Grok answer that
+  searched (web search, X search, collections) records its server-side tool
+  calls as `ToolCall` events and counts them in the ledger row's
+  `tool_calls`. Since 0.20.0 made the engine's loop the default, those
+  calls were lost: the record lived in the deleted ADK shim. The native step
+  carries them onto the final (`lib/runtime/native/step.ts`);
+  `tests/nativeLedgerCounts.test.ts` pins it.
+
+### Unchanged by design
+
+- The stored Event JSON (`adk_sessions.events`, `adk_session_events`), the
+  interrupt names (`adk_request_confirmation`, `ask_user`,
+  `adk_request_input`, `adk_request_credential`) and their argument shapes,
+  the A2A surface, and the table names. The ADK-written session fixtures
+  (`tests/fixtures/sessions`) resume.
+
+### Added and changed
+
+- **One output-token meaning on the ledger (ADR 0107).** For every
+  provider, `output_tokens` (and `llm.tokens.output`) excludes the thinking
+  and `thinking_tokens` carries it, so output plus thinking is the
+  provider's own output count. This is what the engine's loop has written
+  since 0.20.0; it supersedes the ledger clauses of ADR 0056 and ADR 0057,
+  which kept the provider's meaning on the ADK path. Rows written before
+  0.20.0 for GPT, Grok, Kimi and the gateways used that older meaning: a
+  query comparing output across that boundary subtracts `thinking_tokens`
+  from those rows.
+
+- **New exports.** From the barrel and `melchizedek-agents/runtime`:
+  `RuntimeRemovedError`, and the types `SessionService`, `Session`,
+  `SessionKey`, `MemoryService`, `MemoryEntry`, `MemoryIngestOptions`,
+  `MemorySearchRequest`, `MemorySearchResult` and `TurnEvent`. From the
+  barrel: `UnsupportedOnRuntimeError`, `logProviderStatuses`, and the types
+  `Tool` and `ToolContext`.
+- **An import-graph test holds the line** (`tests/importGraph.test.ts`):
+  nothing under `lib/` or `scripts/` names Google ADK, and `@google/genai`
+  is imported only by the Gemini adapter and its genai mapping, the image
+  tools and memory embeddings.
+
+- **A workflow syndicate runs its whole graph as a dispatch route or a
+  workflow node (ADR 0106).** A `yaml_reference` to a workflow syndicate
+  used to run its orchestrator alone there; it now runs the whole graph on
+  the child session filed under the entry's name, as a delegated subagent
+  already did (ADR 0098). As a plan-dispatch route its last output is the
+  turn's answer, and the conversation keeps the message and that answer. As
+  a workflow node its last output is the node's output. A `map` over
+  one and an `ask_user` node inside one are refused by name. Each nested
+  walk has its own node-run ceiling (ADR 0105). **Breaking for a direct
+  caller:** `compileSubagentSpec` refuses a workflow reference by name
+  instead of compiling its orchestrator; compile the entry
+  with `compileEntrySpec`. `melchizedek-agents/compile` adds
+  `compileEntrySpec`, `EntrySpec`, `workflowAgentSpecs`,
+  `workflowEntryNames` and `WorkflowSpec.workflows`; the exports map and the
+  barrel are unchanged.
+
+- **Skill scripts on a workflow node (ADR 0106).** `skills.scripts: local`
+  is allowed on a workflow node's agent: each `run_skill_script` call pauses
+  the node and the walk for a person's approval, as `require_approval` does,
+  and runs once after it, with the minimal script environment of ADR 0086.
+  Still refused on an agent a `map` node runs.
+
+- **Docs: `config/agents/syndicateSchema.yaml` describes the engine as it
+  runs.** Its comments say that the runtime runs every key, explain the ADK
+  spellings and "Maps to:" lines as spellings, prefer
+  `reasoning:` over `generateContentConfig.thinkingConfig`, and no longer
+  call Gemini "ADK-native", plan-dispatch "A2A-only", or `require_approval`
+  unsupported inside a workflow. Comments only.
+
+- **A workflow walk has a node-run ceiling (ADR 0105).** `max_steps`
+  counts model calls, so a routed cycle through nodes that make none (a tool
+  node and its route step looping on each other) ran until the turn's
+  deadline. A walk now starts at most
+  `max(20 × max_steps, 100)` node runs (1,000 at the default of 50); the run
+  that would pass it fails its node with `NodeRunLimitError`, stored as the
+  workflow's node-error event, and the turn fails with the new error code
+  `NODE_RUN_LIMIT` and the progress line `Stopped: the workflow reached its
+  limit of <n> node runs`. A legitimate loop under the ceiling is unchanged;
+  raise `max_steps` to raise it.
+
+- **Docs: the shipped documentation describes the engine as 1.0.0 runs it
+  (WS5-3, WS5-2b).** `README.md`, `QUICKSTART.md`, `DOCUMENTATION.md`,
+  `AGENT_SETUP.md` and the agent skills under `skills/` describe the
+  engine's own loop, model contract, tools, sessions and workflow
+  scheduler, with no ADK to install, and no longer call Gemini
+  "ADK-native".
+
+## 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 +544,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 +556,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 +687,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 +820,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 +861,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 +912,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