@cursor/july 0.1.109 → 0.1.112

package/docs/guides/improve.md

@@ -1,25 +1,24 @@
 ---
 title: "Self-improvement"
-description: "Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens."
+description: "Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."
 ---
 
 # Self-improvement
 
-The `improve` extension lets an agent change how it behaves by changing
-its own source. Someone asks it to answer more briefly, to stop reaching
-for a tool, or to learn a procedure. The agent writes a brief, a one-off
-Cursor cloud agent makes the change on a branch and opens a pull
-request, and the agent reports that pull request. Nothing changes until
-a person reviews it and deploys.
+The `improve` extension teaches an agent how to turn "change how you
+work" into a source change. The agent prepares a brief, a Cursor cloud
+agent edits a checkout and opens a pull request, and the running agent
+reports the verified PR for human review.
 
-The tree the agent runs from is never edited; nothing changed there
-survives a deploy. The pull request is the only path.
+Durable behavior does not change until that source is merged and
+deployed. A cloud-runtime turn may edit its ephemeral checkout, but it
+does not rewrite the source of a running deployment.
 
 ## Mount it
 
-The extension ships with `@cursor/july`. It relies on a
-[`cursor-cloud-agents`](./cloud-agents.md) mount beside it, with the
-agent's own repository among its `cloud.repos`.
+On the local runtime, mount Cloud agents with the agent's own repository
+allowlisted, keep launch approval explicit, then mount `improve` with
+the source directory.
 
 ```ts
 // agent/extensions/cloud.ts
@@ -27,8 +26,15 @@ import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
 
 export default cursorCloudAgents({
   cloud: {
-    repos: [{ url: "https://github.com/acme/agents", startingRef: "main" }],
+    repos: [
+      {
+        url: "https://github.com/acme/agents",
+        startingRef: "main",
+      },
+    ],
+    autoCreatePR: true,
   },
+  needsApproval: true,
 });
 ```
 
@@ -39,58 +45,105 @@ import improve from "@cursor/july/extensions/improve";
 export default improve({
   repo: "https://github.com/acme/agents",
   path: "agents/concierge",
+  ref: "main",
 });
 ```
 
-`repo` is the repository that holds the agent's source and `path` is
-the agent's directory in it, the same values `agent-sdk deploy --repo`
-and `--path` take. Mount it as `improve`: the skill then reads
-`improve__yourself`, which is what a person asks for.
-
-An agent on the
-[cloud runtime](../reference/agent-config.md#choose-a-runtime) already
-runs each turn on a VM with the repository checked out. It mounts
-`improve` alone, and the skill has it branch in that checkout instead of
-launching a second agent.
-
-## What the agent does
-
-With the extension mounted, "change how you work" becomes a procedure:
-
-- **Locate the change.** The skill maps the ask onto the Agent SDK tree:
-  instructions for the always-on prompt, a skill for a procedure, a tool
-  for behavior that must be right every time, `agent.ts` for the model.
-- **Brief a cloud agent.** The agent writes a self-contained brief: who
-  is asking and why, the repository, ref, and path, the files it expects
-  to change, your notes about the tree, and the rules. Follow the
-  repository's conventions, keep the diff to the change, run the
-  repository's checks, open a pull request against the deployed ref,
-  never merge.
-- **Follow up and report.** It gives the person the cloud agent's URL,
-  checks on the run, reads the pull request before repeating its claims,
-  and reports the pull request, not the delegation. It says the change
-  takes effect at the next deploy, never that it has changed already.
-
-Ask it directly. "Improve yourself: stop opening with a summary" is
-enough.
+Mounted as `improve`, the extension contributes the
+`improve__yourself` skill. It does not contribute a tool that can bypass
+the normal repository workflow.
+
+## Ask for one behavioral change
+
+State the change, how to tell it worked, and what behavior must stay
+fixed. The agent maps the request to instructions, a skill, a tool,
+channel configuration, or the model setting before preparing the coding
+brief.
+
+> Improve yourself: stop opening incident replies with a summary.
+> Start with the decision, keep the existing evidence bullets, and
+> preserve every current eval.
+
+The success criterion and freeze line keep the cloud agent from turning
+a narrow behavior request into an unrelated refactor.
+
+## Follow the source change
+
+On local runtime, the agent requests approval and launches one cloud
+agent on the configured repository and ref. It reports the complete
+cloud-agent ID and URL immediately, then checks the same run instead of
+launching another agent for follow-up work.
+
+When the cloud agent opens a pull request, the running agent reads the
+result and the PR before reporting what changed and which checks passed.
+The pull request, not the delegation transcript, is the durable
+deliverable.
+
+Use the [Cloud agents guide](./cloud-agents.md) for launch, status,
+transcript, steering, and cancellation behavior.
+
+## Review, merge, then deploy
+
+The workflow stops at a pull request. A human reviews the diff and
+decides whether to merge it; a separate deployment action decides when
+the new behavior becomes live.
+
+This separation gives each boundary a real control:
+
+- Repository permissions limit who can push the branch.
+- Branch protection and review policy govern the merge.
+- Deployment authorization governs the running agent.
+
+After deployment, repeat the original request or regression eval to
+confirm the behavior changed without crossing the freeze line.
+
+## Use it from a cloud-runtime agent
+
+When the agent's own turn already runs on a cloud VM with the source
+repository checked out, mount `improve` without the Cloud agents
+extension. The skill branches and edits that ephemeral checkout, then
+opens the same reviewable pull request.
+
+Cloud-runtime tool approvals are unavailable. Repository permissions,
+branch protection, human review, and separate deployment remain the
+hard controls.
 
 ## Configure it
 
-| Option | What it controls |
-| --- | --- |
-| `repo` | The repository holding the agent's source. One of the cloud mount's `cloud.repos`. |
-| `path` | The agent's directory in the repository, as `agent-sdk deploy --path` names it. |
-| `ref` | The ref the deployment tracks. Branches start there and pull requests target it. Defaults to `main`. |
-| `notes` | What a coding agent must know about this tree beyond the standard layout: a house skill format, a manifest that forces a reinstall, a pull request convention. Copied into every brief. |
-| `deploy` | Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." |
+- `repo` is the source repository URL.
+- `path` is the agent's repository-relative directory.
+- `ref` is the deployed branch or ref that new branches and pull
+  requests target; it defaults to `main`.
+- `notes` adds tree-specific guidance to every coding brief, such as a
+  required test command or PR convention.
+- `deploy` tells the skill who deploys a merged change and when it
+  becomes live.
 
-## What's next
+`notes` and `deploy` insert prose into the contributed skill. They do
+not run checks, merge a branch, or trigger a deployment.
 
-Continue with these pages:
+Validation checks the URL and path shape. It does not prove the source
+exists, matches the current deployment, or appears in the Cloud agents
+repository allowlist, so keep those values aligned yourself.
+
+## What the extension enforces
+
+`improve__yourself` is model guidance for locating the change, writing a
+brief, following repository rules, opening a PR, and reporting it. Rules
+such as "never merge" are instructions, not framework-enforced
+permissions.
+
+Use repository and deployment controls for hard enforcement. The
+extension provides a repeatable path through those controls; it does not
+replace them.
+
+## What's next
 
-- [Cursor cloud agents](./cloud-agents.md): the mount that does the
-  coding, and how to gate its launches
-- [Extensions](../reference/extensions.md): how mounts, namespaces, and
-  overrides work
-- [Deployment](../deployment.md): how a merged change reaches the
-  running agent
+- [Cloud agents](./cloud-agents.md): delegation and steering on local
+  runtime
+- [Build with a coding agent](../building-with-agents.md): have an
+  external coding agent edit the project directly
+- [Extensions](../reference/extensions.md): namespaces and overlays
+- [Deployment](../deployment.md): make a merged source change live
+- [Evals](../evals.md): protect the requested behavior before and after
+  the change

package/docs/guides/mcp-oauth.md

@@ -1,174 +1,164 @@
 ---
 title: "Host MCP OAuth"
-description: "Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."
+description: "Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."
 ---
 
-# Host MCP OAuth
+# Connect a private MCP server with OAuth
 
-Use host MCP OAuth when your agent talks to a remote MCP server that
-speaks OAuth, and you want credentials on the serve host (or the hosted
-engine) instead of a Cursor account connector. Local login writes tokens
-next to your Cursor credentials. `--store` copies those tokens onto the
-deployment as secrets so prod can reconnect after a redeploy. Hosted
-Connect lets the current process retry.
+Host MCP OAuth lets an Agent SDK process authorize a remote MCP server
+without putting tokens in the agent's source or workspace. Use it when
+the server speaks OAuth and its credentials should belong to the serve
+host instead of a person's Cursor account.
 
-The companion skill is
-[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
+## Use a private MCP tool locally
 
-## What can host MCP OAuth do?
+Declare the remote server, authorize it once in the browser, and start
+the agent. The next local turn can call the server's named tools with
+the credentials stored on that host.
 
-- Authorize `defineConnection({ url, oauth: true })` with a browser PKCE
-  flow (`agent-sdk mcp oauth <connection>`)
-- Keep tokens in `mcp-auth.json` under the CLI config directory, bound
-  to that connection's resource URL
-- Upsert deployment secrets with `--store` so the next deploy seeds the
-  same tokens from env. Hosted Connect lets the current process retry.
-- Use `advertiseTools: true` when local turns should call the server by
-  name. Host tools can still call it through `ctx.host.mcp`.
+```ts
+// agent/mcp-connections/inventory.ts
+import { defineConnection } from "@cursor/july/connections";
 
-Prefer a Cursor account MCP connection when the connector already lives
-in the signed-in account dashboard:
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+  advertiseTools: true,
+});
+```
 
-```ts
-defineConnection({ cursorAccount: true }) // every connected connector
-// or servers: "*" / servers: ["Linear"]
+```bash
+agent-sdk mcp oauth inventory
+agent-sdk run --dir . \
+  --message "Which east-coast warehouse has SKU-142 in stock?"
 ```
 
-Use host OAuth when the server is yours (or private to your network)
-and the host must hold tokens.
+The filename is the connection name used by the CLI and
+`ctx.host.mcp`. Changing the server URL invalidates its saved
+authorization, so run `mcp oauth` again after moving the endpoint.
 
-## How do I declare a host-OAuth connection?
+## Connect on first use
 
-Add one file under `agent/mcp-connections/` (model + host) or
-`agent/host-connections/` (host + `mcp oauth` only). The filename is the
-connection name you pass to the CLI and to `host.mcp`.
+You can also let the first unauthenticated call ask for authorization.
+The turn parks and the playground shows **Connect**. Finish the browser
+flow, return to the playground, and confirm **Connected**; the same call
+retries and the turn continues without restarting the agent.
+
+```bash
+agent-sdk serve --dir . --dev
+```
+
+Connect authorizes the process that is running now. It does not seed
+credentials for a future hosted replacement; use `--store` for that
+separate outcome.
+
+## Keep privileged tools behind a wrapper
+
+Put a connection under `agent/host-connections/` when the model should
+not receive the MCP server's tools directly. A server tool can expose
+one constrained operation while `ctx.host.mcp` keeps the broader server
+on the host.
 
 ```ts
-// agent/mcp-connections/inventory.ts
+// agent/host-connections/inventory.ts
 import { defineConnection } from "@cursor/july/connections";
 
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  description: "Inventory MCP.",
+  tools: ["lookup_stock"],
+});
+```
+
+```ts
+// agent/tools/get_stock.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Read stock for one approved region.",
+  inputSchema: z.object({
+    sku: z.string(),
+    region: z.enum(["us-east", "us-west"]),
+  }),
+  async execute(input, ctx) {
+    const result = await ctx.host.mcp.callTool(
+      "inventory",
+      "lookup_stock",
+      input
+    );
+    return {
+      ok: result.isError !== true,
+      stock: result.structuredContent ?? null,
+    };
+  },
 });
 ```
 
-Rules of the road:
+The model sees `get_stock`, not the unrestricted inventory server.
+Use this shape when code should own an allowlist, approval, or other
+side-effect gate.
 
-- `oauth: true` is required for `agent-sdk mcp oauth`
-- A file under `mcp-connections/` is visible to the model and to `ctx.host.mcp`. A file under `host-connections/` stays on the host.
-- Declare expected secret names on the agent when you plan to `--store`:
+## Keep OAuth across hosted replacements
+
+Declare the server's egress domain and the OAuth secret names, authorize
+from a signed-in machine, then store the credentials and redeploy. The
+next hosted process can reconnect without opening a browser.
 
 ```ts
 // agent/agent.ts
 export default defineAgent({
-  // …
   hosting: {
+    egressDomains: ["mcp.example.com"],
     secretNames: [
       "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
       "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
       "MCP_OAUTH_INVENTORY_CLIENT_ID",
     ],
-    // Hosted engines need an explicit allowlist for non-bootstrap hosts.
-    egressDomains: ["mcp.example.com"],
   },
 });
 ```
 
-Secret names follow `MCP_OAUTH_<CONNECTION>_*` where `<CONNECTION>` is
-the connection filename uppercased with non-alphanumerics turned into
-underscores (`inventory` → `MCP_OAUTH_INVENTORY_…`).
-
-## How do I authorize locally?
-
-From the agent project (Node 22.13+, not Bun):
-
-```bash
-agent-sdk mcp oauth inventory
-```
-
-What happens:
-
-1. The Agent SDK loads the connection file and checks `oauth: true`
-2. It opens the authorization URL in your browser
-3. The callback lands on `http://localhost:8787/callback`
-4. Tokens land in `mcp-auth.json` under the CLI config directory
-  (override with `AGENT_SERVE_CONFIG_DIR`)
-
-If you're already authorized, the command prints that and exits. Re-run
-it after rotating tokens on the MCP server, or after you change the
-connection URL (tokens are bound to the resource URL).
-
-## How do I store credentials on a hosted deployment?
-
-Authorize once. Then get the tokens onto the deployment.
-
-On a hosted engine, finishing Connect lets the current process retry.
-Self-hosted serve writes tokens locally only.
-
-`--store` from a signed-in laptop is the reliable way to put
-`MCP_OAUTH_*` on the next deploy. If `agent-sdk secrets list` is
-empty, run `--store` and redeploy.
-
-From a laptop, push secrets with the CLI:
-
 ```bash
 agent-sdk mcp oauth inventory --store
-# optional:
-#   --slug my-agent
-#   --team <cursor-team-id>
+agent-sdk secrets list my-agent
+agent-sdk deploy
 ```
 
-`--store` upserts:
-
-| Secret | Source |
-| --- | --- |
-| `MCP_OAUTH_<NAME>_ACCESS_TOKEN` | access token (required) |
-| `MCP_OAUTH_<NAME>_REFRESH_TOKEN` | refresh token when the server returns one |
-| `MCP_OAUTH_<NAME>_CLIENT_ID` | dynamic client id when registration returned one |
-
-You must be signed in (`agent-sdk login`) with permission to set secrets
-on that slug. Secrets apply on the **next** deploy. Run
-`agent-sdk deploy` after `--store`. A fresh pod sees `MCP_OAUTH_*`
-only after that deploy.
+`--store` writes deployment secrets; it does not restart the current
+engine. Follow the CLI or dashboard prompt to redeploy, then exercise
+the hosted agent.
 
-On the engine, when `mcp-auth.json` is empty, serve seeds the OAuth
-provider from those env vars so host MCP calls work without a browser
-on the pod.
+These credentials belong to the deployment, not to the person who
+clicked Connect. Anyone able to use that agent can reach the MCP
+capabilities you expose, so keep privileged servers host-only or narrow
+their tool list.
 
-These secrets are deployment-wide. Anyone who can list or set secrets
-on that slug, and the hosted engine's runtime env, can use them. That
-is the same blast radius as `--store`. They are not scoped to the
-caller who clicked Connect. `cursorAccount: true` tokens stay on the
-Cursor backend for the deployment service account and do not use
-`MCP_OAUTH_*`.
+## Choose where credentials live
 
-## How do host tools call the server?
+Use the credential shape that matches who should own access:
 
-```ts
-const result = await ctx.host.mcp.callTool(
-  "inventory",
-  "list_warehouses",
-  { region: "us-east" }
-);
-```
+- Choose `cursorAccount: true` for connectors already authorized under
+  MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.
 
-The model can call the same server. Use a host tool when the write needs
-an allowlist or other deterministic gate.
+- Choose `url` with `oauth: true` when the serve host or hosted
+  deployment should hold OAuth credentials.
 
-## What if authorization fails?
+- Choose `url` with static `headers` when the server uses an API key or
+  bearer token instead of OAuth.
 
-| What you see | What to do |
-| --- | --- |
-| `must be defineConnection({ url, oauth: true })` | Add `oauth: true` on that connection, or pick the right connection name |
-| Callback never completes | Keep port `8787` free; finish the browser login on this machine |
-| Hosted calls unauthorized after Connect or `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
-| Tokens ignored after URL change | Expected: resource URL binding drops stale entries. Re-run `mcp oauth` |
+Host OAuth and per-session `auth` are different identity models and
+cannot be combined on one connection. Use per-session auth when each
+caller needs a different downstream identity.
 
-## What's next
+## Related
 
-- [MCP connections](../reference/connections.md): transports, account MCP
-- [CLI](../reference/cli.md#mcp-oauth): full flag list for `mcp oauth`
-- [Deployment](../deployment.md): secrets, egress, and hosted engines
-- [Fix common agent problems](../troubleshooting.md): more symptom → fix tables
+- [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md): the
+  companion setup procedure for coding agents
+- [MCP connections](../reference/connections.md): transports, account
+  connectors, per-session auth, and tool filtering
+- [CLI reference](../reference/cli.md#mcp-oauth): OAuth command flags
+  and browser callback behavior
+- [Deployment](../deployment.md): hosted secrets and egress
+- [Troubleshooting](../troubleshooting.md): authorization symptoms and
+  remedies