@pyric/cli 0.1.0-alpha.19 → 0.1.0-alpha.21

package/src/serve/ai-status.ts

@@ -0,0 +1,109 @@
+/**
+ * The AI line in the dev server's startup banner.
+ *
+ * AI is the only live service that used to boot silently: hosting, sandbox
+ * bundles, rules, Studio, the bridge and persistence all announce themselves,
+ * so "nothing about AI" read as "AI isn't part of this server" rather than
+ * "AI is here, unconfigured". One description ({@link describeAiStatus}),
+ * rendered in the two dev-server flavors, so the `pyric dev` banner and the
+ * Vite plugin can never disagree about what AI resolved to.
+ */
+import type { AiEngineConfigWire } from './worker/protocol.js';
+import { GEMINI_DEFAULT_BASE_URL, redactUrl } from 'pyric/ai/internal';
+import { AI_PROXY_ROUTE, resolveAiProxyUpstream } from './ai-proxy.js';
+import { sanitizeForTerminal } from './ai-terminal-text.js';
+
+/**
+ * What the dev server itself knows about AI by the time it finishes booting.
+ *
+ * Everything here is resolved SYNCHRONOUSLY at bootstrap: the plugin's
+ * `ai.engine`/`ai.model` (already reduced to the worker wire shape) and the
+ * proxy upstream. Nothing in this shape forces a broker, a page, or an
+ * upstream connection into existence just to be reported. The engine is
+ * instantiated lazily, on the first `ai.*` op, in the page or the worker.
+ */
+export interface AiStartupStatus {
+  /** Engine resolved by the dev server (the Vite plugin's `ai.engine` /
+   *  `ai.model`). Absent means nothing server-side: the served page's own
+   *  `getAI(...)` chooses the engine at runtime, and the server cannot know
+   *  which (there is no CLI surface for it under `pyric dev`). */
+  engine?: AiEngineConfigWire;
+  /** `ai.mode`: `production` passes through to Google AI instead of mirroring. */
+  mode?: 'sandbox' | 'production';
+  /** Configured OpenAI-compatible upstream (`ai.proxyUpstream`). Absent falls
+   *  back to `PYRIC_AI_PROXY_UPSTREAM`, then the local-Ollama default. */
+  proxyUpstream?: string;
+}
+
+/** Where the resolved proxy upstream came from, in the terminal's words. The
+ *  provenance is the point of the line: a developer has to be able to tell a
+ *  deliberate upstream from the Ollama default nobody chose, so every source
+ *  names the knob that set it. */
+function describeUpstreamProvenance(source: 'option' | 'env' | 'default'): string {
+  if (source === 'option') return ' (ai.proxyUpstream)';
+  if (source === 'env') return ' (PYRIC_AI_PROXY_UPSTREAM)';
+  return ' (default)';
+}
+
+/** The openai engine's model binding, which may not be pinned at all. */
+function describeOpenAiModel(model: string | undefined): string {
+  if (model === undefined) return 'no model pinned';
+  return `model ${sanitizeForTerminal(model)}`;
+}
+
+/** Mark + body for one AI status line, in both terminal flavors. */
+function describeAiStatus(status: AiStartupStatus): { mark: string; body: string } {
+  const upstream = resolveAiProxyUpstream(status.proxyUpstream);
+  const provenance = describeUpstreamProvenance(upstream.source);
+  const proxyChain = `${AI_PROXY_ROUTE} → ${redactUrl(upstream.target)}${provenance}`;
+
+  const engine = status.engine;
+  if (engine === undefined) {
+    // Visible absence, the `• rules    no firestore.rules ...` idiom: AI
+    // silence used to be indistinguishable from AI-not-wired-up.
+    return {
+      mark: '•',
+      body: `no engine configured; the served page's getAI() picks one; ${proxyChain}`,
+    };
+  }
+  if (engine.kind === 'openai') {
+    const model = describeOpenAiModel(engine.model);
+    const baseUrl = engine.baseUrl ?? AI_PROXY_ROUTE;
+    let endpoint = proxyChain;
+    if (baseUrl !== AI_PROXY_ROUTE) {
+      endpoint = `${redactUrl(baseUrl)} (direct, bypasses ${AI_PROXY_ROUTE})`;
+    }
+    return { mark: '✔', body: `openai (${model}) → ${endpoint}` };
+  }
+  if (engine.kind === 'gemini') {
+    let passthrough = '';
+    if (status.mode === 'production') passthrough = 'production passthrough, ';
+    const hasKey = engine.apiKey !== undefined && engine.apiKey !== '';
+    let key = 'no API key; set GEMINI_API_KEY';
+    if (hasKey) key = 'API key set';
+    let endpoint = GEMINI_DEFAULT_BASE_URL;
+    if (engine.baseUrl !== undefined) endpoint = redactUrl(engine.baseUrl);
+    return { mark: '✔', body: `gemini (${passthrough}${key}) → ${endpoint}` };
+  }
+  const responses = engine.script?.length ?? 0;
+  return { mark: '✔', body: `scripted (${responses} canned response(s), no network)` };
+}
+
+/**
+ * The banner line for `pyric dev`'s aligned status column (`✔ hosting  ...`).
+ * Exported for unit tests.
+ */
+export function formatAiStatusLine(status: AiStartupStatus): string {
+  const { mark, body } = describeAiStatus(status);
+  return `${mark} ai       ${body}`;
+}
+
+/**
+ * The same report in the Vite dev server's flavor (`  ✔ [pyric] ...`, the
+ * idiom `vite-functions-development.ts` prints). Same content, so the two
+ * dev-server front doors never disagree about what AI resolved to.
+ */
+export function formatAiStatusNote(status: AiStartupStatus): string {
+  const { mark, body } = describeAiStatus(status);
+  return `  ${mark} [pyric] ai: ${body}`;
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Terminal blocks for the AI diagnostics relayed to `POST /__pyric/denials`.
+ *
+ * Three things ride that route besides a rules denial, and each gets one
+ * record in {@link AI_TERMINAL_BLOCKS}: the loosely-typed wire payload, the
+ * formatter that renders it, and the two strings the route's throttle keys it
+ * by. Adding a fourth kind is one entry here plus its narrower in
+ * `ai-diagnostics-relay.ts`; the route itself dispatches through the table and
+ * never grows another branch.
+ *
+ * Every payload field is JSON from the served page, so nothing here trusts a
+ * type: each field is re-checked, and every remote-authored string goes
+ * through the URL redaction and terminal sanitizing in `ai-terminal-text.ts`.
+ */
+import type { AiDiagnosticKind } from './ai-diagnostics-relay.js';
+import { redactUrl } from 'pyric/ai/internal';
+import { sanitizeForTerminal } from './ai-terminal-text.js';
+
+/** Loosely-typed mirror of the AI rejection payload POSTed by
+ *  `ai-diagnostics-relay.ts` (the wire shape lives there). */
+export interface AiRejectionPayload {
+  /** `'ai-rejection'`: what tells the route the body is NOT a rules denial. */
+  kind?: unknown;
+  /** Model resource the rejected op targeted. */
+  model?: unknown;
+  /** Resolved broker engine (`scripted` | `openai` | `gemini` | `custom`). */
+  engine?: unknown;
+  /** Wire error status (e.g. `INVALID_ARGUMENT`) and HTTP-ish code. */
+  status?: unknown;
+  code?: unknown;
+  /** The rejection reason: production's own message for shape errors. */
+  message?: unknown;
+}
+
+/** Loosely-typed mirror of the AI blocked-response payload. Unlike a
+ *  rejection this carries no `message`: a filter block has no error envelope
+ *  at all (HTTP 200, empty candidate), only the wire's reason enums, so the
+ *  phrasing is this file's job. */
+export interface AiBlockedPayload {
+  /** `'ai-blocked'`: what tells the route the body is a filter block. */
+  kind?: unknown;
+  /** Model resource the blocked op targeted. */
+  model?: unknown;
+  /** Resolved broker engine (`scripted` | `openai` | `gemini` | `custom`). */
+  engine?: unknown;
+  /** Candidate-level block: `SAFETY`, `RECITATION`, `BLOCKLIST`, and so on. */
+  finishReason?: unknown;
+  /** Production's own explanatory text for the block, when it sent one. */
+  finishMessage?: unknown;
+  /** Prompt-level block: `promptFeedback.blockReason`. */
+  blockReason?: unknown;
+}
+
+/** Loosely-typed mirror of the AI model-substitution payload. Not a refusal:
+ *  the request SUCCEEDED, answered by a model the developer never named,
+ *  which is why nothing else in the stack reports it. */
+export interface AiModelSubstitutionPayload {
+  /** `'ai-model-substituted'`: what tells the route the body is a swap. */
+  kind?: unknown;
+  /** The model the request asked for. */
+  requestedModel?: unknown;
+  /** The model the engine actually calls. */
+  effectiveModel?: unknown;
+  /** Resolved broker engine (`openai` | `gemini` | ...). */
+  engine?: unknown;
+  /** Why it differs, e.g. `engine modelMap`, `experimental alias`. */
+  reason?: unknown;
+}
+
+/** What the route reads off a body before it knows which kind it holds. */
+export type AiDiagnosticPayload = AiRejectionPayload & AiBlockedPayload & AiModelSubstitutionPayload;
+
+/** A non-empty string field, sanitized, or `null` when the wire omitted it. */
+function readText(value: unknown): string | null {
+  if (typeof value !== 'string' || value === '') return null;
+  return sanitizeForTerminal(redactUrl(value));
+}
+
+/** A raw (unsanitized) string field, for throttle keys that never print. */
+function readRawText(value: unknown, fallback: string): string {
+  if (typeof value !== 'string' || value === '') return fallback;
+  return value;
+}
+
+/**
+ * The `model: <id> (engine: <name>)` line shared by the rejection and block
+ * formatters, which report the same fact in the same place. Degrades to an
+ * engine-only line, and to nothing at all when the event carried neither.
+ */
+function formatModelLine(model: unknown, engine: unknown): string | null {
+  const flatModel = readText(model);
+  const flatEngine = readText(engine);
+  if (flatModel === null && flatEngine === null) return null;
+  if (flatModel === null) return `      engine: ${flatEngine}`;
+  if (flatEngine === null) return `      model: ${flatModel}`;
+  return `      model: ${flatModel} (engine: ${flatEngine})`;
+}
+
+/**
+ * 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.
+ */
+export function formatAiRejectionBlock(payload: AiRejectionPayload): string {
+  const message = readText(payload.message) ?? 'request rejected';
+  const lines = [`  ⚠ [pyric] ai request rejected: ${message}`];
+  const modelLine = formatModelLine(payload.model, payload.engine);
+  if (modelLine !== null) lines.push(modelLine);
+  const status = readText(payload.status);
+  const code = typeof payload.code === 'number' ? payload.code : null;
+  if (status !== null || code !== null) {
+    const label = status ?? 'ERROR';
+    let suffix = '';
+    if (code !== null) suffix = ` (${code})`;
+    lines.push(`      ${label}${suffix}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format a relayed AI filter block, in the same three lines as
+ * {@link formatAiRejectionBlock}: the wire's own reason, the model + resolved
+ * engine, then WHY there is no content. That third line matters more here
+ * than for a rejection: a block throws nothing, so the only symptom a
+ * developer sees is an empty answer, and production's `finishMessage` (when
+ * it sent one) is the whole explanation. Exported for unit tests.
+ */
+export function formatAiBlockedBlock(payload: AiBlockedPayload): string {
+  const finishReason = readText(payload.finishReason);
+  const blockReason = readText(payload.blockReason);
+  const reason = finishReason ?? blockReason ?? 'unknown';
+  const lines = [`  ⚠ [pyric] ai response blocked: ${reason}`];
+  const modelLine = formatModelLine(payload.model, payload.engine);
+  if (modelLine !== null) lines.push(modelLine);
+  const finishMessage = readText(payload.finishMessage);
+  if (finishMessage !== null) {
+    lines.push(`      ${finishMessage}`);
+  } else if (finishReason === null && blockReason !== null) {
+    lines.push('      the prompt was blocked before generation; no candidates were returned');
+  } else {
+    lines.push('      no content was returned; text() and functionCalls() throw for this finish reason');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format a relayed AI model substitution into ONE terminal line, a single
+ * line on purpose: there is no error, no status, and no missing content to
+ * explain. The whole fact IS the arrow, and the parenthetical says which
+ * engine did it and why (`engine modelMap`, `experimental alias`, ...).
+ * Exported for unit tests.
+ */
+export function formatAiModelSubstitutionBlock(payload: AiModelSubstitutionPayload): string {
+  const requested = readText(payload.requestedModel) ?? 'unknown';
+  const effective = readText(payload.effectiveModel) ?? 'unknown';
+  const engine = readText(payload.engine);
+  const reason = readText(payload.reason);
+  const attribution = [engine, reason].filter((part) => part !== null);
+  let suffix = '';
+  if (attribution.length > 0) suffix = ` (${attribution.join(', ')})`;
+  return `  ⚠ [pyric] ai model substituted: ${requested} → ${effective}${suffix}`;
+}
+
+/**
+ * One record per AI diagnostic kind: how it prints, and the (target, reason)
+ * pair the denials route throttles it by.
+ *
+ * The prefixes on `throttleTarget` keep an AI key from colliding with a
+ * rules-denial key built from a Firestore path, or with each other: a
+ * rejection, a block, and a substitution on the same model are three
+ * different problems. `throttleReason` is each kind's identity: a block has
+ * no message of its own, so its reason enum is what collapses an agent's
+ * retry loop into one line, and a substitution's identity is the model it
+ * actually called, so a swap onto a DIFFERENT model still prints.
+ */
+export interface AiTerminalBlock {
+  format(payload: AiDiagnosticPayload): string;
+  throttleTarget(payload: AiDiagnosticPayload): string;
+  throttleReason(payload: AiDiagnosticPayload): string;
+}
+
+const AI_TERMINAL_BLOCKS: { [K in AiDiagnosticKind]: AiTerminalBlock } = {
+  'ai-rejection': {
+    format: formatAiRejectionBlock,
+    throttleTarget: (payload) => `ai-rejection ${readRawText(payload.model, '')}`,
+    throttleReason: (payload) => readRawText(payload.message, 'request rejected'),
+  },
+  'ai-blocked': {
+    format: formatAiBlockedBlock,
+    throttleTarget: (payload) => `ai-blocked ${readRawText(payload.model, '')}`,
+    throttleReason: (payload) =>
+      readRawText(payload.finishReason, readRawText(payload.blockReason, 'unknown')),
+  },
+  'ai-model-substituted': {
+    format: formatAiModelSubstitutionBlock,
+    throttleTarget: (payload) => `ai-model ${readRawText(payload.requestedModel, '')}`,
+    throttleReason: (payload) => readRawText(payload.effectiveModel, 'unknown'),
+  },
+};
+
+/** The record for a relayed body's `kind`, or `null` when the body is a rules
+ *  denial (or anything else this route does not recognize). */
+export function aiTerminalBlockFor(kind: unknown): AiTerminalBlock | null {
+  if (typeof kind !== 'string') return null;
+  if (!Object.hasOwn(AI_TERMINAL_BLOCKS, kind)) return null;
+  return AI_TERMINAL_BLOCKS[kind as AiDiagnosticKind];
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Terminal-safe rendering of remote-authored text.
+ *
+ * Every AI diagnostic the dev server prints quotes a string somebody else
+ * wrote: a broker rejection reason, a model server's finish message, a
+ * `Retry-After` header, a model id out of a project config. The terminal is
+ * not a sandbox, so that text is flattened onto one line, stripped of control
+ * and bidi characters (the same treatment `activity-warning.ts` gives incident
+ * text), and cut to a fixed length. Without the cut, one field of a remote
+ * payload can push the rest of a diagnostic block off the screen.
+ *
+ * Leaf module: it imports nothing, so the browser-side diagnostics relay can
+ * share it without pulling the dev server's formatting code into a served
+ * bundle. Credential masking is a separate concern and comes from
+ * `pyric/ai/internal`, which publishes the broker's own `redactUrl`.
+ */
+
+/**
+ * Longest remote-authored string echoed into one terminal field, and the
+ * longest one the browser-side relay puts on the wire. Broker rejection
+ * reasons run to a few hundred characters at most, so anything past this is
+ * an upstream dumping a payload into a message field.
+ */
+export const AI_TERMINAL_TEXT_MAX = 512;
+
+/** Appended when text is cut, so a truncated line never reads as complete. */
+const TRUNCATION_MARKER = '\u2026';
+
+/** Cut text to {@link AI_TERMINAL_TEXT_MAX}, marking the cut. */
+export function capTerminalText(text: string): string {
+  if (text.length <= AI_TERMINAL_TEXT_MAX) return text;
+  return `${text.slice(0, AI_TERMINAL_TEXT_MAX)}${TRUNCATION_MARKER}`;
+}
+
+/** Control, bidi-override, and line-separator characters. A remote string
+ *  carrying these can forge a terminal line or reverse the text around it. */
+const TERMINAL_UNSAFE_CHARS =
+  /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g;
+
+/**
+ * Flatten an upstream-authored string into ONE terminal-safe line.
+ *
+ * Broker rejection reasons are production's own messages, and several are
+ * multi-line (`ai-error-empty-contents` is a bulleted list): pasted verbatim
+ * they shred the indented block into fragments. Control and bidi characters
+ * get dropped for the same reason `activity-warning.ts` drops them: the text
+ * can originate from a remote model server, and the terminal is not a sandbox.
+ */
+export function sanitizeForTerminal(text: string): string {
+  const flattened = text.replace(TERMINAL_UNSAFE_CHARS, ' ').replace(/\s+/g, ' ').trim();
+  return capTerminalText(flattened);
+}

package/src/serve/beacon-route.ts

@@ -0,0 +1,141 @@
+/**
+ * `POST /__pyric/beacon`, the host half of the interception handshake.
+ *
+ * `@pyric/cli/register` posts here once per activated child, after its module
+ * hooks and net-guard are installed. Receiving it is the only positive proof
+ * the dev server has that `NODE_OPTIONS=--import @pyric/cli/register` actually
+ * reached that process; everything else about the launch is an assumption. See
+ * `register/beacon.ts` for why the child reports on two channels.
+ *
+ * Who may post, and why it is locked down
+ * ---------------------------------------
+ * The dev server is reachable from any page the developer happens to have
+ * open, so an unauthenticated route here would let a web page disarm the
+ * watchdog (post a beacon the launcher counts) and would let any page grow the
+ * server's memory with an unbounded body. Four checks close that, in order:
+ *
+ *  1. `content-type: application/json`. A cross-origin page cannot send that
+ *     header on a POST without a CORS preflight, and this server answers no
+ *     `OPTIONS` on this path, so the browser never sends the real request.
+ *  2. No `Origin` header and no `Sec-Fetch-Mode: cors`. A browser attaches one
+ *     or both to every cross-site request it makes; a Node child attaches
+ *     neither.
+ *  3. A per-launch secret in `x-pyric-beacon-token`, which the launcher put in
+ *     the child's environment as `PYRIC_BEACON_TOKEN`. A page cannot read it.
+ *  4. A 4 KB body cap. A report is under 200 bytes.
+ *
+ * Everything that passes those checks is still best-effort: a malformed body
+ * gets 204 and is dropped, because the consequence of an absent beacon is a
+ * warning on the parent side and must never be a failure on the child's.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { BODY_TOO_LARGE_CODE, collectBody } from '../bridge/server/peer.js';
+import { getHeader } from './server.js';
+import { BEACON_TOKEN_HEADER, type BeaconReport } from '../register/beacon.js';
+
+/** Largest beacon body accepted. A report is well under 200 bytes. */
+export const BEACON_BODY_LIMIT_BYTES = 4_096;
+
+export interface BeaconRouteOptions {
+  /** The per-launch secret the child must present. */
+  readonly token: string;
+  /** Receives each accepted report. Absent means the route still 204s. */
+  readonly onBeacon?: (report: BeaconReport) => void;
+}
+
+/** Constant-time string comparison over the token bytes. */
+function tokenMatches(presented: string | undefined, expected: string): boolean {
+  if (presented === undefined) return false;
+  const a = Buffer.from(presented, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Whether the request carries the browser markings of a cross-site fetch. */
+function isBrowserOriginated(req: IncomingMessage): boolean {
+  if (getHeader(req, 'origin') !== undefined) return true;
+  return getHeader(req, 'sec-fetch-mode') === 'cors';
+}
+
+/** Whether the body is declared as JSON, the header a page cannot set without
+ *  a preflight this server never answers. */
+function declaresJsonBody(req: IncomingMessage): boolean {
+  const contentType = getHeader(req, 'content-type');
+  if (contentType === undefined) return false;
+  return contentType.split(';')[0]!.trim().toLowerCase() === 'application/json';
+}
+
+/**
+ * Read a beacon body defensively. It is JSON off a socket, and the only fields
+ * that matter are the ones the parent reports. `null` for anything that does
+ * not carry a plausible report.
+ */
+export function parseBeaconReport(value: unknown): BeaconReport | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.pid !== 'number' || !Number.isFinite(raw.pid)) return null;
+  const guard = raw.guard;
+  if (guard !== 'warn' && guard !== 'block' && guard !== 'off') return null;
+  if (typeof raw.hooks !== 'boolean') return null;
+  return {
+    pid: raw.pid,
+    guard,
+    hooks: raw.hooks,
+    sandbox: typeof raw.sandbox === 'string' ? raw.sandbox : '',
+  };
+}
+
+/** The one terminal line confirming a child is interlocked. A beacon that
+ *  reports `hooks: false` is the interesting case: the child is running the
+ *  register module, and it is telling us the rewrite did not install. */
+export function formatBeaconReceipt(report: BeaconReport): string {
+  if (!report.hooks) {
+    return (
+      `  ⚠ interlock pid=${report.pid}: register loaded but module hooks did NOT install. ` +
+      `That process's firebase-admin/firebase imports are NOT routed to the sandbox ` +
+      `(Node >= 22.15 is required for full coverage). Net-guard mode ${report.guard}.`
+    );
+  }
+  return `  ⓘ interlock pid=${report.pid}: sandbox interception confirmed live (guard=${report.guard})`;
+}
+
+/** Handle `POST /__pyric/beacon`. */
+export async function handleBeacon(
+  opts: BeaconRouteOptions,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  if (req.method !== 'POST') {
+    res.writeHead(405, { allow: 'POST' }).end('method not allowed');
+    return;
+  }
+  if (!declaresJsonBody(req)) {
+    res.writeHead(415, { 'content-type': 'text/plain' }).end('Unsupported Media Type');
+    return;
+  }
+  if (isBrowserOriginated(req)) {
+    res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: browser origin');
+    return;
+  }
+  if (!tokenMatches(getHeader(req, BEACON_TOKEN_HEADER), opts.token)) {
+    res.writeHead(401, { 'content-type': 'text/plain' }).end('Unauthorized: invalid beacon token');
+    return;
+  }
+  let body: unknown;
+  try {
+    body = await collectBody(req, BEACON_BODY_LIMIT_BYTES);
+  } catch (err) {
+    if ((err as { code?: string }).code === BODY_TOO_LARGE_CODE) {
+      res.writeHead(413, { 'content-type': 'text/plain' }).end('Payload Too Large');
+      return;
+    }
+    // Malformed JSON: drop it. Proof-of-life is a side channel.
+    res.writeHead(204).end();
+    return;
+  }
+  const report = parseBeaconReport(body);
+  if (report !== null) opts.onBeacon?.(report);
+  res.writeHead(204).end();
+}

package/src/serve/bundler.ts

@@ -52,7 +52,7 @@ export function defaultSdkEntries(): Record<string, string> {
     if (existsSync(js)) return js;
     const ts = join(here, 'entries', `${name}.ts`);
     if (existsSync(ts)) return ts;
-    throw new Error(`pyric dev: missing SDK entry '${name}' next to ${here}`);
+    throw new Error(`pyric sandbox: missing SDK entry '${name}' next to ${here}`);
   };
   return {
     ai: pick('ai'),
@@ -94,7 +94,7 @@ export function pyricPackageRoot(): string {
   }
   const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string };
   if (pkg.name !== 'pyric') {
-    throw new Error(`pyric dev: expected to resolve the pyric package, found '${pkg.name}' at ${dir}`);
+    throw new Error(`pyric sandbox: expected to resolve the pyric package, found '${pkg.name}' at ${dir}`);
   }
   return dir;
 }
@@ -131,7 +131,7 @@ export const NODE_BUILTIN_RE = /^(node:)?(url|fs|path)$/;
  *  through its own resolveId/load + optimizeDeps esbuild pass, instead of
  *  re-deriving them. */
 export const NODE_BUILTIN_SHIMS: Record<string, string> = {
-  fs: `const no = () => { throw new Error('pyric dev: fs is not available in the browser'); };
+  fs: `const no = () => { throw new Error('pyric sandbox: fs is not available in the browser'); };
 export const readFileSync = no; export const existsSync = () => false;
 export const readdirSync = no; export const writeFileSync = no; export const mkdirSync = no;
 export default { readFileSync, existsSync, readdirSync, writeFileSync, mkdirSync };`,
@@ -315,13 +315,13 @@ export async function bundleSdk(opts: BundleOptions): Promise<BundleResult> {
       // self-identify as the sandbox shim, not the real Firebase SDK.
       chunkNames: 'pyric-sandbox-[hash]',
       banner: {
-        js: '/* pyric dev: pyric sandbox shim serving firebase/* — NOT the real Firebase SDK */',
+        js: '/* pyric sandbox shim serving firebase/*. This is not the real Firebase SDK. */',
       },
       plugins: [pyricResolvePlugin(), nodeShimPlugin()],
     });
     if (result.errors.length > 0) {
       throw new Error(
-        `pyric dev: SDK bundle failed:\n${result.errors.map((e) => e.text).join('\n')}`,
+        `pyric sandbox: SDK bundle failed:\n${result.errors.map((e) => e.text).join('\n')}`,
       );
     }
     writeFileSync(join(outDir, '.complete'), new Date().toISOString());
@@ -348,7 +348,7 @@ export function workerEntryPath(): string {
   if (existsSync(js)) return js;
   const ts = join(here, 'worker', 'entry.ts');
   if (existsSync(ts)) return ts;
-  throw new Error(`pyric dev: missing SharedWorker entry next to ${here}`);
+  throw new Error(`pyric sandbox: missing SharedWorker entry next to ${here}`);
 }
 
 export interface WorkerBundleOptions {
@@ -371,7 +371,7 @@ const WORKER_EPOCH_FILE = '.worker-epoch';
 function readWorkerBundleEpoch(outDir: string): string {
   const epoch = readFileSync(join(outDir, WORKER_EPOCH_FILE), 'utf8').trim();
   if (!/^[a-f0-9]{16}$/.test(epoch)) {
-    throw new Error(`pyric dev: invalid SharedWorker epoch in ${join(outDir, WORKER_EPOCH_FILE)}`);
+    throw new Error(`pyric sandbox: invalid SharedWorker epoch in ${join(outDir, WORKER_EPOCH_FILE)}`);
   }
   return epoch;
 }
@@ -479,18 +479,18 @@ export async function bundleWorker(opts: WorkerBundleOptions): Promise<WorkerBun
     // with the resulting epoch (same width, so the sourcemap stays aligned).
     define: { __PYRIC_WORKER_VERSION__: JSON.stringify(WORKER_EPOCH_PLACEHOLDER) },
     banner: {
-      js: '/* pyric dev: SharedWorker sandbox host serving firebase/* — NOT the real Firebase SDK */',
+      js: '/* pyric sandbox SharedWorker host serving firebase/*. This is not the real Firebase SDK. */',
     },
     plugins: [pyricResolvePlugin(), nodeShimPlugin()],
   });
   if (result.errors.length > 0) {
     throw new Error(
-      `pyric dev: SharedWorker bundle failed:\n${result.errors.map((e) => e.text).join('\n')}`,
+      `pyric sandbox: SharedWorker bundle failed:\n${result.errors.map((e) => e.text).join('\n')}`,
     );
   }
   const canonicalSource = readFileSync(outFile, 'utf8');
   if (!canonicalSource.includes(WORKER_EPOCH_PLACEHOLDER)) {
-    throw new Error('pyric dev: SharedWorker bundle omitted its epoch placeholder');
+    throw new Error('pyric sandbox: SharedWorker bundle omitted its epoch placeholder');
   }
   const epochHash = createHash('sha256').update(canonicalSource);
   if (opts.epochSalt) epochHash.update('\0').update(opts.epochSalt);

package/src/serve/entries/active-auth-registry.ts

@@ -0,0 +1,56 @@
+type AuthUser<Auth extends { currentUser: unknown }> = Auth['currentUser'];
+
+export interface ActiveAuthRegistry<Auth extends { currentUser: unknown }> {
+  register(auth: Auth): () => void;
+  subscribe(listener: (user: AuthUser<Auth>) => void): () => void;
+  auths(): IterableIterator<Auth>;
+}
+
+/** Coordinates unique Auth handles while allowing more than one lifecycle owner. */
+export function createActiveAuthRegistry<Auth extends { currentUser: unknown }>(
+  observe: (auth: Auth, listener: (user: AuthUser<Auth>) => void) => () => void,
+): ActiveAuthRegistry<Auth> {
+  const registrations = new Map<Auth, { owners: number; unsubscribe: () => void }>();
+  const listeners = new Set<(user: AuthUser<Auth>) => void>();
+
+  const register = (auth: Auth): (() => void) => {
+    const existing = registrations.get(auth);
+    if (existing) {
+      existing.owners += 1;
+    } else {
+      const unsubscribe = observe(auth, (user) => {
+        for (const listener of listeners) listener(user);
+      });
+      registrations.set(auth, { owners: 1, unsubscribe });
+    }
+
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const registration = registrations.get(auth);
+      if (!registration) return;
+      registration.owners -= 1;
+      if (registration.owners > 0) return;
+      registrations.delete(auth);
+      registration.unsubscribe();
+    };
+  };
+
+  const subscribe = (listener: (user: AuthUser<Auth>) => void): (() => void) => {
+    listeners.add(listener);
+    for (const auth of registrations.keys()) {
+      if (auth.currentUser) {
+        listener(auth.currentUser);
+        break;
+      }
+    }
+    return () => listeners.delete(listener);
+  };
+
+  return {
+    register,
+    subscribe,
+    auths: () => registrations.keys(),
+  };
+}