mirror of
https://github.com/TanStack/ai.git
synced 2026-11-16 19:38:41 +00:00
11 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
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. |
||
|
|
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> |
||
|
|
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> |
||
|
|
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>
|
||
|
|
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> |
||
|
|
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> |
||
|
|
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
|
||
|
|
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`.
|
||
|
|
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. |
||
|
|
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> |
||
|
|
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> |
Renamed from docs/guides/code-mode.md (Browse further)