@cursor/july 0.1.111 → 0.1.112

package/dist/docs/reference/extensions.md

@@ -1,207 +1,162 @@
 # 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).
+An extension packages capabilities that would otherwise live under
+`agent/`: tools, skills, instructions, connections, hooks, channels,
+schedules, subagents, artifacts, and workspace seeds. One mount file
+adds them under a namespace without copying their source into your
+project.
 
-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`.
+Extensions and Cursor plugins execute as trusted host code. A namespace
+prevents name collisions; it does not sandbox the package or limit its
+side effects. Review the package before mounting it.
 
 ## Mount an extension
 
-Install the package, then add one file. The filename is the namespace.
+Install the package and add one file under `agent/extensions/`. The
+filename becomes the namespace, so this mount contributes names such as
+`ci__failed_jobs` and `ci__triage`.
 
 ```ts
 // agent/extensions/ci.ts
 import ci from "@acme/ci-triage";
 
-export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
+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`.
+The extension validates its configuration while the project loads.
+Missing or mistyped settings fail `agent-sdk validate` before a turn
+can call the contributed code.
 
-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.
+Extension instructions are appended to the agent's prompt. The root
+agent still needs its own `agent/instructions.md`.
 
-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.
+## See what the extension added
 
-## What an extension can contribute
+Run discovery after mounting or upgrading an extension:
 
-An extension tree uses the same slots as [`agent/`](/docs/reference/project-layout.md).
-Each shareable contribution lands on the agent under the mount's
-namespace:
+```bash
+agent-sdk validate --dir .
+agent-sdk info --dir . --json
+```
+
+`info` lists each mount and its namespaced tools, skills, connections,
+hooks, channels, schedules, subagents, and artifact kinds. The same
+data appears under `extensions` in `GET /v1/info`.
 
-| 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 |
-| `artifacts.ts` | artifact kinds `<ns>__<kind>` |
-
-The root agent still needs its own `instructions.md`. Extension
-instructions are extra fragments, not a substitute.
-
-The built-in HTTP session channel 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 |
-| `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.
+Names inside the extension stay short. A tool authored as
+`tools/failed_jobs.ts` appears to the mounting agent as
+`<namespace>__failed_jobs`. The `__` separator is reserved, so root
+contributions cannot impersonate a mounted one.
 
 ## Adjust a mounted extension
 
-To replace or remove a contribution, mount the extension as a directory
-and overlay the slot you want to change.
+Mount as a directory when you need to replace or remove one
+contribution. Keep the package mount in `extension.ts`, then overlay the
+extension's short name beneath it.
 
 ```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
+  extension.ts
+  tools/
+    job_log.ts
+    retry_job.ts
+```
+
+```ts
+// agent/extensions/ci/tools/job_log.ts
+import { defineTool } from "@cursor/july/tools";
+import {
+  jobLogInput,
+  readRedactedLog,
+} from "../../../lib/ci.js";
+
+export default defineTool({
+  description: "Read a redacted CI log.",
+  inputSchema: jobLogInput,
+  execute: readRedactedLog,
+});
+```
+
+```ts
+// agent/extensions/ci/tools/retry_job.ts
+import { disableTool } from "@cursor/july/extensions";
+
+export default disableTool();
 ```
 
-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()` |
-| `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.
+The first file replaces `ci__job_log`; the second removes
+`ci__retry_job`. Use the matching `disable*` helper for another slot, or
+generic `disable()` when the file location already identifies it.
+Validation fails when an overlay names a contribution the package does
+not provide.
 
 ## 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.
+`cursorPlugin()` adapts a vendored Cursor or Claude plugin into the same
+namespace model. Skills, commands, agents, and MCP servers become Agent
+SDK skills, subagents, and connections.
 
 ```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! },
+  path: "plugins/notion-workspace",
+  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.
+`path` is relative to the project root. `variables` fills placeholders
+declared by the plugin's MCP configuration; unresolved placeholders
+fail validation instead of mounting a partial server.
 
-```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
-```
+Plugin rules and hooks are not mounted. Overlay a generated
+`mcp-connections/<server>.ts` file to replace or disable one plugin
+server. OAuth-backed plugin servers use
+[Host MCP OAuth](/docs/guides/mcp-oauth.md); transport and tool-filter
+details live in [MCP connections](/docs/reference/connections.md).
+
+## What an extension can contain
 
-`disableConnection()` comes from `@cursor/july/extensions` and fails
-discovery when it names a server the plugin doesn't declare.
+Share capabilities that can safely join another agent under a
+namespace:
+
+- Instructions, tools, skills, MCP and host connections
+- Hooks, channels, schedules, and subagents
+- Artifact kinds and local workspace seed files
+
+Agent-wide configuration does not compose through a mount.
+`agent.ts`, storage, OpenTelemetry, playground code, custom sandbox
+backends, and nested extensions are ignored in an extension package;
+`agent-sdk validate` reports unsupported paths.
 
 ## 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.
+Lay out the package like the shareable part of `agent/`. The root
+`extension.ts` supplies a description and validates any settings the
+consumer must provide.
 
 ```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
+  package.json
+  extension.ts
+  instructions.md
+  tools/
+    failed_jobs.ts
+    job_log.ts
+  skills/
+    triage.md
+  hooks/
+    audit.ts
+  lib/
+    buildkite.ts
 ```
 
-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";
@@ -209,7 +164,7 @@ import { z } from "zod";
 
 export default defineExtension({
   root: import.meta.dirname,
-  description: "Investigate failing CI builds on Buildkite.",
+  description: "Investigate failing Buildkite jobs.",
   config: z.object({
     org: z.string(),
     token: z.string(),
@@ -218,48 +173,21 @@ export default defineExtension({
 });
 ```
 
-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.
+Modules inside the package import this definition and read
+`extension.config`, which is already validated and has defaults
+applied. Publish the built entry point with its slot directories and
+prose assets beside it.
 
-```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";
+The [Project layout](/docs/reference/project-layout.md) owns each contribution's
+authoring contract. Keep extension instructions and tool descriptions
+namespace-neutral because the consumer chooses the final prefix.
 
-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 });
-  },
-});
-```
+## Related
 
-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](/docs/guides/cloud-agents.md): the extension that
-  lets an agent launch and steer cloud agents
-- [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): the extension
-  that lets an agent talk to Grok Bot agents
-- [Self-improvement](/docs/guides/improve.md): the extension that lets an
-  agent change its own source through a cloud agent and a pull request
-- [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
+- [Cloud agents](/docs/guides/cloud-agents.md): delegate repository work
+  through an extension
+- [Grok Bot agents](/docs/guides/grokbot-agents.md): consult named bots
+- [Self-improvement](/docs/guides/improve.md): propose source changes
+  through pull requests
+- [Project layout](/docs/reference/project-layout.md): contribution slots
+- [Tools](/docs/reference/tools.md) and [Skills](/docs/reference/skills.md): capability contracts