@cursor/july 0.1.90 → 0.1.91

package/docs/example-agents/weather-agent.md

@@ -1,14 +1,13 @@
 ---
 title: "Explore the full Agent SDK surface with a weather agent"
-description: "Trace cloud server tools, MCP, channels, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."
+description: "Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."
 ---
 
 # Explore the full Agent SDK surface with a weather agent
 
 The weather agent is the broadest small example in the repository. It fetches
 live conditions and forecasts, converts units through MCP, writes notes in a
-session workspace, and pauses an alert tool for human approval. The same agent
-also runs from HTTP, Slack, a schedule, and the MCP endpoint.
+session workspace, and runs from HTTP, Slack, a schedule, and the MCP endpoint.
 
 Use this project when you want to see how the Agent SDK's filesystem pieces fit
 together before you design a larger agent.
@@ -17,19 +16,19 @@ together before you design a larger agent.
 
 ## See the runtime features together
 
-Most examples focus on one architecture. Weather agent puts the major runtime
+Most examples focus on one feature. Weather agent puts the major runtime
 features side by side:
 
 | Capability | Source | Role |
 | --- | --- | --- |
 | Root config and instructions | [`agent/agent.ts`](../../examples/weather-agent/agent/agent.ts), [`agent/instructions.md`](../../examples/weather-agent/agent/instructions.md) | Select the cloud runtime and route each request. |
-| Server tools | [`agent/tools/`](../../examples/weather-agent/agent/tools/) | Execute on the Agent SDK host through authenticated HTTP MCP, fetch Open-Meteo data, call MCP, and model an approval-gated action. |
+| Server tools | [`agent/tools/`](../../examples/weather-agent/agent/tools/) | Fetch Open-Meteo data and call MCP from the serve host. |
 | Agent tool | [`save_weather_note.ts`](../../examples/weather-agent/agent/tools/save_weather_note.ts) | Run a Python script inside the session workspace. |
 | Stdio MCP | [`units.ts`](../../examples/weather-agent/agent/mcp-connections/units.ts), [`probe.ts`](../../examples/weather-agent/agent/mcp-connections/probe.ts) | Expose conversion tools to the model, host tools, and channel handlers. Author VM-side probe tools as TypeScript `execute` functions. |
 | Custom HTTP | [`webhook.ts`](../../examples/weather-agent/agent/channels/webhook.ts) | Start a turn or call MCP without a model turn. |
-| Slack | [`slack.ts`](../../examples/weather-agent/agent/channels/slack.ts), [`slack-app.ts`](../../examples/weather-agent/agent/channels/slack-app.ts) | Compare account-linked chat with a dedicated app offering approval buttons. |
+| Slack | [`slack.ts`](../../examples/weather-agent/agent/channels/slack.ts), [`slack-app.ts`](../../examples/weather-agent/agent/channels/slack-app.ts) | Compare account-linked chat with a dedicated app. |
 | Skill and subagent | [`forecast.md`](../../examples/weather-agent/agent/skills/forecast.md), [`researcher/`](../../examples/weather-agent/agent/subagents/researcher/) | Load a procedure on demand or delegate broad research. |
-| Schedule and hook | [`heartbeat.md`](../../examples/weather-agent/agent/schedules/heartbeat.md), [`audit.ts`](../../examples/weather-agent/agent/hooks/audit.ts) | Start recurring task sessions and observe completed turns. |
+| Schedule and hooks | [`heartbeat.md`](../../examples/weather-agent/agent/schedules/heartbeat.md), [`audit.ts`](../../examples/weather-agent/agent/hooks/audit.ts), [`journal.ts`](../../examples/weather-agent/agent/hooks/journal.ts) | Start recurring tasks, log usage, and save turn summaries. |
 | A/B and evals | [`agent/ab.ts`](../../examples/weather-agent/agent/ab.ts), [`evals/`](../../examples/weather-agent/evals/) | Compare a sticky variant and protect tool routing with regression cases. |
 
 ## Follow one request
@@ -65,7 +64,7 @@ The project mounts an account-linked Slack channel. The Agent SDK checks the
 connection at startup, so sign in even when you plan to call a deterministic
 tool.
 
-The optional approval-enabled Slack app also needs a token pair.
+The optional dedicated Slack app also needs a token pair.
 `agent-sdk slack create --dir examples/weather-agent` provisions the
 app and writes the tokens for you (see the
 [Slack guide](../guides/slack.md#set-it-up)); with hand-minted tokens,
@@ -88,9 +87,8 @@ agent-sdk info --dir examples/weather-agent --json
 agent-sdk eval --dir examples/weather-agent --list
 ```
 
-The manifest should report eight tools, one skill, two MCP connections, one
-subagent, three authored channels, one schedule, one hook, and one A/B
-experiment. The eval listing should report eight cases.
+`validate` should pass. `info` and `eval --list` should match the capabilities
+described above.
 
 ## Call the typed tools
 
@@ -134,10 +132,8 @@ agent-sdk run --dir examples/weather-agent \
 Each session gets its own workspace. Saving a note doesn't edit the authored
 example.
 
-This split matters on cloud. Server tools execute on the Agent SDK host through
-an authenticated HTTP MCP endpoint while retaining the active session context.
-For an agent tool, the Agent SDK includes its catalog and script body in the
-first prompt; the cloud model writes and invokes the script in its VM.
+This split matters on cloud. Server tools stay on the Agent SDK host.
+Agent tools run inside the cloud workspace.
 
 ## Verify tool execution on the agent VM
 
@@ -224,30 +220,6 @@ This is the custom-channel version of a continuation token. See
 [webhooks and custom channels](../guides/webhooks.md) for route schemas,
 authentication, and asynchronous handlers.
 
-## Pause a tool for human approval
-
-`post_weather_alert` sets `needsApproval: true`. Ask for an ops alert in the
-playground and the model's tool call parks before `execute`:
-
-```bash
-agent-sdk dev examples/weather-agent
-```
-
-Open the printed playground URL, ask:
-
-> Alert ops that severe weather is approaching Boston.
-
-Approve or deny the call in the transcript. The dedicated Socket Mode Slack
-channel can show the same buttons when `toolApprovals: true` and Slack
-interactivity are configured.
-
-The example tool returns a placeholder success object. It doesn't contact
-Slack, PagerDuty, or an ops board. Replace its `execute` body with your own
-sink before adapting it.
-
-Use a model turn for this proof. A deterministic `agent-sdk call` runs the
-tool body directly and doesn't demonstrate the parked approval flow.
-
 ## Load procedures and delegate research
 
 The forecast skill gives the root agent an on-demand procedure. The Agent SDK
@@ -303,19 +275,16 @@ agent-sdk eval --dir examples/weather-agent --list
 agent-sdk eval --dir examples/weather-agent --json
 ```
 
-Five cases cover current weather and forecasts against live Open-Meteo. Three
-more cover the local MCP converter, the workspace note tool, and the VM-side
-probe. Together they test model routing, external data, host MCP, agent-side
-execution, and stdio MCP in the agent environment.
+The suite covers weather and forecast routing, the local converter, workspace
+notes, and the VM-side probe.
 
 ## Turn the weather tour into your own agent
 
-Keep the architecture and replace the domain:
+Keep the shape and replace the domain:
 
 - Swap Open-Meteo tools for your typed service clients.
 - Keep deterministic transforms behind direct server tools or MCP.
 - Use an agent tool only when code must run in the agent workspace.
-- Gate side effects with `needsApproval`.
 - Put reusable procedures in skills and narrow specialist work into
   subagents.
 - Add a channel only when the external surface needs its own identity,

package/docs/guides/github.md

@@ -53,6 +53,9 @@ permission on `"contents-write"` tokens. Enabling `commitStatus` opts a
 `"pr-write"` without `commitStatus` is enough for comments and banners.
 Prefer `"pr-write"` unless the agent must push or post a merge-box check.
 
+Set `checks: true` when channel code posts its own Checks API runs through
+`ctx.github.createCheck`. The flag grants access. It does not post a check.
+
 Selected repositories must share one GitHub owner (one App installation).
 Configuration that spans owners fails at startup / mint time.
 
@@ -166,10 +169,10 @@ agent-sdk github replay owner/repo#123 --dir . --events '*' --conclusion failure
 agent-sdk github replay owner/repo#123 --dir . --events '*' --dry-run --out fixtures/github
 ```
 
-`--events` defaults to `pull_request`, and `'*'` means the channel's
-declared set. `--action`, `--conclusion`, `--comment`, and `--context`
-shape each synthesized event. `--secret` (or `GITHUB_WEBHOOK_SECRET`)
-signs them.
+`--events` defaults to `pull_request`. `'*'` replays the events the channel
+declares and the CLI can synthesize. `--action`, `--conclusion`, `--comment`,
+and `--context` shape each event. `--secret` or `GITHUB_WEBHOOK_SECRET` signs
+them.
 
 ## Receive webhooks directly
 

package/docs/guides/slack.md

@@ -65,7 +65,7 @@ export default slackChannel({
 Sign the host in (`agent-sdk login` or `CURSOR_API_KEY`), then mention the
 agent in Slack as `@Cursor Weatherbot …`. Thread replies and DMs keep going to
 the same agent. Messages appear as the Cursor app under that agent's name
-and icon, with live updates as the turn progresses.
+and icon. Slack shows its working status, then posts one final reply.
 
 Use a dedicated Socket Mode Slack app when you need your own bot user,
 channel watching (`engagement.channelPosts`), or approval buttons. On
@@ -230,7 +230,7 @@ export default slackChannel({
   engagement: {
     // mentions / directMessages default to true
     channelPosts: {
-      allow: ["#triage-alerts"], // explicit allowlist; no wildcard exists
+      allow: ["#triage-alerts"], // use ["*"] for every joined channel
       posts: "top-level",       // default: thread replies never dispatch
       debounceMs: 15_000,       // optional: let rapid edits settle
       includeBotPosts: false,   // default: bot-authored posts never dispatch
@@ -249,6 +249,8 @@ on the Slack app (Socket Mode only; not available with
 `slack init --manual`. The bot must also be a member of each watched
 channel.
 
+Set `allow: ["*"]` to watch every channel the bot has joined.
+
 Set `includeBotPosts: true` when the posts worth watching come from bots:
 alert feeds, webhook integrations, or other agents posting notes. The
 watching app's own posts stay dropped either way, matched by the `bot_id`
@@ -265,6 +267,9 @@ Mention and DM handlers may return a prepared `message`,
 PR agents use it: extract a PR URL from the mention text and run the
 same host path as the HTTP channel.
 
+Slack file uploads are attached automatically. Images become vision input.
+Supported documents become workspace files for the turn.
+
 ## Add approval buttons
 
 Tools with `needsApproval` park until a person decides. Route that

package/docs/guides/webhooks.md

@@ -166,10 +166,10 @@ export default defineChannel({
 
 The built-in policies are `localDevStrict()` (the default),
 `localDev()`, `loopbackOnly()`, `bearerAuth(tokenOrVerify)`, and
-`allowAll()`, and any `(request, info) => AuthContext | null` function
-composes with them. Signature-verified surfaces usually use `allowAll()`
-at the route and verify the HMAC in the channel; the GitHub channel with
-a webhook secret works this way. The details live in
+`allowAll()`, and `publicEndpoint()`. Any
+`(request, info) => AuthContext | null` function composes with them.
+
+The details live in
 [Channels](../reference/channels.md#auth-policies).
 
 Server-level flags interact with channel auth. `--bearer-token <secret>`
@@ -177,17 +177,15 @@ swaps the default for `bearerAuth` on every channel that doesn't author
 its own chain, and `--allow-anonymous` swaps it for `allowAll()`
 (trusted networks only). Authored `auth` arrays always win over both.
 
-## Hosted aliases need an alias-token relay
+## Receive signed webhooks on managed hosting
 
 Cursor-managed deployments expose a stable alias URL. External callers
-must send `X-Agent-Alias-Token` on every request to that URL. Channel
-auth still runs after the alias gate.
+normally send `X-Agent-Alias-Token` on every request. Webhook providers
+often cannot set it.
 
-Webhook providers that cannot attach custom headers cannot POST
-straight at a managed alias. Put a relay (or other authenticating
-intermediary) in front, use a Cursor-managed ingress path that does not
-use the public alias (for example Cursor Slack / GitHub event relay),
-or self-host. See [Deployment](../deployment.md#use-the-hosted-agent).
+Add `publicEndpoint()` to a custom channel that verifies its own provider
+signature. Only that channel path skips the alias token. Session and tool
+routes stay private. See [Deployment](../deployment.md#use-the-hosted-agent).
 
 ## Example: Linear as the control plane
 
@@ -218,7 +216,7 @@ Author `agent/channels/linear.ts`:
 ```ts
 import { Buffer } from "node:buffer";
 import { createHmac, timingSafeEqual } from "node:crypto";
-import { allowAll, defineChannel, POST } from "@cursor/july/channels";
+import { defineChannel, POST, publicEndpoint } from "@cursor/july/channels";
 import { z } from "zod";
 
 const secret = process.env.LINEAR_WEBHOOK_SECRET ?? "";
@@ -275,8 +273,7 @@ function issueIdFromToken(token: string | null): string | null {
 }
 
 export default defineChannel({
-  // The HMAC check is the request auth, so admit everything at the route.
-  auth: [allowAll()],
+  auth: [publicEndpoint()],
   routes: [
     POST("/", {
       description: "Linear webhook ingress",

package/docs/reference/channels.md

@@ -188,6 +188,10 @@ non-null wins, and a request no policy admits gets `401`.
 | `loopbackOnly()`    | A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like `gh webhook forward`.                                                                                                                                                                                                                                  |
 | `bearerAuth(token)` | `Authorization: Bearer <token>`, compared in constant time. Also accepts a verifier function mapping a presented token to an `AuthContext`.                                                                                                                                                                                                                |
 | `allowAll()`        | Everyone, as an `anonymous` principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.                                                                                                                                                                                                                            |
+| `publicEndpoint()`  | Everyone on this custom channel. Managed hosting also serves the channel without an alias token. Use it only when the handler verifies the provider signature.                                                                                                                                                                                             |
+
+`publicEndpoint()` applies only to custom channel routes. It does not open
+the built-in session or tool API.
 
 The resolved `AuthContext` (`{ authenticator, principalId,
 principalType, attributes? }`) becomes the request principal. Sessions

package/docs/reference/cli.md

@@ -45,6 +45,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`deployments`](#deployments)                           | List hosted deployments                                        |
 | [`deployment`](#deployment)                             | Inspect one hosted deployment                                  |
 | [`stop`](#stop)                                         | Stop a hosted deployment                                       |
+| [`delete`](#delete)                                     | Delete a hosted deployment                                     |
 | [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
 | [`rotate-pod-credential`](#rotate-pod-credential)       | Replace a deployment's pod credential                          |
 | [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
@@ -104,7 +105,7 @@ agent-sdk serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
 If `--dir` is an agent project, it mounts under its directory name. If
 it contains agent projects, each child mounts separately. The index
 lives at `/`. Each agent is available at `/<slug>/v1/*` and
-`/<slug>/playground`. On a TTY, press Enter to reload agent code.
+`/<slug>/playground`. On a TTY, press Enter to restart.
 Unless `--state-root` is set, each mount uses
 `<agent-project>/.agent-serve`; slugged mounts use
 `<agent-project>/.agent-serve/<slug>`.
@@ -399,8 +400,9 @@ between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
 | `--no-wait` | Return with the Eval ID as soon as a `--prod` or `--url` batch is accepted. |
 | `--timeout-ms <n>` | Per-case timeout override. |
 
-Failed cases exit `1`; no matching cases exit `2`. See
-[Evals](../evals.md).
+Failed cases exit `1`. A scored case also exits `1` under `--strict`.
+No matching cases exit `2`. `eval status` exits `3` while the remote batch
+is still running.
 
 ## trajectory
 
@@ -452,9 +454,9 @@ the browser flow. It then prints the `cd`, `agent-sdk login`, and
 `agent-sdk dev` steps still needed.
 
 With `--json`, `init` still installs dependencies but never blocks on
-login or skill installation. It prints
-`{ ok, directory, created, skipped, installed, installError, next }`
-(with `login` in `next` when unsigned).
+login or skill installation. It prints `{ ok, directory, template, created,
+skipped, installed, installError, cliOnPath, cliLinkError, next }`. The
+`next` list includes `login` when the host is unsigned.
 
 ## convert-automation
 
@@ -673,6 +675,17 @@ agent-sdk stop <slug> [--team <id>] [--no-wait] [--json]
 The command polls for up to ten minutes until the status reaches
 `stopped`. `--no-wait` returns after the stop request is accepted.
 
+## delete
+
+`delete` removes a deployment.
+
+```bash
+agent-sdk delete <slug> [--team <id>] [--no-wait] [--json]
+```
+
+The command waits until the deployment is gone. `--no-wait` returns after
+the delete request is accepted.
+
 ## rotate-token
 
 `rotate-token` replaces the alias token used by callers and the hosted
@@ -807,7 +820,8 @@ agent-sdk slack setup
 agent-sdk slack create [--dir <path>] [--name <name>] [--prod]
                       [--slack-team <T…>] [--team <id>]
                       [--icon <https-url-or-file>]
-                      [--prefix <prefix> | --no-prefix] [--json]
+                      [--prefix <prefix> | --no-prefix]
+                      [--channel-posts] [--json]
 agent-sdk slack destroy [--dir <path>] [--prod] [--slack-team <T…>]
                        [--team <id>] [--json]
 agent-sdk slack icon <https-url-or-file> [--dir <path>] [--prod]

package/docs/reference/connections.md

@@ -104,17 +104,9 @@ attaching them without an identity.
 
 ## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
 
-Attached MCP servers sit behind the harness MCP meta-tools. The model does
-not see names like `Datadog-search_datadog_dashboards` until you set
-`advertiseTools: true`. Use that flag when playground or local chat should
-call the tools by name.
-
-The engine lists the connection at turn-build time and synthesizes a named
-1:1 passthrough server tool per entry, using the server's names,
-descriptions, and live schemas. Those merge into the authored
-`agent/tools/` catalog. The raw connection is then not attached to the
-model (it stays available on `host.mcp`), so each tool appears exactly
-once.
+Set `advertiseTools: true` when the model should call an MCP server's tools
+by name. The Agent SDK preserves each tool's name, description, input and
+output schemas, and MCP annotations.
 
 ```ts
 export default defineConnection({
@@ -124,20 +116,12 @@ export default defineConnection({
 });
 ```
 
-Fail-closed, by design: a `listTools` failure, an invalid tool name, or a
-name collision (with an authored tool or another advertised connection)
-fails the turn. A turn never silently runs with a shrunken toolset.
-Listing runs once per turn, so point this at endpoints that answer
-`tools/list` cheaply. Connections with `auth` are listed and called
-through one-off clients carrying that session's headers. Auth-less ones
-(including Cursor account connections) go through the shared host
-registry. Local runtime only, like all server tools, and not combinable
-with `hostOnly`. Advertising puts the tools in the model's toolset.
-`hostOnly` keeps them off the model. `GET /v1/info` reports
-`advertiseTools` on the connection. The per-tool list is built per turn,
-not on the static catalog, the peer-agent MCP server, or cloud
-`agentsdk-tools`, and those advertised tools cannot be invoked via direct
-tool calls.
+A listing failure, invalid tool name, or name collision fails the turn.
+Advertised tools follow the same runtime support as server tools. They cannot
+be combined with `hostOnly` or called through the direct tool API.
+
+In a dry-run session, MCP tools marked read-only run normally. Tools marked
+as writes are stubbed. Tools without effect annotations are unavailable.
 
 ## Local stdio MCP server
 
@@ -212,13 +196,10 @@ The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
 `serve` fails fast at startup otherwise, and logs each connector's live
 status (`connected`, `needsAuth`, `error`) as it starts.
 
-Local turns and host-side calls go through a loopback bridge guarded by
-a per-startup secret. Cloud-runtime turns reach the same bridge through
-the serve `--public-url`, so `servers` filters apply there too. A
-cloud-capable agent that combines a concrete `servers` allowlist with no
-`--public-url` fails at startup rather than running unfiltered. Backend
-execution covers the account's HTTP/SSE servers. Stdio servers can't run
-server-side, so author a `{ command }` MCP connection for those.
+Filtered account connections work on managed cloud deployments. A
+self-hosted cloud agent with a concrete `servers` list needs `--public-url`.
+Serve fails instead of ignoring the filter. Use a `{ command }` connection
+for stdio servers.
 
 > [!CAUTION]
 > Whoever can talk to the agent can drive these connectors, because they

package/docs/reference/http-api.md

@@ -49,6 +49,14 @@ The response returns as soon as the message is accepted; follow the
 stream for progress. The continuation token is the follow-up credential,
 and `playgroundUrl` deep-links the session in the playground.
 
+| Body field | Meaning |
+| --- | --- |
+| `message` | Required user message |
+| `title` | Session title |
+| `dryRun` | Run read tools and stub write tools |
+| `workspaceFiles` | UTF-8 files written into the session workspace |
+| `cloud` | Per-session cloud options merged over the agent defaults |
+
 ## Send a follow-up
 
 `POST /v1/session/:sessionId` continues an existing conversation.
@@ -62,13 +70,10 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
 Works for any chat session, including ones created by custom channels.
 Each accepted follow-up rotates the token, and the response carries the
 new one. Sending to a busy session interrupts the in-flight turn, waits
-for it to settle, then sends; when the turn can't be interrupted (for
-example, concurrent follow-ups racing), the request returns
-`409 session_busy`.
+for it to settle, then sends.
 
-Expect `409` on a stale token, an uninterruptible busy session, or a
-task/schedule session (those aren't followable), and `403` when the
-caller isn't the session owner.
+Expect `409` on a stale token or a task session. Task sessions do not accept
+follow-ups. Expect `403` when the caller is not the session owner.
 
 ## Stream a session
 
@@ -85,8 +90,8 @@ resume without duplicates. The stream is durable and reconnectable. For
 the vocabulary, see
 [Sessions](./sessions.md#which-events-can-i-stream).
 
-`GET /v1/session/:sessionId/events` returns the same content as a
-one-shot dump with no live follow.
+`GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump.
+Pass `?format=json` for `{ sessionId, events, playgroundUrl }`.
 
 ## Stop and list
 
@@ -254,7 +259,7 @@ Error responses use a small, consistent set of status codes.
 | `403` | Authenticated, but not the session owner                                                                                   |
 | `404` | Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request                              |
 | `405` | Wrong method (GET on the MCP endpoint, say)                                                                                |
-| `409` | Stale continuation token, busy session (`session_busy`), a non-followable task session, or an eval run already in progress |
+| `409` | Stale continuation token, a busy session-bound tool call, a non-followable task session, or an eval run already in progress |
 | `202` | Accepted for background work (GitHub `{ task }` hooks, eval runs)                                                          |
 
 ## What's next

package/docs/reference/tools.md

@@ -115,7 +115,6 @@ export default defineTool({
   description: "Read the current weather.",
   inputSchema: z.object({ city: z.string() }),
   outputSchema: Weather,
-  effect: "read",
   async execute({ city }) {
     return { city, temperatureF: 72 };
   },
@@ -148,8 +147,7 @@ export default defineTool({
 ```
 
 `dryRunResult` keeps the result shape stable. Without it, a stubbed write
-returns `"Operation acknowledged."`. Its `action.result` event has
-`stubbed: true`.
+returns `"Operation acknowledged."`. Traces mark the result as stubbed.
 
 ## Define an agent tool
 

package/docs/templates/triage.md

@@ -67,11 +67,9 @@ curl -X POST http://127.0.0.1:3000/triage-agent/v1/channels/queue/issue \
 `POST /v1/channels/queue/issue` accepts
 `{ identifier, title?, description? }` from the playground.
 
-Hosted Cursor aliases require `X-Agent-Alias-Token`, which Linear and
-Jira cannot send. For create webhooks, self-host, set
-`LINEAR_WEBHOOK_SECRET` or `JIRA_WEBHOOK_SECRET`, and POST the signed
-body to `/v1/channels/webhook`. The channel ACKs immediately and
-coalesces retries onto the same issue.
+For create webhooks, set `LINEAR_WEBHOOK_SECRET` or
+`JIRA_WEBHOOK_SECRET`. Point the provider at the deployed alias under
+`/v1/channels/webhook`. Signed events start or resume triage for that issue.
 
 `record_triage` comments on the issue in the continuation key, not
 whatever identifier the model copies out of the ticket body.

package/docs/troubleshooting.md

@@ -41,7 +41,7 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 
 | What you see | What to do |
 | --- | --- |
-| `409` on a follow-up message | Refresh the `continuationToken` (it rotates on each accepted follow-up), wait if the session is busy, or confirm the session is a chat session (task and schedule sessions are not followable). |
+| `409` on a follow-up message | Refresh the `continuationToken` or confirm the session is a chat session. Task sessions do not accept follow-ups. |
 | `409 session_busy` on `call --session` | Wait for the model turn to finish, or omit `--session` for a one-off call. |
 | `403` on stream or follow-up | Use the same auth identity that created the session. Off localhost, pass `--bearer-token` and send it on every request. |
 | Works on localhost; blocked through a tunnel or LAN | Default auth allows only direct loopback callers. Share the host with `--bearer-token <secret>` (or authored `bearerAuth`). Use `--allow-anonymous` only on a trusted private network. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.90",
+  "version": "0.1.91",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/skills/create-agent/SKILL.md

@@ -59,11 +59,11 @@ questions, concrete options, the recommended option listed first and labeled
 
 | Question | Options | Guidance |
 | --- | --- | --- |
-| **Runtime** | `local` (default) · `cloud` | Local = Cursor SDK harness on this machine; server tools, skills, sandbox seeds, and tool approvals all work. Cloud = Cursor cloud agents; needs `cloud.repos`, no server tools/skills/sandbox seeds (instructions are prepended to the first prompt). Recommend local unless the purpose needs a repo checkout on a cloud VM. |
+| **Runtime** | `local` (default) · `cloud` | Local runs on this machine. Cloud runs on a Cursor cloud agent and needs `cloud.repos`. Server tools and skills work on both. Tool approvals and sandbox seeds are local only. Recommend local unless the purpose needs a cloud checkout. |
 | **Model** | `grok-4.5` with `effort=high`, `fast=true` (default) · Other model id | Effort and fast are params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` — the SDK rejects suffix-style ids. |
 | **Channels** (multi) | playground + HTTP API only (always mounted) · Slack · GitHub webhooks · custom webhook · schedule (cron) | Slack has two connections: the Cursor-hosted connection (`cursorAccount: true` — zero Slack admin, recommended default) and a dedicated Socket Mode app (own bot user + one app/token pair per agent; needed for channel watching or approval buttons). When Slack is picked, resolve the connection with the Step 0 gate in `setup-slack/SKILL.md` — either fold its AskQuestion into this round or ask it before channel setup; default to Cursor-hosted when you cannot ask. GitHub verifies `X-Hub-Signature-256` when a secret is set. Discord/Teams packs do not exist yet — offer custom webhook instead. |
 | **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Cursor account connectors · Other | One file per server under `agent/mcp-connections/`; filename = server name. Do not name an account connection `cursor.ts` (collides with the IDE `cursor` namespace); use `account.ts`. Tokens via env vars, never hardcoded. Connections serve the model and host code (`ctx.host.mcp`). If the model should call them by name on local turns, set `advertiseTools: true`. Set `hostOnly: true` only when host tools call the server and the playground must not. |
-| **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Server tools, skills, sandbox seeds, approvals are local-runtime only. Agent tools (`execution: "agent"`) work on both runtimes. Always recommend at least one smoke eval. |
+| **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Always recommend at least one smoke eval. |
 
 Close the round with a one-screen plan — chosen options plus the file tree you
 intend to create — and a final gate: "Scaffold it" / "Adjust something". Only
@@ -144,9 +144,8 @@ agent-sdk init ./<slug>
 
 `init` writes `package.json` (with `typescript` dev deps and a
 `check` script), `tsconfig.json`, `AGENTS.md`, `.gitignore`, `agent/agent.ts`,
-`agent/instructions.md`, a demo `agent/tools/echo.ts`, and empty capability
-folders (`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
-files are left alone (`exist`) and missing ones are filled in. It then
+`agent/instructions.md`, a demo `agent/tools/echo.ts`, and
+`agent/hooks/memory.ts`. Existing files are left alone (`exist`). It then
 runs `npm install`, and when the host is unsigned runs `login` and waits
 before printing `cd` (when needed) and `agent-sdk dev`. Then shape it to the
 plan:
@@ -261,8 +260,8 @@ loop starts deterministic.
 
 - Interview → plan gate → scaffold → verify → channel setup → hillclimb
   handoff. Do not skip verification because the files "look right".
-- Fill blanks yourself; re-ask only when an answer contradicts the framework
-  (e.g. server tools on cloud runtime — `validate` warns about these).
+- Fill blanks yourself. Re-ask only when an answer contradicts the framework,
+  such as approval-gated tools on the cloud runtime.
 - Do not deploy, post to real Slack/GitHub surfaces beyond the smoke tests the
   user asked for, or commit without being asked.
 - Keep the first cut reviewable: if the plan grows past ~10 files, cut scope

package/skills/framework-map/SKILL.md

@@ -77,10 +77,11 @@ the serve host; `runtime: "cloud"` runs them on Cursor cloud agents
 
 | Capability | local | cloud |
 | --- | --- | --- |
-| Server tools (`execution: "server"`), approvals | yes | **no** |
+| Server tools (`execution: "server"`) | yes | yes on managed hosting; self-hosted needs `--public-url` |
+| Tool approvals | yes | no |
 | Agent tools (`execution: "agent"` scripts) | yes | yes |
-| Skills | yes | yes (Agent Store native discovery) |
-| sandbox seeds | yes | only if in the cloud repo |
+| Skills | yes | yes |
+| sandbox seeds | yes | no |
 | Instructions | `AGENTS.md` in session workspace | prepended to first prompt |
 | Checkout of a repo/PR | you arrange it | the VM carries it |
 
@@ -93,9 +94,8 @@ scale, use cloud and keep the host to routing, briefs, and bookkeeping.
 
 Two handles, two owners:
 
-- **continuationToken** — channel-owned conversation key. Same token =
-  same durable session (a Slack `channelId:threadTs`, a `pr:owner/repo#N`).
-  Rotates on each accepted HTTP follow-up; stale tokens get `409`.
+- **continuationToken:** credential for continuing a conversation. HTTP
+  follow-ups rotate it; stale tokens get `409`.
 - **sessionId** — runtime-owned handle for streaming/inspection
   (`GET /v1/session/:id/stream?startIndex=N`, durable NDJSON replay).
 

package/skills/setup-slack/SKILL.md

@@ -303,7 +303,7 @@ a mention), opt in explicitly:
 export default slackChannel({
   engagement: {
     channelPosts: {
-      allow: ["#issues-cursor-desktop"], // explicit allowlist; no wildcard exists
+      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
     },

package/src/channels/slack/channel-watch.ts

@@ -2,7 +2,7 @@
  * Opt-in channel watch: dispatch on posts in allowlisted channels.
  *
  * Filtering rules (the anti-slop guarantees):
- * - Only explicitly allowlisted channels are watched — no wildcard.
+ * - Only configured channels are watched; `"*"` opts into every channel.
  * - Top-level posts only by default; thread replies never dispatch unless
  *   `posts: "all"` is configured.
  * - Posts that @mention the bot are skipped here (the `app_mention` path

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

@@ -233,7 +233,7 @@ export function slackChannel<const Name extends string = string>(
     const entries = channelPosts.allow.filter((entry) => entry.trim() !== "");
     if (entries.length === 0) {
       throw new Error(
-        "slackChannel engagement.channelPosts.allow must list at least one channel (id or #name); there is no wildcard watch."
+        'slackChannel engagement.channelPosts.allow must list at least one channel (id, #name, or "*").'
       );
     }
   }

package/src/channels/slack/types.ts

@@ -324,10 +324,8 @@ export type SlackBlockActionHandler = (
   | Promise<SlackDispatchDecision | null | undefined>;
 
 /**
- * Opt-in channel watch: dispatch on posts in explicitly allowlisted
- * channels without requiring an @mention. There is deliberately no
- * "every channel the bot is in" wildcard — watching a channel is a
- * per-channel decision.
+ * Opt-in channel watch: dispatch on posts in configured channels without an
+ * @mention. Use `"*"` for every channel the bot has joined.
  */
 export interface SlackChannelPostsOptions {
   /**