@ouispec/agent-core 0.15.0 → 0.17.0

package/README.md

@@ -11,4 +11,26 @@ It has no runtime of its own. `@ouispec/agent-worker` (the agent), `@ouispec/age
 - The turn events come from `@ouispec/agent-events`, and the approval messages from `@ouispec/contract`'s `approvals.json`.
 - `argsHash` and the approval rules are `oui-spec`'s. `@ouispec/agent-core/approval-vectors.json` re-exports its test vectors, so an engine in another language can hold its own hash to them.
 
+## Verifying an approval receipt
+
+A tool's own API refuses an irreversible request no user approved with `verifyApprovalReceipt`. The realtime server signs a receipt when it redeems an approval, and the worker sends it on the approved call as the `OUI-Approval-Receipt` header (`APPROVAL_RECEIPT_HEADER`). The function runs on WebCrypto, the same in Node and in the browser build.
+
+```ts
+import { APPROVAL_RECEIPT_HEADER, argsHash, verifyApprovalReceipt } from '@ouispec/agent-core';
+
+const checked = await verifyApprovalReceipt(request.headers.get(APPROVAL_RECEIPT_HEADER) ?? '', {
+  jwks: 'https://realtime.example.com/.well-known/oui-approval-jwks.json', // or the JWKS document itself
+  expectedArgsHash: await argsHash(toolInput), // the call as you received it
+  audience: 'https://api.example.com', // your own origin
+});
+// { ok: true, claims } or { ok: false, reason, error }
+```
+
+- `expectedArgsHash`: for a generated API tool, the tool's input as the worker's executor received it, one object holding every path, query and body parameter by its declared name; for an operation whose input is its body, that body.
+- `jwks` as a URL is fetched, cached for the response's `max-age`, and fetched again when a receipt names a key id it lacks, at most once a minute. A key set that cannot be read refuses with `key`.
+- It checks, in order: the header (`alg` `EdDSA`, `typ` `oui-approval-receipt+jwt`, a `kid`, no `crit`), a published key with that id, the signature, the claims' shape, `exp` and `iat` with 60 s of clock skew, `aud`, then `argsHash`. The refusal reasons are `malformed`, `key`, `signature`, `expired`, `audience` and `args`.
+- **Single use is yours.** The receipt's `jti` is the call's idempotency key. Record each one you act on for at least two minutes, and answer a repeat with the first result, or refuse it.
+
+Any JOSE library verifies a receipt too: accept only `EdDSA` with this `typ`, read the key from the JWKS by `kid`, and then check `exp`, `aud` and `argsHash` as above. `@ouispec/agent-core/receipt-vectors.json` holds receipts, the keys they were signed with, and the result each must give, for an implementation in any language.
+
 See [the integrator guide](https://github.com/wesreid/oui/blob/main/packages/contract/INTEGRATOR-GUIDE.md) for how the pieces fit, and [VERSIONING.md](https://github.com/wesreid/oui/blob/main/VERSIONING.md) for what a release may change.

package/dist/approvals/index.d.ts

@@ -1,3 +1,4 @@
 export * from './args-hash.js';
 export * from './types.js';
+export * from './receipt.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/approvals/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/approvals/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/approvals/index.js

@@ -1,3 +1,4 @@
 export * from './args-hash.js';
 export * from './types.js';
+export * from './receipt.js';
 //# sourceMappingURL=index.js.map

package/dist/approvals/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/approvals/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/approvals/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/approvals/receipt.d.ts

@@ -0,0 +1,127 @@
+import type { ApprovalReceiptClaims } from '@ouispec/contract';
+/**
+ * The approval receipt: what the tool's own API checks to know that the call
+ * it received is one a person approved.
+ *
+ * When the realtime server redeems an approval token it signs a receipt, a
+ * compact JWS over Ed25519 with a key only it holds, and the worker carries it
+ * on the approved call (`OUI-Approval-Receipt`). The tool holds only the
+ * public keys, published at `<iss>/.well-known/oui-approval-jwks.json`, so it
+ * can verify a receipt and never make one. The receipt names the one API it is
+ * for (`aud`), the call's args hash, and lasts 120 seconds; its `jti` is the
+ * call's idempotency key, which the tool acts on at most once.
+ *
+ * `verifyApprovalReceipt` is the same in Node and in the browser build: it
+ * runs on WebCrypto. `@ouispec/agent-core/receipt-vectors.json` holds every
+ * other implementation, in any language, to the results it gives.
+ */
+/** The receipt's JWS `typ`. A verifier accepts no other. */
+export declare const APPROVAL_RECEIPT_TYP = "oui-approval-receipt+jwt";
+/** The receipt's JWS `alg`: EdDSA over Ed25519. A verifier accepts no other, and never `none`. */
+export declare const APPROVAL_RECEIPT_ALG = "EdDSA";
+/** The request header an approved call carries its receipt in. */
+export declare const APPROVAL_RECEIPT_HEADER = "OUI-Approval-Receipt";
+/** Where, under the realtime server's public base URL (`iss`), its receipt keys are published. */
+export declare const APPROVAL_RECEIPT_JWKS_PATH = "/.well-known/oui-approval-jwks.json";
+/** How long a receipt lasts: the request that runs right after redemption, and one retry. */
+export declare const APPROVAL_RECEIPT_TTL_SEC = 120;
+/** The clock skew a verifier allows on `iat` and `exp`. */
+export declare const APPROVAL_RECEIPT_CLOCK_SKEW_SEC = 60;
+/** How long the published keys may be cached (`Cache-Control: public, max-age=3600`). */
+export declare const APPROVAL_RECEIPT_JWKS_MAX_AGE_SEC = 3600;
+/** A verifier that meets a key id it does not know fetches the keys again, at most this often. */
+export declare const APPROVAL_RECEIPT_JWKS_REFETCH_MS = 60000;
+/**
+ * Why a receipt was refused, in the order the verifier checks:
+ *
+ * - `malformed`: not a compact JWS; a header that is not exactly EdDSA with
+ *   this `typ` and a `kid`, or that names `crit`; or claims that are not a
+ *   receipt's.
+ * - `key`: no published key has its `kid` (a removed key, or another
+ *   environment's), or the keys could not be read.
+ * - `signature`: the signature is not that key's over this header and these claims.
+ * - `expired`: past `exp`, or issued in the future, beyond the clock skew.
+ * - `audience`: issued for another API.
+ * - `args`: issued for other arguments than the request carries.
+ */
+export type ApprovalReceiptRefusalReason = 'malformed' | 'key' | 'signature' | 'expired' | 'audience' | 'args';
+export declare const APPROVAL_RECEIPT_REFUSAL_REASONS: readonly ApprovalReceiptRefusalReason[];
+/** One published receipt key: an Ed25519 public key as a JWK. */
+export interface ApprovalReceiptPublicJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    /** The public key, base64url. */
+    x: string;
+    kid: string;
+    alg?: 'EdDSA';
+    use?: 'sig';
+}
+/** The realtime server's published receipt keys. */
+export interface ApprovalReceiptJwks {
+    keys: ApprovalReceiptPublicJwk[];
+}
+export type ApprovalReceiptVerification = {
+    ok: true;
+    claims: ApprovalReceiptClaims;
+} | {
+    ok: false;
+    reason: ApprovalReceiptRefusalReason;
+    error: string;
+};
+export interface VerifyApprovalReceiptOptions {
+    /**
+     * The realtime server's published keys: the JWKS document, or its URL
+     * (`<iss>/.well-known/oui-approval-jwks.json`). Given a URL, the keys are
+     * fetched, cached for the response's `max-age`, and fetched again when a
+     * receipt names a key id they lack, at most once a minute.
+     */
+    jwks: ApprovalReceiptJwks | string | URL;
+    /**
+     * `argsHash` of the call as the tool received it. For a generated API tool:
+     * one object holding every path, query and body parameter by its declared
+     * name; for an operation whose input is its body, that body.
+     */
+    expectedArgsHash: string;
+    /** The tool's own origin (scheme, host and port), which the receipt must name as `aud`. */
+    audience: string;
+    /** The time to check against, epoch ms. Default: now. */
+    now?: number;
+    /** The fetch the keys are read with, when `jwks` is a URL. Default: the global fetch. */
+    fetch?: typeof fetch;
+}
+/** base64url → bytes, without padding, on any runtime. */
+export declare function base64UrlToBytes(value: string): Uint8Array;
+/** bytes → base64url, without padding, on any runtime. */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+/**
+ * The origin an audience names: scheme, host and port, as `URL.origin` writes
+ * it. One rule for the worker that names an API's audience, the store that
+ * fixes it, and the verifier that compares it. Null when it is not an
+ * absolute http(s) URL with nothing past its origin but a `/`.
+ */
+export declare function approvalReceiptAudience(value: string): string | null;
+/**
+ * What is wrong with a receipt's claims, or null: every required claim of the
+ * right type, no claim it does not define. The signer and the verifier hold a
+ * receipt to this one rule.
+ */
+export declare function approvalReceiptClaimsProblem(claims: unknown): string | null;
+/** The members of a JWK a receipt key is published with: never `d`. */
+export declare function publicReceiptJwk(jwk: {
+    kty?: unknown;
+    crv?: unknown;
+    x?: unknown;
+    kid?: unknown;
+}): ApprovalReceiptPublicJwk;
+/**
+ * Verifies an approval receipt. It checks, in this order: the header (EdDSA,
+ * the receipt `typ`, a key id, no `crit`), that a published key has that id,
+ * the signature, the claims' shape, `exp` and `iat` (60 s of clock skew),
+ * `aud`, then `argsHash`; each failure has its own `reason`. It never throws
+ * for a bad receipt; a JWKS URL that cannot be read refuses with `key`.
+ *
+ * A receipt that verifies is still the tool's to use once: record its `jti`
+ * for at least the receipt's lifetime, and never act twice on one.
+ */
+export declare function verifyApprovalReceipt(jws: string, options: VerifyApprovalReceiptOptions): Promise<ApprovalReceiptVerification>;
+//# sourceMappingURL=receipt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../../src/approvals/receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D;;;;;;;;;;;;;;;GAeG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAC/D,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAC5C,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAC9D,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,wCAAwC,CAAC;AAChF,6FAA6F;AAC7F,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,yFAAyF;AACzF,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,kGAAkG;AAClG,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,4BAA4B,GAAG,WAAW,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE/G,eAAO,MAAM,gCAAgC,EAAE,SAAS,4BAA4B,EAOnF,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,KAAK,CAAC;IACX,GAAG,EAAE,SAAS,CAAC;IACf,iCAAiC;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,KAAK,CAAC;CACb;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,wBAAwB,EAAE,CAAC;CAClC;AAED,MAAM,MAAM,2BAA2B,GACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GAC3C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,4BAA4B,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,IAAI,EAAE,mBAAmB,GAAG,MAAM,GAAG,GAAG,CAAC;IACzC;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAKD,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAO1D;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAI1D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWpE;AAMD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAW3E;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,CAAC,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,wBAAwB,CAE5H;AAuGD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAiEpI"}

package/dist/approvals/receipt.js

@@ -0,0 +1,312 @@
+import { APPROVAL_CHANNELS } from './types.js';
+/**
+ * The approval receipt: what the tool's own API checks to know that the call
+ * it received is one a person approved.
+ *
+ * When the realtime server redeems an approval token it signs a receipt, a
+ * compact JWS over Ed25519 with a key only it holds, and the worker carries it
+ * on the approved call (`OUI-Approval-Receipt`). The tool holds only the
+ * public keys, published at `<iss>/.well-known/oui-approval-jwks.json`, so it
+ * can verify a receipt and never make one. The receipt names the one API it is
+ * for (`aud`), the call's args hash, and lasts 120 seconds; its `jti` is the
+ * call's idempotency key, which the tool acts on at most once.
+ *
+ * `verifyApprovalReceipt` is the same in Node and in the browser build: it
+ * runs on WebCrypto. `@ouispec/agent-core/receipt-vectors.json` holds every
+ * other implementation, in any language, to the results it gives.
+ */
+/** The receipt's JWS `typ`. A verifier accepts no other. */
+export const APPROVAL_RECEIPT_TYP = 'oui-approval-receipt+jwt';
+/** The receipt's JWS `alg`: EdDSA over Ed25519. A verifier accepts no other, and never `none`. */
+export const APPROVAL_RECEIPT_ALG = 'EdDSA';
+/** The request header an approved call carries its receipt in. */
+export const APPROVAL_RECEIPT_HEADER = 'OUI-Approval-Receipt';
+/** Where, under the realtime server's public base URL (`iss`), its receipt keys are published. */
+export const APPROVAL_RECEIPT_JWKS_PATH = '/.well-known/oui-approval-jwks.json';
+/** How long a receipt lasts: the request that runs right after redemption, and one retry. */
+export const APPROVAL_RECEIPT_TTL_SEC = 120;
+/** The clock skew a verifier allows on `iat` and `exp`. */
+export const APPROVAL_RECEIPT_CLOCK_SKEW_SEC = 60;
+/** How long the published keys may be cached (`Cache-Control: public, max-age=3600`). */
+export const APPROVAL_RECEIPT_JWKS_MAX_AGE_SEC = 3600;
+/** A verifier that meets a key id it does not know fetches the keys again, at most this often. */
+export const APPROVAL_RECEIPT_JWKS_REFETCH_MS = 60_000;
+export const APPROVAL_RECEIPT_REFUSAL_REASONS = [
+    'malformed',
+    'key',
+    'signature',
+    'expired',
+    'audience',
+    'args',
+];
+const B64URL = /^[A-Za-z0-9_-]*$/;
+const ARGS_HASH = /^[0-9a-f]{64}$/;
+/** base64url → bytes, without padding, on any runtime. */
+export function base64UrlToBytes(value) {
+    if (!B64URL.test(value) || value.length % 4 === 1)
+        throw new TypeError('not base64url');
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4);
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/** bytes → base64url, without padding, on any runtime. */
+export function bytesToBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * The origin an audience names: scheme, host and port, as `URL.origin` writes
+ * it. One rule for the worker that names an API's audience, the store that
+ * fixes it, and the verifier that compares it. Null when it is not an
+ * absolute http(s) URL with nothing past its origin but a `/`.
+ */
+export function approvalReceiptAudience(value) {
+    if (typeof value !== 'string' || !value)
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    if (url.username || url.password || url.search || url.hash || (url.pathname !== '/' && url.pathname !== ''))
+        return null;
+    return url.origin;
+}
+const REQUIRED_STRINGS = ['iss', 'aud', 'approvalId', 'tool', 'conversationId', 'userId', 'jti'];
+const OPTIONAL_STRINGS = ['operationId', 'accountId'];
+const KNOWN_CLAIMS = new Set([...REQUIRED_STRINGS, ...OPTIONAL_STRINGS, 'argsHash', 'channel', 'iat', 'exp']);
+/**
+ * What is wrong with a receipt's claims, or null: every required claim of the
+ * right type, no claim it does not define. The signer and the verifier hold a
+ * receipt to this one rule.
+ */
+export function approvalReceiptClaimsProblem(claims) {
+    if (!claims || typeof claims !== 'object' || Array.isArray(claims))
+        return 'the claims are not an object';
+    const c = claims;
+    for (const k of REQUIRED_STRINGS)
+        if (typeof c[k] !== 'string' || !c[k])
+            return `claim ${k} is missing`;
+    for (const k of OPTIONAL_STRINGS)
+        if (c[k] !== undefined && (typeof c[k] !== 'string' || !c[k]))
+            return `claim ${k} is not a string`;
+    if (typeof c.argsHash !== 'string' || !ARGS_HASH.test(c.argsHash))
+        return 'claim argsHash is not an args hash';
+    if (!APPROVAL_CHANNELS.includes(c.channel))
+        return 'claim channel is not a channel';
+    for (const k of ['iat', 'exp'])
+        if (!Number.isSafeInteger(c[k]))
+            return `claim ${k} is not a time`;
+    if (c.exp <= c.iat)
+        return 'claim exp is not after iat';
+    for (const k of Object.keys(c))
+        if (!KNOWN_CLAIMS.has(k))
+            return `claim ${k} is not a receipt's`;
+    return null;
+}
+/** The members of a JWK a receipt key is published with: never `d`. */
+export function publicReceiptJwk(jwk) {
+    return { kty: 'OKP', crv: 'Ed25519', x: String(jwk.x), kid: String(jwk.kid), alg: 'EdDSA', use: 'sig' };
+}
+/** Whether a JWK is a receipt verification key: Ed25519, a 32-byte public key, a key id, and no other algorithm or use. */
+function isReceiptKey(jwk) {
+    if (!jwk || typeof jwk !== 'object')
+        return false;
+    const k = jwk;
+    if (k.kty !== 'OKP' || k.crv !== 'Ed25519' || typeof k.kid !== 'string' || !k.kid || typeof k.x !== 'string')
+        return false;
+    if (k.alg !== undefined && k.alg !== APPROVAL_RECEIPT_ALG)
+        return false;
+    if (k.use !== undefined && k.use !== 'sig')
+        return false;
+    try {
+        return base64UrlToBytes(k.x).length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * WebCrypto: global in browsers and Node 19+; Node 18 has it only on
+ * `node:crypto`, imported here by a specifier bundlers leave alone.
+ */
+async function subtleCrypto() {
+    const global = globalThis.crypto?.subtle;
+    if (global)
+        return global;
+    const nodeCrypto = 'node:crypto';
+    try {
+        const mod = (await import(/* @vite-ignore */ nodeCrypto));
+        if (mod.webcrypto?.subtle)
+            return mod.webcrypto.subtle;
+    }
+    catch {
+        // Not Node: fall through to the error below.
+    }
+    throw new Error('[agent-sdk] verifyApprovalReceipt needs WebCrypto (crypto.subtle), which this runtime does not provide');
+}
+/** A JWKS document's receipt keys by key id. Keys of any other kind are ignored, and a kid published twice is refused. */
+function keysById(document) {
+    const keys = document?.keys;
+    if (!Array.isArray(keys))
+        throw new Error('the key set has no "keys" list');
+    const byId = new Map();
+    const doubled = new Set();
+    for (const k of keys) {
+        if (!isReceiptKey(k))
+            continue;
+        if (byId.has(k.kid))
+            doubled.add(k.kid);
+        byId.set(k.kid, k);
+    }
+    // Two keys under one id: neither can be told from the other, so neither is used.
+    for (const kid of doubled)
+        byId.delete(kid);
+    return byId;
+}
+const remoteKeySets = new Map();
+const inflight = new Map();
+function maxAgeSeconds(cacheControl) {
+    if (/(?:^|,)\s*(?:no-store|no-cache)\s*(?:,|$)/i.test(cacheControl ?? ''))
+        return 0;
+    const match = /(?:^|,)\s*max-age\s*=\s*"?(\d+)"?\s*(?:,|$)/i.exec(cacheControl ?? '');
+    return match ? Number(match[1]) : APPROVAL_RECEIPT_JWKS_MAX_AGE_SEC;
+}
+async function fetchKeySet(url, fetchImpl, now) {
+    const running = inflight.get(url);
+    if (running)
+        return running;
+    const reading = (async () => {
+        const res = await fetchImpl(url, { headers: { accept: 'application/json' } });
+        if (!res.ok)
+            throw new Error(`the key set at ${url} answered HTTP ${res.status}`);
+        const document = (await res.json());
+        const set = { keys: keysById(document), freshUntil: now + maxAgeSeconds(res.headers.get('cache-control')) * 1000, fetchedAt: now };
+        remoteKeySets.set(url, set);
+        return set;
+    })();
+    inflight.set(url, reading);
+    try {
+        return await reading;
+    }
+    finally {
+        inflight.delete(url);
+    }
+}
+/** The key a receipt names, from a document or a cached, refreshed URL; null when no published key has that id. */
+async function receiptKey(jwks, kid, fetchImpl, now) {
+    if (typeof jwks !== 'string' && !(jwks instanceof URL))
+        return keysById(jwks).get(kid) ?? null;
+    const url = jwks.toString();
+    const doFetch = fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== 'function')
+        throw new Error('no fetch to read the key set with');
+    let set = remoteKeySets.get(url);
+    if (!set || now >= set.freshUntil)
+        set = await fetchKeySet(url, doFetch, now);
+    else if (!set.keys.has(kid) && now - set.fetchedAt >= APPROVAL_RECEIPT_JWKS_REFETCH_MS)
+        set = await fetchKeySet(url, doFetch, now);
+    return set.keys.get(kid) ?? null;
+}
+const refuse = (reason, error) => ({ ok: false, reason, error });
+function decodeJson(segment) {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(base64UrlToBytes(segment)));
+}
+/**
+ * Verifies an approval receipt. It checks, in this order: the header (EdDSA,
+ * the receipt `typ`, a key id, no `crit`), that a published key has that id,
+ * the signature, the claims' shape, `exp` and `iat` (60 s of clock skew),
+ * `aud`, then `argsHash`; each failure has its own `reason`. It never throws
+ * for a bad receipt; a JWKS URL that cannot be read refuses with `key`.
+ *
+ * A receipt that verifies is still the tool's to use once: record its `jti`
+ * for at least the receipt's lifetime, and never act twice on one.
+ */
+export async function verifyApprovalReceipt(jws, options) {
+    const now = options.now ?? Date.now();
+    if (typeof jws !== 'string')
+        return refuse('malformed', 'not a compact JWS');
+    const parts = jws.split('.');
+    if (parts.length !== 3 || parts.some((p) => !B64URL.test(p)) || !parts[0] || !parts[1] || !parts[2]) {
+        return refuse('malformed', 'not a compact JWS');
+    }
+    const [headerPart, payloadPart, signaturePart] = parts;
+    let header;
+    try {
+        header = decodeJson(headerPart);
+    }
+    catch {
+        return refuse('malformed', 'the header is not JSON');
+    }
+    if (!header || typeof header !== 'object' || Array.isArray(header))
+        return refuse('malformed', 'the header is not an object');
+    if (header.alg !== APPROVAL_RECEIPT_ALG)
+        return refuse('malformed', `the header's alg is not ${APPROVAL_RECEIPT_ALG}`);
+    if (header.typ !== APPROVAL_RECEIPT_TYP)
+        return refuse('malformed', `the header's typ is not ${APPROVAL_RECEIPT_TYP}`);
+    if (typeof header.kid !== 'string' || !header.kid)
+        return refuse('malformed', 'the header names no kid');
+    if (header.crit !== undefined)
+        return refuse('malformed', 'the header names critical extensions, which a receipt has none of');
+    let jwk;
+    try {
+        jwk = await receiptKey(options.jwks, header.kid, options.fetch, now);
+    }
+    catch (err) {
+        return refuse('key', `the receipt keys could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!jwk)
+        return refuse('key', `no published receipt key has kid "${header.kid}"`);
+    let signature;
+    try {
+        signature = base64UrlToBytes(signaturePart);
+    }
+    catch {
+        return refuse('malformed', 'the signature is not base64url');
+    }
+    const subtle = await subtleCrypto();
+    let valid;
+    try {
+        const key = await subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, { name: 'Ed25519' }, false, ['verify']);
+        valid =
+            signature.length === 64 &&
+                (await subtle.verify({ name: 'Ed25519' }, key, signature, new TextEncoder().encode(`${headerPart}.${payloadPart}`)));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return refuse('signature', `the signature is not key "${header.kid}"'s over this receipt`);
+    let claims;
+    try {
+        claims = decodeJson(payloadPart);
+    }
+    catch {
+        return refuse('malformed', 'the claims are not JSON');
+    }
+    const problem = approvalReceiptClaimsProblem(claims);
+    if (problem)
+        return refuse('malformed', problem);
+    const c = claims;
+    const nowSec = Math.floor(now / 1000);
+    if (nowSec >= c.exp + APPROVAL_RECEIPT_CLOCK_SKEW_SEC)
+        return refuse('expired', 'the receipt has expired');
+    if (c.iat > nowSec + APPROVAL_RECEIPT_CLOCK_SKEW_SEC)
+        return refuse('expired', 'the receipt was issued in the future');
+    const audience = approvalReceiptAudience(options.audience) ?? options.audience;
+    if (c.aud !== audience)
+        return refuse('audience', `the receipt is for ${c.aud}, not ${audience}`);
+    if (c.argsHash !== options.expectedArgsHash)
+        return refuse('args', 'the receipt is for other arguments than this request carries');
+    return { ok: true, claims: c };
+}
+//# sourceMappingURL=receipt.js.map

package/dist/approvals/receipt.js.map

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

package/dist/approvals/types.d.ts

@@ -7,6 +7,20 @@ import type { ApprovalChannel } from '@ouispec/contract';
  */
 /** The client event a user's socket sends when they click the approval card. */
 export declare const APPROVAL_DECIDE_EVENT = "approval:decide";
+/**
+ * The longest each part of an approval's preview may be, in characters: what
+ * the approval store accepts, and what the worker holds a host's own preview
+ * (`approvals.preview`) to before it stores or shows it.
+ */
+export declare const APPROVAL_PREVIEW_LIMITS: {
+    readonly title: 500;
+    readonly consequence: 2000;
+    readonly arguments: 50;
+    readonly argumentName: 200;
+    readonly argumentLabel: 500;
+    readonly argumentValue: 4000;
+    readonly readback: 8000;
+};
 /** How long an approval lasts unless its action declares otherwise. */
 export declare const DEFAULT_APPROVAL_TTL_MS: number;
 /** The longest an action may declare an approval lasts. */
@@ -89,5 +103,5 @@ export interface ApprovalOwner {
     userId: string;
     conversationId: string;
 }
-export type { ActionRequestApproval, ApprovalChannel, ApprovalContinuation, ApprovalDecidePayload, ApprovalDecideResult, ApprovalDecision, ApprovalEffect, ApprovalGrant, ApprovalPreview, ApprovalPreviewArgument, ApprovalRedeemResult, ApprovalRefusal, ApprovalRefusalReason, ApprovalRequiredEvent, ApprovalStatus, ApprovalTokenClaims, ApprovedCall, PendingApprovalInput, } from '@ouispec/contract';
+export type { ActionRequestApproval, ApprovalChannel, ApprovalContinuation, ApprovalDecidePayload, ApprovalDecideResult, ApprovalDecision, ApprovalEffect, ApprovalGrant, ApprovalPreview, ApprovalPreviewArgument, ApprovalRedeemResult, ApprovalRefusal, ApprovalRefusalReason, ApprovalRequiredEvent, ApprovalStatus, ApprovalReceiptClaims, ApprovalTokenClaims, ApprovedCall, PendingApprovalInput, } from '@ouispec/contract';
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/approvals/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAyB,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AAE/F;;;;;GAKG;AAEH,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,QAAa,CAAC;AAClD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAE/C,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAA4C,CAAC;AAErG;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAwB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;AAE7F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,sBAAsB,EAA8B,CAAC;AAEtG,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;CAC9C;AAED,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB;AAKD,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,GACrB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/approvals/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAyB,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AAE/F;;;;;GAKG;AAEH,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;CAQ1B,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,QAAa,CAAC;AAClD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAE/C,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAA4C,CAAC;AAErG;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAwB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;AAE7F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,sBAAsB,EAA8B,CAAC;AAEtG,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;CAC9C;AAED,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB;AAKD,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/approvals/types.js

@@ -6,6 +6,20 @@
  */
 /** The client event a user's socket sends when they click the approval card. */
 export const APPROVAL_DECIDE_EVENT = 'approval:decide';
+/**
+ * The longest each part of an approval's preview may be, in characters: what
+ * the approval store accepts, and what the worker holds a host's own preview
+ * (`approvals.preview`) to before it stores or shows it.
+ */
+export const APPROVAL_PREVIEW_LIMITS = {
+    title: 500,
+    consequence: 2000,
+    arguments: 50,
+    argumentName: 200,
+    argumentLabel: 500,
+    argumentValue: 4000,
+    readback: 8000,
+};
 /** How long an approval lasts unless its action declares otherwise. */
 export const DEFAULT_APPROVAL_TTL_MS = 5 * 60_000;
 /** The longest an action may declare an approval lasts. */

package/dist/approvals/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/approvals/types.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEvD,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,MAAM,CAAC;AAClD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,MAAM,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAA+B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAErG;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,MAAM,CAAC;AAqDhD,MAAM,CAAC,MAAM,yBAAyB,GAAsC,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AA8CtG,MAAM,aAAa,GAAmD,IAAI,CAAC;AAC3E,MAAM,WAAW,GAA0C,IAAI,CAAC;AAChE,KAAK,aAAa,CAAC;AACnB,KAAK,WAAW,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/approvals/types.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,KAAK,EAAE,GAAG;IACV,WAAW,EAAE,IAAI;IACjB,SAAS,EAAE,EAAE;IACb,YAAY,EAAE,GAAG;IACjB,aAAa,EAAE,GAAG;IAClB,aAAa,EAAE,IAAI;IACnB,QAAQ,EAAE,IAAI;CACN,CAAC;AAEX,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,MAAM,CAAC;AAClD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,MAAM,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAA+B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAErG;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,MAAM,CAAC;AAqDhD,MAAM,CAAC,MAAM,yBAAyB,GAAsC,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AA+CtG,MAAM,aAAa,GAAmD,IAAI,CAAC;AAC3E,MAAM,WAAW,GAA0C,IAAI,CAAC;AAChE,KAAK,aAAa,CAAC;AACnB,KAAK,WAAW,CAAC"}

package/dist/message-input/index.d.ts

@@ -49,14 +49,45 @@ export declare const REPLY_OUTPUT_CONTEXT_KEY = "output";
 /** The ways a reply can reach the person besides being shown as text. A shown reply carries no `output`. */
 export declare const REPLY_OUTPUT_MODES: readonly ["voice"];
 export type ReplyOutputMode = (typeof REPLY_OUTPUT_MODES)[number];
+/**
+ * What the voice that reads a spoken reply can be directed with: the inline
+ * tags its speech engine honours (`[laughs]`, `[whispering]`), and how to use
+ * them. The service that speaks the reply sends it, since only it knows which
+ * engine will read the reply; the model is told it may use those tags.
+ */
+export interface VoiceDirections {
+    /** The speech engine the tags are for, as the service names it. */
+    engine: string;
+    /** The tags the engine honours, each exactly as it is written in the text. */
+    tags: string[];
+    /** How and when to use them, in the service's words. */
+    guidance: string;
+}
+/** Limits on `VoiceDirections`: longer is not a direction contract, and is left out. */
+export declare const VOICE_DIRECTIONS_LIMITS: {
+    readonly engineChars: 64;
+    readonly tags: 64;
+    readonly tagChars: 64;
+    readonly guidanceChars: 2000;
+};
 /** A reply that will be spoken: a voice reads its text out, and nothing of it is shown. */
 export interface ReplyOutput {
     mode: ReplyOutputMode;
+    /** The voice's direction tags, when the speaking service offers them. */
+    voiceDirections?: VoiceDirections;
 }
+/**
+ * `value` as voice directions, or null when it is not one: an engine, a list
+ * of tags and guidance, each a non-blank string within `VOICE_DIRECTIONS_LIMITS`
+ * and free of control characters (guidance may break lines). Tags are kept
+ * once each, in order.
+ */
+export declare function readVoiceDirections(value: unknown): VoiceDirections | null;
 /**
  * How a reply reaches the person, when `value` says so in a way this runtime
- * knows; else null, and the reply is shown as text. Anything but the mode is
- * left out.
+ * knows; else null, and the reply is shown as text. Anything but the mode and
+ * well-formed `voiceDirections` is left out; malformed directions are left
+ * out and the reply is still spoken.
  */
 export declare function readReplyOutput(value: unknown): ReplyOutput | null;
 //# sourceMappingURL=index.d.ts.map

package/dist/message-input/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/message-input/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,oBAAqB,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,kFAAkF;AAClF,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAStE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAMpE;AAED,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,oBAAqB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAKlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/message-input/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,oBAAqB,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,kFAAkF;AAClF,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAStE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAMpE;AAED,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,oBAAqB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wFAAwF;AACxF,eAAO,MAAM,uBAAuB;;;;;CAK1B,CAAC;AAEX,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,yEAAyE;IACzE,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAQD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAW1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAMlE"}

package/dist/message-input/index.js

@@ -60,17 +60,53 @@ export function readMessageInput(value) {
 export const REPLY_OUTPUT_CONTEXT_KEY = 'output';
 /** The ways a reply can reach the person besides being shown as text. A shown reply carries no `output`. */
 export const REPLY_OUTPUT_MODES = ['voice'];
+/** Limits on `VoiceDirections`: longer is not a direction contract, and is left out. */
+export const VOICE_DIRECTIONS_LIMITS = {
+    engineChars: 64,
+    tags: 64,
+    tagChars: 64,
+    guidanceChars: 2_000,
+};
+/** Any control character but none of the ordinary whitespace a guidance paragraph may hold. */
+// eslint-disable-next-line no-control-regex
+const DIRECTION_CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+// eslint-disable-next-line no-control-regex
+const LINE_CONTROL = /[\u0000-\u001f\u007f]/;
+/**
+ * `value` as voice directions, or null when it is not one: an engine, a list
+ * of tags and guidance, each a non-blank string within `VOICE_DIRECTIONS_LIMITS`
+ * and free of control characters (guidance may break lines). Tags are kept
+ * once each, in order.
+ */
+export function readVoiceDirections(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const { engine, tags, guidance } = value;
+    const line = (s, max) => typeof s === 'string' && s.trim().length > 0 && s.length <= max && !LINE_CONTROL.test(s);
+    if (!line(engine, VOICE_DIRECTIONS_LIMITS.engineChars))
+        return null;
+    if (!Array.isArray(tags) || tags.length === 0 || tags.length > VOICE_DIRECTIONS_LIMITS.tags)
+        return null;
+    if (!tags.every((t) => line(t, VOICE_DIRECTIONS_LIMITS.tagChars)))
+        return null;
+    if (typeof guidance !== 'string' || !guidance.trim() || guidance.length > VOICE_DIRECTIONS_LIMITS.guidanceChars || DIRECTION_CONTROL.test(guidance)) {
+        return null;
+    }
+    return { engine: engine.trim(), tags: [...new Set(tags.map((t) => t.trim()))], guidance: guidance.trim() };
+}
 /**
  * How a reply reaches the person, when `value` says so in a way this runtime
- * knows; else null, and the reply is shown as text. Anything but the mode is
- * left out.
+ * knows; else null, and the reply is shown as text. Anything but the mode and
+ * well-formed `voiceDirections` is left out; malformed directions are left
+ * out and the reply is still spoken.
  */
 export function readReplyOutput(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return null;
-    const { mode } = value;
+    const { mode, voiceDirections } = value;
     if (typeof mode !== 'string' || !REPLY_OUTPUT_MODES.includes(mode))
         return null;
-    return { mode: mode };
+    const directions = readVoiceDirections(voiceDirections);
+    return { mode: mode, ...(directions ? { voiceDirections: directions } : {}) };
 }
 //# sourceMappingURL=index.js.map

package/dist/message-input/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/message-input/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAEjD,4FAA4F;AAC5F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAU,CAAC;AAItD,kFAAkF;AAClF,MAAM,CAAC,MAAM,gCAAgC,GAAG,EAAE,CAAC;AAYnD,uFAAuF;AACvF,MAAM,YAAY,GAAG,uCAAuC,CAAC;AAE7D;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,gCAAgC;QAAE,OAAO,IAAI,CAAC;IACpH,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,8EAA8E;QAC9E,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7E,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAgC,CAAC;IAC5D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAE,mBAAyC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxG,MAAM,GAAG,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,EAAE,IAAwB,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/E,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC;AAEjD,4GAA4G;AAC5G,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAO,CAAU,CAAC;AASrD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7E,MAAM,EAAE,IAAI,EAAE,GAAG,KAAgC,CAAC;IAClD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAE,kBAAwC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvG,OAAO,EAAE,IAAI,EAAE,IAAuB,EAAE,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/message-input/index.ts"],"names":[],"mappings":"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"}

package/dist/protocol/index.d.ts

@@ -10,6 +10,7 @@ export declare const AGENT_SOCKET_EVENTS: {
     readonly TURN_STARTED: "agent:turn_started";
     readonly TOKEN: "agent:token";
     readonly TOKEN_CLEAR: "agent:token_clear";
+    readonly ROUND_END: "agent:round_end";
     readonly TOOL_CALL_STARTED: "agent:tool_call_started";
     readonly TOOL_CALL_COMPLETE: "agent:tool_call_complete";
     readonly TURN_COMPLETE: "agent:turn_complete";
@@ -44,11 +45,28 @@ export declare function displayedToolCall(call: {
     name: string;
     arguments?: Record<string, unknown>;
 };
-export type AgentProtocolEvent = TokenEvent | TokenClearEvent | IntentCallEvent | IntentResultEvent | UICommandEvent | ContextSyncEvent | LearningSignalEvent | SessionUpdateEvent | ErrorEvent | DoneEvent | ApprovalRequiredProtocolEvent | ReasoningEvent;
+export type AgentProtocolEvent = TokenEvent | TokenClearEvent | RoundEndEvent | IntentCallEvent | IntentResultEvent | UICommandEvent | ContextSyncEvent | LearningSignalEvent | SessionUpdateEvent | ErrorEvent | DoneEvent | ApprovalRequiredProtocolEvent | ReasoningEvent;
 export interface TokenEvent {
     type: 'token';
     content: string;
     turnId: string;
+    /** The round (model step) of the turn the text belongs to, from 0. Absent from a worker that does not say. */
+    step?: number;
+}
+/**
+ * A round (one model step) of the turn ended, and all of its text has been
+ * sent. `calledTools`: the round called tools. `final`: no round follows it,
+ * so its text is the turn's last word (a round that ended at an approval or a
+ * choice for the person is final though it called a tool). A consumer that
+ * shows or speaks only what the turn ends with holds each round's text until
+ * this, and keeps it when `final`.
+ */
+export interface RoundEndEvent {
+    type: 'round_end';
+    step: number;
+    calledTools: boolean;
+    final: boolean;
+    turnId: string;
 }
 export interface TokenClearEvent {
     type: 'token_clear';

package/dist/protocol/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;CAAoB,CAAC;AAErD,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAElG,eAAO,MAAM,uBAAuB,EAAE,oBAAoB,EAAuC,CAAC;AAElG;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;CAAuE,CAAC;AAEnG;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAKA;AAED,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,eAAe,GACf,aAAa,GACb,eAAe,GACf,iBAAiB,GACjB,cAAc,GAEd,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,GAClB,UAAU,GACV,SAAS,GACT,6BAA6B,GAC7B,cAAc,CAAC;AAEnB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,8GAA8G;IAC9G,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,SAAS,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACtE;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,MAAM,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3F;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACzE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/E,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EACF;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACnF;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACjF;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,iGAAiG;AACjG,MAAM,WAAW,6BAA8B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC;IAC7F,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;IACjC,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,CAAC;AAEhI,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAOpD,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAOD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAyHhH"}

package/dist/protocol/index.js

@@ -41,6 +41,10 @@ export const TURN_END_REASONS = [
 export function isTurnEndReason(value) {
     return typeof value === 'string' && TURN_END_REASONS.includes(value);
 }
+/** A round index: a whole number from 0. */
+function isStep(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
 /**
  * Maps a raw Socket.IO event (name + payload) to an AgentProtocolEvent.
  * This is the canonical mapping — platforms never need to write their own.
@@ -57,7 +61,12 @@ export function parseSocketEvent(event, data, fallbackTurnId) {
                 type: 'token',
                 content: payload.text ?? payload.token ?? payload.content ?? '',
                 turnId,
+                ...(isStep(payload.step) ? { step: payload.step } : {}),
             };
+        case AGENT_SOCKET_EVENTS.ROUND_END:
+            if (!isStep(payload.step) || typeof payload.calledTools !== 'boolean' || typeof payload.final !== 'boolean')
+                return null;
+            return { type: 'round_end', step: payload.step, calledTools: payload.calledTools, final: payload.final, turnId };
         case AGENT_SOCKET_EVENTS.TOKEN_CLEAR:
             return {
                 type: 'token_clear',

package/dist/protocol/index.js.map

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

package/dist/receipt-vectors.json

@@ -0,0 +1,291 @@
+{
+  "version": 1,
+  "description": "Approval receipts and the result every verifier must give for each. Verify each `receipt` against `jwks`, with `audience` as the tool's audience, `expectedArgsHash` as the hash of the request it received, and `now` (epoch seconds) as the time. A refusal must give `result.reason`; a receipt that verifies must give exactly `result.claims`. `signingKeys` holds every key the receipts were signed with, private parts included: a signer that writes the header and claims in the order shown must reproduce each valid receipt byte for byte.",
+  "provenance": "Written by packages/agent-core/scripts/receipt-vectors.mjs with node:crypto alone: Ed25519 signatures are deterministic, the arguments are hashed from their canonical form as written below, and every time is fixed. The keys come from published seeds and sign nothing real.",
+  "now": 1793145600,
+  "audience": "https://api.example.com",
+  "args": {
+    "vehicleId": "VIN-1HGCM82633A004352",
+    "slot": "2026-10-28T15:30:00-04:00",
+    "customer": {
+      "phone": "+15555550142",
+      "name": "Ana Souza"
+    }
+  },
+  "canonicalArgs": "{\"customer\":{\"name\":\"Ana Souza\",\"phone\":\"+15555550142\"},\"slot\":\"2026-10-28T15:30:00-04:00\",\"vehicleId\":\"VIN-1HGCM82633A004352\"}",
+  "expectedArgsHash": "63b49d3bd683750bf05cc00af982b2b4e5b2903e859052a86c9a4d3c8cedb59f",
+  "jwks": {
+    "keys": [
+      {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": "ml9nEfpt1d5wH6TDUg3mI9zygBB5g-g0Uf2Y_fxV7Gw",
+        "kid": "receipt-2026-10",
+        "alg": "EdDSA",
+        "use": "sig"
+      },
+      {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": "AGiwOPWf-13pP5-ZYdFJPWpuPFAV96144MAwUkKWHIk",
+        "kid": "receipt-2026-07",
+        "alg": "EdDSA",
+        "use": "sig"
+      }
+    ]
+  },
+  "signingKeys": [
+    {
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "kid": "receipt-2026-10",
+      "x": "ml9nEfpt1d5wH6TDUg3mI9zygBB5g-g0Uf2Y_fxV7Gw",
+      "d": "oVL5iy4RviQHSAQyVDXTn_pGRCjkQ9tK6v6ytmcUens"
+    },
+    {
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "kid": "receipt-2026-07",
+      "x": "AGiwOPWf-13pP5-ZYdFJPWpuPFAV96144MAwUkKWHIk",
+      "d": "AzpU5g1LDkYK2ubiyObI5q7f2nBLFUiB3Q-3C5cs4W0"
+    },
+    {
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "kid": "receipt-2026-04",
+      "x": "GCRxk8RuVjisqZN0Vrb3m8mnBcCiCc_9TlVj6OnUphI",
+      "d": "Py5prdt0Axx9wqIzUkVFqzcQsZs6nJ-ZINqveSPTQxs"
+    },
+    {
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "kid": "another-environment",
+      "x": "M1EtZG-9Iy29Vkq8fuQX-yV1buSgPmDGjDWC3Q4qU3k",
+      "d": "LG2oMvPvL1tj07TqY92DcL8lhQSAjC7C8KtcH_aPqRQ"
+    }
+  ],
+  "vectors": [
+    {
+      "name": "valid: signed by the active key, every claim",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.jdc-wTgTiHmNfINq--iOo8E7M6V6VbYmCSvRzUYpZ_YD7P7JtdgWxaec7gvdJYPRgYEKJ0g_xUyTkbTcx55lDQ",
+      "result": {
+        "ok": true,
+        "claims": {
+          "iss": "https://realtime.example.com",
+          "aud": "https://api.example.com",
+          "approvalId": "toolu_01JBK7Q4R8M2V6X9",
+          "argsHash": "63b49d3bd683750bf05cc00af982b2b4e5b2903e859052a86c9a4d3c8cedb59f",
+          "tool": "bookings_create",
+          "operationId": "bookings_create",
+          "conversationId": "conv_7f3a9c",
+          "userId": "user_42",
+          "accountId": "acct_dealer_17",
+          "channel": "voice",
+          "iat": 1793145595,
+          "exp": 1793145715,
+          "jti": "f5b8e7c2-4d1a-4e9b-9c3f-2a6d8e0b1c47"
+        }
+      }
+    },
+    {
+      "name": "valid: no optional claims (no operationId, no accountId), approved in a UI",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJjb25maXJtX2Jvb2tpbmciLCJjb252ZXJzYXRpb25JZCI6ImNvbnZfN2YzYTljIiwidXNlcklkIjoidXNlcl80MiIsImNoYW5uZWwiOiJ1aSIsImlhdCI6MTc5MzE0NTU5NSwiZXhwIjoxNzkzMTQ1NzE1LCJqdGkiOiIwYjZjM2MxZS04ZjBhLTRkNWUtYTJiNy05ZTFmNGM2ZDhhMjAifQ.xOK04_awIKbWTt0enP4VeP6IMAGYzWEuLaZKj0LgVpU3fvPTh0XvQOllPn9GzEsXliKETnSJJBTzCtwbo5idBQ",
+      "result": {
+        "ok": true,
+        "claims": {
+          "iss": "https://realtime.example.com",
+          "aud": "https://api.example.com",
+          "approvalId": "toolu_01JBK7Q4R8M2V6X9",
+          "argsHash": "63b49d3bd683750bf05cc00af982b2b4e5b2903e859052a86c9a4d3c8cedb59f",
+          "tool": "confirm_booking",
+          "conversationId": "conv_7f3a9c",
+          "userId": "user_42",
+          "channel": "ui",
+          "iat": 1793145595,
+          "exp": 1793145715,
+          "jti": "0b6c3c1e-8f0a-4d5e-a2b7-9e1f4c6d8a20"
+        }
+      }
+    },
+    {
+      "name": "valid: signed by the previous key, which is still published",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0wNyJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiN2MyZTliNGQtNWExZi00YzhlLWIzZDYtMmUwYTlmN2MxYjg1In0.mktb2NARmz3znJAAQMQxLR8l4D6VG3cZRLwmksloN6hsj5ul_CXgmHsgcaFtSQECBxruhOQ6cZ7twLWyXBV-CQ",
+      "result": {
+        "ok": true,
+        "claims": {
+          "iss": "https://realtime.example.com",
+          "aud": "https://api.example.com",
+          "approvalId": "toolu_01JBK7Q4R8M2V6X9",
+          "argsHash": "63b49d3bd683750bf05cc00af982b2b4e5b2903e859052a86c9a4d3c8cedb59f",
+          "tool": "bookings_create",
+          "operationId": "bookings_create",
+          "conversationId": "conv_7f3a9c",
+          "userId": "user_42",
+          "accountId": "acct_dealer_17",
+          "channel": "voice",
+          "iat": 1793145595,
+          "exp": 1793145715,
+          "jti": "7c2e9b4d-5a1f-4c8e-b3d6-2e0a9f7c1b85"
+        }
+      }
+    },
+    {
+      "name": "valid: expired 59 s ago, within the clock skew",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU0MjEsImV4cCI6MTc5MzE0NTU0MSwianRpIjoiM2U5ZDJmNGEtNmIxYy00YThlLWI1ZDctMWMwZjllMmE0YjY4In0.Wlpk2MNUBGMyubuo65EJB3UBnWXUQQbqrtTX8EI7rFzJOTcdR43w287wOczUgW3lLQZcqchskSwJfN6xxkvkBA",
+      "result": {
+        "ok": true,
+        "claims": {
+          "iss": "https://realtime.example.com",
+          "aud": "https://api.example.com",
+          "approvalId": "toolu_01JBK7Q4R8M2V6X9",
+          "argsHash": "63b49d3bd683750bf05cc00af982b2b4e5b2903e859052a86c9a4d3c8cedb59f",
+          "tool": "bookings_create",
+          "operationId": "bookings_create",
+          "conversationId": "conv_7f3a9c",
+          "userId": "user_42",
+          "accountId": "acct_dealer_17",
+          "channel": "voice",
+          "iat": 1793145421,
+          "exp": 1793145541,
+          "jti": "3e9d2f4a-6b1c-4a8e-b5d7-1c0f9e2a4b68"
+        }
+      }
+    },
+    {
+      "name": "expired: 60 s past exp, beyond the clock skew",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU0MjAsImV4cCI6MTc5MzE0NTU0MCwianRpIjoiOWExYzdlNWItMmQ0Zi00YjZhLThlMGMtNWYzZDFiN2E5YzI0In0.7nHULjfSV7J6FXAs0XHkpox5A0u5FtnyK-tiHP7TEm1Laqi0zeOxWmclVtUvBm3MUCTwr1-j_AvNptc-__R0DQ",
+      "result": {
+        "ok": false,
+        "reason": "expired"
+      }
+    },
+    {
+      "name": "expired: issued 61 s in the future, beyond the clock skew",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU2NjEsImV4cCI6MTc5MzE0NTc4MSwianRpIjoiNmQ0YjJhOGUtMWY3Yy00ZTNhLTliNWQtMGM4ZTJmNmE0ZDE5In0.93Af8-S10xj3j9Yaqwvr9Er0LKWdL5sV-feO1OwRET2UpXEU0uDLAuXbrVlnVrfZzJCpj3cT5W6zvUZu5T93Cg",
+      "result": {
+        "ok": false,
+        "reason": "expired"
+      }
+    },
+    {
+      "name": "key: signed by a key that has been removed",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0wNCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.XglwKVP1Cp1aQISbglRB3824DADsKEIek4uXUfwEWEYtUF6PRd657TS-dyO1zcqOqqREz-lC_ehuc8UGWVzxCg",
+      "result": {
+        "ok": false,
+        "reason": "key"
+      }
+    },
+    {
+      "name": "signature: names the active key, signed by another",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.JExlbctWcOVonQt_ioQAddwWP7S-NcxC--d-KNAydltrbcbGHmBuhF2_lWqf8uzBywiEXBm9akt6m7gbC3dTAg",
+      "result": {
+        "ok": false,
+        "reason": "signature"
+      }
+    },
+    {
+      "name": "signature: claims changed under the real signature",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiMWRkNjJmY2UyMWFhY2FiMWQxY2E2NmE3NGU5NjQwOTg3YzdkZGY1ODdhZWQ5NjE5NjlmN2QyODdjOGJmYjdkNCIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.jdc-wTgTiHmNfINq--iOo8E7M6V6VbYmCSvRzUYpZ_YD7P7JtdgWxaec7gvdJYPRgYEKJ0g_xUyTkbTcx55lDQ",
+      "result": {
+        "ok": false,
+        "reason": "signature"
+      }
+    },
+    {
+      "name": "signature: signature truncated",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.jdc-wTgTiHmNfINq--iOo8E7M6V6VbYmCSvRzUYpZ_Y",
+      "result": {
+        "ok": false,
+        "reason": "signature"
+      }
+    },
+    {
+      "name": "malformed: typ is JWT",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.vgAwgIGl3H_BPGd5hMtDwI6jjzcwTYrHDbaQ-bssCv2pomwgX_bXHviW7JKyXtI1aLYAmZTjqPxjIFChDy9hDQ",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: alg is HS256, keyed with the public key",
+      "receipt": "eyJhbGciOiJIUzI1NiIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.JBiLvF_JjICz_or8gQzUZ3pNEgyMgIL2_D97Thw0B-0",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: alg is none, with no signature",
+      "receipt": "eyJhbGciOiJub25lIiwidHlwIjoib3VpLWFwcHJvdmFsLXJlY2VpcHQrand0Iiwia2lkIjoicmVjZWlwdC0yMDI2LTEwIn0.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: no kid",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.-iWjBMPz8A9zO-igJdvujLpWs-rb-BTA8awPHV_kEse15IkJ3RAng0iJqo7Z2Ge9W2aYoLfkVnDebufzSlytBw",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: the header names critical extensions",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCIsImNyaXQiOlsiZXhwIl19.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.x7CuVIoN1ZRA4D89ZHJyvQeyz42YWix-D44_WhmuDVT2tLC0k3Uj89e0__4ZVOP-2ZBm8BmdgQCfzOgUQzd-CQ",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: not three segments",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: validly signed, claims not JSON",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.bm90IGpzb24.GY8RAW6bwJl9bfx4o-UmcihyMGkTT3Cdh874sxoHe8IsmH1gkH5_tFzg3nVyITdeTFYnPONc5W2_AYMyOlqsCg",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: validly signed, approvalId missing",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcmdzSGFzaCI6IjYzYjQ5ZDNiZDY4Mzc1MGJmMDVjYzAwYWY5ODJiMmI0ZTViMjkwM2U4NTkwNTJhODZjOWE0ZDNjOGNlZGI1OWYiLCJ0b29sIjoiYm9va2luZ3NfY3JlYXRlIiwib3BlcmF0aW9uSWQiOiJib29raW5nc19jcmVhdGUiLCJjb252ZXJzYXRpb25JZCI6ImNvbnZfN2YzYTljIiwidXNlcklkIjoidXNlcl80MiIsImFjY291bnRJZCI6ImFjY3RfZGVhbGVyXzE3IiwiY2hhbm5lbCI6InZvaWNlIiwiaWF0IjoxNzkzMTQ1NTk1LCJleHAiOjE3OTMxNDU3MTUsImp0aSI6ImY1YjhlN2MyLTRkMWEtNGU5Yi05YzNmLTJhNmQ4ZTBiMWM0NyJ9.78fyUosdu0nOpCA9SRqI0h6ic1uldpchlPJEhCYnTU5EhuuvtwND8Z4wvMaFf3NwlI0xUDkCOKbvuBti9ls2DQ",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "malformed: validly signed, a claim a receipt does not define",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiNjNiNDlkM2JkNjgzNzUwYmYwNWNjMDBhZjk4MmIyYjRlNWIyOTAzZTg1OTA1MmE4NmM5YTRkM2M4Y2VkYjU5ZiIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3Iiwic2NvcGUiOiJib29raW5nczp3cml0ZSJ9.r_tbF6YP6wkQUQZxhrCrdF6ByTwuP0zMYJOX3Xr5YA11V5g62_K7_p0hIvbSpZ_W8I50tsmpXXOO26vcUbJ8BA",
+      "result": {
+        "ok": false,
+        "reason": "malformed"
+      }
+    },
+    {
+      "name": "audience: issued for another API",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkub3RoZXIuZXhhbXBsZSIsImFwcHJvdmFsSWQiOiJ0b29sdV8wMUpCSzdRNFI4TTJWNlg5IiwiYXJnc0hhc2giOiI2M2I0OWQzYmQ2ODM3NTBiZjA1Y2MwMGFmOTgyYjJiNGU1YjI5MDNlODU5MDUyYTg2YzlhNGQzYzhjZWRiNTlmIiwidG9vbCI6ImJvb2tpbmdzX2NyZWF0ZSIsIm9wZXJhdGlvbklkIjoiYm9va2luZ3NfY3JlYXRlIiwiY29udmVyc2F0aW9uSWQiOiJjb252XzdmM2E5YyIsInVzZXJJZCI6InVzZXJfNDIiLCJhY2NvdW50SWQiOiJhY2N0X2RlYWxlcl8xNyIsImNoYW5uZWwiOiJ2b2ljZSIsImlhdCI6MTc5MzE0NTU5NSwiZXhwIjoxNzkzMTQ1NzE1LCJqdGkiOiJmNWI4ZTdjMi00ZDFhLTRlOWItOWMzZi0yYTZkOGUwYjFjNDcifQ.AwgvMG_d-Ck_NyEDznAhFYAiymSe2b4Gp05SHYtN77rjd1LDY98dHh0n842JhedH06yhwaAtgYpAmxssvBTFCQ",
+      "result": {
+        "ok": false,
+        "reason": "audience"
+      }
+    },
+    {
+      "name": "args: issued for other arguments",
+      "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6Im91aS1hcHByb3ZhbC1yZWNlaXB0K2p3dCIsImtpZCI6InJlY2VpcHQtMjAyNi0xMCJ9.eyJpc3MiOiJodHRwczovL3JlYWx0aW1lLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJhcHByb3ZhbElkIjoidG9vbHVfMDFKQks3UTRSOE0yVjZYOSIsImFyZ3NIYXNoIjoiMWRkNjJmY2UyMWFhY2FiMWQxY2E2NmE3NGU5NjQwOTg3YzdkZGY1ODdhZWQ5NjE5NjlmN2QyODdjOGJmYjdkNCIsInRvb2wiOiJib29raW5nc19jcmVhdGUiLCJvcGVyYXRpb25JZCI6ImJvb2tpbmdzX2NyZWF0ZSIsImNvbnZlcnNhdGlvbklkIjoiY29udl83ZjNhOWMiLCJ1c2VySWQiOiJ1c2VyXzQyIiwiYWNjb3VudElkIjoiYWNjdF9kZWFsZXJfMTciLCJjaGFubmVsIjoidm9pY2UiLCJpYXQiOjE3OTMxNDU1OTUsImV4cCI6MTc5MzE0NTcxNSwianRpIjoiZjViOGU3YzItNGQxYS00ZTliLTljM2YtMmE2ZDhlMGIxYzQ3In0.X4ebLnORtbVjqHE55yf-cHs0ttcImJenVgslwSA0q1mVefQWRelGgc_eUfTq6tYp4L15O8T98jHLaaybyd-NCQ",
+      "result": {
+        "ok": false,
+        "reason": "args"
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouispec/agent-core",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Schema types, entity graph, intent resolution, and protocol definitions for the agent SDK",
   "homepage": "https://github.com/wesreid/oui/tree/main/packages/agent-core#readme",
   "bugs": {
@@ -21,7 +21,8 @@
       "browser": "./dist/browser.js",
       "import": "./dist/index.js"
     },
-    "./approval-vectors.json": "./dist/approval-vectors.json"
+    "./approval-vectors.json": "./dist/approval-vectors.json",
+    "./receipt-vectors.json": "./dist/receipt-vectors.json"
   },
   "files": [
     "dist",
@@ -30,8 +31,8 @@
   "dependencies": {
     "ajv": "^8.17.0",
     "yaml": "^2.7.0",
-    "@ouispec/contract": "^0.4.6",
-    "@ouispec/agent-events": "^0.14.0",
+    "@ouispec/agent-events": "^0.17.0",
+    "@ouispec/contract": "^0.4.9",
     "oui-spec": "^0.11.1"
   },
   "devDependencies": {
@@ -45,7 +46,7 @@
   },
   "browser": "./dist/browser.js",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync(require.resolve('oui-spec/approval-vectors.json'), 'dist/approval-vectors.json')\"",
+    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync(require.resolve('oui-spec/approval-vectors.json'), 'dist/approval-vectors.json')\" && node scripts/receipt-vectors.mjs --check && node -e \"require('node:fs').copyFileSync('receipt-vectors.json', 'dist/receipt-vectors.json')\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
     "clean": "rm -rf dist"