@superblocksteam/gateway 2.0.155-next.0

package/dist/preview/capture-screenshot.js

@@ -0,0 +1,158 @@
+/**
+ * Headless capture of a preview viewer URL for MCP image content.
+ *
+ * Best-effort: callers must succeed with URLs alone when this returns
+ * undefined. Output is capped for Claude Desktop tool-result size limits.
+ */
+import { isLoopbackUrl } from "./viewer-url.js";
+/** Soft cap on decoded bytes before base64 (~256 KiB). */
+export const PREVIEW_SCREENSHOT_MAX_BYTES = 256 * 1024;
+/** How long to keep waiting for the shell to subscribe before handshaking anyway. */
+const HANDSHAKE_FALLBACK_MS = 2_000;
+/**
+ * Settle time after the app's first element becomes visible, covering the
+ * layout and data-bound widgets that land just behind it. The app publishes
+ * no "finished rendering" signal an embedder could await.
+ */
+const APP_PAINT_SETTLE_MS = 2_500;
+/**
+ * Page source that hands the deployed shell its bearer, and the whole reason a
+ * headless capture can paint a real app.
+ *
+ * `ui-deployed-shell` only accepts a bearer through an `INITIALIZE_EMBED`
+ * message from its embedder, and ~300ms after mount it gives up and tries
+ * Auth0 silent login instead — which has no session to find here. At top level
+ * the shell's embedder port has no parent window to check messages against, so
+ * it accepts one posted by the page itself.
+ *
+ * Delivery happens exactly once: each `INITIALIZE_EMBED` replaces the shell's
+ * auth state and restarts its bootstrap, so a repeating handshake would keep
+ * the app from ever settling.
+ *
+ * This is source text rather than a function handed to `addInitScript` because
+ * Playwright ships a function by serializing it, which drags in whatever
+ * helpers the bundler injected into its body (`__name` under tsx) and throws a
+ * ReferenceError in the page.
+ *
+ * The result is only ever evaluated as script source (Playwright forwards it
+ * to CDP `addScriptToEvaluateOnNewDocument`), never interpolated into HTML, so
+ * `JSON.stringify` is sufficient to contain the token. Putting it in a
+ * `<script>` element would not be — the token would need `</script>` escaped.
+ */
+export function buildEmbedHandshakeScript(token) {
+    return `(function () {
+  // The app iframe gets its own credentials from the shell; a handshake there
+  // would be rejected as not-from-parent anyway.
+  if (window.parent !== window) return;
+  var token = ${JSON.stringify(token)};
+  var sent = false;
+  function send() {
+    if (sent) return;
+    sent = true;
+    // Addressed to this window only. "*" would expose the bearer to every
+    // listener on the page, including third-party scripts the shell loads.
+    window.postMessage(
+      { data: { token: token }, type: "INITIALIZE_EMBED" },
+      window.location.origin,
+    );
+  }
+  // Handshake the moment the shell subscribes, so its very first render
+  // already has the bearer and no bootstrap is wasted on the Auth0 path.
+  var addEventListener = window.addEventListener;
+  window.addEventListener = function (type, listener, options) {
+    addEventListener.call(window, type, listener, options);
+    if (type === "message") send();
+  };
+  // Safety net for a shell that subscribes some other way: a late handshake
+  // still recovers, at the cost of one discarded bootstrap.
+  window.setTimeout(send, ${HANDSHAKE_FALLBACK_MS});
+})();`;
+}
+/**
+ * Captures a JPEG screenshot via Playwright when available. Soft-fails when
+ * Chromium is missing or the page never becomes ready — callers must still
+ * return preview URLs when this returns undefined.
+ */
+export const capturePreviewScreenshotWithPlaywright = async (input) => {
+    let chromium;
+    try {
+        // Optional runtime dep — demos without browsers still return preview URLs.
+        const mod = (await import(/* webpackIgnore: true */ "playwright"));
+        chromium = mod.chromium;
+    }
+    catch (error) {
+        console.warn("gateway preview screenshot: playwright unavailable", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    const timeoutMs = input.timeoutMs ?? 45_000;
+    let browser;
+    try {
+        // launch() must stay inside this try: a missing Chromium binary throws
+        // here, and that used to fail the whole get_app / preview_app capability.
+        browser = await chromium.launch({ headless: true });
+        const page = await browser.newPage();
+        if (input.embedToken) {
+            // The bearer would reach the app iframe on hosts where the shell hands
+            // the runtime token straight through, so it stays on the local stack
+            // this capture path exists for.
+            if (isLoopbackUrl(input.url)) {
+                await page.addInitScript({
+                    content: buildEmbedHandshakeScript(input.embedToken),
+                });
+            }
+            else {
+                console.warn("gateway preview screenshot: shell is not local, capturing unauthenticated", { url: input.url });
+            }
+        }
+        await page.setViewportSize({ width: 1280, height: 800 });
+        // Not "networkidle": the shell holds a dev-server HMR socket open and
+        // the app streams telemetry, so idle never arrives and goto() would
+        // spend the entire timeout before throwing on an app that had painted.
+        await page.goto(input.url, {
+            timeout: timeoutMs,
+            waitUntil: "domcontentloaded",
+        });
+        // Wait on content *inside* the app frame, not the frame element: the
+        // shell attaches an about:blank iframe within ~50ms and only points it
+        // at the app once auth, metadata, and the CDN cookie prime land, so the
+        // element alone photographs a loading spinner.
+        await page
+            .frameLocator("iframe")
+            .locator("body > *")
+            .first()
+            .waitFor({ state: "visible", timeout: timeoutMs })
+            // A frame that never paints still deserves a screenshot: the error
+            // page it captures is what tells the caller what went wrong.
+            .catch(() => undefined);
+        await page.waitForTimeout(APP_PAINT_SETTLE_MS);
+        let quality = 80;
+        let buffer = await page.screenshot({ type: "jpeg", quality });
+        while (buffer.byteLength > PREVIEW_SCREENSHOT_MAX_BYTES && quality > 30) {
+            quality -= 10;
+            buffer = await page.screenshot({ type: "jpeg", quality });
+        }
+        if (buffer.byteLength > PREVIEW_SCREENSHOT_MAX_BYTES) {
+            console.warn("gateway preview screenshot exceeds size cap; skipping", {
+                bytes: buffer.byteLength,
+            });
+            return undefined;
+        }
+        return {
+            dataBase64: buffer.toString("base64"),
+            mimeType: "image/jpeg",
+        };
+    }
+    catch (error) {
+        console.warn("gateway preview screenshot failed", {
+            message: error instanceof Error ? error.message : String(error),
+            url: input.url,
+        });
+        return undefined;
+    }
+    finally {
+        await browser?.close().catch(() => undefined);
+    }
+};
+//# sourceMappingURL=capture-screenshot.js.map

package/dist/preview/capture-screenshot.js.map

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

package/dist/preview/viewer-url.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Builds the URL that loads a code-mode preview without a Superblocks UI login.
+ *
+ * Deployed-shell contract: the CDN/shell accepts `commitId` + `jwt` as query
+ * params on the first request so it can set a `viewer-jwt` cookie (see
+ * csb-mock `deployed-cdn` and production shell). That first-hop query JWT is
+ * unavoidable for the shell itself today; scoped `apps:preview` tokens are
+ * issued by the Server with the platform default TTL (typically 24h).
+ *
+ * Gateway-facing openLink URLs put the JWT in the URL fragment instead, so
+ * tunnel/proxy access logs and Referer headers do not record the bearer. An
+ * interstitial page reads the fragment and redirects to the shell query form.
+ */
+export declare function isHttpsUrl(url: string): boolean;
+export declare function isLoopbackUrl(url: string): boolean;
+/**
+ * The embed shell route for a preview commit.
+ *
+ * Unlike {@link buildDeployedShellViewerUrl}, which hands the browser the app
+ * bundle straight off the CDN, this loads `ui-deployed-shell`: the piece that
+ * resolves auth, fetches app metadata, primes the CDN cookie, and feeds the
+ * app iframe. A bare bundle has no way to authenticate its APIs, so only this
+ * URL can paint a working app. It carries no token — the shell takes its
+ * bearer from an `INITIALIZE_EMBED` message — and the commit comes from the
+ * application's current version.
+ *
+ * `deployedShellBaseUrl` is forwarded as `deployedUrl` because the shell reads
+ * its CDN origin from `/env.js`, which the local stack does not publish; it
+ * then falls back to a hardcoded `localhost:4041` that only matches slot 0.
+ * On every other slot the cookie prime is refused and the shell renders its
+ * error page instead of the app.
+ */
+export declare function buildEmbedShellPreviewUrl(input: {
+    applicationId: string;
+    deployedShellBaseUrl?: string;
+    uiBaseUrl: string;
+}): string;
+/**
+ * Replaces the origin of `url` with `publicBaseUrl`'s origin, keeping path and
+ * query. Used so Claude Desktop can `openLink` an https URL while the actual
+ * app still lives on a slot-local host.
+ */
+export declare function rewriteUrlOrigin(url: string, publicBaseUrl: string | undefined): string;
+/**
+ * Deployed-shell URL for a preview commit, with the scoped JWT in the query.
+ *
+ * `deployedShellBaseUrl` may include `__SB_APP_ID` (production CDN pattern) or
+ * be a plain origin (local csb-mock CDN on :4041).
+ */
+export declare function buildDeployedShellViewerUrl(input: {
+    applicationId: string;
+    commitId: string;
+    deployedShellBaseUrl: string;
+    jwt: string;
+}): string;
+export type OpenablePreviewUrls = {
+    /**
+     * True when `previewUrl` is https and Claude Desktop can call `openLink`.
+     */
+    openableViaHttps: boolean;
+    /**
+     * URL returned to MCP clients / Open preview button.
+     */
+    previewUrl: string;
+    /**
+     * Direct deployed-shell (or UI) URL used for headless screenshot capture.
+     * May be http localhost even when `previewUrl` is an https gateway redirect.
+     */
+    viewerUrl: string;
+};
+/**
+ * Picks the best preview URL for Claude: prefer an https front door, fall back
+ * to the local viewer / UI preview URL for copy-paste + screenshot.
+ */
+export declare function buildOpenablePreviewUrls(input: {
+    applicationId: string;
+    commitId: string;
+    deployedShellBaseUrl: string | undefined;
+    jwt: string | undefined;
+    publicViewerBaseUrl: string | undefined;
+    uiPreviewUrl: string;
+}): OpenablePreviewUrls;

package/dist/preview/viewer-url.js

@@ -0,0 +1,128 @@
+/**
+ * Builds the URL that loads a code-mode preview without a Superblocks UI login.
+ *
+ * Deployed-shell contract: the CDN/shell accepts `commitId` + `jwt` as query
+ * params on the first request so it can set a `viewer-jwt` cookie (see
+ * csb-mock `deployed-cdn` and production shell). That first-hop query JWT is
+ * unavoidable for the shell itself today; scoped `apps:preview` tokens are
+ * issued by the Server with the platform default TTL (typically 24h).
+ *
+ * Gateway-facing openLink URLs put the JWT in the URL fragment instead, so
+ * tunnel/proxy access logs and Referer headers do not record the bearer. An
+ * interstitial page reads the fragment and redirects to the shell query form.
+ */
+export function isHttpsUrl(url) {
+    try {
+        return new URL(url).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "[::1]", "localhost"]);
+export function isLoopbackUrl(url) {
+    try {
+        return LOOPBACK_HOSTNAMES.has(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The embed shell route for a preview commit.
+ *
+ * Unlike {@link buildDeployedShellViewerUrl}, which hands the browser the app
+ * bundle straight off the CDN, this loads `ui-deployed-shell`: the piece that
+ * resolves auth, fetches app metadata, primes the CDN cookie, and feeds the
+ * app iframe. A bare bundle has no way to authenticate its APIs, so only this
+ * URL can paint a working app. It carries no token — the shell takes its
+ * bearer from an `INITIALIZE_EMBED` message — and the commit comes from the
+ * application's current version.
+ *
+ * `deployedShellBaseUrl` is forwarded as `deployedUrl` because the shell reads
+ * its CDN origin from `/env.js`, which the local stack does not publish; it
+ * then falls back to a hardcoded `localhost:4041` that only matches slot 0.
+ * On every other slot the cookie prime is refused and the shell renders its
+ * error page instead of the app.
+ */
+export function buildEmbedShellPreviewUrl(input) {
+    const base = input.uiBaseUrl.trim().replace(/\/$/, "");
+    const url = `${base}/code-mode/embed/applications/preview/${encodeURIComponent(input.applicationId)}`;
+    const cdnBase = input.deployedShellBaseUrl?.trim();
+    if (!cdnBase) {
+        return url;
+    }
+    // Passed verbatim, `__SB_APP_ID` and all: this is the same template shape
+    // the shell expects from env.js, and it expands the placeholder itself.
+    return `${url}?deployedUrl=${encodeURIComponent(cdnBase)}`;
+}
+/**
+ * Replaces the origin of `url` with `publicBaseUrl`'s origin, keeping path and
+ * query. Used so Claude Desktop can `openLink` an https URL while the actual
+ * app still lives on a slot-local host.
+ */
+export function rewriteUrlOrigin(url, publicBaseUrl) {
+    if (!publicBaseUrl?.trim()) {
+        return url;
+    }
+    try {
+        const original = new URL(url);
+        const publicBase = new URL(publicBaseUrl);
+        // Build from the public origin so a slot-local port (e.g. :4141) is not
+        // carried onto an https tunnel that listens on 443.
+        return new URL(`${original.pathname}${original.search}${original.hash}`, publicBase).toString();
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Deployed-shell URL for a preview commit, with the scoped JWT in the query.
+ *
+ * `deployedShellBaseUrl` may include `__SB_APP_ID` (production CDN pattern) or
+ * be a plain origin (local csb-mock CDN on :4041).
+ */
+export function buildDeployedShellViewerUrl(input) {
+    const base = input.deployedShellBaseUrl
+        .trim()
+        .replace(/\/$/, "")
+        .replaceAll("__SB_APP_ID", input.applicationId);
+    const url = new URL(base.includes("://") ? base : `http://${base}`);
+    // Ensure we hit the shell root when the base is only an origin.
+    if (!url.pathname || url.pathname === "") {
+        url.pathname = "/";
+    }
+    url.searchParams.set("commitId", input.commitId);
+    url.searchParams.set("jwt", input.jwt);
+    return url.toString();
+}
+/**
+ * Picks the best preview URL for Claude: prefer an https front door, fall back
+ * to the local viewer / UI preview URL for copy-paste + screenshot.
+ */
+export function buildOpenablePreviewUrls(input) {
+    const viewerUrl = input.deployedShellBaseUrl && input.jwt
+        ? buildDeployedShellViewerUrl({
+            applicationId: input.applicationId,
+            commitId: input.commitId,
+            deployedShellBaseUrl: input.deployedShellBaseUrl,
+            jwt: input.jwt,
+        })
+        : input.uiPreviewUrl;
+    if (input.publicViewerBaseUrl && isHttpsUrl(input.publicViewerBaseUrl)) {
+        const previewUrl = rewriteUrlOrigin(viewerUrl, input.publicViewerBaseUrl);
+        return {
+            openableViaHttps: isHttpsUrl(previewUrl),
+            previewUrl,
+            viewerUrl,
+        };
+    }
+    // Stdio Gateway does not bind HTTP, so never advertise a gateway /viewer
+    // path as openable. Preview URLs are the editor or the deployed shell.
+    return {
+        openableViaHttps: isHttpsUrl(viewerUrl),
+        previewUrl: viewerUrl,
+        viewerUrl,
+    };
+}
+//# sourceMappingURL=viewer-url.js.map

package/dist/preview/viewer-url.js.map

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

package/dist/process/fault-barrier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Exit code the gateway uses for a fault it decided not to survive.
+ *
+ * Distinct from 0 (an operator asked it to stop) and from 1 (it never got far
+ * enough to serve), so a supervisor can tell "restart this" from "stop trying".
+ * `superviseGateway` in the CLI reads it; the two MUST stay in agreement.
+ */
+export declare const GATEWAY_FAULT_EXIT_CODE = 97;
+export type GatewayFaultKind = "uncaught_exception" | "unhandled_rejection";
+export type GatewayFault = {
+    at: number;
+    /** Whether the gateway gave up its process over this. */
+    fatal: boolean;
+    kind: GatewayFaultKind;
+    message: string;
+};
+/**
+ * The slice of `process` this needs, so a test can emit a fault without arming
+ * the real handlers and taking the runner down with them.
+ */
+export type FaultBarrierListener = (...args: unknown[]) => void;
+export type FaultBarrierHost = {
+    listenerCount: (event: string) => number;
+    off: (event: string, handler: FaultBarrierListener) => void;
+    on: (event: string, handler: FaultBarrierListener) => void;
+};
+export type FaultBarrierOptions = {
+    drainDeadlineMs?: number;
+    exit?: (code: number) => void;
+    log?: (message: string, fault: GatewayFault) => void;
+    /** Where the fault is recorded so `/health` can stop claiming to be well. */
+    onFault: (fault: GatewayFault) => void;
+    process?: FaultBarrierHost;
+    /** Best-effort release of listeners and sockets before a fatal exit. */
+    shutdown?: () => Promise<void>;
+};
+/**
+ * Node's default for an unhandled rejection is to kill the process. That is
+ * wrong for this gateway: its fire-and-forget paths (a live-edit turn, a
+ * liveness beat, a progress notification) belong to one caller, and a
+ * dependency that stopped answering must cost that caller its call rather than
+ * cost every concurrent caller the process. See ENG-5809, where ~8 concurrent
+ * agents lost the gateway to rejections that trailed a 120s upstream timeout.
+ *
+ * An uncaught exception is treated differently on purpose. A rejection that
+ * escaped a promise is a call that failed; an exception nobody caught means an
+ * invariant broke somewhere the code did not expect to be, and the heap it left
+ * behind is not worth serving from. Those exit deterministically on
+ * {@link GATEWAY_FAULT_EXIT_CODE} so a supervisor restarts at once, which is
+ * the other half of ENG-5809: recovery took between 80 seconds and never.
+ *
+ * Returns a disposer that releases the handlers, for tests and for a second
+ * gateway in the same process.
+ */
+export declare function installFaultBarrier(options: FaultBarrierOptions): () => void;

package/dist/process/fault-barrier.js

@@ -0,0 +1,113 @@
+import { recordGatewayFault } from "../telemetry/metrics.js";
+/**
+ * Exit code the gateway uses for a fault it decided not to survive.
+ *
+ * Distinct from 0 (an operator asked it to stop) and from 1 (it never got far
+ * enough to serve), so a supervisor can tell "restart this" from "stop trying".
+ * `superviseGateway` in the CLI reads it; the two MUST stay in agreement.
+ */
+export const GATEWAY_FAULT_EXIT_CODE = 97;
+/** How long a fatal fault waits for in-flight work before the process goes. */
+const DEFAULT_DRAIN_DEADLINE_MS = 2_000;
+/** Hosts this module has already armed, so a second install is a no-op. */
+const armed = new WeakSet();
+function messageOf(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Node's default for an unhandled rejection is to kill the process. That is
+ * wrong for this gateway: its fire-and-forget paths (a live-edit turn, a
+ * liveness beat, a progress notification) belong to one caller, and a
+ * dependency that stopped answering must cost that caller its call rather than
+ * cost every concurrent caller the process. See ENG-5809, where ~8 concurrent
+ * agents lost the gateway to rejections that trailed a 120s upstream timeout.
+ *
+ * An uncaught exception is treated differently on purpose. A rejection that
+ * escaped a promise is a call that failed; an exception nobody caught means an
+ * invariant broke somewhere the code did not expect to be, and the heap it left
+ * behind is not worth serving from. Those exit deterministically on
+ * {@link GATEWAY_FAULT_EXIT_CODE} so a supervisor restarts at once, which is
+ * the other half of ENG-5809: recovery took between 80 seconds and never.
+ *
+ * Returns a disposer that releases the handlers, for tests and for a second
+ * gateway in the same process.
+ */
+export function installFaultBarrier(options) {
+    const host = options.process ?? process;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const log = options.log ??
+        ((message, fault) => {
+            console.error(message, fault);
+        });
+    // Installed twice, one gateway would report every fault twice and race two
+    // exits. `gateway serve` boots through `startStdioGateway`, so this is
+    // reachable rather than theoretical. The MCP host owns process lifecycle;
+    // this barrier records the fault and exits instead of wrapping a grandchild.
+    //
+    // Keyed on our own installs rather than on how many listeners the host has.
+    // Counting foreign listeners looks equivalent and is not: any library that
+    // registers one - a test runner, an instrumentation SDK - would silently
+    // suppress this barrier, and the gateway would go back to dying on a
+    // rejection with nothing recording why.
+    if (armed.has(host)) {
+        return () => undefined;
+    }
+    armed.add(host);
+    const record = (kind, error, fatal) => {
+        const fault = {
+            at: Date.now(),
+            fatal,
+            kind,
+            message: messageOf(error),
+        };
+        recordGatewayFault(fault);
+        log(fatal
+            ? "gateway fatal fault; exiting for a supervised restart"
+            : "gateway survived an unhandled rejection", fault);
+        options.onFault(fault);
+        return fault;
+    };
+    const onRejection = (reason) => {
+        record("unhandled_rejection", reason, false);
+    };
+    const onException = (error) => {
+        record("uncaught_exception", error, true);
+        void drainThenExit();
+    };
+    let exiting = false;
+    const drainThenExit = async () => {
+        // A second exception during the drain must not start a second drain, or the
+        // deadline below stops being a deadline.
+        if (exiting) {
+            return;
+        }
+        exiting = true;
+        const deadlineMs = options.drainDeadlineMs ?? DEFAULT_DRAIN_DEADLINE_MS;
+        try {
+            // The race is the point: a drain that hangs is the failure mode being
+            // fixed, so it never decides when the process leaves.
+            await Promise.race([
+                options.shutdown?.() ?? Promise.resolve(),
+                new Promise((resolve) => {
+                    const timer = setTimeout(resolve, deadlineMs);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        catch {
+            // A shutdown that threw changes nothing about needing to exit.
+        }
+        exit(GATEWAY_FAULT_EXIT_CODE);
+    };
+    host.on("unhandledRejection", onRejection);
+    host.on("uncaughtException", onException);
+    return () => {
+        armed.delete(host);
+        host.off("unhandledRejection", onRejection);
+        host.off("uncaughtException", onException);
+    };
+}
+//# sourceMappingURL=fault-barrier.js.map

package/dist/process/fault-barrier.js.map

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

package/dist/resume/memory-progress-store.d.ts

@@ -0,0 +1,39 @@
+import { type AppScopeKey, type ProgressCursorKey, type ProgressCursorRecord, type ProgressStore } from "./types.js";
+/**
+ * Cap on how many cursors and pointers a single process will hold.
+ *
+ * Redis expires keys on its own; a plain Map does not, and a gateway that ran
+ * for a week would hold one entry per (caller, application) it had ever
+ * served. Insertion order is iteration order for a Map, so the oldest write
+ * is the one dropped — a caller evicted this way re-reads the retained
+ * history rather than losing anything, which is the same outcome as its
+ * cursor having expired.
+ */
+export declare const MAX_MEMORY_PROGRESS_ENTRIES = 2048;
+/**
+ * Local-only fallback, matching the other in-memory stores.
+ *
+ * Not a second source of truth: two replicas with private maps would hand the
+ * same caller two different positions in the same stream, which is exactly
+ * the divergence Redis is required outside local to prevent.
+ */
+export declare class MemoryProgressStore implements ProgressStore {
+    private readonly cursors;
+    private readonly lastActivity;
+    private readonly liveEdits;
+    getCursor(key: ProgressCursorKey): Promise<ProgressCursorRecord | undefined>;
+    getLastActivityAtMs(key: AppScopeKey): Promise<number | undefined>;
+    getLiveEditId(key: AppScopeKey): Promise<string | undefined>;
+    setCursor(input: ProgressCursorKey & {
+        record: ProgressCursorRecord;
+        ttlMs?: number;
+    }): Promise<void>;
+    setLastActivityAtMs(input: AppScopeKey & {
+        atMs: number;
+        ttlMs?: number;
+    }): Promise<void>;
+    setLiveEditId(input: AppScopeKey & {
+        liveEditId: string;
+        ttlMs?: number;
+    }): Promise<void>;
+}