@hasna-internal/kai-sandbox 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,6 @@
+# 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/sandbox/sandbox/README.md
+README.md: 3ebbffd623eee51dd6fcb588eec374e6d09be2f0
+README.zh.md: b9215b59d5ed5314275e91261c5541be1e5586fe

package/README.md

@@ -0,0 +1,43 @@
+# @hasna-internal/kai-sandbox
+
+English | [中文](README.zh.md)
+
+Process-sandbox Service Definition. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. As the Service Definition role of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), it depends only on cordis (+ the harness error base), never on a backend.
+
+The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
+
+Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.
+
+**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names the filesystem-canonical real host directory. Workspace identity is resolved before lexical normalization, so a valid cwd containing `symlink/..` grants the directory where `chdir` actually lands rather than an unrelated lexical parent. Containers, microVMs, and remote executors are NOT backends of this seam — they replace the Service Providers for whole capability seams (`ctx.shell`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+
+Implementations: [`@hasna-internal/kai-sandbox-local`](../sandbox-local/) (Linux: `bwrap`, else the per-platform Landlock launcher; macOS: `sandbox-exec`/Seatbelt). Consumers: [`@hasna-internal/kai-bash-sandbox`](../../shell/bash-sandbox/) (wraps `['bash', '-c', command]`).
+
+## Model Experience
+
+### Confinement error, indirectly
+
+#### What the model sees
+
+Through [`dsh-bash-sandbox`](../../shell/bash-sandbox/README.md) and [`dsh-tool-bash`](../../shell/tool-bash/README.md), failure to enforce a requested mode produces code `SANDBOX_UNAVAILABLE` and the exact error below. An execution-time runner failure adds ` Runner failure: <detail>`.
+
+##### Exact error
+
+```markdown
+sandbox mode "<mode>" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL restricted-token runner can start (Windows) — otherwise switch the consumer to danger-full-access.
+```
+
+#### Token effect
+
+Conditional error text is visible for that call and retained in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **File effects are the whole policy vocabulary** — the seam expresses no network, process, syscall, device, or credential restrictions.
+- **Same-world confinement only** — containers, microVMs, and remote execution require replacing capability implementations rather than adding a provider here.
+- **Denial reporting is a stderr dialect** — the seam returns backend signatures instead of a typed runtime denial channel, so consumers that need classification must infer it from the child process's output.
+- **Runner diagnostics are in-band** — exit status plus stderr evidence cannot prove which process wrote a matching line, so a confined child that deliberately mimics its runner can cause an availability/diagnostic false attribution. This cannot bypass confinement; an out-of-band runner-status channel is deferred.
+- **One provider per context** — composing different sandbox mechanisms simultaneously requires a provider-level ladder or separate Cordis contexts; callers choose policy per call, not backend identity.

package/README.zh.md

@@ -0,0 +1,45 @@
+# @hasna-internal/kai-sandbox
+
+[English](README.md) | 中文
+
+进程沙箱 Service Definition。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。作为[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)中的 Service Definition 角色，它只依赖 cordis（及 harness 错误基类），绝不依赖后端。
+
+用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.zh.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
+
+策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
+
+**只支持与宿主共享文件系统和内核的限制。** 后端与宿主共享文件系统和内核（`bwrap`、Landlock、Seatbelt）；`workspaceRoot` 指向文件系统规范化后的真实主机目录。系统先解析工作区所指的目录，再做词法规范化，因此包含 `symlink/..` 的有效 cwd 会授权 `chdir` 实际到达的目录，而非无关的词法父目录。容器、microVM 与远程执行器都不是该 seam 的后端：它们会以环境一致的分组替换整个能力 seam 的 Service Provider（`ctx.shell`、`ctx.fs`）。边界及其设计理由见[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md)。
+
+实现：[`@hasna-internal/kai-sandbox-local`](../sandbox-local/)（Linux：`bwrap`，否则使用相应平台的 Landlock launcher；macOS：`sandbox-exec`／Seatbelt）。消费方：[`@hasna-internal/kai-bash-sandbox`](../../shell/bash-sandbox/)（包装 `['bash', '-c', command]`）。
+
+## 模型体验
+
+<a id="confinement-error-indirectly"></a>
+
+### 间接的限制错误
+
+#### 模型看到的内容
+
+通过 [`dsh-bash-sandbox`](../../shell/bash-sandbox/README.zh.md) 和 [`dsh-tool-bash`](../../shell/tool-bash/README.zh.md)，无法强制执行所请求模式时会产生错误码 `SANDBOX_UNAVAILABLE` 及以下精确错误。执行期 runner 失败会追加 ` Runner failure: <detail>`。
+
+##### 精确错误
+
+```markdown
+sandbox mode "<mode>" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL restricted-token runner can start (Windows) — otherwise switch the consumer to danger-full-access.
+```
+
+#### Token 影响
+
+条件性错误文本对该次调用可见，并保留在历史中直到压缩（compaction）。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **文件操作是完整的策略词汇**：该 seam 不表达网络、进程、系统调用、设备或凭据限制。
+- **只支持与宿主共享文件系统和内核的限制**：容器、microVM 与远程执行需要替换能力实现，而不是在此处增加提供方。
+- **拒绝报告是一种 stderr 方言**：该 seam 返回后端签名，而非类型化运行时拒绝通道，因此需要分类的消费方必须从子进程输出推断。
+- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过约束；带外 runner 状态通道暂缓实现。
+- **每个上下文只有一个提供方**：同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。

package/lib/index.js

@@ -0,0 +1,201 @@
+import { Service } from "@deepseek-ai/cordis";
+import { HarnessError, assertNever } from "@hasna-internal/kai-llm";
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+//#region lib/types/escalation.js
+/**
+* The escalation vocabulary and choreography shared by every sandbox-enforcing
+* tool family (`@hasna-internal/kai-tool-bash`, `@hasna-internal/kai-tool-fs`): the
+* strictly-wider ladder, the argument-pairing validation, the model-facing
+* denial/hint markers, and {@link approveEscalation} — the ordered fail-closed
+* sequence that resolves a `sandbox_permissions` request through a
+* user-approval channel BEFORE anything executes. One home keeps the two
+* families' approval ordering and verbatim error texts from drifting apart.
+*
+* The channel is a minimal STRUCTURAL function shape ({@link EscalationAsk}),
+* not the approval service type: the tool layer — which owns the agent, the
+* call id, and the tool name — closes over `ctx.approval.request(...)` and
+* hands the closure down, so this package never depends on the approval or
+* agent packages.
+*
+* @module dsh-sandbox/escalation
+*/
+/**
+* The strictly-wider table: what a call whose effective mode is the key may
+* escalate TO. Checked at EXECUTION, never baked into a tool schema — the
+* schema's enum is {@link ESCALATION_TARGETS}, because schemas are
+* registry-global while the effective mode is per-call truth.
+*/
+const WIDER_MODES = {
+	"read-only": ["workspace-write", "danger-full-access"],
+	"workspace-write": ["danger-full-access"]
+};
+/**
+* The closed escalation-target vocabulary — every mode a call could ever
+* escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
+* whenever the mounted capability confines: cutting the enum down to the modes
+* wider than the composition's DEFAULT would strand a session whose effective
+* mode sits below it (a `danger-full-access` default would advertise nothing
+* while a narrower-switched session stays confined with no lever).
+*/
+const ESCALATION_TARGETS = ["workspace-write", "danger-full-access"];
+/**
+* Validate the escalation argument pairing a tool schema cannot express:
+* `sandbox_permissions` and `justification` travel together — an approval
+* prompt without a reason, or a reason driving nothing, is a malformed ask —
+* and the justification must be a non-empty sentence.
+* @param sandboxPermissions - the raw `sandbox_permissions` argument, if given.
+* @param justification - the raw `justification` argument, if given.
+*/
+function validateEscalationArgs(sandboxPermissions, justification) {
+	if (sandboxPermissions !== void 0 && justification === void 0) throw new Error("invalid escalation: sandbox_permissions requires a justification");
+	if (justification !== void 0 && sandboxPermissions === void 0) throw new Error("invalid escalation: justification is only valid together with sandbox_permissions");
+	if (justification !== void 0 && justification.trim().length === 0) throw new Error("invalid justification: expected a non-empty sentence");
+}
+/**
+* The model-facing denial marker — the one vocabulary both enforcing families
+* teach and report, so the model recognizes a policy denial identically
+* whether the kernel refused a bash file effect or the filesystem provider's
+* fence refused a mutation.
+* @param mode - the mode the denied call ran under.
+* @returns the marker line, exactly as the model sees it.
+*/
+function sandboxDenialMarker(mode) {
+	return `[sandbox: file access denied under ${mode} mode]`;
+}
+/**
+* The same-turn escalation hint that rides a denial when the composition
+* advertises the escalation fields — the nudge lives at the decision point so
+* the sanctioned retry does not depend on the model recalling the tool
+* description.
+* @param subject - the family's noun for the denied action (`command` for
+*   bash, `operation` for a filesystem mutation).
+* @returns the hint line, exactly as the model sees it.
+*/
+function escalationHintMarker(subject) {
+	return `[sandbox: escalation available — retry this exact ${subject} once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`;
+}
+/**
+* Resolve a sandbox-escalation request BEFORE anything executes: check strict
+* widening against the call's effective mode, then resolve the approval
+* channel, then map every outcome — the ordered fail-closed sequence both
+* enforcing families share. Returns the granted mode to stamp onto exactly
+* this call; throws the distinct verbatim text for every other path (a
+* non-widening request, a missing approval service, an agent-less execution,
+* a rejection, a cancellation, an unanswerable ask) — the tool registry turns
+* the throw into the call's isError result, and nothing has run. A
+* non-widening request never prompts a human.
+* @param request - the escalation to judge (see {@link EscalationRequest}).
+* @param approval - the approval ingredients the tool holds (see {@link EscalationApproval}).
+* @returns the granted mode, consumed by the one call that asked.
+*/
+async function approveEscalation(request, approval) {
+	const { requestedMode: mode, effectiveMode, justification, subject } = request;
+	if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode)) throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`);
+	if (approval.approver === void 0) throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval service is composed`);
+	if (approval.agent === void 0) throw new Error(`sandbox escalation to "${mode}" requires approval, but the call has no agent to route it through`);
+	const outcome = await approval.approver.request({
+		agent: approval.agent,
+		toolName: approval.toolName,
+		callId: approval.callId,
+		reason: `escalate sandbox to ${mode}: ${justification}`,
+		...approval.signal ? { signal: approval.signal } : {}
+	});
+	switch (outcome) {
+		case "allowed-once": return mode;
+		case "rejected": throw new Error(`the user rejected escalating this ${subject} to "${mode}"`);
+		case "cancelled": throw new Error(`approval for escalating to "${mode}" was cancelled`);
+		case "unavailable": throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval channel is available`);
+		default: return assertNever(outcome, "EscalationOutcome");
+	}
+}
+//#endregion
+//#region lib/types/roots.js
+/**
+* The writable-root derivation shared by every enforcement dialect that
+* expresses a mode as a canonical allow-list: `workspace-write` means "the
+* workspace root plus the platform temp areas", and this module is that
+* meaning's one home. The Seatbelt profile
+* (`@hasna-internal/kai-sandbox-local`) and the in-process filesystem fence
+* (`@hasna-internal/kai-fs-sandbox`) both derive their allow-list here, so "the
+* write tool cannot write /tmp but bash can" asymmetries cannot arise between
+* them. The bwrap and Landlock dialects keep their own grant spellings (an
+* ephemeral `/tmp` mount, launcher-owned flags) — the honest per-runner
+* differences recorded in the sandbox RFC — with parity pinned by test.
+*
+* @module dsh-sandbox/roots
+*/
+/**
+* Resolve a granted root to the path the enforcement layer actually compares:
+* canonical (symlinks resolved), because both Seatbelt filters and the fs
+* fence's containment check match resolved paths — `/tmp` IS `/private/tmp`
+* on darwin, and an as-spelled grant would match nothing.
+* @param path - the root as configured or platform-reported.
+* @returns the canonical path, or the spelling as-is when resolution fails
+*   (a missing root matches nothing until it exists — the conservative
+*   outcome; inventing a fallback would grant a path the caller never named).
+*/
+function canonicalPath(path) {
+	try {
+		return realpathSync.native(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* The roots one confined execution may WRITE under — the mode's meaning as a
+* canonical, deduplicated allow-list. `read-only` allows nothing;
+* `workspace-write` allows the policy's workspace root, the host `/tmp`, and
+* the per-user platform temp dir (`os.tmpdir()` — the real temp area for
+* mkstemp-family tools; omitting it would deny what the mode promises).
+* @param policy - the file-effect policy to derive the allow-list from.
+* @returns the canonical writable roots; empty exactly under `read-only`.
+*/
+function writableRoots(policy) {
+	if (policy.mode !== "workspace-write") return [];
+	return [...new Set([
+		policy.workspaceRoot,
+		"/tmp",
+		tmpdir()
+	].map(canonicalPath))];
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
+* host-path file policy. Containers, microVMs, and remote execution replace the
+* surrounding capability seam instead; this service shares the host kernel and filesystem.
+* @module @hasna-internal/kai-sandbox
+*/
+/**
+* Error code for a requested confined mode when no backend is usable. The
+* provider fails closed, and `HarnessError` carries the code through
+* `tool/result` so callers can distinguish missing confinement from command
+* failure.
+*/
+const SANDBOX_UNAVAILABLE = "SANDBOX_UNAVAILABLE";
+/**
+* Thrown when {@link SandboxProvider.confine} cannot enforce the requested
+* mode. Carries {@link SANDBOX_UNAVAILABLE} through the structured error
+* channel.
+*/
+var SandboxUnavailableError = class extends HarnessError {
+	constructor(mode, detail) {
+		super(`sandbox mode "${mode}" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL restricted-token runner can start (Windows) — otherwise switch the consumer to danger-full-access.` + (detail === void 0 ? "" : ` Runner failure: ${detail}`), SANDBOX_UNAVAILABLE);
+		this.name = "SandboxUnavailableError";
+	}
+};
+/**
+* Abstract process-sandbox service. {@link confine} must return enforcing argv
+* or fail closed at wrap or runner-execution time; silent unconfined passthrough
+* is forbidden. Functional probes arbitrate multi-runner chains and may be
+* skipped for a sole candidate, whose own refusal remains the fail-closed end.
+*/
+var SandboxProvider = class extends Service {
+	/* v8 ignore next -- abstract service construction is covered through concrete provider packages. */
+	constructor(ctx) {
+		super(ctx, "sandbox");
+	}
+};
+//#endregion
+export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs, writableRoots };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-sandbox`.
+* @module @hasna-internal/kai-sandbox/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-sandbox";
+/** Cordis companion plugin name. */
+const name = "sandbox-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/escalation.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The escalation vocabulary and choreography shared by every sandbox-enforcing
+ * tool family (`@hasna-internal/kai-tool-bash`, `@hasna-internal/kai-tool-fs`): the
+ * strictly-wider ladder, the argument-pairing validation, the model-facing
+ * denial/hint markers, and {@link approveEscalation} — the ordered fail-closed
+ * sequence that resolves a `sandbox_permissions` request through a
+ * user-approval channel BEFORE anything executes. One home keeps the two
+ * families' approval ordering and verbatim error texts from drifting apart.
+ *
+ * The channel is a minimal STRUCTURAL function shape ({@link EscalationAsk}),
+ * not the approval service type: the tool layer — which owns the agent, the
+ * call id, and the tool name — closes over `ctx.approval.request(...)` and
+ * hands the closure down, so this package never depends on the approval or
+ * agent packages.
+ *
+ * @module dsh-sandbox/escalation
+ */
+import type { SandboxMode } from './index.ts';
+/**
+ * The strictly-wider table: what a call whose effective mode is the key may
+ * escalate TO. Checked at EXECUTION, never baked into a tool schema — the
+ * schema's enum is {@link ESCALATION_TARGETS}, because schemas are
+ * registry-global while the effective mode is per-call truth.
+ */
+export declare const WIDER_MODES: Record<string, readonly SandboxMode[]>;
+/**
+ * The closed escalation-target vocabulary — every mode a call could ever
+ * escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
+ * whenever the mounted capability confines: cutting the enum down to the modes
+ * wider than the composition's DEFAULT would strand a session whose effective
+ * mode sits below it (a `danger-full-access` default would advertise nothing
+ * while a narrower-switched session stays confined with no lever).
+ */
+export declare const ESCALATION_TARGETS: readonly SandboxMode[];
+/**
+ * Validate the escalation argument pairing a tool schema cannot express:
+ * `sandbox_permissions` and `justification` travel together — an approval
+ * prompt without a reason, or a reason driving nothing, is a malformed ask —
+ * and the justification must be a non-empty sentence.
+ * @param sandboxPermissions - the raw `sandbox_permissions` argument, if given.
+ * @param justification - the raw `justification` argument, if given.
+ */
+export declare function validateEscalationArgs(sandboxPermissions: string | undefined, justification: string | undefined): void;
+/**
+ * The model-facing denial marker — the one vocabulary both enforcing families
+ * teach and report, so the model recognizes a policy denial identically
+ * whether the kernel refused a bash file effect or the filesystem provider's
+ * fence refused a mutation.
+ * @param mode - the mode the denied call ran under.
+ * @returns the marker line, exactly as the model sees it.
+ */
+export declare function sandboxDenialMarker(mode: SandboxMode): string;
+/**
+ * The same-turn escalation hint that rides a denial when the composition
+ * advertises the escalation fields — the nudge lives at the decision point so
+ * the sanctioned retry does not depend on the model recalling the tool
+ * description.
+ * @param subject - the family's noun for the denied action (`command` for
+ *   bash, `operation` for a filesystem mutation).
+ * @returns the hint line, exactly as the model sees it.
+ */
+export declare function escalationHintMarker(subject: string): string;
+/**
+ * The closed outcome vocabulary of one escalation ask — structurally identical
+ * to the approval seam's `ApprovalOutcome` so an `ApprovalService.request`
+ * return is assignable without this package importing it.
+ */
+export type EscalationOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+/**
+ * The minimal approval-request shape {@link approveEscalation} needs —
+ * structurally the approval seam's `ApprovalService`, generic over the agent
+ * type `A` and call-id type `C` so this package resolves escalations through
+ * `ctx.approval` without importing the approval or agent packages (the tool
+ * layer infers `A`/`C` as its own `Agent`/`CallId`).
+ */
+export interface EscalationApprover<A = object, C = string> {
+    /**
+     * Ask the human to approve one action, resolving to a closed outcome.
+     * @param req - the audit-self-contained request (agent, tool, call id, reason, optional signal).
+     * @returns the human's decision as a closed {@link EscalationOutcome}.
+     */
+    request(req: {
+        agent: A;
+        toolName: string;
+        callId: C;
+        reason: string;
+        signal?: AbortSignal;
+    }): Promise<EscalationOutcome>;
+}
+/**
+ * The approval ingredients an escalating tool hands {@link approveEscalation}:
+ * the approval requester (`ctx.approval`, or `undefined` when none is
+ * composed), the calling agent (or `undefined` for an agent-less execution),
+ * and the call's identity. The tool layer holds all of these; this package
+ * only judges them.
+ */
+export interface EscalationApproval<A = object, C = string> {
+    /** The approval requester (`ctx.approval`), or `undefined` when none is composed. */
+    approver: EscalationApprover<A, C> | undefined;
+    /** The calling agent, or `undefined` for an agent-less execution (fails closed). */
+    agent: A | undefined;
+    /** The tool-call id the approval prompt attaches to. */
+    callId: C;
+    /** The tool name recorded on the approval request. */
+    toolName: string;
+    /** The tool-execution abort signal the approval request rides, when present. */
+    signal?: AbortSignal;
+}
+/** One escalation request, as {@link approveEscalation} judges it. */
+export interface EscalationRequest {
+    /** The requested target mode (schema-pinned to {@link ESCALATION_TARGETS} when advertised). */
+    requestedMode: string;
+    /** The model's one-sentence reason, shown verbatim to the user inside the audit reason. */
+    justification: string;
+    /** The call's effective mode (session override ?? composition default) the request must strictly widen. */
+    effectiveMode: SandboxMode;
+    /** The family's noun for the escalated action in user-facing texts (`command` for bash, `operation` for fs). */
+    subject: string;
+}
+/**
+ * Resolve a sandbox-escalation request BEFORE anything executes: check strict
+ * widening against the call's effective mode, then resolve the approval
+ * channel, then map every outcome — the ordered fail-closed sequence both
+ * enforcing families share. Returns the granted mode to stamp onto exactly
+ * this call; throws the distinct verbatim text for every other path (a
+ * non-widening request, a missing approval service, an agent-less execution,
+ * a rejection, a cancellation, an unanswerable ask) — the tool registry turns
+ * the throw into the call's isError result, and nothing has run. A
+ * non-widening request never prompts a human.
+ * @param request - the escalation to judge (see {@link EscalationRequest}).
+ * @param approval - the approval ingredients the tool holds (see {@link EscalationApproval}).
+ * @returns the granted mode, consumed by the one call that asked.
+ */
+export declare function approveEscalation<A, C>(request: EscalationRequest, approval: EscalationApproval<A, C>): Promise<SandboxMode>;
+//# sourceMappingURL=escalation.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
+ * host-path file policy. Containers, microVMs, and remote execution replace the
+ * surrounding capability seam instead; this service shares the host kernel and filesystem.
+ * @module @hasna-internal/kai-sandbox
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { HarnessError } from '@hasna-internal/kai-llm';
+import type { SessionId } from '@hasna-internal/kai-session';
+export { ESCALATION_TARGETS, WIDER_MODES, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs, } from './escalation.ts';
+export type { EscalationApproval, EscalationApprover, EscalationOutcome, EscalationRequest } from './escalation.ts';
+export { canonicalPath, writableRoots } from './roots.ts';
+/**
+ * File-effect policy for confined processes. `read-only` permits only required
+ * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
+ * backend-defined temp area; `danger-full-access` bypasses confinement. Network
+ * and process visibility are outside this vocabulary.
+ */
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
+export type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>;
+/**
+ * The complete file-effect policy resolved for one capability call. The root
+ * is carried even under modes that do not consume it so callers can resolve
+ * policy once before choosing the enforcement path.
+ */
+export interface SandboxExecutionPolicy {
+    /** The file-effect mode this execution runs under. */
+    mode: SandboxMode;
+    /** Absolute root directory `workspace-write` may write under. */
+    workspaceRoot: string;
+    /**
+     * Opaque identity of the calling session (the branded `dsh-session`
+     * SessionId). Backends key per-session state off it (e.g. windows-acl gives
+     * each live session/workspace pair a random private temp directory and SID,
+     * while the workspace SID and standing grant remain per-workspace); absent
+     * for agentless calls, which fall back to per-call backend state.
+     */
+    sessionId?: SessionId;
+}
+/**
+ * Enforcement completeness for this host. `partial` means an active backend or
+ * older kernel ABI cannot govern every promised file effect; callers requiring
+ * an absolute boundary must not treat it as `full`.
+ */
+export type SandboxEnforcement = 'full' | 'partial';
+/**
+ * What one confined execution is allowed to touch — carried PER CALL, not
+ * fixed on the provider: two consumers may confine under different policies
+ * at the same instant (bash under `read-only` while a confined child agent
+ * needs its state directory writable), and an approved escalated retry is a
+ * new call with a wider policy. Defaulting/resolution is an explicit step at
+ * the consumer boundary; the provider treats the policy as fully specified.
+ */
+export interface SandboxPolicy extends SandboxExecutionPolicy {
+    /** The file-effect mode this execution runs under. */
+    mode: ConfinedSandboxMode;
+}
+/**
+ * Evidence that identifies a sandbox runner failing before it executes the
+ * wrapped command. A consumer first applies {@link allowedExitCodes} when
+ * present, removes {@link informationalLines} by case-insensitive exact line
+ * equality, then matches {@link fatalSignatures} case-insensitively within
+ * each remaining stderr line. Exit status alone never proves runner failure.
+ */
+export interface RunnerFailureRule {
+    /** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
+    allowedExitCodes?: readonly number[];
+    /** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
+    fatalSignatures: readonly string[];
+    /** Benign stderr lines excluded by exact full-line equality before fatal matching. */
+    informationalLines?: readonly string[];
+}
+/**
+ * A {@link SandboxProvider.confine} result: the argv to spawn in place of
+ * the caller's own, plus the enforcement completeness the selected backend
+ * achieves for it.
+ */
+export interface ConfinedArgv {
+    /** The wrapped argv (runner, profile, separator, then the caller's argv). */
+    argv: string[];
+    /** How completely the selected backend enforces the policy's file effects. */
+    enforcement: SandboxEnforcement;
+    /**
+     * The selected backend's denial DIALECT: the case-insensitive stderr
+     * substrings a file effect denied by THIS backend produces (EROFS text
+     * under bwrap's read-only binds, EACCES under Landlock, EPERM under
+     * Seatbelt). A consumer that infers denials from a failed run's stderr
+     * matches against exactly these rather than a cross-backend union — the
+     * union claims denials a given backend never produces.
+     */
+    denialSignatures: readonly string[];
+    /**
+     * Structured runner-failure evidence rules. Consumers require a matching
+     * fatal stderr line (after informational exclusions) and any rule-specific
+     * exit-code gate before checking denial signatures: runner failure means the
+     * command never ran, while denial means confinement worked and blocked it.
+     */
+    runnerFailureRules: readonly RunnerFailureRule[];
+}
+/**
+ * Error code for a requested confined mode when no backend is usable. The
+ * provider fails closed, and `HarnessError` carries the code through
+ * `tool/result` so callers can distinguish missing confinement from command
+ * failure.
+ */
+export declare const SANDBOX_UNAVAILABLE = "SANDBOX_UNAVAILABLE";
+/**
+ * Thrown when {@link SandboxProvider.confine} cannot enforce the requested
+ * mode. Carries {@link SANDBOX_UNAVAILABLE} through the structured error
+ * channel.
+ */
+export declare class SandboxUnavailableError extends HarnessError {
+    constructor(mode: ConfinedSandboxMode, detail?: string);
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sandbox: SandboxProvider;
+    }
+}
+/**
+ * Abstract process-sandbox service. {@link confine} must return enforcing argv
+ * or fail closed at wrap or runner-execution time; silent unconfined passthrough
+ * is forbidden. Functional probes arbitrate multi-runner chains and may be
+ * skipped for a sole candidate, whose own refusal remains the fail-closed end.
+ */
+export declare abstract class SandboxProvider extends Service {
+    constructor(ctx: Context);
+    /**
+     * Wrap `argv` so it executes confined under `policy` on this host; the
+     * caller spawns the returned argv in place of its own.
+     * @param argv - the exact argv the caller is about to spawn (program plus
+     *   arguments), NOT a shell string — a shell-shaped consumer passes
+     *   `['bash', '-c', command]`.
+     * @param policy - the file-effect policy this execution runs under,
+     *   carried per call (see {@link SandboxPolicy}).
+     * @returns the argv to spawn instead, plus the enforcement completeness
+     *   the selected backend achieves for it.
+     */
+    abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
+}
+export default SandboxProvider;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-sandbox`.
+ * @module @hasna-internal/kai-sandbox/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sandbox-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/roots.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The writable-root derivation shared by every enforcement dialect that
+ * expresses a mode as a canonical allow-list: `workspace-write` means "the
+ * workspace root plus the platform temp areas", and this module is that
+ * meaning's one home. The Seatbelt profile
+ * (`@hasna-internal/kai-sandbox-local`) and the in-process filesystem fence
+ * (`@hasna-internal/kai-fs-sandbox`) both derive their allow-list here, so "the
+ * write tool cannot write /tmp but bash can" asymmetries cannot arise between
+ * them. The bwrap and Landlock dialects keep their own grant spellings (an
+ * ephemeral `/tmp` mount, launcher-owned flags) — the honest per-runner
+ * differences recorded in the sandbox RFC — with parity pinned by test.
+ *
+ * @module dsh-sandbox/roots
+ */
+import type { SandboxExecutionPolicy } from './index.ts';
+/**
+ * Resolve a granted root to the path the enforcement layer actually compares:
+ * canonical (symlinks resolved), because both Seatbelt filters and the fs
+ * fence's containment check match resolved paths — `/tmp` IS `/private/tmp`
+ * on darwin, and an as-spelled grant would match nothing.
+ * @param path - the root as configured or platform-reported.
+ * @returns the canonical path, or the spelling as-is when resolution fails
+ *   (a missing root matches nothing until it exists — the conservative
+ *   outcome; inventing a fallback would grant a path the caller never named).
+ */
+export declare function canonicalPath(path: string): string;
+/**
+ * The roots one confined execution may WRITE under — the mode's meaning as a
+ * canonical, deduplicated allow-list. `read-only` allows nothing;
+ * `workspace-write` allows the policy's workspace root, the host `/tmp`, and
+ * the per-user platform temp dir (`os.tmpdir()` — the real temp area for
+ * mkstemp-family tools; omitting it would deny what the mode promises).
+ * @param policy - the file-effect policy to derive the allow-list from.
+ * @returns the canonical writable roots; empty exactly under `read-only`.
+ */
+export declare function writableRoots(policy: SandboxExecutionPolicy): string[];
+//# sourceMappingURL=roots.d.ts.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hasna-internal/kai-sandbox",
+  "description": "Abstract process-sandbox seam (ctx.sandbox) for the DeepSeek Harness: same-world confinement vocabulary and the SandboxProvider contract",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/sandbox/sandbox"
+  },
+  "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": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  }
+}