npm - @pyric/cli - Versions diffs - 0.1.0-alpha.10 → 0.1.0-alpha.11 - Mend

@pyric/cli 0.1.0-alpha.10 → 0.1.0-alpha.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (304) hide show

package/dist/serve/studio-ui/assets/seed-DeuFKi4J.js ADDED Viewed

@@ -0,0 +1,20 @@
+import{s as f,a as o,b as d,d as s,G as h,c as n,e as w,f as A,u as m,r as p,T as g}from"./index-cpSfgQ7H.js";async function y(a){n.createUser(a,{uid:"alice",email:"alice@gmail.com",displayName:"Alice Nguyen",emailVerified:!0,photoUrl:"https://lh3.googleusercontent.com/a/alice",providerUserInfo:[{providerId:"google.com"}],customClaims:{plan:"pro"}}),n.createUser(a,{uid:"bob",email:"bob@example.com",password:"pyric-demo",displayName:"Bob Carter",emailVerified:!0,customClaims:{role:"editor"}}),n.createUser(a,{uid:"carol",email:"carol@example.com",displayName:"Carol Diaz",emailVerified:!1}),await w(a),await A(a)}const b=new h(37.7749,-122.4194);async function C(a){const r=Date.now(),i=e=>g.fromMillis(r-e*6e4),l=[{id:"alice",name:"Alice Nguyen",email:"alice@gmail.com",plan:"pro"},{id:"bob",name:"Bob Carter",email:"bob@example.com",plan:"free"},{id:"carol",name:"Carol Diaz",email:"carol@example.com",plan:"free"}];for(const e of l)await o(s(a,"users",e.id),{name:e.name,email:e.email,plan:e.plan,createdAt:d()});const t=["alice","bob","carol"],c=["Ship the redesign","Reply to carol","Buy milk","Draft the launch post","Review the rules","Plan offsite","Renew the domain","Read the spec","Fix the flaky test","Call the bank","Water the plants","Book the flights"];for(let e=0;e<c.length;e++){const u=t[e%t.length];await o(s(a,"notes",`note-${String(e+1).padStart(2,"0")}`),{title:c[e],done:e%3===0,pinned:e===0,priority:e%3+1,ownerId:u,ownerRef:`users/${u}`,tags:e%2===0?["work","urgent"]:["personal"],meta:{source:e%2===0?"app":"import",revision:e+1,flags:{starred:e%4===0,archived:!1}},location:e%3===0?b:null,createdAt:i(120-e*7),updatedAt:d()})}await o(s(a,"posts","post-hello"),{title:"Hello world",body:"First post from the seeded sandbox.",authorRef:"users/alice",published:!0,publishedAt:i(8)}),await o(s(a,"posts","post-draft"),{title:"Draft: roadmap",body:"Unpublished draft.",authorRef:"users/bob",published:!1})}async function R(a){const r=new TextEncoder,l=Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="),t=>t.charCodeAt(0));await m(p(a,"avatars/alice.png"),l,{contentType:"image/png"}),await m(p(a,"notes/note-01/attachment.txt"),r.encode(`Attachment for the redesign note.
+`),{contentType:"text/plain"})}const x=`rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read: if request.auth != null;
+      allow write: if request.auth != null && request.auth.uid == userId;
+    }
+    match /notes/{noteId} {
+      allow read: if request.auth != null;
+      allow create: if request.auth != null && request.resource.data.ownerId == request.auth.uid;
+      allow update, delete: if request.auth != null && resource.data.ownerId == request.auth.uid;
+    }
+    match /posts/{postId} {
+      allow read: if true;
+      allow write: if request.auth != null;
+    }
+  }
+}
+`;function U(a){f(a,x)}async function q(a){await C(a.adminFirestore),await y(a.auth),await R(a.storage)}export{q as applySeed,U as deploySeedRules,y as seedAuth};

package/dist/serve/studio-ui/index.html CHANGED Viewed

@@ -23,7 +23,7 @@
       href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
       rel="stylesheet"
     />
-    <script type="module" crossorigin src="/__pyric/ui/assets/index-BvtQIpGn.js"></script>
+    <script type="module" crossorigin src="/__pyric/ui/assets/index-cpSfgQ7H.js"></script>
     <link rel="stylesheet" crossorigin href="/__pyric/ui/assets/index-BlSGru_r.css">
   </head>
   <body>

package/dist/serve/vite-plugin.d.ts CHANGED Viewed

@@ -1,5 +1,25 @@
 import type { Plugin } from 'vite';
-export interface PyricSandboxOptions {
+import type { AiEngineConfigWire } from './worker/protocol.js';
+import type { AIOptions } from 'pyric/ai';
+/**
+ * The plugin-level engine config surface = `pyric/ai`'s `EngineConfig` (what an
+ * app passes to `getAI`), minus the custom `AnswerEngine` object variant — a
+ * live object cannot cross to the SharedWorker host or serialize into the page,
+ * so the plugin's declarative surface is the JSON-able `scripted` / `openai`
+ * configs only (the same restriction the worker path already enforces).
+ */
+export type PyricAiEngineConfig = Extract<NonNullable<AIOptions['engine']>, {
+    kind: string;
+}>;
+/**
+ * Node-side `EngineConfig` → JSON-safe {@link AiEngineConfigWire}. Mirrors the
+ * browser `toEngineWire` (entries/ai.ts): an openai config with no `baseUrl`
+ * targets the same-origin proxy; scripted `script` entries pass through (plain
+ * authoring shapes — function/RegExp matchers can't survive JSON and are not a
+ * plugin-config use case).
+ */
+export declare function engineConfigToWire(engine: PyricAiEngineConfig): AiEngineConfigWire;
+export interface PyricOptions {
     /** firestore.rules path (relative to `root`). Default: `firebase.json`'s
      *  `firestore.rules`, else `firestore.rules` in the project root. */
     rules?: string;
@@ -21,10 +41,10 @@ export interface PyricSandboxOptions {
      *  + `GET /__pyric/health` + `WS /__pyric/sandbox`, all on Vite's port.
      *  `true` is shorthand for `{}`. The agent and the page share ONE sandbox.
      *
-     *  ⚠ **Forces the in-page sandbox (single-tab).** The bridge peer is the
-     *  in-page sandbox, never the SharedWorker, so enabling `bridge` disables the
-     *  default multi-tab SharedWorker path — otherwise the agent would drive an
-     *  empty in-page sandbox while the app's data lived in the worker. */
+     *  Does NOT change the sandbox topology: on the default SharedWorker path the
+     *  page dials the bridge WS and relays agent tool-calls THROUGH the worker
+     *  (`connectBridgePeer`), so multi-tab stays on. The in-page fallback engages
+     *  only when the worker bundle itself fails, bridge or not. */
     bridge?: boolean | {
         project?: string;
         disableAuditLog?: boolean;
@@ -32,26 +52,83 @@ export interface PyricSandboxOptions {
     /** Serve the **Pyric Studio** app at `/__pyric/ui/` on Vite's dev origin (the
      *  `pyric dev --ui` equivalent). Mounts the disk-backed workspace/project
      *  routes Studio's `local` mode talks to AND serves the built Studio assets
-     *  (vendored in this package at `dist/serve/studio-ui`). **On by default**;
-     *  pass `ui: false` to disable.
-     *
-     *  Not compatible with `bridge`: bridge forces the app in-page, but Studio's
-     *  live plane reads the SharedWorker, so Studio would observe nothing. Under
-     *  `bridge` ui therefore defaults OFF (an explicit `ui: true` still works but
-     *  warns). Use `ui` without `bridge`, or `pyric dev --ui`. */
+     *  (vendored in this package at `dist/serve/studio-ui`). **On by default**,
+     *  including under `bridge` (the bridge peer routes through the SharedWorker,
+     *  so app, Studio, and agent all observe the one sandbox); pass `ui: false`
+     *  to disable. */
     ui?: boolean;
+    /** RTDB-triggered Cloud Functions under this dev server (the `pyric dev`
+     *  parity fold). By default a `functions` block in `firebase.json` is
+     *  discovered automatically: its `onValueCreated` triggers run in an isolated
+     *  node child against the shared sandbox (other trigger kinds warn and are
+     *  skipped), and the discovered codebase turns the MCP bridge mount on (the
+     *  child dials the sandbox over the bridge WS — the page's sandbox topology
+     *  is unchanged, see `bridge`). `functions: false` is the off switch: no
+     *  discovery, no child, no functions-forced bridge mount.
+     *
+     *  Field precedence: explicit option > env var > firebase files > default.
+     *  - `region`: the trigger location. Beats `PYRIC_FUNCTIONS_RTDB_REGION`;
+     *    default `us-central1`.
+     *  - `instance`: the RTDB instance name. Default `<projectId>-default-rtdb`,
+     *    where projectId is `PYRIC_PROJECT`, else `.firebaserc`'s default
+     *    project, else `demo-project`.
+     *  - `watch`: hot-reload the functions source (default `true`, matching
+     *    rules). A save under the functions source dir stops the child and
+     *    respawns it — redeploy semantics: in-flight executions in the old child
+     *    may drop, and writes landing during the swap gap are consumed as the new
+     *    child's baseline (they do not fire). Unlike rules, a broken save cannot
+     *    keep last-good live — the old child is already gone — so functions stay
+     *    down until the next good save. */
+    functions?: false | {
+        region?: string;
+        instance?: string;
+        watch?: boolean;
+    };
     /** Force whether `vite build` runs the firebase→pyric swap, overriding the
      *  mode default. Unset (default): swap for any NON-production mode, keep real
      *  firebase for mode `production`. `true` = always produce a sandbox build;
      *  `false` = never swap in build (real firebase regardless of mode). `vite
      *  dev` is unaffected — the swap is always on there. */
     swapInBuild?: boolean;
+    /**
+     * Dev-server-level AI configuration for `pyric/ai` (the sanctioned
+     * replacement for threading `engine` through every app `getAI(...)` call,
+     * which is first-call-wins and easy to get wrong).
+     *
+     *   pyric({
+     *     ai: {
+     *       engine: { kind: 'openai', model: 'llama3.2', baseUrl: '/__pyric/ai-proxy' },
+     *       proxyUpstream: 'http://localhost:11434/v1', // your Ollama
+     *     },
+     *   })
+     *
+     * - `engine` is `pyric/ai`'s `EngineConfig` (scripted | openai), applied on
+     *   both the SharedWorker and in-page paths. An openai `baseUrl` of
+     *   `/__pyric/ai-proxy` (or omitted) routes through the same-origin proxy so a
+     *   localhost upstream needs zero CORS setup.
+     * - `proxyUpstream` sets what `/__pyric/ai-proxy` forwards to (beats the
+     *   `PYRIC_AI_PROXY_UPSTREAM` env var; default `http://localhost:11434/v1`).
+     *
+     * Precedence: a plugin-level `engine`, when set, always wins over an engine an
+     * app's own `getAI()` passes (host-side via `ctx.aiEngine` on the worker path,
+     * page-side via an injected global on the in-page fallback); with no plugin
+     * engine the first `getAI()` call's engine is honored (first-call-wins), and
+     * with neither the zero-config scripted default applies.
+     */
+    ai?: {
+        /** Engine config (scripted | openai). Custom `AnswerEngine` objects are not
+         *  supported at the plugin level — they can't cross to the worker/page. */
+        engine?: PyricAiEngineConfig;
+        /** OpenAI-compatible upstream `/__pyric/ai-proxy` forwards to. Beats
+         *  `PYRIC_AI_PROXY_UPSTREAM`; default `http://localhost:11434/v1`. */
+        proxyUpstream?: string;
+    };
 }
 /**
  * The dev-only Vite plugin. Add to `vite.config`:
  *
- *   import { pyricSandbox } from '@pyric/cli/vite';
- *   export default defineConfig({ plugins: [pyricSandbox()] });
+ *   import { pyric } from '@pyric/cli/vite';
+ *   export default defineConfig({ plugins: [pyric()] });
  */
-export declare function pyricSandbox(options?: PyricSandboxOptions): Plugin;
+export declare function pyric(options?: PyricOptions): Plugin;
 //# sourceMappingURL=vite-plugin.d.ts.map

package/dist/serve/vite-plugin.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../../src/serve/vite-plugin.ts"],"names":[],"mappings":"~~AA6CA~~,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,MAAM,CAAC;~~AA0D1D~~,MAAM,WAAW,mBAAmB;~~IAClC~~;yEACqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;gEAC4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;~~0EAQsE~~;~~IACtE~~,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACnE~~;;;;;;;;;kEAS8D~~;~~IAC9D~~,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;4DAIwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;~~CACvB~~;AAED;;;;;GAKG;AACH,wBAAgB,~~YAAY~~,CAAC,OAAO,GAAE,~~mBAAwB~~,GAAG,MAAM,~~CA6kBtE~~"}
1	+ {"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../../src/serve/vite-plugin.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,MAAM,CAAC;AAkB1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAiD1C;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE9F;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,CAelF;AAeD,MAAM,WAAW,YAAY;IAC3B;yEACqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;gEAC4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;mEAQ+D;IAC/D,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACnE;;;;;;sBAMkB;IAClB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;;;;;;;;;;;;;;;;;;2CAqBuC;IACvC,SAAS,CAAC,EAAE,KAAK,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5E;;;;4DAIwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,EAAE,CAAC,EAAE;QACH;mFAC2E;QAC3E,MAAM,CAAC,EAAE,mBAAmB,CAAC;QAC7B;8EACsE;QACtE,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,MAAM,CAo0BxD"}

package/dist/serve/vite-plugin.js CHANGED Viewed

@@ -14,7 +14,7 @@
  * mode) produces a SANDBOX build that bundles pyric's in-page adapters instead
  * of the real SDK: self-contained, meant to be previewed under `pyric dev`, and
  * stamped with the sandbox-build marker so it can never be deployed (`pyric
- * deploy hosting` refuses it). `pyricSandbox({ swapInBuild })` forces the build
+ * deploy hosting` refuses it). `pyric({ swapInBuild })` forces the build
  * behavior on/off regardless of mode. See `sandbox-marker.ts`.
  *
  * This is a thin adapter over serve's proven machinery. It REUSES, not reimplements:
@@ -30,8 +30,9 @@
  * Scope = M1 (swap + rules) + M2 (SharedWorker multi-tab + persist/capture/seed)
  * + M3 (the MCP bridge fold — `{ bridge }`). M3 reuses `createBridgeMount` (the
  * proven serve-flavored bridge behind `pyric dev --bridge`), composing it into
- * the same `/__pyric` middleware; bridge mode forces the in-page sandbox path so
- * the agent and the app share one backend.
+ * the same `/__pyric` middleware; on the worker path the bridge peer routes
+ * agent tool-calls THROUGH the SharedWorker (`connectBridgePeer`), so the agent
+ * and the app share one backend without forcing the page in-page.
  *
  * Serving `worker.js` flips `runtime.ts` to the worker path (one backend across
  * tabs, IndexedDB-durable); on that path the WORKER owns persist/capture/seed via
@@ -43,7 +44,8 @@ import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { SDK_MODULES, defaultSdkEntries, resolveStudioUiDir, pyricPackageRoot, bundleWorker, workerSourceHash, NODE_BUILTIN_RE, NODE_BUILTIN_SHIMS, } from './bundler.js';
-import { createEventHub, createPyricNamespace } from './namespace.js';
+import { createEventHub, createPyricNamespace, } from './namespace.js';
+import { formatActivityWarning } from './activity-warning.js';
 import { diskWorkspace, diskProjectStore } from './studio/index.js';
 import { createBridgeMount } from './bridge-mount.js';
 import { loadProjectDatabaseRules, loadProjectRules, loadProjectStorageRules, prepareRulesSource, rulesHashOf, } from './rules.js';
@@ -51,7 +53,10 @@ import { createStateStore, STATE_FILE_VERSION } from './state-store.js';
 import { createCaptureStore } from './capture-store.js';
 import { isAllowedHost } from './server.js';
 import { SANDBOX_BUILD_META } from './sandbox-marker.js';
-import { readFirebaseJson } from '../cli/firebase-json.js';
+import { readFirebaseJson, readFirebaseRc } from '../cli/firebase-json.js';
+import { discoverFunctionsRtdbProject, } from '../functions-rtdb/project.js';
+import { spawnFunctionsRtdbChild, } from '../functions-rtdb/child.js';
+import { buildChildEnv, createLinePrefixer, registerModuleUrl, } from '../cli/dev-runner.js';
 /**
  * Whether a `vite build` should run the firebase→pyric swap (produce a SANDBOX
  * build). MODE-based with a plugin-config override:
@@ -68,6 +73,31 @@ function swapsInBuild(env, swapInBuild) {
 }
 /** Any `firebase/<sub>` specifier. */
 const FB_ANY = /^firebase\/([a-z-]+(?:\/[a-z-]+)*)$/;
+/** The serve proxy route the browser openai engine defaults to (#98.2). */
+const AI_PROXY_PATH = '/__pyric/ai-proxy';
+/**
+ * Node-side `EngineConfig` → JSON-safe {@link AiEngineConfigWire}. Mirrors the
+ * browser `toEngineWire` (entries/ai.ts): an openai config with no `baseUrl`
+ * targets the same-origin proxy; scripted `script` entries pass through (plain
+ * authoring shapes — function/RegExp matchers can't survive JSON and are not a
+ * plugin-config use case).
+ */
+export function engineConfigToWire(engine) {
+    if (engine.kind === 'openai') {
+        return {
+            kind: 'openai',
+            baseUrl: engine.baseUrl ?? AI_PROXY_PATH,
+            ...(engine.model !== undefined ? { model: engine.model } : {}),
+            ...(engine.modelMap !== undefined ? { modelMap: engine.modelMap } : {}),
+        };
+    }
+    return {
+        kind: 'scripted',
+        ...(engine.script !== undefined
+            ? { script: engine.script }
+            : {}),
+    };
+}
 /** The firebase subpaths with swap entries. */
 const SERVED = new Set(SDK_MODULES.map((specifier) => specifier.slice('firebase/'.length)));
 const entryKey = (subpath) => subpath.replaceAll('/', '-');
@@ -83,10 +113,10 @@ function packageRootOf(file) {
 /**
  * The dev-only Vite plugin. Add to `vite.config`:
  *
- *   import { pyricSandbox } from '@pyric/cli/vite';
- *   export default defineConfig({ plugins: [pyricSandbox()] });
+ *   import { pyric } from '@pyric/cli/vite';
+ *   export default defineConfig({ plugins: [pyric()] });
  */
-export function pyricSandbox(options = {}) {
+export function pyric(options = {}) {
     // Resolved once. `defaultSdkEntries()` prefers compiled dist `.js` and falls
     // back to source `.ts` in the workspace.
     const entries = defaultSdkEntries(); // { app, auth, firestore, init } → abs paths
@@ -177,6 +207,11 @@ export function pyricSandbox(options = {}) {
     // sandbox path — the bridge peer is the in-page sandbox, never the SharedWorker,
     // so multi-tab is disabled under bridge to keep agent + app on one backend.
     const bridgeOpts = options.bridge === true ? {} : options.bridge || null;
+    // Plugin-level AI engine, normalized once to the JSON-safe wire shape. Travels
+    // to the worker host via the init payload (→ ctx.aiEngine) AND to the in-page
+    // fallback via an injected synchronous global (see transformIndexHtml). Undefined
+    // when the `ai.engine` option is unset.
+    const aiEngineWire = options.ai?.engine ? engineConfigToWire(options.ai.engine) : undefined;
     return {
         name: 'pyric:sandbox',
         // Active for `vite dev` ALWAYS, and for `vite build` only when it is a
@@ -352,6 +387,30 @@ export function pyricSandbox(options = {}) {
             catch (e) {
                 server.config.logger.warn(`  ⚠ [pyric] SharedWorker bundle failed — using the in-page sandbox (single-tab, ephemeral): ${e instanceof Error ? e.message : String(e)}`);
             }
+            // ── Functions (RTDB triggers) — the `pyric dev` parity fold ───────────
+            // Discover the one supported Functions codebase from the same resolved
+            // firebase.json the rules used (project.ts reads it itself). Reuses the
+            // exact serve module, so absent `functions` → null (silently off) and a
+            // malformed config throws serve's own error text — which, thrown from an
+            // async configureServer, fails the dev start the same way serve's
+            // `return 2` aborts. The Functions child connects to the sandbox over the
+            // bridge WS, so a discovered codebase forces the bridge mount on (mirrors
+            // serve's `bridgeEnabledFor(..., functionsProject)`). `functions: false`
+            // is the off switch: discovery never runs, so neither does the mount.
+            const functionsOpts = typeof options.functions === 'object' ? options.functions : {};
+            let functionsProject = null;
+            if (options.functions !== false) {
+                try {
+                    functionsProject = discoverFunctionsRtdbProject(cwd);
+                }
+                catch (error) {
+                    // Malformed functions config: fail the start with serve's exact message.
+                    throw error instanceof Error ? error : new Error(String(error));
+                }
+            }
+            const functionsProjectId = functionsProject
+                ? (process.env.PYRIC_PROJECT ?? (await readFirebaseRc(cwd))?.projects?.default ?? 'demo-project')
+                : null;
             // ── M3 MCP bridge (mirrors serve.ts:221–274) ─────────────────────────
             // The mount is long-lived (one bridge per dev session); its MCP transport
             // is rebuilt per request (stateless). Composed into the /__pyric middleware
@@ -360,9 +419,12 @@ export function pyricSandbox(options = {}) {
             // Guard the WS upgrade with the SAME allow rule Vite's own host check
             // uses (host + allowedHosts, where `true` = opted into all hosts). Vite's
             // upgrade path bypasses connect middleware, so this is the only guard on it.
-            const mount = bridgeOpts
+            const mount = bridgeOpts || functionsProject
                 ? createBridgeMount({
-                    ...bridgeOpts,
+                    ...(bridgeOpts ?? {}),
+                    // A functions-only session still needs a labeled bridge; prefer an
+                    // explicit bridge project, else the resolved functions project id.
+                    project: bridgeOpts?.project ?? functionsProjectId ?? undefined,
                     upgradeGuard: {
                         boundHost: typeof server.config.server.host === 'string' ? server.config.server.host : 'localhost',
                         allowedHosts: server.config.server.allowedHosts === true
@@ -384,6 +446,9 @@ export function pyricSandbox(options = {}) {
                 databaseUrl: live.databaseUrl,
                 storageRules: live.storageRules,
                 storageRulesHash: live.storageRulesHash,
+                // Project identity: scopes the storage IDB name per served project
+                // (issue #359). Local-only — a dev path never leaves the machine.
+                projectKey: cwd,
                 // The bound port is known only after `listen`; initPayload runs per
                 // request (after listen), so resolve it lazily here. Absolute ws://host:port
                 // mirrors serve (the browser reads this as the bridge peer URL).
@@ -406,6 +471,9 @@ export function pyricSandbox(options = {}) {
                     : seedUsers,
                 // Messaging is part of the canonical firebase/* sandbox swap.
                 messaging: true,
+                // Plugin-level engine → the worker host's ctx.aiEngine (host-ai.ts),
+                // which wins over any op-carried engine. Null when unset.
+                ai: aiEngineWire ? { engine: aiEngineWire } : null,
             });
             // Pyric Studio: mount the disk-backed workspace/project routes that
             // Studio's `local` mode talks to + serve the built Studio app at
@@ -435,10 +503,22 @@ export function pyricSandbox(options = {}) {
                 sdkDir,
                 initPayload,
                 events,
+                activity: (incident) => server.config.logger.warn(formatActivityWarning(incident)),
                 state,
                 capture,
                 studio,
                 studioUiDir,
+                // `ai.proxyUpstream`: what `/__pyric/ai-proxy` forwards to (beats the
+                // PYRIC_AI_PROXY_UPSTREAM env var; falls back to the default when unset).
+                aiProxyUpstream: options.ai?.proxyUpstream,
+                // Adapt Vite's logger to the plain info/note shape the namespace's
+                // diagnostics (denial relay, future hot-reload lines) expect —
+                // matches the `↻`/`⚠ [pyric]` lines already logged elsewhere in this
+                // plugin via `server.config.logger` directly.
+                logger: {
+                    info: (m) => server.config.logger.info(m),
+                    note: (m) => server.config.logger.warn(m),
+                },
             });
             // DNS-rebinding guard for the /__pyric/* surface. Vite has its own host
             // check, but a `configureServer` hook that doesn't return a function mounts
@@ -565,6 +645,187 @@ export function pyricSandbox(options = {}) {
                     }
                 });
             }
+            // ── Functions child lifecycle (mirrors serve's runServe) ─────────────
+            // The Functions runtime executes in an isolated node child (child.ts),
+            // exactly as `pyric dev` runs it: the child loads the user's unchanged
+            // functions module, and `--import @pyric/cli/register` + `PYRIC_SANDBOX=
+            // remote:<serveUrl>` route its `firebase-admin/app` to a RemoteSandbox that
+            // dials the bridge WS (`/__pyric/sandbox`). onValueCreated triggers observe
+            // RTDB writes and write their effects back through that one shared sandbox.
+            // Started once a sandbox peer (a browser tab / SharedWorker relay) has
+            // connected — the trigger's baseline needs a live backend — and stopped on
+            // server close. Vite restarts re-run configureServer, so the child respawns
+            // with the new server. Unlike `pyric dev` (which does not watch functions
+            // source), the plugin hot-reloads it via Vite's own watcher — see the
+            // watch block below; `functions: { watch: false }` restores dev's
+            // restart-to-reload behavior.
+            if (functionsProject && functionsProjectId && mount && server.httpServer) {
+                const httpServer = server.httpServer;
+                const project = functionsProject;
+                const projectId = functionsProjectId;
+                const bridgeMount = mount;
+                const host = (typeof server.config.server.host === 'string' && server.config.server.host) || 'localhost';
+                // Prefer the compiled child (node cannot execute the .ts source when the
+                // plugin runs from source in tests); fall back to spawnFunctionsRtdbChild's
+                // own default (correct when the plugin runs from dist in production).
+                const builtChild = path.join(cliRoot, 'dist/functions-rtdb/child.js');
+                const childModuleUrl = existsSync(builtChild) ? builtChild : undefined;
+                let functionsChild = null;
+                let disposed = false;
+                const start = async (mode = 'initial') => {
+                    const addr = httpServer.address();
+                    const port = addr && typeof addr === 'object' ? addr.port : 0;
+                    if (!port || disposed)
+                        return;
+                    const serveUrl = `http://${host}:${port}`;
+                    // Wait (bounded) for a sandbox peer — the SharedWorker relay / browser
+                    // tab that holds the backend. Poll the mount directly (no self-fetch).
+                    // On a hot reload the peer is usually still connected (the loop exits
+                    // immediately); when it dropped mid-session, wait briefly rather than
+                    // the full initial 30s.
+                    const deadline = Date.now() + (mode === 'reload' ? 5_000 : 30_000);
+                    while (!disposed && !bridgeMount.sandboxConnected()) {
+                        if (Date.now() >= deadline)
+                            break;
+                        await new Promise((r) => setTimeout(r, 250));
+                    }
+                    if (disposed)
+                        return;
+                    if (!bridgeMount.sandboxConnected()) {
+                        server.config.logger.warn(mode === 'reload'
+                            ? `  ✖ [pyric] functions not restarted — no sandbox peer connected. ` +
+                                `Functions stay down until the next save with ${serveUrl} open.`
+                            : `  ⚠ [pyric] functions not started — no browser tab connected after 30s. ` +
+                                `Open ${serveUrl} and restart the dev server.`);
+                        return;
+                    }
+                    functionsChild = spawnFunctionsRtdbChild({
+                        cwd: project.sourceDir,
+                        entry: project.entry,
+                        env: buildChildEnv(process.env, { serveUrl, registerUrl: registerModuleUrl() }),
+                        // Precedence (per field): plugin option > env var > firebase files
+                        // > default. projectId already folds PYRIC_PROJECT > .firebaserc >
+                        // demo-project.
+                        instance: functionsOpts.instance ?? `${projectId}-default-rtdb`,
+                        location: functionsOpts.region ?? process.env.PYRIC_FUNCTIONS_RTDB_REGION ?? 'us-central1',
+                        ...(childModuleUrl ? { childModuleUrl } : {}),
+                        onEvent(event) {
+                            if (event.type === 'execution') {
+                                const params = Object.entries(event.params)
+                                    .map(([name, value]) => `${name}=${value}`)
+                                    .join(', ');
+                                const suffix = params ? ` (${params})` : '';
+                                if (event.status === 'fulfilled') {
+                                    server.config.logger.info(`  ✔ [pyric] function ${event.exportName} ← /${event.ref}${suffix}`);
+                                }
+                                else {
+                                    server.config.logger.error(`  ✖ [pyric] function ${event.exportName} ← /${event.ref}${suffix}: ${event.error.message}`);
+                                }
+                            }
+                            else {
+                                server.config.logger.error(`  ✖ [pyric] functions delivery for ${event.exportName}: ${event.error.message}`);
+                            }
+                        },
+                    });
+                    const out = createLinePrefixer('[functions] ', (line) => server.config.logger.info(line.replace(/\n$/, '')));
+                    const err = createLinePrefixer('[functions] ', (line) => server.config.logger.warn(line.replace(/\n$/, '')));
+                    functionsChild.child.stdout?.setEncoding('utf8');
+                    functionsChild.child.stderr?.setEncoding('utf8');
+                    functionsChild.child.stdout?.on('data', (chunk) => out.push(chunk));
+                    functionsChild.child.stderr?.on('data', (chunk) => err.push(chunk));
+                    functionsChild.child.stdout?.once('end', () => out.flush());
+                    functionsChild.child.stderr?.once('end', () => err.flush());
+                    try {
+                        const ready = await functionsChild.ready;
+                        server.config.logger.info(mode === 'reload'
+                            ? `  ↻ [pyric] functions reloaded (${ready.triggerCount} trigger${ready.triggerCount === 1 ? '' : 's'})`
+                            : `  ✔ [pyric] functions ${ready.triggerCount} onValueCreated ` +
+                                `trigger${ready.triggerCount === 1 ? '' : 's'} from ${path.relative(cwd, project.entry)}`);
+                        for (const unsupported of ready.unsupportedTriggers) {
+                            server.config.logger.warn(`  ⚠ [pyric] functions export ${unsupported.exportName} uses unsupported trigger ` +
+                                `${unsupported.eventType}; it will not run.`);
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        server.config.logger.error(mode === 'reload'
+                            ? // Unlike rules, last-good cannot stay live — the old child is
+                                // already stopped — so a broken save takes functions down.
+                                `  ✖ [pyric] functions failed to reload: ${message}\n` +
+                                    `  ✖ [pyric] functions are down until the next good save.`
+                            : `  ✖ [pyric] functions failed to start: ${message}`);
+                        await functionsChild.stop().catch(() => undefined);
+                        functionsChild = null;
+                    }
+                };
+                let reloadDebounce = null;
+                httpServer.once('close', () => {
+                    disposed = true;
+                    if (reloadDebounce)
+                        clearTimeout(reloadDebounce);
+                    void functionsChild?.stop().catch(() => undefined);
+                });
+                if (httpServer.listening)
+                    void start();
+                else
+                    httpServer.once('listening', () => void start());
+                // Functions hot-reload from Vite's OWN watcher (mirrors the rules block
+                // below). Restart = redeploy: stop the old child, respawn via the same
+                // start path — there is no in-place swap, so in-flight executions in the
+                // old child may drop and writes landing in the swap gap become the new
+                // child's baseline (execution.ts consumes each trigger's first observed
+                // value as baseline; they do not fire). Debounced 300ms — a save fans
+                // out several fs events and a child respawn is far heavier than a rules
+                // re-parse. Restarts are serialized: a save landing mid-restart queues
+                // exactly one follow-up run.
+                if (functionsOpts.watch !== false) {
+                    const sourceDir = project.sourceDir;
+                    // Usually redundant (Vite watches its root, which contains the
+                    // functions dir in the common layout) but load-bearing when the
+                    // functions source lives outside Vite's root. node_modules stays
+                    // ignored: Vite's watcher ignores `**/node_modules/**` globally, and
+                    // the handler below filters it again for explicitly-added trees.
+                    server.watcher.add(sourceDir);
+                    let restarting = false;
+                    let queued = false;
+                    const restart = async () => {
+                        if (restarting) {
+                            queued = true;
+                            return;
+                        }
+                        restarting = true;
+                        try {
+                            do {
+                                queued = false;
+                                if (disposed)
+                                    return;
+                                const old = functionsChild;
+                                functionsChild = null;
+                                if (old)
+                                    await old.stop().catch(() => undefined);
+                                await start('reload');
+                            } while (queued && !disposed);
+                        }
+                        finally {
+                            restarting = false;
+                        }
+                    };
+                    const onFunctionsFsEvent = (file) => {
+                        const resolved = path.resolve(file);
+                        const rel = path.relative(sourceDir, resolved);
+                        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+                            return;
+                        if (rel.split(path.sep).includes('node_modules'))
+                            return;
+                        if (reloadDebounce)
+                            clearTimeout(reloadDebounce);
+                        reloadDebounce = setTimeout(() => void restart(), 300);
+                    };
+                    server.watcher.on('change', onFunctionsFsEvent);
+                    server.watcher.on('add', onFunctionsFsEvent);
+                    server.watcher.on('unlink', onFunctionsFsEvent);
+                }
+            }
             // Rules hot-reload from Vite's OWN watcher (no second fs watcher). Reuse
             // prepareRulesSource (resolve + lint); last-good stays live on a broken save.
             // Debounced (editors emit several change events per save) — matches
@@ -653,10 +914,19 @@ export function pyricSandbox(options = {}) {
             const head = workerReady
                 ? `<meta name="pyric-worker-v" content="${workerVersion}" ${MARKER}>`
                 : `<script ${MARKER}>globalThis.__PYRIC_FORCE_INPAGE__=true;</script>`;
+            // Plugin-level engine for the IN-PAGE path: a classic inline script runs
+            // before the deferred init module AND before app code's `getAI`, so the
+            // served `getAI` (entries/ai.ts) reads it synchronously — init.json can't
+            // be awaited there. Harmless on the worker path (that branch ignores the
+            // global; the worker reads ctx.aiEngine from init.json). `<` is escaped so
+            // an engine value can never break out of the script tag.
+            const aiEngineTag = aiEngineWire
+                ? `<script ${MARKER}>globalThis.__PYRIC_AI_ENGINE__=${JSON.stringify(aiEngineWire).replace(/</g, '\\u003c')};</script>`
+                : '';
             // Boot the sandbox by loading the real init entry as a module (Vite
             // serves + transforms it). The init module's top-level await deploys rules
             // before app code runs. Mirrors serve's injectServeTags.
-            const tag = head + `<script type="module" src="/@fs/${entries.init}" ${MARKER}></script>`;
+            const tag = head + aiEngineTag + `<script type="module" src="/@fs/${entries.init}" ${MARKER}></script>`;
             return html.includes('</head>') ? html.replace('</head>', `${tag}</head>`) : tag + html;
         },
     };