workflow, subagent: fix Codex code-review round-1 blockers

Six verified A-findings from the code-stage review, each with a regression test:

- parallel()/pipeline() resolved to HOST arrays inside the vm realm, exposing
  host Array.prototype to scripts; combinator results are now realm-built
  (in-realm Array.from bound at context setup).
- materializeFromRealm ran proxy traps (ownKeys/getOwnPropertyDescriptor/
  getPrototypeOf) during the descriptor walk — realm code on the host stack,
  outside the vm timeout, escaping as raw errors; proxies (root, nested, and
  in the prototype position) are now rejected trap-free via util.types.isProxy
  before any inspection.
- an already-aborted signal or an immediate cancel() no longer reports
  'completed' for a hook-free script: drive() checks cancellation before
  running the body and again when the script settles.
- dispose() now waits (bounded by disposeGraceMs) for stray agent() children
  to FINISH disposing, not just for the script to settle: every agent() call
  is tracked and quiesce() drains the in-flight set.
- workflow/* event payloads were live mutable aliases shared across emissions;
  emitWorkflowEvent now hands each listener its own structural clone.
- the structured-output turn-continuation veto is now prepend: true, so an
  earlier-registered force-continue listener cannot short-circuit it.

Docs updated in the same change (READMEs, core-data-structures/workflow.md,
the dynamic-workflows RFC, regenerated cordis catalogs).
This commit is contained in:
Tianyi Cui
2026-07-05 19:04:38 +08:00
parent 1d43ea3cd5
commit e264a106fd
17 changed files with 358 additions and 51 deletions
+2 -2
View File
@@ -4,9 +4,9 @@ The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a wor
## Service: `WorkflowService` (abstract)
`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). `dispose()` must reach quiescence within a bounded grace (cancel → wait → abandon), never hanging its caller.
`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller.
The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment (a throwing subscriber is logged, never propagated, and cannot starve later listeners) — the same guarantee as the subagent seam's lifecycle emits.
The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits.
## Vocabulary
+18 -11
View File
@@ -13,8 +13,10 @@
* carry {@link WorkflowRunInfo} (id + meta), never the live {@link WorkflowRun}
* — a listener must not gain `cancel`/`dispose`; control stays with the
* `start()` caller holding the run. Every emit is per-listener contained (a
* throwing subscriber is logged, never propagated), so one bad observer can
* neither strand a live run nor starve later listeners.
* throwing subscriber is logged, never propagated) and every listener gets its
* own payload clone (mutating it corrupts nothing), so one bad observer can
* neither strand a live run, starve later listeners, nor poison another
* listener's view.
*
* @module @deepseek-ai/dsh-workflow
*/
@@ -182,8 +184,9 @@ export function isFatalWorkflowError(error: unknown): boolean {
* snapshots, per-listener containment); `workflow/end` fires exactly once
* per started run, after `result` is settled or as it settles.
* - `dispose()` reaches quiescence within a bounded grace: it cancels, waits
* for the script to settle, and abandons a stuck script rather than
* hanging its caller (the engine documents what abandonment leaves behind).
* for the script to settle AND its started children to finish disposing,
* and abandons whatever is left rather than hanging its caller (the engine
* documents what abandonment leaves behind).
*/
export abstract class WorkflowService extends Service {
constructor(ctx: Context) {
@@ -199,12 +202,16 @@ export abstract class WorkflowService extends Service {
abstract start(request: WorkflowStartRequest): WorkflowRun
/**
* Emit one `workflow/*` lifecycle event with PER-LISTENER containment:
* dispatch each subscriber individually and log (never propagate) a thrown
* one, so one bad subscriber can neither fail the engine mid-run, surface as
* an unhandled rejection on a detached settle hook, nor starve the listeners
* registered after it (cordis `emit` halts on the first throw — same
* guarantee as the subagent seam's lifecycle emits).
* Emit one `workflow/*` lifecycle event with PER-LISTENER containment and
* PER-LISTENER payload snapshots: each subscriber is dispatched individually
* with its OWN structural clone of the payload (the payloads are plain JSON
* data by the seam contract), so a listener mutating what it received can
* corrupt neither the engine's live state nor any other listener's or later
* event's view; a thrown listener is logged (never propagated), so one bad
* subscriber can neither fail the engine mid-run, surface as an unhandled
* rejection on a detached settle hook, nor starve the listeners registered
* after it (cordis `emit` halts on the first throw — same guarantee as the
* subagent seam's lifecycle emits).
* @param name - the `workflow/*` event to dispatch.
* @param args - the event's payload, matching its declared signature.
*/
@@ -213,7 +220,7 @@ export abstract class WorkflowService extends Service {
try {
// The declared workflow/* signatures are all void-returning emits; the
// dispatch callback applies the payload tuple.
;(callback as (...payload: unknown[]) => void)(...args)
;(callback as (...payload: unknown[]) => void)(...structuredClone(args))
} catch (error: unknown) {
this.ctx.logger.warn(`workflow: ${name} listener threw: ${String(error)}`)
}
@@ -66,6 +66,28 @@ describe('dsh-workflow (interface)', () => {
])
})
it('gives each listener its OWN payload snapshot: mutation corrupts neither peers nor the caller', async () => {
const ctx = new Context()
await ctx.plugin(StubEngine)
const seen: string[] = []
ctx.on('workflow/agent-start', (info, agent) => {
agent.label = 'HACKED'
info.meta.name = 'HACKED'
seen.push('mutator')
})
ctx.on('workflow/agent-start', (info, agent) => {
seen.push(`${info.meta.name}/${agent.label}`)
})
const engine = ctx.workflows as StubEngine
const info: WorkflowRunInfo = { id: WorkflowRunId('run-2'), meta: { name: 'w', description: 'd' } }
const payload = { seq: 1, label: 'original', childId: 'c' }
engine.emit('workflow/agent-start', info, payload)
expect(seen).toEqual(['mutator', 'w/original'])
// The caller's own objects are pristine too — no listener ever saw them.
expect(info.meta.name).toBe('w')
expect(payload.label).toBe('original')
})
it('contains a throwing listener PER LISTENER: later listeners still run, nothing propagates', async () => {
const ctx = new Context()
await ctx.plugin(StubEngine)