0
Fork 0
mirror of https://github.com/TanStack/ai.git synced 2026-11-18 19:34:58 +00:00
Commit graph

94 commits

Author SHA1 Message Date
github-actions[bot]
dcc2b296c8
docs: regenerate API documentation (#1313)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-09-03 12:16:40 +02:00
github-actions[bot]
92ed27eefc
docs: regenerate API documentation (#1305)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-09-03 11:09:53 +02:00
github-actions[bot]
4852c78900
docs: regenerate API documentation (#1287)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-09-01 19:11:05 +02:00
github-actions[bot]
273a212bcc
docs: regenerate API documentation (#1265)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-31 18:34:13 +02:00
github-actions[bot]
1999af2267
docs: regenerate API documentation (#1260)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-28 11:42:19 +02:00
kolaworld
62c19edce7
fix(ai): preserve AG-UI fields across conversions (#1204)
* fix(ai): preserve AG-UI timestamps and tool results

* fix(ai): preserve ModelMessage fields in AG-UI serialization

* fix(ai): restore UI parts from message snapshots

* fix(ai): preserve message metadata through persistence

* fix(ai): preserve AG-UI tool errors through snapshots

* chore: update AG-UI conversion changeset

* fix(ai): preserve timestamp and resource identity

* ci: apply automated fixes

* fix(ai): restore name and UI parts across AG-UI round-trips

* test(ai): address CodeRabbit nits on createdAt and ui-resource fixtures

* test(ai): keep MCP widgets out of model content, not persistence metadata

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
2026-08-25 13:29:09 +00:00
github-actions[bot]
c7c3f9508c
docs: regenerate API documentation (#1234)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-24 19:01:47 +02:00
github-actions[bot]
f4f32bdcc2
docs: regenerate API documentation (#1195)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-22 08:16:20 +00:00
github-actions[bot]
b98aa8b429
docs: regenerate API documentation (#1188)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-21 21:20:02 +00:00
kolaworld
47699ed1bf
fix(ai-persistence): persist structured output (#1126)
* fix(ai): persist structured output in message history

Closes #1072

* docs: document structured output lifecycle

Refs #1072

* fix(ai): preserve middleware transcript additions

Append terminal assistant messages to the middleware-visible transcript so chunk observers do not lose messages they recorded before persistence runs.\n\nRefs #1072

* fix(ai-persistence): persist harness structured output

Keep event-source prose and structured-output as two messages.
Add tests for that path. Drop structured-output parts whose raw is not a string.
Document reload hydration and harness persistence.

* fix(ai): keep same-id harness structured output on one message

Codex, OpenCode, ACP, and grok-build reuse the last text messageId.
Split the transcript only when the complete event uses a new id.
Read that id from complete when start omits it.

* ci: apply automated fixes

* docs: isolate harness persistence snippet for kiira

Kiira concatenates snippets that share a group. The persist example now uses its own group so it does not clash with the existing POST handler.

* fix(ai-openrouter): keep combined-models export off the generated file

The model-sync script overwrites model-meta.ts and deleted
OPENROUTER_COMBINED_TOOLS_AND_SCHEMA_MODELS (#1158). Move the handmade
set to its own file and re-export it from the generated file.

---------

Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-08-20 13:50:09 +02:00
github-actions[bot]
0c0c54b92a
docs: regenerate API documentation (#1155)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-19 19:30:00 +02:00
Season Saw
41a5d18908
feat: add self-describing billed usage to TokenUsage (#896)
* feat: add self-describing billed usage to TokenUsage

Non-token billed quantities (seconds of audio/video, fal's endpoint
units) were previously reported as bare counts on unitsBilled /
durationSeconds, leaving consumers to guess the unit from provider
identity. TokenUsage now carries an optional billed field pairing the
quantity with the unit it is denominated in:

  usage.billed = { quantity: 8, unit: 'seconds' }

- BillingUnit is an open string union ('tokens' | 'seconds' | 'units' |
  ...) so provider-specific units stay representable while the common
  ones autocomplete.
- Producers updated: fal adapters ({ unit: 'units' } from the
  x-fal-billable-units header), Grok Imagine video ({ unit: 'seconds' }),
  and the OpenAI/Grok duration-billed transcription paths
  ({ unit: 'seconds' }).
- otelMiddleware emits the pair as tanstack.ai.usage.billed_quantity /
  billed_unit span attributes, guarded so a non-finite quantity never
  leaves a dangling unit.
- unitsBilled / durationSeconds are deprecated but still populated, so
  existing consumers keep working.

Closes #816

* refactor: deduplicate review-flagged helpers

- Extract durationUsage() in the OpenAI transcription adapter so the
  gpt-4o duration branch and the whisper-1 path share one zeroed-tokens +
  billed/durationSeconds shape and can't drift apart.
- Move the identical recordFromBody() body-parsing helper from the
  otel-media and otel-transcription e2e routes into a shared
  lib/request-body module.

* feat: report billed usage from rerank, Seedance, and persistence

Cohere and OpenRouter rerank now set usage.billed with unit units. Seedance video sets unit tokens. Persistence sums billed when both reports use the same unit.

---------

Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
2026-08-19 11:48:53 +02:00
github-actions[bot]
0fcc4e1b62
docs: regenerate API documentation (#1143)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-19 10:39:15 +02:00
github-actions[bot]
5701bf5184
docs: regenerate API documentation (#1141)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-08-18 19:53:35 +02:00
kolaworld
eda82cc8a8
Fix: Add structured output timestamps (#1132)
* fix(ai): preserve structured-output timestamp order

* docs(ai): correct structured-output streaming guidance

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
2026-08-18 17:01:18 +02:00
Jack Herrington
0fb826321c
refactor(code-mode)!: rename Code Mode "skills" to "snippets" (#1114)
* refactor(code-mode)!: rename Code Mode "skills" to "snippets"

Disambiguates Code Mode's runtime code library from the agent/provider
"skills" systems (the SKILL.md packaging feature). Breaking rename of the
package, its public API, and the Code Mode wire contract.

- Package: `@tanstack/ai-code-mode-skills` -> `@tanstack/ai-code-mode-snippets`
  (dir `packages/ai-code-mode-skills` -> `packages/ai-code-mode-snippets`)
- API: `codeModeWithSkills`->`codeModeWithSnippets`, `snippetsToTools`,
  `snippetsToBindings`, `selectRelevantSnippets`, `createSnippetManagementTools`,
  `createSnippetsSystemPrompt`, `generateSnippetTypes`,
  `createFile/MemorySnippetStorage`, all `Snippet*` types/options
- Runtime tools: `search_snippets`/`get_snippet`/`register_snippet`; sandbox
  binding prefix `snippet_`
- Wire contract (`@tanstack/ai`): events `code_mode:snippet_*`,
  `snippet:registered`; types `CodeModeSnippet*Event`/`SnippetRegisteredEvent`
- Sandbox hook (`@tanstack/ai-code-mode`): `createCodeModeTool` option
  `getSkillBindings` -> `getSnippetBindings`
- Updated example `ts-code-mode-web`, docs, and reference docs

Agent/provider skills (packages/*/skills, SKILL.md, provider skills-wire)
are intentionally untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

* docs/test: address CodeRabbit review (rename-related fixes)

- Rename leftover test-cli id `SKL` -> `SNP` (skill abbreviation)
- Fix inaccurate "client-side" execution claim in provider-skills.md and
  ai-core/tool-calling SKILL.md (snippets run in a local isolate, not
  necessarily client-side)
- Package README: correct `registry` -> `toolsRegistry` return field; add
  `text` language to bare fence
- code-mode-with-snippets.md: add `text` language to two bare fences (MD040)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(code-mode-snippets): reject path traversal in snippet names

`createFileSnippetStorage` used the LLM-supplied snippet name directly as an
on-disk path segment (`join(directory, name)`) in get/save/delete, so a name
like `../../x` could read, write, or delete files outside the storage
directory. Snippet names are already identifier-shaped (they double as
`snippet_<name>` sandbox tool names), so names are now validated against
`/^[A-Za-z0-9_-]+$/`: save/delete throw and get returns null for unsafe names.

Addresses a CodeRabbit finding (pre-existing under the old skills storage).
Adds regression tests covering traversal attempts and ordinary names.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-08-15 15:57:37 -07:00
Tom Beckenham
478a4da375
feat(ai): rework tool-call budgets as middleware hooks (#972)
* feat(ai): rework tool-call budgets as middleware hooks

Replace the unreleased maxToolCalls strategy and chat({ maxToolCallsPerTurn })
with an onShouldContinue middleware hook so apps can stop further agent turns
without aborting. Keep toolCallCount / lastTurnToolCallCount on AgentLoopState
for strategies and middleware. Document an app-owned tool-budget recipe
instead of shipping a built-in maxToolCallsMiddleware.

* fix(ai): always run onShouldContinue when evaluating the agent loop

Evaluate agentLoopStrategy and middleware onShouldContinue together so
middleware still observes the final state when the strategy is what stops
the loop. Also use a type-only import for ChatMiddleware in the E2E wire route.

* ci: apply automated fixes
2026-07-28 13:12:53 +10:00
Alem Tuzlak
3301398789
feat(interrupts): AG-UI interrupt lifecycle overhaul (ephemeral) (#970)
* feat(ai): cursor + chat() resume seam, shared locks capability, CUSTOM-event catalog

- Add optional in-band `cursor` to StreamChunk + `cursor` input on chat().
- Add a *replayAndResume() seam: when a cursor is supplied and a ResumeSource
  capability is provided, replay the persisted event tail; if the run is still
  running and the adapter supports re-attach, continue live. No-op without a
  resume source (a non-persisted run is unchanged).
- Move the generic LockStore + LocksCapability ('locks') into core so it is a
  single shared token across the sandbox and persistence layers.
- Add ResumeSource capability/contract and a typed catalog of well-known CUSTOM
  event names (file.changed, process.*, approval.*, artifact.*, sandbox.*).

* feat(persistence): @tanstack/ai-persistence + SQL core + backends + sandbox bridge

- @tanstack/ai-persistence: store contracts, withPersistence middleware,
  memoryPersistence, cursor utilities, approval controller, resume-source
  adapter, history projection. Fully optional; works with and without sandbox.
- @tanstack/ai-persistence-sql: one SQL store impl behind a minimal SqlDriver
  (sqlite|postgres dialect) + versioned migrations + DDL.
- Backends: -sqlite (node:sqlite/better-sqlite3), -postgres (pg), -cloudflare
  (D1, compile-verified), -drizzle and -prisma (BYO).
- @tanstack/ai-sandbox-persistence: durable SQL-backed SandboxStore +
  withPersistenceBridge wiring durable store/locks into withSandbox (agent mode).

* feat(ai-client): in-session auto-resume

- Track the latest in-band cursor per active run; expose getResumeState(),
  resume(), and maybeAutoResume() with an `autoResume` opt-out (default on).
- Pass `cursor` through the connection adapter's RunAgentInput payload so the
  server can replay a run. streamResponse reuses the original runId on resume.

* docs(persistence): overview page, ai-persistence skill, changeset, knip config

- New docs/persistence/overview.md (+ nav entry, addedAt) with server + client +
  agent-mode usage.
- New ai-core/persistence agent skill.
- Changeset covering the feature; knip ignore for the optional pg peer dep.

* ci: apply automated fixes

* feat: finalize ai persistence

* feat: add mysql persistence chat example

* fix: quote mysql usage column

* feat: add cloudflare r2 artifact persistence

* feat: add cloudflare blob persistence primitives

* docs: split persistence guide by scenario

* feat(persistence): client resume + framework use-chat persistence updates

* feat(sandbox): consume persistence without bridge

* feat(persistence): add orm migration CLIs

* feat(sandbox): persist managed workspace files

* fix(ai): tolerate seed messages without parts

* docs(persistence): type-check persistence examples

* fix(client): preserve pending interrupts on mount

* ci: apply automated fixes

* feat: add generation persistence and resumability

* ci: apply automated fixes

* fix: address persistence ci failures

* ci: apply automated fixes

* fix(persistence): default migrations to opt-in

* feat(persistence): add SQL migration CLI docs

* docs(persistence): reorganize persistence guides

* fix(persistence): document internals and r2 prefixes

* Use shared base64 utils

* feat(persistence): split chat and generation middleware

Replace the dual-typed withPersistence cast with honestly typed
withChatPersistence (ChatMiddleware) and withGenerationPersistence
(GenerationMiddleware), sharing feature/run store helpers.

Update callers, tests, docs, skills, and changeset. Document that
runIds must stay unique across activities when both middlewares share
one AIPersistence backend, and how default run ids are allocated.

* ci: apply automated fixes

* feat: split persistence into state (middleware) + delivery (transport/durable-streams) durability (#923)

* feat(ai)!: split state vs delivery durability — StreamDurability transport, remove event-log/cursor/resume seam

* feat(ai-durable-stream): durable-streams protocol StreamDurability adapter

* feat(persistence)!: state-only middleware + memory backend + shared conformance suite; remove delivery stores

* feat(persistence)!: drizzle + prisma state backends; remove SQL-driver sprawl

* feat(client, frameworks)!: resumable SSE + interrupt-only resume; drop cursor & generation delivery-resume

* docs(persistence): state vs delivery durability guides, skills, regenerated API reference

* chore(persistence): migrate examples + e2e; changeset; workspace/knip config

* ci: apply automated fixes

* docs: drop regenerated API reference from this PR

The docs/reference/** API docs are auto-generated (pnpm generate-docs) and
regenerated in dedicated PRs; keeping that churn out of this feature PR.
Restored to the pre-PR base.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

* refactor(ai)!: group batch under durability option ({ adapter, batch })

Transport helpers now take durability: { adapter, batch? } instead of
sibling durability + batch props. batch is a property of how the durability
sink buffers, not a peer of the response init.

* feat: add persistence and delivery durability

* docs: design full AG-UI interrupt support

* docs: plan full AG-UI interrupt support

* feat(ai-persistence-drizzle): user-owned schemas via injection + schema-emit CLI

Let projects own the TanStack AI Drizzle schema instead of the bundled copy:

- drizzlePersistence(db, { schema }) — stores now operate over injected table
  objects, so renamed tables/columns (incl. drizzle `casing` conventions) and
  extra app-owned columns (e.g. a userId on messages) work through the same
  code paths. TanstackAiSchema pins only column data shapes; construction
  validates tables/columns and throws DrizzleSchemaError with per-item detail.
- tanstack-ai-drizzle-schema CLI (--out/--stdout/--force) emits the schema
  module into the project so the user's own drizzle-kit journal owns the DDL
  (verified: drizzle-kit generate on the emitted file reproduces the bundled
  migration exactly).
- Conformance suite runs against a fully renamed variant schema with an
  app-owned ownership column; sync test pins the emitted asset structurally
  identical to the bundled schema; type-level tests cover assignability.
- Docs: drizzle.md "Own the schema", migrations.md cross-ref, persistence
  SKILL.md; package contract tests updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A6Arc9bWdLq1aRRnDRCLMt

* feat: implement AG-UI interrupt lifecycle

* test: allow slow persistence integration setup

* feat(ai-persistence-prisma): renameable models via delegate mapping

Let applications rename the TanStack AI models in their copy of the fragment
(e.g. to avoid collisions with an existing Message/Run model) and map each
store to the renamed client delegate:

  prismaPersistence(prisma, { models: { messages: 'chatMessage' } })

- New model-contract.ts: minimal structural delegate interfaces the stores
  operate over (field surface pinned, delegate names free), PrismaModelMap,
  and construction-time validation throwing PrismaModelError with per-store
  detail. Stores refactored to consume delegates instead of PrismaClient.
- Bytes inputs pinned to Uint8Array<ArrayBuffer> (what Prisma generates);
  blob.upsert result typed unknown with a re-read, matching the Drizzle
  sibling, so user-generated clients stay assignable.
- Conformance suite runs through a fully renamed client; type tests assert
  the generated delegates satisfy the structural contract; validation and
  partial-map tests added.
- Docs: prisma.md "Rename the models" section; persistence SKILL.md note.

Prisma counterpart of the Drizzle schema-injection change (659464a8): DB
names were already free via @map/@@map and generation already ships via the
models CLI — client-level model names were the remaining hardcoded surface.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A6Arc9bWdLq1aRRnDRCLMt

* fix: support interrupts without persistence

* feat: add interrupt testing labs

* fix: complete interrupt resume workflows

* docs: split interrupts into its own section

Interrupts is a large feature; move it out of "Chat & Streaming" into a
dedicated top-level Interrupts section and rewrite the content to be
succinct and example-first with real, rendered React components.

- New docs/interrupts/ pages: overview, tool-approval, multiple, generic,
  client-tool-execution, persistence, migration
- Remove the monolithic docs/chat/interrupts.md and docs/migration/interrupts.md
- Add the Interrupts nav section and drop the old entries in docs/config.json
- Repoint inbound cross-links (chat, tools, persistence, architecture, and the
  generated toolDefinition reference) to the new paths

Examples now show handling a single interrupt, mapping/batching multiple
interrupts, and validating a generic responseSchema in the UI directly,
instead of abstract helper functions.

* docs: clarify interrupt kinds are pauses, not tool categories

The Overview "three kinds" table read as if a tool is either tool-approval
or client-tool-execution. Add a note plus a tool→interrupt matrix showing the
axes are independent: a client tool with needsApproval produces a tool-approval
interrupt first, then a client-tool-execution interrupt once approved.

* docs(interrupts): render examples by looping interrupts, not find+narrow

Replace the `interrupts.find(...)` + whole-component `return null` pattern in
the tool-approval, generic, and client-tool-execution examples with a
`interrupts.map()` that narrows on `kind` and renders per-kind UI. This handles
multiple pending items of a kind and matches the mixed-queue pattern on the
Multiple Interrupts page. Generic items get a per-item child component for their
editor state.

* docs: stop presenting client-tool execution as a resolvable interrupt

Client tools return results through their `.client()` implementation (which runs
automatically) or `addToolResult` — not by resolving a client-tool-execution
interrupt by hand. That manual path was redundant with the tool-result path and
misrepresented how client tools work.

- Delete docs/interrupts/client-tool-execution.md and its nav entry
- Overview: list only tool-approval and generic as kinds you resolve; note client
  tools run automatically and approval is a separate axis
- client-tools.md: drop the manual `execution.resolveInterrupt(...)` snippet;
  keep approval resolution + addToolResult as the manual escape hatch

* feat(interrupts)!: remove client-tool-execution from the public interrupt API

Client tools resolve through their `.client()` implementation (auto-executed)
or `addToolResult` — never as a bound interrupt. The `client-tool-execution`
kind was redundant public surface: `resolveInterrupt(output)` and
`addToolResult` were two doors to the same resolution, and it invited users to
hand-wire client-tool execution that already happens automatically.

The internal architecture is unchanged — the server still emits the
client-tool-execution interrupt as the browser handoff, the client processor
still auto-executes `.client()` tools off it, persistence still stores its
binding. Only the public exposure is removed.

- Remove `ClientToolExecutionInterrupt` from the `ChatInterrupt` union + exports
- Filter client-tool-execution items out of the published `interrupts` /
  `pendingInterrupts` snapshot while keeping them in the internal batch so
  `resolveClientToolOutput` (addToolResult) and auto-execution still work
- Exclude client-tool items from the `resolveInterrupts(cb)` completeness check
  and the boolean-bulk path (they resolve out-of-band; `maybeSubmit` still gates
  real submission on them)
- Update ai-client + framework type tests and the e2e to assert the client tool
  auto-executes and stays out of the public interrupts array

* fix: make interrupts build/typecheck/lint/test/docs green (ephemeral-only)

- Reconcile getChunkRunId precedence for interrupt continuation correlation
- Add resume + loadInterruptState to client connection-adapter surface
- Fix ai-react interrupt-state handler TDZ guard
- Strip recovery/persistence from e2e fixture + example lab
- Fix doc links + kiira snippets for removed persistence surface
- Defer recovery-specific client tests (it.skip) to the persistence PR

* fix(interrupts): ephemeral resume wiring + drop persistence-era e2e

- forward parentRunId from the e2e chat route to chat() so ephemeral
  interrupt resume correlates the child run (fixes tool-approval resume)
- resolve the approval tool-call's owning message from history when the
  live active-message maps were reset by a MESSAGES_SNAPSHOT, so the
  deprecated part.state approval UI still updates
- clear the deprecated approval part.state on approve/deny before the
  compat resolve path runs
- remove interrupts-v2 (durable) e2e routes/fixtures/specs and the
  persistence-era recovery tests/type assertions; these return with the
  stacked persistence PR
- restore the Provider cast on the $provider route dropped during extraction

* ci: apply automated fixes

* refactor(interrupts): remove persistence residue from ephemeral interrupts

The AG-UI interrupt lifecycle was extracted from a larger persistence stack
and shipped ephemeral-only, but carried persistence-shaped code that is never
exercised without a durable layer (which is not part of this package). Remove it.

Server (@tanstack/ai):
- Drop the never-provided InterruptPersistenceGateway capability
  (getInterruptPersistence/provideInterruptPersistence) and its input types
  (OpenInterruptBatchInput, CommitInterruptResolutionsInput). The two call
  sites now always take the ephemeral branch.
- Remove InterruptCommitResult, the InterruptResumeValidationError.recovery
  field, the recovery type guard, and the tanstack:interruptRecovery emission.

Client (@tanstack/ai-client):
- Remove the recovery state machine: getRecoveryState, getPersistedDrafts,
  reportRecoveryError, restorePersistedDrafts, recoverInterrupts,
  {start,recover}PersistedInterrupts, joinContinuationRun, the persisted-state
  branch of applyResumeSnapshot, and the conflict/replay branches of
  submitInterruptBatch (now a plain ephemeral submit).
- Delete interrupt-recovery-parse.ts; drop PersistedInterruptDraft and the
  ChatContinuationLoader option/type.

Kept as a dormant extension seam for a future persistence layer: the optional
ConnectionAdapter.loadInterruptState hook and its InterruptRecoveryStateV1 /
InterruptRecoveryQuery types.

Docs: trim the dangling withChatPersistence step and the persistence-only
migration checklist / recovery sections to match the ephemeral-only surface.

Runtime behavior is unchanged (persistence was never provided). Verified:
typecheck + lint clean across ai/ai-client/6 framework packages, full unit
suites green, docs links pass, and the interrupt lab round-trip re-verified
against the rebuilt dist.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

* chore(interrupts): drop non-interrupt residue from PR surface

Option A slim for #970: restore generation-resume, example/e2e media noise,
import-only churn, and unrelated provider test touch-ups to main while keeping
the AG-UI interrupt lifecycle (engine, InterruptManager, client chat
persistence needed by ChatClient, framework useChat, interrupt lab, docs).

Residue snapshot: branch chore/non-interrupt-residue-from-970 (pre-slim tip).

* chore(interrupts): strip test noise and storage unit tests

Restore pure import/style test churn to main. Drop dedicated storage-adapter,
chat-persistence-controller, and cleared-stream-tracker unit tests from the
ephemeral interrupts PR. Thin chat-client-resume to interrupt resume behavior
only (drop persistence.server hydrate/persist matrix). Remove unused
fake-indexeddb devDependency.

* fix(interrupts): resume race, error surfacing, docs/lab, bound API demos

Defer interrupt resume until the parent stream settles so auto-executed
client tools can continue. Surface client-tool validation failures, match
native CTE reasons, tighten binding types, and lock resume validation with
unit tests. Update docs/skill and e2e/example UIs to the bound interrupt API,
and link the Interrupts Lab from the chat example nav and home page.

* refactor(ai-client): drop storage-adapters and persistence controller from interrupts PR

Restore main's ChatPersistor for optional message storage and keep
ClearedStreamTracker for clear-during-stream. Durable resume adapters
(storage-adapters, ChatPersistenceController, client/server persistence
options) already live on feat/persistence and are out of the ephemeral
interrupt surface.

* fix(interrupts): resume client tools with history results; fix generic lab runId

Ephemeral resume now reconstructs client-tool pending items even when the
client already wrote tool results into message history for UI. Align generic
lab interrupt ids with the terminal provider runId so parentRunId correlates,
surface interrupt validation messages in the lab sanitizer, and match the
home-page Interrupts tile to other demo tiles.

* fix(ai): typecheck after main merge with typed tool-call events

SafeToolInput/Output treat schema generics defaulting to undefined as
unknown, and MCP manager tests use AnyServerTool so fixtures can carry
JSON Schema input without fighting the no-schema ServerTool default.

* chore: reset pnpm-lock to main and reinstall for branch deps

Drop residual Prisma lock entries left from the persistence-era history.
Re-resolve only this branch's package.json deltas on top of main's lock.

* ci: apply automated fixes

* fix: clear knip, lint, and example typecheck after interrupts merge

- Drop unused PublicInterruptBinding and knip ignore for @standard-schema/spec
- Clean interrupt-manager shadowing / unnecessary conditionals / async
- Include serverPersistence in e2e provider links
- Use AnyServerTool for heterogeneous tool arrays in code-mode example

* fix(interrupts): clear resume state after approve; fix e2e approval harness

- Clear interrupt/resume state on successful continuation streams even when
  provider run ids diverge; always clear after a successful interrupt batch
- Immediately reflect approval decisions on tool-call message parts (#532)
- Hide submitting interrupts from the public list; block sends only on
  actionable pending/staged interrupts
- Register client delete_file needsApproval stub so tools-test hydrates
  tool-approval interrupts; match resolve by toolCallId/approval id
- Only render pending approval prompts in e2e ChatUI

* fix(e2e): repair tools-test deny onClick syntax and format

Missing closing brace on the deny-button handler broke prettier parse.

* docs(interrupts): overhaul interrupt guides and strip persistence leftovers

- rewrite the interrupt guides to lead with the problem then the API:
  overview explains what pauses a run and how client tools fit; tool-approval
  covers server and client tools and renders the approval inline in the chat;
  multiple contrasts per-item vs root-helper resolution; generic frames the
  application-pause use case
- remove stale references to a separately-shipped durable persistence layer
  from the interrupt, tools, and architecture docs (ephemeral-only in this PR)
- address review feedback: explain client tools in the overview, render the
  chat alongside the approval UI, and validate the generic value directly
- refresh docs/config.json updatedAt for the touched pages

* Fixed hyphen

* fix(ai): restore tool-call output after MESSAGES_SNAPSHOT

Client-tool interrupt paths emit AG-UI MESSAGES_SNAPSHOT from ModelMessages,
which rebuild tool-call parts as input-complete without output and wipe the
complete/output state the client already applied from TOOL_CALL_END/RESULT.
Reconcile snapshots by folding tool-result content into matching tool-call
parts (and prefer pre-snapshot complete state when richer).

* test(ai): expect tool-call complete+output after snapshot anchor

MESSAGES_SNAPSHOT reconciliation now folds tool-result into the
sibling tool-call; update the anchor test to match.

* fix(ai): satisfy no-unnecessary-condition in snapshot enrichment

Avoid a mutated outer `changed` flag that control-flow analysis treats
as always falsy; detect part identity changes instead.

* ci: apply automated fixes

* docs(interrupts): show error/recovery handling with a real component

Replace the prose-only "when an answer is wrong" section in multiple.md with a
runnable component that renders item errors and root interruptErrors, gates
buttons on status and resuming (not just canResolve), and demonstrates both
recovery paths (clearResolution and retryInterrupts).

* docs(interrupts): show how the server consumes the approval decision

Add a "Consume the decision on the server" section to tool-approval.md: a
server execute snippet reading the (possibly edited) input, and an honest
account of the payload branches (reject payload becomes the tool result the
model reads; approve payload is decision metadata, not passed to execute, use
editedArgs for values the tool needs).

* refactor(interrupts): app owns wire-schema validation; drop ajv and @noble/hashes

The library no longer transforms a generic interrupt's wire JSON Schema into a
validator or validates the resolved value against it, on the client or the
server. Values pass through as-is; the application validates them (e.g. with
z.fromJSONSchema on the client and its own check on the server). Validation of a
tool's code-authored Standard Schema (approvalSchema / inputSchema) is unchanged.

- remove the ajv-based json-schema-validator and the ajv / ajv-formats deps
- generic items are always resolvable; canResolve no longer depends on the
  library being able to compile the wire schema
- replace @noble/hashes with a small bundled SHA-256 (same sha256:<hex> wire
  shape), verified against known vectors; drop the dependency
- update the ts-react-chat interrupt lab to validate the generic payload itself
  with zod, and fix the docs that claimed the library validates

* example(ts-react-chat): rebuild interrupt playground as a wildlife sanctuary

Replace the over-built interrupt lab (durable dead-code, error sanitizer, DI
harness, debug fetch, capability panels, ~1.1k lines of tests) with a lean,
button-driven "Willowbrook Sanctuary" playground: one tool per scenario, wired
to chat()/useChat, each triggered by a preset message.

Covers server + client tools for approval-only, shared approvalSchema, branch
(approve/reject) schemas, and edited args; a generic (app-emitted) interrupt;
and batched approvals resolved per-item or via the root resolveInterrupts.

Fixes found by clicking through every scenario:
- don't force provider tool_choice on a continuation (resume); forcing it made
  the model re-call the approved tool instead of answering (empty reply).
- key the generic interrupt id off the request runId (ctx.runId), not the
  provider chunk.runId, so the client's parentRunId correlates on resume
  (the mismatch surfaced as unknown-interrupt).
- echo edited args in assignEnclosure output so the continuation reflects them.

Add a regression test (api.interrupts.test.ts) covering both fixes, and give
the UI a cozier theme with per-card animal avatars.

* fix(interrupts): recover a denied approval on ephemeral resume

A denied approval writes a final tool result into history, so the tool call
reads as completed and dropped out of the reconstructed pending batch, while
the resume batch still references its `approval_` id. That failed the resume
as `unknown-interrupt` (every deny broke). Ephemeral reconstruction now
recovers `approval_`-referenced calls from history the same way it already
recovers finalized `client_tool_` calls.

- add a regression in chat.test.ts: resume a denial whose call already has a
  result in history resolves without RUN_ERROR and skips execution.
- fix the sibling batch-validation test to use a Standard Schema input; the
  earlier ajv removal means raw JSON Schema args are no longer library-
  validated, so the atomic-batch check now exercises the Standard Schema path.

* example(ts-react-chat): real animal photos + interrupt transparency

- swap the emoji card avatars for real animal photos (loremflickr, keyed by
  species) with an emoji fallback if the image can't load
- render tool calls and results in the transcript (name, input args including
  edits, output, and denial reasons) so it's clear what ran under the hood
- add a "Your decisions" log that captures exactly what was submitted, so
  approve payloads/notes are visible even though they are decision metadata
  the tool never receives

* example(ts-react-chat): restyle interrupt playground with a dark theme

Co-authored-by: Cursor <cursoragent@cursor.com>

* @
test(interrupts): port wildlife scenarios into the e2e harness

Add a deterministic interrupt playground (route /interrupts-test) that mirrors
the ts-react-chat wildlife example, plus 31 aimock-backed specs covering every
AG-UI interrupt shape across allow / deny / cancel via both per-item and root
batch resolution:

- server + client tool approvals: boolean, shared payload, branch payload,
  edited args
- a generic (non-tool) interrupt (resolve-with-payload and cancel)
- batch sets: root approve-all / deny-all / cancel-all, per-item, and the
  mixed resolver form

Server tool results are asserted via the approval-responded state (they are not
surfaced as client message parts); server edited-args are verified through an
emitCustomEvent echo. A shared approvalSchema requires a payload on the deny
decision too, so those scenarios carry a denyPayload. The ts-react-chat example
is unchanged.
@

* fix(interrupts): make interrupt ownership explicit, not assumed

An AG-UI `Interrupt` is a shared envelope. A workflow engine's durable
approval, or another agent framework's pause, can arrive on the same
stream. What makes a pause resumable through `chat()` is the binding this
package attaches to the interrupt's metadata — nothing else.

The client did not enforce that. `hydrateInterrupt` synthesised a binding
for any descriptor that lacked one, so a foreign interrupt rendered as a
resolvable generic interrupt whose answer was submitted against a run
with nothing pending — failing as `unknown-interrupt` only after the user
had filled in the form. That is the silent translation between approval
models the orchestration RFC warns about.

- Interrupts carrying no binding we understand surface as
  `kind: 'unbound'`, `canResolve: false`, with no resolver. Pre-binding
  TanStack descriptors keep their legacy metadata route. Unbound items
  are excluded from the batch-completeness gate so they cannot deadlock
  the interrupts that are ours.
- The binding carries a wire version. Readers reject a version they do
  not recognise instead of duck-typing its fields; a binding written
  before the field existed still reads. This is what lets a future
  workflow-owned binding be rejected cleanly rather than mis-read.
- Export `INTERRUPT_BINDING_METADATA_KEY`, `withInterruptBinding()` and
  `readInterruptBinding()` so other producers attach a binding through a
  supported API rather than copying the metadata key, which was a
  duplicated private const in three files.
- Classify off the binding alone. `Interrupt.reason` is free-form AG-UI
  text another producer can also spell `tool_call`, so it is a display
  hint only and never decides ownership. The emitted values are
  unchanged.
- Enumerate the interrupt export surface instead of `export *`.

REVERSES A DELIBERATE DECISION — please review: 2d26b39c2 kept
`ConnectionAdapter.loadInterruptState` plus `InterruptRecoveryStateV1` /
`InterruptRecoveryQuery` as "a dormant extension seam for a future
persistence layer", after stripping the recovery state machine that used
them. This commit removes them, along with the `persistence-required` /
`atomic-commit-unsupported` / `recovery-unavailable` batch codes.

Reasoning: they describe a persisted, AI-domain interrupt object resumed
through an AI-owned recovery endpoint — which is option 1 of the three
the orchestration RFC (#979) has yet to choose between. Publishing them
as stable types pre-decides that. Nothing consumes the seam today, and
`origin/feat/persistence` (#785) has zero references to any of the three.
Easy to restore if the RFC lands on option 1; hard to unpublish if it
does not. Happy to put them back if the seam is wanted.

Also fixes two pre-existing repo failures the gate surfaced: unresolved
relative tool imports in two interrupt doc snippets (kiira), and knip
flagging the type-only `toolApprovalCapability` brand symbol.

* fix(ai-client): restore per-branch autocomplete for resolveInterrupt options

Replace the two-overload resolveInterrupt signature with a single generic
call signature discriminated on `approved`. Overloads broke editor
autocomplete: a half-typed options literal satisfies neither overload, so
TS resolved no signature and offered no contextual completions. A generic
`TApproved extends boolean` is inferred from the first argument and selects
the matching branch for the rest params, so `payload`/`editedArgs` and the
correct approve/reject schema fields complete per-branch while the wrong
branch's fields are still rejected.

* ci: apply automated fixes

* test(framework): fix @ts-expect-error placement for resolveInterrupt wrong-branch payload

The generic resolveInterrupt signature now reports the wrong-branch payload
error precisely on the offending inner payload property rather than as a
blanket 'no overload matches' on the whole call. Move the @ts-expect-error
directive above that inner line in the framework type tests so it still
suppresses the (now more precise) error.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Jack Herrington <jherr@pobox.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-22 13:22:03 +02:00
Alem Tuzlak
fe53f15f1e
feat(ai): add type-safe tool call events to chat() stream (#452)
* feat(ai): type-safe tool call events on chat() stream

Rebased onto current main as a single clean commit (old history targeted
packages/typescript/ai and could not replay).

- TypedStreamChunk<TTools> with per-tool TOOL_CALL_START/END discrimination
- Thread TTools through chat() / TextActivityResult / createChatOptions
- Honest mergeAgentTools overloads; populate input/output on ToolResult
- Docs + type-level tests

* fix(ai): make TypedStreamChunk discriminable under AG-UI passthrough

- Pick-based ToolCallStart/End/CustomEvent (no Zod index signature leak)
- Remap StreamChunk via type-literal discriminant, not Exclude<{type}>
- Docs: self-contained snippets; use `'type' in chunk` for control-flow narrow
- Sandbox test narrows CUSTOM before reading value

* test(ai): replace deprecated toMatchTypeOf with toExtend

expect-type v1.2+ deprecates toMatchTypeOf in favor of toExtend for
assignability checks.

* ci: apply automated fixes

* fix(ai): clear eslint type-assertion and naming errors

- Rename RemapStreamChunkForTools type param C → TChunk
- Drop unnecessary as StreamChunk/CustomEvent/ToolCallEndEvent casts
- Bedrock test: extract CUSTOM by string literal after Pick-based CustomEvent

---------

Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-07-21 11:01:58 +02:00
github-actions[bot]
54a51fa5c0
docs: regenerate API documentation (#967)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-07-20 13:50:44 +02:00
github-actions[bot]
9548b1526d
docs: regenerate API documentation (#953)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-07-16 14:02:20 +02:00
github-actions[bot]
f2ded503fc
docs: regenerate API documentation (#902)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-07-08 11:29:41 +02:00
github-actions[bot]
a114288ad1
docs: regenerate API documentation (#890)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-07-03 13:29:22 +02:00
github-actions[bot]
18809998fe
docs: regenerate API documentation (#866)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-30 18:55:41 +02:00
github-actions[bot]
3ae96e67a2
docs: regenerate API documentation (#860)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-26 21:32:39 +02:00
github-actions[bot]
33a91e5619
docs: regenerate API documentation (#847)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-25 18:23:45 +02:00
github-actions[bot]
f83c9913e2
docs: regenerate API documentation (#842)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-25 15:17:33 +02:00
github-actions[bot]
64452f246a
docs: regenerate API documentation (#832)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-24 17:33:12 +02:00
github-actions[bot]
c2172c9ce5
docs: regenerate API documentation (#761)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-15 18:38:25 +02:00
Amit Saroj
215b6b401a
fix(ai-openai): migrate WebRTC realtime adapter to OpenAI GA API (#699)
* fix(ai-openai): migrate WebRTC realtime adapter to OpenAI GA API

* Merge branch 'main' into fix/openai-realtime-ga-migration

* fix(ai-openai): complete realtime Beta-to-GA migration

Completes the GA migration started in this PR so the whole realtime flow
works against OpenAI's GA API (the Beta shape was shut down 2026-05-12):

- openaiRealtimeToken() mints ephemeral keys via POST
  /v1/realtime/client_secrets (the Beta /v1/realtime/sessions endpoint is
  retired) and parses the GA top-level value/expires_at response shape
- session.update payloads use the GA shape via a new pure
  buildSessionUpdate() helper: required session.type, audio.input.*,
  audio.output.voice, output_modalities, max_output_tokens; temperature
  (removed in GA) is dropped with a debug log instead of getting the whole
  update rejected with unknown_parameter
- server events handled under GA names (response.output_audio_transcript.*,
  response.output_audio.*, output_text/output_audio content parts)
- removed the now-unused model local in createWebRTCConnection (the GA
  /calls endpoint rejects ?model=; the model is bound to the ephemeral key)
- default model gpt-realtime; dead gpt-4o-(mini-)realtime-preview ids
  (shut down 2026-05-07) removed from OpenAIRealtimeModel, docs, and
  examples
- unit tests for the session.update payload and client-secret
  request/response shapes; changeset added

Live-verified against the OpenAI API: client_secrets 200 (ek_ token),
/v1/realtime/calls 201 with SDP answer, and session.updated echoing voice,
semantic VAD, tools, output_modalities, and max_output_tokens.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ai-openai): collapse output modalities to single GA-supported value

The GA realtime API only accepts ['audio'] or ['text'] for
output_modalities; the Beta API accepted ['audio', 'text'] and the
provider-agnostic RealtimeSessionConfig still legitimately produces it
(e.g. the example UI's audio+text mode). Sending both got the whole
session.update rejected with: Invalid modalities: ['audio', 'text'].

Collapse to ['audio'] when audio is requested — GA audio replies still
stream text via response.output_audio_transcript.* events, so visible
behavior is unchanged. Live-verified: session.updated accepted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Merge branch 'main' into fix/openai-realtime-ga-migration
2026-06-10 14:56:36 +10:00
github-actions[bot]
755dd6f5cd
docs: regenerate API documentation (#706)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-05 11:04:58 +02:00
github-actions[bot]
86c3209c5f
docs: regenerate API documentation (#692)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-03 13:53:20 +02:00
github-actions[bot]
4dd664455b
docs: regenerate API documentation (#680)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-02 08:42:57 +02:00
github-actions[bot]
3419378b6f
docs: regenerate API documentation (#678)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-01 19:32:26 +02:00
github-actions[bot]
f008c5fe21
docs: regenerate API documentation (#674)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-06-01 12:55:33 +02:00
Alem Tuzlak
8036b50543
feat(ai): add typed runtime context (#628)
* feat(ai): add typed runtime context

* fix(ai): address PR 628 review feedback for typed runtime context

- propagate ChatMiddlewareContext<TContext> through compose, structured output, and stream processor
- thread TContext through tool registry, tool-call manager, code-mode bindings, and ai-client
- add type-level tests for typed client context in ai-solid, ai-svelte, ai-vue, ai-preact, and ai-code-mode
- mask user/tenant identifiers in ts-react-chat runtime-context middleware logging
- fix runTest helper false-positive when fixtures are pre-populated by baselining the message count
- update docs and runtime-context example for context typing changes

* ci: apply automated fixes

* fix(e2e): dedupe imports in api.tools-test.ts after merge

Merge auto-resolution left duplicate EventType (value) and StreamChunk
(type) imports, causing Vite pre-transform to fail with "Crawling result
not available" and timing out the entire E2E suite.

* refactor(ai): dedupe runtime-context type helpers, add changeset, document output validation

- Hoist shared context-inference primitives into runtime-context-types.ts,
  imported by chat/index.ts and tools/tool-calls.ts instead of duplicated.
- Standardize the tool tuple reduction on the never-aware MergeContext,
  fixing a latent bug where a mixed untyped+typed tuple collapsed to never.
- Document the deliberate output-validation behavior change (undefined/null
  results are now validated against outputSchema) in code comments and the
  changeset.
- Add the missing changeset for the typed runtime context feature.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-01 09:57:51 +10:00
github-actions[bot]
fcc5bcad84
docs: regenerate API documentation (#664)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-31 13:27:16 +02:00
github-actions[bot]
0da874071a
docs: regenerate API documentation (#658)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-30 09:01:41 +02:00
github-actions[bot]
716892d6de
docs: regenerate API documentation (#652)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-28 18:48:24 +02:00
Tom Beckenham
2c0ebb3669
chore: remove stale PHP and Python packages (#643)
* chore: remove stale PHP and Python packages (closes #642)

Drop the PHP and Python packages and their example apps. TanStack AI now
focuses exclusively on TypeScript; AG-UI handles interop with non-JS
servers, so first-party PHP/Python clients are no longer maintained.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: flatten packages/typescript/* into packages/*

The `typescript/` nesting was a leftover from when other-language packages
lived alongside it. With those gone (commit bda114e3), the extra level is
just noise. Moves all 31 packages with `git mv` so blame/history follow,
then updates workspace globs, tsconfig extends, package.json `directory`
fields, scripts, CI, docs, lockfile, and CLAUDE.md accordingly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-05-26 10:06:29 +02:00
github-actions[bot]
3c6e616102
docs: regenerate API documentation (#638)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-25 18:54:13 +02:00
Alem Tuzlak
37964389d7
docs: fix outdated adapter/tool APIs and add typed-options guide (#635)
Sweep across docs to bring examples back in line with the current
public surface, plus a new guide for the createXxxOptions family.

Broken-import fixes (would have failed for users on copy-paste):
- openai/gemini: openaiTTS/geminiTTS -> openaiSpeech/geminiSpeech
- openai/anthropic/gemini: OpenAIChatConfig/AnthropicChatConfig/
  GeminiChatConfig -> *TextConfig
- openai/anthropic/gemini: corrected the createXxxChat curry pattern
  to the real (model, apiKey, config?) signature
- groq: removed fictional groqSpeech TTS section
- grok: corrected false "no TTS / no transcription" limitations and
  documented grokSpeech, grokTranscription, grokRealtime; fixed
  toStreamResponse -> toServerSentEventsResponse
- fal: removed fictional createFalImage / createFalVideo aliases
- elevenlabs: added Speech / Audio / Transcription sections
- ollama: corrected ollamaText / createOllamaChat factory signatures
- media/text-to-speech: global TTS -> Speech rename, fixed missing
  model args and explicit-API-key examples
- advanced/multimodal-content: removed fabricated assertMessages
  section, replaced with a Standard-Schema validation example
- advanced/middleware: toolCacheMiddleware imports point at the
  @tanstack/ai/middlewares subpath where the symbol actually lives
- getting-started overview / quick-start: added missing `z` imports
- getting-started quick-start-vue + api/ai-vue: corrected Vue
  template antipattern (refs auto-unwrap in templates; .value is
  only needed inside <script setup>)
- tools/tool-approval: corrected ToolCallState lifecycle to the
  real enum (awaiting-input, input-streaming, input-complete,
  approval-requested, approval-responded, complete); use part.input
  instead of stringifying the JSON-string part.arguments
- tools/client-tools: replaced invented `completed` state with the
  real `complete` state and fixed a broken state-check snippet
- tools/tool-architecture: part.arguments.to (string treated as
  object) -> part.input.to
- tools/tools, server-tools: "JSON Schema infers `any`" -> the real
  behavior is `unknown` (Standard Schema validators give full
  inference)
- code-mode: removed legacy chat({ model: "..." }) field
- generateSpeech JSDoc + auto-generated reference: openaiTTS ->
  openaiSpeech so docs stay correct after the next regenerate

New content:
- docs/advanced/typed-options.md — covers the full createXxxOptions
  family (chat, summarize, image, audio, video, speech,
  transcription), what they do (capture an adapter's full type so
  options stay narrowed when spread), what they don't (no runtime
  behavior), with journey-style examples. Added to config.json nav.

Verified with `pnpm test:docs` (298 markdown files, no broken links)
and `pnpm --filter @tanstack/ai test:types`.
2026-05-25 15:14:01 +02:00
github-actions[bot]
6176067597
docs: regenerate API documentation (#631)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-24 21:39:07 +02:00
github-actions[bot]
7c98472358
docs: regenerate API documentation (#614)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-21 14:10:43 +02:00
Alem Tuzlak
188fe11b9b
feat(ai): structured-output middleware coverage (closes #390) (#600)
* feat(ai): structured-output middleware coverage (closes #390)

Middleware now wraps the final structured-output provider call in
`chat({ outputSchema })` for both Promise<T> and streaming variants.

- Add `'structuredOutput'` to `ChatMiddlewarePhase` and set it on
  `ChatMiddlewareContext` for the duration of the final structured-output
  adapter call.
- Add optional `ChatMiddleware.onStructuredOutputConfig` hook receiving a
  `StructuredOutputMiddlewareConfig` (with the JSON Schema) which may
  return a partial to transform the config before the final call.
- Export new `StructuredOutputMiddlewareConfig` type extending
  `ChatMiddlewareConfig` with `outputSchema: JSONSchema`.
- `onChunk` now observes chunks from the final structured-output call;
  `onFinish` fires once at the end of the whole `chat()` invocation
  after finalization completes.
- Remove the previous `RUN_STARTED`/`RUN_FINISHED` suppression hack in
  `runStreamingStructuredOutput`; engine now emits exactly one outer
  pair around the whole run.

* test(ai-e2e): add structured-output x middleware spec

Adds a Playwright spec that exercises the structured-output finalization
path end-to-end with middleware attached, plus a route + fixture for the
mocked LLM call and a phase-capture helper for asserting middleware
phase transitions.

* docs(ai): document onStructuredOutputConfig hook and structuredOutput phase

Updates middleware and structured-outputs skills, public docs, and
regenerated TypeDoc reference for the new `structuredOutput` middleware
phase and the `onStructuredOutputConfig` hook.

* fix(ai): address CR findings on structured-output middleware coverage

- Type: onConfig / onStructuredOutputConfig Promise return allows null
- Error diagnostics: preserve cause + code on validation failures, with
  smarter message extraction for plain-object errors (Standard Schema)
- Streaming consumers see RUN_ERROR on finalization failure (missing
  result or validation), guarded against double-emission
- Synth structured-output.start carries threadId
- Abort signal checked inside runStructuredFinalization for-await loop
- runAgenticStructuredOutput rethrow preserves cause + code
- Skill examples use (ctx, info) signature for onFinish/onError
- Docs Mermaid diagram includes structuredOutput phase branch
- Docs prose acknowledges 3 onConfig firings (init + beforeModel +
  structuredOutput boundary)
- Docs add FinishInfo table marking info.usage explicitly optional
- Changeset reflects suppression-hack relocation (not removal)
- Test comment corrected (synthesis still happens)
- E2E spec title honest about stream:true; docblock notes scope
- kind=phase GET no longer gated behind OTEL_TEST_ENABLED

Call-site enumeration (Procedure 2.8):
- finalizationError gained cause?: unknown. Readers updated:
  * TextEngine terminal hook chooser — propagates cause via Error({ cause })
    and surfaces code as a non-enumerable Object.defineProperty.
  * runAgenticStructuredOutput — same treatment when re-throwing.
  * getFinalizationError return type widened to include cause.
- runStructuredFinalization gained a post-loop synthetic RUN_ERROR yield
  path, gated on yieldChunks and a new runErrorYielded flag. The streaming
  consumer in runStreamingStructuredOutputImpl iterates engine.run() and
  propagates the new chunk transparently — no consumer-side changes.
- Synthesized structured-output.start gained threadId — passive readers,
  no behavioral impact.

* fix(ai): address Round 2 CR findings on structured-output middleware

- Mid-finalization abort routes through onAbort (not onError):
  skip missing-result attribution when isCancelled()
- Finalization chunks no longer pollute agent-loop state:
  removed handleStreamChunk(chunk) call in runStructuredFinalization;
  targeted updates only for structured-output.complete + RUN_ERROR + RUN_FINISHED.usage
- Synth RUN_ERROR for empty-stream case is preceded by a synth
  structured-output.start so client-side StructuredOutputPart routing works

Call-site enumeration:
- handleStreamChunk removal: accumulatedContent (now agent-loop only;
  info.content stays clean of JSON deltas), finishedEvent /
  lastFinishReason (finalization no longer overwrites the agent loop's
  real finish reason), currentMessageId (unchanged path), currentThinking*
  (no thinking pollution), earlyTermination (irrelevant — finalization
  is already terminating). Explicit branches still capture
  structured-output.complete, RUN_ERROR (finalizationError), and
  RUN_FINISHED.usage (runOnUsage).
- isCancelled() early-return + chooser gating: run()'s finally block
  fires onAbort when !terminalHookCalled && isCancelled(). The terminal-
  hook chooser at the end of the try-block now additionally skips when
  isCancelled() so it can't pre-empt the finally with a stray onFinish.
- Pre-synth-start before synth-RUN_ERROR: uses the same
  buildSynthesizedStart() + pipeThroughMiddleware path as the in-loop
  synth, gated on !startEmitted so we never double-emit.

* fix(ai): align onFinish info docs with implementation

- Docs/skill no longer claim onFinish.info.usage reflects the full
  run including finalization tokens. The Round 2 fix correctly
  segregated finalization state; info.* reflects the agent loop's
  terminal state only.
- Add unit test pinning the documented semantics: tools-less
  structured-output run gives info.usage=undefined, finishReason=null,
  content='', while onUsage fires once for finalization tokens.

* fix(ai): clarify tools on StructuredOutputMiddlewareConfig is not forwarded to the structured-output adapter call

Round 4 CR finding: tools is structurally inherited from ChatMiddlewareConfig
but the engine omits tools from structuredCallOptions.chatOptions. Document
the caveat in the type JSDoc and the public middleware reference so middleware
authors don't expect tools transformation at this boundary to take effect.

* fix(ai): align runStreamingStructuredOutput JSDoc with implementation

Round 5 CR finding: the JSDoc claimed "Validates the parsed object against
the original Standard Schema" but the implementation explicitly defers
validation to the consumer (via `void outputSchema`). Update the JSDoc to
honestly describe the streaming-path validation policy and call out the
deliberate asymmetry with `runAgenticStructuredOutput` (which does validate).

* fix(docs): clarify server-side validation is path-dependent (streaming vs Promise<T>)

Round 6 CR finding: docs/structured-outputs/overview.md claimed "Server-side
validation against your schema is always authoritative" but the streaming
path (chat({ outputSchema, stream: true })) deliberately defers validation
to the consumer. Update the prose to reflect the actual path-dependent
behavior — agentic Promise<T> validates server-side; streaming forwards
the adapter event verbatim and consumers validate downstream.

* fix(ai): apply Procedure 3 bucket-(c) audit promotions

Bucket (c) Promotion Audit (cr-loop final step) flagged 4 items as load-bearing on the structured-output subject this PR makes authoritative:

- PROMOTE_TO_A: runAgenticStructuredOutput was calling convertSchemaToJsonSchema without forStructuredOutput: true while runStreamingStructuredOutput did. Same Zod schema produced different JSON Schema depending on stream mode. Both paths now use the strict converter, eliminating the divergence.

- PROMOTE_TO_B (3 trivial fixes on PR-adjacent surfaces):
  - fallbackStructuredOutputStream's IDs prefixed 'mock-' in production code; renamed to 'fallback-' to stop leaking test-style identifiers into user-visible run/thread/message IDs for Anthropic/Gemini/Ollama structured-output runs.
  - fallbackStructuredOutputStream's RUN_ERROR chunk was missing threadId while sibling RUN_STARTED and RUN_FINISHED carried it; added for consumer correlation.
  - chat() JSDoc example used chunk.type === 'content' (wrong); changed to 'TEXT_MESSAGE_CONTENT'.

26 other bucket-(c) items confirmed STAY_IN_C (pre-existing, not subject-load-bearing) and are reported to the loop-exit follow-up list. 1 item (gpt-5.2 model existence) REFUTED.

* ci: apply automated fixes

* fix(ai): address PR #600 review — critical + important findings

- Skip agent loop when finalStructuredOutput is set and tools.length === 0
  to avoid a wasted chatStream round-trip before finalization (Critical #1).
- Omit `tools` structurally from StructuredOutputMiddlewareConfig — the
  field was inherited but silently discarded at the provider boundary
  (Important #2).
- Preserve Standard Schema `issues[]` on validation failures via a new
  exported StandardSchemaValidationError carried as `error.cause`
  (Important #4).
- Preserve the original adapter error (stack, cause, provider properties)
  on the fallbackStructuredOutputStream path via an onAdapterError
  callback (Important #5).
- Add tests for messages-transform via onStructuredOutputConfig and for
  mid-finalization abort routing through onAbort (Important #6, #7).
- Strip transitional source comments ("in Task 7", "closes issue #390").

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(examples): add /verify-pr600 page to ts-react-chat

Adds a diagnostics page in the ts-react-chat example that exercises all
four PR #600 review fixes against the real chat() engine using inline
mock adapters. No API keys required — click "Run verification" and see
pass/fail per scenario with observed values.

- POST /api/verify-pr600 runs the four scenarios server-side.
- /verify-pr600 page calls the endpoint and renders results.
- Header nav gains a "Diagnostics" section linking to the page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(examples): replace verify-pr600 with real-provider repros

The mock-based verify-pr600 page only validated my own fixes; it didn't
prove anything about real provider wire formats. Replace with two
real-provider verifications:

- New /issue-390-repro page runs the exact gist from the issue reporter
  (@imsherrill) against geminiText('gemini-2.5-flash') and surfaces the
  middleware logs + per-phase chunk counts. Fix is verified iff the
  middleware observed any chunks with ctx.phase === 'structuredOutput'.
- Existing /generations/structured-output page now instruments every
  request with a counter middleware. Counts surface via a JSON field
  (non-streaming) or a trailing CUSTOM `phase-counts` event (streaming).
  Works across all configured providers (OpenAI/Anthropic via OpenRouter,
  Gemini via OpenRouter, Grok, Groq).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(examples): drop /issue-390-repro page

The counter middleware on /generations/structured-output already
demonstrates the PR #600 fix against real providers — the dedicated
single-shot repro page is redundant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ai): drop unused ChatMiddlewarePhase import after merge

Surfaced by tsc after merging origin/main (the eslint-config 0.4.0
bump in #607 strengthens unused-import detection). The type is
re-exported elsewhere and not referenced inside this file.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

* fix: address CI lint + openrouter test failures

- Remove unnecessary `as object` cast in compose.ts; the upgraded
  typescript-eslint (via #607) flags it as unnecessary because
  `Object.keys` already accepts the original type.
- Update the openrouter `chat() entrypoint with strict transformation`
  test: with Critical #1 (skip agent loop when tools.length === 0),
  the engine no longer consumes the streaming mock for an empty agent
  pass — the structured-output payload now arrives via the same
  streaming mock that previously held the placeholder 'ok' delta.
  Move the JSON payload into the streaming mock and assert via
  `responseFormat` presence instead of `stream === false`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 07:42:50 +02:00
github-actions[bot]
1e4df18355
docs: regenerate API documentation (#598)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-20 17:50:01 +02:00
github-actions[bot]
308468d9e2
docs: regenerate API documentation (#592)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-20 11:20:10 +02:00
github-actions[bot]
229cdbd1ae
docs: regenerate API documentation (#590)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-19 23:59:36 +02:00
github-actions[bot]
dca370bb06
docs: regenerate API documentation (#585)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-19 18:45:56 +02:00
github-actions[bot]
6a23e80efe
docs: regenerate API documentation (#566)
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-16 23:45:36 +02:00