@cursor/july 0.1.93 → 0.1.95

package/src/channels/slack/pr-ref.ts

@@ -1,7 +1,9 @@
 /**
- * Best-effort GitHub PR references from free-form chat (Slack, etc.).
+ * Best-effort PR references from free-form chat (Slack, etc.).
  */
 
+import { type PrProvider, parsePrUrl } from "../../internal/scm/pr-url.js";
+
 export interface GithubPrRef {
   /** Normalized URL `https://github.com/owner/repo/pull/N`. */
   url: string;
@@ -12,39 +14,68 @@ export interface GithubPrRef {
   number: number;
 }
 
+export type OriginPrRef = GithubPrRef;
+
+const URL_IN_TEXT = /https?:\/\/[^\s>|]+/gi;
+
+function githubRef(owner: string, repo: string, number: number): GithubPrRef {
+  return {
+    owner,
+    repo,
+    number,
+    url: `https://github.com/${owner}/${repo}/pull/${number}`,
+    label: `${owner}/${repo}#${number}`,
+  };
+}
+
+function firstUrlRef(
+  text: string,
+  provider: PrProvider
+): GithubPrRef | undefined {
+  const matches = text.match(URL_IN_TEXT);
+  if (matches === null) {
+    return undefined;
+  }
+  for (const raw of matches) {
+    const parsed = parsePrUrl(raw);
+    if (parsed?.provider === provider) {
+      return {
+        owner: parsed.owner,
+        repo: parsed.repo,
+        number: parsed.number,
+        url: parsed.url,
+        label: `${parsed.owner}/${parsed.repo}#${parsed.number}`,
+      };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Find the first Origin PR URL in `text`.
+ * Does not treat bare `owner/repo#N` as Origin.
+ */
+export function extractOriginPrRef(text: string): OriginPrRef | undefined {
+  return firstUrlRef(text, "origin");
+}
+
 /**
  * Find the first GitHub PR URL or `owner/repo#N` in `text`.
  * Returns `undefined` when none is present.
  */
 export function extractGithubPrRef(text: string): GithubPrRef | undefined {
-  const urlMatch = text.match(
-    /https?:\/\/(?:www\.)?github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/i
-  );
-  if (urlMatch !== null) {
-    const owner = urlMatch[1] as string;
-    const repo = urlMatch[2] as string;
-    const number = Number(urlMatch[3]);
-    return {
-      owner,
-      repo,
-      number,
-      url: `https://github.com/${owner}/${repo}/pull/${number}`,
-      label: `${owner}/${repo}#${number}`,
-    };
+  const fromUrl = firstUrlRef(text, "github");
+  if (fromUrl !== undefined) {
+    return fromUrl;
   }
 
   const hashMatch = text.match(/\b([\w.-]+)\/([\w.-]+)#(\d+)\b/);
   if (hashMatch === null) {
     return undefined;
   }
-  const owner = hashMatch[1] as string;
-  const repo = hashMatch[2] as string;
-  const number = Number(hashMatch[3]);
-  return {
-    owner,
-    repo,
-    number,
-    url: `https://github.com/${owner}/${repo}/pull/${number}`,
-    label: `${owner}/${repo}#${number}`,
-  };
+  return githubRef(
+    hashMatch[1] as string,
+    hashMatch[2] as string,
+    Number(hashMatch[3])
+  );
 }

package/src/channels/slack/setup.ts

@@ -1,10 +1,10 @@
 /**
  * Slack setup guide printed by `agent-serve slack setup`.
  *
- * Two products: Cursor-hosted (`cursorAccount`) vs a dedicated Socket
- * Mode app via `slack create` (dashboard wizard). `slack init --manual`
- * is the unmanaged paste-at-api.slack.com path. {@link SLACK_SETUP_PHASES}
- * is that checklist; its ids key `.agent-serve/slack/setup-status.json`.
+ * Dedicated Socket Mode app via `slack create` (dashboard wizard).
+ * `slack init --manual` is the unmanaged paste-at-api.slack.com path.
+ * {@link SLACK_SETUP_PHASES} is that checklist; its ids key
+ * `.agent-serve/slack/setup-status.json`.
  */
 
 export interface SlackSetupPhase {
@@ -101,17 +101,10 @@ export function formatSlackSetupGuide(): string {
   const lines: string[] = [
     "agent-serve — Slack setup",
     "",
-    "Two products. Pick one.",
-    "",
-    "  A) Cursor-hosted (recommended default, zero Slack admin):",
-    '     slackChannel({ cursorAccount: true, agentName: "MyAgent" })',
-    "     Sign in (agent-serve login / CURSOR_API_KEY), serve, then mention",
-    '     "@Cursor MyAgent ..." in the linked workspace. No app, no tokens.',
-    "  B) Dedicated Slack app (Socket Mode) via the dashboard wizard:",
-    "     agent-serve slack create --dir .",
-    "     Finish Slack consent and the bot name there. The CLI writes",
-    "     tokens into .env.local. Use this when you need your own bot",
-    "     user, channel watching, or approval buttons.",
+    "Dedicated Slack app (Socket Mode) via the dashboard wizard:",
+    "  agent-serve slack create --dir .",
+    "  Finish Slack consent and the bot name there. The CLI writes",
+    "  tokens into .env.local.",
     "",
     "Manual Slack app: `slack init --manual`. Phases below.",
     "Goal: importable dev + prod Slack apps over Socket Mode (no public URL).",

package/src/channels/slack/slack-channel.ts

@@ -39,10 +39,6 @@ import {
   tryResolveAppToken,
   tryResolveBotToken,
 } from "./credentials.js";
-import {
-  createPendingSlackApiTransport,
-  registerSlackCursorAccountRuntime,
-} from "./cursor-account.js";
 import {
   buildDefaultEvents,
   createDefaultOnChannelPost,
@@ -67,12 +63,10 @@ import {
   startSlackSocketMode,
 } from "./socket-mode.js";
 import { buildToolApprovalEvents } from "./tool-approval-events.js";
-import {
-  assertSlackCursorAgentName,
-  type SlackChannelOptions,
-  type SlackChannelState,
-  type SlackCredentials,
-  type SlackCursorAgentName,
+import type {
+  SlackChannelOptions,
+  SlackChannelState,
+  SlackCredentials,
 } from "./types.js";
 
 /** Options used to construct a slack channel — for host-level credential binding. */
@@ -98,8 +92,7 @@ export interface SlackChannelHostBinding {
 }
 
 /**
- * First dedicated (Socket Mode) Slack channel on a project. Skips
- * `cursorAccount` channels — those have no local bot token for
+ * First Slack channel on a project. Used for
  * {@link HostContext.slack.getClient}.
  */
 export function resolveDedicatedSlackHostBinding(
@@ -107,7 +100,7 @@ export function resolveDedicatedSlackHostBinding(
 ): SlackChannelHostBinding | undefined {
   for (const channel of channels) {
     const options = slackChannelOptionsByDefinition.get(channel.definition);
-    if (options === undefined || options.cursorAccount === true) {
+    if (options === undefined) {
       continue;
     }
     return {
@@ -121,97 +114,19 @@ export function resolveDedicatedSlackHostBinding(
 /**
  * Create a Slack channel. Author as `agent/channels/slack.ts` default export.
  *
- * Missing credentials are not an error: without a token pair (or a
- * signed-in host for `cursorAccount`) the channel mounts idle and logs
- * `channel idle`, so serving an agent never blocks on Slack setup.
- *
- * When `cursorAccount` is on, `agentName` must be a single token (no
- * whitespace) — string literals with spaces fail at the type level;
- * runtime values are still checked by {@link assertSlackCursorAgentName}.
+ * Missing credentials are not an error: without a token pair the channel
+ * mounts idle and logs `channel idle`, so serving an agent never blocks
+ * on Slack setup.
  */
-export function slackChannel<const Name extends string = string>(
-  authored: Omit<SlackChannelOptions, "agentName"> & {
-    agentName?: SlackCursorAgentName<Name>;
-  } = {}
+export function slackChannel(
+  authored: SlackChannelOptions = {}
 ): ChannelDefinition<SlackChannelState> {
   const options = { ...authored };
   if (options.continuation !== undefined) {
     options.continuation = normalizeIdentity(options.continuation, "slack");
   }
-  const cursorAccount = options.cursorAccount === true;
-  if (cursorAccount) {
-    // Token pair and the Cursor connection are different Slack apps —
-    // they can't be mixed on one channel definition.
-    if (options.credentials !== undefined || options.envPrefix !== undefined) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) uses the Cursor account's Slack connection — do not also set credentials/envPrefix. Author a second slack channel file for a dedicated Slack app."
-      );
-    }
-    if (options.agentName !== undefined) {
-      assertSlackCursorAgentName(options.agentName);
-    }
-    // Channel watching is Socket Mode only — cursorAccount agents must be
-    // explicitly addressed (@mention, DM, or claimed-thread reply).
-    if (options.engagement?.channelPosts !== undefined) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) does not support engagement.channelPosts — agents must be explicitly addressed (@mention, DM, or claimed-thread reply). Channel watching is Socket Mode only."
-      );
-    }
-    // Bot-mention wake needs the app's own bot identity (auth.test) and
-    // Socket Mode event delivery; the Cursor relay drops bot-authored
-    // mentions before they reach the agent.
-    if (options.engagement?.botMentions !== undefined) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) does not support engagement.botMentions — bot-to-bot mention wake is Socket Mode only (author a dedicated Slack app channel)."
-      );
-    }
-    // Mentions/DMs are always routed by the backend. Disabling them
-    // client-side would black-hole events the webhook already stole from
-    // native Cursor handling — reject at construction instead.
-    if (options.engagement?.mentions === false) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) cannot set engagement.mentions to false — the Cursor Slack relay always delivers mention and claimed-thread traffic."
-      );
-    }
-    if (options.engagement?.directMessages === false) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) cannot set engagement.directMessages to false — DM continuity is part of the Cursor Slack connection."
-      );
-    }
-    // Tool approvals / interactivity ride Slack Socket Mode `interactive`
-    // envelopes; the Cursor connection does not relay Block Kit clicks, so
-    // there is no backend tap to route Approve/Deny over cursorAccount.
-    // Reject at construction (same posture as channelPosts) instead of
-    // silently dropping clicks. Approvals stay available on a dedicated
-    // Socket Mode Slack app channel.
-    if (options.toolApprovals === true) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) does not support toolApprovals — Approve/Deny clicks are not relayed over the Cursor Slack connection. Tool approvals are Socket Mode only (author a dedicated Slack app channel for them)."
-      );
-    }
-    if (options.interactivity === true) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) does not support interactivity — interactive Block Kit clicks are not relayed over the Cursor Slack connection. Interactivity is Socket Mode only."
-      );
-    }
-    if (options.onBlockAction !== undefined) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) does not support onBlockAction — interactive Block Kit clicks are not relayed over the Cursor Slack connection. Block actions are Socket Mode only."
-      );
-    }
-    if (options.onReactionAdded !== undefined) {
-      throw new Error(
-        "slackChannel({ cursorAccount: true }) does not support onReactionAdded because the Cursor Slack relay does not forward reaction events. Reaction handling is Socket Mode only."
-      );
-    }
-  }
-  const accountTransport = cursorAccount
-    ? createPendingSlackApiTransport()
-    : undefined;
   const credentials =
-    accountTransport !== undefined
-      ? { botToken: accountTransport }
-      : (options.credentials ?? credentialsFromEnv(options.envPrefix));
+    options.credentials ?? credentialsFromEnv(options.envPrefix);
   const envKeys = slackEnvKeys(options.envPrefix);
   const loadingMessages = options.loadingMessages;
   const policy = options.policy;
@@ -259,9 +174,7 @@ export function slackChannel<const Name extends string = string>(
       events,
       buildDefaultEvents({
         credentials,
-        // cursorAccount: never edit posts — setStatus for thinking, one
-        // final postMessage for the reply (proxy pins agent username/icon).
-        streaming: cursorAccount ? false : options.streaming,
+        streaming: options.streaming,
         thinkingSteps: options.thinkingSteps,
         suggestedPrompts: options.suggestedPrompts,
         suggestedPromptsTitle: options.suggestedPromptsTitle,
@@ -307,8 +220,7 @@ export function slackChannel<const Name extends string = string>(
       directMessagesEnabled,
       evalCommandsEnabled,
       followUpStatus,
-      // cursorAccount: backend router already refuses externals.
-      blockExternals: cursorAccount ? false : blockExternals,
+      blockExternals,
       ...(args.hasContinuationSession === undefined
         ? {}
         : { hasContinuationSession: args.hasContinuationSession }),
@@ -335,7 +247,6 @@ export function slackChannel<const Name extends string = string>(
     routes: [],
     meta: {
       kind: "slack",
-      ...(cursorAccount ? { slackCursorAccount: true } : {}),
       ...(channelPosts === undefined
         ? {}
         : { slackChannelPosts: [...channelPosts.allow] }),
@@ -390,13 +301,6 @@ export function slackChannel<const Name extends string = string>(
     async onStart(args) {
       runtime.log = createSlackLogger(args.logger ?? options.logger);
 
-      if (cursorAccount) {
-        // Inbound arrives through the serve host's Cursor Slack relay
-        // (`/v0/slack-events`), not Socket Mode; outbound goes through the
-        // bound API transport. Nothing to start here.
-        getLog().info("channel start", { transport: "cursor-account" });
-        return;
-      }
       getLog().info("channel start", { transport: "socket" });
 
       const appToken = await tryResolveAppToken(credentials);
@@ -640,20 +544,5 @@ export function slackChannel<const Name extends string = string>(
 
   slackChannelOptionsByDefinition.set(definition, options);
 
-  if (accountTransport !== undefined) {
-    // Serve-time seam: the host discovers cursor-account channels through
-    // this registry, binds the outbound transport, and dispatches relayed
-    // inbound envelopes through the pack's normal path.
-    registerSlackCursorAccountRuntime(definition, {
-      options,
-      credentials,
-      transport: accountTransport,
-      eventIds,
-      onAppMention,
-      onDirectMessage,
-      getLog,
-    });
-  }
-
   return definition;
 }

package/src/channels/slack/types.ts

@@ -13,14 +13,13 @@ import type {
 
 /**
  * Pluggable Slack Web API caller. Instead of holding a raw `xoxb-…` token,
- * calls are executed by `call` — e.g. proxied through the Cursor backend
- * with the signed-in account's Slack connection (`cursorAccount: true`).
- * Implementations return the Slack response body (including `ok: false`
- * platform errors) and only throw on programmer error.
+ * calls are executed by `call`. Implementations return the Slack response
+ * body (including `ok: false` platform errors) and only throw on
+ * programmer error.
  */
 export interface SlackApiTransport {
   kind: "api-transport";
-  /** Human-readable transport label for logs (e.g. `cursor-account`). */
+  /** Human-readable transport label for logs. */
   label: string;
   call(
     method: string,
@@ -122,8 +121,8 @@ export interface SlackMessageFile {
   mode?: string;
   size?: number;
   /**
-   * When set (cursorAccount relay), bytes were already downloaded by the
-   * Cursor backend — skip a second `files.info` / private URL fetch.
+   * When set, bytes were already downloaded by the caller. Skip a second
+   * `files.info` / private URL fetch.
    */
   dataBase64?: string;
 }
@@ -333,8 +332,7 @@ export interface SlackChannelPostsOptions {
    * channel the bot is in. Must be non-empty (empty is a definition error).
    * `#names` are resolved to ids via `conversations.list` when the channel
    * starts; the bot must be a member of each watched channel to receive its
-   * messages. Socket Mode only — `cursorAccount: true` rejects
-   * `engagement.channelPosts`.
+   * messages.
    *
    * `"*"` suits agents whose handler decides per message (a thread the agent
    * is already in, say) rather than per channel. Every delivered message then
@@ -384,11 +382,8 @@ export interface SlackBotMentionsOptions {
    * - `"U…"` — a bot *user* id.
    * - `"<botId>:<username>"` — compound: the posting app's `bot_id` AND its
    *   message `username` must both match (case-insensitive username). Use
-   *   this for shared multi-tenant apps like the Cursor Slack connection,
-   *   where every agent posts under one `bot_id` but the backend pins each
-   *   agent's `username` server-side — `"B0CURSOR…:Lasso"` trusts only the
-   *   Cursor app posting as Lasso, not every Cursor-connected agent.
-   *   Fails closed when the event carries no username.
+   *   this when several agents post through one app under different
+   *   usernames. Fails closed when the event carries no username.
    *
    * Must be non-empty (empty is a definition error).
    */
@@ -432,51 +427,10 @@ export interface SlackEngagementOptions {
   channelPosts?: SlackChannelPostsOptions;
   /**
    * Opt-in bot-to-bot mention wake (see {@link SlackBotMentionsOptions}).
-   * Socket Mode only — rejected on `cursorAccount: true`.
    */
   botMentions?: SlackBotMentionsOptions;
 }
 
-/**
- * Whitespace forbidden in {@link SlackChannelOptions.agentName}. The Cursor
- * Slack router matches on leading words; multi-word names collide with Named
- * Agent shortened-prefix matching (`Approval …` stealing `ApprovalBuddy`).
- */
-type SlackAgentNameWhitespace = " " | "\t" | "\n" | "\r" | "\f" | "\v";
-
-/**
- * Single-token Cursor Slack handle for `cursorAccount` routing
- * (`@Cursor <name> …`). String literals that contain whitespace become
- * `never` (type error at the call site); plain `string` stays `string` and
- * is still rejected at runtime by {@link assertSlackCursorAgentName}.
- */
-export type SlackCursorAgentName<S extends string = string> = string extends S
-  ? string
-  : S extends `${string}${SlackAgentNameWhitespace}${string}`
-    ? never
-    : S;
-
-const SLACK_CURSOR_AGENT_NAME_WHITESPACE = /\s/;
-
-/**
- * Runtime guard for {@link SlackChannelOptions.agentName}. Call from
- * `slackChannel({ cursorAccount: true })` construction and serve-time
- * name resolution so derived defaults cannot sneak spaces in.
- */
-export function assertSlackCursorAgentName(name: string): void {
-  const trimmed = name.trim();
-  if (trimmed.length === 0) {
-    throw new Error(
-      'slackChannel({ cursorAccount: true }) agentName must be a non-empty single token (no whitespace), e.g. "ApprovalBuddy".'
-    );
-  }
-  if (SLACK_CURSOR_AGENT_NAME_WHITESPACE.test(trimmed)) {
-    throw new Error(
-      `slackChannel({ cursorAccount: true }) agentName must be a single token with no whitespace (got ${JSON.stringify(name)}). Use PascalCase like "ApprovalBuddy" — multi-word names break @Cursor routing.`
-    );
-  }
-}
-
 /** `"thread"` = anyone in the thread (default); `"author"` = session starter only. */
 export type SlackRespondTo = "thread" | "author";
 
@@ -504,38 +458,6 @@ export interface SlackChannelOptions {
    * Ignored when `credentials` is set explicitly.
    */
   envPrefix?: string;
-  /**
-   * Use the signed-in Cursor account's Slack connection instead of a
-   * dedicated Slack app: no bot/app tokens, no extra install. Inbound
-   * traffic (`@Cursor <agent name> …` mentions, replies in threads the
-   * agent owns, and DMs) is relayed from the Cursor backend
-   * (`/v0/slack-events`), and outbound Web API calls are proxied through it
-   * — the agent posts as the Cursor Slack app with this agent's name and
-   * icon.
-   *
-   * Both paths stay first-class: omit this (default) for the classic
-   * Socket-Mode channel with your own Slack app and tokens. Requires a
-   * signed-in host (`agent-serve login` / `CURSOR_API_KEY`) and a Slack
-   * account linked to the Cursor account. Mutually exclusive with
-   * `credentials` / `envPrefix`. `engagement.mentions: false` and
-   * `engagement.directMessages: false` are rejected (the relay always
-   * carries that traffic). Channel watching (`engagement.channelPosts`) and
-   * tool approvals / interactivity (`toolApprovals` / `interactivity`) are
-   * Socket Mode only — not supported on cursorAccount; agents must be
-   * explicitly addressed, and Approve/Deny buttons need a dedicated Slack
-   * app.
-   */
-  cursorAccount?: boolean;
-  /**
-   * Single-token display name registered with the Cursor backend when
-   * {@link cursorAccount} is on: `@Cursor <agentName> …` routes here, and
-   * replies post under this username. **No whitespace** — prefer PascalCase
-   * (`ApprovalBuddy`). Defaults to a PascalCase name derived from the
-   * agent's mount slug (or project name).
-   */
-  agentName?: SlackCursorAgentName;
-  /** Avatar for posts when {@link cursorAccount} is on. */
-  agentIcon?: { url?: string; emoji?: string };
   /**
    * Optional log sink. When omitted, uses `console.log` until the server
    * mounts the channel and rebinds to {@link ServeOptions.logger}.
@@ -573,9 +495,7 @@ export interface SlackChannelOptions {
   deliverDefaults?: boolean;
   /**
    * Stream assistant text while the turn runs via `chat.startStream` /
-   * `appendStream` / `stopStream` (defaults to `true` for Socket Mode).
-   * Ignored when {@link cursorAccount} is on — that path never edits posts
-   * (`setStatus` + one final `chat.postMessage` only).
+   * `appendStream` / `stopStream` (defaults to `true`).
    */
   streaming?: boolean;
   /**
@@ -598,9 +518,7 @@ export interface SlackChannelOptions {
    *
    * Framework park/resume is enabled by `needsApproval` on server tools.
    * Set this to `true` to also post Block Kit Approve/Deny cards and route
-   * the Socket Mode `interactive` clicks to `resolveApproval`. Socket Mode
-   * only — rejected on `cursorAccount: true` (the Cursor Slack connection
-   * does not relay Block Kit clicks).
+   * the Socket Mode `interactive` clicks to `resolveApproval`.
    *
    * Defaults to `false`. For custom composition, spread
    * `buildToolApprovalEvents({ credentials })` into `events`.
@@ -609,8 +527,7 @@ export interface SlackChannelOptions {
   /**
    * Route interactive payloads to approval resolution without opting into
    * the full {@link buildToolApprovalEvents} handler pack. Use when
-   * composing `buildToolApprovalEvents` into `events` manually. Socket Mode
-   * only — rejected on `cursorAccount: true`.
+   * composing `buildToolApprovalEvents` into `events` manually.
    */
   interactivity?: boolean;
   /**
@@ -622,7 +539,6 @@ export interface SlackChannelOptions {
    * thread, or `null` to ignore the click. Setting this implies
    * interactive routing; the Slack app manifest still needs
    * `interactivity` enabled (`buildSlackManifest({ interactivity: true })`).
-   * Socket Mode only — rejected on `cursorAccount: true`.
    */
   onBlockAction?: SlackBlockActionHandler;
   /**

package/src/client.ts

@@ -0,0 +1,23 @@
+/**
+ * Client-side plumbing for talking to a running agent-serve deployment:
+ * production target resolution (stored Cursor login → engineAccess URL and
+ * headers), request-header assembly, and the sessions listing used for
+ * latest-session binding.
+ *
+ * This entry point exists for first-party CLI clients (`agsh`); agent code
+ * should not need it.
+ */
+
+export {
+  mergeRequestHeaders,
+  type RequestAuth,
+} from "./internal/request-headers.js";
+export {
+  PROD_ENGINE_WAKE_HEADERS,
+  ProdTargetError,
+  type ResolvedProdTarget,
+  type ResolveProdTargetOptions,
+  resolveProdTarget,
+} from "./internal/resolve-prod-target.js";
+export { listSessions } from "./internal/sessions-client.js";
+export type { SessionSummary } from "./types.js";

package/src/connections.ts

@@ -1,11 +1,15 @@
 /**
- * `defineConnection` — authored at `agent/mcp-connections/<name>.ts`.
+ * `defineConnection` — authored at `agent/mcp-connections/<name>.ts`
+ * (model + host) or `agent/host-connections/<name>.ts` (host + `mcp oauth`
+ * only).
  *
  * A connection gives tools from an external MCP server. The filename
- * becomes the connection (server) name. Available to the agent (SDK
- * `mcpServers`), host (`ctx.host.mcp`), and channel/schedule handlers.
- * Pass `advertiseTools: true` for named tools on local turns. Pass
- * `hostOnly: true` to keep it off the model (still on `host.mcp`).
+ * becomes the connection (server) name. Files under `mcp-connections/`
+ * are available to the agent (SDK `mcpServers`), host (`ctx.host.mcp`),
+ * and channel/schedule handlers. Pass `advertiseTools: true` for named
+ * tools on local turns. Pass `effects: "read"` with `advertiseTools` to
+ * advertise only tools the server classifies as reads. Files under
+ * `host-connections/` stay off the model.
  *
  * ```ts
  * import { defineConnection } from "@cursor/july/connections";
@@ -27,11 +31,16 @@
  *   },
  * });
  *
- * // privileged connector, model cannot call directly:
  * export default defineConnection({
  *   cursorAccount: true,
  *   servers: ["anytool"],
- *   hostOnly: true,
+ * });
+ *
+ * // query-only: advertise only tools classified as reads
+ * export default defineConnection({
+ *   url: "https://api.cursor.com/v1/agent/mcp",
+ *   advertiseTools: true,
+ *   effects: "read",
  * });
  * ```
  *
@@ -107,15 +116,19 @@ import type { ConnectionConfig, ConnectionDefinition } from "./types.js";
 export type {
   ConnectionConfig,
   ConnectionDefinition,
+  ConnectionEffects,
   ConnectionTransport,
   HostMcpCallResult,
   HostMcpRegistry,
   HostMcpToolInfo,
   InlineStdioConnectionConfig,
   InlineStdioToolConfig,
+  ToolEffect,
 } from "./types.js";
 export {
   isInlineStdioConnection,
+  isToolEffect,
+  normalizeConnectionEffects,
   normalizeCursorAccountServers,
 } from "./types.js";
 

package/src/files-backends/cursor-hosted.ts

@@ -125,8 +125,12 @@ export function isCursorUserStoreFilesAvailable(
 export interface CursorHostedFilesOptions {
   /** Control-plane base URL (default: `CURSOR_API_BASE_URL`, else api.cursor.com). */
   baseUrl?: string;
-  /** Bearer credential (default: `CURSOR_API_KEY`). */
-  apiKey?: string;
+  /**
+   * Bearer credential (default: `CURSOR_API_KEY`). A function is re-resolved
+   * on every call — hosted freeze snapshots listen unsigned and bind the key
+   * file after serve start.
+   */
+  apiKey?: string | (() => string | undefined);
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
   /** Test seam; defaults to global fetch. */
@@ -622,7 +626,9 @@ function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
 }
 
 function resolveApiKey(options: CursorHostedFilesOptions): string {
-  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  const configured =
+    typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
+  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
     throw new Error(
       "cursorHostedFiles requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"

package/src/files.ts

@@ -184,6 +184,17 @@ export const agentStoreKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/memory/journal.jsonl`,
   memoryJournalRotated: (agent: string, stamp: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/memory/journal-${stamp}.jsonl`,
+  // SDK conversation mirror (the runner's SQLite store, exported through the
+  // store APIs): one manifest per SDK agent id plus its content-addressed
+  // checkpoint blobs. See internal/conversation-mirror.ts.
+  conversationManifest: (agent: string, sdkAgentId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/manifest.json`,
+  conversationBlob: (
+    agent: string,
+    sdkAgentId: string,
+    blobId: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/blobs/${encodeURIComponent(blobId)}`,
 } as const;
 
 /**