@andypai/orb 0.1.1

package/src/pipeline/adapters/openai.ts

@@ -0,0 +1,202 @@
+import { createBashTool } from 'bash-tool'
+import { ToolLoopAgent, stepCountIs, type ToolSet, type StepResult } from 'ai'
+import { buildProviderPrompt } from '../../services/prompts'
+import type { Frame } from '../frames'
+import { createFrame } from '../frames'
+import type { AgentAdapter, AgentAdapterConfig } from './types'
+import { normalizeToolInput, isToolError, formatToolResult } from './utils'
+import { resolveOpenAiProvider } from '../../services/openai-auth'
+
+interface OaiToolCall {
+  toolCallId: string
+  toolName: string
+  input: unknown
+}
+
+interface OaiToolResult {
+  toolCallId: string
+  toolName: string
+  output: unknown
+}
+
+export function createOpenAiAdapter(config: AgentAdapterConfig): AgentAdapter {
+  return {
+    async *stream(prompt: string): AsyncIterable<Frame> {
+      const { appConfig, session, abortController } = config
+      const previousResponseId =
+        session?.provider === 'openai' ? session.previousResponseId : undefined
+      const instructions = await buildProviderPrompt({
+        provider: 'openai',
+        projectPath: appConfig.projectPath,
+        ttsEnabled: appConfig.ttsEnabled,
+      })
+
+      const { tools, sandbox } = await createBashTool({
+        uploadDirectory: {
+          source: appConfig.projectPath,
+          include: '**/*',
+        },
+        maxFiles: 5000,
+      })
+
+      const { bash, readFile, writeFile } = tools
+      const allowedTools: ToolSet = { bash, readFile, writeFile }
+
+      let accumulatedText = ''
+      let toolIndex = 0
+      const toolIdToIndex = new Map<string, number>()
+      const pendingFrames: Frame[] = []
+
+      function getOrCreateIndex(toolId: string): number {
+        const existing = toolIdToIndex.get(toolId)
+        if (existing !== undefined) return existing
+        const index = toolIndex++
+        toolIdToIndex.set(toolId, index)
+        return index
+      }
+
+      function registerToolCall(call: OaiToolCall): void {
+        const index = getOrCreateIndex(call.toolCallId)
+        pendingFrames.push(
+          createFrame('tool-call-start', {
+            toolCall: {
+              id: call.toolCallId,
+              index,
+              name: call.toolName,
+              input: normalizeToolInput(call.input),
+              status: 'running',
+            },
+          }),
+        )
+      }
+
+      function registerToolResult(result: OaiToolResult): void {
+        const existingIndex = toolIdToIndex.get(result.toolCallId)
+        const index = getOrCreateIndex(result.toolCallId)
+
+        if (existingIndex === undefined) {
+          pendingFrames.push(
+            createFrame('tool-call-start', {
+              toolCall: {
+                id: result.toolCallId,
+                index,
+                name: result.toolName,
+                input: {},
+                status: 'running',
+              },
+            }),
+          )
+        }
+
+        const text = formatToolResult(result.output)
+        pendingFrames.push(
+          createFrame('tool-call-result', {
+            toolIndex: index,
+            result: text,
+            status: isToolError(result.output) ? 'error' : 'complete',
+          }),
+        )
+      }
+
+      const { provider } = await resolveOpenAiProvider(appConfig)
+      const model = provider.responses(appConfig.llmModel as never)
+
+      let finalResponseId: string | undefined
+
+      const runStream = async function* (continuationResponseId?: string): AsyncIterable<Frame> {
+        accumulatedText = ''
+        toolIndex = 0
+        toolIdToIndex.clear()
+        pendingFrames.length = 0
+
+        const agent = new ToolLoopAgent({
+          model,
+          ...(continuationResponseId ? {} : { instructions }),
+          tools: allowedTools,
+          stopWhen: stepCountIs(20),
+          providerOptions: {
+            openai: {
+              truncation: 'auto',
+              ...(continuationResponseId
+                ? {
+                    previousResponseId: continuationResponseId,
+                    instructions,
+                  }
+                : {}),
+            },
+          },
+        })
+
+        const agentStream = await agent.stream({
+          prompt,
+          onStepFinish: (stepResult: StepResult<ToolSet>) => {
+            for (const call of stepResult.toolCalls) {
+              registerToolCall(call)
+            }
+            for (const result of stepResult.toolResults) {
+              registerToolResult(result)
+            }
+          },
+          abortSignal: abortController.signal,
+        })
+
+        for await (const chunk of agentStream.textStream) {
+          // Drain any tool frames that arrived via onStepFinish
+          while (pendingFrames.length > 0) {
+            yield pendingFrames.shift()!
+          }
+
+          accumulatedText += chunk
+          yield createFrame('agent-text-delta', {
+            delta: chunk,
+            accumulatedText,
+          })
+        }
+
+        // Drain remaining tool frames after text stream ends
+        while (pendingFrames.length > 0) {
+          yield pendingFrames.shift()!
+        }
+
+        finalResponseId = (await agentStream.response).id
+      }
+
+      const isInvalidContinuationError = (err: unknown): boolean => {
+        if (!previousResponseId) return false
+        const message = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase()
+        const statusCode =
+          typeof err === 'object' && err !== null && 'statusCode' in err
+            ? (err as { statusCode?: number }).statusCode
+            : undefined
+
+        return (
+          statusCode === 400 ||
+          statusCode === 404 ||
+          message.includes('previous_response_id') ||
+          message.includes('previous response') ||
+          message.includes('conversation')
+        )
+      }
+
+      try {
+        try {
+          yield* runStream(previousResponseId)
+        } catch (err) {
+          if (!isInvalidContinuationError(err)) throw err
+          yield* runStream()
+        }
+
+        if (finalResponseId) {
+          yield createFrame('agent-text-complete', {
+            text: accumulatedText,
+            session: { provider: 'openai', previousResponseId: finalResponseId },
+          })
+        }
+      } finally {
+        if ('stop' in sandbox && typeof sandbox.stop === 'function') {
+          await (sandbox.stop as () => Promise<void>)().catch(() => {})
+        }
+      }
+    },
+  }
+}

package/src/pipeline/adapters/types.ts

@@ -0,0 +1,16 @@
+import type { Frame } from '../frames'
+import type { AgentSession, AppConfig } from '../../types'
+
+/**
+ * Normalized interface for agent providers.
+ * Each adapter wraps a provider SDK and yields frames instead of calling callbacks.
+ */
+export interface AgentAdapter {
+  stream(prompt: string): AsyncIterable<Frame>
+}
+
+export interface AgentAdapterConfig {
+  appConfig: AppConfig
+  session: AgentSession | undefined
+  abortController: AbortController
+}

package/src/pipeline/adapters/utils.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared parsing helpers extracted from existing agent implementations.
+ * Used by both Anthropic and OpenAI adapters.
+ */
+
+// ── Anthropic SDK message parsing ──
+
+export type TextBlock = { type: 'text'; text: string }
+export type ToolUseBlock = {
+  type: 'tool_use'
+  id?: string
+  tool_use_id?: string
+  name: string
+  input?: Record<string, unknown>
+}
+export type ToolResultBlock = {
+  type: 'tool_result'
+  tool_use_id?: string
+  id?: string
+  content?: unknown
+  is_error?: boolean
+}
+
+export function getContentBlocks(message: unknown): unknown[] {
+  if (typeof message === 'string') {
+    return [{ type: 'text', text: message }]
+  }
+  if (!message || typeof message !== 'object') return []
+  const content = (message as { content?: unknown }).content
+  return Array.isArray(content) ? content : []
+}
+
+function hasType(value: unknown, type: string): value is { type: string } {
+  return value !== null && typeof value === 'object' && (value as { type?: unknown }).type === type
+}
+
+export function isTextBlock(value: unknown): value is TextBlock {
+  return hasType(value, 'text')
+}
+
+export function isToolUseBlock(value: unknown): value is ToolUseBlock {
+  return hasType(value, 'tool_use') && typeof (value as ToolUseBlock).name === 'string'
+}
+
+export function isToolResultBlock(value: unknown): value is ToolResultBlock {
+  return hasType(value, 'tool_result')
+}
+
+export function extractToolResultText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => {
+        if (!block || typeof block !== 'object') return ''
+        const typedBlock = block as { type?: string; text?: string }
+        if (typedBlock.type === 'text' && typeof typedBlock.text === 'string') {
+          return typedBlock.text
+        }
+        return ''
+      })
+      .join('')
+  }
+  if (content && typeof content === 'object' && 'text' in (content as Record<string, unknown>)) {
+    return String((content as { text?: unknown }).text ?? '')
+  }
+  return ''
+}
+
+// ── OpenAI tool result parsing ──
+
+export function normalizeToolInput(value: unknown): Record<string, unknown> {
+  if (!value) return {}
+  if (typeof value === 'object') return value as Record<string, unknown>
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value) as unknown
+      if (parsed && typeof parsed === 'object') {
+        return parsed as Record<string, unknown>
+      }
+    } catch {
+      return { value }
+    }
+  }
+  return { value }
+}
+
+export function isToolError(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return false
+  const typed = value as Record<string, unknown>
+  if (typed.isError === true || typed.is_error === true) return true
+  if (typeof typed.exitCode === 'number' && typed.exitCode !== 0) return true
+  if (typeof typed.success === 'boolean' && typed.success === false) return true
+  if (typed.error instanceof Error) return true
+  if (typeof typed.error === 'string' && typed.error.length > 0) return true
+  return false
+}
+
+export function formatToolResult(value: unknown): string {
+  if (typeof value === 'string') return value
+  if (!value || typeof value !== 'object') return String(value ?? '')
+
+  const typed = value as Record<string, unknown>
+
+  const stdout = typeof typed.stdout === 'string' ? typed.stdout : ''
+  const stderr = typeof typed.stderr === 'string' ? typed.stderr : ''
+  if (stdout || stderr) return [stdout, stderr].filter(Boolean).join('\n').trim()
+
+  if (typeof typed.content === 'string') return typed.content
+  if (typeof typed.result === 'string') return typed.result
+  if (typeof typed.success === 'boolean') return typed.success ? 'success' : 'error'
+
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+// ── Shared ──
+
+export function isAbortError(err: unknown): boolean {
+  if (
+    typeof globalThis.DOMException !== 'undefined' &&
+    err instanceof globalThis.DOMException &&
+    err.name === 'AbortError'
+  )
+    return true
+  if (err instanceof Error && err.name === 'AbortError') return true
+  if (err instanceof Error && err.message.includes('aborted')) return true
+  return false
+}

package/src/pipeline/frames.ts

@@ -0,0 +1,113 @@
+import type { AgentSession, ToolCall, TTSErrorType } from '../types'
+
+// ── Base ──
+
+interface BaseFrame {
+  id: number
+  timestamp: number
+}
+
+// ── User Input ──
+
+export interface UserTextFrame extends BaseFrame {
+  kind: 'user-text'
+  text: string
+  entryId: string
+}
+
+// ── Agent Output ──
+
+export interface AgentTextDeltaFrame extends BaseFrame {
+  kind: 'agent-text-delta'
+  delta: string
+  accumulatedText: string
+}
+
+export interface AgentTextCompleteFrame extends BaseFrame {
+  kind: 'agent-text-complete'
+  text: string
+  session?: AgentSession
+}
+
+export interface ToolCallStartFrame extends BaseFrame {
+  kind: 'tool-call-start'
+  toolCall: ToolCall
+}
+
+export interface ToolCallResultFrame extends BaseFrame {
+  kind: 'tool-call-result'
+  toolIndex: number
+  result: string
+  status: 'complete' | 'error'
+}
+
+export interface AgentSessionFrame extends BaseFrame {
+  kind: 'agent-session'
+  session: AgentSession
+}
+
+export interface AgentErrorFrame extends BaseFrame {
+  kind: 'agent-error'
+  error: Error
+}
+
+// ── TTS ──
+
+export interface TTSSpeakingStartFrame extends BaseFrame {
+  kind: 'tts-speaking-start'
+}
+
+export interface TTSSpeakingEndFrame extends BaseFrame {
+  kind: 'tts-speaking-end'
+}
+
+export interface TTSErrorFrame extends BaseFrame {
+  kind: 'tts-error'
+  errorType: TTSErrorType
+  message: string
+}
+
+// ── Control ──
+
+export interface CancelFrame extends BaseFrame {
+  kind: 'cancel'
+}
+
+// ── Union ──
+
+export type Frame =
+  | UserTextFrame
+  | AgentTextDeltaFrame
+  | AgentTextCompleteFrame
+  | ToolCallStartFrame
+  | ToolCallResultFrame
+  | AgentSessionFrame
+  | AgentErrorFrame
+  | TTSSpeakingStartFrame
+  | TTSSpeakingEndFrame
+  | TTSErrorFrame
+  | CancelFrame
+
+// ── Factory ──
+
+let nextId = 0
+
+type FrameOfKind<K extends Frame['kind']> = Extract<Frame, { kind: K }>
+type FrameData<K extends Frame['kind']> = Omit<FrameOfKind<K>, 'id' | 'timestamp' | 'kind'>
+
+export function createFrame<K extends Frame['kind']>(
+  kind: K,
+  ...[data]: FrameData<K> extends Record<string, never> ? [] : [FrameData<K>]
+): FrameOfKind<K> {
+  return {
+    kind,
+    id: nextId++,
+    timestamp: Date.now(),
+    ...(data ?? {}),
+  } as FrameOfKind<K>
+}
+
+/** Reset frame ID counter (for testing) */
+export function resetFrameIds(): void {
+  nextId = 0
+}

package/src/pipeline/observer.ts

@@ -0,0 +1,36 @@
+import type { Frame } from './frames'
+
+export interface PipelineMetrics {
+  runId: number
+  startTime: number
+  endTime?: number
+
+  /** ms from run start to first AgentTextDeltaFrame */
+  agentFirstTokenMs?: number
+  /** ms from run start to AgentTextCompleteFrame */
+  agentCompleteMs?: number
+  /** total characters across all text deltas */
+  totalTextChars: number
+  toolCallCount: number
+  toolErrorCount: number
+
+  /** ms from run start to first TTSSpeakingStartFrame */
+  ttsSpeakingStartMs?: number
+  /** ms from run start to last TTSSpeakingEndFrame */
+  ttsSpeakingEndMs?: number
+  ttsErrorCount: number
+
+  /** frame counts by kind */
+  frameCounts: Record<string, number>
+}
+
+export interface PipelineObserver {
+  /** Called for every frame flowing through the pipeline */
+  onFrame(frame: Frame): void
+
+  /** Called when a run starts */
+  onRunStart?(runId: number): void
+
+  /** Called when a run completes (with full metrics) */
+  onRunEnd?(metrics: PipelineMetrics): void
+}

package/src/pipeline/observers/metrics.ts

@@ -0,0 +1,95 @@
+import type { Frame } from '../frames'
+import type { PipelineMetrics, PipelineObserver } from '../observer'
+
+/**
+ * Tracks timing and counts for each pipeline run.
+ * Call getMetrics() after onRunEnd to retrieve the snapshot.
+ */
+export function createMetricsObserver(): PipelineObserver & {
+  getMetrics(): PipelineMetrics | null
+} {
+  let current: PipelineMetrics | null = null
+  let lastCompleted: PipelineMetrics | null = null
+
+  function ensureMetrics(runId: number): PipelineMetrics {
+    if (!current || current.runId !== runId) {
+      current = {
+        runId,
+        startTime: Date.now(),
+        totalTextChars: 0,
+        toolCallCount: 0,
+        toolErrorCount: 0,
+        ttsErrorCount: 0,
+        frameCounts: {},
+      }
+    }
+    return current
+  }
+
+  return {
+    onFrame(frame: Frame): void {
+      if (!current) return
+      const m = current
+      const elapsed = Date.now() - m.startTime
+
+      // Count every frame by kind
+      m.frameCounts[frame.kind] = (m.frameCounts[frame.kind] ?? 0) + 1
+
+      switch (frame.kind) {
+        case 'agent-text-delta':
+          if (m.agentFirstTokenMs === undefined) {
+            m.agentFirstTokenMs = elapsed
+          }
+          m.totalTextChars += frame.delta.length
+          break
+
+        case 'agent-text-complete':
+          m.agentCompleteMs = elapsed
+          break
+
+        case 'tool-call-start':
+          m.toolCallCount++
+          break
+
+        case 'tool-call-result':
+          if (frame.status === 'error') m.toolErrorCount++
+          break
+
+        case 'tts-speaking-start':
+          if (m.ttsSpeakingStartMs === undefined) {
+            m.ttsSpeakingStartMs = elapsed
+          }
+          break
+
+        case 'tts-speaking-end':
+          m.ttsSpeakingEndMs = elapsed
+          break
+
+        case 'tts-error':
+          m.ttsErrorCount++
+          break
+      }
+    },
+
+    onRunStart(runId: number): void {
+      ensureMetrics(runId)
+    },
+
+    onRunEnd(metrics: PipelineMetrics): void {
+      if (current) {
+        lastCompleted = {
+          ...current,
+          endTime: metrics.endTime ?? Date.now(),
+        }
+        current = null
+        return
+      }
+
+      lastCompleted = metrics
+    },
+
+    getMetrics(): PipelineMetrics | null {
+      return lastCompleted ?? current
+    },
+  }
+}

package/src/pipeline/pipeline.ts

@@ -0,0 +1,43 @@
+import type { Frame } from './frames'
+import type { Processor } from './processor'
+import type { PipelineObserver } from './observer'
+
+export interface PipelineConfig {
+  processors: Processor[]
+  observers?: PipelineObserver[]
+}
+
+/**
+ * Creates a pipeline that chains processors left-to-right.
+ * The pipeline itself is a Processor: AsyncIterable<Frame> → AsyncIterable<Frame>.
+ */
+export function createPipeline(config: PipelineConfig): Processor {
+  return (source: AsyncIterable<Frame>) => {
+    let stream: AsyncIterable<Frame> = source
+
+    for (const processor of config.processors) {
+      stream = processor(stream)
+    }
+
+    if (config.observers && config.observers.length > 0) {
+      stream = tapObservers(stream, config.observers)
+    }
+
+    return stream
+  }
+}
+
+/**
+ * Wraps a stream to notify observers of each frame without modifying the stream.
+ */
+async function* tapObservers(
+  upstream: AsyncIterable<Frame>,
+  observers: PipelineObserver[],
+): AsyncGenerator<Frame> {
+  for await (const frame of upstream) {
+    for (const observer of observers) {
+      observer.onFrame(frame)
+    }
+    yield frame
+  }
+}

package/src/pipeline/processor.ts

@@ -0,0 +1,57 @@
+import type { Frame } from './frames'
+
+/**
+ * A Processor transforms an async stream of frames.
+ * Compose processors left-to-right: output of one feeds input of the next.
+ * Use `finally` blocks for cleanup on cancellation (generator `.return()`).
+ */
+export type Processor = (upstream: AsyncIterable<Frame>) => AsyncIterable<Frame>
+
+/**
+ * Per-frame handler: receives one frame, returns zero or more frames.
+ * Return `null` to filter a frame out; return the frame to pass it through.
+ */
+type FrameHandler = (frame: Frame) => AsyncIterable<Frame> | Iterable<Frame> | Frame | null
+
+interface ProcessorOptions {
+  onInit?: () => void | Promise<void>
+  onDestroy?: () => void | Promise<void>
+}
+
+/**
+ * Creates a Processor from a simpler per-frame handler.
+ * Handles the common case where each input frame produces 0..N output frames.
+ */
+export function createProcessor(handler: FrameHandler, options?: ProcessorOptions): Processor {
+  return async function* (upstream: AsyncIterable<Frame>): AsyncGenerator<Frame> {
+    await options?.onInit?.()
+    try {
+      for await (const frame of upstream) {
+        const result = handler(frame)
+        if (result === null) continue
+        if (isAsyncIterable(result)) {
+          yield* result
+        } else if (isIterable(result)) {
+          yield* result
+        } else {
+          yield result
+        }
+      }
+    } finally {
+      await options?.onDestroy?.()
+    }
+  }
+}
+
+/** Helper: yield a single frame as an async iterable */
+export async function* singleFrame(frame: Frame): AsyncGenerator<Frame> {
+  yield frame
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<Frame> {
+  return value !== null && typeof value === 'object' && Symbol.asyncIterator in (value as object)
+}
+
+function isIterable(value: unknown): value is Iterable<Frame> {
+  return value !== null && typeof value === 'object' && Symbol.iterator in (value as object)
+}