@agent-commons/sdk 0.2.1 → 0.2.3

package/dist/index.d.mts

@@ -7,6 +7,8 @@ interface ModelConfig {
     temperature?: number;
     maxTokens?: number;
     topP?: number;
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    verbosity?: 'low' | 'medium' | 'high';
 }
 interface Agent {
     agentId: string;
@@ -30,6 +32,91 @@ interface Agent {
     externalUrl?: string;
     createdAt: string;
 }
+type AgentComputerLifecycle = 'persistent' | 'ephemeral';
+type AgentComputerStatus = 'provisioning' | 'starting' | 'running' | 'idle' | 'stopping' | 'stopped' | 'terminated' | 'failed' | 'error' | 'unavailable';
+interface AgentComputerConfig {
+    configId: string;
+    agentId: string;
+    enabled: boolean;
+    defaultMode: AgentComputerLifecycle;
+    autoStart: boolean;
+    allowAgentStart: boolean;
+    allowUserSelect: boolean;
+    allowBrowser: boolean;
+    allowTerminal: boolean;
+    allowFilesystem: boolean;
+    networkAccess: 'standard' | 'restricted' | 'disabled' | string;
+    maxPersistentComputers: number;
+    maxEphemeralComputers: number;
+    maxConcurrentComputers: number;
+    idleTtlMinutes: number;
+    sessionTtlMinutes: number;
+    image?: string | null;
+    cpuLimit?: string | null;
+    memoryLimit?: string | null;
+    storageLimit?: string | null;
+    region?: string | null;
+    provider: string;
+    metadata?: Record<string, any> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentComputerInstance {
+    computerId: string;
+    agentId: string;
+    sessionId?: string | null;
+    ownerUserId?: string | null;
+    workspaceId?: string | null;
+    name: string;
+    lifecycle: AgentComputerLifecycle;
+    status: AgentComputerStatus;
+    provider: string;
+    cloudProvider?: string | null;
+    region?: string | null;
+    namespaceId?: string | null;
+    podName?: string | null;
+    image?: string | null;
+    cpuLimit?: string | null;
+    memoryLimit?: string | null;
+    storageLimit?: string | null;
+    workspaceRoot?: string | null;
+    workspaceSnapshot?: string | null;
+    browser?: {
+        status?: 'off' | 'starting' | 'on' | 'error';
+        url?: string | null;
+        title?: string | null;
+        screenshot?: string | null;
+        lastAction?: string | null;
+        error?: string | null;
+        updatedAt?: string | null;
+    } | null;
+    terminal?: {
+        lastCommand?: string | null;
+        lastExitCode?: number | null;
+        lastOutput?: string | null;
+        updatedAt?: string | null;
+    } | null;
+    metadata?: Record<string, any> | null;
+    lastActivityAt?: string | null;
+    expiresAt?: string | null;
+    startedAt?: string | null;
+    stoppedAt?: string | null;
+    errorMessage?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentComputerEvent {
+    eventId: string;
+    computerId: string;
+    agentId: string;
+    sessionId?: string | null;
+    eventType: string;
+    actorType: string;
+    actorId?: string | null;
+    summary?: string | null;
+    payload?: Record<string, any> | null;
+    createdAt: string;
+}
 interface CreateAgentParams {
     name: string;
     instructions?: string;
@@ -69,6 +156,15 @@ interface RunParams {
     messages: ChatMessage[];
     sessionId?: string;
     initiatorId?: string;
+    computerRequest?: {
+        enabled: boolean;
+        computerIds?: string[];
+        lifecycle?: AgentComputerLifecycle;
+    };
+    /** Uploaded file references. Raw file bytes must be uploaded separately. */
+    attachments?: Array<{
+        fileId: string;
+    }>;
     /** Extra text injected into the agent's system prompt. Used by the CLI to deliver the local tools manifest. */
     cliContext?: string;
     /** Caller-owned function catalog executed through cli_tool_request events. */
@@ -80,21 +176,40 @@ interface RunParams {
 }
 interface ChatMessage {
     role: 'user' | 'assistant' | 'system' | 'tool';
-    content: string;
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image_url';
+        image_url: {
+            url: string;
+        };
+    } | Record<string, any>>;
     tool_call_id?: string;
     name?: string;
 }
-type StreamEventType = 'token' | 'toolStart' | 'toolEnd' | 'agent_step' | 'final' | 'completed' | 'failed' | 'cancelled' | 'status' | 'keepalive' | 'cli_tool_request' | 'error';
+type StreamEventType = 'token' | 'tool' | 'toolProgress' | 'toolStart' | 'toolEnd' | 'agent_step' | 'final' | 'completed' | 'failed' | 'cancelled' | 'status' | 'keepalive' | 'cli_tool_request' | 'error';
 interface StreamEvent {
     type: StreamEventType;
+    phase?: 'commentary' | 'final_answer' | string;
     role?: string;
     content?: string;
+    stage?: string;
+    status?: 'queued' | 'running' | 'completed' | 'failed' | string;
+    name?: string;
     toolName?: string;
+    tool?: string;
+    toolCallId?: string;
     input?: string;
+    args?: any;
     output?: any;
+    result?: any;
+    requestId?: string;
     timestamp?: string;
+    sessionId?: string;
     payload?: any;
     message?: string;
+    detail?: string;
 }
 interface Workflow {
     workflowId: string;
@@ -160,6 +275,14 @@ interface Task {
     workflowId?: string;
     cronExpression?: string;
     isRecurring?: boolean;
+    scheduledFor?: string;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    actualStart?: string;
+    actualEnd?: string;
+    estimatedDuration?: number;
+    dependsOn?: string[];
+    metadata?: Record<string, any>;
     priority?: number;
     timeoutMs?: number;
     progress?: number;
@@ -169,6 +292,7 @@ interface Task {
     createdBy: string;
     createdByType: 'user' | 'agent';
     createdAt: string;
+    updatedAt?: string;
 }
 interface CreateTaskParams {
     agentId: string;
@@ -707,6 +831,56 @@ declare class CommonsClient {
         removePreferredConnection: (id: string) => Promise<{
             success: boolean;
         }>;
+        getComputerConfig: (agentId: string) => Promise<{
+            data: AgentComputerConfig;
+        }>;
+        updateComputerConfig: (agentId: string, params: Partial<AgentComputerConfig>) => Promise<{
+            data: AgentComputerConfig;
+        }>;
+        listComputers: (agentId: string, filter?: {
+            sessionId?: string;
+            includeTerminated?: boolean;
+        }) => Promise<{
+            data: AgentComputerInstance[];
+        }>;
+        startComputer: (agentId: string, params: {
+            sessionId?: string;
+            lifecycle?: "persistent" | "ephemeral";
+            name?: string;
+            reason?: string;
+        }) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        getComputer: (agentId: string, computerId: string) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        refreshComputer: (agentId: string, computerId: string) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        stopComputer: (agentId: string, computerId: string) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        readComputerFile: (agentId: string, computerId: string, path: string) => Promise<{
+            data: {
+                path: string;
+                content: string;
+            };
+        }>;
+        runComputerCommand: (agentId: string, computerId: string, params: {
+            command: string;
+            cwd?: string;
+            timeoutSeconds?: number;
+        }) => Promise<{
+            data: any;
+        }>;
+        openComputerBrowser: (agentId: string, computerId: string, params: {
+            url: string;
+        }) => Promise<{
+            data: any;
+        }>;
+        listComputerEvents: (agentId: string, computerId: string, limit?: number) => Promise<{
+            data: AgentComputerEvent[];
+        }>;
         /**
          * List available TTS voices for a provider.
          * @param provider - 'openai' (default) or 'elevenlabs'
@@ -793,6 +967,25 @@ declare class CommonsClient {
         delete: (taskId: string) => Promise<{
             success: boolean;
         }>;
+        /** Edit human-facing task details (title/description/priority). */
+        update: (taskId: string, params: {
+            title?: string;
+            description?: string;
+            priority?: number;
+        }) => Promise<{
+            data: Task;
+        }>;
+        /** Reschedule a task's upcoming run and/or resize its estimated duration. */
+        reschedule: (taskId: string, params: {
+            scheduledFor?: Date;
+            estimatedDuration?: number;
+        }) => Promise<{
+            data: Task;
+            rescheduledRun: {
+                runId: string;
+                created: boolean;
+            } | null;
+        }>;
         /** Stream task status updates via SSE. Returns an async generator. */
         stream: (taskId: string) => AsyncGenerator<StreamEvent>;
     };

package/dist/index.d.ts

@@ -7,6 +7,8 @@ interface ModelConfig {
     temperature?: number;
     maxTokens?: number;
     topP?: number;
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    verbosity?: 'low' | 'medium' | 'high';
 }
 interface Agent {
     agentId: string;
@@ -30,6 +32,91 @@ interface Agent {
     externalUrl?: string;
     createdAt: string;
 }
+type AgentComputerLifecycle = 'persistent' | 'ephemeral';
+type AgentComputerStatus = 'provisioning' | 'starting' | 'running' | 'idle' | 'stopping' | 'stopped' | 'terminated' | 'failed' | 'error' | 'unavailable';
+interface AgentComputerConfig {
+    configId: string;
+    agentId: string;
+    enabled: boolean;
+    defaultMode: AgentComputerLifecycle;
+    autoStart: boolean;
+    allowAgentStart: boolean;
+    allowUserSelect: boolean;
+    allowBrowser: boolean;
+    allowTerminal: boolean;
+    allowFilesystem: boolean;
+    networkAccess: 'standard' | 'restricted' | 'disabled' | string;
+    maxPersistentComputers: number;
+    maxEphemeralComputers: number;
+    maxConcurrentComputers: number;
+    idleTtlMinutes: number;
+    sessionTtlMinutes: number;
+    image?: string | null;
+    cpuLimit?: string | null;
+    memoryLimit?: string | null;
+    storageLimit?: string | null;
+    region?: string | null;
+    provider: string;
+    metadata?: Record<string, any> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentComputerInstance {
+    computerId: string;
+    agentId: string;
+    sessionId?: string | null;
+    ownerUserId?: string | null;
+    workspaceId?: string | null;
+    name: string;
+    lifecycle: AgentComputerLifecycle;
+    status: AgentComputerStatus;
+    provider: string;
+    cloudProvider?: string | null;
+    region?: string | null;
+    namespaceId?: string | null;
+    podName?: string | null;
+    image?: string | null;
+    cpuLimit?: string | null;
+    memoryLimit?: string | null;
+    storageLimit?: string | null;
+    workspaceRoot?: string | null;
+    workspaceSnapshot?: string | null;
+    browser?: {
+        status?: 'off' | 'starting' | 'on' | 'error';
+        url?: string | null;
+        title?: string | null;
+        screenshot?: string | null;
+        lastAction?: string | null;
+        error?: string | null;
+        updatedAt?: string | null;
+    } | null;
+    terminal?: {
+        lastCommand?: string | null;
+        lastExitCode?: number | null;
+        lastOutput?: string | null;
+        updatedAt?: string | null;
+    } | null;
+    metadata?: Record<string, any> | null;
+    lastActivityAt?: string | null;
+    expiresAt?: string | null;
+    startedAt?: string | null;
+    stoppedAt?: string | null;
+    errorMessage?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentComputerEvent {
+    eventId: string;
+    computerId: string;
+    agentId: string;
+    sessionId?: string | null;
+    eventType: string;
+    actorType: string;
+    actorId?: string | null;
+    summary?: string | null;
+    payload?: Record<string, any> | null;
+    createdAt: string;
+}
 interface CreateAgentParams {
     name: string;
     instructions?: string;
@@ -69,6 +156,15 @@ interface RunParams {
     messages: ChatMessage[];
     sessionId?: string;
     initiatorId?: string;
+    computerRequest?: {
+        enabled: boolean;
+        computerIds?: string[];
+        lifecycle?: AgentComputerLifecycle;
+    };
+    /** Uploaded file references. Raw file bytes must be uploaded separately. */
+    attachments?: Array<{
+        fileId: string;
+    }>;
     /** Extra text injected into the agent's system prompt. Used by the CLI to deliver the local tools manifest. */
     cliContext?: string;
     /** Caller-owned function catalog executed through cli_tool_request events. */
@@ -80,21 +176,40 @@ interface RunParams {
 }
 interface ChatMessage {
     role: 'user' | 'assistant' | 'system' | 'tool';
-    content: string;
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image_url';
+        image_url: {
+            url: string;
+        };
+    } | Record<string, any>>;
     tool_call_id?: string;
     name?: string;
 }
-type StreamEventType = 'token' | 'toolStart' | 'toolEnd' | 'agent_step' | 'final' | 'completed' | 'failed' | 'cancelled' | 'status' | 'keepalive' | 'cli_tool_request' | 'error';
+type StreamEventType = 'token' | 'tool' | 'toolProgress' | 'toolStart' | 'toolEnd' | 'agent_step' | 'final' | 'completed' | 'failed' | 'cancelled' | 'status' | 'keepalive' | 'cli_tool_request' | 'error';
 interface StreamEvent {
     type: StreamEventType;
+    phase?: 'commentary' | 'final_answer' | string;
     role?: string;
     content?: string;
+    stage?: string;
+    status?: 'queued' | 'running' | 'completed' | 'failed' | string;
+    name?: string;
     toolName?: string;
+    tool?: string;
+    toolCallId?: string;
     input?: string;
+    args?: any;
     output?: any;
+    result?: any;
+    requestId?: string;
     timestamp?: string;
+    sessionId?: string;
     payload?: any;
     message?: string;
+    detail?: string;
 }
 interface Workflow {
     workflowId: string;
@@ -160,6 +275,14 @@ interface Task {
     workflowId?: string;
     cronExpression?: string;
     isRecurring?: boolean;
+    scheduledFor?: string;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    actualStart?: string;
+    actualEnd?: string;
+    estimatedDuration?: number;
+    dependsOn?: string[];
+    metadata?: Record<string, any>;
     priority?: number;
     timeoutMs?: number;
     progress?: number;
@@ -169,6 +292,7 @@ interface Task {
     createdBy: string;
     createdByType: 'user' | 'agent';
     createdAt: string;
+    updatedAt?: string;
 }
 interface CreateTaskParams {
     agentId: string;
@@ -707,6 +831,56 @@ declare class CommonsClient {
         removePreferredConnection: (id: string) => Promise<{
             success: boolean;
         }>;
+        getComputerConfig: (agentId: string) => Promise<{
+            data: AgentComputerConfig;
+        }>;
+        updateComputerConfig: (agentId: string, params: Partial<AgentComputerConfig>) => Promise<{
+            data: AgentComputerConfig;
+        }>;
+        listComputers: (agentId: string, filter?: {
+            sessionId?: string;
+            includeTerminated?: boolean;
+        }) => Promise<{
+            data: AgentComputerInstance[];
+        }>;
+        startComputer: (agentId: string, params: {
+            sessionId?: string;
+            lifecycle?: "persistent" | "ephemeral";
+            name?: string;
+            reason?: string;
+        }) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        getComputer: (agentId: string, computerId: string) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        refreshComputer: (agentId: string, computerId: string) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        stopComputer: (agentId: string, computerId: string) => Promise<{
+            data: AgentComputerInstance;
+        }>;
+        readComputerFile: (agentId: string, computerId: string, path: string) => Promise<{
+            data: {
+                path: string;
+                content: string;
+            };
+        }>;
+        runComputerCommand: (agentId: string, computerId: string, params: {
+            command: string;
+            cwd?: string;
+            timeoutSeconds?: number;
+        }) => Promise<{
+            data: any;
+        }>;
+        openComputerBrowser: (agentId: string, computerId: string, params: {
+            url: string;
+        }) => Promise<{
+            data: any;
+        }>;
+        listComputerEvents: (agentId: string, computerId: string, limit?: number) => Promise<{
+            data: AgentComputerEvent[];
+        }>;
         /**
          * List available TTS voices for a provider.
          * @param provider - 'openai' (default) or 'elevenlabs'
@@ -793,6 +967,25 @@ declare class CommonsClient {
         delete: (taskId: string) => Promise<{
             success: boolean;
         }>;
+        /** Edit human-facing task details (title/description/priority). */
+        update: (taskId: string, params: {
+            title?: string;
+            description?: string;
+            priority?: number;
+        }) => Promise<{
+            data: Task;
+        }>;
+        /** Reschedule a task's upcoming run and/or resize its estimated duration. */
+        reschedule: (taskId: string, params: {
+            scheduledFor?: Date;
+            estimatedDuration?: number;
+        }) => Promise<{
+            data: Task;
+            rescheduledRun: {
+                runId: string;
+                created: boolean;
+            } | null;
+        }>;
         /** Stream task status updates via SSE. Returns an async generator. */
         stream: (taskId: string) => AsyncGenerator<StreamEvent>;
     };

package/dist/index.mjs

@@ -81,6 +81,24 @@ var CommonsClient = class {
       addPreferredConnection: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/preferred-connections`, params),
       /** Remove a preferred agent connection by its record ID. */
       removePreferredConnection: (id) => this.request("DELETE", `/v1/agents/preferred-connections/${id}`),
+      // ── Computers ────────────────────────────────────────────────────────
+      getComputerConfig: (agentId) => this.request("GET", `/v1/agents/${agentId}/computer/config`),
+      updateComputerConfig: (agentId, params) => this.request("PUT", `/v1/agents/${agentId}/computer/config`, params),
+      listComputers: (agentId, filter) => {
+        const qs = new URLSearchParams();
+        if (filter?.sessionId) qs.set("sessionId", filter.sessionId);
+        if (filter?.includeTerminated) qs.set("includeTerminated", "true");
+        const query = qs.toString();
+        return this.request("GET", `/v1/agents/${agentId}/computers${query ? `?${query}` : ""}`);
+      },
+      startComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computers`, params),
+      getComputer: (agentId, computerId) => this.request("GET", `/v1/agents/${agentId}/computers/${computerId}`),
+      refreshComputer: (agentId, computerId) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/refresh`),
+      stopComputer: (agentId, computerId) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/stop`),
+      readComputerFile: (agentId, computerId, path) => this.request("GET", `/v1/agents/${agentId}/computers/${computerId}/files/read?path=${encodeURIComponent(path)}`),
+      runComputerCommand: (agentId, computerId, params) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/commands`, params),
+      openComputerBrowser: (agentId, computerId, params) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/browser/open`, params),
+      listComputerEvents: (agentId, computerId, limit) => this.request("GET", `/v1/agents/${agentId}/computers/${computerId}/events${limit ? `?limit=${limit}` : ""}`),
       // ── TTS Voices ───────────────────────────────────────────────────────
       /**
        * List available TTS voices for a provider.
@@ -134,6 +152,10 @@ var CommonsClient = class {
       execute: (taskId) => this.request("POST", `/v1/tasks/${taskId}/execute`),
       cancel: (taskId) => this.request("POST", `/v1/tasks/${taskId}/cancel`),
       delete: (taskId) => this.request("DELETE", `/v1/tasks/${taskId}`),
+      /** Edit human-facing task details (title/description/priority). */
+      update: (taskId, params) => this.request("PATCH", `/v1/tasks/${taskId}`, params),
+      /** Reschedule a task's upcoming run and/or resize its estimated duration. */
+      reschedule: (taskId, params) => this.request("PATCH", `/v1/tasks/${taskId}/schedule`, params),
       /** Stream task status updates via SSE. Returns an async generator. */
       stream: (taskId) => this._streamSse(`/v1/tasks/${taskId}/stream`)
     };