@mininglamp-oss/octo-runtime 0.0.0-stage → 1.0.0

package/node_modules/@mininglamp-oss/octo-runtime-adapter-host/dist/index.js

@@ -0,0 +1,913 @@
+import { prepareInvokeInput } from "@mininglamp-oss/octo-runtime-core";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { sanitizePublicValue } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+export { HostRunService } from "./host-run-service.js";
+export { readAdapterConfigurations } from "./runtime-configuration.js";
+export { startHostSocketServer, streamHostRun } from "./socket-server.js";
+export { prepareRunContext } from "./execution-preparation.js";
+import { createInputInvoke, assertInvokeRequestSize, assertProtocolSupport, assertAdapterProtocolSupport, assertHostFrame, assertHostFrameIdentity, assertNativeInteractionResponse, resolveHostInvokeOptions, protocolError, assertCanonicalEvent, assertInteractionResponse, assertInvokeRequest, failurePayload, isTerminal } from "@mininglamp-oss/octo-runtime-protocol";
+import { InvocationExperience } from "./experience.js";
+import { withModelContexts } from "./model-input.js";
+import { noopRuntimeLog } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+import { AdapterWatchdogTimeoutError, InvocationWatchdog } from "./watchdog.js";
+/**
+ * The in-process registry and lifecycle gatekeeper for adapters.
+ * It validates plugin input/output, fills in the message lifecycle, guarantees
+ * a single terminal, and turns cancellation into an AbortSignal.
+ */
+export class AdapterHost {
+    // F31：.octospec/tasks/gateway-august-feature-assessment/assessment.md
+    #log;
+    constructor(options = {}) {
+        const log = options.log ?? noopRuntimeLog;
+        this.#log = (level, event, data) => {
+            try {
+                log(level, event, data);
+            }
+            catch {
+                /* 宿主诊断不影响执行。 */
+            }
+        };
+    }
+    invoke = createInputInvoke((input, environment) => this.invokeFrames(input, environment));
+    #adapters = new Map();
+    #active = new Map();
+    #activeAdapters = new Map();
+    #acceptedTerminals = new Set();
+    #runs = new Map();
+    #modes = new Map();
+    /** Register an adapter by `metadata.type`; the same type cannot be overwritten twice. */
+    register(adapter) {
+        assertAdapterProtocolSupport(adapter.metadata.protocolSupport);
+        if (this.#adapters.has(adapter.metadata.type))
+            throw new Error(`duplicate adapter: ${adapter.metadata.type}`);
+        this.#adapters.set(adapter.metadata.type, adapter);
+    }
+    /** List registered adapters, for Agent registration and control-plane display. */
+    list() {
+        return [...this.#adapters.values()].map((adapter) => ({
+            ...adapter.metadata,
+            protocolSupport: this.#support(adapter)
+        }));
+    }
+    /** Report installed provider identity separately from adapter registration. */
+    async describe(configurations = {}) {
+        return Promise.all([...this.#adapters.values()].map(async (adapter) => {
+            let probe = {};
+            let unavailableReason = adapter.probe ? "probe_invalid" : "probe_missing";
+            let timer;
+            try {
+                const result = await Promise.race([
+                    Promise.resolve().then(() => adapter.probe?.(configurations[adapter.metadata.type])),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => {
+                            unavailableReason = "probe_timeout";
+                            resolve(undefined);
+                        }, 3_000);
+                    })
+                ]);
+                if (result && typeof result === "object")
+                    probe = result;
+                if (probe.available === false)
+                    unavailableReason =
+                        typeof probe.reason === "string" ? probe.reason : "provider_unavailable";
+            }
+            catch {
+                unavailableReason = "probe_failed";
+                // A failed probe must not make the whole adapter host unavailable.
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+            const available = probe.available === true && typeof probe.command === "string" && probe.command.length > 0;
+            return {
+                ...adapter.metadata,
+                protocolSupport: this.#support(adapter),
+                available,
+                unavailableReason: available ? null : unavailableReason,
+                providerPath: available ? probe.command : null,
+                providerVersion: typeof probe.version === "string" ? probe.version : null
+            };
+        }));
+    }
+    #support(adapter) {
+        const support = adapter.metadata.protocolSupport;
+        assertAdapterProtocolSupport(support);
+        return support;
+    }
+    /** Admission runs before RPC acknowledgement and never starts a provider. */
+    #prepare(adapterType, request, options = {}) {
+        const resolved = resolveHostInvokeOptions(options);
+        assertInvokeRequest(request);
+        const registered = this.#adapters.get(adapterType);
+        if (!registered)
+            throw new Error(`unknown adapter: ${adapterType}`);
+        const support = this.#support(registered);
+        assertProtocolSupport(support, resolved);
+        if (request.approvalMode !== "full_access" &&
+            (resolved.protocolMode === "native"
+                ? typeof registered.respondNative !== "function"
+                : typeof registered.respondInteraction !== "function")) {
+            throw new Error(`APPROVAL_MODE_UNSUPPORTED: ${adapterType} does not implement execution-time approval responses`);
+        }
+        if (!registered?.metadata.agentSources.includes(request.agentSource))
+            throw new Error("AGENT_SOURCE_UNSUPPORTED: " + adapterType);
+        const { signal: _signal, ...wire } = request;
+        void _signal;
+        const fingerprint = createHash("sha256")
+            .update(stableJson([adapterType, resolved.protocolMode, support.protocol, wire]))
+            .digest("hex");
+        const existing = this.#runs.get(request.invocationId);
+        if (existing) {
+            if (existing.fingerprint !== fingerprint)
+                throw protocolError("EXECUTION_IDENTITY_CONFLICT");
+            return { ...existing.receipt };
+        }
+        for (const [id, run] of this.#runs) {
+            if (!this.#active.has(id) && Date.now() - run.at > 120_000)
+                this.#runs.delete(id);
+        }
+        if (this.#runs.size >= 1024)
+            throw new Error("RUN_CAPACITY_EXHAUSTED");
+        if ([...this.#runs.values()].some((run) => run.receipt.run_id === request.runId))
+            throw protocolError("EXECUTION_IDENTITY_CONFLICT");
+        const receipt = {
+            run_id: request.runId,
+            invocation_id: request.invocationId,
+            stream_id: `host:${randomUUID()}`,
+            agent_session_id: request.agentSessionId,
+            session_generation: request.sessionGeneration ?? 0,
+            protocol_mode: resolved.protocolMode,
+            protocol: support.protocol
+        };
+        this.#runs.set(request.invocationId, {
+            receipt,
+            fingerprint,
+            request: structuredClone(wire),
+            started: false,
+            at: Date.now()
+        });
+        return { ...receipt };
+    }
+    /** Public invocations default to native; canonical consumers explicitly select their view. */
+    invokeFrames(input, environment = {}) {
+        const received = Date.now();
+        try {
+            const parts = Array.isArray(input?.inputs) ? input.inputs : [];
+            const items = Array.isArray(input?.contexts?.items) ? input.contexts.items : [];
+            this.#log("info", "invoke.received", {
+                run_id: input?.runId,
+                invocation_id: input?.invocationId,
+                session_id: input?.sessionId,
+                input_count: parts.length,
+                text_input_count: parts.filter((part) => part?.type === "text").length,
+                image_input_count: parts.filter((part) => part?.type === "image").length,
+                context_count: items.filter((item) => !(item?.namespace === "octo.execution" && item?.name === "adapter")).length
+            });
+            environment.signal?.throwIfAborted();
+            assertInvokeRequestSize(input, environment);
+            const { adapterType, request, protocolMode } = prepareInvokeInput(input);
+            request.signal = environment.signal;
+            if (environment.executionEnvOverrides)
+                request.executionEnvOverrides = structuredClone(environment.executionEnvOverrides);
+            const receipt = this.#prepare(adapterType, request, { protocolMode });
+            const run = this.#runs.get(request.invocationId);
+            if (run.started)
+                throw protocolError("EXECUTION_IDENTITY_CONFLICT", "Invocation already executed; subscribe to the retained stream");
+            run.started = true;
+            this.#log("info", "invoke.accepted", {
+                run_id: request.runId,
+                invocation_id: request.invocationId,
+                session_id: request.agentSessionId,
+                adapter_type: adapterType,
+                model: request.agentConfig?.model,
+                duration_ms: Date.now() - received
+            });
+            const frozenRequest = withModelContexts({ ...run.request, signal: request.signal });
+            run.request = undefined;
+            return this.#streamInvocation(adapterType, frozenRequest, receipt);
+        }
+        catch (error) {
+            this.#log("warn", "invoke.rejected", {
+                code: errorCode(error) ?? "INVOKE_REJECTED",
+                duration_ms: Date.now() - received
+            });
+            throw error;
+        }
+    }
+    async *#streamInvocation(adapterType, request, receipt) {
+        const started = Date.now();
+        const identity = {
+            run_id: request.runId,
+            invocation_id: request.invocationId,
+            session_id: request.agentSessionId,
+            adapter_type: adapterType
+        };
+        this.#modes.set(request.invocationId, receipt.protocol_mode);
+        let seq = 0;
+        const frame = (output) => {
+            const result = "kind" in output
+                ? { ...receipt, ...output, seq: seq + 1 }
+                : {
+                    ...receipt,
+                    protocol_mode: "canonical",
+                    kind: "canonical",
+                    event: output,
+                    seq: seq + 1
+                };
+            assertHostFrame(result);
+            assertHostFrameIdentity(result, receipt);
+            const size = Buffer.byteLength(JSON.stringify(result));
+            if (size > 256 * 1024)
+                throw new Error("STREAM_EVENT_TOO_LARGE");
+            seq++;
+            return result;
+        };
+        let state;
+        let failureCode;
+        const pendingInteractions = new Set();
+        const source = receipt.protocol_mode === "canonical"
+            ? this.#invokeCanonical(adapterType, request)
+            : this.#invokeProvider(adapterType, request, "native");
+        try {
+            yield frame({ kind: "control", control: { type: "state", state: "running" } });
+            let pending = source.next();
+            void pending.catch(() => undefined);
+            while (true) {
+                const next = await pending;
+                if (next.done)
+                    break;
+                const output = next.value;
+                if (!("kind" in output) && output.type === "run.failed")
+                    failureCode = output.payload.failure?.code;
+                if ("kind" in output && output.kind === "control" && output.control.type === "error")
+                    failureCode = output.control.code;
+                if ("kind" in output &&
+                    output.kind === "control" &&
+                    output.control.type === "interaction") {
+                    if (output.control.status === "pending")
+                        pendingInteractions.add(output.control.requestId);
+                    else
+                        pendingInteractions.delete(output.control.requestId);
+                }
+                if ("kind" in output &&
+                    output.kind === "control" &&
+                    output.control.type === "state" &&
+                    output.control.state !== "running")
+                    state = output.control;
+                else if (!("kind" in output) && isTerminal(output))
+                    state = {
+                        type: "state",
+                        state: output.type === "run.completed"
+                            ? "completed"
+                            : output.type === "run.cancelled"
+                                ? "cancelled"
+                                : "failed"
+                    };
+                if (!("kind" in output &&
+                    output.kind === "control" &&
+                    output.control.type === "state" &&
+                    output.control.state !== "running"))
+                    yield frame(output);
+                pending = source.next();
+                void pending.catch(() => undefined);
+            }
+            if (!state) {
+                yield frame({
+                    kind: "control",
+                    control: {
+                        type: "error",
+                        code: "HOST_ENDED_WITHOUT_TERMINAL",
+                        message: "Provider ended without terminal"
+                    }
+                });
+                state = { type: "state", state: "failed" };
+            }
+            for (const requestId of pendingInteractions)
+                yield frame({
+                    kind: "control",
+                    control: { type: "interaction", requestId, status: "invalidated" }
+                });
+            pendingInteractions.clear();
+            yield frame({ kind: "control", control: state });
+        }
+        catch (error) {
+            this.#active.get(request.invocationId)?.abort(error);
+            await source.return(undefined);
+            state = { type: "state", state: "failed" };
+            for (const requestId of pendingInteractions)
+                yield {
+                    ...receipt,
+                    kind: "control",
+                    seq: ++seq,
+                    control: { type: "interaction", requestId, status: "invalidated" }
+                };
+            yield {
+                ...receipt,
+                kind: "control",
+                seq: ++seq,
+                control: {
+                    type: "error",
+                    code: "HOST_FRAME_INVALID",
+                    message: "Host output violated the selected stream contract"
+                }
+            };
+            yield { ...receipt, kind: "control", seq: ++seq, control: state };
+        }
+        finally {
+            try {
+                this.cancel(request.invocationId, "consumer_closed");
+                await source.return(undefined);
+            }
+            finally {
+                this.#modes.delete(request.invocationId);
+                this.#runs.get(request.invocationId).at = Date.now();
+                if (state?.state === "failed")
+                    this.#log("error", "invoke.failed", {
+                        ...identity,
+                        code: failureCode ?? "EXECUTION_FAILED"
+                    });
+                this.#log(state?.state === "failed" ? "error" : "info", "invoke.finished", {
+                    ...identity,
+                    frame_count: seq,
+                    status: state?.state ?? "unknown",
+                    duration_ms: Date.now() - started
+                });
+            }
+        }
+    }
+    async *#invokeCanonical(adapterType, request) {
+        const experience = new InvocationExperience();
+        const provider = this.#invokeProvider(adapterType, request);
+        let pending = provider.next();
+        void pending.catch(() => undefined);
+        let finalBody = false;
+        try {
+            for (const event of experience.start())
+                yield event;
+            while (true) {
+                const next = await pending;
+                if (next.done)
+                    break;
+                const event = next.value;
+                if ("kind" in event)
+                    throw protocolError("EXECUTION_PROTOCOL_MISMATCH");
+                if (event.type.startsWith("message.") &&
+                    event.payload.channel === "final" &&
+                    event.payload.text)
+                    finalBody = true;
+                if (event.type === "run.completed" &&
+                    !finalBody &&
+                    typeof event.payload.text === "string" &&
+                    event.payload.text) {
+                    const finalMessage = {
+                        protocolVersion: 2,
+                        type: "message.update",
+                        payload: {
+                            messageId: `${request.runId}:final`,
+                            channel: "final",
+                            status: "completed",
+                            text: event.payload.text
+                        }
+                    };
+                    for (const projected of experience.accept(finalMessage))
+                        yield projected;
+                }
+                for (const projected of experience.accept(event))
+                    yield projected;
+                pending = provider.next();
+                void pending.catch(() => undefined);
+            }
+        }
+        finally {
+            await provider.return(undefined);
+        }
+    }
+    async *#invokeProvider(adapterType, request, protocolMode = "canonical") {
+        this.#log("info", "invoke.started", {
+            run_id: request.runId,
+            invocation_id: request.invocationId,
+            session_id: request.agentSessionId,
+            adapter_type: adapterType
+        });
+        const adapter = this.#adapters.get(adapterType);
+        if (!adapter)
+            throw new Error(`unknown adapter: ${adapterType}`);
+        const controller = new AbortController();
+        const callerAbort = () => {
+            if (!this.#acceptedTerminals.has(request.invocationId))
+                controller.abort(request.signal?.reason);
+        };
+        request.signal?.addEventListener("abort", callerAbort, { once: true });
+        if (request.signal?.aborted)
+            callerAbort();
+        this.#active.set(request.invocationId, controller);
+        this.#activeAdapters.set(request.invocationId, adapter);
+        let terminal;
+        let nativeTerminal;
+        let outcome = "stopped";
+        let conversions = 0;
+        const identity = {
+            run_id: request.runId,
+            invocation_id: request.invocationId,
+            session_id: request.agentSessionId,
+            adapter_type: adapterType
+        };
+        const watchdog = new InvocationWatchdog(request.runtimeLimits, controller, (diagnostic) => this.#log("warn", "invoke.watchdog", {
+            ...identity,
+            code: diagnostic.event
+        }));
+        let iterator;
+        let cleanup;
+        let cleanupWait;
+        const closeIterator = () => (cleanup ??= Promise.resolve().then(() => iterator?.return?.()));
+        const waitCleanup = () => (cleanupWait ??= boundedCleanup(closeIterator(), watchdog.limits.cancelGraceMs));
+        // The timer can fire while a consumer is paused at yield.
+        const onAbort = () => {
+            void closeIterator().catch(() => undefined);
+        };
+        controller.signal.addEventListener("abort", onAbort, { once: true });
+        const messages = new Map();
+        const anonymousMessages = new Map();
+        let messageNumber = 0;
+        const context = {
+            protocolMode,
+            reportConversion: () => {
+                if (protocolMode === "native")
+                    throw protocolError("EXECUTION_PROTOCOL_MISMATCH", "Native execution invoked a canonical converter");
+                conversions++;
+            },
+            reportActivity: (activity) => watchdog.activity(activity)
+        };
+        // A provider may emit only deltas; here the host fills in the message lifecycle and stabilizes the messageId.
+        const prepareMessage = (event) => {
+            const isMessage = event.type === "message.create" ||
+                event.type === "message.delta" ||
+                event.type === "message.update";
+            if (!isMessage)
+                return { prefix: [], event };
+            const previous = event.payload.messageId ? messages.get(event.payload.messageId) : undefined;
+            const channel = event.payload.channel ?? previous?.channel ?? "final";
+            const segmentKey = `${channel}:${event.payload.stepId ?? ""}`;
+            const currentAnonymous = anonymousMessages.get(segmentKey);
+            const messageId = event.payload.messageId ??
+                (currentAnonymous && messages.get(currentAnonymous)?.open && event.type !== "message.create"
+                    ? currentAnonymous
+                    : `${request.runId}:${channel}:message:${++messageNumber}`);
+            if (!event.payload.messageId)
+                anonymousMessages.set(segmentKey, messageId);
+            const state = messages.get(messageId);
+            const stepId = typeof event.payload.stepId === "string" ? event.payload.stepId : state?.stepId;
+            const analysisMetadata = channel === "analysis"
+                ? {
+                    exposure: event.payload.exposure ?? "unknown",
+                    provenance: event.payload.provenance ?? {
+                        provider: adapterType,
+                        nativeEvent: "unknown"
+                    }
+                }
+                : {};
+            const prepared = {
+                ...event,
+                payload: { ...event.payload, channel, messageId, ...analysisMetadata }
+            };
+            const prefix = !state && event.type !== "message.create"
+                ? [
+                    {
+                        protocolVersion: 2,
+                        type: "message.create",
+                        payload: {
+                            role: "assistant",
+                            status: "streaming",
+                            channel,
+                            messageId,
+                            ...(stepId ? { stepId } : {}),
+                            ...analysisMetadata
+                        }
+                    }
+                ]
+                : [];
+            const closed = event.type === "message.update" &&
+                ["completed", "failed", "cancelled", "canceled", "stopped"].includes(String(event.payload.status));
+            messages.set(messageId, {
+                messageId,
+                channel,
+                open: !closed,
+                ...(stepId ? { stepId } : {}),
+                ...analysisMetadata
+            });
+            return { prefix, event: prepared };
+        };
+        const closeMessages = (status, stepId, onlyAnonymous = false) => {
+            const closed = [];
+            for (const state of messages.values()) {
+                if (!state.open || (stepId !== undefined && state.stepId !== stepId))
+                    continue;
+                if (onlyAnonymous && ![...anonymousMessages.values()].includes(state.messageId))
+                    continue;
+                state.open = false;
+                closed.push({
+                    protocolVersion: 2,
+                    type: "message.update",
+                    payload: {
+                        role: "assistant",
+                        status,
+                        channel: state.channel,
+                        messageId: state.messageId,
+                        ...(state.stepId ? { stepId: state.stepId } : {}),
+                        ...(state.exposure ? { exposure: state.exposure } : {}),
+                        ...(state.provenance ? { provenance: state.provenance } : {})
+                    }
+                });
+            }
+            return closed;
+        };
+        try {
+            const invocation = adapter.invoke({ ...request, signal: controller.signal }, context);
+            iterator = invocation[Symbol.asyncIterator]();
+            while (true) {
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                const pendingNext = iterator.next();
+                const next = terminal || nativeTerminal
+                    ? await withCleanupDeadline(pendingNext, watchdog.limits.cancelGraceMs, controller)
+                    : await waitForNext(pendingNext, controller.signal);
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                if (next.done)
+                    break;
+                const adapterEvent = next.value;
+                if (protocolMode === "native") {
+                    if (!("kind" in adapterEvent))
+                        throw protocolError("EXECUTION_PROTOCOL_MISMATCH");
+                    if (nativeTerminal)
+                        throw new Error(`${adapterType} emitted after terminal`);
+                    if (adapterEvent.kind === "control" && adapterEvent.control.type === "interaction")
+                        watchdog.interaction(adapterEvent.control.requestId, adapterEvent.control.status === "pending");
+                    if (adapterEvent.kind === "control" &&
+                        adapterEvent.control.type === "state" &&
+                        adapterEvent.control.state !== "running") {
+                        nativeTerminal = adapterEvent.control;
+                        watchdog.terminal();
+                        this.#acceptedTerminals.add(request.invocationId);
+                    }
+                    else
+                        yield adapterEvent;
+                    continue;
+                }
+                assertCanonicalEvent(adapterEvent);
+                const event = adapterEvent.type === "run.failed"
+                    ? {
+                        protocolVersion: 2,
+                        type: "run.failed",
+                        payload: await adapterFailurePayload(adapterEvent.payload, request.workdir, {
+                            stage: "provider.invoke",
+                            defaultDomain: "provider",
+                            runId: request.runId,
+                            source: { component: "octo-runtime", adapter: adapterType }
+                        })
+                    }
+                    : adapterEvent;
+                watchdog.canonical(event);
+                if (terminal)
+                    throw new Error(`${adapterType} emitted after terminal event`);
+                if (isTerminal(event)) {
+                    terminal = event;
+                    // A later user cancellation cannot replace an accepted provider terminal.
+                    this.#acceptedTerminals.add(request.invocationId);
+                }
+                else {
+                    // Placeholder creates do not establish a provider message boundary.
+                    if (event.type === "message.create" && !event.payload.messageId && !event.payload.text)
+                        continue;
+                    if (event.type === "message.update" &&
+                        !event.payload.messageId &&
+                        !event.payload.text &&
+                        ["completed", "failed", "cancelled", "canceled", "stopped"].includes(String(event.payload.status))) {
+                        for (const closed of closeMessages(String(event.payload.status), typeof event.payload.stepId === "string" ? event.payload.stepId : undefined))
+                            yield closed;
+                        continue;
+                    }
+                    if (event.type === "tool_call.create") {
+                        for (const closed of closeMessages("completed", undefined, true))
+                            yield closed;
+                        anonymousMessages.clear();
+                    }
+                    if (event.type === "model_step.finished") {
+                        for (const closed of closeMessages(event.payload.status, event.payload.stepId))
+                            yield closed;
+                    }
+                    const prepared = prepareMessage(event);
+                    for (const prefix of prepared.prefix)
+                        yield prefix;
+                    yield prepared.event;
+                }
+            }
+            await withCleanupDeadline(closeIterator(), watchdog.limits.cancelGraceMs, controller);
+            if (protocolMode === "native") {
+                if (!nativeTerminal)
+                    throw protocolError("HOST_ENDED_WITHOUT_TERMINAL");
+                outcome = nativeTerminal.state;
+                yield { kind: "control", control: nativeTerminal };
+                return;
+            }
+            if (!terminal)
+                throw protocolError("HOST_ENDED_WITHOUT_TERMINAL");
+            const messageStatus = terminal.type === "run.completed"
+                ? "completed"
+                : terminal.type === "run.failed"
+                    ? "failed"
+                    : "cancelled";
+            outcome = messageStatus;
+            for (const event of closeMessages(messageStatus))
+                yield event;
+            yield terminal;
+        }
+        catch (caught) {
+            const error = controller.signal.reason instanceof AdapterWatchdogTimeoutError
+                ? controller.signal.reason
+                : caught;
+            const failure = await adapterFailurePayload({
+                message: errorMessage(error),
+                adapterType,
+                ...(errorCode(error) ? { code: errorCode(error) } : {}),
+                ...watchdogFailureDetails(error)
+            }, request.workdir, {
+                stage: "adapter.invoke",
+                defaultDomain: "adapter",
+                runId: request.runId,
+                source: { component: "octo-runtime", adapter: adapterType }
+            });
+            const userCancelled = controller.signal.aborted &&
+                !(controller.signal.reason instanceof AdapterWatchdogTimeoutError);
+            outcome = userCancelled ? "stopped" : "failed";
+            if (error instanceof AdapterWatchdogTimeoutError &&
+                error.timeoutReason === "cleanup_timeout") {
+                try {
+                    this.#log("warn", "invoke.watchdog", {
+                        ...identity,
+                        code: "ADAPTER_CLEANUP_TIMEOUT"
+                    });
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            watchdog.dispose();
+            if (!controller.signal.aborted)
+                controller.abort(error);
+            await waitCleanup().catch(() => undefined);
+            if (protocolMode === "native") {
+                if (!userCancelled)
+                    yield {
+                        kind: "control",
+                        control: {
+                            type: "error",
+                            code: error instanceof Error &&
+                                "code" in error &&
+                                error.code === "HOST_ENDED_WITHOUT_TERMINAL"
+                                ? "HOST_ENDED_WITHOUT_TERMINAL"
+                                : "HOST_EXECUTION_FAILED",
+                            message: String(failure.message)
+                        }
+                    };
+                yield {
+                    kind: "control",
+                    control: { type: "state", state: userCancelled ? "cancelled" : "failed" }
+                };
+                return;
+            }
+            for (const event of closeMessages(userCancelled ? "cancelled" : "failed"))
+                yield event;
+            if (userCancelled) {
+                yield {
+                    protocolVersion: 2,
+                    type: "run.cancelled",
+                    payload: { reason: String(controller.signal.reason ?? "cancelled") }
+                };
+            }
+            else if (terminal?.type === "run.failed") {
+                yield terminal;
+            }
+            else {
+                yield {
+                    protocolVersion: 2,
+                    type: "run.failed",
+                    payload: failure
+                };
+            }
+        }
+        finally {
+            watchdog.finish(outcome);
+            this.#log("info", "invoke.conversion", {
+                run_id: request.runId,
+                invocation_id: request.invocationId,
+                protocol_mode: protocolMode,
+                conversion_count: conversions
+            });
+            if (!terminal && !nativeTerminal && !controller.signal.aborted)
+                controller.abort("consumer closed");
+            await waitCleanup().catch(() => undefined);
+            controller.signal.removeEventListener("abort", onAbort);
+            request.signal?.removeEventListener("abort", callerAbort);
+            this.#active.delete(request.invocationId);
+            this.#activeAdapters.delete(request.invocationId);
+            this.#acceptedTerminals.delete(request.invocationId);
+        }
+    }
+    /** Run the adapter's own environment probe; return an unchecked-available status when there is no probe. */
+    probe(adapterType, options) {
+        const adapter = this.#adapters.get(adapterType);
+        if (!adapter)
+            throw new Error(`unknown adapter: ${adapterType}`);
+        if (!adapter.probe)
+            return { available: true, adapterType, unchecked: true };
+        return adapter.probe(options);
+    }
+    /** Abort an active invocation; returns false when that invocation no longer exists or has already ended. */
+    cancel(invocationId, reason = "cancelled") {
+        const controller = this.#active.get(invocationId);
+        if (!controller || this.#acceptedTerminals.has(invocationId))
+            return false;
+        this.#log("info", "invoke.cancel_requested", { invocation_id: invocationId });
+        controller.abort(reason);
+        this.#log("info", "invoke.cancel_accepted", { invocation_id: invocationId });
+        return true;
+    }
+    /** Route an answer only to the adapter instance that owns the active invocation. */
+    async respondInteraction(invocationId, response) {
+        assertInteractionResponse(response);
+        const adapter = this.#activeAdapters.get(invocationId);
+        if (!adapter || this.#acceptedTerminals.has(invocationId)) {
+            throw new Error(`invocation is not active: ${invocationId}`);
+        }
+        if (this.#modes.get(invocationId) !== "canonical")
+            throw protocolError("EXECUTION_PROTOCOL_MISMATCH");
+        if (!adapter.respondInteraction) {
+            throw new Error(`adapter does not support interaction responses: ${adapter.metadata.type}`);
+        }
+        await adapter.respondInteraction(invocationId, response);
+    }
+    async respondNative(invocationId, response) {
+        assertNativeInteractionResponse(response);
+        if (this.#modes.get(invocationId) !== "native")
+            throw protocolError("EXECUTION_PROTOCOL_MISMATCH");
+        const adapter = this.#activeAdapters.get(invocationId);
+        if (!adapter?.respondNative || this.#acceptedTerminals.has(invocationId))
+            throw protocolError("INTERACTION_NOT_ACTIVE");
+        await adapter.respondNative(invocationId, response);
+    }
+    /** Abort every invocation and wait briefly for adapter cleanup to reap its
+     * provider processes. Used when the RPC parent disappears or shuts down. */
+    async shutdown(reason = "adapter host shutdown", timeoutMs = 2_500) {
+        for (const controller of this.#active.values())
+            controller.abort(reason);
+        if (this.#active.size === 0)
+            return;
+        const deadline = Date.now() + timeoutMs;
+        await new Promise((resolve) => {
+            const check = () => {
+                if (this.#active.size === 0 || Date.now() >= deadline) {
+                    resolve();
+                    return;
+                }
+                setTimeout(check, 10);
+            };
+            check();
+        });
+    }
+}
+function stableJson(value) {
+    return JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)))
+        : item);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Keep the Adapter's failure detail; catalog normalization only adds classification. */
+async function adapterFailurePayload(input, workdir, context) {
+    let detail = input;
+    // Node reports the same spawn errno for a missing command and a missing cwd.
+    if (["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(String(input.code)) && workdir) {
+        let problem;
+        try {
+            if (!(await stat(workdir)).isDirectory())
+                problem = "配置的工作目录不是文件夹";
+            else
+                await access(workdir, constants.X_OK);
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code === "ENOENT")
+                problem = "配置的工作目录不存在";
+            else if (code === "ENOTDIR")
+                problem = "配置的工作目录路径中包含非文件夹项";
+            else if (code === "EACCES" || code === "EPERM")
+                problem = "没有进入配置工作目录的权限";
+        }
+        if (problem)
+            detail = {
+                ...input,
+                code: "ADAPTER_INVOCATION_FAILED",
+                message: `${problem}（adapter.workdir=${workdir}）。${typeof input.message === "string" ? input.message : ""}`,
+                error: input.error ?? { code: input.code, message: input.message }
+            };
+    }
+    const normalized = failurePayload(detail, {
+        ...context,
+        ...(detail !== input ? { defaultDomain: "adapter" } : {})
+    });
+    const safe = sanitizePublicValue(detail);
+    const message = typeof safe.message === "string" && safe.message.trim()
+        ? safe.message
+        : typeof safe.error === "string"
+            ? safe.error
+            : safe.error && typeof safe.error === "object"
+                ? JSON.stringify(safe.error, null, 2)
+                : normalized.message;
+    return {
+        ...safe,
+        ...normalized,
+        message
+    };
+}
+function errorCode(error) {
+    return error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+async function waitForNext(pending, signal) {
+    let onAbort = () => { };
+    try {
+        return await Promise.race([
+            pending,
+            new Promise((_resolve, reject) => {
+                onAbort = () => reject(signal.reason instanceof Error
+                    ? signal.reason
+                    : new Error(String(signal.reason ?? "cancelled")));
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            })
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+    }
+}
+async function boundedCleanup(cleanup, graceMs) {
+    let timer;
+    try {
+        await Promise.race([
+            cleanup,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, graceMs);
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function withCleanupDeadline(pending, graceMs, controller) {
+    let timer;
+    try {
+        return await Promise.race([
+            pending,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    const error = new AdapterWatchdogTimeoutError("cleanup", graceMs, "cleanup_timeout");
+                    reject(error);
+                    controller.abort(error);
+                }, graceMs);
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function watchdogFailureDetails(error) {
+    return error instanceof AdapterWatchdogTimeoutError
+        ? {
+            timeoutStage: error.timeoutStage,
+            timeoutMs: error.timeoutMs,
+            timeoutReason: error.timeoutReason,
+            watchdog: error.evidence
+        }
+        : {};
+}
+export { spawnAdapterHost } from "./process.js";
+export { serveAdapterHost } from "./serve.js";
+export { AdapterHostRpcClient, AdapterHostRpcServer } from "./rpc.js";
+export { DEFAULT_RUNTIME_LIMITS } from "./watchdog.js";