Files
deepseek-harness/packages/shell/tool-bash/src/background.ts
T
Yichen Jiang 1596097147 Merge remote-tracking branch 'origin/master' into worktree/jobs-api-review-3052
# Conflicts:
#	apps/web/tsconfig.json
#	docs/event-producer-consumer.i18n.yaml
#	docs/event-producer-consumer.md
#	docs/event-producer-consumer.zh.md
#	docs/module-graph.i18n.yaml
#	docs/module-graph.md
#	docs/module-graph.zh.md
#	packages/api/remotes/package.json
#	packages/api/remotes/src/client/index.ts
#	packages/api/session-controller/tests/client-apply.client.spec.ts
#	packages/api/session-controller/tests/control-jobs.host.spec.ts
#	packages/api/session-controller/tests/fake-api.client.ts
#	packages/api/session-controller/tests/manager.client.spec.ts
#	packages/client/ui-jobs/package.json
#	packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
#	packages/jobs/jobs-local/README.i18n.yaml
#	packages/jobs/jobs-local/README.md
#	packages/jobs/jobs-local/README.zh.md
#	packages/jobs/jobs-local/src/index.ts
#	packages/jobs/jobs-local/tests/jobs.spec.ts
#	packages/jobs/tool-jobs/tests/tool-jobs.spec.ts
#	packages/shell/shell/README.i18n.yaml
#	packages/shell/shell/README.md
#	packages/shell/shell/README.zh.md
#	packages/shell/tool-bash/README.i18n.yaml
#	packages/shell/tool-bash/README.md
#	packages/shell/tool-bash/README.zh.md
#	packages/shell/tool-bash/src/background.ts
#	packages/shell/tool-bash/src/index.ts
#	packages/shell/tool-pwsh/src/background.ts
#	packages/shell/tool-pwsh/src/index.ts
2026-09-16 15:53:02 +08:00

113 lines
4.9 KiB
TypeScript

/**
* Generic-job adaptation for background bash process handles: the terminal
* outcome the registry records and the pull sources it pumps.
*
* @module @deepseek-ai/dsh-tool-bash/background
*/
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
import type { ShellProcess, ShellSandboxInfo } from '@deepseek-ai/dsh-shell'
import type { JobHooks, JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs'
/**
* Sandbox facts worth the terminal detail: a runner that never ran the
* command, or a denial (with the escalation hint this composition offers).
* @param sandbox - settled sandbox facts, when this was a confined process.
* @param escalationModes - escalation targets advertised by this composition.
* @returns the markers to append, oldest first.
*/
function sandboxNotes(sandbox: ShellSandboxInfo | undefined, escalationModes: readonly SandboxMode[]): string[] {
if (sandbox?.runnerFailed) {
return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`]
}
if (sandbox?.denied) {
const notes = [sandboxDenialMarker(sandbox.mode)]
if (escalationModes.length > 0) notes.push(escalationHintMarker('command'))
return notes
}
return []
}
/**
* Map a settled background process onto the generic job-outcome vocabulary:
* `killed` stays `killed` (detail: the signal when one is known), everything
* else is `completed` with the exit code as detail. A nonzero command exit is
* reported, not failed, exactly like the foreground rendering. Sandbox facts
* join the detail, since a job's terminal reason is the one line every
* reader — the model's status line, the roster row — shows.
* @param proc - the settled process handle.
* @param escalationModes - escalation targets advertised by this composition.
* @returns the outcome for the `ctx.jobs` registration.
*/
export function processOutcome(proc: ShellProcess, escalationModes: readonly SandboxMode[] = []): JobOutcome {
// TODO(background-infrastructure-outcome): widen ShellProcess with an explicit
// infrastructure-failure outcome, then map it to job `failed`. Restricted
// runner failures expose sandbox.runnerFailed, but unconfined spawn failures
// still alias a signal-less kill; real nonzero command exits must remain
// `completed`.
const base: JobOutcome = proc.status === 'killed'
? { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
: { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
const notes = sandboxNotes(proc.sandbox, escalationModes)
return notes.length === 0 ? base : { ...base, detail: `${base.detail}; ${notes.join(' ')}` }
}
/**
* The process's non-consuming stream readers as registry pull sources. They
* bind lazily because the process is spawned inside the starter, after the
* registry admitted the job; a read before the spawn yields nothing, and the
* pump keeps the model's consuming cursor untouched. A rejected spawn's
* stderr reader carries the provider's `spawn failed: …` note.
* @param proc - the started process, once the starter has spawned it.
* @returns one source per stream, stdout first.
*/
export function processSources(proc: () => ShellProcess | undefined): JobOutputSource[] {
const source = (channel: 'stdout' | 'stderr'): JobOutputSource => ({
channel,
read: (fromByte) => {
const live = proc()
return live === undefined ? { text: '', nextOffset: fromByte, lossy: false } : live.observed[channel].readFrom(fromByte)
},
})
return [source('stdout'), source('stderr')]
}
/**
* Adapt asynchronous shell preparation after job admission without exposing a partial process.
* @param start - starts the process with job-owned cancellation.
* @param outcome - projects the settled process into the job outcome.
* @returns synchronous job hooks whose completion includes preparation and process settlement.
*/
export function processJob(
start: (signal: AbortSignal) => Promise<ShellProcess>,
outcome: (process: ShellProcess) => JobOutcome,
): JobHooks {
const controller = new AbortController()
let process: ShellProcess | undefined
const done: Promise<JobOutcome> = (async () => {
try {
process = await start(controller.signal)
try {
if (controller.signal.aborted) process.kill()
} finally {
await process.done
}
return outcome(process)
} catch (error: unknown) {
return {
status: controller.signal.aborted && process === undefined ? 'killed' : 'failed',
detail: error instanceof Error ? error.message : String(error),
}
}
})()
return {
cancel: (reason) => {
if (controller.signal.aborted) return
controller.abort(reason)
process?.kill()
},
done,
}
}