melchizedek-agents 1.0.3 → 1.2.0

package/.env.example

@@ -1,3 +1,7 @@
+# Not sure which of these you need? `npx melchizedek-setup` (in a clone: `npm run setup`)
+# asks what you have and prints the names to set for it; --auto detects it.
+# Only names and shapes live here: type the values yourself, never commit .env.
+
 # ── Required for cloud models ─────────────────────────────────────────────────
 # Google AI Studio API key — powers all Gemini model inference.
 # Also required for the gemini-embedding-001 embedding model used by long-term memory.
@@ -33,8 +37,11 @@ ALLOW_PRIVATE_MCP=false
 # ── Optional: OpenAPI tools (an agent's `openapi:` list) ──────────────────────
 # ALLOW_PRIVATE_OPENAPI: set to "true" to let an OpenAPI tool call a localhost /
 # private / link-local server. Off by default as an SSRF guard. Credentials an
-# `openapi:` entry names (auth.bearer_env, auth.api_key.env) are read from this
-# file or the environment, never written in YAML.
+# `openapi:` entry names (auth.bearer_env, auth.api_key.env, and an OAuth
+# grant's auth.oauth2.client_id_env / client_secret_env, which an MCP server's
+# mcp_auth.oauth2 uses too) are read from this file or the environment, never
+# written in YAML. Give each API its own variable: the framework's own
+# settings below are refused (ADR 0112).
 # ALLOW_PRIVATE_OPENAPI=false
 
 # ── Optional: Anthropic / Claude ──────────────────────────────────────────────
@@ -245,6 +252,26 @@ PUBLIC_URL=
 # out of the database and its backups. Unset = no credential store. A row
 # sealed with another key stays unreadable (the user reconnects).
 # MELCHIZEDEK_CREDENTIAL_KEY=
+# The OAuth consent callback (ADR 0085), exactly as registered at every
+# provider a YAML grant names: https, no query. Mounts the callback and lets a
+# run ask a user to connect a provider. Needs MELCHIZEDEK_CREDENTIAL_KEY.
+# OAUTH_REDIRECT_URI=https://agents.example.com/oauth/callback
+# Who may complete a callback (ADR 0114): required (default) — the browser
+# carries the user's identity, which only A2A_AUTH=header behind a gateway
+# gives it; state — the single-use state alone binds the flow to its user.
+# OAUTH_CALLBACK_IDENTITY=required
+# The hosts each provider's tokens may be sent to (ADR 0114), the operator's
+# binding, never the YAML's: provider=host,host;provider=host. A host is a
+# hostname, *.domain (subdomains only), IPv4 or [IPv6]; no scheme or port.
+# Unset: authorization_code grants are refused, client_credentials allowed.
+# Set: every grant's provider is listed and every host it calls is its own.
+# MELCHIZEDEK_OAUTH_HOSTS=tracker=api.tracker.example.com,auth.tracker.example.com
+# The hosts each static credential variable a YAML sends may be sent to
+# (ADR 0122): bearer_env, api_key.env and client_secret_env, each entry the
+# variable's name, '=', then its hosts (as above). Unset: each goes to the
+# host the YAML names, and the server and the doctor name it as unbound.
+# Set: it is the whole list; an unlisted variable is sent nowhere.
+# MELCHIZEDEK_CREDENTIAL_HOSTS=TRACKER_TOKEN=api.tracker.example.com;WEATHER_API_KEY=api.weather.example.com
 
 # ── Optional: Knowledge Bundle (wiki) ─────────────────────────────────────────
 # WIKI_ROOT: filesystem path of the OKF knowledge bundle the wiki tools serve.

package/AGENT_SETUP.md

@@ -26,7 +26,9 @@ Set up the melchizedek-agents framework on this machine.
    it. Never ask me to paste API keys into this chat, never read keys
    from elsewhere on my machine, and never commit .env.
 4. Run the offline test suite (`npm test`) and confirm every shipped
-   syndicate compiles.
+   syndicate compiles. Then run `npm run setup -- --auto`: it reports
+   which authentication level my environment is at, by variable name
+   only. Follow the melchizedek-onboard skill in skills/ to pick my level.
 5. Read README.md and QUICKSTART.md. Then report back with:
    - what you did and the test results,
    - the list of available syndicates (one line each, from the README

package/CHANGELOG.md

@@ -6,6 +6,530 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 1.2.0 — 2026-10-09
+
+Release 1.2.0 carries pauses and consent further down a turn and gives the
+YAML its last v2 keys (ADRs 0117–0123). A delegated subagent may run skill
+scripts and ask for OAuth consent; a nested workflow pauses the turn as a
+dispatch route or a workflow node; a nested dispatch syndicate routes as it
+does at the top; static credentials go only to hosts the operator binds;
+`tool_choice:` and `reasoning: xhigh | max` complete the provider-neutral
+keys; a background job's checkpoint has a cap, and a durable run resumes
+inside a dispatch route. `melchizedek-setup` is the new onboarding command.
+
+### Upgrade first
+
+Read this list before deploying 1.2.0 over 1.1.0.
+
+- **The older spelling's `reasoningEffort: xhigh` and `max` now reach the
+  provider** (ADR 0117). Since 1.0.0 they were read by nothing and sent
+  nowhere; an agent that still carries one now asks its model for that
+  effort (or the model's highest, see Added), and beside a `thinkingConfig`
+  that says `high` the word wins. Such an agent thinks harder and costs
+  more. Remove the word to keep the old behaviour.
+- **`ReasoningLevel` (`melchizedek-agents/models/contract`) gains `xhigh`
+  and `max`**, and `REASONING_BUDGETS` gains both keys (16,384 each,
+  `high`'s budget). An exhaustive `Record<ReasoningLevel, …>` or a `switch`
+  over the levels no longer type-checks without them (ADR 0117).
+- **A nested dispatch syndicate answers with its route's text, not its
+  classifier's JSON** (ADR 0120). A `yaml_reference` to a plan-dispatch
+  syndicate used to compile to its classifier alone, so its caller got the
+  routing verdict and its routes never ran; a prompt or parser that relied
+  on that verdict sees the specialist's answer now. A gate or skill scripts
+  on one of its routes is no longer a load error. `compileSubagentSpec`
+  refuses a reference to a dispatch syndicate by name: compile it with
+  `compileEntrySpec`.
+- **Child session keys for routes and nodes carry their kind and the agent
+  path** (ADR 0119, ADR 0120). A nested syndicate or nested workflow run as
+  a dispatch route is filed under `<app>/route:<route>`, and as a workflow
+  node under `<walk's app>/node:<node>` (`app/route:Writer/node:Inner` two
+  levels down), no longer under the entry's name alone, so it no longer
+  shares a row with a same-named entry of another syndicate, and neither
+  can share a key with a delegated subagent's (`<app>/<caller>/<subagent>`,
+  unchanged). A session 1.1.0 stored under the entry's name, or under
+  `<app>/<entry>`, is still continued when the entry ran in that
+  conversation before; nothing stored is rewritten. Code that read the
+  walk's events at `{ appName: '<entry>' }` or `<app>/<entry>` reads them
+  at the kind key now.
+- **`melchizedek-doctor --check` exits 1 on a grant whose hosts the OAuth
+  host allowlist refuses.** The doctor already printed each such grant
+  (`✗ … is not one of them`, `MELCHIZEDEK_OAUTH_HOSTS`, ADR 0114) and still
+  exited 0; a CI step that runs `--check` against a served syndicate now
+  fails on it. A blocked syndicate, a runtime problem and the OAuth and
+  credential setup's problems fail it as before.
+
+### Added
+
+- **Skill scripts on a delegated subagent.** `skills.scripts: local` is no
+  longer a load error on a delegated subagent (or a nested delegate
+  syndicate's): a `run_skill_script` call there pauses the turn
+  `input-required` with `approval.path`, and the decision runs or refuses the
+  script in the subagent before its caller continues. An agent a map node
+  runs still may not carry scripts (ADR 0118).
+- **OAuth consent inside a delegated subagent.** A subagent's
+  `authorization_code` tool (an `mcp_auth` or OpenAPI `auth.oauth2` grant)
+  now asks for a missing grant instead of answering `not_connected`: the turn
+  ends `input-required` with `consent`, whose new optional `path` names the
+  agents from the turn's own down to the one that asked (`PendingConsent.path`;
+  the A2A `consent_request` data part carries `path` too). The callback stores
+  the grant under the conversation's app, and the next message resumes the
+  subagent's call. The host allowlist's checks are unchanged. The
+  systems_operator template's comment says authorization_code works on its
+  Systems subagent (ADR 0118).
+- **Nested dispatch syndicates route as at the top**
+  ([ADR 0120](./wiki/decisions/0120-nested-dispatch-syndicates-route-as-at-the-top.md)).
+  A `yaml_reference` to a plan-dispatch syndicate runs as a turn of its own
+  on its own conversation, wherever it appears (a delegated subagent, a
+  dispatch route, a workflow node): its classifier picks one of its routes
+  and the route answers, under the turn's `max_steps`, deadline and cancel.
+  Approvals, `ask_user` questions and OAuth consent on its routes, and
+  inside a route's own delegation, pause the turn `input-required` with
+  the path (`["Boss", "Team", "Ops"]` delegated, `["Team", "Ops"]` as a
+  route), over `runSyndicateTurn` and A2A; the answer resumes that route
+  without classifying again. Its grants are stored under the root's app.
+  As a workflow node it fails on a consent pause. A route carrying the
+  entry's own name, a `map` node over one, and a reference cycle below it
+  are refused by name before any model call. Surface:
+  `melchizedek-agents/compile` gains the `DispatchSpec` type, a
+  `{ kind: 'dispatch'; dispatch: DispatchSpec }` variant on `EntrySpec` and
+  `SpecTool`, and an optional `WorkflowSpec.dispatches`; `melchizedek-agents/runtime/turnControl`
+  gains the optional `TurnControl.nestedDispatch` hook and the
+  `NestedDispatchRun` and `NestedDispatchEnd` types. The generated
+  `syndicate.schema.json` describes `yaml_reference` accordingly.
+- **Static credentials go only to hosts the operator binds** (ADR 0122).
+  `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;…"`,
+  or `createA2AApp({ credentialHosts })`, binds each credential variable a
+  YAML sends (`bearer_env`, `api_key.env`, `client_secret_env`) to its hosts.
+  Unset, nothing changes: `melchizedek-serve` warns at boot and
+  `melchizedek-doctor` shows a `credentials` warning naming each unbound
+  variable. Set, it is the whole list, checked when a syndicate loads, when
+  it compiles and before each send; a refused call sends nothing. New
+  modules `melchizedek-agents/tools/credentialHosts` and
+  `melchizedek-agents/tools/credentialUses` (through the existing
+  `./tools/*` export); `openApiServers` in `tools/openapiTools`;
+  `DoctorResult.credentials`; the server's banner gains a `creds` line,
+  and `oauthServerSetup` returns `credentialSummary`.
+- **`tool_choice:`**, a v2 agent key (ADR 0117): `auto` (the default),
+  `none`, `required` (some tool) or `{ name: <tool> }` (that tool). It
+  replaces `generateContentConfig.toolConfig.functionCallingConfig`, may not
+  sit beside it, and is refused on a `yaml_reference` or `a2a_agent_url`
+  subagent. Each provider sends it as before, weakening a forced choice
+  where it must (`llm.tool_choice.weakened`).
+- **`reasoning: xhigh` and `reasoning: max`** (ADR 0117). They reach the
+  models that take them: both as `output_config.effort` on Claude's adaptive
+  generations, `max` on Kimi K3 (and `xhigh` rounds up to it, so K3 can be
+  sent `max` again), `xhigh` on GPT-5.2 and later and on grok-4.7. Every
+  other path sends the model's highest setting (`high`, Gemini's `HIGH`,
+  or `high`'s 16,384-token budget on Claude 4.6 and earlier and Gemini 2.x;
+  `high` on a gateway for any id) and marks the `llm.request` span
+  `llm.reasoning.weakened` with the level asked for. The capability
+  matrix states each path: `REASONING_ABOVE_HIGH`
+  (`melchizedek-agents/models/capabilities`), rendered under
+  `npm run doctor -- --matrix`.
+- `melchizedek-agents/models/reasoning` exports `effortCeiling(model)`,
+  `effortWord(model, setting, ceiling?)`, `isAboveHigh` and
+  `REASONING_ORDER`. `ChatCompletionsAdapter` gains the protected hooks
+  `reasoningCeiling(model)` and `effortFor(model, setting)`.
+- **A cap on a background job's checkpoint**
+  ([ADR 0121](./wiki/decisions/0121-checkpoint-cap-and-dispatch-route-resume.md)).
+  A checkpoint above `MELCHIZEDEK_CHECKPOINT_MAX_BYTES` (the worker's
+  variable; a positive whole number of bytes of JSON, default 5 MiB) is
+  not stored: the job keeps its previous checkpoint, the save still reports
+  whether the claim holds (a cancel still stops the run), and one log line
+  names the job id and the sizes. New in `melchizedek-agents/tools/taskTools`:
+  `TaskBackendOptions` (`checkpointMaxBytes`, `log`), `fileTaskBackendWith`,
+  `checkpointJson`, `checkpointMaxBytesSetting`, `DEFAULT_CHECKPOINT_MAX_BYTES`
+  and `CHECKPOINT_MAX_BYTES_ENV`; `PostgresStorageOptions.taskQueue` passes
+  the options to the Postgres queue. The file store's checkpoint sidecar is
+  written compact; one written by 1.1.0 still reads.
+- **`melchizedek-setup`, the onboarding command** (new bin; `npm run setup`
+  in a clone). A menu of nine authentication levels (no key / local
+  Ollama, one provider's key, several, a gateway key, Vertex AI / Bedrock /
+  Azure credentials, per-caller keys when serving, caller identities
+  through `A2A_AUTH`, OAuth tool grants, and subscription sign-ins), each
+  with a startup guide: the variables to set (names and shapes only), the
+  doctor check, the shipped templates and examples that run there, and the
+  first commands. `--auto` reads the doctor's result and prints the guide
+  for the highest level it detects, never a value; `--level <id|n>` prints
+  one guide; `--write-env` creates `.env` from `.env.example` with the
+  level's names blank, never over an existing file and only when git
+  ignores `.env` (ADR 0123).
+- **`ONBOARDING.md`** ships in the package: the same guides, generated from
+  the same code (`npm run setup -- --markdown`).
+- **Five onboarding skills** in `skills/`: `melchizedek-onboard` (triage:
+  "what do you have?") and `melchizedek-onboard-local`, `-keys`, `-cloud`
+  and `-serve`. `npx melchizedek-skills install` puts them in
+  `.claude/skills/` and `.agents/skills/` with the rest of the suite.
+- **`melchizedek-skills install --agents-md`** also writes a pointer to the
+  skills into the project's `AGENTS.md` (created when absent; only the
+  block between its markers is ever rewritten).
+- **The doctor's `serving` line.** When any A2A identity or billing variable
+  is set, `npm run doctor` prints the `A2A_AUTH` mode, `A2A_KEY_MODE`,
+  which serving variables are set and what the server would refuse to start
+  on, by name. `--json` gains `providers` (the providers line as data) and
+  `serving`.
+- **`ToolCredentialError.allowlist`** (`melchizedek-agents/tools/auth`,
+  with the `HostAllowlist` type): on a `host_refused` error, `'oauth'` when
+  the OAuth host allowlist refused a token's host (ADR 0114) and
+  `'credential'` when the credential host allowlist refused a client
+  secret's (ADR 0122). The constructor takes it as an optional third
+  argument.
+
+### Changed
+
+- **A nested workflow run as a dispatch route or a workflow node pauses the
+  turn** ([ADR 0119](./wiki/decisions/0119-workflow-routes-and-nodes-pause-the-turn.md)).
+  Its `ask_user` nodes and gated agent nodes (`require_approval`, skill
+  scripts) are no longer a load error there: the turn ends `input-required`
+  with `result.input` or `result.approval`, whose `path` runs from the route
+  or node down to the node that asked (`["Writer", "Send"]`, and further
+  down through a node that is itself a nested workflow), over
+  `runSyndicateTurn` and A2A. The next message answers it: a decision, or a
+  plain-text reply to the question, resumes a paused route without running
+  the classifier (`route.decidedBy` `approval` or `answer`); any other
+  message while an approval waits repeats the request and runs nothing. A
+  workflow node resumes inside the caller's walk. The conversation of a
+  paused route ends on the route's pause record (no content, the walk's
+  open interrupt ids in `longRunningToolIds`) in place of its answer.
+- `compileEntrySpec` and `compileWorkflowSpec` still accept their
+  `delegated` argument; it no longer changes what compiles.
+- **`melchizedek-codemod` converts the rest of `generateContentConfig`**
+  (ADR 0117): `toolConfig` becomes `tool_choice:` (mode `ANY` with several
+  allowed names becomes `required`, which is what the engine already sent,
+  with a note), `reasoningEffort: xhigh | max` becomes `reasoning:`, and
+  `thinkingConfig.includeThoughts` is dropped whatever its value: nothing
+  reads it, and the Gemini adapter asks for the thought trace whenever
+  reasoning is not `none` (a `true` gets a note). Only `toolConfig` mode
+  `VALIDATED` and `thinkingBudget: -1` stay, with a note.
+- **The council example's Moderator consults both subagents in one step**
+  (`config/agents/examples/council.yaml`). Its instruction asks for the
+  Advocate and the Skeptic together, both function calls in one response,
+  each given the user's full claim verbatim, so the two run at once under
+  `max_concurrency` (ADR 0116). Its role, its three-part verdict and its
+  guardrails are unchanged; the YAML keeps its v2 keys. A project that
+  copied the example keeps the old prompt until it copies it again.
+- The header comments of `examples/critic.yaml`, `examples/image_production.yaml`
+  and `templates/intake_extractor.yaml` say that a schema on a leaf is
+  their choice, not a rule: an orchestrator that delegates may hold one
+  (ADR 0109). Comments only; the agents are unchanged.
+
+### Fixed
+
+- **A durable dispatch run resumes inside its agent route** (ADR 0121). A
+  background job killed mid-step inside a plan-dispatch route used to start
+  over (its checkpoint was set aside); it now resumes from its checkpoint,
+  classifying again and storing what an uninterrupted run stores. A nested
+  dispatch syndicate's route resumes the same way, and checkpoints 1.1.0
+  saved inside a route restore.
+- **An unrecognised `MODEL_GATEWAY` is never echoed.** The doctor (its
+  `gateway` line and `--json`), `gatewayProblem()` and the boot log said
+  the value back, which may be a key pasted into the wrong variable. They
+  now say `MODEL_GATEWAY is set to an unrecognised value (not shown)` and
+  name the accepted values (`vercel`, `openrouter`).
+- **A `host_refused` refusal names the allowlist that refused.** A client
+  secret refused by the credential host allowlist was reported as the OAuth
+  host allowlist's refusal. The message now names
+  `MELCHIZEDEK_OAUTH_HOSTS` for a token's host and
+  `MELCHIZEDEK_CREDENTIAL_HOSTS` for a client secret's.
+
+### Not supported, on purpose
+
+- ChatGPT / Codex, Claude.ai and Gemini CLI subscription sign-ins are not a
+  way to fund the engine, and nothing reads their tokens. The setup menu's
+  level 9 says so and routes to each vendor's API key or cloud platform.
+
+## 1.1.0 — 2026-10-09
+
+Release 1.1.0 closes workstream 6 of the ADK-independence plan (ADRs
+0109–0116): the first features built on the engine's own loop. An
+orchestrator can delegate and answer in its own JSON schema; a pause inside
+a delegated subagent or a nested syndicate reaches the turn; tools can hold
+OAuth grants declared in YAML, sent only to hosts the operator binds;
+background jobs checkpoint and resume, and cancel works across replicas; a
+step's subagent calls run at once; and the YAML gains provider-neutral v2
+keys, with a codemod. Two fixes: `trace: false` now records nothing, and
+MCP settings on an orchestrator are honoured.
+
+### Upgrade
+
+Read this list before deploying 1.1.0.
+
+1. **Apply migration `0014_durable_runs` before you deploy**
+   (`db/migrations/0014_durable_runs.sql`, through `npx melchizedek-db
+   apply`) on any server or worker that uses `DATABASE_URL`. Every save
+   of the Postgres task stores now writes the new columns
+   (`adk_a2a_tasks.cancel_requested_at`, `melchizedek_tasks.checkpoint`),
+   so without the migration every Postgres task-store save fails. The A2A
+   server refuses to start against a database behind 0014 unless
+   `ALLOW_SCHEMA_MISMATCH=true` is set, and with that override its saves
+   fail. The migration adds nullable columns only and is safe to re-run.
+2. **New OAuth environment variables** for `melchizedek-serve`, needed
+   only when a served syndicate declares an `oauth2` grant:
+   `MELCHIZEDEK_OAUTH_HOSTS` (which hosts each provider's tokens may go to),
+   `OAUTH_REDIRECT_URI` (the consent callback: https, or http on a loopback
+   host) and `OAUTH_CALLBACK_IDENTITY` (`required`, the default, or
+   `state`). `MELCHIZEDEK_CREDENTIAL_KEY` keys the credential store.
+3. **`authorization_code` grants are refused until an allowlist is set.**
+   With no `MELCHIZEDEK_OAUTH_HOSTS` (or `createA2AApp({ oauthHosts })`), a
+   syndicate holding an `authorization_code` grant is refused when served;
+   `client_credentials` grants are allowed.
+4. **`max_concurrency` now runs a step's subagent calls at once**, at most
+   four by default. Set `max_concurrency: 1` at the root of a delegate
+   syndicate to restore the old one-after-another order.
+5. **YAML v2 keys.** `sampling:`, `output:` and `model_overrides:` replace
+   `generateContentConfig` and `outputSchema`. The old spellings are
+   deprecated, not removed: a v1 file loads and behaves as before, with one
+   deprecation line per file per process. `npx melchizedek-codemod
+   [--check] <file|dir>…` rewrites v1 files to v2.
+6. **`trace: false` now records nothing.** A turn run with
+   `runSyndicateTurn({ trace: false })` writes no telemetry row and exports
+   no span. If you relied on its agent, model or tool spans, trace the turn.
+7. **Child sessions are keyed by agent path.** A delegated subagent's
+   session is filed under `<app>/<caller>/<subagent>`; conversations stored
+   under the old key still resume. Code that reads a subagent's session by
+   its name alone reads the path instead.
+8. **The capability matrix has a new member, `structured_output_with_tools`.**
+   Code that builds a `Record<Capability, …>` must add it.
+9. **An A2A task cancelled while waiting for the turn lock now ends
+   `canceled`**, not `rejected`.
+
+### Breaking — read before upgrading
+
+- **Breaking: migration 0014 is required** on a Postgres deployment
+  (Upgrade item 1).
+- **Breaking: `Capability`, `CAPABILITIES` and `CAPABILITY_MATRIX`
+  (`melchizedek-agents/models/capabilities`) gain
+  `structured_output_with_tools`**, so an exhaustive
+  `Record<Capability, …>` no longer type-checks without it.
+- **Breaking: a step's calls to subagents run concurrently by default**
+  (ADR 0116). See Changed; `max_concurrency: 1` keeps the old order.
+- **Breaking: a delegated subagent's own session is filed under its agent
+  path** (ADR 0111). See Changed; stored conversations still resume.
+- **Breaking: `runSyndicateTurn({ trace: false })` records nothing**: no
+  span of any kind, no ledger row, no export. See Fixed.
+- **Breaking: an A2A task cancelled while it waits for its conversation's
+  turn lock ends `canceled`**, not `rejected` (ADR 0113).
+
+### Added
+
+- **An orchestrator that delegates can answer in its own `outputSchema`**
+  (ADR 0109). An agent holding an `outputSchema` beside subagents or tools
+  calls them first, then ends its turn on one JSON object matching the
+  schema; no relay leaf or `dispatch:` block is needed (plan-dispatch stays
+  available). On Claude from Opus 4.8, Sonnet 5 and Haiku 5.5, on every
+  OpenAI id, and on Gemini 2 and later through Vertex AI, the schema now
+  travels in the provider's own structured-output field in the same request
+  as the tools (`output_config.format`, `text.format`, `responseJsonSchema`)
+  instead of as a `set_model_response` tool, on the agent's `fallback_model`
+  too; every other path keeps `set_model_response`.
+- **The capability matrix gains `structured_output_with_tools`**
+  (`melchizedek-agents/models/capabilities`): supported on Anthropic and
+  OpenAI (and Gemini on Vertex AI), degraded (`set_model_response`) on the
+  Gemini API, xAI, Moonshot, Ollama and the gateway. `npm run doctor` names
+  it as a gap for an agent with a schema beside tools on a degraded path.
+  `outputSchemaBesideTools(model)` says whether a model's path takes both.
+- **New starter-pack example `config/agents/examples/structured_critic.yaml`**
+  (`npm run syndicate:structured-critic`): the critic as one agent, an
+  orchestrator on `claude-opus-5-5` that asks a Drafter on
+  `claude-haiku-5-5` for a draft and grades it in its own `output.schema`.
+  It needs only `ANTHROPIC_API_KEY`.
+- **A pause inside a delegated subagent reaches the turn** (WS6-2a,
+  [ADR 0110](./wiki/decisions/0110-pauses-inside-delegated-subagents-reach-the-turn.md)).
+  `require_approval` and `ask_user` are allowed on a delegated subagent, and
+  gates inside a nested delegate syndicate (`yaml_reference`) no longer fail
+  to load. The turn ends `input-required` with the request or question; the
+  decision or answer goes back down to the subagent, which finishes before
+  its caller continues. Before, a gate there was a load error and a pause
+  answered the call with an empty text.
+- `PendingApproval.path` and `PendingInput.path` (optional): the agents from
+  the turn's own agent down to the one that asked, set only for a pause
+  inside a delegated subagent. The A2A `approval_request` and
+  `input_request` data parts carry `path` beside their fields when it is set.
+- **Pauses inside nested syndicates reach the turn** (WS6-2b,
+  [ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md)). An
+  approval request or `ask_user` question raised inside a `yaml_reference`
+  subagent ends the turn `input-required` with the agent path, over
+  `runSyndicateTurn` and A2A, and the answer resumes it. A nested dispatch
+  syndicate may gate its classifier (a gate on one of its routes, which never
+  run nested, is refused by name). A nested workflow delegated to as a
+  subagent may hold `ask_user` nodes and gated agent nodes; the path ends at
+  the node. As a dispatch route or a workflow node, a nested workflow's
+  pauses stay refused, with a message that says so.
+- **OAuth grants in YAML (`auth: { oauth2 }`, `mcp_auth: { oauth2 }`;
+  ADR 0112).** An `openapi:` entry's `auth` takes a third form, `oauth2`,
+  and an agent with `mcp_server_url` may declare `mcp_auth: { oauth2 }`.
+  The block names a `provider`, a `grant` (`authorization_code` or
+  `client_credentials`), `authorization_url`, `token_url`, `client_id` or
+  `client_id_env`, `client_secret_env` and `scopes`; secrets are
+  environment variable names, never values, under the same rule as
+  `bearer_env`. `authorization_code` sends the run's user's own token
+  (`ctx.accessToken`, so the consent pause asks a user who has not granted
+  it); `client_credentials` sends the server's own token from the token
+  endpoint, held in memory until shortly before it expires. A token goes
+  only over https (or http to a loopback host). An authorization-code MCP
+  server needs `mcp_tools` and runs each user on their own connection.
+  `npm run doctor` lists every tool that needs a grant. New module
+  `melchizedek-agents/tools/oauthTools` (`oauthClientsFor`, which builds
+  `oauthConsent({ providers })` from the YAML, `oauthRefreshProviders`,
+  which gives `credentialStore({ providers })` the matching refresh hooks,
+  `clientCredentialsGrant`, `oauthTokenSource`, `tokenTransportProblem`)
+  and `melchizedek-agents/tools/credentialEnv` (`credentialEnvProblem`,
+  still exported from `tools/openapiTools`), both under the existing
+  `./tools/*` export. `OAuthTokenSource` takes the call's destination
+  (`(ctx, destination)`), and `oauthTokenSource` accepts several servers.
+  `ToolCredentialError` gains the codes `unavailable` and `grant_failed`,
+  and `createMcpTools` / `loadMcpTools` an optional second argument. The
+  systems_operator template carries a commented `mcp_auth` block.
+- **The OAuth host allowlist (`MELCHIZEDEK_OAUTH_HOSTS`,
+  `createA2AApp({ oauthHosts })`; ADR 0114).** The operator binds each
+  provider to the hosts its tokens and client secret may be sent to
+  (`provider=host,host;…`; `*.domain` for subdomains). With none, an
+  `authorization_code` grant is refused and `client_credentials` allowed;
+  with one, every grant's provider must be listed and its server, token
+  endpoint and authorization endpoint must be that provider's hosts. A
+  syndicate that breaks it is refused when served, when compiled and at
+  each call (`ToolCredentialError` code `host_refused`). New module
+  `melchizedek-agents/tools/oauthHosts` (`parseOAuthHosts`,
+  `checkOAuthHosts`, `setOAuthHosts`, `oauthHosts`, `hostAllowed`,
+  `oauthHostProblem`) under the existing `./tools/*` export;
+  `tools/oauthTools` gains `oauthGrantHostProblems`, `oauthCallProblem`,
+  `syndicateOAuthGrants` and `syndicateOAuthHostProblems`, and
+  `oauthClientsFor` an `allowlist` option.
+- **`melchizedek-serve` wires tool credentials and the consent step**
+  from `MELCHIZEDEK_CREDENTIAL_KEY` (rows in Postgres with `DATABASE_URL`,
+  else process memory), `OAUTH_REDIRECT_URI`, `OAUTH_CALLBACK_IDENTITY`
+  (`required`, the default, or `state`) and `MELCHIZEDEK_OAUTH_HOSTS`, with
+  the consent clients and refresh hooks built from the served syndicate
+  files. `melchizedek-agents/server` exports `serverOAuth` and
+  `servedFileSyndicates`. `npm run doctor` prints an `oauth` line (which
+  variables are set, and each problem by name) and each grant's host
+  refusals; `--check` fails on an OAuth problem.
+- **Durable long-running runs** (WS6-5, ADR 0113):
+  - **The worker resumes a job instead of starting over.**
+    `melchizedek-worker` checkpoints each job's sessions beside the job at
+    every step boundary (Postgres: the `checkpoint` column; the JSON store:
+    `<store>.checkpoints.json`). A job claimed again after its worker
+    stopped resumes from its last checkpoint. A dispatch syndicate
+    checkpointed inside an agent route starts over, and its classifier runs
+    again.
+  - **SIGTERM re-queues the job in hand** with its checkpoint, so the next
+    worker finishes it. Before, the job was recorded as failed.
+  - **A running background job can be cancelled.** `task_update` with
+    `status: cancelled` now accepts a running job. The worker stops at its
+    next lease renewal or checkpoint save and writes no result.
+  - **A2A cancel works across replicas**
+    (`melchizedek-agents/storage/postgres`): a `tasks/cancel` that reaches a
+    replica not running the task answers `canceled` and records the
+    request; the replica holding the task's lease aborts the run on its
+    lease heartbeat; the stored task stays `canceled`; the reaper keeps a
+    cancel that was already reported. New:
+    `PostgresTaskStore.requestCancel(taskId, context)`, the optional
+    `leases.cancelRequested` on `postgresStorage()`, and the optional
+    `storage.leases.cancelRequested` option of `createA2AApp`.
+  - **`TaskBackend` (`melchizedek-agents/tools/taskTools`), additive only:**
+    new optional members `saveCheckpoint` and `loadCheckpoint`; `renew` may
+    resolve `false` when the claim is gone; new export `taskCheckpointPath`.
+    A backend you wrote yourself still type-checks. It just does not
+    checkpoint.
+- **YAML schema v2: provider-neutral keys** (WS6-4, ADR 0115).
+  `sampling: { temperature, top_p, max_output_tokens, stop }`,
+  `output: { schema, mime }` (`application/json` or `text/plain`) and
+  `reasoning:` (ADR 0047) replace `generateContentConfig` and
+  `outputSchema`. `model_overrides.<provider>` (`gemini`, `anthropic`,
+  `openai`, `xai`, `moonshot`, `ollama`) gives one provider its own
+  `instruction` or an `instruction_append`, applied for the provider the
+  agent's model routes to.
+- **New bin `melchizedek-codemod [--check] <file|dir>…`** rewrites v1 YAML
+  into v2, keeping comments and layout; idempotent; `--check` exits
+  non-zero when a file would change. A registry row is migrated by running
+  it on the file it was published from and republishing.
+- **`LoadSyndicateOptions.onWarning`** receives the v1 deprecation line
+  (default `console.warn`). The agent YAML types (`AgentYamlConfig`,
+  `SubagentYamlConfig`) gain `sampling`, `output` and `model_overrides`.
+- **`max_concurrency`**, a new optional root key of a delegate syndicate:
+  a positive integer up to 32, default 4 (ADR 0116). See Changed.
+- **`turnUntraced()`** (`melchizedek-agents/runtime/turnControl`) says
+  whether the running code belongs to a turn that opted out of tracing;
+  `createTurnControl` takes `untraced`, and `TurnControl` carries it.
+  **`startEngineSpan(tracerName, name, options?)`**
+  (`melchizedek-agents/observability/tracer`) starts a span the way the
+  engine does: a non-recording one, without starting the tracer, inside an
+  untraced turn.
+- Engine internals with no exports map entry: `delegatedPauses`,
+  `openCalls`, `resumedDelegations` in `lib/runtime/native/interrupts.ts`;
+  `resumeSubagent`, `SubagentPause`, `resumeWorkflowSubagent`,
+  `childAppName`, `legacyChild` in `lib/runtime/native/delegate.ts`;
+  `runDurableTurn`, `checkpointingSessions` in
+  `lib/runtime/native/checkpoint.ts` (the worker's runner).
+
+### Changed
+
+- **A step's calls to subagents run at once** (ADR 0116). When an
+  orchestrator's model calls several subagents in one step (the council's
+  Advocate and Skeptic, say), they now run concurrently instead of one after
+  another, at most `max_concurrency` at a time (default 4).
+  `max_concurrency: 1` keeps the old order. Two calls to the same subagent
+  in one step still run one after the other on its one session. The stored
+  responses stay in call order whatever order the subagents finish in, so
+  stored history does not change; a pause, a cancel, `max_steps` and durable
+  checkpoints keep their rules. The key is refused beside `workflow:` (use
+  `workflow.max_concurrency`) and `dispatch:`. Other tool calls are
+  unchanged.
+- **A delegated subagent's own session is filed under its agent path**
+  (WS6-2b, ADR 0111): `<app>/<caller>/<subagent>`, and below a nested
+  syndicate `<app>/<caller>/<subagent>/<inner>`, instead of the subagent's
+  name alone, so two syndicates with a same-named subagent on one
+  conversation no longer share it. A conversation stored before keeps its
+  subagents' sessions under the old key: they are still read, continued and
+  resumed. Code that read a subagent's session directly by its name reads
+  the path instead. The stored events do not change.
+- **`generateContentConfig` and `outputSchema` are deprecated, not
+  removed** (ADR 0115). A v1 file loads and behaves exactly as before; each
+  load that finds them prints one line, once per file or registry id per
+  process, naming the key paths (never their values). A v2 key beside its
+  v1 spelling on one agent (`sampling.temperature` with
+  `generateContentConfig.temperature`, `output.schema` with
+  `outputSchema`, …) is a load error. `toolConfig` and the effort words
+  `xhigh` and `max` have no v2 key yet and stay readable there.
+  `syndicate.schema.json` marks both keys `deprecated`. The loader (and
+  `validateSyndicateConfig`) returns the engine form: `sampling` and
+  `output` arrive folded into `generateContentConfig` and `outputSchema`.
+- **Every shipped example, template, the annotated `syndicateSchema.yaml`
+  and the author skill's `minimal.yaml` are in the v2 spelling.** Copies of
+  them keep working either way. The `ares` example's search agent now says
+  `reasoning: none` (`thinkingLevel: MINIMAL` on Gemini 3) where it said
+  `thinkingBudget: 0`.
+- **An A2A task cancelled during the turn-lock wait** now ends `canceled`,
+  not `rejected` (ADR 0113).
+- **An OpenAPI `auth` that sets two forms** now reads "exactly one of
+  bearer_env, api_key or oauth2" (was "exactly one of bearer_env or
+  api_key").
+- **The authoring skill (`skills/melchizedek-author`) allows an
+  `output: { schema }` on an orchestrator that delegates** when the answer
+  is the orchestrator's own structured judgment (ADR 0109), and points at
+  `structured_critic.yaml`; a schema on a leaf stays the choice when the
+  user should receive a specialist's answer.
+
+### Fixed
+
+- **`runSyndicateTurn({ trace: false })` records nothing.** It used to drop
+  only the turn's root span: the agent, model-step, `llm.request` and tool
+  spans still started the global tracer, so with `TELEMETRY_SUPABASE=true`
+  an untraced turn still wrote `adk_telemetry` rows (and could write
+  `adk_payloads` rows), and with `OTEL_EXPORTER_OTLP_ENDPOINT` set it still
+  exported. Now a turn with `trace: false` opens no span of any kind, sends
+  nothing to the ledger, the console exporter, `onSpanEnd` listeners or an
+  OTLP endpoint, and does not start the tracer. Its step budget and its
+  `usage` are unchanged. The default (traced) is unchanged, and the A2A
+  server and the chat bin trace as before.
+- **`mcp_server_url` and `mcp_tools` on the orchestrator are honoured.**
+  The schema accepted them there, but only subagents read them, so a
+  one-agent syndicate with an MCP server on its orchestrator got no MCP
+  tools and no warning. The orchestrator now resolves them as a subagent
+  does (narrowed by `mcp_tools`, gateable by its `require_approval`). On a
+  plan-dispatch syndicate the orchestrator is the classifier, and an MCP
+  server declared there is now dialled at compile time.
+
 ## 1.0.3 — 2026-10-09
 
 Dependency updates and one packaging fix. No export, bin, YAML key or