@cursor/july 0.1.101 → 0.1.103

package/src/channels/origin/origin-channel.ts

@@ -6,11 +6,17 @@ import {
   loopbackOnly,
   POST,
 } from "../../channels.js";
+import {
+  acknowledgeTask,
+  isTaskDispatch,
+  skipped,
+  turnStarted,
+  withPropagatingBackgroundErrors,
+} from "../../internal/channel-dispatch.js";
 import {
   continuationSource,
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
-import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
 import { isDevMode } from "../../internal/dev-mode.js";
 import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
 import { bindLocalIngressSend } from "../../internal/local-ingress.js";
@@ -49,7 +55,6 @@ import type {
   OriginPullRequestEvent,
   OriginRepositoryRef,
   OriginReview,
-  OriginTaskDispatch,
   OriginTurnDispatch,
   OriginWebhookEnvelope,
 } from "./types.js";
@@ -425,12 +430,6 @@ export function defaultOriginPullRequestDispatch(
   return { auth: defaultOriginAuth(ctx) };
 }
 
-function isTaskDispatch(
-  dispatch: OriginDispatch
-): dispatch is OriginTaskDispatch {
-  return "task" in dispatch;
-}
-
 function enrichEventContext(input: {
   ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">;
   args: ChannelHandlerArgs;
@@ -452,60 +451,6 @@ function enrichEventContext(input: {
   };
 }
 
-export type OriginDispatchOutcome = "skip" | "send" | "task";
-
-const dispatchOutcomeByResponse = new WeakMap<
-  Response,
-  OriginDispatchOutcome
->();
-
-function withDispatchOutcome(
-  response: Response,
-  outcome: OriginDispatchOutcome
-): Response {
-  dispatchOutcomeByResponse.set(response, outcome);
-  return response;
-}
-
-export function getOriginDispatchOutcome(
-  response: Response
-): OriginDispatchOutcome | undefined {
-  return dispatchOutcomeByResponse.get(response);
-}
-
-function skipped(
-  reason: string,
-  extra: Record<string, unknown> = {}
-): Response {
-  return withDispatchOutcome(
-    Response.json({ ok: true, skipped: true, reason, ...extra }),
-    "skip"
-  );
-}
-
-function acknowledgeTask(
-  args: ChannelHandlerArgs,
-  dispatch: OriginTaskDispatch,
-  extra: Record<string, unknown>
-): Response {
-  args.waitUntil(
-    new Promise<void>((resolve, reject) => {
-      setImmediate(() => {
-        Promise.resolve()
-          .then(dispatch.task)
-          .then(() => resolve(), reject);
-      });
-    })
-  );
-  return withDispatchOutcome(
-    Response.json(
-      { ok: true, dispatched: true, mode: "task", ...extra },
-      { status: 202 }
-    ),
-    "task"
-  );
-}
-
 async function startTurn(input: {
   options: OriginChannelOptions;
   args: ChannelHandlerArgs;
@@ -528,26 +473,7 @@ async function startTurn(input: {
     // reply delivery targets the latest wake, not the session's first.
     refreshState: input.state as unknown as JsonValue,
   });
-  if (isDeferredChannelSession(session)) {
-    // Hosted admission captured the send; the control plane allocates the
-    // session after acknowledgement, so there is nothing to report yet.
-    return withDispatchOutcome(
-      Response.json(
-        { ok: true, dispatched: true, mode: "turn" },
-        { status: 202 }
-      ),
-      "send"
-    );
-  }
-  return withDispatchOutcome(
-    Response.json({
-      ok: true,
-      sessionId: session.id,
-      isNew: session.isNew,
-      continuationToken: session.continuationToken,
-    }),
-    "send"
-  );
+  return turnStarted(session);
 }
 
 async function resolveCloudOptions(
@@ -590,7 +516,12 @@ async function applyDispatch(input: {
     return skipped("not_dispatched", input.extra);
   }
   if (isTaskDispatch(input.dispatch)) {
-    return acknowledgeTask(input.args, input.dispatch, input.extra);
+    return acknowledgeTask(
+      input.args,
+      ORIGIN_CHANNEL_KIND,
+      input.dispatch,
+      input.extra
+    );
   }
   const message = [
     input.dispatch.message ?? input.message,
@@ -615,13 +546,10 @@ async function applyDispatch(input: {
 }
 
 /**
- * Core Origin webhook dispatch used by {@link originChannel} routes and by
- * {@link handleAgentServeTrigger} fan-out. Signature verification is the
- * caller's responsibility (HTTP route verifies; internal fan-out skips).
- */
-/**
- * Run authored Origin hooks and `send()`. Does not extract a v2 mailbox —
- * the local CP (or hosted verified ingress) stamps before this runs.
+ * Run the authored hooks for one Origin delivery and `send()` the turn.
+ * Callers own delivery auth: the HTTP route verifies v1ed and binds the app
+ * id; trigger fan-out and hosted admission arrive verified. The v2 mailbox
+ * is stamped upstream (local CP or hosted ingress), never here.
  */
 export async function dispatchOriginWebhook(input: {
   options: OriginChannelOptions;
@@ -893,6 +821,7 @@ export function originChannel(
   originChannelOptionsByDefinition.set(definition, channelOptions);
   attachHostedAdmissionAdapter(definition, {
     kind: ORIGIN_CHANNEL_KIND,
+    prepareArgs: withPropagatingBackgroundErrors,
     dispatch: async ({ payload, args }) => {
       const envelope = parseOriginWebhookEnvelope(payload);
       if (envelope === null) {
@@ -907,10 +836,6 @@ export function originChannel(
         args,
       });
     },
-    getOutcome: (response) => {
-      const outcome = getOriginDispatchOutcome(response);
-      return outcome === "skip" || outcome === "task" ? outcome : undefined;
-    },
   });
   if (usesCursorAccount) {
     registerOriginCursorAccountRuntime(definition, {

package/src/channels/origin/types.ts

@@ -1,4 +1,4 @@
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -97,7 +97,28 @@ export type OriginTurnDispatch = {
   context?: readonly string[];
 };
 
-export type OriginTaskDispatch = { task: () => Promise<void> };
+/** Bound per-delivery helpers passed to an {@link OriginTaskDispatch.task}. */
+export interface OriginTaskArgs {
+  /**
+   * Start (or resume) a session for this delivery. In hosted admission it
+   * captures the send for the control plane; a send captured at `onStart`
+   * bypasses that capture and is rejected.
+   */
+  send: SendMessageFn;
+  /**
+   * Extend the local delivery's background window past the task promise.
+   * Hosted admission awaits the task promise only.
+   */
+  waitUntil: (promise: Promise<unknown>) => void;
+}
+
+/**
+ * Run a host-side handler after the webhook is acknowledged with a 202.
+ * Zero-argument tasks remain valid.
+ */
+export type OriginTaskDispatch = {
+  task: (args: OriginTaskArgs) => void | Promise<void>;
+};
 
 export type OriginDispatch = OriginTurnDispatch | OriginTaskDispatch;
 

package/src/channels/slack/api.ts

@@ -288,18 +288,20 @@ export async function setThreadTitle(args: {
 export async function setSuggestedPrompts(args: {
   botToken: SlackBotToken | undefined;
   channelId: string;
-  threadTs: string;
+  threadTs?: string;
   prompts: SlackSuggestedPrompt[];
   title?: string;
 }): Promise<SoftSlackResult> {
   const body: Record<string, unknown> = {
     channel_id: args.channelId,
-    thread_ts: args.threadTs,
     prompts: args.prompts.map((p) => ({
       title: p.title,
       message: p.message,
     })),
   };
+  if (args.threadTs !== undefined && args.threadTs !== "") {
+    body.thread_ts = args.threadTs;
+  }
   if (args.title !== undefined && args.title !== "") {
     body.title = args.title;
   }

package/src/channels/slack/assistant.ts

@@ -48,7 +48,7 @@ export async function maybeSetThreadTitle(args: {
 export async function maybeSetSuggestedPrompts(args: {
   botToken: SlackBotToken | undefined;
   channelId: string;
-  threadTs: string;
+  threadTs?: string;
   prompts: SlackSuggestedPrompt[];
   title?: string;
   log?: SlackLog;

package/src/channels/slack/dispatch.ts

@@ -38,6 +38,7 @@ import { isExternalSlackSender } from "./external-policy.js";
 import {
   describeSlackEventShape,
   formatSlackContextBlock,
+  parseAppHomeOpened,
   parseAppMentionEvent,
   parseAssistantThreadStarted,
   parseChannelMessageEvent,
@@ -181,8 +182,9 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    */
   blockExternals?: boolean;
   /**
-   * Suggested prompts written on `assistant_thread_started` so the
-   * assistant pane is not blank before the first user message.
+   * Suggested prompts pinned when a user opens the agent Messages tab
+   * (`app_home_opened`). Older apps still seed them on
+   * `assistant_thread_started`.
    */
   suggestedPrompts?: SlackSuggestedPrompt[];
   suggestedPromptsTitle?: string;
@@ -766,6 +768,29 @@ export function dispatchInboundFromEventBody(
     return true;
   }
 
+  const home = parseAppHomeOpened(body);
+  if (home !== null) {
+    const prompts = deps.suggestedPrompts ?? [];
+    log.info("app home opened", {
+      channel: home.channelId,
+      tab: home.tab,
+      user: home.userId,
+      event_id: eventId,
+    });
+    if (home.tab === "messages" && prompts.length > 0) {
+      deps.waitUntil(
+        maybeSetSuggestedPrompts({
+          botToken: deps.credentials?.botToken,
+          channelId: home.channelId,
+          prompts,
+          title: deps.suggestedPromptsTitle,
+          log,
+        })
+      );
+    }
+    return true;
+  }
+
   const assistantThread = parseAssistantThreadStarted(body);
   if (assistantThread !== null) {
     const prompts = deps.suggestedPrompts ?? [];

package/src/channels/slack/eval-directive.ts

@@ -16,6 +16,7 @@ import {
   EvalRunConflictError,
   EvalRunEmptyError,
 } from "../../internal/eval-run-store.js";
+import { sleep } from "../../internal/sleep.js";
 import { stripLeadingSlackMentions } from "./stop.js";
 import type { SlackBinding } from "./types.js";
 
@@ -218,12 +219,6 @@ function truncateTyping(status: string): string {
   return `${status.slice(0, TYPING_STATUS_MAX - 1)}…`;
 }
 
-async function sleep(ms: number): Promise<void> {
-  await new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
 async function safeTyping(
   binding: SlackBinding,
   status: string

package/src/channels/slack/inbound.ts

@@ -138,6 +138,43 @@ export function parseAppMentionEvent(
   return delegation === undefined ? message : { ...message, delegation };
 }
 
+export interface SlackAppHomeOpened {
+  channelId: string;
+  tab: string;
+  userId?: string;
+  teamId?: string;
+}
+
+/** Slack fires this when a user opens the app Home or Messages tab. */
+export function parseAppHomeOpened(body: unknown): SlackAppHomeOpened | null {
+  const root = asRecord(body);
+  if (root === null || root.type !== "event_callback") {
+    return null;
+  }
+  const event = asRecord(root.event);
+  if (event === null || event.type !== "app_home_opened") {
+    return null;
+  }
+  const channelId = asString(event.channel);
+  const tab = asString(event.tab);
+  if (
+    channelId === undefined ||
+    channelId === "" ||
+    tab === undefined ||
+    tab === ""
+  ) {
+    return null;
+  }
+  const userId = asString(event.user);
+  const teamId = asString(root.team_id) ?? asString(event.team_id);
+  return {
+    channelId,
+    tab,
+    userId: userId === undefined || userId === "" ? undefined : userId,
+    teamId: teamId === undefined || teamId === "" ? undefined : teamId,
+  };
+}
+
 export interface SlackAssistantThreadStarted {
   channelId: string;
   threadTs: string;

package/src/channels/slack/init.ts

@@ -8,7 +8,10 @@
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { PACKAGE_NAME } from "../../internal/distribution.js";
+import {
+  CLI_COMMAND_NAME as CLI,
+  PACKAGE_NAME,
+} from "../../internal/distribution.js";
 import { writeSlackCliProject } from "./cli-project.js";
 import { envPrefixFromName, slackEnvKeys } from "./credentials.js";
 import {
@@ -91,8 +94,8 @@ function slackChannelSource(
       : ` * Tokens: ${target.envKeys.bot} + ${target.envKeys.app}`;
   const setupLine =
     kind === "manual"
-      ? " * Full setup: agent-serve slack setup"
-      : " * Full setup: agent-serve slack create --dir .";
+      ? ` * Full setup: ${CLI} slack setup`
+      : ` * Full setup: ${CLI} slack create --dir .`;
   return `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";
 
 /**

package/src/channels/slack/manifest.ts

@@ -84,7 +84,8 @@ const BOT_SCOPES = [
 const BOT_EVENTS = [
   "app_mention",
   "message.im",
-  "assistant_thread_started",
+  // agent_view DMs: Slack no longer fires assistant_thread_started.
+  "app_home_opened",
 ] as const;
 
 /** Slack's display_information.description bound. */

package/src/channels/slack/setup.ts

@@ -1,5 +1,6 @@
+import { CLI_COMMAND_NAME as CLI } from "../../internal/distribution.js";
 /**
- * Slack setup guide printed by `agent-serve slack setup`.
+ * Slack setup guide printed by `agent-sdk slack setup`.
  *
  * Dedicated Socket Mode app via `slack create` (dashboard wizard).
  * `slack init --manual` is the unmanaged Slack CLI / paste path.
@@ -20,7 +21,7 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
     actor: "agent",
     title: "Generate channel + manifests",
     steps: [
-      "agent-serve slack init --manual --dir . --name My Agent",
+      `${CLI} slack init --manual --dir . --name My Agent`,
       "Installs the Slack app when Slack CLI is logged in. Otherwise next asks the user to install it.",
       "Manifests default to Socket Mode (no public Request URL).",
     ],
@@ -55,7 +56,7 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
       "Write per-agent tokens into .env.local (see .agent-serve/slack/env.example)",
       "Multi-agent: <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN",
       "Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN (--no-prefix)",
-      "agent-serve slack doctor --prefix <PREFIX>",
+      `${CLI} slack doctor --prefix <PREFIX>`,
     ],
   },
   {
@@ -63,7 +64,7 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
     actor: "agent",
     title: "Serve",
     steps: [
-      "agent-serve serve --dir . --dev",
+      `${CLI} serve --dir . --dev`,
       "Confirm log: [agent-sdk/slack] Socket Mode connected",
     ],
   },
@@ -103,10 +104,10 @@ export function initialSlackSetupStatus(options: {
 
 export function formatSlackSetupGuide(): string {
   const lines: string[] = [
-    "agent-serve — Slack setup",
+    `${CLI} — Slack setup`,
     "",
     "Dedicated Slack app (Socket Mode) via the dashboard wizard:",
-    "  agent-serve slack create --dir .",
+    `  ${CLI} slack create --dir .`,
     "  Finish Slack consent and the bot name there. The CLI writes",
     "  tokens into .env.local.",
     "",

package/src/channels/slack/types.ts

@@ -2,7 +2,7 @@
  * Types for the Slack platform channel pack.
  */
 
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,

package/src/channels.ts

@@ -103,7 +103,6 @@ export type {
   ChannelRoute,
   ChannelRouteHandler,
   ChannelRouteSchema,
-  ChannelRouteSpec,
   ChannelSession,
   ChannelStartArgs,
   HttpChannelConfig,

package/src/client.ts

@@ -1,5 +1,5 @@
 /**
- * Client-side plumbing for talking to a running agent-serve deployment:
+ * Client-side plumbing for talking to a running agent-sdk deployment:
  * production target resolution (stored Cursor login → engineAccess URL and
  * headers), request-header assembly, and the sessions listing used for
  * latest-session binding.

package/src/connections.ts

@@ -65,7 +65,7 @@
  * executes **on the Cursor backend** with the account's stored OAuth
  * credentials, so the agent gets Linear / Notion / Slack / … tools with
  * zero token plumbing and no OAuth secrets on this host. Requires the host
- * to be signed in (`agent-serve login` or `CURSOR_API_KEY`):
+ * to be signed in (`agent-sdk login` or `CURSOR_API_KEY`):
  *
  * ```ts
  * // agent/mcp-connections/account.ts — every connected server (no allowlist)

package/src/evals.ts

@@ -215,7 +215,7 @@ export interface EvalTestContext extends EvalAssertions {
    * change the exit code. Call it before sending messages.
    */
   skip(reason: string): never;
-  /** Debug line (surfaced under `agent-serve eval --verbose`). */
+  /** Debug line (surfaced under `agent-sdk eval --verbose`). */
   log(message: string): void;
   /**
    * Structured score for the playground (and CLI). Values appear on the

package/src/extensions/cursor-cloud-agents/extension.ts

@@ -11,13 +11,15 @@
  * });
  * ```
  *
- * Contributes `cloud__launch`, `cloud__follow_up`, `cloud__status`,
- * `cloud__list` and the `cloud__handoff` skill (the namespace is the mount
- * filename). Calls go through the Cursor SDK with the serve host's Cursor
- * API key (`CURSOR_API_KEY`, key file, or `login`); each launched agent
- * stays bound to the principal that launched it, and launches go to the
- * configured repositories. The tools run on the serve host, so they need
- * the local runtime.
+ * Contributes `cloud__launch`, `cloud__get`, `cloud__dump`, `cloud__reply`,
+ * `cloud__cancel`, `cloud__list` and the `cloud__handoff` skill (the
+ * namespace is the mount filename), the action vocabulary Sand's CloudAgent
+ * tool uses, over the same backend calls: launches through the v1 Cloud
+ * Agents API, everything else through the BackgroundComposerService RPCs,
+ * all under the serve host's Cursor API key (`CURSOR_API_KEY`, key file, or
+ * `login`). Each launched agent stays bound to the principal that launched
+ * it, and launches go to the configured repositories. The tools run on the
+ * serve host, so they need the local runtime.
  */
 
 import { z } from "zod";