@hasna-internal/kai-subprocess 0.1.1-rc.2 → 0.1.1-rc.3

package/README.md

@@ -1,31 +1,3 @@
 # @hasna-internal/kai-subprocess
 
-English | [中文](README.zh.md)
-
-The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessRuntime` exposes executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
-
-## Contract
-
-- `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- Spawn working directories and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
-- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the caller's config, not to a hidden subprocess-service default (the `dsh-shell` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
-- Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
-- Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches quiescence for every session member the provider can still observe and settles in-flight handle calls; providers document substrate-specific observability limits. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members; readiness, scrollback, and owner policy remain in the PTY consumer.
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
-- Disposal of the service terminates all still-running managed processes and awaits their exit.
-
-See the [subprocess subsystem page](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
-
-## Model Experience
-
-Indirectly, through Consumers (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
-
-#### KV Cache effect
-
-No direct invalidation; the named consumers own any request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **SDK-managed spawns remain outside** — an SDK transport that owns its internal spawn cannot route that call through this service; it can still import `scrubbedParentEnv` so environment policy stays single-sourced.
-- **Teardown ladders are consumer-owned** — the seam ships signalling verbs and the tree-liveness wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template).
+This package has been retired by its owner. This release is an empty placeholder with no dependencies or supported functionality. Do not use it.

package/index.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = {};

package/package.json

@@ -1,42 +1,16 @@
 {
   "name": "@hasna-internal/kai-subprocess",
-  "description": "Subprocess seam (ctx.subprocess) for the DeepSeek Harness — managed process groups, bounded spill-backed output, and escalated kills behind one abstract service",
-  "version": "0.1.1-rc.2",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/subprocess/subprocess"
-  },
-  "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"
-  },
+  "version": "0.1.1-rc.3",
+  "description": "Retired package. Empty placeholder with no dependencies.",
+  "main": "index.js",
   "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts"
+    "index.js",
+    "README.md"
   ],
   "license": "MIT",
-  "peerDependencies": {
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
-  "devDependencies": {
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+  "deprecated": "Retired by the package owner. Empty placeholder; do not use.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 DeepSeek
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.i18n.yaml

@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/subprocess/subprocess/README.md
-README.md: 5e80bc7205c2f06b3528bbcfcb775941d2fa4545
-README.zh.md: 4744b4aeea07e18a8d149865050f7487f8816061

package/README.zh.md

@@ -1,31 +0,0 @@
-# @hasna-internal/kai-subprocess
-
-[English](README.md) | 中文
-
-子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessRuntime` 公开可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.zh.md)。
-
-## 约定
-
-- `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方的配置，而不属于某个隐藏的子进程服务默认值（`dsh-shell` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
-- stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
-- 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；仍处于活动状态的传输若发生故障，会使 `done` 拒绝。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
-- 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
-
-参见[子进程子系统页面](../../../docs/subsystems/subprocess.zh.md)与[seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md)。
-
-## 模型体验
-
-通过 Consumer 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由 Consumer 负责。
-
-#### KV Cache 影响
-
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
-
-## 已知限制与暂缓事项
-
-- **由 SDK 管理的 spawn 仍在服务之外**：拥有内部 spawn 的 SDK 传输无法把该调用路由到本服务；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
-- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。

package/lib/index.js

@@ -1,85 +0,0 @@
-import { Service } from "@deepseek-ai/cordis";
-//#region lib/types/types.js
-/**
-* Vocabulary for the subprocess Service Definition: fully-specified spawn requests with
-* Node-shaped per-stream stdio modes, bounded collected output with spill
-* recovery, raw piped streams, and tree-scoped termination. Command
-* defaulting, shell semantics, protocol framing, and presentation belong to
-* consumers such as the bash executor seam.
-* @module dsh-subprocess/types
-*/
-/** Namespace prefix reserved for DeepSeek Harness-managed child environment facts. */
-const DSH_ENV_PREFIX = "DSH_";
-//#endregion
-//#region lib/types/index.js
-/**
-* Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup,
-* fully specified managed process trees with raw or
-* collected stdio, and one terminal-process primitive. Command defaulting,
-* shell semantics, deadlines, protocol framing, terminal readiness, and
-* presentation belong to consumers. The local implementation lives in
-* `@hasna-internal/kai-subprocess-local`.
-* @module @hasna-internal/kai-subprocess
-*/
-/**
-* Credential-shaped environment names are NOT forwarded to children (the
-* harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a spawned
-* process implicitly). One heuristic for every in-repo spawner; a
-* deliberately supplied entry survives because explicit env layers merge
-* after the scrub.
-*/
-const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i;
-/**
-* The ambient parent environment minus credential-shaped names and minus all
-* `DSH_*` names — the canonical base every harness child starts from. `PATH`,
-* `HOME`, locale, and proxy variables survive, so child CLIs run normally;
-* harness identity never leaks implicitly (a deliberately forwarded
-* credential or current `DSH_*` fact goes through the spec's explicit `env`,
-* which merges after this scrub). Both scrubs match case-insensitively:
-* Windows environment names are case-insensitive, so a parent `dsh_*` entry
-* would otherwise survive and read back as `$env:DSH_*` in the child;
-* deliberate lowercase `dsh_*` names on POSIX are implausible. Exported as a plain function so spawners
-* that cannot route through the service (node-pty backends, SDK-managed
-* transports) share the one scrub definition.
-* @returns a fresh environment object safe to hand to a child spawn.
-*/
-function scrubbedParentEnv() {
-	const env = {};
-	for (const [key, value] of Object.entries(process.env)) if (value !== void 0 && !SENSITIVE_ENV_PATTERN.test(key) && !key.toUpperCase().startsWith("DSH_")) env[key] = value;
-	return env;
-}
-/**
-* Abstract subprocess service. Subclass, implement {@link spawn}, and load the
-* subclass as a plugin — it registers as `ctx.subprocess` (one implementation
-* per context; loading a second throws, which is cordis' standard
-* duplicate-service behavior).
-*
-* Implementations must honor these semantics:
-* - Executable paths belong to one execution world shared with the mounted
-*   filesystem provider.
-* - {@link spawn} returns immediately with a live handle; `done` resolves at
-*   process close with exit facts and rejects only for spawn-level failures.
-* - Collect-mode readers are offset-based and non-consuming, so independent
-*   readers never consume one another's output; lossy reads report truncation
-*   and the spill file holding the complete stream when one exists. Piped
-*   streams are handed to the caller raw and never buffered here.
-* - {@link SubprocessHandle.terminate} (and the spec's abort signal) escalates
-*   SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every
-*   platform. {@link SubprocessHandle.waitForExit} observes whole-tree
-*   liveness, so a consumer-owned teardown ladder can hold each tier on real
-*   quiescence.
-* - Disposal of the service terminates all still-running managed processes
-*   and awaits their exit.
-* - {@link spawnTerminal} owns terminal allocation, text transport,
-*   foreground groups, signalling, and whole-session quiescence behind one
-*   awaited termination method; readiness and persistent-shell policy stay
-*   in the PTY consumer. Its output stream ends after queued terminal output
-*   when the top-level process exits.
-*/
-var SubprocessRuntime = class extends Service {
-	constructor(ctx) {
-		super(ctx, "subprocess");
-	}
-};
-//#endregion
-export { DSH_ENV_PREFIX, SENSITIVE_ENV_PATTERN, SubprocessRuntime, SubprocessRuntime as default, scrubbedParentEnv };

package/lib/invariant.js

@@ -1,17 +0,0 @@
-//#region lib/types/invariant.js
-/** Package-owned invariant companion for the subprocess seam. @module @hasna-internal/kai-subprocess/invariant */
-const PACKAGE_NAME = "@hasna-internal/kai-subprocess";
-/** Cordis companion plugin name. */
-const name = "subprocess-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/** No runtime invariant: this stateless Service Definition owns spawn-spec/handle types, while Service Providers own observations. */
-const install = () => {};
-/**
-* Register the subprocess 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

@@ -1,102 +0,0 @@
-/**
- * Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup,
- * fully specified managed process trees with raw or
- * collected stdio, and one terminal-process primitive. Command defaulting,
- * shell semantics, deadlines, protocol framing, terminal readiness, and
- * presentation belong to consumers. The local implementation lives in
- * `@hasna-internal/kai-subprocess-local`.
- * @module @hasna-internal/kai-subprocess
- */
-import { Context, Service } from '@deepseek-ai/cordis';
-import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts';
-import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts';
-export { DSH_ENV_PREFIX } from './types.ts';
-export type { CollectedOutput, DshEnvironment, DshEnvironmentKey, SubprocessCollect, SubprocessCollectedOutputs, SubprocessHandle, SubprocessOutcome, SubprocessOutputMode, SubprocessOutputRead, SubprocessOutputReader, SubprocessSpawnSpec, SubprocessStdinMode, SubprocessStdio, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal, SubprocessTerminalSpawnSpec, } from './types.ts';
-/**
- * Credential-shaped environment names are NOT forwarded to children (the
- * harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a spawned
- * process implicitly). One heuristic for every in-repo spawner; a
- * deliberately supplied entry survives because explicit env layers merge
- * after the scrub.
- */
-export declare const SENSITIVE_ENV_PATTERN: RegExp;
-/**
- * The ambient parent environment minus credential-shaped names and minus all
- * `DSH_*` names — the canonical base every harness child starts from. `PATH`,
- * `HOME`, locale, and proxy variables survive, so child CLIs run normally;
- * harness identity never leaks implicitly (a deliberately forwarded
- * credential or current `DSH_*` fact goes through the spec's explicit `env`,
- * which merges after this scrub). Both scrubs match case-insensitively:
- * Windows environment names are case-insensitive, so a parent `dsh_*` entry
- * would otherwise survive and read back as `$env:DSH_*` in the child;
- * deliberate lowercase `dsh_*` names on POSIX are implausible. Exported as a plain function so spawners
- * that cannot route through the service (node-pty backends, SDK-managed
- * transports) share the one scrub definition.
- * @returns a fresh environment object safe to hand to a child spawn.
- */
-export declare function scrubbedParentEnv(): Record<string, string>;
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        subprocess: SubprocessRuntime;
-    }
-}
-/**
- * Abstract subprocess service. Subclass, implement {@link spawn}, and load the
- * subclass as a plugin — it registers as `ctx.subprocess` (one implementation
- * per context; loading a second throws, which is cordis' standard
- * duplicate-service behavior).
- *
- * Implementations must honor these semantics:
- * - Executable paths belong to one execution world shared with the mounted
- *   filesystem provider.
- * - {@link spawn} returns immediately with a live handle; `done` resolves at
- *   process close with exit facts and rejects only for spawn-level failures.
- * - Collect-mode readers are offset-based and non-consuming, so independent
- *   readers never consume one another's output; lossy reads report truncation
- *   and the spill file holding the complete stream when one exists. Piped
- *   streams are handed to the caller raw and never buffered here.
- * - {@link SubprocessHandle.terminate} (and the spec's abort signal) escalates
- *   SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every
- *   platform. {@link SubprocessHandle.waitForExit} observes whole-tree
- *   liveness, so a consumer-owned teardown ladder can hold each tier on real
- *   quiescence.
- * - Disposal of the service terminates all still-running managed processes
- *   and awaits their exit.
- * - {@link spawnTerminal} owns terminal allocation, text transport,
- *   foreground groups, signalling, and whole-session quiescence behind one
- *   awaited termination method; readiness and persistent-shell policy stay
- *   in the PTY consumer. Its output stream ends after queued terminal output
- *   when the top-level process exits.
- */
-export declare abstract class SubprocessRuntime extends Service {
-    constructor(ctx: Context);
-    /**
-     * Resolve one configured executable in this provider's execution world.
-     * Absolute paths are verified; bare names use the provider's scrubbed PATH
-     * plus explicit environment overrides. Relative paths containing separators
-     * are rejected: the resolution base is undefined, so providers fail loud
-     * instead of guessing.
-     * @param command - absolute executable path or bare PATH name.
-     * @param env - explicit environment entries used for lookup.
-     * @param signal - aborts remote or local lookup.
-     * @returns a canonical executable path.
-     */
-    abstract resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
-    /**
-     * Start one managed child process from a fully-specified spec; this seam
-     * applies no defaults.
-     * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
-     * @returns the live process handle (streams/readers, signalling, outcome promise).
-     */
-    abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
-    /**
-     * Allocate a real terminal and start one owned process session. This is the
-     * only non-pipe process primitive: implementations own terminal byte I/O,
-     * foreground groups, signals, and complete session-tree cleanup.
-     * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
-     * @returns the live terminal handle after allocation succeeds.
-     */
-    abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
-}
-export default SubprocessRuntime;
-//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -1,13 +0,0 @@
-/** Package-owned invariant companion for the subprocess seam. @module @hasna-internal/kai-subprocess/invariant */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "subprocess-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register the subprocess 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/types.d.ts

@@ -1,248 +0,0 @@
-/**
- * Vocabulary for the subprocess Service Definition: fully-specified spawn requests with
- * Node-shaped per-stream stdio modes, bounded collected output with spill
- * recovery, raw piped streams, and tree-scoped termination. Command
- * defaulting, shell semantics, protocol framing, and presentation belong to
- * consumers such as the bash executor seam.
- * @module dsh-subprocess/types
- */
-import type { Readable, Writable } from 'node:stream';
-/** Namespace prefix reserved for DeepSeek Harness-managed child environment facts. */
-export declare const DSH_ENV_PREFIX: "DSH_";
-/** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
-export type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`;
-/** Trusted DeepSeek Harness variables for one child-process execution. */
-export type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>;
-/** One captured stream: the (possibly truncated) text plus recovery info. */
-export interface CollectedOutput {
-    /** Collected text — the TAIL of the stream when truncated. */
-    text: string;
-    /** True when bytes were dropped from `text`. */
-    truncated: boolean;
-    /** Path to a file holding the COMPLETE stream, when truncated and available. */
-    spillPath?: string;
-}
-/**
- * stdin disposition. `'ignore'` leaves fd 0 on `/dev/null`; `'pipe'` exposes
- * {@link SubprocessHandle.stdin} for the caller's ongoing protocol writes;
- * `{ data }` writes the bytes and closes (the batch shape).
- */
-export type SubprocessStdinMode = 'ignore' | 'pipe' | {
-    readonly data: string;
-};
-/**
- * Bounded in-memory collection for one output stream, with an optional
- * full-stream spill file. Omitting `spill` keeps only the in-memory tail —
- * the diagnostic-tail shape (a language server's stderr); including it makes
- * the complete stream recoverable up to its cap (the bash tool shape).
- */
-export interface SubprocessCollect {
-    /** In-memory cap in bytes; overflow keeps the TAIL. */
-    maxBytes: number;
-    /** Full-stream spill file; absent disables spilling entirely. */
-    spill?: {
-        /** Whole-stream byte cap; a larger stream discards its now-incomplete spill. */
-        maxBytes: number;
-    };
-}
-/**
- * stdout/stderr disposition. `'pipe'` exposes the raw `Readable` for the
- * caller's protocol decoding; `'inherit'` passes the parent's descriptor
- * through (child diagnostics land on the harness's own stream); a
- * {@link SubprocessCollect} object buffers boundedly with offset-based reads.
- */
-export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;
-/** Per-stream stdio dispositions, all explicit — this seam applies no defaults. */
-export interface SubprocessStdio {
-    stdin: SubprocessStdinMode;
-    stdout: SubprocessOutputMode;
-    stderr: SubprocessOutputMode;
-}
-/**
- * A fully-specified spawn request. This seam applies no defaults: every
- * disposition, limit, and directory is explicit, so the caller's own config —
- * not a hidden subprocess-service default — decides them (the `dsh-shell`
- * request/spec split is the owning template).
- */
-export interface SubprocessSpawnSpec {
-    /** Executable and arguments; `argv[0]` is the program. Never shell-interpreted here. */
-    argv: readonly string[];
-    /** Working directory for the child. */
-    cwd: string;
-    /** Per-stream stdio dispositions. */
-    stdio: SubprocessStdio;
-    /**
-     * Positive finite grace period in milliseconds, no greater than
-     * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
-     * and for draining still-open collected pipes after the process exits (an
-     * inherited descriptor held by a surviving descendant cannot hold the
-     * outcome open indefinitely).
-     */
-    graceMs: number;
-    /**
-     * Abort signal — starts the terminate escalation on the process tree when
-     * it fires. The caller owns deadlines and cause classification; this seam
-     * only reacts to the abort.
-     */
-    signal?: AbortSignal | undefined;
-    /**
-     * Explicit environment entries merged onto the implementation's scrubbed
-     * parent base (see `scrubbedParentEnv`), with no namespace validation. A
-     * string is a deliberate caller opt-in, so a forwarded credential-shaped
-     * entry or current `DSH_*` fact survives the scrub; `undefined` is a
-     * tombstone that removes an ordinary ambient entry from the child.
-     */
-    env?: NodeJS.ProcessEnv | undefined;
-}
-/**
- * Exit facts of one closed process — Node's `close`-event vocabulary.
- * Deliberately carries NO timeout or cancellation classification (the caller
- * reads the signal it owns to classify causes) and NO output: collected
- * streams stay readable through {@link SubprocessHandle.collected} after
- * settlement, so batch and streaming callers share one access path.
- */
-export interface SubprocessOutcome {
-    /** Exit code; null when the process died from a signal. */
-    exitCode: number | null;
-    /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
-    signal: NodeJS.Signals | null;
-}
-/** One incremental {@link SubprocessOutputReader.readFrom} read. */
-export interface SubprocessOutputRead {
-    /** Stream text from the requested offset (the whole retained tail when lossy). */
-    text: string;
-    /** Whole-stream offset to resume from on the next read. */
-    nextOffset: number;
-    /** True when the requested offset slid out of the in-memory tail window. */
-    lossy: boolean;
-    /** Path to the full-stream spill file, when one was created and remains intact. */
-    spillPath?: string;
-}
-/**
- * Cursor-free incremental access to one collected output stream. Offsets are
- * whole-stream byte coordinates owned by the caller, so independent readers
- * cannot consume one another's output; `readFrom(0)` after settlement is the
- * batch result (`lossy` then means the in-memory tail lost its head — the
- * {@link CollectedOutput.truncated} fact).
- */
-export interface SubprocessOutputReader {
-    /**
-     * Read everything captured since `fromByte`. When that offset has 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 next offset, the `lossy` flag, and the spill path when one exists.
-     */
-    readFrom(fromByte: number): SubprocessOutputRead;
-}
-/** Offset-based readers for the streams spawned in collect mode. */
-export interface SubprocessCollectedOutputs {
-    /** Present iff stdout is a {@link SubprocessCollect}. */
-    readonly stdout?: SubprocessOutputReader;
-    /** Present iff stderr is a {@link SubprocessCollect}. */
-    readonly stderr?: SubprocessOutputReader;
-}
-/**
- * A live child process rooted in its own process tree. Collected output
- * remains readable after exit; piped streams belong to the caller.
- *
- * Termination is tree-scoped everywhere: POSIX signals the detached process
- * group (falling back to the direct child when the group is gone), Windows
- * terminates the tree via `taskkill /T`, so helper processes cannot outlive
- * the handle unnoticed.
- */
-export interface SubprocessHandle {
-    /** Process id (tree root); -1 when the spawn itself failed. */
-    readonly pid: number;
-    /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */
-    readonly stdin: Writable | undefined;
-    /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */
-    readonly stdout: Readable | undefined;
-    /** The child's raw stderr, present iff spawned with `stderr: 'pipe'`. */
-    readonly stderr: Readable | undefined;
-    /** Offset-based readers for collect-mode streams (also readable after exit). */
-    readonly collected: SubprocessCollectedOutputs;
-    /** Resolves at process close with exit facts; rejects only for spawn-level failures. */
-    readonly done: Promise<SubprocessOutcome>;
-    /**
-     * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree
-     * (Windows force-terminates immediately) — the seam's only termination
-     * verb. Idempotent, a no-op once the tree is gone (the pid may be reused),
-     * and also triggered by the spec's abort signal.
-     */
-    terminate(): void;
-    /**
-     * Wait until the process tree has exited — the tree, not just the direct
-     * child, so a still-running helper is observable before teardown returns.
-     * @param signal - optional bound for the wait.
-     * @returns `true` when the tree exited, `false` when the signal aborted first.
-     */
-    waitForExit(signal?: AbortSignal): Promise<boolean>;
-}
-/**
- * Signals supported by the terminal-process primitive. Kept member-identical
- * to `TerminalSignal` in `@hasna-internal/kai-terminal` without a cross-seam dependency;
- * change both together.
- */
-export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';
-/** A fully specified terminal-process spawn. */
-export interface SubprocessTerminalSpawnSpec {
-    /** Executable and arguments; `argv[0]` is the program. */
-    argv: readonly string[];
-    /** Working directory in this subprocess provider's execution world. */
-    cwd: string;
-    /** Explicit environment layered after the provider's ambient scrub. */
-    env?: Record<string, string> | undefined;
-    /** Initial terminal row count. */
-    rows: number;
-    /** Initial terminal column count. */
-    cols: number;
-    /** TERM-to-KILL cleanup grace for the complete terminal session. */
-    graceMs: number;
-    /** Cancellation of terminal allocation; a published handle owns its later lifetime. */
-    signal?: AbortSignal | undefined;
-}
-/** Current foreground process-group facts for one terminal. */
-export interface SubprocessTerminalForeground {
-    /** Foreground process-group id published by the terminal driver. */
-    processGroupId: number;
-    /** Whether the provider can currently prove that group is waiting on terminal input. */
-    inputWaiting: boolean;
-}
-/**
- * One live terminal process and its owned OS session. Terminal allocation,
- * foreground-group inspection/signalling, and session-tree cleanup are one
- * deep subprocess primitive because none can be reconstructed from ordinary
- * piped stdio without substrate-specific process control.
- */
-export interface SubprocessTerminalHandle {
-    /** Top-level terminal process id. */
-    readonly pid: number;
-    /** UTF-8 terminal output bytes in delivery order; ends after queued output when the terminal exits. */
-    readonly output: Readable;
-    /** Resolves when the top-level process exits; rejects only for a live transport failure. */
-    readonly done: Promise<SubprocessOutcome>;
-    /**
-     * Write text to the terminal input.
-     * @param data - text to deliver without implicit newline conversion.
-     */
-    write(data: string): Promise<void>;
-    /**
-     * Inspect the current foreground process group.
-     * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
-     */
-    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
-    /**
-     * Deliver a signal to the current foreground process group.
-     * @param signal - permitted terminal signal.
-     * @returns the exact group id that received it.
-     */
-    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
-    /**
-     * Idempotently terminate every terminal-session member the provider can still observe and await quiescence.
-     * After settlement, no write, inspection, or signal call remains in flight.
-     * Providers document substrate-specific observability limits.
-     */
-    terminate(): Promise<void>;
-}
-//# sourceMappingURL=types.d.ts.map