@cursor/july 0.1.92 → 0.1.94

package/src/internal/deploy-manifest.ts

@@ -37,6 +37,7 @@ import type { AgentProject, AgentProjectInfo } from "../types.js";
 import {
   applyAgentContinuationDefaults,
   channelContinuationIdentity,
+  channelDeclaredEventTypes,
   handshakeChannelContinuation,
 } from "./continuation-channel.js";
 import { CONTINUATION_SELECTORS } from "./continuation-identity.js";
@@ -95,8 +96,8 @@ export interface AgentDeployManifestDeclarations {
    * Scope keys are installation config and are never extracted here.
    * Omitted channel `continuation` is `/v1` (engine minting) unless the
    * agent set `architecture: "v2"`, which stamps kind `/v2` defaults
-   * (`github.pr/v2`, `slack.thread/v2`, `origin.pr/v2`). Per-channel
-   * selectors still override type.
+   * (`github.pr/v2`, `slack.thread/v2`, `origin.pr/v2`,
+   * `deployments.deployment/v2`). Per-channel selectors still override type.
    */
   channels: Array<{
     id: string;
@@ -141,14 +142,9 @@ export function buildAgentDeployManifest(
       throw new Error(handshake.error);
     }
     const kind = channel.definition.meta?.kind;
-    const githubEvents = channel.definition.meta?.githubWebhookEvents;
-    const originEvents = channel.definition.meta?.originWebhookEvents;
+    const declaredEvents = channelDeclaredEventTypes(channel.definition.meta);
     const eventTypes =
-      githubEvents !== undefined
-        ? [...githubEvents].sort()
-        : originEvents !== undefined
-          ? [...originEvents].sort()
-          : undefined;
+      declaredEvents === undefined ? undefined : [...declaredEvents].sort();
     return {
       id: channel.id,
       kind,

package/src/internal/discovery.ts

@@ -50,8 +50,10 @@ import {
   type InlineStdioConnectionConfig,
   type InstructionsDefinition,
   isInlineStdioConnection,
+  isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
   type ModelSetting,
+  normalizeConnectionEffects,
   normalizeCursorAccountServers,
   type ResolvedAgent,
   type ScheduleDefinition,
@@ -423,6 +425,7 @@ async function loadAgent(
       tools: [],
       skills: [],
       connections: [],
+      hostConnections: [],
       subagents: [],
       seedFiles: [],
     };
@@ -434,6 +437,7 @@ async function loadAgent(
     ctx,
     await resolveMcpConnectionsDir(ctx, agentDir)
   );
+  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
   const seedFiles = await loadSeedFiles(ctx, agentDir);
   const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
   const runtime = resolveRuntime(ctx, agentDir, config?.runtime);
@@ -553,7 +557,7 @@ async function loadAgent(
       agentTools: tools.filter((tool) => tool.execution === "agent").length,
       skills: skills.length,
       seedFiles: seedFiles.length,
-      connections: connections.length,
+      connections: connections.length + hostConnections.length,
       subagents: subagents.length,
       hasCloudOptions: cloud !== undefined,
       hasLocalSandbox: localSandbox,
@@ -576,6 +580,7 @@ async function loadAgent(
     tools,
     skills,
     connections,
+    hostConnections,
     subagents,
     seedFiles,
   };
@@ -1143,6 +1148,26 @@ function hasAuthorizationHeader(
   );
 }
 
+function parseConnectionEffects(
+  effects: unknown
+): { ok: true; value: ToolEffect[] | undefined } | { ok: false } {
+  if (effects === undefined) {
+    return { ok: true, value: undefined };
+  }
+  const raw = typeof effects === "string" ? [effects] : effects;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { ok: false };
+  }
+  const parsed: ToolEffect[] = [];
+  for (const value of raw) {
+    if (!isToolEffect(value)) {
+      return { ok: false };
+    }
+    parsed.push(value);
+  }
+  return { ok: true, value: normalizeConnectionEffects(parsed) };
+}
+
 function connectionHasSpawnOrRemote(connection: ConnectionDefinition): boolean {
   if ("cursorAccount" in connection && connection.cursorAccount === true) {
     return true;
@@ -1265,6 +1290,49 @@ async function resolveMcpConnectionsDir(
   return preferred;
 }
 
+async function loadHostConnections(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  modelConnections: readonly DiscoveredConnection[]
+): Promise<DiscoveredConnection[]> {
+  const hostDir = join(agentDir, "host-connections");
+  const loaded = await loadConnections(ctx, hostDir);
+  const modelNames = new Set(
+    modelConnections.map((connection) => connection.name)
+  );
+  const hostConnections: DiscoveredConnection[] = [];
+  for (const connection of loaded) {
+    if (modelNames.has(connection.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message: `Host connection "${connection.name}" collides with agent/mcp-connections/${connection.name}. Rename one of them.`,
+      });
+      continue;
+    }
+    if (connection.advertiseTools === true) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message:
+          "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
+      });
+      continue;
+    }
+    if (connection.auth !== undefined) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message:
+          "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
+      });
+      continue;
+    }
+    hostConnections.push(connection);
+  }
+  return hostConnections;
+}
+
 async function loadConnections(
   ctx: DiscoveryContext,
   connectionsDir: string
@@ -1292,6 +1360,15 @@ async function loadConnections(
       continue;
     }
     const connection = definition as ConnectionDefinition;
+    if (Object.hasOwn(connection, "hostOnly")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "MCP connection `hostOnly` was removed. Files under `agent/mcp-connections/` are always visible to the model. Put privileged servers in `agent/host-connections/` so only host tools can call them.",
+      });
+      continue;
+    }
     if (
       isInlineStdioConnection(connection) &&
       connectionHasSpawnOrRemote(connection)
@@ -1336,24 +1413,37 @@ async function loadConnections(
       });
       continue;
     }
+    const parsedEffects = parseConnectionEffects(connection.effects);
+    if (!parsedEffects.ok) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          'MCP connection `effects` must be "read", "write", or a non-empty array of those.',
+      });
+      continue;
+    }
     if (
-      connection.advertiseTools === true &&
-      isInlineStdioConnection(connection)
+      parsedEffects.value !== undefined &&
+      connection.advertiseTools !== true
     ) {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
+          "MCP connection `effects` filters advertised tools; set `advertiseTools: true` or drop `effects`.",
       });
       continue;
     }
-    if (connection.advertiseTools === true && connection.hostOnly === true) {
+    if (
+      connection.advertiseTools === true &&
+      isInlineStdioConnection(connection)
+    ) {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "MCP connection `advertiseTools` puts the connection's tools in the model's toolset, which contradicts `hostOnly` (off the model entirely). Drop one of them.",
+          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
       });
       continue;
     }
@@ -1445,9 +1535,9 @@ async function loadConnections(
       name,
       transport,
       description: connection.description,
-      hostOnly: connection.hostOnly,
       auth: connection.auth,
       advertiseTools: connection.advertiseTools,
+      effects: parsedEffects.value,
     });
   }
   return connections;
@@ -1459,7 +1549,6 @@ async function loadInlineStdioConnection(
   entryPath: string,
   connection: InlineStdioConnectionConfig & {
     description?: string;
-    hostOnly?: boolean;
   }
 ): Promise<DiscoveredConnection | undefined> {
   const tools = connection.tools;
@@ -1510,7 +1599,6 @@ async function loadInlineStdioConnection(
       name,
       transport,
       description: connection.description,
-      hostOnly: connection.hostOnly,
     };
   } catch (error) {
     ctx.diagnostics.push({
@@ -1562,6 +1650,7 @@ async function warnUnsupportedSubagentSlots(
     ["tools", "tools"],
     ["skills", "skills"],
     ["mcp-connections", "MCP connections"],
+    ["host-connections", "host MCP connections"],
     ["connections", "MCP connections"],
     ["subagents", "nested subagents"],
     ["channels", "channels"],
@@ -1670,8 +1759,8 @@ function checkGrokBotRuntimeLimitations(
   }
   if (counts.connections > 0) {
     error(
-      displayPath(ctx, join(agentDir, "mcp-connections")),
-      "MCP connections are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
+      displayPath(ctx, agentDir),
+      "MCP connections (agent/mcp-connections/ or agent/host-connections/) are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
     );
   }
   if (counts.subagents > 0) {
@@ -2256,6 +2345,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       description: tool.description,
       execution: tool.execution,
       needsApproval: tool.needsApproval,
+      effect: tool.effect,
       inputSchema: tool.inputSchema,
     })),
     skills: agent.skills.map((skill) => ({
@@ -2265,8 +2355,8 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
     connections: agent.connections.map((connection) => ({
       name: connection.name,
       transport: connectionTransportLabel(connection.transport),
-      hostOnly: connection.hostOnly,
       advertiseTools: connection.advertiseTools,
+      effects: connection.effects,
       cursorAccountServers:
         "cursorAccount" in connection.transport
           ? (connection.transport.servers ?? "*")
@@ -2311,6 +2401,9 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
         if (meta?.originWebhookEvents !== undefined) {
           info.originWebhookEvents = meta.originWebhookEvents;
         }
+        if (meta?.deploymentEventTypes !== undefined) {
+          info.deploymentEventTypes = meta.deploymentEventTypes;
+        }
         if (meta?.slackChannelPosts !== undefined) {
           info.slackChannelPosts = meta.slackChannelPosts;
         }
@@ -2445,6 +2538,7 @@ async function warnUnknownSlots(
     "tools",
     "skills",
     "mcp-connections",
+    "host-connections",
     // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
     "connections",
     "subagents",
@@ -2454,7 +2548,7 @@ async function warnUnknownSlots(
     "ab",
     "sandbox",
     "lib",
-    // Vite playground custom tool chips (examples/*/agent/playground/tools).
+    // Vite playground custom tool chips (agent/playground/tools).
     "playground",
   ]);
   for (const entry of await sortedEntries(agentDir)) {

package/src/internal/distribution.ts

@@ -21,8 +21,9 @@ export const PACKAGE_NAME = "@cursor/july";
 export const LEGACY_PACKAGE_NAME = "@anysphere/agent-serve";
 
 /**
- * Future public package name; aliased with the same fallback-only semantics
- * as PACKAGE_NAME so the eventual rename keeps authored imports working.
+ * Future public package name; aliased with the same direct-to-running-dist
+ * semantics as PACKAGE_NAME so the eventual rename keeps authored imports
+ * on the CLI's module identity.
  */
 export const AGENTKIT_PACKAGE_NAME = "@cursor/agentkit";
 
@@ -117,7 +118,7 @@ export function formatCliVersion(options?: { json?: boolean }): string {
  * runtime mirror of the package `exports` map (the source of truth;
  * `authored-loaders.test.ts` asserts they stay identical). The alias hooks
  * derive `@anysphere/agent-serve[/x]`, `@cursor/july[/x]`, and
- * `@cursor/agentkit[/x]` targets from this list.
+ * `@cursor/agentkit[/x]` direct targets from this list.
  */
 export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   readonly [subpath: string, file: string]

package/src/internal/fixtures/units-server.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny stdio MCP server used by mcp-host tests.
+ *
+ * Exposed as the `units` connection so the host can list and call tools
+ * over a real stdio transport.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({
+  name: "weather-units",
+  version: "0.1.0",
+});
+
+server.tool(
+  "celsius_to_fahrenheit",
+  "Convert a temperature from Celsius to Fahrenheit.",
+  { value: z.number().describe("Temperature in °C") },
+  async ({ value }) => {
+    const fahrenheit = Math.round((value * 9) / 5 + 32);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ celsius: value, fahrenheit }),
+        },
+      ],
+    };
+  }
+);
+
+server.tool(
+  "fahrenheit_to_celsius",
+  "Convert a temperature from Fahrenheit to Celsius.",
+  { value: z.number().describe("Temperature in Fahrenheit") },
+  async ({ value }) => {
+    const celsius = Math.round(((value - 32) * 5) / 9);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ fahrenheit: value, celsius }),
+        },
+      ],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/internal/hosted-delivery-protocol.ts

@@ -0,0 +1,114 @@
+export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
+export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
+export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
+export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+
+export type HostedAdmission = {
+  v: 2;
+  channelId: string;
+  channelKind: "github";
+  eventType: string;
+  deliveryId: string;
+  sessionMode: "event" | "continuation";
+  mailboxContinuationKey: string;
+  payload: unknown;
+};
+
+export type HostedAdmissionOutcome =
+  | { ok: true; v: 2; outcome: "skip" | "task" }
+  | { ok: true; v: 2; outcome: "send"; admissionToken: string };
+
+export type HostedExecution = {
+  v: 2;
+  admissionToken: string;
+  sessionPublicId: string;
+};
+
+export type HostedExecutionOutcome = {
+  ok: true;
+  v: 2;
+  outcome: "send";
+};
+
+const DELIVERY_KEYS = new Set([
+  "v",
+  "channelId",
+  "channelKind",
+  "eventType",
+  "deliveryId",
+  "sessionMode",
+  "mailboxContinuationKey",
+  "payload",
+]);
+const EXECUTION_KEYS = new Set(["v", "admissionToken", "sessionPublicId"]);
+
+function boundedString(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+
+export function parseHostedAdmission(
+  value: unknown
+): HostedAdmission | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some((key) => !DELIVERY_KEYS.has(key)) ||
+    !Object.hasOwn(body, "payload") ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    !boundedString(body.channelId, 128) ||
+    body.channelKind !== "github" ||
+    !boundedString(body.eventType, 128) ||
+    !boundedString(body.deliveryId, 256) ||
+    (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||
+    !boundedString(body.mailboxContinuationKey, 512)
+  ) {
+    return undefined;
+  }
+  const prefix = body.sessionMode === "event" ? "evt:" : "cont:";
+  return body.mailboxContinuationKey.startsWith(prefix)
+    ? (body as HostedAdmission)
+    : undefined;
+}
+
+export function parseHostedExecution(
+  value: unknown
+): HostedExecution | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some((key) => !EXECUTION_KEYS.has(key)) ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    !boundedString(body.admissionToken, 128) ||
+    typeof body.sessionPublicId !== "string" ||
+    !/^ses_[a-f0-9]{24}$/.test(body.sessionPublicId)
+  ) {
+    return undefined;
+  }
+  return body as HostedExecution;
+}
+
+export function parseHostedAdmissionOutcome(
+  value: unknown
+): HostedAdmissionOutcome | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    body.ok !== true ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    (body.outcome !== "skip" &&
+      body.outcome !== "send" &&
+      body.outcome !== "task")
+  ) {
+    return undefined;
+  }
+  if (body.outcome === "send" && !boundedString(body.admissionToken, 128)) {
+    return undefined;
+  }
+  return body as HostedAdmissionOutcome;
+}