@agent-commons/sdk 0.2.0 → 0.2.2

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;
@@ -14,6 +16,8 @@ interface Agent {
     owner?: string;
     instructions?: string;
     persona?: string;
+    greeting?: string;
+    conversationStarters?: string[];
     avatar?: string;
     modelProvider: ModelProvider;
     modelId: string;
@@ -28,11 +32,101 @@ 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;
     persona?: string;
+    greeting?: string;
+    conversationStarters?: string[];
     owner?: string;
+    ownerUserId?: string;
+    workspaceId?: string | null;
+    metadata?: Record<string, unknown>;
     modelProvider?: ModelProvider;
     modelId?: string;
     modelApiKey?: string;
@@ -62,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. */
@@ -73,21 +176,39 @@ 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' | '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;
     input?: string;
+    args?: any;
     output?: any;
+    result?: any;
+    requestId?: string;
     timestamp?: string;
+    sessionId?: string;
     payload?: any;
     message?: string;
+    detail?: string;
 }
 interface Workflow {
     workflowId: string;
@@ -102,11 +223,13 @@ interface Workflow {
     createdAt: string;
 }
 interface WorkflowDefinition {
+    startNodeId?: string;
+    endNodeId?: string;
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
     outputMapping?: Record<string, string>;
 }
-type WorkflowNodeType = 'tool' | 'input' | 'output' | 'condition' | 'transform' | 'loop' | 'agent_processor' | 'human_approval';
+type WorkflowNodeType = 'tool' | 'input' | 'output' | 'condition' | 'transform' | 'loop' | 'agent_processor' | 'workflow' | 'human_approval';
 interface WorkflowNode {
     id: string;
     type: WorkflowNodeType | string;
@@ -198,10 +321,32 @@ interface CreateToolParams {
     displayName?: string;
     description?: string;
     schema: any;
+    apiSpec?: {
+        baseUrl: string;
+        path: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | string;
+        headers?: Record<string, string>;
+        queryParams?: Record<string, string>;
+        bodyTemplate?: any;
+        authType?: 'none' | 'bearer' | 'api-key' | 'basic' | 'oauth2' | string;
+        authKeyName?: string;
+        oauthProviderKey?: string;
+        oauthScopes?: string[];
+        oauthTokenLocation?: 'header' | 'query' | 'body';
+        oauthTokenKey?: string;
+        oauthTokenPrefix?: string;
+    };
+    category?: string;
+    icon?: string;
+    inputSchema?: any;
+    outputSchema?: any;
     owner?: string;
     ownerType?: 'user' | 'agent';
     visibility?: 'private' | 'public' | 'platform';
     tags?: string[];
+    version?: string;
+    rateLimitPerMinute?: number;
+    rateLimitPerHour?: number;
 }
 interface ToolKey {
     keyId: string;
@@ -348,7 +493,8 @@ interface McpPrompt {
     }>;
 }
 interface CommonsClientConfig {
-    baseUrl: string;
+    /** Defaults to the unified Commons API platform. */
+    baseUrl?: string;
     apiKey?: string;
     initiator?: string;
     /** Fetch implementation — defaults to global fetch */
@@ -469,6 +615,58 @@ interface UsageAggregation {
     callCount: number;
     events: UsageEvent[];
 }
+type CreditDirection = 'grant' | 'debit' | 'adjustment' | 'refund' | 'expiration';
+type CreditPlatform = 'agent_commons' | 'commonlab' | 'common_os' | 'system';
+interface CreditLedgerEntry {
+    entryId: string;
+    principalId: string;
+    principalType: 'user' | 'agent' | 'service';
+    workspaceId?: string | null;
+    amount: number;
+    currency: 'credits';
+    direction: CreditDirection;
+    eventType: string;
+    sourcePlatform: CreditPlatform;
+    idempotencyKey: string;
+    description?: string | null;
+    relatedCourseId?: string | null;
+    relatedChallengeId?: string | null;
+    agentId?: string | null;
+    sessionId?: string | null;
+    taskId?: string | null;
+    workflowId?: string | null;
+    usageEventId?: string | null;
+    metadata?: Record<string, unknown>;
+    createdBy?: string | null;
+    createdByType?: string | null;
+    expiresAt?: string | null;
+    voidedAt?: string | null;
+    createdAt: string;
+}
+interface CreditBalance {
+    principalId: string;
+    workspaceId?: string | null;
+    balance: number;
+    currency: 'credits';
+}
+interface CreditWriteParams {
+    principalId: string;
+    principalType?: 'user' | 'agent' | 'service';
+    workspaceId?: string | null;
+    amount: number;
+    eventType: string;
+    sourcePlatform: CreditPlatform;
+    idempotencyKey: string;
+    description?: string;
+    relatedCourseId?: string;
+    relatedChallengeId?: string;
+    agentId?: string;
+    sessionId?: string;
+    taskId?: string;
+    workflowId?: string;
+    usageEventId?: string;
+    metadata?: Record<string, unknown>;
+}
 type WalletType = 'eoa' | 'erc4337' | 'external';
 interface AgentWallet {
     id: string;
@@ -623,6 +821,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'
@@ -1038,6 +1286,27 @@ declare class CommonsClient {
             data: UsageAggregation;
         }>;
     };
+    get credits(): {
+        balance: (filter?: {
+            principalId?: string;
+            workspaceId?: string;
+        }) => Promise<{
+            data: CreditBalance;
+        }>;
+        ledger: (filter?: {
+            principalId?: string;
+            workspaceId?: string;
+            limit?: number;
+        }) => Promise<{
+            data: CreditLedgerEntry[];
+        }>;
+        grant: (params: CreditWriteParams) => Promise<{
+            data: CreditLedgerEntry;
+        }>;
+        debit: (params: CreditWriteParams) => Promise<{
+            data: CreditLedgerEntry;
+        }>;
+    };
 }
 declare class CommonsError extends Error {
     readonly status: number;
@@ -1045,4 +1314,40 @@ declare class CommonsError extends Error {
     constructor(message: string, status: number, data?: unknown | undefined);
 }
 
-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 WorkflowTemplateName = 'country-weather-brief' | 'agent-research-summary' | 'multi-agent-field-report' | 'workflow-invocation-smoke';
+interface WorkflowTemplateContext {
+    ownerId: string;
+    prefix: string;
+    agentId?: string;
+    reviewerAgentId?: string;
+    childWorkflowId?: string;
+}
+interface WorkflowTemplateTool {
+    key: string;
+    payload: CreateToolParams;
+}
+interface WorkflowTemplateBuild {
+    name: string;
+    description: string;
+    tags: string[];
+    category: string;
+    tools: WorkflowTemplateTool[];
+    buildDefinition: (toolIds: Record<string, string>, ctx: WorkflowTemplateContext) => WorkflowDefinition;
+    sampleInput: Record<string, any>;
+}
+declare function listWorkflowTemplates(): readonly [{
+    readonly name: "country-weather-brief";
+    readonly description: "Tool-only workflow using countries.dev and Open-Meteo.";
+}, {
+    readonly name: "agent-research-summary";
+    readonly description: "Multi-tool workflow with an agent_processor summarization step.";
+}, {
+    readonly name: "multi-agent-field-report";
+    readonly description: "Multi-tool workflow with two agent_processor nodes.";
+}, {
+    readonly name: "workflow-invocation-smoke";
+    readonly description: "Parent workflow that invokes another workflow as a workflow node.";
+}];
+declare function buildWorkflowTemplate(templateName: WorkflowTemplateName, ctx: WorkflowTemplateContext): WorkflowTemplateBuild;
+
+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 };