@cursor/july 0.1.39 → 0.1.41

package/dist/internal/init-project.js

@@ -11,6 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { CLI_COMMAND_NAME, PACKAGE_NAME, packageVersion, } from "./distribution.js";
@@ -70,6 +71,7 @@ export function initProject(options) {
             description: `agent project: ${name}`,
             scripts: {
                 check: "tsc --noEmit",
+                dev: "agent-sdk dev",
             },
             dependencies: {
                 [PACKAGE_NAME]: `^${packageVersion()}`,
@@ -176,6 +178,117 @@ export function installScaffoldDependencies(rootDir_1) {
         };
     });
 }
+/**
+ * Put `agent-sdk` on the user PATH by installing the already-downloaded
+ * project copy into the npm global prefix. `npx @cursor/july init` only
+ * runs the package; this is the install that makes bare `agent-sdk …`
+ * work afterward.
+ */
+export function linkCliOntoPath(rootDir_1) {
+    return __awaiter(this, arguments, void 0, function* (rootDir, options = {}) {
+        var _a, _b, _c;
+        const packageDir = join(rootDir, "node_modules", PACKAGE_NAME);
+        if (!existsSync(packageDir)) {
+            return {
+                ok: false,
+                exitCode: 1,
+                stderr: `missing ${PACKAGE_NAME} under ${packageDir} (run npm install first)`,
+            };
+        }
+        const stdio = (_a = options.stdio) !== null && _a !== void 0 ? _a : "inherit";
+        const command = process.platform === "win32" ? "npm.cmd" : "npm";
+        const args = ["install", "--global", "--no-fund", "--no-audit", packageDir];
+        const runner = (_b = options.runner) !== null && _b !== void 0 ? _b : defaultNpmInstallRunner;
+        const result = yield runner({ command, args, cwd: rootDir, stdio });
+        if (result.exitCode !== 0) {
+            return {
+                ok: false,
+                exitCode: result.exitCode,
+                stderr: result.stderr,
+            };
+        }
+        const whichImpl = (_c = options.whichImpl) !== null && _c !== void 0 ? _c : resolveLinkedCli;
+        const resolvedPath = yield whichImpl(CLI_COMMAND_NAME);
+        return {
+            ok: resolvedPath !== undefined,
+            exitCode: 0,
+            stderr: resolvedPath === undefined
+                ? `${CLI_COMMAND_NAME} linked into the npm global prefix but is not on PATH; open a new shell or add that bin directory to PATH`
+                : "",
+            resolvedPath,
+        };
+    });
+}
+/** Prefer the npm-global bin; ignore an older `agent-sdk` earlier on PATH. */
+function resolveLinkedCli(commandName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const prefix = yield npmGlobalPrefix();
+        if (prefix === undefined) {
+            return whichOnPath(commandName);
+        }
+        const binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
+        const exts = process.platform === "win32"
+            ? ((_a = process.env.PATHEXT) !== null && _a !== void 0 ? _a : ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+            : [""];
+        for (const ext of exts) {
+            const candidate = join(binDir, `${commandName}${ext}`);
+            if (!existsSync(candidate)) {
+                continue;
+            }
+            // Only claim PATH success when this linked bin is the first hit.
+            const onPath = whichOnPath(commandName);
+            return onPath === candidate ? candidate : undefined;
+        }
+        return undefined;
+    });
+}
+function npmGlobalPrefix() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const command = process.platform === "win32" ? "npm.cmd" : "npm";
+        return yield new Promise((resolvePromise) => {
+            var _a, _b;
+            const child = spawn(command, ["prefix", "-g"], {
+                stdio: ["ignore", "pipe", "ignore"],
+                env: process.env,
+            });
+            let out = "";
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.setEncoding("utf8");
+            (_b = child.stdout) === null || _b === void 0 ? void 0 : _b.on("data", (chunk) => {
+                out += chunk;
+            });
+            child.on("error", () => resolvePromise(undefined));
+            child.on("close", (code) => {
+                if (code !== 0) {
+                    resolvePromise(undefined);
+                    return;
+                }
+                const prefix = out.trim();
+                resolvePromise(prefix === "" ? undefined : prefix);
+            });
+        });
+    });
+}
+function whichOnPath(commandName) {
+    var _a, _b;
+    const pathEnv = (_a = process.env.PATH) !== null && _a !== void 0 ? _a : "";
+    const sep = process.platform === "win32" ? ";" : ":";
+    const exts = process.platform === "win32"
+        ? ((_b = process.env.PATHEXT) !== null && _b !== void 0 ? _b : ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+        : [""];
+    for (const dir of pathEnv.split(sep)) {
+        if (dir === "") {
+            continue;
+        }
+        for (const ext of exts) {
+            const candidate = join(dir, `${commandName}${ext}`);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
 function defaultNpmInstallRunner(args) {
     return __awaiter(this, void 0, void 0, function* () {
         return yield new Promise((resolvePromise, reject) => {
@@ -286,6 +399,12 @@ function initNextStepEntries(options) {
     if (cd !== undefined) {
         steps.push({ command: cd });
     }
+    if (!options.cliOnPath) {
+        steps.push({
+            command: 'export PATH="$PWD/node_modules/.bin:$PATH"',
+            note: "use the project-local agent-sdk bin",
+        });
+    }
     if (!options.signedIn) {
         steps.push({
             command: `${CLI_COMMAND_NAME} login`,
@@ -313,10 +432,10 @@ export function printInitGuide() {
     process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
 
 Scaffold a project, then open the playground:
-  ${CLI_COMMAND_NAME} init ./my-agent   # installs deps; signs you in when needed
+  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + puts agent-sdk on PATH
   cd ./my-agent && ${CLI_COMMAND_NAME} dev
 
-Recommended loop once the project exists:
+Recommended loop once the project exists (from the project directory):
   1. Edit agent/ + tools under agent/tools/
   2. ${CLI_COMMAND_NAME} info --dir . --json
   3. ${CLI_COMMAND_NAME} run --dir . --message "..."

package/dist/internal/ledger-serving.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`):
+ * coordination only, no inbox. Every engine `send` acquires the session
+ * lease before its turn runs and commits (head+1, lease released) after
+ * it completes, so cross-pod mutual exclusion, generation fencing, and
+ * the committed head sequence are real.
+ *
+ * **Durability trade-off (deliberate):** there is no durable mailbox.
+ * An event that arrives while the lease is held does NOT park in the
+ * store — the delivering pod waits *in-process*: local concurrent sends
+ * serialize on a per-session promise chain (no claim spinning), and a
+ * lease held by another pod is waited out with bounded claim retries. A
+ * crash therefore loses the in-flight event exactly as resident serving
+ * does. A dead pod's lease simply expires (~30s TTL); the next delivery
+ * claims at generation+1 — no janitor is needed because nothing is
+ * parked.
+ *
+ * Re-entrancy caveat (same shape as resident `waitForCompletion`): a
+ * send issued from *inside* a running turn against the same session
+ * chains behind that turn's serve, so awaiting its resolution from the
+ * turn would deadlock. Fire-and-forget such sends.
+ */
+import type { SessionLedger } from "../ledger/session-ledger.js";
+import type { ChannelSession, SendMessageOptions } from "../types.js";
+/** Wait between claim retries while another holder has the lease. */
+export declare const CLAIM_RETRY_DELAY_MS = 250;
+/**
+ * Give up waiting for the lease after this long — two full lease TTLs,
+ * so a dead holder's expiry (~30s) is always survived with margin.
+ */
+export declare const CLAIM_WAIT_TIMEOUT_MS: number;
+/** The `send` options a ledger delivery carries to the resident turn. */
+export type LedgerDeliverOptions = SendMessageOptions & {
+    mode?: "chat" | "task";
+};
+/** One delivery handed back to the engine's resident path. */
+export interface LedgerTurnRequest {
+    channelId: string;
+    continuationToken: string;
+    message: string;
+    options: LedgerDeliverOptions;
+}
+export interface LedgerServingOptions {
+    ledger: SessionLedger;
+    /**
+     * Run one delivery as a resident-path turn (the engine's `send` with
+     * the internal ledger-delivery flag). Must resolve once the turn is
+     * admitted; the pump awaits `waitForCompletion` itself.
+     */
+    deliverTurn: (request: LedgerTurnRequest) => Promise<ChannelSession>;
+    logger?: (line: string) => void;
+    /** Lease heartbeat cadence while the turn runs (default 10s). */
+    heartbeatIntervalMs?: number;
+    /** Claim retry cadence while the lease is held (default 250ms). */
+    claimRetryDelayMs?: number;
+    /** Give-up bound for lease waiting (default 2× lease TTL). */
+    claimWaitTimeoutMs?: number;
+    clock?: () => number;
+    /** Injectable wait (tests use short real delays; keep them tiny). */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class LedgerServing {
+    private readonly ledger;
+    private readonly deliverTurn;
+    private readonly logger;
+    private readonly heartbeatIntervalMs;
+    private readonly claimRetryDelayMs;
+    private readonly claimWaitTimeoutMs;
+    private readonly clock;
+    private readonly sleep;
+    /**
+     * Per-ledger-session in-process serialization: local concurrent sends
+     * queue here instead of spinning claim retries against our own lease.
+     */
+    private readonly chains;
+    constructor(options: LedgerServingOptions);
+    /** Settle every queued and in-flight delivery. */
+    close(): Promise<void>;
+    /**
+     * Ledger-mode `send`: resolve the session identity, wait for the
+     * lease (in-process queue first, then cross-pod claim retries), run
+     * the turn, commit. Resolves with the engine session handle after the
+     * commit released the lease.
+     */
+    deliver(channelId: string, message: string, options: LedgerDeliverOptions): Promise<ChannelSession>;
+    /** Chain a delivery behind the session's in-flight ones. */
+    private enqueue;
+    /** claim (waiting) → resident turn → commit-release. */
+    private serveOne;
+    /**
+     * Claim the lease, waiting out another holder with bounded retries.
+     * The common waits are short: our own pod's deliveries never reach
+     * here concurrently (the in-process chain serializes them), so a held
+     * lease means another pod is serving — usually for one turn — or died
+     * (expiry unblocks us at ~30s).
+     */
+    private claimWithWait;
+}
+/** Mint the lease holder id for this process. */
+export declare function newLedgerPodId(): string;
+//# sourceMappingURL=ledger-serving.d.ts.map

package/dist/internal/ledger-serving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-serving.d.ts","sourceRoot":"","sources":["../../src/internal/ledger-serving.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtE,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAyB,CAAC;AAE9D,yEAAyE;AACzE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,YAAY,OAAO,EAAE,oBAAoB,EAaxC;IAED,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAED;;;;;OAKG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAazB;IAED,4DAA4D;IAC5D,OAAO,CAAC,OAAO;IAoBf,wDAAwD;YAC1C,QAAQ;IAsDtB;;;;;;OAMG;YACW,aAAa;CAiB5B;AAED,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/internal/ledger-serving.js

@@ -0,0 +1,174 @@
+/**
+ * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`):
+ * coordination only, no inbox. Every engine `send` acquires the session
+ * lease before its turn runs and commits (head+1, lease released) after
+ * it completes, so cross-pod mutual exclusion, generation fencing, and
+ * the committed head sequence are real.
+ *
+ * **Durability trade-off (deliberate):** there is no durable mailbox.
+ * An event that arrives while the lease is held does NOT park in the
+ * store — the delivering pod waits *in-process*: local concurrent sends
+ * serialize on a per-session promise chain (no claim spinning), and a
+ * lease held by another pod is waited out with bounded claim retries. A
+ * crash therefore loses the in-flight event exactly as resident serving
+ * does. A dead pod's lease simply expires (~30s TTL); the next delivery
+ * claims at generation+1 — no janitor is needed because nothing is
+ * parked.
+ *
+ * Re-entrancy caveat (same shape as resident `waitForCompletion`): a
+ * send issued from *inside* a running turn against the same session
+ * chains behind that turn's serve, so awaiting its resolution from the
+ * turn would deadlock. Fire-and-forget such sends.
+ */
+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 { randomBytes, randomUUID } from "node:crypto";
+import { HEARTBEAT_INTERVAL_MS, LEASE_TTL_MS, LedgerFencedError, } from "../ledger/session-ledger.js";
+import { newContinuationKey } from "./ids.js";
+/** Wait between claim retries while another holder has the lease. */
+export const CLAIM_RETRY_DELAY_MS = 250;
+/**
+ * Give up waiting for the lease after this long — two full lease TTLs,
+ * so a dead holder's expiry (~30s) is always survived with margin.
+ */
+export const CLAIM_WAIT_TIMEOUT_MS = 2 * LEASE_TTL_MS;
+export class LedgerServing {
+    constructor(options) {
+        var _a, _b, _c, _d, _e, _f;
+        /**
+         * Per-ledger-session in-process serialization: local concurrent sends
+         * queue here instead of spinning claim retries against our own lease.
+         */
+        this.chains = new Map();
+        this.ledger = options.ledger;
+        this.deliverTurn = options.deliverTurn;
+        this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
+        this.heartbeatIntervalMs = (_b = options.heartbeatIntervalMs) !== null && _b !== void 0 ? _b : HEARTBEAT_INTERVAL_MS;
+        this.claimRetryDelayMs = (_c = options.claimRetryDelayMs) !== null && _c !== void 0 ? _c : CLAIM_RETRY_DELAY_MS;
+        this.claimWaitTimeoutMs = (_d = options.claimWaitTimeoutMs) !== null && _d !== void 0 ? _d : CLAIM_WAIT_TIMEOUT_MS;
+        this.clock = (_e = options.clock) !== null && _e !== void 0 ? _e : Date.now;
+        this.sleep = (_f = options.sleep) !== null && _f !== void 0 ? _f : ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /** Settle every queued and in-flight delivery. */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.allSettled([...this.chains.values()]);
+        });
+    }
+    /**
+     * Ledger-mode `send`: resolve the session identity, wait for the
+     * lease (in-process queue first, then cross-pod claim retries), run
+     * the turn, commit. Resolves with the engine session handle after the
+     * commit released the lease.
+     */
+    deliver(channelId, message, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const continuationToken = (_a = options.continuationToken) !== null && _a !== void 0 ? _a : newContinuationKey();
+            const ensured = yield this.ledger.ensureSession(`${channelId}/${continuationToken}`);
+            return this.enqueue(ensured.session.sessionId, () => this.serveOne(ensured.session.sessionId, {
+                channelId,
+                continuationToken,
+                message,
+                options,
+            }));
+        });
+    }
+    /** Chain a delivery behind the session's in-flight ones. */
+    enqueue(ledgerSessionId, run) {
+        var _a;
+        const prior = (_a = this.chains.get(ledgerSessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        const next = prior.then(() => run(), () => run());
+        this.chains.set(ledgerSessionId, next);
+        void next
+            .catch(() => { })
+            .finally(() => {
+            if (this.chains.get(ledgerSessionId) === next) {
+                this.chains.delete(ledgerSessionId);
+            }
+        });
+        return next;
+    }
+    /** claim (waiting) → resident turn → commit-release. */
+    serveOne(ledgerSessionId, request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const lease = yield this.claimWithWait(ledgerSessionId);
+            let fenced = false;
+            const heartbeat = setInterval(() => {
+                this.ledger.heartbeat(ledgerSessionId, lease.generation).then((result) => {
+                    if (!result.ok) {
+                        fenced = true;
+                    }
+                }, () => {
+                    // Transient KV failure: the next beat retries within the TTL.
+                });
+            }, this.heartbeatIntervalMs);
+            (_a = heartbeat.unref) === null || _a === void 0 ? void 0 : _a.call(heartbeat);
+            try {
+                let handle;
+                try {
+                    handle = yield this.deliverTurn(request);
+                    yield handle.waitForCompletion();
+                }
+                catch (error) {
+                    // The turn never committed; free the session for the next
+                    // delivery instead of making it wait out the TTL. A fenced
+                    // holder's release is a no-op.
+                    yield this.ledger
+                        .release(ledgerSessionId, lease.generation)
+                        .catch(() => { });
+                    throw error;
+                }
+                if (fenced) {
+                    // A new holder took over mid-turn (our lease lapsed). Discard:
+                    // committing would fence anyway, and warm state is now stale.
+                    this.logger(`[ledger] session ${ledgerSessionId} fenced mid-turn (generation ${lease.generation}); discarding without commit`);
+                    throw new LedgerFencedError(`deliver(${ledgerSessionId}): fenced mid-turn at generation ${lease.generation}`);
+                }
+                yield this.ledger.commit(ledgerSessionId, {
+                    generation: lease.generation,
+                    expectedHead: lease.head,
+                    commitId: randomUUID(),
+                });
+                return handle;
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+        });
+    }
+    /**
+     * Claim the lease, waiting out another holder with bounded retries.
+     * The common waits are short: our own pod's deliveries never reach
+     * here concurrently (the in-process chain serializes them), so a held
+     * lease means another pod is serving — usually for one turn — or died
+     * (expiry unblocks us at ~30s).
+     */
+    claimWithWait(ledgerSessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const start = this.clock();
+            for (;;) {
+                const claim = yield this.ledger.claim(ledgerSessionId);
+                if (claim.claimed) {
+                    return { generation: claim.lease.generation, head: claim.head };
+                }
+                if (this.clock() - start >= this.claimWaitTimeoutMs) {
+                    throw new Error(`ledger serving: session ${ledgerSessionId} is still leased by ${claim.holder} after ${this.claimWaitTimeoutMs}ms; giving up on this delivery`);
+                }
+                yield this.sleep(this.claimRetryDelayMs);
+            }
+        });
+    }
+}
+/** Mint the lease holder id for this process. */
+export function newLedgerPodId() {
+    return `pod_${randomBytes(6).toString("hex")}`;
+}

package/dist/internal/listen-port.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bind an HTTP server to a port, with a clear next-port path when 3000 (or
+ * whatever was requested) is already taken — a common onboarding failure.
+ */
+import type { Server } from "node:http";
+/** Default listen port for `serve` / `dev` when `--port` is omitted. */
+export declare const DEFAULT_SERVE_PORT = 3000;
+export declare function isAddrInUse(error: unknown): boolean;
+export declare function formatPortInUseHint(port: number): string;
+/**
+ * `server.listen` with fallback when the caller used the default port.
+ * Explicit `--port N` (including `0`) fails immediately with a next-port hint.
+ */
+export declare function listenHttpServer(args: {
+    server: Server;
+    host: string;
+    port: number;
+    /** True when the caller passed `port` (including 0); skip fallback. */
+    portWasExplicit: boolean;
+    logger: (line: string) => void;
+}): Promise<number>;
+//# sourceMappingURL=listen-port.d.ts.map

package/dist/internal/listen-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-port.d.ts","sourceRoot":"","sources":["../../src/internal/listen-port.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAKvC,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOnD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB"}

package/dist/internal/listen-port.js

@@ -0,0 +1,77 @@
+/**
+ * Bind an HTTP server to a port, with a clear next-port path when 3000 (or
+ * whatever was requested) is already taken — a common onboarding failure.
+ */
+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 { once } from "node:events";
+import { CLI_COMMAND_NAME } from "./distribution.js";
+/** Default listen port for `serve` / `dev` when `--port` is omitted. */
+export const DEFAULT_SERVE_PORT = 3000;
+/** How many ports above the default to try when the default is taken. */
+const DEFAULT_PORT_FALLBACK_SPAN = 20;
+export function isAddrInUse(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EADDRINUSE");
+}
+export function formatPortInUseHint(port) {
+    const next = port === 0 ? 3001 : port + 1;
+    return (`port ${port} is already in use. ` +
+        `Try \`${CLI_COMMAND_NAME} dev --port ${next}\` or \`--port 0\` for any free port.`);
+}
+/**
+ * `server.listen` with fallback when the caller used the default port.
+ * Explicit `--port N` (including `0`) fails immediately with a next-port hint.
+ */
+export function listenHttpServer(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { server, host, logger } = args;
+        const startPort = args.port;
+        if (args.portWasExplicit || startPort === 0) {
+            try {
+                server.listen(startPort, host);
+                yield once(server, "listening");
+            }
+            catch (error) {
+                if (isAddrInUse(error)) {
+                    throw new Error(formatPortInUseHint(startPort));
+                }
+                throw error;
+            }
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                throw new Error("server listening without an address");
+            }
+            return address.port;
+        }
+        const last = startPort + DEFAULT_PORT_FALLBACK_SPAN;
+        for (let port = startPort; port <= last; port++) {
+            try {
+                server.listen(port, host);
+                yield once(server, "listening");
+                if (port !== startPort) {
+                    logger(`[agent-sdk] port ${startPort} in use; listening on ${port} instead (pass --port to pick)`);
+                }
+                return port;
+            }
+            catch (error) {
+                if (!isAddrInUse(error)) {
+                    throw error;
+                }
+                if (port === last) {
+                    throw new Error(formatPortInUseHint(port));
+                }
+            }
+        }
+        throw new Error(formatPortInUseHint(last));
+    });
+}

package/dist/internal/mcp-oauth.d.ts

@@ -78,7 +78,18 @@ export type OAuthCallbackResult = {
     code: string;
     state?: string;
 };
-export declare function waitForMcpOAuthCallback(args?: {
+/**
+ * Deliberately not `@anysphere/mcp-core/oauth/loopback`, which is the canonical
+ * implementation every other Cursor surface shares. `@cursor/july` publishes to
+ * public npm with no private workspace dependencies, and its OAuth state is a
+ * bare UUID rather than the payload that module's validator expects.
+ *
+ * Nothing here reads Statsig, so this listener is outside
+ * `unified_mcp_loopback`: turning that gate off restores the other surfaces'
+ * original servers but leaves this one, and its state check, in place.
+ */
+export declare function waitForMcpOAuthCallback(args: {
+    authorizationUrl: string;
     port?: number;
     path?: string;
     timeoutMs?: number;

package/dist/internal/mcp-oauth.d.ts.map

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

package/dist/internal/mcp-oauth.js

@@ -307,12 +307,23 @@ export function createHostMcpOAuthProvider(args) {
         });
     });
 }
+/**
+ * Deliberately not `@anysphere/mcp-core/oauth/loopback`, which is the canonical
+ * implementation every other Cursor surface shares. `@cursor/july` publishes to
+ * public npm with no private workspace dependencies, and its OAuth state is a
+ * bare UUID rather than the payload that module's validator expects.
+ *
+ * Nothing here reads Statsig, so this listener is outside
+ * `unified_mcp_loopback`: turning that gate off restores the other surfaces'
+ * original servers but leaves this one, and its state check, in place.
+ */
 export function waitForMcpOAuthCallback(args) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
-        const port = (_a = args === null || args === void 0 ? void 0 : args.port) !== null && _a !== void 0 ? _a : MCP_OAUTH_CALLBACK_PORT;
-        const path = (_b = args === null || args === void 0 ? void 0 : args.path) !== null && _b !== void 0 ? _b : MCP_OAUTH_CALLBACK_PATH;
-        const timeoutMs = (_c = args === null || args === void 0 ? void 0 : args.timeoutMs) !== null && _c !== void 0 ? _c : 5 * 60 * 1000;
+        const port = (_a = args.port) !== null && _a !== void 0 ? _a : MCP_OAUTH_CALLBACK_PORT;
+        const path = (_b = args.path) !== null && _b !== void 0 ? _b : MCP_OAUTH_CALLBACK_PATH;
+        const timeoutMs = (_c = args.timeoutMs) !== null && _c !== void 0 ? _c : 5 * 60 * 1000;
+        const expectedState = new URL(args.authorizationUrl).searchParams.get("state");
         return new Promise((resolve, reject) => {
             let done = false;
             const finish = (result, error) => {
@@ -344,6 +355,17 @@ export function waitForMcpOAuthCallback(args) {
                 const code = url.searchParams.get("code");
                 const oauthError = url.searchParams.get("error");
                 const state = (_b = url.searchParams.get("state")) !== null && _b !== void 0 ? _b : undefined;
+                // Without this, any page that can reach the loopback port during a login
+                // can inject its own authorization code into the exchange. Ignore what is
+                // not ours rather than failing the login: treating a stray request as
+                // fatal would let any page cancel a login, and free the port for someone
+                // else to bind before the real callback arrives.
+                if (state !== (expectedState !== null && expectedState !== void 0 ? expectedState : undefined)) {
+                    res
+                        .writeHead(404, { "content-type": "text/html; charset=utf-8" })
+                        .end("<!doctype html><html><body><h1>Not found</h1></body></html>");
+                    return;
+                }
                 if (code) {
                     res
                         .writeHead(200, { "content-type": "text/html; charset=utf-8" })