pyric 0.1.0-alpha.19 → 0.1.0-alpha.21

package/dist/storage/service.js

@@ -45,14 +45,15 @@ export function storageAuth(target) {
 export class StorageService {
     backend;
     rules;
-    constructor(backend, rules = null) {
+    crossServiceIam;
+    constructor(backend, rules = null, crossServiceIam = 'granted') {
         this.backend = backend;
         this.rules = rules;
+        this.crossServiceIam = crossServiceIam;
     }
 }
-// ─── Caches ─────────────────────────────────────────────────────────
-/** One `StorageService` per `Sandbox`. */
-const SERVICES = new WeakMap();
+/** One open storage service, with its opening configuration, per `Sandbox`. */
+const OPEN_SERVICES = new WeakMap();
 /** One sandbox `FirebaseStorage` handle per `SandboxContext`. */
 const SANDBOX_HANDLES = new WeakMap();
 /**
@@ -65,15 +66,25 @@ const SANDBOX_HANDLES = new WeakMap();
  */
 const BARE_SANDBOX_HANDLES = new WeakMap();
 /**
- * The rules SOURCE each sandbox's service was opened with (`null` when
- * opened without rules). Late-config detection: rules are honored only on
- * the FIRST storage call per `Sandbox`, so silently discarding a LATER,
- * DIFFERENT `rules` option would be a silent rules wipe — {@link
- * ensureService} throws instead. Re-supplying the IDENTICAL source stays
- * fine (idempotent multi-handle construction, e.g. per-user contexts).
+ * Reject a late option that differs from the one the service is already
+ * open with. Both `rules` and `crossServiceIam` are honored only on the
+ * FIRST storage call per `Sandbox`. Silently discarding a later, differing
+ * value would wipe the rules, or reopen the false-ALLOW surface the IAM
+ * mode models, without a word. Re-supplying the IDENTICAL value stays fine
+ * (idempotent multi-handle construction, for example per-user contexts),
+ * and so does omitting it.
  */
-const SERVICE_RULES_SOURCE = new WeakMap();
-const SERVICE_RULES_RESOLUTION = new WeakMap();
+function rejectDifferingLateConfig(option, descriptor, supplied, openedWith, caller) {
+    if (supplied === undefined || supplied === openedWith)
+        return;
+    const openedDescription = openedWith === null
+        ? `without ${option}`
+        : `with a different ${descriptor}`;
+    throw new Error(`pyric/storage: ${caller} received a ${descriptor}, but this sandbox's storage service ` +
+        `is already open ${openedDescription}. ${option} is honored only on the FIRST storage ` +
+        'call per Sandbox, so this value would be silently discarded. Configure it on the first ' +
+        'storage call for this sandbox.');
+}
 /**
  * Get (or open) the ONE per-sandbox `StorageService`. Loud on the
  * silent-rules-wipe hazard: when the service is already open and the
@@ -82,16 +93,11 @@ const SERVICE_RULES_RESOLUTION = new WeakMap();
  * on the first storage call for the sandbox instead.
  */
 function ensureService(sandbox, options, caller) {
-    const existing = SERVICES.get(sandbox);
+    const existing = OPEN_SERVICES.get(sandbox);
     if (existing) {
-        const openedWith = SERVICE_RULES_SOURCE.get(sandbox) ?? null;
-        if (options.rules !== undefined && options.rules !== openedWith) {
-            throw new Error(`pyric/storage: ${caller} received a rules source, but this sandbox's storage ` +
-                `service is already open ${openedWith === null ? 'without rules' : 'with a different rules source'} ` +
-                '— rules are honored only on the FIRST storage call per Sandbox, so these rules ' +
-                'would be silently discarded. Configure rules on the first storage call for this sandbox.');
-        }
-        return existing;
+        rejectDifferingLateConfig('rules', 'rules source', options.rules, existing.rulesSource, caller);
+        rejectDifferingLateConfig('crossServiceIam', 'crossServiceIam mode', options.crossServiceIam, existing.crossServiceIam, caller);
+        return existing.service;
     }
     let rules = null;
     let resolution = null;
@@ -116,10 +122,14 @@ function ensureService(sandbox, options, caller) {
     }
     // Explicit dbName wins; otherwise scope the default by project identity so
     // two projects on one origin never share a storage database (issue #359).
-    const servicePromise = openStorageBackend(options.dbName ?? storageDbName(options.projectId)).then((backend) => new StorageService(backend, rules));
-    SERVICES.set(sandbox, servicePromise);
-    SERVICE_RULES_SOURCE.set(sandbox, options.rules ?? null);
-    SERVICE_RULES_RESOLUTION.set(sandbox, resolution);
+    const crossServiceIam = options.crossServiceIam ?? 'granted';
+    const servicePromise = openStorageBackend(options.dbName ?? storageDbName(options.projectId)).then((backend) => new StorageService(backend, rules, crossServiceIam));
+    OPEN_SERVICES.set(sandbox, {
+        service: servicePromise,
+        rulesSource: options.rules ?? null,
+        rulesResolution: resolution,
+        crossServiceIam,
+    });
     // Join the sandbox's persistable-service REGISTRY so `sandbox.resetAll()`
     // reaches storage (issue #359: Studio's reset cleared Firestore + auth but
     // never storage — storage was invisible to the sandbox). Storage does NOT
@@ -176,6 +186,7 @@ export function getStorageSandbox(target, options = {}) {
         kind: 'sandbox',
         sandbox,
         context: ctx,
+        currentAuth: fromBareSandbox ? () => sandbox.currentUser : undefined,
         bucket,
         servicePromise,
     };
@@ -286,6 +297,6 @@ export function getStorageService(storage) {
 }
 /** Internal assurance seam for the exact rules source retained by Storage setup. */
 export function getStorageRulesResolution(storage) {
-    return SERVICE_RULES_RESOLUTION.get(targetOf(storage).sandbox) ?? null;
+    return OPEN_SERVICES.get(targetOf(storage).sandbox)?.rulesResolution ?? null;
 }
 //# sourceMappingURL=service.js.map

package/dist/storage/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/storage/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/storage/service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyric",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.21",
   "license": "Apache-2.0",
   "homepage": "https://pyric.dev",
   "repository": {
@@ -13,6 +13,22 @@
   },
   "description": "Firebase for agents \u2014 modular Web SDK adapters (firestore, auth, database, storage) with swappable sandbox/prod backends, plus rules tooling and in-process sandbox. Mirrors firebase.",
   "type": "module",
+  "sideEffects": [
+    "./dist/app/register.js",
+    "./dist/app/registry.js",
+    "./dist/app/runtime.js",
+    "./dist/firestore/sandbox/write-runtime.js",
+    "./dist/rules/grammar/FirestoreParser.js",
+    "./dist/sandbox/admin-firestore/listeners.js",
+    "./dist/sandbox/internal/firebase-error.js",
+    "./src/app/register.ts",
+    "./src/app/registry.ts",
+    "./src/app/runtime.ts",
+    "./src/firestore/sandbox/write-runtime.ts",
+    "./src/rules/grammar/FirestoreParser.ts",
+    "./src/sandbox/admin-firestore/listeners.ts",
+    "./src/sandbox/internal/firebase-error.ts"
+  ],
   "exports": {
     "./app": {
       "types": "./dist/app/index.d.ts",
@@ -38,6 +54,10 @@
       "types": "./dist/firestore/internal/value-codec.d.ts",
       "import": "./dist/firestore/internal/value-codec.js"
     },
+    "./firestore/lite": {
+      "types": "./dist/firestore/lite.d.ts",
+      "import": "./dist/firestore/lite.js"
+    },
     "./auth": {
       "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth/index.js"
@@ -125,6 +145,26 @@
     "./sandbox/admin-firestore": {
       "types": "./dist/sandbox/admin-firestore/index.d.ts",
       "import": "./dist/sandbox/admin-firestore/index.js"
+    },
+    "./app-check": {
+      "types": "./dist/app-check/index.d.ts",
+      "import": "./dist/app-check/index.js"
+    },
+    "./functions": {
+      "types": "./dist/functions/index.d.ts",
+      "import": "./dist/functions/index.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics/index.d.ts",
+      "import": "./dist/analytics/index.js"
+    },
+    "./performance": {
+      "types": "./dist/performance/index.d.ts",
+      "import": "./dist/performance/index.js"
+    },
+    "./remote-config": {
+      "types": "./dist/remote-config/index.d.ts",
+      "import": "./dist/remote-config/index.js"
     }
   },
   "files": [
@@ -150,7 +190,7 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "1.3.14",
     "firebase": "^12.12.0",
     "firebase-admin": "^13.0.0",
     "typescript": "^5.7.0"

package/src/ai/blocked.ts

@@ -0,0 +1,97 @@
+/**
+ * Blocked-response detection: the ONE definition of "this envelope carries
+ * no usable content because a filter fired", shared by the two places that
+ * need it:
+ *
+ *   - `response-helpers.ts`, which throws upstream's exact
+ *     `Response error: Candidate was blocked due to <reason>` out of
+ *     `text()` / `functionCalls()` / `inlineDataParts()` when the caller
+ *     reaches for content that isn't there;
+ *   - `broker/broker.ts`, which lands a `response_blocked` event on the
+ *     sandbox's unified stream at RESPONSE time, so the block is visible
+ *     even when nobody ever calls `text()` (an app that renders
+ *     `response.text ?? ''` used to show an empty bubble and nothing else).
+ *
+ * A block is not a rejection: production answers HTTP 200 with an empty
+ * candidate and the reason in `finishReason` (SAFETY, RECITATION,
+ * BLOCKLIST, PROHIBITED_CONTENT, SPII, the IMAGE_* variants), or, when the
+ * PROMPT itself was refused, with no candidates at all and a
+ * `promptFeedback.blockReason`. Nothing throws on the wire path.
+ *
+ * Leaf module by construction: it imports only `./enums.js` (which imports
+ * nothing) and a type. `broker/` must NOT reach into `response-helpers.ts`
+ * for this: that file pulls `./errors.js`, which imports `./broker/index.js`
+ * as a value, and the round trip would be a real runtime cycle.
+ */
+
+import type { WireResponse } from './broker/types.js';
+import { FinishReason } from './enums.js';
+
+/**
+ * Finish reasons that mean "no usable content": the installed
+ * `@firebase/ai@2.12.0` `badFinishReasons` set, verbatim and in upstream's
+ * order. Every one of these makes the response helpers throw instead of
+ * returning text, which is exactly the set worth announcing to a developer.
+ */
+const BLOCKING_FINISH_REASONS: readonly string[] = [
+  FinishReason.RECITATION,
+  FinishReason.SAFETY,
+  FinishReason.BLOCKLIST,
+  FinishReason.PROHIBITED_CONTENT,
+  FinishReason.SPII,
+  FinishReason.MALFORMED_FUNCTION_CALL,
+  FinishReason.IMAGE_SAFETY,
+  FinishReason.IMAGE_PROHIBITED_CONTENT,
+  FinishReason.IMAGE_OTHER,
+  FinishReason.NO_IMAGE,
+  FinishReason.IMAGE_RECITATION,
+  FinishReason.LANGUAGE,
+  FinishReason.UNEXPECTED_TOOL_CALL,
+  FinishReason.TOO_MANY_TOOL_CALLS,
+  FinishReason.MISSING_THOUGHT_SIGNATURE,
+  FinishReason.MALFORMED_RESPONSE,
+];
+
+/** Does this candidate's finish reason mean the content was withheld? */
+export function isBlockingFinishReason(finishReason: string | undefined): boolean {
+  if (!finishReason) return false;
+  return BLOCKING_FINISH_REASONS.some((reason) => reason === finishReason);
+}
+
+/** What a block was, in the wire's own vocabulary. Exactly one of
+ *  `finishReason` (a candidate was withheld) / `blockReason` (the prompt was
+ *  refused) is normally set; both may be absent when production sent
+ *  `promptFeedback` with no reason at all. */
+export interface ResponseBlock {
+  /** Candidate-level: the blocking `finishReason` off candidate 0. */
+  finishReason?: string;
+  /** Candidate-level: production's own explanatory `finishMessage`. */
+  finishMessage?: string;
+  /** Prompt-level: `promptFeedback.blockReason`. */
+  blockReason?: string;
+}
+
+/**
+ * Classify an envelope, mirroring `hasValidCandidates` in
+ * `response-helpers.ts` EXACTLY so the event stream and the thrown error can
+ * never disagree: candidate 0 with a blocking finish reason is a block; no
+ * candidate 0 at all plus any `promptFeedback` is a block; everything else
+ * (including a plain `STOP` or `MAX_TOKENS`) is not.
+ *
+ * Returns `null` when the response is fine, so a caller reads as
+ * `const block = describeResponseBlock(res); if (block !== null) …`.
+ */
+export function describeResponseBlock(response: WireResponse): ResponseBlock | null {
+  const firstCandidate = response.candidates?.[0];
+  if (firstCandidate !== undefined) {
+    if (!isBlockingFinishReason(firstCandidate.finishReason)) return null;
+    const candidateBlock: ResponseBlock = {};
+    candidateBlock.finishReason = firstCandidate.finishReason;
+    candidateBlock.finishMessage = firstCandidate.finishMessage;
+    return candidateBlock;
+  }
+  if (response.promptFeedback === undefined) return null;
+  const promptBlock: ResponseBlock = {};
+  promptBlock.blockReason = response.promptFeedback.blockReason;
+  return promptBlock;
+}

package/src/ai/broker/broker.ts

@@ -18,6 +18,17 @@
  *   - a model-turn functionCall part with no thoughtSignature
  *                                         → `ai-error-fncall-missing-thought-signature`
  *
+ * It also announces the refusals production does NOT throw for: a safety /
+ * recitation / blocklist block arrives as a 200 with an empty candidate, so
+ * the broker lands a `response_blocked` event ({@link emitBlockIfBlocked})
+ * alongside the normal op event. Without it a filtered answer is
+ * indistinguishable from a model that simply had nothing to say.
+ *
+ * The same goes for a model SUBSTITUTION ({@link emitModelSubstitution}): an
+ * engine that redirects the requested model (an openai `modelMap` entry or
+ * catch-all `model`, a gemini experimental alias) answers normally, so
+ * nothing anywhere says the developer tested a model they never named.
+ *
  * Event emission is best-effort behind one small choke-point ({@link emit}):
  * a throw from the emit path (or any event consumer downstream) must never
  * poison the AI operation the caller just completed — handler errors are the
@@ -28,15 +39,18 @@
 import type { Sandbox } from 'pyric/sandbox';
 import { emitSandboxEvent, makeServiceMutationEvent } from 'pyric/sandbox/internal';
 
+import { describeResponseBlock } from '../blocked.js';
 import { AiBrokerError, Synthesizer, badRole, emptyContents, missingThoughtSignature } from './synthesizer.js';
 import { ScriptedEngine } from './scripted-engine.js';
 import { OpenAiEngine } from './openai-engine.js';
+import { GeminiEngine } from './gemini-engine.js';
 import type {
   AnswerEngine,
   CountTokensRequest,
   CountTokensResponse,
   EngineConfig,
   GenerateContentRequest,
+  ModelResolution,
   RawEnvelope,
   WireChunk,
   WireResponse,
@@ -75,7 +89,7 @@ function isAnswerEngine(value: EngineConfig | AnswerEngine): value is AnswerEngi
 }
 
 /** What Studio's stream (and the construction log line) name the engine. */
-type EngineKind = 'scripted' | 'openai' | 'custom';
+type EngineKind = 'scripted' | 'openai' | 'gemini' | 'custom';
 
 export class AiBroker {
   readonly engine: AnswerEngine;
@@ -93,6 +107,10 @@ export class AiBroker {
     } else if (engine.kind === 'scripted') {
       this.engine = new ScriptedEngine(engine.script ?? [], new Synthesizer());
       this.engineKind = 'scripted';
+    } else if (engine.kind === 'gemini') {
+      this.engine = new GeminiEngine(engine);
+      this.engineKind = 'gemini';
+      this.engineBaseUrl = engine.baseUrl;
     } else {
       this.engine = new OpenAiEngine(engine);
       this.engineKind = 'openai';
@@ -104,10 +122,16 @@ export class AiBroker {
 
   /** One-line construction-time summary of what this broker resolved to. */
   private describeEngine(): string {
-    if (this.engineKind === 'openai') {
+    const isOpenAiEngine = this.engineKind === 'openai';
+    if (isOpenAiEngine) {
       return `[pyric/ai] engine resolved: openai (model=${this.engineModel ?? 'passthrough'}, upstream=${this.engineBaseUrl})`;
     }
-    if (this.engineKind === 'custom') {
+    const isGeminiEngine = this.engineKind === 'gemini';
+    if (isGeminiEngine) {
+      return `[pyric/ai] engine resolved: gemini (upstream=${this.engineBaseUrl ?? 'https://generativelanguage.googleapis.com'})`;
+    }
+    const isCustomEngine = this.engineKind === 'custom';
+    if (isCustomEngine) {
       return '[pyric/ai] engine resolved: custom AnswerEngine';
     }
     return '[pyric/ai] engine resolved: scripted (zero-config unless a script is queued)';
@@ -115,24 +139,109 @@ export class AiBroker {
 
   /** Additive detail fields every emitted event carries so Studio can show the engine. */
   private engineDetail(): Record<string, unknown> {
-    return {
+    const detail: Record<string, unknown> = {
       engine: this.engineKind,
-      ...(this.engineKind === 'openai'
-        ? { model: this.engineModel, baseUrl: this.engineBaseUrl }
-        : {}),
     };
+    const isOpenAiEngine = this.engineKind === 'openai';
+    if (isOpenAiEngine) {
+      detail.model = this.engineModel;
+      detail.baseUrl = this.engineBaseUrl;
+    }
+    const isGeminiEngine = this.engineKind === 'gemini';
+    if (isGeminiEngine) {
+      detail.baseUrl = this.engineBaseUrl ?? 'https://generativelanguage.googleapis.com';
+    }
+    return detail;
+  }
+
+  /**
+   * Announce a SAFETY / RECITATION / BLOCKLIST / … block on the event stream.
+   *
+   * A block is the broker's SILENT refusal: unlike `request_rejected` nothing
+   * throws (production answers 200 with an empty candidate), so an app that
+   * renders whatever `text()` gave it just shows nothing, and the developer
+   * gets no signal anywhere. Emitting at RESPONSE time (not from the response
+   * helpers, which only fire if someone reaches for content) means the event
+   * lands whether or not the caller ever asks for the text.
+   *
+   * Detection is `blocked.ts`'s, shared verbatim with the response helpers'
+   * throw path, so the stream and the thrown error can never disagree.
+   *
+   * Returns whether the envelope WAS blocked, so the stream wrapper can
+   * announce at most once across its chunks.
+   */
+  private emitBlockIfBlocked(model: string, response: WireResponse): boolean {
+    const block = describeResponseBlock(response);
+    if (block === null) return false;
+    this.emit('response_blocked', model, { ...block });
+    return true;
+  }
+
+  /**
+   * Announce that the engine will answer as a DIFFERENT model than the one
+   * requested.
+   *
+   * A substitution is the quietest failure the broker has: nothing throws,
+   * content comes back, and the developer concludes they tested model X when
+   * model Y answered (an openai `modelMap` entry or catch-all `model`, a
+   * gemini experimental alias). Only engines that actually redirect implement
+   * {@link AnswerEngine.resolveEffectiveModel}; the rest are silent by
+   * construction.
+   *
+   * Fired at REQUEST time, before delegating: the swap is a property of the
+   * call about to go out, so it lands even when that call then fails.
+   * Comparison is bare-vs-bare, since `models/x` to `x` is the wire's prefix
+   * convention rather than a substitution, and an exact match emits nothing.
+   *
+   * `countTokens` is deliberately not announced: the openai engine never
+   * sends a model there at all (the count is synthesized locally), so an
+   * announcement would name an upstream call that never happens.
+   */
+  private emitModelSubstitution(model: string): void {
+    const resolve = this.engine.resolveEffectiveModel;
+    if (typeof resolve !== 'function') return;
+    let effective: ModelResolution;
+    try {
+      effective = resolve.call(this.engine, model);
+    } catch {
+      // A misbehaving engine's self-report must never fail the op.
+      return;
+    }
+    const requestedBare = model.startsWith('models/') ? model.slice('models/'.length) : model;
+    if (effective.model === requestedBare) return;
+    this.emit('model_substituted', model, {
+      requestedModel: model,
+      effectiveModel: effective.model,
+      reason: effective.reason,
+    });
+  }
+
+  private emitRejectionIfBrokerError(model: string, err: unknown): void {
+    const code = err instanceof AiBrokerError ? err.envelope.error.code : 500;
+    const status = err instanceof AiBrokerError ? err.envelope.error.status : 'INTERNAL';
+    const message = err instanceof AiBrokerError
+      ? err.envelope.error.message
+      : err instanceof Error ? err.message : String(err);
+    this.emit('request_rejected', model, { code, status, message });
   }
 
   async generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse> {
     this.validate(req, model);
-    const response = await this.engine.generateContent(req, model);
-    this.emit('generate_content', model, {
-      contentCount: req.contents.length,
-      finishReason: response.candidates?.[0]?.finishReason,
-      totalTokenCount: response.usageMetadata?.totalTokenCount,
-      responseId: response.responseId,
-    });
-    return response;
+    this.emitModelSubstitution(model);
+    try {
+      const response = await this.engine.generateContent(req, model);
+      this.emit('generate_content', model, {
+        contentCount: req.contents.length,
+        finishReason: response.candidates?.[0]?.finishReason,
+        totalTokenCount: response.usageMetadata?.totalTokenCount,
+        responseId: response.responseId,
+      });
+      this.emitBlockIfBlocked(model, response);
+      return response;
+    } catch (err) {
+      this.emitRejectionIfBrokerError(model, err);
+      throw err;
+    }
   }
 
   /**
@@ -143,27 +252,49 @@ export class AiBroker {
    */
   streamGenerateContent(req: GenerateContentRequest, model: string): AsyncIterable<WireChunk> {
     this.validate(req, model);
+    this.emitModelSubstitution(model);
     const inner = this.engine.streamGenerateContent(req, model);
     const emit = (chunkCount: number) =>
       this.emit('stream_generate_content', model, {
         contentCount: req.contents.length,
         chunkCount,
       });
+    const emitRejection = (err: unknown) => this.emitRejectionIfBrokerError(model, err);
+    // A block surfaces on whichever chunk carries the finish reason (the last
+    // one, per the captured framing), so it is announced DURING iteration:
+    // an abandoned stream still reports why it produced nothing. At most one
+    // per stream: the aggregate has a single blocking reason, not one per chunk.
+    let announcedBlock = false;
+    const emitBlock = (chunk: WireChunk) => {
+      if (announcedBlock) return;
+      announcedBlock = this.emitBlockIfBlocked(model, chunk);
+    };
     return (async function* wrapped(): AsyncGenerator<WireChunk> {
       let chunkCount = 0;
-      for await (const chunk of inner) {
-        chunkCount++;
-        yield chunk;
+      try {
+        for await (const chunk of inner) {
+          chunkCount++;
+          emitBlock(chunk);
+          yield chunk;
+        }
+        emit(chunkCount);
+      } catch (err) {
+        emitRejection(err);
+        throw err;
       }
-      emit(chunkCount);
     })();
   }
 
   async countTokens(req: CountTokensRequest, model: string): Promise<CountTokensResponse> {
     this.validateContents(req, model);
-    const response = await this.engine.countTokens(req, model);
-    this.emit('count_tokens', model, { totalTokens: response.totalTokens });
-    return response;
+    try {
+      const response = await this.engine.countTokens(req, model);
+      this.emit('count_tokens', model, { totalTokens: response.totalTokens });
+      return response;
+    } catch (err) {
+      this.emitRejectionIfBrokerError(model, err);
+      throw err;
+    }
   }
 
   // ── Production-shaped validation ──────────────────────────────────────────