feat(core): add post-step request recovery (PR3 phase 1)

packages/core/agent-loop/README.md

@@ -52,7 +52,7 @@ The driver owns one agent for its lifetime. It records turn, step, request, stre
 
 Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. A successful `agent/step-result` stores its transformed content; a rejected result records empty content before the original failure continues. The anchor retains exact chunk provenance (`[]` for a stream with no chunks) and usage when available, while empty content stays out of derived message history.
 
-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.
+Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter `agent/request-error`; middleware, result processing, tools, and `agent/post-step` remain ordinary turn failures. Recovery observes a closed failed step, and a retry rebuilds the request from the durable log in a new numbered step. Cancellation clears pending work and aborts the current step without leaking to the next prompt; model-requested calls that were already durable receive synthetic aborted results when cancellation prevents dispatch. Terminal continuation stops remain authoritative through turn close and durability flush.
 
 ### What belongs to plugins
 

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

@@ -7,37 +7,42 @@
 
 import type { Context } from 'cordis'
 import type { FinishReason, GenerateOptions, LlmCallConfig, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
-import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm'
+import { BlockAssembler, HarnessError, deepFreeze, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm'
 import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
-import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent'
+import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
 import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
 import { createTransmissionLog, recordRequestHeader } from './request-log.ts'
 import type { TransmissionLog } from './request-log.ts'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
-import type {} from '@deepseek-ai/dsh-tools'
+import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import type { ReactLoopAgent } from './agent.ts'
 import type { Inbox } from './inbox.ts'
 
-/** An Error with an optional machine-readable code (e.g., from LlmError or a throwing plugin). */
-type CodedError = Error & { code?: string }
-
 /** Normalize thrown values while preserving an existing error code. */
-function toError(error: unknown): CodedError {
+function toError(error: unknown): RequestError {
   return error instanceof Error ? error : new HarnessError(String(error), 'UNKNOWN', { cause: error })
 }
 
+/** Distinguishes a terminal failure finish from failures in later step processing. */
+class TerminalModelRequestFailure extends Error {
+  constructor(readonly requestError: RequestError) {
+    super(requestError.message, { cause: requestError })
+    this.name = 'TerminalModelRequestFailure'
+  }
+}
+
 /** Convert terminal failure finishes into step errors; unknown extensible finishes remain successful. */
-function finishError(finish: FinishReason): CodedError | undefined {
+function finishError(finish: FinishReason): RequestError | undefined {
   switch (finish.kind) {
     case 'error': {
-      const error: CodedError = new Error(finish.message)
+      const error: RequestError = new Error(finish.message)
       if (finish.code !== undefined) error.code = finish.code
       return error
     }
     case 'aborted': {
-      const error: CodedError = new Error('model stream aborted')
+      const error: RequestError = new Error('model stream aborted')
       error.code = 'ABORTED'
       return error
     }
@@ -51,10 +56,19 @@ function finishError(finish: FinishReason): CodedError | undefined {
  * Build the `{ message, code? }` part of an error payload, omitting the
  * `code` key entirely when absent (exactOptionalPropertyTypes-correct).
  */
-function errorData(err: CodedError): { message: string; code?: string } {
+function errorData(err: RequestError): { message: string; code?: string } {
   return { message: err.message, ...typeof err.code === 'string' ? { code: err.code } : {} }
 }
 
+/** Build the durable result for a model-requested call skipped after cancellation. */
+function skippedToolResult(): ToolExecutionResult {
+  return {
+    content: [{ type: 'text', text: 'Error: tool call skipped because the step was aborted before execution' }],
+    isError: true,
+    error: { name: 'AbortError', code: 'ABORTED' },
+  }
+}
+
 /** Map a successful max-token finish onto the turn reason; other successful finishes add nothing. */
 function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
   switch (finish.kind) {
@@ -168,6 +182,7 @@ async function runTurn(
 
   let reason: TurnEndReason = { kind: 'completed' }
   let step = 0
+  let requestRetryAttempt = 0
   let stepOpen = false
   let errorReported = false
   let terminalStopped = false
@@ -180,7 +195,7 @@ async function runTurn(
   }
 
   // Record the durable turn failure once and contain the live error notification.
-  const failTurn = (err: CodedError): void => {
+  const failTurn = (err: RequestError): void => {
     if (errorReported) return
     errorReported = true
     reason = { kind: 'error', step, ...errorData(err) }
@@ -322,14 +337,65 @@ async function runTurn(
         break
       }
 
-      let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error }
+      let stepOutcome:
+        | { hadToolCalls: boolean; finish: FinishReason }
+        | { requestError: RequestError }
+        | { error: RequestError }
       try {
         stepOutcome = await runStep(
           ctx, events, agent, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal)
       } catch (error: unknown) {
-        stepOutcome = { error: toError(error) }
-      } finally {
+        if (isLlmAdapterFailure(error)) {
+          stepOutcome = { requestError: error }
+        } else if (error instanceof TerminalModelRequestFailure) {
+          stepOutcome = { requestError: error.requestError }
+        } else {
+          stepOutcome = { error: toError(error) }
+        }
+      }
+
+      if ('requestError' in stepOutcome) {
+        // Recovery observes a balanced failed step and the original provider
+        // error while the failed step's signal remains the active owner.
+        closeStep()
+        if (handle.isDisposed() || abort.signal.aborted) {
+          handle.setAbort(undefined)
+          reason = handle.isDisposed()
+            ? { kind: 'disposed' }
+            : { kind: 'aborted', reason: String(abort.signal.reason) }
+          break
+        }
+
+        const defaultDecision: RequestErrorDecision = { action: 'fail' }
+        let recoveryDecision: RequestErrorDecision = defaultDecision
+        try {
+          recoveryDecision = await events.waterfall(
+            'agent/request-error', turn, step, stepOutcome.requestError,
+            requestRetryAttempt, abort.signal,
+            () => Promise.resolve(defaultDecision),
+          )
+        } catch (recoveryError: unknown) {
+          ctx.logger.warn(
+            `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${toError(recoveryError).message}`,
+          )
+        }
         handle.setAbort(undefined)
+
+        // Cancellation and disposal always win over either a recovery decision
+        // or a recovery-listener failure.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (handle.isDisposed() || abort.signal.aborted) {
+          reason = handle.isDisposed()
+            ? { kind: 'disposed' }
+            : { kind: 'aborted', reason: String(abort.signal.reason) }
+          break
+        }
+        if (recoveryDecision.action === 'retry') {
+          requestRetryAttempt += 1
+          continue
+        }
+        failTurn(stepOutcome.requestError)
+        break
       }
 
       if ('error' in stepOutcome) {
@@ -337,7 +403,9 @@ async function runTurn(
         // runLoop re-enqueues it as a queued message, so an abort-then-steer
         // starts a fresh turn instead of being silently consumed.
         closeStep()
+        handle.setAbort(undefined)
         const { error } = stepOutcome
+        /* v8 ignore next -- narrow race: disposal while non-request step work throws. */
         if (handle.isDisposed()) {
           reason = { kind: 'disposed' }
         } else if (abort.signal.aborted) {
@@ -349,6 +417,8 @@ async function runTurn(
         break
       }
 
+      requestRetryAttempt = 0
+
       // Preserve max-token completion unless a later disposal, abort, or error wins.
       const stepReason = stepFinishReason(stepOutcome.finish)
       if (stepReason) reason = stepReason
@@ -356,7 +426,38 @@ async function runTurn(
       // Steering that arrived during streaming/tool execution.
       const steered = drainSteering(agent, handle.inbox, turn)
 
+      try {
+        await events.serial('agent/post-step', turn, step, abort.signal)
+      } catch (error: unknown) {
+        stepOutcome = { error: toError(error) }
+      }
+
+      if ('error' in stepOutcome) {
+        closeStep()
+        handle.setAbort(undefined)
+        /* v8 ignore next -- narrow race: disposal while a post-step listener throws. */
+        if (handle.isDisposed()) {
+          reason = { kind: 'disposed' }
+        } else if (abort.signal.aborted) {
+          /* v8 ignore next -- signal.reason always set by cancellation or disposal. */
+          reason = { kind: 'aborted', reason: String(abort.signal.reason ?? 'aborted') }
+        } else {
+          failTurn(stepOutcome.error)
+        }
+        break
+      }
+
+      if (handle.isDisposed() || abort.signal.aborted) {
+        reason = handle.isDisposed()
+          ? { kind: 'disposed' }
+          : { kind: 'aborted', reason: String(abort.signal.reason) }
+        closeStep()
+        handle.setAbort(undefined)
+        break
+      }
+
       closeStep()
+      handle.setAbort(undefined)
 
       const defaultDecision: ContinuationDecision = { action: stepOutcome.hadToolCalls || steered ? 'continue' : 'stop' }
       let decision: ContinuationDecision
@@ -523,7 +624,7 @@ async function runStep(
 
   // Normalize failure finish chunks into the same path as thrown stream errors.
   const stepError = finishError(assembler.finish)
-  if (stepError) throw stepError
+  if (stepError) throw new TerminalModelRequestFailure(stepError)
 
   if (assembler.finish.kind === 'max-tokens') {
     let message: Message = withoutToolCalls(assembler.message())
@@ -553,25 +654,30 @@ async function runStep(
   const toolCalls = message.content.filter(block => block.type === 'tool-call')
   // Buffer context until all results are appended to preserve call/result adjacency.
   const pendingContext: HookContext[] = []
+  let aborted = signal.aborted
   for (const call of toolCalls) {
-    /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
-    if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
     const callEvent = session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments })
-    let parsedArguments: unknown
-    try {
-      parsedArguments = call.arguments ? JSON.parse(call.arguments) : {}
-    } catch {
-      parsedArguments = call.arguments
+    let result: ToolExecutionResult
+    if (aborted || signal.aborted) {
+      aborted = true
+      result = skippedToolResult()
+    } else {
+      let parsedArguments: unknown
+      try {
+        parsedArguments = call.arguments ? JSON.parse(call.arguments) : {}
+      } catch {
+        parsedArguments = call.arguments
+      }
+      // TODO(pre-tool-input-rewrite): Keep logged history and live presentation aligned;
+      // see docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md.
+      result = await ctx.tools.execute({
+        callId: call.id,
+        name: call.name,
+        arguments: parsedArguments,
+        agent,
+        signal,
+      })
     }
-    // TODO(pre-tool-input-rewrite): Keep logged history and live presentation aligned;
-    // see docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md.
-    const result = await ctx.tools.execute({
-      callId: call.id,
-      name: call.name,
-      arguments: parsedArguments,
-      agent,
-      signal,
-    })
     session.append('tool/result', {
       turn, step,
       // Correlation comes from the immutable execution input; the result does
@@ -584,13 +690,12 @@ async function runStep(
       ...result.meta !== undefined ? { meta: result.meta } : {},
     }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] })
     if (result.additionalContext) pendingContext.push(result.additionalContext)
-    // The signal may flip while the tool is awaited.
-    /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
-    /* v8 ignore stop */
+    if (signal.aborted) aborted = true
   }
 
+  /* v8 ignore next -- signal.reason always set by cancellation or disposal. */
+  if (aborted) throw new Error(String(signal.reason ?? 'aborted'))
+
   // Append buffered context after the complete result batch.
   for (const context of pendingContext) {
     agent.inject(context.content, { source: context.source })

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

@@ -12,10 +12,10 @@ import { Context } from 'cordis'
 import LlmService, { type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
-import { MockAdapter, textResponse } from './mock-adapter.ts'
+import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 async function harness(adapter: MockAdapter) {
   const ctx = new Context()
@@ -139,6 +139,59 @@ describe('Agent.cancel()', () => {
     expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled' }])
   })
 
+  it('cancel from an assistant/message observer skips execution but balances replay', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'danger', {}),
+      textResponse('recovered after cancellation'),
+    ])
+    const ctx = await harness(adapter)
+    let executions = 0
+    ctx.tools.register(defineTool({
+      name: 'danger',
+      description: 'must not run after cancellation',
+      parameters: {},
+      async execute() {
+        executions += 1
+        return [{ type: 'text', text: 'ran' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('cancel-after-assistant-message'), { model: 'mock' })
+    const dispose = ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'assistant/message') {
+        agent.cancel('cancelled after assistant message')
+      }
+    })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('session/event', (_session, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+    dispose()
+
+    expect(executions).toBe(0)
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled after assistant message' }])
+    const call = agent.session.events.find(event => event.type === 'tool/call')
+    const result = agent.session.events.find(event => event.type === 'tool/result')
+    expect(call?.type === 'tool/call' ? call.data.callId : undefined).toBe('c1')
+    expect(result?.type === 'tool/result' ? result.data : undefined).toMatchObject({
+      callId: 'c1',
+      isError: true,
+      error: { name: 'AbortError', code: 'ABORTED' },
+    })
+
+    send(agent, 'continue safely')
+    await waitForIdle(ctx, agent)
+    const replayedResult = adapter.requests[1]!.messages
+      .flatMap(message => message.content)
+      .find(block => block.type === 'tool-result')
+    expect(replayedResult).toMatchObject({ toolCallId: 'c1', isError: true })
+    expect(reasons).toEqual([
+      { kind: 'aborted', reason: 'cancelled after assistant message' },
+      { kind: 'completed' },
+    ])
+  })
+
   it('a prompt sent AFTER a cancelled turn settles runs normally (marker reset)', async () => {
     const adapter = new MockAdapter(['hang', textResponse('second reply')])
     const ctx = await harness(adapter)

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

@@ -204,6 +204,16 @@ describe('abort during tool execution ends the turn', () => {
     expect(executed).toEqual(['aborter'])           // second tool never ran
     expect(adapter.requests).toHaveLength(1)        // no follow-up model call
     expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }])
+    const calls = agent.session.events.filter(event => event.type === 'tool/call')
+    const results = agent.session.events.filter(event => event.type === 'tool/result')
+    expect(calls.map(event => event.data.callId)).toEqual([CallId('c1'), CallId('c2')])
+    expect(results).toHaveLength(2)
+    expect(results[0]!.data).toMatchObject({ callId: CallId('c1'), isError: false })
+    expect(results[1]!.data).toMatchObject({
+      callId: CallId('c2'),
+      isError: true,
+      error: { name: 'AbortError', code: 'ABORTED' },
+    })
   })
 })
 

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

@@ -0,0 +1,442 @@
+/**
+ * Agent-loop coverage for the successful post-step checkpoint and model-request
+ * recovery. These tests keep the recovery boundary narrower than the whole
+ * step and pin retry reconstruction, numbering, cancellation, and identity.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import LlmService, {
+  CallId,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  LlmAdapter,
+  LlmError,
+} from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import type { PostToolDecision } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { maxTokensResponse, textResponse, toolCallResponse } from './mock-adapter.ts'
+
+class FailureScriptAdapter extends LlmAdapter {
+  requests: GenerateOptions[] = []
+
+  constructor(private readonly entries: (Error | StreamChunk[])[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.entries.shift()
+    if (entry === undefined) throw new Error('failure script exhausted')
+    if (entry instanceof Error) throw entry
+    yield* entry
+  }
+}
+
+class IteratorConstructionFailureAdapter extends LlmAdapter {
+  stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<StreamChunk> {
+        throw new LlmError('iterator construction failed', 'ITERATOR_CONSTRUCTION')
+      },
+    }
+  }
+}
+
+class SynchronousDispatchFailureAdapter extends LlmAdapter {
+  constructor(private readonly error: Error) {
+    super()
+  }
+
+  stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    throw this.error
+  }
+}
+
+class IteratorResultGetterFailureAdapter extends LlmAdapter {
+  constructor(
+    private readonly field: 'done' | 'value',
+    private readonly error: Error,
+  ) {
+    super()
+  }
+
+  stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const result = this.field === 'done' ? {} : { done: false }
+    Object.defineProperty(result, this.field, { get: () => { throw this.error } })
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<StreamChunk> {
+        return { next: () => Promise.resolve(result as unknown as IteratorResult<StreamChunk>) }
+      },
+    }
+  }
+}
+
+const streamListenerFailureCases: readonly [string, (ctx: Context) => void][] = [
+  ['synchronous listener throw', (ctx) => {
+    ctx.on('llm/stream', () => { throw new Error('synchronous stream listener failed') })
+  }],
+  ['invalid listener iterable', (ctx) => {
+    ctx.on('llm/stream', () => ({}) as AsyncIterable<StreamChunk>)
+  }],
+  ['listener wrapper iteration failure', (ctx) => {
+    ctx.on('llm/stream', (_options, next) => (async function * () {
+      for await (const chunk of next()) {
+        yield chunk
+        throw new Error('stream listener wrapper failed')
+      }
+    })())
+  }],
+]
+
+async function harness(adapter?: LlmAdapter): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  if (adapter) ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function send(agent: ReactLoopAgent): void {
+  agent.send([{ type: 'text', text: 'go' }])
+}
+
+function contextError(message = 'context too large'): LlmError {
+  return new LlmError(message, CONTEXT_WINDOW_EXCEEDED_CODE, 400)
+}
+
+describe('agent post-step and request-error lifecycle', () => {
+  it('fires post-step after results, buffered context, and steering but before step/end', async () => {
+    const twoCalls: StreamChunk[] = [
+      { type: 'block-start', index: 0, blockType: 'tool-call' },
+      { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('call-1'), name: 'work', arguments: '{}' } },
+      { type: 'block-start', index: 1, blockType: 'tool-call' },
+      { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('call-2'), name: 'work', arguments: '{}' } },
+      { type: 'usage', usage: { inputTokens: 10, outputTokens: 5 } },
+      { type: 'finish', reason: { kind: 'tool-calls' } },
+    ]
+    const adapter = new FailureScriptAdapter([twoCalls, textResponse('done')])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'work',
+      description: 'do work',
+      parameters: {},
+      async execute(_args, exec) {
+        if (exec.callId === CallId('call-2')) {
+          exec.agent?.steer([{ type: 'text', text: 'steered' }], { source: { kind: 'plugin', plugin: 'test' } })
+        }
+        return [{ type: 'text', text: 'worked' }]
+      },
+    }))
+    ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> => ({
+      kind: 'accept',
+      additionalContext: {
+        content: [{ type: 'text', text: `context for ${exec.callId}` }],
+        source: { kind: 'plugin', plugin: 'test' },
+      },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('post-step-order'), { model: 'mock' })
+    const order: string[] = []
+    ctx.on('session/event', (_session, event) => {
+      if (
+        event.type === 'assistant/message' || event.type === 'tool/call'
+        || event.type === 'tool/result' || event.type === 'context/message'
+        || event.type === 'steering/message' || event.type === 'step/end'
+      ) {
+        if (!('step' in event.data) || event.data.step === 1) order.push(event.type)
+      }
+    })
+    ctx.on('agent/post-step', (subject, turn, step, signal) => {
+      if (subject !== agent || step !== 1) return
+      expect({ turn, step, aborted: signal.aborted }).toEqual({ turn: 1, step: 1, aborted: false })
+      subject.inject([{ type: 'text', text: 'listener mutation' }], { source: { kind: 'plugin', plugin: 'post-step' } })
+      order.push('agent/post-step')
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(order).toEqual([
+      'assistant/message',
+      'tool/call',
+      'tool/result',
+      'tool/call',
+      'tool/result',
+      'context/message',
+      'context/message',
+      'steering/message',
+      'context/message',
+      'agent/post-step',
+      'step/end',
+    ])
+  })
+
+  it('fires post-step for max-tokens and lets cancellation override that success', async () => {
+    const adapter = new FailureScriptAdapter([maxTokensResponse('partial')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('cancel-post-step-max-tokens'), { model: 'mock' })
+    let entered!: () => void
+    const postStepEntered = new Promise<void>((resolve) => { entered = resolve })
+    ctx.on('agent/post-step', async (_agent, turn, step, signal) => {
+      expect({ turn, step }).toEqual({ turn: 1, step: 1 })
+      entered()
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    })
+
+    send(agent)
+    const idle = waitForIdle(ctx, agent)
+    await postStepEntered
+    agent.cancel('cancelled during max-tokens post-step')
+    await idle
+
+    expect(agent.session.events.find(event => event.type === 'assistant/message')).toMatchObject({
+      data: { usage: { inputTokens: 10, outputTokens: 7 } },
+    })
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'aborted', reason: 'cancelled during max-tokens post-step' } },
+    })
+  })
+
+  it.each([
+    ['thrown', contextError()],
+    ['in-band', [{ type: 'finish', reason: { kind: 'error', message: 'too large', code: CONTEXT_WINDOW_EXCEEDED_CODE } }] satisfies StreamChunk[]],
+  ] as const)('recovers a %s request failure in a new reconstructable step', async (_style, failure) => {
+    const adapter = new FailureScriptAdapter([failure, textResponse('recovered')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId(`recover-${_style}`), { model: 'mock' })
+    const attempts: number[] = []
+    ctx.on('agent/request-error', async (subject, turn, step, error, attempt) => {
+      expect(subject).toBe(agent)
+      expect({ turn, step, code: error.code }).toEqual({ turn: 1, step: 1, code: CONTEXT_WINDOW_EXCEEDED_CODE })
+      attempts.push(attempt)
+      subject.session.append('context/message', {
+        content: [{ type: 'text', text: 'RECOVERY SURFACE MUTATION' }],
+        source: { kind: 'plugin', plugin: 'test-recovery' },
+      }, { surfaceOp: 'append' })
+      return { action: 'retry' }
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(attempts).toEqual([0])
+    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('RECOVERY SURFACE MUTATION')
+    const starts = agent.session.events.filter(event => event.type === 'step/start')
+    const ends = agent.session.events.filter(event => event.type === 'step/end')
+    expect(starts.map(event => event.data.step)).toEqual([1, 2])
+    expect(ends.map(event => event.data.step)).toEqual([1, 2])
+    const recovery = agent.session.events.find(event => event.type === 'context/message')!
+    expect(ends[0]!.seq).toBeLessThan(recovery.seq)
+    expect(recovery.seq).toBeLessThan(starts[1]!.seq)
+  })
+
+  it.each(streamListenerFailureCases)('does not offer %s to request recovery', async (_name, install) => {
+    const ctx = await harness(new FailureScriptAdapter([textResponse('unused')]))
+    const agent = ctx.agentLoop.create(AgentId(`stream-plugin-${_name.replaceAll(' ', '-')}`), { model: 'mock' })
+    let recoveries = 0
+    install(ctx)
+    ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+      recoveries += 1
+      return next()
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(recoveries).toBe(0)
+    expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'error' } } })
+  })
+
+  it.each(['prompt-submit', 'prompt-assembly', 'pre-step', 'request'] as const)(
+    'does not offer %s middleware failures to request recovery',
+    async (boundary) => {
+      const adapter = new FailureScriptAdapter([textResponse('unused')])
+      const ctx = await harness(adapter)
+      if (boundary === 'prompt-submit') {
+        ctx.on('agent/prompt-submit', () => { throw new Error('prompt submit failed') })
+      } else if (boundary === 'prompt-assembly') {
+        ctx.on('system-prompt/assemble', () => { throw new Error('prompt assembly failed') })
+      } else if (boundary === 'pre-step') {
+        ctx.on('agent/pre-step', () => { throw new Error('pre-step failed') })
+      } else {
+        ctx.on('agent/request', () => { throw new Error('request middleware failed') })
+      }
+      const agent = ctx.agentLoop.create(AgentId(`${boundary}-not-recoverable`), { model: 'mock' })
+      let recoveries = 0
+      ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+        recoveries += 1
+        return next()
+      })
+
+      send(agent)
+      await waitForIdle(ctx, agent)
+
+      expect(recoveries).toBe(0)
+      expect(adapter.requests).toHaveLength(0)
+      expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'error' } } })
+    },
+  )
+
+  it('does not offer result, tool, or post-step plugin failures to request recovery', async () => {
+    for (const failure of ['result', 'tool', 'post-step'] as const) {
+      const adapter = new FailureScriptAdapter([
+        failure === 'tool' ? toolCallResponse(`call-${failure}`, 'work', {}) : textResponse('done'),
+      ])
+      const ctx = await harness(adapter)
+      if (failure === 'result') ctx.on('agent/step-result', () => { throw new Error('result failed') })
+      if (failure === 'post-step') ctx.on('agent/post-step', () => { throw new Error('post-step failed') })
+      if (failure === 'tool') {
+        vi.spyOn(ctx.tools, 'execute').mockRejectedValue(new Error('tool service failed'))
+      }
+      const agent = ctx.agentLoop.create(AgentId(`${failure}-not-recoverable`), { model: 'mock' })
+      let recoveries = 0
+      ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+        recoveries += 1
+        return next()
+      })
+      send(agent)
+      await waitForIdle(ctx, agent)
+      expect(recoveries, failure).toBe(0)
+    }
+  })
+
+  it.each([
+    ['synchronous dispatch', (error: Error) => new SynchronousDispatchFailureAdapter(error)],
+    ['done getter', (error: Error) => new IteratorResultGetterFailureAdapter('done', error)],
+    ['value getter', (error: Error) => new IteratorResultGetterFailureAdapter('value', error)],
+  ] as const)('preserves original Error identity for adapter %s', async (_name, makeAdapter) => {
+    const original = contextError(`${_name} overflow`)
+    const ctx = await harness(makeAdapter(original))
+    const agent = ctx.agentLoop.create(AgentId(`identity-${_name.replaceAll(' ', '-')}`), { model: 'mock' })
+    let seen: Error | undefined
+    ctx.on('agent/request-error', async (_agent, _turn, _step, error, _attempt, _signal, next) => {
+      seen = error
+      return next()
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(seen).toBe(original)
+  })
+
+  it('classifies iterator construction and explicit NO_ADAPTER as model-request failures', async () => {
+    for (const scenario of ['iterator', 'no-adapter'] as const) {
+      const ctx = scenario === 'iterator' ? await harness(new IteratorConstructionFailureAdapter()) : await harness()
+      const agent = ctx.agentLoop.create(AgentId(`request-boundary-${scenario}`), { model: 'mock' })
+      let seen = ''
+      ctx.on('agent/request-error', async (_agent, _turn, _step, error, _attempt, _signal, next) => {
+        seen = error.code ?? ''
+        return next()
+      })
+      send(agent)
+      await waitForIdle(ctx, agent)
+      expect(seen).toBe(scenario === 'iterator' ? 'ITERATOR_CONSTRUCTION' : 'NO_ADAPTER')
+    }
+  })
+
+  it('tracks consecutive retry attempts and resets after a successful request', async () => {
+    const capped = new FailureScriptAdapter([contextError('first overflow'), contextError('second overflow')])
+    const cappedCtx = await harness(capped)
+    const cappedAgent = cappedCtx.agentLoop.create(AgentId('retry-cap'), { model: 'mock' })
+    const cappedAttempts: number[] = []
+    cappedCtx.on('agent/request-error', async (_agent, _turn, _step, _error, attempt, _signal, next) => {
+      cappedAttempts.push(attempt)
+      return attempt < 1 ? { action: 'retry' } : next()
+    })
+    send(cappedAgent)
+    await waitForIdle(cappedCtx, cappedAgent)
+    expect(cappedAttempts).toEqual([0, 1])
+
+    const reset = new FailureScriptAdapter([
+      contextError('first overflow'),
+      toolCallResponse('retry-reset-call', 'work', {}),
+      contextError('later overflow'),
+    ])
+    const resetCtx = await harness(reset)
+    resetCtx.tools.register(defineTool({
+      name: 'work',
+      description: 'continue',
+      parameters: {},
+      async execute() { return [{ type: 'text', text: 'worked' }] },
+    }))
+    const resetAgent = resetCtx.agentLoop.create(AgentId('retry-reset'), { model: 'mock' })
+    const resetAttempts: { step: number; attempt: number }[] = []
+    resetCtx.on('agent/request-error', async (_agent, _turn, step, _error, attempt, _signal, next) => {
+      resetAttempts.push({ step, attempt })
+      return resetAttempts.length === 1 ? { action: 'retry' } : next()
+    })
+    send(resetAgent)
+    await waitForIdle(resetCtx, resetAgent)
+    expect(resetAttempts).toEqual([{ step: 1, attempt: 0 }, { step: 3, attempt: 0 }])
+  })
+
+  it('preserves the original provider error when recovery throws', async () => {
+    const adapter = new FailureScriptAdapter([contextError('original overflow')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('recovery-throws'), { model: 'mock' })
+    ctx.on('agent/request-error', () => { throw new Error('recovery exploded') })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'error', message: 'original overflow', code: CONTEXT_WINDOW_EXCEEDED_CODE } },
+    })
+  })
+
+  it.each(['cancel', 'dispose'] as const)('keeps %s live through request recovery', async (action) => {
+    const adapter = new FailureScriptAdapter([contextError()])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId(`${action}-recovery`), { model: 'mock' })
+    let entered!: () => void
+    const recoveryEntered = new Promise<void>((resolve) => { entered = resolve })
+    ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, signal) => {
+      entered()
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+      return { action: 'retry' }
+    })
+
+    send(agent)
+    const idle = waitForIdle(ctx, agent)
+    await recoveryEntered
+    if (action === 'cancel') {
+      agent.cancel('cancelled during recovery')
+      await idle
+    } else {
+      await ctx.fiber.dispose()
+    }
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: action === 'cancel' ? { kind: 'aborted', reason: 'cancelled during recovery' } : { kind: 'disposed' } },
+    })
+  })
+})