@cursor/july 0.1.95 → 0.1.96

package/skills/otel/SKILL.md

@@ -1,80 +1,48 @@
 ---
 name: agentsdk-otel
 description: >-
-  Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
-  traces/metrics/logs, ctx.host.otel). Use when adding observability,
-  Datadog/Grafana/OTLP export, session/turn/tool tracing, or custom metrics.
+  Wire OpenTelemetry export (defineOtel, OTLP env, traces/metrics/logs,
+  ctx.host.otel). Use when adding collector export or custom metrics.
 ---
 
 # Agent SDK OpenTelemetry (`defineOtel`)
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+Push traces and metrics from the serve process to an OTLP
+collector. Logs are off until you opt in.
 
-Push session, turn, tool, and subagent traces, plus token and cost
-metrics, from the serve process to an OTLP collector. Logs are off
-until you opt in.
-
-Read [OpenTelemetry](../../docs/guides/opentelemetry.md) for the full
-guide, including how this joins Cursor enterprise export.
+Guide: `docs/guides/opentelemetry.md`.
 
 ## Enable
 
 Any one of:
 
-1. **Env.** Set `OTEL_EXPORTER_OTLP_ENDPOINT` (and optional
+1. `OTEL_EXPORTER_OTLP_ENDPOINT` (optional
    `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
-   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`).
-   Per-signal URLs work when the base URL is unset:
-   `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `_METRICS_ENDPOINT` /
-   `_LOGS_ENDPOINT`.
-2. **Authored.** `agent/otel.ts`:
+   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`)
+2. `agent/otel.ts`:
 
 ```ts
 import { defineOtel } from "@cursor/july/otel";
 
 export default defineOtel({
   serviceName: "cursor",
-  exporters: [
-    {
-      url: "https://otel.example.com",
-      protocol: "http/protobuf",
-      headers: { Authorization: "Bearer …" },
-    },
-  ],
+  exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
 });
 ```
 
-3. **Programmatic.** `serve(dir, { otel: { … } })`. Pass `otel: false`
-   to disable even when env or `agent/otel.ts` are set.
-
-Multiple `exporters` fan out. Default protocol is `http/protobuf`.
-Use `http/json` only when the collector requires it. `grpc` is ignored.
-
-Precedence: `serve({ otel })` over `agent/otel.ts` over env.
-
-## Signals
-
-| Signal | Default | What |
-| --- | --- | --- |
-| Traces | on | `agent_sdk.http` → `agent_sdk.session` → `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
-| Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` counts and HTTP duration |
-| Logs | off | Opt in with `logs: true`, `OTEL_LOGS_EXPORTER=otlp`, or `OTEL_LOG_USER_PROMPTS=1` / `OTEL_LOG_TOOL_CONTENT=1` |
+3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
+   authored config.
 
-Prompt text, tool payloads, and failure text stay off the wire unless
-those flags are set.
+| Signal | Default |
+| --- | --- |
+| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
+| Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
-## Custom metrics (`ctx.host.otel`)
+Prompt text and tool payloads stay off the wire unless you set
+`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`.
 
-Always present. `increment` / `record` no-op without a meter.
-`setAttributes` still tags the open session when a collector is
-attached. Prefix names with team or agent. No custom spans. Reserved
-metric names: `cursor.token.usage`, `cursor.tool.calls`,
-`cursor.cost.usage`, `agent_sdk.session.count`,
-`agent_sdk.turn.count`, `agent_sdk.subagent.count`,
-`agent_sdk.http.duration`. Reserved attributes:
-`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
-`agent_sdk.framework`.
+## Custom metrics
 
 ```ts
 ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
@@ -82,20 +50,6 @@ ctx.host.otel.increment("abc.ticket.resolved");
 ctx.host.otel.record("abc.approval.duration_ms", 1420);
 ```
 
-## Attributes worth joining on
-
-- `cursor.conversation.id` (session id)
-- `cursor.tool.name` / `cursor.tool.kind` / `cursor.tool.status`
-- `cursor.token.type`, `cursor.model.name`
-- `agent_sdk.agent`, `agent_sdk.turn_id`, `agent_sdk.call_id`, `agent_sdk.channel`
-
-Resource defaults: `service.name=cursor`, `cursor.entrypoint=sdk_ts`,
-`cursor.surface=unspecified`.
-
-Inbound HTTP extracts W3C `traceparent`, so a channel request parents
-the session span when the turn starts in that request.
-
-If another TracerProvider already owns the process (CLI / IDE), Agent
-SDK reuses it. Run `serve` as its own process when Agent SDK should
-own the destination. Conflicting `agent/otel.ts` files across mounts
-fail at serve start.
+Prefix names with team or agent. No custom spans. Join on
+`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
+own process when Agent SDK should own the destination.

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];