@mininglamp-oss/octo-runtime 1.0.1 → 1.1.1

package/node_modules/@mininglamp-oss/octo-runtime-executor-kernel/dist/supervisor.js

@@ -0,0 +1,191 @@
+import { closeWorker, spawnWorker } from "./process.js";
+import { KernelError } from "./types.js";
+import { WorkerHeartbeat } from "./heartbeat.js";
+/** Kernel exclusively owns worker replacement; incomplete cleanup prevents a second owner. */
+export class WorkerSupervisor {
+    options;
+    recordWorker;
+    #worker;
+    #generation = 0;
+    #attempt = 0;
+    #state = "starting";
+    #closing = false;
+    #recovery;
+    #timer;
+    #heartbeat;
+    #activeTime = 0;
+    #attempts = [];
+    #slowRecovery = false;
+    #abort = new AbortController();
+    #cleanupFailure;
+    #closeUntil;
+    constructor(options, recordWorker) {
+        this.options = options;
+        this.recordWorker = recordWorker;
+    }
+    get status() {
+        return {
+            pid: this.#worker?.child.pid,
+            generation: this.#generation,
+            state: this.#state,
+            restart_attempt: this.#attempt
+        };
+    }
+    get client() {
+        if (this.#state !== "ready" || !this.#worker)
+            throw new KernelError("KERNEL_UNAVAILABLE");
+        return this.#worker.client;
+    }
+    async start(signal) {
+        signal?.throwIfAborted();
+        const abort = () => this.#abort.abort();
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            await this.#spawn();
+            signal?.throwIfAborted();
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async #spawn() {
+        let worker;
+        try {
+            worker = await spawnWorker({
+                ...this.options,
+                signal: this.#abort.signal,
+                onSpawn: async (child) => {
+                    await this.recordWorker?.(child.pid);
+                }
+            });
+        }
+        catch (error) {
+            if (error instanceof AggregateError)
+                this.#cleanupFailure = error;
+            throw error;
+        }
+        if (this.#closing) {
+            try {
+                await closeWorker(worker, this.#closeUntil ?? Date.now() + 5000, true);
+            }
+            catch (error) {
+                // A late startup still owns resources; failed rollback must block every future replacement.
+                throw (this.#cleanupFailure = new AggregateError([error], "WORKER_CLEANUP_INCOMPLETE"));
+            }
+            return;
+        }
+        this.#worker = worker;
+        this.#generation++;
+        this.#state = "ready";
+        const heartbeat = new WorkerHeartbeat();
+        this.#heartbeat = heartbeat;
+        let elapsed = 0;
+        worker.child.on("message", (message) => {
+            if (this.#worker === worker &&
+                message &&
+                typeof message === "object" &&
+                "type" in message &&
+                message.type === "worker.pong") {
+                heartbeat.pong("probe" in message ? message.probe : undefined);
+            }
+        });
+        worker.child.once("exit", () => this.#failed(worker));
+        worker.child.once("error", () => this.#failed(worker));
+        this.#timer = setInterval(() => {
+            if (this.#closing || this.#worker !== worker || this.#state !== "ready")
+                return;
+            const probe = heartbeat.tick();
+            this.#activeTime += heartbeat.activeMs - elapsed;
+            elapsed = heartbeat.activeMs;
+            if (probe.type === "expired") {
+                this.#failed(worker);
+                return;
+            }
+            if (probe.type === "ping" && worker.child.connected) {
+                worker.child.send({ type: "kernel.ping", probe: probe.id }, (error) => {
+                    if (error)
+                        this.#failed(worker);
+                });
+            }
+        }, 1000);
+        this.#timer.unref();
+        if (worker.child.exitCode !== null || worker.child.signalCode !== null)
+            this.#failed(worker);
+    }
+    #failed(worker) {
+        if (this.#closing || this.#worker !== worker || this.#state !== "ready")
+            return;
+        clearInterval(this.#timer);
+        this.#state = "recovering";
+        // Reject the old RPC first so its source emits one lost terminal. Recovery admits new work only.
+        worker.client.close(new KernelError("WORKER_LOST"));
+        if ((this.#heartbeat?.healthyMs ?? 0) >= 60_000) {
+            this.#attempts = [];
+            this.#attempt = 0;
+            this.#slowRecovery = false;
+        }
+        this.#recovery = this.#recover(worker).catch((error) => {
+            // Only unconfirmed cleanup or ownership ends recovery; ordinary startup failures stay retryable.
+            this.#cleanupFailure ??= new AggregateError([error], "WORKER_RECOVERY_BLOCKED");
+            if (!this.#closing)
+                this.#state = "exhausted";
+        });
+    }
+    async #recover(worker) {
+        // Reap the old worker before replacement to prevent concurrent Provider owners.
+        // Restore service availability only; #failed already marked old runs lost and never replays them.
+        // Preserve baseline recovery for leaders that exited before close began. On Windows this
+        // path cannot verify detached descendants; EOF-close checks require a live leader at entry.
+        if (worker.child.exitCode !== null || worker.child.signalCode !== null)
+            await worker.close();
+        else
+            await closeWorker(worker, Date.now() + 4800, true);
+        await this.recordWorker?.(undefined);
+        this.#worker = undefined;
+        while (!this.#closing) {
+            // Suspend time and clock changes must not replenish a recently exhausted restart budget.
+            this.#attempts = this.#attempts.filter((at) => this.#activeTime - at < 60_000);
+            if (this.#attempts.length >= 3)
+                this.#slowRecovery = true;
+            // Exhausting the fast budget opens a bounded-rate recovery loop, not a permanent outage.
+            // Keep slow recovery across short-lived workers until 60 seconds of health is observed.
+            const delay = this.#slowRecovery ? 15_000 : [250, 1000, 4000][this.#attempts.length];
+            await new Promise((resolve) => {
+                const finish = () => {
+                    clearTimeout(timer);
+                    this.#abort.signal.removeEventListener("abort", finish);
+                    resolve();
+                };
+                const timer = setTimeout(finish, delay);
+                this.#abort.signal.addEventListener("abort", finish, { once: true });
+            });
+            if (this.#closing)
+                return;
+            if (!this.#slowRecovery)
+                this.#attempts.push(this.#activeTime);
+            this.#attempt = Math.min(Number.MAX_SAFE_INTEGER, this.#attempt + 1);
+            try {
+                await this.#spawn();
+                return;
+            }
+            catch (error) {
+                if (error instanceof AggregateError)
+                    throw error;
+                /* Ordinary startup failures are reaped; aggregate cleanup failures prevent replacement. */
+            }
+        }
+    }
+    async close(until = Date.now() + 5000) {
+        this.#closing = true;
+        this.#closeUntil ??= until;
+        this.#abort.abort();
+        clearInterval(this.#timer);
+        await this.#recovery;
+        if (this.#worker)
+            await closeWorker(this.#worker, this.#closeUntil);
+        if (this.#cleanupFailure)
+            throw this.#cleanupFailure;
+        await this.recordWorker?.(undefined);
+        this.#state = "stopped";
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-executor-kernel/dist/types.d.ts

@@ -0,0 +1,72 @@
+import type { KernelLookupKey, KernelRunRef, KernelRunSnapshot, KernelStatus, InvokeInput, InvokeEnvironment, InputInvoke, HostFrame, InteractionResponse, NativeInteractionResponse } from "@mininglamp-oss/octo-runtime-protocol";
+import type { HostedAdapterMetadata } from "@mininglamp-oss/octo-runtime-executor-core";
+export type LookupKey = KernelLookupKey;
+export type RunRef = KernelRunRef;
+export type RunSnapshot = KernelRunSnapshot;
+export type { KernelStatus };
+export interface KernelInvocationRecord {
+    readonly key: LookupKey;
+    readonly ref?: RunRef;
+    readonly phase: "admitting" | "accepted" | "acceptance_unknown" | "unobserved";
+    readonly cancellation: "none" | "requested" | "acknowledged" | "unknown";
+    readonly lastSeq: number;
+    readonly observationError?: string;
+}
+/** 只确认本 client 登记的执行是否排空；不代表卡片投递或业务 dispose 已完成。 */
+export interface KernelInvocationDrainResult {
+    readonly complete: boolean;
+    readonly unresolved: readonly KernelInvocationRecord[];
+}
+export interface KernelInvocationLifecycle {
+    /** 身份与观察状态的副本，不缓存消息正文；结果未知的执行仍保留在列表中。 */
+    snapshot(): readonly KernelInvocationRecord[];
+    /** 同步关闭 invoke 接纳；已有执行仍可取消、查询和消费尾流。 */
+    stopAdmission(): void;
+    /** 共享 Date.now() 毫秒绝对期限；首次调用确定预算，后续调用复用同一排空结果。 */
+    drain(options: {
+        deadline: number;
+        reason: string;
+    }): Promise<KernelInvocationDrainResult>;
+}
+/**
+ * 附着到独立 Kernel 的客户端，不拥有 Kernel 进程。
+ * 常规接入使用 invoke；owner 退出时先 stopAdmission，再并行 drain 与业务收尾，最后 close。
+ * submit/subscribe 是低层入口，调用方自行保存 RunRef、管理取消与尾流，不自动登记为 invoke。
+ */
+export interface KernelClient {
+    readonly topology: "kernel-ipc";
+    readonly ownership: "attached";
+    /** 开始消费才提交；signal 请求取消但保留尾流，提前结束迭代则仅停止观察。 */
+    readonly invoke: InputInvoke;
+    readonly invocations: KernelInvocationLifecycle;
+    /** 仅操作当前 client 的 invoke 登记；accepted 是取消受理，不是终态或清理完成。 */
+    cancelInvocation(invocationId: string, reason?: string): Promise<{
+        accepted: boolean;
+    }>;
+    respondInteraction(invocationId: string, response: InteractionResponse): Promise<void>;
+    respondNativeInteraction(invocationId: string, response: NativeInteractionResponse): Promise<void>;
+    status(): Promise<KernelStatus>;
+    list(): Promise<HostedAdapterMetadata[]>;
+    /** 接纳后由 Kernel 持续驱动执行；ACK 丢失只查原身份，不重复执行。 */
+    submit(input: InvokeInput, environment?: InvokeEnvironment): Promise<{
+        ref: RunRef;
+    }>;
+    /** 按完整 LookupKey 查询原执行；指定 expectedInstance 可拒绝服务重启后的同名身份。 */
+    get(key: LookupKey, expectedInstance?: string): Promise<RunSnapshot>;
+    /** 从 afterSeq 之后观察同一执行；signal 只关闭订阅，游标过期/身份变化须交给调用方处理。 */
+    subscribe(ref: RunRef, afterSeq?: number, signal?: AbortSignal): AsyncGenerator<HostFrame>;
+    /** 显式控制原 RunRef；ACK 丢失报结果未知，不能自动重试可能已受理的控制动作。 */
+    cancel(ref: RunRef, reason?: string): Promise<{
+        accepted: boolean;
+    }>;
+    /** 交互响应必须匹配原引用和协议模式，过期/未知的响应不能改投其他 Run。 */
+    respond(ref: RunRef, response: InteractionResponse): Promise<void>;
+    respondNative(ref: RunRef, response: NativeInteractionResponse): Promise<void>;
+    /** 释放本 client 的连接和控制请求，不取消已接纳 Run，也不关闭共享 Kernel。 */
+    close(): void;
+}
+export declare class KernelError extends Error {
+    readonly code: string;
+    readonly data?: Record<string, unknown> | undefined;
+    constructor(code: string, data?: Record<string, unknown> | undefined);
+}

package/node_modules/@mininglamp-oss/octo-runtime-executor-kernel/dist/types.js

@@ -0,0 +1,10 @@
+export class KernelError extends Error {
+    code;
+    data;
+    constructor(code, data) {
+        super(code);
+        this.code = code;
+        this.data = data;
+        this.name = "KernelError";
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-executor-kernel/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mininglamp-oss/octo-runtime-executor-kernel",
+  "version": "1.1.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest-adapters": {
+      "types": "./dist/manifest-adapters.d.ts",
+      "import": "./dist/manifest-adapters.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "import": "./dist/runner.js"
+    }
+  },
+  "dependencies": {
+    "@mininglamp-oss/octo-runtime-executor-core": "1.1.1",
+    "@mininglamp-oss/octo-runtime-protocol": "1.1.1",
+    "@mininglamp-oss/octo-runtime-adapter-sdk": "1.1.1"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ]
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/config-schema.json

@@ -6,12 +6,12 @@
   "$comment": "声明文件最多 1 MiB，POSIX 权限须为 0600；单 Bot JSON 最多 256 KiB。Bot 按规范化 api_url 与 bot_id 组合判重。路径可访问性、凭据、身份和 Space 授权、重试起点不大于上限等关系仍需运行时检查。Context 内部对象遵循 octo.context-envelope/v3，具体协议约束由现有运行时校验，本文件不重复展开。",
   "type": "object",
   "additionalProperties": false,
-  "required": ["module", "config"],
+  "required": ["config"],
   "properties": {
     "module": {
       "type": "string",
       "const": "@mininglamp-oss/octo-runtime-extra-channel-gateway",
-      "description": "必填。Octo IM Extra 的固定包入口；宿主须预先安装并确保模块可解析。此 schema 约束包名声明，宿主通过绝对路径加载同一模块时可自行调整该约束。插件实例名及 CLI 配置目录名为 channel-gateway。"
+      "description": "可选旧声明。CLI 从 manifest.json 选择模块；省略时使用有效清单，保留时须与清单文字一致。SDK 原生 import 不需要此字段。此 schema 约束固定包名，宿主使用其他公开路径时可自行调整。"
     },
     "enabled": {
       "type": "boolean",

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/application/host-session-store.d.ts

@@ -0,0 +1,17 @@
+import type { JsonObject } from "@mininglamp-oss/octo-runtime-host-sdk";
+import type { CreateSessionStore } from "../ports.js";
+import type { ImSessionStore } from "./session-store.js";
+/**
+ * 逐 Bot 的宿主句柄租约；先登记再创建，尾写结束或截止后撤权，再释放自己的句柄。
+ * 不认识数据库，不关闭宿主连接；实际 close 和先前失败结果均不会被重复关闭覆盖。
+ */
+export declare class HostSessionStore {
+    #private;
+    readonly signal?: AbortSignal | undefined;
+    constructor(signal?: AbortSignal | undefined);
+    /** 同步工厂只接受实现完整接口的对象；错误 Promise 仍跟踪迟到资源以便回收。 */
+    create(factory: CreateSessionStore, config: JsonObject): ImSessionStore;
+    /** 与 Manager/Runtime 共用最早绝对期限；取消通知本身不禁止必要尾写。 */
+    drain(until: number): void;
+    close(until: number): Promise<void>;
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/application/host-session-store.js

@@ -0,0 +1,123 @@
+import { performance } from "node:perf_hooks";
+import { shutdownDeadline, withinShutdown } from "@mininglamp-oss/octo-runtime-host-sdk/shutdown";
+const required = ["read", "save", "reset", "occurrence", "remember"];
+const optional = ["patchGap", "invalidateRules", "patchRules"];
+/**
+ * 逐 Bot 的宿主句柄租约；先登记再创建，尾写结束或截止后撤权，再释放自己的句柄。
+ * 不认识数据库，不关闭宿主连接；实际 close 和先前失败结果均不会被重复关闭覆盖。
+ */
+export class HostSessionStore {
+    signal;
+    #release;
+    #creation;
+    #closing;
+    #invalidClose = false;
+    #until = Infinity;
+    #revoked = false;
+    #errors = [];
+    #stop = () => this.drain(shutdownDeadline(this.signal));
+    constructor(signal) {
+        this.signal = signal;
+        signal?.addEventListener("abort", this.#stop, { once: true });
+        if (signal?.aborted)
+            this.#stop();
+    }
+    /** 同步工厂只接受实现完整接口的对象；错误 Promise 仍跟踪迟到资源以便回收。 */
+    create(factory, config) {
+        let raw;
+        try {
+            raw = factory(config);
+        }
+        catch {
+            throw new Error("IM_SESSION_STORE_FACTORY_FAILED");
+        }
+        this.#capture(raw);
+        let asynchronous;
+        try {
+            asynchronous = !!raw && typeof raw.then === "function";
+        }
+        catch {
+            throw new Error("IM_SESSION_STORE_INVALID");
+        }
+        if (asynchronous) {
+            this.#creation = Promise.resolve(raw).then((value) => {
+                this.#capture(value);
+            }, () => undefined);
+            // 初始化可能立即回滚；这里消费 rejection，close 仍等待真实创建与释放。
+            void this.#creation.catch(() => undefined);
+            throw new Error("IM_SESSION_STORE_FACTORY_ASYNC");
+        }
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error("IM_SESSION_STORE_INVALID");
+        const view = {};
+        try {
+            for (const name of [...required, ...optional]) {
+                const method = Reflect.get(raw, name);
+                if (method === undefined && optional.some((key) => key === name))
+                    continue;
+                if (typeof method !== "function")
+                    throw new Error("IM_SESSION_STORE_INVALID");
+                view[name] = (...args) => {
+                    if (this.#revoked || performance.now() >= this.#until)
+                        throw new Error("IM_SESSION_STORE_CLOSED");
+                    try {
+                        const result = Reflect.apply(method, raw, args);
+                        return result;
+                    }
+                    catch (error) {
+                        if (this.#until !== Infinity)
+                            this.#errors.push(error);
+                        throw error;
+                    }
+                };
+            }
+            if (this.#invalidClose)
+                throw new Error("IM_SESSION_STORE_INVALID");
+        }
+        catch {
+            throw new Error("IM_SESSION_STORE_INVALID");
+        }
+        return Object.freeze(view);
+    }
+    #capture(raw) {
+        if (!raw || (typeof raw !== "object" && typeof raw !== "function"))
+            return;
+        try {
+            const close = Reflect.get(raw, "close");
+            this.#invalidClose = close !== undefined && typeof close !== "function";
+            if (typeof close === "function")
+                this.#release = () => Reflect.apply(close, raw, []);
+        }
+        catch {
+            this.#invalidClose = true;
+            this.#errors.push(new Error("IM_SESSION_STORE_INVALID"));
+        }
+    }
+    /** 与 Manager/Runtime 共用最早绝对期限；取消通知本身不禁止必要尾写。 */
+    drain(until) {
+        this.#until = Math.min(this.#until, until);
+    }
+    close(until) {
+        if (this.#closing)
+            return this.#closing;
+        this.drain(until);
+        this.#revoked = true;
+        this.signal?.removeEventListener("abort", this.#stop);
+        // 先保存真实操作，超时只停止等待；迟到创建仍会继续执行一次句柄释放。
+        const releasing = Promise.resolve().then(async () => {
+            await this.#creation;
+            await this.#release?.();
+        });
+        this.#closing = (async () => {
+            try {
+                await withinShutdown(releasing, this.#until, "IM_SESSION_STORE_CLOSE_INCOMPLETE");
+            }
+            catch (error) {
+                this.#errors.push(error);
+            }
+            if (this.#errors.length)
+                throw new AggregateError(this.#errors, "IM_SESSION_STORE_DISPOSE_FAILED");
+        })();
+        return this.#closing;
+    }
+}

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

@@ -7,5 +7,9 @@ export declare class ImRuntime {
     constructor(config: ImBotConfig, dependencies: ImModuleDependencies);
     get status(): Record<string, unknown>;
     start(): Promise<void>;
+    /**
+     * 同步停准入，在共享预算内取消执行并等待会话持久化、卡片和 final，再释放连接。
+     * 源终态或空任务表不代表业务 tail 已结束；失败/超时及重复调用都保留同一关闭结果。
+     */
     close(): Promise<void>;
 }