@tanstack/ai 0.38.0 → 0.39.0

package/src/activities/chat/index.ts

@@ -27,6 +27,7 @@ import {
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
+import { provideSandboxRuntime } from './middleware/sandbox-runtime'
 import { CapabilityRegistry } from './middleware/capabilities'
 import { validateCapabilities } from './middleware/validate'
 import { MCPManager } from './mcp/manager'
@@ -67,6 +68,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
+  SandboxFileEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
 import type { CheckCoverage } from './middleware/builder'
@@ -542,6 +544,7 @@ class TextEngine<
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner<TContext>
   private readonly middlewareCtx: ChatMiddlewareContext<TContext>
+  private readonly sandboxFileQueue: Array<StreamChunk> = []
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
@@ -701,6 +704,21 @@ class TextEngine<
         capability[0](this.middlewareCtx, { optional: true }),
       provide: (capability, value) => capability[1](this.middlewareCtx, value),
     }
+
+    // Provide the internal SandboxRuntime capability so harness adapters and
+    // sandbox middleware can emit file events. The sink logs, fans the event
+    // out through the middleware `onFile*` hooks (fire-and-forget), and queues
+    // 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)
+        this.sandboxFileQueue.push(
+          this.createCustomEventChunk('sandbox.file', { ...event }),
+        )
+      },
+    })
   }
 
   /** Get the accumulated content after the chat loop completes */
@@ -1021,6 +1039,10 @@ class TextEngine<
       threadId: this.threadId,
       runId: this.runIdOverride,
       parentRunId: this.parentRunIdOverride,
+      // Expose provided capabilities (e.g. sandbox) to harness adapters.
+      capabilities: this.middlewareCtx,
+      // Client approval decisions, for harness interactive-approval resolution.
+      approvals: this.initialApprovals,
       ...(combinedSchema ? { outputSchema: combinedSchema } : {}),
     })) {
       if (this.isCancelled()) {
@@ -1105,10 +1127,16 @@ class TextEngine<
         await this.middlewareRunner.runOnUsage(this.middlewareCtx, chunk.usage)
       }
 
+      // Drain any sandbox.file events emitted while processing this chunk.
+      yield* this.drainSandboxFileQueue()
+
       if (this.earlyTermination) {
         break
       }
     }
+
+    // Drain any remaining sandbox.file events emitted after the stream ended.
+    yield* this.drainSandboxFileQueue()
   }
 
   private handleStreamChunk(chunk: StreamChunk): void {
@@ -2502,6 +2530,17 @@ class TextEngine<
     }
   }
 
+  /**
+   * Drain queued `sandbox.file` chunks (emitted via the SandboxRuntime sink)
+   * through the middleware pipeline and into the public stream.
+   */
+  private async *drainSandboxFileQueue(): AsyncGenerator<StreamChunk> {
+    while (this.sandboxFileQueue.length > 0) {
+      const chunk = this.sandboxFileQueue.shift()
+      if (chunk) yield* this.pipeThroughMiddleware(chunk)
+    }
+  }
+
   /**
    * Drain an executeToolCalls async generator, yielding any CustomEvent chunks
    * through the middleware pipeline and returning the final ExecuteToolCallsResult.

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

@@ -11,6 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
+  SandboxFileEvent,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
@@ -344,6 +345,39 @@ export class MiddlewareRunner<TContext = unknown> {
     return chunks
   }
 
+  /**
+   * Dispatch a sandbox file event to every middleware's `sandbox` hooks, in
+   * array order: the catch-all `onFile` then the type-specific hook. Errors are
+   * logged and swallowed so one bad hook can't break the run.
+   */
+  async runSandboxFile(
+    ctx: ChatMiddlewareContext<TContext>,
+    event: SandboxFileEvent,
+  ): Promise<void> {
+    const typed = (
+      {
+        create: 'onFileCreate',
+        change: 'onFileChange',
+        delete: 'onFileDelete',
+      } as const
+    )[event.type]
+    for (const mw of this.middlewares) {
+      const hooks = mw.sandbox
+      if (!hooks) continue
+      for (const fn of [hooks.onFile, hooks[typed]]) {
+        if (!fn) continue
+        try {
+          await fn(ctx, event)
+        } catch (error) {
+          this.logger.sandbox(
+            `hook=${typed} middleware=${mw.name ?? 'unnamed'} threw`,
+            { middleware: mw.name ?? 'unnamed', error },
+          )
+        }
+      }
+    }
+  }
+
   /**
    * Run onBeforeToolCall through middleware in order.
    * Returns the first non-void decision, or undefined to continue normally.

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

@@ -13,6 +13,8 @@ export type {
   FinishInfo,
   AbortInfo,
   ErrorInfo,
+  SandboxFileEvent,
+  ChatSandboxHooks,
 } from './types'
 
 export { MiddlewareRunner } from './compose'

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

@@ -0,0 +1,21 @@
+/**
+ * Internal runtime seam the chat engine PROVIDES so the sandbox middleware can
+ * surface file events without a public ctx method. `emit` runs every
+ * middleware's `sandbox` hooks AND emits a CUSTOM `sandbox.file` chunk into the
+ * stream; `logger` lets the sandbox layer log under the `sandbox` debug
+ * category. Consumed (optionally) by `withSandbox` in `@tanstack/ai-sandbox`.
+ */
+import { createCapability } from './capabilities'
+import type { InternalLogger } from '../../../logger/internal-logger'
+import type { SandboxFileEvent } from './types'
+
+export interface SandboxRuntime {
+  emit: (event: SandboxFileEvent) => void
+  logger: InternalLogger
+}
+
+export const SandboxRuntimeCapability =
+  createCapability<SandboxRuntime>()('sandbox-runtime')
+
+export const [getSandboxRuntime, provideSandboxRuntime] =
+  SandboxRuntimeCapability

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

@@ -13,6 +13,37 @@ import type {
   CapabilityRegistry,
 } from './capabilities'
 
+/** A file change observed inside a sandbox during a chat run. */
+export interface SandboxFileEvent {
+  type: 'create' | 'change' | 'delete'
+  /** Absolute path inside the sandbox (under the workspace root). */
+  path: string
+  timestamp: number
+}
+
+/**
+ * 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.
+ */
+export interface ChatSandboxHooks<TContext = unknown> {
+  onFile?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileCreate?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileChange?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+  onFileDelete?: (
+    ctx: ChatMiddlewareContext<TContext>,
+    e: SandboxFileEvent,
+  ) => void | Promise<void>
+}
+
 // ===========================
 // Middleware Context
 // ===========================
@@ -539,6 +570,12 @@ export interface ChatMiddleware<TContext = unknown> {
     ctx: ChatMiddlewareContext<TContext>,
     info: ErrorInfo,
   ) => void | Promise<void>
+
+  /**
+   * Sandbox file-event hooks. Fire when a sandbox provided by `withSandbox` is
+   * active during the run and a file is created/changed/deleted. Server-side.
+   */
+  sandbox?: ChatSandboxHooks<TContext>
 }
 
 /** A `ChatMiddleware` with a permissive context — for use as a constraint. */

package/src/adapter-internals.ts

@@ -10,3 +10,9 @@ export {
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from './activities/error-payload'
+export {
+  getSandboxRuntime,
+  provideSandboxRuntime,
+  SandboxRuntimeCapability,
+} from './activities/chat/middleware/sandbox-runtime'
+export type { SandboxRuntime } from './activities/chat/middleware/sandbox-runtime'

package/src/index.ts

@@ -120,6 +120,8 @@ export type {
   FinishInfo,
   AbortInfo,
   ErrorInfo,
+  SandboxFileEvent,
+  ChatSandboxHooks,
 } from './activities/chat/middleware/index'
 
 // Base, activity-agnostic middleware. The observe-only superset that media
@@ -149,6 +151,8 @@ export type {
   CapabilityContext,
   CapabilityGetter,
   CapabilityProvider,
+  DefinedChatMiddleware,
+  AnyChatMiddleware,
 } from './activities/chat/middleware/index'
 
 // All types

package/src/logger/internal-logger.ts

@@ -31,6 +31,7 @@ const CATEGORY_EMOJI: Record<keyof ResolvedCategories, string> = {
   agentLoop: '🔁',
   config: '⚙️',
   errors: '❌',
+  sandbox: '📦',
 }
 
 export class InternalLogger {
@@ -82,6 +83,11 @@ export class InternalLogger {
     this.emit('debug', 'tools', message, meta)
   }
 
+  /** Log sandbox internals (watcher, file events, hook dispatch). Chat-only. */
+  sandbox(message: string, meta?: Record<string, unknown>): void {
+    this.emit('debug', 'sandbox', message, meta)
+  }
+
   /** Log an agent-loop iteration marker or phase transition. Chat-only. */
   agentLoop(message: string, meta?: Record<string, unknown>): void {
     this.emit('debug', 'agentLoop', message, meta)

package/src/logger/resolve.ts

@@ -12,6 +12,7 @@ const ALL_OFF: ResolvedCategories = {
   config: false,
   errors: false,
   request: false,
+  sandbox: false,
 }
 
 const ALL_ON: ResolvedCategories = {
@@ -23,6 +24,7 @@ const ALL_ON: ResolvedCategories = {
   config: true,
   errors: true,
   request: true,
+  sandbox: true,
 }
 
 const errorsOnlyCategories = (): ResolvedCategories => ({
@@ -41,6 +43,7 @@ const resolveCategoriesFromPartial = (
   config: partial.config ?? true,
   errors: partial.errors ?? true,
   request: partial.request ?? true,
+  sandbox: partial.sandbox ?? true,
 })
 
 /**

package/src/logger/types.ts

@@ -60,6 +60,11 @@ export interface DebugCategories {
    * Outgoing call metadata (provider, model, message/tool counts) emitted before each adapter SDK call.
    */
   request?: boolean
+  /**
+   * Sandbox internals: watcher start/stop + mechanism, file events, sandbox
+   * hook dispatch, ensure/bootstrap and lifecycle transitions. Chat-only.
+   */
+  sandbox?: boolean
 }
 
 /**

package/src/types.ts

@@ -4,6 +4,7 @@ import type {
 } from '@standard-schema/spec'
 import type { InternalLogger } from './logger/internal-logger'
 import type { SystemPrompt } from './system-prompts'
+import type { CapabilityContext } from './activities/chat/middleware/capabilities'
 // The canonical usage types live in the leaf `@tanstack/ai-event-client`
 // package (which `@tanstack/ai` already depends on) so there is a single source
 // of truth without a dependency cycle. They are re-exported below.
@@ -946,6 +947,25 @@ export interface TextOptions<
    * Surfaced for observability/middleware; not consumed by the LLM call.
    */
   parentRunId?: string
+
+  /**
+   * Middleware capability context for this run. The engine populates it with
+   * the live middleware context so harness adapters that declare
+   * `requires: [SomeCapability]` can read provided capabilities from inside
+   * `chatStream` — e.g. `getSandbox(options.capabilities)`. Capabilities are
+   * provisioned by middleware `setup` before the adapter runs. Undefined for
+   * direct adapter usage outside the chat engine.
+   */
+  capabilities?: CapabilityContext
+
+  /**
+   * Client approval decisions for this run, keyed by approval id. The engine
+   * populates this from approvals carried on the incoming messages. Harness
+   * adapters consult it to resolve `ask`-policy permission requests (the agent
+   * pauses on a risky action; the client re-runs with a decision recorded
+   * here). Undefined for direct adapter usage outside the chat engine.
+   */
+  approvals?: ReadonlyMap<string, boolean>
 }
 
 // ============================================================================