@boardwalk-labs/engine 0.1.0

package/dist/mcp/transport_stdio.js

@@ -0,0 +1,94 @@
+// MCP stdio transport: spawn the server command and speak newline-delimited JSON over its
+// stdin/stdout (the MCP stdio framing). Runs in the RUN PROCESS — the program is the trusted
+// layer, so its inline `command`/`env` are honored as-is; the server's stderr is inherited so
+// its diagnostics land in the run log like any other program output.
+import { spawn } from "node:child_process";
+import { EngineError } from "../errors.js";
+export class StdioTransport {
+    serverName;
+    child;
+    messageCb = null;
+    closeCb = null;
+    /** Set once the transport failed or was closed — later sends must fail fast, not hang. */
+    dead = null;
+    closedDeliberately = false;
+    stdoutBuffer = "";
+    constructor(opts) {
+        this.serverName = opts.serverName;
+        this.child = spawn(opts.command, [...(opts.args ?? [])], {
+            env: { ...process.env, ...opts.env },
+            // stderr is inherited: it flows into THIS process's stderr, which the supervisor already
+            // captures as run-log program output — MCP server diagnostics need no extra plumbing.
+            stdio: ["pipe", "pipe", "inherit"],
+        });
+        this.child.stdout?.on("data", (chunk) => {
+            this.stdoutBuffer += chunk.toString("utf8");
+            let newline = this.stdoutBuffer.indexOf("\n");
+            while (newline >= 0) {
+                const line = this.stdoutBuffer.slice(0, newline).trim();
+                this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+                if (line.length > 0)
+                    this.deliverLine(line);
+                newline = this.stdoutBuffer.indexOf("\n");
+            }
+        });
+        this.child.on("error", (err) => {
+            // Spawn failure (ENOENT et al.) — the most common misconfiguration; name the command.
+            this.die(new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}": failed to spawn "${opts.command}": ${err.message}.`, "Check that the command exists on this machine's PATH (stdio MCP servers run locally)."));
+        });
+        this.child.on("exit", (code, signal) => {
+            if (this.closedDeliberately)
+                return;
+            this.die(new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" exited unexpectedly ` +
+                `(${signal !== null ? `signal ${signal}` : `code ${String(code)}`}).`, "Its stderr is in the run log — check there for the server's own error output."));
+        });
+    }
+    send(message) {
+        if (this.dead !== null)
+            return Promise.reject(this.dead);
+        const stdin = this.child.stdin;
+        if (stdin === null || !stdin.writable) {
+            return Promise.reject(new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}": stdin is closed.`));
+        }
+        return new Promise((resolve, reject) => {
+            stdin.write(`${JSON.stringify(message)}\n`, (err) => {
+                if (err !== null && err !== undefined)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    onMessage(cb) {
+        this.messageCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+        // The process may have already died (spawn errors race subscription) — deliver late.
+        if (this.dead !== null && !this.closedDeliberately)
+            cb(this.dead);
+    }
+    /** Kill the server process. Deliberate teardown — no error is surfaced for the exit. */
+    close() {
+        this.closedDeliberately = true;
+        this.dead ??= new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}": connection closed.`);
+        this.child.kill("SIGTERM");
+        return Promise.resolve();
+    }
+    deliverLine(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return; // a non-JSON stdout line is server noise, not a protocol failure
+        }
+        this.messageCb?.(message);
+    }
+    die(err) {
+        if (this.dead !== null)
+            return;
+        this.dead = err;
+        this.closeCb?.(err);
+    }
+}

package/dist/run/child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/run/child.js

@@ -0,0 +1,139 @@
+// The run-process entry point. Spawned by the supervisor with an IPC channel; never run
+// directly. Protocol: wait for `init`, install the SDK host + run inputs, then IMPORT the
+// program bundle — the module body is the program, so importing the file IS running it
+// (MASTER_SPEC §2.1; no entrypoint convention). Report `done`/`failed`, exit. A thrown error
+// anywhere is reported over IPC when possible — the supervisor treats an exit without a
+// report as a crash (which triggers restart-from-the-top, the documented semantics).
+import { pathToFileURL } from "node:url";
+import { installConfig, installHost, installInput, takeDeclaredOutput, } from "@boardwalk-labs/workflow/runtime";
+import { EngineError, toErrorShape } from "../errors.js";
+import { asJsonValue } from "../json_value.js";
+import { createChildHost, errorFromIpc } from "./child_host.js";
+import { parentToChildSchema } from "./ipc.js";
+function send(message) {
+    // Why the guard: process.send disappears if the IPC channel closed (supervisor died);
+    // at that point the orphan exits via the disconnect handler below — nothing to report to.
+    process.send?.(message);
+}
+const pending = new Map();
+let nextCallId = 1;
+let initialized = false;
+process.on("disconnect", () => {
+    // Orphaned by an engine crash. Exit so the boot recovery sweep owns the restart; holding on
+    // with no supervisor would duplicate work when the engine comes back.
+    process.exit(1);
+});
+process.on("message", (raw) => {
+    const parsed = parentToChildSchema.safeParse(raw);
+    if (!parsed.success)
+        return; // Not ours; the supervisor only sends protocol messages.
+    const msg = parsed.data;
+    if (msg.type === "host_result") {
+        const call = pending.get(msg.callId);
+        if (call === undefined)
+            return;
+        pending.delete(msg.callId);
+        if (msg.result.ok)
+            call.resolve(msg.result.value);
+        else
+            call.reject(errorFromIpc(msg.result.error));
+        return;
+    }
+    if (initialized)
+        return; // A second init is a protocol violation; ignore.
+    initialized = true;
+    void runProgram(msg.programPath, msg.workspaceDir, msg.skillsDir, msg.input, msg.config);
+});
+async function runProgram(programPath, workspaceDir, skillsDir, input, config) {
+    let redactor;
+    try {
+        process.chdir(workspaceDir);
+        const childHost = createChildHost({
+            request(method, args) {
+                return new Promise((resolve, reject) => {
+                    const callId = nextCallId++;
+                    pending.set(callId, { resolve, reject });
+                    send({ type: "host_call", callId, method, args });
+                });
+            },
+            emit(body, turnId) {
+                send({ type: "emit", body, ...(turnId !== undefined ? { turnId } : {}) });
+            },
+            startTurn(turnId, identity) {
+                send({ type: "turn_started", turnId, ...identity });
+            },
+            reportUsage(modelRef, usage) {
+                send({ type: "report_usage", modelRef, usage });
+            },
+            memoryUsed(dir) {
+                send({ type: "memory_used", dir });
+            },
+        }, { workspaceDir, skillsDir });
+        redactor = childHost.redactor;
+        installHost(childHost.host);
+        installInput(input);
+        installConfig(narrowConfig(config));
+        // Importing IS running: the module body is the program; top-level await is the norm; the
+        // run completes when evaluation finishes and fails when the body throws.
+        const programModule = await import(pathToFileURL(programPath).href);
+        warnOnLegacyDefaultExport(programModule);
+        const declared = takeDeclaredOutput();
+        send({
+            type: "done",
+            output: declared === null ? null : declared.value,
+            outputDeclared: declared !== null,
+        });
+    }
+    catch (err) {
+        // Program errors can carry secret values the program legitimately read (secrets.get) —
+        // this report persists in the run row and event stream, so it gets the same redaction
+        // as everything model-bound. `redactor` may be unset if the failure preceded host setup;
+        // nothing secret can have been revealed before that point.
+        const scrub = (text) => redactor?.redact(text) ?? text;
+        const shape = toErrorShape(err);
+        const hint = err instanceof EngineError ? err.hint : undefined;
+        // Output declared before the throw still counts (verdict-then-throw): the success path
+        // reports it, so the failure path must too, or the verdict is lost. Safe even when the
+        // failure preceded host setup — nothing was declared, so this is null/false.
+        const declared = takeDeclaredOutput();
+        send({
+            type: "failed",
+            error: {
+                ...shape,
+                message: scrub(shape.message),
+                ...(hint !== undefined ? { hint: scrub(hint) } : {}),
+            },
+            output: declared === null ? null : declared.value,
+            outputDeclared: declared !== null,
+        });
+    }
+    finally {
+        // Why disconnect-then-exit: process.send is async under the hood; disconnecting flushes
+        // the channel so the final message is never lost to an immediate exit.
+        process.disconnect();
+        process.exit(0);
+    }
+}
+/** Per-key narrowing of the deploy-time config crossing IPC (no record-level cast). */
+function narrowConfig(config) {
+    const out = {};
+    for (const [key, value] of Object.entries(config)) {
+        out[key] = asJsonValue(value, `config.${key}`);
+    }
+    return out;
+}
+/**
+ * The rescinded draft convention wrapped the program in `export default async function run()`.
+ * Such a function is NEVER called (the module body is the program) — warn so an author who
+ * wrapped their logic learns why nothing happened. Stderr lands in the run log.
+ */
+function warnOnLegacyDefaultExport(programModule) {
+    if (typeof programModule !== "object" || programModule === null)
+        return;
+    const candidate = Reflect.get(programModule, "default");
+    if (typeof candidate === "function") {
+        console.error("warning: this workflow exports a default function, which Boardwalk does not call — " +
+            "the module body IS the program. Move the function's body to the top level " +
+            "(top-level await is supported).");
+    }
+}

package/dist/run/child_host.d.ts

@@ -0,0 +1,26 @@
+import type { TokenUsage } from "@boardwalk-labs/workflow";
+import type { WorkflowHost } from "@boardwalk-labs/workflow/runtime";
+import { type AgentIdentity } from "../agent/leaf.js";
+import { Redactor } from "../agent/redact.js";
+import type { ToolSetContext } from "../agent/tools.js";
+import { type IpcErrorShape, type HostMethod, type RunEventBody } from "./ipc.js";
+export interface ChildHostIo {
+    /** Broker a host call to the supervisor; resolves with its result. */
+    request(method: HostMethod, args: Record<string, unknown>): Promise<unknown>;
+    /** Emit a run-event body (the supervisor stamps the envelope). turnId scopes leaf frames. */
+    emit(body: RunEventBody, turnId?: string): void;
+    /** Tell the supervisor to open a new turn block (it emits turn_started naming the leaf). */
+    startTurn(turnId: string, identity: AgentIdentity): void;
+    /** Report leaf usage to the supervisor — the budget authority. */
+    reportUsage(modelRef: string, usage: TokenUsage): void;
+    /** Tell the supervisor a memory dir is in use (auto-persisted at successful run end). */
+    memoryUsed(dir: string): void;
+}
+/** Rebuild a typed EngineError from its IPC shape so program-visible errors keep code + hint. */
+export declare function errorFromIpc(shape: IpcErrorShape): Error;
+export interface ChildHost {
+    host: WorkflowHost;
+    /** The run process's one redactor — the child entry scrubs failure reports with it too. */
+    redactor: Redactor;
+}
+export declare function createChildHost(io: ChildHostIo, capabilities: ToolSetContext): ChildHost;

package/dist/run/child_host.js

@@ -0,0 +1,124 @@
+// The WorkflowHost installed in the run process.
+//
+// Split of responsibilities (SPEC §2.3): anything that only needs the local process happens
+// here (sleep — hold-and-pay is literally just holding this process; phase markers); anything
+// that touches engine state (secrets, durable child runs, artifacts) is brokered to the
+// supervisor over IPC. agent() runs its loop in THIS process too — program-defined tools and
+// MCP connections must execute where the program lives (the trusted layer).
+import { z } from "zod";
+import { runAgentLeaf } from "../agent/leaf.js";
+import { Redactor } from "../agent/redact.js";
+import { EngineError, isEngineErrorCode } from "../errors.js";
+import { mcpTokenResultSchema, resolvedModelSchema, } from "./ipc.js";
+/** Rebuild a typed EngineError from its IPC shape so program-visible errors keep code + hint. */
+export function errorFromIpc(shape) {
+    const code = isEngineErrorCode(shape.code) ? shape.code : "INTERNAL";
+    return new EngineError(code, shape.message, shape.hint);
+}
+export function createChildHost(io, capabilities) {
+    let phaseCount = 0;
+    // One counter per run → a stable, run-unique id for each agent() call. The author's optional
+    // name rides alongside as the display label; concurrent agents stay distinguishable either way.
+    let agentCount = 0;
+    // One redactor for the whole run process: every secret value revealed to the program (and
+    // every provider key) is scrubbed from everything model-bound, across all agent() calls.
+    const redactor = new Redactor();
+    const host = {
+        setPhase(name, opts) {
+            phaseCount += 1;
+            io.emit({ kind: "phase", name, id: opts?.id ?? `phase-${String(phaseCount)}` });
+        },
+        async agent(prompt, opts) {
+            agentCount += 1;
+            const identity = {
+                agentId: `agent-${String(agentCount)}`,
+                ...(opts?.name !== undefined ? { agentName: opts.name } : {}),
+            };
+            return await runAgentLeaf(prompt, opts, {
+                identity,
+                resolve: async (model, provider) => resolvedModelSchema.parse(await io.request("resolve_model", {
+                    ...(model !== undefined ? { model } : {}),
+                    ...(provider !== undefined ? { provider } : {}),
+                })),
+                startTurn: (turnId) => io.startTurn(turnId, identity),
+                emit: (turnId, body) => io.emit(body, turnId),
+                reportUsage: (modelRef, usage) => io.reportUsage(modelRef, usage),
+                memoryUsed: (dir) => io.memoryUsed(dir),
+                // MCP OAuth tokens are engine state: brokered per use, validated like any other
+                // supervisor response; refresh tokens and the store never enter this process.
+                mcpToken: async (serverUrl, invalidateToken) => mcpTokenResultSchema.parse(await io.request("mcp_token", {
+                    serverUrl,
+                    ...(invalidateToken !== undefined ? { invalidateToken } : {}),
+                })),
+                redactor,
+                capabilities,
+            });
+        },
+        async callWorkflow(slug, input, opts) {
+            return await io.request("call_workflow", {
+                slug,
+                input,
+                ...(opts?.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+            });
+        },
+        async runWorkflow(slug, input, opts) {
+            const value = await io.request("run_workflow", {
+                slug,
+                input,
+                ...(opts?.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+            });
+            return runIdSchema.parse(value);
+        },
+        async sleep(arg) {
+            // Hold-and-pay: the process just waits. Locals stay in memory; nothing is checkpointed.
+            // Chunked so a multi-week sleep({ until }) doesn't overflow setTimeout's 2^31-1 ms cap
+            // (~24.8 days), which would otherwise fire ~immediately — there is no hard duration cap.
+            let remaining = sleepMs(arg);
+            while (remaining > 0) {
+                const slice = Math.min(remaining, MAX_TIMEOUT_MS);
+                await new Promise((resolve) => {
+                    setTimeout(resolve, slice);
+                });
+                remaining -= slice;
+            }
+        },
+        async getSecret(name) {
+            const value = secretValueSchema.parse(await io.request("get_secret", { name }));
+            redactor.add(name, value);
+            return value;
+        },
+        async writeArtifact(name, contentType, body, metadata) {
+            const bytes = typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body);
+            const value = await io.request("write_artifact", {
+                name,
+                contentType,
+                bodyBase64: bytes.toString("base64"),
+                ...(metadata !== undefined ? { metadata } : {}),
+            });
+            return artifactRefSchema.parse(value);
+        },
+    };
+    return { host, redactor };
+}
+/** setTimeout's max delay (2^31-1 ms ≈ 24.8 days); longer sleeps are chunked. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+// Supervisor responses are validated like any other boundary input — the channel being ours
+// doesn't exempt it (CODE_QUALITY §2.1).
+const secretValueSchema = z.string();
+const runIdSchema = z.string().min(1);
+const artifactRefSchema = z.strictObject({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    url: z.string().min(1),
+});
+function sleepMs(arg) {
+    if (typeof arg === "number")
+        return arg;
+    if ("durationMs" in arg)
+        return arg.durationMs;
+    const until = arg.until instanceof Date ? arg.until.getTime() : Date.parse(arg.until);
+    if (Number.isNaN(until)) {
+        throw new EngineError("VALIDATION", `sleep({ until }) got an unparseable date.`);
+    }
+    return until - Date.now();
+}

package/dist/run/idempotency.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue } from "@boardwalk-labs/workflow";
+/** Serialize like JSON.stringify but with object keys sorted recursively — equal values ⇒ equal strings. */
+export declare function canonicalJson(value: JsonValue): string;
+/** The default child-call idempotency key: sha256 over (parent run, target slug, input). */
+export declare function defaultIdempotencyKey(parentRunId: string, slug: string, input: JsonValue): string;

package/dist/run/idempotency.js

@@ -0,0 +1,31 @@
+// Default idempotency keys for workflows.call / workflows.run.
+//
+// Contract (SDK CallOptions): "a deterministic key over (parent_run_id, target, input)" — a
+// restarted parent recomputes the same key and re-attaches to the child it already spawned
+// instead of spawning a duplicate. Determinism requires canonical JSON: object key order must
+// not change the key. Inputs are narrowed to JsonValue at the IPC boundary before they get
+// here, so this module is fully typed — no unknown, no casts.
+import { createHash } from "node:crypto";
+/** Serialize like JSON.stringify but with object keys sorted recursively — equal values ⇒ equal strings. */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const parts = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, v]) => `${JSON.stringify(key)}:${canonicalJson(v)}`);
+        return `{${parts.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** The default child-call idempotency key: sha256 over (parent run, target slug, input). */
+export function defaultIdempotencyKey(parentRunId, slug, input) {
+    return createHash("sha256")
+        .update(parentRunId)
+        .update(" ")
+        .update(slug)
+        .update(" ")
+        .update(canonicalJson(input))
+        .digest("hex");
+}

package/dist/run/ipc.d.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import type { RunEvent, WorkflowManifest, JsonValue } from "@boardwalk-labs/workflow";
+/** A run event minus its envelope — what the child emits, before the supervisor stamps it. */
+export type RunEventBody = RunEvent extends infer E ? E extends RunEvent ? Omit<E, "runId" | "turnId" | "seq" | "t"> : never : never;
+declare const errorShapeSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type IpcErrorShape = z.infer<typeof errorShapeSchema>;
+export interface InitMessage {
+    type: "init";
+    runId: string;
+    /** Absolute path to the bundled program (ESM, `@boardwalk-labs/workflow` external). */
+    programPath: string;
+    /** The run's isolated working directory (the child chdirs here before importing the program). */
+    workspaceDir: string;
+    /** Where this workflow's deployed skills live, or null when none were deployed. */
+    skillsDir: string | null;
+    input: unknown;
+    config: Record<string, JsonValue>;
+    manifest: WorkflowManifest;
+}
+export interface HostResultMessage {
+    type: "host_result";
+    callId: number;
+    result: {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        error: IpcErrorShape;
+    };
+}
+export type ParentToChild = InitMessage | HostResultMessage;
+export declare const parentToChildSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"init">;
+    runId: z.ZodString;
+    programPath: z.ZodString;
+    workspaceDir: z.ZodString;
+    skillsDir: z.ZodNullable<z.ZodString>;
+    input: z.ZodUnknown;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    manifest: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"host_result">;
+    callId: z.ZodNumber;
+    result: z.ZodUnion<readonly [z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>, z.ZodObject<{
+        ok: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            hint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>]>;
+/** Host methods the child brokers to the supervisor (everything that touches engine state). */
+export declare const HOST_METHODS: readonly ["get_secret", "call_workflow", "run_workflow", "write_artifact", "resolve_model", "mcp_token"];
+export type HostMethod = (typeof HOST_METHODS)[number];
+export declare const childToParentSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"host_call">;
+    callId: z.ZodNumber;
+    method: z.ZodEnum<{
+        get_secret: "get_secret";
+        call_workflow: "call_workflow";
+        run_workflow: "run_workflow";
+        write_artifact: "write_artifact";
+        resolve_model: "resolve_model";
+        mcp_token: "mcp_token";
+    }>;
+    args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"emit">;
+    body: z.ZodObject<{
+        kind: z.ZodString;
+    }, z.core.$loose>;
+    turnId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"turn_started">;
+    turnId: z.ZodString;
+    agentId: z.ZodString;
+    agentName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"report_usage">;
+    modelRef: z.ZodString;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        totalTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"memory_used">;
+    dir: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    output: z.ZodUnknown;
+    outputDeclared: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"failed">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    output: z.ZodUnknown;
+    outputDeclared: z.ZodBoolean;
+}, z.core.$strip>]>;
+export type ChildToParent = z.infer<typeof childToParentSchema>;
+export declare const getSecretArgsSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strict>;
+export declare const callWorkflowArgsSchema: z.ZodObject<{
+    slug: z.ZodString;
+    input: z.ZodUnknown;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const writeArtifactArgsSchema: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodString;
+    bodyBase64: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const resolveModelArgsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The supervisor's resolve_model response, re-validated child-side before use. */
+export declare const resolvedModelSchema: z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    protocol: z.ZodEnum<{
+        anthropic: "anthropic";
+        openai: "openai";
+    }>;
+    baseUrl: z.ZodString;
+    apiKey: z.ZodNullable<z.ZodString>;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    secretHeaderNames: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * mcp_token: the child asks the engine for an OAuth bearer token for an MCP server (token
+ * state is PARENT-owned — the run process never sees refresh tokens or the store).
+ * `invalidateToken` names a token the server just rejected, so the supervisor refreshes
+ * instead of handing the same dead value back.
+ */
+export declare const mcpTokenArgsSchema: z.ZodObject<{
+    serverUrl: z.ZodString;
+    invalidateToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The supervisor's mcp_token response. null accessToken ⇒ interaction would be required —
+ *  the hint names the `engine.authorizeMcpServer(...)` call that fixes it. */
+export declare const mcpTokenResultSchema: z.ZodObject<{
+    accessToken: z.ZodNullable<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export {};