fix(agent-loop): address review — quiet-item parking, meta, discard balance

Resolve six review findings on the unified-send change:
- quiet (wakeup:false) queued items no longer un-park the driver; the
  inbox distinguishes hasWakingQueued (drives the loop, idle/quiescence)
  from hasQueued (anything to dequeue), so a lone quiet item parks at idle
  and rides the next waking send. whenIdle/cancel settle off the waking
  signal, so cancelling a parked quiet item no longer hangs whenIdle.
- SendOptions.meta on queued/steering sends now reaches the durable
  user/message and steering/message (was dropped except on injection).
- a terminal agent/turn-stop that drops pending steering emits
  agent/inbox/discard so the enqueue-dequeue-or-discard ledger balances.
- the loop-authored continuation reason is snapshotted and frozen like a
  public send.
- gen-cordis-api collects exported classes (body-stripped) so the now-
  abstract-class Agent and its transitive shapes reappear in the API
  catalog.

Adds regression tests for each and re-records the affected snapshot.
This commit is contained in:
Turtle
2026-07-23 21:41:42 +08:00
parent c402cc2422
commit 98ee4ce429
13 changed files with 245 additions and 24 deletions
@@ -86,4 +86,35 @@ describe('inbox FIFO-conservation invariant', () => {
expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
})
it('stays balanced when a terminal stop discards pending steering', async () => {
const adapter = new MockAdapter([textResponse('done')])
const ctx = await harness(adapter)
const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
const discards: number[] = []
ctx.on('agent/inbox/discard', (subject, messages) => { if (subject === agent) discards.push(messages.length) })
// A continuation reason enqueues a steering item; a terminal stop then drops
// it. The drop must emit a discard so the enqueue ⇒ dequeue-or-discard
// ledger stays balanced (no dangling outstanding id).
ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => {
if (subject !== agent) return next()
return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
})
let stopped = false
ctx.on('agent/turn-stop', (subject) => {
if (subject !== agent || stopped) return undefined
stopped = true
return { action: 'stop' as const }
})
agent.send([{ type: 'text', text: 'go' }])
await waitForIdle(ctx, agent)
expect(discards).toEqual([1]) // the dropped steering item was reported
expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
})
})