@deepseek-ai/dsh-sandbox 0.1.7-rc.1 → 0.2.0-rc.1

package/README.i18n.yaml

@@ -1,6 +1,91 @@
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# 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: 56cdd87c274cc8d951d4bc4e1388d7e985aa4a28
-README.zh.md: c09d7e31fca4825e370636a4c5d9648e145f6a54
+/:
+  en: 4308065a46738364
+  zh: 2eb6ab7314e74976
+/deepseek-ai-dsh-sandbox:
+  en: 3d3312b2261f0a60
+  zh: 47741e2a3d90da70
+/deepseek-ai-dsh-sandbox/summary:
+  en: be0473ca1d2dbb6c
+  zh: 8c6b097438d2c2af
+/deepseek-ai-dsh-sandbox/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-sandbox/use-this-package:
+  en: 5fbf0b48effb1143
+  zh: 5c570dcc1a17e0ad
+/deepseek-ai-dsh-sandbox/use-this-package/when-to-choose-it:
+  en: 4ddc504d2626fe3e
+  zh: ceb3dd93fb3835db
+/deepseek-ai-dsh-sandbox/use-this-package/confining-a-command:
+  en: c5540889017b6a7f
+  zh: 679bfbd5254bf92d
+/deepseek-ai-dsh-sandbox/use-this-package/modes-and-enforcement:
+  en: ab093e9042b86b99
+  zh: d173df7cb3649446
+/deepseek-ai-dsh-sandbox/use-this-package/denied-calls-and-escalation:
+  en: 92cf42bad65d112c
+  zh: 60fa2cb7e9c4c556
+/deepseek-ai-dsh-sandbox/use-this-package/fail-closed-behavior:
+  en: 6bf240632a7a6bf5
+  zh: ebf414f5cf435875
+/deepseek-ai-dsh-sandbox/understand-the-implementation:
+  en: 7e13d669ecc96d59
+  zh: b5fe7ae65812d926
+/deepseek-ai-dsh-sandbox/understand-the-implementation/design-philosophy:
+  en: 0fc96495c192b513
+  zh: 38b51b9b3c208012
+/deepseek-ai-dsh-sandbox/understand-the-implementation/source-map:
+  en: 54cab3e684afb031
+  zh: b49b476d2f965985
+/deepseek-ai-dsh-sandbox/understand-the-implementation/escalation-choreography:
+  en: 1b418d41f571ab3d
+  zh: 62b289cdd6f4d272
+/deepseek-ai-dsh-sandbox/understand-the-implementation/writable-roots:
+  en: 956d3195cf7a35f8
+  zh: f83d8342e22bb7cd
+/deepseek-ai-dsh-sandbox/further-exploration:
+  en: 9f0d57097c678a25
+  zh: 58e765bf1b223215
+/deepseek-ai-dsh-sandbox/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-sandbox/model-experience/confinement-error-indirectly:
+  en: 35e1ea00601f4003
+  zh: 08152430b840ea05
+/deepseek-ai-dsh-sandbox/model-experience/confinement-error-indirectly/what-the-model-sees:
+  en: 15bcb0abf4a06983
+  zh: 801c506e47f8b063
+/deepseek-ai-dsh-sandbox/model-experience/confinement-error-indirectly/what-the-model-sees/exact-error:
+  en: e8b03df128b832a6
+  zh: dc89500c436a39cf
+/deepseek-ai-dsh-sandbox/model-experience/confinement-error-indirectly/token-effect:
+  en: 8f514efe94edfa8a
+  zh: a46f9f4cd4527f4e
+/deepseek-ai-dsh-sandbox/model-experience/confinement-error-indirectly/kv-cache-effect:
+  en: 2fbf2175168e8244
+  zh: f681f89596f500f5
+/deepseek-ai-dsh-sandbox/model-experience/escalation-request-and-outcome:
+  en: 67c621ef55ec8320
+  zh: ae4bb9162a49e9fb
+/deepseek-ai-dsh-sandbox/model-experience/escalation-request-and-outcome/what-the-model-sees:
+  en: c20128fa8f79c491
+  zh: 96173408d176b9e6
+/deepseek-ai-dsh-sandbox/model-experience/escalation-request-and-outcome/token-effect:
+  en: 1a7b54d68b045beb
+  zh: 5dc6e824110c8fd8
+/deepseek-ai-dsh-sandbox/model-experience/escalation-request-and-outcome/kv-cache-effect:
+  en: ea21ed3a768ed4b8
+  zh: 8e2f396a6875420e
+/deepseek-ai-dsh-sandbox/known-limitations-and-deferred-work:
+  en: 63ff67b6fd13b4b0
+  zh: 6c8efa9ee99ea9bf
+/deepseek-ai-dsh-sandbox/known-limitations-and-deferred-work/dev-note:
+  en: cc273320f6a1beaf
+  zh: 5c57a312ddc50651
+/deepseek-ai-dsh-sandbox/known-limitations-and-deferred-work/dev-note/future-consumers-and-environments:
+  en: a7bc10cf027a51b8
+  zh: 2562dd32d3859205

package/README.md

@@ -63,7 +63,7 @@ Enforcement is reported per call: `full` means the backend governs every promise
 
 ### Denied calls and escalation
 
-When a confined call is denied, the operation reports a denial marker naming the mode — `[sandbox: file access denied under <mode> mode]` — and, when the composition advertises escalation, an escalation hint. The model may retry the exact call once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a `justification`; the user sees one approval prompt and can allow once, reject, or cancel. A wider mode requires approval and applies to that one call only. Repeating the call's effective mode succeeds without approval; narrower targets remain invalid.
+When a confined call is denied, the operation reports a denial marker naming the mode — `[sandbox: file access denied under <mode> mode]` — and, when the composition advertises escalation, an escalation hint. The model may retry the exact call once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a `justification`; the approval service obtains consent for the operation. The request retains its audit reason and supplies English and Chinese presentation copy with the model's justification unchanged. Missing translations follow the locale service's fallback chain, ultimately English; requesters own their translated presentation text. A wider mode requires approval and applies to that one call only. Repeating the call's effective mode succeeds without approval; narrower targets remain invalid.
 
 ### Fail-closed behavior
 

package/README.zh.md

@@ -63,7 +63,7 @@ kind: "package-reference"
 
 ### 被拒绝的调用与升权
 
-受限调用被拒绝时，操作会报告指明模式的拒绝标记——`[sandbox: file access denied under <mode> mode]`——组合声明升权能力时还会给出升权提示。模型可以用 `sandbox_permissions`（足以放行的最窄更宽模式）加 `justification` 重试一次完全相同的调用；用户会看到一次审批提示，可以选择允许一次、拒绝或取消。更宽的模式需要审批，且只作用于该次调用。重复指定调用的生效模式无需审批即可成功；更窄的目标仍然无效。
+受限调用被拒绝时，操作会报告指明模式的拒绝标记——`[sandbox: file access denied under <mode> mode]`——组合声明升权能力时还会给出升权提示。模型可以用 `sandbox_permissions`（足以放行的最窄更宽模式）加 `justification` 重试一次完全相同的调用；审批服务为操作取得同意。请求保留审计原因，同时提供英文和中文展示文案，模型给出的理由保持原样。缺失的译文遵循语言服务的回退链，最终回退到英文；请求方负责自己的展示译文。更宽的模式需要审批，且只作用于该次调用。重复指定调用的生效模式无需审批即可成功；更窄的目标仍然无效。
 
 ### 故障关闭行为
 

package/lib/index.js

@@ -77,6 +77,16 @@ 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]`;
 }
 /**
+* The model-facing `sandbox_permissions` parameter description, which carries
+* the escalation rules for every enforcing family.
+* @param subject - the family's noun for the denied action (`command` for
+*   bash, `operation` for a filesystem mutation).
+* @returns the parameter description, exactly as the model sees it.
+*/
+function sandboxPermissionsDescription(subject) {
+	return `The narrowest wider sandbox mode for a one-shot retry of the exact ${subject} the sandbox just denied; the retry asks the user for approval.`;
+}
+/**
 * Resolve a sandbox permission request before execution. Repeating the call's
 * effective mode returns it without approval. A strictly wider mode requires
 * approval and applies only to this call. Narrower or unsupported targets,
@@ -97,11 +107,15 @@ async function approveEscalation(request, approval) {
 		toolName: approval.toolName,
 		callId: approval.callId,
 		reason: `escalate sandbox to ${mode}: ${justification}`,
+		displayReason: {
+			en: `Allow this operation with ${mode} permissions: ${justification}`,
+			zh: `允许本次操作使用 ${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 "rejected": throw new Error(`the user rejected escalating this ${subject} to "${mode}"; it stays denied, so stop and explain instead of working around it`);
 		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");
@@ -272,4 +286,4 @@ var SandboxProvider = class extends Service {
 	}
 };
 //#endregion
-export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isRunnerSpawnFailure, matchesSignature, sandboxDenialMarker, validateEscalationArgs, writableRoots };
+export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isRunnerSpawnFailure, matchesSignature, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs, writableRoots };

package/lib/types/escalation.d.ts

@@ -60,6 +60,14 @@ export declare function sandboxDenialMarker(mode: SandboxMode): string;
  * @returns the hint line, exactly as the model sees it.
  */
 export declare function escalationHintMarker(subject: string): string;
+/**
+ * The model-facing `sandbox_permissions` parameter description, which carries
+ * the escalation rules for every enforcing family.
+ * @param subject - the family's noun for the denied action (`command` for
+ *   bash, `operation` for a filesystem mutation).
+ * @returns the parameter description, exactly as the model sees it.
+ */
+export declare function sandboxPermissionsDescription(subject: string): string;
 /**
  * The closed outcome vocabulary of one escalation ask — structurally identical
  * to the approval seam's `ApprovalOutcome` so an `ApprovalService.request`
@@ -76,7 +84,7 @@ export type EscalationOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'una
 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).
+     * @param req - the audit request with optional localized displayReason and presentation lifetime signal.
      * @returns the human's decision as a closed {@link EscalationOutcome}.
      */
     request(req: {
@@ -84,6 +92,10 @@ export interface EscalationApprover<A = object, C = string> {
         toolName: string;
         callId: C;
         reason: string;
+        displayReason?: {
+            readonly en: string;
+            readonly [locale: string]: string;
+        };
         signal?: AbortSignal;
     }): Promise<EscalationOutcome>;
 }

package/lib/types/index.d.ts

@@ -7,7 +7,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import { HarnessError } from '@deepseek-ai/dsh-llm';
 import type { SessionId } from '@deepseek-ai/dsh-session';
-export { ESCALATION_TARGETS, WIDER_MODES, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs, } from './escalation.ts';
+export { ESCALATION_TARGETS, WIDER_MODES, approveEscalation, escalationHintMarker, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs, } from './escalation.ts';
 export type { EscalationApproval, EscalationApprover, EscalationOutcome, EscalationRequest } from './escalation.ts';
 export { canonicalPath, writableRoots } from './roots.ts';
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox",
   "description": "Abstract process-sandbox seam (ctx.sandbox) for the DeepSeek Harness: same-world confinement vocabulary and the SandboxProvider contract",
-  "version": "0.1.7-rc.1",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -28,15 +28,15 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.1"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-util-values": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-util-values": "0.2.0-rc.1"
   }
 }