melchizedek-agents 1.1.0 → 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.
@@ -262,6 +266,12 @@ PUBLIC_URL=
 # 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,238 @@ 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

package/DOCUMENTATION.md

@@ -135,11 +135,12 @@ Field reference:
 | `name` / `model` / `instruction` | agent | The agent triple. Any Gemini id, `claude-*`, or `ollama/*` for open-weight local models (see §5). |
 | `description` | subagent | **The delegation API.** The orchestrator reads this when deciding to hand off — write it like a function signature ("Use this subagent to…, pass it…"). |
 | `tools` | agent | Names resolved by the tool registry (§3). Long-term memory agents add `preload_memory` / `load_memory`. |
-| `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). Unset, each adapter keeps its own default. |
+| `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). `xhigh` and `max` reach the models that take them (both on Claude from Opus 4.7 and Sonnet 5, `max` on Kimi K3, `xhigh` on GPT-5.2 and later and grok-4.7); elsewhere the model's highest setting is sent and the span carries `llm.reasoning.weakened` (`npm run doctor -- --matrix` lists each path, [ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). Unset, each adapter keeps its own default. |
 | `sampling` | agent | `{ temperature, top_p, max_output_tokens, stop }`, the fields the engine sends to every provider; each adapter sends the ones its API takes ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `output` | agent | `{ schema, mime }`. `mime` is `application/json` (JSON mode, with or without a schema) or `text/plain` (the default). `schema` is the structured-JSON contract: the agent ends its turn on one JSON object matching it. An orchestrator may hold one beside its subagents: it delegates first, then answers in the schema itself. The schema travels in the provider's own structured-output field beside the tools on Claude from Opus 4.8, Sonnet 5 and Haiku 5.5, on OpenAI, and on Gemini 2+ through Vertex AI, and as a `set_model_response` tool elsewhere (the capability matrix's `structured_output_with_tools`, [ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md)). Worked example: `examples/structured_critic.yaml`. A leaf that holds the schema (`critic.yaml`) and plan-dispatch remain the choices when the answer should be a specialist's. |
 | `model_overrides` | agent | A prompt nuance for one provider: keyed by `gemini`, `anthropic`, `openai`, `xai`, `moonshot` or `ollama`, each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after a blank line). The entry for the provider of the agent's `model` applies, before the skills index is appended; a `fallback_model` gets the primary's instruction. |
-| `generateContentConfig` / `outputSchema` | agent | The deprecated v1 spelling of `sampling`, `output.mime`, `reasoning` (as `thinkingConfig` / `reasoningEffort`) and `output.schema`. Both still load and behave the same; a load that finds either prints one deprecation line per file per process (`LoadSyndicateOptions.onWarning`, default `console.warn`), and a v2 key beside its v1 spelling on one agent is a load error. Only `toolConfig` and the effort words `xhigh` / `max` have no v2 form yet; `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider. `npx melchizedek-codemod [--check] <file|dir>` rewrites a v1 file to v2, comments kept ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
+| `tool_choice` | agent | Which tools the model may call: `auto` (the default), `none`, `required` (some tool), or `{ name: <tool> }` (that tool). A provider that rejects forcing sends a weaker choice and marks the span `llm.tool_choice.weakened` ([ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). |
+| `generateContentConfig` / `outputSchema` | agent | The deprecated v1 spelling of `sampling`, `output.mime`, `reasoning` (as `thinkingConfig` / `reasoningEffort`), `tool_choice` (as `toolConfig.functionCallingConfig`) and `output.schema`. Both still load and behave the same; a load that finds either prints one deprecation line per file per process (`LoadSyndicateOptions.onWarning`, default `console.warn`), and a v2 key beside its v1 spelling on one agent is a load error. Only `toolConfig.functionCallingConfig.mode: VALIDATED` and Gemini's dynamic budget (`thinkingBudget: -1`) have no v2 form; `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider, and the codemod drops `includeThoughts`. `npx melchizedek-codemod [--check] <file|dir>` rewrites a v1 file to v2, comments kept ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `yaml_reference` | subagent | Mount another syndicate file as a nested subagent. |
 | `a2a_agent_url` | subagent | A REMOTE agent over A2A (§6): the orchestrator delegates to it with one `request` argument; in plan-dispatch it can be a route. No `model`/`instruction` — the remote agent has its own. Credentials come from `A2A_AGENT_TOKENS`, never YAML. |
 | `max_steps` | root | Cap on model calls per turn, counted across every agent the turn reaches (orchestrator, subagents, nested syndicates). Exceeding it fails the turn with `STEP_LIMIT`. |
@@ -185,7 +186,7 @@ function, and every adapter recognises it by marker
 | `inspect_image` | Contract | **Blind visual inventory** of a file under `outputs/`: subjects with exact counts, composition, light, palette, medium cues, artifacts — zero quality judgments. Its signature accepts *only* a file path, so an orchestrator cannot leak expectations into the observation (see `image_production.yaml`). |
 | `task_add` / `task_list` / `task_get` / `task_update` | Contract | A to-do list and job queue. Default: a single-user JSON file (`MELCHIZEDEK_TASKS_FILE`, default `outputs/tasks.json`), so every caller of a shared endpoint shares one list. With `DATABASE_URL` (migration 0009) each caller has its own list, scoped by the caller's scope key, and any number of workers take jobs safely. |
 | `ask_user` | Contract, long-running | Asks the person one question (optionally with `options`) and ends the turn `input-required`; the next message on the conversation is the call's result. Any agent but a workflow node's; inside a delegated subagent the question reaches the person with the agent path (§6, Questions). |
-| `task_queue` | Contract | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. A run is durable (ADR 0113): it is checkpointed beside the job at every step boundary (migration 0014 on Postgres), a job claimed again resumes from its last checkpoint, SIGTERM re-queues the job in hand, and `task_update` can cancel a running job. |
+| `task_queue` | Contract | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. A run is durable (ADR 0113): it is checkpointed beside the job at every step boundary (migration 0014 on Postgres), a job claimed again resumes from its last checkpoint (inside a dispatch route too, ADR 0121), a checkpoint above `MELCHIZEDEK_CHECKPOINT_MAX_BYTES` (default 5 MiB of JSON; `TaskBackendOptions.checkpointMaxBytes`, `postgresStorage({ taskQueue })`) is skipped and the previous one kept, SIGTERM re-queues the job in hand, and `task_update` can cancel a running job. |
 
 **MCP tools** are the exception to the registry: a subagent with
 `mcp_server_url:` in its YAML gets its tools from a remote MCP server at
@@ -238,7 +239,12 @@ with no allowlist, `authorization_code` is refused. An unset variable fails the
 (the database URL, a provider key, an `A2A_` secret: anything `.env.example`
 documents), since the YAML chooses the host it goes to.
 `OPENAPI_CREDENTIAL_ENVS`, when set, is the exact list of variables an `auth`
-may name. A refused or unset variable fails the compile, and a static token is applied to the request,
+may name. `MELCHIZEDEK_CREDENTIAL_HOSTS` binds each such variable to the hosts
+its value may reach (`TRACKER_TOKEN=api.tracker.example.com;…`, or
+`createA2AApp({ credentialHosts })`, [ADR 0122](./wiki/decisions/0122-static-credentials-go-only-to-hosts-the-operator-binds.md)):
+unset, a credential goes where the YAML says and the server and the doctor
+name it as unbound; set, it is the whole list, checked when a syndicate
+loads, when it compiles and before each call. A refused or unset variable fails the compile, and a static token is applied to the request,
 never stored in session state. Every server must be http(s) and pass the
 SSRF guard: its literal rules when the agent compiles, the full check with
 DNS before each call; `ALLOW_PRIVATE_OPENAPI=true` permits private hosts for
@@ -426,11 +432,26 @@ reads every syndicate YAML, resolves each agent's model under your `.env`,
 and prints one table — agent, model, provider, which declared server-side
 tools that path runs natively (✓) or drops (✗), and whether the path is
 funded — with one verdict per syndicate and the variables that would
-unlock the most. Read-only; no key value is ever printed. Every
+unlock the most. Read-only; no key value is ever printed, and a
+`MODEL_GATEWAY` it does not recognise is named as such, never repeated.
+`--check` exits 1 on a blocked syndicate, a runtime problem, a problem
+with the server's OAuth or credential settings, or a tool's OAuth grant
+whose hosts `MELCHIZEDEK_OAUTH_HOSTS` refuses. Every
 starter-pack file opens with a `# tier:` header (`keyless`, one provider
 such as `gemini`, or `multi-provider`) the doctor checks against the
 models. `GOOGLE_GENAI_API_KEY` alone runs fourteen of the nineteen examples.
 
+**Not sure where to start? `npx melchizedek-setup`** (`npm run setup` in a
+clone) opens a menu of authentication levels: no key (Ollama), one
+provider's key, several, a gateway key, Vertex AI / Bedrock / Azure,
+per-caller keys (BYOK), caller identities (`A2A_AUTH`), OAuth tool grants,
+and an honest entry for ChatGPT / Codex, Claude.ai and Gemini CLI sign-ins,
+which the engine does not use. Each prints a startup guide: variable names
+and shapes, the doctor check, the shipped files that run there, and the
+first commands. `--auto` reads the doctor's result and prints the guide
+for the highest level it detects, names only. The same guides, generated
+from the same code, are [`ONBOARDING.md`](./ONBOARDING.md).
+
 **One key instead of several — the gateway fallback.** Direct adapters
 are canonical: the native features above exist only on a provider's own
 endpoint. But with `MODEL_GATEWAY=vercel` (or `openrouter`) and
@@ -811,12 +832,19 @@ runs or refuses the call and finishes before its caller continues. The same
 holds inside nested syndicates
 ([ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md)): a
 nested delegate syndicate's gates anywhere in it, a nested dispatch
-syndicate's on its classifier (its routes never run when it is nested, so a
-gate on one is a load error), and a nested workflow's gated agent nodes and
+syndicate's on its routes, which it classifies and runs as at the top
+(`["Boss", "Team", "Ops"]`,
+[ADR 0120](./wiki/decisions/0120-nested-dispatch-syndicates-route-as-at-the-top.md)),
+and a nested workflow's gated agent nodes and
 `ask_user` nodes when the workflow is a delegated subagent; the path then
-ends at the node, e.g. `["Desk", "Writer", "Send"]`. A gate or `ask_user`
-node in a workflow run as a dispatch route or as another workflow's node is
-still a load error, as are skill scripts on a delegated subagent. Only function tools from the registry can be gated, not MCP tools
+ends at the node, e.g. `["Desk", "Writer", "Send"]`. A workflow run as a
+dispatch route or as another workflow's node pauses the turn the same way
+([ADR 0119](./wiki/decisions/0119-workflow-routes-and-nodes-pause-the-turn.md)),
+the path running from the route or node down, e.g. `["Writer", "Send"]`.
+Skill scripts (`skills.scripts: local`) on a delegated
+subagent pause the same way, with `run_skill_script` as the tool
+([ADR 0118](./wiki/decisions/0118-skill-scripts-and-oauth-consent-inside-delegated-subagents.md));
+an agent a map node runs still may not carry them. Only function tools from the registry can be gated, not MCP tools
 or native-search sentinels. In code, `runSyndicateTurn` returns
 `status: 'input-required'` with `approval`, and the next turn's part
 `approvalResponsePart(approval.id, approved)` answers it.
@@ -891,6 +919,13 @@ await createA2AApp({ /* … */ toolCredentials: { store, consent } });
    call again. A message sent before the grant gets the same request back,
    without a model call.
 
+The call may sit in a delegated subagent, at any depth (the systems_operator
+template's Systems, say): the request then carries `path`, the agents from
+the turn's own down to the one that asked (in the data part and in
+`consent.path`), the grant is stored under the conversation's app, and the
+next message resumes that subagent's call before its caller continues
+([ADR 0118](./wiki/decisions/0118-skill-scripts-and-oauth-consent-inside-delegated-subagents.md)).
+
 The callback refuses these, and stores nothing:
 
 - a state that is replayed, tampered with or older than ten minutes;
@@ -914,6 +949,7 @@ name a provider they declare, never define one):
 | `OAUTH_REDIRECT_URI` | `https://agents.example.com/oauth/callback` (no query) | The callback, as registered at every provider. Mounts it and lets a run ask a user to connect. Needs the key |
 | `OAUTH_CALLBACK_IDENTITY` | `required` (default) or `state` | `required`: the browser that completes a grant carries the flow's user's identity, which only `A2A_AUTH=header` behind a gateway gives it. `state`: the single-use state alone binds the flow (a forwarded link can connect the wrong account) |
 | `MELCHIZEDEK_OAUTH_HOSTS` | `provider=host,host;provider=host` | Which hosts each provider's tokens and client secret may be sent to. A host is a hostname, `*.domain` (subdomains only), IPv4 or `[IPv6]` |
+| `MELCHIZEDEK_CREDENTIAL_HOSTS` | `VARIABLE=host,host;VARIABLE=host` | Which hosts each static credential variable a YAML sends (`bearer_env`, `api_key.env`, `client_secret_env`) may be sent to. Unset: as the YAML says, each named as unbound. Set: the whole list ([ADR 0122](./wiki/decisions/0122-static-credentials-go-only-to-hosts-the-operator-binds.md)) |
 
 **The host allowlist** ([ADR 0114](./wiki/decisions/0114-oauth-tokens-go-only-to-hosts-the-operator-binds.md))
 is the operator's binding, never the YAML's: `MELCHIZEDEK_OAUTH_HOSTS`, or
@@ -929,6 +965,21 @@ token to. The server refuses to start on a malformed key, allowlist or
 redirect URI, or on a redirect URI without a key; `npm run doctor` reports
 each of these, and a declared grant with no key or redirect URI, by name.
 
+**The credential host allowlist** ([ADR 0122](./wiki/decisions/0122-static-credentials-go-only-to-hosts-the-operator-binds.md))
+does the same for the static credentials a YAML sends: `bearer_env` and
+`api_key.env` to an OpenAPI server, and `client_secret_env` to a token
+endpoint. `MELCHIZEDEK_CREDENTIAL_HOSTS`, or
+`createA2AApp({ credentialHosts: { TRACKER_TOKEN: ['api.tracker.example.com'] } })`,
+which wins. Unset, nothing changes: each credential goes to the host the
+YAML names, and the server's boot and `npm run doctor` name every variable a
+served YAML sends that no binding holds (names only). Set, it is the whole
+list: a variable not on it is sent nowhere, and one on it only to its own
+hosts. A syndicate that breaks the rule is refused when it loads, when it
+compiles, and each call (an OpenAPI call, a client-credentials token
+request, a consent code exchange, a refresh) checks again and sends nothing
+when refused. `MCP_BEARER_TOKENS` is not covered: it already maps each token
+to its host.
+
 #### Limits
 
 | Setting | Default |
@@ -1222,6 +1273,27 @@ Implemented in `runSyndicateTurn`, so every surface honours it: the A2A
 server, the CLI runner (`scripts/syndicate_chat.ts`), the worker and the
 evals.
 
+**Nested.** A `yaml_reference` to a plan-dispatch syndicate runs as it
+runs at the top, as a turn of its own on its own conversation, wherever
+it appears
+([ADR 0120](./wiki/decisions/0120-nested-dispatch-syndicates-route-as-at-the-top.md)):
+its classifier picks one of its routes, and the route's final text is
+what its caller gets: the tool's answer as a DELEGATE subagent, the turn's
+answer as a plan-dispatch route, the node's output as a workflow node. The
+classifier's JSON never reaches its caller. It runs under the turn's
+`max_steps`, deadline and cancel; its guards run once, on the answer at the
+top; its OAuth grants are stored under the root's app. An approval, an
+`ask_user` question or an OAuth consent on one of its routes, or inside a
+route's own delegation, pauses the whole turn with the path (e.g.
+`["Boss", "Team", "Ops"]` delegated, `["Team", "Ops"]` as a route), and
+the answer resumes that route without classifying again. As a workflow
+node it cannot pause on a consent request: the node fails. Its
+conversation is filed at `<app>/<caller>/<entry>` when delegated, at
+`<app>/route:<route>` as a route and at `<app>/node:<node>` as a node. A
+route that carries the entry's own name, a `map` over one, and a reference
+chain below it that reaches itself are refused by name before any model
+call.
+
 ### Workflows (`workflow:`) — the third orchestration method
 
 A syndicate that declares a `workflow:` block is a **graph**. Its agents
@@ -1302,12 +1374,15 @@ graph, under the entry's name and description, wherever it appears: as a
 DELEGATE subagent its last output is the tool's answer; as a plan-dispatch
 route it is the turn's answer, and the conversation keeps the message and
 that answer; as a node of another workflow it is the node's output. The
-graph's events are kept in the entry's own session, as for any subagent.
-As a DELEGATE subagent, an `ask_user` node or a gated agent node inside it
-pauses the whole turn, and the answer resumes the graph
-([ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md)). As a
-route or a node, a pause inside it cannot reach the turn yet, so an
-`ask_user` node or a gate there is refused by name, as is a `map` over one.
+graph's events are kept in the entry's own session, filed under the agent
+path and its kind (`<app>/route:<route>`, `<app>/node:<node>`; a session
+an earlier release filed under `<app>/<entry>` or the entry's name alone is
+still continued). Wherever it
+runs, an `ask_user` node or a gated agent node inside it pauses the whole
+turn with the path down to that node, and the answer resumes the graph
+([ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md),
+[ADR 0119](./wiki/decisions/0119-workflow-routes-and-nodes-pause-the-turn.md)).
+A `map` over one is refused by name.
 
 **Not yet.** Remote `a2a_agent_url` subagents are refused inside a
 workflow by the schema. An `ask_user` tool on a node agent is refused