feat(llm): add replay token metering (PR2 round 1)

packages/core/agent-loop/README.md

@@ -50,6 +50,8 @@ Configured agents start automatically. `cwd` applies only to fresh sessions; `re
 
 The driver owns one agent for its lifetime. It records turn, step, request, stream, and tool boundaries in the session log; live extension events coordinate policy around those durable facts. The [architecture turn flow](../../../docs/architecture.md#turn-flow) and generated [event catalog](../../../docs/cordis-catalog/events.md) are the authoritative sequence and signatures.
 
+Every provider call that reaches a successful finish appends one `assistant/message` completion anchor after `agent/step-result`, including content-less calls and `max-tokens` finishes. The anchor records exact chunk provenance (`[]` for a stream with no chunks) and usage when available; empty content stays out of derived message history while those replay facts remain durable.
+
 Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush.
 
 ### What belongs to plugins

packages/core/agent-loop/src/loop.ts

@@ -528,15 +528,14 @@ async function runStep(
   if (assembler.finish.kind === 'max-tokens') {
     let message: Message = withoutToolCalls(assembler.message())
     message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)))
-    // Preserve usage even when max-token truncation produced no content.
-    if (message.content.length > 0 || assembler.usage) {
-      // The finish chunk guarantees non-empty provenance here.
-      session.append(
-        'assistant/message',
-        { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
-        { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
-      )
-    }
+    // Every successful call records its completion anchor. Empty content is
+    // skipped by deriveMessages(), while exact chunk provenance lets replay
+    // distinguish a known empty provider stream from unrecorded provenance.
+    session.append(
+      'assistant/message',
+      { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
+      { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+    )
     return { hadToolCalls: false, finish: assembler.finish }
   }
 
@@ -544,14 +543,14 @@ async function runStep(
   let message: Message = assembler.message()
   message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))
 
-  // Empty messages exist only to carry usage; omit empty provenance.
-  if (message.content.length > 0 || assembler.usage) {
-    session.append(
-      'assistant/message',
-      { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
-      { surfaceOp: 'append', ...(chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {}) },
-    )
-  }
+  // Every successful call records its completion anchor. A present empty
+  // source set means the provider stream was known to contain no chunks;
+  // omission remains the conservative legacy/unrecorded representation.
+  session.append(
+    'assistant/message',
+    { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
+    { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+  )
 
   // Tool execution stays sequential; recheck abort around each normalized result.
   const toolCalls = message.content.filter(block => block.type === 'tool-call')

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -1075,9 +1075,10 @@ describe('tool result call identity', () => {
   })
 })
 
-describe('surface: assistant/message omits sourceEventSeqs when no chunks streamed', () => {
-  it('a step-result listener injecting content over an empty stream appends with surfaceOp but no sourceEventSeqs', async () => {
-    // Injected result content with no chunks must omit empty sourceEventSeqs.
+describe('surface: assistant/message records exact empty provenance when no chunks streamed', () => {
+  it('a step-result listener injecting content over an empty stream records sourceEventSeqs []', async () => {
+    // The explicit empty source set distinguishes a known empty provider
+    // stream from legacy events whose provenance was not recorded.
     const adapter = new MockAdapter([[]])
     const ctx = await harness(adapter)
     await ctx.plugin(Invariants)
@@ -1094,7 +1095,7 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream
     const recorded = agent.session.events.find(e => e.type === 'assistant/message')!
     expect(recorded.type).toBe('assistant/message')
     expect(recorded.surfaceOp).toBe('append')
-    expect(recorded.sourceEventSeqs).toBeUndefined()
+    expect(recorded.sourceEventSeqs).toEqual([])
     // The injected content reaches derived history.
     expect(JSON.stringify(agent.session.deriveMessages())).toContain('injected')
   })

packages/core/agent-loop/tests/loop.spec.ts

@@ -717,10 +717,9 @@ describe('agent loop', () => {
     })
   })
 
-  it('appends no assistant/message for a max-tokens step with empty content and no usage', async () => {
-    // A max-tokens step truncated to a dropped tool call AND with no usage chunk has nothing to
-    // record: empty content and no accounting → no assistant/message (the empty-content host
-    // exists only to carry usage).
+  it('appends an empty completion anchor for a max-tokens step with no usage', async () => {
+    // The truncated tool call is dropped from durable content, while the
+    // successful provider call still needs an exact replay anchor.
     const callId = CallId('c1')
     const adapter = new MockAdapter([[
       { type: 'block-start', index: 0, blockType: 'tool-call' },
@@ -744,14 +743,19 @@ describe('agent loop', () => {
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    expect(agent.session.events.some(e => e.type === 'assistant/message')).toBe(false)
+    const assistant = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(assistant.type === 'assistant/message' && assistant.data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+    })
+    expect(assistant.sourceEventSeqs?.length).toBeGreaterThan(0)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
   })
 
-  it('appends no assistant/message for a normal stop finish with empty content and no usage', async () => {
-    // A clean `stop` finish that streamed nothing assembled (no blocks) and
-    // carried no usage chunk has nothing to record: the content-or-usage guard
-    // on the normal step path suppresses a pure trace-only empty assistant/message.
+  it('appends an empty completion anchor for a normal stop with no usage', async () => {
+    // A clean content-less call stays absent from derived messages but remains
+    // 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'), { model: 'mock' })
@@ -763,7 +767,13 @@ describe('agent loop', () => {
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'completed' }])
-    expect(agent.session.events.some(e => e.type === 'assistant/message')).toBe(false)
+    const assistant = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(assistant.type === 'assistant/message' && assistant.data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+    })
+    expect(assistant.sourceEventSeqs?.length).toBe(1)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
   })