@cursor/july 0.1.17 → 0.1.18

package/src/internal/sdk-runner.ts

@@ -86,16 +86,90 @@ export interface CursorSdkRunnerOptions {
   logger?: (line: string) => void;
 }
 
+/**
+ * How long one SDK agent handle (and the Connect transport inside it) may be
+ * reused before the runner retires it.
+ *
+ * The transport exchanges the account API key for a short-lived access token
+ * (`SessionType.API_KEY_TOKEN`, 60 minutes) once per handle, and has no
+ * reliable refresh: an Unauthenticated rejection on the agent's streaming RPC
+ * surfaces while the stream is being read — outside the transport's
+ * request-time 401 retry — so an expired token gets replayed on every
+ * subsequent turn until the handle is rebuilt. Long-lived sessions (watch
+ * wakes, crons) hit this at the ~60 minute mark and then fail forever.
+ * Retiring the handle comfortably before the token can expire keeps them
+ * healthy: `Agent.resume` rehydrates the same conversation from the runner
+ * store on a fresh transport, so recycling costs only transport warmth.
+ */
+const MAX_AGENT_HANDLE_AGE_MS = 45 * 60 * 1000;
+
+interface CachedAgentHandle {
+  agent: Promise<SDKAgent>;
+  openedAtMs: number;
+}
+
+/**
+ * The backend's `NotLoggedIn` copy ("Authentication error" title, "try
+ * logging out and back in." detail) as it surfaces through SDK RunResults.
+ * Deliberately narrow: this gates a one-shot in-place retry, and matching
+ * broader error text would retry turns that a fresh transport cannot fix.
+ */
+export function isAuthErrorMessage(message: string | undefined): boolean {
+  if (message === undefined) {
+    return false;
+  }
+  return /authentication error|try logging out and back in/i.test(message);
+}
+
 export class CursorSdkRunner implements AgentRunner {
-  private readonly agents = new Map<string, Promise<SDKAgent>>();
+  private readonly agents = new Map<string, CachedAgentHandle>();
   private readonly stores = new Map<string, Promise<LocalAgentStore>>();
   private readonly prewarmReleases: Array<() => Promise<void>> = [];
 
   constructor(private readonly options: CursorSdkRunnerOptions = {}) {}
 
   async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    let sawUpdate = false;
+    const tracked: RunnerTurnRequest = {
+      ...request,
+      onUpdate: (update) => {
+        sawUpdate = true;
+        return request.onUpdate(update);
+      },
+    };
+    const outcome = await this.runTurnAttempt(tracked);
+    if (
+      outcome.status !== "error" ||
+      !isAuthErrorMessage(outcome.errorMessage) ||
+      sawUpdate ||
+      request.isFirstTurn ||
+      request.signal?.aborted === true
+    ) {
+      return outcome;
+    }
+    // The turn died on an authentication failure before producing any output
+    // — the signature of a handle whose exchanged access token expired (the
+    // failed attempt already evicted it). Retrying once on a fresh handle is
+    // safe here because nothing streamed and no tool ran. First turns are
+    // excluded: their token was exchanged moments ago, so the credential
+    // itself is the problem and a retry cannot succeed.
+    this.log(
+      `[agentkit] session ${request.sessionId}: retrying the turn on a fresh SDK agent handle after an authentication failure`
+    );
+    try {
+      return await this.runTurnAttempt(tracked);
+    } catch {
+      // The retry was best effort; report the original failure.
+      return outcome;
+    }
+  }
+
+  private async runTurnAttempt(
+    request: RunnerTurnRequest
+  ): Promise<TurnOutcome> {
+    const agentPromise = this.getAgent(request);
     try {
-      const agent = await this.getAgent(request);
+      const agent = await agentPromise;
       const run = await agent.send(request.prompt, {
         onDelta: async ({ update }) => {
           try {
@@ -141,14 +215,24 @@ export class CursorSdkRunner implements AgentRunner {
       }
       try {
         const result = await run.wait();
-        return toTurnOutcome(result);
+        const outcome = toTurnOutcome(result);
+        if (outcome.status === "error") {
+          // An error result usually means the handle's transport is poisoned
+          // — most often a cached access token that aged past its 60-minute
+          // lifetime and gets replayed on every request (stream failures
+          // bypass the transport's 401 retry). Retire the handle so the next
+          // attempt resumes the conversation from the store on a fresh
+          // transport instead of failing every turn until a restart.
+          this.evictAgent(request.sessionId, agentPromise);
+        }
+        return outcome;
       } finally {
         signal?.removeEventListener("abort", onAbort);
       }
     } catch (error) {
       // Drop the cached agent so a dead Connect/HTTP2 session cannot poison
       // the next turn (terminal/shell overflow often kills the transport).
-      this.agents.delete(request.sessionId);
+      this.evictAgent(request.sessionId, agentPromise);
       throw error;
     }
   }
@@ -178,7 +262,9 @@ export class CursorSdkRunner implements AgentRunner {
   async dispose(): Promise<void> {
     const releases = this.prewarmReleases.splice(0);
     await Promise.allSettled(releases.map((release) => release()));
-    const agents = await Promise.allSettled([...this.agents.values()]);
+    const agents = await Promise.allSettled(
+      [...this.agents.values()].map((handle) => handle.agent)
+    );
     this.agents.clear();
     for (const settled of agents) {
       if (settled.status === "fulfilled") {
@@ -188,17 +274,49 @@ export class CursorSdkRunner implements AgentRunner {
   }
 
   private getAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
-    let agentPromise = this.agents.get(request.sessionId);
-    if (agentPromise === undefined) {
-      agentPromise = this.openAgent(request).catch((error) => {
-        this.agents.delete(request.sessionId);
-        throw error;
-      });
-      this.agents.set(request.sessionId, agentPromise);
+    const cached = this.agents.get(request.sessionId);
+    if (cached !== undefined) {
+      const ageMs = Date.now() - cached.openedAtMs;
+      if (ageMs < MAX_AGENT_HANDLE_AGE_MS) {
+        return cached.agent;
+      }
+      // Past this age the handle's exchanged access token could expire
+      // mid-turn. Retire it and reopen below on a fresh transport.
+      this.log(
+        `[agentkit] session ${request.sessionId}: recycling the SDK agent handle after ${Math.round(ageMs / 60_000)} min so the turn runs on a fresh access token`
+      );
+      this.evictAgent(request.sessionId, cached.agent);
     }
+    const agentPromise = this.openAgent(request).catch((error) => {
+      // Nothing opened, so there is no handle to close — just free the slot.
+      this.agents.delete(request.sessionId);
+      throw error;
+    });
+    this.agents.set(request.sessionId, {
+      agent: agentPromise,
+      openedAtMs: Date.now(),
+    });
     return agentPromise;
   }
 
+  /**
+   * Drop a cached handle and close it best-effort to release its transport
+   * and executor lease. Identity-checked so a turn that lost a race with a
+   * newer open cannot evict the replacement handle.
+   */
+  private evictAgent(sessionId: string, agent: Promise<SDKAgent>): void {
+    const cached = this.agents.get(sessionId);
+    if (cached === undefined || cached.agent !== agent) {
+      return;
+    }
+    this.agents.delete(sessionId);
+    void cached.agent.then((sdkAgent) => sdkAgent.close()).catch(() => {});
+  }
+
+  private log(line: string): void {
+    (this.options.logger ?? (() => {}))(line);
+  }
+
   private requireApiKey(): string {
     const apiKey = this.options.apiKey ?? process.env.CURSOR_API_KEY;
     if (apiKey === undefined || apiKey.trim() === "") {
@@ -274,7 +392,7 @@ export class CursorSdkRunner implements AgentRunner {
       // conversation under the same id beats failing this thread's turns
       // forever ("Agent … not found" on every follow-up). The channel's
       // warm-turn prompt context re-hydrates the thread history.
-      (this.options.logger ?? (() => {}))(
+      this.log(
         `[agentkit] no stored conversation for ${agentId} on this host; starting a fresh one`
       );
       return Agent.create({ ...options, agentId });

package/src/internal/server.ts

@@ -421,6 +421,8 @@ export async function startServer(
       cancel: (id, reason) => reminderRunner.cancel(id, reason),
       cancelForContinuation: (token, reason) =>
         reminderRunner.cancelForContinuation(token, reason),
+      rekeyContinuation: (channelId, oldToken, newToken) =>
+        reminderRunner.rekeyContinuation(channelId, oldToken, newToken),
       dispatch: (id) => reminderRunner.dispatch(id),
     });
     engine.setEvals({

package/src/internal/session-engine.ts

@@ -2148,10 +2148,24 @@ export class SessionEngine {
     sessionId: string,
     token: string | null
   ): Promise<void> {
+    const previous = await this.sessions.get(sessionId);
     await this.updateRecord(sessionId, (current) => ({
       ...current,
       continuationKey: token,
     }));
+    // Keep armed reminders addressed at the conversation across rotation
+    // (the built-in HTTP channel rotates after every follow-up).
+    if (
+      previous?.continuationKey != null &&
+      token !== null &&
+      token !== previous.continuationKey
+    ) {
+      await this.reminderApi?.rekeyContinuation(
+        previous.channelId,
+        previous.continuationKey,
+        token
+      );
+    }
   }
 
   isTurnRunning(sessionId: string): boolean {

package/src/internal/slack-provision-client.ts

@@ -9,9 +9,10 @@
  * The endpoints are gated on the `agent_serve_slack_provisioning` Statsig
  * gate and 404 when it is off — the error mapping says so instead of
  * "not found". Expected provisioning failures carry a stable JSON `code`
- * (`not_connected`, `insufficient_scopes`, `app_conflict`,
- * `app_cap_reached`, `ratelimited`, `invalid_app_id`, …) which flows
- * through on {@link SlackProvisionApiError.code} so the CLI can branch.
+ * (`not_connected`, `insufficient_scopes`, `manager_reauth_required`,
+ * `app_conflict`, `app_cap_reached`, `ratelimited`, `invalid_app_id`, …)
+ * which flows through on {@link SlackProvisionApiError.code} so the CLI
+ * can branch.
  */
 
 import { z } from "zod";
@@ -21,6 +22,8 @@ export type SlackAppEnv = "dev" | "prod";
 /** One manager-connected Slack workspace from `GET /status`. */
 export interface SlackConnectedWorkspace {
   slackTeamId: string;
+  /** Workspace name; absent on older backends, null on pre-existing rows. */
+  slackTeamName?: string | null;
   slackUserId: string;
   connectedAt: string;
 }
@@ -113,6 +116,7 @@ const statusResponseSchema = z
       z
         .object({
           slackTeamId: z.string(),
+          slackTeamName: z.string().nullish(),
           slackUserId: z.string(),
           connectedAt: z.string(),
         })

package/src/types.ts

@@ -198,6 +198,29 @@ export interface AgentConfig {
    * Engine-wide turn admission limits. See {@link AgentConcurrencyOptions}.
    */
   concurrency?: AgentConcurrencyOptions;
+  /**
+   * Framework-provided model-facing tools, opted in per capability. See
+   * {@link BuiltinToolsConfig}.
+   */
+  builtinTools?: BuiltinToolsConfig;
+}
+
+/**
+ * Built-in tools on {@link AgentConfig.builtinTools}. Each enabled
+ * capability materializes as ordinary server tools at discovery time, so
+ * turns, direct calls, `info`, and the playground treat them like authored
+ * tools. Authored tools with the same name win (with a warning), and none
+ * of them run on cloud turns (server tools are local-runtime only).
+ */
+export interface BuiltinToolsConfig {
+  /**
+   * Reminder tools bound to the current conversation, over
+   * {@link HostContext.reminders}: `reminders_create`, `reminders_list`,
+   * and `reminders_cancel` (the name the framework's reminder fire prompt
+   * tells the model to call when a stop condition is met). Sessions
+   * without a continuation key cannot arm reminders.
+   */
+  reminders?: boolean;
 }
 
 /**
@@ -1722,6 +1745,16 @@ export interface ReminderHostApi {
     continuationToken: string,
     reason: string
   ): Promise<number>;
+  /**
+   * Re-key armed reminders after a channel rotates a session's continuation
+   * token, so earlier reminders keep waking the conversation. The engine
+   * calls this from `setContinuationToken`; channels rarely need to.
+   */
+  rekeyContinuation(
+    channelId: string,
+    oldToken: string,
+    newToken: string
+  ): Promise<number>;
   /**
    * Fire immediately (dev / hillclimb).
    * `outcome` is `"noop"` when already firing or not armed.