@cursor/july 0.1.17 → 0.1.19

package/src/internal/install-cursor-skills.ts

@@ -18,7 +18,7 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { packageRootDir } from "./distribution.js";
+import { CLI_COMMAND_NAME, packageRootDir } from "./distribution.js";
 import { stdoutPalette } from "./terminal-style.js";
 
 /** Monorepo-only skill; excluded from the published package. */
@@ -27,6 +27,9 @@ const SKIP_SKILL_DIRS = new Set(["operate"]);
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
 export const CURSOR_SKILLS_NAMESPACE = "agentkit";
 
+/** How long the `init` offer waits for an answer before skipping the install. */
+export const SKILL_PROMPT_TIMEOUT_MS = 45_000;
+
 export interface PackageSkill {
   /** Frontmatter `name` (e.g. agentkit-create-agent). */
   name: string;
@@ -115,6 +118,13 @@ export async function findMissingCursorSkills(options?: {
   return missing;
 }
 
+export interface SkillInstallResult {
+  /** Leaf dirs written. */
+  installed: string[];
+  /** Leaf dirs deleted because the package no longer ships them. */
+  removed: string[];
+}
+
 /**
  * Copy each skill directory into `skillsHome/agentkit/<leafDir>/`.
  * Always overwrites so a package upgrade refreshes local Cursor skills.
@@ -123,24 +133,13 @@ export async function findMissingCursorSkills(options?: {
 export async function installCursorSkills(
   skills: readonly PackageSkill[],
   skillsHome: string = cursorSkillsHome()
-): Promise<string[]> {
+): Promise<SkillInstallResult> {
   const namespaceDir = agentkitCursorSkillsDir(skillsHome);
   await mkdir(namespaceDir, { recursive: true });
 
-  const shippedLeaves = new Set(skills.map((skill) => skill.leafDir));
-  let existingLeaves: string[] = [];
-  try {
-    const entries = await readdir(namespaceDir, { withFileTypes: true });
-    existingLeaves = entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name);
-  } catch {
-    existingLeaves = [];
-  }
-  for (const leaf of existingLeaves) {
-    if (!shippedLeaves.has(leaf)) {
-      await rm(join(namespaceDir, leaf), { recursive: true, force: true });
-    }
+  const removed = await orphanLeaves(namespaceDir, skills);
+  for (const leaf of removed) {
+    await rm(join(namespaceDir, leaf), { recursive: true, force: true });
   }
 
   const installed: string[] = [];
@@ -155,7 +154,24 @@ export async function installCursorSkills(
     }
     installed.push(skill.leafDir);
   }
-  return installed;
+  return { installed, removed };
+}
+
+/** Installed leaf dirs the package no longer ships. Installing deletes these. */
+async function orphanLeaves(
+  namespaceDir: string,
+  skills: readonly PackageSkill[]
+): Promise<string[]> {
+  const shipped = new Set(skills.map((skill) => skill.leafDir));
+  let entries: Array<{ name: string; isDirectory: () => boolean }>;
+  try {
+    entries = await readdir(namespaceDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() && !shipped.has(entry.name))
+    .map((entry) => entry.name);
 }
 
 /** Drop monorepo `paths` globs and fix package doc links for ~/.cursor installs. */
@@ -191,20 +207,72 @@ function stripPathsFromFrontmatter(frontmatter: string): string {
   return out.join("\n");
 }
 
+export interface SkillInstallPlan {
+  shipped: PackageSkill[];
+  /** Resolved `~/.cursor/skills`, to install into. */
+  skillsHome: string;
+  /** Install target: `<skillsHome>/agentkit`. */
+  directory: string;
+  /** Leaf dirs the package ships. */
+  leaves: string[];
+  /** Nothing installed yet, so this is a fresh install rather than a refresh. */
+  firstInstall: boolean;
+  /** Installed leaf dirs the package dropped; installing deletes them. */
+  orphans: string[];
+}
+
+/** What an install would do, for the offer and for `install-skills`. */
+export async function planSkillInstall(options?: {
+  packageRoot?: string;
+  skillsHome?: string;
+}): Promise<SkillInstallPlan> {
+  const skillsHome = options?.skillsHome ?? cursorSkillsHome();
+  const directory = agentkitCursorSkillsDir(skillsHome);
+  const shipped = await listShippedPackageSkills(options?.packageRoot);
+  const missing = await findMissingCursorSkills({
+    packageRoot: options?.packageRoot,
+    skillsHome,
+  });
+  return {
+    shipped,
+    skillsHome,
+    directory,
+    leaves: shipped.map((skill) => skill.leafDir),
+    firstInstall: missing.length === shipped.length,
+    orphans: await orphanLeaves(directory, shipped),
+  };
+}
+
+/** `Installed 9 agentkit skills`, what it dropped, and where it went. */
+export function formatSkillInstall(
+  plan: SkillInstallPlan,
+  result: SkillInstallResult
+): string {
+  const noun = result.installed.length === 1 ? "skill" : "skills";
+  const verb = plan.firstInstall ? "Installed" : "Updated";
+  const lines = [`${verb} ${result.installed.length} agentkit ${noun}`];
+  if (result.removed.length > 0) {
+    lines.push(`  removed:  ${result.removed.join(", ")}`);
+  }
+  lines.push(`  location: ${plan.directory}`);
+  return `${lines.join("\n")}\n`;
+}
+
 export interface OfferInstallCursorSkillsOptions {
   /** Skip when false (non-TTY / `--json`). */
   interactive?: boolean;
   packageRoot?: string;
   skillsHome?: string;
-  /** Injected yes/no for tests. */
-  confirm?: (question: string) => Promise<boolean>;
+  /** Injected yes/no for tests. `undefined` means the prompt went unanswered. */
+  confirm?: (question: string) => Promise<boolean | undefined>;
   out?: (text: string) => void;
 }
 
 /**
  * On a TTY, offer to install/update every shipped package skill into
  * ~/.cursor/skills/agentkit (always overwriting). No-op when non-interactive
- * or the package ships no skills.
+ * or the package ships no skills. An unanswered prompt skips the install
+ * rather than blocking the caller — see `SKILL_PROMPT_TIMEOUT_MS`.
  */
 export async function offerInstallCursorSkills(
   options: OfferInstallCursorSkillsOptions = {}
@@ -213,48 +281,60 @@ export async function offerInstallCursorSkills(
   const interactive =
     options.interactive ??
     (process.stdin.isTTY === true && process.stdout.isTTY === true);
-  const shipped = await listShippedPackageSkills(options.packageRoot);
-  if (shipped.length === 0) {
+  if (!interactive) {
     return { installed: [], skipped: true };
   }
 
-  const home = options.skillsHome ?? cursorSkillsHome();
-  const targetDir = agentkitCursorSkillsDir(home);
-  const missing = await findMissingCursorSkills({
+  const plan = await planSkillInstall({
     packageRoot: options.packageRoot,
-    skillsHome: home,
+    skillsHome: options.skillsHome,
   });
-  const names = shipped.map((skill) => skill.leafDir).join(", ");
-  const noun = shipped.length === 1 ? "skill" : "skills";
-  const verb = missing.length === shipped.length ? "Install" : "Update";
-  const question = `${verb} ${shipped.length} agentkit ${noun} in ${targetDir}?`;
-
-  if (!interactive) {
+  if (plan.shipped.length === 0) {
     return { installed: [], skipped: true };
   }
 
+  const noun = plan.shipped.length === 1 ? "skill" : "skills";
+  const verb = plan.firstInstall ? "Install" : "Update";
   const c = stdoutPalette();
-  out(`${question}\n`);
-  out(c.dim(`  ${names}\n`));
-  if (missing.length < shipped.length) {
+  out(
+    `${verb} ${plan.shipped.length} agentkit ${noun} in ${plan.directory}?\n`
+  );
+  out(c.dim(`  ${plan.leaves.join(", ")}\n`));
+  if (!plan.firstInstall) {
     out(c.dim("  (overwrites existing copies with the package version)\n"));
   }
+  if (plan.orphans.length > 0) {
+    out(c.dim(`  (deletes ${plan.orphans.join(", ")})\n`));
+  }
 
   const confirm =
-    options.confirm ?? ((q) => promptYesNo(q, { defaultYes: true, out }));
-  const accepted = await confirm(
-    missing.length === shipped.length ? "Install now?" : "Update now?"
-  );
-  if (!accepted) {
-    out(c.dim("Skipped skill install.\n\n"));
+    options.confirm ??
+    ((q) =>
+      promptYesNo(q, {
+        defaultYes: true,
+        out,
+        timeoutMs: SKILL_PROMPT_TIMEOUT_MS,
+      }));
+  const accepted = await confirm(`${verb} now?`);
+
+  if (accepted !== true) {
+    // `undefined` is the prompt timing out or stdin closing; both mean nobody
+    // said yes, so do not claim a duration neither case is guaranteed to have.
+    const why =
+      accepted === undefined
+        ? "No answer — skipped the skill install."
+        : "Skipped skill install.";
+    out(
+      c.dim(
+        `${why}\nInstall later: ${CLI_COMMAND_NAME} install-skills (${plan.directory})\n\n`
+      )
+    );
     return { installed: [], skipped: true };
   }
 
-  const installed = await installCursorSkills(shipped, home);
-  out(
-    `${verb === "Install" ? "Installed" : "Updated"} ${installed.length} ${noun} in ${targetDir}\n\n`
-  );
-  return { installed, skipped: false };
+  const result = await installCursorSkills(plan.shipped, plan.skillsHome);
+  out(`${formatSkillInstall(plan, result)}\n`);
+  return { installed: result.installed, skipped: false };
 }
 
 function parseSkillName(skillMd: string): string | undefined {
@@ -274,19 +354,34 @@ function parseSkillName(skillMd: string): string | undefined {
   return raw.replace(/^["']|["']$/g, "");
 }
 
-async function promptYesNo(
+export interface PromptYesNoOptions {
+  defaultYes: boolean;
+  out: (text: string) => void;
+  /** Give up after this long; `0` (or omitted) waits forever. */
+  timeoutMs?: number;
+  /** Answer source; defaults to `process.stdin`. */
+  input?: NodeJS.ReadableStream;
+}
+
+/**
+ * Ask a yes/no question. Resolves `undefined` when the answer never comes —
+ * the prompt timed out, or stdin closed on an empty line.
+ */
+export async function promptYesNo(
   question: string,
-  options: {
-    defaultYes: boolean;
-    out: (text: string) => void;
-  }
-): Promise<boolean> {
+  options: PromptYesNoOptions
+): Promise<boolean | undefined> {
   const hint = options.defaultYes ? "Y/n" : "y/N";
+  const input = options.input ?? process.stdin;
   options.out(`${question} [${hint}] `);
-  process.stdin.resume();
-  const line = await readOneLine(process.stdin);
-  process.stdin.pause();
-  if (line === undefined || line.trim() === "") {
+  input.resume();
+  const line = await readOneLine(input, options.timeoutMs);
+  input.pause();
+  if (line === undefined) {
+    options.out("\n");
+    return undefined;
+  }
+  if (line.trim() === "") {
     return options.defaultYes;
   }
   const answer = line.trim().toLowerCase();
@@ -299,11 +394,14 @@ async function promptYesNo(
   return options.defaultYes;
 }
 
+/** The line, or `undefined` when the stream ends or the clock runs out first. */
 function readOneLine(
-  stream: NodeJS.ReadableStream
+  stream: NodeJS.ReadableStream,
+  timeoutMs?: number
 ): Promise<string | undefined> {
   return new Promise((resolve) => {
     let buffer = "";
+    let timer: NodeJS.Timeout | undefined;
     const onData = (chunk: string | Buffer): void => {
       buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
       const newline = buffer.indexOf("\n");
@@ -313,15 +411,25 @@ function readOneLine(
       cleanup();
       resolve(buffer.slice(0, newline).replace(/\r$/, ""));
     };
-    const onEnd = (): void => {
+    // EOF and the timeout both land here. A tty holds a half-typed line until
+    // Enter, so a non-empty buffer only ever happens on piped input.
+    const giveUp = (): void => {
       cleanup();
       resolve(buffer === "" ? undefined : buffer.replace(/\r$/, ""));
     };
     const cleanup = (): void => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
       stream.off("data", onData);
-      stream.off("end", onEnd);
+      stream.off("end", giveUp);
     };
     stream.on("data", onData);
-    stream.on("end", onEnd);
+    stream.on("end", giveUp);
+    if (timeoutMs !== undefined && timeoutMs > 0) {
+      timer = setTimeout(giveUp, timeoutMs);
+      // Never keep the process alive purely to wait for an answer.
+      timer.unref();
+    }
   });
 }

package/src/internal/reminder-runner.ts

@@ -336,6 +336,36 @@ export class ReminderRunner {
     return n;
   }
 
+  /**
+   * Re-key armed reminders when a channel rotates a session's continuation
+   * token (the built-in HTTP channel rotates after every follow-up). Without
+   * this, a reminder armed before the rotation misses its session at fire
+   * time and disarms as `session_gone`.
+   */
+  async rekeyContinuation(
+    channelId: string,
+    oldToken: string,
+    newToken: string
+  ): Promise<number> {
+    const armed = await this.store.listArmed();
+    let n = 0;
+    for (const record of armed) {
+      if (
+        record.channelId !== channelId ||
+        record.continuationToken !== oldToken
+      ) {
+        continue;
+      }
+      await this.persist({
+        ...record,
+        continuationToken: newToken,
+        updatedAt: new Date().toISOString(),
+      });
+      n += 1;
+    }
+    return n;
+  }
+
   /** Fire one reminder immediately (dev / hillclimb). */
   async dispatch(reminderId: string): Promise<{
     reminderId: string;

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.