* 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>
* 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>
* 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>
* 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
* 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>
* 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>
* 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
* 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>
* 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>
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`.
* 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>