Files
deepseek-harness/packages/workflow
Yichen Jiang d6bebc5783 feat(shell): converge on execute() and promote timed-out commands to jobs
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.
2026-08-26 16:11:01 +08:00
..

description, kind
description kind
The workflow group map: model-authored orchestration scripts that fan out subagents, for users and maintainers navigating the group. package-group

packages/workflow

English | 中文

Summary

The workflow group lets an agent run a model-authored orchestration script that fans work out across many subagents and returns a final value. The workflow package provides the run service, the worker-thread package executes scripts in isolated threads, and two model-facing tools expose orchestration: the general workflow tool for scripted fan-out and the fixed ralph tool for fresh-agent iterative loops. The script coordinates agents with hooks while the agents do the actual work. The engine keeps a script's synchronous work off the host event loop but is containment, not a security boundary.

Table of Contents


Packages

Package Role ctx key
workflow Runs a model-written orchestration script that fans out subagents ctx.workflowEngine
workflow-worker-thread Executes each workflow script in its own worker thread, off the host event loop registers on ctx.workflowEngine
tool-workflow Gives the model the workflow tool for scripted multi-agent orchestration registers on ctx.tools
tool-ralph Gives the model the ralph tool for fresh-agent iterative loops registers on ctx.tools


Dev Note

Working context for maintainers — click to expand

None.