@tanstack/ai 0.42.0 → 0.43.0

package/skills/ai-core/tool-calling/SKILL.md

@@ -4,12 +4,12 @@ description: >
   Isomorphic tool system: toolDefinition() with Zod schemas,
   .server() and .client() implementations, passing tools to both
   chat() on server and useChat/clientTools on client, tool approval
-  flows with needsApproval and addToolApprovalResponse(), lazy tool
+  flows with needsApproval and bound interrupts (resolveInterrupt), lazy tool
   discovery with lazy:true, rendering ToolCallPart and ToolResultPart
   in UI.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/tools/tools.md'
   - 'TanStack/ai:docs/tools/server-tools.md'
@@ -108,14 +108,14 @@ function ChatPage() {
     connection: fetchServerSentEvents("/api/chat"),
     tools,
   });
-  type Messages = InferChatMessages<typeof chatOptions>;
-
   const { messages, sendMessage } = useChat(chatOptions);
+  // InferChatMessages ties part types to the configured tools when needed:
+  // type Messages = InferChatMessages<typeof chatOptions>
 
   return (
     <div>
       <span>Cart: {cartCount}</span>
-      {(messages as Messages).map((msg) => (
+      {messages.map((msg) => (
         <div key={msg.id}>
           {msg.parts.map((part) => {
             if (part.type === "text") return <p>{part.content}</p>;
@@ -239,9 +239,11 @@ function ChatPage() {
 
 ### Pattern 3: Tool with Approval Flow
 
-Set `needsApproval: true` in the definition. Execution pauses until the client
-calls `addToolApprovalResponse()`. The part has `state: "approval-requested"`
-and an `approval` object with an `id`.
+Set `needsApproval: true` in the definition. Execution pauses with
+`RUN_FINISHED.outcome.type === 'interrupt'`. The primary client API is bound
+`interrupts` + `resolveInterrupt` / `resolveInterrupts` / `cancel`.
+`addToolApprovalResponse` and `pendingInterrupts` remain as deprecated
+compatibility shims during migration.
 
 ```typescript
 import { toolDefinition } from '@tanstack/ai'
@@ -265,59 +267,40 @@ export const sendEmail = sendEmailDef.server(async ({ to, subject, body }) => {
 })
 ```
 
-Client -- render approval UI and respond:
+Server route must forward `resume` / `parentRunId` (via `chatParamsFromRequest`
+or equivalent). Client -- render bound interrupts:
 
 ```typescript
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 
 function ChatPage() {
-  const { messages, addToolApprovalResponse } = useChat({
+  const { messages, interrupts, sendMessage } = useChat({
     connection: fetchServerSentEvents("/api/chat"),
   });
 
   return (
     <div>
+      {interrupts.map((interrupt) => {
+        if (interrupt.kind !== "tool-approval") return null;
+        return (
+          <div key={interrupt.id}>
+            <p>Approve "{interrupt.toolName}"?</p>
+            <pre>{JSON.stringify(interrupt.originalArgs, null, 2)}</pre>
+            <button onClick={() => interrupt.resolveInterrupt(true)}>
+              Approve
+            </button>
+            <button onClick={() => interrupt.resolveInterrupt(false)}>
+              Deny
+            </button>
+            <button onClick={() => interrupt.cancel()}>Cancel</button>
+          </div>
+        );
+      })}
       {messages.map((msg) => (
         <div key={msg.id}>
-          {msg.parts.map((part) => {
-            if (part.type === "text") return <p>{part.content}</p>;
-            if (
-              part.type === "tool-call" &&
-              part.state === "approval-requested" &&
-              part.approval
-            ) {
-              return (
-                <div key={part.id}>
-                  <p>Approve "{part.name}"?</p>
-                  {/* `part.input` is the parsed, typed object (populated once
-                      the arguments are complete, as they are at approval
-                      time); `part.arguments` remains the raw JSON string. */}
-                  <pre>{JSON.stringify(part.input, null, 2)}</pre>
-                  <button
-                    onClick={() =>
-                      addToolApprovalResponse({
-                        id: part.approval!.id,
-                        approved: true,
-                      })
-                    }
-                  >
-                    Approve
-                  </button>
-                  <button
-                    onClick={() =>
-                      addToolApprovalResponse({
-                        id: part.approval!.id,
-                        approved: false,
-                      })
-                    }
-                  >
-                    Deny
-                  </button>
-                </div>
-              );
-            }
-            return null;
-          })}
+          {msg.parts.map((part) =>
+            part.type === "text" ? <p key={part.content}>{part.content}</p> : null
+          )}
         </div>
       ))}
     </div>
@@ -325,14 +308,24 @@ function ChatPage() {
 }
 ```
 
-> **Type-safe approval:** With typed `tools`, `part.approval` exists **only**
-> on parts for tools defined with `needsApproval: true`. Tools without approval
-> have no `approval` field (reading it is a compile error). For a
-> tool-agnostic handler over a typed union, narrow with `'approval' in part`
-> (`if (part.type === 'tool-call' && 'approval' in part && part.approval)`),
-> or type a shared component against the base `ToolCallPart`. An untyped
-> `useChat()` keeps `approval` on every tool-call part, which is why the
-> snippet above (no `tools` generic) reads it directly.
+Batch all pending approvals with `resolveInterrupts` (void — submission is
+async; watch `resuming` / `interruptErrors`):
+
+```typescript
+// Payloadless tool-approvals only
+resolveInterrupts(true)
+
+// Or per-item:
+resolveInterrupts((interrupt) => {
+  if (interrupt.kind === 'tool-approval') {
+    interrupt.resolveInterrupt(true)
+  }
+})
+```
+
+Migration: `pendingInterrupts` aliases `interrupts`; `addToolApprovalResponse`
+forwards to the matching bound approval when present. Prefer the bound methods
+above for new code. See `docs/interrupts/`.
 
 ### Pattern 4: Lazy Tool Discovery
 
@@ -375,8 +368,8 @@ export async function POST(request: Request) {
     adapter: openaiText('gpt-5.5'),
     messages,
     tools: [getProducts, compareProducts],
-    // maxIterations bounds model turns, not tool calls. Prefer maxToolCalls
-    // (and maxToolCallsPerTurn) when you need a tool-call budget.
+    // maxIterations bounds model turns, not tool calls. For tool budgets,
+    // use middleware onBeforeToolCall + onShouldContinue (see agentic-cycle docs).
     agentLoopStrategy: maxIterations(20),
   })
   return toServerSentEventsResponse(stream)
@@ -649,7 +642,7 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: anthropicText('claude-sonnet-4-5'),
+    adapter: anthropicText('claude-sonnet-4-6'),
     messages,
     tools: [
       codeExecutionTool(
@@ -685,7 +678,7 @@ import { openaiText } from '@tanstack/ai-openai'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: openaiText('gpt-5.2'),
+    adapter: openaiText('gpt-5.5'),
     messages,
     tools: [
       shellTool({

package/src/activities/chat/agent-loop-strategies.ts

@@ -4,9 +4,10 @@ import type { AgentLoopStrategy } from '../../types'
  * Creates a strategy that continues for a maximum number of **model turns**
  * (iterations), not tool calls.
  *
- * One iteration can still emit many parallel tool calls. Prefer
- * {@link maxToolCalls} (and optionally `maxToolCallsPerTurn` on `chat()`)
- * when you need a tool-call budget.
+ * One iteration can still emit many parallel tool calls. For a tool-call
+ * budget, use middleware with `onBeforeToolCall` (per-turn cap) and
+ * `onShouldContinue` (cumulative run budget) — see the docs recipe under
+ * Agentic Cycle.
  *
  * @param max - Maximum number of model turns to allow
  * @returns AgentLoopStrategy that stops after max iterations
@@ -26,40 +27,6 @@ export function maxIterations(max: number): AgentLoopStrategy {
   return ({ iterationCount }) => iterationCount < max
 }
 
-/**
- * Creates a strategy that continues while `toolCallCount < max`.
- *
- * Unlike {@link maxIterations} (which counts model turns), this bounds
- * **emitted** tool calls counted during the run (including ones skipped by
- * `maxToolCallsPerTurn`). Strategies only run between turns, so the turn that
- * crosses `max` is not truncated — the final count (and executions, unless
- * `maxToolCallsPerTurn` is set) may exceed `max`. Pair with
- * `chat({ maxToolCallsPerTurn })` to also cap parallel fan-out inside a single
- * turn.
- *
- * @param max - Maximum cumulative emitted tool calls before stopping further turns
- * @returns AgentLoopStrategy that returns true while `toolCallCount < max`
- *
- * @example
- * ```typescript
- * import { chat, combineStrategies, maxIterations, maxToolCalls } from '@tanstack/ai'
- *
- * const stream = chat({
- *   adapter: openaiText('gpt-4o'),
- *   messages: [...],
- *   tools: [weatherTool],
- *   maxToolCallsPerTurn: 10,
- *   agentLoopStrategy: combineStrategies([
- *     maxIterations(20),
- *     maxToolCalls(20),
- *   ]),
- * })
- * ```
- */
-export function maxToolCalls(max: number): AgentLoopStrategy {
-  return ({ toolCallCount }) => toolCallCount < max
-}
-
 /**
  * Creates a strategy that continues until a specific finish reason is encountered
  *
@@ -99,7 +66,7 @@ export function untilFinishReason(
  * All strategies must return true to continue
  *
  * @param strategies - Array of strategies to combine
- * @returns AgentLoopStrategy that continues only if all strategies return true
+ * @returns AgentLoopStrategy that continues only if all strategies agree
  *
  * @example
  * ```typescript
@@ -110,7 +77,6 @@ export function untilFinishReason(
  *   tools: [weatherTool],
  *   agentLoopStrategy: combineStrategies([
  *     maxIterations(10),
- *     maxToolCalls(20),
  *     ({ messages }) => messages.length < 100,
  *   ]),
  * });

package/src/activities/chat/cancel.ts

@@ -0,0 +1,81 @@
+/**
+ * Out-of-band run cancellation.
+ *
+ * `ChatClient.stop()` only aborts a local `AbortController`; it sends nothing to
+ * the server. A user pressing Stop and a user refreshing the page produce the
+ * IDENTICAL TCP close, so intent is **not inferable** from a disconnect. It has
+ * to arrive out of band, and there are exactly two bands:
+ *
+ * 1. **Durable** — {@link requestRunCancel} records the intent on the run's
+ *    `RunRecord`. This is the only channel that works when the run is being
+ *    driven by a DIFFERENT host than the one the cancel request reached, which
+ *    is the normal case for a detached run.
+ * 2. **In-process** — abort the run's signal with {@link RUN_CANCEL_REASON}.
+ *    Core reads the reason back when it builds `AbortInfo`, so
+ *    `AbortInfo.cancelRequested` is `true` for that abort and `false` for a
+ *    disconnect. This is the fast path when the cancel reaches the driving host.
+ *
+ * A cancel endpoint SHOULD do both: record it (so a remote driver observes it)
+ * and abort locally (so a co-located driver stops immediately).
+ */
+import type { RunStore } from './middleware/run-store'
+
+/**
+ * Abort reason that marks an abort as an explicit cancellation.
+ *
+ * Namespaced so an application's own reason string cannot collide with it by
+ * accident, and matched with `===` (never a substring test) so an arbitrary
+ * provider error message can never be read as a deliberate cancel.
+ */
+export const RUN_CANCEL_REASON = 'tanstack-ai:cancel-requested'
+
+/** Whether an abort reason means "the user explicitly cancelled this run". */
+export function isCancelRequestedReason(reason: string | undefined): boolean {
+  return reason === RUN_CANCEL_REASON
+}
+
+/**
+ * Record an explicit cancel on the run record.
+ *
+ * Deliberately does NOT set a status. The driver is the only actor that knows
+ * when the agent has actually stopped and the sandbox has been torn down, so it
+ * owns the transition to `'aborted'`. Writing a terminal status here would tell
+ * every reader the run is over while the agent is still burning tokens.
+ *
+ * A no-op for an unknown `runId`, inheriting `RunStore.update`'s documented
+ * invariant.
+ */
+export async function requestRunCancel(
+  runs: RunStore,
+  runId: string,
+): Promise<void> {
+  await runs.update(runId, { cancelRequested: true })
+}
+
+/**
+ * Whether an explicit cancel has been recorded for `runId`.
+ *
+ * Answers `false` rather than throwing when the store cannot be read. Callers
+ * are middleware abort hooks, which are already on a teardown path, and a
+ * store failure there must not replace the caller's own reason for tearing
+ * down with a store error. The cost of a false negative is that a cancel
+ * degrades into a detach — the run record gains `detachedSince`/`sandboxKey`
+ * instead of transitioning to `'aborted'`. `@tanstack/ai-sandbox`'s
+ * `reapDetachedRuns` recovers that run once the `detachedRunTtlMs` the
+ * application passes to that sweep has elapsed — nothing derives it from
+ * `withSandbox`, which has no TTL option — so the cost is a delayed teardown
+ * rather than a lost one, provided the application actually schedules the
+ * sweep, which is its job and not the framework's. Still strictly better than
+ * failing the teardown.
+ */
+export async function wasCancelRequested(
+  runs: RunStore,
+  runId: string,
+): Promise<boolean> {
+  try {
+    const record = await runs.get(runId)
+    return record?.cancelRequested === true
+  } catch {
+    return false
+  }
+}