@tanstack/ai-octane 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @tanstack/ai-octane
+
+[TanStack AI](https://tanstack.com/ai) bindings for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+This package ports the `@tanstack/ai-react` hook surface onto Octane while
+reusing `@tanstack/ai` and `@tanstack/ai-client` unchanged. The runtime export
+surface matches the React adapter, so migration starts by changing the package
+import:
+
+```ts
+// before
+import { useChat } from '@tanstack/ai-react'
+
+// after
+import { useChat } from '@tanstack/ai-octane'
+```
+
+The renderer-bearing hook modules are authored as `.tsrx` and compiled by
+Octane. Matching `.tsrx.d.ts` companions are checked declaration emits of those
+implementations, preserving the complete generic surface for TypeScript
+consumers.
+
+Like Svelte packages shipping `.svelte`, this package publishes **uncompiled
+source**: your Octane plugin (`octane/compiler/vite`, or the rspack / rspeedy
+equivalents) compiles the `.tsrx` modules as part of your build. There is no
+`dist`.
+
+## Install
+
+```bash
+pnpm add @tanstack/ai-octane @tanstack/ai @tanstack/ai-client octane
+```
+
+## Usage
+
+```tsx
+import { useState } from 'octane'
+import { useChat } from '@tanstack/ai-octane'
+
+export function Chat() @{
+  const [input, setInput] = useState('')
+  const chat = useChat({
+    fetcher: myFetcher,
+  })
+
+  <div>
+    @for (const message of chat.messages; key message.id) {
+      <p>
+        {message.role}:
+        {message.parts
+          .filter((part) => part.type === 'text')
+          .map((part) => part.content)
+          .join('')}
+      </p>
+    }
+    <input
+      value={input}
+      onInput={(event) => setInput(event.currentTarget.value)}
+    />
+    <button
+      onClick={() => {
+        void chat.sendMessage(input)
+        setInput('')
+      }}
+    >
+      Send
+    </button>
+  </div>
+}
+```
+
+`useChat` has no input state of its own — hold the text box value in a local
+`useState` and pass it to `sendMessage`. Note the `onInput` handler: Octane
+drives text controls per keystroke through the native `input` event, not a
+synthetic `onChange`.
+
+## API
+
+The adapter includes `useChat`, `useRealtimeChat`, `useMcpAppBridge`,
+`useGeneration`, `useGenerateImage`, `useGenerateAudio`, `useGenerateSpeech`,
+`useGenerateVideo`, `useTranscription`, `useSummarize`, and
+`useAudioRecorder`. It also re-exports all 30 `@tanstack/ai-client`
+convenience helpers and types (`fetchServerSentEvents`, `fetchHttpStream`,
+`xhrServerSentEvents`, `xhrHttpStream`, `stream`, `rpcStream`,
+`createChatClientOptions`, `createMcpAppBridge`, and their associated types)
+unchanged, mirroring the `@tanstack/ai-react` index.
+
+Server rendering through `octane/server` is supported. `useChat` renders its
+initial message snapshot without browser-only setup.
+
+## Divergences from `@tanstack/ai-react`
+
+- The `./mcp-apps` subpath and its `MCPAppResource` component are not ported:
+  they render `AppRenderer` from the React-only `@mcp-ui/client`, which has no
+  Octane equivalent. The framework-agnostic `useMcpAppBridge` hook is ported
+  and available on the main entry.
+- Octane uses native events: text/file/recorder inputs drive updates via
+  `onInput`; there is no synthetic `onChange` layer.
+- Octane has no StrictMode double-invoke and always provides `useId`, so no
+  random-id fallback is needed.
+- The devtools bridge is tagged `framework: 'octane'` (upstream sends
+  `'react'`), so the devtools identify this binding correctly.
+- Realtime reconnects and token refreshes use the latest `getToken` and adapter
+  supplied to the hook; upstream captures the first render's callbacks.
+- The declared realtime `onStatusChange` callback is invoked alongside the
+  hook's state update; upstream `@tanstack/ai-react` currently drops the
+  external callback.
+- Changing `useChat`'s connection or fetcher updates the active `ChatClient` in
+  place and preserves conversation state.
+
+### Fixed here, still present upstream
+
+Three defects were found during review of the port and fixed rather than
+mirrored. All are documented in [`status.json`](./status.json) and covered by
+tests, and each is tracked upstream so the other adapters can catch up.
+
+- `useAudioRecorder`'s transforming overload requires `onComplete`. Upstream,
+  passing any unrelated option (`useAudioRecorder({ onError })`) matched the
+  transforming overload, inferred `TOnComplete` as `unknown`, and silently
+  collapsed `recording` and `stop()` to `unknown`.
+  ([#1001](https://github.com/TanStack/ai/issues/1001))
+- `useGeneration` spreads caller `devtools` metadata _before_ the hardcoded
+  `framework`/`hookName`, so a caller can't misattribute the binding in the
+  devtools. `ai-react` spreads it after; `ai-vue` and `ai-solid` already order it
+  this way. ([#1002](https://github.com/TanStack/ai/issues/1002))
+- `UseGenerationReturn<TInput, TOutput>` types `generate` as `(input: TInput)`.
+  Upstream declares `UseGenerationReturn<TOutput>` and widens `generate` to
+  `(input: Record<string, any>)`, so narrow or required input fields go
+  unchecked. **This is the one place the public type surface differs in shape
+  from `@tanstack/ai-react`** — the runtime surface is unchanged, so the
+  "change the import" migration still holds.
+  ([#1003](https://github.com/TanStack/ai/issues/1003))
+
+## Status
+
+This binding was developed as `@octanejs/tanstack-ai` in the
+[octanejs/octane](https://github.com/octanejs/octane) repo as a temporary
+stopgap, and moved here — apart from the rename, the only changes are the three
+fixes listed above and the test-helper hardening noted in `status.json`.
+
+Current scope, divergences, and verification state are tracked in
+[`status.json`](./status.json). `useChat` matches the current ChatClient shape
+(`threadId` identity, queue, interrupts, `attach`/`detach`).
+
+The port runs TanStack AI's React adapter tests against Octane across all eleven
+hooks, with no skipped, todo, or expected-failure cases (except the untestable
+auto-resume case noted in `status.json`). An SSR fixture and the upstream
+compile-time type tests are also included.
+
+## License
+
+MIT — contains source derived from
+[TanStack AI](https://github.com/TanStack/ai) (MIT), adapted for Octane.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@tanstack/ai-octane",
+  "version": "0.0.0",
+  "description": "Octane bindings for TanStack AI streaming chat, structured outputs, and media generation.",
+  "author": "Dominic Gannaway",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-octane"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "octane",
+    "chat",
+    "streaming",
+    "tool-calling",
+    "structured-outputs",
+    "media-generation"
+  ],
+  "//": "Like Svelte packages shipping .svelte, this package publishes uncompiled source: the hook modules are .tsrx and are compiled by the consumer's Octane plugin. There is therefore no build/dist and no publint test:build target. The .tsrx.d.ts companions are checked declaration emits, so `tsc` still type-checks the full public surface.",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "//lint": "The .tsrx.d.ts companions are generated declaration emits of the .tsrx implementations, so they are not hand-formatted and are excluded from lint rather than edited in place (a regeneration would undo any fix).",
+  "dependencies": {
+    "@tanstack/ai-client": "0.25.1"
+  },
+  "peerDependencies": {
+    "octane": "^0.1.17",
+    "@tanstack/ai": "^0.47.2"
+  },
+  "devDependencies": {
+    "@octanejs/testing-library": "0.1.14",
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "happy-dom": "^20.11.2",
+    "octane": "0.1.17",
+    "vite": "^8.2.1",
+    "zod": "^4.2.0",
+    "@tanstack/ai": "0.47.2"
+  },
+  "scripts": {
+    "lint:fix": "oxlint src --type-aware --ignore-pattern '**/*.tsrx.d.ts' --fix",
+    "test:oxlint": "oxlint src --type-aware --ignore-pattern '**/*.tsrx.d.ts'",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc && tsc -p typetests/tsconfig.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+export { useChat } from './use-chat.tsrx'
+export { useRealtimeChat } from './use-realtime-chat.tsrx'
+export { useMcpAppBridge } from './use-mcp-app-bridge.tsrx'
+export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge.tsrx'
+export type {
+  DeepPartial,
+  UseChatOptions,
+  UseChatReturn,
+  UIMessage,
+  ChatRequestBody,
+  QueuedMessage,
+  SendMessageOptions,
+  WhenBusy,
+  QueueConfig,
+  QueueStrategy,
+  QueueOption,
+} from './types'
+export type {
+  UseRealtimeChatOptions,
+  UseRealtimeChatReturn,
+} from './realtime-types'
+
+export { useGeneration } from './use-generation.tsrx'
+export type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation.tsrx'
+export { useGenerateImage } from './use-generate-image.tsrx'
+export type {
+  UseGenerateImageOptions,
+  UseGenerateImageReturn,
+} from './use-generate-image.tsrx'
+export { useGenerateAudio } from './use-generate-audio.tsrx'
+export type {
+  UseGenerateAudioOptions,
+  UseGenerateAudioReturn,
+} from './use-generate-audio.tsrx'
+export { useGenerateSpeech } from './use-generate-speech.tsrx'
+export type {
+  UseGenerateSpeechOptions,
+  UseGenerateSpeechReturn,
+} from './use-generate-speech.tsrx'
+export { useTranscription } from './use-transcription.tsrx'
+export type {
+  UseTranscriptionOptions,
+  UseTranscriptionReturn,
+} from './use-transcription.tsrx'
+export { useSummarize } from './use-summarize.tsrx'
+export type {
+  UseSummarizeOptions,
+  UseSummarizeReturn,
+} from './use-summarize.tsrx'
+export { useGenerateVideo } from './use-generate-video.tsrx'
+export type {
+  UseGenerateVideoOptions,
+  UseGenerateVideoReturn,
+} from './use-generate-video.tsrx'
+export { useAudioRecorder } from './use-audio-recorder.tsrx'
+export type {
+  UseAudioRecorderOptions,
+  UseAudioRecorderReturn,
+} from './use-audio-recorder.tsrx'
+
+// Re-export from ai-client for convenience (mirror upstream index.ts)
+export {
+  fetchServerSentEvents,
+  fetchHttpStream,
+  xhrServerSentEvents,
+  xhrHttpStream,
+  stream,
+  rpcStream,
+  createChatClientOptions,
+  createMcpAppBridge,
+  type McpAppBridge,
+  type CreateMcpAppBridgeOptions,
+  type ChatFetcher,
+  type ChatFetcherInput,
+  type ChatFetcherOptions,
+  type ConnectionAdapter,
+  type ConnectConnectionAdapter,
+  type SubscribeConnectionAdapter,
+  type RunAgentInputContext,
+  type FetchConnectionOptions,
+  type XhrConnectionOptions,
+  type InferChatMessages,
+  type GenerationClientState,
+  type ImageGenerateInput,
+  type AudioGenerateInput,
+  type SpeechGenerateInput,
+  type TranscriptionGenerateInput,
+  type SummarizeGenerateInput,
+  type VideoGenerateInput,
+  type VideoGenerateResult,
+  type VideoStatusInfo,
+} from '@tanstack/ai-client'

package/src/realtime-types.ts

@@ -0,0 +1,146 @@
+import type {
+  AnyClientTool,
+  RealtimeMessage,
+  RealtimeMode,
+  RealtimeSessionConfig,
+  RealtimeStatus,
+  RealtimeToken,
+  UsageInfo,
+} from '@tanstack/ai'
+import type { RealtimeAdapter } from '@tanstack/ai-client'
+
+/**
+ * Options for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatOptions {
+  /**
+   * Function to fetch a realtime token from the server.
+   * Called on connect and when token needs refresh.
+   */
+  getToken: () => Promise<RealtimeToken>
+
+  /**
+   * The realtime adapter to use (e.g., openaiRealtime())
+   */
+  adapter: RealtimeAdapter
+
+  /**
+   * Client-side tools with execution logic
+   */
+  tools?: ReadonlyArray<AnyClientTool>
+
+  /**
+   * Auto-play assistant audio (default: true)
+   */
+  autoPlayback?: boolean
+
+  /**
+   * Request microphone access on connect (default: true)
+   */
+  autoCapture?: boolean
+
+  /**
+   * System instructions for the assistant
+   */
+  instructions?: string
+
+  /**
+   * Voice to use for audio output
+   */
+  voice?: string
+
+  /**
+   * Voice activity detection mode (default: 'server')
+   */
+  vadMode?: 'server' | 'semantic' | 'manual'
+
+  /**
+   * Output modalities for responses (e.g., ['audio', 'text'])
+   */
+  outputModalities?: Array<'audio' | 'text'>
+
+  /**
+   * Temperature for generation (provider-specific range)
+   */
+  temperature?: number
+
+  /**
+   * Maximum number of tokens in a response
+   */
+  maxOutputTokens?: number | 'inf'
+
+  /**
+   * Eagerness level for semantic VAD ('low', 'medium', 'high')
+   */
+  semanticEagerness?: 'low' | 'medium' | 'high'
+
+  // Callbacks
+  onConnect?: () => void
+  onDisconnect?: () => void
+  onError?: (error: Error) => void
+  onMessage?: (message: RealtimeMessage) => void
+  onModeChange?: (mode: RealtimeMode) => void
+  onInterrupted?: () => void
+  onUsage?: (usage: UsageInfo) => void
+  onGoAway?: (timeLeft?: string) => void
+  onStatusChange?: (status: RealtimeStatus) => void
+}
+
+/**
+ * Return type for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatReturn {
+  // Connection state
+  /** Current connection status */
+  status: RealtimeStatus
+  /** Current error, if any */
+  error: Error | null
+  /** Connect to the realtime session */
+  connect: () => Promise<void>
+  /** Disconnect from the realtime session */
+  disconnect: () => Promise<void>
+
+  // Conversation state
+  /** Current mode (idle, listening, thinking, speaking) */
+  mode: RealtimeMode
+  /** Conversation messages */
+  messages: Array<RealtimeMessage>
+  /** User transcript while speaking (before finalized) */
+  pendingUserTranscript: string | null
+  /** Assistant transcript while speaking (before finalized) */
+  pendingAssistantTranscript: string | null
+
+  // Voice control
+  /** Start listening for voice input (manual VAD mode) */
+  startListening: () => void
+  /** Stop listening for voice input (manual VAD mode) */
+  stopListening: () => void
+  /** Interrupt the current assistant response */
+  interrupt: () => void
+
+  // Text input
+  /** Send a text message instead of voice */
+  sendText: (text: string) => void
+
+  // Image input
+  /** Send an image to the conversation */
+  sendImage: (imageData: string, mimeType: string) => void
+
+  // Audio visualization (0-1 normalized)
+  /** Current input (microphone) volume level */
+  inputLevel: number
+  /** Current output (speaker) volume level */
+  outputLevel: number
+  /** Get frequency data for input audio visualization */
+  getInputFrequencyData: () => Uint8Array
+  /** Get frequency data for output audio visualization */
+  getOutputFrequencyData: () => Uint8Array
+  /** Get time domain data for input waveform */
+  getInputTimeDomainData: () => Uint8Array
+  /** Get time domain data for output waveform */
+  getOutputTimeDomainData: () => Uint8Array
+
+  // Session control
+  /** Update the active session and persist the configuration for reconnects. */
+  updateSession: (config: RealtimeSessionConfig) => void
+}