pyric-tools 0.1.0-alpha.7

package/dist/registry/compose.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Composes the prod/admin tool registry from the per-domain factories
+ * (deploy / rules / firestore data + discover / rtdb). Returns a registry
+ * callers iterate and dispatch against: the bridge's prod mode
+ * (`startServer({ prodTools })`), the project-audit skill, and
+ * firestore-path discovery against a real project.
+ *
+ * Construct the `adminDeps` / `scope` / `rtdbHost` inputs from a service
+ * account via `adminDepsFromServiceAccount` (./admin-deps).
+ */
+import type { App as AdminApp } from 'firebase-admin/app';
+import type { Firestore as WebFirestore } from 'firebase/firestore';
+import { type ToolRegistry } from '@inbrowser/agent';
+import { type ProjectScope } from '../deploy/index.js';
+import { type UserAuth } from 'pyric/firestore';
+import { type RtdbHost } from 'pyric/rules/rtdb';
+/**
+ * Admin SDK deps for the Firestore admin-mode + user-mode dispatch factories.
+ */
+export interface AdminAppDeps {
+    /** firebase-admin App instance. Used directly for admin-mode
+     *  Firestore access (`getAdminFirestore(adminApp)`). */
+    adminApp: AdminApp;
+    /**
+     * Resolves to a rules-enforcing client Firestore for the given user.
+     * When omitted, data tool calls that supply `auth` fail with a clear
+     * UNSUPPORTED error — admin-mode dispatch (no auth) keeps working
+     * unchanged. Suppliers typically construct this via
+     * `FirebaseServerApp` + `getFirestore` from the Web SDK (see
+     * `adminDepsFromServiceAccount` in ./admin-deps).
+     */
+    getClientFirestore?: (auth: UserAuth) => Promise<WebFirestore>;
+}
+export type Profile = 'full' | 'browser-parity' | 'control-plane-only';
+export interface ComposeOptions {
+    profile?: Profile;
+    scope?: ProjectScope;
+    /**
+     * Admin SDK deps for Firestore admin-mode + user-mode dispatch.
+     * When supplied, `composeMcpRegistry` wires the Firestore data /
+     * discover / extract factories. Without it, only the scope-based
+     * control-plane + rules tooling is registered (`browser-parity`
+     * profile flow).
+     */
+    adminDeps?: AdminAppDeps;
+    /**
+     * RTDB host — when supplied, RTDB admin tools register. Construct
+     * via `initializeDatabaseApp(...)` from `@pyric/rtdb`. Passed
+     * separately from `adminDeps` so RTDB and Firestore admin surfaces
+     * opt in independently. Skipped in `browser-parity` profile.
+     */
+    rtdbHost?: RtdbHost;
+}
+/**
+ * Compose the MCP server's tool registry from the per-domain
+ * factories. Returns a registry the MCP server iterates +
+ * dispatches against.
+ *
+ * Profile gates the tool surface:
+ *   - `full` (default): control-plane + rules tooling.
+ *   - `browser-parity`: skips Node-only Admin SDK tools so a human
+ *     running the MCP server locally previews what the browser
+ *     playground sees.
+ *   - `control-plane-only`: just the deploy primitives — useful
+ *     for sandboxed Deployment Agent runs.
+ */
+export declare function composeMcpRegistry(opts?: ComposeOptions): Promise<ToolRegistry>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/registry/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/registry/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAS3E,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;4DACwD;IACxD,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAChE;AA+BD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,YAAY,CAAC,CAmDvB"}

package/dist/registry/compose.js

@@ -0,0 +1,113 @@
+/**
+ * Composes the prod/admin tool registry from the per-domain factories
+ * (deploy / rules / firestore data + discover / rtdb). Returns a registry
+ * callers iterate and dispatch against: the bridge's prod mode
+ * (`startServer({ prodTools })`), the project-audit skill, and
+ * firestore-path discovery against a real project.
+ *
+ * Construct the `adminDeps` / `scope` / `rtdbHost` inputs from a service
+ * account via `adminDepsFromServiceAccount` (./admin-deps).
+ */
+import { getFirestore as getAdminFirestore } from 'firebase-admin/firestore';
+import { createToolRegistry } from '@inbrowser/agent';
+import { fromServiceAccount } from '../deploy/index.js';
+import { createFirestoreDeployTools, createRtdbDeployTools, createHostingDeployTools, createFunctionsDeployTools, } from '../deploy/index.js';
+import { createFirestoreRulesTools } from 'pyric/rules/node';
+import { createFirestoreExtractTool } from 'pyric/rules/extract';
+import { createFirestoreDataTools, } from 'pyric/firestore';
+import { createFirestoreDiscoverTools } from '../discover/index.js';
+import { createAuthAdminTools } from '../auth/index.js';
+import { createVerifyTools } from '../verify/index.js';
+import { createRtdbDataTools } from 'pyric/database';
+import { createRtdbRulesTools } from 'pyric/rules/rtdb';
+function createFirestoreAdminDataTools(deps) {
+    // The admin SDK's Firestore has a structurally-compatible subset of
+    // the Web SDK's modular surface that `createFirestoreDataTools` uses
+    // (doc/collection/getDoc/setDoc/etc.). The cast collapses the nominal
+    // mismatch; runtime behavior is identical.
+    const adminFs = getAdminFirestore(deps.adminApp);
+    return createFirestoreDataTools({
+        resolveDb: async (actor) => {
+            // 'admin' (or omitted) → admin SDK (rules bypassed). A specific user
+            // requires a wired client-Firestore factory for rules-enforcing dispatch.
+            if (!actor || actor === 'admin')
+                return adminFs;
+            if (!deps.getClientFirestore) {
+                throw new Error('firestore data tool: user-mode (as:{uid}) requires AdminAppDeps.getClientFirestore. ' +
+                    'Supply it to enable rules-enforcing dispatch.');
+            }
+            const userFs = await deps.getClientFirestore(actor);
+            return userFs;
+        },
+    });
+}
+function createFirestoreAdminDiscoverTools(deps) {
+    return createFirestoreDiscoverTools({
+        resolveDb: () => getAdminFirestore(deps.adminApp),
+    });
+}
+/**
+ * Compose the MCP server's tool registry from the per-domain
+ * factories. Returns a registry the MCP server iterates +
+ * dispatches against.
+ *
+ * Profile gates the tool surface:
+ *   - `full` (default): control-plane + rules tooling.
+ *   - `browser-parity`: skips Node-only Admin SDK tools so a human
+ *     running the MCP server locally previews what the browser
+ *     playground sees.
+ *   - `control-plane-only`: just the deploy primitives — useful
+ *     for sandboxed Deployment Agent runs.
+ */
+export async function composeMcpRegistry(opts = {}) {
+    const profile = opts.profile ?? 'full';
+    const scope = opts.scope ??
+        (await fromServiceAccount(process.env.FIREBASE_SA_BASE64 ?? ''));
+    const registry = createToolRegistry();
+    // Pre-mortem M12 — typed ToolHandler[][] instead of unknown[][].
+    // Surfaces shape drift at the call site if a factory's return
+    // type ever stops being ToolHandler-compatible.
+    const factories = [
+        // Control plane — every profile.
+        createFirestoreDeployTools({ scope }),
+        ...(opts.rtdbHost && profile !== 'browser-parity' ? [] : [createRtdbDeployTools({ scope })]),
+        createHostingDeployTools({ scope }),
+        createFunctionsDeployTools({ scope }),
+        // Rules tooling — full + browser-parity.
+        ...(profile !== 'control-plane-only'
+            ? [createFirestoreRulesTools({ scope })]
+            : []),
+        // Auth configuration (Identity Toolkit) — full + browser-parity.
+        ...(profile !== 'control-plane-only'
+            ? [createAuthAdminTools({ scope })]
+            : []),
+        ...(profile !== 'control-plane-only'
+            ? [createVerifyTools({ scope })]
+            : []),
+        // Admin SDK + RTDB tools — only when `adminDeps` is supplied and
+        // we're not in a profile that explicitly excludes Node-only paths.
+        // `extract` is pure static analysis so it lands regardless of
+        // `adminDeps` when not in `browser-parity` (it reads from disk).
+        ...(profile !== 'control-plane-only' && profile !== 'browser-parity'
+            ? [[createFirestoreExtractTool()]]
+            : []),
+        ...(opts.adminDeps && profile !== 'browser-parity'
+            ? [
+                createFirestoreAdminDataTools(opts.adminDeps),
+                createFirestoreAdminDiscoverTools(opts.adminDeps),
+            ]
+            : []),
+        ...(opts.rtdbHost && profile !== 'browser-parity'
+            ? [
+                createRtdbRulesTools({ host: opts.rtdbHost }),
+                createRtdbDataTools({ host: opts.rtdbHost }),
+            ]
+            : []),
+    ];
+    for (const handlers of factories) {
+        for (const h of handlers)
+            registry.register(h);
+    }
+    return registry;
+}
+//# sourceMappingURL=compose.js.map

package/dist/registry/compose.js.map

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

package/dist/registry/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Prod/admin tool-registry composition for pyric-tools. Composes the
+ * per-domain factories (deploy / rules / firestore / discover / rtdb) into a
+ * registry, and bootstraps the admin inputs from a service account.
+ *
+ * Consumers: the bridge's prod mode (`startServer({ prodTools })`), the
+ * project-audit skill, and firestore-path discovery against a real project.
+ */
+export { composeMcpRegistry, type AdminAppDeps, type ComposeOptions, type Profile, } from './compose.js';
+export { adminDepsFromServiceAccount, type AdminDepsResult } from './admin-deps.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,OAAO,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,2BAA2B,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/registry/index.js

@@ -0,0 +1,11 @@
+/**
+ * Prod/admin tool-registry composition for pyric-tools. Composes the
+ * per-domain factories (deploy / rules / firestore / discover / rtdb) into a
+ * registry, and bootstraps the admin inputs from a service account.
+ *
+ * Consumers: the bridge's prod mode (`startServer({ prodTools })`), the
+ * project-audit skill, and firestore-path discovery against a real project.
+ */
+export { composeMcpRegistry, } from './compose.js';
+export { adminDepsFromServiceAccount } from './admin-deps.js';
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,GAInB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,2BAA2B,EAAwB,MAAM,iBAAiB,CAAC"}

package/dist/remote/index.d.ts

@@ -0,0 +1,232 @@
+import type { AuthUserRecord, CreateUserRequest, UpdateUserRequest } from 'pyric/auth';
+import type { FullMetadata } from 'pyric/storage';
+import { type RemoteSandbox as RemoteSandboxBase } from 'pyric/sandbox';
+import type { BridgeMessage, WorkerOpPayload, WorkerSubPayload } from '../bridge/protocol.js';
+export interface ConnectRemoteSandboxOptions {
+    /** Project root for `.pyric/serve.json` discovery. Default: `process.cwd()`. */
+    cwd?: string;
+    /** Explicit serve base URL (e.g. `http://127.0.0.1:5000`) — skips discovery. */
+    url?: string;
+    /** Per-op timeout in ms on the Node side (default 35s, above the bridge's 30s). */
+    opTimeoutMs?: number;
+}
+/**
+ * The raw relay channel: any worker-protocol op or snap-delivering
+ * subscription, verbatim. The typed conveniences below are built on this;
+ * checkpoint 2's `pyric-admin` remote-dispatch arm consumes it directly.
+ */
+export interface RemoteSandboxChannel {
+    /** Dispatch one worker op. Resolves with the worker's `res.value`;
+     *  rejects with an Error carrying `.code`. NOTE: callers choose their own
+     *  `actAs` lens — nothing is pinned here. */
+    op(op: WorkerOpPayload): Promise<unknown>;
+    /**
+     * Register a worker subscription. `onSnap` receives each snap value;
+     * an establishment failure (the worker host's `{ __error }` snap) routes
+     * to `onError` instead. Returns the unsubscribe function.
+     */
+    subscribe(sub: WorkerSubPayload, onSnap: (value: unknown) => void, onError?: (err: Error & {
+        code: string;
+    }) => void): () => void;
+}
+/** Wire shape of an RTDB snapshot as the worker host serializes it. */
+export interface RemoteRtdbSnapshot {
+    key: string | null;
+    exists: boolean;
+    value: unknown;
+    size: number;
+}
+/**
+ * Thin RTDB conveniences over the channel. Every call pins
+ * `actAs: { mode: 'admin' }` — firebase-admin's rules-bypass semantics,
+ * matching what `pyric-admin`'s database backend needs. Use the raw
+ * `channel` for lensed (rules-evaluated) access.
+ */
+export interface RemoteRtdb {
+    /** Read the value at `path` (null when absent). */
+    get(path: string): Promise<unknown>;
+    set(path: string, value: unknown): Promise<void>;
+    update(path: string, values: Record<string, unknown>): Promise<void>;
+    remove(path: string): Promise<void>;
+    /** Push `value` under a CLIENT-minted 20-char push id (the worker-protocol
+     *  contract: `rtdb.push` carries the key, so `.key` is known synchronously
+     *  on the pyric-admin side). Resolves with the minted key + full path. */
+    push(path: string, value?: unknown): Promise<{
+        key: string;
+        path: string;
+    }>;
+    /** Subscribe to the value at `path` (initial snapshot + every change). */
+    onValue(path: string, callback: (snapshot: RemoteRtdbSnapshot) => void, onError?: (err: Error & {
+        code: string;
+    }) => void): () => void;
+}
+/**
+ * Thin Storage conveniences over the channel — the byte-carrying base64 ops
+ * plus browse/metadata. Every call pins `actAs: { mode: 'admin' }`
+ * (firebase-admin's rules-bypass semantics, matching {@link RemoteRtdb});
+ * use the raw `channel` for lensed (rules-evaluated) access. Bytes are
+ * capped at 8 MiB raw ({@link MAX_STORAGE_OP_BYTES}) on both ends —
+ * streaming transfers are not supported on the sandbox backend.
+ */
+export interface RemoteStorage {
+    /** Upload `data` at `path` (replaces any existing object). Resolves with
+     *  the stored object's `FullMetadata`. */
+    putBytes(path: string, data: Uint8Array, options?: {
+        contentType?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<FullMetadata>;
+    /** Download the object's bytes. Rejects `storage/object-not-found` when
+     *  absent, `payload-too-large` when over the op cap. */
+    getBytes(path: string): Promise<Buffer>;
+    /** Delete the object at `path`. Idempotent (missing = no-op). */
+    deleteObject(path: string): Promise<void>;
+    /** Read the object's `FullMetadata`. */
+    getMetadata(path: string): Promise<FullMetadata>;
+    /** Does an object exist at `path`? (`getMetadata` with not-found → false.) */
+    exists(path: string): Promise<boolean>;
+    /** Enumerate immediate child items + prefixes under `path`. */
+    listAll(path: string): Promise<{
+        items: Array<{
+            fullPath: string;
+            name: string;
+        }>;
+        prefixes: Array<{
+            fullPath: string;
+            name: string;
+        }>;
+    }>;
+}
+/** Admin auth user-CRUD passthrough (never lensed — auth ops operate the
+ *  worker's user pool directly, mirroring `pyric/auth`'s sandbox ops). */
+export interface RemoteAuthAdmin {
+    listUsers(): Promise<AuthUserRecord[]>;
+    createUser(request: CreateUserRequest): Promise<AuthUserRecord>;
+    updateUser(uid: string, request: UpdateUserRequest): Promise<AuthUserRecord>;
+    deleteUser(uid: string): Promise<void>;
+    clearUsers(): Promise<void>;
+}
+/**
+ * The Node-side remote sandbox handle. Extends `pyric/sandbox`'s branded
+ * {@link RemoteSandboxBase} — structurally a full `Sandbox`, so it can be
+ * passed to `pyric-admin/app`'s `initializeApp({ sandbox })`, whose RTDB and
+ * Auth backends dispatch on the brand and route through {@link channel}.
+ *
+ * Sandbox members that are genuinely sync-only (`admin`, `snapshot()`,
+ * `history()`, `onEvent`, `currentUser`, …) cannot be mirrored over the
+ * wire in slice 1 and throw a remediating `unimplemented` error naming
+ * what to do instead. Implemented members: `withAuth` (pure local pair
+ * construction) and `dispose` (aliases {@link close}).
+ */
+export interface RemoteSandbox extends RemoteSandboxBase {
+    /** The raw worker op/sub relay channel (narrowed to the wire payload types). */
+    readonly channel: RemoteSandboxChannel;
+    /** RTDB conveniences (admin lens pinned). */
+    readonly rtdb: RemoteRtdb;
+    /** Storage conveniences (admin lens pinned; 8 MiB per-op byte cap). */
+    readonly storage: RemoteStorage;
+    /** Admin auth user CRUD. */
+    readonly auth: RemoteAuthAdmin;
+    /** Close the connection. In-flight ops reject; subscriptions stop. */
+    close(): void;
+}
+/** Minimal transport the core writes to. `connectRemoteSandbox` adapts a
+ *  `ws` socket; tests inject an in-process pipe to a `ConsumerSession`. */
+export interface RemoteTransport {
+    send(msg: BridgeMessage): void;
+    /**
+     * OPTIONAL event-loop hold hooks (exit-hang fix). The WS adapter unrefs
+     * its socket once connected so an IDLE remote client never pins the Node
+     * event loop (a finished script exits); the core calls `ref()` when work
+     * becomes outstanding (first pending op / live subscription) and
+     * `unref()` when the last one settles, so in-flight delivery keeps the
+     * process alive. Pure in-process transports (tests) may omit both.
+     */
+    ref?(): void;
+    unref?(): void;
+}
+export interface RemoteSandboxCore {
+    /** Feed one parsed message from the transport into the core. */
+    handleMessage(msg: BridgeMessage): void;
+    /** Send the attach handshake. `ready` settles on the ack. */
+    start(): void;
+    /** Resolves on `attach-ack`; rejects when no browser tab is connected. */
+    ready: Promise<void>;
+    channel: RemoteSandboxChannel;
+    /** Fail everything in flight (transport closed). Idempotent. */
+    dispose(reason?: string): void;
+}
+/**
+ * Transport-agnostic client core: correlation ids/subIds are minted HERE
+ * (this leg's id space; the bridge re-mints for the peer leg), pending ops
+ * carry a Node-side timeout above the bridge's 30s, and `{ __error }` snap
+ * values are routed to the subscription's error handler.
+ */
+export declare function createRemoteSandboxCore(transport: RemoteTransport, opts: {
+    serveUrl: string;
+    opTimeoutMs?: number;
+}): RemoteSandboxCore;
+export declare function buildRemoteRtdb(channel: RemoteSandboxChannel): RemoteRtdb;
+export declare function buildRemoteStorage(channel: RemoteSandboxChannel): RemoteStorage;
+export declare function buildRemoteAuthAdmin(channel: RemoteSandboxChannel): RemoteAuthAdmin;
+/**
+ * Build the branded remote sandbox handle over an established channel.
+ *
+ * Split out of {@link connectRemoteSandbox} so the in-process test harness
+ * (fake ports + `createConsumerSession`, no WS) constructs the EXACT handle
+ * production hands to `pyric-admin`.
+ *
+ * The handle satisfies `Sandbox` structurally:
+ *   - `withAuth` / `dispose` are real (pure local construction / teardown).
+ *   - Everything whose contract is sync-only or worker-owned (`admin`,
+ *     `snapshot`, `loadSnapshot`, `history`, `onEvent`, `reset`,
+ *     `currentUser`, `onCurrentUserChanged`, tab sync, persistence) throws
+ *     a remediating `unimplemented` error. Notably `onEvent`: the unified
+ *     event stream (`target: 'events'`) is not relayable until slice 2's
+ *     bounded backpressure lands, and no remote dispatch arm may depend on
+ *     it — a throw (not a silent no-op) keeps a subscriber from believing
+ *     it is observing events that will never arrive.
+ */
+export declare function createRemoteSandboxHandle(opts: {
+    channel: RemoteSandboxChannel;
+    serveUrl: string;
+    close: () => void;
+}): RemoteSandbox;
+/**
+ * Discover the running `pyric dev --bridge`, attach to its bridge WS as a
+ * worker-relay CONSUMER (never a peer — attaching cannot kick the browser
+ * tab out of last-connection-wins), and return the typed remote handle.
+ *
+ * Fails fast when no serve is discoverable or no browser tab is connected —
+ * there is deliberately no headless fallback (see module doc).
+ */
+export declare function connectRemoteSandbox(options?: ConnectRemoteSandboxOptions): Promise<RemoteSandbox>;
+/**
+ * {@link remoteSandbox}'s return type: the branded handle plus `ready` for
+ * eager checkers. `ready` kicks off the connection when first accessed and
+ * settles with the same fail-fast errors {@link connectRemoteSandbox} throws
+ * (no serve discovered / no browser tab connected).
+ */
+export interface LazyRemoteSandbox extends RemoteSandbox {
+    readonly ready: Promise<void>;
+}
+/**
+ * Synchronous construction, lazy connection — the ambient-init seam.
+ *
+ * `pyric-tools/register` installs this behind the
+ * `Symbol.for('pyric.remote.sandboxFactory')` global so `pyric-admin`'s bare
+ * `initializeApp()` can mint a full branded handle without awaiting anything.
+ * The wire connection (discovery → WS attach) happens on the FIRST op (or
+ * `ready` access), so the existing fail-fast — "no browser tab is connected —
+ * open <url>" — surfaces on first use instead of at construction. A failed
+ * connect is NOT latched: the next op retries, matching the error's own
+ * "…and retry" guidance. `connectRemoteSandbox` (eager) is unchanged.
+ */
+export declare function remoteSandbox(options?: ConnectRemoteSandboxOptions): LazyRemoteSandbox;
+/**
+ * The lazy wrapper with the connect function injected — the test seam
+ * (tests inject a fake connect; production injects `connectRemoteSandbox`).
+ */
+export declare function createLazyRemoteSandbox(connect: () => Promise<RemoteSandbox>, options?: {
+    url?: string;
+}): LazyRemoteSandbox;
+//# sourceMappingURL=index.d.ts.map

package/dist/remote/index.d.ts.map

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