@tanstack/ai 0.58.0 → 0.61.0

package/src/activities/chat/tools/tool-calls.ts

@@ -1,5 +1,6 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
+import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
 import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
 import type { ToolApprovalResolution } from '../../../interrupts'
@@ -8,8 +9,10 @@ import type {
   ContentPart,
   CustomEvent,
   EmitCustomEventOptions,
+  Interrupt,
   ModelMessage,
   RunFinishedEvent,
+  StreamChunk,
   Tool,
   ToolCall,
   ToolCallArgsEvent,
@@ -38,6 +41,25 @@ function safeJsonParse(value: string): unknown {
   }
 }
 
+/** Marks the synthetic tool that runs a subagent. */
+export const SUBAGENT_TOOL = Symbol.for('tanstack.ai.subagentTool')
+
+/** Set on the tool context of a subagent tool. Streams a child chunk live. */
+export const EMIT_STREAM_CHUNK = Symbol.for('tanstack.ai.emitStreamChunk')
+
+/** What a subagent tool's `execute` returns. */
+export interface SubagentToolOutcome {
+  subagentRunId: string
+  text: string
+  error?: string
+  /** Set when the child stopped for outside input. The tool call stays open. */
+  interrupts?: Array<Interrupt>
+}
+
+function isSubagentTool(tool: AnyTool): boolean {
+  return (tool as { [SUBAGENT_TOOL]?: true })[SUBAGENT_TOOL] === true
+}
+
 /**
  * MCP Apps metadata attached to a server tool at discovery (see
  * `@tanstack/ai-mcp` discovery + `MCPManager.discover()`).
@@ -505,6 +527,8 @@ interface ExecuteToolCallsResult {
   needsApproval: Array<ApprovalRequest>
   /** Tools that need client-side execution */
   needsClientExecution: Array<ClientToolRequest>
+  /** Interrupts raised by subagents that run as tools */
+  subagentInterrupts: Array<Interrupt>
 }
 
 /**
@@ -514,8 +538,8 @@ interface ExecuteToolCallsResult {
  */
 async function* executeWithEventPolling<T>(
   executionPromise: Promise<T>,
-  pendingEvents: Array<CustomEvent>,
-): AsyncGenerator<CustomEvent, T, void> {
+  pendingEvents: Array<CustomEvent | StreamChunk>,
+): AsyncGenerator<CustomEvent | StreamChunk, T, void> {
   // Use an object to track mutable state across the async boundary
   const state = { done: false, result: undefined as T }
   const executionWithFlag = executionPromise.then((r) => {
@@ -532,14 +556,14 @@ async function* executeWithEventPolling<T>(
     ])
 
     // Flush any pending events
-    let event: CustomEvent | undefined
+    let event: CustomEvent | StreamChunk | undefined
     while ((event = pendingEvents.shift()) !== undefined) {
       yield event
     }
   }
 
   // Final flush in case events were emitted right at completion
-  let event: CustomEvent | undefined
+  let event: CustomEvent | StreamChunk | undefined
   while ((event = pendingEvents.shift()) !== undefined) {
     yield event
   }
@@ -612,19 +636,59 @@ export async function* executeServerTool<TContext = unknown>(
   toolName: string,
   input: unknown,
   context: ToolExecutionContext<TContext>,
-  pendingEvents: Array<CustomEvent>,
+  pendingEvents: Array<CustomEvent | StreamChunk>,
   results: Array<ToolResult>,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
-): AsyncGenerator<CustomEvent, void, void> {
+  subagentInterrupts?: Array<Interrupt>,
+): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
   const startTime = Date.now()
   try {
     if (!tool.execute) {
       throw new Error(`Tool ${toolName} has no execute() implementation`)
     }
+    const subagent = isSubagentTool(tool)
+    if (subagent) {
+      Object.assign(context, {
+        [EMIT_STREAM_CHUNK]: (chunk: StreamChunk) => pendingEvents.push(chunk),
+      })
+    }
     const executionPromise = Promise.resolve(tool.execute(input, context))
     let result = yield* executeWithEventPolling(executionPromise, pendingEvents)
     const duration = Date.now() - startTime
 
+    if (subagent) {
+      const outcome = result as SubagentToolOutcome
+      if (outcome.interrupts?.length) {
+        // The child waits for outside input. Leave the call open so the
+        // resume run executes it again and continues the same child.
+        subagentInterrupts?.push(...outcome.interrupts)
+        return
+      }
+      const modelResult = outcome.error
+        ? { subagentRunId: outcome.subagentRunId, error: outcome.error }
+        : { subagentRunId: outcome.subagentRunId, result: outcome.text }
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: modelResult,
+        input,
+        output: modelResult,
+        duration,
+        ...(outcome.error ? { state: 'output-error' as const } : {}),
+      })
+      await middlewareHooks?.onAfterToolCall?.({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        duration,
+        ...(outcome.error
+          ? { ok: false as const, error: new Error(outcome.error) }
+          : { ok: true as const, result: modelResult }),
+      })
+      return
+    }
+
     // MCP Apps: if this tool links a ui:// resource, eagerly read it and queue
     // a `ui-resource` CUSTOM event. The MCP source stays live until the run
     // drains (MCPManager's `connection:'close'` policy disposes on completion),
@@ -633,7 +697,7 @@ export async function* executeServerTool<TContext = unknown>(
     await emitUiResourceIfLinked(tool, context)
 
     // Flush remaining events (including any queued ui-resource event)
-    let pendingEvent: CustomEvent | undefined
+    let pendingEvent: CustomEvent | StreamChunk | undefined
     while ((pendingEvent = pendingEvents.shift()) !== undefined) {
       yield pendingEvent
     }
@@ -671,7 +735,7 @@ export async function* executeServerTool<TContext = unknown>(
     const duration = Date.now() - startTime
 
     // Flush remaining events
-    let pendingEvent: CustomEvent | undefined
+    let pendingEvent: CustomEvent | StreamChunk | undefined
     while ((pendingEvent = pendingEvents.shift()) !== undefined) {
       yield pendingEvent
     }
@@ -767,10 +831,11 @@ export async function* executeToolCalls<TContext = unknown>(
   userContext?: TContext,
   abortSignal?: AbortSignal,
   resumeState?: ToolResumeExecutionState,
-): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
+): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
   const needsClientExecution: Array<ClientToolRequest> = []
+  const subagentInterrupts: Array<Interrupt> = []
 
   // Create tool lookup map
   const toolMap = new Map<string, AnyTool>()
@@ -790,6 +855,11 @@ export async function* executeToolCalls<TContext = unknown>(
   })
 
   for (const toolCall of toolCalls) {
+    // Provider-executed tools (Anthropic web_search / web_fetch) already ran
+    // inside the provider response and carry their result on the call's
+    // metadata. They have no execute() and must not become client requests.
+    if (isProviderExecutedToolCall(toolCall)) continue
+
     const tool = toolMap.get(toolCall.function.name)
     const toolName = toolCall.function.name
 
@@ -871,7 +941,7 @@ export async function* executeToolCalls<TContext = unknown>(
     }
 
     // Create a ToolExecutionContext for this tool call with event emission
-    const pendingEvents: Array<CustomEvent> = []
+    const pendingEvents: Array<CustomEvent | StreamChunk> = []
     const context = {
       toolCallId: toolCall.id,
       context: userContext,
@@ -1007,6 +1077,7 @@ export async function* executeToolCalls<TContext = unknown>(
             pendingEvents,
             results,
             middlewareHooks,
+            subagentInterrupts,
           )
         } else {
           // User declined
@@ -1055,8 +1126,9 @@ export async function* executeToolCalls<TContext = unknown>(
       pendingEvents,
       results,
       middlewareHooks,
+      subagentInterrupts,
     )
   }
 
-  return { results, needsApproval, needsClientExecution }
+  return { results, needsApproval, needsClientExecution, subagentInterrupts }
 }

package/src/activities/embed/adapter.ts

@@ -39,6 +39,12 @@ export interface EmbeddingAdapter<
   readonly kind: 'embedding'
   /** Adapter name identifier */
   readonly name: string
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content
+   * sources (provider Files API references). `embed()` rejects file sources
+   * in preflight for adapters that don't declare this.
+   */
+  readonly supportsFileSources?: boolean
   /** The model this adapter is configured for */
   readonly model: TModel
 
@@ -85,6 +91,7 @@ export abstract class BaseEmbeddingAdapter<
 > {
   readonly kind = 'embedding' as const
   abstract readonly name: string
+  readonly supportsFileSources: boolean = false
   readonly model: TModel
 
   // Type-only property - never assigned at runtime

package/src/activities/embed/index.ts

@@ -15,6 +15,7 @@ import {
   runGenerationUsage,
 } from '../middleware/run'
 import { countEmbeddingInputModalities } from '../../utilities/embedding-input'
+import { assertPromptFileSourceSupport } from '../../utilities/content-source'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware/types'
@@ -190,6 +191,10 @@ export async function embed<
   TAdapter extends EmbeddingAdapter<string, any, any, any>,
 >(options: EmbedOptions<TAdapter>): Promise<EmbeddingResult> {
   const { adapter, middleware } = options
+  // Fail closed on `{ type: 'file' }` sources before middleware start. No
+  // embedding adapter consumes file handles today; this matches chat /
+  // generateImage / generateVideo.
+  assertPromptFileSourceSupport(adapter, options.input)
   const model = adapter.model
   const requestId = createId('embedding')
   const startTime = Date.now()

package/src/activities/files/adapter.ts

@@ -0,0 +1,120 @@
+/**
+ * Files Adapter
+ *
+ * Base class and interface for the `files` activity — a provider's native Files
+ * API (upload a media asset once, reference it later by the returned handle
+ * instead of re-sending base64 or a public URL each request).
+ *
+ * Providers with a native surface expose a factory (`openaiFiles()`,
+ * `anthropicFiles()`, `geminiFiles()`, `falFiles()`). `upload` is required;
+ * `get`/`delete` are optional because not every provider has a lifecycle API
+ * (fal's storage is upload-only).
+ */
+
+import { base64ToArrayBuffer } from '@tanstack/ai-utils'
+
+/**
+ * Input to {@link FilesAdapter.upload}. Either a `Blob` (memory-efficient,
+ * preferred for large assets) or base64 `data` plus its `mimeType`.
+ */
+export type FileUploadInput =
+  | Blob
+  | {
+      /** Base64-encoded file bytes. */
+      data: string
+      /** MIME type of the bytes (e.g. `'image/png'`, `'application/pdf'`). */
+      mimeType: string
+      /** Optional filename hint sent to providers that accept one. */
+      filename?: string
+    }
+
+/**
+ * A provider-issued file handle returned by {@link FilesAdapter.upload} /
+ * {@link FilesAdapter.get}. Reference it in a message via a `{ type: 'file' }`
+ * content source — use `fileSourceFromHandle` to build one.
+ *
+ * `TProvider` carries the issuing provider's name as a literal (`'openai'`,
+ * `'gemini'`, ...) when the handle came from a concrete files adapter, so
+ * cross-provider lifecycle calls (`deleteFile` with a foreign handle) fail at
+ * compile time. It defaults to `string` so wire-deserialized handles still fit.
+ */
+export interface FileHandle<TProvider extends string = string> {
+  /**
+   * Provider handle used for lifecycle operations (`get`/`delete`): the
+   * OpenAI/Anthropic `file_id`, the Gemini file resource name (`files/...`), or
+   * the fal storage URL (fal itself has no lifecycle API — the URL doubles as
+   * the wire reference).
+   */
+  id: string
+  /** The provider that issued the handle (`'openai'`, `'gemini'`, ...). */
+  provider: TProvider
+  /**
+   * The handle's URL form when the provider exposes one (Gemini file URI, fal
+   * storage URL). For providers whose handle is an opaque id (OpenAI,
+   * Anthropic) this is `undefined`.
+   */
+  uri?: string
+  /** MIME type reported by the provider (or echoed from the upload input). */
+  mimeType?: string
+  /** File size in bytes when the provider reports it. */
+  sizeBytes?: number
+  /** Expiry as epoch milliseconds when the handle is scheduled to expire. */
+  expiresAt?: number
+  /** Original filename when the provider reports it. */
+  filename?: string
+}
+
+/**
+ * The `files` adapter contract. `upload` is required; `get`/`delete` are
+ * optional and present only when the provider has a lifecycle API.
+ *
+ * `TName` is the provider name literal (`'openai'`, `'gemini'`, ...); concrete
+ * adapters bind it so the handles they issue carry their provenance in the
+ * type system.
+ */
+export interface FilesAdapter<TName extends string = string> {
+  readonly kind: 'files'
+  readonly name: TName
+  upload: (input: FileUploadInput) => Promise<FileHandle<TName>>
+  get?: (id: string) => Promise<FileHandle<TName>>
+  delete?: (id: string) => Promise<void>
+}
+
+export type AnyFilesAdapter = FilesAdapter<string>
+
+/**
+ * Normalize a {@link FileUploadInput} to a `Blob` (plus best-effort MIME /
+ * filename) so provider adapters can hand it straight to their SDK. A `Blob`
+ * input passes through; base64 `{ data }` is decoded to bytes. Shared so
+ * provider files adapters don't each re-implement the decode.
+ */
+export function normalizeFileUploadInput(input: FileUploadInput): {
+  blob: Blob
+  mimeType?: string
+  filename?: string
+} {
+  if (input instanceof Blob) {
+    return { blob: input, mimeType: input.type || undefined }
+  }
+  const bytes = base64ToArrayBuffer(input.data)
+  return {
+    blob: new Blob([bytes], { type: input.mimeType }),
+    mimeType: input.mimeType,
+    filename: input.filename,
+  }
+}
+
+/**
+ * Abstract base for provider files adapters. Subclasses bind `TName` to their
+ * provider literal, set `name`, implement `upload`, and may add `get`/`delete`
+ * (declared on {@link FilesAdapter}, not here, since not every provider has a
+ * lifecycle API).
+ */
+export abstract class BaseFilesAdapter<
+  TName extends string = string,
+> implements FilesAdapter<TName> {
+  readonly kind = 'files' as const
+  abstract readonly name: TName
+
+  abstract upload(input: FileUploadInput): Promise<FileHandle<TName>>
+}

package/src/activities/files/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Files Activity
+ *
+ * Dispatch functions for provider Files APIs. Each takes `{ adapter, ... }` and
+ * calls the adapter method directly (mirrors the other activity dispatchers).
+ * `get`/`delete` are optional on the adapter; the dispatchers throw a clear
+ * error when the selected provider has no lifecycle API.
+ */
+
+import type { ContentPartFileSource } from '../../types'
+import type { FileHandle, FileUploadInput, FilesAdapter } from './adapter'
+
+/** The adapter kind this activity handles */
+export const kind = 'files' as const
+
+/**
+ * Upload a file to a provider's Files API and return its handle. The handle
+ * carries the provider name as a literal type, so passing it to another
+ * provider's lifecycle call is a compile error.
+ *
+ * @example
+ * ```ts
+ * const files = openaiFiles()
+ * const handle = await uploadFile({ adapter: files, input: { data, mimeType: 'image/png' } })
+ * ```
+ */
+export async function uploadFile<TName extends string>(options: {
+  adapter: FilesAdapter<TName> & { kind: typeof kind }
+  input: FileUploadInput
+}): Promise<FileHandle<TName>> {
+  return options.adapter.upload(options.input)
+}
+
+/**
+ * Resolve a lifecycle id from either a raw id string or a {@link FileHandle}
+ * (whose `id` — not its `uri`/wire value — is the lifecycle currency).
+ */
+function toLifecycleId(id: string | FileHandle): string {
+  return typeof id === 'string' ? id : id.id
+}
+
+/**
+ * Fetch metadata for a previously uploaded file. Accepts the handle itself
+ * (preferred — the provider-literal type rejects a foreign provider's handle
+ * at compile time) or its raw lifecycle id.
+ *
+ * @throws if the provider's files adapter has no `get` (e.g. fal storage).
+ */
+export async function getFile<TName extends string>(options: {
+  adapter: FilesAdapter<TName> & { kind: typeof kind }
+  // `NoInfer` so `TName` comes from the adapter only. Otherwise a foreign
+  // handle widens it to a union and the call compiles.
+  id: string | FileHandle<NoInfer<TName>>
+}): Promise<FileHandle<TName>> {
+  const { adapter } = options
+  if (!adapter.get) {
+    throw new Error(
+      `${adapter.name}: files adapter does not support get() — this provider ` +
+        `has no file-retrieval API.`,
+    )
+  }
+  return adapter.get(toLifecycleId(options.id))
+}
+
+/**
+ * Delete a previously uploaded file. Accepts the handle itself (preferred —
+ * the provider-literal type rejects a foreign provider's handle at compile
+ * time) or its raw lifecycle id.
+ *
+ * @throws if the provider's files adapter has no `delete` (e.g. fal storage).
+ */
+export async function deleteFile<TName extends string>(options: {
+  adapter: FilesAdapter<TName> & { kind: typeof kind }
+  id: string | FileHandle<NoInfer<TName>>
+}): Promise<void> {
+  const { adapter } = options
+  if (!adapter.delete) {
+    throw new Error(
+      `${adapter.name}: files adapter does not support delete() — this ` +
+        `provider has no file-deletion API.`,
+    )
+  }
+  return adapter.delete(toLifecycleId(options.id))
+}
+
+/**
+ * Build a `{ type: 'file' }` content source from an uploaded
+ * {@link FileHandle}, for use in a chat message (image/audio/document part
+ * `source`).
+ *
+ * The source's `value` is the handle's wire form: the handle URL when the
+ * provider exposes one (Gemini, fal, Grok), otherwise the opaque id (OpenAI,
+ * Anthropic). `provider` records the issuer, so an adapter for a different
+ * provider rejects the source rather than sending a handle it cannot resolve.
+ *
+ * @example
+ * ```ts
+ * const handle = await uploadFile({ adapter: openaiFiles(), input })
+ * messages.push({ role: 'user', content: [
+ *   { type: 'image', source: fileSourceFromHandle(handle) },
+ * ] })
+ * ```
+ */
+export function fileSourceFromHandle<TProvider extends string>(
+  handle: FileHandle<TProvider>,
+): ContentPartFileSource<TProvider> {
+  return {
+    type: 'file',
+    value: handle.uri ?? handle.id,
+    provider: handle.provider,
+    ...(handle.mimeType ? { mimeType: handle.mimeType } : {}),
+  }
+}

package/src/activities/generateImage/adapter.ts

@@ -51,6 +51,13 @@ export interface ImageAdapter<
   readonly kind: 'image'
   /** Adapter name identifier */
   readonly name: string
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content
+   * sources (provider Files API references). The activity dispatcher rejects
+   * file sources in preflight for adapters that don't declare this, so
+   * adapters written before the file arm existed fail closed.
+   */
+  readonly supportsFileSources?: boolean
   /** The model this adapter is configured for */
   readonly model: TModel
 
@@ -103,6 +110,7 @@ export abstract class BaseImageAdapter<
 > {
   readonly kind = 'image' as const
   abstract readonly name: string
+  readonly supportsFileSources: boolean = false
   readonly model: TModel
 
   // Type-only property - never assigned at runtime

package/src/activities/generateImage/index.ts

@@ -24,6 +24,7 @@ import {
   raceWithAbort,
 } from '../../utilities/activity-abort'
 import { resolveMediaPrompt } from '../../utilities/media-prompt'
+import { assertPromptFileSourceSupport } from '../../utilities/content-source'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware/types'
@@ -248,6 +249,9 @@ export function generateImage<
 >(
   options: ImageActivityOptions<TAdapter, TStream>,
 ): ImageActivityResult<TStream> {
+  // Fail closed before middleware start and before `stream: true` emits
+  // RUN_STARTED, so an unsupported file source never opens a run.
+  assertPromptFileSourceSupport(options.adapter, options.prompt)
   if (options.stream) {
     return streamGenerationResult(
       // Only `runId` is taken from the resolved wire identity. `threadId` stays

package/src/activities/generateVideo/adapter.ts

@@ -74,6 +74,13 @@ export interface VideoAdapter<
   readonly kind: 'video'
   /** Adapter name identifier */
   readonly name: string
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content
+   * sources (provider Files API references). The activity dispatcher rejects
+   * file sources in preflight for adapters that don't declare this, so
+   * adapters written before the file arm existed fail closed.
+   */
+  readonly supportsFileSources?: boolean
   /** The model this adapter is configured for */
   readonly model: TModel
 
@@ -161,6 +168,7 @@ export abstract class BaseVideoAdapter<
 > {
   readonly kind = 'video' as const
   abstract readonly name: string
+  readonly supportsFileSources: boolean = false
   readonly model: TModel
 
   // Type-only property - never assigned at runtime

package/src/activities/generateVideo/index.ts

@@ -12,6 +12,7 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { toRunErrorPayload } from '../error-payload'
 import { resolveDebugOption } from '../../logger/resolve'
+import { assertPromptFileSourceSupport } from '../../utilities/content-source'
 import {
   applyGenerationResultTransforms,
   createGenerationContext,
@@ -452,6 +453,9 @@ async function runCreateVideoJob<
     timeout,
     abortSignal: callerAbortSignal,
   } = options
+  // Fail closed on `{ type: 'file' }` sources for adapters that haven't
+  // declared support (see assertPromptFileSourceSupport).
+  assertPromptFileSourceSupport(adapter, prompt)
   const model = adapter.model
   const requestId = createId('video')
   const startTime = Date.now()
@@ -580,6 +584,9 @@ async function* runStreamingVideoGeneration<
     timeout,
     abortSignal: callerAbortSignal,
   } = options
+  // Fail closed on `{ type: 'file' }` sources for adapters that haven't
+  // declared support (see assertPromptFileSourceSupport).
+  assertPromptFileSourceSupport(adapter, prompt)
   const model = adapter.model
   const runId = options.runId ?? createId('run')
   const requestId = createId('video')

package/src/activities/generateWorld/adapter.ts

@@ -44,10 +44,12 @@ export interface WorldAdapter<
   }
 
   /**
-   * Open a world session from a prompt.
+   * Create a world from a prompt.
    *
-   * Server adapters typically mint a short-lived token and return it with the
+   * Live session adapters mint a short-lived token and return it with the
    * prompt so a browser can connect, set the prompt, and start streaming.
+   * Job adapters start generation and return a world URL (or an operation
+   * id while the job is still running).
    */
   createWorld: (
     options: WorldGenerationOptions<TProviderOptions>,

package/src/activities/generateWorld/index.ts

@@ -1,9 +1,9 @@
 /**
  * World Activity (Experimental)
  *
- * Mints a session token for a live, prompt-steerable world. Unlike
- * generateVideo (a job that finishes with a URL), the browser then connects
- * with the token, sets the prompt, and streams until pause/reset/close.
+ * Live adapters mint a session token for a prompt-steerable world. Job
+ * adapters start generation and return a viewer URL, or an operation id
+ * while the job is still running.
  *
  * @experimental World generation is an experimental feature and may change.
  */
@@ -76,7 +76,7 @@ export interface WorldActivityOptions<
   /** Provider-specific options for world generation */
   modelOptions?: WorldProviderOptions<TAdapter>
   /**
-   * Whether to wrap the token result as StreamChunks for SSE transport.
+   * Whether to wrap the result as StreamChunks for SSE transport.
    * This is not the live video. When false or omitted, returns
    * Promise<WorldGenerationResult>.
    *
@@ -100,7 +100,7 @@ export interface WorldActivityOptions<
   /** Stable run id for correlating this run when persisted. */
   runId?: string
   /**
-   * Maximum duration of the token mint in milliseconds.
+   * Maximum wait for the mint or job poll, in milliseconds.
    * No SDK-wide default. Composed with {@link abortSignal}; the first abort wins.
    */
   timeout?: number
@@ -135,7 +135,8 @@ function createId(prefix: string): string {
 // ===========================
 
 /**
- * World generation activity - opens a live, prompt-steerable world session.
+ * World generation activity. Live adapters mint a session token. Job
+ * adapters return a viewer URL or an in-progress operation id.
  *
  * @example Mint a session token on the server
  * ```ts