@mininglamp-oss/octo-runtime 1.0.1 → 1.1.1

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/common.d.ts

@@ -12,6 +12,8 @@ export declare function runCommand(runner: CommandRunner, backend: ServiceBacken
     env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
 }): Promise<CommandResult>;
+/** 平台仅在确认原生 not-found 后忽略失败，其他结果沿同一受控错误合同传播。 */
+export declare function assertCommandSucceeded(result: CommandResult, backend: ServiceBackendKind): void;
 /** Read a UTF-8 service definition; absence is represented as `undefined`. */
 export declare function readDefinition(path: string): Promise<string | undefined>;
 /**

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

@@ -92,15 +92,20 @@ export async function runCommand(runner, backend, command, args, options = {}) {
             detail: cause instanceof Error ? cause.message : String(cause)
         });
     }
-    if ((options.checked ?? true) && result.exitCode !== 0) {
+    if (options.checked ?? true)
+        assertCommandSucceeded(result, backend);
+    return result;
+}
+/** 平台仅在确认原生 not-found 后忽略失败，其他结果沿同一受控错误合同传播。 */
+export function assertCommandSucceeded(result, backend) {
+    if (result.exitCode !== 0) {
         throw new ServiceError("COMMAND_FAILED", `${backend} command failed`, {
             backend,
-            command,
+            command: result.command,
             exitCode: result.exitCode,
             detail: boundedDetail(result.stderr || result.stdout)
         });
     }
-    return result;
 }
 /** Read a UTF-8 service definition; absence is represented as `undefined`. */
 export async function readDefinition(path) {

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

@@ -1,6 +1,7 @@
 /** macOS current-user service backend implemented with a LaunchAgent. */
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { definitionDrift, escapeXml, normalizeServiceSpec, readDefinition, removeDefinition, runCommand, writeDefinition } from "./common.js";
 import { ServiceError } from "./errors.js";
 import { NodeCommandRunner } from "./runner.js";
@@ -106,7 +107,7 @@ export class LaunchdUserBackend {
         if (changed && wasLoaded) {
             // launchd does not reload changed plist bytes in place. Replace a loaded
             // job, but keep it unloaded when the desired definition is disabled.
-            await this.#bootout(label);
+            await this.#bootout(label, normalized.timeoutStopSeconds);
             if (normalized.enabled)
                 await this.#bootstrap(definitionPath);
         }
@@ -115,7 +116,7 @@ export class LaunchdUserBackend {
     async uninstall(spec) {
         const normalized = this.#normalize(spec);
         const label = launchdLabel(normalized);
-        await this.#bootout(label);
+        await this.#bootout(label, normalized.timeoutStopSeconds);
         await removeDefinition(this.#definitionPath(label));
     }
     /** Clear launchd's disabled override; this affects future activation but does not bootstrap now. */
@@ -149,7 +150,7 @@ export class LaunchdUserBackend {
     /** Finish with the job absent from the user's launchd domain; the plist remains installed. */
     async stop(spec) {
         const normalized = await this.#installed(spec);
-        await this.#bootout(launchdLabel(normalized));
+        await this.#bootout(launchdLabel(normalized), normalized.timeoutStopSeconds);
     }
     /** Finish with a newly kicked/bootstrapped process, while leaving identity and data files unchanged. */
     async restart(spec) {
@@ -203,8 +204,8 @@ export class LaunchdUserBackend {
         });
         if (result.exitCode !== 0)
             return false;
-        const match = result.stdout.match(new RegExp(`["']?${escapeRegExp(label)}["']?\\s*=>\\s*(true|false)`));
-        return match?.[1] === "true";
+        const match = result.stdout.match(new RegExp(`["']?${escapeRegExp(label)}["']?\\s*=>\\s*(true|false|enabled|disabled)`));
+        return match?.[1] === "true" || match?.[1] === "disabled";
     }
     #setEnabled(label, enabled) {
         return runCommand(this.#runner, this.kind, this.#launchctl, [enabled ? "enable" : "disable", this.#target(label)], {
@@ -216,12 +217,24 @@ export class LaunchdUserBackend {
             env: this.#environment
         });
     }
-    async #bootout(label) {
+    async #bootout(label, timeoutSeconds) {
         if ((await this.#print(label)).exitCode !== 0)
             return;
         await runCommand(this.#runner, this.kind, this.#launchctl, ["bootout", this.#target(label)], {
             env: this.#environment
         });
+        // bootout 默认异步返回；确认旧 job 消失后才能 stop 完成或 bootstrap。
+        // 有界轮询避免 --wait 无界阻塞及旧版 launchctl 的兼容问题。
+        const until = Date.now() + (timeoutSeconds + 5) * 1000;
+        while ((await this.#print(label)).exitCode === 0) {
+            if (Date.now() >= until)
+                throw new ServiceError("COMMAND_FAILED", "launchd service did not finish unloading", {
+                    backend: this.kind,
+                    command: this.#launchctl,
+                    exitCode: 124
+                });
+            await sleep(50);
+        }
     }
 }
 /** Validate and render the deterministic LaunchAgent plist for a portable spec. */

package/node_modules/@mininglamp-oss/octo-runtime-cross-service/dist/systemd.d.ts

@@ -20,7 +20,7 @@ export declare class SystemdUserBackend implements ServiceBackend {
      * A stopped unit stays stopped; a running unit restarts only when its definition changed.
      */
     install(spec: ServiceSpec): Promise<void>;
-    /** Finish with the unit stopped, disabled, removed, and forgotten by the user manager. */
+    /** 确认用户 unit 已停止再禁用、移除定义；真实管理器失败传播给调用方，保留未删定义。 */
     uninstall(spec: ServiceSpec): Promise<void>;
     /** Add the default-target link for future user-manager activation; do not start now. */
     enable(spec: ServiceSpec): Promise<void>;
@@ -28,7 +28,7 @@ export declare class SystemdUserBackend implements ServiceBackend {
     disable(spec: ServiceSpec): Promise<void>;
     /** Finish with systemd reporting the unit active/starting, then let the CLI verify daemon readiness. */
     start(spec: ServiceSpec): Promise<void>;
-    /** Finish with no active process for the installed unit; keep the unit file and enablement. */
+    /** 请求停止并有界确认 inactive/failed 且无主进程，保留定义与自启设置。 */
     stop(spec: ServiceSpec): Promise<void>;
     /** Finish with systemd having launched a replacement process; persistent Runtime data is unchanged. */
     restart(spec: ServiceSpec): Promise<void>;

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

@@ -1,7 +1,8 @@
 /** Linux current-user service backend implemented with `systemctl --user`. */
 import { mkdir } from "node:fs/promises";
 import { dirname, join, posix } from "node:path";
-import { definitionDrift, normalizeServiceSpec, parseProperties, readDefinition, removeDefinition, runCommand, writeDefinition } from "./common.js";
+import { setTimeout as sleep } from "node:timers/promises";
+import { assertCommandSucceeded, definitionDrift, normalizeServiceSpec, parseProperties, readDefinition, removeDefinition, runCommand, writeDefinition } from "./common.js";
 import { ServiceError } from "./errors.js";
 import { NodeCommandRunner } from "./runner.js";
 const UNIT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@-]{0,127}\.service$/;
@@ -114,15 +115,16 @@ export class SystemdUserBackend {
         if (changed && previous.state === "running" && normalized.enabled)
             await this.#command(["restart", unit]);
     }
-    /** Finish with the unit stopped, disabled, removed, and forgotten by the user manager. */
+    /** 确认用户 unit 已停止再禁用、移除定义；真实管理器失败传播给调用方，保留未删定义。 */
     async uninstall(spec) {
         const normalized = this.#normalize(spec);
         const unit = systemdUnit(normalized);
-        await this.#command(["stop", unit], false);
-        await this.#command(["disable", unit], false);
+        await this.#commandOrMissing(["stop", unit], unit);
+        await this.#waitInactive(unit, normalized.timeoutStopSeconds);
+        await this.#commandOrMissing(["disable", unit], unit);
         await removeDefinition(this.#definitionPath(unit));
         await this.#command(["daemon-reload"]);
-        await this.#command(["reset-failed", unit], false);
+        await this.#commandOrMissing(["reset-failed", unit], unit);
     }
     /** Add the default-target link for future user-manager activation; do not start now. */
     async enable(spec) {
@@ -144,10 +146,12 @@ export class SystemdUserBackend {
         if (status.state !== "running")
             await this.#command(["start", systemdUnit(normalized)]);
     }
-    /** Finish with no active process for the installed unit; keep the unit file and enablement. */
+    /** 请求停止并有界确认 inactive/failed 且无主进程，保留定义与自启设置。 */
     async stop(spec) {
-        const unit = systemdUnit(await this.#installed(spec));
-        await this.#command(["stop", unit]);
+        const normalized = await this.#installed(spec);
+        const unit = systemdUnit(normalized);
+        await this.#commandOrMissing(["stop", unit], unit);
+        await this.#waitInactive(unit, normalized.timeoutStopSeconds);
     }
     /** Finish with systemd having launched a replacement process; persistent Runtime data is unchanged. */
     async restart(spec) {
@@ -198,6 +202,41 @@ export class SystemdUserBackend {
             env: this.#environment
         });
     }
+    /** not-found 不等同于 inactive；删除定义前必须同时确认进程已停止。 */
+    async #commandOrMissing(args, unit) {
+        const result = await this.#command(args, false);
+        if (result.exitCode === 0)
+            return;
+        const shown = await this.#show(unit);
+        const properties = parseProperties(shown.stdout);
+        if (properties.LoadState === "not-found" &&
+            properties.ActiveState === "inactive" &&
+            properties.MainPID === "0")
+            return;
+        assertCommandSucceeded(result, this.kind);
+    }
+    async #waitInactive(unit, seconds) {
+        const end = Date.now() + seconds * 1000;
+        while (true) {
+            const shown = await this.#show(unit);
+            const properties = parseProperties(shown.stdout);
+            if (properties.LoadState !== "not-found")
+                assertCommandSucceeded(shown, this.kind);
+            if (["inactive", "failed"].includes(properties.ActiveState ?? "") &&
+                properties.MainPID === "0")
+                return;
+            assertCommandSucceeded(shown, this.kind);
+            if (!properties.ActiveState || properties.MainPID === undefined)
+                throw new ServiceError("MANAGER_UNAVAILABLE", "systemd did not report process state", {
+                    backend: this.kind
+                });
+            if (Date.now() >= end)
+                throw new ServiceError("COMMAND_FAILED", "systemd stop did not complete", {
+                    backend: this.kind
+                });
+            await sleep(100);
+        }
+    }
 }
 /** Validate and render the deterministic systemd user unit for a portable spec. */
 export function renderSystemdUnit(spec) {

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

@@ -22,7 +22,7 @@ export declare class WindowsUserTaskBackend implements ServiceBackend {
      * when the reconciled task remains enabled.
      */
     install(spec: ServiceSpec): Promise<void>;
-    /** Finish with no scheduled task or XML sidecar; Runtime credentials and data remain. */
+    /** 确认任务停止并删除后才移除 XML；权限/管理器故障不作为不存在，用户数据保留。 */
     uninstall(spec: ServiceSpec): Promise<void>;
     /** Enable future logon/on-demand activation; do not launch the task now. */
     enable(spec: ServiceSpec): Promise<void>;
@@ -30,9 +30,9 @@ export declare class WindowsUserTaskBackend implements ServiceBackend {
     disable(spec: ServiceSpec): Promise<void>;
     /** Finish with Task Scheduler reporting a running/queued task, then let the CLI verify IPC. */
     start(spec: ServiceSpec): Promise<void>;
-    /** Finish with no running task instance; keep the registered task and its logon trigger. */
+    /** 有界确认旧任务不再运行，保留注册和登录触发器；/End 请求受理不代表停止完成。 */
     stop(spec: ServiceSpec): Promise<void>;
-    /** Finish with a replacement task process; it continues through screen lock but not user sign-out. */
+    /** 确认旧实例停止后再启动替换实例；IPC 就绪仍由宿主查询，注销后不承诺继续运行。 */
     restart(spec: ServiceSpec): Promise<void>;
 }
 /** Validate and render deterministic Task Scheduler XML for one Windows user. */

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

@@ -1,6 +1,7 @@
 /** 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 { setTimeout as sleep } from "node:timers/promises";
+import { assertCommandSucceeded, 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}$/;
@@ -143,10 +144,9 @@ export class WindowsUserTaskBackend {
         // 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);
+        if (previous.state === "running" || previous.state === "starting")
+            await this.stop(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.
@@ -154,12 +154,20 @@ export class WindowsUserTaskBackend {
             await this.#schtasksCommand(["/Run", "/TN", taskName]);
         }
     }
-    /** Finish with no scheduled task or XML sidecar; Runtime credentials and data remain. */
+    /** 确认任务停止并删除后才移除 XML；权限/管理器故障不作为不存在，用户数据保留。 */
     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);
+        if (await this.#exists(taskName)) {
+            await this.stop(spec);
+            const result = await this.#schtasksCommand(["/Delete", "/TN", taskName, "/F"], false);
+            if (await this.#exists(taskName)) {
+                assertCommandSucceeded(result, this.kind);
+                throw new ServiceError("COMMAND_FAILED", "Windows task deletion did not complete", {
+                    backend: this.kind
+                });
+            }
+        }
         await removeDefinition(this.#definitionPath(normalized));
     }
     /** Enable future logon/on-demand activation; do not launch the task now. */
@@ -186,12 +194,38 @@ export class WindowsUserTaskBackend {
             await this.#schtasksCommand(["/Run", "/TN", windowsTaskName(normalized)]);
         }
     }
-    /** Finish with no running task instance; keep the registered task and its logon trigger. */
+    /** 有界确认旧任务不再运行，保留注册和登录触发器；/End 请求受理不代表停止完成。 */
     async stop(spec) {
         const normalized = await this.#installed(spec);
-        await this.#schtasksCommand(["/End", "/TN", windowsTaskName(normalized)], false);
+        const taskName = windowsTaskName(normalized);
+        const status = await this.inspect(spec);
+        if (status.state === "stopped" || status.state === "not_installed")
+            return;
+        if (status.state === "unknown")
+            throw new ServiceError("MANAGER_UNAVAILABLE", "Windows task state is unavailable", {
+                backend: this.kind
+            });
+        const result = await this.#schtasksCommand(["/End", "/TN", taskName], false);
+        if (result.exitCode !== 0 && (await this.#exists(taskName)))
+            assertCommandSucceeded(result, this.kind);
+        // /End 仅表示请求受理；旧实例仍运行时不能 /Run（IgnoreNew 会吞掉重启）。
+        const end = Date.now() + normalized.timeoutStopSeconds * 1000;
+        while (true) {
+            const current = await this.inspect(spec);
+            if (current.state === "stopped" || current.state === "not_installed")
+                return;
+            if (current.state === "unknown")
+                throw new ServiceError("MANAGER_UNAVAILABLE", "Windows task state is unavailable", {
+                    backend: this.kind
+                });
+            if (Date.now() >= end)
+                throw new ServiceError("COMMAND_FAILED", "Windows task stop did not complete", {
+                    backend: this.kind
+                });
+            await sleep(100);
+        }
     }
-    /** Finish with a replacement task process; it continues through screen lock but not user sign-out. */
+    /** 确认旧实例停止后再启动替换实例；IPC 就绪仍由宿主查询，注销后不承诺继续运行。 */
     async restart(spec) {
         const normalized = await this.#installed(spec);
         const status = await this.inspect(spec);
@@ -201,7 +235,7 @@ export class WindowsUserTaskBackend {
         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.stop(spec);
         await this.#schtasksCommand(["/Run", "/TN", windowsTaskName(normalized)]);
     }
     #normalize(spec) {
@@ -239,7 +273,24 @@ export class WindowsUserTaskBackend {
     }
     async #exists(taskName) {
         const result = await this.#schtasksCommand(["/Query", "/TN", taskName], false);
-        return result.exitCode === 0;
+        if (result.exitCode === 0)
+            return true;
+        // schtasks 非零也可能是权限/manager 故障；只按原生 ERROR_FILE_NOT_FOUND (0x80070002) 确认缺失。
+        const confirmed = await runCommand(this.#runner, this.kind, this.#powershell, powershellArguments(`$ErrorActionPreference='Stop';$scheduler=New-Object -ComObject Schedule.Service;$scheduler.Connect();$folder=$scheduler.GetFolder('\\');try{$null=$folder.GetTask('${powershellSingleQuote(taskName.slice(1))}');'{"exists":true}'}catch{$errorObject=$_.Exception;while($errorObject.InnerException){$errorObject=$errorObject.InnerException};if($errorObject.HResult -eq -2147024894){'{"exists":false}'}else{throw}}`), { env: this.#environment });
+        let exists;
+        try {
+            const value = JSON.parse(confirmed.stdout);
+            if (value !== null && typeof value === "object" && "exists" in value)
+                exists = value.exists;
+        }
+        catch {
+            /* 下方统一拒绝不完整结果。 */
+        }
+        if (typeof exists !== "boolean")
+            throw new ServiceError("MANAGER_UNAVAILABLE", "Windows task existence query was invalid", {
+                backend: this.kind
+            });
+        return exists;
     }
     #schtasksCommand(args, checked = true) {
         return runCommand(this.#runner, this.kind, this.#schtasks, args, {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mininglamp-oss/octo-runtime-cross-service",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "private": true,
   "description": "Native user-service lifecycle backends for Octo Runtime",
   "type": "module",
@@ -11,7 +11,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=24 <25"
+    "node": "^24.0.0 || ^26.0.0"
   },
   "dependencies": {}
 }

package/node_modules/@mininglamp-oss/{octo-runtime-core → octo-runtime-executor-core}/dist/context.d.ts

@@ -1,7 +1,12 @@
 import { type ContextEnvelope, type ResolvedExecutionPlan, type RuntimeLimits } from "@mininglamp-oss/octo-runtime-protocol";
 export declare function assertLocalContext(context: unknown): asserts context is ContextEnvelope;
+/**
+ * 合并执行默认值与本轮提交，校验后生成 Provider 无关的执行计划；不扫描宿主文件或准备目录。
+ * defaults 仅允许执行/安全配置，业务历史由调用方单独传入，不能变为所有调用的隐式默认。
+ */
 export declare function resolveLocalContext(defaults: ContextEnvelope, submitted: ContextEnvelope, agentSource: "preset" | "provisioned"): {
     effectiveContext: ContextEnvelope;
     resolvedExecutionPlan: ResolvedExecutionPlan;
 };
+/** 将 Context 的 wire 字段映射为 Core 限制；未知键拒绝，避免配置看似生效却被静默忽略。 */
 export declare function localRuntimeLimits(plan: ResolvedExecutionPlan): RuntimeLimits | undefined;

package/node_modules/@mininglamp-oss/{octo-runtime-core → octo-runtime-executor-core}/dist/context.js

@@ -23,6 +23,10 @@ export function assertLocalContext(context) {
         throw new TypeError(`LOCAL_CONTEXT_TYPE_UNSUPPORTED: ${item.namespace}/${item.name}`);
     }
 }
+/**
+ * 合并执行默认值与本轮提交，校验后生成 Provider 无关的执行计划；不扫描宿主文件或准备目录。
+ * defaults 仅允许执行/安全配置，业务历史由调用方单独传入，不能变为所有调用的隐式默认。
+ */
 export function resolveLocalContext(defaults, submitted, agentSource) {
     assertAgentSource(agentSource);
     assertLocalContext(defaults);
@@ -70,6 +74,7 @@ export function resolveLocalContext(defaults, submitted, agentSource) {
     localRuntimeLimits(plan);
     return { effectiveContext, resolvedExecutionPlan: plan };
 }
+/** 将 Context 的 wire 字段映射为 Core 限制；未知键拒绝，避免配置看似生效却被静默忽略。 */
 export function localRuntimeLimits(plan) {
     if (!plan.runtime_limits)
         return undefined;

package/node_modules/@mininglamp-oss/{octo-runtime-adapter-host → octo-runtime-executor-core}/dist/index.d.ts

@@ -1,10 +1,10 @@
-export { HostRunService } from "./host-run-service.js";
-export { readAdapterConfigurations } from "./runtime-configuration.js";
-export { startHostSocketServer, streamHostRun, type HostSocketRequest } from "./socket-server.js";
+export { prepareInvokeInput } from "./invoke-input.js";
+export { resolveLocalContext, localRuntimeLimits } from "./context.js";
 export { prepareRunContext, type PreparedRunContext, type WorkspaceAssignments } from "./execution-preparation.js";
 import type { AdapterInvocationContext, AdapterProbeOptions, AdapterOutput } from "@mininglamp-oss/octo-runtime-adapter-sdk";
 import { type InvokeInput, type InvokeEnvironment, type AdapterProtocolSupport, type HostFrame, type NativeInteractionResponse, type InteractionResponse, type InvokeRequest } from "@mininglamp-oss/octo-runtime-protocol";
 import { type RuntimeLog } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+export type { AdapterInvocationContext, AdapterOutput, AdapterProbeOptions, RuntimeLog } from "@mininglamp-oss/octo-runtime-adapter-sdk";
 /** Provider-neutral metadata the Host uses for registration and capability discovery. */
 export interface HostedAdapterMetadata {
     /** False skips Runtime workspace preparation for this Provider. */
@@ -33,16 +33,27 @@ export interface HostedAdapter {
     respondInteraction?(invocationId: string, response: InteractionResponse): Promise<void>;
     respondNative?(invocationId: string, response: NativeInteractionResponse): Promise<void>;
 }
+/** closed 表示不再接纳；只有 cleanup=complete 才确认当前登记的 Adapter 清理均已完成。 */
+export interface ExecutorShutdownResult {
+    state: "closed";
+    cleanup: "complete" | "incomplete";
+    unresolvedInvocationIds: readonly string[];
+    failedCleanupInvocationIds: readonly string[];
+}
 /**
- * The in-process registry and lifecycle gatekeeper for adapters.
- * It validates plugin input/output, fills in the message lifecycle, guarantees
- * a single terminal, and turns cancellation into an AbortSignal.
+ * 唯一的进程内执行实现：校验输入/Adapter 输出、补齐消息生命周期、约束单个终态并传递取消。
+ * Kernel worker 和显式进程内接入共用本类；它不拥有独立 Kernel、业务会话或 IM 投递。
+ * 接入方须消费流并在退出时检查 shutdown 的 cleanup 结果；终态不能替代资源回收确认。
  */
-export declare class AdapterHost {
+export declare class AgentExecutor {
     #private;
     constructor(options?: {
         log?: RuntimeLog;
     });
+    /**
+     * 常规接入入口：默认返回 native HostFrame，显式 canonical 返回 CanonicalEvent。
+     * 与 Kernel 的观察 iterator 不同，本地 Core 提前结束迭代会请求取消并进入 Adapter 清理。
+     */
     readonly invoke: import("@mininglamp-oss/octo-runtime-protocol").InputInvoke;
     /** Register an adapter by `metadata.type`; the same type cannot be overwritten twice. */
     register(adapter: HostedAdapter): void;
@@ -50,21 +61,22 @@ export declare class AdapterHost {
     list(): HostedAdapterMetadata[];
     /** Report installed provider identity separately from adapter registration. */
     describe(configurations?: Record<string, AdapterProbeOptions>): Promise<HostedAdapterMetadata[]>;
-    /** Public invocations default to native; canonical consumers explicitly select their view. */
+    /**
+     * 同步校验并冻结单次输入，开始迭代时接纳执行；native 为默认，canonical 须显式选择。
+     * signal、执行环境和容量限制来自本次 environment，不从业务会话或其他 Run 继承。
+     */
     invokeFrames(input: InvokeInput, environment?: InvokeEnvironment): AsyncGenerator<HostFrame>;
     /** Run the adapter's own environment probe; return an unchecked-available status when there is no probe. */
     probe(adapterType: string, options?: AdapterProbeOptions): unknown;
-    /** Abort an active invocation; returns false when that invocation no longer exists or has already ended. */
+    /** 请求取消活动执行；true 仅表示已触发 abort，仍须消费终态并等待 Adapter 清理。 */
     cancel(invocationId: string, reason?: string): boolean;
     /** Route an answer only to the adapter instance that owns the active invocation. */
     respondInteraction(invocationId: string, response: InteractionResponse): Promise<void>;
     respondNative(invocationId: string, response: NativeInteractionResponse): Promise<void>;
-    /** Abort every invocation and wait briefly for adapter cleanup to reap its
-     * provider processes. Used when the RPC parent disappears or shuts down. */
-    shutdown(reason?: string, timeoutMs?: number): Promise<void>;
+    /**
+     * 停止接纳并取消未终结执行，在 timeoutMs 内等待 Adapter 清理；不负责业务投递收尾。
+     * 并发调用共用当前尝试；超时或清理失败返回 incomplete 和遗留身份，不冒充资源已回收。
+     */
+    shutdown(reason?: string, timeoutMs?: number): Promise<ExecutorShutdownResult>;
 }
-export { spawnAdapterHost } from "./process.js";
-export { serveAdapterHost } from "./serve.js";
-export type { AdapterHostProcess, SpawnAdapterHostOptions } from "./process.js";
-export { AdapterHostRpcClient, AdapterHostRpcServer, type AdapterHostRpc, type RpcTrace, type RpcTraceDirection } from "./rpc.js";
 export { DEFAULT_RUNTIME_LIMITS } from "./watchdog.js";