@tanstack/ai 0.39.1 → 0.40.0

package/skills/ai-core/middleware/SKILL.md

@@ -11,6 +11,7 @@ library: tanstack-ai
 library_version: '0.10.0'
 sources:
   - 'TanStack/ai:docs/advanced/middleware.md'
+  - 'TanStack/ai:docs/sandbox/observability.md'
 ---
 
 # Middleware
@@ -371,6 +372,95 @@ Options: `maxSize` (default 100), `ttl` (default Infinity), `toolNames` (default
 `keyFn` (custom cache key), `storage` (custom backend like Redis). See
 `docs/advanced/middleware.md` for custom storage examples.
 
+## Sandbox File-Event Hooks (`sandbox` group)
+
+Declare a `sandbox: ChatSandboxHooks` group on `defineChatMiddleware` to react
+to every file created/changed/deleted inside a sandbox provided by
+`withSandbox` (from `@tanstack/ai-sandbox`). These fire **per-run**,
+server-side, and each handler receives the run's `ChatMiddlewareContext` as
+the first argument:
+
+```typescript
+import { defineChatMiddleware } from '@tanstack/ai'
+import { db } from './db'
+
+const auditMiddleware = defineChatMiddleware({
+  name: 'audit',
+  sandbox: {
+    onFile: (ctx, e) => console.log(ctx.runId, e.type, e.path),
+    onFileCreate: (ctx, e) => db.log({ run: ctx.runId, event: e }),
+  },
+})
+```
+
+| Hook           | Fires for                  |
+| -------------- | -------------------------- |
+| `onFile`       | Every create/change/delete |
+| `onFileCreate` | File creates only          |
+| `onFileChange` | File changes only          |
+| `onFileDelete` | File deletes only          |
+
+These are independent of the stream: the engine also emits a `sandbox.file`
+`CUSTOM` chunk per change regardless of whether any `sandbox` hooks are
+registered, so a client can react to the same edits without middleware. See
+`ai-core/ag-ui-protocol/SKILL.md` for reading that chunk (and the opt-in
+`sandbox.file.diff` chunk) off `ChatStream`.
+
+### `before()` / `after()` / `diff()` — lazy, git-backed content accessors
+
+Each hook receives a `SandboxFileHookEvent`: the serializable
+`{ type, path, timestamp }` plus three lazy accessors for the file's content:
+
+```ts
+interface SandboxFileHookEvent {
+  type: 'create' | 'change' | 'delete'
+  path: string
+  timestamp: number
+  before(): Promise<string> // content at the session baseline ('' if new / non-git)
+  after(): Promise<string> // current content ('' if deleted)
+  diff(): Promise<string> // unified patch vs the baseline
+}
+```
+
+```typescript
+import { defineChatMiddleware } from '@tanstack/ai'
+import { db } from './db'
+
+const auditMiddleware = defineChatMiddleware({
+  name: 'audit',
+  sandbox: {
+    onFileChange: async (ctx, e) => {
+      const [before, after] = await Promise.all([e.before(), e.after()])
+      db.log({ run: ctx.runId, path: e.path, before, after })
+    },
+  },
+})
+```
+
+**Lazy — path-only hooks pay nothing.** `before()`, `after()`, and `diff()`
+are methods, not fields: each only reads the file or shells out to `git` when
+called. A hook that only reads `e.path`/`e.type` (like the `onFile` logger
+above) never touches the filesystem or spawns a process.
+
+**Git session baseline.** The sandbox snapshots `git rev-parse HEAD` once at
+setup as the session baseline (empty string if the workspace isn't a git repo
+or has no commits). `before()` and `diff()` always diff against that same
+fixed baseline for the rest of the run, so `onFileChange` reports the file's
+**cumulative** change since the run started, not just the delta since the
+last poll. `after()` always reads current on-disk content. None of the three
+accessors throw: a deleted file resolves `after()` to `''` (it still has
+`before()`); a new file resolves `before()` to `''` (it still has `after()`);
+a non-git workspace resolves **both** `before()` and `after()` to `''` and
+makes `diff()` fall back to a synthesized add-patch built from `after()` —
+except for a `delete` event in a non-git workspace, where there's nothing to
+synthesize and `diff()` resolves to `''`.
+
+**Hook errors are swallowed per hook.** A throwing `sandbox` hook is caught
+and logged under the `sandbox` debug category — it cannot break the run or
+stop other hooks (or the `sandbox.file` chunk) from continuing.
+
+Source: docs/sandbox/observability.md
+
 ## Common Mistakes
 
 ### a. MEDIUM: Trying to modify StreamChunks in middleware
@@ -451,3 +541,4 @@ Source: docs/advanced/middleware.md
 
 - See also: **ai-core/chat-experience/SKILL.md** -- Middleware hooks into the chat lifecycle
 - See also: **ai-core/structured-outputs/SKILL.md** -- Middleware now wraps the final structured-output call; use `onStructuredOutputConfig` for JSON-Schema transforms
+- See also: **ai-core/ag-ui-protocol/SKILL.md** -- Reading the `sandbox.file` / `sandbox.file.diff` `CUSTOM` chunks the sandbox runtime emits alongside these `sandbox` hooks, via `ChatStream`'s typed `KnownCustomEvent` narrowing

package/src/activities/chat/index.ts

@@ -45,6 +45,7 @@ import type {
 import type {
   AgentLoopStrategy,
   AnyTool,
+  ChatStream,
   ConstrainedModelMessage,
   CustomEvent,
   InferSchemaType,
@@ -69,7 +70,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
-  SandboxFileEvent,
+  SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
 import type { CheckCoverage } from './middleware/builder'
@@ -404,7 +405,7 @@ export type TextActivityResult<
     : Promise<InferSchemaType<TSchema>>
   : [TStream] extends [false]
     ? Promise<string>
-    : AsyncIterable<StreamChunk>
+    : ChatStream
 
 // ===========================
 // ChatEngine Implementation
@@ -712,11 +713,30 @@ class TextEngine<
     // a `sandbox.file` custom chunk to be drained into the public stream.
     provideSandboxRuntime(this.middlewareCtx, {
       logger: this.logger,
-      emit: (event: SandboxFileEvent) => {
-        this.logger.sandbox(`file ${event.type} ${event.path}`, { event })
-        void this.middlewareRunner.runSandboxFile(this.middlewareCtx, event)
+      emit: (event: SandboxFileHookEvent) => {
+        this.logger.sandbox(`file ${event.type} ${event.path}`, {
+          event: {
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+          },
+        })
+        void this.middlewareRunner
+          .runSandboxFile(this.middlewareCtx, event)
+          .catch((err: unknown) => {
+            this.logger.errors('sandbox file hook failed', { error: err })
+          })
+        this.sandboxFileQueue.push(
+          this.createCustomEventChunk('sandbox.file', {
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+          }),
+        )
+      },
+      emitFileDiff: (value: { path: string; diff: string }) => {
         this.sandboxFileQueue.push(
-          this.createCustomEventChunk('sandbox.file', { ...event }),
+          this.createCustomEventChunk('sandbox.file.diff', value),
         )
       },
     })

package/src/activities/chat/middleware/compose.ts

@@ -11,7 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
-  SandboxFileEvent,
+  SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
@@ -352,7 +352,7 @@ export class MiddlewareRunner<TContext = unknown> {
    */
   async runSandboxFile(
     ctx: ChatMiddlewareContext<TContext>,
-    event: SandboxFileEvent,
+    event: SandboxFileHookEvent,
   ): Promise<void> {
     const typed = (
       {

package/src/activities/chat/middleware/index.ts

@@ -14,6 +14,7 @@ export type {
   AbortInfo,
   ErrorInfo,
   SandboxFileEvent,
+  SandboxFileHookEvent,
   ChatSandboxHooks,
 } from './types'
 

package/src/activities/chat/middleware/sandbox-runtime.ts

@@ -7,10 +7,12 @@
  */
 import { createCapability } from './capabilities'
 import type { InternalLogger } from '../../../logger/internal-logger'
-import type { SandboxFileEvent } from './types'
+import type { SandboxFileHookEvent } from './types'
 
 export interface SandboxRuntime {
-  emit: (event: SandboxFileEvent) => void
+  emit: (event: SandboxFileHookEvent) => void
+  /** Emit an opt-in per-file `sandbox.file.diff` CUSTOM chunk. */
+  emitFileDiff: (value: { path: string; diff: string }) => void
   logger: InternalLogger
 }
 

package/src/activities/chat/middleware/types.ts

@@ -21,6 +21,19 @@ export interface SandboxFileEvent {
   timestamp: number
 }
 
+/** The file event a sandbox hook receives: the serializable {@link SandboxFileEvent}
+ *  plus lazy, git-backed content accessors. Accessors compute on call, so a hook
+ *  that only reads `path`/`type` pays nothing. Never present on the serialized
+ *  `sandbox.file` CUSTOM chunk. */
+export interface SandboxFileHookEvent extends SandboxFileEvent {
+  /** Content at the session baseline (`''` for a new file or non-git workspace). */
+  before: () => Promise<string>
+  /** Current content (`''` when the event is a delete). */
+  after: () => Promise<string>
+  /** Unified patch vs the session baseline (synthesized add-patch when non-git). */
+  diff: () => Promise<string>
+}
+
 /**
  * Sandbox file-event hooks a chat middleware can declare. Fire server-side for
  * every file create/change/delete observed in the sandbox during the run.
@@ -28,19 +41,19 @@ export interface SandboxFileEvent {
 export interface ChatSandboxHooks<TContext = unknown> {
   onFile?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileCreate?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileChange?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileDelete?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
 }
 

package/src/activities/generateTranscription/index.ts

@@ -19,7 +19,11 @@ import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware'
 import type { TranscriptionAdapter } from './adapter'
-import type { StreamChunk, TranscriptionResult } from '../../types'
+import type {
+  StreamChunk,
+  TranscriptionResponseFormat,
+  TranscriptionResult,
+} from '../../types'
 
 // ===========================
 // Activity Kind
@@ -67,7 +71,7 @@ export interface TranscriptionActivityOptions<
   /** An optional prompt to guide the transcription */
   prompt?: string
   /** The format of the transcription output */
-  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  responseFormat?: TranscriptionResponseFormat
   /** Provider-specific options for transcription */
   modelOptions?: TranscriptionProviderOptions<TAdapter>
   /**

package/src/index.ts

@@ -121,6 +121,7 @@ export type {
   AbortInfo,
   ErrorInfo,
   SandboxFileEvent,
+  SandboxFileHookEvent,
   ChatSandboxHooks,
 } from './activities/chat/middleware/index'
 

package/src/types.ts

@@ -1381,6 +1381,105 @@ export interface UIResourceEvent extends CustomEvent {
   }
 }
 
+// ── Sandbox events ──────────────────────────────────────────────────────────
+export interface SandboxFileCustomEvent extends CustomEvent {
+  name: 'sandbox.file'
+  value: {
+    type: 'create' | 'change' | 'delete'
+    path: string
+    timestamp: number
+  }
+}
+export interface SandboxFileDiffEvent extends CustomEvent {
+  name: 'sandbox.file.diff'
+  value: { path: string; diff: string }
+}
+
+// ── Harness events ──────────────────────────────────────────────────────────
+export interface FileChangedEvent extends CustomEvent {
+  name: 'file.changed'
+  value: { path: string; diff: string }
+}
+export interface SessionIdEvent extends CustomEvent {
+  name: `${string}.session-id`
+  value: { sessionId: string }
+}
+
+// ── Code-mode events ────────────────────────────────────────────────────────
+export interface CodeModeExecutionStartedEvent extends CustomEvent {
+  name: 'code_mode:execution_started'
+  value: { timestamp: number; codeLength: number }
+}
+export interface CodeModeConsoleEvent extends CustomEvent {
+  name: 'code_mode:console'
+  value: {
+    level: 'log' | 'warn' | 'error' | 'info'
+    message: string
+    timestamp: number
+  }
+}
+export interface CodeModeExternalCallEvent extends CustomEvent {
+  name: 'code_mode:external_call'
+  value: { function: string; args: unknown; timestamp: number }
+}
+export interface CodeModeExternalResultEvent extends CustomEvent {
+  name: 'code_mode:external_result'
+  value: { function: string; result: unknown; duration: number }
+}
+export interface CodeModeExternalErrorEvent extends CustomEvent {
+  name: 'code_mode:external_error'
+  value: { function: string; error: string; duration: number }
+}
+export interface CodeModeSkillCallEvent extends CustomEvent {
+  name: 'code_mode:skill_call'
+  value: { skill: string; input: unknown; timestamp: number }
+}
+export interface CodeModeSkillResultEvent extends CustomEvent {
+  name: 'code_mode:skill_result'
+  value: { skill: string; result: unknown; duration: number; timestamp: number }
+}
+export interface CodeModeSkillErrorEvent extends CustomEvent {
+  name: 'code_mode:skill_error'
+  value: { skill: string; error: string; duration: number; timestamp: number }
+}
+export interface SkillRegisteredEvent extends CustomEvent {
+  name: 'skill:registered'
+  value: { id: string; name: string; description: string; timestamp: number }
+}
+
+/**
+ * Every CUSTOM event TanStack AI itself emits, as a discriminated union on
+ * `name`. User-emitted custom events (via `emitCustomEvent` with a custom name)
+ * are intentionally absent — they still flow at runtime.
+ */
+export type KnownCustomEvent =
+  | SandboxFileCustomEvent
+  | SandboxFileDiffEvent
+  | FileChangedEvent
+  | SessionIdEvent
+  | CodeModeExecutionStartedEvent
+  | CodeModeConsoleEvent
+  | CodeModeExternalCallEvent
+  | CodeModeExternalResultEvent
+  | CodeModeExternalErrorEvent
+  | CodeModeSkillCallEvent
+  | CodeModeSkillResultEvent
+  | CodeModeSkillErrorEvent
+  | SkillRegisteredEvent
+  | StructuredOutputStartEvent
+  | StructuredOutputCompleteEvent
+  | ApprovalRequestedEvent
+  | ToolInputAvailableEvent
+  | UIResourceEvent
+
+/** The default chat streaming result: standard chunks plus every typed
+ *  framework CUSTOM event, with the `value: any` catch-all excluded so
+ *  literal-`name` narrowing types `value`. User-emitted custom names are typed
+ *  out (still flow at runtime — branch outside the name narrows or cast). */
+export type ChatStream = AsyncIterable<
+  Exclude<StreamChunk, CustomEvent> | KnownCustomEvent
+>
+
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *
@@ -1930,6 +2029,13 @@ export interface TTSResult {
  * Options for audio transcription.
  * These are the common options supported across providers.
  */
+export type TranscriptionResponseFormat =
+  | 'json'
+  | 'text'
+  | 'srt'
+  | 'verbose_json'
+  | 'vtt'
+
 export interface TranscriptionOptions<
   TProviderOptions extends object = object,
 > {
@@ -1942,7 +2048,7 @@ export interface TranscriptionOptions<
   /** An optional prompt to guide the transcription */
   prompt?: string
   /** The format of the transcription output */
-  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  responseFormat?: TranscriptionResponseFormat
   /** Model-specific options for transcription */
   modelOptions?: TProviderOptions
   /**