diff --git a/docs/reference/classes/BaseRerankAdapter.md b/docs/reference/classes/BaseRerankAdapter.md new file mode 100644 index 0000000000..7a3ca9bf3f --- /dev/null +++ b/docs/reference/classes/BaseRerankAdapter.md @@ -0,0 +1,175 @@ +--- +id: BaseRerankAdapter +title: BaseRerankAdapter +--- + +# Abstract Class: BaseRerankAdapter\ + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:63](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L63) + +Abstract base class for rerank adapters. +Extend this class to implement a rerank adapter for a specific provider. + +Generic parameters match RerankAdapter - all pre-resolved by the provider function. + +## Type Parameters + +### TModel + +`TModel` *extends* `string` = `string` + +### TProviderOptions + +`TProviderOptions` *extends* `object` = `Record`\<`string`, `unknown`\> + +## Implements + +- [`RerankAdapter`](../interfaces/RerankAdapter.md)\<`TModel`, `TProviderOptions`\> + +## Constructors + +### Constructor + +```ts +new BaseRerankAdapter(config?, model): BaseRerankAdapter; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:78](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L78) + +#### Parameters + +##### config? + +`RerankAdapterConfig` = `{}` + +##### model + +`TModel` + +#### Returns + +`BaseRerankAdapter`\<`TModel`, `TProviderOptions`\> + +## Properties + +### ~types + +```ts +~types: object; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L72) + +**`Internal`** + +Type-only properties for inference. Not assigned at runtime. + +#### providerOptions + +```ts +providerOptions: TProviderOptions; +``` + +#### Implementation of + +[`RerankAdapter`](../interfaces/RerankAdapter.md).[`~types`](../interfaces/RerankAdapter.md#types) + +*** + +### config + +```ts +protected config: RerankAdapterConfig; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:76](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L76) + +*** + +### kind + +```ts +readonly kind: "rerank"; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:67](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L67) + +Discriminator for adapter kind + +#### Implementation of + +[`RerankAdapter`](../interfaces/RerankAdapter.md).[`kind`](../interfaces/RerankAdapter.md#kind) + +*** + +### model + +```ts +readonly model: TModel; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:69](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L69) + +The model this adapter is configured for + +#### Implementation of + +[`RerankAdapter`](../interfaces/RerankAdapter.md).[`model`](../interfaces/RerankAdapter.md#model) + +*** + +### name + +```ts +abstract readonly name: string; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:68](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L68) + +Adapter name identifier + +#### Implementation of + +[`RerankAdapter`](../interfaces/RerankAdapter.md).[`name`](../interfaces/RerankAdapter.md#name) + +## Methods + +### generateId() + +```ts +protected generateId(): string; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:87](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L87) + +#### Returns + +`string` + +*** + +### rerank() + +```ts +abstract rerank(options): Promise; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:83](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L83) + +Rerank the given (pre-serialized) documents against the query, returning +scored indices into `options.documents`. The activity layer maps these +back to the caller's original documents. + +#### Parameters + +##### options + +[`RerankOptions`](../interfaces/RerankOptions.md)\<`TProviderOptions`\> + +#### Returns + +`Promise`\<[`RerankAdapterResult`](../interfaces/RerankAdapterResult.md)\> + +#### Implementation of + +[`RerankAdapter`](../interfaces/RerankAdapter.md).[`rerank`](../interfaces/RerankAdapter.md#rerank) diff --git a/docs/reference/classes/BatchStrategy.md b/docs/reference/classes/BatchStrategy.md index e61c4bdae9..a5e7666db0 100644 --- a/docs/reference/classes/BatchStrategy.md +++ b/docs/reference/classes/BatchStrategy.md @@ -19,14 +19,14 @@ Useful for reducing UI update frequency ### Constructor ```ts -new BatchStrategy(batchSize): BatchStrategy; +new BatchStrategy(batchSize?): BatchStrategy; ``` Defined in: [packages/ai/src/activities/chat/stream/strategies.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/strategies.ts#L37) #### Parameters -##### batchSize +##### batchSize? `number` = `5` diff --git a/docs/reference/classes/InMemoryRunStore.md b/docs/reference/classes/InMemoryRunStore.md new file mode 100644 index 0000000000..9db7a68295 --- /dev/null +++ b/docs/reference/classes/InMemoryRunStore.md @@ -0,0 +1,232 @@ +--- +id: InMemoryRunStore +title: InMemoryRunStore +--- + +# Class: InMemoryRunStore + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:338](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L338) + +In-memory [RunStore](../interfaces/RunStore.md). Single process only. + +## Implements + +- [`RunStore`](../interfaces/RunStore.md) + +## Constructors + +### Constructor + +```ts +new InMemoryRunStore(): InMemoryRunStore; +``` + +#### Returns + +`InMemoryRunStore` + +## Methods + +### createOrResume() + +```ts +createOrResume(input): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:341](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L341) + +Create a run record, or return the existing one unchanged if `runId` is +already present. + +INVARIANT (idempotency): an existing record is returned **unchanged** and +the passed `threadId`/`startedAt`/`status` are ignored. This is what makes +resuming a run safe. `status` defaults to `'running'` on first creation. + +#### Parameters + +##### input + +`Pick`\<[`RunRecord`](../interfaces/RunRecord.md), `"threadId"` \| `"runId"` \| `"startedAt"`\> & `object` + +#### Returns + +`Promise`\<[`RunRecord`](../interfaces/RunRecord.md)\> + +#### Implementation of + +[`RunStore`](../interfaces/RunStore.md).[`createOrResume`](../interfaces/RunStore.md#createorresume) + +*** + +### findActiveRun() + +```ts +findActiveRun(threadId): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:404](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L404) + +The most recent `'running'` run for `threadId`, or `null` if none is active. + +REQUIRED. This resolves "does this thread have a live run to attach to?" +from the STABLE thread id, which is the durable basis for reconnecting a +client (a reload, or the same thread opened on another device) — independent +of the ephemeral run id, which a single turn may mint several of. When more +than one run is `'running'`, the one with the greatest `startedAt` wins. + +A backend that stubs this to `null` turns reconnect off silently, because +`null` is also the correct answer for an idle thread. A backend with no run +lifecycle at all should omit the whole `runs` store instead — capability +tiers belong at the store level, not the method level. + +#### Parameters + +##### threadId + +`string` + +#### Returns + +`Promise`\<[`RunRecord`](../interfaces/RunRecord.md) \| `null`\> + +#### Implementation of + +[`RunStore`](../interfaces/RunStore.md).[`findActiveRun`](../interfaces/RunStore.md#findactiverun) + +*** + +### get() + +```ts +get(runId): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:379](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L379) + +Current record, or null when unknown. + +#### Parameters + +##### runId + +`string` + +#### Returns + +`Promise`\<[`RunRecord`](../interfaces/RunRecord.md) \| `null`\> + +#### Implementation of + +[`RunStore`](../interfaces/RunStore.md).[`get`](../interfaces/RunStore.md#get) + +*** + +### listByThread() + +```ts +listByThread(threadId): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L383) + +Every run in a conversation, ascending by `startedAt`. OPTIONAL: only +needed to render a thread's past agent activity. Consumers feature-detect. + +#### Parameters + +##### threadId + +`string` + +#### Returns + +`Promise`\<[`RunRecord`](../interfaces/RunRecord.md)[]\> + +#### Implementation of + +[`RunStore`](../interfaces/RunStore.md).[`listByThread`](../interfaces/RunStore.md#listbythread) + +*** + +### listReclaimable() + +```ts +listReclaimable(opts): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:390](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L390) + +Runs that may be reclaimed: ALL THREE of `status === 'running'`, +`detachedSince` is set, and `detachedSince <= now - ttlMs`. The cutoff is +**inclusive** — a run detached at exactly `now - ttlMs` IS reclaimable. + +OPTIONAL: only needed by a reaper. Consumers feature-detect. + +`detachedSince` is populated by `withSandbox`'s detach path (see +[RunRecord.detachedSince](../interfaces/RunRecord.md#detachedsince)). The sweep over the candidates this +surfaces is `@tanstack/ai-sandbox`'s `reapDetachedRuns`: it finalizes a run +whose agent already finished, expires one past its TTL, and reclaims the +sandbox. That is a function, not a scheduler — the application invokes it +(cron, queue, `alarm()`, `waitUntil`) — and a backend that omits this +method cannot be reaped at all. + +#### Parameters + +##### opts + +###### now + +`number` + +###### ttlMs + +`number` + +#### Returns + +`Promise`\<[`RunRecord`](../interfaces/RunRecord.md)[]\> + +#### Implementation of + +[`RunStore`](../interfaces/RunStore.md).[`listReclaimable`](../interfaces/RunStore.md#listreclaimable) + +*** + +### update() + +```ts +update(runId, patch): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:358](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L358) + +Patch a record's mutable fields. + +INVARIANT: updating an unknown `runId` is a **no-op** — it must not throw +and must not create a record. + +#### Parameters + +##### runId + +`string` + +##### patch + +`Partial`\<`Pick`\<[`RunRecord`](../interfaces/RunRecord.md), + \| `"status"` + \| `"finishedAt"` + \| `"error"` + \| `"usage"` + \| `"sandboxKey"` + \| `"detachedSince"` + \| `"cancelRequested"` + \| `"driverEpoch"`\>\> + +#### Returns + +`Promise`\<`void`\> + +#### Implementation of + +[`RunStore`](../interfaces/RunStore.md).[`update`](../interfaces/RunStore.md#update) diff --git a/docs/reference/classes/InterruptResumeValidationError.md b/docs/reference/classes/InterruptResumeValidationError.md new file mode 100644 index 0000000000..abb94ec8a8 --- /dev/null +++ b/docs/reference/classes/InterruptResumeValidationError.md @@ -0,0 +1,64 @@ +--- +id: InterruptResumeValidationError +title: InterruptResumeValidationError +--- + +# Class: InterruptResumeValidationError + +Defined in: [packages/ai/src/interrupt-resume.ts:69](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L69) + +## Extends + +- `Error` + +## Constructors + +### Constructor + +```ts +new InterruptResumeValidationError(errors): InterruptResumeValidationError; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L72) + +#### Parameters + +##### errors + +readonly [`InterruptSubmissionError`](../type-aliases/InterruptSubmissionError.md)[] + +#### Returns + +`InterruptResumeValidationError` + +#### Overrides + +```ts +Error.constructor +``` + +## Properties + +### errors + +```ts +readonly errors: readonly InterruptSubmissionError[]; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L72) + +*** + +### name + +```ts +readonly name: "InterruptResumeValidationError" = 'InterruptResumeValidationError'; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:70](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L70) + +#### Overrides + +```ts +Error.name +``` diff --git a/docs/reference/classes/StreamProcessor.md b/docs/reference/classes/StreamProcessor.md index 9dcea3802f..68afa162cd 100644 --- a/docs/reference/classes/StreamProcessor.md +++ b/docs/reference/classes/StreamProcessor.md @@ -5,7 +5,7 @@ title: StreamProcessor # Class: StreamProcessor -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:156](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L156) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:157](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L157) StreamProcessor - State machine for processing AI response streams @@ -29,14 +29,14 @@ State tracking: ### Constructor ```ts -new StreamProcessor(options): StreamProcessor; +new StreamProcessor(options?): StreamProcessor; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:193](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L193) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:194](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L194) #### Parameters -##### options +##### options? [`StreamProcessorOptions`](../interfaces/StreamProcessorOptions.md) = `{}` @@ -52,7 +52,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:193](https://gi addToolApprovalResponse(approvalId, approved): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:351](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L351) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:352](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L352) Add an approval response (called by client after handling onApprovalRequest) @@ -81,7 +81,7 @@ addToolResult( error?): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:307](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L307) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:308](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L308) Add a tool result (called by client after handling onToolCall) @@ -111,7 +111,7 @@ Add a tool result (called by client after handling onToolCall) addUserMessage(content, id?): UIMessage; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:240](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L240) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:241](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L241) Add a user message to the conversation. Supports both simple string content and multimodal content arrays. @@ -120,9 +120,9 @@ Supports both simple string content and multimodal content arrays. ##### content -The message content (string or array of content parts) +`string` \| [`ContentPart`](../type-aliases/ContentPart.md)[] -`string` | [`ContentPart`](../type-aliases/ContentPart.md)[] +The message content (string or array of content parts) ##### id? @@ -160,7 +160,7 @@ processor.addUserMessage('Hello!', 'custom-id-123') areAllToolsComplete(): boolean; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:382](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L382) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L383) Check if all tool calls in the last assistant message are complete Useful for auto-continue logic @@ -177,7 +177,7 @@ Useful for auto-continue logic clearMessages(): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:454](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L454) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:455](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L455) Clear all messages @@ -193,7 +193,7 @@ Clear all messages finalizeStream(): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2055](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2055) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2239](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2239) Finalize the stream — complete all pending operations. @@ -217,7 +217,7 @@ docs/chat-architecture.md#single-shot-text-response — Finalization step getCurrentAssistantMessageId(): string | null; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:291](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L291) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:292](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L292) Get the current assistant message ID (if one has been created). Returns null if prepareAssistantMessage() was called but no content @@ -235,7 +235,7 @@ has arrived yet. getMessages(): UIMessage[]; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:374](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L374) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:375](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L375) Get current messages @@ -251,7 +251,7 @@ Get current messages getRecording(): ChunkRecording | null; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2219](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2219) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2403](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2403) Get the current recording @@ -267,7 +267,7 @@ Get the current recording getState(): ProcessorState; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2176](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2176) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2360](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2360) Get current processor state (aggregated across all messages) @@ -283,7 +283,7 @@ Get current processor state (aggregated across all messages) prepareAssistantMessage(): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:270](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L270) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:271](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L271) Prepare for a new assistant message stream. Does NOT create the message immediately -- the message is created lazily @@ -303,7 +303,7 @@ auto-continuation produces no content. process(stream): Promise; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:472](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L472) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:473](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L473) Process a stream and emit events through handlers @@ -325,7 +325,7 @@ Process a stream and emit events through handlers processChunk(chunk): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:506](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L506) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:507](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L507) Process a single chunk from the stream. @@ -355,7 +355,7 @@ docs/chat-architecture.md#adapter-contract — Expected event types and ordering removeMessagesAfter(index): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:422](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L422) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:423](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L423) Remove messages after a certain index (for reload/retry) @@ -377,7 +377,7 @@ Remove messages after a certain index (for reload/retry) reset(): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2244](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2244) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2428](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2428) Full reset (including messages) @@ -393,7 +393,7 @@ Full reset (including messages) setMessages(messages): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L212) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:213](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L213) Set the messages array (e.g., from persisted state) @@ -415,7 +415,7 @@ Set the messages array (e.g., from persisted state) startAssistantMessage(messageId?): string; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:279](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L279) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:280](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L280) #### Parameters @@ -440,7 +440,7 @@ an assistant message which can cause empty message flicker. startRecording(): void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2206](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2206) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2390](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2390) Start recording chunks @@ -459,7 +459,7 @@ toModelMessages(): ModelMessage< | null>[]; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:363](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L363) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:364](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L364) Get the conversation as ModelMessages (for sending to LLM) @@ -478,7 +478,7 @@ Get the conversation as ModelMessages (for sending to LLM) static replay(recording, options?): Promise; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2263](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2263) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2447](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2447) Replay a recording through the processor diff --git a/docs/reference/classes/ToolCallManager.md b/docs/reference/classes/ToolCallManager.md index c69eabef22..d90ef1cb16 100644 --- a/docs/reference/classes/ToolCallManager.md +++ b/docs/reference/classes/ToolCallManager.md @@ -5,7 +5,7 @@ title: ToolCallManager # Class: ToolCallManager\ -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:210](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L210) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:211](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L211) Manages tool call accumulation and execution for the chat() method's automatic tool execution loop. @@ -59,13 +59,13 @@ if (manager.hasToolCalls()) { new ToolCallManager(tools): ToolCallManager; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:221](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L221) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:222](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L222) #### Parameters ##### tools -`TToolsOrContext` *extends* readonly [`AnyTool`](../type-aliases/AnyTool.md)[] ? `TToolsOrContext`\<`TToolsOrContext`\> : readonly [`AnyTool`](../type-aliases/AnyTool.md)[] +`TToolsOrContext` *extends* readonly [`AnyTool`](../type-aliases/AnyTool.md)[] ? `TToolsOrContext` : readonly [`AnyTool`](../type-aliases/AnyTool.md)[] #### Returns @@ -79,7 +79,7 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:221](https://gi addToolCallArgsEvent(event): void; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:251](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L251) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:252](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L252) Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI) @@ -101,7 +101,7 @@ Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI) addToolCallStartEvent(event): void; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:232](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L232) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:233](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L233) Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI) @@ -123,7 +123,7 @@ Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI) clear(): void; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:411](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L411) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:422](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L422) Clear the tool calls map for the next iteration @@ -139,7 +139,7 @@ Clear the tool calls map for the next iteration completeToolCall(event): void; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:265](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L265) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:266](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L266) Complete a tool call with its final input Called when TOOL_CALL_END is received @@ -159,13 +159,13 @@ Called when TOOL_CALL_END is received ### executeTools() ```ts -executeTools(finishEvent, ...contextArgs): AsyncGenerator, ModelMessage< | string | ContentPart[] | null>[], void>; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:300](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L300) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:301](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L301) Execute all tool calls and return tool result messages Yields TOOL_CALL_END events for streaming @@ -184,7 +184,7 @@ RUN_FINISHED event from the stream #### Returns -`AsyncGenerator`\<[`ToolCallEndEvent`](../interfaces/ToolCallEndEvent.md), [`ModelMessage`](../interfaces/ModelMessage.md)\< +`AsyncGenerator`\<[`ToolCallEndEvent`](../interfaces/ToolCallEndEvent.md)\<`string`, `unknown`, `unknown`\>, [`ModelMessage`](../interfaces/ModelMessage.md)\< \| `string` \| [`ContentPart`](../type-aliases/ContentPart.md)\<`unknown`, `unknown`, `unknown`, `unknown`, `unknown`\>[] \| `null`\>[], `void`\> @@ -197,7 +197,7 @@ RUN_FINISHED event from the stream getToolCalls(): ToolCall[]; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:289](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L289) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:290](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L290) Get all complete tool calls (filtered for valid ID and name) @@ -213,7 +213,7 @@ Get all complete tool calls (filtered for valid ID and name) hasToolCalls(): boolean; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:282](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L282) +Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:283](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L283) Check if there are any complete tool calls to execute diff --git a/docs/reference/functions/canonicalInterruptJson.md b/docs/reference/functions/canonicalInterruptJson.md new file mode 100644 index 0000000000..99a4804747 --- /dev/null +++ b/docs/reference/functions/canonicalInterruptJson.md @@ -0,0 +1,22 @@ +--- +id: canonicalInterruptJson +title: canonicalInterruptJson +--- + +# Function: canonicalInterruptJson() + +```ts +function canonicalInterruptJson(value): string; +``` + +Defined in: [packages/ai/src/interrupt-serialization.ts:157](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-serialization.ts#L157) + +## Parameters + +### value + +`unknown` + +## Returns + +`string` diff --git a/docs/reference/functions/canonicalizeInterruptResolutions.md b/docs/reference/functions/canonicalizeInterruptResolutions.md new file mode 100644 index 0000000000..322b5f67db --- /dev/null +++ b/docs/reference/functions/canonicalizeInterruptResolutions.md @@ -0,0 +1,40 @@ +--- +id: canonicalizeInterruptResolutions +title: canonicalizeInterruptResolutions +--- + +# Function: canonicalizeInterruptResolutions() + +```ts +function canonicalizeInterruptResolutions(resolutions): object; +``` + +Defined in: [packages/ai/src/interrupts.ts:129](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L129) + +## Parameters + +### resolutions + +readonly `ResumeEntry`[] + +## Returns + +`object` + +### canonicalResolutions + +```ts +canonicalResolutions: string; +``` + +### fingerprint + +```ts +fingerprint: string; +``` + +### resolutions + +```ts +resolutions: readonly ResumeEntry[]; +``` diff --git a/docs/reference/functions/chat.md b/docs/reference/functions/chat.md index 3143a347fe..79e14a653a 100644 --- a/docs/reference/functions/chat.md +++ b/docs/reference/functions/chat.md @@ -6,10 +6,10 @@ title: chat # Function: chat() ```ts -function chat(options): TextActivityResult; +function chat(options): TextActivityResult; ``` -Defined in: [packages/ai/src/activities/chat/index.ts:2794](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/index.ts#L2794) +Defined in: [packages/ai/src/activities/chat/index.ts:3640](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/index.ts#L3640) Text activity - handles agentic text generation, one-shot text generation, and agentic structured output. @@ -36,11 +36,11 @@ This activity supports four modes: ### TTools `TTools` *extends* - \| ( + \| readonly ( \| `Omit`\<[`Tool`](../interfaces/Tool.md)\<`any`, `any`, `any`, `any`\>, `"execute"`\> & `object` & `object` \| [`ProviderTool`](../interfaces/ProviderTool.md)\<`string`, `TAdapter`\[`"~types"`\]\[`"toolCapabilities"`\]\[`number`\]\>)[] \| `undefined` = - \| ( + \| readonly ( \| `Omit`\<[`Tool`](../interfaces/Tool.md)\<`any`, `any`, `any`, `any`\>, `"execute"`\> & `object` & `object` \| [`ProviderTool`](../interfaces/ProviderTool.md)\<`string`, `TAdapter`\[`"~types"`\]\[`"toolCapabilities"`\]\[`number`\]\>)[] \| `undefined` @@ -61,16 +61,18 @@ This activity supports four modes: ## Returns -`TextActivityResult`\<`TSchema`, `TStream`\> +`TextActivityResult`\<`TSchema`, `TStream`, `TTools`\> ## Examples +**Full agentic text (streaming with tools)** + ```ts import { chat } from '@tanstack/ai' import { openaiText } from '@tanstack/ai-openai' for await (const chunk of chat({ - adapter: openaiText('gpt-4o'), + adapter: openaiText('gpt-5.5'), messages: [{ role: 'user', content: 'What is the weather?' }], tools: [weatherTool] })) { @@ -80,29 +82,35 @@ for await (const chunk of chat({ } ``` +**One-shot text (streaming without tools)** + ```ts for await (const chunk of chat({ - adapter: openaiText('gpt-4o'), + adapter: openaiText('gpt-5.5'), messages: [{ role: 'user', content: 'Hello!' }] })) { console.log(chunk) } ``` +**Non-streaming text (stream: false)** + ```ts const text = await chat({ - adapter: openaiText('gpt-4o'), + adapter: openaiText('gpt-5.5'), messages: [{ role: 'user', content: 'Hello!' }], stream: false }) // text is a string with the full response ``` +**Agentic structured output (tools + structured response)** + ```ts import { z } from 'zod' const result = await chat({ - adapter: openaiText('gpt-4o'), + adapter: openaiText('gpt-5.5'), messages: [{ role: 'user', content: 'Research and summarize the topic' }], tools: [researchTool, analyzeTool], outputSchema: z.object({ diff --git a/docs/reference/functions/chatParamsFromRequest.md b/docs/reference/functions/chatParamsFromRequest.md index f2b73ff83c..a8ff25c114 100644 --- a/docs/reference/functions/chatParamsFromRequest.md +++ b/docs/reference/functions/chatParamsFromRequest.md @@ -7,8 +7,8 @@ title: chatParamsFromRequest ```ts function chatParamsFromRequest(req): Promise<{ - aguiContext: object[]; - context: object[]; + aguiContext: Context[]; + context: Context[]; forwardedProps: Record; messages: ( | ModelMessage< @@ -17,6 +17,7 @@ function chatParamsFromRequest(req): Promise<{ | null> | UIMessage)[]; parentRunId?: string; + resume?: ResumeEntry[]; runId: string; state: unknown; threadId: string; @@ -24,7 +25,7 @@ function chatParamsFromRequest(req): Promise<{ }>; ``` -Defined in: [packages/ai/src/utilities/chat-params.ts:134](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L134) +Defined in: [packages/ai/src/utilities/chat-params.ts:286](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L286) Read an HTTP `Request`, parse its JSON body, and validate it as an AG-UI `RunAgentInput` — collapsing the standard `req.json()` + @@ -57,8 +58,8 @@ with try/catch and return the caught Response yourself, or use ## Returns `Promise`\<\{ - `aguiContext`: `object`[]; - `context`: `object`[]; + `aguiContext`: `Context`[]; + `context`: `Context`[]; `forwardedProps`: `Record`\<`string`, `unknown`\>; `messages`: ( \| [`ModelMessage`](../interfaces/ModelMessage.md)\< @@ -67,6 +68,7 @@ with try/catch and return the caught Response yourself, or use \| `null`\> \| [`UIMessage`](../interfaces/UIMessage.md)\<`unknown`\>)[]; `parentRunId?`: `string`; + `resume?`: `ResumeEntry`[]; `runId`: `string`; `state`: `unknown`; `threadId`: `string`; diff --git a/docs/reference/functions/chatParamsFromRequestBody.md b/docs/reference/functions/chatParamsFromRequestBody.md index 0d72db9e73..be3cfb6f58 100644 --- a/docs/reference/functions/chatParamsFromRequestBody.md +++ b/docs/reference/functions/chatParamsFromRequestBody.md @@ -7,8 +7,8 @@ title: chatParamsFromRequestBody ```ts function chatParamsFromRequestBody(body): Promise<{ - aguiContext: object[]; - context: object[]; + aguiContext: Context[]; + context: Context[]; forwardedProps: Record; messages: ( | ModelMessage< @@ -17,6 +17,7 @@ function chatParamsFromRequestBody(body): Promise<{ | null> | UIMessage)[]; parentRunId?: string; + resume?: ResumeEntry[]; runId: string; state: unknown; threadId: string; @@ -24,7 +25,7 @@ function chatParamsFromRequestBody(body): Promise<{ }>; ``` -Defined in: [packages/ai/src/utilities/chat-params.ts:44](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L44) +Defined in: [packages/ai/src/utilities/chat-params.ts:208](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L208) Parse and validate an HTTP request body as an AG-UI `RunAgentInput`. @@ -33,6 +34,9 @@ passing directly to `chat({ messages })`. The existing `convertMessagesToModelMessages` handles AG-UI fan-out dedup and reasoning/activity/developer-role normalization internally. +Validated structurally against the AG-UI `RunAgentInput` contract without a +schema library, so this package pulls in no validation runtime of its own. + ## Parameters ### body @@ -42,8 +46,8 @@ reasoning/activity/developer-role normalization internally. ## Returns `Promise`\<\{ - `aguiContext`: `object`[]; - `context`: `object`[]; + `aguiContext`: `Context`[]; + `context`: `Context`[]; `forwardedProps`: `Record`\<`string`, `unknown`\>; `messages`: ( \| [`ModelMessage`](../interfaces/ModelMessage.md)\< @@ -52,6 +56,7 @@ reasoning/activity/developer-role normalization internally. \| `null`\> \| [`UIMessage`](../interfaces/UIMessage.md)\<`unknown`\>)[]; `parentRunId?`: `string`; + `resume?`: `ResumeEntry`[]; `runId`: `string`; `state`: `unknown`; `threadId`: `string`; @@ -61,5 +66,5 @@ reasoning/activity/developer-role normalization internally. ## Throws An error with a migration-pointing message when the body does - not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a + not conform to AG-UI `RunAgentInput`. Surface this as a 400 Bad Request to the client. diff --git a/docs/reference/functions/cloneAndDeepFreezeJson.md b/docs/reference/functions/cloneAndDeepFreezeJson.md new file mode 100644 index 0000000000..32ca566e56 --- /dev/null +++ b/docs/reference/functions/cloneAndDeepFreezeJson.md @@ -0,0 +1,28 @@ +--- +id: cloneAndDeepFreezeJson +title: cloneAndDeepFreezeJson +--- + +# Function: cloneAndDeepFreezeJson() + +```ts +function cloneAndDeepFreezeJson(value): T; +``` + +Defined in: [packages/ai/src/interrupt-serialization.ts:179](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-serialization.ts#L179) + +## Type Parameters + +### T + +`T` + +## Parameters + +### value + +`T` + +## Returns + +`T` diff --git a/docs/reference/functions/combineStrategies.md b/docs/reference/functions/combineStrategies.md index 7796fa58fc..9062504ac9 100644 --- a/docs/reference/functions/combineStrategies.md +++ b/docs/reference/functions/combineStrategies.md @@ -9,7 +9,7 @@ title: combineStrategies function combineStrategies(strategies): AgentLoopStrategy; ``` -Defined in: [packages/ai/src/activities/chat/agent-loop-strategies.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/agent-loop-strategies.ts#L119) +Defined in: [packages/ai/src/activities/chat/agent-loop-strategies.ts:85](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/agent-loop-strategies.ts#L85) Creates a strategy that combines multiple strategies with AND logic All strategies must return true to continue @@ -26,7 +26,7 @@ Array of strategies to combine [`AgentLoopStrategy`](../type-aliases/AgentLoopStrategy.md) -AgentLoopStrategy that continues only if all strategies return true +AgentLoopStrategy that continues only if all strategies agree ## Example diff --git a/docs/reference/functions/convertSchemaToJsonSchema.md b/docs/reference/functions/convertSchemaToJsonSchema.md index 081cc7f113..97c277337c 100644 --- a/docs/reference/functions/convertSchemaToJsonSchema.md +++ b/docs/reference/functions/convertSchemaToJsonSchema.md @@ -6,7 +6,7 @@ title: convertSchemaToJsonSchema # Function: convertSchemaToJsonSchema() ```ts -function convertSchemaToJsonSchema(schema, options): JSONSchema | undefined; +function convertSchemaToJsonSchema(schema, options?): JSONSchema | undefined; ``` Defined in: [packages/ai/src/activities/chat/tools/schema-converter.ts:324](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/schema-converter.ts#L324) @@ -25,11 +25,11 @@ If the input is already a plain JSONSchema object, it is returned as-is. ### schema -Standard JSON Schema compliant schema or plain JSONSchema object to convert +[`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` -[`SchemaInput`](../type-aliases/SchemaInput.md) | `undefined` +Standard JSON Schema compliant schema or plain JSONSchema object to convert -### options +### options? `ConvertSchemaOptions` = `{}` diff --git a/docs/reference/functions/countEmbeddingInputModalities.md b/docs/reference/functions/countEmbeddingInputModalities.md new file mode 100644 index 0000000000..a66eb902d8 --- /dev/null +++ b/docs/reference/functions/countEmbeddingInputModalities.md @@ -0,0 +1,37 @@ +--- +id: countEmbeddingInputModalities +title: countEmbeddingInputModalities +--- + +# Function: countEmbeddingInputModalities() + +```ts +function countEmbeddingInputModalities(input): object; +``` + +Defined in: [packages/ai/src/utilities/embedding-input.ts:73](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/embedding-input.ts#L73) + +Count text-only and image-carrying items for observability events. Never +exposes input content. + +## Parameters + +### input + +[`EmbeddingInputItem`](../type-aliases/EmbeddingInputItem.md)[] + +## Returns + +`object` + +### imageInputCount + +```ts +imageInputCount: number; +``` + +### textInputCount + +```ts +textInputCount: number; +``` diff --git a/docs/reference/functions/createAudioOptions.md b/docs/reference/functions/createAudioOptions.md index c116e67241..409409adfa 100644 --- a/docs/reference/functions/createAudioOptions.md +++ b/docs/reference/functions/createAudioOptions.md @@ -9,7 +9,7 @@ title: createAudioOptions function createAudioOptions(options): AudioActivityOptions; ``` -Defined in: [packages/ai/src/activities/generateAudio/index.ts:261](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateAudio/index.ts#L261) +Defined in: [packages/ai/src/activities/generateAudio/index.ts:320](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateAudio/index.ts#L320) Create typed options for the generateAudio() function without executing. diff --git a/docs/reference/functions/createCapability.md b/docs/reference/functions/createCapability.md index 892139f352..bd880c1792 100644 --- a/docs/reference/functions/createCapability.md +++ b/docs/reference/functions/createCapability.md @@ -28,28 +28,12 @@ compile-time coverage check that keys on the literal name.) ## Returns -```ts -(name): Capability; -``` - -### Type Parameters - -#### TName - -`TName` *extends* `string` - -### Parameters - -#### name - -`TName` - -### Returns - -[`Capability`](../type-aliases/Capability.md)\<`TValue`, `TName`\> +\<`TName`\>(`name`) => [`Capability`](../type-aliases/Capability.md)\<`TValue`, `TName`\> ## Example +**Provider + consumer middleware** + ```ts const counterCapability = createCapability<{ value: number }>()('counter') const [getCounter, provideCounter] = counterCapability diff --git a/docs/reference/functions/createChatOptions.md b/docs/reference/functions/createChatOptions.md index 8627dfd165..20ead0c2bc 100644 --- a/docs/reference/functions/createChatOptions.md +++ b/docs/reference/functions/createChatOptions.md @@ -6,10 +6,10 @@ title: createChatOptions # Function: createChatOptions() ```ts -function createChatOptions(options): TextActivityOptions>; +function createChatOptions(options): Omit>, "tools"> & object; ``` -Defined in: [packages/ai/src/activities/chat/index.ts:346](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/index.ts#L346) +Defined in: [packages/ai/src/activities/chat/index.ts:522](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/index.ts#L522) Create typed options for the chat() function without executing. This is useful for pre-defining configurations with full type inference. @@ -31,11 +31,11 @@ This is useful for pre-defining configurations with full type inference. ### TTools `TTools` *extends* - \| ( + \| readonly ( \| `Omit`\<[`Tool`](../interfaces/Tool.md)\<`any`, `any`, `any`, `any`\>, `"execute"`\> & `object` & `object` \| [`ProviderTool`](../interfaces/ProviderTool.md)\<`string`, `TAdapter`\[`"~types"`\]\[`"toolCapabilities"`\]\[`number`\]\>)[] \| `undefined` = - \| ( + \| readonly ( \| `Omit`\<[`Tool`](../interfaces/Tool.md)\<`any`, `any`, `any`, `any`\>, `"execute"`\> & `object` & `object` \| [`ProviderTool`](../interfaces/ProviderTool.md)\<`string`, `TAdapter`\[`"~types"`\]\[`"toolCapabilities"`\]\[`number`\]\>)[] \| `undefined` @@ -56,7 +56,7 @@ This is useful for pre-defining configurations with full type inference. ## Returns -`TextActivityOptions`\<`TAdapter`, `TSchema`, `TStream`, `InferredContext`\<`TTools`, `TMiddleware`\>\> +`Omit`\<`TextActivityOptions`\<`TAdapter`, `TSchema`, `TStream`, `InferredContext`\<`TTools`, `TMiddleware`\>\>, `"tools"`\> & `object` ## Example diff --git a/docs/reference/functions/createEmbedOptions.md b/docs/reference/functions/createEmbedOptions.md new file mode 100644 index 0000000000..166034f1eb --- /dev/null +++ b/docs/reference/functions/createEmbedOptions.md @@ -0,0 +1,30 @@ +--- +id: createEmbedOptions +title: createEmbedOptions +--- + +# Function: createEmbedOptions() + +```ts +function createEmbedOptions(options): EmbedOptions; +``` + +Defined in: [packages/ai/src/activities/embed/index.ts:306](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/index.ts#L306) + +Create typed options for the embed() function without executing. + +## Type Parameters + +### TAdapter + +`TAdapter` *extends* [`EmbeddingAdapter`](../interfaces/EmbeddingAdapter.md)\<`string`, `any`, `any`, `any`\> + +## Parameters + +### options + +`EmbedOptions`\<`TAdapter`\> + +## Returns + +`EmbedOptions`\<`TAdapter`\> diff --git a/docs/reference/functions/createFrozenRegistry.md b/docs/reference/functions/createFrozenRegistry.md index d2014639a1..b0998e63af 100644 --- a/docs/reference/functions/createFrozenRegistry.md +++ b/docs/reference/functions/createFrozenRegistry.md @@ -6,7 +6,7 @@ title: createFrozenRegistry # Function: createFrozenRegistry() ```ts -function createFrozenRegistry(tools): ToolRegistry; +function createFrozenRegistry(tools?): ToolRegistry; ``` Defined in: [packages/ai/src/tool-registry.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/tool-registry.ts#L119) @@ -24,7 +24,7 @@ Add and remove operations are no-ops on frozen registries. ## Parameters -### tools +### tools? `TTool`[] = `[]` diff --git a/docs/reference/functions/createImageOptions.md b/docs/reference/functions/createImageOptions.md index 19241295e0..e6f8451958 100644 --- a/docs/reference/functions/createImageOptions.md +++ b/docs/reference/functions/createImageOptions.md @@ -9,7 +9,7 @@ title: createImageOptions function createImageOptions(options): ImageActivityOptions; ``` -Defined in: [packages/ai/src/activities/generateImage/index.ts:360](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateImage/index.ts#L360) +Defined in: [packages/ai/src/activities/generateImage/index.ts:420](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateImage/index.ts#L420) Create typed options for the generateImage() function without executing. diff --git a/docs/reference/functions/createRealtimeEventEmitter.md b/docs/reference/functions/createRealtimeEventEmitter.md index 4213a53939..9769dac06c 100644 --- a/docs/reference/functions/createRealtimeEventEmitter.md +++ b/docs/reference/functions/createRealtimeEventEmitter.md @@ -65,10 +65,4 @@ on(event, handler): () => void; #### Returns -```ts -(): void; -``` - -##### Returns - -`void` +() => `void` diff --git a/docs/reference/functions/createReplayStream.md b/docs/reference/functions/createReplayStream.md index 17c73e7c1d..ea7c850aa3 100644 --- a/docs/reference/functions/createReplayStream.md +++ b/docs/reference/functions/createReplayStream.md @@ -9,7 +9,7 @@ title: createReplayStream function createReplayStream(recording): AsyncIterable; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2275](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2275) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:2459](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L2459) Create an async iterable from a recording diff --git a/docs/reference/functions/createRerankOptions.md b/docs/reference/functions/createRerankOptions.md new file mode 100644 index 0000000000..b9a46767cb --- /dev/null +++ b/docs/reference/functions/createRerankOptions.md @@ -0,0 +1,34 @@ +--- +id: createRerankOptions +title: createRerankOptions +--- + +# Function: createRerankOptions() + +```ts +function createRerankOptions(options): RerankActivityOptions; +``` + +Defined in: [packages/ai/src/activities/rerank/index.ts:287](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/index.ts#L287) + +Create typed options for the rerank() function without executing. + +## Type Parameters + +### TAdapter + +`TAdapter` *extends* [`RerankAdapter`](../interfaces/RerankAdapter.md)\<`string`, `RerankProviderOptions`\<`TAdapter`\>\> + +### TDocument + +`TDocument` *extends* `string` \| `object` = `string` + +## Parameters + +### options + +`RerankActivityOptions`\<`TAdapter`, `TDocument`\> + +## Returns + +`RerankActivityOptions`\<`TAdapter`, `TDocument`\> diff --git a/docs/reference/functions/createSpeechOptions.md b/docs/reference/functions/createSpeechOptions.md index fe67625cdc..c9e3d91bbb 100644 --- a/docs/reference/functions/createSpeechOptions.md +++ b/docs/reference/functions/createSpeechOptions.md @@ -9,7 +9,7 @@ title: createSpeechOptions function createSpeechOptions(options): TTSActivityOptions; ``` -Defined in: [packages/ai/src/activities/generateSpeech/index.ts:274](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateSpeech/index.ts#L274) +Defined in: [packages/ai/src/activities/generateSpeech/index.ts:339](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateSpeech/index.ts#L339) Create typed options for the generateSpeech() function without executing. diff --git a/docs/reference/functions/createSummarizeOptions.md b/docs/reference/functions/createSummarizeOptions.md index 0bf5114dce..7a03796961 100644 --- a/docs/reference/functions/createSummarizeOptions.md +++ b/docs/reference/functions/createSummarizeOptions.md @@ -9,7 +9,7 @@ title: createSummarizeOptions function createSummarizeOptions(options): SummarizeActivityOptions; ``` -Defined in: [packages/ai/src/activities/summarize/index.ts:298](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/summarize/index.ts#L298) +Defined in: [packages/ai/src/activities/summarize/index.ts:528](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/summarize/index.ts#L528) Create typed options for the summarize() function without executing. diff --git a/docs/reference/functions/createToolRegistry.md b/docs/reference/functions/createToolRegistry.md index 43f7e2bb28..d83067eb7c 100644 --- a/docs/reference/functions/createToolRegistry.md +++ b/docs/reference/functions/createToolRegistry.md @@ -6,7 +6,7 @@ title: createToolRegistry # Function: createToolRegistry() ```ts -function createToolRegistry(initialTools): ToolRegistry; +function createToolRegistry(initialTools?): ToolRegistry; ``` Defined in: [packages/ai/src/tool-registry.ts:78](https://github.com/TanStack/ai/blob/main/packages/ai/src/tool-registry.ts#L78) @@ -24,7 +24,7 @@ changes will be reflected in subsequent agent loop iterations. ## Parameters -### initialTools +### initialTools? `TTool`[] = `[]` diff --git a/docs/reference/functions/createTranscriptionOptions.md b/docs/reference/functions/createTranscriptionOptions.md index 7184522c6a..24426debf5 100644 --- a/docs/reference/functions/createTranscriptionOptions.md +++ b/docs/reference/functions/createTranscriptionOptions.md @@ -9,7 +9,7 @@ title: createTranscriptionOptions function createTranscriptionOptions(options): TranscriptionActivityOptions; ``` -Defined in: [packages/ai/src/activities/generateTranscription/index.ts:296](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateTranscription/index.ts#L296) +Defined in: [packages/ai/src/activities/generateTranscription/index.ts:362](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateTranscription/index.ts#L362) Create typed options for the generateTranscription() function without executing. diff --git a/docs/reference/functions/createVideoOptions.md b/docs/reference/functions/createVideoOptions.md index 6005e1902e..f114160217 100644 --- a/docs/reference/functions/createVideoOptions.md +++ b/docs/reference/functions/createVideoOptions.md @@ -9,7 +9,7 @@ title: createVideoOptions function createVideoOptions(options): VideoCreateOptions; ``` -Defined in: [packages/ai/src/activities/generateVideo/index.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateVideo/index.ts#L708) +Defined in: [packages/ai/src/activities/generateVideo/index.ts:1069](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateVideo/index.ts#L1069) Create typed options for the generateVideo() function without executing. diff --git a/docs/reference/functions/defineRunStore.md b/docs/reference/functions/defineRunStore.md new file mode 100644 index 0000000000..2fe5a50156 --- /dev/null +++ b/docs/reference/functions/defineRunStore.md @@ -0,0 +1,36 @@ +--- +id: defineRunStore +title: defineRunStore +--- + +# Function: defineRunStore() + +```ts +function defineRunStore(store): T; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:267](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L267) + +Type a [RunStore](../interfaces/RunStore.md) implementation inline: pass the object and get +autocomplete plus contract checking with no separate annotation. Mirrors +`defineLock` / `defineSandboxInstanceStore`. + +The generic return preserves the argument's own type, so an optional method +the implementation actually provides stays known-present on the result +instead of collapsing back to `| undefined` on the interface. + +## Type Parameters + +### T + +`T` *extends* [`RunStore`](../interfaces/RunStore.md) + +## Parameters + +### store + +`T` + +## Returns + +`T` diff --git a/docs/reference/functions/detectImageMimeType.md b/docs/reference/functions/detectImageMimeType.md index 92e1e3a388..3dc2e878e6 100644 --- a/docs/reference/functions/detectImageMimeType.md +++ b/docs/reference/functions/detectImageMimeType.md @@ -6,7 +6,7 @@ title: detectImageMimeType # Function: detectImageMimeType() ```ts -function detectImageMimeType(base64Data): "image/png" | "image/jpeg" | "image/gif" | "image/webp" | undefined; +function detectImageMimeType(base64Data): "image/jpeg" | "image/png" | "image/gif" | "image/webp" | undefined; ``` Defined in: [packages/ai/src/utils.ts:17](https://github.com/TanStack/ai/blob/main/packages/ai/src/utils.ts#L17) @@ -27,7 +27,7 @@ The base64-encoded image data ## Returns -`"image/png"` \| `"image/jpeg"` \| `"image/gif"` \| `"image/webp"` \| `undefined` +`"image/jpeg"` \| `"image/png"` \| `"image/gif"` \| `"image/webp"` \| `undefined` The detected mime type, or undefined if unrecognized diff --git a/docs/reference/functions/digestInterruptJson.md b/docs/reference/functions/digestInterruptJson.md new file mode 100644 index 0000000000..50a4bf12e8 --- /dev/null +++ b/docs/reference/functions/digestInterruptJson.md @@ -0,0 +1,26 @@ +--- +id: digestInterruptJson +title: digestInterruptJson +--- + +# Function: digestInterruptJson() + +```ts +function digestInterruptJson(canonicalJson, hash?): string; +``` + +Defined in: [packages/ai/src/interrupt-serialization.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-serialization.ts#L161) + +## Parameters + +### canonicalJson + +`string` + +### hash? + +`InterruptHash` = `defaultInterruptHash` + +## Returns + +`string` diff --git a/docs/reference/functions/embed.md b/docs/reference/functions/embed.md new file mode 100644 index 0000000000..df8d0c6601 --- /dev/null +++ b/docs/reference/functions/embed.md @@ -0,0 +1,78 @@ +--- +id: embed +title: embed +--- + +# Function: embed() + +```ts +function embed(options): Promise; +``` + +Defined in: [packages/ai/src/activities/embed/index.ts:189](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/index.ts#L189) + +Embed activity - generates embedding vectors from text and image inputs. + +Accepts a single item or an array of items; the result always carries an +`embeddings` array with one vector per input item, in input order. + +## Type Parameters + +### TAdapter + +`TAdapter` *extends* [`EmbeddingAdapter`](../interfaces/EmbeddingAdapter.md)\<`string`, `any`, `any`, `any`\> + +## Parameters + +### options + +`EmbedOptions`\<`TAdapter`\> + +## Returns + +`Promise`\<[`EmbeddingResult`](../interfaces/EmbeddingResult.md)\> + +## Examples + +**Embed a single text** + +```ts +import { embed } from '@tanstack/ai' +import { openaiEmbedding } from '@tanstack/ai-openai' + +const result = await embed({ + adapter: openaiEmbedding('text-embedding-3-small'), + input: 'a red guitar', +}) + +console.log(result.embeddings[0].vector) +``` + +**Batch with requested dimensions** + +```ts +const result = await embed({ + adapter: openaiEmbedding('text-embedding-3-large'), + input: ['a red guitar', 'a blue drum kit'], + dimensions: 1024, +}) +``` + +**Multimodal embedding (text + image fused into one vector)** + +```ts +import { cohereEmbedding } from '@tanstack/ai-cohere' + +// A nested array of parts fuses them into a single vector. The outer array +// is the item list, so this embeds one fused item into one vector. +const result = await embed({ + adapter: cohereEmbedding('embed-v4.0'), + input: [ + [ + { type: 'text', content: 'product photo' }, + { type: 'image', source: { type: 'data', value: base64, mimeType: 'image/png' } }, + ], + ], + modelOptions: { inputType: 'search_document' }, +}) +``` diff --git a/docs/reference/functions/generateAudio.md b/docs/reference/functions/generateAudio.md index 2bb158a8d4..a7d97bba9c 100644 --- a/docs/reference/functions/generateAudio.md +++ b/docs/reference/functions/generateAudio.md @@ -9,7 +9,7 @@ title: generateAudio function generateAudio(options): AudioActivityResult; ``` -Defined in: [packages/ai/src/activities/generateAudio/index.ts:130](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateAudio/index.ts#L130) +Defined in: [packages/ai/src/activities/generateAudio/index.ts:154](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateAudio/index.ts#L154) Audio generation activity - generates audio from text prompts. @@ -37,6 +37,8 @@ Uses AI models to create music, sound effects, and other audio content. ## Example +**Generate music from a prompt** + ```ts import { generateAudio } from '@tanstack/ai' import { falAudio } from '@tanstack/ai-fal' diff --git a/docs/reference/functions/generateImage.md b/docs/reference/functions/generateImage.md index 2dbd0e8c86..a3ead0b49a 100644 --- a/docs/reference/functions/generateImage.md +++ b/docs/reference/functions/generateImage.md @@ -9,7 +9,7 @@ title: generateImage function generateImage(options): ImageActivityResult; ``` -Defined in: [packages/ai/src/activities/generateImage/index.ts:221](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateImage/index.ts#L221) +Defined in: [packages/ai/src/activities/generateImage/index.ts:245](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateImage/index.ts#L245) Image activity - generates images from text prompts. @@ -37,6 +37,8 @@ Uses AI image generation models to create images based on natural language descr ## Examples +**Generate a single image** + ```ts import { generateImage } from '@tanstack/ai' import { openaiImage } from '@tanstack/ai-openai' @@ -49,6 +51,8 @@ const result = await generateImage({ console.log(result.images[0].url) ``` +**Generate multiple images** + ```ts const result = await generateImage({ adapter: openaiImage('dall-e-2'), @@ -62,6 +66,8 @@ result.images.forEach((image, i) => { }) ``` +**With provider-specific options** + ```ts const result = await generateImage({ adapter: openaiImage('dall-e-3'), diff --git a/docs/reference/functions/generateMessageId.md b/docs/reference/functions/generateMessageId.md index 6dc6c892bd..4a0cd6bae4 100644 --- a/docs/reference/functions/generateMessageId.md +++ b/docs/reference/functions/generateMessageId.md @@ -9,7 +9,7 @@ title: generateMessageId function generateMessageId(): string; ``` -Defined in: [packages/ai/src/activities/chat/messages.ts:668](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L668) +Defined in: [packages/ai/src/activities/chat/messages.ts:699](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L699) Generate a unique message ID diff --git a/docs/reference/functions/generateSpeech.md b/docs/reference/functions/generateSpeech.md index c7ac72cc9a..842904c8da 100644 --- a/docs/reference/functions/generateSpeech.md +++ b/docs/reference/functions/generateSpeech.md @@ -9,7 +9,7 @@ title: generateSpeech function generateSpeech(options): TTSActivityResult; ``` -Defined in: [packages/ai/src/activities/generateSpeech/index.ts:142](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateSpeech/index.ts#L142) +Defined in: [packages/ai/src/activities/generateSpeech/index.ts:167](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateSpeech/index.ts#L167) TTS activity - generates speech from text. @@ -37,6 +37,8 @@ Uses AI text-to-speech models to create audio from natural language text. ## Examples +**Generate speech from text** + ```ts import { generateSpeech } from '@tanstack/ai' import { openaiSpeech } from '@tanstack/ai-openai' @@ -50,6 +52,8 @@ const result = await generateSpeech({ console.log(result.audio) // base64-encoded audio ``` +**With format and speed options** + ```ts const result = await generateSpeech({ adapter: openaiSpeech('tts-1'), diff --git a/docs/reference/functions/generateTranscription.md b/docs/reference/functions/generateTranscription.md index 3df0c1a276..797c415a59 100644 --- a/docs/reference/functions/generateTranscription.md +++ b/docs/reference/functions/generateTranscription.md @@ -9,7 +9,7 @@ title: generateTranscription function generateTranscription(options): TranscriptionActivityResult; ``` -Defined in: [packages/ai/src/activities/generateTranscription/index.ts:164](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateTranscription/index.ts#L164) +Defined in: [packages/ai/src/activities/generateTranscription/index.ts:189](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateTranscription/index.ts#L189) Transcription activity - converts audio to text. @@ -37,6 +37,8 @@ Uses AI speech-to-text models to transcribe audio content. ## Examples +**Transcribe an audio file** + ```ts import { generateTranscription } from '@tanstack/ai' import { openaiTranscription } from '@tanstack/ai-openai' @@ -50,6 +52,8 @@ const result = await generateTranscription({ console.log(result.text) ``` +**With verbose output for timestamps** + ```ts const result = await generateTranscription({ adapter: openaiTranscription('whisper-1'), @@ -62,6 +66,8 @@ result.segments?.forEach(segment => { }) ``` +**Streaming transcription result** + ```ts for await (const chunk of generateTranscription({ adapter: openaiTranscription('whisper-1'), diff --git a/docs/reference/functions/generateVideo.md b/docs/reference/functions/generateVideo.md index 93087105c1..51798b7853 100644 --- a/docs/reference/functions/generateVideo.md +++ b/docs/reference/functions/generateVideo.md @@ -9,7 +9,7 @@ title: generateVideo function generateVideo(options): TStream extends true ? AsyncIterable : Promise; ``` -Defined in: [packages/ai/src/activities/generateVideo/index.ts:312](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateVideo/index.ts#L312) +Defined in: [packages/ai/src/activities/generateVideo/index.ts:389](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateVideo/index.ts#L389) **`Experimental`** @@ -45,8 +45,10 @@ create job → poll for status → stream updates → yield final result. ## Examples +**Create a video generation job** + ```ts -import { generateVideo } from '@tanstack/ai' +import { generateVideo, getVideoJobStatus } from '@tanstack/ai' import { openaiVideo } from '@tanstack/ai-openai' // Start a video generation job @@ -56,8 +58,18 @@ const { jobId } = await generateVideo({ }) console.log('Job started:', jobId) + +// The submission only OPENS the run; the poll that sees a terminal state is +// what completes it. The `jobId` is the whole correlation — pass the same +// `middleware` and `threadId` when you use them. +const status = await getVideoJobStatus({ + adapter: openaiVideo('sora-2'), + jobId, +}) ``` +**Stream the full video generation lifecycle** + ```ts import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai' import { openaiVideo } from '@tanstack/ai-openai' diff --git a/docs/reference/functions/generationParamsFromBody.md b/docs/reference/functions/generationParamsFromBody.md new file mode 100644 index 0000000000..a137c5d2c2 --- /dev/null +++ b/docs/reference/functions/generationParamsFromBody.md @@ -0,0 +1,32 @@ +--- +id: generationParamsFromBody +title: generationParamsFromBody +--- + +# Function: generationParamsFromBody() + +```ts +function generationParamsFromBody(kind, body): GenerationParams; +``` + +Defined in: [packages/ai/src/client.ts:136](https://github.com/TanStack/ai/blob/main/packages/ai/src/client.ts#L136) + +## Type Parameters + +### TKind + +`TKind` *extends* `GenerationKind` + +## Parameters + +### kind + +`TKind` + +### body + +`unknown` + +## Returns + +`GenerationParams`\<`TKind`\> diff --git a/docs/reference/functions/generationParamsFromRequest.md b/docs/reference/functions/generationParamsFromRequest.md new file mode 100644 index 0000000000..fc364af4a3 --- /dev/null +++ b/docs/reference/functions/generationParamsFromRequest.md @@ -0,0 +1,32 @@ +--- +id: generationParamsFromRequest +title: generationParamsFromRequest +--- + +# Function: generationParamsFromRequest() + +```ts +function generationParamsFromRequest(kind, request): Promise>; +``` + +Defined in: [packages/ai/src/client.ts:174](https://github.com/TanStack/ai/blob/main/packages/ai/src/client.ts#L174) + +## Type Parameters + +### TKind + +`TKind` *extends* `GenerationKind` + +## Parameters + +### kind + +`TKind` + +### request + +`Request` + +## Returns + +`Promise`\<`GenerationParams`\<`TKind`\>\> diff --git a/docs/reference/functions/getProviderExecutedMetadata.md b/docs/reference/functions/getProviderExecutedMetadata.md index 803ad8a0a1..fdb327e68d 100644 --- a/docs/reference/functions/getProviderExecutedMetadata.md +++ b/docs/reference/functions/getProviderExecutedMetadata.md @@ -20,9 +20,11 @@ Returns the typed metadata when the call is provider-executed, else `null`. ### toolCall -\{ -`metadata?`: `unknown`; -\} | `null` | `undefined` + \| \{ + `metadata?`: `unknown`; +\} + \| `null` + \| `undefined` ## Returns diff --git a/docs/reference/functions/getVideoJobStatus.md b/docs/reference/functions/getVideoJobStatus.md index 56c02405bc..25aa2516cc 100644 --- a/docs/reference/functions/getVideoJobStatus.md +++ b/docs/reference/functions/getVideoJobStatus.md @@ -6,16 +6,10 @@ title: getVideoJobStatus # Function: getVideoJobStatus() ```ts -function getVideoJobStatus(options): Promise<{ - error?: string; - progress?: number; - status: "pending" | "processing" | "completed" | "failed"; - url?: string; - usage?: TokenUsage; -}>; +function getVideoJobStatus(options): Promise; ``` -Defined in: [packages/ai/src/activities/generateVideo/index.ts:598](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateVideo/index.ts#L598) +Defined in: [packages/ai/src/activities/generateVideo/index.ts:910](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/generateVideo/index.ts#L910) **`Experimental`** @@ -24,6 +18,12 @@ Get video job status - returns the current status, progress, and URL if availabl This function combines status checking and URL retrieval. If the job is completed, it will automatically fetch and include the video URL. +It is also where a non-streaming `generateVideo()` run ENDS: pass the same +`middleware` and `threadId`, and the poll that first sees a terminal job state +finishes the run (recording the result and its artifacts) or fails it. The run +is identified by `adapter` + `jobId`, exactly what the submission derived it +from, so there is nothing else to carry between the two calls. + Video generation is an experimental feature and may change. ## Type Parameters @@ -36,25 +36,15 @@ it will automatically fetch and include the video URL. ### options -#### adapter - -`TAdapter` & `object` - -#### jobId - -`string` +`VideoJobStatusOptions`\<`TAdapter`\> ## Returns -`Promise`\<\{ - `error?`: `string`; - `progress?`: `number`; - `status`: `"pending"` \| `"processing"` \| `"completed"` \| `"failed"`; - `url?`: `string`; - `usage?`: `TokenUsage`\<`ProviderUsageDetails`\>; -\}\> +`Promise`\<`VideoJobStatusResult`\> -## Example +## Examples + +**Check job status** ```ts import { getVideoJobStatus } from '@tanstack/ai' @@ -71,3 +61,33 @@ if (result.url) { console.log('Video URL:', result.url) } ``` + +**Submit and poll one persisted run** + +```ts +import { generateVideo, getVideoJobStatus } from '@tanstack/ai' +import { withGenerationPersistence } from '@tanstack/ai-persistence' +import { openaiVideo } from '@tanstack/ai-openai' + +const adapter = openaiVideo('sora-2') +const middleware = [withGenerationPersistence(persistence)] + +// Opens the run (status `running`, jobId recorded). Its run id is derived +// from the provider job, so nothing has to be stored to resume it. +const { jobId } = await generateVideo({ + adapter, + prompt: 'A cat chasing a dog in a sunny park', + threadId, + middleware, +}) + +// Completes the SAME run once the job settles — this is what writes the +// video, its artifacts, and the terminal status. Works from a different +// request or process: the jobId is the only correlation. +const status = await getVideoJobStatus({ + adapter, + jobId, + threadId, + middleware, +}) +``` diff --git a/docs/reference/functions/hashSchemaInput.md b/docs/reference/functions/hashSchemaInput.md new file mode 100644 index 0000000000..6961893f7f --- /dev/null +++ b/docs/reference/functions/hashSchemaInput.md @@ -0,0 +1,22 @@ +--- +id: hashSchemaInput +title: hashSchemaInput +--- + +# Function: hashSchemaInput() + +```ts +function hashSchemaInput(schema): string; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:198](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L198) + +## Parameters + +### schema + +[`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` + +## Returns + +`string` diff --git a/docs/reference/functions/interruptItemError.md b/docs/reference/functions/interruptItemError.md new file mode 100644 index 0000000000..df64bf3c8a --- /dev/null +++ b/docs/reference/functions/interruptItemError.md @@ -0,0 +1,53 @@ +--- +id: interruptItemError +title: interruptItemError +--- + +# Function: interruptItemError() + +```ts +function interruptItemError( + input, + interruptId, + code, + message, + options?): InterruptSubmissionError; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L104) + +## Parameters + +### input + +`Pick`\<[`ValidateInterruptResumeBatchInput`](../interfaces/ValidateInterruptResumeBatchInput.md), `"threadId"` \| `"interruptedRunId"` \| `"generation"`\> + +### interruptId + +`string` + +### code + +[`ItemInterruptErrorCode`](../type-aliases/ItemInterruptErrorCode.md) + +### message + +`string` + +### options? + +#### path? + +readonly (`string` \| `number`)[] + +#### retryable? + +`boolean` + +#### source? + +`"server"` \| `"client"` + +## Returns + +[`InterruptSubmissionError`](../type-aliases/InterruptSubmissionError.md) diff --git a/docs/reference/functions/isCancelRequestedReason.md b/docs/reference/functions/isCancelRequestedReason.md new file mode 100644 index 0000000000..30533d0e4d --- /dev/null +++ b/docs/reference/functions/isCancelRequestedReason.md @@ -0,0 +1,24 @@ +--- +id: isCancelRequestedReason +title: isCancelRequestedReason +--- + +# Function: isCancelRequestedReason() + +```ts +function isCancelRequestedReason(reason): boolean; +``` + +Defined in: [packages/ai/src/activities/chat/cancel.ts:33](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/cancel.ts#L33) + +Whether an abort reason means "the user explicitly cancelled this run". + +## Parameters + +### reason + +`string` \| `undefined` + +## Returns + +`boolean` diff --git a/docs/reference/functions/isCustomEvent.md b/docs/reference/functions/isCustomEvent.md new file mode 100644 index 0000000000..5113168d80 --- /dev/null +++ b/docs/reference/functions/isCustomEvent.md @@ -0,0 +1,35 @@ +--- +id: isCustomEvent +title: isCustomEvent +--- + +# Function: isCustomEvent() + +```ts +function isCustomEvent(chunk, name): chunk is WellKnownCustomEvent; +``` + +Defined in: [packages/ai/src/custom-events.ts:102](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L102) + +Type guard: is `chunk` a CUSTOM event with the given well-known `name`? +Narrows the payload type when true, so consumers read `chunk.value` typed. + +## Type Parameters + +### TName + +`TName` *extends* [`WellKnownCustomEventName`](../type-aliases/WellKnownCustomEventName.md) + +## Parameters + +### chunk + +[`AGUIEvent`](../type-aliases/AGUIEvent.md) + +### name + +`TName` + +## Returns + +`chunk is WellKnownCustomEvent` diff --git a/docs/reference/functions/isProviderExecutedToolCall.md b/docs/reference/functions/isProviderExecutedToolCall.md index 7e681730b1..e3ad163fe0 100644 --- a/docs/reference/functions/isProviderExecutedToolCall.md +++ b/docs/reference/functions/isProviderExecutedToolCall.md @@ -19,9 +19,11 @@ calls must not be routed to client-side execution and are already "complete". ### toolCall -\{ -`metadata?`: `unknown`; -\} | `null` | `undefined` + \| \{ + `metadata?`: `unknown`; +\} + \| `null` + \| `undefined` ## Returns diff --git a/docs/reference/functions/isRunStatus.md b/docs/reference/functions/isRunStatus.md new file mode 100644 index 0000000000..7b3411c5ae --- /dev/null +++ b/docs/reference/functions/isRunStatus.md @@ -0,0 +1,33 @@ +--- +id: isRunStatus +title: isRunStatus +--- + +# Function: isRunStatus() + +```ts +function isRunStatus(value): value is RunStatus; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:69](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L69) + +Whether `value` is a [RunStatus](../type-aliases/RunStatus.md) — the guard a backend validates a row +with at DESERIALIZATION. + +`RunStatus` is a compile-time claim about a storage column. A row arrives as +JSON out of D1, a Durable Object, or Postgres, and nothing in the type system +checked what that column actually held, so a `RunStore` implementation should +run its row's `status` through this before handing the record on. The readers +downstream act DESTRUCTIVELY on the answer — `@tanstack/ai-sandbox`'s journal +sweep DELETES the journal of a run it believes terminal — so a row that lies +about its status is not a display bug. + +## Parameters + +### value + +`unknown` + +## Returns + +`value is RunStatus` diff --git a/docs/reference/functions/isTerminalRunStatus.md b/docs/reference/functions/isTerminalRunStatus.md new file mode 100644 index 0000000000..0a61f5547c --- /dev/null +++ b/docs/reference/functions/isTerminalRunStatus.md @@ -0,0 +1,34 @@ +--- +id: isTerminalRunStatus +title: isTerminalRunStatus +--- + +# Function: isTerminalRunStatus() + +```ts +function isTerminalRunStatus(status): status is TerminalRunStatus; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:86](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L86) + +Whether `status` means no further events will be appended. Narrows, so a +caller inside the guard can pass `status` where a [TerminalRunStatus](../type-aliases/TerminalRunStatus.md) +is required without a cast. + +`Object.hasOwn`, never `in`: `in` walks the prototype chain, so a row whose +`status` column held `'toString'` or `'constructor'` would be reported +terminal. `status` is TYPED `RunStatus`, but every value reaching here comes +off a user-implemented [RunStore](../interfaces/RunStore.md) and the type is only a claim (see +[isRunStatus](isRunStatus.md)). A false `true` deletes a live run's journal +(`@tanstack/ai-sandbox`'s journal sweep), fails its attach as `'terminal-run'` +(`attach-preflight`), and refuses to drive it (`stream-to-response.ts`). + +## Parameters + +### status + +[`RunStatus`](../type-aliases/RunStatus.md) + +## Returns + +`status is TerminalRunStatus` diff --git a/docs/reference/functions/maxIterations.md b/docs/reference/functions/maxIterations.md index 5d1cdb7396..5f06907e4d 100644 --- a/docs/reference/functions/maxIterations.md +++ b/docs/reference/functions/maxIterations.md @@ -9,14 +9,15 @@ title: maxIterations function maxIterations(max): AgentLoopStrategy; ``` -Defined in: [packages/ai/src/activities/chat/agent-loop-strategies.ts:25](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/agent-loop-strategies.ts#L25) +Defined in: [packages/ai/src/activities/chat/agent-loop-strategies.ts:26](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/agent-loop-strategies.ts#L26) Creates a strategy that continues for a maximum number of **model turns** (iterations), not tool calls. -One iteration can still emit many parallel tool calls. Prefer middleware -with `onBeforeToolCall` / `onShouldContinue` when you need a tool-call -budget (see the Agentic Cycle docs recipe). +One iteration can still emit many parallel tool calls. For a tool-call +budget, use middleware with `onBeforeToolCall` (per-turn cap) and +`onShouldContinue` (cumulative run budget) — see the docs recipe under +Agentic Cycle. ## Parameters diff --git a/docs/reference/functions/memoryStream.md b/docs/reference/functions/memoryStream.md new file mode 100644 index 0000000000..8933ce6e52 --- /dev/null +++ b/docs/reference/functions/memoryStream.md @@ -0,0 +1,38 @@ +--- +id: memoryStream +title: memoryStream +--- + +# Function: memoryStream() + +```ts +function memoryStream(source, options?): UpsertableStreamDurability; +``` + +Defined in: [packages/ai/src/stream-durability.ts:331](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L331) + +The zero-infrastructure delivery-durability backend. Its versioned cursor is +deliberately private: callers and core only pass the returned string back. + +Construct from the incoming `Request` (HTTP transports) or from an explicit +[MemoryStreamInit](../interfaces/MemoryStreamInit.md) (server functions / direct calls that already know +the run id). + +Logs live in a process-global map, so this backend is for development, tests, +and single-process deployments only. Completed runs are evicted after a grace +window (see COMPLETED\_LOG\_TTL\_MS); a resume of an evicted or unknown +run fails loudly rather than hanging. + +## Parameters + +### source + +`Request` \| [`MemoryStreamInit`](../interfaces/MemoryStreamInit.md) + +### options? + +[`MemoryStreamOptions`](../interfaces/MemoryStreamOptions.md) = `{}` + +## Returns + +[`UpsertableStreamDurability`](../interfaces/UpsertableStreamDurability.md) diff --git a/docs/reference/functions/mergeAgentTools.md b/docs/reference/functions/mergeAgentTools.md index 6796c281b8..a6f0af1b9e 100644 --- a/docs/reference/functions/mergeAgentTools.md +++ b/docs/reference/functions/mergeAgentTools.md @@ -5,11 +5,69 @@ title: mergeAgentTools # Function: mergeAgentTools() +## Call Signature + +```ts +function mergeAgentTools(serverTools, clientTools): TServerTools; +``` + +Defined in: [packages/ai/src/utilities/chat-params.ts:359](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L359) + +Merge a server-side tool array with the AG-UI client-declared tools +received in the request body. + +Rules: +- Server tools win on name collision. The client's declaration is + ignored if the server already has a tool with that name. The client's + UI-side handler still fires when the streamed tool-result event comes + through (see `chat-client.ts` `onToolCall`), giving the + "after server execution the client also handles" semantic for free. +- Client-only tools (name not in `serverTools`) become no-execute + entries: the runtime's existing `ClientToolRequest` path handles + them — server emits a tool-call request, client executes via its + registered handler, client posts back the result. + +Typing: +- Empty `clientTools` preserves the server tuple (closed name union). +- Non-empty `clientTools` returns a widened array that honestly includes + client stubs, so `TypedStreamChunk` does not claim a closed server-only + name union. + +### Type Parameters + +#### TServerTools + +`TServerTools` *extends* readonly [`AnyTool`](../type-aliases/AnyTool.md)[] + +### Parameters + +#### serverTools + +`TServerTools` + +The server's tool array (e.g. from + `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`. + +#### clientTools + +readonly \[\] + +The `tools` array received from + `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`. + +### Returns + +`TServerTools` + +A merged array suitable for `chat({ tools })`. + +## Call Signature + ```ts -function mergeAgentTools(serverTools, clientTools): Tool[]; +function mergeAgentTools(serverTools, clientTools): MergedAgentTools; ``` -Defined in: [packages/ai/src/utilities/chat-params.ts:187](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L187) +Defined in: [packages/ai/src/utilities/chat-params.ts:362](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L362) Merge a server-side tool array with the AG-UI client-declared tools received in the request body. @@ -25,30 +83,36 @@ Rules: them — server emits a tool-call request, client executes via its registered handler, client posts back the result. -## Type Parameters +Typing: +- Empty `clientTools` preserves the server tuple (closed name union). +- Non-empty `clientTools` returns a widened array that honestly includes + client stubs, so `TypedStreamChunk` does not claim a closed server-only + name union. + +### Type Parameters -### TContext +#### TServerTools -`TContext` = `unknown` +`TServerTools` *extends* readonly [`AnyTool`](../type-aliases/AnyTool.md)[] -## Parameters +### Parameters -### serverTools +#### serverTools -readonly [`Tool`](../interfaces/Tool.md)\<[`SchemaInput`](../type-aliases/SchemaInput.md), [`SchemaInput`](../type-aliases/SchemaInput.md), `string`, `TContext`\>[] +`TServerTools` The server's tool array (e.g. from `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`. -### clientTools +#### clientTools readonly `object`[] The `tools` array received from `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`. -## Returns +### Returns -[`Tool`](../interfaces/Tool.md)\<[`SchemaInput`](../type-aliases/SchemaInput.md), [`SchemaInput`](../type-aliases/SchemaInput.md), `string`, `TContext`\>[] +[`MergedAgentTools`](../type-aliases/MergedAgentTools.md)\<`TServerTools`\> A merged array suitable for `chat({ tools })`. diff --git a/docs/reference/functions/modelMessageToUIMessage.md b/docs/reference/functions/modelMessageToUIMessage.md index 6d0755a9d9..bb7ce7becb 100644 --- a/docs/reference/functions/modelMessageToUIMessage.md +++ b/docs/reference/functions/modelMessageToUIMessage.md @@ -9,7 +9,7 @@ title: modelMessageToUIMessage function modelMessageToUIMessage(modelMessage, id?): UIMessage; ``` -Defined in: [packages/ai/src/activities/chat/messages.ts:402](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L402) +Defined in: [packages/ai/src/activities/chat/messages.ts:429](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L429) Convert a ModelMessage to UIMessage diff --git a/docs/reference/functions/modelMessagesToUIMessages.md b/docs/reference/functions/modelMessagesToUIMessages.md index 1f0e69f58b..3ce2654b1f 100644 --- a/docs/reference/functions/modelMessagesToUIMessages.md +++ b/docs/reference/functions/modelMessagesToUIMessages.md @@ -9,7 +9,7 @@ title: modelMessagesToUIMessages function modelMessagesToUIMessages(modelMessages): UIMessage[]; ``` -Defined in: [packages/ai/src/activities/chat/messages.ts:584](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L584) +Defined in: [packages/ai/src/activities/chat/messages.ts:614](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L614) Convert an array of ModelMessages to UIMessages diff --git a/docs/reference/functions/normalizeApprovalSchema.md b/docs/reference/functions/normalizeApprovalSchema.md new file mode 100644 index 0000000000..1a22a10d35 --- /dev/null +++ b/docs/reference/functions/normalizeApprovalSchema.md @@ -0,0 +1,27 @@ +--- +id: normalizeApprovalSchema +title: normalizeApprovalSchema +--- + +# Function: normalizeApprovalSchema() + +```ts +function normalizeApprovalSchema(approvalSchema, inputSchema?): NormalizedApprovalSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:141](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L141) + +## Parameters + +### approvalSchema + + \| [`ApprovalSchemaConfig`](../type-aliases/ApprovalSchemaConfig.md) + \| `undefined` + +### inputSchema? + +[`SchemaInput`](../type-aliases/SchemaInput.md) + +## Returns + +[`NormalizedApprovalSchema`](../interfaces/NormalizedApprovalSchema.md) diff --git a/docs/reference/functions/normalizeSystemPrompts.md b/docs/reference/functions/normalizeSystemPrompts.md index 6d339c4197..f7fcabfc1e 100644 --- a/docs/reference/functions/normalizeSystemPrompts.md +++ b/docs/reference/functions/normalizeSystemPrompts.md @@ -33,7 +33,8 @@ function through `as any` / external JS would otherwise stream a literal ### prompts -readonly [`SystemPrompt`](../type-aliases/SystemPrompt.md)\<`unknown`\>[] | `undefined` + \| readonly [`SystemPrompt`](../type-aliases/SystemPrompt.md)\<`unknown`\>[] + \| `undefined` ## Returns diff --git a/docs/reference/functions/normalizeToUIMessage.md b/docs/reference/functions/normalizeToUIMessage.md index 55cb976269..891fe10b0b 100644 --- a/docs/reference/functions/normalizeToUIMessage.md +++ b/docs/reference/functions/normalizeToUIMessage.md @@ -9,7 +9,7 @@ title: normalizeToUIMessage function normalizeToUIMessage(message, generateId): UIMessage; ``` -Defined in: [packages/ai/src/activities/chat/messages.ts:645](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L645) +Defined in: [packages/ai/src/activities/chat/messages.ts:676](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/messages.ts#L676) Normalize a message (UIMessage or ModelMessage) to a UIMessage Ensures the message has an ID and createdAt timestamp @@ -18,12 +18,13 @@ Ensures the message has an ID and createdAt timestamp ### message -Either a UIMessage or ModelMessage + \| [`ModelMessage`](../interfaces/ModelMessage.md)\< + \| `string` + \| [`ContentPart`](../type-aliases/ContentPart.md)\<`unknown`, `unknown`, `unknown`, `unknown`, `unknown`\>[] + \| `null`\> + \| [`UIMessage`](../interfaces/UIMessage.md)\<`unknown`\> -[`ModelMessage`](../interfaces/ModelMessage.md)\< -\| `string` -\| [`ContentPart`](../type-aliases/ContentPart.md)\<`unknown`, `unknown`, `unknown`, `unknown`, `unknown`\>[] -\| `null`\> | [`UIMessage`](../interfaces/UIMessage.md)\<`unknown`\> +Either a UIMessage or ModelMessage ### generateId diff --git a/docs/reference/functions/readInterruptBinding.md b/docs/reference/functions/readInterruptBinding.md new file mode 100644 index 0000000000..4b07361223 --- /dev/null +++ b/docs/reference/functions/readInterruptBinding.md @@ -0,0 +1,28 @@ +--- +id: readInterruptBinding +title: readInterruptBinding +--- + +# Function: readInterruptBinding() + +```ts +function readInterruptBinding(descriptor): InterruptBinding | undefined; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:795](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L795) + +Read the opened resume binding off a descriptor, or `undefined` when the +descriptor carries no binding of a version we understand. + +`undefined` means "this interrupt is not ours to resume" — it is not a +failure to recover from by inventing a binding. + +## Parameters + +### descriptor + +`Interrupt` + +## Returns + +[`InterruptBinding`](../type-aliases/InterruptBinding.md) \| `undefined` diff --git a/docs/reference/functions/readUnopenedInterruptBinding.md b/docs/reference/functions/readUnopenedInterruptBinding.md new file mode 100644 index 0000000000..4c394431d0 --- /dev/null +++ b/docs/reference/functions/readUnopenedInterruptBinding.md @@ -0,0 +1,29 @@ +--- +id: readUnopenedInterruptBinding +title: readUnopenedInterruptBinding +--- + +# Function: readUnopenedInterruptBinding() + +```ts +function readUnopenedInterruptBinding(descriptor): + | Omit + | Omit + | Omit + | undefined; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:700](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L700) + +## Parameters + +### descriptor + +`Interrupt` + +## Returns + + \| `Omit`\<`InterruptBindingBase` & `object`, `"interruptedRunId"` \| `"generation"`\> + \| `Omit`\<`InterruptBindingBase` & `object`, `"interruptedRunId"` \| `"generation"`\> + \| `Omit`\<`InterruptBindingBase` & `object`, `"interruptedRunId"` \| `"generation"`\> + \| `undefined` diff --git a/docs/reference/functions/realtimeToken.md b/docs/reference/functions/realtimeToken.md index e1548e82fb..4007558d86 100644 --- a/docs/reference/functions/realtimeToken.md +++ b/docs/reference/functions/realtimeToken.md @@ -9,7 +9,7 @@ title: realtimeToken function realtimeToken(options): Promise; ``` -Defined in: [packages/ai/src/realtime/index.ts:33](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/index.ts#L33) +Defined in: [packages/ai/src/realtime/index.ts:29](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/index.ts#L29) Generate a realtime token using the provided adapter. @@ -36,13 +36,9 @@ Promise resolving to a RealtimeToken import { realtimeToken } from '@tanstack/ai' import { openaiRealtimeToken } from '@tanstack/ai-openai' -// Server function (TanStack Start example) -export const getRealtimeToken = createServerFn() - .handler(async () => { - return realtimeToken({ - adapter: openaiRealtimeToken({ - model: 'gpt-realtime', - }), - }) - }) +// On the server (e.g. inside a server route or framework server +// function), mint an ephemeral token for the client: +const token = await realtimeToken({ + adapter: openaiRealtimeToken({ model: 'gpt-realtime' }), +}) ``` diff --git a/docs/reference/functions/renderLazyCatalogEntry.md b/docs/reference/functions/renderLazyCatalogEntry.md index eb4dda57c5..4c54708f5c 100644 --- a/docs/reference/functions/renderLazyCatalogEntry.md +++ b/docs/reference/functions/renderLazyCatalogEntry.md @@ -9,7 +9,7 @@ title: renderLazyCatalogEntry function renderLazyCatalogEntry( name, description, - includeDescription): string; + includeDescription?): string; ``` Defined in: [packages/ai/src/activities/chat/tools/lazy-tools.ts:22](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/lazy-tools.ts#L22) @@ -30,9 +30,9 @@ Falls back to the bare name when there is no description. `string` -### includeDescription +### includeDescription? -`"full"` | `"first-sentence"` | `"none"` | `undefined` +`"full"` \| `"first-sentence"` \| `"none"` \| `undefined` ## Returns diff --git a/docs/reference/functions/replayRunStream.md b/docs/reference/functions/replayRunStream.md new file mode 100644 index 0000000000..e80d656e28 --- /dev/null +++ b/docs/reference/functions/replayRunStream.md @@ -0,0 +1,64 @@ +--- +id: replayRunStream +title: replayRunStream +--- + +# Function: replayRunStream() + +```ts +function replayRunStream( + durability, + offset?, +signal?): AsyncGenerator; +``` + +Defined in: [packages/ai/src/stream-durability.ts:588](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L588) + +Replay a run's delivery-durability log as a bare stream of chunks, for +callers that serve a `joinRun` handler without an HTTP `Response` — e.g. a +TanStack Start server function returning an async iterable: + +```ts +async function* joinImageRun({ data: runId }: { data: string }) { + yield* replayRunStream(memoryStream({ runId })) +} + +// Serve it from a server function whose handler is the generator above +// (`createServerFn({ method: 'GET' }).inputValidator(...)`). +``` + +NOTE: the example deliberately declares the generator separately instead of +inlining it into the server-fn builder chain. TanStack Start's server-fn +Vite plugin decides whether a module needs compiling by regex-matching the +SOURCE for a dotted `handler(` call, and JSDoc survives into `dist` — an +inlined chain here would make every Start app treat this package as a +server-fn module and try to resolve its framework's `@tanstack/*-start` +package, failing the build wherever that framework is not the one installed. + +Reads from `offset` (default `'-1'` — from the start) and tails until the +producer closes the log or `signal` aborts, exactly like the HTTP +`resumeServerSentEventsResponse` path. + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` + +## Parameters + +### durability + +[`StreamDurability`](../interfaces/StreamDurability.md)\<`TOffset`\> + +### offset? + +`TOffset` + +### signal? + +`AbortSignal` + +## Returns + +`AsyncGenerator`\<[`AGUIEvent`](../type-aliases/AGUIEvent.md)\> diff --git a/docs/reference/functions/requestRunCancel.md b/docs/reference/functions/requestRunCancel.md new file mode 100644 index 0000000000..212da7997d --- /dev/null +++ b/docs/reference/functions/requestRunCancel.md @@ -0,0 +1,36 @@ +--- +id: requestRunCancel +title: requestRunCancel +--- + +# Function: requestRunCancel() + +```ts +function requestRunCancel(runs, runId): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/cancel.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/cancel.ts#L48) + +Record an explicit cancel on the run record. + +Deliberately does NOT set a status. The driver is the only actor that knows +when the agent has actually stopped and the sandbox has been torn down, so it +owns the transition to `'aborted'`. Writing a terminal status here would tell +every reader the run is over while the agent is still burning tokens. + +A no-op for an unknown `runId`, inheriting `RunStore.update`'s documented +invariant. + +## Parameters + +### runs + +[`RunStore`](../interfaces/RunStore.md) + +### runId + +`string` + +## Returns + +`Promise`\<`void`\> diff --git a/docs/reference/functions/requireTextOnlyEmbeddingInput.md b/docs/reference/functions/requireTextOnlyEmbeddingInput.md new file mode 100644 index 0000000000..8cde0a1203 --- /dev/null +++ b/docs/reference/functions/requireTextOnlyEmbeddingInput.md @@ -0,0 +1,37 @@ +--- +id: requireTextOnlyEmbeddingInput +title: requireTextOnlyEmbeddingInput +--- + +# Function: requireTextOnlyEmbeddingInput() + +```ts +function requireTextOnlyEmbeddingInput( + input, + provider, + model): string[]; +``` + +Defined in: [packages/ai/src/utilities/embedding-input.ts:53](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/embedding-input.ts#L53) + +Extract plain text inputs for a text-only embedding model, throwing a +uniform error if any item carries an image. The per-model modality typing +rejects these at compile time; this guard covers untyped/dynamic callers. + +## Parameters + +### input + +[`EmbeddingInputItem`](../type-aliases/EmbeddingInputItem.md)[] + +### provider + +`string` + +### model + +`string` + +## Returns + +`string`[] diff --git a/docs/reference/functions/rerank.md b/docs/reference/functions/rerank.md new file mode 100644 index 0000000000..5a51eaac57 --- /dev/null +++ b/docs/reference/functions/rerank.md @@ -0,0 +1,68 @@ +--- +id: rerank +title: rerank +--- + +# Function: rerank() + +```ts +function rerank(options): Promise>; +``` + +Defined in: [packages/ai/src/activities/rerank/index.ts:152](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/index.ts#L152) + +Rerank activity - reorders documents by relevance to a query. + +## Type Parameters + +### TAdapter + +`TAdapter` *extends* [`RerankAdapter`](../interfaces/RerankAdapter.md)\<`string`, `RerankProviderOptions`\<`TAdapter`\>\> + +### TDocument + +`TDocument` *extends* `string` \| `object` = `string` + +## Parameters + +### options + +`RerankActivityOptions`\<`TAdapter`, `TDocument`\> + +## Returns + +`Promise`\<[`RerankResult`](../interfaces/RerankResult.md)\<`TDocument`\>\> + +## Examples + +**Basic reranking** + +```ts +import { rerank } from '@tanstack/ai' +import { cohereRerank } from '@tanstack/ai-cohere' + +const { ranking, rerankedDocuments } = await rerank({ + adapter: cohereRerank('rerank-v3.5'), + query: 'talk about rain', + documents: ['sunny day at the beach', 'rainy afternoon in the city'], + topN: 2, +}) + +console.log(rerankedDocuments[0]) // 'rainy afternoon in the city' +``` + +**Reranking object documents** + +```ts +const { ranking } = await rerank({ + adapter: cohereRerank('rerank-v3.5'), + query: 'best laptop for travel', + documents: [ + { id: 1, text: 'A heavy gaming desktop' }, + { id: 2, text: 'A lightweight ultrabook with all-day battery' }, + ], +}) + +// ranking[0].document is the original object, fully typed. +console.log(ranking[0].document.id) +``` diff --git a/docs/reference/functions/resolveEmbeddingInput.md b/docs/reference/functions/resolveEmbeddingInput.md new file mode 100644 index 0000000000..1bd0c8df3e --- /dev/null +++ b/docs/reference/functions/resolveEmbeddingInput.md @@ -0,0 +1,26 @@ +--- +id: resolveEmbeddingInput +title: resolveEmbeddingInput +--- + +# Function: resolveEmbeddingInput() + +```ts +function resolveEmbeddingInput(input): ResolvedEmbeddingItem[]; +``` + +Defined in: [packages/ai/src/utilities/embedding-input.ts:42](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/embedding-input.ts#L42) + +Resolve each embedding input item into its text and image constituents, +preserving input order (result[i] corresponds to input[i] and to the +vector at index i). + +## Parameters + +### input + +[`EmbeddingInputItem`](../type-aliases/EmbeddingInputItem.md)[] + +## Returns + +[`ResolvedEmbeddingItem`](../interfaces/ResolvedEmbeddingItem.md)[] diff --git a/docs/reference/functions/resolveResumeRunId.md b/docs/reference/functions/resolveResumeRunId.md new file mode 100644 index 0000000000..67eacc7a44 --- /dev/null +++ b/docs/reference/functions/resolveResumeRunId.md @@ -0,0 +1,29 @@ +--- +id: resolveResumeRunId +title: resolveResumeRunId +--- + +# Function: resolveResumeRunId() + +```ts +function resolveResumeRunId(request): string | null; +``` + +Defined in: [packages/ai/src/stream-durability.ts:141](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L141) + +The run id a request names: `X-Run-Id` header first, then `?runId`. + +The single implementation of that precedence, shared by the durability +adapters below and by the resume response helpers' run driver +(`stream-to-response.ts`), so the helper and the adapter can never disagree +about which run a request is talking about. + +## Parameters + +### request + +`Request` + +## Returns + +`string` \| `null` diff --git a/docs/reference/functions/resumeHttpResponse.md b/docs/reference/functions/resumeHttpResponse.md new file mode 100644 index 0000000000..f8a21123ec --- /dev/null +++ b/docs/reference/functions/resumeHttpResponse.md @@ -0,0 +1,41 @@ +--- +id: resumeHttpResponse +title: resumeHttpResponse +--- + +# Function: resumeHttpResponse() + +```ts +function resumeHttpResponse(options): Response; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:1189](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L1189) + +Serve a resumable run from its durability log over NDJSON, without re-running +the model. The NDJSON counterpart of [resumeServerSentEventsResponse](resumeServerSentEventsResponse.md); +pair it with a `toHttpResponse` producer. Returns a 400 when the request +carries no resume offset (no `Last-Event-ID` header and no `?offset`). + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` = `string` + +## Parameters + +### options + +`ResumeResponseOptions`\<`TOffset`\> + +## Returns + +`Response` + +## Example + +```typescript +export async function GET(request: Request) { + return resumeHttpResponse({ adapter: memoryStream(request) }); +} +``` diff --git a/docs/reference/functions/resumeServerSentEventsResponse.md b/docs/reference/functions/resumeServerSentEventsResponse.md new file mode 100644 index 0000000000..668fc5bf9d --- /dev/null +++ b/docs/reference/functions/resumeServerSentEventsResponse.md @@ -0,0 +1,44 @@ +--- +id: resumeServerSentEventsResponse +title: resumeServerSentEventsResponse +--- + +# Function: resumeServerSentEventsResponse() + +```ts +function resumeServerSentEventsResponse(options): Response; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:996](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L996) + +Serve a resumable run from its durability log over Server-Sent Events, without +re-running the model. Use this in a `GET` handler so a reload or a second tab +can re-attach to an in-flight or finished run. + +The adapter (`memoryStream(request)` / `durableStream(request)`) captures the +resume offset from the request. If there is none (no `Last-Event-ID` header +and no `?offset`), there is nothing to replay and this returns a 400. + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` = `string` + +## Parameters + +### options + +`ResumeResponseOptions`\<`TOffset`\> + +## Returns + +`Response` + +## Example + +```typescript +export async function GET(request: Request) { + return resumeServerSentEventsResponse({ adapter: memoryStream(request) }); +} +``` diff --git a/docs/reference/functions/streamToText.md b/docs/reference/functions/streamToText.md index dab52a6a49..6f53446c79 100644 --- a/docs/reference/functions/streamToText.md +++ b/docs/reference/functions/streamToText.md @@ -9,7 +9,7 @@ title: streamToText function streamToText(stream): Promise; ``` -Defined in: [packages/ai/src/stream-to-response.ts:24](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L24) +Defined in: [packages/ai/src/stream-to-response.ts:43](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L43) Collect all text content from a StreamChunk async iterable and return as a string. @@ -34,8 +34,7 @@ Promise - The accumulated text content ```typescript const stream = chat({ - adapter: openaiText(), - model: 'gpt-4o', + adapter: openaiText('gpt-5.5'), messages: [{ role: 'user', content: 'Hello!' }] }); const text = await streamToText(stream); diff --git a/docs/reference/functions/summarize.md b/docs/reference/functions/summarize.md index 87fdda4891..a83f6f1670 100644 --- a/docs/reference/functions/summarize.md +++ b/docs/reference/functions/summarize.md @@ -9,7 +9,7 @@ title: summarize function summarize(options): SummarizeActivityResult; ``` -Defined in: [packages/ai/src/activities/summarize/index.ts:152](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/summarize/index.ts#L152) +Defined in: [packages/ai/src/activities/summarize/index.ts:207](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/summarize/index.ts#L207) Summarize activity - generates summaries from text. @@ -37,6 +37,8 @@ Supports both streaming and non-streaming modes. ## Examples +**Basic summarization** + ```ts import { summarize } from '@tanstack/ai' import { openaiSummarize } from '@tanstack/ai-openai' @@ -49,6 +51,8 @@ const result = await summarize({ console.log(result.summary) ``` +**Summarization with style** + ```ts const result = await summarize({ adapter: openaiSummarize('gpt-4o-mini'), @@ -58,6 +62,8 @@ const result = await summarize({ }) ``` +**Focused summarization** + ```ts const result = await summarize({ adapter: openaiSummarize('gpt-4o-mini'), @@ -66,6 +72,8 @@ const result = await summarize({ }) ``` +**Streaming summarization** + ```ts for await (const chunk of summarize({ adapter: openaiSummarize('gpt-4o-mini'), diff --git a/docs/reference/functions/toHttpResponse.md b/docs/reference/functions/toHttpResponse.md index 44c713caf3..dbef5f19e3 100644 --- a/docs/reference/functions/toHttpResponse.md +++ b/docs/reference/functions/toHttpResponse.md @@ -6,10 +6,10 @@ title: toHttpResponse # Function: toHttpResponse() ```ts -function toHttpResponse(stream, init?): Response; +function toHttpResponse(stream, init?): Response; ``` -Defined in: [packages/ai/src/stream-to-response.ts:240](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L240) +Defined in: [packages/ai/src/stream-to-response.ts:1106](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L1106) Convert a StreamChunk async iterable to a Response in HTTP stream format (newline-delimited JSON) @@ -19,6 +19,21 @@ This creates a Response that emits chunks in HTTP stream format: This format is compatible with `fetchHttpStream` connection adapter. +Pass a `durability` sink (`memoryStream(request)` / `durableStream(request)`) +to make the stream resumable: fresh runs are appended to the log and each +NDJSON line is emitted as an `{ id, chunk }` envelope carrying an opaque +offset; a reconnect (native `Last-Event-ID` header) or a `?offset` join +replays from the log without re-running the producer. `batch` controls how +many chunks are buffered per `append` (default 32). This shares the exact +`durableStreamSource` used by `toServerSentEventsResponse` — only the wire +encoding differs. + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` = `string` + ## Parameters ### stream @@ -31,7 +46,7 @@ AsyncIterable of StreamChunks from chat() `ResponseInit` & `object` -Optional Response initialization options (including `abortController`) +Optional Response initialization options (including `abortController`, `durability` with its optional `batch`, and `debug`) ## Returns @@ -42,6 +57,8 @@ Response in HTTP stream format (newline-delimited JSON) ## Example ```typescript -const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] }); -return toHttpResponse(stream, { abortController }); +export async function POST(request: Request) { + const stream = chat({ adapter: openaiText('gpt-5.5'), messages: [...] }); + return toHttpResponse(stream, { durability: { adapter: memoryStream(request) } }); +} ``` diff --git a/docs/reference/functions/toHttpStream.md b/docs/reference/functions/toHttpStream.md index f2f343c2aa..65baa19abb 100644 --- a/docs/reference/functions/toHttpStream.md +++ b/docs/reference/functions/toHttpStream.md @@ -6,10 +6,13 @@ title: toHttpStream # Function: toHttpStream() ```ts -function toHttpStream(stream, abortController?): ReadableStream>; +function toHttpStream( + stream, + abortController?, +getId?): ReadableStream>; ``` -Defined in: [packages/ai/src/stream-to-response.ts:171](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L171) +Defined in: [packages/ai/src/stream-to-response.ts:1044](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L1044) Convert a StreamChunk async iterable to a ReadableStream in HTTP stream format (newline-delimited JSON) @@ -19,6 +22,12 @@ This creates a ReadableStream that emits chunks as newline-delimited JSON: This format is compatible with `fetchHttpStream` connection adapter. +When `getId` is supplied (delivery durability), each chunk is emitted as an +envelope `{"id":"","chunk":{…}}` instead of a bare chunk. NDJSON has +no native event-id field like SSE's `id:` line, so the resumable offset rides +inside the payload. Untagged chunks (no id) stay bare, so a non-durable +stream is byte-identical to before and the client auto-detects either form. + ## Parameters ### stream @@ -33,6 +42,12 @@ AsyncIterable of StreamChunks from chat() Optional AbortController to abort when stream is cancelled +### getId? + +(`chunk`, `index`) => `string` \| `undefined` + +Optional per-chunk durability offset; when present, chunks are envelope-encoded + ## Returns `ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\> @@ -42,7 +57,7 @@ ReadableStream in HTTP stream format (newline-delimited JSON) ## Example ```typescript -const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] }); +const stream = chat({ adapter: openaiText('gpt-5.5'), messages: [...] }); const readableStream = toHttpStream(stream); // Use with Response for HTTP streaming (not SSE) return new Response(readableStream, { diff --git a/docs/reference/functions/toServerSentEventsResponse.md b/docs/reference/functions/toServerSentEventsResponse.md index 482295fdba..4c0a4c290f 100644 --- a/docs/reference/functions/toServerSentEventsResponse.md +++ b/docs/reference/functions/toServerSentEventsResponse.md @@ -6,10 +6,10 @@ title: toServerSentEventsResponse # Function: toServerSentEventsResponse() ```ts -function toServerSentEventsResponse(stream, init?): Response; +function toServerSentEventsResponse(stream, init?): Response; ``` -Defined in: [packages/ai/src/stream-to-response.ts:120](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L120) +Defined in: [packages/ai/src/stream-to-response.ts:693](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L693) Convert a StreamChunk async iterable to a Response in Server-Sent Events format @@ -18,6 +18,18 @@ This creates a Response that emits chunks in SSE format: - Each chunk is followed by "\n\n" - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event) +Pass a `durability` sink (`memoryStream(request)` / `durableStream(request)`) +to make the stream resumable: fresh runs are appended to the log and each SSE +event is tagged with an `id:` offset; a reconnect (native `Last-Event-ID`) or +a `?offset` join replays from the log without re-running the producer. `batch` +controls how many chunks are buffered per `append` (default 32). + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` = `string` + ## Parameters ### stream @@ -30,7 +42,7 @@ AsyncIterable of StreamChunks from chat() `ResponseInit` & `object` -Optional Response initialization options (including `abortController`) +Optional Response initialization options (including `abortController`, `durability` with its optional `batch`, and `debug`) ## Returns @@ -41,6 +53,8 @@ Response in Server-Sent Events format ## Example ```typescript -const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] }); -return toServerSentEventsResponse(stream, { abortController }); +export async function POST(request: Request) { + const stream = chat({ adapter: openaiText('gpt-5.5'), messages: [...] }); + return toServerSentEventsResponse(stream, { durability: { adapter: memoryStream(request) } }); +} ``` diff --git a/docs/reference/functions/toServerSentEventsStream.md b/docs/reference/functions/toServerSentEventsStream.md index e2d5f559cb..5d2403a869 100644 --- a/docs/reference/functions/toServerSentEventsStream.md +++ b/docs/reference/functions/toServerSentEventsStream.md @@ -6,10 +6,13 @@ title: toServerSentEventsStream # Function: toServerSentEventsStream() ```ts -function toServerSentEventsStream(stream, abortController?): ReadableStream>; +function toServerSentEventsStream( + stream, + abortController?, +getId?): ReadableStream>; ``` -Defined in: [packages/ai/src/stream-to-response.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L50) +Defined in: [packages/ai/src/stream-to-response.ts:260](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L260) Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format @@ -32,6 +35,12 @@ AsyncIterable of StreamChunks from chat() Optional AbortController to abort when stream is cancelled +### getId? + +(`chunk`, `index`) => `string` \| `undefined` + +Optional per-chunk durability offset; when present, each event gets an `id:` line + ## Returns `ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\> diff --git a/docs/reference/functions/toolDefinition.md b/docs/reference/functions/toolDefinition.md index 59451f529a..7fcbebd1b4 100644 --- a/docs/reference/functions/toolDefinition.md +++ b/docs/reference/functions/toolDefinition.md @@ -6,22 +6,10 @@ title: toolDefinition # Function: toolDefinition() ```ts -function toolDefinition< - TInput, - TOutput, - TName, - TNeedsApproval, - TApprovalSchema, ->(config): ToolDefinition< - TInput, - TOutput, - TName, - TNeedsApproval, - TApprovalSchema -> +function toolDefinition(config): ToolDefinition; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:209](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L209) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:331](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L331) Create an isomorphic tool definition that can be used directly or instantiated for server/client @@ -33,43 +21,15 @@ The definition contains all tool metadata (name, description, schemas) and can b Supports any Standard JSON Schema compliant library (Zod v4+, ArkType, Valibot, etc.) or plain JSON Schema objects. -## Conditional approval schema - -`approvalSchema` is available only when `needsApproval: true`. It accepts either -one Standard Schema/JSON Schema for both decisions or a nonempty branch map: - -```ts -type ApprovalSchemaConfig = - | SchemaInput - | { approve: SchemaInput; reject?: SchemaInput } - | { approve?: SchemaInput; reject: SchemaInput } -``` - -The schema generic is preserved by `.server()` and `.client()`. Client -`tool-approval` interrupts infer the selected branch payload, require it when -the schema requires it, and place it under `payload`. Approval may also carry an -optional, fully validated `editedArgs` replacement when the tool has an input -schema. Rejection never accepts edited arguments. - -Plain JSON Schema remains runtime-only and therefore produces `unknown` payload -data. Standard Schema inputs such as Zod infer both runtime validation and the -bound resolver overloads. - -At runtime, defining `approvalSchema` without `needsApproval: true` throws. -TanStack AI converts the input, output, and selected approval branches to -canonical JSON Schema, embeds their hashes in the protected interrupt binding, -and validates again on resume. See [Interrupts](../../interrupts/overview) for the -full lifecycle. - ## Type Parameters ### TInput -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TOutput -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TName @@ -77,23 +37,23 @@ full lifecycle. ### TNeedsApproval -`TNeedsApproval` *extends* `boolean` = `false`. The literal `true` enables the -approval capability in mapped client interrupt types. +`TNeedsApproval` *extends* `boolean` = `false` ### TApprovalSchema -`TApprovalSchema` *extends* `ApprovalSchemaConfig | undefined` = `undefined`. -This generic is conditionally permitted only when `TNeedsApproval` is `true`. +`TApprovalSchema` *extends* + \| [`ApprovalSchemaConfig`](../type-aliases/ApprovalSchemaConfig.md) + \| `undefined` = `undefined` ## Parameters ### config -[`ToolDefinitionConfig`](../interfaces/ToolDefinitionConfig.md)\<`TInput`, `TOutput`, `TName`, `TNeedsApproval`\> +[`ToolDefinitionConfig`](../type-aliases/ToolDefinitionConfig.md)\<`TInput`, `TOutput`, `TName`, `TNeedsApproval`, `TApprovalSchema`\> ## Returns -[`ToolDefinition`](../interfaces/ToolDefinition.md)\<`TInput`, `TOutput`, `TName`, `TNeedsApproval`\> +[`ToolDefinition`](../interfaces/ToolDefinition.md)\<`TInput`, `TOutput`, `TName`, `TNeedsApproval`, `TApprovalSchema`\> ## Example @@ -115,10 +75,6 @@ const addToCartTool = toolDefinition({ cartId: z.string(), totalItems: z.number(), }), - approvalSchema: { - approve: z.object({ note: z.string() }), - reject: z.object({ reason: z.string() }), - }, }); // Use directly in chat (server-side, no execute function) @@ -143,17 +99,3 @@ const addToCartClient = addToCartTool.client(async (args) => { return { success: true, cartId: 'local', totalItems: 1 }; }); ``` - -With `tools: [addToCartTool] as const`, the corresponding bound approval has -branch-specific overloads: - -```ts -interrupt.resolveInterrupt(true, { - editedArgs: { guitarId: 'guitar-2', quantity: 2 }, - payload: { note: 'Reviewed' }, -}) - -interrupt.resolveInterrupt(false, { - payload: { reason: 'Budget limit' }, -}) -``` diff --git a/docs/reference/functions/untilFinishReason.md b/docs/reference/functions/untilFinishReason.md index 5ef6f72e91..91eb2a2762 100644 --- a/docs/reference/functions/untilFinishReason.md +++ b/docs/reference/functions/untilFinishReason.md @@ -9,7 +9,7 @@ title: untilFinishReason function untilFinishReason(stopReasons): AgentLoopStrategy; ``` -Defined in: [packages/ai/src/activities/chat/agent-loop-strategies.ts:80](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/agent-loop-strategies.ts#L80) +Defined in: [packages/ai/src/activities/chat/agent-loop-strategies.ts:47](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/agent-loop-strategies.ts#L47) Creates a strategy that continues until a specific finish reason is encountered diff --git a/docs/reference/functions/validateInterruptResumeBatch.md b/docs/reference/functions/validateInterruptResumeBatch.md new file mode 100644 index 0000000000..83040abb31 --- /dev/null +++ b/docs/reference/functions/validateInterruptResumeBatch.md @@ -0,0 +1,25 @@ +--- +id: validateInterruptResumeBatch +title: validateInterruptResumeBatch +--- + +# Function: validateInterruptResumeBatch() + +```ts +function validateInterruptResumeBatch(input): Promise; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:243](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L243) + +Validate and translate a complete interrupt batch before any tool executes. +Used by ephemeral chat resume; a durable layer may share the same validator. + +## Parameters + +### input + +[`ValidateInterruptResumeBatchInput`](../interfaces/ValidateInterruptResumeBatchInput.md) + +## Returns + +`Promise`\<[`ValidatedInterruptResumeBatch`](../interfaces/ValidatedInterruptResumeBatch.md)\> diff --git a/docs/reference/functions/validateWithStandardSchema.md b/docs/reference/functions/validateWithStandardSchema.md new file mode 100644 index 0000000000..6010c896b4 --- /dev/null +++ b/docs/reference/functions/validateWithStandardSchema.md @@ -0,0 +1,56 @@ +--- +id: validateWithStandardSchema +title: validateWithStandardSchema +--- + +# Function: validateWithStandardSchema() + +```ts +function validateWithStandardSchema(schema, data): Promise< + | { + data: T; + success: true; +} + | { + issues: object[]; + success: false; +}>; +``` + +Defined in: [packages/ai/src/activities/chat/tools/schema-converter.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/schema-converter.ts#L383) + +Validates data against a Standard Schema compliant schema. + +## Type Parameters + +### T + +`T` + +## Parameters + +### schema + +`unknown` + +Standard Schema compliant schema + +### data + +`unknown` + +Data to validate + +## Returns + +`Promise`\< + \| \{ + `data`: `T`; + `success`: `true`; +\} + \| \{ + `issues`: `object`[]; + `success`: `false`; +\}\> + +Validation result with success status, data or issues diff --git a/docs/reference/functions/wasCancelRequested.md b/docs/reference/functions/wasCancelRequested.md new file mode 100644 index 0000000000..babe6cd84a --- /dev/null +++ b/docs/reference/functions/wasCancelRequested.md @@ -0,0 +1,41 @@ +--- +id: wasCancelRequested +title: wasCancelRequested +--- + +# Function: wasCancelRequested() + +```ts +function wasCancelRequested(runs, runId): Promise; +``` + +Defined in: [packages/ai/src/activities/chat/cancel.ts:71](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/cancel.ts#L71) + +Whether an explicit cancel has been recorded for `runId`. + +Answers `false` rather than throwing when the store cannot be read. Callers +are middleware abort hooks, which are already on a teardown path, and a +store failure there must not replace the caller's own reason for tearing +down with a store error. The cost of a false negative is that a cancel +degrades into a detach — the run record gains `detachedSince`/`sandboxKey` +instead of transitioning to `'aborted'`. `@tanstack/ai-sandbox`'s +`reapDetachedRuns` recovers that run once the `detachedRunTtlMs` the +application passes to that sweep has elapsed — nothing derives it from +`withSandbox`, which has no TTL option — so the cost is a delayed teardown +rather than a lost one, provided the application actually schedules the +sweep, which is its job and not the framework's. Still strictly better than +failing the teardown. + +## Parameters + +### runs + +[`RunStore`](../interfaces/RunStore.md) + +### runId + +`string` + +## Returns + +`Promise`\<`boolean`\> diff --git a/docs/reference/functions/withInterruptBinding.md b/docs/reference/functions/withInterruptBinding.md new file mode 100644 index 0000000000..bf4deed393 --- /dev/null +++ b/docs/reference/functions/withInterruptBinding.md @@ -0,0 +1,37 @@ +--- +id: withInterruptBinding +title: withInterruptBinding +--- + +# Function: withInterruptBinding() + +```ts +function withInterruptBinding(descriptor, binding): Interrupt; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:771](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L771) + +Attach a resume binding to an interrupt descriptor, under +[INTERRUPT\_BINDING\_METADATA\_KEY](../variables/INTERRUPT_BINDING_METADATA_KEY.md). + +This is the supported way to make an interrupt resumable by this package. +The descriptor keeps its AG-UI shape; only `metadata` gains the namespaced +key. Pass the unopened form (no `interruptedRunId` / `generation`) when +emitting from inside a run — those fields are stamped as the run finishes. + +## Parameters + +### descriptor + +`Interrupt` + +### binding + + \| [`InterruptBinding`](../type-aliases/InterruptBinding.md) + \| `Omit`\<`InterruptBindingBase` & `object`, `"interruptedRunId"` \| `"generation"`\> + \| `Omit`\<`InterruptBindingBase` & `object`, `"interruptedRunId"` \| `"generation"`\> + \| `Omit`\<`InterruptBindingBase` & `object`, `"interruptedRunId"` \| `"generation"`\> + +## Returns + +`Interrupt` diff --git a/docs/reference/functions/withoutInterruptBinding.md b/docs/reference/functions/withoutInterruptBinding.md new file mode 100644 index 0000000000..061440800d --- /dev/null +++ b/docs/reference/functions/withoutInterruptBinding.md @@ -0,0 +1,22 @@ +--- +id: withoutInterruptBinding +title: withoutInterruptBinding +--- + +# Function: withoutInterruptBinding() + +```ts +function withoutInterruptBinding(descriptor): Interrupt; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:818](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L818) + +## Parameters + +### descriptor + +`Interrupt` + +## Returns + +`Interrupt` diff --git a/docs/reference/index.md b/docs/reference/index.md index 73f19eec0f..76a9dc60b8 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -7,10 +7,13 @@ title: "@tanstack/ai" ## Classes +- [BaseRerankAdapter](classes/BaseRerankAdapter.md) - [BatchStrategy](classes/BatchStrategy.md) - [CompositeStrategy](classes/CompositeStrategy.md) - [ConsoleLogger](classes/ConsoleLogger.md) - [ImmediateStrategy](classes/ImmediateStrategy.md) +- [InMemoryRunStore](classes/InMemoryRunStore.md) +- [InterruptResumeValidationError](classes/InterruptResumeValidationError.md) - [MCPDuplicateToolNameError](classes/MCPDuplicateToolNameError.md) - [PartialJSONParser](classes/PartialJSONParser.md) - [PunctuationStrategy](classes/PunctuationStrategy.md) @@ -24,7 +27,10 @@ title: "@tanstack/ai" - [AbortInfo](interfaces/AbortInfo.md) - [AfterToolCallInfo](interfaces/AfterToolCallInfo.md) - [AgentLoopState](interfaces/AgentLoopState.md) -- [ApprovalRequestedEvent](interfaces/ApprovalRequestedEvent.md) +- [~~ApprovalRequestedEvent~~](interfaces/ApprovalRequestedEvent.md) +- [ApprovalRequestedPayload](interfaces/ApprovalRequestedPayload.md) +- [ApprovalResolvedPayload](interfaces/ApprovalResolvedPayload.md) +- [ArtifactCreatedPayload](interfaces/ArtifactCreatedPayload.md) - [AudioAdapter](interfaces/AudioAdapter.md) - [AudioGenerationOptions](interfaces/AudioGenerationOptions.md) - [AudioGenerationResult](interfaces/AudioGenerationResult.md) @@ -32,12 +38,14 @@ title: "@tanstack/ai" - [AudioVisualization](interfaces/AudioVisualization.md) - [BaseAGUIEvent](interfaces/BaseAGUIEvent.md) - [BaseUsageInput](interfaces/BaseUsageInput.md) +- [BatchInterruptError](interfaces/BatchInterruptError.md) - [CapabilityContext](interfaces/CapabilityContext.md) - [CapabilityGetter](interfaces/CapabilityGetter.md) - [ChatMCPOptions](interfaces/ChatMCPOptions.md) - [ChatMiddleware](interfaces/ChatMiddleware.md) - [ChatMiddlewareConfig](interfaces/ChatMiddlewareConfig.md) - [ChatMiddlewareContext](interfaces/ChatMiddlewareContext.md) +- [ChatResumeToolState](interfaces/ChatResumeToolState.md) - [ChatSandboxHooks](interfaces/ChatSandboxHooks.md) - [ChunkRecording](interfaces/ChunkRecording.md) - [ChunkStrategy](interfaces/ChunkStrategy.md) @@ -58,21 +66,29 @@ title: "@tanstack/ai" - [DefaultMessageMetadataByModality](interfaces/DefaultMessageMetadataByModality.md) - [DefinedChatMiddleware](interfaces/DefinedChatMiddleware.md) - [DocumentPart](interfaces/DocumentPart.md) +- [Embedding](interfaces/Embedding.md) +- [EmbeddingAdapter](interfaces/EmbeddingAdapter.md) +- [EmbeddingOptions](interfaces/EmbeddingOptions.md) +- [EmbeddingResult](interfaces/EmbeddingResult.md) - [ErrorInfo](interfaces/ErrorInfo.md) - [ExtendedModelDef](interfaces/ExtendedModelDef.md) - [FileChangedEvent](interfaces/FileChangedEvent.md) +- [FileChangedPayload](interfaces/FileChangedPayload.md) - [FinishInfo](interfaces/FinishInfo.md) - [GenerationAbortInfo](interfaces/GenerationAbortInfo.md) - [GenerationErrorInfo](interfaces/GenerationErrorInfo.md) - [GenerationFinishInfo](interfaces/GenerationFinishInfo.md) - [GenerationMiddleware](interfaces/GenerationMiddleware.md) - [GenerationMiddlewareContext](interfaces/GenerationMiddlewareContext.md) +- [GenerationResultTransformContext](interfaces/GenerationResultTransformContext.md) - [GenerationUsageInfo](interfaces/GenerationUsageInfo.md) - [ImageAdapter](interfaces/ImageAdapter.md) - [ImageGenerationOptions](interfaces/ImageGenerationOptions.md) - [ImageGenerationResult](interfaces/ImageGenerationResult.md) - [ImagePart](interfaces/ImagePart.md) - [InternalToolCallState](interfaces/InternalToolCallState.md) +- [InterruptCorrelation](interfaces/InterruptCorrelation.md) +- [ItemInterruptError](interfaces/ItemInterruptError.md) - [IterationInfo](interfaces/IterationInfo.md) - [JSONParser](interfaces/JSONParser.md) - [JSONSchema](interfaces/JSONSchema.md) @@ -80,12 +96,20 @@ title: "@tanstack/ai" - [Logger](interfaces/Logger.md) - [MCPToolSource](interfaces/MCPToolSource.md) - [MediaInputMetadata](interfaces/MediaInputMetadata.md) +- [MemoryStreamInit](interfaces/MemoryStreamInit.md) +- [MemoryStreamOptions](interfaces/MemoryStreamOptions.md) - [MessagesSnapshotEvent](interfaces/MessagesSnapshotEvent.md) - [ModelCapabilities](interfaces/ModelCapabilities.md) - [ModelMessage](interfaces/ModelMessage.md) +- [NormalizedApprovalSchema](interfaces/NormalizedApprovalSchema.md) +- [NormalizedSchemaInput](interfaces/NormalizedSchemaInput.md) - [NormalizedSystemPrompt](interfaces/NormalizedSystemPrompt.md) +- [PendingInterruptResumeRecord](interfaces/PendingInterruptResumeRecord.md) +- [PersistedArtifactRef](interfaces/PersistedArtifactRef.md) +- [PortOpenedPayload](interfaces/PortOpenedPayload.md) - [ProcessorResult](interfaces/ProcessorResult.md) - [ProcessorState](interfaces/ProcessorState.md) +- [ProcessOutputPayload](interfaces/ProcessOutputPayload.md) - [ProviderExecutedToolMetadata](interfaces/ProviderExecutedToolMetadata.md) - [ProviderTool](interfaces/ProviderTool.md) - [RealtimeAdapter](interfaces/RealtimeAdapter.md) @@ -109,15 +133,26 @@ title: "@tanstack/ai" - [ReasoningMessageEndEvent](interfaces/ReasoningMessageEndEvent.md) - [ReasoningMessageStartEvent](interfaces/ReasoningMessageStartEvent.md) - [ReasoningStartEvent](interfaces/ReasoningStartEvent.md) +- [RerankAdapter](interfaces/RerankAdapter.md) +- [RerankAdapterResult](interfaces/RerankAdapterResult.md) +- [RerankOptions](interfaces/RerankOptions.md) +- [RerankResult](interfaces/RerankResult.md) +- [ResolvedEmbeddingItem](interfaces/ResolvedEmbeddingItem.md) - [ResolvedMediaPrompt](interfaces/ResolvedMediaPrompt.md) - [ResponseFormat](interfaces/ResponseFormat.md) +- [RunDriverOptions](interfaces/RunDriverOptions.md) +- [RunError](interfaces/RunError.md) - [RunErrorEvent](interfaces/RunErrorEvent.md) - [RunFinishedEvent](interfaces/RunFinishedEvent.md) +- [RunRecord](interfaces/RunRecord.md) - [RunStartedEvent](interfaces/RunStartedEvent.md) +- [RunStore](interfaces/RunStore.md) - [SandboxFileCustomEvent](interfaces/SandboxFileCustomEvent.md) - [SandboxFileDiffEvent](interfaces/SandboxFileDiffEvent.md) - [SandboxFileEvent](interfaces/SandboxFileEvent.md) - [SandboxFileHookEvent](interfaces/SandboxFileHookEvent.md) +- [SandboxLifecyclePayload](interfaces/SandboxLifecyclePayload.md) +- [Scope](interfaces/Scope.md) - [ServerTool](interfaces/ServerTool.md) - [SessionIdEvent](interfaces/SessionIdEvent.md) - [SkillRegisteredEvent](interfaces/SkillRegisteredEvent.md) @@ -125,6 +160,7 @@ title: "@tanstack/ai" - [StateSnapshotEvent](interfaces/StateSnapshotEvent.md) - [StepFinishedEvent](interfaces/StepFinishedEvent.md) - [StepStartedEvent](interfaces/StepStartedEvent.md) +- [StreamDurability](interfaces/StreamDurability.md) - [StreamProcessorEvents](interfaces/StreamProcessorEvents.md) - [StreamProcessorOptions](interfaces/StreamProcessorOptions.md) - [StructuredOutputCompleteEvent](interfaces/StructuredOutputCompleteEvent.md) @@ -152,9 +188,8 @@ title: "@tanstack/ai" - [ToolCallStartEvent](interfaces/ToolCallStartEvent.md) - [ToolConfig](interfaces/ToolConfig.md) - [ToolDefinition](interfaces/ToolDefinition.md) -- [ToolDefinitionConfig](interfaces/ToolDefinitionConfig.md) - [ToolDefinitionInstance](interfaces/ToolDefinitionInstance.md) -- [ToolInputAvailableEvent](interfaces/ToolInputAvailableEvent.md) +- [~~ToolInputAvailableEvent~~](interfaces/ToolInputAvailableEvent.md) - [ToolPhaseCompleteInfo](interfaces/ToolPhaseCompleteInfo.md) - [ToolRegistry](interfaces/ToolRegistry.md) - [ToolResultPart](interfaces/ToolResultPart.md) @@ -169,8 +204,11 @@ title: "@tanstack/ai" - [UIMessage](interfaces/UIMessage.md) - [UIResourceEvent](interfaces/UIResourceEvent.md) - [UIResourcePart](interfaces/UIResourcePart.md) +- [UpsertableStreamDurability](interfaces/UpsertableStreamDurability.md) - [UsageInfo](interfaces/UsageInfo.md) - [VADConfig](interfaces/VADConfig.md) +- [ValidatedInterruptResumeBatch](interfaces/ValidatedInterruptResumeBatch.md) +- [ValidateInterruptResumeBatchInput](interfaces/ValidateInterruptResumeBatchInput.md) - [VideoAdapter](interfaces/VideoAdapter.md) - [VideoGenerationOptions](interfaces/VideoGenerationOptions.md) - [VideoJobResult](interfaces/VideoJobResult.md) @@ -187,20 +225,29 @@ title: "@tanstack/ai" - [AnyAudioAdapter](type-aliases/AnyAudioAdapter.md) - [AnyChatMiddleware](type-aliases/AnyChatMiddleware.md) - [AnyClientTool](type-aliases/AnyClientTool.md) +- [AnyEmbeddingAdapter](type-aliases/AnyEmbeddingAdapter.md) - [AnyGenerationMiddleware](type-aliases/AnyGenerationMiddleware.md) - [AnyImageAdapter](type-aliases/AnyImageAdapter.md) +- [AnyRerankAdapter](type-aliases/AnyRerankAdapter.md) +- [AnyServerTool](type-aliases/AnyServerTool.md) - [AnySummarizeAdapter](type-aliases/AnySummarizeAdapter.md) - [AnyTextAdapter](type-aliases/AnyTextAdapter.md) - [AnyTool](type-aliases/AnyTool.md) - [AnyTranscriptionAdapter](type-aliases/AnyTranscriptionAdapter.md) - [AnyTTSAdapter](type-aliases/AnyTTSAdapter.md) - [AnyVideoAdapter](type-aliases/AnyVideoAdapter.md) +- [ApprovalCapabilityOf](type-aliases/ApprovalCapabilityOf.md) +- [ApprovalSchemaConfig](type-aliases/ApprovalSchemaConfig.md) +- [ApprovalSchemaOf](type-aliases/ApprovalSchemaOf.md) +- [BatchInterruptErrorCode](type-aliases/BatchInterruptErrorCode.md) - [BeforeToolCallDecision](type-aliases/BeforeToolCallDecision.md) - [Capability](type-aliases/Capability.md) - [CapabilityHandle](type-aliases/CapabilityHandle.md) - [CapabilityProvider](type-aliases/CapabilityProvider.md) - [ChatMiddlewarePhase](type-aliases/ChatMiddlewarePhase.md) +- [ChatResumeGenericResolution](type-aliases/ChatResumeGenericResolution.md) - [ChatStream](type-aliases/ChatStream.md) +- [ClientToolDeclaration](type-aliases/ClientToolDeclaration.md) - [ConstrainedContent](type-aliases/ConstrainedContent.md) - [ConstrainedModelMessage](type-aliases/ConstrainedModelMessage.md) - [ContentPart](type-aliases/ContentPart.md) @@ -208,15 +255,26 @@ title: "@tanstack/ai" - [ContentPartSource](type-aliases/ContentPartSource.md) - [DebugOption](type-aliases/DebugOption.md) - [DeepPartial](type-aliases/DeepPartial.md) +- [EmbeddingContentParts](type-aliases/EmbeddingContentParts.md) +- [EmbeddingInputItem](type-aliases/EmbeddingInputItem.md) +- [EmbeddingInputItemFor](type-aliases/EmbeddingInputItemFor.md) +- [EmbeddingModality](type-aliases/EmbeddingModality.md) +- [EmbeddingModelInputModalitiesByName](type-aliases/EmbeddingModelInputModalitiesByName.md) - [GeneratedAudio](type-aliases/GeneratedAudio.md) - [GeneratedImage](type-aliases/GeneratedImage.md) - [GeneratedMediaSource](type-aliases/GeneratedMediaSource.md) - [GenerationActivity](type-aliases/GenerationActivity.md) +- [GenerationResultTransform](type-aliases/GenerationResultTransform.md) - [InferSchemaType](type-aliases/InferSchemaType.md) - [InferToolInput](type-aliases/InferToolInput.md) - [InferToolName](type-aliases/InferToolName.md) - [InferToolOutput](type-aliases/InferToolOutput.md) - [InputModalitiesTypes](type-aliases/InputModalitiesTypes.md) +- [InputSchemaOf](type-aliases/InputSchemaOf.md) +- [Interrupt](type-aliases/Interrupt.md) +- [InterruptBinding](type-aliases/InterruptBinding.md) +- [InterruptSubmissionError](type-aliases/InterruptSubmissionError.md) +- [ItemInterruptErrorCode](type-aliases/ItemInterruptErrorCode.md) - [KnownCustomEvent](type-aliases/KnownCustomEvent.md) - [MCPConnectionPolicy](type-aliases/MCPConnectionPolicy.md) - [MediaInputRole](type-aliases/MediaInputRole.md) @@ -224,61 +282,96 @@ title: "@tanstack/ai" - [MediaPromptFor](type-aliases/MediaPromptFor.md) - [MediaPromptModality](type-aliases/MediaPromptModality.md) - [MediaPromptPart](type-aliases/MediaPromptPart.md) +- [MergedAgentTools](type-aliases/MergedAgentTools.md) - [MessagePart](type-aliases/MessagePart.md) - [ModalitiesArrayToUnion](type-aliases/ModalitiesArrayToUnion.md) - [Modality](type-aliases/Modality.md) - [ModelInputModalitiesByName](type-aliases/ModelInputModalitiesByName.md) +- [NoSchema](type-aliases/NoSchema.md) +- [OutputSchemaOf](type-aliases/OutputSchemaOf.md) +- [PersistedArtifactActivity](type-aliases/PersistedArtifactActivity.md) +- [PersistedArtifactRole](type-aliases/PersistedArtifactRole.md) - [RealtimeErrorCode](type-aliases/RealtimeErrorCode.md) - [RealtimeEvent](type-aliases/RealtimeEvent.md) - [RealtimeEventHandler](type-aliases/RealtimeEventHandler.md) - [RealtimeMessagePart](type-aliases/RealtimeMessagePart.md) - [RealtimeMode](type-aliases/RealtimeMode.md) - [RealtimeStatus](type-aliases/RealtimeStatus.md) +- [RunAgentResumeItem](type-aliases/RunAgentResumeItem.md) +- [RunFinishedOutcome](type-aliases/RunFinishedOutcome.md) +- [RunStatus](type-aliases/RunStatus.md) - [SchemaInput](type-aliases/SchemaInput.md) - [StreamChunk](type-aliases/StreamChunk.md) - [~~StreamChunkType~~](type-aliases/StreamChunkType.md) - [StructuredOutputStream](type-aliases/StructuredOutputStream.md) - [SystemPrompt](type-aliases/SystemPrompt.md) +- [TaggedCustomEvent](type-aliases/TaggedCustomEvent.md) +- [TerminalRunStatus](type-aliases/TerminalRunStatus.md) +- [ToolApprovalResolution](type-aliases/ToolApprovalResolution.md) - [ToolCallState](type-aliases/ToolCallState.md) +- [ToolDefinitionConfig](type-aliases/ToolDefinitionConfig.md) - [ToolExecuteFunction](type-aliases/ToolExecuteFunction.md) - [ToolExecutionContext](type-aliases/ToolExecutionContext.md) - [ToolOutputState](type-aliases/ToolOutputState.md) - [ToolResultState](type-aliases/ToolResultState.md) - [TranscriptionResponseFormat](type-aliases/TranscriptionResponseFormat.md) +- [TypedStreamChunk](type-aliases/TypedStreamChunk.md) +- [UnopenedInterruptBinding](type-aliases/UnopenedInterruptBinding.md) - [~~UsageTotals~~](type-aliases/UsageTotals.md) +- [WellKnownCustomEventName](type-aliases/WellKnownCustomEventName.md) - [WireMessage](type-aliases/WireMessage.md) ## Variables +- [CUSTOM\_EVENT](variables/CUSTOM_EVENT.md) - [defaultJSONParser](variables/defaultJSONParser.md) +- [DetachableRunCapability](variables/DetachableRunCapability.md) - [DISCOVERY\_TOOL\_NAME](variables/DISCOVERY_TOOL_NAME.md) +- [getDetachableRun](variables/getDetachableRun.md) +- [getRunDetached](variables/getRunDetached.md) +- [INTERRUPT\_BINDING\_METADATA\_KEY](variables/INTERRUPT_BINDING_METADATA_KEY.md) +- [INTERRUPT\_BINDING\_VERSION](variables/INTERRUPT_BINDING_VERSION.md) +- [provideDetachableRun](variables/provideDetachableRun.md) +- [provideRunDetached](variables/provideRunDetached.md) +- [RUN\_ACCEPTED\_EVENT](variables/RUN_ACCEPTED_EVENT.md) +- [RUN\_CANCEL\_REASON](variables/RUN_CANCEL_REASON.md) +- [RunDetachedCapability](variables/RunDetachedCapability.md) ## Functions - [brandProviderTool](functions/brandProviderTool.md) - [buildBaseUsage](functions/buildBaseUsage.md) +- [canonicalInterruptJson](functions/canonicalInterruptJson.md) +- [canonicalizeInterruptResolutions](functions/canonicalizeInterruptResolutions.md) - [chat](functions/chat.md) - [chatParamsFromRequest](functions/chatParamsFromRequest.md) - [chatParamsFromRequestBody](functions/chatParamsFromRequestBody.md) +- [cloneAndDeepFreezeJson](functions/cloneAndDeepFreezeJson.md) - [combineStrategies](functions/combineStrategies.md) - [convertMessagesToModelMessages](functions/convertMessagesToModelMessages.md) - [convertSchemaToJsonSchema](functions/convertSchemaToJsonSchema.md) +- [countEmbeddingInputModalities](functions/countEmbeddingInputModalities.md) - [createAudioOptions](functions/createAudioOptions.md) - [createCapability](functions/createCapability.md) - [createChatMiddleware](functions/createChatMiddleware.md) - [createChatOptions](functions/createChatOptions.md) +- [createEmbedOptions](functions/createEmbedOptions.md) - [createFrozenRegistry](functions/createFrozenRegistry.md) - [createImageOptions](functions/createImageOptions.md) - [createModel](functions/createModel.md) - [createRealtimeEventEmitter](functions/createRealtimeEventEmitter.md) - [createReplayStream](functions/createReplayStream.md) +- [createRerankOptions](functions/createRerankOptions.md) - [createSpeechOptions](functions/createSpeechOptions.md) - [createSummarizeOptions](functions/createSummarizeOptions.md) - [createToolRegistry](functions/createToolRegistry.md) - [createTranscriptionOptions](functions/createTranscriptionOptions.md) - [createVideoOptions](functions/createVideoOptions.md) - [defineChatMiddleware](functions/defineChatMiddleware.md) +- [defineRunStore](functions/defineRunStore.md) - [detectImageMimeType](functions/detectImageMimeType.md) +- [digestInterruptJson](functions/digestInterruptJson.md) +- [embed](functions/embed.md) - [extendAdapter](functions/extendAdapter.md) - [firstSentence](functions/firstSentence.md) - [generateAudio](functions/generateAudio.md) @@ -287,24 +380,44 @@ title: "@tanstack/ai" - [generateSpeech](functions/generateSpeech.md) - [generateTranscription](functions/generateTranscription.md) - [generateVideo](functions/generateVideo.md) +- [generationParamsFromBody](functions/generationParamsFromBody.md) +- [generationParamsFromRequest](functions/generationParamsFromRequest.md) - [getProviderExecutedMetadata](functions/getProviderExecutedMetadata.md) - [getVideoJobStatus](functions/getVideoJobStatus.md) +- [hashSchemaInput](functions/hashSchemaInput.md) +- [interruptItemError](functions/interruptItemError.md) +- [isCancelRequestedReason](functions/isCancelRequestedReason.md) - [isContentPart](functions/isContentPart.md) - [isContentPartArray](functions/isContentPartArray.md) +- [isCustomEvent](functions/isCustomEvent.md) - [isProviderExecutedToolCall](functions/isProviderExecutedToolCall.md) +- [isRunStatus](functions/isRunStatus.md) - [isStandardSchema](functions/isStandardSchema.md) +- [isTerminalRunStatus](functions/isTerminalRunStatus.md) - [maxIterations](functions/maxIterations.md) +- [memoryStream](functions/memoryStream.md) - [mergeAgentTools](functions/mergeAgentTools.md) - [modelMessagesToUIMessages](functions/modelMessagesToUIMessages.md) - [modelMessageToUIMessage](functions/modelMessageToUIMessage.md) +- [normalizeApprovalSchema](functions/normalizeApprovalSchema.md) - [normalizeSystemPrompts](functions/normalizeSystemPrompts.md) - [normalizeToolResult](functions/normalizeToolResult.md) - [normalizeToUIMessage](functions/normalizeToUIMessage.md) - [parsePartialJSON](functions/parsePartialJSON.md) - [parseWithStandardSchema](functions/parseWithStandardSchema.md) +- [readInterruptBinding](functions/readInterruptBinding.md) +- [readUnopenedInterruptBinding](functions/readUnopenedInterruptBinding.md) - [realtimeToken](functions/realtimeToken.md) - [renderLazyCatalogEntry](functions/renderLazyCatalogEntry.md) +- [replayRunStream](functions/replayRunStream.md) +- [requestRunCancel](functions/requestRunCancel.md) +- [requireTextOnlyEmbeddingInput](functions/requireTextOnlyEmbeddingInput.md) +- [rerank](functions/rerank.md) +- [resolveEmbeddingInput](functions/resolveEmbeddingInput.md) - [resolveMediaPrompt](functions/resolveMediaPrompt.md) +- [resolveResumeRunId](functions/resolveResumeRunId.md) +- [resumeHttpResponse](functions/resumeHttpResponse.md) +- [resumeServerSentEventsResponse](functions/resumeServerSentEventsResponse.md) - [streamToText](functions/streamToText.md) - [summarize](functions/summarize.md) - [toHttpResponse](functions/toHttpResponse.md) @@ -315,3 +428,8 @@ title: "@tanstack/ai" - [uiMessagesToWire](functions/uiMessagesToWire.md) - [uiMessageToModelMessages](functions/uiMessageToModelMessages.md) - [untilFinishReason](functions/untilFinishReason.md) +- [validateInterruptResumeBatch](functions/validateInterruptResumeBatch.md) +- [validateWithStandardSchema](functions/validateWithStandardSchema.md) +- [wasCancelRequested](functions/wasCancelRequested.md) +- [withInterruptBinding](functions/withInterruptBinding.md) +- [withoutInterruptBinding](functions/withoutInterruptBinding.md) diff --git a/docs/reference/interfaces/AbortInfo.md b/docs/reference/interfaces/AbortInfo.md index 7f9b599ef3..fd29267634 100644 --- a/docs/reference/interfaces/AbortInfo.md +++ b/docs/reference/interfaces/AbortInfo.md @@ -5,19 +5,43 @@ title: AbortInfo # Interface: AbortInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:371](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L371) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:397](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L397) Information passed to onAbort. ## Properties +### cancelRequested? + +```ts +optional cancelRequested?: boolean; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:417](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L417) + +True only when the abort came from an explicit, out-of-band cancel (e.g. a +cancel endpoint setting `RunRecord.cancelRequested`), never from a mere +client disconnect. + +A disconnect and a user pressing "stop" are the SAME connection close on +the wire, so consumers must not infer intent from an abort alone. Middleware +that tears down expensive resources reads this to distinguish "the viewer +left, keep going" from "the user wants this stopped". Populated from the +abort reason: `true` exactly when the run was aborted with `RUN_CANCEL_REASON` +(matched with `===`, so an arbitrary error message can never be read as a +deliberate cancel), `false` for every other abort. The durable channel is +separate — middleware that must also catch a cancel recorded on a different +host reads `RunRecord.cancelRequested` in addition to this flag. + +*** + ### duration ```ts duration: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:375](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L375) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:401](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L401) Duration until abort in milliseconds @@ -26,9 +50,9 @@ Duration until abort in milliseconds ### reason? ```ts -optional reason: string; +optional reason?: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:373](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L373) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:399](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L399) The reason for the abort, if provided diff --git a/docs/reference/interfaces/AfterToolCallInfo.md b/docs/reference/interfaces/AfterToolCallInfo.md index 6a249ab660..013831b921 100644 --- a/docs/reference/interfaces/AfterToolCallInfo.md +++ b/docs/reference/interfaces/AfterToolCallInfo.md @@ -5,7 +5,7 @@ title: AfterToolCallInfo # Interface: AfterToolCallInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:271](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L271) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:297](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L297) Outcome information provided to onAfterToolCall. @@ -17,7 +17,7 @@ Outcome information provided to onAfterToolCall. duration: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:283](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L283) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:309](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L309) Duration of tool execution in milliseconds @@ -26,10 +26,10 @@ Duration of tool execution in milliseconds ### error? ```ts -optional error: unknown; +optional error?: unknown; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:286](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L286) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:312](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L312) *** @@ -39,7 +39,7 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:286](https://gi ok: boolean; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:281](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L281) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:307](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L307) Whether the execution succeeded @@ -48,10 +48,10 @@ Whether the execution succeeded ### result? ```ts -optional result: unknown; +optional result?: unknown; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:285](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L285) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:311](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L311) The result (if ok) or error (if not ok) @@ -65,7 +65,7 @@ tool: | undefined; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:275](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L275) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:301](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L301) The resolved tool definition @@ -77,7 +77,7 @@ The resolved tool definition toolCall: ToolCall; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:273](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L273) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:299](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L299) The tool call that was executed @@ -89,7 +89,7 @@ The tool call that was executed toolCallId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:279](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L279) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:305](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L305) ID of the tool call @@ -101,6 +101,6 @@ ID of the tool call toolName: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:277](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L277) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:303](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L303) Name of the tool diff --git a/docs/reference/interfaces/AgentLoopState.md b/docs/reference/interfaces/AgentLoopState.md index ff5c224ce2..cef4d1bea7 100644 --- a/docs/reference/interfaces/AgentLoopState.md +++ b/docs/reference/interfaces/AgentLoopState.md @@ -5,7 +5,7 @@ title: AgentLoopState # Interface: AgentLoopState -Defined in: [packages/ai/src/types.ts:833](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L833) +Defined in: [packages/ai/src/types.ts:858](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L858) State passed to agent loop strategy for determining whether to continue @@ -17,7 +17,7 @@ State passed to agent loop strategy for determining whether to continue finishReason: string | null; ``` -Defined in: [packages/ai/src/types.ts:839](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L839) +Defined in: [packages/ai/src/types.ts:864](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L864) Finish reason from the last response @@ -29,7 +29,7 @@ Finish reason from the last response iterationCount: number; ``` -Defined in: [packages/ai/src/types.ts:835](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L835) +Defined in: [packages/ai/src/types.ts:860](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L860) Current iteration count (0-indexed). One iteration = one model turn. @@ -41,9 +41,9 @@ Current iteration count (0-indexed). One iteration = one model turn. lastTurnToolCallCount: number; ``` -Defined in: [packages/ai/src/types.ts:851](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L851) +Defined in: [packages/ai/src/types.ts:876](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L876) -Tool calls in the most recent budgeted batch — a live model turn or a +Tool calls in the most recent batch — a live model turn or a pending/resume batch (0 when the last phase produced no tool calls). *** @@ -57,7 +57,7 @@ messages: ModelMessage< | null>[]; ``` -Defined in: [packages/ai/src/types.ts:837](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L837) +Defined in: [packages/ai/src/types.ts:862](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L862) Current messages array @@ -69,7 +69,7 @@ Current messages array toolCallCount: number; ``` -Defined in: [packages/ai/src/types.ts:846](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L846) +Defined in: [packages/ai/src/types.ts:871](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L871) Cumulative tool calls counted so far in this run (model-emitted during the agent loop, including ones skipped by middleware, and pending tools from diff --git a/docs/reference/interfaces/ApprovalRequestedEvent.md b/docs/reference/interfaces/ApprovalRequestedEvent.md index d36e9aed62..051ea5798e 100644 --- a/docs/reference/interfaces/ApprovalRequestedEvent.md +++ b/docs/reference/interfaces/ApprovalRequestedEvent.md @@ -3,35 +3,28 @@ id: ApprovalRequestedEvent title: ApprovalRequestedEvent --- -# Interface: ApprovalRequestedEvent +# ~~Interface: ApprovalRequestedEvent~~ -Defined in: [packages/ai/src/types.ts:1387](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1387) +Defined in: [packages/ai/src/types.ts:1467](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1467) -Emitted when a server tool requires approval before execution. The agent -loop yields this and pauses — `structured-output.complete` will not fire -for that run. The shape is fixed by the orchestrator's tool-approval flow -(the agent-loop branch of `runStreamingStructuredOutputImpl` in -`activities/chat/index.ts` forwards CUSTOM events from `TextEngine.run()`). +## Deprecated + +Native interrupts use RUN_FINISHED interrupt outcomes. This +compatibility event remains readable until 1.0. ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties -### model? +### ~~model?~~ ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -41,13 +34,13 @@ Model identifier for multi-model support *** -### name +### ~~name~~ ```ts name: "approval-requested"; ``` -Defined in: [packages/ai/src/types.ts:1388](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1388) +Defined in: [packages/ai/src/types.ts:1468](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1468) #### Overrides @@ -57,15 +50,62 @@ CustomEvent.name *** -### value +### ~~runId?~~ + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### ~~threadId?~~ + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### ~~type~~ + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + +### ~~value~~ ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1389](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1389) +Defined in: [packages/ai/src/types.ts:1469](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1469) -#### approval +#### ~~approval~~ ```ts approval: object; @@ -83,19 +123,19 @@ id: string; needsApproval: true; ``` -#### input +#### ~~input~~ ```ts input: unknown; ``` -#### toolCallId +#### ~~toolCallId~~ ```ts toolCallId: string; ``` -#### toolName +#### ~~toolName~~ ```ts toolName: string; diff --git a/docs/reference/interfaces/ApprovalRequestedPayload.md b/docs/reference/interfaces/ApprovalRequestedPayload.md new file mode 100644 index 0000000000..b7e2036ea7 --- /dev/null +++ b/docs/reference/interfaces/ApprovalRequestedPayload.md @@ -0,0 +1,36 @@ +--- +id: ApprovalRequestedPayload +title: ApprovalRequestedPayload +--- + +# Interface: ApprovalRequestedPayload + +Defined in: [packages/ai/src/custom-events.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L57) + +## Indexable + +```ts +[key: string]: unknown +``` + +Free-form detail describing the action awaiting approval. + +## Properties + +### approvalId + +```ts +approvalId: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L58) + +*** + +### title + +```ts +title: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:59](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L59) diff --git a/docs/reference/interfaces/ApprovalResolvedPayload.md b/docs/reference/interfaces/ApprovalResolvedPayload.md new file mode 100644 index 0000000000..4067973eda --- /dev/null +++ b/docs/reference/interfaces/ApprovalResolvedPayload.md @@ -0,0 +1,28 @@ +--- +id: ApprovalResolvedPayload +title: ApprovalResolvedPayload +--- + +# Interface: ApprovalResolvedPayload + +Defined in: [packages/ai/src/custom-events.ts:64](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L64) + +## Properties + +### approvalId + +```ts +approvalId: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:65](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L65) + +*** + +### granted + +```ts +granted: boolean; +``` + +Defined in: [packages/ai/src/custom-events.ts:66](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L66) diff --git a/docs/reference/interfaces/ArtifactCreatedPayload.md b/docs/reference/interfaces/ArtifactCreatedPayload.md new file mode 100644 index 0000000000..692481b541 --- /dev/null +++ b/docs/reference/interfaces/ArtifactCreatedPayload.md @@ -0,0 +1,48 @@ +--- +id: ArtifactCreatedPayload +title: ArtifactCreatedPayload +--- + +# Interface: ArtifactCreatedPayload + +Defined in: [packages/ai/src/custom-events.ts:69](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L69) + +## Properties + +### artifactId + +```ts +artifactId: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:70](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L70) + +*** + +### mimeType + +```ts +mimeType: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L72) + +*** + +### name + +```ts +name: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:71](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L71) + +*** + +### size + +```ts +size: number; +``` + +Defined in: [packages/ai/src/custom-events.ts:73](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L73) diff --git a/docs/reference/interfaces/AudioAdapter.md b/docs/reference/interfaces/AudioAdapter.md index e668791005..3c4a8258e7 100644 --- a/docs/reference/interfaces/AudioAdapter.md +++ b/docs/reference/interfaces/AudioAdapter.md @@ -48,7 +48,7 @@ providerOptions: TProviderOptions; *** -### generateAudio() +### generateAudio ```ts generateAudio: (options) => Promise; diff --git a/docs/reference/interfaces/AudioGenerationOptions.md b/docs/reference/interfaces/AudioGenerationOptions.md index cc3159c32a..3a44dd39d1 100644 --- a/docs/reference/interfaces/AudioGenerationOptions.md +++ b/docs/reference/interfaces/AudioGenerationOptions.md @@ -5,7 +5,7 @@ title: AudioGenerationOptions # Interface: AudioGenerationOptions\ -Defined in: [packages/ai/src/types.ts:1882](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1882) +Defined in: [packages/ai/src/types.ts:2310](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2310) Options for audio generation (music, sound effects, etc.). These are the common options supported across providers. @@ -18,13 +18,27 @@ These are the common options supported across providers. ## Properties +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2332](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2332) + +Effective abort signal composed by the activity from caller `abortSignal` +and/or `timeout`. Adapters should forward this to the provider SDK when +supported. Request-specific — never store on a global client config. + +*** + ### duration? ```ts -optional duration: number; +optional duration?: number; ``` -Defined in: [packages/ai/src/types.ts:1890](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1890) +Defined in: [packages/ai/src/types.ts:2318](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2318) Desired duration in seconds @@ -36,7 +50,7 @@ Desired duration in seconds logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:1898](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1898) +Defined in: [packages/ai/src/types.ts:2326](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2326) Internal logger threaded from the generateAudio() entry point. Adapters must call logger.request() before the SDK call and logger.errors() in @@ -50,7 +64,7 @@ catch blocks. model: string; ``` -Defined in: [packages/ai/src/types.ts:1886](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1886) +Defined in: [packages/ai/src/types.ts:2314](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2314) The model to use for audio generation @@ -59,10 +73,10 @@ The model to use for audio generation ### modelOptions? ```ts -optional modelOptions: TProviderOptions; +optional modelOptions?: TProviderOptions; ``` -Defined in: [packages/ai/src/types.ts:1892](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1892) +Defined in: [packages/ai/src/types.ts:2320](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2320) Model-specific options for audio generation @@ -74,6 +88,6 @@ Model-specific options for audio generation prompt: string; ``` -Defined in: [packages/ai/src/types.ts:1888](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1888) +Defined in: [packages/ai/src/types.ts:2316](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2316) Text description of the desired audio diff --git a/docs/reference/interfaces/AudioGenerationResult.md b/docs/reference/interfaces/AudioGenerationResult.md index 015abbe4b6..458235b598 100644 --- a/docs/reference/interfaces/AudioGenerationResult.md +++ b/docs/reference/interfaces/AudioGenerationResult.md @@ -5,19 +5,31 @@ title: AudioGenerationResult # Interface: AudioGenerationResult -Defined in: [packages/ai/src/types.ts:1914](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1914) +Defined in: [packages/ai/src/types.ts:2348](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2348) Result of audio generation ## Properties +### artifacts? + +```ts +optional artifacts?: PersistedArtifactRef[]; +``` + +Defined in: [packages/ai/src/types.ts:2358](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2358) + +Persisted artifact references for generated assets, when available + +*** + ### audio ```ts audio: GeneratedAudio; ``` -Defined in: [packages/ai/src/types.ts:1920](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1920) +Defined in: [packages/ai/src/types.ts:2354](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2354) The generated audio @@ -29,7 +41,7 @@ The generated audio id: string; ``` -Defined in: [packages/ai/src/types.ts:1916](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1916) +Defined in: [packages/ai/src/types.ts:2350](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2350) Unique identifier for the generation @@ -41,7 +53,7 @@ Unique identifier for the generation model: string; ``` -Defined in: [packages/ai/src/types.ts:1918](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1918) +Defined in: [packages/ai/src/types.ts:2352](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2352) Model used for generation @@ -50,9 +62,9 @@ Model used for generation ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:1922](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1922) +Defined in: [packages/ai/src/types.ts:2356](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2356) Token usage information (if available) diff --git a/docs/reference/interfaces/AudioPart.md b/docs/reference/interfaces/AudioPart.md index 241e01e338..8f261338b3 100644 --- a/docs/reference/interfaces/AudioPart.md +++ b/docs/reference/interfaces/AudioPart.md @@ -5,7 +5,7 @@ title: AudioPart # Interface: AudioPart\ -Defined in: [packages/ai/src/types.ts:260](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L260) +Defined in: [packages/ai/src/types.ts:271](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L271) Audio content part for multimodal messages. @@ -22,10 +22,10 @@ Provider-specific metadata type ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:265](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L265) +Defined in: [packages/ai/src/types.ts:276](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L276) Provider-specific metadata (e.g., format, sample rate) @@ -37,7 +37,7 @@ Provider-specific metadata (e.g., format, sample rate) source: ContentPartSource; ``` -Defined in: [packages/ai/src/types.ts:263](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L263) +Defined in: [packages/ai/src/types.ts:274](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L274) Source of the audio content @@ -49,4 +49,4 @@ Source of the audio content type: "audio"; ``` -Defined in: [packages/ai/src/types.ts:261](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L261) +Defined in: [packages/ai/src/types.ts:272](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L272) diff --git a/docs/reference/interfaces/AudioVisualization.md b/docs/reference/interfaces/AudioVisualization.md index 8f8bf45613..76a1dcc17f 100644 --- a/docs/reference/interfaces/AudioVisualization.md +++ b/docs/reference/interfaces/AudioVisualization.md @@ -11,7 +11,7 @@ Interface for accessing audio visualization data ## Properties -### getInputFrequencyData() +### getInputFrequencyData ```ts getInputFrequencyData: () => Uint8Array; @@ -27,7 +27,7 @@ Get frequency data for input audio visualization *** -### getInputTimeDomainData() +### getInputTimeDomainData ```ts getInputTimeDomainData: () => Uint8Array; @@ -43,7 +43,7 @@ Get time domain data for input waveform *** -### getOutputFrequencyData() +### getOutputFrequencyData ```ts getOutputFrequencyData: () => Uint8Array; @@ -59,7 +59,7 @@ Get frequency data for output audio visualization *** -### getOutputTimeDomainData() +### getOutputTimeDomainData ```ts getOutputTimeDomainData: () => Uint8Array; @@ -99,10 +99,10 @@ Input sample rate *** -### onInputAudio()? +### onInputAudio? ```ts -optional onInputAudio: (callback) => () => void; +optional onInputAudio?: (callback) => () => void; ``` Defined in: [packages/ai/src/realtime/types.ts:227](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L227) @@ -117,20 +117,14 @@ Subscribe to raw input audio samples #### Returns -```ts -(): void; -``` - -##### Returns - -`void` +() => `void` *** -### onOutputAudio()? +### onOutputAudio? ```ts -optional onOutputAudio: (callback) => () => void; +optional onOutputAudio?: (callback) => () => void; ``` Defined in: [packages/ai/src/realtime/types.ts:231](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L231) @@ -145,13 +139,7 @@ Subscribe to raw output audio samples #### Returns -```ts -(): void; -``` - -##### Returns - -`void` +() => `void` *** diff --git a/docs/reference/interfaces/BaseAGUIEvent.md b/docs/reference/interfaces/BaseAGUIEvent.md index 973c516695..b57c2bbafc 100644 --- a/docs/reference/interfaces/BaseAGUIEvent.md +++ b/docs/reference/interfaces/BaseAGUIEvent.md @@ -5,7 +5,7 @@ title: BaseAGUIEvent # Interface: BaseAGUIEvent -Defined in: [packages/ai/src/types.ts:1065](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1065) +Defined in: [packages/ai/src/types.ts:1082](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1082) Base structure for AG-UI events. Extends @ag-ui/core BaseEvent with TanStack AI additions. @@ -28,9 +28,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1067](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1067) +Defined in: [packages/ai/src/types.ts:1084](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1084) Model identifier for multi-model support diff --git a/docs/reference/interfaces/BatchInterruptError.md b/docs/reference/interfaces/BatchInterruptError.md new file mode 100644 index 0000000000..a268cd5332 --- /dev/null +++ b/docs/reference/interfaces/BatchInterruptError.md @@ -0,0 +1,142 @@ +--- +id: BatchInterruptError +title: BatchInterruptError +--- + +# Interface: BatchInterruptError + +Defined in: [packages/ai/src/interrupts.ts:53](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L53) + +## Extends + +- [`InterruptCorrelation`](InterruptCorrelation.md) + +## Properties + +### code + +```ts +code: BatchInterruptErrorCode; +``` + +Defined in: [packages/ai/src/interrupts.ts:55](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L55) + +*** + +### continuationRunId? + +```ts +optional continuationRunId?: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:13](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L13) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`continuationRunId`](InterruptCorrelation.md#continuationrunid) + +*** + +### generation + +```ts +generation: number; +``` + +Defined in: [packages/ai/src/interrupts.ts:11](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L11) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`generation`](InterruptCorrelation.md#generation) + +*** + +### interruptedRunId + +```ts +interruptedRunId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:10](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L10) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`interruptedRunId`](InterruptCorrelation.md#interruptedrunid) + +*** + +### interruptIds + +```ts +interruptIds: readonly string[]; +``` + +Defined in: [packages/ai/src/interrupts.ts:59](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L59) + +*** + +### message + +```ts +message: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:56](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L56) + +*** + +### retryable + +```ts +retryable: boolean; +``` + +Defined in: [packages/ai/src/interrupts.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L58) + +*** + +### scope + +```ts +scope: "batch"; +``` + +Defined in: [packages/ai/src/interrupts.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L54) + +*** + +### source + +```ts +source: "transport" | "server" | "client"; +``` + +Defined in: [packages/ai/src/interrupts.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L57) + +*** + +### submissionId? + +```ts +optional submissionId?: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L12) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`submissionId`](InterruptCorrelation.md#submissionid) + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:9](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L9) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`threadId`](InterruptCorrelation.md#threadid) diff --git a/docs/reference/interfaces/ChatMCPOptions.md b/docs/reference/interfaces/ChatMCPOptions.md index c3c0287377..826aeb4918 100644 --- a/docs/reference/interfaces/ChatMCPOptions.md +++ b/docs/reference/interfaces/ChatMCPOptions.md @@ -26,7 +26,7 @@ The MCP clients or client pools to discover tools from and manage. ### connection? ```ts -optional connection: MCPConnectionPolicy; +optional connection?: MCPConnectionPolicy; ``` Defined in: [packages/ai/src/activities/chat/mcp/types.ts:66](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/mcp/types.ts#L66) @@ -40,7 +40,7 @@ Defaults to `'close'`. ### lazyTools? ```ts -optional lazyTools: boolean; +optional lazyTools?: boolean; ``` Defined in: [packages/ai/src/activities/chat/mcp/types.ts:74](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/mcp/types.ts#L74) @@ -52,10 +52,10 @@ Defaults to `false`. *** -### onDiscoveryError()? +### onDiscoveryError? ```ts -optional onDiscoveryError: (error, source) => void | Promise; +optional onDiscoveryError?: (error, source) => void | Promise; ``` Defined in: [packages/ai/src/activities/chat/mcp/types.ts:85](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/mcp/types.ts#L85) diff --git a/docs/reference/interfaces/ChatMiddleware.md b/docs/reference/interfaces/ChatMiddleware.md index aa11560e00..22aab1567c 100644 --- a/docs/reference/interfaces/ChatMiddleware.md +++ b/docs/reference/interfaces/ChatMiddleware.md @@ -5,7 +5,7 @@ title: ChatMiddleware # Interface: ChatMiddleware\ -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:421](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L421) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:463](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L463) Chat middleware interface. @@ -15,6 +15,8 @@ All hooks are optional. Middleware is composed in array order: ## Examples +**Logging middleware** + ```ts const loggingMiddleware: ChatMiddleware = { name: 'logging', @@ -24,6 +26,8 @@ const loggingMiddleware: ChatMiddleware = { } ``` +**Redaction middleware** + ```ts const redactionMiddleware: ChatMiddleware = { name: 'redaction', @@ -50,22 +54,22 @@ const redactionMiddleware: ChatMiddleware = { ### name? ```ts -optional name: string; +optional name?: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:423](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L423) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:465](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L465) Optional name for debugging and identification *** -### onAbort()? +### onAbort? ```ts -optional onAbort: (ctx, info) => void | Promise; +optional onAbort?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:573](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L573) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:634](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L634) Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run. @@ -86,13 +90,13 @@ Exactly one of onFinish/onAbort/onError will be called per run. *** -### onAfterToolCall()? +### onAfterToolCall? ```ts -optional onAfterToolCall: (ctx, info) => void | Promise; +optional onAfterToolCall?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:537](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L537) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:598](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L598) Called after a tool execution completes (success or failure). @@ -112,15 +116,15 @@ Called after a tool execution completes (success or failure). *** -### onBeforeToolCall()? +### onBeforeToolCall? ```ts -optional onBeforeToolCall: (ctx, hookCtx) => +optional onBeforeToolCall?: (ctx, hookCtx) => | BeforeToolCallDecision | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:529](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L529) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:590](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L590) Called before a tool is executed. Can observe, transform args, skip execution, or abort the run. @@ -142,10 +146,10 @@ Can observe, transform args, skip execution, or abort the run. *** -### onChunk()? +### onChunk? ```ts -optional onChunk: (ctx, chunk) => +optional onChunk?: (ctx, chunk) => | void | AGUIEvent | AGUIEvent[] @@ -153,7 +157,7 @@ optional onChunk: (ctx, chunk) => | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:515](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L515) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:576](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L576) Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks. @@ -180,10 +184,10 @@ void (pass through), chunk (replace), chunk[] (expand), null (drop) *** -### onConfig()? +### onConfig? ```ts -optional onConfig: (ctx, config) => +optional onConfig?: (ctx, config) => | void | Partial | Promise< @@ -193,7 +197,7 @@ optional onConfig: (ctx, config) => | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:462](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L462) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:504](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L504) Called to observe or transform the chat configuration. Called at init and at the beginning of each agent iteration. @@ -223,13 +227,13 @@ Only the fields you return are overwritten — everything else is preserved. *** -### onError()? +### onError? ```ts -optional onError: (ctx, info) => void | Promise; +optional onError?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:582](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L582) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:643](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L643) Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run. @@ -250,13 +254,13 @@ Exactly one of onFinish/onAbort/onError will be called per run. *** -### onFinish()? +### onFinish? ```ts -optional onFinish: (ctx, info) => void | Promise; +optional onFinish?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:564](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L564) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:625](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L625) Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run. @@ -277,13 +281,13 @@ Exactly one of onFinish/onAbort/onError will be called per run. *** -### onIteration()? +### onIteration? ```ts -optional onIteration: (ctx, info) => void | Promise; +optional onIteration?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:504](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L504) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:546](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L546) Called at the start of each agent loop iteration, after a new assistant message ID is created. Use this to observe iteration boundaries. @@ -304,13 +308,50 @@ is created. Use this to observe iteration boundaries. *** -### onStart()? +### onShouldContinue? + +```ts +optional onShouldContinue?: (ctx, state) => boolean | void | Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:565](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L565) + +Called when the engine is deciding whether to start another agent-loop +iteration (after a tool phase or between model turns). + +Return `false` to stop further iterations. Return `true`, `void`, or +`undefined` to allow continuation. Combined with AND semantics across +middleware and with `agentLoopStrategy` — any `false` stops the loop. + +Does not abort the run: the stream finishes normally with the current +messages. Use `ctx.abort()` only when you need a hard abort. + +Receives the same [AgentLoopState](AgentLoopState.md) passed to strategies +(`iterationCount`, `toolCallCount`, `lastTurnToolCallCount`, etc.). + +#### Parameters + +##### ctx + +[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\> + +##### state + +[`AgentLoopState`](AgentLoopState.md) + +#### Returns + +`boolean` \| `void` \| `Promise`\<`boolean` \| `void`\> + +*** + +### onStart? ```ts -optional onStart: (ctx) => void | Promise; +optional onStart?: (ctx) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:498](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L498) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:540](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L540) Called when the chat run starts (after initial onConfig). @@ -326,10 +367,10 @@ Called when the chat run starts (after initial onConfig). *** -### onStructuredOutputConfig()? +### onStructuredOutputConfig? ```ts -optional onStructuredOutputConfig: (ctx, config) => +optional onStructuredOutputConfig?: (ctx, config) => | void | Partial | Promise< @@ -339,7 +380,7 @@ optional onStructuredOutputConfig: (ctx, config) => | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:486](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L486) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:528](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L528) Called at the start of the final structured-output call (when the chat was invoked with outputSchema). Pipes through middleware in order, like @@ -377,13 +418,13 @@ outputSchema or apply structured-output-specific behavior. *** -### onToolPhaseComplete()? +### onToolPhaseComplete? ```ts -optional onToolPhaseComplete: (ctx, info) => void | Promise; +optional onToolPhaseComplete?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:546](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L546) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:607](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L607) Called after all tool calls in an iteration have been processed. Provides aggregate data about tool execution results, approvals, and client tools. @@ -404,13 +445,13 @@ Provides aggregate data about tool execution results, approvals, and client tool *** -### onUsage()? +### onUsage? ```ts -optional onUsage: (ctx, usage) => void | Promise; +optional onUsage?: (ctx, usage) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:555](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L555) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:616](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L616) Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage. @@ -434,10 +475,10 @@ Called once per model iteration that reports usage. ### optionalRequires? ```ts -optional optionalRequires: readonly CapabilityHandle[]; +optional optionalRequires?: readonly CapabilityHandle[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:445](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L445) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:487](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L487) Capabilities this middleware uses if present but does not require. Non-gating: never causes a validation error. Read with @@ -448,10 +489,10 @@ Non-gating: never causes a validation error. Read with ### provides? ```ts -optional provides: readonly CapabilityHandle[]; +optional provides?: readonly CapabilityHandle[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:438](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L438) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:480](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L480) Capabilities this middleware provides. Each declared capability MUST be provided (via its `provide` accessor) inside `setup`, or `chat()` throws @@ -462,10 +503,10 @@ after the setup phase. ### requires? ```ts -optional requires: readonly CapabilityHandle[]; +optional requires?: readonly CapabilityHandle[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:431](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L431) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:473](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L473) Capabilities this middleware requires. `chat()` validates that some middleware (or the adapter) provides each one; unsatisfied requirements are @@ -477,23 +518,23 @@ the adapter runs. ### sandbox? ```ts -optional sandbox: ChatSandboxHooks; +optional sandbox?: ChatSandboxHooks; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:591](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L591) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:652](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L652) Sandbox file-event hooks. Fire when a sandbox provided by `withSandbox` is active during the run and a file is created/changed/deleted. Server-side. *** -### setup()? +### setup? ```ts -optional setup: (ctx) => void | Promise; +optional setup?: (ctx) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:453](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L453) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:495](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L495) Provisioning hook. Runs FIRST — before `onConfig` (init) — across all middleware in array order. Use it to call `provide` accessors so later diff --git a/docs/reference/interfaces/ChatMiddlewareConfig.md b/docs/reference/interfaces/ChatMiddlewareConfig.md index 8ab8321ed8..228f8965bb 100644 --- a/docs/reference/interfaces/ChatMiddlewareConfig.md +++ b/docs/reference/interfaces/ChatMiddlewareConfig.md @@ -5,7 +5,7 @@ title: ChatMiddlewareConfig # Interface: ChatMiddlewareConfig -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:207](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L207) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L212) Chat configuration that middleware can observe or transform. This is a subset of the chat engine's effective configuration @@ -22,27 +22,47 @@ messages: ModelMessage< | null>[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:208](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L208) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:213](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L213) *** ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:211](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L211) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:218](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L218) *** ### modelOptions? ```ts -optional modelOptions: Record; +optional modelOptions?: Record; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L212) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:219](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L219) + +*** + +### resume? + +```ts +optional resume?: ResumeEntry[]; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:216](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L216) + +*** + +### resumeToolState? + +```ts +optional resumeToolState?: ChatResumeToolState; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:217](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L217) *** @@ -52,7 +72,7 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:212](https://gi systemPrompts: SystemPrompt[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:209](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L209) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:214](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L214) *** @@ -62,4 +82,4 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:209](https://gi tools: Tool[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:210](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L210) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:215](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L215) diff --git a/docs/reference/interfaces/ChatMiddlewareContext.md b/docs/reference/interfaces/ChatMiddlewareContext.md index ea31d81e02..e3f4d4200c 100644 --- a/docs/reference/interfaces/ChatMiddlewareContext.md +++ b/docs/reference/interfaces/ChatMiddlewareContext.md @@ -5,7 +5,7 @@ title: ChatMiddlewareContext # Interface: ChatMiddlewareContext\ -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:86](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L86) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:89](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L89) Stable context object passed to all middleware hooks. Created once per chat() invocation and shared across all hooks. @@ -18,13 +18,13 @@ Created once per chat() invocation and shared across all hooks. ## Properties -### abort() +### abort ```ts abort: (reason?) => void; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:115](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L115) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:120](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L120) Abort the chat run with a reason @@ -46,7 +46,7 @@ Abort the chat run with a reason accumulatedContent: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:166](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L166) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:171](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L171) Accumulated text content for the current iteration @@ -58,7 +58,7 @@ Accumulated text content for the current iteration activity: "chat"; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:133](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L133) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:138](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L138) Which activity this context describes — always `'chat'`. Present so the chat context structurally satisfies the base `GenerationMiddlewareContext`, @@ -73,7 +73,7 @@ letting an observe-only middleware authored against the base (e.g. capabilities: CapabilityRegistry; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:180](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L180) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:185](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L185) Capability bookkeeping for this request. Populated by middleware `setup` hooks (via `provide` accessors) and read by later middleware (via `get` @@ -88,7 +88,7 @@ this directly. Orthogonal to `context` (the user runtime context). chunkIndex: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:111](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L111) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:116](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L116) Running count of chunks yielded so far @@ -100,7 +100,7 @@ Running count of chunks yielded so far context: TContext; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:117](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L117) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:122](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L122) Runtime context provided by chat() options @@ -109,10 +109,10 @@ Runtime context provided by chat() options ### ~~conversationId?~~ ```ts -optional conversationId: string; +optional conversationId?: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:105](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L105) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:110](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L110) #### Deprecated @@ -122,13 +122,13 @@ working unchanged. Will be removed in a future major release. *** -### createId() +### createId ```ts createId: (prefix) => string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:173](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L173) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:178](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L178) Generate a unique ID with the given prefix @@ -150,19 +150,19 @@ Generate a unique ID with the given prefix currentMessageId: string | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:164](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L164) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:169](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L169) Current assistant message ID (changes per iteration) *** -### defer() +### defer ```ts defer: (promise) => void; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:123](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L123) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:128](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L128) Defer a non-blocking side-effect promise. Deferred promises do not block streaming and are awaited @@ -180,13 +180,13 @@ after the terminal hook (onFinish/onAbort/onError). *** -### get() +### get ```ts get: (capability) => TValue; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:185](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L185) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:190](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L190) Read a provided capability by its handle. Equivalent to the handle's own `get` accessor (`getX(ctx)`); throws if the capability was never provided. @@ -209,13 +209,13 @@ Read a provided capability by its handle. Equivalent to the handle's own *** -### getOptional() +### getOptional ```ts getOptional: (capability) => TValue | undefined; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:190](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L190) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:195](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L195) Read a capability by its handle, returning `undefined` if it was never provided (never throws). @@ -244,7 +244,7 @@ provided (never throws). hasTools: boolean; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:159](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L159) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:164](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L164) Whether tools are configured @@ -256,7 +256,7 @@ Whether tools are configured iteration: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:109](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L109) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:114](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L114) Current agent loop iteration (0-indexed) @@ -268,7 +268,7 @@ Current agent loop iteration (0-indexed) messageCount: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:157](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L157) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:162](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L162) Number of messages at the start of the request @@ -283,7 +283,7 @@ messages: readonly ModelMessage< | null>[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:171](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L171) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:176](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L176) Current messages array (read-only view) @@ -295,19 +295,19 @@ Current messages array (read-only view) model: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:137](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L137) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:142](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L142) -Model identifier (e.g., 'gpt-4o') +Model identifier (e.g., 'gpt-5.5') *** ### modelOptions? ```ts -optional modelOptions: Record; +optional modelOptions?: Record; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:152](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L152) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:157](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L157) Provider-specific model options @@ -316,34 +316,46 @@ Provider-specific model options ### options? ```ts -optional options: Record; +optional options?: Record; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:150](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L150) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:155](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L155) Flattened generation options (metadata) *** +### parentRunId? + +```ts +optional parentRunId?: string; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:97](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L97) + +Interrupted or parent run correlated with this continuation. + +*** + ### phase ```ts phase: ChatMiddlewarePhase; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L107) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:112](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L112) Current lifecycle phase *** -### provide() +### provide ```ts provide: (capability, value) => void; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:195](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L195) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:200](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L200) Provide a capability value. Equivalent to the handle's own `provide` accessor (`provideX(ctx, value)`). Typically called from `setup`. @@ -376,7 +388,7 @@ accessor (`provideX(ctx, value)`). Typically called from `setup`. provider: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:135](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L135) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:140](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L140) Provider name (e.g., 'openai', 'anthropic') @@ -388,7 +400,7 @@ Provider name (e.g., 'openai', 'anthropic') requestId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:88](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L88) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:91](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L91) Unique identifier for this chat request @@ -400,7 +412,7 @@ Unique identifier for this chat request runId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:92](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L92) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:95](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L95) AG-UI run identifier for correlating client and server events @@ -409,10 +421,10 @@ AG-UI run identifier for correlating client and server events ### signal? ```ts -optional signal: AbortSignal; +optional signal?: AbortSignal; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:113](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L113) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:118](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L118) Abort signal from the chat request @@ -424,7 +436,7 @@ Abort signal from the chat request source: "server" | "client"; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:139](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L139) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:144](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L144) Source of the chat invocation — always 'server' for server-side chat @@ -436,7 +448,7 @@ Source of the chat invocation — always 'server' for server-side chat streamId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L90) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:93](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L93) Unique identifier for this stream @@ -448,7 +460,7 @@ Unique identifier for this stream streaming: boolean; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:141](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L141) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:146](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L146) Whether the chat is streaming @@ -460,7 +472,7 @@ Whether the chat is streaming systemPrompts: SystemPrompt[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:146](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L146) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L151) System prompts configured for this chat @@ -472,7 +484,7 @@ System prompts configured for this chat threadId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L99) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L104) AG-UI thread identifier — a stable per-conversation ID used to correlate client and server devtools events. Resolves to the @@ -484,9 +496,9 @@ auto-generated value when neither is supplied. ### toolNames? ```ts -optional toolNames: string[]; +optional toolNames?: string[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:148](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L148) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:153](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L153) Names of configured tools, if any diff --git a/docs/reference/interfaces/ChatResumeToolState.md b/docs/reference/interfaces/ChatResumeToolState.md new file mode 100644 index 0000000000..b99bb2eafd --- /dev/null +++ b/docs/reference/interfaces/ChatResumeToolState.md @@ -0,0 +1,62 @@ +--- +id: ChatResumeToolState +title: ChatResumeToolState +--- + +# Interface: ChatResumeToolState + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:227](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L227) + +Tool decisions reconstructed by server-side middleware from validated resume +entries. This lets empty-message interrupt resumes continue tool execution +without relying on client message history. + +## Properties + +### approvals? + +```ts +optional approvals?: ReadonlyMap; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:228](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L228) + +*** + +### cancelledToolCallIds? + +```ts +optional cancelledToolCallIds?: ReadonlySet; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:234](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L234) + +*** + +### clientToolResults? + +```ts +optional clientToolResults?: ReadonlyMap; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:229](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L229) + +*** + +### deniedToolResults? + +```ts +optional deniedToolResults?: ReadonlyMap; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:233](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L233) + +*** + +### genericInterrupts? + +```ts +optional genericInterrupts?: ReadonlyMap; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:230](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L230) diff --git a/docs/reference/interfaces/ChatSandboxHooks.md b/docs/reference/interfaces/ChatSandboxHooks.md index 8a7ace1ad8..b21cf696fe 100644 --- a/docs/reference/interfaces/ChatSandboxHooks.md +++ b/docs/reference/interfaces/ChatSandboxHooks.md @@ -5,7 +5,7 @@ title: ChatSandboxHooks # Interface: ChatSandboxHooks\ -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:41](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L41) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:44](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L44) Sandbox file-event hooks a chat middleware can declare. Fire server-side for every file create/change/delete observed in the sandbox during the run. @@ -18,13 +18,13 @@ every file create/change/delete observed in the sandbox during the run. ## Properties -### onFile()? +### onFile? ```ts -optional onFile: (ctx, e) => void | Promise; +optional onFile?: (ctx, e) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:42](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L42) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:45](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L45) #### Parameters @@ -42,13 +42,13 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:42](https://git *** -### onFileChange()? +### onFileChange? ```ts -optional onFileChange: (ctx, e) => void | Promise; +optional onFileChange?: (ctx, e) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L50) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:53](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L53) #### Parameters @@ -66,13 +66,13 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:50](https://git *** -### onFileCreate()? +### onFileCreate? ```ts -optional onFileCreate: (ctx, e) => void | Promise; +optional onFileCreate?: (ctx, e) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L46) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:49](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L49) #### Parameters @@ -90,13 +90,13 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:46](https://git *** -### onFileDelete()? +### onFileDelete? ```ts -optional onFileDelete: (ctx, e) => void | Promise; +optional onFileDelete?: (ctx, e) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L54) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L57) #### Parameters diff --git a/docs/reference/interfaces/ChunkRecording.md b/docs/reference/interfaces/ChunkRecording.md index 45df932cf6..fcca53fccf 100644 --- a/docs/reference/interfaces/ChunkRecording.md +++ b/docs/reference/interfaces/ChunkRecording.md @@ -42,7 +42,7 @@ timestamp: number; ### model? ```ts -optional model: string; +optional model?: string; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:103](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L103) @@ -52,7 +52,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:103](https://github ### provider? ```ts -optional provider: string; +optional provider?: string; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L104) @@ -62,7 +62,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:104](https://github ### result? ```ts -optional result: ProcessorResult; +optional result?: ProcessorResult; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:110](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L110) diff --git a/docs/reference/interfaces/ChunkStrategy.md b/docs/reference/interfaces/ChunkStrategy.md index 3305e59956..92fd8486e3 100644 --- a/docs/reference/interfaces/ChunkStrategy.md +++ b/docs/reference/interfaces/ChunkStrategy.md @@ -11,10 +11,10 @@ Strategy for determining when to emit text updates ## Properties -### reset()? +### reset? ```ts -optional reset: () => void; +optional reset?: () => void; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L50) @@ -27,7 +27,7 @@ Optional: Reset strategy state (called when streaming starts) *** -### shouldEmit() +### shouldEmit ```ts shouldEmit: (chunk, accumulated) => boolean; diff --git a/docs/reference/interfaces/ClientTool.md b/docs/reference/interfaces/ClientTool.md index 6d10bbfb0f..64b5531d54 100644 --- a/docs/reference/interfaces/ClientTool.md +++ b/docs/reference/interfaces/ClientTool.md @@ -3,21 +3,25 @@ id: ClientTool title: ClientTool --- -# Interface: ClientTool\ +# Interface: ClientTool\ -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:24](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L24) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L107) Marker type for client-side tools +## Extends + +- `ToolApprovalCapabilityMarker`\<`TNeedsApproval`, `TApprovalSchema`\> + ## Type Parameters ### TInput -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TOutput -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TName @@ -31,6 +35,12 @@ Marker type for client-side tools `TNeedsApproval` *extends* `boolean` = `false` +### TApprovalSchema + +`TApprovalSchema` *extends* + \| [`ApprovalSchemaConfig`](../type-aliases/ApprovalSchemaConfig.md) + \| `undefined` = `undefined` + ## Properties ### \_\_toolSide @@ -39,7 +49,45 @@ Marker type for client-side tools __toolSide: "client"; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:34](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L34) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:118](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L118) + +*** + +### \[toolApprovalCapability\]? + +```ts +readonly optional [toolApprovalCapability]?: object; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:26](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L26) + +#### approvalSchema + +```ts +approvalSchema: TApprovalSchema; +``` + +#### needsApproval + +```ts +needsApproval: TNeedsApproval; +``` + +#### Inherited from + +```ts +ToolApprovalCapabilityMarker.[toolApprovalCapability] +``` + +*** + +### approvalSchema? + +```ts +optional approvalSchema?: TApprovalSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:129](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L129) *** @@ -49,47 +97,47 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:34](https: description: string; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:36](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L36) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:120](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L120) *** ### execute? ```ts -optional execute: ToolExecuteFunction; +optional execute?: ToolExecuteFunction; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:47](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L47) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:132](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L132) *** ### inputSchema? ```ts -optional inputSchema: TInput; +optional inputSchema?: TInput; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:42](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L42) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:126](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L126) *** ### lazy? ```ts -optional lazy: boolean; +optional lazy?: boolean; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:45](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L45) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:130](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L130) *** ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L46) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:131](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L131) *** @@ -99,24 +147,24 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:46](https: name: TName; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:35](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L35) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L119) *** ### needsApproval? ```ts -optional needsApproval: TNeedsApproval; +optional needsApproval?: TNeedsApproval; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:44](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L44) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:128](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L128) *** ### outputSchema? ```ts -optional outputSchema: TOutput; +optional outputSchema?: TOutput; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:43](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L43) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:127](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L127) diff --git a/docs/reference/interfaces/CodeModeConsoleEvent.md b/docs/reference/interfaces/CodeModeConsoleEvent.md index 33a90e4a90..b1a6651691 100644 --- a/docs/reference/interfaces/CodeModeConsoleEvent.md +++ b/docs/reference/interfaces/CodeModeConsoleEvent.md @@ -5,32 +5,30 @@ title: CodeModeConsoleEvent # Interface: CodeModeConsoleEvent -Defined in: [packages/ai/src/types.ts:1454](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1454) +Defined in: [packages/ai/src/types.ts:1538](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1538) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:console"; ``` -Defined in: [packages/ai/src/types.ts:1455](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1455) +Defined in: [packages/ai/src/types.ts:1539](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1539) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1456](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1456) +Defined in: [packages/ai/src/types.ts:1540](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1540) #### level diff --git a/docs/reference/interfaces/CodeModeExecutionStartedEvent.md b/docs/reference/interfaces/CodeModeExecutionStartedEvent.md index 00e4f9d247..59f6ff217a 100644 --- a/docs/reference/interfaces/CodeModeExecutionStartedEvent.md +++ b/docs/reference/interfaces/CodeModeExecutionStartedEvent.md @@ -5,32 +5,30 @@ title: CodeModeExecutionStartedEvent # Interface: CodeModeExecutionStartedEvent -Defined in: [packages/ai/src/types.ts:1450](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1450) +Defined in: [packages/ai/src/types.ts:1534](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1534) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:execution_started"; ``` -Defined in: [packages/ai/src/types.ts:1451](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1451) +Defined in: [packages/ai/src/types.ts:1535](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1535) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1452](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1452) +Defined in: [packages/ai/src/types.ts:1536](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1536) #### codeLength diff --git a/docs/reference/interfaces/CodeModeExternalCallEvent.md b/docs/reference/interfaces/CodeModeExternalCallEvent.md index 9171b64b20..f40075c45d 100644 --- a/docs/reference/interfaces/CodeModeExternalCallEvent.md +++ b/docs/reference/interfaces/CodeModeExternalCallEvent.md @@ -5,32 +5,30 @@ title: CodeModeExternalCallEvent # Interface: CodeModeExternalCallEvent -Defined in: [packages/ai/src/types.ts:1462](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1462) +Defined in: [packages/ai/src/types.ts:1546](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1546) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:external_call"; ``` -Defined in: [packages/ai/src/types.ts:1463](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1463) +Defined in: [packages/ai/src/types.ts:1547](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1547) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1464](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1464) +Defined in: [packages/ai/src/types.ts:1548](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1548) #### args diff --git a/docs/reference/interfaces/CodeModeExternalErrorEvent.md b/docs/reference/interfaces/CodeModeExternalErrorEvent.md index 1617373f91..9588f672bb 100644 --- a/docs/reference/interfaces/CodeModeExternalErrorEvent.md +++ b/docs/reference/interfaces/CodeModeExternalErrorEvent.md @@ -5,32 +5,30 @@ title: CodeModeExternalErrorEvent # Interface: CodeModeExternalErrorEvent -Defined in: [packages/ai/src/types.ts:1470](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1470) +Defined in: [packages/ai/src/types.ts:1554](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1554) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:external_error"; ``` -Defined in: [packages/ai/src/types.ts:1471](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1471) +Defined in: [packages/ai/src/types.ts:1555](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1555) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1472](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1472) +Defined in: [packages/ai/src/types.ts:1556](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1556) #### duration diff --git a/docs/reference/interfaces/CodeModeExternalResultEvent.md b/docs/reference/interfaces/CodeModeExternalResultEvent.md index bf135da91f..e90d131bf3 100644 --- a/docs/reference/interfaces/CodeModeExternalResultEvent.md +++ b/docs/reference/interfaces/CodeModeExternalResultEvent.md @@ -5,32 +5,30 @@ title: CodeModeExternalResultEvent # Interface: CodeModeExternalResultEvent -Defined in: [packages/ai/src/types.ts:1466](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1466) +Defined in: [packages/ai/src/types.ts:1550](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1550) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:external_result"; ``` -Defined in: [packages/ai/src/types.ts:1467](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1467) +Defined in: [packages/ai/src/types.ts:1551](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1551) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1468](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1468) +Defined in: [packages/ai/src/types.ts:1552](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1552) #### duration diff --git a/docs/reference/interfaces/CodeModeSkillCallEvent.md b/docs/reference/interfaces/CodeModeSkillCallEvent.md index bc151592c0..374be32726 100644 --- a/docs/reference/interfaces/CodeModeSkillCallEvent.md +++ b/docs/reference/interfaces/CodeModeSkillCallEvent.md @@ -5,32 +5,30 @@ title: CodeModeSkillCallEvent # Interface: CodeModeSkillCallEvent -Defined in: [packages/ai/src/types.ts:1474](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1474) +Defined in: [packages/ai/src/types.ts:1558](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1558) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:skill_call"; ``` -Defined in: [packages/ai/src/types.ts:1475](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1475) +Defined in: [packages/ai/src/types.ts:1559](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1559) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1476](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1476) +Defined in: [packages/ai/src/types.ts:1560](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1560) #### input diff --git a/docs/reference/interfaces/CodeModeSkillErrorEvent.md b/docs/reference/interfaces/CodeModeSkillErrorEvent.md index f59bc8f74a..0bc151022a 100644 --- a/docs/reference/interfaces/CodeModeSkillErrorEvent.md +++ b/docs/reference/interfaces/CodeModeSkillErrorEvent.md @@ -5,32 +5,30 @@ title: CodeModeSkillErrorEvent # Interface: CodeModeSkillErrorEvent -Defined in: [packages/ai/src/types.ts:1482](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1482) +Defined in: [packages/ai/src/types.ts:1566](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1566) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:skill_error"; ``` -Defined in: [packages/ai/src/types.ts:1483](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1483) +Defined in: [packages/ai/src/types.ts:1567](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1567) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1484](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1484) +Defined in: [packages/ai/src/types.ts:1568](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1568) #### duration diff --git a/docs/reference/interfaces/CodeModeSkillResultEvent.md b/docs/reference/interfaces/CodeModeSkillResultEvent.md index 2a75ad0e99..e6642bbb7e 100644 --- a/docs/reference/interfaces/CodeModeSkillResultEvent.md +++ b/docs/reference/interfaces/CodeModeSkillResultEvent.md @@ -5,32 +5,30 @@ title: CodeModeSkillResultEvent # Interface: CodeModeSkillResultEvent -Defined in: [packages/ai/src/types.ts:1478](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1478) +Defined in: [packages/ai/src/types.ts:1562](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1562) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "code_mode:skill_result"; ``` -Defined in: [packages/ai/src/types.ts:1479](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1479) +Defined in: [packages/ai/src/types.ts:1563](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1563) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1480](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1480) +Defined in: [packages/ai/src/types.ts:1564](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1564) #### duration diff --git a/docs/reference/interfaces/ContentPartDataSource.md b/docs/reference/interfaces/ContentPartDataSource.md index 01b7b115c7..38627518a4 100644 --- a/docs/reference/interfaces/ContentPartDataSource.md +++ b/docs/reference/interfaces/ContentPartDataSource.md @@ -5,7 +5,7 @@ title: ContentPartDataSource # Interface: ContentPartDataSource -Defined in: [packages/ai/src/types.ts:201](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L201) +Defined in: [packages/ai/src/types.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L212) Source specification for inline data content (base64). Requires a mimeType to ensure providers receive proper content type information. @@ -18,7 +18,7 @@ Requires a mimeType to ensure providers receive proper content type information. mimeType: string; ``` -Defined in: [packages/ai/src/types.ts:214](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L214) +Defined in: [packages/ai/src/types.ts:225](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L225) The MIME type of the content (e.g., 'image/png', 'audio/wav'). Required for data sources to ensure proper handling by providers. @@ -31,7 +31,7 @@ Required for data sources to ensure proper handling by providers. type: "data"; ``` -Defined in: [packages/ai/src/types.ts:205](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L205) +Defined in: [packages/ai/src/types.ts:216](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L216) Indicates this is inline data content. @@ -43,6 +43,6 @@ Indicates this is inline data content. value: string; ``` -Defined in: [packages/ai/src/types.ts:209](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L209) +Defined in: [packages/ai/src/types.ts:220](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L220) The base64-encoded content value. diff --git a/docs/reference/interfaces/ContentPartUrlSource.md b/docs/reference/interfaces/ContentPartUrlSource.md index a96de875c5..6b7a467a37 100644 --- a/docs/reference/interfaces/ContentPartUrlSource.md +++ b/docs/reference/interfaces/ContentPartUrlSource.md @@ -5,7 +5,7 @@ title: ContentPartUrlSource # Interface: ContentPartUrlSource -Defined in: [packages/ai/src/types.ts:221](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L221) +Defined in: [packages/ai/src/types.ts:232](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L232) Source specification for URL-based content. mimeType is optional as it can often be inferred from the URL or response headers. @@ -15,10 +15,10 @@ mimeType is optional as it can often be inferred from the URL or response header ### mimeType? ```ts -optional mimeType: string; +optional mimeType?: string; ``` -Defined in: [packages/ai/src/types.ts:233](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L233) +Defined in: [packages/ai/src/types.ts:244](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L244) Optional MIME type hint for cases where providers can't infer it from the URL. @@ -30,7 +30,7 @@ Optional MIME type hint for cases where providers can't infer it from the URL. type: "url"; ``` -Defined in: [packages/ai/src/types.ts:225](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L225) +Defined in: [packages/ai/src/types.ts:236](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L236) Indicates this is URL-referenced content. @@ -42,6 +42,6 @@ Indicates this is URL-referenced content. value: string; ``` -Defined in: [packages/ai/src/types.ts:229](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L229) +Defined in: [packages/ai/src/types.ts:240](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L240) HTTP(S) URL or data URI pointing to the content. diff --git a/docs/reference/interfaces/CustomEvent.md b/docs/reference/interfaces/CustomEvent.md index 3f83ba63eb..9e4581eba3 100644 --- a/docs/reference/interfaces/CustomEvent.md +++ b/docs/reference/interfaces/CustomEvent.md @@ -5,16 +5,20 @@ title: CustomEvent # Interface: CustomEvent -Defined in: [packages/ai/src/types.ts:1337](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1337) +Defined in: [packages/ai/src/types.ts:1401](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1401) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends -- `CustomEvent` +- `Pick`\<`AGUICustomEvent`, `"name"` \| `"value"` \| `"timestamp"` \| `"rawEvent"`\> ## Extended by @@ -37,20 +41,49 @@ TanStack AI adds: `model?` - [`CodeModeSkillErrorEvent`](CodeModeSkillErrorEvent.md) - [`SkillRegisteredEvent`](SkillRegisteredEvent.md) -## Indexable +## Properties + +### model? ```ts -[k: string]: unknown +optional model?: string; ``` -## Properties +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) -### model? +Model identifier for multi-model support + +*** + +### runId? ```ts -optional model: string; +optional runId?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) -Model identifier for multi-model support +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) diff --git a/docs/reference/interfaces/DebugCategories.md b/docs/reference/interfaces/DebugCategories.md index 8a113c0934..e7313b1a04 100644 --- a/docs/reference/interfaces/DebugCategories.md +++ b/docs/reference/interfaces/DebugCategories.md @@ -18,7 +18,7 @@ Per-category toggles for debug logging. Each flag enables or disables one class ### agentLoop? ```ts -optional agentLoop: boolean; +optional agentLoop?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L50) @@ -30,7 +30,7 @@ Iteration markers and phase transitions in the chat agent loop. Chat-only. ### config? ```ts -optional config: boolean; +optional config?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L54) @@ -42,7 +42,7 @@ Config transforms returned by middleware `onConfig` hooks. Chat-only. ### errors? ```ts -optional errors: boolean; +optional errors?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L58) @@ -54,7 +54,7 @@ Caught errors throughout the pipeline. Unlike other categories, defaults to `tru ### middleware? ```ts -optional middleware: boolean; +optional middleware?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:42](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L42) @@ -66,7 +66,7 @@ Inputs and outputs around each middleware hook invocation. Chat-only. ### output? ```ts -optional output: boolean; +optional output?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:38](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L38) @@ -78,19 +78,19 @@ Chunks/results yielded to the consumer after all middleware. For streaming activ ### provider? ```ts -optional provider: boolean; +optional provider?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:34](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L34) -Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs). Emitted inside every streaming adapter's chunk loop. +Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs, BytePlus). Emitted inside every streaming adapter's chunk loop. *** ### request? ```ts -optional request: boolean; +optional request?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:62](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L62) @@ -102,7 +102,7 @@ Outgoing call metadata (provider, model, message/tool counts) emitted before eac ### sandbox? ```ts -optional sandbox: boolean; +optional sandbox?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:67](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L67) @@ -115,7 +115,7 @@ hook dispatch, ensure/bootstrap and lifecycle transitions. Chat-only. ### tools? ```ts -optional tools: boolean; +optional tools?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L46) diff --git a/docs/reference/interfaces/DebugConfig.md b/docs/reference/interfaces/DebugConfig.md index 0da28f3e79..a80407dd48 100644 --- a/docs/reference/interfaces/DebugConfig.md +++ b/docs/reference/interfaces/DebugConfig.md @@ -18,7 +18,7 @@ Granular debug configuration combining per-category toggles with an optional cus ### agentLoop? ```ts -optional agentLoop: boolean; +optional agentLoop?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L50) @@ -34,7 +34,7 @@ Iteration markers and phase transitions in the chat agent loop. Chat-only. ### config? ```ts -optional config: boolean; +optional config?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L54) @@ -50,7 +50,7 @@ Config transforms returned by middleware `onConfig` hooks. Chat-only. ### errors? ```ts -optional errors: boolean; +optional errors?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L58) @@ -66,7 +66,7 @@ Caught errors throughout the pipeline. Unlike other categories, defaults to `tru ### logger? ```ts -optional logger: Logger; +optional logger?: Logger; ``` Defined in: [packages/ai/src/logger/types.ts:77](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L77) @@ -78,7 +78,7 @@ Custom `Logger` implementation. When omitted, a default `ConsoleLogger` routes o ### middleware? ```ts -optional middleware: boolean; +optional middleware?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:42](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L42) @@ -94,7 +94,7 @@ Inputs and outputs around each middleware hook invocation. Chat-only. ### output? ```ts -optional output: boolean; +optional output?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:38](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L38) @@ -110,12 +110,12 @@ Chunks/results yielded to the consumer after all middleware. For streaming activ ### provider? ```ts -optional provider: boolean; +optional provider?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:34](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L34) -Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs). Emitted inside every streaming adapter's chunk loop. +Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs, BytePlus). Emitted inside every streaming adapter's chunk loop. #### Inherited from @@ -126,7 +126,7 @@ Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollam ### request? ```ts -optional request: boolean; +optional request?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:62](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L62) @@ -142,7 +142,7 @@ Outgoing call metadata (provider, model, message/tool counts) emitted before eac ### sandbox? ```ts -optional sandbox: boolean; +optional sandbox?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:67](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L67) @@ -159,7 +159,7 @@ hook dispatch, ensure/bootstrap and lifecycle transitions. Chat-only. ### tools? ```ts -optional tools: boolean; +optional tools?: boolean; ``` Defined in: [packages/ai/src/logger/types.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/logger/types.ts#L46) diff --git a/docs/reference/interfaces/DefaultMessageMetadataByModality.md b/docs/reference/interfaces/DefaultMessageMetadataByModality.md index c958f75b75..0a6ede728a 100644 --- a/docs/reference/interfaces/DefaultMessageMetadataByModality.md +++ b/docs/reference/interfaces/DefaultMessageMetadataByModality.md @@ -5,7 +5,7 @@ title: DefaultMessageMetadataByModality # Interface: DefaultMessageMetadataByModality -Defined in: [packages/ai/src/types.ts:2159](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2159) +Defined in: [packages/ai/src/types.ts:2738](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2738) Default metadata type for adapters that don't define custom metadata. Uses unknown for all modalities. @@ -18,7 +18,7 @@ Uses unknown for all modalities. audio: unknown; ``` -Defined in: [packages/ai/src/types.ts:2162](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2162) +Defined in: [packages/ai/src/types.ts:2741](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2741) *** @@ -28,7 +28,7 @@ Defined in: [packages/ai/src/types.ts:2162](https://github.com/TanStack/ai/blob/ document: unknown; ``` -Defined in: [packages/ai/src/types.ts:2164](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2164) +Defined in: [packages/ai/src/types.ts:2743](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2743) *** @@ -38,7 +38,7 @@ Defined in: [packages/ai/src/types.ts:2164](https://github.com/TanStack/ai/blob/ image: unknown; ``` -Defined in: [packages/ai/src/types.ts:2161](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2161) +Defined in: [packages/ai/src/types.ts:2740](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2740) *** @@ -48,7 +48,7 @@ Defined in: [packages/ai/src/types.ts:2161](https://github.com/TanStack/ai/blob/ text: unknown; ``` -Defined in: [packages/ai/src/types.ts:2160](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2160) +Defined in: [packages/ai/src/types.ts:2739](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2739) *** @@ -58,4 +58,4 @@ Defined in: [packages/ai/src/types.ts:2160](https://github.com/TanStack/ai/blob/ video: unknown; ``` -Defined in: [packages/ai/src/types.ts:2163](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2163) +Defined in: [packages/ai/src/types.ts:2742](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2742) diff --git a/docs/reference/interfaces/DefinedChatMiddleware.md b/docs/reference/interfaces/DefinedChatMiddleware.md index 07b6637a79..53c63c5a22 100644 --- a/docs/reference/interfaces/DefinedChatMiddleware.md +++ b/docs/reference/interfaces/DefinedChatMiddleware.md @@ -33,10 +33,10 @@ A middleware whose `requires`/`provides` tuple types are captured precisely ### name? ```ts -optional name: string; +optional name?: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:423](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L423) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:465](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L465) Optional name for debugging and identification @@ -46,13 +46,13 @@ Optional name for debugging and identification *** -### onAbort()? +### onAbort? ```ts -optional onAbort: (ctx, info) => void | Promise; +optional onAbort?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:573](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L573) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:634](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L634) Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run. @@ -77,13 +77,13 @@ Exactly one of onFinish/onAbort/onError will be called per run. *** -### onAfterToolCall()? +### onAfterToolCall? ```ts -optional onAfterToolCall: (ctx, info) => void | Promise; +optional onAfterToolCall?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:537](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L537) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:598](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L598) Called after a tool execution completes (success or failure). @@ -107,15 +107,15 @@ Called after a tool execution completes (success or failure). *** -### onBeforeToolCall()? +### onBeforeToolCall? ```ts -optional onBeforeToolCall: (ctx, hookCtx) => +optional onBeforeToolCall?: (ctx, hookCtx) => | BeforeToolCallDecision | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:529](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L529) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:590](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L590) Called before a tool is executed. Can observe, transform args, skip execution, or abort the run. @@ -141,10 +141,10 @@ Can observe, transform args, skip execution, or abort the run. *** -### onChunk()? +### onChunk? ```ts -optional onChunk: (ctx, chunk) => +optional onChunk?: (ctx, chunk) => | void | AGUIEvent | AGUIEvent[] @@ -152,7 +152,7 @@ optional onChunk: (ctx, chunk) => | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:515](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L515) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:576](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L576) Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks. @@ -183,10 +183,10 @@ void (pass through), chunk (replace), chunk[] (expand), null (drop) *** -### onConfig()? +### onConfig? ```ts -optional onConfig: (ctx, config) => +optional onConfig?: (ctx, config) => | void | Partial | Promise< @@ -196,7 +196,7 @@ optional onConfig: (ctx, config) => | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:462](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L462) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:504](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L504) Called to observe or transform the chat configuration. Called at init and at the beginning of each agent iteration. @@ -230,13 +230,13 @@ Only the fields you return are overwritten — everything else is preserved. *** -### onError()? +### onError? ```ts -optional onError: (ctx, info) => void | Promise; +optional onError?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:582](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L582) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:643](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L643) Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run. @@ -261,13 +261,13 @@ Exactly one of onFinish/onAbort/onError will be called per run. *** -### onFinish()? +### onFinish? ```ts -optional onFinish: (ctx, info) => void | Promise; +optional onFinish?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:564](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L564) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:625](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L625) Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run. @@ -292,13 +292,13 @@ Exactly one of onFinish/onAbort/onError will be called per run. *** -### onIteration()? +### onIteration? ```ts -optional onIteration: (ctx, info) => void | Promise; +optional onIteration?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:504](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L504) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:546](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L546) Called at the start of each agent loop iteration, after a new assistant message ID is created. Use this to observe iteration boundaries. @@ -323,13 +323,54 @@ is created. Use this to observe iteration boundaries. *** -### onStart()? +### onShouldContinue? ```ts -optional onStart: (ctx) => void | Promise; +optional onShouldContinue?: (ctx, state) => boolean | void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:498](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L498) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:565](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L565) + +Called when the engine is deciding whether to start another agent-loop +iteration (after a tool phase or between model turns). + +Return `false` to stop further iterations. Return `true`, `void`, or +`undefined` to allow continuation. Combined with AND semantics across +middleware and with `agentLoopStrategy` — any `false` stops the loop. + +Does not abort the run: the stream finishes normally with the current +messages. Use `ctx.abort()` only when you need a hard abort. + +Receives the same [AgentLoopState](AgentLoopState.md) passed to strategies +(`iterationCount`, `toolCallCount`, `lastTurnToolCallCount`, etc.). + +#### Parameters + +##### ctx + +[`ChatMiddlewareContext`](ChatMiddlewareContext.md)\<`TContext`\> + +##### state + +[`AgentLoopState`](AgentLoopState.md) + +#### Returns + +`boolean` \| `void` \| `Promise`\<`boolean` \| `void`\> + +#### Inherited from + +[`ChatMiddleware`](ChatMiddleware.md).[`onShouldContinue`](ChatMiddleware.md#onshouldcontinue) + +*** + +### onStart? + +```ts +optional onStart?: (ctx) => void | Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:540](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L540) Called when the chat run starts (after initial onConfig). @@ -349,10 +390,10 @@ Called when the chat run starts (after initial onConfig). *** -### onStructuredOutputConfig()? +### onStructuredOutputConfig? ```ts -optional onStructuredOutputConfig: (ctx, config) => +optional onStructuredOutputConfig?: (ctx, config) => | void | Partial | Promise< @@ -362,7 +403,7 @@ optional onStructuredOutputConfig: (ctx, config) => | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:486](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L486) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:528](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L528) Called at the start of the final structured-output call (when the chat was invoked with outputSchema). Pipes through middleware in order, like @@ -404,13 +445,13 @@ outputSchema or apply structured-output-specific behavior. *** -### onToolPhaseComplete()? +### onToolPhaseComplete? ```ts -optional onToolPhaseComplete: (ctx, info) => void | Promise; +optional onToolPhaseComplete?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:546](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L546) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:607](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L607) Called after all tool calls in an iteration have been processed. Provides aggregate data about tool execution results, approvals, and client tools. @@ -435,13 +476,13 @@ Provides aggregate data about tool execution results, approvals, and client tool *** -### onUsage()? +### onUsage? ```ts -optional onUsage: (ctx, usage) => void | Promise; +optional onUsage?: (ctx, usage) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:555](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L555) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:616](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L616) Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage. @@ -469,10 +510,10 @@ Called once per model iteration that reports usage. ### optionalRequires? ```ts -optional optionalRequires: readonly CapabilityHandle[]; +optional optionalRequires?: readonly CapabilityHandle[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:445](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L445) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:487](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L487) Capabilities this middleware uses if present but does not require. Non-gating: never causes a validation error. Read with @@ -487,7 +528,7 @@ Non-gating: never causes a validation error. Read with ### provides? ```ts -optional provides: TProvides; +optional provides?: TProvides; ``` Defined in: [packages/ai/src/activities/chat/middleware/define.ts:14](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/define.ts#L14) @@ -505,7 +546,7 @@ after the setup phase. ### requires? ```ts -optional requires: TRequires; +optional requires?: TRequires; ``` Defined in: [packages/ai/src/activities/chat/middleware/define.ts:13](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/define.ts#L13) @@ -524,10 +565,10 @@ the adapter runs. ### sandbox? ```ts -optional sandbox: ChatSandboxHooks; +optional sandbox?: ChatSandboxHooks; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:591](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L591) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:652](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L652) Sandbox file-event hooks. Fire when a sandbox provided by `withSandbox` is active during the run and a file is created/changed/deleted. Server-side. @@ -538,13 +579,13 @@ active during the run and a file is created/changed/deleted. Server-side. *** -### setup()? +### setup? ```ts -optional setup: (ctx) => void | Promise; +optional setup?: (ctx) => void | Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:453](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L453) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:495](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L495) Provisioning hook. Runs FIRST — before `onConfig` (init) — across all middleware in array order. Use it to call `provide` accessors so later diff --git a/docs/reference/interfaces/DocumentPart.md b/docs/reference/interfaces/DocumentPart.md index b84009af0f..d90d87fcfa 100644 --- a/docs/reference/interfaces/DocumentPart.md +++ b/docs/reference/interfaces/DocumentPart.md @@ -5,7 +5,7 @@ title: DocumentPart # Interface: DocumentPart\ -Defined in: [packages/ai/src/types.ts:284](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L284) +Defined in: [packages/ai/src/types.ts:295](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L295) Document content part for multimodal messages (e.g., PDFs). @@ -22,10 +22,10 @@ Provider-specific metadata type (e.g., Anthropic's media_type) ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:289](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L289) +Defined in: [packages/ai/src/types.ts:300](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L300) Provider-specific metadata (e.g., media_type for PDFs) @@ -37,7 +37,7 @@ Provider-specific metadata (e.g., media_type for PDFs) source: ContentPartSource; ``` -Defined in: [packages/ai/src/types.ts:287](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L287) +Defined in: [packages/ai/src/types.ts:298](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L298) Source of the document content @@ -49,4 +49,4 @@ Source of the document content type: "document"; ``` -Defined in: [packages/ai/src/types.ts:285](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L285) +Defined in: [packages/ai/src/types.ts:296](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L296) diff --git a/docs/reference/interfaces/Embedding.md b/docs/reference/interfaces/Embedding.md new file mode 100644 index 0000000000..b1748f274f --- /dev/null +++ b/docs/reference/interfaces/Embedding.md @@ -0,0 +1,34 @@ +--- +id: Embedding +title: Embedding +--- + +# Interface: Embedding + +Defined in: [packages/ai/src/types.ts:2713](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2713) + +A single embedding vector. + +## Properties + +### index + +```ts +index: number; +``` + +Defined in: [packages/ai/src/types.ts:2717](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2717) + +Position of the source item in the (normalized) input array + +*** + +### vector + +```ts +vector: number[]; +``` + +Defined in: [packages/ai/src/types.ts:2715](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2715) + +The embedding vector diff --git a/docs/reference/interfaces/EmbeddingAdapter.md b/docs/reference/interfaces/EmbeddingAdapter.md new file mode 100644 index 0000000000..34ddea5237 --- /dev/null +++ b/docs/reference/interfaces/EmbeddingAdapter.md @@ -0,0 +1,128 @@ +--- +id: EmbeddingAdapter +title: EmbeddingAdapter +--- + +# Interface: EmbeddingAdapter\ + +Defined in: [packages/ai/src/activities/embed/adapter.ts:31](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L31) + +Embedding adapter interface with pre-resolved generics. + +An adapter is created by a provider function: `provider('model')` → `adapter` +All type resolution happens at the provider call site, not in this interface. + +Generic parameters: +- TModel: The specific model name (e.g., 'text-embedding-3-small') +- TProviderOptions: Base provider-specific options (already resolved) +- TModelProviderOptionsByName: Map from model name to its specific provider options +- TModelInputModalitiesByName: Map from model name to the input modalities it + accepts (constrains the `input` item types at compile time) + +## Type Parameters + +### TModel + +`TModel` *extends* `string` = `string` + +### TProviderOptions + +`TProviderOptions` *extends* `object` = `Record`\<`string`, `unknown`\> + +### TModelProviderOptionsByName + +`TModelProviderOptionsByName` *extends* `Record`\<`string`, `any`\> = `Record`\<`string`, `any`\> + +### TModelInputModalitiesByName + +`TModelInputModalitiesByName` *extends* [`EmbeddingModelInputModalitiesByName`](../type-aliases/EmbeddingModelInputModalitiesByName.md) = [`EmbeddingModelInputModalitiesByName`](../type-aliases/EmbeddingModelInputModalitiesByName.md) + +## Properties + +### ~types + +```ts +~types: object; +``` + +Defined in: [packages/ai/src/activities/embed/adapter.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L48) + +**`Internal`** + +Type-only properties for inference. Not assigned at runtime. + +#### modelInputModalitiesByName + +```ts +modelInputModalitiesByName: TModelInputModalitiesByName; +``` + +#### modelProviderOptionsByName + +```ts +modelProviderOptionsByName: TModelProviderOptionsByName; +``` + +#### providerOptions + +```ts +providerOptions: TProviderOptions; +``` + +*** + +### createEmbeddings + +```ts +createEmbeddings: (options) => Promise; +``` + +Defined in: [packages/ai/src/activities/embed/adapter.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L57) + +Generate embeddings for the input items (one vector per item) + +#### Parameters + +##### options + +[`EmbeddingOptions`](EmbeddingOptions.md)\<`TProviderOptions`\> + +#### Returns + +`Promise`\<[`EmbeddingResult`](EmbeddingResult.md)\> + +*** + +### kind + +```ts +readonly kind: "embedding"; +``` + +Defined in: [packages/ai/src/activities/embed/adapter.ts:39](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L39) + +Discriminator for adapter kind + +*** + +### model + +```ts +readonly model: TModel; +``` + +Defined in: [packages/ai/src/activities/embed/adapter.ts:43](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L43) + +The model this adapter is configured for + +*** + +### name + +```ts +readonly name: string; +``` + +Defined in: [packages/ai/src/activities/embed/adapter.ts:41](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L41) + +Adapter name identifier diff --git a/docs/reference/interfaces/EmbeddingOptions.md b/docs/reference/interfaces/EmbeddingOptions.md new file mode 100644 index 0000000000..098d8707f2 --- /dev/null +++ b/docs/reference/interfaces/EmbeddingOptions.md @@ -0,0 +1,81 @@ +--- +id: EmbeddingOptions +title: EmbeddingOptions +--- + +# Interface: EmbeddingOptions\ + +Defined in: [packages/ai/src/types.ts:2690](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2690) + +Options for embedding generation, as received by adapters. The `embed()` +entry point normalizes a single input item to an array before calling the +adapter, so `input` is always an array here. + +## Type Parameters + +### TProviderOptions + +`TProviderOptions` *extends* `object` = `object` + +## Properties + +### dimensions? + +```ts +optional dimensions?: number; +``` + +Defined in: [packages/ai/src/types.ts:2699](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2699) + +Requested output dimensionality. Adapters for models with fixed +dimensions throw a clear runtime error when this is set. + +*** + +### input + +```ts +input: EmbeddingInputItem[]; +``` + +Defined in: [packages/ai/src/types.ts:2694](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2694) + +The items to embed — one vector per item + +*** + +### logger + +```ts +logger: InternalLogger; +``` + +Defined in: [packages/ai/src/types.ts:2707](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2707) + +Internal logger threaded from the embed() entry point. Adapters must +call logger.request() before the SDK call and logger.errors() in catch +blocks. + +*** + +### model + +```ts +model: string; +``` + +Defined in: [packages/ai/src/types.ts:2692](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2692) + +The model to use for embedding generation + +*** + +### modelOptions? + +```ts +optional modelOptions?: TProviderOptions; +``` + +Defined in: [packages/ai/src/types.ts:2701](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2701) + +Model-specific options for embedding generation diff --git a/docs/reference/interfaces/EmbeddingResult.md b/docs/reference/interfaces/EmbeddingResult.md new file mode 100644 index 0000000000..5fc5330033 --- /dev/null +++ b/docs/reference/interfaces/EmbeddingResult.md @@ -0,0 +1,58 @@ +--- +id: EmbeddingResult +title: EmbeddingResult +--- + +# Interface: EmbeddingResult + +Defined in: [packages/ai/src/types.ts:2723](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2723) + +Result of embedding generation. + +## Properties + +### embeddings + +```ts +embeddings: Embedding[]; +``` + +Defined in: [packages/ai/src/types.ts:2729](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2729) + +One embedding per input item, in input order + +*** + +### id + +```ts +id: string; +``` + +Defined in: [packages/ai/src/types.ts:2725](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2725) + +Unique identifier for the generation + +*** + +### model + +```ts +model: string; +``` + +Defined in: [packages/ai/src/types.ts:2727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2727) + +Model used for generation + +*** + +### usage? + +```ts +optional usage?: TokenUsage; +``` + +Defined in: [packages/ai/src/types.ts:2731](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2731) + +Token usage information (if provided by the adapter) diff --git a/docs/reference/interfaces/ErrorInfo.md b/docs/reference/interfaces/ErrorInfo.md index 3343fcef72..99e4e095ff 100644 --- a/docs/reference/interfaces/ErrorInfo.md +++ b/docs/reference/interfaces/ErrorInfo.md @@ -5,7 +5,7 @@ title: ErrorInfo # Interface: ErrorInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:381](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L381) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:423](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L423) Information passed to onError. @@ -17,7 +17,7 @@ Information passed to onError. duration: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:385](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L385) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:427](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L427) Duration until error in milliseconds @@ -29,6 +29,6 @@ Duration until error in milliseconds error: unknown; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L383) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:425](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L425) The error that caused the failure diff --git a/docs/reference/interfaces/ExtendedModelDef.md b/docs/reference/interfaces/ExtendedModelDef.md index e591402dcd..27b7e6aa85 100644 --- a/docs/reference/interfaces/ExtendedModelDef.md +++ b/docs/reference/interfaces/ExtendedModelDef.md @@ -50,7 +50,7 @@ Provider options type for this model ### features? ```ts -optional features: TFeatures; +optional features?: TFeatures; ``` Defined in: [packages/ai/src/extend-adapter.ts:35](https://github.com/TanStack/ai/blob/main/packages/ai/src/extend-adapter.ts#L35) @@ -98,7 +98,7 @@ The model name identifier ### tools? ```ts -optional tools: TTools; +optional tools?: TTools; ``` Defined in: [packages/ai/src/extend-adapter.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/extend-adapter.ts#L37) diff --git a/docs/reference/interfaces/FileChangedEvent.md b/docs/reference/interfaces/FileChangedEvent.md index 2baf7ee5b4..26af205563 100644 --- a/docs/reference/interfaces/FileChangedEvent.md +++ b/docs/reference/interfaces/FileChangedEvent.md @@ -5,32 +5,30 @@ title: FileChangedEvent # Interface: FileChangedEvent -Defined in: [packages/ai/src/types.ts:1440](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1440) +Defined in: [packages/ai/src/types.ts:1524](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1524) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "file.changed"; ``` -Defined in: [packages/ai/src/types.ts:1441](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1441) +Defined in: [packages/ai/src/types.ts:1525](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1525) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1442](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1442) +Defined in: [packages/ai/src/types.ts:1526](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1526) #### diff diff --git a/docs/reference/interfaces/FileChangedPayload.md b/docs/reference/interfaces/FileChangedPayload.md new file mode 100644 index 0000000000..9d7d03a863 --- /dev/null +++ b/docs/reference/interfaces/FileChangedPayload.md @@ -0,0 +1,52 @@ +--- +id: FileChangedPayload +title: FileChangedPayload +--- + +# Interface: FileChangedPayload + +Defined in: [packages/ai/src/custom-events.ts:35](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L35) + +## Properties + +### diff? + +```ts +optional diff?: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:40](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L40) + +Unified diff, when the harness can produce one. + +*** + +### path + +```ts +path: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:38](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L38) + +Absolute path inside the sandbox (under the workspace root). + +*** + +### timestamp + +```ts +timestamp: number; +``` + +Defined in: [packages/ai/src/custom-events.ts:41](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L41) + +*** + +### type + +```ts +type: "create" | "change" | "delete"; +``` + +Defined in: [packages/ai/src/custom-events.ts:36](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L36) diff --git a/docs/reference/interfaces/FinishInfo.md b/docs/reference/interfaces/FinishInfo.md index 4a933fc306..13a6bbfe8e 100644 --- a/docs/reference/interfaces/FinishInfo.md +++ b/docs/reference/interfaces/FinishInfo.md @@ -5,7 +5,7 @@ title: FinishInfo # Interface: FinishInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:357](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L357) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L383) Information passed to onFinish. @@ -17,7 +17,7 @@ Information passed to onFinish. content: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:363](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L363) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:389](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L389) Final accumulated text content @@ -29,7 +29,7 @@ Final accumulated text content duration: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:361](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L361) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:387](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L387) Total duration of the chat run in milliseconds @@ -41,7 +41,7 @@ Total duration of the chat run in milliseconds finishReason: string | null; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:359](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L359) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:385](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L385) The finish reason from the last model response @@ -50,9 +50,9 @@ The finish reason from the last model response ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:365](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L365) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:391](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L391) Final usage totals, if available (optionally including provider-reported cost) diff --git a/docs/reference/interfaces/GenerationAbortInfo.md b/docs/reference/interfaces/GenerationAbortInfo.md index 989a3e25aa..149c8d744b 100644 --- a/docs/reference/interfaces/GenerationAbortInfo.md +++ b/docs/reference/interfaces/GenerationAbortInfo.md @@ -5,7 +5,7 @@ title: GenerationAbortInfo # Interface: GenerationAbortInfo -Defined in: [packages/ai/src/activities/middleware/types.ts:97](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L97) +Defined in: [packages/ai/src/activities/middleware/types.ts:143](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L143) Information passed to [GenerationMiddleware.onAbort](GenerationMiddleware.md#onabort). @@ -17,7 +17,7 @@ Information passed to [GenerationMiddleware.onAbort](GenerationMiddleware.md#ona duration: number; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:101](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L101) +Defined in: [packages/ai/src/activities/middleware/types.ts:147](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L147) Wall-clock duration until the abort, in milliseconds. @@ -26,9 +26,9 @@ Wall-clock duration until the abort, in milliseconds. ### reason? ```ts -optional reason: string; +optional reason?: string; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L99) +Defined in: [packages/ai/src/activities/middleware/types.ts:145](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L145) The reason for the abort, if provided. diff --git a/docs/reference/interfaces/GenerationErrorInfo.md b/docs/reference/interfaces/GenerationErrorInfo.md index 74f816dfbb..bf56be6390 100644 --- a/docs/reference/interfaces/GenerationErrorInfo.md +++ b/docs/reference/interfaces/GenerationErrorInfo.md @@ -5,7 +5,7 @@ title: GenerationErrorInfo # Interface: GenerationErrorInfo -Defined in: [packages/ai/src/activities/middleware/types.ts:105](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L105) +Defined in: [packages/ai/src/activities/middleware/types.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L151) Information passed to [GenerationMiddleware.onError](GenerationMiddleware.md#onerror). @@ -17,7 +17,7 @@ Information passed to [GenerationMiddleware.onError](GenerationMiddleware.md#one duration: number; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:109](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L109) +Defined in: [packages/ai/src/activities/middleware/types.ts:155](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L155) Wall-clock duration until the failure, in milliseconds. @@ -29,6 +29,6 @@ Wall-clock duration until the failure, in milliseconds. error: unknown; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L107) +Defined in: [packages/ai/src/activities/middleware/types.ts:153](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L153) The thrown value (typically an `Error`). diff --git a/docs/reference/interfaces/GenerationFinishInfo.md b/docs/reference/interfaces/GenerationFinishInfo.md index 204e70b059..e68329239b 100644 --- a/docs/reference/interfaces/GenerationFinishInfo.md +++ b/docs/reference/interfaces/GenerationFinishInfo.md @@ -5,7 +5,7 @@ title: GenerationFinishInfo # Interface: GenerationFinishInfo -Defined in: [packages/ai/src/activities/middleware/types.ts:89](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L89) +Defined in: [packages/ai/src/activities/middleware/types.ts:135](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L135) Information passed to [GenerationMiddleware.onFinish](GenerationMiddleware.md#onfinish). @@ -17,7 +17,7 @@ Information passed to [GenerationMiddleware.onFinish](GenerationMiddleware.md#on duration: number; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:91](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L91) +Defined in: [packages/ai/src/activities/middleware/types.ts:137](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L137) Wall-clock duration of the activity call, in milliseconds. @@ -26,9 +26,9 @@ Wall-clock duration of the activity call, in milliseconds. ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:93](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L93) +Defined in: [packages/ai/src/activities/middleware/types.ts:139](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L139) Unified usage, when the provider reported it. diff --git a/docs/reference/interfaces/GenerationMiddleware.md b/docs/reference/interfaces/GenerationMiddleware.md index c7d1065084..ebb30a3b40 100644 --- a/docs/reference/interfaces/GenerationMiddleware.md +++ b/docs/reference/interfaces/GenerationMiddleware.md @@ -5,7 +5,7 @@ title: GenerationMiddleware # Interface: GenerationMiddleware\ -Defined in: [packages/ai/src/activities/middleware/types.ts:145](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L145) +Defined in: [packages/ai/src/activities/middleware/types.ts:191](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L191) Activity-agnostic, observe-only middleware. @@ -47,22 +47,22 @@ await generateImage({ ### name? ```ts -optional name: string; +optional name?: string; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:147](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L147) +Defined in: [packages/ai/src/activities/middleware/types.ts:193](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L193) Optional name, surfaced in diagnostics. *** -### onAbort()? +### onAbort? ```ts -optional onAbort: (ctx, info) => void | Promise; +optional onAbort?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L161) +Defined in: [packages/ai/src/activities/middleware/types.ts:207](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L207) Called when the activity is aborted (e.g. an abandoned stream). @@ -82,13 +82,13 @@ Called when the activity is aborted (e.g. an abandoned stream). *** -### onError()? +### onError? ```ts -optional onError: (ctx, info) => void | Promise; +optional onError?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:166](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L166) +Defined in: [packages/ai/src/activities/middleware/types.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L212) Called when the activity throws before completing. @@ -108,13 +108,13 @@ Called when the activity throws before completing. *** -### onFinish()? +### onFinish? ```ts -optional onFinish: (ctx, info) => void | Promise; +optional onFinish?: (ctx, info) => void | Promise; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:156](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L156) +Defined in: [packages/ai/src/activities/middleware/types.ts:202](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L202) Called after the activity completes successfully. @@ -134,13 +134,13 @@ Called after the activity completes successfully. *** -### onStart()? +### onStart? ```ts -optional onStart: (ctx) => void | Promise; +optional onStart?: (ctx) => void | Promise; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:149](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L149) +Defined in: [packages/ai/src/activities/middleware/types.ts:195](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L195) Called before the adapter request begins. @@ -156,13 +156,13 @@ Called before the adapter request begins. *** -### onUsage()? +### onUsage? ```ts -optional onUsage: (ctx, usage) => void | Promise; +optional onUsage?: (ctx, usage) => void | Promise; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L151) +Defined in: [packages/ai/src/activities/middleware/types.ts:197](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L197) Called when the provider reports usage, before `onFinish`. diff --git a/docs/reference/interfaces/GenerationMiddlewareContext.md b/docs/reference/interfaces/GenerationMiddlewareContext.md index 95da9e63cb..d5abc39a57 100644 --- a/docs/reference/interfaces/GenerationMiddlewareContext.md +++ b/docs/reference/interfaces/GenerationMiddlewareContext.md @@ -5,7 +5,7 @@ title: GenerationMiddlewareContext # Interface: GenerationMiddlewareContext\ -Defined in: [packages/ai/src/activities/middleware/types.ts:51](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L51) +Defined in: [packages/ai/src/activities/middleware/types.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L57) Stable context passed to every [GenerationMiddleware](GenerationMiddleware.md) hook. Created once per activity call and shared across the hooks of that call. @@ -29,31 +29,44 @@ extra fields is not assignable to `GenerationMiddleware`. activity: GenerationActivity; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L58) +Defined in: [packages/ai/src/activities/middleware/types.ts:64](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L64) Which activity this call is. Discriminates media from chat. *** +### artifactInputs? + +```ts +optional artifactInputs?: unknown; +``` + +Defined in: [packages/ai/src/activities/middleware/types.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L104) + +Activity inputs captured for middleware that needs to transform or persist +the result together with reconstructable request metadata. + +*** + ### context ```ts context: TContext; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:74](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L74) +Defined in: [packages/ai/src/activities/middleware/types.ts:84](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L84) Runtime context provided by the activity options, if any. *** -### createId() +### createId ```ts createId: (prefix) => string; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L72) +Defined in: [packages/ai/src/activities/middleware/types.ts:82](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L82) Generate a unique id with the given prefix. @@ -75,7 +88,7 @@ Generate a unique id with the given prefix. model: string; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:62](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L62) +Defined in: [packages/ai/src/activities/middleware/types.ts:68](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L68) Model id. Emitted as `gen_ai.request.model`. @@ -84,10 +97,10 @@ Model id. Emitted as `gen_ai.request.model`. ### modelOptions? ```ts -optional modelOptions: unknown; +optional modelOptions?: unknown; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:68](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L68) +Defined in: [packages/ai/src/activities/middleware/types.ts:78](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L78) Provider-specific options passed to the activity, if any. Typed `unknown` because each activity's options are strongly typed per model; a supertype @@ -101,7 +114,7 @@ of `ChatMiddlewareContext`'s `modelOptions`. provider: string; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:60](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L60) +Defined in: [packages/ai/src/activities/middleware/types.ts:66](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L66) Provider/adapter name (e.g. `"openai"`). Emitted as `gen_ai.system`. @@ -113,19 +126,66 @@ Provider/adapter name (e.g. `"openai"`). Emitted as `gen_ai.system`. requestId: string; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:56](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L56) +Defined in: [packages/ai/src/activities/middleware/types.ts:62](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L62) Stable id correlating the `onStart` / `onFinish` / `onError` / `onAbort` hooks of a single activity call. *** +### resultTransforms + +```ts +resultTransforms: GenerationResultTransform[]; +``` + +Defined in: [packages/ai/src/activities/middleware/types.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L99) + +Result transforms registered by middleware during this activity call. +Transforms run after the raw adapter result exists and before the final +result is returned or streamed. Push multiple transforms to run them in +registration order. + +REQUIRED (always an array, empty when nothing registered): middleware +registers by pushing onto it, so an optional array would let a host that +builds its own context omit it and silently no-op every registration — +generation persistence would then mark a run completed with neither its +result nor its artifacts written, with nothing to observe but the missing +data. Every context the library builds comes from +`createGenerationContext`, which always sets `[]`. + +*** + +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/activities/middleware/types.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L72) + +Stable run id, when supplied by the caller. + +*** + ### source ```ts source: "server" | "client"; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:70](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L70) +Defined in: [packages/ai/src/activities/middleware/types.ts:80](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L80) Where the call originates. Always `'server'` for media activities. + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/activities/middleware/types.ts:70](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L70) + +Stable conversation/thread id, when supplied by the caller. diff --git a/docs/reference/interfaces/GenerationResultTransformContext.md b/docs/reference/interfaces/GenerationResultTransformContext.md new file mode 100644 index 0000000000..d6d435f386 --- /dev/null +++ b/docs/reference/interfaces/GenerationResultTransformContext.md @@ -0,0 +1,28 @@ +--- +id: GenerationResultTransformContext +title: GenerationResultTransformContext +--- + +# Interface: GenerationResultTransformContext\ + +Defined in: [packages/ai/src/activities/middleware/types.ts:108](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L108) + +Stable context handed to each [GenerationResultTransform](../type-aliases/GenerationResultTransform.md). + +## Type Parameters + +### TContext + +`TContext` = `unknown` + +## Properties + +### middleware + +```ts +middleware: GenerationMiddlewareContext; +``` + +Defined in: [packages/ai/src/activities/middleware/types.ts:110](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L110) + +The activity call being transformed. diff --git a/docs/reference/interfaces/GenerationUsageInfo.md b/docs/reference/interfaces/GenerationUsageInfo.md index 9fd477dab6..1666f276f7 100644 --- a/docs/reference/interfaces/GenerationUsageInfo.md +++ b/docs/reference/interfaces/GenerationUsageInfo.md @@ -5,7 +5,7 @@ title: GenerationUsageInfo # Interface: GenerationUsageInfo -Defined in: [packages/ai/src/activities/middleware/types.ts:86](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L86) +Defined in: [packages/ai/src/activities/middleware/types.ts:132](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L132) Token usage passed to [GenerationMiddleware.onUsage](GenerationMiddleware.md#onusage). Kept as an interface extending `TokenUsage` to preserve declaration merging for this diff --git a/docs/reference/interfaces/ImageAdapter.md b/docs/reference/interfaces/ImageAdapter.md index 95e8dad18f..9b8ee57d04 100644 --- a/docs/reference/interfaces/ImageAdapter.md +++ b/docs/reference/interfaces/ImageAdapter.md @@ -82,7 +82,7 @@ providerOptions: TProviderOptions; *** -### generateImages() +### generateImages ```ts generateImages: (options) => Promise; diff --git a/docs/reference/interfaces/ImageGenerationOptions.md b/docs/reference/interfaces/ImageGenerationOptions.md index e7834db528..a9f4a776a4 100644 --- a/docs/reference/interfaces/ImageGenerationOptions.md +++ b/docs/reference/interfaces/ImageGenerationOptions.md @@ -5,7 +5,7 @@ title: ImageGenerationOptions # Interface: ImageGenerationOptions\ -Defined in: [packages/ai/src/types.ts:1805](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1805) +Defined in: [packages/ai/src/types.ts:2181](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2181) Options for image generation. These are the common options supported across providers. @@ -22,13 +22,27 @@ These are the common options supported across providers. ## Properties +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2213](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2213) + +Effective abort signal composed by the activity from caller `abortSignal` +and/or `timeout`. Adapters should forward this to the provider SDK when +supported. Request-specific — never store on a global client config. + +*** + ### logger ```ts logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:1831](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1831) +Defined in: [packages/ai/src/types.ts:2207](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2207) Internal logger threaded from the generateImage() entry point. Adapters must call logger.request() before the SDK call and logger.errors() in catch blocks. @@ -41,7 +55,7 @@ call logger.request() before the SDK call and logger.errors() in catch blocks. model: string; ``` -Defined in: [packages/ai/src/types.ts:1810](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1810) +Defined in: [packages/ai/src/types.ts:2186](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2186) The model to use for image generation @@ -50,10 +64,10 @@ The model to use for image generation ### modelOptions? ```ts -optional modelOptions: TProviderOptions; +optional modelOptions?: TProviderOptions; ``` -Defined in: [packages/ai/src/types.ts:1826](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1826) +Defined in: [packages/ai/src/types.ts:2202](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2202) Model-specific options for image generation @@ -62,10 +76,10 @@ Model-specific options for image generation ### numberOfImages? ```ts -optional numberOfImages: number; +optional numberOfImages?: number; ``` -Defined in: [packages/ai/src/types.ts:1822](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1822) +Defined in: [packages/ai/src/types.ts:2198](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2198) Number of images to generate (default: 1) @@ -77,7 +91,7 @@ Number of images to generate (default: 1) prompt: MediaPrompt; ``` -Defined in: [packages/ai/src/types.ts:1820](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1820) +Defined in: [packages/ai/src/types.ts:2196](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2196) Description of the desired image(s): a plain string, or an ordered array of content parts for image-conditioned generation (image-to-image, @@ -92,9 +106,9 @@ multimodal `contents`, OpenAI `images.edit()`, fal `image_url` / ### size? ```ts -optional size: TSize; +optional size?: TSize; ``` -Defined in: [packages/ai/src/types.ts:1824](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1824) +Defined in: [packages/ai/src/types.ts:2200](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2200) Image size in WIDTHxHEIGHT format (e.g., "1024x1024") diff --git a/docs/reference/interfaces/ImageGenerationResult.md b/docs/reference/interfaces/ImageGenerationResult.md index 26a1a2aead..f267392a0b 100644 --- a/docs/reference/interfaces/ImageGenerationResult.md +++ b/docs/reference/interfaces/ImageGenerationResult.md @@ -5,19 +5,31 @@ title: ImageGenerationResult # Interface: ImageGenerationResult -Defined in: [packages/ai/src/types.ts:1863](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1863) +Defined in: [packages/ai/src/types.ts:2289](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2289) Result of image generation ## Properties +### artifacts? + +```ts +optional artifacts?: PersistedArtifactRef[]; +``` + +Defined in: [packages/ai/src/types.ts:2299](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2299) + +Persisted artifact references for generated assets, when available + +*** + ### id ```ts id: string; ``` -Defined in: [packages/ai/src/types.ts:1865](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1865) +Defined in: [packages/ai/src/types.ts:2291](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2291) Unique identifier for the generation @@ -29,7 +41,7 @@ Unique identifier for the generation images: GeneratedImage[]; ``` -Defined in: [packages/ai/src/types.ts:1869](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1869) +Defined in: [packages/ai/src/types.ts:2295](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2295) Array of generated images @@ -41,7 +53,7 @@ Array of generated images model: string; ``` -Defined in: [packages/ai/src/types.ts:1867](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1867) +Defined in: [packages/ai/src/types.ts:2293](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2293) Model used for generation @@ -50,9 +62,9 @@ Model used for generation ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:1871](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1871) +Defined in: [packages/ai/src/types.ts:2297](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2297) Token usage information (if available) diff --git a/docs/reference/interfaces/ImagePart.md b/docs/reference/interfaces/ImagePart.md index bc8bc5331a..c6f0b0388c 100644 --- a/docs/reference/interfaces/ImagePart.md +++ b/docs/reference/interfaces/ImagePart.md @@ -5,7 +5,7 @@ title: ImagePart # Interface: ImagePart\ -Defined in: [packages/ai/src/types.ts:248](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L248) +Defined in: [packages/ai/src/types.ts:259](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L259) Image content part for multimodal messages. @@ -22,10 +22,10 @@ Provider-specific metadata type (e.g., OpenAI's detail level) ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:253](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L253) +Defined in: [packages/ai/src/types.ts:264](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L264) Provider-specific metadata (e.g., OpenAI's detail: 'auto' | 'low' | 'high') @@ -37,7 +37,7 @@ Provider-specific metadata (e.g., OpenAI's detail: 'auto' | 'low' | 'high') source: ContentPartSource; ``` -Defined in: [packages/ai/src/types.ts:251](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L251) +Defined in: [packages/ai/src/types.ts:262](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L262) Source of the image content @@ -49,4 +49,4 @@ Source of the image content type: "image"; ``` -Defined in: [packages/ai/src/types.ts:249](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L249) +Defined in: [packages/ai/src/types.ts:260](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L260) diff --git a/docs/reference/interfaces/InternalToolCallState.md b/docs/reference/interfaces/InternalToolCallState.md index 94d218cad5..39bc8163a0 100644 --- a/docs/reference/interfaces/InternalToolCallState.md +++ b/docs/reference/interfaces/InternalToolCallState.md @@ -44,7 +44,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:27](https://github. ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:32](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L32) @@ -69,7 +69,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:23](https://github. ### parsedArguments? ```ts -optional parsedArguments: any; +optional parsedArguments?: any; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:26](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L26) diff --git a/docs/reference/interfaces/InterruptCorrelation.md b/docs/reference/interfaces/InterruptCorrelation.md new file mode 100644 index 0000000000..69d33d99da --- /dev/null +++ b/docs/reference/interfaces/InterruptCorrelation.md @@ -0,0 +1,63 @@ +--- +id: InterruptCorrelation +title: InterruptCorrelation +--- + +# Interface: InterruptCorrelation + +Defined in: [packages/ai/src/interrupts.ts:8](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L8) + +## Extended by + +- [`BatchInterruptError`](BatchInterruptError.md) +- [`ItemInterruptError`](ItemInterruptError.md) + +## Properties + +### continuationRunId? + +```ts +optional continuationRunId?: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:13](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L13) + +*** + +### generation + +```ts +generation: number; +``` + +Defined in: [packages/ai/src/interrupts.ts:11](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L11) + +*** + +### interruptedRunId + +```ts +interruptedRunId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:10](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L10) + +*** + +### submissionId? + +```ts +optional submissionId?: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L12) + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:9](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L9) diff --git a/docs/reference/interfaces/ItemInterruptError.md b/docs/reference/interfaces/ItemInterruptError.md new file mode 100644 index 0000000000..33c923c470 --- /dev/null +++ b/docs/reference/interfaces/ItemInterruptError.md @@ -0,0 +1,152 @@ +--- +id: ItemInterruptError +title: ItemInterruptError +--- + +# Interface: ItemInterruptError + +Defined in: [packages/ai/src/interrupts.ts:43](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L43) + +## Extends + +- [`InterruptCorrelation`](InterruptCorrelation.md) + +## Properties + +### code + +```ts +code: ItemInterruptErrorCode; +``` + +Defined in: [packages/ai/src/interrupts.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L46) + +*** + +### continuationRunId? + +```ts +optional continuationRunId?: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:13](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L13) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`continuationRunId`](InterruptCorrelation.md#continuationrunid) + +*** + +### generation + +```ts +generation: number; +``` + +Defined in: [packages/ai/src/interrupts.ts:11](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L11) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`generation`](InterruptCorrelation.md#generation) + +*** + +### interruptedRunId + +```ts +interruptedRunId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:10](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L10) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`interruptedRunId`](InterruptCorrelation.md#interruptedrunid) + +*** + +### interruptId + +```ts +interruptId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:45](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L45) + +*** + +### message + +```ts +message: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:47](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L47) + +*** + +### path? + +```ts +optional path?: readonly (string | number)[]; +``` + +Defined in: [packages/ai/src/interrupts.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L48) + +*** + +### retryable + +```ts +retryable: boolean; +``` + +Defined in: [packages/ai/src/interrupts.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L50) + +*** + +### scope + +```ts +scope: "item"; +``` + +Defined in: [packages/ai/src/interrupts.ts:44](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L44) + +*** + +### source + +```ts +source: "server" | "client"; +``` + +Defined in: [packages/ai/src/interrupts.ts:49](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L49) + +*** + +### submissionId? + +```ts +optional submissionId?: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L12) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`submissionId`](InterruptCorrelation.md#submissionid) + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/interrupts.ts:9](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L9) + +#### Inherited from + +[`InterruptCorrelation`](InterruptCorrelation.md).[`threadId`](InterruptCorrelation.md#threadid) diff --git a/docs/reference/interfaces/IterationInfo.md b/docs/reference/interfaces/IterationInfo.md index 9461dbd84e..e1294ccc33 100644 --- a/docs/reference/interfaces/IterationInfo.md +++ b/docs/reference/interfaces/IterationInfo.md @@ -5,7 +5,7 @@ title: IterationInfo # Interface: IterationInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:296](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L296) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:322](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L322) Information passed to onIteration at the start of each agent loop iteration. @@ -17,7 +17,7 @@ Information passed to onIteration at the start of each agent loop iteration. iteration: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:298](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L298) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:324](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L324) 0-based iteration index @@ -29,6 +29,6 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:298](https://gi messageId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:300](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L300) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:326](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L326) The assistant message ID created for this iteration diff --git a/docs/reference/interfaces/JSONParser.md b/docs/reference/interfaces/JSONParser.md index d85be3f707..6955b36d42 100644 --- a/docs/reference/interfaces/JSONParser.md +++ b/docs/reference/interfaces/JSONParser.md @@ -11,7 +11,7 @@ JSON Parser interface - allows for custom parser implementations ## Properties -### parse() +### parse ```ts parse: (jsonString) => any; diff --git a/docs/reference/interfaces/JSONSchema.md b/docs/reference/interfaces/JSONSchema.md index 76656a719a..db2543a64c 100644 --- a/docs/reference/interfaces/JSONSchema.md +++ b/docs/reference/interfaces/JSONSchema.md @@ -5,7 +5,7 @@ title: JSONSchema # Interface: JSONSchema -Defined in: [packages/ai/src/types.ts:71](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L71) +Defined in: [packages/ai/src/types.ts:82](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L82) JSON Schema type for defining tool input/output schemas as raw JSON Schema objects. This allows tools to be defined without schema libraries when you have JSON Schema definitions available. @@ -21,367 +21,367 @@ This allows tools to be defined without schema libraries when you have JSON Sche ### $defs? ```ts -optional $defs: Record; +optional $defs?: Record; ``` -Defined in: [packages/ai/src/types.ts:81](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L81) +Defined in: [packages/ai/src/types.ts:92](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L92) *** ### $ref? ```ts -optional $ref: string; +optional $ref?: string; ``` -Defined in: [packages/ai/src/types.ts:80](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L80) +Defined in: [packages/ai/src/types.ts:91](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L91) *** ### additionalItems? ```ts -optional additionalItems: boolean | JSONSchema; +optional additionalItems?: boolean | JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:102](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L102) +Defined in: [packages/ai/src/types.ts:113](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L113) *** ### additionalProperties? ```ts -optional additionalProperties: boolean | JSONSchema; +optional additionalProperties?: boolean | JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:101](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L101) +Defined in: [packages/ai/src/types.ts:112](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L112) *** ### allOf? ```ts -optional allOf: JSONSchema[]; +optional allOf?: JSONSchema[]; ``` -Defined in: [packages/ai/src/types.ts:83](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L83) +Defined in: [packages/ai/src/types.ts:94](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L94) *** ### anyOf? ```ts -optional anyOf: JSONSchema[]; +optional anyOf?: JSONSchema[]; ``` -Defined in: [packages/ai/src/types.ts:84](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L84) +Defined in: [packages/ai/src/types.ts:95](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L95) *** ### const? ```ts -optional const: unknown; +optional const?: unknown; ``` -Defined in: [packages/ai/src/types.ts:77](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L77) +Defined in: [packages/ai/src/types.ts:88](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L88) *** ### default? ```ts -optional default: unknown; +optional default?: unknown; ``` -Defined in: [packages/ai/src/types.ts:79](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L79) +Defined in: [packages/ai/src/types.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L90) *** ### definitions? ```ts -optional definitions: Record; +optional definitions?: Record; ``` -Defined in: [packages/ai/src/types.ts:82](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L82) +Defined in: [packages/ai/src/types.ts:93](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L93) *** ### description? ```ts -optional description: string; +optional description?: string; ``` -Defined in: [packages/ai/src/types.ts:78](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L78) +Defined in: [packages/ai/src/types.ts:89](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L89) *** ### else? ```ts -optional else: JSONSchema; +optional else?: JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:89](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L89) +Defined in: [packages/ai/src/types.ts:100](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L100) *** ### enum? ```ts -optional enum: unknown[]; +optional enum?: unknown[]; ``` -Defined in: [packages/ai/src/types.ts:76](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L76) +Defined in: [packages/ai/src/types.ts:87](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L87) *** ### examples? ```ts -optional examples: unknown[]; +optional examples?: unknown[]; ``` -Defined in: [packages/ai/src/types.ts:108](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L108) +Defined in: [packages/ai/src/types.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L119) *** ### exclusiveMaximum? ```ts -optional exclusiveMaximum: number; +optional exclusiveMaximum?: number; ``` -Defined in: [packages/ai/src/types.ts:93](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L93) +Defined in: [packages/ai/src/types.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L104) *** ### exclusiveMinimum? ```ts -optional exclusiveMinimum: number; +optional exclusiveMinimum?: number; ``` -Defined in: [packages/ai/src/types.ts:92](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L92) +Defined in: [packages/ai/src/types.ts:103](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L103) *** ### format? ```ts -optional format: string; +optional format?: string; ``` -Defined in: [packages/ai/src/types.ts:97](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L97) +Defined in: [packages/ai/src/types.ts:108](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L108) *** ### if? ```ts -optional if: JSONSchema; +optional if?: JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:87](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L87) +Defined in: [packages/ai/src/types.ts:98](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L98) *** ### items? ```ts -optional items: JSONSchema | JSONSchema[]; +optional items?: JSONSchema | JSONSchema[]; ``` -Defined in: [packages/ai/src/types.ts:74](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L74) +Defined in: [packages/ai/src/types.ts:85](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L85) *** ### maximum? ```ts -optional maximum: number; +optional maximum?: number; ``` -Defined in: [packages/ai/src/types.ts:91](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L91) +Defined in: [packages/ai/src/types.ts:102](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L102) *** ### maxItems? ```ts -optional maxItems: number; +optional maxItems?: number; ``` -Defined in: [packages/ai/src/types.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L99) +Defined in: [packages/ai/src/types.ts:110](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L110) *** ### maxLength? ```ts -optional maxLength: number; +optional maxLength?: number; ``` -Defined in: [packages/ai/src/types.ts:95](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L95) +Defined in: [packages/ai/src/types.ts:106](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L106) *** ### maxProperties? ```ts -optional maxProperties: number; +optional maxProperties?: number; ``` -Defined in: [packages/ai/src/types.ts:106](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L106) +Defined in: [packages/ai/src/types.ts:117](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L117) *** ### minimum? ```ts -optional minimum: number; +optional minimum?: number; ``` -Defined in: [packages/ai/src/types.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L90) +Defined in: [packages/ai/src/types.ts:101](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L101) *** ### minItems? ```ts -optional minItems: number; +optional minItems?: number; ``` -Defined in: [packages/ai/src/types.ts:98](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L98) +Defined in: [packages/ai/src/types.ts:109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L109) *** ### minLength? ```ts -optional minLength: number; +optional minLength?: number; ``` -Defined in: [packages/ai/src/types.ts:94](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L94) +Defined in: [packages/ai/src/types.ts:105](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L105) *** ### minProperties? ```ts -optional minProperties: number; +optional minProperties?: number; ``` -Defined in: [packages/ai/src/types.ts:105](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L105) +Defined in: [packages/ai/src/types.ts:116](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L116) *** ### not? ```ts -optional not: JSONSchema; +optional not?: JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:86](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L86) +Defined in: [packages/ai/src/types.ts:97](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L97) *** ### oneOf? ```ts -optional oneOf: JSONSchema[]; +optional oneOf?: JSONSchema[]; ``` -Defined in: [packages/ai/src/types.ts:85](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L85) +Defined in: [packages/ai/src/types.ts:96](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L96) *** ### pattern? ```ts -optional pattern: string; +optional pattern?: string; ``` -Defined in: [packages/ai/src/types.ts:96](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L96) +Defined in: [packages/ai/src/types.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L107) *** ### patternProperties? ```ts -optional patternProperties: Record; +optional patternProperties?: Record; ``` -Defined in: [packages/ai/src/types.ts:103](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L103) +Defined in: [packages/ai/src/types.ts:114](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L114) *** ### properties? ```ts -optional properties: Record; +optional properties?: Record; ``` -Defined in: [packages/ai/src/types.ts:73](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L73) +Defined in: [packages/ai/src/types.ts:84](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L84) *** ### propertyNames? ```ts -optional propertyNames: JSONSchema; +optional propertyNames?: JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L104) +Defined in: [packages/ai/src/types.ts:115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L115) *** ### required? ```ts -optional required: string[]; +optional required?: string[]; ``` -Defined in: [packages/ai/src/types.ts:75](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L75) +Defined in: [packages/ai/src/types.ts:86](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L86) *** ### then? ```ts -optional then: JSONSchema; +optional then?: JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:88](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L88) +Defined in: [packages/ai/src/types.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L99) *** ### title? ```ts -optional title: string; +optional title?: string; ``` -Defined in: [packages/ai/src/types.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L107) +Defined in: [packages/ai/src/types.ts:118](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L118) *** ### type? ```ts -optional type: string | string[]; +optional type?: string | string[]; ``` -Defined in: [packages/ai/src/types.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L72) +Defined in: [packages/ai/src/types.ts:83](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L83) *** ### uniqueItems? ```ts -optional uniqueItems: boolean; +optional uniqueItems?: boolean; ``` -Defined in: [packages/ai/src/types.ts:100](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L100) +Defined in: [packages/ai/src/types.ts:111](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L111) diff --git a/docs/reference/interfaces/LazyToolsConfig.md b/docs/reference/interfaces/LazyToolsConfig.md index e29e6808df..98626e289e 100644 --- a/docs/reference/interfaces/LazyToolsConfig.md +++ b/docs/reference/interfaces/LazyToolsConfig.md @@ -5,7 +5,7 @@ title: LazyToolsConfig # Interface: LazyToolsConfig -Defined in: [packages/ai/src/types.ts:721](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L721) +Defined in: [packages/ai/src/types.ts:746](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L746) Configuration for the lazy-tool discovery catalog, shared by chat() and Code Mode. Optional in both — lazy behavior is triggered purely by tools @@ -18,10 +18,10 @@ always returns the full description + schema. ### includeDescription? ```ts -optional includeDescription: "full" | "first-sentence" | "none"; +optional includeDescription?: "full" | "first-sentence" | "none"; ``` -Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727) +Defined in: [packages/ai/src/types.ts:752](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L752) How much of each lazy tool's description appears in the pre-discovery catalog (the names list shown before the model discovers the tool). diff --git a/docs/reference/interfaces/Logger.md b/docs/reference/interfaces/Logger.md index 5a93aedb98..7c6d4325c1 100644 --- a/docs/reference/interfaces/Logger.md +++ b/docs/reference/interfaces/Logger.md @@ -11,7 +11,7 @@ Pluggable logger interface consumed by every `@tanstack/ai` activity when `debug ## Properties -### debug() +### debug ```ts debug: (message, meta?) => void; @@ -39,7 +39,7 @@ Structured data forwarded to the underlying logger. Loggers like pino will prese *** -### error() +### error ```ts error: (message, meta?) => void; @@ -67,7 +67,7 @@ Structured data forwarded to the underlying logger. Loggers like pino will prese *** -### info() +### info ```ts info: (message, meta?) => void; @@ -95,7 +95,7 @@ Structured data forwarded to the underlying logger. Loggers like pino will prese *** -### warn() +### warn ```ts warn: (message, meta?) => void; diff --git a/docs/reference/interfaces/MCPToolSource.md b/docs/reference/interfaces/MCPToolSource.md index b894a81d73..504daf3a2b 100644 --- a/docs/reference/interfaces/MCPToolSource.md +++ b/docs/reference/interfaces/MCPToolSource.md @@ -15,7 +15,7 @@ shape — the core `@tanstack/ai` package does NOT import `@tanstack/ai-mcp` ## Properties -### close() +### close ```ts close: () => Promise; @@ -29,10 +29,10 @@ Defined in: [packages/ai/src/activities/chat/mcp/types.ts:30](https://github.com *** -### readResource()? +### readResource? ```ts -optional readResource: (uri) => Promise; +optional readResource?: (uri) => Promise; ``` Defined in: [packages/ai/src/activities/chat/mcp/types.ts:38](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/mcp/types.ts#L38) @@ -55,10 +55,10 @@ this method. `ai-mcp`'s `MCPClient` satisfies this structurally. *** -### tools() +### tools ```ts -tools: (options?) => Promise[]>; +tools: (options?) => Promise; ``` Defined in: [packages/ai/src/activities/chat/mcp/types.ts:29](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/mcp/types.ts#L29) @@ -73,4 +73,4 @@ Defined in: [packages/ai/src/activities/chat/mcp/types.ts:29](https://github.com #### Returns -`Promise`\<[`ServerTool`](ServerTool.md)\<[`SchemaInput`](../type-aliases/SchemaInput.md), [`SchemaInput`](../type-aliases/SchemaInput.md), `string`, `unknown`\>[]\> +`Promise`\<[`AnyServerTool`](../type-aliases/AnyServerTool.md)[]\> diff --git a/docs/reference/interfaces/MediaInputMetadata.md b/docs/reference/interfaces/MediaInputMetadata.md index 007f66a54f..d9344fcc02 100644 --- a/docs/reference/interfaces/MediaInputMetadata.md +++ b/docs/reference/interfaces/MediaInputMetadata.md @@ -5,7 +5,7 @@ title: MediaInputMetadata # Interface: MediaInputMetadata -Defined in: [packages/ai/src/types.ts:1728](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1728) +Defined in: [packages/ai/src/types.ts:2104](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2104) Metadata convention for image / video / audio inputs to media generation. Carried on `ImagePart.metadata` / `VideoPart.metadata` / `AudioPart.metadata` @@ -16,10 +16,10 @@ when used as conditioning inputs to `generateImage()` or `generateVideo()`. ### role? ```ts -optional role: MediaInputRole; +optional role?: MediaInputRole; ``` -Defined in: [packages/ai/src/types.ts:1730](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1730) +Defined in: [packages/ai/src/types.ts:2106](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2106) Optional role hint disambiguating the part's intent for the adapter @@ -28,10 +28,10 @@ Optional role hint disambiguating the part's intent for the adapter ### tag? ```ts -optional tag: string; +optional tag?: string; ``` -Defined in: [packages/ai/src/types.ts:1739](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1739) +Defined in: [packages/ai/src/types.ts:2115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2115) Optional user-defined label for this input (e.g. `'woman-in-red-dress'`). **Informational only** — adapters never read it and the SDK never diff --git a/docs/reference/interfaces/MemoryStreamInit.md b/docs/reference/interfaces/MemoryStreamInit.md new file mode 100644 index 0000000000..7ae1e34f11 --- /dev/null +++ b/docs/reference/interfaces/MemoryStreamInit.md @@ -0,0 +1,42 @@ +--- +id: MemoryStreamInit +title: MemoryStreamInit +--- + +# Interface: MemoryStreamInit + +Defined in: [packages/ai/src/stream-durability.ts:308](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L308) + +Explicit construction for [memoryStream](../functions/memoryStream.md), for callers that don't have +the incoming `Request` — e.g. a TanStack Start server function implementing +a `joinRun` replay for a run id it received as call data: + +```ts +const durability = memoryStream({ runId }) +for await (const chunk of replayRunStream(durability)) yield chunk +``` + +## Properties + +### offset? + +```ts +optional offset?: string | null; +``` + +Defined in: [packages/ai/src/stream-durability.ts:315](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L315) + +Resume offset captured by the consumer (`resumeFrom()` returns it). +Defaults to `null` (a producer / from-start reader). + +*** + +### runId + +```ts +runId: string; +``` + +Defined in: [packages/ai/src/stream-durability.ts:310](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L310) + +The run this durability adapter attaches to. diff --git a/docs/reference/interfaces/MemoryStreamOptions.md b/docs/reference/interfaces/MemoryStreamOptions.md new file mode 100644 index 0000000000..d665fec3b5 --- /dev/null +++ b/docs/reference/interfaces/MemoryStreamOptions.md @@ -0,0 +1,24 @@ +--- +id: MemoryStreamOptions +title: MemoryStreamOptions +--- + +# Interface: MemoryStreamOptions + +Defined in: [packages/ai/src/stream-durability.ts:242](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L242) + +Options for the in-process delivery-durability backend. + +## Properties + +### firstChunkDeadlineMs? + +```ts +optional firstChunkDeadlineMs?: number; +``` + +Defined in: [packages/ai/src/stream-durability.ts:248](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L248) + +Milliseconds a from-start join waits for the run's first chunk before +throwing. Defaults to DEFAULT\_FIRST\_CHUNK\_DEADLINE\_MS (100ms) — +raise it if a producer can legitimately start long after a joiner attaches. diff --git a/docs/reference/interfaces/MessagesSnapshotEvent.md b/docs/reference/interfaces/MessagesSnapshotEvent.md index 0b42e9e948..55d3378e02 100644 --- a/docs/reference/interfaces/MessagesSnapshotEvent.md +++ b/docs/reference/interfaces/MessagesSnapshotEvent.md @@ -5,7 +5,7 @@ title: MessagesSnapshotEvent # Interface: MessagesSnapshotEvent -Defined in: [packages/ai/src/types.ts:1299](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1299) +Defined in: [packages/ai/src/types.ts:1359](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1359) Emitted to provide a snapshot of all messages in a conversation. @@ -33,9 +33,9 @@ Use converters to transform to/from TanStack UIMessage format. ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1301](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1301) +Defined in: [packages/ai/src/types.ts:1361](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1361) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ModelCapabilities.md b/docs/reference/interfaces/ModelCapabilities.md index 633df6a635..1f856b1d61 100644 --- a/docs/reference/interfaces/ModelCapabilities.md +++ b/docs/reference/interfaces/ModelCapabilities.md @@ -32,7 +32,7 @@ Capability bag accepted by the object form of `createModel`. ### features? ```ts -optional features: TFeatures; +optional features?: TFeatures; ``` Defined in: [packages/ai/src/extend-adapter.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/extend-adapter.ts#L48) @@ -42,7 +42,7 @@ Defined in: [packages/ai/src/extend-adapter.ts:48](https://github.com/TanStack/a ### input? ```ts -optional input: TInput; +optional input?: TInput; ``` Defined in: [packages/ai/src/extend-adapter.ts:47](https://github.com/TanStack/ai/blob/main/packages/ai/src/extend-adapter.ts#L47) @@ -52,7 +52,7 @@ Defined in: [packages/ai/src/extend-adapter.ts:47](https://github.com/TanStack/a ### modelOptions? ```ts -optional modelOptions: TOptions; +optional modelOptions?: TOptions; ``` Defined in: [packages/ai/src/extend-adapter.ts:50](https://github.com/TanStack/ai/blob/main/packages/ai/src/extend-adapter.ts#L50) @@ -62,7 +62,7 @@ Defined in: [packages/ai/src/extend-adapter.ts:50](https://github.com/TanStack/a ### tools? ```ts -optional tools: TTools; +optional tools?: TTools; ``` Defined in: [packages/ai/src/extend-adapter.ts:49](https://github.com/TanStack/ai/blob/main/packages/ai/src/extend-adapter.ts#L49) diff --git a/docs/reference/interfaces/ModelMessage.md b/docs/reference/interfaces/ModelMessage.md index 6d2de2dce4..51f88127fe 100644 --- a/docs/reference/interfaces/ModelMessage.md +++ b/docs/reference/interfaces/ModelMessage.md @@ -5,7 +5,7 @@ title: ModelMessage # Interface: ModelMessage\ -Defined in: [packages/ai/src/types.ts:347](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L347) +Defined in: [packages/ai/src/types.ts:358](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L358) ## Type Parameters @@ -21,17 +21,47 @@ Defined in: [packages/ai/src/types.ts:347](https://github.com/TanStack/ai/blob/m content: TContent; ``` -Defined in: [packages/ai/src/types.ts:354](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L354) +Defined in: [packages/ai/src/types.ts:365](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L365) + +*** + +### createdAt? + +```ts +optional createdAt?: Date; +``` + +Defined in: [packages/ai/src/types.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L383) + +Optional message creation timestamp. When present, message converters +preserve it across persist → hydrate round-trips. + +*** + +### id? + +```ts +optional id?: string; +``` + +Defined in: [packages/ai/src/types.ts:378](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L378) + +Optional stable message id. Providers ignore it; it exists so a persisted +transcript can retain the streaming `messageId` and survive the +persist → hydrate round-trip. When present, `modelMessagesToUIMessages` +reuses it instead of generating a fresh id, so a hydrated message keeps the +same identity as its live stream — which is what lets a mid-stream reload +resume the SAME message bubble in place (see `@tanstack/ai-persistence`). *** ### name? ```ts -optional name: string; +optional name?: string; ``` -Defined in: [packages/ai/src/types.ts:355](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L355) +Defined in: [packages/ai/src/types.ts:366](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L366) *** @@ -41,17 +71,17 @@ Defined in: [packages/ai/src/types.ts:355](https://github.com/TanStack/ai/blob/m role: "user" | "assistant" | "tool"; ``` -Defined in: [packages/ai/src/types.ts:353](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L353) +Defined in: [packages/ai/src/types.ts:364](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L364) *** ### thinking? ```ts -optional thinking: object[]; +optional thinking?: object[]; ``` -Defined in: [packages/ai/src/types.ts:358](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L358) +Defined in: [packages/ai/src/types.ts:369](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L369) #### content @@ -62,7 +92,7 @@ content: string; #### signature? ```ts -optional signature: string; +optional signature?: string; ``` *** @@ -70,17 +100,17 @@ optional signature: string; ### toolCallId? ```ts -optional toolCallId: string; +optional toolCallId?: string; ``` -Defined in: [packages/ai/src/types.ts:357](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L357) +Defined in: [packages/ai/src/types.ts:368](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L368) *** ### toolCalls? ```ts -optional toolCalls: ToolCall[]; +optional toolCalls?: ToolCall[]; ``` -Defined in: [packages/ai/src/types.ts:356](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L356) +Defined in: [packages/ai/src/types.ts:367](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L367) diff --git a/docs/reference/interfaces/NormalizedApprovalSchema.md b/docs/reference/interfaces/NormalizedApprovalSchema.md new file mode 100644 index 0000000000..b1c385668d --- /dev/null +++ b/docs/reference/interfaces/NormalizedApprovalSchema.md @@ -0,0 +1,60 @@ +--- +id: NormalizedApprovalSchema +title: NormalizedApprovalSchema +--- + +# Interface: NormalizedApprovalSchema + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:16](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L16) + +## Properties + +### approvalSchemaHash + +```ts +approvalSchemaHash: string; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:23](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L23) + +*** + +### branches + +```ts +branches: object; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:17](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L17) + +#### approve + +```ts +approve: NormalizedSchemaInput | null; +``` + +#### reject + +```ts +reject: NormalizedSchemaInput | null; +``` + +*** + +### responseSchema + +```ts +responseSchema: JSONSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:21](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L21) + +*** + +### responseSchemaHash + +```ts +responseSchemaHash: string; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:22](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L22) diff --git a/docs/reference/interfaces/NormalizedSchemaInput.md b/docs/reference/interfaces/NormalizedSchemaInput.md new file mode 100644 index 0000000000..b347dbef2d --- /dev/null +++ b/docs/reference/interfaces/NormalizedSchemaInput.md @@ -0,0 +1,38 @@ +--- +id: NormalizedSchemaInput +title: NormalizedSchemaInput +--- + +# Interface: NormalizedSchemaInput + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:10](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L10) + +## Properties + +### jsonSchema? + +```ts +optional jsonSchema?: JSONSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:13](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L13) + +*** + +### source + +```ts +source: SchemaInput; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:11](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L11) + +*** + +### validator? + +```ts +optional validator?: StandardSchemaV1; +``` + +Defined in: [packages/ai/src/activities/chat/tools/approval-schema.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/approval-schema.ts#L12) diff --git a/docs/reference/interfaces/NormalizedSystemPrompt.md b/docs/reference/interfaces/NormalizedSystemPrompt.md index ebf4916d48..b2c5acaccf 100644 --- a/docs/reference/interfaces/NormalizedSystemPrompt.md +++ b/docs/reference/interfaces/NormalizedSystemPrompt.md @@ -33,7 +33,7 @@ Defined in: [packages/ai/src/system-prompts.ts:53](https://github.com/TanStack/a ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` Defined in: [packages/ai/src/system-prompts.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/system-prompts.ts#L54) diff --git a/docs/reference/interfaces/PendingInterruptResumeRecord.md b/docs/reference/interfaces/PendingInterruptResumeRecord.md new file mode 100644 index 0000000000..2700af81b2 --- /dev/null +++ b/docs/reference/interfaces/PendingInterruptResumeRecord.md @@ -0,0 +1,40 @@ +--- +id: PendingInterruptResumeRecord +title: PendingInterruptResumeRecord +--- + +# Interface: PendingInterruptResumeRecord + +Defined in: [packages/ai/src/interrupt-resume.ts:45](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L45) + +The persistence-neutral shape required to validate an interrupt resume. + +## Properties + +### binding + +```ts +binding: InterruptBinding; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L48) + +*** + +### interruptId + +```ts +interruptId: string; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L46) + +*** + +### payload + +```ts +payload: unknown; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:47](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L47) diff --git a/docs/reference/interfaces/PersistedArtifactRef.md b/docs/reference/interfaces/PersistedArtifactRef.md new file mode 100644 index 0000000000..55e223dfa2 --- /dev/null +++ b/docs/reference/interfaces/PersistedArtifactRef.md @@ -0,0 +1,171 @@ +--- +id: PersistedArtifactRef +title: PersistedArtifactRef +--- + +# Interface: PersistedArtifactRef + +Defined in: [packages/ai/src/types.ts:2243](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2243) + +## Properties + +### artifactId + +```ts +artifactId: string; +``` + +Defined in: [packages/ai/src/types.ts:2245](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2245) + +*** + +### createdAt + +```ts +createdAt: string; +``` + +Defined in: [packages/ai/src/types.ts:2251](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2251) + +*** + +### mimeType + +```ts +mimeType: string; +``` + +Defined in: [packages/ai/src/types.ts:2249](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2249) + +*** + +### name + +```ts +name: string; +``` + +Defined in: [packages/ai/src/types.ts:2248](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2248) + +*** + +### role + +```ts +role: PersistedArtifactRole; +``` + +Defined in: [packages/ai/src/types.ts:2244](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2244) + +*** + +### runId + +```ts +runId: string; +``` + +Defined in: [packages/ai/src/types.ts:2247](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2247) + +*** + +### size + +```ts +size: number; +``` + +Defined in: [packages/ai/src/types.ts:2250](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2250) + +*** + +### source + +```ts +source: object; +``` + +Defined in: [packages/ai/src/types.ts:2267](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2267) + +#### activity + +```ts +activity: PersistedArtifactActivity; +``` + +#### expiresAt? + +```ts +optional expiresAt?: string; +``` + +#### jobId? + +```ts +optional jobId?: string; +``` + +#### mediaType? + +```ts +optional mediaType?: "image" | "audio" | "video" | "document" | "json"; +``` + +#### model + +```ts +model: string; +``` + +#### path + +```ts +path: string; +``` + +#### provider + +```ts +provider: string; +``` + +*** + +### sourceUrl? + +```ts +optional sourceUrl?: string; +``` + +Defined in: [packages/ai/src/types.ts:2258](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2258) + +Where these bytes were fetched FROM — the provider's original result URL, +or a caller-supplied prompt URL when `allowInputUrl` opted that in. Usually +expiring, and provenance only: serve from [PersistedArtifactRef.url](#url) +instead. + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/types.ts:2246](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2246) + +*** + +### url? + +```ts +optional url?: string; +``` + +Defined in: [packages/ai/src/types.ts:2266](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2266) + +Durable app-origin URL that serves this artifact's persisted bytes (your +`GET` route around `retrieveArtifact` / `retrieveBlob`). Stamped by +`withGenerationPersistence`'s `artifactUrl` option, so clients render and +restore durable media from your own origin rather than the provider's +expiring link. diff --git a/docs/reference/interfaces/PortOpenedPayload.md b/docs/reference/interfaces/PortOpenedPayload.md new file mode 100644 index 0000000000..b1e70515c3 --- /dev/null +++ b/docs/reference/interfaces/PortOpenedPayload.md @@ -0,0 +1,30 @@ +--- +id: PortOpenedPayload +title: PortOpenedPayload +--- + +# Interface: PortOpenedPayload + +Defined in: [packages/ai/src/custom-events.ts:51](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L51) + +## Properties + +### port + +```ts +port: number; +``` + +Defined in: [packages/ai/src/custom-events.ts:52](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L52) + +*** + +### url? + +```ts +optional url?: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L54) + +Externally reachable URL, when the provider exposes one. diff --git a/docs/reference/interfaces/ProcessOutputPayload.md b/docs/reference/interfaces/ProcessOutputPayload.md new file mode 100644 index 0000000000..4384f2094f --- /dev/null +++ b/docs/reference/interfaces/ProcessOutputPayload.md @@ -0,0 +1,32 @@ +--- +id: ProcessOutputPayload +title: ProcessOutputPayload +--- + +# Interface: ProcessOutputPayload + +Defined in: [packages/ai/src/custom-events.ts:44](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L44) + +## Properties + +### chunk + +```ts +chunk: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L48) + +A chunk of stdout/stderr text. + +*** + +### processId + +```ts +processId: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L46) + +Stable id for the spawned process whose output this is. diff --git a/docs/reference/interfaces/ProcessorResult.md b/docs/reference/interfaces/ProcessorResult.md index a48bc8f6b4..1d537e740d 100644 --- a/docs/reference/interfaces/ProcessorResult.md +++ b/docs/reference/interfaces/ProcessorResult.md @@ -24,7 +24,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:79](https://github. ### finishReason? ```ts -optional finishReason: string | null; +optional finishReason?: string | null; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:82](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L82) @@ -34,7 +34,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:82](https://github. ### thinking? ```ts -optional thinking: string; +optional thinking?: string; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:80](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L80) @@ -44,7 +44,7 @@ Defined in: [packages/ai/src/activities/chat/stream/types.ts:80](https://github. ### toolCalls? ```ts -optional toolCalls: ToolCall[]; +optional toolCalls?: ToolCall[]; ``` Defined in: [packages/ai/src/activities/chat/stream/types.ts:81](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/types.ts#L81) diff --git a/docs/reference/interfaces/ProviderExecutedToolMetadata.md b/docs/reference/interfaces/ProviderExecutedToolMetadata.md index c162deed87..eee3bd4540 100644 --- a/docs/reference/interfaces/ProviderExecutedToolMetadata.md +++ b/docs/reference/interfaces/ProviderExecutedToolMetadata.md @@ -5,7 +5,7 @@ title: ProviderExecutedToolMetadata # Interface: ProviderExecutedToolMetadata -Defined in: [packages/ai/src/types.ts:178](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L178) +Defined in: [packages/ai/src/types.ts:189](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L189) Convention for tool-call `metadata` that marks a call as **provider-executed** — run by the provider's own infrastructure (e.g. Anthropic `web_search` / @@ -32,7 +32,7 @@ preserves those per-adapter fields. ### providerExecuted? ```ts -optional providerExecuted: boolean; +optional providerExecuted?: boolean; ``` -Defined in: [packages/ai/src/types.ts:179](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L179) +Defined in: [packages/ai/src/types.ts:190](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L190) diff --git a/docs/reference/interfaces/ProviderTool.md b/docs/reference/interfaces/ProviderTool.md index ab26b46694..3214327057 100644 --- a/docs/reference/interfaces/ProviderTool.md +++ b/docs/reference/interfaces/ProviderTool.md @@ -65,7 +65,7 @@ Defined in: [packages/ai/src/tools/provider-tool.ts:24](https://github.com/TanSt description: string; ``` -Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622) +Defined in: [packages/ai/src/types.ts:647](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L647) Clear description of what the tool does. @@ -84,13 +84,13 @@ Be specific about what the tool does, what parameters it needs, and what it retu *** -### execute()? +### execute? ```ts -optional execute: (args, context?) => any; +optional execute?: (args, context?) => any; ``` -Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702) +Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727) Optional function to execute when the model calls this tool. @@ -135,10 +135,10 @@ execute: async (args) => { ### inputSchema? ```ts -optional inputSchema: SchemaInput; +optional inputSchema?: SchemaInput; ``` -Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662) +Defined in: [packages/ai/src/types.ts:687](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L687) Schema describing the tool's input parameters. @@ -193,10 +193,10 @@ type({ ### lazy? ```ts -optional lazy: boolean; +optional lazy?: boolean; ``` -Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) +Defined in: [packages/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L733) If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). @@ -209,10 +209,10 @@ If true, this tool is lazy and will only be sent to the LLM after being discover ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711) +Defined in: [packages/ai/src/types.ts:736](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L736) Additional metadata for adapters or custom extensions @@ -228,7 +228,7 @@ Additional metadata for adapters or custom extensions name: string; ``` -Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612) +Defined in: [packages/ai/src/types.ts:637](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L637) Unique name of the tool (used by the model to call it). @@ -250,10 +250,10 @@ Must be unique within the tools array. ### needsApproval? ```ts -optional needsApproval: boolean; +optional needsApproval?: boolean; ``` -Defined in: [packages/ai/src/types.ts:705](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L705) +Defined in: [packages/ai/src/types.ts:730](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L730) If true, tool execution requires user approval before running. Works with both server and client tools. @@ -266,10 +266,10 @@ If true, tool execution requires user approval before running. Works with both s ### outputSchema? ```ts -optional outputSchema: SchemaInput; +optional outputSchema?: SchemaInput; ``` -Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683) +Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) Optional schema for validating tool output. diff --git a/docs/reference/interfaces/RealtimeAdapter.md b/docs/reference/interfaces/RealtimeAdapter.md index 1132bfe639..b003d3699c 100644 --- a/docs/reference/interfaces/RealtimeAdapter.md +++ b/docs/reference/interfaces/RealtimeAdapter.md @@ -18,7 +18,7 @@ re-exports this type for backwards compatibility. ## Properties -### connect() +### connect ```ts connect: (token, clientTools?) => Promise; diff --git a/docs/reference/interfaces/RealtimeAudioPart.md b/docs/reference/interfaces/RealtimeAudioPart.md index 1e3af5494d..312d425e3d 100644 --- a/docs/reference/interfaces/RealtimeAudioPart.md +++ b/docs/reference/interfaces/RealtimeAudioPart.md @@ -14,7 +14,7 @@ Audio content part in a realtime message ### audioData? ```ts -optional audioData: ArrayBuffer; +optional audioData?: ArrayBuffer; ``` Defined in: [packages/ai/src/realtime/types.ts:112](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L112) @@ -26,7 +26,7 @@ Raw audio data (optional, if stored) ### durationMs? ```ts -optional durationMs: number; +optional durationMs?: number; ``` Defined in: [packages/ai/src/realtime/types.ts:114](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L114) diff --git a/docs/reference/interfaces/RealtimeConnection.md b/docs/reference/interfaces/RealtimeConnection.md index 05348a5fdd..835b5f56d9 100644 --- a/docs/reference/interfaces/RealtimeConnection.md +++ b/docs/reference/interfaces/RealtimeConnection.md @@ -12,7 +12,7 @@ Handles audio I/O, events, and session management. ## Properties -### disconnect() +### disconnect ```ts disconnect: () => Promise; @@ -28,7 +28,7 @@ Disconnect from the realtime session *** -### getAudioVisualization() +### getAudioVisualization ```ts getAudioVisualization: () => AudioVisualization; @@ -44,7 +44,7 @@ Get audio visualization data *** -### interrupt() +### interrupt ```ts interrupt: () => void; @@ -60,7 +60,7 @@ Interrupt the current response *** -### on() +### on ```ts on: (event, handler) => () => void; @@ -88,17 +88,11 @@ Subscribe to connection events #### Returns -```ts -(): void; -``` - -##### Returns - -`void` +() => `void` *** -### sendImage() +### sendImage ```ts sendImage: (imageData, mimeType) => void; @@ -124,7 +118,7 @@ Send an image to the conversation *** -### sendText() +### sendText ```ts sendText: (text) => void; @@ -146,7 +140,7 @@ Send a text message (fallback for when voice isn't available) *** -### sendToolResult() +### sendToolResult ```ts sendToolResult: (callId, result) => void; @@ -172,7 +166,7 @@ Send a tool execution result back to the provider *** -### startAudioCapture() +### startAudioCapture ```ts startAudioCapture: () => Promise; @@ -188,7 +182,7 @@ Start capturing audio from the microphone *** -### stopAudioCapture() +### stopAudioCapture ```ts stopAudioCapture: () => void; @@ -204,7 +198,7 @@ Stop capturing audio *** -### updateSession() +### updateSession ```ts updateSession: (config) => void; @@ -226,10 +220,10 @@ Update session configuration *** -### updateToken()? +### updateToken? ```ts -optional updateToken: (token) => void; +optional updateToken?: (token) => void; ``` Defined in: [packages/ai/src/realtime/types.ts:366](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L366) diff --git a/docs/reference/interfaces/RealtimeError.md b/docs/reference/interfaces/RealtimeError.md index 9abb5c404a..18b6170783 100644 --- a/docs/reference/interfaces/RealtimeError.md +++ b/docs/reference/interfaces/RealtimeError.md @@ -28,7 +28,7 @@ Defined in: [packages/ai/src/realtime/types.ts:300](https://github.com/TanStack/ ### details? ```ts -optional details: unknown; +optional details?: unknown; ``` Defined in: [packages/ai/src/realtime/types.ts:302](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L302) @@ -38,7 +38,7 @@ Defined in: [packages/ai/src/realtime/types.ts:302](https://github.com/TanStack/ ### provider? ```ts -optional provider: string; +optional provider?: string; ``` Defined in: [packages/ai/src/realtime/types.ts:301](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L301) diff --git a/docs/reference/interfaces/RealtimeEventPayloads.md b/docs/reference/interfaces/RealtimeEventPayloads.md index ad1cb8733a..1974befcb8 100644 --- a/docs/reference/interfaces/RealtimeEventPayloads.md +++ b/docs/reference/interfaces/RealtimeEventPayloads.md @@ -60,7 +60,7 @@ Defined in: [packages/ai/src/realtime/types.ts:271](https://github.com/TanStack/ #### timeLeft? ```ts -optional timeLeft: string; +optional timeLeft?: string; ``` *** @@ -76,7 +76,7 @@ Defined in: [packages/ai/src/realtime/types.ts:269](https://github.com/TanStack/ #### messageId? ```ts -optional messageId: string; +optional messageId?: string; ``` *** diff --git a/docs/reference/interfaces/RealtimeMessage.md b/docs/reference/interfaces/RealtimeMessage.md index 75d0c69bc0..61f7351be4 100644 --- a/docs/reference/interfaces/RealtimeMessage.md +++ b/docs/reference/interfaces/RealtimeMessage.md @@ -14,7 +14,7 @@ A message in a realtime conversation ### audioId? ```ts -optional audioId: string; +optional audioId?: string; ``` Defined in: [packages/ai/src/realtime/types.ts:174](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L174) @@ -26,7 +26,7 @@ Reference to audio buffer if stored ### durationMs? ```ts -optional durationMs: number; +optional durationMs?: number; ``` Defined in: [packages/ai/src/realtime/types.ts:176](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L176) @@ -50,7 +50,7 @@ Unique message identifier ### interrupted? ```ts -optional interrupted: boolean; +optional interrupted?: boolean; ``` Defined in: [packages/ai/src/realtime/types.ts:172](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L172) diff --git a/docs/reference/interfaces/RealtimeSessionConfig.md b/docs/reference/interfaces/RealtimeSessionConfig.md index 4c115f265e..2a6f887519 100644 --- a/docs/reference/interfaces/RealtimeSessionConfig.md +++ b/docs/reference/interfaces/RealtimeSessionConfig.md @@ -14,7 +14,7 @@ Configuration for a realtime session ### instructions? ```ts -optional instructions: string; +optional instructions?: string; ``` Defined in: [packages/ai/src/realtime/types.ts:41](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L41) @@ -26,7 +26,7 @@ System instructions for the assistant ### maxOutputTokens? ```ts -optional maxOutputTokens: number | "inf"; +optional maxOutputTokens?: number | "inf"; ``` Defined in: [packages/ai/src/realtime/types.ts:53](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L53) @@ -38,7 +38,7 @@ Maximum number of tokens in a response ### model? ```ts -optional model: string; +optional model?: string; ``` Defined in: [packages/ai/src/realtime/types.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L37) @@ -50,7 +50,7 @@ Model to use for the session ### outputModalities? ```ts -optional outputModalities: ("text" | "audio")[]; +optional outputModalities?: ("text" | "audio")[]; ``` Defined in: [packages/ai/src/realtime/types.ts:49](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L49) @@ -62,7 +62,7 @@ Output modalities for responses (e.g., ['audio', 'text'], ['text']) ### providerOptions? ```ts -optional providerOptions: Record; +optional providerOptions?: Record; ``` Defined in: [packages/ai/src/realtime/types.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L57) @@ -74,7 +74,7 @@ Provider-specific options ### semanticEagerness? ```ts -optional semanticEagerness: "high" | "low" | "medium"; +optional semanticEagerness?: "low" | "medium" | "high"; ``` Defined in: [packages/ai/src/realtime/types.ts:55](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L55) @@ -86,7 +86,7 @@ Eagerness level for semantic VAD ('low', 'medium', 'high') ### temperature? ```ts -optional temperature: number; +optional temperature?: number; ``` Defined in: [packages/ai/src/realtime/types.ts:51](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L51) @@ -98,7 +98,7 @@ Temperature for generation (provider-specific range, e.g., 0.6-1.2 for OpenAI) ### tools? ```ts -optional tools: RealtimeToolConfig[]; +optional tools?: RealtimeToolConfig[]; ``` Defined in: [packages/ai/src/realtime/types.ts:43](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L43) @@ -110,7 +110,7 @@ Tools available in the session ### vadConfig? ```ts -optional vadConfig: VADConfig; +optional vadConfig?: VADConfig; ``` Defined in: [packages/ai/src/realtime/types.ts:47](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L47) @@ -122,7 +122,7 @@ VAD configuration ### vadMode? ```ts -optional vadMode: "server" | "manual" | "semantic"; +optional vadMode?: "server" | "manual" | "semantic"; ``` Defined in: [packages/ai/src/realtime/types.ts:45](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L45) @@ -134,7 +134,7 @@ VAD mode ### voice? ```ts -optional voice: string; +optional voice?: string; ``` Defined in: [packages/ai/src/realtime/types.ts:39](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L39) diff --git a/docs/reference/interfaces/RealtimeTokenAdapter.md b/docs/reference/interfaces/RealtimeTokenAdapter.md index cbfcc1763c..54dd85813e 100644 --- a/docs/reference/interfaces/RealtimeTokenAdapter.md +++ b/docs/reference/interfaces/RealtimeTokenAdapter.md @@ -11,7 +11,7 @@ Adapter interface for generating provider-specific tokens ## Properties -### generateToken() +### generateToken ```ts generateToken: () => Promise; diff --git a/docs/reference/interfaces/RealtimeToolCallPart.md b/docs/reference/interfaces/RealtimeToolCallPart.md index fdae159530..cd68b1aae5 100644 --- a/docs/reference/interfaces/RealtimeToolCallPart.md +++ b/docs/reference/interfaces/RealtimeToolCallPart.md @@ -34,7 +34,7 @@ Defined in: [packages/ai/src/realtime/types.ts:122](https://github.com/TanStack/ ### input? ```ts -optional input: unknown; +optional input?: unknown; ``` Defined in: [packages/ai/src/realtime/types.ts:125](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L125) @@ -54,7 +54,7 @@ Defined in: [packages/ai/src/realtime/types.ts:123](https://github.com/TanStack/ ### output? ```ts -optional output: unknown; +optional output?: unknown; ``` Defined in: [packages/ai/src/realtime/types.ts:126](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L126) diff --git a/docs/reference/interfaces/RealtimeToolConfig.md b/docs/reference/interfaces/RealtimeToolConfig.md index fa8cc1971e..de48a159b6 100644 --- a/docs/reference/interfaces/RealtimeToolConfig.md +++ b/docs/reference/interfaces/RealtimeToolConfig.md @@ -25,7 +25,7 @@ Defined in: [packages/ai/src/realtime/types.ts:27](https://github.com/TanStack/a ### inputSchema? ```ts -optional inputSchema: Record; +optional inputSchema?: Record; ``` Defined in: [packages/ai/src/realtime/types.ts:28](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L28) @@ -45,7 +45,7 @@ Defined in: [packages/ai/src/realtime/types.ts:26](https://github.com/TanStack/a ### outputSchema? ```ts -optional outputSchema: Record; +optional outputSchema?: Record; ``` Defined in: [packages/ai/src/realtime/types.ts:29](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L29) diff --git a/docs/reference/interfaces/ReasoningEncryptedValueEvent.md b/docs/reference/interfaces/ReasoningEncryptedValueEvent.md index 53a2d6b5bc..70008064dc 100644 --- a/docs/reference/interfaces/ReasoningEncryptedValueEvent.md +++ b/docs/reference/interfaces/ReasoningEncryptedValueEvent.md @@ -5,7 +5,7 @@ title: ReasoningEncryptedValueEvent # Interface: ReasoningEncryptedValueEvent -Defined in: [packages/ai/src/types.ts:1627](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1627) +Defined in: [packages/ai/src/types.ts:1713](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1713) Emitted for encrypted reasoning values. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1629](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1629) +Defined in: [packages/ai/src/types.ts:1715](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1715) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ReasoningEndEvent.md b/docs/reference/interfaces/ReasoningEndEvent.md index 68c9bcc174..c06e6cc38f 100644 --- a/docs/reference/interfaces/ReasoningEndEvent.md +++ b/docs/reference/interfaces/ReasoningEndEvent.md @@ -5,7 +5,7 @@ title: ReasoningEndEvent # Interface: ReasoningEndEvent -Defined in: [packages/ai/src/types.ts:1616](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1616) +Defined in: [packages/ai/src/types.ts:1702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1702) Emitted when reasoning ends for a message. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1618](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1618) +Defined in: [packages/ai/src/types.ts:1704](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1704) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ReasoningMessageContentEvent.md b/docs/reference/interfaces/ReasoningMessageContentEvent.md index 49e290daf1..3e95a4723d 100644 --- a/docs/reference/interfaces/ReasoningMessageContentEvent.md +++ b/docs/reference/interfaces/ReasoningMessageContentEvent.md @@ -5,7 +5,7 @@ title: ReasoningMessageContentEvent # Interface: ReasoningMessageContentEvent -Defined in: [packages/ai/src/types.ts:1594](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1594) +Defined in: [packages/ai/src/types.ts:1680](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1680) Emitted when reasoning message content is generated. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1596](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1596) +Defined in: [packages/ai/src/types.ts:1682](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1682) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ReasoningMessageEndEvent.md b/docs/reference/interfaces/ReasoningMessageEndEvent.md index fd3030b4a0..4647d216b5 100644 --- a/docs/reference/interfaces/ReasoningMessageEndEvent.md +++ b/docs/reference/interfaces/ReasoningMessageEndEvent.md @@ -5,7 +5,7 @@ title: ReasoningMessageEndEvent # Interface: ReasoningMessageEndEvent -Defined in: [packages/ai/src/types.ts:1605](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1605) +Defined in: [packages/ai/src/types.ts:1691](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1691) Emitted when a reasoning message ends. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1607](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1607) +Defined in: [packages/ai/src/types.ts:1693](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1693) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ReasoningMessageStartEvent.md b/docs/reference/interfaces/ReasoningMessageStartEvent.md index 06c64b83a3..5ca5e2b84c 100644 --- a/docs/reference/interfaces/ReasoningMessageStartEvent.md +++ b/docs/reference/interfaces/ReasoningMessageStartEvent.md @@ -5,7 +5,7 @@ title: ReasoningMessageStartEvent # Interface: ReasoningMessageStartEvent -Defined in: [packages/ai/src/types.ts:1583](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1583) +Defined in: [packages/ai/src/types.ts:1669](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1669) Emitted when a reasoning message starts. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1585](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1585) +Defined in: [packages/ai/src/types.ts:1671](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1671) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ReasoningStartEvent.md b/docs/reference/interfaces/ReasoningStartEvent.md index 41a3f3877f..011ec564d0 100644 --- a/docs/reference/interfaces/ReasoningStartEvent.md +++ b/docs/reference/interfaces/ReasoningStartEvent.md @@ -5,7 +5,7 @@ title: ReasoningStartEvent # Interface: ReasoningStartEvent -Defined in: [packages/ai/src/types.ts:1572](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1572) +Defined in: [packages/ai/src/types.ts:1658](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1658) Emitted when reasoning starts for a message. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1574](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1574) +Defined in: [packages/ai/src/types.ts:1660](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1660) Model identifier for multi-model support diff --git a/docs/reference/interfaces/RerankAdapter.md b/docs/reference/interfaces/RerankAdapter.md new file mode 100644 index 0000000000..75bfa6faf0 --- /dev/null +++ b/docs/reference/interfaces/RerankAdapter.md @@ -0,0 +1,107 @@ +--- +id: RerankAdapter +title: RerankAdapter +--- + +# Interface: RerankAdapter\ + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:23](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L23) + +Rerank adapter interface with pre-resolved generics. + +An adapter is created by a provider function: `provider('model')` → `adapter` +All type resolution happens at the provider call site, not in this interface. + +Generic parameters: +- TModel: The specific model name (e.g. 'rerank-v3.5') +- TProviderOptions: Provider-specific options (already resolved) + +## Type Parameters + +### TModel + +`TModel` *extends* `string` = `string` + +### TProviderOptions + +`TProviderOptions` *extends* `object` = `Record`\<`string`, `unknown`\> + +## Properties + +### ~types + +```ts +~types: object; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L37) + +**`Internal`** + +Type-only properties for inference. Not assigned at runtime. + +#### providerOptions + +```ts +providerOptions: TProviderOptions; +``` + +*** + +### kind + +```ts +readonly kind: "rerank"; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:28](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L28) + +Discriminator for adapter kind + +*** + +### model + +```ts +readonly model: TModel; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:32](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L32) + +The model this adapter is configured for + +*** + +### name + +```ts +readonly name: string; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:30](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L30) + +Adapter name identifier + +*** + +### rerank + +```ts +rerank: (options) => Promise; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L46) + +Rerank the given (pre-serialized) documents against the query, returning +scored indices into `options.documents`. The activity layer maps these +back to the caller's original documents. + +#### Parameters + +##### options + +[`RerankOptions`](RerankOptions.md)\<`TProviderOptions`\> + +#### Returns + +`Promise`\<[`RerankAdapterResult`](RerankAdapterResult.md)\> diff --git a/docs/reference/interfaces/RerankAdapterResult.md b/docs/reference/interfaces/RerankAdapterResult.md new file mode 100644 index 0000000000..35bda083b9 --- /dev/null +++ b/docs/reference/interfaces/RerankAdapterResult.md @@ -0,0 +1,56 @@ +--- +id: RerankAdapterResult +title: RerankAdapterResult +--- + +# Interface: RerankAdapterResult + +Defined in: [packages/ai/src/types.ts:2052](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2052) + +Provider-level rerank result. Adapters return scored indices into the +(serialized) `documents` array plus usage — never the documents themselves. +The activity attaches the original documents. + +## Properties + +### id + +```ts +id: string; +``` + +Defined in: [packages/ai/src/types.ts:2053](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2053) + +*** + +### ranking + +```ts +ranking: object[]; +``` + +Defined in: [packages/ai/src/types.ts:2055](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2055) + +Scored results, highest relevance first, as indices into `documents`. + +#### index + +```ts +index: number; +``` + +#### score + +```ts +score: number; +``` + +*** + +### usage + +```ts +usage: TokenUsage; +``` + +Defined in: [packages/ai/src/types.ts:2056](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2056) diff --git a/docs/reference/interfaces/RerankOptions.md b/docs/reference/interfaces/RerankOptions.md new file mode 100644 index 0000000000..88dc5e49b1 --- /dev/null +++ b/docs/reference/interfaces/RerankOptions.md @@ -0,0 +1,103 @@ +--- +id: RerankOptions +title: RerankOptions +--- + +# Interface: RerankOptions\ + +Defined in: [packages/ai/src/types.ts:2025](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2025) + +Options passed to a [RerankAdapter](RerankAdapter.md). Documents reach the adapter +already serialized to strings — the `rerank()` activity stringifies object +documents and maps results back to the original elements, so adapters never +deal with the caller's document type. + +## Type Parameters + +### TProviderOptions + +`TProviderOptions` *extends* `object` = `Record`\<`string`, `unknown`\> + +## Properties + +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2038](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2038) + +Forwarded to the provider request for cancellation. + +*** + +### documents + +```ts +documents: string[]; +``` + +Defined in: [packages/ai/src/types.ts:2032](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2032) + +Documents to rerank, pre-serialized to strings by the activity. + +*** + +### logger + +```ts +logger: InternalLogger; +``` + +Defined in: [packages/ai/src/types.ts:2044](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2044) + +Internal logger threaded from the rerank() entry point. Adapters must call +logger.request() before the provider call and logger.errors() in catch +blocks. + +*** + +### model + +```ts +model: string; +``` + +Defined in: [packages/ai/src/types.ts:2028](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2028) + +*** + +### modelOptions? + +```ts +optional modelOptions?: TProviderOptions; +``` + +Defined in: [packages/ai/src/types.ts:2036](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2036) + +Provider-specific options forwarded by the rerank() activity. + +*** + +### query + +```ts +query: string; +``` + +Defined in: [packages/ai/src/types.ts:2030](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2030) + +The search query documents are scored against. + +*** + +### topN? + +```ts +optional topN?: number; +``` + +Defined in: [packages/ai/src/types.ts:2034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2034) + +Return only the top N results. Passed through to the provider. diff --git a/docs/reference/interfaces/RerankResult.md b/docs/reference/interfaces/RerankResult.md new file mode 100644 index 0000000000..2ff25898d9 --- /dev/null +++ b/docs/reference/interfaces/RerankResult.md @@ -0,0 +1,95 @@ +--- +id: RerankResult +title: RerankResult +--- + +# Interface: RerankResult\ + +Defined in: [packages/ai/src/types.ts:2064](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2064) + +Public result of the `rerank()` activity, generic over the caller's document +element type so `document` / `rerankedDocuments` carry the original values +(strings or objects), not their serialized form. + +## Type Parameters + +### TDocument + +`TDocument` = `string` + +## Properties + +### id + +```ts +id: string; +``` + +Defined in: [packages/ai/src/types.ts:2065](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2065) + +*** + +### model + +```ts +model: string; +``` + +Defined in: [packages/ai/src/types.ts:2066](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2066) + +*** + +### ranking + +```ts +ranking: object[]; +``` + +Defined in: [packages/ai/src/types.ts:2068](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2068) + +Scored results, highest relevance first. + +#### document + +```ts +document: TDocument; +``` + +#### index + +```ts +index: number; +``` + +#### score + +```ts +score: number; +``` + +*** + +### rerankedDocuments + +```ts +rerankedDocuments: TDocument[]; +``` + +Defined in: [packages/ai/src/types.ts:2070](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2070) + +The documents reordered by relevance — `ranking.map(r => r.document)`. + +*** + +### usage + +```ts +usage: TokenUsage; +``` + +Defined in: [packages/ai/src/types.ts:2077](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2077) + +Usage for the request. Rerank typically bills in provider-defined "search +units" (`usage.unitsBilled`) rather than tokens. Some providers (e.g. +OpenRouter) may also report `totalTokens` and `cost`; Cohere reports only +search units and leaves the token counts at 0. diff --git a/docs/reference/interfaces/ResolvedEmbeddingItem.md b/docs/reference/interfaces/ResolvedEmbeddingItem.md new file mode 100644 index 0000000000..eb98cd846e --- /dev/null +++ b/docs/reference/interfaces/ResolvedEmbeddingItem.md @@ -0,0 +1,36 @@ +--- +id: ResolvedEmbeddingItem +title: ResolvedEmbeddingItem +--- + +# Interface: ResolvedEmbeddingItem + +Defined in: [packages/ai/src/utilities/embedding-input.ts:8](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/embedding-input.ts#L8) + +One embedding input item resolved into its text and image constituents. +Produced by [resolveEmbeddingInput](../functions/resolveEmbeddingInput.md); adapters map each entry onto +one provider-native input (one vector per entry). + +## Properties + +### images + +```ts +images: ImagePart[]; +``` + +Defined in: [packages/ai/src/utilities/embedding-input.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/embedding-input.ts#L12) + +Image parts of the item, in order (empty for text-only items) + +*** + +### texts + +```ts +texts: string[]; +``` + +Defined in: [packages/ai/src/utilities/embedding-input.ts:10](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/embedding-input.ts#L10) + +Text contents of the item, in order (empty for image-only items) diff --git a/docs/reference/interfaces/ResponseFormat.md b/docs/reference/interfaces/ResponseFormat.md index 0595dcd2bc..1a1094cecb 100644 --- a/docs/reference/interfaces/ResponseFormat.md +++ b/docs/reference/interfaces/ResponseFormat.md @@ -5,7 +5,7 @@ title: ResponseFormat # Interface: ResponseFormat\ -Defined in: [packages/ai/src/types.ts:749](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L749) +Defined in: [packages/ai/src/types.ts:774](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L774) Structured output format specification. @@ -30,10 +30,10 @@ TypeScript type of the expected data structure (for type safety) ### \_\_data? ```ts -optional __data: TData; +optional __data?: TData; ``` -Defined in: [packages/ai/src/types.ts:827](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L827) +Defined in: [packages/ai/src/types.ts:852](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L852) **`Internal`** @@ -47,10 +47,10 @@ Allows the SDK to know what type to expect when parsing the response. ### json\_schema? ```ts -optional json_schema: object; +optional json_schema?: object; ``` -Defined in: [packages/ai/src/types.ts:766](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L766) +Defined in: [packages/ai/src/types.ts:791](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L791) JSON schema specification (required when type is "json_schema"). @@ -60,7 +60,7 @@ OpenAI's structured outputs will guarantee the output matches this schema. #### description? ```ts -optional description: string; +optional description?: string; ``` Optional description of what the schema represents. @@ -117,7 +117,7 @@ https://json-schema.org/ #### strict? ```ts -optional strict: boolean; +optional strict?: boolean; ``` Whether to enforce strict schema validation. @@ -139,7 +139,7 @@ https://platform.openai.com/docs/guides/structured-outputs#strict-mode type: "json_object" | "json_schema"; ``` -Defined in: [packages/ai/src/types.ts:758](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L758) +Defined in: [packages/ai/src/types.ts:783](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L783) Type of structured output. diff --git a/docs/reference/interfaces/RunDriverOptions.md b/docs/reference/interfaces/RunDriverOptions.md new file mode 100644 index 0000000000..3bd512be2a --- /dev/null +++ b/docs/reference/interfaces/RunDriverOptions.md @@ -0,0 +1,195 @@ +--- +id: RunDriverOptions +title: RunDriverOptions +--- + +# Interface: RunDriverOptions + +Defined in: [packages/ai/src/stream-to-response.ts:794](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L794) + +Everything the resume helpers need to take a run over as a side effect of +serving its log. + +`claim` and `pipe` are **injected**, not imported. The two mechanisms a +takeover needs (`withRunClaim` and `pipeToRunLog`) live in +`@tanstack/ai-sandbox`, and `@tanstack/ai` must not depend on that package — +that layering inversion is exactly what moving `LockStore` into core was meant +to prevent, and it would make core depend on the sandbox package to serve a +plain chat run. Injecting them keeps only the *shape* of a takeover in core +(parse the run id, read the record, skip if terminal, claim, drive) and lets a +background-worker-driven run supply its own pair. +`@tanstack/ai-sandbox`'s `sandboxRunDriver` fills both in. + +## Properties + +### claim + +```ts +claim: (input, fn) => Promise; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:806](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L806) + +Run `fn` under exclusive ownership of the run, or reject if refused. + +#### Type Parameters + +##### T + +`T` + +#### Parameters + +##### input + +###### locks + +`LockStore` + +###### runId + +`string` + +###### runs + +[`RunStore`](RunStore.md) + +##### fn + +(`claim`) => `Promise`\<`T`\> + +#### Returns + +`Promise`\<`T`\> + +*** + +### drive + +```ts +drive: (input) => AsyncIterable; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:800](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L800) + +Produce the run's remaining events. Called only once the claim is held. + +#### Parameters + +##### input + +###### runId + +`string` + +###### signal + +`AbortSignal` + +###### threadId + +`string` + +#### Returns + +`AsyncIterable`\<[`AGUIEvent`](../type-aliases/AGUIEvent.md)\> + +*** + +### locks + +```ts +locks: LockStore; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:798](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L798) + +*** + +### logger? + +```ts +optional logger?: InternalLogger; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:821](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L821) + +*** + +### pipe + +```ts +pipe: (stream, input) => Promise; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:815](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L815) + +Persist the driven stream to the run's producer-side durability log. + +#### Parameters + +##### stream + +`AsyncIterable`\<[`AGUIEvent`](../type-aliases/AGUIEvent.md)\> + +##### input + +###### runId + +`string` + +###### signal + +`AbortSignal` + +###### threadId + +`string` + +#### Returns + +`Promise`\<`unknown`\> + +*** + +### request + +```ts +request: Request; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:796](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L796) + +The attach request; its run id is read with [resolveResumeRunId](../functions/resolveResumeRunId.md). + +*** + +### runs + +```ts +runs: RunStore; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:797](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L797) + +*** + +### waitUntil? + +```ts +optional waitUntil?: (promise) => void; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:820](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L820) + +Platform keep-alive (e.g. `ctx.waitUntil`) for the background drive. + +#### Parameters + +##### promise + +`Promise`\<`unknown`\> + +#### Returns + +`void` diff --git a/docs/reference/interfaces/RunError.md b/docs/reference/interfaces/RunError.md new file mode 100644 index 0000000000..2015f35fa2 --- /dev/null +++ b/docs/reference/interfaces/RunError.md @@ -0,0 +1,36 @@ +--- +id: RunError +title: RunError +--- + +# Interface: RunError + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L99) + +Why a run failed. + +A bare message is an LLM provider's prose: it changes between model +versions and cannot be branched on. `code` is what a consumer switches over +to decide whether to retry, escalate, or surface a specific UI. + +## Properties + +### code? + +```ts +optional code?: string; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:102](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L102) + +Stable, machine-branchable classification, when the provider supplies one. + +*** + +### message + +```ts +message: string; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:100](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L100) diff --git a/docs/reference/interfaces/RunErrorEvent.md b/docs/reference/interfaces/RunErrorEvent.md index 959728af2f..1c24707bbd 100644 --- a/docs/reference/interfaces/RunErrorEvent.md +++ b/docs/reference/interfaces/RunErrorEvent.md @@ -5,7 +5,7 @@ title: RunErrorEvent # Interface: RunErrorEvent -Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124) +Defined in: [packages/ai/src/types.ts:1147](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1147) Emitted when an error occurs during a run. @@ -27,15 +27,15 @@ TanStack AI adds: `model?`, `error?` (deprecated nested form) ### ~~error?~~ ```ts -optional error: object; +optional error?: object; ``` -Defined in: [packages/ai/src/types.ts:1131](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1131) +Defined in: [packages/ai/src/types.ts:1156](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1156) #### ~~code?~~ ```ts -optional code: string; +optional code?: string; ``` #### ~~message~~ @@ -54,9 +54,21 @@ Kept for backward compatibility. ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1126) +Defined in: [packages/ai/src/types.ts:1149](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1149) Model identifier for multi-model support + +*** + +### tanstack:interruptErrors? + +```ts +optional tanstack:interruptErrors?: readonly InterruptSubmissionError[]; +``` + +Defined in: [packages/ai/src/types.ts:1151](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1151) + +Exhaustive TanStack interrupt submission failures for this run. diff --git a/docs/reference/interfaces/RunFinishedEvent.md b/docs/reference/interfaces/RunFinishedEvent.md index 5b5062ce52..3cfc249fb4 100644 --- a/docs/reference/interfaces/RunFinishedEvent.md +++ b/docs/reference/interfaces/RunFinishedEvent.md @@ -5,7 +5,7 @@ title: RunFinishedEvent # Interface: RunFinishedEvent -Defined in: [packages/ai/src/types.ts:1109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1109) +Defined in: [packages/ai/src/types.ts:1132](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1132) Emitted when a run completes successfully. @@ -27,10 +27,10 @@ TanStack AI adds: `model?`, `finishReason?`, `usage?` ### finishReason? ```ts -optional finishReason: "length" | "stop" | "content_filter" | "tool_calls" | null; +optional finishReason?: "length" | "stop" | "content_filter" | "tool_calls" | null; ``` -Defined in: [packages/ai/src/types.ts:1113](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1113) +Defined in: [packages/ai/src/types.ts:1136](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1136) Why the generation stopped @@ -39,10 +39,10 @@ Why the generation stopped ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1111](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1111) +Defined in: [packages/ai/src/types.ts:1134](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1134) Model identifier for multi-model support @@ -51,9 +51,9 @@ Model identifier for multi-model support ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:1115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1115) +Defined in: [packages/ai/src/types.ts:1138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1138) Token usage statistics with optional detailed breakdowns and provider-reported cost. diff --git a/docs/reference/interfaces/RunRecord.md b/docs/reference/interfaces/RunRecord.md new file mode 100644 index 0000000000..7a0823cf3a --- /dev/null +++ b/docs/reference/interfaces/RunRecord.md @@ -0,0 +1,159 @@ +--- +id: RunRecord +title: RunRecord +--- + +# Interface: RunRecord + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:106](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L106) + +Durable bookkeeping for a single run. + +## Properties + +### cancelRequested? + +```ts +optional cancelRequested?: boolean; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L151) + +Set by an explicit out-of-band cancel, to be distinguished from a mere +client disconnect (the two produce an identical TCP close, so intent is not +inferable from the disconnect). + +Written by `requestRunCancel` and read by `wasCancelRequested` (both in +`../cancel`). Deliberately NOT a status: recording intent is not the same as +the run having stopped, and only the driver knows when it has. + +*** + +### detachedSince? + +```ts +optional detachedSince?: number; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:141](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L141) + +Epoch ms when the last viewer detached; absent while someone is attached. +Written by `withSandbox`'s detach path (`onAbort` in `@tanstack/ai-sandbox`'s +`middleware.ts`) alongside `sandboxKey`, when a disconnect leaves the +agent running rather than tearing the sandbox down. A backend must +round-trip this field: `listReclaimable` depends on it, and +`@tanstack/ai-sandbox`'s `reapDetachedRuns` sweeps the candidates it +surfaces (see that method's doc comment). + +*** + +### driverEpoch? + +```ts +optional driverEpoch?: number; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L161) + +Monotonic fencing token for the run's driver. Bumped by each host that +successfully claims the run (see `withRunClaim` in `@tanstack/ai-sandbox`), +so a superseded host can discover it lost by comparing the stored value +against the one it holds. + +A lock alone cannot provide this: it tells the winner it won, but gives a +loser nothing to read. Absent on a run that was never claimed. + +*** + +### error? + +```ts +optional error?: RunError; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:120](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L120) + +*** + +### finishedAt? + +```ts +optional finishedAt?: number; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L119) + +*** + +### runId + +```ts +runId: string; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L107) + +*** + +### sandboxKey? + +```ts +optional sandboxKey?: string; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:131](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L131) + +Compound sandbox key this run was bound to, when it ran in a sandbox. +Recorded so a future reclaimer can identify the sandbox to tear down +without re-deriving the key. Written by `withSandbox`'s detach path +(`onAbort` in `@tanstack/ai-sandbox`'s `middleware.ts`) at the same time as +`detachedSince`, when a disconnect leaves the run detached rather than +destroying the sandbox. A backend must round-trip this field — see +`listReclaimable` below for who eventually reads it. + +*** + +### startedAt + +```ts +startedAt: number; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:118](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L118) + +*** + +### status + +```ts +status: RunStatus; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:117](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L117) + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:116](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L116) + +Conversation this run belongs to — the `Scope.threadId`. + +Generation jobs (a one-shot `generate()` with no conversation) must not +reuse this record by faking `threadId = requestId`; they need a separate +job store. `withGenerationPersistence` currently does exactly that and +labels itself a stopgap — do not copy it. + +*** + +### usage? + +```ts +optional usage?: TokenUsage; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:121](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L121) diff --git a/docs/reference/interfaces/RunStartedEvent.md b/docs/reference/interfaces/RunStartedEvent.md index 6ef8deb51f..6ddf14a455 100644 --- a/docs/reference/interfaces/RunStartedEvent.md +++ b/docs/reference/interfaces/RunStartedEvent.md @@ -5,7 +5,7 @@ title: RunStartedEvent # Interface: RunStartedEvent -Defined in: [packages/ai/src/types.ts:1081](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1081) +Defined in: [packages/ai/src/types.ts:1098](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1098) Emitted when a run starts. This is the first event in any streaming response. @@ -28,9 +28,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1083](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1083) +Defined in: [packages/ai/src/types.ts:1100](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1100) Model identifier for multi-model support diff --git a/docs/reference/interfaces/RunStore.md b/docs/reference/interfaces/RunStore.md new file mode 100644 index 0000000000..1ab132abed --- /dev/null +++ b/docs/reference/interfaces/RunStore.md @@ -0,0 +1,204 @@ +--- +id: RunStore +title: RunStore +--- + +# Interface: RunStore + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:179](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L179) + +Durable store for run lifecycle records. + +REQUIRED: `createOrResume`, `update`, `get`, `findActiveRun`. Every backend +must implement all four — they are what the persistence middleware calls +unconditionally. `findActiveRun` is required rather than feature-detected +because a backend that has not implemented it is indistinguishable from one +whose answer is legitimately `null`, so reconnect would silently do nothing +instead of failing at build time. It was optional for exactly one release +cycle and cost precisely that. + +OPTIONAL: `listByThread`, `listReclaimable`. Each serves one higher-level +feature (thread history, reclaim reaping) and callers feature-detect them, +degrading gracefully when a backend omits them. + +## Properties + +### createOrResume + +```ts +createOrResume: (input) => Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:188](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L188) + +Create a run record, or return the existing one unchanged if `runId` is +already present. + +INVARIANT (idempotency): an existing record is returned **unchanged** and +the passed `threadId`/`startedAt`/`status` are ignored. This is what makes +resuming a run safe. `status` defaults to `'running'` on first creation. + +#### Parameters + +##### input + +`Pick`\<[`RunRecord`](RunRecord.md), `"threadId"` \| `"runId"` \| `"startedAt"`\> & `object` + +#### Returns + +`Promise`\<[`RunRecord`](RunRecord.md)\> + +*** + +### findActiveRun + +```ts +findActiveRun: (threadId) => Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:255](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L255) + +The most recent `'running'` run for `threadId`, or `null` if none is active. + +REQUIRED. This resolves "does this thread have a live run to attach to?" +from the STABLE thread id, which is the durable basis for reconnecting a +client (a reload, or the same thread opened on another device) — independent +of the ephemeral run id, which a single turn may mint several of. When more +than one run is `'running'`, the one with the greatest `startedAt` wins. + +A backend that stubs this to `null` turns reconnect off silently, because +`null` is also the correct answer for an idle thread. A backend with no run +lifecycle at all should omit the whole `runs` store instead — capability +tiers belong at the store level, not the method level. + +#### Parameters + +##### threadId + +`string` + +#### Returns + +`Promise`\<[`RunRecord`](RunRecord.md) \| `null`\> + +*** + +### get + +```ts +get: (runId) => Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:216](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L216) + +Current record, or null when unknown. + +#### Parameters + +##### runId + +`string` + +#### Returns + +`Promise`\<[`RunRecord`](RunRecord.md) \| `null`\> + +*** + +### listByThread? + +```ts +optional listByThread?: (threadId) => Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:221](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L221) + +Every run in a conversation, ascending by `startedAt`. OPTIONAL: only +needed to render a thread's past agent activity. Consumers feature-detect. + +#### Parameters + +##### threadId + +`string` + +#### Returns + +`Promise`\<[`RunRecord`](RunRecord.md)[]\> + +*** + +### listReclaimable? + +```ts +optional listReclaimable?: (opts) => Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:237](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L237) + +Runs that may be reclaimed: ALL THREE of `status === 'running'`, +`detachedSince` is set, and `detachedSince <= now - ttlMs`. The cutoff is +**inclusive** — a run detached at exactly `now - ttlMs` IS reclaimable. + +OPTIONAL: only needed by a reaper. Consumers feature-detect. + +`detachedSince` is populated by `withSandbox`'s detach path (see +[RunRecord.detachedSince](RunRecord.md#detachedsince)). The sweep over the candidates this +surfaces is `@tanstack/ai-sandbox`'s `reapDetachedRuns`: it finalizes a run +whose agent already finished, expires one past its TTL, and reclaims the +sandbox. That is a function, not a scheduler — the application invokes it +(cron, queue, `alarm()`, `waitUntil`) — and a backend that omits this +method cannot be reaped at all. + +#### Parameters + +##### opts + +###### now + +`number` + +###### ttlMs + +`number` + +#### Returns + +`Promise`\<[`RunRecord`](RunRecord.md)[]\> + +*** + +### update + +```ts +update: (runId, patch) => Promise; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:199](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L199) + +Patch a record's mutable fields. + +INVARIANT: updating an unknown `runId` is a **no-op** — it must not throw +and must not create a record. + +#### Parameters + +##### runId + +`string` + +##### patch + +`Partial`\<`Pick`\<[`RunRecord`](RunRecord.md), + \| `"status"` + \| `"finishedAt"` + \| `"error"` + \| `"usage"` + \| `"sandboxKey"` + \| `"detachedSince"` + \| `"cancelRequested"` + \| `"driverEpoch"`\>\> + +#### Returns + +`Promise`\<`void`\> diff --git a/docs/reference/interfaces/SandboxFileCustomEvent.md b/docs/reference/interfaces/SandboxFileCustomEvent.md index ee4067b55b..9d16107046 100644 --- a/docs/reference/interfaces/SandboxFileCustomEvent.md +++ b/docs/reference/interfaces/SandboxFileCustomEvent.md @@ -5,32 +5,30 @@ title: SandboxFileCustomEvent # Interface: SandboxFileCustomEvent -Defined in: [packages/ai/src/types.ts:1426](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1426) +Defined in: [packages/ai/src/types.ts:1510](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1510) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "sandbox.file"; ``` -Defined in: [packages/ai/src/types.ts:1427](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1427) +Defined in: [packages/ai/src/types.ts:1511](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1511) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1428](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1428) +Defined in: [packages/ai/src/types.ts:1512](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1512) #### path diff --git a/docs/reference/interfaces/SandboxFileDiffEvent.md b/docs/reference/interfaces/SandboxFileDiffEvent.md index d21da74e99..533f491692 100644 --- a/docs/reference/interfaces/SandboxFileDiffEvent.md +++ b/docs/reference/interfaces/SandboxFileDiffEvent.md @@ -5,32 +5,30 @@ title: SandboxFileDiffEvent # Interface: SandboxFileDiffEvent -Defined in: [packages/ai/src/types.ts:1434](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1434) +Defined in: [packages/ai/src/types.ts:1518](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1518) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "sandbox.file.diff"; ``` -Defined in: [packages/ai/src/types.ts:1435](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1435) +Defined in: [packages/ai/src/types.ts:1519](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1519) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1436](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1436) +Defined in: [packages/ai/src/types.ts:1520](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1520) #### diff diff --git a/docs/reference/interfaces/SandboxFileEvent.md b/docs/reference/interfaces/SandboxFileEvent.md index 063b231b5e..b1edfb64f9 100644 --- a/docs/reference/interfaces/SandboxFileEvent.md +++ b/docs/reference/interfaces/SandboxFileEvent.md @@ -5,7 +5,7 @@ title: SandboxFileEvent # Interface: SandboxFileEvent -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:17](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L17) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:20](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L20) A file change observed inside a sandbox during a chat run. @@ -21,7 +21,7 @@ A file change observed inside a sandbox during a chat run. path: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:20](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L20) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:23](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L23) Absolute path inside the sandbox (under the workspace root). @@ -33,7 +33,7 @@ Absolute path inside the sandbox (under the workspace root). timestamp: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:21](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L21) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:24](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L24) *** @@ -43,4 +43,4 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:21](https://git type: "create" | "change" | "delete"; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:18](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L18) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:21](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L21) diff --git a/docs/reference/interfaces/SandboxFileHookEvent.md b/docs/reference/interfaces/SandboxFileHookEvent.md index 16ee5eaa09..e58b8174bd 100644 --- a/docs/reference/interfaces/SandboxFileHookEvent.md +++ b/docs/reference/interfaces/SandboxFileHookEvent.md @@ -5,7 +5,7 @@ title: SandboxFileHookEvent # Interface: SandboxFileHookEvent -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:28](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L28) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:31](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L31) The file event a sandbox hook receives: the serializable [SandboxFileEvent](SandboxFileEvent.md) plus lazy, git-backed content accessors. Accessors compute on call, so a hook @@ -18,13 +18,13 @@ The file event a sandbox hook receives: the serializable [SandboxFileEvent](Sand ## Properties -### after() +### after ```ts after: () => Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:32](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L32) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:35](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L35) Current content (`''` when the event is a delete). @@ -34,13 +34,13 @@ Current content (`''` when the event is a delete). *** -### before() +### before ```ts before: () => Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:30](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L30) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:33](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L33) Content at the session baseline (`''` for a new file or non-git workspace). @@ -50,13 +50,13 @@ Content at the session baseline (`''` for a new file or non-git workspace). *** -### diff() +### diff ```ts diff: () => Promise; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:34](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L34) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L37) Unified patch vs the session baseline (synthesized add-patch when non-git). @@ -72,7 +72,7 @@ Unified patch vs the session baseline (synthesized add-patch when non-git). path: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:20](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L20) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:23](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L23) Absolute path inside the sandbox (under the workspace root). @@ -88,7 +88,7 @@ Absolute path inside the sandbox (under the workspace root). timestamp: number; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:21](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L21) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:24](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L24) #### Inherited from @@ -102,7 +102,7 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:21](https://git type: "create" | "change" | "delete"; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:18](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L18) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:21](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L21) #### Inherited from diff --git a/docs/reference/interfaces/SandboxLifecyclePayload.md b/docs/reference/interfaces/SandboxLifecyclePayload.md new file mode 100644 index 0000000000..f8bb771b1d --- /dev/null +++ b/docs/reference/interfaces/SandboxLifecyclePayload.md @@ -0,0 +1,28 @@ +--- +id: SandboxLifecyclePayload +title: SandboxLifecyclePayload +--- + +# Interface: SandboxLifecyclePayload + +Defined in: [packages/ai/src/custom-events.ts:76](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L76) + +## Properties + +### provider + +```ts +provider: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:78](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L78) + +*** + +### sandboxId + +```ts +sandboxId: string; +``` + +Defined in: [packages/ai/src/custom-events.ts:77](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L77) diff --git a/docs/reference/interfaces/Scope.md b/docs/reference/interfaces/Scope.md new file mode 100644 index 0000000000..fec914cac2 --- /dev/null +++ b/docs/reference/interfaces/Scope.md @@ -0,0 +1,84 @@ +--- +id: Scope +title: Scope +--- + +# Interface: Scope + +Defined in: [packages/ai/src/scope.ts:23](https://github.com/TanStack/ai/blob/main/packages/ai/src/scope.ts#L23) + +Shared identity/isolation scope for the TanStack AI subsystems that persist +or recall per-conversation data — `@tanstack/ai-persistence` (keyed CRUD over +threads, runs, interrupts) and `@tanstack/ai-memory` (ranked recall/save). + +Both subsystems answer the same underlying question — "whose data is this?" — +so they share ONE identity vocabulary defined here rather than each inventing +its own. `threadId` is the single conversation key across the codebase (it is +`ChatMiddlewareContext.threadId`, and `conversationId` is deprecated in favor +of it); a subsystem must never introduce a second name (`sessionId`, +`conversationId`, …) for the same concept. + +## Security + +A `Scope` is an isolation boundary. Derive every field server-side from +trusted, validated session state — **never** from client input. `threadId` +in particular resolves from a client-supplied value on the request, so a +subsystem that reads/writes user-owned data (memory, per-user metadata) must +pair it with a server-trusted `userId`/`tenantId` and must not treat a bare +client `threadId` as sufficient isolation: thread ids are guessable, so on +their own they let one caller read another's data. + +## Properties + +### namespace? + +```ts +optional namespace?: string; +``` + +Defined in: [packages/ai/src/scope.ts:46](https://github.com/TanStack/ai/blob/main/packages/ai/src/scope.ts#L46) + +Logical partition within a tenant/user (e.g. separating distinct memory +banks or persistence namespaces). Reserved — no subsystem keys on it yet; +adapters that don't understand it must ignore it rather than error. + +*** + +### tenantId? + +```ts +optional tenantId?: string; +``` + +Defined in: [packages/ai/src/scope.ts:40](https://github.com/TanStack/ai/blob/main/packages/ai/src/scope.ts#L40) + +Tenant/organization boundary for multi-tenant deployments. When present, +every read and write must be confined to it. + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/scope.ts:29](https://github.com/TanStack/ai/blob/main/packages/ai/src/scope.ts#L29) + +The conversation this data belongs to. Required — the minimal isolation +key both subsystems already center on. Same concept as +`ChatMiddlewareContext.threadId`. + +*** + +### userId? + +```ts +optional userId?: string; +``` + +Defined in: [packages/ai/src/scope.ts:35](https://github.com/TanStack/ai/blob/main/packages/ai/src/scope.ts#L35) + +Durable end-user identity, for cross-thread recall and per-user isolation. +Optional, but required in practice for any multi-user deployment — a +`threadId` alone is not an authorization boundary (see Security above). diff --git a/docs/reference/interfaces/ServerTool.md b/docs/reference/interfaces/ServerTool.md index 01dec5dca6..b605e6aee8 100644 --- a/docs/reference/interfaces/ServerTool.md +++ b/docs/reference/interfaces/ServerTool.md @@ -3,25 +3,25 @@ id: ServerTool title: ServerTool --- -# Interface: ServerTool\ +# Interface: ServerTool\ -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L12) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:86](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L86) Marker type for server-side tools ## Extends -- [`Tool`](Tool.md)\<`TInput`, `TOutput`, `TName`, `TContext`\> +- [`Tool`](Tool.md)\<`TInput`, `TOutput`, `TName`, `TContext`\>.`ToolApprovalCapabilityMarker`\<`TNeedsApproval`, `TApprovalSchema`\> ## Type Parameters ### TInput -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TOutput -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TName @@ -31,6 +31,16 @@ Marker type for server-side tools `TContext` = `unknown` +### TNeedsApproval + +`TNeedsApproval` *extends* `boolean` = `false` + +### TApprovalSchema + +`TApprovalSchema` *extends* + \| [`ApprovalSchemaConfig`](../type-aliases/ApprovalSchemaConfig.md) + \| `undefined` = `undefined` + ## Properties ### \_\_toolSide @@ -39,7 +49,45 @@ Marker type for server-side tools __toolSide: "server"; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:18](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L18) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:97](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L97) + +*** + +### \[toolApprovalCapability\]? + +```ts +readonly optional [toolApprovalCapability]?: object; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:26](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L26) + +#### approvalSchema + +```ts +approvalSchema: TApprovalSchema; +``` + +#### needsApproval + +```ts +needsApproval: TNeedsApproval; +``` + +#### Inherited from + +```ts +ToolApprovalCapabilityMarker.[toolApprovalCapability] +``` + +*** + +### approvalSchema? + +```ts +optional approvalSchema?: TApprovalSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:101](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L101) *** @@ -49,7 +97,7 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:18](https: description: string; ``` -Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622) +Defined in: [packages/ai/src/types.ts:647](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L647) Clear description of what the tool does. @@ -71,10 +119,10 @@ Be specific about what the tool does, what parameters it needs, and what it retu ### execute? ```ts -optional execute: ToolExecuteFunction; +optional execute?: ToolExecuteFunction; ``` -Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702) +Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727) Optional function to execute when the model calls this tool. @@ -85,6 +133,8 @@ Can return any value - will be automatically stringified if needed. #### Param +**args** + The arguments parsed from the model's tool call (validated against inputSchema) #### Returns @@ -109,10 +159,10 @@ execute: async (args) => { ### inputSchema? ```ts -optional inputSchema: TInput; +optional inputSchema?: TInput; ``` -Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:98](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L98) Schema describing the tool's input parameters. @@ -158,7 +208,7 @@ type({ } ``` -#### Inherited from +#### Overrides [`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema) @@ -167,10 +217,10 @@ type({ ### lazy? ```ts -optional lazy: boolean; +optional lazy?: boolean; ``` -Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) +Defined in: [packages/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L733) If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). @@ -183,10 +233,10 @@ If true, this tool is lazy and will only be sent to the LLM after being discover ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711) +Defined in: [packages/ai/src/types.ts:736](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L736) Additional metadata for adapters or custom extensions @@ -202,7 +252,7 @@ Additional metadata for adapters or custom extensions name: TName; ``` -Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612) +Defined in: [packages/ai/src/types.ts:637](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L637) Unique name of the tool (used by the model to call it). @@ -224,14 +274,14 @@ Must be unique within the tools array. ### needsApproval? ```ts -optional needsApproval: boolean; +optional needsApproval?: TNeedsApproval; ``` -Defined in: [packages/ai/src/types.ts:705](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L705) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:100](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L100) If true, tool execution requires user approval before running. Works with both server and client tools. -#### Inherited from +#### Overrides [`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval) @@ -240,10 +290,10 @@ If true, tool execution requires user approval before running. Works with both s ### outputSchema? ```ts -optional outputSchema: TOutput; +optional outputSchema?: TOutput; ``` -Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L99) Optional schema for validating tool output. @@ -266,6 +316,6 @@ z.object({ }) ``` -#### Inherited from +#### Overrides [`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema) diff --git a/docs/reference/interfaces/SessionIdEvent.md b/docs/reference/interfaces/SessionIdEvent.md index 6440dcc265..d81b1bf95a 100644 --- a/docs/reference/interfaces/SessionIdEvent.md +++ b/docs/reference/interfaces/SessionIdEvent.md @@ -5,32 +5,30 @@ title: SessionIdEvent # Interface: SessionIdEvent -Defined in: [packages/ai/src/types.ts:1444](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1444) +Defined in: [packages/ai/src/types.ts:1528](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1528) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: `${string}.session-id`; ``` -Defined in: [packages/ai/src/types.ts:1445](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1445) +Defined in: [packages/ai/src/types.ts:1529](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1529) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1446](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1446) +Defined in: [packages/ai/src/types.ts:1530](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1530) #### sessionId diff --git a/docs/reference/interfaces/SkillRegisteredEvent.md b/docs/reference/interfaces/SkillRegisteredEvent.md index c59fbd36a3..26227f49af 100644 --- a/docs/reference/interfaces/SkillRegisteredEvent.md +++ b/docs/reference/interfaces/SkillRegisteredEvent.md @@ -5,32 +5,30 @@ title: SkillRegisteredEvent # Interface: SkillRegisteredEvent -Defined in: [packages/ai/src/types.ts:1486](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1486) +Defined in: [packages/ai/src/types.ts:1570](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1570) Custom event for extensibility. @ag-ui/core provides: `name`, `value` TanStack AI adds: `model?` +Uses `Pick` (not `extends`) so the Zod passthrough index signature does not +erase discriminant property access on [KnownCustomEvent](../type-aliases/KnownCustomEvent.md) / +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) unions. + ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -46,7 +44,7 @@ Model identifier for multi-model support name: "skill:registered"; ``` -Defined in: [packages/ai/src/types.ts:1487](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1487) +Defined in: [packages/ai/src/types.ts:1571](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1571) #### Overrides @@ -56,13 +54,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1488](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1488) +Defined in: [packages/ai/src/types.ts:1572](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1572) #### description diff --git a/docs/reference/interfaces/StateDeltaEvent.md b/docs/reference/interfaces/StateDeltaEvent.md index 31ed06e466..26b26ed9b2 100644 --- a/docs/reference/interfaces/StateDeltaEvent.md +++ b/docs/reference/interfaces/StateDeltaEvent.md @@ -5,7 +5,7 @@ title: StateDeltaEvent # Interface: StateDeltaEvent -Defined in: [packages/ai/src/types.ts:1326](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1326) +Defined in: [packages/ai/src/types.ts:1386](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1386) Emitted to provide an incremental state update. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1328](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1328) +Defined in: [packages/ai/src/types.ts:1388](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1388) Model identifier for multi-model support diff --git a/docs/reference/interfaces/StateSnapshotEvent.md b/docs/reference/interfaces/StateSnapshotEvent.md index 9f940b4bbe..6a45b4712f 100644 --- a/docs/reference/interfaces/StateSnapshotEvent.md +++ b/docs/reference/interfaces/StateSnapshotEvent.md @@ -5,7 +5,7 @@ title: StateSnapshotEvent # Interface: StateSnapshotEvent -Defined in: [packages/ai/src/types.ts:1310](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1310) +Defined in: [packages/ai/src/types.ts:1370](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1370) Emitted to provide a full state snapshot. @@ -27,10 +27,10 @@ TanStack AI adds: `model?`, `state?` (deprecated alias for snapshot) ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1312](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1312) +Defined in: [packages/ai/src/types.ts:1372](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1372) Model identifier for multi-model support @@ -39,10 +39,10 @@ Model identifier for multi-model support ### ~~state?~~ ```ts -optional state: Record; +optional state?: Record; ``` -Defined in: [packages/ai/src/types.ts:1317](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1317) +Defined in: [packages/ai/src/types.ts:1377](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1377) #### Deprecated diff --git a/docs/reference/interfaces/StepFinishedEvent.md b/docs/reference/interfaces/StepFinishedEvent.md index 6cece85b54..3c1d6b6a56 100644 --- a/docs/reference/interfaces/StepFinishedEvent.md +++ b/docs/reference/interfaces/StepFinishedEvent.md @@ -5,7 +5,7 @@ title: StepFinishedEvent # Interface: StepFinishedEvent -Defined in: [packages/ai/src/types.ts:1271](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1271) +Defined in: [packages/ai/src/types.ts:1331](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1331) Emitted when a thinking/reasoning step finishes. @@ -27,10 +27,10 @@ TanStack AI adds: `model?`, `stepId?` (deprecated alias), `delta?`, `content?` ### content? ```ts -optional content: string; +optional content?: string; ``` -Defined in: [packages/ai/src/types.ts:1282](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1282) +Defined in: [packages/ai/src/types.ts:1342](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1342) Full accumulated thinking content (TanStack AI internal) @@ -39,10 +39,10 @@ Full accumulated thinking content (TanStack AI internal) ### delta? ```ts -optional delta: string; +optional delta?: string; ``` -Defined in: [packages/ai/src/types.ts:1280](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1280) +Defined in: [packages/ai/src/types.ts:1340](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1340) Incremental thinking content (TanStack AI internal) @@ -51,10 +51,10 @@ Incremental thinking content (TanStack AI internal) ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1273](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1273) +Defined in: [packages/ai/src/types.ts:1333](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1333) Model identifier for multi-model support @@ -63,10 +63,10 @@ Model identifier for multi-model support ### signature? ```ts -optional signature: string; +optional signature?: string; ``` -Defined in: [packages/ai/src/types.ts:1284](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1284) +Defined in: [packages/ai/src/types.ts:1344](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1344) Provider signature for the thinking block @@ -75,10 +75,10 @@ Provider signature for the thinking block ### ~~stepId?~~ ```ts -optional stepId: string; +optional stepId?: string; ``` -Defined in: [packages/ai/src/types.ts:1278](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1278) +Defined in: [packages/ai/src/types.ts:1338](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1338) #### Deprecated diff --git a/docs/reference/interfaces/StepStartedEvent.md b/docs/reference/interfaces/StepStartedEvent.md index 469836e700..587ea01c6c 100644 --- a/docs/reference/interfaces/StepStartedEvent.md +++ b/docs/reference/interfaces/StepStartedEvent.md @@ -5,7 +5,7 @@ title: StepStartedEvent # Interface: StepStartedEvent -Defined in: [packages/ai/src/types.ts:1253](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1253) +Defined in: [packages/ai/src/types.ts:1313](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1313) Emitted when a thinking/reasoning step starts. @@ -27,10 +27,10 @@ TanStack AI adds: `model?`, `stepId?` (deprecated alias), `stepType?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1255](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1255) +Defined in: [packages/ai/src/types.ts:1315](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1315) Model identifier for multi-model support @@ -39,10 +39,10 @@ Model identifier for multi-model support ### ~~stepId?~~ ```ts -optional stepId: string; +optional stepId?: string; ``` -Defined in: [packages/ai/src/types.ts:1260](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1260) +Defined in: [packages/ai/src/types.ts:1320](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1320) #### Deprecated @@ -54,9 +54,9 @@ Kept for backward compatibility. ### stepType? ```ts -optional stepType: string; +optional stepType?: string; ``` -Defined in: [packages/ai/src/types.ts:1262](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1262) +Defined in: [packages/ai/src/types.ts:1322](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1322) Type of step (e.g., 'thinking', 'planning') diff --git a/docs/reference/interfaces/StreamDurability.md b/docs/reference/interfaces/StreamDurability.md new file mode 100644 index 0000000000..0d40e651c1 --- /dev/null +++ b/docs/reference/interfaces/StreamDurability.md @@ -0,0 +1,154 @@ +--- +id: StreamDurability +title: StreamDurability +--- + +# Interface: StreamDurability\ + +Defined in: [packages/ai/src/stream-durability.ts:10](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L10) + +A pluggable delivery-durability backend. + +Offsets are owned by the adapter and opaque to the transport. The generic +parameter lets an adapter retain a branded string type across append, read, +and resume without requiring core to understand its cursor format. + +## Extended by + +- [`UpsertableStreamDurability`](UpsertableStreamDurability.md) + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` = `string` + +## Properties + +### append + +```ts +append: (chunks) => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:17](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L17) + +Persist a batch before it is delivered and return exactly one resumable +offset for each chunk, in the same order. + +#### Parameters + +##### chunks + +[`AGUIEvent`](../type-aliases/AGUIEvent.md)[] + +#### Returns + +`Promise`\<`TOffset`[]\> + +*** + +### close + +```ts +close: () => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:27](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L27) + +Terminalize the producer log and unblock live readers. Core awaits this +for every producer exit, including completion, cancellation, and failure. + +#### Returns + +`Promise`\<`void`\> + +*** + +### read + +```ts +read: (offset, signal?) => AsyncIterable<{ + chunk: AGUIEvent; + offset: TOffset; +}>; +``` + +Defined in: [packages/ai/src/stream-durability.ts:19](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L19) + +Replay chunks strictly after the supplied adapter-owned offset. + +#### Parameters + +##### offset + +`TOffset` + +##### signal? + +`AbortSignal` + +#### Returns + +`AsyncIterable`\<\{ + `chunk`: [`AGUIEvent`](../type-aliases/AGUIEvent.md); + `offset`: `TOffset`; +\}\> + +*** + +### resumeFrom + +```ts +resumeFrom: () => TOffset | null; +``` + +Defined in: [packages/ai/src/stream-durability.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L12) + +Return the adapter offset captured from the request, or null for a producer. + +#### Returns + +`TOffset` \| `null` + +*** + +### snapshot + +```ts +snapshot: () => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L57) + +Everything stored for this run **at the moment of the call**, in append +order, then resolve. + +This is the bounded counterpart to [StreamDurability.read](#read). `read` +tails: it parks until the log is terminalized or the caller aborts, so it +cannot be used to inspect a log whose producer died without calling +`close` — that log stays open forever and a `for await` over it never +finishes. `snapshot` exists for exactly that case: a producer resuming a +run needs to see the prefix a previous host already stored so it can line +its own output up against it, and it needs that read to *return*. + +Implementations MUST: + +- never wait for more entries — resolve with what is stored, including + while the log is still open and still being appended to; +- resolve to an empty array for a run with nothing stored, rather than + throwing. In particular an implementation must not reuse the + unknown-run failure path a from-start `read` join takes (`read('-1')` on + an empty log is allowed to fail; `snapshot()` is not). A backend over a + network may of course still reject on a transport, protocol, or + authorization failure — that is a failed call, not an empty run; +- return a fresh array the caller can keep or mutate without reaching the + stored log through it. + +The result is a point-in-time view and carries no lock: a concurrent +`append` may land immediately after the snapshot is taken, so a caller +must not treat the last returned offset as the permanent tail. + +#### Returns + +`Promise`\<`object`[]\> diff --git a/docs/reference/interfaces/StreamProcessorEvents.md b/docs/reference/interfaces/StreamProcessorEvents.md index 4cc04d90bf..32fea9a199 100644 --- a/docs/reference/interfaces/StreamProcessorEvents.md +++ b/docs/reference/interfaces/StreamProcessorEvents.md @@ -5,19 +5,19 @@ title: StreamProcessorEvents # Interface: StreamProcessorEvents -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:67](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L67) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:68](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L68) Events emitted by the StreamProcessor ## Properties -### onApprovalRequest()? +### onApprovalRequest? ```ts -optional onApprovalRequest: (args) => void; +optional onApprovalRequest?: (args) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:82](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L82) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:83](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L83) #### Parameters @@ -45,13 +45,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:82](https://git *** -### onCustomEvent()? +### onCustomEvent? ```ts -optional onCustomEvent: (eventType, data, context) => void; +optional onCustomEvent?: (eventType, data, context) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L90) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:91](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L91) #### Parameters @@ -75,13 +75,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:90](https://git *** -### onError()? +### onError? ```ts -optional onError: (error) => void; +optional onError?: (error) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:74](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L74) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:75](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L75) #### Parameters @@ -95,13 +95,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:74](https://git *** -### onMessagesChange()? +### onMessagesChange? ```ts -optional onMessagesChange: (messages) => void; +optional onMessagesChange?: (messages) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:69](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L69) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:70](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L70) #### Parameters @@ -115,13 +115,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:69](https://git *** -### onStreamEnd()? +### onStreamEnd? ```ts -optional onStreamEnd: (message) => void; +optional onStreamEnd?: (message) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:73](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L73) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:74](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L74) #### Parameters @@ -135,13 +135,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:73](https://git *** -### onStreamStart()? +### onStreamStart? ```ts -optional onStreamStart: () => void; +optional onStreamStart?: () => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:72](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L72) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:73](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L73) #### Returns @@ -149,13 +149,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:72](https://git *** -### onStructuredOutputChange()? +### onStructuredOutputChange? ```ts -optional onStructuredOutputChange: (args) => void; +optional onStructuredOutputChange?: (args) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:109](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L109) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:110](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L110) #### Parameters @@ -203,13 +203,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:109](https://gi *** -### onTextUpdate()? +### onTextUpdate? ```ts -optional onTextUpdate: (messageId, content) => void; +optional onTextUpdate?: (messageId, content) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:97](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L97) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:98](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L98) #### Parameters @@ -227,13 +227,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:97](https://git *** -### onThinkingUpdate()? +### onThinkingUpdate? ```ts -optional onThinkingUpdate: (messageId, stepId, content) => void; +optional onThinkingUpdate?: (messageId, stepId, content) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L104) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:105](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L105) #### Parameters @@ -255,13 +255,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:104](https://gi *** -### onToolCall()? +### onToolCall? ```ts -optional onToolCall: (args) => void; +optional onToolCall?: (args) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:77](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L77) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:78](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L78) #### Parameters @@ -285,13 +285,13 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:77](https://git *** -### onToolCallStateChange()? +### onToolCallStateChange? ```ts -optional onToolCallStateChange: (messageId, toolCallId, state, args) => void; +optional onToolCallStateChange?: (messageId, toolCallId, state, args) => void; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:98](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L98) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:99](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L99) #### Parameters diff --git a/docs/reference/interfaces/StreamProcessorOptions.md b/docs/reference/interfaces/StreamProcessorOptions.md index e7fe7dd5df..a25b22493c 100644 --- a/docs/reference/interfaces/StreamProcessorOptions.md +++ b/docs/reference/interfaces/StreamProcessorOptions.md @@ -5,7 +5,7 @@ title: StreamProcessorOptions # Interface: StreamProcessorOptions -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:125](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L125) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:126](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L126) Options for StreamProcessor @@ -14,20 +14,20 @@ Options for StreamProcessor ### chunkStrategy? ```ts -optional chunkStrategy: ChunkStrategy; +optional chunkStrategy?: ChunkStrategy; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:126](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L126) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:127](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L127) *** ### events? ```ts -optional events: StreamProcessorEvents; +optional events?: StreamProcessorEvents; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:128](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L128) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:129](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L129) Event-driven handlers @@ -36,10 +36,10 @@ Event-driven handlers ### initialMessages? ```ts -optional initialMessages: UIMessage[]; +optional initialMessages?: UIMessage[]; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:135](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L135) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:136](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L136) Initial messages to populate the processor @@ -48,12 +48,12 @@ Initial messages to populate the processor ### jsonParser? ```ts -optional jsonParser: object; +optional jsonParser?: object; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:129](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L129) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:130](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L130) -#### parse() +#### parse ```ts parse: (jsonString) => any; @@ -74,9 +74,9 @@ parse: (jsonString) => any; ### recording? ```ts -optional recording: boolean; +optional recording?: boolean; ``` -Defined in: [packages/ai/src/activities/chat/stream/processor.ts:133](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L133) +Defined in: [packages/ai/src/activities/chat/stream/processor.ts:134](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L134) Enable recording for replay testing diff --git a/docs/reference/interfaces/StructuredOutputCompleteEvent.md b/docs/reference/interfaces/StructuredOutputCompleteEvent.md index 49c217236c..c9ba555558 100644 --- a/docs/reference/interfaces/StructuredOutputCompleteEvent.md +++ b/docs/reference/interfaces/StructuredOutputCompleteEvent.md @@ -5,7 +5,7 @@ title: StructuredOutputCompleteEvent # Interface: StructuredOutputCompleteEvent\ -Defined in: [packages/ai/src/types.ts:1360](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1360) +Defined in: [packages/ai/src/types.ts:1436](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1436) Final event of a streaming structured-output run. Carries the validated `object` (typed as `T` after the orchestrator runs Standard Schema parsing), @@ -34,21 +34,15 @@ if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') { `T` = `unknown` -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -64,7 +58,7 @@ Model identifier for multi-model support name: "structured-output.complete"; ``` -Defined in: [packages/ai/src/types.ts:1363](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1363) +Defined in: [packages/ai/src/types.ts:1439](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1439) #### Overrides @@ -74,13 +68,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1364](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1364) +Defined in: [packages/ai/src/types.ts:1440](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1440) #### object @@ -97,7 +138,7 @@ raw: string; #### reasoning? ```ts -optional reasoning: string; +optional reasoning?: string; ``` #### Overrides diff --git a/docs/reference/interfaces/StructuredOutputMiddlewareConfig.md b/docs/reference/interfaces/StructuredOutputMiddlewareConfig.md index 19fc367fdd..d51886bb55 100644 --- a/docs/reference/interfaces/StructuredOutputMiddlewareConfig.md +++ b/docs/reference/interfaces/StructuredOutputMiddlewareConfig.md @@ -5,7 +5,7 @@ title: StructuredOutputMiddlewareConfig # Interface: StructuredOutputMiddlewareConfig -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:225](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L225) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:251](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L251) Config passed to onStructuredOutputConfig. @@ -31,7 +31,7 @@ messages: ModelMessage< | null>[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:208](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L208) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:213](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L213) #### Inherited from @@ -42,10 +42,10 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:208](https://gi ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:211](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L211) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:218](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L218) #### Inherited from @@ -56,10 +56,10 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:211](https://gi ### modelOptions? ```ts -optional modelOptions: Record; +optional modelOptions?: Record; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:212](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L212) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:219](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L219) #### Inherited from @@ -73,19 +73,47 @@ Defined in: [packages/ai/src/activities/chat/middleware/types.ts:212](https://gi outputSchema: JSONSchema; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:230](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L230) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:256](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L256) JSON Schema being sent to the provider for structured output. *** +### resume? + +```ts +optional resume?: ResumeEntry[]; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:216](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L216) + +#### Inherited from + +[`ChatMiddlewareConfig`](ChatMiddlewareConfig.md).[`resume`](ChatMiddlewareConfig.md#resume) + +*** + +### resumeToolState? + +```ts +optional resumeToolState?: ChatResumeToolState; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:217](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L217) + +#### Inherited from + +[`ChatMiddlewareConfig`](ChatMiddlewareConfig.md).[`resumeToolState`](ChatMiddlewareConfig.md#resumetoolstate) + +*** + ### systemPrompts ```ts systemPrompts: SystemPrompt[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:209](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L209) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:214](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L214) #### Inherited from diff --git a/docs/reference/interfaces/StructuredOutputPart.md b/docs/reference/interfaces/StructuredOutputPart.md index 6846cba3d2..958f28abb5 100644 --- a/docs/reference/interfaces/StructuredOutputPart.md +++ b/docs/reference/interfaces/StructuredOutputPart.md @@ -5,7 +5,7 @@ title: StructuredOutputPart # Interface: StructuredOutputPart\ -Defined in: [packages/ai/src/types.ts:436](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L436) +Defined in: [packages/ai/src/types.ts:461](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L461) StructuredOutputPart — a typed structured response attached to the assistant message that produced it. Generic over the schema-inferred data type so @@ -24,10 +24,10 @@ to `messages[i].parts[j].data`. Defaults to `unknown` so untyped consumers ### data? ```ts -optional data: TData; +optional data?: TData; ``` -Defined in: [packages/ai/src/types.ts:442](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L442) +Defined in: [packages/ai/src/types.ts:467](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L467) Validated final object — only set when `status === 'complete'`. @@ -36,10 +36,10 @@ Validated final object — only set when `status === 'complete'`. ### errorMessage? ```ts -optional errorMessage: string; +optional errorMessage?: string; ``` -Defined in: [packages/ai/src/types.ts:448](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L448) +Defined in: [packages/ai/src/types.ts:473](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L473) Populated when `status === 'error'`. @@ -48,10 +48,10 @@ Populated when `status === 'error'`. ### partial? ```ts -optional partial: DeepPartial; +optional partial?: DeepPartial; ``` -Defined in: [packages/ai/src/types.ts:440](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L440) +Defined in: [packages/ai/src/types.ts:465](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L465) Progressive parse of `raw` via parsePartialJSON — populated while streaming and after complete. @@ -63,7 +63,7 @@ Progressive parse of `raw` via parsePartialJSON — populated while streaming an raw: string; ``` -Defined in: [packages/ai/src/types.ts:444](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L444) +Defined in: [packages/ai/src/types.ts:469](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L469) Accumulating JSON buffer. Source of truth for wire round-trip. @@ -72,10 +72,10 @@ Accumulating JSON buffer. Source of truth for wire round-trip. ### reasoning? ```ts -optional reasoning: string; +optional reasoning?: string; ``` -Defined in: [packages/ai/src/types.ts:446](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L446) +Defined in: [packages/ai/src/types.ts:471](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L471) Optional chain-of-thought surfaced by reasoning models alongside the structured output. @@ -87,7 +87,7 @@ Optional chain-of-thought surfaced by reasoning models alongside the structured status: "error" | "complete" | "streaming"; ``` -Defined in: [packages/ai/src/types.ts:438](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L438) +Defined in: [packages/ai/src/types.ts:463](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L463) *** @@ -97,4 +97,4 @@ Defined in: [packages/ai/src/types.ts:438](https://github.com/TanStack/ai/blob/m type: "structured-output"; ``` -Defined in: [packages/ai/src/types.ts:437](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L437) +Defined in: [packages/ai/src/types.ts:462](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L462) diff --git a/docs/reference/interfaces/StructuredOutputStartEvent.md b/docs/reference/interfaces/StructuredOutputStartEvent.md index 52bdb93702..53c13546bd 100644 --- a/docs/reference/interfaces/StructuredOutputStartEvent.md +++ b/docs/reference/interfaces/StructuredOutputStartEvent.md @@ -5,7 +5,7 @@ title: StructuredOutputStartEvent # Interface: StructuredOutputStartEvent -Defined in: [packages/ai/src/types.ts:1375](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1375) +Defined in: [packages/ai/src/types.ts:1451](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1451) Emitted at the start of a streaming structured-output run, before the JSON deltas. Tells consumers that the upcoming `TEXT_MESSAGE_CONTENT` deltas @@ -18,21 +18,15 @@ made per-message rather than globally. - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -48,7 +42,7 @@ Model identifier for multi-model support name: "structured-output.start"; ``` -Defined in: [packages/ai/src/types.ts:1376](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1376) +Defined in: [packages/ai/src/types.ts:1452](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1452) #### Overrides @@ -58,13 +52,60 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1377](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1377) +Defined in: [packages/ai/src/types.ts:1453](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1453) #### messageId diff --git a/docs/reference/interfaces/SummarizationOptions.md b/docs/reference/interfaces/SummarizationOptions.md index 97d9b6e99f..de01531e0d 100644 --- a/docs/reference/interfaces/SummarizationOptions.md +++ b/docs/reference/interfaces/SummarizationOptions.md @@ -5,7 +5,7 @@ title: SummarizationOptions # Interface: SummarizationOptions\ -Defined in: [packages/ai/src/types.ts:1680](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1680) +Defined in: [packages/ai/src/types.ts:1975](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1975) ## Type Parameters @@ -15,13 +15,27 @@ Defined in: [packages/ai/src/types.ts:1680](https://github.com/TanStack/ai/blob/ ## Properties +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2005](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2005) + +Effective abort signal composed by the activity from caller `abortSignal` +and/or `timeout`. Adapters should forward this to the provider SDK when +supported. Request-specific — never store on a global client config. + +*** + ### focus? ```ts -optional focus: string[]; +optional focus?: string[]; ``` -Defined in: [packages/ai/src/types.ts:1687](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1687) +Defined in: [packages/ai/src/types.ts:1982](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1982) *** @@ -31,7 +45,7 @@ Defined in: [packages/ai/src/types.ts:1687](https://github.com/TanStack/ai/blob/ logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:1694](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1694) +Defined in: [packages/ai/src/types.ts:1999](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1999) Internal logger threaded from the summarize() entry point. Adapters must call logger.request() before the SDK call and logger.errors() in catch blocks. @@ -41,10 +55,10 @@ call logger.request() before the SDK call and logger.errors() in catch blocks. ### maxLength? ```ts -optional maxLength: number; +optional maxLength?: number; ``` -Defined in: [packages/ai/src/types.ts:1685](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1685) +Defined in: [packages/ai/src/types.ts:1980](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1980) *** @@ -54,29 +68,46 @@ Defined in: [packages/ai/src/types.ts:1685](https://github.com/TanStack/ai/blob/ model: string; ``` -Defined in: [packages/ai/src/types.ts:1683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1683) +Defined in: [packages/ai/src/types.ts:1978](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1978) *** ### modelOptions? ```ts -optional modelOptions: TProviderOptions; +optional modelOptions?: TProviderOptions; ``` -Defined in: [packages/ai/src/types.ts:1689](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1689) +Defined in: [packages/ai/src/types.ts:1984](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1984) Provider-specific options forwarded by the summarize() activity. *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1993](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1993) + +Run identity forwarded from the summarize() activity. When set, the +streaming adapter stamps it onto the emitted `RUN_STARTED` (via the wrapped +chat), so a delivery-durable route keys the run's log by the same id the +client rejoins with — making a mid-run reload resumable, like the media +activities. Optional and non-breaking: adapters that ignore it just mint +their own. + +*** + ### style? ```ts -optional style: "bullet-points" | "paragraph" | "concise"; +optional style?: "bullet-points" | "paragraph" | "concise"; ``` -Defined in: [packages/ai/src/types.ts:1686](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1686) +Defined in: [packages/ai/src/types.ts:1981](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1981) *** @@ -86,4 +117,14 @@ Defined in: [packages/ai/src/types.ts:1686](https://github.com/TanStack/ai/blob/ text: string; ``` -Defined in: [packages/ai/src/types.ts:1684](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1684) +Defined in: [packages/ai/src/types.ts:1979](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1979) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1994](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1994) diff --git a/docs/reference/interfaces/SummarizationResult.md b/docs/reference/interfaces/SummarizationResult.md index 792b7c7c2a..3d8bd3d725 100644 --- a/docs/reference/interfaces/SummarizationResult.md +++ b/docs/reference/interfaces/SummarizationResult.md @@ -5,7 +5,7 @@ title: SummarizationResult # Interface: SummarizationResult -Defined in: [packages/ai/src/types.ts:1697](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1697) +Defined in: [packages/ai/src/types.ts:2008](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2008) ## Properties @@ -15,7 +15,7 @@ Defined in: [packages/ai/src/types.ts:1697](https://github.com/TanStack/ai/blob/ id: string; ``` -Defined in: [packages/ai/src/types.ts:1698](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1698) +Defined in: [packages/ai/src/types.ts:2009](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2009) *** @@ -25,7 +25,7 @@ Defined in: [packages/ai/src/types.ts:1698](https://github.com/TanStack/ai/blob/ model: string; ``` -Defined in: [packages/ai/src/types.ts:1699](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1699) +Defined in: [packages/ai/src/types.ts:2010](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2010) *** @@ -35,7 +35,7 @@ Defined in: [packages/ai/src/types.ts:1699](https://github.com/TanStack/ai/blob/ summary: string; ``` -Defined in: [packages/ai/src/types.ts:1700](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1700) +Defined in: [packages/ai/src/types.ts:2011](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2011) *** @@ -45,4 +45,4 @@ Defined in: [packages/ai/src/types.ts:1700](https://github.com/TanStack/ai/blob/ usage: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:1701](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1701) +Defined in: [packages/ai/src/types.ts:2012](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2012) diff --git a/docs/reference/interfaces/SummarizeAdapter.md b/docs/reference/interfaces/SummarizeAdapter.md index 1ea03b8acc..5643810b13 100644 --- a/docs/reference/interfaces/SummarizeAdapter.md +++ b/docs/reference/interfaces/SummarizeAdapter.md @@ -84,7 +84,7 @@ Adapter name identifier *** -### summarize() +### summarize ```ts summarize: (options) => Promise; @@ -106,10 +106,10 @@ Summarize the given text *** -### summarizeStream()? +### summarizeStream? ```ts -optional summarizeStream: (options) => AsyncIterable; +optional summarizeStream?: (options) => AsyncIterable; ``` Defined in: [packages/ai/src/activities/summarize/adapter.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/summarize/adapter.ts#L58) diff --git a/docs/reference/interfaces/TTSAdapter.md b/docs/reference/interfaces/TTSAdapter.md index e4a38253f3..cd09ef0f47 100644 --- a/docs/reference/interfaces/TTSAdapter.md +++ b/docs/reference/interfaces/TTSAdapter.md @@ -48,7 +48,7 @@ providerOptions: TProviderOptions; *** -### generateSpeech() +### generateSpeech ```ts generateSpeech: (options) => Promise; diff --git a/docs/reference/interfaces/TTSOptions.md b/docs/reference/interfaces/TTSOptions.md index 0defbf27c1..e8c61191f8 100644 --- a/docs/reference/interfaces/TTSOptions.md +++ b/docs/reference/interfaces/TTSOptions.md @@ -5,7 +5,7 @@ title: TTSOptions # Interface: TTSOptions\ -Defined in: [packages/ai/src/types.ts:2024](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2024) +Defined in: [packages/ai/src/types.ts:2474](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2474) Options for text-to-speech generation. These are the common options supported across providers. @@ -18,13 +18,27 @@ These are the common options supported across providers. ## Properties +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2498](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2498) + +Effective abort signal composed by the activity from caller `abortSignal` +and/or `timeout`. Adapters should forward this to the provider SDK when +supported. Request-specific — never store on a global client config. + +*** + ### format? ```ts -optional format: "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm"; +optional format?: "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm"; ``` -Defined in: [packages/ai/src/types.ts:2032](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2032) +Defined in: [packages/ai/src/types.ts:2482](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2482) The output audio format @@ -36,7 +50,7 @@ The output audio format logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:2042](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2042) +Defined in: [packages/ai/src/types.ts:2492](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2492) Internal logger threaded from the generateSpeech() entry point. Adapters must call logger.request() before the SDK call and logger.errors() in @@ -50,7 +64,7 @@ catch blocks. model: string; ``` -Defined in: [packages/ai/src/types.ts:2026](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2026) +Defined in: [packages/ai/src/types.ts:2476](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2476) The model to use for TTS generation @@ -59,10 +73,10 @@ The model to use for TTS generation ### modelOptions? ```ts -optional modelOptions: TProviderOptions; +optional modelOptions?: TProviderOptions; ``` -Defined in: [packages/ai/src/types.ts:2036](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2036) +Defined in: [packages/ai/src/types.ts:2486](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2486) Model-specific options for TTS generation @@ -71,10 +85,10 @@ Model-specific options for TTS generation ### speed? ```ts -optional speed: number; +optional speed?: number; ``` -Defined in: [packages/ai/src/types.ts:2034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2034) +Defined in: [packages/ai/src/types.ts:2484](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2484) The speed of the generated audio (0.25 to 4.0) @@ -86,7 +100,7 @@ The speed of the generated audio (0.25 to 4.0) text: string; ``` -Defined in: [packages/ai/src/types.ts:2028](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2028) +Defined in: [packages/ai/src/types.ts:2478](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2478) The text to convert to speech @@ -95,9 +109,9 @@ The text to convert to speech ### voice? ```ts -optional voice: string; +optional voice?: string; ``` -Defined in: [packages/ai/src/types.ts:2030](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2030) +Defined in: [packages/ai/src/types.ts:2480](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2480) The voice to use for generation diff --git a/docs/reference/interfaces/TTSResult.md b/docs/reference/interfaces/TTSResult.md index 5b13f81430..15d7b0c45f 100644 --- a/docs/reference/interfaces/TTSResult.md +++ b/docs/reference/interfaces/TTSResult.md @@ -5,19 +5,31 @@ title: TTSResult # Interface: TTSResult -Defined in: [packages/ai/src/types.ts:2048](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2048) +Defined in: [packages/ai/src/types.ts:2504](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2504) Result of text-to-speech generation. ## Properties +### artifacts? + +```ts +optional artifacts?: PersistedArtifactRef[]; +``` + +Defined in: [packages/ai/src/types.ts:2520](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2520) + +Persisted artifact references for generated assets, when available + +*** + ### audio ```ts audio: string; ``` -Defined in: [packages/ai/src/types.ts:2054](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2054) +Defined in: [packages/ai/src/types.ts:2510](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2510) Base64-encoded audio data @@ -26,10 +38,10 @@ Base64-encoded audio data ### contentType? ```ts -optional contentType: string; +optional contentType?: string; ``` -Defined in: [packages/ai/src/types.ts:2060](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2060) +Defined in: [packages/ai/src/types.ts:2516](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2516) Content type of the audio (e.g., 'audio/mp3') @@ -38,10 +50,10 @@ Content type of the audio (e.g., 'audio/mp3') ### duration? ```ts -optional duration: number; +optional duration?: number; ``` -Defined in: [packages/ai/src/types.ts:2058](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2058) +Defined in: [packages/ai/src/types.ts:2514](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2514) Duration of the audio in seconds, if available @@ -53,7 +65,7 @@ Duration of the audio in seconds, if available format: string; ``` -Defined in: [packages/ai/src/types.ts:2056](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2056) +Defined in: [packages/ai/src/types.ts:2512](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2512) Audio format of the generated audio @@ -65,7 +77,7 @@ Audio format of the generated audio id: string; ``` -Defined in: [packages/ai/src/types.ts:2050](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2050) +Defined in: [packages/ai/src/types.ts:2506](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2506) Unique identifier for the generation @@ -77,7 +89,7 @@ Unique identifier for the generation model: string; ``` -Defined in: [packages/ai/src/types.ts:2052](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2052) +Defined in: [packages/ai/src/types.ts:2508](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2508) Model used for generation @@ -86,9 +98,9 @@ Model used for generation ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:2062](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2062) +Defined in: [packages/ai/src/types.ts:2518](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2518) Token usage information (if provided by the adapter) diff --git a/docs/reference/interfaces/TextAdapter.md b/docs/reference/interfaces/TextAdapter.md index 0b8fb4c6e7..c71d6c052f 100644 --- a/docs/reference/interfaces/TextAdapter.md +++ b/docs/reference/interfaces/TextAdapter.md @@ -106,7 +106,7 @@ toolCapabilities: TToolCapabilities; *** -### chatStream() +### chatStream ```ts chatStream: (options) => AsyncIterable; @@ -167,7 +167,7 @@ Provider name identifier (e.g., 'openai', 'anthropic') ### requires? ```ts -readonly optional requires: readonly CapabilityHandle[]; +readonly optional requires?: readonly CapabilityHandle[]; ``` Defined in: [packages/ai/src/activities/chat/adapter.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L90) @@ -180,7 +180,7 @@ this is the declaration/validation surface only. *** -### structuredOutput() +### structuredOutput ```ts structuredOutput: (options) => Promise>; @@ -208,10 +208,10 @@ Promise with the raw data (validation is done in the chat function) *** -### structuredOutputStream()? +### structuredOutputStream? ```ts -optional structuredOutputStream: (options) => AsyncIterable; +optional structuredOutputStream?: (options) => AsyncIterable; ``` Defined in: [packages/ai/src/activities/chat/adapter.ts:136](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L136) @@ -240,10 +240,10 @@ TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final *** -### supportsCombinedToolsAndSchema()? +### supportsCombinedToolsAndSchema? ```ts -optional supportsCombinedToolsAndSchema: (modelOptions?) => boolean; +optional supportsCombinedToolsAndSchema?: (modelOptions?) => boolean; ``` Defined in: [packages/ai/src/activities/chat/adapter.ts:159](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L159) diff --git a/docs/reference/interfaces/TextCompletionChunk.md b/docs/reference/interfaces/TextCompletionChunk.md index d84b3bf88d..2f3924b972 100644 --- a/docs/reference/interfaces/TextCompletionChunk.md +++ b/docs/reference/interfaces/TextCompletionChunk.md @@ -5,7 +5,7 @@ title: TextCompletionChunk # Interface: TextCompletionChunk -Defined in: [packages/ai/src/types.ts:1671](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1671) +Defined in: [packages/ai/src/types.ts:1966](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1966) ## Properties @@ -15,17 +15,17 @@ Defined in: [packages/ai/src/types.ts:1671](https://github.com/TanStack/ai/blob/ content: string; ``` -Defined in: [packages/ai/src/types.ts:1674](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1674) +Defined in: [packages/ai/src/types.ts:1969](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1969) *** ### finishReason? ```ts -optional finishReason: "length" | "stop" | "content_filter" | null; +optional finishReason?: "length" | "stop" | "content_filter" | null; ``` -Defined in: [packages/ai/src/types.ts:1676](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1676) +Defined in: [packages/ai/src/types.ts:1971](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1971) *** @@ -35,7 +35,7 @@ Defined in: [packages/ai/src/types.ts:1676](https://github.com/TanStack/ai/blob/ id: string; ``` -Defined in: [packages/ai/src/types.ts:1672](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1672) +Defined in: [packages/ai/src/types.ts:1967](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1967) *** @@ -45,24 +45,24 @@ Defined in: [packages/ai/src/types.ts:1672](https://github.com/TanStack/ai/blob/ model: string; ``` -Defined in: [packages/ai/src/types.ts:1673](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1673) +Defined in: [packages/ai/src/types.ts:1968](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1968) *** ### role? ```ts -optional role: "assistant"; +optional role?: "assistant"; ``` -Defined in: [packages/ai/src/types.ts:1675](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1675) +Defined in: [packages/ai/src/types.ts:1970](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1970) *** ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:1677](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1677) +Defined in: [packages/ai/src/types.ts:1972](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1972) diff --git a/docs/reference/interfaces/TextMessageContentEvent.md b/docs/reference/interfaces/TextMessageContentEvent.md index ac0de2e9a8..33b4e674a5 100644 --- a/docs/reference/interfaces/TextMessageContentEvent.md +++ b/docs/reference/interfaces/TextMessageContentEvent.md @@ -5,7 +5,7 @@ title: TextMessageContentEvent # Interface: TextMessageContentEvent -Defined in: [packages/ai/src/types.ts:1156](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1156) +Defined in: [packages/ai/src/types.ts:1181](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1181) Emitted when text content is generated (streaming tokens). @@ -27,10 +27,10 @@ TanStack AI adds: `model?`, `content?` (accumulated) ### content? ```ts -optional content: string; +optional content?: string; ``` -Defined in: [packages/ai/src/types.ts:1160](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1160) +Defined in: [packages/ai/src/types.ts:1185](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1185) Full accumulated content so far (TanStack AI internal, for debugging) @@ -39,9 +39,9 @@ Full accumulated content so far (TanStack AI internal, for debugging) ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1158](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1158) +Defined in: [packages/ai/src/types.ts:1183](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1183) Model identifier for multi-model support diff --git a/docs/reference/interfaces/TextMessageEndEvent.md b/docs/reference/interfaces/TextMessageEndEvent.md index a9d1d6216c..5ed84c2baa 100644 --- a/docs/reference/interfaces/TextMessageEndEvent.md +++ b/docs/reference/interfaces/TextMessageEndEvent.md @@ -5,7 +5,7 @@ title: TextMessageEndEvent # Interface: TextMessageEndEvent -Defined in: [packages/ai/src/types.ts:1169](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1169) +Defined in: [packages/ai/src/types.ts:1194](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1194) Emitted when a text message completes. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1171](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1171) +Defined in: [packages/ai/src/types.ts:1196](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1196) Model identifier for multi-model support diff --git a/docs/reference/interfaces/TextMessageStartEvent.md b/docs/reference/interfaces/TextMessageStartEvent.md index 8fdfef75c9..7c83450d63 100644 --- a/docs/reference/interfaces/TextMessageStartEvent.md +++ b/docs/reference/interfaces/TextMessageStartEvent.md @@ -5,7 +5,7 @@ title: TextMessageStartEvent # Interface: TextMessageStartEvent -Defined in: [packages/ai/src/types.ts:1145](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1145) +Defined in: [packages/ai/src/types.ts:1170](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1170) Emitted when a text message starts. @@ -27,9 +27,9 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1147](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1147) +Defined in: [packages/ai/src/types.ts:1172](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1172) Model identifier for multi-model support diff --git a/docs/reference/interfaces/TextOptions.md b/docs/reference/interfaces/TextOptions.md index b1da1eaea9..a64700b189 100644 --- a/docs/reference/interfaces/TextOptions.md +++ b/docs/reference/interfaces/TextOptions.md @@ -5,7 +5,7 @@ title: TextOptions # Interface: TextOptions\ -Defined in: [packages/ai/src/types.ts:873](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L873) +Defined in: [packages/ai/src/types.ts:898](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L898) Options passed into the SDK and further piped to the AI provider. @@ -28,10 +28,10 @@ Options passed into the SDK and further piped to the AI provider. ### abortController? ```ts -optional abortController: AbortController; +optional abortController?: AbortController; ``` -Defined in: [packages/ai/src/types.ts:988](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L988) +Defined in: [packages/ai/src/types.ts:995](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L995) AbortController for request cancellation. @@ -55,20 +55,20 @@ https://developer.mozilla.org/en-US/docs/Web/API/AbortController ### agentLoopStrategy? ```ts -optional agentLoopStrategy: AgentLoopStrategy; +optional agentLoopStrategy?: AgentLoopStrategy; ``` -Defined in: [packages/ai/src/types.ts:901](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L901) +Defined in: [packages/ai/src/types.ts:926](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L926) *** ### approvals? ```ts -optional approvals: ReadonlyMap; +optional approvals?: ReadonlyMap; ``` -Defined in: [packages/ai/src/types.ts:1031](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1031) +Defined in: [packages/ai/src/types.ts:1048](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1048) Client approval decisions for this run, keyed by approval id. The engine populates this from approvals carried on the incoming messages. Harness @@ -81,10 +81,10 @@ here). Undefined for direct adapter usage outside the chat engine. ### capabilities? ```ts -optional capabilities: CapabilityContext; +optional capabilities?: CapabilityContext; ``` -Defined in: [packages/ai/src/types.ts:1022](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1022) +Defined in: [packages/ai/src/types.ts:1039](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1039) Middleware capability context for this run. The engine populates it with the live middleware context so harness adapters that declare @@ -98,10 +98,10 @@ direct adapter usage outside the chat engine. ### context? ```ts -optional context: TContext; +optional context?: TContext; ``` -Defined in: [packages/ai/src/types.ts:885](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L885) +Defined in: [packages/ai/src/types.ts:910](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L910) Runtime context provided by the caller and passed to middleware and server-side tool implementations. @@ -111,10 +111,10 @@ server-side tool implementations. ### ~~conversationId?~~ ```ts -optional conversationId: string; +optional conversationId?: string; ``` -Defined in: [packages/ai/src/types.ts:974](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L974) +Defined in: [packages/ai/src/types.ts:981](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L981) #### Deprecated @@ -132,10 +132,10 @@ Will be removed in a future major release. ### lazyToolsConfig? ```ts -optional lazyToolsConfig: LazyToolsConfig; +optional lazyToolsConfig?: LazyToolsConfig; ``` -Defined in: [packages/ai/src/types.ts:925](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L925) +Defined in: [packages/ai/src/types.ts:932](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L932) Optional configuration for lazy-tool discovery (tools marked `lazy: true`). Tunes how much of each lazy tool's description appears in the discovery @@ -149,7 +149,7 @@ catalog. Optional — defaults to `{ includeDescription: 'none' }`. logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:995](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L995) +Defined in: [packages/ai/src/types.ts:1002](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1002) Internal logger threaded from the chat entry point. Adapter implementations must call `logger.request()` before SDK calls, `logger.provider()` for each @@ -166,17 +166,17 @@ messages: ModelMessage< | null>[]; ``` -Defined in: [packages/ai/src/types.ts:879](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L879) +Defined in: [packages/ai/src/types.ts:904](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L904) *** ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:936](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L936) +Defined in: [packages/ai/src/types.ts:943](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L943) Observability metadata attached to this call. Surfaced to middleware, devtools, and the event client; values may be arbitrarily structured @@ -195,27 +195,27 @@ OpenAI's and OpenRouter's `metadata` are both Record). model: string; ``` -Defined in: [packages/ai/src/types.ts:878](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L878) +Defined in: [packages/ai/src/types.ts:903](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L903) *** ### modelOptions? ```ts -optional modelOptions: TProviderOptionsForModel; +optional modelOptions?: TProviderOptionsForModel; ``` -Defined in: [packages/ai/src/types.ts:937](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L937) +Defined in: [packages/ai/src/types.ts:944](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L944) *** ### outputSchema? ```ts -optional outputSchema: SchemaInput; +optional outputSchema?: SchemaInput; ``` -Defined in: [packages/ai/src/types.ts:963](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L963) +Defined in: [packages/ai/src/types.ts:970](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L970) Schema for structured output. @@ -244,10 +244,10 @@ Schema for structured output. ### parentRunId? ```ts -optional parentRunId: string; +optional parentRunId?: string; ``` -Defined in: [packages/ai/src/types.ts:1012](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1012) +Defined in: [packages/ai/src/types.ts:1019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1019) Parent run ID for AG-UI protocol nested run correlation. Surfaced for observability/middleware; not consumed by the LLM call. @@ -257,20 +257,34 @@ Surfaced for observability/middleware; not consumed by the LLM call. ### request? ```ts -optional request: Request | RequestInit; +optional request?: Request | RequestInit; +``` + +Defined in: [packages/ai/src/types.ts:945](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L945) + +*** + +### resume? + +```ts +optional resume?: ResumeEntry[]; ``` -Defined in: [packages/ai/src/types.ts:938](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L938) +Defined in: [packages/ai/src/types.ts:1029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1029) + +AG-UI interrupt resume responses supplied by the client on a follow-up run. +Threaded through request parsing now so later runtime behavior can resolve +upstream-native interrupts. *** ### runId? ```ts -optional runId: string; +optional runId?: string; ``` -Defined in: [packages/ai/src/types.ts:1007](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1007) +Defined in: [packages/ai/src/types.ts:1014](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1014) Run ID for AG-UI protocol run correlation. When provided, this will be used in RunStartedEvent and RunFinishedEvent. @@ -278,13 +292,25 @@ If not provided, a unique ID will be generated. *** +### state? + +```ts +optional state?: unknown; +``` + +Defined in: [packages/ai/src/types.ts:1022](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1022) + +Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. + +*** + ### systemPrompts? ```ts -optional systemPrompts: SystemPrompt[]; +optional systemPrompts?: SystemPrompt[]; ``` -Defined in: [packages/ai/src/types.ts:900](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L900) +Defined in: [packages/ai/src/types.ts:925](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L925) System prompts to include with the request. @@ -306,10 +332,10 @@ SystemPrompt ### threadId? ```ts -optional threadId: string; +optional threadId?: string; ``` -Defined in: [packages/ai/src/types.ts:1001](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1001) +Defined in: [packages/ai/src/types.ts:1008](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1008) Thread ID for AG-UI protocol run correlation. When provided, this will be used in RunStartedEvent and RunFinishedEvent. @@ -319,7 +345,7 @@ When provided, this will be used in RunStartedEvent and RunFinishedEvent. ### tools? ```ts -optional tools: AnyTool[]; +optional tools?: AnyTool[]; ``` -Defined in: [packages/ai/src/types.ts:880](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L880) +Defined in: [packages/ai/src/types.ts:905](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L905) diff --git a/docs/reference/interfaces/TextPart.md b/docs/reference/interfaces/TextPart.md index 0de7eea0c5..7e4408579c 100644 --- a/docs/reference/interfaces/TextPart.md +++ b/docs/reference/interfaces/TextPart.md @@ -5,7 +5,7 @@ title: TextPart # Interface: TextPart\ -Defined in: [packages/ai/src/types.ts:364](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L364) +Defined in: [packages/ai/src/types.ts:389](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L389) Message parts - building blocks of UIMessage @@ -23,17 +23,17 @@ Message parts - building blocks of UIMessage content: string; ``` -Defined in: [packages/ai/src/types.ts:366](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L366) +Defined in: [packages/ai/src/types.ts:391](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L391) *** ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:367](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L367) +Defined in: [packages/ai/src/types.ts:392](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L392) *** @@ -43,4 +43,4 @@ Defined in: [packages/ai/src/types.ts:367](https://github.com/TanStack/ai/blob/m type: "text"; ``` -Defined in: [packages/ai/src/types.ts:365](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L365) +Defined in: [packages/ai/src/types.ts:390](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L390) diff --git a/docs/reference/interfaces/ThinkingPart.md b/docs/reference/interfaces/ThinkingPart.md index 514246b5e2..cdd8db3c87 100644 --- a/docs/reference/interfaces/ThinkingPart.md +++ b/docs/reference/interfaces/ThinkingPart.md @@ -5,7 +5,7 @@ title: ThinkingPart # Interface: ThinkingPart -Defined in: [packages/ai/src/types.ts:408](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L408) +Defined in: [packages/ai/src/types.ts:433](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L433) ## Properties @@ -15,27 +15,27 @@ Defined in: [packages/ai/src/types.ts:408](https://github.com/TanStack/ai/blob/m content: string; ``` -Defined in: [packages/ai/src/types.ts:410](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L410) +Defined in: [packages/ai/src/types.ts:435](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L435) *** ### signature? ```ts -optional signature: string; +optional signature?: string; ``` -Defined in: [packages/ai/src/types.ts:412](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L412) +Defined in: [packages/ai/src/types.ts:437](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L437) *** ### stepId? ```ts -optional stepId: string; +optional stepId?: string; ``` -Defined in: [packages/ai/src/types.ts:411](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L411) +Defined in: [packages/ai/src/types.ts:436](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L436) *** @@ -45,4 +45,4 @@ Defined in: [packages/ai/src/types.ts:411](https://github.com/TanStack/ai/blob/m type: "thinking"; ``` -Defined in: [packages/ai/src/types.ts:409](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L409) +Defined in: [packages/ai/src/types.ts:434](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L434) diff --git a/docs/reference/interfaces/Tool.md b/docs/reference/interfaces/Tool.md index e3abb86ecf..ef1ef0b05d 100644 --- a/docs/reference/interfaces/Tool.md +++ b/docs/reference/interfaces/Tool.md @@ -5,7 +5,7 @@ title: Tool # Interface: Tool\ -Defined in: [packages/ai/src/types.ts:598](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L598) +Defined in: [packages/ai/src/types.ts:623](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L623) Tool/Function definition for function calling. @@ -31,11 +31,11 @@ or plain JSON Schema objects for runtime validation and type safety. ### TInput -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = [`SchemaInput`](../type-aliases/SchemaInput.md) ### TOutput -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = [`SchemaInput`](../type-aliases/SchemaInput.md) ### TName @@ -53,7 +53,7 @@ or plain JSON Schema objects for runtime validation and type safety. description: string; ``` -Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622) +Defined in: [packages/ai/src/types.ts:647](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L647) Clear description of what the tool does. @@ -71,10 +71,10 @@ Be specific about what the tool does, what parameters it needs, and what it retu ### execute? ```ts -optional execute: ToolExecuteFunction; +optional execute?: ToolExecuteFunction; ``` -Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702) +Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727) Optional function to execute when the model calls this tool. @@ -85,6 +85,8 @@ Can return any value - will be automatically stringified if needed. #### Param +**args** + The arguments parsed from the model's tool call (validated against inputSchema) #### Returns @@ -105,10 +107,10 @@ execute: async (args) => { ### inputSchema? ```ts -optional inputSchema: TInput; +optional inputSchema?: TInput; ``` -Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662) +Defined in: [packages/ai/src/types.ts:687](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L687) Schema describing the tool's input parameters. @@ -159,10 +161,10 @@ type({ ### lazy? ```ts -optional lazy: boolean; +optional lazy?: boolean; ``` -Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) +Defined in: [packages/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L733) If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). @@ -171,10 +173,10 @@ If true, this tool is lazy and will only be sent to the LLM after being discover ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711) +Defined in: [packages/ai/src/types.ts:736](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L736) Additional metadata for adapters or custom extensions @@ -186,7 +188,7 @@ Additional metadata for adapters or custom extensions name: TName; ``` -Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612) +Defined in: [packages/ai/src/types.ts:637](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L637) Unique name of the tool (used by the model to call it). @@ -204,10 +206,10 @@ Must be unique within the tools array. ### needsApproval? ```ts -optional needsApproval: boolean; +optional needsApproval?: boolean; ``` -Defined in: [packages/ai/src/types.ts:705](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L705) +Defined in: [packages/ai/src/types.ts:730](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L730) If true, tool execution requires user approval before running. Works with both server and client tools. @@ -216,10 +218,10 @@ If true, tool execution requires user approval before running. Works with both s ### outputSchema? ```ts -optional outputSchema: TOutput; +optional outputSchema?: TOutput; ``` -Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683) +Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) Optional schema for validating tool output. diff --git a/docs/reference/interfaces/ToolCall.md b/docs/reference/interfaces/ToolCall.md index c658ba2264..9c952e6192 100644 --- a/docs/reference/interfaces/ToolCall.md +++ b/docs/reference/interfaces/ToolCall.md @@ -5,7 +5,7 @@ title: ToolCall # Interface: ToolCall\ -Defined in: [packages/ai/src/types.ts:150](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L150) +Defined in: [packages/ai/src/types.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L161) ## Type Parameters @@ -21,7 +21,7 @@ Defined in: [packages/ai/src/types.ts:150](https://github.com/TanStack/ai/blob/m function: object; ``` -Defined in: [packages/ai/src/types.ts:153](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L153) +Defined in: [packages/ai/src/types.ts:164](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L164) #### arguments @@ -43,17 +43,17 @@ name: string; id: string; ``` -Defined in: [packages/ai/src/types.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L151) +Defined in: [packages/ai/src/types.ts:162](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L162) *** ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:160](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L160) +Defined in: [packages/ai/src/types.ts:171](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L171) Provider-specific metadata to carry through the tool call lifecycle. Typed per-adapter via `TToolCallMetadata`. For example, @@ -67,4 +67,4 @@ Typed per-adapter via `TToolCallMetadata`. For example, type: "function"; ``` -Defined in: [packages/ai/src/types.ts:152](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L152) +Defined in: [packages/ai/src/types.ts:163](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L163) diff --git a/docs/reference/interfaces/ToolCallArgsEvent.md b/docs/reference/interfaces/ToolCallArgsEvent.md index 95ce6d107c..cfc47c4b1e 100644 --- a/docs/reference/interfaces/ToolCallArgsEvent.md +++ b/docs/reference/interfaces/ToolCallArgsEvent.md @@ -5,7 +5,7 @@ title: ToolCallArgsEvent # Interface: ToolCallArgsEvent -Defined in: [packages/ai/src/types.ts:1203](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1203) +Defined in: [packages/ai/src/types.ts:1245](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1245) Emitted when tool call arguments are streaming. @@ -27,10 +27,10 @@ TanStack AI adds: `model?`, `args?` (accumulated) ### args? ```ts -optional args: string; +optional args?: string; ``` -Defined in: [packages/ai/src/types.ts:1207](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1207) +Defined in: [packages/ai/src/types.ts:1249](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1249) Full accumulated arguments so far (TanStack AI internal) @@ -39,9 +39,9 @@ Full accumulated arguments so far (TanStack AI internal) ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1205](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1205) +Defined in: [packages/ai/src/types.ts:1247](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1247) Model identifier for multi-model support diff --git a/docs/reference/interfaces/ToolCallEndEvent.md b/docs/reference/interfaces/ToolCallEndEvent.md index 93be96c3f5..6f936477c5 100644 --- a/docs/reference/interfaces/ToolCallEndEvent.md +++ b/docs/reference/interfaces/ToolCallEndEvent.md @@ -3,34 +3,50 @@ id: ToolCallEndEvent title: ToolCallEndEvent --- -# Interface: ToolCallEndEvent +# Interface: ToolCallEndEvent\ -Defined in: [packages/ai/src/types.ts:1216](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1216) +Defined in: [packages/ai/src/types.ts:1264](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1264) Emitted when a tool call completes. @ag-ui/core provides: `toolCallId` -TanStack AI adds: `model?`, `toolCallName?`, `toolName?` (deprecated), `input?`, `result?` +TanStack AI adds: `model?`, `toolCallName?`, `toolName?` (deprecated), `input?`, `output?`, `result?` + +Same `Pick` (not `extends`) rationale as [ToolCallStartEvent](ToolCallStartEvent.md). ## Extends -- `ToolCallEndEvent` +- `Pick`\<`AGUIToolCallEndEvent`, `"toolCallId"` \| `"timestamp"` \| `"rawEvent"`\> -## Indexable +## Type Parameters -```ts -[k: string]: unknown -``` +### TToolName + +`TToolName` *extends* `string` = `string` + +Constrained tool name type. Defaults to `string` (untyped). + +### TInput + +`TInput` = `unknown` + +Constrained input arguments type. Defaults to `unknown`. + +### TOutput + +`TOutput` = `unknown` + +Constrained output type from the tool's `outputSchema`. Defaults to `unknown`. ## Properties ### input? ```ts -optional input: unknown; +optional input?: TInput; ``` -Defined in: [packages/ai/src/types.ts:1227](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1227) +Defined in: [packages/ai/src/types.ts:1280](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1280) Final parsed input arguments (TanStack AI internal) @@ -39,36 +55,51 @@ Final parsed input arguments (TanStack AI internal) ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1218](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1218) +Defined in: [packages/ai/src/types.ts:1271](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1271) Model identifier for multi-model support *** +### output? + +```ts +optional output?: TOutput; +``` + +Defined in: [packages/ai/src/types.ts:1287](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1287) + +Tool execution output, validated against the tool's `outputSchema` when +one is declared. Prefer this over parsing `result` when present. +Undefined for tools without execute, client tools pending approval, or +when execution throws. + +*** + ### result? ```ts -optional result: +optional result?: | string | ContentPart[]; ``` -Defined in: [packages/ai/src/types.ts:1229](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1229) +Defined in: [packages/ai/src/types.ts:1289](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1289) -Tool execution result (TanStack AI internal) +Tool execution result (TanStack AI internal / wire form) *** ### state? ```ts -optional state: ToolOutputState; +optional state?: ToolOutputState; ``` -Defined in: [packages/ai/src/types.ts:1231](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1231) +Defined in: [packages/ai/src/types.ts:1291](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1291) Tool execution output state (TanStack AI internal) @@ -77,24 +108,34 @@ Tool execution output state (TanStack AI internal) ### toolCallName? ```ts -optional toolCallName: string; +optional toolCallName?: TToolName; ``` -Defined in: [packages/ai/src/types.ts:1220](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1220) +Defined in: [packages/ai/src/types.ts:1273](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1273) -Name of the tool that completed +Name of the tool that completed (AG-UI-compatible optional field) *** ### ~~toolName?~~ ```ts -optional toolName: string; +optional toolName?: TToolName; ``` -Defined in: [packages/ai/src/types.ts:1225](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1225) +Defined in: [packages/ai/src/types.ts:1278](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1278) #### Deprecated Use `toolCallName` instead. Kept for backward compatibility. + +*** + +### type + +```ts +type: "TOOL_CALL_END"; +``` + +Defined in: [packages/ai/src/types.ts:1269](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1269) diff --git a/docs/reference/interfaces/ToolCallHookContext.md b/docs/reference/interfaces/ToolCallHookContext.md index 6032162645..bded15acb9 100644 --- a/docs/reference/interfaces/ToolCallHookContext.md +++ b/docs/reference/interfaces/ToolCallHookContext.md @@ -5,7 +5,7 @@ title: ToolCallHookContext # Interface: ToolCallHookContext -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:240](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L240) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:266](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L266) Context provided to tool call hooks (onBeforeToolCall / onAfterToolCall). @@ -17,7 +17,7 @@ Context provided to tool call hooks (onBeforeToolCall / onAfterToolCall). args: unknown; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:246](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L246) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:272](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L272) Parsed arguments for the tool call @@ -31,7 +31,7 @@ tool: | undefined; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:244](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L244) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:270](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L270) The resolved tool definition, if found @@ -43,7 +43,7 @@ The resolved tool definition, if found toolCall: ToolCall; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:242](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L242) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:268](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L268) The tool call being executed @@ -55,7 +55,7 @@ The tool call being executed toolCallId: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:250](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L250) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:276](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L276) ID of the tool call @@ -67,6 +67,6 @@ ID of the tool call toolName: string; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:248](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L248) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:274](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L274) Name of the tool diff --git a/docs/reference/interfaces/ToolCallPart.md b/docs/reference/interfaces/ToolCallPart.md index 08149e2562..4f2e67e7a9 100644 --- a/docs/reference/interfaces/ToolCallPart.md +++ b/docs/reference/interfaces/ToolCallPart.md @@ -5,7 +5,7 @@ title: ToolCallPart # Interface: ToolCallPart\ -Defined in: [packages/ai/src/types.ts:370](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L370) +Defined in: [packages/ai/src/types.ts:395](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L395) ## Type Parameters @@ -18,17 +18,17 @@ Defined in: [packages/ai/src/types.ts:370](https://github.com/TanStack/ai/blob/m ### approval? ```ts -optional approval: object; +optional approval?: object; ``` -Defined in: [packages/ai/src/types.ts:386](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L386) +Defined in: [packages/ai/src/types.ts:411](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L411) Approval metadata if tool requires user approval #### approved? ```ts -optional approved: boolean; +optional approved?: boolean; ``` #### id @@ -51,7 +51,7 @@ needsApproval: boolean; arguments: string; ``` -Defined in: [packages/ai/src/types.ts:374](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L374) +Defined in: [packages/ai/src/types.ts:399](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L399) *** @@ -61,17 +61,17 @@ Defined in: [packages/ai/src/types.ts:374](https://github.com/TanStack/ai/blob/m id: string; ``` -Defined in: [packages/ai/src/types.ts:372](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L372) +Defined in: [packages/ai/src/types.ts:397](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L397) *** ### input? ```ts -optional input: unknown; +optional input?: unknown; ``` -Defined in: [packages/ai/src/types.ts:383](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L383) +Defined in: [packages/ai/src/types.ts:408](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L408) Parsed tool input. Set from the parsed arguments once they are complete (`state: 'input-complete'` and later). `undefined` while the raw @@ -85,10 +85,10 @@ available as a fallback. Typed per-tool on the client `ToolCallPart` (see ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:397](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L397) +Defined in: [packages/ai/src/types.ts:422](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L422) Provider-specific metadata that round-trips with the tool call. Typed per-adapter via `TToolCallMetadata`. May follow the @@ -103,17 +103,17 @@ server tools (e.g. Anthropic `web_search`). name: string; ``` -Defined in: [packages/ai/src/types.ts:373](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L373) +Defined in: [packages/ai/src/types.ts:398](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L398) *** ### output? ```ts -optional output: any; +optional output?: any; ``` -Defined in: [packages/ai/src/types.ts:392](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L392) +Defined in: [packages/ai/src/types.ts:417](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L417) Tool execution output (for client tools or after approval) @@ -125,7 +125,7 @@ Tool execution output (for client tools or after approval) state: ToolCallState; ``` -Defined in: [packages/ai/src/types.ts:384](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L384) +Defined in: [packages/ai/src/types.ts:409](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L409) *** @@ -135,4 +135,4 @@ Defined in: [packages/ai/src/types.ts:384](https://github.com/TanStack/ai/blob/m type: "tool-call"; ``` -Defined in: [packages/ai/src/types.ts:371](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L371) +Defined in: [packages/ai/src/types.ts:396](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L396) diff --git a/docs/reference/interfaces/ToolCallResultEvent.md b/docs/reference/interfaces/ToolCallResultEvent.md index cc6e344df7..e96fb428ba 100644 --- a/docs/reference/interfaces/ToolCallResultEvent.md +++ b/docs/reference/interfaces/ToolCallResultEvent.md @@ -5,7 +5,7 @@ title: ToolCallResultEvent # Interface: ToolCallResultEvent -Defined in: [packages/ai/src/types.ts:1240](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1240) +Defined in: [packages/ai/src/types.ts:1300](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1300) Emitted when a tool call result is available. @@ -27,10 +27,10 @@ TanStack AI adds: `model?` ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1242](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1242) +Defined in: [packages/ai/src/types.ts:1302](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1302) Model identifier for multi-model support @@ -39,9 +39,9 @@ Model identifier for multi-model support ### state? ```ts -optional state: ToolOutputState; +optional state?: ToolOutputState; ``` -Defined in: [packages/ai/src/types.ts:1244](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1244) +Defined in: [packages/ai/src/types.ts:1304](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1304) Tool execution output state (TanStack AI internal) diff --git a/docs/reference/interfaces/ToolCallStartEvent.md b/docs/reference/interfaces/ToolCallStartEvent.md index 0aa2b66932..40e2576336 100644 --- a/docs/reference/interfaces/ToolCallStartEvent.md +++ b/docs/reference/interfaces/ToolCallStartEvent.md @@ -3,34 +3,47 @@ id: ToolCallStartEvent title: ToolCallStartEvent --- -# Interface: ToolCallStartEvent +# Interface: ToolCallStartEvent\ -Defined in: [packages/ai/src/types.ts:1180](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1180) +Defined in: [packages/ai/src/types.ts:1213](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1213) Emitted when a tool call starts. @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?` TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `metadata?` +Field shapes are taken from AG-UI via `Pick` (not `extends`) so Zod +`.passthrough()` index signatures do not pollute the StreamChunk +discriminated union — required for [TypedStreamChunk](../type-aliases/TypedStreamChunk.md) narrowing. + ## Extends -- `ToolCallStartEvent` +- `Pick`\<`AGUIToolCallStartEvent`, + \| `"toolCallId"` + \| `"toolCallName"` + \| `"parentMessageId"` + \| `"timestamp"` + \| `"rawEvent"`\> -## Indexable +## Type Parameters -```ts -[k: string]: unknown -``` +### TToolName + +`TToolName` *extends* `string` = `string` + +Constrained tool name type. Defaults to `string` (untyped). + When the stream is returned from `chat()` with typed tools, `TypedStreamChunk` + intersects a literal onto `toolCallName` and `toolName` for discrimination. ## Properties ### index? ```ts -optional index: number; +optional index?: number; ``` -Defined in: [packages/ai/src/types.ts:1189](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1189) +Defined in: [packages/ai/src/types.ts:1231](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1231) Index for parallel tool calls @@ -39,10 +52,10 @@ Index for parallel tool calls ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:1194](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1194) +Defined in: [packages/ai/src/types.ts:1236](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1236) Provider-specific metadata to carry into the ToolCall. Untyped at the event layer because events flow through a discriminated @@ -54,10 +67,10 @@ union that does not survive generics; adapters cast it to their typed ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1182](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1182) +Defined in: [packages/ai/src/types.ts:1221](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1221) Model identifier for multi-model support @@ -66,12 +79,25 @@ Model identifier for multi-model support ### ~~toolName~~ ```ts -toolName: string; +toolName: TToolName; ``` -Defined in: [packages/ai/src/types.ts:1187](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1187) +Defined in: [packages/ai/src/types.ts:1229](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1229) #### Deprecated Use `toolCallName` instead (from @ag-ui/core spec). Kept for backward compatibility. + +Carries `TToolName` on the base interface; for `toolCallName` narrowing use +[TypedStreamChunk](../type-aliases/TypedStreamChunk.md) (distributed variants intersect the AG-UI field). + +*** + +### type + +```ts +type: "TOOL_CALL_START"; +``` + +Defined in: [packages/ai/src/types.ts:1219](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1219) diff --git a/docs/reference/interfaces/ToolConfig.md b/docs/reference/interfaces/ToolConfig.md index 56bd87b964..e7ce55bf5c 100644 --- a/docs/reference/interfaces/ToolConfig.md +++ b/docs/reference/interfaces/ToolConfig.md @@ -5,7 +5,7 @@ title: ToolConfig # Interface: ToolConfig -Defined in: [packages/ai/src/types.ts:734](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L734) +Defined in: [packages/ai/src/types.ts:759](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L759) ## Indexable diff --git a/docs/reference/interfaces/ToolDefinition.md b/docs/reference/interfaces/ToolDefinition.md index 1ed6346e75..1ae11d4ed2 100644 --- a/docs/reference/interfaces/ToolDefinition.md +++ b/docs/reference/interfaces/ToolDefinition.md @@ -3,25 +3,25 @@ id: ToolDefinition title: ToolDefinition --- -# Interface: ToolDefinition\ +# Interface: ToolDefinition\ -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:125](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L125) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:229](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L229) Tool definition builder that allows creating server or client tools from a shared definition ## Extends -- [`ToolDefinitionInstance`](ToolDefinitionInstance.md)\<`TInput`, `TOutput`, `TName`, `unknown`, `TNeedsApproval`\> +- [`ToolDefinitionInstance`](ToolDefinitionInstance.md)\<`TInput`, `TOutput`, `TName`, `unknown`, `TNeedsApproval`, `TApprovalSchema`\> ## Type Parameters ### TInput -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TOutput -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TName @@ -31,6 +31,12 @@ Tool definition builder that allows creating server or client tools from a share `TNeedsApproval` *extends* `boolean` = `false` +### TApprovalSchema + +`TApprovalSchema` *extends* + \| [`ApprovalSchemaConfig`](../type-aliases/ApprovalSchemaConfig.md) + \| `undefined` = `undefined` + ## Properties ### \_\_toolSide @@ -39,7 +45,7 @@ Tool definition builder that allows creating server or client tools from a share __toolSide: "definition"; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:60](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L60) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:154](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L154) #### Inherited from @@ -47,13 +53,53 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:60](https: *** -### client() +### \[toolApprovalCapability\]? + +```ts +readonly optional [toolApprovalCapability]?: object; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L161) + +#### approvalSchema + +```ts +approvalSchema: TApprovalSchema; +``` + +#### needsApproval + +```ts +needsApproval: TNeedsApproval; +``` + +#### Inherited from + +[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`[toolApprovalCapability]`](ToolDefinitionInstance.md#toolapprovalcapability) + +*** + +### approvalSchema + +```ts +approvalSchema: TApprovalSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:160](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L160) + +#### Inherited from + +[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`approvalSchema`](ToolDefinitionInstance.md#approvalschema) + +*** + +### client ```ts -client: (execute?) => ClientTool; +client: (execute?) => ClientTool & BuiltToolSchemaFields; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:149](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L149) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:263](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L263) Create a client-side tool with optional execute function. Carries the definition's `needsApproval` literal through to the client @@ -73,7 +119,7 @@ tool so the tool-call part's `approval` field stays gated on it. #### Returns -[`ClientTool`](ClientTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`, `TNeedsApproval`\> +[`ClientTool`](ClientTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`, `TNeedsApproval`, `TApprovalSchema`\> & `BuiltToolSchemaFields`\<`TInput`, `TOutput`, `TApprovalSchema`\> *** @@ -83,7 +129,7 @@ tool so the tool-call part's `approval` field stays gated on it. description: string; ``` -Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622) +Defined in: [packages/ai/src/types.ts:647](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L647) Clear description of what the tool does. @@ -102,15 +148,15 @@ Be specific about what the tool does, what parameters it needs, and what it retu *** -### execute()? +### execute? ```ts -optional execute: (args, context?) => +optional execute?: (args, context?) => | InferSchemaType | Promise>; ``` -Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702) +Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727) Optional function to execute when the model calls this tool. @@ -153,13 +199,13 @@ execute: async (args) => { *** -### inputSchema? +### inputSchema ```ts -optional inputSchema: TInput; +inputSchema: TInput; ``` -Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:157](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L157) Schema describing the tool's input parameters. @@ -214,10 +260,10 @@ type({ ### lazy? ```ts -optional lazy: boolean; +optional lazy?: boolean; ``` -Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) +Defined in: [packages/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L733) If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). @@ -230,10 +276,10 @@ If true, this tool is lazy and will only be sent to the LLM after being discover ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711) +Defined in: [packages/ai/src/types.ts:736](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L736) Additional metadata for adapters or custom extensions @@ -249,7 +295,7 @@ Additional metadata for adapters or custom extensions name: TName; ``` -Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612) +Defined in: [packages/ai/src/types.ts:637](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L637) Unique name of the tool (used by the model to call it). @@ -271,10 +317,10 @@ Must be unique within the tools array. ### needsApproval? ```ts -optional needsApproval: TNeedsApproval; +optional needsApproval?: TNeedsApproval; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:63](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L63) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:159](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L159) If true, tool execution requires user approval before running. Works with both server and client tools. @@ -284,13 +330,13 @@ If true, tool execution requires user approval before running. Works with both s *** -### outputSchema? +### outputSchema ```ts -optional outputSchema: TOutput; +outputSchema: TOutput; ``` -Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:158](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L158) Optional schema for validating tool output. @@ -319,13 +365,13 @@ z.object({ *** -### server() +### server ```ts -server: (execute) => ServerTool; +server: (execute) => ServerTool & BuiltToolSchemaFields; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:140](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L140) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:246](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L246) Create a server-side tool with execute function @@ -343,4 +389,4 @@ Create a server-side tool with execute function #### Returns -[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`\> +[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`, `TNeedsApproval`, `TApprovalSchema`\> & `BuiltToolSchemaFields`\<`TInput`, `TOutput`, `TApprovalSchema`\> diff --git a/docs/reference/interfaces/ToolDefinitionConfig.md b/docs/reference/interfaces/ToolDefinitionConfig.md deleted file mode 100644 index f5d8186f9a..0000000000 --- a/docs/reference/interfaces/ToolDefinitionConfig.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -id: ToolDefinitionConfig -title: ToolDefinitionConfig ---- - -# Interface: ToolDefinitionConfig\ - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L107) - -Tool definition configuration - -## Type Parameters - -### TInput - -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) - -### TOutput - -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) - -### TName - -`TName` *extends* `string` = `string` - -### TNeedsApproval - -`TNeedsApproval` *extends* `boolean` = `false` - -## Properties - -### description - -```ts -description: string; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:114](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L114) - -*** - -### inputSchema? - -```ts -optional inputSchema: TInput; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:115](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L115) - -*** - -### lazy? - -```ts -optional lazy: boolean; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:118](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L118) - -*** - -### metadata? - -```ts -optional metadata: Record; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L119) - -*** - -### name - -```ts -name: TName; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:113](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L113) - -*** - -### needsApproval? - -```ts -optional needsApproval: TNeedsApproval; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:117](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L117) - -*** - -### outputSchema? - -```ts -optional outputSchema: TOutput; -``` - -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:116](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L116) diff --git a/docs/reference/interfaces/ToolDefinitionInstance.md b/docs/reference/interfaces/ToolDefinitionInstance.md index 9d9a608811..300beb4a1c 100644 --- a/docs/reference/interfaces/ToolDefinitionInstance.md +++ b/docs/reference/interfaces/ToolDefinitionInstance.md @@ -3,9 +3,9 @@ id: ToolDefinitionInstance title: ToolDefinitionInstance --- -# Interface: ToolDefinitionInstance\ +# Interface: ToolDefinitionInstance\ -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:53](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L53) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:146](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L146) Tool definition that can be used directly or instantiated for server/client @@ -21,11 +21,11 @@ Tool definition that can be used directly or instantiated for server/client ### TInput -`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TOutput -`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) \| `undefined` = `undefined` ### TName @@ -39,6 +39,12 @@ Tool definition that can be used directly or instantiated for server/client `TNeedsApproval` *extends* `boolean` = `false` +### TApprovalSchema + +`TApprovalSchema` *extends* + \| [`ApprovalSchemaConfig`](../type-aliases/ApprovalSchemaConfig.md) + \| `undefined` = `undefined` + ## Properties ### \_\_toolSide @@ -47,7 +53,39 @@ Tool definition that can be used directly or instantiated for server/client __toolSide: "definition"; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:60](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L60) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:154](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L154) + +*** + +### \[toolApprovalCapability\]? + +```ts +readonly optional [toolApprovalCapability]?: object; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L161) + +#### approvalSchema + +```ts +approvalSchema: TApprovalSchema; +``` + +#### needsApproval + +```ts +needsApproval: TNeedsApproval; +``` + +*** + +### approvalSchema + +```ts +approvalSchema: TApprovalSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:160](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L160) *** @@ -57,7 +95,7 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:60](https: description: string; ``` -Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622) +Defined in: [packages/ai/src/types.ts:647](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L647) Clear description of what the tool does. @@ -79,10 +117,10 @@ Be specific about what the tool does, what parameters it needs, and what it retu ### execute? ```ts -optional execute: ToolExecuteFunction; +optional execute?: ToolExecuteFunction; ``` -Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702) +Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727) Optional function to execute when the model calls this tool. @@ -93,6 +131,8 @@ Can return any value - will be automatically stringified if needed. #### Param +**args** + The arguments parsed from the model's tool call (validated against inputSchema) #### Returns @@ -114,13 +154,13 @@ execute: async (args) => { *** -### inputSchema? +### inputSchema ```ts -optional inputSchema: TInput; +inputSchema: TInput; ``` -Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:157](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L157) Schema describing the tool's input parameters. @@ -166,7 +206,7 @@ type({ } ``` -#### Inherited from +#### Overrides [`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema) @@ -175,10 +215,10 @@ type({ ### lazy? ```ts -optional lazy: boolean; +optional lazy?: boolean; ``` -Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708) +Defined in: [packages/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L733) If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). @@ -191,10 +231,10 @@ If true, this tool is lazy and will only be sent to the LLM after being discover ### metadata? ```ts -optional metadata: Record; +optional metadata?: Record; ``` -Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711) +Defined in: [packages/ai/src/types.ts:736](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L736) Additional metadata for adapters or custom extensions @@ -210,7 +250,7 @@ Additional metadata for adapters or custom extensions name: TName; ``` -Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612) +Defined in: [packages/ai/src/types.ts:637](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L637) Unique name of the tool (used by the model to call it). @@ -232,10 +272,10 @@ Must be unique within the tools array. ### needsApproval? ```ts -optional needsApproval: TNeedsApproval; +optional needsApproval?: TNeedsApproval; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:63](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L63) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:159](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L159) If true, tool execution requires user approval before running. Works with both server and client tools. @@ -245,13 +285,13 @@ If true, tool execution requires user approval before running. Works with both s *** -### outputSchema? +### outputSchema ```ts -optional outputSchema: TOutput; +outputSchema: TOutput; ``` -Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:158](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L158) Optional schema for validating tool output. @@ -274,6 +314,6 @@ z.object({ }) ``` -#### Inherited from +#### Overrides [`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema) diff --git a/docs/reference/interfaces/ToolInputAvailableEvent.md b/docs/reference/interfaces/ToolInputAvailableEvent.md index 2f19f9ff77..4fc136b63d 100644 --- a/docs/reference/interfaces/ToolInputAvailableEvent.md +++ b/docs/reference/interfaces/ToolInputAvailableEvent.md @@ -3,34 +3,28 @@ id: ToolInputAvailableEvent title: ToolInputAvailableEvent --- -# Interface: ToolInputAvailableEvent +# ~~Interface: ToolInputAvailableEvent~~ -Defined in: [packages/ai/src/types.ts:1403](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1403) +Defined in: [packages/ai/src/types.ts:1487](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1487) -Emitted when a client tool is invoked. The agent loop yields this and -pauses to let the caller run the tool client-side — `structured-output.complete` -will not fire for that run. Shape fixed by the agent-loop forwarding in -`runStreamingStructuredOutputImpl` in `activities/chat/index.ts`. +## Deprecated + +Native interrupts use RUN_FINISHED interrupt outcomes. This +compatibility event remains readable until 1.0. ## Extends - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties -### model? +### ~~model?~~ ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -40,13 +34,13 @@ Model identifier for multi-model support *** -### name +### ~~name~~ ```ts name: "tool-input-available"; ``` -Defined in: [packages/ai/src/types.ts:1404](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1404) +Defined in: [packages/ai/src/types.ts:1488](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1488) #### Overrides @@ -56,27 +50,74 @@ CustomEvent.name *** -### value +### ~~runId?~~ ```ts -value: object; +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### ~~threadId?~~ + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### ~~type~~ + +```ts +type: "CUSTOM"; ``` Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) -#### input +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + +### ~~value~~ + +```ts +value: object; +``` + +Defined in: [packages/ai/src/types.ts:1489](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1489) + +#### ~~input~~ ```ts input: unknown; ``` -#### toolCallId +#### ~~toolCallId~~ ```ts toolCallId: string; ``` -#### toolName +#### ~~toolName~~ ```ts toolName: string; diff --git a/docs/reference/interfaces/ToolPhaseCompleteInfo.md b/docs/reference/interfaces/ToolPhaseCompleteInfo.md index 5823a5c547..b380a0ac90 100644 --- a/docs/reference/interfaces/ToolPhaseCompleteInfo.md +++ b/docs/reference/interfaces/ToolPhaseCompleteInfo.md @@ -5,7 +5,7 @@ title: ToolPhaseCompleteInfo # Interface: ToolPhaseCompleteInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:311](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L311) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:337](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L337) Aggregate information passed to onToolPhaseComplete after all tool calls in an iteration have been processed. @@ -18,7 +18,7 @@ in an iteration have been processed. needsApproval: object[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:322](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L322) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:348](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L348) Tools that need user approval @@ -54,7 +54,7 @@ toolName: string; needsClientExecution: object[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:329](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L329) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:355](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L355) Tools that need client-side execution @@ -84,14 +84,14 @@ toolName: string; results: object[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:315](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L315) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:341](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L341) Completed tool results #### duration? ```ts -optional duration: number; +optional duration?: number; ``` #### result @@ -120,6 +120,6 @@ toolName: string; toolCalls: ToolCall[]; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:313](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L313) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:339](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L339) Tool calls that were assigned to the assistant message diff --git a/docs/reference/interfaces/ToolRegistry.md b/docs/reference/interfaces/ToolRegistry.md index bc684ecb07..9e5865926c 100644 --- a/docs/reference/interfaces/ToolRegistry.md +++ b/docs/reference/interfaces/ToolRegistry.md @@ -20,7 +20,7 @@ or frozen (static tool list, for backward compatibility with tools arrays). ## Properties -### add() +### add ```ts add: (tool) => void; @@ -45,7 +45,7 @@ The tool to add *** -### get() +### get ```ts get: (name) => TTool | undefined; @@ -71,7 +71,7 @@ The tool if found, undefined otherwise *** -### getTools() +### getTools ```ts getTools: () => TTool[]; @@ -88,7 +88,7 @@ Called each agent loop iteration to get the latest tool list. *** -### has() +### has ```ts has: (name) => boolean; @@ -125,7 +125,7 @@ Frozen registries don't allow add/remove operations. *** -### remove() +### remove ```ts remove: (name) => boolean; diff --git a/docs/reference/interfaces/ToolResultPart.md b/docs/reference/interfaces/ToolResultPart.md index 3df1ebd845..6c1514adf2 100644 --- a/docs/reference/interfaces/ToolResultPart.md +++ b/docs/reference/interfaces/ToolResultPart.md @@ -5,7 +5,7 @@ title: ToolResultPart # Interface: ToolResultPart -Defined in: [packages/ai/src/types.ts:400](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L400) +Defined in: [packages/ai/src/types.ts:425](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L425) ## Properties @@ -17,17 +17,17 @@ content: | ContentPart[]; ``` -Defined in: [packages/ai/src/types.ts:403](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L403) +Defined in: [packages/ai/src/types.ts:428](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L428) *** ### error? ```ts -optional error: string; +optional error?: string; ``` -Defined in: [packages/ai/src/types.ts:405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L405) +Defined in: [packages/ai/src/types.ts:430](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L430) *** @@ -37,7 +37,7 @@ Defined in: [packages/ai/src/types.ts:405](https://github.com/TanStack/ai/blob/m state: ToolResultState; ``` -Defined in: [packages/ai/src/types.ts:404](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L404) +Defined in: [packages/ai/src/types.ts:429](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L429) *** @@ -47,7 +47,7 @@ Defined in: [packages/ai/src/types.ts:404](https://github.com/TanStack/ai/blob/m toolCallId: string; ``` -Defined in: [packages/ai/src/types.ts:402](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L402) +Defined in: [packages/ai/src/types.ts:427](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L427) *** @@ -57,4 +57,4 @@ Defined in: [packages/ai/src/types.ts:402](https://github.com/TanStack/ai/blob/m type: "tool-result"; ``` -Defined in: [packages/ai/src/types.ts:401](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L401) +Defined in: [packages/ai/src/types.ts:426](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L426) diff --git a/docs/reference/interfaces/TranscriptionAdapter.md b/docs/reference/interfaces/TranscriptionAdapter.md index 4b3088d2c9..25a6bd5271 100644 --- a/docs/reference/interfaces/TranscriptionAdapter.md +++ b/docs/reference/interfaces/TranscriptionAdapter.md @@ -84,7 +84,7 @@ Adapter name identifier *** -### transcribe() +### transcribe ```ts transcribe: (options) => Promise; diff --git a/docs/reference/interfaces/TranscriptionOptions.md b/docs/reference/interfaces/TranscriptionOptions.md index 6ed85414d5..ff6a4d6a5b 100644 --- a/docs/reference/interfaces/TranscriptionOptions.md +++ b/docs/reference/interfaces/TranscriptionOptions.md @@ -5,7 +5,7 @@ title: TranscriptionOptions # Interface: TranscriptionOptions\ -Defined in: [packages/ai/src/types.ts:2080](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2080) +Defined in: [packages/ai/src/types.ts:2538](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2538) ## Type Parameters @@ -15,13 +15,27 @@ Defined in: [packages/ai/src/types.ts:2080](https://github.com/TanStack/ai/blob/ ## Properties +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2564](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2564) + +Effective abort signal composed by the activity from caller `abortSignal` +and/or `timeout`. Adapters should forward this to the provider SDK when +supported. Request-specific — never store on a global client config. + +*** + ### audio ```ts -audio: string | File | Blob | ArrayBuffer; +audio: string | ArrayBuffer | File | Blob; ``` -Defined in: [packages/ai/src/types.ts:2086](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2086) +Defined in: [packages/ai/src/types.ts:2544](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2544) The audio data to transcribe - can be base64 string, File, Blob, or Buffer @@ -30,10 +44,10 @@ The audio data to transcribe - can be base64 string, File, Blob, or Buffer ### language? ```ts -optional language: string; +optional language?: string; ``` -Defined in: [packages/ai/src/types.ts:2088](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2088) +Defined in: [packages/ai/src/types.ts:2546](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2546) The language of the audio in ISO-639-1 format (e.g., 'en') @@ -45,7 +59,7 @@ The language of the audio in ISO-639-1 format (e.g., 'en') logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:2100](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2100) +Defined in: [packages/ai/src/types.ts:2558](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2558) Internal logger threaded from the generateTranscription() entry point. Adapters must call logger.request() before the SDK call and logger.errors() @@ -59,7 +73,7 @@ in catch blocks. model: string; ``` -Defined in: [packages/ai/src/types.ts:2084](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2084) +Defined in: [packages/ai/src/types.ts:2542](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2542) The model to use for transcription @@ -68,10 +82,10 @@ The model to use for transcription ### modelOptions? ```ts -optional modelOptions: TProviderOptions; +optional modelOptions?: TProviderOptions; ``` -Defined in: [packages/ai/src/types.ts:2094](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2094) +Defined in: [packages/ai/src/types.ts:2552](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2552) Model-specific options for transcription @@ -80,10 +94,10 @@ Model-specific options for transcription ### prompt? ```ts -optional prompt: string; +optional prompt?: string; ``` -Defined in: [packages/ai/src/types.ts:2090](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2090) +Defined in: [packages/ai/src/types.ts:2548](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2548) An optional prompt to guide the transcription @@ -92,9 +106,9 @@ An optional prompt to guide the transcription ### responseFormat? ```ts -optional responseFormat: TranscriptionResponseFormat; +optional responseFormat?: TranscriptionResponseFormat; ``` -Defined in: [packages/ai/src/types.ts:2092](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2092) +Defined in: [packages/ai/src/types.ts:2550](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2550) The format of the transcription output diff --git a/docs/reference/interfaces/TranscriptionResult.md b/docs/reference/interfaces/TranscriptionResult.md index 9829d088da..5cb7e5167e 100644 --- a/docs/reference/interfaces/TranscriptionResult.md +++ b/docs/reference/interfaces/TranscriptionResult.md @@ -5,19 +5,31 @@ title: TranscriptionResult # Interface: TranscriptionResult -Defined in: [packages/ai/src/types.ts:2136](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2136) +Defined in: [packages/ai/src/types.ts:2600](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2600) Result of audio transcription. ## Properties +### artifacts? + +```ts +optional artifacts?: PersistedArtifactRef[]; +``` + +Defined in: [packages/ai/src/types.ts:2618](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2618) + +Persisted artifact references for generated assets, when available + +*** + ### duration? ```ts -optional duration: number; +optional duration?: number; ``` -Defined in: [packages/ai/src/types.ts:2146](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2146) +Defined in: [packages/ai/src/types.ts:2610](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2610) Duration of the audio in seconds @@ -29,7 +41,7 @@ Duration of the audio in seconds id: string; ``` -Defined in: [packages/ai/src/types.ts:2138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2138) +Defined in: [packages/ai/src/types.ts:2602](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2602) Unique identifier for the transcription @@ -38,10 +50,10 @@ Unique identifier for the transcription ### language? ```ts -optional language: string; +optional language?: string; ``` -Defined in: [packages/ai/src/types.ts:2144](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2144) +Defined in: [packages/ai/src/types.ts:2608](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2608) Language detected or specified @@ -53,7 +65,7 @@ Language detected or specified model: string; ``` -Defined in: [packages/ai/src/types.ts:2140](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2140) +Defined in: [packages/ai/src/types.ts:2604](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2604) Model used for transcription @@ -62,10 +74,10 @@ Model used for transcription ### segments? ```ts -optional segments: TranscriptionSegment[]; +optional segments?: TranscriptionSegment[]; ``` -Defined in: [packages/ai/src/types.ts:2148](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2148) +Defined in: [packages/ai/src/types.ts:2612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2612) Detailed segments with timing, if available @@ -77,7 +89,7 @@ Detailed segments with timing, if available text: string; ``` -Defined in: [packages/ai/src/types.ts:2142](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2142) +Defined in: [packages/ai/src/types.ts:2606](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2606) The full transcribed text @@ -86,10 +98,10 @@ The full transcribed text ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:2152](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2152) +Defined in: [packages/ai/src/types.ts:2616](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2616) Token usage information (if provided by the adapter) @@ -98,9 +110,9 @@ Token usage information (if provided by the adapter) ### words? ```ts -optional words: TranscriptionWord[]; +optional words?: TranscriptionWord[]; ``` -Defined in: [packages/ai/src/types.ts:2150](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2150) +Defined in: [packages/ai/src/types.ts:2614](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2614) Word-level timestamps, if available diff --git a/docs/reference/interfaces/TranscriptionSegment.md b/docs/reference/interfaces/TranscriptionSegment.md index a98bde067c..71902d1dc5 100644 --- a/docs/reference/interfaces/TranscriptionSegment.md +++ b/docs/reference/interfaces/TranscriptionSegment.md @@ -5,7 +5,7 @@ title: TranscriptionSegment # Interface: TranscriptionSegment -Defined in: [packages/ai/src/types.ts:2106](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2106) +Defined in: [packages/ai/src/types.ts:2570](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2570) A single segment of transcribed audio with timing information. @@ -14,10 +14,10 @@ A single segment of transcribed audio with timing information. ### confidence? ```ts -optional confidence: number; +optional confidence?: number; ``` -Defined in: [packages/ai/src/types.ts:2116](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2116) +Defined in: [packages/ai/src/types.ts:2580](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2580) Confidence score (0-1), if available @@ -29,7 +29,7 @@ Confidence score (0-1), if available end: number; ``` -Defined in: [packages/ai/src/types.ts:2112](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2112) +Defined in: [packages/ai/src/types.ts:2576](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2576) End time of the segment in seconds @@ -41,7 +41,7 @@ End time of the segment in seconds id: number; ``` -Defined in: [packages/ai/src/types.ts:2108](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2108) +Defined in: [packages/ai/src/types.ts:2572](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2572) Unique identifier for the segment @@ -50,10 +50,10 @@ Unique identifier for the segment ### speaker? ```ts -optional speaker: string; +optional speaker?: string; ``` -Defined in: [packages/ai/src/types.ts:2118](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2118) +Defined in: [packages/ai/src/types.ts:2582](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2582) Speaker identifier, if diarization is enabled @@ -65,7 +65,7 @@ Speaker identifier, if diarization is enabled start: number; ``` -Defined in: [packages/ai/src/types.ts:2110](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2110) +Defined in: [packages/ai/src/types.ts:2574](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2574) Start time of the segment in seconds @@ -77,6 +77,6 @@ Start time of the segment in seconds text: string; ``` -Defined in: [packages/ai/src/types.ts:2114](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2114) +Defined in: [packages/ai/src/types.ts:2578](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2578) Transcribed text for this segment diff --git a/docs/reference/interfaces/TranscriptionWord.md b/docs/reference/interfaces/TranscriptionWord.md index 5f1cd3e426..4e8db86542 100644 --- a/docs/reference/interfaces/TranscriptionWord.md +++ b/docs/reference/interfaces/TranscriptionWord.md @@ -5,7 +5,7 @@ title: TranscriptionWord # Interface: TranscriptionWord -Defined in: [packages/ai/src/types.ts:2124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2124) +Defined in: [packages/ai/src/types.ts:2588](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2588) A single word with timing information. @@ -17,7 +17,7 @@ A single word with timing information. end: number; ``` -Defined in: [packages/ai/src/types.ts:2130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2130) +Defined in: [packages/ai/src/types.ts:2594](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2594) End time in seconds @@ -29,7 +29,7 @@ End time in seconds start: number; ``` -Defined in: [packages/ai/src/types.ts:2128](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2128) +Defined in: [packages/ai/src/types.ts:2592](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2592) Start time in seconds @@ -41,6 +41,6 @@ Start time in seconds word: string; ``` -Defined in: [packages/ai/src/types.ts:2126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2126) +Defined in: [packages/ai/src/types.ts:2590](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2590) The transcribed word diff --git a/docs/reference/interfaces/UIMessage.md b/docs/reference/interfaces/UIMessage.md index dd4c820d13..e4912cffe3 100644 --- a/docs/reference/interfaces/UIMessage.md +++ b/docs/reference/interfaces/UIMessage.md @@ -5,7 +5,7 @@ title: UIMessage # Interface: UIMessage\ -Defined in: [packages/ai/src/types.ts:487](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L487) +Defined in: [packages/ai/src/types.ts:512](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L512) UIMessage - Domain-specific message format optimized for building chat UIs Contains parts that can be text, tool calls, or tool results. Generic over @@ -24,10 +24,10 @@ consumer side without manual casts. ### createdAt? ```ts -optional createdAt: Date; +optional createdAt?: Date; ``` -Defined in: [packages/ai/src/types.ts:491](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L491) +Defined in: [packages/ai/src/types.ts:516](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L516) *** @@ -37,7 +37,7 @@ Defined in: [packages/ai/src/types.ts:491](https://github.com/TanStack/ai/blob/m id: string; ``` -Defined in: [packages/ai/src/types.ts:488](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L488) +Defined in: [packages/ai/src/types.ts:513](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L513) *** @@ -47,7 +47,7 @@ Defined in: [packages/ai/src/types.ts:488](https://github.com/TanStack/ai/blob/m parts: MessagePart[]; ``` -Defined in: [packages/ai/src/types.ts:490](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L490) +Defined in: [packages/ai/src/types.ts:515](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L515) *** @@ -57,4 +57,4 @@ Defined in: [packages/ai/src/types.ts:490](https://github.com/TanStack/ai/blob/m role: "user" | "assistant" | "system"; ``` -Defined in: [packages/ai/src/types.ts:489](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L489) +Defined in: [packages/ai/src/types.ts:514](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L514) diff --git a/docs/reference/interfaces/UIResourceEvent.md b/docs/reference/interfaces/UIResourceEvent.md index c794db0c61..b15e302330 100644 --- a/docs/reference/interfaces/UIResourceEvent.md +++ b/docs/reference/interfaces/UIResourceEvent.md @@ -5,7 +5,7 @@ title: UIResourceEvent # Interface: UIResourceEvent -Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) +Defined in: [packages/ai/src/types.ts:1498](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1498) Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into a UIResourcePart on the assistant UIMessage. Never enters model input. @@ -14,21 +14,15 @@ Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into - [`CustomEvent`](CustomEvent.md) -## Indexable - -```ts -[k: string]: unknown -``` - ## Properties ### model? ```ts -optional model: string; +optional model?: string; ``` -Defined in: [packages/ai/src/types.ts:1339](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1339) +Defined in: [packages/ai/src/types.ts:1407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1407) Model identifier for multi-model support @@ -44,7 +38,7 @@ Model identifier for multi-model support name: "ui-resource"; ``` -Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) +Defined in: [packages/ai/src/types.ts:1499](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1499) #### Overrides @@ -54,18 +48,65 @@ CustomEvent.name *** +### runId? + +```ts +optional runId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1415) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`runId`](CustomEvent.md#runid) + +*** + +### threadId? + +```ts +optional threadId?: string; +``` + +Defined in: [packages/ai/src/types.ts:1414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1414) + +Routing metadata the TanStack engine attaches when emitting CUSTOM +events that need to be correlated with a specific thread/run. +Stripped by `strip-to-spec-middleware` before going on the wire so +the AG-UI consumer never sees them (when that middleware is enabled). + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`threadId`](CustomEvent.md#threadid) + +*** + +### type + +```ts +type: "CUSTOM"; +``` + +Defined in: [packages/ai/src/types.ts:1405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1405) + +#### Inherited from + +[`CustomEvent`](CustomEvent.md).[`type`](CustomEvent.md#type) + +*** + ### value ```ts value: object; ``` -Defined in: [packages/ai/src/types.ts:1416](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1416) +Defined in: [packages/ai/src/types.ts:1500](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1500) #### meta? ```ts -optional meta: Record; +optional meta?: Record; ``` #### resource @@ -77,7 +118,7 @@ resource: object; ##### resource.blob? ```ts -optional blob: string; +optional blob?: string; ``` ##### resource.mimeType @@ -89,7 +130,7 @@ mimeType: string; ##### resource.text? ```ts -optional text: string; +optional text?: string; ``` ##### resource.uri @@ -101,7 +142,7 @@ uri: string; #### serverId? ```ts -optional serverId: string; +optional serverId?: string; ``` #### toolCallId diff --git a/docs/reference/interfaces/UIResourcePart.md b/docs/reference/interfaces/UIResourcePart.md index 1e15deb968..4a412a9746 100644 --- a/docs/reference/interfaces/UIResourcePart.md +++ b/docs/reference/interfaces/UIResourcePart.md @@ -5,17 +5,17 @@ title: UIResourcePart # Interface: UIResourcePart -Defined in: [packages/ai/src/types.ts:451](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L451) +Defined in: [packages/ai/src/types.ts:476](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L476) ## Properties ### meta? ```ts -optional meta: Record; +optional meta?: Record; ``` -Defined in: [packages/ai/src/types.ts:465](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L465) +Defined in: [packages/ai/src/types.ts:490](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L490) Reserved for future passthrough of the resource/tool `_meta.ui` (e.g. frame-size hints). Currently always `undefined` — nothing populates this field yet. @@ -28,14 +28,14 @@ Reserved for future passthrough of the resource/tool `_meta.ui` (e.g. frame-size resource: object; ``` -Defined in: [packages/ai/src/types.ts:454](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L454) +Defined in: [packages/ai/src/types.ts:479](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L479) The ui:// resource object in MCP-native shape — fed straight to the renderer. #### blob? ```ts -optional blob: string; +optional blob?: string; ``` #### mimeType @@ -47,7 +47,7 @@ mimeType: string; #### text? ```ts -optional text: string; +optional text?: string; ``` #### uri @@ -61,10 +61,10 @@ uri: string; ### serverId? ```ts -optional serverId: string; +optional serverId?: string; ``` -Defined in: [packages/ai/src/types.ts:456](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L456) +Defined in: [packages/ai/src/types.ts:481](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L481) Pool prefix / config key — routes interactive calls to the right MCP server. @@ -76,7 +76,7 @@ Pool prefix / config key — routes interactive calls to the right MCP server. toolCallId: string; ``` -Defined in: [packages/ai/src/types.ts:459](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L459) +Defined in: [packages/ai/src/types.ts:484](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L484) Links the widget to the originating tool call — correlates it with the sibling ToolCallPart/ToolResultPart in the same message. @@ -89,7 +89,7 @@ Links the widget to the originating tool call — correlates it with the toolName: string; ``` -Defined in: [packages/ai/src/types.ts:462](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L462) +Defined in: [packages/ai/src/types.ts:487](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L487) Server-native (unprefixed) MCP tool name whose UI this resource renders. Required by the renderer (`@mcp-ui/client`'s `AppRenderer` `toolName` prop). @@ -102,4 +102,4 @@ Server-native (unprefixed) MCP tool name whose UI this resource renders. type: "ui-resource"; ``` -Defined in: [packages/ai/src/types.ts:452](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L452) +Defined in: [packages/ai/src/types.ts:477](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L477) diff --git a/docs/reference/interfaces/UpsertableStreamDurability.md b/docs/reference/interfaces/UpsertableStreamDurability.md new file mode 100644 index 0000000000..5ecd6a7dee --- /dev/null +++ b/docs/reference/interfaces/UpsertableStreamDurability.md @@ -0,0 +1,213 @@ +--- +id: UpsertableStreamDurability +title: UpsertableStreamDurability +--- + +# Interface: UpsertableStreamDurability\ + +Defined in: [packages/ai/src/stream-durability.ts:83](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L83) + +A [StreamDurability](StreamDurability.md) that can re-persist an already-stored range +idempotently. + +A run driver resuming after a crash re-derives the same offsets from its +source position, so replaying an overlapping range must be a no-op rather +than producing duplicates. That capability is deliberately a **separate, +optional method** instead of an optional parameter on `append`: + +- Only adapters that actually support it return this type, so a consumer + requiring the capability asks for `UpsertableStreamDurability` and a + mismatch is a compile error rather than a runtime failure buried in a + run log. +- Pairing each chunk with its offset structurally makes a length mismatch + and an unpaired chunk unrepresentable. A sparse hole is still + representable, so implementations must reject one explicitly. + +Implementations MUST validate the entire batch before mutating any stored +state (so a rejected call never partially applies), MUST reject an offset +they did not mint themselves (every accepted offset is resumable by +definition), MUST reject an offset repeated within one batch, and MUST +reject a hole in the entries array. + +## Extends + +- [`StreamDurability`](StreamDurability.md)\<`TOffset`\> + +## Type Parameters + +### TOffset + +`TOffset` *extends* `string` = `string` + +## Properties + +### append + +```ts +append: (chunks) => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:17](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L17) + +Persist a batch before it is delivered and return exactly one resumable +offset for each chunk, in the same order. + +#### Parameters + +##### chunks + +[`AGUIEvent`](../type-aliases/AGUIEvent.md)[] + +#### Returns + +`Promise`\<`TOffset`[]\> + +#### Inherited from + +[`StreamDurability`](StreamDurability.md).[`append`](StreamDurability.md#append) + +*** + +### close + +```ts +close: () => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:27](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L27) + +Terminalize the producer log and unblock live readers. Core awaits this +for every producer exit, including completion, cancellation, and failure. + +#### Returns + +`Promise`\<`void`\> + +#### Inherited from + +[`StreamDurability`](StreamDurability.md).[`close`](StreamDurability.md#close) + +*** + +### read + +```ts +read: (offset, signal?) => AsyncIterable<{ + chunk: AGUIEvent; + offset: TOffset; +}>; +``` + +Defined in: [packages/ai/src/stream-durability.ts:19](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L19) + +Replay chunks strictly after the supplied adapter-owned offset. + +#### Parameters + +##### offset + +`TOffset` + +##### signal? + +`AbortSignal` + +#### Returns + +`AsyncIterable`\<\{ + `chunk`: [`AGUIEvent`](../type-aliases/AGUIEvent.md); + `offset`: `TOffset`; +\}\> + +#### Inherited from + +[`StreamDurability`](StreamDurability.md).[`read`](StreamDurability.md#read) + +*** + +### resumeFrom + +```ts +resumeFrom: () => TOffset | null; +``` + +Defined in: [packages/ai/src/stream-durability.ts:12](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L12) + +Return the adapter offset captured from the request, or null for a producer. + +#### Returns + +`TOffset` \| `null` + +#### Inherited from + +[`StreamDurability`](StreamDurability.md).[`resumeFrom`](StreamDurability.md#resumefrom) + +*** + +### snapshot + +```ts +snapshot: () => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L57) + +Everything stored for this run **at the moment of the call**, in append +order, then resolve. + +This is the bounded counterpart to [StreamDurability.read](StreamDurability.md#read). `read` +tails: it parks until the log is terminalized or the caller aborts, so it +cannot be used to inspect a log whose producer died without calling +`close` — that log stays open forever and a `for await` over it never +finishes. `snapshot` exists for exactly that case: a producer resuming a +run needs to see the prefix a previous host already stored so it can line +its own output up against it, and it needs that read to *return*. + +Implementations MUST: + +- never wait for more entries — resolve with what is stored, including + while the log is still open and still being appended to; +- resolve to an empty array for a run with nothing stored, rather than + throwing. In particular an implementation must not reuse the + unknown-run failure path a from-start `read` join takes (`read('-1')` on + an empty log is allowed to fail; `snapshot()` is not). A backend over a + network may of course still reject on a transport, protocol, or + authorization failure — that is a failed call, not an empty run; +- return a fresh array the caller can keep or mutate without reaching the + stored log through it. + +The result is a point-in-time view and carries no lock: a concurrent +`append` may land immediately after the snapshot is taken, so a caller +must not treat the last returned offset as the permanent tail. + +#### Returns + +`Promise`\<`object`[]\> + +#### Inherited from + +[`StreamDurability`](StreamDurability.md).[`snapshot`](StreamDurability.md#snapshot) + +*** + +### upsert + +```ts +upsert: (entries) => Promise; +``` + +Defined in: [packages/ai/src/stream-durability.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-durability.ts#L90) + +Persist a batch at caller-supplied offsets, replacing any entry already +stored at the same offset. Returns the offsets in the order supplied. + +#### Parameters + +##### entries + +`object`[] + +#### Returns + +`Promise`\<`TOffset`[]\> diff --git a/docs/reference/interfaces/UsageInfo.md b/docs/reference/interfaces/UsageInfo.md index 32ce4a0d4a..fdc7393e67 100644 --- a/docs/reference/interfaces/UsageInfo.md +++ b/docs/reference/interfaces/UsageInfo.md @@ -5,7 +5,7 @@ title: UsageInfo # Interface: UsageInfo -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:348](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L348) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:374](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L374) Token usage statistics passed to the onUsage hook. Extracted from the RUN_FINISHED chunk when usage data is present. diff --git a/docs/reference/interfaces/VADConfig.md b/docs/reference/interfaces/VADConfig.md index e7ae07601b..92a4135adc 100644 --- a/docs/reference/interfaces/VADConfig.md +++ b/docs/reference/interfaces/VADConfig.md @@ -14,7 +14,7 @@ Voice activity detection configuration ### prefixPaddingMs? ```ts -optional prefixPaddingMs: number; +optional prefixPaddingMs?: number; ``` Defined in: [packages/ai/src/realtime/types.ts:16](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L16) @@ -26,7 +26,7 @@ Audio to include before speech detection (ms) ### silenceDurationMs? ```ts -optional silenceDurationMs: number; +optional silenceDurationMs?: number; ``` Defined in: [packages/ai/src/realtime/types.ts:18](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L18) @@ -38,7 +38,7 @@ Silence duration to end turn (ms) ### threshold? ```ts -optional threshold: number; +optional threshold?: number; ``` Defined in: [packages/ai/src/realtime/types.ts:14](https://github.com/TanStack/ai/blob/main/packages/ai/src/realtime/types.ts#L14) diff --git a/docs/reference/interfaces/ValidateInterruptResumeBatchInput.md b/docs/reference/interfaces/ValidateInterruptResumeBatchInput.md new file mode 100644 index 0000000000..b67b0d9f17 --- /dev/null +++ b/docs/reference/interfaces/ValidateInterruptResumeBatchInput.md @@ -0,0 +1,78 @@ +--- +id: ValidateInterruptResumeBatchInput +title: ValidateInterruptResumeBatchInput +--- + +# Interface: ValidateInterruptResumeBatchInput + +Defined in: [packages/ai/src/interrupt-resume.ts:51](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L51) + +## Properties + +### generation + +```ts +generation: number; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:54](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L54) + +*** + +### interruptedRunId + +```ts +interruptedRunId: string; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:53](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L53) + +*** + +### now? + +```ts +optional now?: number; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:58](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L58) + +*** + +### pending + +```ts +pending: readonly PendingInterruptResumeRecord[]; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:55](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L55) + +*** + +### resume? + +```ts +optional resume?: readonly ResumeEntry[]; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:56](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L56) + +*** + +### threadId + +```ts +threadId: string; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:52](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L52) + +*** + +### tools + +```ts +tools: Tool[]; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L57) diff --git a/docs/reference/interfaces/ValidatedInterruptResumeBatch.md b/docs/reference/interfaces/ValidatedInterruptResumeBatch.md new file mode 100644 index 0000000000..f19dc1c6af --- /dev/null +++ b/docs/reference/interfaces/ValidatedInterruptResumeBatch.md @@ -0,0 +1,58 @@ +--- +id: ValidatedInterruptResumeBatch +title: ValidatedInterruptResumeBatch +--- + +# Interface: ValidatedInterruptResumeBatch + +Defined in: [packages/ai/src/interrupt-resume.ts:61](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L61) + +## Properties + +### canonicalResolutions? + +```ts +optional canonicalResolutions?: string; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:64](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L64) + +*** + +### errors + +```ts +errors: readonly InterruptSubmissionError[]; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:62](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L62) + +*** + +### fingerprint? + +```ts +optional fingerprint?: string; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:65](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L65) + +*** + +### resolutions? + +```ts +optional resolutions?: readonly ResumeEntry[]; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:63](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L63) + +*** + +### resumeToolState? + +```ts +optional resumeToolState?: ChatResumeToolState; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:66](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L66) diff --git a/docs/reference/interfaces/VideoAdapter.md b/docs/reference/interfaces/VideoAdapter.md index 9f0059a7ce..7b105f39b6 100644 --- a/docs/reference/interfaces/VideoAdapter.md +++ b/docs/reference/interfaces/VideoAdapter.md @@ -99,7 +99,7 @@ providerOptions: TProviderOptions; *** -### availableDurations() +### availableDurations ```ts availableDurations: () => DurationOptions; @@ -119,7 +119,7 @@ knowledge. *** -### createVideoJob() +### createVideoJob ```ts createVideoJob: (options) => Promise; @@ -144,7 +144,7 @@ Returns a job ID that can be used to poll for status and retrieve the video. *** -### getVideoStatus() +### getVideoStatus ```ts getVideoStatus: (jobId) => Promise; @@ -168,7 +168,7 @@ Get the current status of a video generation job. *** -### getVideoUrl() +### getVideoUrl ```ts getVideoUrl: (jobId) => Promise; @@ -235,7 +235,7 @@ Adapter name identifier *** -### snapDuration() +### snapDuration ```ts snapDuration: (seconds) => TModelDurationByName[TModel] | undefined; diff --git a/docs/reference/interfaces/VideoGenerationOptions.md b/docs/reference/interfaces/VideoGenerationOptions.md index c6ba39c225..59f2957c9b 100644 --- a/docs/reference/interfaces/VideoGenerationOptions.md +++ b/docs/reference/interfaces/VideoGenerationOptions.md @@ -5,7 +5,7 @@ title: VideoGenerationOptions # Interface: VideoGenerationOptions\ -Defined in: [packages/ai/src/types.ts:1935](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1935) +Defined in: [packages/ai/src/types.ts:2371](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2371) **`Experimental`** @@ -30,13 +30,29 @@ These are the common options supported across providers. ## Properties +### abortSignal? + +```ts +optional abortSignal?: AbortSignal; +``` + +Defined in: [packages/ai/src/types.ts:2407](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2407) + +**`Experimental`** + +Effective abort signal composed by the activity from caller `abortSignal` +and/or `timeout`. Adapters should forward this to the provider SDK when +supported. Request-specific — never store on a global client config. + +*** + ### duration? ```ts -optional duration: TDuration; +optional duration?: TDuration; ``` -Defined in: [packages/ai/src/types.ts:1958](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1958) +Defined in: [packages/ai/src/types.ts:2394](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2394) **`Experimental`** @@ -52,7 +68,7 @@ map narrow this to the model's valid union; use logger: InternalLogger; ``` -Defined in: [packages/ai/src/types.ts:1965](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1965) +Defined in: [packages/ai/src/types.ts:2401](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2401) **`Experimental`** @@ -67,7 +83,7 @@ call logger.request() before the SDK call and logger.errors() in catch blocks. model: string; ``` -Defined in: [packages/ai/src/types.ts:1941](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1941) +Defined in: [packages/ai/src/types.ts:2377](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2377) **`Experimental`** @@ -78,10 +94,10 @@ The model to use for video generation ### modelOptions? ```ts -optional modelOptions: TProviderOptions; +optional modelOptions?: TProviderOptions; ``` -Defined in: [packages/ai/src/types.ts:1960](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1960) +Defined in: [packages/ai/src/types.ts:2396](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2396) **`Experimental`** @@ -95,7 +111,7 @@ Model-specific options for video generation prompt: MediaPrompt; ``` -Defined in: [packages/ai/src/types.ts:1950](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1950) +Defined in: [packages/ai/src/types.ts:2386](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2386) **`Experimental`** @@ -111,10 +127,10 @@ provider-native request (e.g. OpenAI Sora `input_reference`, fal ### size? ```ts -optional size: TSize; +optional size?: TSize; ``` -Defined in: [packages/ai/src/types.ts:1952](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1952) +Defined in: [packages/ai/src/types.ts:2388](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2388) **`Experimental`** diff --git a/docs/reference/interfaces/VideoJobResult.md b/docs/reference/interfaces/VideoJobResult.md index eaf447fce1..e387f0b76b 100644 --- a/docs/reference/interfaces/VideoJobResult.md +++ b/docs/reference/interfaces/VideoJobResult.md @@ -5,7 +5,7 @@ title: VideoJobResult # Interface: VideoJobResult -Defined in: [packages/ai/src/types.ts:1973](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1973) +Defined in: [packages/ai/src/types.ts:2415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2415) **`Experimental`** @@ -15,13 +15,29 @@ Result of creating a video generation job. ## Properties +### artifacts? + +```ts +optional artifacts?: PersistedArtifactRef[]; +``` + +Defined in: [packages/ai/src/types.ts:2425](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2425) + +**`Experimental`** + +Durable artifact references, when generation persistence with an artifact + +blob store is wired. A submission has no video yet, so this only carries +refs for persisted prompt INPUTS (e.g. a start frame). + +*** + ### jobId ```ts jobId: string; ``` -Defined in: [packages/ai/src/types.ts:1975](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1975) +Defined in: [packages/ai/src/types.ts:2417](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2417) **`Experimental`** @@ -35,7 +51,7 @@ Unique job identifier for polling status model: string; ``` -Defined in: [packages/ai/src/types.ts:1977](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1977) +Defined in: [packages/ai/src/types.ts:2419](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2419) **`Experimental`** diff --git a/docs/reference/interfaces/VideoPart.md b/docs/reference/interfaces/VideoPart.md index 1f2f55bada..29a152e195 100644 --- a/docs/reference/interfaces/VideoPart.md +++ b/docs/reference/interfaces/VideoPart.md @@ -5,7 +5,7 @@ title: VideoPart # Interface: VideoPart\ -Defined in: [packages/ai/src/types.ts:272](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L272) +Defined in: [packages/ai/src/types.ts:283](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L283) Video content part for multimodal messages. @@ -22,10 +22,10 @@ Provider-specific metadata type ### metadata? ```ts -optional metadata: TMetadata; +optional metadata?: TMetadata; ``` -Defined in: [packages/ai/src/types.ts:277](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L277) +Defined in: [packages/ai/src/types.ts:288](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L288) Provider-specific metadata (e.g., duration, resolution) @@ -37,7 +37,7 @@ Provider-specific metadata (e.g., duration, resolution) source: ContentPartSource; ``` -Defined in: [packages/ai/src/types.ts:275](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L275) +Defined in: [packages/ai/src/types.ts:286](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L286) Source of the video content @@ -49,4 +49,4 @@ Source of the video content type: "video"; ``` -Defined in: [packages/ai/src/types.ts:273](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L273) +Defined in: [packages/ai/src/types.ts:284](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L284) diff --git a/docs/reference/interfaces/VideoStatusResult.md b/docs/reference/interfaces/VideoStatusResult.md index 6c1632be06..1db12df900 100644 --- a/docs/reference/interfaces/VideoStatusResult.md +++ b/docs/reference/interfaces/VideoStatusResult.md @@ -5,7 +5,7 @@ title: VideoStatusResult # Interface: VideoStatusResult -Defined in: [packages/ai/src/types.ts:1985](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1985) +Defined in: [packages/ai/src/types.ts:2433](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2433) **`Experimental`** @@ -18,10 +18,10 @@ Status of a video generation job. ### error? ```ts -optional error: string; +optional error?: string; ``` -Defined in: [packages/ai/src/types.ts:1993](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1993) +Defined in: [packages/ai/src/types.ts:2441](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2441) **`Experimental`** @@ -35,7 +35,7 @@ Error message if status is 'failed' jobId: string; ``` -Defined in: [packages/ai/src/types.ts:1987](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1987) +Defined in: [packages/ai/src/types.ts:2435](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2435) **`Experimental`** @@ -46,10 +46,10 @@ Job identifier ### progress? ```ts -optional progress: number; +optional progress?: number; ``` -Defined in: [packages/ai/src/types.ts:1991](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1991) +Defined in: [packages/ai/src/types.ts:2439](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2439) **`Experimental`** @@ -63,7 +63,7 @@ Progress percentage (0-100), if available status: "pending" | "processing" | "completed" | "failed"; ``` -Defined in: [packages/ai/src/types.ts:1989](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1989) +Defined in: [packages/ai/src/types.ts:2437](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2437) **`Experimental`** diff --git a/docs/reference/interfaces/VideoUrlResult.md b/docs/reference/interfaces/VideoUrlResult.md index 4c0840d216..9969ca3d11 100644 --- a/docs/reference/interfaces/VideoUrlResult.md +++ b/docs/reference/interfaces/VideoUrlResult.md @@ -5,7 +5,7 @@ title: VideoUrlResult # Interface: VideoUrlResult -Defined in: [packages/ai/src/types.ts:2001](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2001) +Defined in: [packages/ai/src/types.ts:2449](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2449) **`Experimental`** @@ -15,13 +15,27 @@ Result containing the URL to a generated video. ## Properties +### artifacts? + +```ts +optional artifacts?: PersistedArtifactRef[]; +``` + +Defined in: [packages/ai/src/types.ts:2463](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2463) + +**`Experimental`** + +Persisted artifact references for generated assets, when available + +*** + ### expiresAt? ```ts -optional expiresAt: Date; +optional expiresAt?: Date; ``` -Defined in: [packages/ai/src/types.ts:2007](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2007) +Defined in: [packages/ai/src/types.ts:2455](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2455) **`Experimental`** @@ -35,7 +49,7 @@ When the URL expires, if applicable jobId: string; ``` -Defined in: [packages/ai/src/types.ts:2003](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2003) +Defined in: [packages/ai/src/types.ts:2451](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2451) **`Experimental`** @@ -49,7 +63,7 @@ Job identifier url: string; ``` -Defined in: [packages/ai/src/types.ts:2005](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2005) +Defined in: [packages/ai/src/types.ts:2453](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2453) **`Experimental`** @@ -60,10 +74,10 @@ URL to the generated video ### usage? ```ts -optional usage: TokenUsage; +optional usage?: TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:2013](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2013) +Defined in: [packages/ai/src/types.ts:2461](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2461) **`Experimental`** diff --git a/docs/reference/type-aliases/AGUIEvent.md b/docs/reference/type-aliases/AGUIEvent.md index 08c045e8bc..418c5fc3b3 100644 --- a/docs/reference/type-aliases/AGUIEvent.md +++ b/docs/reference/type-aliases/AGUIEvent.md @@ -31,6 +31,6 @@ type AGUIEvent = | ReasoningEncryptedValueEvent; ``` -Defined in: [packages/ai/src/types.ts:1639](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1639) +Defined in: [packages/ai/src/types.ts:1725](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1725) Union of all AG-UI events. diff --git a/docs/reference/type-aliases/AGUIEventType.md b/docs/reference/type-aliases/AGUIEventType.md index 6e58fbbb7e..e465f73597 100644 --- a/docs/reference/type-aliases/AGUIEventType.md +++ b/docs/reference/type-aliases/AGUIEventType.md @@ -9,7 +9,7 @@ title: AGUIEventType type AGUIEventType = `${EventType}`; ``` -Defined in: [packages/ai/src/types.ts:1050](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1050) +Defined in: [packages/ai/src/types.ts:1067](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1067) AG-UI Protocol event types. diff --git a/docs/reference/type-aliases/AIAdapter.md b/docs/reference/type-aliases/AIAdapter.md index 8e60e3c96a..a6b682560e 100644 --- a/docs/reference/type-aliases/AIAdapter.md +++ b/docs/reference/type-aliases/AIAdapter.md @@ -13,9 +13,11 @@ type AIAdapter = | AnyAudioAdapter | AnyVideoAdapter | AnyTTSAdapter - | AnyTranscriptionAdapter; + | AnyTranscriptionAdapter + | AnyEmbeddingAdapter + | AnyRerankAdapter; ``` -Defined in: [packages/ai/src/activities/index.ts:178](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/index.ts#L178) +Defined in: [packages/ai/src/activities/index.ts:218](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/index.ts#L218) Union of all adapter types that can be passed to chat() diff --git a/docs/reference/type-aliases/AgentLoopStrategy.md b/docs/reference/type-aliases/AgentLoopStrategy.md index b411a80dd5..543e3cbb30 100644 --- a/docs/reference/type-aliases/AgentLoopStrategy.md +++ b/docs/reference/type-aliases/AgentLoopStrategy.md @@ -3,13 +3,13 @@ id: AgentLoopStrategy title: AgentLoopStrategy --- -# Type Alias: AgentLoopStrategy() +# Type Alias: AgentLoopStrategy ```ts type AgentLoopStrategy = (state) => boolean; ``` -Defined in: [packages/ai/src/types.ts:868](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L868) +Defined in: [packages/ai/src/types.ts:893](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L893) Strategy function that determines whether the agent loop should continue @@ -32,6 +32,6 @@ true to continue looping, false to stop ```typescript // Continue for up to 5 iterations (model turns, not tool calls) const strategy: AgentLoopStrategy = ({ iterationCount }) => iterationCount < 5; -// Cap total tool calls across the run +// Cap total tool calls across the run (or use middleware onShouldContinue) const byTools: AgentLoopStrategy = ({ toolCallCount }) => toolCallCount < 20; ``` diff --git a/docs/reference/type-aliases/AnyChatMiddleware.md b/docs/reference/type-aliases/AnyChatMiddleware.md index d971eb5bef..bd4e2fecbe 100644 --- a/docs/reference/type-aliases/AnyChatMiddleware.md +++ b/docs/reference/type-aliases/AnyChatMiddleware.md @@ -9,6 +9,6 @@ title: AnyChatMiddleware type AnyChatMiddleware = ChatMiddleware; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:595](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L595) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:656](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L656) A `ChatMiddleware` with a permissive context — for use as a constraint. diff --git a/docs/reference/type-aliases/AnyClientTool.md b/docs/reference/type-aliases/AnyClientTool.md index fa6296e3a8..7efeedcc2c 100644 --- a/docs/reference/type-aliases/AnyClientTool.md +++ b/docs/reference/type-aliases/AnyClientTool.md @@ -7,10 +7,10 @@ title: AnyClientTool ```ts type AnyClientTool = - | Omit, "execute"> & object - | Omit, "execute"> & object; + | Omit, "execute"> & object + | Omit, "execute"> & object; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:69](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L69) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:170](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L170) Union type for any kind of client-side tool (client tool or definition) diff --git a/docs/reference/type-aliases/AnyEmbeddingAdapter.md b/docs/reference/type-aliases/AnyEmbeddingAdapter.md new file mode 100644 index 0000000000..cba8285c35 --- /dev/null +++ b/docs/reference/type-aliases/AnyEmbeddingAdapter.md @@ -0,0 +1,15 @@ +--- +id: AnyEmbeddingAdapter +title: AnyEmbeddingAdapter +--- + +# Type Alias: AnyEmbeddingAdapter + +```ts +type AnyEmbeddingAdapter = EmbeddingAdapter; +``` + +Defined in: [packages/ai/src/activities/embed/adapter.ts:66](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/embed/adapter.ts#L66) + +An EmbeddingAdapter with any/unknown type parameters. +Useful as a constraint in generic functions and interfaces. diff --git a/docs/reference/type-aliases/AnyGenerationMiddleware.md b/docs/reference/type-aliases/AnyGenerationMiddleware.md index 8d2d7f8c3b..b258da2d81 100644 --- a/docs/reference/type-aliases/AnyGenerationMiddleware.md +++ b/docs/reference/type-aliases/AnyGenerationMiddleware.md @@ -9,6 +9,6 @@ title: AnyGenerationMiddleware type AnyGenerationMiddleware = GenerationMiddleware; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:173](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L173) +Defined in: [packages/ai/src/activities/middleware/types.ts:219](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L219) A `GenerationMiddleware` with a permissive context — for use as a constraint. diff --git a/docs/reference/type-aliases/AnyRerankAdapter.md b/docs/reference/type-aliases/AnyRerankAdapter.md new file mode 100644 index 0000000000..202f1846a7 --- /dev/null +++ b/docs/reference/type-aliases/AnyRerankAdapter.md @@ -0,0 +1,15 @@ +--- +id: AnyRerankAdapter +title: AnyRerankAdapter +--- + +# Type Alias: AnyRerankAdapter + +```ts +type AnyRerankAdapter = RerankAdapter; +``` + +Defined in: [packages/ai/src/activities/rerank/adapter.ts:55](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/rerank/adapter.ts#L55) + +A RerankAdapter with any/unknown type parameters. +Useful as a constraint in generic functions and interfaces. diff --git a/docs/reference/type-aliases/AnyServerTool.md b/docs/reference/type-aliases/AnyServerTool.md new file mode 100644 index 0000000000..faaf1f591e --- /dev/null +++ b/docs/reference/type-aliases/AnyServerTool.md @@ -0,0 +1,36 @@ +--- +id: AnyServerTool +title: AnyServerTool +--- + +# Type Alias: AnyServerTool + +```ts +type AnyServerTool = Omit, "execute"> & object; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:136](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L136) + +Broad server-tool shape for heterogeneous internal collections. + +## Type Declaration + +### execute? + +```ts +optional execute?: (args, context?) => any; +``` + +#### Parameters + +##### args + +`any` + +##### context? + +`any` + +#### Returns + +`any` diff --git a/docs/reference/type-aliases/AnyTool.md b/docs/reference/type-aliases/AnyTool.md index 8624ea4185..a4ba1b4b7f 100644 --- a/docs/reference/type-aliases/AnyTool.md +++ b/docs/reference/type-aliases/AnyTool.md @@ -9,14 +9,14 @@ title: AnyTool type AnyTool = Omit, "execute"> & object; ``` -Defined in: [packages/ai/src/types.ts:730](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L730) +Defined in: [packages/ai/src/types.ts:755](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L755) ## Type Declaration -### execute()? +### execute? ```ts -optional execute: (args, context?) => any; +optional execute?: (args, context?) => any; ``` #### Parameters diff --git a/docs/reference/type-aliases/ApprovalCapabilityOf.md b/docs/reference/type-aliases/ApprovalCapabilityOf.md new file mode 100644 index 0000000000..82cbacca66 --- /dev/null +++ b/docs/reference/type-aliases/ApprovalCapabilityOf.md @@ -0,0 +1,18 @@ +--- +id: ApprovalCapabilityOf +title: ApprovalCapabilityOf +--- + +# Type Alias: ApprovalCapabilityOf\ + +```ts +type ApprovalCapabilityOf = TTool extends ToolApprovalCapabilityMarker ? TNeeds : false; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:44](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L44) + +## Type Parameters + +### TTool + +`TTool` diff --git a/docs/reference/type-aliases/ApprovalSchemaConfig.md b/docs/reference/type-aliases/ApprovalSchemaConfig.md new file mode 100644 index 0000000000..051015e0b0 --- /dev/null +++ b/docs/reference/type-aliases/ApprovalSchemaConfig.md @@ -0,0 +1,21 @@ +--- +id: ApprovalSchemaConfig +title: ApprovalSchemaConfig +--- + +# Type Alias: ApprovalSchemaConfig + +```ts +type ApprovalSchemaConfig = + | SchemaInput + | { + approve: SchemaInput; + reject?: SchemaInput; +} + | { + approve?: SchemaInput; + reject: SchemaInput; +}; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:32](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L32) diff --git a/docs/reference/type-aliases/ApprovalSchemaOf.md b/docs/reference/type-aliases/ApprovalSchemaOf.md new file mode 100644 index 0000000000..a5999bc359 --- /dev/null +++ b/docs/reference/type-aliases/ApprovalSchemaOf.md @@ -0,0 +1,18 @@ +--- +id: ApprovalSchemaOf +title: ApprovalSchemaOf +--- + +# Type Alias: ApprovalSchemaOf\ + +```ts +type ApprovalSchemaOf = TTool extends ToolApprovalCapabilityMarker ? TSchema : undefined; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:49](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L49) + +## Type Parameters + +### TTool + +`TTool` diff --git a/docs/reference/type-aliases/BatchInterruptErrorCode.md b/docs/reference/type-aliases/BatchInterruptErrorCode.md new file mode 100644 index 0000000000..9721ca9127 --- /dev/null +++ b/docs/reference/type-aliases/BatchInterruptErrorCode.md @@ -0,0 +1,26 @@ +--- +id: BatchInterruptErrorCode +title: BatchInterruptErrorCode +--- + +# Type Alias: BatchInterruptErrorCode + +```ts +type BatchInterruptErrorCode = + | "incomplete-batch" + | "item-validation-failed" + | "unsupported-bulk-operation" + | "async-resolver" + | "inactive-transaction" + | "mixed-provenance" + | "transport" + | "server" + | "protocol" + | "invalid-response-schema" + | "expired" + | "stale" + | "conflict" + | "legacy-submit-failed"; +``` + +Defined in: [packages/ai/src/interrupts.ts:27](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L27) diff --git a/docs/reference/type-aliases/BeforeToolCallDecision.md b/docs/reference/type-aliases/BeforeToolCallDecision.md index aed7489087..8aa31e25b5 100644 --- a/docs/reference/type-aliases/BeforeToolCallDecision.md +++ b/docs/reference/type-aliases/BeforeToolCallDecision.md @@ -24,7 +24,7 @@ type BeforeToolCallDecision = }; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:260](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L260) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:286](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L286) Decision returned from onBeforeToolCall. - undefined/void: continue with normal execution diff --git a/docs/reference/type-aliases/Capability.md b/docs/reference/type-aliases/Capability.md index f41835b288..aa12a25d99 100644 --- a/docs/reference/type-aliases/Capability.md +++ b/docs/reference/type-aliases/Capability.md @@ -26,7 +26,7 @@ unique across an app or the type-level coverage check conflates them. readonly capabilityName: TName; ``` -### has() +### has ```ts has: (ctx) => boolean; diff --git a/docs/reference/type-aliases/CapabilityProvider.md b/docs/reference/type-aliases/CapabilityProvider.md index 255493d0f4..58eb93a80f 100644 --- a/docs/reference/type-aliases/CapabilityProvider.md +++ b/docs/reference/type-aliases/CapabilityProvider.md @@ -3,7 +3,7 @@ id: CapabilityProvider title: CapabilityProvider --- -# Type Alias: CapabilityProvider()\ +# Type Alias: CapabilityProvider\ ```ts type CapabilityProvider = (ctx, value) => void; diff --git a/docs/reference/type-aliases/ChatMiddlewarePhase.md b/docs/reference/type-aliases/ChatMiddlewarePhase.md index eafbc23a7c..4500ceb9e4 100644 --- a/docs/reference/type-aliases/ChatMiddlewarePhase.md +++ b/docs/reference/type-aliases/ChatMiddlewarePhase.md @@ -15,7 +15,7 @@ type ChatMiddlewarePhase = | "structuredOutput"; ``` -Defined in: [packages/ai/src/activities/chat/middleware/types.ts:74](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L74) +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:77](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L77) Phase of the chat middleware lifecycle. - 'init': Initial config transform before the chat engine starts diff --git a/docs/reference/type-aliases/ChatResumeGenericResolution.md b/docs/reference/type-aliases/ChatResumeGenericResolution.md new file mode 100644 index 0000000000..2a74483620 --- /dev/null +++ b/docs/reference/type-aliases/ChatResumeGenericResolution.md @@ -0,0 +1,22 @@ +--- +id: ChatResumeGenericResolution +title: ChatResumeGenericResolution +--- + +# Type Alias: ChatResumeGenericResolution + +```ts +type ChatResumeGenericResolution = + | { + interruptId: string; + payload: unknown; + status: "resolved"; +} + | { + interruptId: string; + payload?: never; + status: "cancelled"; +}; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/types.ts:237](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/types.ts#L237) diff --git a/docs/reference/type-aliases/ChatStream.md b/docs/reference/type-aliases/ChatStream.md index a9b182976a..6572795f2a 100644 --- a/docs/reference/type-aliases/ChatStream.md +++ b/docs/reference/type-aliases/ChatStream.md @@ -11,7 +11,7 @@ type ChatStream = AsyncIterable< | KnownCustomEvent>; ``` -Defined in: [packages/ai/src/types.ts:1520](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1520) +Defined in: [packages/ai/src/types.ts:1604](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1604) The default chat streaming result: standard chunks plus every typed framework CUSTOM event, with the `value: any` catch-all excluded so diff --git a/docs/reference/type-aliases/ClientToolDeclaration.md b/docs/reference/type-aliases/ClientToolDeclaration.md new file mode 100644 index 0000000000..5277fb7c2d --- /dev/null +++ b/docs/reference/type-aliases/ClientToolDeclaration.md @@ -0,0 +1,46 @@ +--- +id: ClientToolDeclaration +title: ClientToolDeclaration +--- + +# Type Alias: ClientToolDeclaration + +```ts +type ClientToolDeclaration = object; +``` + +Defined in: [packages/ai/src/utilities/chat-params.ts:323](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L323) + +Client-declared tool stub (no execute). `name` is `string`, so arrays that +include these stubs intentionally widen `TypedStreamChunk` tool-name +discrimination — pass server tools alone when you need a closed name union. + +## Properties + +### description + +```ts +description: string; +``` + +Defined in: [packages/ai/src/utilities/chat-params.ts:325](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L325) + +*** + +### inputSchema + +```ts +inputSchema: JSONSchema; +``` + +Defined in: [packages/ai/src/utilities/chat-params.ts:326](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L326) + +*** + +### name + +```ts +name: string; +``` + +Defined in: [packages/ai/src/utilities/chat-params.ts:324](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L324) diff --git a/docs/reference/type-aliases/ConstrainedContent.md b/docs/reference/type-aliases/ConstrainedContent.md index 6b7553da1b..9583fe5214 100644 --- a/docs/reference/type-aliases/ConstrainedContent.md +++ b/docs/reference/type-aliases/ConstrainedContent.md @@ -12,7 +12,7 @@ type ConstrainedContent = | ContentPartForInputModalitiesTypes[]; ``` -Defined in: [packages/ai/src/types.ts:340](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L340) +Defined in: [packages/ai/src/types.ts:351](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L351) Type for message content constrained by supported modalities. When modalities is ['text', 'image'], only TextPart and ImagePart are allowed in the array. diff --git a/docs/reference/type-aliases/ConstrainedModelMessage.md b/docs/reference/type-aliases/ConstrainedModelMessage.md index ee09183eab..16a124a6a4 100644 --- a/docs/reference/type-aliases/ConstrainedModelMessage.md +++ b/docs/reference/type-aliases/ConstrainedModelMessage.md @@ -9,7 +9,7 @@ title: ConstrainedModelMessage type ConstrainedModelMessage = Omit & object; ``` -Defined in: [packages/ai/src/types.ts:503](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L503) +Defined in: [packages/ai/src/types.ts:528](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L528) A ModelMessage with content constrained to only allow content parts matching the specified input modalities. diff --git a/docs/reference/type-aliases/ContentPart.md b/docs/reference/type-aliases/ContentPart.md index 213ec1c4f8..8cbf831e05 100644 --- a/docs/reference/type-aliases/ContentPart.md +++ b/docs/reference/type-aliases/ContentPart.md @@ -14,7 +14,7 @@ type ContentPart = | DocumentPart; ``` -Defined in: [packages/ai/src/types.ts:299](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L299) +Defined in: [packages/ai/src/types.ts:310](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L310) Union type for all multimodal content parts. diff --git a/docs/reference/type-aliases/ContentPartForInputModalitiesTypes.md b/docs/reference/type-aliases/ContentPartForInputModalitiesTypes.md index 8c26a43b69..22639e8332 100644 --- a/docs/reference/type-aliases/ContentPartForInputModalitiesTypes.md +++ b/docs/reference/type-aliases/ContentPartForInputModalitiesTypes.md @@ -11,7 +11,7 @@ type ContentPartForInputModalitiesTypes = Extract; ``` -Defined in: [packages/ai/src/types.ts:316](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L316) +Defined in: [packages/ai/src/types.ts:327](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L327) Helper type to filter ContentPart union to only include specific modalities. Used to constrain message content based on model capabilities. diff --git a/docs/reference/type-aliases/ContentPartSource.md b/docs/reference/type-aliases/ContentPartSource.md index 6e01304896..c635492f7d 100644 --- a/docs/reference/type-aliases/ContentPartSource.md +++ b/docs/reference/type-aliases/ContentPartSource.md @@ -11,7 +11,7 @@ type ContentPartSource = | ContentPartUrlSource; ``` -Defined in: [packages/ai/src/types.ts:242](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L242) +Defined in: [packages/ai/src/types.ts:253](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L253) Source specification for multimodal content. Discriminated union supporting both inline data (base64) and URL-based content. diff --git a/docs/reference/type-aliases/DeepPartial.md b/docs/reference/type-aliases/DeepPartial.md index 71e4703a6a..c5bdb47b8c 100644 --- a/docs/reference/type-aliases/DeepPartial.md +++ b/docs/reference/type-aliases/DeepPartial.md @@ -9,7 +9,7 @@ title: DeepPartial type DeepPartial = T extends ReadonlyArray ? DeepPartial[] : T extends object ? { [K in keyof T]?: DeepPartial } : T; ``` -Defined in: [packages/ai/src/types.ts:422](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L422) +Defined in: [packages/ai/src/types.ts:447](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L447) Recursive `Partial` — every nested field becomes optional. Used as the `partial` type on a streaming structured-output part since the progressive diff --git a/docs/reference/type-aliases/EmbeddingContentParts.md b/docs/reference/type-aliases/EmbeddingContentParts.md new file mode 100644 index 0000000000..297d2256ce --- /dev/null +++ b/docs/reference/type-aliases/EmbeddingContentParts.md @@ -0,0 +1,22 @@ +--- +id: EmbeddingContentParts +title: EmbeddingContentParts +--- + +# Type Alias: EmbeddingContentParts + +```ts +type EmbeddingContentParts = ( + | TextPart + | ImagePart)[]; +``` + +Defined in: [packages/ai/src/types.ts:2652](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2652) + +A fused multi-part embedding item: all parts are embedded together into a +single vector (e.g. a product photo plus its caption). Written as a nested +array of content parts — the same `Array` convention chat +messages use — so a fused item is visually distinct from the top-level +`input` list, where each element produces its own vector. Supported by +multimodal embedding models such as Cohere embed-v4 and Amazon Titan +Multimodal. diff --git a/docs/reference/type-aliases/EmbeddingInputItem.md b/docs/reference/type-aliases/EmbeddingInputItem.md new file mode 100644 index 0000000000..7bfa38e60d --- /dev/null +++ b/docs/reference/type-aliases/EmbeddingInputItem.md @@ -0,0 +1,22 @@ +--- +id: EmbeddingInputItem +title: EmbeddingInputItem +--- + +# Type Alias: EmbeddingInputItem + +```ts +type EmbeddingInputItem = + | string + | TextPart + | ImagePart + | EmbeddingContentParts; +``` + +Defined in: [packages/ai/src/types.ts:2661](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2661) + +One embeddable item, producing exactly one vector. A bare string is +shorthand for a text part; a nested [EmbeddingContentParts](EmbeddingContentParts.md) array +fuses its parts into a single vector. Note that a bare array at the top +level of `input` is the *list of items* (one vector each) — fuse by +nesting, e.g. `input: [[textPart, imagePart]]`. diff --git a/docs/reference/type-aliases/EmbeddingInputItemFor.md b/docs/reference/type-aliases/EmbeddingInputItemFor.md new file mode 100644 index 0000000000..f06fefac56 --- /dev/null +++ b/docs/reference/type-aliases/EmbeddingInputItemFor.md @@ -0,0 +1,28 @@ +--- +id: EmbeddingInputItemFor +title: EmbeddingInputItemFor +--- + +# Type Alias: EmbeddingInputItemFor\ + +```ts +type EmbeddingInputItemFor = + | string + | TextPart + | EmbeddingItemByModality[TModalities]; +``` + +Defined in: [packages/ai/src/types.ts:2681](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2681) + +Embedding item type narrowed to the modalities a specific model supports. +`EmbeddingInputItemFor<'text'>` (a text-only model) is `string | TextPart`; +`'text' | 'image'` additionally admits image parts and fused +[EmbeddingContentParts](EmbeddingContentParts.md) arrays. Used by the activity option types +together with the adapter's per-model modality map so unsupported inputs +fail at compile time. + +## Type Parameters + +### TModalities + +`TModalities` *extends* [`EmbeddingModality`](EmbeddingModality.md) = [`EmbeddingModality`](EmbeddingModality.md) diff --git a/docs/reference/type-aliases/EmbeddingModality.md b/docs/reference/type-aliases/EmbeddingModality.md new file mode 100644 index 0000000000..46c294e0a0 --- /dev/null +++ b/docs/reference/type-aliases/EmbeddingModality.md @@ -0,0 +1,17 @@ +--- +id: EmbeddingModality +title: EmbeddingModality +--- + +# Type Alias: EmbeddingModality + +```ts +type EmbeddingModality = "text" | "image"; +``` + +Defined in: [packages/ai/src/types.ts:2631](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2631) + +Input modalities an embedding model can accept. Unlike +[MediaPromptModality](MediaPromptModality.md), `'text'` is listed explicitly because +text-only embedding models are the common case and the modality list +drives compile-time narrowing of [EmbeddingInputItem](EmbeddingInputItem.md). diff --git a/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md b/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md new file mode 100644 index 0000000000..2417a0f920 --- /dev/null +++ b/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md @@ -0,0 +1,16 @@ +--- +id: EmbeddingModelInputModalitiesByName +title: EmbeddingModelInputModalitiesByName +--- + +# Type Alias: EmbeddingModelInputModalitiesByName + +```ts +type EmbeddingModelInputModalitiesByName = Record>; +``` + +Defined in: [packages/ai/src/types.ts:2638](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2638) + +Per-model map from model name to the input modalities it accepts, used as +an adapter type parameter (`TModelInputModalitiesByName`). Models absent +from the map fall back to the unconstrained [EmbeddingInputItem](EmbeddingInputItem.md). diff --git a/docs/reference/type-aliases/GeneratedAudio.md b/docs/reference/type-aliases/GeneratedAudio.md index e6772d0547..66d6c11440 100644 --- a/docs/reference/type-aliases/GeneratedAudio.md +++ b/docs/reference/type-aliases/GeneratedAudio.md @@ -9,7 +9,7 @@ title: GeneratedAudio type GeneratedAudio = GeneratedMediaSource & object; ``` -Defined in: [packages/ai/src/types.ts:1904](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1904) +Defined in: [packages/ai/src/types.ts:2338](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2338) A single generated audio output @@ -18,7 +18,7 @@ A single generated audio output ### contentType? ```ts -optional contentType: string; +optional contentType?: string; ``` Content type of the audio (e.g., 'audio/wav', 'audio/mp3') @@ -26,7 +26,7 @@ Content type of the audio (e.g., 'audio/wav', 'audio/mp3') ### duration? ```ts -optional duration: number; +optional duration?: number; ``` Duration of the generated audio in seconds diff --git a/docs/reference/type-aliases/GeneratedImage.md b/docs/reference/type-aliases/GeneratedImage.md index 08294450ac..7a3d12baca 100644 --- a/docs/reference/type-aliases/GeneratedImage.md +++ b/docs/reference/type-aliases/GeneratedImage.md @@ -9,7 +9,7 @@ title: GeneratedImage type GeneratedImage = GeneratedMediaSource & object; ``` -Defined in: [packages/ai/src/types.ts:1855](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1855) +Defined in: [packages/ai/src/types.ts:2281](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2281) A single generated image @@ -18,7 +18,7 @@ A single generated image ### revisedPrompt? ```ts -optional revisedPrompt: string; +optional revisedPrompt?: string; ``` Revised prompt used by the model (if applicable) diff --git a/docs/reference/type-aliases/GeneratedMediaSource.md b/docs/reference/type-aliases/GeneratedMediaSource.md index 516b34e4b4..dfc5b11fb0 100644 --- a/docs/reference/type-aliases/GeneratedMediaSource.md +++ b/docs/reference/type-aliases/GeneratedMediaSource.md @@ -17,14 +17,16 @@ type GeneratedMediaSource = }; ``` -Defined in: [packages/ai/src/types.ts:1840](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1840) +Defined in: [packages/ai/src/types.ts:2222](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2222) Source of a generated media asset. Exactly one of `url` or `b64Json` is present; the other is absent. Modeled as a mutually-exclusive union so the type rejects `{}` and `{ url, b64Json }` together at compile time while preserving the flat `.url` / `.b64Json` access patterns. -## Type Declaration +## Union Members + +### Type Literal ```ts { @@ -33,13 +35,13 @@ preserving the flat `.url` / `.b64Json` access patterns. } ``` -### b64Json? +#### b64Json? ```ts -optional b64Json: never; +optional b64Json?: never; ``` -### url +#### url ```ts url: string; @@ -47,6 +49,10 @@ url: string; URL to the generated asset (may be temporary) +*** + +### Type Literal + ```ts { b64Json: string; @@ -54,7 +60,7 @@ URL to the generated asset (may be temporary) } ``` -### b64Json +#### b64Json ```ts b64Json: string; @@ -62,8 +68,8 @@ b64Json: string; Base64-encoded asset data -### url? +#### url? ```ts -optional url: never; +optional url?: never; ``` diff --git a/docs/reference/type-aliases/GenerationActivity.md b/docs/reference/type-aliases/GenerationActivity.md index 85b003530a..bf1a043cd7 100644 --- a/docs/reference/type-aliases/GenerationActivity.md +++ b/docs/reference/type-aliases/GenerationActivity.md @@ -6,15 +6,27 @@ title: GenerationActivity # Type Alias: GenerationActivity ```ts -type GenerationActivity = "chat" | "image" | "video" | "audio" | "tts" | "transcription"; +type GenerationActivity = + | "chat" + | "image" + | "video" + | "audio" + | "tts" + | "transcription" + | "embedding" + | "rerank" + | "summarize"; ``` -Defined in: [packages/ai/src/activities/middleware/types.ts:34](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L34) +Defined in: [packages/ai/src/activities/middleware/types.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L37) The activity an observability event describes. -Mirrors the public surface a caller reaches for: `'chat'` for `chat()`, and -the media kinds for the `generate*` activities. `'tts'` matches the speech -adapter's kind (the public discriminator avoids inventing a parallel -`'speech'`/`'text'` vocabulary). `otelMiddleware` maps each to its -`gen_ai.operation.name`. +Mirrors the public surface a caller reaches for: `'chat'` for `chat()`, +`'summarize'` for `summarize()`, and the media kinds for the `generate*` +activities. `'tts'` matches the speech adapter's kind (the public +discriminator avoids inventing a parallel `'speech'`/`'text'` vocabulary). +`otelMiddleware` maps each to its `gen_ai.operation.name`. + +`'summarize'` produces text, not media, so it has no artifacts — a +persistence middleware stores its run record and result and nothing else. diff --git a/docs/reference/type-aliases/GenerationResultTransform.md b/docs/reference/type-aliases/GenerationResultTransform.md new file mode 100644 index 0000000000..dff2b9c27d --- /dev/null +++ b/docs/reference/type-aliases/GenerationResultTransform.md @@ -0,0 +1,40 @@ +--- +id: GenerationResultTransform +title: GenerationResultTransform +--- + +# Type Alias: GenerationResultTransform\ + +```ts +type GenerationResultTransform = (result, ctx) => TResult | undefined | Promise; +``` + +Defined in: [packages/ai/src/activities/middleware/types.ts:118](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L118) + +A transform middleware registers on `ctx.resultTransforms` to rewrite the raw +adapter result before it is returned or streamed. Return a new result to +replace it, or `undefined` to leave it unchanged. + +## Type Parameters + +### TResult + +`TResult` = `unknown` + +### TContext + +`TContext` = `unknown` + +## Parameters + +### result + +`TResult` + +### ctx + +[`GenerationResultTransformContext`](../interfaces/GenerationResultTransformContext.md)\<`TContext`\> + +## Returns + +`TResult` \| `undefined` \| `Promise`\<`TResult` \| `undefined`\> diff --git a/docs/reference/type-aliases/InferSchemaType.md b/docs/reference/type-aliases/InferSchemaType.md index 4eca9016a4..fc2342e436 100644 --- a/docs/reference/type-aliases/InferSchemaType.md +++ b/docs/reference/type-aliases/InferSchemaType.md @@ -9,7 +9,7 @@ title: InferSchemaType type InferSchemaType = T extends StandardJSONSchemaV1 ? TInput : T extends StandardSchemaV1 ? TInput : unknown; ``` -Defined in: [packages/ai/src/types.ts:143](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L143) +Defined in: [packages/ai/src/types.ts:154](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L154) Infer the TypeScript type from a schema. For Standard JSON Schema compliant schemas, extracts the input type. diff --git a/docs/reference/type-aliases/InferToolInput.md b/docs/reference/type-aliases/InferToolInput.md index d8daad6258..844715cfe1 100644 --- a/docs/reference/type-aliases/InferToolInput.md +++ b/docs/reference/type-aliases/InferToolInput.md @@ -6,10 +6,10 @@ title: InferToolInput # Type Alias: InferToolInput\ ```ts -type InferToolInput = T extends object ? TInput extends StandardJSONSchemaV1 ? TInferred : TInput extends JSONSchema ? unknown : unknown : unknown; +type InferToolInput = T extends object ? TInput extends JSONSchema ? unknown : InferSchemaType : unknown; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:85](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L85) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:189](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L189) Extract the input type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema) diff --git a/docs/reference/type-aliases/InferToolName.md b/docs/reference/type-aliases/InferToolName.md index 1aee5c2a6d..935e7847a5 100644 --- a/docs/reference/type-aliases/InferToolName.md +++ b/docs/reference/type-aliases/InferToolName.md @@ -9,7 +9,7 @@ title: InferToolName type InferToolName = T extends object ? N : never; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:80](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L80) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:184](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L184) Extract the tool name as a literal type diff --git a/docs/reference/type-aliases/InferToolOutput.md b/docs/reference/type-aliases/InferToolOutput.md index f49e1deed1..b4bb54786f 100644 --- a/docs/reference/type-aliases/InferToolOutput.md +++ b/docs/reference/type-aliases/InferToolOutput.md @@ -6,10 +6,10 @@ title: InferToolOutput # Type Alias: InferToolOutput\ ```ts -type InferToolOutput = T extends object ? TOutput extends StandardJSONSchemaV1 ? TInferred : TOutput extends JSONSchema ? unknown : unknown : unknown; +type InferToolOutput = T extends object ? TOutput extends StandardJSONSchemaV1 ? InferSchemaType : TOutput extends StandardSchemaV1 ? InferSchemaType : TOutput extends JSONSchema ? unknown : InferSchemaType : unknown; ``` -Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:96](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L96) +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:198](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L198) Extract the output type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema) diff --git a/docs/reference/type-aliases/InputModalitiesTypes.md b/docs/reference/type-aliases/InputModalitiesTypes.md index bafb4a81cf..ef8aa48e70 100644 --- a/docs/reference/type-aliases/InputModalitiesTypes.md +++ b/docs/reference/type-aliases/InputModalitiesTypes.md @@ -9,7 +9,7 @@ title: InputModalitiesTypes type InputModalitiesTypes = object; ``` -Defined in: [packages/ai/src/types.ts:494](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L494) +Defined in: [packages/ai/src/types.ts:519](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L519) ## Properties @@ -19,7 +19,7 @@ Defined in: [packages/ai/src/types.ts:494](https://github.com/TanStack/ai/blob/m inputModalities: ReadonlyArray; ``` -Defined in: [packages/ai/src/types.ts:495](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L495) +Defined in: [packages/ai/src/types.ts:520](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L520) *** @@ -29,4 +29,4 @@ Defined in: [packages/ai/src/types.ts:495](https://github.com/TanStack/ai/blob/m messageMetadataByModality: DefaultMessageMetadataByModality; ``` -Defined in: [packages/ai/src/types.ts:496](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L496) +Defined in: [packages/ai/src/types.ts:521](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L521) diff --git a/docs/reference/type-aliases/InputSchemaOf.md b/docs/reference/type-aliases/InputSchemaOf.md new file mode 100644 index 0000000000..1edca7c564 --- /dev/null +++ b/docs/reference/type-aliases/InputSchemaOf.md @@ -0,0 +1,18 @@ +--- +id: InputSchemaOf +title: InputSchemaOf +--- + +# Type Alias: InputSchemaOf\ + +```ts +type InputSchemaOf = TTool extends object ? TInput extends undefined ? NoSchema : TInput : NoSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:57](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L57) + +## Type Parameters + +### TTool + +`TTool` diff --git a/docs/reference/type-aliases/Interrupt.md b/docs/reference/type-aliases/Interrupt.md new file mode 100644 index 0000000000..8f58e368b6 --- /dev/null +++ b/docs/reference/type-aliases/Interrupt.md @@ -0,0 +1,12 @@ +--- +id: Interrupt +title: Interrupt +--- + +# Type Alias: Interrupt + +```ts +type Interrupt = AGUIInterrupt; +``` + +Defined in: [packages/ai/src/types.ts:1120](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1120) diff --git a/docs/reference/type-aliases/InterruptBinding.md b/docs/reference/type-aliases/InterruptBinding.md new file mode 100644 index 0000000000..2bc035027c --- /dev/null +++ b/docs/reference/type-aliases/InterruptBinding.md @@ -0,0 +1,15 @@ +--- +id: InterruptBinding +title: InterruptBinding +--- + +# Type Alias: InterruptBinding + +```ts +type InterruptBinding = + | InterruptBindingBase & object + | InterruptBindingBase & object + | InterruptBindingBase & object; +``` + +Defined in: [packages/ai/src/interrupts.ts:91](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L91) diff --git a/docs/reference/type-aliases/InterruptSubmissionError.md b/docs/reference/type-aliases/InterruptSubmissionError.md new file mode 100644 index 0000000000..df1811ebfb --- /dev/null +++ b/docs/reference/type-aliases/InterruptSubmissionError.md @@ -0,0 +1,14 @@ +--- +id: InterruptSubmissionError +title: InterruptSubmissionError +--- + +# Type Alias: InterruptSubmissionError + +```ts +type InterruptSubmissionError = + | ItemInterruptError + | BatchInterruptError; +``` + +Defined in: [packages/ai/src/interrupts.ts:62](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L62) diff --git a/docs/reference/type-aliases/ItemInterruptErrorCode.md b/docs/reference/type-aliases/ItemInterruptErrorCode.md new file mode 100644 index 0000000000..4b7c65e8f7 --- /dev/null +++ b/docs/reference/type-aliases/ItemInterruptErrorCode.md @@ -0,0 +1,21 @@ +--- +id: ItemInterruptErrorCode +title: ItemInterruptErrorCode +--- + +# Type Alias: ItemInterruptErrorCode + +```ts +type ItemInterruptErrorCode = + | "invalid-payload" + | "invalid-edited-args" + | "invalid-tool-output" + | "invalid-response-schema" + | "unknown-interrupt" + | "expired" + | "stale" + | "conflict" + | "legacy-unsupported"; +``` + +Defined in: [packages/ai/src/interrupts.ts:16](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L16) diff --git a/docs/reference/type-aliases/KnownCustomEvent.md b/docs/reference/type-aliases/KnownCustomEvent.md index 97c01fec00..9158b38610 100644 --- a/docs/reference/type-aliases/KnownCustomEvent.md +++ b/docs/reference/type-aliases/KnownCustomEvent.md @@ -27,7 +27,7 @@ type KnownCustomEvent = | UIResourceEvent; ``` -Defined in: [packages/ai/src/types.ts:1496](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1496) +Defined in: [packages/ai/src/types.ts:1580](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1580) Every CUSTOM event TanStack AI itself emits, as a discriminated union on `name`. User-emitted custom events (via `emitCustomEvent` with a custom name) diff --git a/docs/reference/type-aliases/MediaInputRole.md b/docs/reference/type-aliases/MediaInputRole.md index 7300a1d585..a9a9583510 100644 --- a/docs/reference/type-aliases/MediaInputRole.md +++ b/docs/reference/type-aliases/MediaInputRole.md @@ -15,7 +15,7 @@ type MediaInputRole = | "character"; ``` -Defined in: [packages/ai/src/types.ts:1715](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1715) +Defined in: [packages/ai/src/types.ts:2091](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2091) Optional role hint on a media input part (image / video / audio). Adapters read `metadata.role` to route the part to the provider-specific request diff --git a/docs/reference/type-aliases/MediaPrompt.md b/docs/reference/type-aliases/MediaPrompt.md index 3d383022ee..f3ed6d08c1 100644 --- a/docs/reference/type-aliases/MediaPrompt.md +++ b/docs/reference/type-aliases/MediaPrompt.md @@ -9,7 +9,7 @@ title: MediaPrompt type MediaPrompt = string | MediaPromptPart[]; ``` -Defined in: [packages/ai/src/types.ts:1766](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1766) +Defined in: [packages/ai/src/types.ts:2142](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2142) Prompt accepted by `generateImage()` / `generateVideo()`: a plain string, or an ordered array of content parts for image-conditioned generation diff --git a/docs/reference/type-aliases/MediaPromptFor.md b/docs/reference/type-aliases/MediaPromptFor.md index b0b45c6be9..6d39aee52c 100644 --- a/docs/reference/type-aliases/MediaPromptFor.md +++ b/docs/reference/type-aliases/MediaPromptFor.md @@ -13,7 +13,7 @@ type MediaPromptFor = | MediaPartByModality[TModalities])[]; ``` -Defined in: [packages/ai/src/types.ts:1787](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1787) +Defined in: [packages/ai/src/types.ts:2163](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2163) Prompt type narrowed to the modalities a specific model supports. `MediaPromptFor` (a text-only model) is `string | Array`; diff --git a/docs/reference/type-aliases/MediaPromptModality.md b/docs/reference/type-aliases/MediaPromptModality.md index 1b34b4b97d..9f099851f5 100644 --- a/docs/reference/type-aliases/MediaPromptModality.md +++ b/docs/reference/type-aliases/MediaPromptModality.md @@ -9,6 +9,6 @@ title: MediaPromptModality type MediaPromptModality = "image" | "video" | "audio"; ``` -Defined in: [packages/ai/src/types.ts:1771](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1771) +Defined in: [packages/ai/src/types.ts:2147](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2147) Non-text modalities a media-generation model can accept in its prompt. diff --git a/docs/reference/type-aliases/MediaPromptPart.md b/docs/reference/type-aliases/MediaPromptPart.md index 1a6f0d57ce..db0359ff2b 100644 --- a/docs/reference/type-aliases/MediaPromptPart.md +++ b/docs/reference/type-aliases/MediaPromptPart.md @@ -13,7 +13,7 @@ type MediaPromptPart = | AudioPart; ``` -Defined in: [packages/ai/src/types.ts:1748](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1748) +Defined in: [packages/ai/src/types.ts:2124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2124) A single part of a multimodal media-generation prompt. Reuses the chat content-part shapes: text parts carry the instruction, image / video / diff --git a/docs/reference/type-aliases/MergedAgentTools.md b/docs/reference/type-aliases/MergedAgentTools.md new file mode 100644 index 0000000000..6443fab6cd --- /dev/null +++ b/docs/reference/type-aliases/MergedAgentTools.md @@ -0,0 +1,20 @@ +--- +id: MergedAgentTools +title: MergedAgentTools +--- + +# Type Alias: MergedAgentTools\ + +```ts +type MergedAgentTools = ReadonlyArray< + | TServerTools[number] +| ClientToolDeclaration>; +``` + +Defined in: [packages/ai/src/utilities/chat-params.ts:329](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/chat-params.ts#L329) + +## Type Parameters + +### TServerTools + +`TServerTools` *extends* `ReadonlyArray`\<[`AnyTool`](AnyTool.md)\> diff --git a/docs/reference/type-aliases/MessagePart.md b/docs/reference/type-aliases/MessagePart.md index d8c3c7e32b..65bfae95ef 100644 --- a/docs/reference/type-aliases/MessagePart.md +++ b/docs/reference/type-aliases/MessagePart.md @@ -19,7 +19,7 @@ type MessagePart = | UIResourcePart; ``` -Defined in: [packages/ai/src/types.ts:468](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L468) +Defined in: [packages/ai/src/types.ts:493](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L493) ## Type Parameters diff --git a/docs/reference/type-aliases/ModalitiesArrayToUnion.md b/docs/reference/type-aliases/ModalitiesArrayToUnion.md index 2ed4468b7c..fd5f64e450 100644 --- a/docs/reference/type-aliases/ModalitiesArrayToUnion.md +++ b/docs/reference/type-aliases/ModalitiesArrayToUnion.md @@ -9,7 +9,7 @@ title: ModalitiesArrayToUnion type ModalitiesArrayToUnion = T[number]; ``` -Defined in: [packages/ai/src/types.ts:333](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L333) +Defined in: [packages/ai/src/types.ts:344](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L344) Helper type to convert a readonly array of modalities to a union type. e.g., readonly ['text', 'image'] -> 'text' | 'image' diff --git a/docs/reference/type-aliases/Modality.md b/docs/reference/type-aliases/Modality.md index bbeb71d160..bda220a27e 100644 --- a/docs/reference/type-aliases/Modality.md +++ b/docs/reference/type-aliases/Modality.md @@ -9,7 +9,7 @@ title: Modality type Modality = "text" | "image" | "audio" | "video" | "document"; ``` -Defined in: [packages/ai/src/types.ts:195](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L195) +Defined in: [packages/ai/src/types.ts:206](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L206) Supported input modality types for multimodal content. - 'text': Plain text content diff --git a/docs/reference/type-aliases/ModelInputModalitiesByName.md b/docs/reference/type-aliases/ModelInputModalitiesByName.md index ff1f6fe0e7..566615d641 100644 --- a/docs/reference/type-aliases/ModelInputModalitiesByName.md +++ b/docs/reference/type-aliases/ModelInputModalitiesByName.md @@ -9,7 +9,7 @@ title: ModelInputModalitiesByName type ModelInputModalitiesByName = Record>; ``` -Defined in: [packages/ai/src/types.ts:1796](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1796) +Defined in: [packages/ai/src/types.ts:2172](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2172) Per-model map from model name to the prompt modalities it accepts, used as an adapter type parameter (`TModelInputModalitiesByName`). Models absent diff --git a/docs/reference/type-aliases/NoSchema.md b/docs/reference/type-aliases/NoSchema.md new file mode 100644 index 0000000000..ca10c74f4d --- /dev/null +++ b/docs/reference/type-aliases/NoSchema.md @@ -0,0 +1,12 @@ +--- +id: NoSchema +title: NoSchema +--- + +# Type Alias: NoSchema + +```ts +type NoSchema = typeof noSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:55](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L55) diff --git a/docs/reference/type-aliases/OutputSchemaOf.md b/docs/reference/type-aliases/OutputSchemaOf.md new file mode 100644 index 0000000000..3d7993ab18 --- /dev/null +++ b/docs/reference/type-aliases/OutputSchemaOf.md @@ -0,0 +1,18 @@ +--- +id: OutputSchemaOf +title: OutputSchemaOf +--- + +# Type Alias: OutputSchemaOf\ + +```ts +type OutputSchemaOf = TTool extends object ? TOutput extends undefined ? NoSchema : TOutput : NoSchema; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:65](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L65) + +## Type Parameters + +### TTool + +`TTool` diff --git a/docs/reference/type-aliases/PersistedArtifactActivity.md b/docs/reference/type-aliases/PersistedArtifactActivity.md new file mode 100644 index 0000000000..2a11c5e9b9 --- /dev/null +++ b/docs/reference/type-aliases/PersistedArtifactActivity.md @@ -0,0 +1,12 @@ +--- +id: PersistedArtifactActivity +title: PersistedArtifactActivity +--- + +# Type Alias: PersistedArtifactActivity + +```ts +type PersistedArtifactActivity = "image" | "audio" | "tts" | "video" | "transcription"; +``` + +Defined in: [packages/ai/src/types.ts:2236](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2236) diff --git a/docs/reference/type-aliases/PersistedArtifactRole.md b/docs/reference/type-aliases/PersistedArtifactRole.md new file mode 100644 index 0000000000..944ab01427 --- /dev/null +++ b/docs/reference/type-aliases/PersistedArtifactRole.md @@ -0,0 +1,12 @@ +--- +id: PersistedArtifactRole +title: PersistedArtifactRole +--- + +# Type Alias: PersistedArtifactRole + +```ts +type PersistedArtifactRole = "input" | "output"; +``` + +Defined in: [packages/ai/src/types.ts:2234](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2234) diff --git a/docs/reference/type-aliases/RealtimeEventHandler.md b/docs/reference/type-aliases/RealtimeEventHandler.md index 7eab646516..9246334a78 100644 --- a/docs/reference/type-aliases/RealtimeEventHandler.md +++ b/docs/reference/type-aliases/RealtimeEventHandler.md @@ -3,7 +3,7 @@ id: RealtimeEventHandler title: RealtimeEventHandler --- -# Type Alias: RealtimeEventHandler()\ +# Type Alias: RealtimeEventHandler\ ```ts type RealtimeEventHandler = (payload) => void; diff --git a/docs/reference/type-aliases/RunAgentResumeItem.md b/docs/reference/type-aliases/RunAgentResumeItem.md new file mode 100644 index 0000000000..d646d613b0 --- /dev/null +++ b/docs/reference/type-aliases/RunAgentResumeItem.md @@ -0,0 +1,12 @@ +--- +id: RunAgentResumeItem +title: RunAgentResumeItem +--- + +# Type Alias: RunAgentResumeItem + +```ts +type RunAgentResumeItem = AGUIResumeEntry; +``` + +Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124) diff --git a/docs/reference/type-aliases/RunFinishedOutcome.md b/docs/reference/type-aliases/RunFinishedOutcome.md new file mode 100644 index 0000000000..bca6674af2 --- /dev/null +++ b/docs/reference/type-aliases/RunFinishedOutcome.md @@ -0,0 +1,12 @@ +--- +id: RunFinishedOutcome +title: RunFinishedOutcome +--- + +# Type Alias: RunFinishedOutcome + +```ts +type RunFinishedOutcome = AGUIRunFinishedOutcome; +``` + +Defined in: [packages/ai/src/types.ts:1122](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1122) diff --git a/docs/reference/type-aliases/RunStatus.md b/docs/reference/type-aliases/RunStatus.md new file mode 100644 index 0000000000..d81e7ba36f --- /dev/null +++ b/docs/reference/type-aliases/RunStatus.md @@ -0,0 +1,31 @@ +--- +id: RunStatus +title: RunStatus +--- + +# Type Alias: RunStatus + +```ts +type RunStatus = "running" | "interrupted" | TerminalRunStatus; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:37](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L37) + +Lifecycle status of one run (one agent turn within a conversation). + +`interrupted` is a human-in-the-loop PAUSE that interrupt-resume continues +from — it is deliberately NOT terminal, and must never be conflated with +`aborted` (an explicit cancellation). + +The two are now written by different hooks and cannot be confused: + +- `'interrupted'` is written ONLY by `withPersistence`'s `onInterrupt`, and + carries NO `finishedAt` (a non-terminal status has not finished). +- `'aborted'` is written by `withPersistence`'s `onAbort`, and only for an + abort that is an explicit cancel or that is ending the run for good. +- A mere client disconnect on a run with durable storage wired writes + NEITHER: the record stays `'running'` and gains `detachedSince`, because the + agent is still running and a later attach can take it over. + +Intent is never inferred from the abort itself — see `RUN_CANCEL_REASON` and +`requestRunCancel` in `../cancel`. diff --git a/docs/reference/type-aliases/SchemaInput.md b/docs/reference/type-aliases/SchemaInput.md index 61b584eccd..6da61bbcf3 100644 --- a/docs/reference/type-aliases/SchemaInput.md +++ b/docs/reference/type-aliases/SchemaInput.md @@ -12,7 +12,7 @@ type SchemaInput = | JSONSchema; ``` -Defined in: [packages/ai/src/types.ts:130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L130) +Defined in: [packages/ai/src/types.ts:141](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L141) Union type for schema input - can be any Standard Schema compliant validator, any Standard JSON Schema compliant schema, or a plain JSONSchema object. diff --git a/docs/reference/type-aliases/StreamChunk.md b/docs/reference/type-aliases/StreamChunk.md index 7a4dc8348d..9fe0091b6a 100644 --- a/docs/reference/type-aliases/StreamChunk.md +++ b/docs/reference/type-aliases/StreamChunk.md @@ -9,9 +9,7 @@ title: StreamChunk type StreamChunk = AGUIEvent; ``` -Defined in: [packages/ai/src/types.ts:1667](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1667) +Defined in: [packages/ai/src/types.ts:1753](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1753) Chunk returned by the SDK during streaming chat completions. Uses the AG-UI protocol event format. - -For the tool-aware variant that narrows `TOOL_CALL_START`/`TOOL_CALL_END` events by tool name and `CUSTOM` events by tagged literal name, see [`TypedStreamChunk`](./TypedStreamChunk). diff --git a/docs/reference/type-aliases/StreamChunkType.md b/docs/reference/type-aliases/StreamChunkType.md index 393db93a82..630d36b8a6 100644 --- a/docs/reference/type-aliases/StreamChunkType.md +++ b/docs/reference/type-aliases/StreamChunkType.md @@ -9,7 +9,7 @@ title: StreamChunkType type StreamChunkType = AGUIEventType; ``` -Defined in: [packages/ai/src/types.ts:1056](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1056) +Defined in: [packages/ai/src/types.ts:1073](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1073) Stream chunk/event types (AG-UI protocol). diff --git a/docs/reference/type-aliases/StructuredOutputStream.md b/docs/reference/type-aliases/StructuredOutputStream.md index 401a33506c..5e563f4219 100644 --- a/docs/reference/type-aliases/StructuredOutputStream.md +++ b/docs/reference/type-aliases/StructuredOutputStream.md @@ -14,15 +14,19 @@ type StructuredOutputStream = AsyncIterable< | ToolInputAvailableEvent>; ``` -Defined in: [packages/ai/src/types.ts:1554](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1554) +Defined in: [packages/ai/src/types.ts:1640](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1640) Public type for streams returned by `chat({ outputSchema, stream: true })`. -Yields all standard `StreamChunk` lifecycle events plus the three tagged -`CUSTOM` events the orchestrator can emit through this path: +Yields all standard `StreamChunk` lifecycle events plus the typed +structured-output `CUSTOM` event emitted through this path: - `structured-output.complete` — terminal event with typed `value.object: T` -- `approval-requested` — server tool needs approval (pauses the run) -- `tool-input-available` — client tool invocation (pauses the run) + +User-actionable waits, such as tool approval and client tool input, are +represented by `RUN_FINISHED.outcome.type === 'interrupt'` in current core +streams. Legacy `approval-requested` and `tool-input-available` custom +events may still be consumed for replay and backward compatibility, but +they are not the current source of truth for waits. Each variant has a literal `name`, so a single discriminated narrow gives you a typed `value` with no helper or cast: @@ -31,8 +35,6 @@ you a typed `value` with no helper or cast: for await (const chunk of stream) { if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') { chunk.value.object // typed as T - } else if (chunk.type === 'CUSTOM' && chunk.name === 'approval-requested') { - chunk.value.toolCallId // typed as string } } ``` diff --git a/docs/reference/type-aliases/TaggedCustomEvent.md b/docs/reference/type-aliases/TaggedCustomEvent.md index 04140ca189..f42e806e42 100644 --- a/docs/reference/type-aliases/TaggedCustomEvent.md +++ b/docs/reference/type-aliases/TaggedCustomEvent.md @@ -6,16 +6,18 @@ title: TaggedCustomEvent # Type Alias: TaggedCustomEvent\ ```ts -type TaggedCustomEvent = +type TaggedCustomEvent = | StructuredOutputStartEvent | StructuredOutputCompleteEvent | ApprovalRequestedEvent | ToolInputAvailableEvent; ``` -Defined in: [packages/typescript/ai/src/types.ts](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts) +Defined in: [packages/ai/src/types.ts:1912](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1912) -Discriminated union of the orchestrator-tagged `CUSTOM` events. Each variant has a literal `name`, so a single narrow on `chunk.name` yields a typed `value` with no helper or cast: +Discriminated union of the orchestrator-tagged `CUSTOM` events. Each variant +has a literal `name`, so a single narrow on `chunk.name` yields a typed +`value` with no helper or cast: ```ts if (chunk.type === 'CUSTOM' && chunk.name === 'approval-requested') { @@ -23,10 +25,20 @@ if (chunk.type === 'CUSTOM' && chunk.name === 'approval-requested') { } ``` -The `StructuredOutputCompleteEvent` value is parameterized by `T`, which the chat orchestrator narrows to the schema's inferred type after Standard Schema validation. Adapters always emit it with `T = unknown`. +The `StructuredOutputCompleteEvent` value is parameterized by `T`, which +the chat orchestrator narrows to the schema's inferred type after Standard +Schema validation. Adapters always emit it with `T = unknown`. -`TaggedCustomEvent` is included in [`TypedStreamChunk`](./TypedStreamChunk)'s typed-tools branch so consumers iterating `chat()` streams get tagged narrowing alongside the per-tool `TOOL_CALL_START`/`TOOL_CALL_END` typing. +Caveat: tools can emit arbitrary user-defined custom events via the +`emitCustomEvent(name, value)` context API. Those flow through the stream +at runtime but are intentionally absent from this union — including a bare +`CustomEvent` (whose `value: any` would poison the union) would collapse +`chunk.value` back to `any` after the narrow. If you rely on +`emitCustomEvent`, branch on `CUSTOM` outside the literal-`name` narrows +or cast the chunk to `StreamChunk` to recover the wider shape. -## Caveat: user-emitted custom events +## Type Parameters -Tools can emit arbitrary user-defined custom events via the `emitCustomEvent(name, value)` context API. Those flow through the stream at runtime but are intentionally absent from this union — including a bare `CustomEvent` (whose `value: any` would poison the union) would collapse `chunk.value` back to `any` after the narrow. If you rely on `emitCustomEvent`, branch on `CUSTOM` outside the literal-`name` narrows or cast the chunk to [`StreamChunk`](./StreamChunk) to recover the wider shape. +### T + +`T` = `unknown` diff --git a/docs/reference/type-aliases/TerminalRunStatus.md b/docs/reference/type-aliases/TerminalRunStatus.md new file mode 100644 index 0000000000..4c00f675c1 --- /dev/null +++ b/docs/reference/type-aliases/TerminalRunStatus.md @@ -0,0 +1,14 @@ +--- +id: TerminalRunStatus +title: TerminalRunStatus +--- + +# Type Alias: TerminalRunStatus + +```ts +type TerminalRunStatus = "completed" | "failed" | "aborted"; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:15](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L15) + +A terminal run status: no further events will be appended. diff --git a/docs/reference/type-aliases/ToolApprovalResolution.md b/docs/reference/type-aliases/ToolApprovalResolution.md new file mode 100644 index 0000000000..37fc1af3b4 --- /dev/null +++ b/docs/reference/type-aliases/ToolApprovalResolution.md @@ -0,0 +1,23 @@ +--- +id: ToolApprovalResolution +title: ToolApprovalResolution +--- + +# Type Alias: ToolApprovalResolution + +```ts +type ToolApprovalResolution = + | boolean + | { + approved: true; + editedArgs?: unknown; + payload?: unknown; +} + | { + approved: false; + editedArgs?: never; + payload?: unknown; +}; +``` + +Defined in: [packages/ai/src/interrupts.ts:116](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L116) diff --git a/docs/reference/type-aliases/ToolCallState.md b/docs/reference/type-aliases/ToolCallState.md index 8491b029d9..9d102e5a0c 100644 --- a/docs/reference/type-aliases/ToolCallState.md +++ b/docs/reference/type-aliases/ToolCallState.md @@ -16,6 +16,6 @@ type ToolCallState = | "error"; ``` -Defined in: [packages/ai/src/types.ts:48](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L48) +Defined in: [packages/ai/src/types.ts:59](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L59) Tool call states - track the lifecycle of a tool call diff --git a/docs/reference/type-aliases/ToolDefinitionConfig.md b/docs/reference/type-aliases/ToolDefinitionConfig.md new file mode 100644 index 0000000000..2fc02d6c52 --- /dev/null +++ b/docs/reference/type-aliases/ToolDefinitionConfig.md @@ -0,0 +1,74 @@ +--- +id: ToolDefinitionConfig +title: ToolDefinitionConfig +--- + +# Type Alias: ToolDefinitionConfig\ + +```ts +type ToolDefinitionConfig = object & ApprovalConfig; +``` + +Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:211](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L211) + +Tool definition configuration + +## Type Declaration + +### description + +```ts +description: string; +``` + +### inputSchema? + +```ts +optional inputSchema?: TInput; +``` + +### lazy? + +```ts +optional lazy?: boolean; +``` + +### metadata? + +```ts +optional metadata?: Record; +``` + +### name + +```ts +name: TName; +``` + +### outputSchema? + +```ts +optional outputSchema?: TOutput; +``` + +## Type Parameters + +### TInput + +`TInput` *extends* [`SchemaInput`](SchemaInput.md) \| `undefined` = `undefined` + +### TOutput + +`TOutput` *extends* [`SchemaInput`](SchemaInput.md) \| `undefined` = `undefined` + +### TName + +`TName` *extends* `string` = `string` + +### TNeedsApproval + +`TNeedsApproval` *extends* `boolean` = `false` + +### TApprovalSchema + +`TApprovalSchema` *extends* [`ApprovalSchemaConfig`](ApprovalSchemaConfig.md) \| `undefined` = `undefined` diff --git a/docs/reference/type-aliases/ToolExecuteFunction.md b/docs/reference/type-aliases/ToolExecuteFunction.md index 1d2085260c..8ffc96c3fe 100644 --- a/docs/reference/type-aliases/ToolExecuteFunction.md +++ b/docs/reference/type-aliases/ToolExecuteFunction.md @@ -13,17 +13,17 @@ type ToolExecuteFunction = undefined extends TContext | InferSchemaType; ``` -Defined in: [packages/ai/src/types.ts:571](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L571) +Defined in: [packages/ai/src/types.ts:596](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L596) ## Type Parameters ### TInput -`TInput` *extends* [`SchemaInput`](SchemaInput.md) = [`SchemaInput`](SchemaInput.md) +`TInput` *extends* [`SchemaInput`](SchemaInput.md) \| `undefined` = [`SchemaInput`](SchemaInput.md) ### TOutput -`TOutput` *extends* [`SchemaInput`](SchemaInput.md) = [`SchemaInput`](SchemaInput.md) +`TOutput` *extends* [`SchemaInput`](SchemaInput.md) \| `undefined` = [`SchemaInput`](SchemaInput.md) ### TContext diff --git a/docs/reference/type-aliases/ToolExecutionContext.md b/docs/reference/type-aliases/ToolExecutionContext.md index 0e162989ac..d6569c83e0 100644 --- a/docs/reference/type-aliases/ToolExecutionContext.md +++ b/docs/reference/type-aliases/ToolExecutionContext.md @@ -9,7 +9,7 @@ title: ToolExecutionContext type ToolExecutionContext = RuntimeContextField & object; ``` -Defined in: [packages/ai/src/types.ts:540](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L540) +Defined in: [packages/ai/src/types.ts:565](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L565) Context passed to tool execute functions, providing capabilities like emitting custom events during execution. @@ -19,14 +19,14 @@ emitting custom events during execution. ### abortSignal? ```ts -optional abortSignal: AbortSignal; +optional abortSignal?: AbortSignal; ``` Abort signal for the current chat run. Aborts when the run's `abortController` fires (or middleware aborts). Long-running tools — e.g. MCP `callTool` — should forward this to cancel in-flight work. -### emitCustomEvent() +### emitCustomEvent ```ts emitCustomEvent: (eventName, value) => void; @@ -68,7 +68,7 @@ const tool = toolDefinition({ ... }).server(async (args, context) => { ### toolCallId? ```ts -optional toolCallId: string; +optional toolCallId?: string; ``` The ID of the tool call being executed diff --git a/docs/reference/type-aliases/ToolOutputState.md b/docs/reference/type-aliases/ToolOutputState.md index acf8d8424a..2b3c5cb516 100644 --- a/docs/reference/type-aliases/ToolOutputState.md +++ b/docs/reference/type-aliases/ToolOutputState.md @@ -9,4 +9,4 @@ title: ToolOutputState type ToolOutputState = "output-available" | "output-error"; ``` -Defined in: [packages/ai/src/types.ts:65](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L65) +Defined in: [packages/ai/src/types.ts:76](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L76) diff --git a/docs/reference/type-aliases/ToolResultState.md b/docs/reference/type-aliases/ToolResultState.md index 9530b7a5aa..c35450b0d8 100644 --- a/docs/reference/type-aliases/ToolResultState.md +++ b/docs/reference/type-aliases/ToolResultState.md @@ -9,6 +9,6 @@ title: ToolResultState type ToolResultState = "streaming" | "complete" | "error"; ``` -Defined in: [packages/ai/src/types.ts:60](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L60) +Defined in: [packages/ai/src/types.ts:71](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L71) Tool result states - track the lifecycle of a tool result diff --git a/docs/reference/type-aliases/TranscriptionResponseFormat.md b/docs/reference/type-aliases/TranscriptionResponseFormat.md index a56fa32764..f0d25cb4b1 100644 --- a/docs/reference/type-aliases/TranscriptionResponseFormat.md +++ b/docs/reference/type-aliases/TranscriptionResponseFormat.md @@ -9,7 +9,7 @@ title: TranscriptionResponseFormat type TranscriptionResponseFormat = "json" | "text" | "srt" | "verbose_json" | "vtt"; ``` -Defined in: [packages/ai/src/types.ts:2073](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2073) +Defined in: [packages/ai/src/types.ts:2531](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2531) Options for audio transcription. These are the common options supported across providers. diff --git a/docs/reference/type-aliases/TypedStreamChunk.md b/docs/reference/type-aliases/TypedStreamChunk.md index d8a5f16e31..0dda456775 100644 --- a/docs/reference/type-aliases/TypedStreamChunk.md +++ b/docs/reference/type-aliases/TypedStreamChunk.md @@ -6,62 +6,17 @@ title: TypedStreamChunk # Type Alias: TypedStreamChunk\ ```ts -type TypedStreamChunk< - TTools extends ReadonlyArray> = ReadonlyArray>, -> = - HasTypedTools extends true - ? - | Exclude< - StreamChunk, - | { type: 'TOOL_CALL_START' } - | { type: 'TOOL_CALL_END' } - | { type: 'CUSTOM' } - > - | DistributedToolCallStart - | DistributedToolCallEnd - | TaggedCustomEvent - : StreamChunk; +type TypedStreamChunk = HasTypedTools extends true ? + | RemapStreamChunkForTools + | KnownCustomEvent : + | Exclude + | KnownCustomEvent; ``` -Defined in: [packages/typescript/ai/src/types.ts](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts) +Defined in: [packages/ai/src/types.ts:1957](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1957) -A variant of [`StreamChunk`](./StreamChunk) parameterized by the tools array. When specific tool types are provided (e.g. from `chat({ tools: [myTool] })`): +## Type Parameters -- `TOOL_CALL_START` and `TOOL_CALL_END` events form a **discriminated union** over tool names. -- Checking `toolName === 'x'` narrows `input` to that specific tool's input type. -- `TOOL_CALL_END` events have `input` typed per-tool via Standard Schema inference. -- `CUSTOM` events with literal tagged names (`structured-output.start`, `structured-output.complete`, `approval-requested`, `tool-input-available`) narrow `value` to the corresponding payload via the [`TaggedCustomEvent`](./TaggedCustomEvent) union. +### TTools -When tools are untyped or absent, `TypedStreamChunk` falls back to plain `StreamChunk` so existing consumers that pass streams as `AsyncIterable` keep working. - -This is the type returned by `chat()` when streaming is enabled (the default). You don't typically need to reference it directly unless annotating function parameters or return types. - -```ts -import { chat, toolDefinition, type TypedStreamChunk } from "@tanstack/ai"; -import { openaiText } from "@tanstack/ai-openai"; -import { z } from "zod"; - -const weatherTool = toolDefinition({ - name: "get_weather", - description: "Get weather for a location", - inputSchema: z.object({ location: z.string() }), -}); - -const searchTool = toolDefinition({ - name: "search", - description: "Search the web", - inputSchema: z.object({ query: z.string() }), -}); - -// Inferred from `chat()` — typed tool call events plus tagged CUSTOM events -const stream = chat({ - adapter: openaiText("gpt-5.5"), - messages, - tools: [weatherTool, searchTool], -}); - -// Explicit annotation -type Chunk = TypedStreamChunk<[typeof weatherTool, typeof searchTool]>; -``` - -See [Streaming - Type-Safe Tool Call Events](../../chat/streaming) for a practical walkthrough. +`TTools` *extends* `ReadonlyArray`\<[`AnyTool`](AnyTool.md)\> = `ReadonlyArray`\<[`AnyTool`](AnyTool.md)\> diff --git a/docs/reference/type-aliases/UnopenedInterruptBinding.md b/docs/reference/type-aliases/UnopenedInterruptBinding.md new file mode 100644 index 0000000000..f5d4742b02 --- /dev/null +++ b/docs/reference/type-aliases/UnopenedInterruptBinding.md @@ -0,0 +1,12 @@ +--- +id: UnopenedInterruptBinding +title: UnopenedInterruptBinding +--- + +# Type Alias: UnopenedInterruptBinding + +```ts +type UnopenedInterruptBinding = InterruptBinding extends infer TBinding ? TBinding extends InterruptBinding ? Omit : never : never; +``` + +Defined in: [packages/ai/src/interrupts.ts:110](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L110) diff --git a/docs/reference/type-aliases/UsageTotals.md b/docs/reference/type-aliases/UsageTotals.md index b9d5b8e856..f4e4d7bece 100644 --- a/docs/reference/type-aliases/UsageTotals.md +++ b/docs/reference/type-aliases/UsageTotals.md @@ -9,7 +9,7 @@ title: UsageTotals type UsageTotals = TokenUsage; ``` -Defined in: [packages/ai/src/types.ts:1101](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1101) +Defined in: [packages/ai/src/types.ts:1118](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1118) ## Deprecated diff --git a/docs/reference/type-aliases/WellKnownCustomEventName.md b/docs/reference/type-aliases/WellKnownCustomEventName.md new file mode 100644 index 0000000000..bd079b5350 --- /dev/null +++ b/docs/reference/type-aliases/WellKnownCustomEventName.md @@ -0,0 +1,14 @@ +--- +id: WellKnownCustomEventName +title: WellKnownCustomEventName +--- + +# Type Alias: WellKnownCustomEventName + +```ts +type WellKnownCustomEventName = typeof CUSTOM_EVENT[keyof typeof CUSTOM_EVENT]; +``` + +Defined in: [packages/ai/src/custom-events.ts:30](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L30) + +Union of the well-known CUSTOM event name literals. diff --git a/docs/reference/variables/CUSTOM_EVENT.md b/docs/reference/variables/CUSTOM_EVENT.md new file mode 100644 index 0000000000..eaa406dfc0 --- /dev/null +++ b/docs/reference/variables/CUSTOM_EVENT.md @@ -0,0 +1,70 @@ +--- +id: CUSTOM_EVENT +title: CUSTOM_EVENT +--- + +# Variable: CUSTOM\_EVENT + +```ts +const CUSTOM_EVENT: object; +``` + +Defined in: [packages/ai/src/custom-events.ts:17](https://github.com/TanStack/ai/blob/main/packages/ai/src/custom-events.ts#L17) + +Well-known CUSTOM event names. + +## Type Declaration + +### APPROVAL\_REQUESTED + +```ts +readonly APPROVAL_REQUESTED: "approval.requested" = 'approval.requested'; +``` + +### APPROVAL\_RESOLVED + +```ts +readonly APPROVAL_RESOLVED: "approval.resolved" = 'approval.resolved'; +``` + +### ARTIFACT\_CREATED + +```ts +readonly ARTIFACT_CREATED: "artifact.created" = 'artifact.created'; +``` + +### FILE\_CHANGED + +```ts +readonly FILE_CHANGED: "file.changed" = 'file.changed'; +``` + +### PORT\_OPENED + +```ts +readonly PORT_OPENED: "port.opened" = 'port.opened'; +``` + +### PROCESS\_STDERR + +```ts +readonly PROCESS_STDERR: "process.stderr" = 'process.stderr'; +``` + +### PROCESS\_STDOUT + +```ts +readonly PROCESS_STDOUT: "process.stdout" = 'process.stdout'; +``` + +### SANDBOX\_CREATED + +```ts +readonly SANDBOX_CREATED: "sandbox.created" = 'sandbox.created'; +``` + +### SANDBOX\_RESUMED + +```ts +readonly SANDBOX_RESUMED: "sandbox.resumed" = 'sandbox.resumed'; +``` diff --git a/docs/reference/variables/DetachableRunCapability.md b/docs/reference/variables/DetachableRunCapability.md new file mode 100644 index 0000000000..bac67fb1f2 --- /dev/null +++ b/docs/reference/variables/DetachableRunCapability.md @@ -0,0 +1,30 @@ +--- +id: DetachableRunCapability +title: DetachableRunCapability +--- + +# Variable: DetachableRunCapability + +```ts +const DetachableRunCapability: Capability; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:290](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L290) + +Whether the current run can be DETACHED rather than destroyed when its client +disconnects — `true` only when some middleware has both a [RunStore](../interfaces/RunStore.md) and +a durable event log wired (`withSandbox`'s `runs` + `durability.adapter`). + +Lives in core for the same reason `LockStore` does: it is a coordination fact +that two consumer packages must agree on, and neither may depend on the other. +`@tanstack/ai-sandbox` provides it; `@tanstack/ai-persistence` reads it to +decide whether an abort is terminal (`'aborted'`) or a detach (write nothing). +A persistence → sandbox import would be a layering inversion. + +Consumers read it with `{ optional: true }`: absent means "not detachable", +which is every app that has not wired durability. + +Typed `true`, not `boolean`: ABSENCE is the negative, so a published `false` +has no meaning — and a consumer that tests PRESENCE rather than the value +would read one as "detachable". Narrowing the payload makes that +unrepresentable instead of merely undocumented. diff --git a/docs/reference/variables/INTERRUPT_BINDING_METADATA_KEY.md b/docs/reference/variables/INTERRUPT_BINDING_METADATA_KEY.md new file mode 100644 index 0000000000..30cfd36c24 --- /dev/null +++ b/docs/reference/variables/INTERRUPT_BINDING_METADATA_KEY.md @@ -0,0 +1,21 @@ +--- +id: INTERRUPT_BINDING_METADATA_KEY +title: INTERRUPT_BINDING_METADATA_KEY +--- + +# Variable: INTERRUPT\_BINDING\_METADATA\_KEY + +```ts +const INTERRUPT_BINDING_METADATA_KEY: "tanstack:interruptBinding" = 'tanstack:interruptBinding'; +``` + +Defined in: [packages/ai/src/interrupt-resume.ts:40](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupt-resume.ts#L40) + +The `Interrupt.metadata` key under which this package's resume binding +travels. + +Exported so anything that produces an interrupt this package must later +resume — an application middleware raising a generic pause, a future +workflow-to-AG-UI projection — attaches the binding through +[withInterruptBinding](../functions/withInterruptBinding.md) rather than copying the string. Everything +outside this key is the plain AG-UI envelope and is left untouched. diff --git a/docs/reference/variables/INTERRUPT_BINDING_VERSION.md b/docs/reference/variables/INTERRUPT_BINDING_VERSION.md new file mode 100644 index 0000000000..351a00376c --- /dev/null +++ b/docs/reference/variables/INTERRUPT_BINDING_VERSION.md @@ -0,0 +1,26 @@ +--- +id: INTERRUPT_BINDING_VERSION +title: INTERRUPT_BINDING_VERSION +--- + +# Variable: INTERRUPT\_BINDING\_VERSION + +```ts +const INTERRUPT_BINDING_VERSION: 1; +``` + +Defined in: [packages/ai/src/interrupts.ts:79](https://github.com/TanStack/ai/blob/main/packages/ai/src/interrupts.ts#L79) + +Wire version of [InterruptBinding](../type-aliases/InterruptBinding.md). + +The binding is the only part of an AG-UI `Interrupt` that this package +claims — it rides in `metadata` under +[INTERRUPT\_BINDING\_METADATA\_KEY](INTERRUPT_BINDING_METADATA_KEY.md) and tells the resume path how to +correlate an answer back to a paused run. Producers stamp `v`; readers +reject any version they don't understand rather than duck-typing the fields. + +That matters because an AG-UI `Interrupt` is a shared envelope. Another +producer — a workflow engine projecting a durable approval, a third-party +agent — can legitimately put its own binding in the same envelope. Versioning +makes "not mine" a clean rejection instead of a partial match that resumes +against the wrong owner. diff --git a/docs/reference/variables/RUN_ACCEPTED_EVENT.md b/docs/reference/variables/RUN_ACCEPTED_EVENT.md new file mode 100644 index 0000000000..ccb33f08f8 --- /dev/null +++ b/docs/reference/variables/RUN_ACCEPTED_EVENT.md @@ -0,0 +1,30 @@ +--- +id: RUN_ACCEPTED_EVENT +title: RUN_ACCEPTED_EVENT +--- + +# Variable: RUN\_ACCEPTED\_EVENT + +```ts +const RUN_ACCEPTED_EVENT: "run.accepted" = 'run.accepted'; +``` + +Defined in: [packages/ai/src/stream-to-response.ts:352](https://github.com/TanStack/ai/blob/main/packages/ai/src/stream-to-response.ts#L352) + +Name of the synthetic `CUSTOM` chunk a fresh durable producer appends to its +log before pulling the first real chunk. + +Flushing `RUN_STARTED` (above) makes a run joinable from the instant the +stream EMITS something — but a `chat()` whose middleware boots a sandbox +(create a container, install a CLI) legitimately emits nothing for minutes, +and during that window the log is empty. Every joiner's empty-log fail-fast +(`memoryStream`'s first-chunk deadline, the client's rejoin connect deadline) +then reads the run as gone — and the client clears its resume pointer, so a +reload during the boot window permanently orphans a run that is still going. + +This marker closes the window: it is appended (and flushed) before the +producer stream is first pulled, so a join always finds a first chunk within +milliseconds of the run being accepted. Takeover alignment is unaffected — a +journal replay cannot reproduce the marker, and alignment already skips +stored `CUSTOM` chunks as out-of-band for exactly that reason (see +`isBridgeCustomChunk` in `@tanstack/ai-sandbox`). diff --git a/docs/reference/variables/RUN_CANCEL_REASON.md b/docs/reference/variables/RUN_CANCEL_REASON.md new file mode 100644 index 0000000000..c0291b5ef0 --- /dev/null +++ b/docs/reference/variables/RUN_CANCEL_REASON.md @@ -0,0 +1,18 @@ +--- +id: RUN_CANCEL_REASON +title: RUN_CANCEL_REASON +--- + +# Variable: RUN\_CANCEL\_REASON + +```ts +const RUN_CANCEL_REASON: "tanstack-ai:cancel-requested" = 'tanstack-ai:cancel-requested'; +``` + +Defined in: [packages/ai/src/activities/chat/cancel.ts:30](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/cancel.ts#L30) + +Abort reason that marks an abort as an explicit cancellation. + +Namespaced so an application's own reason string cannot collide with it by +accident, and matched with `===` (never a substring test) so an arbitrary +provider error message can never be read as a deliberate cancel. diff --git a/docs/reference/variables/RunDetachedCapability.md b/docs/reference/variables/RunDetachedCapability.md new file mode 100644 index 0000000000..384ee4b9ed --- /dev/null +++ b/docs/reference/variables/RunDetachedCapability.md @@ -0,0 +1,41 @@ +--- +id: RunDetachedCapability +title: RunDetachedCapability +--- + +# Variable: RunDetachedCapability + +```ts +const RunDetachedCapability: Capability; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:329](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L329) + +Whether this run's teardown DID detach — the disconnect was survived, the +agent is still working, and a later attach can take the run over. + +The past-tense counterpart of [DetachableRunCapability](DetachableRunCapability.md), and the two must +not be confused: + +- **detachABLE** is published at `setup`, and only says a disconnect *may* be + survived (a `RunStore` and a durable log are wired). +- **detachED** is published on the ABORT path, by the middleware that actually + makes the call — `withSandbox`'s `onAbort`, which is the only actor that has + resolved BOTH out-of-band cancel bands (`AbortInfo.cancelRequested` and + `wasCancelRequested` on the record) and `detachOnDisconnect`. An explicit + cancel, a non-detachable disconnect, an error, and a normal finish all leave + it unpublished. + +Its consumer is the durable DELIVERY sink in `stream-to-response.ts`: a +detached run's log must stay OPEN and un-terminalized so the takeover can +continue it (see `wasRunDetached` in `../../../delivery-detach`). Reading it +is safe and race-free only because a `for await` over the chat stream awaits +the generator's `return()` — and therefore the whole `onAbort` chain — before +the sink's own `finally` runs. + +Read with `{ optional: true }`: absent means "not detached", which is every +other exit path and every app that has not wired durability. + +Typed `true`, not `boolean`, for the same reason as +[DetachableRunCapability](DetachableRunCapability.md): absence is the only negative, so publishing +`false` must not be representable. diff --git a/docs/reference/variables/getDetachableRun.md b/docs/reference/variables/getDetachableRun.md new file mode 100644 index 0000000000..935145cdf0 --- /dev/null +++ b/docs/reference/variables/getDetachableRun.md @@ -0,0 +1,12 @@ +--- +id: getDetachableRun +title: getDetachableRun +--- + +# Variable: getDetachableRun + +```ts +getDetachableRun: CapabilityGetter; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:297](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L297) diff --git a/docs/reference/variables/getRunDetached.md b/docs/reference/variables/getRunDetached.md new file mode 100644 index 0000000000..369b66b793 --- /dev/null +++ b/docs/reference/variables/getRunDetached.md @@ -0,0 +1,12 @@ +--- +id: getRunDetached +title: getRunDetached +--- + +# Variable: getRunDetached + +```ts +getRunDetached: CapabilityGetter; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:335](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L335) diff --git a/docs/reference/variables/provideDetachableRun.md b/docs/reference/variables/provideDetachableRun.md new file mode 100644 index 0000000000..a113c5685f --- /dev/null +++ b/docs/reference/variables/provideDetachableRun.md @@ -0,0 +1,12 @@ +--- +id: provideDetachableRun +title: provideDetachableRun +--- + +# Variable: provideDetachableRun + +```ts +provideDetachableRun: CapabilityProvider; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:297](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L297) diff --git a/docs/reference/variables/provideRunDetached.md b/docs/reference/variables/provideRunDetached.md new file mode 100644 index 0000000000..1902d73f05 --- /dev/null +++ b/docs/reference/variables/provideRunDetached.md @@ -0,0 +1,12 @@ +--- +id: provideRunDetached +title: provideRunDetached +--- + +# Variable: provideRunDetached + +```ts +provideRunDetached: CapabilityProvider; +``` + +Defined in: [packages/ai/src/activities/chat/middleware/run-store.ts:335](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/middleware/run-store.ts#L335) diff --git a/packages/ai-client/README.md b/packages/ai-client/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai-client/README.md +++ b/packages/ai-client/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-devtools/README.md b/packages/ai-devtools/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai-devtools/README.md +++ b/packages/ai-devtools/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-gemini/README.md b/packages/ai-gemini/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai-gemini/README.md +++ b/packages/ai-gemini/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-ollama/README.md b/packages/ai-ollama/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai-ollama/README.md +++ b/packages/ai-ollama/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-openai/README.md b/packages/ai-openai/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai-openai/README.md +++ b/packages/ai-openai/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-openrouter/README.md b/packages/ai-openrouter/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai-openrouter/README.md +++ b/packages/ai-openrouter/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-preact/README.md b/packages/ai-preact/README.md index cc5235a860..9252787d8c 100644 --- a/packages/ai-preact/README.md +++ b/packages/ai-preact/README.md @@ -2,15 +2,15 @@ TanStack Preact AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-react-ui/README.md b/packages/ai-react-ui/README.md index b0e22bf760..9252787d8c 100644 --- a/packages/ai-react-ui/README.md +++ b/packages/ai-react-ui/README.md @@ -2,15 +2,15 @@ TanStack React AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-react/README.md b/packages/ai-react/README.md index b0e22bf760..9252787d8c 100644 --- a/packages/ai-react/README.md +++ b/packages/ai-react/README.md @@ -2,15 +2,15 @@ TanStack React AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-solid-ui/README.md b/packages/ai-solid-ui/README.md index 6f4cdd8906..9252787d8c 100644 --- a/packages/ai-solid-ui/README.md +++ b/packages/ai-solid-ui/README.md @@ -2,15 +2,15 @@ TanStack Solid AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-vue-ui/README.md b/packages/ai-vue-ui/README.md index e6e8259991..9252787d8c 100644 --- a/packages/ai-vue-ui/README.md +++ b/packages/ai-vue-ui/README.md @@ -2,15 +2,15 @@ TanStack Vue AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai-vue/README.md b/packages/ai-vue/README.md index e6e8259991..9252787d8c 100644 --- a/packages/ai-vue/README.md +++ b/packages/ai-vue/README.md @@ -2,15 +2,15 @@ TanStack Vue AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/ai/README.md b/packages/ai/README.md index a89696b18e..9252787d8c 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/preact-ai-devtools/README.md b/packages/preact-ai-devtools/README.md index cc5235a860..9252787d8c 100644 --- a/packages/preact-ai-devtools/README.md +++ b/packages/preact-ai-devtools/README.md @@ -2,15 +2,15 @@ TanStack Preact AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/react-ai-devtools/README.md b/packages/react-ai-devtools/README.md index b0e22bf760..9252787d8c 100644 --- a/packages/react-ai-devtools/README.md +++ b/packages/react-ai-devtools/README.md @@ -2,15 +2,15 @@ TanStack React AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat, diff --git a/packages/solid-ai-devtools/README.md b/packages/solid-ai-devtools/README.md index 6f4cdd8906..9252787d8c 100644 --- a/packages/solid-ai-devtools/README.md +++ b/packages/solid-ai-devtools/README.md @@ -2,15 +2,15 @@ TanStack Solid AI @@ -36,6 +36,14 @@ +
+ + + # TanStack AI Type-safe, provider-agnostic TypeScript SDK for building streaming chat, @@ -208,6 +216,7 @@ Official adapters include: | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok) | xAI Grok chat, images, and realtime | | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq) | Groq low-latency inference | | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects | +| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus) | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR | | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal) | fal.ai image, video, audio, speech, and transcription models | The adapter system is tree-shakeable by activity. Import `openaiText` for chat,