@reminix/runtime 0.0.13 → 0.0.16

package/README.md

@@ -2,7 +2,7 @@
 
 The open source runtime for serving AI agents via REST APIs. Part of [Reminix](https://reminix.com) — the developer platform for AI agents.
 
-Core runtime package for serving AI agents and tools via REST APIs. Provides the `agent()`, `chatAgent()`, and `tool()` factory functions for building and serving AI agents.
+Core runtime package for serving AI agents and tools via REST APIs. Provides the `agent()` and `tool()` factory functions, agent templates (prompt, chat, task, rag, thread), and types `Message` and `ToolCall` for OpenAI-style conversations.
 
 Built on [Hono](https://hono.dev) for portability across Node.js, Deno, Bun, and edge runtimes.
 
@@ -17,12 +17,12 @@ npm install @reminix/runtime
 ## Quick Start
 
 ```typescript
-import { agent, chatAgent, serve } from '@reminix/runtime';
+import { agent, serve } from '@reminix/runtime';
 
 // Create an agent for task-oriented operations
 const calculator = agent('calculator', {
   description: 'Add two numbers',
-  parameters: {
+  input: {
     type: 'object',
     properties: { a: { type: 'number' }, b: { type: 'number' } },
     required: ['a', 'b'],
@@ -30,14 +30,8 @@ const calculator = agent('calculator', {
   handler: async ({ a, b }) => (a as number) + (b as number),
 });
 
-// Create a chat agent for conversational interactions
-const assistant = chatAgent('assistant', {
-  description: 'A helpful assistant',
-  handler: async (messages) => `You said: ${messages.at(-1)?.content}`,
-});
-
-// Serve the agents
-serve({ agents: [calculator, assistant], port: 8080 });
+// Serve the agent
+serve({ agents: [calculator], port: 8080 });
 ```
 
 ## How It Works
@@ -71,7 +65,7 @@ Returns runtime information, available agents, and tools:
 {
   "runtime": {
     "name": "reminix-runtime",
-    "version": "0.0.13",
+    "version": "0.0.16",
     "language": "typescript",
     "framework": "hono"
   },
@@ -80,7 +74,7 @@ Returns runtime information, available agents, and tools:
       "name": "calculator",
       "type": "agent",
       "description": "Add two numbers",
-      "parameters": {
+      "input": {
         "type": "object",
         "properties": { "a": { "type": "number" }, "b": { "type": "number" } },
         "required": ["a", "b"]
@@ -93,41 +87,6 @@ Returns runtime information, available agents, and tools:
       "requestKeys": ["a", "b"],
       "responseKeys": ["content"],
       "streaming": false
-    },
-    {
-      "name": "assistant",
-      "type": "chat_agent",
-      "description": "A helpful assistant",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "messages": {
-            "type": "array",
-            "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"] }
-          }
-        },
-        "required": ["messages"]
-      },
-      "output": {
-        "type": "object",
-        "properties": {
-          "messages": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "properties": {
-                "role": { "type": "string" },
-                "content": { "type": "string" }
-              },
-              "required": ["role", "content"]
-            }
-          }
-        },
-        "required": ["messages"]
-      },
-      "requestKeys": ["messages"],
-      "responseKeys": ["messages"],
-      "streaming": false
     }
   ],
   "tools": [
@@ -135,7 +94,7 @@ Returns runtime information, available agents, and tools:
       "name": "get_weather",
       "type": "tool",
       "description": "Get current weather for a location",
-      "parameters": { ... },
+      "input": { ... },
       "output": { ... }
     }
   ]
@@ -146,7 +105,7 @@ Returns runtime information, available agents, and tools:
 
 `POST /agents/{name}/invoke` - Invoke an agent.
 
-Request keys are defined by the agent's `parameters` schema. For example, a calculator agent with `parameters: { properties: { a, b } }` expects `a` and `b` at the top level:
+Request keys are defined by the agent's input schema. For example, a calculator agent with input schema `{ properties: { a, b } }` expects `a` and `b` at the top level:
 
 **Task-oriented agent:**
 ```bash
@@ -164,7 +123,7 @@ curl -X POST http://localhost:8080/agents/calculator/invoke \
 
 **Chat agent:**
 
-Chat agents expect `messages` at the top level and return `messages` (array):
+Chat agents (template `chat` or `thread`) expect `messages` at the top level. Messages are OpenAI-style: `role` (`user` | `assistant` | `system` | `tool`), `content`, and optionally `tool_calls`, `tool_call_id`, and `name`. Use the `Message` and `ToolCall` types from `@reminix/runtime` in your handler. Chat returns a string; thread returns an array of messages.
 
 ```bash
 curl -X POST http://localhost:8080/agents/assistant/invoke \
@@ -176,15 +135,10 @@ curl -X POST http://localhost:8080/agents/assistant/invoke \
   }'
 ```
 
-**Response:**
+**Response (chat):**
 ```json
 {
-  "messages": [
-    {
-      "role": "assistant",
-      "content": "You said: Hello!"
-    }
-  ]
+  "content": "You said: Hello!"
 }
 ```
 
@@ -209,16 +163,45 @@ curl -X POST http://localhost:8080/tools/get_weather/call \
 
 Agents handle requests via the `/agents/{name}/invoke` endpoint.
 
+### Agent templates
+
+You can use a **template** to get standard input/output schemas without defining them yourself. Pass `template` when creating an agent:
+
+| Template | Input | Output | Use case |
+|----------|--------|--------|----------|
+| `prompt` (default) | `{ prompt: string }` | `string` | Single prompt in, text out |
+| `chat` | `{ messages: Message[] }` | `string` | Multi-turn chat, final reply as string |
+| `task` | `{ task: string, ... }` | JSON | Task name + params, structured result |
+| `rag` | `{ query: string, messages?: Message[], collectionIds?: string[] }` | `string` | RAG query, optional history and collections |
+| `thread` | `{ messages: Message[] }` | `Message[]` | Multi-turn with tool calls; returns updated thread |
+
+Messages are OpenAI-style: `role`, `content`, and optionally `tool_calls`, `tool_call_id`, and `name`. Use the exported types `Message` and `ToolCall` from `@reminix/runtime` for type-safe handlers.
+
+```typescript
+import { agent, serve, type Message, type ToolCall } from '@reminix/runtime';
+
+const assistant = agent('assistant', {
+  template: 'chat',
+  description: 'Helpful assistant',
+  handler: async ({ messages }) => {
+    const last = (messages as Message[]).slice(-1)[0];
+    return last?.role === 'user' ? `You said: ${last.content}` : 'Hello!';
+  },
+});
+
+serve({ agents: [assistant], port: 8080 });
+```
+
 ### Task-Oriented Agent
 
-Use `agent()` for task-oriented agents that take structured input and return output:
+Use `agent()` for task-oriented agents that take structured input and return output (or omit `template` / use `template: 'prompt'` or `template: 'task'` for standard shapes):
 
 ```typescript
 import { agent, serve } from '@reminix/runtime';
 
 const calculator = agent('calculator', {
   description: 'Add two numbers',
-  parameters: {
+  input: {
     type: 'object',
     properties: {
       a: { type: 'number' },
@@ -231,7 +214,7 @@ const calculator = agent('calculator', {
 
 const textProcessor = agent('text-processor', {
   description: 'Process text in various ways',
-  parameters: {
+  input: {
     type: 'object',
     properties: {
       text: { type: 'string' },
@@ -248,44 +231,16 @@ const textProcessor = agent('text-processor', {
 serve({ agents: [calculator, textProcessor], port: 8080 });
 ```
 
-### Chat Agent
-
-Use `chatAgent()` for conversational agents that handle message history:
-
-```typescript
-import { chatAgent, serve } from '@reminix/runtime';
-
-const assistant = chatAgent('assistant', {
-  description: 'A helpful assistant',
-  handler: async (messages) => {
-    const lastMsg = messages.at(-1)?.content ?? '';
-    return `You said: ${lastMsg}`;
-  },
-});
-
-// With context support
-const contextualBot = chatAgent('contextual-bot', {
-  description: 'Bot with context awareness',
-  handler: async (messages, context) => {
-    const userId = context?.user_id ?? 'unknown';
-    return `Hello user ${userId}!`;
-  },
-});
-
-serve({ agents: [assistant, contextualBot], port: 8080 });
-```
-
 ### Streaming
 
-Both factories support streaming via async generators. When you use an async generator function, the agent automatically supports streaming:
+Agents support streaming via async generators. When you use an async generator function, the agent automatically supports streaming:
 
 ```typescript
-import { agent, chatAgent, serve } from '@reminix/runtime';
+import { agent, serve } from '@reminix/runtime';
 
-// Streaming task agent
 const streamer = agent('streamer', {
   description: 'Stream text word by word',
-  parameters: {
+  input: {
     type: 'object',
     properties: { text: { type: 'string' } },
     required: ['text'],
@@ -297,18 +252,7 @@ const streamer = agent('streamer', {
   },
 });
 
-// Streaming chat agent
-const streamingAssistant = chatAgent('streaming-assistant', {
-  description: 'Stream responses token by token',
-  handler: async function* (messages) {
-    const response = `You said: ${messages.at(-1)?.content}`;
-    for (const char of response) {
-      yield char;
-    }
-  },
-});
-
-serve({ agents: [streamer, streamingAssistant], port: 8080 });
+serve({ agents: [streamer], port: 8080 });
 ```
 
 For streaming agents:
@@ -328,7 +272,7 @@ import { tool, serve } from '@reminix/runtime';
 
 const getWeather = tool('get_weather', {
   description: 'Get current weather for a location',
-  parameters: {
+  input: {
     type: 'object',
     properties: {
       location: { type: 'string', description: 'City name' },
@@ -361,7 +305,7 @@ import { agent, tool, serve } from '@reminix/runtime';
 
 const summarizer = agent('summarizer', {
   description: 'Summarize text',
-  parameters: {
+  input: {
     type: 'object',
     properties: { text: { type: 'string' } },
     required: ['text'],
@@ -371,7 +315,7 @@ const summarizer = agent('summarizer', {
 
 const calculator = tool('calculate', {
   description: 'Perform basic math operations',
-  parameters: {
+  input: {
     type: 'object',
     properties: { expression: { type: 'string' } },
     required: ['expression'],
@@ -422,14 +366,15 @@ const app = createApp({ agents: [myAgent], tools: [myTool] });
 
 ### `agent(name, options)`
 
-Factory function to create a task-oriented agent.
+Factory function to create an agent. Use `template` for standard I/O shapes, or provide custom `input`/`output` schemas.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `name` | `string` | Unique identifier for the agent |
+| `options.template` | `'prompt' \| 'chat' \| 'task' \| 'rag' \| 'thread'` | Optional. Standard input/output schema (default: `prompt` when no custom input/output). |
 | `options.description` | `string` | Human-readable description |
-| `options.parameters` | `object` | JSON Schema for input parameters |
-| `options.output` | `object` | Optional JSON Schema for output |
+| `options.input` | `object` | JSON Schema for input (ignored if `template` is set) |
+| `options.output` | `object` | Optional JSON Schema for output (ignored if `template` is set) |
 | `options.handler` | `function` | Async function or async generator |
 
 ```typescript
@@ -438,7 +383,7 @@ import { agent } from '@reminix/runtime';
 // Regular agent
 const myAgent = agent('my-agent', {
   description: 'Does something useful',
-  parameters: {
+  input: {
     type: 'object',
     properties: { input: { type: 'string' } },
     required: ['input'],
@@ -449,7 +394,7 @@ const myAgent = agent('my-agent', {
 // Streaming agent
 const streamingAgent = agent('streaming-agent', {
   description: 'Streams output',
-  parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+  input: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
   handler: async function* ({ text }) {
     for (const word of (text as string).split(' ')) {
       yield word + ' ';
@@ -458,39 +403,6 @@ const streamingAgent = agent('streaming-agent', {
 });
 ```
 
-### `chatAgent(name, options)`
-
-Factory function to create a chat agent.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Unique identifier for the agent |
-| `options.description` | `string` | Human-readable description |
-| `options.handler` | `function` | Async function or async generator receiving messages |
-
-```typescript
-import { chatAgent } from '@reminix/runtime';
-
-// Regular chat agent
-const bot = chatAgent('bot', {
-  description: 'A simple bot',
-  handler: async (messages) => `You said: ${messages.at(-1)?.content}`,
-});
-
-// With context
-const contextBot = chatAgent('context-bot', {
-  handler: async (messages, context) => `Hello ${context?.user_id}!`,
-});
-
-// Streaming chat agent
-const streamingBot = chatAgent('streaming-bot', {
-  handler: async function* (messages) {
-    yield 'Hello';
-    yield ' world!';
-  },
-});
-```
-
 ### `tool(name, options)`
 
 Factory function to create a tool.
@@ -499,7 +411,7 @@ Factory function to create a tool.
 |-----------|------|-------------|
 | `name` | `string` | Unique identifier for the tool |
 | `options.description` | `string` | Human-readable description |
-| `options.parameters` | `object` | JSON Schema for input parameters |
+| `options.input` | `object` | JSON Schema for input |
 | `options.output` | `object` | Optional JSON Schema for output |
 | `options.handler` | `function` | Async function to call when invoked |
 
@@ -508,7 +420,7 @@ import { tool } from '@reminix/runtime';
 
 const myTool = tool('my_tool', {
   description: 'Does something useful',
-  parameters: {
+  input: {
     type: 'object',
     properties: { input: { type: 'string' } },
     required: ['input'],
@@ -520,32 +432,19 @@ const myTool = tool('my_tool', {
 ### Request/Response Types
 
 ```typescript
-// Request: top-level keys based on agent's requestKeys (derived from parameters)
-// For a calculator agent with parameters { a: number, b: number }:
+// Request: top-level keys based on agent's input schema
+// For a calculator agent with input schema { a: number, b: number }:
 interface CalculatorRequest {
-  a: number;                          // Top-level key from parameters
-  b: number;                          // Top-level key from parameters
+  a: number;                          // Top-level key from input schema
+  b: number;                          // Top-level key from input schema
   stream?: boolean;                   // Whether to stream the response
   context?: Record<string, unknown>;  // Optional metadata
 }
 
-// For a chat agent:
-interface ChatRequest {
-  messages: Message[];                // Top-level key (requestKeys: ['messages'])
-  stream?: boolean;
-  context?: Record<string, unknown>;
-}
-
-// Response: keys based on agent's responseKeys
-// Regular agent (responseKeys: ['content']):
+// Response: keys based on agent's output schema
 interface AgentResponse {
   content: unknown;
 }
-
-// Chat agent (responseKeys: ['messages']):
-interface ChatResponse {
-  messages: Array<{ role: string; content: string }>;
-}
 ```
 
 ## Advanced
@@ -581,7 +480,7 @@ import { Tool, serve } from '@reminix/runtime';
 
 const myTool = new Tool('get_weather', {
   description: 'Get weather for a location',
-  parameters: {
+  input: {
     type: 'object',
     properties: { location: { type: 'string' } },
     required: ['location'],

package/dist/agent-adapter.d.ts

@@ -1,7 +1,7 @@
 /**
  * Base agent adapter class for framework integrations.
  */
-import type { ExecuteRequest } from './types.js';
+import type { AgentInvokeRequest } from './types.js';
 import { AgentBase, type AgentMetadata } from './agent.js';
 /**
  * Base class for framework agent adapters.
@@ -14,18 +14,14 @@ export declare abstract class AgentAdapter extends AgentBase {
      * The adapter name. Subclasses should override this.
      */
     static adapterName: string;
-    /**
-     * All built-in adapters support streaming.
-     */
-    get streaming(): boolean;
     /**
      * Return adapter metadata for discovery.
      * Adapters accept both 'messages' (chat-style) and 'prompt' (simple) inputs.
      */
     get metadata(): AgentMetadata;
     /**
-     * Handle a streaming execute request.
+     * Handle a streaming invoke request.
      */
-    executeStream(_request: ExecuteRequest): AsyncGenerator<string, void, unknown>;
+    invokeStream(_request: AgentInvokeRequest): AsyncGenerator<string, void, unknown>;
 }
 //# sourceMappingURL=agent-adapter.d.ts.map

package/dist/agent-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-adapter.d.ts","sourceRoot":"","sources":["../src/agent-adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,8BAAsB,YAAa,SAAQ,SAAS;IAClD;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,CAAa;IAEvC;;OAEG;IACH,IAAa,SAAS,IAAI,OAAO,CAEhC;IAED;;;OAGG;IACH,IAAI,QAAQ,IAAI,aAAa,CAO5B;IAED;;OAEG;IAEI,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;CAGtF"}
+{"version":3,"file":"agent-adapter.d.ts","sourceRoot":"","sources":["../src/agent-adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAmB3D;;;;;GAKG;AACH,8BAAsB,YAAa,SAAQ,SAAS;IAClD;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,CAAa;IAEvC;;;OAGG;IACH,IAAI,QAAQ,IAAI,aAAa,CAU5B;IAED;;OAEG;IAEI,YAAY,CAAC,QAAQ,EAAE,kBAAkB,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;CAGzF"}

package/dist/agent-adapter.js

@@ -2,6 +2,22 @@
  * Base agent adapter class for framework integrations.
  */
 import { AgentBase } from './agent.js';
+/**
+ * Adapter input schema - accepts both messages and prompt.
+ */
+const ADAPTER_INPUT = {
+    type: 'object',
+    properties: {
+        messages: {
+            type: 'array',
+            description: 'Chat-style messages input',
+        },
+        prompt: {
+            type: 'string',
+            description: 'Simple prompt input',
+        },
+    },
+};
 /**
  * Base class for framework agent adapters.
  *
@@ -13,29 +29,26 @@ export class AgentAdapter extends AgentBase {
      * The adapter name. Subclasses should override this.
      */
     static adapterName = 'unknown';
-    /**
-     * All built-in adapters support streaming.
-     */
-    get streaming() {
-        return true;
-    }
     /**
      * Return adapter metadata for discovery.
      * Adapters accept both 'messages' (chat-style) and 'prompt' (simple) inputs.
      */
     get metadata() {
         return {
-            type: 'adapter',
+            description: `${this.constructor.adapterName} adapter`,
+            capabilities: {
+                streaming: true,
+            },
+            input: ADAPTER_INPUT,
+            output: { type: 'string' },
             adapter: this.constructor.adapterName,
-            requestKeys: ['messages', 'prompt'],
-            responseKeys: ['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 adapter');
     }
 }

package/dist/agent-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-adapter.js","sourceRoot":"","sources":["../src/agent-adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,OAAgB,YAAa,SAAQ,SAAS;IAClD;;OAEG;IACH,MAAM,CAAC,WAAW,GAAW,SAAS,CAAC;IAEvC;;OAEG;IACH,IAAa,SAAS;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,IAAI,QAAQ;QACV,OAAO;YACL,IAAI,EAAE,SAAS;YACf,OAAO,EAAG,IAAI,CAAC,WAAmC,CAAC,WAAW;YAC9D,WAAW,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;YACnC,YAAY,EAAE,CAAC,QAAQ,CAAC;SACzB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,yCAAyC;IACzC,KAAK,CAAC,CAAC,aAAa,CAAC,QAAwB;QAC3C,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC"}
+{"version":3,"file":"agent-adapter.js","sourceRoot":"","sources":["../src/agent-adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,aAAa,GAAe;IAChC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,QAAQ,EAAE;YACR,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,2BAA2B;SACzC;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,qBAAqB;SACnC;KACF;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,OAAgB,YAAa,SAAQ,SAAS;IAClD;;OAEG;IACH,MAAM,CAAC,WAAW,GAAW,SAAS,CAAC;IAEvC;;;OAGG;IACH,IAAI,QAAQ;QACV,OAAO;YACL,WAAW,EAAE,GAAI,IAAI,CAAC,WAAmC,CAAC,WAAW,UAAU;YAC/E,YAAY,EAAE;gBACZ,SAAS,EAAE,IAAI;aAChB;YACD,KAAK,EAAE,aAAa;YACpB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,OAAO,EAAG,IAAI,CAAC,WAAmC,CAAC,WAAW;SAC/D,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,yCAAyC;IACzC,KAAK,CAAC,CAAC,YAAY,CAAC,QAA4B;QAC9C,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC"}