@reminix/runtime 0.0.7 → 0.0.9

package/dist/agent.js

@@ -2,24 +2,29 @@
  * Agent classes for Reminix Runtime.
  */
 import { VERSION } from './version.js';
+/**
+ * Default parameters schema for agents.
+ * Request: { prompt: '...' }
+ */
+const DEFAULT_AGENT_PARAMETERS = {
+    type: 'object',
+    properties: {
+        prompt: { type: 'string', description: 'The prompt or task for the agent' },
+    },
+    required: ['prompt'],
+};
 /**
  * Abstract base class defining the agent interface.
  *
  * This is the core contract that all agents must fulfill.
  * Use `Agent` for callback-based registration or extend
- * `BaseAdapter` for framework adapters.
+ * `AgentAdapter` for framework adapters.
  */
 export class AgentBase {
     /**
-     * Whether invoke supports streaming. Override to enable.
-     */
-    get invokeStreaming() {
-        return false;
-    }
-    /**
-     * Whether chat supports streaming. Override to enable.
+     * Whether execute supports streaming. Override to enable.
      */
-    get chatStreaming() {
+    get streaming() {
         return false;
     }
     /**
@@ -27,20 +32,18 @@ export class AgentBase {
      * Override this to provide custom metadata.
      */
     get metadata() {
-        return { type: 'agent' };
-    }
-    /**
-     * Handle a streaming invoke request.
-     */
-    // eslint-disable-next-line require-yield
-    async *invokeStream(_request) {
-        throw new Error('Streaming not implemented for this agent');
+        return {
+            type: 'agent',
+            parameters: DEFAULT_AGENT_PARAMETERS,
+            requestKeys: ['prompt'],
+            responseKeys: ['content'],
+        };
     }
     /**
-     * Handle a streaming chat request.
+     * Handle a streaming execute request.
      */
     // eslint-disable-next-line require-yield
-    async *chatStream(_request) {
+    async *executeStream(_request) {
         throw new Error('Streaming not implemented for this agent');
     }
     /**
@@ -53,7 +56,7 @@ export class AgentBase {
      * ```typescript
      * // Vercel Edge Function
      * const agent = new Agent('my-agent');
-     * agent.onInvoke(async (req) => ({ output: 'Hello!' }));
+     * agent.onExecute(async (req) => ({ output: 'Hello!' }));
      * export default agent.toHandler();
      *
      * // Cloudflare Worker
@@ -93,30 +96,41 @@ export class AgentBase {
                             {
                                 name: this.name,
                                 ...this.metadata,
-                                invoke: { streaming: this.invokeStreaming },
-                                chat: { streaming: this.chatStreaming },
+                                streaming: this.streaming,
                             },
                         ],
                     }, { headers: corsHeaders });
                 }
-                // POST /agents/{name}/invoke
-                const invokeMatch = path.match(/^\/agents\/([^/]+)\/invoke$/);
-                if (method === 'POST' && invokeMatch) {
-                    const agentName = invokeMatch[1];
+                // POST /agents/{name}/execute
+                const executeMatch = path.match(/^\/agents\/([^/]+)\/execute$/);
+                if (method === 'POST' && executeMatch) {
+                    const agentName = executeMatch[1];
                     if (agentName !== this.name) {
                         return Response.json({ error: `Agent '${agentName}' not found` }, { status: 404, headers: corsHeaders });
                     }
                     const body = (await request.json());
-                    if (!body.input || Object.keys(body.input).length === 0) {
-                        return Response.json({ error: 'input is required and must not be empty' }, { status: 400, headers: corsHeaders });
+                    // 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,
+                        stream: body.stream === true,
+                        context: body.context,
+                    };
                     // Handle streaming
-                    if (body.stream) {
+                    if (executeRequest.stream) {
                         const stream = new ReadableStream({
                             start: async (controller) => {
                                 const encoder = new TextEncoder();
                                 try {
-                                    for await (const chunk of this.invokeStream(body)) {
+                                    for await (const chunk of this.executeStream(executeRequest)) {
                                         controller.enqueue(encoder.encode(`data: ${chunk}\n\n`));
                                     }
                                     controller.enqueue(encoder.encode('data: [DONE]\n\n'));
@@ -137,48 +151,7 @@ export class AgentBase {
                             },
                         });
                     }
-                    const response = await this.invoke(body);
-                    return Response.json(response, { headers: corsHeaders });
-                }
-                // POST /agents/{name}/chat
-                const chatMatch = path.match(/^\/agents\/([^/]+)\/chat$/);
-                if (method === 'POST' && chatMatch) {
-                    const agentName = chatMatch[1];
-                    if (agentName !== this.name) {
-                        return Response.json({ error: `Agent '${agentName}' not found` }, { status: 404, headers: corsHeaders });
-                    }
-                    const body = (await request.json());
-                    if (!body.messages || body.messages.length === 0) {
-                        return Response.json({ error: 'messages is required and must not be empty' }, { status: 400, headers: corsHeaders });
-                    }
-                    // Handle streaming
-                    if (body.stream) {
-                        const stream = new ReadableStream({
-                            start: async (controller) => {
-                                const encoder = new TextEncoder();
-                                try {
-                                    for await (const chunk of this.chatStream(body)) {
-                                        controller.enqueue(encoder.encode(`data: ${chunk}\n\n`));
-                                    }
-                                    controller.enqueue(encoder.encode('data: [DONE]\n\n'));
-                                }
-                                catch (error) {
-                                    const message = error instanceof Error ? error.message : 'Unknown error';
-                                    controller.enqueue(encoder.encode(`data: ${JSON.stringify({ error: message })}\n\n`));
-                                }
-                                controller.close();
-                            },
-                        });
-                        return new Response(stream, {
-                            headers: {
-                                ...corsHeaders,
-                                'Content-Type': 'text/event-stream',
-                                'Cache-Control': 'no-cache',
-                                Connection: 'keep-alive',
-                            },
-                        });
-                    }
-                    const response = await this.chat(body);
+                    const response = await this.execute(executeRequest);
                     return Response.json(response, { headers: corsHeaders });
                 }
                 // Not found
@@ -199,28 +172,22 @@ export class AgentBase {
  * ```typescript
  * const agent = new Agent('my-agent');
  *
- * agent.onInvoke(async (request) => {
+ * agent.onExecute(async (request) => {
  *   return { output: 'Hello!' };
  * });
  *
- * agent.onChat(async (request) => {
- *   return { output: 'Hi!', messages: [...] };
- * });
- *
  * serve({ agents: [agent], port: 8080 });
  * ```
  */
 export class Agent extends AgentBase {
     _name;
     _metadata;
-    _invokeHandler = null;
-    _chatHandler = null;
-    _invokeStreamHandler = null;
-    _chatStreamHandler = null;
+    _executeHandler = null;
+    _executeStreamHandler = null;
     /**
      * Create a new agent.
      *
-     * @param name - The agent name (used in URLs like /agents/{name}/invoke)
+     * @param name - The agent name (used in URLs like /agents/{name}/execute)
      * @param options - Optional configuration
      */
     constructor(name, options) {
@@ -238,104 +205,364 @@ export class Agent extends AgentBase {
      * Return agent metadata for discovery.
      */
     get metadata() {
-        return { type: 'agent', ...this._metadata };
-    }
-    /**
-     * Whether invoke supports streaming.
-     */
-    get invokeStreaming() {
-        return this._invokeStreamHandler !== null;
+        return {
+            type: 'agent',
+            parameters: DEFAULT_AGENT_PARAMETERS,
+            requestKeys: ['prompt'],
+            responseKeys: ['content'],
+            ...this._metadata,
+        };
     }
     /**
-     * Whether chat supports streaming.
+     * Whether execute supports streaming.
      */
-    get chatStreaming() {
-        return this._chatStreamHandler !== null;
+    get streaming() {
+        return this._executeStreamHandler !== null;
     }
     /**
-     * Register an invoke handler.
+     * Register an execute handler.
      *
      * @example
-     * agent.onInvoke(async (request) => {
+     * agent.onExecute(async (request) => {
      *   return { output: 'Hello!' };
      * });
      */
-    onInvoke(handler) {
-        this._invokeHandler = handler;
-        return this;
-    }
-    /**
-     * Register a chat handler.
-     *
-     * @example
-     * agent.onChat(async (request) => {
-     *   return { output: 'Hi!', messages: [...] };
-     * });
-     */
-    onChat(handler) {
-        this._chatHandler = handler;
+    onExecute(handler) {
+        this._executeHandler = handler;
         return this;
     }
     /**
-     * Register a streaming invoke handler.
+     * Register a streaming execute handler.
      *
      * @example
-     * agent.onInvokeStream(async function* (request) {
+     * agent.onExecuteStream(async function* (request) {
      *   yield '{"chunk": "Hello"}';
      *   yield '{"chunk": " world!"}';
      * });
      */
-    onInvokeStream(handler) {
-        this._invokeStreamHandler = handler;
+    onExecuteStream(handler) {
+        this._executeStreamHandler = handler;
         return this;
     }
     /**
-     * Register a streaming chat handler.
-     *
-     * @example
-     * agent.onChatStream(async function* (request) {
-     *   yield '{"chunk": "Hi"}';
-     * });
-     */
-    onChatStream(handler) {
-        this._chatStreamHandler = handler;
-        return this;
-    }
-    /**
-     * Handle an invoke request.
+     * Handle an execute request.
      */
-    async invoke(request) {
-        if (this._invokeHandler === null) {
-            throw new Error(`No invoke handler registered for agent '${this._name}'`);
+    async execute(request) {
+        if (this._executeHandler === null) {
+            throw new Error(`No execute handler registered for agent '${this._name}'`);
         }
-        return this._invokeHandler(request);
+        return this._executeHandler(request);
     }
     /**
-     * Handle a chat request.
+     * Handle a streaming execute request.
      */
-    async chat(request) {
-        if (this._chatHandler === null) {
-            throw new Error(`No chat handler registered for agent '${this._name}'`);
+    async *executeStream(request) {
+        if (this._executeStreamHandler === null) {
+            throw new Error(`No streaming execute handler registered for agent '${this._name}'`);
         }
-        return this._chatHandler(request);
+        yield* this._executeStreamHandler(request);
     }
-    /**
-     * Handle a streaming invoke request.
-     */
-    async *invokeStream(request) {
-        if (this._invokeStreamHandler === null) {
-            throw new Error(`No streaming invoke handler registered for agent '${this._name}'`);
-        }
-        yield* this._invokeStreamHandler(request);
+}
+/**
+ * Detect if a function is an async generator function.
+ */
+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;
     }
-    /**
-     * Handle a streaming chat request.
-     */
-    async *chatStream(request) {
-        if (this._chatStreamHandler === null) {
-            throw new Error(`No streaming chat handler registered for agent '${this._name}'`);
-        }
-        yield* this._chatStreamHandler(request);
+    // 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`.
+ *
+ * @example
+ * ```typescript
+ * // Simple agent with default parameters
+ * // Request: { prompt: 'Hello world' }
+ * // Response: { output: 'You said: Hello world' }
+ * const echo = agent('echo', {
+ *   description: 'Echo the prompt',
+ *   execute: async ({ prompt }) => `You said: ${prompt}`,
+ * });
+ *
+ * // Agent with custom parameters
+ * // Request: { a: 1, b: 2 }
+ * // Response: { output: 3 }
+ * const calculator = agent('calculator', {
+ *   description: 'Add two numbers',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { a: { type: 'number' }, b: { type: 'number' } },
+ *     required: ['a', 'b'],
+ *   },
+ *   execute: async ({ a, b }) => (a as number) + (b as number),
+ * });
+ *
+ * // Streaming agent (async generator)
+ * // Request: { prompt: 'hello world' }
+ * // Response: { output: 'hello world ' } (streamed)
+ * const streamer = agent('streamer', {
+ *   description: 'Stream text word by word',
+ *   execute: async function* ({ prompt }) {
+ *     for (const word of (prompt as string).split(' ')) {
+ *       yield word + ' ';
+ *     }
+ *   },
+ * });
+ * ```
+ */
+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;
+    }
+    const agentInstance = new Agent(name, {
+        metadata: {
+            ...baseMetadata,
+            ...options.metadata,
+        },
+    });
+    // Detect if execute is an async generator function
+    const isStreaming = isAsyncGeneratorFunction(options.execute);
+    // 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 streamExecute = options.execute;
+        // Register streaming execute handler
+        agentInstance.onExecuteStream(async function* (request) {
+            yield* streamExecute(request.input, request.context);
+        });
+        // Also register non-streaming handler that collects chunks
+        agentInstance.onExecute(async (request) => {
+            const chunks = [];
+            for await (const chunk of streamExecute(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 };
+        });
+    }
+    else {
+        const regularExecute = options.execute;
+        agentInstance.onExecute(async (request) => {
+            const result = await regularExecute(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, message out).
+ *
+ * Request: `{ messages: [...] }`
+ * Response: `{ message: { role: 'assistant', content: '...' } }`
+ *
+ * @example
+ * ```typescript
+ * // Non-streaming chat agent
+ * // Request: { messages: [{ role: 'user', content: 'hello' }] }
+ * // Response: { message: { role: 'assistant', content: 'You said: hello' } }
+ * const bot = chatAgent('bot', {
+ *   description: 'A simple chatbot',
+ *   execute: 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',
+ *   execute: 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 = ['message'];
+    // Define standard chat agent schemas
+    const parametersSchema = {
+        type: 'object',
+        properties: {
+            messages: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        role: { type: 'string' },
+                        content: { type: 'string' },
+                    },
+                    required: ['role', 'content'],
+                },
+            },
+        },
+        required: ['messages'],
+    };
+    // Message schema (the value, not the full response)
+    const messageSchema = {
+        type: 'object',
+        properties: {
+            role: { type: 'string' },
+            content: { type: 'string' },
+        },
+        required: ['role', 'content'],
+    };
+    // Wrap message schema to match responseKeys structure
+    const wrappedOutput = wrapOutputSchemaForResponseKeys(messageSchema, 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(messageSchema, finalResponseKeys)
+        : wrappedOutput;
+    if (finalWrappedOutput !== undefined) {
+        baseMetadata.output = finalWrappedOutput;
+    }
+    const agentInstance = new Agent(name, {
+        metadata: {
+            ...baseMetadata,
+            ...options.metadata,
+        },
+    });
+    // Detect if execute is an async generator function
+    const isStreaming = isAsyncGeneratorFunction(options.execute);
+    // 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 : ['message'];
+    };
+    if (isStreaming) {
+        const streamExecute = options.execute;
+        // Register streaming execute handler
+        agentInstance.onExecuteStream(async function* (request) {
+            const rawMessages = (request.input.messages ?? []);
+            yield* streamExecute(rawMessages, request.context);
+        });
+        // Also register non-streaming handler that collects chunks
+        agentInstance.onExecute(async (request) => {
+            const rawMessages = (request.input.messages ?? []);
+            const chunks = [];
+            for await (const chunk of streamExecute(rawMessages, request.context)) {
+                chunks.push(chunk);
+            }
+            const result = { role: 'assistant', content: chunks.join('') };
+            // For chat agents, always wrap in first responseKey (typically "message")
+            const responseKeys = getResponseKeys();
+            return { [responseKeys[0]]: result };
+        });
+    }
+    else {
+        const regularExecute = options.execute;
+        agentInstance.onExecute(async (request) => {
+            const rawMessages = (request.input.messages ?? []);
+            const result = await regularExecute(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) &&
+                'role' in result === false && // Not a Message (Message has 'role' property)
+                responseKeys.every((key) => key in result)) {
+                return result;
+            }
+            // Convert Message to dict if needed, then wrap in first responseKey
+            const messageDict = typeof result === 'object' && result !== null && 'role' in result && 'content' in result
+                ? { role: result.role, content: result.content }
+                : result;
+            return { [responseKeys[0]]: messageDict };
+        });
     }
+    return agentInstance;
 }
 //# sourceMappingURL=agent.js.map