melchizedek-agents 0.16.2 → 0.17.0

package/.env.example

@@ -25,6 +25,13 @@ GOOGLE_GENAI_API_KEY=
 # turn it on for local development — e.g. the librarian demo (npm run mcp:demo).
 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.
+# ALLOW_PRIVATE_OPENAPI=false
+
 # ── Optional: Anthropic / Claude ──────────────────────────────────────────────
 # Required only when using claude-* model identifiers in syndicate YAML configs.
 # Get your key at: https://console.anthropic.com
@@ -54,6 +61,16 @@ OPENAI_API_KEY=
 # Get your key at: https://console.x.ai
 XAI_API_KEY=
 
+# ── Optional: Moonshot AI / Kimi ─────────────────────────────────────────────
+# Required only when using kimi-* model identifiers in YAML (kimi-k3 is the
+# flagship; kimi-k2.6 the cheaper tier; kimi-k2.7-code[-highspeed] for code).
+# Get your key at: https://platform.moonshot.ai (the .cn console serves
+# mainland China). Without it, MODEL_GATEWAY serves kimi-* ids as
+# moonshotai/kimi-k3 and friends. web_search is never native on Kimi
+# (Moonshot's built-in search retires 2026-10-20); use web_extract.
+MOONSHOT_API_KEY=
+# MOONSHOT_BASE_URL=   # a proxy speaking the same chat-completions dialect
+
 # XAI_COLLECTION_IDS: comma-separated xAI Collection ids searched by the
 # `collections_search` tool (grok-* agents only). Create collections and
 # upload documents at console.x.ai. Declared with no ids set, the tool is

package/AGENT_SETUP.md

@@ -70,7 +70,8 @@ After the agent reports back:
    of them — set only what you'll declare in YAML:
    `ANTHROPIC_API_KEY` for `claude-*` (https://console.anthropic.com),
    `OPENAI_API_KEY` for `gpt-*` (https://platform.openai.com/api-keys),
-   `XAI_API_KEY` for `grok-*` (https://console.x.ai). Not sure which
+   `XAI_API_KEY` for `grok-*` (https://console.x.ai),
+   `MOONSHOT_API_KEY` for `kimi-*` (https://platform.moonshot.ai). Not sure which
    you need? `npm run doctor` reads every syndicate and prints what is
    ready, what is blocked, and which variable unlocks what — read-only,
    no key value shown. Verify the whole multi-provider surface live with

package/CHANGELOG.md

@@ -4,6 +4,148 @@ Consumers of the package read this file; it records changes to the
 **published API surface** (the exports map in `package.json`, the bins,
 the starter pack and the templates), not the repo's full history.
 
+## 0.17.0 — 2026-10-06
+
+### Read before upgrading
+
+- **Run `npx melchizedek-db apply`.** Migration `0011_erase_expired` ships
+  with this version, and the server refuses to start against a database
+  behind the shipped migrations.
+- **A public Supabase deployment on `DATABASE_URL` must be hardened.** The
+  boot-time RLS check now runs on that path; `db/hardening.sql` (which
+  `melchizedek-db apply` runs) satisfies it, `ALLOW_UNHARDENED_DB=true`
+  opts out.
+- **Self-correction is on by default.** Retries count against `max_steps`
+  and can raise spend; `retries: { model_errors: 0, tool_errors: 0 }`
+  restores the previous behaviour.
+
+### Changes
+
+- **Behaviour change: the hardening check runs on the `DATABASE_URL` path.**
+  The boot-time RLS check ran only on the deprecated supabase-js path, so a
+  deployment that followed the recommended setup was never checked, and
+  "fatal on public deployments without it" did not hold. `postgresStorage`
+  now supplies `rlsHardening()` and the server applies the same rules
+  (`lib/storage/rlsStatus.ts`): with `PUBLIC_URL` set, a Supabase database
+  whose `public` tables lack RLS stops the server (set
+  `ALLOW_UNHARDENED_DB=true` to accept the risk). A database with no `anon`
+  or `authenticated` role, or with the tables in a private schema, passes.
+  `createA2AApp`'s `storage` option accepts `rlsHardening` for custom storage.
+- **Fix: OpenAPI tools no longer follow redirects past the SSRF guard.**
+  ADK's REST tool calls `fetch`, which follows redirects, and the guard
+  checked only the configured server: an allowed API with an open redirect
+  could send a call to the cloud metadata service, and an `api_key` header
+  went with it. A call now follows redirects one hop at a time
+  (`lib/net/redirects.ts`): same-origin hops get the server's own check,
+  cross-origin hops the full guard (even with `ALLOW_PRIVATE_OPENAPI`) and
+  only content-negotiation headers. A refused hop returns an error to the
+  model. Nothing changes for a fetch made outside an OpenAPI tool call.
+- **Fix: `DELETE /memory` erases expired conversations.** A namespace erase
+  (the default) found conversations through their live session rows, so once
+  a session expired after seven idle days its ledger turns, spans, payloads
+  and A2A tasks survived the erase while the response reported success.
+  Migration `0011_erase_expired` replaces `melchizedek_erase_scope`: a
+  namespace erase now keeps a turn or task only when its conversation is
+  still live in another namespace. Run `npx melchizedek-db apply`; the server
+  refuses to start against a database behind the shipped migrations.
+- **Moonshot AI (Kimi) is a provider.** `kimi-*` model ids route to a new
+  direct adapter (`lib/models/kimiLlm.ts`, chat completions against
+  `api.moonshot.ai`), funded by `MOONSHOT_API_KEY` (`MOONSHOT_BASE_URL` for a
+  proxy). Tool calling, delegation, strict structured output, streaming,
+  images and `reasoning_content` work; native `web_search` is dropped with a
+  warning (Moonshot's model-side search retires 2026-10-20), and thinking is
+  not carried across a tool loop (K3 re-reasons each step; both stated in
+  the capability matrix). `kimi-k3` takes `reasoning_effort` (pinned `high`,
+  `DEFAULT_KIMI_REASONING_EFFORT`); K2.x ids take a thinking switch. With no
+  direct key the gateway serves the ids as `moonshotai/…`. The doctor,
+  `.env.example`, the schema comments and the docs know the provider;
+  `model_zoo.yaml` gains a sixth agent, `kimi` on `kimi-k3` at low effort,
+  and the Zookeeper names six providers. Cost note: `kimi-k3` is priced
+  like Claude Sonnet 4.6 ($3 / $15, thinking billed as output), so
+  `kimi-k2.6` is the budget tier and the gateway the cheap route to K3.
+  One plain turn verified live on 2026-10-03; tool loops were not.
+- **The doctor's providers line names each provider's own key.** It probed
+  every provider past the fourth with a `grok-` id, so Moonshot was reported
+  as missing `XAI_API_KEY`.
+- **Behaviour change: self-correction is on by default.** Every turn now runs
+  ADK's reflect-and-retry plugins. A model reply ADK marks malformed
+  (`MALFORMED_FUNCTION_CALL`) is retried up to twice with guidance instead of
+  failing the turn; a tool that throws is answered with structured reflection
+  guidance and retried at most three times. Every retry counts against
+  `max_steps`. Set `retries: { model_errors: 0, tool_errors: 0 }` at the root
+  of a syndicate to restore the previous behaviour. ADR 0034.
+- **`url_context` and `examples:`.** `url_context` lets a Gemini agent read
+  the pages at URLs in the conversation, server-side; on other providers it is
+  a no-op the doctor reports as dropped. An agent's `examples: [{ input,
+  output }]` adds few-shot exchanges to every request (ADK's `ExampleTool`).
+- **Three agent keys from ADK: `code_execution`, `context`, `mode`.**
+  `code_execution: gemini` lets a Gemini agent write and run Python in
+  Gemini's server-side sandbox (nothing runs on the host). `context:
+  { compact_after_tokens, keep_recent_events?, summary_model? }` on a delegate
+  orchestrator summarizes earlier turns once a prompt passes the threshold,
+  keeping the recent ones verbatim and the full history stored. `mode: task`
+  on a workflow node makes its output the arguments of its `finish_task`
+  call. The schema places each where it means something. ADR 0033.
+- **`openapi:`: any HTTP API as an agent's tools, from its spec.** An agent
+  lists OpenAPI 3 spec files (relative to the syndicate file); every operation
+  becomes a tool named from its `operationId`, its parameters the arguments,
+  its summary the description. Read-only by default (GET operations only,
+  unless `operations` names others); a named operation can be listed under
+  `require_approval`. Credentials come from environment variables
+  (`auth.bearer_env`, `auth.api_key`), never YAML, and are never stored in
+  session state. Every server passes the SSRF guard (literal rules at
+  compile, DNS before each call; `ALLOW_PRIVATE_OPENAPI=true` for local
+  development); results are capped at 20,000 characters. On ADK's
+  `OpenAPIToolset`. Worked example: `config/agents/examples/weather.yaml`
+  (`npm run syndicate:weather`), with two keyless Open-Meteo specs. ADR 0032.
+- **`ask_user`: an agent asks the person and waits.** A registry tool,
+  `ask_user(question, options?)`, on the orchestrator or a plan-dispatch
+  route. Called, it ends the turn `input-required` with `result.input`
+  (`node`, `message`, `payload.options`); the next plain-text message on the
+  conversation becomes the call's result and the agent resumes its own tool
+  loop (a dispatch turn goes straight back to the route that asked). Over A2A
+  the task carries an `input_request` data part — the same one a workflow's
+  `ask_user` node publishes. A delegated subagent or a workflow node listing
+  it is a load error. ADR 0031.
+- **Workflows: the `workflow:` block, the third orchestration method.** A
+  syndicate may be a graph: its agents are the nodes, `edges` says what runs
+  after what and on which route (a map after a node routes on the `route_key`
+  of its JSON output, else its text, with `default`), and `nodes` declares
+  what is not an agent — `join` (fan-in), `map` (one run per list item,
+  concurrently), `tool` (a registry tool as a node), `ask_user` (a pause: the
+  turn ends `input-required` with the question, the next message answers,
+  and the node outputs `{ reply, input }`). Any node may carry `retry` and
+  `timeout`. Every node receives the previous node's output as its message
+  and sees nothing else of the conversation unless its YAML says so. Runs on
+  ADK's `Workflow`; `runSyndicateTurn` gains `status: 'input-required'` with
+  `input` (the A2A server publishes an `input_request` data part;
+  `melchizedek-chat` prints the question and takes the next line);
+  `compileWorkflow` and `isWorkflowSyndicate` are exported. Not yet inside a
+  workflow: approval gates, skill scripts, remote subagents. Worked example:
+  `config/agents/examples/pipeline.yaml` (`npm run syndicate:pipeline`);
+  ADR 0030.
+- **Agent Skills in a syndicate: the `skills:` agent key and the Harness.**
+  An agent may declare `skills: { dir, scripts?, tools? }`. Every skill's
+  frontmatter (name, description) is appended to the agent's instruction at
+  compile time, so no turn is spent discovering skills; `load_skill` reads one
+  SKILL.md in full with the names of the files it ships, and
+  `load_skill_resource` reads one file (`references/`, `assets/`, `scripts/`,
+  the open standard's layout). A skill's `allowed-tools` frontmatter unlocks
+  the registry tools the YAML lists under `skills.tools`, once that skill is
+  loaded. With `scripts: local`, `run_skill_script` runs a skill's own scripts
+  on the host, each run only after a person approves it through the same
+  pause as `require_approval` (A2A `input-required`; `melchizedek-chat` now
+  asks `[y/N]`); the model's own code never executes. Built on ADK's
+  `SkillToolset` (`lib/tools/skillToolset.ts`). `config/agents/examples/harness.yaml`
+  is the specimen: a generic agent that works from whatever shelf of skills
+  `--bind skills_dir=…` points it at (default: this package's own suite).
+- **The suite's files move to the standard `assets/` directory.**
+  `melchizedek-author` ships `assets/minimal.yaml` (was `templates/minimal.yaml`)
+  and `melchizedek-scribe` ships `assets/brief.md` (was `templates/brief.md`),
+  so a harness, this one or any other, can read them as skill resources. A
+  skill installed by an earlier release keeps its old path until it is
+  reinstalled with `--force`.
+
 ## 0.16.2 — 2026-10-02
 
 - **`OTEL_EXPORT_CONTENT=off` also drops library content attributes.** In

package/DOCUMENTATION.md

@@ -98,6 +98,8 @@ Field reference:
 | `memory_extraction_model` | root | The model that distils this syndicate's turns into memory records (long-term only); any model id. Default: the deployment's `MEMORY_EXTRACTION_MODEL`. |
 | `memory_retention_days` | root | Days a fact in this syndicate's namespace is kept; the server deletes older facts when it loads the syndicate and daily after. Requires `memory_namespace` (never applied to the shared default namespace). |
 | `dispatch` | root | Switches the syndicate from DELEGATE to PLAN-DISPATCH routing (§6). `default_route` (required) names the fail-static subagent; `route_key` / `reason_key` name the router's JSON properties (defaults `route` / `reason`). Honoured by every surface (the CLI, the server, the worker, evals). |
+| `workflow` | root | Switches the syndicate to a WORKFLOW (§6): a graph whose nodes are its agents plus declared `join`, `map`, `tool` and `ask_user` nodes, and whose `edges` say what runs after what and on which route. The orchestrator is a node like any other; nothing delegates. Cannot be combined with `dispatch`. Contract: `lib/workflow.ts`; worked example: `examples/pipeline.yaml`. |
+| `retries` | root | Self-correction, on by default ([ADR 0034](./wiki/decisions/0034-self-correction.md)): `model_errors` (default 2) retries a model reply ADK marks malformed (`MALFORMED_FUNCTION_CALL`) instead of failing the turn; `tool_errors` (default 3) answers a tool that threw with structured reflection guidance and caps its retries. `0` turns either off. Every retry is a model call under `max_steps`. |
 | `guards` | root | Optional list of post-answer guard NAMES (`lib/guards/index.ts`). Each runs after the answering turn and before the reply publishes, receiving the final text plus every tool-result text of that turn, and rewrites in place rather than re-asking the model; its notes land in the `[STATUS]` stream. Guards declared by a syndicate reached through `yaml_reference:` count too — the server resolves the union via `collectGuards()`. Resolved by name, never by module path, so adding one is a deliberate act in code; **the published registry ships one, `science`** (citation checks for `research.yaml`); `registerGuard()` adds your own from code, and an unregistered name is warned about and skipped. |
 | `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…"). |
@@ -109,6 +111,12 @@ Field reference:
 | `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 ADK's LlmAgent. `includeContents: none` makes an agent see only the current message. |
 | `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. |
+| `examples` | any agent | Few-shot exchanges, `[{ input, output }]` (up to 20), added to every request's instruction by ADK's `ExampleTool`; 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); `tools:` names registry tools a skill's `allowed-tools` may unlock once loaded. Worked example: `examples/harness.yaml`; engine: `lib/tools/skillToolset.ts`. |
 
 Validation happens at load: missing names, legacy option blocks, and
 malformed agents fail with pointed errors before any model is called.
@@ -122,16 +130,18 @@ instance:
 
 | Name | Kind | Does |
 |---|---|---|
-| `web_search` | Provider-agnostic | Live web search via the agent model's NATIVE search: Gemini grounding, Anthropic `web_search` server tool, OpenAI Responses `web_search`, xAI Agent Tools `web_search`. On local `ollama/*` models the tool is omitted with a one-time warning (keyless stays keyless). On grok-* agents, optional server-side domain filters via `XAI_WEB_SEARCH_ALLOWED_DOMAINS` / `_EXCLUDED_DOMAINS` in `.env` (max 5, mutually exclusive; xAI accepts no date bounds — those are `x_search`-only). Prefer this in new YAMLs. |
+| `web_search` | Provider-agnostic | Live web search via the agent model's NATIVE search: Gemini grounding, Anthropic `web_search` server tool, OpenAI Responses `web_search`, xAI Agent Tools `web_search`. On local `ollama/*` models, and on `kimi-*` (Moonshot's model-side search retires 2026-10-20; its successor is a REST API, not a request field), the tool is omitted with a one-time warning (keyless stays keyless). On grok-* agents, optional server-side domain filters via `XAI_WEB_SEARCH_ALLOWED_DOMAINS` / `_EXCLUDED_DOMAINS` in `.env` (max 5, mutually exclusive; xAI accepts no date bounds — those are `x_search`-only). Prefer this in new YAMLs. |
 | `web_extract` | FunctionTool | Deterministic page reading: fetches 1–5 agent-chosen URLs and returns clean page text (no LLM summarization). Keyless — works on every provider including local `ollama/*`. Per-page char budget (default 15k, `WEB_EXTRACT_CHAR_LIMIT`); long pages return a head+tail window with an `offset` continuation call served from a 15-minute cache. SSRF-guarded (http(s) only, private/link-local hosts refused, redirects re-checked). Block pages (bot checks, paywall stubs, JS shells) are detected code-side and returned as labeled `Error:` blocks, never as content. Pair with `web_search`: search to find, extract to read past the headline. |
 | `x_search` | xAI-only | Live search over X (Twitter) posts via xAI Agent Tools. Self-gates to `grok-*` agents; a silent no-op on every other provider, so mixed-provider YAMLs stay safe. Optional server-side constraints in `.env`: `XAI_X_SEARCH_FROM_DATE`/`_TO_DATE` (inclusive `YYYY-MM-DD`) and `_ALLOWED_HANDLES`/`_EXCLUDED_HANDLES` (max 20, mutually exclusive — allowlist wins). |
 | `collections_search` | xAI-only | Semantic search over xAI **Collections** — hosted document stores (PDFs/text/CSVs) uploaded at console.x.ai — server-side RAG with `collections://…` citations. Which collections: `XAI_COLLECTION_IDS` in `.env` (optional `XAI_COLLECTIONS_MAX_RESULTS`). Declared with no ids → omitted with a warning; non-xAI providers → silent no-op. |
+| `url_context` | Gemini built-in | Gemini reads the pages at URLs in the conversation, server-side (Google fetches them, not this host). On any other provider it is a no-op the doctor reports as dropped; use `web_extract` there. |
 | `google_search` | ADK built-in | Live web search — Gemini agents only (legacy alias; use `web_search`). |
 | `preload_memory` | ADK built-in | Silently injects similarity-matched facts into every request (ambient recall). |
 | `load_memory` | ADK built-in | Explicit tool call to search the fact store (deliberate recall). |
 | `generate_image` | FunctionTool | Calls the Gemini image model directly, saves the result under `outputs/`, returns the path. A FunctionTool because binary `inlineData` cannot survive the AgentTool text boundary. |
 | `inspect_image` | FunctionTool | **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` | FunctionTool | 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` | LongRunningFunctionTool | 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` | FunctionTool | 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. |
 
 **MCP tools** are the exception to the registry: a subagent with
@@ -147,12 +157,46 @@ loopback/private hosts unless `ALLOW_PRIVATE_MCP=true` (SSRF guard);
 treat any remote MCP server as an untrusted tool vendor whose results
 are data, never instructions.
 
+**OpenAPI tools** turn any HTTP API with an OpenAPI 3 spec into an
+agent's tools, with no tool code (`lib/tools/openapiTools.ts`, on ADK's
+`OpenAPIToolset`; [ADR 0032](./wiki/decisions/0032-openapi-tools.md)):
+
+```yaml
+orchestrator:
+  name: Forecaster
+  openapi:
+    - spec: "specs/open-meteo-forecast.json"     # relative to this YAML file
+      operations: [getForecast]                  # omitted: every GET operation
+      auth: { api_key: { env: "WEATHER_KEY", in: "header", name: "X-Api-Key" } }
+      # base_url: overrides servers[0].url · prefix: keeps two APIs apart
+```
+
+One tool per operation, named from its `operationId` in snake_case
+(`getForecast` → `get_forecast`; no `operationId`: path and method), with
+the parameters and request body as its arguments and the operation's
+`summary` as the description the model reads. Exposure is deliberate:
+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 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
+local development. A response over 20,000 characters is cut and says so; a
+network failure comes back to the model as an error. Specs are files, never
+URLs: save the spec beside the YAML and review it like code (trim it to the
+operations the agent needs, and write each `summary` for the model). Worked
+example: `config/agents/examples/weather.yaml`, two keyless Open-Meteo specs
+in `examples/specs/`.
+
 > **Schema dialects, handled for you.** The factory emits Gemini-style
 > UPPERCASE schema types (`'OBJECT'`, `'STRING'`, …) because the ADK is
 > Gemini-native; every non-Gemini adapter normalizes them back to
 > standard lowercase JSON-Schema at request-build time
 > (`lib/models/schemaNormalize.ts`). MCP tools therefore work on any
-> provider's agents — Gemini, Claude, GPT, or Grok.
+> provider's agents — Gemini, Claude, GPT, Grok, or Kimi.
 
 ## 4. Sessions & long-term memory
 
@@ -260,6 +304,7 @@ accordingly — model optionality is a single YAML line per agent:
 | `claude-*` | Anthropic | `lib/models/claudeLlm.ts` | `ANTHROPIC_API_KEY` | ✅ server tool |
 | `gpt-*`, o-series | OpenAI | `lib/models/gptLlm.ts` (Responses API) | `OPENAI_API_KEY` | ✅ web_search tool |
 | `grok-*` | xAI | `lib/models/grokLlm.ts` (Responses API) | `XAI_API_KEY` | ✅ Agent Tools search |
+| `kimi-*` | Moonshot AI (Kimi) | `lib/models/kimiLlm.ts` (chat completions) | `MOONSHOT_API_KEY` | ⚠ omitted + warning |
 | `ollama/*` | Local Ollama | `lib/models/ollamaLlm.ts` | none | ⚠ omitted + warning |
 | *any cloud id whose direct key is absent* | the id's own provider, via a gateway | `lib/models/gatewayLlm.ts` (chat completions) | `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` | ⚠ omitted + reported |
 
@@ -271,6 +316,45 @@ structured outputs ride `outputSchema` → `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.
 
+**Moonshot AI (Kimi).** `kimi-*` ids route to `lib/models/kimiLlm.ts`, a
+subclass of the chat-completions base, against `https://api.moonshot.ai/v1`
+(`MOONSHOT_BASE_URL` for a proxy). Get a key at platform.moonshot.ai; the
+`.cn` console serves mainland China. The family (USD per 1M tokens, October
+2026): `kimi-k3`, the flagship — 2.8T-parameter open-weight MoE, 1M context,
+vision, always-on thinking, $3 in / $0.30 cache hit / $15 out; `kimi-k2.6`,
+the cheaper general tier (256K, vision, thinking switchable, $0.95 / $4);
+`kimi-k2.7-code` and `kimi-k2.7-code-highspeed` (256K, coding, thinking
+cannot be turned off; the highspeed variant streams at ~180 tokens/s for
+twice the price). There is no small or "flash" K3. On price, K3 is a mid-tier
+closed model, not a bargain: Claude Sonnet 4.6's rate, and Claude Sonnet 5.5
+($2 / $10) undercuts it per token while leading it on the coding boards;
+thinking is always on and billed as output, which is why the adapter pins
+effort below Moonshot's `max`. Choose K3 for the strongest open weights
+(self-hostable) and the flat-rate 1M context; choose `kimi-k2.6` for cost;
+or serve K3 through `MODEL_GATEWAY` (OpenRouter's endpoints run from about
+$0.88 to $3.45 per 1M input, the cheap ones quantized). What works: tool calling
+and delegation, strict `json_schema` structured output (K3 and K2.7 Code
+document it; K2.6 is unstable on `$ref`/`oneOf`), SSE streaming, images as
+base64 (Moonshot takes no public image URLs), MCP tools (they are function
+tools to the model), `reasoning_content` surfaced as THINKING. Reasoning:
+K3 takes a top-level `reasoning_effort` (`low` | `high` | `max`); the adapter
+pins `DEFAULT_KIMI_REASONING_EFFORT` (`high`, `lib/config.ts`) unless
+`generateContentConfig.reasoningEffort` says otherwise, and maps `none` to
+`low` because K3 cannot stop thinking. K2.x models take a `thinking:
+{ type }` switch instead: `reasoningEffort: "none"` or `thinkingBudget: 0`
+sends `disabled`, and any effort value is dropped from the body. What does
+not: native `web_search` (dropped with a warning; `web_extract` works, and
+Moonshot's standalone `POST /v1/tools/search`, billed per call, could back
+a client-side tool), and thinking carried across a tool loop (Moonshot asks
+for K3's `reasoning_content` back on the assistant message; this adapter
+keeps scratchpads out of history, so K3 re-reasons each step). K3's open
+weights mean the same id is served by OpenRouter, Together, Fireworks and
+Vercel AI Gateway; with no direct key, `MODEL_GATEWAY` maps it to
+`moonshotai/kimi-k3`. The row in the capability matrix is asserted against
+the request body the adapter sends; one plain turn was verified live on
+2026-10-03 (`npm run demo:models`, kimi-k3 at low effort, 17.9 s), tool
+loops and search were not.
+
 **Which keys do I need?** `npm run doctor` (the `melchizedek-doctor` bin)
 reads every syndicate YAML, resolves each agent's model under your `.env`,
 and prints one table — agent, model, provider, which declared server-side
@@ -340,7 +424,7 @@ line each. `config/agents/examples/claude.yaml` is the minimal Claude example;
 provider, and `npm run demo:models` proves the whole surface: one
 prompt to every available provider, printing input, thinking (qwen3
 `<think>` blocks, Claude extended thinking, GPT reasoning summaries,
-Grok reasoning), output, and a per-request token/latency trace; add
+Grok reasoning, Kimi reasoning_content), output, and a per-request token/latency trace; add
 `-- --search` to watch four native web searches plus the local
 omission. Providers without keys are skipped, never fatal.
 
@@ -415,7 +499,7 @@ options. `demo/a2a_demo.mjs` is a complete client.
 | `POST /a2a/jsonrpc`, `/a2a/rest` | bearer | the default syndicate |
 | `GET /<agentId>/.well-known/agent-card.json` | bearer | another syndicate's card; its URLs point at `/<agentId>/a2a/...` |
 | `POST /<agentId>/a2a/jsonrpc`, `/<agentId>/a2a/rest` | bearer | another syndicate (`A2A_SERVED_AGENTS` restricts which) |
-| `DELETE /memory` | bearer | erase everything stored for the calling scope: facts, sessions (with subagent rows) and ledger rows, with per-store counts; `?all=1` covers every memory namespace |
+| `DELETE /memory` | bearer | erase everything stored for the calling scope: facts, sessions (with subagent rows), ledger rows and A2A tasks, including conversations whose sessions have expired, with per-store counts; `?all=1` covers every memory namespace |
 
 "bearer" means the credential `A2A_AUTH` asks for (below); with no
 `A2A_SERVER_SECRET` and no authenticator the server binds `127.0.0.1` only.
@@ -533,6 +617,8 @@ JSON); `file` parts are refused.
 
 #### Approval gates (`require_approval`)
 
+A skill script run (`skills.scripts: local`) pauses the same way, without being listed: every `run_skill_script` call waits for the person's answer.
+
 A tool can run only after a person approves the exact call
 ([ADR 0028](./wiki/decisions/0028-approval-gates.md)). The agent lists it:
 
@@ -564,6 +650,35 @@ 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.
 
+#### Questions (`ask_user`)
+
+An agent can ask the person something mid-turn and wait for the answer
+(`lib/runtime/questions.ts`, [ADR 0031](./wiki/decisions/0031-ask-user.md)).
+It lists the tool:
+
+```yaml
+orchestrator:
+  name: Desk
+  tools: [ask_user]   # ask_user(question, options?)
+```
+
+When the model calls `ask_user`, the turn ends `input-required`, final. The
+status message is the question ("Desk asks: Which account? (personal /
+work)") with a data part
+`{ type: 'input_request', interrupt_id, node, message, payload }`, where
+`payload.options` lists the choices when the agent gave some. The caller's
+next message on the same conversation is the answer: its text becomes the
+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
+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,
+`runSyndicateTurn` returns `status: 'input-required'` with `input`
+(`node`, `message`, `payload`), and the next message's text answers it.
+
 #### Limits
 
 | Setting | Default |
@@ -634,6 +749,49 @@ Set `PUBLIC_URL`, `A2A_SERVER_SECRET` and the provider keys from your
 secret manager; give the orchestrator's stop timeout at least
 `A2A_SHUTDOWN_GRACE_MS`.
 
+#### Backups
+
+Everything durable is in the one Postgres you point the server at:
+conversations (`adk_sessions`, `adk_session_events`), long-term memory
+(`adk_memory_facts`), the telemetry ledger, the agent registry and its
+versions, A2A tasks, the task tools' lists and the budget counters. The
+engine takes no backups of it; back it up as you would any production
+database, with your provider's scheduled backups or point-in-time recovery
+(RDS and Cloud SQL automated backups; on Supabase, a paid plan, since the
+Free plan has none).
+
+What a backup protects is the history. The rest can be rebuilt: the schema
+with `npx melchizedek-db apply`, and registry agents by republishing their
+YAML files. Without a backup, lost conversations, memory and ledger rows
+stay lost.
+
+A logical backup works on any provider and is worth having beside its
+snapshots. Use a `pg_dump` at least as new as the server, and the
+schema the tables live in (`public`, or `MELCHIZEDEK_DB_SCHEMA`):
+
+```bash
+pg_dump --schema=public --no-owner --no-privileges -Fc -f melch.dump "$DATABASE_URL"
+# restore into a new database that has pgvector:
+psql "$TARGET_URL" -c 'CREATE EXTENSION IF NOT EXISTS vector'
+pg_restore --no-owner --no-privileges -d "$TARGET_URL" melch.dump
+npx melchizedek-db status    # with DATABASE_URL=$TARGET_URL: schema version and counts
+```
+
+Test the restore, not just the dump: restore into a scratch database and
+compare row counts per table with the source. Two things a backup changes:
+
+- **Erasure.** `DELETE /memory` removes a scope from the live database, not
+  from backups taken before it. Keep backup retention as short as your
+  recovery needs allow. After a restore, re-run any erasures made since the
+  backup was taken. The server logs each one with its scope (`Erasure for
+  scope …`); keep those lines for as long as you keep backups, since a
+  platform's log retention is usually shorter. The same holds for the
+  telemetry dead-letter spool (`outputs/telemetry-deadletter.ndjson`), which
+  holds ledger rows only while the database was unreachable: replay it
+  (`npm run telemetry:replay`) before honouring an erasure, then delete it.
+- **Secrets.** A dump holds every conversation in clear text. Encrypt it at
+  rest and give it the same access rules as the database.
+
 #### The agent registry
 
 A file is the default home of a syndicate. The registry is for a definition
@@ -793,6 +951,74 @@ Implemented in `scripts/a2a_server.ts`; like `yaml_reference`, it is
 A2A-only — the CLI runner (`scripts/syndicate_chat.ts`) still compiles
 every syndicate in DELEGATE mode.
 
+### Workflows (`workflow:`) — the third orchestration method
+
+A syndicate that declares a `workflow:` block is a **graph**. Its agents
+are the nodes; `edges` says what runs after what, and on which route;
+nothing delegates and nothing classifies. It is for the shape the other
+two methods cannot express: run these two at once, join what they
+produce, edit it, ask the person, then publish.
+
+```yaml
+workflow:
+  edges:
+    - [START, Planner, { article: [Writer, Checker], default: Answerer }]
+    - [[Writer, Checker], Both, Editor, Confirm, Publisher]
+  nodes:
+    Planner: { route_key: "kind" }                 # an agent: modifiers only
+    Both:    { join: true }                        # waits for every predecessor
+    Editor:  { retry: { max_attempts: 2 } }
+    Confirm: { ask_user: "Publish this draft? Reply yes, or say what to change." }
+```
+
+**Edges.** Each entry is a chain. `START` opens at least one chain. A
+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
+key matched. Every node receives the previous node's output as its
+message; a join hands on `{ <predecessor>: <output>, … }`.
+
+**Nodes.** `workflow.nodes` declares the nodes that are not agents, each
+exactly one kind: `join: true`; `map: <Agent>` (runs the agent once per
+item of a list input, concurrently, `max_parallel` at a time, and outputs
+the list of results); `tool: <registry name>` (runs the tool with the
+node input as its arguments); `ask_user: "<question>"` (below). An entry
+named after an agent carries modifiers only: `route_key`, `retry`
+(`max_attempts`, `initial_delay`, `max_delay`, `backoff_factor`, in
+seconds) and `timeout` (seconds), which any node may carry.
+
+**The pause.** An `ask_user` node ends the turn `input-required`
+(`result.input`: the node, the question, and what it was asked about).
+The next message on the conversation is the answer: the node's output
+becomes `{ "reply": <the answer>, "input": <what it received> }` and the
+graph resumes where it waited. `melchizedek-chat` prints the question
+and takes the next line; the A2A server ends the task `input-required`
+with a data part `{ type: 'input_request', interrupt_id, node, message,
+payload, schema }`, and the client's next message on the same
+conversation resumes it. A later message after the graph has finished
+starts it again from `START`.
+
+**What a node sees.** Unless its YAML sets `includeContents`, a node
+agent sees only its input — not the conversation, not the other nodes —
+which is what makes a graph legible: each agent's input is one value a
+person can read in the trace. Every node runs in the shared session, so
+`memory_system: long-term` would ingest node inputs as user turns;
+`internal-only` is the sensible default for a workflow.
+
+**Failure.** A node's error is not the turn's: a node with `retry` tries
+again (the attempt is recorded in `answer.nodeErrors`), and a node that
+gives up fails the turn with `NODE_FAILED` naming it. `max_steps` and
+the deadline cap the whole graph as they cap any turn.
+
+**Not yet.** Approval gates (`require_approval`, `skills.scripts: local`)
+and remote `a2a_agent_url` subagents are refused inside a workflow by
+the schema, and a workflow cannot be another syndicate's `yaml_reference`
+(ADK cannot yet make a `Workflow` a subagent; nested, only its
+orchestrator runs). The record is [ADR 0030](./wiki/decisions/0030-workflow-graphs.md);
+the contract is `lib/workflow.ts`, on ADK's `Workflow`.
+
 ## 7. Extending the framework
 
 **Call ADK directly (no syndicate)**: the YAML layer is a convenience,
@@ -801,7 +1027,7 @@ the canonical minimal block — `LlmAgent` + `Runner` +
 `InMemorySessionService` straight from `@google/adk`, ~30 lines you can
 copy into any repo that has `@google/adk` installed. Add
 `registerAvailableProviders()` from `lib/models/registry.ts` and the
-same block runs `claude-*` / `gpt-*` / `grok-*` / `ollama/*` ids too.
+same block runs `claude-*` / `gpt-*` / `grok-*` / `kimi-*` / `ollama/*` ids too.
 
 **Add a syndicate**: create `config/agents/<name>.yaml` — copy the
 closest starter-pack file from `config/agents/examples/` or start from
@@ -852,8 +1078,12 @@ by a person; `skills/README.md` records the procedure.
   optional `adk_telemetry` sink and `adk_agent_registry` with its version
   history (an unprotected registry is worst of all: agent definitions writable with the anon key
   means anyone can rewrite the instructions your server boots). The A2A
-  server verifies hardening at boot and is fatal on public deployments
-  without it. Note `service_role` bypasses RLS by design — the hardening
+  server verifies hardening at boot on both storage paths (`DATABASE_URL`
+  and supabase-js) and is fatal on public deployments without it
+  (`ALLOW_UNHARDENED_DB=true` accepts the risk). Over `DATABASE_URL` the check
+  passes on its own when the database has no `anon` or `authenticated` role
+  (plain Postgres: no API serves the tables) or when the tables live in a
+  schema other than `public` (`MELCHIZEDEK_DB_SCHEMA`). Note `service_role` bypasses RLS by design — the hardening
   constrains the API surface, not the trusted server.
 - **A2A**: bearer auth, a failed-login limiter and a request rate limit
   are built in; without `A2A_SERVER_SECRET` the server binds loopback only.

package/QUICKSTART.md

@@ -14,7 +14,7 @@ fifteen. The full reference is [`DOCUMENTATION.md`](./DOCUMENTATION.md).
 - Optional: **Ollama** ([ollama.com](https://ollama.com)) for the
   open-weight local syndicates; provider keys only for the models you
   actually declare — **Anthropic** (`claude-*`), **OpenAI** (`gpt-*`),
-  **xAI** (`grok-*`) — or one `MODEL_GATEWAY` key as the fallback for
+  **xAI** (`grok-*`), **Moonshot** (`kimi-*`) — or one `MODEL_GATEWAY` key as the fallback for
   whatever direct key is missing (native search is lost on that path);
   and a free **Supabase project** (only for persistent sessions / memory).
   Not sure which you need? `npm run doctor` tells you, read-only.
@@ -243,7 +243,7 @@ console.log(result.text);
 |---|---|
 | `Gemini API Key is not configured` | `.env` missing or key not set — step 2. |
 | `[400] Tool call context circulation is not enabled` | The agent's `model:` is too old for agent transfer. Use `gemini-3.8-flash` or newer (all shipped configs already do). |
-| `Model not found` for `claude-*` / `gpt-*` / `grok-*` | The matching provider key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `XAI_API_KEY`) is not set in `.env`, so the provider wasn't registered — `npm run doctor` names the variable. Or set `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` once for every cloud provider (native search is lost on that path). |
+| `Model not found` for `claude-*` / `gpt-*` / `grok-*` / `kimi-*` | The matching provider key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `XAI_API_KEY` / `MOONSHOT_API_KEY`) is not set in `.env`, so the provider wasn't registered — `npm run doctor` names the variable. Or set `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` once for every cloud provider (native search is lost on that path). |
 | `GATEWAY_HTTP_ERROR … 404/400` | The gateway rejected the mapped model id. Fix the name once in `.env`: `MODEL_GATEWAY_MODEL_MAP=<your id>=<the gateway's id>`. `GATEWAY_KEY_MISSING` means `MODEL_GATEWAY` is set without `MODEL_GATEWAY_API_KEY`. |
 | `OLLAMA_UNREACHABLE` for `ollama/*` | Ollama isn't running — start the app or `ollama serve`; then check the model is pulled (`ollama list`). |
 | `Refusing to connect to private/loopback MCP host` | The SSRF guard is on (correctly). For the local demo set `ALLOW_PRIVATE_MCP=true` in `.env`. |