@tanstack/ai 0.58.0 → 0.61.0

package/src/activities/index.ts

@@ -27,6 +27,7 @@ import type { AnyRerankAdapter } from './rerank/adapter'
 import type { AnyEvaluateAdapter } from './evaluate/adapter'
 import type { AnyWorldAdapter } from './generateWorld/adapter'
 import type { AnyLiveVideoAdapter } from './generateLiveVideo/adapter'
+import type { AnyFilesAdapter } from './files/adapter'
 
 // ===========================
 // Chat Activity
@@ -39,6 +40,21 @@ export {
   type TextActivityResult,
 } from './chat/index'
 
+export {
+  defineAgent,
+  type DefinedAgent,
+  type SubagentChoiceOptions,
+  type SubagentRunContext,
+} from './chat/agents/define-agent'
+export { subagentRoute, type SubagentRouteOptions } from './chat/agents/route'
+export type {
+  SubagentOrder,
+  SubagentRouterPick,
+  SubagentRouterPlan,
+  SubagentStep,
+  SubagentStepsPlan,
+} from './chat/agents/spawn'
+
 export {
   BaseTextAdapter,
   type AnyTextAdapter,
@@ -315,11 +331,32 @@ export {
   type AnyLiveVideoAdapter,
 } from './generateLiveVideo/adapter'
 
+// ===========================
+// Files Activity
+// ===========================
+
+export {
+  kind as filesKind,
+  uploadFile,
+  getFile,
+  deleteFile,
+  fileSourceFromHandle,
+} from './files/index'
+
+export {
+  BaseFilesAdapter,
+  normalizeFileUploadInput,
+  type FilesAdapter,
+  type AnyFilesAdapter,
+  type FileHandle,
+  type FileUploadInput,
+} from './files/adapter'
+
 // ===========================
 // Adapter Union Types
 // ===========================
 
-/** Union of all adapter types that can be passed to chat() */
+/** Union of all adapter types across every activity kind */
 export type AIAdapter =
   | AnyTextAdapter
   | AnySummarizeAdapter
@@ -334,6 +371,7 @@ export type AIAdapter =
   | AnyEvaluateAdapter
   | AnyWorldAdapter
   | AnyLiveVideoAdapter
+  | AnyFilesAdapter
 
 /** Union type of all adapter kinds */
 export type AdapterKind =
@@ -350,3 +388,4 @@ export type AdapterKind =
   | 'evaluate'
   | 'world'
   | 'liveVideo'
+  | 'files'

package/src/activities/summarize/chat-stream-summarize.ts

@@ -65,6 +65,8 @@ function throwRunError(
  * `SummarizationOptions<TProviderOptions>` on the wrapper itself.
  */
 export interface ChatStreamCapable {
+  /** Native token-limit option for adapters whose provider name is user-defined. */
+  readonly maxTokensKey?: string
   chatStream: (options: TextOptions<any>) => AsyncIterable<AdapterYieldChunk>
 }
 
@@ -151,8 +153,8 @@ function applyDefaultTemperature(
 
 /**
  * Resolve `maxLength` to the provider-native max-output-tokens key for the
- * given summarize-adapter `name` (this wrapper's OWN `name`, not the wrapped
- * text adapter's) and merge it into a working copy of the caller's
+ * wrapped text adapter's explicit key, falling back to this wrapper's `name`,
+ * and merge it into a working copy of the caller's
  * `modelOptions`. The caller always wins: if they already set any recognised
  * token-limit key (flat or, for Ollama, nested `options.num_predict`), the
  * default is left untouched. Unknown/unrecognised adapter names fall back to
@@ -172,10 +174,11 @@ function applyMaxLength(
   adapterName: string,
   maxLength: number,
   modelOptions: Record<string, unknown>,
+  maxTokensKey?: string,
 ): Record<string, unknown> {
   const merged: Record<string, unknown> = { ...modelOptions }
 
-  if (adapterName === 'ollama') {
+  if (adapterName === 'ollama' && maxTokensKey === undefined) {
     // Honor a caller-set limit in either shape: a recognised flat key (e.g.
     // left over from a migration) or the nested `options.num_predict`.
     const callerSetFlatLimit = KNOWN_MAX_TOKENS_KEYS.some(
@@ -195,12 +198,12 @@ function applyMaxLength(
     return merged
   }
 
-  const key = MAX_TOKENS_KEY_BY_ADAPTER[adapterName]
+  const key = maxTokensKey ?? MAX_TOKENS_KEY_BY_ADAPTER[adapterName]
   if (key === undefined) return merged
 
-  const callerSetLimit = KNOWN_MAX_TOKENS_KEYS.some(
-    (k) => typeof merged[k] === 'number',
-  )
+  const callerSetLimit =
+    typeof merged[key] === 'number' ||
+    KNOWN_MAX_TOKENS_KEYS.some((k) => typeof merged[k] === 'number')
   if (callerSetLimit) return merged
 
   merged[key] = maxLength
@@ -372,17 +375,24 @@ export class ChatStreamSummarizeAdapter<
     working = applyDefaultTemperature(this.name, 0.3, working)
     // `maxLength` must reach the wire under the provider-native token key (it
     // differs per provider, and no adapter reads a generic `maxTokens`).
-    // Resolve it from this summarize adapter's `name` (the constructor arg,
-    // not the wrapped text adapter's name), never overriding a caller-supplied
-    // token limit.
+    // Prefer the wrapped adapter's explicit key, then this wrapper's name,
+    // never overriding a caller-supplied token limit.
     if (options.maxLength !== undefined) {
-      if (!isKnownMaxTokensAdapter(this.name)) {
+      if (
+        this.textAdapter.maxTokensKey === undefined &&
+        !isKnownMaxTokensAdapter(this.name)
+      ) {
         options.logger.warn(
           `summarize: maxLength=${options.maxLength} could not be mapped to a provider token key for adapter name "${this.name}" — it was dropped from modelOptions (the prompt still asks the model to stay under it). Construct ChatStreamSummarizeAdapter with a recognised provider name to forward the cap.`,
           { provider: this.name },
         )
       }
-      working = applyMaxLength(this.name, options.maxLength, working)
+      working = applyMaxLength(
+        this.name,
+        options.maxLength,
+        working,
+        this.textAdapter.maxTokensKey,
+      )
     }
     const modelOptions = working as TProviderOptions
 

package/src/client.ts

@@ -224,41 +224,25 @@ export async function generationParamsFromRequest<TKind extends GenerationKind>(
   return generationParamsFromBody(kind, body)
 }
 
-export enum EventType {
-  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',
-  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',
-  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',
-  TEXT_MESSAGE_CHUNK = 'TEXT_MESSAGE_CHUNK',
-  TOOL_CALL_START = 'TOOL_CALL_START',
-  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',
-  TOOL_CALL_END = 'TOOL_CALL_END',
-  TOOL_CALL_CHUNK = 'TOOL_CALL_CHUNK',
-  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',
-  THINKING_START = 'THINKING_START',
-  THINKING_END = 'THINKING_END',
-  THINKING_TEXT_MESSAGE_START = 'THINKING_TEXT_MESSAGE_START',
-  THINKING_TEXT_MESSAGE_CONTENT = 'THINKING_TEXT_MESSAGE_CONTENT',
-  THINKING_TEXT_MESSAGE_END = 'THINKING_TEXT_MESSAGE_END',
-  STATE_SNAPSHOT = 'STATE_SNAPSHOT',
-  STATE_DELTA = 'STATE_DELTA',
-  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',
-  ACTIVITY_SNAPSHOT = 'ACTIVITY_SNAPSHOT',
-  ACTIVITY_DELTA = 'ACTIVITY_DELTA',
-  RAW = 'RAW',
-  CUSTOM = 'CUSTOM',
-  RUN_STARTED = 'RUN_STARTED',
-  RUN_FINISHED = 'RUN_FINISHED',
-  RUN_ERROR = 'RUN_ERROR',
-  STEP_STARTED = 'STEP_STARTED',
-  STEP_FINISHED = 'STEP_FINISHED',
-  REASONING_START = 'REASONING_START',
-  REASONING_MESSAGE_START = 'REASONING_MESSAGE_START',
-  REASONING_MESSAGE_CONTENT = 'REASONING_MESSAGE_CONTENT',
-  REASONING_MESSAGE_END = 'REASONING_MESSAGE_END',
-  REASONING_MESSAGE_CHUNK = 'REASONING_MESSAGE_CHUNK',
-  REASONING_END = 'REASONING_END',
-  REASONING_ENCRYPTED_VALUE = 'REASONING_ENCRYPTED_VALUE',
-}
+export { EventType } from '@ag-ui/core'
+
+export {
+  defineAgent,
+  type DefinedAgent,
+  type SubagentChoiceOptions,
+  type SubagentRunContext,
+} from './activities/chat/agents/define-agent'
+export {
+  subagentRoute,
+  type SubagentRouteOptions,
+} from './activities/chat/agents/route'
+export type {
+  SubagentOrder,
+  SubagentRouterPick,
+  SubagentRouterPlan,
+  SubagentStep,
+  SubagentStepsPlan,
+} from './activities/chat/agents/spawn'
 
 export {
   toolDefinition,
@@ -345,10 +329,20 @@ export type { AdapterYieldChunk } from './utilities/adapter-yield-chunk'
 export { getChunkRunId, getChunkThreadId } from './utilities/chunk-ids'
 export type { WireMessage } from './utilities/ag-ui-wire'
 
+// A browser client that received an uploaded handle from its server can build
+// the `{ type: 'file' }` content source itself — `fileSourceFromHandle` is a
+// pure object builder, so exporting it here keeps the documented client flow
+// from pulling in the server entry.
+export { fileSourceFromHandle } from './activities/files/index'
+export type { FileHandle } from './activities/files/adapter'
+
 export type {
   AudioPart,
   ContentPart,
   ContentPartDataSource,
+  ContentPartFileSource,
+  SubagentHandleData,
+  SubagentStatus,
   ContentPartSource,
   ContentPartUrlSource,
   CustomEvent,

package/src/index.ts

@@ -18,6 +18,10 @@ export {
   embed,
   generateWorld,
   generateLiveVideo,
+  uploadFile,
+  getFile,
+  deleteFile,
+  fileSourceFromHandle,
 } from './activities/index'
 
 // Create options functions - for pre-defining typed configurations
@@ -70,6 +74,10 @@ export type {
   WorldAdapter,
   AnyLiveVideoAdapter,
   LiveVideoAdapter,
+  FilesAdapter,
+  AnyFilesAdapter,
+  FileHandle,
+  FileUploadInput,
 } from './activities/index'
 
 // Rerank adapter base + types
@@ -78,6 +86,24 @@ export { BaseRerankAdapter } from './activities/rerank/adapter'
 // Evaluate adapter base + types
 export { BaseEvaluateAdapter } from './activities/evaluate/adapter'
 
+export {
+  defineAgent,
+  type DefinedAgent,
+  type SubagentChoiceOptions,
+  type SubagentRunContext,
+} from './activities/chat/agents/define-agent'
+export {
+  subagentRoute,
+  type SubagentRouteOptions,
+} from './activities/chat/agents/route'
+export type {
+  SubagentOrder,
+  SubagentRouterPick,
+  SubagentRouterPlan,
+  SubagentStep,
+  SubagentStepsPlan,
+} from './activities/chat/agents/spawn'
+
 // Tool definition
 export {
   toolDefinition,
@@ -494,6 +520,11 @@ export { generationParamsFromBody, generationParamsFromRequest } from './client'
 
 // AG-UI wire serialization (used internally by @tanstack/ai-client)
 export { uiMessagesToWire } from './utilities/ag-ui-wire'
+export type { SubagentWireInfo } from './utilities/subagent-wire'
+export {
+  subagentHostMessageId,
+  wireSubagentInfo,
+} from './utilities/subagent-wire'
 export { mergeMetadata, withTanstackMetadata } from './utilities/merge-metadata'
 export { fromSpecTokenUsage, toSpecTokenUsage } from './utilities/ag-ui-usage'
 export type { SpecTokenUsage } from './utilities/ag-ui-usage'
@@ -506,6 +537,14 @@ export {
   isContentPartArray,
   normalizeToolResult,
 } from './utilities/tool-result'
+export {
+  assertMessagesFileSourceSupport,
+  assertPromptFileSourceSupport,
+  fileReferenceFor,
+  isFileSource,
+  unsupportedFileSourceError,
+  type FileSourceCapable,
+} from './utilities/content-source'
 
 export {
   getProviderExecutedMetadata,

package/src/middlewares/content-guard.ts

@@ -3,6 +3,7 @@ import type {
   ChatMiddlewareContext,
 } from '../activities/chat/middleware/types'
 import type { StreamChunk } from '../types'
+import type { AdapterYieldChunk } from '../utilities/adapter-yield-chunk'
 
 /**
  * A content guard rule — either a regex pattern with replacement, or a transform function.
@@ -142,11 +143,12 @@ function createDeltaStrategy(
 
       if (blockOnMatch) return null // drop chunk
 
-      // Strip out the previous `content` field by destructuring it away — with
-      // `exactOptionalPropertyTypes` we can't assign `content: undefined`
-      // against `content?: string`. The replacement event carries only the
-      // filtered delta.
-      const { content: _strippedContent, ...rest } = chunk
+      // Drop the adapter-era content field; the replacement event carries only
+      // the filtered delta.
+      const { content: _strippedContent, ...rest } = chunk as Extract<
+        AdapterYieldChunk,
+        { type: 'TEXT_MESSAGE_CONTENT' }
+      >
       void _strippedContent
       return {
         ...rest,