-
Notifications
You must be signed in to change notification settings - Fork 3.8k
Expand file tree
/
Copy pathtypes.ts
More file actions
372 lines (339 loc) · 10.8 KB
/
Copy pathtypes.ts
File metadata and controls
372 lines (339 loc) · 10.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
import type { MothershipResource } from '@/lib/copilot/resources/types'
import type { HostedKeyRateLimitConfig } from '@/lib/core/rate-limiter'
import type { OAuthService } from '@/lib/oauth'
export type BYOKProviderId =
| 'openai'
| 'anthropic'
| 'google'
| 'mistral'
| 'zai'
| 'kimi'
| 'xai'
| 'fireworks'
| 'together'
| 'baseten'
| 'ollama-cloud'
| 'falai'
| 'firecrawl'
| 'exa'
| 'context_dev'
| 'serper'
| 'jina'
| 'perplexity'
| 'google_cloud'
| 'linkup'
| 'brandfetch'
| 'parallel_ai'
| 'cohere'
| 'hunter'
| 'peopledatalabs'
| 'findymail'
| 'prospeo'
| 'wiza'
| 'zerobounce'
| 'neverbounce'
| 'millionverifier'
| 'datagma'
| 'dropcontact'
| 'leadmagic'
| 'icypeas'
| 'enrow'
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD'
/**
* Minimal execution context injected into tool params at runtime.
* This is a subset of the full ExecutionContext from executor/types.ts.
*/
export type WorkflowToolExecutionContext = {
workspaceId?: string
workflowId?: string
executionId?: string
userId?: string
}
export type OutputType =
| 'string'
| 'number'
| 'boolean'
| 'json'
| 'file'
| 'file[]'
| 'array'
| 'object'
export interface OutputProperty {
type: OutputType
description?: string
optional?: boolean
nullable?: boolean
properties?: Record<string, OutputProperty>
items?: {
type: OutputType
description?: string
properties?: Record<string, OutputProperty>
}
}
export interface ToolOutputProperty extends OutputProperty {
fileConfig?: {
mimeType?: string
extension?: string
}
}
export type ParameterVisibility =
| 'user-or-llm' // User can provide OR LLM must generate
| 'user-only' // Only user can provide (required/optional determined by required field)
| 'llm-only' // Only LLM provides (computed values)
| 'hidden' // Not shown to user or LLM
export interface ToolResponse {
success: boolean // Whether the tool execution was successful
output: Record<string, any> // The structured output from the tool
error?: string // Error message if success is false
resources?: MothershipResource[] // Resources to auto-open/show in UI
largeValueKeys?: string[]
fileKeys?: string[]
timing?: {
startTime: string // ISO timestamp when the tool execution started
endTime: string // ISO timestamp when the tool execution ended
duration: number // Duration in milliseconds
}
}
export interface OAuthConfig {
required: boolean // Whether this tool requires OAuth authentication
provider: OAuthService // The service that needs to be authorized
requiredScopes?: string[] // Specific scopes this tool needs (for granular scope validation)
}
export interface ToolRetryConfig {
enabled: boolean
maxRetries?: number
initialDelayMs?: number
maxDelayMs?: number
retryIdempotentOnly?: boolean
}
/** JSON Schema subset supported for array item definitions in tool parameters. */
export interface ToolParameterItemSchema {
readonly type?: string
readonly description?: string
readonly const?: string | number | boolean
readonly minimum?: number
readonly maximum?: number
readonly minLength?: number
readonly maxLength?: number
readonly pattern?: string
readonly additionalProperties?: boolean
readonly required?: readonly string[]
readonly properties?: Readonly<Record<string, ToolParameterItemSchema>>
readonly anyOf?: readonly ToolParameterItemSchema[]
}
export interface ToolConfig<P = any, R = any> {
// Basic tool identification
id: string
name: string
description: string
version: string
// Parameter schema - what this tool accepts
params: Record<
string,
{
type: string
required?: boolean
visibility?: ParameterVisibility
default?: any
description?: string
items?: ToolParameterItemSchema
}
>
// Output schema - what this tool produces
outputs?: Record<string, ToolOutputProperty>
// OAuth configuration for this tool (if it requires authentication)
oauth?: OAuthConfig
// Error extractor to use for this tool's error responses
// If specified, only this extractor will be used (deterministic)
// If not specified, will try all extractors in order (fallback)
errorExtractor?: string
// Request configuration
request: {
url: string | ((params: P) => string)
method: HttpMethod | ((params: P) => HttpMethod)
headers: (params: P) => Record<string, string>
body?: (params: P) => Record<string, any> | string | FormData | undefined
retry?: ToolRetryConfig
}
// Post-processing (optional) - allows additional processing after the initial request
postProcess?: (
result: R extends ToolResponse ? R : ToolResponse,
params: P,
executeTool: (toolId: string, params: Record<string, any>) => Promise<ToolResponse>
) => Promise<R extends ToolResponse ? R : ToolResponse>
// Response handling
transformResponse?: (response: Response, params?: P) => Promise<R>
/**
* Direct execution function for tools that don't need HTTP requests.
* If provided, this will be called instead of making an HTTP request.
* Receives the workflow execution's abort signal (when one is active) so
* long-running direct executions can propagate cancellation.
*/
directExecution?: (params: P, signal?: AbortSignal) => Promise<ToolResponse>
/**
* Optional dynamic schema enrichment for specific params.
* Maps param IDs to their enrichment configuration.
*/
schemaEnrichment?: Record<string, SchemaEnrichmentConfig>
/**
* Optional tool-level enrichment that modifies description and all parameters.
* Use when multiple params depend on a single runtime value.
*/
toolEnrichment?: ToolEnrichmentConfig
/**
* Hosted API key configuration for this tool.
* When configured, the tool can use Sim's hosted API keys if user doesn't provide their own.
* Usage is billed according to the pricing config.
*/
hosting?: ToolHostingConfig<P>
}
export interface TableRow {
id: string
cells: {
Key: string
Value: any
}
}
export interface OAuthTokenPayload {
credentialId?: string
credentialAccountUserId?: string
providerId?: string
workflowId?: string
impersonateEmail?: string
scopes?: string[]
}
/**
* File data that tools can return for file-typed outputs
*/
export interface ToolFileData {
name: string
mimeType: string
data?: Buffer | string // Buffer or base64 string
url?: string // URL to download file from
size?: number
}
/**
* Configuration for dynamically enriching a parameter's schema at runtime.
* Used when a parameter's schema depends on runtime values (e.g., KB tags, workflow inputs).
*/
interface SchemaEnrichmentConfig {
/** The param ID that this enrichment depends on (e.g., 'knowledgeBaseId', 'workflowId') */
dependsOn: string
/** Function to fetch and build dynamic schema based on the dependency value */
enrichSchema: (dependencyValue: string) => Promise<{
type: string
properties?: Record<string, { type: string; description?: string }>
description?: string
required?: string[]
} | null>
}
/**
* Configuration for enriching an entire tool (description + all parameters) at runtime.
* Used when multiple parameters and the description depend on a single runtime value (e.g., tableId).
*/
interface ToolEnrichmentConfig {
/** The param ID that this enrichment depends on (e.g., 'tableId') */
dependsOn: string
/** Function to enrich the tool's description and parameter schema */
enrichTool: (
dependencyValue: string,
originalSchema: {
type: 'object'
properties: Record<string, unknown>
required: string[]
},
originalDescription: string
) => Promise<{
description: string
parameters: {
type: 'object'
properties: Record<string, unknown>
required: string[]
}
} | null>
}
/**
* Pricing models for hosted API key usage
*/
/** Flat fee per API call (e.g., Serper search) */
interface PerRequestPricing {
type: 'per_request'
/** Cost per request in dollars */
cost: number
}
/** Result from custom pricing calculation */
interface CustomPricingResult {
/** Cost in dollars */
cost: number
/** Optional metadata about the cost calculation (e.g., breakdown from API) */
metadata?: Record<string, unknown>
}
/** Custom pricing calculated from params and response (e.g., Exa with different modes/result counts) */
interface CustomPricing<P = Record<string, unknown>> {
type: 'custom'
/** Calculate cost based on request params and response output. Fields starting with _ are internal. */
getCost: (params: P, output: Record<string, unknown>) => number | CustomPricingResult
}
/** Union of all pricing models */
export type ToolHostingPricing<P = Record<string, unknown>> = PerRequestPricing | CustomPricing<P>
export type ToolHostingCondition =
| {
field: string
operator: 'equals'
value: string | number | boolean | null
}
| {
field: string
operator: 'one_of'
values: Array<string | number | boolean | null>
}
export type ToolHostingPredicate<P> = ((params: P) => boolean) & {
/** Serializable equivalent of this predicate for VFS consumers. */
condition?: ToolHostingCondition
}
/**
* Configuration for hosted API key support.
* When configured, the tool can use Sim's hosted API keys if user doesn't provide their own.
*
* ### Hosted key env var convention
*
* Keys follow a numbered naming convention driven by a count env var:
*
* 1. Set `{envKeyPrefix}_COUNT` to the number of keys available.
* 2. Provide each key as `{envKeyPrefix}_1`, `{envKeyPrefix}_2`, ..., `{envKeyPrefix}_N`.
*
* **Example** — for `envKeyPrefix: 'EXA_API_KEY'` with 5 keys:
* ```
* EXA_API_KEY_COUNT=5
* EXA_API_KEY_1=sk-...
* EXA_API_KEY_2=sk-...
* EXA_API_KEY_3=sk-...
* EXA_API_KEY_4=sk-...
* EXA_API_KEY_5=sk-...
* ```
*
* For a single-key deployment, `{envKeyPrefix}` is also supported when no
* `{envKeyPrefix}_COUNT` is configured.
*
* Adding more keys only requires updating the count and adding the new env var —
* no code changes needed.
*/
export interface ToolHostingConfig<P = Record<string, unknown>> {
/** Optional predicate for tools where hosted keys only apply to some parameter combinations. */
enabled?: ToolHostingPredicate<P>
/**
* Env var name prefix for hosted keys.
* At runtime, `{envKeyPrefix}_COUNT` is read to determine how many keys exist,
* then `{envKeyPrefix}_1` through `{envKeyPrefix}_N` are resolved. If no count
* is configured, a singular `{envKeyPrefix}` is used when present.
*/
envKeyPrefix: string
/** The parameter name that receives the API key */
apiKeyParam: string
/** BYOK provider ID for workspace key lookup */
byokProviderId?: BYOKProviderId
/** Pricing when using hosted key */
pricing: ToolHostingPricing<P>
/** Hosted key rate limit configuration (required for hosted key distribution) */
rateLimit: HostedKeyRateLimitConfig
}