@tanstack/ai 0.0.1

package/src/core/embedding.ts

@@ -0,0 +1,54 @@
+import { aiEventClient } from '../event-client.js'
+import type {
+  AIAdapter,
+  EmbeddingOptions,
+  EmbeddingResult,
+  ExtractModelsFromAdapter,
+} from '../types'
+
+function createId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+/**
+ * Standalone embedding function with type inference from adapter
+ */
+export async function embedding<
+  TAdapter extends AIAdapter<any, any, any, any, any>,
+>(
+  options: Omit<EmbeddingOptions, 'model'> & {
+    adapter: TAdapter
+    model: ExtractModelsFromAdapter<TAdapter>
+  },
+): Promise<EmbeddingResult> {
+  const { adapter, model, ...restOptions } = options
+  const requestId = createId('embedding')
+  const inputCount = Array.isArray(restOptions.input)
+    ? restOptions.input.length
+    : 1
+  const startTime = Date.now()
+
+  aiEventClient.emit('embedding:started', {
+    requestId,
+    model: model as string,
+    inputCount,
+    timestamp: startTime,
+  })
+
+  const result = await adapter.createEmbeddings({
+    ...restOptions,
+    model: model as string,
+  })
+
+  const duration = Date.now() - startTime
+
+  aiEventClient.emit('embedding:completed', {
+    requestId,
+    model: model as string,
+    inputCount,
+    duration,
+    timestamp: Date.now(),
+  })
+
+  return result
+}

package/src/core/summarize.ts

@@ -0,0 +1,56 @@
+import { aiEventClient } from '../event-client.js'
+import type {
+  AIAdapter,
+  ExtractModelsFromAdapter,
+  SummarizationOptions,
+  SummarizationResult,
+} from '../types'
+
+function createId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+/**
+ * Standalone summarize function with type inference from adapter
+ */
+export async function summarize<
+  TAdapter extends AIAdapter<any, any, any, any, any>,
+>(
+  options: Omit<SummarizationOptions, 'model'> & {
+    adapter: TAdapter
+    model: ExtractModelsFromAdapter<TAdapter>
+    text: string
+  },
+): Promise<SummarizationResult> {
+  const { adapter, model, text, ...restOptions } = options
+  const requestId = createId('summarize')
+  const inputLength = text.length
+  const startTime = Date.now()
+
+  aiEventClient.emit('summarize:started', {
+    requestId,
+    model: model as string,
+    inputLength,
+    timestamp: startTime,
+  })
+
+  const result = await adapter.summarize({
+    ...restOptions,
+    text,
+    model: model as string,
+  })
+
+  const duration = Date.now() - startTime
+  const outputLength = result.summary.length
+
+  aiEventClient.emit('summarize:completed', {
+    requestId,
+    model: model as string,
+    inputLength,
+    outputLength,
+    duration,
+    timestamp: Date.now(),
+  })
+
+  return result
+}

package/src/event-client.ts

@@ -0,0 +1,389 @@
+import { EventClient } from '@tanstack/devtools-event-client'
+
+/**
+ * Tool call states - track the lifecycle of a tool call
+ * Must match @tanstack/ai-client ToolCallState
+ */
+type ToolCallState =
+  | 'awaiting-input' // Received start but no arguments yet
+  | 'input-streaming' // Partial arguments received
+  | 'input-complete' // All arguments received
+  | 'approval-requested' // Waiting for user approval
+  | 'approval-responded' // User has approved/denied
+
+/**
+ * Tool result states - track the lifecycle of a tool result
+ * Must match @tanstack/ai-client ToolResultState
+ */
+type ToolResultState =
+  | 'streaming' // Placeholder for future streamed output
+  | 'complete' // Result is complete
+  | 'error' // Error occurred
+
+export interface AIDevtoolsEventMap {
+  // AI Stream events - from @tanstack/ai package
+  'tanstack-ai-devtools:stream:started': {
+    streamId: string
+    model: string
+    provider: string
+    timestamp: number
+    clientId?: string
+  }
+  'tanstack-ai-devtools:stream:chunk:content': {
+    streamId: string
+    messageId?: string
+    content: string
+    delta?: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:chunk:tool-call': {
+    streamId: string
+    messageId?: string
+    toolCallId: string
+    toolName: string
+    index: number
+    arguments: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:chunk:tool-result': {
+    streamId: string
+    messageId?: string
+    toolCallId: string
+    result: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:chunk:done': {
+    streamId: string
+    messageId?: string
+    finishReason: string | null
+    usage?: {
+      promptTokens: number
+      completionTokens: number
+      totalTokens: number
+    }
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:chunk:error': {
+    streamId: string
+    messageId?: string
+    error: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:chunk:thinking': {
+    streamId: string
+    messageId?: string
+    content: string
+    delta?: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:approval-requested': {
+    streamId: string
+    messageId?: string
+    toolCallId: string
+    toolName: string
+    input: any
+    approvalId: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:tool-input-available': {
+    streamId: string
+    messageId?: string
+    toolCallId: string
+    toolName: string
+    input: any
+    timestamp: number
+  }
+  'tanstack-ai-devtools:tool:call-completed': {
+    requestId: string
+    streamId: string
+    messageId?: string
+    toolCallId: string
+    toolName: string
+    result: any
+    duration: number
+    timestamp: number
+  }
+  'tanstack-ai-devtools:stream:ended': {
+    requestId: string
+    streamId: string
+    totalChunks: number
+    duration: number
+    timestamp: number
+  }
+  'tanstack-ai-devtools:chat:started': {
+    requestId: string
+    streamId: string
+    provider: string
+    model: string
+    messageCount: number
+    hasTools: boolean
+    streaming: boolean
+    timestamp: number
+    clientId?: string
+    toolNames?: Array<string>
+    options?: Record<string, unknown>
+    providerOptions?: Record<string, unknown>
+  }
+  'tanstack-ai-devtools:chat:completed': {
+    requestId: string
+    streamId: string
+    model: string
+    content: string
+    messageId?: string
+    finishReason?: string
+    usage?: {
+      promptTokens: number
+      completionTokens: number
+      totalTokens: number
+    }
+    timestamp: number
+  }
+  'tanstack-ai-devtools:chat:iteration': {
+    requestId: string
+    streamId: string
+    iterationNumber: number
+    messageCount: number
+    toolCallCount: number
+    timestamp: number
+  }
+  'tanstack-ai-devtools:usage:tokens': {
+    requestId: string
+    streamId: string
+    model: string
+    messageId?: string
+    usage: {
+      promptTokens: number
+      completionTokens: number
+      totalTokens: number
+    }
+    timestamp: number
+  }
+
+  // Embedding events
+  'tanstack-ai-devtools:embedding:started': {
+    requestId: string
+    model: string
+    inputCount: number
+    timestamp: number
+    clientId?: string
+  }
+  'tanstack-ai-devtools:embedding:completed': {
+    requestId: string
+    model: string
+    inputCount: number
+    duration: number
+    timestamp: number
+  }
+
+  // Summarize events
+  'tanstack-ai-devtools:summarize:started': {
+    requestId: string
+    model: string
+    inputLength: number
+    timestamp: number
+    clientId?: string
+  }
+  'tanstack-ai-devtools:summarize:completed': {
+    requestId: string
+    model: string
+    inputLength: number
+    outputLength: number
+    duration: number
+    timestamp: number
+  }
+
+  // Chat Client events - from @tanstack/ai-client package
+  'tanstack-ai-devtools:client:created': {
+    clientId: string
+    initialMessageCount: number
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:message-appended': {
+    clientId: string
+    messageId: string
+    role: 'user' | 'assistant' | 'system' | 'tool'
+    contentPreview: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:message-sent': {
+    clientId: string
+    messageId: string
+    content: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:loading-changed': {
+    clientId: string
+    isLoading: boolean
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:error-changed': {
+    clientId: string
+    error: string | null
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:messages-cleared': {
+    clientId: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:reloaded': {
+    clientId: string
+    fromMessageIndex: number
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:stopped': {
+    clientId: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:tool:result-added': {
+    clientId: string
+    toolCallId: string
+    toolName: string
+    output: any
+    state: 'output-available' | 'output-error'
+    timestamp: number
+  }
+  'tanstack-ai-devtools:tool:approval-responded': {
+    clientId: string
+    approvalId: string
+    toolCallId: string
+    approved: boolean
+    timestamp: number
+  }
+  'tanstack-ai-devtools:processor:text-updated': {
+    streamId: string
+    content: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:processor:tool-call-state-changed': {
+    streamId: string
+    toolCallId: string
+    toolName: string
+    state: ToolCallState
+    arguments: any
+    timestamp: number
+  }
+  'tanstack-ai-devtools:processor:tool-result-state-changed': {
+    streamId: string
+    toolCallId: string
+    content: any
+    state: ToolResultState
+    error?: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:assistant-message-updated': {
+    clientId: string
+    messageId: string
+    content: string
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:tool-call-updated': {
+    clientId: string
+    messageId: string
+    toolCallId: string
+    toolName: string
+    state: ToolCallState
+    arguments: any
+    timestamp: number
+  }
+  'tanstack-ai-devtools:client:approval-requested': {
+    clientId: string
+    messageId: string
+    toolCallId: string
+    toolName: string
+    input: any
+    approvalId: string
+    timestamp: number
+  }
+}
+
+// Helper type to strip the prefix at the type level
+type StripPrefix<T extends string> =
+  T extends `tanstack-ai-devtools:${infer Suffix}` ? Suffix : never
+
+// Get all event names without the prefix
+type EventSuffix = StripPrefix<keyof AIDevtoolsEventMap & string>
+
+class AiEventClient extends EventClient<AIDevtoolsEventMap> {
+  private eventTarget: EventTarget
+
+  constructor() {
+    super({
+      pluginId: 'tanstack-ai-devtools',
+    })
+    this.eventTarget = new EventTarget()
+  }
+
+  /**
+   * Subscribe to events using both the parent EventClient and EventTarget API
+   * @param eventSuffix - The event name without the prefix (e.g., "stream:started")
+   * @param handler - The event handler function
+   * @param options - Optional configuration for event subscription
+   * @returns A function to unsubscribe from the event
+   */
+  override on<TSuffix extends EventSuffix>(
+    eventSuffix: TSuffix,
+    handler: (event: {
+      type: `tanstack-ai-devtools:${TSuffix}`
+      payload: AIDevtoolsEventMap[`tanstack-ai-devtools:${TSuffix}`]
+    }) => void,
+    options?: { withEventTarget?: boolean },
+  ): () => void {
+    const parentUnsubscribe = super.on(eventSuffix, handler)
+
+    const withEventTarget = options?.withEventTarget ?? true
+    let eventListener: ((event: Event) => void) | undefined
+
+    if (withEventTarget) {
+      // Create a wrapper to handle CustomEvent for EventTarget
+      eventListener = (event: Event) => {
+        if (event instanceof CustomEvent) {
+          handler({
+            type: `${eventSuffix}` as `tanstack-ai-devtools:${TSuffix}`,
+            payload: event.detail,
+          })
+        }
+      }
+
+      // Add listener to EventTarget
+      this.eventTarget.addEventListener(eventSuffix, eventListener)
+    }
+
+    // Return unsubscribe function that cleans up both subscriptions
+    return () => {
+      parentUnsubscribe()
+      if (withEventTarget && eventListener) {
+        this.eventTarget.removeEventListener(eventSuffix, eventListener)
+      }
+    }
+  }
+
+  /**
+   * Emit an event to both the parent EventClient and the EventTarget
+   * @param eventSuffix - The event name without the prefix (e.g., "stream:started")
+   * @param data - The event data
+   */
+  override emit<TSuffix extends EventSuffix>(
+    eventSuffix: TSuffix,
+    data: AIDevtoolsEventMap[`tanstack-ai-devtools:${TSuffix}`],
+  ): void {
+    super.emit(eventSuffix, data)
+
+    // Always dispatch to EventTarget (for local listeners)
+    const customEvent = new CustomEvent(eventSuffix, {
+      detail: data,
+    })
+    this.eventTarget.dispatchEvent(customEvent)
+  }
+
+  /**
+   * Get the underlying EventTarget for advanced use cases
+   * @returns The EventTarget instance
+   */
+  getEventTarget(): EventTarget {
+    return this.eventTarget
+  }
+}
+
+const aiEventClient = new AiEventClient()
+
+export { aiEventClient }

package/src/index.ts

@@ -0,0 +1,68 @@
+export { chat } from './core/chat'
+export { summarize } from './core/summarize'
+export { embedding } from './core/embedding'
+export {
+  toolDefinition,
+  type ToolDefinition,
+  type ToolDefinitionInstance,
+  type ToolDefinitionConfig,
+  type ServerTool,
+  type ClientTool,
+  type AnyClientTool,
+  type InferToolName,
+  type InferToolInput,
+  type InferToolOutput,
+} from './tools/tool-definition'
+export { convertZodToJsonSchema } from './tools/zod-converter'
+export {
+  toServerSentEventsStream,
+  toStreamResponse,
+} from './utilities/stream-to-response'
+export { BaseAdapter } from './base-adapter'
+export { ToolCallManager } from './tools/tool-calls'
+export {
+  maxIterations,
+  untilFinishReason,
+  combineStrategies,
+} from './utilities/agent-loop-strategies'
+export * from './types'
+export { chatOptions } from './utilities/chat-options'
+export { messages } from './utilities/messages'
+export { aiEventClient } from './event-client'
+
+// Message converters
+export {
+  convertMessagesToModelMessages,
+  uiMessageToModelMessages,
+  modelMessageToUIMessage,
+  modelMessagesToUIMessages,
+  normalizeToUIMessage,
+  generateMessageId,
+} from './message-converters'
+
+// Stream processing (unified for server and client)
+export {
+  StreamProcessor,
+  createReplayStream,
+  ImmediateStrategy,
+  PunctuationStrategy,
+  BatchStrategy,
+  WordBoundaryStrategy,
+  CompositeStrategy,
+  PartialJSONParser,
+  defaultJSONParser,
+  parsePartialJSON,
+} from './stream'
+export type {
+  ChunkStrategy,
+  ChunkRecording,
+  InternalToolCallState,
+  ProcessorResult,
+  ProcessorState,
+  StreamProcessorEvents,
+  StreamProcessorHandlers,
+  StreamProcessorOptions,
+  ToolCallState,
+  ToolResultState,
+  JSONParser,
+} from './stream'