refactor: apply repository naming contract

Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.

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

@@ -0,0 +1,116 @@
+/**
+ * Internal sandbox-result classification helpers.
+ *
+ * @module @deepseek-ai/dsh-bash-sandbox/helpers
+ */
+
+import { accessSync, constants, statSync } from 'node:fs'
+import type { ShellRunResult } from '@deepseek-ai/dsh-shell'
+import type { RunnerFailureRule } from '@deepseek-ai/dsh-sandbox'
+
+/** Node-local spawn codes proven to identify executable resolution or permission failure. */
+const EXECUTABLE_SPAWN_CODES = new Set(['EACCES', 'ENOENT'])
+
+/** Whether the caller-owned spawn cwd can be entered. */
+function isUsableWorkdir(path: string): boolean {
+  try {
+    if (!statSync(path).isDirectory()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+ * after independently ruling out the caller-owned cwd. A supplied error path
+ * must exactly identify the runner; without one, the syscall must. With a
+ * usable cwd, these codes describe resolution or execute permission for that
+ * argv[0] or its shebang interpreter.
+ * The workdir is checked at classification time, not atomically with spawn;
+ * concurrent path replacement may change attribution but cannot permit an
+ * unconfined execution.
+ * @param error - the original spawn rejection.
+ * @param runnerProgram - provider argv[0], the executable that establishes confinement.
+ * @param workdir - the caller-owned spawn cwd, checked independently for usability.
+ * @returns whether the rejection has executable-specific runner evidence.
+ */
+export function isRunnerSpawnFailure(
+  error: unknown,
+  runnerProgram: string | undefined,
+  workdir: string,
+): boolean {
+  if (runnerProgram === undefined || !isUsableWorkdir(workdir)) return false
+  if (typeof error !== 'object' || error === null) return false
+  const { code, path, syscall } = error as { code?: unknown; path?: unknown; syscall?: unknown }
+  if (typeof code !== 'string' || !EXECUTABLE_SPAWN_CODES.has(code)) return false
+  if (typeof syscall !== 'string') return false
+  const exactSyscall = `spawn ${runnerProgram}`
+  if (path === undefined) return syscall === exactSyscall
+  if (typeof path !== 'string' || path.length === 0 || path !== runnerProgram) return false
+  return syscall === 'spawn' || syscall === exactSyscall
+}
+
+/** Fatal runner evidence retained for infrastructure-error detail. */
+interface RunnerFailureMatch {
+  /** The original stderr line that matched a fatal signature. */
+  detail: string
+}
+
+/**
+ * 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: ShellRunResult, signatures: readonly string[]): boolean {
+  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Classify one settled process against the selected backend's structured
+ * runner-failure rules. Each rule requires a nonzero exit, its optional
+ * exit-code gate, and a fatal signature on one stderr line after exact
+ * informational lines are excluded.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text, left unchanged.
+ * @param rules - structured runner-failure rules from the active wrap.
+ * @returns the first matching fatal line, or undefined when evidence is insufficient.
+ */
+export function classifyRunnerFailure(
+  exitCode: number | null,
+  stderr: string,
+  rules: readonly RunnerFailureRule[],
+): RunnerFailureMatch | undefined {
+  if (exitCode === null || exitCode === 0) return undefined
+  const lines = stderr.split(/\r?\n/)
+  for (const rule of rules) {
+    if (rule.allowedExitCodes !== undefined && !rule.allowedExitCodes.includes(exitCode)) continue
+    const informationalLines = new Set((rule.informationalLines ?? []).map(line => line.toLowerCase()))
+    // An empty or whitespace-only substring is not meaningful runner evidence.
+    // Ignore it while keeping any valid signatures beside it active.
+    const fatalSignatures = rule.fatalSignatures
+      .filter(signature => signature.trim().length > 0)
+      .map(signature => signature.toLowerCase())
+    for (const line of lines) {
+      const lowered = line.toLowerCase()
+      if (informationalLines.has(lowered)) continue
+      if (fatalSignatures.some(signature => lowered.includes(signature))) return { detail: line }
+    }
+  }
+  return undefined
+}
+
+/**
+ * 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/shell/bash-sandbox/src/index.ts

@@ -0,0 +1,182 @@
+/**
+ * Sandbox-consuming bash executor. It wraps the exact local bash argv through
+ * `ctx.sandbox`, inherits local process mechanics, and reports the selected
+ * mode, enforcement, and denial facts. Positive runner-launch evidence means
+ * the command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
+ * background processes carry `runnerFailed`; other spawn rejections retain
+ * local-executor semantics. The tool owns approval and passes a complete per-call policy.
+ * @module @deepseek-ai/dsh-bash-sandbox
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell'
+import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
+import type {
+  ConfinedArgv,
+  ConfinedSandboxMode,
+  RunnerFailureRule,
+  SandboxEnforcement,
+  SandboxExecutionPolicy,
+  SandboxMode,
+  SandboxPolicy,
+} from '@deepseek-ai/dsh-sandbox'
+import type {} from '@deepseek-ai/dsh-sandbox-policy'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
+import { classifyDenial, classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature } from './helpers.ts'
+
+/**
+ * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
+ * the default mode and fallback `workspace-write` root — is NOT here: it lives
+ * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves
+ * each calling session's mode and cwd for every enforcing capability. The runner
+ * choice is likewise the `ctx.sandbox` provider's config, not this executor's.
+ */
+export type Config = LocalConfig
+
+/**
+ * Registers as `ctx.shell` in place of the local executor and requires a
+ * `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer is
+ * unchanged. Tool calls pass the calling session's resolved policy; direct
+ * calls fall back to deployment policy. `result.sandbox` reports the mode and
+ * enforcement actually used.
+ */
+export class SandboxBashExecutor extends LocalBashExecutor {
+  static override inject = ['subprocess', 'sandbox', 'sandboxPolicy']
+
+  // No own Config: the sandbox default (mode + workspaceRoot) is owned by
+  // ctx.sandboxPolicy, so this executor inherits LocalBashExecutor's Config
+  // verbatim (the config catalog walks the inherited static).
+
+  private readonly mode: SandboxMode
+  /**
+   * Per-process confinement facts retained until settlement. Providers may
+   * vary enforcement and diagnostic dialect between overlapping calls, so a
+   * shared latest-wrap value would classify a process against the wrong facts.
+   * Unconfined processes have no entry.
+   */
+  private readonly processFacts = new Map<ShellProcess, {
+    mode: ConfinedSandboxMode
+    enforcement: SandboxEnforcement
+    denialSignatures: readonly string[]
+    runnerFailureRules: readonly RunnerFailureRule[]
+    runnerProgram: string | undefined
+    workdir: string
+  }>()
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, config)
+    // The default mode is the capability fact used for schema advertisement;
+    // actual tool executions carry their resolved per-call policy.
+    this.mode = ctx.sandboxPolicy.defaultMode
+  }
+
+  /** The configured default mode — the capability fact the tool layer reads. */
+  override get sandboxMode(): SandboxMode {
+    return this.mode
+  }
+
+  /**
+   * Stamp a complete per-call policy onto the spec. Tool calls supply the
+   * calling session's resolved mode and root; lower-level callers fall back to
+   * the deployment policy.
+   */
+  override resolve(request: ShellExecRequest): ShellExecSpec {
+    return { ...super.resolve(request), sandboxPolicy: request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve() }
+  }
+
+  override async run(spec: ShellExecSpec): Promise<ShellRunResult> {
+    const policy = spec.sandboxPolicy as SandboxExecutionPolicy
+    const { mode } = policy
+    if (mode === 'danger-full-access') {
+      const result = await super.run(spec)
+      return { ...result, sandbox: { mode, denied: false } }
+    }
+    const confined = this.confine(spec.command, { ...policy, mode })
+    let result: ShellRunResult
+    try {
+      result = await this.runArgv(spec, confined.argv)
+    } catch (error) {
+      // An upstream abort remains cancellation even when it prevents spawn.
+      if (spec.signal?.aborted === true) spec.signal.throwIfAborted()
+      if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) {
+        throw new SandboxUnavailableError(mode, String(error))
+      }
+      throw error
+    }
+    // Runner failure outranks denial because the command did not run. Carry
+    // the matched fatal line, not an informational line that preceded it.
+    const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, confined.runnerFailureRules)
+    if (runnerFailure !== undefined) {
+      throw new SandboxUnavailableError(mode, runnerFailure.detail)
+    }
+    return { ...result, sandbox: { mode, denied: classifyDenial(result, confined.denialSignatures), enforcement: confined.enforcement } }
+  }
+
+  override start(spec: ShellExecSpec): ShellProcess {
+    const policy = spec.sandboxPolicy as SandboxExecutionPolicy
+    const { mode } = policy
+    if (mode === 'danger-full-access') return super.start(spec)
+    // Once startArgv returns, install facts synchronously; promise settlement
+    // cannot run before start() returns.
+    const confined = this.confine(spec.command, { ...policy, mode })
+    let proc: ShellProcess
+    try {
+      proc = this.startArgv(spec, confined.argv)
+    } catch (error) {
+      // LocalSubprocessRuntime reports ENOENT/EACCES with the failed executable path through async
+      // `done` rejection; this covers alternatives that throw the same error synchronously.
+      if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) {
+        throw new SandboxUnavailableError(mode, String(error))
+      }
+      throw error
+    }
+    const { enforcement, denialSignatures, runnerFailureRules } = confined
+    this.processFacts.set(proc, {
+      mode,
+      enforcement,
+      denialSignatures,
+      runnerFailureRules,
+      runnerProgram: confined.argv[0],
+      workdir: spec.workdir,
+    })
+    return proc
+  }
+
+  /**
+   * Stamp per-process sandbox facts before `done` settles. Full-access processes
+   * have no facts; signal deaths are not denials.
+   */
+  protected override onProcessDone(proc: ShellProcess, stderr: string, spawnFailed: boolean, spawnError?: unknown): void {
+    const facts = this.processFacts.get(proc)
+    if (facts !== undefined) {
+      this.processFacts.delete(proc)
+      // A rejected spawn never started the confined launch. Otherwise runner
+      // failure outranks denial because its diagnostics may contain denial terms.
+      const runnerFailed = spawnFailed
+        ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir)
+        : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== undefined
+      proc.sandbox = {
+        mode: facts.mode,
+        denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
+        enforcement: facts.enforcement,
+        ...(runnerFailed ? { runnerFailed } : {}),
+      }
+    }
+    super.onProcessDone(proc, stderr, spawnFailed, spawnError)
+  }
+
+  /**
+   * Wrap one shell command via the `ctx.sandbox` provider. Provider errors
+   * propagate unchanged; the returned argv is handed directly to the local
+   * executor's subprocess path.
+   * @param command - shell source for the confined inner `bash -c`.
+   * @param policy - resolved confined execution policy.
+   * @returns the provider's exact argv and settlement-classification facts.
+   */
+  private confine(command: string, policy: SandboxPolicy): ConfinedArgv {
+    return this.ctx.sandbox.confine(['bash', '-c', command], policy)
+  }
+}
+
+export default SandboxBashExecutor

packages/shell/bash-sandbox/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-bash-sandbox`.
+ * @module @deepseek-ai/dsh-bash-sandbox/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-bash-sandbox'
+
+/** Cordis companion plugin name. */
+export const name = 'bash-sandbox-invariant'
+/** Service required before the companion can reserve package ownership. */
+export 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: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */