pyric-tools 0.1.0-alpha.7

package/dist/remote/index.js

@@ -0,0 +1,719 @@
+/**
+ * `connectRemoteSandbox()` — Node-side client for the browser-hosted
+ * SharedWorker sandbox (remote sandbox, slice 1 / checkpoint 1).
+ *
+ * Server-side Node code (ultimately `pyric-admin`'s remote dispatch arm)
+ * reaches the ONE sandbox the app + Studio + agent share:
+ *
+ *   Node process ──ws──> `pyric dev --bridge` ──ws──> browser tab
+ *                 (attach/consumer leg)        (peer leg)
+ *                                        ──MessagePort──> SharedWorker
+ *
+ * DISCOVERY mirrors `pyric mcp-proxy` (`serve/discovery.ts`): the
+ * `.pyric/serve.json` pointer in cwd, health-probed across both loopback
+ * families with the pointer's `instanceId` pinned so a cross-family
+ * port-squatter can't split-brain the connection.
+ *
+ * FAIL-FAST, NEVER FALL BACK: when no browser tab is connected the connect
+ * (and every later op that races a closing tab) fails with a clear
+ * "open <serve url>" error. There is deliberately NO silent headless
+ * fallback — a silently split backend is exactly the failure this client
+ * exists to avoid.
+ *
+ * SUBSCRIPTION OWNERSHIP: the bridge process owns the durable sub registry
+ * and re-issues it to every newly registered peer (tab refresh/replacement),
+ * so a subscription made here survives peer churn — RTDB value semantics
+ * make the replay safe (each resubscribe re-delivers a fresh snapshot;
+ * consumers are last-value-wins).
+ *
+ * NODE-ONLY: uses `ws` and `node:fs` — exported via a `node`-conditional
+ * subpath (`pyric-tools/remote`), never bundled for the browser.
+ */
+import { WebSocket } from 'ws';
+import { REMOTE_SANDBOX, SandboxContextImpl, } from 'pyric/sandbox';
+import { isBridgeMessage, NO_SANDBOX_ERROR_MESSAGE } from '../bridge/protocol.js';
+import { pyricToolsVersion } from '../pkg-version.js';
+import { MAX_STORAGE_OP_BYTES, storagePayloadTooLarge } from '../serve/worker/protocol.js';
+import { discoverServe } from '../serve/discovery.js';
+/** Sits just above the bridge's own 30s `callTimeoutMs` so a legitimately
+ *  slow worker op still completes (same layering as `mcp-proxy`'s 35s). */
+const DEFAULT_OP_TIMEOUT_MS = 35_000;
+/** How long the attach handshake may take before connect() fails. */
+const ATTACH_TIMEOUT_MS = 5_000;
+function remoteError(code, message, denialContext) {
+    const err = new Error(message);
+    err.code = code;
+    // Structured denial context (spike gap 6): a relayed permission-denied
+    // carries the same "why did this deny" frame a local SandboxError has —
+    // plain JSON off the wire, re-attached here.
+    if (denialContext !== undefined)
+        err.denialContext = denialContext;
+    return err;
+}
+function noTabError(serveUrl) {
+    return remoteError('unavailable', `no browser tab is connected to the sandbox — open ${serveUrl} in a browser and retry.`);
+}
+/**
+ * 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 function createRemoteSandboxCore(transport, opts) {
+    const serveUrl = opts.serveUrl;
+    const opTimeoutMs = opts.opTimeoutMs ?? DEFAULT_OP_TIMEOUT_MS;
+    let opCounter = 0;
+    let subCounter = 0;
+    let disposed = null;
+    const pending = new Map();
+    const subs = new Map();
+    let readyResolve;
+    let readyReject;
+    const ready = new Promise((resolve, reject) => {
+        readyResolve = resolve;
+        readyReject = reject;
+    });
+    // `ready` may legitimately go unobserved after dispose — never unhandled.
+    ready.catch(() => { });
+    /**
+     * Version-skew guidance (integration-smoke fix). Set once when the
+     * `attach-ack`'s `serveVersion` stamp is present AND differs from this
+     * client's own pyric-tools version: an old worker can accept a newer op
+     * frame and die mid-handling, which surfaces as a bare timeout — so the
+     * mismatch warns ONCE on stderr at attach, and op-timeout errors append
+     * the same guidance. Old servers omit the stamp → stays null → silent.
+     */
+    let versionSkewGuidance = null;
+    function send(msg) {
+        transport.send(msg);
+    }
+    /**
+     * Event-loop hold accounting (exit-hang fix): ref the transport while ANY
+     * op or subscription is outstanding, unref when the last one settles.
+     * Transition-edged so the hooks fire once per busy/idle flip.
+     */
+    let holdingLoop = false;
+    function updateLoopHold() {
+        const busy = pending.size + subs.size > 0;
+        if (busy && !holdingLoop) {
+            holdingLoop = true;
+            transport.ref?.();
+        }
+        else if (!busy && holdingLoop) {
+            holdingLoop = false;
+            transport.unref?.();
+        }
+    }
+    function op(payload) {
+        if (disposed) {
+            return Promise.reject(remoteError('unavailable', disposed));
+        }
+        return new Promise((resolve, reject) => {
+            const id = `rop-${++opCounter}`;
+            const timer = setTimeout(() => {
+                if (pending.has(id)) {
+                    pending.delete(id);
+                    updateLoopHold();
+                    reject(remoteError('deadline-exceeded', `remote sandbox op timed out after ${opTimeoutMs}ms (op: ${payload.method}) — is pyric dev still running?` +
+                        // A version-skewed old worker accepts frames it cannot
+                        // handle and never responds — a timeout is its signature.
+                        (versionSkewGuidance ? ` ${versionSkewGuidance}` : '')));
+                }
+            }, opTimeoutMs);
+            pending.set(id, { resolve, reject, timer });
+            updateLoopHold();
+            try {
+                send({ type: 'worker-op', id, op: payload });
+            }
+            catch (err) {
+                clearTimeout(timer);
+                pending.delete(id);
+                updateLoopHold();
+                reject(remoteError('unavailable', `failed to send op to serve: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        });
+    }
+    function subscribe(sub, onSnap, onError) {
+        if (disposed)
+            throw remoteError('unavailable', disposed);
+        const subId = `rsub-${++subCounter}`;
+        subs.set(subId, { onSnap, onError });
+        updateLoopHold();
+        send({ type: 'worker-sub', subId, sub });
+        return () => {
+            if (!subs.delete(subId))
+                return;
+            updateLoopHold();
+            if (!disposed) {
+                try {
+                    send({ type: 'worker-unsub', subId });
+                }
+                catch { }
+            }
+        };
+    }
+    function handleMessage(msg) {
+        if (!isBridgeMessage(msg))
+            return;
+        switch (msg.type) {
+            case 'attach-ack': {
+                // Version-skew stamp: warn ONCE when the serve process runs a
+                // different pyric-tools version (absent stamp = old server = silent).
+                if (versionSkewGuidance === null &&
+                    typeof msg.serveVersion === 'string' &&
+                    msg.serveVersion !== pyricToolsVersion()) {
+                    versionSkewGuidance =
+                        `pyric dev is running version ${msg.serveVersion}, this client is ` +
+                            `${pyricToolsVersion()} — restart pyric dev and reload the browser tab.`;
+                    process.stderr.write(`pyric: ${versionSkewGuidance}\n`);
+                }
+                if (msg.peerConnected)
+                    readyResolve();
+                else
+                    readyReject(noTabError(serveUrl));
+                return;
+            }
+            case 'worker-res': {
+                const call = pending.get(msg.id);
+                if (!call)
+                    return; // late (already timed out) — drop
+                clearTimeout(call.timer);
+                pending.delete(msg.id);
+                updateLoopHold();
+                if (msg.ok) {
+                    call.resolve(msg.value);
+                }
+                else {
+                    const code = msg.error?.code ?? 'unknown';
+                    let message = msg.error?.message ?? 'unknown sandbox error';
+                    // Enrich the bridge's generic no-peer error with actionable guidance.
+                    if (message === NO_SANDBOX_ERROR_MESSAGE) {
+                        message = noTabError(serveUrl).message;
+                    }
+                    else if (/^Unknown method:/.test(message)) {
+                        // Version skew: a live tab whose SharedWorker predates this op.
+                        message +=
+                            ' — the running sandbox may predate this feature; restart pyric dev ' +
+                                'and reload the browser tab.';
+                    }
+                    call.reject(remoteError(code, message, msg.error?.denialContext));
+                }
+                return;
+            }
+            case 'worker-snap': {
+                const sub = subs.get(msg.subId);
+                if (!sub)
+                    return; // unsubscribed — drop
+                const value = (msg.value ?? {});
+                if (value.__error) {
+                    // A listener error is TERMINAL (Firestore's onSnapshot contract:
+                    // after onError, no further snapshots and the listener is dead).
+                    // Auto-unsubscribe BEFORE delivering: drop the local record (so a
+                    // consumer's own unsubscribe becomes an idempotent no-op and the
+                    // event-loop hold releases — an errored sub must not pin the
+                    // process forever) and tell the worker to tear down whatever
+                    // listener it may have registered (harmless no-op for a
+                    // registration failure that never registered one).
+                    subs.delete(msg.subId);
+                    updateLoopHold();
+                    if (!disposed) {
+                        try {
+                            send({ type: 'worker-unsub', subId: msg.subId });
+                        }
+                        catch { }
+                    }
+                    const payload = value.__error;
+                    const err = remoteError(payload.code, payload.message, payload.denialContext);
+                    if (sub.onError)
+                        sub.onError(err);
+                    else
+                        console.error('pyric remote sandbox: uncaught error in subscription:', err);
+                    return;
+                }
+                try {
+                    sub.onSnap(msg.value);
+                }
+                catch {
+                    // Consumer callback failures must not break the relay loop.
+                }
+                return;
+            }
+            case 'ping': {
+                send({ type: 'pong', id: msg.id });
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    function dispose(reason) {
+        if (disposed)
+            return;
+        disposed = reason ?? 'remote sandbox connection closed';
+        const err = remoteError('unavailable', disposed);
+        for (const call of pending.values()) {
+            clearTimeout(call.timer);
+            call.reject(err);
+        }
+        pending.clear();
+        subs.clear();
+        updateLoopHold();
+        readyReject(err); // no-op if already settled
+    }
+    return {
+        handleMessage,
+        start: () => send({ type: 'attach', protocol: 1 }),
+        ready,
+        channel: { op, subscribe },
+        dispose,
+    };
+}
+// ─── Typed conveniences over the raw channel ───────────────────────────────
+/** firebase-admin's rules-bypass lens, pinned on every RTDB convenience op. */
+const ADMIN_LENS = { mode: 'admin' };
+export function buildRemoteRtdb(channel) {
+    return {
+        async get(path) {
+            const snap = (await channel.op({
+                method: 'rtdb.get',
+                path,
+                actAs: ADMIN_LENS,
+            }));
+            return snap.value ?? null;
+        },
+        async set(path, value) {
+            await channel.op({ method: 'rtdb.set', path, value, actAs: ADMIN_LENS });
+        },
+        async update(path, values) {
+            await channel.op({ method: 'rtdb.update', path, values, actAs: ADMIN_LENS });
+        },
+        async remove(path) {
+            await channel.op({ method: 'rtdb.remove', path, actAs: ADMIN_LENS });
+        },
+        async push(path, value) {
+            const key = generatePushId();
+            const res = (await channel.op({
+                method: 'rtdb.push',
+                path,
+                key,
+                ...(value !== undefined ? { value } : {}),
+                actAs: ADMIN_LENS,
+            }));
+            return res;
+        },
+        onValue(path, callback, onError) {
+            return channel.subscribe({ target: { service: 'rtdb', path }, actAs: ADMIN_LENS }, (value) => callback(value), onError);
+        },
+    };
+}
+export function buildRemoteStorage(channel) {
+    return {
+        async putBytes(path, data, options) {
+            // Client-side cap: reject BEFORE encoding/sending so an oversized
+            // payload never hits the wire (the host enforces the same cap on
+            // decode — belt and braces across the relay).
+            if (data.byteLength > MAX_STORAGE_OP_BYTES) {
+                throw storagePayloadTooLarge(data.byteLength, `storage payload for '${path}'`);
+            }
+            return (await channel.op({
+                method: 'storage.putBytes',
+                path,
+                dataB64: Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('base64'),
+                ...(options?.contentType !== undefined ? { contentType: options.contentType } : {}),
+                ...(options?.metadata !== undefined ? { metadata: options.metadata } : {}),
+                actAs: ADMIN_LENS,
+            }));
+        },
+        async getBytes(path) {
+            const res = (await channel.op({
+                method: 'storage.getBytes',
+                path,
+                actAs: ADMIN_LENS,
+            }));
+            return Buffer.from(res.dataB64, 'base64');
+        },
+        async deleteObject(path) {
+            await channel.op({ method: 'storage.deleteObject', path, actAs: ADMIN_LENS });
+        },
+        async getMetadata(path) {
+            return (await channel.op({
+                method: 'storage.getMetadata',
+                path,
+                actAs: ADMIN_LENS,
+            }));
+        },
+        async exists(path) {
+            try {
+                await this.getMetadata(path);
+                return true;
+            }
+            catch (err) {
+                if (err.code === 'storage/object-not-found')
+                    return false;
+                throw err;
+            }
+        },
+        async listAll(path) {
+            return (await channel.op({
+                method: 'storage.listAll',
+                path,
+                actAs: ADMIN_LENS,
+            }));
+        },
+    };
+}
+export function buildRemoteAuthAdmin(channel) {
+    return {
+        async listUsers() {
+            return (await channel.op({ method: 'auth.listUsers' }));
+        },
+        async createUser(request) {
+            return (await channel.op({
+                method: 'auth.adminCreateUser',
+                request: request,
+            }));
+        },
+        async updateUser(uid, request) {
+            return (await channel.op({
+                method: 'auth.adminUpdateUser',
+                uid,
+                request: request,
+            }));
+        },
+        async deleteUser(uid) {
+            await channel.op({ method: 'auth.adminDeleteUser', uid });
+        },
+        async clearUsers() {
+            await channel.op({ method: 'auth.adminClearUsers' });
+        },
+    };
+}
+// ─── Handle construction ────────────────────────────────────────────────────
+/** A member of `Sandbox` that slice 1 cannot express over the wire throws
+ *  this branded, remediating error instead of silently misbehaving. */
+function notAvailableRemotely(member, remedy) {
+    return remoteError('unimplemented', `${member} is not available on a remote sandbox — ${remedy}`);
+}
+/**
+ * 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 function createRemoteSandboxHandle(opts) {
+    const { channel, serveUrl, close } = opts;
+    const throwMember = (member, remedy) => {
+        throw notAvailableRemotely(member, remedy);
+    };
+    const handle = {
+        [REMOTE_SANDBOX]: true,
+        serveUrl,
+        channel,
+        rtdb: buildRemoteRtdb(channel),
+        storage: buildRemoteStorage(channel),
+        auth: buildRemoteAuthAdmin(channel),
+        close,
+        // ── Implemented Sandbox members ─────────────────────────────────────
+        withAuth(auth) {
+            // Pure local pair construction — contexts carry identity, the data
+            // stays behind the channel.
+            return new SandboxContextImpl(handle, auth);
+        },
+        dispose() {
+            close();
+        },
+        // ── Sync-only / worker-owned members: remediating throws ───────────
+        onEvent: () => throwMember('onEvent', 'the unified event stream is not relayed over the bridge yet (slice 2); ' +
+            `observe activity in the browser tab at ${serveUrl} or in Pyric Studio instead`),
+        history: () => throwMember('history()', 'the event log lives in the browser worker; inspect it in Pyric Studio ' +
+            'or subscribe from the page that hosts the sandbox'),
+        get admin() {
+            return throwMember('admin', 'the sync Firestore admin plane cannot span the wire; dispatch async worker ops ' +
+                "through the handle's channel instead (e.g. channel.op({ method: 'admin.getDocument', path }))");
+        },
+        reset: () => throwMember('reset()', `reset the sandbox from the browser tab at ${serveUrl} or from Pyric Studio`),
+        snapshot: () => throwMember('snapshot()', "use the async worker op instead: channel.op({ method: 'getSnapshot' })"),
+        loadSnapshot: () => throwMember('loadSnapshot()', "use the async worker ops instead: channel.op({ method: 'importState', bundle })"),
+        get currentUser() {
+            return throwMember('currentUser', 'the browser tab owns the auth session; ' +
+                "read it asynchronously via channel.op({ method: 'auth.getCurrentUser' })");
+        },
+        onCurrentUserChanged: () => throwMember('onCurrentUserChanged', 'the browser tab owns the auth session; subscribe there instead'),
+        enableTabSync: () => throwMember('enableTabSync', 'tab sync is a browser concern; enable it in the page'),
+        enablePersistence: () => throwMember('enablePersistence', 'the browser worker owns persistence; it is already enabled by `pyric dev`'),
+        flush: () => throwMember('flush()', 'the browser worker owns persistence and flushes itself'),
+        clearPersistence: () => throwMember('clearPersistence()', 'clear the persisted state from the browser tab or Pyric Studio'),
+        registerPersistableService: () => throwMember('registerPersistableService', 'the browser worker owns persistence; services register there'),
+    };
+    return handle;
+}
+// ─── connect ───────────────────────────────────────────────────────────────
+/**
+ * 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 async function connectRemoteSandbox(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    // Two URLs on purpose: `serveUrl` is the CANONICAL display URL that lands in
+    // "open <url>" guidance — it MUST match the origin serve's banner/auto-open
+    // use (`http://localhost:<port>` for the default host), or a user following
+    // the guidance opens a DIFFERENT browser origin (127.0.0.1 vs localhost →
+    // separate SharedWorkers → split sandboxes). `wsBase` is connectivity: the
+    // literal loopback family the health probe actually reached.
+    let serveUrl;
+    let wsBase;
+    if (options.url) {
+        serveUrl = options.url.replace(/\/$/, '');
+        wsBase = serveUrl;
+    }
+    else {
+        const found = await discoverServe(cwd);
+        if (!found) {
+            throw remoteError('not-found', 'no running `pyric dev --bridge` found (looked for .pyric/serve.json in ' +
+                `${cwd} and the default ports) — start your dev server with the bridge enabled and retry.`);
+        }
+        serveUrl = found.url;
+        wsBase = found.base;
+    }
+    const wsUrl = `${wsBase.replace(/^http/, 'ws')}/__pyric/sandbox`;
+    const ws = new WebSocket(wsUrl);
+    // Event-loop hold (exit-hang fix): `ws` exposes no ref/unref of its own —
+    // reach the underlying net.Socket (present once connected). Unref'ing only
+    // changes loop-exit accounting, never delivery: while ANY pending op or
+    // live subscription holds a ref (the core's updateLoopHold), frames flow
+    // normally; when idle, a finished script exits instead of hanging.
+    const wsSocket = () => ws._socket;
+    const core = createRemoteSandboxCore({
+        send: (msg) => ws.send(JSON.stringify(msg)),
+        ref: () => wsSocket()?.ref(),
+        unref: () => wsSocket()?.unref(),
+    }, { serveUrl, opTimeoutMs: options.opTimeoutMs });
+    ws.on('message', (raw) => {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch {
+            return;
+        }
+        if (isBridgeMessage(msg))
+            core.handleMessage(msg);
+    });
+    ws.on('close', () => core.dispose('remote sandbox connection closed (serve stopped or connection lost)'));
+    ws.on('error', (err) => core.dispose(`remote sandbox connection failed: ${err.message}`));
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(remoteError('deadline-exceeded', `timed out connecting to ${wsUrl}`)), ATTACH_TIMEOUT_MS);
+        ws.once('open', () => {
+            clearTimeout(timer);
+            // Idle default: an open-but-idle connection must not pin the event
+            // loop (both the eager and lazy `remoteSandbox` paths come through
+            // here). The core re-refs while ops/subs are outstanding.
+            wsSocket()?.unref();
+            resolve();
+        });
+        ws.once('error', (err) => {
+            clearTimeout(timer);
+            reject(remoteError('unavailable', `failed to connect to ${wsUrl}: ${err.message}`));
+        });
+    });
+    core.start();
+    try {
+        await withTimeout(core.ready, ATTACH_TIMEOUT_MS, `timed out attaching to the bridge at ${wsUrl}`);
+    }
+    catch (err) {
+        try {
+            ws.close();
+        }
+        catch { }
+        throw err;
+    }
+    return createRemoteSandboxHandle({
+        serveUrl,
+        channel: core.channel,
+        close() {
+            core.dispose('remote sandbox connection closed by the client');
+            try {
+                ws.close();
+            }
+            catch { }
+        },
+    });
+}
+/**
+ * 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 function remoteSandbox(options = {}) {
+    return createLazyRemoteSandbox(() => connectRemoteSandbox(options), options);
+}
+/**
+ * The lazy wrapper with the connect function injected — the test seam
+ * (tests inject a fake connect; production injects `connectRemoteSandbox`).
+ */
+export function createLazyRemoteSandbox(connect, options = {}) {
+    let inner = null;
+    let closed = false;
+    function ensure() {
+        if (closed) {
+            return Promise.reject(remoteError('unavailable', 'remote sandbox connection closed by the client'));
+        }
+        if (!inner) {
+            inner = connect().then((h) => {
+                if (closed) {
+                    h.close();
+                    throw remoteError('unavailable', 'remote sandbox connection closed by the client');
+                }
+                // Discovery resolved the real URL — reflect it on the outer handle.
+                handle.serveUrl = h.serveUrl;
+                return h;
+            }, (err) => {
+                // Fail-fast surfaces on this op, but don't latch: the remediation
+                // is "open <url> and retry", so the next op re-attempts the connect.
+                inner = null;
+                throw err;
+            });
+        }
+        return inner;
+    }
+    const channel = {
+        op: (payload) => ensure().then((h) => h.channel.op(payload)),
+        subscribe(sub, onSnap, onError) {
+            let cancelled = false;
+            let innerUnsub = null;
+            ensure().then((h) => {
+                if (cancelled)
+                    return;
+                innerUnsub = h.channel.subscribe(sub, onSnap, onError);
+            }, (err) => {
+                if (cancelled)
+                    return;
+                const e = err instanceof Error && 'code' in err
+                    ? err
+                    : remoteError('unavailable', String(err));
+                if (onError)
+                    onError(e);
+                else
+                    console.error('pyric remote sandbox: subscription failed to connect:', e);
+            });
+            return () => {
+                cancelled = true;
+                if (innerUnsub) {
+                    innerUnsub();
+                    innerUnsub = null;
+                }
+            };
+        },
+    };
+    const handle = createRemoteSandboxHandle({
+        channel,
+        // Before discovery the URL is unknown; op-level errors always carry the
+        // real URL (they come from the inner connect), and `serveUrl` is patched
+        // to the discovered value as soon as the first connect succeeds.
+        serveUrl: options.url?.replace(/\/$/, '') ?? '<pyric dev url (pending discovery)>',
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            const settled = inner;
+            inner = null;
+            if (settled) {
+                settled.then((h) => h.close(), () => { });
+            }
+        },
+    });
+    // `ready` — the eager checker: accessing it starts the connection. Marked
+    // handled (same pattern as the core's `ready`) so a mere existence check
+    // (`handle.ready instanceof Promise`) never surfaces an unhandled rejection.
+    Object.defineProperty(handle, 'ready', {
+        get: () => {
+            const p = ensure().then(() => undefined);
+            p.catch(() => { });
+            return p;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+    return handle;
+}
+function withTimeout(p, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(remoteError('deadline-exceeded', message)), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+// ─── RTDB push-id generator ────────────────────────────────────────────────
+// Client-minted push ids (the worker-protocol contract: `rtdb.push` carries
+// the key so `.key` is synchronously known to callers). Standard Firebase
+// algorithm — 8 chars of timestamp + 12 random, monotonic within one ms.
+// Inlined (like pyric-admin does) because pyric doesn't export its generator.
+const PUSH_CHARS = '-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz';
+let lastPushTime = 0;
+const lastRandChars = new Array(12).fill(0);
+function generatePushId(now = Date.now()) {
+    const duplicateTime = now === lastPushTime;
+    lastPushTime = now;
+    const timeStampChars = new Array(8);
+    let ts = now;
+    for (let i = 7; i >= 0; i--) {
+        timeStampChars[i] = PUSH_CHARS.charAt(ts % 64);
+        ts = Math.floor(ts / 64);
+    }
+    if (ts !== 0) {
+        throw new Error('RTDB push-id: timestamp overflow.');
+    }
+    let id = timeStampChars.join('');
+    if (!duplicateTime) {
+        for (let i = 0; i < 12; i++) {
+            lastRandChars[i] = Math.floor(Math.random() * 64);
+        }
+    }
+    else {
+        let i;
+        for (i = 11; i >= 0 && lastRandChars[i] === 63; i--) {
+            lastRandChars[i] = 0;
+        }
+        if (i < 0) {
+            for (let j = 0; j < 12; j++) {
+                lastRandChars[j] = Math.floor(Math.random() * 64);
+            }
+        }
+        else {
+            lastRandChars[i] = (lastRandChars[i] ?? 0) + 1;
+        }
+    }
+    for (let i = 0; i < 12; i++) {
+        id += PUSH_CHARS.charAt(lastRandChars[i]);
+    }
+    return id;
+}
+//# sourceMappingURL=index.js.map