@vrealtime/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @vrealtime/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+vRealTime server: attach any WebSocket, Node serve(), Cloudflare Workers and Durable Objects
+
+Part of [vRealTime](https://github.com/austinchennn/vRT). Licensed under Apache-2.0.

package/dist/capabilities.d.ts

@@ -0,0 +1,13 @@
+import type { Capabilities } from '@vrealtime/core';
+/**
+ * A protocol capability (spec/capabilities.json) this server implements. It is
+ * offered only when the agent's model can support it, e.g. argument streaming.
+ */
+export interface CapabilityRule {
+    token: string;
+    available(model: Capabilities): boolean;
+}
+/** Every capability this server implements. None yet. */
+export declare const CAPABILITY_RULES: readonly CapabilityRule[];
+/** The tokens sessions of an agent with this model may negotiate. */
+export declare function supportedCapabilities(model: Capabilities, rules?: readonly CapabilityRule[]): ReadonlySet<string>;

package/dist/capabilities.js

@@ -0,0 +1,6 @@
+/** Every capability this server implements. None yet. */
+export const CAPABILITY_RULES = [];
+/** The tokens sessions of an agent with this model may negotiate. */
+export function supportedCapabilities(model, rules = CAPABILITY_RULES) {
+    return new Set(rules.filter((rule) => rule.available(model)).map((rule) => rule.token));
+}

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import { type AgentDefinition, type AgentSession, type AudioFormat, type Clock, type SessionConfig } from '@vrealtime/core';
+import { Inbox, Outbox, type ServerMessage, type Unsequenced, type WireAudioFormat } from '@vrealtime/protocol';
+/**
+ * The only socket surface the server needs. Runtimes with event-style sockets
+ * (browsers, Deno, Workers, `ws`) can pass the socket as-is; callback-style
+ * runtimes (Bun) call `connection.receive()` and `connection.closed()` instead.
+ */
+export interface WebSocketLike {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    /** Bytes queued but not yet sent; enables backpressure when present. */
+    readonly bufferedAmount?: number;
+    addEventListener?(type: 'message' | 'close', listener: (event: {
+        data?: unknown;
+    }) => void): void;
+}
+/** Who is connected. `id` identifies the subject: a resume must come from the same `id`. */
+export interface Principal {
+    id: string;
+    [key: string]: unknown;
+}
+export interface AuthRequest {
+    /** `hello.auth`: a short-lived token sent in the first message, never in the URL. */
+    token: string | undefined;
+    /** `hello.context`, e.g. the document the app wants to work on. */
+    context: unknown;
+    /** Set when the client is resuming a session. */
+    sessionId: string | undefined;
+    /** Headers of the upgrade request, when the edge has them (cookies, origin). */
+    headers: Headers | undefined;
+}
+export interface AttachOptions {
+    /**
+     * Called for every `hello`, new or resumed. Return a principal to accept, or
+     * `null` / `undefined` / `false` (or throw) to refuse with `UNAUTHORIZED`.
+     * Without it every connection is accepted.
+     */
+    authenticate?: (request: AuthRequest) => Principal | null | undefined | false | Promise<Principal | null | undefined | false>;
+    /** Per-session config for new sessions (instructions, voice, transcription vocabulary...), from the principal and `hello.context`. */
+    configure?: (principal: Principal | undefined, hello: {
+        context: unknown;
+    }) => Partial<SessionConfig> | Promise<Partial<SessionConfig>>;
+    /** How long a session survives without a socket, waiting for a resume. Default 30 s. */
+    resumeWindowMs?: number;
+    /** Close a socket that sent nothing (not even `ping`) for this long. Default 45 s. */
+    heartbeatTimeoutMs?: number;
+    /** Queue outgoing frames while `bufferedAmount` exceeds this. Default 256 KiB. */
+    highWaterMark?: number;
+    /** Receives `context` messages and `hello.context` from the app. */
+    onContext?: (context: unknown, session: AgentSession) => void;
+    clock?: Clock;
+}
+export interface Connection {
+    /** Feed one incoming WebSocket message (text or binary). */
+    receive(data: unknown): void;
+    /** Tell the server the socket closed. */
+    closed(): void;
+    readonly sessionId: string | undefined;
+}
+export declare function toCoreFormat(format: WireAudioFormat | undefined): AudioFormat | undefined;
+export declare function toWireFormat(format: AudioFormat): WireAudioFormat;
+/** One agent session and everything that must survive a reconnect. */
+declare class LiveSession {
+    #private;
+    private readonly hub;
+    readonly principal: Principal | undefined;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly outbox: Outbox<ServerMessage>;
+    readonly inbox: Inbox;
+    session: AgentSession;
+    input: AudioFormat;
+    output: AudioFormat;
+    /** Negotiated when the session starts; fixed for its lifetime, resumes included. */
+    capabilities: readonly string[];
+    socket: SocketConnection | undefined;
+    expiry: unknown;
+    constructor(hub: Hub, principal: Principal | undefined);
+    bind(agentSession: AgentSession): void;
+    send(message: Unsequenced<ServerMessage>, epoch?: number): void;
+    /** Opens the session on the bound socket; `resumedFrom` is set on a resume. */
+    sendReady(resumedFrom?: number): void;
+    /** Re-sends everything after the client's last seen seq. False when that is no longer possible. */
+    resend(lastSeen: number): boolean;
+    detach(): void;
+    flush(): void;
+}
+declare class SocketConnection implements Connection {
+    #private;
+    private readonly hub;
+    private readonly socket;
+    private readonly headers?;
+    constructor(hub: Hub, socket: WebSocketLike, headers?: Headers | undefined);
+    get sessionId(): string | undefined;
+    congested(): boolean;
+    send(data: string | Uint8Array): void;
+    close(code: number, reason: string): void;
+    receive(data: unknown): void;
+    closed(): void;
+}
+/** Shares sessions between sockets, so a reconnecting app can resume. */
+export declare class Hub {
+    #private;
+    readonly agent: AgentDefinition;
+    readonly options: AttachOptions;
+    readonly clock: Clock;
+    readonly highWaterMark: number;
+    readonly heartbeatTimeoutMs: number;
+    /** Protocol capabilities sessions may negotiate: what this server implements and the agent's model supports. */
+    readonly capabilities: ReadonlySet<string>;
+    constructor(agent: AgentDefinition, options?: AttachOptions);
+    /** `headers` (of the upgrade request) are passed to `authenticate`. */
+    attach(socket: WebSocketLike, info?: {
+        headers?: Headers;
+    }): Connection;
+    /** Live sessions, connected or waiting for a resume. */
+    get size(): number;
+    close(): Promise<void>;
+    /** @internal */
+    adopt(live: LiveSession): void;
+    /** @internal */
+    find(id: string): LiveSession | undefined;
+    /** @internal */
+    forget(live: LiveSession): void;
+    /** @internal Keeps a socketless session for `resumeWindowMs`, then closes it. */
+    park(live: LiveSession): void;
+    /** @internal */
+    unpark(live: LiveSession): void;
+}
+/**
+ * Serves `agent` over one WebSocket using protocol v1. Sockets attached for the
+ * same agent share a hub, so a reconnecting app can resume its session.
+ * Options apply when the agent's hub is first created.
+ */
+export declare function attach(agent: AgentDefinition, socket: WebSocketLike, options?: AttachOptions, info?: {
+    headers?: Headers;
+}): Connection;
+export {};

package/dist/index.js

@@ -0,0 +1,474 @@
+import { startSession, } from '@vrealtime/core';
+import { Inbox, Outbox, decodeAudioFrame, decodeClientMessage, encodeAudioFrame, encodeMessage, negotiateCapabilities, PROTOCOL_VERSION, } from '@vrealtime/protocol';
+import { supportedCapabilities } from './capabilities.js';
+const PCM24 = { encoding: 'pcm16', sampleRate: 24000, channels: 1 };
+const REFUSED = Symbol('refused');
+const FLUSH_INTERVAL_MS = 10;
+const OUTPUT = 2;
+const INPUT = 1;
+const systemClock = {
+    now: () => performance.now(),
+    setTimeout: (run, ms) => setTimeout(run, ms),
+    clearTimeout: (id) => clearTimeout(id),
+};
+export function toCoreFormat(format) {
+    if (format === undefined)
+        return undefined;
+    if (format.encoding === 'pcmu')
+        return { encoding: 'pcmu' };
+    if (format.encoding === 'opus')
+        return { encoding: 'opus', frameMs: 20 };
+    const rate = format.sampleRate;
+    return rate === 8000 || rate === 16000 || rate === 24000 || rate === 48000 ? { encoding: 'pcm16', sampleRate: rate, channels: 1 } : undefined;
+}
+export function toWireFormat(format) {
+    return format.encoding === 'pcm16' ? { encoding: 'pcm16', sampleRate: format.sampleRate } : { encoding: format.encoding };
+}
+function sameFormat(a, b) {
+    return a.encoding === b.encoding && (a.encoding !== 'pcm16' || (b.encoding === 'pcm16' && a.sampleRate === b.sampleRate));
+}
+/** Use the app's format when the model takes it as-is (pass-through), otherwise 24 kHz PCM16. */
+function negotiate(requested, supported) {
+    const format = toCoreFormat(requested);
+    if (format && supported.some((s) => sameFormat(s, format)))
+        return format;
+    return supported.find((s) => sameFormat(s, PCM24)) ?? supported[0] ?? PCM24;
+}
+/** One agent session and everything that must survive a reconnect. */
+class LiveSession {
+    hub;
+    principal;
+    id = crypto.randomUUID();
+    outbox = new Outbox();
+    inbox = new Inbox();
+    session;
+    input = PCM24;
+    output = PCM24;
+    /** Negotiated when the session starts; fixed for its lifetime, resumes included. */
+    capabilities = [];
+    socket;
+    expiry;
+    #audioSeq = 0;
+    #audioItem;
+    #queue = [];
+    #flushTimer;
+    constructor(hub, principal) {
+        this.hub = hub;
+        this.principal = principal;
+    }
+    bind(agentSession) {
+        this.session = agentSession;
+        agentSession.on('turn.state', (e) => this.send({ type: 'turn.state', turnId: e.turnId, epoch: e.epoch, state: e.state }));
+        agentSession.on('transcript', (e) => this.send({ type: 'transcript', role: e.role, itemId: e.itemId, text: e.text, final: e.final }));
+        agentSession.on('text', (e) => this.send({ type: 'text', responseId: e.responseId, delta: e.delta }));
+        agentSession.on('audio', (e) => this.#audio(e));
+        // `arguments` and `preview` are required members on the wire: a missing value is sent as null.
+        agentSession.on('tool.call', (e) => this.send({ type: 'tool.call', callId: e.callId, epoch: e.epoch, turnId: e.turnId, name: e.name, arguments: e.arguments ?? null }));
+        agentSession.on('tool.call.delta', (e) => this.send({ type: 'tool.call.delta', callId: e.callId, epoch: e.epoch, name: e.name, preview: { argumentsDelta: e.argumentsDelta } }));
+        agentSession.on('tool.preview', (e) => this.send({ type: 'tool.call.delta', callId: e.callId, epoch: e.epoch, name: e.name, preview: e.preview ?? null }));
+        agentSession.on('interrupted', (e) => {
+            this.#dropAudio(e.epoch);
+            this.send({ type: 'interrupted', epoch: e.epoch });
+        });
+        agentSession.on('error', (e) => this.send({ type: 'error', code: 'AGENT_ERROR', message: e.error.message, recoverable: e.recoverable }));
+        agentSession.on('closed', () => {
+            this.hub.forget(this);
+            this.socket?.close(1000, 'session closed');
+        });
+    }
+    send(message, epoch) {
+        const stamped = this.outbox.stamp(message);
+        this.#write(encodeMessage(stamped), epoch);
+    }
+    /** Opens the session on the bound socket; `resumedFrom` is set on a resume. */
+    sendReady(resumedFrom) {
+        this.send({
+            type: 'ready',
+            sessionId: this.id,
+            input: toWireFormat(this.input),
+            output: toWireFormat(this.output),
+            ...(resumedFrom !== undefined ? { resumedFrom } : {}),
+            ...(this.capabilities.length > 0 ? { capabilities: [...this.capabilities] } : {}),
+        });
+    }
+    /** Re-sends everything after the client's last seen seq. False when that is no longer possible. */
+    resend(lastSeen) {
+        const missed = this.outbox.resendFrom(lastSeen);
+        if (missed === undefined)
+            return false;
+        for (const message of missed)
+            this.#write(encodeMessage(message));
+        return true;
+    }
+    detach() {
+        this.socket = undefined;
+        this.#queue = [];
+        this.#audioItem = undefined;
+    }
+    flush() {
+        this.#flushTimer = undefined;
+        const socket = this.socket;
+        if (!socket) {
+            this.#queue = [];
+            return;
+        }
+        while (this.#queue.length > 0 && !socket.congested())
+            socket.send(this.#queue.shift().data);
+        if (this.#queue.length > 0)
+            this.#scheduleFlush();
+    }
+    #audio(event) {
+        if (!this.socket)
+            return;
+        if (event.itemId !== this.#audioItem) {
+            this.#audioItem = event.itemId;
+            this.send({ type: 'audio.start', itemId: event.itemId, responseId: event.responseId, epoch: event.epoch }, event.epoch);
+        }
+        this.#write(encodeAudioFrame(OUTPUT, this.#audioSeq++, event.chunk.data), event.epoch);
+    }
+    /** Frames keep their order: once anything is queued, everything queues behind it. */
+    #write(data, epoch) {
+        const socket = this.socket;
+        if (!socket)
+            return;
+        if (this.#queue.length === 0 && !socket.congested()) {
+            socket.send(data);
+            return;
+        }
+        this.#queue.push(epoch === undefined ? { data } : { data, epoch });
+        this.#scheduleFlush();
+    }
+    #dropAudio(closedEpoch) {
+        this.#queue = this.#queue.filter((item) => item.epoch === undefined || item.epoch > closedEpoch);
+        this.#audioItem = undefined;
+    }
+    #scheduleFlush() {
+        if (this.#flushTimer === undefined)
+            this.#flushTimer = this.hub.clock.setTimeout(() => this.flush(), FLUSH_INTERVAL_MS);
+    }
+}
+class SocketConnection {
+    hub;
+    socket;
+    headers;
+    #live;
+    #starting;
+    #pending = [];
+    #closed = false;
+    #lastSeen;
+    #heartbeat;
+    #ackScheduled = false;
+    constructor(hub, socket, headers) {
+        this.hub = hub;
+        this.socket = socket;
+        this.headers = headers;
+        this.#lastSeen = hub.clock.now();
+        this.#checkHeartbeat();
+        socket.addEventListener?.('message', (event) => this.receive(event.data));
+        socket.addEventListener?.('close', () => this.closed());
+    }
+    get sessionId() {
+        return this.#live?.id;
+    }
+    congested() {
+        return (this.socket.bufferedAmount ?? 0) > this.hub.highWaterMark;
+    }
+    send(data) {
+        if (!this.#closed)
+            this.socket.send(data);
+    }
+    close(code, reason) {
+        if (this.#closed)
+            return;
+        this.socket.close(code, reason);
+        this.closed();
+    }
+    receive(data) {
+        if (this.#closed)
+            return;
+        this.#lastSeen = this.hub.clock.now();
+        if (typeof data !== 'string') {
+            this.#receiveAudio(data);
+            return;
+        }
+        const decoded = decodeClientMessage(data);
+        if (!decoded.ok) {
+            this.#error(decoded.error.code, decoded.error.message, true);
+            return;
+        }
+        const message = decoded.message;
+        if (message.type === 'ping') {
+            this.#sendDirect({ type: 'pong' });
+            return;
+        }
+        if (message.type === 'hello') {
+            void this.#hello(message);
+            return;
+        }
+        if (this.#starting || !this.#live) {
+            if (this.#starting)
+                this.#pending.push(message);
+            else
+                this.#error('NO_SESSION', 'Send hello first', false);
+            return;
+        }
+        this.#handle(this.#live, message);
+    }
+    closed() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.hub.clock.clearTimeout(this.#heartbeat);
+        const live = this.#live;
+        if (live?.socket === this) {
+            live.detach();
+            this.hub.park(live);
+        }
+    }
+    #receiveAudio(data) {
+        const bytes = data instanceof Uint8Array ? data : data instanceof ArrayBuffer ? new Uint8Array(data) : undefined;
+        const frame = bytes && decodeAudioFrame(bytes);
+        if (!frame || frame.kind !== INPUT) {
+            this.#error('MALFORMED', 'Invalid audio frame', true);
+            return;
+        }
+        const live = this.#live;
+        if (live && !this.#starting)
+            live.session.sendAudio({ data: frame.payload, format: live.input });
+    }
+    async #hello(hello) {
+        if (this.#live || this.#starting) {
+            this.#error('DUPLICATE_HELLO', 'hello was already received', true);
+            return;
+        }
+        // Messages that arrive while authenticating or starting are queued in order.
+        let done;
+        this.#starting = new Promise((resolve) => { done = resolve; });
+        try {
+            const principal = await this.#authenticate(hello);
+            if (this.#closed)
+                return;
+            if (principal === REFUSED) {
+                this.#error('UNAUTHORIZED', 'Authentication failed', false);
+                this.close(4401, 'unauthorized');
+                return;
+            }
+            const live = hello.sessionId !== undefined ? this.#resume(hello, principal) : await this.#start(hello, principal);
+            if (!live)
+                return;
+            if (hello.context !== undefined)
+                this.hub.options.onContext?.(hello.context, live.session);
+            for (const message of this.#pending.splice(0))
+                this.#handle(live, message);
+        }
+        finally {
+            this.#starting = undefined;
+            done();
+        }
+    }
+    async #authenticate(hello) {
+        const authenticate = this.hub.options.authenticate;
+        if (!authenticate)
+            return undefined;
+        try {
+            const principal = await authenticate({ token: hello.auth, context: hello.context, sessionId: hello.sessionId, headers: this.headers });
+            return principal ? principal : REFUSED;
+        }
+        catch {
+            return REFUSED;
+        }
+    }
+    async #start(hello, principal) {
+        const live = new LiveSession(this.hub, principal);
+        const supported = this.hub.agent.model.capabilities;
+        live.input = negotiate(hello.input, supported.input.formats);
+        live.output = negotiate(hello.output, supported.output.formats);
+        live.capabilities = negotiateCapabilities(hello.capabilities, this.hub.capabilities);
+        try {
+            const configured = (await this.hub.options.configure?.(principal, { context: hello.context })) ?? {};
+            const session = await startSession(this.hub.agent, {
+                clientTools: hello.tools,
+                config: { ...configured, inputFormat: live.input, outputFormat: live.output },
+                clock: this.hub.clock,
+                data: principal,
+            });
+            live.bind(session);
+        }
+        catch (error) {
+            this.#error('START_FAILED', error instanceof Error ? error.message : String(error), false);
+            this.close(1011, 'session start failed');
+            return undefined;
+        }
+        this.hub.adopt(live);
+        if (this.#closed) {
+            // The socket went away while the model was connecting; park so a resume can still find it.
+            this.hub.park(live);
+            return undefined;
+        }
+        this.#bind(live);
+        live.sendReady();
+        live.resend(0); // anything the session emitted before the socket was bound
+        return live;
+    }
+    #resume(hello, principal) {
+        const live = this.hub.find(hello.sessionId);
+        // An unknown session and someone else's session get the same answer.
+        if (!live || live.principal?.id !== principal?.id) {
+            this.#error('RESUME_FAILED', 'Unknown or expired session', false);
+            this.close(4404, 'unknown session');
+            return undefined;
+        }
+        live.socket?.close(4000, 'replaced by a newer connection');
+        this.#bind(live);
+        if (live.session.closed)
+            return undefined;
+        live.sendReady(live.inbox.lastSeq);
+        if (!live.resend(hello.resumeFrom ?? 0)) {
+            this.#error('RESUME_FAILED', 'Cannot resend from resumeFrom: those messages were dropped or never sent', false);
+            void live.session.close();
+            return undefined;
+        }
+        return live;
+    }
+    #bind(live) {
+        this.hub.unpark(live);
+        this.#live = live;
+        live.socket = this;
+    }
+    #handle(live, message) {
+        if (message.type === 'ack') {
+            live.outbox.ack(message.upTo);
+            return;
+        }
+        if (!live.inbox.accept(message)) {
+            this.#scheduleAck(live);
+            return;
+        }
+        const session = live.session;
+        switch (message.type) {
+            case 'text':
+                session.sendText(message.text);
+                break;
+            case 'interrupt':
+                session.interrupt(message.reason);
+                break;
+            case 'playback':
+                session.playback(message.itemId, message.playedMs);
+                break;
+            case 'tool.result': {
+                const result = message.ok
+                    ? { ok: true, output: message.output }
+                    : { ok: false, code: message.code, message: message.message };
+                session.submitClientToolResult(message.callId, result);
+                break;
+            }
+            case 'context':
+                this.hub.options.onContext?.(message.context, session);
+                break;
+        }
+        this.#scheduleAck(live);
+    }
+    #scheduleAck(live) {
+        if (this.#ackScheduled)
+            return;
+        this.#ackScheduled = true;
+        queueMicrotask(() => {
+            this.#ackScheduled = false;
+            if (live.socket === this)
+                live.send({ type: 'ack', upTo: live.inbox.lastSeq });
+        });
+    }
+    #sendDirect(message) {
+        if (this.#live?.socket === this)
+            this.#live.send(message);
+        else
+            this.send(encodeMessage({ v: PROTOCOL_VERSION, seq: 0, ...message }));
+    }
+    #error(code, message, recoverable) {
+        this.#sendDirect({ type: 'error', code, message, recoverable });
+    }
+    #checkHeartbeat() {
+        const timeout = this.hub.heartbeatTimeoutMs;
+        this.#heartbeat = this.hub.clock.setTimeout(() => {
+            if (this.#closed)
+                return;
+            if (this.hub.clock.now() - this.#lastSeen >= timeout)
+                this.close(4408, 'heartbeat timeout');
+            else
+                this.#checkHeartbeat();
+        }, Math.max(1, timeout / 3));
+    }
+}
+/** Shares sessions between sockets, so a reconnecting app can resume. */
+export class Hub {
+    agent;
+    options;
+    clock;
+    highWaterMark;
+    heartbeatTimeoutMs;
+    /** Protocol capabilities sessions may negotiate: what this server implements and the agent's model supports. */
+    capabilities;
+    #sessions = new Map();
+    constructor(agent, options = {}) {
+        this.agent = agent;
+        this.options = options;
+        this.capabilities = supportedCapabilities(agent.model.capabilities);
+        this.clock = options.clock ?? systemClock;
+        this.highWaterMark = options.highWaterMark ?? 256 * 1024;
+        this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? 45_000;
+    }
+    /** `headers` (of the upgrade request) are passed to `authenticate`. */
+    attach(socket, info = {}) {
+        return new SocketConnection(this, socket, info.headers);
+    }
+    /** Live sessions, connected or waiting for a resume. */
+    get size() {
+        return this.#sessions.size;
+    }
+    async close() {
+        await Promise.all([...this.#sessions.values()].map((live) => live.session.close()));
+        this.#sessions.clear();
+    }
+    /** @internal */
+    adopt(live) {
+        this.#sessions.set(live.id, live);
+    }
+    /** @internal */
+    find(id) {
+        return this.#sessions.get(id);
+    }
+    /** @internal */
+    forget(live) {
+        this.unpark(live);
+        this.#sessions.delete(live.id);
+    }
+    /** @internal Keeps a socketless session for `resumeWindowMs`, then closes it. */
+    park(live) {
+        this.unpark(live);
+        live.expiry = this.clock.setTimeout(() => {
+            live.expiry = undefined;
+            if (!live.socket)
+                void live.session.close();
+        }, this.options.resumeWindowMs ?? 30_000);
+    }
+    /** @internal */
+    unpark(live) {
+        if (live.expiry !== undefined)
+            this.clock.clearTimeout(live.expiry);
+        live.expiry = undefined;
+    }
+}
+const hubs = new WeakMap();
+/**
+ * Serves `agent` over one WebSocket using protocol v1. Sockets attached for the
+ * same agent share a hub, so a reconnecting app can resume its session.
+ * Options apply when the agent's hub is first created.
+ */
+export function attach(agent, socket, options, info) {
+    let hub = hubs.get(agent);
+    if (!hub) {
+        hub = new Hub(agent, options);
+        hubs.set(agent, hub);
+    }
+    return hub.attach(socket, info);
+}

package/dist/node/debug-page.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Microphone debug page served by `serve()` at `/`. A dependency-free protocol v1
+ * client: text and voice in, transcripts and audio out, a barge-in interrupt and
+ * one app-side tool (`set_accent_color`) behind an epoch gate.
+ */
+export declare const DEBUG_PAGE = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n<title>vRealTime debug</title>\n<style>\n  :root { --accent: #2563eb; --bg: #fff; --fg: #111827; --muted: #6b7280; --line: #e5e7eb; color-scheme: light dark; }\n  @media (prefers-color-scheme: dark) { :root { --bg: #0b0f17; --fg: #e5e7eb; --muted: #9ca3af; --line: #1f2937; } }\n  body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }\n  main { max-width: 720px; margin: 0 auto; padding: 16px; }\n  h1 { font-size: 20px; margin: 0 0 4px; color: var(--accent); }\n  .muted { color: var(--muted); font-size: 13px; }\n  .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 12px 0; }\n  button { background: var(--accent); color: #fff; border: 0; border-radius: 6px; padding: 8px 14px; font: inherit; cursor: pointer; }\n  button.secondary { background: transparent; color: var(--fg); border: 1px solid var(--line); }\n  form { display: flex; gap: 8px; }\n  input { flex: 1; min-width: 0; padding: 8px; border: 1px solid var(--line); border-radius: 6px; background: transparent; color: inherit; font: inherit; }\n  #state { padding: 2px 8px; border-radius: 99px; border: 1px solid var(--accent); color: var(--accent); font-size: 13px; }\n  #log { border-top: 1px solid var(--line); margin-top: 12px; padding-top: 8px; }\n  #log p { margin: 6px 0; } .user { font-weight: 600; } .note { color: var(--muted); font-size: 13px; }\n</style>\n</head>\n<body>\n<main>\n  <h1>vRealTime</h1>\n  <div class=\"muted\" id=\"status\">connecting\u2026</div>\n  <div class=\"row\">\n    <button id=\"mic\">Start mic</button>\n    <button id=\"stop\" class=\"secondary\">Interrupt</button>\n    <span id=\"state\">idle</span>\n  </div>\n  <form id=\"form\"><input id=\"text\" placeholder=\"Type a message\" autocomplete=\"off\"><button>Send</button></form>\n  <div id=\"log\"></div>\n</main>\n<script type=\"module\">\nconst RATE = 24000, FRAME = 480, TRANSIENT = ['hello', 'ack', 'ping'];\nconst $ = (id) => document.getElementById(id);\nlet seq = 0, lastSeq = 0, epoch = 0, closedEpoch = -1, audioSeq = 0;\n\nconst tools = {\n  set_accent_color: {\n    description: 'Set the page accent color to any CSS color.',\n    parameters: { type: 'object', properties: { color: { type: 'string' } }, required: ['color'] },\n    run: ({ color }) => { document.documentElement.style.setProperty('--accent', color); return { color }; },\n  },\n};\n\nconst ws = new WebSocket(location.origin.replace(/^http/, 'ws') + location.pathname);\nws.binaryType = 'arraybuffer';\nconst send = (m) => { if (ws.readyState === 1) ws.send(JSON.stringify({ v: 1, seq: TRANSIENT.includes(m.type) ? 0 : ++seq, ...m })); };\nws.onopen = () => send({\n  type: 'hello',\n  tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, parameters: t.parameters })),\n  input: { encoding: 'pcm16', sampleRate: RATE }, output: { encoding: 'pcm16', sampleRate: RATE },\n});\nws.onclose = (e) => { $('status').textContent = 'disconnected (' + e.code + ')'; };\nsetInterval(() => { send({ type: 'ping' }); if (lastSeq) send({ type: 'ack', upTo: lastSeq }); }, 10000);\n\nconst lines = new Map();\nfunction line(id, role, text) {\n  let el = lines.get(id);\n  if (!el) { el = document.createElement('p'); el.className = role; $('log').append(el); lines.set(id, el); }\n  el.textContent = (role === 'user' ? 'You: ' : 'Agent: ') + text;\n  el.scrollIntoView({ block: 'end' });\n}\nfunction note(text) { const el = document.createElement('p'); el.className = 'note'; el.textContent = text; $('log').append(el); }\n\n// Playback: schedule PCM16 chunks back to back; track what was actually heard per item.\nlet ctx, playhead = 0, sources = [], item;\nconst audio = () => (ctx ??= new AudioContext({ sampleRate: RATE }));\nfunction play(bytes) {\n  const c = audio(), n = bytes.byteLength >> 1, view = new DataView(bytes.buffer, bytes.byteOffset, n * 2);\n  const buffer = c.createBuffer(1, n, RATE), data = buffer.getChannelData(0);\n  for (let i = 0; i < n; i++) data[i] = view.getInt16(i * 2, true) / 32768;\n  const src = c.createBufferSource();\n  src.buffer = buffer; src.connect(c.destination);\n  const at = Math.max(playhead, c.currentTime + 0.02);\n  if (item.start === undefined) item.start = at;\n  src.start(at); playhead = at + buffer.duration; item.end = playhead;\n  sources.push(src); src.onended = () => { sources = sources.filter((s) => s !== src); };\n}\nfunction stopPlayback() {\n  for (const s of sources) s.stop();\n  sources = []; playhead = 0;\n  if (item && item.start !== undefined) {\n    const heard = Math.max(0, Math.min(audio().currentTime, item.end) - item.start) * 1000;\n    send({ type: 'playback', itemId: item.id, playedMs: Math.round(heard) });\n  }\n  item = undefined;\n}\nfunction interrupt() {\n  closedEpoch = Math.max(closedEpoch, epoch);\n  stopPlayback();\n  send({ type: 'interrupt', epoch, reason: 'user' });\n}\n\nasync function runTool(m) {\n  const tool = tools[m.name];\n  if (m.epoch <= closedEpoch) return send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: false, code: 'INTERRUPTED', message: 'interrupted' });\n  if (!tool) return send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: false, code: 'FAILED', message: 'unknown tool' });\n  try {\n    const output = await tool.run(m.arguments);\n    send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: true, output });\n    note('tool ' + m.name + ' ' + JSON.stringify(m.arguments));\n  } catch (e) {\n    send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: false, code: 'FAILED', message: String(e) });\n  }\n}\n\nws.onmessage = (e) => {\n  if (typeof e.data !== 'string') {\n    const bytes = new Uint8Array(e.data);\n    if (bytes[0] === 2 && item) play(bytes.subarray(5));\n    return;\n  }\n  const m = JSON.parse(e.data);\n  if (m.seq > 0) { if (m.seq <= lastSeq) return; lastSeq = m.seq; }\n  switch (m.type) {\n    case 'ready': $('status').textContent = 'session ' + m.sessionId; break;\n    case 'turn.state':\n      epoch = Math.max(epoch, m.epoch); $('state').textContent = m.state;\n      if (m.state === 'listening' && sources.length) stopPlayback();\n      break;\n    case 'transcript': line(m.itemId, m.role, m.text); break;\n    case 'text': line(m.responseId, 'agent', ((lines.get(m.responseId)?.textContent ?? 'Agent: ').slice(7)) + m.delta); break;\n    case 'audio.start': item = m.epoch > closedEpoch ? { id: m.itemId } : undefined; break;\n    case 'tool.call': runTool(m); break;\n    case 'interrupted': closedEpoch = Math.max(closedEpoch, m.epoch); stopPlayback(); note('interrupted'); break;\n    case 'error': note('error ' + m.code + ': ' + m.message); break;\n  }\n};\n\n$('form').onsubmit = (e) => {\n  e.preventDefault();\n  const text = $('text').value.trim();\n  if (!text) return;\n  stopPlayback(); line('local-' + seq, 'user', text); send({ type: 'text', text }); $('text').value = '';\n};\n$('stop').onclick = interrupt;\n\n// Microphone: AudioWorklet \u2192 20 ms PCM16 frames \u2192 [kind=1][seq u32 BE][payload].\nconst WORKLET = `class Capture extends AudioWorkletProcessor {\n  constructor() { super(); this.buf = new Int16Array(${FRAME}); this.n = 0; }\n  process(inputs) {\n    const ch = inputs[0][0];\n    if (ch) for (let i = 0; i < ch.length; i++) {\n      const s = Math.max(-1, Math.min(1, ch[i]));\n      this.buf[this.n++] = s < 0 ? s * 32768 : s * 32767;\n      if (this.n === ${FRAME}) { this.port.postMessage(this.buf.buffer.slice(0)); this.n = 0; }\n    }\n    return true;\n  }\n}\nregisterProcessor('vrt-capture', Capture);`;\nlet mic;\n$('mic').onclick = async () => {\n  if (mic) { mic.getTracks().forEach((t) => t.stop()); mic = undefined; $('mic').textContent = 'Start mic'; return; }\n  const c = audio();\n  await c.resume();\n  mic = await navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, channelCount: 1 } });\n  await c.audioWorklet.addModule(URL.createObjectURL(new Blob([WORKLET], { type: 'text/javascript' })));\n  const node = new AudioWorkletNode(c, 'vrt-capture');\n  node.port.onmessage = ({ data }) => {\n    if (!mic || ws.readyState !== 1) return;\n    const frame = new Uint8Array(5 + data.byteLength);\n    frame[0] = 1; new DataView(frame.buffer).setUint32(1, audioSeq++ >>> 0); frame.set(new Uint8Array(data), 5);\n    ws.send(frame);\n  };\n  c.createMediaStreamSource(mic).connect(node);\n  $('mic').textContent = 'Stop mic';\n};\n</script>\n</body>\n</html>\n";

package/dist/node/debug-page.js

@@ -0,0 +1,181 @@
+/**
+ * Microphone debug page served by `serve()` at `/`. A dependency-free protocol v1
+ * client: text and voice in, transcripts and audio out, a barge-in interrupt and
+ * one app-side tool (`set_accent_color`) behind an epoch gate.
+ */
+export const DEBUG_PAGE = /* html */ `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>vRealTime debug</title>
+<style>
+  :root { --accent: #2563eb; --bg: #fff; --fg: #111827; --muted: #6b7280; --line: #e5e7eb; color-scheme: light dark; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0b0f17; --fg: #e5e7eb; --muted: #9ca3af; --line: #1f2937; } }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }
+  main { max-width: 720px; margin: 0 auto; padding: 16px; }
+  h1 { font-size: 20px; margin: 0 0 4px; color: var(--accent); }
+  .muted { color: var(--muted); font-size: 13px; }
+  .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 12px 0; }
+  button { background: var(--accent); color: #fff; border: 0; border-radius: 6px; padding: 8px 14px; font: inherit; cursor: pointer; }
+  button.secondary { background: transparent; color: var(--fg); border: 1px solid var(--line); }
+  form { display: flex; gap: 8px; }
+  input { flex: 1; min-width: 0; padding: 8px; border: 1px solid var(--line); border-radius: 6px; background: transparent; color: inherit; font: inherit; }
+  #state { padding: 2px 8px; border-radius: 99px; border: 1px solid var(--accent); color: var(--accent); font-size: 13px; }
+  #log { border-top: 1px solid var(--line); margin-top: 12px; padding-top: 8px; }
+  #log p { margin: 6px 0; } .user { font-weight: 600; } .note { color: var(--muted); font-size: 13px; }
+</style>
+</head>
+<body>
+<main>
+  <h1>vRealTime</h1>
+  <div class="muted" id="status">connecting…</div>
+  <div class="row">
+    <button id="mic">Start mic</button>
+    <button id="stop" class="secondary">Interrupt</button>
+    <span id="state">idle</span>
+  </div>
+  <form id="form"><input id="text" placeholder="Type a message" autocomplete="off"><button>Send</button></form>
+  <div id="log"></div>
+</main>
+<script type="module">
+const RATE = 24000, FRAME = 480, TRANSIENT = ['hello', 'ack', 'ping'];
+const $ = (id) => document.getElementById(id);
+let seq = 0, lastSeq = 0, epoch = 0, closedEpoch = -1, audioSeq = 0;
+
+const tools = {
+  set_accent_color: {
+    description: 'Set the page accent color to any CSS color.',
+    parameters: { type: 'object', properties: { color: { type: 'string' } }, required: ['color'] },
+    run: ({ color }) => { document.documentElement.style.setProperty('--accent', color); return { color }; },
+  },
+};
+
+const ws = new WebSocket(location.origin.replace(/^http/, 'ws') + location.pathname);
+ws.binaryType = 'arraybuffer';
+const send = (m) => { if (ws.readyState === 1) ws.send(JSON.stringify({ v: 1, seq: TRANSIENT.includes(m.type) ? 0 : ++seq, ...m })); };
+ws.onopen = () => send({
+  type: 'hello',
+  tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, parameters: t.parameters })),
+  input: { encoding: 'pcm16', sampleRate: RATE }, output: { encoding: 'pcm16', sampleRate: RATE },
+});
+ws.onclose = (e) => { $('status').textContent = 'disconnected (' + e.code + ')'; };
+setInterval(() => { send({ type: 'ping' }); if (lastSeq) send({ type: 'ack', upTo: lastSeq }); }, 10000);
+
+const lines = new Map();
+function line(id, role, text) {
+  let el = lines.get(id);
+  if (!el) { el = document.createElement('p'); el.className = role; $('log').append(el); lines.set(id, el); }
+  el.textContent = (role === 'user' ? 'You: ' : 'Agent: ') + text;
+  el.scrollIntoView({ block: 'end' });
+}
+function note(text) { const el = document.createElement('p'); el.className = 'note'; el.textContent = text; $('log').append(el); }
+
+// Playback: schedule PCM16 chunks back to back; track what was actually heard per item.
+let ctx, playhead = 0, sources = [], item;
+const audio = () => (ctx ??= new AudioContext({ sampleRate: RATE }));
+function play(bytes) {
+  const c = audio(), n = bytes.byteLength >> 1, view = new DataView(bytes.buffer, bytes.byteOffset, n * 2);
+  const buffer = c.createBuffer(1, n, RATE), data = buffer.getChannelData(0);
+  for (let i = 0; i < n; i++) data[i] = view.getInt16(i * 2, true) / 32768;
+  const src = c.createBufferSource();
+  src.buffer = buffer; src.connect(c.destination);
+  const at = Math.max(playhead, c.currentTime + 0.02);
+  if (item.start === undefined) item.start = at;
+  src.start(at); playhead = at + buffer.duration; item.end = playhead;
+  sources.push(src); src.onended = () => { sources = sources.filter((s) => s !== src); };
+}
+function stopPlayback() {
+  for (const s of sources) s.stop();
+  sources = []; playhead = 0;
+  if (item && item.start !== undefined) {
+    const heard = Math.max(0, Math.min(audio().currentTime, item.end) - item.start) * 1000;
+    send({ type: 'playback', itemId: item.id, playedMs: Math.round(heard) });
+  }
+  item = undefined;
+}
+function interrupt() {
+  closedEpoch = Math.max(closedEpoch, epoch);
+  stopPlayback();
+  send({ type: 'interrupt', epoch, reason: 'user' });
+}
+
+async function runTool(m) {
+  const tool = tools[m.name];
+  if (m.epoch <= closedEpoch) return send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: false, code: 'INTERRUPTED', message: 'interrupted' });
+  if (!tool) return send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: false, code: 'FAILED', message: 'unknown tool' });
+  try {
+    const output = await tool.run(m.arguments);
+    send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: true, output });
+    note('tool ' + m.name + ' ' + JSON.stringify(m.arguments));
+  } catch (e) {
+    send({ type: 'tool.result', callId: m.callId, epoch: m.epoch, ok: false, code: 'FAILED', message: String(e) });
+  }
+}
+
+ws.onmessage = (e) => {
+  if (typeof e.data !== 'string') {
+    const bytes = new Uint8Array(e.data);
+    if (bytes[0] === 2 && item) play(bytes.subarray(5));
+    return;
+  }
+  const m = JSON.parse(e.data);
+  if (m.seq > 0) { if (m.seq <= lastSeq) return; lastSeq = m.seq; }
+  switch (m.type) {
+    case 'ready': $('status').textContent = 'session ' + m.sessionId; break;
+    case 'turn.state':
+      epoch = Math.max(epoch, m.epoch); $('state').textContent = m.state;
+      if (m.state === 'listening' && sources.length) stopPlayback();
+      break;
+    case 'transcript': line(m.itemId, m.role, m.text); break;
+    case 'text': line(m.responseId, 'agent', ((lines.get(m.responseId)?.textContent ?? 'Agent: ').slice(7)) + m.delta); break;
+    case 'audio.start': item = m.epoch > closedEpoch ? { id: m.itemId } : undefined; break;
+    case 'tool.call': runTool(m); break;
+    case 'interrupted': closedEpoch = Math.max(closedEpoch, m.epoch); stopPlayback(); note('interrupted'); break;
+    case 'error': note('error ' + m.code + ': ' + m.message); break;
+  }
+};
+
+$('form').onsubmit = (e) => {
+  e.preventDefault();
+  const text = $('text').value.trim();
+  if (!text) return;
+  stopPlayback(); line('local-' + seq, 'user', text); send({ type: 'text', text }); $('text').value = '';
+};
+$('stop').onclick = interrupt;
+
+// Microphone: AudioWorklet → 20 ms PCM16 frames → [kind=1][seq u32 BE][payload].
+const WORKLET = \`class Capture extends AudioWorkletProcessor {
+  constructor() { super(); this.buf = new Int16Array(\${FRAME}); this.n = 0; }
+  process(inputs) {
+    const ch = inputs[0][0];
+    if (ch) for (let i = 0; i < ch.length; i++) {
+      const s = Math.max(-1, Math.min(1, ch[i]));
+      this.buf[this.n++] = s < 0 ? s * 32768 : s * 32767;
+      if (this.n === \${FRAME}) { this.port.postMessage(this.buf.buffer.slice(0)); this.n = 0; }
+    }
+    return true;
+  }
+}
+registerProcessor('vrt-capture', Capture);\`;
+let mic;
+$('mic').onclick = async () => {
+  if (mic) { mic.getTracks().forEach((t) => t.stop()); mic = undefined; $('mic').textContent = 'Start mic'; return; }
+  const c = audio();
+  await c.resume();
+  mic = await navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, channelCount: 1 } });
+  await c.audioWorklet.addModule(URL.createObjectURL(new Blob([WORKLET], { type: 'text/javascript' })));
+  const node = new AudioWorkletNode(c, 'vrt-capture');
+  node.port.onmessage = ({ data }) => {
+    if (!mic || ws.readyState !== 1) return;
+    const frame = new Uint8Array(5 + data.byteLength);
+    frame[0] = 1; new DataView(frame.buffer).setUint32(1, audioSeq++ >>> 0); frame.set(new Uint8Array(data), 5);
+    ws.send(frame);
+  };
+  c.createMediaStreamSource(mic).connect(node);
+  $('mic').textContent = 'Stop mic';
+};
+</script>
+</body>
+</html>
+`;

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/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.1.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.1.0",
+    "@vrealtime/protocol": "0.1.0"
+  },
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  }
+}