@deepseek-ai/dsh-subprocess-local 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-local`.
+* @module @deepseek-ai/dsh-subprocess-local/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-subprocess-local";
+/** Cordis companion plugin name. */
+const name = "subprocess-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+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/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Local Service provider for the subprocess capability seam. Each spawn is a detached
+ * process tree with the spec's per-stream stdio dispositions; disposal
+ * terminates and joins live trees. It has no config: every disposition and
+ * limit arrives on the spec, so the deployment-varying choices stay with the
+ * caller's config (the bash executor's, the LSP host's, …).
+ * @module @deepseek-ai/dsh-subprocess-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess';
+import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { SpawnInternals } from './spawn.ts';
+import type { ProcessInspector } from './process-inspector.ts';
+/**
+ * Local subprocess service: detached process trees, Node-shaped stdio
+ * dispositions (raw pipes, inherit, bounded tail-keep collection with spill
+ * files), credential-scrubbed environment, and tree-scoped signalling with
+ * SIGTERM→grace→SIGKILL escalation.
+ */
+export declare class LocalSubprocessService extends SubprocessService {
+    /** Live handles retained only so disposal can terminate and join them. */
+    private live;
+    /** Live terminal sessions retained through whole-session quiescence. */
+    private terminals;
+    /** Test hook: spill and platform knobs forwarded to spawnSubprocess. */
+    internals: SpawnInternals;
+    /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
+    terminalInspector: ProcessInspector | undefined;
+    constructor(ctx: Context);
+    resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+    private executableCandidates;
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+export default LocalSubprocessService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-local`.
+ * @module @deepseek-ai/dsh-subprocess-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "subprocess-local-invariant";
+/** Service required before the companion can reserve 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/process-inspector.d.ts

@@ -0,0 +1,64 @@
+/** Platform process-table inspection for terminal readiness, signals, and teardown. */
+import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
+/** PID plus start identity, preventing teardown escalation after PID reuse. */
+export interface ProcessIdentity {
+    pid: number;
+    started: string;
+}
+/** Injectable OS process operations used by one local PTY session. */
+export interface ProcessInspector {
+    foregroundPgid(shellPid: number): number | undefined;
+    isStdinWaiting(pgid: number): boolean;
+    /** Return the root and its current transitive descendants, children first. */
+    processTree(rootPid: number): ProcessIdentity[];
+    /** Return current members of one POSIX process session when the platform exposes them. */
+    processSession(sessionId: number): ProcessIdentity[];
+    /** Return whether the exact identity remains a non-quiescent process. */
+    isAlive(identity: ProcessIdentity): boolean;
+    signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
+    signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+/** Testable boundary around filesystem, process-table, and signal syscalls. */
+export interface ProcessInspectorInternals {
+    readFile(path: string): string;
+    readDir(path: string): string[];
+    open(path: string): number;
+    read(fd: number, buffer: Buffer, length: number, position: number): number;
+    close(fd: number): void;
+    exec(file: string, args: string[]): string;
+    kill(pid: number, signal: NodeJS.Signals): void;
+}
+interface ProcStat {
+    pid: number;
+    parentPid: number;
+    pgrp: number;
+    session: number;
+    state: string;
+    tpgid: number;
+    started: string;
+}
+/**
+ * Parse fields used from Linux `/proc/<pid>/stat`, including parenthesized comm text.
+ * @param text - complete stat line.
+ * @returns Parsed identity/group fields, or undefined for malformed input.
+ */
+export declare function parseProcStat(text: string): ProcStat | undefined;
+/**
+ * Report whether a Linux process group has an executing member. `false`
+ * means the group contains only zombie/dead entries; `undefined` means the
+ * process table could not prove either outcome.
+ * @param processGroupId - POSIX process-group id to inspect.
+ * @param internals - injectable process-table operations.
+ * @returns Live-member presence, or `undefined` when unavailable/absent.
+ */
+export declare function linuxProcessGroupHasLiveMembers(processGroupId: number, internals?: ProcessInspectorInternals): boolean | undefined;
+/**
+ * Create the supported platform inspector or fail at plugin load.
+ * @param platform - target Node platform.
+ * @param arch - target CPU architecture for Linux syscall numbers.
+ * @param internals - filesystem/process boundary, injectable for deterministic tests.
+ * @returns Platform process inspector.
+ */
+export declare function createProcessInspector(platform?: NodeJS.Platform, arch?: NodeJS.Architecture, internals?: ProcessInspectorInternals): ProcessInspector;
+export {};
+//# sourceMappingURL=process-inspector.d.ts.map

package/lib/types/spawn.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Process plumbing for the local subprocess service: detached process-tree
+ * spawn with per-stream stdio dispositions, tail-keep collection with spill
+ * files, tree-scoped signalling (POSIX groups; Windows taskkill), and the
+ * SIGTERM→SIGKILL escalation. This layer reacts to an abort signal; callers
+ * own deadlines, teardown ladders, and cause classification.
+ * @module dsh-subprocess-local/spawn
+ */
+import type { CollectedOutput, SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Build a child environment: explicit caller entries override the scrubbed
+ * parent base using the target platform's environment-key semantics. A string
+ * deliberately restores or overrides an entry; an explicit `undefined`
+ * tombstone removes an ordinary ambient entry.
+ * @param extra - explicit caller entries and tombstones, merged after the scrub.
+ * @returns the environment to hand to `spawn` for the child process.
+ */
+export declare function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv;
+/** Injectable knobs so tests can exercise spill and platform behavior deterministically. */
+export interface SpawnInternals {
+    /** Directory for spill files (defaults to the OS temp dir). */
+    spillDir?: string;
+    /** Windows tree-termination runner (defaults to `taskkill /PID <pid> /T /F`). */
+    taskkill?: (pid: number) => void;
+    /** Host platform override for signalling decisions. */
+    platform?: NodeJS.Platform;
+    /** Linux process-group member probe (defaults to `/proc` inspection). */
+    linuxProcessGroupHasLiveMembers?: (processGroupId: number) => boolean | undefined;
+}
+/**
+ * Collects one stream with a bounded in-memory tail. With a spill cap, on
+ * first overflow a spill file is created and every chunk (including those
+ * already collected) is appended there while the full stream remains within
+ * the cap; without one, only the in-memory tail is ever retained (the
+ * diagnostic-tail shape — a language server's stderr).
+ *
+ * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
+ * end of command output; the spill file covers the head.
+ */
+export declare class OutputCollector {
+    private readonly maxBytes;
+    private readonly maxSpillBytes;
+    private readonly label;
+    private readonly spillDir;
+    private chunks;
+    private bytes;
+    private dropped;
+    private spillFd;
+    private spillFile;
+    private spillDisabled;
+    /** Total bytes ever pushed (not just retained). */
+    private total;
+    constructor(maxBytes: number, maxSpillBytes: number | undefined, label: string, spillDir: string);
+    /**
+     * Ingest one stream chunk, counting it toward the whole-stream total. On
+     * first overflow of the in-memory cap a spill file is opened (when spilling
+     * is enabled) and every chunk (already-collected ones included) is appended
+     * there from then on; the in-memory tail then drops whole chunks from its
+     * head (or the head of a single over-cap chunk) until it fits the cap again.
+     * @param chunk - the raw bytes from one stream 'data' event.
+     */
+    push(chunk: Buffer): void;
+    /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
+    private spillAll;
+    /** Stop spilling and remove the file once it can no longer hold the complete stream. */
+    private discardSpill;
+    /**
+     * Incremental read in whole-stream byte coordinates: returns everything
+     * pushed since `fromByte`. When `fromByte` has already slid out of the
+     * in-memory tail window, the read is `lossy` — it returns the whole
+     * retained tail and the gap is only recoverable from the spill file.
+     * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+     * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
+     */
+    readFrom(fromByte: number): {
+        text: string;
+        nextOffset: number;
+        lossy: boolean;
+        spillPath?: string;
+    };
+    /**
+     * Close the spill file once the stream has ended. A failed close (delayed
+     * writeback fault) stops advertising the spill path — the file may be
+     * missing its tail — while every in-memory read keeps working. Idempotent;
+     * the spawn path seals both collectors at settlement so reads after exit
+     * never point at a still-open file.
+     */
+    seal(): void;
+    /**
+     * Seal the spill file and return the final output.
+     * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
+     */
+    finalize(): CollectedOutput;
+}
+/**
+ * Send `sig` to a detached POSIX process group. Never throws: delivery races
+ * process exit and may run in a timer callback, so failures are contained and
+ * a non-positive pid is a no-op.
+ * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
+ * @param sig - the signal to deliver to the whole group.
+ */
+export declare function killGroup(pid: number, sig: NodeJS.Signals): void;
+/**
+ * Terminate one Windows process tree with `taskkill /T /F`. Contained like
+ * POSIX group signalling — delivery races tree exit, so an absent tree, a
+ * nonzero status, or a missing taskkill binary must not break idempotent
+ * teardown.
+ * @param pid - root process id; non-positive is a no-op.
+ */
+export declare function taskkillProcessTree(pid: number): void;
+/**
+ * Spawn one isolated detached process tree with the spec's per-stream stdio
+ * dispositions. Runtime exits resolve `done` as {@link SubprocessOutcome};
+ * only spawn failures reject.
+ * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
+ * @param internals - test-only spill-directory, platform, and taskkill overrides.
+ * @returns live subprocess handle.
+ * @throws when `graceMs` cannot be represented by one Node timer.
+ */
+export declare function spawnSubprocess(spec: SubprocessSpawnSpec, internals?: SpawnInternals): SubprocessHandle;
+//# sourceMappingURL=spawn.d.ts.map

package/lib/types/terminal.d.ts

@@ -0,0 +1,48 @@
+/** Local node-pty terminal-process implementation for the subprocess seam. */
+import { PassThrough } from 'node:stream';
+import type { IPty } from 'node-pty';
+import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
+import type { ProcessInspector } from './process-inspector.ts';
+/**
+ * A local terminal whose process-session ownership stays below the PTY backend.
+ * The seam's terminate() promise — no write, inspection, or signal in flight
+ * after settlement — holds here without operation tracking only because every
+ * handle call completes synchronously under the hood (node-pty write, ps-based
+ * inspection). A first genuinely asynchronous step in any handle call must add
+ * the tracking a remote provider needs.
+ */
+export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
+    private readonly terminal;
+    private readonly inspector;
+    private readonly graceMs;
+    readonly pid: number;
+    readonly output: PassThrough;
+    readonly done: Promise<SubprocessOutcome>;
+    private readonly outcome;
+    private readonly dataDisposable;
+    private readonly exitDisposable;
+    private cleanup;
+    private exited;
+    private trackedDescendants;
+    /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
+    private readonly rootIdentity;
+    /**
+     * @param terminal - allocated node-pty process.
+     * @param inspector - platform process/session operations.
+     * @param graceMs - TERM-to-KILL and exit-wait grace.
+     */
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number);
+    write(data: string): Promise<void>;
+    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
+    terminate(): Promise<void>;
+    private survivors;
+    private descendants;
+    private waitForMembers;
+    private signalMembers;
+    private unionMembers;
+    private stopDescendants;
+    private stopShell;
+    private closeOnce;
+}
+//# sourceMappingURL=terminal.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-subprocess-local",
+  "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/subprocess/subprocess-local"
+  },
+  "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",
+    "scripts/ensure-spawn-helper.mjs",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@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"
+  },
+  "scripts": {
+    "postinstall": "node scripts/ensure-spawn-helper.mjs"
+  }
+}

package/scripts/ensure-spawn-helper.mjs

@@ -0,0 +1,16 @@
+/** Restore the executable bit stripped from node-pty's prebuilt helper. */
+
+import { chmodSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const entry = fileURLToPath(import.meta.resolve('node-pty'))
+const packageRoot = dirname(dirname(entry))
+const candidates = [
+  join(packageRoot, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper'),
+  join(packageRoot, 'build', 'Release', 'spawn-helper'),
+]
+
+for (const helper of candidates) {
+  if (existsSync(helper)) chmodSync(helper, 0o755)
+}