@openserv-labs/sdk 2.3.0 → 2.4.1

package/README.md

@@ -232,7 +232,7 @@ npm install @openserv-labs/sdk
    agent.addCapability({
      name: 'greet',
      description: 'Greet a user by name',
-     schema: z.object({
+     inputSchema: z.object({
        name: z.string().describe('The name of the user to greet')
      }),
      async run({ args }) {
@@ -273,7 +273,7 @@ const agent = new Agent({
 agent.addCapability({
   name: 'greet',
   description: 'Greet a user by name',
-  schema: z.object({
+  inputSchema: z.object({
     name: z.string().describe('The name of the user to greet')
   }),
   async run({ args }) {
@@ -286,7 +286,7 @@ agent.addCapabilities([
   {
     name: 'farewell',
     description: 'Say goodbye to a user',
-    schema: z.object({
+    inputSchema: z.object({
       name: z.string().describe('The name of the user to bid farewell')
     }),
     async run({ args }) {
@@ -296,7 +296,7 @@ agent.addCapabilities([
   {
     name: 'help',
     description: 'Show available commands',
-    schema: z.object({}),
+    inputSchema: z.object({}),
     async run() {
       return 'Available commands: greet, farewell, help'
     }
@@ -316,13 +316,13 @@ agent.start()
 | Variable              | Description                                | Required | Default                            |
 | --------------------- | ------------------------------------------ | -------- | ---------------------------------- |
 | `OPENSERV_API_KEY`    | Your OpenServ API key                      | Yes      | -                                  |
-| `OPENAI_API_KEY`      | OpenAI API key (for process() method)      | No\*     | -                                  |
+| `OPENAI_API_KEY`      | OpenAI API key (only 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` |
 | `DISABLE_TUNNEL`      | Skip tunnel and run HTTP server only       | No       | -                                  |
 
-\*Required if using OpenAI integration features
+**Note:** `OPENAI_API_KEY` is only needed if you use the `process()` method for direct OpenAI calls. Most agents don't need it -- use run-less capabilities or `generate()` instead.
 
 ## Core Concepts
 
@@ -334,8 +334,10 @@ Each capability must include:
 
 - `name`: Unique identifier for the capability
 - `description`: What the capability does
-- `schema`: Zod schema defining the parameters
-- `run`: Function that executes the capability, receiving validated args and action context
+- `inputSchema`: Zod schema defining the input parameters (optional for run-less capabilities, defaults to `z.object({ input: z.string() })`)
+- `run`: Function that executes the capability (optional -- omit for run-less capabilities handled by the runtime)
+- `outputSchema`: Zod schema for structured LLM output (only for run-less capabilities)
+- `schema`: **Deprecated** -- use `inputSchema` instead (kept for backwards compatibility)
 
 ```typescript
 import { Agent } from '@openserv-labs/sdk'
@@ -349,7 +351,7 @@ const agent = new Agent({
 agent.addCapability({
   name: 'summarize',
   description: 'Summarize a piece of text',
-  schema: z.object({
+  inputSchema: z.object({
     text: z.string().describe('Text content to summarize'),
     maxLength: z.number().optional().describe('Maximum length of summary')
   }),
@@ -377,7 +379,7 @@ agent.addCapabilities([
   {
     name: 'analyze',
     description: 'Analyze text for sentiment and keywords',
-    schema: z.object({
+    inputSchema: z.object({
       text: z.string().describe('Text to analyze')
     }),
     async run({ args, action }) {
@@ -388,7 +390,7 @@ agent.addCapabilities([
   {
     name: 'help',
     description: 'Show available commands',
-    schema: z.object({}),
+    inputSchema: z.object({}),
     async run({ args, action }) {
       return 'Available commands: summarize, analyze, help'
     }
@@ -399,8 +401,8 @@ agent.addCapabilities([
 Each capability's run function receives:
 
 - `params`: Object containing:
-  - `args`: The validated arguments matching the capability's schema
-  - `action`: The action context containing:
+  - `args`: The validated arguments matching the capability's inputSchema
+  - `action`: The action context provided by the runtime, containing:
     - `task`: The current task context (if running as part of a task)
     - `workspace`: The current workspace context
     - `me`: Information about the current agent
@@ -408,6 +410,92 @@ Each capability's run function receives:
 
 The run function must return a string or Promise<string>.
 
+### Run-less Capabilities
+
+Run-less capabilities let you define tools without a `run` function. The OpenServ runtime handles execution via its own LLM, using the capability's `description` as instructions. This means you don't need your own OpenAI key.
+
+```typescript
+import { Agent, run } from '@openserv-labs/sdk'
+import { z } from 'zod'
+
+const agent = new Agent({
+  systemPrompt: 'You are a creative writing assistant.'
+})
+
+// Simplest form: just name + description (default inputSchema: { input: string })
+agent.addCapability({
+  name: 'generate_haiku',
+  description:
+    'Generate a haiku poem (5-7-5 syllables) about the given input. Only output the haiku.'
+})
+
+// With custom inputSchema
+agent.addCapability({
+  name: 'translate',
+  description: 'Translate the given text to the target language. Return only the translated text.',
+  inputSchema: z.object({
+    text: z.string().describe('The text to translate'),
+    targetLanguage: z.string().describe('The target language')
+  })
+})
+
+// With structured output via outputSchema
+agent.addCapability({
+  name: 'analyze_sentiment',
+  description: 'Analyze the sentiment of the given input text.',
+  outputSchema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral']),
+    confidence: z.number().min(0).max(1)
+  })
+})
+
+run(agent)
+```
+
+### The `generate()` Method
+
+Inside custom `run` functions, use `this.generate()` to delegate LLM calls to the OpenServ runtime without needing your own OpenAI key. The `action` parameter is required for billing. You can optionally pass `messages` for conversation context.
+
+```typescript
+agent.addCapability({
+  name: 'write_and_save_poem',
+  description: 'Write a poem and save it to the workspace',
+  inputSchema: z.object({ topic: z.string() }),
+  async run({ args, action }, messages) {
+    // Text generation
+    const poem = await this.generate({
+      prompt: `Write a short poem about ${args.topic}`,
+      action
+    })
+
+    // Structured output generation
+    const metadata = await this.generate({
+      prompt: `Suggest a title and 3 tags for this poem: ${poem}`,
+      outputSchema: z.object({
+        title: z.string(),
+        tags: z.array(z.string()).length(3)
+      }),
+      action
+    })
+
+    // With conversation history for context
+    const followUp = await this.generate({
+      prompt: 'Based on our conversation, suggest a related topic.',
+      messages, // pass conversation history from the run function
+      action
+    })
+
+    await this.uploadFile({
+      workspaceId: action.workspace.id,
+      path: `poems/${metadata.title}.txt`,
+      file: poem
+    })
+
+    return `Saved "${metadata.title}" with tags: ${metadata.tags.join(', ')}`
+  }
+})
+```
+
 ### Tasks
 
 Tasks are units of work that agents can execute. They can have dependencies, require human assistance, and maintain state:
@@ -451,7 +539,7 @@ const customerSupportAgent = new Agent({
     {
       name: 'respondToCustomer',
       description: 'Generate a response to a customer inquiry',
-      schema: z.object({
+      inputSchema: z.object({
         query: z.string(),
         context: z.string().optional()
       }),
@@ -771,7 +859,7 @@ const agent = new Agent({
 agent.addCapability({
   name: 'greet',
   description: 'Greet someone',
-  schema: z.object({ name: z.string() }),
+  inputSchema: z.object({ name: z.string() }),
   async run({ args }) {
     return `Hello, ${args.name}!`
   }
@@ -795,13 +883,13 @@ The `run()` function automatically:
 
 #### 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                          |
-| Tunnel            | Enabled (default)          | Disabled (`DISABLE_TUNNEL=true`)     |
-| Use case          | Development & testing      | Production                           |
+| 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                      |
+| Tunnel            | Enabled (default)          | Disabled (`DISABLE_TUNNEL=true`) |
+| Use case          | Development & testing      | Production                       |
 
 When deploying to a hosting provider like Cloud Run, set `DISABLE_TUNNEL=true` as an environment variable. This makes `run()` start only the HTTP server without opening a WebSocket tunnel to the proxy — the platform reaches your agent directly at its public URL.
 

package/dist/agent.d.ts

@@ -2,9 +2,47 @@ import { type AxiosInstance } from 'axios';
 import type { GetFilesParams, GetSecretsParams, GetSecretValueParams, UploadFileParams, DeleteFileParams, MarkTaskAsErroredParams, CompleteTaskParams, SendChatMessageParams, GetTaskDetailParams, GetAgentsParams, GetTasksParams, CreateTaskParams, AddLogToTaskParams, RequestHumanAssistanceParams, UpdateTaskStatusParams, ProcessParams, IntegrationCallRequest, GetChatMessagesParams, AgentChatMessagesResponse, GetFilesResponse, GetSecretsResponse, UploadFileResponse, DeleteFileResponse, GetTaskDetailResponse, GetAgentsResponse, GetTasksResponse, CreateTaskResponse, ActionSchema, DoTaskActionSchema, RespondChatMessageActionSchema } from './types';
 import type { ChatCompletionMessageParam, ChatCompletion } from 'openai/resources/chat/completions';
 import OpenAI from 'openai';
-import type { z } from 'zod';
+import { z } from 'zod';
 import { Capability } from './capability';
 import { type MCPServerConfig, MCPClient } from './mcp';
+/** Accept inputSchema (preferred) or schema (deprecated), never both */
+type WithInputSchema<S extends z.ZodTypeAny> = {
+    inputSchema: S;
+    schema?: never;
+} | {
+    schema: S;
+    inputSchema?: never;
+};
+/** Optional inputSchema for run-less caps -- can omit entirely (uses default) */
+type WithOptionalInputSchema<S extends z.ZodTypeAny> = {
+    inputSchema: S;
+    schema?: never;
+} | {
+    schema: S;
+    inputSchema?: never;
+} | {
+    inputSchema?: never;
+    schema?: never;
+};
+/** Capability with a run function -- inputSchema required, outputSchema not allowed */
+type RunnableCapabilityConfig<M extends string, S extends z.ZodTypeAny> = {
+    name: string;
+    description: string;
+    run(this: Agent<M>, params: {
+        args: z.infer<S>;
+        action: ActionSchema;
+    }, messages: ChatCompletionMessageParam[]): string | Promise<string>;
+    outputSchema?: never;
+} & WithInputSchema<S>;
+/** Capability without run -- inputSchema optional, outputSchema optional */
+type RunlessCapabilityConfig<S extends z.ZodTypeAny = z.ZodTypeAny> = {
+    name: string;
+    description: string;
+    run?: never;
+    outputSchema?: z.ZodTypeAny;
+} & WithOptionalInputSchema<S>;
+/** Union of all valid capability forms */
+export type CapabilityConfig<M extends string, S extends z.ZodTypeAny> = RunnableCapabilityConfig<M, S> | RunlessCapabilityConfig<S>;
 /**
  * Configuration options for creating a new Agent instance.
  */
@@ -31,9 +69,9 @@ export interface AgentOptions<T extends string> {
      */
     systemPrompt: string;
     /**
-     * The OpenAI API key for chat completions.
+     * Optional OpenAI API key for direct LLM access via process().
+     * NOT required for platform-deployed agents -- use generate() or run-less capabilities instead.
      * Can also be provided via OPENAI_API_KEY environment variable.
-     * Required when using the process() method.
      */
     openaiApiKey?: string;
     /**
@@ -82,7 +120,8 @@ export declare class Agent<M extends string = string> {
     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.
+     * Each capability is an instance of the Capability class with a name, description, inputSchema,
+     * and optionally a run function and/or outputSchema.
      * @protected
      */
     protected tools: Array<Capability<M, z.ZodTypeAny>>;
@@ -167,53 +206,32 @@ export declare class Agent<M extends string = string> {
     private initializeMCPClients;
     /**
      * 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.
+     * Each capability must have a unique name. Capabilities can be:
+     * - **Runnable**: has a `run` function and requires `inputSchema` (or deprecated `schema`)
+     * - **Run-less**: no `run` function -- the runtime handles execution via LLM.
+     *   `inputSchema` is optional (defaults to `{ input: z.string() }`), `outputSchema` is optional.
      *
      * @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 {ActionSchema} [capability.run.params.action] - Optional action context
-     * @param {ChatCompletionMessageParam[]} capability.run.messages - Chat message history
-     * @returns {this} The agent instance for method chaining
+     * @param capability - The capability configuration
+     * @returns The agent instance for method chaining
      * @throws {Error} If a capability with the same name already exists
+     * @throws {Error} If both `inputSchema` and `schema` are provided
+     * @throws {Error} If both `run` and `outputSchema` are provided
+     * @throws {Error} If a runnable capability omits `inputSchema`/`schema`
      */
-    addCapability<S extends z.ZodTypeAny>({ name, description, schema, run }: {
-        name: string;
-        description: string;
-        schema: S;
-        run(this: Agent<M>, params: {
-            args: z.infer<S>;
-            action?: ActionSchema;
-        }, messages: ChatCompletionMessageParam[]): string | Promise<string>;
-    }): this;
+    addCapability<S extends z.ZodTypeAny>(capability: CapabilityConfig<M, S>): this;
     /**
      * Adds multiple capabilities (tools) to the agent at once.
      * Each capability must have a unique name and not conflict with existing capabilities.
+     * Each element can be runnable or run-less independently.
      *
      * @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
+     * @param capabilities - Array of capability configurations
+     * @returns 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(this: Agent<M>, params: {
-                args: z.infer<T[K]>;
-                action?: ActionSchema;
-            }, messages: ChatCompletionMessageParam[]): string | Promise<string>;
-        };
+        [K in keyof T]: CapabilityConfig<M, T[K]>;
     }): this;
     /**
      * Gets files in a workspace.
@@ -370,6 +388,37 @@ export declare class Agent<M extends string = string> {
      * @returns {Promise<UpdateTaskStatusResponse>} The updated task details
      */
     updateTaskStatus(params: UpdateTaskStatusParams): Promise<undefined>;
+    /**
+     * Generate text via the OpenServ runtime.
+     * Billed to the workspace/task in the action.
+     * Use this inside custom `run` functions when you need LLM generation without your own OpenAI key.
+     *
+     * @param params.prompt - The prompt for the LLM
+     * @param params.messages - Optional conversation history for context
+     * @param params.action - Action context (required for billing)
+     * @returns The generated text
+     */
+    generate(params: {
+        prompt: string;
+        messages?: ChatCompletionMessageParam[];
+        action: ActionSchema;
+    }): Promise<string>;
+    /**
+     * Generate a structured object via the OpenServ runtime.
+     * Billed to the workspace/task in the action.
+     *
+     * @param params.prompt - The prompt for the LLM
+     * @param params.messages - Optional conversation history for context
+     * @param params.outputSchema - Zod schema for structured output
+     * @param params.action - Action context (required for billing)
+     * @returns The generated object, validated against the schema
+     */
+    generate<T extends z.ZodTypeAny>(params: {
+        prompt: string;
+        messages?: ChatCompletionMessageParam[];
+        outputSchema: T;
+        action: ActionSchema;
+    }): Promise<z.infer<T>>;
     /**
      * Processes a conversation with OpenAI, handling tool calls iteratively until completion.
      *
@@ -394,15 +443,18 @@ export declare class Agent<M extends string = string> {
     /**
      * Handles execution of a specific tool/capability.
      *
+     * The runtime calls this for both task execution (do-task) and chat (respond-chat-message),
+     * always providing the action context in the request body.
+     *
      * @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 {ActionSchema} [req.body.action] - Action context
+     * @param {ActionSchema} req.body.action - Action context (required)
      * @param {ChatCompletionMessageParam[]} [req.body.messages] - Message history
      * @returns {Promise<{result: string}>} The result of the tool execution
-     * @throws {BadRequest} If tool name is missing or tool is not found
+     * @throws {BadRequest} If tool name is missing, tool is not found, or action is missing
      * @throws {Error} If tool execution fails
      */
     handleToolRoute(req: {
@@ -479,4 +531,5 @@ export declare class Agent<M extends string = string> {
      */
     private addMCPToolsAsCapabilities;
 }
+export {};
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"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;AAMd;;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;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;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;AAED,qBAAa,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAqJ9B,OAAO,CAAC,OAAO;IApJ3B;;;;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;;;OAGG;IACI,MAAM,CAAC,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACI,SAAS,CAAC,EAAE,MAAM,CAAA;IAEzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKzE;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAgB;IAEjC;;;;OAIG;IACH,SAAS,CAAC,aAAa,EAAG,aAAa,CAAA;IAEvC;;;;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;;;;;OAKG;gBACiB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;IAa5C,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,YAAY;IAmBpB;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2J5B;;;;OAIG;IACG,IAAI;IAQV;;;OAGG;IACH,OAAO,CAAC,WAAW;IAOnB;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,WAAW,EAAE,sBAAsB;IASzD;;;;;;;;OAQG;IACH,OAAO,CAAC,yBAAyB;CAsClC"}
+{"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;AAC1C,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAmBvB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAGL,KAAK,eAAe,EAEpB,SAAS,EACV,MAAM,OAAO,CAAA;AA4Cd,wEAAwE;AACxE,KAAK,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,IACvC;IAAE,WAAW,EAAE,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAEtC,iFAAiF;AACjF,KAAK,uBAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,IAC/C;IAAE,WAAW,EAAE,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,GAClC;IAAE,WAAW,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAE3C,uFAAuF;AACvF,KAAK,wBAAwB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU,IAAI;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,CACD,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE;QAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAClD,QAAQ,EAAE,0BAA0B,EAAE,GACrC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3B,YAAY,CAAC,EAAE,KAAK,CAAA;CACrB,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AAEtB,4EAA4E;AAC5E,KAAK,uBAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IAAI;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,CAAC,EAAE,KAAK,CAAA;IACX,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU,CAAA;CAC5B,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAA;AAE9B,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU,IACjE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,uBAAuB,CAAC,CAAC,CAAC,CAAA;AAE9B;;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;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;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;AAED,qBAAa,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAuJ9B,OAAO,CAAC,OAAO;IAtJ3B;;;;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;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAK;IAExD;;;OAGG;IACI,MAAM,CAAC,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACI,SAAS,CAAC,EAAE,MAAM,CAAA;IAEzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKzE;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAgB;IAEjC;;;;OAIG;IACH,SAAS,CAAC,aAAa,EAAG,aAAa,CAAA;IAEvC;;;;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,GAYjB;IAED;;;;;OAKG;gBACiB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;IAa5C,OAAO,CAAC,oBAAoB;IAgB5B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IA2B/E;;;;;;;;;OASG;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,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;KAC1C,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;;;;;;;;;OASG;IACG,QAAQ,CAAC,MAAM,EAAE;QACrB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAA;QACvC,MAAM,EAAE,YAAY,CAAA;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACG,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE;QAC7C,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAA;QACvC,YAAY,EAAE,CAAC,CAAA;QACf,MAAM,EAAE,YAAY,CAAA;KACrB,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IA0BvB;;;;;;;OAOG;IACG,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAwHnE;;;;OAIG;cACa,MAAM,CAAC,MAAM,EAAE,kBAAkB;IAiCjD;;;;OAIG;cACa,aAAa,CAAC,MAAM,EAAE,8BAA8B;IAmCpE;;;;;;;;;;;;;;;;OAgBG;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;;;IAmCD;;;;;;;OAOG;IACG,eAAe,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE;IAgB5C;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAmBpB;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2J5B;;;;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

@@ -13,14 +13,61 @@ const helmet_1 = __importDefault(require("helmet"));
 const hpp_1 = __importDefault(require("hpp"));
 const logger_1 = require("./logger");
 const http_errors_1 = require("http-errors");
+const openai_1 = __importDefault(require("openai"));
+const zod_1 = require("zod");
 const zod_to_json_schema_1 = require("zod-to-json-schema");
 const json_schema_to_zod_1 = require("@n8n/json-schema-to-zod");
-const openai_1 = __importDefault(require("openai"));
+// Zod v4 has native toJSONSchema/fromJSONSchema. For v3 we use third-party libs.
+function zodToJsonSchema(schema, opts) {
+    if (typeof zod_1.z.toJSONSchema === 'function') {
+        return zod_1.z.toJSONSchema(schema);
+    }
+    return (0, zod_to_json_schema_1.zodToJsonSchema)(schema, opts);
+}
+function jsonSchemaToZodSchema(jsonSchema) {
+    if (typeof zod_1.z.fromJSONSchema === 'function') {
+        return zod_1.z.fromJSONSchema(jsonSchema);
+    }
+    return (0, json_schema_to_zod_1.jsonSchemaToZod)(jsonSchema);
+}
 const capability_1 = require("./capability");
 const mcp_1 = require("./mcp");
 const PLATFORM_URL = process.env.OPENSERV_API_URL || 'https://api.openserv.ai';
 const RUNTIME_URL = process.env.OPENSERV_RUNTIME_URL || 'https://agents.openserv.ai';
 const DEFAULT_PORT = Number.parseInt(process.env.PORT || '') || 7378;
+/** Default input schema for run-less capabilities that omit inputSchema */
+const DEFAULT_INPUT_SCHEMA = zod_1.z.object({ input: zod_1.z.string() });
+/** Runtime validation schema for capability configs */
+const capabilityConfigSchema = zod_1.z
+    .object({
+    name: zod_1.z.string().min(1),
+    description: zod_1.z.string().min(1),
+    inputSchema: zod_1.z.any().optional(),
+    schema: zod_1.z.any().optional(),
+    run: zod_1.z.any().optional(),
+    outputSchema: zod_1.z.any().optional()
+})
+    .superRefine((data, ctx) => {
+    if (data.inputSchema && data.schema) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Cannot provide both "inputSchema" and "schema". Use "inputSchema" ("schema" is deprecated).'
+        });
+    }
+    if (data.run && data.outputSchema) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Cannot provide both "run" and "outputSchema". "outputSchema" is only for run-less capabilities.'
+        });
+    }
+    if (!data.inputSchema && !data.schema && data.run) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Runnable capabilities require "inputSchema" (or deprecated "schema"). ' +
+                'Only run-less capabilities can omit it.'
+        });
+    }
+});
 class Agent {
     options;
     /**
@@ -55,7 +102,8 @@ class Agent {
     systemPrompt;
     /**
      * 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.
+     * Each capability is an instance of the Capability class with a name, description, inputSchema,
+     * and optionally a run function and/or outputSchema.
      * @protected
      */
     tools = [];
@@ -127,7 +175,7 @@ class Agent {
             function: {
                 name: tool.name,
                 description: tool.description,
-                parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(tool.schema)
+                parameters: zodToJsonSchema(tool.inputSchema)
             }
         }));
     }
@@ -142,7 +190,8 @@ class Agent {
         if (!this._openai) {
             const apiKey = this.options.openaiApiKey || process.env.OPENAI_API_KEY;
             if (!apiKey) {
-                throw new Error('OpenAI API key is required for process(). Please provide it in options or set OPENAI_API_KEY environment variable.');
+                throw new Error('OpenAI API key is required for process(). Provide it via options or OPENAI_API_KEY env var. ' +
+                    'Alternatively, use generate() for runtime-delegated LLM calls, or run-less capabilities.');
             }
             this._openai = new openai_1.default({ apiKey });
         }
@@ -180,41 +229,42 @@ class Agent {
     }
     /**
      * 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.
+     * Each capability must have a unique name. Capabilities can be:
+     * - **Runnable**: has a `run` function and requires `inputSchema` (or deprecated `schema`)
+     * - **Run-less**: no `run` function -- the runtime handles execution via LLM.
+     *   `inputSchema` is optional (defaults to `{ input: z.string() }`), `outputSchema` is optional.
      *
      * @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 {ActionSchema} [capability.run.params.action] - Optional action context
-     * @param {ChatCompletionMessageParam[]} capability.run.messages - Chat message history
-     * @returns {this} The agent instance for method chaining
+     * @param capability - The capability configuration
+     * @returns The agent instance for method chaining
      * @throws {Error} If a capability with the same name already exists
+     * @throws {Error} If both `inputSchema` and `schema` are provided
+     * @throws {Error} If both `run` and `outputSchema` are provided
+     * @throws {Error} If a runnable capability omits `inputSchema`/`schema`
      */
-    addCapability({ name, description, schema, run }) {
-        // Validate tool name uniqueness
+    addCapability(capability) {
+        const result = capabilityConfigSchema.safeParse(capability);
+        if (!result.success) {
+            throw new Error(result.error.issues[0]?.message ?? 'Invalid capability configuration');
+        }
+        const { name, description, run, outputSchema } = result.data;
+        const resolvedSchema = (result.data.inputSchema ??
+            result.data.schema ??
+            DEFAULT_INPUT_SCHEMA);
         if (this.tools.some(tool => tool.name === name)) {
             throw new Error(`Tool with name "${name}" already exists`);
         }
-        // Type assertion through unknown for safe conversion between compatible generic types
-        this.tools.push(new capability_1.Capability(name, description, schema, run));
+        this.tools.push(new capability_1.Capability(name, description, resolvedSchema, typeof run === 'function' ? run : undefined, outputSchema));
         return this;
     }
     /**
      * Adds multiple capabilities (tools) to the agent at once.
      * Each capability must have a unique name and not conflict with existing capabilities.
+     * Each element can be runnable or run-less independently.
      *
      * @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
+     * @param capabilities - Array of capability configurations
+     * @returns The agent instance for method chaining
      * @throws {Error} If any capability has a name that already exists
      */
     addCapabilities(capabilities) {
@@ -479,6 +529,24 @@ class Agent {
         });
         return response.data;
     }
+    async generate(params) {
+        const response = await this.runtimeClient.post('/generate', {
+            prompt: params.prompt,
+            ...(params.messages ? { messages: params.messages } : {}),
+            ...(params.outputSchema ? { outputSchema: zodToJsonSchema(params.outputSchema) } : {}),
+            action: params.action
+        });
+        if (params.outputSchema) {
+            if (response.data.object === undefined || response.data.object === null) {
+                throw new Error('Runtime returned no structured output for generate() with outputSchema');
+            }
+            return params.outputSchema.parse(response.data.object);
+        }
+        if (typeof response.data.text !== 'string') {
+            throw new Error('Runtime returned no text for generate()');
+        }
+        return response.data.text;
+    }
     /**
      * Processes a conversation with OpenAI, handling tool calls iteratively until completion.
      *
@@ -491,7 +559,8 @@ class Agent {
         try {
             const apiKey = this.options.openaiApiKey || process.env.OPENAI_API_KEY;
             if (!apiKey) {
-                throw new Error('OpenAI API key is required for process(). Please provide it in options or set OPENAI_API_KEY environment variable.');
+                throw new Error('OpenAI API key is required for process(). Provide it via options or OPENAI_API_KEY env var. ' +
+                    'Alternatively, use generate() for runtime-delegated LLM calls, or run-less capabilities.');
             }
             const currentMessages = [...messages];
             if (!currentMessages.find(m => m.content === this.systemPrompt)) {
@@ -530,8 +599,35 @@ class Agent {
                         if (!tool) {
                             throw new Error(`Tool "${name}" not found`);
                         }
-                        // Call the tool's run method with the parsed arguments and bind this
-                        const result = await tool.run.bind(this)({ args: parsedArgs }, currentMessages);
+                        let result;
+                        if (tool.run) {
+                            // Call the tool's run method with the parsed arguments and bind this
+                            result = await tool.run.bind(this)({ args: parsedArgs }, currentMessages);
+                        }
+                        else {
+                            // Shim: use OpenAI with conversation history + description for run-less capabilities
+                            const shimCompletion = await this.openai.chat.completions.create({
+                                model: 'gpt-4o',
+                                messages: [
+                                    ...currentMessages,
+                                    { role: 'system', content: tool.description },
+                                    { role: 'user', content: JSON.stringify(parsedArgs) }
+                                ],
+                                ...(tool.outputSchema
+                                    ? {
+                                        response_format: {
+                                            type: 'json_schema',
+                                            json_schema: {
+                                                name: tool.name,
+                                                schema: zodToJsonSchema(tool.outputSchema),
+                                                strict: true
+                                            }
+                                        }
+                                    }
+                                    : {})
+                            });
+                            result = shimCompletion.choices[0]?.message?.content || '';
+                        }
                         return {
                             role: 'tool',
                             content: JSON.stringify(result),
@@ -582,9 +678,12 @@ class Agent {
                 content: action.task.description
             });
         }
+        const proxyTools = this.tools.filter(t => t.run);
+        const runtimeTools = this.tools.filter(t => !t.run);
         try {
             await this.runtimeClient.post('/execute', {
-                tools: this.tools.map(convertToolToJsonSchema),
+                tools: proxyTools.map(convertProxyToolToJsonSchema),
+                runtimeTools: runtimeTools.map(convertRuntimeToolToJsonSchema),
                 messages,
                 action
             });
@@ -616,9 +715,12 @@ class Agent {
                 });
             }
         }
+        const proxyTools = this.tools.filter(t => t.run);
+        const runtimeTools = this.tools.filter(t => !t.run);
         try {
             await this.runtimeClient.post('/chat', {
-                tools: this.tools.map(convertToolToJsonSchema),
+                tools: proxyTools.map(convertProxyToolToJsonSchema),
+                runtimeTools: runtimeTools.map(convertRuntimeToolToJsonSchema),
                 messages,
                 action
             });
@@ -633,15 +735,18 @@ class Agent {
     /**
      * Handles execution of a specific tool/capability.
      *
+     * The runtime calls this for both task execution (do-task) and chat (respond-chat-message),
+     * always providing the action context in the request body.
+     *
      * @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 {ActionSchema} [req.body.action] - Action context
+     * @param {ActionSchema} req.body.action - Action context (required)
      * @param {ChatCompletionMessageParam[]} [req.body.messages] - Message history
      * @returns {Promise<{result: string}>} The result of the tool execution
-     * @throws {BadRequest} If tool name is missing or tool is not found
+     * @throws {BadRequest} If tool name is missing, tool is not found, or action is missing
      * @throws {Error} If tool execution fails
      */
     async handleToolRoute(req) {
@@ -653,7 +758,13 @@ class Agent {
             if (!tool) {
                 throw new http_errors_1.BadRequest(`Tool "${req.params.toolName}" not found`);
             }
-            const args = await tool.schema.parseAsync(req.body?.args);
+            if (!tool.run) {
+                throw new http_errors_1.BadRequest(`Tool "${req.params.toolName}" is a run-less capability handled by the runtime, not by this agent.`);
+            }
+            if (!req.body?.action) {
+                throw new http_errors_1.BadRequest('Action context is required for tool execution');
+            }
+            const args = await tool.inputSchema.parseAsync(req.body?.args);
             const messages = req.body.messages || [];
             const result = await tool.run.call(this, { args, action: req.body.action }, messages);
             return { result };
@@ -905,7 +1016,7 @@ class Agent {
             this.addCapability({
                 name: capabilityName,
                 description: tool.description || `Tool from MCP server ${serverId}`,
-                schema: (0, json_schema_to_zod_1.jsonSchemaToZod)(inputSchema),
+                inputSchema: jsonSchemaToZodSchema(inputSchema),
                 async run({ args }) {
                     const mcpClient = this.mcpClients[serverId];
                     if (!mcpClient) {
@@ -930,10 +1041,18 @@ class Agent {
     }
 }
 exports.Agent = Agent;
-function convertToolToJsonSchema(tool) {
+function convertProxyToolToJsonSchema(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        schema: zodToJsonSchema(tool.inputSchema)
+    };
+}
+function convertRuntimeToolToJsonSchema(tool) {
     return {
         name: tool.name,
         description: tool.description,
-        schema: (0, zod_to_json_schema_1.zodToJsonSchema)(tool.schema)
+        schema: zodToJsonSchema(tool.inputSchema),
+        ...(tool.outputSchema ? { outputSchema: zodToJsonSchema(tool.outputSchema) } : {})
     };
 }

package/dist/capability.d.ts

@@ -5,8 +5,11 @@ import type { Agent } from './agent';
 export declare class Capability<M extends string, Schema extends z.ZodTypeAny> {
     readonly name: string;
     readonly description: string;
+    readonly run?: ((this: Agent<M>, params: CapabilityFuncParams<Schema>, messages: ChatCompletionMessageParam[]) => string | Promise<string>) | undefined;
+    readonly outputSchema?: z.ZodTypeAny | undefined;
+    readonly inputSchema: Schema;
+    /** @deprecated Use `inputSchema` instead */
     readonly schema: Schema;
-    readonly run: (this: Agent<M>, params: CapabilityFuncParams<Schema>, messages: ChatCompletionMessageParam[]) => string | Promise<string>;
-    constructor(name: string, description: string, schema: Schema, run: (this: Agent<M>, params: CapabilityFuncParams<Schema>, messages: ChatCompletionMessageParam[]) => string | Promise<string>);
+    constructor(name: string, description: string, inputSchema: Schema, run?: ((this: Agent<M>, params: CapabilityFuncParams<Schema>, messages: ChatCompletionMessageParam[]) => string | Promise<string>) | undefined, outputSchema?: z.ZodTypeAny | undefined);
 }
 //# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAA;AACnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,qBAAa,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,SAAS,CAAC,CAAC,UAAU;aAEjD,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,MAAM;aACnB,MAAM,EAAE,MAAM;aACd,GAAG,EAAE,CACnB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACpC,QAAQ,EAAE,0BAA0B,EAAE,KACnC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAPb,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CACnB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACpC,QAAQ,EAAE,0BAA0B,EAAE,KACnC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAEhC"}
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAA;AACnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,qBAAa,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,SAAS,CAAC,CAAC,UAAU;aAMjD,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,MAAM;aAEnB,GAAG,CAAC,GAAE,CACpB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACpC,QAAQ,EAAE,0BAA0B,EAAE,KACnC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;aACb,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU;IAb7C,SAAgB,WAAW,EAAE,MAAM,CAAA;IACnC,4CAA4C;IAC5C,SAAgB,MAAM,EAAE,MAAM,CAAA;gBAGZ,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnC,WAAW,EAAE,MAAM,EACH,GAAG,CAAC,GAAE,CACpB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EACd,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACpC,QAAQ,EAAE,0BAA0B,EAAE,KACnC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAA,EACb,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU,YAAA;CAK9C"}

package/dist/capability.js

@@ -4,13 +4,18 @@ exports.Capability = void 0;
 class Capability {
     name;
     description;
-    schema;
     run;
-    constructor(name, description, schema, run) {
+    outputSchema;
+    inputSchema;
+    /** @deprecated Use `inputSchema` instead */
+    schema;
+    constructor(name, description, inputSchema, run, outputSchema) {
         this.name = name;
         this.description = description;
-        this.schema = schema;
         this.run = run;
+        this.outputSchema = outputSchema;
+        this.inputSchema = inputSchema;
+        this.schema = inputSchema;
     }
 }
 exports.Capability = Capability;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Agent } from './agent';
-export type { AgentOptions } from './agent';
+export type { AgentOptions, CapabilityConfig } from './agent';
 export { Capability } from './capability';
 export { OpenServTunnel } from './tunnel';
 export type { OpenServTunnelOptions, RequestData, ResponseData, TunnelState, TunnelEvent } from './tunnel';

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;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"}
+{"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,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC7D,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/run.d.ts

@@ -45,7 +45,7 @@ export interface RunResult {
  * agent.addCapability({
  *   name: 'greet',
  *   description: 'Greet someone',
- *   schema: z.object({ name: z.string() }),
+ *   inputSchema: z.object({ name: z.string() }),
  *   run: async ({ args }) => `Hello, ${args.name}!`
  * })
  *

package/dist/run.js

@@ -28,7 +28,7 @@ const tunnel_1 = require("./tunnel");
  * agent.addCapability({
  *   name: 'greet',
  *   description: 'Greet someone',
- *   schema: z.object({ name: z.string() }),
+ *   inputSchema: z.object({ name: z.string() }),
  *   run: async ({ args }) => `Hello, ${args.name}!`
  * })
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openserv-labs/sdk",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "OpenServ Agent SDK - Create AI agents easily",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,7 +44,6 @@
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^7.3.0",
     "@modelcontextprotocol/sdk": "^1.10.2",
-    "@n8n/json-schema-to-zod": "^1.1.0",
     "axios": "^1.6.8",
     "axios-retry": "^4.1.0",
     "bcryptjs": "^3.0.2",
@@ -57,8 +56,8 @@
     "pino": "^9.6.0",
     "pino-pretty": "^13.1.3",
     "ws": "^8.18.0",
-    "zod": "^3.22.4",
-    "zod-to-json-schema": "^3.22.4"
+    "zod-to-json-schema": "^3.25.0",
+    "@n8n/json-schema-to-zod": "^1.1.0"
   },
   "devDependencies": {
     "@tsconfig/strictest": "^2.0.3",
@@ -92,6 +91,7 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "openai": "^5.0.1"
+    "openai": "^5.0.1",
+    "zod": "^3.22.4 || ^4.0.0"
   }
 }