@cursor/july 0.1.1

package/dist/internal/cursor/credentials.js

@@ -0,0 +1,329 @@
+/**
+ * Cursor account credentials for the agent-serve host.
+ *
+ * Exactly one kind of secret exists at runtime: a **personal Cursor user API
+ * key**. Two ways to obtain it, one code path after that:
+ *
+ * - `agent-serve login` runs the same PKCE browser flow as `cursor-agent`
+ *   and Sand, then uses the short-lived session once to mint a named,
+ *   dashboard-revocable user API key — only the key is stored.
+ * - `CURSOR_API_KEY` (or `serve({ apiKey })`) wins over the stored key, so
+ *   CI and hosted deployments stay env-driven.
+ *
+ * There is deliberately no session-token storage, refresh-token rotation, or
+ * cross-tool credential sharing here: short-lived access tokens are minted
+ * on demand from the API key (see `backend-client.ts`).
+ */
+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 { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { CLI_COMMAND_NAME } from "../distribution.js";
+export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
+const DEFAULT_CURSOR_WEBSITE_URL = "https://cursor.com";
+/** Backend API base URL (`CURSOR_API_BASE_URL` override for local dev). */
+export function cursorBackendUrl() {
+    var _a;
+    return trimTrailingSlash((_a = process.env.CURSOR_API_BASE_URL) !== null && _a !== void 0 ? _a : DEFAULT_CURSOR_BACKEND_URL);
+}
+/** Website base URL for the login deep link (`CURSOR_WEBSITE_URL` override). */
+export function cursorWebsiteUrl() {
+    var _a;
+    return trimTrailingSlash((_a = process.env.CURSOR_WEBSITE_URL) !== null && _a !== void 0 ? _a : DEFAULT_CURSOR_WEBSITE_URL);
+}
+function trimTrailingSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+// ============================================================================
+// Stored credential (one file, one secret)
+// ============================================================================
+const storedCredentialsSchema = z.object({
+    /** Backend the key was minted against; keys never cross backends. */
+    backendUrl: z.string(),
+    apiKey: z.string().min(1),
+});
+/**
+ * `~/.config/agent-serve/credentials.json` (0600), honoring
+ * `XDG_CONFIG_HOME`. `AGENT_SERVE_CONFIG_DIR` pins the directory outright
+ * (tests, containers).
+ */
+export function credentialsFilePath() {
+    var _a, _b;
+    const configDir = (_a = process.env.AGENT_SERVE_CONFIG_DIR) !== null && _a !== void 0 ? _a : join((_b = process.env.XDG_CONFIG_HOME) !== null && _b !== void 0 ? _b : join(homedir(), ".config"), "agent-serve");
+    return join(configDir, "credentials.json");
+}
+export function readStoredCredentials() {
+    return __awaiter(this, void 0, void 0, function* () {
+        let raw;
+        try {
+            raw = yield readFile(credentialsFilePath(), "utf8");
+        }
+        catch (_a) {
+            return undefined;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (_b) {
+            // Corrupt file — treat as signed out; login rewrites it.
+            return undefined;
+        }
+        const credentials = storedCredentialsSchema.safeParse(parsed);
+        if (!credentials.success) {
+            return undefined;
+        }
+        return {
+            backendUrl: trimTrailingSlash(credentials.data.backendUrl),
+            apiKey: credentials.data.apiKey,
+        };
+    });
+}
+export function writeStoredCredentials(credentials) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = credentialsFilePath();
+        yield mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        yield writeFile(path, `${JSON.stringify(credentials, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        // writeFile mode only applies on create; clamp pre-existing files too.
+        yield chmod(path, 0o600);
+    });
+}
+export function clearStoredCredentials() {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield rm(credentialsFilePath());
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+/**
+ * Resolve the account API key for `backendUrl` (defaults to the active
+ * backend): explicit option → `CURSOR_API_KEY` → stored login. A stored key
+ * minted against a different backend is ignored rather than sent to the
+ * wrong host.
+ */
+export function resolveApiKey(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const backendUrl = (_a = options === null || options === void 0 ? void 0 : options.backendUrl) !== null && _a !== void 0 ? _a : cursorBackendUrl();
+        if ((options === null || options === void 0 ? void 0 : options.apiKey) !== undefined && options.apiKey.trim() !== "") {
+            return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
+        }
+        const envKey = process.env.CURSOR_API_KEY;
+        if (envKey !== undefined && envKey.trim() !== "") {
+            return { apiKey: envKey.trim(), source: "env", backendUrl };
+        }
+        const stored = yield readStoredCredentials();
+        if (stored !== undefined && stored.backendUrl === backendUrl) {
+            return { apiKey: stored.apiKey, source: "login", backendUrl };
+        }
+        return undefined;
+    });
+}
+/** One-line hint for "no credentials" errors, shared across surfaces. */
+export const SIGN_IN_HINT = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / pass serve({ apiKey })).`;
+// ============================================================================
+// PKCE browser login (mirrors cursor-agent / Sand)
+// ============================================================================
+const loginPollResponseSchema = z.object({ accessToken: z.string() });
+/**
+ * Build the `/loginDeepControl` deep link and its PKCE material. The portal
+ * completes the login and the backend holds the resulting session until
+ * {@link pollForLoginTokens} picks it up with the verifier.
+ */
+export function startBrowserLogin() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const uuid = randomUUID();
+    const url = new URL("/loginDeepControl", `${cursorWebsiteUrl()}/`);
+    url.searchParams.set("challenge", challenge);
+    url.searchParams.set("uuid", uuid);
+    url.searchParams.set("mode", "login");
+    url.searchParams.set("redirectTarget", "cli");
+    return { loginUrl: url.toString(), uuid, verifier };
+}
+/** Backend pending-login 404 body from `respondToPollLogin` ("still waiting"). */
+const POLL_PENDING_BODY = "Not found";
+/**
+ * Poll `/auth/poll` until the browser login completes.
+ *
+ * **POST, with the verifier in the JSON body.** The verifier is redeemable:
+ * anyone holding it (plus the uuid) can complete the login and mint a durable
+ * user API key, so it must not reach a URL — not the backend's access log, not
+ * a proxy's request log, not a terminal. `POST /auth/poll` exists for exactly
+ * this reason.
+ *
+ * A backend that predates that route answers POST with a route-not-found 404.
+ * Those get one sticky fallback to `GET /auth/poll?uuid=…&verifier=…` — the
+ * shape the vscode client and Sand already use — so the login still works
+ * while the backend catches up. The fallback puts the verifier in the query
+ * string, which is the exposure POST was added to remove, so it warns; it
+ * disappears on its own once the backend serves POST.
+ */
+export function pollForLoginTokens(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b, _c, _d;
+        const backendUrl = trimTrailingSlash((_b = args.backendUrl) !== null && _b !== void 0 ? _b : cursorBackendUrl());
+        const fetchImpl = (_c = args.fetchImpl) !== null && _c !== void 0 ? _c : fetch;
+        const redact = (text) => truncate(redactVerifier(text, args.verifier));
+        const postUrl = `${backendUrl}/auth/poll`;
+        // Only built if the backend leaves us no choice (see the doc comment).
+        const getUrl = () => {
+            const url = new URL("/auth/poll", `${backendUrl}/`);
+            url.searchParams.set("uuid", args.uuid);
+            url.searchParams.set("verifier", args.verifier);
+            return url.toString();
+        };
+        const maxAttempts = (_d = args.maxAttempts) !== null && _d !== void 0 ? _d : 150;
+        let useGet = false;
+        let consecutiveErrors = 0;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (isAborted(args.signal)) {
+                return { status: "cancelled" };
+            }
+            try {
+                const response = useGet
+                    ? yield fetchImpl(getUrl(), Object.assign({ method: "GET", headers: { accept: "application/json" } }, (args.signal === undefined ? {} : { signal: args.signal })))
+                    : yield fetchImpl(postUrl, Object.assign({ method: "POST", headers: {
+                            accept: "application/json",
+                            "content-type": "application/json",
+                        }, body: JSON.stringify({ uuid: args.uuid, verifier: args.verifier }) }, (args.signal === undefined ? {} : { signal: args.signal })));
+                if (response.status === 404) {
+                    const body = (yield response.text()).trim();
+                    if (!useGet && body !== POLL_PENDING_BODY) {
+                        // Any 404 on POST that is not the pending marker means this backend
+                        // has no POST route. Retry the same attempt over GET rather than
+                        // guessing at body shapes; GET's handling below is deliberately
+                        // lenient, so an unrecognized body cannot strand the login.
+                        useGet = true;
+                        (_a = args.logger) === null || _a === void 0 ? void 0 : _a.call(args, `${backendUrl} has no POST /auth/poll; falling back to GET, which puts the single-use login verifier in the request URL (and the backend's access log). It will use POST once the backend deploys that route.`);
+                        continue;
+                    }
+                    if (useGet && isRouteNotFoundBody(body)) {
+                        // Neither verb is served — polling harder cannot fix that.
+                        return {
+                            status: "failed",
+                            message: `${backendUrl} serves neither POST nor GET /auth/poll (404: ${redact(body)})`,
+                        };
+                    }
+                    // Pending: the browser sign-in has not landed yet. On GET this is
+                    // deliberately lenient — treating an unrecognized 404 body as fatal is
+                    // what made an earlier poll die on its first attempt and call it a
+                    // timeout.
+                    consecutiveErrors = 0;
+                }
+                else if (!response.ok) {
+                    consecutiveErrors++;
+                    if (consecutiveErrors >= 3) {
+                        return {
+                            status: "failed",
+                            message: `${backendUrl}/auth/poll kept failing (${response.status}: ${redact((yield response.text()).trim())})`,
+                        };
+                    }
+                }
+                else {
+                    const body = loginPollResponseSchema.safeParse(yield response.json());
+                    if (body.success && body.data.accessToken !== "") {
+                        return { status: "signed_in", accessToken: body.data.accessToken };
+                    }
+                    return {
+                        status: "failed",
+                        message: `${backendUrl}/auth/poll returned 200 without an accessToken`,
+                    };
+                }
+            }
+            catch (error) {
+                if (isAborted(args.signal)) {
+                    return { status: "cancelled" };
+                }
+                consecutiveErrors++;
+                if (consecutiveErrors >= 3) {
+                    return {
+                        status: "failed",
+                        message: `could not reach ${backendUrl}/auth/poll (${redact(error instanceof Error ? error.message : String(error))})`,
+                    };
+                }
+            }
+            yield sleep(Math.min(1000 * Math.pow(1.2, attempt), 10000), args.signal);
+        }
+        return { status: "timed_out" };
+    });
+}
+/**
+ * Fastify's route-not-found envelope: `{"message":"Route GET:/auth/poll not
+ * found",…}`. Distinct from the backend's pending marker ({@link
+ * POLL_PENDING_BODY}), and the only 404 shape on the GET path that is fatal.
+ */
+function isRouteNotFoundBody(body) {
+    if (!body.startsWith("{")) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(body);
+        return (typeof parsed.message === "string" &&
+            /^Route \w+:/.test(parsed.message) &&
+            parsed.message.includes("not found"));
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Keep the verifier out of anything user-visible. Fastify's 404 body echoes the
+ * whole request URL — `Route GET:/auth/poll?uuid=…&verifier=… not found` — so
+ * echoing a poll response verbatim would print a redeemable secret into the
+ * terminal, CI logs, and pasted bug reports.
+ */
+function redactVerifier(text, verifier) {
+    if (verifier === "") {
+        return text;
+    }
+    let redacted = text.split(verifier).join("[verifier redacted]");
+    const encoded = encodeURIComponent(verifier);
+    if (encoded !== verifier) {
+        redacted = redacted.split(encoded).join("[verifier redacted]");
+    }
+    return redacted;
+}
+function truncate(value, max = 200) {
+    return value.length <= max ? value : `${value.slice(0, max)}…`;
+}
+// Reads the abort flag through a call boundary so repeated checks across an
+// `await` aren't collapsed by control-flow narrowing (the signal is mutated
+// by another task, so `aborted` really can flip mid-loop).
+function isAborted(signal) {
+    return (signal === null || signal === void 0 ? void 0 : signal.aborted) === true;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if ((signal === null || signal === void 0 ? void 0 : signal.aborted) === true) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Pulls `/v0/scm-events` into agent-serve: register repos+events, long-poll
+ * with a durable offset under `<stateDir>/offset.json`. Registration-gated
+ * so consumption never starts unsubscribed. Shared streams: durable
+ * consumer id + repo/event filtering skip sibling deliveries.
+ *
+ * The long-poll lifecycle (consumer id, registration-gated consume loop,
+ * anchor/offset/backoff) lives in the shared {@link CursorRelayCore}; this
+ * module is the GitHub adapter over it. {@link RelayOffsetStore} and
+ * {@link compareStreamOffsets} are re-exported for stability.
+ */
+import { RelayOffsetStore } from "./cursor-relay-core.js";
+export { RelayOffsetStore };
+/** PR snapshot from scm-events compact metadata (Sand-style; no raw body). */
+export type CursorScmPullRequestMeta = {
+    number: number;
+    url: string;
+    title?: string;
+    body?: string | null;
+    draft?: boolean;
+    authorLogin?: string;
+    headRef?: string;
+    headSha?: string;
+    baseRef?: string;
+    baseSha?: string;
+};
+/** One event delivered by `GET /v0/scm-events` (metadata only). */
+export interface CursorScmEvent {
+    offset: string;
+    provider: string;
+    eventName: string;
+    deliveryId?: string;
+    repo: string;
+    receivedAtMs: number;
+    /** Webhook `action` when present. */
+    action?: string;
+    /** PR number when the delivery is PR-scoped. */
+    prNumber?: number;
+    /** Canonical PR URL when known. */
+    prUrl?: string;
+    /**
+     * Richer PR snapshot when the backend saw `body.pull_request`. Enough to
+     * stub a Zod-valid GitHub `pull_request` webhook body.
+     */
+    pullRequest?: CursorScmPullRequestMeta;
+    /** GitHub-side event time from the payload, when present. */
+    occurredAtMs?: number;
+}
+export interface CursorEventRelayOptions {
+    baseUrl: string;
+    apiKey: string;
+    repos: readonly string[];
+    events: readonly string[];
+    stateDir: string;
+    /** Called for each matching event; failures are logged, not retried. */
+    dispatch: (event: CursorScmEvent) => 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 cursor-events log fragment: event, repo/PR, times, delivery. */
+export declare function formatCursorScmEventLog(event: {
+    eventName: string;
+    repo: string;
+    action?: string;
+    prNumber?: number;
+    prUrl?: string;
+    receivedAtMs: number;
+    occurredAtMs?: number;
+    deliveryId?: string;
+}): string;
+/**
+ * Minimal GitHub webhook body from an SCM-events metadata envelope.
+ * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
+ * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
+ */
+export declare function scmMetadataToGitHubPayload(event: {
+    repo: string;
+    action?: string;
+    prNumber?: number;
+    prUrl?: string;
+    pullRequest?: CursorScmPullRequestMeta;
+}): Record<string, unknown>;
+/**
+ * GitHub SCM-events relay: a thin {@link CursorRelayCore} adapter. Consumers
+ * keep the same `new CursorEventRelay(options).start()/.stop()` surface.
+ */
+export declare class CursorEventRelay {
+    private readonly options;
+    private readonly core;
+    /**
+     * Normalized repos the server confirmed for THIS consumer. The stream is
+     * shared with sibling consumers of the same principal, so only events for
+     * these repos may dispatch.
+     */
+    private subscribedRepos;
+    private readonly loggedSkippedRepos;
+    constructor(options: CursorEventRelayOptions);
+    /**
+     * Whether an event from the shared stream belongs to THIS consumer: the
+     * repo must be one the server confirmed for us and the event kind one the
+     * mounted channels declared. Anything else came from a sibling consumer's
+     * subscription and must not fire this host's hooks.
+     */
+    private shouldDispatch;
+    start(): void;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=cursor-event-relay.d.ts.map

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

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

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

@@ -0,0 +1,181 @@
+/**
+ * Pulls `/v0/scm-events` into agent-serve: register repos+events, long-poll
+ * with a durable offset under `<stateDir>/offset.json`. Registration-gated
+ * so consumption never starts unsubscribed. Shared streams: durable
+ * consumer id + repo/event filtering skip sibling deliveries.
+ *
+ * The long-poll lifecycle (consumer id, registration-gated consume loop,
+ * anchor/offset/backoff) lives in the shared {@link CursorRelayCore}; this
+ * module is the GitHub adapter over it. {@link RelayOffsetStore} and
+ * {@link compareStreamOffsets} are re-exported for stability.
+ */
+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 { CursorRelayCore, RelayOffsetStore, } from "./cursor-relay-core.js";
+export { RelayOffsetStore };
+/** Human-readable cursor-events log fragment: event, repo/PR, times, delivery. */
+export function formatCursorScmEventLog(event) {
+    var _a;
+    const action = event.action !== undefined && event.action !== "" ? `.${event.action}` : "";
+    const pr = event.prUrl !== undefined
+        ? event.prUrl
+        : event.prNumber !== undefined
+            ? `${event.repo}#${event.prNumber}`
+            : event.repo;
+    const received = new Date(event.receivedAtMs).toISOString();
+    const occurred = event.occurredAtMs !== undefined
+        ? ` occurred=${new Date(event.occurredAtMs).toISOString()}`
+        : "";
+    const delivery = (_a = event.deliveryId) !== null && _a !== void 0 ? _a : "no delivery id";
+    return `${event.eventName}${action} on ${pr} received=${received}${occurred} (${delivery})`;
+}
+/**
+ * Minimal GitHub webhook body from an SCM-events metadata envelope.
+ * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
+ * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
+ */
+export function scmMetadataToGitHubPayload(event) {
+    var _a, _b, _c;
+    const slash = event.repo.indexOf("/");
+    const owner = slash === -1 ? "" : event.repo.slice(0, slash);
+    const name = slash === -1 ? event.repo : event.repo.slice(slash + 1);
+    const repoUrl = `https://github.com/${event.repo}`;
+    const prMeta = event.pullRequest;
+    const prNumber = (_a = prMeta === null || prMeta === void 0 ? void 0 : prMeta.number) !== null && _a !== void 0 ? _a : event.prNumber;
+    const prUrl = (_c = (_b = prMeta === null || prMeta === void 0 ? void 0 : prMeta.url) !== null && _b !== void 0 ? _b : event.prUrl) !== null && _c !== void 0 ? _c : (prNumber !== undefined ? `${repoUrl}/pull/${prNumber}` : undefined);
+    const payload = {
+        repository: {
+            full_name: event.repo,
+            name,
+            html_url: repoUrl,
+            owner: { login: owner },
+        },
+    };
+    payload.action = event.action;
+    const title = prMeta === null || prMeta === void 0 ? void 0 : prMeta.title;
+    const headRef = prMeta === null || prMeta === void 0 ? void 0 : prMeta.headRef;
+    const headSha = prMeta === null || prMeta === void 0 ? void 0 : prMeta.headSha;
+    const baseRef = prMeta === null || prMeta === void 0 ? void 0 : prMeta.baseRef;
+    const canStubTypedPr = prNumber !== undefined &&
+        prUrl !== undefined &&
+        title !== undefined &&
+        headRef !== undefined &&
+        headSha !== undefined &&
+        baseRef !== undefined;
+    if (canStubTypedPr) {
+        const pullRequest = {
+            number: prNumber,
+            html_url: prUrl,
+            title,
+            body: prMeta === null || prMeta === void 0 ? void 0 : prMeta.body,
+            draft: prMeta === null || prMeta === void 0 ? void 0 : prMeta.draft,
+            head: { ref: headRef, sha: headSha },
+            base: { ref: baseRef, sha: prMeta === null || prMeta === void 0 ? void 0 : prMeta.baseSha },
+        };
+        if ((prMeta === null || prMeta === void 0 ? void 0 : prMeta.authorLogin) !== undefined) {
+            pullRequest.user = { login: prMeta.authorLogin };
+        }
+        payload.pull_request = pullRequest;
+        payload.issue = {
+            number: prNumber,
+            html_url: prUrl,
+            pull_request: {},
+        };
+        return payload;
+    }
+    if (prNumber !== undefined) {
+        payload.pull_request = {
+            number: prNumber,
+            html_url: prUrl !== null && prUrl !== void 0 ? prUrl : `${repoUrl}/pull/${prNumber}`,
+        };
+        payload.issue = {
+            number: prNumber,
+            html_url: prUrl !== null && prUrl !== void 0 ? prUrl : `${repoUrl}/pull/${prNumber}`,
+            pull_request: {},
+        };
+    }
+    return payload;
+}
+/**
+ * GitHub SCM-events relay: a thin {@link CursorRelayCore} adapter. Consumers
+ * keep the same `new CursorEventRelay(options).start()/.stop()` surface.
+ */
+export class CursorEventRelay {
+    constructor(options) {
+        this.options = options;
+        /**
+         * Normalized repos the server confirmed for THIS consumer. The stream is
+         * shared with sibling consumers of the same principal, so only events for
+         * these repos may dispatch.
+         */
+        this.subscribedRepos = new Set();
+        this.loggedSkippedRepos = new Set();
+        const adapter = {
+            logPrefix: "cursor-events",
+            subscribePath: "/v0/scm-events/subscriptions",
+            pollPath: "/v0/scm-events",
+            buildRegistrationBody: (consumerId) => ({
+                consumerId,
+                subscriptions: this.options.repos.map((repo) => ({
+                    provider: "github",
+                    repo,
+                    events: [...this.options.events],
+                })),
+            }),
+            applyRegistrationResponse: (json) => {
+                var _a, _b;
+                const result = json;
+                const statuses = (_a = result.repos) !== null && _a !== void 0 ? _a : [];
+                this.subscribedRepos = new Set(statuses
+                    .filter((status) => status.isSubscribed)
+                    .map((status) => status.repo));
+                const lines = [];
+                for (const status of statuses.filter((s) => !s.isSubscribed)) {
+                    lines.push(`not subscribed to ${status.repo}: ${(_b = status.detail) !== null && _b !== void 0 ? _b : "unknown reason"}`);
+                }
+                if (this.subscribedRepos.size > 0) {
+                    lines.push(`subscribed to ${[...this.subscribedRepos].join(", ")} for events: ${this.options.events.join(", ")}`);
+                }
+                return lines;
+            },
+            shouldDispatch: (event) => this.shouldDispatch(event),
+            dispatch: (event) => this.options.dispatch(event),
+        };
+        this.core = new CursorRelayCore(Object.assign(Object.assign({ baseUrl: options.baseUrl, apiKey: options.apiKey, stateDir: options.stateDir, adapter, logger: options.logger }, (options.fetchImpl === undefined
+            ? {}
+            : { fetchImpl: options.fetchImpl })), (options.pollWaitMs === undefined
+            ? {}
+            : { pollWaitMs: options.pollWaitMs })));
+    }
+    /**
+     * Whether an event from the shared stream belongs to THIS consumer: the
+     * repo must be one the server confirmed for us and the event kind one the
+     * mounted channels declared. Anything else came from a sibling consumer's
+     * subscription and must not fire this host's hooks.
+     */
+    shouldDispatch(event) {
+        if (!this.subscribedRepos.has(event.repo)) {
+            if (!this.loggedSkippedRepos.has(event.repo)) {
+                this.loggedSkippedRepos.add(event.repo);
+                this.options.logger(`[agent-serve] cursor-events: skipping events for ${event.repo}: not in this host's subscription (another consumer of this API key likely subscribed it)`);
+            }
+            return false;
+        }
+        return this.options.events.includes(event.eventName);
+    }
+    start() {
+        this.core.start();
+    }
+    stop() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.core.stop();
+        });
+    }
+}