@mininglamp-oss/octo-runtime 1.0.1 → 1.1.0

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/dist/extra-service.js

@@ -0,0 +1,272 @@
+import net from "node:net";
+import { performance } from "node:perf_hooks";
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { RuntimeLogging, assertRuntimeLogging, readBoundedLines } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+import { acquireEndpoint, attachKernel, ServiceInitializationError } from "@mininglamp-oss/octo-runtime-executor-kernel";
+import { assertExtraName, ExtraPlugins } from "./extras.js";
+import { shutdownDeadline, withShutdownDeadline, withinShutdown } from "./shutdown.js";
+import { snapshotExtraDependencies } from "./extra-dependencies.js";
+// 未确认清理的实例仍占有名称；不同 Kernel/Home 的同名 Extra 相互独立。
+const owners = new Map();
+/** 装配插件和同进程业务函数；只借用指定 Kernel，不启动或关闭它。 */
+export function createExtraService(options) {
+    assertExtraName(options.module.name);
+    assertRuntimeLogging(options.logging);
+    const name = options.module.name;
+    const config = structuredClone(options.config);
+    const module = { ...options.module };
+    const pendingDependencies = new Set();
+    const endpoint = options.endpoint;
+    const controlEndpoint = options.controlEndpoint;
+    const enabled = options.enabled !== false;
+    const logging = options.logging && { ...options.logging };
+    const key = `${process.platform === "win32" ? endpoint.toLowerCase() : resolve(endpoint)}\0${name}`;
+    const owner = new AbortController();
+    let dependenciesOpen = true;
+    let shutdownUntil;
+    const dependencies = snapshotExtraDependencies(options.dependencies, (invoke) => (...args) => {
+        // 取消通知不撤销尾部保存权限；清理完成或绝对截止后才禁止调用宿主函数。
+        if (!dependenciesOpen || performance.now() >= (shutdownUntil ?? Infinity))
+            throw new Error("EXTRA_DEPENDENCIES_CLOSED");
+        if (pendingDependencies.size >= 128)
+            throw new Error("EXTRA_DEPENDENCY_CAPACITY_EXHAUSTED");
+        const result = invoke(...args);
+        if (result && typeof result.then === "function") {
+            // 每次调用独立占额；宿主复用同一 Promise 时也不能绕过在途上限。
+            const operation = Promise.resolve(result).then((value) => value);
+            pendingDependencies.add(operation);
+            void operation.finally(() => pendingDependencies.delete(operation)).catch(() => undefined);
+        }
+        return result;
+    });
+    const ownership = { failed: false };
+    let acquired = false;
+    let phase = "created";
+    let client;
+    let logs;
+    let plugins;
+    let starting;
+    let initialized;
+    let closing;
+    let cleanupDeadline;
+    let draining;
+    let server;
+    let binding;
+    let release;
+    const sockets = new Set();
+    let finishClosed;
+    const closed = new Promise((resolve) => {
+        finishClosed = resolve;
+    });
+    const status = async () => ({
+        phase,
+        name,
+        pid: process.pid,
+        kernel_available: (await client?.status().then((value) => value.execution_ready, () => false)) ?? false,
+        plugin: !enabled
+            ? { phase: "disabled" }
+            : phase === "ready" && plugins
+                ? await plugins.inspect(name)
+                : { phase }
+    });
+    const drainRuns = async () => {
+        if (!client)
+            return;
+        const result = await client.invocations.drain({
+            deadline: (cleanupDeadline ??= Date.now() + 5000),
+            reason: "extra_shutdown"
+        });
+        if (!result.complete)
+            throw new Error("EXTRA_RUN_CLEANUP_INCOMPLETE");
+    };
+    const beginDrain = (signal) => {
+        shutdownUntil ??= shutdownDeadline(signal);
+        cleanupDeadline ??= Date.now() + Math.max(0, Math.floor(shutdownUntil - performance.now()));
+        client?.invocations.stopAdmission();
+        // 回滚通知先于加载器等待 disposer；立即取消源调用，避免消费者与清理互相等待。
+        if (!draining) {
+            draining = drainRuns();
+            void draining.catch(() => undefined);
+        }
+        return draining;
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        phase = "closing";
+        shutdownUntil ??= shutdownDeadline();
+        const draining = beginDrain();
+        owner.abort();
+        withShutdownDeadline(shutdownUntil, () => plugins?.stopAdmission());
+        for (const socket of sockets)
+            socket.destroy();
+        closing = (async () => {
+            const until = shutdownUntil;
+            const errors = [];
+            const attempt = async (resource, operation) => {
+                try {
+                    await withinShutdown(Promise.resolve().then(operation), until, "EXTRA_CLEANUP_TIMEOUT");
+                }
+                catch {
+                    errors.push({ resource, code: "EXTRA_CLEANUP_INCOMPLETE" });
+                }
+            };
+            await attempt("initialization", () => starting?.catch(() => undefined));
+            // 插件先停业务准入并等待自己的消费者；与源调用排空并行，避免收尾互相等待。
+            await Promise.all([
+                attempt("runs", () => draining),
+                attempt("plugin", async () => {
+                    try {
+                        await withShutdownDeadline(until, () => plugins?.close());
+                    }
+                    finally {
+                        dependenciesOpen = false;
+                    }
+                })
+            ]);
+            dependenciesOpen = false;
+            // 权限撤销后集合不再增长，才能完整等待清理中新开始的真实依赖操作。
+            await attempt("dependencies", async () => {
+                await Promise.allSettled([...pendingDependencies]);
+            });
+            await attempt("control-server", async () => {
+                // 到期只结束等待；绑定稍后完成时，此操作仍须继续关闭迟到的监听句柄。
+                await binding?.catch(() => undefined);
+                if (server?.listening)
+                    await new Promise((resolve, reject) => {
+                        server.close((error) => (error ? reject(error) : resolve()));
+                    });
+            });
+            client?.close();
+            await attempt("logs", () => logs?.close());
+            if (!errors.length)
+                await attempt("control-endpoint", async () => {
+                    if (!release)
+                        return;
+                    if (controlEndpoint && process.platform !== "win32")
+                        await rm(controlEndpoint, { force: true });
+                    await release();
+                });
+            if (acquired) {
+                if (errors.length)
+                    ownership.failed = true;
+                else
+                    owners.delete(key);
+            }
+            phase = errors.length ? "failed" : "closed";
+            const result = {
+                complete: !errors.length,
+                errors,
+                pendingResources: errors.map((error) => error.resource)
+            };
+            finishClosed(result);
+            return result;
+        })();
+        return closing;
+    };
+    return {
+        status,
+        close,
+        closed,
+        initialize({ signal } = {}) {
+            if (initialized)
+                return initialized;
+            if (phase !== "created")
+                return Promise.reject(new Error("SERVICE_CLOSED"));
+            phase = "initializing";
+            let onAbort;
+            const cancelled = new Promise((_, reject) => {
+                onAbort = () => reject(owner.signal.reason instanceof Error
+                    ? owner.signal.reason
+                    : new Error("SERVICE_INITIALIZATION_CANCELLED", { cause: owner.signal.reason }));
+                owner.signal.addEventListener("abort", onAbort, { once: true });
+            });
+            const abort = () => {
+                shutdownUntil ??= shutdownDeadline();
+                void beginDrain();
+                owner.abort();
+                withShutdownDeadline(shutdownUntil, () => plugins?.stopAdmission());
+            };
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            starting = (async () => {
+                owner.signal.throwIfAborted();
+                const previous = owners.get(key);
+                if (previous)
+                    throw new Error(previous.failed ? "EXTRA_DISPOSE_FAILED" : "EXTRA_ALREADY_LOADED");
+                if (owners.size >= 64)
+                    throw new Error("EXTRA_CAPACITY_EXHAUSTED");
+                owners.set(key, ownership);
+                acquired = true;
+                client = attachKernel({ endpoint });
+                logs = new RuntimeLogging(logging);
+                plugins = new ExtraPlugins([], client, () => logs.extra(name));
+                if (enabled)
+                    await plugins.load({
+                        ...module,
+                        default(context, config) {
+                            // 初始化失败先停准入并排空；不 abort owner，以保留加载器抛出的原始 cause。
+                            context.signal.addEventListener("abort", () => {
+                                void beginDrain(context.signal);
+                            }, { once: true });
+                            return module.default(context, config);
+                        }
+                    }, config, dependencies);
+                owner.signal.throwIfAborted();
+                if (controlEndpoint) {
+                    if (process.platform !== "win32")
+                        await mkdir(dirname(controlEndpoint), { recursive: true, mode: 0o700 });
+                    owner.signal.throwIfAborted();
+                    release = await acquireEndpoint(controlEndpoint);
+                    owner.signal.throwIfAborted();
+                    server = net.createServer((socket) => {
+                        if (owner.signal.aborted) {
+                            socket.destroy();
+                            return;
+                        }
+                        sockets.add(socket);
+                        socket.once("close", () => sockets.delete(socket));
+                        socket.on("error", () => socket.destroy());
+                        socket.setTimeout(5000, () => socket.destroy());
+                        const off = readBoundedLines(socket, 4096, {
+                            onError: () => socket.destroy(),
+                            onTooLarge: () => socket.destroy(),
+                            onClose() { },
+                            onLine(line) {
+                                off();
+                                try {
+                                    const request = JSON.parse(line);
+                                    if (request.method !== "status")
+                                        throw new Error("METHOD_NOT_FOUND");
+                                    void status().then((value) => socket.end(`${JSON.stringify({ jsonrpc: "2.0", id: request.id, result: { name, pid: process.pid, status: { ...value.plugin, kernel_available: value.kernel_available } } })}\n`), () => socket.destroy());
+                                }
+                                catch {
+                                    socket.destroy();
+                                }
+                            }
+                        });
+                    });
+                    await (binding = new Promise((resolve, reject) => {
+                        server.once("error", reject);
+                        server.listen(controlEndpoint, resolve);
+                    }));
+                    if (process.platform !== "win32")
+                        await chmod(controlEndpoint, 0o600);
+                    owner.signal.throwIfAborted();
+                }
+                phase = "ready";
+            })();
+            initialized = Promise.race([starting, cancelled])
+                .catch(async (error) => {
+                throw new ServiceInitializationError(error, await close());
+            })
+                .finally(() => {
+                signal?.removeEventListener("abort", abort);
+                owner.signal.removeEventListener("abort", onAbort);
+            });
+            return initialized;
+        }
+    };
+}

package/node_modules/@mininglamp-oss/{octo-runtime-daemon → octo-runtime-host-sdk}/dist/extras.d.ts

@@ -1,5 +1,4 @@
-import type { InputInvoke, InteractionResponse } from "@mininglamp-oss/octo-runtime-protocol";
-import type { HostedAdapterMetadata } from "@mininglamp-oss/octo-runtime-adapter-host";
+import type { KernelClient } from "@mininglamp-oss/octo-runtime-executor-kernel";
 import { type RuntimeLog } from "@mininglamp-oss/octo-runtime-adapter-sdk";
 export type { ChannelDependencies, LoadContexts } from "./context-loader.js";
 export type { RuntimeLog, RuntimeLogLevel } from "@mininglamp-oss/octo-runtime-adapter-sdk";
@@ -9,20 +8,11 @@ export interface JsonObject {
 }
 export type ExtraDisposer = () => void | Promise<void>;
 export type ExtraStatusHandler = () => JsonObject;
-/** 插件复用宿主执行实例，不依赖 HostRunService 的内部实现。 */
-export interface ExtraAdapterHost {
-    list?(): Promise<HostedAdapterMetadata[]>;
-    invoke: InputInvoke;
-    cancel(invocationId: string, reason?: string): Promise<{
-        cancelled: boolean;
-    }>;
-    respondInteraction(invocationId: string, response: InteractionResponse): Promise<void>;
-}
 /** This execution environment is unrelated to the model Context envelope. */
 export interface ExtraContext {
     /** F31：.octospec/tasks/gateway-august-feature-assessment/assessment.md；无日志宿主也提供 no-op。 */
     readonly log: RuntimeLog;
-    readonly adapterHost: ExtraAdapterHost;
+    readonly kernel: KernelClient;
     readonly signal: AbortSignal;
     onDispose(dispose: ExtraDisposer): void;
     onStatus(handler: ExtraStatusHandler): void;
@@ -50,15 +40,16 @@ export declare function assertExtraName(name: unknown): asserts name is string;
 /** 每个声明名最多一个实例；只加载宿主选定的插件，并统一管理取消、状态和清理。 */
 export declare class ExtraPlugins {
     #private;
-    private readonly adapterHost;
+    private readonly kernel;
     private readonly logForExtra;
     static validate(registrations: readonly ExtraRegistration[]): void;
-    constructor(registrations: readonly ExtraRegistration[], adapterHost: ExtraContext["adapterHost"], logForExtra?: (name: string) => RuntimeLog);
+    constructor(registrations: readonly ExtraRegistration[], kernel: KernelClient, logForExtra?: (name: string) => RuntimeLog);
     get status(): Record<string, ExtraStatus>;
     loadConfigured(): Promise<void>;
     inspect(name: string): Promise<JsonObject>;
     load<D extends object>(module: ExtraPluginModule<D>, config: JsonObject, dependencies: Readonly<D>): Promise<void>;
     load(name: string, registration?: ExtraRegistration): Promise<void>;
     unload(name: string): Promise<void>;
+    stopAdmission(): void;
     close(): Promise<void>;
 }

package/node_modules/@mininglamp-oss/{octo-runtime-daemon → octo-runtime-host-sdk}/dist/extras.js

@@ -1,11 +1,13 @@
 import { noopRuntimeLog } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+import { abortForShutdown, shutdownDeadline, withinShutdown } from "./shutdown.js";
+import { snapshotExtraDependencies } from "./extra-dependencies.js";
 export function assertExtraName(name) {
     if (typeof name !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(name))
         throw new Error("EXTRA_NAME_INVALID");
 }
 /** 每个声明名最多一个实例；只加载宿主选定的插件，并统一管理取消、状态和清理。 */
 export class ExtraPlugins {
-    adapterHost;
+    kernel;
     logForExtra;
     #registrations = new Map();
     #instances = new Map();
@@ -29,8 +31,8 @@ export class ExtraPlugins {
             names.add(entry.name);
         }
     }
-    constructor(registrations, adapterHost, logForExtra = () => noopRuntimeLog) {
-        this.adapterHost = adapterHost;
+    constructor(registrations, kernel, logForExtra = () => noopRuntimeLog) {
+        this.kernel = kernel;
         this.logForExtra = logForExtra;
         ExtraPlugins.validate(registrations);
         for (const registration of registrations) {
@@ -83,7 +85,9 @@ export class ExtraPlugins {
     load(target, configOrRegistration, dependencies) {
         if (typeof target !== "string") {
             // 仅在同一 Node 进程闭包捕获函数；复用下方生命周期，不把函数写入声明或传过 IPC。
-            const functions = Object.freeze({ ...dependencies });
+            const functions = dependencies === undefined
+                ? Object.freeze({})
+                : snapshotExtraDependencies(dependencies);
             const registration = {
                 name: target.name,
                 config: configOrRegistration,
@@ -168,7 +172,7 @@ export class ExtraPlugins {
                 assertStatusObject(registration.config);
                 instance.controller.signal.throwIfAborted();
                 const initialize = plugin.default({
-                    adapterHost: this.adapterHost,
+                    kernel: this.kernel,
                     log: (level, event, data) => {
                         try {
                             this.logForExtra(name)(level, event, data);
@@ -204,7 +208,7 @@ export class ExtraPlugins {
                 this.#statuses.set(name, { phase: "loaded" });
             }
             catch (error) {
-                instance.controller.abort();
+                abortForShutdown(instance.controller);
                 let cleanupFailed = false;
                 await withDisposalDeadline(this.#dispose(instance)).catch((cleanupError) => {
                     cleanupFailed = true;
@@ -236,7 +240,9 @@ export class ExtraPlugins {
             return Promise.resolve();
         // 递增代次也能撤销尚未创建 AbortController 的排队 load，防止卸载后又启动旧声明。
         this.#loadEpochs.set(name, (this.#loadEpochs.get(name) ?? 0) + 1);
-        this.#instances.get(name)?.controller.abort();
+        const stopping = this.#instances.get(name);
+        if (stopping)
+            abortForShutdown(stopping.controller);
         const instance = this.#instances.get(name);
         // abort 不能排在初始化 Promise 后面；外部初始化可能正等待这个取消信号才会退出。
         const task = instance ? this.#unload(name) : this.#serial(name, () => this.#unload(name));
@@ -257,14 +263,14 @@ export class ExtraPlugins {
             return Promise.resolve();
         if (instance.disposing)
             return instance.disposing;
-        instance.controller.abort();
+        abortForShutdown(instance.controller);
         this.#statuses.set(name, { phase: "disposing" });
         instance.disposing = (async () => {
             try {
-                await withDisposalDeadline((async () => {
+                await withinShutdown((async () => {
                     await instance.starting.catch(() => undefined);
                     await this.#dispose(instance);
-                })());
+                })(), shutdownDeadline(instance.controller.signal), "EXTRA_DISPOSE_FAILED");
                 this.#statuses.set(name, { phase: "disposed" });
             }
             catch (error) {
@@ -279,12 +285,17 @@ export class ExtraPlugins {
         })();
         return instance.disposing;
     }
+    stopAdmission() {
+        this.#closed = true;
+        for (const instance of this.#instances.values())
+            abortForShutdown(instance.controller);
+    }
     close() {
         if (this.#closing)
             return this.#closing;
         this.#closed = true;
         for (const instance of this.#instances.values())
-            instance.controller.abort();
+            abortForShutdown(instance.controller);
         this.#closing = (async () => {
             const results = await Promise.allSettled([...this.#instances.keys()].reverse().map((name) => this.unload(name)));
             const failures = results.filter((result) => result.status === "rejected");
@@ -308,11 +319,11 @@ export class ExtraPlugins {
         instance.cleanup = (async () => {
             const errors = [];
             // 逆序匹配资源的创建依赖；所有 disposer 共用宽限，单项失败仍继续尝试其余清理。
-            const deadline = Date.now() + 5_000;
+            const deadline = shutdownDeadline(instance.controller.signal);
             for (const dispose of instance.disposers.reverse()) {
                 try {
                     const operation = Promise.resolve().then(dispose);
-                    await withDisposalDeadline(operation, Math.max(1, deadline - Date.now()));
+                    await withinShutdown(operation, deadline, "EXTRA_DISPOSE_FAILED");
                 }
                 catch (error) {
                     errors.push(error);

package/node_modules/@mininglamp-oss/{octo-runtime-daemon/dist/runtime → octo-runtime-host-sdk/dist}/home.d.ts

@@ -2,47 +2,38 @@ export interface MachineIdentity {
     schema_version: 1;
     machine_id: string;
 }
-export interface DaemonHomePaths {
+export interface HostHomePaths {
     home: string;
     machineFile: string;
     run: string;
     socket: string;
     pidFile: string;
-    ownerLock: string;
-    sessionFile: string;
-    supervisorState: string;
-    shutdownFile: string;
 }
-export interface DaemonAccountPaths {
+export interface HostAccountPaths {
     accountKey: string;
     root: string;
     configFile: string;
     logs: string;
 }
-export interface DaemonProfilePaths {
+export interface HostProfilePaths {
     name: string;
     root: string;
     configFile: string;
     identityFile: string;
     credentialFile: string;
 }
-export interface OwnerLock {
-    nonce: string;
-    release(): void;
-}
-export declare function resolveDaemonHome(appId: string, options?: {
+export declare function resolveHostHome(appId: string, options?: {
     platform?: NodeJS.Platform;
     env?: NodeJS.ProcessEnv;
     userHome?: string;
 }): string;
-export declare function daemonHomePaths(homeInput: string, platform?: NodeJS.Platform): DaemonHomePaths;
+export declare function hostHomePaths(homeInput: string, platform?: NodeJS.Platform): HostHomePaths;
 export declare function accountKeyFor(subjectType: string, subjectId: string): string;
 export declare function profileNameFor(appId: string, tenantId: string): string;
-export declare function accountPaths(paths: DaemonHomePaths, accountKey: string): DaemonAccountPaths;
-export declare function profilePaths(account: DaemonAccountPaths, name: string): DaemonProfilePaths;
-export declare function ensureDaemonHome(paths: DaemonHomePaths): MachineIdentity;
-export declare function ensureAccount(account: DaemonAccountPaths, profiles: readonly string[]): void;
-export declare function acquireOwnerLock(paths: DaemonHomePaths): OwnerLock;
+export declare function accountPaths(paths: HostHomePaths, accountKey: string): HostAccountPaths;
+export declare function profilePaths(account: HostAccountPaths, name: string): HostProfilePaths;
+export declare function ensureHostHome(paths: HostHomePaths): MachineIdentity;
+export declare function ensureAccount(account: HostAccountPaths, profiles: readonly string[]): void;
 export declare function readJson<T>(path: string): T;
 export declare function readJsonOptional<T>(path: string): T | undefined;
 export declare function writeJsonAtomic(path: string, value: unknown, secret?: boolean): void;