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

11 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
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
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
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
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
Renamed from docs/guides/code-mode.md (Browse further)