melchizedek-agents 1.0.3 → 1.1.0

package/.env.example

@@ -33,8 +33,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 +248,20 @@ 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
 
 # ── Optional: Knowledge Bundle (wiki) ─────────────────────────────────────────
 # WIKI_ROOT: filesystem path of the OKF knowledge bundle the wiki tools serve.

package/CHANGELOG.md

@@ -6,6 +6,298 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 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

package/DOCUMENTATION.md

@@ -106,8 +106,8 @@ orchestrator:
   tools:
     - "google_search"             # names resolved via lib/toolRegistry.ts
   reasoning: medium               # none | low | medium | high, or { budget_tokens: 4096 }
-  generateContentConfig:
-    maxOutputTokens: 4096
+  sampling:
+    max_output_tokens: 4096
 
 subagents:
   - name: "Researcher"
@@ -136,19 +136,22 @@ Field reference:
 | `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. |
-| `generateContentConfig` | agent | Temperature, output caps. Its `thinkingConfig` and `reasoningEffort` are the older, provider-specific spelling of `reasoning`; setting either next to `reasoning` is a load error. |
-| `outputSchema` | agent | Structured-JSON contract. **Constraint:** an agent holding `outputSchema` cannot also hold transfer powers — structured output does not combine with delegation on one agent. Keep schema-holders as leaf agents (see `critic.yaml`'s header comment for the war story). |
+| `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)). |
 | `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`. |
 | `includeContents` / `outputKey` / `globalInstruction` / `disallowTransferToParent` / `disallowTransferToPeers` | agent | Passed through to the agent (spelled after ADK's `LlmAgent` fields). `includeContents: none` makes an agent see only the current message. |
 | `fallback_model` | any agent | A model, ideally on another provider, that answers when this agent's model fails provider-side (5xx, 429, a connection reset, after its own retries) before producing any output, or while that provider's circuit is open: after `MODEL_BREAKER_THRESHOLD` consecutive provider failures (default 5; 0 disables) the provider is skipped for `MODEL_BREAKER_COOLDOWN_MS` (default 30 s). A 4xx and a canceled turn are never redirected, and a stream that already produced text is never replayed elsewhere ([ADR 0044](./wiki/decisions/0044-fallback-model-and-circuit-breaker.md)). |
 | `mcp_tools` | subagent | The MCP server's tools this agent may use; any other tool the server lists is not exposed. On a dispatch route `require_approval` may name them ([ADR 0041](./wiki/decisions/0041-tool-vendors-get-least-privilege.md)). |
+| `mcp_auth` | subagent | `{ oauth2 }`: the OAuth grant the MCP server takes, the same block as an OpenAPI `auth.oauth2`. `client_credentials` sends the server's own token; `authorization_code` sends each user's own token on their own connection (the consent pause asks for it) and needs `mcp_tools` ([ADR 0112](./wiki/decisions/0112-oauth-grants-declared-beside-the-tool.md)). |
 | `mcp_server_url` | subagent | Discover this subagent's tools from a remote MCP server at load time (§3). SSRF-guarded; `ALLOW_PRIVATE_MCP=true` permits localhost for development. |
 | `openapi` | any agent | HTTP APIs as tools, each from an OpenAPI 3 spec file (§3, OpenAPI tools): `spec`, and optionally `operations` (default: the GET operations only), `auth` (from environment variables), `base_url`, `prefix`. |
 | `code_execution` | any Gemini agent | `"gemini"`: the model writes Python and Gemini runs it in Google's server-side sandbox, returning the output to the model; nothing runs on this host. For arithmetic, data and checks a model gets wrong in its head. Gemini models only ([ADR 0033](./wiki/decisions/0033-context-task-code.md)). |
 | `context` | orchestrator | Compacts a long conversation: when the last request's prompt passed `compact_after_tokens`, earlier turns become one summary (written by `summary_model`, default the agent's own) and the last `keep_recent_events` stay verbatim. The full history stays stored; only what the model reads shrinks. The orchestrator of a delegate syndicate only: a dispatch route already reads a bounded projection, a workflow node sees only its input. |
-| `mode` | workflow node | `"task"`: the agent works with its tools until it calls `finish_task`, whose arguments (matching its `outputSchema`) become the node's output. Workflow nodes only. |
+| `mode` | workflow node | `"task"`: the agent works with its tools until it calls `finish_task`, whose arguments (matching its `output.schema`) become the node's output. Workflow nodes only. |
 | `examples` | any agent | Few-shot exchanges, `[{ input, output }]` (up to 20), added to every request's instruction as a few-shot block, the one ADK's `ExampleTool` wrote (an Instruction tool, `lib/tools/examples.ts`); the model never calls it. Keeps worked examples out of the prose of `instruction`. |
 | `skills` | any agent | Agent Skills (a directory of SKILL.md folders) the agent holds the way a coding harness does: every skill's name and description is appended to its instruction at compile time; `load_skill` reads one in full with the names of its files, `load_skill_resource` reads one file. `scripts: local` adds `run_skill_script`, which runs a skill's own scripts on this machine, each after a person approves (the `require_approval` pause), with PATH, HOME, the temp directory and the locale but none of the server's keys, plus the variable names listed under `env:` (or `secret_env:` for a secret-shaped name, ADR 0086), and stdout and stderr each cut at 20,000 characters; `tools:` names registry tools a skill's `allowed-tools` may unlock once loaded. Worked example: `examples/harness.yaml`; engine: `lib/tools/skillToolset.ts` over `lib/tools/skills/`. |
 
@@ -181,8 +184,8 @@ function, and every adapter recognises it by marker
 | `generate_image` | Contract | Calls the Gemini image model directly, saves the result under `outputs/`, returns the path. A function tool because binary `inlineData` cannot survive delegation, where a subagent returns only its final text. |
 | `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. Orchestrator or plan-dispatch route only (§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. |
+| `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. |
 
 **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
@@ -221,8 +224,17 @@ without `operations`, only GET operations become tools, so anything that
 writes is exposed only by naming it, and a named operation can be listed
 under `require_approval` (as written under `operations`) so a person
 approves each call. `auth` names an environment variable, never a value
-(`bearer_env`, or `api_key` with `in: header | query` and `name`); an unset
-variable fails the compile, and so does one of the framework's own settings
+(`bearer_env`, or `api_key` with `in: header | query` and `name`), or
+declares an OAuth grant (`oauth2`: `provider`, `grant: authorization_code |
+client_credentials`, `authorization_url`, `token_url`, `client_id` or
+`client_id_env`, `client_secret_env`, `scopes`), whose token each call
+fetches: the run's user's own through the consent pause, or the server's own
+from the token endpoint ([ADR 0112](./wiki/decisions/0112-oauth-grants-declared-beside-the-tool.md)).
+`oauthClientsFor(configs)` (`melchizedek-agents/tools/oauthTools`) builds the
+consent step's clients from the same YAML, and `npm run doctor` lists every
+tool that needs a grant. The hosts a grant's token goes to must be ones the
+operator binds to its provider (`MELCHIZEDEK_OAUTH_HOSTS`, [ADR 0114](./wiki/decisions/0114-oauth-tokens-go-only-to-hosts-the-operator-binds.md));
+with no allowlist, `authorization_code` is refused. An unset variable fails the compile, and so does one of the framework's own settings
 (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`
@@ -365,7 +377,7 @@ The xAI adapter carries the deepest capability surface: `grok-4.5`
 requests pin `reasoning.effort: "medium"` (`lib/config.ts`), SSE
 streaming works end-to-end (`runConfig: { streamingMode: 'sse' }` —
 partial delta events stream, one aggregated event persists with usage),
-structured outputs ride `outputSchema` → `text.format`, and two
+structured outputs ride `output.schema` → `text.format`, and two
 xAI-only tools — `x_search` and `collections_search` (§3) — turn on
 live X search and hosted-document RAG. All verified live on grok-4.5.
 
@@ -486,7 +498,7 @@ runs as a one-agent syndicate through `runSyndicateTurn`.
 
 Reasoning/thinking: scratchpads from every provider are surfaced as
 dimmed THINKING output and kept out of session history. On Claude, any
-`reasoning:` other than `none` (or the older
+`reasoning:` other than `none` (or the deprecated
 `generateContentConfig.thinkingConfig.thinkingBudget`) enables Anthropic
 extended thinking, tools included: the signed thinking blocks ride on the
 response's parts as `providerState` and are replayed verbatim within the
@@ -787,12 +799,24 @@ without it. A message that is not an answer gets the same request back,
 without a model call. The paused call and its arguments are pinned, so an
 approval cannot run a different call.
 
-Gates are allowed on the orchestrator and on the subagents of a
-plan-dispatch syndicate, which run as the turn's own agent, and on the
-agent nodes of a workflow (§6). A delegated
-subagent runs inside a tool call, where a pause cannot reach the caller, so a
-gate there is a load error, as is any gate inside a nested `yaml_reference`
-syndicate. Only function tools from the registry can be gated, not MCP tools
+Gates are allowed on the orchestrator, on the subagents of a plan-dispatch
+syndicate, on the agent nodes of a workflow (§6), and on a delegated
+subagent, at any depth of nested delegate syndicates
+([ADR 0110](./wiki/decisions/0110-pauses-inside-delegated-subagents-reach-the-turn.md)).
+A delegated subagent's gate pauses the whole turn: the call that reached it
+stays open, the request carries `path` (the agents from the turn's own down
+to the one that asked, e.g. `["Desk", "Mailer"]`, in the data part and in
+`approval.path`), and the decision goes back down to that subagent, which
+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
+`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
 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.
@@ -819,12 +843,14 @@ call's result, and the agent resumes its own tool loop where it asked. A
 workflow's `ask_user` node (§6, Workflows) publishes the same data part and
 is answered the same way, so a client handles both alike.
 
-`ask_user` is allowed where an approval gate is: the orchestrator and the
+`ask_user` is allowed where an approval gate is: the orchestrator, the
 subagents of a plan-dispatch syndicate (a dispatch turn that answers goes
-straight back to the route that asked, without the classifier). A delegated
-subagent or a workflow node listing it is a load error. In code,
+straight back to the route that asked, without the classifier), and a
+delegated subagent, whose question carries `path` and whose answer goes back
+down to it (ADR 0110). A workflow node listing it is a load error. In code,
 `runSyndicateTurn` returns `status: 'input-required'` with `input`
-(`node`, `message`, `payload`), and the next message's text answers it.
+(`node`, `message`, `payload`, and `path` for a delegated subagent's
+question), and the next message's text answers it.
 
 #### OAuth consent for tools
 
@@ -877,6 +903,32 @@ one replica, or route the callback to the instance that paused the call. In
 code, `runSyndicateTurn({ …, toolCredentials })` returns
 `status: 'input-required'` with `consent`.
 
+**From the environment (`melchizedek-serve`).** The server binary builds the
+store and the consent step itself, with the clients taken from the grants the
+served syndicate files declare (`auth.oauth2`, `mcp_auth`; a registry row may
+name a provider they declare, never define one):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `MELCHIZEDEK_CREDENTIAL_KEY` | 32 random bytes, base64 or 64 hex (`openssl rand -base64 32`) | Seals each user's tokens. Unset: no store, and an authorization-code tool answers `unavailable`. Rows live in Postgres with `DATABASE_URL`, else in process memory |
+| `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]` |
+
+**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
+`createA2AApp({ oauthHosts: { tracker: ['api.tracker.example.com'] } })`,
+which wins. Unset, an `authorization_code` grant is refused (a user's token
+never goes to a host nobody bound) and a `client_credentials` grant is
+allowed (its secret is the operator's, as `bearer_env`'s is). Set, it is the
+whole list: every grant's provider must be on it, and its API or MCP server,
+token endpoint and authorization endpoint must be that provider's hosts. A
+syndicate that breaks the rule is refused when the server loads it to serve,
+again when its tools compile, and every call checks the host it sends a
+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.
+
 #### Limits
 
 | Setting | Default |
@@ -1056,7 +1108,7 @@ user:
 | | DELEGATE (default) | PLAN-DISPATCH (`dispatch:` present) |
 |---|---|---|
 | Subagents are | tools on the orchestrator | plain configs the server selects from |
-| Orchestrator holds | subagent tools, no `outputSchema` | an `outputSchema`, no subagent tools |
+| Orchestrator holds | subagent tools, no `output.schema` | an `output.schema`, no subagent tools |
 | Routing decision is | implicit in which tool it calls | an explicit value in code |
 | The final answer comes from | the orchestrator re-emitting the answer | **the specialist itself** |
 | LLM calls per request | classify + specialist + relay | classify + specialist |
@@ -1070,14 +1122,14 @@ orchestrator:
   model: "gemini-3.5-flash-lite"
   instruction: |
     Name exactly ONE specialist for this message. ...
-  outputSchema:                        # a leaf holding a schema — no subagent tools
-    type: "OBJECT"
-    properties:
-      route:  { type: "STRING", description: "Exact specialist name" }
-      reason: { type: "STRING", description: "≤8 plain words for the waiting user" }
-    required: ["route"]
-  generateContentConfig:
-    responseMimeType: "application/json"
+  output:
+    mime: "application/json"
+    schema:                            # the router's schema; dispatch gives it no subagent tools
+      type: "OBJECT"
+      properties:
+        route:  { type: "STRING", description: "Exact specialist name" }
+        reason: { type: "STRING", description: "≤8 plain words for the waiting user" }
+      required: ["route"]
 ```
 
 **Why it exists.** In DELEGATE mode the orchestrator receives the
@@ -1090,13 +1142,18 @@ Plan-dispatch has no relay turn to fail, and the classifier's output
 shrinks from a whole relayed answer to ~15 tokens of JSON.
 
 **Why the classifier is tool-less.** An agent that holds an
-`outputSchema` answers with that JSON and nothing else, so the schema sits
-on a leaf that delegates nothing (see `config/agents/examples/critic.yaml`,
-whose header also tells how an orchestrator holding both deadlocked on
-ADK before 1.0.0).
-That constraint shapes the method: the classifier is a leaf, and the
+`output.schema` ends its turn on that JSON. The router's JSON names a
+route for code to run, so the router holds no subagent tools, and the
 hand-off happens in code, where it can be logged, traced, and streamed
-to the user as progress.
+to the user as progress. This is a choice of method, not a limit of the
+engine: an orchestrator may hold an `output.schema` beside its subagents,
+delegate, and answer in the schema itself
+([ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md));
+under ADK, before 1.0.0, an orchestrator holding both deadlocked (see
+`config/agents/examples/critic.yaml`'s header). Choose plan-dispatch when
+the answer is the specialist's, and a schema on the orchestrator when the
+answer is its own structured judgment of what its team returned
+(`config/agents/examples/structured_critic.yaml`).
 
 **Sessions.** Every *route* runs in the shared `<contextId>` session, so
 one transcript accumulates across routes and long-term memory ingests
@@ -1190,7 +1247,7 @@ name is an agent or a declared node; a list of names fans out (after one
 node) or fans in (before one node); a map `{ <route>: <node or nodes>,
 default: <node> }` ends a chain and routes on the output of the node
 before it — the `route_key` property of a JSON output (an agent with an
-`outputSchema`), else the trimmed text — with `default` catching what no
+`output.schema`), else the trimmed text — with `default` catching what no
 key matched. Every node receives the previous node's output as its
 message; a join hands on `{ <predecessor>: <output>, … }`.
 
@@ -1246,8 +1303,11 @@ 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.
-A nested workflow may not have an `ask_user` node (a pause inside it
-cannot reach the caller); it is refused by name, as is a `map` over one.
+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.
 
 **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

package/README.md

@@ -173,6 +173,7 @@ Configurations live in `config/agents/examples/` and each demonstrates a differe
 | `tutor.yaml` | Single local agent (Ollama); the anatomy of an instruction block | [1.03 · Agent Design](https://lyceumagents.com/curriculum/agent-design/) |
 | `council.yaml` | Advocate/skeptic council weighed by an orchestrator (local) | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
 | `critic.yaml` | Drafter → Critic loop that re-drafts until a parsed confidence score clears the bar | [1.04 · Testing & Refinement](https://lyceumagents.com/curriculum/testing-and-refinement/) |
+| `structured_critic.yaml` | The critic as one agent: it delegates to a Drafter, then answers in its own JSON schema (Claude) | — |
 | `delegation.yaml` | Intent routing to specialists via agent descriptions | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
 | `hierarchical.yaml` | Goal decomposition into sequential research and writing stages, then a checked merge | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
 | `style_council.yaml` | Three stylists with identical knowledge and different voices, behind one router | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |

package/config/agents/README.md

@@ -17,8 +17,8 @@ and it is loadable by filename everywhere (`npm run chat:syndicate --
 
 Everything under `examples/` is a **starter pack**: working, tested
 syndicates that demonstrate the engine's patterns (synthesis, delegation,
-critic loops, hierarchies, MCP tools, local open-weight models, the wiki
-gardeners). They are teaching material, not product — copy them, gut them,
+critic loops, an orchestrator answering in its own JSON schema,
+hierarchies, MCP tools, local open-weight models, the wiki gardeners). They are teaching material, not product — copy them, gut them,
 delete the whole directory; the engine runs fine without them.
 
 ## `templates/` — the production templates