@deepseek-ai/dsh-subprocess-e2b 0.0.1-rc.1

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`.
+* @module @deepseek-ai/dsh-subprocess-e2b/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-subprocess-e2b";
+/** Cordis companion plugin name. */
+const name = "subprocess-e2b-invariant";
+/** Service required before reserving package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: live remote handles are private teardown ownership,
+* and the E2B command event stream is the sole outcome authority.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/environment.d.ts

@@ -0,0 +1,29 @@
+/** Shared remote-environment scrubbing for E2B process and terminal launchers. */
+import type { Sandbox } from '@deepseek-ai/dsh-e2b';
+/**
+ * Read the remote environment through ASCII base64 so SDK callback chunking cannot corrupt UTF-8.
+ * @param sandbox - shared E2B execution world.
+ * @param signal - optional cancellation for the control-plane request.
+ * @returns the complete NUL-delimited UTF-8 environment.
+ */
+export declare function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string>;
+/**
+ * Parse an E2B NUL-delimited environment while removing harness-private and credential-shaped names.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Mutable retained entries for the caller to overlay and serialize.
+ */
+export declare function scrubRemoteEnvironment(raw: string): Map<string, string>;
+/**
+ * Isolate E2B's fixed login-shell bootstrap from user profiles and ambient credentials.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Explicit E2B command or PTY overrides for bootstrap-shell startup.
+ */
+export declare function bootstrapEnvironment(raw: string): Record<string, string>;
+/**
+ * Overlay explicit entries and serialize one validated E2B environment.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @param explicit - Deliberate caller overrides applied after ambient scrubbing; an `undefined` tombstone removes an ambient entry.
+ * @returns NUL-delimited `name=value` entries accepted by `env -i`.
+ */
+export declare function serializeRemoteEnvironment(raw: string, explicit: Readonly<NodeJS.ProcessEnv> | undefined): string;
+//# sourceMappingURL=environment.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * E2B Service provider for the subprocess capability seam. Each handle starts through the
+ * shared sandbox and retains command output/status paths in that remote world.
+ * @module @deepseek-ai/dsh-subprocess-e2b
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess';
+import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+    /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+    pollMs?: number;
+}
+/** E2B command manager registered as `ctx.subprocess`. */
+export declare class E2BSubprocessService extends SubprocessService {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly live;
+    private readonly terminals;
+    private readonly terminalSetups;
+    private readonly pollMs;
+    private disposing;
+    /** Create the E2B subprocess service and bind its disposal policy. */
+    constructor(ctx: Context, config: Config);
+    /** @inheritdoc */
+    resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+    /** @inheritdoc */
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    /** @inheritdoc */
+    spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+export default E2BSubprocessService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`.
+ * @module @deepseek-ai/dsh-subprocess-e2b/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "subprocess-e2b-invariant";
+/** Service required before reserving package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/output.d.ts

@@ -0,0 +1,50 @@
+/** Bounded host-side projection of a complete output file retained in E2B. */
+import { Buffer } from 'node:buffer';
+import type { SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess';
+/** Reserved non-base64 frame proving that one remote encoder reached clean EOF. */
+export declare const E2B_OUTPUT_COMPLETE_FRAME = "!dsh-e2b-output-complete!";
+/** Incrementally decode newline-delimited base64 frames emitted by one remote encoder. */
+export declare class E2BBase64Decoder {
+    private pending;
+    private complete;
+    /**
+     * Decode every complete newline-delimited frame in one arbitrarily split SDK callback.
+     * @param text - ASCII base64 frames from E2B's decoded callback.
+     * @returns the complete raw bytes made available by this callback.
+     */
+    push(text: string): Buffer;
+    /**
+     * Validate clean encoder completion, or discard an interrupted trailing frame after requested termination.
+     * @param requireComplete - Whether natural completion requires the reserved EOF frame.
+     */
+    finish(requireComplete?: boolean): void;
+}
+/** Offset reader used for one collect-mode E2B stream. */
+export declare class E2BOutputReader implements SubprocessOutputReader {
+    private readonly maxBytes;
+    private readonly maxSpillBytes;
+    private readonly spillPath;
+    private chunks;
+    private retainedBytes;
+    private totalBytes;
+    private spillValid;
+    /**
+     * Create a bounded reader over one remote spill path.
+     * @param maxBytes - In-memory tail cap.
+     * @param maxSpillBytes - Maximum complete remote file size the caller accepts.
+     * @param spillPath - Remote full-output path.
+     */
+    constructor(maxBytes: number, maxSpillBytes: number | undefined, spillPath: string);
+    /** Total bytes observed from the SDK stream. */
+    get size(): number;
+    /** Stop advertising a remote spill whose writer did not reach clean EOF. */
+    invalidateSpill(): void;
+    /**
+     * Append one byte-faithful decoded transport event.
+     * @param bytes - Raw command bytes recovered from the ASCII SDK transport.
+     */
+    push(bytes: Uint8Array): void;
+    /** @inheritdoc */
+    readFrom(fromByte: number): SubprocessOutputRead;
+}
+//# sourceMappingURL=output.d.ts.map

package/lib/types/process.d.ts

@@ -0,0 +1,71 @@
+/** One asynchronously-started E2B command projected onto the subprocess seam. */
+import { PassThrough, Writable } from 'node:stream';
+import type { SubprocessHandle, SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b';
+/** E2B-backed subprocess handle with deferred remote PID acquisition. */
+export declare class E2BSubprocessHandle implements SubprocessHandle {
+    private readonly runtime;
+    private readonly spec;
+    readonly stateDir: string;
+    private readonly pollMs;
+    readonly stdin: Writable | undefined;
+    readonly stdout: PassThrough | undefined;
+    readonly stderr: PassThrough | undefined;
+    readonly collected: SubprocessHandle['collected'];
+    readonly done: Promise<SubprocessOutcome>;
+    private readonly commandState;
+    private readonly readyState;
+    private readonly stdoutDecoder;
+    private readonly stderrDecoder;
+    private readonly terminationController;
+    /** Releases output waits that survive the command outcome, so blocked SDK callbacks settle. */
+    private readonly outputReleased;
+    private readonly stdoutReader;
+    private readonly stderrReader;
+    private readonly paths;
+    private controlEnvs;
+    private remotePid;
+    private outputTransportError;
+    private outputDrainExpired;
+    private stateDirectoryCreated;
+    private quiescenceProven;
+    private terminationAttempt;
+    private terminationFailure;
+    private terminationSignal;
+    /**
+     * Begin an E2B command without blocking the synchronous subprocess spawn call.
+     * @param runtime - Shared E2B sandbox owner.
+     * @param spec - Fully resolved subprocess request.
+     * @param stateDir - Remote directory retaining process identity, status, and valid spills.
+     * @param pollMs - Remote status/liveness poll cadence.
+     */
+    constructor(runtime: E2BSandboxService, spec: SubprocessSpawnSpec, stateDir: string, pollMs: number);
+    /** Remote process id after start; `-1` while E2B startup is pending or after it fails. */
+    get pid(): number;
+    /** @inheritdoc */
+    terminate(): void;
+    /** @inheritdoc */
+    waitForExit(signal?: AbortSignal): Promise<boolean>;
+    private readonly onAbort;
+    private markQuiescent;
+    private run;
+    private prepareState;
+    private writeBatchStdin;
+    private dispatchOutput;
+    private writeOutput;
+    private waitForProcessGroupId;
+    private waitForCommand;
+    private commandOutcome;
+    private rollbackPublishedFailure;
+    private rollbackUnpublishedGroup;
+    private terminateRemote;
+    private terminateRemoteInSandbox;
+    private terminateGroup;
+    private forceKillGroup;
+    private waitForGroupExit;
+    private throwTerminationFailure;
+    private groupAlive;
+    private finalizeSpills;
+    private removeFailedState;
+}
+//# sourceMappingURL=process.d.ts.map

package/lib/types/remote.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared remote-control helpers for the E2B subprocess adapter: SDK option
+ * shaping, poll ticks, and the one tolerant process-group signal used by both
+ * the ordinary-process and terminal teardown ladders.
+ */
+import type { Sandbox } from '@deepseek-ai/dsh-e2b';
+/**
+ * Normalize an unknown rejection into an Error.
+ * @param error - Any thrown or rejected value.
+ * @returns The value itself when already an Error, else a stringified wrapper.
+ */
+export declare function asError(error: unknown): Error;
+/**
+ * Shape the optional-signal SDK options object.
+ * @param signal - Optional cancellation for one SDK request.
+ * @returns An options fragment that omits an undefined signal.
+ */
+export declare function signalOpts(signal: AbortSignal | undefined): {
+    signal?: AbortSignal;
+};
+/**
+ * Shape control-shell command options with the isolated HOME override.
+ * @param envs - Explicit environment entries for the control command.
+ * @param signal - Optional cancellation for the SDK request.
+ * @returns Options for `sandbox.commands.run` control invocations.
+ */
+export declare function commandOpts(envs: Record<string, string>, signal?: AbortSignal): {
+    envs: Record<string, string>;
+    signal?: AbortSignal;
+};
+/**
+ * Resolve after one duration.
+ * @param ms - Milliseconds to wait.
+ * @returns Settles after the timeout.
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Wait one poll interval or until the signal aborts.
+ * @param pollMs - Poll cadence in milliseconds.
+ * @param signal - Optional abort that ends the wait early.
+ * @returns `true` after a full tick, `false` when aborted first.
+ */
+export declare function waitTick(pollMs: number, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Signal remote process groups, tolerating the shared teardown outcomes: a
+ * nonzero `kill` (groups already gone) and a disappeared sandbox. Both the
+ * pgid-keyed process ladder and the sid-keyed terminal ladder deliver signals
+ * through this single tolerance so they cannot drift apart.
+ * @param sandbox - Live SDK handle.
+ * @param envs - Control-shell environment entries.
+ * @param groups - Positive process-group ids to signal.
+ * @param signal - `TERM` or `KILL`.
+ */
+export declare function signalRemoteGroups(sandbox: Sandbox, envs: Record<string, string>, groups: readonly number[], signal: 'TERM' | 'KILL'): Promise<void>;
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/terminal.d.ts

@@ -0,0 +1,49 @@
+/** E2B PTY allocation and process-session ownership for the subprocess seam. */
+import { PassThrough } from 'node:stream';
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b';
+import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b';
+/** One E2B PTY and all process groups in its remote process session. */
+export declare class E2BTerminalHandle implements SubprocessTerminalHandle {
+    private readonly sandbox;
+    private readonly handle;
+    readonly output: PassThrough;
+    private readonly completion;
+    private readonly sessionId;
+    private readonly controlEnvs;
+    private readonly stateDir;
+    private readonly graceMs;
+    private readonly pollMs;
+    readonly pid: number;
+    readonly done: Promise<SubprocessOutcome>;
+    private topLevelExited;
+    private cleanup;
+    private readonly operationController;
+    private readonly operations;
+    private terminationSignal;
+    constructor(sandbox: Sandbox, handle: CommandHandle, output: PassThrough, completion: Promise<CommandResult>, sessionId: number, controlEnvs: Record<string, string>, stateDir: string, graceMs: number, pollMs: number);
+    /** @inheritdoc */
+    write(data: string): Promise<void>;
+    /** @inheritdoc */
+    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    /** @inheritdoc */
+    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
+    /** @inheritdoc */
+    terminate(): Promise<void>;
+    private inspectForegroundOnce;
+    private trackOperation;
+    private closeAfterOperations;
+    private waitForCommand;
+    private closeOnce;
+}
+/**
+ * Allocate an E2B PTY, replace its bootstrap shell with the requested argv,
+ * and return only after the private runner has published readiness.
+ * @param runtime - Shared E2B sandbox owner.
+ * @param spec - Fully specified terminal-process request.
+ * @param stateDir - Private remote directory for one startup transaction.
+ * @param pollMs - Remote session liveness poll cadence.
+ * @returns The live subprocess terminal handle.
+ */
+export declare function spawnE2BTerminal(runtime: E2BSandboxService, spec: SubprocessTerminalSpawnSpec, stateDir: string, pollMs: number): Promise<E2BTerminalHandle>;
+//# sourceMappingURL=terminal.d.ts.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-subprocess-e2b",
+  "description": "E2B subprocess implementation for DeepSeek Harness",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/e2b/subprocess-e2b"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-e2b": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}