refactor(agent-loop): simplify message machine

2026-07-24 11:46:06 +08:00
parent 7b7f793ee5
commit aaa42d5844
25 changed files with 1205 additions and 2622 deletions
--- a/packages/core/agent-loop/tests/MIGRATION.md
+++ b/packages/core/agent-loop/tests/MIGRATION.md
@@ -0,0 +1,86 @@
+# Agent-loop test migration guide (naive-machine contract)
+
+The loop was rewritten in the naive-agent shape. `packages/core/agent-loop/src/agent.ts`
+is the single source of truth — read it before migrating a spec. Key changes:
+
+## Event seams (old → new)
+
+| Old seam | Replacement |
+|---|---|
+| `agent/pre-step` (serial, before step/start) | `agent/step` (serial, before EVERY request derives; same position) |
+| `agent/post-step` (serial, after tools, before step/end) | REMOVED — use `agent/step` of the next step, or `agent/idle` after the turn |
+| `agent/session-prefix` (waterfall, request-only prefix) | REMOVED — requests carry no unlogged prefix; durable context via `agent.inject()` at `agent/session-start` |
+| `agent/step-result` (waterfall, rewrite assistant msg) | REMOVED — the assembled message is recorded as-is |
+| `agent/request-error` (waterfall, retry/fail decision) | REMOVED — observe `agent/idle` with `reason.kind === 'error'`, repair, then `agent.retry()` |
+| `agent/turn-continuation` (waterfall, ContinuationDecision) | `agent/continue` (waterfall of `boolean`; handler `(agent, turn, signal, next)`) |
+| `agent/turn-stop` (serial, terminal stop) | REMOVED — `agent/continue` returning `false` stops the turn |
+| `agent/request` `(agent, turn, step, config, signal, next)` | `(agent, turn, step, signal, next)` — the config comes only from `await next()` |
+| `agent/prompt-submit` | unchanged |
+
+New emit: `agent/idle (agent, turn, reason: IdleReason)` fires once per closed turn
+(after turn/end + flush, with `busy` already false, so listeners may synchronously
+`retry()`/`send()`). `IdleReason = completed | aborted | { kind: 'error', error, failure? }`.
+
+## Verb semantics
+
+- `send()` — unchanged (queued FIFO, one turn each).
+- `steer()` while running — enters the outbox; taken whole at the next step
+  boundary. Steering left when the turn closes becomes a queued prompt.
+  There is NO terminal-stop discard of steering anymore.
+- `inject()` while the machine is busy — enters the outbox (a `context/message`
+  appears at the NEXT step boundary, not immediately). While idle — writes a
+  one-shot turn (`turn/start(injection)` + `context/message` + `turn/end`) and
+  requests a flush. Enclosure is decided by `busy`, NOT by scanning the log for
+  an open turn.
+- `retry()` — NEW verb: re-opens a turn on the current log with trigger
+  `{ kind: 'retry' }`. Throws while busy ("cannot retry while busy") and after
+  disposal. Legal from a synchronous `agent/idle` listener.
+- `cancel()` — unchanged surface. No more "pre-run cancelled" bookkeeping:
+  clearing the queue before a run starts simply means no run starts.
+
+## Machine shape (timing-sensitive tests)
+
+- `kick()` runs SYNCHRONOUSLY from `send()` when idle: status flips to
+  `running` inside the `send()` call. There is no parked driver loop, no
+  waitForQueued, no microtask collection window.
+- One `run()` = one turn. The idle tail (`idle()`) runs after turn/end +
+  flush: it sets `busy=false`, emits `agent/idle`, requeues leftover steering,
+  then either kicks the next turn or settles `whenIdle` waiters and flips
+  status to `idle`. Status stays `running` continuously across queued turns.
+- `step/end` is appended INSIDE the step (after tools + the in-step outbox
+  drain), before `agent/continue` runs. The old `post-step → step/end`
+  window no longer exists.
+- Request messages = `session.deriveMessages()` snapshot taken right before
+  `step/start` — no `messagePrefix`. `request/header` events no longer carry
+  a `messagePrefix` field.
+- Provider/model config waterfall (`agent/request`) runs INSIDE the step
+  (after step/start), seeded from agent options (first request) or the folded
+  logged header (later requests).
+- The assembled assistant message is recorded verbatim (with replayState when
+  present); there is no rewrite path and no "content-less anchor on rejection".
+- A model failure (thrown by the adapter or a failure finish chunk) closes the
+  turn: balanced step/end + turn/end `{ kind:'error', step, failure }` +
+  `agent/error` emit + `agent/idle` `{ kind:'error', error, failure }`.
+  There are no in-turn recovery steps.
+- Cancellation classification: signal reason `user`/`parent` → turn/end
+  `aborted`; disposal → `disposed`. IdleReason for both is `aborted`.
+- A blocked prompt (`prompt-submit` → block) records `prompt/blocked`, closes
+  a zero-step turn `rejected` in turn/end, and emits `agent/idle`
+  `{ kind: 'completed' }` (rejection is a policy outcome, not an error).
+- Accept-validation error message is now
+  "agent message content and source must be losslessly JSON-serializable".
+- `dispose()` (the prepared disposer / factory teardown) returns `undefined`
+  when the machine is not busy — do not `.resolves` it unconditionally; use
+  `await Promise.resolve(dispose())`.
+
+## What to do with tests of removed seams
+
+- Rewrite the scenario against the nearest new seam when the protected
+  behavior still exists (e.g. turn-stop tests → `agent/continue` returning
+  false; request-error retry tests → `agent/idle` + `retry()` flows).
+- Delete tests whose subject no longer exists at all (session-prefix
+  reconstruction, step-result rewrite provenance, post-step ordering windows,
+  pre-run-cancel bookkeeping). Do not keep zombie tests alive by weakening
+  their assertions.
+- Keep the durable-log invariants strong: balanced turn/step boundaries,
+  ordered tool call/result pairs, header change tracking — those still hold.
--- a/packages/core/agent-loop/tests/agent.spec.ts
+++ b/packages/core/agent-loop/tests/agent.spec.ts
@@ -5,7 +5,7 @@ import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { bindReactLoopAgentContext, prepareReactLoopAgent, type ReactLoopAgent } from '../src/agent.ts'
 import { MockAdapter, textResponse } from './mock-adapter.ts'

@@ -57,12 +57,12 @@ describe('Agent', () => {
    await ctx.plugin(SessionStore)
    const session = ctx.sessions.create(SessionId('exclusive-driver'))
    const prepared = prepareReactLoopAgent(
-      ctx, SessionId('first-driver'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+      ctx, SessionId('first-driver'), { provider: 'mock', model: 'mock' }, session,
    )

    expect(() => prepared.agent.ctx).toThrow('context is not bound')
    expect(() => prepareReactLoopAgent(
-      ctx, SessionId('second-driver'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+      ctx, SessionId('second-driver'), { provider: 'mock', model: 'mock' }, session,
    ))
      .toThrow('already has a concrete agent driver')

@@ -78,56 +78,11 @@ describe('Agent', () => {
    expect(agent.options).toBe(options)
    expect(agent.id).toBe('owned-bindings')
    expect(agent.session.id).toBe(agent.id)
-    expect(() => { bindReactLoopAgentContext(agent as ReactLoopAgent, new Context()) }).toThrow(/context is already bound/)
+    expect(() => { bindReactLoopAgentContext(agent, new Context()) }).toThrow(/context is already bound/)

    await ctx.fiber.dispose()
  })

-  it('send() throws after disposal', async () => {
-    const adapter = new MockAdapter(['hang'])
-    const ctx = await harness(adapter)
-    let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
-    }, { inject: ['agentLoop'] }))
-    send(agent, 'go')
-    await new Promise(r => setTimeout(r, 30))
-    await fiber.dispose()
-    await driverDone(agent)
-
-    expect(() => { agent.send([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
-  })
-
-  it('steer() throws after disposal', async () => {
-    const adapter = new MockAdapter(['hang'])
-    const ctx = await harness(adapter)
-    let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
-    }, { inject: ['agentLoop'] }))
-    send(agent, 'go')
-    await new Promise(r => setTimeout(r, 30))
-    await fiber.dispose()
-    await driverDone(agent)
-
-    expect(() => { agent.steer([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
-  })
-
-  it('inject() throws after disposal', async () => {
-    const adapter = new MockAdapter(['hang'])
-    const ctx = await harness(adapter)
-    let agent!: Agent
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
-    }, { inject: ['agentLoop'] }))
-    send(agent, 'go')
-    await new Promise(r => setTimeout(r, 30))
-    await fiber.dispose()
-    await driverDone(agent)
-
-    expect(() => { agent.inject([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
-  })
-
  it('inject() decides enclosure from the LOG (open turn), not agent status', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
@@ -277,14 +232,15 @@ describe('Agent', () => {
    await ctx.plugin(AgentRegistry)
    const session = ctx.sessions.create(SessionId('test'))
    const prepared = prepareReactLoopAgent(
-      ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+      ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session,
    )
    const { agent } = prepared

    // Start the loop to get the disposer; the agent waits for messages
    // (idle, never-resolving cancel), so it will stay idle.
    prepared.markPublished()
-    const dispose = prepared.startDriver()
+    prepared.start()
+    const dispose = prepared.dispose

    // First dispose
    const firstDisposal = dispose()
@@ -301,12 +257,13 @@ describe('Agent', () => {
    await ctx.plugin(SessionStore)
    const session = ctx.sessions.create(SessionId('pre-start-dispose'))
    const prepared = prepareReactLoopAgent(
-      ctx, SessionId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+      ctx, SessionId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session,
    )

    await prepared.dispose()
    expect(prepared.agent.status).toBe('disposed')
-    const dispose = prepared.startDriver()
+    prepared.start()
+    const dispose = prepared.dispose
    await dispose()
    await expect(prepared.agent.done).resolves.toBeUndefined()
    expect(prepared.agent.session.events).toEqual([])
@@ -402,11 +359,12 @@ describe('Agent', () => {
    ctx.llm.registerAdapter(['mock'], adapter)
    const session = ctx.sessions.create(SessionId('bare'))
    const prepared = prepareReactLoopAgent(
-      ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+      ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session,
    )
    const { agent } = prepared
    prepared.markPublished()
-    const dispose = prepared.startDriver()
+    prepared.start()
+    const dispose = prepared.dispose
    agent.send([{ type: 'text', text: 'go' }])
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -3,9 +3,9 @@ import { Context } from 'cordis'
 import LlmService, { CallId, ContentBlock, MessageSource, ProviderRequestId, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineContentToolFixture, TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { type Agent, type ContinuationDecision, type HookContext } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
+import ToolRegistry, { defineTool, TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
@@ -60,7 +60,7 @@ describe('session log records what agent/step-result actually produced', () => {
    const adapter = new MockAdapter([original, textResponse('done')])
    const ctx = await harness(adapter)
    const executed: string[] = []
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'injected-tool',
      description: '',
      parameters: {},
@@ -229,7 +229,7 @@ describe('abort during tool execution ends the turn', () => {
    const ctx = await harness(adapter)
    const executed: string[] = []
    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'aborter',
      description: '',
      parameters: {},
@@ -250,7 +250,7 @@ describe('abort during tool execution ends the turn', () => {
        source: { kind: 'plugin', plugin: 'abort-test' },
      }],
    }))
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'second',
      description: '',
      parameters: {},
@@ -275,9 +275,7 @@ describe('abort during tool execution ends the turn', () => {
          order.push(`tool/result:${event.data.callId}:${outcome}`)
          break
        }
-        // Injected context is a plugin-sourced user/message; the direct human
-        // prompt (user source) is not tracked in this ordering.
-        case 'user/message': if (event.data.source.kind !== 'user') order.push('context/message'); break
+        case 'context/message': order.push('context/message'); break
        case 'steering/message': order.push('steering/message'); break
        case 'step/end': order.push('step/end'); break
        case 'turn/end': {
@@ -334,7 +332,7 @@ describe('abort during tool execution ends the turn', () => {
    const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'aborter',
      description: '',
      parameters: {},
@@ -356,14 +354,13 @@ describe('abort during tool execution ends the turn', () => {
    await waitForIdle(ctx, agent)

    const events = [...agent.session.events]
-    const isInjected = (e: SessionEvent): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user'
    expect(events
-      .filter(event => event.type === 'tool/result' || isInjected(event)
+      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
        || event.type === 'step/end' || event.type === 'turn/end')
-      .map(event => isInjected(event) ? 'context/message' : event.type))
+      .map(event => event.type))
      .toEqual(['tool/result', 'context/message', 'context/message', 'step/end', 'turn/end'])
    expect(events
-      .filter(isInjected)
+      .filter(event => event.type === 'context/message')
      .map(event => event.data.content))
      .toEqual([
        [{ type: 'text', text: 'accepted before abort' }],
@@ -381,7 +378,7 @@ describe('abort during tool execution ends the turn', () => {
    ] satisfies StreamChunk[]])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(SessionId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'first',
      description: '',
      parameters: {},
@@ -389,7 +386,7 @@ describe('abort during tool execution ends the turn', () => {
        return [{ type: 'text', text: 'first done' }]
      },
    }))
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'aborter',
      description: '',
      parameters: {},
@@ -413,13 +410,12 @@ describe('abort during tool execution ends the turn', () => {
    await waitForIdle(ctx, agent)

    const events = [...agent.session.events]
-    const isInjected = (e: SessionEvent): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user'
    expect(events
-      .filter(event => event.type === 'tool/result' || isInjected(event)
+      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
        || event.type === 'step/end' || event.type === 'turn/end')
-      .map(event => isInjected(event) ? 'context/message' : event.type))
+      .map(event => event.type))
      .toEqual(['tool/result', 'tool/result', 'context/message', 'step/end', 'turn/end'])
-    expect(events.find(isInjected)?.data.content)
+    expect(events.find(event => event.type === 'context/message')?.data.content)
      .toEqual([{ type: 'text', text: 'accepted after first result' }])
  })

@@ -431,7 +427,7 @@ describe('abort during tool execution ends the turn', () => {
    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
      agent = inner.agentLoop.create(SessionId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
    }, { inject: ['agentLoop'] }))
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'waiter',
      description: '',
      parameters: {},
@@ -460,7 +456,7 @@ describe('abort during tool execution ends the turn', () => {
    await fiber.dispose()

    expect(agent.session.events
-      .filter((event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind !== 'user')
+      .filter(event => event.type === 'context/message')
      .map(event => event.data.content))
      .toEqual([
        [{ type: 'text', text: 'accepted before disposal' }],
@@ -483,7 +479,7 @@ describe('abort during tool execution ends the turn', () => {
    ])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(SessionId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'aborter',
      description: '',
      parameters: {},
@@ -492,7 +488,7 @@ describe('abort during tool execution ends the turn', () => {
        return [{ type: 'text', text: 'done' }]
      },
    }))
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'second',
      description: '',
      parameters: {},
@@ -511,7 +507,7 @@ describe('abort during tool execution ends the turn', () => {
    send(agent, 'start a text-only turn')
    await waitForIdle(ctx, agent)

-    expect(agent.session.events.find((event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind !== 'user')?.data.content)
+    expect(agent.session.events.find(event => event.type === 'context/message')?.data.content)
      .toEqual([{ type: 'text', text: 'new turn context' }])
    expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context')
  })
@@ -767,11 +763,11 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    expect(agent.session.deriveMessages().at(-1)?.content).toEqual([{ type: 'text', text: 'routed' }])
  })

-  it('agent/inbox/enqueue carries the resolved source; steering/message records its source', async () => {
+  it('agent/queued carries the resolved source; steering/message records its source', async () => {
    const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'noop',
      description: '',
      parameters: {},
@@ -781,14 +777,14 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
      },
    }))

-    const queuedSources: { source: MessageSource; contexts: HookContext[]; steering: boolean }[] = []
-    ctx.on('agent/inbox/enqueue', (_agent, info) => void queuedSources.push({ source: info.source, contexts: info.contexts, steering: info.steering }))
+    const queuedSources: { source: MessageSource; steering: boolean }[] = []
+    ctx.on('agent/queued', (_agent, _content, info) => void queuedSources.push(info))

    send(agent, 'go') // no explicit source → default {kind:'user'} must be visible
    await waitForIdle(ctx, agent)

-    expect(queuedSources[0]).toEqual({ source: { kind: 'user' }, contexts: [], steering: false })
-    expect(queuedSources[1]).toEqual({ source: { kind: 'plugin', plugin: 'goal' }, contexts: [], steering: true })
+    expect(queuedSources[0]).toEqual({ source: { kind: 'user' }, steering: false })
+    expect(queuedSources[1]).toEqual({ source: { kind: 'plugin', plugin: 'goal' }, steering: true })
    // The drain appends the durable steering/message with the caller's source
    // intact — the log, not a transient emit, is where consumers read it.
    const steeringSources = agent.session.events.flatMap(e => e.type === 'steering/message' ? [e.data.source] : [])
@@ -803,39 +799,24 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
    let notifiedContent: ContentBlock[] | undefined
    let notifiedSource: MessageSource | undefined
-    let notifiedContexts: HookContext[] | undefined
-    ctx.on('agent/inbox/enqueue', (subject, info) => {
+    ctx.on('agent/queued', (subject, acceptedContent, info) => {
      if (subject !== agent || info.steering) return
      // Retain the exact notification references: cloning here would test the
      // listener's copy rather than the event/inbox ownership boundary.
-      notifiedContent = info.content
+      notifiedContent = acceptedContent
      notifiedSource = info.source
-      notifiedContexts = info.contexts
    })

-    const contexts: HookContext[] = [{
-      content: [{ type: 'text', text: 'accepted-context' }],
-      source: { kind: 'plugin', plugin: 'context-source' },
-      meta: { version: 1 },
-    }]
-    agent.send(content, { source, contexts })
+    agent.send(content, { source })
    content[0]!.text = 'caller-mutated-send'
    source.plugin = 'caller-mutated-source'
-    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-context' }
    await waitForIdle(ctx, agent)

    expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-send' }])
    expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
-    expect(notifiedContexts).toEqual([{
-      content: [{ type: 'text', text: 'accepted-context' }],
-      source: { kind: 'plugin', plugin: 'context-source' },
-      meta: { version: 1 },
-    }])
    expect(Object.isFrozen(notifiedContent)).toBe(true)
    expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
    expect(Object.isFrozen(notifiedSource)).toBe(true)
-    expect(Object.isFrozen(notifiedContexts)).toBe(true)
-    expect(Object.isFrozen(notifiedContexts?.[0]?.content)).toBe(true)
    const recorded = agent.session.events.flatMap(event => event.type === 'user/message' ? [event.data] : [])
    expect(recorded).toContainEqual({
      content: [{ type: 'text', text: 'accepted-send' }],
@@ -843,9 +824,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    })
    const request = JSON.stringify(adapter.requests[0]!.messages)
    expect(request).toContain('accepted-send')
-    expect(request).toContain('accepted-context')
    expect(request).not.toContain('caller-mutated-send')
-    expect(request).not.toContain('caller-mutated-context')
  })

  it('running steer() owns content and source before notification and delivery', async () => {
@@ -854,7 +833,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    const agent = ctx.agentLoop.create(SessionId('owned-steer'), { provider: 'mock', model: 'mock' })
    const entered = Promise.withResolvers<undefined>()
    const release = Promise.withResolvers<undefined>()
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'gate',
      description: '',
      parameters: {},
@@ -866,12 +845,10 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    }))
    let notifiedContent: ContentBlock[] | undefined
    let notifiedSource: MessageSource | undefined
-    let notifiedContexts: HookContext[] | undefined
-    ctx.on('agent/inbox/enqueue', (subject, info) => {
+    ctx.on('agent/queued', (subject, acceptedContent, info) => {
      if (subject !== agent || !info.steering) return
-      notifiedContent = info.content
+      notifiedContent = acceptedContent
      notifiedSource = info.source
-      notifiedContexts = info.contexts
    })

    agent.send([{ type: 'text', text: 'start' }])
@@ -879,86 +856,27 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    expect(agent.status).toBe('running')
    const content = [{ type: 'text' as const, text: 'accepted-steer' }]
    const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
-    const contexts: HookContext[] = [
-      {
-        content: [{ type: 'text', text: 'accepted-steering-prefix' }],
-        source: { kind: 'plugin', plugin: 'steering-prefix' },
-        placement: 'prompt-prefix',
-      },
-      {
-        content: [{ type: 'text', text: 'accepted-steering-context' }],
-        source: { kind: 'plugin', plugin: 'steering-context' },
-        meta: { kind: 'separate-card' },
-      },
-      {
-        content: [{ type: 'text', text: 'accepted-steering-context-without-meta' }],
-        source: { kind: 'plugin', plugin: 'steering-context-without-meta' },
-      },
-    ]
-    agent.steer(content, { source, contexts })
+    agent.steer(content, { source })
    content[0]!.text = 'caller-mutated-steer'
    source.plugin = 'caller-mutated-source'
-    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-steering-prefix' }
-    contexts[0]!.placement = 'separate'
-    contexts[1]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context' }
-    contexts[2]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context-without-meta' }
    const idle = waitForIdle(ctx, agent)
    release.resolve(undefined)
    await idle

    expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-steer' }])
    expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
-    expect(notifiedContexts).toEqual([
-      {
-        content: [{ type: 'text', text: 'accepted-steering-prefix' }],
-        source: { kind: 'plugin', plugin: 'steering-prefix' },
-        placement: 'prompt-prefix',
-      },
-      {
-        content: [{ type: 'text', text: 'accepted-steering-context' }],
-        source: { kind: 'plugin', plugin: 'steering-context' },
-        meta: { kind: 'separate-card' },
-      },
-      {
-        content: [{ type: 'text', text: 'accepted-steering-context-without-meta' }],
-        source: { kind: 'plugin', plugin: 'steering-context-without-meta' },
-      },
-    ])
    expect(Object.isFrozen(notifiedContent)).toBe(true)
    expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
    expect(Object.isFrozen(notifiedSource)).toBe(true)
-    expect(Object.isFrozen(notifiedContexts)).toBe(true)
    const recorded = agent.session.events.flatMap(event => event.type === 'steering/message' ? [event.data] : [])
    expect(recorded).toContainEqual({
      turn: 1,
-      content: [
-        { type: 'text', text: 'accepted-steering-prefix' },
-        { type: 'text', text: '\n\n## My request:\n' },
-        { type: 'text', text: 'accepted-steer' },
-      ],
+      content: [{ type: 'text', text: 'accepted-steer' }],
      source: { kind: 'plugin', plugin: 'accepted-source' },
-      envelope: {
-        displayContent: [{ type: 'text', text: 'accepted-steer' }],
-        prefixContexts: [{
-          source: { kind: 'plugin', plugin: 'steering-prefix' },
-        }],
-      },
    })
    const request = JSON.stringify(adapter.requests[1]!.messages)
    expect(request).toContain('accepted-steer')
-    expect(request).toContain('accepted-steering-prefix')
-    expect(request).toContain('accepted-steering-context')
-    expect(request).toContain('accepted-steering-context-without-meta')
    expect(request).not.toContain('caller-mutated-steer')
-    expect(request).not.toContain('caller-mutated-steering-prefix')
-    expect(request).not.toContain('caller-mutated-steering-context')
-    expect(request).not.toContain('caller-mutated-steering-context-without-meta')
-
-    const steeringIndex = agent.session.events.findIndex(event => event.type === 'steering/message')
-    const contextIndex = agent.session.events.findIndex(event => event.type === 'user/message'
-      && event.data.source.kind === 'plugin' && event.data.source.plugin === 'steering-context')
-    expect(steeringIndex).toBeGreaterThanOrEqual(0)
-    expect(contextIndex).toBe(steeringIndex + 1)
  })
 })

@@ -983,11 +901,11 @@ describe('turn numbering continues across seeded sessions', () => {

    const seeded = ctx2.sessions.create(SessionId('forked'), { seed: [...agent.session.events] })
    const prepared = prepareReactLoopAgent(
-      ctx2, SessionId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+      ctx2, SessionId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded,
    )
    const forked = prepared.agent
    prepared.markPublished()
-    ctx2.effect(() => prepared.startDriver())
+    ctx2.effect(() => { prepared.start(); return prepared.dispose })

    const turns: number[] = []
    ctx2.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
@@ -1501,7 +1419,7 @@ describe('tool result call identity', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: 'echo',
      parameters: { x: { type: 'number' } },
--- a/packages/core/agent-loop/tests/inbox.spec.ts
+++ b/packages/core/agent-loop/tests/inbox.spec.ts
@@ -1,130 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { AgentMessageId } from '@deepseek-ai/dsh-agent'
-import { Inbox } from '../src/inbox.ts'
-
-function message(text: string) {
-  return { id: AgentMessageId(text), content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [], wakeup: true }
-}
-
-function resolverPair() {
-  let r!: () => void
-  const p = new Promise<void>((resolve) => { r = resolve })
-  return { promise: p, resolve: r }
-}
-
-describe('Inbox', () => {
-  it('dequeues one queued message at a time in FIFO order', () => {
-    const inbox = new Inbox()
-    inbox.enqueue(message('first'))
-    inbox.enqueue(message('second'))
-    expect(inbox.hasQueued).toBe(true)
-
-    expect(inbox.dequeueQueued()?.content[0]).toMatchObject({ text: 'first' })
-    expect(inbox.hasQueued).toBe(true)
-    expect(inbox.dequeueQueued()?.content[0]).toMatchObject({ text: 'second' })
-    expect(inbox.hasQueued).toBe(false)
-    expect(inbox.dequeueQueued()).toBeUndefined()
-  })
-
-  it('enqueue(msg, false) queues without waking a parked waiter', async () => {
-    const inbox = new Inbox()
-    let woke = false
-    const waiter = inbox.waitForQueued(new Promise(() => {})).then(() => { woke = true })
-    inbox.enqueue(message('quiet'), false)
-    // The item is queued, but the parked waiter was not resolved by it.
-    expect(inbox.hasQueued).toBe(true)
-    await Promise.resolve()
-    expect(woke).toBe(false)
-    // A later waking enqueue resolves the same waiter.
-    inbox.enqueue(message('loud'))
-    await waiter
-    expect(woke).toBe(true)
-  })
-
-  it('pending() snapshots queued then steering without removing them', () => {
-    const inbox = new Inbox()
-    inbox.enqueue(message('q'))
-    inbox.steer(message('s'))
-    const pending = inbox.pending()
-    expect(pending.map(p => p.steering)).toEqual([false, true])
-    // Snapshot does not drain the FIFOs.
-    expect(inbox.hasQueued).toBe(true)
-    expect(inbox.hasSteering).toBe(true)
-  })
-
-  it('pushes and drains steering messages separately from queued', () => {
-    const inbox = new Inbox()
-    inbox.steer(message('steer'))
-    expect(inbox.hasQueued).toBe(false)
-    expect(inbox.hasSteering).toBe(true)
-
-    const steering = inbox.drainSteering()
-    expect(steering).toHaveLength(1)
-    expect(inbox.hasSteering).toBe(false)
-  })
-
-  it('waitForQueued returns immediately when a queued message is already present', async () => {
-    const inbox = new Inbox()
-    inbox.enqueue(message('ready'))
-
-    const started = Date.now()
-    await inbox.waitForQueued(new Promise(() => {})) // never-resolving cancel
-    expect(Date.now() - started).toBeLessThan(50)
-  })
-
-  it('waitForQueued resolves when a message is enqueued', async () => {
-    const inbox = new Inbox()
-    const waiter = inbox.waitForQueued(new Promise(() => {})) // never-resolving cancel
-    // enqueue after starting the wait
-    setTimeout(() => { inbox.enqueue(message('wake')) }, 5)
-    await waiter
-  })
-
-  it('waitForQueued resolves when the cancel promise resolves', async () => {
-    const inbox = new Inbox()
-    const { promise, resolve } = resolverPair()
-    const waiter = inbox.waitForQueued(promise)
-    resolve()
-    await waiter
-  })
-
-  it('waitForQueued overwrites the previous wakeup callback (only the latest waiter is notified)', async () => {
-    const inbox = new Inbox()
-    const { promise: p1, resolve: r1 } = resolverPair()
-
-    void inbox.waitForQueued(new Promise(() => {})) // first call, never resolved
-    void inbox.waitForQueued(p1) // second call overwrites wakeup
-
-    // Cancelling the latest waiter clears the shared callback; enqueue must neither
-    // wake the stale waiter nor fail on the cleared callback.
-    r1()
-    await p1
-
-    inbox.enqueue(message('hey'))
-  })
-
-  it('clears wakeup in finally handler when enqueue resolves', async () => {
-    const inbox = new Inbox()
-    void inbox.waitForQueued(new Promise(() => {})) // never-resolving cancel
-    // The wakeup is set. Now trigger it via enqueue → wakeup() calls resolve,
-    // promise resolves, finally clears wakeup because wakeup === resolve.
-    inbox.enqueue(message('wake'))
-    // No explicit await needed — enqueue is synchronous, and the microtask
-    // (finally) runs. The key coverage hit is finally with wakeup === resolve.
-  })
-
-  it('finally handler does not clear wakeup when a different waiter overwrote it', async () => {
-    // A stale waiter's finally must not clear the replacement waiter.
-    const inbox = new Inbox()
-    const { promise: c1, resolve: r1 } = resolverPair()
-
-    void inbox.waitForQueued(c1) // wakeup = resolve1, c1.then(resolve1)
-    void inbox.waitForQueued(new Promise(() => {})) // wakeup = resolve2, cancel never resolves
-
-    r1()
-    await c1
-
-    // The replacement remains registered and is resolved by enqueue.
-    inbox.enqueue(message('hey'))
-  })
-})
--- a/packages/core/agent-loop/tests/invariant.spec.ts
+++ b/packages/core/agent-loop/tests/invariant.spec.ts
@@ -47,15 +47,14 @@ describe('request-reconstruction invariant', () => {
    expect(() => { dispatch(ctx, options) }).not.toThrow()
  })

-  it('requires the folded session prefix ahead of derived history', async () => {
+  it('requires the messages to equal the boundary derivation exactly (no unlogged prefix)', async () => {
    const { ctx, session, boundary } = await requestSetup()
-    const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: '<system-reminder>catalog</system-reminder>' }] }
-    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' }, messagePrefix: [prefix] }, reason: 'change' })
-    expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id })) })
-      .not.toThrow()
+    const extra = { role: 'user' as const, content: [{ type: 'text' as const, text: '<system-reminder>catalog</system-reminder>' }] }
    expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })) })
+      .not.toThrow()
+    expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([extra, ...boundary]), sessionId: session.id })) })
      .toThrow(/diverges from the boundary derivation/)
-    expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id })) })
+    expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary, extra]), sessionId: session.id })) })
      .toThrow(/diverges from the boundary derivation/)
  })

--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
-import SessionStore, { SessionId, TurnEndReason, type JsonValue } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineContentToolFixture, defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'

 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -89,7 +89,7 @@ describe('agent loop', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: 'echo back',
      parameters: { text: { type: 'string' } },
@@ -118,27 +118,22 @@ describe('agent loop', () => {
    const types = agent.session.events.map(e => e.type)
    expect(types).toContain('tool/call')
    expect(types).toContain('tool/result')
-    const durableResult = agent.session.events.find(event => event.type === 'tool/result')
-    expect(durableResult?.type === 'tool/result' && 'value' in durableResult.data).toBe(false)
  })

-  it('persists presentation metadata projected from the canonical value', async () => {
+  it('threads a tool-attached meta (execute object return) onto the tool/result event', async () => {
    const adapter = new MockAdapter([
      toolCallResponse('c1', 'writer', { path: 'a.txt' }, 'writing'),
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
+    // A tool that returns the { content, meta } object form: the loop must
+    // persist `meta` on the tool/result event so a UI reproduces the card on replay.
    ctx.tools.register(defineTool({
      name: 'writer',
      description: 'writes a file',
      parameters: { path: { type: 'string' } },
-      output: {
-        schema: { type: 'string' },
-        render: () => [{ type: 'text', text: 'ok' }],
-        presentationMeta: (_args, value) => ({ diffs: [{ path: value, oldText: null, newText: 'x' }] }),
-      },
      async execute() {
-        return 'a.txt'
+        return { content: [{ type: 'text', text: 'ok' }], meta: { diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] } }
      },
    }))
    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -157,7 +152,7 @@ describe('agent loop', () => {
    // projecting this agent's configured model, so the model knows its own name.
    const ctx = await harness(adapter, 'You are a test agent on {{model}}.')
    ctx.systemPrompt.section({ name: 'tool:noop', order: 100, text: 'Use the noop tool wisely.' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'noop',
      description: 'does nothing',
      parameters: {},
@@ -253,7 +248,7 @@ describe('agent loop', () => {
    ['BigInt', { n: 1n }],
    ['Map', new Map([['key', 'value']])],
    ['class instance', new (class ResultMeta { x = 1 })()],
-  ])('rejects non-JSON presentation metadata (%s) before the durable result commit', async (_kind, meta) => {
+  ])('normalizes non-JSON tool meta (%s) before the durable result commit', async (_kind, meta) => {
    const adapter = new MockAdapter([
      toolCallResponse('bad-meta-call', 'bad-meta', {}, 'calling'),
      textResponse('recovered'),
@@ -263,12 +258,7 @@ describe('agent loop', () => {
      name: 'bad-meta',
      description: 'returns invalid durable metadata',
      parameters: {},
-      output: {
-        schema: { type: 'string' },
-        render: (_args, value) => [{ type: 'text', text: value }],
-        presentationMeta: () => meta as unknown as JsonValue,
-      },
-      execute: () => Promise.resolve('apparent success'),
+      execute: () => Promise.resolve({ content: [{ type: 'text' as const, text: 'apparent success' }], meta }),
    }))
    const agent = ctx.agentLoop.create(SessionId('bad-meta-agent'), { provider: 'mock', model: 'mock' })

@@ -281,16 +271,15 @@ describe('agent loop', () => {
      expect(result.data.callId).toBe('bad-meta-call')
      expect(result.data.isError).toBe(true)
      expect(result.data.meta).toBeUndefined()
-      expect(result.data.error).toEqual({ name: 'ToolOutputError', code: 'INVALID_TOOL_OUTPUT' })
      expect(result.data.content).toEqual([{
        type: 'text',
-        text: 'Error: tool "bad-meta" returned invalid output: output.presentationMeta returned non-lossless JSON',
+        text: 'Error: tool result must be losslessly JSON-serializable',
      }])
    }
    // The normalized failure was durably logged and fed back to the model; the
    // turn continued normally instead of failing after an apparent success.
    expect(adapter.requests).toHaveLength(2)
-    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('output.presentationMeta returned non-lossless JSON')
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('losslessly JSON-serializable')
  })

  it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
@@ -337,7 +326,7 @@ describe('agent loop', () => {
    const ctx = await harness(adapter)

    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'slow',
      description: '',
      parameters: {},
@@ -443,7 +432,7 @@ describe('agent loop', () => {
    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
    let visibleDuringTool = false
    const meta = { kind: 'deferred-test', version: 1 }
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'noticer',
      description: 'injects a notice',
      parameters: {},
@@ -505,7 +494,7 @@ describe('agent loop', () => {
    ])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(SessionId('invalid-context'), { provider: 'mock', model: 'mock' })
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'invalid-injector',
      description: 'attempts an invalid context injection',
      parameters: {},
@@ -513,7 +502,7 @@ describe('agent loop', () => {
        expect(() => {
          agent.inject([{ type: 'text', text: 'invalid' }], {
            source: { kind: 'plugin', plugin: 'test' },
-            meta: { bigint: 1n } as never,
+            meta: { bigint: 1n },
          })
        }).toThrow('agent context must be losslessly JSON-serializable')
        return [{ type: 'text', text: 'rejected invalid context' }]
@@ -574,7 +563,7 @@ describe('agent loop', () => {
  it('agent/turn-continuation can veto continuation despite tool calls (budget-guard pattern)', async () => {
    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', { text: 'x' })])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: '',
      parameters: { text: { type: 'string' } },
@@ -622,7 +611,7 @@ describe('agent loop', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo', description: 'echo', parameters: {},
      async execute() { return [{ type: 'text', text: 'echoed' }] },
    }))
@@ -814,7 +803,7 @@ describe('agent loop', () => {
    ]])
    const ctx = await harness(adapter)
    let executions = 0
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: '',
      parameters: { text: { type: 'string' } },
@@ -854,7 +843,7 @@ describe('agent loop', () => {
      { type: 'finish', reason: { kind: 'max-tokens' } },
    ]])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: '',
      parameters: { text: { type: 'string' } },
@@ -941,7 +930,7 @@ describe('agent loop', () => {
      textResponse('continued after tool call'),
    ])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: '',
      parameters: { text: { type: 'string' } },
@@ -1224,7 +1213,6 @@ describe('agent loop', () => {

    expect(agent.status).toBe('disposed')
    expect(ctx.agents.get(SessionId('scoped'))).toBeUndefined()
-    expect(() => { send(agent, 'too late') }).toThrow('disposed')
  })

  it('creates agents from config on startup', async () => {
@@ -1273,7 +1261,7 @@ describe('agent loop', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'echo',
      description: '',
      parameters: { text: { type: 'string' } },
--- a/packages/core/agent-loop/tests/tool-calls.spec.ts
+++ b/packages/core/agent-loop/tests/tool-calls.spec.ts
@@ -9,9 +9,9 @@ import { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import LlmService from '@deepseek-ai/dsh-llm'
-import ToolRegistry, { defineContentToolFixture, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineTool, TOOL_ABORTED_BEFORE_DISPATCH, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
-import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse } from './mock-adapter.ts'

 async function harness(adapter: MockAdapter, maxParallelToolCalls?: number) {
@@ -61,7 +61,7 @@ function multiCall(calls: { id: string; name: string; args: object }[]): StreamC
 function gatedTool(name: string, parallel: boolean) {
  const gates = new Map<string, () => void>()
  const started: string[] = []
-  const tool = defineContentToolFixture({
+  const tool = defineTool({
    name,
    description: `gated ${name}`,
    parameters: { id: { type: 'string', required: true } },
@@ -123,12 +123,12 @@ describe('tool-call scheduler: grouping and barriers', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'r', description: 'read', parameters: { id: { type: 'string', required: true } },
      isConcurrencySafe: () => true,
      async execute(args) { order.push(`r-start-${args.id}`); order.push(`r-end-${args.id}`); return [{ type: 'text', text: 'r' }] },
    }))
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'w', description: 'write', parameters: { id: { type: 'string', required: true } },
      async execute(args) { order.push(`w-${args.id}`); return [{ type: 'text', text: 'w' }] },
    }))
@@ -150,14 +150,14 @@ describe('tool-call scheduler: grouping and barriers', () => {
    ])
    const ctx = await harness(adapter)
    const replacement = gatedExclusiveTool('x')
-    const disposeSafe = ctx.tools.register(defineContentToolFixture({
+    const disposeSafe = ctx.tools.register(defineTool({
      name: 'x',
      description: 'initially safe',
      parameters: { id: { type: 'string', required: true } },
      isConcurrencySafe: () => true,
      async execute(args) { return [{ type: 'text', text: `old-${args.id}` }] },
    }))
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'replace',
      description: 'replace x',
      parameters: { id: { type: 'string', required: true } },
@@ -280,7 +280,8 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)

-    expect(() => new AgentLoop(ctx, { agents: [] })).not.toThrow()
+    const loop = new AgentLoop(ctx, { agents: [] })
+    expect(loop.config.maxParallelToolCalls).toBe(DEFAULT_MAX_PARALLEL_TOOL_CALLS)
    await ctx.fiber.dispose()
  })

@@ -539,14 +540,10 @@ describe('tool-call scheduler: abort handling', () => {
      .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
    expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId))
      .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
-    expect(events(agent).filter(e => e.type === 'tool/result').slice(-2).map(e => ({
-      callId: e.data.callId,
-      isError: e.data.isError,
-      errorInfo: e.data.error,
-    })))
+    expect(events(agent).filter(e => e.type === 'tool/result').slice(-2).map(e => e.data))
      .toEqual([
-        { callId: CallId('c3'), isError: true, errorInfo: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
-        { callId: CallId('c4'), isError: true, errorInfo: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
+        expect.objectContaining({ callId: CallId('c3'), isError: true, error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } }),
+        expect.objectContaining({ callId: CallId('c4'), isError: true, error: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } }),
      ])
    const settled = events(agent).filter(e => e.type === 'tool/result'
      || (e.type === 'user/message' && e.data.source.kind === 'plugin'))
@@ -570,7 +567,7 @@ describe('tool-call scheduler: abort handling', () => {
    const gated = gatedParallelTool('p')
    const exclusive: string[] = []
    ctx.tools.register(gated.tool)
-    ctx.tools.register(defineContentToolFixture({
+    ctx.tools.register(defineTool({
      name: 'x',
      description: 'exclusive',
      parameters: { id: { type: 'string', required: true } },