@openserv-labs/sdk 1.0.0

package/dist/agent.d.ts

@@ -0,0 +1,369 @@
+import { type AxiosInstance } from 'axios';
+import type { GetFilesParams, UploadFileParams, MarkTaskAsErroredParams, CompleteTaskParams, SendChatMessageParams, GetTaskDetailParams, GetAgentsParams, GetTasksParams, CreateTaskParams, AddLogToTaskParams, RequestHumanAssistanceParams, UpdateTaskStatusParams, ProcessParams } from './types';
+import { actionSchema, doTaskActionSchema, respondChatMessageActionSchema } from './types';
+import type { ChatCompletionMessageParam, ChatCompletion } from 'openai/resources/chat/completions';
+import OpenAI from 'openai';
+import type { z } from 'zod';
+import { Capability } from './capability';
+/**
+ * Configuration options for creating a new Agent instance.
+ */
+export interface AgentOptions {
+    /**
+     * The port number for the agent's HTTP server.
+     * Defaults to 7378 if not specified.
+     */
+    port?: number;
+    /**
+     * The OpenServ API key for authentication.
+     * Can also be provided via OPENSERV_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * The system prompt that defines the agent's behavior and context.
+     * Used as the initial system message in OpenAI chat completions.
+     */
+    systemPrompt: string;
+    /**
+     * The OpenAI API key for chat completions.
+     * Can also be provided via OPENAI_API_KEY environment variable.
+     * Required when using the process() method.
+     */
+    openaiApiKey?: string;
+}
+export declare class Agent {
+    private options;
+    /**
+     * The Express application instance used to handle HTTP requests.
+     * This is initialized in the constructor and used to set up middleware and routes.
+     * @private
+     */
+    private app;
+    /**
+     * The HTTP server instance created from the Express application.
+     * This is initialized when start() is called and used to listen for incoming requests.
+     * @private
+     */
+    private server;
+    /**
+     * The Express router instance used to define API routes.
+     * This handles routing for health checks, tool execution, and action handling.
+     * @private
+     */
+    private router;
+    /**
+     * The port number the server will listen on.
+     * Defaults to DEFAULT_PORT (7378) if not specified in options.
+     * @private
+     */
+    private port;
+    /**
+     * The system prompt used for OpenAI chat completions.
+     * This defines the base behavior and context for the agent.
+     * @protected
+     */
+    protected systemPrompt: string;
+    /**
+     * Array of capabilities (tools) available to the agent.
+     * Each capability is an instance of the Capability class with a name, description, schema, and run function.
+     * @protected
+     */
+    protected tools: Array<Capability<any>>;
+    /**
+     * The OpenServ API key used for authentication.
+     * Can be provided in options or via OPENSERV_API_KEY environment variable.
+     * @private
+     */
+    private apiKey;
+    /**
+     * Axios instance for making requests to the OpenServ API.
+     * Pre-configured with base URL and authentication headers.
+     * @private
+     */
+    private apiClient;
+    /**
+     * Axios instance for making requests to the OpenServ Runtime API.
+     * Pre-configured with base URL and authentication headers.
+     * @protected
+     */
+    protected runtimeClient: AxiosInstance;
+    /**
+     * OpenAI client instance.
+     * Lazily initialized when needed using the provided API key.
+     * @protected
+     */
+    protected _openai?: OpenAI;
+    /**
+     * Getter that converts the agent's tools into OpenAI function calling format.
+     * Used when making chat completion requests to OpenAI.
+     * @private
+     * @returns Array of ChatCompletionTool objects
+     */
+    private get openAiTools();
+    /**
+     * Getter that provides access to the OpenAI client instance.
+     * Lazily initializes the client with the API key from options or environment.
+     * @private
+     * @throws {Error} If no OpenAI API key is available
+     * @returns {OpenAI} The OpenAI client instance
+     */
+    private get openai();
+    /**
+     * Creates a new Agent instance.
+     * Sets up the Express application, middleware, and routes.
+     * Initializes API clients with appropriate authentication.
+     *
+     * @param {AgentOptions} options - Configuration options for the agent
+     * @throws {Error} If OpenServ API key is not provided in options or environment
+     */
+    constructor(options: AgentOptions);
+    /**
+     * Adds a single capability (tool) to the agent.
+     * Each capability must have a unique name and defines a function that can be called via the API.
+     *
+     * @template S - The Zod schema type for the capability's parameters
+     * @param {Object} capability - The capability configuration
+     * @param {string} capability.name - Unique name for the capability
+     * @param {string} capability.description - Description of what the capability does
+     * @param {S} capability.schema - Zod schema defining the capability's parameters
+     * @param {Function} capability.run - Function that implements the capability's behavior
+     * @param {Object} capability.run.params - Parameters for the run function
+     * @param {z.infer<S>} capability.run.params.args - Validated arguments matching the schema
+     * @param {z.infer<typeof actionSchema>} [capability.run.params.action] - Optional action context
+     * @param {ChatCompletionMessageParam[]} capability.run.messages - Chat message history
+     * @returns {this} The agent instance for method chaining
+     * @throws {Error} If a capability with the same name already exists
+     */
+    addCapability<S extends z.ZodTypeAny>({ name, description, schema, run }: {
+        name: string;
+        description: string;
+        schema: S;
+        run(params: {
+            args: z.infer<S>;
+            action?: z.infer<typeof actionSchema>;
+        }, messages: ChatCompletionMessageParam[]): string | Promise<string>;
+    }): this;
+    /**
+     * Adds multiple capabilities (tools) to the agent at once.
+     * Each capability must have a unique name and not conflict with existing capabilities.
+     *
+     * @template T - Tuple of Zod schema types for the capabilities' parameters
+     * @param {Object} capabilities - Array of capability configurations
+     * @param {string} capabilities[].name - Unique name for each capability
+     * @param {string} capabilities[].description - Description of what each capability does
+     * @param {T[number]} capabilities[].schema - Zod schema defining each capability's parameters
+     * @param {Function} capabilities[].run - Function that implements each capability's behavior
+     * @returns {this} The agent instance for method chaining
+     * @throws {Error} If any capability has a name that already exists
+     */
+    addCapabilities<T extends readonly [z.ZodTypeAny, ...z.ZodTypeAny[]]>(capabilities: {
+        [K in keyof T]: {
+            name: string;
+            description: string;
+            schema: T[K];
+            run: (params: {
+                args: z.infer<T[K]>;
+                action?: z.infer<typeof actionSchema>;
+            }, messages: ChatCompletionMessageParam[]) => string | Promise<string>;
+        };
+    }): this;
+    /**
+     * Gets files in a workspace.
+     *
+     * @param {GetFilesParams} params - Parameters for the file retrieval
+     * @param {number} params.workspaceId - ID of the workspace to get files from
+     * @returns {Promise<any>} The files in the workspace
+     */
+    getFiles(params: GetFilesParams): Promise<any>;
+    /**
+     * Uploads a file to a workspace.
+     *
+     * @param {UploadFileParams} params - Parameters for the file upload
+     * @param {number} params.workspaceId - ID of the workspace to upload to
+     * @param {string} params.path - Path where the file should be stored
+     * @param {number[]|number|null} [params.taskIds] - Optional task IDs to associate with the file
+     * @param {boolean} [params.skipSummarizer] - Whether to skip file summarization
+     * @param {Buffer|string} params.file - The file content to upload
+     * @returns {Promise<any>} The uploaded file details
+     */
+    uploadFile(params: UploadFileParams): Promise<any>;
+    /**
+     * Marks a task as errored.
+     *
+     * @param {MarkTaskAsErroredParams} params - Parameters for marking the task as errored
+     * @param {number} params.workspaceId - ID of the workspace containing the task
+     * @param {number} params.taskId - ID of the task to mark as errored
+     * @param {string} params.error - Error message describing what went wrong
+     * @returns {Promise<any>} The updated task details
+     */
+    markTaskAsErrored(params: MarkTaskAsErroredParams): Promise<any>;
+    /**
+     * Completes a task with the specified output.
+     *
+     * @param {CompleteTaskParams} params - Parameters for completing the task
+     * @param {number} params.workspaceId - ID of the workspace containing the task
+     * @param {number} params.taskId - ID of the task to complete
+     * @param {string} params.output - Output or result of the completed task
+     * @returns {Promise<any>} The completed task details
+     */
+    completeTask(params: CompleteTaskParams): Promise<any>;
+    /**
+     * Sends a chat message from the agent.
+     *
+     * @param {SendChatMessageParams} params - Parameters for sending the chat message
+     * @param {number} params.workspaceId - ID of the workspace where the chat is happening
+     * @param {number} params.agentId - ID of the agent sending the message
+     * @param {string} params.message - Content of the message to send
+     * @returns {Promise<any>} The sent message details
+     */
+    sendChatMessage(params: SendChatMessageParams): Promise<any>;
+    /**
+     * Gets detailed information about a specific task.
+     *
+     * @param {GetTaskDetailParams} params - Parameters for getting task details
+     * @param {number} params.workspaceId - ID of the workspace containing the task
+     * @param {number} params.taskId - ID of the task to get details for
+     * @returns {Promise<any>} The detailed task information
+     */
+    getTaskDetail(params: GetTaskDetailParams): Promise<any>;
+    /**
+     * Gets a list of agents in a workspace.
+     *
+     * @param {GetAgentsParams} params - Parameters for getting agents
+     * @param {number} params.workspaceId - ID of the workspace to get agents from
+     * @returns {Promise<any>} List of agents in the workspace
+     */
+    getAgents(params: GetAgentsParams): Promise<any>;
+    /**
+     * Gets a list of tasks in a workspace.
+     *
+     * @param {GetTasksParams} params - Parameters for getting tasks
+     * @param {number} params.workspaceId - ID of the workspace to get tasks from
+     * @returns {Promise<any>} List of tasks in the workspace
+     */
+    getTasks(params: GetTasksParams): Promise<any>;
+    /**
+     * Creates a new task in a workspace.
+     *
+     * @param {CreateTaskParams} params - Parameters for creating the task
+     * @param {number} params.workspaceId - ID of the workspace to create the task in
+     * @param {number} params.assignee - ID of the agent to assign the task to
+     * @param {string} params.description - Short description of the task
+     * @param {string} params.body - Detailed body/content of the task
+     * @param {string} params.input - Input data for the task
+     * @param {string} params.expectedOutput - Expected output format or content
+     * @param {number[]} params.dependencies - IDs of tasks that this task depends on
+     * @returns {Promise<any>} The created task details
+     */
+    createTask(params: CreateTaskParams): Promise<any>;
+    /**
+     * Adds a log entry to a task.
+     *
+     * @param {AddLogToTaskParams} params - Parameters for adding the log
+     * @param {number} params.workspaceId - ID of the workspace containing the task
+     * @param {number} params.taskId - ID of the task to add the log to
+     * @param {'info'|'warning'|'error'} params.severity - Severity level of the log
+     * @param {'text'|'openai-message'} params.type - Type of log entry
+     * @param {string|object} params.body - Content of the log entry
+     * @returns {Promise<any>} The created log entry details
+     */
+    addLogToTask(params: AddLogToTaskParams): Promise<any>;
+    /**
+     * Requests human assistance for a task.
+     *
+     * @param {RequestHumanAssistanceParams} params - Parameters for requesting assistance
+     * @param {number} params.workspaceId - ID of the workspace containing the task
+     * @param {number} params.taskId - ID of the task needing assistance
+     * @param {'text'|'project-manager-plan-review'} params.type - Type of assistance needed
+     * @param {string|object} params.question - Question or request for the human
+     * @param {object} [params.agentDump] - Optional agent state/context information
+     * @returns {Promise<any>} The created assistance request details
+     */
+    requestHumanAssistance(params: RequestHumanAssistanceParams): Promise<any>;
+    /**
+     * Updates the status of a task.
+     *
+     * @param {UpdateTaskStatusParams} params - Parameters for updating the status
+     * @param {number} params.workspaceId - ID of the workspace containing the task
+     * @param {number} params.taskId - ID of the task to update
+     * @param {TaskStatus} params.status - New status for the task
+     * @returns {Promise<any>} The updated task details
+     */
+    updateTaskStatus(params: UpdateTaskStatusParams): Promise<any>;
+    /**
+     * Processes a conversation with OpenAI, handling tool calls iteratively until completion.
+     *
+     * @param {ProcessParams} params - Parameters for processing the conversation
+     * @param {ChatCompletionMessageParam[]} params.messages - The conversation history
+     * @returns {Promise<ChatCompletion>} The final response from OpenAI
+     * @throws {Error} If no response is received from OpenAI or max iterations are reached
+     */
+    process({ messages }: ProcessParams): Promise<ChatCompletion>;
+    /**
+     * Handle a task execution request
+     * This method can be overridden by extending classes to customize task handling
+     * @protected
+     */
+    protected doTask(action: z.infer<typeof doTaskActionSchema>): Promise<void>;
+    /**
+     * Handle a chat message response request
+     * This method can be overridden by extending classes to customize chat handling
+     * @protected
+     */
+    protected respondToChat(action: z.infer<typeof respondChatMessageActionSchema>): Promise<void>;
+    /**
+     * Handles execution of a specific tool/capability.
+     *
+     * @param {Object} req - The request object
+     * @param {Object} req.params - Request parameters
+     * @param {string} req.params.toolName - Name of the tool to execute
+     * @param {Object} req.body - Request body
+     * @param {z.infer<z.ZodTypeAny>} [req.body.args] - Arguments for the tool
+     * @param {z.infer<typeof actionSchema>} [req.body.action] - Action context
+     * @returns {Promise<{result: string}>} The result of the tool execution
+     * @throws {BadRequest} If tool name is missing or tool is not found
+     * @throws {Error} If tool execution fails
+     */
+    handleToolRoute(req: {
+        params: {
+            toolName: string;
+        };
+        body: {
+            args?: z.infer<z.ZodTypeAny>;
+            action?: z.infer<typeof actionSchema>;
+        };
+    }): Promise<{
+        result: string;
+    }>;
+    /**
+     * Handles the root route for task execution and chat message responses.
+     *
+     * @param {Object} req - The request object
+     * @param {unknown} req.body - Request body to be parsed as an action
+     * @returns {Promise<void>}
+     * @throws {Error} If action type is invalid
+     */
+    handleRootRoute(req: {
+        body: unknown;
+    }): Promise<void>;
+    /**
+     * Sets up the Express routes for the agent's HTTP server.
+     * Configures health check endpoint and routes for tool execution.
+     * @private
+     */
+    private setupRoutes;
+    /**
+     * Starts the agent's HTTP server.
+     *
+     * @returns {Promise<void>} Resolves when the server has started
+     * @throws {Error} If server fails to start
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the agent's HTTP server.
+     *
+     * @returns {Promise<void>} Resolves when the server has stopped
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}