@ggui-ai/protocol-reference-server 0.1.0-rc.1

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * `ggui-protocol-reference-server` — CLI entry.
+ *
+ * Usage:
+ *
+ *     npx @ggui-ai/protocol-reference-server --port 3100
+ *
+ * Prints `READY ws://host:port/ws` to stdout when bound. Runs
+ * indefinitely; Ctrl-C to stop.
+ *
+ * This is the manual smoke-check entry. For programmatic use (the
+ * conformance CI test, third-party integration tests), import
+ * `ReferenceServer` + `createReferenceConformanceHost` directly.
+ */
+import { ReferenceServer } from './server.js';
+function parseArgs(argv) {
+    let port = 3100;
+    let host = '127.0.0.1';
+    let help = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const flag = argv[i];
+        const next = () => {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`missing value for '${flag}'`);
+            }
+            i += 1;
+            return value;
+        };
+        switch (flag) {
+            case '--port':
+                port = Number.parseInt(next(), 10);
+                if (Number.isNaN(port))
+                    throw new Error('--port must be an integer');
+                break;
+            case '--host':
+                host = next();
+                break;
+            case '--help':
+            case '-h':
+                help = true;
+                break;
+            default:
+                throw new Error(`unknown flag '${flag}' — run with --help for usage`);
+        }
+    }
+    return { port, host, help };
+}
+const USAGE = `
+ggui-protocol-reference-server — minimal ggui protocol reference implementation
+
+Usage:
+  ggui-protocol-reference-server [--port <N>] [--host <H>]
+
+Options:
+  --port <N>        Port to bind. Default 3100.
+  --host <H>        Host interface. Default 127.0.0.1.
+  --help, -h        Show this help.
+
+Scope: narrow WS server implementing the ggui live-channel wire.
+Used by @ggui-ai/protocol-conformance to prove the protocol is vendor-neutral.
+NOT a production server — no auth, no persistence.
+`.trimStart();
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`error: ${String(err.message ?? err)}\n\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    const server = new ReferenceServer({ port: parsed.port, host: parsed.host });
+    await server.start();
+    process.stdout.write(`READY ws://${parsed.host}:${server.port}/ws\n`);
+    // Keep the process alive until SIGINT/SIGTERM.
+    await new Promise((done) => {
+        const shutdown = () => {
+            void server.stop().then(done);
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+    return 0;
+}
+function isEntryPoint() {
+    if (typeof import.meta.url !== 'string')
+        return false;
+    const scriptPath = process.argv[1];
+    if (typeof scriptPath !== 'string' || scriptPath.length === 0)
+        return false;
+    try {
+        return import.meta.url === new URL(`file://${scriptPath}`).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`fatal: ${String(err.message ?? err)}\n`);
+        process.exit(2);
+    });
+}
+export { main, parseArgs };

package/dist/conformance-host.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `ConformanceHost` adapter — wires the `@ggui-ai/protocol-conformance`
+ * setup/teardown directive dispatcher onto this package's
+ * `ReferenceServer` instance.
+ *
+ * Directives split into "implement" and "throw":
+ *
+ *   Implement:
+ *     - create-session            → `sessions.create()`
+ *     - register-tool             → `tools.register(name, handler)`
+ *     - register-actionspec       → `sessions.registerActionSpec()`
+ *     - register-streamspec       → `sessions.registerStreamSpec()`
+ *     - server-version-override   → `sessions.setVersionOverride()`
+ *     - emit-envelope             → `sessions.injectFrame()`
+ *     - close-session             → `sessions.close()`
+ *     - unregister-tool           → `tools.unregister()`
+ *
+ *   Throw (kit records SKIP, not FAIL):
+ *     - seed-channel              — unimplemented
+ *     - renderer-url-override     — unimplemented (browser-level)
+ *     - ui-initialize-response-override — unimplemented
+ *
+ * The "throw" set matches the conformance kit's `unmatchable-on-ws`
+ * skip expectations — browser-level fault injection that requires a
+ * richer host harness. Throwing surfaces "directive not implemented"
+ * with the error message as the skip reason.
+ */
+import type { ConformanceHost } from '@ggui-ai/protocol-conformance';
+import type { ReferenceServer } from './server.js';
+export interface CreateReferenceConformanceHostInput {
+    readonly serverInstance: ReferenceServer;
+}
+/**
+ * Build a `ConformanceHost` bound to the given `ReferenceServer`
+ * instance. Pass the return value to `runConformance({host})` to
+ * drive the kit against the server.
+ *
+ * The server MUST be `start()`-ed before the first dispatch — the
+ * kit calls `create-session` via `dispatchSetup` before any subscribe,
+ * so the session store must be reachable. The caller owns the
+ * server lifecycle (`start()` + `stop()`).
+ */
+export declare function createReferenceConformanceHost({ serverInstance, }: CreateReferenceConformanceHostInput): ConformanceHost;
+//# sourceMappingURL=conformance-host.d.ts.map

package/dist/conformance-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance-host.d.ts","sourceRoot":"","sources":["../src/conformance-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAEV,eAAe,EAMhB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,EAC7C,cAAc,GACf,EAAE,mCAAmC,GAAG,eAAe,CAwNvD"}

package/dist/conformance-host.js

@@ -0,0 +1,185 @@
+/**
+ * Build a `ConformanceHost` bound to the given `ReferenceServer`
+ * instance. Pass the return value to `runConformance({host})` to
+ * drive the kit against the server.
+ *
+ * The server MUST be `start()`-ed before the first dispatch — the
+ * kit calls `create-session` via `dispatchSetup` before any subscribe,
+ * so the session store must be reachable. The caller owns the
+ * server lifecycle (`start()` + `stop()`).
+ */
+export function createReferenceConformanceHost({ serverInstance, }) {
+    return {
+        async dispatchSetup(step) {
+            // Discriminant-narrow via explicit casts — the extensibly-closed
+            // `HostUnknownSetupStep` arm (`kind: string & {}`) widens the
+            // discriminant and blocks literal-narrowing on the union.
+            if (step.kind === 'create-session') {
+                const s = step;
+                serverInstance.sessions.create(s.sessionId, s.appId ?? 'conformance');
+                return;
+            }
+            if (step.kind === 'register-tool') {
+                // Fixture JSON authors the field as `toolName`; the kit's
+                // runtime narrowing (`run-conformance.ts::narrowSetupStep`)
+                // only renames `type → kind` and passes other fields verbatim,
+                // so the runtime object carries `toolName` not `name`.
+                // Tolerate both for forward-compat with a kit fix.
+                const raw = step;
+                const toolName = raw.toolName ?? raw.name;
+                if (typeof toolName !== 'string' || toolName.length === 0) {
+                    throw new Error(`register-tool directive missing toolName/name: ${JSON.stringify(step)}`);
+                }
+                serverInstance.tools.register(toolName, raw.handler);
+                return;
+            }
+            if (step.kind === 'register-actionspec') {
+                const s = step;
+                // register-actionspec doesn't carry a sessionId in the
+                // directive shape — it's scoped to the most-recently-created
+                // session, matching the fixture-authoring convention that
+                // create-session → register-tool → register-actionspec all
+                // land in order on the same session.
+                const lastSession = serverInstance.sessions.lastCreatedSessionId();
+                if (lastSession === undefined) {
+                    throw new Error('reference-server: register-actionspec invoked before create-session — no session scope to bind to');
+                }
+                serverInstance.sessions.registerActionSpec(lastSession, {
+                    name: s.name,
+                    tool: s.tool,
+                });
+                return;
+            }
+            if (step.kind === 'register-streamspec') {
+                // register-streamspec is the streamSpec analogue of register-
+                // actionspec — binds a stream channel to a refresh tool. The
+                // kit does not export a `RegisterStreamSpecSetup` type today
+                // (the directive is reference-server-specific scaffolding for
+                // Slice I refresh-stream support); the runtime shape is
+                // narrowed locally, matching the same convention as the
+                // pre-existing `register-tool` branch above. Same most-
+                // recently-created session scoping as register-actionspec.
+                const raw = step;
+                if (typeof raw.channel !== 'string' || raw.channel.length === 0) {
+                    throw new Error(`register-streamspec directive missing channel: ${JSON.stringify(step)}`);
+                }
+                if (typeof raw.tool !== 'string' || raw.tool.length === 0) {
+                    throw new Error(`register-streamspec directive missing tool: ${JSON.stringify(step)}`);
+                }
+                const lastSession = serverInstance.sessions.lastCreatedSessionId();
+                if (lastSession === undefined) {
+                    throw new Error('reference-server: register-streamspec invoked before create-session — no session scope to bind to');
+                }
+                serverInstance.sessions.registerStreamSpec(lastSession, {
+                    channel: raw.channel,
+                    tool: raw.tool,
+                });
+                return;
+            }
+            if (step.kind === 'emit-envelope') {
+                // The directive carries `channel` + `payload` but no
+                // sessionId — it's scoped to the most-recently-created
+                // session, matching the same fixture-authoring convention as
+                // register-actionspec / register-streamspec / server-version-
+                // override (the kit's `narrowSetupStep` is a flat `type → kind`
+                // rename pass-through, so any sessionId on the directive JSON
+                // would survive, but the canonical EmitEnvelopeSetup shape
+                // doesn't declare one).
+                //
+                // Wire-format wrapping: the directive's `payload: unknown` is
+                // the envelope body; the host wraps it in the SPEC §12.2
+                // `{type:'stream', payload:{channel, value}}` shape (matching
+                // the existing reference-server stream emissions in
+                // action-router.ts) before fan-out. Per the kit type docstring,
+                // "Host is responsible for wrapping in the wire format
+                // (sequence stamp, timestamp, etc.)" — the kit does NOT
+                // expect the directive to carry a fully-formed wire frame.
+                const s = step;
+                if (typeof s.channel !== 'string' || s.channel.length === 0) {
+                    throw new Error(`emit-envelope directive missing channel: ${JSON.stringify(step)}`);
+                }
+                const lastSession = serverInstance.sessions.lastCreatedSessionId();
+                if (lastSession === undefined) {
+                    throw new Error('reference-server: emit-envelope invoked before create-session — no session scope to bind to');
+                }
+                const fanned = serverInstance.sessions.injectFrame(lastSession, {
+                    type: 'stream',
+                    payload: {
+                        channel: s.channel,
+                        value: s.payload,
+                    },
+                });
+                if (!fanned) {
+                    // No subscribers attached — the directive's emission is
+                    // unobservable. Surface for fixture-authoring debuggability
+                    // (the canonical sequence is create-session → subscribe →
+                    // emit-envelope; fixtures that swap order silently lose the
+                    // injection). Not a throw — the directive itself succeeded;
+                    // the unobservability is a fixture concern.
+                    // eslint-disable-next-line no-console
+                    console.warn(`[@ggui-ai/protocol-reference-server] emit-envelope on session '${lastSession}' channel '${s.channel}' had no subscribers — frame dropped`);
+                }
+                return;
+            }
+            if (step.kind === 'renderer-url-override') {
+                throw new Error('reference server does not implement renderer-url-override — browser-level fault injection, out of scope');
+            }
+            if (step.kind === 'ui-initialize-response-override') {
+                throw new Error('reference server does not implement ui-initialize-response-override — MCP Apps host concern, out of scope');
+            }
+            if (step.kind === 'server-version-override') {
+                // Fixture JSON authors `advertiseVersion` (matches the
+                // semantic — "advertise this version on the wire"); the kit's
+                // exported `ServerVersionOverrideSetup` interface uses
+                // `version`. Tolerate both for forward-compat with the kit's
+                // own type, mirroring the same name-tolerance pattern in
+                // register-tool above. The runtime `narrowSetupStep` only
+                // renames `type → kind` and passes other fields verbatim, so
+                // whichever the fixture authors arrives unchanged.
+                const raw = step;
+                const advertise = raw.advertiseVersion ?? raw.version;
+                if (typeof advertise !== 'string' || advertise.length === 0) {
+                    throw new Error(`server-version-override directive missing advertiseVersion/version: ${JSON.stringify(step)}`);
+                }
+                // Same most-recently-created session scope as register-
+                // actionspec / register-streamspec — the fixture authoring
+                // convention is `create-session` immediately precedes this
+                // directive, and the kit's narrowSetupStep doesn't surface a
+                // sessionId on the directive object even when the fixture
+                // JSON includes one (only `type → kind` is renamed; the rest
+                // is a flat passthrough, so a `sessionId` field WOULD survive
+                // — but the canonical ServerVersionOverrideSetup type doesn't
+                // declare one, so fixtures may omit it. Falling back to
+                // `lastCreatedSessionId()` keeps the host robust to either.
+                const lastSession = serverInstance.sessions.lastCreatedSessionId();
+                if (lastSession === undefined) {
+                    throw new Error('reference-server: server-version-override invoked before create-session — no session scope to bind to');
+                }
+                serverInstance.sessions.setVersionOverride(lastSession, advertise);
+                return;
+            }
+            // Unknown kind — extensibly-closed. Throw so the kit records
+            // SKIP with an honest reason.
+            const unknownKind = step.kind ?? 'unknown';
+            throw new Error(`reference server does not implement setup kind '${String(unknownKind)}'`);
+        },
+        async dispatchTeardown(step) {
+            if (step.kind === 'close-session') {
+                const s = step;
+                serverInstance.sessions.close(s.sessionId);
+                return;
+            }
+            if (step.kind === 'unregister-tool') {
+                // Same toolName/name tolerance as register-tool.
+                const raw = step;
+                const toolName = raw.toolName ?? raw.name;
+                if (typeof toolName === 'string' && toolName.length > 0) {
+                    serverInstance.tools.unregister(toolName);
+                }
+                return;
+            }
+            const unknownKind = step.kind ?? 'unknown';
+            throw new Error(`reference server does not implement teardown kind '${String(unknownKind)}'`);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@ggui-ai/protocol-reference-server` — minimal reference
+ * implementation of the ggui protocol.
+ *
+ * **Role**: empirical proof of the protocol's vendor-neutral
+ * separation. If an independent, from-scratch implementation passes
+ * `@ggui-ai/protocol-conformance`, the protocol's vendor-neutrality
+ * claim is grounded — not an aspiration.
+ *
+ * **Non-goals**:
+ *   - Not a production server.
+ *   - Not intended for agent use.
+ *   - Deliberately does NOT depend on `@ggui-ai/mcp-server*` — the
+ *     whole point of this package is to prove those aren't needed.
+ */
+export declare const REFERENCE_SERVER_VERSION = "0.1.0";
+export { ReferenceServer } from './server.js';
+export type { ReferenceServerOptions } from './server.js';
+export { createReferenceConformanceHost, type CreateReferenceConformanceHostInput, } from './conformance-host.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAahD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,8BAA8B,EAC9B,KAAK,mCAAmC,GACzC,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@ggui-ai/protocol-reference-server` — minimal reference
+ * implementation of the ggui protocol.
+ *
+ * **Role**: empirical proof of the protocol's vendor-neutral
+ * separation. If an independent, from-scratch implementation passes
+ * `@ggui-ai/protocol-conformance`, the protocol's vendor-neutrality
+ * claim is grounded — not an aspiration.
+ *
+ * **Non-goals**:
+ *   - Not a production server.
+ *   - Not intended for agent use.
+ *   - Deliberately does NOT depend on `@ggui-ai/mcp-server*` — the
+ *     whole point of this package is to prove those aren't needed.
+ */
+export const REFERENCE_SERVER_VERSION = '0.1.0';
+// Public surface for embedding the reference server in an external
+// runner — used to drive the `@ggui-ai/protocol-conformance` kit
+// through the reference WS server from inside a browser-based test
+// harness.
+//
+// Embedding contract:
+//   - Caller owns lifecycle: `new ReferenceServer({port: 0}); await
+//     server.start(); … await server.stop()`.
+//   - `createReferenceConformanceHost({serverInstance})` returns the
+//     `ConformanceHost` to pass into `runConformance({host})`.
+//   - Throws on unimplemented directives — kit maps them to SKIP.
+export { ReferenceServer } from './server.js';
+export { createReferenceConformanceHost, } from './conformance-host.js';

package/dist/server.d.ts

@@ -0,0 +1,59 @@
+import { SessionStore } from './session.js';
+import { ToolRegistry } from './tool-registry.js';
+export interface ReferenceServerOptions {
+    /** Port to bind. `0` = ephemeral — use {@link ReferenceServer.port}
+     *  to read the resolved port after start. */
+    readonly port: number;
+    /** Host interface. Default `127.0.0.1`. */
+    readonly host?: string;
+    /**
+     * If `true` (default), reject subscribes whose `supportedVersions`
+     * does not include `PROTOCOL_SCHEMA_VERSION` by emitting
+     * `UPGRADE_REQUIRED` AND closing the underlying WebSocket. This is
+     * the default first-party posture. Set to `false` for an 'advisory'
+     * posture — the error frame is emitted but the connection stays
+     * open (used by tests that need the mismatch emission observable
+     * without closing the socket).
+     */
+    readonly strictVersionPolicy?: boolean;
+    /**
+     * Override the server-advertised protocol schema version. Defaults to
+     * `PROTOCOL_SCHEMA_VERSION` (current canonical). Used by the
+     * `server-version-override` conformance directive — a Path-A test
+     * boots a sidecar `ReferenceServer` with a deliberately mismatched
+     * version so the kit's `version-mismatch` fixture can drive the
+     * UPGRADE_REQUIRED emission entirely over WS.
+     *
+     * Discipline: this field is for conformance-test fault injection ONLY.
+     * Production-use of the reference server (none planned — see
+     * package non-goals) MUST default to canonical.
+     */
+    readonly versionOverride?: string;
+}
+export declare class ReferenceServer {
+    readonly sessions: SessionStore;
+    readonly tools: ToolRegistry;
+    private readonly options;
+    private http;
+    private wss;
+    private boundPort;
+    constructor(options: ReferenceServerOptions);
+    /**
+     * Protocol schema version the server advertises in subscribe ack
+     * frames + UPGRADE_REQUIRED error frames. Defaults to
+     * `PROTOCOL_SCHEMA_VERSION`; overridable via
+     * {@link ReferenceServerOptions.versionOverride} for conformance
+     * fault injection.
+     */
+    get advertisedVersion(): string;
+    /** Resolved port (valid after `start()` resolves). */
+    get port(): number;
+    /** Base URL for the kit's `runConformance({serverUrl})`. */
+    get baseUrl(): string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleConnection;
+    private handleMessage;
+    private handleSubscribe;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,YAAY,EAAmB,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC;iDAC6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,QAAQ,eAAsB;IACvC,QAAQ,CAAC,KAAK,eAAsB;IAEpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,EAAE,sBAAsB;IAS3C;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,sDAAsD;IACtD,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED,4DAA4D;IAC5D,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,OAAO,CAAC,gBAAgB;YAoCV,aAAa;IAuC3B,OAAO,CAAC,eAAe;CAmExB"}