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

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/windows-task.js

@@ -0,0 +1,414 @@
+/** Windows current-user service backend implemented with Task Scheduler. */
+import { join, win32 } from "node:path";
+import { definitionDrift, escapeXml, normalizeServiceSpec, readDefinition, removeDefinition, runCommand, writeDefinition } from "./common.js";
+import { ServiceError } from "./errors.js";
+import { NodeCommandRunner } from "./runner.js";
+const WINDOWS_TASK_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._ -]{0,199}$/;
+const TASK_RESTART_MINIMUM_SECONDS = 60;
+/**
+ * Manage a least-privilege Task Scheduler task for the current Windows user.
+ *
+ * The task uses an `InteractiveToken` principal and a logon trigger, so it runs
+ * while that user is signed in (including while the session is locked). It is
+ * intentionally not a Windows SCM service and does not run before user logon.
+ * Desired XML is retained as a protected sidecar for deterministic drift checks.
+ */
+export class WindowsUserTaskBackend {
+    kind = "windows-user-task";
+    #platform;
+    #runner;
+    #homeDirectory;
+    #environment;
+    #windowsUserId;
+    #schtasks;
+    #powershell;
+    #definitionDirectory;
+    /** Build a backend for the current Windows user, with injectable dependencies for tests. */
+    constructor(options = {}) {
+        this.#platform = options.platform ?? process.platform;
+        this.#runner = options.runner ?? new NodeCommandRunner();
+        this.#homeDirectory = options.homeDirectory ?? process.env.USERPROFILE ?? "";
+        this.#environment = options.environment ?? process.env;
+        this.#windowsUserId = options.windowsUserId ?? windowsUserId(this.#environment);
+        const windowsDirectory = this.#environment.SystemRoot ?? this.#environment.WINDIR ?? "C:\\Windows";
+        this.#schtasks =
+            options.schtasksPath ?? win32.join(windowsDirectory, "System32", "schtasks.exe");
+        this.#powershell =
+            options.powershellPath ??
+                win32.join(windowsDirectory, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+        const localAppData = this.#environment.LOCALAPPDATA ?? win32.join(this.#homeDirectory, "AppData", "Local");
+        this.#definitionDirectory =
+            options.windowsDefinitionDirectory ?? win32.join(localAppData, "OctoRuntime", "services");
+    }
+    /** Report whether Task Scheduler and query cmdlets work for this user; no task is created. */
+    async probe() {
+        if (this.#platform !== "win32")
+            return { supported: false, manager: this.kind, detail: "requires Windows" };
+        if (!this.#homeDirectory || !this.#windowsUserId) {
+            return {
+                supported: false,
+                manager: this.kind,
+                detail: "current Windows user or profile is unavailable"
+            };
+        }
+        try {
+            const scheduler = await runCommand(this.#runner, this.kind, this.#schtasks, ["/Query", "/FO", "CSV", "/NH"], {
+                checked: false,
+                env: this.#environment
+            });
+            if (scheduler.exitCode !== 0) {
+                return {
+                    supported: false,
+                    manager: this.kind,
+                    detail: (scheduler.stderr || scheduler.stdout).trim() || "Task Scheduler is unavailable"
+                };
+            }
+            await runCommand(this.#runner, this.kind, this.#powershell, powershellArguments("Get-Command Get-ScheduledTask -ErrorAction Stop | Out-Null"), {
+                env: this.#environment
+            });
+            return { supported: true, manager: this.kind };
+        }
+        catch (error) {
+            return {
+                supported: false,
+                manager: this.kind,
+                detail: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /** Return live scheduler state and exact drift from the desired XML/principal/action. */
+    async inspect(spec) {
+        const normalized = this.#normalize(spec);
+        const taskName = windowsTaskName(normalized);
+        const definitionPath = this.#definitionPath(normalized);
+        const desired = renderWindowsTaskXmlNormalized(normalized, taskName, this.#windowsUserId);
+        const actual = await readDefinition(definitionPath);
+        const exists = await this.#exists(taskName);
+        if (!exists) {
+            return {
+                manager: this.kind,
+                state: "not_installed",
+                enabled: false,
+                definitionPath,
+                drift: ["manager_definition_missing", ...definitionDrift(actual, desired)]
+            };
+        }
+        const queried = await this.#query(taskName);
+        if (queried.exitCode !== 0) {
+            return {
+                manager: this.kind,
+                state: "unknown",
+                enabled: false,
+                definitionPath,
+                drift: definitionDrift(actual, desired),
+                detail: (queried.stderr || queried.stdout).trim() || "PowerShell task status query failed"
+            };
+        }
+        let task;
+        try {
+            task = JSON.parse(queried.stdout);
+        }
+        catch {
+            return {
+                manager: this.kind,
+                state: "unknown",
+                enabled: false,
+                definitionPath,
+                drift: definitionDrift(actual, desired),
+                detail: "PowerShell returned an invalid task status payload"
+            };
+        }
+        return {
+            manager: this.kind,
+            state: windowsTaskState(task.state),
+            enabled: task.enabled === true,
+            lastExitCode: task.last_exit_code,
+            definitionPath,
+            drift: [
+                ...definitionDrift(actual, desired),
+                ...windowsManagerDrift(task, normalized, this.#windowsUserId)
+            ],
+            detail: task.state ? undefined : "Task Scheduler did not report a state"
+        };
+    }
+    /**
+     * Leave the registered task and enabled setting matching `spec`.
+     * A stopped task stays stopped; a previously running task is relaunched only
+     * when the reconciled task remains enabled.
+     */
+    async install(spec) {
+        const normalized = this.#normalize(spec);
+        const taskName = windowsTaskName(normalized);
+        const definitionPath = this.#definitionPath(normalized);
+        // Re-registration replaces Task Scheduler's definition. Capture running
+        // state first so install can restore it without becoming an implicit start.
+        const previous = await this.inspect(spec);
+        await writeDefinition(definitionPath, renderWindowsTaskXmlNormalized(normalized, taskName, this.#windowsUserId));
+        if (previous.state === "running") {
+            await this.#schtasksCommand(["/End", "/TN", taskName], false);
+        }
+        await this.#schtasksCommand(["/Create", "/TN", taskName, "/XML", definitionPath, "/F"]);
+        // Restore only a previously running enabled task. A stopped task remains
+        // stopped, so setup controls the explicit first start and readiness wait.
+        if (previous.state === "running" && normalized.enabled) {
+            await this.#schtasksCommand(["/Run", "/TN", taskName]);
+        }
+    }
+    /** Finish with no scheduled task or XML sidecar; Runtime credentials and data remain. */
+    async uninstall(spec) {
+        const normalized = this.#normalize(spec);
+        const taskName = windowsTaskName(normalized);
+        await this.#schtasksCommand(["/End", "/TN", taskName], false);
+        await this.#schtasksCommand(["/Delete", "/TN", taskName, "/F"], false);
+        await removeDefinition(this.#definitionPath(normalized));
+    }
+    /** Enable future logon/on-demand activation; do not launch the task now. */
+    async enable(spec) {
+        const normalized = await this.#installed(spec);
+        await this.#schtasksCommand(["/Change", "/TN", windowsTaskName(normalized), "/ENABLE"]);
+    }
+    /** Prevent future activation; an already running process is deliberately left running. */
+    async disable(spec) {
+        const normalized = await this.#installed(spec);
+        await this.#schtasksCommand(["/Change", "/TN", windowsTaskName(normalized), "/DISABLE"]);
+    }
+    /** Finish with Task Scheduler reporting a running/queued task, then let the CLI verify IPC. */
+    async start(spec) {
+        const normalized = await this.#installed(spec);
+        const status = await this.inspect(spec);
+        if (status.detail) {
+            throw new ServiceError("MANAGER_UNAVAILABLE", status.detail, { backend: this.kind });
+        }
+        if (!status.enabled) {
+            throw new ServiceError("SERVICE_DISABLED", "Windows task is disabled; call enable before start", { backend: this.kind });
+        }
+        if (status.state !== "running") {
+            await this.#schtasksCommand(["/Run", "/TN", windowsTaskName(normalized)]);
+        }
+    }
+    /** Finish with no running task instance; keep the registered task and its logon trigger. */
+    async stop(spec) {
+        const normalized = await this.#installed(spec);
+        await this.#schtasksCommand(["/End", "/TN", windowsTaskName(normalized)], false);
+    }
+    /** Finish with a replacement task process; it continues through screen lock but not user sign-out. */
+    async restart(spec) {
+        const normalized = await this.#installed(spec);
+        const status = await this.inspect(spec);
+        if (status.detail) {
+            throw new ServiceError("MANAGER_UNAVAILABLE", status.detail, { backend: this.kind });
+        }
+        if (!status.enabled) {
+            throw new ServiceError("SERVICE_DISABLED", "Windows task is disabled; call enable before restart", { backend: this.kind });
+        }
+        await this.#schtasksCommand(["/End", "/TN", windowsTaskName(normalized)], false);
+        await this.#schtasksCommand(["/Run", "/TN", windowsTaskName(normalized)]);
+    }
+    #normalize(spec) {
+        if (this.#platform !== "win32")
+            throw new ServiceError("UNSUPPORTED_PLATFORM", "Windows task backend requires Windows");
+        if (!this.#homeDirectory || !this.#windowsUserId) {
+            throw new ServiceError("MANAGER_UNAVAILABLE", "current Windows user or profile is unavailable");
+        }
+        assertSingleLine(this.#windowsUserId, "Windows user id");
+        const normalized = normalizeServiceSpec(spec, "win32");
+        assertWindowsSupported(normalized);
+        return normalized;
+    }
+    async #installed(spec) {
+        const normalized = this.#normalize(spec);
+        if (!(await this.#exists(windowsTaskName(normalized)))) {
+            throw new ServiceError("NOT_INSTALLED", "Windows task is not installed", {
+                backend: this.kind
+            });
+        }
+        return normalized;
+    }
+    #definitionPath(spec) {
+        const fileName = `${spec.id}.xml`;
+        return this.#definitionDirectory.includes("\\")
+            ? win32.join(this.#definitionDirectory, fileName)
+            : join(this.#definitionDirectory, fileName);
+    }
+    #query(taskName) {
+        const script = windowsTaskQueryScript(taskName);
+        return runCommand(this.#runner, this.kind, this.#powershell, powershellArguments(script), {
+            checked: false,
+            env: this.#environment
+        });
+    }
+    async #exists(taskName) {
+        const result = await this.#schtasksCommand(["/Query", "/TN", taskName], false);
+        return result.exitCode === 0;
+    }
+    #schtasksCommand(args, checked = true) {
+        return runCommand(this.#runner, this.kind, this.#schtasks, args, {
+            checked,
+            env: this.#environment
+        });
+    }
+}
+/** Validate and render deterministic Task Scheduler XML for one Windows user. */
+export function renderWindowsTaskXml(spec, userId) {
+    assertSingleLine(userId, "Windows user id");
+    const normalized = normalizeServiceSpec(spec, "win32");
+    assertWindowsSupported(normalized);
+    return renderWindowsTaskXmlNormalized(normalized, windowsTaskName(normalized), userId);
+}
+/**
+ * Quote one argv element with the Windows `CommandLineToArgvW` escaping rules.
+ * The returned string is suitable for Task Scheduler's single Arguments field.
+ */
+export function quoteWindowsArgument(value) {
+    if (value.length > 0 && !/[\s"]/u.test(value))
+        return value;
+    let quoted = '"';
+    let backslashes = 0;
+    for (const character of value) {
+        if (character === "\\") {
+            backslashes += 1;
+            continue;
+        }
+        if (character === '"') {
+            quoted += "\\".repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        quoted += "\\".repeat(backslashes) + character;
+        backslashes = 0;
+    }
+    return `${quoted}${"\\".repeat(backslashes * 2)}"`;
+}
+function renderWindowsTaskXmlNormalized(spec, taskName, userId) {
+    const argumentsText = spec.args.map(quoteWindowsArgument).join(" ");
+    const restart = spec.restart.policy === "on-failure"
+        ? `    <RestartOnFailure>\n      <Interval>PT${Math.max(TASK_RESTART_MINIMUM_SECONDS, spec.restart.delaySeconds)}S</Interval>\n      <Count>${spec.restart.maxBurst}</Count>\n    </RestartOnFailure>\n`
+        : "";
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>${escapeXml(spec.description)}</Description>
+    <URI>${escapeXml(taskName)}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${escapeXml(userId)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${escapeXml(userId)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>${spec.enabled}</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+${restart}  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${escapeXml(spec.command)}</Command>
+${argumentsText ? `      <Arguments>${escapeXml(argumentsText)}</Arguments>\n` : ""}      <WorkingDirectory>${escapeXml(spec.workingDirectory)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+function windowsTaskName(spec) {
+    const name = spec.names.windowsTaskName ?? `\\OctoRuntime.${spec.id}`;
+    const segment = name.startsWith("\\") ? name.slice(1) : "";
+    if (!WINDOWS_TASK_SEGMENT.test(segment)) {
+        throw new ServiceError("INVALID_SPEC", "Windows task name must be a single root task such as \\OctoRuntime.daemon");
+    }
+    return name;
+}
+function assertWindowsSupported(spec) {
+    if (Object.keys(spec.environment).length > 0) {
+        throw new ServiceError("UNSUPPORTED_SPEC", "Windows user tasks do not support service environment variables", {
+            backend: "windows-user-task"
+        });
+    }
+    if (spec.stdoutPath || spec.stderrPath) {
+        throw new ServiceError("UNSUPPORTED_SPEC", "Windows user tasks do not support native stdout/stderr redirection", {
+            backend: "windows-user-task"
+        });
+    }
+    if (spec.restart.policy === "always") {
+        throw new ServiceError("UNSUPPORTED_SPEC", "Windows Task Scheduler cannot represent restart policy 'always'", {
+            backend: "windows-user-task"
+        });
+    }
+}
+function windowsTaskQueryScript(taskName) {
+    const task = taskName.slice(1);
+    const quotedTask = powershellSingleQuote(task);
+    return `$ErrorActionPreference='Stop';$task=Get-ScheduledTask -TaskPath '\\' -TaskName '${quotedTask}';$info=Get-ScheduledTaskInfo -InputObject $task;$action=@($task.Actions)[0];$trigger=@($task.Triggers)[0];[ordered]@{state=[string]$task.State;enabled=([string]$task.State -ne 'Disabled');last_exit_code=[long]$info.LastTaskResult;execute=[string]$action.Execute;arguments=[string]$action.Arguments;working_directory=[string]$action.WorkingDirectory;principal_user_id=[string]$task.Principal.UserId;principal_logon_type=[string]$task.Principal.LogonType;trigger_user_id=[string]$trigger.UserId}|ConvertTo-Json -Compress`;
+}
+function powershellArguments(script) {
+    return ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script];
+}
+function powershellSingleQuote(value) {
+    return value.replaceAll("'", "''");
+}
+function windowsManagerDrift(task, spec, userId) {
+    const expectedArguments = spec.args.map(quoteWindowsArgument).join(" ");
+    const drift = [];
+    if (!equalWindowsPath(task.execute, spec.command))
+        drift.push("manager.command");
+    if ((task.arguments ?? "") !== expectedArguments)
+        drift.push("manager.arguments");
+    if (!equalWindowsPath(task.working_directory, spec.workingDirectory))
+        drift.push("manager.working_directory");
+    if (!equalWindowsIdentity(task.principal_user_id, userId))
+        drift.push("manager.principal_user");
+    if (!["interactivetoken", "interactive", "3"].includes(task.principal_logon_type?.toLowerCase() ?? "")) {
+        drift.push("manager.logon_type");
+    }
+    if (!equalWindowsIdentity(task.trigger_user_id, userId))
+        drift.push("manager.trigger_user");
+    if (task.enabled !== spec.enabled)
+        drift.push("manager.enabled");
+    return drift;
+}
+function equalWindowsPath(actual, expected) {
+    return (actual?.replaceAll("/", "\\").toLowerCase() === expected.replaceAll("/", "\\").toLowerCase());
+}
+function equalWindowsIdentity(actual, expected) {
+    return actual?.toLowerCase() === expected.toLowerCase();
+}
+function windowsTaskState(value) {
+    switch (value?.toLowerCase()) {
+        case "running":
+            return "running";
+        case "queued":
+            return "starting";
+        case "ready":
+        case "disabled":
+            return "stopped";
+        default:
+            return "unknown";
+    }
+}
+function windowsUserId(environment) {
+    const username = environment.USERNAME?.trim() ?? "";
+    const domain = environment.USERDOMAIN?.trim() ?? "";
+    return domain && username ? `${domain}\\${username}` : username;
+}
+function assertSingleLine(value, field) {
+    if (!value.trim() || value.includes("\0") || /[\r\n]/u.test(value)) {
+        throw new ServiceError("INVALID_SPEC", `${field} must be non-empty and single-line`);
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@mininglamp-oss/octo-runtime-cross-service",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Native user-service lifecycle backends for Octo Runtime",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "dependencies": {}
+}

package/node_modules/@mininglamp-oss/octo-runtime-daemon/dist/context-loader.d.ts

@@ -0,0 +1,30 @@
+import { type ContextItem } from "@mininglamp-oss/octo-runtime-protocol";
+import type { JsonObject, JsonValue } from "./extras.js";
+/**
+ * 宿主业务函数：每轮接收独立 Bot 配置快照，返回 ContextItem 列表而非 envelope。
+ * 函数引用在初始化时固定，但每次调用可读取宿主最新的 Agent 提示词，无需重载 Extra。
+ * 存储、授权及读取一致性归宿主；同步读取和异步 IO 均支持，IO 须传递 signal。
+ * SQLite 同步驱动可直接返回数组，异步驱动可返回 Promise；async 不会使同步查询自动非阻塞。
+ * .octospec/tasks/sdk-host-extra-contexts/brief.md；SDK 在主进程绑定函数，不把它写入 JSON/IPC。
+ */
+export type LoadContexts = (config: JsonObject, options: {
+    readonly signal: AbortSignal;
+}) => readonly ContextItem[] | Promise<readonly ContextItem[]>;
+export interface ChannelDependencies {
+    readonly loadContexts?: LoadContexts;
+}
+/**
+ * 只合并本轮数据，不保留历史。动态同 key 整项替换且保留静态位置，新项按返回顺序追加。
+ * instructions.entries 也不拼接：覆盖方须显式保留需要的固定人设；空动态列表不删除静态项。
+ * 两个来源先分别校验，避免同源重复 key 被覆盖掩盖；返回副本隔离宿主与插件的后续修改。
+ */
+export declare function mergeConfiguredContexts(base: readonly ContextItem[], dynamic: readonly ContextItem[]): ContextItem[];
+/**
+ * 每个 Extra 共用一个有界回调池，而非每个 Bot 各建一份额度。
+ * 超时只结束本轮等待，不能强制结束外部 Promise；实际操作结束前仍须占额，防止挂起 IO 累积。
+ */
+export declare function createContextLoader(callback: LoadContexts | undefined, settings: JsonValue | undefined, owner: AbortSignal): {
+    load(config: JsonObject, signal: AbortSignal): Promise<ContextItem[]>;
+    close(): Promise<void>;
+    readonly inFlight: number;
+};

package/node_modules/@mininglamp-oss/octo-runtime-daemon/dist/context-loader.js

@@ -0,0 +1,158 @@
+import { CONTEXT_SCHEMA, assertContextEnvelope } from "@mininglamp-oss/octo-runtime-protocol";
+/**
+ * 只合并本轮数据，不保留历史。动态同 key 整项替换且保留静态位置，新项按返回顺序追加。
+ * instructions.entries 也不拼接：覆盖方须显式保留需要的固定人设；空动态列表不删除静态项。
+ * 两个来源先分别校验，避免同源重复 key 被覆盖掩盖；返回副本隔离宿主与插件的后续修改。
+ */
+export function mergeConfiguredContexts(base, dynamic) {
+    assertContextEnvelope({ schema: CONTEXT_SCHEMA, items: base });
+    assertContextEnvelope({ schema: CONTEXT_SCHEMA, items: dynamic });
+    const items = [...base];
+    const positions = new Map(items.map((item, index) => [`${item.namespace}/${item.name}`, index]));
+    for (const item of dynamic) {
+        const key = `${item.namespace}/${item.name}`;
+        const position = positions.get(key);
+        if (position === undefined) {
+            positions.set(key, items.length);
+            items.push(item);
+        }
+        else
+            items[position] = item;
+    }
+    const envelope = { schema: CONTEXT_SCHEMA, items };
+    assertContextEnvelope(envelope);
+    return structuredClone(items);
+}
+/**
+ * 每个 Extra 共用一个有界回调池，而非每个 Bot 各建一份额度。
+ * 超时只结束本轮等待，不能强制结束外部 Promise；实际操作结束前仍须占额，防止挂起 IO 累积。
+ */
+export function createContextLoader(callback, settings, owner) {
+    const options = settings ?? {};
+    if (!options ||
+        typeof options !== "object" ||
+        Array.isArray(options) ||
+        Object.keys(options).some((key) => !["timeout_ms", "max_in_flight"].includes(key)))
+        throw new Error("IM_CONTEXT_LOADING_CONFIG_INVALID");
+    const timeout = options.timeout_ms ?? 5_000;
+    const capacity = options.max_in_flight ?? 8;
+    if (typeof timeout !== "number" ||
+        !Number.isInteger(timeout) ||
+        timeout < 1 ||
+        timeout > 30_000 ||
+        typeof capacity !== "number" ||
+        !Number.isInteger(capacity) ||
+        capacity < 1 ||
+        capacity > 32)
+        throw new Error("IM_CONTEXT_LOADING_CONFIG_INVALID");
+    const pending = new Set();
+    const stop = new AbortController();
+    return {
+        async load(config, signal) {
+            const base = config.context?.items ?? [];
+            if (!Array.isArray(base))
+                throw new Error("IM_CONTEXT_INVALID");
+            if (!callback)
+                return mergeConfiguredContexts(base, []);
+            owner.throwIfAborted();
+            stop.signal.throwIfAborted();
+            signal.throwIfAborted();
+            // 满额直接拒绝，不再建立等待队列；否则排队的配置副本和闭包也可能无限增长。
+            if (pending.size >= capacity)
+                throw new Error("IM_CONTEXT_LOADING_BUSY");
+            const abort = new AbortController();
+            const combined = AbortSignal.any([owner, stop.signal, signal, abort.signal]);
+            let timer;
+            let onAbort;
+            const operation = Promise.resolve()
+                .then(() => {
+                combined.throwIfAborted();
+                // 每轮重新调用同一业务函数，不在启动时预取；下一轮可读到宿主已更新的数据。
+                return callback(structuredClone(config), { signal: combined });
+            })
+                .then((items) => {
+                // 超时或取消后的迟到结果不能再校验、复制或进入本轮模型输入。
+                combined.throwIfAborted();
+                assertBoundedJson(items);
+                return mergeConfiguredContexts(base, items);
+            });
+            pending.add(operation);
+            // 跟踪真实操作，而非 race 的等待结果；迟到 reject 也必须被消费，避免未处理拒绝。
+            void operation.finally(() => pending.delete(operation)).catch(() => undefined);
+            try {
+                return await Promise.race([
+                    operation,
+                    new Promise((_, reject) => {
+                        onAbort = () => reject(new Error("IM_CONTEXT_LOADING_CANCELLED"));
+                        combined.addEventListener("abort", onAbort, { once: true });
+                        if (combined.aborted)
+                            onAbort();
+                        timer = setTimeout(() => {
+                            reject(new Error("IM_CONTEXT_LOADING_TIMEOUT"));
+                            abort.abort();
+                        }, timeout);
+                    })
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+                if (onAbort)
+                    combined.removeEventListener("abort", onAbort);
+            }
+        },
+        async close() {
+            // 这里等待实际 IO 退出；外层 Extra loader 负责 5 秒宽限，超时后保留失败实例阻止重载。
+            stop.abort();
+            await Promise.allSettled([...pending]);
+        },
+        get inFlight() {
+            return pending.size;
+        }
+    };
+}
+// 先限制外部结果的深度和遍历成本，再进入协议校验、序列化和复制，避免校验本身放大内存。
+// 这不是 JS 沙箱：无法限制业务函数执行期间自行分配的内存或阻塞事件循环。
+function assertBoundedJson(value) {
+    if (!Array.isArray(value) || value.length > 32)
+        throw new Error("IM_CONTEXT_RESULT_INVALID");
+    // 预检预算覆盖节点、键和字符；最终字节数及 item 约束仍由 Context v3 校验器决定。
+    let budget = 262_144;
+    const ancestors = new Set();
+    const visit = (item, depth) => {
+        if (depth > 32 || --budget < 0)
+            throw new Error("IM_CONTEXT_RESULT_TOO_LARGE");
+        if (item === null || typeof item === "boolean")
+            return;
+        if (typeof item === "string") {
+            budget -= item.length * 3;
+            if (budget < 0)
+                throw new Error("IM_CONTEXT_RESULT_TOO_LARGE");
+            return;
+        }
+        if (typeof item === "number" && Number.isFinite(item))
+            return;
+        if (!item ||
+            typeof item !== "object" ||
+            ancestors.has(item) ||
+            (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype))
+            throw new Error("IM_CONTEXT_RESULT_INVALID");
+        if (Array.isArray(item) && item.length > budget)
+            throw new Error("IM_CONTEXT_RESULT_TOO_LARGE");
+        // 不执行业务 getter/toJSON；否则一次普通校验也可能触发副作用或生成更大的对象。
+        const toJson = Object.getOwnPropertyDescriptor(item, "toJSON");
+        if (toJson && (!Object.hasOwn(toJson, "value") || typeof toJson.value === "function"))
+            throw new Error("IM_CONTEXT_RESULT_INVALID");
+        ancestors.add(item);
+        for (const key in item) {
+            if (!Object.hasOwn(item, key))
+                continue;
+            budget -= key.length * 3;
+            const descriptor = Object.getOwnPropertyDescriptor(item, key);
+            if (!Object.hasOwn(descriptor, "value"))
+                throw new Error("IM_CONTEXT_RESULT_INVALID");
+            visit(descriptor.value, depth + 1);
+        }
+        ancestors.delete(item);
+    };
+    visit(value, 0);
+}

package/node_modules/@mininglamp-oss/octo-runtime-daemon/dist/extra-config.d.ts

@@ -0,0 +1,13 @@
+import { type ExtraRegistration, type JsonObject } from "./extras.js";
+/** Host-owned, serializable declaration; config remains plugin-specific JSON. */
+export interface ExtraDescriptor {
+    name: string;
+    module: string;
+    enabled?: boolean;
+    config: JsonObject;
+}
+export type StoredExtra = Omit<ExtraDescriptor, "name">;
+export declare function assertStoredExtra(value: unknown): asserts value is StoredExtra;
+export declare function extraRegistration(descriptor: ExtraDescriptor): ExtraRegistration;
+/** Called only by a host that explicitly selects this directory as its source. */
+export declare function readExtraDirectory(directory: string): Promise<ExtraRegistration[]>;