Merge origin/master into worktree/explicit-turn-signal

2026-07-20 21:38:49 +08:00
parent 5190e10d27 7b7d6f38e8
commit a92d2e5f34
1322 changed files with 47895 additions and 20257 deletions
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -4,11 +4,15 @@ import LlmService, { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentExecutionProvider from '@deepseek-ai/dsh-agent-execution'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from './mock-adapter.ts'

+function driverDone(agent: Agent): Promise<void> {
+  return (agent as Agent & { done: Promise<void> }).done
+}
+
 async function harness(adapter: MockAdapter, persona = '') {
  const ctx = new Context()
  await ctx.plugin(LlmService)
@@ -16,7 +20,6 @@ async function harness(adapter: MockAdapter, persona = '') {
  await ctx.plugin(SystemPrompt, { persona })
  await ctx.plugin(ToolRegistry)
  await ctx.plugin(AgentRegistry)
-  await ctx.plugin(AgentExecutionProvider)
  await ctx.plugin(AgentLoop, { agents: [] })
  ctx.llm.registerAdapter(['mock'], adapter)
  return ctx
@@ -27,7 +30,7 @@ async function harness(adapter: MockAdapter, persona = '') {
 * invoke this right after send(), when the loop hasn't woken yet (status is
 * still 'idle' synchronously), so polling the current status would lie.
 */
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
  return new Promise((resolve) => {
    const dispose = ctx.on('agent/status', (subject, status) => {
      if (subject === agent && status === 'idle') {
@@ -38,7 +41,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
  })
 }

-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
  agent.send([{ type: 'text', text }])
 }

@@ -46,7 +49,7 @@ describe('agent loop', () => {
  it('runs a simple turn: queued message → model → idle, with ordered events', async () => {
    const adapter = new MockAdapter([textResponse('hello there')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    // All boundaries — turn and step — are durable session events on the
    // session/event feed (no agent/* mirror). Record them in fire order to
@@ -94,7 +97,7 @@ describe('agent loop', () => {
        return [{ type: 'text', text: `echo: ${args.text}` }]
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    send(agent, 'use the tool')
    await waitForIdle(ctx, agent)
@@ -133,7 +136,7 @@ describe('agent loop', () => {
        return { content: [{ type: 'text', text: 'ok' }], meta: { diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] } }
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    send(agent, 'use the tool')
    await waitForIdle(ctx, agent)
@@ -157,7 +160,7 @@ describe('agent loop', () => {
        return []
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    send(agent, 'hi')
    await waitForIdle(ctx, agent)
@@ -171,13 +174,12 @@ describe('agent loop', () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter, 'Working in {{cwd}}.')
    const handle = await ctx.agents.create({
-      agentId: AgentId('a-cwd'),
      sessionId: SessionId('s-cwd'),
      meta: { cwd: '/work/space' },
      agentOptions: { provider: 'mock', model: 'mock' },
    })

-    const agent = handle.agent as ReactLoopAgent
+    const agent = handle.agent
    send(agent, 'hi')
    await waitForIdle(ctx, agent)

@@ -190,7 +192,7 @@ describe('agent loop', () => {
    const ctx = await harness(adapter, 'In {{cwd}}.')
    const errors: Error[] = []
    ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    send(agent, 'hi')
    await waitForIdle(ctx, agent)
@@ -232,7 +234,7 @@ describe('agent loop', () => {
    ctx.on('agent/request', async (_agent, _turn, _step, config, _signal, _next) => {
      return { ...config, provider: 'mock', model: 'mock' }
    })
-    const agent = ctx.agentLoop.create(AgentId('a-late-model'), {})
+    const agent = ctx.agentLoop.create(SessionId('a-late-model'), {})

    send(agent, 'hi')
    await waitForIdle(ctx, agent)
@@ -258,7 +260,7 @@ describe('agent loop', () => {
      parameters: {},
      execute: () => Promise.resolve({ content: [{ type: 'text' as const, text: 'apparent success' }], meta }),
    }))
-    const agent = ctx.agentLoop.create(AgentId('bad-meta-agent'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('bad-meta-agent'), { provider: 'mock', model: 'mock' })

    send(agent, 'use the tool')
    await waitForIdle(ctx, agent)
@@ -287,7 +289,7 @@ describe('agent loop', () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
    ctx.on('system-prompt/assemble', async () => ({ sections: [], tools: [], variables: {} }))
-    const agent = ctx.agentLoop.create(AgentId('a-no-system'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-no-system'), { provider: 'mock', model: 'mock' })

    send(agent, 'hi')
    await waitForIdle(ctx, agent)
@@ -299,7 +301,7 @@ describe('agent loop', () => {
  it('records raw chunks for replay as assistant/chunk session events', async () => {
    const adapter = new MockAdapter([textResponse('abc')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    send(agent, 'hi')
    await waitForIdle(ctx, agent)
@@ -323,7 +325,7 @@ describe('agent loop', () => {
    ])
    const ctx = await harness(adapter)

-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
    ctx.tools.register(defineTool({
      name: 'slow',
      description: '',
@@ -352,20 +354,30 @@ describe('agent loop', () => {
    expect(flat).toContain('change of plans')
  })

-  it('steering while idle behaves like send (starts a turn)', async () => {
-    const adapter = new MockAdapter([textResponse('ok')])
+  it('same-tick idle steering inherits one-send-one-turn FIFO behavior', async () => {
+    const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

-    agent.steer([{ type: 'text', text: 'hello' }])
-    await waitForIdle(ctx, agent)
-    expect(agent.session.events.some(e => e.type === 'user/message')).toBe(true)
+    const idle = waitForIdle(ctx, agent)
+    agent.steer([{ type: 'text', text: 'first idle steer' }])
+    agent.steer([{ type: 'text', text: 'second idle steer' }])
+    await idle
+
+    expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
+    expect(agent.session.events
+      .filter(event => event.type === 'user/message')
+      .map(event => event.data.content)).toEqual([
+      [{ type: 'text', text: 'first idle steer' }],
+      [{ type: 'text', text: 'second idle steer' }],
+    ])
+    expect(adapter.requests).toHaveLength(2)
  })

  it('inject() while idle wraps context in a one-shot turn, visible to the next request', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    agent.inject([{ type: 'text', text: 'file changed: a.ts' }], { source: { kind: 'plugin', plugin: 'watcher' } })
    // The idle inject records a self-contained turn (turn/start → context/message
@@ -383,13 +395,13 @@ describe('agent loop', () => {
    await waitForIdle(ctx, agent)
    const flat = JSON.stringify(adapter.requests[0]!.messages)
    expect(flat).toContain('file changed: a.ts')
-    expect(flat).toContain('<context source=\\"plugin\\">')
+    expect(flat).not.toContain('<context source=')
  })

-  it('inject() can persist raw structured context without the generic context envelope', async () => {
+  it('inject() persists structured context content verbatim with durable hidden meta', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('raw-context'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('raw-context'), { provider: 'mock', model: 'mock' })
    const text = '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>'
    const meta = {
      kind: 'workspace-instructions',
@@ -399,14 +411,13 @@ describe('agent loop', () => {

    agent.inject([{ type: 'text', text }], {
      source: { kind: 'plugin', plugin: 'workspace-context' },
-      envelope: 'raw',
      meta,
    })
    send(agent, 'go')
    await waitForIdle(ctx, agent)

    const contextEvent = agent.session.events.find(event => event.type === 'context/message')
-    expect(contextEvent?.type === 'context/message' && contextEvent.data).toMatchObject({ envelope: 'raw', meta })
+    expect(contextEvent?.type === 'context/message' && contextEvent.data).toMatchObject({ meta })
    const requestText = JSON.stringify(adapter.requests[0]!.messages)
    expect(requestText).toContain('Additional instructions from: pkg/AGENTS.md')
    expect(requestText).not.toContain('<context source=')
@@ -418,7 +429,7 @@ describe('agent loop', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
    let visibleDuringTool = false
    const meta = { kind: 'deferred-test', version: 1 }
    ctx.tools.register(defineTool({
@@ -430,7 +441,6 @@ describe('agent loop', () => {
        const first = { type: 'text' as const, text: 'mid-turn notice' }
        agent.inject([first], {
          source: { kind: 'plugin', plugin: 'x' },
-          envelope: 'raw',
          meta,
        })
        first.text = 'mutated after inject'
@@ -456,7 +466,6 @@ describe('agent loop', () => {
    expect(contexts).toHaveLength(2)
    expect(result.seq).toBeLessThan(contexts[0]!.seq)
    expect(contexts[0]?.type === 'context/message' && contexts[0].data).toMatchObject({
-      envelope: 'raw',
      meta,
    })
    expect(contexts.flatMap(event => event.type === 'context/message' ? event.data.content : []))
@@ -484,7 +493,7 @@ describe('agent loop', () => {
      textResponse('done'),
    ])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('invalid-context'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('invalid-context'), { provider: 'mock', model: 'mock' })
    ctx.tools.register(defineTool({
      name: 'invalid-injector',
      description: 'attempts an invalid context injection',
@@ -514,7 +523,7 @@ describe('agent loop', () => {
      textResponse('step 3'),
    ])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    let steps = 0
    ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -540,7 +549,7 @@ describe('agent loop', () => {
        return [{ type: 'text', text: String(args.text) }]
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    ctx.on('agent/turn-continuation', async () => ({ action: 'stop' }) as const)

@@ -555,7 +564,7 @@ describe('agent loop', () => {
  it('agent/request waterfall switches models by returning a replacement config; the switch is logged', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    ctx.on('agent/request', async (_agent, _turn, _step, config, _signal, _next) => {
      // The seed is frozen — config is not a mutable per-call knob; a switch
@@ -575,10 +584,6 @@ describe('agent loop', () => {
  })

  it('agent/pre-step fires once per step before the step is opened', async () => {
-    // Two steps (a tool call, then a final text turn) → two model calls → two
-    // pre-step fires, each carrying the assembled full system prompt, BEFORE
-    // the step is opened and its request is derived (the request the adapter
-    // sees reflects any surface state at fire time).
    const adapter = new MockAdapter([
      toolCallResponse('c1', 'echo', {}, 'calling echo'),
      textResponse('done'),
@@ -588,23 +593,21 @@ describe('agent loop', () => {
      name: 'echo', description: 'echo', parameters: {},
      async execute() { return [{ type: 'text', text: 'echoed' }] },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

-    const fires: { turn: number; step: number; fullSystemPrompt: string }[] = []
-    ctx.on('agent/pre-step', (subject, turn, step, fullSystemPrompt) => {
-      if (subject === agent) fires.push({ turn, step, fullSystemPrompt })
+    const fires: { turn: number; step: number; signal: AbortSignal }[] = []
+    ctx.on('agent/pre-step', (subject, turn, step, signal) => {
+      if (subject === agent) fires.push({ turn, step, signal })
    })

    send(agent, 'go')
    await waitForIdle(ctx, agent)

-    // One fire per step, in order, each with the assembled system prompt
-    // (here just the loop's own harness-identity section — no persona set).
-    const HARNESS = 'You are an AI agent powered by the DeepSeek Harness SDK.'
-    expect(fires).toEqual([
-      { turn: 1, step: 1, fullSystemPrompt: HARNESS },
-      { turn: 1, step: 2, fullSystemPrompt: HARNESS },
+    expect(fires.map(({ turn, step }) => ({ turn, step }))).toEqual([
+      { turn: 1, step: 1 },
+      { turn: 1, step: 2 },
    ])
+    expect(fires.every(({ signal }) => signal instanceof AbortSignal)).toBe(true)
  })

  it('agent/pre-step fires BEFORE the step it precedes opens (events land outside the step)', async () => {
@@ -612,7 +615,7 @@ describe('agent loop', () => {
    // same step's request must include it.
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    let injected = false
    ctx.on('agent/pre-step', (subject) => {
@@ -646,7 +649,7 @@ describe('agent loop', () => {
    // closing, the turn records error, and the loop remains available.
    const adapter = new MockAdapter([textResponse('second turn ok')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    let throwOnce = true
    ctx.on('agent/pre-step', () => {
@@ -680,7 +683,7 @@ describe('agent loop', () => {
  it('cancel() mid-stream ends the turn with reason aborted', async () => {
    const adapter = new MockAdapter(['hang'])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const reasons: TurnEndReason[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -700,7 +703,7 @@ describe('agent loop', () => {
    // turn stops by default and ends max-tokens, not completed.
    const adapter = new MockAdapter([maxTokensResponse('truncat')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const reasons: TurnEndReason[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -723,7 +726,7 @@ describe('agent loop', () => {
      textResponse('second half'),
    ])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    let steps = 0
    ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -754,7 +757,7 @@ describe('agent loop', () => {
    // stop. The per-turn reason must be independent — turn 2 ends completed.
    const adapter = new MockAdapter([maxTokensResponse('cut'), textResponse('clean')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const reasons: TurnEndReason[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -787,7 +790,7 @@ describe('agent loop', () => {
        return [{ type: 'text', text: 'should not run' }]
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const reasons: TurnEndReason[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -824,7 +827,7 @@ describe('agent loop', () => {
      parameters: { text: { type: 'string' } },
      async execute() { return [{ type: 'text', text: 'should not run' }] },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const reasons: TurnEndReason[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -849,7 +852,7 @@ describe('agent loop', () => {
    // a durable successful-call boundary for replay consumers.
    const adapter = new MockAdapter([[{ type: 'finish', reason: { kind: 'stop' } }]])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const reasons: TurnEndReason[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -886,7 +889,7 @@ describe('agent loop', () => {
      expect(message.content).toEqual([{ type: 'text', text: 'partial text' }])
      return next()
    })
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    send(agent, 'go')
    await waitForIdle(ctx, agent)
@@ -913,7 +916,7 @@ describe('agent loop', () => {
        return [{ type: 'text', text: String(args.text) }]
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
    let threw = false
    // Post-commit session observers cannot control the loop. The tool call still
    // drives the second model request, and the turn completes normally.
@@ -929,10 +932,152 @@ describe('agent loop', () => {
    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('completed')
  })

-  it('chains queued messages into consecutive turns', async () => {
+  it('keeps same-tick sends in separate turns and checkpoints before the next starts', async () => {
+    const adapter = new MockAdapter([textResponse('first answer'), textResponse('second answer')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    const firstFlush = Promise.withResolvers<undefined>()
+    const releaseFirstFlush = Promise.withResolvers<undefined>()
+    let flushes = 0
+    ctx.on('session/flush', async (session) => {
+      if (session !== agent.session) return
+      flushes += 1
+      if (flushes === 1) {
+        firstFlush.resolve(undefined)
+        await releaseFirstFlush.promise
+      }
+    })
+
+    const turns: number[] = []
+    ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'turn/start') turns.push(event.data.turn)
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'first message')
+    send(agent, 'second message')
+
+    await firstFlush.promise
+    expect(turns).toEqual([1])
+    expect(adapter.requests).toHaveLength(1)
+
+    releaseFirstFlush.resolve(undefined)
+    await idle
+
+    expect(turns).toEqual([1, 2])
+    expect(flushes).toBe(2)
+    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('first answer')
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('second message')
+  })
+
+  it('holds a turn-end listener send behind the closing turn checkpoint', async () => {
+    const adapter = new MockAdapter([textResponse('first answer'), textResponse('second answer')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    const firstFlush = Promise.withResolvers<undefined>()
+    const releaseFirstFlush = Promise.withResolvers<undefined>()
+    let flushes = 0
+    ctx.on('session/flush', async (session) => {
+      if (session !== agent.session) return
+      flushes += 1
+      if (flushes === 1) {
+        firstFlush.resolve(undefined)
+        await releaseFirstFlush.promise
+      }
+    })
+
+    const turns: number[] = []
+    const statuses: string[] = []
+    ctx.on('agent/status', (subject, status) => {
+      if (subject === agent) statuses.push(status)
+    })
+    ctx.on('session/event', (session, event) => {
+      if (session !== agent.session) return
+      if (event.type === 'turn/start') turns.push(event.data.turn)
+      if (event.type === 'turn/end' && event.data.turn === 1) send(agent, 'turn-end listener message')
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'first message')
+    await firstFlush.promise
+
+    expect(turns).toEqual([1])
+    expect(adapter.requests).toHaveLength(1)
+
+    releaseFirstFlush.resolve(undefined)
+    await idle
+
+    expect(turns).toEqual([1, 2])
+    expect(statuses).toEqual(['running', 'idle'])
+    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('first answer')
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('turn-end listener message')
+  })
+
+  it('keeps a reentrant agent/queued send as the next independent turn', async () => {
    const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    let nested = false
+    ctx.on('agent/queued', (subject) => {
+      if (subject !== agent || nested) return
+      nested = true
+      send(agent, 'queued listener message')
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'outer message')
+    await idle
+
+    const turns = agent.session.events.filter(event => event.type === 'turn/start')
+    const messages = agent.session.events
+      .filter(event => event.type === 'user/message')
+      .map(event => event.data.content)
+    expect(turns).toHaveLength(2)
+    expect(messages).toEqual([
+      [{ type: 'text', text: 'outer message' }],
+      [{ type: 'text', text: 'queued listener message' }],
+    ])
+  })
+
+  it('preserves independent turn sources across an adjacent microtask send', async () => {
+    const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    const idle = waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'user message' }])
+    await Promise.resolve()
+    agent.send(
+      [{ type: 'text', text: 'plugin message' }],
+      { source: { kind: 'plugin', plugin: 'test' } },
+    )
+    await idle
+
+    const triggers = agent.session.events
+      .filter(event => event.type === 'turn/start')
+      .map(event => event.data.trigger)
+    const sources = agent.session.events
+      .filter(event => event.type === 'user/message')
+      .map(event => event.data.source)
+    expect(triggers).toEqual([
+      { kind: 'message', source: { kind: 'user' } },
+      { kind: 'message', source: { kind: 'plugin', plugin: 'test' } },
+    ])
+    expect(sources).toEqual([
+      { kind: 'user' },
+      { kind: 'plugin', plugin: 'test' },
+    ])
+  })
+
+  it('keeps a session-listener send after dequeue in the following turn', async () => {
+    const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const turns: number[] = []
    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
@@ -952,12 +1097,43 @@ describe('agent loop', () => {

    expect(turns).toEqual([1, 2])
    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('first')
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('second message')
+  })
+
+  it('keeps a model-adapter callback send in the following turn', async () => {
+    const agentRef: { current?: Agent } = {}
+    const adapter = new MockAdapter([
+      () => {
+        const agent = agentRef.current
+        if (agent === undefined) throw new Error('model callback ran before agent setup')
+        send(agent, 'model callback message')
+        return textResponse('first')
+      },
+      textResponse('second'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agentRef.current = agent
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'outer message')
+    await idle
+
+    const messages = agent.session.events
+      .filter(event => event.type === 'user/message')
+      .map(event => event.data.content)
+    expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
+    expect(messages).toEqual([
+      [{ type: 'text', text: 'outer message' }],
+      [{ type: 'text', text: 'model callback message' }],
+    ])
  })

  it('awaits session/flush at turn end (persistence checkpoint)', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    let flushed = 0
    let flushedBeforeIdle = false
@@ -977,7 +1153,7 @@ describe('agent loop', () => {
  it('errors from the model surface as agent/error and end the turn', async () => {
    const adapter = new MockAdapter([]) // script exhausted → throws
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    const errors: Error[] = []
    const reasons: TurnEndReason[] = []
@@ -1000,21 +1176,21 @@ describe('agent loop', () => {
    const adapter = new MockAdapter(['hang'])
    const ctx = await harness(adapter)

-    let agent!: ReactLoopAgent
+    let agent!: Agent
    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
    }, { inject: ['agentLoop'] }))

-    expect(ctx.agents.get(AgentId('scoped'))).toBe(agent)
+    expect(ctx.agents.get(SessionId('scoped'))).toBe(agent)
    send(agent, 'go')
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')

    await fiber.dispose()
-    await agent.done
+    await driverDone(agent)

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

@@ -1026,15 +1202,15 @@ describe('agent loop', () => {
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(AgentExecutionProvider)
    await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), provider: 'mock', model: 'mock' }],
+      agents: [{ id: SessionId('config-agent'), provider: 'mock', model: 'mock' }],
    })
    ctx.llm.registerAdapter(['mock'], adapter)

-    const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
+    const agent = ctx.agents.list()[0]!
    expect(agent).toBeDefined()
-    expect(agent.id).toBe('config-agent')
+    expect(agent.id).toBe(agent.session.id)
+    expect(agent.id).toMatch(/^config-agent-session-/)
    expect(agent.options.model).toBe('mock')

    // the agent is alive: send triggers a turn
@@ -1050,12 +1226,11 @@ describe('agent loop', () => {
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(AgentExecutionProvider)
    await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), provider: 'mock', model: 'mock', cwd: '/work/project' }],
+      agents: [{ id: SessionId('config-agent'), provider: 'mock', model: 'mock', cwd: '/work/project' }],
    })

-    const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
+    const agent = ctx.agents.list()[0]!
    expect(agent.session.header.cwd).toBe('/work/project')
  })

@@ -1073,7 +1248,7 @@ describe('agent loop', () => {
        return [{ type: 'text', text: String(args.text) }]
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
    send(agent, 'run')
    await waitForIdle(ctx, agent)