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

package/src/bridge/server/peer.ts

@@ -0,0 +1,232 @@
+/**
+ * Bridge transport helpers shared by the bridge mounts.
+ *
+ * `attachPeer` adapts a `ws` WebSocket into either a registered sandbox PEER
+ * (the browser-side `connectBridge` is the other end — first message
+ * `hello`) or a worker-relay CONSUMER (the Node-side `connectRemoteSandbox`
+ * — first message `attach`); `collectBody` buffers a Node request body into
+ * parsed JSON for the stateless MCP transport.
+ *
+ * Both are consumed by `serve/bridge-mount.ts` (the `pyric dev --bridge` and
+ * `pyric({ bridge })` mount) and `serve/namespace.ts` (capture route).
+ * They live here — not inline in a plugin file — so retiring the standalone
+ * bridge Vite plugin doesn't drag its consumers with it.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { WebSocket } from 'ws';
+import { createBridge, type Bridge } from './bridge.js';
+import {
+  isBridgeMessage,
+  PEER_REPLACED_CLOSE_CODE,
+  PEER_REPLACED_CLOSE_REASON,
+  type BridgeMessage,
+} from '../protocol.js';
+import { cliVersion } from '../../pkg-version.js';
+
+export function attachPeer(
+  bridge: ReturnType<typeof createBridge>,
+  ws: WebSocket,
+): void {
+  let disconnect: (() => void) | null = null;
+  /** Peer generation captured at registration — tags every inbound frame so
+   *  a replaced tab's socket can't resolve the NEW peer's calls or deliver
+   *  stale subscription snaps (see Bridge.peerGeneration). */
+  let peerGen = 0;
+  let helloed = false;
+  let consumer: ConsumerSession | null = null;
+
+  ws.on('message', (raw) => {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (!isBridgeMessage(msg)) return;
+    if (msg.type === 'attach') {
+      // Worker-relay consumer (Node client). NOT a peer: attaching never
+      // kicks the browser tab out of last-connection-wins.
+      if (helloed || consumer) return;
+      consumer = createConsumerSession(bridge, (out: BridgeMessage) => {
+        try {
+          ws.send(JSON.stringify(out));
+        } catch {}
+      });
+      consumer.handleMessage(msg); // acks with attach-ack
+      return;
+    }
+    if (consumer) {
+      consumer.handleMessage(msg);
+      return;
+    }
+    if (msg.type === 'hello') {
+      if (helloed) return;
+      helloed = true;
+      disconnect = bridge.registerSandboxPeer(
+        (out: BridgeMessage) => {
+          try {
+            ws.send(JSON.stringify(out));
+          } catch {}
+        },
+        // Harden against a malformed hello: these fields come off the wire
+        // and feed `new Set(...)` in the bridge core — a non-array value
+        // (e.g. `capabilities: 42`) would throw inside this message
+        // listener, escape uncaught, and crash the serve process.
+        Array.isArray(msg.tools) ? msg.tools : [],
+        msg.sandboxId,
+        Array.isArray(msg.capabilities) ? msg.capabilities : [],
+        // On replacement, close THIS socket: the browser side's onclose
+        // handler tears down its relayed worker subscriptions, so a
+        // replaced tab's SharedWorker listeners don't keep streaming
+        // snaps the bridge drops as stale-generation until the tab closes.
+        // The REPLACED close code tells that client to go STANDBY (health-
+        // poll for a vacant slot) instead of re-helloing — an immediate
+        // re-hello would kick the new peer right back, and two open tabs
+        // would fight over the slot forever.
+        () => {
+          try {
+            ws.close(PEER_REPLACED_CLOSE_CODE, PEER_REPLACED_CLOSE_REASON);
+          } catch {}
+        },
+      );
+      peerGen = bridge.peerGeneration();
+      try {
+        ws.send(
+          JSON.stringify({
+            type: 'hello-ack',
+            protocol: 1,
+            bridgeVersion: bridge.version,
+          }),
+        );
+      } catch {
+        // Socket died between hello and ack — the close handler unwinds.
+      }
+      return;
+    }
+    if (!helloed) return;
+    bridge.handleSandboxMessage(msg, peerGen);
+  });
+
+  ws.on('close', () => {
+    if (disconnect) disconnect();
+    disconnect = null;
+    if (consumer) consumer.dispose();
+    consumer = null;
+  });
+  ws.on('error', () => {});
+}
+
+// ── Worker-relay consumer session (transport-agnostic) ───────────────────
+
+/**
+ * One attached worker-relay consumer (the Node `connectRemoteSandbox`
+ * client). Transport-agnostic — `attachPeer` adapts it onto a `ws` socket;
+ * tests drive `handleMessage` directly.
+ */
+export interface ConsumerSession {
+  /** Handle one parsed message from the consumer. */
+  handleMessage(msg: BridgeMessage): void;
+  /** Tear down every subscription this consumer registered. */
+  dispose(): void;
+}
+
+/**
+ * Create a consumer session over `send`. Correlation ids/subIds on this leg
+ * are CONSUMER-minted and echoed verbatim; the bridge core mints its own ids
+ * for the peer leg (`dispatchWorkerOp` / `subscribeWorker`), so the two legs'
+ * id spaces never mix.
+ */
+export function createConsumerSession(
+  bridge: Bridge,
+  send: (msg: BridgeMessage) => void,
+): ConsumerSession {
+  /** consumer subId → bridge-side unsubscribe. */
+  const subs = new Map<string, () => void>();
+
+  return {
+    handleMessage(msg: BridgeMessage): void {
+      switch (msg.type) {
+        case 'attach': {
+          // Idempotent re-attach: just re-ack. `serveVersion` is the
+          // version-skew stamp (bridge/protocol.ts) — this process's own
+          // @pyric/cli version, compared client-side at attach.
+          send({
+            type: 'attach-ack',
+            protocol: 1,
+            bridgeVersion: bridge.version,
+            peerConnected: bridge.isSandboxConnected(),
+            serveVersion: cliVersion(),
+          });
+          return;
+        }
+        case 'worker-op': {
+          bridge.dispatchWorkerOp(msg.op).then(
+            (value) => send({ type: 'worker-res', id: msg.id, ok: true, value }),
+            (err: Error & { code?: string; denialContext?: unknown }) =>
+              send({
+                type: 'worker-res',
+                id: msg.id,
+                ok: false,
+                error: {
+                  code: err.code ?? 'unknown',
+                  message: err.message,
+                  // Structured denial context (spike gap 6) — plain JSON,
+                  // relayed verbatim so the Node side re-attaches it.
+                  ...(err.denialContext !== undefined ? { denialContext: err.denialContext } : {}),
+                },
+              }),
+          );
+          return;
+        }
+        case 'worker-sub': {
+          if (subs.has(msg.subId)) return; // idempotent
+          const unsubscribe = bridge.subscribeWorker(msg.sub, (value) =>
+            send({ type: 'worker-snap', subId: msg.subId, value }),
+          );
+          subs.set(msg.subId, unsubscribe);
+          return;
+        }
+        case 'worker-unsub': {
+          const unsubscribe = subs.get(msg.subId);
+          if (!unsubscribe) return;
+          subs.delete(msg.subId);
+          unsubscribe();
+          return;
+        }
+        case 'ping': {
+          send({ type: 'pong', id: msg.id });
+          return;
+        }
+        default:
+          return; // peer-only or unknown frames — ignore
+      }
+    },
+    dispose(): void {
+      for (const unsubscribe of subs.values()) unsubscribe();
+      subs.clear();
+    },
+  };
+}
+
+export async function collectBody(req: IncomingMessage): Promise<unknown> {
+  if (req.method === 'GET' || req.method === 'DELETE') return undefined;
+  return await new Promise<unknown>((resolve, reject) => {
+    let raw = '';
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => {
+      raw += chunk;
+    });
+    req.on('end', () => {
+      if (!raw) {
+        resolve(undefined);
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on('error', reject);
+  });
+}

package/src/bridge/server/standalone.ts

@@ -0,0 +1,347 @@
+/**
+ * Standalone bridge server. Spins up an HTTP server on a known
+ * loopback port that handles three routes:
+ *
+ *   GET  /health           — diagnostic
+ *   POST /mcp              — MCP-over-HTTP (StreamableHTTPServerTransport)
+ *   GET  /sandbox (Upgrade) — WebSocket the browser tab connects to
+ *
+ * Bound to 127.0.0.1 only. Refuses to start if the port is occupied.
+ *
+ * Premortem fixes baked in:
+ *  - #A2 — per-session idle timeout (10 min default) + max-session cap.
+ *  - #U1 — peer connect/disconnect logged; per-call logging behind
+ *    PYRIC_VERBOSE=1.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer, WebSocket } from 'ws';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createBridge, type Bridge, type BridgeToolEvent } from './bridge.js';
+import { buildMcpServer } from './mcp.js';
+import { getDefaultMcpToolSurface } from './mcp-contract.js';
+import { createAuditWriter, type AuditWriter } from './audit.js';
+import {
+  createConsoleLogger,
+  createSilentLogger,
+  type BridgeLogger,
+} from './logger.js';
+import {
+  DEFAULT_BRIDGE_PORT,
+  DEFAULT_HEALTH_PATH,
+  DEFAULT_MCP_PATH,
+  DEFAULT_SANDBOX_PATH,
+  type BridgeMessage,
+  isBridgeMessage,
+} from '../protocol.js';
+import { pyricVersion } from '../../serve/standalone-assets.js';
+import { isAllowedUpgrade } from '../../serve/server.js';
+
+const BRIDGE_VERSION = pyricVersion();
+const DEFAULT_SESSION_IDLE_MS = 10 * 60 * 1000; // 10 minutes
+const DEFAULT_MAX_SESSIONS = 50;
+
+export interface StartServerOptions {
+  /** Port to bind. Default: 5174. Env: PYRIC_PORT. */
+  port?: number;
+  /** Sandbox label surfaced in health and audit metadata. */
+  project?: string;
+  /** Disable the audit log writer (useful in tests). */
+  disableAuditLog?: boolean;
+  /** Extra hostnames allowed past the WS-upgrade rebinding/origin guard
+   *  (besides the loopback set the bridge binds to). Mirrors serve's
+   *  `--allowed-host`. */
+  allowedHosts?: string[];
+  /** Override the audit writer (testing). */
+  auditWriter?: AuditWriter;
+  /** Premortem #A2 — kill idle sessions after this many ms. Default 10 min. */
+  sessionIdleMs?: number;
+  /** Premortem #A2 — refuse new sessions when this many are active. Default 50. */
+  maxSessions?: number;
+  /** Premortem #U1 — logger; defaults to stderr `[pyric]` prefix. */
+  logger?: BridgeLogger;
+  /** Convenience: install a silent logger (tests). */
+  silent?: boolean;
+
+}
+
+export interface ServerHandle {
+  readonly bridge: Bridge;
+  readonly port: number;
+  readonly url: string;
+  readonly auditLogPath: string | null;
+  stop(): Promise<void>;
+}
+
+export async function startServer(
+  opts: StartServerOptions = {},
+): Promise<ServerHandle> {
+  // `??` doesn't short-circuit on NaN; Number(undefined) is NaN, which
+  // would silently slip through to the http server and produce
+  // "options.port should be >= 0 and < 65536. Received NaN."
+  // Resolve the env var separately so the default actually wins.
+  const envPort = process.env.PYRIC_PORT ? Number(process.env.PYRIC_PORT) : undefined;
+  const port = opts.port ?? (Number.isFinite(envPort) ? envPort : undefined) ?? DEFAULT_BRIDGE_PORT;
+  const project = opts.project ?? process.env.PYRIC_PROJECT ?? 'sandbox';
+  const logger =
+    opts.logger ?? (opts.silent ? createSilentLogger() : createConsoleLogger());
+  const sessionIdleMs = opts.sessionIdleMs ?? DEFAULT_SESSION_IDLE_MS;
+  const maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+
+  // Set up audit log writer (best-effort).
+  const auditWriter = opts.disableAuditLog
+    ? null
+    : opts.auditWriter ?? createAuditWriter(project);
+
+  const bridge = createBridge({
+    project,
+    version: BRIDGE_VERSION,
+    onToolEvent: (event: BridgeToolEvent) => {
+      auditWriter?.write(event);
+      logger.verbose(
+        `tool ${event.tool} → ${event.result.ok ? 'ok' : 'fail'} (${event.durationMs}ms) [${event.mode}]`,
+      );
+    },
+  });
+
+  const { forwarded, inProcess } = getDefaultMcpToolSurface();
+
+  // Per-session transport+server map. Each MCP client connection
+  // gets its own pair; cleared on DELETE / idle / transport close.
+  type Session = {
+    transport: StreamableHTTPServerTransport;
+    close: () => Promise<void>;
+    /** Idle-timeout handle; reset on each request. */
+    idleTimer: ReturnType<typeof setTimeout> | null;
+    sessionId: string | null;
+  };
+  const sessions = new Map<string, Session>();
+  const pendingSessions = new Set<Session>();
+
+  function bumpIdle(session: Session): void {
+    if (session.idleTimer) clearTimeout(session.idleTimer);
+    session.idleTimer = setTimeout(() => {
+      if (session.sessionId) {
+        logger.verbose(`session ${session.sessionId.slice(0, 8)}… idle-closed`);
+        sessions.delete(session.sessionId);
+      }
+      pendingSessions.delete(session);
+      void session.close();
+    }, sessionIdleMs);
+  }
+
+  async function newSession(): Promise<Session> {
+    if (sessions.size >= maxSessions) {
+      const err = new Error(
+        `pyric bridge: refusing new session — at session cap (${maxSessions}). Existing sessions: ${sessions.size}.`,
+      );
+      (err as { statusCode?: number }).statusCode = 503;
+      throw err;
+    }
+    const session: Session = {
+      transport: null as unknown as StreamableHTTPServerTransport,
+      close: async () => {},
+      idleTimer: null,
+      sessionId: null,
+    };
+    session.transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (id) => {
+        session.sessionId = id;
+        sessions.set(id, session);
+        pendingSessions.delete(session);
+        bumpIdle(session);
+        logger.verbose(`session ${id.slice(0, 8)}… initialized`);
+      },
+    });
+    const server = buildMcpServer(bridge, { forwarded, inProcess });
+    session.close = async () => {
+      if (session.idleTimer) clearTimeout(session.idleTimer);
+      session.idleTimer = null;
+      await server.close().catch(() => {});
+      await session.transport.close().catch(() => {});
+    };
+    pendingSessions.add(session);
+    await server.connect(session.transport);
+    return session;
+  }
+
+  // ── HTTP server ─────────────────────────────────────────────────
+  const http = createServer(async (req, res) => {
+    const url = req.url ?? '/';
+    if (process.env.PYRIC_DEBUG) {
+      process.stderr.write(`[pyric debug] ${req.method} ${url}\n`);
+    }
+    if (url === DEFAULT_HEALTH_PATH && req.method === 'GET') {
+      const body = JSON.stringify(bridge.health());
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(body);
+      return;
+    }
+    if (url === DEFAULT_MCP_PATH && (req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE')) {
+      try {
+        const sessionId = (req.headers['mcp-session-id'] ?? req.headers['Mcp-Session-Id']) as string | undefined;
+        let session: Session | undefined;
+        if (sessionId && sessions.has(sessionId)) {
+          session = sessions.get(sessionId);
+          if (session) bumpIdle(session);
+        } else {
+          session = await newSession();
+        }
+        if (req.method === 'DELETE' && sessionId) {
+          if (session) await session.close();
+          sessions.delete(sessionId);
+          res.writeHead(204);
+          res.end();
+          return;
+        }
+        await session!.transport.handleRequest(
+          req as IncomingMessage,
+          res as ServerResponse,
+        );
+      } catch (err) {
+        const statusCode = (err as { statusCode?: number })?.statusCode ?? 500;
+        const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+        logger.error(`MCP transport error: ${msg}`);
+        if (!res.headersSent) {
+          res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
+      }
+      return;
+    }
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'not found', path: url }));
+  });
+
+  // ── WebSocket server (mounted on /sandbox) ──────────────────────
+  const wss = new WebSocketServer({ noServer: true });
+  http.on('upgrade', (req, socket, head) => {
+    if ((req.url ?? '') !== DEFAULT_SANDBOX_PATH) {
+      socket.destroy();
+      return;
+    }
+    // DNS-rebinding + cross-origin hijack guard (the request-time isAllowedHost
+    // runs on the `request` event only — `upgrade` bypasses it). The standalone
+    // bridge binds 127.0.0.1 only, so the allowlist is the loopback set.
+    if (!isAllowedUpgrade(req.headers, '127.0.0.1', opts.allowedHosts)) {
+      logger.error(
+        `refused WS upgrade — Host='${req.headers.host ?? ''}' Origin='${req.headers.origin ?? ''}' (rebinding/origin guard)`,
+      );
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      attachPeer(bridge, ws, logger);
+    });
+  });
+
+  // Bind to loopback only.
+  await new Promise<void>((resolve, reject) => {
+    http.once('error', reject);
+    http.listen(port, '127.0.0.1', () => {
+      http.removeListener('error', reject);
+      resolve();
+    });
+  });
+
+  const address = http.address();
+  const boundPort = typeof address === 'object' && address ? address.port : port;
+  const url = `http://127.0.0.1:${boundPort}`;
+
+  logger.info(`bridge ${BRIDGE_VERSION} listening on ${url} — sandbox: ${project}`);
+
+  return {
+    bridge,
+    port: boundPort,
+    url,
+    auditLogPath: auditWriter?.path ?? null,
+    async stop() {
+      // Stop accepting new WebSocket upgrades…
+      wss.close();
+      // …and forcibly terminate any existing WS clients. Without this,
+      // http.close() below waits for clients to disconnect on their own
+      // (MCP keep-alives sit forever — a Ctrl-C with any open peer
+      // would hang the CLI shutdown indefinitely).
+      for (const client of wss.clients) {
+        try { client.terminate(); } catch { /* already closed */ }
+      }
+      // Destroy any open HTTP keep-alive sockets. Node 18.2+.
+      http.closeAllConnections();
+      await new Promise<void>((resolve) => {
+        http.close(() => resolve());
+      });
+      for (const session of sessions.values()) {
+        await session.close().catch(() => {});
+      }
+      for (const session of pendingSessions) {
+        await session.close().catch(() => {});
+      }
+      sessions.clear();
+      pendingSessions.clear();
+      logger.info('bridge stopped');
+    },
+  };
+}
+
+function attachPeer(bridge: Bridge, ws: WebSocket, logger: BridgeLogger): void {
+  let disconnect: (() => void) | null = null;
+  let helloed = false;
+  let sandboxId: string | null = null;
+
+  ws.on('message', (raw) => {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return; // ignore malformed
+    }
+    if (!isBridgeMessage(msg)) return;
+
+    if (msg.type === 'hello') {
+      if (helloed) return; // ignore duplicate hellos
+      helloed = true;
+      sandboxId = msg.sandboxId;
+      logger.info(
+        `peer connected — sandboxId=${sandboxId.slice(0, 12)} tools=${msg.tools.length}`,
+      );
+      disconnect = bridge.registerSandboxPeer(
+        (out: BridgeMessage) => {
+          try {
+            ws.send(JSON.stringify(out));
+          } catch {
+            // socket likely closed; the close handler runs disconnect.
+          }
+        },
+        msg.tools,
+        msg.sandboxId,
+      );
+      ws.send(
+        JSON.stringify({
+          type: 'hello-ack',
+          protocol: 1,
+          bridgeVersion: bridge.version,
+        }),
+      );
+      return;
+    }
+
+    if (!helloed) return; // ignore messages before hello
+    bridge.handleSandboxMessage(msg);
+  });
+
+  ws.on('close', () => {
+    if (disconnect) {
+      disconnect();
+      logger.info(
+        `peer disconnected — sandboxId=${sandboxId ? sandboxId.slice(0, 12) : 'unknown'}`,
+      );
+    }
+    disconnect = null;
+  });
+
+  ws.on('error', () => {
+    // ws will follow up with a 'close' event; cleanup happens there.
+  });
+}

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

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+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';
+
+export interface ToolMetadata {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+function toMetadata(handler: ToolHandler): ToolMetadata {
+  return {
+    name: handler.name,
+    description: handler.description,
+    parameters: handler.parameters as Record<string, unknown>,
+  };
+}
+
+/**
+ * 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.
+ */
+export function getSandboxToolMetadata(): ToolMetadata[] {
+  // The resolver stub never runs: the bridge replaces execute() with
+  // its own forward-to-peer dispatch.
+  const stubResolver = async () => {
+    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);
+}
+
+/**
+ * Tooling factories that execute in-process on the bridge
+ * (no browser needed). Returned as live ToolHandlers — 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(),
+  ];
+}