@tanstack/ai-octane 0.0.0

package/src/use-mcp-app-bridge.tsrx

@@ -0,0 +1,60 @@
+import { useMemo, useRef } from 'octane'
+import { createMcpAppBridge } from '@tanstack/ai-client'
+import type {
+  CreateMcpAppBridgeOptions,
+  McpAppBridge,
+} from '@tanstack/ai-client'
+
+export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
+
+/**
+ * Octane wrapper around `createMcpAppBridge` that returns a **stable** bridge for
+ * the given `threadId`/`callEndpoint`, while always invoking the latest
+ * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating
+ * the bridge on every render and the stale-closure / `exhaustive-deps` dance
+ * you'd otherwise write by hand:
+ *
+ * ```tsx
+ * const { sendMessage } = useChat({ threadId, connection })
+ * const bridge = useMcpAppBridge({
+ *   threadId,
+ *   callEndpoint: '/api/mcp-apps-call',
+ *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+ * })
+ * // pass `bridge` to <MCPAppResource bridge={bridge} … />
+ * ```
+ *
+ * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or
+ * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`
+ * each render does not churn it.
+ */
+export function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options
+
+  // Latest-value refs so the bridge identity stays stable but its callbacks are
+  // never stale (the bridge calls `.current` at invocation time, not creation).
+  const chatRef = useRef(chat)
+  chatRef.current = chat
+  const onLinkRef = useRef(onLink)
+  onLinkRef.current = onLink
+
+  // Whether a link handler was supplied governs the bridge's link behavior
+  // (forward vs. display-only warn), so it's part of the bridge's identity.
+  const hasOnLink = onLink != null
+
+  return useMemo(
+    () =>
+      createMcpAppBridge({
+        threadId,
+        callEndpoint,
+        fetchImpl,
+        chat: {
+          sendMessage: (content, body) =>
+            chatRef.current.sendMessage(content, body),
+        },
+        onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : undefined,
+      }),
+    [threadId, callEndpoint, fetchImpl, hasOnLink],
+  )
+}

package/src/use-mcp-app-bridge.tsrx.d.ts

@@ -0,0 +1,31 @@
+// Declaration companion generated from use-mcp-app-bridge.tsrx.
+import type {
+  CreateMcpAppBridgeOptions,
+  McpAppBridge,
+} from '@tanstack/ai-client'
+export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
+/**
+ * Octane wrapper around `createMcpAppBridge` that returns a **stable** bridge for
+ * the given `threadId`/`callEndpoint`, while always invoking the latest
+ * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating
+ * the bridge on every render and the stale-closure / `exhaustive-deps` dance
+ * you'd otherwise write by hand:
+ *
+ * ```tsx
+ * const { sendMessage } = useChat({ threadId, connection })
+ * const bridge = useMcpAppBridge({
+ *   threadId,
+ *   callEndpoint: '/api/mcp-apps-call',
+ *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+ * })
+ * // pass `bridge` to <MCPAppResource bridge={bridge} … />
+ * ```
+ *
+ * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or
+ * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`
+ * each render does not churn it.
+ */
+export declare function useMcpAppBridge(
+  options: UseMcpAppBridgeOptions,
+): McpAppBridge

package/src/use-realtime-chat.tsrx

@@ -0,0 +1,307 @@
+import { useCallback, useEffect, useRef, useState } from 'octane'
+import { RealtimeClient } from '@tanstack/ai-client'
+import type {
+  RealtimeMessage,
+  RealtimeMode,
+  RealtimeSessionConfig,
+  RealtimeStatus,
+} from '@tanstack/ai'
+import type {
+  UseRealtimeChatOptions,
+  UseRealtimeChatReturn,
+} from './realtime-types'
+
+// Empty frequency data for when client is not connected
+const emptyFrequencyData = new Uint8Array(128)
+const emptyTimeDomainData = new Uint8Array(128).fill(128)
+
+/**
+ * Octane hook for realtime voice conversations.
+ *
+ * Provides a simple interface for voice-to-voice AI interactions
+ * with support for multiple providers (OpenAI, ElevenLabs, etc.).
+ *
+ * @param options - Configuration options including adapter and callbacks
+ * @returns Hook return value with state and control methods
+ *
+ * @example
+ * ```typescript
+ * import { useRealtimeChat } from '@tanstack/ai-octane'
+ * import { openaiRealtime } from '@tanstack/ai-openai'
+ *
+ * function VoiceChat() {
+ *   const {
+ *     status,
+ *     mode,
+ *     messages,
+ *     connect,
+ *     disconnect,
+ *     inputLevel,
+ *     outputLevel,
+ *   } = useRealtimeChat({
+ *     getToken: () => fetch('/api/realtime-token').then(r => r.json()),
+ *     adapter: openaiRealtime(),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {status}</p>
+ *       <p>Mode: {mode}</p>
+ *       <button onClick={status === 'idle' ? connect : disconnect}>
+ *         {status === 'idle' ? 'Start' : 'Stop'}
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useRealtimeChat(
+  options: UseRealtimeChatOptions,
+): UseRealtimeChatReturn {
+  // State
+  const [status, setStatus] = useState<RealtimeStatus>('idle')
+  const [mode, setMode] = useState<RealtimeMode>('idle')
+  const [messages, setMessages] = useState<Array<RealtimeMessage>>([])
+  const [pendingUserTranscript, setPendingUserTranscript] = useState<
+    string | null
+  >(null)
+  const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState<
+    string | null
+  >(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [inputLevel, setInputLevel] = useState(0)
+  const [outputLevel, setOutputLevel] = useState(0)
+
+  // Refs
+  const clientRef = useRef<RealtimeClient | null>(null)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const animationFrameRef = useRef<number | null>(null)
+
+  // Create client instance - use ref to ensure we reuse the same instance
+  // This handles React StrictMode double-rendering
+  if (!clientRef.current) {
+    // Each optional source field is spread conditionally because the
+    // `RealtimeClientOptions` target declares strict optionals
+    // (`field?: T`) and `exactOptionalPropertyTypes` rejects passing
+    // `undefined` for absent values.
+    const initial = optionsRef.current
+    clientRef.current = new RealtimeClient({
+      // OCTANE DIVERGENCE: upstream captures the first transport callbacks.
+      // Ref-backed delegates keep the client stable while reconnects and token
+      // refreshes observe the latest render's authentication and adapter.
+      getToken: () => optionsRef.current.getToken(),
+      adapter: {
+        get provider() {
+          return optionsRef.current.adapter.provider
+        },
+        connect(token, tools) {
+          return optionsRef.current.adapter.connect(token, tools)
+        },
+      },
+      ...(initial.tools !== undefined && { tools: initial.tools }),
+      ...(initial.instructions !== undefined && {
+        instructions: initial.instructions,
+      }),
+      ...(initial.voice !== undefined && { voice: initial.voice }),
+      ...(initial.autoPlayback !== undefined && {
+        autoPlayback: initial.autoPlayback,
+      }),
+      ...(initial.autoCapture !== undefined && {
+        autoCapture: initial.autoCapture,
+      }),
+      ...(initial.vadMode !== undefined && { vadMode: initial.vadMode }),
+      ...(initial.outputModalities !== undefined && {
+        outputModalities: initial.outputModalities,
+      }),
+      ...(initial.temperature !== undefined && {
+        temperature: initial.temperature,
+      }),
+      ...(initial.maxOutputTokens !== undefined && {
+        maxOutputTokens: initial.maxOutputTokens,
+      }),
+      ...(initial.semanticEagerness !== undefined && {
+        semanticEagerness: initial.semanticEagerness,
+      }),
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus)
+        // OCTANE DIVERGENCE: upstream declares this callback but does not
+        // forward status changes beyond its own hook state.
+        optionsRef.current.onStatusChange?.(newStatus)
+      },
+      onModeChange: (newMode) => {
+        setMode(newMode)
+        optionsRef.current.onModeChange?.(newMode)
+      },
+      onMessage: (message) => {
+        setMessages((prev) => [...prev, message])
+        optionsRef.current.onMessage?.(message)
+      },
+      onUsage: (usage) => {
+        optionsRef.current.onUsage?.(usage)
+      },
+      onGoAway: (timeLeft) => {
+        optionsRef.current.onGoAway?.(timeLeft)
+      },
+      onError: (err) => {
+        setError(err)
+        optionsRef.current.onError?.(err)
+      },
+      onConnect: () => {
+        setError(null)
+        optionsRef.current.onConnect?.()
+      },
+      onDisconnect: () => {
+        optionsRef.current.onDisconnect?.()
+      },
+      onInterrupted: () => {
+        setPendingAssistantTranscript(null)
+        optionsRef.current.onInterrupted?.()
+      },
+    })
+
+    // Subscribe to state changes for transcripts
+    clientRef.current.onStateChange((state) => {
+      setPendingUserTranscript(state.pendingUserTranscript)
+      setPendingAssistantTranscript(state.pendingAssistantTranscript)
+    })
+  }
+
+  const client = clientRef.current
+
+  // Audio level animation loop
+  useEffect(() => {
+    function updateLevels() {
+      if (clientRef.current?.audio) {
+        setInputLevel(clientRef.current.audio.inputLevel)
+        setOutputLevel(clientRef.current.audio.outputLevel)
+      }
+      animationFrameRef.current = requestAnimationFrame(updateLevels)
+    }
+
+    if (status === 'connected') {
+      updateLevels()
+    }
+
+    return () => {
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current)
+        animationFrameRef.current = null
+      }
+    }
+  }, [status])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      clientRef.current?.destroy()
+    }
+  }, [])
+
+  // Connection methods
+  const connect = useCallback(async () => {
+    setError(null)
+    setMessages([])
+    setPendingUserTranscript(null)
+    setPendingAssistantTranscript(null)
+    await client.connect()
+  }, [client])
+
+  const disconnect = useCallback(async () => {
+    await client.disconnect()
+  }, [client])
+
+  // Voice control methods
+  const startListening = useCallback(() => {
+    client.startListening()
+  }, [client])
+
+  const stopListening = useCallback(() => {
+    client.stopListening()
+  }, [client])
+
+  const interrupt = useCallback(() => {
+    client.interrupt()
+  }, [client])
+
+  // Text input
+  const sendText = useCallback(
+    (text: string) => {
+      client.sendText(text)
+    },
+    [client],
+  )
+
+  // Image input
+  const sendImage = useCallback(
+    (imageData: string, mimeType: string) => {
+      client.sendImage(imageData, mimeType)
+    },
+    [client],
+  )
+
+  // Audio visualization
+  const getInputFrequencyData = useCallback(() => {
+    return (
+      clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData
+    )
+  }, [])
+
+  const getOutputFrequencyData = useCallback(() => {
+    return (
+      clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData
+    )
+  }, [])
+
+  const getInputTimeDomainData = useCallback(() => {
+    return (
+      clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData
+    )
+  }, [])
+
+  const getOutputTimeDomainData = useCallback(() => {
+    return (
+      clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData
+    )
+  }, [])
+
+  const updateSession = useCallback((config: RealtimeSessionConfig) => {
+    clientRef.current?.updateSession(config)
+  }, [])
+
+  return {
+    // Connection state
+    status,
+    error,
+    connect,
+    disconnect,
+
+    // Conversation state
+    mode,
+    messages,
+    pendingUserTranscript,
+    pendingAssistantTranscript,
+
+    // Voice control
+    startListening,
+    stopListening,
+    interrupt,
+
+    // Text input
+    sendText,
+
+    // Image input
+    sendImage,
+
+    // Audio visualization
+    inputLevel,
+    outputLevel,
+    getInputFrequencyData,
+    getOutputFrequencyData,
+    getInputTimeDomainData,
+    getOutputTimeDomainData,
+
+    // Session control
+    updateSession,
+  }
+}

package/src/use-realtime-chat.tsrx.d.ts

@@ -0,0 +1,48 @@
+// Declaration companion generated from use-realtime-chat.tsrx.
+import type {
+  UseRealtimeChatOptions,
+  UseRealtimeChatReturn,
+} from './realtime-types'
+/**
+ * Octane hook for realtime voice conversations.
+ *
+ * Provides a simple interface for voice-to-voice AI interactions
+ * with support for multiple providers (OpenAI, ElevenLabs, etc.).
+ *
+ * @param options - Configuration options including adapter and callbacks
+ * @returns Hook return value with state and control methods
+ *
+ * @example
+ * ```typescript
+ * import { useRealtimeChat } from '@tanstack/ai-octane'
+ * import { openaiRealtime } from '@tanstack/ai-openai'
+ *
+ * function VoiceChat() {
+ *   const {
+ *     status,
+ *     mode,
+ *     messages,
+ *     connect,
+ *     disconnect,
+ *     inputLevel,
+ *     outputLevel,
+ *   } = useRealtimeChat({
+ *     getToken: () => fetch('/api/realtime-token').then(r => r.json()),
+ *     adapter: openaiRealtime(),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {status}</p>
+ *       <p>Mode: {mode}</p>
+ *       <button onClick={status === 'idle' ? connect : disconnect}>
+ *         {status === 'idle' ? 'Start' : 'Stop'}
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useRealtimeChat(
+  options: UseRealtimeChatOptions,
+): UseRealtimeChatReturn

package/src/use-summarize.tsrx

@@ -0,0 +1,124 @@
+import { useGeneration } from './use-generation.tsrx'
+import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutputFromReturn,
+  SummarizeGenerateInput,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the useSummarize hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
+ */
+export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function for summarization */
+  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with connect-based adapter requests */
+  body?: Record<string, any>
+  /** Display options for TanStack AI Devtools. */
+  devtools?: AIDevtoolsDisplayOptions
+  /**
+   * Callback when summarization is complete. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: SummarizationResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (connect-based adapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useSummarize hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+  /** Trigger summarization */
+  generate: (input: SummarizeGenerateInput) => Promise<void>
+  /** The summarization result, or null */
+  result: TOutput | null
+  /** Whether summarization is in progress */
+  isLoading: boolean
+  /** Current error, if any */
+  error: Error | undefined
+  /** Current state of the generation */
+  status: GenerationClientState
+  /** Abort the current summarization */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+
+/**
+ * Octane hook for summarizing text using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useSummarize } from '@tanstack/ai-octane'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function Summarizer() {
+ *   const { generate, result, isLoading } = useSummarize({
+ *     connection: fetchServerSentEvents('/api/summarize'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({
+ *         text: 'Long article text...',
+ *         style: 'bullet-points',
+ *         maxLength: 200,
+ *       })}>
+ *         Summarize
+ *       </button>
+ *       {isLoading && <p>Summarizing...</p>}
+ *       {result && <p>{result.summary}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useSummarize<TTransformed = void>(
+  options: Omit<UseSummarizeOptions, 'onResult'> & {
+    onResult?: (result: SummarizationResult) => TTransformed
+  },
+): UseSummarizeReturn<
+  InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
+> {
+  const devtools = {
+    ...options.devtools,
+    // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+    framework: 'octane',
+    hookName: 'useSummarize',
+    outputKind: 'text' as const,
+  }
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
+      ...options,
+      devtools,
+    })
+
+  return {
+    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-summarize.tsrx.d.ts

@@ -0,0 +1,98 @@
+// Declaration companion generated from use-summarize.tsrx.
+import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutputFromReturn,
+  SummarizeGenerateInput,
+} from '@tanstack/ai-client'
+/**
+ * Options for the useSummarize hook.
+ *
+ * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
+ */
+export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function for summarization */
+  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with connect-based adapter requests */
+  body?: Record<string, any>
+  /** Display options for TanStack AI Devtools. */
+  devtools?: AIDevtoolsDisplayOptions
+  /**
+   * Callback when summarization is complete. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: SummarizationResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (connect-based adapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+/**
+ * Return type for the useSummarize hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+  /** Trigger summarization */
+  generate: (input: SummarizeGenerateInput) => Promise<void>
+  /** The summarization result, or null */
+  result: TOutput | null
+  /** Whether summarization is in progress */
+  isLoading: boolean
+  /** Current error, if any */
+  error: Error | undefined
+  /** Current state of the generation */
+  status: GenerationClientState
+  /** Abort the current summarization */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+/**
+ * Octane hook for summarizing text using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useSummarize } from '@tanstack/ai-octane'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function Summarizer() {
+ *   const { generate, result, isLoading } = useSummarize({
+ *     connection: fetchServerSentEvents('/api/summarize'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({
+ *         text: 'Long article text...',
+ *         style: 'bullet-points',
+ *         maxLength: 200,
+ *       })}>
+ *         Summarize
+ *       </button>
+ *       {isLoading && <p>Summarizing...</p>}
+ *       {result && <p>{result.summary}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useSummarize<TTransformed = void>(
+  options: Omit<UseSummarizeOptions, 'onResult'> & {
+    onResult?: (result: SummarizationResult) => TTransformed
+  },
+): UseSummarizeReturn<
+  InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
+>