@reminix/http-adapter

HTTP adapter for running Reminix handlers locally. This package provides an HTTP server that can load and execute TypeScript/JavaScript handlers, making them accessible via REST API.

Installation

npm install @reminix/http-adapter
# or
pnpm add @reminix/http-adapter
# or
yarn add @reminix/http-adapter

Quick Start

1. Create a Handler

Create a file my-handler.ts:

import type { AgentHandler, Context, Request, Response } from '@reminix/runtime';

export const agents = {
  chatbot: async (context: Context, request: Request): Promise<Response> => {
    const lastMessage = request.messages[request.messages.length - 1];
    return {
      messages: [
        {
          role: 'assistant',
          content: `You said: ${lastMessage?.content || 'Hello!'}`,
        },
      ],
      metadata: {},
    };
  },
};

2. Start the Server

# Using npx
npx @reminix/http-adapter serve my-handler.ts

# Or using tsx (development)
tsx node_modules/@reminix/http-adapter/dist/cli.js serve my-handler.ts

3. Test the Handler

# Health check
curl http://localhost:3000/health

# Invoke the agent
curl -X POST http://localhost:3000/agents/chatbot/invoke \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

Usage

Command Line

# Basic usage
npx @reminix/http-adapter serve <handler-path> [options]

# Options
--port <number>    Port to listen on (default: 3000)
--host <string>    Host to listen on (default: localhost)

# Examples
npx @reminix/http-adapter serve ./my-handler.ts
npx @reminix/http-adapter serve ./my-handler.ts --port 8080
npx @reminix/http-adapter serve ./my-handler --host 0.0.0.0

Programmatic API

import { startServer } from '@reminix/http-adapter';

// Start server with default options
await startServer('./my-handler.ts');

// Start server with custom options
await startServer('./my-handler.ts', {
  port: 8080,
  host: '0.0.0.0',
  context: async (req) => {
    // Provide custom context from request
    return {
      chatId: req.headers['x-chat-id'] || 'default',
      // ... other context properties
    };
  },
});

Handler Formats

Single File Handler

Export agents, tools, and/or prompts:

export const agents = {
  chatbot: async (context, request) => ({ messages: [] }),
};

export const tools = {
  calculator: async (context, request) => ({ messages: [] }),
};

export const prompts = {
  system: 'You are a helpful assistant.',
};

Directory-Based Handler (Auto-Discovery)

Organize handlers in a directory structure:

my-handler/
  agents/
    chatbot.ts      # export const chatbot = async (...) => {...}
    assistant.ts    # export const assistant = async (...) => {...}
  tools/
    search.ts       # export const search = async (...) => {...}
    weather.ts      # export const weather = async (...) => {...}
  prompts/
    system.ts       # export const system = {...}

The adapter will automatically discover and load all handlers from this structure.

API Endpoints

Health Check

GET /health

Returns:

{
  "status": "ok",
  "agents": ["chatbot", "assistant"],
  "tools": ["search", "weather"],
  "prompts": ["system"]
}

Invoke Agent

POST /agents/:agentId/invoke
Content-Type: application/json

{
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "metadata": {
    "chatId": "chat-123"
  }
}

Invoke Tool

POST /tools/:toolId/invoke
Content-Type: application/json

{
  "messages": [
    {
      "role": "user",
      "content": "5 + 3"
    }
  ]
}

Handler Interface

Handlers receive a Context and Request, and return a Response:

import type { AgentHandler, Context, Request, Response } from '@reminix/runtime';

const myAgent: AgentHandler = async (context: Context, request: Request): Promise<Response> => {
  // Access context
  const chatId = context.chatId;
  const memory = context.memory;

  // Access request
  const messages = request.messages;
  const metadata = request.metadata;

  // Return response
  return {
    messages: [
      {
        role: 'assistant',
        content: 'Response here',
      },
    ],
    metadata: {
      tokensUsed: 100,
    },
    toolCalls: [], // Optional
    stateUpdates: {}, // Optional
  };
};

API Reference

startServer(handlerPath, options?)

Start an HTTP server for the given handler.

Parameters:

• handlerPath (string): Path to handler file or directory
• options (ServerOptions, optional):
  • port (number): Port to listen on (default: 3000)
  • host (string): Host to listen on (default: 'localhost')
  • context (function): Custom context provider

Returns: Promise<void>

loadHandler(handlerPath)

Load a handler from a file.

Parameters:

• handlerPath (string): Path to handler file

Returns: Promise<LoadedHandler>

discoverRegistry(handlerPath)

Auto-discover handlers from a directory structure.

Parameters:

• handlerPath (string): Path to handler directory

Returns: Promise<Registry>

convertHttpToRequest(httpReq)

Convert HTTP request to handler Request format.

Parameters:

• httpReq (IncomingMessage): Node.js HTTP request

Returns: Promise<Request>

convertResponseToHttp(handlerRes, httpRes)

Convert handler Response to HTTP response.

Parameters:

• handlerRes (Response): Handler response
• httpRes (ServerResponse): Node.js HTTP response

Returns: void

TypeScript Support

This package is written in TypeScript and includes full type definitions. No additional @types package needed.

License

MIT

Links

• GitHub Repository
• Documentation