@vrealtime/server 0.0.0-stage → 0.2.0

package/dist/node/index.d.ts

@@ -0,0 +1,23 @@
+import type { AgentDefinition } from '@vrealtime/core';
+import { Hub, type AttachOptions } from '../index.js';
+export interface ServeOptions extends AttachOptions {
+    /** Default 8790; 0 picks a free port. */
+    port?: number;
+    /** Default `localhost`. */
+    host?: string;
+    /** Serve static files from this directory; its `index.html` replaces the debug page. */
+    publicDir?: string | URL;
+    /** Called once listening; logs the URL by default. */
+    onListening?: (url: string) => void;
+}
+export interface RunningServer {
+    url: string;
+    port: number;
+    hub: Hub;
+    close(): Promise<void>;
+}
+/**
+ * Serves `agent` on Node: WebSocket protocol v1 on every path, the microphone
+ * debug page (or `publicDir`) over HTTP. Needs the optional peer dependency `ws`.
+ */
+export declare function serve(agent: AgentDefinition, options?: ServeOptions): Promise<RunningServer>;

package/dist/node/index.js

@@ -0,0 +1,120 @@
+/// <reference types="node" />
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Hub } from '../index.js';
+import { DEBUG_PAGE } from './debug-page.js';
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json',
+    '.map': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.wasm': 'application/wasm',
+};
+function toHeaders(req) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value))
+            for (const v of value)
+                headers.append(name, v);
+        else if (value !== undefined)
+            headers.set(name, value);
+    }
+    return headers;
+}
+const utf8 = new TextDecoder();
+function toBytes(data) {
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    return data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+}
+/**
+ * Serves `agent` on Node: WebSocket protocol v1 on every path, the microphone
+ * debug page (or `publicDir`) over HTTP. Needs the optional peer dependency `ws`.
+ */
+export async function serve(agent, options = {}) {
+    let ws;
+    try {
+        ws = await import('ws');
+    }
+    catch {
+        throw new Error('@vrealtime/server/node: serve() needs the optional peer dependency "ws" (npm i ws)');
+    }
+    const hub = new Hub(agent, options);
+    const publicDir = options.publicDir === undefined ? undefined : resolve(options.publicDir instanceof URL ? fileURLToPath(options.publicDir) : options.publicDir);
+    const wss = new ws.WebSocketServer({ noServer: true });
+    async function handle(req, res) {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405).end();
+            return;
+        }
+        const path = decodeURIComponent(new URL(req.url ?? '/', 'http://localhost').pathname);
+        if (publicDir !== undefined) {
+            const file = resolve(publicDir, `.${path.endsWith('/') ? `${path}index.html` : path}`);
+            if (file !== publicDir && !file.startsWith(publicDir + sep)) {
+                res.writeHead(403).end();
+                return;
+            }
+            try {
+                const body = await readFile(file);
+                res.writeHead(200, { 'content-type': CONTENT_TYPES[extname(file)] ?? 'application/octet-stream' }).end(req.method === 'HEAD' ? undefined : body);
+            }
+            catch {
+                res.writeHead(404).end('Not found');
+            }
+            return;
+        }
+        if (path !== '/') {
+            res.writeHead(404).end('Not found');
+            return;
+        }
+        res.writeHead(200, { 'content-type': CONTENT_TYPES['.html'] }).end(req.method === 'HEAD' ? undefined : DEBUG_PAGE);
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch(() => res.writeHead(500).end());
+    });
+    server.on('upgrade', (req, socket, head) => {
+        wss.handleUpgrade(req, socket, head, (client) => {
+            const connection = hub.attach({
+                send: (data) => client.send(data),
+                close: (code, reason) => client.close(code, reason),
+                get bufferedAmount() {
+                    return client.bufferedAmount;
+                },
+            }, { headers: toHeaders(req) });
+            client.on('message', (data, isBinary) => connection.receive(isBinary ? toBytes(data) : utf8.decode(toBytes(data))));
+            client.on('close', () => connection.closed());
+            client.on('error', () => connection.closed());
+        });
+    });
+    const host = options.host ?? 'localhost';
+    await new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(options.port ?? 8790, host, () => {
+            server.off('error', reject);
+            resolveListen();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : (options.port ?? 8790);
+    const url = `http://${host}:${port}`;
+    (options.onListening ?? ((u) => console.log(`vRealTime listening on ${u}`)))(url);
+    return {
+        url,
+        port,
+        hub,
+        async close() {
+            for (const client of wss.clients)
+                client.terminate();
+            await hub.close();
+            wss.close();
+            await new Promise((done) => server.close(() => done()));
+        },
+    };
+}

package/dist/tool-stream.d.ts

@@ -0,0 +1,8 @@
+import type { ToolStreamEvent } from '@vrealtime/core';
+import type { ServerMessage, Unsequenced } from '@vrealtime/protocol';
+type Outgoing = Unsequenced<ServerMessage>;
+/** With `tool-stream-v1`: the step as a `tool.stream` message. A server tool's output never leaves the server. */
+export declare function toolStreamMessage(event: ToolStreamEvent): Outgoing;
+/** Without the capability: argument fragments and progress as the `tool.call.delta` preview of protocol 1.0; nothing else is sent. */
+export declare function legacyPreview(event: ToolStreamEvent): Outgoing | undefined;
+export {};

package/dist/tool-stream.js

@@ -0,0 +1,29 @@
+/** With `tool-stream-v1`: the step as a `tool.stream` message. A server tool's output never leaves the server. */
+export function toolStreamMessage(event) {
+    const call = { type: 'tool.stream', callId: event.callId, epoch: event.epoch, turnId: event.turnId, name: event.name };
+    switch (event.phase) {
+        case 'start':
+        case 'cancelled':
+            return { ...call, phase: event.phase };
+        case 'arguments-delta':
+            return { ...call, phase: event.phase, delta: event.delta };
+        // Required members on the wire: a missing value is sent as null.
+        case 'arguments-complete':
+            return { ...call, phase: event.phase, arguments: event.arguments ?? null };
+        case 'progress':
+            return { ...call, phase: event.phase, progress: event.progress ?? null };
+        case 'settled':
+            return event.result.ok ? { ...call, phase: 'settled', ok: true } : { ...call, phase: 'settled', ok: false, code: event.result.code };
+        case 'failed':
+            return { ...call, phase: event.phase, message: event.message };
+    }
+}
+/** Without the capability: argument fragments and progress as the `tool.call.delta` preview of protocol 1.0; nothing else is sent. */
+export function legacyPreview(event) {
+    const call = { type: 'tool.call.delta', callId: event.callId, epoch: event.epoch, name: event.name };
+    if (event.phase === 'arguments-delta')
+        return { ...call, preview: { argumentsDelta: event.delta } };
+    if (event.phase === 'progress')
+        return { ...call, preview: event.progress ?? null };
+    return undefined;
+}

package/dist/workers/index.d.ts

@@ -0,0 +1,15 @@
+import type { AgentDefinition } from '@vrealtime/core';
+import { Hub, type AttachOptions } from '../index.js';
+/**
+ * Upgrades a request to a vRealTime session on Cloudflare Workers or inside a
+ * Durable Object's `fetch()`. Sessions live in memory (per isolate, or per object),
+ * so route reconnects to the same Durable Object to resume. Use the standard,
+ * non-hibernating WebSocket API.
+ *
+ * ```ts
+ * export default { fetch: (request) => upgrade(agent, request) };
+ * ```
+ */
+export declare function upgrade(agent: AgentDefinition | Hub, request: Request, options?: AttachOptions): Response;
+export type { AttachOptions, AuthRequest, Connection, Principal } from '../index.js';
+export { Hub };

package/dist/workers/index.js

@@ -0,0 +1,37 @@
+import { Hub } from '../index.js';
+const hubs = new WeakMap();
+function hubFor(agent, options) {
+    if (agent instanceof Hub)
+        return agent;
+    let hub = hubs.get(agent);
+    if (!hub) {
+        hub = new Hub(agent, options);
+        hubs.set(agent, hub);
+    }
+    return hub;
+}
+/**
+ * Upgrades a request to a vRealTime session on Cloudflare Workers or inside a
+ * Durable Object's `fetch()`. Sessions live in memory (per isolate, or per object),
+ * so route reconnects to the same Durable Object to resume. Use the standard,
+ * non-hibernating WebSocket API.
+ *
+ * ```ts
+ * export default { fetch: (request) => upgrade(agent, request) };
+ * ```
+ */
+export function upgrade(agent, request, options) {
+    if (request.headers.get('Upgrade')?.toLowerCase() !== 'websocket') {
+        return new Response('Expected a WebSocket upgrade', { status: 426, headers: { Upgrade: 'websocket' } });
+    }
+    const Pair = globalThis.WebSocketPair;
+    if (!Pair)
+        throw new Error('@vrealtime/server/workers: upgrade() needs the Workers runtime (WebSocketPair)');
+    const pair = new Pair();
+    const client = pair[0];
+    const server = pair[1];
+    server.accept();
+    hubFor(agent, options).attach(server, { headers: request.headers });
+    return new Response(null, { status: 101, webSocket: client });
+}
+export { Hub };

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@vrealtime/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "vRealTime server: attach any WebSocket, Node serve(), Cloudflare Workers and Durable Objects",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/austinchennn/vRT.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/austinchennn/vRT#readme",
+  "bugs": "https://github.com/austinchennn/vRT/issues",
+  "keywords": [
+    "realtime",
+    "voice",
+    "agent",
+    "websocket",
+    "vrealtime"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@vrealtime/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "@vrealtime/source": "./src/node/index.ts",
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./workers": {
+      "@vrealtime/source": "./src/workers/index.ts",
+      "types": "./dist/workers/index.d.ts",
+      "default": "./dist/workers/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@vrealtime/core": "0.2.0",
+    "@vrealtime/protocol": "0.2.0"
+  },
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  }
+}