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

package/dist/server.js

@@ -0,0 +1,224 @@
+/**
+ * `ReferenceServer` — the minimal WS live-channel server this package
+ * exports. Honest scope: SPEC §12.2 wire, version handshake,
+ * wired-action dispatch. That's it.
+ *
+ * No auth (accepts any bearer). No persistence. No bundle loading.
+ * The whole point is to be narrow enough that the vendor-neutral
+ * separation claim (Protocol #6) is empirically grounded — if this
+ * server passes `@ggui-ai/protocol-conformance`, the protocol has
+ * no implicit `@ggui-ai/mcp-server` coupling.
+ */
+import { createServer } from 'node:http';
+import { PROTOCOL_SCHEMA_VERSION } from '@ggui-ai/protocol';
+import { WebSocketServer } from 'ws';
+import { dispatchAction, isActionFrame } from './action-router.js';
+import { SessionStore } from './session.js';
+import { ToolRegistry } from './tool-registry.js';
+export class ReferenceServer {
+    sessions = new SessionStore();
+    tools = new ToolRegistry();
+    options;
+    http = null;
+    wss = null;
+    boundPort = null;
+    constructor(options) {
+        this.options = {
+            port: options.port,
+            host: options.host ?? '127.0.0.1',
+            strictVersionPolicy: options.strictVersionPolicy ?? true,
+            versionOverride: options.versionOverride ?? PROTOCOL_SCHEMA_VERSION,
+        };
+    }
+    /**
+     * 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() {
+        return this.options.versionOverride;
+    }
+    /** Resolved port (valid after `start()` resolves). */
+    get port() {
+        if (this.boundPort === null) {
+            throw new Error('reference-server: port not resolved — did you await start()?');
+        }
+        return this.boundPort;
+    }
+    /** Base URL for the kit's `runConformance({serverUrl})`. */
+    get baseUrl() {
+        return `http://${this.options.host}:${this.port}`;
+    }
+    async start() {
+        const http = createServer();
+        const wss = new WebSocketServer({ server: http, path: '/ws' });
+        wss.on('connection', (socket) => {
+            this.handleConnection(socket);
+        });
+        await new Promise((done, fail) => {
+            const onError = (err) => {
+                http.off('listening', onListening);
+                fail(err);
+            };
+            const onListening = () => {
+                http.off('error', onError);
+                done();
+            };
+            http.once('error', onError);
+            http.once('listening', onListening);
+            http.listen(this.options.port, this.options.host);
+        });
+        const address = http.address();
+        if (address === null || typeof address === 'string') {
+            throw new Error('reference-server: failed to resolve bound port');
+        }
+        this.boundPort = address.port;
+        this.http = http;
+        this.wss = wss;
+    }
+    async stop() {
+        const wss = this.wss;
+        const http = this.http;
+        if (wss !== null) {
+            await new Promise((done) => wss.close(() => done()));
+            this.wss = null;
+        }
+        if (http !== null) {
+            await new Promise((done) => http.close(() => done()));
+            this.http = null;
+        }
+        this.boundPort = null;
+    }
+    // ===========================================================================
+    // Connection handling
+    // ===========================================================================
+    handleConnection(socket) {
+        // Subscribe state is per-connection — one WS may subscribe to
+        // one session at a time. Re-subscribe overwrites.
+        let subscribedSessionId = null;
+        const subscriber = {
+            send: (frame) => {
+                try {
+                    socket.send(JSON.stringify(frame));
+                }
+                catch {
+                    // Socket lifecycle issues are the caller's problem.
+                }
+            },
+        };
+        socket.on('message', (raw) => {
+            void this.handleMessage(raw.toString('utf8'), {
+                socket,
+                subscriber,
+                onSubscribed: (sessionId) => {
+                    // If previously subscribed to a different session, unsub
+                    // from it first.
+                    if (subscribedSessionId !== null && subscribedSessionId !== sessionId) {
+                        this.sessions.removeSubscriber(subscribedSessionId, subscriber);
+                    }
+                    subscribedSessionId = sessionId;
+                },
+            });
+        });
+        socket.on('close', () => {
+            if (subscribedSessionId !== null) {
+                this.sessions.removeSubscriber(subscribedSessionId, subscriber);
+            }
+        });
+    }
+    async handleMessage(text, ctx) {
+        let frame;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch {
+            // Malformed JSON — silently drop per SPEC non-promise "no flow
+            // control / no retries". Real servers would log; the reference
+            // server keeps it silent so `no-op` fixtures pass.
+            return;
+        }
+        if (frame === null || typeof frame !== 'object')
+            return;
+        const f = frame;
+        if (f['type'] === 'subscribe') {
+            this.handleSubscribe(f, {
+                subscriber: ctx.subscriber,
+                onSubscribed: ctx.onSubscribed,
+                socket: ctx.socket,
+            });
+            return;
+        }
+        if (f['type'] === 'action' && isActionFrame(frame)) {
+            const session = this.sessions.get(frame.sessionId);
+            if (session === undefined)
+                return; // drop actions for unknown sessions
+            await dispatchAction(frame, { session, tools: this.tools });
+            return;
+        }
+        // Unrecognized type — silently drop (extensibly-closed; third
+        // parties may send frame types we don't know about).
+    }
+    handleSubscribe(frame, ctx) {
+        const payload = frame['payload'];
+        if (payload === null || typeof payload !== 'object')
+            return;
+        const p = payload;
+        const sessionId = p['sessionId'];
+        if (typeof sessionId !== 'string')
+            return;
+        const appId = typeof p['appId'] === 'string' ? p['appId'] : 'conformance';
+        const requestId = typeof frame['requestId'] === 'string' ? frame['requestId'] : undefined;
+        const supportedVersions = Array.isArray(p['supportedVersions'])
+            ? p['supportedVersions'].filter((v) => typeof v === 'string')
+            : undefined;
+        // Version handshake — if the client declared `supportedVersions`
+        // AND our current schema-version is not in the list, emit
+        // UPGRADE_REQUIRED per SPEC §12.2.2.
+        //
+        //   - `strictVersionPolicy: true` (default): emit + close the
+        //     WebSocket so the caller cannot proceed.
+        //   - `strictVersionPolicy: false` (advisory opt-out): emit +
+        //     keep the connection open.
+        //
+        // Per-session override precedence: if the `server-version-override`
+        // directive set a `versionOverride` on this session BEFORE the
+        // subscribe landed, advertise that value instead of the instance-
+        // level default. Lets parallel kit fixtures share one server while
+        // mismatching version on exactly one session.
+        const existingSession = this.sessions.get(sessionId);
+        const advertised = existingSession?.versionOverride ?? this.options.versionOverride;
+        if (supportedVersions !== undefined && !supportedVersions.includes(advertised)) {
+            ctx.subscriber.send({
+                type: 'error',
+                payload: {
+                    code: 'UPGRADE_REQUIRED',
+                    message: `server advertises '${advertised}'; client supports [${supportedVersions.join(', ')}]`,
+                    serverVersion: advertised,
+                },
+                ...(requestId !== undefined ? { requestId } : {}),
+            });
+            if (this.options.strictVersionPolicy) {
+                try {
+                    ctx.socket.close();
+                }
+                catch {
+                    // best-effort — socket may already be closing
+                }
+            }
+            return;
+        }
+        // Add the subscriber + emit ack.
+        this.sessions.addSubscriber(sessionId, ctx.subscriber);
+        // Preserve appId on first subscribe — create() is no-op if the
+        // session already exists from an earlier directive.
+        this.sessions.create(sessionId, appId);
+        ctx.onSubscribed(sessionId);
+        ctx.subscriber.send({
+            type: 'ack',
+            payload: { serverVersion: advertised },
+            ...(requestId !== undefined ? { requestId } : {}),
+        });
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,142 @@
+/**
+ * In-memory session store for the reference server.
+ *
+ * Sessions are ephemeral and process-local — this is the whole
+ * point of the reference server. Persistence is explicitly out of
+ * scope. Restart drops state; that's documented behavior, not a TODO.
+ *
+ * Each session carries an actionSpec map that the `register-actionspec`
+ * ConformanceHost directive populates. The action router
+ * (`./action-router.ts`) consults this map at dispatch time to
+ * resolve action-name → tool-name → handler.
+ */
+/**
+ * Actionspec entry maps an action name (the value wired into DOM
+ * `data-ggui-action` attributes on real UIs; here sent verbatim on
+ * the fixture's inputEnvelope) to the registered tool name the
+ * router should dispatch to.
+ */
+export interface ActionSpecEntry {
+    readonly name: string;
+    readonly tool: string;
+}
+/**
+ * Streamspec entry binds a stream channel to a "refresh tool" — the
+ * tool the action-router invokes after a successful wired-action
+ * dispatch to produce the channel's next snapshot. Mirrors the real
+ * `streamSpec[channel].tool` shape declared by ggui blueprints (SPEC
+ * §2.3 StreamSpec refresh triggers): a wired action mutates state,
+ * the refresh tool reads fresh state, the stream-update wraps the
+ * read into an envelope on the named channel.
+ *
+ * Reference-server scope: refresh-tool invocation is unconditional
+ * — every successful wired-action dispatch fans out through every
+ * registered streamSpec for the session. Real ggui servers may
+ * filter by which actions touch which channels; the reference
+ * server's narrower contract is "any successful action triggers all
+ * declared refreshes", which is sufficient for the kit's
+ * `stream-refresh-success` proof and stays under the package's
+ * 20–50 LOC budget for refresh-stream support.
+ */
+export interface StreamSpecEntry {
+    readonly channel: string;
+    readonly tool: string;
+}
+export interface Session {
+    readonly sessionId: string;
+    readonly appId: string;
+    readonly actionSpecs: Map<string, ActionSpecEntry>;
+    readonly streamSpecs: Map<string, StreamSpecEntry>;
+    readonly subscribers: Set<Subscriber>;
+    /**
+     * Per-session protocol-version override. When set, the WS subscribe
+     * + UPGRADE_REQUIRED paths advertise this value in place of the
+     * server-instance-level `versionOverride`.
+     *
+     * Discipline (mirrors `ReferenceServerOptions.versionOverride`):
+     * conformance fault-injection ONLY. Populated exclusively by the
+     * `server-version-override` setup directive in the conformance host
+     * adapter — production code paths leave this `undefined`.
+     *
+     * Why per-session, not per-instance: parallel kit fixtures share
+     * one `ReferenceServer`. Mutating the instance-level override would
+     * leak across sessions; the per-session field scopes the mismatch
+     * to the one fixture that asked for it.
+     */
+    versionOverride?: string;
+}
+/**
+ * Minimal subscriber handle — the action router calls `send()` to
+ * emit stream frames (including `_ggui:contract-error`) back to the
+ * subscribed WebSocket.
+ */
+export interface Subscriber {
+    send(frame: unknown): void;
+}
+/**
+ * In-memory session store. Wraps a `Map<sessionId, Session>` with
+ * the operations the ConformanceHost adapter + WS subscribe handler
+ * need. No locking — JS single-threaded; all calls originate from
+ * the event loop.
+ */
+export declare class SessionStore {
+    private readonly sessions;
+    private lastCreated;
+    create(sessionId: string, appId: string): Session;
+    /**
+     * The sessionId most recently passed to `create()`. Used by the
+     * ConformanceHost's `register-actionspec` dispatcher — that
+     * directive doesn't carry a sessionId in its JSON shape, so the
+     * adapter needs the "most recently created" scope to bind the
+     * actionspec to. This matches the fixture-authoring convention that
+     * create-session always precedes register-actionspec.
+     */
+    lastCreatedSessionId(): string | undefined;
+    get(sessionId: string): Session | undefined;
+    close(sessionId: string): boolean;
+    addSubscriber(sessionId: string, subscriber: Subscriber): Session;
+    removeSubscriber(sessionId: string, subscriber: Subscriber): void;
+    registerActionSpec(sessionId: string, entry: ActionSpecEntry): void;
+    /**
+     * Register a stream channel ↔ refresh-tool binding on the named
+     * session. Same "create-if-missing" semantics as
+     * {@link registerActionSpec} so the ConformanceHost adapter can
+     * dispatch this directive before subscribe lands. Keyed by
+     * `entry.channel` — registering the same channel twice replaces
+     * the prior binding, matching the action-spec map's behavior.
+     */
+    registerStreamSpec(sessionId: string, entry: StreamSpecEntry): void;
+    /**
+     * Set the per-session protocol-version override. Used by the
+     * `server-version-override` ConformanceHost directive — populates
+     * {@link Session.versionOverride} so the WS subscribe handler
+     * advertises this value (and emits UPGRADE_REQUIRED keyed off it)
+     * for THIS session only, leaving parallel sessions on the instance-
+     * level default.
+     *
+     * Same "create-if-missing" semantics as the other register* setters
+     * so directive ordering relative to subscribe doesn't matter.
+     */
+    setVersionOverride(sessionId: string, version: string): void;
+    /**
+     * Fan out a frame to every subscriber on the named session. Used by
+     * the `emit-envelope` ConformanceHost directive — kit fixtures use
+     * it to inject WS-observable side-effects (envelopes the server
+     * would not normally emit on its own) so the kit can assert
+     * downstream consequences (sequencing, fan-out, observability).
+     *
+     * Returns `true` if the session existed and at least one subscriber
+     * received the frame; `false` if the session is unknown OR has no
+     * subscribers attached. Caller may use the boolean to log a warning
+     * when a fixture's directive-injection lands before any subscribe
+     * — the directive then has no observable effect, which is usually
+     * a fixture-authoring bug worth surfacing.
+     *
+     * Subscriber-level send failures (closed socket, etc.) are
+     * swallowed per the same convention as the action router's
+     * `broadcast()` — one bad subscriber must not block fan-out to the
+     * rest.
+     */
+    injectFrame(sessionId: string, frame: unknown): boolean;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,WAAW,CAAqB;IAExC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAkBjD;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM,GAAG,SAAS;IAI1C,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI3C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIjC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO;IAMjE,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAMjE,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAKnE;;;;;;;OAOG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAKnE;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;CAcxD"}

package/dist/session.js

@@ -0,0 +1,134 @@
+/**
+ * In-memory session store for the reference server.
+ *
+ * Sessions are ephemeral and process-local — this is the whole
+ * point of the reference server. Persistence is explicitly out of
+ * scope. Restart drops state; that's documented behavior, not a TODO.
+ *
+ * Each session carries an actionSpec map that the `register-actionspec`
+ * ConformanceHost directive populates. The action router
+ * (`./action-router.ts`) consults this map at dispatch time to
+ * resolve action-name → tool-name → handler.
+ */
+/**
+ * In-memory session store. Wraps a `Map<sessionId, Session>` with
+ * the operations the ConformanceHost adapter + WS subscribe handler
+ * need. No locking — JS single-threaded; all calls originate from
+ * the event loop.
+ */
+export class SessionStore {
+    sessions = new Map();
+    lastCreated;
+    create(sessionId, appId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing !== undefined) {
+            this.lastCreated = sessionId;
+            return existing;
+        }
+        const session = {
+            sessionId,
+            appId,
+            actionSpecs: new Map(),
+            streamSpecs: new Map(),
+            subscribers: new Set(),
+        };
+        this.sessions.set(sessionId, session);
+        this.lastCreated = sessionId;
+        return session;
+    }
+    /**
+     * The sessionId most recently passed to `create()`. Used by the
+     * ConformanceHost's `register-actionspec` dispatcher — that
+     * directive doesn't carry a sessionId in its JSON shape, so the
+     * adapter needs the "most recently created" scope to bind the
+     * actionspec to. This matches the fixture-authoring convention that
+     * create-session always precedes register-actionspec.
+     */
+    lastCreatedSessionId() {
+        return this.lastCreated;
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    close(sessionId) {
+        return this.sessions.delete(sessionId);
+    }
+    addSubscriber(sessionId, subscriber) {
+        const session = this.create(sessionId, 'conformance');
+        session.subscribers.add(subscriber);
+        return session;
+    }
+    removeSubscriber(sessionId, subscriber) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined)
+            return;
+        session.subscribers.delete(subscriber);
+    }
+    registerActionSpec(sessionId, entry) {
+        const session = this.create(sessionId, 'conformance');
+        session.actionSpecs.set(entry.name, entry);
+    }
+    /**
+     * Register a stream channel ↔ refresh-tool binding on the named
+     * session. Same "create-if-missing" semantics as
+     * {@link registerActionSpec} so the ConformanceHost adapter can
+     * dispatch this directive before subscribe lands. Keyed by
+     * `entry.channel` — registering the same channel twice replaces
+     * the prior binding, matching the action-spec map's behavior.
+     */
+    registerStreamSpec(sessionId, entry) {
+        const session = this.create(sessionId, 'conformance');
+        session.streamSpecs.set(entry.channel, entry);
+    }
+    /**
+     * Set the per-session protocol-version override. Used by the
+     * `server-version-override` ConformanceHost directive — populates
+     * {@link Session.versionOverride} so the WS subscribe handler
+     * advertises this value (and emits UPGRADE_REQUIRED keyed off it)
+     * for THIS session only, leaving parallel sessions on the instance-
+     * level default.
+     *
+     * Same "create-if-missing" semantics as the other register* setters
+     * so directive ordering relative to subscribe doesn't matter.
+     */
+    setVersionOverride(sessionId, version) {
+        const session = this.create(sessionId, 'conformance');
+        session.versionOverride = version;
+    }
+    /**
+     * Fan out a frame to every subscriber on the named session. Used by
+     * the `emit-envelope` ConformanceHost directive — kit fixtures use
+     * it to inject WS-observable side-effects (envelopes the server
+     * would not normally emit on its own) so the kit can assert
+     * downstream consequences (sequencing, fan-out, observability).
+     *
+     * Returns `true` if the session existed and at least one subscriber
+     * received the frame; `false` if the session is unknown OR has no
+     * subscribers attached. Caller may use the boolean to log a warning
+     * when a fixture's directive-injection lands before any subscribe
+     * — the directive then has no observable effect, which is usually
+     * a fixture-authoring bug worth surfacing.
+     *
+     * Subscriber-level send failures (closed socket, etc.) are
+     * swallowed per the same convention as the action router's
+     * `broadcast()` — one bad subscriber must not block fan-out to the
+     * rest.
+     */
+    injectFrame(sessionId, frame) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined)
+            return false;
+        if (session.subscribers.size === 0)
+            return false;
+        for (const subscriber of session.subscribers) {
+            try {
+                subscriber.send(frame);
+            }
+            catch {
+                // Subscriber lifecycle issues (closed socket, etc.) are the
+                // subscriber's problem — the store keeps fanning out.
+            }
+        }
+        return true;
+    }
+}

package/dist/tool-registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tool registry — the 4 handler kinds the reference server wires
+ * through wired-action dispatch. Names match the `handler` enumeration
+ * in `packages/protocol-conformance/src/conformance-host.ts`'s
+ * `RegisterToolSetup` so the conformance kit's `register-tool`
+ * directive drops through cleanly.
+ *
+ * The four handler kinds:
+ *
+ *   - `echo`     — returns `{received: args}`.
+ *   - `throw`    — rejects with `Error('tool_threw_for_fixture')`.
+ *   - `timeout`  — never resolves; router enforces a 500ms timeout.
+ *   - `malformed`— returns `{wrong: 'shape'}` to exercise
+ *                  SCHEMA_VIOLATION.
+ *
+ * `TOOL_NOT_FOUND` is the 5th failure path — exercised by dispatching
+ * to an action whose tool is NOT in the registry; no handler needed.
+ *
+ * Handlers are declarative: they return `{status: 'resolved', value}`
+ * or throw. The router consults the return shape against the
+ * declared channel schema (minimal — currently only `malformed` is
+ * flagged) and maps unsupported cases to `_ggui:contract-error` with
+ * the matching ContractErrorCode.
+ */
+/**
+ * One tool's executable behavior. Async so `timeout` can return a
+ * never-resolving promise the router bounds with a timer.
+ */
+export type ToolHandler = (args: unknown) => Promise<unknown>;
+export type ToolHandlerKind = 'echo' | 'throw' | 'timeout' | 'malformed' | 'malformed-stream' | 'list-snapshot' | (string & {});
+/**
+ * Registered tool — the handler + its declared behavior kind so
+ * the router can match against fixture expectations.
+ */
+export interface RegisteredTool {
+    readonly name: string;
+    readonly kind: ToolHandlerKind;
+    readonly handler: ToolHandler;
+}
+/**
+ * Build one of the four canonical handlers by kind. Unknown kinds
+ * throw — the caller (ConformanceHost adapter or setup-step
+ * dispatcher) MUST surface this as an honest "handler not implemented"
+ * error so the kit records a SKIP with the error message as reason.
+ */
+export declare function buildHandler(kind: ToolHandlerKind): ToolHandler;
+/**
+ * In-memory tool registry. Scoped to a session via the action router
+ * (the plan's register-tool directive wires a handler under the
+ * session's tool namespace). No-persistence by design.
+ */
+export declare class ToolRegistry {
+    private readonly tools;
+    register(name: string, kind: ToolHandlerKind): void;
+    unregister(name: string): boolean;
+    get(name: string): RegisteredTool | undefined;
+    has(name: string): boolean;
+    /** Name of the first tool registered on this registry, or
+     *  `undefined` if none. Used by the action-router as a fallback
+     *  when no explicit action→tool binding exists. */
+    firstRegistered(): string | undefined;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9D,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,OAAO,GACP,SAAS,GACT,WAAW,GACX,kBAAkB,GAClB,eAAe,GACf,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAYD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAkC/D;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAE3D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI;IAInD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;uDAEmD;IACnD,eAAe,IAAI,MAAM,GAAG,SAAS;CAItC"}

package/dist/tool-registry.js

@@ -0,0 +1,99 @@
+/**
+ * Tool registry — the 4 handler kinds the reference server wires
+ * through wired-action dispatch. Names match the `handler` enumeration
+ * in `packages/protocol-conformance/src/conformance-host.ts`'s
+ * `RegisterToolSetup` so the conformance kit's `register-tool`
+ * directive drops through cleanly.
+ *
+ * The four handler kinds:
+ *
+ *   - `echo`     — returns `{received: args}`.
+ *   - `throw`    — rejects with `Error('tool_threw_for_fixture')`.
+ *   - `timeout`  — never resolves; router enforces a 500ms timeout.
+ *   - `malformed`— returns `{wrong: 'shape'}` to exercise
+ *                  SCHEMA_VIOLATION.
+ *
+ * `TOOL_NOT_FOUND` is the 5th failure path — exercised by dispatching
+ * to an action whose tool is NOT in the registry; no handler needed.
+ *
+ * Handlers are declarative: they return `{status: 'resolved', value}`
+ * or throw. The router consults the return shape against the
+ * declared channel schema (minimal — currently only `malformed` is
+ * flagged) and maps unsupported cases to `_ggui:contract-error` with
+ * the matching ContractErrorCode.
+ */
+/**
+ * Returns a never-resolving promise. The router pairs it with a
+ * timer to emit `TOOL_TIMEOUT` contract-error after N ms.
+ */
+function neverResolve() {
+    return new Promise(() => {
+        /* deliberate: never settles */
+    });
+}
+/**
+ * Build one of the four canonical handlers by kind. Unknown kinds
+ * throw — the caller (ConformanceHost adapter or setup-step
+ * dispatcher) MUST surface this as an honest "handler not implemented"
+ * error so the kit records a SKIP with the error message as reason.
+ */
+export function buildHandler(kind) {
+    switch (kind) {
+        case 'echo':
+            return async (args) => ({ received: args });
+        case 'throw':
+            return async () => {
+                throw new Error('tool_threw_for_fixture');
+            };
+        case 'timeout':
+            return () => neverResolve();
+        case 'malformed':
+        case 'malformed-stream':
+            // Both kinds return a shape that does not match the declared
+            // channel schema — router maps to SCHEMA_VIOLATION.
+            // `malformed-stream` is the fixture-authored alias used by
+            // `stream-schema-violation` in the kit.
+            return async () => ({ wrong: 'shape' });
+        case 'list-snapshot':
+            // Refresh-tool kind: returns a deterministic empty list snapshot
+            // (`{ items: [] }`). Models the "list-fresh-state" role of a
+            // streamSpec refresh tool (real ggui blueprints' `tasks_list` /
+            // `notes_list` etc.). The reference server runs handlers
+            // statelessly — the snapshot intentionally does NOT reflect
+            // prior `tasks_create` calls, since modeling stateful in-memory
+            // stores is out of scope for the smallest conformant impl. The
+            // kit's `stream-refresh-success` matcher only asserts the
+            // channel-update arrived with the declared shape, not that the
+            // payload reflects mutation history.
+            return async () => ({ items: [] });
+        default:
+            throw new Error(`reference-server: tool handler kind '${String(kind)}' is not recognized — supported: echo, throw, timeout, malformed, malformed-stream, list-snapshot`);
+    }
+}
+/**
+ * In-memory tool registry. Scoped to a session via the action router
+ * (the plan's register-tool directive wires a handler under the
+ * session's tool namespace). No-persistence by design.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    register(name, kind) {
+        this.tools.set(name, { name, kind, handler: buildHandler(kind) });
+    }
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Name of the first tool registered on this registry, or
+     *  `undefined` if none. Used by the action-router as a fallback
+     *  when no explicit action→tool binding exists. */
+    firstRegistered() {
+        const it = this.tools.keys().next();
+        return it.done === true ? undefined : it.value;
+    }
+}