melchizedek-agents 1.1.0 → 1.3.0

package/dist/scripts/assistant_worker.js

@@ -40,15 +40,18 @@
  *   --agent names a subagent of the syndicate, or its orchestrator.
  *   MELCHIZEDEK_TASKS_FILE moves the store (default: outputs/tasks.json),
  *   and must match the chat process's value. Run ONE worker per store.
+ *   MELCHIZEDEK_CHECKPOINT_MAX_BYTES caps a stored checkpoint (bytes of
+ *   JSON, default 5 MiB); a larger one is skipped and the previous kept.
  */
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
 import { loadSyndicate } from '../lib/loadSyndicate.js';
 import { runDurableTurn } from '../lib/runtime/native/checkpoint.js';
 import { runtimeSetting } from '../lib/runtime/runtimeFlag.js';
+import { refuseChatGptSignInOnServedSurface } from '../lib/chatgpt/state.js';
 import { setLogLevel } from '../lib/runtime/logging.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, } from '../lib/models/registry.js';
-import { applyInterrupted, getTaskBackend, setTaskBackend, taskStorePath } from '../lib/tools/taskTools.js';
+import { CHECKPOINT_MAX_BYTES_ENV, applyInterrupted, checkpointMaxBytesSetting, fileTaskBackendWith, getTaskBackend, setTaskBackend, taskStorePath, } from '../lib/tools/taskTools.js';
 import { postgresStorage } from '../lib/storage/postgres/index.js';
 import { dbSchema } from '../lib/storage/schema.js';
 import { hostname } from 'node:os';
@@ -56,6 +59,14 @@ loadEnv(import.meta.url);
 setLogLevel('warn');
 // MELCHIZEDEK_RUNTIME=adk (removed in 1.0.0) stops the worker here, naming the release.
 runtimeSetting();
+// Sign in with ChatGPT is local only (ADR 0126): the worker runs jobs unattended, so it never runs on it.
+try {
+    refuseChatGptSignInOnServedSurface('melchizedek-worker');
+}
+catch (err) {
+    console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}
 // ── CLI ──────────────────────────────────────────────────────────────────────
 const argv = process.argv.slice(2).filter((a) => a !== '--');
 const flag = (name) => {
@@ -90,10 +101,17 @@ if (!providerKeyPresent(provider)) {
 const log = (message) => console.log(`[worker] ${message}`);
 // The queue: the JSON file, or Postgres when DATABASE_URL is set, where any
 // number of workers may run (each claim is FOR UPDATE SKIP LOCKED).
+// A checkpoint above MELCHIZEDEK_CHECKPOINT_MAX_BYTES (bytes of JSON, default
+// 5 MiB) is not saved: the job keeps its previous one (ADR 0113).
+const rawCap = process.env[CHECKPOINT_MAX_BYTES_ENV];
+const checkpointMaxBytes = checkpointMaxBytesSetting(rawCap);
+if (rawCap?.trim() && Number(rawCap.trim()) !== checkpointMaxBytes) {
+    log(`${CHECKPOINT_MAX_BYTES_ENV} is not a positive whole number of bytes; using ${checkpointMaxBytes}`);
+}
+const taskQueue = { checkpointMaxBytes, log };
 const databaseUrl = process.env.DATABASE_URL?.trim();
-const pg = databaseUrl ? postgresStorage({ connectionString: databaseUrl, schema: dbSchema() }) : undefined;
-if (pg)
-    setTaskBackend(pg.taskQueue);
+const pg = databaseUrl ? postgresStorage({ connectionString: databaseUrl, schema: dbSchema(), taskQueue }) : undefined;
+setTaskBackend(pg ? pg.taskQueue : fileTaskBackendWith(taskQueue));
 const backend = getTaskBackend();
 /** A claimed job stays this worker's while it renews; the job timeout bounds a turn. */
 const lease = { workerId: `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`, leaseMs: 60_000 };
@@ -169,7 +187,8 @@ async function drain() {
         ran += 1;
         const started = Date.now();
         const label = job.owner ? `${job.id} (${job.owner})` : job.id;
-        log(`${label} started: ${job.title}`);
+        // The title is the person's words: the log names the job, never its text.
+        log(`${label} started (${(job.instruction ?? job.title).length.toLocaleString()} chars)`);
         // Renew the lease while the job runs, so no other worker takes it back;
         // a renewal that finds the claim gone (the job was cancelled) stops the run.
         const held = job;

package/dist/scripts/doctor.d.ts

@@ -11,7 +11,9 @@
  * removed that runtime). Lists the tools that need an OAuth grant (an
  * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
  * server's own client credentials and whether their variables are set
- * (names only). Closes with the env vars that would
+ * (names only). When any A2A identity or billing variable is set, a
+ * `serving` line names the A2A_AUTH mode and A2A_KEY_MODE and what the
+ * server would refuse to start on. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -20,7 +22,7 @@
  * Usage:
  *   npm run doctor
  *   npm run doctor -- --json          # machine-readable
- *   npm run doctor -- --check         # exit 1 when any syndicate is blocked
+ *   npm run doctor -- --check         # exit 1 on a blocked syndicate, a runtime problem, an unrecognised MODEL_GATEWAY, or an OAuth or credential host problem
  *   npm run doctor -- --matrix        # the provider × capability matrix
  *   npm run doctor -- --fix-namespaces [file…]   # give long-term syndicates a memory_namespace
  *   MELCHIZEDEK_AGENTS_DIR=/path npm run doctor

package/dist/scripts/doctor.js

@@ -11,7 +11,9 @@
  * removed that runtime). Lists the tools that need an OAuth grant (an
  * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
  * server's own client credentials and whether their variables are set
- * (names only). Closes with the env vars that would
+ * (names only). When any A2A identity or billing variable is set, a
+ * `serving` line names the A2A_AUTH mode and A2A_KEY_MODE and what the
+ * server would refuse to start on. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -20,7 +22,7 @@
  * Usage:
  *   npm run doctor
  *   npm run doctor -- --json          # machine-readable
- *   npm run doctor -- --check         # exit 1 when any syndicate is blocked
+ *   npm run doctor -- --check         # exit 1 on a blocked syndicate, a runtime problem, an unrecognised MODEL_GATEWAY, or an OAuth or credential host problem
  *   npm run doctor -- --matrix        # the provider × capability matrix
  *   npm run doctor -- --fix-namespaces [file…]   # give long-term syndicates a memory_namespace
  *   MELCHIZEDEK_AGENTS_DIR=/path npm run doctor
@@ -28,7 +30,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadEnv } from '../lib/loadEnv.js';
-import { renderDoctor, runDoctor } from '../lib/doctor.js';
+import { checkProblems, renderDoctor, runDoctor } from '../lib/doctor.js';
 import { renderCapabilityMatrix } from '../lib/models/capabilities.js';
 import { assignMemoryNamespace, LEGACY_MEMORY_APP_NAME } from '../lib/memory/namespace.js';
 loadEnv();
@@ -91,5 +93,5 @@ if (json) {
 else {
     console.log(renderDoctor(result, { color: !noColor }));
 }
-if (check && (result.counts.blocked > 0 || result.runtime.problem || result.oauth?.problems.length))
+if (check && checkProblems(result).length)
     process.exit(1);

package/dist/scripts/mcp_server.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export interface McpCliArgs {
+    syndicates: string[];
+    agentsDir?: string;
+    http: boolean;
+    host?: string;
+    port?: number;
+    help: boolean;
+}
+/** The bin's flags. Throws, naming the flag, on one it does not know. */
+export declare function parseMcpArgs(argv: string[]): McpCliArgs;
+export declare function startMcpServer(argv?: string[]): Promise<void>;

package/dist/scripts/mcp_server.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+/**
+ * scripts/mcp_server.ts — the `melchizedek-mcp` bin: syndicates as MCP tools
+ * (ADR 0125). Thin: it reads flags and the environment, loads the syndicates,
+ * refuses unsafe binds, and hands everything to lib/mcp/server.ts.
+ *
+ *   claude mcp add melch -- npx melchizedek-mcp
+ *   melchizedek-mcp --syndicate research_desk --syndicate tutor
+ *   melchizedek-mcp --http --port 4100
+ *
+ * Every console line goes to stderr: on stdio, stdout is the protocol.
+ *
+ * Flags:
+ *   --syndicate <id>      serve this syndicate (repeatable; a bare id may also
+ *                         resolve to the shipped examples/ and templates/).
+ *                         Positional ids work too. None: every YAML at the
+ *                         agents directory's root.
+ *   --agents-dir <dir>    the agents directory (MELCHIZEDEK_AGENTS_DIR, else
+ *                         <cwd>/config/agents)
+ *   --http                Streamable HTTP at /mcp instead of stdio
+ *   --host <addr>         HTTP bind (MCP_HOST, default 127.0.0.1)
+ *   --port <n>            HTTP port (MCP_PORT, default 4100)
+ *
+ * Environment (all optional):
+ *   MCP_SERVER_SECRET     bearer every HTTP request presents; required, 32+
+ *                         characters, on a bind beyond loopback
+ *   MCP_ALLOWED_HOSTS     comma list: Host names a non-loopback bind answers to
+ *   MCP_TRUST_PROXY       Express trust proxy (hop count, true/false, subnets)
+ *   MCP_RATE_LIMIT_PER_MINUTE   HTTP requests per minute per IP (240)
+ *   MCP_USER_ID           the scope a stdio client's sessions are stored under (default)
+ *   DATABASE_URL          Postgres for sessions, memory, turn locks, audit, credentials
+ *   A2A_TASK_TIMEOUT_MS, A2A_MAX_CONCURRENT_TASKS, A2A_MAX_CONCURRENT_PER_SCOPE,
+ *   A2A_MAX_CONCURRENT_PER_CALLER, A2A_TURN_LOCK_WAIT_MS, A2A_BUDGETS,
+ *   A2A_SHUTDOWN_GRACE_MS, MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI,
+ *   OAUTH_CALLBACK_IDENTITY, MELCHIZEDEK_OAUTH_HOSTS, MELCHIZEDEK_CREDENTIAL_HOSTS
+ *                         as melchizedek-serve reads them (scripts/a2a_server.ts)
+ */
+import { readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The bin's flags. Throws, naming the flag, on one it does not know. */
+export function parseMcpArgs(argv) {
+    const out = { syndicates: [], http: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const value = () => {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith('--'))
+                throw new Error(`${a} needs a value`);
+            return v;
+        };
+        if (a === '--help' || a === '-h')
+            out.help = true;
+        else if (a === '--http')
+            out.http = true;
+        else if (a === '--stdio')
+            out.http = false;
+        else if (a === '--syndicate')
+            out.syndicates.push(value());
+        else if (a === '--agents-dir')
+            out.agentsDir = value();
+        else if (a === '--host')
+            out.host = value();
+        else if (a === '--port') {
+            const n = Number(value());
+            if (!Number.isInteger(n) || n < 0 || n > 65535)
+                throw new Error('--port must be a port number');
+            out.port = n;
+        }
+        else if (a.startsWith('-'))
+            throw new Error(`Unknown flag ${a} (see --help)`);
+        else
+            out.syndicates.push(a);
+    }
+    return out;
+}
+const HELP = [
+    'Usage: melchizedek-mcp [--syndicate <id>]... [--agents-dir <dir>] [--http [--host <addr>] [--port <n>]]',
+    '',
+    'Serves syndicates as MCP tools: one tool per syndicate ({ message, session_id? }),',
+    'plus melch_resume for a turn that paused (an approval, a question, an authorization).',
+    'stdio by default (Claude Code: claude mcp add melch -- npx melchizedek-mcp);',
+    '--http serves Streamable HTTP at /mcp on 127.0.0.1; a wider --host needs MCP_SERVER_SECRET.',
+    'Environment variables are listed at the top of scripts/mcp_server.ts.',
+].join('\n');
+function envInt(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`${name} must be a non-negative number`);
+    return Math.floor(n);
+}
+function trustProxy() {
+    const raw = process.env.MCP_TRUST_PROXY?.trim();
+    if (!raw)
+        return false;
+    if (/^\d+$/.test(raw))
+        return Number(raw);
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return raw;
+}
+function fatal(message) {
+    console.error(`[MCP] ✗ FATAL: ${message}`);
+    process.exit(1);
+}
+export async function startMcpServer(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseMcpArgs(argv);
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    if (args.help) {
+        console.error(HELP);
+        process.exit(0);
+    }
+    if (args.agentsDir)
+        process.env.MELCHIZEDEK_AGENTS_DIR = path.resolve(args.agentsDir);
+    const { loadEnv, isPlaceholderValue } = await import('../lib/loadEnv.js');
+    loadEnv(import.meta.url);
+    // Sign in with ChatGPT is local only (ADR 0126). Over stdio this bin is one person's process, spawned by
+    // their own MCP client; --http can be reached by others, so it refuses like melchizedek-serve.
+    if (args.http) {
+        const { refuseChatGptSignInOnServedSurface } = await import('../lib/chatgpt/state.js');
+        try {
+            refuseChatGptSignInOnServedSurface('melchizedek-mcp --http');
+        }
+        catch (err) {
+            fatal(err instanceof Error ? err.message : String(err));
+        }
+    }
+    if (process.env.OTEL_CONSOLE_SPANS === undefined)
+        process.env.OTEL_CONSOLE_SPANS = 'false';
+    const { setLogLevel } = await import('../lib/runtime/logging.js');
+    setLogLevel('warn');
+    const log = (m) => console.error(`[MCP] ${m}`);
+    const warn = (m) => console.error(`[MCP] ⚠ ${m}`);
+    const { createMcpServer, mcpBindProblem, mcpHttpApp, serveMcpStdio, toolNameFor } = await import('../lib/mcp/server.js');
+    const { loadSyndicate, nestedLoader } = await import('../lib/loadSyndicate.js');
+    const { syndicateOAuthHostProblems } = await import('../lib/tools/oauthTools.js');
+    const { syndicateCredentialHostProblems } = await import('../lib/tools/credentialUses.js');
+    // ── Transport posture first: a refused bind loads nothing ────────────────
+    const host = args.host ?? (process.env.MCP_HOST?.trim() || '127.0.0.1');
+    const port = args.port ?? envInt('MCP_PORT', 4100);
+    let secret = process.env.MCP_SERVER_SECRET?.trim() || undefined;
+    if (secret && isPlaceholderValue(secret))
+        fatal('MCP_SERVER_SECRET is still a placeholder. Generate one: openssl rand -hex 32');
+    if (args.http) {
+        const problem = mcpBindProblem({ host, ...(secret ? { secret } : {}) });
+        if (problem)
+            fatal(problem);
+    }
+    // ── The syndicates: the exposure ──────────────────────────────────────────
+    const bindings = () => ({
+        current_date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }),
+    });
+    const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+    let files = args.syndicates.map((id) => (id.endsWith('.yaml') || id.endsWith('.yml') ? id : `${id}.yaml`));
+    const named = files.length > 0;
+    if (!named) {
+        try {
+            files = readdirSync(agentsDir)
+                .filter((f) => (f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+                .sort();
+        }
+        catch {
+            files = [];
+        }
+        if (!files.length)
+            fatal(`No syndicates at the root of ${agentsDir}. Name one: melchizedek-mcp --syndicate <id> (a shipped example works: --syndicate tutor).`);
+    }
+    const syndicates = [];
+    for (const file of files) {
+        try {
+            const config = loadSyndicate(file, { bindings: bindings(), shippedFallback: named });
+            // The operator's host allowlists hold here as on the A2A server (ADR 0114, ADR 0122).
+            const nested = nestedLoader(config, (ref) => loadSyndicate(ref, { bindings: bindings() }));
+            const load = (ref) => {
+                try {
+                    return nested(ref);
+                }
+                catch {
+                    return {};
+                }
+            };
+            const problems = [...syndicateOAuthHostProblems([config], { load }), ...syndicateCredentialHostProblems([config], { load })];
+            if (problems.length)
+                throw new Error(`refused by the operator's host allowlists:\n  - ${problems.join('\n  - ')}`);
+            syndicates.push({ id: toolNameFor(path.basename(file)), config });
+        }
+        catch (err) {
+            const why = err?.code === 'ENOENT' ? 'not found' : err instanceof Error ? err.message : String(err);
+            if (named)
+                fatal(`${file}: ${why}`);
+            warn(`Skipped ${file}: ${why.split('\n')[0]}`);
+        }
+    }
+    if (!syndicates.length)
+        fatal('No syndicate loaded.');
+    // ── Storage, budgets, tool credentials: as melchizedek-serve ─────────────
+    const databaseUrl = process.env.DATABASE_URL?.trim() || undefined;
+    let pg;
+    if (databaseUrl) {
+        const { postgresStorage } = await import('../lib/storage/postgres/index.js');
+        const { dbSchema } = await import('../lib/storage/schema.js');
+        pg = postgresStorage({
+            connectionString: databaseUrl,
+            schema: dbSchema(),
+            memory: { apiKey: process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY || '' },
+        });
+        const { compareSchema, schemaBehindMessage, shippedSchemaVersion } = await import('../lib/storage/schemaVersion.js');
+        const check = compareSchema(await pg.schemaVersion(), shippedSchemaVersion());
+        if (check.state === 'behind' && process.env.ALLOW_SCHEMA_MISMATCH?.trim().toLowerCase() !== 'true')
+            fatal(schemaBehindMessage(check));
+    }
+    let policy;
+    const budgetsJson = process.env.A2A_BUDGETS?.trim();
+    if (budgetsJson) {
+        const { budgets, memoryUsageStore, parseBudgets, postgresUsageStore } = await import('../lib/a2a/policy.js');
+        try {
+            policy = budgets(parseBudgets(budgetsJson), { store: pg ? postgresUsageStore(pg.pool) : memoryUsageStore() });
+        }
+        catch (err) {
+            fatal(err instanceof Error ? err.message : String(err));
+        }
+    }
+    const { oauthServerSetup, callbackIdentity } = await import('../lib/a2a/oauthSetup.js');
+    const { postgresCredentialRows } = await import('../lib/storage/postgres/credentialStore.js');
+    let oauth;
+    try {
+        oauth = oauthServerSetup({
+            configs: syndicates.map((s) => s.config),
+            load: (ref) => loadSyndicate(ref),
+            env: process.env,
+            ...(pg ? { rows: postgresCredentialRows(pg.pool), audit: pg.audit } : {}),
+            allowPrivate: process.env.ALLOW_PRIVATE_OPENAPI === 'true' || process.env.ALLOW_PRIVATE_MCP === 'true',
+        });
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    for (const w of oauth.warnings)
+        warn(w);
+    const consent = oauth.toolCredentials?.consent;
+    if (consent && !args.http) {
+        warn('stdio serves no OAuth consent callback: a consent pause completes only where OAUTH_REDIRECT_URI is served by a server sharing this credential store.');
+    }
+    const mcp = createMcpServer({
+        syndicates,
+        ...(pg ? { sessionService: pg.sessionService, turnLock: pg.turnLock, audit: pg.audit } : {}),
+        ...(pg?.memoryService ? { memoryService: pg.memoryService } : {}),
+        taskTimeoutMs: envInt('A2A_TASK_TIMEOUT_MS', 15 * 60 * 1000),
+        maxConcurrentTasks: envInt('A2A_MAX_CONCURRENT_TASKS', 0),
+        maxConcurrentPerScope: envInt('A2A_MAX_CONCURRENT_PER_SCOPE', 4),
+        maxConcurrentPerCaller: envInt('A2A_MAX_CONCURRENT_PER_CALLER', 0),
+        turnLockWaitMs: envInt('A2A_TURN_LOCK_WAIT_MS', 30_000),
+        ...(policy ? { policy } : {}),
+        ...(oauth.toolCredentials ? { toolCredentials: oauth.toolCredentials } : {}),
+        log,
+        warn,
+    });
+    const toolList = syndicates.map((s) => s.id).join(', ');
+    const graceMs = envInt('A2A_SHUTDOWN_GRACE_MS', 25_000);
+    let stopping = false;
+    let closeHttp;
+    const stop = async (why) => {
+        if (stopping)
+            return;
+        stopping = true;
+        log(`${why}: waiting up to ${graceMs} ms for running turns.`);
+        const canceled = await mcp.shutdown(graceMs);
+        if (canceled > 0)
+            warn(`${canceled} turn(s) did not finish in time and were canceled.`);
+        await closeHttp?.().catch(() => { });
+        const { flushTracing } = await import('../lib/observability/tracer.js');
+        await flushTracing().catch(() => { });
+        await pg?.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => void stop('SIGTERM'));
+    process.on('SIGINT', () => void stop('SIGINT'));
+    if (!args.http) {
+        const scope = process.env.MCP_USER_ID?.trim() || 'default';
+        const { HEADER_VALUE_PATTERN } = await import('../lib/a2a/identity.js');
+        if (!HEADER_VALUE_PATTERN.test(scope))
+            fatal('MCP_USER_ID must match [A-Za-z0-9._-]{1,64}');
+        await serveMcpStdio(mcp, { caller: { scopeKey: scope, caller: 'local' } });
+        log(`✓ Serving ${syndicates.length} syndicate tool(s) over stdio: ${toolList}`);
+        process.stdin.on('end', () => void stop('stdin closed'));
+        return;
+    }
+    const allowedHosts = process.env.MCP_ALLOWED_HOSTS?.split(',').map((s) => s.trim()).filter(Boolean);
+    const { consentCallback } = await import('../lib/a2a/app.js');
+    const app = mcpHttpApp(mcp, {
+        host,
+        port,
+        ...(secret ? { secret } : {}),
+        ...(allowedHosts?.length ? { allowedHosts } : {}),
+        trustProxy: trustProxy(),
+        rateLimitPerMinute: envInt('MCP_RATE_LIMIT_PER_MINUTE', 240),
+        ...(consent
+            ? {
+                beforeAuth: (a) => a.get(new URL(consent.redirectUri).pathname, consentCallback(consent, { requireCallerIdentity: callbackIdentity(process.env) === 'required', log, warn })),
+            }
+            : {}),
+        warn,
+    });
+    closeHttp = app.closeSessions;
+    // The secret is not needed past this point.
+    secret = undefined;
+    await new Promise((resolve) => {
+        app.listen(port, host, () => resolve());
+    });
+    log(`✓ Serving ${syndicates.length} syndicate tool(s) at http://${host.includes(':') ? `[${host}]` : host}:${port}/mcp: ${toolList}`);
+    log(`  auth     ${process.env.MCP_SERVER_SECRET?.trim() ? 'bearer MCP_SERVER_SECRET' : 'none (loopback only)'}`);
+    log(`  storage  ${pg ? 'postgres' : 'in-memory (lost on restart)'}`);
+    log(`  oauth    ${oauth.summary}`);
+}
+// Run-as-main guard on the realpath of argv[1] (the bin is a symlink; see a2a_server.ts).
+const invokedAsMain = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+})();
+if (invokedAsMain) {
+    // Before anything else loads: stdout is the stdio protocol channel.
+    console.log = console.error;
+    console.info = console.error;
+    console.debug = console.error;
+    startMcpServer().catch((error) => {
+        console.error(`[MCP] ✗ ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}

package/dist/scripts/setup.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * scripts/setup.ts — the `melchizedek-setup` bin and `npm run setup`.
+ *
+ * The onboarding command: a menu of authentication levels (no key, one
+ * provider, several, a gateway, a cloud platform, per-caller keys, caller
+ * tokens, OAuth tool grants, and an honest entry for subscription sign-ins),
+ * each with a startup guide: the variables to set (names and shapes only),
+ * the doctor command that confirms it, the shipped files that run there and
+ * the first commands to try. The levels and guides live in lib/onboarding.ts;
+ * ONBOARDING.md is generated from the same function.
+ *
+ *   npx melchizedek-setup                     # the menu (interactive terminal)
+ *   npx melchizedek-setup --auto              # detect from the environment, names only
+ *   npx melchizedek-setup --level gateway     # one guide, by id or number
+ *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
+ *   npx melchizedek-setup --list
+ *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *   npx melchizedek-setup --chatgpt-signin    # Sign in with ChatGPT, local only (ADR 0126)
+ *   npx melchizedek-setup --chatgpt-signout | --chatgpt-status
+ *
+ * Never prints a value. `--write-env` never overwrites `.env`, leaves every
+ * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.
+ */
+export declare function main(argv?: string[]): Promise<number>;