@cursor/july 0.1.12 → 0.1.15

package/src/internal/run-client.ts

@@ -6,7 +6,11 @@
  * compact {@link Trajectory} plus the continuation token for follow-ups.
  */
 
-import type { SessionEvent, SessionPurpose } from "../types.js";
+import type {
+  AgentCloudOptions,
+  SessionEvent,
+  SessionPurpose,
+} from "../types.js";
 import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
 import { buildTrajectory, type Trajectory } from "./trajectory.js";
 
@@ -24,6 +28,8 @@ export interface RunClientOptions extends RequestAuth {
   baseUrl: string;
   /** Abort a hung turn. */
   timeoutMs?: number;
+  /** External cancel (combined with {@link timeoutMs} when both are set). */
+  signal?: AbortSignal;
   /** Called for each stream event as it arrives (for CLI progress). */
   onEvent?: (event: SessionEvent) => void;
   /**
@@ -61,6 +67,8 @@ export async function runSession(
     workspaceDir?: string;
     /** Applied only when creating a new session (first message). */
     workspaceFiles?: Record<string, string>;
+    /** Applied only when creating a new session (first message). */
+    cloud?: AgentCloudOptions;
   }
 ): Promise<RunSessionResult> {
   if (options.messages.length === 0) {
@@ -86,11 +94,13 @@ export async function runSession(
       startIndex: sessionId === undefined ? 0 : nextEventIndex,
       auth,
       timeoutMs: options.timeoutMs,
+      signal: options.signal,
       onEvent: options.onEvent,
       purpose: sessionId === undefined ? options.purpose : undefined,
       workspaceDir: sessionId === undefined ? options.workspaceDir : undefined,
       workspaceFiles:
         sessionId === undefined ? options.workspaceFiles : undefined,
+      cloud: sessionId === undefined ? options.cloud : undefined,
     });
     sessionId = turn.sessionId;
     continuationToken = turn.continuationToken;
@@ -127,9 +137,11 @@ interface OneTurnArgs {
   purpose?: SessionPurpose;
   workspaceDir?: string;
   workspaceFiles?: Record<string, string>;
+  cloud?: AgentCloudOptions;
   startIndex: number;
   auth?: RequestAuth;
   timeoutMs?: number;
+  signal?: AbortSignal;
   onEvent?: (event: SessionEvent) => void;
 }
 
@@ -155,6 +167,9 @@ async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
     if (args.workspaceFiles !== undefined) {
       body.workspaceFiles = args.workspaceFiles;
     }
+    if (args.cloud !== undefined) {
+      body.cloud = args.cloud;
+    }
     const created = await postJson(
       args.baseUrl,
       "/v1/session",
@@ -193,6 +208,7 @@ async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
     startIndex: args.startIndex,
     auth: args.auth,
     timeoutMs: args.timeoutMs,
+    signal: args.signal,
     onEvent: args.onEvent,
   });
 
@@ -212,9 +228,20 @@ async function collectStream(args: {
   startIndex: number;
   auth?: RequestAuth;
   timeoutMs?: number;
+  signal?: AbortSignal;
   onEvent?: (event: SessionEvent) => void;
 }): Promise<SessionEvent[]> {
   const controller = new AbortController();
+  const onExternalAbort = (): void => {
+    controller.abort();
+  };
+  if (args.signal !== undefined) {
+    if (args.signal.aborted) {
+      controller.abort();
+    } else {
+      args.signal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+  }
   const timer =
     args.timeoutMs === undefined
       ? undefined
@@ -271,6 +298,9 @@ async function collectStream(args: {
     return events;
   } catch (error) {
     if (error instanceof Error && error.name === "AbortError") {
+      if (args.signal?.aborted) {
+        throw new Error("cancelled");
+      }
       throw new RunSessionTimeoutError(
         `turn timed out after ${args.timeoutMs ?? "?"}ms (session ${args.sessionId})`,
         args.sessionId
@@ -278,6 +308,7 @@ async function collectStream(args: {
     }
     throw error;
   } finally {
+    args.signal?.removeEventListener("abort", onExternalAbort);
     if (timer !== undefined) {
       clearTimeout(timer);
     }

package/src/internal/server.ts

@@ -21,6 +21,7 @@ import {
   getGithubCursorAccountRuntime,
   parseCursorGithubRepoScope,
   resolveCursorGithubPermissions,
+  resolveCursorGithubProxyUrl,
 } from "../channels/github/cursor-account.js";
 import { findGitHubChannelTargets } from "../channels/github/forward.js";
 import {
@@ -80,7 +81,9 @@ import {
 import {
   EvalRunConflictError,
   EvalRunEmptyError,
+  EvalRunNotRunningError,
   EvalRunStore,
+  EvalRunUnknownError,
 } from "./eval-run-store.js";
 import {
   collectGitHubTriggerTargets,
@@ -251,8 +254,35 @@ export async function startServer(
       logger,
     });
     cursorGithubCredentials = provider;
-    for (const target of cursorGithubTargets) {
-      target.accountRuntime.credentials.bind(() => provider.getToken());
+    const githubProxyUrl =
+      options.cursorGithubProxy === true
+        ? resolveCursorGithubProxyUrl(cursorEventsAuth.baseUrl)
+        : undefined;
+    if (githubProxyUrl !== undefined) {
+      // Proxy mode: channel Octokit calls carry the Cursor API key to the
+      // backend forwarder, which swaps in the installation token server-side
+      // and logs every call with per-deployment attribution. The provider
+      // still runs so child `gh` processes get a `GH_TOKEN` lease (v1).
+      const proxyTransport = {
+        apiBaseUrl: githubProxyUrl,
+        headers: {
+          "x-cursor-github-repos": cursorGithubConfig.scope.repos.join(","),
+          "x-cursor-github-permissions": cursorGithubConfig.scope.permissions,
+        },
+      };
+      for (const target of cursorGithubTargets) {
+        target.accountRuntime.credentials.bind(
+          async () => cursorEventsAuth.apiKey
+        );
+        target.accountRuntime.credentials.bindProxyTransport(proxyTransport);
+      }
+      logger(
+        `[agentkit] GitHub auth: channel API calls route through ${githubProxyUrl}`
+      );
+    } else {
+      for (const target of cursorGithubTargets) {
+        target.accountRuntime.credentials.bind(() => provider.getToken());
+      }
     }
   }
   const resolvedCursorGithubCredentials = cursorGithubCredentials;
@@ -392,6 +422,7 @@ export async function startServer(
       get: (runId) => evalRuns.get(runId),
       listRunsWithActive: () => evalRuns.listRunsWithActive(),
       start: (input) => evalRuns.start(input),
+      cancel: (runId) => evalRuns.cancel(runId),
     });
     const runtime: MountedRuntime = {
       slug,
@@ -1171,6 +1202,42 @@ function mountAgentRoutes(
       return jsonResponse(snap);
     },
   });
+  router.add({
+    method: "POST",
+    pattern: `${base}/v1/dev/evals/runs/:runId/cancel`,
+    auth: httpAuth,
+    handler: async (_request, ctx) => {
+      const runId = ctx.params.runId ?? "";
+      try {
+        const snap = await runtime.evalRuns.cancel(runId);
+        return jsonResponse(snap);
+      } catch (error) {
+        if (error instanceof EvalRunUnknownError) {
+          return jsonResponse(
+            { ok: false, error: "unknown_eval_run" },
+            { status: 404 }
+          );
+        }
+        if (error instanceof EvalRunNotRunningError) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: "eval_run_not_running",
+              runId: error.runId,
+              status: error.status,
+              message: error.message,
+            },
+            { status: 409 }
+          );
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return jsonResponse(
+          { ok: false, error: "eval_cancel_failed", message },
+          { status: 400 }
+        );
+      }
+    },
+  });
 
   if (dev) {
     router.add({

package/src/internal/session-engine.ts

@@ -2335,6 +2335,25 @@ export class SessionEngine {
     }
   }
 
+  /**
+   * Local session lookup with lazy restore by session id.
+   *
+   * `GET /v1/sessions` (cursor-hosted) can list durable rows that were not
+   * bulk-restored into `--state-root` (restore caps, `restore: "off"`, or
+   * eval Open-trace by id). Events/stream/follow-up must materialize that
+   * one session before answering, or the playground shows an empty timeline
+   * after redeploy.
+   */
+  async getOrRestoreSession(
+    sessionId: string
+  ): Promise<SessionRecord | undefined> {
+    const local = await this.sessions.get(sessionId);
+    if (local !== undefined) {
+      return local;
+    }
+    return this.restoreSessionById(sessionId);
+  }
+
   /**
    * Lazy restore: a continuation lookup missed locally, so ask the sink
    * for that one session and materialize it before resuming. Disk grows
@@ -2367,6 +2386,24 @@ export class SessionEngine {
     return pending;
   }
 
+  private restoreSessionById(
+    sessionId: string
+  ): Promise<SessionRecord | undefined> {
+    const storage = this.storage;
+    if (storage === undefined) {
+      return Promise.resolve(undefined);
+    }
+    const key = `id\u0000${sessionId}`;
+    let pending = this.restoreInFlight.get(key);
+    if (pending === undefined) {
+      pending = this.loadAndMaterializeById(storage, sessionId).finally(() =>
+        this.restoreInFlight.delete(key)
+      );
+      this.restoreInFlight.set(key, pending);
+    }
+    return pending;
+  }
+
   private async loadAndMaterializeByContinuation(
     storage: StorageCoordinator,
     channelId: string,
@@ -2380,10 +2417,31 @@ export class SessionEngine {
       // Definitive miss: the caller starts a fresh session under this token.
       return undefined;
     }
+    return this.materializeRestoredRecord(record);
+  }
+
+  private async loadAndMaterializeById(
+    storage: StorageCoordinator,
+    sessionId: string
+  ): Promise<SessionRecord | undefined> {
+    const record = await storage.getSessionById(sessionId);
+    if (record === undefined) {
+      return undefined;
+    }
+    return this.materializeRestoredRecord(record);
+  }
+
+  private async materializeRestoredRecord(
+    record: SessionRecord
+  ): Promise<SessionRecord> {
     const local = await this.sessions.get(record.sessionId);
     if (local !== undefined) {
       return local;
     }
+    const storage = this.storage;
+    if (storage === undefined) {
+      return record;
+    }
     const events = await storage.listSessionEvents(record.sessionId);
     await this.materializeSession(record, eventsNdjson(events));
     this.logger(

package/src/internal/storage-coordinator.ts

@@ -329,6 +329,36 @@ export class StorageCoordinator {
     return events;
   }
 
+  /**
+   * One saved session by id (lazy restore for playground Open-trace /
+   * events / stream after a host replacement). Sink errors **propagate**
+   * — same posture as {@link getSessionByContinuation}. A definitive miss
+   * (no row, or a write-only sink without `get`) resolves undefined.
+   */
+  async getSessionById(sessionId: string): Promise<SessionRecord | undefined> {
+    const get = this.definition.get;
+    if (get === undefined) {
+      return undefined;
+    }
+    if (typeof sessionId !== "string" || sessionId === "") {
+      return undefined;
+    }
+    const ctx = this.context("restore");
+    const record = (await get(
+      storageKeys.session(this.agentName, sessionId),
+      ctx
+    )) as SessionRecord | null | undefined;
+    if (record == null) {
+      return undefined;
+    }
+    if (record.sessionId !== sessionId) {
+      throw new Error(
+        `storage returned a session that does not match the requested id ${sessionId}`
+      );
+    }
+    return record;
+  }
+
   /**
    * One saved session by channel continuation key (lazy restore). Unlike
    * the startup reads, sink errors **propagate**: a failing store must
@@ -363,11 +393,8 @@ export class StorageCoordinator {
         `storage returned a malformed continuation entry for channel ${channelId}`
       );
     }
-    const record = (await get(
-      storageKeys.session(this.agentName, sessionId),
-      ctx
-    )) as SessionRecord | null | undefined;
-    if (record == null) {
+    const record = await this.getSessionById(sessionId);
+    if (record === undefined) {
       // Index entry without its record (e.g. the record write was shed
       // under at-most-once). The session is unrecoverable; treat as a miss
       // so the conversation can continue rather than failing forever.
@@ -380,7 +407,6 @@ export class StorageCoordinator {
     // mismatched row is a broken store, not a miss; treating it as a miss
     // would fork the continuation token onto a new session.
     if (
-      record.sessionId !== sessionId ||
       record.channelId !== channelId ||
       record.continuationKey !== continuationKey
     ) {

package/src/types.ts

@@ -1974,6 +1974,16 @@ export interface ServeOptions {
    * SSO/Okta proxy in front of the host).
    */
   allowAnonymousCursorGithub?: boolean;
+  /**
+   * Route `githubChannel({ cursorAccount })` API calls through the Cursor
+   * backend's GitHub forwarder (`/v0/github-proxy`) instead of minting raw
+   * installation tokens into this process. The backend logs and meters every
+   * call with per-deployment attribution. `AGENT_SERVE_GITHUB_PROXY_URL`
+   * overrides the forwarder base URL (default: the resolved Cursor API base
+   * URL + `/v0/github-proxy`). Child `gh` processes still use a minted
+   * `GH_TOKEN` lease (proxying `gh` is a follow-up).
+   */
+  cursorGithubProxy?: boolean;
   /**
    * Allow {@link allowAnonymous} together with
    * `defineConnection({ cursorAccount: true })`. Without this opt-in, `serve`