@reminix/runtime 0.0.13 → 0.0.16

package/dist/agent.js

@@ -2,17 +2,125 @@
  * Agent classes for Reminix Runtime.
  */
 import { VERSION } from './version.js';
-/**
- * Default parameters schema for agents.
- * Request: { prompt: '...' }
- */
-const DEFAULT_AGENT_PARAMETERS = {
+/** Default template when none specified and no custom input/output. */
+const DEFAULT_AGENT_TEMPLATE = 'prompt';
+/** JSON schema for a single tool call (OpenAI-style). */
+const TOOL_CALL_ITEM_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: { type: 'string', description: 'Tool call id' },
+        type: { type: 'string', enum: ['function'], description: 'Tool call type' },
+        function: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Function/tool name' },
+                arguments: { type: 'string', description: 'JSON string of arguments' },
+            },
+            required: ['name', 'arguments'],
+        },
+    },
+    required: ['id', 'type', 'function'],
+};
+/** JSON schema for a message item (OpenAI-style; supports tool_calls and tool results). */
+const CHAT_INPUT_MESSAGE_ITEMS = {
     type: 'object',
     properties: {
-        prompt: { type: 'string', description: 'The prompt or task for the agent' },
+        role: { type: 'string', description: 'Message role (user, assistant, system, tool)' },
+        content: { type: 'string', description: 'Message content', nullable: true },
+        tool_calls: {
+            type: 'array',
+            description: 'Tool calls requested by the model (assistant messages)',
+            items: TOOL_CALL_ITEM_SCHEMA,
+        },
+        tool_call_id: {
+            type: 'string',
+            description: 'Id of the tool call this message is a result for (tool messages)',
+        },
+        name: { type: 'string', description: 'Tool name (tool messages)' },
+    },
+};
+const AGENT_TEMPLATES = {
+    prompt: {
+        input: {
+            type: 'object',
+            properties: {
+                prompt: { type: 'string', description: 'The prompt or task for the agent' },
+            },
+            required: ['prompt'],
+        },
+        output: { type: 'string' },
+    },
+    chat: {
+        input: {
+            type: 'object',
+            properties: {
+                messages: {
+                    type: 'array',
+                    description: 'Chat messages (OpenAI-style)',
+                    items: CHAT_INPUT_MESSAGE_ITEMS,
+                },
+            },
+            required: ['messages'],
+        },
+        output: { type: 'string' },
+    },
+    task: {
+        input: {
+            type: 'object',
+            properties: {
+                task: { type: 'string', description: 'Task name or description' },
+            },
+            required: ['task'],
+            additionalProperties: true,
+        },
+        output: {
+            description: 'Structured JSON result (object, array, string, number, boolean, or null)',
+            type: 'object',
+            additionalProperties: true,
+        },
+    },
+    rag: {
+        input: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'The question to answer from documents' },
+                messages: {
+                    type: 'array',
+                    description: 'Optional prior conversation (chat-style RAG)',
+                    items: CHAT_INPUT_MESSAGE_ITEMS,
+                },
+                collectionIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional knowledge collection IDs to scope the search',
+                },
+            },
+            required: ['query'],
+        },
+        output: { type: 'string' },
+    },
+    thread: {
+        input: {
+            type: 'object',
+            properties: {
+                messages: {
+                    type: 'array',
+                    description: 'Chat messages with tool_calls and tool results (OpenAI-style)',
+                    items: CHAT_INPUT_MESSAGE_ITEMS,
+                },
+            },
+            required: ['messages'],
+        },
+        output: {
+            type: 'array',
+            description: 'Updated message thread (OpenAI-style, may include assistant message and tool_calls)',
+            items: CHAT_INPUT_MESSAGE_ITEMS,
+        },
     },
-    required: ['prompt'],
 };
+/** Default input/output schemas (same as prompt template). Used by AgentBase and custom agents. */
+const DEFAULT_AGENT_INPUT = AGENT_TEMPLATES[DEFAULT_AGENT_TEMPLATE].input;
+const DEFAULT_AGENT_OUTPUT = AGENT_TEMPLATES[DEFAULT_AGENT_TEMPLATE].output;
 /**
  * Abstract base class defining the agent interface.
  *
@@ -21,29 +129,22 @@ const DEFAULT_AGENT_PARAMETERS = {
  * `AgentAdapter` for framework adapters.
  */
 export class AgentBase {
-    /**
-     * Whether execute supports streaming. Override to enable.
-     */
-    get streaming() {
-        return false;
-    }
     /**
      * Return agent metadata for discovery.
      * Override this to provide custom metadata.
      */
     get metadata() {
         return {
-            type: 'agent',
-            parameters: DEFAULT_AGENT_PARAMETERS,
-            requestKeys: ['prompt'],
-            responseKeys: ['content'],
+            capabilities: { streaming: false },
+            input: DEFAULT_AGENT_INPUT,
+            output: DEFAULT_AGENT_OUTPUT,
         };
     }
     /**
-     * Handle a streaming execute request.
+     * Handle a streaming invoke request.
      */
     // eslint-disable-next-line require-yield
-    async *executeStream(_request) {
+    async *invokeStream(_request) {
         throw new Error('Streaming not implemented for this agent');
     }
     /**
@@ -96,7 +197,6 @@ export class AgentBase {
                             {
                                 name: this.name,
                                 ...this.metadata,
-                                streaming: this.streaming,
                             },
                         ],
                     }, { headers: corsHeaders });
@@ -106,38 +206,29 @@ export class AgentBase {
                 if (method === 'POST' && invokeMatch) {
                     const agentName = invokeMatch[1];
                     if (agentName !== this.name) {
-                        return Response.json({ error: `Agent '${agentName}' not found` }, { status: 404, headers: corsHeaders });
+                        return Response.json({ error: { type: 'NotFoundError', message: `Agent '${agentName}' not found` } }, { status: 404, headers: corsHeaders });
                     }
                     const body = (await request.json());
-                    // Get requestKeys from agent metadata (all agents have defaults)
-                    const requestKeys = this.metadata.requestKeys ?? [];
-                    // Extract declared keys from body into input object
-                    // e.g., requestKeys: ['prompt'] with body { prompt: '...' } -> input = { prompt: '...' }
-                    const input = {};
-                    for (const key of requestKeys) {
-                        if (key in body) {
-                            input[key] = body[key];
-                        }
-                    }
-                    const executeRequest = {
-                        input,
+                    const invokeRequest = {
+                        input: body.input ?? {},
                         stream: body.stream === true,
                         context: body.context,
                     };
                     // Handle streaming
-                    if (executeRequest.stream) {
+                    if (invokeRequest.stream) {
                         const stream = new ReadableStream({
                             start: async (controller) => {
                                 const encoder = new TextEncoder();
                                 try {
-                                    for await (const chunk of this.executeStream(executeRequest)) {
-                                        controller.enqueue(encoder.encode(`data: ${chunk}\n\n`));
+                                    for await (const chunk of this.invokeStream(invokeRequest)) {
+                                        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ delta: chunk })}\n\n`));
                                     }
-                                    controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+                                    controller.enqueue(encoder.encode(`data: ${JSON.stringify({ done: true })}\n\n`));
                                 }
                                 catch (error) {
                                     const message = error instanceof Error ? error.message : 'Unknown error';
-                                    controller.enqueue(encoder.encode(`data: ${JSON.stringify({ error: message })}\n\n`));
+                                    const errorType = error instanceof Error ? error.constructor.name : 'ExecutionError';
+                                    controller.enqueue(encoder.encode(`data: ${JSON.stringify({ error: { type: errorType, message } })}\n\n`));
                                 }
                                 controller.close();
                             },
@@ -151,15 +242,16 @@ export class AgentBase {
                             },
                         });
                     }
-                    const response = await this.execute(executeRequest);
+                    const response = await this.invoke(invokeRequest);
                     return Response.json(response, { headers: corsHeaders });
                 }
                 // Not found
-                return Response.json({ error: 'Not found' }, { status: 404, headers: corsHeaders });
+                return Response.json({ error: { type: 'NotFoundError', message: 'Not found' } }, { status: 404, headers: corsHeaders });
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : 'Unknown error';
-                return Response.json({ error: message }, { status: 500, headers: corsHeaders });
+                const errorType = error instanceof Error ? error.constructor.name : 'ExecutionError';
+                return Response.json({ error: { type: errorType, message } }, { status: 500, headers: corsHeaders });
             }
         };
     }
@@ -182,8 +274,8 @@ export class AgentBase {
 export class Agent extends AgentBase {
     _name;
     _metadata;
-    _executeHandler = null;
-    _executeStreamHandler = null;
+    _invokeHandler = null;
+    _invokeStreamHandler = null;
     /**
      * Create a new agent.
      *
@@ -206,19 +298,15 @@ export class Agent extends AgentBase {
      */
     get metadata() {
         return {
-            type: 'agent',
-            parameters: DEFAULT_AGENT_PARAMETERS,
-            requestKeys: ['prompt'],
-            responseKeys: ['content'],
+            capabilities: {
+                streaming: this._invokeStreamHandler !== null,
+                ...this._metadata.capabilities,
+            },
+            input: this._metadata.input ?? DEFAULT_AGENT_INPUT,
+            output: this._metadata.output ?? DEFAULT_AGENT_OUTPUT,
             ...this._metadata,
         };
     }
-    /**
-     * Whether execute supports streaming.
-     */
-    get streaming() {
-        return this._executeStreamHandler !== null;
-    }
     /**
      * Register a handler.
      *
@@ -228,7 +316,7 @@ export class Agent extends AgentBase {
      * });
      */
     handler(fn) {
-        this._executeHandler = fn;
+        this._invokeHandler = fn;
         return this;
     }
     /**
@@ -236,31 +324,31 @@ export class Agent extends AgentBase {
      *
      * @example
      * agent.streamHandler(async function* (request) {
-     *   yield '{"chunk": "Hello"}';
-     *   yield '{"chunk": " world!"}';
+     *   yield 'Hello';
+     *   yield ' world!';
      * });
      */
     streamHandler(fn) {
-        this._executeStreamHandler = fn;
+        this._invokeStreamHandler = fn;
         return this;
     }
     /**
-     * Handle an execute request.
+     * Handle an invoke request.
      */
-    async execute(request) {
-        if (this._executeHandler === null) {
-            throw new Error(`No execute handler registered for agent '${this._name}'`);
+    async invoke(request) {
+        if (this._invokeHandler === null) {
+            throw new Error(`No invoke handler registered for agent '${this._name}'`);
         }
-        return this._executeHandler(request);
+        return this._invokeHandler(request);
     }
     /**
-     * Handle a streaming execute request.
+     * Handle a streaming invoke request.
      */
-    async *executeStream(request) {
-        if (this._executeStreamHandler === null) {
-            throw new Error(`No streaming execute handler registered for agent '${this._name}'`);
+    async *invokeStream(request) {
+        if (this._invokeStreamHandler === null) {
+            throw new Error(`No streaming invoke handler registered for agent '${this._name}'`);
         }
-        yield* this._executeStreamHandler(request);
+        yield* this._invokeStreamHandler(request);
     }
 }
 /**
@@ -269,77 +357,38 @@ export class Agent extends AgentBase {
 function isAsyncGeneratorFunction(fn) {
     return fn?.constructor?.name === 'AsyncGeneratorFunction';
 }
-/**
- * Wrap output schema to match the full response structure based on responseKeys.
- *
- * If responseKeys = ["output"], wraps the schema as { output: <schema> }
- * If responseKeys = ["message"], wraps the schema as { message: <schema> }
- * If responseKeys = ["message", "output"], wraps as { message: <schema>, output: <schema> }
- *
- * @param outputSchema - The schema for the return value (or undefined)
- * @param responseKeys - List of top-level response keys
- * @returns Wrapped schema describing the full response object, or undefined if outputSchema is undefined
- */
-function wrapOutputSchemaForResponseKeys(outputSchema, responseKeys) {
-    if (outputSchema === undefined || responseKeys.length === 0) {
-        return undefined;
-    }
-    // If single response key, wrap the output schema
-    if (responseKeys.length === 1) {
-        return {
-            type: 'object',
-            properties: { [responseKeys[0]]: outputSchema },
-            required: responseKeys,
-        };
-    }
-    // Multiple response keys - need to split the output schema
-    // For now, assume the output schema describes the first key's value
-    // and other keys are optional/unknown
-    const properties = { [responseKeys[0]]: outputSchema };
-    const required = [responseKeys[0]];
-    // For additional keys, we don't know their schema, so mark as optional
-    // Users can override via metadata if they need full schema
-    for (const key of responseKeys.slice(1)) {
-        properties[key] = { type: 'object' }; // Placeholder - should be overridden
-    }
-    return {
-        type: 'object',
-        properties,
-        required,
-    };
-}
 /**
  * Create an agent from a configuration object.
  *
- * By default, agents expect `{ prompt: string }` in the request body and
- * return `{ output: ... }`. You can customize by providing `parameters`.
+ * By default, agents expect `{ input: { prompt: string } }` in the request body and
+ * return `{ output: string }`. You can customize by providing `input` schema.
  *
  * @example
  * ```typescript
- * // Simple agent with default parameters
- * // Request: { prompt: 'Hello world' }
+ * // Simple agent with default input/output
+ * // Request: { input: { prompt: 'Hello world' } }
  * // Response: { output: 'You said: Hello world' }
  * const echo = agent('echo', {
  *   description: 'Echo the prompt',
  *   handler: async ({ prompt }) => `You said: ${prompt}`,
  * });
  *
- * // Agent with custom parameters
- * // Request: { a: 1, b: 2 }
+ * // Agent with custom input schema
+ * // Request: { input: { a: 1, b: 2 } }
  * // Response: { output: 3 }
  * const calculator = agent('calculator', {
  *   description: 'Add two numbers',
- *   parameters: {
+ *   input: {
  *     type: 'object',
  *     properties: { a: { type: 'number' }, b: { type: 'number' } },
  *     required: ['a', 'b'],
  *   },
+ *   output: { type: 'number' },
  *   handler: async ({ a, b }) => (a as number) + (b as number),
  * });
  *
  * // Streaming agent (async generator)
- * // Request: { prompt: 'hello world' }
- * // Response: { output: 'hello world ' } (streamed)
+ * // Request: { input: { prompt: 'hello world' }, stream: true }
  * const streamer = agent('streamer', {
  *   description: 'Stream text word by word',
  *   handler: async function* ({ prompt }) {
@@ -351,43 +400,25 @@ function wrapOutputSchemaForResponseKeys(outputSchema, responseKeys) {
  * ```
  */
 export function agent(name, options) {
-    // Use provided parameters or default to { prompt: string }
-    const parameters = options.parameters ?? DEFAULT_AGENT_PARAMETERS;
-    // Derive requestKeys from parameters.properties
-    const requestKeys = Object.keys(parameters.properties);
-    // Default responseKeys (can be overridden via metadata)
-    const responseKeys = ['content'];
-    // Wrap output schema to match responseKeys structure
-    const wrappedOutput = wrapOutputSchemaForResponseKeys(options.output, responseKeys);
-    // Build metadata (allow metadata override to change responseKeys)
-    const baseMetadata = {
-        type: 'agent',
-        description: options.description,
-        parameters,
-        requestKeys,
-        responseKeys,
-    };
-    // If metadata override includes responseKeys, re-wrap output schema
-    const finalResponseKeys = options.metadata?.responseKeys ?? responseKeys;
-    const finalWrappedOutput = options.metadata?.responseKeys !== undefined
-        ? wrapOutputSchemaForResponseKeys(options.output, finalResponseKeys)
-        : wrappedOutput;
-    if (finalWrappedOutput !== undefined) {
-        baseMetadata.output = finalWrappedOutput;
-    }
+    // Default template is 'prompt' when no template and no custom input/output
+    const effectiveTemplate = options.template ??
+        (options.input === undefined && options.output === undefined
+            ? DEFAULT_AGENT_TEMPLATE
+            : undefined);
+    const inputSchema = options.input ??
+        (effectiveTemplate ? AGENT_TEMPLATES[effectiveTemplate].input : DEFAULT_AGENT_INPUT);
+    const outputSchema = options.output ??
+        (effectiveTemplate ? AGENT_TEMPLATES[effectiveTemplate].output : DEFAULT_AGENT_OUTPUT);
     const agentInstance = new Agent(name, {
         metadata: {
-            ...baseMetadata,
-            ...options.metadata,
+            description: options.description,
+            input: inputSchema,
+            output: outputSchema,
+            ...(effectiveTemplate !== undefined && { template: effectiveTemplate }),
         },
     });
     // Detect if handler is an async generator function
     const isStreaming = isAsyncGeneratorFunction(options.handler);
-    // Get the response keys from the agent's metadata (allows custom override)
-    const getResponseKeys = () => {
-        const keys = agentInstance.metadata.responseKeys;
-        return keys && keys.length > 0 ? keys : ['content'];
-    };
     if (isStreaming) {
         const streamFn = options.handler;
         // Register streaming handler
@@ -400,194 +431,14 @@ export function agent(name, options) {
             for await (const chunk of streamFn(request.input, request.context)) {
                 chunks.push(chunk);
             }
-            const result = chunks.join('');
-            // If result is dict, use as-is; otherwise wrap in first responseKey
-            if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
-                return result;
-            }
-            const responseKeys = getResponseKeys();
-            return { [responseKeys[0]]: result };
+            return { output: chunks.join('') };
         });
     }
     else {
         const regularHandler = options.handler;
         agentInstance.handler(async (request) => {
             const result = await regularHandler(request.input, request.context);
-            // If result is dict with all responseKeys, use as-is; otherwise wrap in first responseKey
-            const responseKeys = getResponseKeys();
-            if (typeof result === 'object' &&
-                result !== null &&
-                !Array.isArray(result) &&
-                responseKeys.every((key) => key in result)) {
-                return result;
-            }
-            return { [responseKeys[0]]: result };
-        });
-    }
-    return agentInstance;
-}
-/**
- * Create a chat agent from a configuration object.
- *
- * This is a convenience factory that creates an agent with a standard chat
- * interface (messages in, messages out).
- *
- * Request: `{ messages: [...] }`
- * Response: `{ messages: [{ role: 'assistant', content: '...' }, ...] }`
- *
- * @example
- * ```typescript
- * // Non-streaming chat agent
- * // Request: { messages: [{ role: 'user', content: 'hello' }] }
- * // Response: { messages: [{ role: 'assistant', content: 'You said: hello' }] }
- * const bot = chatAgent('bot', {
- *   description: 'A simple chatbot',
- *   handler: async (messages) => {
- *     const lastMsg = messages.at(-1)?.content ?? '';
- *     return [{ role: 'assistant', content: `You said: ${lastMsg}` }];
- *   },
- * });
- *
- * // Streaming chat agent (async generator)
- * const streamingBot = chatAgent('streaming-bot', {
- *   description: 'A streaming chatbot',
- *   handler: async function* (messages) {
- *     yield 'Hello';
- *     yield ' ';
- *     yield 'world!';
- *   },
- * });
- * ```
- */
-export function chatAgent(name, options) {
-    // Chat agents have default request/response keys (can be overridden via metadata)
-    const requestKeys = ['messages'];
-    const responseKeys = ['messages'];
-    // Message item schema (shared between parameters and output)
-    const messageItemSchema = {
-        type: 'object',
-        properties: {
-            role: {
-                type: 'string',
-                enum: ['system', 'user', 'assistant', 'tool'],
-            },
-            content: {
-                type: ['string', 'null'],
-            },
-            name: {
-                type: 'string',
-            },
-            tool_call_id: {
-                type: 'string',
-            },
-            tool_calls: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    properties: {
-                        id: { type: 'string' },
-                        type: { type: 'string', enum: ['function'] },
-                        function: {
-                            type: 'object',
-                            properties: {
-                                name: { type: 'string' },
-                                arguments: { type: 'string' },
-                            },
-                            required: ['name', 'arguments'],
-                        },
-                    },
-                    required: ['id', 'type', 'function'],
-                },
-            },
-        },
-        required: ['role'],
-    };
-    // Define standard chat agent schemas
-    const parametersSchema = {
-        type: 'object',
-        properties: {
-            messages: {
-                type: 'array',
-                items: messageItemSchema,
-            },
-        },
-        required: ['messages'],
-    };
-    // Messages schema (array of messages, the value, not the full response)
-    const messagesSchema = {
-        type: 'array',
-        items: messageItemSchema,
-    };
-    // Wrap messages schema to match responseKeys structure
-    const wrappedOutput = wrapOutputSchemaForResponseKeys(messagesSchema, responseKeys);
-    // Build metadata (allow metadata override to change responseKeys)
-    const baseMetadata = {
-        type: 'chat_agent',
-        description: options.description,
-        parameters: parametersSchema,
-        requestKeys,
-        responseKeys,
-    };
-    // If metadata override includes responseKeys, re-wrap output schema
-    const finalResponseKeys = options.metadata?.responseKeys ?? responseKeys;
-    const finalWrappedOutput = options.metadata?.responseKeys !== undefined
-        ? wrapOutputSchemaForResponseKeys(messagesSchema, finalResponseKeys)
-        : wrappedOutput;
-    if (finalWrappedOutput !== undefined) {
-        baseMetadata.output = finalWrappedOutput;
-    }
-    const agentInstance = new Agent(name, {
-        metadata: {
-            ...baseMetadata,
-            ...options.metadata,
-        },
-    });
-    // Detect if handler is an async generator function
-    const isStreaming = isAsyncGeneratorFunction(options.handler);
-    // Get the response keys from the agent's metadata (allows custom override)
-    const getResponseKeys = () => {
-        const keys = agentInstance.metadata.responseKeys;
-        return keys && keys.length > 0 ? keys : ['messages'];
-    };
-    if (isStreaming) {
-        const streamFn = options.handler;
-        // Register streaming handler
-        agentInstance.streamHandler(async function* (request) {
-            const rawMessages = (request.input.messages ?? []);
-            yield* streamFn(rawMessages, request.context);
-        });
-        // Also register non-streaming handler that collects chunks
-        agentInstance.handler(async (request) => {
-            const rawMessages = (request.input.messages ?? []);
-            const chunks = [];
-            for await (const chunk of streamFn(rawMessages, request.context)) {
-                chunks.push(chunk);
-            }
-            const result = [{ role: 'assistant', content: chunks.join('') }];
-            // For chat agents, always wrap in first responseKey (typically "messages")
-            const responseKeys = getResponseKeys();
-            return { [responseKeys[0]]: result };
-        });
-    }
-    else {
-        const regularHandler = options.handler;
-        agentInstance.handler(async (request) => {
-            const rawMessages = (request.input.messages ?? []);
-            const result = await regularHandler(rawMessages, request.context);
-            const responseKeys = getResponseKeys();
-            // Check if result is already a full response dict with all responseKeys
-            // (This handles cases where responseKeys are overridden and function returns a dict)
-            if (typeof result === 'object' &&
-                result !== null &&
-                !Array.isArray(result) &&
-                responseKeys.every((key) => key in result)) {
-                return result;
-            }
-            // Convert list of Message objects to list of dicts
-            const messagesList = Array.isArray(result)
-                ? result.map((m) => ({ role: m.role, content: m.content }))
-                : [{ role: result.role, content: result.content }];
-            return { [responseKeys[0]]: messagesList };
+            return { output: result };
         });
     }
     return agentInstance;