Merge remote-tracking branch 'origin/worktree-agent-scope-design' into codex/package-readme-limitations-audit-20260712

# Conflicts: # packages/core/scope/README.md # packages/session-persistence/session-persistence-jsonl/README.md # packages/session-persistence/session-persistence-sqlite/README.md # packages/subagent/subagent-acp/README.md # packages/subagent/subagent-fork/README.md # packages/subagent/subagent-inprocess/README.md # packages/subagent/subagent/README.md # packages/subagent/tool-subagent/README.md # packages/support/invariants/README.md # packages/support/subagent-mock/README.md # packages/workflow/workflow-workerthread/README.md # packages/workflow/workflow/README.md
2026-07-12 23:35:47 +08:00
parent 41a7c70cb1 2ca806a1ec
commit 6967c584d1
164 changed files with 8906 additions and 7154 deletions
--- a/packages/support/subagent-mock/README.md
+++ b/packages/support/subagent-mock/README.md
@@ -2,7 +2,7 @@

 A scripted `SubagentProvider` for testing the [subagent seam](../../subagent/subagent/README.md) without a model or a real child agent — the subagent analog of [`dsh-llm-replay`](../llm-replay/README.md).

-It lets a test drive `ctx.subagents` and the model-facing `dsh-tool-subagent` through the **real cordis Loader / export path**, exercising provider registration, start-time capability validation, the run lifecycle (`result` / `cancel` / `dispose`), and the structured-output branch — all deterministically and keylessly.
+It lets a test drive `ctx.subagents` and the model-facing `dsh-tool-subagent` through the real Cordis loader/export path, exercising provider registration, async start, start-time capability validation, required-signal cancellation, `result`, `dispose`, and structured output deterministically and keylessly.

 ## Usage

@@ -13,14 +13,13 @@ Load it as a plugin (functional shape: `name`/`inject`/`Config`/`apply`, no defa
 | `name` | `mock` | Registry name to register the provider under. |
 | `reply` | `mock subagent reply` | The scripted child's final answer text. |
 | `stopReason` | `completed` | The stop reason `result` settles with. |
-| `capabilities` | all `true` | Which start-time capabilities (`outputSchema`/`depthLimit`/`toolFilter`/`persona`) the provider advertises. |
-| `inheritsParentContext` | `false` | The context contract to declare; `true` exercises the fork-shaped tool wording in consumer tests. |
+| `capabilities` | all `true` | Which start-time capabilities (`outputSchema`, `depthLimit`, `toolFilter`, and `persona`) the provider advertises. |
+| `inheritsParentContext` | `false` | Conversation-history descriptor: `false` means fresh, while `true` exercises seeded/fork wording. It says nothing about tool, service, scope, or authority inheritance. |
 | `structured` | `{ reply }` | Structured value surfaced when a request carries an `outputSchema` and the capability is on. |

-A `cancel()` issued before `result` settles flips the stop reason to `aborted`, so the cancellation path is observable.
+Aborting the required request signal or disposing before `result` settles flips the stop reason to `aborted`, so both holder-facing cancellation paths are observable.

 ## Known Limitations and Deferred Work

 - **Scripted provider only** — it does not run a model, create a child agent, or exercise real prompt/tool-loop behavior.
- **One immediate synthetic outcome per run** — it models no multi-turn, streaming, readiness delay, or subprocess transport behavior.
- **`dispose()` is a no-op** — lifecycle tests using it prove consumer control flow, not resource teardown or quiescence of a real backend.
+- **One synthetic outcome per run** — it models no multi-turn, streaming, steering, resume, or subprocess transport behavior.
--- a/packages/support/subagent-mock/src/index.ts
+++ b/packages/support/subagent-mock/src/index.ts
@@ -29,11 +29,10 @@ const STOP_REASONS = ['completed', 'aborted', 'error', 'max-tokens', 'refusal']
 const DEFAULT_CAPS: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true, persona: true }

 /**
- * A scripted provider: every {@link start} returns a run whose `result`
- * resolves on a microtask with the configured reply (and a structured value
- * when the request asked for one and the capability is on). `dispose` is a
- * no-op; a `cancel()` before the result settles flips the stop reason to
- * `aborted`, so the cancellation path is observable in a test.
+ * A scripted provider: every {@link start} returns a ready run whose `result`
+ * resolves on the next task with the configured reply (and a structured value
+ * when the request asked for one and the capability is on). The required
+ * signal and `dispose()` both flip an unsettled result to `aborted`.
 */
 class MockSubagentProvider implements SubagentProvider {
  readonly capabilities: SubagentCapabilities
@@ -47,12 +46,22 @@ class MockSubagentProvider implements SubagentProvider {
    this.inheritsParentContext = config.inheritsParentContext ?? false
  }

-  start(request: SubagentStartRequest): SubagentRun {
+  async start(request: SubagentStartRequest): Promise<SubagentRun> {
+    if (request.signal.aborted) throw new Error('mock subagent start aborted before publication')
    const reply = this.config.reply ?? 'mock subagent reply'
    const output: ContentBlock[] = [{ type: 'text', text: reply }]
    const wantsStructured = request.outputSchema !== undefined && this.capabilities.outputSchema
    const baseStop: SubagentStopReason = this.config.stopReason ?? 'completed'
-    let cancelled = false
+    const flags = { cancelled: false }
+    const onAbort = (): void => { flags.cancelled = true }
+    request.signal.addEventListener('abort', onAbort, { once: true })
+    // Make publication genuinely asynchronous so a same-turn abort is still
+    // a provider-owned startup failure rather than a returned live run.
+    await Promise.resolve()
+    if (flags.cancelled) {
+      request.signal.removeEventListener('abort', onAbort)
+      throw new Error('mock subagent start aborted before publication')
+    }

    // A deterministic child id derived from the parent — no clock/random (both
    // banned in deterministic paths here, and unnecessary for a scripted run).
@@ -60,21 +69,22 @@ class MockSubagentProvider implements SubagentProvider {

    const resultFor = (): SubagentResult => ({
      output,
-      structured: wantsStructured ? (this.config.structured ?? { reply }) : undefined,
-      stopReason: cancelled ? 'aborted' : baseStop,
+      ...wantsStructured ? { structured: this.config.structured ?? { reply } } : {},
+      stopReason: flags.cancelled ? 'aborted' : baseStop,
    })

+    const result = new Promise<SubagentResult>((resolve) => {
+      setTimeout(() => { resolve(resultFor()) }, 0)
+    }).finally(() => {
+      request.signal.removeEventListener('abort', onAbort)
+    })
    return {
      id,
-      // A scripted run has no asynchronous publication phase; it is ready as
-      // soon as the provider returns the handle.
-      started: Promise.resolve(),
-      result: Promise.resolve().then(resultFor),
-      cancel() {
-        cancelled = true
-      },
-      async dispose() {
-        // Scripted run holds no resources — nothing to await.
+      result,
+      dispose(): Promise<void> {
+        flags.cancelled = true
+        request.signal.removeEventListener('abort', onAbort)
+        return Promise.resolve()
      },
    }
  }
@@ -94,9 +104,11 @@ export interface Config {
  /** Which start-time capabilities to advertise (default: all `true`). */
  capabilities?: Partial<SubagentCapabilities>
  /**
-   * The context contract to declare ({@link SubagentProvider.inheritsParentContext});
-   * default `false` (spawn-like). Set `true` to exercise the fork-shaped tool
-   * wording in consumer tests.
+   * The conversation-history descriptor to declare
+   * ({@link SubagentProvider.inheritsParentContext}); default `false` (fresh
+   * conversation). Set `true` to exercise seeded/fork wording in consumer
+   * tests. This flag says nothing about tool, service, scope, or authority
+   * inheritance.
   */
  inheritsParentContext?: boolean
  /**
--- a/packages/support/subagent-mock/tests/subagent-mock.spec.ts
+++ b/packages/support/subagent-mock/tests/subagent-mock.spec.ts
@@ -11,7 +11,7 @@ function fakeParent(id = 'parent-1'): Agent {
 }

 function baseRequest(over: Partial<SubagentStartRequest> = {}): SubagentStartRequest {
-  return { prompt: [{ type: 'text', text: 'task' }], parent: fakeParent(), ...over }
+  return { prompt: [{ type: 'text', text: 'task' }], parent: fakeParent(), signal: new AbortController().signal, ...over }
 }

 async function mount(config: Partial<mock.Config> = {}): Promise<Context> {
@@ -26,12 +26,13 @@ describe('dsh-subagent-mock', () => {
    const ctx = await mount({ reply: 'hello from mock' })
    expect(ctx.subagents.list()).toEqual(['mock'])

-    const run = ctx.subagents.start('mock', baseRequest())
+    const run = await ctx.subagents.start('mock', baseRequest())
    await expect(run.result).resolves.toEqual({
      output: [{ type: 'text', text: 'hello from mock' }],
      structured: undefined,
      stopReason: 'completed',
    })
+    await run.dispose()
  })

  it('registers under a configurable name', async () => {
@@ -41,13 +42,13 @@ describe('dsh-subagent-mock', () => {

  it('surfaces a structured result when the request carries an outputSchema', async () => {
    const ctx = await mount({ reply: 'r', structured: { answer: 42 } })
-    const run = ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } }))
+    const run = await ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } }))
    await expect(run.result).resolves.toMatchObject({ structured: { answer: 42 } })
  })

  it('defaults structured output to { reply } when outputSchema is requested but no structured value is configured', async () => {
    const ctx = await mount({ reply: 'fallback reply' })
-    const run = ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } }))
+    const run = await ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } }))
    await expect(run.result).resolves.toMatchObject({ structured: { reply: 'fallback reply' } })
  })

@@ -56,23 +57,44 @@ describe('dsh-subagent-mock', () => {
    // The service rejects an outputSchema request against a no-cap provider, so
    // the structured path is only reachable when the cap is on; with it off and
    // no schema requested, the result has no structured field.
-    const run = ctx.subagents.start('mock', baseRequest())
-    await expect(run.result).resolves.toMatchObject({ structured: undefined })
+    const run = await ctx.subagents.start('mock', baseRequest())
+    const result = await run.result
+    expect(result).not.toHaveProperty('structured')
  })

  it('honors a configured stop reason', async () => {
    const ctx = await mount({ stopReason: 'refusal' })
-    const run = ctx.subagents.start('mock', baseRequest())
+    const run = await ctx.subagents.start('mock', baseRequest())
    await expect(run.result).resolves.toMatchObject({ stopReason: 'refusal' })
  })

-  it('flips the stop reason to aborted when cancelled before the result settles', async () => {
+  it('flips the stop reason to aborted when the signal fires before the result settles', async () => {
    const ctx = await mount()
-    const run = ctx.subagents.start('mock', baseRequest())
-    run.cancel()
+    const controller = new AbortController()
+    const run = await ctx.subagents.start('mock', baseRequest({ signal: controller.signal }))
+    controller.abort()
    await expect(run.result).resolves.toMatchObject({ stopReason: 'aborted' })
  })

+  it('rejects an already-aborted request before starting publication', async () => {
+    const ctx = await mount()
+    const controller = new AbortController()
+    controller.abort()
+
+    await expect(ctx.subagents.start('mock', baseRequest({ signal: controller.signal })))
+      .rejects.toThrow('mock subagent start aborted before publication')
+  })
+
+  it('rejects when cancellation wins the asynchronous publication handoff', async () => {
+    const ctx = await mount()
+    const controller = new AbortController()
+    const pending = ctx.subagents.start('mock', baseRequest({ signal: controller.signal }))
+
+    controller.abort()
+
+    await expect(pending).rejects.toThrow('mock subagent start aborted before publication')
+  })
+
  it('unregisters the provider when the owning fiber is disposed (HMR safety)', async () => {
    const ctx = new Context()
    await ctx.plugin(SubagentService)