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

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/card-action.js

@@ -0,0 +1,75 @@
+/**
+ * 按钮报文解析：提取服务端确认的操作者与原卡片地址，供上层校验 Run 归属。
+ * 表单 data 只是输入，不能覆盖可信身份；按钮不会被合成为新的普通聊天消息。
+ */
+// Adapted from openclaw-channel-octo/src/card-action.ts; parsing only, no synthesized message.
+import { ChannelType } from "./api/types.js";
+function stringValue(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function channelTypeValue(value) {
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (numeric !== Number(ChannelType.DM) &&
+        numeric !== Number(ChannelType.Group) &&
+        numeric !== Number(ChannelType.CommunityTopic)) {
+        return null;
+    }
+    return numeric;
+}
+/** Parse the server-authoritative card_action envelope without trusting form input values. */
+export function parseCardAction(event) {
+    if (!Number.isSafeInteger(event.event_id) ||
+        event.event_id < 0 ||
+        event.event_type !== "card_action" ||
+        !event.event_data ||
+        typeof event.event_data !== "object") {
+        return null;
+    }
+    const data = event.event_data;
+    const messageId = stringValue(data.message_id);
+    const channelId = stringValue(data.channel_id);
+    const channelType = channelTypeValue(data.channel_type);
+    const actionId = stringValue(data.action_id);
+    const operatorUid = stringValue(data.operator_uid);
+    if (!messageId || !channelId || channelType === null || !actionId || !operatorUid)
+        return null;
+    const inputs = {};
+    if (data.inputs && typeof data.inputs === "object" && !Array.isArray(data.inputs)) {
+        for (const [key, value] of Object.entries(data.inputs)) {
+            // The server contract serializes every submitted value as a string, but normalize a raw
+            // JSON number/boolean (e.g. an Input.Number / Input.Toggle value) to its string form rather
+            // than dropping it: a dropped field still passes validation (missing keys are allowed) and
+            // would reach the agent as silently incomplete input. `false` / `0` must normalize too, so
+            // this tests the type, not truthiness. Objects / arrays / null / non-finite numbers stay
+            // dropped as malformed or unsupported envelope shapes.
+            if (typeof value === "string")
+                inputs[key] = value;
+            else if (typeof value === "boolean")
+                inputs[key] = String(value);
+            else if (typeof value === "number" && Number.isFinite(value))
+                inputs[key] = String(value);
+        }
+    }
+    const action = {
+        eventId: event.event_id,
+        messageId,
+        channelId,
+        channelType,
+        actionId,
+        inputs,
+        operatorUid
+    };
+    if (data.data && typeof data.data === "object" && !Array.isArray(data.data)) {
+        action.data = data.data;
+    }
+    const spaceId = stringValue(data.space_id);
+    if (spaceId)
+        action.spaceId = spaceId;
+    const clientToken = stringValue(data.client_token);
+    if (clientToken)
+        action.clientToken = clientToken;
+    if (typeof data.acted_at === "number" && Number.isFinite(data.acted_at)) {
+        action.actedAt = data.acted_at;
+    }
+    return action;
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/card-session.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 单 Run 卡片会话：首次创建、后续编辑同一消息，并用序号和终态屏障收敛状态。
+ * 卡片失败独立记录，最终文本仍由执行编排投递；发送回执不代表客户端已经渲染。
+ */
+import type { ImAddress } from "../contracts.js";
+import type { OctoConnector } from "./connector.js";
+import type { ImDeliveryDispatcher } from "../delivery/dispatcher.js";
+import type { RunPresentation } from "../presentation/run-projector.js";
+export declare class CardSession {
+    #private;
+    readonly connector: OctoConnector;
+    readonly delivery: ImDeliveryDispatcher;
+    readonly address: ImAddress;
+    readonly stopTyping: () => void;
+    readonly onDiagnostic: (code: string) => void;
+    readonly effectKey: string;
+    constructor(connector: OctoConnector, delivery: ImDeliveryDispatcher, address: ImAddress, runId: string, stopTyping: () => void, onDiagnostic: (code: string) => void);
+    update(snapshot: RunPresentation): void;
+    finish(): Promise<void>;
+    get messageId(): string | undefined;
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/card-session.js

@@ -0,0 +1,61 @@
+import { imBotIdentity } from "../lifecycle/configuration.js";
+import { stableEffectKey } from "./connector.js";
+import { ProgressScheduler } from "../delivery/scheduler.js";
+import { buildReasoningFrame } from "./reasoning-frame.js";
+export class CardSession {
+    connector;
+    delivery;
+    address;
+    stopTyping;
+    onDiagnostic;
+    #messageId;
+    #seq = 0;
+    #scheduler;
+    effectKey;
+    constructor(connector, delivery, address, runId, stopTyping, onDiagnostic) {
+        this.connector = connector;
+        this.delivery = delivery;
+        this.address = address;
+        this.stopTyping = stopTyping;
+        this.onDiagnostic = onDiagnostic;
+        this.effectKey = stableEffectKey(imBotIdentity(connector.config), address, runId, "progress");
+        this.#scheduler = new ProgressScheduler((snapshot) => this.#send(snapshot), () => onDiagnostic("IM_CARD_FAILED"));
+    }
+    update(snapshot) {
+        if (snapshot.terminal || snapshot.phase === "waiting")
+            this.stopTyping();
+        this.#scheduler.enqueue(snapshot, !!snapshot.terminal || !!snapshot.resultUnknown);
+    }
+    async #send(snapshot) {
+        const template = await this.connector.reasoningTemplate();
+        if (!template) {
+            this.onDiagnostic("IM_CARD_UNAVAILABLE");
+            return;
+        }
+        const frame = buildReasoningFrame(snapshot, template);
+        if (!frame) {
+            this.onDiagnostic("IM_CARD_BUDGET_EXCEEDED");
+            return;
+        }
+        const settled = !!snapshot.terminal || !!snapshot.resultUnknown;
+        // 模板查询期间可能已收到终态；旧快照必须在出站前再次检查。
+        if (this.#scheduler.terminal && !settled)
+            return;
+        const seq = ++this.#seq;
+        const receipt = await this.delivery.deliver(`${this.effectKey}:${seq}`, () => this.connector.card(this.address, template, frame, this.effectKey, this.#messageId, seq, !settled), { transient: !settled, obsolete: () => this.#scheduler.terminal && !settled });
+        if (receipt.state === "delivered") {
+            // 后续更新绑定第一次成功发送的消息，不另起卡片；可见卡片接替 typing 提示。
+            this.#messageId = receipt.messageId;
+            this.stopTyping();
+        }
+        else
+            this.onDiagnostic(receipt.code ?? "IM_CARD_FAILED");
+    }
+    async finish() {
+        this.stopTyping();
+        await this.#scheduler.flush();
+    }
+    get messageId() {
+        return this.#messageId;
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/cards.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 模板协商：只选择服务端明确声明可用且视图/动作合同完整的推理模板。
+ * 服务端启用卡片不等于任意模板都能使用，能力不足时交给上层降级处理。
+ */
+import type { CardProfileManifest } from "./api/cards.js";
+import type { ReasoningTemplate } from "./reasoning-frame.js";
+export declare function selectReasoningTemplate(profile: CardProfileManifest): ReasoningTemplate | undefined;

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/cards.js

@@ -0,0 +1,40 @@
+export function selectReasoningTemplate(profile) {
+    const config = profile.config;
+    if (!profile.available ||
+        !profile.enabled ||
+        profile.card_version !== "1.5" ||
+        !profile.profiles?.includes("octo/v1") ||
+        !profile.profiles.includes("octo/v2") ||
+        !config?.card_enabled ||
+        !config.reasoning_enabled ||
+        !config.reasoning_template_ref ||
+        !profile.templating?.supported ||
+        profile.templating.wire !== "template-ref/v1")
+        return;
+    const ref = config.reasoning_template_ref;
+    const templates = profile.templating.templates.filter((t) => t.id === ref.id &&
+        t.version === ref.version &&
+        t.id === "ai.reasoning-process" &&
+        t.available !== false);
+    if (templates.length !== 1)
+        return;
+    for (const [name, wire, states, actions] of [
+        ["active", "octo/v2", ["reasoning", "answering"], ["reasoning_stop"]],
+        ["error", "octo/v2", ["error"], ["reasoning_retry"]],
+        ["result", "octo/v1", ["completed", "stopped"], []]
+    ]) {
+        const views = templates[0].views.filter((view) => view.name === name);
+        const view = views[0];
+        if (views.length !== 1 ||
+            !view ||
+            view.wire_profile !== wire ||
+            !states.every((s) => view.states.includes(s)) ||
+            view.submit_actions.some((a) => !actions.includes(a)))
+            return;
+    }
+    const limit = profile.limits?.max_payload_bytes;
+    return {
+        ref,
+        maxPayloadBytes: typeof limit === "number" && Number.isSafeInteger(limit) && limit > 0 ? limit : 16_384
+    };
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/channel.d.ts

@@ -0,0 +1,43 @@
+import type { ChannelCallbacks, OctoBotConfig } from "../contracts.js";
+import type { ImCredentialSource } from "../ports.js";
+/** Octo IM 平台连接器：WuKong 与 Octo REST 适配；不是 MCP 连接器。 */
+export declare class GatewayTransport {
+    #private;
+    readonly config: OctoBotConfig;
+    readonly credentials: ImCredentialSource;
+    readonly callbacks: ChannelCallbacks;
+    identity: string;
+    readonly botId: string;
+    get scopedConfig(): {
+        spaceId: string;
+        api_url: string;
+        bf_token?: string;
+        groups_enabled?: boolean;
+        group_ids?: string[] | null;
+        cards?: boolean;
+        typing?: boolean;
+        bot_id: string;
+        bot_name?: string;
+        enabled?: boolean;
+        adapter: import("../contracts.js").ImAdapterConfig;
+        context?: import("@mininglamp-oss/octo-runtime-protocol").ContextEnvelope;
+        approval_mode?: import("@mininglamp-oss/octo-runtime-protocol").ApprovalMode;
+        run_timeout_ms?: number;
+        codex_retry?: {
+            enabled?: boolean;
+            max_consecutive_retries?: number;
+            max_total_retries?: number;
+            recovery_timeout_ms?: number;
+            initial_delay_ms?: number;
+            max_delay_ms?: number;
+        };
+        allowed_sender_ids?: string[];
+    };
+    constructor(config: OctoBotConfig, credentials: ImCredentialSource, callbacks: ChannelCallbacks);
+    get status(): {
+        connected: boolean;
+        cardDeliveries: import("../contracts.js").ImDeliveryReceipt[];
+    };
+    start(signal: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/channel.js

@@ -0,0 +1,407 @@
+/**
+ * Octo 接入编排：直连 IM Server，完成身份准入、Context 读取、卡片与按钮回传。
+ * 此通道就是 IM 事件发起方；只处理 IM 归属，不合成文档评论或其他领域请求。
+ */
+import { CONTEXT_SCHEMA } from "@mininglamp-oss/octo-runtime-protocol";
+import { interactionCard, interactionAnswer } from "./interaction-card.js";
+import { imBotIdentity } from "../lifecycle/configuration.js";
+import { verifyBotIdentity } from "./auth.js";
+import { registerBot, WukongConnection } from "./wukong.js";
+import { acceptsImMessage, groupScope } from "./normalize.js";
+import { build_im_contexts } from "./contexts.js";
+import { OctoConnector, stableEffectKey } from "./connector.js";
+import { CardSession } from "./card-session.js";
+import { TypingController } from "../presentation/typing.js";
+import { ImRunProjector } from "../presentation/run-projector.js";
+import { buildReasoningFrame } from "./reasoning-frame.js";
+import { ImDeliveryDispatcher } from "../delivery/dispatcher.js";
+import { fetchBotEvents, ackBotEvent } from "./api/events.js";
+import { parseCardAction } from "./card-action.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { octoCliEnvironment } from "../execution/tool-environment.js";
+import { downloadImageInput } from "./image-input.js";
+import { prepareFinalMention } from "./mentions.js";
+import { getGroupMembers } from "./api/conversations.js";
+import { getJson } from "./api/client.js";
+import { connectionFailure, ImConnectionError } from "./connection-error.js";
+import { sendReadReceipt } from "./api/messages.js";
+import { deliveryNoticeCard } from "../presentation/delivery-notice.js";
+import { ImSendError } from "../delivery/text-send.js";
+/** Octo IM 平台连接器：WuKong 与 Octo REST 适配；不是 MCP 连接器。 */
+export class GatewayTransport {
+    config;
+    credentials;
+    callbacks;
+    identity;
+    botId;
+    #detachAbort;
+    #closing;
+    #connection;
+    #spaceId = "";
+    get scopedConfig() {
+        return { ...this.config, spaceId: this.#spaceId };
+    }
+    #connected = false;
+    #closed = true;
+    #abort = new AbortController();
+    #typing;
+    #api;
+    #delivery;
+    #polling;
+    #bindings = new Map();
+    constructor(config, credentials, callbacks) {
+        this.config = config;
+        this.credentials = credentials;
+        this.callbacks = callbacks;
+        this.identity = imBotIdentity(config);
+        this.botId = config.bot_id;
+    }
+    get status() {
+        return { connected: this.#connected, cardDeliveries: this.#delivery?.receipts ?? [] };
+    }
+    async start(signal) {
+        this.#closed = false;
+        signal = AbortSignal.any([signal, this.#abort.signal]);
+        const token = (await this.credentials(this.config, signal))?.trim();
+        if (!token)
+            throw new Error("IM_CREDENTIALS_REQUIRED");
+        if (!/^bf_[A-Za-z0-9_-]+$/.test(token))
+            throw new Error("IM_BOT_TOKEN_INVALID");
+        const principal = await verifyBotIdentity(this.config.api_url, token, signal);
+        if (principal.bot_uid !== this.config.bot_id)
+            throw new Error("IM_BOT_IDENTITY_MISMATCH");
+        this.callbacks.authorizeSpace?.(principal.space_id);
+        this.#spaceId = principal.space_id;
+        this.identity = `${imBotIdentity(this.config)}:${encodeURIComponent(this.#spaceId)}`;
+        const registration = await registerBot(this.config.api_url, token, signal);
+        const toolEnvironment = octoCliEnvironment(this.config.api_url, token);
+        if (signal.aborted)
+            return;
+        if (registration.robot_id !== this.config.bot_id)
+            throw new Error("IM_BOT_IDENTITY_MISMATCH");
+        const connection = new WukongConnection((message) => {
+            if (this.#closed || !acceptsImMessage(this.scopedConfig, registration.owner_uid, message))
+                return;
+            let finalReply;
+            this.callbacks.onMessage({
+                messageId: message.messageId,
+                markRead: (turnSignal) => sendReadReceipt({
+                    apiUrl: this.config.api_url,
+                    botToken: token,
+                    channelId: message.channelId,
+                    channelType: message.channelType,
+                    messageIds: [message.messageId],
+                    signal: AbortSignal.any([signal, turnSignal])
+                }),
+                senderId: message.fromUid,
+                conversationId: message.channelId,
+                conversationKind: message.channelType === 1 ? "direct" : message.channelType === 5 ? "thread" : "group",
+                text: message.payload.type === 2
+                    ? ""
+                    : message.payload.type === 11 || message.payload.type === 14
+                        ? `收到一条${message.payload.type === 14 ? "富文本" : "合并转发"}新消息；正文见本轮 extra.im/message-content。`
+                        : message.payload.type === 8 || message.payload.type === 18
+                            ? typeof message.payload.content === "string" && message.payload.content.trim()
+                                ? message.payload.content
+                                : "请根据本轮资源上下文处理此资源。"
+                            : String(message.payload.content),
+                ...(message.payload.type === 2
+                    ? {
+                        buildInputs: (turnSignal) => downloadImageInput(message.payload.url, this.config.api_url, token, AbortSignal.any([signal, turnSignal]))
+                    }
+                    : {}),
+                executionEnvironment: () => {
+                    if (this.#closed || signal.aborted)
+                        throw new Error("IM_CONNECTION_REPLACED");
+                    return { executionEnvOverrides: structuredClone(toolEnvironment) };
+                },
+                runMetadata: {
+                    spaceId: this.#spaceId,
+                    botId: this.config.bot_id,
+                    channelType: message.channelType
+                },
+                isReplyDelivered: (effectKey) => connection.isDelivered(stableEffectKey(this.identity, message, effectKey, "text")),
+                replyDeliveryUnknown: async (event, effectKey, replyEffectKey, deliverySignal) => {
+                    if (deliverySignal.aborted ||
+                        connection.isDelivered(stableEffectKey(this.identity, message, replyEffectKey, "text")))
+                        return;
+                    // F27：REST 跟随 Bot/Extra 的投递期限，不跟随已断开的 WS 连接期限。
+                    const rest = new OctoConnector(this.config, token, deliverySignal, async () => { });
+                    const sent = await rest.displayCard(message, deliveryNoticeCard(event), stableEffectKey(this.identity, message, effectKey, "delivery"), () => connection.isDelivered(stableEffectKey(this.identity, message, replyEffectKey, "text")));
+                    if (!sent &&
+                        !connection.isDelivered(stableEffectKey(this.identity, message, replyEffectKey, "text")))
+                        throw new ImSendError("IM_DELIVERY_NOTICE_UNSUPPORTED", "failed");
+                },
+                replyFailure: async (event, effectKey) => {
+                    if (this.#closed || signal.aborted)
+                        return;
+                    const template = await this.#api.reasoningTemplate();
+                    if (!template)
+                        return;
+                    const projector = new ImRunProjector(`channel:${effectKey}`, message.channelType === 1);
+                    projector.accept(event);
+                    const frame = buildReasoningFrame(projector.snapshot(), template);
+                    if (!frame)
+                        throw Error("IM_CARD_BUDGET_EXCEEDED");
+                    await this.#api.card(message, template, frame, stableEffectKey(this.identity, message, effectKey, "error"), undefined, 1, false);
+                },
+                reply: async (text, effectKey) => {
+                    // 闭包绑定接收消息的连接和地址；配置替换后不把旧 Run 的回复转到新账号。
+                    if (this.#closed || signal.aborted)
+                        throw new Error("IM_CONNECTION_REPLACED");
+                    const key = stableEffectKey(this.identity, message, effectKey ?? message.messageId, "text");
+                    await connection.sendText(message.channelId, message.channelType, text, key, this.#spaceId);
+                },
+                replyFinal: async (text, effectKey) => {
+                    if (this.#closed || signal.aborted)
+                        throw new Error("IM_CONNECTION_REPLACED");
+                    if (finalReply?.key !== effectKey)
+                        finalReply = {
+                            key: effectKey,
+                            value: prepareFinalMention(text, async () => {
+                                if ([2, 5].includes(message.channelType))
+                                    return getGroupMembers({
+                                        apiUrl: this.config.api_url,
+                                        botToken: token,
+                                        groupNo: groupScope(message.channelId).groupNo,
+                                        signal
+                                    });
+                                const peer = await getJson(this.config.api_url, token, `/v1/bot/user/info?uid=${encodeURIComponent(message.fromUid)}`, AbortSignal.any([signal, AbortSignal.timeout(5000)]), { maxResponseBytes: 64 << 10, logRateLimit: false });
+                                return peer?.uid === message.fromUid ? [peer] : [];
+                            })
+                        };
+                    const result = await finalReply.value;
+                    if (this.#closed || signal.aborted)
+                        throw new Error("IM_CONNECTION_REPLACED");
+                    await connection.sendText(message.channelId, message.channelType, result.text, stableEffectKey(this.identity, message, effectKey, "text"), this.#spaceId, result.mention);
+                },
+                buildContext: async (turnSignal, options) => ({
+                    schema: CONTEXT_SCHEMA,
+                    items: await build_im_contexts(this.scopedConfig, message, token, AbortSignal.any([signal, turnSignal]), options)
+                }),
+                beginPresentation: (runId, onDiagnostic, controls) => {
+                    const interactions = new Map();
+                    const resolveInteraction = async (id, status) => {
+                        const entry = interactions.get(id);
+                        if (!entry)
+                            return;
+                        interactions.delete(id);
+                        await this.#api.interactionCard(message, interactionCard(entry.request, status), stableEffectKey(this.identity, message, id, "interaction"), entry.messageId);
+                    };
+                    const stopTyping = this.config.typing === false ? () => { } : this.#typing.acquire(message, runId);
+                    const card = new CardSession(this.#api, this.#delivery, message, runId, stopTyping, onDiagnostic);
+                    this.#bindings.set(runId, {
+                        card,
+                        address: message,
+                        senderId: message.fromUid,
+                        controls,
+                        expires: Date.now() + 86_400_000 + 30 * 60_000,
+                        active: true,
+                        interactions
+                    });
+                    if (this.#bindings.size > 128) {
+                        const idle = [...this.#bindings].find(([, binding]) => !binding.active);
+                        if (idle)
+                            this.#bindings.delete(idle[0]);
+                    }
+                    if (!this.#polling)
+                        this.#polling = this.#pollActions(token, registration.owner_uid, signal);
+                    return {
+                        interaction: async (request) => {
+                            const document = interactionCard(request);
+                            const effect = stableEffectKey(this.identity, message, request.interactionId, "interaction");
+                            let messageId;
+                            const receipt = await this.#delivery.deliver(effect, async () => {
+                                messageId = await this.#api.interactionCard(message, document, effect);
+                                if (!messageId)
+                                    throw Error("IM_INTERACTION_CARD_UNAVAILABLE");
+                                return messageId;
+                            });
+                            if (receipt.state !== "delivered" || !receipt.messageId)
+                                return false;
+                            interactions.set(request.interactionId, {
+                                request: structuredClone(request),
+                                messageId: receipt.messageId
+                            });
+                            return true;
+                        },
+                        resolveInteraction,
+                        update: (snapshot) => card.update(snapshot),
+                        finish: async () => {
+                            try {
+                                for (const id of interactions.keys()) {
+                                    try {
+                                        await resolveInteraction(id, "invalidated");
+                                    }
+                                    catch {
+                                        onDiagnostic("IM_INTERACTION_CARD_FAILED");
+                                    }
+                                }
+                                await card.finish();
+                            }
+                            finally {
+                                const binding = this.#bindings.get(runId);
+                                if (binding) {
+                                    binding.active = false;
+                                    binding.expires = Date.now() + 30 * 60_000;
+                                }
+                            }
+                        }
+                    };
+                }
+            });
+        }, (error) => {
+            this.#connected = false;
+            const failure = connectionFailure(error);
+            this.callbacks.onDisconnect(failure.message, failure.retryable);
+        });
+        this.#connection = connection;
+        this.#api = new OctoConnector(this.config, token, signal, async (address, text, effectKey) => {
+            if (this.#closed || signal.aborted)
+                throw new Error("IM_CONNECTION_REPLACED");
+            await connection.sendText(address.channelId, address.channelType, text, effectKey, this.#spaceId);
+        });
+        this.#delivery = new ImDeliveryDispatcher(signal);
+        this.#typing = new TypingController((address, typingSignal) => this.#api.typing(address, typingSignal), () => this.callbacks.onDiagnostic?.("IM_TYPING_FAILED"));
+        const abort = () => {
+            void connection.close();
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        this.#detachAbort = () => signal.removeEventListener("abort", abort);
+        if (signal.aborted)
+            return;
+        await connection.connect(registration);
+        if (signal.aborted) {
+            await connection.close();
+            return;
+        }
+        if (!connection.connected)
+            throw new ImConnectionError("IM_DISCONNECTED", true);
+        this.#connected = true;
+    }
+    async #pollActions(token, owner, signal) {
+        if (this.config.cards === false)
+            return;
+        let cursor = 0, failures = 0;
+        const handled = new Set();
+        while (!signal.aborted && !this.#closed) {
+            const started = Date.now();
+            try {
+                const events = await fetchBotEvents({
+                    apiUrl: this.config.api_url,
+                    botToken: token,
+                    sinceEventId: cursor,
+                    limit: 100,
+                    waitSeconds: 30,
+                    signal: AbortSignal.any([signal, AbortSignal.timeout(40_000)])
+                });
+                for (const event of events.sort((a, b) => a.event_id - b.event_id)) {
+                    if (signal.aborted)
+                        return;
+                    if (!Number.isSafeInteger(event.event_id) || event.event_id <= cursor)
+                        continue;
+                    // cursor 仅记录本地读取位置；不认识的领域事件不 ACK，也不转换成 IM 请求。
+                    const action = parseCardAction(event);
+                    if (!action) {
+                        cursor = event.event_id;
+                        continue;
+                    }
+                    if (action.spaceId !== this.#spaceId ||
+                        !(this.config.allowed_sender_ids ?? [owner]).includes(action.operatorUid)) {
+                        cursor = event.event_id;
+                        continue;
+                    }
+                    let consumed = handled.has(event.event_id);
+                    for (const [id, binding] of this.#bindings) {
+                        if (consumed)
+                            break;
+                        if (binding.expires <= Date.now()) {
+                            this.#bindings.delete(id);
+                            continue;
+                        }
+                        const sameAddress = binding.address.channelId === action.channelId ||
+                            (Number(action.channelType) === 1 &&
+                                binding.address.channelId === `s${this.#spaceId}_${action.channelId}`);
+                        // 操作者、空间、原消息和地址均匹配才允许控制 Run，不信任表单中的归属声明。
+                        const interaction = [...binding.interactions.values()].find((entry) => entry.messageId === action.messageId);
+                        if ((binding.card.messageId !== action.messageId && !interaction) ||
+                            binding.address.channelType !== Number(action.channelType) ||
+                            binding.senderId !== action.operatorUid ||
+                            !sameAddress)
+                            continue;
+                        if (interaction && action.actionId.startsWith("interaction_")) {
+                            if (!binding.active || !binding.controls.respond)
+                                continue;
+                            await binding.controls.respond(interactionAnswer(interaction.request, action));
+                            binding.interactions.delete(interaction.request.interactionId);
+                            try {
+                                await this.#api.interactionCard(binding.address, interactionCard(interaction.request, "resolved"), stableEffectKey(this.identity, binding.address, interaction.request.interactionId, "interaction"), interaction.messageId);
+                            }
+                            catch {
+                                this.callbacks.onDiagnostic?.("IM_INTERACTION_CARD_FAILED");
+                            }
+                        }
+                        else if (!interaction && action.actionId === "reasoning_stop")
+                            await binding.controls.cancel();
+                        else if (!interaction && action.actionId === "reasoning_retry")
+                            binding.controls.retry(action.operatorUid, `card_action:${event.event_id}`);
+                        else
+                            continue;
+                        consumed = true;
+                        handled.add(event.event_id);
+                        break;
+                    }
+                    if (consumed) {
+                        await ackBotEvent({
+                            apiUrl: this.config.api_url,
+                            botToken: token,
+                            eventId: event.event_id,
+                            signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)])
+                        });
+                        handled.delete(event.event_id);
+                    }
+                    cursor = event.event_id;
+                    for (const id of handled)
+                        if (id <= cursor)
+                            handled.delete(id);
+                }
+                failures = 0;
+                if (Date.now() - started < 1000)
+                    await delay(2_000, undefined, { signal });
+            }
+            catch {
+                if (signal.aborted)
+                    return;
+                this.callbacks.onDiagnostic?.("IM_CARD_ACTION_POLL_FAILED");
+                try {
+                    await delay(Math.min(30_000, 2_000 * 2 ** failures++), undefined, { signal });
+                }
+                catch {
+                    return;
+                }
+            }
+        }
+    }
+    close() {
+        if (this.#closing)
+            return this.#closing;
+        this.#closed = true;
+        this.#connected = false;
+        this.#abort.abort();
+        this.#detachAbort?.();
+        this.#closing = Promise.resolve().then(async () => {
+            const results = await Promise.allSettled([
+                Promise.resolve().then(() => this.#typing?.close()),
+                Promise.resolve().then(() => this.#connection?.close()),
+                this.#polling
+            ]);
+            const errors = results
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason);
+            if (errors.length)
+                throw new AggregateError(errors, "IM_TRANSPORT_DISPOSE_FAILED");
+            this.#bindings.clear();
+        });
+        return this.#closing;
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/connection-error.d.ts

@@ -0,0 +1,10 @@
+/** 只携带连接协议事实；恢复策略由 Bot 编排决定，不保留响应正文或凭据。 */
+export declare class ImConnectionError extends Error {
+    readonly retryable: boolean;
+    readonly retryAfterMs: number;
+    constructor(code: string, retryable: boolean, retryAfterMs?: number);
+}
+export declare function connectionFailure(error: unknown): ImConnectionError;
+export declare function connectionFetch(url: string, init: RequestInit, phase: "AUTH" | "REGISTER"): Promise<Response>;
+export declare function httpConnectionFailure(response: Response, phase: "AUTH" | "REGISTER"): Promise<ImConnectionError>;
+export declare function connectionJson(response: Response, phase: "AUTH" | "REGISTER", invalidCode: string): Promise<unknown>;