akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/integrations/agent/runner-dispatch.js

@@ -2,278 +2,49 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * The low-level exhaustive dispatch seam for the {@link RunnerSpec} transport
- * union (`llm | agent | sdk`). User/model work reaches this function only
- * after `ResolvedExecutionRequestV1` preparation and engine-owned lowering;
- * `dispatchLoweredExecutionRequest` supplies the direct-LLM handler. A
- * prompt-free native launch crosses the explicit payload-free interactive
- * lowerer in that same shared layer.
- *
- * Agent and SDK arms use the shared profile runners. The LLM arm deliberately
- * requires a handler because structured callers own their parse/fallback
- * contract. The `assertNever` arm keeps a fourth transport kind from becoming
- * an implicit fallthrough. Symbolic LLM and SDK-fallback credentials are
- * materialized here, at authorized operation-lease acquisition or the final
- * single-call boundary, then scrubbed from the result.
+ * Run a built execution: the one place credentials are read. A direct LLM
+ * goes to `chatCompletion`, an agent engine to `runAgent` (the harness builder
+ * turns the request into argv), an SDK engine to `runOpencodeSdk`. Every
+ * credential and passthrough value that could reach the child is redacted
+ * from the result.
  */
 import { assertNever } from "../../core/assert.js";
+import { UsageError } from "../../core/errors.js";
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
-import { spawnEnvNamesFor } from "../../core/spawn-env.js";
-import { closeServer as disposeOpencodeSdkServers, opencodeSdkServerEnvironmentNames, runOpencodeSdk, } from "../harnesses/opencode-sdk/sdk-runner.js";
-import { lookupApiKeyFileValue, lookupApiKeySecretRefValue, lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveLlmCredentialValue, } from "./engine-resolution.js";
-import { materializeLlmRunnerConnection, materializeLlmRunnerConnectionWithCredential, } from "./runner.js";
+import { chatCompletion, LlmCallError } from "../../llm/client.js";
+import { closeServer as disposeOpencodeSdkServers, runOpencodeSdk } from "../harnesses/opencode-sdk/sdk-runner.js";
+import { lookupApiKeyFileValue, lookupApiKeySecretRefValue, lookupCredentialFromEnv, resolveEngine, } from "./engine-resolution.js";
+import { materializeLlmRunnerConnection, materializeSdkFallbackConnection } from "./runner.js";
 import { runAgent } from "./spawn.js";
-const liveRunnerDispatchLeases = new WeakMap();
-const issuedRunnerDispatchLeases = new WeakSet();
-const disposedRunnerDispatchLeases = new WeakSet();
-function credentialBinding(credential) {
-    return credential ? { names: [...credential.names], required: credential.required } : null;
-}
-function passthroughBinding(spec) {
-    return [...new Set(spec.profile.envPassthrough)].sort();
-}
-function dispatchEnvironmentNames(spec) {
-    switch (spec.kind) {
-        case "llm":
-            return [];
-        case "agent":
-            return spawnEnvNamesFor(spec.profile.envPassthrough);
-        case "sdk":
-            return opencodeSdkServerEnvironmentNames(spec.profile);
-        default:
-            return assertNever(spec);
-    }
-}
-function snapshotDispatchEnvironment(spec, envSource) {
-    const snapshot = new Map();
-    const read = (name) => {
-        if (!snapshot.has(name))
-            snapshot.set(name, envSource[name]);
-        return snapshot.get(name);
-    };
-    const environmentSource = new Proxy(Object.create(null), {
-        get(_target, property) {
-            return typeof property === "string" ? snapshot.get(property) : undefined;
-        },
-    });
-    for (const name of dispatchEnvironmentNames(spec))
-        read(name);
-    const passthroughSensitiveValues = new Set();
-    if (spec.kind !== "llm") {
-        for (const name of new Set(spec.profile.envPassthrough)) {
-            const value = snapshot.get(name);
-            if (!isEnvPassthroughValueSafeToExpose(name, value) && value)
-                passthroughSensitiveValues.add(value);
-        }
+const OPERATIONAL_OPTIONS = [
+    "stdio",
+    "parseOutput",
+    "signal",
+    "envSource",
+    "spawn",
+    "setTimeoutFn",
+    "clearTimeoutFn",
+    "onEvent",
+];
+/** Every value that can reach one dispatch and must never be echoed back: credentials and secret-looking env. */
+export function collectDispatchSensitiveValues(runner, opts, envSource = opts.envSource ?? process.env) {
+    const values = [];
+    if (runner.kind === "llm") {
+        values.push(runner.connection.apiKey, lookupCredentialFromEnv(runner.credential, envSource), runner.apiKeyFile ? lookupApiKeyFileValue(runner.apiKeyFile) : undefined, runner.apiKeySecretRef ? lookupApiKeySecretRefValue(runner.apiKeySecretRef) : undefined);
     }
-    return { environmentSnapshot: snapshot, environmentSource, passthroughSensitiveValues, read };
-}
-/** Bind only transport identity; request model/inference/schema/timeout remain per-call. */
-function runnerLeaseBinding(spec) {
-    switch (spec.kind) {
-        case "llm":
-            return JSON.stringify({
-                kind: spec.kind,
-                engine: spec.engine ?? null,
-                endpoint: spec.connection.endpoint,
-                provider: spec.connection.provider ?? null,
-                credential: credentialBinding(spec.credential),
-                apiKeyFile: spec.apiKeyFile ?? null,
-            });
-        case "agent":
-            return JSON.stringify({
-                kind: spec.kind,
-                engine: spec.engine ?? null,
-                platform: spec.profile.platform ?? null,
-                name: spec.profile.name,
-                bin: spec.profile.bin,
-                envPassthrough: passthroughBinding(spec),
-            });
-        case "sdk":
-            return JSON.stringify({
-                kind: spec.kind,
-                engine: spec.engine ?? null,
-                platform: spec.profile.platform ?? null,
-                name: spec.profile.name,
-                bin: spec.profile.bin,
-                envPassthrough: passthroughBinding(spec),
-                fallbackEndpoint: spec.fallbackConnection?.endpoint ?? null,
-                fallbackProvider: spec.fallbackConnection?.provider ?? null,
-                fallbackCredential: credentialBinding(spec.fallbackCredential),
-                fallbackApiKeyFile: spec.fallbackApiKeyFile ?? null,
-            });
-        default:
-            return assertNever(spec);
-    }
-}
-function requireRunnerDispatchLease(lease, spec) {
-    if (typeof lease !== "object" || lease === null)
-        throw new TypeError("invalid dispatch lease");
-    const state = liveRunnerDispatchLeases.get(lease);
-    if (!state) {
-        if (issuedRunnerDispatchLeases.has(lease) && disposedRunnerDispatchLeases.has(lease)) {
-            throw new TypeError("dispatch lease is disposed");
+    else {
+        if (runner.kind === "sdk") {
+            values.push(runner.fallbackConnection?.apiKey, lookupCredentialFromEnv(runner.fallbackCredential, envSource), runner.fallbackApiKeyFile ? lookupApiKeyFileValue(runner.fallbackApiKeyFile) : undefined, runner.fallbackApiKeySecretRef ? lookupApiKeySecretRefValue(runner.fallbackApiKeySecretRef) : undefined);
         }
-        throw new TypeError("invalid dispatch lease");
-    }
-    if (spec && state.binding !== runnerLeaseBinding(spec)) {
-        throw new TypeError("dispatch lease does not match the lowered runner transport");
-    }
-    return state;
-}
-/** @internal Verify provenance, liveness, and transport binding without exposing state. */
-export function assertRunnerDispatchLease(lease, spec) {
-    requireRunnerDispatchLease(lease, spec);
-}
-/** @internal Acquire only through execution-lowering after authorization/provenance validation. */
-export function acquireRunnerDispatchLease(spec, envSource = process.env) {
-    const environment = snapshotDispatchEnvironment(spec, envSource);
-    const credentialSource = new Proxy(Object.create(null), {
-        get(_target, property) {
-            return typeof property === "string" ? environment.read(property) : undefined;
-        },
-    });
-    const primaryCredential = spec.kind === "llm"
-        ? resolveLlmCredentialValue(spec.engine, spec.credential, spec.apiKeyFile, spec.apiKeySecretRef, credentialSource)
-        : undefined;
-    const fallbackCredential = spec.kind === "sdk"
-        ? resolveLlmCredentialValue(spec.engine, spec.fallbackCredential, spec.fallbackApiKeyFile, spec.fallbackApiKeySecretRef, credentialSource)
-        : undefined;
-    const handle = Object.create(null);
-    Object.defineProperty(handle, "toJSON", {
-        configurable: false,
-        enumerable: false,
-        writable: false,
-        value: () => {
-            throw new TypeError("dispatch lease is not serializable");
-        },
-    });
-    Object.freeze(handle);
-    const sensitiveValues = collectSensitiveValues([
-        primaryCredential,
-        fallbackCredential,
-        ...environment.passthroughSensitiveValues,
-    ]);
-    liveRunnerDispatchLeases.set(handle, {
-        binding: runnerLeaseBinding(spec),
-        primaryCredential,
-        fallbackCredential,
-        environmentSnapshot: environment.environmentSnapshot,
-        environmentSource: environment.environmentSource,
-        sensitiveValues,
-    });
-    issuedRunnerDispatchLeases.add(handle);
-    return handle;
-}
-/** @internal Scrub private material and invalidate one issued handle. */
-export function disposeRunnerDispatchLease(lease) {
-    if (typeof lease !== "object" || lease === null || !issuedRunnerDispatchLeases.has(lease)) {
-        throw new TypeError("invalid dispatch lease");
-    }
-    const state = liveRunnerDispatchLeases.get(lease);
-    if (!state)
-        return;
-    state.primaryCredential = undefined;
-    state.fallbackCredential = undefined;
-    state.environmentSnapshot.clear();
-    state.sensitiveValues.fill("");
-    state.sensitiveValues = [];
-    liveRunnerDispatchLeases.delete(lease);
-    disposedRunnerDispatchLeases.add(lease);
-}
-/** @internal Redact with private credential material without exposing its values. */
-export function redactWithRunnerDispatchLease(lease, value) {
-    return redactSensitiveText(value, requireRunnerDispatchLease(lease).sensitiveValues);
-}
-/**
- * Release every long-lived resource the dispatch runners CACHE for reuse, so a
- * one-shot process (the CLI) can exit cleanly once dispatching is done.
- *
- * The `sdk` runner keeps a per-material registry of `opencode serve` CHILD
- * PROCESSES (see `opencode-sdk/sdk-runner.ts`), started lazily and reused
- * across units within a process. Each live child is an OS handle that keeps
- * Bun's event loop open — and the registry's own teardown is wired ONLY to
- * `process.once('exit')`, which never fires while such a child holds the loop
- * open. That is a deadlock: a successful `akm workflow run` that dispatched via
- * the SDK path would hang the CLI (owner finding 4) because the process is
- * never idle enough for the exit hook to run and close the children it is
- * waiting on.
- *
- * The CLI composition root and workflow engine call this in `finally` blocks to
- * drain the registry deterministically before relying on the event loop. Started
- * servers close synchronously; in-flight starts are awaited and closed on
- * arrival. When no SDK server was started this is an idempotent no-op.
- */
-export async function disposeDispatchResources() {
-    await disposeOpencodeSdkServers();
-}
-/** Collect every materialized value that can reach one runner dispatch. */
-export function collectDispatchSensitiveValues(spec, opts, envSource = opts.envSource ?? process.env) {
-    const values = new Set();
-    const add = (value) => {
-        if (value !== undefined && value.length > 0)
-            values.add(value);
-    };
-    const addConnection = (connection) => add(connection?.apiKey);
-    if (spec.kind === "llm")
-        addConnection(spec.connection);
-    if (spec.kind === "sdk")
-        addConnection(spec.fallbackConnection);
-    if (spec.kind === "llm")
-        add(lookupCredentialFromEnv(spec.credential, envSource));
-    if (spec.kind === "sdk")
-        add(lookupCredentialFromEnv(spec.fallbackCredential, envSource));
-    // #905: a file-backed credential is read at dispatch, so it must be in the
-    // scrub set for the same reason the env-backed one is.
-    if (spec.kind === "llm" && spec.apiKeyFile)
-        add(lookupApiKeyFileValue(spec.apiKeyFile));
-    if (spec.kind === "sdk" && spec.fallbackApiKeyFile)
-        add(lookupApiKeyFileValue(spec.fallbackApiKeyFile));
-    // #953: a secret-store-backed credential is read at dispatch too — same
-    // best-effort scrub-set inclusion rationale.
-    if (spec.kind === "llm" && spec.apiKeySecretRef)
-        add(lookupApiKeySecretRefValue(spec.apiKeySecretRef));
-    if (spec.kind === "sdk" && spec.fallbackApiKeySecretRef)
-        add(lookupApiKeySecretRefValue(spec.fallbackApiKeySecretRef));
-    if (spec.kind !== "llm") {
-        for (const value of Object.values(spec.profile.env ?? {}))
-            add(value);
-        for (const name of spec.profile.envPassthrough) {
-            const value = envSource[name];
-            if (!isEnvPassthroughValueSafeToExpose(name, value))
-                add(value);
+        values.push(...Object.values(runner.profile.env ?? {}));
+        for (const name of runner.profile.envPassthrough) {
+            if (!isEnvPassthroughValueSafeToExpose(name, envSource[name]))
+                values.push(envSource[name]);
         }
     }
     for (const [name, value] of Object.entries(opts.env ?? {})) {
         if (!isEnvPassthroughValueSafeToExpose(name, value))
-            add(value);
-    }
-    return collectSensitiveValues(values);
-}
-function collectNonCredentialDispatchSensitiveValues(spec, opts, envSource = opts.envSource ?? process.env, includeProfilePassthrough = true) {
-    const values = new Set();
-    const add = (value) => {
-        if (value !== undefined && value.length > 0)
-            values.add(value);
-    };
-    if (spec.kind === "llm")
-        add(spec.connection.apiKey);
-    if (spec.kind === "sdk")
-        add(spec.fallbackConnection?.apiKey);
-    if (spec.kind !== "llm") {
-        for (const value of Object.values(spec.profile.env ?? {}))
-            add(value);
-        if (includeProfilePassthrough) {
-            for (const name of spec.profile.envPassthrough) {
-                const value = envSource[name];
-                if (!isEnvPassthroughValueSafeToExpose(name, value))
-                    add(value);
-            }
-        }
-    }
-    for (const [name, value] of Object.entries(opts.env ?? {})) {
-        if (!isEnvPassthroughValueSafeToExpose(name, value))
-            add(value);
+            values.push(value);
     }
     return collectSensitiveValues(values);
 }
@@ -286,75 +57,126 @@ function redactResult(result, sensitiveValues) {
         ...(result.parsed !== undefined ? { parsed: redactSensitiveValue(result.parsed, sensitiveValues) } : {}),
     };
 }
-/**
- * Dispatch a {@link RunnerSpec} to its runner and return the raw
- * {@link AgentRunResult}. `opts` is the {@link RunAgentOptions} for the profile
- * (`agent` / `sdk`) arms. Callers keep their per-call options; a bound lease
- * replaces only `envSource` with its private immutable environment snapshot.
- */
-export async function executeRunner(spec, prompt, opts, seams = {}, lease) {
-    const withSpecOptions = (timeoutMs, workspace, environmentSource) => ({
-        ...opts,
-        ...(Object.hasOwn(opts, "timeoutMs") ? {} : timeoutMs !== undefined ? { timeoutMs } : {}),
-        ...(opts.cwd === undefined && workspace ? { cwd: workspace } : {}),
-        ...(environmentSource ? { envSource: environmentSource } : {}),
-    });
+function llmFailureReason(error) {
+    if (!(error instanceof LlmCallError))
+        return "spawn_failed";
+    switch (error.code) {
+        case "aborted":
+            return "aborted";
+        case "timeout":
+            return "timeout";
+        case "rate_limited":
+            return "llm_rate_limit";
+        case "parse_error":
+        case "provider_html_error":
+            return "parse_error";
+        default:
+            return "spawn_failed";
+    }
+}
+async function dispatchRunner(runner, prompt, opts, seams, llm) {
+    const envSource = opts.envSource ?? process.env;
+    const secrets = collectDispatchSensitiveValues(runner, opts, envSource);
     let result;
-    const dispatchSensitiveValues = [];
-    const leaseState = lease ? requireRunnerDispatchLease(lease, spec) : undefined;
-    const preDispatchSensitiveValues = leaseState
-        ? collectSensitiveValues([
-            ...leaseState.sensitiveValues,
-            ...collectNonCredentialDispatchSensitiveValues(spec, opts, undefined, false),
-        ])
-        : collectDispatchSensitiveValues(spec, opts);
-    switch (spec.kind) {
+    switch (runner.kind) {
         case "llm": {
-            if (!seams.llm) {
-                throw new Error("executeRunner: an `llm` runner requires a `seams.llm` handler (no default LLM dispatch).");
-            }
-            const connection = leaseState
-                ? materializeLlmRunnerConnectionWithCredential(spec, leaseState.primaryCredential)
-                : materializeLlmRunnerConnection(spec);
+            if (!llm)
+                throw new Error("an llm runner dispatches only a built execution's chat messages");
+            const connection = materializeLlmRunnerConnection(runner, envSource);
             if (connection.apiKey)
-                dispatchSensitiveValues.push(connection.apiKey);
-            result = await seams.llm({ ...spec, connection }, prompt, withSpecOptions(spec.timeoutMs));
+                secrets.push(connection.apiKey);
+            result = await llm(connection, opts);
             break;
         }
-        case "agent": {
-            const run = seams.runAgent ?? runAgent;
-            result = await run(spec.profile, prompt, withSpecOptions(spec.timeoutMs, spec.profile.workspace, leaseState?.environmentSource));
+        case "agent":
+            result = await (seams.runAgent ?? runAgent)(runner.profile, prompt, opts);
             break;
-        }
         case "sdk": {
-            const run = seams.runSdk ?? runOpencodeSdk;
-            const fallbackMaterial = spec.fallbackConnection
-                ? {
-                    engine: spec.engine ?? "unnamed-sdk-fallback",
-                    connection: spec.fallbackConnection,
-                    ...(spec.fallbackCredential ? { credential: spec.fallbackCredential } : {}),
-                    ...(spec.fallbackApiKeyFile ? { apiKeyFile: spec.fallbackApiKeyFile } : {}),
-                    timeoutMs: spec.fallbackTimeoutMs !== undefined
-                        ? spec.fallbackTimeoutMs
-                        : Object.hasOwn(spec.fallbackConnection, "timeoutMs")
-                            ? (spec.fallbackConnection.timeoutMs ?? null)
-                            : null,
-                }
-                : undefined;
-            const fallbackConnection = fallbackMaterial
-                ? leaseState
-                    ? materializeLlmConnectionWithCredential(fallbackMaterial, leaseState.fallbackCredential)
-                    : materializeLlmConnection(fallbackMaterial)
-                : undefined;
+            const fallbackConnection = materializeSdkFallbackConnection(runner, envSource);
             if (fallbackConnection?.apiKey)
-                dispatchSensitiveValues.push(fallbackConnection.apiKey);
-            result = await run(spec.profile, prompt, withSpecOptions(spec.timeoutMs, spec.profile.workspace, leaseState?.environmentSource), fallbackConnection);
+                secrets.push(fallbackConnection.apiKey);
+            result = await (seams.runSdk ?? runOpencodeSdk)(runner.profile, prompt, opts, fallbackConnection);
             break;
         }
         default:
-            // Exhaustiveness arm: a 4th RunnerSpec kind becomes a compile error here.
-            return assertNever(spec);
+            return assertNever(runner);
+    }
+    return redactResult(result, collectSensitiveValues(secrets));
+}
+/** Run a built execution. Credentials are read here, once per call, and never returned. */
+export async function runExecution(execution, options = {}) {
+    const opts = { ...execution.options };
+    const operational = options.runOptions ?? {};
+    for (const key of OPERATIONAL_OPTIONS) {
+        if (operational[key] !== undefined)
+            opts[key] = operational[key];
+    }
+    if (options.eventSource !== undefined) {
+        opts.env = { ...execution.options.env, AKM_EVENT_SOURCE: options.eventSource };
     }
-    const sensitiveValues = collectSensitiveValues([...preDispatchSensitiveValues, ...dispatchSensitiveValues]);
-    return redactResult(result, sensitiveValues);
+    const chat = options.chat ?? chatCompletion;
+    const llm = async (connection, callOpts) => {
+        const started = Date.now();
+        try {
+            const stdout = await chat(connection, [...(execution.messages ?? [])], {
+                ...execution.chatOptions,
+                ...(Object.hasOwn(callOpts, "timeoutMs") ? { timeoutMs: callOpts.timeoutMs } : {}),
+                ...(callOpts.signal ? { signal: callOpts.signal } : {}),
+                ...(options.onRetryAttempt ? { onRetryAttempt: options.onRetryAttempt } : {}),
+            });
+            return { ok: true, exitCode: 0, stdout, stderr: "", durationMs: Date.now() - started };
+        }
+        catch (error) {
+            // Returned rather than thrown so the redaction below covers provider bodies.
+            return {
+                ok: false,
+                exitCode: null,
+                stdout: "",
+                stderr: "",
+                durationMs: Date.now() - started,
+                error: error instanceof Error ? error.message : String(error),
+                reason: llmFailureReason(error),
+                ...(error instanceof LlmCallError ? { llmErrorCode: error.code } : {}),
+            };
+        }
+    };
+    return dispatchRunner(execution.runner, execution.prompt, opts, options, llm);
+}
+/** `akm agent`: launch an agent engine interactively, with no prompt of its own. */
+export async function executeInteractiveAgentInvocation(input, seams = {}) {
+    const runner = resolveEngine(input.engine, input.config);
+    if (runner.kind === "llm") {
+        throw new UsageError(`Engine "${input.engine}" is an LLM engine; akm agent requires an agent engine.`, "INVALID_FLAG_VALUE");
+    }
+    const opts = {
+        stdio: runner.kind === "sdk" ? runner.profile.stdio : "interactive",
+        parseOutput: "text",
+        ...(input.timeoutMs !== undefined
+            ? { timeoutMs: input.timeoutMs }
+            : runner.timeoutMs !== undefined
+                ? { timeoutMs: runner.timeoutMs }
+                : {}),
+        ...(input.cwd ? { cwd: input.cwd } : runner.profile.workspace ? { cwd: runner.profile.workspace } : {}),
+    };
+    return { engine: input.engine, result: await dispatchRunner(runner, "", opts, seams) };
+}
+/**
+ * Close the `opencode serve` children the SDK runner keeps for reuse. Its own
+ * teardown hangs off `process.once("exit")`, which never fires while a child
+ * holds the event loop open, so the CLI and workflow engine call this in
+ * `finally` blocks. A no-op when no SDK server was started.
+ */
+export async function disposeDispatchResources() {
+    await disposeOpencodeSdkServers();
+}
+/**
+ * Fail fast, before an operation makes any durable change, when `runner`'s
+ * required credential is missing. Reads it and keeps nothing: every dispatch
+ * reads it again.
+ */
+export function assertRunnerCredentials(runner, envSource) {
+    if (runner.kind === "llm")
+        materializeLlmRunnerConnection(runner, envSource);
+    if (runner.kind === "sdk")
+        materializeSdkFallbackConnection(runner, envSource);
 }

package/dist/integrations/agent/runner.js

@@ -1,28 +1,68 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { materializeLlmConnection, materializeLlmConnectionWithCredential, } from "./engine-resolution.js";
-/** Resolve the current credential value for one frozen LLM runner at dispatch. */
-export function materializeLlmRunnerConnection(runner) {
-    return materializeLlmConnection({
+import { materializeLlmConnection } from "./engine-resolution.js";
+/** The symbolic LLM use behind one llm runner; nothing is read here. */
+export function llmUseFromRunner(runner) {
+    return {
         engine: runner.engine,
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
         ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
         ...(runner.apiKeySecretRef ? { apiKeySecretRef: runner.apiKeySecretRef } : {}),
         timeoutMs: runner.timeoutMs ?? null,
-    });
+    };
 }
-/** Inject an already-snapshotted credential without consulting live process state. */
-export function materializeLlmRunnerConnectionWithCredential(runner, credentialValue) {
-    return materializeLlmConnectionWithCredential({
+/** The symbolic LLM use behind an sdk runner's provider fallback, when it has one. */
+export function sdkFallbackUseFromRunner(runner) {
+    if (!runner.fallbackConnection)
+        return undefined;
+    return {
         engine: runner.engine,
-        connection: runner.connection,
-        ...(runner.credential ? { credential: runner.credential } : {}),
-        ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
-        ...(runner.apiKeySecretRef ? { apiKeySecretRef: runner.apiKeySecretRef } : {}),
-        timeoutMs: runner.timeoutMs ?? null,
-    }, credentialValue);
+        connection: runner.fallbackConnection,
+        ...(runner.fallbackCredential ? { credential: runner.fallbackCredential } : {}),
+        ...(runner.fallbackApiKeyFile ? { apiKeyFile: runner.fallbackApiKeyFile } : {}),
+        ...(runner.fallbackApiKeySecretRef ? { apiKeySecretRef: runner.fallbackApiKeySecretRef } : {}),
+        timeoutMs: runner.fallbackTimeoutMs !== undefined ? runner.fallbackTimeoutMs : (runner.fallbackConnection.timeoutMs ?? null),
+    };
+}
+/** Read the current credential and inject it: the dispatch boundary for one llm runner. */
+export function materializeLlmRunnerConnection(runner, envSource = process.env) {
+    return materializeLlmConnection(llmUseFromRunner(runner), envSource);
+}
+/** The same for an sdk runner's provider fallback, when it has one. */
+export function materializeSdkFallbackConnection(runner, envSource = process.env) {
+    const use = sdkFallbackUseFromRunner(runner);
+    return use ? materializeLlmConnection(use, envSource) : undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Read a journaled runner back. Tolerant: unknown keys are kept and missing
+ * profile defaults are filled in; only a shape nothing could dispatch is refused.
+ */
+export function decodeFrozenRunnerSpec(value) {
+    if (!isRecord(value) || typeof value.engine !== "string") {
+        throw new TypeError("a frozen runner must be an object with an engine name");
+    }
+    if (value.kind === "llm") {
+        if (!isRecord(value.connection) || typeof value.connection.endpoint !== "string") {
+            throw new TypeError("a frozen llm runner must carry connection.endpoint");
+        }
+        return value;
+    }
+    if (value.kind !== "agent" && value.kind !== "sdk") {
+        throw new TypeError("a frozen runner's kind must be llm, agent, or sdk");
+    }
+    const profile = value.profile;
+    if (!isRecord(profile) || typeof profile.name !== "string" || typeof profile.bin !== "string") {
+        throw new TypeError("a frozen agent runner must carry profile.name and profile.bin");
+    }
+    return {
+        ...value,
+        profile: { args: [], envPassthrough: [], stdio: "captured", parseOutput: "text", ...profile },
+    };
 }
 export function runnerIsLlm(runner) {
     return runner.kind === "llm";