@agent-commons/sdk 0.3.0 → 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,18 +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' | 'run_started' | '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
364
  /** Identifies the run; pass to POST /v1/agents/runs/:runId/stream to resume a dropped stream. */
195
365
  runId?: string;
196
366
  /** Monotonic per-run sequence number; resume with `after: <last seen seq>` to avoid duplicates. */
197
367
  seq?: number;
198
- phase?: 'commentary' | 'final_answer' | string;
368
+ phase?: "commentary" | "final_answer" | string;
199
369
  role?: string;
200
370
  content?: string;
201
371
  stage?: string;
202
- status?: 'queued' | 'running' | 'completed' | 'failed' | string;
372
+ status?: "queued" | "running" | "completed" | "failed" | string;
203
373
  name?: string;
204
374
  toolName?: string;
205
375
  tool?: string;
@@ -221,7 +391,7 @@ interface Workflow {
221
391
  description?: string;
222
392
  definition: WorkflowDefinition;
223
393
  ownerId: string;
224
- ownerType: 'user' | 'agent';
394
+ ownerType: "user" | "agent";
225
395
  isPublic?: boolean;
226
396
  category?: string;
227
397
  tags?: string[];
@@ -234,7 +404,7 @@ interface WorkflowDefinition {
234
404
  edges: WorkflowEdge[];
235
405
  outputMapping?: Record<string, string>;
236
406
  }
237
- 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";
238
408
  interface WorkflowNode {
239
409
  id: string;
240
410
  type: WorkflowNodeType | string;
@@ -257,7 +427,7 @@ interface WorkflowEdge {
257
427
  interface WorkflowExecution {
258
428
  executionId: string;
259
429
  workflowId: string;
260
- status: 'running' | 'completed' | 'failed' | 'cancelled' | 'awaiting_approval';
430
+ status: "running" | "completed" | "failed" | "cancelled" | "awaiting_approval";
261
431
  startedAt?: string;
262
432
  completedAt?: string;
263
433
  outputData?: any;
@@ -274,8 +444,8 @@ interface Task {
274
444
  sessionId: string;
275
445
  title: string;
276
446
  description?: string;
277
- status: 'pending' | 'started' | 'running' | 'completed' | 'failed' | 'cancelled';
278
- executionMode: 'single' | 'workflow' | 'sequential';
447
+ status: "pending" | "started" | "running" | "completed" | "failed" | "cancelled";
448
+ executionMode: "single" | "workflow" | "sequential";
279
449
  workflowId?: string;
280
450
  cronExpression?: string;
281
451
  isRecurring?: boolean;
@@ -294,7 +464,7 @@ interface Task {
294
464
  summary?: string;
295
465
  errorMessage?: string;
296
466
  createdBy: string;
297
- createdByType: 'user' | 'agent';
467
+ createdByType: "user" | "agent";
298
468
  createdAt: string;
299
469
  updatedAt?: string;
300
470
  }
@@ -303,7 +473,7 @@ interface CreateTaskParams {
303
473
  sessionId: string;
304
474
  title: string;
305
475
  description?: string;
306
- executionMode?: 'single' | 'workflow' | 'sequential';
476
+ executionMode?: "single" | "workflow" | "sequential";
307
477
  workflowId?: string;
308
478
  workflowInputs?: Record<string, any>;
309
479
  cronExpression?: string;
@@ -311,13 +481,13 @@ interface CreateTaskParams {
311
481
  isRecurring?: boolean;
312
482
  dependsOn?: string[];
313
483
  tools?: string[];
314
- toolConstraintType?: 'hard' | 'soft' | 'none';
484
+ toolConstraintType?: "hard" | "soft" | "none";
315
485
  toolInstructions?: string;
316
486
  priority?: number;
317
487
  /** Max execution time in milliseconds for workflow tasks */
318
488
  timeoutMs?: number;
319
489
  createdBy: string;
320
- createdByType: 'user' | 'agent';
490
+ createdByType: "user" | "agent";
321
491
  }
322
492
  interface Tool {
323
493
  toolId: string;
@@ -338,15 +508,15 @@ interface CreateToolParams {
338
508
  apiSpec?: {
339
509
  baseUrl: string;
340
510
  path: string;
341
- method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | string;
511
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | string;
342
512
  headers?: Record<string, string>;
343
513
  queryParams?: Record<string, string>;
344
514
  bodyTemplate?: any;
345
- authType?: 'none' | 'bearer' | 'api-key' | 'basic' | 'oauth2' | string;
515
+ authType?: "none" | "bearer" | "api-key" | "basic" | "oauth2" | string;
346
516
  authKeyName?: string;
347
517
  oauthProviderKey?: string;
348
518
  oauthScopes?: string[];
349
- oauthTokenLocation?: 'header' | 'query' | 'body';
519
+ oauthTokenLocation?: "header" | "query" | "body";
350
520
  oauthTokenKey?: string;
351
521
  oauthTokenPrefix?: string;
352
522
  };
@@ -355,8 +525,8 @@ interface CreateToolParams {
355
525
  inputSchema?: any;
356
526
  outputSchema?: any;
357
527
  owner?: string;
358
- ownerType?: 'user' | 'agent';
359
- visibility?: 'private' | 'public' | 'platform';
528
+ ownerType?: "user" | "agent";
529
+ visibility?: "private" | "public" | "platform";
360
530
  tags?: string[];
361
531
  version?: string;
362
532
  rateLimitPerMinute?: number;
@@ -366,7 +536,7 @@ interface ToolKey {
366
536
  keyId: string;
367
537
  toolId?: string;
368
538
  ownerId: string;
369
- ownerType: 'user' | 'agent';
539
+ ownerType: "user" | "agent";
370
540
  keyName: string;
371
541
  displayName?: string;
372
542
  description?: string;
@@ -378,7 +548,7 @@ interface ToolKey {
378
548
  interface CreateToolKeyParams {
379
549
  toolId?: string;
380
550
  ownerId: string;
381
- ownerType: 'user' | 'agent';
551
+ ownerType: "user" | "agent";
382
552
  keyName: string;
383
553
  value: string;
384
554
  displayName?: string;
@@ -389,25 +559,25 @@ interface ToolPermission {
389
559
  id: string;
390
560
  toolId: string;
391
561
  subjectId: string;
392
- subjectType: 'user' | 'agent';
393
- permission: 'read' | 'execute' | 'admin';
562
+ subjectType: "user" | "agent";
563
+ permission: "read" | "execute" | "admin";
394
564
  grantedBy?: string;
395
565
  createdAt: string;
396
566
  expiresAt?: string;
397
567
  }
398
- type A2ATaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
568
+ type A2ATaskState = "submitted" | "working" | "input-required" | "completed" | "failed" | "canceled";
399
569
  interface A2ATextPart {
400
- type: 'text';
570
+ type: "text";
401
571
  text: string;
402
572
  metadata?: Record<string, any>;
403
573
  }
404
574
  interface A2ADataPart {
405
- type: 'data';
575
+ type: "data";
406
576
  data: Record<string, any>;
407
577
  metadata?: Record<string, any>;
408
578
  }
409
579
  interface A2AFilePart {
410
- type: 'file';
580
+ type: "file";
411
581
  file: {
412
582
  name?: string;
413
583
  mimeType?: string;
@@ -418,7 +588,7 @@ interface A2AFilePart {
418
588
  }
419
589
  type A2AMessagePart = A2ATextPart | A2ADataPart | A2AFilePart;
420
590
  interface A2AMessage {
421
- role: 'user' | 'agent';
591
+ role: "user" | "agent";
422
592
  parts: A2AMessagePart[];
423
593
  contextId?: string;
424
594
  messageId?: string;
@@ -476,19 +646,19 @@ interface A2ASendTaskParams {
476
646
  token?: string;
477
647
  };
478
648
  }
479
- type McpConnectionType = 'stdio' | 'sse' | 'http' | 'streamable-http';
649
+ type McpConnectionType = "stdio" | "sse" | "http" | "streamable-http";
480
650
  interface McpServer {
481
651
  serverId: string;
482
652
  name: string;
483
653
  description?: string;
484
654
  connectionType: McpConnectionType;
485
655
  connectionConfig: Record<string, any>;
486
- status: 'connected' | 'disconnected' | 'error';
656
+ status: "connected" | "disconnected" | "error";
487
657
  toolsCount: number;
488
658
  capabilities?: Record<string, any>;
489
659
  isPublic: boolean;
490
660
  ownerId: string;
491
- ownerType: 'user' | 'agent';
661
+ ownerType: "user" | "agent";
492
662
  createdAt: string;
493
663
  }
494
664
  interface McpResource {
@@ -552,15 +722,15 @@ interface CreateSkillParams {
552
722
  tools?: string[];
553
723
  triggers?: string[];
554
724
  ownerId?: string;
555
- ownerType?: 'platform' | 'user' | 'agent';
725
+ ownerType?: "platform" | "user" | "agent";
556
726
  isPublic?: boolean;
557
727
  tags?: string[];
558
728
  icon?: string;
559
729
  source?: string;
560
730
  sourceUrl?: string;
561
731
  }
562
- type MemoryType = 'episodic' | 'semantic' | 'procedural';
563
- type MemorySourceType = 'auto' | 'manual';
732
+ type MemoryType = "episodic" | "semantic" | "procedural";
733
+ type MemorySourceType = "auto" | "manual";
564
734
  interface AgentMemory {
565
735
  memoryId: string;
566
736
  agentId: string;
@@ -602,6 +772,18 @@ interface UpdateMemoryParams {
602
772
  isActive?: boolean;
603
773
  memoryType?: MemoryType;
604
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
+ }
605
787
  interface UsageEvent {
606
788
  eventId: string;
607
789
  agentId: string;
@@ -629,15 +811,15 @@ interface UsageAggregation {
629
811
  callCount: number;
630
812
  events: UsageEvent[];
631
813
  }
632
- type CreditDirection = 'grant' | 'debit' | 'adjustment' | 'refund' | 'expiration';
633
- 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";
634
816
  interface CreditLedgerEntry {
635
817
  entryId: string;
636
818
  principalId: string;
637
- principalType: 'user' | 'agent' | 'service';
819
+ principalType: "user" | "agent" | "service";
638
820
  workspaceId?: string | null;
639
821
  amount: number;
640
- currency: 'credits';
822
+ currency: "credits";
641
823
  direction: CreditDirection;
642
824
  eventType: string;
643
825
  sourcePlatform: CreditPlatform;
@@ -661,11 +843,11 @@ interface CreditBalance {
661
843
  principalId: string;
662
844
  workspaceId?: string | null;
663
845
  balance: number;
664
- currency: 'credits';
846
+ currency: "credits";
665
847
  }
666
848
  interface CreditWriteParams {
667
849
  principalId: string;
668
- principalType?: 'user' | 'agent' | 'service';
850
+ principalType?: "user" | "agent" | "service";
669
851
  workspaceId?: string | null;
670
852
  amount: number;
671
853
  eventType: string;
@@ -681,7 +863,7 @@ interface CreditWriteParams {
681
863
  usageEventId?: string;
682
864
  metadata?: Record<string, unknown>;
683
865
  }
684
- type WalletType = 'eoa' | 'erc4337' | 'external';
866
+ type WalletType = "eoa" | "erc4337" | "external";
685
867
  interface AgentWallet {
686
868
  id: string;
687
869
  agentId: string;
@@ -707,7 +889,7 @@ interface CreateWalletParams {
707
889
  externalAddress?: string;
708
890
  chainId?: string;
709
891
  }
710
- type ApiKeyPrincipalType = 'user' | 'agent';
892
+ type ApiKeyPrincipalType = "user" | "agent";
711
893
  interface ApiKey {
712
894
  id: string;
713
895
  label?: string | null;
@@ -755,6 +937,26 @@ declare class CommonsClient {
755
937
  update: (agentId: string, params: Partial<CreateAgentParams>) => Promise<{
756
938
  data: Agent;
757
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
+ }>;
758
960
  /** List tools assigned to an agent. */
759
961
  listTools: (agentId: string) => Promise<{
760
962
  data: any[];
@@ -838,16 +1040,49 @@ declare class CommonsClient {
838
1040
  getComputerConfig: (agentId: string) => Promise<{
839
1041
  data: AgentComputerConfig;
840
1042
  }>;
841
- updateComputerConfig: (agentId: string, params: Partial<AgentComputerConfig>) => Promise<{
1043
+ updateComputerConfig: (agentId: string, params: ComputerConfigUpdate) => Promise<{
842
1044
  data: AgentComputerConfig;
843
1045
  }>;
844
- 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?: {
845
1079
  sessionId?: string;
846
1080
  includeTerminated?: boolean;
847
1081
  }) => Promise<{
848
1082
  data: AgentComputerInstance[];
849
1083
  }>;
850
- startComputer: (agentId: string, params: {
1084
+ /** @deprecated Use wakeComputer. Lifecycle, name, and session are ignored. */
1085
+ startComputer: (agentId: string, params?: {
851
1086
  sessionId?: string;
852
1087
  lifecycle?: "persistent" | "ephemeral";
853
1088
  name?: string;
@@ -855,36 +1090,18 @@ declare class CommonsClient {
855
1090
  }) => Promise<{
856
1091
  data: AgentComputerInstance;
857
1092
  }>;
858
- getComputer: (agentId: string, computerId: string) => Promise<{
859
- data: AgentComputerInstance;
860
- }>;
861
- refreshComputer: (agentId: string, computerId: string) => Promise<{
1093
+ /** @deprecated Use getComputer. Computer IDs are ignored. */
1094
+ refreshComputer: (agentId: string, _computerId?: string) => Promise<{
862
1095
  data: AgentComputerInstance;
863
1096
  }>;
864
- stopComputer: (agentId: string, computerId: string) => Promise<{
1097
+ /** @deprecated Use sleepComputer. Computer IDs are ignored. */
1098
+ stopComputer: (agentId: string, _computerId?: string) => Promise<{
865
1099
  data: AgentComputerInstance;
866
1100
  }>;
867
- readComputerFile: (agentId: string, computerId: string, path: string) => Promise<{
868
- data: {
869
- path: string;
870
- content: string;
871
- };
872
- }>;
873
- runComputerCommand: (agentId: string, computerId: string, params: {
874
- command: string;
875
- cwd?: string;
876
- timeoutSeconds?: number;
877
- }) => Promise<{
1101
+ /** @deprecated Use execComputer. Computer IDs are ignored. */
1102
+ runComputerCommand: (agentId: string, paramsOrLegacyComputerId: ComputerCommandParams | string, legacyParams?: ComputerCommandParams) => Promise<{
878
1103
  data: any;
879
1104
  }>;
880
- openComputerBrowser: (agentId: string, computerId: string, params: {
881
- url: string;
882
- }) => Promise<{
883
- data: any;
884
- }>;
885
- listComputerEvents: (agentId: string, computerId: string, limit?: number) => Promise<{
886
- data: AgentComputerEvent[];
887
- }>;
888
1105
  /**
889
1106
  * List available TTS voices for a provider.
890
1107
  * @param provider - 'openai' (default) or 'elevenlabs'
@@ -1049,6 +1266,55 @@ declare class CommonsClient {
1049
1266
  data: Tool[];
1050
1267
  }>;
1051
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
+ };
1052
1318
  get toolKeys(): {
1053
1319
  list: (filter: {
1054
1320
  ownerId?: string;
@@ -1305,6 +1571,14 @@ declare class CommonsClient {
1305
1571
  }>;
1306
1572
  /** Soft-delete (deactivate) a memory. */
1307
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
+ }>;
1308
1582
  };
1309
1583
  get usage(): {
1310
1584
  /** Get aggregated token + cost usage for an agent. */
@@ -1383,4 +1657,4 @@ declare function listWorkflowTemplates(): readonly [{
1383
1657
  }];
1384
1658
  declare function buildWorkflowTemplate(templateName: WorkflowTemplateName, ctx: WorkflowTemplateContext): WorkflowTemplateBuild;
1385
1659
 
1386
- 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 };