@formant/realtime-tools

Client for Formant cortex Realtime Tool Sources. Register JSON-RPC tools over a WebSocket, handle tools/call requests, and upload files to your source's HTTP endpoint — without writing any plumbing.

Install

npm install @formant/realtime-tools

Requires Node.js 18+ (uses the built-in fetch).

Quick start

Create a source at /admin/remote-realtime-tools in your cortex deployment — it gives you a wsUrl and a sourceId. Then:

import { RealtimeToolSourceClient } from '@formant/realtime-tools';

const client = new RealtimeToolSourceClient({
  wsUrl: process.env.WS_URL,      // ws://host/sources/ws?token=...
  sourceId: process.env.SOURCE_ID,
});

client.tool({
  name: 'echo',
  description: 'Echo back its input.',
  inputSchema: {
    type: 'object',
    properties: { msg: { type: 'string' } },
    required: ['msg'],
  },
  handler: async ({ msg }) => ({ msg }),
});

client.tool({
  name: 'make_readme',
  description: 'Upload a text file and return its public URL.',
  inputSchema: {
    type: 'object',
    properties: { body: { type: 'string' } },
    required: ['body'],
  },
  handler: async ({ body }, ctx) => {
    const { url } = await ctx.uploadFile(Buffer.from(body, 'utf8'), 'text/plain');
    return { url };
  },
});

client.start();

API

new RealtimeToolSourceClient(options)

| Option | Type | Description | | --- | --- | --- | | wsUrl | string | The ws(s)://…?token=… URL from the admin console. Required. | | sourceId | string | The source id from the admin console. Required. | | httpOrigin | string | Override the http(s) origin derived from wsUrl. | | log | (...a) => void | Logger for info messages. Defaults to console.log. | | error | (...a) => void | Logger for errors. Defaults to console.error. | | installSignalHandlers | boolean | Install a SIGINT handler to close cleanly. Default true. |

client.tool({ name, description, inputSchema, handler })

Register a tool. Must be called before start(). Returns the client for chaining.

handler(args, ctx) receives:

• args — the JSON arguments from tools/call.
• ctx — { sourceId, httpOrigin, uploadFile }.

Whatever the handler returns becomes the JSON-RPC result. Thrown errors become a JSON-RPC error with code -32000.

client.uploadFile(bytes, mimeType)

POSTs bytes to /realtime/sources/:sourceId/files and returns { url, mimeType, sizeBytes, fileId }. url is absolute (origin-prefixed).

client.start()

Opens the WebSocket, sends the register notification, and begins dispatching tools/call requests.

client.stop(reason?)

Closes the WebSocket with code 1000.

License

MIT