@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.
- package/CHANGELOG.md +14 -0
- package/dist/analytics/index.d.ts +384 -0
- package/dist/auth/index.d.ts +113 -0
- package/dist/browser/index.d.ts +332 -0
- package/dist/cli.js +29 -29
- package/dist/client.d.ts +767 -0
- package/dist/config.d.ts +13 -0
- package/dist/context.d.ts +125 -0
- package/dist/datasources/index.d.ts +52 -0
- package/dist/datasources/source.d.ts +1074 -0
- package/dist/db/aggregate.d.ts +101 -0
- package/dist/db/index.d.ts +280 -0
- package/dist/db/mutation.d.ts +65 -0
- package/dist/db/predicate.d.ts +85 -0
- package/dist/db/query.d.ts +233 -0
- package/dist/db/raw.d.ts +36 -0
- package/dist/db/readBatching.d.ts +36 -0
- package/dist/db/scanHints.d.ts +8 -0
- package/dist/db/sql.d.ts +136 -0
- package/dist/db/table.d.ts +146 -0
- package/dist/db/time.d.ts +17 -0
- package/dist/db/types.d.ts +237 -0
- package/dist/db-ws.d.ts +35 -0
- package/dist/email/index.d.ts +396 -0
- package/dist/errors.d.ts +34 -0
- package/dist/events/index.d.ts +127 -0
- package/dist/files/index.d.ts +62 -0
- package/dist/files/store.d.ts +244 -0
- package/dist/generated/metadata.d.ts +8 -0
- package/dist/generated/snippets.d.ts +8 -0
- package/dist/generated/steps.d.ts +2745 -0
- package/dist/generated/types.d.ts +4234 -0
- package/dist/http.d.ts +22 -0
- package/dist/index.d.ts +59 -13329
- package/dist/index.js +17 -17
- package/dist/index.js.map +7 -1
- package/dist/jewel/index.d.ts +325 -0
- package/dist/mapper/index.d.ts +229 -0
- package/dist/rate-limit.d.ts +25 -0
- package/dist/reader/index.d.ts +170 -0
- package/dist/respond.d.ts +68 -0
- package/dist/task/index.d.ts +18 -0
- package/dist/task/local.d.ts +48 -0
- package/dist/task/schema.d.ts +120 -0
- package/dist/task/types.d.ts +203 -0
- package/dist/types.d.ts +591 -0
- package/dist/voice/index.d.ts +87 -0
- package/llms.txt +2 -2
- package/package.json +6 -12
- package/dist/postinstall.js +0 -12115
package/dist/types.d.ts
ADDED
|
@@ -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),
|
|
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-
|
|
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).
|