@agent-native/core 0.145.3 → 0.145.5

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/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.3",
+  "version": "0.145.5",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -413,7 +413,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.3"
+    "@agent-native/toolkit": "^0.13.4"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",