@cursor/july 0.1.111 → 0.1.113

package/docs/guides/cloud-agents.md

@@ -1,26 +1,26 @@
 ---
 title: "Cursor cloud agents"
-description: "Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."
+description: "Mount an extension that lets your agent delegate repository work, inspect the result, and steer or stop the cloud agent."
 ---
 
 # Cloud agents
 
-The `cursor-cloud-agents` extension lets an agent delegate coding work
-to Cursor cloud agents and stay in the conversation while they do it.
-The cloud agents work on real repository checkouts and push branches and
-pull requests; your agent hands off the task, reports back, and answers
-questions in the meantime. A Slack triage agent turns a bug report into
-a PR, a planner fans a refactor out across repositories, a reviewer asks
-a cloud agent to address its own comments.
+The `cursor-cloud-agents` extension adds repository delegation to an
+existing Agent SDK conversation. Your agent can launch a Cursor cloud
+agent, keep talking while it works, inspect the result, and steer or
+stop the same branch.
 
-This is different from
-`[runtime: "cloud"](../reference/agent-config.md#choose-a-runtime)`. The
-runtime moves *this* agent's turns onto a cloud VM. The extension keeps
-the agent where it is and lets it start *other* cloud agents.
+This is different from choosing
+[`runtime: "cloud"`](../reference/agent-config.md#choose-a-runtime).
+That setting moves this agent's turns to a cloud VM; this extension lets
+the agent delegate separate coding tasks.
 
 ## Mount it
 
-The extension ships with `@cursor/july`. Mount it with one file.
+Mount the extension under a namespace, list every repository it may
+touch, and choose whether launches need approval. This example makes the
+boundary explicit even though a configured repository list would
+otherwise turn approval off by default.
 
 ```ts
 // agent/extensions/cloud.ts
@@ -28,75 +28,127 @@ import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
 
 export default cursorCloudAgents({
   cloud: {
-    repos: [{ url: "https://github.com/acme/api", startingRef: "main" }],
+    repos: [
+      {
+        url: "https://github.com/acme/api",
+        startingRef: "main",
+      },
+    ],
     autoCreatePR: true,
   },
+  needsApproval: true,
 });
 ```
 
-Launches run under the host's signed-in account (`agent-sdk login`,
-`CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`) and spend its
-cloud-agent budget. Name the repositories the agent may target, and
-keep approval on when you can't.
-
-Mount it on an agent that runs on the local runtime; that is where
-launches park for approval. On the cloud runtime approvals don't
-resolve.
-
-## What the agent can do
-
-With the extension mounted, the agent can hand off coding work and stay
-in the conversation while it happens:
-
-- **Hand off a task.** Launch a cloud agent on one of your repositories,
-or on a pull request, with a self-contained brief. It gets back an
-agent id and a URL to share.
-- **Check on it.** See whether the agent is still running, what it
-produced, and which branches or pull requests it pushed.
-- **Read what was done.** Pull the agent's full conversation into the
-workspace, quote its final report, or trace the exact edits before
-summarizing for a person.
-- **Steer or stop.** Send a follow-up to an agent it launched; it queues
-behind the current run, or interrupts it on request. Cancel a run that
-went sideways.
-- **Keep track.** List the agents launched in this conversation, or
-everything it has launched before.
-
-A skill teaches the model when to delegate, how to write a brief a cloud
-agent can act on alone, and how to follow up. Everything the extension
-launches stays bound to whoever launched it: an agent started by another
-user, or outside the extension, is out of reach. That separation is only
-as fine as your host's auth; a shared bearer token or `--allow-anonymous`
-makes every caller one principal, so use
-[authored auth](../reference/channels.md#auth-policies) when callers need
-their own.
+Mounted as `cloud`, the extension contributes tools such as
+`cloud__launch`, `cloud__get`, `cloud__dump`, `cloud__reply`, and
+`cloud__cancel`, plus guidance for using them.
+
+## Hand off repository work
+
+Ask for an outcome that needs a checkout or a long isolated run. The
+agent writes a self-contained brief, requests approval when configured,
+then immediately reports the complete cloud-agent ID and URL. A branch
+or pull request appears later as the cloud agent works.
+
+> Hand this bug to a cloud agent in `acme/api`. Preserve the public API,
+> run the package tests, and open a pull request with the fix.
+
+The brief should include the goal, repository or PR, starting ref,
+constraints, files to leave alone, and what completion means. The cloud
+agent cannot see the surrounding conversation, so references such as
+"fix the issue above" are not enough.
+
+## Check and report the result
+
+Use `get` when you need current status, branch or PR links, and change
+counts. Status can be `creating`, `running`, `finished`, `error`,
+`expired`, or `unknown`.
+
+After work finishes, `dump` writes the conversation and tool transcript
+into the session workspace and returns its path plus `finalMessage`.
+If neither is available yet, wait for more output instead of inventing
+a report.
+
+Read `finalMessage`, then inspect the resulting branch or pull request
+before telling a person exactly what changed. The transcript records
+commands and tool activity, but it is not a canonical code diff.
+
+## Steer or stop the same agent
+
+Use `reply` to add constraints, ask for a correction, or continue work
+on the existing branch. A follow-up queues behind the current run by
+default; choose interruption only when the active step should stop
+immediately.
+
+> Keep the current branch, but replace the new dependency with the
+> standard library and rerun the same tests.
+
+`cancel` stops active work immediately while preserving the branch and
+conversation, so a later `reply` can continue from that state. Approval
+applies to `launch` and `reply`; `get`, `dump`, `list`, and `cancel` do
+not park.
 
 ## Configure it
 
+Two settings define the important boundary:
 
-| Option          | What it controls                                                                                                                                                                                                                               |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cloud`         | Launch defaults, in the same shape as the agent's own [cloud options](../reference/agent-config.md#cloud-options).                                                                                                                             |
-| `cloud.repos`   | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in `cloud.envVars` never reach a repository you didn't list. |
-| `model`         | The model launched agents run. Omit it to use the account default.                                                                                                                                                                             |
-| `needsApproval` | Park launches and follow-ups for a [human decision](../reference/tools.md#gate-a-tool-on-human-approval). Defaults to `true` when no `cloud.repos` are configured, `false` otherwise.                                                          |
-| `apiKey`        | A Cursor API key to launch with instead of the host's own.                                                                                                                                                                                     |
+- `cloud.repos` is both the launch default and the repository allowlist.
+  A model-selected repository or PR outside it is refused, including
+  when cloud environment variables carry secrets.
 
+- `needsApproval` controls launches and follow-ups. Approval cards
+  require the local runtime; parked approvals do not survive a host
+  restart.
 
+The extension spends cloud-agent budget and uses the serve host's
+Cursor credential: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`. Pass `apiKey` only
+when this extension should use a different account.
 
+Local runtime is the simplest setup and supports approvals. A
+cloud-runtime agent can reach these server tools through managed hosting
+or a protected `--public-url`, but it cannot resolve tool approvals.
 
-## Adjust it
+Model choice, environment, PR behavior, and other launch defaults use
+the standard [cloud options](../reference/agent-config.md#cloud-options).
 
-To take a capability away, such as sending follow-ups, mount as a
-directory and disable that tool; see
-[overlays](../reference/extensions.md#adjust-a-mounted-extension).
+## Caller ownership
 
-## What's next
+Every launched agent belongs to the authenticated principal that
+started it. Other principals cannot inspect, steer, or cancel that run.
+A shared bearer token or anonymous host collapses callers into one
+principal, so use per-caller auth when this separation matters.
+
+`dump` materializes reasoning and tool-call content into the session
+workspace. Treat that file like any other detailed agent transcript.
+
+## Practices
+
+- Launch one cloud agent per independent task; steer the same agent for
+  follow-up work on its branch.
+
+- Use `list` for launches from the current session. Request caller-wide
+  history only when the user asks for earlier work.
 
-Continue with these pages:
+- Report the complete agent ID and URL. Do not abbreviate the ID.
 
-- [Extensions](../reference/extensions.md): how mounts, namespaces, and
-overrides work
-- [Gate a tool on human approval](../reference/tools.md#gate-a-tool-on-human-approval):
-where parked launches get approved
+- Check status when someone needs progress or when the result should be
+  ready, not in a tight polling loop.
+
+## Adjust it
+
+To remove a capability such as `reply`, mount the extension as a
+directory and disable that tool. See
+[Adjust a mounted extension](../reference/extensions.md#adjust-a-mounted-extension).
+
+## What's next
 
+- [Extensions](../reference/extensions.md): namespaces, trust, and
+  overlays
+- [Self-improvement](./improve.md): use this extension to propose
+  changes to the agent's own source
+- [Tool approvals](../reference/tools.md#gate-a-tool-on-human-approval):
+  review launches and follow-ups
+- [Deployment](../deployment.md): expose server tools to cloud-runtime
+  turns

package/docs/guides/convert-automation.md

@@ -1,176 +1,185 @@
 ---
 title: "Convert a Cursor Automation"
-description: "Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it."
+description: "Turn a dashboard Automation into an Agent SDK project, then reconnect its actions and triggers."
 ---
 
 # Convert a Cursor Automation
 
-`convert-automation` exports a dashboard Automation into a local Agent
-SDK project. Use it when you need to edit, test, or deploy the
-Automation as code. Keep using the dashboard if you only need to change
-its prompt or trigger.
+Convert a dashboard Automation when you want to edit its behavior as
+code, test it locally, or deploy it as an Agent SDK project. If you only
+need to change the prompt or trigger, the dashboard remains the shorter
+path.
 
-The converter refuses Cursor-managed Automations because their behavior
-lives in managed configuration. The
-[CLI reference](../reference/cli.md#convert-automation) lists flags and
-exit codes.
+`convert-automation` carries over what it can prove from the exported
+configuration and prints a checklist for everything that still needs
+your judgment.
 
-## Run the conversion
+## Convert and run locally
 
-Sign in before converting. Unlike `init`, this command does not start a
-login flow.
+The command creates a project named after the Automation, installs its
+dependencies, and prints the generated files along with warnings and
+setup steps. Once `dev` starts, you can exercise the converted agent in
+the playground before reconnecting any live trigger.
 
 ```bash
 agent-sdk login
-# or: export CURSOR_API_KEY=key_...
-agent-sdk whoami
+agent-sdk convert-automation \
+  https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555
+
+cd nightly-triage
+agent-sdk validate
+agent-sdk dev
 ```
 
-Pass the Automation's dashboard URL or UUID. The URL must end with
-`/automations/<uuid>` or `/custom-agents/<uuid>`. Do not add path
-segments after the UUID.
+The project includes the Automation's prompt and model plus any
+schedules, channels, and account connections the converter could
+represent directly. The
+[CLI reference](../reference/cli.md#convert-automation) covers custom
+output directories, JSON output, and command failures.
+
+## Reconnect account-backed actions
+
+For an HTTP or SSE MCP server, the converter writes a name-based
+connection instead of copying its URL or credentials. After you connect
+the same server under MCP in Cursor and sign in the local host, the
+converted agent can use that server's tools through your account.
+
+```ts
+// agent/mcp-connections/linear.ts
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  cursorAccount: true,
+  servers: ["Linear"],
+});
+```
+
+The summary adds a `Verify:` step when an original dashboard action
+does not map to one generated tool. Treat that step as a behavior test:
+run the converted agent with a representative input and confirm the
+same external write happens before you consider the action restored.
+
+## Bring a Slack trigger online
+
+After you create the dedicated Slack app, mentions wake the converted
+agent and its answers land in the same thread. A channel watch also
+wakes on allowed posts, but only after you subscribe the app with
+`--channel-posts`.
 
 ```bash
-agent-sdk convert-automation https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555
+agent-sdk slack create --dir . --channel-posts
 ```
 
-The summary prints the output directory. Change into it before running
-any setup command. For an Automation named "Nightly triage":
+The converter preserves the watch allowlist. If a warning says Cursor
+previously filtered messages by text, add that decision to the
+generated channel before inviting the bot:
+
+```ts
+export default slackChannel({
+  envPrefix: "NIGHTLY_TRIAGE",
+  engagement: {
+    channelPosts: { allow: ["C123"] },
+  },
+  onChannelPost: async (_ctx, message) => {
+    if (!message.markdown.includes("deploy")) {
+      return null;
+    }
+    // `{}` starts a model turn as the sender.
+    return {};
+  },
+});
+```
+
+For mention-only Automations, run `agent-sdk slack create --dir .`
+without `--channel-posts`. The [Slack guide](./slack.md) covers the
+reply experience and app setup.
+
+## Bring a GitHub trigger online
+
+The generated GitHub channel keeps mechanical filters such as PR
+actions, branches, issue actions, repositories, and simple user
+allowlists. Conditions that depended on backend-only context stay
+fail-closed, so the corresponding hook returns `null` until you replace
+it.
+
+For example, a converted CI trigger can wake only when the suite fails:
+
+```ts
+import {
+  defaultGitHubAuth,
+  githubChannel,
+} from "@cursor/july/channels/github";
+
+export default githubChannel({
+  cursorAccount: { repos: ["acme/api"] },
+  webhookEvents: ["check_suite"],
+  onCheckSuite: (ctx, suite) => {
+    if (suite.conclusion !== "failure") {
+      return null;
+    }
+    // `auth` starts a model turn running as the sender.
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+});
+```
+
+Replay a PR with a failing check before connecting live delivery:
 
 ```bash
-cd nightly-triage
+agent-sdk github replay acme/api#42 \
+  --dir . \
+  --events '*' \
+  --conclusion failure
 ```
 
-The command fetches the Automation before writing files. A 404 means it
-was not found, you do not have access, or convert is not enabled for
-your team. A 422 means it is Cursor-managed. The command writes nothing
-after either error.
+Cursor-account delivery carries PR and comment events. Push, issue, and
+CI triggers need real GitHub webhook delivery through a GitHub App or
+`github forward`. The [GitHub guide](./github.md) covers both paths.
 
-The command runs `npm install` after writing the project. If the install
-fails, the files remain. Run `npm install` in the output directory
-before `dev`.
+## Treat warnings as the migration checklist
 
-## What the project contains
+A successful conversion means the project was generated, not that
+every source behavior survived. Read the warnings and setup steps before
+turning on a live trigger:
 
-A cron Automation with a Linear MCP server might produce:
+- A setup step names something you must connect or configure.
 
-```
-nightly-triage/
-  package.json
-  tsconfig.json
-  agent/
-    agent.ts
-    instructions.md
-    schedules/nightly-triage.ts
-    mcp-connections/linear.ts
-  evals/
-```
+- A `Verify:` step names an external action whose behavior needs a test.
+
+- A fail-closed hook intentionally starts no turns until you restore its
+  filter.
+
+- A `.todo.md` file is ignored by the framework and marks a connection
+  you must replace.
+
+Keep the source Automation enabled while you work through this list, so
+you still have its behavior as a reference.
+
+## Know the conversion boundary
+
+The converter can reproduce configuration that has a direct home in an
+Agent SDK project: instructions, the selected model, cron schedules,
+mechanical GitHub filters, Slack mentions and watch allowlists, and
+named Cursor-account MCP connections.
+
+It cannot infer policy that lived behind the dashboard. Bespoke trigger
+conditions, provider webhook registration and auth, credentials,
+unsupported trigger semantics, and built-in action behavior remain
+warnings, comments, or TODO files for you to resolve. Credentials are
+never exported.
+
+Cursor-managed Automations do not convert because their behavior lives
+entirely in managed configuration.
+
+## Related
 
-The command adds missing `init` scaffold files but omits the demo
-`echo` tool. It writes the memory hook only when memory was enabled.
-File generation leaves existing paths unchanged and marks them as
-`exist`. This does not cover `npm install`, which may update lockfiles
-or run lifecycle scripts from an existing `package.json`.
-
-| Automation input | Project output |
-| --- | --- |
-| First prompt | Copies text to `agent/instructions.md`. Action markup such as `@[label](action:...)` becomes the label text. |
-| Prompt model | Pins the model on `defineAgent` in `agent/agent.ts`. `git_config` and `agent_options` remain comments. |
-| Cron trigger | Creates `agent/schedules/<slug>.ts` with `defineSchedule` in UTC. |
-| GitHub trigger | Creates `agent/channels/github.ts`. It converts pull-request action, push branch, issue action, and user allowlist filters. |
-| Slack trigger | Creates `agent/channels/slack.ts` as Socket Mode with `envPrefix` from the automation name (same names `slack create` writes). Watches add `engagement.channelPosts`. Run `agent-sdk slack create` for the bot. |
-| Linear, PagerDuty, Sentry, Teams, or generic webhook | Creates a boilerplate `agent/channels/<slug>.ts`. |
-| HTTP or SSE MCP server | Creates a name-based Cursor-account connection under `agent/mcp-connections/`. The project contains no server URL or credentials. |
-| Stdio MCP server | Writes `agent/mcp-connections/<slug>.todo.md`. |
-| Slack post or read action | Adds `agent/mcp-connections/slack.ts`. The summary includes a `Verify:` step for the original action. |
-| Other built-in dashboard action | Adds a `Verify:` setup step instead of an Agent SDK tool. |
-
-## Finish unsupported behavior
-
-Warnings and setup steps identify behavior the converter could not
-reproduce.
-
-### Prompt snippets
-
-The export omits the source text for unresolved `%%INLINECODE<n>%%`
-placeholders. Restore those snippets in `instructions.md`.
-
-### GitHub filters
-
-Comment text, CI conclusion, label name, and review-state filters stay
-fail-closed. The generated hooks return `null` until you add them.
-The generated Cursor-account event relay includes only pull-request and
-comment data. Push, issue, and CI triggers need a GitHub App webhook or
-`github forward`. Add repositories for org-wide watches. The converter
-drops non-GitHub remotes.
-
-### Slack triggers
-
-Reaction and channel-created triggers have no Agent SDK equivalent. The
-converter keeps their configuration in comments but adds no handler.
-Re-add any `messageContains` filter or completion reaction you need.
-These triggers and channel watches require a dedicated Socket Mode app.
-Run `agent-sdk slack create --channel-posts`, then finish the dashboard
-wizard.
-
-### Provider webhooks
-
-Linear, PagerDuty, Sentry, Teams, and generic webhook channels mount
-`POST /` under their channel route. Every accepted body starts a run.
-In default multi-agent mode, the route is
-`/<agent-slug>/v1/channels/<channel-id>`. Single mode uses
-`/v1/channels/<channel-id>`.
-
-Restore the filters and auth before registering the provider. A hosted
-alias requires `X-Agent-Alias-Token`. If the provider cannot send that
-header, use `publicEndpoint()` with signature verification in the
-handler, put an alias-token relay in front, or self-host.
-
-### Stdio MCP servers
-
-The converter does not export the command, arguments, or environment.
-Run the server, then replace the `.todo.md` stub with a reachable
-connection.
-
-### Disabled default tools
-
-The converter cannot preserve this restriction. Do not rely on
-`instructions.md` as enforcement. Use the
-[`tools` allowlist](../reference/agent-config.md#allowlist-built-in-harness-tools),
-remove unwanted authored or MCP tools, and limit channel permissions.
-
-## Review and run the project
-
-1. Read every warning and setup step.
-2. Open the generated channel files. Fail-closed GitHub hooks dispatch
-   nothing until you add their filters. Add auth to boilerplate webhook
-   routes.
-3. Confirm the account MCP servers are connected under MCP in the Cursor
-   dashboard. The serving host must be signed in with `agent-sdk login`
-   or `CURSOR_API_KEY`.
-4. Run the printed next steps:
-
-   ```bash
-   agent-sdk validate
-   agent-sdk dev
-   ```
-
-5. Before you [deploy](../deployment.md), disable the source Automation
-   so both versions do not respond to the same events. The final setup
-   step includes its dashboard URL.
-6. A hosted deployment uses a separate service account. After the first
-   deploy, run `agent-sdk mcp oauth <connection>` for each generated
-   Cursor-account connection.
-
-## What's next
-
-- [CLI](../reference/cli.md#convert-automation): flags, `--json`, exit
-  codes
+- [CLI reference](../reference/cli.md#convert-automation): arguments,
+  JSON output, and failures
 - [MCP connections](../reference/connections.md): Cursor-account
-  connectors
-- [GitHub](./github.md): hook filters and replay; use
-  [`github forward`](../reference/cli.md#github) for live delivery
-- [Slack](./slack.md): Cursor connection vs Socket Mode
-- [Webhooks](./webhooks.md): auth on a custom channel route
-- [Deployment](../deployment.md): hosted engines after you have reviewed
-  the project
+  connectors and hosted authorization
+- [GitHub](./github.md): event delivery, hook filters, and replay
+- [Slack](./slack.md): mentions, channel watches, and reply modes
+- [Webhooks](./webhooks.md): auth and filtering for generated provider
+  routes
+- [Deployment](../deployment.md): deploy the reviewed project, then
+  disable the source Automation before enabling the same live triggers