fix(native-chat): the host writes chat failures for a person, with a typed fact beside them

mobile/src/session/mobile-structured-agent-session-rpc.ts

@@ -10,13 +10,15 @@ import type {
 import { structuredAgentSessionPayloadFingerprint } from '../../../src/shared/structured-agent-session-mutation'
 import {
   agentSessionRefusalNotice,
-  agentSessionRpcErrorFailure,
   agentSessionWriteFailureNotice,
-  agentSessionWriteKindForMethod,
   agentSessionWriteNoticeEnglish,
-  agentSessionWriteNoticeParts,
-  type AgentSessionWriteKind
+  agentSessionWriteNoticeParts
 } from '../../../src/shared/agent-session-refusal-notice'
+import {
+  agentSessionRpcErrorFailure,
+  agentSessionWriteKindForMethod,
+  type AgentSessionWriteKind
+} from '../../../src/shared/agent-session-write-failure'
 import { structuredSessionOperationId } from './structured-session-operation-id'
 import { isRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity'
 import type { RpcClient } from '../transport/rpc-client'

mobile/src/session/mobile-structured-operation-id-retirement.test.ts

@@ -161,6 +161,36 @@ describe('what a structured refusal says on the phone', () => {
     })
   })
 
+  it('says what the host named as the reason, in the same words as desktop', async () => {
+    const result = await requestStructuredAgentSessionMutation({
+      client: fakeClient(async () => ({
+        ok: true,
+        result: {
+          ok: false,
+          refusal: {
+            code: 'agent_session_operation_invalid',
+            message: 'This conversation has been cleared. Use the current conversation.',
+            details: { reason: 'conversationCleared' }
+          }
+        },
+        _meta: { runtimeId: 'runtime-1' }
+      })),
+      method: 'agentSession.send',
+      fingerprintMethod: 'agentSession.send',
+      sessionId: 'session-1',
+      expectedRuntimeFence: 1,
+      fields: { body: 'hello' },
+      clientOperationId: `1900000000000-${'e'.repeat(32)}`
+    })
+
+    expect(result).toEqual({
+      status: 'refused',
+      code: 'agent_session_operation_invalid',
+      message:
+        'This conversation has been cleared. Your message was not sent. Open the current conversation to continue.'
+    })
+  })
+
   const stop = {
     method: 'agentSession.cancel',
     fingerprintMethod: 'agentSession.cancel',

src/main/claude/claude-api-retry-idle-sweep.test.ts

@@ -0,0 +1,132 @@
+// A Claude that keeps retrying a refused request is working, so the idle sweep must not stop it.
+// Every retry frame's publish is the activity the sweep reads, even though a run writes one row.
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { AgentSessionRecordStore } from '../runtime/agent-session-record-store'
+import type { StructuredAgentSessionAdapter } from '../native-chat/agent-session-wire/structured-agent-session-adapter'
+import type { StructuredAgentSessionEventSink } from '../native-chat/agent-session-wire/structured-agent-session-event-sink'
+import { StructuredAgentSessionHost } from '../native-chat/agent-session-wire/structured-agent-session-host'
+import { STRUCTURED_AGENT_SESSION_IDLE_MS } from '../native-chat/agent-session-wire/structured-agent-session-idle-sweep'
+import {
+  HOST_TEST_NOW as NOW,
+  HOST_TEST_SESSION as SESSION,
+  HOST_TEST_THREAD as THREAD,
+  hostTestAttachParams,
+  resetHostTestOperationIds
+} from '../native-chat/agent-session-wire/structured-agent-session-host-test-data'
+import { createClaudeJournalTranslator } from './claude-structured-journal-translation'
+
+const SWEEP_MS = 5
+const RETRY_GAP_MS = 10 * 60_000
+
+let root: string
+let host: StructuredAgentSessionHost
+let sink: StructuredAgentSessionEventSink | null
+let closeSession: Mock<NonNullable<StructuredAgentSessionAdapter['closeSession']>>
+let clock: number
+
+function apiRetry(attempt: number): Record<string, unknown> {
+  return {
+    type: 'system',
+    subtype: 'api_retry',
+    attempt,
+    max_retries: 10,
+    retry_delay_ms: 600_000,
+    error_status: 429,
+    error: 'rate_limit',
+    session_id: 'provider-1',
+    uuid: `9b2f6a1e-0c4d-4e7a-8f3b-00000000000${attempt}`
+  }
+}
+
+/** Long enough for many sweep ticks, so "still open" means the sweep declined. */
+function waitOutSeveralSweeps(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, SWEEP_MS * 20))
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'orca-claude-retry-sweep-'))
+  resetHostTestOperationIds()
+  sink = null
+  clock = NOW
+  closeSession = vi.fn(async () => true)
+  const store = await AgentSessionRecordStore.open({
+    directory: join(root, 'store'),
+    hostId: 'local'
+  })
+  const adapter: StructuredAgentSessionAdapter = {
+    acquire: async ({ fence, spawnToken, events }) => {
+      sink = events ?? null
+      return {
+        process: { hostId: 'local', pid: 4242, processStartTimeMs: NOW - 1_000, spawnToken },
+        acquisitionGeneration: 'generation-1',
+        link: {
+          linkId: `link-${fence}`,
+          handle: { provider: 'codex', threadId: THREAD },
+          origin: 'created',
+          mintedAtFence: fence,
+          observedAt: NOW
+        }
+      }
+    },
+    closeSession,
+    releaseAcquisition: async () => true,
+    dispatch: async () => ({ state: 'admitted' }),
+    cancelTurn: async () => ({ cancelled: false }),
+    answerPrompt: async () => undefined,
+    setOption: async () => undefined
+  }
+  host = new StructuredAgentSessionHost({
+    store,
+    adapter,
+    journalRoot: root,
+    claimKeyId: 'key-1',
+    mintSpawnToken: () => 'spawn-1',
+    idleSweep: { intervalMs: SWEEP_MS, idleMs: STRUCTURED_AGENT_SESSION_IDLE_MS },
+    now: () => clock
+  })
+})
+
+afterEach(async () => {
+  await host.flushAllStreamedEvents()
+  await rm(root, { recursive: true, force: true })
+})
+
+describe('a Claude retrying a refused request', () => {
+  it('keeps the conversation open past the idle window while retry frames arrive', async () => {
+    expect(await host.attach({ callerKey: 'client-1' }, hostTestAttachParams(null))).toMatchObject({
+      ok: true
+    })
+    if (!sink) {
+      throw new Error('the host never handed the provider its event sink')
+    }
+    const translator = createClaudeJournalTranslator({ sink, fallbackIdPrefix: '1' })
+
+    // Five frames ten minutes apart: fifty minutes, well past the thirty-minute idle window.
+    for (let attempt = 1; attempt <= 5; attempt += 1) {
+      clock += RETRY_GAP_MS
+      translator.handle({ type: 'message', sessionId: SESSION, message: apiRetry(attempt) })
+      await waitOutSeveralSweeps()
+      expect(closeSession).not.toHaveBeenCalled()
+      expect(host.hasSession(SESSION)).toBe(true)
+    }
+
+    const items = host['sessions'].get(SESSION)?.journal.snapshot().items ?? []
+    const retryRows = items.filter(
+      (item) => item.body.kind === 'status' && item.body.failure?.kind === 'providerRetrying'
+    )
+    expect(retryRows).toHaveLength(1)
+    expect(retryRows[0]?.body).toMatchObject({
+      failure: { detail: { text: expect.stringContaining('"attempt":5') } }
+    })
+
+    // Once the frames stop, the same clock does let the sweep close it.
+    clock += STRUCTURED_AGENT_SESSION_IDLE_MS
+    await vi.waitFor(() => {
+      expect(closeSession).toHaveBeenCalledWith(SESSION)
+      expect(host.hasSession(SESSION)).toBe(false)
+    })
+  })
+})

src/main/claude/claude-api-retry-row.test.ts

@@ -0,0 +1,133 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type {
+  AgentJournalItemBody,
+  AgentSessionJournalIdentity
+} from '../../shared/agent-session-journal-types'
+import { MAX_PROVIDER_DIAGNOSTIC_CHARS } from '../../shared/agent-session-failure'
+import { openAgentSessionJournal } from '../native-chat/agent-session-journal/journal-store-factory'
+import { createDeferredStructuredAgentSessionEventSink } from '../native-chat/agent-session-wire/structured-agent-session-event-sink'
+import { unhandledProviderFrameJournalItem } from '../native-chat/agent-session-wire/unhandled-provider-frame'
+import { createClaudeJournalTranslator } from './claude-structured-journal-translation'
+
+const IDENTITY: AgentSessionJournalIdentity = {
+  sessionId: 'session-1',
+  workspaceId: 'workspace-1',
+  hostId: 'host-1',
+  agent: 'claude',
+  providerHandle: { kind: 'claude', sessionId: 'provider-1', leafUuid: 'leaf-1' }
+}
+
+/** A frame as Claude Code sends it while it retries a refused request. */
+function apiRetry(attempt: number, fields: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    type: 'system',
+    subtype: 'api_retry',
+    attempt,
+    max_retries: 10,
+    retry_delay_ms: 622,
+    error_status: 429,
+    error: 'rate_limit',
+    session_id: 'provider-1',
+    uuid: `9b2f6a1e-0c4d-4e7a-8f3b-00000000000${attempt}`,
+    ...fields
+  }
+}
+
+let root = ''
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'orca-claude-api-retry-'))
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+async function statusRowsFor(frames: Record<string, unknown>[]) {
+  const journal = await openAgentSessionJournal({
+    identity: IDENTITY,
+    journalDir: root,
+    now: () => 1_700_000_000_000,
+    mintEpoch: () => 'epoch-1'
+  })
+  const deferred = createDeferredStructuredAgentSessionEventSink()
+  deferred.bind({ journal, fence: 1, publish: vi.fn() })
+  const translator = createClaudeJournalTranslator({ sink: deferred.sink, fallbackIdPrefix: '1' })
+  for (const frame of frames) {
+    translator.handle({ type: 'message', sessionId: 'orca-session', message: frame })
+    await deferred.drained()
+  }
+  return journal
+    .snapshot()
+    .items.flatMap((item): Extract<AgentJournalItemBody, { kind: 'status' }>[] =>
+      item.body.kind === 'status' ? [item.body] : []
+    )
+}
+
+describe('a Claude api_retry frame', () => {
+  it('writes one sentence row per retry run, revised by each attempt, not the frame', async () => {
+    const rows = await statusRowsFor([apiRetry(1), apiRetry(2), apiRetry(3)])
+
+    expect(rows).toHaveLength(1)
+    const [row] = rows
+    expect(row).toMatchObject({
+      text: 'Claude is rate-limited and retrying.',
+      tone: 'warning',
+      failure: {
+        kind: 'providerRetrying',
+        retry: { error: 'rate_limit', status: 429 },
+        detail: { audience: 'log' }
+      }
+    })
+    expect(row).not.toHaveProperty('providerFrame')
+    // The latest attempt's frame, as the log detail.
+    expect(row.failure?.detail?.text).toContain('"attempt":3')
+  })
+
+  it('starts a new row when a later run starts over', async () => {
+    const rows = await statusRowsFor([apiRetry(1), apiRetry(2), apiRetry(1)])
+    expect(rows.map((row) => row.text)).toEqual([
+      'Claude is rate-limited and retrying.',
+      'Claude is rate-limited and retrying.'
+    ])
+  })
+
+  it('does not call a retry a rate limit unless the frame says so', async () => {
+    const rows = await statusRowsFor([
+      apiRetry(1, { error: 'overloaded', error_status: 529 }),
+      apiRetry(1, { error: 'server_error', error_status: 500 }),
+      apiRetry(1, { error: undefined, error_status: undefined }),
+      apiRetry(1, { error: 'something_new', error_status: 429 })
+    ])
+    expect(rows.map((row) => row.text)).toEqual([
+      'Claude hit a temporary problem and is retrying.',
+      'Claude hit a temporary problem and is retrying.',
+      'Claude hit a temporary problem and is retrying.',
+      'Claude is rate-limited and retrying.'
+    ])
+    expect(rows[0]?.failure).toMatchObject({ retry: { error: 'overloaded', status: 529 } })
+  })
+
+  it('caps the frame it keeps as the detail', async () => {
+    const [row] = await statusRowsFor([apiRetry(1, { padding: 'x'.repeat(5_000) })])
+    expect(row?.failure?.detail?.text.length).toBe(MAX_PROVIDER_DIAGNOSTIC_CHARS)
+  })
+
+  it('leaves a frame kind no one catalogued to the provider fallback, as before', async () => {
+    const unknown = {
+      type: 'system',
+      subtype: 'future_notice',
+      error: 'rate_limit',
+      session_id: 'provider-1',
+      uuid: 'future-1'
+    }
+    const rows = await statusRowsFor([unknown])
+    expect(rows).toEqual([
+      unhandledProviderFrameJournalItem('claude', 'message:system:future_notice', unknown)?.body
+    ])
+    expect(rows[0]).toMatchObject({ text: 'rate_limit', tone: 'error' })
+  })
+})

src/main/claude/claude-api-retry-row.ts

@@ -0,0 +1,39 @@
+// The one row a Claude `system/api_retry` frame writes: a sentence and a `providerRetrying` fact,
+// revised in place for every attempt of the same retry run.
+
+import {
+  agentSessionFailureFact,
+  providerDiagnostic,
+  readProviderRetry
+} from '../../shared/agent-session-failure'
+import { agentSessionFailureWords } from '../../shared/agent-session-failure-words'
+import type { AgentJournalStatusItem } from '../../shared/agent-session-journal-types'
+import { TUI_AGENT_DISPLAY_NAMES } from '../../shared/tui-agent-display-names'
+
+export const CLAUDE_API_RETRY_FRAME_KIND = 'message:system:api_retry'
+
+export function claudeApiRetryRowBody(message: Record<string, unknown>): AgentJournalStatusItem {
+  const retry = readProviderRetry({ error: message.error, status: message.error_status })
+  const words = agentSessionFailureWords(
+    agentSessionFailureFact('providerRetrying', {
+      detail: providerDiagnostic(JSON.stringify(message), 'log'),
+      ...(retry ? { retry } : {})
+    }),
+    { surface: 'row', agentName: TUI_AGENT_DISPLAY_NAMES.claude }
+  )
+  return { kind: 'status', tone: 'warning', ...words }
+}
+
+/** Numbers retry runs: a frame whose attempt does not follow the last one starts a new run. */
+export function createClaudeApiRetryRuns(): (message: Record<string, unknown>) => number {
+  let run = 0
+  let lastAttempt: number | null = null
+  return (message) => {
+    const attempt = typeof message.attempt === 'number' ? message.attempt : null
+    if (attempt === null || lastAttempt === null || attempt <= lastAttempt) {
+      run += 1
+    }
+    lastAttempt = attempt
+    return run
+  }
+}

src/main/claude/claude-stream-json-connection.test.ts

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process'
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { providerDiagnosticOf } from '../../shared/agent-session-failure'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { spawnProcess, type SpawnedProcess } from '../../shared/child-process/run-process'
 import { hasLiveClaudePtys } from '../claude-accounts/live-pty-gate'
@@ -592,6 +593,11 @@ describe('Claude stream-json connection', () => {
     await until(() => exit, 'the exit error')
     // The status and stderr are the only diagnostic a refused start leaves behind.
     expect((exit as unknown as Error).message).toMatch(/exited \(code 1\): claude: not signed in/)
+    // Kept apart from Orca's wording where it is composed, and marked as log text.
+    expect(providerDiagnosticOf(exit)).toEqual({
+      text: expect.stringMatching(/^\(code 1\)\n.*claude: not signed in/s),
+      audience: 'log'
+    })
     expect(connection.closed).toBe(true)
     // Stderr-triggered capture can win or lose the race with this real child's exit.
     const closed = await connection.close()