@smooai/smooth-operator 0.1.0

package/dist/validate.js

@@ -0,0 +1,133 @@
+/**
+ * Runtime validation against the spec JSON Schemas, using ajv.
+ *
+ * The spec ships draft 2020-12 schemas with internal `$defs` (no cross-file
+ * `$ref`s). We register every schema under its `$id` so ajv can resolve any
+ * `#/$defs/...` pointer within it, then expose:
+ *
+ *  - `validateAt(schemaRef, instance)` — validate against a spec-relative ref like
+ *    `events/stream-chunk.schema.json` or `actions/send-message.schema.json#/$defs/Request`
+ *    (the exact form used by `conformance/fixtures.json`).
+ *  - `validateEvent` / `validateAction` — convenience validators that pick the
+ *    right schema from a frame's discriminator and validate it.
+ *
+ * Schemas are loaded from the spec directory on disk. This module is Node-only
+ * (it reads files); it is intended for build/test/server use, not the browser
+ * bundle. The wire client (`client.ts`) does not import it — validation is opt-in.
+ */
+import _Ajv2020, { Ajv2020 as AjvClass } from 'ajv/dist/2020.js';
+import _addFormats from 'ajv-formats';
+const Ajv2020 = (_Ajv2020.default ?? _Ajv2020);
+const addFormats = (_addFormats.default ?? _addFormats);
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Default location of the spec dir relative to this source file (../../spec). */
+export const DEFAULT_SPEC_DIR = join(__dirname, '..', '..', 'spec');
+/** Maps an event `type` to its schema file (spec-relative). */
+const EVENT_SCHEMA_FILE = {
+    immediate_response: 'events/immediate-response.schema.json',
+    eventual_response: 'events/eventual-response.schema.json',
+    stream_chunk: 'events/stream-chunk.schema.json',
+    stream_token: 'events/stream-token.schema.json',
+    keepalive: 'events/keepalive.schema.json',
+    write_confirmation_required: 'events/write-confirmation-required.schema.json',
+    otp_verification_required: 'events/otp-verification-required.schema.json',
+    otp_sent: 'events/otp-sent.schema.json',
+    otp_verified: 'events/otp-verified.schema.json',
+    otp_invalid: 'events/otp-invalid.schema.json',
+    error: 'events/error.schema.json',
+    pong: 'events/pong.schema.json',
+};
+/** Maps an action `action` to its request schema ref (spec-relative). */
+const ACTION_SCHEMA_REF = {
+    create_conversation_session: 'actions/create-conversation-session.schema.json#/$defs/Request',
+    send_message: 'actions/send-message.schema.json#/$defs/Request',
+    get_session: 'actions/get-session.schema.json#/$defs/Request',
+    get_conversation_messages: 'actions/get-messages.schema.json#/$defs/Request',
+    confirm_tool_action: 'actions/confirm-tool-action.schema.json#/$defs/Request',
+    verify_otp: 'actions/verify-otp.schema.json#/$defs/Request',
+    ping: 'actions/ping.schema.json#/$defs/Request',
+};
+export class ProtocolValidator {
+    ajv;
+    /** spec-relative file path → the schema's `$id` (used to build `$ref`-able URIs). */
+    fileToId = new Map();
+    cache = new Map();
+    constructor(ajv) {
+        this.ajv = ajv;
+    }
+    /** Load every `*.schema.json` under `specDir` and register it with ajv. */
+    static async load(specDir = DEFAULT_SPEC_DIR) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        addFormats(ajv);
+        const validator = new ProtocolValidator(ajv);
+        for (const sub of ['', 'actions', 'events', 'domain']) {
+            const dir = sub ? join(specDir, sub) : specDir;
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const e of entries) {
+                if (!e.isFile() || !e.name.endsWith('.schema.json'))
+                    continue;
+                const rel = sub ? `${sub}/${e.name}` : e.name;
+                const schema = JSON.parse(await readFile(join(dir, e.name), 'utf8'));
+                const id = schema.$id ?? `urn:smooth-agent:${rel}`;
+                // ajv throws if the same $id is added twice; guard against it.
+                if (!ajv.getSchema(id))
+                    ajv.addSchema(schema, id);
+                validator.fileToId.set(rel, id);
+            }
+        }
+        return validator;
+    }
+    /**
+     * Validate `instance` against a spec-relative schema ref. The ref is the form
+     * used in `fixtures.json`: a file path, optionally with a JSON-pointer fragment
+     * into the schema's `$defs` (e.g. `actions/ping.schema.json#/$defs/Request`).
+     */
+    validateAt(schemaRef, instance) {
+        const validate = this.compile(schemaRef);
+        const valid = validate(instance);
+        return { valid, errors: valid ? [] : (validate.errors ?? []) };
+    }
+    /** Validate a server event frame by selecting the schema from its `type`. */
+    validateEvent(frame) {
+        const file = EVENT_SCHEMA_FILE[frame.type];
+        if (!file) {
+            return { valid: false, errors: [syntheticError(`Unknown event type: ${String(frame.type)}`)] };
+        }
+        return this.validateAt(file, frame);
+    }
+    /** Validate a client action frame by selecting the schema from its `action`. */
+    validateAction(frame) {
+        const ref = ACTION_SCHEMA_REF[frame.action];
+        if (!ref) {
+            return { valid: false, errors: [syntheticError(`Unknown action: ${String(frame.action)}`)] };
+        }
+        return this.validateAt(ref, frame);
+    }
+    compile(schemaRef) {
+        const cached = this.cache.get(schemaRef);
+        if (cached)
+            return cached;
+        const [file, pointer] = schemaRef.split('#');
+        const id = this.fileToId.get(file);
+        if (!id)
+            throw new Error(`No schema registered for "${file}" (ref "${schemaRef}")`);
+        // Resolve via the registered $id + optional JSON-pointer fragment.
+        const uri = pointer ? `${id}#${pointer}` : id;
+        const validate = this.ajv.getSchema(uri);
+        if (!validate)
+            throw new Error(`ajv could not resolve schema ref "${schemaRef}" (uri "${uri}")`);
+        this.cache.set(schemaRef, validate);
+        return validate;
+    }
+}
+function syntheticError(message) {
+    return { instancePath: '', schemaPath: '', keyword: 'protocol', params: {}, message };
+}
+/** Render ajv errors into a single human-readable string. */
+export function formatErrors(errors) {
+    return errors.map((e) => `${e.instancePath || '<root>'} ${e.message ?? ''}`.trim()).join('; ');
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@smooai/smooth-operator",
+  "version": "0.1.0",
+  "description": "TypeScript protocol types and native WebSocket client for the smooth-operator protocol. Generated from the language-neutral JSON Schemas in spec/.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "import": "./dist/validate.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SmooAI/smooth-operator.git",
+    "directory": "typescript"
+  },
+  "homepage": "https://github.com/SmooAI/smooth-operator/tree/main/typescript",
+  "keywords": [
+    "smooth-operator",
+    "websocket",
+    "protocol",
+    "client",
+    "ai",
+    "agent",
+    "streaming"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@apidevtools/json-schema-ref-parser": "^11.7.3",
+    "@types/node": "^25.9.2",
+    "json-schema-to-typescript": "^15.0.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "generate": "tsx scripts/generate.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts"
+  }
+}

package/src/client.ts

@@ -0,0 +1,435 @@
+/**
+ * SmoothAgentClient — a minimal, idiomatic, transport-agnostic client for the
+ * smooth-operator WebSocket protocol.
+ *
+ * Design goals
+ * ------------
+ *  - **Transport-agnostic.** The client never touches a real socket directly; it
+ *    talks to an injectable {@link Transport}. The default ({@link WebSocketTransport})
+ *    uses the global `WebSocket`, but tests inject a mock and Node can inject `ws`.
+ *  - **Request/response correlation by `requestId`.** Every action gets a generated
+ *    `requestId`; the client routes incoming events back to the originating call.
+ *  - **Streaming as an async iterator.** `sendMessage` returns a {@link MessageTurn}
+ *    that is both awaitable (resolves with the terminal `eventual_response`) and
+ *    async-iterable (yields each `stream_token` / `stream_chunk` / HITL event in
+ *    order). This models the `stream_token`/`stream_chunk` → `eventual_response`
+ *    flow without forcing a callback style on the caller.
+ *  - **No live server required.** Correctness is fully unit-testable with a mock
+ *    transport (see `test/client.test.ts`).
+ */
+import {
+    WebSocketTransport,
+    type Transport,
+    type WebSocketFactory,
+} from './transport.js';
+import type {
+    ClientAction,
+    CreateConversationSessionRequest,
+    CreateConversationSessionResponse,
+    EventualResponse,
+    GetMessagesRequest,
+    GetMessagesResponse,
+    GetSessionRequest,
+    GetSessionResponse,
+    SendMessageRequest,
+    ServerEvent,
+} from './types.js';
+import { isServerEvent } from './types.js';
+
+export interface SmoothAgentClientOptions {
+    /** WebSocket URL, e.g. `wss://realtime.prod.smooth-agent.dev`. */
+    url: string;
+    /** Inject a transport (for tests / non-browser runtimes). Defaults to a WebSocket transport. */
+    transport?: Transport;
+    /** Inject a WebSocket factory used by the default transport (e.g. the `ws` package on Node). */
+    webSocketFactory?: WebSocketFactory;
+    /** Generate request IDs. Defaults to `crypto.randomUUID()` with a `req-` prefix. */
+    generateRequestId?: () => string;
+    /** Per-request timeout in ms for non-streaming actions. Default 30000. */
+    requestTimeout?: number;
+    /**
+     * Overall timeout in ms for a streaming `sendMessage` turn: if the server accepts
+     * the message but never emits a terminal `eventual_response` / `error`, the turn
+     * rejects with a {@link TurnTimeoutError} instead of hanging forever. Default
+     * 120000. Set to 0 (or a negative number) to disable.
+     */
+    turnTimeout?: number;
+}
+
+/** Events that terminate a streaming turn (success or error). */
+const TURN_TERMINAL = new Set(['eventual_response', 'error']);
+
+/** A timeout that yields no terminal event. */
+class RequestTimeoutError extends Error {
+    constructor(requestId: string, ms: number) {
+        super(`Request ${requestId} timed out after ${ms}ms`);
+        this.name = 'RequestTimeoutError';
+    }
+}
+
+/**
+ * A streaming turn that received no terminal `eventual_response` / `error` within the
+ * configured {@link SmoothAgentClientOptions.turnTimeout}. The turn rejects with this
+ * and its async iteration throws it, so a stuck server can never hang the caller.
+ */
+export class TurnTimeoutError extends Error {
+    readonly requestId: string;
+    constructor(requestId: string, ms: number) {
+        super(`Turn ${requestId} timed out after ${ms}ms without a terminal response`);
+        this.name = 'TurnTimeoutError';
+        this.requestId = requestId;
+    }
+}
+
+/** A protocol-level error event surfaced as a throwable. */
+export class ProtocolError extends Error {
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(code: string, message: string, requestId?: string) {
+        super(message);
+        this.name = 'ProtocolError';
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+
+/** Internal record for an in-flight single-response request. */
+interface PendingRequest {
+    resolve: (event: ServerEvent) => void;
+    reject: (err: unknown) => void;
+    timer: ReturnType<typeof setTimeout> | undefined;
+}
+
+/**
+ * A streaming message turn. Await it for the terminal {@link EventualResponse},
+ * or async-iterate it to receive every intermediate event in arrival order.
+ *
+ * ```ts
+ * const turn = client.sendMessage({ sessionId, message: 'hi' });
+ * for await (const ev of turn) {
+ *   if (ev.type === 'stream_token') process.stdout.write(ev.token ?? '');
+ * }
+ * const final = await turn; // EventualResponse
+ * ```
+ */
+export class MessageTurn implements AsyncIterable<ServerEvent>, PromiseLike<EventualResponse> {
+    /** The requestId this turn is correlated on. */
+    readonly requestId: string;
+
+    private readonly queue: ServerEvent[] = [];
+    private waiter: {
+        resolve: (result: IteratorResult<ServerEvent>) => void;
+        reject: (err: unknown) => void;
+    } | null = null;
+    private done = false;
+    private finalEvent: EventualResponse | null = null;
+    private error: unknown = null;
+    private readonly settled: Promise<EventualResponse>;
+    private settle!: (value: EventualResponse) => void;
+    private fail!: (err: unknown) => void;
+    private readonly onClose: () => void;
+    private timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+    constructor(requestId: string, onClose: () => void, turnTimeout = 0) {
+        this.requestId = requestId;
+        this.onClose = onClose;
+        this.settled = new Promise<EventualResponse>((resolve, reject) => {
+            this.settle = resolve;
+            this.fail = reject;
+        });
+        // Avoid unhandled-rejection noise if the caller only iterates and never awaits.
+        this.settled.catch(() => {});
+        // Bound the turn: a server that accepts the message but never emits a terminal
+        // event must not hang the caller forever.
+        if (turnTimeout > 0) {
+            this.timeoutTimer = setTimeout(() => {
+                this.finish(null, new TurnTimeoutError(this.requestId, turnTimeout));
+            }, turnTimeout);
+        }
+    }
+
+    /** Feed an event into the turn (called by the client's dispatcher). */
+    push(event: ServerEvent): void {
+        if (this.done) return;
+
+        if (event.type === 'error') {
+            const code = event.data?.error?.code ?? 'INTERNAL_ERROR';
+            const message = event.data?.error?.message ?? 'Unknown protocol error';
+            this.deliver(event);
+            this.finish(null, new ProtocolError(code, message, this.requestId));
+            return;
+        }
+
+        this.deliver(event);
+
+        if (event.type === 'eventual_response') {
+            this.finish(event, null);
+        }
+    }
+
+    /** Force-close the turn (e.g. on disconnect) with an error. */
+    abort(err: unknown): void {
+        if (this.done) return;
+        this.finish(null, err);
+    }
+
+    private deliver(event: ServerEvent): void {
+        if (this.waiter) {
+            const w = this.waiter;
+            this.waiter = null;
+            w.resolve({ value: event, done: false });
+        } else {
+            this.queue.push(event);
+        }
+    }
+
+    private finish(final: EventualResponse | null, err: unknown): void {
+        if (this.done) return;
+        this.done = true;
+        this.finalEvent = final;
+        this.error = err;
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = undefined;
+        }
+        this.onClose();
+
+        if (err) this.fail(err);
+        else if (final) this.settle(final);
+
+        // Release any pending iterator waiter now that the stream has ended. On error
+        // the parked next() must *reject* (mirroring the queued-error path in next())
+        // so a pure `for await` consumer sees the terminal error thrown instead of a
+        // silent, indistinguishable `{ done: true }`.
+        if (this.waiter) {
+            const w = this.waiter;
+            this.waiter = null;
+            if (err) {
+                w.reject(err);
+            } else {
+                w.resolve({ value: undefined as never, done: true });
+            }
+        }
+    }
+
+    [Symbol.asyncIterator](): AsyncIterator<ServerEvent> {
+        return {
+            next: (): Promise<IteratorResult<ServerEvent>> => {
+                if (this.queue.length > 0) {
+                    return Promise.resolve({ value: this.queue.shift()!, done: false });
+                }
+                if (this.done) {
+                    if (this.error) return Promise.reject(this.error);
+                    return Promise.resolve({ value: undefined as never, done: true });
+                }
+                return new Promise<IteratorResult<ServerEvent>>((resolve, reject) => {
+                    this.waiter = { resolve, reject };
+                });
+            },
+        };
+    }
+
+    // PromiseLike — `await turn` resolves with the EventualResponse.
+    then<TResult1 = EventualResponse, TResult2 = never>(
+        onfulfilled?: ((value: EventualResponse) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+    ): PromiseLike<TResult1 | TResult2> {
+        return this.settled.then(onfulfilled, onrejected);
+    }
+}
+
+export class SmoothAgentClient {
+    private readonly transport: Transport;
+    private readonly generateRequestId: () => string;
+    private readonly requestTimeout: number;
+    private readonly turnTimeout: number;
+
+    /** requestId → single-response waiter (create_session, get_session, ping, …). */
+    private readonly pending = new Map<string, PendingRequest>();
+    /** requestId → active streaming turn (send_message, and HITL resumes). */
+    private readonly turns = new Map<string, MessageTurn>();
+    /** Unsolicited-event listeners (keepalive, server-push). */
+    private readonly listeners = new Set<(event: ServerEvent) => void>();
+
+    private unsubscribe: Array<() => void> = [];
+
+    constructor(options: SmoothAgentClientOptions) {
+        this.transport = options.transport ?? new WebSocketTransport(options.url, options.webSocketFactory);
+        this.requestTimeout = options.requestTimeout ?? 30_000;
+        this.turnTimeout = options.turnTimeout ?? 120_000;
+        this.generateRequestId =
+            options.generateRequestId ??
+            (() => `req-${(globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2))}`);
+
+        this.unsubscribe.push(this.transport.onMessage((data) => this.handleFrame(data)));
+        this.unsubscribe.push(
+            this.transport.onClose(() => this.failAll(new Error('Transport closed'))),
+        );
+    }
+
+    /** Open the underlying transport. */
+    async connect(): Promise<void> {
+        await this.transport.connect();
+    }
+
+    /** Close the transport and reject all in-flight work. */
+    disconnect(reason = 'client disconnect'): void {
+        this.failAll(new Error(reason));
+        for (const u of this.unsubscribe) u();
+        this.unsubscribe = [];
+        this.transport.close(1000, reason);
+    }
+
+    /** Subscribe to unsolicited / uncorrelated server events (e.g. keepalive). */
+    onEvent(listener: (event: ServerEvent) => void): () => void {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    // ───────────────────────────── Actions ─────────────────────────────────
+
+    /** Start a new conversation session. Resolves with the session descriptor. */
+    async createConversationSession(
+        req: Omit<CreateConversationSessionRequest, 'action' | 'requestId'>,
+    ): Promise<CreateConversationSessionResponse> {
+        const event = await this.request({ action: 'create_conversation_session', ...req });
+        return extractImmediateData<CreateConversationSessionResponse>(event);
+    }
+
+    /** Fetch a session snapshot by ID. */
+    async getSession(req: Omit<GetSessionRequest, 'action' | 'requestId'>): Promise<GetSessionResponse> {
+        const event = await this.request({ action: 'get_session', ...req });
+        return extractImmediateData<GetSessionResponse>(event);
+    }
+
+    /** Fetch a page of conversation messages. */
+    async getMessages(req: Omit<GetMessagesRequest, 'action' | 'requestId'>): Promise<GetMessagesResponse> {
+        const event = await this.request({ action: 'get_conversation_messages', ...req });
+        return extractImmediateData<GetMessagesResponse>(event);
+    }
+
+    /** Keepalive ping. Resolves with the server timestamp from the `pong` event. */
+    async ping(): Promise<number> {
+        const event = await this.request({ action: 'ping' });
+        if (event.type === 'pong') return event.timestamp ?? event.data?.timestamp ?? Date.now();
+        return Date.now();
+    }
+
+    /**
+     * Submit a user message and return a {@link MessageTurn}: await it for the
+     * terminal `eventual_response`, or async-iterate it for the streaming events.
+     */
+    sendMessage(req: Omit<SendMessageRequest, 'action' | 'requestId'>): MessageTurn {
+        const requestId = this.generateRequestId();
+        const turn = new MessageTurn(requestId, () => this.turns.delete(requestId), this.turnTimeout);
+        this.turns.set(requestId, turn);
+        try {
+            this.transport.send(JSON.stringify({ action: 'send_message', requestId, ...req }));
+        } catch (err) {
+            this.turns.delete(requestId);
+            turn.abort(err);
+        }
+        return turn;
+    }
+
+    /**
+     * Approve or reject a pending tool write, resuming the paused turn identified
+     * by `requestId`. The resumed streaming events flow back into the original
+     * {@link MessageTurn} for that `requestId`.
+     */
+    confirmToolAction(req: { sessionId: string; requestId: string; approved: boolean }): void {
+        this.transport.send(JSON.stringify({ action: 'confirm_tool_action', ...req }));
+    }
+
+    /**
+     * Submit an OTP code, resuming the paused turn identified by `requestId`.
+     * The resumed streaming events flow back into the original {@link MessageTurn}.
+     */
+    verifyOtp(req: { sessionId: string; requestId: string; code: string }): void {
+        this.transport.send(JSON.stringify({ action: 'verify_otp', ...req }));
+    }
+
+    // ─────────────────────────── Internals ─────────────────────────────────
+
+    /** Send an action that expects a single correlated response event. */
+    private request(action: Omit<ClientAction, 'requestId'> & { requestId?: string }): Promise<ServerEvent> {
+        const requestId = action.requestId ?? this.generateRequestId();
+        const frame = { ...action, requestId } as ClientAction;
+
+        return new Promise<ServerEvent>((resolve, reject) => {
+            const timer =
+                this.requestTimeout > 0
+                    ? setTimeout(() => {
+                          this.pending.delete(requestId);
+                          reject(new RequestTimeoutError(requestId, this.requestTimeout));
+                      }, this.requestTimeout)
+                    : undefined;
+
+            this.pending.set(requestId, { resolve, reject, timer });
+            try {
+                this.transport.send(JSON.stringify(frame));
+            } catch (err) {
+                if (timer) clearTimeout(timer);
+                this.pending.delete(requestId);
+                reject(err);
+            }
+        });
+    }
+
+    /** Parse and route an incoming frame to the right consumer. */
+    private handleFrame(data: string): void {
+        let frame: unknown;
+        try {
+            frame = JSON.parse(data);
+        } catch {
+            return; // ignore malformed frames
+        }
+        if (!isServerEvent(frame)) return;
+        const event = frame;
+        const requestId = event.requestId;
+
+        // 1. Streaming turn? Route every related event into it.
+        if (requestId && this.turns.has(requestId)) {
+            this.turns.get(requestId)!.push(event);
+            return;
+        }
+
+        // 2. Single-response request awaiting resolution?
+        if (requestId && this.pending.has(requestId)) {
+            const pending = this.pending.get(requestId)!;
+            this.pending.delete(requestId);
+            if (pending.timer) clearTimeout(pending.timer);
+
+            if (event.type === 'error') {
+                const code = event.data?.error?.code ?? 'INTERNAL_ERROR';
+                const message = event.data?.error?.message ?? 'Unknown protocol error';
+                pending.reject(new ProtocolError(code, message, requestId));
+            } else {
+                pending.resolve(event);
+            }
+            return;
+        }
+
+        // 3. Unsolicited / uncorrelated event (keepalive, server push).
+        for (const l of this.listeners) l(event);
+    }
+
+    private failAll(err: unknown): void {
+        for (const [, p] of this.pending) {
+            if (p.timer) clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+        for (const [, turn] of this.turns) turn.abort(err);
+        this.turns.clear();
+    }
+}
+
+/** Pull the typed `data` payload out of an `immediate_response` event. */
+function extractImmediateData<T>(event: ServerEvent): T {
+    if (event.type === 'immediate_response') return event.data as T;
+    // Some servers may answer a non-streaming action with the payload elsewhere;
+    // fall back to `data` if present.
+    if ('data' in event && event.data && typeof event.data === 'object') return event.data as T;
+    throw new ProtocolError('UNEXPECTED_EVENT', `Expected immediate_response, got "${event.type}"`, event.requestId);
+}