@cursor/july 0.1.93 → 0.1.94

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/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/cli-mcp-oauth.ts

@@ -68,13 +68,15 @@ export async function cmdMcpOauth(
   const err = options.err ?? ((text) => process.stderr.write(text));
   const out = options.out ?? ((text) => process.stdout.write(text));
   const project = await loadAgentProject(options.dir);
-  const connection = project.agent.connections.find(
+  const authored = [
+    ...project.agent.connections,
+    ...(project.agent.hostConnections ?? []),
+  ];
+  const connection = authored.find(
     (entry) => entry.name === options.connection
   );
   if (connection === undefined) {
-    const known =
-      project.agent.connections.map((entry) => entry.name).join(", ") ||
-      "(none)";
+    const known = authored.map((entry) => entry.name).join(", ") || "(none)";
     err(
       `${LOG_PREFIX} Unknown MCP connection "${options.connection}". Authored: ${known}.\n`
     );

package/src/internal/convert-automation/convert-workflow.ts

@@ -6,9 +6,10 @@
  * clock — `exportedAt` comes from the caller.
  */
 
+import { envPrefixFromName } from "../../channels/slack/credentials.js";
 import { CLI_COMMAND_NAME, PACKAGE_NAME } from "../distribution.js";
 import { MEMORY_TS } from "../init-scaffold.js";
-import { pascalCase, SlugRegistry, slugify } from "./slug.js";
+import { SlugRegistry, slugify } from "./slug.js";
 import type {
   ActionJson,
   ConvertedFile,
@@ -998,11 +999,11 @@ function emitSlackChannel(
       "The Slack trigger marked triggering messages with a completion reaction; agentsdk has no completion-reaction option, so that signal is lost unless agent/instructions.md tells the agent to add the reaction itself via Slack tools."
     );
   }
-  if (socketMode) {
-    out.setupSteps.push(
-      `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app (not the Cursor connection): run \`${CLI_COMMAND_NAME} slack create --channel-posts\`, then finish in the dashboard wizard.`
-    );
-  }
+  out.setupSteps.push(
+    socketMode
+      ? `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app: run \`${CLI_COMMAND_NAME} slack create --channel-posts\`, then finish in the dashboard wizard.`
+      : `Slack mentions need a dedicated Socket Mode Slack app: run \`${CLI_COMMAND_NAME} slack create\`, then finish in the dashboard wizard.`
+  );
 
   const header = [
     `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";`,
@@ -1069,26 +1070,37 @@ function emitSlackChannel(
     }
     body = [
       "//",
-      "// This channel needs a dedicated Socket Mode Slack app (not the Cursor",
-      `// connection): run \`${CLI_COMMAND_NAME} slack create --channel-posts\`.`,
-      "export default slackChannel({",
-      ...engagement,
-      "});",
+      `// Run \`${CLI_COMMAND_NAME} slack create --channel-posts\` for a dedicated Slack app.`,
+      ...slackChannelExport(automation.name, engagement),
     ];
   } else {
-    const agentName = pascalCase(automation.name, "ExportedAgent");
     body = [
       "//",
-      `// Mention this agent in Slack with \`@Cursor ${agentName} ...\`.`,
-      "export default slackChannel({",
-      "  cursorAccount: true,",
-      `  agentName: ${JSON.stringify(agentName)},`,
-      "});",
+      `// Run \`${CLI_COMMAND_NAME} slack create\` for a dedicated Slack app.`,
+      ...slackChannelExport(automation.name, []),
     ];
   }
   out.files.push({ path, contents: `${[...header, ...body].join("\n")}\n` });
 }
 
+/**
+ * `slack create` writes `<DIR>_SLACK_*` from the project directory. Convert
+ * names that directory from the automation (`Nightly Triage` →
+ * `nightly-triage` → `NIGHTLY_TRIAGE`). Emit the same prefix so minted
+ * tokens bind.
+ */
+function slackChannelExport(name: string, optionLines: string[]): string[] {
+  const prefix = envPrefixFromName(slugify(name, "automation"));
+  const options = [
+    ...(prefix === "" ? [] : [`  envPrefix: ${JSON.stringify(prefix)},`]),
+    ...optionLines,
+  ];
+  if (options.length === 0) {
+    return ["export default slackChannel();"];
+  }
+  return ["export default slackChannel({", ...options, "});"];
+}
+
 function slackChannelList(
   trigger: SlackChannelsTriggerJson | undefined
 ): string[] {

package/src/internal/convert-automation/slug.ts

@@ -9,15 +9,6 @@ export function slugify(name: string, fallback: string): string {
   return slug === "" ? fallback : slug;
 }
 
-/** Single-token PascalCase (Slack cursorAccount agentName). */
-export function pascalCase(name: string, fallback: string): string {
-  const words = name.split(/[^a-zA-Z0-9]+/).filter((word) => word !== "");
-  if (words.length === 0) {
-    return fallback;
-  }
-  return words.map((word) => word[0]?.toUpperCase() + word.slice(1)).join("");
-}
-
 /** Dedupes slugs with numeric suffixes: `linear`, `linear-2`, `linear-3`, … */
 export class SlugRegistry {
   private readonly used = new Set<string>();

package/src/internal/cursor/account-mcp.ts

@@ -85,7 +85,10 @@ export function collectCursorAccountConnections(
   const bySlug = new Map<string, CursorAccountConnectionRef[]>();
   for (const { slug, project } of mounts) {
     const refs: CursorAccountConnectionRef[] = [];
-    for (const connection of project.agent.connections) {
+    for (const connection of [
+      ...project.agent.connections,
+      ...(project.agent.hostConnections ?? []),
+    ]) {
       if (!isCursorAccountTransport(connection.transport)) {
         continue;
       }