@cursor/july 0.1.1

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

@@ -0,0 +1,113 @@
+/**
+ * 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-serve] 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;
+    /**
+     * 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 are logged, not retried. */
+    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;
+}
+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 consumerId;
+    /** undefined until the first registration, so a clean first success logs. */
+    private lastRegistrationLog;
+    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>;
+    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;
+    /** 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":"AAAA;;;;;;;;GAQG;AAsBH,8DAA8D;AAC9D,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAArC,YAA6B,QAAQ,EAAE,MAAM,EAAI;IAEjD,OAAO,KAAK,QAAQ,GAEnB;IAEK,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAcxC;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxC;CACF;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMjE;AASD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEzD;AAQD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE;IAC7D,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACnD;;;;;OAKG;IACH,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IACnD;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB,CAAC,MAAM,SAAS;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,eAAe,CAAC,MAAM,SAAS;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE;IAWhD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,UAAU,CAAM;IACxB,6EAA6E;IAC7E,OAAO,CAAC,mBAAmB,CAAqB;IAEhD,YAA6B,OAAO,EAAE,sBAAsB,CAAC,MAAM,CAAC,EAGnE;IAED,KAAK,IAAI,IAAI,CAKZ;IAED;;;;OAIG;YACW,GAAG;IAWjB;;;;;OAKG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CA2BzC;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB1B;IAED,OAAO,CAAC,GAAG;YAMG,OAAO;IAiBrB,4EAA4E;YAC9D,oBAAoB;IAYlC;;;;OAIG;YACW,YAAY;IA6B1B,8EAA8E;IAC9E,OAAO,CAAC,sBAAsB;YAShB,WAAW;IA4FzB,2EAA2E;YAC7D,uBAAuB;IAgBrC,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,OAAO;CAKhB"}

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

@@ -0,0 +1,364 @@
+/**
+ * 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";
+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;
+/** 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);
+}
+export class CursorRelayCore {
+    constructor(options) {
+        var _a;
+        this.options = options;
+        this.running = false;
+        this.consumerId = "";
+        this.offsetStore = new RelayOffsetStore(options.stateDir);
+        this.fetchImpl = (_a = options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+    }
+    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(() => {
+                void 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;
+            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);
+                }),
+            ]);
+        });
+    }
+    log(line) {
+        this.options.logger(`[agent-serve] ${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({ authorization: `Bearer ${this.options.apiKey}` }, (body === undefined ? {} : { "content-type": "application/json" })) }, (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));
+                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)) {
+                            try {
+                                yield this.options.adapter.dispatch(event);
+                            }
+                            catch (error) {
+                                this.log(`dispatch failed at offset ${event.offset}: ${describeRelayError(error)}`);
+                            }
+                        }
+                        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);
+                }
+            }
+        });
+    }
+    /** Log the failure, sleep, and return the backoff for the NEXT failure. */
+    backoffAfterHttpFailure(response, backoffMs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const isAuthFailure = response.status === 401 || response.status === 403;
+            const sleepMs = isAuthFailure ? 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 isAuthFailure
+                ? 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/cursor-slack-relay.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Pulls `/v0/slack-events` into agent-serve: register the mounted
+ * cursor-account Slack agents (name + icon) with the Cursor backend, then
+ * long-poll routed events with a durable offset under
+ * `<stateDir>/offset.json` and dispatch each to the agent it addresses.
+ * Outbound Slack Web API calls are proxied through `POST /v0/slack-events/api`
+ * via a per-agent {@link SlackApiTransport} binding.
+ *
+ * Same lifecycle rules as the SCM relay (`cursor-event-relay.ts`):
+ * registration-gated consumption, heartbeat re-registration, durable
+ * consumer id, at-least-once dispatch with client-owned offsets.
+ */
+import type { CursorSlackEnvelope } from "../channels/slack/cursor-account.js";
+/** One agent this host registers over the Cursor Slack connection. */
+export interface CursorSlackAgentRegistration {
+    name: string;
+    iconUrl?: string;
+    iconEmoji?: string;
+}
+/** One relayed event as delivered to {@link CursorSlackRelayOptions.dispatch}. */
+export type CursorSlackRelayEvent = CursorSlackEnvelope & {
+    offset: string;
+};
+export interface CursorSlackRelayOptions {
+    baseUrl: string;
+    apiKey: string;
+    agents: readonly CursorSlackAgentRegistration[];
+    stateDir: string;
+    /**
+     * Called for each event addressed to this consumer's agents; failures are
+     * logged, not retried.
+     */
+    dispatch: (envelope: CursorSlackRelayEvent) => Promise<void>;
+    logger: (line: string) => void;
+    /** Test seam. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Test seam: override long-poll wait (default 25s). */
+    pollWaitMs?: number;
+}
+/** Human-readable log fragment for one relayed Slack event. */
+export declare function formatCursorSlackEventLog(envelope: {
+    eventName: string;
+    agentName: string;
+    matchedBy: string;
+    channelId: string;
+    threadTs: string;
+    receivedAtMs: number;
+    eventId?: string;
+}): string;
+/**
+ * Build the backend proxy caller one agent's {@link SlackApiTransport}
+ * binds to. Returns Slack-shaped `{ ok: false, error }` bodies on transport
+ * failures so channel soft-fail paths behave exactly like direct Web API
+ * callers.
+ */
+export declare function createCursorSlackApiCaller(args: {
+    baseUrl: string;
+    apiKey: string;
+    agentName: string;
+    consumerId: string;
+    fetchImpl?: typeof fetch;
+    logger?: (line: string) => void;
+}): (method: string, callArgs: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * Cursor Slack relay: a thin {@link CursorRelayCore} adapter. Keeps the same
+ * `new CursorSlackRelay(options)` surface with `.resolveConsumerId()`,
+ * `.start()`, and `.stop()` (the server binds outbound transports with the
+ * resolved consumer id before starting).
+ */
+export declare class CursorSlackRelay {
+    private readonly options;
+    private readonly core;
+    /**
+     * Agent names (lowercased) the server confirmed for THIS consumer. The
+     * stream is shared with sibling consumers of the same principal, so only
+     * events for these agents (and this consumer id) may dispatch.
+     */
+    private subscribedAgents;
+    private consumerId;
+    constructor(options: CursorSlackRelayOptions);
+    /**
+     * Resolve the durable consumer id before starting, so transports can bind
+     * with it. Also used by tests.
+     */
+    resolveConsumerId(): Promise<string>;
+    /**
+     * Whether a relayed event belongs to THIS consumer: the backend stamps
+     * each envelope with the registering consumer id and agent.
+     */
+    private shouldDispatch;
+    start(): void;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=cursor-slack-relay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-slack-relay.d.ts","sourceRoot":"","sources":["../../src/internal/cursor-slack-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAO/E,sEAAsE;AACtE,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAYD,kFAAkF;AAClF,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAGT;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,CACF,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0CpC;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAUf,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,UAAU,CAAM;IAExB,YAA6B,OAAO,EAAE,uBAAuB,EAiE5D;IAED;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAGzC;IAED;;;OAGG;IACH,OAAO,CAAC,cAAc;IAOtB,KAAK,IAAI,IAAI,CAEZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;CACF"}