melchizedek-agents 1.3.1 → 1.5.0

package/dist/lib/runtime/syndicateTurn.js

@@ -70,7 +70,7 @@ import { traceAgentRun } from '../observability/tracer.js';
 import { ProjectedSessionService, renderTranscriptDigest } from '../session/transcript.js';
 import { approvalDecisionIn, describeApproval, interruptedTurnStart, pendingApproval } from './approvals.js';
 import { pendingQuestion, questionAnswerPart, questionFrom, turnStartOfCall } from './questions.js';
-import { deepestPause, delegatedPauses, nestedWorkflowPause, routePause } from './native/interrupts.js';
+import { deepestPause, delegatedPauses, nestedWorkflowPause, routePause, walkConsents } from './native/interrupts.js';
 import { consentPinnedTo, entrySession } from './native/delegate.js';
 import { workflowPauseEvent } from '../workflow/pause.js';
 import { INPUT_REQUEST } from '../workflowConfig.js';
@@ -485,6 +485,15 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         ev.log?.(`⏸ Authorization needed: ${(pending.path ?? [pending.agent]).join(' → ')} → ${pending.provider}`);
         return finish();
     };
+    /** Whether the grant a consent request waits for is stored (an expired or unreadable one is not). */
+    const grantStored = async (open) => {
+        try {
+            return !!open.provider && !!(await credentialStore?.get({ appName: credentialApp, userId, provider: open.provider }));
+        }
+        catch {
+            return false;
+        }
+    };
     let granting;
     // A call waiting for a grant inside a delegated subagent (ADR 0118): the grant's answer is stored here, and the open call carries it down.
     let grantingBelow;
@@ -508,14 +517,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
                 result.error = { code: 'CONSENT_UNAVAILABLE', message: `A call waits for a ${open.provider} authorization, but this turn has no credential store.` };
                 return finish();
             }
-            let granted = false;
-            try {
-                granted = !!open.provider && !!(await credentialStore.get({ appName: credentialApp, userId, provider: open.provider }));
-            }
-            catch {
-                // Expired or unreadable: not granted. The request stands.
-            }
-            if (!granted)
+            if (!(await grantStored(open)))
                 return consentPause(open);
             // The route's own turn carries the grant's answer down to its call; the message goes to it as it came.
             if (routeWaits)
@@ -527,6 +529,28 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
             ev.log?.(`✓ Authorization granted: ${(open.path ?? [open.agent]).join(' → ')} → ${open.provider}`);
         }
     }
+    // A walk waiting for grants (ADR 0128): a node's own consent request, or one a node raised again from below it. Once every
+    // grant is stored, the message becomes their answers and the walk resumes those nodes; until then it repeats the first
+    // request still missing and stores nothing, as at the top.
+    if (!decision && isWorkflowSyndicate(config)) {
+        const waiting = await walkConsents(pauseKey, existing?.events ?? []);
+        if (waiting.length > 0) {
+            if (!credentialStore) {
+                result.status = 'failed';
+                result.error = { code: 'CONSENT_UNAVAILABLE', message: `A call waits for a ${waiting[0].provider} authorization, but this turn has no credential store.` };
+                return finish();
+            }
+            for (const open of waiting)
+                if (!(await grantStored(open)))
+                    return consentPause(open);
+            granting = waiting[0];
+            parts = waiting.map((open) => credentialResponsePart(open.id, open.provider));
+            for (const open of waiting)
+                ev.log?.(`✓ Authorization granted: ${(open.path ?? [open.agent]).join(' → ')} → ${open.provider}`);
+        }
+    }
+    /** The parts a paused workflow route's walk resumes on once its grant is stored (ADR 0128): the grant's answer to its credential request. */
+    const routeGrant = consentRoute?.consent ? [credentialResponsePart(consentRoute.consent.id, consentRoute.consent.provider)] : undefined;
     // ── Questions (lib/runtime/questions.ts) ───────────────────────────────────
     // While an agent's `ask_user` call is open, a plain-text message is its
     // answer: it becomes that call's response, and the agent that asked
@@ -651,6 +675,8 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
                 memory: nativeMemory(opts.memoryService),
                 ...(selfCorrection ? { selfCorrection } : {}),
                 ...(credentialStore ? { credentials: credentialStore } : {}),
+                // The consent step, its flows bound to the app the grants are read under, wherever the walk's session is filed (ADR 0128).
+                ...(consentStep ? { consent: consentPinnedTo(consentStep, credentialApp) } : {}),
                 ...(compileOpts.log ? { log: compileOpts.log } : {}),
             });
         }
@@ -747,7 +773,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
             throw new Error(`Session not found: ${sessionId} (appName=${appName}, userId=${userId})`);
         const kept = (state) => Object.fromEntries(Object.entries(state ?? {}).filter(([k]) => !k.startsWith(TEMP_STATE_PREFIX)));
         // Filed under the agent path (ADR 0119), else continued under the route's name alone where ADR 0106 filed it.
-        const resumingWalk = resumingRoute !== undefined || routeAnswer !== undefined;
+        const resumingWalk = resumingRoute !== undefined || routeAnswer !== undefined || consentRoute !== undefined;
         const child = await entrySession(store, { appName, userId, sessionId, events: shared.events }, route, 'route', kept(shared.state), resumingWalk);
         const childKey = { appName: child.appName, userId, sessionId };
         const before = new Map(Object.entries(kept(child.state)).map(([k, v]) => [k, JSON.stringify(v)]));
@@ -760,7 +786,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         };
         let walked;
         try {
-            walked = await runAgent({ agent, sid: sessionId, appName: child.appName, userParts: routeAnswer ?? parts, sessions: sessionService, stage: 'dispatch', route: resolution, publishToolStatus: true, errorPolicy: 'collect' });
+            walked = await runAgent({ agent, sid: sessionId, appName: child.appName, userParts: routeAnswer ?? routeGrant ?? parts, sessions: sessionService, stage: 'dispatch', route: resolution, publishToolStatus: true, errorPolicy: 'collect' });
         }
         catch (err) {
             const last = control.stopReason ? undefined : err;
@@ -1087,6 +1113,10 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         const pending = pendingApproval(after?.events ?? []);
         if (pending)
             return pause(await deepen(pending));
+        // A node waiting for a grant (ADR 0128): its own request, or one from below it, with the path from the node down.
+        const [consent] = await walkConsents(pauseKey, after?.events ?? []);
+        if (consent)
+            return consentPause(consent);
         if (answer.inputRequests.length)
             return question(await deepen(answer.inputRequests[answer.inputRequests.length - 1]));
         result.text = answer.text;

package/dist/lib/storage/postgres/index.d.ts

@@ -19,6 +19,7 @@ import { PostgresSessionService } from './sessionService.ts';
 import { PostgresTaskStore } from './taskStore.ts';
 import type { CredentialStoreOptions } from '../../tools/credentialStore.ts';
 import type { CredentialStore } from '../../tools/auth.ts';
+import type { PayloadPolicy } from '../../observability/supabaseSpanExporter.ts';
 import type { AuditSink } from '../../observability/audit.ts';
 import type { RlsHardeningStatus } from '../rlsStatus.ts';
 import type { TaskBackend, TaskBackendOptions } from '../../tools/taskTools.ts';
@@ -28,6 +29,8 @@ export { PostgresSessionService } from './sessionService.ts';
 export { PostgresTaskStore } from './taskStore.ts';
 export { postgresMemoryStore } from './memoryStore.ts';
 export { postgresCredentialRows, postgresCredentialStore } from './credentialStore.ts';
+export { inProcessTurnLock } from '../../a2a/turnLock.ts';
+export type { TurnLock } from '../../a2a/turnLock.ts';
 export interface PostgresStorageOptions {
     /** A Postgres URL. Ignored when `pool` is given. */
     connectionString?: string;
@@ -54,6 +57,28 @@ export interface PostgresStorageOptions {
     };
     /** Owner of an A2A call, for the task store. Default: the SDK's user scope. */
     taskOwner?: PostgresTaskStoreOptions['ownerResolver'];
+    /**
+     * The turn lock to use instead of the advisory lock below. The advisory
+     * lock is what makes several instances on one database take turns; it
+     * needs a database that gives each connection its own session. Embedded
+     * Postgres (PGlite behind pglite-socket) runs every connection in ONE
+     * session, where an advisory lock is re-entrant and so excludes nothing:
+     * there, one process owns the database, and `inProcessTurnLock()`
+     * (exported here) is the correct lock. When given, no turn-lock
+     * pool is opened.
+     */
+    turnLock?: TurnLock;
+    /**
+     * Write the telemetry ledger (adk_turns, adk_telemetry, adk_payloads) to
+     * this database (ADR 0131): the rows the Supabase sink writes, with the
+     * same payload policy (TELEMETRY_PAYLOADS, or `policy`) and redaction.
+     * Needs db/telemetry.sql applied. `close()` flushes and detaches it.
+     * Default off.
+     */
+    ledger?: boolean | {
+        policy?: PayloadPolicy;
+        deadLetterFile?: string;
+    };
     /**
      * Connections reserved for turn locks: each running turn holds one for its
      * length, apart from the main pool so a long turn never starves queries.

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?: {