@cursor/july 0.1.101 → 0.1.103

package/docs/design/runtime-abstraction.md

@@ -5,8 +5,8 @@
 > until this document has been reviewed.
 > **Audience:** Agent SDK and cursor-sdk maintainers; change-monitor as the
 > first consumer that is already faking a third runtime.
-> **Companions:** [cloud-runtime.md](../guides/cloud-runtime.md) (today's
-> user-facing contract),
+> **Companions:** [agent-config.md](../reference/agent-config.md#choose-a-runtime)
+> (today's user-facing contract),
 > [factory/change-monitor/docs/tools.md](../../../../factory/change-monitor/docs/tools.md)
 > (why change-monitor is pinned to local),
 > [factory/change-monitor/docs/computer-use.md](../../../../factory/change-monitor/docs/computer-use.md)
@@ -1604,7 +1604,6 @@ sandbox })`, next to `cloudRuntime({ repos })`. Sibling
 | Page | Change |
 |---|---|
 | [reference/agent-config.md](../reference/agent-config.md) | `runtime` type becomes constructors **or** the deprecated string. Table + "Choose a runtime" show `localRuntime(opts)` / `cloudRuntime(opts)` / `virtualRuntime(fs)` first. Move cwd / sandbox / workspaceDir onto the `localRuntime` section. Mark sibling `local` / `cloud` and string `runtime` deprecated. |
-| [guides/cloud-runtime.md](../guides/cloud-runtime.md) | Open with `cloudRuntime({ repos })`. Keep `runtime: "cloud"` as the still-supported form. Cloud is a turn host, not a filesystem. Hybrid is `send({ runtime: cloudRuntime(opts) })`; local overlay is `send({ runtime: localRuntime(opts) })`. `send({ cloud })` / `send({ workspaceDir })` deprecated. |
 | [concepts.md](../concepts.md) | Local vs cloud table: same facts, constructor names. Add one line that `virtualRuntime` is local-with-your-files, not a third host. |
 
 **New page**

package/docs/evals.md

@@ -157,17 +157,19 @@ Drive the agent with `t.send(message, options?)`. It runs one turn and
 waits for the session to park or fail. Multiple sends in one case share
 the session, which is how you write multi-turn evals.
 
-Each `t.send` resolves to a turn result with `message`, `sessionId`,
-`events`, `toolCalls`, `ok`, and `index`. The turn carries the same
-assertion vocabulary as `t`, scoped to that turn, so you can grade an
-intermediate turn before the next send overwrites `t.reply`.
-`turn.expectOk()` throws when the turn failed, for later steps that
-depend on it.
+Each `t.send` resolves to a turn result with `message`,
+`sessionId`, `events`, `toolCalls`, `ok`, and `index`. The turn carries
+the same assertion vocabulary as `t`, scoped to that turn, so you can
+grade an intermediate turn before the next send overwrites `t.reply`.
+`turn.expectOk()` throws when the turn failed, for later
+steps that depend on it.
 
 Read the full case state with `t.reply` (the last assistant text),
 `t.events` (session events captured so far), `t.turns` (settled
 turns, oldest first), and `t.sessionId`. `t.signal` aborts when the
-case hits its timeout; pass it to your own async work.
+case hits its timeout; pass it to your own async work. A thrown
+[turn result](./reference/result.md) `commit` fails the turn, so
+`t.succeeded()` fails too.
 
 Assert with the gates:
 

package/docs/guides/cloud-agents.md

@@ -0,0 +1,96 @@
+---
+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."
+---
+
+# 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
+[`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.
+
+## 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 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.
+
+## Configure it
+
+| 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](./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](../reference/extensions.md#adjust-a-mounted-extension).
+
+## What's next
+
+Continue with these pages:
+
+- [Extensions](../reference/extensions.md): how mounts, namespaces, and
+  overrides work
+- [Human-in-the-loop approvals](./human-in-the-loop.md): where parked
+  launches get approved

package/docs/guides/github.md

@@ -275,6 +275,5 @@ key. Handlers you author replace the matching defaults (same as
 - [Webhooks and custom channels](./webhooks.md): the HTTP mechanism under
   this pack
 - [Evals](../evals.md): turn replay snapshots into regression fixtures
-- [Cloud runtime](./cloud-runtime.md): attach PRs to cloud VMs
 - [Hooks](../reference/hooks.md): observe-only; use channel `progress` for
   GitHub surfaces

package/docs/guides/opentelemetry.md

@@ -8,7 +8,7 @@ description: "Push session, turn, and tool traces from the serve process to an O
 Agent SDK can push traces, metrics, and logs from the serve process to
 an OTLP collector you run. Point the process at the collector with
 standard `OTEL_EXPORTER_OTLP_*` env, or author `agent/otel.ts`. Traces
-cover the inbound request, the session, each turn, and every tool call.
+cover the inbound request, each turn, and every tool call.
 
 Export is opt-in. Nothing leaves the process until you set an endpoint
 or a `defineOtel` config.
@@ -17,7 +17,7 @@ or a `defineOtel` config.
 
 | Signal | Default | What you get |
 | --- | --- | --- |
-| Traces | on | `agent_sdk.http` → `agent_sdk.session` → `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
+| Traces | on | `agent_sdk.http` (per request) and `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
 | Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` session and turn counts |
 | Logs | off | Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in |
 
@@ -89,7 +89,17 @@ destination with `signals: ["traces"]`.
 
 You can also pass the same object to `serve(dir, { otel })`. Precedence
 is `serve({ otel })` over `agent/otel.ts` over env. An empty
-`defineOtel()` still enables export when `OTEL_EXPORTER_OTLP_*` is set.
+`defineOtel()` still records traces; export starts when
+`OTEL_EXPORTER_OTLP_*` or a factory-returned `exporters` list appears.
+
+Hosted v2 binds deployment secrets after bake, onto the already-listening
+process. Pass a factory so flush can re-read them. Spans record from
+bake; the hosted handler flush constructs the OTLP client and sends the
+queued batch.
+
+```ts
+export default defineOtel(() => resolveMyOtelConfig());
+```
 
 The companion skill is [`skills/otel/SKILL.md`](../skills/otel.md).
 
@@ -97,17 +107,23 @@ The companion skill is [`skills/otel/SKILL.md`](../skills/otel.md).
 
 ```text
 agent_sdk.http          inbound channel request (W3C traceparent)
-  └─ agent_sdk.session  cursor.conversation.id = session id
-       └─ agent_sdk.turn
-            ├─ agent_sdk.tool
-            └─ agent_sdk.subagent
-                 └─ agent_sdk.tool
+agent_sdk.turn          one root per turn (`agent_sdk.session_id` = session id)
+  ├─ agent_sdk.tool
+  └─ agent_sdk.subagent
+       └─ agent_sdk.tool
 ```
 
-Inbound HTTP extracts W3C `traceparent`, so a channel request parents
-the session span when the turn starts in that request. Turns that
-resume after restore, or a direct `callTool` with no `turn.started` in
-this process, open a synthetic turn span so tool calls still nest.
+Conversational sessions stay on `session.waiting` and can take more
+turns, so there is no `agent_sdk.session` span — it would never end
+and OTel only exports ended spans. Each turn is its own root. Inbound
+HTTP is a separate SERVER span (it extracts W3C `traceparent`) and
+does not parent the turn, so the turn tree can export when the turn
+ends. Hosted flush ends that SERVER span before the one-shot export so
+`agent_sdk.http` is in the same batch.
+
+Turns that resume after restore, or a direct `callTool` with no
+`turn.started` in this process, open a synthetic turn span so tool
+calls still nest.
 
 ## Which attributes land on the wire?
 
@@ -118,6 +134,12 @@ Every signal carries these resource attributes:
 - `cursor.surface=unspecified`
 - `agent_sdk.framework=@cursor/july`
 
+Span attributes (not process resource attributes — one serve process
+handles many sessions):
+
+- `agent_sdk.session_id` / `cursor.conversation.id`: the session id.
+  Search all turns for one conversation with `@agent_sdk.session_id`.
+
 Shared names (same keys as enterprise export):
 
 - `cursor.conversation.id`: the session id
@@ -128,22 +150,24 @@ Shared names (same keys as enterprise export):
   `cursor.tool.status`
 - `cursor.cost.usage` (USD)
 
-Agent SDK only (`agent_sdk.*`): agent name, turn id, channel, call id,
-subagent name, session mode, and HTTP duration (`agent_sdk.http.duration`).
+Agent SDK only (`agent_sdk.*`): session id, agent name, turn id, channel,
+call id, subagent name, session mode, and HTTP duration
+(`agent_sdk.http.duration`).
 
 ## How do I emit my own metrics?
 
 `ctx.host.otel` is always present on tools, hooks, and channel
 handlers. Counters and histograms no-op when no meter is running.
-`setAttributes` still tags the open session when a collector is
+`setAttributes` still tags open turn/tool spans when a collector is
 attached.
 
 Prefix metric names with your team or agent. First-party names
 (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`,
 `agent_sdk.session.count`, `agent_sdk.turn.count`,
 `agent_sdk.subagent.count`, `agent_sdk.http.duration`) and join keys
-(`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
-`agent_sdk.framework`) are reserved. Custom spans are not on this
+(`cursor.conversation.id`, `agent_sdk.session_id`, `agent_sdk.agent`,
+`agent_sdk.turn_id`, `agent_sdk.framework`) are reserved. Custom spans
+are not on this
 surface.
 
 ```ts

package/docs/reference/agent-config.md

@@ -82,11 +82,10 @@ the first prompt, because the local session workspace is not the cloud
 VM.
 
 `validate` warns when `runtime: "cloud"` is combined with agent tools
-or sandbox seeds (they only materialize into local session workspaces),
-when skills are present (they sync onto an Agent Store for native
-discovery rather than the session workspace), and when the `cloud`
-block is missing. The full capability matrix and the patterns that hold
-up are in the [Cloud runtime guide](../guides/cloud-runtime.md).
+(they are described on the first prompt instead of written to the VM),
+when skills or sandbox seeds are present (they sync onto an Agent Store
+rather than the session workspace), and when the `cloud` block is
+missing.
 
 ## Local options
 
@@ -172,9 +171,8 @@ set `local: { sandbox: true }`.
 Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
 `{ url, startingRef? }`), environment selection, `envVars`, and the
 rest. A local agent uses the same block as the base config when a
-channel opens a cloud-attached session per send. That hybrid pattern is
-covered in
-[Cloud runtime](../guides/cloud-runtime.md#hybrid-local-agent-cloud-sessions).
+channel opens a cloud-attached session per send (the `cloud` option on
+[`send`](./channels.md#handler-arguments)).
 
 ## Concurrency
 
@@ -251,6 +249,4 @@ Continue with these pages:
 
 - [Instructions](./instructions.md): the required half of a minimal
   agent
-- [Cloud runtime](../guides/cloud-runtime.md): when and how to leave
-  the host
 - [CLI](./cli.md): the `serve` flags `serve()` accepts

package/docs/reference/channels.md

@@ -142,8 +142,10 @@ The `events` map subscribes the channel to stream events for the
 sessions it owns. Keys are event types from the
 [event vocabulary](./sessions.md#which-events-can-i-stream), or `"*"`.
 Handlers receive `(event, channel, ctx)`, where `channel.state` is the
-per-session adapter state and `ctx` exposes session info and host
-services. This is where a channel delivers replies back to its surface.
+per-session adapter state, `ctx.session` is the session info, and
+`ctx.host` is the shared host services, bound to that session as in a
+[hook](./hooks.md#handler-context). This is where a channel delivers
+replies back to its surface.
 
 ## State and lifecycle
 
@@ -216,13 +218,21 @@ converge a merge-box check and sticky PR comment from default stream
 events. Guide: [GitHub](../guides/github.md).
 
 **Deployments** (`@cursor/july/channels/deployments`): pull deploy
-events. Subscribe per deploy source with `deploySourceUris`, narrow
-with `environments` / `events`, and handle each event in `onEvent`.
-`deploySourceUris` must match `Deployment.deploy_source_uri` as your
+events. Declare `events` and handle each one in `onEvent`. Each event
+carries `deploySourceUri` and `deployVersion`. Author
+`agent/channels/deployments.ts` with `deploymentsChannel()`.
+
+Omit `deploySourceUris` on hosted v2. The control plane binds
+`deploy_source` edges from the deploy's watched `repositories` and the
+channel admits what it is sent, which is what makes it multi-tenant
+safe.
+
+Name sources to narrow below that scope, or to drive the self-hosted
+pull relay, which has no deploy scope to inherit. There, subscribe per
+deploy source with `deploySourceUris` and narrow with `environments` /
+`events`. Each entry must match `Deployment.deploy_source_uri` as your
 deployment writer records it; matching is case-insensitive but
-otherwise literal. Each event carries `deploySourceUri` and
-`deployVersion`. Author `agent/channels/deployments.ts` with
-`deploymentsChannel()`. It uses the host credential. A restart resumes
+otherwise literal. It uses the host credential. A restart resumes
 rather than dropping events. An empty `deploySourceUris` list mounts
 the channel but starts no pull, so an env-configured agent stays inert
 until its deploy sources are set.

package/docs/reference/cli.md

@@ -5,10 +5,9 @@ description: "Commands and common flags for local development, running servers,
 
 # CLI reference
 
-`@cursor/july` installs `july` (so `npx @cursor/july docs` works) and
-`agent-sdk`. The examples on this page use `agent-sdk`. Run the CLI with
-Node 22.13 or newer. Don't run it with Bun; Bun corrupts tool-result
-streams from the Cursor SDK.
+`@cursor/july` installs one command, `agent-sdk`; `npx @cursor/july <cmd>`
+runs it. Run the CLI with Node 22.13 or newer. Don't run it with Bun; Bun
+corrupts tool-result streams from the Cursor SDK.
 
 `agent-sdk help` prints the built-in summary. The Slack and GitHub packs
 also provide `agent-sdk slack help` and `agent-sdk github help`.

package/docs/reference/extensions.md

@@ -0,0 +1,269 @@
+---
+title: "Extensions"
+description: "Mount a package of agent contributions 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/."
+---
+
+# Extensions
+
+An extension packages the same contributions an agent authors under
+`agent/` and installs them 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).
+
+Extensions are native to the Agent SDK. Slot files use the `@cursor/july`
+helpers, so a package built on another agent framework fails
+`agent-sdk validate` until you rewrite it onto `@cursor/july`.
+
+## 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.
+
+## What an extension can contribute
+
+An extension tree uses the same slots as [`agent/`](./project-layout.md).
+Each shareable contribution lands on the agent under the mount's
+namespace:
+
+| Path | Becomes |
+| --- | --- |
+| `tools/<name>.ts` | tool `<ns>__<name>` |
+| `skills/<name>` | skill `<ns>__<name>` |
+| `mcp-connections/<name>.ts` | connection `<ns>__<name>` |
+| `host-connections/<name>.ts` | host connection `<ns>__<name>` |
+| `hooks/<name>.ts` | hook `<ns>__<name>` |
+| `channels/<name>.ts` | channel `<ns>__<name>` |
+| `schedules/<name>` | schedule `<ns>__<name>` |
+| `subagents/<id>/` | subagent `<ns>__<id>` |
+| `instructions.md` / `.ts` / dir | appended to the agent's system prompt |
+| `sandbox/workspace/**` | seeded into each local session workspace |
+| `ab.ts` / `ab/<name>.ts` | A/B experiment `<ns>__<name>` |
+| `artifacts.ts` | artifact kinds `<ns>__<kind>` |
+
+The root agent still needs its own `instructions.md`. Extension
+instructions are extra fragments, not a substitute.
+
+`httpChannel()` stays on the agent. An extension authors
+`defineChannel` only; a file named `http.ts` becomes `<ns>__http`.
+
+These stay on the agent that mounts the extension. Each is a singleton
+or is outside discovery:
+
+| Path | Why it stays on the agent |
+| --- | --- |
+| `agent.ts` | One `defineAgent` runtime per agent |
+| `storage.ts` | One `host.kv` / `host.files` backend |
+| `otel.ts` | One OTLP exporter |
+| `ab.config.ts` | One experiment-platform config; `ab.ts` / `ab/` still merge |
+| `playground/` | Custom chips are a Vite glob of the agent tree, not a discovery walk |
+| `extensions/` | Nested mounts are not loaded |
+| `sandbox.ts` | Custom sandbox backends stay on the agent |
+
+`agent-sdk validate` warns when a tree carries those paths.
+
+## 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
+├── hooks/
+│   └── audit.ts        # export default disableHook() removes ci__audit
+└── skills/
+    └── triage.ts       # export default disableSkill() removes 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 contribution under the namespace. Each helper comes from
+`@cursor/july/extensions` and fails discovery when it names a
+contribution the extension doesn't have, so a typo can't silently keep
+it alive.
+
+| Slot | Helper |
+| --- | --- |
+| `tools/<name>.ts` | `disableTool()` |
+| `mcp-connections/<name>.ts` / `host-connections/<name>.ts` | `disableConnection()` |
+| `skills/<name>.ts` | `disableSkill()` |
+| `hooks/<name>.ts` | `disableHook()` |
+| `channels/<name>.ts` | `disableChannel()` |
+| `schedules/<name>.ts` | `disableSchedule()` |
+| `subagents/<id>.ts` | `disableSubagent()` |
+| `instructions.ts` | `disableInstructions()` |
+| `ab.ts` / `ab/<name>.ts` | `disableAB()` |
+| `artifacts.ts` | `disableArtifacts()` |
+
+`disable()` is the same brand as the slot helpers above and works in
+any of those files.
+
+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](../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; the slots in [What an extension can contribute](#what-an-extension-can-contribute)
+use the same authoring forms as the rest of this reference.
+
+```text
+@acme/ci-triage/
+├── package.json
+├── extension.ts        # defineExtension
+├── tools/
+│   ├── failed_jobs.ts
+│   ├── job_log.ts
+│   └── retry_job.ts
+├── skills/
+│   └── triage.md
+├── hooks/
+│   └── audit.ts
+├── mcp-connections/
+│   └── buildkite.ts
+└── 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 the
+slot directories beside it. `root` is read from the built file, so copy
+`skills/*.md` and `instructions.md` into the build output or author them
+as `.ts`.
+
+## What's next
+
+Continue with these pages:
+
+- [Cursor cloud agents](../guides/cloud-agents.md): the extension that
+  lets an agent launch and steer cloud agents
+- [Tools](./tools.md): the tool contract extensions contribute to
+- [Skills](./skills.md): the skill forms an extension can carry
+- [Project layout](./project-layout.md): where `agent/extensions/` sits
+  in the tree