@ouispec/agent-realtime 0.1.0

package/dist/events/declared.js

@@ -0,0 +1,30 @@
+import { createPayloadValidator } from '@ouispec/agent-events/validate';
+export function createDeclaredEvents(catalog) {
+    return { catalog, validator: createPayloadValidator(catalog) };
+}
+/** The rooms an event is declared for, as its patterns. */
+function declaredRooms(events, event) {
+    return events.catalog
+        .get(event)
+        .rooms.map((r) => r.pattern ?? "the turn's room")
+        .join(', ');
+}
+/**
+ * Why `data` may not be sent as `event` to `rooms`, or null when it may.
+ * `noun` names the data as the caller knows it: an emit's payload, a relay's data.
+ */
+export function declaredRefusal(events, event, data, rooms, noun) {
+    if (!events.catalog.has(event))
+        return `event "${event}" is not declared`;
+    if (rooms.length === 0) {
+        return `"${event}" is declared for ${declaredRooms(events, event)}; name its rooms, a declared event is never broadcast`;
+    }
+    for (const room of rooms) {
+        if (!events.catalog.allowsRoom(event, room)) {
+            return `"${event}" may not go to ${room}; it is declared for ${declaredRooms(events, event)}`;
+        }
+    }
+    const problems = events.validator.problems(event, data);
+    return problems.length > 0 ? `invalid "${event}" ${noun}: ${problems.join('; ')}` : null;
+}
+//# sourceMappingURL=declared.js.map

package/dist/events/declared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared.js","sourceRoot":"","sources":["../../src/events/declared.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAyB,MAAM,gCAAgC,CAAC;AAO/F,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,sBAAsB,CAAC,OAAO,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,2DAA2D;AAC3D,SAAS,aAAa,CAAC,MAAsB,EAAE,KAAa;IAC1D,OAAO,MAAM,CAAC,OAAO;SAClB,GAAG,CAAC,KAAK,CAAE;SACX,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,iBAAiB,CAAC;SAChD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAsB,EACtB,KAAa,EACb,IAAa,EACb,KAAwB,EACxB,IAAwB;IAExB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,KAAK,mBAAmB,CAAC;IAC1E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,KAAK,qBAAqB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,uDAAuD,CAAC;IAC3H,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO,IAAI,KAAK,mBAAmB,IAAI,wBAAwB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAChG,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACxD,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,KAAK,KAAK,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3F,CAAC"}

package/dist/events/settlements.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Job settlements, kept for the workers that wait on them (W9).
+ *
+ * Every declared completion or failure the server emits settles one job: the
+ * job of its kind whose id is in its correlation field. The first is kept, so
+ * a worker on any instance can ask how the job ended without joining a room,
+ * even when it asks after the event went out:
+ *
+ *   events:settlement:{kind}:{id}  → JSON Settlement, TTL 35 min, first wins
+ *   channel events:settlements     → `{kind}:{id}`, published when one is kept
+ *
+ * The emitter is the product's backend, trusted by the internal key; so is
+ * the worker that reads. No browser reaches either.
+ */
+import type { Settlement } from '@ouispec/agent-events';
+import type { RealtimeLogger } from '../logger.js';
+import { type ResultsRedis, type ResultsSubscriber } from '../redis-waits.js';
+/** As long as the longest wait on a job may run, with margin: the same horizon as a final UI action result. */
+export declare const SETTLEMENT_TTL_SEC: number;
+export interface SettlementStore {
+    /** Keep a job's settlement. Returns false when the job was already settled. */
+    record(settlement: Settlement): Promise<boolean>;
+    /** The job's settlement, waiting up to `waitMs` for it. */
+    await(kind: string, id: string, waitMs: number): Promise<Settlement | null>;
+    pendingCount(): number;
+}
+export declare function createSettlementStore(redis: ResultsRedis, subscriber: ResultsSubscriber, logger: RealtimeLogger): SettlementStore;
+//# sourceMappingURL=settlements.d.ts.map

package/dist/events/settlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlements.d.ts","sourceRoot":"","sources":["../../src/events/settlements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG7F,+GAA+G;AAC/G,eAAO,MAAM,kBAAkB,QAAU,CAAC;AAK1C,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,2DAA2D;IAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC5E,YAAY,IAAI,MAAM,CAAC;CACxB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,eAAe,CAoCjI"}

package/dist/events/settlements.js

@@ -0,0 +1,29 @@
+import { createWaitHub } from '../redis-waits.js';
+const CHANNEL = 'events:settlements';
+/** As long as the longest wait on a job may run, with margin: the same horizon as a final UI action result. */
+export const SETTLEMENT_TTL_SEC = 35 * 60;
+const settlementId = (kind, id) => `${kind}:${id}`;
+const settlementKey = (kind, id) => `events:settlement:${settlementId(kind, id)}`;
+export function createSettlementStore(redis, subscriber, logger) {
+    const hub = createWaitHub(subscriber, CHANNEL, logger, 'Settlements');
+    async function read(kind, id) {
+        const raw = await redis.get(settlementKey(kind, id));
+        return raw ? JSON.parse(raw) : null;
+    }
+    return {
+        async record(settlement) {
+            const written = await redis.set(settlementKey(settlement.kind, settlement.id), JSON.stringify(settlement), 'EX', SETTLEMENT_TTL_SEC, 'NX');
+            if (written !== 'OK') {
+                logger.info({ kind: settlement.kind, id: settlement.id, event: settlement.event }, 'Job already settled; later settlement not kept');
+                return false;
+            }
+            await redis.publish(CHANNEL, settlementId(settlement.kind, settlement.id));
+            return true;
+        },
+        await(kind, id, waitMs) {
+            return hub.wait(settlementId(kind, id), waitMs, () => read(kind, id), (err) => logger.error({ err, kind, id }, 'Settlement read failed'));
+        },
+        pendingCount: () => hub.pendingCount(),
+    };
+}
+//# sourceMappingURL=settlements.js.map

package/dist/events/settlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlements.js","sourceRoot":"","sources":["../../src/events/settlements.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,aAAa,EAA6C,MAAM,mBAAmB,CAAC;AAE7F,MAAM,OAAO,GAAG,oBAAoB,CAAC;AACrC,+GAA+G;AAC/G,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,CAAC;AAE1C,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;AACnE,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,EAAE,CAAC,qBAAqB,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;AAUlG,MAAM,UAAU,qBAAqB,CAAC,KAAmB,EAAE,UAA6B,EAAE,MAAsB;IAC9G,MAAM,GAAG,GAAG,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IAEtE,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,EAAU;QAC1C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QACrD,OAAO,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,CAAC;IAED,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,UAAU;YACrB,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,CAC7B,aAAa,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,EAC7C,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAC1B,IAAI,EACJ,kBAAkB,EAClB,IAAI,CACL,CAAC;YACF,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,MAAM,CAAC,IAAI,CACT,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,EACrE,gDAAgD,CACjD,CAAC;gBACF,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;YAC3E,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM;YACpB,OAAO,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAC5E,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,wBAAwB,CAAC,CAC1D,CAAC;QACJ,CAAC;QAED,YAAY,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,EAAE;KACvC,CAAC;AACJ,CAAC"}

package/dist/http/routes.d.ts

@@ -0,0 +1,91 @@
+import { Router } from 'express';
+import type { Server } from 'socket.io';
+import type { RoomPolicy } from '../types.js';
+import type { RoomTokenSigner } from '../rooms/room-token.js';
+import type { OUIResultStore } from '../oui/results.js';
+import type { RealtimeLogger } from '../logger.js';
+import { type DeclaredEvents } from '../events/declared.js';
+import type { SettlementStore } from '../events/settlements.js';
+/** The longest a single result wait may hold a request open. Callers ask again until their own deadline. */
+export declare const MAX_RESULT_WAIT_MS = 25000;
+/** The longest `/api/emit` waits for the receivers' receipts (`ackTimeoutMs`). */
+export declare const MAX_RECEIPT_WAIT_MS = 5000;
+/** What `/api/emit` reports when asked for receipts: how many receivers acknowledged, and how many accepted. */
+export interface EmitReceipts {
+    acknowledged: number;
+    accepted: number;
+}
+/** A constant-time check of the internal key. */
+export declare function createInternalKeyCheck(internalApiKey: string): (presented: string | undefined) => boolean;
+export interface RouteDeps {
+    io: Server;
+    roomPolicy: RoomPolicy;
+    roomTokens: RoomTokenSigner;
+    /** Null until Redis is connected. */
+    results: () => OUIResultStore | null;
+    /** The product's event declarations; null when none were given. */
+    declared: DeclaredEvents | null;
+    /** Null when there are no declarations. */
+    settlements: () => SettlementStore | null;
+    isInternalKey: (presented: string | undefined) => boolean;
+    logger: RealtimeLogger;
+}
+export declare function healthRouter(deps: Pick<RouteDeps, 'io' | 'results'>): Router;
+/**
+ * POST /api/emit — `{ event, data, rooms? }`. Sends a server event to rooms,
+ * or to every socket when `rooms` is empty or absent. How the product's
+ * backend and worker reach clients (turn events, UI action dispatches, job
+ * events).
+ *
+ * With event declarations: only a declared event, with a payload its schema
+ * accepts, into rooms it is declared for (never a broadcast); anything else is
+ * a 400, logged. A completion or failure is then kept as its job's settlement.
+ *
+ * With `ackTimeoutMs` (rooms only, at most MAX_RECEIPT_WAIT_MS): the event asks
+ * its receivers for a receipt, and the response says how many acknowledged it
+ * within that time and how many accepted it (`receipts`). A UI action request
+ * is answered `{ ok: true }` by a tab that received it (oui-spec §7.3.7), so the
+ * worker can tell a request that reached the page from one that reached
+ * nobody, and send it again only then.
+ */
+export declare function emitRouter(deps: RouteDeps): Router;
+/**
+ * POST /internal/room-token — `{ userId, room }` → `{ token }`.
+ *
+ * Signs a token that admits `userId` to `room`, for any room the policy marks
+ * `requiresToken`. The product calls it only after its own authorization for
+ * the resource accepted the user; this route decides nothing about access.
+ */
+export declare function roomTokenRouter(deps: RouteDeps): Router;
+/**
+ * GET /internal/oui/action-results/:requestId?userId=&waitMs=&final=1
+ *
+ * The client's answer to a UI action request (ADR-0209). Waits up to `waitMs`
+ * (capped at 25 s) for it to arrive. With `final=1`, the final answer: for an
+ * async action, the one sent when its work is done or has failed, never its
+ * acknowledgment; for any other action, its one answer.
+ *   200 — the OUIActionResult
+ *   204 — no answer yet; ask again
+ *   400 — userId missing or waitMs invalid
+ *   401 — missing or wrong internal API key
+ *   503 — the result store is not connected
+ *
+ * `userId` is the user the turn belongs to. An answer from any other user's
+ * socket is never returned.
+ */
+export declare function ouiResultsRouter(deps: RouteDeps): Router;
+/**
+ * GET /internal/events/settlements/:kind/:id?waitMs=
+ *
+ * How a job of a declared kind ended: its first completion or failure, as
+ * `{ kind, role, event, id, payload }`. Waits up to `waitMs` (capped at 25 s)
+ * for it; a worker asks again until its own deadline.
+ *   200 — the settlement
+ *   204 — not settled yet
+ *   400 — an undeclared kind, or waitMs invalid
+ *   401 — missing or wrong internal API key
+ *   404 — this server has no event declarations
+ *   503 — the store is not connected
+ */
+export declare function settlementsRouter(deps: RouteDeps): Router;
+//# sourceMappingURL=routes.d.ts.map

package/dist/http/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAA+B,MAAM,SAAS,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC,gHAAgH;AAChH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAMzG;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAC5B,qCAAqC;IACrC,OAAO,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;IACrC,mEAAmE;IACnE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IAC1C,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;IAC1D,MAAM,EAAE,cAAc,CAAC;CACxB;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAc5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAyElD;AAqBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CA2BvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAoCxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAsCzD"}

package/dist/http/routes.js

@@ -0,0 +1,290 @@
+/**
+ * The server's HTTP endpoints. Every `/internal/*` and `/api/emit` route
+ * requires the internal key (`x-api-key`); they are for the product's backend
+ * and its agent worker, never a browser.
+ */
+import crypto from 'node:crypto';
+import { Router } from 'express';
+import { declaredRefusal } from '../events/declared.js';
+/** The longest a single result wait may hold a request open. Callers ask again until their own deadline. */
+export const MAX_RESULT_WAIT_MS = 25_000;
+/** The longest `/api/emit` waits for the receivers' receipts (`ackTimeoutMs`). */
+export const MAX_RECEIPT_WAIT_MS = 5_000;
+/** A constant-time check of the internal key. */
+export function createInternalKeyCheck(internalApiKey) {
+    const expected = crypto.createHash('sha256').update(internalApiKey).digest();
+    return (presented) => {
+        if (typeof presented !== 'string' || presented.length === 0)
+            return false;
+        return crypto.timingSafeEqual(crypto.createHash('sha256').update(presented).digest(), expected);
+    };
+}
+function refuseWithoutKey(deps, req, res) {
+    if (deps.isInternalKey(req.headers['x-api-key']))
+        return false;
+    res.status(401).json({ error: 'Invalid or missing API key' });
+    return true;
+}
+export function healthRouter(deps) {
+    const router = Router();
+    const startedAt = Date.now();
+    router.get('/health', (_req, res) => {
+        const results = deps.results();
+        res.status(results ? 200 : 503).json({
+            status: results ? 'ok' : 'starting',
+            uptime: Math.floor((Date.now() - startedAt) / 1000),
+            connections: deps.io.engine.clientsCount,
+            pendingResultWaits: results?.pendingCount() ?? 0,
+            timestamp: new Date().toISOString(),
+        });
+    });
+    return router;
+}
+/**
+ * POST /api/emit — `{ event, data, rooms? }`. Sends a server event to rooms,
+ * or to every socket when `rooms` is empty or absent. How the product's
+ * backend and worker reach clients (turn events, UI action dispatches, job
+ * events).
+ *
+ * With event declarations: only a declared event, with a payload its schema
+ * accepts, into rooms it is declared for (never a broadcast); anything else is
+ * a 400, logged. A completion or failure is then kept as its job's settlement.
+ *
+ * With `ackTimeoutMs` (rooms only, at most MAX_RECEIPT_WAIT_MS): the event asks
+ * its receivers for a receipt, and the response says how many acknowledged it
+ * within that time and how many accepted it (`receipts`). A UI action request
+ * is answered `{ ok: true }` by a tab that received it (oui-spec §7.3.7), so the
+ * worker can tell a request that reached the page from one that reached
+ * nobody, and send it again only then.
+ */
+export function emitRouter(deps) {
+    const router = Router();
+    router.post('/api/emit', async (req, res) => {
+        if (refuseWithoutKey(deps, req, res))
+            return;
+        const { event, data, rooms, ackTimeoutMs } = (req.body ?? {});
+        if (!event || typeof event !== 'string') {
+            res.status(400).json({ error: 'event is required and must be a string' });
+            return;
+        }
+        if (rooms !== undefined && (!Array.isArray(rooms) || rooms.some((r) => typeof r !== 'string'))) {
+            res.status(400).json({ error: 'rooms must be an array of strings' });
+            return;
+        }
+        if (ackTimeoutMs !== undefined &&
+            (typeof ackTimeoutMs !== 'number' ||
+                !Number.isInteger(ackTimeoutMs) ||
+                ackTimeoutMs < 1 ||
+                ackTimeoutMs > MAX_RECEIPT_WAIT_MS)) {
+            res.status(400).json({ error: `ackTimeoutMs must be a whole number of ms from 1 to ${MAX_RECEIPT_WAIT_MS}` });
+            return;
+        }
+        const targets = rooms ?? [];
+        if (ackTimeoutMs !== undefined && targets.length === 0) {
+            res.status(400).json({ error: 'receipts (ackTimeoutMs) are asked of rooms, never of a broadcast' });
+            return;
+        }
+        const invalid = targets.filter((r) => !deps.roomPolicy.isValidRoom(r));
+        if (invalid.length > 0) {
+            res.status(400).json({ error: `Invalid room names: ${invalid.join(', ')}` });
+            return;
+        }
+        if (deps.declared) {
+            const reason = declaredRefusal(deps.declared, event, data, targets, 'payload');
+            if (reason) {
+                deps.logger.warn({ event, rooms: targets, reason }, 'Emit refused');
+                res.status(400).json({ error: reason });
+                return;
+            }
+        }
+        let receipts = null;
+        if (targets.length > 0 && ackTimeoutMs !== undefined) {
+            receipts = await emitWithReceipts(deps.io, targets, event, data, ackTimeoutMs);
+            deps.logger.info({ event, rooms: targets, hasData: data != null, receipts }, 'Emitted to rooms');
+        }
+        else if (targets.length > 0) {
+            deps.io.to(targets).emit(event, data);
+            deps.logger.info({ event, rooms: targets, hasData: data != null }, 'Emitted to rooms');
+        }
+        else {
+            deps.io.emit(event, data);
+            deps.logger.info({ event, hasData: data != null }, 'Broadcast emitted');
+        }
+        const settlement = deps.declared?.catalog.settlement(event, data) ?? null;
+        const store = deps.settlements();
+        if (settlement && store) {
+            try {
+                await store.record(settlement);
+            }
+            catch (err) {
+                // The event reached its rooms; only a worker's later wait on the job misses it.
+                deps.logger.error({ err, event, kind: settlement.kind, id: settlement.id }, 'Settlement not kept');
+                res.json({ ok: true, settled: false, ...(receipts ? { receipts } : {}) });
+                return;
+            }
+        }
+        res.json({ ok: true, ...(receipts ? { receipts } : {}) });
+    });
+    return router;
+}
+/**
+ * Emit to rooms asking each receiver for an acknowledgment, and count them:
+ * those that answered within `timeoutMs`, and of those, the ones that accepted
+ * (anything but `{ ok: false }`). A receiver that does not acknowledge — an
+ * older client — counts in neither, so its sender falls back to its own
+ * schedule. Across instances through the Redis adapter's broadcast acks.
+ */
+function emitWithReceipts(io, rooms, event, data, timeoutMs) {
+    return new Promise((resolve) => {
+        io.to(rooms)
+            .timeout(timeoutMs)
+            .emit(event, data, (_err, responses = []) => {
+            const acks = Array.isArray(responses) ? responses : [];
+            const accepted = acks.filter((r) => !(r && typeof r === 'object' && r.ok === false)).length;
+            resolve({ acknowledged: acks.length, accepted });
+        });
+    });
+}
+/**
+ * POST /internal/room-token — `{ userId, room }` → `{ token }`.
+ *
+ * Signs a token that admits `userId` to `room`, for any room the policy marks
+ * `requiresToken`. The product calls it only after its own authorization for
+ * the resource accepted the user; this route decides nothing about access.
+ */
+export function roomTokenRouter(deps) {
+    const router = Router();
+    router.post('/internal/room-token', (req, res) => {
+        if (refuseWithoutKey(deps, req, res))
+            return;
+        const { userId, room } = (req.body ?? {});
+        if (!userId || typeof userId !== 'string') {
+            res.status(400).json({ error: 'userId is required and must be a string' });
+            return;
+        }
+        if (!room || typeof room !== 'string') {
+            res.status(400).json({ error: 'room is required and must be a string' });
+            return;
+        }
+        if (!deps.roomPolicy.isValidRoom(room)) {
+            res.status(400).json({ error: `Invalid room name: ${room}` });
+            return;
+        }
+        if (!deps.roomPolicy.requiresToken(room)) {
+            res.status(400).json({ error: `${room} is joined by identity, not with a room token` });
+            return;
+        }
+        const token = deps.roomTokens.sign(userId, room);
+        deps.logger.info({ userId, room }, 'Room token issued');
+        res.json({ token, expiresInMs: deps.roomTokens.ttlMs });
+    });
+    return router;
+}
+/**
+ * GET /internal/oui/action-results/:requestId?userId=&waitMs=&final=1
+ *
+ * The client's answer to a UI action request (ADR-0209). Waits up to `waitMs`
+ * (capped at 25 s) for it to arrive. With `final=1`, the final answer: for an
+ * async action, the one sent when its work is done or has failed, never its
+ * acknowledgment; for any other action, its one answer.
+ *   200 — the OUIActionResult
+ *   204 — no answer yet; ask again
+ *   400 — userId missing or waitMs invalid
+ *   401 — missing or wrong internal API key
+ *   503 — the result store is not connected
+ *
+ * `userId` is the user the turn belongs to. An answer from any other user's
+ * socket is never returned.
+ */
+export function ouiResultsRouter(deps) {
+    const router = Router();
+    router.get('/internal/oui/action-results/:requestId', async (req, res) => {
+        if (refuseWithoutKey(deps, req, res))
+            return;
+        const requestId = req.params.requestId;
+        const userId = typeof req.query.userId === 'string' ? req.query.userId : '';
+        const waitMs = req.query.waitMs === undefined ? 0 : Number(req.query.waitMs);
+        const final = req.query.final === '1' || req.query.final === 'true';
+        if (!userId) {
+            res.status(400).json({ error: 'userId is required' });
+            return;
+        }
+        if (!Number.isFinite(waitMs) || waitMs < 0) {
+            res.status(400).json({ error: 'waitMs must be a non-negative number' });
+            return;
+        }
+        const store = deps.results();
+        if (!store) {
+            res.status(503).json({ error: 'OUI result store not connected' });
+            return;
+        }
+        try {
+            const result = await store.await(requestId, userId, Math.min(waitMs, MAX_RESULT_WAIT_MS), { final });
+            if (!result) {
+                res.status(204).end();
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            deps.logger.error({ err, requestId, userId }, 'OUI result lookup failed');
+            res.status(500).json({ error: 'OUI result lookup failed' });
+        }
+    });
+    return router;
+}
+/**
+ * GET /internal/events/settlements/:kind/:id?waitMs=
+ *
+ * How a job of a declared kind ended: its first completion or failure, as
+ * `{ kind, role, event, id, payload }`. Waits up to `waitMs` (capped at 25 s)
+ * for it; a worker asks again until its own deadline.
+ *   200 — the settlement
+ *   204 — not settled yet
+ *   400 — an undeclared kind, or waitMs invalid
+ *   401 — missing or wrong internal API key
+ *   404 — this server has no event declarations
+ *   503 — the store is not connected
+ */
+export function settlementsRouter(deps) {
+    const router = Router();
+    router.get('/internal/events/settlements/:kind/:id', async (req, res) => {
+        if (refuseWithoutKey(deps, req, res))
+            return;
+        if (!deps.declared) {
+            res.status(404).json({ error: 'this server has no event declarations' });
+            return;
+        }
+        const kind = req.params.kind;
+        const id = req.params.id;
+        const waitMs = req.query.waitMs === undefined ? 0 : Number(req.query.waitMs);
+        if (!deps.declared.catalog.jobKind(kind)) {
+            const declared = deps.declared.catalog.jobKinds().map((k) => k.kind);
+            res.status(400).json({ error: `job kind '${kind}' is not declared (declared: ${declared.join(', ') || 'none'})` });
+            return;
+        }
+        if (!Number.isFinite(waitMs) || waitMs < 0) {
+            res.status(400).json({ error: 'waitMs must be a non-negative number' });
+            return;
+        }
+        const store = deps.settlements();
+        if (!store) {
+            res.status(503).json({ error: 'settlement store not connected' });
+            return;
+        }
+        try {
+            const settlement = await store.await(kind, id, Math.min(waitMs, MAX_RESULT_WAIT_MS));
+            if (!settlement) {
+                res.status(204).end();
+                return;
+            }
+            res.json(settlement);
+        }
+        catch (err) {
+            deps.logger.error({ err, kind, id }, 'Settlement lookup failed');
+            res.status(500).json({ error: 'settlement lookup failed' });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=routes.js.map

package/dist/http/routes.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @ouispec/agent-realtime — the realtime server for agent turns and
+ * UI actions.
+ *
+ * The product supplies: an auth verifier, a room policy, the internal key, the
+ * room-token secret, the approval signing key, Redis and its CORS origins,
+ * and optionally its event declarations (ADR-0227 §2.2).
+ * The server handles: declared client events, room tokens, the UI action
+ * result store, the approval store, the emit API (held to the declarations),
+ * job settlements, and fan-out across instances.
+ */
+export type { RealtimeServerConfig, AuthAdapter, AuthResult, RoomPolicy, RelayRule, PayloadSchema, RedisConfig, RoomTokenConfig, ApprovalsConfig, } from './types.js';
+export { createRealtimeServer } from './server.js';
+export type { RealtimeServerInstance } from './server.js';
+export { assertRealtimeServerConfig } from './config.js';
+export { defineClientEvent, registerClientEvents } from './client-events/chain.js';
+export type { ClientEvent, ClientEventDefinition, ClientEventContext, Authorization, AuthenticatedSocket, } from './client-events/chain.js';
+export { relayRefusal } from './client-events/builtin.js';
+export { createRoomTokenSigner, DEFAULT_ROOM_TOKEN_TTL_MS } from './rooms/room-token.js';
+export type { RoomTokenSigner, RoomTokenPayload } from './rooms/room-token.js';
+export { joinRefusal } from './rooms/join.js';
+export { createOUIResultStore, RESULT_TTL_SEC, FINAL_RESULT_TTL_SEC } from './oui/results.js';
+export type { OUIResultStore } from './oui/results.js';
+export type { ResultsRedis, ResultsSubscriber } from './redis-waits.js';
+export { createSettlementStore, SETTLEMENT_TTL_SEC } from './events/settlements.js';
+export type { SettlementStore } from './events/settlements.js';
+export { MAX_RESULT_WAIT_MS } from './http/routes.js';
+export { createConsoleLogger } from './logger.js';
+export type { RealtimeLogger } from './logger.js';
+export { createApprovalStore, DECLINED_TTL_SEC } from './approvals/store.js';
+export type { ApprovalStore, ApprovalRedis } from './approvals/store.js';
+export { createApprovalTokenSigner, MIN_APPROVAL_KEY_LENGTH } from './approvals/token.js';
+export type { ApprovalTokenSigner, ApprovalTokenCheck } from './approvals/token.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;;;;;;;;;;GAUG;AAEH,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,WAAW,EACX,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACnF,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACzF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC9F,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACpF,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @ouispec/agent-realtime — the realtime server for agent turns and
+ * UI actions.
+ *
+ * The product supplies: an auth verifier, a room policy, the internal key, the
+ * room-token secret, the approval signing key, Redis and its CORS origins,
+ * and optionally its event declarations (ADR-0227 §2.2).
+ * The server handles: declared client events, room tokens, the UI action
+ * result store, the approval store, the emit API (held to the declarations),
+ * job settlements, and fan-out across instances.
+ */
+export { createRealtimeServer } from './server.js';
+export { assertRealtimeServerConfig } from './config.js';
+export { defineClientEvent, registerClientEvents } from './client-events/chain.js';
+export { relayRefusal } from './client-events/builtin.js';
+export { createRoomTokenSigner, DEFAULT_ROOM_TOKEN_TTL_MS } from './rooms/room-token.js';
+export { joinRefusal } from './rooms/join.js';
+export { createOUIResultStore, RESULT_TTL_SEC, FINAL_RESULT_TTL_SEC } from './oui/results.js';
+export { createSettlementStore, SETTLEMENT_TTL_SEC } from './events/settlements.js';
+export { MAX_RESULT_WAIT_MS } from './http/routes.js';
+export { createConsoleLogger } from './logger.js';
+export { createApprovalStore, DECLINED_TTL_SEC } from './approvals/store.js';
+export { createApprovalTokenSigner, MIN_APPROVAL_KEY_LENGTH } from './approvals/token.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAQnF,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEzF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG9F,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The server logs refusals, joins and results as structured records. pino's
+ * `(object, message)` signature is the shape, so a product passes its own
+ * pino logger unchanged.
+ */
+export interface RealtimeLogger {
+    debug(data: Record<string, unknown>, msg: string): void;
+    info(data: Record<string, unknown>, msg: string): void;
+    warn(data: Record<string, unknown>, msg: string): void;
+    error(data: Record<string, unknown>, msg: string): void;
+}
+/** One JSON line per record. Debug records are written only when `LOG_LEVEL=debug`. */
+export declare function createConsoleLogger(): RealtimeLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACzD;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,IAAI,cAAc,CAWpD"}

package/dist/logger.js

@@ -0,0 +1,22 @@
+/** One JSON line per record. Debug records are written only when `LOG_LEVEL=debug`. */
+export function createConsoleLogger() {
+    const line = (level, data, msg) => JSON.stringify({ level, time: Date.now(), msg, ...serializable(data) });
+    return {
+        debug: (data, msg) => {
+            if (process.env.LOG_LEVEL === 'debug')
+                console.log(line('debug', data, msg));
+        },
+        info: (data, msg) => console.log(line('info', data, msg)),
+        warn: (data, msg) => console.warn(line('warn', data, msg)),
+        error: (data, msg) => console.error(line('error', data, msg)),
+    };
+}
+/** Errors serialize to `{}` in JSON; keep their message and stack. */
+function serializable(data) {
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        out[key] = value instanceof Error ? { message: value.message, stack: value.stack } : value;
+    }
+    return out;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAYA,uFAAuF;AACvF,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,IAA6B,EAAE,GAAW,EAAE,EAAE,CACzE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1E,OAAO;QACL,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACnB,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,OAAO;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACzD,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1D,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,SAAS,YAAY,CAAC,IAA6B;IACjD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}