@tanstack/ai-code-mode

Major Changes

• breaking

  TanStack AI 1.0.0. This release removes every API that was deprecated in 0.x. Read the upgrade guide before you upgrade: tanstack.com/ai/latest/docs/migration/v1

  • Removed all @deprecated exports, options, fields, and type aliases. Each one has a replacement that already shipped in 0.x.

  • Removed addToolApprovalResponse() from ChatClient and every chat hook. Resolve the bound tool-approval interrupt with resolveInterrupt instead. The devtools event tools:approval:responded is also removed.

  • Removed the old wire formats: the CUSTOM approval-requested and tool-input-available events, the [DONE] SSE line, the data copy of forwardedProps, pre-binding interrupt descriptors and their approval_required and client_tool_input reasons, and the STEP events that adapters sent next to REASONING_* events. Use a 1.0 client with a 1.0 server.

  • Removed the toolName alias from TOOL_CALL_START chunks. Read toolCallName instead.

  • threadId is now required on useChat and every other chat hook, ChatClient, the generation hooks and clients, chat(), summarize(), the generation functions, codeModeWithSnippets(), selectRelevantSnippets(), CompactionContext, and SummarizeInput. TanStack AI no longer makes a thread id for you. Pass a stable id for each conversation. createChatHook factory options no longer take threadId: pass it on each hook call. Octane generation hooks take threadId instead of id. @tanstack/ai-sandbox removes resolveDurableThreadId and DurableThreadIdRequiredError.

  • The published @tanstack/ai-octane/ui types are now strict. UI.Messages, UI.Message, UI.Part, and UI.Interrupts type their render children. ToolProps types part.input and part.output for the named tool. toolsComponents and interruptsComponents are required when the chat options declare tools or named interrupts. Code that relied on the old loose types can fail to compile.

  • A connection adapter's connect() and send() need the run context (with threadId) as their fourth argument. ChatClient and the generation clients pass it.

  • @tanstack/ai-sandbox: createToolBridgeCore(), startHostToolBridge(), a ToolBridgeProvisioner, and executeHostTool() take a required threadId. Bridged tools get it in their context.

  • @tanstack/ai-sandbox: the harness tool bridge and executeHostTool() refuse a tool with needsApproval. Before, the tool ran with no approval. Remove needsApproval, or run the tool with an HTTP adapter.

  • stream() and rpcStream() pass the AG-UI RunAgentInput for the run as the fourth factory argument, the same body the HTTP adapters send. Read it on the server with chatParamsFromRequestBody() or generationParamsFromBody(), so threadId, runId, and interrupt resume reach a server function. RunAgentInput is exported from @tanstack/ai/client.

  • A generation fetcher gets threadId and runId in its second argument, next to signal and headers. Pass them to the server generation call.

  • generationParamsFromBody() and generationParamsFromRequest() read the generation input from forwardedProps. A server that reads body.data gets undefined. Read body.forwardedProps instead. They also require threadId and runId and return them as strings, the same as chatParamsFromRequestBody() and the AG-UI RunAgentInput. A body that holds only the input is rejected.

  • Removed the readers for data saved in old 0.x formats (old Cloudflare run-log records, a bare UIMessage from client persistence, artifact records without blobKey).

  • Removed provider models that are shut down.

  • @tanstack/ai-react-ui, @tanstack/ai-solid-ui, and @tanstack/ai-vue-ui get no 1.0 release. Import from @tanstack/ai-react/ui, @tanstack/ai-solid/ui, or @tanstack/ai-vue/ui.

Minor Changes

• Add @tanstack/ai-code-mode/harness with codeMode({ driver }): a harness plugin that gives the model one execute_typescript tool. The model writes a program that calls several tools, and the program runs in the isolate of any @tanstack/ai-isolate-* driver.

  • By default, only tools that are safe to run without a question move into code mode. These are server tools with no needsApproval and no permission resources, which the permission rules allow in plan mode. A safe tool with metadata.codeMode: true always moves.

  • include picks more tools, also tools with permission checks, such as the coding tools read_file, write_file, edit_file, patch, list_files, grep, bash, and webfetch. Each call of such a tool in a program gets the same decision from permissions() as a direct call. The call runs, or it throws an error with the reason, or the program waits for the user to approve it. The approval is a question wait that session.answer answers with once, always, or reject. A program that can wait gets a timeout of 10 minutes by default.

  • The session log keeps the result of each checked call. After a stop, the next host runs the program again, and a call that finished before the stop does not run twice. A call that the stop cut, and that is not safe to run again, throws in the program.

  • include never moves a tool that needs approval, or a tool that the rules deny in the current permission mode. The rules decide again at each turn, so in plan mode the tools that edit stay normal tool calls.

  • directCalls: 'keep' keeps the moved tools in the model's tool list too. The session setting directCalls changes it while the session runs.

  • lazy: true lists only the tool names and adds discover_tools. A tool name that is not a JavaScript identifier gets a safe name inside the program.

  @tanstack/ai-harness is an optional peer dependency.

Patch Changes

• The execute_typescript tool description and the code-mode system prompt now tell the model that the tool returns { success, result, logs, error }, where result is the value its code returned.

• The mcp(), codeMode(), and skills() harness plugins send their warnings to the logger of the host (createHarnessHost({ logger })).

Patch Changes

• Pass the chat run's abortSignal and runtime context to the tools that Code Mode calls as external_* functions. A tool that listens to the signal now stops its in-flight work when the run stops, for example MCP tools. A call does not start when the run is already aborted. toolCallId and inputResponse of the execute_typescript call are not passed on.

Patch Changes

• Keep enum and const values and property descriptions in the generated Code Mode type stubs. A typed schema such as { type: 'string', enum: ['a', 'b'] } now renders as 'a' | 'b' instead of string, and property descriptions are emitted as JSDoc, as the includeDescriptions option of generateTypeStubs already documented.

Minor Changes

• Rename Code Mode "skills" to "snippets" to disambiguate them from agent skills (the SKILL.md packaging system).

  Breaking — package rename. @tanstack/ai-code-mode-skills is now published as @tanstack/ai-code-mode-snippets. Update your dependency and imports. The /storage subpath is unchanged.

  Breaking — API rename. Every Skill/skill identifier in the package public API becomes Snippet/snippet, for example:

  • codeModeWithSkills() → codeModeWithSnippets()

  • skillsToTools() / skillToTool() → snippetsToTools() / snippetToTool()

  • skillsToBindings() / skillsToSimpleBindings() → snippetsToBindings() / snippetsToSimpleBindings()

  • selectRelevantSkills() → selectRelevantSnippets()

  • createSkillManagementTools() → createSnippetManagementTools()

  • createSkillsSystemPrompt() → createSnippetsSystemPrompt()

  • generateSkillTypes() → generateSnippetTypes()

  • createFileSkillStorage() / createMemorySkillStorage() → createFileSnippetStorage() / createMemorySnippetStorage()

  • Types: Skill, SkillStorage, SkillIndexEntry, SkillStats, SkillBinding, SkillsConfig, CodeModeWithSkillsOptions/Result → the Snippet… equivalents

  • Options: skills → snippets, skillsAsTools → snippetsAsTools, maxSkillsInContext → maxSnippetsInContext

  • Runtime tools: search_skills / get_skill / register_skill → search_snippets / get_snippet / register_snippet

  • Sandbox bindings are now exposed with the snippet_ prefix (was skill_)

  Breaking — sandbox hook (@tanstack/ai-code-mode). The createCodeModeTool config option getSkillBindings is renamed to getSnippetBindings (same signature — an optional () => Promise<Record<string, ToolBinding>> returning dynamic bindings merged at execution time).

  Breaking — wire contract (@tanstack/ai). The Code Mode custom events are renamed: code_mode:skill_call / _result / _error → code_mode:snippet_* (payload field skill → snippet), and skill:registered → snippet:registered. The exported event types CodeModeSkillCallEvent / CodeModeSkillResultEvent / CodeModeSkillErrorEvent / SkillRegisteredEvent are renamed to their Snippet equivalents.

Patch Changes

• Add @tanstack/ai-isolate-quickjs-bun, a Code Mode isolate driver that runs QuickJS natively on the Bun runtime through bun:ffi (via quickjs-bun).

  It implements the same IsolateDriver contract as the existing drivers and is a drop-in replacement for @tanstack/ai-isolate-quickjs on Bun servers:

  import { createQuickJSBunIsolateDriver } from '@tanstack/ai-isolate-quickjs-bun'
  import { createCodeModeTool } from '@tanstack/ai-code-mode'
  
  const executeTypescript = createCodeModeTool({
    driver: createQuickJSBunIsolateDriver(),
    tools: [myTool],
  })

  Compared to the WASM driver:

  • Native QuickJS through bun:ffi — no WebAssembly or asyncify overhead, and no native build step (the QuickJS sources are compiled once per process by Bun's embedded TinyCC).

  • Each context gets a dedicated QuickJS runtime with its own memory and stack limits, so executions on different contexts are not serialized through a shared VM.

  • Same normalized MemoryLimitError / StackOverflowError / DisposedError contract, console capture prefixes, and JSON tool-call protocol as the other drivers, plus a normalized TimeoutError for deadline expiry (the WASM driver surfaces timeouts as InternalError: interrupted).

  • A configurable maxToolCalls limit (default 1000) bounds output and memory growth from untrusted sandbox code.

  The driver requires Bun >= 1.3.14 and throws an error when used on Node.js.

  It pins quickjs-bun to an exact version (0.1.2) rather than a range, because that package is still pre-1.0 and compiles QuickJS through TinyCC/bun:ffi — its API and platform support may shift between patch releases (see the package README for the compatibility note and the Windows QUICKJS_BUN_NATIVE_LIBRARY requirement).

  The @tanstack/ai-code-mode README and bundled skill are updated to document the new driver.

• publish internal dependency ranges as ^x.y.z instead of exact pins

  Internal dependencies on other TanStack AI packages used workspace:* in dependencies and peerDependencies. pnpm rewrites that to an exact version at publish time, so a released package asked for e.g. @tanstack/ai-utils@0.4.0 rather than ^0.4.0.

  Two consequences for consumers:

  • Duplicate copies. An exact pin cannot dedupe. Installing a newer @tanstack/ai alongside a package pinned to the previous patch produced two copies in the tree, which breaks instanceof checks and module-level state, and inflates bundles.

  • Unsatisfiable peers. An exactly pinned peerDependency conflicts the moment the internal package ships its next patch, forcing consumers into overrides or --legacy-peer-deps.

  These fields now use workspace:^, which publishes as ^x.y.z. Every package here is still 0.x, so ^0.43.1 resolves to 0.43.x only — patches dedupe cleanly and no breaking minor is ever pulled in.

  devDependencies deliberately keep workspace:*: they are never published, and * correctly means "always build against the local copy".