@tanstack/ai-octane 0.0.0

package/src/types.ts

@@ -0,0 +1,305 @@
+import type {
+  AnyClientTool,
+  InterruptDefinition,
+  InferSchemaType,
+  ModelMessage,
+  RunAgentResumeItem,
+  SchemaInput,
+} from '@tanstack/ai/client'
+import type {
+  AIDevtoolsDisplayOptions,
+  BoundInterrupts,
+  ChatClientOptions,
+  ChatClientState,
+  ResolvableChatInterrupt,
+  ChatInterruptState,
+  ChatRequestBody,
+  ChatResumeState,
+  ClientContextOptionFromTools,
+  ConnectionStatus,
+  DistributedOmit,
+  InferredClientContext,
+  MultimodalContent,
+  QueueConfig,
+  QueueOption,
+  QueueStrategy,
+  QueuedMessage,
+  SendMessageOptions,
+  UIMessage,
+  WhenBusy,
+} from '@tanstack/ai-client'
+
+// Re-export types from ai-client
+export type {
+  ChatRequestBody,
+  MultimodalContent,
+  QueueConfig,
+  QueuedMessage,
+  QueueOption,
+  QueueStrategy,
+  SendMessageOptions,
+  UIMessage,
+  WhenBusy,
+}
+
+/**
+ * Recursive partial — every property and every nested array element is optional.
+ * Used to type the in-flight `partial` value the hook exposes while a structured
+ * output stream is still arriving (the JSON has shape but is incomplete).
+ */
+export type DeepPartial<T> =
+  T extends ReadonlyArray<infer U>
+    ? Array<DeepPartial<U>>
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T
+
+/**
+ * Options for the useChat hook.
+ *
+ * Pass either `connection` or `fetcher` — the XOR is enforced at the type
+ * level via `ChatTransport`.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by hook state:
+ * - `onMessagesChange` - Managed by hook state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by hook state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by hook state (exposed as `error`)
+ * - `onStatusChange` - Managed by hook state (exposed as `status`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * When `outputSchema` is supplied, the hook returns a typed `partial` (live
+ * progressive object, updated from `TEXT_MESSAGE_CONTENT` deltas via
+ * `parsePartialJSON`) and `final` (validated terminal payload from the
+ * `structured-output.complete` event). The schema is used purely for type
+ * inference on the client — server-side validation still runs against the
+ * schema you pass to `chat({ outputSchema })` on the server route.
+ *
+ * Changing `connection` or `fetcher` updates the active ChatClient in place,
+ * preserving its state. Changing `threadId` creates a fresh client.
+ */
+export type UseChatOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+  TContext = InferredClientContext<TTools>,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> = DistributedOmit<
+  ChatClientOptions<TTools, TContext, TInterrupts>,
+  | 'onMessagesChange'
+  | 'onLoadingChange'
+  | 'onErrorChange'
+  | 'onStatusChange'
+  | 'onSubscriptionChange'
+  | 'onConnectionStatusChange'
+  | 'onSessionGeneratingChange'
+  | 'onQueueChange'
+  | 'onResumeStateChange'
+  | 'onRunIdChange'
+  | 'context'
+  | 'devtools'
+> & {
+  /** Display options for TanStack AI Devtools. */
+  devtools?: AIDevtoolsDisplayOptions
+  /**
+   * Opt into mount-time live subscription behavior.
+   * When enabled, the hook subscribes on mount and unsubscribes on unmount.
+   */
+  live?: boolean
+  /**
+   * Standard-schema-compatible schema (Zod, Valibot, ArkType, or a plain JSON
+   * Schema). Used to infer the shape of `partial` and `final` in the return.
+   * The schema is **not** sent to the server — server-side validation runs
+   * against the schema passed to `chat({ outputSchema })` on the server route.
+   */
+  outputSchema?: TSchema
+} & ClientContextOptionFromTools<TTools, TContext>
+
+/**
+ * Discriminated return shape: when `outputSchema` is supplied, the hook adds
+ * typed `partial` / `final` fields; when it is omitted (default), the return
+ * is unchanged.
+ */
+export type UseChatReturn<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> = BaseUseChatReturn<
+  TTools,
+  TSchema extends SchemaInput ? InferSchemaType<TSchema> : unknown,
+  TInterrupts
+> &
+  (TSchema extends SchemaInput
+    ? {
+        /**
+         * Live, progressively-parsed structured output. Updated from
+         * `TEXT_MESSAGE_CONTENT` deltas via `parsePartialJSON` while the stream
+         * is still arriving, and snapped to the validated payload when
+         * `structured-output.complete` fires. Resets on every new run
+         * (`sendMessage` / `reload`).
+         */
+        partial: DeepPartial<InferSchemaType<TSchema>>
+        /**
+         * Final, schema-validated structured output. `null` until the terminal
+         * `structured-output.complete` event arrives. Resets on every new run.
+         */
+        final: InferSchemaType<TSchema> | null
+      }
+    : Record<never, never>)
+
+interface BaseUseChatReturn<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TData = unknown,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> {
+  /**
+   * Current messages in the conversation. When `outputSchema` is supplied,
+   * `messages[i].parts.find(p => p.type === 'structured-output')` is typed
+   * with the schema's inferred shape — `data: T`, `partial: DeepPartial<T>`.
+   */
+  messages: Array<UIMessage<TTools, TData>>
+
+  /**
+   * Send a message and get a response.
+   * Can be a simple string or multimodal content with images, audio, etc.
+   * By default, sends while busy are queued until the run settles successfully
+   * (`queue: 'drop'` restores the old drop-while-busy behavior).
+   * Pass `{ whenBusy }` to override the policy for a single send.
+   */
+  sendMessage: (
+    content: string | MultimodalContent,
+    options?: SendMessageOptions,
+  ) => Promise<void>
+
+  /**
+   * Pending messages queued while the client is busy (streaming, claiming a
+   * send, or draining). Separate from `messages` until they drain.
+   */
+  queue: Array<QueuedMessage>
+
+  /**
+   * Cancel a queued message before it drains. No-op if already sent.
+   */
+  cancelQueued: (id: string) => void
+
+  /**
+   * Append a message to the conversation
+   */
+  append: (message: ModelMessage | UIMessage<TTools, TData>) => Promise<void>
+
+  /**
+   * Add the result of a client-side tool execution
+   */
+  addToolResult: (result: {
+    toolCallId: string
+    tool: string
+    output: any
+    state?: 'output-available' | 'output-error'
+    errorText?: string
+  }) => Promise<void>
+
+  /**
+   * Respond to a tool approval request
+   */
+  addToolApprovalResponse: (response: {
+    id: string // approval.id, not toolCallId
+    approved: boolean
+  }) => Promise<void>
+
+  /**
+   * The id of the run this client has in flight — one it started or rejoined —
+   * or `null` when there is none (including while a run sits paused on an
+   * interrupt, waiting on approval).
+   *
+   * A run is one turn of the conversation, so this changes from turn to turn. A
+   * whole tool loop stays inside one run, while resuming after an interrupt
+   * continues the turn under a new id — so one user message can produce several
+   * run ids. Use it to talk to your own server about that run (cancel it, poll
+   * it, correlate a log line).
+   */
+  runId: string | null
+  interrupts: BoundInterrupts<TTools, TInterrupts>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: BoundInterrupts<TTools, TInterrupts>
+  interruptErrors: ChatInterruptState<TTools, TInterrupts>['interruptErrors']
+  resuming: boolean
+  resolveInterrupts: {
+    (approved: boolean): void
+    (
+      resolver: (
+        interrupt: ResolvableChatInterrupt<TTools, TInterrupts>,
+      ) => undefined,
+    ): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
+  /**
+   * Reload the last assistant message
+   */
+  reload: () => Promise<void>
+
+  /**
+   * Stop the current response generation
+   */
+  stop: () => void
+
+  /**
+   * Whether a response is currently being generated
+   */
+  isLoading: boolean
+
+  /**
+   * Current error, if any
+   */
+  error: Error | undefined
+
+  /**
+   * Current status of the chat client
+   */
+  status: ChatClientState
+
+  /**
+   * Whether the subscription loop is currently active
+   */
+  isSubscribed: boolean
+
+  /**
+   * Current connection lifecycle status
+   */
+  connectionStatus: ConnectionStatus
+
+  /**
+   * Whether the shared session is actively generating.
+   * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+   * Unlike `isLoading` (request-local), this reflects shared generation
+   * activity visible to all subscribers (e.g. across tabs/devices).
+   */
+  sessionGenerating: boolean
+
+  /**
+   * Set messages manually
+   */
+  setMessages: (messages: Array<UIMessage<TTools, TData>>) => void
+
+  /**
+   * Clear all messages
+   */
+  clear: () => void
+}
+
+// Note: createChatClientOptions and InferChatMessages are now in @tanstack/ai-client
+// and re-exported from there for convenience

package/src/use-audio-recorder.tsrx

@@ -0,0 +1,118 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'octane'
+import { AudioRecorder } from '@tanstack/ai-client'
+import type {
+  AudioRecorderOptions,
+  AudioRecording,
+  InferAudioRecordingOutput,
+} from '@tanstack/ai-client'
+
+export type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+  /**
+   * Optional transform applied to the recording when `stop()` resolves. Its
+   * (awaited) return value becomes `recording` and the resolved value of
+   * `stop()`. Return nothing to keep the raw `AudioRecording`.
+   */
+  onComplete?: TOnComplete
+}
+
+export interface UseAudioRecorderReturn<TOutput> {
+  /** Latest recording (transformed if `onComplete` provided), or null. */
+  recording: TOutput | null
+  /** True while actively capturing audio. */
+  isRecording: boolean
+  /** Whether the browser supports recording (getUserMedia + MediaRecorder). */
+  isSupported: boolean
+  /** Acquire the mic and begin recording. */
+  start: () => Promise<void>
+  /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+  stop: () => Promise<TOutput>
+  /** Discard the in-progress recording and release the mic. */
+  cancel: () => void
+}
+
+/**
+ * Octane hook for recording an audio message. The resolved
+ * {@link AudioRecording} carries `.part` (an audio content part for
+ * `useChat.sendMessage`) and `.base64` (for the generation hooks).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if the component
+ * unmounts while a stop is in flight) — handle one channel, not both.
+ *
+ * @example
+ * ```tsx
+ * const { isRecording, start, stop, recording } = useAudioRecorder()
+ * const { sendMessage } = useChat({ connection })
+ * // ...
+ * const rec = await stop()
+ * sendMessage({ content: [rec.part] })
+ * ```
+ */
+// The transforming overload requires `onComplete`. Without that constraint an
+// options object carrying only unrelated keys (`useAudioRecorder({ onError })`)
+// still matches it, `TOnComplete` infers as `unknown`, and `recording`/`stop()`
+// collapse to `unknown` — so passing any option would silently cost you the
+// `AudioRecording` type. Requiring it here sends those calls to the second
+// overload instead.
+export function useAudioRecorder<
+  TOnComplete extends (recording: AudioRecording) => unknown,
+>(
+  options: UseAudioRecorderOptions<TOnComplete> & { onComplete: TOnComplete },
+): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>
+export function useAudioRecorder(
+  options?: UseAudioRecorderOptions<undefined>,
+): UseAudioRecorderReturn<AudioRecording>
+export function useAudioRecorder(
+  options: UseAudioRecorderOptions<(recording: AudioRecording) => unknown> = {},
+): UseAudioRecorderReturn<unknown> {
+  const [isRecording, setIsRecording] = useState(false)
+  const [recording, setRecording] = useState<unknown>(null)
+  // Read the freshest callbacks at fire time without recreating the recorder.
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const recorder = useMemo(
+    () =>
+      new AudioRecorder({
+        ...(options.audio !== undefined && { audio: options.audio }),
+        ...(options.mimeType !== undefined && { mimeType: options.mimeType }),
+        onError: (err) => optionsRef.current.onError?.(err),
+      }),
+    // Recorder config (audio/mimeType) is captured once at mount, matching the
+    // other hooks' create-once pattern.
+    [],
+  )
+
+  useEffect(() => {
+    const unsubscribe = recorder.subscribe((state) => {
+      setIsRecording(state === 'recording')
+    })
+    return () => {
+      unsubscribe()
+      recorder.cancel()
+    }
+  }, [recorder])
+
+  const start = useCallback(() => recorder.start(), [recorder])
+  const stop = useCallback(async () => {
+    const recording = await recorder.stop()
+    const transformed = await optionsRef.current.onComplete?.(recording)
+    // Only `undefined` (returning nothing) falls back to the raw recording, so
+    // a transform that returns null is preserved — matching the inferred type,
+    // which excludes only undefined/void/null from the transform's return.
+    const output = transformed === undefined ? recording : transformed
+    setRecording(() => output)
+    return output
+  }, [recorder])
+  const cancel = useCallback(() => recorder.cancel(), [recorder])
+
+  return {
+    recording,
+    isRecording,
+    // recording is client-only; if SSR'd, gate UI on a mounted flag.
+    isSupported: AudioRecorder.isSupported(),
+    start,
+    stop,
+    cancel,
+  }
+}

package/src/use-audio-recorder.tsrx.d.ts

@@ -0,0 +1,54 @@
+// Declaration companion generated from use-audio-recorder.tsrx.
+import type {
+  AudioRecorderOptions,
+  AudioRecording,
+  InferAudioRecordingOutput,
+} from '@tanstack/ai-client'
+export type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+  /**
+   * Optional transform applied to the recording when `stop()` resolves. Its
+   * (awaited) return value becomes `recording` and the resolved value of
+   * `stop()`. Return nothing to keep the raw `AudioRecording`.
+   */
+  onComplete?: TOnComplete
+}
+export interface UseAudioRecorderReturn<TOutput> {
+  /** Latest recording (transformed if `onComplete` provided), or null. */
+  recording: TOutput | null
+  /** True while actively capturing audio. */
+  isRecording: boolean
+  /** Whether the browser supports recording (getUserMedia + MediaRecorder). */
+  isSupported: boolean
+  /** Acquire the mic and begin recording. */
+  start: () => Promise<void>
+  /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+  stop: () => Promise<TOutput>
+  /** Discard the in-progress recording and release the mic. */
+  cancel: () => void
+}
+/**
+ * Octane hook for recording an audio message. The resolved
+ * {@link AudioRecording} carries `.part` (an audio content part for
+ * `useChat.sendMessage`) and `.base64` (for the generation hooks).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if the component
+ * unmounts while a stop is in flight) — handle one channel, not both.
+ *
+ * @example
+ * ```tsx
+ * const { isRecording, start, stop, recording } = useAudioRecorder()
+ * const { sendMessage } = useChat({ connection })
+ * // ...
+ * const rec = await stop()
+ * sendMessage({ content: [rec.part] })
+ * ```
+ */
+export declare function useAudioRecorder<
+  TOnComplete extends (recording: AudioRecording) => unknown,
+>(
+  options: UseAudioRecorderOptions<TOnComplete> & { onComplete: TOnComplete },
+): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>
+export declare function useAudioRecorder(
+  options?: UseAudioRecorderOptions<undefined>,
+): UseAudioRecorderReturn<AudioRecording>