@cursor/july 0.1.109 → 0.1.112

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

@@ -1,45 +1,31 @@
 ---
 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: "Let one Agent SDK agent consult an independent specialist, continue its session, or call its deterministic tools."
 ---
 
 # 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.
-
-This guide wires a `concierge` agent that delegates weather questions
-to a `weather-agent` peer mounted on the same host.
-
-## MCP endpoint
-
-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:
-
-| 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. |
-
-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.
-
-Any MCP client can attach to this endpoint. It isn't only for other
-Agent SDK agents.
-
-## Wire a peer MCP connection
-
-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:
+A peer connection lets one agent ask another agent on the same host for
+help. The specialist keeps its own instructions, tools, and session,
+while the caller decides when to delegate and returns the answer to the
+user.
+
+## How do I wire two agents?
+
+Put both projects under one directory, then point the concierge at the
+specialist's mount slug. When a user asks about weather, the concierge
+calls the peer's `ask` tool, the weather agent runs in its own context,
+and the concierge returns that answer.
+
+```text
+agents/
+  concierge/
+    agent/instructions.md
+    agent/mcp-connections/weather.ts
+  weather-agent/
+    agent/agent.ts
+    agent/instructions.md
+```
 
 ```ts
 // agents/concierge/agent/mcp-connections/weather.ts
@@ -47,72 +33,120 @@ import { defineConnection } from "@cursor/july/connections";
 
 export default defineConnection({
   agent: "weather-agent",
-  description: "Delegate weather questions to the weather agent.",
+  description: "Delegate weather questions to the weather specialist.",
 });
 ```
 
-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.
+Give the concierge a narrow routing rule:
+
+```md
+When a request needs current weather, ask the `weather` peer. Return its
+answer without delegating the same request again.
+```
 
 ```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
 ```
 
+The connection filename becomes the MCP server name. The `agent` value
+is the specialist's mount slug, normally its directory name.
+
+## Continue the specialist's conversation
+
+The first `ask` returns a peer `sessionId`. Pass that ID into the next
+`ask` when the specialist should remember its earlier work instead of
+starting with fresh context.
+
+```json
+{
+  "message": "How does that compare with tomorrow?",
+  "sessionId": "<session-id>"
+}
+```
+
+The peer owns this session. Follow-ups resume its instructions and tool
+history without merging them into the concierge's conversation.
+
+## Wait for long-running specialist work
+
+`ask` waits for a bounded time. If the specialist is still working, it
+returns `status: "running"` with the session ID, allowing the caller to
+do other work and check again later.
+
+```json
+{
+  "sessionId": "<session-id>",
+  "waitSeconds": 20
+}
+```
+
+Call the peer's `check` tool with that input. It returns the final reply
+when the turn settles, or another running status when more time is
+needed.
+
+## Call a deterministic peer tool
+
+When the specialist has a server tool and no second model turn should
+make a decision, call its `call_tool` endpoint through the peer
+connection. This example runs `get_forecast` in the weather agent's
+workspace and returns its structured result to the concierge tool.
+
+```ts
+const result = await ctx.host.mcp.callTool("weather", "call_tool", {
+  toolName: "get_forecast",
+  input: { city: "Paris" },
+});
+
+return {
+  ok: result.isError !== true,
+  forecast: result.structuredContent ?? null,
+};
+```
+
+`call_tool` appears only when the peer declares at least one
+deterministic server tool.
+
 ## Peer or subagent?
 
-The two delegation mechanisms solve different problems.
+Use a [subagent](../reference/subagents.md) to split one agent's job
+into roles that share its project. Use a peer when the specialist is a
+complete agent you would also run, inspect, or expose on its own.
 
-| | Subagent (`agent/subagents/<id>/`) | Peer (`defineConnection({ agent })`) |
+| | Subagent | Peer |
 | --- | --- | --- |
-| 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.
-
-## 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
+| Context | Child role inside one agent | Independent agent and session |
+| Tools and connections | Inherits the parent project | Owns its project surface |
+| Reachability | Parent only | Other co-hosted agents and MCP clients |
+
+## Peer sessions
+
+Calls through `ask` create sessions on the peer's `mcp` channel. They
+use the caller's authenticated principal and appear in the peer's
+playground, so the same authorization boundary applies to starts,
+follow-ups, and checks.
+
+There is no automatic recursion guard between peers. Give each caller a
+one-way routing rule so agent A cannot delegate the same work to B and
+receive it back from B.
+
+## Run peers on one host
+
+Peers require the default multi-agent layout and one shared `serve`
+process. Unknown slugs and self-references fail at startup.
+Cursor-managed hosting deploys one agent per slug, so use subagents
+there instead of peer connections.
+
+For a self-hosted cloud-runtime caller, expose the shared process with
+`--public-url` and protect it with `--bearer-token`. The
+[Deployment guide](../deployment.md) owns that hosting setup.
+
+## Related
+
+- [MCP connections](../reference/connections.md#peer-mcp-connection):
+  peer configuration and connection naming
+- [MCP endpoint](../reference/http-api.md#mcp-endpoint): exact `ask`,
+  `check`, and `call_tool` schemas
+- [Subagents](../reference/subagents.md): specialists inside one agent
+- [Deployment](../deployment.md): secure shared-host setup

package/docs/guides/bitbucket.md

@@ -1,89 +1,290 @@
 ---
 title: "Bitbucket"
-description: "Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center."
+description: "Review pull requests, answer comments, and triage pushes on Bitbucket Cloud or 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.
+A Bitbucket agent wakes from a verified repository event, reads the
+current pull-request or commit state, and writes the result back to
+Bitbucket. `bitbucketChannel()` gives the same hooks and normalized
+payloads on Bitbucket Cloud and Data Center.
 
-## Define the channel
+## Review a pull request
 
-Author `agent/channels/bitbucket.ts`:
+Creating a pull request, or pushing new commits to a Data Center pull
+request, starts a review. The hook reads the current diff through the
+repository-bound API, the model returns a verdict, and the completed
+answer appears as a comment on the pull request.
 
 ```ts
-import { bitbucketChannel } from "@cursor/july/channels/bitbucket";
+// agent/channels/bitbucket.ts
+import {
+  bitbucketChannel,
+  bitbucketChannelStateForEvent,
+  defaultBitbucketAuth,
+} from "@cursor/july/channels/bitbucket";
+import {
+  postPullRequestComment,
+  setPushTriageStatus,
+} from "../lib/bitbucket.js";
 
-export default bitbucketChannel({});
+export default bitbucketChannel({
+  repos: ["acme/widgets"],
+  onPullRequest: async (ctx, pullRequest) => {
+    if (pullRequest.draft) {
+      return null;
+    }
+    const hasNewCommits =
+      pullRequest.action === "updated" &&
+      pullRequest.previousHeadSha !== undefined &&
+      pullRequest.previousHeadSha !== pullRequest.headSha;
+    if (pullRequest.action !== "created" && !hasNewCommits) {
+      return null;
+    }
+
+    const diff = await ctx.bitbucket.api.getPullRequestDiff(pullRequest.id);
+    return {
+      // `auth` starts a model turn running as the event sender.
+      auth: defaultBitbucketAuth(ctx),
+      message: `Review ${ctx.repository.fullName}#${pullRequest.id}.`,
+      context: [`<bitbucket_diff>${diff}</bitbucket_diff>`],
+    };
+  },
+  events: {
+    async "message.completed"(event, channel, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      const pullRequestId = channel.state.pullRequestId;
+      if (
+        !channel.state.eventType?.startsWith("pullrequest:") ||
+        pullRequestId === null
+      ) {
+        return;
+      }
+      await postPullRequestComment(
+        channel.state,
+        pullRequestId,
+        event.data.text
+      );
+    },
+  },
+});
 ```
 
-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.
+`postPullRequestComment` is a small wrapper around the normalized
+Bitbucket API. Configure it with the same token and API base described
+under [Connect](#connect). It takes the repository and PR ID from the
+verified event state, so the model never chooses where its review is
+posted.
 
-Filter comment hooks by author before starting a turn. This prevents comments
-posted by the agent from triggering another turn.
+## Answer a pull-request comment
 
-`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.
+Mentioning `@cursor-reviewer` in a PR comment resumes that pull
+request's conversation, and the first example's reply sink posts the
+answer back to the same PR. The author guard ignores comments written
+by the agent, preventing each reply from starting another turn.
 
-## Connect Bitbucket
+```ts
+const AGENT_USERNAME = "cursor-reviewer";
 
-Set a repository hook secret and API token:
+onPullRequestComment: (ctx, comment) => {
+  if (comment.author?.username === AGENT_USERNAME) {
+    return null;
+  }
+  if (!comment.body.includes(`@${AGENT_USERNAME}`)) {
+    return null;
+  }
+  return {
+    auth: defaultBitbucketAuth(ctx),
+    message: comment.body,
+  };
+},
+```
 
-```bash
-BITBUCKET_WEBHOOK_SECRET=...
-BITBUCKET_TOKEN=...
+Add this property to the same `bitbucketChannel()` declaration as the
+review handler.
+
+## Triage a push to `main`
+
+A push to `main` immediately adds a running `cursor/push-triage` build
+status to the new commit. The webhook is acknowledged while the model
+investigates, then the status reports whether that triage turn
+completed.
+
+```ts
+onPush: (ctx, push) => {
+  const change = push.changes.find(
+    candidate =>
+      candidate.name === "main" && candidate.after !== undefined
+  );
+  if (change?.after === undefined) {
+    return null;
+  }
+  const sha = change.after;
+
+  return {
+    // `task` runs this host sequence after the webhook is acknowledged.
+    task: async ({ send }) => {
+      await ctx.bitbucket.setBuildStatus({
+        sha,
+        key: "cursor/push-triage",
+        state: "INPROGRESS",
+        name: "Cursor push triage",
+        description: "Investigating push to main",
+      });
+
+      await send(`Triage push ${sha} on ${ctx.repository.fullName}.`, {
+        auth: defaultBitbucketAuth(ctx),
+        title: `Bitbucket push ${sha}`,
+        state: {
+          ...bitbucketChannelStateForEvent({
+            repository: ctx.repository,
+            headSha: sha,
+            eventType: ctx.eventType,
+          }),
+        },
+      });
+    },
+  };
+},
+```
+
+Extend the `events` map so the turn's terminal event concludes the
+status through the same provider wrapper:
+
+```ts
+async "message.completed"(event, channel, ctx) {
+  if (
+    ctx.session.purpose !== "eval" &&
+    channel.state.eventType === "repo:push" &&
+    channel.state.headSha !== null &&
+    event.data.finishReason !== "tool_call"
+  ) {
+    await setPushTriageStatus(
+      channel.state,
+      "SUCCESSFUL",
+      "Push triage complete"
+    );
+    return;
+  }
+
+  // Continue with the pull-request reply branch from the first example.
+},
+async "turn.failed"(_event, channel, ctx) {
+  if (
+    ctx.session.purpose === "eval" ||
+    channel.state.eventType !== "repo:push" ||
+    channel.state.headSha === null
+  ) {
+    return;
+  }
+  await setPushTriageStatus(
+    channel.state,
+    "FAILED",
+    "Push triage failed"
+  );
+},
 ```
 
-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.
+This status reports the triage run, not the health of the pushed commit
+itself.
+
+## Events
+
+Use `onPullRequest`, `onPullRequestComment`, or `onPush` for the events
+shown above. Each hook returns one of three decisions:
+
+| Return | What happens |
+| --- | --- |
+| `{ auth }` | Start a model turn as the Bitbucket event sender |
+| `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
+| `null` | Skip the event |
+
+The [Channels reference](../reference/channels.md) covers the remaining
+hook and session behavior.
 
-Bitbucket Cloud uses its 2.0 API by default. Data Center also needs its REST
-API base:
+## Pull-request affinity
+
+Every pull-request event and comment for the same repository and PR ID
+resumes one agent session. A new PR, later commits, and a mention in the
+discussion therefore share the same conversation across both Bitbucket
+dialects.
+
+## Call Bitbucket through `ctx.bitbucket`
+
+Each hook receives an API client already bound to the repository and
+dialect from the verified delivery. Use `ctx.bitbucket.api` for
+pull-request reads and comments, `setBuildStatus()` for one status
+update, or `createCheck()` when a status changes throughout longer
+work.
+
+The repository does not come from model output. Keep API calls on this
+bound client so the event decides where reads and writes go.
+
+## Connect
+
+On Cursor-managed hosting, use the signed-in Cursor account and list
+the repositories that may wake the agent:
+
+```ts
+export default bitbucketChannel({
+  cursorAccount: {
+    repos: ["acme/widgets"],
+  },
+});
+```
+
+`cursorAccount` covers event delivery and API calls made through
+`ctx.bitbucket` inside hooks. The `postPullRequestComment` and
+`setPushTriageStatus` wrappers are separate REST clients, so configure
+their Bitbucket API credential too.
+
+For direct webhooks, configure the repository hook secret, API token,
+and allowed repositories. Data Center also needs its REST API base:
 
 ```ts
 export default bitbucketChannel({
-  apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
   repos: ["PLATFORM/api"],
+  webhookSecret: () => process.env.BITBUCKET_WEBHOOK_SECRET,
+  token: () => process.env.BITBUCKET_TOKEN ?? "",
+  apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
 });
 ```
 
-You can set `BITBUCKET_API_BASE_URL` instead.
+Without `webhookSecret`, the direct production route stays
+loopback-only. Setting it admits deliveries signed with the matching
+repository-hook secret; `token` authorizes the API reads and writes in
+the examples.
+
+Register the repository webhook at
+`https://<your-host>/<slug>/v1/channels/bitbucket` with the same secret.
+For Bitbucket Cloud, omit `apiBaseUrl`.
 
 ## Test locally
 
-Start the agent, then replay a pull request you can read:
+Replay lets you exercise the same hooks with a pull request you can
+read before registering a live repository webhook.
 
 ```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 .
+  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42 \
+  --events '*'
 ```
 
-`forward` prints the repository-hook and HTTPS tunnel setup for live
-deliveries.
+Use `--dry-run --out fixtures/bitbucket` to save the payloads instead of
+posting them. `BITBUCKET_TOKEN` needs read access to the pull request.
 
 ## Related
 
-- [Channels reference](../reference/channels.md)
-- [Webhooks and custom channels](./webhooks.md)
-- [Evals](../evals.md)
+- [Channels reference](../reference/channels.md): channel hooks,
+  dispatch decisions, and session behavior
+- [Webhooks and custom channels](./webhooks.md): direct webhook auth
+  and reply delivery
+- [Evals](../evals.md): turn saved Bitbucket payloads into regression
+  fixtures