@cursor/bdk 0.2.1

package/dist/internal/cursor-relay-core.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Shared engine for the Cursor pull relays (`--cursor-events` for GitHub SCM
+ * events, and the automatic Slack relay for `cursorAccount` channels). Both
+ * long-poll a per-principal Cursor backend stream with a durable client-owned
+ * offset and a heartbeat registration; only the subscribe/poll paths, the
+ * registration body/response, and the per-event dispatch differ. Those vary
+ * as data or closures on a {@link RelayAdapter}, so this engine is written
+ * once and tested through each provider's relay.
+ */
+/** Durable offset snapshot under `<stateDir>/offset.json`. */
+export declare class RelayOffsetStore {
+    private readonly stateDir;
+    constructor(stateDir: string);
+    private get filePath();
+    load(): Promise<string | undefined>;
+    save(offset: string): Promise<void>;
+}
+/** Compare stream offsets (`<ms>-<seq>`). */
+export declare function compareStreamOffsets(a: string, b: string): number;
+export declare function describeRelayError(error: unknown): string;
+/**
+ * Provider-specific behavior for {@link CursorRelayCore}. Everything else —
+ * consumer-id persistence, registration-gated lifecycle, heartbeat, the
+ * anchor/poll/dedupe/offset loop, and backoff — is shared.
+ */
+export interface RelayAdapter<TEvent extends {
+    offset: string;
+}> {
+    /** Log fragment, e.g. `cursor-events` → `[agent-sdk] cursor-events: …`. */
+    readonly logPrefix: string;
+    /** Subscription registration path, e.g. `/v0/scm-events/subscriptions`. */
+    readonly subscribePath: string;
+    /** Base long-poll path, e.g. `/v0/scm-events`. */
+    readonly pollPath: string;
+    /** The registration request body for this consumer id. */
+    buildRegistrationBody(consumerId: string): unknown;
+    /**
+     * The empty-scope registration body used to deregister this consumer on a
+     * clean stop. When present, `stop()` best-effort PUTs it so the consumer's
+     * registration does not linger as a ghost until its server-side TTL (a
+     * ghost with this host's agent names makes name routing ambiguous for a
+     * redeployed sibling until it expires).
+     */
+    buildDeregistrationBody?(consumerId: string): unknown;
+    /**
+     * Apply the (ok) registration response: update the accepted-scope filter
+     * and return the human-readable outcome lines to log. The core logs them
+     * only when they change, so returning stable lines keeps the heartbeat
+     * quiet.
+     */
+    applyRegistrationResponse(json: unknown): string[];
+    /**
+     * Whether an event from the shared principal stream belongs to THIS
+     * consumer (repo/agent + kind filter). Non-matching events still advance
+     * the offset but are not dispatched.
+     */
+    shouldDispatch(event: TEvent): boolean;
+    /**
+     * Handle one matching event. Failures retry a bounded number of times
+     * ({@link DISPATCH_ATTEMPTS}), then log and skip.
+     */
+    dispatch(event: TEvent): Promise<void>;
+}
+export interface CursorRelayCoreOptions<TEvent extends {
+    offset: string;
+}> {
+    baseUrl: string;
+    apiKey: string;
+    stateDir: string;
+    adapter: RelayAdapter<TEvent>;
+    logger: (line: string) => void;
+    /** Test seam. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Test seam: override long-poll wait (default 25s). */
+    pollWaitMs?: number;
+    /**
+     * Desired-revision generation for hosted engines. Sent as
+     * `x-agent-serve-generation` so the control plane can fence zombies after
+     * a redeploy. Defaults to `process.env.AGENT_SERVE_GENERATION` when set.
+     */
+    deploymentGeneration?: number;
+}
+/** Must match server-shared `AGENT_SERVE_GENERATION_HEADER`. */
+export declare const AGENT_SERVE_GENERATION_HEADER = "x-agent-serve-generation";
+/** Must match server-shared `AGENT_SERVE_GENERATION_ENV_VAR`. */
+export declare const AGENT_SERVE_GENERATION_ENV_VAR = "AGENT_SERVE_GENERATION";
+export declare function resolveAgentServeDeploymentGeneration(explicit?: number): number | undefined;
+export declare class CursorRelayCore<TEvent extends {
+    offset: string;
+}> {
+    private readonly options;
+    private running;
+    private abort;
+    private registerTimer;
+    private consumePromise;
+    private readonly offsetStore;
+    private readonly fetchImpl;
+    private readonly deploymentGeneration;
+    private consumerId;
+    /** undefined until the first registration, so a clean first success logs. */
+    private lastRegistrationLog;
+    /** Whether any registration succeeded (gates the stop-time deregister). */
+    private registeredOnce;
+    /**
+     * The in-flight heartbeat re-registration, if any. `stop()` awaits it
+     * before deregistering so a just-sent heartbeat cannot land after the
+     * deregistration PUT and resurrect the registration for a full TTL.
+     */
+    private heartbeatPromise;
+    constructor(options: CursorRelayCoreOptions<TEvent>);
+    start(): void;
+    /**
+     * Registration-gated lifecycle: no anchor and no consumption until one
+     * registration succeeded — anchoring "now" while unsubscribed would
+     * silently miss every delivery in between.
+     */
+    private run;
+    /**
+     * Durable consumer identity for this state root (memoized), so this host's
+     * registrations never clobber a sibling consumer's on the same key and
+     * survive restarts. Public so callers can bind transports with it before
+     * `start()` (the Slack relay proxies outbound calls under this id).
+     */
+    resolveConsumerId(): Promise<string>;
+    stop(): Promise<void>;
+    /**
+     * Best-effort empty-scope PUT on clean stop, so this consumer's
+     * registration is dropped immediately instead of lingering until its
+     * server-side TTL. A ghost registration keeps this host's agent names
+     * live and makes name routing ambiguous for a redeployed sibling with a
+     * fresh consumer id. Failures only log — the TTL still cleans up.
+     */
+    private deregister;
+    private log;
+    private request;
+    /** Retry registration with backoff until it succeeds or the relay stops. */
+    private registerUntilSuccess;
+    /**
+     * Register (or refresh) via the adapter. Returns true when the server
+     * accepted the registration (individual scopes may still have failed
+     * validation — the adapter logs those).
+     */
+    private registerOnce;
+    /** Log registration outcome lines only when they change (heartbeat-quiet). */
+    private logRegistrationOutcome;
+    private consumeLoop;
+    /**
+     * Dispatch one event with a small bounded retry before the offset advances
+     * past it. Transient local failures (e.g. a connection reset while POSTing
+     * to the channel) used to drop the event outright; a poison event still
+     * only costs {@link DISPATCH_ATTEMPTS} tries and is then skipped, keeping
+     * at-least-once semantics without a retry loop.
+     */
+    private dispatchWithRetry;
+    /** Log the failure, sleep, and return the backoff for the NEXT failure. */
+    private backoffAfterHttpFailure;
+    private sleep;
+    private isAbort;
+}
+//# sourceMappingURL=cursor-relay-core.d.ts.map

package/dist/internal/cursor-relay-core.d.ts.map

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

package/dist/internal/cursor-relay-core.js

@@ -0,0 +1,470 @@
+/**
+ * Shared engine for the Cursor pull relays (`--cursor-events` for GitHub SCM
+ * events, and the automatic Slack relay for `cursorAccount` channels). Both
+ * long-poll a per-principal Cursor backend stream with a durable client-owned
+ * offset and a heartbeat registration; only the subscribe/poll paths, the
+ * registration body/response, and the per-event dispatch differ. Those vary
+ * as data or closures on a {@link RelayAdapter}, so this engine is written
+ * once and tested through each provider's relay.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LOG_PREFIX } from "./distribution.js";
+const OFFSET_SNAPSHOT_VERSION = 1;
+const DEFAULT_POLL_WAIT_MS = 25000;
+const DEFAULT_POLL_LIMIT = 100;
+const DEFAULT_REGISTER_INTERVAL_MS = 5 * 60 * 1000;
+const CONSUMER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const DEFAULT_IDLE_POLL_DELAY_MS = 250;
+const MIN_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30000;
+const AUTH_FAILURE_BACKOFF_MS = 60000;
+/** Attempts per event before the offset advances past it. */
+const DISPATCH_ATTEMPTS = 3;
+const DISPATCH_RETRY_DELAYS_MS = [250, 1000];
+/** Budget for the best-effort deregistration PUT during stop(). */
+const DEREGISTER_TIMEOUT_MS = 1500;
+/** Durable offset snapshot under `<stateDir>/offset.json`. */
+export class RelayOffsetStore {
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+    }
+    get filePath() {
+        return join(this.stateDir, "offset.json");
+    }
+    load() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const raw = yield readFile(this.filePath, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed.version === OFFSET_SNAPSHOT_VERSION && typeof parsed.offset === "string") {
+                    return parsed.offset;
+                }
+                return undefined;
+            }
+            catch (_a) {
+                return undefined;
+            }
+        });
+    }
+    save(offset) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield mkdir(this.stateDir, { recursive: true });
+            const snapshot = {
+                version: OFFSET_SNAPSHOT_VERSION,
+                offset,
+                updatedAt: new Date().toISOString(),
+            };
+            // Write-then-rename so a crash mid-write never corrupts the snapshot.
+            const tmpPath = `${this.filePath}.tmp`;
+            yield writeFile(tmpPath, JSON.stringify(snapshot, null, 2), "utf8");
+            yield rename(tmpPath, this.filePath);
+        });
+    }
+}
+/** Compare stream offsets (`<ms>-<seq>`). */
+export function compareStreamOffsets(a, b) {
+    const [aMs, aSeq] = splitOffset(a);
+    const [bMs, bSeq] = splitOffset(b);
+    if (aMs !== bMs)
+        return aMs < bMs ? -1 : 1;
+    if (aSeq !== bSeq)
+        return aSeq < bSeq ? -1 : 1;
+    return 0;
+}
+function splitOffset(offset) {
+    const dash = offset.indexOf("-");
+    const ms = Number(dash === -1 ? offset : offset.slice(0, dash));
+    const seq = dash === -1 ? 0 : Number(offset.slice(dash + 1));
+    return [Number.isFinite(ms) ? ms : 0, Number.isFinite(seq) ? seq : 0];
+}
+export function describeRelayError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Must match server-shared `AGENT_SERVE_GENERATION_HEADER`. */
+export const AGENT_SERVE_GENERATION_HEADER = "x-agent-serve-generation";
+/** Must match server-shared `AGENT_SERVE_GENERATION_ENV_VAR`. */
+export const AGENT_SERVE_GENERATION_ENV_VAR = "AGENT_SERVE_GENERATION";
+export function resolveAgentServeDeploymentGeneration(explicit) {
+    var _a;
+    if (explicit !== undefined && Number.isSafeInteger(explicit) && explicit > 0) {
+        return explicit;
+    }
+    const raw = (_a = process.env[AGENT_SERVE_GENERATION_ENV_VAR]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
+    }
+    if (!/^\d+$/.test(raw)) {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return parsed;
+}
+export class CursorRelayCore {
+    constructor(options) {
+        var _a;
+        this.options = options;
+        this.running = false;
+        this.consumerId = "";
+        /** Whether any registration succeeded (gates the stop-time deregister). */
+        this.registeredOnce = false;
+        this.offsetStore = new RelayOffsetStore(options.stateDir);
+        this.fetchImpl = (_a = options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        this.deploymentGeneration = resolveAgentServeDeploymentGeneration(options.deploymentGeneration);
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.abort = new AbortController();
+        this.consumePromise = this.run();
+    }
+    /**
+     * Registration-gated lifecycle: no anchor and no consumption until one
+     * registration succeeded — anchoring "now" while unsubscribed would
+     * silently miss every delivery in between.
+     */
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            yield this.resolveConsumerId();
+            const registered = yield this.registerUntilSuccess();
+            if (!registered)
+                return;
+            this.registerTimer = setInterval(() => {
+                this.heartbeatPromise = this.registerOnce();
+            }, DEFAULT_REGISTER_INTERVAL_MS);
+            (_b = (_a = this.registerTimer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+            yield this.consumeLoop();
+        });
+    }
+    /**
+     * Durable consumer identity for this state root (memoized), so this host's
+     * registrations never clobber a sibling consumer's on the same key and
+     * survive restarts. Public so callers can bind transports with it before
+     * `start()` (the Slack relay proxies outbound calls under this id).
+     */
+    resolveConsumerId() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.consumerId !== "") {
+                return this.consumerId;
+            }
+            const filePath = join(this.options.stateDir, "consumer-id");
+            try {
+                const existing = (yield readFile(filePath, "utf8")).trim();
+                if (CONSUMER_ID_PATTERN.test(existing)) {
+                    this.consumerId = existing;
+                    return existing;
+                }
+            }
+            catch (_a) {
+                // Missing or unreadable: mint below.
+            }
+            const minted = randomUUID();
+            try {
+                yield mkdir(this.options.stateDir, { recursive: true });
+                const tmpPath = `${filePath}.tmp`;
+                yield writeFile(tmpPath, `${minted}\n`, "utf8");
+                yield rename(tmpPath, filePath);
+            }
+            catch (error) {
+                this.log(`could not persist consumer id (${describeRelayError(error)}); using an ephemeral one for this run`);
+            }
+            this.consumerId = minted;
+            return minted;
+        });
+    }
+    stop() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (!this.running)
+                return;
+            this.running = false;
+            if (this.registerTimer !== undefined) {
+                clearInterval(this.registerTimer);
+                this.registerTimer = undefined;
+            }
+            (_a = this.abort) === null || _a === void 0 ? void 0 : _a.abort();
+            // Bounded wait: server close must never hang on a poll that ignores the
+            // abort (offsets are saved as events are processed, so cutting the loop
+            // loose loses nothing).
+            yield Promise.race([
+                (_b = this.consumePromise) === null || _b === void 0 ? void 0 : _b.catch(() => { }),
+                new Promise(resolve => {
+                    var _a;
+                    const timer = setTimeout(resolve, 2000);
+                    (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+                }),
+            ]);
+            // A heartbeat re-registration may be in flight (its fetch was just
+            // aborted); let it settle so it cannot land after the deregistration.
+            yield (_c = this.heartbeatPromise) === null || _c === void 0 ? void 0 : _c.catch(() => { });
+            yield this.deregister();
+        });
+    }
+    /**
+     * Best-effort empty-scope PUT on clean stop, so this consumer's
+     * registration is dropped immediately instead of lingering until its
+     * server-side TTL. A ghost registration keeps this host's agent names
+     * live and makes name routing ambiguous for a redeployed sibling with a
+     * fresh consumer id. Failures only log — the TTL still cleans up.
+     */
+    deregister() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const adapter = this.options.adapter;
+            if (adapter.buildDeregistrationBody === undefined ||
+                !this.registeredOnce ||
+                this.consumerId === "") {
+                return;
+            }
+            const url = `${this.options.baseUrl.replace(/\/+$/, "")}${adapter.subscribePath}`;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), DEREGISTER_TIMEOUT_MS);
+            (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+            try {
+                const response = yield this.fetchImpl(url, {
+                    method: "PUT",
+                    headers: Object.assign({ authorization: `Bearer ${this.options.apiKey}`, "content-type": "application/json" }, (this.deploymentGeneration === undefined
+                        ? {}
+                        : {
+                            [AGENT_SERVE_GENERATION_HEADER]: String(this.deploymentGeneration),
+                        })),
+                    body: JSON.stringify(adapter.buildDeregistrationBody(this.consumerId)),
+                    signal: controller.signal,
+                });
+                if (response.ok) {
+                    this.log("deregistered on shutdown");
+                }
+                else {
+                    this.log(`deregistration failed: ${response.status} (registration lapses by TTL)`);
+                }
+            }
+            catch (error) {
+                this.log(`deregistration failed: ${describeRelayError(error)} (registration lapses by TTL)`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+    }
+    log(line) {
+        this.options.logger(`${LOG_PREFIX} ${this.options.adapter.logPrefix}: ${line}`);
+    }
+    request(method, path, body) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = `${this.options.baseUrl.replace(/\/+$/, "")}${path}`;
+            return this.fetchImpl(url, Object.assign(Object.assign({ method, headers: Object.assign(Object.assign({ authorization: `Bearer ${this.options.apiKey}` }, (body === undefined ? {} : { "content-type": "application/json" })), (this.deploymentGeneration === undefined
+                    ? {}
+                    : {
+                        [AGENT_SERVE_GENERATION_HEADER]: String(this.deploymentGeneration),
+                    })) }, (body === undefined ? {} : { body: JSON.stringify(body) })), (this.abort === undefined ? {} : { signal: this.abort.signal })));
+        });
+    }
+    /** Retry registration with backoff until it succeeds or the relay stops. */
+    registerUntilSuccess() {
+        return __awaiter(this, void 0, void 0, function* () {
+            let backoffMs = MIN_BACKOFF_MS;
+            while (this.running) {
+                if (yield this.registerOnce()) {
+                    return true;
+                }
+                yield this.sleep(backoffMs);
+                backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+            }
+            return false;
+        });
+    }
+    /**
+     * Register (or refresh) via the adapter. Returns true when the server
+     * accepted the registration (individual scopes may still have failed
+     * validation — the adapter logs those).
+     */
+    registerOnce() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.running)
+                return false;
+            try {
+                const response = yield this.request("PUT", this.options.adapter.subscribePath, this.options.adapter.buildRegistrationBody(this.consumerId));
+                if (!response.ok) {
+                    const text = yield response.text().catch(() => "");
+                    this.logRegistrationOutcome([
+                        `registration failed: ${response.status} ${text.slice(0, 300)}`,
+                    ]);
+                    return false;
+                }
+                const json = (yield response.json());
+                this.logRegistrationOutcome(this.options.adapter.applyRegistrationResponse(json));
+                this.registeredOnce = true;
+                return true;
+            }
+            catch (error) {
+                if (this.isAbort(error))
+                    return false;
+                this.logRegistrationOutcome([`registration error: ${describeRelayError(error)}`]);
+                return false;
+            }
+        });
+    }
+    /** Log registration outcome lines only when they change (heartbeat-quiet). */
+    logRegistrationOutcome(lines) {
+        const key = lines.join("\n");
+        if (key === this.lastRegistrationLog)
+            return;
+        this.lastRegistrationLog = key;
+        for (const line of lines) {
+            this.log(line);
+        }
+    }
+    consumeLoop() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            let backoffMs = MIN_BACKOFF_MS;
+            let offset = yield this.offsetStore.load();
+            let announcedGap = false;
+            while (this.running) {
+                try {
+                    if (offset === undefined) {
+                        // First run: anchor at "now" so the agent does not replay (and
+                        // react to) the retained backlog of old events.
+                        const anchorResponse = yield this.request("GET", `${this.options.adapter.pollPath}?after=%24&limit=1`);
+                        if (!anchorResponse.ok) {
+                            backoffMs = yield this.backoffAfterHttpFailure(anchorResponse, backoffMs);
+                            continue;
+                        }
+                        const anchor = (yield anchorResponse.json());
+                        offset = anchor.nextOffset;
+                        yield this.offsetStore.save(offset);
+                        this.log(`anchored at offset "${offset}"`);
+                        backoffMs = MIN_BACKOFF_MS;
+                        continue;
+                    }
+                    const query = new URLSearchParams({
+                        after: offset,
+                        limit: String(DEFAULT_POLL_LIMIT),
+                        waitMs: String((_a = this.options.pollWaitMs) !== null && _a !== void 0 ? _a : DEFAULT_POLL_WAIT_MS),
+                    });
+                    const response = yield this.request("GET", `${this.options.adapter.pollPath}?${query.toString()}`);
+                    if (!response.ok) {
+                        backoffMs = yield this.backoffAfterHttpFailure(response, backoffMs);
+                        continue;
+                    }
+                    const poll = (yield response.json());
+                    backoffMs = MIN_BACKOFF_MS;
+                    if (poll.gapDetected && !announcedGap) {
+                        announcedGap = true;
+                        this.log("gap detected: events may have been trimmed while this host was offline; resuming from the oldest retained event");
+                    }
+                    if (poll.events.length > 0) {
+                        announcedGap = false;
+                    }
+                    for (const event of poll.events) {
+                        if (!this.running)
+                            break;
+                        // At-least-once dedupe: never re-dispatch at or before the last
+                        // processed offset (reads are exclusive-after, so this only fires
+                        // on replay after a crash between dispatch and save).
+                        if (compareStreamOffsets(event.offset, offset) <= 0)
+                            continue;
+                        if (this.options.adapter.shouldDispatch(event)) {
+                            yield this.dispatchWithRetry(event);
+                        }
+                        offset = event.offset;
+                    }
+                    if (poll.nextOffset !== "" && compareStreamOffsets(poll.nextOffset, offset) > 0) {
+                        offset = poll.nextOffset;
+                    }
+                    if (poll.events.length > 0) {
+                        yield this.offsetStore.save(offset);
+                    }
+                    else {
+                        yield this.sleep(DEFAULT_IDLE_POLL_DELAY_MS);
+                    }
+                }
+                catch (error) {
+                    if (this.isAbort(error))
+                        return;
+                    this.log(`poll error: ${describeRelayError(error)}`);
+                    yield this.sleep(backoffMs);
+                    backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+                }
+            }
+        });
+    }
+    /**
+     * Dispatch one event with a small bounded retry before the offset advances
+     * past it. Transient local failures (e.g. a connection reset while POSTing
+     * to the channel) used to drop the event outright; a poison event still
+     * only costs {@link DISPATCH_ATTEMPTS} tries and is then skipped, keeping
+     * at-least-once semantics without a retry loop.
+     */
+    dispatchWithRetry(event) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (let attempt = 1; attempt <= DISPATCH_ATTEMPTS; attempt++) {
+                if (attempt > 1 && !this.running) {
+                    this.log(`dispatch abandoned at offset ${event.offset}: relay stopping`);
+                    return;
+                }
+                try {
+                    yield this.options.adapter.dispatch(event);
+                    return;
+                }
+                catch (error) {
+                    if (attempt === DISPATCH_ATTEMPTS) {
+                        this.log(`dispatch failed at offset ${event.offset} after ${attempt} attempts: ${describeRelayError(error)}`);
+                        return;
+                    }
+                    this.log(`dispatch attempt ${attempt} failed at offset ${event.offset}: ${describeRelayError(error)}; retrying`);
+                    yield this.sleep(DISPATCH_RETRY_DELAYS_MS[Math.min(attempt - 1, DISPATCH_RETRY_DELAYS_MS.length - 1)]);
+                }
+            }
+        });
+    }
+    /** Log the failure, sleep, and return the backoff for the NEXT failure. */
+    backoffAfterHttpFailure(response, backoffMs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 409 = generation fence (stale resident after redeploy). Same long
+            // backoff as auth: retrying every second cannot heal a wrong generation.
+            const isAuthOrFenceFailure = response.status === 401 || response.status === 403 || response.status === 409;
+            const sleepMs = isAuthOrFenceFailure ? AUTH_FAILURE_BACKOFF_MS : backoffMs;
+            const text = yield response.text().catch(() => "");
+            this.log(`poll failed: ${response.status} ${text.slice(0, 300)} (retrying in ${Math.round(sleepMs / 1000)}s)`);
+            yield this.sleep(sleepMs);
+            return isAuthOrFenceFailure ? AUTH_FAILURE_BACKOFF_MS : Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+        });
+    }
+    sleep(ms) {
+        return new Promise(resolve => {
+            var _a, _b;
+            const signal = (_a = this.abort) === null || _a === void 0 ? void 0 : _a.signal;
+            if ((signal === null || signal === void 0 ? void 0 : signal.aborted) === true) {
+                resolve();
+                return;
+            }
+            const finish = () => {
+                clearTimeout(timer);
+                signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", finish);
+                resolve();
+            };
+            const timer = setTimeout(finish, ms);
+            (_b = timer.unref) === null || _b === void 0 ? void 0 : _b.call(timer);
+            signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", finish, { once: true });
+        });
+    }
+    isAbort(error) {
+        return !this.running || (error instanceof Error && error.name === "AbortError");
+    }
+}

package/dist/internal/deferred-channel-session.d.ts

@@ -0,0 +1,20 @@
+import type { ChannelSession } from "../types.js";
+/**
+ * Authored code touched a member of the deferred handle that needs the live
+ * session. This is deterministic (the session never exists during admission),
+ * so the admission route surfaces it as a non-retryable 422 rather than a
+ * retryable failure.
+ */
+export declare class DeferredChannelSessionError extends Error {
+    constructor(member: string);
+}
+/**
+ * Inert `ChannelSession` returned by the hosted-admission `send` stub: every
+ * member fails loudly via {@link DeferredChannelSessionError}. Caveat: new
+ * OPTIONAL members added to `ChannelSession` slip through this factory
+ * silently (reads return `undefined`) until a throwing getter is added here.
+ */
+export declare function createDeferredChannelSession(): ChannelSession;
+/** True when `send()` returned a hosted-admission capture handle. */
+export declare function isDeferredChannelSession(session: ChannelSession): boolean;
+//# sourceMappingURL=deferred-channel-session.d.ts.map

package/dist/internal/deferred-channel-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-channel-session.d.ts","sourceRoot":"","sources":["../../src/internal/deferred-channel-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,YAAY,MAAM,EAAE,MAAM,EAQzB;CACF;AAMD;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,cAAc,CAuB7D;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAEzE"}