akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/integrations/agent/execution-lowering.js

@@ -0,0 +1,811 @@
+// 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 { ConfigError, UsageError } from "../../core/errors.js";
+import { cloneExecutionJsonObject } from "../../execution/json.js";
+import { EXECUTION_MAX_TIMEOUT_MS } from "../../execution/limits.js";
+import { assertSnapshotKeys, snapshotStrictRecord } from "../../execution/record.js";
+import { canonicalResolvedExecutionRequest, } from "../../execution/resolved-request.js";
+import { chatCompletion, LlmCallError, } from "../../llm/client.js";
+import { HARNESS_REGISTRY } from "../harnesses/index.js";
+import { resolveEngine } from "./engine-resolution.js";
+import { SDK_FALLBACK_MODEL_FROM_REQUEST_SETTING } from "./execution-definitions.js";
+import { acquireRunnerDispatchLease, assertRunnerDispatchLease, disposeRunnerDispatchLease, executeRunner, redactWithRunnerDispatchLease, } from "./runner-dispatch.js";
+export const EXECUTION_LOWERING_SCHEMA_VERSION = 1;
+const loweredExecutionInstances = new WeakSet();
+function registerLoweredExecution(value) {
+    const frozen = Object.freeze(value);
+    loweredExecutionInstances.add(frozen);
+    return frozen;
+}
+function own(value, key) {
+    return Object.hasOwn(value, key);
+}
+function sterileRecord(value) {
+    return Object.assign(Object.create(null), value);
+}
+function sortedUnique(values) {
+    return Object.freeze([...new Set(values)].sort());
+}
+function freezeNotices(values) {
+    return Object.freeze([...values]);
+}
+const SAFE_ENGINE_FALLBACK_NOTICE = Object.freeze({
+    code: "engine-fallback",
+    severity: "info",
+    adapter: "akm",
+    field: "engine",
+    message: "No engine was selected; using the fixed opencode-sdk fallback.",
+});
+const UNRECOGNIZED_REQUEST_NOTICE = Object.freeze({
+    code: "unrecognized-request-notice",
+    severity: "warning",
+    adapter: "akm",
+    message: "An unrecognized durable execution notice was omitted at the engine lowering boundary.",
+});
+/** Reconstruct durable/untrusted notices without forwarding message/details bytes. */
+function safeRequestNotices(request) {
+    let fallback = false;
+    let unknown = false;
+    for (const notice of request.notices) {
+        if (notice.code === "engine-fallback")
+            fallback = true;
+        else
+            unknown = true;
+    }
+    return Object.freeze([
+        ...(fallback ? [SAFE_ENGINE_FALLBACK_NOTICE] : []),
+        ...(unknown ? [UNRECOGNIZED_REQUEST_NOTICE] : []),
+    ]);
+}
+function untranslatedNotice(adapter, field) {
+    return Object.freeze({
+        code: "untranslated-field",
+        severity: "warning",
+        adapter,
+        field,
+        message: `The ${adapter} lowerer does not translate resolved field ${field}; dispatch will continue optimistically.`,
+    });
+}
+function requireAuthorizedRequest(request) {
+    // The canonical round trip is the public brand/prototype/accessor guard. It
+    // deliberately happens before config or registry access.
+    canonicalResolvedExecutionRequest(request);
+    if (request.authorization.status === "denied") {
+        throw new ConfigError(request.authorization.reason ?? "Resolved execution is not authorized by operator policy.", "EXECUTION_NOT_AUTHORIZED");
+    }
+    return request;
+}
+function snapshotConfig(config) {
+    return cloneExecutionJsonObject(config, "execution lowering config");
+}
+function assertKeys(value, allowed, path) {
+    const allowedKeys = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key))
+            throw new TypeError(`${path} contains unsupported field: ${key}`);
+    }
+}
+function requireStringField(value, key, path) {
+    const field = value[key];
+    if (typeof field !== "string")
+        throw new TypeError(`${path}.${key} must be a string`);
+    return field;
+}
+function validateOptionalString(value, key, path) {
+    if (own(value, key) && typeof value[key] !== "string")
+        throw new TypeError(`${path}.${key} must be a string`);
+}
+function validateTimeout(value, path) {
+    if (value !== null &&
+        (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > EXECUTION_MAX_TIMEOUT_MS)) {
+        throw new TypeError(`${path} must be null or an integer from 0 through ${EXECUTION_MAX_TIMEOUT_MS}`);
+    }
+}
+function validateStringArray(value, path, allowEmpty = true) {
+    if (!Array.isArray(value) ||
+        (!allowEmpty && value.length === 0) ||
+        value.some((entry) => typeof entry !== "string")) {
+        throw new TypeError(`${path} must be ${allowEmpty ? "an" : "a non-empty"} array of strings`);
+    }
+}
+function validateCredential(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${path} must be an object`);
+    const record = value;
+    assertKeys(record, ["names", "required"], path);
+    validateStringArray(record.names, `${path}.names`, false);
+    if (typeof record.required !== "boolean")
+        throw new TypeError(`${path}.required must be a boolean`);
+}
+function validateConnection(value, path, requireModel = true) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${path} must be an object`);
+    const record = value;
+    requireStringField(record, "endpoint", path);
+    if (requireModel || own(record, "model"))
+        requireStringField(record, "model", path);
+    if (own(record, "apiKey")) {
+        throw new TypeError(`${path}.apiKey must remain a symbolic credential and cannot be frozen as secret material`);
+    }
+}
+function validateProfile(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${path} must be an object`);
+    const record = value;
+    assertKeys(record, [
+        "name",
+        "platform",
+        "personaChannel",
+        "workspace",
+        "bin",
+        "args",
+        "stdio",
+        "env",
+        "envPassthrough",
+        "parseOutput",
+        "model",
+    ], path);
+    requireStringField(record, "name", path);
+    requireStringField(record, "bin", path);
+    validateOptionalString(record, "platform", path);
+    validateOptionalString(record, "workspace", path);
+    validateOptionalString(record, "model", path);
+    validateStringArray(record.args, `${path}.args`);
+    validateStringArray(record.envPassthrough, `${path}.envPassthrough`);
+    if (record.stdio !== "captured" && record.stdio !== "interactive") {
+        throw new TypeError(`${path}.stdio is invalid`);
+    }
+    if (record.parseOutput !== "text" && record.parseOutput !== "json") {
+        throw new TypeError(`${path}.parseOutput is invalid`);
+    }
+    if (own(record, "personaChannel") && record.personaChannel !== "native" && record.personaChannel !== "prompt") {
+        throw new TypeError(`${path}.personaChannel is invalid`);
+    }
+    if (own(record, "env")) {
+        const env = record.env;
+        if (env === null ||
+            typeof env !== "object" ||
+            Array.isArray(env) ||
+            Object.values(env).some((entry) => typeof entry !== "string")) {
+            throw new TypeError(`${path}.env must be an object of strings`);
+        }
+    }
+}
+/** Durable runner material may contain ordinary literals, never credential-shaped bytes. */
+function runnerEnvironmentValueLooksSecret(name, value) {
+    const key = name.toLowerCase();
+    if ([
+        "secret",
+        "token",
+        "password",
+        "passwd",
+        "apikey",
+        "api_key",
+        "api-key",
+        "accesskey",
+        "access_key",
+        "privatekey",
+        "private_key",
+        "credential",
+        "bearer",
+        "client_secret",
+    ].some((hint) => key.includes(hint))) {
+        return true;
+    }
+    const candidate = value.trim();
+    if (candidate.length < 20 || /\s/.test(candidate))
+        return false;
+    if (/^(?:sk-|rk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[baprs]-|AKIA|ASIA|AIza|ya29\.|-----BEGIN)/.test(candidate)) {
+        return true;
+    }
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((pattern) => pattern.test(candidate)).length;
+    return (candidate.length >= 24 && classes >= 3) || (candidate.length >= 32 && /^[A-Za-z0-9+/=_-]+$/.test(candidate));
+}
+/** Strictly detach and deep-freeze non-secret runner material before lowering. */
+function snapshotRunnerSpec(input, options = {}) {
+    const cloned = cloneExecutionJsonObject(input, "execution runner material");
+    const kind = cloned.kind;
+    validateOptionalString(cloned, "engine", "execution runner material");
+    if (own(cloned, "timeoutMs"))
+        validateTimeout(cloned.timeoutMs, "execution runner material.timeoutMs");
+    if (kind === "llm") {
+        assertKeys(cloned, ["kind", "engine", "connection", "credential", "timeoutMs"], "execution runner material");
+        validateConnection(cloned.connection, "execution runner material.connection", !options.allowMissingLlmModel);
+        if (own(cloned, "credential"))
+            validateCredential(cloned.credential, "execution runner material.credential");
+    }
+    else if (kind === "agent") {
+        assertKeys(cloned, ["kind", "engine", "profile", "timeoutMs"], "execution runner material");
+        validateProfile(cloned.profile, "execution runner material.profile");
+    }
+    else if (kind === "sdk") {
+        assertKeys(cloned, ["kind", "engine", "profile", "fallbackConnection", "fallbackCredential", "fallbackTimeoutMs", "timeoutMs"], "execution runner material");
+        validateProfile(cloned.profile, "execution runner material.profile");
+        if (own(cloned, "fallbackConnection")) {
+            validateConnection(cloned.fallbackConnection, "execution runner material.fallbackConnection", !options.allowMissingSdkFallbackModel);
+        }
+        if (own(cloned, "fallbackCredential")) {
+            validateCredential(cloned.fallbackCredential, "execution runner material.fallbackCredential");
+        }
+        if (own(cloned, "fallbackTimeoutMs")) {
+            validateTimeout(cloned.fallbackTimeoutMs, "execution runner material.fallbackTimeoutMs");
+        }
+    }
+    else {
+        throw new TypeError("execution runner material.kind must be llm, agent, or sdk");
+    }
+    return cloned;
+}
+/** Strict public decoder for persisted, non-secret runner/transport material. */
+export function decodeFrozenRunnerSpec(input) {
+    const runner = snapshotRunnerSpec(input);
+    if (runner.kind !== "llm") {
+        for (const [name, value] of Object.entries(runner.profile.env ?? {})) {
+            if (runnerEnvironmentValueLooksSecret(name, value)) {
+                throw new TypeError("execution runner material.profile.env contains a secret-shaped literal; freeze only symbolic environment names");
+            }
+        }
+    }
+    return runner;
+}
+function lowererEntries() {
+    return HARNESS_REGISTRY.map((harness) => {
+        const lowerer = harness.agentBuilder?.lower !== undefined
+            ? {
+                platform: harness.agentBuilder.platform,
+                personaChannel: harness.agentBuilder.personaChannel,
+                lower: harness.agentBuilder.lower,
+            }
+            : harness.executionLowerer;
+        if (!lowerer) {
+            throw new Error(`dispatch harness ${harness.id} has no registered resolved-request lowerer`);
+        }
+        if (lowerer.platform !== harness.id) {
+            throw new Error(`dispatch harness ${harness.id} registered mismatched lowerer ${lowerer.platform}`);
+        }
+        return [harness.id, lowerer];
+    });
+}
+const AGENT_LOWERERS = new Map(lowererEntries());
+function requireRunnerShape(request, runner) {
+    if (!own(runner, "engine") || runner.engine !== request.engine.name) {
+        throw new ConfigError(`Resolved engine ${JSON.stringify(request.engine.name)} changed engine identity before lowering.`, "INVALID_CONFIG_FILE");
+    }
+    if (request.engine.kind !== runner.kind) {
+        throw new ConfigError(`Resolved engine ${JSON.stringify(request.engine.name)} changed transport kind before lowering.`, "INVALID_CONFIG_FILE");
+    }
+    const platform = own(request.engine, "platform") ? request.engine.platform : undefined;
+    const runnerPlatform = runner.kind === "llm"
+        ? (runner.connection.provider ?? runner.engine)
+        : (runner.profile.platform ?? runner.profile.name);
+    // A selected platform is an identity binding rather than a capability hint.
+    if (typeof platform === "string" && platform !== runnerPlatform) {
+        throw new ConfigError(`Resolved engine ${JSON.stringify(request.engine.name)} changed provider/harness platform before lowering.`, "INVALID_CONFIG_FILE");
+    }
+}
+const LLM_CALL_ERROR_CODES = new Set([
+    "aborted",
+    "timeout",
+    "rate_limited",
+    "parse_error",
+    "provider_html_error",
+    "network_error",
+    "provider_error",
+]);
+function safeLlmCallErrorCode(error) {
+    if (!(error instanceof LlmCallError))
+        return undefined;
+    const descriptor = Reflect.getOwnPropertyDescriptor(error, "code");
+    if (!descriptor || !("value" in descriptor) || !LLM_CALL_ERROR_CODES.has(descriptor.value)) {
+        return undefined;
+    }
+    return descriptor.value;
+}
+function directLlmFailure(error) {
+    const code = safeLlmCallErrorCode(error);
+    if (!code)
+        return { reason: "spawn_failed" };
+    switch (code) {
+        case "aborted":
+            return { reason: "aborted", code };
+        case "timeout":
+            return { reason: "timeout", code };
+        case "rate_limited":
+            return { reason: "llm_rate_limit", code };
+        case "parse_error":
+        case "provider_html_error":
+            return { reason: "parse_error", code };
+        case "network_error":
+        case "provider_error":
+            return { reason: "spawn_failed", code };
+    }
+}
+function safeCaughtErrorMessage(error) {
+    if (typeof error === "string")
+        return error;
+    if (error instanceof Error) {
+        const descriptor = Reflect.getOwnPropertyDescriptor(error, "message");
+        if (descriptor && "value" in descriptor && typeof descriptor.value === "string")
+            return descriptor.value;
+    }
+    if (error === null || error === undefined || typeof error === "number" || typeof error === "boolean") {
+        return String(error);
+    }
+    return "LLM transport failed.";
+}
+function requestRuntimeOptions(request) {
+    const options = sterileRecord({ stdio: "captured", parseOutput: "text" });
+    if (own(request.runtime, "timeoutMs"))
+        options.timeoutMs = request.runtime.timeoutMs;
+    if (own(request.runtime, "workspace") && typeof request.runtime.workspace === "string") {
+        options.cwd = request.runtime.workspace;
+    }
+    if (own(request.runtime, "environment") && request.runtime.environment !== null) {
+        options.env = request.runtime.environment;
+    }
+    return Object.freeze(options);
+}
+function projectAgentRunner(base, request) {
+    const settings = own(request.engine, "settings") ? request.engine.settings : undefined;
+    const profile = sterileRecord({ ...base.profile });
+    delete profile.model;
+    delete profile.workspace;
+    if (own(request, "model") && request.model) {
+        profile.model = request.model.resolved;
+    }
+    if (own(request.runtime, "workspace") && typeof request.runtime.workspace === "string") {
+        profile.workspace = request.runtime.workspace;
+    }
+    if (settings) {
+        if (own(settings, "bin") && typeof settings.bin === "string")
+            profile.bin = settings.bin;
+        if (own(settings, "args") &&
+            Array.isArray(settings.args) &&
+            settings.args.every((entry) => typeof entry === "string")) {
+            profile.args = Object.freeze([...settings.args]);
+        }
+    }
+    const common = {
+        ...base,
+        profile: Object.freeze(profile),
+    };
+    const sdkFallbackModelFromRequest = base.kind === "sdk" &&
+        settings !== null &&
+        settings !== undefined &&
+        own(settings, SDK_FALLBACK_MODEL_FROM_REQUEST_SETTING);
+    const clearsSdkFallbackModel = base.kind === "sdk" && base.fallbackConnection !== undefined && request.model === null;
+    if (sdkFallbackModelFromRequest && settings?.[SDK_FALLBACK_MODEL_FROM_REQUEST_SETTING] !== true) {
+        throw new ConfigError("Resolved SDK fallback model marker is invalid.", "INVALID_CONFIG_FILE");
+    }
+    if (sdkFallbackModelFromRequest && (!base.fallbackConnection || !own(request, "model"))) {
+        throw new ConfigError("Resolved SDK fallback model material is incomplete.", "INVALID_CONFIG_FILE");
+    }
+    if (base.kind === "sdk" && base.fallbackConnection) {
+        const fallbackConnection = sterileRecord({ ...base.fallbackConnection });
+        if (sdkFallbackModelFromRequest || clearsSdkFallbackModel) {
+            delete fallbackConnection.model;
+            if (sdkFallbackModelFromRequest && request.model)
+                fallbackConnection.model = request.model.resolved;
+        }
+        if (own(request, "inference")) {
+            for (const key of LLM_INFERENCE_CONNECTION_FIELDS)
+                delete fallbackConnection[key];
+            if (request.inference) {
+                for (const key of LLM_INFERENCE_CONNECTION_FIELDS) {
+                    if (own(request.inference, key))
+                        fallbackConnection[key] = request.inference[key];
+                }
+            }
+        }
+        common.fallbackConnection = Object.freeze(fallbackConnection);
+    }
+    delete common.timeoutMs;
+    if (own(request.runtime, "timeoutMs"))
+        common.timeoutMs = request.runtime.timeoutMs;
+    else if (own(base, "timeoutMs"))
+        common.timeoutMs = base.timeoutMs;
+    return snapshotRunnerSpec(common, {
+        allowMissingSdkFallbackModel: clearsSdkFallbackModel,
+    });
+}
+function selectedExtensionPaths(request) {
+    const out = [];
+    if (own(request, "extensions"))
+        out.push("extensions");
+    if (own(request.command, "extensions"))
+        out.push("command.extensions");
+    const persona = own(request, "persona") ? request.persona : undefined;
+    if (persona && own(persona, "extensions"))
+        out.push("persona.extensions");
+    if (own(request.engine, "extensions"))
+        out.push("engine.extensions");
+    if (own(request.runtime, "extensions"))
+        out.push("runtime.extensions");
+    return out;
+}
+const LLM_INFERENCE_CONNECTION_FIELDS = new Set([
+    "temperature",
+    "maxTokens",
+    "supportsJsonSchema",
+    "extraParams",
+    "contextLength",
+    "enableThinking",
+    "reasoningEffort",
+]);
+function projectLlmRunner(base, request) {
+    const connection = sterileRecord({ ...base.connection });
+    for (const key of [
+        "model",
+        "temperature",
+        "maxTokens",
+        "supportsJsonSchema",
+        "extraParams",
+        "contextLength",
+        "enableThinking",
+        "reasoningEffort",
+    ]) {
+        delete connection[key];
+    }
+    const settings = own(request.engine, "settings") ? request.engine.settings : undefined;
+    if (settings) {
+        if (own(settings, "endpoint") && typeof settings.endpoint === "string")
+            connection.endpoint = settings.endpoint;
+        if (own(settings, "provider") && typeof settings.provider === "string")
+            connection.provider = settings.provider;
+    }
+    if (own(request, "model") && request.model)
+        connection.model = request.model.resolved;
+    const inference = own(request, "inference") ? request.inference : undefined;
+    if (inference) {
+        for (const key of LLM_INFERENCE_CONNECTION_FIELDS) {
+            if (own(inference, key))
+                connection[key] = inference[key];
+        }
+    }
+    const projected = {
+        ...base,
+        connection: Object.freeze(connection),
+    };
+    delete projected.timeoutMs;
+    if (own(request.runtime, "timeoutMs"))
+        projected.timeoutMs = request.runtime.timeoutMs;
+    else if (own(base, "timeoutMs"))
+        projected.timeoutMs = base.timeoutMs;
+    return snapshotRunnerSpec(projected, { allowMissingLlmModel: true });
+}
+function lowerAgent(request, base) {
+    const platform = own(request.engine, "platform") ? request.engine.platform : undefined;
+    if (typeof platform !== "string") {
+        throw new ConfigError(`Resolved agent engine ${JSON.stringify(request.engine.name)} has no platform.`, "INVALID_CONFIG_FILE");
+    }
+    const lowerer = AGENT_LOWERERS.get(platform);
+    if (!lowerer) {
+        throw new ConfigError(`Agent platform ${JSON.stringify(platform)} has no registered lowerer.`, "INVALID_CONFIG_FILE");
+    }
+    const runner = projectAgentRunner(base, request);
+    const lowered = lowerer.lower(runner.profile, request);
+    const options = Object.freeze(sterileRecord({ ...requestRuntimeOptions(request), dispatch: lowered.dispatch }));
+    return registerLoweredExecution({
+        schemaVersion: EXECUTION_LOWERING_SCHEMA_VERSION,
+        request,
+        adapter: platform,
+        runner,
+        prompt: lowered.prompt,
+        dispatch: lowered.dispatch,
+        options,
+        translatedFields: sortedUnique([
+            ...lowered.translatedFields,
+            ...(own(request.engine, "settings") ? ["engine.settings"] : []),
+        ]),
+        untranslatedFields: lowered.untranslatedFields,
+        notices: freezeNotices([...safeRequestNotices(request), ...lowered.notices]),
+    });
+}
+function lowerLlm(request, base) {
+    const runner = projectLlmRunner(base, request);
+    const translated = new Set(["command.content", "engine"]);
+    const untranslated = new Set();
+    const notices = [...safeRequestNotices(request)];
+    const reject = (field) => {
+        untranslated.add(field);
+        notices.push(untranslatedNotice("llm", field));
+    };
+    if (own(request.engine, "settings"))
+        translated.add("engine.settings");
+    if (own(request, "model"))
+        translated.add("model");
+    if (own(request, "persona"))
+        translated.add("persona");
+    if (own(request, "agent")) {
+        if (typeof request.agent === "string" && request.persona === null) {
+            throw new ConfigError(`The direct LLM transport cannot consume native agent selector ${JSON.stringify(request.agent)}.`, "INVALID_CONFIG_FILE");
+        }
+        translated.add("agent");
+    }
+    if (own(request, "conversation"))
+        translated.add("conversation");
+    if (own(request, "inference")) {
+        const inference = request.inference;
+        if (inference && Object.keys(inference).length > 0) {
+            for (const key of Object.keys(inference).sort()) {
+                const field = `inference.${key}`;
+                if (LLM_INFERENCE_CONNECTION_FIELDS.has(key))
+                    translated.add(field);
+                else
+                    reject(field);
+            }
+        }
+        else {
+            translated.add("inference");
+        }
+    }
+    const chatOptions = sterileRecord({});
+    if (own(request.runtime, "timeoutMs")) {
+        translated.add("runtime.timeoutMs");
+        chatOptions.timeoutMs = request.runtime.timeoutMs;
+    }
+    if (own(request, "outputSchema")) {
+        if (request.outputSchema === null)
+            translated.add("outputSchema");
+        else if (runner.connection.supportsJsonSchema === true) {
+            translated.add("outputSchema");
+            chatOptions.responseSchema = request.outputSchema;
+        }
+        else
+            reject("outputSchema");
+    }
+    if (own(request, "tools")) {
+        const tools = request.tools;
+        const empty = tools === null ||
+            tools === "" ||
+            (Array.isArray(tools) && tools.length === 0) ||
+            (typeof tools === "object" && tools !== null && !Array.isArray(tools) && Object.keys(tools).length === 0);
+        if (empty)
+            translated.add("tools");
+        else
+            reject("tools");
+    }
+    if (own(request.runtime, "workspace")) {
+        if (request.runtime.workspace === null || request.runtime.workspace === "")
+            translated.add("runtime.workspace");
+        else
+            reject("runtime.workspace");
+    }
+    if (own(request.runtime, "environment")) {
+        const environment = request.runtime.environment;
+        if (environment === null || environment === undefined || Object.keys(environment).length === 0) {
+            translated.add("runtime.environment");
+        }
+        else
+            reject("runtime.environment");
+    }
+    if (own(request.runtime, "settings")) {
+        const settings = request.runtime.settings;
+        if (settings === null || settings === undefined || Object.keys(settings).length === 0) {
+            translated.add("runtime.settings");
+        }
+        else
+            reject("runtime.settings");
+    }
+    for (const field of selectedExtensionPaths(request))
+        reject(field);
+    const messages = Object.freeze([
+        ...(own(request, "persona") && request.persona
+            ? [{ role: "system", content: request.persona.content }]
+            : []),
+        ...(request.conversation ?? []),
+        { role: "user", content: request.command.content },
+    ].map((message) => Object.freeze({ role: message.role, content: message.content })));
+    return registerLoweredExecution({
+        schemaVersion: EXECUTION_LOWERING_SCHEMA_VERSION,
+        request,
+        adapter: "llm",
+        runner,
+        prompt: request.command.content,
+        messages,
+        chatOptions: Object.freeze(chatOptions),
+        options: requestRuntimeOptions(request),
+        translatedFields: sortedUnique(translated),
+        untranslatedFields: sortedUnique(untranslated),
+        notices: freezeNotices(notices),
+    });
+}
+/** The sole live-config engine resolver used by every current execution mode. */
+function resolveSnapshotRunner(engine, config) {
+    return snapshotRunnerSpec(resolveEngine(engine, config));
+}
+/**
+ * Lower one payload-free interactive launch. The input vocabulary is closed:
+ * there is deliberately no command, prompt, model, tool, or arbitrary env.
+ */
+function lowerInteractiveAgentExecution(input) {
+    if (typeof input.engine !== "string" || input.engine.length === 0) {
+        throw new TypeError("interactive agent execution input.engine must be a non-empty string");
+    }
+    if (input.timeoutMs !== undefined) {
+        validateTimeout(input.timeoutMs, "interactive agent execution input.timeoutMs");
+    }
+    if (input.cwd !== undefined && typeof input.cwd !== "string") {
+        throw new TypeError("interactive agent execution input.cwd must be a string");
+    }
+    const runner = resolveSnapshotRunner(input.engine, snapshotConfig(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 options = Object.freeze(sterileRecord({
+        stdio: runner.kind === "sdk" ? runner.profile.stdio : "interactive",
+        parseOutput: "text",
+        ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        ...(input.cwd ? { cwd: input.cwd } : {}),
+    }));
+    return Object.freeze({
+        engine: input.engine,
+        runner,
+        options,
+    });
+}
+/**
+ * The one optimistic lowering boundary. Authorization and request-brand
+ * validation precede config, registry, credential, and transport work.
+ */
+export function lowerResolvedExecutionRequest(input, config) {
+    const request = requireAuthorizedRequest(input);
+    const frozenConfig = snapshotConfig(config);
+    const base = resolveSnapshotRunner(request.engine.name, frozenConfig);
+    requireRunnerShape(request, base);
+    return base.kind === "llm" ? lowerLlm(request, base) : lowerAgent(request, base);
+}
+/**
+ * Lower from already-frozen, symbolic runner material. Workflow resume uses
+ * this entry point so no live config, alias, environment, or credential lookup
+ * can alter a journaled request before dispatch.
+ */
+export function lowerResolvedExecutionRequestWithRunner(input, runner) {
+    const request = requireAuthorizedRequest(input);
+    const base = snapshotRunnerSpec(runner);
+    requireRunnerShape(request, base);
+    return base.kind === "llm" ? lowerLlm(request, base) : lowerAgent(request, base);
+}
+function requireLoweredExecutionProvenance(lowered) {
+    if (typeof lowered !== "object" ||
+        lowered === null ||
+        !loweredExecutionInstances.has(lowered) ||
+        !Object.isFrozen(lowered)) {
+        throw new TypeError("lowered execution request must be produced by the engine lowerer registry");
+    }
+    canonicalResolvedExecutionRequest(lowered.request);
+}
+/**
+ * Acquire an opaque operation capability only after genuine lowered-request
+ * provenance and canonical authorization have been revalidated.
+ */
+export function acquireLoweredExecutionDispatchLease(lowered, options = {}) {
+    requireLoweredExecutionProvenance(lowered);
+    const optionSnapshot = snapshotStrictRecord(options, "dispatch lease acquisition options");
+    assertSnapshotKeys(optionSnapshot, ["envSource"], "dispatch lease acquisition options");
+    const strictOptions = optionSnapshot;
+    return acquireRunnerDispatchLease(lowered.runner, strictOptions.envSource ?? process.env);
+}
+/** Idempotently scrub and invalidate a genuine operation dispatch lease. */
+export function disposeLoweredExecutionDispatchLease(lease) {
+    disposeRunnerDispatchLease(lease);
+}
+/** Redact text with a lease's private credential inventory without exposing it. */
+export function redactWithLoweredExecutionDispatchLease(lease, value) {
+    return redactWithRunnerDispatchLease(lease, value);
+}
+/** One raw runner symbol reference for every shared execution dispatch mode. */
+function runnerDispatcher(candidate) {
+    return candidate ?? executeRunner;
+}
+async function dispatchLoweredInteractiveAgentExecution(lowered, seams) {
+    const lease = acquireRunnerDispatchLease(lowered.runner, process.env);
+    try {
+        return await runnerDispatcher()(lowered.runner, "", lowered.options, {
+            ...(seams.runAgent ? { runAgent: seams.runAgent } : {}),
+            ...(seams.runSdk ? { runSdk: seams.runSdk } : {}),
+        }, lease);
+    }
+    finally {
+        disposeRunnerDispatchLease(lease);
+    }
+}
+/** Resolve, lower, and dispatch one native interactive agent invocation. */
+export async function executeInteractiveAgentInvocation(input, seams = {}) {
+    const lowered = lowerInteractiveAgentExecution(input);
+    return {
+        engine: lowered.engine,
+        result: await dispatchLoweredInteractiveAgentExecution(lowered, seams),
+    };
+}
+/** Dispatch a previously lowered request without re-resolving any model, ref, or persona. */
+export async function dispatchLoweredExecutionRequest(lowered, options = {}) {
+    requireLoweredExecutionProvenance(lowered);
+    const optionSnapshot = snapshotStrictRecord(options, "lowered execution dispatch options");
+    assertSnapshotKeys(optionSnapshot, ["executeRunner", "chat", "onRetryAttempt", "runAgent", "runSdk", "lease", "runOptions"], "lowered execution dispatch options");
+    const strictOptions = optionSnapshot;
+    if (strictOptions.onRetryAttempt !== undefined && typeof strictOptions.onRetryAttempt !== "function") {
+        throw new TypeError("lowered execution dispatch options.onRetryAttempt must be a function");
+    }
+    const usesDefaultRunner = strictOptions.executeRunner === undefined;
+    const run = runnerDispatcher(strictOptions.executeRunner);
+    const operationalSnapshot = snapshotStrictRecord(strictOptions.runOptions ?? {}, "lowered execution operational options");
+    assertSnapshotKeys(operationalSnapshot, [
+        "stdio",
+        "timeoutMs",
+        "parseOutput",
+        "env",
+        "cwd",
+        "args",
+        "stdin",
+        "signal",
+        "envSource",
+        "spawn",
+        "setTimeoutFn",
+        "clearTimeoutFn",
+        "onEvent",
+        "dispatch",
+        "builderRegistry",
+    ], "lowered execution operational options");
+    const operational = operationalSnapshot;
+    const runOptions = sterileRecord({
+        ...lowered.options,
+        ...(operational.stdio !== undefined ? { stdio: operational.stdio } : {}),
+        ...(operational.parseOutput !== undefined ? { parseOutput: operational.parseOutput } : {}),
+        ...(operational.signal !== undefined ? { signal: operational.signal } : {}),
+        ...(operational.envSource !== undefined ? { envSource: operational.envSource } : {}),
+        ...(operational.spawn !== undefined ? { spawn: operational.spawn } : {}),
+        ...(operational.setTimeoutFn !== undefined ? { setTimeoutFn: operational.setTimeoutFn } : {}),
+        ...(operational.clearTimeoutFn !== undefined ? { clearTimeoutFn: operational.clearTimeoutFn } : {}),
+        ...(operational.onEvent !== undefined ? { onEvent: operational.onEvent } : {}),
+    });
+    const ownedLease = strictOptions.lease === undefined && usesDefaultRunner;
+    const lease = strictOptions.lease ??
+        (ownedLease ? acquireRunnerDispatchLease(lowered.runner, runOptions.envSource ?? process.env) : undefined);
+    if (lease)
+        assertRunnerDispatchLease(lease, lowered.runner);
+    try {
+        return await run(lowered.runner, lowered.prompt, runOptions, {
+            ...(strictOptions.runAgent ? { runAgent: strictOptions.runAgent } : {}),
+            ...(strictOptions.runSdk ? { runSdk: strictOptions.runSdk } : {}),
+            ...("messages" in lowered
+                ? {
+                    llm: async (spec, _prompt, runOptions) => {
+                        const started = Date.now();
+                        try {
+                            const stdout = await (strictOptions.chat ?? chatCompletion)(spec.connection, [...lowered.messages], {
+                                ...lowered.chatOptions,
+                                ...(!own(lowered.chatOptions, "timeoutMs") && own(runOptions, "timeoutMs")
+                                    ? { timeoutMs: runOptions.timeoutMs }
+                                    : {}),
+                                ...(runOptions.signal ? { signal: runOptions.signal } : {}),
+                                ...(strictOptions.onRetryAttempt ? { onRetryAttempt: strictOptions.onRetryAttempt } : {}),
+                            });
+                            return { ok: true, exitCode: 0, stdout, stderr: "", durationMs: Date.now() - started };
+                        }
+                        catch (error) {
+                            // Return through executeRunner so its credential-aware redactor
+                            // handles provider bodies before any caller can persist them.
+                            const failure = directLlmFailure(error);
+                            return {
+                                ok: false,
+                                exitCode: null,
+                                stdout: "",
+                                stderr: "",
+                                durationMs: Date.now() - started,
+                                error: safeCaughtErrorMessage(error),
+                                reason: failure.reason,
+                                ...(failure.code ? { llmErrorCode: failure.code } : {}),
+                            };
+                        }
+                    },
+                }
+                : {}),
+        }, lease);
+    }
+    finally {
+        if (ownedLease && lease)
+            disposeRunnerDispatchLease(lease);
+    }
+}