@agent-commons/sdk 0.2.3 → 0.4.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.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- type ModelProvider = 'openai' | 'anthropic' | 'google' | 'mistral' | 'groq' | 'ollama' | 'openrouter' | 'xai' | 'custom';
1
+ type ModelProvider = "openai" | "anthropic" | "google" | "mistral" | "groq" | "ollama" | "openrouter" | "xai" | "custom";
2
2
  interface ModelConfig {
3
3
  provider: ModelProvider;
4
4
  modelId: string;
@@ -7,8 +7,28 @@ interface ModelConfig {
7
7
  temperature?: number;
8
8
  maxTokens?: number;
9
9
  topP?: number;
10
- reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
11
- verbosity?: 'low' | 'medium' | 'high';
10
+ reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
11
+ verbosity?: "low" | "medium" | "high";
12
+ }
13
+ type AgentRuntimeType = "native" | "openclaw" | "hermes" | "custom";
14
+ type AgentRuntimeStatus = "disabled" | "provisioning" | "starting" | "ready" | "degraded" | "stopped" | "failed";
15
+ interface AgentRuntimeConfig {
16
+ deploymentMode?: "managed" | "external";
17
+ channelPolicy?: "pairing" | "allowlist" | "open" | "disabled";
18
+ enabledPlugins?: string[];
19
+ enabledToolsets?: string[];
20
+ memoryMode?: "native" | "platform" | "hybrid";
21
+ metadata?: Record<string, string | number | boolean>;
22
+ }
23
+ interface AgentRuntime {
24
+ runtimeType: AgentRuntimeType;
25
+ version?: string | null;
26
+ status: AgentRuntimeStatus;
27
+ config: AgentRuntimeConfig;
28
+ capabilities: Record<string, boolean>;
29
+ updatedAt?: string | null;
30
+ managed: boolean;
31
+ computer?: AgentComputer | null;
12
32
  }
13
33
  interface Agent {
14
34
  agentId: string;
@@ -31,36 +51,157 @@ interface Agent {
31
51
  isLiaison?: boolean;
32
52
  externalUrl?: string;
33
53
  createdAt: string;
54
+ runtimeType?: AgentRuntimeType;
55
+ runtimeVersion?: string | null;
56
+ runtimeStatus?: AgentRuntimeStatus;
57
+ runtimeConfig?: AgentRuntimeConfig;
58
+ runtimeCapabilities?: Record<string, boolean>;
59
+ }
60
+ /** Agent computers are durable. Runtime pods may be replaced, but this identity persists. */
61
+ type AgentComputerLifecycle = "persistent";
62
+ type ComputerPersistence = AgentComputerLifecycle;
63
+ type ComputerLifecycle = AgentComputerLifecycle;
64
+ type ComputerResourceProfile = "starter" | "standard" | "performance" | "gpu";
65
+ type ComputerResourceMode = "fixed" | "elastic";
66
+ type AgentComputerResourceProfile = ComputerResourceProfile;
67
+ type AgentComputerResourceMode = ComputerResourceMode;
68
+ /**
69
+ * Common accelerator names. Providers may expose additional values without
70
+ * requiring an SDK release, so string extensions remain valid.
71
+ */
72
+ type ComputerGpuType = "nvidia-t4" | "nvidia-l4" | "nvidia-a10" | "nvidia-a100" | "nvidia-h100" | "nvidia-h200" | "nvidia-b200" | (string & {});
73
+ interface ComputerGpu {
74
+ count: number;
75
+ type?: ComputerGpuType;
76
+ }
77
+ type AgentComputerGpuType = ComputerGpuType;
78
+ type AgentComputerGpu = ComputerGpu;
79
+ /** Public, provider-neutral resource units. */
80
+ interface ComputerResources {
81
+ vcpu: number;
82
+ memoryGiB: number;
83
+ storageGiB: number;
84
+ gpu?: ComputerGpu | null;
85
+ }
86
+ type AgentComputerResources = ComputerResources;
87
+ interface ComputerResourceUpdate {
88
+ vcpu?: number;
89
+ memoryGiB?: number;
90
+ storageGiB?: number;
91
+ gpu?: ComputerGpu | null;
92
+ }
93
+ type AgentComputerDesiredState = "running" | "sleeping" | "disabled";
94
+ type AgentComputerStatus = "disabled" | "provisioning" | "starting" | "running" | "idle" | "sleeping" | "resizing" | "restarting" | "stopping" | "error" | "unavailable" | "stopped" | "terminated" | "failed";
95
+ type ComputerNetworkAccess = "standard" | "restricted" | "disabled" | (string & {});
96
+ /**
97
+ * Mutable computer settings only. Server-owned identity, provider, billing,
98
+ * timestamps, and runtime fields intentionally cannot be submitted here.
99
+ */
100
+ interface ComputerConfigUpdate {
101
+ enabled?: boolean;
102
+ autoWake?: boolean;
103
+ allowAgentUse?: boolean;
104
+ allowBrowser?: boolean;
105
+ allowTerminal?: boolean;
106
+ allowFilesystem?: boolean;
107
+ networkAccess?: ComputerNetworkAccess;
108
+ resourceProfile?: ComputerResourceProfile;
109
+ resourceMode?: ComputerResourceMode;
110
+ resources?: ComputerResourceUpdate;
34
111
  }
35
- type AgentComputerLifecycle = 'persistent' | 'ephemeral';
36
- type AgentComputerStatus = 'provisioning' | 'starting' | 'running' | 'idle' | 'stopping' | 'stopped' | 'terminated' | 'failed' | 'error' | 'unavailable';
37
112
  interface AgentComputerConfig {
38
113
  configId: string;
39
114
  agentId: string;
40
115
  enabled: boolean;
41
- defaultMode: AgentComputerLifecycle;
116
+ /** @deprecated Computers are always persistent. */
117
+ defaultMode: AgentComputerLifecycle | "ephemeral";
118
+ /** @deprecated Use autoWake. */
42
119
  autoStart: boolean;
120
+ /** @deprecated Use allowAgentUse. */
43
121
  allowAgentStart: boolean;
122
+ /** @deprecated The singleton computer is selected implicitly. */
44
123
  allowUserSelect: boolean;
45
124
  allowBrowser: boolean;
46
125
  allowTerminal: boolean;
47
126
  allowFilesystem: boolean;
48
- networkAccess: 'standard' | 'restricted' | 'disabled' | string;
127
+ networkAccess: ComputerNetworkAccess;
128
+ /** @deprecated The singleton limit is always one. */
49
129
  maxPersistentComputers: number;
130
+ /** @deprecated Ephemeral computers are no longer supported. */
50
131
  maxEphemeralComputers: number;
132
+ /** @deprecated The singleton limit is always one. */
51
133
  maxConcurrentComputers: number;
134
+ /** @deprecated Use the service's sleep policy. */
52
135
  idleTtlMinutes: number;
136
+ /** @deprecated Persistent computers are not scoped to chat sessions. */
53
137
  sessionTtlMinutes: number;
54
138
  image?: string | null;
139
+ /** @deprecated Provider quantities are represented by resources. */
55
140
  cpuLimit?: string | null;
141
+ /** @deprecated Provider quantities are represented by resources. */
56
142
  memoryLimit?: string | null;
143
+ /** @deprecated Provider quantities are represented by resources. */
57
144
  storageLimit?: string | null;
58
145
  region?: string | null;
59
146
  provider: string;
60
147
  metadata?: Record<string, any> | null;
61
148
  createdAt: string;
62
149
  updatedAt: string;
150
+ persistence?: ComputerPersistence;
151
+ autoWake?: boolean;
152
+ allowAgentUse?: boolean;
153
+ resourceProfile?: ComputerResourceProfile;
154
+ resourceMode?: ComputerResourceMode;
155
+ resources?: ComputerResources;
156
+ cpuRequest?: string | null;
157
+ memoryRequest?: string | null;
158
+ gpuType?: ComputerGpuType | null;
159
+ gpuCount?: number;
160
+ billingMode?: "tier" | "usage" | (string & {});
161
+ }
162
+ interface AgentComputerBrowser {
163
+ status?: "off" | "starting" | "on" | "error";
164
+ url?: string | null;
165
+ title?: string | null;
166
+ screenshot?: string | null;
167
+ lastAction?: string | null;
168
+ error?: string | null;
169
+ updatedAt?: string | null;
170
+ }
171
+ interface AgentComputerTerminal {
172
+ lastCommand?: string | null;
173
+ lastExitCode?: number | null;
174
+ lastOutput?: string | null;
175
+ updatedAt?: string | null;
176
+ }
177
+ /** The one persistent cloud computer assigned to an agent. */
178
+ interface AgentComputer {
179
+ computerId: string;
180
+ agentId: string;
181
+ enabled: boolean;
182
+ persistence: ComputerPersistence;
183
+ desiredState: AgentComputerDesiredState;
184
+ status: AgentComputerStatus;
185
+ resourceProfile: ComputerResourceProfile;
186
+ resourceMode: ComputerResourceMode;
187
+ resources: ComputerResources;
188
+ provider?: string;
189
+ cloudProvider?: string | null;
190
+ region?: string | null;
191
+ runtimeId?: string | null;
192
+ runtimeGeneration?: number;
193
+ namespaceId?: string | null;
194
+ workspaceRoot?: string | null;
195
+ browser?: AgentComputerBrowser | null;
196
+ terminal?: AgentComputerTerminal | null;
197
+ lastActivityAt?: string | null;
198
+ startedAt?: string | null;
199
+ sleptAt?: string | null;
200
+ errorMessage?: string | null;
201
+ createdAt: string;
202
+ updatedAt: string;
63
203
  }
204
+ /** @deprecated Use AgentComputer. */
64
205
  interface AgentComputerInstance {
65
206
  computerId: string;
66
207
  agentId: string;
@@ -68,7 +209,8 @@ interface AgentComputerInstance {
68
209
  ownerUserId?: string | null;
69
210
  workspaceId?: string | null;
70
211
  name: string;
71
- lifecycle: AgentComputerLifecycle;
212
+ /** @deprecated Ephemeral values may be read from historical records only. */
213
+ lifecycle: AgentComputerLifecycle | "ephemeral";
72
214
  status: AgentComputerStatus;
73
215
  provider: string;
74
216
  cloudProvider?: string | null;
@@ -81,21 +223,8 @@ interface AgentComputerInstance {
81
223
  storageLimit?: string | null;
82
224
  workspaceRoot?: string | null;
83
225
  workspaceSnapshot?: string | null;
84
- browser?: {
85
- status?: 'off' | 'starting' | 'on' | 'error';
86
- url?: string | null;
87
- title?: string | null;
88
- screenshot?: string | null;
89
- lastAction?: string | null;
90
- error?: string | null;
91
- updatedAt?: string | null;
92
- } | null;
93
- terminal?: {
94
- lastCommand?: string | null;
95
- lastExitCode?: number | null;
96
- lastOutput?: string | null;
97
- updatedAt?: string | null;
98
- } | null;
226
+ browser?: AgentComputerBrowser | null;
227
+ terminal?: AgentComputerTerminal | null;
99
228
  metadata?: Record<string, any> | null;
100
229
  lastActivityAt?: string | null;
101
230
  expiresAt?: string | null;
@@ -104,6 +233,42 @@ interface AgentComputerInstance {
104
233
  errorMessage?: string | null;
105
234
  createdAt: string;
106
235
  updatedAt: string;
236
+ canonical?: boolean;
237
+ enabled?: boolean;
238
+ persistence?: ComputerPersistence;
239
+ desiredState?: AgentComputerDesiredState;
240
+ resourceProfile?: ComputerResourceProfile;
241
+ resourceMode?: ComputerResourceMode;
242
+ resources?: ComputerResources;
243
+ cpuRequest?: string | null;
244
+ memoryRequest?: string | null;
245
+ gpuType?: ComputerGpuType | null;
246
+ gpuCount?: number;
247
+ runtimeId?: string | null;
248
+ runtimeGeneration?: number;
249
+ persistentVolumeId?: string | null;
250
+ computeTenantId?: string | null;
251
+ computeCellId?: string | null;
252
+ }
253
+ interface ComputerActionParams {
254
+ reason?: string;
255
+ }
256
+ interface ComputerResizeParams {
257
+ resourceProfile?: ComputerResourceProfile;
258
+ resourceMode?: ComputerResourceMode;
259
+ resources?: ComputerResourceUpdate;
260
+ }
261
+ interface ComputerCommandParams {
262
+ command: string;
263
+ cwd?: string;
264
+ timeoutSeconds?: number;
265
+ }
266
+ interface ComputerFile {
267
+ path: string;
268
+ content: string;
269
+ }
270
+ interface ComputerBrowserOpenParams {
271
+ url: string;
107
272
  }
108
273
  interface AgentComputerEvent {
109
274
  eventId: string;
@@ -136,6 +301,9 @@ interface CreateAgentParams {
136
301
  topP?: number;
137
302
  commonTools?: string[];
138
303
  avatar?: string;
304
+ runtimeType?: AgentRuntimeType;
305
+ runtimeVersion?: string;
306
+ runtimeConfig?: AgentRuntimeConfig;
139
307
  }
140
308
  interface Session {
141
309
  sessionId: string;
@@ -147,9 +315,9 @@ interface Session {
147
315
  };
148
316
  createdAt: string;
149
317
  /** 'cli' | 'web' — origin of the session, used for filtering in the UI */
150
- source?: 'cli' | 'web';
318
+ source?: "cli" | "web";
151
319
  /** Same as source; returned from the backend column `initiator_type` */
152
- initiatorType?: 'cli' | 'web';
320
+ initiatorType?: "cli" | "web";
153
321
  }
154
322
  interface RunParams {
155
323
  agentId: string;
@@ -158,8 +326,10 @@ interface RunParams {
158
326
  initiatorId?: string;
159
327
  computerRequest?: {
160
328
  enabled: boolean;
329
+ /** @deprecated The agent's singleton computer is selected implicitly. */
161
330
  computerIds?: string[];
162
- lifecycle?: AgentComputerLifecycle;
331
+ /** @deprecated Computers are always persistent; this value is ignored. */
332
+ lifecycle?: AgentComputerLifecycle | "ephemeral";
163
333
  };
164
334
  /** Uploaded file references. Raw file bytes must be uploaded separately. */
165
335
  attachments?: Array<{
@@ -175,12 +345,12 @@ interface RunParams {
175
345
  }>;
176
346
  }
177
347
  interface ChatMessage {
178
- role: 'user' | 'assistant' | 'system' | 'tool';
348
+ role: "user" | "assistant" | "system" | "tool";
179
349
  content: string | Array<{
180
- type: 'text';
350
+ type: "text";
181
351
  text: string;
182
352
  } | {
183
- type: 'image_url';
353
+ type: "image_url";
184
354
  image_url: {
185
355
  url: string;
186
356
  };
@@ -188,14 +358,18 @@ interface ChatMessage {
188
358
  tool_call_id?: string;
189
359
  name?: string;
190
360
  }
191
- type StreamEventType = 'token' | 'tool' | 'toolProgress' | 'toolStart' | 'toolEnd' | 'agent_step' | 'final' | 'completed' | 'failed' | 'cancelled' | 'status' | 'keepalive' | 'cli_tool_request' | 'error';
361
+ type StreamEventType = "token" | "tool" | "toolProgress" | "toolStart" | "toolEnd" | "agent_step" | "run_started" | "final" | "completed" | "failed" | "cancelled" | "status" | "keepalive" | "cli_tool_request" | "error";
192
362
  interface StreamEvent {
193
363
  type: StreamEventType;
194
- phase?: 'commentary' | 'final_answer' | string;
364
+ /** Identifies the run; pass to POST /v1/agents/runs/:runId/stream to resume a dropped stream. */
365
+ runId?: string;
366
+ /** Monotonic per-run sequence number; resume with `after: <last seen seq>` to avoid duplicates. */
367
+ seq?: number;
368
+ phase?: "commentary" | "final_answer" | string;
195
369
  role?: string;
196
370
  content?: string;
197
371
  stage?: string;
198
- status?: 'queued' | 'running' | 'completed' | 'failed' | string;
372
+ status?: "queued" | "running" | "completed" | "failed" | string;
199
373
  name?: string;
200
374
  toolName?: string;
201
375
  tool?: string;
@@ -217,7 +391,7 @@ interface Workflow {
217
391
  description?: string;
218
392
  definition: WorkflowDefinition;
219
393
  ownerId: string;
220
- ownerType: 'user' | 'agent';
394
+ ownerType: "user" | "agent";
221
395
  isPublic?: boolean;
222
396
  category?: string;
223
397
  tags?: string[];
@@ -230,7 +404,7 @@ interface WorkflowDefinition {
230
404
  edges: WorkflowEdge[];
231
405
  outputMapping?: Record<string, string>;
232
406
  }
233
- type WorkflowNodeType = 'tool' | 'input' | 'output' | 'condition' | 'transform' | 'loop' | 'agent_processor' | 'workflow' | 'human_approval';
407
+ type WorkflowNodeType = "tool" | "input" | "output" | "condition" | "transform" | "loop" | "agent_processor" | "workflow" | "human_approval";
234
408
  interface WorkflowNode {
235
409
  id: string;
236
410
  type: WorkflowNodeType | string;
@@ -253,7 +427,7 @@ interface WorkflowEdge {
253
427
  interface WorkflowExecution {
254
428
  executionId: string;
255
429
  workflowId: string;
256
- status: 'running' | 'completed' | 'failed' | 'cancelled' | 'awaiting_approval';
430
+ status: "running" | "completed" | "failed" | "cancelled" | "awaiting_approval";
257
431
  startedAt?: string;
258
432
  completedAt?: string;
259
433
  outputData?: any;
@@ -270,8 +444,8 @@ interface Task {
270
444
  sessionId: string;
271
445
  title: string;
272
446
  description?: string;
273
- status: 'pending' | 'started' | 'running' | 'completed' | 'failed' | 'cancelled';
274
- executionMode: 'single' | 'workflow' | 'sequential';
447
+ status: "pending" | "started" | "running" | "completed" | "failed" | "cancelled";
448
+ executionMode: "single" | "workflow" | "sequential";
275
449
  workflowId?: string;
276
450
  cronExpression?: string;
277
451
  isRecurring?: boolean;
@@ -290,7 +464,7 @@ interface Task {
290
464
  summary?: string;
291
465
  errorMessage?: string;
292
466
  createdBy: string;
293
- createdByType: 'user' | 'agent';
467
+ createdByType: "user" | "agent";
294
468
  createdAt: string;
295
469
  updatedAt?: string;
296
470
  }
@@ -299,7 +473,7 @@ interface CreateTaskParams {
299
473
  sessionId: string;
300
474
  title: string;
301
475
  description?: string;
302
- executionMode?: 'single' | 'workflow' | 'sequential';
476
+ executionMode?: "single" | "workflow" | "sequential";
303
477
  workflowId?: string;
304
478
  workflowInputs?: Record<string, any>;
305
479
  cronExpression?: string;
@@ -307,13 +481,13 @@ interface CreateTaskParams {
307
481
  isRecurring?: boolean;
308
482
  dependsOn?: string[];
309
483
  tools?: string[];
310
- toolConstraintType?: 'hard' | 'soft' | 'none';
484
+ toolConstraintType?: "hard" | "soft" | "none";
311
485
  toolInstructions?: string;
312
486
  priority?: number;
313
487
  /** Max execution time in milliseconds for workflow tasks */
314
488
  timeoutMs?: number;
315
489
  createdBy: string;
316
- createdByType: 'user' | 'agent';
490
+ createdByType: "user" | "agent";
317
491
  }
318
492
  interface Tool {
319
493
  toolId: string;
@@ -334,15 +508,15 @@ interface CreateToolParams {
334
508
  apiSpec?: {
335
509
  baseUrl: string;
336
510
  path: string;
337
- method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | string;
511
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | string;
338
512
  headers?: Record<string, string>;
339
513
  queryParams?: Record<string, string>;
340
514
  bodyTemplate?: any;
341
- authType?: 'none' | 'bearer' | 'api-key' | 'basic' | 'oauth2' | string;
515
+ authType?: "none" | "bearer" | "api-key" | "basic" | "oauth2" | string;
342
516
  authKeyName?: string;
343
517
  oauthProviderKey?: string;
344
518
  oauthScopes?: string[];
345
- oauthTokenLocation?: 'header' | 'query' | 'body';
519
+ oauthTokenLocation?: "header" | "query" | "body";
346
520
  oauthTokenKey?: string;
347
521
  oauthTokenPrefix?: string;
348
522
  };
@@ -351,8 +525,8 @@ interface CreateToolParams {
351
525
  inputSchema?: any;
352
526
  outputSchema?: any;
353
527
  owner?: string;
354
- ownerType?: 'user' | 'agent';
355
- visibility?: 'private' | 'public' | 'platform';
528
+ ownerType?: "user" | "agent";
529
+ visibility?: "private" | "public" | "platform";
356
530
  tags?: string[];
357
531
  version?: string;
358
532
  rateLimitPerMinute?: number;
@@ -362,7 +536,7 @@ interface ToolKey {
362
536
  keyId: string;
363
537
  toolId?: string;
364
538
  ownerId: string;
365
- ownerType: 'user' | 'agent';
539
+ ownerType: "user" | "agent";
366
540
  keyName: string;
367
541
  displayName?: string;
368
542
  description?: string;
@@ -374,7 +548,7 @@ interface ToolKey {
374
548
  interface CreateToolKeyParams {
375
549
  toolId?: string;
376
550
  ownerId: string;
377
- ownerType: 'user' | 'agent';
551
+ ownerType: "user" | "agent";
378
552
  keyName: string;
379
553
  value: string;
380
554
  displayName?: string;
@@ -385,25 +559,25 @@ interface ToolPermission {
385
559
  id: string;
386
560
  toolId: string;
387
561
  subjectId: string;
388
- subjectType: 'user' | 'agent';
389
- permission: 'read' | 'execute' | 'admin';
562
+ subjectType: "user" | "agent";
563
+ permission: "read" | "execute" | "admin";
390
564
  grantedBy?: string;
391
565
  createdAt: string;
392
566
  expiresAt?: string;
393
567
  }
394
- type A2ATaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
568
+ type A2ATaskState = "submitted" | "working" | "input-required" | "completed" | "failed" | "canceled";
395
569
  interface A2ATextPart {
396
- type: 'text';
570
+ type: "text";
397
571
  text: string;
398
572
  metadata?: Record<string, any>;
399
573
  }
400
574
  interface A2ADataPart {
401
- type: 'data';
575
+ type: "data";
402
576
  data: Record<string, any>;
403
577
  metadata?: Record<string, any>;
404
578
  }
405
579
  interface A2AFilePart {
406
- type: 'file';
580
+ type: "file";
407
581
  file: {
408
582
  name?: string;
409
583
  mimeType?: string;
@@ -414,7 +588,7 @@ interface A2AFilePart {
414
588
  }
415
589
  type A2AMessagePart = A2ATextPart | A2ADataPart | A2AFilePart;
416
590
  interface A2AMessage {
417
- role: 'user' | 'agent';
591
+ role: "user" | "agent";
418
592
  parts: A2AMessagePart[];
419
593
  contextId?: string;
420
594
  messageId?: string;
@@ -472,19 +646,19 @@ interface A2ASendTaskParams {
472
646
  token?: string;
473
647
  };
474
648
  }
475
- type McpConnectionType = 'stdio' | 'sse' | 'http' | 'streamable-http';
649
+ type McpConnectionType = "stdio" | "sse" | "http" | "streamable-http";
476
650
  interface McpServer {
477
651
  serverId: string;
478
652
  name: string;
479
653
  description?: string;
480
654
  connectionType: McpConnectionType;
481
655
  connectionConfig: Record<string, any>;
482
- status: 'connected' | 'disconnected' | 'error';
656
+ status: "connected" | "disconnected" | "error";
483
657
  toolsCount: number;
484
658
  capabilities?: Record<string, any>;
485
659
  isPublic: boolean;
486
660
  ownerId: string;
487
- ownerType: 'user' | 'agent';
661
+ ownerType: "user" | "agent";
488
662
  createdAt: string;
489
663
  }
490
664
  interface McpResource {
@@ -548,15 +722,15 @@ interface CreateSkillParams {
548
722
  tools?: string[];
549
723
  triggers?: string[];
550
724
  ownerId?: string;
551
- ownerType?: 'platform' | 'user' | 'agent';
725
+ ownerType?: "platform" | "user" | "agent";
552
726
  isPublic?: boolean;
553
727
  tags?: string[];
554
728
  icon?: string;
555
729
  source?: string;
556
730
  sourceUrl?: string;
557
731
  }
558
- type MemoryType = 'episodic' | 'semantic' | 'procedural';
559
- type MemorySourceType = 'auto' | 'manual';
732
+ type MemoryType = "episodic" | "semantic" | "procedural";
733
+ type MemorySourceType = "auto" | "manual";
560
734
  interface AgentMemory {
561
735
  memoryId: string;
562
736
  agentId: string;
@@ -598,6 +772,18 @@ interface UpdateMemoryParams {
598
772
  isActive?: boolean;
599
773
  memoryType?: MemoryType;
600
774
  }
775
+ interface SharedMemoryScope {
776
+ scopeId: string;
777
+ name: string;
778
+ description?: string | null;
779
+ access?: "read" | "write" | "admin";
780
+ updatedAt: string;
781
+ }
782
+ interface CreateSharedMemoryScopeParams {
783
+ name: string;
784
+ description?: string;
785
+ agentIds: string[];
786
+ }
601
787
  interface UsageEvent {
602
788
  eventId: string;
603
789
  agentId: string;
@@ -625,15 +811,15 @@ interface UsageAggregation {
625
811
  callCount: number;
626
812
  events: UsageEvent[];
627
813
  }
628
- type CreditDirection = 'grant' | 'debit' | 'adjustment' | 'refund' | 'expiration';
629
- type CreditPlatform = 'agent_commons' | 'commonlab' | 'common_os' | 'system';
814
+ type CreditDirection = "grant" | "debit" | "adjustment" | "refund" | "expiration";
815
+ type CreditPlatform = "agent_commons" | "commonlab" | "common_os" | "system";
630
816
  interface CreditLedgerEntry {
631
817
  entryId: string;
632
818
  principalId: string;
633
- principalType: 'user' | 'agent' | 'service';
819
+ principalType: "user" | "agent" | "service";
634
820
  workspaceId?: string | null;
635
821
  amount: number;
636
- currency: 'credits';
822
+ currency: "credits";
637
823
  direction: CreditDirection;
638
824
  eventType: string;
639
825
  sourcePlatform: CreditPlatform;
@@ -657,11 +843,11 @@ interface CreditBalance {
657
843
  principalId: string;
658
844
  workspaceId?: string | null;
659
845
  balance: number;
660
- currency: 'credits';
846
+ currency: "credits";
661
847
  }
662
848
  interface CreditWriteParams {
663
849
  principalId: string;
664
- principalType?: 'user' | 'agent' | 'service';
850
+ principalType?: "user" | "agent" | "service";
665
851
  workspaceId?: string | null;
666
852
  amount: number;
667
853
  eventType: string;
@@ -677,7 +863,7 @@ interface CreditWriteParams {
677
863
  usageEventId?: string;
678
864
  metadata?: Record<string, unknown>;
679
865
  }
680
- type WalletType = 'eoa' | 'erc4337' | 'external';
866
+ type WalletType = "eoa" | "erc4337" | "external";
681
867
  interface AgentWallet {
682
868
  id: string;
683
869
  agentId: string;
@@ -703,7 +889,7 @@ interface CreateWalletParams {
703
889
  externalAddress?: string;
704
890
  chainId?: string;
705
891
  }
706
- type ApiKeyPrincipalType = 'user' | 'agent';
892
+ type ApiKeyPrincipalType = "user" | "agent";
707
893
  interface ApiKey {
708
894
  id: string;
709
895
  label?: string | null;
@@ -751,6 +937,26 @@ declare class CommonsClient {
751
937
  update: (agentId: string, params: Partial<CreateAgentParams>) => Promise<{
752
938
  data: Agent;
753
939
  }>;
940
+ getRuntime: (agentId: string) => Promise<{
941
+ data: AgentRuntime;
942
+ }>;
943
+ configureRuntime: (agentId: string, params: {
944
+ runtimeType?: AgentRuntimeType;
945
+ version?: string | null;
946
+ config?: AgentRuntimeConfig;
947
+ deploy?: boolean;
948
+ }) => Promise<{
949
+ data: AgentRuntime;
950
+ }>;
951
+ deployRuntime: (agentId: string) => Promise<{
952
+ data: AgentRuntime;
953
+ }>;
954
+ sleepRuntime: (agentId: string) => Promise<{
955
+ data: AgentRuntime;
956
+ }>;
957
+ restartRuntime: (agentId: string) => Promise<{
958
+ data: AgentRuntime;
959
+ }>;
754
960
  /** List tools assigned to an agent. */
755
961
  listTools: (agentId: string) => Promise<{
756
962
  data: any[];
@@ -834,16 +1040,49 @@ declare class CommonsClient {
834
1040
  getComputerConfig: (agentId: string) => Promise<{
835
1041
  data: AgentComputerConfig;
836
1042
  }>;
837
- updateComputerConfig: (agentId: string, params: Partial<AgentComputerConfig>) => Promise<{
1043
+ updateComputerConfig: (agentId: string, params: ComputerConfigUpdate) => Promise<{
838
1044
  data: AgentComputerConfig;
839
1045
  }>;
840
- listComputers: (agentId: string, filter?: {
1046
+ /** Get the agent's one persistent cloud computer. */
1047
+ getComputer: (agentId: string, _legacyComputerId?: string) => Promise<{
1048
+ data: AgentComputer | null;
1049
+ }>;
1050
+ /** Wake the agent's persistent cloud computer, provisioning it if needed. */
1051
+ wakeComputer: (agentId: string, params?: ComputerActionParams) => Promise<{
1052
+ data: AgentComputer;
1053
+ }>;
1054
+ /** Sleep the runtime while preserving the computer's durable workspace. */
1055
+ sleepComputer: (agentId: string, params?: ComputerActionParams) => Promise<{
1056
+ data: AgentComputer;
1057
+ }>;
1058
+ /** Replace the runtime without replacing the persistent computer. */
1059
+ restartComputer: (agentId: string, params?: ComputerActionParams) => Promise<{
1060
+ data: AgentComputer;
1061
+ }>;
1062
+ resizeComputer: (agentId: string, params: ComputerResizeParams) => Promise<{
1063
+ data: AgentComputer;
1064
+ }>;
1065
+ execComputer: (agentId: string, params: ComputerCommandParams) => Promise<{
1066
+ data: any;
1067
+ }>;
1068
+ readComputerFile: (agentId: string, pathOrLegacyComputerId: string, legacyPath?: string) => Promise<{
1069
+ data: ComputerFile;
1070
+ }>;
1071
+ openComputerBrowser: (agentId: string, paramsOrLegacyComputerId: ComputerBrowserOpenParams | string, legacyParams?: ComputerBrowserOpenParams) => Promise<{
1072
+ data: any;
1073
+ }>;
1074
+ listComputerEvents: (agentId: string, limitOrLegacyComputerId?: number | string, legacyLimit?: number) => Promise<{
1075
+ data: AgentComputerEvent[];
1076
+ }>;
1077
+ /** @deprecated Use getComputer. The singleton is returned as a one-item list. */
1078
+ listComputers: (agentId: string, _filter?: {
841
1079
  sessionId?: string;
842
1080
  includeTerminated?: boolean;
843
1081
  }) => Promise<{
844
1082
  data: AgentComputerInstance[];
845
1083
  }>;
846
- startComputer: (agentId: string, params: {
1084
+ /** @deprecated Use wakeComputer. Lifecycle, name, and session are ignored. */
1085
+ startComputer: (agentId: string, params?: {
847
1086
  sessionId?: string;
848
1087
  lifecycle?: "persistent" | "ephemeral";
849
1088
  name?: string;
@@ -851,36 +1090,18 @@ declare class CommonsClient {
851
1090
  }) => Promise<{
852
1091
  data: AgentComputerInstance;
853
1092
  }>;
854
- getComputer: (agentId: string, computerId: string) => Promise<{
855
- data: AgentComputerInstance;
856
- }>;
857
- refreshComputer: (agentId: string, computerId: string) => Promise<{
1093
+ /** @deprecated Use getComputer. Computer IDs are ignored. */
1094
+ refreshComputer: (agentId: string, _computerId?: string) => Promise<{
858
1095
  data: AgentComputerInstance;
859
1096
  }>;
860
- stopComputer: (agentId: string, computerId: string) => Promise<{
1097
+ /** @deprecated Use sleepComputer. Computer IDs are ignored. */
1098
+ stopComputer: (agentId: string, _computerId?: string) => Promise<{
861
1099
  data: AgentComputerInstance;
862
1100
  }>;
863
- readComputerFile: (agentId: string, computerId: string, path: string) => Promise<{
864
- data: {
865
- path: string;
866
- content: string;
867
- };
868
- }>;
869
- runComputerCommand: (agentId: string, computerId: string, params: {
870
- command: string;
871
- cwd?: string;
872
- timeoutSeconds?: number;
873
- }) => Promise<{
1101
+ /** @deprecated Use execComputer. Computer IDs are ignored. */
1102
+ runComputerCommand: (agentId: string, paramsOrLegacyComputerId: ComputerCommandParams | string, legacyParams?: ComputerCommandParams) => Promise<{
874
1103
  data: any;
875
1104
  }>;
876
- openComputerBrowser: (agentId: string, computerId: string, params: {
877
- url: string;
878
- }) => Promise<{
879
- data: any;
880
- }>;
881
- listComputerEvents: (agentId: string, computerId: string, limit?: number) => Promise<{
882
- data: AgentComputerEvent[];
883
- }>;
884
1105
  /**
885
1106
  * List available TTS voices for a provider.
886
1107
  * @param provider - 'openai' (default) or 'elevenlabs'
@@ -1045,6 +1266,55 @@ declare class CommonsClient {
1045
1266
  data: Tool[];
1046
1267
  }>;
1047
1268
  };
1269
+ get oauth(): {
1270
+ /** List OAuth providers available on the platform (Google Workspace, GitHub, …). */
1271
+ listProviders: () => Promise<{
1272
+ providers: any[];
1273
+ }>;
1274
+ /** Get one provider's details, including its scope groups. */
1275
+ getProvider: (providerKey: string) => Promise<{
1276
+ provider: any;
1277
+ }>;
1278
+ /**
1279
+ * List the caller's OAuth connections (the accounts agents act with).
1280
+ * `ownerId` is only needed when authenticating with a management key.
1281
+ */
1282
+ listConnections: (params?: {
1283
+ ownerId?: string;
1284
+ ownerType?: "user" | "agent";
1285
+ }) => Promise<{
1286
+ connections: any[];
1287
+ }>;
1288
+ /**
1289
+ * Start an OAuth connect flow. Returns the authorization URL the user
1290
+ * must open in a browser to grant access.
1291
+ */
1292
+ connect: (params: {
1293
+ providerKey: string;
1294
+ scopes?: string[];
1295
+ redirectUri?: string;
1296
+ }) => Promise<{
1297
+ authorizationUrl: string;
1298
+ state: string;
1299
+ expiresAt: string;
1300
+ }>;
1301
+ /** Refresh a connection's access token now. */
1302
+ refresh: (connectionId: string) => Promise<{
1303
+ success: boolean;
1304
+ }>;
1305
+ /** Check whether a connection's token is valid. */
1306
+ test: (connectionId: string) => Promise<{
1307
+ success: boolean;
1308
+ status: string;
1309
+ accessTokenValid: boolean;
1310
+ providerUserEmail?: string;
1311
+ error?: string;
1312
+ }>;
1313
+ /** Revoke a connection and delete its tokens. */
1314
+ revoke: (connectionId: string) => Promise<{
1315
+ success: boolean;
1316
+ }>;
1317
+ };
1048
1318
  get toolKeys(): {
1049
1319
  list: (filter: {
1050
1320
  ownerId?: string;
@@ -1301,6 +1571,14 @@ declare class CommonsClient {
1301
1571
  }>;
1302
1572
  /** Soft-delete (deactivate) a memory. */
1303
1573
  delete: (memoryId: string) => Promise<void>;
1574
+ /** Create an append-only memory scope shared by a set of owned agents. */
1575
+ createSharedScope: (params: CreateSharedMemoryScopeParams) => Promise<{
1576
+ data: SharedMemoryScope;
1577
+ }>;
1578
+ /** List shared-memory scopes available to an agent. */
1579
+ listSharedScopes: (agentId: string) => Promise<{
1580
+ data: SharedMemoryScope[];
1581
+ }>;
1304
1582
  };
1305
1583
  get usage(): {
1306
1584
  /** Get aggregated token + cost usage for an agent. */
@@ -1379,4 +1657,4 @@ declare function listWorkflowTemplates(): readonly [{
1379
1657
  }];
1380
1658
  declare function buildWorkflowTemplate(templateName: WorkflowTemplateName, ctx: WorkflowTemplateContext): WorkflowTemplateBuild;
1381
1659
 
1382
- export { type A2AArtifact, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2AMessagePart, type A2ASendTaskParams, type A2ASkill, type A2ATask, type A2ATaskState, type A2ATextPart, type Agent, type AgentCard, type AgentMemory, type AgentWallet, type ApiKey, type ApiKeyPrincipalType, type ChatMessage, CommonsClient, type CommonsClientConfig, CommonsError, type CreateAgentParams, type CreateApiKeyParams, type CreateMemoryParams, type CreateSkillParams, type CreateTaskParams, type CreateToolKeyParams, type CreateToolParams, type CreateWalletParams, type CreatedApiKey, type McpConnectionType, type McpPrompt, type McpResource, type McpServer, type MemorySourceType, type MemoryStats, type MemoryType, type ModelConfig, type ModelProvider, type RunParams, type Session, type Skill, type SkillIndex, type StreamEvent, type StreamEventType, type Task, type Tool, type ToolKey, type ToolPermission, type UpdateMemoryParams, type UsageAggregation, type UsageEvent, type WalletBalance, type WalletType, type Workflow, type WorkflowDefinition, type WorkflowEdge, type WorkflowExecution, type WorkflowNode, type WorkflowNodeType, type WorkflowTemplateBuild, type WorkflowTemplateContext, type WorkflowTemplateName, type WorkflowTemplateTool, buildWorkflowTemplate, listWorkflowTemplates };
1660
+ export { type A2AArtifact, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2AMessagePart, type A2ASendTaskParams, type A2ASkill, type A2ATask, type A2ATaskState, type A2ATextPart, type Agent, type AgentCard, type AgentComputer, type AgentComputerBrowser, type AgentComputerConfig, type AgentComputerDesiredState, type AgentComputerEvent, type AgentComputerGpu, type AgentComputerGpuType, type AgentComputerInstance, type AgentComputerLifecycle, type AgentComputerResourceMode, type AgentComputerResourceProfile, type AgentComputerResources, type AgentComputerStatus, type AgentComputerTerminal, type AgentMemory, type AgentWallet, type ApiKey, type ApiKeyPrincipalType, type ChatMessage, CommonsClient, type CommonsClientConfig, CommonsError, type ComputerActionParams, type ComputerBrowserOpenParams, type ComputerCommandParams, type ComputerConfigUpdate, type ComputerFile, type ComputerGpu, type ComputerGpuType, type ComputerLifecycle, type ComputerNetworkAccess, type ComputerPersistence, type ComputerResizeParams, type ComputerResourceMode, type ComputerResourceProfile, type ComputerResourceUpdate, type ComputerResources, type CreateAgentParams, type CreateApiKeyParams, type CreateMemoryParams, type CreateSkillParams, type CreateTaskParams, type CreateToolKeyParams, type CreateToolParams, type CreateWalletParams, type CreatedApiKey, type McpConnectionType, type McpPrompt, type McpResource, type McpServer, type MemorySourceType, type MemoryStats, type MemoryType, type ModelConfig, type ModelProvider, type RunParams, type Session, type Skill, type SkillIndex, type StreamEvent, type StreamEventType, type Task, type Tool, type ToolKey, type ToolPermission, type UpdateMemoryParams, type UsageAggregation, type UsageEvent, type WalletBalance, type WalletType, type Workflow, type WorkflowDefinition, type WorkflowEdge, type WorkflowExecution, type WorkflowNode, type WorkflowNodeType, type WorkflowTemplateBuild, type WorkflowTemplateContext, type WorkflowTemplateName, type WorkflowTemplateTool, buildWorkflowTemplate, listWorkflowTemplates };