@mindstudio-ai/agent 0.1.176 → 0.1.178

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 (50) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/analytics/index.d.ts +384 -0
  3. package/dist/auth/index.d.ts +113 -0
  4. package/dist/browser/index.d.ts +332 -0
  5. package/dist/cli.js +29 -29
  6. package/dist/client.d.ts +767 -0
  7. package/dist/config.d.ts +13 -0
  8. package/dist/context.d.ts +125 -0
  9. package/dist/datasources/index.d.ts +52 -0
  10. package/dist/datasources/source.d.ts +1074 -0
  11. package/dist/db/aggregate.d.ts +101 -0
  12. package/dist/db/index.d.ts +280 -0
  13. package/dist/db/mutation.d.ts +65 -0
  14. package/dist/db/predicate.d.ts +85 -0
  15. package/dist/db/query.d.ts +233 -0
  16. package/dist/db/raw.d.ts +36 -0
  17. package/dist/db/readBatching.d.ts +36 -0
  18. package/dist/db/scanHints.d.ts +8 -0
  19. package/dist/db/sql.d.ts +136 -0
  20. package/dist/db/table.d.ts +146 -0
  21. package/dist/db/time.d.ts +17 -0
  22. package/dist/db/types.d.ts +237 -0
  23. package/dist/db-ws.d.ts +35 -0
  24. package/dist/email/index.d.ts +396 -0
  25. package/dist/errors.d.ts +34 -0
  26. package/dist/events/index.d.ts +127 -0
  27. package/dist/files/index.d.ts +62 -0
  28. package/dist/files/store.d.ts +244 -0
  29. package/dist/generated/metadata.d.ts +8 -0
  30. package/dist/generated/snippets.d.ts +8 -0
  31. package/dist/generated/steps.d.ts +2745 -0
  32. package/dist/generated/types.d.ts +4234 -0
  33. package/dist/http.d.ts +22 -0
  34. package/dist/index.d.ts +59 -13329
  35. package/dist/index.js +17 -17
  36. package/dist/index.js.map +7 -1
  37. package/dist/jewel/index.d.ts +325 -0
  38. package/dist/mapper/index.d.ts +229 -0
  39. package/dist/rate-limit.d.ts +25 -0
  40. package/dist/reader/index.d.ts +170 -0
  41. package/dist/respond.d.ts +68 -0
  42. package/dist/task/index.d.ts +18 -0
  43. package/dist/task/local.d.ts +48 -0
  44. package/dist/task/schema.d.ts +120 -0
  45. package/dist/task/types.d.ts +203 -0
  46. package/dist/types.d.ts +591 -0
  47. package/dist/voice/index.d.ts +87 -0
  48. package/llms.txt +2 -2
  49. package/package.json +6 -12
  50. package/dist/postinstall.js +0 -12115
@@ -0,0 +1,591 @@
1
+ import type { Store } from './files/store.js';
2
+ /** Configuration options for creating a {@link MindStudioAgent}. */
3
+ export interface AgentOptions {
4
+ /**
5
+ * MindStudio API key. Used as a Bearer token for authentication.
6
+ *
7
+ * Note: `CALLBACK_TOKEN` (auto-set inside MindStudio) always takes
8
+ * priority over all other auth sources when present.
9
+ *
10
+ * If omitted (and no CALLBACK_TOKEN), the SDK checks (in order):
11
+ * 1. `MINDSTUDIO_API_KEY` environment variable
12
+ * 2. `~/.mindstudio/config.json` (set via `mindstudio login`)
13
+ */
14
+ apiKey?: string;
15
+ /**
16
+ * Base URL of the MindStudio API.
17
+ *
18
+ * If omitted, the SDK looks for `MINDSTUDIO_BASE_URL` in the environment,
19
+ * then `REMOTE_HOSTNAME` (available automatically inside MindStudio
20
+ * custom functions), then falls back to `https://v1.mindstudio-api.com`.
21
+ */
22
+ baseUrl?: string;
23
+ /**
24
+ * Maximum number of automatic retries on 429 (rate limited) responses.
25
+ * Each retry waits for the duration specified by the `Retry-After` header.
26
+ *
27
+ * @default 3
28
+ */
29
+ maxRetries?: number;
30
+ /**
31
+ * App ID for auth and database context. Required when using `auth` or
32
+ * `db` namespaces outside the MindStudio sandbox.
33
+ *
34
+ * If omitted, the SDK checks:
35
+ * 1. `MINDSTUDIO_APP_ID` environment variable
36
+ * 2. Sandbox globals (when running inside MindStudio)
37
+ * 3. Auto-detected from the first `executeStep` response header
38
+ *
39
+ * Not needed for plain step execution — only for `db` and `auth`.
40
+ */
41
+ appId?: string;
42
+ /**
43
+ * When true, the thread ID from the first API response is automatically
44
+ * reused for all subsequent calls (unless an explicit `threadId` is passed).
45
+ * Useful for local debugging to simulate custom function sandbox behavior.
46
+ *
47
+ * If omitted, the SDK checks `MINDSTUDIO_REUSE_THREAD_ID` in the environment.
48
+ * Any truthy value (`"true"`, `"1"`) enables reuse.
49
+ *
50
+ * @default false
51
+ */
52
+ reuseThreadId?: boolean;
53
+ }
54
+ /** A debug log event emitted during streaming step execution. */
55
+ export interface StepLogEvent {
56
+ /** Log message text. */
57
+ value: string;
58
+ /** Step display name, e.g. "Generate Image", "Scrape URL". */
59
+ tag: string;
60
+ /** Unix timestamp in milliseconds. */
61
+ ts: number;
62
+ /**
63
+ * A passing status the next one replaces (how far a render or a model's
64
+ * queue is), rather than a line worth keeping.
65
+ */
66
+ ephemeral?: boolean;
67
+ /** How far the action is, 0 to 1, on a passing status, when it knows. */
68
+ progress?: number;
69
+ }
70
+ /** Options for a single step execution call. */
71
+ export interface StepExecutionOptions {
72
+ /**
73
+ * App ID to execute within. When using an API key, omit this to let the
74
+ * API create a service account app automatically. Pass a previously returned
75
+ * `appId` to reuse an existing app context.
76
+ */
77
+ appId?: string;
78
+ /**
79
+ * Thread ID for state persistence across calls. Omit to create an ephemeral
80
+ * thread. Pass a previously returned `threadId` to maintain conversation
81
+ * history or variable state.
82
+ */
83
+ threadId?: string;
84
+ /**
85
+ * Called for each debug log event during step execution. When set, the SDK
86
+ * uses SSE streaming to receive real-time progress updates from the API.
87
+ * When omitted, the endpoint returns a single JSON response as before.
88
+ *
89
+ * Log content and frequency varies by step type — image generation emits
90
+ * 2-3 logs, scrape steps emit per-URL progress, LLM steps may emit model
91
+ * selection and token info. A passing status is flagged `ephemeral`, and
92
+ * carries `progress` (0 to 1) when the action knows how far it is: a
93
+ * render's or a media job's.
94
+ */
95
+ onLog?: (event: StepLogEvent) => void;
96
+ /**
97
+ * Send any asset this step generates to one of the app's own file stores
98
+ * instead of the shared public MindStudio CDN.
99
+ *
100
+ * **Optional — the default is fine for most cases.** Omit it and generated
101
+ * assets keep going to the public CDN, exactly as before. Reach for it when
102
+ * the asset is user-specific, should be private, or belongs alongside the
103
+ * app's other files (where it shows up in the app's Files dashboard).
104
+ *
105
+ * The store's `access` comes from its `defineStore()`, so a private store
106
+ * yields a private asset — the returned URL is an on-domain
107
+ * `/_/files/private/...` link that only an authorized session can load,
108
+ * rather than a permanent public one.
109
+ *
110
+ * **For confidential material, pass a private store.** A public CDN URL is
111
+ * unlisted rather than protected: anyone holding it can read the object, and
112
+ * it does not expire.
113
+ *
114
+ * This governs the step's OUTPUT. Inputs are never published either way — a
115
+ * private file or a `shareUrl` you hand an action is read where it sits, and
116
+ * any intermediate the platform needs (transcoding a video, rasterizing a
117
+ * PDF's pages, staging a document for an extraction model) is written to
118
+ * private platform storage and dropped when the call finishes.
119
+ *
120
+ * v2 apps only.
121
+ *
122
+ * @example
123
+ * ```ts
124
+ * const Photos = files.defineStore('product-photos', { access: 'public' });
125
+ *
126
+ * const { imageUrl } = await agent.generateImage(
127
+ * { prompt: 'a red sneaker on concrete' },
128
+ * { store: Photos },
129
+ * );
130
+ * ```
131
+ */
132
+ store?: Store;
133
+ /**
134
+ * @internal Usage-metrics attribution label for this call (e.g. `v2-task`
135
+ * for task-agent tool calls). Analytics-only. Overrides the instance-level
136
+ * source when set.
137
+ */
138
+ requestSource?: string;
139
+ }
140
+ /** Execution metadata returned alongside every step result. */
141
+ export interface StepExecutionMeta {
142
+ /** The app ID used for this execution. Pass to subsequent calls to reuse. */
143
+ $appId: string;
144
+ /** The thread ID used for this execution. Pass to subsequent calls to maintain state. */
145
+ $threadId: string;
146
+ /**
147
+ * Number of API calls remaining in the current rate limit window.
148
+ * Useful for throttling proactively before hitting the limit.
149
+ */
150
+ $rateLimitRemaining?: number;
151
+ /**
152
+ * Cost of this step execution in nanodollars (1/1,000,000,000th of a US
153
+ * dollar). Divide by 1e9 to get USD — e.g. `40000000` = $0.04.
154
+ */
155
+ $billingCost?: number;
156
+ /** Itemized billing events for this step execution. */
157
+ $billingEvents?: Array<Record<string, unknown>>;
158
+ }
159
+ /**
160
+ * Result of a step execution call.
161
+ *
162
+ * Output properties are spread at the top level for easy destructuring:
163
+ * ```ts
164
+ * const { content } = await agent.generateText({ ... });
165
+ * ```
166
+ *
167
+ * Execution metadata (`$appId`, `$threadId`, `$rateLimitRemaining`, `$billingCost`, `$billingEvents`) is also available:
168
+ * ```ts
169
+ * const result = await agent.generateText({ ... });
170
+ * console.log(result.content, result.$threadId, result.$rateLimitRemaining);
171
+ * ```
172
+ */
173
+ export type StepExecutionResult<TOutput = Record<string, unknown>> = TOutput & StepExecutionMeta;
174
+ /** Information about a pre-built agent in the organization. */
175
+ export interface AgentInfo {
176
+ /** Agent UUID. Pass as `appId` to {@link RunAgentOptions}. */
177
+ id: string;
178
+ /** Display name. */
179
+ name: string;
180
+ /** Short description. */
181
+ description: string;
182
+ /** URL-friendly identifier. */
183
+ slug: string;
184
+ /** Agent icon URL. */
185
+ iconUrl: string;
186
+ /** Links: run, edit, details, logs. */
187
+ refs: Record<string, string>;
188
+ /** ISO timestamp. */
189
+ dateCreated: string;
190
+ /** ISO timestamp. */
191
+ dateLastEdited: string;
192
+ }
193
+ /** Result of {@link MindStudioAgent.listAgents}. */
194
+ export interface ListAgentsResult {
195
+ /** Organization UUID. */
196
+ orgId: string;
197
+ /** Organization display name. */
198
+ orgName: string;
199
+ /** Agents in the organization. */
200
+ apps: AgentInfo[];
201
+ }
202
+ /** Result of {@link MindStudioAgent.getUserInfo}. */
203
+ export interface UserInfoResult {
204
+ userId: string;
205
+ displayName: string;
206
+ organizationId: string;
207
+ organizationName: string;
208
+ members: {
209
+ userId: string;
210
+ displayName: string;
211
+ role: 'owner' | 'admin' | 'member' | 'guest' | 'agent';
212
+ }[];
213
+ }
214
+ /**
215
+ * A reference to a MindStudio platform user. Stored as a UUID string.
216
+ *
217
+ * In the database, user values are stored with a `@@user@@` prefix
218
+ * (e.g. `@@user@@550e8400-...`). The SDK handles this automatically —
219
+ * values are clean UUIDs in application code, prefixed/stripped
220
+ * transparently during read/write operations.
221
+ *
222
+ * Use `resolveUser(userId)` when you need display info (name, email, etc.).
223
+ *
224
+ * @example
225
+ * ```ts
226
+ * interface Order {
227
+ * id: string;
228
+ * createdAt: number;
229
+ * updatedAt: number;
230
+ * lastUpdatedBy: string;
231
+ * requestedBy: User;
232
+ * }
233
+ * ```
234
+ */
235
+ export type User = string;
236
+ /**
237
+ * Resolved display info for a platform user. Returned by `resolveUser()`
238
+ * and `resolveUsers()`.
239
+ */
240
+ export interface ResolvedUser {
241
+ /** User ID. */
242
+ id: string;
243
+ /** Display name. */
244
+ name: string;
245
+ /** Email address, if available. */
246
+ email?: string | null;
247
+ /** Profile picture URL, if set. */
248
+ profilePictureUrl?: string | null;
249
+ }
250
+ /** Input for {@link MindStudioAgent.reportIssue}. */
251
+ export interface ReportIssueInput {
252
+ /** Short summary. Required, non-empty, ≤ 300 chars (trimmed server-side). */
253
+ title: string;
254
+ /** Longer description. Optional, ≤ 10,000 chars. Defaults to `""`. */
255
+ body?: string;
256
+ /** Report kind. Defaults to `"bug"`. */
257
+ kind?: 'bug' | 'idea';
258
+ /**
259
+ * Free-form label for who reported it — a name, email, or ticket id.
260
+ * ≤ 200 chars. Display-only; NOT an identity check and NOT tied to a user.
261
+ * Omit for an anonymous report.
262
+ */
263
+ reporter?: string;
264
+ }
265
+ /** A filed issue, returned by {@link MindStudioAgent.reportIssue}. */
266
+ export interface ReportedIssue {
267
+ id: string;
268
+ /** Friendly per-app number — show the user "Reported as #42". */
269
+ number: number;
270
+ title: string;
271
+ body: string;
272
+ kind: 'bug' | 'idea';
273
+ status: 'open';
274
+ /** `"sdk"` for in-app reports filed through this method. */
275
+ authorKind: 'sdk';
276
+ authorUserId: string | null;
277
+ /** Echoes the `reporter` that was sent, or null. */
278
+ reporter: string | null;
279
+ /** ISO-8601. */
280
+ createdAt: string;
281
+ /** ISO-8601. */
282
+ updatedAt: string;
283
+ closedAt: string | null;
284
+ }
285
+ /** An AI model available on MindStudio. */
286
+ export interface MindStudioModel {
287
+ id?: string;
288
+ /** Display name of the model. */
289
+ name?: string;
290
+ /** See `ModelType` for the full set. */
291
+ type?: ModelType;
292
+ maxTemperature?: number;
293
+ maxResponseSize?: number;
294
+ /** Accepted input types for this model (text, imageUrl, videoUrl, etc.). */
295
+ inputs?: Record<string, unknown>[];
296
+ /**
297
+ * When the platform retires this model (`YYYY-MM-DD`, from 00:00 UTC). Until
298
+ * then it runs as itself; from then saved calls run on `replacedBy`.
299
+ */
300
+ retiresOn?: string;
301
+ /** The model that runs in this one's place once it has retired. */
302
+ replacedBy?: string;
303
+ /** True once the model has retired: a call to it runs on `replacedBy`. */
304
+ retired?: boolean;
305
+ }
306
+ /** A lightweight AI model summary. */
307
+ export interface MindStudioModelSummary {
308
+ id?: string;
309
+ /** Display name of the model. */
310
+ name?: string;
311
+ /** See `ModelType` for the full set. */
312
+ type?: ModelType;
313
+ /** Comma-separated tags for the model. */
314
+ tags?: string;
315
+ /**
316
+ * When the platform retires this model (`YYYY-MM-DD`, from 00:00 UTC). Until
317
+ * then it runs as itself; from then saved calls run on `replacedBy`.
318
+ */
319
+ retiresOn?: string;
320
+ /** The model that runs in this one's place once it has retired. */
321
+ replacedBy?: string;
322
+ /** True once the model has retired: a call to it runs on `replacedBy`. */
323
+ retired?: boolean;
324
+ }
325
+ /**
326
+ * Supported model type categories for filtering.
327
+ *
328
+ * `embedding`, `reranking` and `document_extraction` have no SDK step — the
329
+ * data-source pipeline chooses those platform-side and reports the result on
330
+ * `pipeline.embeddingModelId`. They are listed so the catalog can be queried
331
+ * and described, not so they can be passed to a generate call.
332
+ */
333
+ export type ModelType = 'llm_chat' | 'image_generation' | '3d_generation' | 'video_generation' | 'video_analysis' | 'text_to_speech' | 'music_generation' | 'lipsync' | 'vision' | 'transcription' | 'embedding' | 'reranking' | 'document_extraction';
334
+ /** Role assignment for a user within an app. */
335
+ export interface AppRoleAssignment {
336
+ userId: string;
337
+ roleName: string;
338
+ }
339
+ /** Auth context for an app. */
340
+ export interface AppAuthContext {
341
+ /** The authenticated user ID, or null for unauthenticated users. */
342
+ userId: string | null;
343
+ /** All role assignments for this app (all users, all roles). */
344
+ roleAssignments: AppRoleAssignment[];
345
+ }
346
+ /** Column schema for a managed database table. */
347
+ export interface AppDatabaseColumnSchema {
348
+ name: string;
349
+ type: 'text' | 'number' | 'boolean' | 'json' | 'user';
350
+ required: boolean;
351
+ }
352
+ /** Table schema within a managed database. */
353
+ export interface AppDatabaseTable {
354
+ name: string;
355
+ schema: AppDatabaseColumnSchema[];
356
+ }
357
+ /** A managed SQLite database for an app. */
358
+ export interface AppDatabase {
359
+ id: string;
360
+ name: string;
361
+ tables: AppDatabaseTable[];
362
+ }
363
+ /** Result of {@link MindStudioAgent.getAppContext}. */
364
+ export interface AppContextResult {
365
+ auth: AppAuthContext;
366
+ databases: AppDatabase[];
367
+ authConfig?: AuthTableConfig;
368
+ }
369
+ /** Auth table config from the app manifest. Tells the SDK which table/columns are platform-managed. */
370
+ export interface AuthTableConfig {
371
+ table: string;
372
+ columns: {
373
+ email?: string;
374
+ phone?: string;
375
+ roles?: string;
376
+ };
377
+ }
378
+ /** An OAuth connector service with its available actions. Third-party integration from the MindStudio Connector Registry. */
379
+ export interface ConnectorService {
380
+ id?: string;
381
+ /** Display name of the connector service. */
382
+ name?: string;
383
+ icon?: string;
384
+ /** Available actions for this connector service. */
385
+ actions?: {
386
+ id?: string;
387
+ /** Display name of the action. */
388
+ name?: string;
389
+ }[];
390
+ }
391
+ /** Full configuration details for an OAuth connector action. */
392
+ export interface ConnectorActionDetail {
393
+ id?: string;
394
+ /** Display name of the action. */
395
+ name?: string;
396
+ /** What this action does. */
397
+ description?: string;
398
+ /** Short usage guidance for the action. */
399
+ quickHelp?: string;
400
+ /** Input field groups required to call this action. */
401
+ configuration?: {
402
+ title?: string;
403
+ items?: {
404
+ label?: string;
405
+ helpText?: string;
406
+ /** The variable name to use when passing this input. */
407
+ variable?: string;
408
+ /** One of: `text`, `outputVariableName`, `select`. */
409
+ type?: 'text' | 'outputVariableName' | 'select';
410
+ defaultValue?: string;
411
+ placeholder?: string;
412
+ selectOptions?: {
413
+ options?: {
414
+ label?: string;
415
+ value?: string;
416
+ }[];
417
+ };
418
+ }[];
419
+ }[];
420
+ }
421
+ /** An OAuth connection to a third-party service. */
422
+ export interface Connection {
423
+ /** Connection ID. Pass this when executing connector actions. */
424
+ id?: string;
425
+ /** The integration provider (e.g., slack, google, github). */
426
+ provider?: string;
427
+ /** Display name or account identifier for the connection. */
428
+ name?: string;
429
+ }
430
+ export interface PackagedWorkflowInput {
431
+ /** Variable key for this input */
432
+ key: string;
433
+ /** Display name of the input */
434
+ name: string;
435
+ /** Description of what this input is for */
436
+ description: string;
437
+ /** Placeholder text shown in the input field */
438
+ placeholder: string;
439
+ /** Whether this input must be provided */
440
+ required: boolean;
441
+ /** Default value if the input is not provided */
442
+ defaultValue?: string;
443
+ /** Input field type */
444
+ type: 'text' | 'select' | 'transition';
445
+ /** Settings for text-type inputs */
446
+ textSettings?: {
447
+ /** Text input format */
448
+ type: 'default' | 'markdown';
449
+ };
450
+ /** Settings for select-type inputs */
451
+ selectSettings?: {
452
+ /** Available options for the select input */
453
+ options: {
454
+ /** Option value */
455
+ value: string;
456
+ /** Option display label */
457
+ label: string;
458
+ }[];
459
+ };
460
+ }
461
+ export interface PackagedWorkflowSignature {
462
+ /** Metadata about the packaged workflow */
463
+ metadata: {
464
+ /** Display name of the packaged workflow */
465
+ name: string;
466
+ /** Description of what the packaged workflow does */
467
+ description: string;
468
+ /** Icon URL for the packaged workflow */
469
+ iconUrl: string;
470
+ /** Quick help text for users */
471
+ quickHelp: string;
472
+ /** Transition type for the packaged workflow */
473
+ transitionType?: 'controlled' | 'dynamic';
474
+ };
475
+ /** Input parameters the packaged workflow accepts */
476
+ inputs: PackagedWorkflowInput[];
477
+ /** Output variables the packaged workflow returns */
478
+ outputs: {
479
+ /** Output variable key */
480
+ key: string;
481
+ /** Display name of the output */
482
+ name: string;
483
+ /** Description of the output */
484
+ description: string;
485
+ /** Data type of the output */
486
+ type: string;
487
+ }[];
488
+ }
489
+ export interface PackagedWorkflow {
490
+ appId: string;
491
+ workflowId: string;
492
+ appShortId: string;
493
+ workflowName: string;
494
+ signature: PackagedWorkflowSignature;
495
+ }
496
+ /** A single cost estimate entry for an action. */
497
+ export interface StepCostEstimateEntry {
498
+ /** Billing event type identifier. */
499
+ eventType?: string;
500
+ /** Human-readable label for the cost. */
501
+ label?: string;
502
+ /** Price per unit in nanodollars (1/1,000,000,000th of a US dollar). */
503
+ unitPrice?: number;
504
+ /** What constitutes a unit (e.g. "token", "request"). */
505
+ unitType?: string;
506
+ /** Estimated total cost in nanodollars (divide by 1e9 for USD), or null if not estimable. */
507
+ estimatedCost?: number;
508
+ /** Number of billable units. */
509
+ quantity?: number;
510
+ /** Estimated latency based on recent global model metrics. null when no metrics are available. */
511
+ latency?: unknown;
512
+ }
513
+ /** Result of {@link MindStudioAgent.uploadFile}. */
514
+ export interface UploadFileResult {
515
+ /** Permanent public URL where the file is accessible. */
516
+ url: string;
517
+ }
518
+ /** Options for {@link MindStudioAgent.runAgent}. */
519
+ export interface RunAgentOptions {
520
+ /** App/agent ID to run (required). */
521
+ appId: string;
522
+ /** Input variables as key-value pairs. */
523
+ variables?: Record<string, unknown>;
524
+ /** Workflow name to execute. Omit for the app's default. */
525
+ workflow?: string;
526
+ /** App version override (e.g. "draft"). Defaults to "live". */
527
+ version?: string;
528
+ /** Include billing cost in the response. */
529
+ includeBillingCost?: boolean;
530
+ /** Arbitrary metadata stored with the API request log. */
531
+ metadata?: Record<string, unknown>;
532
+ /** Polling interval in milliseconds. @default 1000 */
533
+ pollIntervalMs?: number;
534
+ }
535
+ /** A single step in a batch request. */
536
+ export interface BatchStepInput {
537
+ /** The step type to execute (e.g. "generateImage", "userMessage"). */
538
+ stepType: string;
539
+ /** Step configuration — same format as the single execute endpoint. */
540
+ step: Record<string, unknown>;
541
+ }
542
+ /** Result for a single step in a batch response. */
543
+ export interface BatchStepResult {
544
+ /** The step type that was executed. */
545
+ stepType: string;
546
+ /** Step output data. Present on success. */
547
+ output?: Record<string, unknown>;
548
+ /** Cost of this step in nanodollars (divide by 1e9 for USD). Present on success. */
549
+ billingCost?: number;
550
+ /** Error message. Present when this step failed. */
551
+ error?: string;
552
+ }
553
+ /** Options for {@link MindStudioAgent.executeStepBatch}. */
554
+ export interface ExecuteStepBatchOptions {
555
+ /** App ID to execute within. If omitted, a service account app is used. */
556
+ appId?: string;
557
+ /** Thread ID for state persistence. If omitted, an ephemeral thread is created. */
558
+ threadId?: string;
559
+ /** Progress callback, called on each poll while the batch is running. */
560
+ onProgress?: (completedSteps: number, totalSteps: number) => void;
561
+ /**
562
+ * Send assets generated by any step in this batch to one of the app's own
563
+ * file stores instead of the shared public MindStudio CDN. Optional; applies
564
+ * to every step in the batch. See {@link StepExecutionOptions.store}.
565
+ */
566
+ store?: Store;
567
+ }
568
+ /** Result of {@link MindStudioAgent.executeStepBatch}. */
569
+ export interface ExecuteStepBatchResult {
570
+ /** Results in the same order as the input steps. */
571
+ results: BatchStepResult[];
572
+ /** Sum of billingCost across all successful steps, in nanodollars. */
573
+ totalBillingCost?: number;
574
+ /** The app ID used for execution. */
575
+ appId?: string;
576
+ /** The thread ID used for execution. */
577
+ threadId?: string;
578
+ }
579
+ /** Result of a successful agent run. */
580
+ export interface RunAgentResult {
581
+ /** Whether the run succeeded. */
582
+ success: boolean;
583
+ /** Thread ID for the run. */
584
+ threadId: string;
585
+ /** The result content (last system message). */
586
+ result: string;
587
+ /** Thread messages, if returned. */
588
+ thread?: unknown;
589
+ /** Cost in nanodollars (divide by 1e9 for USD), if `includeBillingCost` was set. */
590
+ billingCost?: number;
591
+ }
@@ -0,0 +1,87 @@
1
+ /**
2
+ * The `voice` namespace — telephony actions for apps with a voice interface.
3
+ *
4
+ * `voice.call()` places an outbound phone call: the platform dials the
5
+ * number and connects the callee to your app's voice agent (the persona,
6
+ * engine, and tools from `src/interfaces/voice.md`). The method that invokes
7
+ * it is the authorization gate — the voice interface's own `auth` block does
8
+ * not apply to calls your backend places deliberately.
9
+ *
10
+ * ```ts
11
+ * // routes/notifyOrderShipped.ts
12
+ * import { voice, auth } from '@mindstudio-ai/agent';
13
+ *
14
+ * export async function notifyOrderShipped(input: { phone: string }) {
15
+ * auth.requireRole('member');
16
+ * const call = await voice.call({ to: input.phone, assumeIdentity: true });
17
+ * return { calling: call.to, from: call.from };
18
+ * }
19
+ * ```
20
+ *
21
+ * **Identity.** With `assumeIdentity: true` the call session runs as the user
22
+ * who invoked this method — the agent's Current User block and every tool
23
+ * call carry that user's identity and roles, exactly as if they'd opened the
24
+ * voice interface themselves. The identity comes from the platform's own
25
+ * execution context, never from arguments. System/cron invocations have no
26
+ * human identity and run the call anonymously. Omitted or `false`: anonymous
27
+ * session (role-gated tools decline).
28
+ *
29
+ * **Caller ID.** A call goes out from one of the app's own dedicated phone
30
+ * numbers (attached in its settings, or with `remy-admin voice numbers`),
31
+ * in dev sessions too. With one number, that's the caller ID. With several,
32
+ * pass `from` to say which (`from_required` otherwise); `from` must be one
33
+ * of the app's active numbers (`from_not_app_number`). Deployed apps
34
+ * without a number throw `phone_out_requires_dedicated_number`; dev
35
+ * sessions without one call from a shared platform number that varies per
36
+ * call, under tighter limits.
37
+ *
38
+ * **Limits.** Per-app: concurrent-session policy, a daily outbound-call cap
39
+ * across all the app's numbers, and a per-call duration ceiling. A number
40
+ * already on an active call with this app can't be dialed again
41
+ * (`voice_callee_busy`).
42
+ *
43
+ * **Compliance.** Automated calls require the callee's prior consent — call
44
+ * your own users who opted in to calls from this app, honor reasonable
45
+ * calling hours, and never dial purchased/cold lists. You are responsible
46
+ * for TCPA (and local-equivalent) compliance.
47
+ */
48
+ /** Transport for the `voice` namespace. @internal */
49
+ export type VoiceTransport = (op: string, body: unknown) => Promise<any>;
50
+ /** The accepted outbound call, already dialing. */
51
+ export interface VoiceCallResult {
52
+ /** The call record's session id (appears in the app's voice call log). */
53
+ sessionId: string;
54
+ status: 'dialing';
55
+ /** The caller-ID number the callee sees. */
56
+ from: string;
57
+ /** The dialed number. */
58
+ to: string;
59
+ }
60
+ /** The `voice` namespace object. */
61
+ export interface Voice {
62
+ /**
63
+ * Place an outbound call to `to` (E.164, e.g. `+13105551234`) and connect
64
+ * the callee to this app's voice agent. Returns as soon as dialing starts;
65
+ * the outcome (answered, busy, no answer) lands on the call record.
66
+ */
67
+ call(params: VoiceCallParams): Promise<VoiceCallResult>;
68
+ }
69
+ /** What `voice.call()` takes. */
70
+ export interface VoiceCallParams {
71
+ /** The number to dial, E.164. */
72
+ to: string;
73
+ /**
74
+ * Which of the app's own numbers to call from, E.164. Required once the
75
+ * app has more than one; with one it's that one.
76
+ */
77
+ from?: string;
78
+ /** Run the call as the user who invoked this method. */
79
+ assumeIdentity?: boolean;
80
+ }
81
+ /**
82
+ * Create a Voice namespace bound to a transport.
83
+ *
84
+ * @internal Called by MindStudioAgent; not part of the public API — access
85
+ * `voice` via the agent instance or the top-level export.
86
+ */
87
+ export declare function createVoice(call: VoiceTransport): Voice;
package/llms.txt CHANGED
@@ -465,7 +465,7 @@ Generate a 3D model using a 3D generation model.
465
465
  - The default model is wavespeed-tripo3d-h3.1 (Tripo v3.1), which makes a model from the prompt, from one `image`, or from `images`: 2–4 views of the same object, in order front, left, back, right.
466
466
  - Models and what they take, set in `threeDModelOverride.config`:
467
467
  - From text or an image: wavespeed-tripo3d-h3.1, wavespeed-meshy7.1 (also `images`, 1–4 views), wavespeed-hunyuan3d-v3 (an `image`, plus optional `back_image_url`, `left_image_url`, `right_image_url`), wavespeed-hunyuan-3d-v3.1-rapid, wavespeed-tripo3d-p2, wavespeed-rodin-v2.5 (`images`, 1–5).
468
- - From an image only: trellis-2, wavespeed-meshy7 (or `images`, 1–4 views), wavespeed-tripo3d-v2.5, seed3d-2.0, wavespeed-sam-3d-objects (with optional `mask_images`).
468
+ - From an image only: trellis-2, wavespeed-meshy7 (or `images`, 1–4 views), seed3d-2.0.
469
469
  - From views: wavespeed-hi3d-v3.0 (`front_image`, and optional `back_image`, `left_image`, `right_image`).
470
470
  - `$mode` in the config picks a model's mode (`text-to-3d`, `image-to-3d`, or its multi-view mode). Left out, `images` picks the multi-view mode and `image` picks image-to-3d; with neither, the model's default mode. A text mode needs the prompt; in the others the prompt is optional guidance.
471
471
  - The output is standardized as a GLB URL plus optional FBX/OBJ/USDZ, thumbnail, texture maps, and provider task ID.
@@ -514,7 +514,7 @@ Generate an audio file from provided instructions (text) using a music model.
514
514
  #### generateSound
515
515
  Generate a sound effect from a text description using a sound model.
516
516
  - `text` describes the sound effect to generate.
517
- - The default model is elevenlabs-sound_v2. Options go in `soundModelOverride.config`:
517
+ - The default model is elevenlabs-sound_v3. Options go in `soundModelOverride.config`:
518
518
  - `durationSeconds` — the length, from 0.5 to 30. Left out, the model picks one from the text, and the effect is billed as 5 seconds whatever its length.
519
519
  - `loop: true` — a sound that repeats with no audible start or end, for ambience and backgrounds.
520
520
  - `promptInfluence` — how literally the text is followed, from 0 to 1 (default 0.3).