@cursor/july 0.1.108 → 0.1.111

package/docs/guides/agent-to-agent.md

@@ -1,45 +1,41 @@
 ---
 title: "Agent-to-agent"
-description: "Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context."
+description: "Wire two Agent SDK agents on one host so one can ask the other."
 ---
 
 # Agent-to-agent
 
-Every mounted agent is also an MCP server. So agents can delegate to each
-other without extra infrastructure. One agent hands a question to
-another, and the peer answers in its own session with its own
-instructions, tools, and context. Any external MCP client can do the
-same. A peer MCP connection makes the wiring one line.
+Point one agent at another on the same host. The peer keeps its own
+session, instructions, and tools.
 
-This guide wires a `concierge` agent that delegates weather questions
-to a `weather-agent` peer mounted on the same host.
-
-## MCP endpoint
+## Peer or subagent?
 
-Each agent serves the Model Context Protocol over streamable HTTP at
-`/<slug>/v1/mcp` (or `/v1/mcp` in single mode). The surface is stateless
-(session identity travels in tool arguments) and runs the same route
-auth chain as the session API. It exposes three tools:
+Use a [subagent](../reference/subagents.md) to split one job into roles
+inside a single agent. Use a peer when the specialist is a full agent
+you would run on its own.
 
-| Tool | Behavior |
-| --- | --- |
-| `ask` | Send a message. Runs a model turn in this agent's own session and returns `{ status, sessionId, reply }`. Omit `sessionId` for a fresh session; pass it back to follow up. |
-| `check` | Wait for or poll a running session (`waitSeconds: 0` polls without blocking). |
-| `call_tool` | Call one of the agent's server tools directly, no model turn. Registered only when the agent has server tools. |
+| | Subagent (`agent/subagents/<id>/`) | Peer (`defineConnection({ agent })`) |
+| --- | --- | --- |
+| Runs as | a child of this agent | an agent on the same host |
+| Tools, MCP connections, sessions | the parent's | its own |
+| Who can reach it | only the parent | other agents, MCP clients, its playground |
 
-Waits are bounded at roughly 50 seconds, below typical MCP client
-request timeouts: a long turn returns `status: "running"` and the caller
-keeps waiting with `check`. Sessions created this way live on the `mcp`
-channel, bind to the calling principal, and show up in the playground
-and `GET /v1/sessions` like any other session.
+## How do I wire two agents?
 
-Any MCP client can attach to this endpoint. It isn't only for other
-Agent SDK agents.
+Put both projects in one directory:
 
-## Wire a peer MCP connection
+```
+agents/
+  concierge/
+    agent/instructions.md
+    agent/mcp-connections/weather.ts
+  weather-agent/
+    agent/instructions.md
+```
 
-A peer MCP connection points one agent at another mounted on the same
-serve host. Author an MCP connection whose transport is the peer's slug:
+`weather-agent` is a normal Agent SDK project. On the concierge, add a
+connection. Set `agent` to the peer's slug, which is its directory
+name:
 
 ```ts
 // agents/concierge/agent/mcp-connections/weather.ts
@@ -51,68 +47,29 @@ export default defineConnection({
 });
 ```
 
-The parent model now sees the peer's `ask` and `check` (and `call_tool`)
-tools under the `weather` server name. It reads like subagent
-delegation, except the peer is a full agent that keeps its own
-instructions, tools, MCP connections, and sessions.
+The filename is the MCP server name. The concierge model sees the peer
+under `weather`. See
+[HTTP API](../reference/http-api.md#mcp-endpoint) for the MCP tools.
+
+In the concierge `instructions.md`, say when to ask: "When a request
+needs weather, ask the `weather` peer." Scope the line to the work the
+peer should handle. If two agents can ask each other, they will loop.
 
 ```bash
-agent-sdk serve --dir ./agents --dev
+agent-sdk dev ./agents
 agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
-# concierge → weather.ask → weather-agent's own session/tools → reply
 ```
 
-## Peer or subagent?
-
-The two delegation mechanisms solve different problems.
+Cursor-managed hosting deploys one agent per slug. Keep peers on one
+self-hosted process. Cloud-runtime turns need `--public-url` and
+`--bearer-token`. See [Deployment](../deployment.md).
 
-| | Subagent (`agent/subagents/<id>/`) | Peer (`defineConnection({ agent })`) |
-| --- | --- | --- |
-| Runs as | an SDK custom subagent inside the parent's harness | an independent agent on the same host |
-| Own tools, MCP connections, sessions | no, inherits the parent's surface | yes, everything is its own |
-| Visible to others | only its parent | any MCP client, other agents, its own playground |
-| Reach for it when | splitting one job into specialist roles | composing independently useful agents |
-
-## How peer URLs resolve
-
-Peer URLs resolve when the server starts, so the ephemeral ports `run`
-and `eval` use work too. Local-runtime turns (and host-side
-`ctx.host.mcp` or channel-handler calls) reach the peer over loopback,
-which works under the default auth. Cloud-runtime turns execute on a VM
-that cannot reach this host's loopback address: pass
-`--public-url https://agent-sdk.example.com` (or
-`serve(dir, { publicUrl })`) so peers resolve to a reachable URL.
-Without one, peers are omitted from cloud turns and the server warns at
-startup. With `--bearer-token`, the token is attached to peer calls
-automatically so they pass the target agent's auth chain.
-
-## Guardrails
-
-Unknown peer slugs and self-references fail `serve` at startup, so you
-find out immediately rather than at delegation time. Peers require the
-multi-agent layout (each agent mounted under its slug, the default).
-
-The framework does not provide cross-host loop protection. If agent A's
-instructions delegate to B and B's delegate back to A, they can recurse.
-Scope each agent's delegation instructions narrowly. The concierge
-delegates *weather questions* to `weather-agent`, not everything.
-
-## Call a peer from host code
-
-Peer MCP connections are ordinary MCP connections, so deterministic host code
-can use them too. A channel handler or server tool can call
-`host.mcp.callTool("weather", "ask", { message: "…" })` without any
-model turn deciding to. See
-[MCP connections](../reference/connections.md#every-model-visible-mcp-connection-is-available-in-three-places)
-for the three places every model-visible MCP connection is available.
+Unknown slugs and self-references fail `serve` at startup. Peers need
+the default multi-agent layout.
 
 ## What's next
 
-Continue with these pages:
-
-- [MCP connections](../reference/connections.md): all four MCP connection
-  transports
-- [Subagents](../reference/subagents.md): the in-harness alternative
-- [HTTP API](../reference/http-api.md#mcp-endpoint): the endpoint
-  contract
+- [MCP connections](../reference/connections.md#peer-mcp-connection): `{ agent }`
+- [Subagents](../reference/subagents.md): specialists inside one agent
+- [HTTP API](../reference/http-api.md#mcp-endpoint): `/v1/mcp`

package/docs/guides/bitbucket.md

@@ -0,0 +1,89 @@
+---
+title: "Bitbucket"
+description: "Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center."
+---
+
+# Bitbucket agents
+
+Use `bitbucketChannel()` for Bitbucket Cloud and Bitbucket Data Center. The
+channel detects the source from each signed payload and normalizes Data Center
+events to the Bitbucket Cloud event vocabulary.
+
+## Define the channel
+
+Author `agent/channels/bitbucket.ts`:
+
+```ts
+import { bitbucketChannel } from "@cursor/july/channels/bitbucket";
+
+export default bitbucketChannel({});
+```
+
+Without `onPullRequest`, new pull requests start turns. Data Center updates
+also start turns when the source branch has new commits. Comments and pushes
+are opt-in through `onPullRequestComment` and `onPush`. Use `onEvent` for
+other event types. Set `webhookEvents` when managed event delivery must
+subscribe to an event that only `onEvent` handles.
+
+Filter comment hooks by author before starting a turn. This prevents comments
+posted by the agent from triggering another turn.
+
+`ctx.bitbucket.api` can read pull requests, post comments, and create build
+statuses. See the [Channels reference](../reference/channels.md) for hook
+return values and session behavior.
+
+## Connect Bitbucket
+
+Set a repository hook secret and API token:
+
+```bash
+BITBUCKET_WEBHOOK_SECRET=...
+BITBUCKET_TOKEN=...
+```
+
+Add a repository webhook for
+`https://<your-host>/<slug>/v1/channels/bitbucket`. Use the same secret on
+both sides. The channel verifies the `X-Hub-Signature` HMAC before it parses
+the payload.
+
+Bitbucket Cloud uses its 2.0 API by default. Data Center also needs its REST
+API base:
+
+```ts
+export default bitbucketChannel({
+  apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
+  repos: ["PLATFORM/api"],
+});
+```
+
+You can set `BITBUCKET_API_BASE_URL` instead.
+
+## Test locally
+
+Start the agent, then replay a pull request you can read:
+
+```bash
+agent-sdk dev
+agent-sdk bitbucket replay \
+  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42
+```
+
+Replay supports Bitbucket Cloud and Data Center URLs. `BITBUCKET_TOKEN` needs
+pull request read access. The command reads the pull request, creates a payload
+in the matching dialect, and sends it through the same channel route. Use
+`--events '*'` to replay the supported events declared by the channel. Use
+`--dry-run --out fixtures/bitbucket` to save fixtures.
+
+```bash
+agent-sdk bitbucket events --dir .
+agent-sdk bitbucket forward --dir .
+```
+
+`forward` prints the repository-hook and HTTPS tunnel setup for live
+deliveries.
+
+## Related
+
+- [Channels reference](../reference/channels.md)
+- [Webhooks and custom channels](./webhooks.md)
+- [Evals](../evals.md)

package/docs/guides/cloud-agents.md

@@ -3,7 +3,7 @@ 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
+# 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.
@@ -14,7 +14,7 @@ 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: "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.
 
@@ -49,18 +49,18 @@ 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.
+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.
+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.
+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.
+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.
+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
@@ -73,13 +73,17 @@ 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. |
+
+| 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](../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.                                                                                                                                                                                     |
+
+
+
 
 ## Adjust it
 
@@ -92,6 +96,7 @@ directory and disable that tool; see
 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
+overrides work
+- [Gate a tool on human approval](../reference/tools.md#gate-a-tool-on-human-approval):
+where parked launches get approved
+

package/docs/guides/github.md

@@ -11,7 +11,7 @@ event stream for repos you've connected to Cursor. You still declare a
 `githubChannel` so hooks decide what each event does.
 
 The companion skill for coding agents is
-[`skills/github/SKILL.md`](../skills/github.md).
+[`skills/github/SKILL.md`](../../skills/github/SKILL.md).
 
 ## Pull events from Cursor
 
@@ -79,6 +79,37 @@ snapshot in the wake.
 This is the preferred production path: no public URL, no repo admin
 webhook, and no inbound network for GitHub deliveries.
 
+## Connect GitHub Enterprise Server
+
+GitHub Enterprise Server uses the same `githubChannel()` hooks and normalized
+events. Connect it through the direct webhook route. Set the REST API base and
+credentials for your server:
+
+```ts
+export default githubChannel({
+  api: {
+    apiBaseUrl: "https://github.example.com/api/v3",
+  },
+  credentials: {
+    token: () => process.env.GITHUB_TOKEN,
+    webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
+  },
+  onPullRequest: (ctx, pr) =>
+    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+});
+```
+
+Add a repository webhook for
+`https://<your-host>/<slug>/v1/channels/github`. Use the same webhook secret
+on the server and in `GITHUB_WEBHOOK_SECRET`. The channel verifies
+`X-Hub-Signature-256` before it parses the payload.
+
+Cursor account event pull, `github replay`, and `github forward` target
+GitHub.com. Test Enterprise Server integrations by posting saved webhook
+fixtures to a local `--dev` server. Leave `GITHUB_WEBHOOK_SECRET` unset for
+this local test so the channel admits unsigned loopback deliveries. Use a real
+delivery from your server so the fixture matches its version.
+
 ## Define the channel
 
 Author `agent/channels/github.ts` with `githubChannel()` from

package/docs/guides/gitlab.md

@@ -0,0 +1,97 @@
+---
+title: "GitLab"
+description: "Wake your agent from GitLab merge requests, notes, pipelines, and pushes on GitLab.com or self-managed GitLab."
+---
+
+# GitLab agents
+
+Use `gitlabChannel()` for GitLab.com and self-managed GitLab. The channel
+verifies project hooks, normalizes their payloads, and gives each hook a
+project-bound `ctx.gitlab` API client.
+
+## Define the channel
+
+Author `agent/channels/gitlab.ts`:
+
+```ts
+import { gitlabChannel } from "@cursor/july/channels/gitlab";
+
+export default gitlabChannel({});
+```
+
+Without `onMergeRequest`, new and reopened merge requests start turns.
+Updates start turns only when they include new commits. Notes, pushes, and
+pipelines are opt-in through `onNote`, `onPush`, and `onPipeline`.
+Use `onEvent` for other GitLab event types. Set `webhookEvents` when managed
+event delivery must subscribe to an event that only `onEvent` handles.
+
+Filter note hooks by author before starting a turn. This prevents comments
+posted by the agent from triggering another turn.
+
+`ctx.gitlab` can call the project REST API and create commit statuses. See the
+[Channels reference](../reference/channels.md) for hook return values and
+session behavior.
+
+## Connect GitLab
+
+On Cursor-managed hosting, use the signed-in Cursor account:
+
+```ts
+export default gitlabChannel({
+  cursorAccount: {
+    projects: ["acme/platform"],
+  },
+});
+```
+
+For direct webhooks, set a project hook secret and API token:
+
+```bash
+GITLAB_WEBHOOK_SECRET=...
+GITLAB_TOKEN=...
+```
+
+Add a project webhook for
+`https://<your-host>/<slug>/v1/channels/gitlab`. Use the same value for the
+GitLab secret token and `GITLAB_WEBHOOK_SECRET`. The channel checks
+`X-Gitlab-Token` before it parses the payload.
+
+Self-managed GitLab also needs its REST API base:
+
+```ts
+export default gitlabChannel({
+  apiBaseUrl: "https://gitlab.example.com/api/v4",
+  projects: ["acme/platform"],
+});
+```
+
+You can set `GITLAB_API_BASE_URL` instead.
+
+## Test locally
+
+Start the agent, then replay a merge request you can read:
+
+```bash
+agent-sdk dev
+agent-sdk gitlab replay \
+  https://gitlab.example.com/acme/platform/-/merge_requests/42
+```
+
+`GITLAB_TOKEN` needs API read access. Replay reads the merge request,
+creates GitLab-shaped payloads, and sends them through the same channel route.
+Use `--events '*'` to replay the supported events declared by the channel.
+Use `--dry-run --out fixtures/gitlab` to save fixtures.
+
+```bash
+agent-sdk gitlab events --dir .
+agent-sdk gitlab forward --dir .
+```
+
+GitLab has no local webhook relay. `forward` prints the project-hook and HTTPS
+tunnel setup for live deliveries.
+
+## Related
+
+- [Channels reference](../reference/channels.md)
+- [Webhooks and custom channels](./webhooks.md)
+- [Evals](../evals.md)

package/docs/guides/grokbot-agents.md

@@ -3,7 +3,7 @@ title: "Cursor Grok Bot agents"
 description: "Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval."
 ---
 
-# Cursor Grok Bot agents
+# Grok Bot agents
 
 The `cursor-grokbot-agents` extension lets an agent send a message to
 one of your Grok Bot agents and read the reply. The Grok Bot keeps its
@@ -35,8 +35,13 @@ a name outside the list is refused. Calls run under the host's
 signed-in account (`agent-sdk login`, `CURSOR_API_KEY`, or
 `CURSOR_SERVICE_ACCOUNT_KEY`). Keep approval on when you can't.
 
-Start from the [Grok Bot agents template](../templates/grokbot-agents.md)
-when you want a project that already mounts this.
+To scaffold a project that already mounts this:
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+
 
 ## What the agent can do
 
@@ -44,15 +49,15 @@ With the extension mounted, the agent can consult a Grok Bot and stay
 in its own conversation:
 
 - **Ask.** Send a self-contained message to a Grok Bot by the name
-  shown in the Grok Bot app. The message lands in your conversation
-  with that bot. The tool waits for the bot's reply.
+shown in the Grok Bot app. The message lands in your conversation
+with that bot. The tool waits for the bot's reply.
 - **Keep waiting.** A long turn returns `status: "running"`. Call check
-  with the same name to read what arrived since the last look.
+with the same name to read what arrived since the last look.
 - **Stop a turn.** Interrupt the bot's current work. The conversation
-  stays; a later ask continues it.
+stays; a later ask continues it.
 - **See who you can talk to.** List the configured bots and the ones
-  this caller has already asked. Add a name to `agents` when you want
-  the model to reach another bot.
+this caller has already asked. Add a name to `agents` when you want
+the model to reach another bot.
 
 A skill teaches the model when to bring a Grok Bot in, how to write a
 message the bot can act on alone, and how to wait or interrupt. The
@@ -69,11 +74,15 @@ need their own.
 
 ## Configure it
 
-| Option | What it controls |
-| --- | --- |
-| `agents` | The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit `agents` to allow any name; an unknown name creates an empty Grok Bot on the account. |
-| `needsApproval` | Park asks for a [human decision](./human-in-the-loop.md). Defaults to `true` when no `agents` are configured, `false` otherwise. |
-| `apiKey` | A Cursor API key to call with instead of the host's own. |
+
+| Option          | What it controls                                                                                                                                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents`        | The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit `agents` to allow any name; an unknown name creates an empty Grok Bot on the account. |
+| `needsApproval` | Park asks for a [human decision](../reference/tools.md#gate-a-tool-on-human-approval). Defaults to `true` when no `agents` are configured, `false` otherwise.                                                           |
+| `apiKey`        | A Cursor API key to call with instead of the host's own.                                                                                                                                                                |
+
+
+
 
 ## Adjust it
 
@@ -85,9 +94,8 @@ directory and disable that tool; see
 
 Continue with these pages:
 
-- [Grok Bot agents template](../templates/grokbot-agents.md): scaffold
-  an agent that already mounts this
 - [Extensions](../reference/extensions.md): how mounts, namespaces, and
-  overrides work
-- [Human-in-the-loop approvals](./human-in-the-loop.md): where parked
-  asks get approved
+overrides work
+- [Gate a tool on human approval](../reference/tools.md#gate-a-tool-on-human-approval):
+where parked asks get approved
+

package/docs/guides/mcp-oauth.md

@@ -13,7 +13,7 @@ deployment as secrets so prod can reconnect after a redeploy. Hosted
 Connect lets the current process retry.
 
 The companion skill is
-[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
+[`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
 
 ## What can host MCP OAuth do?