0
Fork 0
mirror of https://github.com/TanStack/ai.git synced 2026-11-16 19:38:41 +00:00
Commit graph

16 commits

Author SHA1 Message Date
Tom Beckenham
c675499fea
docs: consolidate quick starts and sort guides by build path (#1274)
* docs: reorder sidebar, split streaming, and use install tabs

Put Guides in build-path order (chat first). Split streaming into stream
events and message queue. Replace stacked npm/pnpm/yarn fences with
package-manager tabs, including Octane.

* docs: consolidate quick starts and raise structured outputs

One Quick Start page switches client snippets with the selected
framework. Vue, Svelte, Angular, and Octane pages redirect into it.
Structured Outputs sits after Chat in the Guides sidebar.

* docs: put middleware after tools and sort guides by build path

Guides now follow the chat path: stream, structured output, tools,
middleware, interrupts, then MCP. Chat children start with the stream
and leave queueing last.
2026-08-31 10:43:31 +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
SilvioYMollov
44a3848308
feat(ai-isolate-quickjs): support custom WASM locations (#1099)
* feat(ai-isolate-quickjs): adding support for wasmLocation option for QuickJsWASM driver and documentation update

* Update docs/config.json

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* feat(ai-isolate-quickjs): standardize code formatting

* fix formatting

* ci: apply automated fixes

* fix(docs): import createQuickJSIsolateDriver in wasmLocation snippet

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
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-14 13:17:25 +02:00
Muhammad Hashmi
8a159db787
feat: add Daytona Code Mode isolate driver (#645)
* feat: add Daytona Code Mode isolate driver

* fix: clear Daytona timeout timers

* docs: clarify Daytona isolate driver positioning

* chore(ai-isolate-daytona): use oxlint to match repo lint convention

The package shipped eslint lint scripts (lint:fix/test:eslint) while the
rest of the monorepo standardized on oxlint. This left the package's
source outside the CI lint gate (nx affected --target=test:oxlint skipped
it) and tripped knip with an unlisted 'eslint' binary. Align with sibling
drivers (oxlint src --type-aware).

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

* fix(ai-isolate-daytona): align @daytona/sdk to ^0.191.0 to satisfy sherif

Merging main brought in @tanstack/ai-sandbox-daytona, which depends on
@daytona/sdk@^0.191.0. This package still pinned ^0.180.0, so sherif's
multiple-dependency-versions rule failed the Test job (single-version policy
across the workspace).

Bump the devDependency to ^0.191.0 to match. It stays a devDependency: this
driver is bring-your-own-SDK (the caller passes a Daytona sandbox via the
`DaytonaSandboxLike` structural type and the driver never imports @daytona/sdk
at runtime), so the SDK is only needed for dev/type-checking. Build, types,
oxlint, and the unit suite all pass against 0.191.0.

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

---------

Co-authored-by: Jack Herrington <jherr@pobox.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
2026-08-07 14:18:02 +02:00
Kenta Iwasaki
b2b82e4f88
feat(ai-isolate): add native QuickJS Code Mode isolate driver for Bun (#750)
* feat(ai-isolate): add native QuickJS Code Mode isolate driver for Bun

Adds @tanstack/ai-isolate-quickjs-bun, a Code Mode IsolateDriver that
runs QuickJS natively on the Bun runtime via bun:ffi (through
quickjs-bun) instead of WebAssembly. It is a drop-in replacement for
@tanstack/ai-isolate-quickjs on Bun servers.

- Per-context native QuickJS runtime with its own memory/stack/timeout
  limits; contexts execute independently (the WASM driver serializes all
executions through one asyncified module).
- Same JSON tool-call protocol, console prefixes, and normalized
  MemoryLimit/StackOverflowError/DisposedError contract as the other
drivers, plus a normalized TimeoutError for deadline expiry.
- maxToolCalls (default 1000) and conosle log caps to bound stack and
  memory growth from untrusted snadbox code.
- Requires Bun >= 1.3.14; throws an error on Node.js.

Unit tests mirror the WASM/Node suites and run under `bun test`; the
Node-side rejection test runs in normal CI. Docs, the ai-code-mode
README + skill, and the code-mode example have been updated.

* fix: docs/code-mode/code-mode-isolates.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* fix(ai-isolate-quickjs-bun): address review feedback

Correctness:
- Classify fatal OOM/stack-limit errors thrown as Error *objects* (not just
  bare-null) as fatal so an exhausted VM is released, not reused, by routing
  the recovered name/message back through normalizeError.
- When vm.dump throws while materializing a tool call's args (sandbox heap
  exhausted), surface it via hostSettleError and abandon the call instead of
  running the host tool with empty {} args.
- Drain the QuickJS job queue between runs so a prior aborted/timed-out
  execution's queued promise reactions can't bleed their output, tool-call
  budget, or wall-clock into the next execution (+ regression test).
- Rename MAX_LOG_BYTES/logBytes -> MAX_LOG_CHARS/logChars to match the actual
  UTF-16 code-unit measure.

Docs / metadata:
- Close the unterminated YAML frontmatter in code-mode-isolates.md, fix the
  broken `external_*` inline code, and add the missing maxToolCalls option row.
- Soften the isolate-driver "fully isolated from the host" wording: this is an
  in-process bun:ffi VM, not an OS/VM sandbox boundary.
- Fill in package.json author/homepage/bugs/funding; pin quickjs-bun exactly
  and document the pre-1.0 supply-chain/compat caveat in the README + changeset.
- Convert the package's stray eslint scripts to oxlint (repo convention; also
  brings its source under the CI lint gate and clears knip).
- Document that the full behavioral suite is Bun-only (test:bun).

Example:
- Gate the "QuickJS Bun" sidebar option honestly: create-isolate-driver falls
  back to QuickJS (WASM) with a warning when not running under Bun, and the
  option description states the requirement.

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

* ci(ai-isolate-quickjs-bun): run the Bun-gated test suite in CI

The driver's substantive suite (escape attempts, timeouts, memory limits,
maxToolCalls, concurrency) is gated behind `describe.skipIf(typeof Bun ===
'undefined')` and only runs under Bun. The Node PR job exercised only the
"rejects on Node.js" case, leaving that behavior unverified in CI.

Add a separate, path-filtered `Bun Tests` workflow that installs Bun, builds
the package's workspace dependencies via nx (`@tanstack/ai-code-mode` is a
runtime peer dep), and runs `test:bun`. Path-filtered to the package so it
stays off unrelated PRs.

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

* fix(workspace): stop @types/bun from polluting other packages' global types

Adding @types/bun as a devDependency of @tanstack/ai-isolate-quickjs-bun let
pnpm hoist it into the shared virtual store (node_modules/.pnpm/node_modules),
where it became resolvable workspace-wide. Unrelated deps in the nitro/SSR
stack (srvx, crossws) carry phantom `import "bun"` type statements that
previously no-op'd; once @types/bun was reachable they resolved to it and
pulled bun-types into every dependent's `tsc` run. bun-types globally
redeclares `fetch` with `init: RequestInit | BunFetchRequestInit`, dropping the
DOM `preconnect` member, which broke `@tanstack/sandbox-web-example:test:types`
(and any other app using `typeof fetch`).

Exclude @types/bun from the shared hoist so only its direct dependent resolves
it via its own node_modules symlink. quickjs-bun still type-checks, builds, and
passes its Bun test suite; sandbox-web no longer pulls in bun-types.

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

* fix(ai-isolate-quickjs-bun): make Bun isolate work under Vite/Start demos

Load quickjs-bun via Bun-aware path resolution and a host-native dynamic
import so Vite's module runner no longer fails package exports or inlines
bun:ffi sources. Add CODE_MODE_BUN/dev:bun for ts-code-mode-web (default
VM quickjs-bun, Nitro bun preset, SSR-only bun resolve conditions), runtime
sidebar warnings, and richer execute_typescript tracing (phase, stack,
execution_finished events).

* refactor(ts-code-mode-web): simplify Bun Vite config

Drop the quickjs-bun path walker/plugin/alias. Keep the working pattern:
browser-only client resolve conditions, bun on SSR only, externalize
quickjs-bun + the isolate driver, and CODE_MODE_BUN/Nitro bun preset.

* ci: apply automated fixes

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Jack Herrington <jherr@pobox.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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-08-07 11:05:31 +02:00
Alem Tuzlak
fbd37623b2
feat(code-mode): lazy tool support (progressive disclosure) (#726)
* feat(ai): add shared LazyToolsConfig and thread it through chat lazy discovery

Introduces a single optional LazyToolsConfig ({ includeDescription:
'none' | 'first-sentence' | 'full' }, default 'none') plus shared
renderLazyCatalogEntry/firstSentence helpers. chat() now accepts
lazyToolsConfig and threads it into LazyToolManager, which renders the
discovery-tool catalog accordingly. The 'none' default is byte-identical
to the previous names-only output.

* feat(code-mode): add lazy tool support with discover_tools catalog

Tools marked `lazy: true` are kept out of the execute_typescript system
prompt (their type stubs omitted) and listed in a "Discoverable APIs"
catalog instead. A new discover_tools companion tool returns each lazy
tool signature on demand; lookups tolerate the optional external_ prefix
so the model can pass the catalog name verbatim. All tool bindings are
still injected into the sandbox (documentation-only lazy). createCodeMode
now returns { tool, discoveryTool, tools, systemPrompt } (additive;
tool/systemPrompt unchanged) and honors the shared lazyToolsConfig.

* test(e2e): cover chat lazyToolsConfig discovery catalog

Adds a wire-journal E2E (api.lazy-tools-wire route + fixture + spec) that
asserts the lazy discovery tool's wire description renders names-only for
'none', name plus first sentence for 'first-sentence', and the full
description for 'full'. routeTree.gen.ts is the router plugin's auto-regen
for the new route.

* docs: add code-mode lazy tools page, update skills, add changeset

New docs/code-mode/lazy-tools.md (with config.json nav entry) covering
lazy tools, the discover_tools flow, and lazyToolsConfig.includeDescription
for both Code Mode and plain chat(). Updates the ai-code-mode and
ai-core/tool-calling agent skills to document the new API, and adds the
changeset (minor for @tanstack/ai and @tanstack/ai-code-mode).

* docs: document lazyToolsConfig on the lazy tool discovery page

The chat lazy-tool discovery page now documents the new optional
lazyToolsConfig.includeDescription ('none' default / 'first-sentence' /
'full') that tunes the pre-discovery catalog, with a cross-link to the
Code Mode lazy tools page. Bumps the example model ids to gpt-5.2 and
sets updatedAt on the docs config entry.

* chore: address PR review feedback

- Use gpt-5.5 (newest OpenAI chat model in model-meta) in docs, skill,
  and the e2e route instead of gpt-5.2.
- e2e: drop the beforeEach DELETE /v1/_requests journal reset; the spec
  already isolates per-test via the X-Test-Id header, so the global reset
  only risked racing adjacent parallel specs.
- Alphabetize vitest named imports in the two new test files (sort-imports).
- Add `text` language identifiers to the Discoverable APIs example fences
  in the lazy-tools doc and code-mode skill (markdownlint).

* fix(docs): make lazy-tools snippets type-check under kiira after main merge

Main introduced the kiira docs type-checker. Make the lazy-tools doc
snippets self-contained (real imports, endpoint-wrapped messages, relative
tool imports) and group the sequential server-setup example. Exclude
docs/superpowers/** planning artifacts (illustrative pseudo-code, not
published examples).
2026-06-25 12:42:22 +02:00
Alem Tuzlak
c9175ed97f
ci(docs): type-check doc code samples with kiira (#805)
* ci(docs): type-check doc code samples with kiira

Add kiira to type-check the TS/TSX/JS/JSX code fences in /docs against the
real package APIs, and wire it into the CI quality gate so doc examples
can't drift from the SDK.

- Add kiira devDependency + kiira.config.ts: checks docs/**/*.md, excludes
  the auto-generated docs/reference/**, enables the JSX runtime per
  framework, and provides an `ambient` fixture for illustrative
  messages/message values. No tsconfig.docs.json.
- Add `test:kiira` script; include it in the test:pr/test:ci nx target
  lists, nx.includedScripts, and an nx cache target (nx.json).
- knip: ignore kiira.config.ts (consumed by the kiira binary, not imported).
- Fix the type errors kiira surfaced across 81 docs: add missing imports,
  group continuation fences, import arbitrary placeholders from relative
  modules, and fix real API drift (e.g. toolDefinition now requires
  `description`, ContentPartUrlSource uses `value`, chat passes tools via
  `tools`/modelOptions). Genuinely un-checkable fences (competitor SDKs,
  uninstalled community adapters, framework route-registration boilerplate)
  are marked `ignore`.

* ci: apply automated fixes

* fix(docs): exclude Angular docs from kiira (ng-packagr entry not source-resolvable)

@tanstack/ai-angular ships only dist/types/*.d.ts (ng-packagr), which kiira's
dist->src resolution heuristic can't map to a source file, so its docs only
type-check against the built bundle. That isn't available during a source-based
docs check (and a docs-only PR builds nothing), so kiira failed on
@tanstack/ai-angular imports in CI. Exclude the two Angular docs until the
package exposes a source-resolvable entry.

* docs(kiira): use real minimal setup instead of declare/ambient/group-rename

Refine the doc snippets per review:
- Remove the ambient fixture and every `declare const`; show real minimal
  setup instead (extract messages from the request in a server endpoint, a
  minimal messages literal, import+create an adapter, define/import tools).
- Isolate snippets that were grouped only to share state via renamed
  duplicates (client/client1, stream/stream2, chatSSE/chatHTTP, adapter
  variants) — each fence now stands alone with natural names, importing shared
  setup from a relative module where needed.
- Drop callback return-type annotations added only to satisfy the checker;
  set noImplicitReturns:false for doc snippets so partial control flow in
  illustrative callbacks is fine.
- Replace remaining gpt-4o usages touched along the way with current model ids.

Kiira: 596 snippets pass, 0 fail (more snippets now actually checked, fewer
ignored).

* docs(kiira): inline tool definitions so client tool input infers (no input: any)

The framework-hook examples imported tool definitions from an unresolved
relative module, so .client() callbacks fell back to (input: any). Define the
toolDefinition() inline (name + description + inputSchema) so the callback param
infers from the schema — the tools are fully type-safe, the any was masking a
missing definition.

* chore(lessons): capture kiira doc-snippet authoring + CI-setup lessons

* docs(kiira): infer tool callback input from inline schema (drop hand-typed params)

* ci: apply automated fixes

* docs(kiira): type-check third-party libs via externalPackages (kiira 0.5.0)

Upgrade kiira to 0.5.0 and declare the third-party packages the docs import
(Vercel AI SDK, openai, arktype/valibot, redis/pino/@opentelemetry/api/express/
hono, @modelcontextprotocol/sdk, and the community adapters) under
externalPackages, so kiira installs them into an isolated cache and type-checks
against the real types instead of ignoring those fences. Un-ignored ~67 fences
across migration/comparison, community-adapters, advanced (redis/pino/otel),
mcp, structured-outputs, and server quick-starts -- catching real API drift in
the examples along the way. Remaining ignores are genuine: removed/old TanStack
APIs in before-code, framework route boilerplate, MCP/cencori subpath exports
kiira's external resolver can't map yet, and a couple of pseudo-code blocks.

Kiira: 663 snippets pass, 0 fail, 147 ignored (was 596 / 214).

* docs(kiira): keep express snippets ignored (workspace-shadowed, no @types)

express@5 is a transitive workspace dep without @types, shadowing the
externalPackages cache copy in CI (TS7016). Drop express/@types/express from
externalPackages and re-ignore the two express server snippets.

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-06-24 06:38:42 +00:00
Tom Beckenham
6caac6b528
fix(ai-code-mode-skills): make root export Worker/browser-safe (#486) (#736)
* fix(ai-code-mode-skills): make root export Worker/browser-safe (#486)

The root entry re-exported `createFileSkillStorage` via `export * from
'./storage'`, eagerly pulling in `node:fs`/`node:path`. This broke
Cloudflare Workers and browser bundlers even for consumers that only used
non-storage helpers like `createSkillManagementTools`.

The Node-only file storage now lives only behind the
`@tanstack/ai-code-mode-skills/storage` subpath. The root re-exports only
the browser-safe `createMemorySkillStorage`. Docs, README, JSDoc, and a
changeset are updated, plus a regression test that walks the root module
graph (static + dynamic imports) and asserts it reaches zero `node:`
builtins and that the public export surface is correct.

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-06-23 10:55:19 +02:00
Season Saw
81e3aee318
fix(code-mode): drop esbuild for edge-safe TypeScript stripping (#487) (#799)
* fix(code-mode): drop esbuild for edge-safe TypeScript stripping (#487)

@tanstack/ai-code-mode hard-depended on esbuild to strip TypeScript before
sandbox execution. esbuild ships a Node-native binary and pulls in Node-only
built-ins (e.g. require("pnpapi")), which broke browser bundles and edge
runtimes such as Cloudflare Workers/Pages.

Replace esbuild with sucrase, a pure-JavaScript transform with no native
binary, on the default TypeScript-stripping path. Add an optional `transpile`
escape hatch on createCodeModeTool so callers who don't need edge safety can
swap in a heavier Node-only transpiler (e.g. esbuild).

sucrase is a type-stripper rather than a down-leveler, so unlike esbuild it
does not compile a few exotic constructs (value `namespace` blocks, decorators,
the `accessor` keyword, post-ES2022 syntax such as `using` and the `/v` regex
flag). These are documented on stripTypeScript and in the changeset, with the
transpile hook as the workaround.

Add an edge-safety guard test asserting no source imports esbuild or a
Node-only built-in, and keep the dependency out of every install-facing bucket.

* test(code-mode): escape module names in edge-safety import scan

Escape regex metacharacters before interpolating each FORBIDDEN entry into
the import-scan pattern. The current entries contain no metacharacters, so
behavior is unchanged, but this keeps the pattern correct if an entry ever
contains one and silences a static-analysis ReDoS warning.

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-06-22 14:11:49 +02:00
Alem Tuzlak
afb2960a8c
docs: use tsx code fences for JSX examples (#710)
36 code blocks containing JSX (React/Solid/Preact components) were fenced as ```typescript. Re-fence them as ```tsx so editors and the docs site highlight the JSX correctly. No ```ts blocks contained JSX; the mislabeled ones were all ```typescript.
2026-06-05 12:54:52 +02:00
Alem Tuzlak
b906666fa6
docs: fix inaccurate code samples and expand coverage across guides (#691)
* docs: fix inaccurate code samples and expand coverage across guides

Audited all guide pages against the actual package APIs and fixed
copy-paste-broken / outdated samples and filled coverage gaps.

Middleware & structured outputs:
- New Built-in Middleware page (toolCache, contentGuard, otel) + new
  top-level Middleware nav section; document structured-output chunk
  transforms via onChunk + ctx.phase; fix middleware type import paths.
- Document client consumption (useChat partial/final) on the one-shot page.

Correctness fixes (verified against packages/ source):
- chat: providerOptions -> modelOptions; invalid model ids; budget_tokens
  requires maxTokens; async stream() factory -> fetcher; add missing
  imports; document default maxIterations(5) and agentLoopStrategy.
- tools: toServerSentEventsStream -> toServerSentEventsResponse; remove
  duplicate tools key; clarify tool-call vs tool-result states; fix the
  React examples and state diagram; add emitCustomEvent / runtime-context.
- media: add required model args to factory calls; fix recursive
  generateVideo; TranscriptionResult.words is top-level; speed is a
  top-level speech option; Gemini audio returns b64Json; onResult transform.
- advanced: adapter.model (not selectedModel); GeminiImageMetadata;
  source.mimeType; text.format structured-output shape; fill How It Works;
  createModel capabilities form; soften unsubstantiated bundle figures.
- protocol: rewrite SSE / HTTP-stream pages to the AG-UI event format
  (drop obsolete chunk shapes and [DONE]); use toHttpResponse/toHttpStream;
  expand chunk-definitions with TOOL_CALL_RESULT, MESSAGES_SNAPSHOT,
  REASONING_* and deprecated-alias notes.
- adapters: elevenlabs SFX model + @elevenlabs/client; ollama modelOptions
  placement; cencori AG-UI event/tools alignment.
- fix @tanstack/ai-openai/adapters -> @tanstack/ai-openai (ag-ui-compliance, otel).

* docs: address CR-round findings (correctness + latest models)

A 7+1-agent confirmation review of the docs PR surfaced further
source-accuracy issues (and caught one regression the first fix pass
introduced). All verified against packages/ source:

- tools/server-tools: JSON-schema tool input is `unknown` (not `any`);
  samples now narrow/cast args.
- thinking-content: drop the adaptive-thinking / output_config.effort
  example — those option types are not wired into any model's typed
  modelOptions; document the `{ type: 'enabled', budget_tokens }` form.
- multimodal-content: correct the Anthropic modality bullets (no
  `claude-3*` ids; Claude Haiku 3 supports documents).
- comparison: fix the ImagePart (`source: { type:'url', url }`) and
  TextPart (`content`) shapes in the flagship example.
- chunk-definitions: RUN_STARTED/RUN_FINISHED `threadId` is required;
  add REASONING_MESSAGE_CHUNK to the internal-members note.
- media: createOpenaiVideo needs a model arg; video `seconds` is a
  string union; transcription `responseFormat`/`prompt` are top-level
  (not modelOptions); drop the non-existent gpt-4o-mini-audio-preview
  TTS model; add the Audio row to the generations table.
- advanced: typed-options gpt-image-1 size must be a GptImageSize.
- observability: aiEventClient imports from @tanstack/ai-event-client
  (the @tanstack/ai/event-client subpath does not exist).
- adapters: revert claude-haiku-3 -> claude-3-haiku (the id passed to
  anthropicText); clarify max_tokens auto-adjust; @elevenlabs/client
  (not @11labs/client); elevenlabs agentId optional, debug is DebugOption.
- structured-outputs: Standard JSON Schema /json-schema link; Zod v4.2+.

Model ids touched in these fixes use the latest per provider from
model-meta.ts (gpt-5.5, claude-sonnet-4-6, etc.).

* docs: use latest per-provider models in examples

Sweep example model ids across the PR's docs to the latest available
per provider, sourced from each adapter's model-meta.ts:
- OpenAI: gpt-5.2 -> gpt-5.5, gpt-5-mini -> gpt-5.4-mini
- Anthropic: claude-sonnet-4-5 -> claude-sonnet-4-6,
  claude-opus-4-6 -> claude-opus-4.8
- Gemini: gemini-2.0-flash -> gemini-3-flash-preview,
  image -> gemini-3.1-flash-image-preview, tts -> gemini-3.1-flash-tts-preview

Every replacement id was verified present in model-meta.ts. Intentional
cases preserved: negative/capability-contrast examples
(per-model-type-safety), the claude-3-haiku web_search note, model
enumeration/availability tables, DALL-E and o-series demos, and the
Cencori pass-through ids (external provider, no in-repo model-meta).

* docs: reconcile thinking examples with modelOptions sampling convention

After rebasing onto main (which merged #660 moving temperature/topP/
maxTokens into modelOptions), fix the two spots where our edits still
assumed top-level sampling:
- thinking-content.md: max_tokens now lives in modelOptions alongside
  the thinking budget (was a top-level maxTokens).
- anthropic.md: drop the stale "auto-raises top-level maxTokens" note;
  budget_tokens must be below modelOptions.max_tokens.

(ollama.md and typed-options.md conflicts were resolved to main's new
convention during the rebase.)

* docs: migrate ag-ui-compliance forwardedProps allowlist to modelOptions

The "safe allowlist" example still forwarded temperature/maxTokens as
top-level chat() options (missed by #660's sampling-into-modelOptions
migration). Map them into modelOptions under OpenAI's native keys
(temperature / max_output_tokens) so the example type-checks.

* docs: remove deprecated observability + protocol pages, drop all casts

- Remove the deprecated Observability page (event-client observability is
  superseded; otelMiddleware is the supported path) and its nav entry +
  inbound links.
- Remove the protocol pages (chunk-definitions, sse-protocol,
  http-stream-protocol) — TanStack AI implements AG-UI, whose protocol is
  documented upstream; repoint the few inbound links to docs.ag-ui.com.
- Fix the broken ToolCacheStorage snippet (it imported the type then
  re-declared it) and verify the shape against source.
- Remove every `as <Type>` assertion cast from the docs (JSON-schema tool
  inputs, JSON.parse, formData, custom-event values, type brands, …),
  replacing them with typeof/in guards, type guards, typed annotations, or
  schema validation. `createModel`'s provider-option brand now uses a typed
  const instead of `{} as X`.
- CLAUDE.md / AGENTS.md: codify the docs conventions — no `as` casts in
  samples, use the latest model per provider from model-meta.ts, and show
  both server and client sides when a doc spans both.

* docs: latest model in built-in-middleware + concrete structured-output transform

- built-in-middleware.md: gpt-4o -> gpt-5.5 in the examples.
- middleware.md: make the "Transforming structured-output chunks" example
  self-contained — redact SSNs inline in the streaming JSON delta instead of
  calling an undefined `redact()` helper.

(The docs conventions — no casts, latest models, show both sides — already
live in the project CLAUDE.md / AGENTS.md; the earlier global-CLAUDE.md
addition has been reverted.)
2026-06-03 14:15:43 +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
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
Alem Tuzlak
2d1fd08e88
docs: add agent-skills guide and SEO frontmatter (#464)
Add a new getting-started/agent-skills.md guide explaining how to use
@tanstack/intent install to wire the bundled Agent Skills from
@tanstack/ai and @tanstack/ai-code-mode into Claude Code, Cursor,
GitHub Copilot, and other AI coding assistants, register it in
docs/config.json, and add a disambiguation callout on
code-mode-with-skills.md so readers searching for "skills" land on the
correct page.

Add description and keywords frontmatter to all 64 hand-authored docs
for search-engine discoverability. Auto-generated TypeDoc reference
pages under docs/reference/ are left untouched since they would be
overwritten on the next regeneration.

A follow-up PR on tanstack.com will wire these fields into the document
head.
2026-04-17 12:19:14 +02:00
Jack Herrington
3490da975b
docs(code-mode): add model compatibility table (#427)
Adds a "Model Compatibility" section to the Code Mode docs showing
benchmark results for 7 models against the database-demo gold prompt
(accuracy/comprehensiveness/TS quality/code-mode efficiency, plus
latency and tokens). Highlights best cloud and local picks and lists
models to avoid.

Also adds Gemma 4 31B to the eval-config working list and refreshes
results.json with the latest session.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-09 01:23:52 +02:00
Alem Tuzlak
49ade0a22f
docs: restructure sidebar and add code mode client integration guide (#425)
* docs: restructure sidebar into thematic sections and add code mode client integration guide

Split the flat "Guides" sidebar section (27 pages) into 6 thematic sections:
Tools, Chat & Streaming, Code Mode, Media, Advanced, and Migration. Added a
new "Showing Code Mode in the UI" guide covering onCustomEvent and real-time
execution rendering. Improved existing code mode docs with journey framing,
install steps, cross-links, and removed internal benchmark content.

* ci: apply automated fixes

* docs: remove superpowers specs/plans from git and add to gitignore

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-04-07 13:39:17 +02:00