@ouispec/agent-realtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Closure Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @ouispec/agent-realtime
+
+The realtime server for agent turns and UI actions. One implementation serves every product (ADR-0227). It does six things:
+
+- **Carries events.** Turn events, UI action dispatches and the product's own events reach rooms through the internal emit API.
+- **Holds UI action results.** It keeps each browser's answer to a UI action for the agent worker that asked (ADR-0209). Answers are shared across instances through Redis.
+- **Keeps approvals.** An irreversible action runs only on an approval the user gave, bound to the exact call by a single-use token (ADR-0228).
+- **Signs and checks room tokens.** A room token admits one user to one room.
+- **Checks client events.** It accepts only the client events it declares, and puts each one through a chain: rate limit, size cap, schema, then authorization against the verified identity.
+- **Restricts relays.** A client can relay only allow-listed events, and only into rooms its socket has joined.
+
+## What the product supplies
+
+Every seam is required. When one is missing, the server fails at start-up and names it. No seam defaults to another product's value.
+
+| Seam | Config | What it is |
+|---|---|---|
+| Auth verifier | `auth` | `AuthAdapter.verify(token)`. It verifies your users' tokens once per socket and returns `{ userId, accountId?, platformAdmin?, metadata? }`. |
+| Room policy | `roomPolicy` | `isValidRoom`, `identityRooms` (the rooms a socket joins on connect and can never leave), `requiresToken`, and `canJoin` for the rooms that need no token. |
+| Internal key | `internalApiKey` | Guards `/api/emit` and `/internal/*`. Use one per environment, kept in your secret store. |
+| Room-token secret | `roomTokens.secret` | Signs room tokens with HMAC-SHA256. It must be at least 32 characters and must differ from the internal key. `ttlMs` is optional and defaults to 15 minutes. |
+| Approval signing key | `approvals.signingKey` | Signs approval tokens (compact JWS, HS256). It must be at least 32 characters and differ from the internal key and the room-token secret. Use one per environment; an engine that verifies approval tokens holds this key and nothing else. |
+| Redis | `redis` | `{ host, port, tls }`. UI action results and room fan-out cross instances here. |
+| CORS origins | `corsOrigins` | The browser origins allowed to connect. Pass `['*']` only on purpose. |
+| Port | `port` | The port to listen on. `0` picks a free one. |
+
+Optional:
+- `events`: your event declarations, with the platform's own: `createEventCatalog(PLATFORM_EVENTS, yourEvents)` from `@ouispec/agent-events` (see below).
+- `relay`: the client-relayable events, each with a room prefix and a data schema. With `events`, the declaration supplies both, so `{}` is enough; the event must be a declared `notice` that does not go to a turn's room.
+- `clientEvents`: your own declared events, built with `defineClientEvent`.
+- `logger`: a pino-shaped logger.
+- `pingInterval` and `pingTimeout`.
+
+## Room tokens: the product decides, the server signs
+
+A room that `requiresToken` is joined only with a token binding this user to this exact room. Minting one takes two steps:
+
+1. The browser asks your API for a token. Your API runs the resource's own read authorization, the same check its GET route applies.
+2. Only if that check passes does your API call `POST /internal/room-token` with `{ userId, room }` and the internal key. The response is `{ token, expiresInMs }`, and your API returns the token to the browser.
+
+The browser then joins with `socket.emit('subscribe', { rooms: [room], tokens: { [room]: token } }, ack)`. A room joined by identity is refused a token.
+
+## Declared events
+
+Pass `events` and the server follows your declarations (ADR-0227 §2.4):
+
+- **Emit.** `/api/emit` sends only a declared event, with a payload its schema accepts, into rooms it is declared for. Anything else is refused with `400 { error }` and logged as `Emit refused` with the event, the rooms and the reason. A declared event is never broadcast.
+- **Relay.** A client relays only an event you list in `relay` that is declared as a `notice`. Its declaration decides the rooms and the data it may carry. Listing a completion, failure, progress or turn event fails at start-up.
+- **Settlements.** Every declared completion or failure you emit settles one job: the job of its kind whose id is in its correlation field. The first is kept for 35 minutes, shared across instances, so a worker can wait for a job to end without joining a room (`createHttpEventWaiter` in `@ouispec/agent-worker`).
+
+The platform's own events (the worker's turn events and OUI's UI action dispatch) are declared in `PLATFORM_EVENTS`, so they pass the same checks.
+
+## Internal endpoints
+
+All of them require the `x-api-key` header.
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /api/emit` `{ event, data, rooms? }` | Sends a server event to rooms. With no `rooms`, it goes to every socket. |
+| `POST /internal/room-token` `{ userId, room }` | Signs a room token (see above). |
+| `GET /internal/oui/action-results/:requestId?userId=&waitMs=&final=1` | Returns the browser's answer to a UI action. The first answer wins. With `final=1` you get an async action's final answer instead. Answers are returned only to the turn's own user. `200` carries the result; `204` means not yet, so ask again. A wait lasts at most 25 s. |
+| `POST /internal/approvals` | Stores a pending approval (the worker, or a conversation engine). `201`; `400` for a bad body, a hash that does not match the arguments, or an expiry more than 30 minutes away; `409` for an id already stored. |
+| `POST /internal/approvals/:id/decide` `{ userId, decision, channel }` | A conversation channel's decision (`voice`, `phone`, `sms`, `chat`), made by the engine for the session's user. A `ui` decision is refused here: in a UI only the user's click counts. |
+| `POST /internal/approvals/redeem` `{ token, userId, conversationId }` | Atomic single use. `200 { call }` returns exactly the stored call. `403` for a token this environment did not sign, another user's or conversation's, or one not for the stored call; `410` for an expired or already used one. |
+| `GET /internal/approvals/:id?userId=` | Where an approval of this user's stands: `pending`, `approved` or `declined` (remembered for 30 minutes). |
+| `GET /internal/events/settlements/:kind/:id?waitMs=` | How a job of a declared kind ended: `{ kind, role, event, id, payload }`, with `role` `completion` or `failure`. `204` means not yet; `400` an undeclared kind; `404` a server without `events`. A wait lasts at most 25 s. |
+| `GET /health` | Returns `200` with connection and pending-wait counts. No key needed. |
+
+## Approvals (ADR-0228)
+
+1. The worker stops the turn at a call that needs approval, stores it with `POST /internal/approvals`, and emits `agent:approval_required` with the preview.
+2. The user clicks the approval card. Their socket sends `approval:decide { approvalId, decision }`, a declared client event. The store checks that the socket's verified user is the approval's own. An approval's token is answered only to that socket, in the ack: `{ ok: true, decision: 'approve', token, argsHash, expiresAt }`.
+3. The next turn carries the token outside the message text. The worker redeems it, and the store returns the stored call exactly once.
+
+A declined approval is deleted and remembered for the next turn. Every issue, decision and redemption is logged with the approval id, user, tool, effect, channel and args hash. The arguments are logged only when their declaration marks them not sensitive, and a token never is.
+
+The token's claims are `aid sub cid tool ah eff ch iat exp jti`. `ah` is `argsHash(args)` from `@ouispec/agent-core`: SHA-256 over the RFC 8785 canonical JSON. The package ships `approval-vectors.json`, which every other implementation must match.
+
+## Example
+
+```ts
+import { createRealtimeServer } from '@ouispec/agent-realtime';
+
+const server = await createRealtimeServer({
+  auth: { verify: (token) => verifyMyUser(token) },
+  roomPolicy: {
+    isValidRoom: (room) => /^member:[\w-]+$|^chat:turn:[\w-]+$/.test(room),
+    identityRooms: (user) => [`member:${user.userId}`],
+    requiresToken: (room) => room.startsWith('chat:turn:'),
+    canJoin: (room, user) => room === `member:${user.userId}`,
+  },
+  internalApiKey: secrets.realtimeInternalKey,
+  roomTokens: { secret: secrets.roomTokenSecret },
+  approvals: { signingKey: secrets.approvalSigningKey },
+  redis: { host: env.REDIS_HOST, port: 6379, tls: true },
+  corsOrigins: ['https://app.example.com'],
+  port: 3331,
+});
+```
+
+## Testing
+
+`@ouispec/agent-realtime/testing` exports `startTestRedis()`. If `REDIS_URL` is set it uses that Redis. Otherwise it starts a private `redis-server` on a free port. If neither is available, it fails.

package/dist/approvals/client-event.d.ts

@@ -0,0 +1,4 @@
+import { type ClientEvent } from '../client-events/chain.js';
+import type { ApprovalStore } from './store.js';
+export declare function createApprovalDecideEvent(approvals: () => ApprovalStore): ClientEvent;
+//# sourceMappingURL=client-event.d.ts.map

package/dist/approvals/client-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-event.d.ts","sourceRoot":"","sources":["../../src/approvals/client-event.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,aAAa,GAAG,WAAW,CAcrF"}

package/dist/approvals/client-event.js

@@ -0,0 +1,25 @@
+/**
+ * `approval:decide` (ADR-0228 §2.2.3): the user's click on the approval card,
+ * on their own authenticated socket. The decider is the socket's verified
+ * identity, never one the payload names, and an approval's token is answered
+ * only to this socket, in the event's ack.
+ */
+import { APPROVAL_DECIDE_EVENT } from '@ouispec/agent-core';
+import { defineClientEvent } from '../client-events/chain.js';
+import { decidePayloadSchema } from './schemas.js';
+export function createApprovalDecideEvent(approvals) {
+    return defineClientEvent({
+        name: APPROVAL_DECIDE_EVENT,
+        schema: decidePayloadSchema,
+        maxBytes: 1024,
+        // A person clicks; a burst is a script.
+        rate: { perSecond: 2, burst: 5 },
+        // Scoped by construction: the store decides only an approval whose user is this socket's.
+        refusal: (reason) => ({ ok: false, reason: 'invalid', error: reason }),
+        handle: async ({ user }, payload, ack) => {
+            const result = await approvals().decide(payload.approvalId, { userId: user.userId, decision: payload.decision, channel: 'ui' });
+            ack?.(result);
+        },
+    });
+}
+//# sourceMappingURL=client-event.js.map

package/dist/approvals/client-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-event.js","sourceRoot":"","sources":["../../src/approvals/client-event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,qBAAqB,EAAoD,MAAM,qBAAqB,CAAC;AAC9G,OAAO,EAAE,iBAAiB,EAAoB,MAAM,2BAA2B,CAAC;AAEhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,UAAU,yBAAyB,CAAC,SAA8B;IACtE,OAAO,iBAAiB,CAAwB;QAC9C,IAAI,EAAE,qBAAqB;QAC3B,MAAM,EAAE,mBAAmB;QAC3B,QAAQ,EAAE,IAAI;QACd,wCAAwC;QACxC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QAChC,0FAA0F;QAC1F,OAAO,EAAE,CAAC,MAAM,EAAmB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QACvF,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;YACvC,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAChI,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QAChB,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/approvals/routes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The approval store's internal endpoints (ADR-0228 §2.4). Each requires the
+ * internal key: they are for the product's agent worker and a conversation
+ * engine, never a browser. A browser decides only through `approval:decide`
+ * on its own authenticated socket.
+ *
+ *   POST /internal/approvals               store a pending approval (worker, engine)
+ *   POST /internal/approvals/:id/decide    a conversation channel's decision (engine)
+ *   POST /internal/approvals/redeem        atomic single use (worker, engine)
+ *   GET  /internal/approvals/:id?userId=   where an approval stands (worker, for the turn after a decision)
+ */
+import { Router } from 'express';
+import type { ApprovalStore } from './store.js';
+export interface ApprovalRouteDeps {
+    approvals: ApprovalStore;
+    isInternalKey: (presented: string | undefined) => boolean;
+}
+export declare function approvalRouter(deps: ApprovalRouteDeps): Router;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/approvals/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAA+B,MAAM,SAAS,CAAC;AAG9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,aAAa,CAAC;IACzB,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;CAC3D;AAkBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAyE9D"}

package/dist/approvals/routes.js

@@ -0,0 +1,100 @@
+/**
+ * The approval store's internal endpoints (ADR-0228 §2.4). Each requires the
+ * internal key: they are for the product's agent worker and a conversation
+ * engine, never a browser. A browser decides only through `approval:decide`
+ * on its own authenticated socket.
+ *
+ *   POST /internal/approvals               store a pending approval (worker, engine)
+ *   POST /internal/approvals/:id/decide    a conversation channel's decision (engine)
+ *   POST /internal/approvals/redeem        atomic single use (worker, engine)
+ *   GET  /internal/approvals/:id?userId=   where an approval stands (worker, for the turn after a decision)
+ */
+import { Router } from 'express';
+import { internalDecideSchema, pendingApprovalSchema, redeemSchema } from './schemas.js';
+const DECIDE_STATUS = {
+    unknown: 404,
+    forbidden: 403,
+    expired: 410,
+    decided: 409,
+    used: 410,
+    invalid: 400,
+    mismatch: 403,
+    channel: 400,
+};
+const REDEEM_STATUS = {
+    ...DECIDE_STATUS,
+    invalid: 403,
+    unknown: 410,
+};
+export function approvalRouter(deps) {
+    const router = Router();
+    const accept = (req, res, schema) => {
+        if (!deps.isInternalKey(req.headers['x-api-key'])) {
+            res.status(401).json({ error: 'Invalid or missing API key' });
+            return null;
+        }
+        const { value, error } = schema.validate(req.body ?? {}, { abortEarly: true, convert: false });
+        if (error) {
+            res.status(400).json({ error: `invalid body: ${error.message}`, reason: 'invalid' });
+            return null;
+        }
+        return value;
+    };
+    router.post('/internal/approvals/redeem', async (req, res) => {
+        const body = accept(req, res, redeemSchema);
+        if (!body)
+            return;
+        const result = await deps.approvals.redeem(body.token, { userId: body.userId, conversationId: body.conversationId });
+        if (!result.ok) {
+            res.status(REDEEM_STATUS[result.reason]).json({ error: result.error, reason: result.reason });
+            return;
+        }
+        res.json({ call: result.call });
+    });
+    router.post('/internal/approvals', async (req, res) => {
+        const body = accept(req, res, pendingApprovalSchema);
+        if (!body)
+            return;
+        const result = await deps.approvals.create(body);
+        if (!result.ok) {
+            res.status(result.reason === 'decided' ? 409 : 400).json({ error: result.error, reason: result.reason });
+            return;
+        }
+        res.status(201).json({ approvalId: result.approvalId, argsHash: result.argsHash, expiresAt: result.expiresAt });
+    });
+    router.post('/internal/approvals/:id/decide', async (req, res) => {
+        const body = accept(req, res, internalDecideSchema);
+        if (!body)
+            return;
+        // In a UI only the user's click counts, and it arrives on their own socket.
+        if (body.channel === 'ui') {
+            res.status(400).json({ error: 'a UI approval is decided only on the user’s own socket (approval:decide)', reason: 'channel' });
+            return;
+        }
+        const result = await deps.approvals.decide(req.params.id, body);
+        if (!result.ok) {
+            res.status(DECIDE_STATUS[result.reason]).json({ error: result.error, reason: result.reason });
+            return;
+        }
+        res.json(result);
+    });
+    router.get('/internal/approvals/:id', async (req, res) => {
+        if (!deps.isInternalKey(req.headers['x-api-key'])) {
+            res.status(401).json({ error: 'Invalid or missing API key' });
+            return;
+        }
+        const userId = typeof req.query.userId === 'string' ? req.query.userId : '';
+        if (!userId) {
+            res.status(400).json({ error: 'userId is required' });
+            return;
+        }
+        const status = await deps.approvals.status(req.params.id, userId);
+        if (!status) {
+            res.status(404).json({ error: 'no such approval for this user', reason: 'unknown' });
+            return;
+        }
+        res.json(status);
+    });
+    return router;
+}
+//# sourceMappingURL=routes.js.map

package/dist/approvals/routes.js.map

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

package/dist/approvals/schemas.d.ts

@@ -0,0 +1,7 @@
+/** The shapes the approval endpoints and the `approval:decide` event accept. Unknown keys are refused. */
+import Joi from 'joi';
+export declare const pendingApprovalSchema: Joi.ObjectSchema<any>;
+export declare const decidePayloadSchema: Joi.ObjectSchema<any>;
+export declare const internalDecideSchema: Joi.ObjectSchema<any>;
+export declare const redeemSchema: Joi.ObjectSchema<any>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/approvals/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/approvals/schemas.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,OAAO,GAAG,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,qBAAqB,uBAsBhC,CAAC;AAEH,eAAO,MAAM,mBAAmB,uBAG9B,CAAC;AAEH,eAAO,MAAM,oBAAoB,uBAM/B,CAAC;AAEH,eAAO,MAAM,YAAY,uBAIvB,CAAC"}

package/dist/approvals/schemas.js

@@ -0,0 +1,45 @@
+/** The shapes the approval endpoints and the `approval:decide` event accept. Unknown keys are refused. */
+import Joi from 'joi';
+import { APPROVAL_CHANNELS, ARGS_HASH_PATTERN } from '@ouispec/agent-core';
+const id = Joi.string().min(1).max(200);
+const text = (max) => Joi.string().max(max);
+export const pendingApprovalSchema = Joi.object({
+    approvalId: id.required(),
+    toolCallId: id.required(),
+    conversationId: id.required(),
+    turnId: id.required(),
+    userId: id.required(),
+    tool: id.required(),
+    args: Joi.object().unknown(true).required(),
+    argsHash: Joi.string().pattern(ARGS_HASH_PATTERN).required(),
+    effect: Joi.string().min(1).max(64).required(),
+    destructive: Joi.boolean().required(),
+    argsSensitive: Joi.boolean().required(),
+    expiresAt: Joi.number().integer().positive().required(),
+    preview: Joi.object({
+        title: text(500).min(1).required(),
+        consequence: text(2000),
+        arguments: Joi.array()
+            .items(Joi.object({ name: text(200).required(), label: text(500).required(), value: text(4000).allow('').required() }))
+            .max(50)
+            .required(),
+        readback: text(8000).allow('').required(),
+    }).required(),
+});
+export const decidePayloadSchema = Joi.object({
+    approvalId: id.required(),
+    decision: Joi.string().valid('approve', 'decline').required(),
+});
+export const internalDecideSchema = Joi.object({
+    userId: id.required(),
+    decision: Joi.string().valid('approve', 'decline').required(),
+    channel: Joi.string()
+        .valid(...APPROVAL_CHANNELS)
+        .required(),
+});
+export const redeemSchema = Joi.object({
+    token: Joi.string().max(4096).required(),
+    userId: id.required(),
+    conversationId: id.required(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/approvals/schemas.js.map

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

package/dist/approvals/store.d.ts

@@ -0,0 +1,33 @@
+import { type ApprovalChannel, type ApprovalDecideResult, type ApprovalDecision, type ApprovalRedeemResult, type ApprovalRefusal, type ApprovalStatus, type PendingApprovalInput } from '@ouispec/agent-core';
+import type { RealtimeLogger } from '../logger.js';
+import type { ApprovalTokenSigner } from './token.js';
+/** The Redis command the store uses. ioredis satisfies it. */
+export interface ApprovalRedis {
+    eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
+}
+export interface ApprovalStore {
+    /** Keep a pending approval until it expires. */
+    create(input: PendingApprovalInput): Promise<{
+        ok: true;
+        approvalId: string;
+        argsHash: string;
+        expiresAt: number;
+    } | ApprovalRefusal>;
+    /** The user's decision. An approval's token is returned only here, to the decider. */
+    decide(approvalId: string, by: {
+        userId: string;
+        decision: ApprovalDecision;
+        channel: ApprovalChannel;
+    }): Promise<ApprovalDecideResult>;
+    /** Atomic single use: the stored call, for a valid, unexpired, unused token of this user and conversation. */
+    redeem(token: string, caller: {
+        userId: string;
+        conversationId: string;
+    }): Promise<ApprovalRedeemResult>;
+    /** Where an approval of this user's stands, or null when it is not theirs or not known. */
+    status(approvalId: string, userId: string): Promise<ApprovalStatus | null>;
+}
+/** How long a decline is remembered for the turn that follows it. */
+export declare const DECLINED_TTL_SEC: number;
+export declare function createApprovalStore(redis: ApprovalRedis, signer: ApprovalTokenSigner, logger: RealtimeLogger): ApprovalStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/approvals/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/approvals/store.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EAEpB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1F;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,CAAC,CAAC;IACtI,sFAAsF;IACtF,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,eAAe,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACxI,8GAA8G;IAC9G,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzG,2FAA2F;IAC3F,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC5E;AAED,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,QAAU,CAAC;AA4ExC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,aAAa,CAmK5H"}

package/dist/approvals/store.js

@@ -0,0 +1,206 @@
+/**
+ * The approval store (ADR-0228 §2.4), beside the UI action result store and on
+ * the same Redis, so every realtime instance sees every approval:
+ *
+ *   approval:{id}           → the pending call as the worker stored it (JSON,
+ *                             never rewritten), TTL until it expires
+ *   approval:{id}:state     → hash: status (pending | approved), userId,
+ *                             conversationId, tool, argsHash, expiresAt, and
+ *                             once approved the token's jti and the channel
+ *   approval:declined:{id}  → what the next turn tells the model, 30 min
+ *
+ * Each decision and each redemption is one Lua script, so two instances can
+ * never both approve one call, or both redeem one token. The stored call is
+ * kept as the worker wrote it and never re-encoded inside Redis: Lua's JSON
+ * would round numbers and turn `[]` into `{}`, and the redeemed call must be
+ * exactly the one the user approved.
+ */
+import crypto from 'node:crypto';
+import { argsHash as hashOf, MAX_APPROVAL_TTL_MS, } from '@ouispec/agent-core';
+/** How long a decline is remembered for the turn that follows it. */
+export const DECLINED_TTL_SEC = 30 * 60;
+const recordKey = (id) => `approval:${id}`;
+const stateKey = (id) => `approval:${id}:state`;
+const declinedKey = (id) => `approval:declined:${id}`;
+// KEYS: record, state, declined. ARGV: record JSON, ttl ms, userId, conversationId, tool, argsHash, expiresAt.
+// A new approval supersedes an old decline under the same id.
+const CREATE = `
+if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[2]) == 1 then return 'exists' end
+redis.call('DEL', KEYS[3])
+redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[2])
+redis.call('HSET', KEYS[2], 'status', 'pending', 'userId', ARGV[3], 'conversationId', ARGV[4], 'tool', ARGV[5], 'argsHash', ARGV[6], 'expiresAt', ARGV[7])
+redis.call('PEXPIRE', KEYS[2], ARGV[2])
+return 'ok'`;
+// KEYS: state, record, declined. ARGV: userId, decision, now ms, jti, channel, declined ttl s, declined JSON.
+const DECIDE = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return {'unknown'} end
+local s = redis.call('HMGET', KEYS[1], 'status', 'userId', 'expiresAt')
+if s[2] ~= ARGV[1] then return {'forbidden'} end
+if s[1] ~= 'pending' then return {'decided'} end
+if tonumber(ARGV[3]) >= tonumber(s[3]) then return {'expired'} end
+local record = redis.call('GET', KEYS[2])
+if ARGV[2] == 'approve' then
+  redis.call('HSET', KEYS[1], 'status', 'approved', 'jti', ARGV[4], 'channel', ARGV[5])
+  return {'approved', record}
+end
+redis.call('DEL', KEYS[1], KEYS[2])
+redis.call('SET', KEYS[3], ARGV[7], 'EX', ARGV[6])
+return {'declined', record}`;
+// KEYS: state, record. ARGV: jti, argsHash, tool, userId, conversationId.
+const REDEEM = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return {'used'} end
+local s = redis.call('HMGET', KEYS[1], 'status', 'jti', 'argsHash', 'tool', 'userId', 'conversationId', 'channel')
+if s[1] ~= 'approved' or s[2] ~= ARGV[1] or s[3] ~= ARGV[2] or s[4] ~= ARGV[3] or s[5] ~= ARGV[4] or s[6] ~= ARGV[5] then
+  return {'mismatch'}
+end
+local record = redis.call('GET', KEYS[2])
+redis.call('DEL', KEYS[1], KEYS[2])
+return {'ok', record, s[7]}`;
+// KEYS: state, record, declined. ARGV: userId. A live approval first, then a remembered decline.
+const STATUS = `
+if redis.call('EXISTS', KEYS[1]) == 1 then
+  local s = redis.call('HMGET', KEYS[1], 'status', 'userId')
+  if s[2] ~= ARGV[1] then return {'unknown'} end
+  return {s[1], redis.call('GET', KEYS[2])}
+end
+local d = redis.call('GET', KEYS[3])
+if d then return {'declined', d} end
+return {'unknown'}`;
+const refusal = (reason, error) => ({ ok: false, reason, error });
+const REFUSALS = {
+    unknown: 'no such approval is waiting: it was never asked for, was already decided and used, or has expired',
+    forbidden: "this approval is another user's",
+    decided: 'this approval has already been decided',
+    expired: 'this approval has expired',
+    used: 'this approval has already been used',
+    mismatch: 'this token is not for the stored call',
+};
+export function createApprovalStore(redis, signer, logger) {
+    /** An approval as this user may see it. */
+    async function read(approvalId, userId) {
+        const [status, raw] = ((await redis.eval(STATUS, 3, stateKey(approvalId), recordKey(approvalId), declinedKey(approvalId), userId)) ??
+            []);
+        if (status === 'declined' && raw)
+            return { kind: 'declined', declined: JSON.parse(raw) };
+        if ((status === 'pending' || status === 'approved') && raw)
+            return { kind: 'open', status, pending: JSON.parse(raw) };
+        return { kind: 'unknown' };
+    }
+    /** What every log record about an approval carries; the arguments only when their declaration says they are not sensitive. */
+    const audit = (p, extra = {}) => ({
+        approvalId: p.approvalId,
+        userId: p.userId,
+        conversationId: p.conversationId,
+        tool: p.tool,
+        effect: p.effect,
+        destructive: p.destructive,
+        argsHash: p.argsHash,
+        ...(p.argsSensitive === false ? { args: p.args } : {}),
+        ...extra,
+    });
+    return {
+        async create(input) {
+            const now = Date.now();
+            if (input.approvalId !== input.toolCallId)
+                return refusal('invalid', 'approvalId must be the tool call id');
+            if (!(input.expiresAt > now))
+                return refusal('invalid', 'expiresAt must be in the future');
+            if (input.expiresAt - now > MAX_APPROVAL_TTL_MS) {
+                return refusal('invalid', `an approval lasts at most ${MAX_APPROVAL_TTL_MS / 60_000} minutes`);
+            }
+            let computed;
+            try {
+                computed = await hashOf(input.args);
+            }
+            catch (err) {
+                return refusal('invalid', err instanceof Error ? err.message : String(err));
+            }
+            if (computed !== input.argsHash)
+                return refusal('invalid', 'argsHash does not match the arguments');
+            const result = await redis.eval(CREATE, 3, recordKey(input.approvalId), stateKey(input.approvalId), declinedKey(input.approvalId), JSON.stringify(input), input.expiresAt - now, input.userId, input.conversationId, input.tool, input.argsHash, input.expiresAt);
+            if (result !== 'ok')
+                return refusal('decided', `an approval ${input.approvalId} already exists`);
+            logger.info(audit(input, { expiresAt: input.expiresAt }), 'Approval stored');
+            return { ok: true, approvalId: input.approvalId, argsHash: input.argsHash, expiresAt: input.expiresAt };
+        },
+        async decide(approvalId, { userId, decision, channel }) {
+            const jti = crypto.randomUUID();
+            // What a decline is remembered by: the call's tool and title, from its
+            // record, which never changes once stored.
+            const seen = await read(approvalId, userId);
+            const declined = {
+                userId,
+                tool: seen.kind === 'open' ? seen.pending.tool : '',
+                title: seen.kind === 'open' ? seen.pending.preview.title : '',
+            };
+            const [outcome, raw] = (await redis.eval(DECIDE, 3, stateKey(approvalId), recordKey(approvalId), declinedKey(approvalId), userId, decision, Date.now(), jti, channel, DECLINED_TTL_SEC, JSON.stringify(declined)));
+            if (outcome !== 'approved' && outcome !== 'declined') {
+                logger.warn({ approvalId, userId, decision, channel, reason: outcome }, 'Approval decision refused');
+                return refusal(outcome, REFUSALS[outcome] ?? outcome);
+            }
+            const pending = JSON.parse(raw);
+            if (outcome === 'declined') {
+                logger.info(audit(pending, { channel }), 'Approval declined');
+                return { ok: true, decision: 'decline', approvalId };
+            }
+            const token = signer.sign({
+                aid: approvalId,
+                sub: pending.userId,
+                cid: pending.conversationId,
+                tool: pending.tool,
+                ah: pending.argsHash,
+                eff: pending.effect,
+                ch: channel,
+                iat: Math.floor(Date.now() / 1000),
+                exp: Math.floor(pending.expiresAt / 1000),
+                jti,
+            });
+            logger.info(audit(pending, { channel, expiresAt: pending.expiresAt }), 'Approval approved');
+            return { ok: true, decision: 'approve', approvalId, token, argsHash: pending.argsHash, expiresAt: pending.expiresAt, channel };
+        },
+        async redeem(token, caller) {
+            const checked = signer.verify(token);
+            if (!checked.ok) {
+                logger.warn({ userId: caller.userId, conversationId: caller.conversationId, reason: checked.reason, error: checked.error }, 'Approval redemption refused');
+                return refusal(checked.reason, checked.reason === 'expired' ? REFUSALS.expired : `not a valid approval token: ${checked.error}`);
+            }
+            const { claims } = checked;
+            const context = { approvalId: claims.aid, userId: caller.userId, tool: claims.tool, effect: claims.eff, channel: claims.ch, argsHash: claims.ah };
+            if (claims.sub !== caller.userId || claims.cid !== caller.conversationId) {
+                logger.warn({ ...context, tokenUser: claims.sub, reason: 'forbidden' }, 'Approval redemption refused');
+                return refusal('forbidden', "this approval is another user's or another conversation's");
+            }
+            const [outcome, raw, channel] = (await redis.eval(REDEEM, 2, stateKey(claims.aid), recordKey(claims.aid), claims.jti, claims.ah, claims.tool, claims.sub, claims.cid));
+            if (outcome !== 'ok') {
+                logger.warn({ ...context, reason: outcome }, 'Approval redemption refused');
+                return refusal(outcome, REFUSALS[outcome] ?? outcome);
+            }
+            const p = JSON.parse(raw);
+            const call = {
+                approvalId: p.approvalId,
+                toolCallId: p.toolCallId,
+                conversationId: p.conversationId,
+                turnId: p.turnId,
+                userId: p.userId,
+                tool: p.tool,
+                args: p.args,
+                argsHash: p.argsHash,
+                effect: p.effect,
+                destructive: p.destructive,
+                channel: channel,
+            };
+            logger.info(audit(p, { channel }), 'Approval redeemed');
+            return { ok: true, call };
+        },
+        async status(approvalId, userId) {
+            const seen = await read(approvalId, userId);
+            if (seen.kind === 'declined') {
+                return seen.declined.userId === userId ? { approvalId, status: 'declined', tool: seen.declined.tool, title: seen.declined.title } : null;
+            }
+            if (seen.kind === 'open')
+                return { approvalId, status: seen.status, tool: seen.pending.tool, title: seen.pending.preview.title };
+            return null;
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/approvals/store.js.map

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