refactor: hide sandbox implementation helpers

packages/bash/bash-sandbox/README.md

@@ -2,6 +2,8 @@
 
 Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) — the model-facing tool layer (`dsh-tool-bash`) is untouched; that swap is exactly what the seams exist for.
 
+The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; quoting and result-classification helpers stay internal.
+
 Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned (wrapped) argv instead. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.
 
 | Mode | File effects |

packages/bash/bash-sandbox/src/helpers.ts

@@ -0,0 +1,49 @@
+/**
+ * Internal shell-quoting and sandbox-result classification helpers.
+ *
+ * @module @deepseek-ai/dsh-bash-sandbox/helpers
+ */
+
+import type { BashRunResult } from '@deepseek-ai/dsh-bash'
+
+/**
+ * Quote one string as a single-quoted POSIX shell word.
+ * @param text - raw argv element to preserve through the outer shell parse.
+ * @returns the quoted shell word.
+ */
+export function shellQuote(text: string): string {
+  return `'${text.replaceAll("'", String.raw`'\''`)}'`
+}
+
+/**
+ * Classify a failed run against the selected backend's denial dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive denial substrings from the active wrap.
+ * @returns whether the failed run matches that denial dialect.
+ */
+export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
+  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Classify a failed run against the selected backend's runner-failure dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive runner-failure substrings from the active wrap.
+ * @returns whether the failed run matches that runner-failure dialect.
+ */
+export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
+  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
+  if (exitCode === null || exitCode === 0) return false
+  const lowered = stderr.toLowerCase()
+  return signatures.some(signature => lowered.includes(signature.toLowerCase()))
+}

packages/bash/bash-sandbox/src/index.ts

@@ -49,6 +49,7 @@ import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedSandboxMode, SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
+import { classifyDenial, classifyRunnerFailure, matchesSignature, shellQuote } from './helpers.ts'
 
 /**
  * Plugin config: the local executor's knobs plus the sandbox policy. All
@@ -67,75 +68,6 @@ export interface Config extends LocalConfig {
   workspaceRoot?: string
 }
 
-/**
- * Quote one string as a single-quoted POSIX shell word (embedded single
- * quotes become `'\''`), so a wrapped argv element survives the outer
- * `bash -c` re-parse byte-for-byte.
- * @param text - the raw argv element to quote.
- * @returns the single-quoted shell word.
- */
-export function shellQuote(text: string): string {
-  return `'${text.replaceAll("'", String.raw`'\''`)}'`
-}
-
-/**
- * Conservative sandbox-denial classifier: a run counts as denied only when it
- * FAILED (nonzero exit — a signal kill is not a denial) and its stderr
- * carries one of the SELECTED BACKEND's own denial signatures — the dialect
- * the provider stamps on every wrap (`ConfinedArgv.denialSignatures`:
- * `Read-only file system` under bwrap's EROFS mounts, `Permission denied`
- * under Landlock's EACCES, `Operation not permitted` under Seatbelt's
- * EPERM). Matching the backend's dialect rather than a cross-backend union
- * keeps the classifier from claiming denials the active backend never
- * produces (bare EPERM text under a Linux runner names non-file boundaries —
- * mount, kill, ptrace — that fail the same way unsandboxed). Text inference
- * is the fallback signal until a runner provides a structured one (which
- * wins once it exists); it errs toward NOT claiming a denial, and its known
- * residual imprecision is non-sandbox text in the active dialect (an ssh
- * auth failure reads as a denial under Landlock, a refused `kill` under
- * Seatbelt).
- * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's denial dialect, case-insensitive
- *   stderr substrings.
- * @returns whether the run's failure reads as a sandbox denial.
- */
-export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
-  return matchesSignature(result.exitCode, result.stderr.text, signatures)
-}
-
-/**
- * Runner-failure classifier: a failed run whose stderr carries the SELECTED
- * BACKEND's own runner-failure signature (`ConfinedArgv.
- * runnerFailureSignatures`: the runner's error prefix, which also matches
- * the shell's runner-not-found message) means the SANDBOX itself failed and
- * the command never ran. Checked BEFORE {@link classifyDenial} — a runner's
- * error text can contain denial words (an unopenable grant root reports
- * `Permission denied`) — and surfaced as the fail-closed
- * `SANDBOX_UNAVAILABLE` error on the foreground path, `sandbox.runnerFailed`
- * on a settled background task. Same conservative-text-inference stance and
- * residual imprecision as the denial classifier (a failing task that itself
- * prints the runner's prefix reads as a runner failure).
- * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's runner-failure signatures,
- *   case-insensitive stderr substrings.
- * @returns whether the run's failure reads as the runner itself failing.
- */
-export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
-  return matchesSignature(result.exitCode, result.stderr.text, signatures)
-}
-
-/**
- * The classifier core shared by foreground results and settled background
- * tasks: failed AND signature present. Lowercases BOTH sides — the seam
- * declares its signatures case-insensitive, and producers compose them from
- * runtime data of any case (an `argv0` path, `No such file or directory`).
- */
-function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
-  if (exitCode === null || exitCode === 0) return false
-  const lowered = stderr.toLowerCase()
-  return signatures.some(signature => lowered.includes(signature.toLowerCase()))
-}
-
 /**
  * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it
  * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is

packages/bash/bash-sandbox/tests/bwrap.e2e.ts

@@ -5,7 +5,8 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { bwrapProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 
 /**

packages/bash/bash-sandbox/tests/sandbox.spec.ts

@@ -16,7 +16,8 @@ import { Context } from 'cordis'
 import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 import { SANDBOX_UNAVAILABLE, SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { classifyDenial, classifyRunnerFailure, SandboxBashExecutor, shellQuote } from '@deepseek-ai/dsh-bash-sandbox'
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import { classifyDenial, classifyRunnerFailure, shellQuote } from '../src/helpers.ts'
 import type { Config } from '@deepseek-ai/dsh-bash-sandbox'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-sandbox-spec-'))

packages/bash/bash-sandbox/tests/seatbelt.e2e.ts

@@ -5,7 +5,8 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 
 /**