@agent-native/core 0.145.4 → 0.145.6

package/dist/server/poll.js

@@ -25,7 +25,7 @@ import { defineEventHandler, getQuery, setResponseStatus } from "h3";
 import { ACTION_CHANGE_MARKER_KEY, parseActionChangeMarker, } from "../action-change-marker.js";
 import { getAppStateEmitter } from "../application-state/emitter.js";
 import { getDbExec, isPostgres } from "../db/client.js";
-import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+import { ensureIndexExists, ensureIndexExistsConcurrently, ensureTableExists, } from "../db/ddl-guard.js";
 import { EXTENSION_CHANGE_MARKER_KEY, parseExtensionChangeMarker, } from "../extensions/change-marker.js";
 import { getSettingsEmitter } from "../settings/store.js";
 import { getSession } from "./auth.js";
@@ -34,6 +34,21 @@ import { getSession } from "./auth.js";
 const MAX_BUFFER = 200;
 const DURABLE_READ_LIMIT = 1000;
 const DURABLE_RETENTION_MS = 24 * 60 * 60 * 1000;
+/**
+ * Rows per prune statement, and the ceiling on statements per prune call.
+ * The product (400k) leaves headroom over one app's documented production of
+ * ~1k events/sec over the five-minute throttle, so a healthy app catches up;
+ * the cap still bounds how long a single call can run.
+ */
+const DURABLE_PRUNE_BATCH = 10_000;
+const DURABLE_PRUNE_MAX_BATCHES = 40;
+/**
+ * How far back a cold-started process replays durable action markers.
+ * Covers the gap between a separate action process writing its marker and this
+ * process's first poll — seconds in practice. Anything older is history, and
+ * replaying history is what produced 1,169 sync events/sec on one app.
+ */
+const ACTION_MARKER_REPLAY_WINDOW_MS = 60_000;
 const LEGACY_DB_CHECK_INTERVAL_MS = 1000;
 export const DURABLE_LEGACY_DB_CHECK_INTERVAL_MS = 30_000;
 export const POLL_CHANGE_EVENT = "poll-change";
@@ -243,6 +258,7 @@ export class AppSyncState {
     pollEmitter = new EventEmitter();
     syncEventsInitPromise;
     lastDurablePrune = 0;
+    durablePruneFailures = 0;
     /**
      * Whether we've seeded `version` from the DB. In serverless (Netlify,
      * Vercel, etc.) each invocation starts fresh — without seeding, `version`
@@ -388,6 +404,7 @@ export class AppSyncState {
                     await ensureIndexExists("sync_events_version_idx", "CREATE INDEX IF NOT EXISTS sync_events_version_idx ON sync_events (version)", guardOptions);
                     await ensureIndexExists("sync_events_owner_version_idx", "CREATE INDEX IF NOT EXISTS sync_events_owner_version_idx ON sync_events (owner, version)", guardOptions);
                     await ensureIndexExists("sync_events_org_version_idx", "CREATE INDEX IF NOT EXISTS sync_events_org_version_idx ON sync_events (org_id, version)", guardOptions);
+                    await ensureIndexExistsConcurrently("sync_events_created_at_id_idx", "CREATE INDEX CONCURRENTLY IF NOT EXISTS sync_events_created_at_id_idx ON sync_events (created_at, id)", guardOptions);
                     if (this.dbAssignedVersions) {
                         await ensureTableExists("sync_version", "CREATE TABLE IF NOT EXISTS sync_version (id INT PRIMARY KEY, v BIGINT NOT NULL)", guardOptions);
                         // Seed at/above both the existing durable max and wall clock, so
@@ -401,6 +418,7 @@ export class AppSyncState {
                     "CREATE INDEX IF NOT EXISTS sync_events_version_idx ON sync_events (version)",
                     "CREATE INDEX IF NOT EXISTS sync_events_owner_version_idx ON sync_events (owner, version)",
                     "CREATE INDEX IF NOT EXISTS sync_events_org_version_idx ON sync_events (org_id, version)",
+                    "CREATE INDEX IF NOT EXISTS sync_events_created_at_id_idx ON sync_events (created_at, id)",
                 ]) {
                     try {
                         await client.execute(ddl);
@@ -417,17 +435,66 @@ export class AppSyncState {
         }
         return this.syncEventsInitPromise;
     }
+    /**
+     * Drop events past the retention window, in bounded batches.
+     *
+     * Three things here are load-bearing, all of them learned from a 47 GB
+     * `sync_events` table on a live app:
+     *
+     *   - Prune by `created_at`, the actual retention timestamp, with the
+     *     additive `(created_at, id)` index created above. A version can move
+     *     ahead of the clock under bursty writes, so it is not a retention
+     *     timestamp and cannot define a 24-hour boundary safely.
+     *   - Batch it. One statement deleting an unbounded slice is a long
+     *     transaction, and a long transaction killed mid-flight by a serverless
+     *     worker shutdown is what leaves connections `idle in transaction`
+     *     holding locks — the shape of the 2026-08-06 outage.
+     *   - `ORDER BY version` inside the subquery. Without it the planner
+     *     prefers a sequential scan even with a LIMIT; with it, the existing
+     *     `sync_events_version_idx` drives the batch and the delete is a
+     *     bounded index range scan.
+     *
+     * The `lastDurablePrune` throttle below is per-process, so every serverless
+     * worker prunes on its first poll. That was survivable only once the work
+     * itself became bounded and indexed; if concurrency is still a problem,
+     * the next step is a `pg_try_advisory_xact_lock` so one worker prunes at a
+     * time. Deliberately not done yet — measure before adding a lock.
+     */
     async pruneDurableEvents(client) {
         const now = Date.now();
         if (now - this.lastDurablePrune < 5 * 60 * 1000)
             return;
         this.lastDurablePrune = now;
-        await client
-            .execute({
-            sql: "DELETE FROM sync_events WHERE created_at < ?",
-            args: [now - DURABLE_RETENTION_MS],
-        })
-            .catch(() => { });
+        const cutoff = now - DURABLE_RETENTION_MS;
+        let deleted = 0;
+        try {
+            for (let batch = 0; batch < DURABLE_PRUNE_MAX_BATCHES; batch++) {
+                const result = await client.execute({
+                    // `id IN (...)` rather than ctid/rowid: both are dialect-specific,
+                    // and the primary key is indexed on every dialect we ship.
+                    sql: `DELETE FROM sync_events WHERE id IN (
+                  SELECT id FROM sync_events WHERE created_at < ?
+                  ORDER BY created_at, id LIMIT ?
+                )`,
+                    args: [cutoff, DURABLE_PRUNE_BATCH],
+                });
+                deleted += result.rowsAffected;
+                if (result.rowsAffected < DURABLE_PRUNE_BATCH)
+                    break;
+            }
+            this.durablePruneFailures = 0;
+        }
+        catch (err) {
+            // This used to be `.catch(() => {})`. A prune that silently never
+            // succeeded is indistinguishable from one that had nothing to do, which
+            // is how the table reached 47 GB without anyone finding out. Warn once
+            // per failure streak so a persistently broken prune is visible without
+            // repeating every five minutes.
+            this.durablePruneFailures++;
+            if (this.durablePruneFailures === 1) {
+                console.warn(`[agent-native] sync_events prune failed after deleting ${deleted} row(s); the table will grow until this succeeds:`, err instanceof Error ? err.message : String(err));
+            }
+        }
     }
     async persistSyncEvent(event, dedupeKey, presetId) {
         if (!(await this.ensureSyncEventsTable()))
@@ -1025,7 +1092,17 @@ export class AppSyncState {
             // Action markers are durable specifically so a web server can observe work
             // performed by a separate action process. Do not baseline past an existing
             // marker on cold start, or the first poll after the action will miss it.
-            this.lastActionMarkerTs = 0;
+            //
+            // Bounded to a replay window rather than rewound to 0. At 0 the filter
+            // below (`updated_at > lastActionMarkerTs`) passes EVERY row, and the
+            // marker table is one never-pruned row per identity that has ever run a
+            // mutating action — so every cold start re-emitted the entire history.
+            // On one production app that was 2,188 rows replayed ~32 times a minute:
+            // 1,169 sync events/sec, none of it real traffic, against ~1.7/sec that
+            // was. A `> 0` first-run guard like the sibling detectors use would be
+            // wrong here — it would discard the cross-process wakeup this rewind
+            // exists for. Bounding the window keeps that and drops the history.
+            this.lastActionMarkerTs = Math.max(0, actionMarkerTs - ACTION_MARKER_REPLAY_WINDOW_MS);
             this.replayActionMarkerOnce = actionMarkerTs > 0;
             this.lastScreenRefreshTs = refreshTs;
             this.lastScreenRefreshTsBySession.clear();
@@ -1151,14 +1228,25 @@ export class AppSyncState {
             // serverless action invocations wake the web server's SSE/poll loop as a
             // first-class source:"action" event rather than a generic app-state bump.
             if (actionMarkerTs > this.lastActionMarkerTs) {
+                // Bounded by the same watermark the filter below applies, so a cold
+                // start reads its replay window instead of every marker ever written.
                 const actionMarkerResult = await db.execute({
-                    sql: "SELECT session_id, value, updated_at FROM application_state WHERE key = ? ORDER BY updated_at ASC",
-                    args: [ACTION_CHANGE_MARKER_KEY],
+                    sql: "SELECT session_id, value, updated_at FROM application_state WHERE key = ? AND updated_at > ? ORDER BY updated_at ASC",
+                    args: [ACTION_CHANGE_MARKER_KEY, this.lastActionMarkerTs],
                 });
                 const changedActionMarkers = actionMarkerResult.rows.filter((row) => timestampValue(row.updated_at) > this.lastActionMarkerTs);
-                this.recordActionChanges(changedActionMarkers
-                    .map((row) => parseActionChangeMarker(row.session_id, row.value))
-                    .filter((target) => !!target), `action|${actionMarkerTs}`);
+                for (const row of changedActionMarkers) {
+                    const target = parseActionChangeMarker(row.session_id, row.value);
+                    if (!target)
+                        continue;
+                    // Keyed on the ROW's own timestamp, not the table-wide max: every
+                    // process replaying the same marker must produce the same id so
+                    // `ON CONFLICT (id) DO NOTHING` collapses them. Keyed on the max,
+                    // two processes booting a moment apart hash the same row
+                    // differently and each writes its own copy. Matches the extension
+                    // marker path.
+                    this.recordActionChanges([target], `action|${timestampValue(row.updated_at)}`);
+                }
                 this.lastActionMarkerTs = actionMarkerTs;
             }
             // Check for screen-refresh requests from the agent. The `refresh-screen`
@@ -1290,6 +1378,13 @@ export function getDefaultAppSyncState() {
     if (!_defaultState) {
         _defaultState = new AppSyncState({
             dbAssignedVersions: hostedRealtimeTransportEnabled(),
+            // Only the out-of-band detectors (action markers, extensions, app-state)
+            // pass a dedupeKey, so this changes nothing for ordinary writes — they
+            // keep unique ids. It exists so N processes detecting the SAME external
+            // write collapse to one row via `ON CONFLICT (id) DO NOTHING`. Left off,
+            // it never once executed in production: every dedupeKey threaded through
+            // this file was inert, and each cold start wrote its own duplicate set.
+            deterministicEventIds: true,
         });
     }
     return _defaultState;

package/dist/server/realtime-voice.d.ts

@@ -8,8 +8,9 @@ export declare const REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS = 16000;
 export declare const REALTIME_VOICE_MAX_TOOLS = 32;
 export declare const REALTIME_VOICE_MAX_TOOL_SCHEMA_BYTES = 32000;
 export declare const REALTIME_VOICE_MAX_SESSION_BYTES = 64000;
+/** Absolute, not sliding — a signed grant cannot be extended server-side, so
+ * this must outlast the provider's 60-minute maximum realtime session. */
 export declare const REALTIME_VOICE_TOOL_GRANT_TTL_MS: number;
-export declare const REALTIME_VOICE_MAX_TOOL_GRANT_SESSIONS = 256;
 export declare const REALTIME_VOICE_CAPABILITY_HEADER = "X-Agent-Native-Realtime-Capability";
 export interface RealtimeVoiceRequestContext {
     event: H3Event;

package/dist/server/realtime-voice.js

@@ -9,6 +9,7 @@ import { getBuilderGatewayBaseUrl, resolveBuilderCredentials, resolveSecret, } f
 import { getH3App } from "./framework-request-handler.js";
 import { runWithRequestContext } from "./request-context.js";
 import { isSameOriginRequest } from "./request-origin.js";
+import { signRealtimeVoiceCapability, verifyRealtimeVoiceCapability, } from "./short-lived-token.js";
 export const REALTIME_VOICE_SESSION_PATH = "/_agent-native/realtime-voice/session";
 export const REALTIME_VOICE_TOOL_PATH = "/_agent-native/realtime-voice/tool";
 export const REALTIME_VOICE_MAX_SDP_BYTES = 64 * 1024;
@@ -17,8 +18,9 @@ export const REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS = 16_000;
 export const REALTIME_VOICE_MAX_TOOLS = 32;
 export const REALTIME_VOICE_MAX_TOOL_SCHEMA_BYTES = 32_000;
 export const REALTIME_VOICE_MAX_SESSION_BYTES = 64_000;
-export const REALTIME_VOICE_TOOL_GRANT_TTL_MS = 10 * 60 * 1_000;
-export const REALTIME_VOICE_MAX_TOOL_GRANT_SESSIONS = 256;
+/** Absolute, not sliding — a signed grant cannot be extended server-side, so
+ * this must outlast the provider's 60-minute maximum realtime session. */
+export const REALTIME_VOICE_TOOL_GRANT_TTL_MS = 75 * 60 * 1_000;
 export const REALTIME_VOICE_CAPABILITY_HEADER = "X-Agent-Native-Realtime-Capability";
 const OPENAI_REALTIME_CALLS_URL = "https://api.openai.com/v1/realtime/calls";
 const DEFAULT_MODEL = "gpt-realtime-2.1";
@@ -207,56 +209,30 @@ function packRealtimeTools(session, eligibleTools) {
     }
     return packed;
 }
-function mintRealtimeToolCapability() {
-    return globalThis.crypto.randomUUID().replaceAll("-", "");
-}
-function cleanRealtimeToolCapabilities(capabilities, now = Date.now()) {
-    for (const [key, capability] of capabilities) {
-        if (capability.expiresAt <= now)
-            capabilities.delete(key);
-    }
-    while (capabilities.size > REALTIME_VOICE_MAX_TOOL_GRANT_SESSIONS) {
-        let oldestKey;
-        let oldestExpiry = Number.POSITIVE_INFINITY;
-        for (const [key, capability] of capabilities) {
-            if (capability.expiresAt < oldestExpiry) {
-                oldestKey = key;
-                oldestExpiry = capability.expiresAt;
-            }
-        }
-        if (!oldestKey)
-            break;
-        capabilities.delete(oldestKey);
-    }
+function mintRealtimeToolCapability(auth, capability) {
+    return signRealtimeVoiceCapability({
+        userEmail: auth.userEmail,
+        ...(auth.orgId ? { orgId: auth.orgId } : {}),
+        ...(auth.browserTabId ? { browserTabId: auth.browserTabId } : {}),
+        toolNames: [...capability.initialNames],
+        discoveredToolNames: [...capability.names],
+    }, REALTIME_VOICE_TOOL_GRANT_TTL_MS / 1_000);
 }
-function registerRealtimeToolCapability(capabilities, auth, initialNames) {
-    cleanRealtimeToolCapabilities(capabilities);
-    const token = mintRealtimeToolCapability();
-    capabilities.set(token, {
-        userEmail: auth.userEmail.trim().toLowerCase(),
+function resolveRealtimeToolCapability(token, auth) {
+    const verified = verifyRealtimeVoiceCapability(token, {
+        userEmail: auth.userEmail,
         ...(auth.orgId ? { orgId: auth.orgId } : {}),
         ...(auth.browserTabId ? { browserTabId: auth.browserTabId } : {}),
-        expiresAt: Date.now() + REALTIME_VOICE_TOOL_GRANT_TTL_MS,
-        initialNames: new Set(initialNames),
-        names: new Set(),
     });
-    cleanRealtimeToolCapabilities(capabilities);
-    return token;
-}
-function resolveRealtimeToolCapability(capabilities, token, auth) {
-    cleanRealtimeToolCapabilities(capabilities);
-    if (!token)
-        return null;
-    const capability = capabilities.get(token);
-    if (!capability)
-        return null;
-    if (capability.userEmail !== auth.userEmail.trim().toLowerCase() ||
-        capability.orgId !== auth.orgId ||
-        capability.browserTabId !== auth.browserTabId) {
+    if (!verified.ok)
         return null;
-    }
-    capability.expiresAt = Date.now() + REALTIME_VOICE_TOOL_GRANT_TTL_MS;
-    return capability;
+    return {
+        userEmail: verified.userEmail,
+        ...(verified.orgId ? { orgId: verified.orgId } : {}),
+        ...(verified.browserTabId ? { browserTabId: verified.browserTabId } : {}),
+        initialNames: new Set(verified.toolNames),
+        names: new Set(verified.discoveredToolNames),
+    };
 }
 function parseSuccessfulToolSearchNames(output) {
     try {
@@ -302,7 +278,6 @@ function grantDiscoveredRealtimeTools(input) {
         input.capability.names.add(tool.name);
         expandedTools.push(tool);
     }
-    input.capability.expiresAt = Date.now() + REALTIME_VOICE_TOOL_GRANT_TTL_MS;
     return expandedTools;
 }
 function declaredBodyBytes(event) {
@@ -364,7 +339,7 @@ function invalidMethod(event) {
     setResponseStatus(event, 405);
     return { error: "Method not allowed" };
 }
-function createSessionHandler(tools, capabilities, options) {
+function createSessionHandler(tools, options) {
     return defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST")
             return invalidMethod(event);
@@ -510,7 +485,10 @@ function createSessionHandler(tools, capabilities, options) {
             }
             setResponseStatus(event, upstream.status);
             setResponseHeader(event, "Content-Type", "application/sdp");
-            setResponseHeader(event, REALTIME_VOICE_CAPABILITY_HEADER, registerRealtimeToolCapability(capabilities, auth, packedTools.map((tool) => tool.name)));
+            setResponseHeader(event, REALTIME_VOICE_CAPABILITY_HEADER, mintRealtimeToolCapability(auth, {
+                initialNames: new Set(packedTools.map((tool) => tool.name)),
+                names: new Set(),
+            }));
             return answerSdp;
         });
     });
@@ -563,7 +541,7 @@ function normalizeExecutionResult(result) {
             : {}),
     };
 }
-function createToolHandler(toolsByName, capabilities, options) {
+function createToolHandler(toolsByName, options) {
     return defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST")
             return invalidMethod(event);
@@ -577,7 +555,7 @@ function createToolHandler(toolsByName, capabilities, options) {
             setResponseStatus(event, 401);
             return { error: "Authentication required" };
         }
-        const capability = resolveRealtimeToolCapability(capabilities, readSafeHeader(event, REALTIME_VOICE_CAPABILITY_HEADER), auth);
+        const capability = resolveRealtimeToolCapability(readSafeHeader(event, REALTIME_VOICE_CAPABILITY_HEADER), auth);
         if (!capability) {
             setResponseStatus(event, 403);
             return { error: "Invalid or expired realtime voice capability" };
@@ -648,7 +626,12 @@ function createToolHandler(toolsByName, capabilities, options) {
                 return {
                     callId: request.callId,
                     ...result,
-                    ...(expandedTools.length > 0 ? { expandedTools } : {}),
+                    ...(expandedTools.length > 0
+                        ? {
+                            expandedTools,
+                            capability: mintRealtimeToolCapability(auth, capability),
+                        }
+                        : {}),
                 };
             }
             catch (error) {
@@ -669,10 +652,9 @@ export function mountRealtimeVoiceRoutes(nitroApp, actions, options) {
     }
     const tools = buildRealtimeTools(actions);
     const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
-    const capabilities = new Map();
     const app = getH3App(nitroApp);
-    app.use(REALTIME_VOICE_SESSION_PATH, createSessionHandler(tools, capabilities, options));
-    app.use(REALTIME_VOICE_TOOL_PATH, createToolHandler(toolsByName, capabilities, options));
+    app.use(REALTIME_VOICE_SESSION_PATH, createSessionHandler(tools, options));
+    app.use(REALTIME_VOICE_TOOL_PATH, createToolHandler(toolsByName, options));
     return {
         sessionPath: REALTIME_VOICE_SESSION_PATH,
         toolPath: REALTIME_VOICE_TOOL_PATH,

package/dist/server/short-lived-token.d.ts

@@ -121,6 +121,49 @@ export declare function verifyRealtimeSubscribeToken(token: string, expected: {
     projectId: string;
     key: string;
 }): RealtimeVerifyResult;
+/** Payload `typ` discriminator for realtime voice tool capabilities. */
+export declare const REALTIME_VOICE_CAPABILITY_TOKEN_TYPE = "rt-voice-capability";
+/** Inputs for {@link signRealtimeVoiceCapability}. */
+export interface RealtimeVoiceCapabilityClaims {
+    /** Authenticated caller. Re-checked against the session on every tool call. */
+    userEmail: string;
+    orgId?: string;
+    /** Binds the capability to the tab that opened the session. */
+    browserTabId?: string;
+    /** Tool names packed into the session's opening manifest. */
+    toolNames: readonly string[];
+    /** Names added later by a successful `tool-search`, capped separately. */
+    discoveredToolNames?: readonly string[];
+    ttlSeconds?: number;
+}
+/** Result of {@link verifyRealtimeVoiceCapability}. */
+export type RealtimeVoiceCapabilityVerifyResult = {
+    ok: true;
+    userEmail: string;
+    orgId?: string;
+    browserTabId?: string;
+    toolNames: string[];
+    discoveredToolNames: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Mint a capability authorising `claims.toolNames` for one realtime voice
+ * session. The token is a bounded manifest scope layered on top of the
+ * caller's session cookie — never a standalone credential.
+ */
+export declare function signRealtimeVoiceCapability(claims: RealtimeVoiceCapabilityClaims, ttlSecondsDefault: number): string;
+/**
+ * Verify a realtime voice capability and confirm it was minted for exactly the
+ * identity now making the request. Identity mismatch is reported separately
+ * from a bad signature so callers can tell a replay from a stale tab.
+ */
+export declare function verifyRealtimeVoiceCapability(token: string | undefined, expected: {
+    userEmail: string;
+    orgId?: string;
+    browserTabId?: string;
+}): RealtimeVoiceCapabilityVerifyResult;
 /** Payload `typ` discriminator for gateway access-check tokens. */
 export declare const GATEWAY_ACCESS_TOKEN_TYPE = "rt-access-check";
 /** Inputs for {@link signGatewayAccessToken}. */

package/dist/server/short-lived-token.js

@@ -241,6 +241,80 @@ export function verifyRealtimeSubscribeToken(token, expected) {
         absExp: claims.absExp,
     };
 }
+// ── Realtime voice tool capabilities ─────────────────────────────────────────
+// Signed, not stored: minting and spending are separate requests, and under a
+// serverless preset they land on different instances.
+/** Payload `typ` discriminator for realtime voice tool capabilities. */
+export const REALTIME_VOICE_CAPABILITY_TOKEN_TYPE = "rt-voice-capability";
+/**
+ * Mint a capability authorising `claims.toolNames` for one realtime voice
+ * session. The token is a bounded manifest scope layered on top of the
+ * caller's session cookie — never a standalone credential.
+ */
+export function signRealtimeVoiceCapability(claims, ttlSecondsDefault) {
+    const payload = {
+        typ: REALTIME_VOICE_CAPABILITY_TOKEN_TYPE,
+        userEmail: claims.userEmail.trim().toLowerCase(),
+        toolNames: [...claims.toolNames],
+        exp: Math.floor(Date.now() / 1000) + (claims.ttlSeconds ?? ttlSecondsDefault),
+    };
+    if (claims.orgId)
+        payload.orgId = claims.orgId;
+    if (claims.browserTabId)
+        payload.browserTabId = claims.browserTabId;
+    if (claims.discoveredToolNames?.length) {
+        payload.discovered = [...claims.discoveredToolNames];
+    }
+    const payloadStr = base64UrlEncode(JSON.stringify(payload));
+    return `${payloadStr}.${hmacB64(payloadStr, getSigningKey())}`;
+}
+/**
+ * Verify a realtime voice capability and confirm it was minted for exactly the
+ * identity now making the request. Identity mismatch is reported separately
+ * from a bad signature so callers can tell a replay from a stale tab.
+ */
+export function verifyRealtimeVoiceCapability(token, expected) {
+    if (typeof token !== "string" || !token.includes(".")) {
+        return { ok: false, reason: "malformed" };
+    }
+    const [payloadStr, sig] = token.split(".", 2);
+    if (!payloadStr || !sig)
+        return { ok: false, reason: "malformed" };
+    if (!timingSafeEqualB64(sig, hmacB64(payloadStr, getSigningKey()))) {
+        return { ok: false, reason: "bad_signature" };
+    }
+    let claims;
+    try {
+        claims = JSON.parse(base64UrlDecode(payloadStr).toString("utf8"));
+    }
+    catch {
+        return { ok: false, reason: "bad_payload" };
+    }
+    if (claims.typ !== REALTIME_VOICE_CAPABILITY_TOKEN_TYPE) {
+        return { ok: false, reason: "wrong_type" };
+    }
+    if (typeof claims.exp !== "number" || !Array.isArray(claims.toolNames)) {
+        return { ok: false, reason: "bad_payload" };
+    }
+    if (claims.exp * 1000 < Date.now())
+        return { ok: false, reason: "expired" };
+    if (claims.userEmail !== expected.userEmail.trim().toLowerCase() ||
+        claims.orgId !== expected.orgId ||
+        claims.browserTabId !== expected.browserTabId) {
+        return { ok: false, reason: "identity_mismatch" };
+    }
+    const stringsOnly = (value) => Array.isArray(value)
+        ? value.filter((name) => typeof name === "string")
+        : [];
+    return {
+        ok: true,
+        userEmail: claims.userEmail,
+        orgId: claims.orgId,
+        browserTabId: claims.browserTabId,
+        toolNames: stringsOnly(claims.toolNames),
+        discoveredToolNames: stringsOnly(claims.discovered),
+    };
+}
 // ── Gateway access-check tokens ──────────────────────────────────────────────
 //
 // The hosted gateway has no access to an app's shareable-resource registry, so

package/dist/server/ssr-handler.js

@@ -18,7 +18,7 @@ import { defineEventHandler } from "h3";
  */
 import { createRequestHandler } from "react-router";
 import { isMcpPublicPath } from "../mcp/route-paths.js";
-import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, } from "../shared/cache-control.js";
+import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, } from "../shared/cache-control.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, withAgentNativeSocialImageCacheBuster, } from "../shared/social-meta.js";
 import { getAppBasePathFromViteEnv, stripAppBasePath as canonicalStripAppBasePath, } from "./app-base-path.js";
 import { captureError } from "./capture-error.js";
@@ -225,6 +225,9 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
     for (const [name, value] of Object.entries(resolveSsrCacheHeaders())) {
         headers.set(name, value);
     }
+    for (const [name, value] of Object.entries(resolveSsrCacheKeyHeaders())) {
+        headers.set(name, value);
+    }
 }
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {
     if (status < 200 || status >= 400)

package/dist/shared/index.d.ts

@@ -5,6 +5,7 @@ export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_EN
 export { truncate } from "./truncate.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnectionStatus, } from "./llm-connection.js";
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, type WorkspaceAppRouteAccess, type WorkspaceAppRouteAccessFromConfig, type WorkspaceAppAudience, } from "./workspace-app-audience.js";

package/dist/shared/index.js

@@ -5,6 +5,7 @@ export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_EN
 export { truncate } from "./truncate.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-connection.js";
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, } from "./workspace-app-audience.js";

package/dist/shared/runtime-config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Production configuration diagnostics.
+ *
+ * This module deliberately accepts an env-like record instead of reading
+ * process.env so the same rules can run during a Vite build, on the server,
+ * and in focused tests without ever exposing secret values to the browser.
+ */
+export type RuntimeConfigEnvironment = "development" | "production";
+export type RuntimeConfigPhase = "build" | "runtime";
+export type RuntimeConfigIssueSeverity = "warning" | "error";
+export type RuntimeConfigIssueCode = "auth-disabled-in-production" | "missing-auth-secret" | "weak-auth-secret" | "missing-a2a-secret" | "weak-a2a-secret" | "invalid-auth-url" | "missing-database-url" | "local-database-in-production" | "missing-required-env";
+export interface RuntimeConfigRequirements {
+    /** Whether the app's default or custom auth layer is expected to run. */
+    authEnabled?: boolean;
+    /** Whether the app needs a persistent database outside local development. */
+    databaseRequired?: boolean;
+    /** Additional non-secret keys the app declares as required. */
+    requiredEnv?: readonly string[];
+}
+export interface RuntimeConfigIssue {
+    code: RuntimeConfigIssueCode;
+    severity: RuntimeConfigIssueSeverity;
+    title: string;
+    message: string;
+    envKeys: string[];
+}
+export interface RuntimeConfigReport {
+    ok: boolean;
+    status: "ok" | "warning" | "error";
+    environment: RuntimeConfigEnvironment;
+    phase: RuntimeConfigPhase;
+    issues: RuntimeConfigIssue[];
+    prompt: string;
+}
+export interface RuntimeConfigReportOptions {
+    environment?: RuntimeConfigEnvironment;
+    phase?: RuntimeConfigPhase;
+    appName?: string;
+}
+export declare function runtimeConfigRequirementsFromSearchParams(searchParams: URLSearchParams): RuntimeConfigRequirements;
+export declare function buildRuntimeConfigPrompt(report: Pick<RuntimeConfigReport, "environment" | "phase" | "issues">, appName?: string): string;
+export declare function getRuntimeConfigReport(env: Record<string, string | undefined>, requirements?: RuntimeConfigRequirements, options?: RuntimeConfigReportOptions): RuntimeConfigReport;
+export declare function formatRuntimeConfigReport(report: RuntimeConfigReport): string;
+export declare function parseRuntimeConfigReport(value: unknown): RuntimeConfigReport | null;