melchizedek-agents 1.3.0 → 1.6.0

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
@@ -51,17 +75,18 @@ DO $$
 DECLARE t text;
 BEGIN
   FOREACH t IN ARRAY ARRAY['adk_telemetry', 'adk_turns', 'adk_payloads', 'adk_verdicts', 'adk_labels',
-                            'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage', 'melchizedek_audit'] LOOP
+                            'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage', 'melchizedek_audit',
+                            'model_pricing'] 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 +98,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 +109,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 $$;
 
@@ -139,9 +164,12 @@ BEGIN
                         'melchizedek_registry_versions_immutable', 'melchizedek_registry_publish',
                         'melchizedek_registry_activate', 'melchizedek_memory_commit',
                         'melchizedek_memory_dimensions', 'melchizedek_prune_memory_ingest',
-                        'melchizedek_prune_memory', 'melchizedek_prune_audit')
+                        'melchizedek_prune_memory', 'melchizedek_prune_audit',
+                        'melchizedek_cost_usd', 'melchizedek_usage_cost', 'melchizedek_usage_text_cost',
+                        'melchizedek_turns_cost', 'melchizedek_telemetry_cost')
   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 +198,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/db/migrations/0015_model_pricing.sql

@@ -0,0 +1,107 @@
+-- ============================================================================
+-- 0015_model_pricing — what a model call costs, so the ledger records dollars
+--                      (ADR 0136)
+-- ============================================================================
+-- model_pricing: USD per million tokens, one row per model id as the YAML
+-- declares it (`claude-opus-5`, `gemini-3.8-flash`, `grok-4.7`). A row whose
+-- id ends in `/*` prices every id under that prefix (`ollama/*`: local
+-- models cost nothing). `thinking_per_mtok` NULL means thinking bills at the
+-- output rate, as every provider here bills it. `verified_at` NULL means
+-- nobody has checked the row against the vendor's price list: spend built on
+-- it is a steering estimate (the convention ymir_model_pricing set).
+--
+-- Seeded from melch-obs's pricing.toml (2026-10). The seed never overwrites a
+-- row: an operator's own rates survive a re-run. A rate change ships as a
+-- later migration that UPDATEs the row and its verified_at.
+--
+-- The cost functions below are what db/telemetry.sql's ledger trigger calls
+-- to fill adk_turns.cost_usd and adk_telemetry.cost_usd at write time:
+--   melchizedek_cost_usd(model, input, output, thinking)  one call's cost,
+--       NULL for a model with no row
+--   melchizedek_usage_cost(usage)  a turn's cost from its per-model usage
+--       ({"<model>": {"input": n, "output": n, "thinking": n}}), NULL when
+--       any model in it has no row: a partial sum would read as the total.
+-- Ledger output_tokens exclude thinking (genaiMapping's usage meaning), so
+-- thinking is priced on top of output.
+--
+-- Nothing secret, nothing personal; hardening.sql closes it to the API roles
+-- like every other table. Idempotent; safe to re-run.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS model_pricing (
+  model              TEXT PRIMARY KEY,
+  input_per_mtok     NUMERIC NOT NULL CHECK (input_per_mtok >= 0),
+  output_per_mtok    NUMERIC NOT NULL CHECK (output_per_mtok >= 0),
+  thinking_per_mtok  NUMERIC CHECK (thinking_per_mtok >= 0),
+  verified_at        TIMESTAMPTZ,
+  source             TEXT,
+  note               TEXT,
+  updated_at         TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+INSERT INTO model_pricing (model, input_per_mtok, output_per_mtok, verified_at, source, note) VALUES
+  -- Anthropic first-party rates; pricing.toml dates the check to the month (2026-06).
+  ('claude-fable-5-1',      10.00, 50.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-fable-5',        10.00, 50.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-5',          5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-4-8',        5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-4-7',        5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-4-6',        5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-sonnet-5',        2.00, 10.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-sonnet-4-6',      3.00, 15.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-haiku-4-5',       1.00,  5.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('gemini-3.5-flash-lite',  0.30,  2.50, '2026-10-01', 'melch-obs/pricing.toml', 'Gemini API standard tier, checked 2026-10-01'),
+  -- Carried over from ymir_model_pricing, never checked against a vendor list.
+  ('gemini-3.1-flash-lite',  0.10,  0.40, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  ('gemini-3.7-flash',       0.30,  2.50, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  ('gemini-3.8-flash',       0.30,  2.50, NULL, 'melch-obs/pricing.toml', 'placeholder at 3.7''s rate, unverified'),
+  ('grok-4.5',               3.00, 15.00, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  ('grok-4.7',               3.00, 15.00, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  -- A local model bills nothing; that needs no vendor list.
+  ('ollama/*',               0,     0,    '2026-10-15', 'engine', 'local models: no provider charge')
+ON CONFLICT (model) DO NOTHING;
+
+-- The row that prices `model`: its own, else its prefix's `<prefix>/*`.
+CREATE OR REPLACE FUNCTION melchizedek_cost_usd(model TEXT, input BIGINT, output BIGINT, thinking BIGINT)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT (coalesce(input, 0) * p.input_per_mtok
+          + coalesce(output, 0) * p.output_per_mtok
+          + coalesce(thinking, 0) * coalesce(p.thinking_per_mtok, p.output_per_mtok)) / 1000000
+  FROM model_pricing p
+  WHERE p.model = melchizedek_cost_usd.model
+     OR (position('/' IN melchizedek_cost_usd.model) > 0
+         AND p.model = split_part(melchizedek_cost_usd.model, '/', 1) || '/*')
+  ORDER BY (p.model = melchizedek_cost_usd.model) DESC
+  LIMIT 1
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_usage_cost(usage JSONB)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT CASE
+    WHEN usage IS NULL OR jsonb_typeof(usage) <> 'object' THEN NULL
+    -- bool_and over no rows is NULL: a turn that made no model call costs nothing.
+    WHEN coalesce(bool_and(c.cost IS NOT NULL), true) THEN coalesce(sum(c.cost), 0)
+    ELSE NULL
+  END
+  FROM (
+    SELECT melchizedek_cost_usd(
+             e.key,
+             CASE WHEN jsonb_typeof(e.value->'input') = 'number' THEN (e.value->>'input')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'output') = 'number' THEN (e.value->>'output')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'thinking') = 'number' THEN (e.value->>'thinking')::numeric::bigint END
+           ) AS cost
+    FROM jsonb_each(CASE WHEN jsonb_typeof(usage) = 'object' THEN usage ELSE '{}'::jsonb END) e
+  ) c
+$$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (15, '0015_model_pricing')
+ON CONFLICT (version) DO NOTHING;

package/db/telemetry.sql

@@ -163,6 +163,83 @@ CREATE INDEX IF NOT EXISTS idx_adk_turns_surface_user
 -- at CREATE time. It does not gain these columns until it is re-created, so
 -- run the whole file, in order.
 
+-- ── Cost: dollars per turn and per model call (ADR 0136) ─────────────────
+-- cost_usd is filled at write time by the trigger below from model_pricing
+-- (db/migrations/0015_model_pricing.sql), so both sinks and a replayed
+-- dead-letter spool get it, and the price table is the one source:
+--   adk_telemetry  an llm.request row: its model and tokens. A root row: the
+--                  turn's per-model usage on the span (syndicate.usage).
+--   adk_turns      the turn's per-model usage (attributes->'syndicate.usage',
+--                  the tracer sums each model's calls), so a turn that used
+--                  two models is priced per model, input summed per call.
+-- NULL when a model has no price row (a partial sum would read as the
+-- total), or when the row carries no usage (a row written before this
+-- column). A value the writer set itself is kept. The rate in force at
+-- write time is the rate recorded: a later price change does not rewrite
+-- history. Re-price on purpose with an UPDATE ... SET cost_usd = ... .
+ALTER TABLE adk_turns     ADD COLUMN IF NOT EXISTS cost_usd NUMERIC;
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS cost_usd NUMERIC;
+
+-- SECURITY DEFINER: the inserting role (service_role, or an application's
+-- own role) need not be able to execute the pricing functions or read
+-- model_pricing. Each reads only NEW and the price table. Unreadable usage
+-- leaves the cost NULL; it never fails the insert.
+CREATE OR REPLACE FUNCTION melchizedek_usage_text_cost(usage_text TEXT)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE
+SET search_path = public
+AS $$
+BEGIN
+  IF usage_text IS NULL OR to_regclass('model_pricing') IS NULL THEN
+    RETURN NULL;
+  END IF;
+  RETURN melchizedek_usage_cost(usage_text::jsonb);
+EXCEPTION WHEN others THEN
+  RETURN NULL;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_turns_cost()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  IF NEW.cost_usd IS NULL THEN
+    NEW.cost_usd := melchizedek_usage_text_cost(NEW.attributes->>'syndicate.usage');
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_telemetry_cost()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  IF NEW.cost_usd IS NOT NULL OR to_regclass('model_pricing') IS NULL THEN
+    RETURN NEW;
+  END IF;
+  IF NEW.model IS NOT NULL THEN
+    NEW.cost_usd := melchizedek_cost_usd(NEW.model, NEW.input_tokens, NEW.output_tokens, NEW.thinking_tokens);
+  ELSE
+    NEW.cost_usd := melchizedek_usage_text_cost(NEW.span->'attributes'->>'syndicate.usage');
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS melchizedek_turns_cost ON adk_turns;
+CREATE TRIGGER melchizedek_turns_cost BEFORE INSERT ON adk_turns
+  FOR EACH ROW EXECUTE FUNCTION melchizedek_turns_cost();
+DROP TRIGGER IF EXISTS melchizedek_telemetry_cost ON adk_telemetry;
+CREATE TRIGGER melchizedek_telemetry_cost BEFORE INSERT ON adk_telemetry
+  FOR EACH ROW EXECUTE FUNCTION melchizedek_telemetry_cost();
+
 -- ── adk_payloads: full prompt/response per model call, by policy, expiring ─
 CREATE TABLE IF NOT EXISTS adk_payloads (
   id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
@@ -360,7 +437,8 @@ CREATE OR REPLACE VIEW adk_kpi_daily AS
          sum(output_tokens)                                 AS output_tokens,
          sum(thinking_tokens)                               AS thinking_tokens,
          avg(llm_calls)                                     AS avg_llm_calls,
-         avg(tool_calls)                                    AS avg_tool_calls
+         avg(tool_calls)                                    AS avg_tool_calls,
+         sum(cost_usd)                                      AS cost_usd
   FROM adk_turns_production
   GROUP BY 1, 2;
 

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/oauth.d.ts

@@ -75,9 +75,10 @@ export interface SignInResult {
     planUsage: boolean;
 }
 /**
- * The browser sign-in. Stores the registration (host id, issued client id)
- * before the code exchange, and the tokens after the ID token verifies and
- * the plan scope is confirmed.
+ * The browser sign-in. Stores the host id before the browser opens when no
+ * file exists yet, the registration (host id, issued client id) before the
+ * code exchange, and the tokens after the ID token verifies and the plan
+ * scope is confirmed.
  */
 export declare function signIn(opts: SignInOptions): Promise<SignInResult>;
 export interface AccessTokenOptions extends OAuthOptions {

package/dist/lib/chatgpt/oauth.js

@@ -50,6 +50,14 @@ const UNUSABLE_REFRESH = new Set([
     'refresh_token_invalidated',
     'refresh_token_reused',
 ]);
+/**
+ * Callback error codes that mean the consent page refused or the person
+ * stopped there: OpenAI's page for a plan or workspace without plan usage for
+ * apps offers no way on, so leaving it is the usual way these arrive.
+ */
+const REFUSED_AT_CONSENT = new Set(['access_denied', 'unauthorized_client', 'consent_required', 'interaction_required']);
+/** One line for a sign-in OpenAI refused at the consent page or the code exchange. */
+const signInRefused = (code) => `ChatGPT refused the sign-in (${code}); the most common cause is a ChatGPT plan or workspace that does not include plan usage for apps. Retry with \`npm run setup -- --chatgpt-signin\` (\`npx melchizedek-setup --chatgpt-signin\` from an installed package).`;
 /** A sign-in failure: a code for the program, a message for the person, never a token. */
 export class SignInError extends Error {
     code;
@@ -236,7 +244,7 @@ async function listen(port, state, savedClientId, timeoutMs, signal) {
             res.writeHead(200, PAGE_HEADERS).end(page('Sign-in cancelled', 'You can close this tab and return to the terminal.'));
             const raw = url.searchParams.get('error') ?? '';
             const code = /^[a-z0-9_.-]{1,64}$/i.test(raw) ? raw : 'authorization_failed';
-            settle(new SignInError(code, `ChatGPT did not authorize the sign-in (${code}).`));
+            settle(new SignInError(code, REFUSED_AT_CONSENT.has(code) ? signInRefused(code) : `ChatGPT did not authorize the sign-in (${code}).`));
             return;
         }
         const codes = url.searchParams.getAll('code');
@@ -284,9 +292,10 @@ export async function openInBrowser(url) {
     });
 }
 /**
- * The browser sign-in. Stores the registration (host id, issued client id)
- * before the code exchange, and the tokens after the ID token verifies and
- * the plan scope is confirmed.
+ * The browser sign-in. Stores the host id before the browser opens when no
+ * file exists yet, the registration (host id, issued client id) before the
+ * code exchange, and the tokens after the ID token verifies and the plan
+ * scope is confirmed.
  */
 export async function signIn(opts) {
     const issuer = issuerOf(opts);
@@ -295,6 +304,11 @@ export async function signIn(opts) {
     const sameIssuer = previous?.issuer === issuer;
     const hostId = previous?.hostId ?? `urn:uuid:${randomUUID()}`;
     const savedClientId = sameIssuer ? previous?.clientId : undefined;
+    // OpenAI asks for the host id to be chosen and persisted before the first
+    // sign-in, so a timed-out or cancelled attempt does not send a new one next
+    // time. Only written when nothing is stored: a stored registration is kept.
+    if (!previous)
+        writeStoredSignIn(opts.file, { version: 1, issuer, hostId });
     const state = randomValue();
     const nonce = randomValue();
     const verifier = randomValue();
@@ -326,14 +340,24 @@ export async function signIn(opts) {
             ? { ...previous, clientId: cb.clientId, hostId }
             : { version: 1, issuer, hostId, clientId: cb.clientId };
         writeStoredSignIn(opts.file, registration);
-        const data = await tokenRequest(d.token_endpoint, {
-            grant_type: 'authorization_code',
-            client_id: cb.clientId,
-            code: cb.code,
-            code_verifier: verifier,
-            redirect_uri: listener.redirectUri,
-            resource: OPENAI_API_RESOURCE,
-        });
+        let data;
+        try {
+            data = await tokenRequest(d.token_endpoint, {
+                grant_type: 'authorization_code',
+                client_id: cb.clientId,
+                code: cb.code,
+                code_verifier: verifier,
+                redirect_uri: listener.redirectUri,
+                resource: OPENAI_API_RESOURCE,
+            });
+        }
+        catch (err) {
+            // OpenAI's consent page refuses a plan or workspace without plan usage
+            // for apps, and the exchange then answers invalid_grant.
+            if (err instanceof SignInError && err.code === 'invalid_grant')
+                throw new SignInError('invalid_grant', signInRefused('invalid_grant'));
+            throw err;
+        }
         const subject = await verifyIdToken(data.id_token, d, cb.clientId, nonce);
         const fields = tokenFields(data);
         const planUsage = fields.scopes.includes(PLAN_SCOPE);

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/compileNative.js

@@ -215,6 +215,7 @@ export function workflowSubagentOf(workflow) {
             ...(run.memory ? { memory: run.memory } : {}),
             ...(run.log ? { log: run.log } : {}),
             ...(run.credentials ? { credentials: run.credentials } : {}),
+            ...(run.consent ? { consent: run.consent } : {}),
         }),
     };
 }

package/dist/lib/index.d.ts

@@ -24,7 +24,7 @@ export type { MemoryEntry, MemoryIngestOptions, MemorySearchRequest, MemorySearc
 export type { TurnEvent } from './runtime/events.ts';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.ts';
 export type { PendingApproval } from './runtime/approvals.ts';
-export type { DrainedRun, MessagePart, TurnUsage, RouteDecision, SyndicateTurnOptions, SyndicateTurnResult, TraceOptions, TurnEvents, TurnStage, } from './runtime/syndicateTurn.ts';
+export type { AgentBranch, DrainedRun, MessagePart, TurnUsage, RouteDecision, SyndicateTurnOptions, SyndicateTurnResult, TraceOptions, TurnEvents, TurnStage, } from './runtime/syndicateTurn.ts';
 export type { CompileOptions } from './compile.ts';
 export { isWorkflowSyndicate, describeInput } from './workflow.ts';
 export type { WorkflowConfig, WorkflowNodeYaml, EdgeElement, PendingInput } from './workflow.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;