@tanstack/ai 0.41.0 → 0.43.0

package/src/activities/chat/tools/tool-calls.ts

@@ -1,5 +1,6 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
+import type { ToolApprovalResolution } from '../../../interrupts'
 import type {
   AnyTool,
   ContentPart,
@@ -311,6 +312,13 @@ export class ToolCallManager<
 
       let toolResultContent: string | Array<ContentPart>
       let toolResultState: ToolOutputState | undefined
+      // Holds the parsed/validated execution output before serialization.
+      // Surfaced on the emitted `TOOL_CALL_END` event as `output` so
+      // consumers can read it typed (via `TypedStreamChunk` distribution
+      // over the tools array) without re-parsing `result`.
+      // Stays `undefined` when the tool has no `execute` (client-only
+      // tools) or when execution throws.
+      let toolOutput: unknown
       if (tool?.execute) {
         try {
           // Parse arguments (normalize null/non-object to {} for empty tool_use blocks)
@@ -369,6 +377,7 @@ export class ToolCallManager<
             }
           }
 
+          toolOutput = result
           toolResultContent = normalizeToolResult(result)
         } catch (error: unknown) {
           // If tool execution fails, add error message
@@ -390,9 +399,11 @@ export class ToolCallManager<
         toolName: toolCall.function.name,
         model: finishEvent.model,
         timestamp: Date.now(),
+        // Typed parsed output (undefined for failed exec / client-only tools).
+        ...(toolOutput !== undefined ? { output: toolOutput } : {}),
         result: toolResultContent,
         ...(toolResultState !== undefined && { state: toolResultState }),
-      } as ToolCallEndEvent
+      }
 
       // Add tool result message
       toolResults.push({
@@ -420,6 +431,17 @@ export interface ToolResult {
   state?: 'output-available' | 'output-error'
   /** Duration of tool execution in milliseconds (only for server-executed tools) */
   duration?: number
+  /**
+   * Parsed tool input (after JSON parse + optional Standard Schema validation).
+   * Surfaced on engine-emitted `TOOL_CALL_END` events for TypedStreamChunk consumers.
+   */
+  input?: unknown
+  /**
+   * Parsed tool output before wire serialization. Surfaced on engine-emitted
+   * `TOOL_CALL_END` events so consumers can read typed `output` without
+   * re-parsing `result`. Undefined on error paths and when execution is skipped.
+   */
+  output?: unknown
 }
 
 export interface ApprovalRequest {
@@ -435,6 +457,36 @@ export interface ClientToolRequest {
   input: any
 }
 
+export interface ToolResumeExecutionState {
+  deniedToolResults?: ReadonlyMap<string, unknown>
+  cancelledToolCallIds?: ReadonlySet<string>
+}
+
+function approvalResolution(
+  approvals: ReadonlyMap<string, ToolApprovalResolution>,
+  toolCallId: string,
+): ToolApprovalResolution | undefined {
+  return approvals.get(toolCallId) ?? approvals.get(`approval_${toolCallId}`)
+}
+
+function isApproved(resolution: ToolApprovalResolution): boolean {
+  return typeof resolution === 'boolean' ? resolution : resolution.approved
+}
+
+function editedApprovalArgs(
+  resolution: ToolApprovalResolution,
+): unknown | undefined {
+  return typeof resolution === 'object' && resolution.approved
+    ? resolution.editedArgs
+    : undefined
+}
+
+function deniedApprovalResult(resolution: ToolApprovalResolution): unknown {
+  return typeof resolution === 'object' && !resolution.approved
+    ? (resolution.payload ?? { error: 'User declined tool execution' })
+    : { error: 'User declined tool execution' }
+}
+
 interface ExecuteToolCallsResult {
   /** Tool results ready to send to LLM */
   results: Array<ToolResult>
@@ -588,6 +640,8 @@ export async function* executeServerTool<TContext = unknown>(
       toolCallId: toolCall.id,
       toolName,
       result: finalResult,
+      input,
+      output: finalResult,
       duration,
     })
 
@@ -620,6 +674,7 @@ export async function* executeServerTool<TContext = unknown>(
       toolCallId: toolCall.id,
       toolName,
       result: { error: message },
+      input,
       state: 'output-error',
       duration,
     })
@@ -643,6 +698,7 @@ function buildClientToolResult(
   toolName: string,
   tool: AnyTool,
   rawResult: unknown,
+  input?: unknown,
 ): ToolResult {
   try {
     let result = rawResult
@@ -650,11 +706,14 @@ function buildClientToolResult(
       result = parseWithStandardSchema(tool.outputSchema, result)
     }
 
+    const parsed =
+      typeof result === 'string' ? safeJsonParse(result) : (result ?? null)
     return {
       toolCallId,
       toolName,
-      result:
-        typeof result === 'string' ? safeJsonParse(result) : (result ?? null),
+      result: parsed,
+      input,
+      output: parsed,
     }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : 'Validation failed'
@@ -662,6 +721,7 @@ function buildClientToolResult(
       toolCallId,
       toolName,
       result: { error: message },
+      input,
       state: 'output-error',
     }
   }
@@ -678,14 +738,14 @@ function buildClientToolResult(
  *
  * @param toolCalls - Tool calls from the LLM
  * @param tools - Available tools with their configurations
- * @param approvals - Map of approval decisions (approval.id -> approved boolean)
+ * @param approvals - Map keyed by toolCallId (or `approval_${toolCallId}`) → ToolApprovalResolution
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
  */
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
   tools: ReadonlyArray<AnyTool>,
-  approvals: Map<string, boolean> = new Map(),
+  approvals: Map<string, ToolApprovalResolution> = new Map(),
   clientResults: Map<string, any> = new Map(),
   createCustomEventChunk?: (
     eventName: string,
@@ -694,6 +754,7 @@ export async function* executeToolCalls<TContext = unknown>(
   middlewareHooks?: ToolExecutionMiddlewareHooks,
   userContext?: TContext,
   abortSignal?: AbortSignal,
+  resumeState?: ToolResumeExecutionState,
 ): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -709,7 +770,11 @@ export async function* executeToolCalls<TContext = unknown>(
   // defer all execution so side effects don't happen before the user decides.
   const hasPendingApprovals = toolCalls.some((tc) => {
     const t = toolMap.get(tc.function.name)
-    return t?.needsApproval && !approvals.has(`approval_${tc.id}`)
+    return (
+      t?.needsApproval &&
+      approvalResolution(approvals, tc.id) === undefined &&
+      !resumeState?.cancelledToolCallIds?.has(tc.id)
+    )
   })
 
   for (const toolCall of toolCalls) {
@@ -729,11 +794,25 @@ export async function* executeToolCalls<TContext = unknown>(
 
     // Skip non-pending tools while approvals are outstanding
     if (hasPendingApprovals) {
-      if (!tool.needsApproval || approvals.has(`approval_${toolCall.id}`)) {
+      const isPendingApproval =
+        tool.needsApproval &&
+        approvalResolution(approvals, toolCall.id) === undefined
+      const isPlainClientRequest = !tool.needsApproval && !tool.execute
+      if (!isPendingApproval && !isPlainClientRequest) {
         continue
       }
     }
 
+    if (resumeState?.cancelledToolCallIds?.has(toolCall.id)) {
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: 'Tool execution cancelled' },
+        state: 'output-error',
+      })
+      continue
+    }
+
     // Parse arguments, throwing error if invalid JSON
     let input: unknown = {}
     const argsStr = toolCall.function.arguments.trim() || '{}'
@@ -763,6 +842,8 @@ export async function* executeToolCalls<TContext = unknown>(
           result: {
             error: `Input validation failed for tool ${tool.name}: ${message}`,
           },
+          // raw parse may have failed validation — still attach best-effort input
+          input,
           state: 'output-error',
         })
         continue
@@ -792,12 +873,14 @@ export async function* executeToolCalls<TContext = unknown>(
       // Check if tool needs approval
       if (tool.needsApproval) {
         const approvalId = `approval_${toolCall.id}`
+        const resolution = approvalResolution(approvals, toolCall.id)
 
         // Check if approval decision exists
-        if (approvals.has(approvalId)) {
-          const approved = approvals.get(approvalId)
+        if (resolution !== undefined) {
+          const approved = isApproved(resolution)
 
           if (approved) {
+            input = editedApprovalArgs(resolution) ?? input
             // Approved - check if client has executed
             if (clientResults.has(toolCall.id)) {
               results.push(
@@ -806,6 +889,7 @@ export async function* executeToolCalls<TContext = unknown>(
                   toolName,
                   tool,
                   clientResults.get(toolCall.id),
+                  input,
                 ),
               )
             } else {
@@ -821,7 +905,10 @@ export async function* executeToolCalls<TContext = unknown>(
             results.push({
               toolCallId: toolCall.id,
               toolName,
-              result: { error: 'User declined tool execution' },
+              result:
+                resumeState?.deniedToolResults?.get(toolCall.id) ??
+                deniedApprovalResult(resolution),
+              input,
               state: 'output-error',
             })
           }
@@ -843,6 +930,7 @@ export async function* executeToolCalls<TContext = unknown>(
               toolName,
               tool,
               clientResults.get(toolCall.id),
+              input,
             ),
           )
         } else {
@@ -860,12 +948,14 @@ export async function* executeToolCalls<TContext = unknown>(
     // CASE 2: Server tool with approval required
     if (tool.needsApproval) {
       const approvalId = `approval_${toolCall.id}`
+      const resolution = approvalResolution(approvals, toolCall.id)
 
       // Check if approval decision exists
-      if (approvals.has(approvalId)) {
-        const approved = approvals.get(approvalId)
+      if (resolution !== undefined) {
+        const approved = isApproved(resolution)
 
         if (approved) {
+          input = editedApprovalArgs(resolution) ?? input
           // Apply middleware before-hook for approved tools
           if (middlewareHooks) {
             const decision = await applyBeforeToolCallDecision(
@@ -895,7 +985,10 @@ export async function* executeToolCalls<TContext = unknown>(
           results.push({
             toolCallId: toolCall.id,
             toolName,
-            result: { error: 'User declined tool execution' },
+            result:
+              resumeState?.deniedToolResults?.get(toolCall.id) ??
+              deniedApprovalResult(resolution),
+            input,
             state: 'output-error',
           })
         }

package/src/activities/chat/tools/tool-definition.ts

@@ -1,36 +1,120 @@
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
 import type {
+  InferSchemaType,
   JSONSchema,
   SchemaInput,
   Tool,
   ToolExecuteFunction,
 } from '../../../types'
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
+
+/**
+ * Type-level brand key for {@link ToolApprovalCapabilityMarker}. Only ever used
+ * in type positions, but it must stay exported: a `unique symbol` referenced by
+ * an exported interface has to be nameable in the emitted declarations.
+ *
+ * @public
+ */
+export declare const toolApprovalCapability: unique symbol
+
+export interface ToolApprovalCapabilityMarker<
+  TNeedsApproval extends boolean,
+  TApprovalSchema,
+> {
+  readonly [toolApprovalCapability]?: {
+    needsApproval: TNeedsApproval
+    approvalSchema: TApprovalSchema
+  }
+}
+
+export type ApprovalSchemaConfig =
+  | SchemaInput
+  | { approve: SchemaInput; reject?: SchemaInput }
+  | { approve?: SchemaInput; reject: SchemaInput }
+
+type ApprovalConfig<
+  TNeedsApproval extends boolean,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined,
+> = TNeedsApproval extends true
+  ? { needsApproval: TNeedsApproval; approvalSchema?: TApprovalSchema }
+  : { needsApproval?: TNeedsApproval; approvalSchema?: never }
+
+export type ApprovalCapabilityOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<infer TNeeds, unknown>
+    ? TNeeds
+    : false
+
+export type ApprovalSchemaOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<boolean, infer TSchema>
+    ? TSchema
+    : undefined
+
+export declare const noSchema: unique symbol
+export type NoSchema = typeof noSchema
+
+export type InputSchemaOf<TTool> = TTool extends {
+  inputSchema: infer TInput
+}
+  ? TInput extends undefined
+    ? NoSchema
+    : TInput
+  : NoSchema
+
+export type OutputSchemaOf<TTool> = TTool extends {
+  outputSchema: infer TOutput
+}
+  ? TOutput extends undefined
+    ? NoSchema
+    : TOutput
+  : NoSchema
+
+type BuiltToolSchemaFields<
+  TInput extends SchemaInput | undefined,
+  TOutput extends SchemaInput | undefined,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined,
+> = {
+  inputSchema: TInput
+  outputSchema: TOutput
+  approvalSchema: TApprovalSchema
+}
 
 /**
  * Marker type for server-side tools
  */
 export interface ServerTool<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TContext = unknown,
-> extends Tool<TInput, TOutput, TName, TContext> {
+  TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+>
+  extends
+    Tool<TInput, TOutput, TName, TContext>,
+    ToolApprovalCapabilityMarker<TNeedsApproval, TApprovalSchema> {
   __toolSide: 'server'
+  inputSchema?: TInput
+  outputSchema?: TOutput
+  needsApproval?: TNeedsApproval
+  approvalSchema?: TApprovalSchema
 }
 
 /**
  * Marker type for client-side tools
  */
 export interface ClientTool<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TContext = unknown,
   // Captured as a literal (`true` / `false`) so downstream types — notably
   // the tool-call part's `approval` field — can be gated on it. Defaults to
   // `false` when the tool config omits `needsApproval`.
   TNeedsApproval extends boolean = false,
-> {
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+> extends ToolApprovalCapabilityMarker<TNeedsApproval, TApprovalSchema> {
   __toolSide: 'client'
   name: TName
   description: string
@@ -42,35 +126,55 @@ export interface ClientTool<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: TNeedsApproval
+  approvalSchema?: TApprovalSchema
   lazy?: boolean
   metadata?: Record<string, unknown>
   execute?: ToolExecuteFunction<TInput, TOutput, TContext>
 }
 
+/** Broad server-tool shape for heterogeneous internal collections. */
+export type AnyServerTool = Omit<
+  ServerTool<any, any, string, any, boolean, any>,
+  'execute'
+> & {
+  execute?: ((args: any, context?: any) => any) | undefined
+}
+
 /**
  * Tool definition that can be used directly or instantiated for server/client
  */
 export interface ToolDefinitionInstance<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TContext = unknown,
   TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
 > extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'definition'
   // Narrow the base `needsApproval?: boolean` to the captured literal so it
   // survives into `ToolCallPartForTool`'s approval gate.
+  inputSchema: TInput
+  outputSchema: TOutput
   needsApproval?: TNeedsApproval
+  approvalSchema: TApprovalSchema
+  readonly [toolApprovalCapability]?: {
+    needsApproval: TNeedsApproval
+    approvalSchema: TApprovalSchema
+  }
 }
 
 /**
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | (Omit<ClientTool<any, any, string, any, boolean>, 'execute'> & {
+  | (Omit<ClientTool<any, any, string, any, boolean, any>, 'execute'> & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
-  | (Omit<ToolDefinitionInstance<any, any, string, any, boolean>, 'execute'> & {
+  | (Omit<
+      ToolDefinitionInstance<any, any, string, any, boolean, any>,
+      'execute'
+    > & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
 
@@ -83,63 +187,73 @@ export type InferToolName<T> = T extends { name: infer N } ? N : never
  * Extract the input type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolInput<T> = T extends { inputSchema?: infer TInput }
-  ? TInput extends StandardJSONSchemaV1<infer TInferred, unknown>
-    ? TInferred
-    : TInput extends JSONSchema
-      ? unknown
-      : unknown
+  ? TInput extends JSONSchema
+    ? unknown
+    : InferSchemaType<TInput>
   : unknown
 
 /**
  * Extract the output type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolOutput<T> = T extends { outputSchema?: infer TOutput }
-  ? TOutput extends StandardJSONSchemaV1<infer TInferred, unknown>
-    ? TInferred
-    : TOutput extends JSONSchema
-      ? unknown
-      : unknown
+  ? TOutput extends StandardJSONSchemaV1<any, any>
+    ? InferSchemaType<TOutput>
+    : TOutput extends StandardSchemaV1<any, any>
+      ? InferSchemaType<TOutput>
+      : TOutput extends JSONSchema
+        ? unknown
+        : InferSchemaType<TOutput>
   : unknown
 
 /**
  * Tool definition configuration
  */
-export interface ToolDefinitionConfig<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+export type ToolDefinitionConfig<
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TNeedsApproval extends boolean = false,
-> {
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+> = {
   name: TName
   description: string
   inputSchema?: TInput
   outputSchema?: TOutput
-  needsApproval?: TNeedsApproval
   lazy?: boolean
   metadata?: Record<string, unknown>
-}
+} & ApprovalConfig<TNeedsApproval, TApprovalSchema>
 
 /**
  * Tool definition builder that allows creating server or client tools from a shared definition
  */
 export interface ToolDefinition<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
 > extends ToolDefinitionInstance<
   TInput,
   TOutput,
   TName,
   unknown,
-  TNeedsApproval
+  TNeedsApproval,
+  TApprovalSchema
 > {
   /**
    * Create a server-side tool with execute function
    */
   server: <TContext = unknown>(
     execute: ToolExecuteFunction<TInput, TOutput, TContext>,
-  ) => ServerTool<TInput, TOutput, TName, TContext>
+  ) => ServerTool<
+    TInput,
+    TOutput,
+    TName,
+    TContext,
+    TNeedsApproval,
+    TApprovalSchema
+  > &
+    BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>
 
   /**
    * Create a client-side tool with optional execute function.
@@ -148,7 +262,15 @@ export interface ToolDefinition<
    */
   client: <TContext = unknown>(
     execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-  ) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval>
+  ) => ClientTool<
+    TInput,
+    TOutput,
+    TName,
+    TContext,
+    TNeedsApproval,
+    TApprovalSchema
+  > &
+    BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>
 }
 
 /**
@@ -207,35 +329,84 @@ export interface ToolDefinition<
  * ```
  */
 export function toolDefinition<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   // `const` forces the literal (`true` / `false`) to be captured from the
   // config's optional `needsApproval` — without it TS widens to `boolean`,
   // which collapses the approval gate in `ToolCallPartForTool`.
   const TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
 >(
-  config: ToolDefinitionConfig<TInput, TOutput, TName, TNeedsApproval>,
-): ToolDefinition<TInput, TOutput, TName, TNeedsApproval> {
-  const definition: ToolDefinition<TInput, TOutput, TName, TNeedsApproval> = {
+  config: ToolDefinitionConfig<
+    TInput,
+    TOutput,
+    TName,
+    TNeedsApproval,
+    TApprovalSchema
+  >,
+): ToolDefinition<TInput, TOutput, TName, TNeedsApproval, TApprovalSchema> {
+  if (config.approvalSchema !== undefined && config.needsApproval !== true) {
+    throw new TypeError('approvalSchema requires needsApproval: true.')
+  }
+  const inputSchema = config.inputSchema as TInput
+  const outputSchema = config.outputSchema as TOutput
+  const approvalSchema = config.approvalSchema as TApprovalSchema
+  const needsApproval = config.needsApproval as TNeedsApproval | undefined
+
+  const definition: ToolDefinition<
+    TInput,
+    TOutput,
+    TName,
+    TNeedsApproval,
+    TApprovalSchema
+  > = {
     __toolSide: 'definition',
     ...config,
+    inputSchema,
+    outputSchema,
+    approvalSchema,
+    needsApproval,
     server<TContext = unknown>(
       execute: ToolExecuteFunction<TInput, TOutput, TContext>,
-    ): ServerTool<TInput, TOutput, TName, TContext> {
+    ): ServerTool<
+      TInput,
+      TOutput,
+      TName,
+      TContext,
+      TNeedsApproval,
+      TApprovalSchema
+    > &
+      BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema> {
       return {
         __toolSide: 'server',
         ...config,
+        inputSchema,
+        outputSchema,
+        approvalSchema,
+        needsApproval,
         execute,
       }
     },
 
     client<TContext = unknown>(
       execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-    ): ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval> {
+    ): ClientTool<
+      TInput,
+      TOutput,
+      TName,
+      TContext,
+      TNeedsApproval,
+      TApprovalSchema
+    > &
+      BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema> {
       return {
         __toolSide: 'client',
         ...config,
+        inputSchema,
+        outputSchema,
+        approvalSchema,
+        needsApproval,
         ...(execute !== undefined && { execute }),
       }
     },