@cursor/july 0.1.92 → 0.1.94

package/src/internal/hosted-delivery.ts

@@ -0,0 +1,359 @@
+import { randomBytes } from "node:crypto";
+import {
+  dispatchGitHubWebhook,
+  getGitHubChannelOptions,
+  getGitHubDispatchOutcome,
+  withPropagatingGitHubBackgroundErrors,
+} from "../channels/github/github-channel.js";
+import type {
+  AuthPolicy,
+  ChannelHandlerArgs,
+  SendMessageOptions,
+} from "../types.js";
+import {
+  HOSTED_ADMISSION_PATH,
+  HOSTED_DELIVERY_HEADER,
+  HOSTED_DELIVERY_PROTOCOL_VERSION,
+  HOSTED_EXECUTION_PATH,
+  type HostedAdmission,
+  parseHostedAdmission,
+  parseHostedExecution,
+} from "./hosted-delivery-protocol.js";
+import { errorResponse, readJsonObject } from "./http-channel.js";
+import type { Router } from "./router.js";
+
+type DispatchInput = {
+  delivery: HostedAdmission;
+  definition: object;
+  args: ChannelHandlerArgs;
+};
+
+type PendingSend = {
+  channelId: string;
+  message: string;
+  options: SendMessageOptions;
+  mailboxContinuationKey: string;
+};
+
+type AdmissionDispatch = {
+  response: Response;
+  pendingSend?: PendingSend;
+};
+
+type ExecutionReply = {
+  status: number;
+  body: Record<string, unknown>;
+};
+
+class HostedSendAdmitted extends Error {
+  constructor(
+    readonly prompt: string,
+    readonly options: SendMessageOptions
+  ) {
+    super("hosted channel admitted a send");
+  }
+}
+
+/**
+ * Run authored admission without creating a framework session. V1 GitHub
+ * `task` callbacks execute as sessionless work; `send` is captured and
+ * resumed only after the control plane allocates `ses_…`.
+ */
+export async function dispatchHostedAdmission(
+  input: DispatchInput
+): Promise<AdmissionDispatch> {
+  const github = getGitHubChannelOptions(input.definition);
+  if (github === undefined) {
+    return {
+      response: Response.json(
+        { ok: false, error: "channel_kind_mismatch" },
+        { status: 422 }
+      ),
+    };
+  }
+
+  const background: Promise<unknown>[] = [];
+  let deferredSend: HostedSendAdmitted | undefined;
+  const args = withPropagatingGitHubBackgroundErrors({
+    ...input.args,
+    send: async (message, options = {}) => {
+      throw new HostedSendAdmitted(message, options);
+    },
+    waitUntil: (promise) => {
+      background.push(
+        promise.catch((error: unknown) => {
+          if (error instanceof HostedSendAdmitted) {
+            deferredSend = error;
+            return;
+          }
+          throw error;
+        })
+      );
+    },
+  });
+  let dispatched: Response;
+  try {
+    dispatched = await dispatchGitHubWebhook({
+      options: github,
+      eventName: input.delivery.eventType,
+      payload: input.delivery.payload,
+      deliveryId: input.delivery.deliveryId,
+      args,
+    });
+  } catch (error) {
+    if (error instanceof HostedSendAdmitted) {
+      return {
+        response: Response.json({
+          ok: true,
+          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+          outcome: "send",
+        }),
+        pendingSend: {
+          channelId: input.delivery.channelId,
+          message: error.prompt,
+          options: error.options,
+          mailboxContinuationKey: input.delivery.mailboxContinuationKey,
+        },
+      };
+    }
+    throw error;
+  }
+  if (!dispatched.ok) {
+    return {
+      response: Response.json(
+        { ok: false, error: "channel_dispatch_failed" },
+        { status: dispatched.status >= 400 ? dispatched.status : 502 }
+      ),
+    };
+  }
+
+  try {
+    await Promise.all(background);
+  } catch {
+    return {
+      response: Response.json(
+        { ok: false, error: "background_dispatch_failed" },
+        { status: 503 }
+      ),
+    };
+  }
+  if (deferredSend !== undefined) {
+    return {
+      response: Response.json({
+        ok: true,
+        v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+        outcome: "send",
+      }),
+      pendingSend: {
+        channelId: input.delivery.channelId,
+        message: deferredSend.prompt,
+        options: deferredSend.options,
+        mailboxContinuationKey: input.delivery.mailboxContinuationKey,
+      },
+    };
+  }
+  const outcome = getGitHubDispatchOutcome(dispatched);
+  if (outcome === undefined) {
+    return {
+      response: Response.json(
+        { ok: false, error: "channel_outcome_missing" },
+        { status: 502 }
+      ),
+    };
+  }
+  return {
+    response: Response.json({
+      ok: true,
+      v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+      outcome,
+    }),
+  };
+}
+
+function withServerTiming(response: Response, durationMs: number): Response {
+  const headers = new Headers(response.headers);
+  headers.set(
+    "Server-Timing",
+    `agent_sdk;desc="hosted";dur=${Math.max(0, durationMs).toFixed(1)}`
+  );
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+export function registerHostedDeliveryRoute(input: {
+  router: Router;
+  base: string;
+  channels: Array<{ id: string; definition: object }>;
+  buildHandlerArgs(
+    channelId: string,
+    sessionPublicId?: string
+  ): ChannelHandlerArgs;
+}): void {
+  const pending = new Map<
+    string,
+    {
+      send: PendingSend;
+      expiresAt: number;
+      sessionPublicId?: string;
+      execution?: Promise<ExecutionReply>;
+    }
+  >();
+  const pendingTtlMs = 10 * 60_000;
+  const pruneExpired = () => {
+    const now = Date.now();
+    for (const [token, item] of pending) {
+      if (item.expiresAt <= now) {
+        pending.delete(token);
+      }
+    }
+  };
+
+  // Hosted callers reach this only through AnyRun's signed pod-port URL.
+  // The marker is a second, route-specific fence distinct from channel auth.
+  const auth: AuthPolicy = (request) => {
+    if (request.headers.get(HOSTED_DELIVERY_HEADER) !== "1") {
+      return null;
+    }
+    return {
+      authenticator: "app",
+      principalId: "agent-sdk:hosted-delivery",
+      principalType: "runtime",
+    };
+  };
+  input.router.add({
+    method: "POST",
+    pattern: `${input.base}${HOSTED_ADMISSION_PATH}`,
+    auth: [auth],
+    handler: async (request) => {
+      const startedAt = performance.now();
+      const finish = (response: Response) =>
+        withServerTiming(response, performance.now() - startedAt);
+      const delivery = parseHostedAdmission(await readJsonObject(request));
+      if (delivery === undefined) {
+        return finish(
+          errorResponse(
+            400,
+            "invalid_hosted_admission",
+            "Expected a supported Agent SDK hosted-admission envelope."
+          )
+        );
+      }
+      const channel = input.channels.find(
+        (candidate) => candidate.id === delivery.channelId
+      );
+      if (channel === undefined) {
+        return finish(
+          errorResponse(
+            404,
+            "channel_not_found",
+            `No channel named "${delivery.channelId}" is mounted.`
+          )
+        );
+      }
+      const admitted = await dispatchHostedAdmission({
+        delivery,
+        definition: channel.definition,
+        args: input.buildHandlerArgs(delivery.channelId),
+      });
+      if (admitted.pendingSend === undefined) {
+        return finish(admitted.response);
+      }
+      pruneExpired();
+      const admissionToken = randomBytes(24).toString("hex");
+      pending.set(admissionToken, {
+        send: admitted.pendingSend,
+        expiresAt: Date.now() + pendingTtlMs,
+      });
+      return finish(
+        Response.json({
+          ok: true,
+          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+          outcome: "send",
+          admissionToken,
+        })
+      );
+    },
+  });
+  input.router.add({
+    method: "POST",
+    pattern: `${input.base}${HOSTED_EXECUTION_PATH}`,
+    auth: [auth],
+    handler: async (request) => {
+      const startedAt = performance.now();
+      const finish = (response: Response) =>
+        withServerTiming(response, performance.now() - startedAt);
+
+      const execution = parseHostedExecution(await readJsonObject(request));
+      if (execution === undefined) {
+        return finish(
+          errorResponse(
+            400,
+            "invalid_hosted_execution",
+            "Expected a supported Agent SDK hosted-execution envelope."
+          )
+        );
+      }
+      pruneExpired();
+      const admitted = pending.get(execution.admissionToken);
+      if (admitted === undefined) {
+        return finish(
+          errorResponse(
+            409,
+            "hosted_admission_unavailable",
+            "The hosted admission token is missing or expired."
+          )
+        );
+      }
+      if (
+        admitted.sessionPublicId !== undefined &&
+        admitted.sessionPublicId !== execution.sessionPublicId
+      ) {
+        return finish(
+          errorResponse(
+            409,
+            "hosted_admission_session_mismatch",
+            "The hosted admission token is already bound to another session."
+          )
+        );
+      }
+      admitted.sessionPublicId = execution.sessionPublicId;
+      admitted.execution ??= (async (): Promise<ExecutionReply> => {
+        const args = input.buildHandlerArgs(
+          admitted.send.channelId,
+          execution.sessionPublicId
+        );
+        const session = await args.send(admitted.send.message, {
+          ...admitted.send.options,
+          mailboxContinuation: {
+            key: admitted.send.mailboxContinuationKey,
+          },
+        });
+        const outcome = await session.waitForCompletion();
+        if (outcome.status !== "finished") {
+          return {
+            status: 503,
+            body: {
+              ok: false,
+              error: "turn_failed",
+              turnStatus: outcome.status,
+              message: outcome.errorMessage,
+            },
+          };
+        }
+        return {
+          status: 200,
+          body: {
+            ok: true,
+            v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+            outcome: "send",
+          },
+        };
+      })();
+      const reply = await admitted.execution;
+      return finish(Response.json(reply.body, { status: reply.status }));
+    },
+  });
+}

package/src/internal/http-channel.ts

@@ -16,7 +16,6 @@ import type {
   AuthContext,
   AuthPolicy,
   HttpChannelDefinition,
-  JsonValue,
   SessionRecord,
 } from "../types.js";
 import { samePrincipal } from "./auth.js";
@@ -101,7 +100,6 @@ export function buildHttpChannelRoutes(args: {
       const cloud = readCloudOptions(body.cloud);
       const session = await engine.send(HTTP_CHANNEL_ID, message, {
         auth: ctx.auth,
-        ...(body.state === undefined ? {} : { state: body.state as JsonValue }),
         ...(typeof body.title === "string" ? { title: body.title } : {}),
         ...(body.purpose === "eval" ? { purpose: "eval" as const } : {}),
         ...(body.dryRun === true ? { dryRun: true } : {}),

package/src/internal/mcp-endpoint.ts

@@ -252,9 +252,9 @@ function buildToolMcpServer(
  * travels in the turn's MCP config or lands on the VM.
  *
  * The engine gates access twice, mirroring the authored server-tool path:
- * only bridgeable names (`isCloudBridgedConnection`) — `hostOnly`
- * connections and unknown names stay unreachable from a VM even with a
- * valid endpoint credential — and only while the bound session has a turn
+ * only bridgeable names (`isCloudBridgedConnection`) — unknown names
+ * stay unreachable from a VM even with a valid endpoint credential —
+ * and only while the bound session has a turn
  * in flight (`hasActiveTurn`), so a credential that persists on a VM after
  * its turn cannot keep calling host connectors. Listing forwards per
  * request, so a server that adds tools mid-session (`tools/list_changed`,

package/src/internal/mcp-host.ts

@@ -1,12 +1,13 @@
 /**
- * Host-side MCP clients for authored `agent/mcp-connections/*`.
+ * Host-side MCP clients for authored `agent/mcp-connections/*` and
+ * `agent/host-connections/*`.
  *
- * Every connection is always available in three places:
- * - the Cursor agent, via SDK `mcpServers` (local harness or cloud)
- * - the agent-serve host, for in-process server tools through
- *   {@link HostMcpRegistry} on {@link ToolContext.host}.mcp
- * - channel / webhook route handlers through
- *   {@link HostMcpRegistry} on {@link ChannelHandlerArgs.host}.mcp
+ * Model-visible connections (`mcp-connections/`) are available in three
+ * places: SDK `mcpServers`, in-process server tools through
+ * {@link HostMcpRegistry} on {@link ToolContext.host}.mcp, and channel /
+ * webhook handlers through {@link HostMcpRegistry} on
+ * {@link ChannelHandlerArgs.host}.mcp. Host connections skip the model
+ * and stay on `host.mcp` plus `mcp oauth`.
  */
 
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";

package/src/internal/peer-connections.ts

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

package/src/internal/playground/static.ts

@@ -96,9 +96,7 @@ export function renderPlaygroundAsset(file: string): Response {
 }
 
 /** Slack surface summary for the host home / `GET /v1/agents`. */
-export type AgentIndexSlack =
-  | { kind: "cursor-account"; handle: string }
-  | { kind: "socket" };
+export type AgentIndexSlack = { kind: "socket" };
 
 /** One row on the host home page and `GET /v1/agents`. */
 export interface AgentIndexEntry {

package/src/internal/resolved-connections.ts

@@ -46,13 +46,13 @@ export function validateMountConnectionsConfig(args: {
     return;
   }
   const label = args.slug === "" ? args.project.name : args.slug;
-  const hostOnlyNames = new Set(
-    agent.connections
-      .filter((connection) => connection.hostOnly === true)
-      .map((connection) => connection.name)
+  const hostConnectionNames = new Set(
+    (args.project.agent.hostConnections ?? []).map(
+      (connection) => connection.name
+    )
   );
   const filteredRefs = args.accountRefs.filter(
-    (ref) => ref.servers !== undefined && !hostOnlyNames.has(ref.name)
+    (ref) => ref.servers !== undefined && !hostConnectionNames.has(ref.name)
   );
   if (filteredRefs.length === 0) {
     return;
@@ -140,10 +140,8 @@ export function resolveMountConnections(args: {
 
   if (cloudCapable) {
     const hostOauthNames = agent.connections
-      .filter(
-        (connection) =>
-          connection.hostOnly !== true &&
-          isHostOauthConnectionTransport(connection.transport)
+      .filter((connection) =>
+        isHostOauthConnectionTransport(connection.transport)
       )
       .map((connection) => connection.name);
     if (hostOauthNames.length > 0) {
@@ -154,7 +152,7 @@ export function resolveMountConnections(args: {
             )}) reach cloud turns through the host connection bridge; their tokens stay on this serve host.`
           : `[agent-sdk] warning: agent "${label}" has host-OAuth MCP connections (${hostOauthNames.join(
               ", "
-            )}) whose tokens live on this serve host; cloud-runtime turns omit them. Mark them \`hostOnly: true\` and call them from host tools, or drop \`oauth\` and authorize the server another way.`
+            )}) whose tokens live on this serve host; cloud-runtime turns omit them. Serve with a cloud tools URL so they reach turns through the host connection bridge, or drop \`oauth\` and authorize the server another way.`
       );
     }
   }