@agent-native/core 0.116.0 → 0.117.0

package/src/db/ddl-guard.ts

@@ -46,8 +46,14 @@ const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export async function pgTableExists(
   table: string,
   injectedClient?: DbExec,
+  dialectIsPostgres?: boolean,
 ): Promise<boolean> {
-  if (!isPostgres() || !PLAIN_IDENTIFIER.test(table)) return false;
+  // The dialect override travels with an injected client: a multi-app process
+  // (the hosted Realtime Gateway) probes a per-app Postgres DB even when its
+  // own process-global DB is absent or SQLite.
+  if (!(dialectIsPostgres ?? isPostgres()) || !PLAIN_IDENTIFIER.test(table)) {
+    return false;
+  }
   const client = injectedClient ?? getDbExec();
   try {
     const { rows } = await client.execute({
@@ -106,8 +112,14 @@ export async function pgColumnExists(
 export async function pgIndexExists(
   indexName: string,
   injectedClient?: DbExec,
+  dialectIsPostgres?: boolean,
 ): Promise<boolean> {
-  if (!isPostgres() || !PLAIN_IDENTIFIER.test(indexName)) return false;
+  if (
+    !(dialectIsPostgres ?? isPostgres()) ||
+    !PLAIN_IDENTIFIER.test(indexName)
+  ) {
+    return false;
+  }
   const client = injectedClient ?? getDbExec();
   try {
     const { rows } = await client.execute({
@@ -158,10 +170,17 @@ export async function ensureSchemaObject(options: {
   lockTimeout?: string;
   /** Injectable client for tests. */
   injectedClient?: DbExec;
+  /** Dialect override for injected per-app clients; defaults to the global. */
+  dialectIsPostgres?: boolean;
 }): Promise<boolean> {
-  const { probe, ddl, label, lockTimeout, injectedClient } = options;
+  const { probe, ddl, label, lockTimeout, injectedClient, dialectIsPostgres } =
+    options;
   if (await probe()) return false;
-  const ran = await runGuardedDdl(ddl, { lockTimeout, injectedClient });
+  const ran = await runGuardedDdl(ddl, {
+    lockTimeout,
+    injectedClient,
+    dialectIsPostgres,
+  });
   if (ran) return true;
   // The DDL was swallowed by a lock-timeout. The object is virtually always
   // already correct by the time a contended boot retries (a concurrent
@@ -185,14 +204,20 @@ export async function ensureSchemaObject(options: {
 export async function ensureTableExists(
   table: string,
   createSql: string,
-  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+  options: {
+    lockTimeout?: string;
+    injectedClient?: DbExec;
+    dialectIsPostgres?: boolean;
+  } = {},
 ): Promise<boolean> {
   return ensureSchemaObject({
-    probe: () => pgTableExists(table, options.injectedClient),
+    probe: () =>
+      pgTableExists(table, options.injectedClient, options.dialectIsPostgres),
     ddl: createSql,
     label: `table ${table}`,
     lockTimeout: options.lockTimeout,
     injectedClient: options.injectedClient,
+    dialectIsPostgres: options.dialectIsPostgres,
   });
 }
 
@@ -222,14 +247,24 @@ export async function ensureColumnExists(
 export async function ensureIndexExists(
   indexName: string,
   createIndexSql: string,
-  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+  options: {
+    lockTimeout?: string;
+    injectedClient?: DbExec;
+    dialectIsPostgres?: boolean;
+  } = {},
 ): Promise<boolean> {
   return ensureSchemaObject({
-    probe: () => pgIndexExists(indexName, options.injectedClient),
+    probe: () =>
+      pgIndexExists(
+        indexName,
+        options.injectedClient,
+        options.dialectIsPostgres,
+      ),
     ddl: createIndexSql,
     label: `index ${indexName}`,
     lockTimeout: options.lockTimeout,
     injectedClient: options.injectedClient,
+    dialectIsPostgres: options.dialectIsPostgres,
   });
 }
 
@@ -263,10 +298,14 @@ export function isLockTimeoutError(err: unknown): boolean {
  */
 export async function runGuardedDdl(
   ddl: string,
-  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+  options: {
+    lockTimeout?: string;
+    injectedClient?: DbExec;
+    dialectIsPostgres?: boolean;
+  } = {},
 ): Promise<boolean> {
   const client = options.injectedClient ?? getDbExec();
-  if (!isPostgres()) {
+  if (!(options.dialectIsPostgres ?? isPostgres())) {
     await client.execute(ddl);
     return true;
   }

package/src/deploy/build.ts

@@ -951,6 +951,26 @@ function getSentryClientConfigScript() {
   );
 }
 
+function getRealtimeClientConfigScript() {
+  // MUST stay byte-for-byte consistent with resolveRealtimeClientConfig in
+  // server/sentry-config.ts (worker bundles a string copy; it can't import it).
+  // Fail closed: require BOTH hosted transport AND an explicit gateway URL — no
+  // production default, since this ships into the CDN-cached shell.
+  const env = globalThis.process?.env || {};
+  if (firstNonEmpty(env.AGENT_NATIVE_REALTIME_TRANSPORT) !== "hosted") {
+    return null;
+  }
+  const gatewayBaseUrl = firstNonEmpty(env.AGENT_NATIVE_REALTIME_GATEWAY_URL);
+  if (!gatewayBaseUrl) return null;
+  const config = { realtime: { transport: "hosted", gatewayBaseUrl } };
+  return (
+    '<script data-agent-native-realtime-config>' +
+    'window.__AGENT_NATIVE_CONFIG__=Object.assign({},window.__AGENT_NATIVE_CONFIG__,' +
+    JSON.stringify(config) +
+    ");</script>"
+  );
+}
+
 function injectHeadScript(html, script) {
   if (!script) return html;
   const headCloseIdx = html.indexOf("</head>");
@@ -1102,7 +1122,10 @@ function applyImmutableAssetCacheHeaders(response, request) {
 }
 
 async function rewriteMountedResponse(response, basePath, pathname, request) {
-  const sentryClientConfigScript = getSentryClientConfigScript();
+  const clientConfigScript =
+    [getSentryClientConfigScript(), getRealtimeClientConfigScript()]
+      .filter(Boolean)
+      .join("") || null;
   const headers = new Headers(response.headers);
   applyDefaultSsrCacheHeader(headers, response.status, pathname);
   applyDefaultSpeculationRulesHeader(headers, response.status, basePath);
@@ -1129,7 +1152,7 @@ async function rewriteMountedResponse(response, basePath, pathname, request) {
         prefixMountedHtml(html, basePath),
         defaultSocialImageUrl(request, basePath),
       ),
-      sentryClientConfigScript,
+      clientConfigScript,
     ),
     {
       status: response.status,

package/src/realtime-protocol.ts

@@ -0,0 +1,92 @@
+/**
+ * Realtime SSE wire protocol — shared by the server SSE handlers (framework
+ * in-process path + the hosted Realtime Gateway) and the client transport.
+ *
+ * Pure constants, types, and parsers only — NO h3/node/browser deps — so both
+ * the Node server and the browser client import it.
+ *
+ * Frame taxonomy:
+ *   - CHANGE / batch frames ride the default (unnamed) SSE `message` event and
+ *     are parsed by the client's existing `normalizeEventPayload`. Unchanged.
+ *   - CONTROL frames (handshake, token rotation) ride NAMED SSE events, so
+ *     `EventSource.addEventListener(name)` routes them separately and an older
+ *     client that only reads `onmessage` silently ignores them (backward safe).
+ */
+
+export const REALTIME_PROTOCOL_VERSION = 1;
+
+/** Named SSE event carrying the one-time handshake ({@link RealtimeHandshake}). */
+export const REALTIME_SSE_HANDSHAKE_EVENT = "handshake";
+/** Named SSE event carrying a rotated subscribe token ({@link RealtimeTokenFrame}). */
+export const REALTIME_SSE_TOKEN_EVENT = "token";
+
+/**
+ * Capability advertised by the hosted gateway: awareness/presence is NOT
+ * forwarded (it lives only on the in-process emitter, never in `sync_events`),
+ * so the collab client must keep its own presence cadence. The framework's
+ * in-process SSE path forwards awareness and therefore sends no handshake — the
+ * client treats an absent handshake as "all capabilities present."
+ */
+export const REALTIME_CAP_NO_AWARENESS = "no-awareness";
+
+export interface RealtimeHandshake {
+  protocol: number;
+  capabilities: string[];
+}
+
+export interface RealtimeTokenFrame {
+  token: string;
+  /** ISO expiry, informational; the client re-mints/rotates before this. */
+  expiresAt?: string;
+}
+
+export function buildHandshakeFrame(
+  capabilities: readonly string[] = [],
+): RealtimeHandshake {
+  return {
+    protocol: REALTIME_PROTOCOL_VERSION,
+    capabilities: [...capabilities],
+  };
+}
+
+export function parseHandshakeFrame(data: string): RealtimeHandshake | null {
+  try {
+    const parsed = JSON.parse(data);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      typeof parsed.protocol === "number" &&
+      Array.isArray(parsed.capabilities)
+    ) {
+      return {
+        protocol: parsed.protocol,
+        capabilities: parsed.capabilities.filter(
+          (c: unknown): c is string => typeof c === "string",
+        ),
+      };
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+export function parseTokenFrame(data: string): RealtimeTokenFrame | null {
+  try {
+    const parsed = JSON.parse(data);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      typeof parsed.token === "string"
+    ) {
+      return {
+        token: parsed.token,
+        expiresAt:
+          typeof parsed.expiresAt === "string" ? parsed.expiresAt : undefined,
+      };
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}

package/src/server/core-routes-plugin.ts

@@ -170,6 +170,7 @@ import { handleIdentitySso } from "./identity-sso.js";
 import { createOpenRouteHandler } from "./open-route.js";
 import { createPollEventsHandler } from "./poll-events.js";
 import { createPollHandler } from "./poll.js";
+import { createRealtimeTokenHandler } from "./realtime-token.js";
 import { runWithRequestContext } from "./request-context.js";
 import {
   findUnsupportedScopedKeyNames,
@@ -1414,6 +1415,12 @@ export function createCoreRoutesPlugin(
       // Polling
       getH3App(nitroApp).use(`${P}/poll`, createPollHandler());
 
+      // Realtime subscribe-token mint (hosted gateway path)
+      getH3App(nitroApp).use(
+        `${P}/realtime-token`,
+        createRealtimeTokenHandler(),
+      );
+
       // SSE
       if (!options.disableSSE) {
         for (const route of resolveFrameworkSseRoutes(options.sseRoute)) {

package/src/server/poll-events.ts

@@ -7,10 +7,11 @@ import {
 } from "../collab/awareness.js";
 import { getSession } from "./auth.js";
 import {
+  type AppSyncState,
   canSeeChangeForUser,
-  getPollEmitter,
-  POLL_CHANGE_EVENT,
   type ChangeEvent,
+  getDefaultAppSyncState,
+  POLL_CHANGE_EVENT,
 } from "./poll.js";
 
 export function canSeeAwarenessChangeForUser(
@@ -37,8 +38,15 @@ export function canSeeAwarenessChangeForUser(
  * connected peers receive cursor moves push-style instead of waiting for
  * the next poll cycle. Polling fallback keeps working — cursors degrade
  * gracefully to poll cadence without SSE.
+ *
+ * `state` defaults to the process-wide instance so self-hosted apps are
+ * unchanged; the hosted gateway passes a per-app instance to fan out that
+ * app's events (awareness stays on the process-global emitter and is a v0
+ * gateway Non-Goal).
  */
-export function createPollEventsHandler() {
+export function createPollEventsHandler(
+  state: AppSyncState = getDefaultAppSyncState(),
+) {
   return defineEventHandler(async (event) => {
     const session = await getSession(event).catch(() => null);
     if (!session?.email) {
@@ -60,7 +68,9 @@ export function createPollEventsHandler() {
 
     const push = (change: ChangeEvent) => {
       if (closed) return;
-      if (!canSeeChangeForUser(change, session.email, session.orgId)) return;
+      if (!state.canSeeChangeForUser(change, session.email, session.orgId)) {
+        return;
+      }
       safePush(JSON.stringify(change));
     };
 
@@ -74,13 +84,24 @@ export function createPollEventsHandler() {
       safePush(JSON.stringify(change));
     };
 
-    getPollEmitter().on(POLL_CHANGE_EVENT, push);
-    getAwarenessEmitter().on(AWARENESS_CHANGE_EVENT, pushAwareness);
+    state.getPollEmitter().on(POLL_CHANGE_EVENT, push);
+    // Awareness lives ONLY on the process-global emitter and is filtered via the
+    // module-level (default-state) access path — both untenable in a multi-app
+    // gateway process, where they'd leak another app's presence/document id and
+    // resolve access against the wrong tenant. Fail closed: only the default
+    // (in-process) instance forwards awareness. The gateway advertises
+    // `no-awareness` so collab keeps its own presence cadence.
+    const forwardAwareness = state === getDefaultAppSyncState();
+    if (forwardAwareness) {
+      getAwarenessEmitter().on(AWARENESS_CHANGE_EVENT, pushAwareness);
+    }
 
     stream.onClosed(() => {
       closed = true;
-      getPollEmitter().off(POLL_CHANGE_EVENT, push);
-      getAwarenessEmitter().off(AWARENESS_CHANGE_EVENT, pushAwareness);
+      state.getPollEmitter().off(POLL_CHANGE_EVENT, push);
+      if (forwardAwareness) {
+        getAwarenessEmitter().off(AWARENESS_CHANGE_EVENT, pushAwareness);
+      }
     });
 
     return stream.send();