melchizedek-agents 1.3.0 → 1.6.0

package/dist/lib/storage/postgres/index.js

@@ -22,12 +22,16 @@ import { postgresCredentialStore } from './credentialStore.js';
 import { searchPathOption } from '../schema.js';
 import { POSTGRES_RLS_QUERY, evaluatePostgresRls } from '../rlsStatus.js';
 import { postgresAuditSink } from '../../observability/audit.js';
+import { attachLedger } from '../../observability/tracer.js';
+import { postgresLedgerClient } from '../../observability/supabaseSpanExporter.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 export { PostgresSessionService } from './sessionService.js';
 export { PostgresTaskStore } from './taskStore.js';
 export { postgresMemoryStore } from './memoryStore.js';
 export { postgresCredentialRows, postgresCredentialStore } from './credentialStore.js';
+// The single-process turn lock, for an embedded database (`turnLock` below).
+export { inProcessTurnLock } from '../../a2a/turnLock.js';
 /**
  * A pool emits 'error' when an idle connection dies (a database restart, a
  * failover, an administrator's terminate); unhandled, that event crashes the
@@ -69,7 +73,7 @@ export function postgresStorage(options) {
         ...(options.pool ? options.pool.options : { connectionString: options.connectionString, ...options.poolConfig }),
         max: options.lockPoolMax ?? 20,
     }), 'turn-lock pool'));
-    const turnLock = async (key, { waitMs, signal }) => {
+    const advisoryTurnLock = async (key, { waitMs, signal }) => {
         const lockId = advisoryLockId(key);
         const client = await locks().connect();
         const deadline = Date.now() + Math.max(0, waitMs);
@@ -105,6 +109,10 @@ export function postgresStorage(options) {
         };
         return release;
     };
+    const turnLock = options.turnLock ?? advisoryTurnLock;
+    const detachLedger = options.ledger
+        ? attachLedger(postgresLedgerClient(pool), options.ledger === true ? {} : options.ledger)
+        : undefined;
     const audit = postgresAuditSink(pool);
     const credentials = options.credentials ? postgresCredentialStore(pool, { ...options.credentials, audit }) : undefined;
     return {
@@ -160,6 +168,7 @@ export function postgresStorage(options) {
             return counts;
         },
         async close() {
+            await detachLedger?.();
             if (lockPool)
                 await lockPool.end();
             if (owned)

package/dist/lib/syndicateSchema.d.ts

@@ -28,6 +28,8 @@ export declare const REASONING_LEVELS: readonly ['none', 'low', 'medium', 'high'
 export declare const OUTPUT_MIMES: readonly ['application/json', 'text/plain'];
 export declare const TOOL_CHOICE_MODES: readonly ['auto', 'none', 'required'];
 export declare const SKILL_SCRIPT_MODES: readonly ['none', 'local'];
+/** An `env` key that names a credential: such a value belongs in pass_env, never in the YAML (ADR 0132). */
+export declare const SECRET_ENV_KEY: RegExp;
 /** An `mcp_servers` entry's name: lowercase, bounded, one character class (no backtracking). */
 export declare const MCP_SERVER_NAME: RegExp;
 export declare const agentSchema: z.ZodObject<{
@@ -150,7 +152,12 @@ export declare const agentSchema: z.ZodObject<{
     }>>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        url: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        pass_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
         tools: z.ZodArray<z.ZodString>;
         auth: z.ZodOptional<z.ZodObject<{
             oauth2: z.ZodObject<{
@@ -359,7 +366,12 @@ export declare const subagentSchema: z.ZodObject<{
     }>>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        url: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        pass_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
         tools: z.ZodArray<z.ZodString>;
         auth: z.ZodOptional<z.ZodObject<{
             oauth2: z.ZodObject<{
@@ -572,7 +584,12 @@ export declare const syndicateSchema: z.ZodObject<{
         }>>;
         mcp_servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
-            url: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+            command: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            pass_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
             tools: z.ZodArray<z.ZodString>;
             auth: z.ZodOptional<z.ZodObject<{
                 oauth2: z.ZodObject<{
@@ -775,7 +792,12 @@ export declare const syndicateSchema: z.ZodObject<{
         }>>;
         mcp_servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
-            url: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+            command: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            pass_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
             tools: z.ZodArray<z.ZodString>;
             auth: z.ZodOptional<z.ZodObject<{
                 oauth2: z.ZodObject<{

package/dist/lib/syndicateSchema.js

@@ -272,6 +272,10 @@ const oauth2Auth = z
 const mcpTransport = z
     .enum(MCP_TRANSPORTS)
     .describe('How the MCP server is reached: auto (the default) tries Streamable HTTP and falls back to the legacy SSE transport on the spec\'s signal; streamable_http or sse use that one only (ADR 0124).');
+/** An environment variable name, as a stdio MCP entry's env and pass_env keys must be. */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+/** An `env` key that names a credential: such a value belongs in pass_env, never in the YAML (ADR 0132). */
+export const SECRET_ENV_KEY = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)/i;
 /** An `mcp_servers` entry's name: lowercase, bounded, one character class (no backtracking). */
 export const MCP_SERVER_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
 const mcpServerEntry = z
@@ -280,7 +284,23 @@ const mcpServerEntry = z
         .string()
         .regex(MCP_SERVER_NAME, 'lowercase letters, digits, _ and -, starting with a letter (at most 64)')
         .describe('A short name for the server, unique on this agent: logs and errors name it.'),
-    url: z.string().url().describe('The MCP server\'s URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard.'),
+    url: z.string().url().optional().describe('The MCP server\'s URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard. Give url or command, not both.'),
+    command: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A local MCP server to start and speak to over stdio (ADR 0132), instead of url: the program to run. It runs only when the operator lists this exact value in MELCHIZEDEK_STDIO_MCP. One process per distinct command, args, env and cwd, kept for the life of the engine.'),
+    args: z.array(z.string()).max(64).optional().describe('The command\'s arguments (stdio only).'),
+    env: z
+        .record(z.string().regex(ENV_NAME, 'an environment variable name'), z.string())
+        .optional()
+        .describe('Non-secret variables set for the command (stdio only). A credential is never written here: name it in pass_env.'),
+    pass_env: z
+        .array(z.string().regex(ENV_NAME, 'an environment variable name'))
+        .max(32)
+        .optional()
+        .describe('Variables copied by name from the engine\'s environment into the command\'s (stdio only); the command sees no other variable of the engine\'s beyond a minimal default set (PATH, HOME, …). A name that is unset fails the compile.'),
+    cwd: z.string().min(1).optional().describe('The command\'s working directory (stdio only); relative to the YAML file\'s directory.'),
     tools: z
         .array(z.string().min(1))
         .min(1)
@@ -759,6 +779,30 @@ function mcpServersProblems(agent, path) {
         if (!isObj(entry))
             return;
         const name = typeof entry.name === 'string' ? entry.name : `#${i}`;
+        // url or command (ADR 0132), and each one's own keys only.
+        const at = (key) => [...path, 'mcp_servers', i, key];
+        if (entry.url === undefined && entry.command === undefined)
+            out.push({ path: at('url'), message: 'give url (a remote server) or command (a local stdio server) (ADR 0132)' });
+        if (entry.url !== undefined && entry.command !== undefined)
+            out.push({ path: at('command'), message: 'url and command cannot both be given: one entry is one server (ADR 0132)' });
+        if (entry.command !== undefined) {
+            for (const key of ['transport', 'auth']) {
+                if (entry[key] !== undefined)
+                    out.push({ path: at(key), message: `${key} is how a url is reached; a command entry speaks stdio and takes no ${key} (ADR 0132)` });
+            }
+            if (isObj(entry.env)) {
+                for (const key of Object.keys(entry.env)) {
+                    if (SECRET_ENV_KEY.test(key))
+                        out.push({ path: [...at('env'), key], message: `'${key}' looks like a credential: never write its value in the YAML; list the name in pass_env instead (ADR 0132)` });
+                }
+            }
+        }
+        else {
+            for (const key of ['args', 'env', 'pass_env', 'cwd']) {
+                if (entry[key] !== undefined)
+                    out.push({ path: at(key), message: `${key} configures a command entry; this entry has a url (ADR 0132)` });
+            }
+        }
         if (typeof entry.name === 'string') {
             if (names.has(entry.name))
                 out.push({ path: [...path, 'mcp_servers', i, 'name'], message: `'${entry.name}' names mcp_servers entry ${names.get(entry.name)} too; each server's name is unique on the agent` });
@@ -1153,12 +1197,30 @@ function workflowProblems(raw, subs) {
         if (typeof agent.name === 'string' && mapped.has(agent.name) && isObj(agent.skills) && agent.skills.scripts === 'local') {
             out.push({ path: [...path, 'skills', 'scripts'], message: 'skill scripts (an approval pause) are not supported on an agent a map node runs: a map item cannot pause the walk' });
         }
+        // An authorization_code grant pauses for consent (ADR 0128): allowed on a node, not on a map item.
+        if (typeof agent.name === 'string' && mapped.has(agent.name)) {
+            for (const where of authorizationCodeGrants(agent)) {
+                out.push({ path: [...path, ...where], message: 'an authorization_code grant (a consent pause) is not supported on an agent a map node runs: a map item cannot pause the walk' });
+            }
+        }
         if (typeof agent.a2a_agent_url === 'string') {
             out.push({ path: [...path, 'a2a_agent_url'], message: 'a remote agent cannot be a workflow node yet' });
         }
     }
     return out;
 }
+/** Where an agent declares an authorization_code grant (mcp_auth, mcp_servers[].auth, openapi[].auth), by its path below the agent. */
+function authorizationCodeGrants(agent) {
+    const out = [];
+    const isCode = (auth) => isObj(auth) && isObj(auth.oauth2) && auth.oauth2.grant === 'authorization_code';
+    if (isCode(agent.mcp_auth))
+        out.push(['mcp_auth', 'oauth2', 'grant']);
+    if (Array.isArray(agent.mcp_servers))
+        agent.mcp_servers.forEach((e, i) => isObj(e) && isCode(e.auth) && out.push(['mcp_servers', i, 'auth', 'oauth2', 'grant']));
+    if (Array.isArray(agent.openapi))
+        agent.openapi.forEach((e, i) => isObj(e) && isCode(e.auth) && out.push(['openapi', i, 'auth', 'oauth2', 'grant']));
+    return out;
+}
 // ── Public API ───────────────────────────────────────────────────────────────
 /**
  * Thrown by validateSyndicateConfig. `problems` holds one `<file>: <path> —

package/dist/lib/tools/generateImageTool.js

@@ -16,9 +16,11 @@
  */
 import { GoogleGenAI } from '@google/genai';
 import { writeFileSync, mkdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { z } from 'zod';
 import { asTool, defineTool } from './toolContract.js';
+import { outputsDir } from '../paths.js';
+import { credentialValue } from '../models/credentialSource.js';
 const IMAGE_MODEL = 'gemini-3.1-flash-image-preview';
 export const generateImageContract = defineTool({
     name: 'generate_image',
@@ -32,7 +34,7 @@ export const generateImageContract = defineTool({
     }),
     execute: async ({ prompt, style, aspect_ratio, color_palette }) => {
         console.log("[ImageTool] Starting image generation execution...");
-        const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+        const apiKey = credentialValue('GEMINI_API_KEY') || credentialValue('GOOGLE_GENAI_API_KEY');
         if (!apiKey) {
             const err = new Error('Gemini API Key is not configured (neither GEMINI_API_KEY nor GOOGLE_GENAI_API_KEY was found in environment).');
             console.error(`[ImageTool ERROR] Initialization failed: ${err.message}`);
@@ -74,10 +76,8 @@ export const generateImageContract = defineTool({
                     if (inlineData?.data) {
                         const { mimeType, data } = inlineData;
                         const ext = mimeType?.split('/')[1] ?? 'png';
-                        // OUTPUTS_DIR env overrides the cwd default (package consumers).
-                        const outputDir = process.env.OUTPUTS_DIR
-                            ? resolve(process.env.OUTPUTS_DIR)
-                            : join(process.cwd(), 'outputs');
+                        // OUTPUTS_DIR, else MELCHIZEDEK_DATA_DIR/outputs, else ./outputs (lib/paths.ts).
+                        const outputDir = outputsDir();
                         console.log(`[ImageTool] Found inline image data. MimeType: ${mimeType}, Data Length: ${data.length} chars.`);
                         console.log(`[ImageTool] Ensuring output directory exists: ${outputDir}`);
                         mkdirSync(outputDir, { recursive: true });

package/dist/lib/tools/inspectImageTool.d.ts

@@ -17,6 +17,8 @@
  *   SpecAuditor subagent, which sees spec + inventory but never the image.
  */
 import { z } from 'zod';
+/** A path generate_image reported, inside the outputs directory: relative paths are read there, a leading `outputs/` dropped. */
+export declare function resolveOutputPath(imagePath: string): string;
 export declare const inspectImageContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     image_path: z.ZodString;
 }, z.core.$strip>, string>;

package/dist/lib/tools/inspectImageTool.js

@@ -18,9 +18,11 @@
  */
 import { GoogleGenAI } from '@google/genai';
 import { readFileSync } from 'node:fs';
-import { resolve, extname, sep } from 'node:path';
+import { isAbsolute, resolve, extname, sep } from 'node:path';
 import { z } from 'zod';
 import { asTool, defineTool } from './toolContract.js';
+import { outputsDir } from '../paths.js';
+import { credentialValue } from '../models/credentialSource.js';
 const VISION_MODEL = 'gemini-3.8-flash';
 const INVENTORY_PROTOCOL = `You are a blind visual inventory agent. You know NOTHING about what this image was supposed to be, who requested it, or why. Enumerate ONLY what is actually present:
 
@@ -37,6 +39,13 @@ RULES:
 - ZERO guesses about intent or purpose.
 - If something is genuinely ambiguous, write "uncertain:" and describe what is visible.
 Return a plain, factual, numbered inventory.`;
+/** A path generate_image reported, inside the outputs directory: relative paths are read there, a leading `outputs/` dropped. */
+export function resolveOutputPath(imagePath) {
+    if (isAbsolute(imagePath))
+        return resolve(imagePath);
+    const rel = imagePath.replace(/^(\.\/)?outputs[\\/]/, '');
+    return resolve(outputsDir(), rel);
+}
 export const inspectImageContract = defineTool({
     name: 'inspect_image',
     description: 'Performs a BLIND visual inventory of a previously saved image (subjects with exact counts, ' +
@@ -47,17 +56,15 @@ export const inspectImageContract = defineTool({
     }),
     execute: async ({ image_path }) => {
         console.log(`[InspectTool] Blind inventory requested (path ${image_path.length} chars).`);
-        // Confine reads to the outputs/ directory — this tool inventories
-        // generated artifacts, not the filesystem. OUTPUTS_DIR env overrides
-        // the cwd default (must match generateImageTool's).
-        const outputsDir = process.env.OUTPUTS_DIR
-            ? resolve(process.env.OUTPUTS_DIR)
-            : resolve(process.cwd(), 'outputs');
-        const fullPath = resolve(process.cwd(), image_path);
-        if (!fullPath.startsWith(outputsDir + sep)) {
+        // Confine reads to the outputs directory — this tool inventories
+        // generated artifacts, not the filesystem. generate_image reports
+        // `outputs/<file>` wherever that directory is (lib/paths.ts), so a
+        // relative path is read inside it, with that prefix dropped.
+        const fullPath = resolveOutputPath(image_path);
+        if (!fullPath.startsWith(outputsDir() + sep)) {
             throw new Error('inspect_image only reads files under outputs/');
         }
-        const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+        const apiKey = credentialValue('GEMINI_API_KEY') || credentialValue('GOOGLE_GENAI_API_KEY');
         if (!apiKey) {
             throw new Error('Gemini API Key is not configured (neither GEMINI_API_KEY nor GOOGLE_GENAI_API_KEY was found in environment).');
         }

package/dist/lib/tools/mcpToolFactory.d.ts

@@ -34,6 +34,30 @@ export type { McpTransportKind };
  * the credential, which another transport would not change.
  */
 export declare function isSseFallbackSignal(error: unknown): boolean;
+/** A local MCP server: the program, its arguments, its environment and its directory. */
+export interface StdioMcpSpec {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    pass_env?: string[];
+    cwd?: string;
+}
+/**
+ * Whether the operator allows `command` to run as an MCP server: its exact
+ * value is one of MELCHIZEDEK_STDIO_MCP's comma-separated entries. Unset
+ * means none. Read at each connect, so an embedding application can set it
+ * as its user approves servers.
+ */
+export declare function stdioCommandAllowed(command: string, env?: NodeJS.ProcessEnv): boolean;
+/** The command's environment: the SDK's minimal default set, then `pass_env` by name (the credential source first, then the environment), then `env`. Throws naming an unset variable, never a value. */
+export declare function stdioEnvironment(spec: StdioMcpSpec, label: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * The tools a local stdio MCP server offers, as own Tools (ADR 0132). A
+ * command the operator has not allowed (MELCHIZEDEK_STDIO_MCP) or an unset
+ * pass_env variable fails the compile (thrown); a server that cannot be
+ * started or listed is logged and yields no tools, as a remote one does.
+ */
+export declare function loadStdioMcpTools(name: string, spec: StdioMcpSpec): Promise<Tool[]>;
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
  * the process (its tools are called for the life of the compiled agent), and
@@ -69,7 +93,16 @@ export interface McpToolOptions {
 export interface McpServerConfig {
     /** A short name for the server, unique on the agent: logs and errors name it. */
     name: string;
-    url: string;
+    /** A remote server. Exactly one of url and command is set (ADR 0132). */
+    url?: string;
+    /** A local server, started and spoken to over stdio (ADR 0132). */
+    command?: string;
+    args?: string[];
+    /** Non-secret variables for the command. */
+    env?: Record<string, string>;
+    /** Variables copied by name from the engine's environment. */
+    pass_env?: string[];
+    cwd?: string;
     /** The server's tools this agent may use, by name. Required: names across servers are refused on collision at load. */
     tools: string[];
     auth?: {

package/dist/lib/tools/mcpToolFactory.js

@@ -5,8 +5,9 @@
  * An agent's `mcp_server_url:` (or each entry of `mcp_servers:`, ADR 0124)
  * connects here over Streamable HTTP, falling back to the legacy SSE
  * transport when the server answers the initialize POST with the spec's
- * fallback signal (a 4xx other than 401/403), or over the transport the YAML
- * names. Every tool the server lists becomes an own Tool whose declaration is the server's
+ * fallback signal (a 4xx other than 401/403), or with a 401 when no OAuth
+ * grant is configured for the connection, or over the transport the YAML
+ * names; the transport that worked is remembered per URL. Every tool the server lists becomes an own Tool whose declaration is the server's
  * description (bounded) and input schema, and whose execute calls the
  * server and returns its text (bounded). loadMcpTools returns them;
  * createMcpTools is the name the compiler calls.
@@ -24,6 +25,8 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { credentialValue } from '../models/credentialSource.js';
 import { toContractJsonSchema } from '../models/schemaNormalize.js';
 import { checkHost } from '../net/addressGuard.js';
 import { fetchWithRedirectPolicy } from '../net/redirects.js';
@@ -134,14 +137,56 @@ export function isSseFallbackSignal(error) {
     const code = error.code;
     return typeof code === 'number' && code >= 400 && code < 500 && code !== 401 && code !== 403;
 }
+/**
+ * True when a Streamable HTTP connect failed with a 401: the server refused
+ * the request's credential (or its absence). Where the connection carries no
+ * OAuth grant, an SSE-only server behind a bearer can answer the initialize
+ * POST to its stream URL that way, so connectMcp tries SSE once (ADR 0124's
+ * note of 2026-10-11).
+ */
+const isUnauthorized = (error) => error instanceof StreamableHTTPError && error.code === 401;
+/** Server URLs whose transport `auto` has learned, at most; the least recently used is forgotten first. */
+const MAX_REMEMBERED_MCP_TRANSPORTS = 256;
+/**
+ * The transport that last connected to each server URL under `auto`, for the
+ * life of the process, so a later connection skips the probe. It holds a URL
+ * and a transport name, never a credential.
+ */
+const rememberedTransports = new Map();
+function rememberTransport(href, kind) {
+    rememberedTransports.delete(href);
+    rememberedTransports.set(href, kind);
+    while (rememberedTransports.size > MAX_REMEMBERED_MCP_TRANSPORTS) {
+        const oldest = rememberedTransports.keys().next().value;
+        rememberedTransports.delete(oldest);
+    }
+}
+const STREAMABLE_PREFIX = 'Streamable HTTP error: ';
+/** `message` with the credential header's value, and its token, cut out. */
+function withoutCredential(message, headers) {
+    const auth = headers.Authorization;
+    if (!auth)
+        return message;
+    const token = auth.startsWith('Bearer ') ? auth.slice('Bearer '.length) : undefined;
+    return redact(redact(message, auth), token);
+}
 /**
  * A client connected to `url` over `kind`, every request through `fetchFn`
  * (the redirect rule, and the credential when there is one). A transport
  * that fails to connect is closed before the error leaves, so nothing keeps
- * reconnecting; with `auto`, a failed Streamable HTTP attempt carrying the
- * fallback signal is closed and the SSE transport tried once.
+ * reconnecting. With `auto`:
+ *   - a transport remembered for this URL is tried first; if it fails, it is
+ *     forgotten and the probe runs;
+ *   - the probe posts over Streamable HTTP. On the spec's fallback signal, or
+ *     on a 401 when the connection has no OAuth grant (`MCP_BEARER_TOKENS`
+ *     or no credential), it closes that attempt and tries SSE once with the
+ *     same fetch and headers. When SSE fails after a 401, the 401 is what is
+ *     thrown, naming both attempts and no credential. A 401 under an OAuth
+ *     grant (its consent and discovery path, ADR 0112 and 0124), a 403, a 5xx
+ *     and a network failure do not fall back;
+ *   - the transport that connected is remembered for this URL.
  */
-async function connectMcp(url, kind, fetchFn, headers = {}) {
+async function connectMcp(url, kind, fetchFn, headers = {}, options = {}) {
     const attempt = async (which) => {
         const requestInit = Object.keys(headers).length ? { requestInit: { headers } } : {};
         const transport = which === 'sse' ? new SSEClientTransport(url, { ...requestInit, fetch: fetchFn }) : new StreamableHTTPClientTransport(url, { ...requestInit, fetch: fetchFn });
@@ -160,14 +205,154 @@ async function connectMcp(url, kind, fetchFn, headers = {}) {
         return attempt('sse');
     if (kind === 'streamable_http')
         return attempt('streamable_http');
+    const href = url.href;
+    const known = rememberedTransports.get(href);
+    if (known) {
+        try {
+            const conn = await attempt(known);
+            rememberTransport(href, known);
+            return conn;
+        }
+        catch {
+            // The server may have changed: forget it and probe as if new.
+            rememberedTransports.delete(href);
+        }
+    }
+    let conn;
     try {
-        return await attempt('streamable_http');
+        conn = await attempt('streamable_http');
     }
     catch (error) {
-        if (!isSseFallbackSignal(error))
+        if (isSseFallbackSignal(error)) {
+            conn = await attempt('sse');
+        }
+        else if (isUnauthorized(error) && !options.oauth) {
+            try {
+                conn = await attempt('sse');
+            }
+            catch (sseError) {
+                const original = error.message.startsWith(STREAMABLE_PREFIX) ? error.message.slice(STREAMABLE_PREFIX.length) : error.message;
+                const sseMessage = sseError instanceof Error ? sseError.message : String(sseError);
+                throw new StreamableHTTPError(401, withoutCredential(`${original} (Streamable HTTP answered 401; the SSE transport was tried once after it and failed too: ${sseMessage})`, headers));
+            }
+        }
+        else {
             throw error;
-        return attempt('sse');
+        }
+    }
+    rememberTransport(href, conn.kind);
+    return conn;
+}
+/**
+ * Whether the operator allows `command` to run as an MCP server: its exact
+ * value is one of MELCHIZEDEK_STDIO_MCP's comma-separated entries. Unset
+ * means none. Read at each connect, so an embedding application can set it
+ * as its user approves servers.
+ */
+export function stdioCommandAllowed(command, env = process.env) {
+    const list = (env.MELCHIZEDEK_STDIO_MCP ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    return list.includes(command);
+}
+/** The command's environment: the SDK's minimal default set, then `pass_env` by name (the credential source first, then the environment), then `env`. Throws naming an unset variable, never a value. */
+export function stdioEnvironment(spec, label, env = process.env) {
+    const out = { ...getDefaultEnvironment() };
+    for (const name of spec.pass_env ?? []) {
+        // Through the credential source (ADR 0133): a key held in an application's keychain reaches the server by name.
+        const value = credentialValue(name, env);
+        if (value === undefined || value === '')
+            throw new Error(`${label}: pass_env names ${name}, which is not set in the engine's environment`);
+        out[name] = value;
+    }
+    return { ...out, ...(spec.env ?? {}) };
+}
+/** Live stdio connections by spec: one process per distinct spec, for the life of the engine. */
+const stdioConnections = new Map();
+/** The last stderr a stdio server wrote, for a failure message. */
+const STDERR_TAIL = 1_000;
+function stdioKey(spec) {
+    return JSON.stringify([spec.command, spec.args ?? [], Object.entries(spec.env ?? {}).sort(), [...(spec.pass_env ?? [])].sort(), spec.cwd ?? null]);
+}
+async function connectStdio(spec, label) {
+    const key = stdioKey(spec);
+    const live = stdioConnections.get(key);
+    if (live)
+        return live;
+    const env = stdioEnvironment(spec, label);
+    const attempt = (async () => {
+        const transport = new StdioClientTransport({ command: spec.command, args: spec.args ?? [], env, ...(spec.cwd ? { cwd: spec.cwd } : {}), stderr: 'pipe' });
+        let tail = '';
+        transport.stderr?.on('data', (chunk) => {
+            tail = (tail + chunk.toString('utf-8')).slice(-STDERR_TAIL);
+        });
+        const client = new Client({ name: 'melchizedek-a2a-client', version: '1.0.0' }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            await transport.close().catch(() => { });
+            // The tail reaches a log line: every value pass_env copied in is cut out of it.
+            const secrets = (spec.pass_env ?? []).map((n) => env[n]).filter((v) => !!v);
+            const clean = secrets.reduce((text, v) => text.split(v).join('[redacted]'), tail.trim());
+            const said = clean ? ` (stderr: ${clean.split('\n').slice(-3).join(' | ')})` : '';
+            throw new Error(`${error instanceof Error ? error.message : String(error)}${said}`);
+        }
+        // A server that exits is started again by the next compile that needs it.
+        transport.onclose = () => {
+            stdioConnections.delete(key);
+            openTransports.delete(transport);
+        };
+        openTransports.add(transport);
+        return client;
+    })();
+    stdioConnections.set(key, attempt);
+    attempt.catch(() => stdioConnections.delete(key));
+    return attempt;
+}
+/**
+ * The tools a local stdio MCP server offers, as own Tools (ADR 0132). A
+ * command the operator has not allowed (MELCHIZEDEK_STDIO_MCP) or an unset
+ * pass_env variable fails the compile (thrown); a server that cannot be
+ * started or listed is logged and yields no tools, as a remote one does.
+ */
+export async function loadStdioMcpTools(name, spec) {
+    const label = `mcp_servers ${name}`;
+    if (!stdioCommandAllowed(spec.command)) {
+        throw new Error(`${label}: the command '${spec.command}' is not allowed to run; the operator lists it in MELCHIZEDEK_STDIO_MCP (ADR 0132)`);
     }
+    let client;
+    try {
+        client = await connectStdio(spec, label);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(label))
+            throw error; // pass_env: a configuration error
+        console.warn(`[MCP] Failed to start or connect to ${label} (stdio: ${spec.command})`, error instanceof Error ? error.message : error);
+        return [];
+    }
+    try {
+        const { tools } = await client.listTools();
+        return tools.map((tool) => listedTool(client, tool));
+    }
+    catch (error) {
+        console.warn(`[MCP] Failed to list tools from ${label} (stdio: ${spec.command})`, error instanceof Error ? error.message : error);
+        return [];
+    }
+}
+/** One listed tool as an own Tool on `client`'s connection: the same declaration and result handling for every transport. */
+function listedTool(client, tool) {
+    const declaration = declarationOf(tool);
+    return {
+        name: tool.name,
+        declaration: () => declaration,
+        execute: async (input) => {
+            try {
+                return resultText(await client.callTool({ name: tool.name, arguments: input }));
+            }
+            catch (error) {
+                return `[MCP ERROR] Tool ${tool.name} failed: ${error instanceof ToolCredentialError ? error.message : error?.message}`;
+            }
+        },
+    };
 }
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
@@ -180,6 +365,8 @@ export async function closeMcpConnections() {
     openTransports.clear();
     for (const pool of userPools)
         pool.clear();
+    stdioConnections.clear();
+    rememberedTransports.clear();
     await Promise.all(all.map((t) => t.close().catch(() => { })));
 }
 /**
@@ -265,28 +452,14 @@ export async function loadMcpTools(mcpServerUrl, options = {}) {
     try {
         const url = await assertSafeMcpUrl(mcpServerUrl);
         conn = tokenSource
-            ? await connectMcp(url, kind, bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)))
+            ? await connectMcp(url, kind, bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)), {}, { oauth: true })
             : await connectMcp(url, kind, mcpFetch, mcpAuthHeaders(url));
         const client = conn.client;
         // Fetch available tools from the MCP server
         const toolsResponse = await client.listTools();
-        return toolsResponse.tools.map((tool) => {
-            // MCP servers describe tools in standard lowercase JSON Schema, which
-            // is the contract's dialect; mcpToolParameters derives the parameters.
-            const declaration = declarationOf(tool);
-            return {
-                name: tool.name,
-                declaration: () => declaration,
-                execute: async (input) => {
-                    try {
-                        return resultText(await client.callTool({ name: tool.name, arguments: input }));
-                    }
-                    catch (error) {
-                        return `[MCP ERROR] Tool ${tool.name} failed: ${error instanceof ToolCredentialError ? error.message : error?.message}`;
-                    }
-                },
-            };
-        });
+        // MCP servers describe tools in standard lowercase JSON Schema, which is
+        // the contract's dialect; mcpToolParameters derives the parameters.
+        return toolsResponse.tools.map((tool) => listedTool(client, tool));
     }
     catch (error) {
         // A token that cannot be had is reported by kind; the rest as before.
@@ -335,7 +508,7 @@ function userGrantMcpTools(mcpServerUrl, oauth2, names, kind) {
         conn.holder = holder;
         conn.ready = (async () => {
             const url = await assertSafeMcpUrl(mcpServerUrl);
-            const { client, transport } = await connectMcp(url, kind, bearerFetch(oauth2, async () => holder.token));
+            const { client, transport } = await connectMcp(url, kind, bearerFetch(oauth2, async () => holder.token), {}, { oauth: true });
             conn.transport = transport;
             if (!listed) {
                 const offered = await client.listTools();