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

package/src/client/state.ts

@@ -1,6 +1,8 @@
 import {
+  type AgentError,
   type AgentEvent,
   type AgentMessage,
+  type AgentRetry,
   type HitlRequest,
   type QuestionRequest,
   type QuestionResponse,
@@ -63,6 +65,8 @@ export type AgentClientState = {
   readonly reasoning: string
   readonly toolRuns: ReadonlyArray<AgentToolRun>
   readonly error: string | null
+  readonly errorInfo: AgentError | null
+  readonly retryInfo: AgentRetry | null
   readonly seenEventIds: ReadonlyArray<string>
 }
 
@@ -80,9 +84,14 @@ export const initialAgentClientState: AgentClientState = {
   reasoning: '',
   toolRuns: [],
   error: null,
+  errorInfo: null,
+  retryInfo: null,
   seenEventIds: []
 }
 
+const clearRetryInfo = (state: AgentClientState): AgentClientState =>
+  state.retryInfo === null ? state : { ...state, retryInfo: null }
+
 const hasSeenEvent = (state: AgentClientState, event: AgentEvent) =>
   event.eventId !== undefined && state.seenEventIds.includes(event.eventId)
 
@@ -260,16 +269,18 @@ const applyAgentEventUnchecked = (
         reasoning: '',
         liveMessages: [],
         toolRuns: completedToolRuns(state.toolRuns),
-        error: null
+        error: null,
+        errorInfo: null,
+        retryInfo: null
       }
     case 'AgentError':
-      return markAgentError(state, event.message)
+      return markAgentError(state, event.message, event)
     case 'LLMTextDelta':
-      return { ...state, text: `${state.text}${event.text}` }
+      return clearRetryInfo({ ...state, text: `${state.text}${event.text}` })
     case 'LLMReasoningDelta':
-      return { ...state, reasoning: `${state.reasoning}${event.text}` }
+      return clearRetryInfo({ ...state, reasoning: `${state.reasoning}${event.text}` })
     case 'ToolInputStart':
-      return {
+      return clearRetryInfo({
         ...state,
         toolRuns: replaceToolRun(state.toolRuns, {
           _tag: 'InputStreaming',
@@ -277,14 +288,17 @@ const applyAgentEventUnchecked = (
           name: event.name,
           input: ''
         })
-      }
+      })
     case 'ToolInputDelta':
-      return { ...state, toolRuns: appendToolInputDelta(state.toolRuns, event.id, event.delta) }
+      return clearRetryInfo({
+        ...state,
+        toolRuns: appendToolInputDelta(state.toolRuns, event.id, event.delta)
+      })
     case 'ToolInputEnd':
-      return {
+      return clearRetryInfo({
         ...state,
         toolRuns: replaceToolRun(state.toolRuns, { _tag: 'InputReady', call: event.call })
-      }
+      })
     case 'ToolApprovalRequested':
       return {
         ...state,
@@ -370,21 +384,21 @@ const applyAgentEventUnchecked = (
         })
       }
     case 'ProviderToolResult':
-      return {
+      return clearRetryInfo({
         ...state,
         toolRuns: replaceToolRun(state.toolRuns, {
           _tag: 'ProviderCompleted',
           call: event.call,
           result: event.result
         })
-      }
+      })
     case 'AssistantMessage':
-      return {
+      return clearRetryInfo({
         ...state,
         liveMessages: [...state.liveMessages, event.message],
         text: '',
         reasoning: ''
-      }
+      })
     case 'AgentEnd':
       return {
         ...state,
@@ -393,7 +407,8 @@ const applyAgentEventUnchecked = (
         liveMessages: [],
         text: '',
         reasoning: '',
-        toolRuns: completedToolRuns(state.toolRuns)
+        toolRuns: completedToolRuns(state.toolRuns),
+        retryInfo: null
       }
     case 'AgentAwaitingInput':
       return {
@@ -403,9 +418,12 @@ const applyAgentEventUnchecked = (
         liveMessages: [],
         text: '',
         reasoning: '',
-        error: null
+        error: null,
+        errorInfo: null,
+        retryInfo: null
       }
     case 'AgentRetry':
+      return { ...state, retryInfo: event }
     case 'CompactionEnd':
     case 'CompactionStart':
     case 'LLMStreamEnd':
@@ -431,24 +449,31 @@ export const submitAgentUserMessage = (
   reasoning: '',
   toolRuns: completedToolRuns(state.toolRuns),
   error: null,
+  errorInfo: null,
+  retryInfo: null,
   seenEventIds: []
 })
 
 export const markAgentError = (
   state: AgentClientState,
-  message = 'Agent request failed'
+  message = 'Agent request failed',
+  errorInfo: AgentError | null = null
 ): AgentClientState => ({
   ...state,
   status: 'error',
   toolRuns: completedToolRuns(state.toolRuns),
-  error: message
+  error: message,
+  errorInfo,
+  retryInfo: null
 })
 
 export const markAgentAborted = (state: AgentClientState): AgentClientState => ({
   ...state,
   status: 'aborted',
   toolRuns: completedToolRuns(state.toolRuns),
-  error: null
+  error: null,
+  errorInfo: null,
+  retryInfo: null
 })
 
 export const reduceAgentEvents = (

package/src/loop/error.ts

@@ -1,16 +1,18 @@
 import * as Schema from 'effect/Schema'
-import { AgentError, type AgentErrorCode } from '@yolk-sdk/agent/protocol'
+import { AgentError, ProviderErrorInfo, type AgentErrorCode } from '@yolk-sdk/agent/protocol'
 
 export class LLMError extends Schema.TaggedErrorClass<LLMError>()('LLMError', {
   cause: Schema.Literals([
     'validation_error',
     'provider_error',
     'rate_limit',
+    'overloaded',
     'context_overflow',
     'invalid_response'
   ]),
   message: Schema.String,
-  retryable: Schema.Boolean
+  retryable: Schema.Boolean,
+  provider: Schema.optional(ProviderErrorInfo)
 }) {}
 
 export class FauxExhaustedError extends Schema.TaggedErrorClass<FauxExhaustedError>()(
@@ -75,7 +77,8 @@ export const agentLoopErrorToAgentError = (error: AgentLoopError): AgentError =>
       return AgentError.make({
         code: error.cause,
         message: error.message,
-        retryable: error.retryable
+        retryable: error.retryable,
+        ...(error.provider === undefined ? {} : { provider: error.provider })
       })
     case 'ToolError':
       return AgentError.make({

package/src/loop/run.ts

@@ -292,8 +292,30 @@ type TurnStreamInput = {
   readonly turn: number
 }
 
-const retryDelayMs = (baseDelayMs: number, attempt: number) =>
-  Math.max(0, Math.floor(baseDelayMs * 2 ** Math.max(0, attempt - 1)))
+const maxUnhintedRetryDelayMs = 30_000
+const maxHintedRetryDelayMs = 2_147_483_647
+
+const validDelayMs = (delayMs: number) =>
+  Number.isFinite(delayMs) && delayMs >= 0 ? Math.floor(delayMs) : undefined
+
+const hintedRetryDelayMs = (error: LLMError) => {
+  const delayMs = error.provider?.retryAfterMs
+  const validDelay = delayMs === undefined ? undefined : validDelayMs(delayMs)
+
+  return validDelay === undefined ? undefined : Math.min(validDelay, maxHintedRetryDelayMs)
+}
+
+const retryDelayMs = (baseDelayMs: number, attempt: number, error: LLMError) => {
+  const hintedDelay = hintedRetryDelayMs(error)
+
+  if (hintedDelay !== undefined) {
+    return hintedDelay
+  }
+
+  const delayMs = validDelayMs(baseDelayMs * 2 ** Math.max(0, attempt - 1)) ?? 0
+
+  return Math.min(delayMs, maxUnhintedRetryDelayMs)
+}
 
 const retryReason = (error: LLMError): AgentErrorCode => error.cause
 
@@ -332,13 +354,14 @@ const withProviderRetries = (
                       return failAgentLoopError(error)
                     }
 
-                    const delayMs = retryDelayMs(loopConfig.retryBaseDelayMs, attempt)
+                    const delayMs = retryDelayMs(loopConfig.retryBaseDelayMs, attempt, error)
                     return Stream.make(
                       AgentRetry.make({
                         attempt,
                         reason: retryReason(error),
                         delayMs,
-                        message: error.message
+                        message: error.message,
+                        ...(error.provider === undefined ? {} : { provider: error.provider })
                       })
                     ).pipe(
                       Stream.concat(sleepStream(delayMs)),

package/src/loop/services/loop-config.ts

@@ -14,7 +14,7 @@ export class LoopConfig extends Context.Service<LoopConfig, LoopConfigShape>()(
   static defaultLayer = this.layer({
     maxTurns: 500,
     maxRetries: 2,
-    retryBaseDelayMs: 1000,
+    retryBaseDelayMs: 2000,
     toolConcurrency: 4
   })
 }

package/src/protocol/content.ts

@@ -201,6 +201,135 @@ export const attachmentSourceDataUrl = (source: AttachmentSource, mimeType: stri
   }
 }
 
+const normalizeMimeType = (mimeType: string) => mimeType.split(';', 1)[0]?.trim().toLowerCase() ?? ''
+
+const textDocumentMimeTypeByExtension: Readonly<Record<string, string>> = {
+  '.csv': 'text/csv',
+  '.css': 'text/css',
+  '.gql': 'application/graphql',
+  '.graphql': 'application/graphql',
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.jsx': 'application/javascript',
+  '.json': 'application/json',
+  '.jsonl': 'application/x-ndjson',
+  '.md': 'text/markdown',
+  '.markdown': 'text/markdown',
+  '.sql': 'application/sql',
+  '.toml': 'application/toml',
+  '.ts': 'application/typescript',
+  '.tsx': 'application/typescript',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml',
+  '.yaml': 'application/yaml',
+  '.yml': 'application/yaml'
+}
+
+const isUnknownDocumentMimeType = (mimeType: string) =>
+  mimeType.length === 0 || mimeType === 'application/octet-stream' || mimeType === 'binary/octet-stream'
+
+export const isTextDocumentMimeType = (mimeType: string) => {
+  const normalized = normalizeMimeType(mimeType)
+
+  return (
+    normalized.startsWith('text/') ||
+    normalized === 'application/json' ||
+    normalized === 'application/ld+json' ||
+    normalized === 'application/jsonl' ||
+    normalized === 'application/x-ndjson' ||
+    normalized === 'application/javascript' ||
+    normalized === 'application/x-javascript' ||
+    normalized === 'application/typescript' ||
+    normalized === 'application/x-typescript' ||
+    normalized === 'application/xml' ||
+    normalized === 'application/yaml' ||
+    normalized === 'application/x-yaml' ||
+    normalized === 'application/toml' ||
+    normalized === 'application/markdown' ||
+    normalized === 'application/sql' ||
+    normalized === 'application/graphql' ||
+    normalized.endsWith('+json') ||
+    normalized.endsWith('+xml')
+  )
+}
+
+export const textDocumentMimeTypeFromFilename = (filename: string) => {
+  const normalized = filename.trim().toLowerCase()
+  const entry = Object.entries(textDocumentMimeTypeByExtension).find(([extension]) =>
+    normalized.endsWith(extension)
+  )
+
+  return entry?.[1]
+}
+
+export const inferTextDocumentMimeType = (input: {
+  readonly filename: string
+  readonly mimeType: string
+}) => {
+  const normalized = normalizeMimeType(input.mimeType)
+
+  if (isTextDocumentMimeType(normalized)) return normalized
+  if (!isUnknownDocumentMimeType(normalized)) return undefined
+
+  return textDocumentMimeTypeFromFilename(input.filename)
+}
+
+export const textToBase64Utf8 = (text: string) => {
+  const bytes = new TextEncoder().encode(text)
+  let binary = ''
+
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte)
+  }
+
+  return globalThis.btoa(binary)
+}
+
+export const documentPartFromText = (input: {
+  readonly text: string
+  readonly filename: string
+  readonly mimeType: string
+  readonly title?: string
+}) => {
+  const normalized = normalizeMimeType(input.mimeType)
+  const mimeType = inferTextDocumentMimeType({
+    filename: input.filename,
+    mimeType: input.mimeType
+  }) ?? (isUnknownDocumentMimeType(normalized) ? 'text/plain' : undefined)
+
+  if (mimeType === undefined) return undefined
+
+  const base = {
+    source: inlineBase64AttachmentSource(textToBase64Utf8(input.text)),
+    mimeType,
+    filename: input.filename
+  }
+
+  return input.title === undefined
+    ? DocumentPart.make(base)
+    : DocumentPart.make({ ...base, title: input.title })
+}
+
+const decodeBase64Utf8 = (data: string) => {
+  const binary = globalThis.atob(data)
+  const bytes = Uint8Array.from(binary, character => character.charCodeAt(0))
+
+  return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+}
+
+export const attachmentSourceText = (source: AttachmentSource) => {
+  switch (source._tag) {
+    case 'InlineBase64':
+      return Effect.try({
+        try: () => Option.some(decodeBase64Utf8(source.data)),
+        catch: error => error
+      })
+    case 'Url':
+    case 'Ref':
+      return Effect.succeed(Option.none<string>())
+  }
+}
+
 export const attachmentSourceBase64 = (source: AttachmentSource) => {
   switch (source._tag) {
     case 'InlineBase64':

package/src/protocol/event.ts

@@ -27,6 +27,7 @@ export const AgentErrorCode = Schema.Literals([
   'validation_error',
   'provider_error',
   'rate_limit',
+  'overloaded',
   'context_overflow',
   'invalid_response',
   'tool_error',
@@ -40,6 +41,27 @@ export const AgentErrorCode = Schema.Literals([
 ])
 export type AgentErrorCode = typeof AgentErrorCode.Type
 
+export const ProviderFailureKind = Schema.Literals([
+  'rate_limit',
+  'overloaded',
+  'server_error',
+  'network',
+  'stream',
+  'auth',
+  'context_overflow',
+  'invalid_response',
+  'unknown'
+])
+export type ProviderFailureKind = typeof ProviderFailureKind.Type
+
+export class ProviderErrorInfo extends Schema.Class<ProviderErrorInfo>('ProviderErrorInfo')({
+  provider: NonEmptyTrimmedString,
+  kind: ProviderFailureKind,
+  status: Schema.optional(Schema.Number),
+  providerCode: Schema.optional(Schema.String),
+  retryAfterMs: Schema.optional(Schema.Number)
+}) {}
+
 export class AgentStart extends Schema.TaggedClass<AgentStart>()('AgentStart', {
   ...EventIdentity
 }) {}
@@ -48,7 +70,8 @@ export class AgentError extends Schema.TaggedClass<AgentError>()('AgentError', {
   ...EventIdentity,
   code: AgentErrorCode,
   message: Schema.String,
-  retryable: Schema.Boolean
+  retryable: Schema.Boolean,
+  provider: Schema.optional(ProviderErrorInfo)
 }) {}
 
 export class AgentEnd extends Schema.TaggedClass<AgentEnd>()('AgentEnd', {
@@ -79,7 +102,8 @@ export class AgentRetry extends Schema.TaggedClass<AgentRetry>()('AgentRetry', {
   attempt: Schema.Number,
   reason: AgentErrorCode,
   delayMs: Schema.Number,
-  message: Schema.String
+  message: Schema.String,
+  provider: Schema.optional(ProviderErrorInfo)
 }) {}
 
 export class CompactionStart extends Schema.TaggedClass<CompactionStart>()('CompactionStart', {

package/src/protocol/index.ts

@@ -10,6 +10,7 @@ export {
   attachmentSourceBase64,
   attachmentSourceDataUrl,
   AttachmentSource,
+  attachmentSourceText,
   type AttachmentContentPart,
   type AttachmentSourceResolver,
   attachmentSourcePreview,
@@ -22,14 +23,19 @@ export {
   contentPreview,
   contentText,
   DocumentPart,
+  documentPartFromText,
   ImagePart,
+  inferTextDocumentMimeType,
   InlineBase64AttachmentSource,
   inlineBase64AttachmentSource,
   inlineBase64Source,
   isContentEmpty,
+  isTextDocumentMimeType,
   refAttachmentSource,
   RefAttachmentSource,
   resolveContentAttachmentSources,
+  textDocumentMimeTypeFromFilename,
+  textToBase64Utf8,
   urlAttachmentSource,
   UrlAttachmentSource,
   TextPart
@@ -49,6 +55,8 @@ export {
   LLMStreamEnd,
   LLMStreamStart,
   LLMTextDelta,
+  ProviderErrorInfo,
+  ProviderFailureKind,
   ProviderToolResult,
   QuestionAnswered,
   QuestionCancelled,

package/src/providers/anthropic/claude-provider.ts

@@ -12,13 +12,16 @@ import {
   AgentUsage,
   ToolCall,
   attachmentSourceBase64,
+  attachmentSourceText,
   assistantContent,
   assistantHostToolCalls,
+  isTextDocumentMimeType,
   messageContextText,
   prependMessageContextToContent,
   type AgentMessage,
   type Content,
   type ContentPart,
+  type ProviderFailureKind,
   type ToolDef
 } from '@yolk-sdk/agent/protocol'
 import {
@@ -39,6 +42,12 @@ import {
   anthropicClaudeOAuthUserAgent
 } from './claude.ts'
 import type { OAuthAccessToken } from '@yolk-sdk/agent/oauth'
+import {
+  classifyProviderFailure,
+  providerErrorInfo,
+  providerFailureCause,
+  providerFailureRetryable
+} from '../provider-error.ts'
 
 export type AnthropicClaudeProviderConfig = {
   readonly token: OAuthAccessToken
@@ -433,6 +442,24 @@ const unsupportedContentError = (contentType: string) =>
     retryable: false
   })
 
+const textDocumentToAnthropicBlock = (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: AnthropicTextBlock = {
+            type: 'text',
+            text: `Document: ${part.title ?? part.filename}\n\n${text}`
+          }
+
+          return Effect.succeed(block)
+        }
+      })
+    )
+  )
+
 const contentPartToUserBlock = (part: ContentPart): Effect.Effect<AnthropicUserBlock, LLMError> => {
   switch (part._tag) {
     case 'Text':
@@ -450,7 +477,9 @@ const contentPartToUserBlock = (part: ContentPart): Effect.Effect<AnthropicUserB
         })
       })
     case 'Document':
-      return part.mimeType === 'application/pdf'
+      return isTextDocumentMimeType(part.mimeType)
+        ? textDocumentToAnthropicBlock(part)
+        : part.mimeType === 'application/pdf'
         ? Option.match(attachmentSourceBase64(part.source), {
             onNone: () => Effect.fail(unsupportedContentError('Unresolved document source')),
             onSome: data => Effect.succeed({
@@ -795,26 +824,19 @@ export const toAnthropicClaudeRequestBody = (
     }
   })
 
-const responseStatusToCause = (status: number): LLMError['cause'] => {
-  if (status === 429) {
-    return 'rate_limit'
-  }
-
-  if (status === 413 || status === 400) {
-    return 'context_overflow'
-  }
-
-  return 'provider_error'
-}
-
-const isRetryableStatus = (status: number) => status === 429 || status >= 500
+const anthropicClaudeProvider = 'anthropic_claude'
 
 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: anthropicClaudeProvider,
+        kind: retryable ? kind : 'unknown'
+      })
     })
 
 const decodeJsonString = (raw: string, message: string) =>
@@ -840,6 +862,26 @@ const stringField = (value: unknown, key: string) => {
   return typeof raw === 'string' ? raw : undefined
 }
 
+const providerSignalError = (input: {
+  readonly message: string
+  readonly providerCode?: string
+  readonly fallbackKind?: ProviderFailureKind
+}) => {
+  const provider = classifyProviderFailure({
+    provider: anthropicClaudeProvider,
+    message: input.message,
+    ...(input.providerCode === undefined ? {} : { providerCode: input.providerCode }),
+    ...(input.fallbackKind === undefined ? {} : { fallbackKind: input.fallbackKind })
+  })
+
+  return new LLMError({
+    cause: providerFailureCause(provider.kind),
+    message: input.message,
+    retryable: providerFailureRetryable(provider.kind),
+    provider
+  })
+}
+
 const numberField = (value: unknown, key: string) => {
   const raw = field(value, key)
   return typeof raw === 'number' ? raw : undefined
@@ -1134,11 +1176,12 @@ const makeAnthropicStreamEmitter = () => {
 
     if (type === 'error') {
       const error = field(data, 'error')
+      const providerCode = stringField(error, 'type') ?? stringField(error, 'code')
+
       return Effect.fail(
-        new LLMError({
-          cause: 'provider_error',
+        providerSignalError({
           message: stringField(error, 'message') ?? 'Anthropic Claude stream error',
-          retryable: false
+          ...(providerCode === undefined ? {} : { providerCode })
         })
       )
     }
@@ -1258,7 +1301,7 @@ export const streamAnthropicClaudeResponse = (
       Effect.map(bodyStateRef => {
         const emitData = makeAnthropicStreamEmitter()
         const chunks = response.stream.pipe(
-          Stream.mapError(toHttpClientLlmError('Could not read Anthropic Claude stream', false)),
+          Stream.mapError(toHttpClientLlmError('Could not read Anthropic Claude stream', true, 'stream')),
           Stream.decodeText,
           Stream.mapEffect(chunk =>
             Effect.gen(function* () {
@@ -1316,11 +1359,19 @@ const sendAnthropicClaudeRequest = (
         )
       )
 
+      const provider = classifyProviderFailure({
+        provider: anthropicClaudeProvider,
+        status: response.status,
+        headers: response.headers,
+        body: errorText
+      })
+
       return yield* Effect.fail(
         new LLMError({
-          cause: responseStatusToCause(response.status),
-          message: `Anthropic Claude returned ${response.status}: ${errorText}`,
-          retryable: isRetryableStatus(response.status)
+          cause: providerFailureCause(provider.kind),
+          message: `Anthropic Claude returned ${response.status}`,
+          retryable: providerFailureRetryable(provider.kind),
+          provider
         })
       )
     }