@cursor/july 0.1.92 → 0.1.94

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/continuation.ts

@@ -13,7 +13,7 @@
  *
  * Per-channel selectors still override type (`"github.issue/v2"`,
  * `"github.none/v2"`). Other `/v2` selectors: `"slack.thread/v2"`,
- * `"origin.pr/v2"`, `"none/v2"`.
+ * `"origin.pr/v2"`, `"deployments.deployment/v2"`, `"none/v2"`.
  */
 
 export type {

package/src/index.ts

@@ -182,7 +182,9 @@ export {
   isCursorAccountTransport,
   isPeerConnectionTransport,
   isSymbolicConnectionTransport,
+  isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
+  normalizeConnectionEffects,
   normalizeCursorAccountServers,
   supportsKvCas,
 } from "./types.js";

package/src/internal/advertise-tools.ts

@@ -23,6 +23,10 @@
  * `normalizeMcpToolName` uses for IDE/Sand MCP tools. A listing failure
  * still fails the turn rather than running it with a silently shrunken
  * toolset.
+ *
+ * `defineConnection({ effects })` filters the listing before names are
+ * assigned: only tools whose MCP annotations classify as an intended
+ * effect are advertised. Unclassified tools are omitted, not guessed.
  */
 
 import type {
@@ -31,9 +35,11 @@ import type {
   HostMcpCallResult,
   HostMcpToolInfo,
   JsonSchemaObject,
+  McpToolAnnotations,
   ResolvedAgent,
   SessionInfo,
   ToolDefinition,
+  ToolEffect,
 } from "../types.js";
 import { brandDefinition } from "./brand.js";
 import type { HostMcpOneOff } from "./mcp-host.js";
@@ -41,6 +47,7 @@ import {
   sanitizeMcpToolName,
   suffixMcpToolName,
 } from "./sanitize-mcp-tool-name.js";
+import { classifyAnnotationsEffect } from "./tool-policy.js";
 
 /**
  * What the resolver needs from the host MCP registry: the shared cached
@@ -88,6 +95,13 @@ export async function resolveAdvertisedTools(args: {
   agent: ResolvedAgent;
   session: SessionInfo;
   hostMcp: AdvertiseHostMcp;
+  /**
+   * When set, a connection whose source or listing fails is reported here
+   * and skipped instead of throwing. Turns keep the throwing default (a
+   * turn must fail closed); the inspection catalog passes this so one
+   * broken connector does not hide every other tool.
+   */
+  onConnectionError?: (connection: string, error: unknown) => void;
   /** Test seam; defaults to {@link sourceForConnection}. */
   sourceFor?: (
     connection: DiscoveredConnection,
@@ -105,17 +119,25 @@ export async function resolveAdvertisedTools(args: {
   const claimed = new Set(args.agent.tools.map((tool) => tool.name));
   const resolved: DiscoveredTool[] = [];
   for (const connection of advertising) {
-    const source = await sourceFor(connection, args.session, args.hostMcp);
     let listed: HostMcpToolInfo[];
+    let source: AdvertisedToolSource;
     try {
+      source = await sourceFor(connection, args.session, args.hostMcp);
       listed = await source.listTools();
     } catch (error) {
+      if (args.onConnectionError !== undefined) {
+        args.onConnectionError(connection.name, error);
+        continue;
+      }
       throw new Error(
         `Failed to list tools on advertised connection "${connection.name}": ${describeError(error)}`,
         { cause: error }
       );
     }
-    const exposed = exposeListedTools(listed, claimed);
+    const intended = listed.filter((info) =>
+      matchesIntendedEffects(info.annotations, connection.effects)
+    );
+    const exposed = exposeListedTools(intended, claimed);
     for (const { info, exposedName } of exposed) {
       resolved.push(toDiscoveredTool(connection, info, exposedName, source));
       claimed.add(exposedName);
@@ -210,6 +232,17 @@ function exposeListedTools(
   }));
 }
 
+function matchesIntendedEffects(
+  annotations: McpToolAnnotations | undefined,
+  effects: readonly ToolEffect[] | undefined
+): boolean {
+  if (effects === undefined) {
+    return true;
+  }
+  const effect = classifyAnnotationsEffect(annotations);
+  return effect !== undefined && effects.includes(effect);
+}
+
 function toDiscoveredTool(
   connection: DiscoveredConnection,
   info: HostMcpToolInfo,
@@ -222,10 +255,15 @@ function toDiscoveredTool(
       : info.description;
   const inputSchema = info.inputSchema ?? ANY_OBJECT_SCHEMA;
   const outputSchema = info.outputSchema;
+  const effect =
+    connection.effects === undefined
+      ? undefined
+      : classifyAnnotationsEffect(info.annotations);
   const definition: ToolDefinition = brandDefinition("tool", {
     description,
     inputSchema,
-    ...(outputSchema === undefined ? {} : { outputSchema }),
+    outputSchema,
+    effect,
     execute: async (input: Record<string, unknown>) =>
       formatMcpToolResult(
         connection.name,
@@ -237,16 +275,16 @@ function toDiscoveredTool(
     name: exposedName,
     description,
     inputSchema,
-    ...(outputSchema === undefined ? {} : { outputSchema }),
+    outputSchema,
     execution: "server",
     needsApproval: false,
+    effect,
     // The server's own annotations ride along (bounded at listing time), so
     // the harness listing carries them and effect classification can read
     // them. Absent stays absent — the fail-closed state.
-    ...(info.annotations === undefined
-      ? {}
-      : { annotations: info.annotations }),
+    annotations: info.annotations,
     advertised: true,
+    connection: connection.name,
     definition,
   };
 }

package/src/internal/authored-alias-hooks.ts

@@ -3,19 +3,22 @@
  * node:module `register()` from authored-loaders.ts; runs on Node's loader
  * thread — keep this module dependency-free).
  *
- * Authored files import the framework by bare specifier. From a published
- * install those need help in two cases:
+ * Authored files import the framework by bare specifier. On compiled runs the
+ * CLI pins every public package name onto the running `dist/` entries via
+ * `directAliases` so channel-option WeakMaps stay single-copy:
  *
- * - `@anysphere/agent-serve[/subpath]` (the historical monorepo name) is not
- *   on npm, so it can never resolve from a user project. `directAliases` map
- *   it straight onto the running package's dist entries.
- * - `@cursor/july[/subpath]` (the published name) and `@cursor/agentkit
- *   [/subpath]` (the future public name) normally resolve through the
- *   project's own node_modules; `fallbackAliases` only apply when that
- *   fails (npx/global installs, projects without a local dependency), so a
- *   real install in the user's project keeps precedence.
+ * - `@anysphere/agent-serve[/subpath]` (historical monorepo name; not on npm)
+ * - `@cursor/july[/subpath]` (published name)
+ * - `@cursor/agentkit[/subpath]` (future public name)
  *
- * A third case is first-party factory agents that relative-import this
+ * Preferring a project's own `node_modules` (or tsx tsconfig paths that map
+ * onto this package's `src/`) would load a second module instance and break
+ * `getGitHubChannelOptions` / continuation stamping / hosted-delivery.
+ *
+ * `fallbackAliases` remains for tests and any future soft remap; production
+ * registration leaves it empty.
+ *
+ * A separate case is first-party factory agents that relative-import this
  * package's `src/` from a monorepo checkout. Hosted engines `npm install`
  * only the agent directory, so files under `packages/agent-serve/src` have
  * no `node_modules`. Bare specifiers from that tree (`zod`, octokit, …)