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

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/ai-diagnostics-relay.ts

@@ -11,7 +11,8 @@ import { capTerminalText } from './ai-terminal-text.js';
  * agent driving `pyric dev` in process therefore saw NOTHING.
  *
  *   - `request_rejected`: a bad role, empty `contents`, a missing thought
- *     signature, or an engine that answered an error envelope.
+ *     signature, a request without a valid App Check token, or an engine
+ *     that answered an error envelope.
  *   - `response_blocked`: the SILENT refusal. A safety / recitation /
  *     blocklist filter answers HTTP 200 with an empty candidate, so nothing
  *     throws anywhere and the app simply renders nothing.
@@ -73,6 +74,8 @@ interface AiRejectionRelayPayload {
   code?: number;
   /** The rejection reason: production's own message for shape errors. */
   message: string;
+  /** Pyric's guidance beside production's message, such as the App Check gate's. */
+  hint?: string;
 }
 
 /** Shape POSTed for a `response_blocked` event. Carries the wire's own
@@ -148,6 +151,8 @@ function toRejectionPayload(event: ServiceMutation): AiRejectionRelayPayload | n
   payload.engine = detailText(detail, 'engine');
   payload.status = detailText(detail, 'status');
   if (typeof detail.code === 'number') payload.code = detail.code;
+  const hint = detailText(detail, 'hint');
+  if (hint !== undefined) payload.hint = hint;
   return payload;
 }
 

package/src/serve/ai-proxy.ts

@@ -16,6 +16,8 @@ import type { AiEngineConfigWire } from './worker/protocol.js';
 import { permitGuardHost } from '../register/net-guard.js';
 import { FIREBASE_AI_LOGIC_HOST } from '../google-endpoints.js';
 import type { AiMode } from './firebase-module-swap.js';
+import { HOSTED_METHOD_BODY_LIMIT } from './hosted/method-protocol.js';
+import { BODY_TOO_LARGE_CODE, collectRawBody } from '../bridge/server/peer.js';
 
 /** The dev server's diagnostics throttle, as this module needs it: the
  *  denials route owns the instance, and the proxy shares it so a failing
@@ -30,6 +32,10 @@ export const AI_PROXY_DEFAULT_UPSTREAM = 'http://localhost:11434/v1';
 /** The route the dev server mounts for OpenAI-compatible traffic. */
 export const AI_PROXY_ROUTE = '/__pyric/ai-proxy';
 
+/** Largest request body the proxy forwards: the hosted method route's limit,
+ *  which already carries AI requests with inline images. */
+export const AI_PROXY_BODY_LIMIT_BYTES = HOSTED_METHOD_BODY_LIMIT;
+
 /**
  * Request headers that must NOT be forwarded upstream: origin-sensitive
  * browser context (`origin`/`referer`/`cookie`, since the upstream is a
@@ -280,6 +286,25 @@ export async function fetchAiUpstream(
   });
 }
 
+/**
+ * Read an AI proxy request's body, at most {@link AI_PROXY_BODY_LIMIT_BYTES}.
+ * Past the limit it answers 413, and on a broken upload 400, and returns
+ * null: the caller sends nothing upstream. Both proxy routes read through it.
+ */
+export async function readAiProxyBody(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<Uint8Array<ArrayBuffer> | null> {
+  try {
+    return await collectRawBody(req, AI_PROXY_BODY_LIMIT_BYTES);
+  } catch (error) {
+    const tooLarge = (error as { code?: unknown }).code === BODY_TOO_LARGE_CODE;
+    const status = tooLarge ? 413 : 400;
+    res.writeHead(status, { 'content-type': 'text/plain' }).end(tooLarge ? 'Payload Too Large' : 'Bad Request');
+    return null;
+  }
+}
+
 /**
  * Handle `POST /__pyric/ai-proxy/<suffix>`: a same-origin passthrough to the
  * configured OpenAI-compatible upstream, so the browser openai engine
@@ -290,7 +315,11 @@ export async function fetchAiUpstream(
  *   - POST only (the OpenAI chat-completions surface is POST); 405 otherwise.
  *   - the path suffix + query ride through verbatim
  *     (`/__pyric/ai-proxy/chat/completions` becomes `<upstream>/chat/completions`).
- *   - the request body is forwarded verbatim; headers minus the
+ *   - the caller must pass the namespace's loopback guard (Host, and an
+ *     Origin naming this server when one is sent), which the namespace runs
+ *     before this handler: the upstream may carry the developer's key.
+ *   - the request body is forwarded verbatim, up to
+ *     {@link AI_PROXY_BODY_LIMIT_BYTES} (413 past it); headers minus the
  *     origin-sensitive/hop-by-hop set above (`authorization` DOES forward,
  *     since upstreams may require a key).
  *   - the response body is STREAMED through chunk-by-chunk. SSE passthrough
@@ -319,17 +348,9 @@ export async function handleAiProxy(
   const suffix = url.pathname.slice(AI_PROXY_ROUTE.length);
   const target = `${upstreamBase}${suffix}${url.search}`;
 
-  // Buffer the REQUEST body (small JSON payloads); the RESPONSE streams.
-  const raw = await new Promise<Buffer>((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    req.on('data', (c: Buffer) => chunks.push(c));
-    req.on('end', () => resolve(Buffer.concat(chunks)));
-    req.on('error', reject);
-  });
-  // Copy into a plain-ArrayBuffer view; fetch's BodyInit typing rejects
-  // Buffer's ArrayBufferLike backing.
-  const body = new Uint8Array(raw.byteLength);
-  body.set(raw);
+  // The request body is a bounded JSON payload, read once; the RESPONSE streams.
+  const body = await readAiProxyBody(req, res);
+  if (body === null) return;
 
   const headers: Record<string, string> = {};
   for (const [key, value] of Object.entries(req.headers)) {
@@ -355,6 +376,16 @@ export async function handleAiProxy(
     return;
   }
 
+  await relayAiUpstream(upstream, res);
+}
+
+/**
+ * Send an upstream's answer to the caller: its status and content type, then
+ * the body chunk by chunk. SSE passthrough must never buffer. A dropped
+ * client cancels the upstream read so an abandoned stream doesn't keep the
+ * upstream generating.
+ */
+export async function relayAiUpstream(upstream: Response, res: ServerResponse): Promise<void> {
   const responseHeaders: Record<string, string> = { 'cache-control': 'no-store' };
   const contentType = upstream.headers.get('content-type');
   if (contentType) responseHeaders['content-type'] = contentType;
@@ -365,8 +396,6 @@ export async function handleAiProxy(
   }
   (res as ServerResponse & { flushHeaders?: () => void }).flushHeaders?.();
 
-  // Chunk-by-chunk passthrough. A dropped client cancels the upstream read
-  // so an abandoned SSE stream doesn't keep the upstream generating.
   const reader = upstream.body.getReader();
   res.on('close', () => {
     void reader.cancel().catch(() => {});

package/src/serve/ai-terminal-blocks.ts

@@ -30,6 +30,8 @@ export interface AiRejectionPayload {
   code?: unknown;
   /** The rejection reason: production's own message for shape errors. */
   message?: unknown;
+  /** Pyric's guidance beside production's message, such as the App Check gate's. */
+  hint?: unknown;
 }
 
 /** Loosely-typed mirror of the AI blocked-response payload. Unlike a
@@ -99,10 +101,10 @@ function formatModelLine(model: unknown, engine: unknown): string | null {
 /**
  * Format a relayed AI broker rejection into the compact terminal block, the
  * same `  [pyric] ...` idiom the denial relay and the ai-proxy warning print.
- * Three lines at most: the reason production itself gives, then the model
- * (with the resolved engine, since a rejection reads very differently for
- * `scripted` than for a real upstream), then the wire status. Exported for
- * unit tests.
+ * The reason production itself gives, then the model (with the resolved
+ * engine, since a rejection reads very differently for `scripted` than for a
+ * real upstream), then the wire status, then pyric's guidance when the broker
+ * gave one (the App Check gate does). Exported for unit tests.
  */
 export function formatAiRejectionBlock(payload: AiRejectionPayload): string {
   const message = readText(payload.message) ?? 'request rejected';
@@ -117,6 +119,8 @@ export function formatAiRejectionBlock(payload: AiRejectionPayload): string {
     if (code !== null) suffix = ` (${code})`;
     lines.push(`      ${label}${suffix}`);
   }
+  const hint = readText(payload.hint);
+  if (hint !== null) lines.push(`      ${hint}`);
   return lines.join('\n');
 }
 

package/src/serve/ai-terminal-text.ts

@@ -37,6 +37,17 @@ export function capTerminalText(text: string): string {
 const TERMINAL_UNSAFE_CHARS =
   /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g;
 
+/**
+ * Replace control, bidi-override and line-separator characters with spaces,
+ * and change nothing else: no flattening, no whitespace collapsing, no cut.
+ * For one line of text a reader copies out of the terminal, such as a
+ * pasteable command or JSON fixture, where the exact spacing and the whole
+ * length matter. The caller splits lines first and bounds the total.
+ */
+export function stripTerminalControls(text: string): string {
+  return text.replace(TERMINAL_UNSAFE_CHARS, ' ');
+}
+
 /**
  * Flatten an upstream-authored string into ONE terminal-safe line.
  *

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'))