@tanstack/ai 0.39.1 → 0.41.0

package/src/realtime/types.ts

@@ -4,6 +4,8 @@ import type { AnyClientTool } from '../activities/chat/tools/tool-definition'
 // Token Types
 // ============================================================================
 
+import type { UsageInfo } from '../activities/chat/middleware/types'
+
 /**
  * Voice activity detection configuration
  */
@@ -24,6 +26,7 @@ export interface RealtimeToolConfig {
   name: string
   description: string
   inputSchema?: Record<string, any>
+  outputSchema?: Record<string, any>
 }
 
 /**
@@ -246,6 +249,8 @@ export type RealtimeEvent =
   | 'message_complete'
   | 'interrupted'
   | 'error'
+  | 'go_away' // Event that signals that the current connection will soon be terminated
+  | 'usage'
 
 /**
  * Event payloads for realtime events
@@ -263,6 +268,8 @@ export interface RealtimeEventPayloads {
   message_complete: { message: RealtimeMessage }
   interrupted: { messageId?: string }
   error: { error: Error }
+  go_away: { timeLeft?: string }
+  usage: UsageInfo
 }
 
 /**
@@ -355,6 +362,8 @@ export interface RealtimeConnection {
   // Session management
   /** Update session configuration */
   updateSession: (config: Partial<RealtimeSessionConfig>) => void
+  /** Update the ephemeral token (e.g. on refresh); provider may reconnect */
+  updateToken?: (token: RealtimeToken) => void
   /** Interrupt the current response */
   interrupt: () => void
 

package/src/types.ts

@@ -372,6 +372,15 @@ export interface ToolCallPart<TMetadata = unknown> {
   id: string
   name: string
   arguments: string // JSON string (may be incomplete)
+  /**
+   * Parsed tool input. Set from the parsed arguments once they are complete
+   * (`state: 'input-complete'` and later). `undefined` while the raw
+   * `arguments` string is still streaming, and may stay `undefined` for a call
+   * that terminates in an error state — the raw `arguments` string is always
+   * available as a fallback. Typed per-tool on the client `ToolCallPart` (see
+   * `@tanstack/ai-client`); `unknown` on this base type.
+   */
+  input?: unknown
   state: ToolCallState
   /** Approval metadata if tool requires user approval */
   approval?: {
@@ -1381,6 +1390,105 @@ export interface UIResourceEvent extends CustomEvent {
   }
 }
 
+// ── Sandbox events ──────────────────────────────────────────────────────────
+export interface SandboxFileCustomEvent extends CustomEvent {
+  name: 'sandbox.file'
+  value: {
+    type: 'create' | 'change' | 'delete'
+    path: string
+    timestamp: number
+  }
+}
+export interface SandboxFileDiffEvent extends CustomEvent {
+  name: 'sandbox.file.diff'
+  value: { path: string; diff: string }
+}
+
+// ── Harness events ──────────────────────────────────────────────────────────
+export interface FileChangedEvent extends CustomEvent {
+  name: 'file.changed'
+  value: { path: string; diff: string }
+}
+export interface SessionIdEvent extends CustomEvent {
+  name: `${string}.session-id`
+  value: { sessionId: string }
+}
+
+// ── Code-mode events ────────────────────────────────────────────────────────
+export interface CodeModeExecutionStartedEvent extends CustomEvent {
+  name: 'code_mode:execution_started'
+  value: { timestamp: number; codeLength: number }
+}
+export interface CodeModeConsoleEvent extends CustomEvent {
+  name: 'code_mode:console'
+  value: {
+    level: 'log' | 'warn' | 'error' | 'info'
+    message: string
+    timestamp: number
+  }
+}
+export interface CodeModeExternalCallEvent extends CustomEvent {
+  name: 'code_mode:external_call'
+  value: { function: string; args: unknown; timestamp: number }
+}
+export interface CodeModeExternalResultEvent extends CustomEvent {
+  name: 'code_mode:external_result'
+  value: { function: string; result: unknown; duration: number }
+}
+export interface CodeModeExternalErrorEvent extends CustomEvent {
+  name: 'code_mode:external_error'
+  value: { function: string; error: string; duration: number }
+}
+export interface CodeModeSkillCallEvent extends CustomEvent {
+  name: 'code_mode:skill_call'
+  value: { skill: string; input: unknown; timestamp: number }
+}
+export interface CodeModeSkillResultEvent extends CustomEvent {
+  name: 'code_mode:skill_result'
+  value: { skill: string; result: unknown; duration: number; timestamp: number }
+}
+export interface CodeModeSkillErrorEvent extends CustomEvent {
+  name: 'code_mode:skill_error'
+  value: { skill: string; error: string; duration: number; timestamp: number }
+}
+export interface SkillRegisteredEvent extends CustomEvent {
+  name: 'skill:registered'
+  value: { id: string; name: string; description: string; timestamp: number }
+}
+
+/**
+ * Every CUSTOM event TanStack AI itself emits, as a discriminated union on
+ * `name`. User-emitted custom events (via `emitCustomEvent` with a custom name)
+ * are intentionally absent — they still flow at runtime.
+ */
+export type KnownCustomEvent =
+  | SandboxFileCustomEvent
+  | SandboxFileDiffEvent
+  | FileChangedEvent
+  | SessionIdEvent
+  | CodeModeExecutionStartedEvent
+  | CodeModeConsoleEvent
+  | CodeModeExternalCallEvent
+  | CodeModeExternalResultEvent
+  | CodeModeExternalErrorEvent
+  | CodeModeSkillCallEvent
+  | CodeModeSkillResultEvent
+  | CodeModeSkillErrorEvent
+  | SkillRegisteredEvent
+  | StructuredOutputStartEvent
+  | StructuredOutputCompleteEvent
+  | ApprovalRequestedEvent
+  | ToolInputAvailableEvent
+  | UIResourceEvent
+
+/** The default chat streaming result: standard chunks plus every typed
+ *  framework CUSTOM event, with the `value: any` catch-all excluded so
+ *  literal-`name` narrowing types `value`. User-emitted custom names are typed
+ *  out (still flow at runtime — branch outside the name narrows or cast). */
+export type ChatStream = AsyncIterable<
+  Exclude<StreamChunk, CustomEvent> | KnownCustomEvent
+>
+
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *
@@ -1930,6 +2038,13 @@ export interface TTSResult {
  * Options for audio transcription.
  * These are the common options supported across providers.
  */
+export type TranscriptionResponseFormat =
+  | 'json'
+  | 'text'
+  | 'srt'
+  | 'verbose_json'
+  | 'vtt'
+
 export interface TranscriptionOptions<
   TProviderOptions extends object = object,
 > {
@@ -1942,7 +2057,7 @@ export interface TranscriptionOptions<
   /** An optional prompt to guide the transcription */
   prompt?: string
   /** The format of the transcription output */
-  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  responseFormat?: TranscriptionResponseFormat
   /** Model-specific options for transcription */
   modelOptions?: TProviderOptions
   /**