@strav/brain 0.4.30 → 1.0.0-alpha.8

package/src/providers/openai_responses_provider.ts

@@ -1,321 +0,0 @@
-import { parseSSE } from '../utils/sse_parser.ts'
-import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
-import { ExternalServiceError } from '@strav/kernel'
-import { scrubProviderError } from '../utils/error_scrub.ts'
-import type {
-  AIProvider,
-  CompletionRequest,
-  CompletionResponse,
-  StreamChunk,
-  ProviderConfig,
-  Message,
-  ToolCall,
-  Usage,
-} from '../types.ts'
-
-/**
- * OpenAI Responses API provider (`/v1/responses`).
- *
- * Drop-in replacement for the Chat Completions provider.
- * Implements the same `AIProvider` interface so Thread, AgentRunner,
- * and all Brain helpers work unchanged.
- */
-export class OpenAIResponsesProvider implements AIProvider {
-  readonly name: string
-  private apiKey: string
-  private baseUrl: string
-  private defaultModel: string
-  private defaultMaxTokens?: number
-  private retryOptions: RetryOptions
-
-  constructor(config: ProviderConfig, name?: string) {
-    this.name = name ?? 'openai'
-    this.apiKey = config.apiKey
-    this.baseUrl = (config.baseUrl ?? 'https://api.openai.com').replace(/\/$/, '')
-    this.defaultModel = config.model
-    this.defaultMaxTokens = config.maxTokens
-    this.retryOptions = {
-      maxRetries: config.maxRetries ?? 3,
-      baseDelay: config.retryBaseDelay ?? 1000,
-    }
-  }
-
-  // ── Non-streaming completion ────────────────────────────────────────────
-
-  async complete(request: CompletionRequest): Promise<CompletionResponse> {
-    const body = this.buildRequestBody(request, false)
-
-    const response = await retryableFetch(
-      'OpenAI',
-      `${this.baseUrl}/v1/responses`,
-      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
-      this.retryOptions
-    )
-
-    const data: any = await response.json()
-    return this.parseResponse(data)
-  }
-
-  // ── Streaming completion ────────────────────────────────────────────────
-
-  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
-    const body = this.buildRequestBody(request, true)
-
-    const response = await retryableFetch(
-      'OpenAI',
-      `${this.baseUrl}/v1/responses`,
-      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
-      this.retryOptions
-    )
-
-    if (!response.body) {
-      throw new ExternalServiceError('OpenAI', undefined, 'No stream body returned')
-    }
-
-    // Track function call items by output_index for tool_start/tool_delta mapping
-    const toolIndexMap = new Map<number, { callId: string; name: string }>()
-    let toolCounter = 0
-
-    for await (const sse of parseSSE(response.body)) {
-      const eventType = sse.event ?? ''
-      let data: any
-
-      try {
-        data = JSON.parse(sse.data)
-      } catch {
-        continue
-      }
-
-      // ── Text content ──────────────────────────────────────────────
-      if (eventType === 'response.output_text.delta') {
-        yield { type: 'text', text: data.delta ?? '' }
-        continue
-      }
-
-      // ── Function call start ───────────────────────────────────────
-      if (eventType === 'response.output_item.added' && data.item?.type === 'function_call') {
-        const index = toolCounter++
-        toolIndexMap.set(data.output_index ?? index, {
-          callId: data.item.call_id ?? '',
-          name: data.item.name ?? '',
-        })
-        yield {
-          type: 'tool_start',
-          toolCall: { id: data.item.call_id ?? '', name: data.item.name ?? '' },
-          toolIndex: index,
-        }
-        continue
-      }
-
-      // ── Function call argument deltas ─────────────────────────────
-      if (eventType === 'response.function_call_arguments.delta') {
-        // Map output_index to our sequential toolIndex
-        const outputIdx = data.output_index ?? 0
-        let toolIdx = 0
-        for (const [oi] of toolIndexMap) {
-          if (oi === outputIdx) break
-          toolIdx++
-        }
-        yield { type: 'tool_delta', text: data.delta ?? '', toolIndex: toolIdx }
-        continue
-      }
-
-      // ── Function call arguments done ──────────────────────────────
-      if (eventType === 'response.function_call_arguments.done') {
-        const outputIdx = data.output_index ?? 0
-        let toolIdx = 0
-        for (const [oi] of toolIndexMap) {
-          if (oi === outputIdx) break
-          toolIdx++
-        }
-        yield { type: 'tool_end', toolIndex: toolIdx }
-        continue
-      }
-
-      // ── Response completed ────────────────────────────────────────
-      if (eventType === 'response.completed') {
-        const usage = data.response?.usage
-        if (usage) {
-          yield {
-            type: 'usage',
-            usage: {
-              inputTokens: usage.input_tokens ?? 0,
-              outputTokens: usage.output_tokens ?? 0,
-              totalTokens: usage.total_tokens ?? 0,
-            },
-          }
-        }
-        yield { type: 'done' }
-        break
-      }
-
-      // ── Error ─────────────────────────────────────────────────────
-      if (eventType === 'error') {
-        const message = typeof data.message === 'string' ? data.message : JSON.stringify(data)
-        throw new ExternalServiceError('OpenAI', undefined, scrubProviderError(message))
-      }
-    }
-  }
-
-  // ── Private helpers ─────────────────────────────────────────────────────
-
-  private buildHeaders(): Record<string, string> {
-    return {
-      'content-type': 'application/json',
-      authorization: `Bearer ${this.apiKey}`,
-    }
-  }
-
-  private buildRequestBody(request: CompletionRequest, stream: boolean): Record<string, unknown> {
-    const body: Record<string, unknown> = {
-      model: request.model ?? this.defaultModel,
-      input: this.mapMessages(request.messages),
-    }
-
-    // System prompt → instructions
-    if (request.system) {
-      body.instructions = request.system
-    }
-
-    if (stream) body.stream = true
-    if (request.maxTokens ?? this.defaultMaxTokens) {
-      body.max_output_tokens = request.maxTokens ?? this.defaultMaxTokens
-    }
-    // Note: temperature is not supported by the Responses API for some models
-    // if (request.temperature !== undefined) body.temperature = request.temperature
-    if (request.stopSequences?.length) body.stop = request.stopSequences
-
-    // Tools
-    if (request.tools?.length) {
-      body.tools = request.tools.map(t => ({
-        type: 'function',
-        name: t.name,
-        description: t.description,
-        parameters: t.parameters,
-      }))
-    }
-
-    // Tool choice
-    if (request.toolChoice) {
-      if (typeof request.toolChoice === 'string') {
-        body.tool_choice = request.toolChoice
-      } else {
-        body.tool_choice = {
-          type: 'function',
-          name: request.toolChoice.name,
-        }
-      }
-    }
-
-    // Structured output
-    if (request.schema) {
-      body.text = {
-        format: {
-          type: 'json_schema',
-          name: 'response',
-          schema: request.schema,
-          strict: true,
-        },
-      }
-    }
-
-    return body
-  }
-
-  /**
-   * Translate Brain Message[] into Responses API input items.
-   *
-   * User messages → { role: 'user', content }
-   * Assistant messages → assistant message item + separate function_call items
-   * Tool messages → { type: 'function_call_output', call_id, output }
-   */
-  private mapMessages(messages: Message[]): any[] {
-    const items: any[] = []
-
-    for (const msg of messages) {
-      if (msg.role === 'user') {
-        items.push({
-          role: 'user',
-          content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
-        })
-      } else if (msg.role === 'assistant') {
-        const text = typeof msg.content === 'string' ? msg.content : ''
-
-        // Add assistant message item (only if there's text content)
-        if (text) {
-          items.push({
-            type: 'message',
-            role: 'assistant',
-            content: [{ type: 'output_text', text }],
-          })
-        }
-
-        // Add function_call items for any tool calls
-        if (msg.toolCalls?.length) {
-          for (const tc of msg.toolCalls) {
-            items.push({
-              type: 'function_call',
-              call_id: tc.id,
-              name: tc.name,
-              arguments: JSON.stringify(tc.arguments),
-            })
-          }
-        }
-      } else if (msg.role === 'tool') {
-        items.push({
-          type: 'function_call_output',
-          call_id: msg.toolCallId ?? '',
-          output: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
-        })
-      }
-    }
-
-    return items
-  }
-
-  /**
-   * Parse a non-streaming Responses API response into Brain CompletionResponse.
-   */
-  private parseResponse(data: any): CompletionResponse {
-    const output: any[] = data.output ?? []
-    let content = ''
-    const toolCalls: ToolCall[] = []
-
-    for (const item of output) {
-      if (item.type === 'message' && item.role === 'assistant') {
-        for (const part of item.content ?? []) {
-          if (part.type === 'output_text') {
-            content += part.text ?? ''
-          }
-        }
-      } else if (item.type === 'function_call') {
-        let args: Record<string, unknown> = {}
-        try {
-          args = JSON.parse(item.arguments ?? '{}')
-        } catch {
-          args = item.arguments ? { _raw: item.arguments } : {}
-        }
-        toolCalls.push({
-          id: item.call_id ?? item.id ?? '',
-          name: item.name ?? '',
-          arguments: args,
-        })
-      }
-    }
-
-    const usage: Usage = {
-      inputTokens: data.usage?.input_tokens ?? 0,
-      outputTokens: data.usage?.output_tokens ?? 0,
-      totalTokens: data.usage?.total_tokens ?? 0,
-    }
-
-    let stopReason: CompletionResponse['stopReason'] = 'end'
-    if (toolCalls.length > 0) {
-      stopReason = 'tool_use'
-    } else if (data.status === 'incomplete') {
-      stopReason = 'max_tokens'
-    }
-
-    return { id: data.id ?? '', content, toolCalls, stopReason, usage, raw: data }
-  }
-}

package/src/tool.ts

@@ -1,51 +0,0 @@
-import { zodToJsonSchema } from './utils/schema.ts'
-import type { ToolDefinition, JsonSchema } from './types.ts'
-
-/**
- * Define a tool that an agent can invoke.
- *
- * Accepts either a Zod schema or a raw JSON Schema object
- * for `parameters`. Zod schemas are automatically converted.
- *
- * @example
- * const searchTool = defineTool({
- *   name: 'search',
- *   description: 'Search the database',
- *   parameters: z.object({ query: z.string() }),
- *   execute: async ({ query }, context) => {
- *     const userId = context?.userId
- *     return await db.search(query, { userId })
- *   },
- * })
- */
-export function defineTool<TArgs = any, TContext = Record<string, unknown>>(config: {
-  name: string
-  description: string
-  parameters: any
-  execute: (args: TArgs, context?: TContext) => unknown | Promise<unknown>
-}): ToolDefinition {
-  return {
-    name: config.name,
-    description: config.description,
-    parameters: zodToJsonSchema(config.parameters) as JsonSchema,
-    execute: config.execute as (args: Record<string, unknown>, context?: Record<string, unknown>) => unknown | Promise<unknown>,
-  }
-}
-
-/**
- * Group related tools into a named collection.
- *
- * A toolbox is simply a labeled array — useful for organizing
- * tools by domain (e.g., database tools, API tools) and
- * spreading them into an agent's `tools` array.
- *
- * @example
- * const dbTools = defineToolbox('database', [searchTool, insertTool])
- *
- * class MyAgent extends Agent {
- *   tools = [...dbTools, weatherTool]
- * }
- */
-export function defineToolbox(_name: string, tools: ToolDefinition[]): ToolDefinition[] {
-  return tools
-}

package/src/utils/error_scrub.ts

@@ -1,5 +0,0 @@
-// Re-export the shared kernel helper so the same scrubber is used across
-// every package that wraps upstream-provider errors. Keeping this thin
-// re-export avoids a breaking import-path change for callers that
-// already pulled `scrubProviderError` from `@strav/brain/utils/error_scrub`.
-export { scrubProviderError } from '@strav/kernel'

package/src/utils/prompt.ts

@@ -1,65 +0,0 @@
-/**
- * Heuristic detector for prompt-injection markers in untrusted strings
- * destined for the system prompt. The interpolation in
- * `agent.instructions` does naïve `replaceAll` of `{{key}}` placeholders
- * with string values — any user-controlled value flowing through is a
- * prompt-injection vector against the LLM.
- *
- * We can't fully solve this at the template layer (the proper fix is to
- * pass values as structured user-role messages, not interpolate them
- * into the system role). What we can do is detect the easy cases and
- * warn the developer that a value looks suspicious. Detection here is
- * deliberately loose — false positives are cheap, missed cases let
- * exploits through silently.
- */
-const INJECTION_PATTERNS: readonly RegExp[] = [
-  /ignore\s+(?:[\w\s]{0,30}\s+)?(?:instructions?|prompts?|messages?)/i,
-  /disregard\s+(?:[\w\s]{0,30}\s+)?(?:instructions?|prompts?|messages?)/i,
-  /(?:^|\n)\s*system\s*[:>]/i,
-  /(?:^|\n)\s*assistant\s*[:>]/i,
-  /\bsystem\s*:\s*\S/i,
-  /you\s+are\s+now\s+(?:a|an|the)/i,
-  /act\s+as\s+(?:a|an|the)\s+(?:different|new)/i,
-  /\[INST\]|\[\/INST\]/i,
-  /<\|im_(?:start|end)\|>/i,
-  /<\|system\|>|<\|user\|>|<\|assistant\|>/i,
-  /###\s*(?:system|instruction|new\s+instruction)/i,
-]
-
-/** Return true if the string contains a known prompt-injection marker. */
-export function looksLikePromptInjection(value: string): boolean {
-  if (!value || typeof value !== 'string') return false
-  return INJECTION_PATTERNS.some(re => re.test(value))
-}
-
-/**
- * Substitute `{{key}}` placeholders in a system-prompt template with
- * values from `context`. Emits a `console.warn` when a value matches
- * `looksLikePromptInjection()` so developers notice when untrusted
- * input is reaching the system prompt.
- *
- * The replacement still happens — the warning is informational. Callers
- * who need hard rejection should validate context themselves before
- * calling. The framework cannot decide whether a given context value is
- * trusted; only the application can.
- */
-export function interpolateInstructions(
-  template: string,
-  context: Record<string, unknown>
-): string {
-  let out = template
-  for (const [key, rawValue] of Object.entries(context)) {
-    const stringValue = String(rawValue)
-    if (looksLikePromptInjection(stringValue)) {
-      console.warn(
-        `[brain] Possible prompt-injection in agent context.${key} — ` +
-          `the value contains markers commonly used to override system ` +
-          `instructions. Treat untrusted user input as user-role messages, ` +
-          `not as interpolated system-prompt context. ` +
-          `See packages/brain/CLAUDE.md ("Prompt-injection threat model").`
-      )
-    }
-    out = out.replaceAll(`{{${key}}}`, stringValue)
-  }
-  return out
-}

package/src/utils/retry.ts

@@ -1,104 +0,0 @@
-import { ExternalServiceError } from '@strav/kernel'
-import { scrubProviderError } from './error_scrub.ts'
-
-export interface RetryOptions {
-  maxRetries?: number
-  baseDelay?: number
-  maxDelay?: number
-  retryableStatuses?: number[]
-}
-
-const DEFAULT_RETRYABLE = [429, 500, 502, 503, 529]
-
-/**
- * Fetch with automatic retry and exponential backoff for transient errors.
- *
- * Retries on 429 (rate limit), 5xx, and network failures.
- * Parses the `retry-after` header when available; otherwise uses
- * exponential backoff with jitter.
- *
- * Returns the successful `Response`. On final failure, throws
- * `ExternalServiceError` with the last status and body.
- */
-export async function retryableFetch(
-  service: string,
-  url: string,
-  init: RequestInit,
-  options?: RetryOptions
-): Promise<Response> {
-  const maxRetries = options?.maxRetries ?? 3
-  const baseDelay = options?.baseDelay ?? 1000
-  const maxDelay = options?.maxDelay ?? 60_000
-  const retryable = options?.retryableStatuses ?? DEFAULT_RETRYABLE
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    let response: Response
-
-    try {
-      response = await fetch(url, init)
-    } catch (err) {
-      // Network error (DNS, connection refused, etc.). Some Bun/Node
-      // network errors include the URL — scrub before surfacing in
-      // case it carries credentials in query params.
-      if (attempt === maxRetries) {
-        throw new ExternalServiceError(
-          service,
-          undefined,
-          scrubProviderError(err instanceof Error ? err.message : String(err))
-        )
-      }
-      await sleep(backoffDelay(attempt, baseDelay, maxDelay))
-      continue
-    }
-
-    if (response.ok) return response
-
-    // Non-retryable status — fail immediately. Provider response bodies
-    // can echo request headers or other context; scrub before wrapping.
-    if (!retryable.includes(response.status)) {
-      const text = await response.text()
-      throw new ExternalServiceError(service, response.status, scrubProviderError(text))
-    }
-
-    // Retryable status — wait and retry (unless last attempt)
-    if (attempt === maxRetries) {
-      const text = await response.text()
-      throw new ExternalServiceError(service, response.status, scrubProviderError(text))
-    }
-
-    const delay = parseRetryAfter(response) ?? backoffDelay(attempt, baseDelay, maxDelay)
-    await sleep(delay)
-  }
-
-  // Unreachable, but satisfies TypeScript
-  throw new ExternalServiceError(service, undefined, 'Retry loop exited unexpectedly')
-}
-
-/**
- * Parse the `retry-after` header into milliseconds.
- * Supports both delta-seconds ("2") and HTTP-date formats.
- */
-function parseRetryAfter(response: Response): number | null {
-  const header = response.headers.get('retry-after')
-  if (!header) return null
-
-  const seconds = Number(header)
-  if (!Number.isNaN(seconds)) return seconds * 1000
-
-  // HTTP-date format
-  const date = Date.parse(header)
-  if (!Number.isNaN(date)) return Math.max(0, date - Date.now())
-
-  return null
-}
-
-/** Exponential backoff with jitter: base * 2^attempt + random jitter, capped at maxDelay. */
-function backoffDelay(attempt: number, baseDelay: number, maxDelay: number): number {
-  const exp = baseDelay * 2 ** attempt
-  const jitter = Math.random() * baseDelay
-  return Math.min(exp + jitter, maxDelay)
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}

package/src/utils/schema.ts

@@ -1,27 +0,0 @@
-import type { JsonSchema } from '../types.ts'
-
-/**
- * Convert a Zod schema to a JSON Schema object.
- *
- * Detection logic:
- * - If the input has a `toJSONSchema()` method (Zod v4+), use it directly
- * - If the input is already a plain object (raw JSON Schema), return as-is
- * - null/undefined pass through unchanged
- *
- * The `$schema` meta-field is stripped from the output since
- * AI provider APIs don't expect it.
- */
-export function zodToJsonSchema(schema: any): JsonSchema {
-  if (schema == null) return schema
-
-  // Zod v4+: native toJSONSchema() method
-  if (typeof schema.toJSONSchema === 'function') {
-    const jsonSchema = schema.toJSONSchema()
-    // Strip the $schema meta-field — providers don't need it
-    const { $schema, ...rest } = jsonSchema
-    return rest as JsonSchema
-  }
-
-  // Already a plain JSON Schema object
-  return schema as JsonSchema
-}

package/src/utils/sse_parser.ts

@@ -1,62 +0,0 @@
-import type { SSEEvent } from '../types.ts'
-
-/**
- * Parse a Server-Sent Events stream into structured events.
- *
- * Handles:
- * - Chunks split at arbitrary byte boundaries
- * - Multi-line `data:` fields (concatenated with newlines)
- * - Optional `event:` field
- * - Empty lines / keepalive comments
- */
-export async function* parseSSE(stream: ReadableStream<Uint8Array>): AsyncIterable<SSEEvent> {
-  const reader = stream.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ''
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-
-      buffer += decoder.decode(value, { stream: true })
-
-      const events = buffer.split('\n\n')
-      // Last element is either empty (if buffer ended with \n\n) or incomplete
-      buffer = events.pop()!
-
-      for (const block of events) {
-        const parsed = parseBlock(block)
-        if (parsed) yield parsed
-      }
-    }
-
-    // Flush any remaining data in buffer
-    if (buffer.trim()) {
-      const parsed = parseBlock(buffer)
-      if (parsed) yield parsed
-    }
-  } finally {
-    reader.releaseLock()
-  }
-}
-
-function parseBlock(block: string): SSEEvent | null {
-  let event: string | undefined
-  const dataLines: string[] = []
-
-  for (const line of block.split('\n')) {
-    if (line.startsWith('event: ')) {
-      event = line.slice(7)
-    } else if (line.startsWith('data: ')) {
-      dataLines.push(line.slice(6))
-    } else if (line === 'data:') {
-      dataLines.push('')
-    }
-    // Skip comments (lines starting with ':') and other fields
-  }
-
-  if (dataLines.length === 0) return null
-
-  return { event, data: dataLines.join('\n') }
-}