The executor seam collapses run()/start() (and the planned begin()) into one
resolve() + execute(): the handle IS the live process, and the foreground
result, the background cursor, and the deadline's promotion offer are
projections over the same spawn. ShellExecSpec.onExpiry ('kill' default /
'offer' / 'none') replaces the implicit method split; one stdout budget applies
everywhere, the 'start ignores timeoutMs' wart dies, and sync spawn throws are
contained into the same settled-killed handle as async rejections (result()
rejects with the original error, identity preserved for the sandbox
classification).
The promotion offer settles exactly once and never rejects — offer at an
'offer' deadline while running, undefined when the process settles first — so
'await execution.promotion' alone distinguishes the outcomes. An offer must be
answered synchronously; an unanswered one auto-declines back to the
kill-on-timeout behavior. accept() ends the deadline and detaches the caller's
abort signal; decline() kills and classifies timedOut.
tool-bash and tool-pwsh promote on timeout by default (promoteOnTimeout: true,
inert without run_in_background or a job registry): at the offer the running
handle registers as a job with the same hooks as run_in_background, mirrors
into ctx.activities (the web task list streams it, stop control included), and
the call returns { kind: 'promoted', jobId, timeoutMs, output } carrying the
output so far — the job cursor continues exactly after it. Any promotion
failure declines and falls back to the plain timeout kill. Descriptions and
the timeoutMs schema text advertise the semantics only when they hold;
recorded-session and web snapshot fixtures re-recorded with them.
Also repairs the four CI failures from the human-kill push: ui-activity's
missing dsh-session peer declaration (static + windows observational), the
observe owner-arm/outer-catch and killJob-stub coverage gaps, tool-workflow's
owned-run arm, and the timing-dependent projection-cache interval flush test
(now poll-based for coarse Windows timers).
Peer evidence and rejected alternatives (Codex's session model, a third seam
method, a second threshold knob) in the Agent Note
2026-08-26-shell-execute-timeout-promotion.
186 lines
7.8 KiB
TypeScript
186 lines
7.8 KiB
TypeScript
/**
|
|
* 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, ShellExecution, 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 execute(spec: ShellExecSpec): ShellExecution {
|
|
const policy = spec.sandboxPolicy as SandboxExecutionPolicy
|
|
const { mode } = policy
|
|
if (mode === 'danger-full-access') {
|
|
return SandboxBashExecutor.decorateResult(
|
|
super.execute(spec),
|
|
result => ({ ...result, sandbox: { mode, denied: false } }),
|
|
)
|
|
}
|
|
// Once executeArgv returns, install facts synchronously; promise
|
|
// settlement cannot run before execute() returns.
|
|
const confined = this.confine(spec.command, { ...policy, mode })
|
|
// executeArgv contains spawn problems (sync or async) into the settled
|
|
// handle, so nothing here can throw before the facts are installed.
|
|
const ex = this.executeArgv(spec, confined.argv)
|
|
const { enforcement, denialSignatures, runnerFailureRules } = confined
|
|
this.processFacts.set(ex, {
|
|
mode,
|
|
enforcement,
|
|
denialSignatures,
|
|
runnerFailureRules,
|
|
runnerProgram: confined.argv[0],
|
|
workdir: spec.workdir,
|
|
})
|
|
return SandboxBashExecutor.decorateResult(ex, (result) => {
|
|
// 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, runnerFailureRules)
|
|
if (runnerFailure !== undefined) {
|
|
throw new SandboxUnavailableError(mode, runnerFailure.detail)
|
|
}
|
|
return { ...result, sandbox: { mode, denied: classifyDenial(result, denialSignatures), enforcement } }
|
|
}, (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
|
|
})
|
|
}
|
|
|
|
/**
|
|
* Decorate the handle's foreground projection in place, memoized once. The
|
|
* handle keeps its identity (never wrapped in a second object) because the
|
|
* per-process facts and `onProcessDone` key on the exact instance.
|
|
*/
|
|
private static decorateResult(
|
|
ex: ShellExecution,
|
|
map: (result: ShellRunResult) => ShellRunResult,
|
|
mapError?: (error: unknown) => never,
|
|
): ShellExecution {
|
|
const base = ex.result.bind(ex)
|
|
let decorated: Promise<ShellRunResult> | undefined
|
|
ex.result = () => {
|
|
decorated ??= base().then(map, mapError)
|
|
return decorated
|
|
}
|
|
return ex
|
|
}
|
|
|
|
/**
|
|
* 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
|