@songtonyli/dsh-cli 0.1.58 → 0.1.60
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/bin/dsh.mjs +1 -1
- package/node_modules/@deepseek-ai/dsh-agent-preset/skills/cordis-composition-reference/references/packages.md +1 -0
- package/node_modules/@deepseek-ai/dsh-api-session-controller/lib/client.js +1 -0
- package/node_modules/@deepseek-ai/dsh-client-ui-primitives/package.json +1 -1
- package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
- package/node_modules/@deepseek-ai/dsh-client-ui-slots/package.json +2 -2
- package/node_modules/@deepseek-ai/dsh-sandbox/lib/index.js +59 -4
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.i18n.yaml +73 -0
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.md +166 -0
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.zh.md +166 -0
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/exec-shim.js +227 -0
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/index.js +704 -0
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/package.json +62 -0
- package/node_modules/@deepseek-ai/dsh-sandbox-policy/README.i18n.yaml +2 -2
- package/node_modules/@deepseek-ai/dsh-sandbox-policy/README.md +1 -1
- package/node_modules/@deepseek-ai/dsh-sandbox-policy/README.zh.md +1 -1
- package/node_modules/@deepseek-ai/dsh-sandbox-policy/lib/index.js +23 -0
- package/node_modules/@deepseek-ai/dsh-session/lib/index.js +1 -0
- package/node_modules/@deepseek-ai/dsh-session/lib/types/known-event-types.js +1 -0
- package/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/worker.cjs +1 -0
- package/node_modules/@deepseek-ai/dsh-system-prompt/lib/index.js +1 -0
- package/node_modules/@deepseek-ai/dsh-tool-cordis/lib/types/api-catalog.js +22 -0
- package/node_modules/@deepseek-ai/dsh-tool-fs/README.i18n.yaml +2 -2
- package/node_modules/@deepseek-ai/dsh-tool-fs/README.md +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-fs/README.zh.md +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js +24 -0
- package/node_modules/@deepseek-ai/dsh-tool-fs-search/README.i18n.yaml +4 -4
- package/node_modules/@deepseek-ai/dsh-tool-fs-search/README.md +2 -2
- package/node_modules/@deepseek-ai/dsh-tool-fs-search/README.zh.md +2 -2
- package/node_modules/@deepseek-ai/dsh-tool-fs-search/lib/index.js +28 -3
- package/node_modules/@deepseek-ai/dsh-tool-fs-search/package.json +7 -2
- package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/README.i18n.yaml +2 -2
- package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/README.md +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/README.zh.md +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/lib/index.js +14 -6
- package/node_modules/@deepseek-ai/dsh-tui-app/README.i18n.yaml +8 -8
- package/node_modules/@deepseek-ai/dsh-tui-app/README.md +13 -7
- package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +13 -7
- package/node_modules/@deepseek-ai/dsh-tui-app/cordis.patch.yml +20 -0
- package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +2403 -2033
- package/node_modules/@deepseek-ai/dsh-tui-app/package.json +1 -0
- package/node_modules/@deepseek-ai/libreoffice-kit/README.md +20 -5
- package/node_modules/@deepseek-ai/libreoffice-kit/README.zh.md +21 -6
- package/node_modules/@deepseek-ai/libreoffice-kit/lib/cli.js +499 -253
- package/node_modules/@deepseek-ai/libreoffice-kit/lib/font-snapshot-worker.js +37 -26
- package/node_modules/@deepseek-ai/libreoffice-kit/lib/index.js +498 -252
- package/node_modules/@deepseek-ai/libreoffice-kit/lib/worker.js +39 -13
- package/node_modules/@deepseek-ai/libreoffice-kit/package.json +5 -3
- package/node_modules/@earendil-works/pi-ai/README.md +4 -3
- package/node_modules/@earendil-works/pi-ai/dist/api/anthropic-messages.js +117 -18
- package/node_modules/@earendil-works/pi-ai/dist/api/bedrock-converse-stream.js +1 -0
- package/node_modules/@earendil-works/pi-ai/dist/api/constrained-sampling.js +19 -8
- package/node_modules/@earendil-works/pi-ai/dist/api/mistral-conversations.js +1 -0
- package/node_modules/@earendil-works/pi-ai/dist/api/openai-completions.js +1 -0
- package/node_modules/@earendil-works/pi-ai/dist/api/openai-responses-shared.js +1 -0
- package/node_modules/@earendil-works/pi-ai/dist/api/pi-messages.js +2 -0
- package/node_modules/@earendil-works/pi-ai/dist/env-api-keys.js +5 -0
- package/node_modules/@earendil-works/pi-ai/dist/providers/anthropic.js +24 -2
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/.manifest.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/amazon-bedrock.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/azure-openai-responses.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/baseten.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/cerebras.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/github-copilot.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/openai.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/opencode.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/openrouter.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/radius.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/providers/data/vercel-ai-gateway.json +1 -1
- package/node_modules/@earendil-works/pi-ai/dist/utils/overflow.js +2 -1
- package/node_modules/@earendil-works/pi-ai/dist/utils/provider-retry.js +3 -2
- package/node_modules/@earendil-works/pi-ai/package.json +6 -2
- package/node_modules/@earendil-works/pi-telemetry/package.json +1 -1
- package/node_modules/@shikijs/core/dist/index.mjs +15 -12
- package/node_modules/@shikijs/core/package.json +4 -4
- package/node_modules/@shikijs/engine-javascript/dist/engine-compile.mjs +2 -4
- package/node_modules/@shikijs/engine-javascript/dist/engine-raw.mjs +2 -4
- package/node_modules/@shikijs/engine-javascript/dist/index.mjs +1 -1
- package/node_modules/@shikijs/engine-javascript/dist/string-TLTPtCPs.mjs +115 -0
- package/node_modules/@shikijs/engine-javascript/package.json +3 -3
- package/node_modules/@shikijs/engine-oniguruma/package.json +3 -3
- package/node_modules/@shikijs/langs/dist/ada.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/ahk.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/beancount.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/coq.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/csharp.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/css.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/dart.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/dotenv.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/emacs-lisp.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/gn.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/handlebars.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/julia.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/latex.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/luau.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/marko.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/moonbit.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/nextflow-groovy.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/nextflow.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/nushell.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/php.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/powershell.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/ruby.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/rust.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/sql.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/svelte.mjs +1 -1
- package/node_modules/@shikijs/langs/dist/twig.mjs +3 -3
- package/node_modules/@shikijs/langs/dist/typespec.mjs +1 -1
- package/node_modules/@shikijs/langs/package.json +3 -3
- package/node_modules/@shikijs/primitive/dist/index.mjs +2 -1
- package/node_modules/@shikijs/primitive/package.json +3 -3
- package/node_modules/@shikijs/themes/dist/monokai.mjs +1 -1
- package/node_modules/@shikijs/themes/dist/one-dark-pro.mjs +1 -1
- package/node_modules/@shikijs/themes/dist/red.mjs +1 -1
- package/node_modules/@shikijs/themes/dist/solarized-dark.mjs +1 -1
- package/node_modules/@shikijs/themes/dist/solarized-light.mjs +1 -1
- package/node_modules/@shikijs/themes/package.json +3 -3
- package/node_modules/@shikijs/types/package.json +1 -1
- package/node_modules/@smithy/core/dist-cjs/submodules/client/index.js +33 -11
- package/node_modules/@smithy/core/dist-cjs/submodules/schema/index.js +3 -0
- package/node_modules/@smithy/core/dist-es/submodules/client/smithy-client/exceptions.js +33 -11
- package/node_modules/@smithy/core/dist-es/submodules/schema/TypeRegistry.js +3 -0
- package/node_modules/@smithy/core/package.json +1 -1
- package/node_modules/node-addon-native-custom-loader/lib/index.js +23 -10
- package/node_modules/node-addon-native-custom-loader/package.json +6 -1
- package/node_modules/node-addon-require-builtin/package.json +7 -2
- package/node_modules/powershell-utils/index.js +40 -19
- package/node_modules/powershell-utils/package.json +1 -1
- package/node_modules/powershell-utils/readme.md +69 -13
- package/node_modules/shiki/package.json +10 -10
- package/node_modules/wsl-utils/index.js +18 -37
- package/node_modules/wsl-utils/package.json +2 -2
- package/package.json +33 -29
- package/node_modules/@shikijs/engine-javascript/dist/scanner-DX8LRFGE.mjs +0 -77
- package/node_modules/open/node_modules/powershell-utils/index.js +0 -79
- package/node_modules/open/node_modules/powershell-utils/license +0 -9
- package/node_modules/open/node_modules/powershell-utils/package.json +0 -47
- package/node_modules/open/node_modules/powershell-utils/readme.md +0 -209
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ workspace and no build step. Native packages that ship one build per platform
|
|
|
26
26
|
ripgrep, the PTY backend's addons, sharp, koffi, and the Landlock launcher — are
|
|
27
27
|
ordinary optional dependencies, so npm resolves the right one for your machine.
|
|
28
28
|
|
|
29
|
-
Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.
|
|
29
|
+
Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.60; `dsh --version`
|
|
30
30
|
also reports the harness build the package was assembled from.
|
|
31
31
|
|
|
32
32
|
## License
|
package/bin/dsh.mjs
CHANGED
|
@@ -18,7 +18,7 @@ const argv = process.argv.slice(2)
|
|
|
18
18
|
// version this package publishes. Reporting only one of the two would make an
|
|
19
19
|
// ordinary `npm install @songtonyli/dsh-cli@x` look like it installed something else.
|
|
20
20
|
if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
|
|
21
|
-
console.log('@songtonyli/dsh-cli 0.1.
|
|
21
|
+
console.log('@songtonyli/dsh-cli 0.1.60 (deepseek-harness 0.2.0-rc.2)')
|
|
22
22
|
process.exit(0)
|
|
23
23
|
}
|
|
24
24
|
|
|
@@ -337,6 +337,7 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
|
|
|
337
337
|
|
|
338
338
|
| Package | Config | Description |
|
|
339
339
|
|---|---|---|
|
|
340
|
+
| `@deepseek-ai/dsh-sandbox-apple-container` | yes | Apple container sandbox backend for the DeepSeek Harness sandbox seam: confined commands run in a per-workspace Linux VM with the workspace bind-mounted, switchable per session to the local backend |
|
|
340
341
|
| `@deepseek-ai/dsh-sandbox-local` | yes | Local process-sandbox backends for the DeepSeek Harness sandbox seam: bwrap, the npm-distributed landlock-run launcher, macOS Seatbelt, or the Windows ACL restricted-token runner — functionally probed, fail-closed |
|
|
341
342
|
| `@deepseek-ai/dsh-sandbox-policy` | yes | Per-call sandbox policy resolver and current model context: deployment fallbacks plus each session's mode and workspace root, shared by every enforcing capability family |
|
|
342
343
|
|
|
@@ -48,8 +48,8 @@
|
|
|
48
48
|
"micromark-util-sanitize-uri": "^2.0.1",
|
|
49
49
|
"simple-icons": "16.31.0",
|
|
50
50
|
"@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
|
|
51
|
-
"@deepseek-ai/dsh-util-workspace-path": "0.2.0-rc.2",
|
|
52
51
|
"@deepseek-ai/dsh-util-code-language": "0.2.0-rc.2",
|
|
52
|
+
"@deepseek-ai/dsh-util-workspace-path": "0.2.0-rc.2",
|
|
53
53
|
"@deepseek-ai/cordis": "~4.0.4"
|
|
54
54
|
},
|
|
55
55
|
"files": [
|
|
@@ -167,7 +167,7 @@ window.__ModuleLoader__.load({
|
|
|
167
167
|
const SCROLLBAR_LINGER_MS = 2e3;
|
|
168
168
|
/** Format complete-build metadata for the local brand badge. */
|
|
169
169
|
function localBuildVersion() {
|
|
170
|
-
return `0.2.0-rc.2-
|
|
170
|
+
return `0.2.0-rc.2-b920c06` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
|
|
171
171
|
}
|
|
172
172
|
/** Each panel row subscribes only to its own selection state. */
|
|
173
173
|
function PanelRow({ id, label, wide, usePanelInfo, selectPanel, renderSlot }) {
|
|
@@ -24,8 +24,8 @@
|
|
|
24
24
|
"license": "MIT",
|
|
25
25
|
"devDependencies": {
|
|
26
26
|
"@types/react": "~18.3.1",
|
|
27
|
-
"@deepseek-ai/
|
|
28
|
-
"@deepseek-ai/
|
|
27
|
+
"@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
|
|
28
|
+
"@deepseek-ai/cordis": "~4.0.4"
|
|
29
29
|
},
|
|
30
30
|
"files": [
|
|
31
31
|
"lib/index.js",
|
|
@@ -3,6 +3,7 @@ import { HarnessError } from "@deepseek-ai/dsh-llm";
|
|
|
3
3
|
import { assertNever } from "@deepseek-ai/dsh-util-values";
|
|
4
4
|
import { accessSync, constants, realpathSync, statSync } from "node:fs";
|
|
5
5
|
import { tmpdir } from "node:os";
|
|
6
|
+
import { basename, dirname, join, resolve, sep } from "node:path";
|
|
6
7
|
//#region lib/types/escalation.js
|
|
7
8
|
/**
|
|
8
9
|
* The escalation vocabulary and choreography shared by every sandbox-enforcing
|
|
@@ -171,6 +172,47 @@ function writableRoots(policy) {
|
|
|
171
172
|
tmpdir()
|
|
172
173
|
].map(canonicalPath))];
|
|
173
174
|
}
|
|
175
|
+
/**
|
|
176
|
+
* Canonicalize a path that may not exist yet: the deepest existing ancestor
|
|
177
|
+
* resolves through symlinks and the missing remainder is appended, after
|
|
178
|
+
* lexical `.`/`..` collapse.
|
|
179
|
+
* @param path - an absolute or process-relative path.
|
|
180
|
+
* @returns the canonical spelling a containment check compares.
|
|
181
|
+
*/
|
|
182
|
+
function canonicalTarget(path) {
|
|
183
|
+
const absolute = resolve(path);
|
|
184
|
+
const canonical = canonicalPath(absolute);
|
|
185
|
+
if (canonical !== absolute) return canonical;
|
|
186
|
+
const parent = dirname(absolute);
|
|
187
|
+
return parent === absolute ? absolute : join(canonicalTarget(parent), basename(absolute));
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Whether a file name matches a hidden-name glob, where `*` matches any run
|
|
191
|
+
* of characters and matching ignores case.
|
|
192
|
+
* @param name - a single path component.
|
|
193
|
+
* @param glob - a pattern such as `.env.*` or `id_rsa*`.
|
|
194
|
+
* @returns true when `name` matches the whole pattern.
|
|
195
|
+
*/
|
|
196
|
+
function matchesNameGlob(name, glob) {
|
|
197
|
+
const pattern = glob.split("*").map((part) => part.replaceAll(/[.+?^${}()|[\]\\]/gu, String.raw`\$&`)).join(".*");
|
|
198
|
+
return new RegExp(`^${pattern}$`, "iu").test(name);
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* Whether `path` is readable within `scope`: it lies inside a root after both
|
|
202
|
+
* are canonicalized (so neither `..` nor a symlink can leave the roots), and
|
|
203
|
+
* its file name matches no hidden-name glob.
|
|
204
|
+
* @param path - the host path a reader is about to open or search.
|
|
205
|
+
* @param scope - the read scope from `SandboxProvider.readScope`.
|
|
206
|
+
* @returns true when the path may be read.
|
|
207
|
+
*/
|
|
208
|
+
function isReadableIn(path, scope) {
|
|
209
|
+
const target = canonicalTarget(path);
|
|
210
|
+
if (scope.hiddenNames.some((glob) => matchesNameGlob(basename(target), glob))) return false;
|
|
211
|
+
return scope.roots.some((root) => {
|
|
212
|
+
const canonicalRoot = canonicalTarget(root);
|
|
213
|
+
return target === canonicalRoot || target.startsWith(canonicalRoot.endsWith(sep) ? canonicalRoot : `${canonicalRoot}${sep}`);
|
|
214
|
+
});
|
|
215
|
+
}
|
|
174
216
|
//#endregion
|
|
175
217
|
//#region lib/types/diagnostics.js
|
|
176
218
|
/** Classify observed sandbox runner failures and file-effect denials. */
|
|
@@ -250,9 +292,12 @@ function matchesSignature(exitCode, stderr, signatures) {
|
|
|
250
292
|
//#endregion
|
|
251
293
|
//#region lib/types/index.js
|
|
252
294
|
/**
|
|
253
|
-
* Service Definition for the
|
|
254
|
-
* host-path file policy
|
|
255
|
-
*
|
|
295
|
+
* Service Definition for the process-confinement capability seam: wrap exact
|
|
296
|
+
* subprocess argv under a host-path file policy, and report the host read
|
|
297
|
+
* scope that model-facing file tools must share. Providers either confine on
|
|
298
|
+
* the host kernel or, like the Apple container backend, run the argv in a VM
|
|
299
|
+
* that mounts the workspace at its host path; remote execution replaces the
|
|
300
|
+
* surrounding capability seam instead.
|
|
256
301
|
* @module @deepseek-ai/dsh-sandbox
|
|
257
302
|
*/
|
|
258
303
|
/**
|
|
@@ -284,6 +329,16 @@ var SandboxProvider = class extends Service {
|
|
|
284
329
|
constructor(ctx) {
|
|
285
330
|
super(ctx, "sandbox");
|
|
286
331
|
}
|
|
332
|
+
/**
|
|
333
|
+
* What a process confined under `policy` can read on the host, or
|
|
334
|
+
* `undefined` when this backend does not confine reads. Model-facing tools
|
|
335
|
+
* that read the host for the same session must refuse paths outside the
|
|
336
|
+
* scope, so their view never exceeds the confined processes'. The base
|
|
337
|
+
* implementation confines no reads.
|
|
338
|
+
* @param _policy - the file-effect policy of the calling session.
|
|
339
|
+
* @returns the read scope, or `undefined` for unconfined reads.
|
|
340
|
+
*/
|
|
341
|
+
readScope(_policy) {}
|
|
287
342
|
};
|
|
288
343
|
//#endregion
|
|
289
|
-
export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isRunnerSpawnFailure, matchesSignature, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs, writableRoots };
|
|
344
|
+
export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isReadableIn, isRunnerSpawnFailure, matchesNameGlob, matchesSignature, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs, writableRoots };
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
|
|
2
|
+
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
|
|
3
|
+
# After editing either side, bring the other along and re-record with:
|
|
4
|
+
# pnpm run verify-translation-pairing --write packages/sandbox/sandbox-apple-container/README.md
|
|
5
|
+
/:
|
|
6
|
+
en: f5db367582d648e9
|
|
7
|
+
zh: 10d241446995742e
|
|
8
|
+
/deepseek-ai-dsh-sandbox-apple-container:
|
|
9
|
+
en: fd474288bb2dac31
|
|
10
|
+
zh: e0e109692d3df1c4
|
|
11
|
+
/deepseek-ai-dsh-sandbox-apple-container/summary:
|
|
12
|
+
en: 6fcdeb62db78134c
|
|
13
|
+
zh: e710602af4bd1a41
|
|
14
|
+
/deepseek-ai-dsh-sandbox-apple-container/table-of-contents:
|
|
15
|
+
en: d152484eb41ac6b4
|
|
16
|
+
zh: 09388d293f9be9cb
|
|
17
|
+
/deepseek-ai-dsh-sandbox-apple-container/use-this-package:
|
|
18
|
+
en: ec93fe28f7da27d7
|
|
19
|
+
zh: 36718f53bcbb2bf5
|
|
20
|
+
/deepseek-ai-dsh-sandbox-apple-container/use-this-package/when-to-choose-it:
|
|
21
|
+
en: d49845cf75f81420
|
|
22
|
+
zh: 331b90bec2afb896
|
|
23
|
+
/deepseek-ai-dsh-sandbox-apple-container/use-this-package/minimal-configuration:
|
|
24
|
+
en: 1a7a36bfc29d9f18
|
|
25
|
+
zh: 1769b4d7bfae4f95
|
|
26
|
+
/deepseek-ai-dsh-sandbox-apple-container/use-this-package/switching-a-session:
|
|
27
|
+
en: fe0f7d5ac6160763
|
|
28
|
+
zh: 4e1455a8559d46ca
|
|
29
|
+
/deepseek-ai-dsh-sandbox-apple-container/use-this-package/what-confinement-covers:
|
|
30
|
+
en: db58fc9ee37b3ac9
|
|
31
|
+
zh: c4d7f44c9209a61e
|
|
32
|
+
/deepseek-ai-dsh-sandbox-apple-container/use-this-package/failures-and-recovery:
|
|
33
|
+
en: 79782500f91b1f06
|
|
34
|
+
zh: a132d680acb85edc
|
|
35
|
+
/deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation:
|
|
36
|
+
en: 42b15ac6321706aa
|
|
37
|
+
zh: c8011788e17a2cd6
|
|
38
|
+
/deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation/containers:
|
|
39
|
+
en: 7087986d3a71c0b6
|
|
40
|
+
zh: a94c3e9ed81e9b7e
|
|
41
|
+
/deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation/execution-shim:
|
|
42
|
+
en: 62f9ae7df4c108d9
|
|
43
|
+
zh: a1efc34390a80364
|
|
44
|
+
/deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation/source-map:
|
|
45
|
+
en: 866bf8dec1ab38ba
|
|
46
|
+
zh: af875a19b5ceb7b9
|
|
47
|
+
/deepseek-ai-dsh-sandbox-apple-container/further-exploration:
|
|
48
|
+
en: b355596cf895ca5c
|
|
49
|
+
zh: 428721b37381c782
|
|
50
|
+
/deepseek-ai-dsh-sandbox-apple-container/model-experience:
|
|
51
|
+
en: 215e7ba838619b7b
|
|
52
|
+
zh: a311da3843709f90
|
|
53
|
+
/deepseek-ai-dsh-sandbox-apple-container/model-experience/container-backend-context:
|
|
54
|
+
en: 2c476ee0e446e672
|
|
55
|
+
zh: 0e29da370c83a81c
|
|
56
|
+
/deepseek-ai-dsh-sandbox-apple-container/model-experience/container-backend-context/what-the-model-sees:
|
|
57
|
+
en: f30fafaeefc6b28b
|
|
58
|
+
zh: 46d7e90e11d3d0d7
|
|
59
|
+
/deepseek-ai-dsh-sandbox-apple-container/model-experience/container-backend-context/what-the-model-sees/container-backend:
|
|
60
|
+
en: 25979839c019b197
|
|
61
|
+
zh: 1ada36cc7f551286
|
|
62
|
+
/deepseek-ai-dsh-sandbox-apple-container/model-experience/container-backend-context/token-effect:
|
|
63
|
+
en: 163b29c0c5c5ea52
|
|
64
|
+
zh: 1cc3123cb27d99e5
|
|
65
|
+
/deepseek-ai-dsh-sandbox-apple-container/model-experience/container-backend-context/kv-cache-effect:
|
|
66
|
+
en: 3ab9e835ea38981a
|
|
67
|
+
zh: 4839ebd84726eca0
|
|
68
|
+
/deepseek-ai-dsh-sandbox-apple-container/known-limitations-and-deferred-work:
|
|
69
|
+
en: 774a7b78c802da01
|
|
70
|
+
zh: 920961d8b70297ba
|
|
71
|
+
/deepseek-ai-dsh-sandbox-apple-container/known-limitations-and-deferred-work/dev-note:
|
|
72
|
+
en: d96c06feb419a24e
|
|
73
|
+
zh: d8c3b5781c9c1690
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "The Apple container sandbox backend for users and maintainers who run confined commands in a per-workspace Linux VM on macOS and switch sessions between the container and the local sandbox."
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @deepseek-ai/dsh-sandbox-apple-container
|
|
7
|
+
|
|
8
|
+
English | [中文](README.zh.md)
|
|
9
|
+
|
|
10
|
+
## Summary
|
|
11
|
+
|
|
12
|
+
Use this package to run confined bash, terminal, and PTC commands inside an [Apple `container`](https://github.com/apple/container) Linux VM on macOS on Apple silicon. The VM mounts only the session workspace at its host path, so commands cannot read or change other host files, and the model's file tools are held to the same read scope. Secret files such as `.env` are masked, credential-shaped environment variables never reach the guest, and `.git` stays read-only. On every other host, and for sessions switched with `/sandbox local`, the package confines through the inherited local sandbox chain.
|
|
13
|
+
|
|
14
|
+
## Table of Contents
|
|
15
|
+
|
|
16
|
+
- [Use this package](#use-this-package)
|
|
17
|
+
- [Understand the implementation](#understand-the-implementation)
|
|
18
|
+
- [Further Exploration](#further-exploration)
|
|
19
|
+
- [Model Experience](#model-experience)
|
|
20
|
+
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
|
|
21
|
+
- [Dev Note](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## Use this package
|
|
27
|
+
|
|
28
|
+
Mount this package in place of `@deepseek-ai/dsh-sandbox-local` as the `ctx.sandbox` provider, beside `@deepseek-ai/dsh-sandbox-policy`. The shipped terminal profile does so: it disables the base `sandbox` row and inserts this package with `backend: auto`.
|
|
29
|
+
|
|
30
|
+
### When to choose it
|
|
31
|
+
|
|
32
|
+
Choose it when confined commands should not see the user's home directory, keys, or other repositories, and the host is a Mac with Apple silicon, macOS 26, and the `container` CLI installed (`brew install container`, then `container system start`). Keep the local provider when commands need host-only toolchains, such as Xcode or Darwin-native `node_modules` binaries.
|
|
33
|
+
|
|
34
|
+
### Minimal configuration
|
|
35
|
+
|
|
36
|
+
```yaml
|
|
37
|
+
- id: sandbox
|
|
38
|
+
disabled: true
|
|
39
|
+
- insert:
|
|
40
|
+
- name: '@deepseek-ai/dsh-sandbox-apple-container'
|
|
41
|
+
config:
|
|
42
|
+
backend: auto
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| Field | Default | Meaning |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `backend` | `auto` | Default backend: `auto` selects `container` on macOS on Apple silicon when the CLI resolves and `local` elsewhere; `container` and `local` are fixed |
|
|
48
|
+
| `executable` | `container` | The `container` CLI, resolved on `PATH` when bare |
|
|
49
|
+
| `image` | `node:22-bookworm` | OCI image every owned container runs; it must provide `sh` and util-linux `setsid` |
|
|
50
|
+
| `cpus`, `memory` | unset | Per-container resources; unset uses the `container` system defaults |
|
|
51
|
+
| `autoStart` | `true` | Run `container system start` once when the API server is stopped |
|
|
52
|
+
| `recheckMs` | `10000` | Minimum interval between liveness checks of a cached container |
|
|
53
|
+
| `envDenylist` | host paths plus `*KEY*`, `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `*PASSWD*`, `*CREDENTIAL*`, `*COOKIE*`, `*PRIVATE*`, `AWS_*` | Environment name globs never forwarded to the guest, even when a composition passes them explicitly |
|
|
54
|
+
| `readOnlyMounts` | `[]` | Absolute host directories mounted read-only at their own paths and readable by file tools; the terminal profile mounts the user skill roots |
|
|
55
|
+
| `protectedPaths` | `['.git']` | Workspace-relative directories mounted read-only under `workspace-write` |
|
|
56
|
+
| `hiddenFiles` | `.env`, `.env.*`, `.envrc`, private-key and certificate names, `.npmrc`, `.pypirc`, `.netrc`, `.git-credentials` | File-name globs masked in the guest and refused by file tools |
|
|
57
|
+
| `hiddenFilesMaxDepth`, `hiddenFilesSkipDirs` | `8`, `['node_modules', '.git']` | Bounds of the workspace scan that finds files to mask when a container starts |
|
|
58
|
+
|
|
59
|
+
The fields of `@deepseek-ai/dsh-sandbox-local` also apply to the `local` backend. The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-sandbox-apple-container) is the exhaustive source for every field and its JSDoc.
|
|
60
|
+
|
|
61
|
+
### Switching a session
|
|
62
|
+
|
|
63
|
+
`/sandbox` reports the session's backend, the image, and each owned container's state. `/sandbox container` and `/sandbox local` record a `sandbox/backend` event; the session's next confined call uses the new backend, and the choice survives restart. `/sandbox container` is refused on hosts that cannot run Apple `container`.
|
|
64
|
+
|
|
65
|
+
### What confinement covers
|
|
66
|
+
|
|
67
|
+
| Threat | Behavior under the container backend |
|
|
68
|
+
|---|---|
|
|
69
|
+
| A command reads host files outside the workspace | The path does not exist in the guest |
|
|
70
|
+
| A file tool reads outside the workspace | `read`, `edit`, `write`, `str_replace_editor`, `grep`, and `glob` refuse it through the read scope |
|
|
71
|
+
| A command or tool reads a secret file in the workspace | Masked to `/dev/null` in the guest; refused by file tools; excluded from `grep` |
|
|
72
|
+
| A credential reaches the guest environment | Denied names and URLs carrying `user:password@` are never forwarded |
|
|
73
|
+
| A command plants a Git hook or config the host later runs | `.git` is read-only under `workspace-write`; writes fail with `Read-only file system` and use the normal escalation |
|
|
74
|
+
| A command writes outside the workspace | The write lands in the container's own disk and never reaches the host |
|
|
75
|
+
|
|
76
|
+
`danger-full-access` bypasses `confine`, so it runs on the host under either backend.
|
|
77
|
+
|
|
78
|
+
### Failures and recovery
|
|
79
|
+
|
|
80
|
+
Missing CLI, a stopped API server that cannot start, or a failed `container run` rejects the confined call with `SANDBOX_UNAVAILABLE`, and the message names `/sandbox local`. A `read-only` write denial reports `Read-only file system`, which the tool layer offers for the standard one-time escalation. Invalid `envDenylist`, `readOnlyMounts`, `protectedPaths`, or `cpus` values fail at load.
|
|
81
|
+
|
|
82
|
+
-----
|
|
83
|
+
|
|
84
|
+
<a id="understand-the-implementation"></a>
|
|
85
|
+
## Understand the implementation
|
|
86
|
+
|
|
87
|
+
<details>
|
|
88
|
+
<summary>Implementation internals — click to expand</summary>
|
|
89
|
+
|
|
90
|
+
### Containers
|
|
91
|
+
|
|
92
|
+
The provider owns one container per canonical workspace root and confined mode, shared by every session and subagent in that workspace and mode. It starts with `container run --detach --init --rm`, labelled with the owning process id, bind-mounted with `--mount type=bind,…` (the `-v src:dst:ro` form is not used because `container` 1.5.0 misparses it), and idles on `sleep infinity`. A cached container is re-inspected at most once per `recheckMs` and restarted when gone; disposal deletes every owned container, and load deletes containers whose labelled process has exited. When the default backend is `container` and the deployment default mode is confined, the default-mode container starts in the background at load.
|
|
93
|
+
|
|
94
|
+
### Execution shim
|
|
95
|
+
|
|
96
|
+
`confine` returns `[node, exec-shim.js, <executable>, <container>, <denylist>, '--', ...argv]`. The shim runs on the host with the caller's working directory and environment, writes the filtered environment to a private `--env-file`, and runs `container exec -i [-t] -w <cwd>` with the argv under `setsid -w` in the guest. Because `container exec` does not forward signals, the shim records the guest process-group id and signals that group itself; a forwarded signal exits `128 + n`. A start sentinel separates a runtime failure, reported as `dsh-container-exec: …` with exit 125 and classified by the runner-failure rule, from a command that ran and failed. The built `lib/exec-shim.js` depends only on Node built-ins and runs under plain Node in the npm-installed CLI; a source checkout launches `src/exec-shim.ts` through tsx.
|
|
97
|
+
|
|
98
|
+
### Source map
|
|
99
|
+
|
|
100
|
+
| File | Role |
|
|
101
|
+
|---|---|
|
|
102
|
+
| [`src/index.ts`](src/index.ts) | Provider: config, per-session routing, `readScope`, `/sandbox`, context contribution, warm-up and sweep |
|
|
103
|
+
| [`src/pool.ts`](src/pool.ts) | Owned containers, mounts, masks, liveness recheck, disposal |
|
|
104
|
+
| [`src/runtime.ts`](src/runtime.ts) | Typed `container` CLI calls |
|
|
105
|
+
| [`src/shim.ts`](src/shim.ts), [`src/exec-shim.ts`](src/exec-shim.ts) | Exec-shim logic and its process entry |
|
|
106
|
+
| [`src/secrets.ts`](src/secrets.ts) | Workspace scan for files to mask |
|
|
107
|
+
| [`src/host.ts`](src/host.ts) | Host support and `auto` resolution |
|
|
108
|
+
| [`src/session-backend.ts`](src/session-backend.ts) | The `sandbox/backend` event and its write path |
|
|
109
|
+
|
|
110
|
+
</details>
|
|
111
|
+
|
|
112
|
+
-----
|
|
113
|
+
|
|
114
|
+
<a id="further-exploration"></a>
|
|
115
|
+
## Further Exploration
|
|
116
|
+
|
|
117
|
+
- [Process sandbox subsystem](../../../docs/subsystems/sandbox.md) — modes, per-call policy, and the read scope.
|
|
118
|
+
- [Apple container sandbox decision](../../../.agents/notes/implemented/feature/2026-10-01-apple-container-sandbox-backend.md) — why a VM backend joins the sandbox seam, and the alternatives.
|
|
119
|
+
- [Local provider](../sandbox-local/README.md) — the backend this package inherits for `local` sessions.
|
|
120
|
+
|
|
121
|
+
-----
|
|
122
|
+
|
|
123
|
+
<a id="model-experience"></a>
|
|
124
|
+
## Model Experience
|
|
125
|
+
|
|
126
|
+
### Container backend context
|
|
127
|
+
|
|
128
|
+
#### What the model sees
|
|
129
|
+
|
|
130
|
+
One `sandbox:backend` contribution in the runtime-context snapshot when the session resolves to the `container` backend under a confined mode; it is empty under `local` and `danger-full-access`. `<image>` and `<workspace root>` are JSON-quoted.
|
|
131
|
+
|
|
132
|
+
##### Container backend
|
|
133
|
+
|
|
134
|
+
```markdown
|
|
135
|
+
Commands confined by the DSH file sandbox run inside a Linux container from image <image>. Only the session workspace <workspace root> is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools cannot read host paths outside the workspace, and secret files such as `.env` and private keys are hidden from commands and file tools.
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
#### Token effect
|
|
139
|
+
|
|
140
|
+
About sixty tokens in the context snapshot of the first request and of each request after the backend or mode changes the text; unchanged requests add nothing.
|
|
141
|
+
|
|
142
|
+
#### KV Cache effect
|
|
143
|
+
|
|
144
|
+
The stable system prompt is unchanged. A changed context snapshot is appended after retained history, preserving the cached prefix; switching the backend or mode is the only package-owned change to the text.
|
|
145
|
+
|
|
146
|
+
## Known Limitations and Deferred Work
|
|
147
|
+
|
|
148
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
149
|
+
|
|
150
|
+
- **Masks cover files present at container start** — `container` masks only paths that exist at creation, so a secret file created later is readable by commands in the running container until it restarts; file tools refuse it immediately.
|
|
151
|
+
- **Single-file mounts are unsupported** — `container` 1.5.0 binds only directories, so protection works per directory (`.git`), not per file (`.git/config`).
|
|
152
|
+
- **Subagents start on the default backend** — a child session does not inherit its parent's `/sandbox` choice.
|
|
153
|
+
- **Terminal resizes do not reach the guest** — `container exec` does not forward `SIGWINCH`.
|
|
154
|
+
- **Host and guest toolchains differ** — Darwin-native binaries in the workspace do not run in the Linux guest; use `/sandbox local` for those projects.
|
|
155
|
+
|
|
156
|
+
<a id="dev-note"></a>
|
|
157
|
+
### Dev Note
|
|
158
|
+
|
|
159
|
+
<details>
|
|
160
|
+
<summary>Working context for maintainers — click to expand</summary>
|
|
161
|
+
|
|
162
|
+
No invariant companion is published: the `sandboxBackend` projection validates every folded `sandbox/backend` value against its two-value state schema, so a forged value fails at replay without a separate observation.
|
|
163
|
+
|
|
164
|
+
Revisit the `-v` parsing, signal-forwarding, and single-file-mount workarounds when upgrading `container`; its releases are product versions, not semantic versions.
|
|
165
|
+
|
|
166
|
+
</details>
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Apple container 沙箱后端,面向在 macOS 上于按工作区划分的 Linux 虚拟机中运行受限命令、并在容器与本地沙箱之间切换会话的用户和维护者。"
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @deepseek-ai/dsh-sandbox-apple-container
|
|
7
|
+
|
|
8
|
+
[English](README.md) | 中文
|
|
9
|
+
|
|
10
|
+
## 概述
|
|
11
|
+
|
|
12
|
+
使用本包可以在搭载 Apple 芯片的 macOS 上,于 [Apple `container`](https://github.com/apple/container) Linux 虚拟机中运行受限的 bash、终端与 PTC 命令。虚拟机只在宿主机路径处挂载会话工作区,因此命令无法读取或修改其他宿主机文件,模型的文件工具也受同一读取范围约束。`.env` 等密钥文件被遮蔽,形似凭据的环境变量永远不会进入客户机,`.git` 保持只读。在其他所有主机上,以及通过 `/sandbox local` 切换的会话中,本包通过继承的本地沙箱链进行限制。
|
|
13
|
+
|
|
14
|
+
## 目录
|
|
15
|
+
|
|
16
|
+
- [使用本包](#use-this-package)
|
|
17
|
+
- [理解实现](#understand-the-implementation)
|
|
18
|
+
- [进一步探索](#further-exploration)
|
|
19
|
+
- [模型体验](#model-experience)
|
|
20
|
+
- [已知限制与延期工作](#known-limitations-and-deferred-work)
|
|
21
|
+
- [开发备注](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## 使用本包
|
|
27
|
+
|
|
28
|
+
将本包作为 `ctx.sandbox` 提供方挂载,取代 `@deepseek-ai/dsh-sandbox-local`,并与 `@deepseek-ai/dsh-sandbox-policy` 并列。随附的终端 profile 正是如此:它禁用基础的 `sandbox` 行,并以 `backend: auto` 插入本包。
|
|
29
|
+
|
|
30
|
+
### 何时选择
|
|
31
|
+
|
|
32
|
+
当受限命令不应看到用户的主目录、密钥或其他仓库,且宿主机是搭载 Apple 芯片、运行 macOS 26 并已安装 `container` CLI 的 Mac 时(`brew install container`,然后 `container system start`),选择本包。当命令需要仅存在于宿主机的工具链(例如 Xcode 或 Darwin 原生的 `node_modules` 二进制)时,保留本地提供方。
|
|
33
|
+
|
|
34
|
+
### 最小配置
|
|
35
|
+
|
|
36
|
+
```yaml
|
|
37
|
+
- id: sandbox
|
|
38
|
+
disabled: true
|
|
39
|
+
- insert:
|
|
40
|
+
- name: '@deepseek-ai/dsh-sandbox-apple-container'
|
|
41
|
+
config:
|
|
42
|
+
backend: auto
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| 字段 | 默认值 | 含义 |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `backend` | `auto` | 默认后端:`auto` 在 CLI 可解析的 Apple 芯片 macOS 上选择 `container`,其他情况选择 `local`;`container` 与 `local` 为固定值 |
|
|
48
|
+
| `executable` | `container` | `container` CLI;为裸名称时在 `PATH` 上解析 |
|
|
49
|
+
| `image` | `node:22-bookworm` | 每个自有容器运行的 OCI 镜像;必须提供 `sh` 与 util-linux 的 `setsid` |
|
|
50
|
+
| `cpus`、`memory` | 未设置 | 每个容器的资源;未设置时使用 `container` 系统默认值 |
|
|
51
|
+
| `autoStart` | `true` | API 服务器停止时运行一次 `container system start` |
|
|
52
|
+
| `recheckMs` | `10000` | 对缓存容器两次存活检查之间的最小间隔 |
|
|
53
|
+
| `envDenylist` | 宿主机路径以及 `*KEY*`、`*TOKEN*`、`*SECRET*`、`*PASSWORD*`、`*PASSWD*`、`*CREDENTIAL*`、`*COOKIE*`、`*PRIVATE*`、`AWS_*` | 永不转发到客户机的环境变量名通配模式,即使组合显式传入也不转发 |
|
|
54
|
+
| `readOnlyMounts` | `[]` | 以只读方式挂载在其自身路径、且文件工具可读取的宿主机绝对目录;终端 profile 挂载用户技能根目录 |
|
|
55
|
+
| `protectedPaths` | `['.git']` | 在 `workspace-write` 下以只读方式挂载的工作区相对目录 |
|
|
56
|
+
| `hiddenFiles` | `.env`、`.env.*`、`.envrc`、私钥与证书文件名、`.npmrc`、`.pypirc`、`.netrc`、`.git-credentials` | 在客户机中被遮蔽、并被文件工具拒绝的文件名通配模式 |
|
|
57
|
+
| `hiddenFilesMaxDepth`、`hiddenFilesSkipDirs` | `8`、`['node_modules', '.git']` | 容器启动时查找待遮蔽文件的工作区扫描范围 |
|
|
58
|
+
|
|
59
|
+
`@deepseek-ai/dsh-sandbox-local` 的字段同样适用于 `local` 后端。生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-sandbox-apple-container)是每个字段及其 JSDoc 的完整来源。
|
|
60
|
+
|
|
61
|
+
### 切换会话
|
|
62
|
+
|
|
63
|
+
`/sandbox` 报告会话的后端、镜像以及每个自有容器的状态。`/sandbox container` 与 `/sandbox local` 记录一个 `sandbox/backend` 事件;会话的下一次受限调用使用新后端,且该选择在重启后保留。在无法运行 Apple `container` 的主机上,`/sandbox container` 会被拒绝。
|
|
64
|
+
|
|
65
|
+
### 限制所覆盖的范围
|
|
66
|
+
|
|
67
|
+
| 威胁 | container 后端下的行为 |
|
|
68
|
+
|---|---|
|
|
69
|
+
| 命令读取工作区之外的宿主机文件 | 该路径在客户机中不存在 |
|
|
70
|
+
| 文件工具读取工作区之外的内容 | `read`、`edit`、`write`、`str_replace_editor`、`grep` 与 `glob` 通过读取范围拒绝 |
|
|
71
|
+
| 命令或工具读取工作区中的密钥文件 | 在客户机中被遮蔽为 `/dev/null`;被文件工具拒绝;从 `grep` 中排除 |
|
|
72
|
+
| 凭据进入客户机环境 | 被拒绝的名称以及带有 `user:password@` 的 URL 永不转发 |
|
|
73
|
+
| 命令植入宿主机之后会执行的 Git hook 或配置 | 在 `workspace-write` 下 `.git` 为只读;写入以 `Read-only file system` 失败,并走常规提权流程 |
|
|
74
|
+
| 命令写入工作区之外 | 写入落在容器自己的磁盘上,永远不会到达宿主机 |
|
|
75
|
+
|
|
76
|
+
`danger-full-access` 绕过 `confine`,因此在任一后端下都在宿主机上运行。
|
|
77
|
+
|
|
78
|
+
### 失败与恢复
|
|
79
|
+
|
|
80
|
+
CLI 缺失、已停止且无法启动的 API 服务器,或 `container run` 失败,都会以 `SANDBOX_UNAVAILABLE` 拒绝受限调用,消息中会提到 `/sandbox local`。`read-only` 下被拒绝的写入报告 `Read-only file system`,工具层会为此提供标准的一次性提权。无效的 `envDenylist`、`readOnlyMounts`、`protectedPaths` 或 `cpus` 值在加载时失败。
|
|
81
|
+
|
|
82
|
+
-----
|
|
83
|
+
|
|
84
|
+
<a id="understand-the-implementation"></a>
|
|
85
|
+
## 理解实现
|
|
86
|
+
|
|
87
|
+
<details>
|
|
88
|
+
<summary>实现细节 — 点击展开</summary>
|
|
89
|
+
|
|
90
|
+
### 容器
|
|
91
|
+
|
|
92
|
+
提供方为每个规范化的工作区根目录与受限模式各持有一个容器,由该工作区与模式下的所有会话和子智能体共享。容器以 `container run --detach --init --rm` 启动,带有所属进程 id 的标签,使用 `--mount type=bind,…` 绑定挂载(不使用 `-v src:dst:ro` 形式,因为 `container` 1.5.0 会错误解析它),并以 `sleep infinity` 空转。缓存的容器每 `recheckMs` 至多重新检查一次,消失时重新启动;销毁时删除所有自有容器,加载时删除其标签进程已退出的容器。当默认后端为 `container` 且部署默认模式为受限模式时,默认模式的容器会在加载时于后台启动。
|
|
93
|
+
|
|
94
|
+
### 执行 shim
|
|
95
|
+
|
|
96
|
+
`confine` 返回 `[node, exec-shim.js, <executable>, <container>, <denylist>, '--', ...argv]`。shim 以调用方的工作目录与环境在宿主机上运行,将过滤后的环境写入私有的 `--env-file`,并在客户机中通过 `setsid -w` 以 `container exec -i [-t] -w <cwd>` 运行 argv。由于 `container exec` 不转发信号,shim 记录客户机的进程组 id 并自行向该进程组发送信号;被转发的信号以 `128 + n` 退出。启动哨兵文件用于区分运行时失败(以 `dsh-container-exec: …` 报告、退出码 125,并由运行器失败规则分类)与已运行但失败的命令。构建后的 `lib/exec-shim.js` 只依赖 Node 内置模块,可在 npm 安装的 CLI 中以纯 Node 运行;源码检出则通过 tsx 启动 `src/exec-shim.ts`。
|
|
97
|
+
|
|
98
|
+
### 源码地图
|
|
99
|
+
|
|
100
|
+
| 文件 | 职责 |
|
|
101
|
+
|---|---|
|
|
102
|
+
| [`src/index.ts`](src/index.ts) | 提供方:配置、按会话路由、`readScope`、`/sandbox`、上下文贡献、预热与清理 |
|
|
103
|
+
| [`src/pool.ts`](src/pool.ts) | 自有容器、挂载、遮蔽、存活重检与销毁 |
|
|
104
|
+
| [`src/runtime.ts`](src/runtime.ts) | 类型化的 `container` CLI 调用 |
|
|
105
|
+
| [`src/shim.ts`](src/shim.ts)、[`src/exec-shim.ts`](src/exec-shim.ts) | exec shim 逻辑及其进程入口 |
|
|
106
|
+
| [`src/secrets.ts`](src/secrets.ts) | 查找待遮蔽文件的工作区扫描 |
|
|
107
|
+
| [`src/host.ts`](src/host.ts) | 主机支持判断与 `auto` 解析 |
|
|
108
|
+
| [`src/session-backend.ts`](src/session-backend.ts) | `sandbox/backend` 事件及其写入路径 |
|
|
109
|
+
|
|
110
|
+
</details>
|
|
111
|
+
|
|
112
|
+
-----
|
|
113
|
+
|
|
114
|
+
<a id="further-exploration"></a>
|
|
115
|
+
## 进一步探索
|
|
116
|
+
|
|
117
|
+
- [进程沙箱子系统](../../../docs/subsystems/sandbox.zh.md) — 模式、逐调用策略与读取范围。
|
|
118
|
+
- [Apple container 沙箱决策](../../../.agents/notes/implemented/feature/2026-10-01-apple-container-sandbox-backend.zh.md) — 虚拟机后端为何加入沙箱 seam,以及备选方案。
|
|
119
|
+
- [本地提供方](../sandbox-local/README.zh.md) — 本包为 `local` 会话继承的后端。
|
|
120
|
+
|
|
121
|
+
-----
|
|
122
|
+
|
|
123
|
+
<a id="model-experience"></a>
|
|
124
|
+
## 模型体验
|
|
125
|
+
|
|
126
|
+
### container 后端上下文
|
|
127
|
+
|
|
128
|
+
#### 模型看到什么
|
|
129
|
+
|
|
130
|
+
当会话在受限模式下解析为 `container` 后端时,运行时上下文快照中会有一条 `sandbox:backend` 贡献;在 `local` 与 `danger-full-access` 下为空。`<image>` 与 `<workspace root>` 以 JSON 引号包裹。
|
|
131
|
+
|
|
132
|
+
##### container 后端
|
|
133
|
+
|
|
134
|
+
```markdown
|
|
135
|
+
Commands confined by the DSH file sandbox run inside a Linux container from image <image>. Only the session workspace <workspace root> is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools cannot read host paths outside the workspace, and secret files such as `.env` and private keys are hidden from commands and file tools.
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
#### Token 影响
|
|
139
|
+
|
|
140
|
+
约六十个 token,出现在首次请求以及后端或模式改变该文本后的每次请求的上下文快照中;未变化的请求不增加任何内容。
|
|
141
|
+
|
|
142
|
+
#### KV Cache 影响
|
|
143
|
+
|
|
144
|
+
稳定的系统提示词保持不变。变化后的上下文快照追加在保留的历史之后,保持已缓存的前缀;切换后端或模式是本包唯一会改变该文本的操作。
|
|
145
|
+
|
|
146
|
+
## 已知限制与延期工作
|
|
147
|
+
|
|
148
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
149
|
+
|
|
150
|
+
- **遮蔽只覆盖容器启动时已存在的文件** — `container` 只遮蔽创建时存在的路径,因此之后创建的密钥文件在容器重启前可被运行中容器内的命令读取;文件工具会立即拒绝它。
|
|
151
|
+
- **不支持单文件挂载** — `container` 1.5.0 只能绑定目录,因此保护以目录(`.git`)为单位,而非文件(`.git/config`)。
|
|
152
|
+
- **子智能体从默认后端开始** — 子会话不继承父会话的 `/sandbox` 选择。
|
|
153
|
+
- **终端尺寸变化不会传到客户机** — `container exec` 不转发 `SIGWINCH`。
|
|
154
|
+
- **宿主机与客户机工具链不同** — 工作区中的 Darwin 原生二进制无法在 Linux 客户机中运行;此类项目请使用 `/sandbox local`。
|
|
155
|
+
|
|
156
|
+
<a id="dev-note"></a>
|
|
157
|
+
### 开发备注
|
|
158
|
+
|
|
159
|
+
<details>
|
|
160
|
+
<summary>维护者工作上下文 — 点击展开</summary>
|
|
161
|
+
|
|
162
|
+
未发布 `./invariant` 配套模块:`sandboxBackend` 投影会用其二值状态 schema 校验每个折叠的 `sandbox/backend` 值,因此伪造的值会在回放时失败,无需额外的独立观察。
|
|
163
|
+
|
|
164
|
+
升级 `container` 时,请重新评估 `-v` 解析、信号转发与单文件挂载这几项绕行措施;其版本号是产品版本,而非语义化版本。
|
|
165
|
+
|
|
166
|
+
</details>
|