@mininglamp-oss/octo-runtime 1.0.1 → 1.1.0

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

@@ -2,10 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, parse, resolve, win32 } from "node:path";
-import { DaemonRuntimeError } from "./errors.js";
+import { HostRuntimeError } from "./errors.js";
+import { componentEndpoint } from "./endpoint.js";
 const PROFILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const MACHINE_PATTERN = /^machine_[0-9a-f-]{36}$/;
-export function resolveDaemonHome(appId, options = {}) {
+export function resolveHostHome(appId, options = {}) {
     const slug = appSlug(appId);
     const platform = options.platform ?? process.platform;
     const env = options.env ?? process.env;
@@ -13,7 +14,7 @@ export function resolveDaemonHome(appId, options = {}) {
     if (platform === "win32") {
         const localAppData = env.LOCALAPPDATA?.trim();
         if (!localAppData) {
-            throw new DaemonRuntimeError("HOME_UNAVAILABLE", "home", false, "LOCALAPPDATA is required on Windows");
+            throw new HostRuntimeError("HOME_UNAVAILABLE", "home", false, "LOCALAPPDATA is required on Windows");
         }
         return win32.join(localAppData, slug, "OctoRuntime");
     }
@@ -21,36 +22,30 @@ export function resolveDaemonHome(appId, options = {}) {
         return join(userHome, "Library", "Application Support", slug, "octo-runtime");
     return join(env.XDG_STATE_HOME?.trim() || join(userHome, ".local", "state"), slug, "octo-runtime");
 }
-export function daemonHomePaths(homeInput, platform = process.platform) {
+export function hostHomePaths(homeInput, platform = process.platform) {
     const home = validateHome(homeInput, platform);
     const run = join(home, "run");
-    const socket = platform === "win32"
-        ? `\\\\.\\pipe\\octo-runtime-embedded-${createHash("sha256").update(home.toLowerCase()).digest("hex").slice(0, 16)}`
-        : join(home, "sockets", "octo-runtime-daemon.sock");
+    const socket = componentEndpoint(home, "executor-kernel", platform);
     return {
         home,
         machineFile: join(home, "machine.json"),
         run,
         socket,
-        pidFile: join(home, "octo-daemon.pid"),
-        ownerLock: join(run, "embedded-owner.lock"),
-        sessionFile: join(run, "embedded-session.json"),
-        supervisorState: join(run, "embedded-supervisor.json"),
-        shutdownFile: join(run, "embedded-shutdown")
+        pidFile: join(home, "octo-runtime-executor-kernel.pid")
     };
 }
 export function accountKeyFor(subjectType, subjectId) {
     if (subjectType !== "user" || !subjectId.trim()) {
-        throw new DaemonRuntimeError("SUBJECT_INVALID", "home", false, "a stable user subject is required");
+        throw new HostRuntimeError("SUBJECT_INVALID", "home", false, "a stable user subject is required");
     }
     return base32Hash(`${subjectType}\0${subjectId.trim()}`, 20);
 }
 export function profileNameFor(appId, tenantId) {
     if (!tenantId.trim())
-        throw new DaemonRuntimeError("TENANT_INVALID", "home", false, "tenant id is required");
+        throw new HostRuntimeError("TENANT_INVALID", "home", false, "tenant id is required");
     const name = `${appSlug(appId)}-${base32Hash(tenantId.trim(), 20)}`;
     if (!PROFILE_PATTERN.test(name)) {
-        throw new DaemonRuntimeError("PROFILE_INVALID", "home", false, `generated profile is invalid: ${name}`);
+        throw new HostRuntimeError("PROFILE_INVALID", "home", false, `generated profile is invalid: ${name}`);
     }
     return name;
 }
@@ -65,7 +60,7 @@ export function accountPaths(paths, accountKey) {
 }
 export function profilePaths(account, name) {
     if (!PROFILE_PATTERN.test(name))
-        throw new DaemonRuntimeError("PROFILE_INVALID", "home", false, `invalid profile: ${name}`);
+        throw new HostRuntimeError("PROFILE_INVALID", "home", false, `invalid profile: ${name}`);
     const root = join(account.root, name);
     return {
         name,
@@ -75,7 +70,7 @@ export function profilePaths(account, name) {
         credentialFile: join(root, "credentials", "runtime-token.json")
     };
 }
-export function ensureDaemonHome(paths) {
+export function ensureHostHome(paths) {
     for (const directory of [paths.home, paths.run, join(paths.home, "accounts")])
         mkdirSync(directory, { recursive: true });
     if (process.platform !== "win32")
@@ -83,7 +78,7 @@ export function ensureDaemonHome(paths) {
     if (existsSync(paths.machineFile)) {
         const machine = readJson(paths.machineFile);
         if (machine.schema_version !== 1 || !MACHINE_PATTERN.test(machine.machine_id)) {
-            throw new DaemonRuntimeError("MACHINE_INVALID", "home", false, `invalid machine identity: ${paths.machineFile}`);
+            throw new HostRuntimeError("MACHINE_INVALID", "home", false, `invalid machine identity: ${paths.machineFile}`);
         }
         return machine;
     }
@@ -93,7 +88,7 @@ export function ensureDaemonHome(paths) {
 }
 export function ensureAccount(account, profiles) {
     if (profiles.length === 0)
-        throw new DaemonRuntimeError("TENANTS_EMPTY", "home", false, "at least one authorized tenant is required");
+        throw new HostRuntimeError("TENANTS_EMPTY", "home", false, "at least one authorized tenant is required");
     for (const profile of profiles) {
         const paths = profilePaths(account, profile);
         mkdirSync(dirname(paths.identityFile), { recursive: true });
@@ -111,48 +106,12 @@ export function ensureAccount(account, profiles) {
         channel: "stable"
     });
 }
-export function acquireOwnerLock(paths) {
-    mkdirSync(paths.run, { recursive: true });
-    const nonce = randomUUID();
-    const acquire = () => openSync(paths.ownerLock, "wx", 0o600);
-    let fd;
-    try {
-        fd = acquire();
-    }
-    catch (error) {
-        if (!isNodeError(error, "EEXIST") || lockOwnerAlive(paths.ownerLock)) {
-            throw new DaemonRuntimeError("HOME_LOCKED", "home", false, "Embedded Runtime Home is owned by another process", { cause: error });
-        }
-        rmSync(paths.ownerLock, { force: true });
-        fd = acquire();
-    }
-    writeFileSync(fd, `${JSON.stringify({ schema_version: 1, pid: process.pid, nonce, created_at: new Date().toISOString() })}\n`);
-    fsyncSync(fd);
-    let released = false;
-    return {
-        nonce,
-        release() {
-            if (released)
-                return;
-            released = true;
-            closeSync(fd);
-            try {
-                const current = readJson(paths.ownerLock);
-                if (current.nonce === nonce)
-                    rmSync(paths.ownerLock, { force: true });
-            }
-            catch {
-                // A missing lock is already released; a replaced lock belongs to another session.
-            }
-        }
-    };
-}
 export function readJson(path) {
     try {
         return JSON.parse(readFileSync(path, "utf8"));
     }
     catch (error) {
-        throw new DaemonRuntimeError("LOCAL_STATE_INVALID", "home", false, `cannot read ${path}`, {
+        throw new HostRuntimeError("LOCAL_STATE_INVALID", "home", false, `cannot read ${path}`, {
             cause: error
         });
     }
@@ -185,16 +144,16 @@ export function removeFile(path) {
 function validateHome(homeInput, platform) {
     const pathApi = platform === "win32" ? win32 : { isAbsolute, resolve, parse };
     if (!homeInput.trim() || !pathApi.isAbsolute(homeInput)) {
-        throw new DaemonRuntimeError("HOME_INVALID", "home", false, "Embedded Runtime Home must be an absolute path");
+        throw new HostRuntimeError("HOME_INVALID", "home", false, "Embedded Runtime Home must be an absolute path");
     }
     const home = pathApi.resolve(homeInput);
     const root = pathApi.parse(home).root;
     if (home === root)
-        throw new DaemonRuntimeError("HOME_INVALID", "home", false, "filesystem root cannot be used as Embedded Runtime Home");
+        throw new HostRuntimeError("HOME_INVALID", "home", false, "filesystem root cannot be used as Embedded Runtime Home");
     if (platform === "win32") {
         const input = homeInput.replaceAll("/", "\\");
         if (input.startsWith("\\\\") || input.startsWith("\\\\?\\") || /^[A-Za-z]:[^\\]/.test(input)) {
-            throw new DaemonRuntimeError("HOME_UNSUPPORTED", "home", false, "Windows Embedded Runtime Home must be a local absolute path");
+            throw new HostRuntimeError("HOME_UNSUPPORTED", "home", false, "Windows Embedded Runtime Home must be a local absolute path");
         }
     }
     return home;
@@ -207,7 +166,7 @@ function appSlug(appId) {
         .replace(/^-+|-+$/g, "")
         .slice(0, 48);
     if (!slug || !/^[a-z0-9]/.test(slug)) {
-        throw new DaemonRuntimeError("APP_ID_INVALID", "home", false, "appId must contain an ASCII letter or digit");
+        throw new HostRuntimeError("APP_ID_INVALID", "home", false, "appId must contain an ASCII letter or digit");
     }
     return slug;
 }
@@ -247,19 +206,9 @@ function renameWithRetry(source, target) {
         }
     }
     rmSync(source, { force: true });
-    throw new DaemonRuntimeError("WRITE_FAILED", "home", true, `cannot atomically replace ${target}`, { cause: lastError });
-}
-function lockOwnerAlive(path) {
-    try {
-        const lock = readJson(path);
-        if (!Number.isSafeInteger(lock.pid) || Number(lock.pid) <= 0)
-            return false;
-        process.kill(Number(lock.pid), 0);
-        return true;
-    }
-    catch (error) {
-        return isNodeError(error, "EPERM");
-    }
+    throw new HostRuntimeError("WRITE_FAILED", "home", true, `cannot atomically replace ${target}`, {
+        cause: lastError
+    });
 }
 function isNodeError(error, code) {
     return (error instanceof Error && "code" in error && error.code === code);

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

@@ -1,4 +1,4 @@
-import { type DaemonProfilePaths } from "./home.js";
+import { type HostProfilePaths } from "./home.js";
 import type { AuthorizedTenant } from "./types.js";
 export interface LocalRuntimeIdentity {
     schema_version: 1;
@@ -8,4 +8,4 @@ export interface LocalRuntimeIdentity {
     credential_id?: string;
     enrolled_at?: string;
 }
-export declare function ensureLocalRuntime(profile: DaemonProfilePaths, tenant: AuthorizedTenant): LocalRuntimeIdentity;
+export declare function ensureLocalRuntime(profile: HostProfilePaths, tenant: AuthorizedTenant): LocalRuntimeIdentity;

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { RUNTIME_RUN_CONTRACT } from "@mininglamp-oss/octo-runtime-protocol";
+export * from "./extras.js";
+export * from "./extra-config.js";
+export * from "./context-loader.js";
+export * from "./extra-service.js";
+export * from "./endpoint.js";
+export * from "./home.js";
+export * from "./identity.js";
+export * from "./native.js";
+export type { CleanupResult } from "./launch.js";
+export { ComponentStartError } from "./launch.js";

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

@@ -0,0 +1,10 @@
+export { RUNTIME_RUN_CONTRACT } from "@mininglamp-oss/octo-runtime-protocol";
+export * from "./extras.js";
+export * from "./extra-config.js";
+export * from "./context-loader.js";
+export * from "./extra-service.js";
+export * from "./endpoint.js";
+export * from "./home.js";
+export * from "./identity.js";
+export * from "./native.js";
+export { ComponentStartError } from "./launch.js";

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/dist/launch.d.ts

@@ -0,0 +1,15 @@
+/** Cleanup contract for explicitly configured external native executables. */
+export interface CleanupResult {
+    complete: boolean;
+    processExited: boolean;
+    pendingResources: string[];
+    errors: {
+        code: string;
+        component: string;
+    }[];
+}
+export declare class ComponentStartError extends Error {
+    readonly cleanup: CleanupResult;
+    constructor(cause: unknown, cleanup: CleanupResult);
+}
+export declare function deadline<T>(operation: Promise<T>, timeoutMs: number, code: string): Promise<T>;

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

@@ -0,0 +1,22 @@
+export class ComponentStartError extends Error {
+    cleanup;
+    constructor(cause, cleanup) {
+        super(cause instanceof Error ? cause.message : "COMPONENT_START_FAILED", { cause });
+        this.cleanup = cleanup;
+        this.name = "ComponentStartError";
+    }
+}
+export async function deadline(operation, timeoutMs, code) {
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(code)), timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/dist/native.d.ts

@@ -0,0 +1,16 @@
+import { type CleanupResult } from "./launch.js";
+export interface NativeComponentOptions {
+    executable: string;
+    argv: string[];
+    cwd: string;
+    configPath: string;
+    endpoint: string;
+    stop: "stdin-json" | "signal";
+    readiness: "ipc" | "process";
+}
+/** 原生组件拥有独立进程树，参数始终按 argv 传递，不经过 shell。 */
+export declare function startNativeComponent(options: NativeComponentOptions): Promise<{
+    ownership: "owned";
+    pid: number;
+    stop: () => Promise<CleanupResult>;
+}>;

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

@@ -0,0 +1,160 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { once } from "node:events";
+import net from "node:net";
+import { createProcessCleanup } from "@mininglamp-oss/octo-runtime-adapter-sdk/process-cleanup";
+import { readBoundedLines } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+import { ComponentStartError, deadline } from "./launch.js";
+/** 原生组件拥有独立进程树，参数始终按 argv 传递，不经过 shell。 */
+export async function startNativeComponent(options) {
+    for (const path of [options.executable, options.cwd, options.configPath])
+        if (!isAbsolute(path))
+            throw new Error("COMPONENT_PATH_INVALID");
+    if (options.argv.some((arg) => /^--(?:config|endpoint)(?:=|$)/.test(arg)))
+        throw new Error("COMPONENT_RESERVED_ARGUMENT");
+    const child = spawn(options.executable, [...options.argv, "--config", options.configPath, "--endpoint", options.endpoint], {
+        cwd: options.cwd,
+        shell: false,
+        stdio: ["pipe", "pipe", "ignore"],
+        detached: process.platform !== "win32"
+    });
+    const cleanup = createProcessCleanup(child, {
+        processGroup: process.platform !== "win32",
+        processTree: true
+    });
+    let ack;
+    child.stdin.on("error", () => ack?.reject(new Error("COMPONENT_INPUT_CLOSED")));
+    child.on("error", () => ack?.reject(new Error("COMPONENT_EXITED")));
+    child.once("exit", () => ack?.reject(new Error("COMPONENT_CLEANUP_UNCONFIRMED")));
+    const stopInput = readBoundedLines(child.stdout, 4096, {
+        onError: () => { },
+        onTooLarge: () => { },
+        onClose: () => { },
+        onLine(line) {
+            try {
+                const value = JSON.parse(line);
+                if (ack && value.type === "component.stopped" && value.request_id === ack.id) {
+                    if (value.complete === true)
+                        ack.resolve();
+                    else
+                        ack.reject(new Error("COMPONENT_CLEANUP_INCOMPLETE"));
+                }
+            }
+            catch {
+                /* 原生组件 stdout 不作诊断或业务数据来源。 */
+            }
+        }
+    });
+    let closing;
+    const stop = () => (closing ??= (async () => {
+        const errors = [];
+        if (child.exitCode === null && child.signalCode === null) {
+            try {
+                if (options.stop === "stdin-json") {
+                    const pending = new Promise((resolve, reject) => {
+                        ack = { id: randomUUID(), resolve, reject };
+                    });
+                    void pending.catch(() => undefined);
+                    child.stdin.write(`${JSON.stringify({ type: "component.stop", request_id: ack.id })}\n`);
+                    await deadline(pending, 5000, "COMPONENT_STOP_TIMEOUT");
+                }
+                else {
+                    child.kill("SIGTERM");
+                    await deadline(once(child, "exit"), 5000, "COMPONENT_STOP_TIMEOUT");
+                }
+            }
+            catch {
+                errors.push({ component: options.executable, code: "COMPONENT_CLEANUP_INCOMPLETE" });
+            }
+        }
+        else {
+            errors.push({ component: options.executable, code: "COMPONENT_CLEANUP_UNCONFIRMED" });
+        }
+        try {
+            await cleanup();
+        }
+        catch {
+            errors.push({ component: options.executable, code: "PROCESS_CLEANUP_INCOMPLETE" });
+        }
+        finally {
+            stopInput();
+        }
+        const processExited = child.exitCode !== null || child.signalCode !== null;
+        return {
+            complete: !errors.length && processExited,
+            processExited,
+            errors,
+            pendingResources: errors.length ? ["native"] : []
+        };
+    })());
+    try {
+        await deadline(once(child, "spawn"), 5000, "COMPONENT_START_TIMEOUT");
+        if (options.readiness === "ipc") {
+            const until = Date.now() + 30_000;
+            while (true) {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    throw new Error("COMPONENT_EXITED");
+                try {
+                    await nativeStatus(options.endpoint, child.pid);
+                    break;
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message === "COMPONENT_IDENTITY_MISMATCH")
+                        throw error;
+                    if (Date.now() >= until)
+                        throw new Error("COMPONENT_START_TIMEOUT", { cause: error });
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                }
+            }
+        }
+    }
+    catch (error) {
+        throw new ComponentStartError(error, await stop());
+    }
+    return { ownership: "owned", pid: child.pid, stop };
+}
+async function nativeStatus(endpoint, pid) {
+    await new Promise((resolve, reject) => {
+        const socket = net.createConnection(endpoint);
+        const requestId = randomUUID();
+        let bytes = "";
+        socket.setTimeout(1000, () => {
+            socket.destroy();
+            reject(new Error("COMPONENT_UNAVAILABLE"));
+        });
+        socket.on("error", reject);
+        socket.on("connect", () => socket.write(`${JSON.stringify({ jsonrpc: "2.0", id: requestId, method: "status", params: {} })}\n`));
+        socket.on("data", (chunk) => {
+            bytes += chunk.toString();
+            if (bytes.length > 4096) {
+                socket.destroy();
+                reject(new Error("COMPONENT_STATUS_INVALID"));
+            }
+            if (bytes.includes("\n")) {
+                try {
+                    const reply = JSON.parse(bytes.slice(0, bytes.indexOf("\n")));
+                    if (reply.jsonrpc !== "2.0" || reply.id !== requestId || !reply.result)
+                        throw new Error();
+                    if (typeof reply.result !== "object" ||
+                        !("pid" in reply.result) ||
+                        reply.result.pid !== pid) {
+                        socket.destroy();
+                        reject(new Error("COMPONENT_IDENTITY_MISMATCH"));
+                        return;
+                    }
+                    resolve();
+                }
+                catch {
+                    reject(new Error("COMPONENT_STATUS_INVALID"));
+                }
+                socket.destroy();
+            }
+        });
+        socket.on("end", () => {
+            if (!bytes.includes("\n"))
+                reject(new Error("COMPONENT_UNAVAILABLE"));
+        });
+        socket.on("close", () => reject(new Error("COMPONENT_UNAVAILABLE")));
+    });
+}

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/dist/shutdown.d.ts

@@ -0,0 +1,7 @@
+/** 私有关闭预算；不增加 ExtraContext 的公开字段或插件 ABI。 */
+export declare function shutdownDeadline(signal?: AbortSignal): number;
+export declare function withShutdownDeadline<T>(until: number, operation: () => T): T;
+export declare function abortForShutdown(controller: AbortController): void;
+export declare function shutdownSignal(signals: AbortSignal[]): AbortSignal;
+/** 只限制等待时间，不强停 operation；owner 须在到期后撤销迟到操作的写入和投递权限。 */
+export declare function withinShutdown<T>(operation: Promise<T>, until: number, code: string): Promise<T>;

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

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { performance } from "node:perf_hooks";
+const scope = new AsyncLocalStorage();
+const deadlines = new WeakMap();
+const parents = new WeakMap();
+/** 私有关闭预算；不增加 ExtraContext 的公开字段或插件 ABI。 */
+export function shutdownDeadline(signal) {
+    const inherited = signal && parents.get(signal);
+    return Math.min(scope.getStore() ?? Infinity, (signal && deadlines.get(signal)) ?? Infinity, ...(inherited?.map((parent) => shutdownDeadline(parent)) ?? []), performance.now() + 4000);
+}
+export function withShutdownDeadline(until, operation) {
+    return scope.run(Math.min(scope.getStore() ?? Infinity, until), operation);
+}
+export function abortForShutdown(controller) {
+    if (!deadlines.has(controller.signal))
+        deadlines.set(controller.signal, shutdownDeadline());
+    controller.abort();
+}
+export function shutdownSignal(signals) {
+    // AbortSignal.any 不携带私有预算；保留父信号关系，让稍后开始的 dispose 仍继承最早期限。
+    const signal = AbortSignal.any(signals);
+    parents.set(signal, signals);
+    return signal;
+}
+/** 只限制等待时间，不强停 operation；owner 须在到期后撤销迟到操作的写入和投递权限。 */
+export async function withinShutdown(operation, until, code) {
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(code)), Math.max(0, until - performance.now()));
+            })
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/dist/types.d.ts

@@ -0,0 +1,4 @@
+export interface AuthorizedTenant {
+    id: string;
+    name?: string;
+}

package/node_modules/@mininglamp-oss/octo-runtime-host-sdk/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mininglamp-oss/octo-runtime-host-sdk",
+  "version": "1.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./shutdown": "./dist/shutdown.js",
+    "./extra": {
+      "types": "./dist/extras.d.ts",
+      "import": "./dist/extras.js"
+    },
+    "./extra-config": {
+      "types": "./dist/extra-config.d.ts",
+      "import": "./dist/extra-config.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@mininglamp-oss/octo-runtime-adapter-sdk": "1.1.0",
+    "@mininglamp-oss/octo-runtime-executor-kernel": "1.1.0",
+    "@mininglamp-oss/octo-runtime-protocol": "1.1.0"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ]
+}