melchizedek-agents 1.4.0 → 1.5.0

package/.env.example

@@ -136,6 +136,21 @@ SUPABASE_SERVICE_ROLE_KEY=
 # adk_telemetry table. Provision it first: run db/telemetry.sql in the Supabase
 # SQL Editor, then re-run db/hardening.sql. See DOCUMENTATION.md §5.
 TELEMETRY_SUPABASE=false
+# Or, with DATABASE_URL set, write the same ledger to that Postgres instead
+# (db/telemetry.sql applied there). Use one sink, not both.
+TELEMETRY_POSTGRES=false
+
+# ── Optional: local MCP servers over stdio ───────────────────────────────────
+# Comma-separated `command` values an mcp_servers entry may start (exact
+# match, e.g. "npx,uvx"). Unset: no stdio server runs. See ADR 0132.
+MELCHIZEDEK_STDIO_MCP=
+
+# ── Optional: where the engine writes ─────────────────────────────────────────
+# One directory for the on-disk defaults (outputs/, outputs/tasks.json,
+# chatgpt-signin.json). OUTPUTS_DIR, MELCHIZEDEK_TASKS_FILE and
+# MELCHIZEDEK_CHATGPT_SIGNIN_FILE still win. Unset: ./outputs and
+# ~/.melchizedek as before. See ADR 0134.
+MELCHIZEDEK_DATA_DIR=
 
 # ── Optional: A2A Server ──────────────────────────────────────────────────────
 # A2A_SERVER_SECRET: Bearer token used to authenticate incoming A2A requests.

package/CHANGELOG.md

@@ -6,6 +6,83 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 1.5.0 — 2026-10-15
+
+A minor release that makes the engine embeddable in a single-process
+application with no database server and no keys in its environment, and
+adds local MCP servers. Embedded Postgres (PGlite) runs the schema and
+`postgresStorage` unchanged (ADR 0130); the telemetry ledger can be written
+to any Postgres through the storage's own pool (ADR 0131); an `mcp_servers`
+entry can start a local server over stdio, behind an operator allowlist
+(ADR 0132); an application supplies credentials from its own store through
+one source asked by variable name (ADR 0133); and one variable,
+`MELCHIZEDEK_DATA_DIR`, roots the engine's files (ADR 0134). Nothing
+changes for an existing deployment that sets none of the new options. Two
+fixes ride along: `inspect_image` with `OUTPUTS_DIR` set, and the ledger's
+`engine_version` for an installed engine.
+
+### Added
+
+- **`postgresStorage({ turnLock })` and `inProcessTurnLock` exported from
+  `melchizedek-agents/storage/postgres` (ADR 0130).** The storage uses the
+  given lock instead of its advisory lock and opens no turn-lock pool. Pass
+  `inProcessTurnLock()` when one process owns an embedded database such as
+  PGlite behind pglite-socket, where every connection shares one session and
+  an advisory lock excludes nothing. The default is unchanged.
+
+- **The telemetry ledger on any Postgres (ADR 0131).**
+  `postgresStorage({ ledger: true })` writes `adk_turns`, `adk_telemetry` and
+  `adk_payloads` through the storage's own pool, with the rows, payload
+  policy and redaction the Supabase sink uses; `close()` flushes it. The A2A
+  bin turns it on with `TELEMETRY_POSTGRES=true` beside `DATABASE_URL`.
+  New exports from `melchizedek-agents/observability/*`: `attachLedger`
+  (tracer), `postgresLedgerClient`, `LedgerClient` and `LEDGER_TABLES`
+  (supabaseSpanExporter).
+
+- **Local MCP servers over stdio (ADR 0132).** An `mcp_servers` entry may give
+  `command` (with `args`, `env`, `pass_env`, `cwd`) instead of `url`; the
+  server is started over stdio, one process per spec for the life of the
+  engine. It runs only when `MELCHIZEDEK_STDIO_MCP` lists the exact command.
+  The child gets a minimal environment plus `pass_env` by name and `env`
+  literals; a credential-looking `env` key is refused at load. New exports
+  from `melchizedek-agents/tools/mcpToolFactory`: `loadStdioMcpTools`,
+  `stdioCommandAllowed`, `stdioEnvironment`, `StdioMcpSpec`; `McpServerConfig.url`
+  is now optional. `pass_env` reads through the credential source (below)
+  before the environment, so a key held in an application's keychain reaches
+  the server by name.
+
+- **`setCredentialSource`, `credentialValue` and `CredentialSource` in the
+  barrel (ADR 0133).** An embedding application supplies keys from its own
+  store, asked by environment variable name (`ANTHROPIC_API_KEY`, …) before
+  `process.env`, at each use and never cached. Every key read in the engine
+  goes through it: the five adapters, the gateway, provider presence and
+  `providerStatuses()`, endpoints, embeddings, the memory providers and the
+  Gemini image and vision tools. Without a source, behaviour is unchanged.
+
+- **`MELCHIZEDEK_DATA_DIR` (ADR 0134).** When set, the engine's on-disk
+  defaults go under it: `outputs/` (generated images, the telemetry spool),
+  `outputs/tasks.json` and `chatgpt-signin.json`. `OUTPUTS_DIR`,
+  `MELCHIZEDEK_TASKS_FILE` and `MELCHIZEDEK_CHATGPT_SIGNIN_FILE` still win;
+  without any, the defaults are unchanged.
+
+### Fixed
+
+- **`db/hardening.sql` applies on Postgres without Supabase's API roles
+  (ADR 0130).** It revoked from `anon` and `authenticated` by name and failed
+  where they do not exist (plain Postgres, PGlite). It now revokes from
+  whichever of the two exist, through helpers in `pg_temp` that leave nothing
+  behind; on Supabase the result is the same as before. RLS and the `PUBLIC`
+  revokes apply everywhere.
+
+- **`inspect_image` reads the image `generate_image` reported when
+  `OUTPUTS_DIR` is set (ADR 0134).** It resolved `outputs/<file>` against the
+  working directory and refused it whenever the outputs directory was
+  elsewhere. A relative path is now read inside the outputs directory; the
+  confinement is unchanged.
+- **The ledger's `engine_version` is the engine's (ADR 0134).** It read
+  `package.json` and the git commit from the working directory, so an
+  installed engine reported the embedding application's version and commit.
+
 ## 1.4.0 — 2026-10-13
 
 A minor release with two additions and no breaking change. OAuth consent

package/DOCUMENTATION.md

@@ -150,7 +150,7 @@ Field reference:
 | `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)). With `client_registration: dynamic` and no client id or endpoints, the authorization server is discovered from the MCP server and this deployment registers itself as a client, every discovered host held to `MELCHIZEDEK_OAUTH_HOSTS` (ADR 0124). |
 | `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. |
 | `mcp_transport` | subagent | How `mcp_server_url` is reached: `auto` (default: Streamable HTTP, falling back to the legacy SSE transport on the spec's signal), `streamable_http` or `sse` ([ADR 0124](./wiki/decisions/0124-mcp-client-streamable-http-several-servers-and-dynamic-registration.md)). |
-| `mcp_servers` | any agent | Several MCP servers: a list of `{ name, url, tools, auth?, transport? }`. `tools` is required on each; a tool name on two servers, or shared with the agent's own tools, is refused at load. `require_approval` may name any server's tool. Not with `mcp_server_url` (ADR 0124). |
+| `mcp_servers` | any agent | Several MCP servers: a list of `{ name, url, tools, auth?, transport? }`, or for a local server `{ name, command, args?, env?, pass_env?, cwd?, tools }` started over stdio when `MELCHIZEDEK_STDIO_MCP` lists the command (ADR 0132). `tools` is required on each; a tool name on two servers, or shared with the agent's own tools, is refused at load. `require_approval` may name any server's tool. Not with `mcp_server_url` (ADR 0124). |
 | `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. |
@@ -207,6 +207,23 @@ 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.
 
+A local MCP server is an `mcp_servers` entry with `command` instead of
+`url`, started over stdio (ADR 0132):
+
+```yaml
+mcp_servers:
+  - name: github
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    pass_env: [GITHUB_PERSONAL_ACCESS_TOKEN]   # copied by name; never a value here
+    tools: [search_issues, get_issue]
+```
+
+It runs only when the operator lists the exact command,
+`MELCHIZEDEK_STDIO_MCP=npx`. The child sees a minimal environment plus
+the `pass_env` names and the non-secret `env` values, nothing else of the
+engine's. One process serves every turn and is restarted if it exits.
+
 **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 the
 engine's own parser and caller in `lib/tools/openapi/`;
@@ -302,6 +319,14 @@ nothing is changed, and two applies started together run one after the other.
 Rolling back a migration that succeeded is a restore from backup (§6), since
 the migrations only move forward.
 
+The same install runs on plain Postgres without Supabase's `anon` and
+`authenticated` roles (the hardening skips the revokes by role name there), and
+on embedded Postgres: an application can run PGlite with pgvector in-process,
+serve it with pglite-socket, and pass `postgresStorage({ connectionString,
+turnLock: inProcessTurnLock() })`. Every connection to PGlite shares one
+session, so the default advisory turn lock would exclude nothing; one process
+owns the data directory (ADR 0130).
+
 The tables go in the `public` schema by default. To keep them out of reach of
 a REST layer (Supabase exposes `public`), install into a private schema and
 run the server with the same setting:
@@ -568,13 +593,29 @@ helpers. A project that only calls models imports from there. Its
 `resolveAdapter` gives a Gemini id `GeminiAdapter`; `resolveModel` is not
 in it.
 
+An application that keeps keys outside the environment (an OS keychain,
+a secret manager) sets one credential source, asked by the same variable
+names at each use, before `process.env` (ADR 0133):
+
+```ts
+import { setCredentialSource } from 'melchizedek-agents';
+setCredentialSource((name) => keychain.get(name)); // e.g. 'ANTHROPIC_API_KEY'
+```
+
+Every key read goes through it: the adapters, the gateway, provider
+status, embeddings and the image tools. A key removed from the source
+stops being sent on the next request.
+
 Every model request also emits an `llm.request` OpenTelemetry span
 (provider, model, input/output/thinking tokens, latency). Scripts print it
 as an `[OTEL_SPAN_JSON]` line; `melchizedek-chat` and the `syndicate:*`
 scripts keep those lines off unless `OTEL_CONSOLE_SPANS=true`. Set
 `TELEMETRY_SUPABASE=true` to persist
 spans to the `adk_telemetry` table (run `db/telemetry.sql`, then
-re-run `db/hardening.sql` — schema below):
+re-run `db/hardening.sql` — schema below). On `DATABASE_URL`, set
+`TELEMETRY_POSTGRES=true` instead to write the same rows through the
+storage's own pool; an application that builds its own storage passes
+`postgresStorage({ ledger: true })` (ADR 0131). Use one sink:
 
 `db/telemetry.sql` (idempotent) creates three tables: `adk_turns` — one
 row per turn with input, output, the responding agent, the plan-dispatch

package/config/agents/syndicate.schema.json

@@ -583,9 +583,47 @@
                 "description": "A short name for the server, unique on this agent: logs and errors name it."
               },
               "url": {
+                "description": "The MCP server's URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard. Give url or command, not both.",
                 "type": "string",
-                "format": "uri",
-                "description": "The MCP server's URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard."
+                "format": "uri"
+              },
+              "command": {
+                "description": "A local MCP server to start and speak to over stdio (ADR 0132), instead of url: the program to run. It runs only when the operator lists this exact value in MELCHIZEDEK_STDIO_MCP. One process per distinct command, args, env and cwd, kept for the life of the engine.",
+                "type": "string",
+                "minLength": 1
+              },
+              "args": {
+                "description": "The command's arguments (stdio only).",
+                "maxItems": 64,
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "env": {
+                "description": "Non-secret variables set for the command (stdio only). A credential is never written here: name it in pass_env.",
+                "type": "object",
+                "propertyNames": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"
+                },
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "pass_env": {
+                "description": "Variables copied by name from the engine's environment into the command's (stdio only); the command sees no other variable of the engine's beyond a minimal default set (PATH, HOME, …). A name that is unset fails the compile.",
+                "maxItems": 32,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"
+                }
+              },
+              "cwd": {
+                "description": "The command's working directory (stdio only); relative to the YAML file's directory.",
+                "type": "string",
+                "minLength": 1
               },
               "tools": {
                 "minItems": 1,
@@ -694,7 +732,6 @@
             },
             "required": [
               "name",
-              "url",
               "tools"
             ],
             "additionalProperties": false,
@@ -1570,9 +1607,47 @@
                   "description": "A short name for the server, unique on this agent: logs and errors name it."
                 },
                 "url": {
+                  "description": "The MCP server's URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard. Give url or command, not both.",
                   "type": "string",
-                  "format": "uri",
-                  "description": "The MCP server's URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard."
+                  "format": "uri"
+                },
+                "command": {
+                  "description": "A local MCP server to start and speak to over stdio (ADR 0132), instead of url: the program to run. It runs only when the operator lists this exact value in MELCHIZEDEK_STDIO_MCP. One process per distinct command, args, env and cwd, kept for the life of the engine.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "args": {
+                  "description": "The command's arguments (stdio only).",
+                  "maxItems": 64,
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "env": {
+                  "description": "Non-secret variables set for the command (stdio only). A credential is never written here: name it in pass_env.",
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"
+                  },
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                "pass_env": {
+                  "description": "Variables copied by name from the engine's environment into the command's (stdio only); the command sees no other variable of the engine's beyond a minimal default set (PATH, HOME, …). A name that is unset fails the compile.",
+                  "maxItems": 32,
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"
+                  }
+                },
+                "cwd": {
+                  "description": "The command's working directory (stdio only); relative to the YAML file's directory.",
+                  "type": "string",
+                  "minLength": 1
                 },
                 "tools": {
                   "minItems": 1,
@@ -1681,7 +1756,6 @@
               },
               "required": [
                 "name",
-                "url",
                 "tools"
               ],
               "additionalProperties": false,

package/db/hardening.sql

@@ -30,6 +30,27 @@
 -- The A2A server checks at boot whether this file has been applied and
 -- prints a prominent warning if not (see lib/persistence/supabaseProvider.ts).
 
+-- ── The API roles ────────────────────────────────────────────────────────
+-- anon and authenticated are Supabase's PostgREST roles. Plain Postgres and
+-- embedded Postgres (PGlite) have no REST API and normally no such roles;
+-- there, the PUBLIC revokes and RLS below are the whole lockdown, and the
+-- revokes by role name are skipped rather than failing. These two helpers
+-- live in pg_temp: they exist for this session only and leave nothing behind.
+CREATE OR REPLACE FUNCTION pg_temp.melchizedek_api_roles() RETURNS text
+LANGUAGE sql AS $$
+  SELECT string_agg(quote_ident(rolname), ', ' ORDER BY rolname)
+  FROM pg_roles WHERE rolname IN ('anon', 'authenticated');
+$$;
+
+CREATE OR REPLACE FUNCTION pg_temp.melchizedek_revoke_api(target text) RETURNS void
+LANGUAGE plpgsql AS $$
+DECLARE roles text := pg_temp.melchizedek_api_roles();
+BEGIN
+  IF roles IS NOT NULL THEN
+    EXECUTE format('REVOKE ALL ON %s FROM %s', target, roles);
+  END IF;
+END $$;
+
 -- ── Tier 1: lock the public API paths ────────────────────────────────────
 
 -- Enable RLS. With RLS on and NO policies defined, anon/authenticated get
@@ -40,8 +61,11 @@ ALTER TABLE adk_sessions     ENABLE ROW LEVEL SECURITY;
 -- Belt and suspenders: also revoke the default table privileges from the
 -- API roles, so even a future accidentally-created permissive policy
 -- cannot re-expose the tables.
-REVOKE ALL ON adk_memory_facts FROM anon, authenticated;
-REVOKE ALL ON adk_sessions     FROM anon, authenticated;
+DO $$
+BEGIN
+  PERFORM pg_temp.melchizedek_revoke_api('adk_memory_facts');
+  PERFORM pg_temp.melchizedek_revoke_api('adk_sessions');
+END $$;
 
 -- Optional observability ledger (db/telemetry.sql). Guarded: the tables only
 -- exist when the operator opted into TELEMETRY_SUPABASE. adk_turns holds
@@ -54,14 +78,14 @@ BEGIN
                             'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage', 'melchizedek_audit'] LOOP
     IF to_regclass('public.' || t) IS NOT NULL THEN
       EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', t);
-      EXECUTE format('REVOKE ALL ON %I FROM anon, authenticated', t);
+      PERFORM pg_temp.melchizedek_revoke_api(format('%I', t));
     END IF;
   END LOOP;
   -- The production view and the retention function read/delete those
   -- tables on behalf of the caller; neither belongs on the public API.
   FOREACH t IN ARRAY ARRAY['adk_turns_production', 'adk_kpi_daily', 'adk_kpi_routes_daily', 'adk_kpi_judges_daily', 'adk_kpi_hourly'] LOOP
     IF to_regclass('public.' || t) IS NOT NULL THEN
-      EXECUTE format('REVOKE ALL ON %I FROM anon, authenticated', t);
+      PERFORM pg_temp.melchizedek_revoke_api(format('%I', t));
     END IF;
   END LOOP;
   -- Function privileges for these are handled in the FUNCTIONS block below.
@@ -73,7 +97,7 @@ DO $$
 BEGIN
   IF to_regclass('public.melchizedek_schema_version') IS NOT NULL THEN
     EXECUTE 'ALTER TABLE melchizedek_schema_version ENABLE ROW LEVEL SECURITY';
-    EXECUTE 'REVOKE ALL ON melchizedek_schema_version FROM anon, authenticated';
+    PERFORM pg_temp.melchizedek_revoke_api('melchizedek_schema_version');
   END IF;
 END $$;
 
@@ -84,29 +108,29 @@ DO $$
 BEGIN
   IF to_regclass('public.adk_agent_registry') IS NOT NULL THEN
     EXECUTE 'ALTER TABLE adk_agent_registry ENABLE ROW LEVEL SECURITY';
-    EXECUTE 'REVOKE ALL ON adk_agent_registry FROM anon, authenticated';
+    PERFORM pg_temp.melchizedek_revoke_api('adk_agent_registry');
   END IF;
   -- The task tools' lists and job queue (migration 0009).
   IF to_regclass('public.melchizedek_tasks') IS NOT NULL THEN
     EXECUTE 'ALTER TABLE melchizedek_tasks ENABLE ROW LEVEL SECURITY';
     EXECUTE 'ALTER TABLE melchizedek_task_owners ENABLE ROW LEVEL SECURITY';
-    EXECUTE 'REVOKE ALL ON melchizedek_tasks, melchizedek_task_owners FROM anon, authenticated';
+    PERFORM pg_temp.melchizedek_revoke_api('melchizedek_tasks, melchizedek_task_owners');
   END IF;
   -- The memory processed marker (migration 0007): identifiers only.
   IF to_regclass('public.melchizedek_memory_ingest') IS NOT NULL THEN
     EXECUTE 'ALTER TABLE melchizedek_memory_ingest ENABLE ROW LEVEL SECURITY';
-    EXECUTE 'REVOKE ALL ON melchizedek_memory_ingest FROM anon, authenticated';
+    PERFORM pg_temp.melchizedek_revoke_api('melchizedek_memory_ingest');
   END IF;
   -- Third-party tokens held for tools (migration 0013): ciphertext only,
   -- still nothing an API role should read.
   IF to_regclass('public.melchizedek_tool_credentials') IS NOT NULL THEN
     EXECUTE 'ALTER TABLE melchizedek_tool_credentials ENABLE ROW LEVEL SECURITY';
-    EXECUTE 'REVOKE ALL ON melchizedek_tool_credentials FROM anon, authenticated';
+    PERFORM pg_temp.melchizedek_revoke_api('melchizedek_tool_credentials');
   END IF;
   -- Its history (migration 0005): every definition an id has held.
   IF to_regclass('public.adk_agent_registry_versions') IS NOT NULL THEN
     EXECUTE 'ALTER TABLE adk_agent_registry_versions ENABLE ROW LEVEL SECURITY';
-    EXECUTE 'REVOKE ALL ON adk_agent_registry_versions FROM anon, authenticated';
+    PERFORM pg_temp.melchizedek_revoke_api('adk_agent_registry_versions');
   END IF;
 END $$;
 
@@ -141,7 +165,8 @@ BEGIN
                         'melchizedek_memory_dimensions', 'melchizedek_prune_memory_ingest',
                         'melchizedek_prune_memory', 'melchizedek_prune_audit')
   LOOP
-    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC, anon, authenticated', fn);
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC', fn);
+    PERFORM pg_temp.melchizedek_revoke_api(format('FUNCTION %s', fn));
     IF has_service_role THEN
       EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO service_role', fn);
     END IF;
@@ -170,9 +195,10 @@ AS $$
                       'melchizedek_audit', 'melchizedek_tool_credentials');
 $$;
 
-REVOKE ALL ON FUNCTION melchizedek_rls_status() FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION melchizedek_rls_status() FROM PUBLIC;
 DO $$
 BEGIN
+  PERFORM pg_temp.melchizedek_revoke_api('FUNCTION melchizedek_rls_status()');
   IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
     GRANT EXECUTE ON FUNCTION melchizedek_rls_status() TO service_role;
   END IF;

package/dist/lib/a2a/app.js

@@ -68,6 +68,7 @@ import { setOAuthHosts } from '../tools/oauthHosts.js';
 import { setCredentialHosts } from '../tools/credentialHosts.js';
 import { syndicateCredentialHostProblems } from '../tools/credentialUses.js';
 import { syndicateOAuthHostProblems } from '../tools/oauthTools.js';
+import { credentialValue } from '../models/credentialSource.js';
 const SURFACE_HEADERS = [
     ['x-surface', 'name'],
     ['x-surface-guild', 'guild'],
@@ -335,7 +336,7 @@ export async function createA2AApp(options) {
         // Embeddings and fact extraction use the SERVER's Gemini key: memory is
         // operator infrastructure, like tools.
         const services = await createSupabaseServices({
-            apiKey: process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY || '',
+            apiKey: credentialValue('GOOGLE_GENAI_API_KEY') || credentialValue('GEMINI_API_KEY') || '',
             withMemory: true,
             extractor: options.memory?.extractor,
             embedder: options.memory?.embedder,

package/dist/lib/chatgpt/state.js

@@ -21,8 +21,9 @@
  * times and the file's path.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { chatGptSignInFile } from '../paths.js';
+import { credentialEnv } from '../models/credentialSource.js';
 /** Where the credential file lives, when not the default (a path; never a value). */
 export const CHATGPT_SIGNIN_FILE_ENV = 'MELCHIZEDEK_CHATGPT_SIGNIN_FILE';
 /** `off` ignores a stored sign-in (a served process on a machine that also signed in). */
@@ -31,8 +32,7 @@ export const CHATGPT_SIGNIN_ENV = 'MELCHIZEDEK_CHATGPT_SIGNIN';
 export const PLAN_SCOPE = 'chatgpt.tokens.use.direct';
 /** The credential file: MELCHIZEDEK_CHATGPT_SIGNIN_FILE, else ~/.melchizedek/chatgpt-signin.json. */
 export function signInFile(env = process.env) {
-    const set = env[CHATGPT_SIGNIN_FILE_ENV]?.trim();
-    return set ? resolve(set) : join(homedir(), '.melchizedek', 'chatgpt-signin.json');
+    return chatGptSignInFile(env);
 }
 /** The git work tree a path sits inside, if any (an ancestor holding `.git`). */
 export function insideGitWorkTree(file) {
@@ -100,7 +100,7 @@ export function chatGptSignInStatus(env = process.env) {
  * OPENAI_PLATFORM other than direct, no OPENAI_BASE_URL proxy, which must
  * never receive the token).
  */
-export function chatGptSignInRoutesOpenAi(env = process.env) {
+export function chatGptSignInRoutesOpenAi(env = credentialEnv()) {
     if (env.OPENAI_API_KEY?.trim())
         return false;
     const platform = env.OPENAI_PLATFORM?.trim().toLowerCase();

package/dist/lib/compile.js

@@ -42,7 +42,7 @@ import { REASONING_OLDER_SPELLING } from './syndicateSchema.js';
 import { reasoningConfig } from './models/reasoning.js';
 import { instructionFor, toEngineAgent } from './agentDialect.js';
 import { resolveTools as resolveNamedTools } from './toolRegistry.js';
-import { createMcpTools } from './tools/mcpToolFactory.js';
+import { createMcpTools, loadStdioMcpTools } from './tools/mcpToolFactory.js';
 import { requireApproval, toolOf } from './tools/tool.js';
 import { examplesInstructionTool } from './tools/examples.js';
 import { capabilitySummary, describeCapabilities } from './models/capabilities.js';
@@ -145,6 +145,17 @@ export function examplesTool(examples) {
     const tool = examplesInstructionTool(examples);
     return tool ? [tool] : [];
 }
+/** A stdio server's tools (ADR 0132), narrowed to the names the entry lists. */
+async function stdioOfferedBy(server, opts) {
+    const label = `${server.name} (stdio: ${server.command})`;
+    opts.log?.(`Loading MCP tools: ${label}`);
+    const offered = await loadStdioMcpTools(server.name, { command: server.command, args: server.args, env: server.env, pass_env: server.pass_env, cwd: server.cwd });
+    const allowed = new Set(server.tools);
+    const missing = server.tools.filter((n) => !offered.some((t) => t.name === n));
+    if (missing.length)
+        opts.log?.(`MCP ${label} does not offer ${missing.map((n) => `'${n}'`).join(', ')}`);
+    return offered.filter((t) => allowed.has(t.name));
+}
 async function resolveAgentTools(agent, opts) {
     const tools = [...resolveNamedTools(agent.tools, opts.onUnknownTool), ...examplesTool(agent.examples)];
     // OpenAPI operations become tools here, so require_approval can name them.
@@ -185,7 +196,9 @@ async function resolveAgentTools(agent, opts) {
     // mcp_servers (ADR 0124): the loader refused a declared name twice; a
     // server that answers with a name already taken is refused here too, so
     // no server's tool can stand in for another's or the agent's own.
-    const servers = await Promise.all((agent.mcp_servers ?? []).map((server) => offeredBy(`${server.name} (${server.url})`, server.url, server.tools, server.auth?.oauth2, server.transport)));
+    const servers = await Promise.all((agent.mcp_servers ?? []).map((server) => server.command !== undefined
+        ? stdioOfferedBy(server, opts)
+        : offeredBy(`${server.name} (${server.url})`, server.url, server.tools, server.auth?.oauth2, server.transport)));
     for (const [i, offered] of servers.entries()) {
         const server = agent.mcp_servers[i];
         for (const mcpTool of offered) {

package/dist/lib/index.d.ts

@@ -57,3 +57,5 @@ export type { MemoryStore } from './memory/store.ts';
 export { validateSyndicateConfig, syndicateJsonSchema, SyndicateValidationError } from './syndicateSchema.ts';
 export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logProviderStatuses, resolveModel, describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayProblem, gatewayUsable, GATEWAYS, } from './models/registry.ts';
 export { loadEnv } from './loadEnv.ts';
+export { setCredentialSource, credentialValue } from './models/credentialSource.ts';
+export type { CredentialSource } from './models/credentialSource.ts';

package/dist/lib/index.js

@@ -48,3 +48,5 @@ export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logP
 // subpath until 0.16.0.
 describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayProblem, gatewayUsable, GATEWAYS, } from './models/registry.js';
 export { loadEnv } from './loadEnv.js';
+// Where credentials are read, by environment variable name (ADR 0133).
+export { setCredentialSource, credentialValue } from './models/credentialSource.js';

package/dist/lib/loadSyndicate.js

@@ -261,6 +261,10 @@ function anchorSpecPaths(config, dir) {
         for (const entry of agent?.openapi ?? [])
             if (!path.isAbsolute(entry.spec))
                 entry.spec = path.resolve(dir, entry.spec);
+        // A stdio server's working directory, like a spec, is the YAML's (ADR 0132).
+        for (const entry of agent?.mcp_servers ?? [])
+            if (entry.cwd && !path.isAbsolute(entry.cwd))
+                entry.cwd = path.resolve(dir, entry.cwd);
     };
     anchor(config.orchestrator);
     for (const sub of config.subagents ?? [])

package/dist/lib/memory/providers.js

@@ -37,6 +37,7 @@ import { providerForModel } from '../models/providerMap.js';
 import { resolveModel } from '../models/registry.js';
 import { startEngineSpan, traceLlmGeneration } from '../observability/tracer.js';
 import { trimTrailingSlashes } from '../models/urls.js';
+import { credentialEnv } from '../models/credentialSource.js';
 /**
  * Extraction on any model id. The key passed here reaches only a model of
  * the matching provider (resolveModel's BYOK rule); other providers read
@@ -194,7 +195,7 @@ export const DEFAULT_EMBEDDING_MODELS = {
  * already passes for memory; it is used only when the configured extraction
  * model or embedder is Gemini.
  */
-export function memoryProvidersFromEnv(env = process.env, geminiKey) {
+export function memoryProvidersFromEnv(env = credentialEnv(), geminiKey) {
     const extractionModel = env.MEMORY_EXTRACTION_MODEL?.trim() || MEMORY_EXTRACTION_MODEL;
     const extractor = modelExtractor({
         model: extractionModel,

package/dist/lib/models/claudeAdapter.js

@@ -47,6 +47,7 @@ import { currentTurnStart, providerStateOf, withProviderState } from './provider
 import { errorDecision, errorText } from './errorResponse.js';
 import { adaptiveThinkingFor, claudeGeneration, claudeReasoningOf, claudeUrlImagesOn, THINKING_BINDING_BETA } from './claudeModels.js';
 import { isAboveHigh } from './reasoning.js';
+import { credentialValue } from './credentialSource.js';
 /** The provider id this adapter reports and writes its state under (lib/models/providerMap.ts). */
 export const ANTHROPIC_PROVIDER = 'anthropic';
 /** The providerState kind this adapter writes: the signed blocks that preceded a part. */
@@ -217,7 +218,7 @@ export class ClaudeAdapter {
             yield setupFailure('ENDPOINT_MISCONFIGURED', messageOf(err));
             return;
         }
-        const spec = claudeClientSpec(endpoint, this.#apiKey || endpoint.apiKey || process.env.ANTHROPIC_API_KEY);
+        const spec = claudeClientSpec(endpoint, this.#apiKey || endpoint.apiKey || credentialValue('ANTHROPIC_API_KEY'));
         if ('error' in spec) {
             yield setupFailure(endpoint.platform === 'direct' ? 'MISSING_API_KEY' : 'ENDPOINT_MISCONFIGURED', spec.error);
             return;

package/dist/lib/models/credentialSource.d.ts

@@ -0,0 +1,28 @@
+/**
+ * lib/models/credentialSource.ts — where the engine reads a credential by
+ * its environment variable name (ADR 0133).
+ *
+ * By default every provider key, gateway key and embedding key is read from
+ * `process.env`. An embedding application that holds keys elsewhere (an OS
+ * keychain, a secret manager) sets a source once:
+ *
+ *   setCredentialSource((name) => keychain.get(name));
+ *
+ * and every read below asks the source first, by the same names the
+ * environment uses (ANTHROPIC_API_KEY, MODEL_GATEWAY_API_KEY, …), at the
+ * moment of use: nothing is cached, so a key the user removes stops working
+ * on the next call. A source that returns undefined for a name falls back to
+ * the environment. A dependency-free leaf, so providerMap.ts stays one.
+ */
+/** Returns the credential held under an environment variable name, or undefined. Must not throw. */
+export type CredentialSource = (name: string) => string | undefined;
+/** Sets (or, with undefined, clears) the process's credential source. */
+export declare function setCredentialSource(next: CredentialSource | undefined): void;
+/** The credential named `name`: the source's, else `env`'s. A source that throws counts as holding nothing. */
+export declare function credentialValue(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * `env` as the engine's env-reading helpers see it: a read by name asks the
+ * source first. For functions that take an `env` parameter; enumeration and
+ * spreading see only `env`'s own variables.
+ */
+export declare function credentialEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;