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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyric/cli",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "license": "Apache-2.0",
   "homepage": "https://pyric.dev",
   "repository": {
@@ -13,6 +13,12 @@
   },
   "description": "Pyric CLI for local sandbox development, verification, artifact generation, and agent bridges.",
   "type": "module",
+  "sideEffects": [
+    "./dist/register/index.js",
+    "./src/register/index.ts",
+    "./dist/serve/entries/*.js",
+    "./src/serve/entries/*.ts"
+  ],
   "exports": {
     "./credentials/node": {
       "types": "./dist/credentials/node/index.d.ts",
@@ -73,6 +79,10 @@
       "types": "./dist/next/index.d.ts",
       "import": "./dist/next/index.js"
     },
+    "./bundler": {
+      "types": "./dist/bundler/index.d.ts",
+      "import": "./dist/bundler/index.js"
+    },
     "./serve/worker": {
       "types": "./dist/serve/worker/index.d.ts",
       "import": "./dist/serve/worker/index.js"
@@ -109,11 +119,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "prebuild": "bun run scripts/generate-service-command-registry.ts && (test \"${PYRIC_CONFORMANCE_READY:-0}\" = \"1\" || bun run ../../packages/conformance/src/generate-projections.ts --write)",
+    "prebuild": "bun run scripts/generate-service-command-registry.ts && bun run scripts/generate-tool-family-registry.ts && (test \"${PYRIC_CONFORMANCE_READY:-0}\" = \"1\" || bun run ../../packages/conformance/src/generate-projections.ts --write)",
     "build": "tsc && bun run scripts/postbuild.ts",
     "pretest": "bash ../../scripts/build.sh --packages-only",
     "test": "bun test",
     "test:app-conformance": "playwright test app-deletion.pw.ts app-multi-app.pw.ts ai-worker-boundary.pw.ts messaging-app-boundary.pw.ts --config test/e2e/playwright.config.ts",
+    "test:identity-conformance": "playwright test identity-switch.pw.ts auth-popup.pw.ts --config test/e2e/playwright.config.ts",
     "test:site-cli": "playwright test --config test/e2e/site-cli/playwright.config.ts",
     "test:site-static": "playwright test --config test/e2e/site-static/playwright.config.ts",
     "test:soak": "playwright test --config test/e2e/soak/playwright.config.ts",
@@ -127,11 +138,11 @@
   "dependencies": {
     "@inbrowser/agent": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "create-pyric": "^0.1.0-alpha.20",
+    "create-pyric": "^0.1.0-alpha.21",
     "esbuild": "^0.28.0",
     "fake-indexeddb": "^6.0.0",
-    "pyric": "^0.1.0-alpha.20",
-    "pyric-admin": "^0.1.0-alpha.20",
+    "pyric": "^0.1.0-alpha.21",
+    "pyric-admin": "^0.1.0-alpha.21",
     "ws": "^8.18.0",
     "zod": "^3.23.0"
   },

package/src/assurance/.generated/conformance-verdicts.ts

@@ -397,6 +397,71 @@ export const CONFORMANCE_VERDICTS = {
   "firestore#97": "supported",
   "firestore#98": "supported",
   "firestore#99": "supported",
+  "firestore-flutter#1": "supported",
+  "firestore-flutter#10": "qualified",
+  "firestore-flutter#11": "supported",
+  "firestore-flutter#12": "qualified",
+  "firestore-flutter#13": "qualified",
+  "firestore-flutter#14": "supported",
+  "firestore-flutter#15": "supported",
+  "firestore-flutter#16": "supported",
+  "firestore-flutter#17": "supported",
+  "firestore-flutter#18": "supported",
+  "firestore-flutter#19": "supported",
+  "firestore-flutter#2": "supported",
+  "firestore-flutter#20": "supported",
+  "firestore-flutter#21": "supported",
+  "firestore-flutter#22": "supported",
+  "firestore-flutter#23": "supported",
+  "firestore-flutter#24": "supported",
+  "firestore-flutter#25": "supported",
+  "firestore-flutter#26": "supported",
+  "firestore-flutter#27": "supported",
+  "firestore-flutter#28": "supported",
+  "firestore-flutter#29": "supported",
+  "firestore-flutter#3": "supported",
+  "firestore-flutter#30": "supported",
+  "firestore-flutter#31": "supported",
+  "firestore-flutter#32": "supported",
+  "firestore-flutter#33": "supported",
+  "firestore-flutter#34": "supported",
+  "firestore-flutter#35": "supported",
+  "firestore-flutter#36": "supported",
+  "firestore-flutter#37": "supported",
+  "firestore-flutter#38": "supported",
+  "firestore-flutter#39": "supported",
+  "firestore-flutter#4": "supported",
+  "firestore-flutter#40": "supported",
+  "firestore-flutter#41": "supported",
+  "firestore-flutter#42": "supported",
+  "firestore-flutter#43": "supported",
+  "firestore-flutter#44": "supported",
+  "firestore-flutter#45": "supported",
+  "firestore-flutter#46": "supported",
+  "firestore-flutter#47": "supported",
+  "firestore-flutter#48": "supported",
+  "firestore-flutter#49": "supported",
+  "firestore-flutter#5": "supported",
+  "firestore-flutter#50": "supported",
+  "firestore-flutter#51": "supported",
+  "firestore-flutter#52": "supported",
+  "firestore-flutter#53": "qualified",
+  "firestore-flutter#54": "supported",
+  "firestore-flutter#55": "supported",
+  "firestore-flutter#56": "supported",
+  "firestore-flutter#57": "supported",
+  "firestore-flutter#58": "supported",
+  "firestore-flutter#59": "supported",
+  "firestore-flutter#6": "supported",
+  "firestore-flutter#60": "supported",
+  "firestore-flutter#61": "supported",
+  "firestore-flutter#62": "supported",
+  "firestore-flutter#63": "supported",
+  "firestore-flutter#64": "supported",
+  "firestore-flutter#65": "supported",
+  "firestore-flutter#7": "supported",
+  "firestore-flutter#8": "supported",
+  "firestore-flutter#9": "qualified",
   "firestore-rules#160": "supported",
   "firestore-rules#161": "supported",
   "firestore-rules#162": "supported",
@@ -450,7 +515,7 @@ export const CONFORMANCE_VERDICTS = {
   "firestore.function.cast.int": "supported",
   "firestore.function.cast.path": "supported",
   "firestore.function.cast.string": "supported",
-  "firestore.function.debug": "unsupported",
+  "firestore.function.debug": "supported",
   "firestore.function.duration.abs": "supported",
   "firestore.function.duration.time": "supported",
   "firestore.function.duration.value": "supported",
@@ -1065,6 +1130,8 @@ export const CONFORMANCE_VERDICTS = {
   "storage-rules#130": "supported",
   "storage-rules#131": "supported",
   "storage-rules#132": "supported",
+  "storage-rules#133": "supported",
+  "storage-rules#134": "supported",
   "storage-rules#94": "supported",
   "storage-rules#95": "supported",
   "storage-rules#96": "supported",

package/src/bridge/client/dispatch.ts

@@ -1,31 +1,28 @@
 /**
- * Browser-side tool dispatcher. Consumes the SAME tool factories the
- * bridge advertises over MCP (`getSandboxToolMetadata`), so the set the
- * bridge LISTS and the set the page EXECUTES are identical. There is one
- * source of truth: the factories in `buildSandboxHandlers`.
+ * Browser-side tool dispatcher. Composes the forwarded tool families from the
+ * same records the bridge advertises over MCP (`getSandboxToolMetadata`), so
+ * the set the bridge LISTS and the set the page EXECUTES are identical by
+ * construction: the records under `../tool-family-records/` pin the names,
+ * and `./tool-family-factories.ts` supplies one browser-safe factory per
+ * family.
  *
- * History of the trap this guards against: earlier this file delegated
- * to ONLY `createFirestoreSimulatorTools`, while `getSandboxToolMetadata`
- * advertised the simulator + data-plane + inspect families. The bridge
- * therefore LISTED `firestore_create_document` / `sandbox_inspect`
- * etc., but a `callTool` failed at dispatch with "tool 'X' is not
- * registered with the connected sandbox peer" — succeed-at-list,
- * fail-at-dispatch. Registering every family here (and deriving
- * `SANDBOX_TOOL_NAMES` from the same set) closes the gap. The parity is
- * pinned by `test/bridge/tool-parity.test.ts`.
+ * History of the trap this guards against: earlier this file delegated to
+ * ONLY the simulator factory, while the bridge advertised the simulator,
+ * data-plane and inspect families. The bridge therefore LISTED
+ * `firestore_create_document` / `sandbox_inspect` etc., but a `callTool`
+ * failed at dispatch with "tool 'X' is not registered with the connected
+ * sandbox peer" (succeed-at-list, fail-at-dispatch). Composing every family
+ * from the records, and deriving `SANDBOX_TOOL_NAMES` from the same records,
+ * closes the gap. The parity is pinned by `test/bridge/tool-parity.test.ts`
+ * and `test/bridge/tool-families.test.ts`.
  */
 
-import { createFirestoreSimulatorTools } from 'pyric/rules/internal';
-import {
-  createFirestoreDataTools,
-  createFirestoreInspectTools,
-  getFirestore,
-  getAdminFirestore,
-  type As,
-} from 'pyric/firestore';
+import type { ToolHandler } from '@inbrowser/agent';
+import { getFirestore, getAdminFirestore, type As } from 'pyric/firestore';
 import { getInternalEnv } from 'pyric/sandbox/internal';
 import type { LocalSandbox } from 'pyric/sandbox';
-import { createRtdbInspectionTools } from '../../rtdb/inspection.js';
+import { assertExactToolNames, toolFamilies } from '../tool-families.js';
+import { SANDBOX_HANDLER_FACTORIES, type SandboxBinding } from './tool-family-factories.js';
 
 export interface DispatchResult {
   ok: boolean;
@@ -34,11 +31,8 @@ export interface DispatchResult {
 }
 
 /**
- * The full handler set for a sandbox: the simulator family (bound to the
- * internal env) plus the modular data-plane and inspect families (bound
- * to a per-call `resolveDb`). This is the single source of truth shared
- * by `buildSandboxDispatcher` and `SANDBOX_TOOL_NAMES`, and it MUST stay
- * aligned with `getSandboxToolMetadata` (asserted by tool-parity.test.ts).
+ * The full handler set for a sandbox: every forwarded family bound to one
+ * `SandboxBinding` built here.
  *
  * Auth: `resolveDb('admin')` / `resolveDb(undefined)` is an admin-bypass handle
  * (no rules); `resolveDb({ uid, claims })` is a rules-enforcing client acting as
@@ -46,29 +40,39 @@ export interface DispatchResult {
  * `request.auth.token` shape. This is a SANDBOX dispatcher, so the admin default
  * is intended; a dispatcher wired to a real backend must reject `'admin'`.
  */
-function buildSandboxHandlers(sandbox: LocalSandbox) {
-  const env = getInternalEnv(sandbox);
-  const resolveDb = (actor?: As) =>
-    actor && actor !== 'admin'
-      ? getFirestore(sandbox.withAuth({ uid: actor.uid, token: actor.claims }))
-      : getAdminFirestore(sandbox);
-  return [
-    ...createFirestoreSimulatorTools({ resolveSandbox: () => env }),
-    ...createFirestoreDataTools({ resolveDb }),
-    ...createFirestoreInspectTools({ resolveSandbox: () => sandbox }),
-    ...createRtdbInspectionTools({ resolveSandbox: () => sandbox }),
-  ];
+function buildSandboxHandlers(sandbox: LocalSandbox): ToolHandler[] {
+  const binding: SandboxBinding = {
+    sandbox,
+    env: getInternalEnv(sandbox),
+    resolveDb: (actor?: As) =>
+      actor && actor !== 'admin'
+        ? getFirestore(sandbox.withAuth({ uid: actor.uid, token: actor.claims }))
+        : getAdminFirestore(sandbox),
+  };
+  return toolFamilies('forwarded').flatMap((family) =>
+    SANDBOX_HANDLER_FACTORIES[family.key](binding),
+  );
 }
 
 /**
  * Build a dispatcher for the supplied `Sandbox`. The returned function
- * looks up tools by name across every factory and invokes the
+ * looks up tools by name across every family and invokes the
  * canonical handler. Throws `UnknownToolError` on unknown names.
+ *
+ * Fails closed before any dispatch if the bound handlers do not yield exactly
+ * the names the family records pin, so a factory that drifts from its record
+ * surfaces when the sandbox connects rather than at the first call.
  */
 export function buildSandboxDispatcher(
   sandbox: LocalSandbox,
 ): (name: string, args: Record<string, unknown>) => Promise<DispatchResult> {
-  const byName = new Map(buildSandboxHandlers(sandbox).map((h) => [h.name, h]));
+  const handlers = buildSandboxHandlers(sandbox);
+  assertExactToolNames(
+    'sandbox dispatcher tools',
+    handlers.map((h) => h.name),
+    SANDBOX_TOOL_NAMES,
+  );
+  const byName = new Map(handlers.map((h) => [h.name, h]));
   return async (name, args) => {
     const handler = byName.get(name);
     if (!handler) throw new UnknownToolError(name);
@@ -112,22 +116,14 @@ export async function dispatchSandboxTool(
 }
 
 /**
- * Tool names this dispatcher recognises, derived at load time from the
- * SAME factories — so it equals what the page executes AND what the
- * bridge advertises. `connectBridge` sends this as the `hello.tools`
- * payload so the bridge advertises exactly the executable set.
+ * Tool names this dispatcher recognises, read from the forwarded family
+ * records in family order, so it equals what the page executes AND what the
+ * bridge advertises. `connectBridge` sends this as the `hello.tools` payload
+ * so the bridge advertises exactly the executable set.
  */
-export const SANDBOX_TOOL_NAMES: string[] = (() => {
-  const stub = async () => {
-    throw new Error('SANDBOX_TOOL_NAMES: stub resolver should never be invoked');
-  };
-  return [
-    ...createFirestoreSimulatorTools({ resolveSandbox: stub as never }),
-    ...createFirestoreDataTools({ resolveDb: stub as never }),
-    ...createFirestoreInspectTools({ resolveSandbox: stub as never }),
-    ...createRtdbInspectionTools({ resolveSandbox: stub as never }),
-  ].map((h) => h.name);
-})();
+export const SANDBOX_TOOL_NAMES: readonly string[] = toolFamilies('forwarded').flatMap(
+  (family) => family.tools,
+);
 
 export class UnknownToolError extends Error {
   constructor(public readonly tool: string) {

package/src/bridge/client/tool-family-factories.ts

@@ -0,0 +1,34 @@
+/**
+ * Browser-side factory for each forwarded tool family, bound to one
+ * sandbox. Imports only browser-safe subpaths (`pyric/rules/internal`, never
+ * `/node`); the Node side has its own map in `server/tool-family-factories.ts`.
+ *
+ * The keys are the family record filenames. `satisfies` against the keys
+ * derived from the generated aggregate makes a missing or surplus entry a
+ * compile error.
+ */
+import type { ToolHandler } from '@inbrowser/agent';
+import { createFirestoreSimulatorTools } from 'pyric/rules/internal';
+import {
+  createFirestoreDataTools,
+  createFirestoreInspectTools,
+  type FirestoreDataToolDeps,
+} from 'pyric/firestore';
+import type { LocalSandbox } from 'pyric/sandbox';
+import type { getInternalEnv } from 'pyric/sandbox/internal';
+import { createRtdbInspectionTools } from '../../rtdb/inspection.js';
+import type { ForwardedFamilyKey } from '../tool-families.js';
+
+/** Everything a forwarded family needs from one sandbox, built once per sandbox. */
+export interface SandboxBinding {
+  sandbox: LocalSandbox;
+  env: ReturnType<typeof getInternalEnv>;
+  resolveDb: FirestoreDataToolDeps['resolveDb'];
+}
+
+export const SANDBOX_HANDLER_FACTORIES = {
+  'firestore-simulator': ({ env }) => createFirestoreSimulatorTools({ resolveSandbox: () => env }),
+  'firestore-data': ({ resolveDb }) => createFirestoreDataTools({ resolveDb }),
+  'firestore-inspect': ({ sandbox }) => createFirestoreInspectTools({ resolveSandbox: () => sandbox }),
+  'rtdb-inspection': ({ sandbox }) => createRtdbInspectionTools({ resolveSandbox: () => sandbox }),
+} satisfies Record<ForwardedFamilyKey, (binding: SandboxBinding) => ToolHandler[]>;

package/src/bridge/server/mcp-contract.ts

@@ -1,4 +1,5 @@
 import type { ToolHandler } from '@inbrowser/agent';
+import { assertExactToolNames, toolFamilies } from '../tool-families.js';
 import {
   getInProcessToolHandlers,
   getSandboxToolMetadata,
@@ -6,75 +7,30 @@ import {
 } from './tool-metadata.js';
 
 /**
- * The exact tools a default local Pyric MCP server forwards to its sandbox.
- * A tool addition or removal is a public contract change and must update this
- * manifest deliberately.
+ * The exact tools a default local Pyric MCP server forwards to its sandbox,
+ * in `tools/list` order. Names are authored in `bridge/tool-family-records/`;
+ * a tool addition or removal is a public contract change and must update the
+ * family record deliberately.
  */
-export const DEFAULT_MCP_FORWARDED_TOOL_NAMES = [
-  'firestore_simulator_create',
-  'firestore_simulator_execute',
-  'firestore_simulator_read',
-  'firestore_simulator_batch',
-  'firestore_create_with_auto_id',
-  'firestore_simulator_undo',
-  'firestore_simulator_redo',
-  'firestore_simulator_events',
-  'firestore_simulator_transaction',
-  'firestore_get_document',
-  'firestore_list_documents',
-  'firestore_create_document',
-  'firestore_add_document',
-  'firestore_update_document',
-  'firestore_delete_document',
-  'firestore_batch_write',
-  'firestore_query_where',
-  'sandbox_inspect',
-  'rtdb_simulate_access',
-  'rtdb_crawl_structure',
-] as const;
+export const DEFAULT_MCP_FORWARDED_TOOL_NAMES: readonly string[] = toolFamilies(
+  'forwarded',
+).flatMap((family) => family.tools);
 
 /** Local rules tools that run in the MCP process without a browser peer. */
-export const DEFAULT_MCP_IN_PROCESS_TOOL_NAMES = [
-  'firestore_simulate_rules',
-  'firestore_rules_stdlib_list',
-  'firestore_rules_stdlib_get',
-  'firestore_lint_rules',
-  'firestore_resolve_modules',
-  'rules_stdlib_list',
-  'rules_stdlib_get',
-  'rules_resolve_modules',
-  'pyric_can_i_use',
-] as const;
+export const DEFAULT_MCP_IN_PROCESS_TOOL_NAMES: readonly string[] = toolFamilies(
+  'in-process',
+).flatMap((family) => family.tools);
 
-export const DEFAULT_MCP_TOOL_NAMES = [
+export const DEFAULT_MCP_TOOL_NAMES: readonly string[] = [
   ...DEFAULT_MCP_FORWARDED_TOOL_NAMES,
   ...DEFAULT_MCP_IN_PROCESS_TOOL_NAMES,
-] as const;
+];
 
 export interface DefaultMcpToolSurface {
   forwarded: ToolMetadata[];
   inProcess: ToolHandler[];
 }
 
-function assertExactNames(
-  label: string,
-  actual: readonly string[],
-  expected: readonly string[],
-): void {
-  const actualSorted = [...actual].sort();
-  const expectedSorted = [...expected].sort();
-  if (
-    actualSorted.length !== expectedSorted.length ||
-    actualSorted.some((name, index) => name !== expectedSorted[index])
-  ) {
-    throw new Error(
-      `${label} drifted from the default MCP contract\n` +
-        `expected: ${expected.join(', ')}\n` +
-        `actual:   ${actual.join(', ')}`,
-    );
-  }
-}
-
 /**
  * Assemble the default MCP surface and fail closed if a factory changed
  * without a corresponding public-contract decision.
@@ -82,12 +38,12 @@ function assertExactNames(
 export function getDefaultMcpToolSurface(): DefaultMcpToolSurface {
   const forwarded = getSandboxToolMetadata();
   const inProcess = getInProcessToolHandlers();
-  assertExactNames(
+  assertExactToolNames(
     'forwarded sandbox tools',
     forwarded.map((tool) => tool.name),
     DEFAULT_MCP_FORWARDED_TOOL_NAMES,
   );
-  assertExactNames(
+  assertExactToolNames(
     'in-process tools',
     inProcess.map((tool) => tool.name),
     DEFAULT_MCP_IN_PROCESS_TOOL_NAMES,

package/src/bridge/server/peer.ts

@@ -209,13 +209,36 @@ export function createConsumerSession(
   };
 }
 
-export async function collectBody(req: IncomingMessage): Promise<unknown> {
+/** Thrown by {@link collectBody} when a body exceeds the caller's limit. The
+ *  code lets a route answer 413 instead of treating it as malformed JSON. */
+export const BODY_TOO_LARGE_CODE = 'PYRIC_BODY_TOO_LARGE';
+
+/**
+ * Read a request body and parse it as JSON.
+ *
+ * `limitBytes` caps how much is buffered. A route that is reachable by
+ * anything other than a trusted local caller must pass one: without it a
+ * single request can grow the string until the process dies.
+ */
+export async function collectBody(
+  req: IncomingMessage,
+  limitBytes?: number,
+): Promise<unknown> {
   if (req.method === 'GET' || req.method === 'DELETE') return undefined;
   return await new Promise<unknown>((resolve, reject) => {
     let raw = '';
+    let overLimit = false;
     req.setEncoding('utf8');
     req.on('data', (chunk) => {
+      // Past the limit the rest of the upload is read and discarded rather
+      // than the socket being destroyed. Destroying resets the connection, so
+      // the caller's 413 would never reach the client.
+      if (overLimit) return;
       raw += chunk;
+      if (limitBytes === undefined || Buffer.byteLength(raw) <= limitBytes) return;
+      overLimit = true;
+      raw = '';
+      reject(Object.assign(new Error('request body too large'), { code: BODY_TOO_LARGE_CODE }));
     });
     req.on('end', () => {
       if (!raw) {

package/src/bridge/server/tool-family-factories.ts

@@ -0,0 +1,40 @@
+/**
+ * Node-side factory for each tool family. This is the only bridge module
+ * that imports `pyric/rules/internal/node` or the conformance tools; the
+ * browser side has its own map in `client/tool-family-factories.ts`.
+ *
+ * The keys are the family record filenames. `satisfies` against the keys
+ * derived from the generated aggregate makes a missing or surplus entry a
+ * compile error.
+ */
+import type { ToolHandler } from '@inbrowser/agent';
+import {
+  createFirestoreSimulatorTools,
+  createFirestoreRulesTools,
+} from 'pyric/rules/internal/node';
+import { createFirestoreDataTools, createFirestoreInspectTools } from 'pyric/firestore';
+import { createRtdbInspectionTools } from '../../rtdb/inspection.js';
+import { createConformanceTools } from '../../conformance/tools.js';
+import type { ForwardedFamilyKey, InProcessFamilyKey } from '../tool-families.js';
+
+/** A resolver that must never run: forwarded families are executed by the browser peer, not here. */
+export type StubResolver = () => never;
+
+/** Forwarded families, called with a stub so only metadata is read. */
+export const FORWARDED_METADATA_FACTORIES = {
+  'firestore-simulator': (stub) => createFirestoreSimulatorTools({ resolveSandbox: stub as never }),
+  'firestore-data': (stub) => createFirestoreDataTools({ resolveDb: stub as never }),
+  'firestore-inspect': (stub) => createFirestoreInspectTools({ resolveSandbox: stub as never }),
+  'rtdb-inspection': (stub) => createRtdbInspectionTools({ resolveSandbox: stub as never }),
+} satisfies Record<ForwardedFamilyKey, (stub: StubResolver) => ToolHandler[]>;
+
+/**
+ * In-process families, returned as live handlers the MCP server registers
+ * directly. `scope` reaches the rules factory, which appends a hosted
+ * verification tool only when one is supplied; the default surface supplies
+ * none.
+ */
+export const IN_PROCESS_HANDLER_FACTORIES = {
+  'firestore-rules': (scope) => createFirestoreRulesTools({ scope } as never),
+  conformance: () => createConformanceTools(),
+} satisfies Record<InProcessFamilyKey, (scope?: unknown) => ToolHandler[]>;

package/src/bridge/server/tool-metadata.ts

@@ -1,26 +1,27 @@
 /**
- * Extract tool metadata (name + description + parameters) from the
- * existing `pyric/rules` factories without running any
- * tool logic. Used by the bridge to register MCP tools whose actual
- * dispatch happens against the connected browser peer.
+ * Node-side composition of the tool families the bridge serves over MCP.
  *
- * Why: `createFirestoreSimulatorTools` returns `ToolHandler[]` with
- * `execute` bound to a `LocalEnvironment`. The bridge process doesn't
- * have a `LocalEnvironment` — it forwards. But it does need the
- * metadata to populate the MCP server's tool list. This module calls
- * the factory with a stub resolver and reads only the metadata; the
- * stub never gets invoked because the bridge replaces `execute`
- * before dispatch.
+ * Forwarded families are executed by the browser sandbox peer, so this
+ * process never holds a `LocalEnvironment`. It still needs each tool's
+ * metadata (name, description, parameters) to populate the MCP tool list, so
+ * it calls the family factories with a stub resolver and reads only the
+ * metadata; the bridge replaces `execute` with forward-to-peer dispatch
+ * before any call reaches a handler.
+ *
+ * In-process families run here without a browser peer and are returned as
+ * live handlers.
+ *
+ * Family order comes from the records under `../tool-family-records/`; the
+ * factories come from `./tool-family-factories.ts`.
  */
 
 import type { ToolHandler } from '@inbrowser/agent';
+import { toolFamilies } from '../tool-families.js';
 import {
-  createFirestoreSimulatorTools,
-  createFirestoreRulesTools,
-} from 'pyric/rules/internal/node';
-import { createFirestoreDataTools, createFirestoreInspectTools } from 'pyric/firestore';
-import { createRtdbInspectionTools } from '../../rtdb/inspection.js';
-import { createConformanceTools } from '../../conformance/tools.js';
+  FORWARDED_METADATA_FACTORIES,
+  IN_PROCESS_HANDLER_FACTORIES,
+  type StubResolver,
+} from './tool-family-factories.js';
 
 export interface ToolMetadata {
   name: string;
@@ -37,63 +38,30 @@ function toMetadata(handler: ToolHandler): ToolMetadata {
 }
 
 /**
- * Tool metadata for the sandbox bridge. Includes the
- * data-plane / sandbox-management tools that the browser dispatches
- * via `LocalEnvironment`. Rules tooling (lint, validate, simulate,
- * test) is NOT included here — those execute in Node and are
- * registered separately, since they don't need the browser sandbox.
+ * Tool metadata for every forwarded family, in family order. The stub
+ * resolver never runs: the bridge replaces `execute()` with its own
+ * forward-to-peer dispatch.
  */
 export function getSandboxToolMetadata(): ToolMetadata[] {
-  // The resolver stub never runs: the bridge replaces execute() with
-  // its own forward-to-peer dispatch.
-  const stubResolver = async () => {
+  const stub: StubResolver = () => {
     throw new Error(
       'BUG: sandbox-tool factory executor invoked on the bridge side — should have been replaced',
     );
   };
-  const handlers: ToolHandler[] = [
-    // Simulator / write / batch / undo / redo / events / transaction —
-    // 8 tools that mutate or read the in-browser sandbox state.
-    ...createFirestoreSimulatorTools({
-      resolveSandbox: stubResolver as never,
-    }),
-    // Data plane — addDoc / setDoc / getDoc / updateDoc / deleteDoc /
-    // collection / query / where — the modular Firestore CRUD surface
-    // routed through the browser sandbox so agents can drive a real app
-    // session rather than only the simulator.
-    ...createFirestoreDataTools({
-      resolveDb: stubResolver as never,
-    }),
-    // `sandbox_inspect` — single-call diagnostic that answers
-    // "what state is the sandbox in?" Born out of CLAUDE_DEBUG_SESSION.md
-    // (a real agent needing 51 tool calls + 72k tokens to figure out
-    // that rules weren't loaded). Routes to the browser sandbox like
-    // the other forwarded tools.
-    ...createFirestoreInspectTools({
-      resolveSandbox: stubResolver as never,
-    }),
-    ...createRtdbInspectionTools({
-      resolveSandbox: stubResolver as never,
-    }),
-  ];
-  return handlers.map(toMetadata);
+  return toolFamilies('forwarded')
+    .flatMap((family) => FORWARDED_METADATA_FACTORIES[family.key](stub))
+    .map(toMetadata);
 }
 
 /**
- * Tooling factories that execute in-process on the bridge
- * (no browser needed). Returned as live ToolHandlers — the bridge
+ * Live handlers for every in-process family, in family order. The bridge
  * registers each handler's `execute` directly.
  *
  * `scope` is forwarded so the hosted Rules Test API verification tool can
  * authenticate without changing the bridge's sandbox-only execution model.
  */
 export function getInProcessToolHandlers(scope?: unknown): ToolHandler[] {
-  // Factory accepts { scope } per packages/pyric/src/rules/tools.ts.
-  // The bridge does not need to own the structurally compatible type.
-  // Includes the rules tool surface plus the Node-only conformance query.
-  // No browser is needed.
-  return [
-    ...createFirestoreRulesTools({ scope } as never),
-    ...createConformanceTools(),
-  ];
+  return toolFamilies('in-process').flatMap((family) =>
+    IN_PROCESS_HANDLER_FACTORIES[family.key](scope),
+  );
 }