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

package/src/register/swap-or-stop.ts

@@ -0,0 +1,194 @@
+/**
+ * Swap or stop (ADR 0022): under the register, `firebase` and `firebase-admin`
+ * imports resolve to the sandbox. When a resolve lands in the real SDK anyway,
+ * through an absolute path, an npm alias, a link under another name, or a
+ * direct `@firebase/*` import, the import stops before the file loads. The
+ * real SDK never runs, so it never reaches production with this machine's
+ * credentials.
+ *
+ * The package is named by the resolved file's own `package.json`
+ * (`package-identity.ts`), never by its folder. Only files under a
+ * `node_modules` directory are checked: every installed SDK lives under one,
+ * including the pnpm and bun stores, and the check stays off the resolve path
+ * for everything else.
+ *
+ * The real SDK is allowed only where the swap table chooses it
+ * (`choosesRealFirebase` in `mapping.ts`), or when an SDK file this hook
+ * already allowed imports what its entry needs: a firebase-admin file
+ * reaches only the verifier bridge pair's files, and a client SDK file only
+ * the `@firebase/*` packages the production AI entries import. The importer's
+ * URL alone is no proof, since `createRequire` can name any file, so each
+ * hook keeps the URLs it allowed. In sandbox AI mode that set stays empty.
+ * `firebase-admin` is never chosen, with one exception: the App Check verifier
+ * bridge that production AI mode loads on pyric's behalf (#1552), whose
+ * firebase-admin app holds no credentials. An app's own import of the real
+ * package still stops. `PYRIC_GUARD` does not change any of this: the stop
+ * belongs to the swap, not to the network guard.
+ *
+ * Loaded by both resolve hooks, including the loader-thread one, so it imports
+ * node built-ins and side-effect-free modules only.
+ */
+import { fileURLToPath } from 'node:url';
+import { packageNameOf, pathInPackageOf } from './package-identity.js';
+import { choosesRealFirebase } from './mapping.js';
+import {
+  SDK_MODULES,
+  isAdminBridgeFile,
+  isBypassedBridgeImport,
+  isProductionAiSdkPackage,
+  resolveAiMode,
+  type AiMode,
+} from '../serve/firebase-module-swap.js';
+
+/** The code on the error a stopped import throws. */
+export const REAL_SDK_STOPPED_CODE = 'PYRIC_REAL_SDK_STOPPED';
+
+const LOG_PREFIX = '@pyric/cli/register';
+const REPORT_URL = 'https://github.com/davideast/pyric/issues/new';
+
+/** One resolve the register finished: what was asked, by whom, and where it landed. */
+export interface ResolvedLoad {
+  readonly specifier: string;
+  /** The canonical name of a Turbopack-renamed specifier, when it is one. */
+  readonly canonical?: string | null;
+  readonly importer: string | undefined;
+  readonly url: string;
+  /** Defaults to the mode `PYRIC_AI_MODE` and `PYRIC_AI_PASSTHROUGH` select. */
+  readonly aiMode?: AiMode;
+  /** Defaults to the manifest lookup in `package-identity.ts`. */
+  readonly nameOf?: (url: string) => string | null;
+  /** Defaults to `pathInPackageOf` in `package-identity.ts`. */
+  readonly pathInPackage?: (url: string, packageName: string) => string | null;
+}
+
+type SdkFamily = 'admin' | 'client';
+
+/** `firebase-admin` is the admin SDK; `firebase` and every `@firebase/*` package are the client SDK. */
+function sdkFamilyOf(name: string | null): SdkFamily | null {
+  if (name === 'firebase-admin') return 'admin';
+  const isClientPackage = name === 'firebase' || (name?.startsWith('@firebase/') ?? false);
+  return isClientPackage ? 'client' : null;
+}
+
+function isInstalledFile(url: string): boolean {
+  return url.startsWith('file:') && url.includes('/node_modules/');
+}
+
+/**
+ * Whether this load is an SDK file the hook already allowed, importing what
+ * that SDK entry needs: a firebase-admin file reaches only the files of the
+ * verifier bridge's `firebase-admin/app` and `firebase-admin/app-check`, and a
+ * client SDK file only the `@firebase/*` packages that `firebase/ai`,
+ * `firebase/app` and `firebase/app-check` import. So a `createRequire` forge
+ * from an allowed file gets no further than the entry it came from.
+ */
+function isFromAllowedSdkFile(load: ResolvedLoad, packageName: string, allowedUrls: ReadonlySet<string>): boolean {
+  const importer = load.importer;
+  const isAllowedImporter = importer !== undefined && allowedUrls.has(importer);
+  if (!isAllowedImporter) return false;
+  const importerFamily = sdkFamilyOf((load.nameOf ?? packageNameOf)(importer));
+  if (importerFamily === 'client') return isProductionAiSdkPackage(packageName);
+  const isAdminTarget = importerFamily === 'admin' && packageName === 'firebase-admin';
+  if (!isAdminTarget) return false;
+  const pathOf = load.pathInPackage ?? pathInPackageOf;
+  return isAdminBridgeFile(pathOf(load.url, packageName));
+}
+
+/** Whether this load may reach the real SDK. */
+function isAllowedRealLoad(load: ResolvedLoad, packageName: string, family: SdkFamily, allowedUrls: ReadonlySet<string>): boolean {
+  if (isFromAllowedSdkFile(load, packageName, allowedUrls)) return true;
+  const specifier = load.canonical ?? load.specifier;
+  const aiMode = load.aiMode ?? resolveAiMode(undefined, process.env);
+  if (family === 'admin') return isBypassedBridgeImport(specifier, load.importer, aiMode);
+  const pathOf = load.pathInPackage ?? pathInPackageOf;
+  return choosesRealFirebase({
+    specifier,
+    importer: load.importer,
+    packageName,
+    pathInPackage: () => pathOf(load.url, packageName),
+    aiMode,
+  });
+}
+
+/** The served `firebase/*` import that stands for a `@firebase/*` package, when pyric serves one. */
+function servedImportFor(packageName: string): string | null {
+  const candidate = `firebase/${packageName.slice('@firebase/'.length)}`;
+  const isServed = (SDK_MODULES as readonly string[]).includes(candidate);
+  return isServed ? candidate : null;
+}
+
+/** The import an app writes in place of the one that stopped. */
+function fixFor(family: SdkFamily, packageName: string): string {
+  if (family === 'admin') {
+    return "import firebase-admin by its package name (for example 'firebase-admin/app'), so the register routes it to the sandbox";
+  }
+  if (packageName === 'firebase') {
+    return "import firebase by its package name (for example 'firebase/firestore'), so the register routes it to the sandbox";
+  }
+  const served = servedImportFor(packageName);
+  if (served === null) {
+    return `pyric serves no firebase/* import for '${packageName}', so import a served one (for example 'firebase/firestore'), or move this code out of the sandboxed process`;
+  }
+  return `import '${served}' instead of '${packageName}', so the register routes it to the sandbox`;
+}
+
+function stopMessage(load: ResolvedLoad, family: SdkFamily, packageName: string): string {
+  const consequence = family === 'admin'
+    ? "so it would have run with this machine's Google credentials"
+    : "so it would have reached production with the app's API key";
+  return [
+    `${LOG_PREFIX}: stopped loading the real ${packageName}`,
+    `  import '${load.specifier}'`,
+    `  from   ${load.importer ?? 'the entry point'}`,
+    `  found  ${load.url}`,
+    `Under pyric, ${packageName} resolves to the sandbox. This import didn't, ${consequence}.`,
+    `Fix: ${fixFor(family, packageName)}. To run the real SDK, start this process without @pyric/cli/register.`,
+    `If pyric should have routed this import, report it: ${REPORT_URL}`,
+    `code: ${REAL_SDK_STOPPED_CODE}`,
+  ].join('\n');
+}
+
+/**
+ * Whether this load is Node 22 resolving again a CommonJS file this hook
+ * already allowed. Node 22 resolves a CommonJS file imported from ESM a second
+ * time, by its own path and with no importer; Node 24 does not. That second
+ * pass loads nothing new, so it goes ahead. An app's import of the same file
+ * names its importer, so it still stops.
+ */
+function isCjsReloadOfAllowedFile(load: ResolvedLoad, allowedUrls: ReadonlySet<string>): boolean {
+  const hasNoImporter = load.importer === undefined;
+  const wasAllowed = allowedUrls.has(load.url);
+  if (!hasNoImporter || !wasAllowed) return false;
+  return load.specifier === fileURLToPath(load.url);
+}
+
+/**
+ * The error that stops this load, or `null` when the load may go ahead: it is
+ * not the real SDK, or the swap table chose the real SDK here. `allowedUrls`
+ * is the calling hook's record of the real SDK files it allowed; an allowed
+ * load joins it.
+ */
+export function stopFor(load: ResolvedLoad, allowedUrls: Set<string>): Error | null {
+  if (!isInstalledFile(load.url)) return null;
+  const packageName = (load.nameOf ?? packageNameOf)(load.url);
+  const family = sdkFamilyOf(packageName);
+  if (family === null || packageName === null) return null;
+  if (isCjsReloadOfAllowedFile(load, allowedUrls)) return null;
+  if (isAllowedRealLoad(load, packageName, family, allowedUrls)) {
+    allowedUrls.add(load.url);
+    return null;
+  }
+  const error = new Error(stopMessage(load, family, packageName));
+  return Object.assign(error, { code: REAL_SDK_STOPPED_CODE, url: load.url, specifier: load.specifier });
+}
+
+/** Writes each stop to stderr once per file, so a caught import still shows in the log. */
+export function createStopReporter(write: (line: string) => void): (error: Error) => void {
+  const reported = new Set<string>();
+  return (error) => {
+    const url = (error as { url?: string }).url ?? error.message;
+    if (reported.has(url)) return;
+    reported.add(url);
+    write(`${error.message}\n`);
+  };
+}

package/src/register/worker-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * The register in worker threads.
+ *
+ * Built-in modules and resolve hooks are per thread, so the swap, the stop
+ * and the network guard have to be installed inside each worker as well. The
+ * register installs this wrapper whatever `PYRIC_GUARD` says. Node runs `--import` preloads (from the command
+ * line or `NODE_OPTIONS`) in a worker built from a file, a `data:` URL or ESM
+ * source, and the register then activates there as it does on the main
+ * thread. Two kinds of worker skip it:
+ *
+ *  - a worker built from CommonJS source with `eval: true`, which never runs
+ *    preloads;
+ *  - a worker given its own `execArgv`, when the register came from the
+ *    command line rather than `NODE_OPTIONS`.
+ *
+ * Wrapping `worker_threads.Worker` closes both. The worker still activates
+ * the register only under its own `PYRIC_SANDBOX`, exactly as the main thread
+ * does, so a worker the caller started outside the sandbox stays outside it.
+ */
+import Module, { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+/** The `Worker` options this module reads. */
+interface WorkerOptionsLike {
+  eval?: unknown;
+  execArgv?: unknown;
+}
+
+type WorkerConstructor = new (source: unknown, options?: unknown) => object;
+
+/** Marks a `Worker` this module already wrapped. */
+const GUARDED_WORKER = Symbol.for('pyric.guardedWorker');
+
+/** A `'use strict'` directive, which must stay the first statement. */
+const USE_STRICT = /^(\s*(['"])use strict\2;?[ \t]*\n?)/;
+
+/**
+ * The arguments to build the worker with, so that it loads the register at
+ * `registerUrl`. Returns new values and never changes the caller's.
+ */
+export function guardWorkerArguments(
+  source: unknown,
+  options: WorkerOptionsLike | undefined,
+  registerUrl: string,
+): [unknown, WorkerOptionsLike | undefined] {
+  let guardedSource = source;
+  let guardedOptions = options;
+  if (options?.eval === true && typeof source === 'string') {
+    guardedSource = withRegisterPrefix(source, registerUrl);
+  }
+  if (Array.isArray(options?.execArgv) && !options.execArgv.includes(registerUrl)) {
+    guardedOptions = { ...options, execArgv: [...options.execArgv, '--import', registerUrl] };
+  }
+  return [guardedSource, guardedOptions];
+}
+
+/**
+ * Eval source that first loads the register. `require` exists only when Node
+ * runs the source as CommonJS; ESM source already ran the preload, and the
+ * prefix does nothing there.
+ */
+function withRegisterPrefix(source: string, registerUrl: string): string {
+  const prefix = `typeof require === 'function' && require(${JSON.stringify(fileURLToPath(registerUrl))});\n`;
+  const directive = USE_STRICT.exec(source)?.[1];
+  if (directive === undefined) return `${prefix}${source}`;
+  const separator = directive.endsWith('\n') ? '' : '\n';
+  return `${directive}${separator}${prefix}${source.slice(directive.length)}`;
+}
+
+/**
+ * Replace `workerThreads.Worker` with a subclass that builds every worker with
+ * {@link guardWorkerArguments}. A subclass keeps `instanceof Worker` true.
+ * `workerThreads` defaults to `node:worker_threads`; tests pass a stand-in.
+ */
+export function installWorkerGuard(registerUrl: string, workerThreads?: { Worker: unknown }): void {
+  const target = workerThreads ?? (createRequire(import.meta.url)('node:worker_threads') as { Worker: unknown });
+  const Original = target.Worker as (WorkerConstructor & { [GUARDED_WORKER]?: true }) | undefined;
+  if (typeof Original !== 'function' || Original[GUARDED_WORKER] === true) return;
+  class GuardedWorker extends Original {
+    static readonly [GUARDED_WORKER] = true;
+    constructor(source: unknown, options?: WorkerOptionsLike) {
+      super(...guardWorkerArguments(source, options, registerUrl));
+    }
+  }
+  Object.defineProperty(GuardedWorker, 'name', { value: Original.name });
+  target.Worker = GuardedWorker;
+  // ESM `import { Worker } from 'node:worker_threads'` reads the export as
+  // synced, so publish the replacement there too.
+  if (workerThreads === undefined) Module.syncBuiltinESMExports();
+}

package/src/remote/resolve-host.ts

@@ -6,6 +6,13 @@
  * Shared by the Node remote client (`connectRemoteSandbox`, which
  * `pyric-admin` uses) and the client SDK bootstrap that `@pyric/cli/register`
  * installs (#1082), so both pick the same host for the same process.
+ *
+ * Discovery reads the project's `.pyric/serve.json` and probes the port it
+ * names, without the port scan `discoverServe` falls back to: a host found
+ * only by the scan is never attached to (`selectProjectHost`), and on a
+ * machine where closed ports never answer the scan takes seconds. A process
+ * resolves again at each reconnect, so a scan there would spend the window
+ * its held calls wait in (#1219).
  */
 import {
   discoverServe,
@@ -54,12 +61,17 @@ function warnOncePerUrl(url: string, message: string, warn?: (message: string) =
   else process.stderr.write(`${message}\n`);
 }
 
+/** The project's host as its `.pyric/serve.json` names it; no port scan. */
+export function discoverProjectPointer(cwd: string): Promise<Discovered | null> {
+  return discoverServe(cwd, () => {}, []);
+}
+
 async function resolveConfiguredHost(configuredUrl: string, options: ResolveRemoteHostOptions): Promise<ResolvedRemoteHost> {
   const choice = await selectExplicitHost({
     url: configuredUrl,
     cwd: options.cwd,
     launcherInstanceId: options.instanceId,
-    discover: options.discover,
+    discover: options.discover ?? discoverProjectPointer,
     probe: options.probe,
   });
   if (choice.kind === 'stale') throw hostError('not-found', choice.message);
@@ -73,7 +85,7 @@ async function resolveConfiguredHost(configuredUrl: string, options: ResolveRemo
 
 async function discoverProjectHost(options: ResolveRemoteHostOptions): Promise<ResolvedRemoteHost> {
   const refused: string[] = [];
-  const found = selectProjectHost(await (options.discover ?? discoverServe)(options.cwd), (m) => refused.push(m));
+  const found = selectProjectHost(await (options.discover ?? discoverProjectPointer)(options.cwd), (m) => refused.push(m));
   const hasNoDiscovery = found === null;
   if (hasNoDiscovery) {
     throw hostError(

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

@@ -10,12 +10,14 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ServeLogger } from './server.js';
-import { redactUrl } from 'pyric/ai/internal';
+import { redactUpstreamText, redactUrl } from 'pyric/ai/internal';
 import { sanitizeForTerminal } from './ai-terminal-text.js';
 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, closingHeaders, 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
@@ -64,6 +70,8 @@ type AiProxyFailure =
       status: number;
       /** The upstream's raw `Retry-After` header, when it sent one. */
       retryAfter?: string;
+      /** The credentials the request carried, masked from `retryAfter`. */
+      credentials?: readonly string[];
     }
   | { kind: 'stream-abort'; target: string; latencyMs: number; cause: string };
 
@@ -76,13 +84,17 @@ const AI_PROXY_RETRY_AFTER_MAX = 64;
  * nothing worth printing.
  *
  * The header is remote-authored, so it is sanitized and length-capped like
- * every other upstream string that reaches the terminal. Delta-seconds (the
+ * every other upstream string that reaches the terminal. It is masked of the
+ * request's credentials first, with the masking the gemini engine and proxy
+ * use (`redactUpstreamText`), so the cap cannot leave a prefix of a key
+ * behind. Delta-seconds (the
  * common form) get an `s` suffix so the wait reads as a duration; the
  * HTTP-date form is echoed verbatim, since `Wed, 21 Oct 2026 07:28:00 GMTs`
  * would be nonsense.
  */
-function formatRetryAfter(raw: string): string | null {
-  const clean = sanitizeForTerminal(raw).slice(0, AI_PROXY_RETRY_AFTER_MAX).trim();
+function formatRetryAfter(raw: string, credentials: readonly string[]): string | null {
+  const masked = redactUpstreamText(raw, credentials);
+  const clean = sanitizeForTerminal(masked).slice(0, AI_PROXY_RETRY_AFTER_MAX).trim();
   if (clean === '') return null;
   if (/^\d+$/.test(clean)) return `${clean}s`;
   return clean;
@@ -155,7 +167,7 @@ export function formatAiProxyWarning(failure: AiProxyFailure, source = 'ai-proxy
     );
   }
   if (failure.kind === 'status' && failure.retryAfter !== undefined) {
-    const wait = formatRetryAfter(failure.retryAfter);
+    const wait = formatRetryAfter(failure.retryAfter, failure.credentials ?? []);
     if (wait !== null) {
       lines.push(`      Retry-After: ${wait}, no automatic retry; the status went to the caller`);
     }
@@ -223,6 +235,28 @@ export function permitAiUpstreams(ai: {
   for (const destination of destinations) permitGuardHost(destination);
 }
 
+/** The `key` parameter of `target`, or null when it has none or is not a URL. */
+function urlKeyParam(target: string): string | null {
+  try {
+    return new URL(target).searchParams.get('key');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The credentials an upstream request carries: the `key` URL parameter, the
+ * `x-goog-api-key` header, and the `Authorization` value without its scheme.
+ */
+function requestCredentials(input: Parameters<typeof fetch>[0], init: RequestInit | undefined): string[] {
+  const isRequest = input instanceof Request;
+  const headers = new Headers(isRequest ? input.headers : init?.headers);
+  const urlKey = urlKeyParam(isRequest ? input.url : String(input));
+  const authorization = headers.get('authorization')?.replace(/^\S+\s+/, '') ?? null;
+  const found = [urlKey, headers.get('x-goog-api-key'), authorization];
+  return found.filter((value): value is string => value !== null && value !== '');
+}
+
 /** Shared upstream I/O for the browser proxy and the direct Node engine.
  * Responses remain incremental; cancellation stops reading without a warning.
  */
@@ -249,7 +283,7 @@ export async function fetchAiUpstream(
   if (failed) {
     const retryAfter = upstream.headers.get('retry-after');
     note({ kind: 'status', target, latencyMs: Date.now() - startedAt, status: upstream.status,
-      ...(retryAfter !== null ? { retryAfter } : {}) });
+      ...(retryAfter !== null ? { retryAfter, credentials: requestCredentials(input, init) } : {}) });
   }
   const body = upstream.body;
   const hasNoBody = body === null;
@@ -280,6 +314,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, closingHeaders({ '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 +343,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 +376,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 +404,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 +424,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.
  *