@cursor/july 0.1.39 → 0.1.41

package/src/internal/init-project.ts

@@ -3,6 +3,7 @@
  */
 
 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 type { ModelSetting } from "../types.js";
@@ -104,6 +105,7 @@ export async function initProject(
         description: `agent project: ${name}`,
         scripts: {
           check: "tsc --noEmit",
+          dev: "agent-sdk dev",
         },
         dependencies: {
           [PACKAGE_NAME]: `^${packageVersion()}`,
@@ -256,6 +258,141 @@ export async function installScaffoldDependencies(
   };
 }
 
+export interface LinkCliOntoPathOptions {
+  stdio?: "inherit" | "pipe";
+  runner?: (args: {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdio: "inherit" | "pipe";
+  }) => Promise<{ exitCode: number; stderr: string }>;
+  /** Test seam — absolute path of the linked CLI when present. */
+  whichImpl?: (
+    command: string
+  ) => string | undefined | Promise<string | undefined>;
+}
+
+export interface LinkCliOntoPathResult {
+  ok: boolean;
+  exitCode: number;
+  stderr: string;
+  /** Absolute path to the linked `agent-sdk` when it resolves on PATH. */
+  resolvedPath?: string;
+}
+
+/**
+ * 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 async function linkCliOntoPath(
+  rootDir: string,
+  options: LinkCliOntoPathOptions = {}
+): Promise<LinkCliOntoPathResult> {
+  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 = options.stdio ?? "inherit";
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const args = ["install", "--global", "--no-fund", "--no-audit", packageDir];
+  const runner = options.runner ?? defaultNpmInstallRunner;
+  const result = await runner({ command, args, cwd: rootDir, stdio });
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      exitCode: result.exitCode,
+      stderr: result.stderr,
+    };
+  }
+  const whichImpl = options.whichImpl ?? resolveLinkedCli;
+  const resolvedPath = await 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. */
+async function resolveLinkedCli(
+  commandName: string
+): Promise<string | undefined> {
+  const prefix = await npmGlobalPrefix();
+  if (prefix === undefined) {
+    return whichOnPath(commandName);
+  }
+  const binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".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;
+}
+
+async function npmGlobalPrefix(): Promise<string | undefined> {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  return await new Promise((resolvePromise) => {
+    const child = spawn(command, ["prefix", "-g"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: process.env,
+    });
+    let out = "";
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      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: string): string | undefined {
+  const pathEnv = process.env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".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;
+}
+
 async function defaultNpmInstallRunner(args: {
   command: string;
   args: string[];
@@ -323,6 +460,11 @@ export interface InitNextStepsOptions {
    * `login` (used for `--json` and when an interactive login attempt failed).
    */
   signedIn: boolean;
+  /**
+   * True when `agent-sdk` resolves on PATH after init linked the CLI.
+   * When false, next steps include a PATH export for `node_modules/.bin`.
+   */
+  cliOnPath: boolean;
   /** Override TTY color detection (tests / `--json` callers). */
   color?: boolean;
 }
@@ -415,6 +557,12 @@ function initNextStepEntries(options: InitNextStepsOptions): Array<{
   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`,
@@ -436,6 +584,7 @@ export function initNextCommands(options: {
   rootDir: string;
   cwd: string;
   signedIn: boolean;
+  cliOnPath: boolean;
 }): string[] {
   return initNextStepEntries(options).map((step) => step.command);
 }
@@ -448,10 +597,10 @@ export function printInitGuide(): void {
   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/src/internal/ledger-serving.ts

@@ -0,0 +1,240 @@
+/**
+ * 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 { randomBytes, randomUUID } from "node:crypto";
+import type { SessionLedger } from "../ledger/session-ledger.js";
+import {
+  HEARTBEAT_INTERVAL_MS,
+  LEASE_TTL_MS,
+  LedgerFencedError,
+} from "../ledger/session-ledger.js";
+import type { ChannelSession, SendMessageOptions } from "../types.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: number = 2 * LEASE_TTL_MS;
+
+/** 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 class LedgerServing {
+  private readonly ledger: SessionLedger;
+  private readonly deliverTurn: LedgerServingOptions["deliverTurn"];
+  private readonly logger: (line: string) => void;
+  private readonly heartbeatIntervalMs: number;
+  private readonly claimRetryDelayMs: number;
+  private readonly claimWaitTimeoutMs: number;
+  private readonly clock: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  /**
+   * Per-ledger-session in-process serialization: local concurrent sends
+   * queue here instead of spinning claim retries against our own lease.
+   */
+  private readonly chains = new Map<string, Promise<unknown>>();
+
+  constructor(options: LedgerServingOptions) {
+    this.ledger = options.ledger;
+    this.deliverTurn = options.deliverTurn;
+    this.logger = options.logger ?? (() => {});
+    this.heartbeatIntervalMs =
+      options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    this.claimRetryDelayMs = options.claimRetryDelayMs ?? CLAIM_RETRY_DELAY_MS;
+    this.claimWaitTimeoutMs =
+      options.claimWaitTimeoutMs ?? CLAIM_WAIT_TIMEOUT_MS;
+    this.clock = options.clock ?? Date.now;
+    this.sleep =
+      options.sleep ??
+      ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+
+  /** Settle every queued and in-flight delivery. */
+  async close(): Promise<void> {
+    await 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.
+   */
+  async deliver(
+    channelId: string,
+    message: string,
+    options: LedgerDeliverOptions
+  ): Promise<ChannelSession> {
+    const continuationToken = options.continuationToken ?? newContinuationKey();
+    const ensured = await 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. */
+  private enqueue(
+    ledgerSessionId: string,
+    run: () => Promise<ChannelSession>
+  ): Promise<ChannelSession> {
+    const prior = this.chains.get(ledgerSessionId) ?? 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. */
+  private async serveOne(
+    ledgerSessionId: string,
+    request: LedgerTurnRequest
+  ): Promise<ChannelSession> {
+    const lease = await 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);
+    heartbeat.unref?.();
+    try {
+      let handle: ChannelSession;
+      try {
+        handle = await this.deliverTurn(request);
+        await 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.
+        await 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}`
+        );
+      }
+      await 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).
+   */
+  private async claimWithWait(
+    ledgerSessionId: string
+  ): Promise<{ generation: number; head: number }> {
+    const start = this.clock();
+    for (;;) {
+      const claim = await 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`
+        );
+      }
+      await this.sleep(this.claimRetryDelayMs);
+    }
+  }
+}
+
+/** Mint the lease holder id for this process. */
+export function newLedgerPodId(): string {
+  return `pod_${randomBytes(6).toString("hex")}`;
+}

package/src/internal/listen-port.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 { once } from "node:events";
+import type { Server } from "node:http";
+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: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "EADDRINUSE"
+  );
+}
+
+export function formatPortInUseHint(port: number): string {
+  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 async 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> {
+  const { server, host, logger } = args;
+  const startPort = args.port;
+  if (args.portWasExplicit || startPort === 0) {
+    try {
+      server.listen(startPort, host);
+      await 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);
+      await 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/src/internal/mcp-oauth.ts

@@ -385,14 +385,28 @@ export type OAuthCallbackResult = {
   state?: string;
 };
 
-export async 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 async function waitForMcpOAuthCallback(args: {
+  authorizationUrl: string;
   port?: number;
   path?: string;
   timeoutMs?: number;
 }): Promise<OAuthCallbackResult> {
-  const port = args?.port ?? MCP_OAUTH_CALLBACK_PORT;
-  const path = args?.path ?? MCP_OAUTH_CALLBACK_PATH;
-  const timeoutMs = args?.timeoutMs ?? 5 * 60 * 1000;
+  const port = args.port ?? MCP_OAUTH_CALLBACK_PORT;
+  const path = args.path ?? MCP_OAUTH_CALLBACK_PATH;
+  const timeoutMs = args.timeoutMs ?? 5 * 60 * 1000;
+  const expectedState = new URL(args.authorizationUrl).searchParams.get(
+    "state"
+  );
 
   return new Promise((resolve, reject) => {
     let done = false;
@@ -428,6 +442,17 @@ export async function waitForMcpOAuthCallback(args?: {
       const code = url.searchParams.get("code");
       const oauthError = url.searchParams.get("error");
       const state = url.searchParams.get("state") ?? 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 ?? 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" })