melchizedek-agents 1.2.0 → 1.3.1

package/dist/lib/chatgpt/state.js

@@ -0,0 +1,145 @@
+/**
+ * lib/chatgpt/state.ts — where a Sign in with ChatGPT credential lives, whether
+ * it is the OpenAI path, and the served-surface refusal (ADR 0126).
+ *
+ * WHY a leaf (node:fs, node:os, node:path only):
+ *   The gateway's transport rule (lib/models/gateway.ts), the doctor, the
+ *   resolver and every served bin ask the same two questions — is a sign-in
+ *   stored, and does it carry OpenAI ids here — so the answer lives in one
+ *   module with no adapter or SDK in its import graph.
+ *
+ * LOCAL ONLY:
+ *   OpenAI's plan-usage flow is for open-source apps that run on the user's
+ *   own machine (developers.openai.com/siwc/token-sharing-open-source). The
+ *   A2A server, the worker and any other served surface call
+ *   `refuseChatGptSignInOnServedSurface` at startup and stop while the
+ *   sign-in would carry OpenAI ids; `markServedSurface` also makes the
+ *   adapter refuse at call time, so a surface that skipped the startup check
+ *   still never spends a person's ChatGPT plan on someone else's request.
+ *
+ * WHAT IT NEVER DOES: return or print a token. The status carries presence,
+ * 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';
+/** 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). */
+export const CHATGPT_SIGNIN_ENV = 'MELCHIZEDEK_CHATGPT_SIGNIN';
+/** The scope that lets the token use the person's ChatGPT plan. */
+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');
+}
+/** The git work tree a path sits inside, if any (an ancestor holding `.git`). */
+export function insideGitWorkTree(file) {
+    let dir = dirname(resolve(file));
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Whether a parsed value has the stored shape. */
+export function isStoredSignIn(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    return o.version === 1 && typeof o.issuer === 'string' && typeof o.hostId === 'string';
+}
+/**
+ * Read the credential file: undefined when absent; throws, naming the file
+ * and never its content, when it is readable by others or malformed.
+ */
+export function readStoredSignIn(file) {
+    if (!existsSync(file))
+        return undefined;
+    if (process.platform !== 'win32' && (statSync(file).mode & 0o077) !== 0) {
+        throw new Error(`${file} is readable by other users; run \`chmod 600 ${file}\` (or sign in again).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        throw new Error(`${file} is not a Sign in with ChatGPT credential file; delete it and sign in again.`);
+    }
+    if (!isStoredSignIn(parsed))
+        throw new Error(`${file} is not a Sign in with ChatGPT credential file; delete it and sign in again.`);
+    return parsed;
+}
+/** Signed in: a refresh token, and the plan scope granted. */
+export function isSignedIn(s) {
+    return !!s?.refreshToken && !!s.accessToken && (s.scopes ?? []).includes(PLAN_SCOPE);
+}
+/** The stored sign-in's status under this environment. */
+export function chatGptSignInStatus(env = process.env) {
+    const file = signInFile(env);
+    const enabled = env[CHATGPT_SIGNIN_ENV]?.trim().toLowerCase() !== 'off';
+    const present = existsSync(file);
+    if (!present)
+        return { enabled, file, present, signedIn: false };
+    try {
+        const s = readStoredSignIn(file);
+        const signedIn = isSignedIn(s);
+        return { enabled, file, present, signedIn, ...(signedIn && s?.expiresAt ? { expiresAt: s.expiresAt } : {}) };
+    }
+    catch (err) {
+        return { enabled, file, present, signedIn: false, problem: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Whether OpenAI ids would run on the sign-in here: it is enabled and signed
+ * in, no OPENAI_API_KEY is set, and OpenAI is on its own API (no
+ * OPENAI_PLATFORM other than direct, no OPENAI_BASE_URL proxy, which must
+ * never receive the token).
+ */
+export function chatGptSignInRoutesOpenAi(env = process.env) {
+    if (env.OPENAI_API_KEY?.trim())
+        return false;
+    const platform = env.OPENAI_PLATFORM?.trim().toLowerCase();
+    if (platform && platform !== 'direct')
+        return false;
+    if (env.OPENAI_BASE_URL?.trim())
+        return false;
+    const status = chatGptSignInStatus(env);
+    return status.enabled && status.signedIn;
+}
+// ── Local only ───────────────────────────────────────────────────────────────
+let served;
+/** Mark this process a served surface: the sign-in adapter refuses every call from here on. */
+export function markServedSurface(surface) {
+    served ??= surface;
+}
+/** The served surface this process was marked as, if any. */
+export function servedSurface() {
+    return served;
+}
+/** Test seam: forget the mark. */
+export function resetServedSurfaceForTests() {
+    served = undefined;
+}
+/** The message a served surface stops with. */
+export function servedSurfaceMessage(surface, env = process.env) {
+    return (`${surface} will not start: Sign in with ChatGPT is local only, and it is the OpenAI path here ` +
+        `(a sign-in is stored at ${signInFile(env)} and OPENAI_API_KEY is not set). ` +
+        `A served surface answers other people, and a ChatGPT plan pays only for its owner's own use on their own machine. ` +
+        `Set OPENAI_API_KEY (or Azure OpenAI), or set ${CHATGPT_SIGNIN_ENV}=off for this process, ` +
+        `or sign out with \`melchizedek-setup --chatgpt-signout\`.`);
+}
+/**
+ * Called by every served surface at startup: marks the process served, and
+ * throws when the sign-in would carry OpenAI ids here. The A2A app, the A2A
+ * server bin and the worker call it; a new served surface calls it too.
+ */
+export function refuseChatGptSignInOnServedSurface(surface, env = process.env) {
+    markServedSurface(surface);
+    if (chatGptSignInRoutesOpenAi(env))
+        throw new Error(servedSurfaceMessage(surface, env));
+}

package/dist/lib/chatgpt/store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * lib/chatgpt/store.ts — writing the Sign in with ChatGPT credential file and
+ * serializing its refreshes (ADR 0126).
+ *
+ * The file is the person's own: mode 600 in a mode-700 directory, outside any
+ * git work tree, replaced atomically (a new mode-600 file renamed over the
+ * old one). OpenAI's refresh tokens rotate, so two processes must not refresh
+ * the same session at once (developers.openai.com/siwc/token-sharing-open-source/
+ * profiles-and-sessions): a lock file beside the credential serializes them.
+ */
+import type { StoredSignIn } from './state.ts';
+/** Write the credential file: mode 600, atomically, never inside a git work tree. */
+export declare function writeStoredSignIn(file: string, value: StoredSignIn): void;
+/** The stored sign-in with its tokens removed; the host id and the issued client id stay (OpenAI asks apps to reuse them). */
+export declare function withoutTokens(s: StoredSignIn): StoredSignIn;
+/** Remove the tokens from the file, keeping the registration. */
+export declare function clearTokens(file: string): void;
+/**
+ * Run `fn` holding the credential's lock file (created exclusively). A lock
+ * older than a minute is a crashed holder's and is taken over.
+ */
+export declare function withSignInLock<T>(file: string, fn: () => Promise<T>, opts?: {
+    waitMs?: number;
+}): Promise<T>;

package/dist/lib/chatgpt/store.js

@@ -0,0 +1,94 @@
+/**
+ * lib/chatgpt/store.ts — writing the Sign in with ChatGPT credential file and
+ * serializing its refreshes (ADR 0126).
+ *
+ * The file is the person's own: mode 600 in a mode-700 directory, outside any
+ * git work tree, replaced atomically (a new mode-600 file renamed over the
+ * old one). OpenAI's refresh tokens rotate, so two processes must not refresh
+ * the same session at once (developers.openai.com/siwc/token-sharing-open-source/
+ * profiles-and-sessions): a lock file beside the credential serializes them.
+ */
+import { randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { insideGitWorkTree, readStoredSignIn } from './state.js';
+/** Write the credential file: mode 600, atomically, never inside a git work tree. */
+export function writeStoredSignIn(file, value) {
+    const repo = insideGitWorkTree(file);
+    if (repo) {
+        throw new Error(`refusing to store a ChatGPT sign-in inside the git work tree ${repo}; set MELCHIZEDEK_CHATGPT_SIGNIN_FILE to a path outside it.`);
+    }
+    const dir = dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    const fd = openSync(tmp, 'wx', 0o600);
+    try {
+        writeSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        if (process.platform !== 'win32')
+            chmodSync(tmp, 0o600);
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+/** The stored sign-in with its tokens removed; the host id and the issued client id stay (OpenAI asks apps to reuse them). */
+export function withoutTokens(s) {
+    const { accessToken: _a, refreshToken: _r, expiresAt: _e, earliestRefreshAt: _n, scopes: _s, ...kept } = s;
+    return { ...kept, savedAt: new Date().toISOString() };
+}
+/** Remove the tokens from the file, keeping the registration. */
+export function clearTokens(file) {
+    const s = readStoredSignIn(file);
+    if (s)
+        writeStoredSignIn(file, withoutTokens(s));
+}
+const LOCK_STALE_MS = 60_000;
+const LOCK_WAIT_MS = 20_000;
+/**
+ * Run `fn` holding the credential's lock file (created exclusively). A lock
+ * older than a minute is a crashed holder's and is taken over.
+ */
+export async function withSignInLock(file, fn, opts = {}) {
+    const lock = `${file}.lock`;
+    const dir = dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + (opts.waitMs ?? LOCK_WAIT_MS);
+    for (;;) {
+        try {
+            closeSync(openSync(lock, 'wx', 0o600));
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            try {
+                if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                    rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`another process holds ${lock}; try again, or delete it if no melchizedek process is running.`);
+            await delay(100);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        rmSync(lock, { force: true });
+    }
+}

package/dist/lib/compile.js

@@ -145,10 +145,10 @@ export function examplesTool(examples) {
     const tool = examplesInstructionTool(examples);
     return tool ? [tool] : [];
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed, mcpAuth) {
-    const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
+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.
-    for (const entry of openapi ?? []) {
+    for (const entry of agent.openapi ?? []) {
         const built = await buildOpenApiTools(entry);
         opts.log?.(`openapi · ${relative(process.cwd(), entry.spec) || entry.spec}: ${built.map((t) => t.name).join(', ') || '(no operations)'}`);
         for (const t of built) {
@@ -157,28 +157,43 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, example
             tools.push(t);
         }
     }
-    if (mcpServerUrl) {
-        opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        // An authorization_code server lists nothing at startup: its tools are the mcp_tools names, each on its user's own connection (ADR 0112).
-        const offered = await createMcpTools(mcpServerUrl, { ...(mcpAllowed ? { tools: mcpAllowed } : {}), ...(mcpAuth?.oauth2 ? { oauth2: mcpAuth.oauth2 } : {}) });
-        // mcp_tools: only the named tools are exposed (a server's list is its
-        // own to change); a name the server does not offer is reported, and a
-        // gate on it fails the compile in gateTools.
-        const allowed = mcpAllowed ? new Set(mcpAllowed) : undefined;
-        const mcpTools = allowed ? offered.filter((t) => allowed.has(t.name)) : offered;
-        if (allowed) {
-            const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
-            if (missing.length)
-                opts.log?.(`MCP ${mcpServerUrl} does not offer ${missing.map((n) => `'${n}'`).join(', ')} (mcp_tools)`);
-            const hidden = offered.length - mcpTools.length;
-            if (hidden)
-                opts.log?.(`MCP ${mcpServerUrl}: ${hidden} tool(s) not in mcp_tools are not exposed`);
-        }
-        for (const mcpTool of mcpTools) {
+    /** One server's tools, narrowed to the names the YAML allows (a server's list is its own to change). */
+    const offeredBy = async (label, url, allowedNames, oauth2, transport) => {
+        opts.log?.(`Loading MCP tools: ${label}`);
+        // An authorization_code server lists nothing at startup: its tools are the allowed names, each on its user's own connection (ADR 0112).
+        const offered = await createMcpTools(url, { ...(allowedNames ? { tools: allowedNames } : {}), ...(oauth2 ? { oauth2 } : {}), ...(transport ? { transport } : {}) });
+        if (!allowedNames)
+            return offered;
+        // A name the server does not offer is reported, and a gate on it fails the compile in gateTools.
+        const allowed = new Set(allowedNames);
+        const kept = offered.filter((t) => allowed.has(t.name));
+        const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
+        if (missing.length)
+            opts.log?.(`MCP ${label} does not offer ${missing.map((n) => `'${n}'`).join(', ')}`);
+        const hidden = offered.length - kept.length;
+        if (hidden)
+            opts.log?.(`MCP ${label}: ${hidden} tool(s) not named for this agent are not exposed`);
+        return kept;
+    };
+    if (agent.mcp_server_url) {
+        // The single-server form: a name the agent already has keeps the agent's tool.
+        for (const mcpTool of await offeredBy(agent.mcp_server_url, agent.mcp_server_url, agent.mcp_tools, agent.mcp_auth?.oauth2, agent.mcp_transport)) {
             if (!tools.some((t) => t.name === mcpTool.name))
                 tools.push(mcpTool);
         }
     }
+    // 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)));
+    for (const [i, offered] of servers.entries()) {
+        const server = agent.mcp_servers[i];
+        for (const mcpTool of offered) {
+            if (tools.some((t) => t?.name === mcpTool.name))
+                throw new Error(`mcp_servers ${server.name}: tool '${mcpTool.name}' collides with another of this agent's tools (ADR 0124)`);
+            tools.push(mcpTool);
+        }
+    }
     return tools;
 }
 /**
@@ -413,7 +428,7 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
     }
     // YAML v2 (ADR 0115): the engine form, for a config built in code (a loaded one already is).
     const agent = toEngineAgent(subCfg);
-    const gated = gateTools(await resolveAgentTools(agent.tools, agent.mcp_server_url, opts, agent.openapi, agent.examples, agent.mcp_tools, agent.mcp_auth), agent.require_approval, agent.name);
+    const gated = gateTools(await resolveAgentTools(agent, opts), agent.require_approval, agent.name);
     const model = resolveAgentModel(agent.model, opts);
     // model_overrides for the provider the agent runs on, before the skills index is appended.
     const { instruction, tools } = await withSkills(instructionFor(agent, model.modelId), gated, agent.skills, agent.name, opts);
@@ -452,9 +467,9 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
     const orchestrator = toEngineAgent(config.orchestrator); // YAML v2 (ADR 0115), for a config built in code
     const name = overrideName || orchestrator.name;
     // The orchestrator's own tools resolve as a subagent's do: registry
-    // names, OpenAPI operations, and the MCP server's tools (narrowed by
-    // mcp_tools, under its mcp_auth grant), so a one-agent syndicate can reach an MCP server.
-    const own = gateTools(await resolveAgentTools(orchestrator.tools, orchestrator.mcp_server_url, opts, orchestrator.openapi, orchestrator.examples, orchestrator.mcp_tools, orchestrator.mcp_auth), orchestrator.require_approval, name);
+    // names, OpenAPI operations, and the MCP servers' tools (narrowed by
+    // mcp_tools or each mcp_servers entry's tools, under its grant), so a one-agent syndicate can reach an MCP server.
+    const own = gateTools(await resolveAgentTools(orchestrator, opts), orchestrator.require_approval, name);
     const model = resolveAgentModel(orchestrator.model, opts);
     // The skills toolset goes last, after the delegations and the agent's own tools; the
     // skills index goes after the instruction with its model_overrides entry applied.

package/dist/lib/dispatch.js

@@ -73,6 +73,8 @@ function matchSubagent(candidate, subagents) {
         return undefined;
     return subagents.find(sub => norm(sub.name) === target);
 }
+/** What a subagent name can look like: one token, linear to test. */
+const ROUTE_SHAPED = /^[A-Za-z0-9_.-]{1,64}$/;
 /**
  * Turn the router's raw output into a route that definitely exists.
  *
@@ -108,7 +110,8 @@ export function resolveRoute(rawOutput, config) {
         parsed = JSON.parse(unfence(rawOutput));
     }
     catch {
-        return defaultResolution(`router output was not JSON: ${rawOutput.trim().slice(0, 80)}`);
+        // The reason reaches the server log: the size, never the text (the router can echo the person).
+        return defaultResolution(`router output was not JSON (${rawOutput.trim().length} chars)`);
     }
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return defaultResolution('router output was not a JSON object');
@@ -120,7 +123,8 @@ export function resolveRoute(rawOutput, config) {
     }
     const matched = matchSubagent(rawRoute, subagents);
     if (!matched) {
-        return defaultResolution(`router chose unknown route '${rawRoute}'`);
+        // A route-shaped value is named; anything else is model text and is only measured.
+        return defaultResolution(ROUTE_SHAPED.test(rawRoute) ? `router chose unknown route '${rawRoute}'` : `router chose an unknown route (${rawRoute.length} chars)`);
     }
     const rawReason = record[reasonKey];
     return {

package/dist/lib/doctor.d.ts

@@ -167,6 +167,25 @@ export interface DoctorResult {
     providers: ProviderPath[];
     /** How the A2A server would authenticate and bill, when any of its variables is set. */
     serving?: DoctorServing;
+    /** A stored Sign in with ChatGPT credential (ADR 0126), when one is present or its variables are set. */
+    chatgpt?: DoctorChatGpt;
+}
+/**
+ * A Sign in with ChatGPT credential (ADR 0126): where it is, whether it is
+ * signed in and carries OpenAI ids here, and what stops it. Never a token.
+ */
+export interface DoctorChatGpt {
+    file: string;
+    /** False when MELCHIZEDEK_CHATGPT_SIGNIN=off. */
+    enabled: boolean;
+    present: boolean;
+    signedIn: boolean;
+    /** OpenAI ids run on it here (no OPENAI_API_KEY, OpenAI on its own API). */
+    routesOpenAi: boolean;
+    /** Epoch milliseconds the stored access token expires (it refreshes on use). */
+    expiresAt?: number;
+    /** A served configuration on it, or a file that cannot be used. `--check` fails on any. */
+    problems: string[];
 }
 /**
  * How one provider would be reached under this environment (the doctor's
@@ -183,6 +202,8 @@ export interface ProviderPath {
     /** `local` for Ollama; a cloud platform (vertex, bedrock, azure) or `direct` otherwise. */
     platform: Platform | 'local';
     keyEnv: string | null;
+    /** `chatgpt-signin` when a stored Sign in with ChatGPT funds the provider instead of its key (ADR 0126). */
+    credential?: 'chatgpt-signin';
 }
 /**
  * The A2A server's identity and billing settings (scripts/a2a_server.ts),
@@ -263,11 +284,21 @@ export declare function runDoctor(options?: {
     agentsDir?: string;
     scripts?: Record<string, string>;
 }): DoctorResult;
+/**
+ * The Sign in with ChatGPT line (ADR 0126), when a credential file is present
+ * or one of its variables is set. `served`: a serving variable is set, so
+ * this configuration is meant for melchizedek-serve, which refuses to start
+ * while the sign-in is the OpenAI path.
+ */
+export declare function chatGptReport(served: boolean, env?: NodeJS.ProcessEnv): DoctorChatGpt | undefined;
 /**
  * Why `melchizedek-doctor --check` exits non-zero, one line each; empty when
- * it passes. A blocked syndicate, a runtime problem, the OAuth setup's and
- * the credential allowlist's problems, and each grant whose hosts the OAuth
- * host allowlist refuses (ADR 0114). Names and hosts only, never a value.
+ * it passes. A blocked syndicate, a runtime problem, a `MODEL_GATEWAY` that
+ * names no gateway (named with the accepted values only: the value may be a
+ * key pasted into the wrong variable), the OAuth setup's and the credential
+ * allowlist's problems, and each grant whose hosts the OAuth host allowlist
+ * refuses (ADR 0114), and the Sign in with ChatGPT line's problems (ADR 0126).
+ * Names and hosts only, never a value.
  */
 export declare function checkProblems(result: DoctorResult): string[];
 export declare function renderDoctor(result: DoctorResult, opts?: {

package/dist/lib/doctor.js

@@ -34,6 +34,7 @@ import { credentialSource, endpointFromEnv, endpointLabel, endpointProblems, PLA
 import { GATEWAY_ENV, GATEWAY_KEY_ENV, GATEWAYS, gatewayConfig, gatewayProblem, gatewayUsable, } from './models/gateway.js';
 import { PROVIDERS } from './models/providerMap.js';
 import { describeRuntime } from './runtime/runtimeFlag.js';
+import { CHATGPT_SIGNIN_ENV, CHATGPT_SIGNIN_FILE_ENV, chatGptSignInRoutesOpenAi, chatGptSignInStatus } from './chatgpt/state.js';
 import { agentOAuthGrants, oauthEnvNames } from './tools/oauthTools.js';
 import { grantHostProblems, OAUTH_REDIRECT_URI_ENV, oauthEnvProblems } from './a2a/oauthSetup.js';
 import { CREDENTIAL_KEY_ENV } from './tools/credentialCipher.js';
@@ -41,6 +42,8 @@ import { OAUTH_HOSTS_ENV } from './tools/oauthHosts.js';
 import { CREDENTIAL_HOSTS_ENV, credentialHosts } from './tools/credentialHosts.js';
 import { syndicateCredentialUses } from './tools/credentialUses.js';
 import { credentialHostEnvProblems, unboundCredentialWarning } from './a2a/oauthSetup.js';
+/** The `gateway.id` the doctor reports when `MODEL_GATEWAY` names no known gateway; the value itself is never kept. */
+const UNRECOGNISED_GATEWAY = 'unrecognised';
 function resolvable(module) {
     try {
         createRequire(import.meta.url).resolve(module);
@@ -115,6 +118,7 @@ export function providerPaths() {
             ...(r.gateway ? { gateway: r.gateway } : {}),
             platform: p === 'ollama' ? 'local' : (r.platform ?? 'direct'),
             keyEnv: r.keyEnv,
+            ...(p === 'openai' && r.funded && r.transport === 'direct' && chatGptSignInRoutesOpenAi() ? { credential: 'chatgpt-signin' } : {}),
         };
     });
 }
@@ -484,7 +488,7 @@ export function runDoctor(options = {}) {
     const gateway = rawGateway
         ? {
             // An unrecognised value is never echoed: it may be a key pasted into the wrong variable.
-            id: cfg?.gateway.id ?? 'unrecognised',
+            id: cfg?.gateway.id ?? UNRECOGNISED_GATEWAY,
             label: cfg?.gateway.label ?? 'an unrecognised gateway',
             usable: gatewayUsable(),
             ...(gatewayProblem() ? { problem: gatewayProblem() } : {}),
@@ -523,6 +527,7 @@ export function runDoctor(options = {}) {
         credentials = { set: credentialSet, envs, ...(warning ? { warning } : {}), problems };
     }
     const serving = servingReport();
+    const chatgpt = chatGptReport(!!serving);
     return {
         agentsDir,
         runtime: runtimeReport(),
@@ -535,6 +540,34 @@ export function runDoctor(options = {}) {
         ...(credentials ? { credentials } : {}),
         providers: providerPaths(),
         ...(serving ? { serving } : {}),
+        ...(chatgpt ? { chatgpt } : {}),
+    };
+}
+/**
+ * The Sign in with ChatGPT line (ADR 0126), when a credential file is present
+ * or one of its variables is set. `served`: a serving variable is set, so
+ * this configuration is meant for melchizedek-serve, which refuses to start
+ * while the sign-in is the OpenAI path.
+ */
+export function chatGptReport(served, env = process.env) {
+    const status = chatGptSignInStatus(env);
+    if (!status.present && !env[CHATGPT_SIGNIN_FILE_ENV]?.trim() && !env[CHATGPT_SIGNIN_ENV]?.trim())
+        return undefined;
+    const routesOpenAi = chatGptSignInRoutesOpenAi(env);
+    const problems = [];
+    if (status.problem)
+        problems.push(status.problem);
+    if (served && routesOpenAi) {
+        problems.push(`Sign in with ChatGPT is local only, and it is the OpenAI path in this served configuration: melchizedek-serve and melchizedek-worker refuse to start. Set OPENAI_API_KEY (or Azure OpenAI), or ${CHATGPT_SIGNIN_ENV}=off for the served process.`);
+    }
+    return {
+        file: status.file,
+        enabled: status.enabled,
+        present: status.present,
+        signedIn: status.signedIn,
+        routesOpenAi,
+        ...(status.expiresAt ? { expiresAt: status.expiresAt } : {}),
+        problems,
     };
 }
 // ── Rendering ────────────────────────────────────────────────────────────────
@@ -558,9 +591,12 @@ const PROBE_ID = {
 };
 /**
  * Why `melchizedek-doctor --check` exits non-zero, one line each; empty when
- * it passes. A blocked syndicate, a runtime problem, the OAuth setup's and
- * the credential allowlist's problems, and each grant whose hosts the OAuth
- * host allowlist refuses (ADR 0114). Names and hosts only, never a value.
+ * it passes. A blocked syndicate, a runtime problem, a `MODEL_GATEWAY` that
+ * names no gateway (named with the accepted values only: the value may be a
+ * key pasted into the wrong variable), the OAuth setup's and the credential
+ * allowlist's problems, and each grant whose hosts the OAuth host allowlist
+ * refuses (ADR 0114), and the Sign in with ChatGPT line's problems (ADR 0126).
+ * Names and hosts only, never a value.
  */
 export function checkProblems(result) {
     const problems = [];
@@ -568,10 +604,15 @@ export function checkProblems(result) {
         problems.push(`${result.counts.blocked} syndicate(s) blocked`);
     if (result.runtime.problem)
         problems.push(result.runtime.problem);
+    if (result.gateway?.id === UNRECOGNISED_GATEWAY) {
+        problems.push(`gateway: ${GATEWAY_ENV} is set to an unrecognised value (not shown); it must be one of: ${Object.keys(GATEWAYS).join(', ')}`);
+    }
     for (const p of result.oauth?.problems ?? [])
         problems.push(`oauth: ${p}`);
     for (const p of result.credentials?.problems ?? [])
         problems.push(`credentials: ${p}`);
+    for (const p of result.chatgpt?.problems ?? [])
+        problems.push(`chatgpt: ${p}`);
     for (const s of result.syndicates) {
         for (const g of s.grants ?? [])
             for (const p of g.hostProblems ?? [])
@@ -607,7 +648,7 @@ export function renderDoctor(result, opts = {}) {
     // xAI's key beside Moonshot).
     const providerBits = (result.providers ?? providerPaths()).map((r) => {
         const mark = !r.funded ? `${c.red}✗${c.reset}` : r.transport === 'gateway' ? `${c.yellow}◇${c.reset}` : `${c.green}✓${c.reset}`;
-        const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : r.platform === 'local' ? `${c.dim}local${c.reset}` : `${c.dim}${r.platform}${c.reset}`;
+        const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : r.platform === 'local' ? `${c.dim}local${c.reset}` : r.credential === 'chatgpt-signin' ? `${c.dim}ChatGPT sign-in, local only${c.reset}` : `${c.dim}${r.platform}${c.reset}`;
         return `${mark} ${r.label} ${how}`;
     });
     lines.push('providers   ' + providerBits.join('   '));
@@ -632,6 +673,23 @@ export function renderDoctor(result, opts = {}) {
         for (const p of sv.problems)
             lines.push(`            ${c.red}✗ ${p}${c.reset}`);
     }
+    if (result.chatgpt) {
+        // Presence and the file's path, never a token (ADR 0126).
+        const g = result.chatgpt;
+        const mark = g.problems.length ? `${c.red}✗${c.reset}` : g.routesOpenAi ? `${c.green}✓${c.reset}` : `${c.dim}·${c.reset}`;
+        const state = !g.enabled
+            ? `${CHATGPT_SIGNIN_ENV}=off, ignored`
+            : !g.present
+                ? 'not signed in'
+                : !g.signedIn
+                    ? 'signed out (run melchizedek-setup --chatgpt-signin)'
+                    : g.routesOpenAi
+                        ? 'signed in · carries OpenAI ids · local only'
+                        : 'signed in · not used (OPENAI_API_KEY or another OpenAI endpoint wins)';
+        lines.push(`chatgpt     ${mark} ${state} ${c.dim}· ${g.file}${c.reset}`);
+        for (const p of g.problems)
+            lines.push(`            ${c.red}✗ ${p}${c.reset}`);
+    }
     if (result.oauth) {
         // Names only: which variables are set, never their values (ADR 0114).
         const set = Object.entries(result.oauth.set).map(([name, on]) => `${name} ${on ? 'set' : 'unset'}`).join(' · ');

package/dist/lib/loadSyndicate.d.ts

@@ -3,6 +3,8 @@ export type { DispatchConfig } from './dispatch.ts';
 import type { SkillsConfig } from './tools/skillToolset.ts';
 import type { OpenApiConfig } from './tools/openapiTools.ts';
 import type { McpAuthConfig } from './tools/oauthTools.ts';
+import type { McpTransportKind } from './tools/mcpTransports.ts';
+import type { McpServerConfig } from './tools/mcpToolFactory.ts';
 import type { ContextConfig, ExampleConfig } from './compile.ts';
 export type { OpenApiConfig } from './tools/openapiTools.ts';
 export type { SkillsConfig } from './tools/skillToolset.ts';
@@ -153,6 +155,10 @@ export interface AgentYamlConfig {
     mcp_tools?: string[];
     /** The OAuth grant the MCP server takes (ADR 0112): each user's, or the server's own. */
     mcp_auth?: McpAuthConfig;
+    /** How mcp_server_url is reached: auto (the default), streamable_http or sse (ADR 0124). */
+    mcp_transport?: McpTransportKind;
+    /** Several MCP servers, each with its tools, grant and transport (ADR 0124). Not with mcp_server_url. */
+    mcp_servers?: McpServerConfig[];
     /** Answers when `model` fails provider-side, or its provider's circuit is open (ADR 0044). */
     fallback_model?: string;
     /**