Capture Codex reasoning summaries (#4617)

## Summary
- request OpenAI/Codex reasoning summaries by default when enabling
reasoning effort
- preserve explicit reasoning summary settings from caller payloads
- add adapter coverage proving streamed thinking events are written as
entity reasoning rows/deltas

## Verification
- cd packages/agents-runtime && pnpm exec vitest run
test/pi-adapter.test.ts
- cd packages/agents && pnpm exec vitest run test/model-catalog.test.ts

---------

Co-authored-by: Sam Willis <sam.willis@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

.changeset/capture-codex-reasoning-summaries.md

@@ -0,0 +1,6 @@
+---
+'@electric-ax/agents': patch
+'@electric-ax/agents-runtime': patch
+---
+
+Capture OpenAI Codex reasoning summaries by default when built-in reasoning is enabled while preserving explicit reasoning summary settings from caller payloads.

packages/agents-runtime/test/pi-adapter.test.ts

@@ -689,6 +689,145 @@ describe(`createPiAgentAdapter`, () => {
     )
   })
 
+  it(`writes reasoning rows for streamed thinking events`, async () => {
+    const events: Array<ChangeEvent> = []
+    const usage = {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        total: 0,
+      },
+    }
+    const startMessage: AssistantMessage = {
+      role: `assistant`,
+      content: [],
+      api: `openai-codex-responses`,
+      provider: `openai-codex`,
+      model: `gpt-5.4`,
+      usage,
+      stopReason: `stop`,
+      timestamp: Date.now(),
+    }
+    const partialMessage: AssistantMessage = {
+      ...startMessage,
+      content: [{ type: `thinking`, thinking: `**Updating PR**\n\n` }],
+    }
+    const finalMessage: AssistantMessage = {
+      ...startMessage,
+      content: [
+        {
+          type: `thinking`,
+          thinking: `**Updating PR**\n\nI'm updating the PR description.`,
+        },
+      ],
+    }
+
+    const factory = createPiAgentAdapter({
+      systemPrompt: `Test system prompt`,
+      provider: `openai-codex`,
+      model: `gpt-5.4`,
+      tools: [],
+      streamFn: () => {
+        const stream = createAssistantMessageEventStream()
+        queueMicrotask(() => {
+          stream.push({ type: `start`, partial: startMessage })
+          stream.push({
+            type: `thinking_start`,
+            contentIndex: 0,
+            partial: partialMessage,
+          })
+          stream.push({
+            type: `thinking_delta`,
+            contentIndex: 0,
+            delta: `**Updating PR**\n\n`,
+            partial: partialMessage,
+          })
+          stream.push({
+            type: `thinking_delta`,
+            contentIndex: 0,
+            delta: `I'm updating the PR description.`,
+            partial: finalMessage,
+          })
+          stream.push({
+            type: `thinking_end`,
+            contentIndex: 0,
+            content: `**Updating PR**\n\nI'm updating the PR description.`,
+            partial: finalMessage,
+          })
+          stream.end(finalMessage)
+        })
+        return stream
+      },
+    })
+
+    const handle = factory({
+      entityUrl: `test/entity-1`,
+      epoch: 1,
+      messages: [],
+      outboundIdSeed: { run: 0, step: 0, msg: 0, tc: 0, reasoning: 0 },
+      writeEvent: (event: ChangeEvent) => {
+        events.push(event)
+      },
+    })
+
+    await handle.run(`hello`)
+
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: `reasoning`,
+        headers: expect.objectContaining({ operation: `insert` }),
+        key: `reasoning-0`,
+        value: expect.objectContaining({
+          status: `streaming`,
+          run_id: `run-0`,
+        }),
+      })
+    )
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: `reasoning_delta`,
+        headers: expect.objectContaining({ operation: `insert` }),
+        key: `reasoning-0:0`,
+        value: expect.objectContaining({
+          reasoning_id: `reasoning-0`,
+          run_id: `run-0`,
+          delta: `**Updating PR**\n\n`,
+        }),
+      })
+    )
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: `reasoning_delta`,
+        headers: expect.objectContaining({ operation: `insert` }),
+        key: `reasoning-0:1`,
+        value: expect.objectContaining({
+          reasoning_id: `reasoning-0`,
+          run_id: `run-0`,
+          delta: `I'm updating the PR description.`,
+        }),
+      })
+    )
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: `reasoning`,
+        headers: expect.objectContaining({ operation: `update` }),
+        key: `reasoning-0`,
+        value: expect.objectContaining({
+          status: `completed`,
+          run_id: `run-0`,
+          summary_title: `Updating PR`,
+        }),
+      })
+    )
+  })
+
   it(`isRunning returns false initially`, () => {
     const factory = createPiAgentAdapter({
       systemPrompt: `Test system prompt`,

packages/agents/src/model-catalog.ts

@@ -270,6 +270,37 @@ function resolveBuiltinReasoning(
   return reasoningEffort ?? `minimal`
 }
 
+function resolveBuiltinPayloadMapper(
+  choice: BuiltinModelChoice,
+  reasoning: AgentConfig[`reasoning`] | undefined
+): AgentConfig[`onPayload`] | undefined {
+  if (
+    !choice.reasoning ||
+    (choice.provider !== `openai` && choice.provider !== `openai-codex`) ||
+    !reasoning
+  ) {
+    return undefined
+  }
+
+  return (payload) => {
+    if (typeof payload !== `object` || payload === null) return undefined
+    const body = payload as Record<string, unknown>
+    const existingReasoning =
+      typeof body.reasoning === `object` && body.reasoning !== null
+        ? (body.reasoning as Record<string, unknown>)
+        : {}
+
+    return {
+      ...body,
+      reasoning: {
+        ...existingReasoning,
+        effort: reasoning,
+        summary: existingReasoning.summary ?? `auto`,
+      },
+    }
+  }
+}
+
 function parseReasoningEffort(value: unknown): ExplicitReasoningEffort | null {
   return value === `minimal` ||
     value === `low` ||
@@ -345,11 +376,13 @@ export function resolveBuiltinModelConfig(
 
   const choice = selected ?? catalog.defaultChoice
   const reasoning = resolveBuiltinReasoning(choice, reasoningEffort)
+  const onPayload = resolveBuiltinPayloadMapper(choice, reasoning)
   const config: BuiltinAgentModelConfig = {
     provider: choice.provider,
     model: choice.id,
     ...(reasoningEffort && { reasoningEffort }),
     ...(reasoning && { reasoning }),
+    ...(onPayload && { onPayload }),
     ...(choice.reasoning &&
       choice.provider === `anthropic` && {
         thinkingBudgets: ANTHROPIC_THINKING_BUDGETS,

packages/agents/test/model-catalog.test.ts

@@ -119,7 +119,16 @@ describe(`model catalog`, () => {
       model: `gpt-5`,
       reasoning: `minimal`,
     })
-    expect(config.onPayload).toBeUndefined()
+    expect(config.onPayload).toBeTypeOf(`function`)
+
+    const payload = config.onPayload!(
+      { reasoning: { effort: `none` } },
+      {} as any
+    )
+
+    expect(payload).toEqual({
+      reasoning: { effort: `minimal`, summary: `auto` },
+    })
   })
 
   it(`uses explicit reasoning effort for OpenAI reasoning models`, async () => {
@@ -131,6 +140,31 @@ describe(`model catalog`, () => {
 
     expect(config.reasoningEffort).toBe(`high`)
     expect(config.reasoning).toBe(`high`)
+
+    const payload = config.onPayload!(
+      { reasoning: { effort: `none` } },
+      {} as any
+    )
+
+    expect(payload).toEqual({
+      reasoning: { effort: `high`, summary: `auto` },
+    })
+  })
+
+  it(`preserves an explicit OpenAI reasoning summary setting`, async () => {
+    const catalog = await createBuiltinModelCatalog()
+    const config = resolveBuiltinModelConfig(catalog!, {
+      model: `openai:gpt-5`,
+    })
+
+    const payload = config.onPayload!(
+      { reasoning: { effort: `none`, summary: `detailed` } },
+      {} as any
+    )
+
+    expect(payload).toEqual({
+      reasoning: { effort: `minimal`, summary: `detailed` },
+    })
   })
 
   it(`enables Anthropic reasoning through pi-ai when reasoningEffort is auto`, async () => {