@openserv-labs/sdk 1.8.2 → 2.0.0

package/README.md

@@ -6,9 +6,42 @@
 
 A powerful TypeScript framework for building non-deterministic AI agents with advanced cognitive capabilities like reasoning, decision-making, and inter-agent collaboration within the OpenServ platform. Built with strong typing, extensible architecture, and a fully autonomous agent runtime.
 
+## What's New in v2
+
+Version 2.0.0 introduces built-in tunnel support for local development, eliminating the need to deploy your agent to test it with the OpenServ platform.
+
+### Key Changes
+
+- **Built-in Tunnel for Local Development** - New `run()` function and `OpenServTunnel` class create a secure WebSocket connection to OpenServ, allowing you to develop and test locally without deploying. No need to configure an Agent Endpoint URL during development.
+- **Automatic Port Fallback** - If your preferred port is busy, the agent automatically finds an available port instead of failing.
+- **Secrets Management** - New `getSecrets()` and `getSecretValue()` methods allow agents to securely access workspace secrets.
+- **Delete File Support** - New `deleteFile()` method for workspace file management.
+- **Increased Request Size Limit** - Body parser limit increased to 10MB for larger payloads.
+- **Enhanced Logging** - Added pino-pretty for more readable log output during development.
+
+### Migration from v1.x
+
+The v2 API is backwards compatible. To take advantage of the new tunnel feature for local development, simply replace:
+
+```typescript
+// v1.x - Required deploying to a public URL
+agent.start()
+```
+
+With:
+
+```typescript
+// v2.x - Works locally without deployment
+import { run } from '@openserv-labs/sdk'
+const { stop } = await run(agent)
+```
+
 ## Table of Contents
 
 - [OpenServ TypeScript SDK, Autonomous AI Agent Development Framework](#openserv-typescript-sdk-autonomous-ai-agent-development-framework)
+  - [What's New in v2](#whats-new-in-v2)
+    - [Key Changes](#key-changes)
+    - [Migration from v1.x](#migration-from-v1x)
   - [Table of Contents](#table-of-contents)
   - [Features](#features)
   - [Framework Architecture](#framework-architecture)
@@ -39,10 +72,24 @@ A powerful TypeScript framework for building non-deterministic AI agents with ad
     - [Workspace Management](#workspace-management)
       - [Get Files](#get-files)
       - [Upload File](#upload-file)
+      - [Delete File](#delete-file)
+    - [Secrets Management](#secrets-management)
+      - [Get Secrets](#get-secrets)
+      - [Get Secret Value](#get-secret-value)
     - [Integration Management](#integration-management)
       - [Call Integration](#call-integration)
     - [MCP](#mcp)
+      - [Configure MCP servers](#configure-mcp-servers)
+        - [Local (stdio) transport](#local-stdio-transport)
+        - [Server-Sent Events (sse) transport](#server-sent-events-sse-transport)
+      - [Using MCP tools](#using-mcp-tools)
   - [Advanced Usage](#advanced-usage)
+    - [Local Development with Tunnel](#local-development-with-tunnel)
+      - [How It Works](#how-it-works)
+      - [Quick Start](#quick-start-1)
+      - [Tunnel vs. Deployed Endpoint](#tunnel-vs-deployed-endpoint)
+      - [Configuration Options](#configuration-options)
+      - [Using the Tunnel Directly](#using-the-tunnel-directly)
     - [OpenAI Process Runtime](#openai-process-runtime)
     - [Error Handling](#error-handling)
     - [Custom Agents](#custom-agents)
@@ -64,6 +111,7 @@ A powerful TypeScript framework for building non-deterministic AI agents with ad
 - 📝 Strong TypeScript typing with Zod schemas
 - 📊 Built-in logging and error handling
 - 🎯 Three levels of control for different development needs
+- 🚇 Built-in tunnel for local development and testing
 
 ## Framework Architecture
 
@@ -257,15 +305,21 @@ agent.addCapabilities([
 
 // Start the agent server
 agent.start()
+
+// Or use run() for local development with automatic tunnel management
+// import { run } from '@openserv-labs/sdk'
+// const { stop } = await run(agent)
 ```
 
 ## Environment Variables
 
-| Variable           | Description                           | Required | Default |
-| ------------------ | ------------------------------------- | -------- | ------- |
-| `OPENSERV_API_KEY` | Your OpenServ API key                 | Yes      | -       |
-| `OPENAI_API_KEY`   | OpenAI API key (for process() method) | No\*     | -       |
-| `PORT`             | Server port                           | No       | 7378    |
+| Variable              | Description                                | Required | Default                            |
+| --------------------- | ------------------------------------------ | -------- | ---------------------------------- |
+| `OPENSERV_API_KEY`    | Your OpenServ API key                      | Yes      | -                                  |
+| `OPENAI_API_KEY`      | OpenAI API key (for process() method)      | No\*     | -                                  |
+| `PORT`                | Server port                                | No       | 7378                               |
+| `OPENSERV_AUTH_TOKEN` | Token for authenticating incoming requests | No       | -                                  |
+| `OPENSERV_PROXY_URL`  | Custom proxy URL for tunnel connections    | No       | `https://agents-proxy.openserv.ai` |
 
 \*Required if using OpenAI integration features
 
@@ -528,6 +582,61 @@ await agent.uploadFile({
 })
 ```
 
+#### Delete File
+
+```typescript
+await agent.deleteFile({
+  workspaceId: number | string,
+  fileId: number
+})
+```
+
+### Secrets Management
+
+Agents can securely access secrets configured in their workspace. Secrets are managed through the OpenServ platform.
+
+#### Get Secrets
+
+Returns a list of all secrets available to the agent in a workspace.
+
+```typescript
+const secrets = await agent.getSecrets({
+  workspaceId: number | string
+})
+// Returns: { id: number, name: string }[]
+```
+
+#### Get Secret Value
+
+Retrieves the actual value of a specific secret.
+
+```typescript
+const value = await agent.getSecretValue({
+  workspaceId: number | string,
+  secretId: number
+})
+// Returns: string
+```
+
+**Example:**
+
+```typescript
+// Get all available secrets
+const secrets = await agent.getSecrets({ workspaceId: 123 })
+
+// Find a specific secret by name
+const apiKeySecret = secrets.find(s => s.name === 'EXTERNAL_API_KEY')
+
+if (apiKeySecret) {
+  // Retrieve the secret value
+  const apiKey = await agent.getSecretValue({
+    workspaceId: 123,
+    secretId: apiKeySecret.id
+  })
+  // Use the secret value securely
+}
+```
+
 ### Integration Management
 
 #### Call Integration
@@ -633,6 +742,109 @@ You can also access the raw MCP client via `agent.mcpClients['MCP_SERVER_ID']` t
 
 ## Advanced Usage
 
+### Local Development with Tunnel
+
+The SDK provides a built-in tunnel that connects your locally running agent to the OpenServ platform. This eliminates the need to deploy your agent to a public URL during development.
+
+#### How It Works
+
+When you use the `run()` function or `OpenServTunnel` class:
+
+1. Your agent starts an HTTP server locally (default port 7378)
+2. A WebSocket connection is established to OpenServ's proxy server
+3. The proxy authenticates your agent using your `OPENSERV_API_KEY`
+4. OpenServ routes incoming tasks through the tunnel to your local machine
+
+**No Agent Endpoint URL configuration is needed during local development.** The tunnel connection is identified by your API key, which is already associated with your registered agent in the OpenServ platform.
+
+#### Quick Start
+
+```typescript
+import { Agent, run } from '@openserv-labs/sdk'
+import { z } from 'zod'
+
+const agent = new Agent({
+  systemPrompt: 'You are a helpful assistant.'
+})
+
+agent.addCapability({
+  name: 'greet',
+  description: 'Greet someone',
+  schema: z.object({ name: z.string() }),
+  async run({ args }) {
+    return `Hello, ${args.name}!`
+  }
+})
+
+// Start the agent with automatic tunnel management
+const { tunnel, stop } = await run(agent)
+
+// The agent is now connected to OpenServ and ready to receive tasks
+
+// To gracefully stop the agent and tunnel:
+await stop()
+```
+
+The `run()` function automatically:
+
+- Starts the agent's HTTP server
+- Creates a WebSocket tunnel to the OpenServ proxy
+- Handles reconnection with exponential backoff (up to 10 retries)
+- Registers signal handlers for graceful shutdown (SIGTERM, SIGINT)
+
+#### Tunnel vs. Deployed Endpoint
+
+| Aspect            | Tunnel (Local Development) | Deployed Endpoint (Production) |
+| ----------------- | -------------------------- | ------------------------------ |
+| Setup             | Just run your code         | Deploy to cloud/server         |
+| URL Configuration | Not needed                 | Set Agent Endpoint in platform |
+| Connection        | WebSocket via proxy        | Direct HTTP                    |
+| Use case          | Development & testing      | Production                     |
+
+#### Configuration Options
+
+```typescript
+const { tunnel, stop } = await run(agent, {
+  // Tunnel-specific options
+  tunnel: {
+    apiKey: 'your-api-key', // Defaults to OPENSERV_API_KEY env var
+    proxyUrl: 'custom-proxy-url' // Defaults to OPENSERV_PROXY_URL env var
+  },
+  // Disable automatic signal handlers if you want to handle shutdown yourself
+  handleSignals: false
+})
+```
+
+#### Using the Tunnel Directly
+
+For more advanced control, you can use the `OpenServTunnel` class directly:
+
+```typescript
+import { Agent, OpenServTunnel } from '@openserv-labs/sdk'
+
+const agent = new Agent({
+  systemPrompt: 'You are a helpful assistant.'
+})
+
+await agent.start()
+
+const tunnel = new OpenServTunnel({
+  apiKey: process.env.OPENSERV_API_KEY,
+  onConnected: isReconnect => {
+    console.log(isReconnect ? 'Reconnected!' : 'Connected!')
+  },
+  onError: error => {
+    console.error('Tunnel error:', error.message)
+  }
+})
+
+await tunnel.start(agent.port)
+
+// Later, to stop:
+await tunnel.stop()
+await agent.stop()
+```
+
 ### OpenAI Process Runtime
 
 The framework includes built-in OpenAI function calling support through the `process()` method:

package/dist/agent.d.ts

@@ -65,9 +65,9 @@ export declare class Agent<M extends string = string> {
     /**
      * The port number the server will listen on.
      * Defaults to DEFAULT_PORT (7378) if not specified in options.
-     * @private
+     * May change if the preferred port is unavailable.
      */
-    private port;
+    port: number;
     /**
      * The system prompt used for OpenAI chat completions.
      * This defines the base behavior and context for the agent.
@@ -405,6 +405,7 @@ export declare class Agent<M extends string = string> {
     private setupRoutes;
     /**
      * Starts the agent's HTTP server.
+     * If the preferred port is unavailable, it will find an open port.
      *
      * @returns {Promise<void>} Resolves when the server has started
      * @throws {Error} If server fails to start

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAUjD,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,sBAAsB,EACtB,aAAa,EACb,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAEhB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAOlB,YAAY,EACZ,kBAAkB,EAClB,8BAA8B,EAC/B,MAAM,SAAS,CAAA;AAEhB,OAAO,KAAK,EACV,0BAA0B,EAE1B,cAAc,EACf,MAAM,mCAAmC,CAAA;AAI1C,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAGL,KAAK,eAAe,EAEpB,SAAS,EACV,MAAM,OAAO,CAAA;AAOd;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM;IAC5C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAEnE;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,eAAe,CAAC,CAAA;CACxC;AAoBD,qBAAa,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IA0H9B,OAAO,CAAC,OAAO;IAzH3B;;;;OAIG;IACH,OAAO,CAAC,GAAG,CAAqB;IAEhC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAA2B;IAEzC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAqB;IAEnC;;;;OAIG;IACI,IAAI,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,SAAS,CAAC,YAAY,EAAE,MAAM,CAAA;IAE9B;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAK;IAExD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAQ;IAEtB;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAe;IAEhC;;;;OAIG;IACH,SAAS,CAAC,aAAa,EAAE,aAAa,CAAA;IAEtC;;;;OAIG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAE1B;;;OAGG;IACI,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAgC;IAE1E;;;;;OAKG;IACH,OAAO,KAAK,WAAW,GAStB;IAED;;;;;;OAMG;IACH,OAAO,KAAK,MAAM,GAWjB;IAED;;;;;;;OAOG;gBACiB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;IAgD5C,OAAO,CAAC,oBAAoB;IAgB5B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,EACpC,IAAI,EACJ,WAAW,EACX,MAAM,EACN,GAAG,EACJ,EAAE;QACD,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,CAAC,CAAA;QACT,GAAG,CACD,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE;YAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAC,MAAM,CAAC,EAAE,YAAY,CAAA;SAAE,EACnD,QAAQ,EAAE,0BAA0B,EAAE,GACrC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;KAC5B,GAAG,IAAI;IAYR;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE;SACjF,CAAC,IAAI,MAAM,CAAC,GAAG;YACd,IAAI,EAAE,MAAM,CAAA;YACZ,WAAW,EAAE,MAAM,CAAA;YACnB,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YACZ,GAAG,CACD,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE;gBAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAAC,MAAM,CAAC,EAAE,YAAY,CAAA;aAAE,EACtD,QAAQ,EAAE,0BAA0B,EAAE,GACrC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;SAC5B;KACF,GAAG,IAAI;IAOR;;;;;;OAMG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc;IAOrC;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB;IAOzC;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,oBAAoB;IAOjD;;;;;;;;;;OAUG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB;IA6BzC;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB;IAOzC;;;;;;;;OAQG;IACG,iBAAiB,CAAC,MAAM,EAAE,uBAAuB;IAUvD;;;;;;;;OAQG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB;IAU7C;;;;;;;;OAQG;IACG,eAAe,CAAC,MAAM,EAAE,qBAAqB;IAUnD;;;;;;;OAOG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB;IAO/C;;;;;;OAMG;IACG,SAAS,CAAC,MAAM,EAAE,eAAe;IAOvC;;;;;;OAMG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc;IAOrC;;;;;;;OAOG;IACG,eAAe,CAAC,MAAM,EAAE,qBAAqB;IAOnD;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB;IAezC;;;;;;;;;;OAUG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB;IAY7C;;;;;;;;;;OAUG;IACG,sBAAsB,CAAC,MAAM,EAAE,4BAA4B;IA0BjE;;;;;;;;OAQG;IACG,gBAAgB,CAAC,MAAM,EAAE,sBAAsB;IAUrD;;;;;;;OAOG;IACG,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IA4FnE;;;;OAIG;cACa,MAAM,CAAC,MAAM,EAAE,kBAAkB;IA6BjD;;;;OAIG;cACa,aAAa,CAAC,MAAM,EAAE,8BAA8B;IA+BpE;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,GAAG,EAAE;QACzB,MAAM,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;QAC5B,IAAI,EAAE;YACJ,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;YAC5B,MAAM,CAAC,EAAE,YAAY,CAAA;YACrB,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAA;SACxC,CAAA;KACF;;;IAyBD;;;;;;;OAOG;IACG,eAAe,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE;IAgB5C;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAuBnB;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqF5B;;;;OAIG;IACG,IAAI;IAQV;;;OAGG;IACH,OAAO,CAAC,WAAW;IAOnB;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,WAAW,EAAE,sBAAsB;IASzD;;;;;;;;OAQG;IACH,OAAO,CAAC,yBAAyB;CAsClC"}

package/dist/agent.js

@@ -58,7 +58,7 @@ class Agent {
     /**
      * The port number the server will listen on.
      * Defaults to DEFAULT_PORT (7378) if not specified in options.
-     * @private
+     * May change if the preferred port is unavailable.
      */
     port;
     /**
@@ -169,7 +169,7 @@ class Agent {
                 'x-openserv-key': this.apiKey
             }
         });
-        this.app.use(express_1.default.json());
+        this.app.use(express_1.default.json({ limit: '10mb' }));
         this.app.use(express_1.default.urlencoded({ extended: false }));
         this.app.use((0, hpp_1.default)());
         this.app.use((0, helmet_1.default)());
@@ -737,17 +737,53 @@ class Agent {
     }
     /**
      * Starts the agent's HTTP server.
+     * If the preferred port is unavailable, it will find an open port.
      *
      * @returns {Promise<void>} Resolves when the server has started
      * @throws {Error} If server fails to start
      */
     async start() {
+        const preferredPort = this.port;
+        // Try the preferred port first, fallback to an available port if it fails
         await new Promise((resolve, reject) => {
-            this.server = this.app.listen(this.port, () => {
-                logger_1.logger.info(`Agent server started on port ${this.port}`);
-                resolve();
-            });
-            this.server.on('error', reject);
+            const tryListen = (port, isRetry) => {
+                const server = this.app.listen(port);
+                const onListening = () => {
+                    // Remove the startup handlers once listening succeeds
+                    server.removeListener('error', errorHandler);
+                    server.removeListener('listening', onListening);
+                    if (isRetry) {
+                        const address = server.address();
+                        if (address && typeof address === 'object') {
+                            this.port = address.port;
+                            logger_1.logger.info(`Port ${preferredPort} was unavailable, using port ${this.port} instead`);
+                        }
+                    }
+                    else {
+                        logger_1.logger.info(`Agent server started on port ${this.port}`);
+                    }
+                    this.server = server;
+                    resolve();
+                };
+                const errorHandler = (err) => {
+                    // Clean up the failed server before handling the error
+                    server.removeListener('error', errorHandler);
+                    server.removeListener('listening', onListening);
+                    // Close the failed server to release resources
+                    server.close();
+                    if (err.code === 'EADDRINUSE' && !isRetry) {
+                        logger_1.logger.warn(`Port ${this.port} is in use, finding an available port...`);
+                        // Let the OS assign an available port
+                        tryListen(0, true);
+                    }
+                    else {
+                        reject(err);
+                    }
+                };
+                server.on('listening', onListening);
+                server.on('error', errorHandler);
+            };
+            tryListen(this.port, false);
         });
         const connectionPromises = Object.values(this.mcpClients).map(client => client.connect());
         const results = await Promise.allSettled(connectionPromises);

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { Agent } from './agent';
 export type { AgentOptions } from './agent';
 export { Capability } from './capability';
+export { OpenServTunnel } from './tunnel';
+export type { OpenServTunnelOptions, RequestData, ResponseData, TunnelState, TunnelEvent } from './tunnel';
+export { run } from './run';
+export type { RunOptions, RunResult } from './run';
 export type { TaskStatus, GetFilesParams, UploadFileParams, DeleteFileParams, MarkTaskAsErroredParams, CompleteTaskParams, SendChatMessageParams, GetTaskDetailParams, GetAgentsParams, GetTasksParams, CreateTaskParams, AddLogToTaskParams, RequestHumanAssistanceParams, UpdateTaskStatusParams, ProcessParams, CapabilityFuncParams, GetChatMessagesParams } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,YAAY,EACV,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACZ,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAElD,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Capability = exports.Agent = void 0;
+exports.run = exports.OpenServTunnel = exports.Capability = exports.Agent = void 0;
 var agent_1 = require("./agent");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_1.Agent; } });
 var capability_1 = require("./capability");
 Object.defineProperty(exports, "Capability", { enumerable: true, get: function () { return capability_1.Capability; } });
+var tunnel_1 = require("./tunnel");
+Object.defineProperty(exports, "OpenServTunnel", { enumerable: true, get: function () { return tunnel_1.OpenServTunnel; } });
+var run_1 = require("./run");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_1.run; } });

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,6CAIrB,CAAA;AAEJ,eAAO,MAAM,MAAM,uCAAiB,CAAA"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,6CAmBxB,CAAA;AAED,eAAO,MAAM,MAAM,uCAAiB,CAAA"}

package/dist/logger.js

@@ -5,9 +5,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logger = exports.createLogger = void 0;
 const pino_1 = __importDefault(require("pino"));
-const createLogger = () => (0, pino_1.default)({
-    name: 'openserv-agent',
-    level: process.env.LOG_LEVEL || 'info'
-});
+const createLogger = () => {
+    const isPretty = process.env.LOG_PRETTY === 'true' ||
+        (process.env.NODE_ENV !== 'production' && process.stdout.isTTY);
+    return (0, pino_1.default)({
+        name: 'openserv-agent',
+        level: process.env.LOG_LEVEL || 'info',
+        transport: isPretty
+            ? {
+                target: 'pino-pretty',
+                options: {
+                    colorize: true,
+                    translateTime: 'SYS:standard',
+                    ignore: 'pid,hostname'
+                }
+            }
+            : undefined
+    });
+};
 exports.createLogger = createLogger;
 exports.logger = (0, exports.createLogger)();

package/dist/run.d.ts

@@ -0,0 +1,58 @@
+import type { Agent } from './agent';
+import { OpenServTunnel, type OpenServTunnelOptions } from './tunnel';
+export interface RunOptions {
+    /**
+     * Options for the OpenServ tunnel.
+     * If not provided, defaults will be used (API key from env, default proxy URL).
+     */
+    tunnel?: Omit<OpenServTunnelOptions, 'onConnected' | 'onRequest' | 'onError'>;
+    /**
+     * Whether to register signal handlers for graceful shutdown (SIGTERM, SIGINT).
+     * Defaults to true.
+     */
+    handleSignals?: boolean;
+}
+export interface RunResult {
+    /**
+     * The tunnel instance for advanced control.
+     */
+    tunnel: OpenServTunnel;
+    /**
+     * Stop the agent and tunnel.
+     */
+    stop: () => Promise<void>;
+}
+/**
+ * Run an agent with automatic tunnel management.
+ *
+ * This function handles:
+ * 1. Starting the agent's HTTP server
+ * 2. Creating a tunnel to connect to the OpenServ proxy
+ *
+ * @param agent - The Agent instance to run
+ * @param options - Optional configuration for the tunnel
+ * @returns Run result with tunnel and stop function
+ *
+ * @example
+ * ```typescript
+ * import { Agent, run } from '@openserv-labs/sdk'
+ *
+ * const agent = new Agent({
+ *   systemPrompt: 'You are a helpful assistant.'
+ * })
+ *
+ * agent.addCapability({
+ *   name: 'greet',
+ *   description: 'Greet someone',
+ *   schema: z.object({ name: z.string() }),
+ *   run: async ({ args }) => `Hello, ${args.name}!`
+ * })
+ *
+ * const { stop } = await run(agent)
+ *
+ * // Later, to stop:
+ * await stop()
+ * ```
+ */
+export declare function run(agent: Agent, options?: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAMrE,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC,CAAA;IAE7E;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,MAAM,EAAE,cAAc,CAAA;IAEtB;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA2EhF"}

package/dist/run.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const logger_1 = require("./logger");
+const tunnel_1 = require("./tunnel");
+// ============================================================================
+// Main Run Function
+// ============================================================================
+/**
+ * Run an agent with automatic tunnel management.
+ *
+ * This function handles:
+ * 1. Starting the agent's HTTP server
+ * 2. Creating a tunnel to connect to the OpenServ proxy
+ *
+ * @param agent - The Agent instance to run
+ * @param options - Optional configuration for the tunnel
+ * @returns Run result with tunnel and stop function
+ *
+ * @example
+ * ```typescript
+ * import { Agent, run } from '@openserv-labs/sdk'
+ *
+ * const agent = new Agent({
+ *   systemPrompt: 'You are a helpful assistant.'
+ * })
+ *
+ * agent.addCapability({
+ *   name: 'greet',
+ *   description: 'Greet someone',
+ *   schema: z.object({ name: z.string() }),
+ *   run: async ({ args }) => `Hello, ${args.name}!`
+ * })
+ *
+ * const { stop } = await run(agent)
+ *
+ * // Later, to stop:
+ * await stop()
+ * ```
+ */
+async function run(agent, options) {
+    await agent.start();
+    const tunnel = new tunnel_1.OpenServTunnel({
+        ...options?.tunnel,
+        onConnected: isReconnect => {
+            if (!isReconnect) {
+                logger_1.logger.info('Agent connected to OpenServ proxy');
+            }
+        },
+        onError: error => {
+            logger_1.logger.error(`Tunnel error: ${error.message}`);
+        }
+    });
+    try {
+        await tunnel.start(agent.port);
+    }
+    catch (error) {
+        // Clean up the agent if tunnel fails to connect
+        await agent.stop();
+        throw error;
+    }
+    let shutdownPromise = null;
+    let sigtermHandler = null;
+    let sigintHandler = null;
+    const stop = async () => {
+        // Return existing shutdown promise if already in progress
+        // This ensures concurrent callers wait for actual completion
+        if (shutdownPromise)
+            return shutdownPromise;
+        shutdownPromise = (async () => {
+            // Remove signal handlers to prevent stale references on repeated run() calls
+            if (sigtermHandler) {
+                process.removeListener('SIGTERM', sigtermHandler);
+                sigtermHandler = null;
+            }
+            if (sigintHandler) {
+                process.removeListener('SIGINT', sigintHandler);
+                sigintHandler = null;
+            }
+            await tunnel.stop();
+            await agent.stop();
+        })();
+        return shutdownPromise;
+    };
+    // Register signal handlers for graceful shutdown (default: true)
+    const handleSignals = options?.handleSignals !== false;
+    if (handleSignals) {
+        const signalHandler = (signal) => {
+            logger_1.logger.info(`Received ${signal}, shutting down gracefully...`);
+            stop()
+                .then(() => {
+                process.exit(0);
+            })
+                .catch(err => {
+                logger_1.logger.error(`Error during shutdown: ${err.message}`);
+                process.exit(1);
+            });
+        };
+        sigtermHandler = () => signalHandler('SIGTERM');
+        sigintHandler = () => signalHandler('SIGINT');
+        process.once('SIGTERM', sigtermHandler);
+        process.once('SIGINT', sigintHandler);
+    }
+    return {
+        tunnel,
+        stop
+    };
+}