@mininglamp-oss/octo-runtime 1.0.1 → 1.1.1

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

@@ -0,0 +1,436 @@
+import net from "node:net";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readBoundedLines } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+import { assertHostRunReceipt, createInputInvoke, contextItem, INVOKE_REQUEST_MAX_BYTES, HOST_RPC_MAX_LINE_BYTES } from "@mininglamp-oss/octo-runtime-protocol";
+import { HostRunService } from "./host-run-service.js";
+import { WorkerSupervisor } from "./supervisor.js";
+import { acquireEndpoint } from "./endpoint.js";
+import { InvocationManifest } from "./invocation-manifest.js";
+import { readModuleManifest, resolveAdapterModules } from "@mininglamp-oss/octo-runtime-adapter-sdk/module-manifest";
+import { KernelError } from "./types.js";
+function validateParams(method, params) {
+    const fields = {
+        status: [],
+        "adapter.list": [],
+        "agent_run.invoke": ["input", "executionEnvOverrides", "kernel_instance_id"],
+        "agent_run.get": ["key", "kernel_instance_id"],
+        "agent_run.subscribe": ["ref", "after_seq"],
+        "agent_run.cancel": ["ref", "reason"],
+        "agent_run.respond": ["ref", "response"],
+        "agent_run.native.respond": ["ref", "response"]
+    };
+    const allowed = fields[method];
+    if (!allowed)
+        throw new KernelError("METHOD_NOT_FOUND");
+    if (Object.keys(params).some((key) => !allowed.includes(key)))
+        throw new KernelError("INVALID_PARAMS");
+    if (method === "agent_run.invoke" &&
+        (!record(params.input) ||
+            (params.executionEnvOverrides !== undefined && !record(params.executionEnvOverrides))))
+        throw new KernelError("INVALID_PARAMS");
+    if (method === "agent_run.get") {
+        const key = params.key;
+        if (!record(key) ||
+            Object.keys(key).length !== 5 ||
+            Object.keys(key).some((field) => ![
+                "run_id",
+                "invocation_id",
+                "agent_session_id",
+                "session_generation",
+                "protocol_mode"
+            ].includes(field)) ||
+            ["run_id", "invocation_id", "agent_session_id"].some((field) => typeof key[field] !== "string" || !key[field]) ||
+            !Number.isSafeInteger(key.session_generation) ||
+            Number(key.session_generation) < 0 ||
+            !["native", "canonical"].includes(String(key.protocol_mode)) ||
+            (params.kernel_instance_id !== undefined && typeof params.kernel_instance_id !== "string"))
+            throw new KernelError("INVALID_PARAMS");
+    }
+    if (allowed.includes("ref")) {
+        if (!record(params.ref) ||
+            typeof params.ref.kernel_instance_id !== "string" ||
+            !params.ref.kernel_instance_id)
+            throw new KernelError("INVALID_PARAMS");
+        const { kernel_instance_id: instance, ...receipt } = params.ref;
+        void instance;
+        try {
+            assertHostRunReceipt(receipt);
+        }
+        catch {
+            throw new KernelError("INVALID_PARAMS");
+        }
+    }
+    if (allowed.includes("response") && !record(params.response))
+        throw new KernelError("INVALID_PARAMS");
+    if (params.reason !== undefined && typeof params.reason !== "string")
+        throw new KernelError("INVALID_PARAMS");
+}
+/**
+ * 创建独立 Kernel 的本地 RPC 端点，独占端点租约、Run 事件源与 worker 监督器。
+ * 启动失败也执行回收；close 失败会保留所有权证据，客户端断开不等同于 owner 关闭。
+ */
+export async function startKernelServer(options, signal) {
+    if (options.manifest && options.adapterModules !== undefined)
+        throw new TypeError("manifest and adapterModules are mutually exclusive");
+    // 文件仅在服务启动时读取一次；worker 自动恢复沿用快照，不因磁盘改动改变加载集合。
+    const adapterModules = options.manifest
+        ? resolveAdapterModules(await readModuleManifest(options.manifest, { legacy: true }))
+        : options.adapterModules;
+    const instance = randomUUID();
+    let manifest;
+    const worker = new WorkerSupervisor({ entrypoint: options.workerEntrypoint, adapterModules, env: options.env }, (pid) => manifest?.setWorker(pid, options.workerEntrypoint) ?? Promise.resolve());
+    const configure = (input) => {
+        const type = contextItem(input.contexts, "octo.execution", "adapter")?.payload.type;
+        return (options.configurations?.(typeof input.runMetadata?.runtimeId === "string" ? input.runMetadata.runtimeId : undefined) ?? options.adapterConfigurations)?.[typeof type === "string" ? type : "codex"];
+    };
+    const transport = {
+        list: (configs) => worker.client.list(configs ?? options.configurations?.() ?? options.adapterConfigurations),
+        probe: (type, config) => worker.client.probe(type, config),
+        cancel: (id, reason) => worker.client.cancel(id, reason),
+        respondInteraction: (id, response) => worker.client.respondInteraction(id, response),
+        respondNative: (id, response) => worker.client.respondNative(id, response),
+        invoke: createInputInvoke((input, environment) => transport.invokeFrames(input, environment)),
+        async *invokeFrames(input, environment) {
+            const config = configure(input);
+            yield* worker.client.invokeFrames(config
+                ? {
+                    ...input,
+                    agentConfig: {
+                        ...input.agentConfig,
+                        providerOptions: {
+                            ...input.agentConfig?.providerOptions,
+                            ...config.providerOptions
+                        }
+                    }
+                }
+                : input, environment);
+        }
+    };
+    const runs = new HostRunService(transport, (input) => configure(input)?.streamLimits);
+    const sockets = new Set();
+    let closing;
+    let listening = false;
+    let releaseEndpoint;
+    const status = () => ({
+        ipc_version: 1,
+        kernel_instance_id: instance,
+        pid: process.pid,
+        worker: worker.status,
+        execution_ready: !closing && worker.status.state === "ready"
+    });
+    const snapshot = (key, expected) => {
+        if (expected !== undefined && expected !== instance)
+            throw new KernelError("KERNEL_INSTANCE_CHANGED");
+        if (!key || typeof key !== "object" || typeof key.run_id !== "string")
+            throw new KernelError("INVALID_PARAMS");
+        const { oldest_seq, latest_seq, terminal, ...receipt } = runs.get(key.run_id);
+        for (const field of [
+            "run_id",
+            "invocation_id",
+            "agent_session_id",
+            "session_generation",
+            "protocol_mode"
+        ]) {
+            if (key[field] !== receipt[field])
+                throw new KernelError("RUN_IDENTITY_MISMATCH");
+        }
+        return {
+            ref: { ...receipt, kernel_instance_id: instance },
+            oldest_seq,
+            latest_seq,
+            ...(terminal ? { terminal } : {})
+        };
+    };
+    const validateRef = (value) => {
+        const ref = value;
+        if (!ref || typeof ref.kernel_instance_id !== "string")
+            throw new KernelError("INVALID_PARAMS");
+        const result = snapshot(ref, ref.kernel_instance_id);
+        if (ref.stream_id !== result.ref.stream_id || ref.protocol !== result.ref.protocol)
+            throw new KernelError("RUN_IDENTITY_MISMATCH");
+        return result;
+    };
+    const handle = async (line, socket) => {
+        let id = null;
+        let streaming = false;
+        try {
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                throw new KernelError("PARSE_ERROR");
+            }
+            if (!record(request) ||
+                request.jsonrpc !== "2.0" ||
+                typeof request.id !== "string" ||
+                !request.id ||
+                Buffer.byteLength(request.id) > 128 ||
+                typeof request.method !== "string")
+                throw new KernelError("INVALID_REQUEST");
+            id = request.id;
+            if (Object.keys(request).some((key) => !["jsonrpc", "id", "method", "params"].includes(key)) ||
+                !record(request.params))
+                throw new KernelError("INVALID_PARAMS");
+            const params = request.params;
+            validateParams(request.method, params);
+            let result;
+            switch (request.method) {
+                case "status":
+                    result = status();
+                    break;
+                case "adapter.list":
+                    result = await runs.list();
+                    break;
+                case "agent_run.invoke": {
+                    if (params.kernel_instance_id !== undefined && params.kernel_instance_id !== instance)
+                        throw new KernelError("KERNEL_INSTANCE_CHANGED");
+                    if (worker.status.state === "exhausted")
+                        throw new KernelError("WORKER_RESTART_EXHAUSTED");
+                    if (!status().execution_ready)
+                        throw new KernelError("KERNEL_UNAVAILABLE");
+                    const receipt = await runs.submit(params.input, {
+                        executionEnvOverrides: params.executionEnvOverrides
+                    });
+                    result = { kernel_instance_id: instance, receipt };
+                    break;
+                }
+                case "agent_run.get":
+                    result = snapshot(params.key, params.kernel_instance_id);
+                    break;
+                case "agent_run.subscribe": {
+                    const info = validateRef(params.ref);
+                    if (typeof params.after_seq !== "number")
+                        throw new KernelError("STREAM_CURSOR_INVALID");
+                    let after = params.after_seq;
+                    // 先校验 cursor 再发送 ACK，避免错误被解释成空订阅成功。
+                    runs.read(info.ref.run_id, info.ref.stream_id, after);
+                    const release = runs.acquireSubscription();
+                    try {
+                        await write(socket, { jsonrpc: "2.0", id, result: info });
+                        streaming = true;
+                        while (!socket.destroyed) {
+                            const page = runs.read(info.ref.run_id, info.ref.stream_id, after);
+                            for (const event of page.events) {
+                                await write(socket, {
+                                    jsonrpc: "2.0",
+                                    method: "agent_run.event",
+                                    params: {
+                                        kernel_instance_id: instance,
+                                        run_id: info.ref.run_id,
+                                        stream_id: info.ref.stream_id,
+                                        seq: event.seq,
+                                        event: event.event
+                                    }
+                                });
+                                after = event.seq;
+                            }
+                            if (page.terminal && after >= page.latest_seq) {
+                                socket.end();
+                                return;
+                            }
+                            if (!page.events.length)
+                                await new Promise((resolve) => {
+                                    const done = () => {
+                                        clearTimeout(timer);
+                                        socket.off("close", done);
+                                        resolve();
+                                    };
+                                    const timer = setTimeout(done, 25);
+                                    socket.once("close", done);
+                                });
+                        }
+                    }
+                    finally {
+                        release();
+                    }
+                    return;
+                }
+                case "agent_run.cancel": {
+                    const info = validateRef(params.ref);
+                    const response = info.terminal
+                        ? { cancelled: false }
+                        : await runs.cancelRun(info.ref.run_id, typeof params.reason === "string" ? params.reason : undefined);
+                    result = { accepted: response.cancelled };
+                    break;
+                }
+                case "agent_run.respond": {
+                    const info = validateRef(params.ref);
+                    await runs.respond(info.ref.run_id, params.response);
+                    result = {};
+                    break;
+                }
+                case "agent_run.native.respond": {
+                    const info = validateRef(params.ref);
+                    await runs.respondNativeRun(info.ref.run_id, params.response);
+                    result = {};
+                    break;
+                }
+                default:
+                    throw new KernelError("METHOD_NOT_FOUND");
+            }
+            await write(socket, { jsonrpc: "2.0", id, result });
+            socket.end();
+        }
+        catch (error) {
+            const code = safeCode(error);
+            const rpcCode = {
+                PARSE_ERROR: -32700,
+                INVALID_REQUEST: -32600,
+                METHOD_NOT_FOUND: -32601,
+                INVALID_PARAMS: -32602
+            }[code] ?? -32001;
+            if (!socket.destroyed) {
+                await write(socket, streaming
+                    ? {
+                        jsonrpc: "2.0",
+                        method: "agent_run.stream_error",
+                        params: { code, kernel_instance_id: instance }
+                    }
+                    : {
+                        jsonrpc: "2.0",
+                        id,
+                        error: { code: rpcCode, message: "Kernel request failed", data: { code } }
+                    }).catch(() => undefined);
+                socket.end();
+            }
+        }
+    };
+    const server = net.createServer((socket) => {
+        socket.on("error", () => socket.destroy());
+        if (sockets.size >= 64) {
+            socket.destroy();
+            return;
+        }
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+        socket.setTimeout(5000, () => socket.destroy());
+        const stop = readBoundedLines(socket, INVOKE_REQUEST_MAX_BYTES, {
+            onError: () => socket.destroy(),
+            onClose: () => { },
+            onTooLarge: () => socket.destroy(),
+            onLine: (line) => {
+                stop();
+                socket.pause();
+                socket.setTimeout(0);
+                void handle(line, socket);
+            }
+        });
+    });
+    const teardown = async (until = Date.now() + 5000) => {
+        runs.beginDrain();
+        for (const socket of sockets)
+            socket.destroy();
+        const errors = [];
+        const attempt = async (operation) => {
+            try {
+                await operation();
+                return true;
+            }
+            catch (error) {
+                errors.push(error);
+                return false;
+            }
+        };
+        if (listening)
+            await attempt(() => new Promise((resolve) => server.close(() => resolve())));
+        // 先终止 worker 才能让失联的源流结束，再清空 Run 缓存；每个资源仍独立尝试回收并汇总失败。
+        // 内部沿用服务截止时间，为清单和端点收尾预留时间；不重启一份独立关闭预算。
+        const workerStopped = await attempt(() => worker.close(until - 200));
+        await attempt(() => runs.close());
+        // An incomplete worker close retains ownership, including an observed executor cleanup failure.
+        if (workerStopped) {
+            await attempt(() => manifest?.close() ?? Promise.resolve());
+            if (listening && process.platform !== "win32")
+                await attempt(() => rm(options.endpoint, { force: true }));
+            if (!errors.length)
+                await attempt(() => releaseEndpoint?.() ?? Promise.resolve());
+        }
+        if (errors.length)
+            throw new AggregateError(errors, "KERNEL_CLEANUP_INCOMPLETE");
+    };
+    try {
+        signal?.throwIfAborted();
+        if (process.platform !== "win32")
+            await mkdir(dirname(options.endpoint), { recursive: true, mode: 0o700 });
+        signal?.throwIfAborted();
+        releaseEndpoint = await acquireEndpoint(options.endpoint);
+        signal?.throwIfAborted();
+        const statePath = options.stateDirectory
+            ? join(options.stateDirectory, "kernel-invocations.json")
+            : process.platform !== "win32"
+                ? `${options.endpoint}.runs`
+                : undefined;
+        if (statePath)
+            manifest = (await InvocationManifest.open(statePath)).manifest;
+        signal?.throwIfAborted();
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.endpoint, () => {
+                listening = true;
+                resolve();
+            });
+        });
+        signal?.throwIfAborted();
+        if (process.platform !== "win32")
+            await chmod(options.endpoint, 0o600);
+        signal?.throwIfAborted();
+        await worker.start(signal);
+        signal?.throwIfAborted();
+    }
+    catch (error) {
+        try {
+            await teardown();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "KERNEL_START_CLEANUP_INCOMPLETE", {
+                cause: cleanupError
+            });
+        }
+        throw error;
+    }
+    return {
+        status,
+        close(until) {
+            return (closing ??= teardown(until));
+        }
+    };
+}
+function record(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function safeCode(error) {
+    return error instanceof Error && /^[A-Z][A-Z0-9_]{1,80}$/.test(error.message)
+        ? error.message
+        : "KERNEL_REQUEST_FAILED";
+}
+async function write(socket, value) {
+    if (socket.destroyed)
+        throw new KernelError("CONNECTION_CLOSED");
+    const line = `${JSON.stringify(value)}\n`;
+    if (Buffer.byteLength(line) > HOST_RPC_MAX_LINE_BYTES)
+        throw new KernelError("HOST_FRAME_TOO_LARGE");
+    if (socket.write(line))
+        return;
+    await new Promise((resolve, reject) => {
+        const done = (error) => {
+            clearTimeout(timer);
+            socket.off("drain", drain);
+            socket.off("close", close);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const drain = () => done();
+        const close = () => done(new KernelError("CONNECTION_CLOSED"));
+        const timer = setTimeout(() => {
+            socket.destroy();
+            close();
+        }, 5000);
+        socket.once("drain", drain);
+        socket.once("close", close);
+    });
+}

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

@@ -0,0 +1,15 @@
+import { type KernelServerOptions } from "./server.js";
+import type { KernelClient, KernelStatus } from "./types.js";
+import { type ServiceLifecycle, type ServicePhase } from "./lifecycle.js";
+export type KernelServiceOptions = KernelServerOptions;
+export interface KernelServiceStatus {
+    phase: ServicePhase;
+    endpoint: string;
+    pid: number;
+    kernel?: KernelStatus;
+}
+export interface KernelService extends ServiceLifecycle<KernelServiceStatus> {
+    readonly client: KernelClient;
+}
+/** 服务 socket 直接属于调用进程；只允许 server 内部创建执行 worker。 */
+export declare function createKernelService(options: KernelServiceOptions): KernelService;

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

@@ -0,0 +1,105 @@
+import { attachKernel } from "./client.js";
+import { startKernelServer } from "./server.js";
+import { beforeDeadline, ServiceInitializationError } from "./lifecycle.js";
+/** 服务 socket 直接属于调用进程；只允许 server 内部创建执行 worker。 */
+export function createKernelService(options) {
+    const configuration = {
+        ...options,
+        adapterModules: options.adapterModules && structuredClone(options.adapterModules),
+        adapterConfigurations: options.adapterConfigurations && structuredClone(options.adapterConfigurations),
+        env: options.env && { ...options.env }
+    };
+    const owner = new AbortController();
+    let phase = "created";
+    let server;
+    let client;
+    let starting;
+    let initialized;
+    let startupFailure;
+    let closing;
+    let finishClosed;
+    const closed = new Promise((resolve) => {
+        finishClosed = resolve;
+    });
+    const close = () => {
+        if (closing)
+            return closing;
+        phase = "closing";
+        owner.abort();
+        client?.close();
+        closing = (async () => {
+            const until = Date.now() + 5000;
+            const errors = [];
+            try {
+                await beforeDeadline(starting?.catch(() => undefined) ?? Promise.resolve(), until);
+                if (startupFailure instanceof AggregateError)
+                    throw startupFailure;
+                await beforeDeadline(server?.close(until) ?? Promise.resolve(), until);
+            }
+            catch {
+                errors.push({ resource: "kernel", code: "KERNEL_CLEANUP_INCOMPLETE" });
+            }
+            phase = errors.length ? "failed" : "closed";
+            const result = {
+                complete: !errors.length,
+                errors,
+                pendingResources: errors.map((error) => error.resource)
+            };
+            finishClosed(result);
+            return result;
+        })();
+        return closing;
+    };
+    return {
+        closed,
+        get client() {
+            if (phase !== "ready" || !client)
+                throw new Error("KERNEL_NOT_INITIALIZED");
+            return client;
+        },
+        initialize({ signal } = {}) {
+            if (initialized)
+                return initialized;
+            if (phase !== "created")
+                return Promise.reject(new Error("SERVICE_CLOSED"));
+            phase = "initializing";
+            const combined = signal ? AbortSignal.any([owner.signal, signal]) : owner.signal;
+            let onAbort;
+            const cancelled = new Promise((_, reject) => {
+                onAbort = () => reject(combined.reason instanceof Error
+                    ? combined.reason
+                    : new Error("SERVICE_INITIALIZATION_CANCELLED", { cause: combined.reason }));
+                combined.addEventListener("abort", onAbort, { once: true });
+                if (combined.aborted)
+                    onAbort();
+            });
+            // 原 server 负责部分启动的回滚；初始化失败后仍保留其清理事实。
+            starting = startKernelServer(configuration, combined)
+                .then((value) => {
+                server = value;
+                combined.throwIfAborted();
+                client = attachKernel({ endpoint: configuration.endpoint });
+                phase = "ready";
+            })
+                .catch((error) => {
+                startupFailure = error;
+                if (!closing)
+                    phase = "failed";
+                throw error;
+            });
+            initialized = Promise.race([starting, cancelled])
+                .catch(async (error) => {
+                throw new ServiceInitializationError(error, await close());
+            })
+                .finally(() => combined.removeEventListener("abort", onAbort));
+            return initialized;
+        },
+        status: () => Promise.resolve({
+            phase,
+            endpoint: configuration.endpoint,
+            pid: process.pid,
+            ...(server ? { kernel: server.status() } : {})
+        }),
+        close
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type SpawnWorkerOptions } from "./process.js";
+import type { KernelStatus } from "./types.js";
+/** Kernel exclusively owns worker replacement; incomplete cleanup prevents a second owner. */
+export declare class WorkerSupervisor {
+    #private;
+    private readonly options;
+    private readonly recordWorker?;
+    constructor(options: SpawnWorkerOptions, recordWorker?: ((pid: number | undefined) => Promise<void>) | undefined);
+    get status(): KernelStatus["worker"];
+    get client(): import("./rpc.js").WorkerRpcClient;
+    start(signal?: AbortSignal): Promise<void>;
+    close(until?: number): Promise<void>;
+}