@cursor/july 0.1.100 → 0.1.102

package/dist/docs/llms-full.txt

@@ -508,9 +508,9 @@ name. For example, `agent/tools/get_weather.ts` creates a tool named
 | `agent/ab.ts` or `agent/ab/*.ts` | Sticky variants and live performance metrics |
 | `evals/**/*.eval.ts` | Repeatable checks at the project root |
 
-Other folders add subagents, hooks, schedules, and workspace files. You
-don't register them elsewhere. Run `agent-sdk validate` to catch
-invalid files before serving the project.
+Other folders add subagents, extensions, hooks, schedules, and workspace
+files. You don't register them elsewhere. Run `agent-sdk validate` to
+catch invalid files before serving the project.
 
 See [Project layout](/docs/reference/project-layout.md) for the folder
 structure.
@@ -3436,6 +3436,104 @@ Continue with these pages:
 
 ---
 
+Source: /docs/guides/cloud-agents.md
+
+# Cursor 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 the [cloud runtime](/docs/guides/cloud-runtime.md). 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.
+
+## Mount it
+
+The extension ships with `@cursor/july`. Mount it with one file.
+
+```ts
+// agent/extensions/cloud.ts
+import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
+
+export default cursorCloudAgents({
+  cloud: {
+    repos: [{ url: "https://github.com/acme/api", startingRef: "main" }],
+    autoCreatePR: true,
+  },
+});
+```
+
+Launches run under the host's signed-in account (`agent-sdk login` or
+`CURSOR_API_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](/docs/guides/cloud-runtime.md#what-changes-on-cloud) 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.
+
+## Configure it
+
+| 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/guides/human-in-the-loop.md). 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. |
+
+## 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).
+
+## What's next
+
+Continue with these pages:
+
+- [Extensions](/docs/reference/extensions.md): how mounts, namespaces, and
+  overrides work
+- [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md): where parked
+  launches get approved
+- [Cloud runtime](/docs/guides/cloud-runtime.md): run the agent's own turns on
+  cloud agents instead
+
+---
+
 Source: /docs/guides/cloud-runtime.md
 
 # Cloud runtime
@@ -3553,6 +3651,8 @@ Continue with these pages:
   `cloud` fields
 - [GitHub guide](/docs/guides/github.md): the webhook patterns that pair with
   cloud triage
+- [Cursor cloud agents](/docs/guides/cloud-agents.md): keep the agent local and
+  let it launch cloud agents instead
 
 ---
 
@@ -5404,6 +5504,7 @@ npx @cursor/july docs
 | Starting from a packaged template | [Demo](/docs/templates/demo.md), [Code wiki](/docs/templates/code-wiki.md), [Living AGENTS.md](/docs/templates/agents-md.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
 | Wiring an agent to GitHub webhooks | [GitHub guide](/docs/guides/github.md) |
 | Driving PRs from a cloud VM | [PR autofixer template](/docs/templates/pr-autofixer.md) |
+| Handing coding work to Cursor cloud agents | [Cursor cloud agents](/docs/guides/cloud-agents.md) |
 | Driving an agent from Linear (or another tracker) | [Webhooks guide: Linear example](/docs/guides/webhooks.md#example-linear-as-the-control-plane) |
 | Making an existing agent measurably better | [Evals](/docs/evals.md), then [Hillclimbing](/docs/hillclimbing.md) |
 | Comparing variants on live traffic | [Live A/B metrics](/docs/ab.md) |
@@ -5470,6 +5571,8 @@ npx @cursor/july docs
   server; agents can delegate to each other.
 - [Cloud runtime](/docs/guides/cloud-runtime.md): run turns on Cursor cloud
   agents instead of the local harness.
+- [Cursor cloud agents](/docs/guides/cloud-agents.md): let the agent launch
+  and steer cloud agents through the `cursor-cloud-agents` extension.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): push session, turn, and
   tool traces to an OTLP collector you run.
 
@@ -5489,7 +5592,8 @@ npx @cursor/july docs
   [`prompt`](/docs/reference/prompt.md) ·
   [Skills](/docs/reference/skills.md) ·
   [MCP connections](/docs/reference/connections.md) ·
-  [Subagents](/docs/reference/subagents.md)
+  [Subagents](/docs/reference/subagents.md) ·
+  [Extensions](/docs/reference/extensions.md)
 - [Channels](/docs/reference/channels.md) ·
   [Schedules and reminders](/docs/reference/schedules.md) ·
   [Hooks](/docs/reference/hooks.md) ·
@@ -7606,6 +7710,37 @@ be 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.
 
+## Restrict which tools a connection serves
+
+Use `tools` the same way you allowlist harness tools on the agent. When
+set, the connection serves only those names. Use `disallowedTools` to
+drop names instead. The two combine as deny-wins, same as the Cursor
+SDK. The model and `host.mcp` only see what remains. On a model-visible
+connection, set `advertiseTools: true` so the raw server is not attached.
+
+```ts
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  advertiseTools: true,
+  tools: ["search_skus", "get_stock"],
+});
+
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  advertiseTools: true,
+  disallowedTools: ["place_order", "delete_sku"],
+});
+```
+
+Names are the server's `tools/list` names. Unknown names are omitted. A
+filter that matches nothing on the server fails the turn. Combine with
+`effects: "read"` to keep only the listed tools the server classifies as
+reads.
+
+A list of names is an allowlist. An object of handlers authors TypeScript
+tools. On `host-connections/`, a name list restricts `host.mcp` without
+advertising.
+
 ## Local stdio MCP server
 
 Run a local MCP server as a child process with `command`.
@@ -7758,6 +7893,211 @@ Continue with these pages:
 
 ---
 
+Source: /docs/reference/extensions.md
+
+# Extensions
+
+An extension packages tools and skills an agent installs as one unit. You
+mount it with a single file under `agent/extensions/`, and its
+contributions join the agent under a namespace. The package updates
+like any other dependency; nothing is copied into your project. A Cursor
+plugin mounts the same way; see [Mount a Cursor plugin](#mount-a-cursor-plugin).
+
+## Mount an extension
+
+Install the package, then add one file. The filename is the namespace.
+
+```ts
+// agent/extensions/ci.ts
+import ci from "@acme/ci-triage";
+
+export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
+```
+
+Every contribution is exposed as `<namespace>__<name>`. A `failed_jobs`
+tool from this mount runs in the agent as `ci__failed_jobs`, and a
+`triage` skill loads as `ci__triage`. `agent-sdk info` lists each mount
+with what it contributed, and `GET /v1/info` returns the same under
+`extensions`.
+
+Pass the configuration the extension asks for. The extension validates it
+when the agent loads, so a missing or mistyped field fails
+`agent-sdk validate` instead of a tool call later.
+
+Namespaces follow the tool-name rule, and `__` is reserved: an authored
+`agent/tools/ci__failed_jobs.ts` fails discovery, so nothing outside a
+mount can pose as one of its tools.
+
+## Adjust a mounted extension
+
+To replace or remove a contribution, mount the extension as a directory
+and overlay the slot you want to change.
+
+```text
+agent/extensions/ci/
+├── extension.ts        # the mount: export default ci({ ... })
+├── tools/
+│   ├── job_log.ts      # replaces ci__job_log with your own defineTool
+│   └── retry_job.ts    # export default disableTool() removes ci__retry_job
+└── skills/
+    └── triage.md       # replaces ci__triage
+```
+
+Use the extension's own names inside the directory, without the
+namespace. A file with a name the extension doesn't contribute adds a
+new tool or skill under the namespace. `disableTool()` comes from
+`@cursor/july/extensions` and fails discovery when it names a tool the
+extension doesn't have, so a typo can't silently keep a tool alive.
+A Cursor plugin mount overlays its MCP servers the same way; see below.
+
+## Mount a Cursor plugin
+
+A Cursor plugin is a directory with `.cursor-plugin/plugin.json` (or
+`.claude-plugin/plugin.json`, or `plugin.json`) and any of `skills/`,
+`commands/`, `agents/`, and `mcp.json`. Copy the plugin into your project
+and mount it with `cursorPlugin`. The filename is the namespace, as with
+any extension.
+
+```ts
+// agent/extensions/notion.ts
+import { cursorPlugin } from "@cursor/july/extensions";
+
+export default cursorPlugin({
+  path: "plugins/notion-workspace", // relative to the project root
+  variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
+});
+```
+
+The plugin joins the agent under that namespace:
+
+| Plugin content | Becomes |
+| --- | --- |
+| `skills/<name>/SKILL.md` | skill `notion__<name>` |
+| `commands/<name>.md` | skill `notion__<name>`, since a command is a procedure the model runs on request |
+| `agents/<name>.md` | subagent `notion__<name>` |
+| MCP servers in `mcp.json` or the manifest | connection `notion__<server>` |
+
+`variables` fills the `${NAME}` placeholders the plugin's MCP config
+declares; names you leave out come from the environment by exact name. A
+placeholder nothing fills fails `agent-sdk validate`, so a server never
+attaches half configured. A server that declares an OAuth client
+authorizes through [host MCP OAuth](/docs/guides/mcp-oauth.md) as
+`agent-sdk mcp oauth notion__<server>`; its secret names collapse the
+namespace separator, so `notion__notion` stores `MCP_OAUTH_NOTION_NOTION_*`.
+A server that lists `enabledTools` mounts as an advertised connection with
+that allowlist and requires the local runtime; `agent-sdk validate` fails
+otherwise.
+
+Mounting a plugin trusts it like authored code: its servers run the
+commands and read the environment variables its config names. Review a
+plugin before you vendor it.
+
+Plugin rules and hooks are not mounted; `agent-sdk validate` warns when a
+plugin carries them. To drop or reconfigure one of the plugin's servers,
+mount as a directory and overlay `mcp-connections/<server>.ts`. An
+overlaid server is never read from the plugin, so it needs no variables.
+
+```text
+agent/extensions/cloudflare/
+├── extension.ts                        # export default cursorPlugin({ path: "plugins/cloudflare" })
+└── mcp-connections/
+    ├── cloudflare-docs.ts              # replaces cloudflare__cloudflare-docs with your defineConnection
+    └── cloudflare-bindings.ts          # export default disableConnection() drops it
+```
+
+`disableConnection()` comes from `@cursor/july/extensions` and fails
+discovery when it names a server the plugin doesn't declare.
+
+## Build an extension
+
+An extension is a directory laid out like `agent/`. `extension.ts`
+declares it; `tools/` and `skills/` hold the contributions in the same
+authoring forms as [Tools](/docs/reference/tools.md) and [Skills](/docs/reference/skills.md).
+
+```text
+@acme/ci-triage/
+├── package.json
+├── extension.ts        # defineExtension
+├── tools/
+│   ├── failed_jobs.ts
+│   ├── job_log.ts
+│   └── retry_job.ts
+├── skills/
+│   └── triage.md
+└── lib/
+    └── buildkite.ts    # shared code, never discovered
+```
+
+Declare the extension with its root and, when consumers must configure
+it, a schema for their settings.
+
+```ts
+// extension.ts
+import { defineExtension } from "@cursor/july/extensions";
+import { z } from "zod";
+
+export default defineExtension({
+  root: import.meta.dirname,
+  description: "Investigate failing CI builds on Buildkite.",
+  config: z.object({
+    org: z.string(),
+    token: z.string(),
+    logTailLines: z.number().int().positive().default(200),
+  }),
+});
+```
+
+The default export is what consumers call to mount the extension, and it
+is also how your own modules read the consumer's settings. Import it and
+read `extension.config`; the value is validated and has defaults applied.
+
+```ts
+// tools/job_log.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+import extension from "../extension.js";
+import { jobLogTail } from "../lib/buildkite.js";
+
+export default defineTool({
+  description: "Read the tail of a CI job's log.",
+  effect: "read",
+  inputSchema: z.object({ pipeline: z.string(), build: z.number(), job: z.string() }),
+  async execute({ pipeline, build, job }) {
+    const { org, token, logTailLines } = extension.config;
+    return jobLogTail({ org, token, pipeline, build, job, lines: logTailLines });
+  },
+});
+```
+
+Because the consumer picks the namespace, have skills and tool
+descriptions refer to sibling tools by their short names and say they
+appear under the mount's namespace (`<namespace>__job_log`).
+
+Publish the built `extension.js` as the package entry point with
+`tools/` and `skills/` beside it. `root` is read from the built file, so
+copy `skills/*.md` into the build output or author skills as `.ts` with
+`defineSkill`.
+
+Only `tools/` and `skills/` are mounted from an extension tree.
+Instructions, connections, hooks, channels, and the runtime
+configuration belong to the agent that mounts the extension;
+`agent-sdk validate` warns when a tree carries agent slots such as
+`instructions.md`, `connections/`, `hooks/`, `channels/`, or
+`schedules/`.
+
+## What's next
+
+Continue with these pages:
+
+- [Cursor cloud agents](/docs/guides/cloud-agents.md): the extension that
+  lets an agent launch and steer cloud agents
+- [Tools](/docs/reference/tools.md): the tool contract extensions contribute to
+- [Skills](/docs/reference/skills.md): the skill forms an extension can carry
+- [Project layout](/docs/reference/project-layout.md): where `agent/extensions/` sits
+  in the tree
+
+---
+
 Source: /docs/reference/hooks.md
 
 # Hooks
@@ -7912,7 +8252,7 @@ and `playgroundUrl` deep-links the session in the playground.
 | `message` | Required user message |
 | `title` | Session title |
 | `dryRun` | Run read tools and stub write tools |
-| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tools declaring `timeArgs` refuse calls not bounded at or before it. `400` when unusable |
+| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tool calls with relative, later-than-`asOf`, or omitted schema-declared time bounds are refused. `400` when unusable |
 | `workspaceFiles` | UTF-8 files written into the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
 
@@ -8283,6 +8623,8 @@ experiments can override their file-derived name.
 | `agent/host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
 | `agent/skills/pr-review.md` | skill `pr-review` |
 | `agent/subagents/reviewer/` | subagent `reviewer` |
+| `agent/extensions/ci.ts` | extension mount `ci`; its tools and skills become `ci__<name>` |
+| `agent/extensions/notion.ts` | Cursor plugin mount `notion` (`cursorPlugin`); its skills, agents, and MCP servers become `notion__<name>` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
 | `agent/ab.ts` | A/B experiment `ab` unless `name` overrides it |
 | `agent/ab/concise.ts` | A/B experiment `concise` unless `name` overrides it |
@@ -8333,6 +8675,7 @@ Each path maps to a capability and a reference page.
 | `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](/docs/reference/connections.md) |
 | `agent/host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](/docs/reference/connections.md) |
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](/docs/reference/subagents.md) |
+| `agent/extensions/<ns>.ts` or `agent/extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](/docs/reference/extensions.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](/docs/reference/channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](/docs/reference/hooks.md) |
 | `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](/docs/guides/opentelemetry.md) |
@@ -8895,6 +9238,8 @@ Continue with these pages:
 
 - [Instructions](/docs/reference/instructions.md): what stays always-on
 - [Tools](/docs/reference/tools.md): when prose needs to become code
+- [Extensions](/docs/reference/extensions.md): skills installed as a package under a
+  namespace
 - [Project layout](/docs/reference/project-layout.md): where skills sit in the tree
 
 ---
@@ -9317,6 +9662,8 @@ Continue with these pages:
   lifecycle in full
 - [MCP connections](/docs/reference/connections.md): tools that come from MCP servers
   instead
+- [Extensions](/docs/reference/extensions.md): tools installed as a package under a
+  namespace
 - [Evals](/docs/evals.md): gating tool decisions with `calledTool`
 
 ---
@@ -9860,6 +10207,7 @@ Path is identity. Full list: README "Folder structure".
 | `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
 | `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
 | `agent/subagents/<id>/` | Child agent (`description` required) |
+| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin({ path })`); contributions are `<ns>__<name>` |
 | `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `agent/hooks/*.ts` | Observe-only |
 | `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |

package/dist/docs/llms.txt

@@ -34,6 +34,7 @@
 ## Guides
 
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context.
+- [Cursor cloud agents](/docs/guides/cloud-agents.md): 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.
 - [Cloud runtime](/docs/guides/cloud-runtime.md): Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.
 - [Convert a Cursor Automation](/docs/guides/convert-automation.md): Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it.
 - [GitHub](/docs/guides/github.md): Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.
@@ -64,6 +65,7 @@
 - [Channels](/docs/reference/channels.md): The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.
 - [CLI](/docs/reference/cli.md): Commands and common flags for local development, running servers, and Cursor-managed hosting.
 - [MCP Connections](/docs/reference/connections.md): Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.
+- [Extensions](/docs/reference/extensions.md): Mount a package of tools and skills or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/.
 - [Hooks](/docs/reference/hooks.md): Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.
 - [HTTP API](/docs/reference/http-api.md): Public session, discovery, and channel routes callers use.
 - [Instructions](/docs/reference/instructions.md): The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up.