@yolk-sdk/agent 0.1.0-canary.19 → 0.1.0-canary.21

package/src/providers/openai/codex-provider.ts

@@ -21,6 +21,7 @@ import {
   type AgentReasoningEffort,
   type Content,
   type ContentPart,
+  type ProviderFailureKind,
   type ToolDef
 } from '@yolk-sdk/agent/protocol'
 import {
@@ -36,6 +37,12 @@ import {
 } from '@yolk-sdk/agent/loop'
 import { openAiCodexAuthorizationHeaders, openAiCodexResponsesUrl } from './codex.ts'
 import type { OAuthAccessToken } from '@yolk-sdk/agent/oauth'
+import {
+  classifyProviderFailure,
+  providerErrorInfo,
+  providerFailureCause,
+  providerFailureRetryable
+} from '../provider-error.ts'
 
 export type OpenAiCodexReasoningSummary = 'auto' | 'concise' | 'detailed'
 
@@ -395,22 +402,50 @@ export const toOpenAiCodexRequestBody = (
     }
   })
 
-const responseStatusToCause = (status: number): LLMError['cause'] => {
-  if (status === 429) {
-    return 'rate_limit'
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+const stringField = (value: unknown, key: string) => {
+  if (!isRecord(value)) {
+    return undefined
   }
 
-  if (status === 413) {
-    return 'context_overflow'
+  const field = Object.getOwnPropertyDescriptor(value, key)?.value
+
+  return typeof field === 'string' ? field : undefined
+}
+
+const recordField = (value: unknown, key: string) => {
+  if (!isRecord(value)) {
+    return undefined
   }
 
-  return 'provider_error'
+  const field = Object.getOwnPropertyDescriptor(value, key)?.value
+
+  return isRecord(field) ? field : undefined
 }
 
-const isRetryableStatus = (status: number) => status === 429 || status >= 500
+const openAiCodexProvider = 'openai_codex'
+
+const providerSignalError = (input: {
+  readonly message: string
+  readonly providerCode?: string
+  readonly fallbackKind?: ProviderFailureKind
+}) => {
+  const provider = classifyProviderFailure({
+    provider: openAiCodexProvider,
+    message: input.message,
+    ...(input.providerCode === undefined ? {} : { providerCode: input.providerCode }),
+    ...(input.fallbackKind === undefined ? {} : { fallbackKind: input.fallbackKind })
+  })
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null
+  return new LLMError({
+    cause: providerFailureCause(provider.kind),
+    message: `OpenAI Codex stream error: ${input.message}`,
+    retryable: providerFailureRetryable(provider.kind),
+    provider
+  })
+}
 
 const parseToolArguments = (raw: string) =>
   decodeJsonString(raw, 'Invalid OpenAI Codex tool arguments JSON')
@@ -811,12 +846,26 @@ const processSseData = (
       }
     }
 
+    if (parsed.type === 'response.failed') {
+      const error = recordField(recordField(parsed, 'response'), 'error')
+      const message = stringField(error, 'message') ?? 'OpenAI Codex response failed'
+      const providerCode = stringField(error, 'code') ?? stringField(error, 'type')
+
+      return yield* Effect.fail(
+        providerSignalError({
+          message,
+          ...(providerCode === undefined ? {} : { providerCode })
+        })
+      )
+    }
+
     if (parsed.type === 'error' && typeof parsed.message === 'string') {
+      const providerCode = stringField(parsed, 'code') ?? stringField(parsed, 'type')
+
       return yield* Effect.fail(
-        new LLMError({
-          cause: 'provider_error',
-          message: `OpenAI Codex stream error: ${parsed.message}`,
-          retryable: false
+        providerSignalError({
+          message: parsed.message,
+          ...(providerCode === undefined ? {} : { providerCode })
         })
       )
     }
@@ -915,11 +964,16 @@ const finalizeBodyState = (
   })
 
 const toHttpClientLlmError =
-  (message: string, retryable: boolean) => (error: HttpClientError.HttpClientError) =>
+  (message: string, retryable: boolean, kind: ProviderFailureKind = 'network') =>
+  (error: HttpClientError.HttpClientError) =>
     new LLMError({
       cause: 'provider_error',
       message: `${message}: ${error.message}`,
-      retryable
+      retryable,
+      provider: providerErrorInfo({
+        provider: openAiCodexProvider,
+        kind: retryable ? kind : 'unknown'
+      })
     })
 
 export const streamOpenAiCodexResponse = (
@@ -929,7 +983,7 @@ export const streamOpenAiCodexResponse = (
     Ref.make(initialBodyState).pipe(
       Effect.map(bodyStateRef => {
         const chunks = response.stream.pipe(
-          Stream.mapError(toHttpClientLlmError('Could not read OpenAI Codex stream', false)),
+          Stream.mapError(toHttpClientLlmError('Could not read OpenAI Codex stream', true, 'stream')),
           Stream.decodeText,
           Stream.mapEffect(chunk =>
             Effect.gen(function* () {
@@ -987,11 +1041,19 @@ const sendOpenAiCodexRequest = (
         )
       )
 
+      const provider = classifyProviderFailure({
+        provider: openAiCodexProvider,
+        status: response.status,
+        headers: response.headers,
+        body: errorText
+      })
+
       return yield* Effect.fail(
         new LLMError({
-          cause: responseStatusToCause(response.status),
-          message: `OpenAI Codex returned ${response.status}: ${errorText}`,
-          retryable: isRetryableStatus(response.status)
+          cause: providerFailureCause(provider.kind),
+          message: `OpenAI Codex returned ${response.status}`,
+          retryable: providerFailureRetryable(provider.kind),
+          provider
         })
       )
     }

package/src/providers/openai/provider.ts

@@ -13,8 +13,10 @@ import {
   AgentOutputUsage,
   AgentUsage,
   attachmentSourceDataUrl,
+  attachmentSourceText,
   assistantContent,
   assistantHostToolCalls,
+  isTextDocumentMimeType,
   messageContextText,
   prependMessageContextToContent,
   type AgentMessage,
@@ -32,6 +34,12 @@ import {
   type LLMEvent,
   type LLMRequest
 } from '@yolk-sdk/agent/loop'
+import {
+  classifyProviderFailure,
+  providerErrorInfo,
+  providerFailureCause,
+  providerFailureRetryable
+} from '../provider-error.ts'
 
 export type OpenAiProviderConfig = {
   readonly chatCompletionsUrl?: string
@@ -195,6 +203,24 @@ const unsupportedContentError = (contentType: string) =>
     retryable: false
   })
 
+const textDocumentToOpenAiPart = (part: Extract<ContentPart, { readonly _tag: 'Document' }>) =>
+  attachmentSourceText(part.source).pipe(
+    Effect.mapError(() => unsupportedContentError('Invalid document text')),
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.fail(unsupportedContentError('Unresolved document source')),
+        onSome: text => {
+          const block: OpenAiTextContentPart = {
+            type: 'text',
+            text: `Document: ${part.title ?? part.filename}\n\n${text}`
+          }
+
+          return Effect.succeed(block)
+        }
+      })
+    )
+  )
+
 const contentPartToUserPart = (
   part: ContentPart
 ): Effect.Effect<OpenAiTextContentPart | OpenAiImageContentPart, LLMError> => {
@@ -207,7 +233,9 @@ const contentPartToUserPart = (
         onSome: url => Effect.succeed({ type: 'image_url', image_url: { url } })
       })
     case 'Document':
-      return Effect.fail(unsupportedContentError('Document'))
+      return isTextDocumentMimeType(part.mimeType)
+        ? textDocumentToOpenAiPart(part)
+        : Effect.fail(unsupportedContentError('Document'))
     case 'Audio':
       return Effect.fail(unsupportedContentError('Audio'))
   }
@@ -333,20 +361,6 @@ export const toOpenAiRequestBody = (
     }
   })
 
-const responseStatusToCause = (status: number): LLMError['cause'] => {
-  if (status === 429) {
-    return 'rate_limit'
-  }
-
-  if (status === 413) {
-    return 'context_overflow'
-  }
-
-  return 'provider_error'
-}
-
-const isRetryableStatus = (status: number) => status === 429 || status >= 500
-
 const parseToolArguments = (raw: string) =>
   decodeJsonString(raw, 'Invalid OpenAI tool arguments JSON')
 
@@ -396,7 +410,11 @@ const toHttpClientLlmError =
     new LLMError({
       cause: 'provider_error',
       message: `${message}: ${error.message}`,
-      retryable
+      retryable,
+      provider: providerErrorInfo({
+        provider: 'openai',
+        kind: retryable ? 'network' : 'unknown'
+      })
     })
 
 const parseOpenAiResponseJson = (
@@ -447,11 +465,19 @@ const sendOpenAiRequest = (
         )
       )
 
+      const provider = classifyProviderFailure({
+        provider: 'openai',
+        status: response.status,
+        headers: response.headers,
+        body: errorText
+      })
+
       return yield* Effect.fail(
         new LLMError({
-          cause: responseStatusToCause(response.status),
-          message: `OpenAI returned ${response.status}: ${errorText}`,
-          retryable: isRetryableStatus(response.status)
+          cause: providerFailureCause(provider.kind),
+          message: `OpenAI returned ${response.status}`,
+          retryable: providerFailureRetryable(provider.kind),
+          provider
         })
       )
     }

package/src/providers/provider-error.ts

@@ -0,0 +1,213 @@
+import {
+  ProviderErrorInfo,
+  type AgentErrorCode,
+  type ProviderFailureKind
+} from '@yolk-sdk/agent/protocol'
+
+type HeaderMap = Readonly<Record<string, string>>
+
+type ProviderFailureInput = {
+  readonly provider: string
+  readonly status?: number
+  readonly headers?: HeaderMap
+  readonly body?: string
+  readonly message?: string
+  readonly providerCode?: string
+  readonly fallbackKind?: ProviderFailureKind
+}
+
+type ProviderErrorInfoInput = {
+  readonly provider: string
+  readonly kind: ProviderFailureKind
+  readonly status?: number
+  readonly providerCode?: string
+  readonly retryAfterMs?: number
+}
+
+export type ProviderLlmErrorCause = Extract<
+  AgentErrorCode,
+  'provider_error' | 'rate_limit' | 'overloaded' | 'context_overflow' | 'invalid_response'
+>
+
+const numericDelayMs = (value: number) =>
+  Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined
+
+const headerValue = (headers: HeaderMap, name: string) => {
+  const lowerName = name.toLowerCase()
+
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lowerName) {
+      return value
+    }
+  }
+
+  return undefined
+}
+
+export const parseRetryAfterMs = (value: string | undefined) => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  return numericDelayMs(Number(value.trim()))
+}
+
+export const parseRetryAfter = (value: string | undefined) => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  const trimmed = value.trim()
+  const seconds = Number(trimmed)
+  const secondsDelay = numericDelayMs(seconds * 1000)
+
+  if (secondsDelay !== undefined) {
+    return secondsDelay
+  }
+
+  const timestamp = Date.parse(trimmed)
+
+  if (Number.isNaN(timestamp)) {
+    return undefined
+  }
+
+  return numericDelayMs(timestamp - Date.now())
+}
+
+export const retryAfterMsFromHeaders = (headers: HeaderMap | undefined) => {
+  if (headers === undefined) {
+    return undefined
+  }
+
+  return parseRetryAfterMs(headerValue(headers, 'retry-after-ms')) ??
+    parseRetryAfter(headerValue(headers, 'retry-after'))
+}
+
+const kindFromStatus = (status: number | undefined): ProviderFailureKind | undefined => {
+  if (status === undefined) {
+    return undefined
+  }
+
+  if (status === 429) {
+    return 'rate_limit'
+  }
+
+  if (status === 529) {
+    return 'overloaded'
+  }
+
+  if (status === 413) {
+    return 'context_overflow'
+  }
+
+  if (status === 401 || status === 403) {
+    return 'auth'
+  }
+
+  if (status >= 500) {
+    return 'server_error'
+  }
+
+  return undefined
+}
+
+const normalizedSignal = (input: ProviderFailureInput) =>
+  [input.providerCode, input.message, input.body]
+    .filter(value => value !== undefined)
+    .join(' ')
+    .toLowerCase()
+
+const kindFromSignal = (input: ProviderFailureInput): ProviderFailureKind | undefined => {
+  const signal = normalizedSignal(input)
+
+  if (
+    signal.includes('rate_limit') ||
+    signal.includes('rate limit') ||
+    signal.includes('too_many_requests') ||
+    signal.includes('too many request')
+  ) {
+    return 'rate_limit'
+  }
+
+  if (
+    signal.includes('overloaded_error') ||
+    signal.includes('overloaded') ||
+    signal.includes('overload') ||
+    signal.includes('service unavailable')
+  ) {
+    return 'overloaded'
+  }
+
+  if (
+    signal.includes('context_length') ||
+    signal.includes('context length') ||
+    signal.includes('context_overflow') ||
+    signal.includes('context overflow')
+  ) {
+    return 'context_overflow'
+  }
+
+  return undefined
+}
+
+export const providerFailureKind = (input: ProviderFailureInput): ProviderFailureKind =>
+  kindFromSignal(input) ??
+  kindFromStatus(input.status) ??
+  input.fallbackKind ??
+  'unknown'
+
+export const providerFailureRetryable = (kind: ProviderFailureKind) => {
+  switch (kind) {
+    case 'rate_limit':
+    case 'overloaded':
+    case 'server_error':
+    case 'network':
+    case 'stream':
+      return true
+    case 'auth':
+    case 'context_overflow':
+    case 'invalid_response':
+    case 'unknown':
+      return false
+  }
+}
+
+export const providerFailureCause = (kind: ProviderFailureKind): ProviderLlmErrorCause => {
+  switch (kind) {
+    case 'rate_limit':
+      return 'rate_limit'
+    case 'overloaded':
+      return 'overloaded'
+    case 'context_overflow':
+      return 'context_overflow'
+    case 'invalid_response':
+      return 'invalid_response'
+    case 'auth':
+    case 'network':
+    case 'server_error':
+    case 'stream':
+    case 'unknown':
+      return 'provider_error'
+  }
+}
+
+export const providerErrorInfo = (input: ProviderErrorInfoInput) =>
+  ProviderErrorInfo.make({
+    provider: input.provider,
+    kind: input.kind,
+    ...(input.status === undefined ? {} : { status: input.status }),
+    ...(input.providerCode === undefined ? {} : { providerCode: input.providerCode }),
+    ...(input.retryAfterMs === undefined ? {} : { retryAfterMs: input.retryAfterMs })
+  })
+
+export const classifyProviderFailure = (input: ProviderFailureInput) => {
+  const kind = providerFailureKind(input)
+
+  return providerErrorInfo({
+    provider: input.provider,
+    kind,
+    ...(input.status === undefined ? {} : { status: input.status }),
+    ...(input.providerCode === undefined ? {} : { providerCode: input.providerCode }),
+    ...(input.headers === undefined ? {} : { retryAfterMs: retryAfterMsFromHeaders(input.headers) })
+  })
+}

package/src/react/chat-core.ts

@@ -1,7 +1,9 @@
 import {
   hitlResponseEvent,
+  type AgentError,
   type AgentEvent,
   type AgentMessage,
+  type AgentRetry,
   type Content,
   type HitlResponse,
   type UserMessage
@@ -31,6 +33,8 @@ export type AgentRunStatus = 'idle' | 'running' | 'waiting' | 'done' | 'error' |
 export type AgentChatState = {
   readonly status: AgentRunStatus
   readonly error: string | null
+  readonly errorInfo: AgentError | null
+  readonly retryInfo: AgentRetry | null
   readonly chatMessages: ReadonlyArray<AgentChatMessage>
   readonly sessionEvents: ReadonlyArray<AgentChatSessionEvent>
   readonly seenEventIds: ReadonlyArray<string>
@@ -39,6 +43,8 @@ export type AgentChatState = {
 export const initialAgentChatState: AgentChatState = {
   status: 'idle',
   error: null,
+  errorInfo: null,
+  retryInfo: null,
   chatMessages: [],
   sessionEvents: [],
   seenEventIds: []
@@ -52,6 +58,9 @@ const rememberEvent = (state: AgentChatState, event: AgentEvent): AgentChatState
     ? state
     : { ...state, seenEventIds: [...state.seenEventIds, event.eventId] }
 
+const clearRetryInfo = (state: AgentChatState): AgentChatState =>
+  state.retryInfo === null ? state : { ...state, retryInfo: null }
+
 export type AgentChatAction =
   | { readonly _tag: 'HydrateMessage'; readonly message: AgentMessage }
   | { readonly _tag: 'Submit'; readonly message: UserMessage }
@@ -73,13 +82,17 @@ export const reduceAgentChatState = (
       return {
         ...state,
         chatMessages: appendProtocolMessage(state.chatMessages, action.message),
-        error: null
+        error: null,
+        errorInfo: null,
+        retryInfo: null
       }
     case 'Submit':
       return {
         ...state,
         status: 'running',
         error: null,
+        errorInfo: null,
+        retryInfo: null,
         seenEventIds: [],
         chatMessages: appendProtocolMessage(state.chatMessages, action.message),
         sessionEvents: [
@@ -92,6 +105,8 @@ export const reduceAgentChatState = (
         ...state,
         chatMessages: appendProtocolMessage(state.chatMessages, action.message),
         error: null,
+        errorInfo: null,
+        retryInfo: null,
         sessionEvents: [
           ...state.sessionEvents,
           ProtocolMessageAppended.make({ message: action.message })
@@ -102,6 +117,8 @@ export const reduceAgentChatState = (
         ...state,
         status: 'running',
         error: null,
+        errorInfo: null,
+        retryInfo: null,
         seenEventIds: [],
         chatMessages: applyAgentEventToChatMessages(
           state.chatMessages,
@@ -118,6 +135,8 @@ export const reduceAgentChatState = (
       return {
         ...state,
         error: null,
+        errorInfo: null,
+        retryInfo: null,
         chatMessages: next.messages,
         sessionEvents: [
           ...state.sessionEvents,
@@ -139,6 +158,8 @@ export const reduceAgentChatState = (
         ...state,
         status: 'running',
         error: null,
+        errorInfo: null,
+        retryInfo: null,
         seenEventIds: [],
         chatMessages: next.messages,
         sessionEvents: [
@@ -161,6 +182,8 @@ export const reduceAgentChatState = (
         ...state,
         status: 'running',
         error: null,
+        errorInfo: null,
+        retryInfo: null,
         seenEventIds: [],
         chatMessages: next.messages,
         sessionEvents: [
@@ -185,6 +208,8 @@ export const reduceAgentChatState = (
               ...state,
               status: 'running',
               error: null,
+              errorInfo: null,
+              retryInfo: null,
               chatMessages: applyAgentEventToChatMessages(state.chatMessages, action.event, action)
             },
             action.event
@@ -195,6 +220,8 @@ export const reduceAgentChatState = (
               ...state,
               status: 'error',
               error: action.event.message,
+              errorInfo: action.event,
+              retryInfo: null,
               chatMessages: applyAgentEventToChatMessages(state.chatMessages, action.event, action)
             },
             action.event
@@ -205,6 +232,8 @@ export const reduceAgentChatState = (
               ...state,
               status: 'done',
               error: null,
+              errorInfo: null,
+              retryInfo: null,
               chatMessages: applyAgentEventToChatMessages(state.chatMessages, action.event, action)
             },
             action.event
@@ -215,13 +244,23 @@ export const reduceAgentChatState = (
               ...state,
               status: 'waiting',
               error: null,
+              errorInfo: null,
+              retryInfo: null,
               chatMessages: applyAgentEventToChatMessages(state.chatMessages, action.event, action)
             },
             action.event
           )
-        case 'AssistantMessage':
         case 'AgentRetry':
+          return rememberEvent(
+            {
+              ...state,
+              retryInfo: action.event,
+              chatMessages: applyAgentEventToChatMessages(state.chatMessages, action.event, action)
+            },
+            action.event
+          )
         case 'CompactionEnd':
+        case 'AssistantMessage':
         case 'CompactionStart':
         case 'LLMReasoningDelta':
         case 'LLMStreamEnd':
@@ -246,10 +285,10 @@ export const reduceAgentChatState = (
         case 'TurnStart':
         case 'UsageUpdate':
           return rememberEvent(
-            {
+            clearRetryInfo({
               ...state,
               chatMessages: applyAgentEventToChatMessages(state.chatMessages, action.event, action)
-            },
+            }),
             action.event
           )
       }
@@ -259,11 +298,13 @@ export const reduceAgentChatState = (
         ...state,
         status: 'error',
         error: action.message,
+        errorInfo: null,
+        retryInfo: null,
         chatMessages: markChatError(state.chatMessages, action.message)
       }
     }
     case 'Abort':
-      return { ...state, status: 'aborted', error: null }
+      return { ...state, status: 'aborted', error: null, errorInfo: null, retryInfo: null }
   }
 }