@cursor/july 0.1.94 → 0.1.96

package/skills/setup-slack/SKILL.md

@@ -1,270 +1,139 @@
 ---
 name: agentsdk-setup-slack
 description: >-
-  Wire Slack to an Agent SDK agent. Mint a dedicated Socket Mode app with
-  slack create (dashboard wizard), then doctor and smoke. Use the manual
-  manifest path only when the user owns the Slack app. Use when adding
-  Slack to an agent.
+  Wire Slack to an Agent SDK agent. Mint a dedicated Socket Mode app
+  with slack create, then doctor and smoke. Use slack init --manual
+  only when the user owns the Slack app. Use when adding Slack.
 ---
 
 # Setup Slack for the Agent SDK
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+Dedicated Socket Mode bot. `agent-sdk slack create` opens the
+signed-in dashboard wizard. Tokens land in `.env.local` and as
+deployment secrets. Never print token values.
 
-Use this skill when a human asks to wire Slack to an Agent SDK agent.
+Do not generate manifests or ask anyone to paste tokens unless
+they asked for `slack init --manual`.
 
-`slackChannel()` is a dedicated Socket Mode Slack app: the agent's own
-bot user. `agent-sdk slack create` opens a signed-in Cursor dashboard
-wizard; Slack consent and the bot name happen there. Tokens land in
-`.env.local` and as deployment secrets.
+Existing `<PREFIX>_SLACK_BOT_TOKEN` + `_SLACK_APP_TOKEN` in
+`.env.local` keep working. Do not force those onto the wizard.
 
-Do not generate manifests or ask anyone to paste tokens unless they
-asked for a custom Slack app (`slack init --manual`).
+Guide: `docs/guides/slack.md`.
 
-Existing bots that already have `<PREFIX>_SLACK_BOT_TOKEN` and
-`_SLACK_APP_TOKEN` in `.env.local` keep working. Do not force them onto
-the wizard.
-
-## Dedicated Slack app (Socket Mode)
-
-Goal: one dedicated bot per agent, tokens in `.env.local`, local serve
-without a cloud deploy. The dashboard wizard is the only first-run.
+## 1. Wizard (default)
 
 ```bash
 agent-sdk login
 agent-sdk slack create --dir .
 ```
 
-That opens the signed-in Cursor dashboard. Sign in as the same Cursor
-account that ran the command. Click **Add Slack to this agent**, approve
-Slack's consent screen, pick the bot name, and continue. The CLI waits
-and writes `<PREFIX>_SLACK_BOT_TOKEN` / `<PREFIX>_SLACK_APP_TOKEN` into
-`<dir>/.env.local`, then runs `doctor`. Token values never print.
-
-`--prod` provisions the prod app (default is dev). `--name` / `--icon` /
-`--channel-posts` prefill the wizard. `--prefix` / `--no-prefix` set the
-env-var names.
+Same Cursor account in the browser. **Add Slack to this agent**,
+approve Slack, pick the bot name. CLI writes
+`<PREFIX>_SLACK_BOT_TOKEN` / `<PREFIX>_SLACK_APP_TOKEN` and runs
+`doctor`.
 
-If Slack asks a workspace admin to approve the app, keep the CLI
-running. Open Slack's **Request approval** page (the CLI prints the
-link; the same URL is **Send a reminder** after you submit). Managed
-install does not file the request. After an admin approves, click
-**Retry** in the wizard.
+Prefix is the directory basename in upper snake (`jenny` →
+`JENNY`, `pr-approver` → `PR_APPROVER` → `PR_APPROVER_SLACK_*`).
+`--prefix` / `--no-prefix` override. Dev and prod are separate
+apps; `--prod` is the prod app. `--name` / `--icon` /
+`--channel-posts` / `--slack-team` prefill the wizard.
 
-`create` scaffolds `agent/channels/slack.ts` when missing. Do not paste
-a manifest at api.slack.com for this path. `slack init` without
-`--manual` hard-errors; see the manual path below for a hand-imported
-app.
+If Slack needs workspace-admin approval, keep the CLI running.
+Open the **Request approval** link it prints. Managed install
+does not file the request. After approval, **Retry** in the
+wizard.
 
-Existing tokens in `.env.local` keep working. Skip the wizard for those
-agents unless you want a Cursor-managed app.
+`create` scaffolds `agent/channels/slack.ts` when missing:
 
-Then:
-
-```bash
-agent-sdk slack doctor --prefix MY_AGENT
-agent-sdk dev .
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  suggestedPrompts: [{ title: "Help", message: "How can you help me?" }],
+});
 ```
 
-Confirm log: `[agent-sdk/slack] Socket Mode connected`.
-
-When tokens are missing the channel logs
-`channel idle reason=missing credentials need=…` and `serve` continues.
-
-Human:
+Return from dispatch handlers. Do not await long work in the
+handler.
 
-1. Invite the bot to a channel
-2. `@mention` it (or DM)
-3. Confirm Thinking… / Working… typing and a threaded reply
-4. Server logs should show correlated lines (`event_id`, `session`, `channel`, `thread_ts`):
-   - `inbound kind=app_mention …`
-   - `session start …`
-   - `reply delivered via postMessage|stream …`
+A second `slack create` for the same agent and env overwrites the
+app (same Slack app id, new manifest and tokens).
+`agent-sdk slack destroy` deletes it.
 
-The dashboard lists a first-run agent as **Not deployed yet**. Local
-serve does not need a hosted engine. The next `agent-sdk deploy` (or
-dashboard **Deploy**) injects the stored secrets.
+Local serve does not need a hosted engine. Next
+`agent-sdk deploy` injects the stored secrets.
 
-A second `slack create` for the same agent and env overwrites that Slack
-app. It keeps the Slack app id and replaces the manifest and tokens.
-`agent-sdk slack destroy` deletes the provisioned app. Tokens left in
-`.env.local` simply stop working.
+## 2. Manual (`slack init --manual`)
 
-## Manual Slack app (`slack init --manual`)
-
-Use this when the user wants a Slack app they own at api.slack.com, not
-a Cursor-managed app. Not the default. Do not offer it unless they
-asked for a custom/unmanaged app or already have one. Update
-`.agent-serve/slack/setup-status.json` as you complete phases.
-
-### Phase 0 — Generate (agent)
+Only when they own the app at api.slack.com.
 
 ```bash
 agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-Creates:
-
-- `agent/channels/slack.ts` with `envPrefix` from the directory name
-- `.agent-serve/slack/manifest.{dev,prod}.json`
-- `.agent-serve/slack/env.example` (`<PREFIX>_SLACK_BOT_TOKEN` / `_APP_TOKEN`)
-- `.agent-serve/slack/setup-status.json`
-
-Use `--no-prefix` for the shared `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN`
-globals (single-agent only). Use `--prefix CUSTOM` to override the
-default prefix. `--channel-posts` subscribes the manifests to
-`message.channels` / `message.groups`.
-
-These files omit `settings.managed_app_settings`. Slack accepts that
-block only from a manager app's user token, so it belongs to
-`slack create`, not to a manifest a human pastes in.
-
-### Phase 1 — Create apps (human)
-
-1. Open https://api.slack.com/apps → **Create New App** → **From a manifest**
-2. Paste `manifest.dev.json` → create the *dev* app
-3. Repeat with `manifest.prod.json` for prod
-
-Stop and ask the human to complete this gate.
-
-### Phase 2 — Install + tokens (human)
+Writes `agent/channels/slack.ts` (`envPrefix` from the directory),
+manifests under the project state directory, and `env.example`.
+`--channel-posts` subscribes `message.channels` /
+`message.groups`.
 
-For each app:
+Human gates, one at a time. Stop after each.
 
-1. **Install to Workspace** — copy Bot User OAuth Token (`xoxb-…`)
-2. **Basic Information → App-Level Tokens** — Create Token with scope
-   `connections:write` → copy (`xapp-…`)
+1. **Create the app.** Create New App → From a manifest. Start
+   with `manifest.dev.json`.
+2. **Install.** Install to Workspace. Copy the bot token
+   (`xoxb-...`).
+3. **App token.** Create an app-level token with
+   `connections:write` (`xapp-...`).
+4. **Write env.** Put both in `.env.local`. Then doctor.
 
-### Phase 3 — Env (agent)
+Repeat for prod with the prod manifest.
 
-Write into `.env.local` (dev app), using the keys from `env.example`:
+## 3. Doctor and smoke
 
 ```bash
-MY_AGENT_SLACK_BOT_TOKEN=xoxb-…
-MY_AGENT_SLACK_APP_TOKEN=xapp-…
+agent-sdk slack doctor --prefix JENNY
+agent-sdk serve --dir . --dev
 ```
 
-```bash
-agent-sdk slack doctor --prefix MY_AGENT
-```
-
-Stop when `app_token`, `connections_open`, `bot_token`, and `auth_test`
-are green.
-
-### Phase 4 — Serve + smoke (agent + human)
-
-```bash
-agent-sdk dev .
-```
-
-Confirm log: `[agent-sdk/slack] Socket Mode connected`.
-
-When tokens are missing the channel logs
-`channel idle reason=missing credentials need=…` and `serve` continues.
+Green: `app_token`, `connections_open`, `bot_token`, `auth_test`.
+Log: `[agent-sdk/slack] Socket Mode connected`. Missing tokens
+idle the channel; `serve` continues.
 
-Human:
+1. Invite the bot
+2. `@mention` or DM
+3. Thinking / Working, then a threaded reply
+4. Logs: `inbound kind=app_mention`, `session start`,
+   `reply delivered via postMessage|stream`
 
-1. Invite the bot to a channel
-2. `@mention` it (or DM)
-3. Confirm Thinking… / Working… typing and a threaded reply
-4. Server logs should show correlated lines (`event_id`, `session`, `channel`, `thread_ts`):
-   - `inbound kind=app_mention …`
-   - `session start …`
-   - `reply delivered via postMessage|stream …`
+## Watch channels (opt-in)
 
-## Features (defaults ON)
-
-- Chat streaming (`chat.startStream` / `appendStream` / `stopStream`) with postMessage fallback
-- Thinking / task cards for tool calls
-- `assistant.threads.setStatus` with rotating `loading_messages`
-- Thread title + suggested prompts
-- `markdown_text` when supported
-- Handler `message` / `workspaceFiles` / `cloud` passthrough for PR demos
-
-If a Slack API is unavailable (`method_not_found` / `missing_scope`), the pack falls back to postMessage + setStatus.
-
-## Engagement: mentions by default, channel watch opt-in
-
-The pack dispatches only on `app_mention` + DMs unless told otherwise:
-summoned, never proactive. To watch channels (dispatch on new posts without
-a mention), opt in explicitly:
+Default is mentions + DMs only. To wake on new posts:
 
 ```ts
 export default slackChannel({
+  envPrefix: "JENNY",
   engagement: {
     channelPosts: {
-      allow: ["#issues-cursor-desktop"], // use ["*"] for every joined channel
-      posts: "top-level",       // default — thread replies never dispatch
-      debounceMs: 15_000,       // optional: edits settle, deletes cancel
+      allow: ["#alerts"], // ["*"] for every joined channel
+      posts: "top-level",
     },
   },
   onChannelPost: async (ctx, message) => ({}), // null = skip
 });
 ```
 
-Pass `--channel-posts` on `slack create` or `slack init --manual` so the
-app subscribes to `message.channels` / `message.groups`. Invite the bot to
-each watched channel. Posts mentioning the bot stay on the
-`app_mention` path; watch sessions reuse the thread-scoped principal with an
-`engagement: "channel_post"` attribute, so a later mention continues the
-thread. `engagement.mentions` / `engagement.directMessages` can be set to
-`false` to turn those surfaces off.
-
-## Tool approvals over Slack (opt-in HITL)
+Pass `--channel-posts` on `create` / `init --manual`. Invite the
+bot to each watched channel. Mentions stay on `app_mention`; a
+later mention continues the watch thread.
 
-Tools with `needsApproval` park until a human approves or denies. To route
-that through Slack, set `toolApprovals: true` on `slackChannel`. It posts
-Block Kit Approve/Deny cards and routes Socket Mode `interactive` clicks
-back to the parked call:
+## Approvals (opt-in)
 
 ```ts
 export default slackChannel({
-  credentials: { /* … */ },
+  envPrefix: "JENNY",
   toolApprovals: true,
 });
 ```
 
-Requirements and caveats:
-
-- The Slack app needs **interactivity** enabled. The wizard turns this
-  on when `toolApprovals` is in play; `buildSlackManifest({ interactivity: true })`
-  is the same switch for existing apps.
-- Composing by hand: spread `buildToolApprovalEvents({ credentials })` into
-  `events` **and** set `interactivity: true` on the channel.
-- Cards show **redacted / truncated** args (Block Kit limits); execution
-  uses the full validated input. Review sensitive tools in the playground
-  when args may exceed the card.
-- Approvals only exist for `execution: "server"` tools on the `local`
-  runtime, and parked calls do not survive a host restart.
-- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
-  playground can also list Slack sessions and Approve/Deny
-  their parked tools (audit records the HTTP caller). Production and
-  bearer-auth hosts stay strict: Slack resolve must come from Slack
-  interactivity or a matching principal.
-
-## Notes
-
-- Dev and prod are **separate Slack apps** (separate tokens).
-- Socket Mode is outbound only. No Events HTTP / Request URL path.
-- Do not `await waitForCompletion()` inside Slack dispatch handlers. The pack uses `waitUntil`.
-- Do not share one token pair across multiple agents in the same process.
-
-## CLI reference
-
-Wizard tooling is `create` / `destroy` / `icon` / `doctor`. Manual is
-`init --manual` / `manifest` / `doctor`. `slack setup` prints this
-guide. `slack init` hard-errors unless `--manual`.
-
-```bash
-agent-sdk slack setup
-agent-sdk slack create --dir .                     # dashboard wizard (dev app)
-agent-sdk slack create --dir . --prod              # prod app
-agent-sdk slack create --dir . --slack-team T0123ABCD
-agent-sdk slack destroy --dir . [--prod] [--slack-team T0123ABCD]
-agent-sdk slack init --manual --dir . --name "My Agent"
-agent-sdk slack init --manual --dir . --no-prefix
-agent-sdk slack init --manual --dir . --channel-posts
-agent-sdk slack manifest --env both
-agent-sdk slack doctor --prefix MY_AGENT
-```
+Wizard enables interactivity when this is set. Server tools on
+`local` only. Parked calls die on host restart. Cards truncate
+args; execution uses the full input.

package/src/channels/deployments/types.ts

@@ -7,6 +7,7 @@ export const DEPLOYMENTS_CHANNEL_KIND = "deployments";
 export const DEPLOYMENT_EVENT_TYPES = [
   "deployment.created",
   "deployment.succeeded",
+  "deployment.failed",
 ] as const;
 export type DeploymentEventType = (typeof DEPLOYMENT_EVENT_TYPES)[number];
 

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

@@ -11,6 +11,7 @@ import {
   continuationSource,
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
+import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
 import { isDevMode } from "../../internal/dev-mode.js";
 import { bindLocalIngressSend } from "../../internal/local-ingress.js";
 import type {
@@ -1622,16 +1623,15 @@ async function startTurn(input: {
     scheduleAfterAck(input.args, async () => {
       await sendTurn();
     });
-    return withDispatchOutcome(
-      Response.json(
-        { ok: true, dispatched: true, mode: "turn" },
-        { status: 202 }
-      ),
-      "send"
-    );
+    return acknowledgeTurn();
   }
 
   const session = await sendTurn();
+  if (isDeferredChannelSession(session)) {
+    // Hosted admission captured the send; the control plane allocates the
+    // session after acknowledgement, so there is nothing to report yet.
+    return acknowledgeTurn();
+  }
   return withDispatchOutcome(
     Response.json({
       ok: true,
@@ -1677,12 +1677,27 @@ function scheduleAfterAck(
   );
 }
 
+/** 202 ack for a turn whose send completes after the response flushes. */
+function acknowledgeTurn(): Response {
+  return withDispatchOutcome(
+    Response.json(
+      { ok: true, dispatched: true, mode: "turn" },
+      { status: 202 }
+    ),
+    "send"
+  );
+}
+
 function acknowledgeTask(
   args: ChannelHandlerArgs,
   dispatch: GitHubTaskDispatch,
   extra: Record<string, unknown>
 ): Response {
-  scheduleAfterAck(args, dispatch.task);
+  // Hand the task the per-delivery send/waitUntil so hosted admission can
+  // capture task-initiated sends; startup-captured sends bypass capture.
+  scheduleAfterAck(args, () =>
+    dispatch.task({ send: args.send, waitUntil: args.waitUntil })
+  );
   return withDispatchOutcome(
     Response.json(
       { ok: true, dispatched: true, mode: "task", ...extra },

package/src/channels/github/types.ts

@@ -7,6 +7,7 @@ import type {
   ChannelEventHandlers,
   ChannelStartArgs,
   HostContext,
+  SendMessageFn,
   SendMessageOptions,
 } from "../../types.js";
 import type { GitHubApiOptions } from "./api.js";
@@ -370,13 +371,29 @@ export interface GitHubTurnDispatch {
         | Promise<GitHubWorkspaceFiles | undefined>);
 }
 
+/** Bound per-delivery helpers passed to a {@link GitHubTaskDispatch.task}. */
+export interface GitHubTaskArgs {
+  /**
+   * Start (or resume) a session for this delivery. Locally this runs a real
+   * turn and returns the live session. In hosted admission it captures the
+   * send for the control plane to execute after `ses_…` is allocated and
+   * returns an inert deferred handle, so the task body keeps running.
+   * Always use this over a send captured at `onStart` — a startup-captured
+   * send bypasses hosted capture and is rejected during hosted admission.
+   */
+  send: SendMessageFn;
+  /** Extend the delivery's background window past the task promise. */
+  waitUntil: (promise: Promise<unknown>) => void;
+}
+
 /**
  * Run a host-side handler for the event instead of a model turn. The task
  * runs in the background (`waitUntil`) after the webhook is acknowledged
- * with a 202, so it can outlive GitHub's ~10s delivery timeout.
+ * with a 202, so it can outlive GitHub's ~10s delivery timeout. The callback
+ * receives {@link GitHubTaskArgs}; zero-argument tasks remain valid.
  */
 export interface GitHubTaskDispatch {
-  task: () => void | Promise<void>;
+  task: (args: GitHubTaskArgs) => void | Promise<void>;
 }
 
 export type GitHubDispatchResult =