@openrouter/sdk 0.3.14 → 0.3.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/esm/funcs/analyticsGetUserActivity.d.ts +1 -1
  2. package/esm/funcs/analyticsGetUserActivity.js +1 -1
  3. package/esm/funcs/apiKeysCreate.d.ts +3 -0
  4. package/esm/funcs/apiKeysCreate.js +3 -0
  5. package/esm/funcs/apiKeysDelete.d.ts +3 -0
  6. package/esm/funcs/apiKeysDelete.js +3 -0
  7. package/esm/funcs/apiKeysGet.d.ts +3 -0
  8. package/esm/funcs/apiKeysGet.js +3 -0
  9. package/esm/funcs/apiKeysList.d.ts +3 -0
  10. package/esm/funcs/apiKeysList.js +3 -0
  11. package/esm/funcs/apiKeysUpdate.d.ts +3 -0
  12. package/esm/funcs/apiKeysUpdate.js +3 -0
  13. package/esm/funcs/call-model.js +9 -6
  14. package/esm/funcs/creditsGetCredits.d.ts +1 -1
  15. package/esm/funcs/creditsGetCredits.js +1 -1
  16. package/esm/funcs/guardrailsBulkAssignKeys.d.ts +18 -0
  17. package/esm/funcs/guardrailsBulkAssignKeys.js +89 -0
  18. package/esm/funcs/guardrailsBulkAssignMembers.d.ts +18 -0
  19. package/esm/funcs/guardrailsBulkAssignMembers.js +89 -0
  20. package/esm/funcs/guardrailsBulkUnassignKeys.d.ts +18 -0
  21. package/esm/funcs/guardrailsBulkUnassignKeys.js +89 -0
  22. package/esm/funcs/guardrailsBulkUnassignMembers.d.ts +18 -0
  23. package/esm/funcs/guardrailsBulkUnassignMembers.js +89 -0
  24. package/esm/funcs/guardrailsCreate.d.ts +18 -0
  25. package/esm/funcs/guardrailsCreate.js +83 -0
  26. package/esm/funcs/guardrailsDelete.d.ts +18 -0
  27. package/esm/funcs/guardrailsDelete.js +88 -0
  28. package/esm/funcs/{parametersGetParameters.d.ts → guardrailsGet.d.ts} +6 -3
  29. package/esm/funcs/guardrailsGet.js +88 -0
  30. package/esm/funcs/guardrailsList.d.ts +18 -0
  31. package/esm/funcs/guardrailsList.js +87 -0
  32. package/esm/funcs/guardrailsListGuardrailKeyAssignments.d.ts +18 -0
  33. package/esm/funcs/guardrailsListGuardrailKeyAssignments.js +93 -0
  34. package/esm/funcs/guardrailsListGuardrailMemberAssignments.d.ts +18 -0
  35. package/esm/funcs/guardrailsListGuardrailMemberAssignments.js +93 -0
  36. package/esm/funcs/guardrailsListKeyAssignments.d.ts +18 -0
  37. package/esm/funcs/guardrailsListKeyAssignments.js +87 -0
  38. package/esm/funcs/guardrailsListMemberAssignments.d.ts +18 -0
  39. package/esm/funcs/guardrailsListMemberAssignments.js +87 -0
  40. package/esm/funcs/guardrailsUpdate.d.ts +18 -0
  41. package/esm/funcs/{parametersGetParameters.js → guardrailsUpdate.js} +24 -32
  42. package/esm/index.d.ts +4 -3
  43. package/esm/index.js +3 -1
  44. package/esm/lib/async-params.d.ts +46 -6
  45. package/esm/lib/async-params.js +10 -2
  46. package/esm/lib/config.d.ts +2 -4
  47. package/esm/lib/config.js +2 -2
  48. package/esm/lib/conversation-state.d.ts +61 -0
  49. package/esm/lib/conversation-state.js +207 -0
  50. package/esm/lib/model-result.d.ts +179 -4
  51. package/esm/lib/model-result.js +719 -191
  52. package/esm/lib/tool-executor.js +37 -13
  53. package/esm/lib/tool-types.d.ts +135 -2
  54. package/esm/lib/tool-types.js +19 -0
  55. package/esm/lib/tool.d.ts +21 -1
  56. package/esm/lib/tool.js +7 -0
  57. package/esm/models/assistantmessage.d.ts +31 -0
  58. package/esm/models/assistantmessage.js +43 -0
  59. package/esm/models/chatmessagecontentitemimage.d.ts +8 -8
  60. package/esm/models/chatmessagecontentitemimage.js +8 -9
  61. package/esm/models/chatresponsechoice.d.ts +0 -2
  62. package/esm/models/chatresponsechoice.js +0 -3
  63. package/esm/models/chatstreamingmessagechunk.d.ts +2 -2
  64. package/esm/models/chatstreamingmessagechunk.js +2 -2
  65. package/esm/models/index.d.ts +1 -1
  66. package/esm/models/index.js +1 -1
  67. package/esm/models/model.d.ts +4 -0
  68. package/esm/models/model.js +2 -0
  69. package/esm/models/operations/bulkassignkeystoguardrail.d.ts +44 -0
  70. package/esm/models/operations/bulkassignkeystoguardrail.js +42 -0
  71. package/esm/models/operations/bulkassignmemberstoguardrail.d.ts +44 -0
  72. package/esm/models/operations/bulkassignmemberstoguardrail.js +42 -0
  73. package/esm/models/operations/bulkunassignkeysfromguardrail.d.ts +44 -0
  74. package/esm/models/operations/bulkunassignkeysfromguardrail.js +42 -0
  75. package/esm/models/operations/bulkunassignmembersfromguardrail.d.ts +44 -0
  76. package/esm/models/operations/bulkunassignmembersfromguardrail.js +42 -0
  77. package/esm/models/operations/createguardrail.d.ts +136 -0
  78. package/esm/models/operations/createguardrail.js +85 -0
  79. package/esm/models/operations/deleteguardrail.d.ts +29 -0
  80. package/esm/models/operations/deleteguardrail.js +21 -0
  81. package/esm/models/operations/getguardrail.d.ts +92 -0
  82. package/esm/models/operations/getguardrail.js +60 -0
  83. package/esm/models/operations/getmodels.d.ts +28 -1
  84. package/esm/models/operations/getmodels.js +22 -1
  85. package/esm/models/operations/index.d.ts +13 -1
  86. package/esm/models/operations/index.js +13 -1
  87. package/esm/models/operations/listguardrailkeyassignments.d.ts +76 -0
  88. package/esm/models/operations/listguardrailkeyassignments.js +51 -0
  89. package/esm/models/operations/listguardrailmemberassignments.d.ts +72 -0
  90. package/esm/models/operations/listguardrailmemberassignments.js +49 -0
  91. package/esm/models/operations/listguardrails.d.ts +98 -0
  92. package/esm/models/operations/listguardrails.js +66 -0
  93. package/esm/models/operations/listkeyassignments.d.ts +71 -0
  94. package/esm/models/operations/listkeyassignments.js +50 -0
  95. package/esm/models/operations/listmemberassignments.d.ts +67 -0
  96. package/esm/models/operations/listmemberassignments.js +48 -0
  97. package/esm/models/operations/updateguardrail.d.ts +151 -0
  98. package/esm/models/operations/updateguardrail.js +97 -0
  99. package/esm/models/outputmodality.d.ts +1 -0
  100. package/esm/models/outputmodality.js +1 -0
  101. package/esm/models/percentilelatencycutoffs.js +1 -1
  102. package/esm/models/percentilestats.js +1 -1
  103. package/esm/models/percentilethroughputcutoffs.js +1 -1
  104. package/esm/models/preferredmaxlatency.js +1 -1
  105. package/esm/models/preferredminthroughput.js +1 -1
  106. package/esm/models/publicendpoint.d.ts +8 -0
  107. package/esm/models/publicendpoint.js +4 -0
  108. package/esm/models/publicpricing.d.ts +4 -0
  109. package/esm/models/publicpricing.js +2 -0
  110. package/esm/models/responseinputvideo.js +1 -1
  111. package/esm/models/responsesoutputmodality.js +1 -1
  112. package/esm/models/schema2.d.ts +92 -0
  113. package/esm/models/schema2.js +109 -0
  114. package/esm/sdk/analytics.d.ts +1 -1
  115. package/esm/sdk/analytics.js +1 -1
  116. package/esm/sdk/apikeys.d.ts +15 -0
  117. package/esm/sdk/apikeys.js +15 -0
  118. package/esm/sdk/credits.d.ts +1 -1
  119. package/esm/sdk/credits.js +1 -1
  120. package/esm/sdk/guardrails.d.ts +96 -0
  121. package/esm/sdk/guardrails.js +139 -0
  122. package/esm/sdk/sdk.d.ts +3 -3
  123. package/esm/sdk/sdk.js +4 -4
  124. package/esm/types/index.d.ts +2 -0
  125. package/esm/types/index.js +1 -0
  126. package/esm/types/models.d.ts +25 -0
  127. package/esm/types/models.js +10 -0
  128. package/jsr.json +1 -1
  129. package/package.json +12 -10
  130. package/scripts/check-types.js +127 -0
  131. package/esm/models/operations/getparameters.d.ts +0 -87
  132. package/esm/models/operations/getparameters.js +0 -73
  133. package/esm/models/schema3.d.ts +0 -51
  134. package/esm/models/schema3.js +0 -62
  135. package/esm/sdk/parameters.d.ts +0 -9
  136. package/esm/sdk/parameters.js +0 -16
@@ -87,6 +87,14 @@ export function validateToolInput(schema, args) {
87
87
  export function validateToolOutput(schema, result) {
88
88
  return z4.parse(schema, result);
89
89
  }
90
+ /**
91
+ * Try to validate a value against a Zod schema without throwing
92
+ * @returns true if validation succeeds, false otherwise
93
+ */
94
+ function tryValidate(schema, value) {
95
+ const result = z4.safeParse(schema, value);
96
+ return result.success;
97
+ }
90
98
  /**
91
99
  * Parse tool call arguments from JSON string
92
100
  */
@@ -150,29 +158,45 @@ export async function executeGeneratorTool(tool, toolCall, context, onPreliminar
150
158
  // Validate input - the schema validation ensures type safety at runtime
151
159
  // The inputSchema's inferred type matches the execute function's parameter type by construction
152
160
  const validatedInput = validateToolInput(tool.function.inputSchema, toolCall.arguments);
153
- // Execute generator and collect all results
161
+ // Stream preliminary results in realtime
162
+ // Final result is identified by: matches outputSchema BUT NOT eventSchema
163
+ // All other yields are preliminary results (validated against eventSchema)
164
+ // If no explicit final result is found, the last emitted value is used as the final result
154
165
  const preliminaryResults = [];
155
- let lastEmittedValue = null;
166
+ let finalResult = undefined;
167
+ let hasFinalResult = false;
168
+ let lastEmittedValue = undefined;
156
169
  let hasEmittedValue = false;
157
170
  for await (const event of tool.function.execute(validatedInput, context)) {
171
+ lastEmittedValue = event;
158
172
  hasEmittedValue = true;
159
- // Validate event against eventSchema
160
- const validatedEvent = validateToolOutput(tool.function.eventSchema, event);
161
- preliminaryResults.push(validatedEvent);
162
- lastEmittedValue = validatedEvent;
163
- // Emit preliminary result via callback
164
- if (onPreliminaryResult) {
165
- onPreliminaryResult(toolCall.id, validatedEvent);
173
+ // Try to determine if this is the final result:
174
+ // It must match outputSchema but NOT match eventSchema
175
+ const matchesOutputSchema = tryValidate(tool.function.outputSchema, event);
176
+ const matchesEventSchema = tryValidate(tool.function.eventSchema, event);
177
+ if (matchesOutputSchema && !matchesEventSchema && !hasFinalResult) {
178
+ // This is the final result - matches output but not event schema
179
+ finalResult = validateToolOutput(tool.function.outputSchema, event);
180
+ hasFinalResult = true;
181
+ }
182
+ else {
183
+ // This is a preliminary result - validate against eventSchema and emit in realtime
184
+ const validatedPreliminary = validateToolOutput(tool.function.eventSchema, event);
185
+ preliminaryResults.push(validatedPreliminary);
186
+ if (onPreliminaryResult) {
187
+ onPreliminaryResult(toolCall.id, validatedPreliminary);
188
+ }
166
189
  }
167
190
  }
168
191
  // Generator must emit at least one value
169
192
  if (!hasEmittedValue) {
170
193
  throw new Error(`Generator tool "${toolCall.name}" completed without emitting any values`);
171
194
  }
172
- // Validate the last emitted value against outputSchema (this is the final result)
173
- const finalResult = validateToolOutput(tool.function.outputSchema, lastEmittedValue);
174
- // Remove last item from preliminaryResults since it's the final output
175
- preliminaryResults.pop();
195
+ // If no explicit final result was found (no yield matched outputSchema but not eventSchema),
196
+ // use the last emitted value as the final result
197
+ if (!hasFinalResult) {
198
+ finalResult = validateToolOutput(tool.function.outputSchema, lastEmittedValue);
199
+ }
176
200
  return {
177
201
  toolCallId: toolCall.id,
178
202
  toolName: toolCall.name,
@@ -50,6 +50,12 @@ export type NextTurnParamsContext = {
50
50
  export type NextTurnParamsFunctions<TInput> = {
51
51
  [K in keyof NextTurnParamsContext]?: (params: TInput, context: NextTurnParamsContext) => NextTurnParamsContext[K] | Promise<NextTurnParamsContext[K]>;
52
52
  };
53
+ /**
54
+ * Tool-level approval check function type
55
+ * Receives the tool's input params and turn context
56
+ * Returns true if approval is required, false otherwise
57
+ */
58
+ export type ToolApprovalCheck<TInput> = (params: TInput, context: TurnContext) => boolean | Promise<boolean>;
53
59
  /**
54
60
  * Base tool function interface with inputSchema
55
61
  */
@@ -58,6 +64,11 @@ export interface BaseToolFunction<TInput extends $ZodObject<$ZodShape>> {
58
64
  description?: string;
59
65
  inputSchema: TInput;
60
66
  nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
67
+ /**
68
+ * Whether this tool requires human approval before execution
69
+ * Can be a boolean or an async function that receives the tool's input params and context
70
+ */
71
+ requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
61
72
  }
62
73
  /**
63
74
  * Regular tool with synchronous or asynchronous execute function and optional outputSchema
@@ -164,6 +175,13 @@ export type TypedToolCallUnion<T extends readonly Tool[]> = {
164
175
  export type ToolExecutionResultUnion<T extends readonly Tool[]> = {
165
176
  [K in keyof T]: T[K] extends Tool ? ToolExecutionResult<T[K]> : never;
166
177
  }[number];
178
+ /**
179
+ * Union of output types for all tools in a tuple
180
+ * Used for typing tool result events
181
+ */
182
+ export type InferToolOutputsUnion<T extends readonly Tool[]> = {
183
+ [K in keyof T]: T[K] extends Tool ? InferToolOutput<T[K]> : never;
184
+ }[number];
167
185
  /**
168
186
  * Extracts the event type from a generator tool definition
169
187
  * Returns `never` for non-generator tools
@@ -289,16 +307,34 @@ export type ToolPreliminaryResultEvent<TEvent = unknown> = {
289
307
  result: TEvent;
290
308
  timestamp: number;
291
309
  };
310
+ /**
311
+ * Tool result event emitted when a tool execution completes
312
+ * Contains the final result and any preliminary results that were emitted
313
+ * @template TResult - The result type from the tool's outputSchema
314
+ * @template TPreliminaryResults - The event type from generator tools' eventSchema
315
+ */
316
+ export type ToolResultEvent<TResult = unknown, TPreliminaryResults = unknown> = {
317
+ type: 'tool.result';
318
+ toolCallId: string;
319
+ result: TResult;
320
+ timestamp: number;
321
+ preliminaryResults?: TPreliminaryResults[];
322
+ };
292
323
  /**
293
324
  * Enhanced stream event types for getFullResponsesStream
294
- * Extends OpenResponsesStreamEvent with tool preliminary results
325
+ * Extends OpenResponsesStreamEvent with tool preliminary results and tool results
295
326
  * @template TEvent - The event type from generator tools
327
+ * @template TResult - The result type from tool execution
296
328
  */
297
- export type ResponseStreamEvent<TEvent = unknown> = OpenResponsesStreamEvent | ToolPreliminaryResultEvent<TEvent>;
329
+ export type ResponseStreamEvent<TEvent = unknown, TResult = unknown> = OpenResponsesStreamEvent | ToolPreliminaryResultEvent<TEvent> | ToolResultEvent<TResult, TEvent>;
298
330
  /**
299
331
  * Type guard to check if an event is a tool preliminary result event
300
332
  */
301
333
  export declare function isToolPreliminaryResultEvent<TEvent = unknown>(event: ResponseStreamEvent<TEvent>): event is ToolPreliminaryResultEvent<TEvent>;
334
+ /**
335
+ * Type guard to check if an event is a tool result event
336
+ */
337
+ export declare function isToolResultEvent<TResult = unknown, TPreliminaryResults = unknown>(event: ResponseStreamEvent<TPreliminaryResults, TResult>): event is ToolResultEvent<TResult, TPreliminaryResults>;
302
338
  /**
303
339
  * Tool stream event types for getToolStream
304
340
  * Includes both argument deltas and preliminary results
@@ -331,4 +367,101 @@ export type ChatStreamEvent<TEvent = unknown> = {
331
367
  type: string;
332
368
  event: OpenResponsesStreamEvent;
333
369
  };
370
+ /**
371
+ * Result of a tool execution that hasn't been sent to the model yet
372
+ * Used for interrupted or awaiting approval states
373
+ * @template TTools - The tools array type for proper type inference
374
+ */
375
+ export interface UnsentToolResult<TTools extends readonly Tool[] = readonly Tool[]> {
376
+ /** The ID of the tool call this result is for */
377
+ callId: string;
378
+ /** The name of the tool that was executed */
379
+ name: TTools[number]['function']['name'];
380
+ /** The output of the tool execution */
381
+ output: unknown;
382
+ /** Error message if the tool call was rejected or failed */
383
+ error?: string;
384
+ }
385
+ /**
386
+ * Partial response captured during interruption
387
+ * @template TTools - The tools array type for proper type inference
388
+ */
389
+ export interface PartialResponse<TTools extends readonly Tool[] = readonly Tool[]> {
390
+ /** Partial text response accumulated before interruption */
391
+ text?: string;
392
+ /** Tool calls that were in progress when interrupted */
393
+ toolCalls?: Array<ParsedToolCall<TTools[number]>>;
394
+ }
395
+ /**
396
+ * Status of a conversation state
397
+ */
398
+ export type ConversationStatus = 'complete' | 'interrupted' | 'awaiting_approval' | 'in_progress';
399
+ /**
400
+ * State for multi-turn conversations with persistence and approval gates
401
+ * @template TTools - The tools array type for proper type inference
402
+ */
403
+ export interface ConversationState<TTools extends readonly Tool[] = readonly Tool[]> {
404
+ /** Unique identifier for this conversation */
405
+ id: string;
406
+ /** Full message history */
407
+ messages: models.OpenResponsesInput;
408
+ /** Previous response ID for chaining (OpenRouter server-side optimization) */
409
+ previousResponseId?: string;
410
+ /** Tool calls awaiting human approval */
411
+ pendingToolCalls?: Array<ParsedToolCall<TTools[number]>>;
412
+ /** Tool results executed but not yet sent to the model */
413
+ unsentToolResults?: Array<UnsentToolResult<TTools>>;
414
+ /** Partial response data captured during interruption */
415
+ partialResponse?: PartialResponse<TTools>;
416
+ /** Signal from a new request to interrupt this conversation */
417
+ interruptedBy?: string;
418
+ /** Current status of the conversation */
419
+ status: ConversationStatus;
420
+ /** Creation timestamp (Unix ms) */
421
+ createdAt: number;
422
+ /** Last update timestamp (Unix ms) */
423
+ updatedAt: number;
424
+ }
425
+ /**
426
+ * State accessor for loading and saving conversation state
427
+ * Enables any storage backend (memory, Redis, database, etc.)
428
+ * @template TTools - The tools array type for proper type inference
429
+ */
430
+ export interface StateAccessor<TTools extends readonly Tool[] = readonly Tool[]> {
431
+ /** Load the current conversation state, or null if none exists */
432
+ load: () => Promise<ConversationState<TTools> | null>;
433
+ /** Save the conversation state */
434
+ save: (state: ConversationState<TTools>) => Promise<void>;
435
+ }
436
+ /**
437
+ * Check if a single tool has approval configured (non-false, non-undefined)
438
+ * Returns true if the tool definitely requires approval,
439
+ * false if it definitely doesn't, or boolean if it's uncertain
440
+ */
441
+ export type ToolHasApproval<T extends Tool> = T extends {
442
+ function: {
443
+ requireApproval: true | ToolApprovalCheck<unknown>;
444
+ };
445
+ } ? true : T extends {
446
+ function: {
447
+ requireApproval: false;
448
+ };
449
+ } ? false : T extends {
450
+ function: {
451
+ requireApproval: undefined;
452
+ };
453
+ } ? false : boolean;
454
+ /**
455
+ * Check if ANY tool in an array has approval configured
456
+ * Returns true if at least one tool might require approval
457
+ */
458
+ export type HasApprovalTools<TTools extends readonly Tool[]> = TTools extends readonly [infer First extends Tool, ...infer Rest extends Tool[]] ? ToolHasApproval<First> extends true ? true : HasApprovalTools<Rest> : false;
459
+ /**
460
+ * Type guard to check if a tool has approval configured at runtime
461
+ */
462
+ export declare function toolHasApprovalConfigured(tool: Tool): boolean;
463
+ /**
464
+ * Type guard to check if any tools in array have approval configured at runtime
465
+ */
466
+ export declare function hasApprovalRequiredTools(tools: readonly Tool[]): boolean;
334
467
  //# sourceMappingURL=tool-types.d.ts.map
@@ -35,4 +35,23 @@ export function isManualTool(tool) {
35
35
  export function isToolPreliminaryResultEvent(event) {
36
36
  return event.type === 'tool.preliminary_result';
37
37
  }
38
+ /**
39
+ * Type guard to check if an event is a tool result event
40
+ */
41
+ export function isToolResultEvent(event) {
42
+ return event.type === 'tool.result';
43
+ }
44
+ /**
45
+ * Type guard to check if a tool has approval configured at runtime
46
+ */
47
+ export function toolHasApprovalConfigured(tool) {
48
+ const requireApproval = tool.function.requireApproval;
49
+ return requireApproval === true || typeof requireApproval === 'function';
50
+ }
51
+ /**
52
+ * Type guard to check if any tools in array have approval configured at runtime
53
+ */
54
+ export function hasApprovalRequiredTools(tools) {
55
+ return tools.some(toolHasApprovalConfigured);
56
+ }
38
57
  //# sourceMappingURL=tool-types.js.map
package/esm/lib/tool.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { $ZodObject, $ZodShape, $ZodType, infer as zodInfer } from 'zod/v4/core';
2
- import { type TurnContext, type ToolWithExecute, type ToolWithGenerator, type ManualTool, type NextTurnParamsFunctions } from "./tool-types.js";
2
+ import { type TurnContext, type ToolWithExecute, type ToolWithGenerator, type ManualTool, type NextTurnParamsFunctions, type ToolApprovalCheck } from "./tool-types.js";
3
3
  /**
4
4
  * Configuration for a regular tool with outputSchema
5
5
  */
@@ -10,6 +10,11 @@ type RegularToolConfigWithOutput<TInput extends $ZodObject<$ZodShape>, TOutput e
10
10
  outputSchema: TOutput;
11
11
  eventSchema?: undefined;
12
12
  nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
13
+ /**
14
+ * Whether this tool requires human approval before execution
15
+ * Can be a boolean or an async function that receives the tool's input params and context
16
+ */
17
+ requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
13
18
  execute: (params: zodInfer<TInput>, context?: TurnContext) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
14
19
  };
15
20
  /**
@@ -22,6 +27,11 @@ type RegularToolConfigWithoutOutput<TInput extends $ZodObject<$ZodShape>, TRetur
22
27
  outputSchema?: undefined;
23
28
  eventSchema?: undefined;
24
29
  nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
30
+ /**
31
+ * Whether this tool requires human approval before execution
32
+ * Can be a boolean or an async function that receives the tool's input params and context
33
+ */
34
+ requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
25
35
  execute: (params: zodInfer<TInput>, context?: TurnContext) => Promise<TReturn> | TReturn;
26
36
  };
27
37
  /**
@@ -34,6 +44,11 @@ type GeneratorToolConfig<TInput extends $ZodObject<$ZodShape>, TEvent extends $Z
34
44
  eventSchema: TEvent;
35
45
  outputSchema: TOutput;
36
46
  nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
47
+ /**
48
+ * Whether this tool requires human approval before execution
49
+ * Can be a boolean or an async function that receives the tool's input params and context
50
+ */
51
+ requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
37
52
  execute: (params: zodInfer<TInput>, context?: TurnContext) => AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>>;
38
53
  };
39
54
  /**
@@ -44,6 +59,11 @@ type ManualToolConfig<TInput extends $ZodObject<$ZodShape>> = {
44
59
  description?: string;
45
60
  inputSchema: TInput;
46
61
  nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
62
+ /**
63
+ * Whether this tool requires human approval before execution
64
+ * Can be a boolean or an async function that receives the tool's input params and context
65
+ */
66
+ requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
47
67
  execute: false;
48
68
  };
49
69
  /**
package/esm/lib/tool.js CHANGED
@@ -25,6 +25,9 @@ export function tool(config) {
25
25
  if (config.nextTurnParams !== undefined) {
26
26
  fn.nextTurnParams = config.nextTurnParams;
27
27
  }
28
+ if (config.requireApproval !== undefined) {
29
+ fn.requireApproval = config.requireApproval;
30
+ }
28
31
  return {
29
32
  type: ToolType.Function,
30
33
  function: fn,
@@ -46,6 +49,9 @@ export function tool(config) {
46
49
  if (config.nextTurnParams !== undefined) {
47
50
  fn.nextTurnParams = config.nextTurnParams;
48
51
  }
52
+ if (config.requireApproval !== undefined) {
53
+ fn.requireApproval = config.requireApproval;
54
+ }
49
55
  return {
50
56
  type: ToolType.Function,
51
57
  function: fn,
@@ -61,6 +67,7 @@ export function tool(config) {
61
67
  ...(config.description !== undefined && { description: config.description }),
62
68
  ...(config.outputSchema !== undefined && { outputSchema: config.outputSchema }),
63
69
  ...(config.nextTurnParams !== undefined && { nextTurnParams: config.nextTurnParams }),
70
+ ...(config.requireApproval !== undefined && { requireApproval: config.requireApproval }),
64
71
  };
65
72
  // The function signature guarantees this is type-safe via overloads
66
73
  return {
@@ -3,7 +3,14 @@ import { Result as SafeParseResult } from "../types/fp.js";
3
3
  import { ChatMessageContentItem, ChatMessageContentItem$Outbound } from "./chatmessagecontentitem.js";
4
4
  import { ChatMessageToolCall, ChatMessageToolCall$Outbound } from "./chatmessagetoolcall.js";
5
5
  import { SDKValidationError } from "./errors/sdkvalidationerror.js";
6
+ import { Schema2, Schema2$Outbound } from "./schema2.js";
6
7
  export type AssistantMessageContent = string | Array<ChatMessageContentItem>;
8
+ export type AssistantMessageImageUrl = {
9
+ url: string;
10
+ };
11
+ export type Image = {
12
+ imageUrl: AssistantMessageImageUrl;
13
+ };
7
14
  export type AssistantMessage = {
8
15
  role: "assistant";
9
16
  content?: string | Array<ChatMessageContentItem> | null | undefined;
@@ -11,6 +18,8 @@ export type AssistantMessage = {
11
18
  toolCalls?: Array<ChatMessageToolCall> | undefined;
12
19
  refusal?: string | null | undefined;
13
20
  reasoning?: string | null | undefined;
21
+ reasoningDetails?: Array<Schema2> | undefined;
22
+ images?: Array<Image> | undefined;
14
23
  };
15
24
  /** @internal */
16
25
  export declare const AssistantMessageContent$inboundSchema: z.ZodType<AssistantMessageContent, unknown>;
@@ -21,6 +30,26 @@ export declare const AssistantMessageContent$outboundSchema: z.ZodType<Assistant
21
30
  export declare function assistantMessageContentToJSON(assistantMessageContent: AssistantMessageContent): string;
22
31
  export declare function assistantMessageContentFromJSON(jsonString: string): SafeParseResult<AssistantMessageContent, SDKValidationError>;
23
32
  /** @internal */
33
+ export declare const AssistantMessageImageUrl$inboundSchema: z.ZodType<AssistantMessageImageUrl, unknown>;
34
+ /** @internal */
35
+ export type AssistantMessageImageUrl$Outbound = {
36
+ url: string;
37
+ };
38
+ /** @internal */
39
+ export declare const AssistantMessageImageUrl$outboundSchema: z.ZodType<AssistantMessageImageUrl$Outbound, AssistantMessageImageUrl>;
40
+ export declare function assistantMessageImageUrlToJSON(assistantMessageImageUrl: AssistantMessageImageUrl): string;
41
+ export declare function assistantMessageImageUrlFromJSON(jsonString: string): SafeParseResult<AssistantMessageImageUrl, SDKValidationError>;
42
+ /** @internal */
43
+ export declare const Image$inboundSchema: z.ZodType<Image, unknown>;
44
+ /** @internal */
45
+ export type Image$Outbound = {
46
+ image_url: AssistantMessageImageUrl$Outbound;
47
+ };
48
+ /** @internal */
49
+ export declare const Image$outboundSchema: z.ZodType<Image$Outbound, Image>;
50
+ export declare function imageToJSON(image: Image): string;
51
+ export declare function imageFromJSON(jsonString: string): SafeParseResult<Image, SDKValidationError>;
52
+ /** @internal */
24
53
  export declare const AssistantMessage$inboundSchema: z.ZodType<AssistantMessage, unknown>;
25
54
  /** @internal */
26
55
  export type AssistantMessage$Outbound = {
@@ -30,6 +59,8 @@ export type AssistantMessage$Outbound = {
30
59
  tool_calls?: Array<ChatMessageToolCall$Outbound> | undefined;
31
60
  refusal?: string | null | undefined;
32
61
  reasoning?: string | null | undefined;
62
+ reasoning_details?: Array<Schema2$Outbound> | undefined;
63
+ images?: Array<Image$Outbound> | undefined;
33
64
  };
34
65
  /** @internal */
35
66
  export declare const AssistantMessage$outboundSchema: z.ZodType<AssistantMessage$Outbound, AssistantMessage>;
@@ -7,6 +7,7 @@ import { remap as remap$ } from "../lib/primitives.js";
7
7
  import { safeParse } from "../lib/schemas.js";
8
8
  import { ChatMessageContentItem$inboundSchema, ChatMessageContentItem$outboundSchema, } from "./chatmessagecontentitem.js";
9
9
  import { ChatMessageToolCall$inboundSchema, ChatMessageToolCall$outboundSchema, } from "./chatmessagetoolcall.js";
10
+ import { Schema2$inboundSchema, Schema2$outboundSchema, } from "./schema2.js";
10
11
  /** @internal */
11
12
  export const AssistantMessageContent$inboundSchema = z.union([z.string(), z.array(ChatMessageContentItem$inboundSchema)]);
12
13
  /** @internal */
@@ -18,6 +19,42 @@ export function assistantMessageContentFromJSON(jsonString) {
18
19
  return safeParse(jsonString, (x) => AssistantMessageContent$inboundSchema.parse(JSON.parse(x)), `Failed to parse 'AssistantMessageContent' from JSON`);
19
20
  }
20
21
  /** @internal */
22
+ export const AssistantMessageImageUrl$inboundSchema = z.object({
23
+ url: z.string(),
24
+ });
25
+ /** @internal */
26
+ export const AssistantMessageImageUrl$outboundSchema = z.object({
27
+ url: z.string(),
28
+ });
29
+ export function assistantMessageImageUrlToJSON(assistantMessageImageUrl) {
30
+ return JSON.stringify(AssistantMessageImageUrl$outboundSchema.parse(assistantMessageImageUrl));
31
+ }
32
+ export function assistantMessageImageUrlFromJSON(jsonString) {
33
+ return safeParse(jsonString, (x) => AssistantMessageImageUrl$inboundSchema.parse(JSON.parse(x)), `Failed to parse 'AssistantMessageImageUrl' from JSON`);
34
+ }
35
+ /** @internal */
36
+ export const Image$inboundSchema = z.object({
37
+ image_url: z.lazy(() => AssistantMessageImageUrl$inboundSchema),
38
+ }).transform((v) => {
39
+ return remap$(v, {
40
+ "image_url": "imageUrl",
41
+ });
42
+ });
43
+ /** @internal */
44
+ export const Image$outboundSchema = z.object({
45
+ imageUrl: z.lazy(() => AssistantMessageImageUrl$outboundSchema),
46
+ }).transform((v) => {
47
+ return remap$(v, {
48
+ imageUrl: "image_url",
49
+ });
50
+ });
51
+ export function imageToJSON(image) {
52
+ return JSON.stringify(Image$outboundSchema.parse(image));
53
+ }
54
+ export function imageFromJSON(jsonString) {
55
+ return safeParse(jsonString, (x) => Image$inboundSchema.parse(JSON.parse(x)), `Failed to parse 'Image' from JSON`);
56
+ }
57
+ /** @internal */
21
58
  export const AssistantMessage$inboundSchema = z.object({
22
59
  role: z.literal("assistant"),
23
60
  content: z.nullable(z.union([z.string(), z.array(ChatMessageContentItem$inboundSchema)])).optional(),
@@ -25,9 +62,12 @@ export const AssistantMessage$inboundSchema = z.object({
25
62
  tool_calls: z.array(ChatMessageToolCall$inboundSchema).optional(),
26
63
  refusal: z.nullable(z.string()).optional(),
27
64
  reasoning: z.nullable(z.string()).optional(),
65
+ reasoning_details: z.array(Schema2$inboundSchema).optional(),
66
+ images: z.array(z.lazy(() => Image$inboundSchema)).optional(),
28
67
  }).transform((v) => {
29
68
  return remap$(v, {
30
69
  "tool_calls": "toolCalls",
70
+ "reasoning_details": "reasoningDetails",
31
71
  });
32
72
  });
33
73
  /** @internal */
@@ -38,9 +78,12 @@ export const AssistantMessage$outboundSchema = z.object({
38
78
  toolCalls: z.array(ChatMessageToolCall$outboundSchema).optional(),
39
79
  refusal: z.nullable(z.string()).optional(),
40
80
  reasoning: z.nullable(z.string()).optional(),
81
+ reasoningDetails: z.array(Schema2$outboundSchema).optional(),
82
+ images: z.array(z.lazy(() => Image$outboundSchema)).optional(),
41
83
  }).transform((v) => {
42
84
  return remap$(v, {
43
85
  toolCalls: "tool_calls",
86
+ reasoningDetails: "reasoning_details",
44
87
  });
45
88
  });
46
89
  export function assistantMessageToJSON(assistantMessage) {
@@ -8,35 +8,35 @@ export declare const ChatMessageContentItemImageDetail: {
8
8
  readonly High: "high";
9
9
  };
10
10
  export type ChatMessageContentItemImageDetail = OpenEnum<typeof ChatMessageContentItemImageDetail>;
11
- export type ImageUrl = {
11
+ export type ChatMessageContentItemImageImageUrl = {
12
12
  url: string;
13
13
  detail?: ChatMessageContentItemImageDetail | undefined;
14
14
  };
15
15
  export type ChatMessageContentItemImage = {
16
16
  type: "image_url";
17
- imageUrl: ImageUrl;
17
+ imageUrl: ChatMessageContentItemImageImageUrl;
18
18
  };
19
19
  /** @internal */
20
20
  export declare const ChatMessageContentItemImageDetail$inboundSchema: z.ZodType<ChatMessageContentItemImageDetail, unknown>;
21
21
  /** @internal */
22
22
  export declare const ChatMessageContentItemImageDetail$outboundSchema: z.ZodType<string, ChatMessageContentItemImageDetail>;
23
23
  /** @internal */
24
- export declare const ImageUrl$inboundSchema: z.ZodType<ImageUrl, unknown>;
24
+ export declare const ChatMessageContentItemImageImageUrl$inboundSchema: z.ZodType<ChatMessageContentItemImageImageUrl, unknown>;
25
25
  /** @internal */
26
- export type ImageUrl$Outbound = {
26
+ export type ChatMessageContentItemImageImageUrl$Outbound = {
27
27
  url: string;
28
28
  detail?: string | undefined;
29
29
  };
30
30
  /** @internal */
31
- export declare const ImageUrl$outboundSchema: z.ZodType<ImageUrl$Outbound, ImageUrl>;
32
- export declare function imageUrlToJSON(imageUrl: ImageUrl): string;
33
- export declare function imageUrlFromJSON(jsonString: string): SafeParseResult<ImageUrl, SDKValidationError>;
31
+ export declare const ChatMessageContentItemImageImageUrl$outboundSchema: z.ZodType<ChatMessageContentItemImageImageUrl$Outbound, ChatMessageContentItemImageImageUrl>;
32
+ export declare function chatMessageContentItemImageImageUrlToJSON(chatMessageContentItemImageImageUrl: ChatMessageContentItemImageImageUrl): string;
33
+ export declare function chatMessageContentItemImageImageUrlFromJSON(jsonString: string): SafeParseResult<ChatMessageContentItemImageImageUrl, SDKValidationError>;
34
34
  /** @internal */
35
35
  export declare const ChatMessageContentItemImage$inboundSchema: z.ZodType<ChatMessageContentItemImage, unknown>;
36
36
  /** @internal */
37
37
  export type ChatMessageContentItemImage$Outbound = {
38
38
  type: "image_url";
39
- image_url: ImageUrl$Outbound;
39
+ image_url: ChatMessageContentItemImageImageUrl$Outbound;
40
40
  };
41
41
  /** @internal */
42
42
  export declare const ChatMessageContentItemImage$outboundSchema: z.ZodType<ChatMessageContentItemImage$Outbound, ChatMessageContentItemImage>;
@@ -16,26 +16,25 @@ export const ChatMessageContentItemImageDetail$inboundSchema = openEnums.inbound
16
16
  /** @internal */
17
17
  export const ChatMessageContentItemImageDetail$outboundSchema = openEnums.outboundSchema(ChatMessageContentItemImageDetail);
18
18
  /** @internal */
19
- export const ImageUrl$inboundSchema = z.object({
19
+ export const ChatMessageContentItemImageImageUrl$inboundSchema = z.object({
20
20
  url: z.string(),
21
21
  detail: ChatMessageContentItemImageDetail$inboundSchema.optional(),
22
22
  });
23
23
  /** @internal */
24
- export const ImageUrl$outboundSchema = z
25
- .object({
24
+ export const ChatMessageContentItemImageImageUrl$outboundSchema = z.object({
26
25
  url: z.string(),
27
26
  detail: ChatMessageContentItemImageDetail$outboundSchema.optional(),
28
27
  });
29
- export function imageUrlToJSON(imageUrl) {
30
- return JSON.stringify(ImageUrl$outboundSchema.parse(imageUrl));
28
+ export function chatMessageContentItemImageImageUrlToJSON(chatMessageContentItemImageImageUrl) {
29
+ return JSON.stringify(ChatMessageContentItemImageImageUrl$outboundSchema.parse(chatMessageContentItemImageImageUrl));
31
30
  }
32
- export function imageUrlFromJSON(jsonString) {
33
- return safeParse(jsonString, (x) => ImageUrl$inboundSchema.parse(JSON.parse(x)), `Failed to parse 'ImageUrl' from JSON`);
31
+ export function chatMessageContentItemImageImageUrlFromJSON(jsonString) {
32
+ return safeParse(jsonString, (x) => ChatMessageContentItemImageImageUrl$inboundSchema.parse(JSON.parse(x)), `Failed to parse 'ChatMessageContentItemImageImageUrl' from JSON`);
34
33
  }
35
34
  /** @internal */
36
35
  export const ChatMessageContentItemImage$inboundSchema = z.object({
37
36
  type: z.literal("image_url"),
38
- image_url: z.lazy(() => ImageUrl$inboundSchema),
37
+ image_url: z.lazy(() => ChatMessageContentItemImageImageUrl$inboundSchema),
39
38
  }).transform((v) => {
40
39
  return remap$(v, {
41
40
  "image_url": "imageUrl",
@@ -44,7 +43,7 @@ export const ChatMessageContentItemImage$inboundSchema = z.object({
44
43
  /** @internal */
45
44
  export const ChatMessageContentItemImage$outboundSchema = z.object({
46
45
  type: z.literal("image_url"),
47
- imageUrl: z.lazy(() => ImageUrl$outboundSchema),
46
+ imageUrl: z.lazy(() => ChatMessageContentItemImageImageUrl$outboundSchema),
48
47
  }).transform((v) => {
49
48
  return remap$(v, {
50
49
  imageUrl: "image_url",
@@ -4,12 +4,10 @@ import { AssistantMessage } from "./assistantmessage.js";
4
4
  import { ChatCompletionFinishReason } from "./chatcompletionfinishreason.js";
5
5
  import { ChatMessageTokenLogprobs } from "./chatmessagetokenlogprobs.js";
6
6
  import { SDKValidationError } from "./errors/sdkvalidationerror.js";
7
- import { Schema3 } from "./schema3.js";
8
7
  export type ChatResponseChoice = {
9
8
  finishReason: ChatCompletionFinishReason | null;
10
9
  index: number;
11
10
  message: AssistantMessage;
12
- reasoningDetails?: Array<Schema3> | undefined;
13
11
  logprobs?: ChatMessageTokenLogprobs | null | undefined;
14
12
  };
15
13
  /** @internal */
@@ -8,18 +8,15 @@ import { safeParse } from "../lib/schemas.js";
8
8
  import { AssistantMessage$inboundSchema, } from "./assistantmessage.js";
9
9
  import { ChatCompletionFinishReason$inboundSchema, } from "./chatcompletionfinishreason.js";
10
10
  import { ChatMessageTokenLogprobs$inboundSchema, } from "./chatmessagetokenlogprobs.js";
11
- import { Schema3$inboundSchema } from "./schema3.js";
12
11
  /** @internal */
13
12
  export const ChatResponseChoice$inboundSchema = z.object({
14
13
  finish_reason: z.nullable(ChatCompletionFinishReason$inboundSchema),
15
14
  index: z.number(),
16
15
  message: AssistantMessage$inboundSchema,
17
- reasoning_details: z.array(Schema3$inboundSchema).optional(),
18
16
  logprobs: z.nullable(ChatMessageTokenLogprobs$inboundSchema).optional(),
19
17
  }).transform((v) => {
20
18
  return remap$(v, {
21
19
  "finish_reason": "finishReason",
22
- "reasoning_details": "reasoningDetails",
23
20
  });
24
21
  });
25
22
  export function chatResponseChoiceFromJSON(jsonString) {
@@ -3,7 +3,7 @@ import { ClosedEnum } from "../types/enums.js";
3
3
  import { Result as SafeParseResult } from "../types/fp.js";
4
4
  import { ChatStreamingMessageToolCall } from "./chatstreamingmessagetoolcall.js";
5
5
  import { SDKValidationError } from "./errors/sdkvalidationerror.js";
6
- import { Schema3 } from "./schema3.js";
6
+ import { Schema2 } from "./schema2.js";
7
7
  export declare const ChatStreamingMessageChunkRole: {
8
8
  readonly Assistant: "assistant";
9
9
  };
@@ -14,7 +14,7 @@ export type ChatStreamingMessageChunk = {
14
14
  reasoning?: string | null | undefined;
15
15
  refusal?: string | null | undefined;
16
16
  toolCalls?: Array<ChatStreamingMessageToolCall> | undefined;
17
- reasoningDetails?: Array<Schema3> | undefined;
17
+ reasoningDetails?: Array<Schema2> | undefined;
18
18
  };
19
19
  /** @internal */
20
20
  export declare const ChatStreamingMessageChunkRole$inboundSchema: z.ZodEnum<typeof ChatStreamingMessageChunkRole>;
@@ -6,7 +6,7 @@ import * as z from "zod/v4";
6
6
  import { remap as remap$ } from "../lib/primitives.js";
7
7
  import { safeParse } from "../lib/schemas.js";
8
8
  import { ChatStreamingMessageToolCall$inboundSchema, } from "./chatstreamingmessagetoolcall.js";
9
- import { Schema3$inboundSchema } from "./schema3.js";
9
+ import { Schema2$inboundSchema } from "./schema2.js";
10
10
  export const ChatStreamingMessageChunkRole = {
11
11
  Assistant: "assistant",
12
12
  };
@@ -19,7 +19,7 @@ export const ChatStreamingMessageChunk$inboundSchema = z.object({
19
19
  reasoning: z.nullable(z.string()).optional(),
20
20
  refusal: z.nullable(z.string()).optional(),
21
21
  tool_calls: z.array(ChatStreamingMessageToolCall$inboundSchema).optional(),
22
- reasoning_details: z.array(Schema3$inboundSchema).optional(),
22
+ reasoning_details: z.array(Schema2$inboundSchema).optional(),
23
23
  }).transform((v) => {
24
24
  return remap$(v, {
25
25
  "tool_calls": "toolCalls",