@ggui-ai/protocol-reference-server 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/server.js

@@ -1,7 +1,12 @@
 /**
  * `ReferenceServer` — the minimal WS live-channel server this package
- * exports. Honest scope: SPEC §12.2 wire, version handshake,
- * wired-action dispatch. That's it.
+ * exports. Honest scope: SPEC §12.2 wire (subscribe incl. the §12.2
+ * appId-tenancy MUST → APP_MISMATCH), version handshake, the single
+ * action-routing model (action → consume-buffer append → ack with
+ * sequence; undeclared actions AND schema-violating payloads rejected
+ * with CONTRACT_VIOLATION per SPEC §4.6 receipt validation), and
+ * `host_context_observed` persistence onto `GguiSession.hostContext`.
+ * 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
@@ -9,22 +14,19 @@
  * server passes `@ggui-ai/protocol-conformance`, the protocol has
  * no implicit `@ggui-ai/mcp-server` coupling.
  *
- * Wire-field note: the consumer (`@ggui-ai/protocol-conformance`)
- * still names the render identity field `sessionId` on the wire (its
- * fixtures have not yet been renamed). The reference server honors
- * the consumer contract by reading that field name verbatim, then
- * binds the value to a `renderId` internally — see {@link Render}
- * for the canonical identity name used throughout this package.
+ * Wire-field note: the GguiSession identity field is the canonical SPEC
+ * field `sessionId` — see {@link GguiSession} for the identity name used
+ * throughout this package.
  */
 import { createServer } from 'node:http';
 import { PROTOCOL_SCHEMA_VERSION } from '@ggui-ai/protocol';
 import { WebSocketServer } from 'ws';
-import { dispatchAction, parseActionFrame } from './action-router.js';
-import { RenderStore } from './render.js';
-import { ToolRegistry } from './tool-registry.js';
+import { handleAction, parseActionFrame } from './action-router.js';
+import { handleHostContextObserved, parseHostContextObservedFrame, } from './host-context.js';
+import { isRecord } from '@ggui-ai/protocol';
+import { DEPLOYMENT_DEFAULT_APP_ID, GguiSessionStore, } from './render.js';
 export class ReferenceServer {
-    renders = new RenderStore();
-    tools = new ToolRegistry();
+    renders = new GguiSessionStore();
     options;
     http = null;
     wss = null;
@@ -104,7 +106,7 @@ export class ReferenceServer {
     handleConnection(socket) {
         // Subscribe state is per-connection — one WS may subscribe to
         // one render at a time. Re-subscribe overwrites.
-        let subscribedRenderId = null;
+        let subscribedSessionId = null;
         const subscriber = {
             send: (frame) => {
                 try {
@@ -116,26 +118,26 @@ export class ReferenceServer {
             },
         };
         socket.on('message', (raw) => {
-            void this.handleMessage(raw.toString('utf8'), {
+            this.handleMessage(raw.toString('utf8'), {
                 socket,
                 subscriber,
-                onSubscribed: (renderId) => {
+                onSubscribed: (sessionId) => {
                     // If previously subscribed to a different render, unsub
                     // from it first.
-                    if (subscribedRenderId !== null && subscribedRenderId !== renderId) {
-                        this.renders.removeSubscriber(subscribedRenderId, subscriber);
+                    if (subscribedSessionId !== null && subscribedSessionId !== sessionId) {
+                        this.renders.removeSubscriber(subscribedSessionId, subscriber);
                     }
-                    subscribedRenderId = renderId;
+                    subscribedSessionId = sessionId;
                 },
             });
         });
         socket.on('close', () => {
-            if (subscribedRenderId !== null) {
-                this.renders.removeSubscriber(subscribedRenderId, subscriber);
+            if (subscribedSessionId !== null) {
+                this.renders.removeSubscriber(subscribedSessionId, subscriber);
             }
         });
     }
-    async handleMessage(text, ctx) {
+    handleMessage(text, ctx) {
         let frame;
         try {
             frame = JSON.parse(text);
@@ -146,25 +148,43 @@ export class ReferenceServer {
             // server keeps it silent so `no-op` fixtures pass.
             return;
         }
-        if (frame === null || typeof frame !== 'object')
+        if (!isRecord(frame))
             return;
-        const f = frame;
-        if (f['type'] === 'subscribe') {
-            this.handleSubscribe(f, {
+        if (frame['type'] === 'subscribe') {
+            this.handleSubscribe(frame, {
                 subscriber: ctx.subscriber,
                 onSubscribed: ctx.onSubscribed,
                 socket: ctx.socket,
             });
             return;
         }
-        if (f['type'] === 'action') {
+        if (frame['type'] === 'action') {
             const parsed = parseActionFrame(frame);
             if (parsed === undefined)
                 return; // malformed — silently drop
-            const render = this.renders.get(parsed.renderId);
+            const render = this.renders.get(parsed.payload.sessionId);
             if (render === undefined)
                 return; // drop actions for unknown renders
-            await dispatchAction(parsed, { render, tools: this.tools });
+            // Ack + contract rejections reply to the SENDING socket — the
+            // dispatcher gets the persistence proof, not the broadcast set.
+            handleAction(parsed, { render, reply: ctx.subscriber });
+            return;
+        }
+        if (frame['type'] === 'host_context_observed') {
+            // Fire-and-forget observation message — no response frame. The
+            // obligation is purely stateful: persist the validated
+            // projection onto the named render (idempotent overwrite). The
+            // first-party server scopes the write through its subscriber
+            // binding; this no-auth server's tenancy scope is the render
+            // lookup itself — malformed frames and unknown renders drop,
+            // mirroring the action path.
+            const parsed = parseHostContextObservedFrame(frame);
+            if (parsed === undefined)
+                return; // malformed — silently drop
+            const render = this.renders.get(parsed.payload.sessionId);
+            if (render === undefined)
+                return; // drop observations for unknown renders
+            handleHostContextObserved(parsed, render);
             return;
         }
         // Unrecognized type — silently drop (extensibly-closed; third
@@ -172,24 +192,31 @@ export class ReferenceServer {
     }
     handleSubscribe(frame, ctx) {
         const payload = frame['payload'];
-        if (payload === null || typeof payload !== 'object')
+        if (!isRecord(payload))
+            return;
+        // GguiSession-identity field: the canonical SPEC field `sessionId`.
+        const sessionId = typeof payload['sessionId'] === 'string' ? payload['sessionId'] : undefined;
+        if (sessionId === undefined)
             return;
-        const p = payload;
-        // Wire-field acceptance: the conformance kit currently sends
-        // `sessionId`; the canonical SPEC field is `renderId`. Read both
-        // so the reference server is forward-compatible with the kit's
-        // eventual rename without breaking today's fixtures.
-        const renderId = typeof p['renderId'] === 'string'
-            ? p['renderId']
-            : typeof p['sessionId'] === 'string'
-                ? p['sessionId']
-                : undefined;
-        if (renderId === undefined)
+        // `appId` is OPTIONAL on the subscribe payload (SPEC §12.2 field
+        // table): absent ⇒ the server resolves the caller's
+        // identity-default app. This server's identity model is no-auth —
+        // every caller is the same anonymous identity — so the
+        // identity-default collapses to the deployment-level
+        // {@link DEPLOYMENT_DEFAULT_APP_ID}; the resolved value flows
+        // through the SAME tenancy gate + provision-on-subscribe path a
+        // client-supplied appId takes. A PRESENT-but-non-string `appId` is
+        // still a malformed frame and takes the missing-`sessionId`
+        // posture: silently dropped, no error frame, no render
+        // provisioned.
+        const rawAppId = payload['appId'];
+        if (rawAppId !== undefined && typeof rawAppId !== 'string')
             return;
-        const appId = typeof p['appId'] === 'string' ? p['appId'] : 'conformance';
+        const appId = rawAppId ?? DEPLOYMENT_DEFAULT_APP_ID;
         const requestId = typeof frame['requestId'] === 'string' ? frame['requestId'] : undefined;
-        const supportedVersions = Array.isArray(p['supportedVersions'])
-            ? p['supportedVersions'].filter((v) => typeof v === 'string')
+        const rawVersions = payload['supportedVersions'];
+        const supportedVersions = Array.isArray(rawVersions)
+            ? rawVersions.filter((v) => typeof v === 'string')
             : undefined;
         // Version handshake — if the client declared `supportedVersions`
         // AND our current schema-version is not in the list, emit
@@ -205,7 +232,7 @@ export class ReferenceServer {
         // subscribe landed, advertise that value instead of the instance-
         // level default. Lets parallel kit fixtures share one server while
         // mismatching version on exactly one render.
-        const existingRender = this.renders.get(renderId);
+        const existingRender = this.renders.get(sessionId);
         const advertised = existingRender?.versionOverride ?? this.options.versionOverride;
         if (supportedVersions !== undefined && !supportedVersions.includes(advertised)) {
             ctx.subscriber.send({
@@ -227,12 +254,39 @@ export class ReferenceServer {
             }
             return;
         }
-        // Add the subscriber + emit ack.
-        this.renders.addSubscriber(renderId, ctx.subscriber);
-        // Preserve appId on first subscribe — create() is no-op if the
-        // render already exists from an earlier directive.
-        this.renders.create(renderId, appId);
-        ctx.onSubscribed(renderId);
+        // SPEC §12.2 tenancy MUST: the subscribe's `appId` MUST match the
+        // GguiSession's bound appId or the subscribe fails APP_MISMATCH
+        // (§12.2.3). The code is deliberately distinct from
+        // SESSION_NOT_FOUND — the GguiSession EXISTS, it is reachable only
+        // from a different app, so the client's recovery is "fix your
+        // appId / API key", not "re-handshake". Only an existing render
+        // can mismatch: an unknown sessionId falls through to the
+        // provision-on-subscribe path below, which binds the subscribe's
+        // own appId (mirroring the first-party dev-mode posture: look up
+        // first; if not present, create). The mismatch rejects without
+        // registering a subscriber and without an ack; the socket stays
+        // open (matching the first-party handler).
+        if (existingRender !== undefined && existingRender.appId !== appId) {
+            ctx.subscriber.send({
+                type: 'error',
+                payload: {
+                    code: 'APP_MISMATCH',
+                    message: `GguiSession '${sessionId}' belongs to a different app`,
+                },
+                ...(requestId !== undefined ? { requestId } : {}),
+            });
+            return;
+        }
+        // Bind the render BEFORE registering the subscriber: create() is a
+        // no-op when the render already exists (preserving the appId an
+        // earlier directive bound), and for provision-on-subscribe it
+        // binds the subscribe payload's own appId. Ordering matters —
+        // `addSubscriber`'s create-if-missing fallback binds the default
+        // app, which would make this render reject the SAME client's next
+        // subscribe with APP_MISMATCH.
+        this.renders.create(sessionId, appId);
+        this.renders.addSubscriber(sessionId, ctx.subscriber);
+        ctx.onSubscribed(sessionId);
         ctx.subscriber.send({
             type: 'ack',
             payload: { serverVersion: advertised },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol-reference-server",
-  "version": "0.2.0-alpha.4",
+  "version": "0.4.0-rc.0",
   "description": "Minimal reference implementation of the ggui protocol. Implements exactly enough of the live-channel WebSocket wire to pass the @ggui-ai/protocol-conformance kit. Not a production server — it exists to prove the protocol is vendor-neutral: an independent, from-scratch implementation passing the kit grounds that claim empirically.",
   "keywords": [
     "ggui",
@@ -29,14 +29,14 @@
   },
   "dependencies": {
     "ws": "^8.20.1",
-    "@ggui-ai/protocol": "0.2.0-alpha.4"
+    "@ggui-ai/protocol": "0.4.0-rc.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.10",
     "typescript": "^5.0.0",
-    "vitest": "^3.0.0",
-    "@ggui-ai/protocol-conformance": "0.2.0-alpha.4"
+    "vitest": "^3.2.6",
+    "@ggui-ai/protocol-conformance": "0.4.0-rc.0"
   },
   "repository": {
     "type": "git",
@@ -55,7 +55,7 @@
   },
   "author": "ggui contributors <hello@ggui.ai>",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node ../scripts/fix-esm-imports.mjs dist && chmod +x dist/cli.js",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../scripts/fix-esm-imports.mjs dist && chmod +x dist/cli.js",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",

package/dist/tool-registry.d.ts

@@ -1,63 +0,0 @@
-/**
- * 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 render via the action router
- * (the plan's register-tool directive wires a handler under the
- * render'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

@@ -1 +0,0 @@
-{"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

@@ -1,99 +0,0 @@
-/**
- * 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 render via the action router
- * (the plan's register-tool directive wires a handler under the
- * render'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;
-    }
-}