@simple-ai-lab/sdk 0.4.0 → 0.6.0

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 (74) hide show
  1. package/README.md +54 -1
  2. package/dist/actions.cjs +438 -0
  3. package/dist/actions.d.cts +336 -0
  4. package/dist/actions.d.ts +336 -0
  5. package/dist/actions.js +429 -0
  6. package/dist/agents.cjs +1054 -0
  7. package/dist/agents.d.cts +1016 -0
  8. package/dist/agents.d.ts +1016 -0
  9. package/dist/agents.js +1044 -0
  10. package/dist/built-in-actions.cjs +356 -0
  11. package/dist/built-in-actions.d.cts +41 -0
  12. package/dist/built-in-actions.d.ts +41 -0
  13. package/dist/built-in-actions.js +353 -0
  14. package/dist/client.cjs +29 -0
  15. package/dist/client.d.cts +15 -0
  16. package/dist/client.d.ts +15 -0
  17. package/dist/client.js +25 -0
  18. package/dist/code-action/defaults.cjs +11 -0
  19. package/dist/code-action/defaults.d.cts +7 -0
  20. package/dist/code-action/defaults.d.ts +7 -0
  21. package/dist/code-action/defaults.js +8 -0
  22. package/dist/code-action/define-action.cjs +74 -0
  23. package/dist/code-action/define-action.d.cts +94 -0
  24. package/dist/code-action/define-action.d.ts +94 -0
  25. package/dist/code-action/define-action.js +69 -0
  26. package/dist/code-action/index.cjs +11 -0
  27. package/dist/code-action/index.d.cts +4 -0
  28. package/dist/code-action/index.d.ts +4 -0
  29. package/dist/code-action/index.js +3 -0
  30. package/dist/code-action/types.cjs +13 -0
  31. package/dist/code-action/types.d.cts +13 -0
  32. package/dist/code-action/types.d.ts +13 -0
  33. package/dist/code-action/types.js +10 -0
  34. package/dist/code-action/workflow.cjs +29 -0
  35. package/dist/code-action/workflow.d.cts +53 -0
  36. package/dist/code-action/workflow.d.ts +53 -0
  37. package/dist/code-action/workflow.js +26 -0
  38. package/dist/data.cjs +98 -0
  39. package/dist/data.d.cts +44 -0
  40. package/dist/data.d.ts +44 -0
  41. package/dist/data.js +94 -0
  42. package/dist/http.cjs +65 -0
  43. package/dist/http.d.cts +14 -0
  44. package/dist/http.d.ts +14 -0
  45. package/dist/http.js +62 -0
  46. package/dist/index.cjs +68 -1597
  47. package/dist/index.d.cts +12 -780
  48. package/dist/index.d.ts +12 -780
  49. package/dist/index.js +10 -1311
  50. package/dist/projects.cjs +234 -0
  51. package/dist/projects.d.cts +24 -0
  52. package/dist/projects.d.ts +24 -0
  53. package/dist/projects.js +228 -0
  54. package/dist/schemas.cjs +50 -0
  55. package/dist/schemas.d.cts +81 -0
  56. package/dist/schemas.d.ts +81 -0
  57. package/dist/schemas.js +47 -0
  58. package/dist/shared/errors.cjs +31 -0
  59. package/dist/shared/errors.d.cts +22 -0
  60. package/dist/shared/errors.d.ts +22 -0
  61. package/dist/shared/errors.js +26 -0
  62. package/package.json +27 -31
  63. package/dist/chunk-V4E5PSKB.js +0 -267
  64. package/dist/chunk-V4E5PSKB.js.map +0 -1
  65. package/dist/code-action-CDt77m7I.d.cts +0 -191
  66. package/dist/code-action-CDt77m7I.d.ts +0 -191
  67. package/dist/code-action.cjs +0 -282
  68. package/dist/code-action.cjs.map +0 -1
  69. package/dist/code-action.d.cts +0 -2
  70. package/dist/code-action.d.ts +0 -2
  71. package/dist/code-action.js +0 -9
  72. package/dist/code-action.js.map +0 -1
  73. package/dist/index.cjs.map +0 -1
  74. package/dist/index.js.map +0 -1
@@ -0,0 +1,429 @@
1
+ import { z } from 'zod';
2
+ import { BUILT_IN_ACTION_CONTRACTS, builtInOperationSchema } from "./built-in-actions.js";
3
+ export function resolveActionHttpHeaders(headers) {
4
+ if (headers === undefined) {
5
+ return [];
6
+ }
7
+ return Array.isArray(headers)
8
+ ? headers
9
+ : Object.entries(headers).map(([name, valueTemplate]) => ({ name, valueTemplate }));
10
+ }
11
+ export function resolveActionIoSchema(schema) {
12
+ return schema instanceof z.ZodType ? actionsIoSchemaFromZod(schema) : schema;
13
+ }
14
+ function isRecord(value) {
15
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
16
+ }
17
+ function nullableJsonSchema(value) {
18
+ const type = value.type;
19
+ if (Array.isArray(type)) {
20
+ const nonNullTypes = type.filter((item) => item !== 'null');
21
+ if (nonNullTypes.length === 1 && typeof nonNullTypes[0] === 'string') {
22
+ return { schema: { ...value, type: nonNullTypes[0] }, nullable: type.includes('null') };
23
+ }
24
+ }
25
+ const anyOf = value.anyOf;
26
+ if (Array.isArray(anyOf)) {
27
+ const schemas = anyOf.filter(isRecord);
28
+ const nonNullSchemas = schemas.filter((schema) => schema.type !== 'null');
29
+ const containsNull = schemas.some((schema) => schema.type === 'null');
30
+ if (containsNull && nonNullSchemas.length === 1) {
31
+ const nonNullSchema = nonNullSchemas[0] ?? {};
32
+ return {
33
+ schema: {
34
+ ...nonNullSchema,
35
+ ...(typeof value.description === 'string' ? { description: value.description } : {}),
36
+ },
37
+ nullable: true,
38
+ };
39
+ }
40
+ }
41
+ return { schema: value, nullable: false };
42
+ }
43
+ function schemaDescription(schema) {
44
+ return typeof schema.description === 'string' ? schema.description : '';
45
+ }
46
+ function convertJsonSchemaNode(value, path) {
47
+ if (!isRecord(value)) {
48
+ throw new Error(`${path} is not a representable Zod schema`);
49
+ }
50
+ const { schema, nullable } = nullableJsonSchema(value);
51
+ if (schema.enum !== undefined || schema.const !== undefined) {
52
+ throw new Error(`${path} uses enum/const, which Actions I/O schemas do not support`);
53
+ }
54
+ switch (schema.type) {
55
+ case 'string':
56
+ case 'number':
57
+ case 'boolean':
58
+ return {
59
+ type: schema.type,
60
+ description: schemaDescription(schema),
61
+ nullable,
62
+ };
63
+ case 'object': {
64
+ const rawProperties = isRecord(schema.properties) ? schema.properties : {};
65
+ const properties = {};
66
+ for (const [name, child] of Object.entries(rawProperties)) {
67
+ if (!/^[A-Za-z_]\w*$/.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name)) {
68
+ throw new Error(`${path}.${name} is not a valid Actions I/O property name`);
69
+ }
70
+ properties[name] = convertJsonSchemaNode(child, `${path}.${name}`);
71
+ }
72
+ const required = Array.isArray(schema.required)
73
+ ? schema.required.filter((name) => typeof name === 'string')
74
+ : [];
75
+ const additionalProperties = schema.additionalProperties === true;
76
+ return {
77
+ type: 'object',
78
+ description: schemaDescription(schema),
79
+ nullable,
80
+ properties,
81
+ required,
82
+ additionalProperties,
83
+ };
84
+ }
85
+ case 'array':
86
+ return {
87
+ type: 'array',
88
+ description: schemaDescription(schema),
89
+ nullable,
90
+ ...(schema.items === undefined ? {} : { items: convertJsonSchemaNode(schema.items, `${path}[]`) }),
91
+ };
92
+ case 'integer':
93
+ return {
94
+ type: 'number',
95
+ description: schemaDescription(schema),
96
+ nullable,
97
+ };
98
+ default:
99
+ throw new Error(`${path} uses unsupported Zod/JSON Schema type "${String(schema.type)}"`);
100
+ }
101
+ }
102
+ export function actionsIoSchemaFromZod(schema) {
103
+ const converted = convertJsonSchemaNode(z.toJSONSchema(schema), 'schema');
104
+ if (converted.type !== 'object') {
105
+ throw new Error('Action input and output schemas must be Zod objects');
106
+ }
107
+ return {
108
+ type: 'object',
109
+ description: converted.description,
110
+ properties: converted.properties,
111
+ required: converted.required,
112
+ additionalProperties: converted.additionalProperties,
113
+ };
114
+ }
115
+ function pointerForName(name) {
116
+ const escaped = name.replace(/~/g, '~0').replace(/\//g, '~1');
117
+ return `/${escaped}`;
118
+ }
119
+ function normalizeOutputMappings({ mappings, outputSchema, }) {
120
+ const normalized = Object.fromEntries(Object.entries(mappings).map(([name, template]) => [name.startsWith('/') ? name : pointerForName(name), template]));
121
+ for (const name of Object.keys(outputSchema.properties)) {
122
+ const pointer = pointerForName(name);
123
+ if (normalized[pointer] === undefined) {
124
+ throw new Error(`Action output "${name}" needs an output mapping`);
125
+ }
126
+ }
127
+ for (const pointer of Object.keys(normalized)) {
128
+ const firstToken = pointer.slice(1).split('/')[0]?.replace(/~1/g, '/').replace(/~0/g, '~');
129
+ if (firstToken === undefined || outputSchema.properties[firstToken] === undefined) {
130
+ throw new Error(`Action output mapping "${pointer}" does not reference a declared output`);
131
+ }
132
+ }
133
+ return normalized;
134
+ }
135
+ function compileContracts({ input, output }) {
136
+ return {
137
+ inputSchema: resolveActionIoSchema(input),
138
+ outputSchema: resolveActionIoSchema(output),
139
+ };
140
+ }
141
+ /**
142
+ * Code Action source shared by SDK compilation, CLI comparisons, and file hashes.
143
+ * Surrounding whitespace is trimmed to match Agent v2. Line endings use LF for
144
+ * consistent comparisons across operating systems. Publishing writes this form.
145
+ */
146
+ export function canonicalActionSource(source) {
147
+ return source.replace(/\r\n?/g, '\n').trim();
148
+ }
149
+ /**
150
+ * Resolves a handler's TypeScript, whether it is written inline or kept in the
151
+ * file a `sourceFile(...)` reference names, in its canonical form.
152
+ */
153
+ function resolveActionSource({ source, options, }) {
154
+ if (typeof source === 'string') {
155
+ return canonicalActionSource(source);
156
+ }
157
+ if (options.readSourceFile === undefined) {
158
+ throw new Error(`Action source file "${source.path}" requires a readSourceFile compiler option`);
159
+ }
160
+ return canonicalActionSource(options.readSourceFile(source.path));
161
+ }
162
+ function compileHttpAction(config) {
163
+ const contract = compileContracts(config);
164
+ return {
165
+ kind: 'inline',
166
+ key: config.key,
167
+ contract,
168
+ compile: () => ({
169
+ actionType: 'http',
170
+ name: config.name,
171
+ description: config.description,
172
+ ...contract,
173
+ outputMappings: normalizeOutputMappings({
174
+ mappings: config.outputMappings,
175
+ outputSchema: contract.outputSchema,
176
+ }),
177
+ operation: {
178
+ type: 'request',
179
+ method: config.request.method,
180
+ urlTemplate: config.request.url,
181
+ headers: resolveActionHttpHeaders(config.request.headers),
182
+ bodyTemplate: config.request.body ?? null,
183
+ },
184
+ }),
185
+ };
186
+ }
187
+ function compileCodeAction(config) {
188
+ const contract = compileContracts(config);
189
+ return {
190
+ kind: 'inline',
191
+ key: config.key,
192
+ contract,
193
+ compile: (options) => ({
194
+ actionType: 'code',
195
+ name: config.name,
196
+ description: config.description,
197
+ ...contract,
198
+ outputMappings: normalizeOutputMappings({
199
+ mappings: config.outputMappings,
200
+ outputSchema: contract.outputSchema,
201
+ }),
202
+ operation: {
203
+ type: 'execute',
204
+ language: 'typescript',
205
+ source: resolveActionSource({ source: config.source, options }),
206
+ compiledJs: null,
207
+ runtime: 'cloudflare-worker',
208
+ timeoutMs: config.timeoutMs ?? 30_000,
209
+ },
210
+ }),
211
+ };
212
+ }
213
+ const CUSTOM_DATA_AGENT_SEARCH_INPUT_SCHEMA = {
214
+ type: 'object',
215
+ description: 'System-managed Custom Data search inputs.',
216
+ properties: {},
217
+ required: [],
218
+ additionalProperties: true,
219
+ };
220
+ function compileCustomDataTransform({ transform, options, }) {
221
+ if (transform == null) {
222
+ return null;
223
+ }
224
+ return {
225
+ language: 'typescript',
226
+ source: resolveActionSource({ source: transform.source, options }),
227
+ compiledJs: null,
228
+ runtime: 'cloudflare-worker',
229
+ timeoutMs: transform.timeoutMs ?? 30_000,
230
+ };
231
+ }
232
+ function compileCustomDataAction(config) {
233
+ const outputSchema = resolveActionIoSchema(config.output);
234
+ let inputSchema;
235
+ switch (config.operation.type) {
236
+ case 'agent_search':
237
+ inputSchema = CUSTOM_DATA_AGENT_SEARCH_INPUT_SCHEMA;
238
+ break;
239
+ case 'query':
240
+ case 'search':
241
+ if (config.input === undefined) {
242
+ throw new Error(`Custom Data ${config.operation.type} Actions require an input schema`);
243
+ }
244
+ inputSchema = resolveActionIoSchema(config.input);
245
+ break;
246
+ }
247
+ const contract = { inputSchema, outputSchema };
248
+ return {
249
+ kind: 'inline',
250
+ key: config.key,
251
+ contract,
252
+ compile: (options) => {
253
+ const transform = compileCustomDataTransform({ transform: config.transform, options });
254
+ const common = {
255
+ actionType: 'custom_data',
256
+ name: config.name,
257
+ description: config.description,
258
+ ...contract,
259
+ outputMappings: normalizeOutputMappings({
260
+ mappings: config.outputMappings,
261
+ outputSchema: contract.outputSchema,
262
+ }),
263
+ };
264
+ switch (config.operation.type) {
265
+ case 'agent_search':
266
+ return {
267
+ ...common,
268
+ operation: {
269
+ ...config.operation,
270
+ aiFacetingEnabled: config.operation.aiFacetingEnabled ?? false,
271
+ transform,
272
+ },
273
+ };
274
+ case 'query':
275
+ return { ...common, operation: { ...config.operation, transform } };
276
+ case 'search': {
277
+ const { body, ...operation } = config.operation;
278
+ return { ...common, operation: { ...operation, bodyTemplate: body, transform } };
279
+ }
280
+ }
281
+ },
282
+ };
283
+ }
284
+ function compileCustomDataQueryAction(config) {
285
+ const { sql, ...common } = config;
286
+ return compileCustomDataAction({ ...common, operation: { type: 'query', sql } });
287
+ }
288
+ function compileCustomDataSearchAction(config) {
289
+ const { table, body, ...common } = config;
290
+ return compileCustomDataAction({ ...common, operation: { type: 'search', table, body } });
291
+ }
292
+ function compileKnowledgeBaseSearchAction(config) {
293
+ const contract = compileContracts(config);
294
+ return {
295
+ kind: 'inline',
296
+ key: config.key,
297
+ contract,
298
+ compile: () => ({
299
+ actionType: 'knowledge_base',
300
+ name: config.name,
301
+ description: config.description,
302
+ ...contract,
303
+ outputMappings: normalizeOutputMappings({
304
+ mappings: config.outputMappings,
305
+ outputSchema: contract.outputSchema,
306
+ }),
307
+ operation: {
308
+ type: 'search',
309
+ knowledgeBaseIds: config.knowledgeBaseIds,
310
+ bodyTemplate: config.body,
311
+ },
312
+ }),
313
+ };
314
+ }
315
+ /** Compiles built-in schema parameters through the same path as other Actions. */
316
+ function compileBuiltInAction({ config, operation, }) {
317
+ // Validate against the Agent v2 operation schema without applying its transforms:
318
+ // historical versions must retain their stored strings when pulled and diffed.
319
+ builtInOperationSchema.parse(operation);
320
+ const { key, name, description } = config;
321
+ if ('contract' in config) {
322
+ throw new Error(`Built-in Action "${key}" no longer accepts contract; use input, output, and outputMappings`);
323
+ }
324
+ // JavaScript callers and CLI compilation do not run TypeScript checks.
325
+ // A partial stored contract must never be mixed with Agent v2 defaults.
326
+ const hasSchemas = config.input !== undefined || config.output !== undefined || config.outputMappings !== undefined;
327
+ if (hasSchemas &&
328
+ (config.input === undefined || config.output === undefined || config.outputMappings === undefined)) {
329
+ throw new Error(`Built-in Action "${key}" requires input, output, and outputMappings together`);
330
+ }
331
+ const fixed = BUILT_IN_ACTION_CONTRACTS[operation.type];
332
+ const schemas = config.input === undefined
333
+ ? { input: fixed.inputSchema, output: fixed.outputSchema, outputMappings: fixed.outputMappings }
334
+ : config;
335
+ const contract = compileContracts(schemas);
336
+ return {
337
+ kind: 'inline',
338
+ key,
339
+ contract,
340
+ compile: () => ({
341
+ actionType: 'built_in',
342
+ name,
343
+ description,
344
+ ...contract,
345
+ outputMappings: normalizeOutputMappings({
346
+ mappings: schemas.outputMappings,
347
+ outputSchema: contract.outputSchema,
348
+ }),
349
+ operation,
350
+ }),
351
+ };
352
+ }
353
+ export const action = {
354
+ http(config) {
355
+ return compileHttpAction(config);
356
+ },
357
+ code(config) {
358
+ return compileCodeAction(config);
359
+ },
360
+ customData: compileCustomDataAction,
361
+ customDataAgentSearch(config) {
362
+ const { table, aiFacetingEnabled = false, ...common } = config;
363
+ return compileCustomDataAction({
364
+ ...common,
365
+ operation: { type: 'agent_search', table, aiFacetingEnabled },
366
+ });
367
+ },
368
+ customDataQuery(config) {
369
+ return compileCustomDataQueryAction(config);
370
+ },
371
+ customDataSearch(config) {
372
+ return compileCustomDataSearchAction(config);
373
+ },
374
+ knowledgeBaseSearch(config) {
375
+ return compileKnowledgeBaseSearchAction(config);
376
+ },
377
+ /** Sends an email through a verified sending domain of the organization. */
378
+ sendEmail(config) {
379
+ const { sendingDomainUuid, fromLocalPart, fromDisplayName = null } = config;
380
+ return compileBuiltInAction({
381
+ config,
382
+ operation: { type: 'send_email', sendingDomainUuid, fromLocalPart, fromDisplayName },
383
+ });
384
+ },
385
+ /** Sends a text message from one of the organization's phone numbers. */
386
+ sendTextMessage(config) {
387
+ const { senderPhoneNumberUuid } = config;
388
+ return compileBuiltInAction({
389
+ config,
390
+ operation: { type: 'send_text_message', senderPhoneNumberUuid },
391
+ });
392
+ },
393
+ /** Validates and standardizes a postal address. */
394
+ validateAddress(config) {
395
+ return compileBuiltInAction({
396
+ config,
397
+ operation: { type: 'validate_address' },
398
+ });
399
+ },
400
+ ref(config) {
401
+ return {
402
+ kind: 'reference',
403
+ key: config.key,
404
+ versionUuid: config.versionUuid,
405
+ contract: config.contract ?? null,
406
+ };
407
+ },
408
+ callable(config) {
409
+ const { backgroundMessage = null, ...rest } = config;
410
+ return { kind: 'callable', ...rest, backgroundMessage };
411
+ },
412
+ run(config) {
413
+ return { kind: 'run', ...config };
414
+ },
415
+ fromAgent(description) {
416
+ return { source: 'agent', description };
417
+ },
418
+ from(value, description) {
419
+ // The description is kept separately on the wire, so a prefilled input can
420
+ // still carry the text the agent is shown.
421
+ return { source: 'template', value, ...(description === undefined ? {} : { description }) };
422
+ },
423
+ };
424
+ export function compileAction(definition, options = {}) {
425
+ return definition.compile(options);
426
+ }
427
+ export function sourceFile(path) {
428
+ return { kind: 'source-file', path };
429
+ }