Merge pull request #21 from deepseek-ai/fix/agent-loop-step-start-order

fix(agent-loop): append step/start before emitting agent/step-start

docs/architecture.md

@@ -134,7 +134,7 @@ forever:
     drain queued → session('user/message'…) → 'turn/start' → emit agent/turn-start
     STEP loop:
       drain steering (late steering from previous step's listeners)
-      emit agent/step-start
+      session('step/start'); emit agent/step-start
       assembly = ctx.systemPrompt.assemble()          ⟵ waterfall system-prompt/assemble
       req = {model, system, tools, messages: session.deriveMessages(), signal}
       req = waterfall agent/request                   ⟵ hooks, compaction, model switch

packages/agent-loop/src/loop.ts

@@ -94,7 +94,7 @@ export interface LoopHandle {
  *     drain queued → session('user/message'…) → 'turn/start' → emit agent/turn-start
  *     STEP loop:
  *       drain steering → session('steering/message')  ⟵ catches late steering
- *       emit agent/step-start
+ *       session('step/start'); emit agent/step-start    ⟵ append before emit (ADR 0003)
  *       assembly = ctx.systemPrompt.assemble()        ⟵ waterfall system-prompt/assemble
  *       req = {model, system, tools, messages: session.deriveMessages(), signal}
  *       req = waterfall agent/request                 ⟵ hooks/compaction/model-switch
@@ -174,8 +174,8 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // (or turn-start listeners on the first step) joins before the request.
     drainSteering(ctx, agent, turn)
 
-    ctx.emit('agent/step-start', agent, turn, step)
     session.append('step/start', { turn, step })
+    ctx.emit('agent/step-start', agent, turn, step)
 
     const abort = new AbortController()
     handle.setAbort(abort)

packages/agent-loop/tests/review-fixes.spec.ts

@@ -610,3 +610,32 @@ describe('HIGH: a finish-error stream chunk ends the turn as error, not complete
     expect(reasons).toEqual([{ kind: 'error', message: 'codeless failure' }])
   })
 })
+
+describe('P1-6: step/start is appended before agent/step-start is emitted', () => {
+  it('a step-start listener sees the step/start event already in session.events', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a-step-order', { model: 'mock' })
+
+    // Capture, at the moment agent/step-start fires, whether the matching
+    // step/start event is already in the log (append-before-emit, ADR 0003).
+    const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
+    ctx.on('agent/step-start', (subject, turn, step) => {
+      if (subject !== agent) return
+      const events = [...subject.session.events]
+      const last = events.at(-1)
+      observed.push({
+        turn,
+        step,
+        lastEventType: last?.type,
+        sawStepStart: events.some(e => e.type === 'step/start' && e.data.turn === turn && e.data.step === step),
+      })
+    })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(observed).toHaveLength(1)
+    expect(observed[0]).toMatchObject({ turn: 1, step: 1, lastEventType: 'step/start', sawStepStart: true })
+  })
+})