@cursor/july 0.1.93 → 0.1.94

package/src/types.ts

@@ -553,8 +553,9 @@ export interface SlackNudgeHostApi {
  */
 export interface HostContext {
   /**
-   * Authored MCP connections (`agent/mcp-connections/*`). Call a specific MCP
-   * tool deterministically without going through the agent loop.
+   * Authored MCP connections (`agent/mcp-connections/*` and
+   * `agent/host-connections/*`). Call a specific MCP tool deterministically
+   * without going through the agent loop.
    */
   mcp: HostMcpRegistry;
   /**
@@ -921,6 +922,33 @@ export type ToolNeedsApproval<TInput> =
  */
 export type ToolEffect = "read" | "write";
 
+/** Authored `defineConnection({ effects })` — one effect or a set. */
+export type ConnectionEffects = ToolEffect | readonly ToolEffect[];
+
+const TOOL_EFFECTS: readonly ToolEffect[] = ["read", "write"];
+
+export function isToolEffect(value: unknown): value is ToolEffect {
+  return value === "read" || value === "write";
+}
+
+/**
+ * Normalize authored {@link ConnectionConfig.effects} to a unique list.
+ * Invalid values are left for discovery to reject — this only collapses
+ * `"read"` / `["read"]` / duplicates.
+ */
+export function normalizeConnectionEffects(
+  effects: ConnectionEffects
+): ToolEffect[] {
+  const list = typeof effects === "string" ? [effects] : [...effects];
+  const unique: ToolEffect[] = [];
+  for (const effect of TOOL_EFFECTS) {
+    if (list.includes(effect)) {
+      unique.push(effect);
+    }
+  }
+  return unique;
+}
+
 /**
  * A tool's declared {@link ToolEffect} — fixed, or decided per call from
  * validated input for tools that read or write depending on their arguments
@@ -1185,12 +1213,6 @@ export type ConnectionConfig = (
 ) & {
   /** Documentation only; shown in `info` output. */
   description?: string;
-  /**
-   * Omit from SDK `mcpServers` (model never sees it). Still available on
-   * `host.mcp` for server tools / channel handlers. Does not affect
-   * cloud-native account connectors provisioned by the platform.
-   */
-  hostOnly?: boolean;
   /**
    * Per-session auth: called at turn-build time with the session's
    * {@link SessionInfo}, returning headers merged over the transport's
@@ -1239,12 +1261,27 @@ export type ConnectionConfig = (
    * fails the turn — a turn never silently runs with a shrunken toolset.
    * Local runtime only, like all server tools: a `runtime: "cloud"` agent
    * fails discovery, and hybrid per-send cloud sessions refuse the turn.
-   * Not combinable with {@link hostOnly} (advertising puts the tools in
-   * the model's toolset; hostOnly means off the model — discovery rejects
-   * the pair). The listing runs once per turn; point this at endpoints
-   * that can answer `tools/list` cheaply.
+   * The listing runs once per turn; point this at endpoints that can
+   * answer `tools/list` cheaply.
    */
   advertiseTools?: boolean;
+  /**
+   * Intended effects of tools this connection serves. When set, only
+   * tools whose classified effect is in this set are advertised — a
+   * connection that wants reads never puts a write, or a tool nothing
+   * classified, in the model's toolset.
+   *
+   * Classification is the same fail-closed read of MCP annotations the
+   * dry-run gate uses (`readOnlyHint` / `destructiveHint`). A tool the
+   * server does not classify is omitted, not guessed. Servers that leave
+   * tools unannotated stay empty here until they annotate or a trusted
+   * listing injects a known-read hint.
+   *
+   * Requires {@link advertiseTools}: this filters the named passthroughs
+   * the model sees. A single value (`"read"`) and an array (`["read"]`)
+   * are the same.
+   */
+  effects?: ConnectionEffects;
 };
 
 /**
@@ -1266,15 +1303,13 @@ export function isInlineStdioConnection(
   connection: ConnectionConfig
 ): connection is InlineStdioConnectionConfig & {
   description?: string;
-  hostOnly?: boolean;
 } {
   return "tools" in connection && connection.tools !== undefined;
 }
 
 /**
  * An MCP connection is available to the agent (SDK `mcpServers`), host
- * (`ctx.host.mcp`), and channel/schedule handlers — unless `hostOnly`,
- * which keeps it off the model surface only.
+ * (`ctx.host.mcp`), and channel/schedule handlers.
  */
 export type ConnectionDefinition = ConnectionConfig &
   BrandedDefinition<"connection">;
@@ -1847,6 +1882,19 @@ export const DIRECT_TOOL_CALL_CHANNEL_ID = "direct";
 export interface CallToolOptions {
   /** Who is calling; becomes the tool context's session auth. */
   auth?: AuthContext | null;
+  /**
+   * Address the session by its wire continuation token
+   * (`<channelId>:<key>`, as `/v1/sessions` lists it). A token that maps
+   * to a live (or restorable) session behaves exactly like passing that
+   * session's {@link sessionId} — ownership check, turn serialization, and
+   * event recording included. A token with no session behind it runs the
+   * call scratch-bound with the token's channel id and continuation key as
+   * the call's session identity, so deployments whose tools resolve state
+   * from the continuation key (e.g. VFS mounts rebuilt by a binding
+   * resolver) can serve it with no live session. Mutually exclusive with
+   * {@link sessionId}.
+   */
+  continuationToken?: string;
   /**
    * Run the tool inside an existing session: the tool sees that session's
    * info and materialized workspace, and the call is recorded on the
@@ -1878,6 +1926,14 @@ export interface ToolCallOutcome {
   durationMs: number;
   /** Present when the call ran inside an existing session. */
   sessionId?: string;
+  /**
+   * Present (true) when a session-bound call could not materialize the
+   * session's harness cwd and ran in a scratch workspace instead. The
+   * session identity still applied (read-effect calls only get here), but
+   * `ctx.workspaceDir` was not the session workspace — callers rendering
+   * results as session state should surface this.
+   */
+  scratchWorkspace?: true;
 }
 
 /**
@@ -2172,12 +2228,6 @@ export interface ChannelMeta {
    * by `info` so watched channels are auditable.
    */
   slackChannelPosts?: readonly string[];
-  /**
-   * For Slack packs riding the signed-in Cursor account's Slack connection
-   * (`slackChannel({ cursorAccount: true })`): inbound relays from
-   * `/v0/slack-events` instead of Socket Mode.
-   */
-  slackCursorAccount?: boolean;
 }
 
 export interface ChannelConfig<TState = JsonValue> {
@@ -2648,6 +2698,8 @@ export interface DiscoveredTool {
    * refused — see `decideToolCall`.
    */
   advertised?: true;
+  /** Name of the advertising connection an advertised tool came from. */
+  connection?: string;
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.
@@ -2672,11 +2724,15 @@ export interface DiscoveredConnection {
   name: string;
   transport: ConnectionTransport;
   description?: string;
-  hostOnly?: boolean;
   /** Per-session auth from {@link ConnectionConfig.auth} (http/sse only). */
   auth?: ConnectionAuthProvider;
   /** Advertise-by-name from {@link ConnectionConfig.advertiseTools}. */
   advertiseTools?: boolean;
+  /**
+   * Normalized intended effects from {@link ConnectionConfig.effects}.
+   * Absent means every listed tool is advertised.
+   */
+  effects?: readonly ToolEffect[];
 }
 
 export interface DiscoveredChannel {
@@ -2749,6 +2805,11 @@ export interface ResolvedAgent {
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
+  /**
+   * MCP connections from `agent/host-connections/`. Host tools and
+   * `mcp oauth` see them; the model does not.
+   */
+  hostConnections?: DiscoveredConnection[];
   subagents: ResolvedAgent[];
   seedFiles: SeedFile[];
 }
@@ -2816,14 +2877,20 @@ export interface AgentProjectInfo {
     description: string;
     execution: ToolExecution;
     needsApproval: boolean;
+    /**
+     * The tool's declared {@link ToolEffect} when static, `"dynamic"` when
+     * declared as a predicate. Absent when the author declared nothing —
+     * "unknown", not "mutates".
+     */
+    effect?: ToolEffect | "dynamic";
     inputSchema: JsonSchemaObject;
   }>;
   skills: Array<{ name: string; description: string }>;
   connections: Array<{
     name: string;
     transport: string;
-    hostOnly?: boolean;
     advertiseTools?: boolean;
+    effects?: readonly ToolEffect[];
     /**
      * Present only for `cursorAccount` connections: the connector-name
      * allowlist, or `"*"` for every connected server. Structured twin of the

package/templates/pr-autofixer/agent/channels/slack.ts

@@ -1,8 +1,14 @@
 import { slackChannel } from "@cursor/july/channels/slack";
 
+/**
+ * Slack channel (Socket Mode).
+ *
+ * Tokens: PR_AUTOFIXER_SLACK_BOT_TOKEN + PR_AUTOFIXER_SLACK_APP_TOKEN
+ *
+ * Full setup: agent-sdk slack create
+ */
 export default slackChannel({
-  cursorAccount: true,
-  agentName: "PrAutofixer",
+  envPrefix: "PR_AUTOFIXER",
   suggestedPromptsTitle: "Try asking",
   suggestedPrompts: [
     {

package/templates/triage/README.md

@@ -43,4 +43,5 @@ on both issues. `agent-sdk eval` classifies and skips tracker writes.
 - `agent/instructions.md`: procedure around the rubric
 - `evals/triage.eval.ts`: three smoke cases
 
-`agent/lib/actuate.ts` talks to the tracker. The connection is host-only.
+`agent/lib/actuate.ts` talks to the tracker. Writes go through
+`record_triage` so the host owns comments, priority, and duplicate links.

package/templates/triage/overlays/jira/agent/mcp-connections/tracker.ts

@@ -3,5 +3,4 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   cursorAccount: true,
   servers: ["Jira"],
-  hostOnly: true,
 });

package/templates/triage/overlays/linear/agent/mcp-connections/tracker.ts

@@ -3,5 +3,4 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   cursorAccount: true,
   servers: ["Linear", "Linear MCP"],
-  hostOnly: true,
 });

package/dist/channels/slack/cursor-account.d.ts

@@ -1,87 +0,0 @@
-/**
- * Cursor-account mode for the Slack channel pack: instead of a dedicated
- * Slack app (Socket Mode + `xoxb`/`xapp` tokens), the channel rides the
- * signed-in Cursor account's Slack connection. Inbound events are relayed
- * by the serve host from `/v0/slack-events` (see
- * `internal/cursor-slack-relay.ts`); outbound Web API calls run through a
- * {@link SlackApiTransport} bound to the backend proxy.
- *
- * This file is the seam between the channel definition (authored at
- * `defineChannel` time) and the serve-time relay: `slackChannel()` registers
- * a runtime ref here, and the server discovers it, binds the transport, and
- * dispatches relayed envelopes through the pack's normal inbound path.
- */
-import type { ArtifactsApi, HostContext, SendMessageFn } from "../../types.js";
-import type { EventIdDedupe } from "./event-id-dedupe.js";
-import type { SlackLog } from "./log.js";
-import type { SlackApiTransport, SlackChannelOptions, SlackCredentials, SlackMessageFile, SlackMessageHandler } from "./types.js";
-/**
- * Transport placeholder created at `slackChannel()` definition time and
- * bound to the real backend proxy caller when the serve host starts its
- * relay. Calls before binding soft-fail Slack-style.
- */
-export interface PendingSlackApiTransport extends SlackApiTransport {
-    bind(impl: SlackApiTransport["call"]): void;
-}
-export declare function createPendingSlackApiTransport(): PendingSlackApiTransport;
-/**
- * One routed Slack event from `/v0/slack-events` (mirror of the backend's
- * SlackAgentEventEnvelope, minus server-only fields).
- */
-export interface CursorSlackEnvelope {
-    eventName: string;
-    slackTeamId: string;
-    channelId: string;
-    channelType?: string;
-    threadTs: string;
-    messageTs: string;
-    slackUserId?: string;
-    text: string;
-    agentName: string;
-    consumerId: string;
-    /**
-     * How the backend routed the event: leading agent name or owned thread.
-     */
-    matchedBy: "name" | "thread";
-    eventId?: string;
-    receivedAtMs: number;
-    /**
-     * Slack file uploads on the triggering message. When `dataBase64` is set
-     * the Cursor backend already downloaded bytes (cursorAccount has no bot
-     * token for files.slack.com).
-     */
-    files?: SlackMessageFile[];
-}
-/** Serve-time runtime handle for one cursor-account Slack channel. */
-export interface SlackCursorAccountRuntime {
-    options: SlackChannelOptions;
-    /** The channel's live credentials (botToken slot holds the transport). */
-    credentials: SlackCredentials;
-    transport: PendingSlackApiTransport;
-    eventIds: EventIdDedupe;
-    onAppMention: SlackMessageHandler;
-    onDirectMessage: SlackMessageHandler;
-    getLog: () => SlackLog;
-}
-export declare function registerSlackCursorAccountRuntime(definition: object, runtime: SlackCursorAccountRuntime): void;
-/**
- * Recover the cursor-account runtime for a channel definition, if it was
- * created via `slackChannel({ cursorAccount: true })`.
- */
-export declare function getSlackCursorAccountRuntime(definition: object): SlackCursorAccountRuntime | undefined;
-/**
- * Dispatch one relayed envelope through the pack's normal inbound path
- * (same handlers, session continuation, and reply delivery as Socket Mode).
- */
-export declare function dispatchCursorSlackEnvelope(args: {
-    runtime: SlackCursorAccountRuntime;
-    envelope: CursorSlackEnvelope;
-    send: SendMessageFn;
-    host: HostContext;
-    artifacts: ArtifactsApi;
-    hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
-    isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
-    getContinuationLastBotMessageTs?: (continuationToken: string) => Promise<string | undefined>;
-    interruptContinuation?: (continuationToken: string) => Promise<boolean>;
-}): Promise<void>;
-//# sourceMappingURL=cursor-account.d.ts.map

package/dist/channels/slack/cursor-account.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cursor-account.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/cursor-account.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAEhB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,IAAI,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,8BAA8B,IAAI,wBAAwB,CAezE;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,0EAA0E;IAC1E,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,EAAE,wBAAwB,CAAC;IACpC,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,mBAAmB,CAAC;IAClC,eAAe,EAAE,mBAAmB,CAAC;IACrC,MAAM,EAAE,MAAM,QAAQ,CAAC;CACxB;AAID,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,yBAAyB,GACjC,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,GACjB,yBAAyB,GAAG,SAAS,CAEvC;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,yBAAyB,CAAC;IACnC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,YAAY,CAAC;IACxB,sBAAsB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,+BAA+B,CAAC,EAAE,CAChC,iBAAiB,EAAE,MAAM,KACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhB"}

package/dist/channels/slack/cursor-account.js

@@ -1,100 +0,0 @@
-/**
- * Cursor-account mode for the Slack channel pack: instead of a dedicated
- * Slack app (Socket Mode + `xoxb`/`xapp` tokens), the channel rides the
- * signed-in Cursor account's Slack connection. Inbound events are relayed
- * by the serve host from `/v0/slack-events` (see
- * `internal/cursor-slack-relay.ts`); outbound Web API calls run through a
- * {@link SlackApiTransport} bound to the backend proxy.
- *
- * This file is the seam between the channel definition (authored at
- * `defineChannel` time) and the serve-time relay: `slackChannel()` registers
- * a runtime ref here, and the server discovers it, binds the transport, and
- * dispatches relayed envelopes through the pack's normal inbound path.
- */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { dispatchInboundMessage } from "./dispatch.js";
-import { slackTextToMarkdown } from "./inbound.js";
-export function createPendingSlackApiTransport() {
-    let bound;
-    return {
-        kind: "api-transport",
-        label: "cursor-account",
-        bind(impl) {
-            bound = impl;
-        },
-        call(method, args) {
-            return __awaiter(this, void 0, void 0, function* () {
-                if (bound === undefined) {
-                    return { ok: false, error: "cursor_slack_relay_not_started" };
-                }
-                return bound(method, args);
-            });
-        },
-    };
-}
-const runtimeByDefinition = new WeakMap();
-export function registerSlackCursorAccountRuntime(definition, runtime) {
-    runtimeByDefinition.set(definition, runtime);
-}
-/**
- * Recover the cursor-account runtime for a channel definition, if it was
- * created via `slackChannel({ cursorAccount: true })`.
- */
-export function getSlackCursorAccountRuntime(definition) {
-    return runtimeByDefinition.get(definition);
-}
-/**
- * Dispatch one relayed envelope through the pack's normal inbound path
- * (same handlers, session continuation, and reply delivery as Socket Mode).
- */
-export function dispatchCursorSlackEnvelope(args) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const { runtime, envelope } = args;
-        const log = runtime.getLog();
-        if (envelope.eventId !== undefined &&
-            envelope.eventId.length > 0 &&
-            !runtime.eventIds.tryHandle(envelope.eventId)) {
-            log.debug("cursor-account inbound dedupe drop", {
-                event_id: envelope.eventId,
-            });
-            return;
-        }
-        const message = Object.assign(Object.assign({ text: envelope.text, body: envelope.text, markdown: slackTextToMarkdown(envelope.text), ts: envelope.messageTs, threadTs: envelope.threadTs, channelId: envelope.channelId, teamId: envelope.slackTeamId }, (envelope.slackUserId === undefined
-            ? {}
-            : {
-                author: { userId: envelope.slackUserId, isBot: false },
-            })), { files: envelope.files });
-        // DMs to @Cursor route as direct messages; everything else (explicit
-        // `@Cursor <agent> …` mentions and claimed-thread replies) dispatches on
-        // the mention handler — a claimed-thread reply is addressed to the agent
-        // by construction. Mentions/DM disable toggles are rejected at
-        // `slackChannel({ cursorAccount: true })` construction so the backend
-        // never consumes events the host would drop.
-        const isDm = envelope.channelType === "im" || envelope.channelId.startsWith("D");
-        const kind = isDm ? "direct_message" : "app_mention";
-        const handler = isDm ? runtime.onDirectMessage : runtime.onAppMention;
-        yield dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind,
-            message,
-            handler, send: args.send, credentials: runtime.credentials, host: args.host, artifacts: args.artifacts, log, evalCommandsEnabled: runtime.options.evalCommands !== false, cursorAgentName: envelope.agentName, 
-            // Backend router already refused externals for this envelope.
-            blockExternals: false }, (args.hasContinuationSession === undefined
-            ? {}
-            : { hasContinuationSession: args.hasContinuationSession })), (args.isContinuationBusy === undefined
-            ? {}
-            : { isContinuationBusy: args.isContinuationBusy })), (args.getContinuationLastBotMessageTs === undefined
-            ? {}
-            : {
-                getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
-            })), (args.interruptContinuation === undefined
-            ? {}
-            : { interruptContinuation: args.interruptContinuation })), { continuation: runtime.options.continuation }), (envelope.eventId === undefined ? {} : { eventId: envelope.eventId })));
-    });
-}