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

package/README.md

@@ -1,53 +1,3 @@
 # @hasna-internal/kai-shell
 
-English | [中文](README.zh.md)
-
-The **`ShellExecutor`** (`ctx.shell`) defines WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Job ids, ownership, collection, cancellation, and notices belong to the generic `ctx.jobs` runtime.
-
-This package owns the Service Definition role of the bash capability, split so each role can evolve (and be swapped) independently:
-
-| Package | Role |
-|---|---|
-| `@hasna-internal/kai-shell` (this) | Service Definition: abstract service + vocabulary types |
-| `@hasna-internal/kai-bash-local` | Service Provider: local subprocesses |
-| `@hasna-internal/kai-bash-sandbox` | Service Provider: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
-| `@hasna-internal/kai-tool-bash` | the model-facing tool schemas over `ctx.shell` |
-
-The split is a standard capability seam ([capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): `dsh-bash-sandbox` is a sandboxing executor behind the same Service Definition — the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider — and a containerized or remote executor slots in the same way.
-
-## Service API (`ctx.shell`)
-
-| Member | Semantics |
-|---|---|
-| `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `ShellRunResult`. |
-| `start(spec)` | Background execution. Returns a task-free `ShellProcess` handle immediately; **no timeout applies**. The caller may adapt it into `ctx.jobs`. |
-| `sandboxMode` | The capability fact for the tool layer: the default mode a SANDBOXING executor confines under (`undefined` in the base class — "this executor does not sandbox"). `dsh-tool-bash` reads it at registration to advertise the escalation fields only when the composition honors them. |
-| `ShellProcess.readOutput()` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. |
-| `ShellProcess.kill()` | Kill the process group. Returns `false` when it already finished. |
-
-Implementations subclass `ShellExecutor` and implement the abstract methods. Disposal must kill every running process and await its exit.
-
-`SHELL_SETTINGS_NAMESPACE` (`bash`) is exported here rather than by a provider because it names the capability, not an implementation. A host composes exactly one provider of `ctx.shell` — the win32 layer swaps the POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate service registration — so every provider can register this one namespace with its own schema and composition entry without two of them ever colliding, and a `settings.yaml` carried between platforms keeps resolving on both.
-
-## Vocabulary
-
-`ShellExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, dshEnv?, sandboxPolicy?) resolves to `ShellExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, dshEnv?, sandboxPolicy) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxPolicy` is optional on the request and required-but-nullable on the resolved spec: it carries the complete per-call mode and workspace root. The sandbox tool path resolves it from the calling session through `ctx.sandboxPolicy`; a direct sandbox-executor caller falls back to deployment policy, while a non-sandboxing executor carries the field and confines nothing.
-
-The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@hasna-internal/kai-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `ShellRunResult`; `start()` returns `ShellProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `ShellSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [subsystems/shell.md](../../../docs/subsystems/shell.md).
-
-`stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.shellEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
-
-The exported `parseExitStatus` (with `ParsedExitStatus`) is the shared rendering contract half of the shell tools: the inverse of the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append. Both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill; it lives with the Service Definition so the two tools never drift on the marker contract.
-
-## Model Experience
-
-Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox facts into guidance and retained tool-result tokens.
-
-#### KV Cache effect
-
-No direct invalidation; the named consumer owns any request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **No interactive-input vocabulary** — `stdin` is written once at spawn and closed; the seam has no channel to feed a running task and no PTY session concept.
-- **Foreground timeouts are always executor-owned** — a caller-owned-deadline mode on the seam is explicitly deferred by [the tool-call timeout-policy Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
+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,48 +1,16 @@
 {
   "name": "@hasna-internal/kai-shell",
-  "description": "Abstract bash executor seam (ctx.shell) for the DeepSeek Harness",
-  "version": "0.1.1-rc.2",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/shell/shell"
-  },
-  "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",
-    "@hasna-internal/kai-subprocess": "^0.1.1-rc.2",
-    "@hasna-internal/kai-settings": "^0.1.1-rc.2",
-    "@hasna-internal/kai-sandbox": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
-  "devDependencies": {
-    "@hasna-internal/kai-sandbox": "^0.1.1-rc.2",
-    "@hasna-internal/kai-subprocess": "^0.1.1-rc.2",
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@hasna-internal/kai-settings": "^0.1.1-rc.2"
+  "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/shell/shell/README.md
-README.md: a15980ead797a73c18dd6d8825a4b38cf845df60
-README.zh.md: 008b19835697d5d9514cf5472696852cfc684acd

package/README.zh.md

@@ -1,53 +0,0 @@
-# @hasna-internal/kai-shell
-
-[English](README.md) | 中文
-
-**`ShellExecutor`**（`ctx.shell`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。job id、所有权、收集、取消与通知属于通用 `ctx.jobs` 运行时。
-
-本包承担 bash 能力的 Service Definition 角色，各角色因此可以独立演进（和替换）：
-
-| 包 | 职责 |
-|---|---|
-| `@hasna-internal/kai-shell`（本包） | Service Definition：抽象服务 + 词汇类型 |
-| `@hasna-internal/kai-bash-local` | Service Provider：本地子进程 |
-| `@hasna-internal/kai-bash-sandbox` | Service Provider：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
-| `@hasna-internal/kai-tool-bash` | 基于 `ctx.shell`、面向模型的工具 schema |
-
-该拆分是一个标准的能力 seam（[capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)）：`dsh-bash-sandbox` 是位于同一 Service Definition 之后的沙箱执行器——Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方——容器化或远程执行器也可以同样接入。
-
-## 服务 API（`ctx.shell`）
-
-| 成员 | 语义 |
-|---|---|
-| `run(spec)` | 前台执行。命令完成时 resolve。**只会因基础设施失败而 reject**（工作目录不可用、shell 缺失、信号已在调用前中止）；非零退出、超时终止和中止导致的终止都会 resolve 为描述性 `ShellRunResult`。 |
-| `start(spec)` | 后台执行。立即返回不含任务语义的 `ShellProcess` 句柄；**不应用超时**。调用方可以将其适配到 `ctx.jobs`。 |
-| `sandboxMode` | 工具层的能力事实：沙箱执行器用于限制执行的默认模式（基类中为 `undefined`，即「此执行器不使用沙箱」）。`dsh-tool-bash` 会在注册时读取它，仅当组合确实支持升权字段时才公布这些字段。 |
-| `ShellProcess.readOutput()` | **增量** 读取输出：连续读取绝不会重复交付。因缓冲区容量限制而丢失数据的读取会标记 `lossy`，并指向完整流 spill 文件。 |
-| `ShellProcess.kill()` | 终止进程组。如果进程已结束，返回 `false`。 |
-
-实现会继承 `ShellExecutor` 并实现抽象方法。dispose（资源释放）必须终止每个运行中的进程并等待其退出。
-
-`SHELL_SETTINGS_NAMESPACE`（`bash`）由此处导出而非由某个提供方导出，因为它命名的是能力而不是实现。一个宿主只组装一个 `ctx.shell` 提供方——win32 层会把 POSIX 行换成 pwsh 行，同时挂载两者会因服务重复注册而在加载期失败——所以每个提供方都能用自己的 schema 与组装条目注册这同一个命名空间，两者永不相撞；在平台间携带的 `settings.yaml` 也能在两边继续解析。
-
-## 词汇
-
-`ShellExecRequest`（command、workdir?、timeoutMs?、stdoutMaxBytes?、signal?、stdin?、env?、dshEnv?、sandboxPolicy?）在执行前解析为 `ShellExecSpec`（command、workdir、timeoutMs、stdoutMaxBytes、signal?、stdin?、env?、dshEnv?、sandboxPolicy）。`stdoutMaxBytes` 是受信任前台运行的捕获预算，用于必须解析完整有界 stdout 的消费方；面向模型的 bash 工具不公开该字段。`sandboxPolicy` 在请求上可选，在已解析 spec 上必填但可为 null：它携带完整的每次调用模式与工作区根目录。沙箱工具路径通过 `ctx.sandboxPolicy` 从调用会话解析它；沙箱执行器的直接调用方回退到部署策略，非沙箱执行器则携带该字段但不作限制。
-
-每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@hasna-internal/kai-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `ShellRunResult`；`start()` 返回 `ShellProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `ShellSandboxInfo`。详见 `src/types.ts` 与 [subsystems/shell.md](../../../docs/subsystems/shell.zh.md)。
-
-`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.shellEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md)。
-
-导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的另一半：`dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 追加的 `[exit code: N]`／`[killed by signal: X]` marker 的逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与其退出状态 pill；它放在 Service Definition 中，两个工具便永远不会在 marker 约定上漂移。
-
-## 模型体验
-
-通过 `dsh-tool-bash` 间接影响；该工具会将执行器输出与沙箱事实转为指引和保留的工具结果 token。
-
-#### KV Cache 影响
-
-不会直接导致 KV Cache 失效；请求前缀变更由具名消费方负责。
-
-## 已知限制与暂缓事项
-
-- **没有交互式输入词汇**：`stdin` 只会在 spawn 时写入一次并关闭；seam 不提供向运行中任务继续输入的通道，也没有 PTY 会话概念。
-- **前台超时始终由执行器负责**：seam 上由调用方负责 deadline 的模式已由 [工具调用超时策略 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md) 明确暂缓。

package/lib/index.js

@@ -1,96 +0,0 @@
-import { Service } from "@deepseek-ai/cordis";
-import { settingsNamespace } from "@hasna-internal/kai-settings";
-import { DSH_ENV_PREFIX } from "@hasna-internal/kai-subprocess";
-//#region lib/types/render.js
-/**
-* Shared rendering helpers for the shell tools (`dsh-tool-bash`,
-* `dsh-tool-pwsh`): the exit-status marker contract the tools' renderers
-* emit and the presentation layer parses back.
-* @module @hasna-internal/kai-shell/render
-*/
-/**
-* Split a rendered shell-tool result string into its output body and the
-* structured exit status — the inverse of the `[exit code: N]` /
-* `[killed by signal: X]` markers the shell tools' renderers append. A killed
-* marker yields `signal`; otherwise a non-zero marker yields `exitCode`;
-* absent both means a clean exit 0.
-*
-* The consumed marker is removed from `body` because a terminal presentation
-* shows the exit status as its own pill: leaving the marker in the output
-* would render the exit twice. Other markers (timeout, sandbox denial) carry
-* facts no pill shows, so they stay in the body.
-*
-* Replay only retains the rendered content text, not the original
-* `ShellRunResult`, so terminal presentation must recover the exit pill here.
-* Requiring a leading newline and the end of the string keeps ordinary output
-* that merely ends with marker-like text from matching unless the final line
-* is indistinguishable from a real marker.
-* @param text - rendered model-facing shell-tool result.
-* @returns the marker-free body plus the recovered terminal exit code or signal.
-*/
-function parseExitStatus(text) {
-	const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text);
-	if (signal?.[1] !== void 0) return {
-		body: text.slice(0, signal.index),
-		signal: signal[1]
-	};
-	const exit = /\n\[exit code: (\d+)\]$/.exec(text);
-	if (exit?.[1] !== void 0) return {
-		body: text.slice(0, exit.index),
-		exitCode: Number(exit[1])
-	};
-	return {
-		body: text,
-		exitCode: 0
-	};
-}
-//#endregion
-//#region lib/types/index.js
-/**
-* Service Definition for the `ctx.shell` capability seam, covering foreground commands and background process
-* handles. Job ids, ownership, polling, and notices belong to
-* `@hasna-internal/kai-jobs`, keeping executors independent of sessions.
-* @module @hasna-internal/kai-shell
-*/
-/**
-* Settings namespace of this capability, owned here rather than by either
-* executor family because it names the capability, not an implementation: a
-* host composes exactly one provider of `ctx.shell` (the win32 layer swaps the
-* POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate
-* service registration), so the providers share one namespace without ever
-* registering it twice, and a settings document carried between platforms
-* keeps resolving on both.
-*/
-const SHELL_SETTINGS_NAMESPACE = settingsNamespace("shell");
-/**
-* Abstract bash execution service. Subclass, implement the abstract methods,
-* and load the subclass as a plugin — it registers as `ctx.shell` (one
-* implementation per context; loading a second throws, which is cordis'
-* standard duplicate-service behavior).
-*
-* Implementations must honor these semantics:
-* - {@link run} rejects only for infrastructure failures. Nonzero exits,
-*   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
-* - {@link start} returns immediately; no timeout applies to background
-*   processes. `done` settles at process close and never rejects; spawn
-*   failures settle as `killed` with the error on stderr.
-* - {@link ShellProcess.readOutput} is incremental: consecutive reads never
-*   repeat output. Lossy reads report truncation and available spill files.
-* - A still-running background process is stopped and awaited when its
-*   owning composition tears down. With the subprocess seam that
-*   boundary is `ctx.subprocess` disposal, so a background process survives
-*   an executor-only reload.
-*/
-var ShellExecutor = class extends Service {
-	constructor(ctx) {
-		super(ctx, "shell");
-	}
-	/**
-	* The sandbox mode this executor applies by default, or `undefined` when it
-	* does not sandbox commands.
-	* @returns the configured default sandbox mode, when supported.
-	*/
-	get sandboxMode() {}
-};
-//#endregion
-export { DSH_ENV_PREFIX, SHELL_SETTINGS_NAMESPACE, ShellExecutor, ShellExecutor as default, parseExitStatus };

package/lib/invariant.js

@@ -1,17 +0,0 @@
-//#region lib/types/invariant.js
-/** Package-owned invariant companion for the bash seam. @module @hasna-internal/kai-shell/invariant */
-const PACKAGE_NAME = "@hasna-internal/kai-shell";
-/** Cordis companion plugin name. */
-const name = "shell-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/** No runtime invariant: this stateless Service Definition owns request/result types, while executors and policy own observations. */
-const install = () => {};
-/**
-* Register the bash 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,78 +0,0 @@
-/**
- * Service Definition for the `ctx.shell` capability seam, covering foreground commands and background process
- * handles. Job ids, ownership, polling, and notices belong to
- * `@hasna-internal/kai-jobs`, keeping executors independent of sessions.
- * @module @hasna-internal/kai-shell
- */
-import { Context, Service } from '@deepseek-ai/cordis';
-import type { SandboxMode } from '@hasna-internal/kai-sandbox';
-import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from './types.ts';
-/**
- * Settings namespace of this capability, owned here rather than by either
- * executor family because it names the capability, not an implementation: a
- * host composes exactly one provider of `ctx.shell` (the win32 layer swaps the
- * POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate
- * service registration), so the providers share one namespace without ever
- * registering it twice, and a settings document carried between platforms
- * keeps resolving on both.
- */
-export declare const SHELL_SETTINGS_NAMESPACE: import("@hasna-internal/kai-settings").SettingsNamespace;
-export { DSH_ENV_PREFIX } from './types.ts';
-export type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellProcessStatus, ShellRunResult, ShellSandboxInfo, CollectedOutput, DshEnvironment, DshEnvironmentKey, } from './types.ts';
-export { parseExitStatus } from './render.ts';
-export type { ParsedExitStatus } from './render.ts';
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        shell: ShellExecutor;
-    }
-}
-/**
- * Abstract bash execution service. Subclass, implement the abstract methods,
- * and load the subclass as a plugin — it registers as `ctx.shell` (one
- * implementation per context; loading a second throws, which is cordis'
- * standard duplicate-service behavior).
- *
- * Implementations must honor these semantics:
- * - {@link run} rejects only for infrastructure failures. Nonzero exits,
- *   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
- * - {@link start} returns immediately; no timeout applies to background
- *   processes. `done` settles at process close and never rejects; spawn
- *   failures settle as `killed` with the error on stderr.
- * - {@link ShellProcess.readOutput} is incremental: consecutive reads never
- *   repeat output. Lossy reads report truncation and available spill files.
- * - A still-running background process is stopped and awaited when its
- *   owning composition tears down. With the subprocess seam that
- *   boundary is `ctx.subprocess` disposal, so a background process survives
- *   an executor-only reload.
- */
-export declare abstract class ShellExecutor extends Service {
-    constructor(ctx: Context);
-    /**
-     * The sandbox mode this executor applies by default, or `undefined` when it
-     * does not sandbox commands.
-     * @returns the configured default sandbox mode, when supported.
-     */
-    get sandboxMode(): SandboxMode | undefined;
-    /**
-     * Apply implementation-owned defaults and caps to a request before execution.
-     * @param request - the caller's request; omitted fields get this
-     *   implementation's defaults, capped fields are clamped.
-     * @returns the fully-specified spec to hand to {@link run}/{@link start}.
-     */
-    abstract resolve(request: ShellExecRequest): ShellExecSpec;
-    /**
-     * Run a command in the foreground; resolves when it finishes.
-     * @param spec - a resolved spec from {@link resolve}, never a raw request.
-     * @returns the outcome; nonzero exits, timeout kills, and abort kills
-     *   resolve with a descriptive result rather than reject.
-     */
-    abstract run(spec: ShellExecSpec): Promise<ShellRunResult>;
-    /**
-     * Start a background process and return its handle immediately.
-     * @param spec - a resolved spec from {@link resolve}, never a raw request.
-     * @returns the live process handle (reads, kill, quiescence promise).
-     */
-    abstract start(spec: ShellExecSpec): ShellProcess;
-}
-export default ShellExecutor;
-//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

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

@@ -1,39 +0,0 @@
-/**
- * Shared rendering helpers for the shell tools (`dsh-tool-bash`,
- * `dsh-tool-pwsh`): the exit-status marker contract the tools' renderers
- * emit and the presentation layer parses back.
- * @module @hasna-internal/kai-shell/render
- */
-/**
- * The exit status recovered from a rendered result, with the output body that
- * status was split off from.
- */
-export type ParsedExitStatus = {
-    body: string;
-} & ({
-    exitCode: number;
-} | {
-    signal: string;
-});
-/**
- * Split a rendered shell-tool result string into its output body and the
- * structured exit status — the inverse of the `[exit code: N]` /
- * `[killed by signal: X]` markers the shell tools' renderers append. A killed
- * marker yields `signal`; otherwise a non-zero marker yields `exitCode`;
- * absent both means a clean exit 0.
- *
- * The consumed marker is removed from `body` because a terminal presentation
- * shows the exit status as its own pill: leaving the marker in the output
- * would render the exit twice. Other markers (timeout, sandbox denial) carry
- * facts no pill shows, so they stay in the body.
- *
- * Replay only retains the rendered content text, not the original
- * `ShellRunResult`, so terminal presentation must recover the exit pill here.
- * Requiring a leading newline and the end of the string keeps ordinary output
- * that merely ends with marker-like text from matching unless the final line
- * is indistinguishable from a real marker.
- * @param text - rendered model-facing shell-tool result.
- * @returns the marker-free body plus the recovered terminal exit code or signal.
- */
-export declare function parseExitStatus(text: string): ParsedExitStatus;
-//# sourceMappingURL=render.d.ts.map

package/lib/types/types.d.ts

@@ -1,175 +0,0 @@
-/**
- * Execution types for the bash executor seam. Background job semantics belong
- * to `@hasna-internal/kai-jobs`; this seam exposes only process handles. The
- * managed-environment and captured-output vocabulary is owned by the
- * subprocess seam and re-exported here so bash consumers keep one import
- * root.
- * @module dsh-shell/types
- */
-import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@hasna-internal/kai-sandbox';
-import type { CollectedOutput, DshEnvironment } from '@hasna-internal/kai-subprocess';
-export { DSH_ENV_PREFIX } from '@hasna-internal/kai-subprocess';
-export type { CollectedOutput, DshEnvironment, DshEnvironmentKey } from '@hasna-internal/kai-subprocess';
-/**
- * Sandbox facts for one run, present iff a sandboxing executor handled it.
- * Facts are reported independently of process exit status so callers can
- * distinguish command failures from policy denials and runner failures.
- */
-export interface ShellSandboxInfo {
-    /** The mode the command actually ran under. */
-    mode: SandboxMode;
-    /** Whether the sandbox denied a file operation. */
-    denied: boolean;
-    /** How completely the selected runner enforced the requested mode. */
-    enforcement?: SandboxEnforcement;
-    /** Whether the sandbox runner failed before the command could run. */
-    runnerFailed?: boolean;
-}
-/**
- * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
- * filled by {@link ShellExecutor.resolve} from the implementation's config.
- * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
- * fully-resolved {@link ShellExecSpec}.
- */
-export interface ShellExecRequest {
-    command: string;
-    /** Working directory override (default: implementation-configured). */
-    workdir?: string | undefined;
-    /** Timeout override in milliseconds (implementations cap it). */
-    timeoutMs?: number | undefined;
-    /**
-     * Foreground stdout capture budget in bytes. Absent uses the executor's
-     * default output cap. Trusted in-process consumers use this when they must
-     * parse complete stdout up to their own bounded limit; the model-facing bash
-     * tool does not expose it as a parameter.
-     */
-    stdoutMaxBytes?: number | undefined;
-    /** Abort signal — implementations kill the command when it fires. */
-    signal?: AbortSignal | undefined;
-    /**
-     * Bytes to write to the command's stdin, then close it. Absent leaves stdin
-     * closed/empty (the default for model-driven tool calls). Set by in-process
-     * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
-     * to its stdin); the model-facing bash tool does not expose it as a parameter
-     * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
-     */
-    stdin?: string | undefined;
-    /**
-     * Ordinary environment entries for the command, merged after the credential
-     * scrub. Managed facts belong in {@link dshEnv}, which merges after this
-     * map, so an entry here can never displace one. Set by in-process plugins
-     * (the hooks bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the
-     * model-facing bash tool does not expose it as a parameter.
-     */
-    env?: Record<string, string> | undefined;
-    /**
-     * Harness-owned `DSH_*` variables for this execution (typed to managed
-     * keys). Executors discard ambient `DSH_*` entries before merging this
-     * snapshot last, so an unavailable current fact cannot inherit a stale
-     * value from the harness process and a caller {@link env} entry cannot
-     * displace a managed one.
-     */
-    dshEnv?: DshEnvironment | undefined;
-    /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
-    sandboxPolicy?: SandboxExecutionPolicy | undefined;
-}
-/**
- * A resolved execution spec. {@link ShellExecutor.resolve} fills and caps the
- * required fields; {@link ShellExecutor.start} ignores `timeoutMs` because
- * background processes have no executor timeout.
- */
-export interface ShellExecSpec {
-    command: string;
-    workdir: string;
-    timeoutMs: number;
-    /**
-     * Resolved foreground stdout capture budget in bytes. `run()` uses it for
-     * stdout; background jobs and stderr keep the executor's own output cap.
-     */
-    stdoutMaxBytes: number;
-    /** Abort signal — implementations kill the command when it fires. */
-    signal?: AbortSignal | undefined;
-    /** Bytes to write to stdin before closing it; absent means no stdin. */
-    stdin?: string | undefined;
-    /**
-     * Ordinary environment entries carried through from
-     * {@link ShellExecRequest.env}; {@link dshEnv} still merges after them.
-     * OPTIONAL on the spec for the same reason as `stdin`: absent means no
-     * ordinary extra environment.
-     */
-    env?: Record<string, string> | undefined;
-    /** Managed `DSH_*` snapshot (typed to managed keys); merges after {@link env}. */
-    dshEnv?: DshEnvironment | undefined;
-    /** Resolved sandbox policy; ignored by executors that do not confine. */
-    sandboxPolicy: SandboxExecutionPolicy | undefined;
-}
-/** The outcome of one completed (or killed) foreground run. */
-export interface ShellRunResult {
-    /** 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;
-    /**
-     * True when the executor's own timeout was the FIRST cause to cut the command
-     * short. Mutually exclusive with {@link aborted}: one fused deadline drives
-     * both the timeout and the caller's cancellation, so a timeout and an abort
-     * racing before process close report the single first-abort cause, not both
-     * (see the [timeout-library Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
-     */
-    timedOut: boolean;
-    /**
-     * True when the caller's `AbortSignal` was the FIRST cause to kill the command
-     * (and it was not the executor's own timeout). Mutually exclusive with
-     * {@link timedOut} — see there for the first-cause classification.
-     */
-    aborted: boolean;
-    /** The effective timeout applied to this run (after defaulting/capping). */
-    timeoutMs: number;
-    stdout: CollectedOutput;
-    stderr: CollectedOutput;
-    /** Sandbox execution facts, absent for an unsandboxed executor. */
-    sandbox?: ShellSandboxInfo;
-}
-/** Lifecycle of a background process. */
-export type ShellProcessStatus = 'running' | 'completed' | 'killed';
-/** One incremental {@link ShellProcess.readOutput} read. */
-export interface ShellProcessRead {
-    /** Output produced since the previous read (stderr in a marked section). */
-    delta: string;
-    /** True when truncation dropped unread bytes the delta cannot include. */
-    lossy: boolean;
-    /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
-    stdoutSpillPath?: string;
-    /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
-    stderrSpillPath?: string;
-}
-/**
- * A background process handle returned by {@link ShellExecutor.start}. It is the
- * only access path; buffered output remains readable after exit. Composition
- * teardown (the subprocess service's disposal) kills running processes and
- * awaits {@link done}; an executor-only reload leaves them running.
- */
-export interface ShellProcess {
-    /** Process lifecycle state (settled exactly once). */
-    status: ShellProcessStatus;
-    /** Exit code once finished (null = killed by signal / still running). */
-    exitCode: number | null;
-    /** Terminating signal name, when signal-killed. */
-    signal: NodeJS.Signals | null;
-    /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
-    readonly done: Promise<void>;
-    /** Sandbox facts, stamped once a confined process settles. */
-    sandbox?: ShellSandboxInfo;
-    /**
-     * Read output produced since the previous read (consuming — consecutive
-     * reads never re-deliver). Reads that lost data flag `lossy` and point at
-     * full-stream spill files when available.
-     */
-    readOutput(): ShellProcessRead;
-    /**
-     * Kill the process group. Returns false when it had already finished
-     * (no-op); idempotent.
-     */
-    kill(): boolean;
-}
-//# sourceMappingURL=types.d.ts.map