@gigaai/newton 0.3.0 → 0.4.1

package/dist/executor.js

@@ -1,11 +1,62 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { cpus } from "node:os";
-import { resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { AcpAgentSession } from "./acp.js";
-import { agentCallKey, loadResumeCache, RunJournal } from "./journal.js";
+import { readSkipRequests, writeStatus } from "./control.js";
+import { agentCallKey, loadResumeCache, loadResumeCalls, RunJournal } from "./journal.js";
+import { resolveMcpServers } from "./mcp.js";
+import { checkCompile, createRealm } from "./sandbox.js";
 import { balancedSlice, extractJson, INVALID, structuredOutputInstruction, structuredOutputRetryPrompt, validateAgainstSchema, } from "./schema.js";
-const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
-const SCRIPT_PARAMS = ["agent", "parallel", "pipeline", "phase", "log", "args", "budget", "Date", "Math"];
+import { createWorktree, finishWorktree } from "./worktree.js";
+const SCRIPT_PARAMS = ["agent", "parallel", "pipeline", "phase", "log", "args", "budget", "workflow"];
+const AGENT_MAX_ATTEMPTS = 3;
+const AGENT_RETRY_BASE_MS = 2_000;
+/**
+ * Failures worth a fresh attempt: provider 5xx/overload/rate-limit responses
+ * and dropped connections. Deterministic failures (auth, missing binaries,
+ * bad model ids, structured-output exhaustion) return null without retrying.
+ */
+const TRANSIENT_AGENT_ERROR = new RegExp([
+    "\\b(?:429|500|502|503|504|529)\\b",
+    "overloaded",
+    "rate.?limit",
+    "too many requests",
+    "internal server error",
+    "service unavailable",
+    "bad gateway",
+    "gateway timeout",
+    "econn(?:reset|refused|aborted)",
+    "etimedout",
+    "epipe",
+    "eai_again",
+    "socket hang.?up",
+    "connection (?:reset|refused|closed|error)",
+    "fetch failed",
+    "network error",
+    "stream (?:closed|disconnected)",
+].join("|"), "i");
+function errorMessage(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "message" in error &&
+        typeof error.message === "string"
+        ? error.message
+        : String(error);
+}
+function isPlainObject(value) {
+    if (Object.prototype.toString.call(value) !== "[object Object]")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || Object.getPrototypeOf(proto) === null;
+}
+function validateConfig(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value) || Object.values(value).some((entry) => typeof entry !== "string")) {
+        throw new Error("agent() config takes an object of configId → string value");
+    }
+    return value;
+}
 export function loadWorkflow(file) {
     const absolute = resolve(file);
     const source = readFileSync(absolute, "utf8");
@@ -33,33 +84,8 @@ export function loadWorkflow(file) {
 }
 /** Compile without running — catches syntax errors and non-literal meta. */
 export function compileWorkflow(workflow) {
-    new AsyncFunction(...SCRIPT_PARAMS, workflow.body);
+    checkCompile(SCRIPT_PARAMS, workflow.body);
 }
-// Wall-clock and randomness would silently break resume replay, so scripts get
-// guarded shims instead of the real globals. Pass timestamps in via --args.
-const guardedDate = new Proxy(Date, {
-    get(target, prop, receiver) {
-        if (prop === "now") {
-            return () => {
-                throw new Error("Date.now() is unavailable in workflows (breaks resume); pass timestamps via --args");
-            };
-        }
-        return Reflect.get(target, prop, receiver);
-    },
-    construct(target, argArray) {
-        if (argArray.length === 0) {
-            throw new Error("new Date() without arguments is unavailable in workflows (breaks resume)");
-        }
-        return Reflect.construct(target, argArray);
-    },
-});
-const guardedMath = Object.create(Math, {
-    random: {
-        value: () => {
-            throw new Error("Math.random() is unavailable in workflows (breaks resume); vary prompts by index instead");
-        },
-    },
-});
 class Semaphore {
     queue = [];
     available;
@@ -89,11 +115,13 @@ const AGENT_PREAMBLE = [
 ].join("\n");
 export async function runWorkflow(options) {
     const startedAt = Date.now();
+    const statusStartedAt = new Date().toISOString();
     const workflow = loadWorkflow(options.file);
-    const scriptFn = new AsyncFunction(...SCRIPT_PARAMS, workflow.body);
     const workspace = resolve(options.cwd);
-    const journal = new RunJournal(workspace);
-    const resumeCache = options.resumeRunId ? loadResumeCache(workspace, options.resumeRunId) : undefined;
+    const journal = new RunJournal(workspace, options.runId);
+    const resumeMode = options.resumeMode ?? "prefix";
+    const resumeCache = options.resumeRunId && resumeMode === "hash" ? loadResumeCache(workspace, options.resumeRunId) : undefined;
+    const priorCalls = options.resumeRunId && resumeMode !== "hash" ? loadResumeCalls(workspace, options.resumeRunId) : undefined;
     const reporter = options.reporter;
     const maxAgents = options.maxAgents ?? 200;
     const agentTimeoutMs = options.agentTimeoutMs ?? 20 * 60 * 1000;
@@ -103,6 +131,33 @@ export async function runWorkflow(options) {
     let agentCounter = 0;
     let outputTokens = 0;
     let currentPhase;
+    let prefixIntact = true;
+    const liveSessions = new Map();
+    const skipped = new Set();
+    const controlTimer = setInterval(() => {
+        for (const id of readSkipRequests(journal.runDir)) {
+            if (skipped.has(id))
+                continue;
+            skipped.add(id);
+            liveSessions.get(id)?.abort("skipped via newton skip");
+        }
+    }, 500);
+    controlTimer.unref();
+    function syncStatus(status, extra = {}) {
+        writeStatus(journal.runDir, {
+            runId: journal.runId,
+            pid: process.pid,
+            file: workflow.file,
+            name: workflow.meta.name,
+            detached: options.detached ?? false,
+            startedAt: statusStartedAt,
+            updatedAt: new Date().toISOString(),
+            status,
+            agents: agentCounter,
+            outputTokens,
+            ...extra,
+        });
+    }
     journal.append({
         type: "workflow_start",
         runId: journal.runId,
@@ -110,8 +165,10 @@ export async function runWorkflow(options) {
         name: workflow.meta.name,
         args: options.args ?? null,
         resumedFrom: options.resumeRunId ?? null,
+        resumeMode: options.resumeRunId ? resumeMode : null,
     });
     reporter.start(workflow.meta, journal.runId, journal.runDir);
+    syncStatus("running");
     const budget = {
         total: budgetTotal,
         spent: () => outputTokens,
@@ -135,61 +192,168 @@ export async function runWorkflow(options) {
         if (budgetTotal !== null && outputTokens >= budgetTotal) {
             throw new Error(`token budget exhausted (${outputTokens}/${budgetTotal} output tokens)`);
         }
-        const key = agentCallKey(prompt, spec, callOptions.schema ?? null);
+        const config = validateConfig(callOptions.config);
+        const key = agentCallKey(prompt, { ...spec, isolation: callOptions.isolation, mcp: callOptions.mcp, config }, callOptions.schema ?? null);
         const label = callOptions.label ?? prompt.replace(/\s+/g, " ").trim().slice(0, 64);
         const phase = callOptions.phase ?? currentPhase;
+        if (priorCalls && prefixIntact) {
+            const prior = priorCalls.get(id);
+            if (!prior || prior.key !== key) {
+                prefixIntact = false;
+            }
+            else if (prior.ok) {
+                journal.append({ type: "agent_end", id, key, label, phase, status: "ok", cached: true, result: prior.result });
+                syncStatus("running");
+                reporter.agentStart(id, label, spec, phase, true);
+                reporter.agentEnd(id, true, 0, "cached");
+                return prior.result;
+            }
+        }
         const cachedQueue = resumeCache?.get(key);
         if (cachedQueue && cachedQueue.length > 0) {
             const result = cachedQueue.shift();
             journal.append({ type: "agent_end", id, key, label, phase, status: "ok", cached: true, result });
+            syncStatus("running");
             reporter.agentStart(id, label, spec, phase, true);
             reporter.agentEnd(id, true, 0, "cached");
             return result;
         }
+        const mcpServers = callOptions.mcp !== undefined ? resolveMcpServers(workspace, callOptions.mcp) : undefined;
         await semaphore.acquire();
         const agentStartedAt = Date.now();
-        reporter.agentStart(id, label, spec, phase, false);
-        journal.append({ type: "agent_start", id, key, label, phase, spec, prompt });
-        const trace = journal.traceWriter(id);
+        let session;
+        let wt;
+        let worktreeFinished = false;
+        // Idempotent so the finally can guarantee cleanup on a throw without
+        // double-finalizing the worktree that the normal path already removed.
+        const finishCreatedWorktree = async () => {
+            if (!wt || worktreeFinished)
+                return undefined;
+            worktreeFinished = true;
+            const wtInfo = await finishWorktree(workspace, wt);
+            const worktree = { path: wt.path, dirty: wtInfo.dirty, removed: wtInfo.removed };
+            if (wtInfo.dirty)
+                reporter.log(`worktree kept: ${wt.path}`);
+            return worktree;
+        };
         try {
+            reporter.agentStart(id, label, spec, phase, false);
+            journal.append({ type: "agent_start", id, key, label, phase, spec, prompt });
+            const trace = journal.traceWriter(id);
+            if (skipped.has(id)) {
+                journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: "skipped via newton skip", seconds: 0 });
+                syncStatus("running");
+                reporter.agentEnd(id, false, 0, "skipped");
+                return null;
+            }
+            if (callOptions.isolation === "worktree") {
+                try {
+                    wt = await createWorktree(workspace, journal.runId, id);
+                }
+                catch (error) {
+                    const message = errorMessage(error);
+                    journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: message, seconds: 0 });
+                    syncStatus("running");
+                    reporter.agentEnd(id, false, 0, message);
+                    return null;
+                }
+            }
+            if (skipped.has(id)) {
+                const worktree = await finishCreatedWorktree();
+                journal.append({
+                    type: "agent_end",
+                    id,
+                    key,
+                    label,
+                    phase,
+                    status: "error",
+                    error: "skipped via newton skip",
+                    seconds: 0,
+                    ...(worktree ? { worktree } : {}),
+                });
+                syncStatus("running");
+                reporter.agentEnd(id, false, 0, "skipped");
+                return null;
+            }
             const fullPrompt = AGENT_PREAMBLE + prompt + (callOptions.schema ? structuredOutputInstruction(callOptions.schema) : "");
-            const session = new AcpAgentSession({
-                spec,
-                prompt: fullPrompt,
-                cwd: callOptions.cwd ? resolve(workspace, callOptions.cwd) : workspace,
-                timeoutMs: callOptions.timeoutMs ?? agentTimeoutMs,
-                trace,
-            });
-            let turn = await session.prompt();
-            let result = turn.text;
-            let failure = turn.error;
-            if (!failure && callOptions.schema) {
-                for (let attempt = 0;; attempt++) {
-                    const parsed = extractJson(turn.text);
-                    const errors = parsed === INVALID
-                        ? ["response contained no parseable JSON"]
-                        : validateAgainstSchema(parsed, callOptions.schema);
-                    if (errors.length === 0) {
-                        result = parsed;
-                        break;
-                    }
-                    if (attempt >= 2) {
-                        failure = `structured output failed after ${attempt + 1} attempts: ${errors.join("; ")}`;
-                        break;
-                    }
-                    turn = await session.promptAgain(structuredOutputRetryPrompt(errors, callOptions.schema));
-                    if (turn.error) {
-                        failure = turn.error;
-                        break;
+            const cwd = wt
+                ? callOptions.cwd
+                    ? resolve(wt.path, callOptions.cwd)
+                    : wt.path
+                : callOptions.cwd
+                    ? resolve(workspace, callOptions.cwd)
+                    : workspace;
+            let turn;
+            let result;
+            let failure;
+            for (let attempt = 1;; attempt++) {
+                session = new AcpAgentSession({
+                    spec,
+                    prompt: fullPrompt,
+                    cwd,
+                    timeoutMs: callOptions.timeoutMs ?? agentTimeoutMs,
+                    mcpServers,
+                    config,
+                    trace,
+                });
+                liveSessions.set(id, session);
+                turn = await session.prompt();
+                result = turn.text;
+                failure = turn.error;
+                if (!failure && callOptions.schema) {
+                    for (let retry = 0;; retry++) {
+                        const parsed = extractJson(turn.text);
+                        const errors = parsed === INVALID
+                            ? ["response contained no parseable JSON"]
+                            : validateAgainstSchema(parsed, callOptions.schema);
+                        if (errors.length === 0) {
+                            result = parsed;
+                            break;
+                        }
+                        if (retry >= 2) {
+                            failure = `structured output failed after ${retry + 1} attempts: ${errors.join("; ")}`;
+                            break;
+                        }
+                        turn = await session.promptAgain(structuredOutputRetryPrompt(errors, callOptions.schema));
+                        if (turn.error) {
+                            failure = turn.error;
+                            break;
+                        }
                     }
                 }
+                liveSessions.delete(id);
+                session.close();
+                outputTokens += turn.usage?.outputTokens ?? 0;
+                if (!failure ||
+                    attempt >= AGENT_MAX_ATTEMPTS ||
+                    turn.stopReason === "timeout" ||
+                    turn.stopReason === "cancelled" ||
+                    !TRANSIENT_AGENT_ERROR.test(failure)) {
+                    break;
+                }
+                const delayMs = AGENT_RETRY_BASE_MS * 4 ** (attempt - 1);
+                journal.append({ type: "agent_retry", id, key, label, phase, attempt, error: failure, delayMs });
+                reporter.log(`↻ agent #${id} transient error, retry ${attempt}/${AGENT_MAX_ATTEMPTS - 1} in ${delayMs / 1000}s: ${failure.split("\n")[0]}`);
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, delayMs));
+                if (skipped.has(id))
+                    break;
             }
-            session.close();
+            const worktree = await finishCreatedWorktree();
             const seconds = Math.round((Date.now() - agentStartedAt) / 1000);
             const turnTokens = turn.usage?.outputTokens ?? 0;
-            outputTokens += turnTokens;
             if (failure) {
-                journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: failure, seconds });
+                journal.append({
+                    type: "agent_end",
+                    id,
+                    key,
+                    label,
+                    phase,
+                    status: "error",
+                    error: failure,
+                    seconds,
+                    ...(worktree ? { worktree } : {}),
+                });
+                syncStatus("running");
                 reporter.agentEnd(id, false, seconds, failure);
                 return null;
             }
@@ -204,11 +368,19 @@ export async function runWorkflow(options) {
                 toolCalls: turn.toolCalls,
                 usage: turn.usage,
                 result,
+                ...(worktree ? { worktree } : {}),
             });
+            syncStatus("running");
             reporter.agentEnd(id, true, seconds, turn.usage ? `${turn.toolCalls} tools · ${turnTokens} out-tok` : `${turn.toolCalls} tools`);
             return result;
         }
         finally {
+            if (session) {
+                liveSessions.delete(id);
+                session.close();
+            }
+            // No-op unless a throw skipped the normal finalize (guard above).
+            await finishCreatedWorktree().catch(() => { });
             semaphore.release();
         }
     }
@@ -219,7 +391,7 @@ export async function runWorkflow(options) {
         return Promise.all(thunks.map((thunk) => Promise.resolve()
             .then(thunk)
             .catch((error) => {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorMessage(error);
             journal.append({ type: "log", message: `parallel task failed: ${message}` });
             reporter.log(`parallel task failed: ${message}`);
             return null;
@@ -238,7 +410,7 @@ export async function runWorkflow(options) {
                     previous = await stage(previous, item, index);
                 }
                 catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = errorMessage(error);
                     journal.append({ type: "log", message: `pipeline item ${index} dropped: ${message}` });
                     reporter.log(`pipeline item ${index} dropped: ${message}`);
                     return null;
@@ -253,14 +425,64 @@ export async function runWorkflow(options) {
         currentPhase = title;
         journal.append({ type: "phase", title });
         reporter.phase(title);
+        syncStatus("running");
     }
     function logFn(message) {
         const text = typeof message === "string" ? message : JSON.stringify(message);
         journal.append({ type: "log", message: text });
         reporter.log(text);
     }
+    const realm = createRealm((message) => logFn(message));
+    async function executeScript(loaded, scriptArgs, depth) {
+        const scriptFn = realm.compile(SCRIPT_PARAMS, loaded.body, loaded.file);
+        return scriptFn(agentFn, parallelFn, pipelineFn, phaseFn, logFn, scriptArgs, budget, makeWorkflowFn(loaded.file, depth));
+    }
+    function makeWorkflowFn(callerFile, depth) {
+        return async (nameOrPath, childArgs) => {
+            if (depth >= 1)
+                throw new Error("workflow() nesting is limited to one level");
+            if (typeof nameOrPath !== "string")
+                throw new Error("workflow() takes a workflow name or path string");
+            const registryDir = join(workspace, ".newton", "workflows");
+            const file = /\.(js|mjs)$/.test(nameOrPath) || nameOrPath.includes("/")
+                ? resolve(dirname(callerFile), nameOrPath)
+                : join(registryDir, `${nameOrPath}.js`);
+            if (!existsSync(file)) {
+                let names = [];
+                try {
+                    names = readdirSync(registryDir, { withFileTypes: true })
+                        .filter((entry) => entry.isFile() && /\.(js|mjs)$/.test(entry.name))
+                        .map((entry) => entry.name.replace(/\.(?:js|mjs)$/, ""))
+                        .sort();
+                }
+                catch {
+                    names = [];
+                }
+                throw new Error(`workflow "${nameOrPath}" not found at ${file}; registered workflows: ${names.length > 0 ? names.join(", ") : "(none)"}`);
+            }
+            const child = loadWorkflow(file);
+            journal.append({ type: "workflow_child_start", name: child.meta.name, file: child.file, args: childArgs ?? null });
+            reporter.log(`▸ workflow ${child.meta.name}`);
+            const savedPhase = currentPhase;
+            try {
+                const result = await executeScript(child, childArgs, depth + 1);
+                journal.append({ type: "workflow_child_end", name: child.meta.name, status: "ok" });
+                reporter.log(`✔ workflow ${child.meta.name}`);
+                return result;
+            }
+            catch (error) {
+                const message = errorMessage(error);
+                journal.append({ type: "workflow_child_end", name: child.meta.name, status: "error", error: message });
+                reporter.log(`✖ workflow ${child.meta.name}: ${message}`);
+                throw error;
+            }
+            finally {
+                currentPhase = savedPhase;
+            }
+        };
+    }
     try {
-        const result = await scriptFn(agentFn, parallelFn, pipelineFn, phaseFn, logFn, options.args, budget, guardedDate, guardedMath);
+        const result = await executeScript(workflow, options.args, 0);
         const runResult = {
             runId: journal.runId,
             status: "ok",
@@ -270,11 +492,13 @@ export async function runWorkflow(options) {
             durationMs: Date.now() - startedAt,
         };
         journal.append({ type: "workflow_end", status: "ok", result: runResult.result, agents: agentCounter, outputTokens });
+        syncStatus("ok", { result: runResult.result });
         return runResult;
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = errorMessage(error);
         journal.append({ type: "workflow_end", status: "error", error: message, agents: agentCounter, outputTokens });
+        syncStatus("error", { error: message });
         return {
             runId: journal.runId,
             status: "error",
@@ -284,4 +508,7 @@ export async function runWorkflow(options) {
             durationMs: Date.now() - startedAt,
         };
     }
+    finally {
+        clearInterval(controlTimer);
+    }
 }

package/dist/journal.js

@@ -27,7 +27,7 @@ export class RunJournal {
         };
     }
 }
-function newRunId() {
+export function newRunId() {
     const now = new Date();
     const stamp = now
         .toISOString()
@@ -43,8 +43,14 @@ export function agentCallKey(prompt, spec, schema) {
         .slice(0, 32);
 }
 /**
- * Resume cache: successful agent results from a prior run, keyed by
- * (prompt, spec, schema) hash. Duplicate keys replay in call order.
+ * Resume has two modes:
+ *   - prefix: load prior calls by positional id via loadResumeCalls.
+ *   - hash: load successful results by (prompt, spec, schema) hash here.
+ *
+ * Invariant: journal `id` is the positional sequence. Agent ids increment at
+ * every agent() call, including cached calls.
+ *
+ * Duplicate hash keys replay in call order.
  */
 export function loadResumeCache(workspace, runId) {
     const journalPath = join(workspace, ".newton", "runs", runId, "journal.jsonl");
@@ -70,3 +76,34 @@ export function loadResumeCache(workspace, runId) {
     }
     return cache;
 }
+export function loadResumeCalls(workspace, runId) {
+    const journalPath = join(workspace, ".newton", "runs", runId, "journal.jsonl");
+    if (!existsSync(journalPath)) {
+        throw new Error(`No journal found for run "${runId}" (looked at ${journalPath})`);
+    }
+    const calls = new Map();
+    for (const line of readFileSync(journalPath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const id = entry.id;
+        const key = entry.key;
+        if (typeof id !== "number" || !Number.isFinite(id) || typeof key !== "string")
+            continue;
+        if (entry.type === "agent_start") {
+            if (!calls.has(id)) {
+                calls.set(id, { key, ok: false });
+            }
+        }
+        else if (entry.type === "agent_end") {
+            calls.set(id, { key, ok: entry.status === "ok", result: entry.result });
+        }
+    }
+    return calls;
+}

package/dist/mcp.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return isRecord(error) && typeof error.message === "string" ? error.message : String(error);
+}
+function readMcpConfig(workspace) {
+    const path = join(workspace, ".mcp.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT") {
+            throw new Error(`MCP config file not found at ${path}`);
+        }
+        throw new Error(`Could not read ${path}: ${errorMessage(error)}`);
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.mcpServers)) {
+        throw new Error(`${path}: expected { "mcpServers": { ... } }`);
+    }
+    return { path, servers: parsed.mcpServers };
+}
+function availableNames(servers) {
+    const names = Object.keys(servers).sort();
+    return names.length > 0 ? names.join(", ") : "(none)";
+}
+function optionalStringArray(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`${field} must be an array of strings`);
+    }
+    return value;
+}
+function nameValueEntries(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    return Object.entries(value).map(([name, entryValue]) => ({ name, value: String(entryValue) }));
+}
+function toMcpServer(name, value, source) {
+    if (!isRecord(value))
+        throw new Error(`${source} must be an object`);
+    if (value.type !== undefined) {
+        if (value.type !== "http" && value.type !== "sse") {
+            throw new Error(`${source} type must be "http" or "sse"`);
+        }
+        if (typeof value.url !== "string" || !value.url) {
+            throw new Error(`${source} missing url`);
+        }
+        return {
+            type: value.type,
+            name,
+            url: value.url,
+            headers: nameValueEntries(value.headers, `${source} headers`),
+        };
+    }
+    if (typeof value.command !== "string" || !value.command) {
+        throw new Error(`${source} missing command`);
+    }
+    return {
+        name,
+        command: value.command,
+        args: optionalStringArray(value.args, `${source} args`),
+        env: nameValueEntries(value.env, `${source} env`),
+    };
+}
+export function resolveMcpServers(workspace, opt) {
+    if (opt === true) {
+        const config = readMcpConfig(workspace);
+        return Object.entries(config.servers).map(([name, server]) => toMcpServer(name, server, `MCP server "${name}"`));
+    }
+    if (!Array.isArray(opt)) {
+        throw new Error("agent() mcp option takes true or an array of names/servers");
+    }
+    let config;
+    const getConfig = () => {
+        config ??= readMcpConfig(workspace);
+        return config;
+    };
+    return opt.map((entry) => {
+        if (typeof entry === "string") {
+            const loaded = getConfig();
+            const server = loaded.servers[entry];
+            if (server === undefined) {
+                throw new Error(`MCP server "${entry}" not found in ${loaded.path}; available: ${availableNames(loaded.servers)}`);
+            }
+            return toMcpServer(entry, server, `MCP server "${entry}"`);
+        }
+        if (!isRecord(entry)) {
+            throw new Error("agent() mcp option takes true or an array of names/servers");
+        }
+        if (typeof entry.name !== "string" || !entry.name.trim()) {
+            throw new Error("inline MCP server missing name");
+        }
+        return toMcpServer(entry.name, entry, `inline MCP server "${entry.name}"`);
+    });
+}