@cursor/july 0.1.111 → 0.1.113

package/dist/docs/guides/cloud-agents.md

@@ -1,21 +1,21 @@
 # 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.
-
-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.
+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 choosing
+[`runtime: "cloud"`](/docs/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
@@ -23,74 +23,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](/docs/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:
+
+- `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.
+
+Model choice, environment, PR behavior, and other launch defaults use
+the standard [cloud options](/docs/reference/agent-config.md#cloud-options).
 
-| Option          | What it controls                                                                                                                                                                                                                               |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cloud`         | Launch defaults, in the same shape as the agent's own [cloud options](/docs/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](/docs/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.                                                                                                                                                                                     |
+## Caller ownership
 
+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.
+
+- Report the complete agent ID and URL. Do not abbreviate the ID.
+
+- Check status when someone needs progress or when the result should be
+  ready, not in a tight polling loop.
 
 ## Adjust it
 
-To take a capability away, such as sending follow-ups, mount as a
-directory and disable that tool; see
-[overlays](/docs/reference/extensions.md#adjust-a-mounted-extension).
+To remove a capability such as `reply`, mount the extension as a
+directory and disable that tool. See
+[Adjust a mounted extension](/docs/reference/extensions.md#adjust-a-mounted-extension).
 
 ## What's next
 
-Continue with these pages:
-
-- [Extensions](/docs/reference/extensions.md): how mounts, namespaces, and
-overrides work
-- [Gate a tool on human approval](/docs/reference/tools.md#gate-a-tool-on-human-approval):
-where parked launches get approved
+- [Extensions](/docs/reference/extensions.md): namespaces, trust, and
+  overlays
+- [Self-improvement](/docs/guides/improve.md): use this extension to propose
+  changes to the agent's own source
+- [Tool approvals](/docs/reference/tools.md#gate-a-tool-on-human-approval):
+  review launches and follow-ups
+- [Deployment](/docs/deployment.md): expose server tools to cloud-runtime
+  turns