niceeval 0.13.2 → 0.13.3

package/dist/sandbox/backend.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.noSandboxBackendCapabilities = exports.unsupportedBackendCapability = void 0;
+exports.SandboxManagedProcessCapabilityError = exports.noSandboxBackendCapabilities = exports.unsupportedBackendCapability = void 0;
+exports.unsupportedBackendCapabilityBecause = unsupportedBackendCapabilityBecause;
 exports.supportedBackendCapability = supportedBackendCapability;
 exports.providerBoundaryEffect = providerBoundaryEffect;
 exports.providerCompatibilityPromise = providerCompatibilityPromise;
@@ -9,18 +10,24 @@ exports.registerSandboxCapabilities = registerSandboxCapabilities;
 exports.inheritSandboxCapabilities = inheritSandboxCapabilities;
 exports.sandboxCapabilities = sandboxCapabilities;
 exports.sandboxSupportsRootCommands = sandboxSupportsRootCommands;
+exports.requireManagedProcessCapability = requireManagedProcessCapability;
 exports.sandboxReuseCapability = sandboxReuseCapability;
 // Provider Promise SDK 与公共 Sandbox facade 之间的唯一边界。
 const effect_1 = require("effect");
 exports.unsupportedBackendCapability = Object.freeze({
     _tag: "Unsupported",
+    reason: "the provider does not implement this capability",
 });
+function unsupportedBackendCapabilityBecause(reason) {
+    return Object.freeze({ _tag: "Unsupported", reason });
+}
 exports.noSandboxBackendCapabilities = Object.freeze({
     rootCommands: exports.unsupportedBackendCapability,
     appendLog: exports.unsupportedBackendCapability,
     suspend: exports.unsupportedBackendCapability,
     ensureLifetime: exports.unsupportedBackendCapability,
     setCommandDeadline: exports.unsupportedBackendCapability,
+    managedProcess: exports.unsupportedBackendCapability,
 });
 function supportedBackendCapability(value) {
     return Object.freeze({ _tag: "Supported", value });
@@ -56,7 +63,10 @@ function customSandboxBackend(sandbox) {
     const appendLog = sandbox.appendLog;
     // Provider facade 产出的 Sandbox 再经 runtime 归一化时必须保留 provider-only capabilities；
     // 作者直接返回的普通 Sandbox 没有登记项，仍严格退回 Unsupported，不能靠鸭子类型猜能力。
-    const registered = SANDBOX_CAPABILITIES.get(sandbox) ?? exports.noSandboxBackendCapabilities;
+    const registered = SANDBOX_CAPABILITIES.get(sandbox) ?? {
+        ...exports.noSandboxBackendCapabilities,
+        managedProcess: unsupportedBackendCapabilityBecause("custom Sandbox facades do not declare the internal managed-process capability"),
+    };
     return {
         get workdir() {
             return sandbox.workdir;
@@ -108,6 +118,26 @@ function sandboxCapabilities(sandbox) {
 function sandboxSupportsRootCommands(sandbox) {
     return SANDBOX_CAPABILITIES.get(sandbox)?.rootCommands._tag === "Supported";
 }
+class SandboxManagedProcessCapabilityError extends Error {
+    agent;
+    sandboxId;
+    reason;
+    name = "SandboxManagedProcessCapabilityError";
+    constructor(agent, sandboxId, reason) {
+        super(`Agent ${agent} requires the sandbox managed-process capability, but sandbox ${sandboxId} does not support it: ${reason}`);
+        this.agent = agent;
+        this.sandboxId = sandboxId;
+        this.reason = reason;
+    }
+}
+exports.SandboxManagedProcessCapabilityError = SandboxManagedProcessCapabilityError;
+function requireManagedProcessCapability(sandbox, agent) {
+    const capability = sandboxCapabilities(sandbox).managedProcess;
+    if (capability._tag === "Unsupported") {
+        throw new SandboxManagedProcessCapabilityError(agent, sandbox.sandboxId, capability.reason);
+    }
+    return capability.value;
+}
 /** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */
 function sandboxReuseCapability(sandbox) {
     const capability = sandboxCapabilities(sandbox).ensureLifetime;

package/dist/sandbox/backend.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["backend.ts"],"names":[],"mappings":"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","sourcesContent":["// Provider Promise SDK 与公共 Sandbox facade 之间的唯一边界。\nimport { Effect } from \"effect\";\nimport type { CommandOptions, CommandResult, Sandbox, SandboxReuseCapability, SandboxTransferOperations, } from \"./types.ts\";\nexport type SandboxBackendSupport<T> = {\n    readonly _tag: \"Supported\";\n    readonly value: T;\n} | {\n    readonly _tag: \"Unsupported\";\n};\nexport interface SandboxBackendCapabilities {\n    /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */\n    readonly rootCommands: SandboxBackendSupport<true>;\n    readonly appendLog: SandboxBackendSupport<(line: string) => Promise<void>>;\n    readonly suspend: SandboxBackendSupport<() => Promise<void>>;\n    readonly ensureLifetime: SandboxBackendSupport<(minRemainingMs: number) => Promise<{\n        ready: true;\n        expiresAt?: string;\n    } | {\n        ready: false;\n        reason: string;\n    }>>;\n    readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;\n}\nexport interface SandboxProviderBackend extends SandboxTransferOperations {\n    readonly workdir: string;\n    readonly sandboxId: string;\n    readonly otlpHost: string | null;\n    readonly capabilities: SandboxBackendCapabilities;\n    runCommand(command: string, args?: readonly string[], options?: CommandOptions): Promise<CommandResult>;\n    runShell(script: string, options?: CommandOptions): Promise<CommandResult>;\n    readText(path: string): Promise<string>;\n    writeText(path: string, content: string): Promise<void>;\n    readBytes(path: string): Promise<Uint8Array>;\n    writeBytes(path: string, content: Uint8Array): Promise<void>;\n    pathExists(path: string): Promise<boolean>;\n    stop(): Promise<void>;\n}\nexport const unsupportedBackendCapability: SandboxBackendSupport<never> = Object.freeze({\n    _tag: \"Unsupported\",\n});\nexport const noSandboxBackendCapabilities: SandboxBackendCapabilities = Object.freeze({\n    rootCommands: unsupportedBackendCapability,\n    appendLog: unsupportedBackendCapability,\n    suspend: unsupportedBackendCapability,\n    ensureLifetime: unsupportedBackendCapability,\n    setCommandDeadline: unsupportedBackendCapability,\n});\nexport function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T> {\n    return Object.freeze({ _tag: \"Supported\", value });\n}\nfunction providerBoundaryError(cause: unknown): Error {\n    return cause instanceof Error ? cause : new Error(String(cause));\n}\n/** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */\nexport function providerBoundaryEffect<T>(operation: (signal: AbortSignal) => Promise<T>): Effect.Effect<T, Error> {\n    return Effect.tryPromise({\n        // 保留 Effect 运行时的取消信号，供真正支持 AbortSignal 的 SDK adapter 接入；不把中断\n        // 编码成 Error，也不在这里启动嵌套 runtime。\n        try: (signal) => operation(signal),\n        catch: providerBoundaryError,\n    });\n}\n/**\n * 公开 Sandbox Promise 接口唯一的兼容入口。\n *\n * 这不是内部 Effect runner：它只把 provider Promise 原样留在公开兼容面，并归一化非 Error\n * rejection。runtime / resource lifecycle 必须改用 providerBoundaryEffect() 组合 Effect。\n */\nexport async function providerCompatibilityPromise<T>(operation: () => Promise<T>): Promise<T> {\n    try {\n        return await operation();\n    }\n    catch (cause) {\n        throw providerBoundaryError(cause);\n    }\n}\n/** defineSandbox() 的公共新接口实现显式降成 provider backend；不探测任何旧方法。 */\nexport function customSandboxBackend(sandbox: Sandbox): SandboxProviderBackend {\n    const appendLog = sandbox.appendLog;\n    // Provider facade 产出的 Sandbox 再经 runtime 归一化时必须保留 provider-only capabilities；\n    // 作者直接返回的普通 Sandbox 没有登记项，仍严格退回 Unsupported，不能靠鸭子类型猜能力。\n    const registered = SANDBOX_CAPABILITIES.get(sandbox) ?? noSandboxBackendCapabilities;\n    return {\n        get workdir() {\n            return sandbox.workdir;\n        },\n        get sandboxId() {\n            return sandbox.sandboxId;\n        },\n        get otlpHost() {\n            return sandbox.otlpHost;\n        },\n        capabilities: {\n            ...registered,\n            appendLog: appendLog === undefined\n                ? unsupportedBackendCapability\n                : supportedBackendCapability((line) => appendLog.call(sandbox, line)),\n        },\n        runCommand: (command, args, options) => sandbox.runCommand(command, args, options),\n        runShell: (script, options) => sandbox.runShell(script, options),\n        readText: (path) => sandbox.readText(path),\n        writeText: (path, content) => sandbox.writeText(path, content),\n        readBytes: (path) => sandbox.readBytes(path),\n        writeBytes: (path, content) => sandbox.writeBytes(path, content),\n        pathExists: (path) => sandbox.pathExists(path),\n        uploadFile: (source, targetPath) => sandbox.uploadFile(source, targetPath),\n        uploadDirectory: (sourceDir, targetDir, options) => sandbox.uploadDirectory(sourceDir, targetDir, options),\n        downloadFile: (sourcePath, target) => sandbox.downloadFile(sourcePath, target),\n        downloadDirectory: (sourceDir, targetDir, options) => sandbox.downloadDirectory(sourceDir, targetDir, options),\n        stop: () => sandbox.stop(),\n    };\n}\nconst SANDBOX_CAPABILITIES = new WeakMap<Sandbox, SandboxBackendCapabilities>();\nexport function registerSandboxCapabilities(sandbox: Sandbox, capabilities: SandboxBackendCapabilities): void {\n    SANDBOX_CAPABILITIES.set(sandbox, capabilities);\n}\n/** 装饰器产生新 Sandbox 对象时显式继承同一份 provider-only 能力，不靠接口外成员探测。 */\nexport function inheritSandboxCapabilities(source: Sandbox, target: Sandbox): void {\n    const capabilities = SANDBOX_CAPABILITIES.get(source);\n    if (capabilities !== undefined)\n        SANDBOX_CAPABILITIES.set(target, capabilities);\n}\nexport function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities {\n    const capabilities = SANDBOX_CAPABILITIES.get(sandbox);\n    if (capabilities === undefined) {\n        throw new Error(`sandbox ${sandbox.sandboxId} was not constructed by the provider facade`);\n    }\n    return capabilities;\n}\n/** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */\nexport function sandboxSupportsRootCommands(sandbox: Sandbox): boolean {\n    return SANDBOX_CAPABILITIES.get(sandbox)?.rootCommands._tag === \"Supported\";\n}\n/** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */\nexport function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined {\n    const capability = sandboxCapabilities(sandbox).ensureLifetime;\n    return capability._tag === \"Supported\" ? { ensureLifetime: capability.value } : undefined;\n}\n"]}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["backend.ts"],"names":[],"mappings":"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","sourcesContent":["// Provider Promise SDK 与公共 Sandbox facade 之间的唯一边界。\nimport { Effect } from \"effect\";\nimport type { CommandOptions, CommandResult, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations, } from \"./types.ts\";\nexport type SandboxBackendSupport<T> = {\n    readonly _tag: \"Supported\";\n    readonly value: T;\n} | {\n    readonly _tag: \"Unsupported\";\n    readonly reason: string;\n};\nexport interface SandboxBackendCapabilities {\n    /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */\n    readonly rootCommands: SandboxBackendSupport<true>;\n    readonly appendLog: SandboxBackendSupport<(line: string) => Promise<void>>;\n    readonly suspend: SandboxBackendSupport<() => Promise<void>>;\n    readonly ensureLifetime: SandboxBackendSupport<(minRemainingMs: number) => Promise<{\n        ready: true;\n        expiresAt?: string;\n    } | {\n        ready: false;\n        reason: string;\n    }>>;\n    readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;\n    readonly managedProcess: SandboxBackendSupport<(input: ManagedProcessStart) => Promise<ManagedProcess>>;\n}\nexport interface SandboxProviderBackend extends SandboxTransferOperations {\n    readonly workdir: string;\n    readonly sandboxId: string;\n    readonly otlpHost: string | null;\n    readonly capabilities: SandboxBackendCapabilities;\n    runCommand(command: string, args?: readonly string[], options?: CommandOptions): Promise<CommandResult>;\n    runShell(script: string, options?: CommandOptions): Promise<CommandResult>;\n    readText(path: string): Promise<string>;\n    writeText(path: string, content: string): Promise<void>;\n    readBytes(path: string): Promise<Uint8Array>;\n    writeBytes(path: string, content: Uint8Array): Promise<void>;\n    pathExists(path: string): Promise<boolean>;\n    stop(): Promise<void>;\n}\nexport const unsupportedBackendCapability: SandboxBackendSupport<never> = Object.freeze({\n    _tag: \"Unsupported\",\n    reason: \"the provider does not implement this capability\",\n});\nexport function unsupportedBackendCapabilityBecause(reason: string): SandboxBackendSupport<never> {\n    return Object.freeze({ _tag: \"Unsupported\", reason });\n}\nexport const noSandboxBackendCapabilities: SandboxBackendCapabilities = Object.freeze({\n    rootCommands: unsupportedBackendCapability,\n    appendLog: unsupportedBackendCapability,\n    suspend: unsupportedBackendCapability,\n    ensureLifetime: unsupportedBackendCapability,\n    setCommandDeadline: unsupportedBackendCapability,\n    managedProcess: unsupportedBackendCapability,\n});\nexport function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T> {\n    return Object.freeze({ _tag: \"Supported\", value });\n}\nfunction providerBoundaryError(cause: unknown): Error {\n    return cause instanceof Error ? cause : new Error(String(cause));\n}\n/** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */\nexport function providerBoundaryEffect<T>(operation: (signal: AbortSignal) => Promise<T>): Effect.Effect<T, Error> {\n    return Effect.tryPromise({\n        // 保留 Effect 运行时的取消信号，供真正支持 AbortSignal 的 SDK adapter 接入；不把中断\n        // 编码成 Error，也不在这里启动嵌套 runtime。\n        try: (signal) => operation(signal),\n        catch: providerBoundaryError,\n    });\n}\n/**\n * 公开 Sandbox Promise 接口唯一的兼容入口。\n *\n * 这不是内部 Effect runner：它只把 provider Promise 原样留在公开兼容面，并归一化非 Error\n * rejection。runtime / resource lifecycle 必须改用 providerBoundaryEffect() 组合 Effect。\n */\nexport async function providerCompatibilityPromise<T>(operation: () => Promise<T>): Promise<T> {\n    try {\n        return await operation();\n    }\n    catch (cause) {\n        throw providerBoundaryError(cause);\n    }\n}\n/** defineSandbox() 的公共新接口实现显式降成 provider backend；不探测任何旧方法。 */\nexport function customSandboxBackend(sandbox: Sandbox): SandboxProviderBackend {\n    const appendLog = sandbox.appendLog;\n    // Provider facade 产出的 Sandbox 再经 runtime 归一化时必须保留 provider-only capabilities；\n    // 作者直接返回的普通 Sandbox 没有登记项，仍严格退回 Unsupported，不能靠鸭子类型猜能力。\n    const registered = SANDBOX_CAPABILITIES.get(sandbox) ?? {\n        ...noSandboxBackendCapabilities,\n        managedProcess: unsupportedBackendCapabilityBecause(\"custom Sandbox facades do not declare the internal managed-process capability\"),\n    };\n    return {\n        get workdir() {\n            return sandbox.workdir;\n        },\n        get sandboxId() {\n            return sandbox.sandboxId;\n        },\n        get otlpHost() {\n            return sandbox.otlpHost;\n        },\n        capabilities: {\n            ...registered,\n            appendLog: appendLog === undefined\n                ? unsupportedBackendCapability\n                : supportedBackendCapability((line) => appendLog.call(sandbox, line)),\n        },\n        runCommand: (command, args, options) => sandbox.runCommand(command, args, options),\n        runShell: (script, options) => sandbox.runShell(script, options),\n        readText: (path) => sandbox.readText(path),\n        writeText: (path, content) => sandbox.writeText(path, content),\n        readBytes: (path) => sandbox.readBytes(path),\n        writeBytes: (path, content) => sandbox.writeBytes(path, content),\n        pathExists: (path) => sandbox.pathExists(path),\n        uploadFile: (source, targetPath) => sandbox.uploadFile(source, targetPath),\n        uploadDirectory: (sourceDir, targetDir, options) => sandbox.uploadDirectory(sourceDir, targetDir, options),\n        downloadFile: (sourcePath, target) => sandbox.downloadFile(sourcePath, target),\n        downloadDirectory: (sourceDir, targetDir, options) => sandbox.downloadDirectory(sourceDir, targetDir, options),\n        stop: () => sandbox.stop(),\n    };\n}\nconst SANDBOX_CAPABILITIES = new WeakMap<Sandbox, SandboxBackendCapabilities>();\nexport function registerSandboxCapabilities(sandbox: Sandbox, capabilities: SandboxBackendCapabilities): void {\n    SANDBOX_CAPABILITIES.set(sandbox, capabilities);\n}\n/** 装饰器产生新 Sandbox 对象时显式继承同一份 provider-only 能力，不靠接口外成员探测。 */\nexport function inheritSandboxCapabilities(source: Sandbox, target: Sandbox): void {\n    const capabilities = SANDBOX_CAPABILITIES.get(source);\n    if (capabilities !== undefined)\n        SANDBOX_CAPABILITIES.set(target, capabilities);\n}\nexport function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities {\n    const capabilities = SANDBOX_CAPABILITIES.get(sandbox);\n    if (capabilities === undefined) {\n        throw new Error(`sandbox ${sandbox.sandboxId} was not constructed by the provider facade`);\n    }\n    return capabilities;\n}\n/** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */\nexport function sandboxSupportsRootCommands(sandbox: Sandbox): boolean {\n    return SANDBOX_CAPABILITIES.get(sandbox)?.rootCommands._tag === \"Supported\";\n}\nexport class SandboxManagedProcessCapabilityError extends Error {\n    readonly name = \"SandboxManagedProcessCapabilityError\";\n    constructor(readonly agent: string, readonly sandboxId: string, readonly reason: string) {\n        super(`Agent ${agent} requires the sandbox managed-process capability, but sandbox ${sandboxId} does not support it: ${reason}`);\n    }\n}\nexport function requireManagedProcessCapability(sandbox: Sandbox, agent: string): (input: ManagedProcessStart) => Promise<ManagedProcess> {\n    const capability = sandboxCapabilities(sandbox).managedProcess;\n    if (capability._tag === \"Unsupported\") {\n        throw new SandboxManagedProcessCapabilityError(agent, sandbox.sandboxId, capability.reason);\n    }\n    return capability.value;\n}\n/** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */\nexport function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined {\n    const capability = sandboxCapabilities(sandbox).ensureLifetime;\n    return capability._tag === \"Supported\" ? { ensureLifetime: capability.value } : undefined;\n}\n"]}

package/dist/sandbox/backend.d.cts

@@ -1,10 +1,11 @@
 import { Effect } from "effect";
-import type { CommandOptions, CommandResult, Sandbox, SandboxReuseCapability, SandboxTransferOperations } from "./types.cjs";
+import type { CommandOptions, CommandResult, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations } from "./types.cjs";
 export type SandboxBackendSupport<T> = {
     readonly _tag: "Supported";
     readonly value: T;
 } | {
     readonly _tag: "Unsupported";
+    readonly reason: string;
 };
 export interface SandboxBackendCapabilities {
     /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */
@@ -19,6 +20,7 @@ export interface SandboxBackendCapabilities {
         reason: string;
     }>>;
     readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;
+    readonly managedProcess: SandboxBackendSupport<(input: ManagedProcessStart) => Promise<ManagedProcess>>;
 }
 export interface SandboxProviderBackend extends SandboxTransferOperations {
     readonly workdir: string;
@@ -35,6 +37,7 @@ export interface SandboxProviderBackend extends SandboxTransferOperations {
     stop(): Promise<void>;
 }
 export declare const unsupportedBackendCapability: SandboxBackendSupport<never>;
+export declare function unsupportedBackendCapabilityBecause(reason: string): SandboxBackendSupport<never>;
 export declare const noSandboxBackendCapabilities: SandboxBackendCapabilities;
 export declare function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T>;
 /** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */
@@ -54,5 +57,13 @@ export declare function inheritSandboxCapabilities(source: Sandbox, target: Sand
 export declare function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities;
 /** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */
 export declare function sandboxSupportsRootCommands(sandbox: Sandbox): boolean;
+export declare class SandboxManagedProcessCapabilityError extends Error {
+    readonly agent: string;
+    readonly sandboxId: string;
+    readonly reason: string;
+    readonly name = "SandboxManagedProcessCapabilityError";
+    constructor(agent: string, sandboxId: string, reason: string);
+}
+export declare function requireManagedProcessCapability(sandbox: Sandbox, agent: string): (input: ManagedProcessStart) => Promise<ManagedProcess>;
 /** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */
 export declare function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined;

package/dist/sandbox/backend.d.mts

@@ -1,10 +1,11 @@
 import { Effect } from "effect";
-import type { CommandOptions, CommandResult, Sandbox, SandboxReuseCapability, SandboxTransferOperations } from "./types.mjs";
+import type { CommandOptions, CommandResult, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations } from "./types.mjs";
 export type SandboxBackendSupport<T> = {
     readonly _tag: "Supported";
     readonly value: T;
 } | {
     readonly _tag: "Unsupported";
+    readonly reason: string;
 };
 export interface SandboxBackendCapabilities {
     /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */
@@ -19,6 +20,7 @@ export interface SandboxBackendCapabilities {
         reason: string;
     }>>;
     readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;
+    readonly managedProcess: SandboxBackendSupport<(input: ManagedProcessStart) => Promise<ManagedProcess>>;
 }
 export interface SandboxProviderBackend extends SandboxTransferOperations {
     readonly workdir: string;
@@ -35,6 +37,7 @@ export interface SandboxProviderBackend extends SandboxTransferOperations {
     stop(): Promise<void>;
 }
 export declare const unsupportedBackendCapability: SandboxBackendSupport<never>;
+export declare function unsupportedBackendCapabilityBecause(reason: string): SandboxBackendSupport<never>;
 export declare const noSandboxBackendCapabilities: SandboxBackendCapabilities;
 export declare function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T>;
 /** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */
@@ -54,5 +57,13 @@ export declare function inheritSandboxCapabilities(source: Sandbox, target: Sand
 export declare function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities;
 /** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */
 export declare function sandboxSupportsRootCommands(sandbox: Sandbox): boolean;
+export declare class SandboxManagedProcessCapabilityError extends Error {
+    readonly agent: string;
+    readonly sandboxId: string;
+    readonly reason: string;
+    readonly name = "SandboxManagedProcessCapabilityError";
+    constructor(agent: string, sandboxId: string, reason: string);
+}
+export declare function requireManagedProcessCapability(sandbox: Sandbox, agent: string): (input: ManagedProcessStart) => Promise<ManagedProcess>;
 /** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */
 export declare function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined;

package/dist/sandbox/backend.d.ts

@@ -1,10 +1,11 @@
 import { Effect } from "effect";
-import type { CommandOptions, CommandResult, Sandbox, SandboxReuseCapability, SandboxTransferOperations } from "./types.js";
+import type { CommandOptions, CommandResult, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations } from "./types.js";
 export type SandboxBackendSupport<T> = {
     readonly _tag: "Supported";
     readonly value: T;
 } | {
     readonly _tag: "Unsupported";
+    readonly reason: string;
 };
 export interface SandboxBackendCapabilities {
     /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */
@@ -19,6 +20,7 @@ export interface SandboxBackendCapabilities {
         reason: string;
     }>>;
     readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;
+    readonly managedProcess: SandboxBackendSupport<(input: ManagedProcessStart) => Promise<ManagedProcess>>;
 }
 export interface SandboxProviderBackend extends SandboxTransferOperations {
     readonly workdir: string;
@@ -35,6 +37,7 @@ export interface SandboxProviderBackend extends SandboxTransferOperations {
     stop(): Promise<void>;
 }
 export declare const unsupportedBackendCapability: SandboxBackendSupport<never>;
+export declare function unsupportedBackendCapabilityBecause(reason: string): SandboxBackendSupport<never>;
 export declare const noSandboxBackendCapabilities: SandboxBackendCapabilities;
 export declare function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T>;
 /** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */
@@ -54,5 +57,13 @@ export declare function inheritSandboxCapabilities(source: Sandbox, target: Sand
 export declare function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities;
 /** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */
 export declare function sandboxSupportsRootCommands(sandbox: Sandbox): boolean;
+export declare class SandboxManagedProcessCapabilityError extends Error {
+    readonly agent: string;
+    readonly sandboxId: string;
+    readonly reason: string;
+    readonly name = "SandboxManagedProcessCapabilityError";
+    constructor(agent: string, sandboxId: string, reason: string);
+}
+export declare function requireManagedProcessCapability(sandbox: Sandbox, agent: string): (input: ManagedProcessStart) => Promise<ManagedProcess>;
 /** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */
 export declare function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined;

package/dist/sandbox/backend.js

@@ -1,26 +1,32 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./backend.cjs");
-const __niceevalExport0 = __niceevalCanonical["customSandboxBackend"];
-export { __niceevalExport0 as customSandboxBackend };
-const __niceevalExport1 = __niceevalCanonical["inheritSandboxCapabilities"];
-export { __niceevalExport1 as inheritSandboxCapabilities };
-const __niceevalExport2 = __niceevalCanonical["noSandboxBackendCapabilities"];
-export { __niceevalExport2 as noSandboxBackendCapabilities };
-const __niceevalExport3 = __niceevalCanonical["providerBoundaryEffect"];
-export { __niceevalExport3 as providerBoundaryEffect };
-const __niceevalExport4 = __niceevalCanonical["providerCompatibilityPromise"];
-export { __niceevalExport4 as providerCompatibilityPromise };
-const __niceevalExport5 = __niceevalCanonical["registerSandboxCapabilities"];
-export { __niceevalExport5 as registerSandboxCapabilities };
-const __niceevalExport6 = __niceevalCanonical["sandboxCapabilities"];
-export { __niceevalExport6 as sandboxCapabilities };
-const __niceevalExport7 = __niceevalCanonical["sandboxReuseCapability"];
-export { __niceevalExport7 as sandboxReuseCapability };
-const __niceevalExport8 = __niceevalCanonical["sandboxSupportsRootCommands"];
-export { __niceevalExport8 as sandboxSupportsRootCommands };
-const __niceevalExport9 = __niceevalCanonical["supportedBackendCapability"];
-export { __niceevalExport9 as supportedBackendCapability };
-const __niceevalExport10 = __niceevalCanonical["unsupportedBackendCapability"];
-export { __niceevalExport10 as unsupportedBackendCapability };
+const __niceevalExport0 = __niceevalCanonical["SandboxManagedProcessCapabilityError"];
+export { __niceevalExport0 as SandboxManagedProcessCapabilityError };
+const __niceevalExport1 = __niceevalCanonical["customSandboxBackend"];
+export { __niceevalExport1 as customSandboxBackend };
+const __niceevalExport2 = __niceevalCanonical["inheritSandboxCapabilities"];
+export { __niceevalExport2 as inheritSandboxCapabilities };
+const __niceevalExport3 = __niceevalCanonical["noSandboxBackendCapabilities"];
+export { __niceevalExport3 as noSandboxBackendCapabilities };
+const __niceevalExport4 = __niceevalCanonical["providerBoundaryEffect"];
+export { __niceevalExport4 as providerBoundaryEffect };
+const __niceevalExport5 = __niceevalCanonical["providerCompatibilityPromise"];
+export { __niceevalExport5 as providerCompatibilityPromise };
+const __niceevalExport6 = __niceevalCanonical["registerSandboxCapabilities"];
+export { __niceevalExport6 as registerSandboxCapabilities };
+const __niceevalExport7 = __niceevalCanonical["requireManagedProcessCapability"];
+export { __niceevalExport7 as requireManagedProcessCapability };
+const __niceevalExport8 = __niceevalCanonical["sandboxCapabilities"];
+export { __niceevalExport8 as sandboxCapabilities };
+const __niceevalExport9 = __niceevalCanonical["sandboxReuseCapability"];
+export { __niceevalExport9 as sandboxReuseCapability };
+const __niceevalExport10 = __niceevalCanonical["sandboxSupportsRootCommands"];
+export { __niceevalExport10 as sandboxSupportsRootCommands };
+const __niceevalExport11 = __niceevalCanonical["supportedBackendCapability"];
+export { __niceevalExport11 as supportedBackendCapability };
+const __niceevalExport12 = __niceevalCanonical["unsupportedBackendCapability"];
+export { __niceevalExport12 as unsupportedBackendCapability };
+const __niceevalExport13 = __niceevalCanonical["unsupportedBackendCapabilityBecause"];
+export { __niceevalExport13 as unsupportedBackendCapabilityBecause };
 //# sourceMappingURL=backend.js.map

package/dist/sandbox/docker.cjs

@@ -14,6 +14,7 @@ exports.dockerManagedNetworkOptions = dockerManagedNetworkOptions;
 // 改编自 agent-eval 的 docker-sandbox.ts,签名对齐 ../types.ts 的 Sandbox 契约
 //(runShell/runCommand 的 opts 一律是选项对象,不再用位置参数)。
 const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
 const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
 const dockerode_1 = __importDefault(require("dockerode"));
@@ -30,6 +31,7 @@ const errors_ts_1 = require("./errors.cjs");
 const run_identity_ts_1 = require("./run-identity.cjs");
 const backend_ts_1 = require("./backend.cjs");
 const dind_supervisor_ts_1 = require("./dind-supervisor.cjs");
+const managed_process_ts_1 = require("./managed-process.cjs");
 /**
  * dockerode 对镜像拉取限流没有专门的错误类型;Docker Hub 429 体现在错误 message 里
  * (如 "toomanyrequests: You have reached your pull rate limit")。
@@ -267,7 +269,145 @@ class DockerSandbox {
         suspend: (0, backend_ts_1.supportedBackendCapability)(() => this.suspend()),
         ensureLifetime: (0, backend_ts_1.supportedBackendCapability)((minRemainingMs) => this.ensureLifetime(minRemainingMs)),
         setCommandDeadline: (0, backend_ts_1.supportedBackendCapability)((deadlineAt) => this.setCommandDeadline(deadlineAt)),
+        managedProcess: (0, backend_ts_1.supportedBackendCapability)((input) => this.startManagedProcess(input)),
     };
+    async startManagedProcess(input) {
+        if (!this.container)
+            throw new Error((0, index_ts_1.t)("docker.containerNotInitialized"));
+        const [command, ...args] = input.argv;
+        const env = {
+            HOME: this.defaultHome,
+            USER: this.defaultUserName,
+            LOGNAME: this.defaultUserName,
+            ...input.env,
+            PATH: this.sandboxPath,
+            ...(this.defaultIsRoot ? { npm_config_unsafe_perm: "true" } : {}),
+        };
+        const marker = `__NICEEVAL_MANAGED_PID_${(0, node_crypto_1.randomUUID)()}__`;
+        const exec = await this.container.exec({
+            // If the Docker exec leader is already a process-group leader, setsid
+            // forks. --wait keeps Docker's receipt tied to the native child lifetime.
+            Cmd: ["setsid", "--wait", "sh", "-c", `printf '${marker}%s\\n' "$$" >&2; exec "$@"`, "sh", command, ...args],
+            AttachStdin: true,
+            AttachStdout: true,
+            AttachStderr: true,
+            WorkingDir: (0, paths_ts_1.resolveSandboxPath)(this.workdir, input.cwd),
+            Env: Object.entries(env).map(([key, value]) => `${key}=${value}`),
+            User: this.userOverride,
+        });
+        const stream = await exec.start({ hijack: true, stdin: true });
+        const output = new managed_process_ts_1.ManagedProcessOutput();
+        const stdout = new node_stream_1.PassThrough();
+        const stderr = new node_stream_1.PassThrough();
+        stdout.on("data", (bytes) => output.push({ _tag: "Stdout", bytes: new Uint8Array(bytes) }));
+        let stderrPrefix = Buffer.alloc(0);
+        let processGroup;
+        stderr.on("data", (bytes) => {
+            if (processGroup !== undefined) {
+                output.push({ _tag: "Stderr", bytes: new Uint8Array(bytes) });
+                return;
+            }
+            stderrPrefix = Buffer.concat([stderrPrefix, bytes]);
+            const newline = stderrPrefix.indexOf(10);
+            if (newline < 0)
+                return;
+            const first = stderrPrefix.subarray(0, newline).toString("utf8");
+            if (!first.startsWith(marker) || !/^\d+$/.test(first.slice(marker.length))) {
+                output.push({ _tag: "Stderr", bytes: new Uint8Array(stderrPrefix) });
+            }
+            else {
+                processGroup = Number(first.slice(marker.length));
+                const rest = stderrPrefix.subarray(newline + 1);
+                if (rest.length > 0)
+                    output.push({ _tag: "Stderr", bytes: new Uint8Array(rest) });
+            }
+            stderrPrefix = Buffer.alloc(0);
+        });
+        this.docker.modem.demuxStream(stream, stdout, stderr);
+        let poll;
+        let settled = false;
+        let rejectExit;
+        const finishError = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (poll !== undefined)
+                clearInterval(poll);
+            output.end();
+            stream.destroy();
+            rejectExit(error);
+        };
+        const exit = new Promise((resolve, reject) => {
+            rejectExit = reject;
+            stream.once("error", finishError);
+            poll = setInterval(() => {
+                void exec.inspect().then((inspection) => {
+                    if (inspection.Running)
+                        return;
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (poll !== undefined)
+                        clearInterval(poll);
+                    output.end();
+                    stream.destroy();
+                    resolve({ exitCode: inspection.ExitCode ?? null });
+                }, finishError);
+            }, 100);
+        });
+        let closeReceipt;
+        let terminateReceipt;
+        let stdinState = "open";
+        return {
+            output,
+            writeStdin: (bytes) => new Promise((resolve, reject) => {
+                if (stdinState !== "open") {
+                    reject(new Error("managed process stdin is closed"));
+                    return;
+                }
+                stream.write(Buffer.from(bytes), (error) => error ? reject(error) : resolve());
+            }),
+            closeStdin: () => closeReceipt ??= new Promise((resolve) => {
+                stdinState = "closing";
+                stream.end(() => { stdinState = "closed"; resolve(); });
+            }),
+            wait: () => exit,
+            terminate: () => terminateReceipt ??= (async () => {
+                stdinState = "closing";
+                const inspection = await exec.inspect().catch(() => undefined);
+                if (!inspection?.Running) {
+                    await exit.catch(() => undefined);
+                    return;
+                }
+                if (processGroup === undefined) {
+                    const error = new Error("docker managed process did not disclose its process-group identity; sandbox retirement is required");
+                    finishError(error);
+                    throw error;
+                }
+                // Do not route this provider-owned control operation through runCommand's
+                // command-tree supervisor: killing the target exec while that supervisor
+                // samples the same tree creates an ambiguous non-zero receipt. Docker's
+                // own exec receipt is the exact acknowledgement for this one kill(2).
+                const killer = await this.container.exec({
+                    // POSIX `kill` is a shell builtin in slim images (no /usr/bin/kill).
+                    // The PGID is a separate positional parameter, never interpolated.
+                    Cmd: ["sh", "-c", "kill -KILL \"$1\"", "sh", `-${processGroup}`],
+                    AttachStdout: true,
+                    AttachStderr: true,
+                    User: "root",
+                });
+                const killStream = await killer.start({});
+                const killOutput = await (0, docker_stream_ts_1.readableToBuffer)(killStream);
+                const killed = await killer.inspect();
+                if (killed.ExitCode !== 0) {
+                    const error = new Error(`docker could not terminate managed process group ${processGroup}; sandbox retirement is required: ${killOutput.toString("utf8")}`);
+                    finishError(error);
+                    throw error;
+                }
+                await exit;
+            })(),
+        };
+    }
     constructor(options = {}) {
         this.docker = new dockerode_1.default(options.dockerSocketPath === undefined ? undefined : { socketPath: options.dockerSocketPath });
         this.workdir = options.workdir ?? CONTAINER_WORKDIR;