@pyric/cli 0.1.0-alpha.30 → 0.1.0-alpha.30.1

package/src/register/app-bridge-admin-app-check.ts

@@ -0,0 +1,46 @@
+/**
+ * Production AI mode's App Check verifier for a registered Node process
+ * (#1552): firebase-admin's own `verifyToken`, for the tokens the page gets
+ * from Firebase.
+ *
+ * The register installs it behind `pyric.admin.appCheck.firebaseVerifier` in
+ * production AI mode only, and loads this module on the first token whose
+ * `kid` is not the sandbox's, so a server that never sees one never loads
+ * firebase-admin. `firebase-admin/app` and `firebase-admin/app-check` reach
+ * the real package from here (`isBypassedBridgeImport`).
+ *
+ * Each project gets one firebase-admin app whose credential refuses to mint an
+ * access token, so the app cannot fall back to Application Default
+ * Credentials, the metadata server, or Google's OAuth endpoints. Verifying a
+ * token needs none of them: firebase-admin fetches Firebase's public keys from
+ * `https://firebaseappcheck.googleapis.com/v1/jwks` without credentials and
+ * caches them for six hours. `consume` is never passed here; the mirror
+ * records it in the process.
+ *
+ * The export is typed loosely on purpose: the published declarations of
+ * @pyric/cli carry no Firebase SDK edge. pyric-admin types the result.
+ */
+import { initializeApp, type App, type Credential } from 'firebase-admin/app';
+import { getAppCheck } from 'firebase-admin/app-check';
+
+const NO_CREDENTIALS = "Pyric's App Check verifier holds no credentials.";
+
+/** A credential that never mints an access token. */
+const noCredentials: Credential = {
+  getAccessToken: () => Promise.reject(new Error(NO_CREDENTIALS)),
+};
+
+const appsByProject = new Map<string, App>();
+
+function verifierApp(projectId: string): App {
+  const existing = appsByProject.get(projectId);
+  if (existing !== undefined) return existing;
+  const app = initializeApp({ projectId, credential: noCredentials }, `[pyric] app-check verifier ${projectId}`);
+  appsByProject.set(projectId, app);
+  return app;
+}
+
+/** firebase-admin's `verifyToken(token)` for an app scoped to `projectId`, with no options. */
+export function verifyFirebaseAppCheckToken(token: string, projectId: string): Promise<unknown> {
+  return getAppCheck(verifierApp(projectId)).verifyToken(token);
+}

package/src/register/app-bridge-app-check.ts

@@ -20,6 +20,10 @@ import { shadowAppOf } from './app-bridge-shadow.js';
 
 type RealInitialize = typeof realAppCheck.initializeAppCheck;
 
+/**
+ * `shadowAppOf` throws when the shadow app could not be created, so that
+ * cause surfaces here before the SDK would fail on a missing container.
+ */
 export function initializeAppCheck(app: { name: string } | undefined, options: unknown): unknown {
   const shadow = app === undefined ? undefined : shadowAppOf(app);
   return realAppCheck.initializeAppCheck(shadow as Parameters<RealInitialize>[0], options as Parameters<RealInitialize>[1]);

package/src/register/app-bridge-shadow.ts

@@ -2,7 +2,8 @@
  * Production AI pass-through for canonical `firebase/app` in a registered Node
  * process: each Pyric app gets a shadow real Firebase app whose container the
  * real `firebase/ai` reads. Shared by the in-process adapter
- * (`./app-bridge.ts`) and the Node host client (`./client/app-bridge.ts`).
+ * (`./app-bridge.ts`), the Node host client (`./client/app-bridge.ts`), and
+ * the served `firebase/app` entry (`serve/entries/app-ai-passthrough.ts`).
  */
 import * as realApp from 'firebase/app';
 import type { FirebaseApp, FirebaseAppSettings, FirebaseOptions } from 'pyric/app';
@@ -14,6 +15,27 @@ export interface PyricAppRegistry {
   deleteApp(app: FirebaseApp): Promise<void>;
 }
 
+/**
+ * Why the shadow app for a name could not be created, kept until a later
+ * attempt succeeds or the app is deleted. It sits behind `Symbol.for` so every
+ * bundle or module record of this file on a page or in a process shares it.
+ */
+const SHADOW_FAILURES = Symbol.for('pyric.ai.shadowAppFailures');
+type GlobalShadowFailures = { [SHADOW_FAILURES]?: Map<string, unknown> };
+const shadowFailures = ((globalThis as GlobalShadowFailures)[SHADOW_FAILURES] ??= new Map<string, unknown>());
+
+function causeText(cause: unknown): string {
+  const text = cause instanceof Error ? cause.message : String(cause);
+  return text.replace(/\.$/, '');
+}
+
+function shadowFailedError(name: string, cause: unknown): Error {
+  return new Error(
+    `Pyric could not create the Firebase app that firebase/app-check and firebase/ai attach to in production AI mode, for app "${name}": ${causeText(cause)}.`,
+    { cause },
+  );
+}
+
 function decorateApp(
   app: FirebaseApp,
   options?: FirebaseOptions,
@@ -34,24 +56,31 @@ function decorateApp(
         shadow = realApp.initializeApp(initOptions, objectSettings) as { container?: unknown };
       }
     }
+    shadowFailures.delete(app.name);
     const hasShadowContainer = shadow.container !== undefined && shadow.container !== null;
     if (hasShadowContainer) {
       Object.defineProperty(app, 'container', { value: shadow.container, configurable: true });
     }
-  } catch {
-    // Observational/best-effort: do not break Pyric initialization if shadow initialization fails.
+  } catch (error) {
+    // Pyric's initializeApp still succeeds; shadowAppOf reports the cause
+    // when firebase/app-check or firebase/ai needs the shadow.
+    shadowFailures.set(app.name, error);
   }
   return app;
 }
 
 /**
- * The shadow Firebase app for a Pyric app, by name. A Firebase app passed in
- * directly, or a Pyric app with no shadow yet, is returned unchanged.
+ * The shadow Firebase app for a Pyric app, by name. When creating it failed,
+ * throws an error that names the app and keeps the failure as `cause`. A
+ * Firebase app passed in directly, or a Pyric app with no attempt yet, is
+ * returned unchanged.
  */
 export function shadowAppOf(app: { name: string }): object {
   try {
     return realApp.getApp(app.name);
   } catch {
+    const hasFailure = shadowFailures.has(app.name);
+    if (hasFailure) throw shadowFailedError(app.name, shadowFailures.get(app.name));
     return app;
   }
 }
@@ -69,6 +98,7 @@ export function shadowedAppRegistry(pyricApp: PyricAppRegistry): PyricAppRegistr
       return pyricApp.getApps().map((app) => decorateApp(app));
     },
     async deleteApp(app) {
+      shadowFailures.delete(app.name);
       try {
         const shadow = realApp.getApp(app.name);
         const hasShadow = shadow !== undefined && shadow !== null;

package/src/register/index.ts

@@ -38,12 +38,16 @@ import { resolveEsmOnlySubpath } from './esm-exports.js';
 import { NET_GUARD_GLOBAL, installNetGuard, parseGuardMode, type GuardMode } from './net-guard.js';
 import { emitBeacon } from './beacon.js';
 import { remoteSandbox } from '../remote/index.js';
+import { resolveAiMode } from '../serve/firebase-module-swap.js';
 
 /** The shared seam with pyric-admin's ambient init: a synchronous factory
  *  returning the lazy branded handle. `Symbol.for` so both packages agree
  *  without importing each other's types. */
 const SANDBOX_FACTORY = Symbol.for('pyric.remote.sandboxFactory');
 
+/** The seam with pyric-admin's App Check mirror: firebase-admin's verifier for tokens from Firebase (#1552). */
+const APP_CHECK_FIREBASE_VERIFIER = Symbol.for('pyric.admin.appCheck.firebaseVerifier');
+
 interface SyncResolveContext {
   parentURL?: string;
   conditions?: string[];
@@ -170,6 +174,8 @@ function activate(): void {
   (globalThis as Record<symbol, unknown>)[SANDBOX_FACTORY] = (opts?: { url?: string }) =>
     remoteSandbox({ configuredUrl: opts?.url, instanceId: process.env.PYRIC_SANDBOX_INSTANCE });
 
+  installAppCheckVerifier();
+
   process.stderr.write(
     `@pyric/cli/register: active. firebase-admin/firebase imports now resolve to the ` +
       `pyric sandbox (PYRIC_SANDBOX=${process.env.PYRIC_SANDBOX}).\n`,
@@ -187,6 +193,23 @@ function activate(): void {
   });
 }
 
+/**
+ * Production AI mode only: the page's App Check tokens come from Firebase, so
+ * pyric-admin's mirror hands them to firebase-admin's own verifier (#1552).
+ * The bridge, and firebase-admin with it, loads on the first such token, so a
+ * server that never verifies one never loads firebase-admin. In sandbox AI
+ * mode nothing is installed, and the mirror refuses such a token with a
+ * message that says why.
+ */
+function installAppCheckVerifier(): void {
+  const isProductionAiMode = resolveAiMode(undefined, process.env) === 'production';
+  if (!isProductionAiMode) return;
+  (globalThis as Record<symbol, unknown>)[APP_CHECK_FIREBASE_VERIFIER] = async (token: string, projectId: string) => {
+    const bridge = await import('./app-bridge-admin-app-check.js');
+    return bridge.verifyFirebaseAppCheckToken(token, projectId);
+  };
+}
+
 /**
  * The net-guard mode actually in force, for the beacon to report.
  *

package/src/serve/bundler.ts

@@ -28,6 +28,8 @@ import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as esbuild from 'esbuild';
 
+import { bridgeImportEntryKey, REAL_SDK_ENTRIES } from './firebase-module-swap.js';
+
 export { SDK_MODULES } from './firebase-module-swap.js';
 
 /**
@@ -160,6 +162,145 @@ function nodeShimPlugin(): esbuild.Plugin {
   };
 }
 
+/**
+ * Send the shadow-app wrappers' own `firebase/app` and `firebase/app-check`
+ * imports to the Firebase SDK bundle `pyric sandbox` builds in production AI
+ * mode (`/__pyric/sdk/firebase-sdk-*.js`). Left bare, the import map would
+ * send them back to the wrappers themselves. The rule is
+ * `isBypassedBridgeImport`, which the Vite and register planes read too.
+ */
+function bridgeImportPlugin(): esbuild.Plugin {
+  return {
+    name: 'pyric-serve-bridge-imports',
+    setup(build) {
+      build.onResolve({ filter: /^firebase\// }, (args) => {
+        const key = bridgeImportEntryKey(args.path, args.importer);
+        if (key === undefined) return undefined;
+        return { path: `/__pyric/sdk/${key}.js`, external: true };
+      });
+    },
+  };
+}
+
+// ─── the project's Firebase SDK (production AI mode) ─────────────────
+
+/** The project's resolved `firebase` package. */
+export interface ProjectFirebase {
+  /** The package directory, as resolved from the project. */
+  root: string;
+  version: string;
+}
+
+/**
+ * Find the `firebase` package the project's own code resolves, walking up
+ * `node_modules` directories from `projectDir` as Node does. Throws a message
+ * that tells the user to install it when there is none.
+ */
+export function resolveProjectFirebase(projectDir: string): ProjectFirebase {
+  let dir = projectDir;
+  while (true) {
+    const manifest = join(dir, 'node_modules', 'firebase', 'package.json');
+    if (existsSync(manifest)) {
+      const pkg = JSON.parse(readFileSync(manifest, 'utf8')) as { version?: string };
+      return { root: dirname(manifest), version: pkg.version ?? '0.0.0' };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `pyric sandbox: production AI mode (${productionModeSetting(process.env)}) serves the Firebase SDK from this project, ` +
+      `but no firebase package resolves from ${projectDir}. Install it with \`npm install firebase\`, ` +
+      `or unset ${productionModeSetting(process.env).split('=')[0]} to answer firebase/ai from the Pyric sandbox.`,
+  );
+}
+
+/**
+ * The environment setting that turned production AI mode on, for messages.
+ * `PYRIC_AI_MODE=production` wins; otherwise the passthrough switch did it.
+ */
+export function productionModeSetting(env: NodeJS.ProcessEnv): string {
+  const isModeSet = env.PYRIC_AI_MODE === 'production';
+  return isModeSet ? 'PYRIC_AI_MODE=production' : 'PYRIC_AI_PASSTHROUGH=1';
+}
+
+export interface ProjectFirebasePlan {
+  /** Pass to `bundleSdk`; absent when the real-SDK build is skipped. */
+  projectFirebase?: { projectDir: string };
+  /** One line to log when the build is skipped. */
+  warning?: string;
+}
+
+/**
+ * Decide whether production AI mode builds the Firebase SDK. Plain
+ * `pyric sandbox` serves the page itself, so a missing `firebase` throws.
+ * With a child command the child resolves `firebase` on its own, so a
+ * missing one only skips the build and warns.
+ */
+export function planProjectFirebase(projectDir: string, hasChildCommand: boolean, env: NodeJS.ProcessEnv = process.env): ProjectFirebasePlan {
+  try {
+    resolveProjectFirebase(projectDir);
+  } catch (error) {
+    if (!hasChildCommand) throw error;
+    return {
+      warning:
+        `  ⚠ production AI mode (${productionModeSetting(env)}): no firebase package resolves from ${projectDir}, ` +
+        `so the Firebase SDK is not built. Pages the sandbox serves itself (import map) need firebase installed where pyric starts; ` +
+        `your command resolves firebase on its own.`,
+    };
+  }
+  return { projectFirebase: { projectDir } };
+}
+
+
+const REAL_SDK_NAMESPACE = 'pyric-firebase-sdk';
+
+/**
+ * Build `firebase/app`, `firebase/ai` and `firebase/app-check` from the
+ * project's `firebase` install into `outDir`, in one pass with splitting so
+ * the three share one `@firebase/app` component registry, as Vite's
+ * dependency optimizer does.
+ */
+async function bundleProjectFirebase(outDir: string, projectDir: string, firebase: ProjectFirebase, minify: boolean): Promise<void> {
+  const entryPoints: Record<string, string> = {};
+  for (const [specifier, key] of REAL_SDK_ENTRIES) entryPoints[key] = `${REAL_SDK_NAMESPACE}:${specifier}`;
+  const result = await esbuild.build({
+    entryPoints,
+    outdir: outDir,
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    splitting: true,
+    sourcemap: 'linked',
+    minify,
+    logLevel: 'silent',
+    chunkNames: 'firebase-sdk-[hash]',
+    banner: {
+      js: `/* The Firebase JS SDK, firebase@${firebase.version} from this project, built by pyric sandbox for production AI mode. */`,
+    },
+    plugins: [{
+      name: 'pyric-serve-project-firebase',
+      setup(build) {
+        build.onResolve({ filter: new RegExp(`^${REAL_SDK_NAMESPACE}:`) }, (args) => ({
+          path: args.path.slice(REAL_SDK_NAMESPACE.length + 1),
+          namespace: REAL_SDK_NAMESPACE,
+        }));
+        build.onLoad({ filter: /.*/, namespace: REAL_SDK_NAMESPACE }, (args) => ({
+          contents: `export * from ${JSON.stringify(args.path)};`,
+          resolveDir: projectDir,
+          loader: 'js',
+        }));
+      },
+    }],
+  });
+  const hasBuildErrors = result.errors.length > 0;
+  if (hasBuildErrors) {
+    throw new Error(
+      `pyric sandbox: building firebase@${firebase.version} for production AI mode failed:\n${result.errors.map((e) => e.text).join('\n')}`,
+    );
+  }
+}
+
 // ─── cache ────────────────────────────────────────────────────────────
 
 export interface BundleOptions {
@@ -171,6 +312,12 @@ export interface BundleOptions {
   /** Override the cache root (tests). Default `~/.pyric/serve-cache`. */
   cacheRoot?: string;
   minify?: boolean;
+  /**
+   * Production AI mode: also build the Firebase SDK from this project's own
+   * `firebase` install (`/__pyric/sdk/firebase-sdk-*.js`). Absent in sandbox
+   * AI mode, which neither builds nor serves it.
+   */
+  projectFirebase?: { projectDir: string };
 }
 
 export interface BundleResult {
@@ -184,7 +331,7 @@ export interface BundleResult {
 }
 
 /** Bump when bundler logic changes in a way that must invalidate caches. */
-const BUNDLER_REV = 9; // 9: cache keys also cover dependency-resolution metadata
+const BUNDLER_REV = 10; // 10: wrappers import the project's Firebase SDK by URL; production keys cover it
 
 const RESOLUTION_FILES = [
   'bun.lock',
@@ -262,12 +409,23 @@ export function cacheKey(
     h.update(name);
     h.update(readFileSync(file, 'utf8'));
   }
+  // Production AI mode also serves the project's Firebase SDK, so upgrading
+  // `firebase`, or a project resolving another copy, rebuilds it.
+  const projectFirebase = opts.projectFirebase;
+  if (projectFirebase) {
+    const firebase = resolveProjectFirebase(projectFirebase.projectDir);
+    h.update(`firebase-sdk\0${firebase.root}\0${firebase.version}`);
+  }
   return `${version}-${h.digest('hex').slice(0, 12)}`;
 }
 
 // ─── the bundle step ──────────────────────────────────────────────────
 
 export async function bundleSdk(opts: BundleOptions): Promise<BundleResult> {
+  // Resolved first, so a project without `firebase` fails before any build.
+  const projectFirebase = opts.projectFirebase
+    ? { ...opts.projectFirebase, firebase: resolveProjectFirebase(opts.projectFirebase.projectDir) }
+    : undefined;
   const root = pyricPackageRoot();
   const version = pyricVersion(root);
   const key = cacheKey(opts, version);
@@ -317,7 +475,7 @@ export async function bundleSdk(opts: BundleOptions): Promise<BundleResult> {
         js: '/* pyric sandbox shim serving firebase/*. This is not the real Firebase SDK. */',
       },
       external: ['firebase/*'],
-      plugins: [pyricResolvePlugin(), nodeShimPlugin()],
+      plugins: [pyricResolvePlugin(), nodeShimPlugin(), bridgeImportPlugin()],
     });
     const hasBuildErrors = result.errors.length > 0;
     if (hasBuildErrors) {
@@ -325,6 +483,9 @@ export async function bundleSdk(opts: BundleOptions): Promise<BundleResult> {
         `pyric sandbox: SDK bundle failed:\n${result.errors.map((e) => e.text).join('\n')}`,
       );
     }
+    if (projectFirebase) {
+      await bundleProjectFirebase(outDir, projectFirebase.projectDir, projectFirebase.firebase, opts.minify ?? true);
+    }
     writeFileSync(join(outDir, '.complete'), new Date().toISOString());
     const files = readdirSync(outDir)
       .filter((f) => f.endsWith('.js'))

package/src/serve/entries/app-ai-passthrough.ts

@@ -2,68 +2,18 @@
 import { bindAppRegistrySandbox } from 'pyric/app/internal';
 import { sandbox } from './app-backend.js';
 import * as pyricApp from 'pyric/app';
-import * as realApp from 'firebase/app';
+import { shadowedAppRegistry } from '../../register/app-bridge-shadow.js';
 
 bindAppRegistrySandbox(sandbox);
 
-function decorateApp(
-  app: pyricApp.FirebaseApp,
-  options?: pyricApp.FirebaseOptions,
-  rawSettings?: string | pyricApp.FirebaseAppSettings,
-): pyricApp.FirebaseApp {
-  try {
-    let shadow: { container?: unknown };
-    try {
-      shadow = realApp.getApp(app.name) as { container?: unknown };
-    } catch {
-      const initOptions = (options ?? app.options) as realApp.FirebaseOptions;
-      const initSettings = rawSettings ?? app.name;
-      const isStringSettings = typeof initSettings === 'string';
-      if (isStringSettings) {
-        shadow = realApp.initializeApp(initOptions, initSettings) as { container?: unknown };
-      } else {
-        const objectSettings = initSettings as realApp.FirebaseAppSettings;
-        shadow = realApp.initializeApp(initOptions, objectSettings) as { container?: unknown };
-      }
-    }
-    const hasShadowContainer = shadow.container !== undefined && shadow.container !== null;
-    if (hasShadowContainer) {
-      Object.defineProperty(app, 'container', { value: shadow.container, configurable: true });
-    }
-  } catch {
-    // Observational/best-effort: do not break Pyric initialization if shadow initialization fails.
-  }
-  return app;
-}
+// One shadow implementation for every plane: the register adapters build
+// their exports from the same registry.
+const registry = shadowedAppRegistry(pyricApp);
 
-export function initializeApp(
-  options?: pyricApp.FirebaseOptions,
-  rawSettings?: string | pyricApp.FirebaseAppSettings,
-): pyricApp.FirebaseApp {
-  const app = pyricApp.initializeApp(options, rawSettings);
-  return decorateApp(app, options, rawSettings);
-}
-
-export function getApp(name?: string): pyricApp.FirebaseApp {
-  return decorateApp(pyricApp.getApp(name));
-}
-
-export function getApps(): pyricApp.FirebaseApp[] {
-  return pyricApp.getApps().map((app) => decorateApp(app));
-}
-
-export async function deleteApp(app: pyricApp.FirebaseApp): Promise<void> {
-  try {
-    const shadow = realApp.getApp(app.name);
-    const hasShadow = shadow !== undefined && shadow !== null;
-    if (hasShadow) {
-      await realApp.deleteApp(shadow);
-    }
-  } catch {
-    // Ignore if shadow app was not initialized or already deleted.
-  }
-  return pyricApp.deleteApp(app);
-}
+export const initializeApp = registry.initializeApp;
+export const getApp = registry.getApp;
+export const getApps = registry.getApps;
+export const deleteApp = registry.deleteApp;
 
 export {
   FirebaseError,

package/src/serve/firebase-module-swap.ts

@@ -8,7 +8,8 @@
  * container.
  *
  * Every plane that swaps Firebase modules reads {@link swappedFirebaseEntries}:
- * the `pyric sandbox` import map (`html-injection.ts`) and the Vite resolver
+ * the `pyric sandbox` import map (`html-injection.ts`, through
+ * {@link importMapFirebaseEntries}) and the Vite resolver
  * (`vite-module-swap.ts`). Every front door resolves the mode with
  * {@link resolveAiMode}. One table and one precedence rule, so the planes
  * cannot disagree about what production mode means. It imports only Node
@@ -78,6 +79,34 @@ export function swappedFirebaseEntries(mode: AiMode): ReadonlyMap<ServedFirebase
   return swapped;
 }
 
+/**
+ * The Firebase SDK modules `pyric sandbox` builds for the browser from the
+ * project's own `firebase` install in production AI mode, to the entry key of
+ * each (`/__pyric/sdk/<key>.js`). One build, so the three share one
+ * `@firebase/app` component registry. The Vite and register planes resolve
+ * the Firebase SDK themselves and never read this.
+ */
+export const REAL_SDK_ENTRIES: ReadonlyMap<ServedFirebaseSpecifier, string> = new Map([
+  ['firebase/app', 'firebase-sdk-app'],
+  ['firebase/ai', 'firebase-sdk-ai'],
+  ['firebase/app-check', 'firebase-sdk-app-check'],
+]);
+
+/**
+ * The import-map plane's specifier to entry key table: the swap, plus, in
+ * production AI mode, the unswapped `firebase/ai` sent to the Firebase SDK
+ * that `pyric sandbox` builds. A browser has no package resolution, so on
+ * this plane an unswapped specifier still needs a URL.
+ */
+export function importMapFirebaseEntries(mode: AiMode): ReadonlyMap<ServedFirebaseSpecifier, string> {
+  const entries = new Map(swappedFirebaseEntries(mode));
+  for (const [specifier, key] of REAL_SDK_ENTRIES) {
+    const isUnswapped = !entries.has(specifier);
+    if (isUnswapped) entries.set(specifier, key);
+  }
+  return entries;
+}
+
 /** This package's root (`src/serve/` and `dist/serve/` both sit two levels below it), as written and resolved. */
 const PACKAGE_ROOTS: readonly string[] = (() => {
   const root = fileURLToPath(new URL('../../', import.meta.url)).replaceAll('\\', '/');
@@ -110,10 +139,30 @@ export function isShadowAppImporter(importer: string | undefined): boolean {
   return PACKAGE_ROOTS.some((root) => file.startsWith(root) && SHADOW_MODULE.test(file.slice(root.length)));
 }
 
-/** The SDK modules a shadow-app wrapper imports for itself. */
-const BRIDGED_SPECIFIERS: ReadonlySet<string> = new Set(['firebase/app', 'firebase/app-check']);
+/**
+ * The SDK modules a shadow-app wrapper imports for itself. The firebase-admin
+ * pair is the register's App Check verifier for production AI mode
+ * (`register/app-bridge-admin-app-check.ts`); no browser plane serves them.
+ */
+const BRIDGED_SPECIFIERS: ReadonlySet<string> = new Set([
+  'firebase/app',
+  'firebase/app-check',
+  'firebase-admin/app',
+  'firebase-admin/app-check',
+]);
 
 /** Whether this import is a shadow-app wrapper reaching the Firebase SDK it wraps. */
 export function isBypassedBridgeImport(specifier: string, importer: string | undefined): boolean {
   return BRIDGED_SPECIFIERS.has(specifier) && isShadowAppImporter(importer);
 }
+
+/**
+ * Where a bypassed bridge import goes on the import-map plane: the entry key
+ * of the Firebase SDK module `pyric sandbox` builds. The bare specifier
+ * cannot stay, because the import map sends it back to the wrapper itself.
+ * Undefined for every import {@link isBypassedBridgeImport} does not name.
+ */
+export function bridgeImportEntryKey(specifier: string, importer: string | undefined): string | undefined {
+  if (!isBypassedBridgeImport(specifier, importer)) return undefined;
+  return REAL_SDK_ENTRIES.get(specifier as ServedFirebaseSpecifier);
+}

package/src/serve/html-injection.ts

@@ -2,15 +2,17 @@ import { stampHostedTarget } from './runtime/hosted-target.js';
 import type { OwnersConfig } from './owners-config.js';
 import { REACT_BOOTSTRAP } from './react-bootstrap.js';
 import { SANDBOX_BUILD_MARKER } from './sandbox-marker.js';
-import { swappedFirebaseEntries, type AiMode } from './firebase-module-swap.js';
+import { importMapFirebaseEntries, type AiMode } from './firebase-module-swap.js';
 
 /**
  * The import-map targets, specifier to served URL, for one AI mode. Derived
  * from the shared swap table, so the Vite resolver serves the same modules.
+ * In production AI mode `firebase/ai` goes to the Firebase SDK that
+ * `pyric sandbox` builds from the project's `firebase` install.
  */
 export function sdkImportMap(mode: AiMode = 'sandbox'): Record<string, string> {
   const imports: Record<string, string> = {};
-  for (const [specifier, entryKey] of swappedFirebaseEntries(mode)) {
+  for (const [specifier, entryKey] of importMapFirebaseEntries(mode)) {
     imports[specifier] = `/__pyric/sdk/${entryKey}.js`;
   }
   return imports;

package/src/serve/namespace.ts

@@ -731,7 +731,11 @@ export function createPyricNamespace(opts: NamespaceOptions) {
       const file = join(opts.sdkDir, basename(url.pathname));
       const missingFile = !existsSync(file);
       if (missingFile) {
-        res.writeHead(404).end('not found');
+        const isRealSdk = basename(url.pathname).startsWith('firebase-sdk-');
+        const body = isRealSdk
+          ? 'pyric sandbox: the Firebase SDK was not built. Install firebase where pyric starts (production AI mode).'
+          : 'not found';
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end(body);
         return true;
       }
       const isSourceMap = file.endsWith('.map');