@cursor/july 0.1.111 → 0.1.113

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

@@ -1,59 +1,37 @@
 ---
-title: "Agent-to-agent"
-description: "Wire two Agent SDK agents on one host so one can ask the other."
+title: "Peer agents"
+description: "Let one Agent SDK agent consult an independent specialist, continue its session, or call its deterministic tools."
 ---
 
-# Agent-to-agent
+# Peer agents
 
-Point one agent at another on the same host. The peer keeps its own
-session, instructions, and tools.
+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. Co-host both projects under one `agent-sdk` process.
 
-## Peer or subagent?
-
-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.
-
-| | 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 |
-
-## How do I wire two agents?
+## Delegate a question to a specialist
 
-Put both projects in one directory:
-
-```
-agents/
-  concierge/
-    agent/instructions.md
-    agent/mcp-connections/weather.ts
-  weather-agent/
-    agent/instructions.md
-```
-
-`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:
+Ask the concierge about the weather and it hands the question to the
+specialist. The weather agent answers in its own context, then the
+concierge returns that answer to you.
 
 ```ts
-// agents/concierge/agent/mcp-connections/weather.ts
+// agent/mcp-connections/weather.ts
 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 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.
+Give the concierge a narrow routing rule:
 
-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.
+```md
+When a request needs current weather, ask the `weather` peer. Return its
+answer.
+```
 
 ```bash
 agent-sdk dev ./agents
@@ -61,15 +39,119 @@ agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
 ```
 
-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).
+The connection filename is the MCP server name the concierge calls, and
+`agent` is the specialist's mount slug, normally its directory name.
+
+## Continue the specialist's session
+
+Ask a follow-up about the same forecast and the specialist picks up
+where it left off, with its own instructions and tool history still in
+place. The first `ask` returns `{ status, sessionId, reply }` as text on
+the `callTool` result. Parse `sessionId` and pass it on the next `ask`
+so the peer remembers its earlier work instead of starting fresh.
+
+```ts
+const first = await ctx.host.mcp.callTool("weather", "ask", {
+  message: "What's the weather in Paris right now?",
+});
+const firstText = first.content.find((part) => part.type === "text");
+if (firstText?.text === undefined) {
+  throw new Error("weather ask returned no text payload");
+}
+const { sessionId } = JSON.parse(firstText.text) as { sessionId: string };
+
+await ctx.host.mcp.callTool("weather", "ask", {
+  message: "How does that compare with tomorrow?",
+  sessionId,
+});
+```
+
+If the specialist is still working, `ask` returns `status: "running"`
+with the session ID, and you can do other work before calling `check`.
+
+```ts
+await ctx.host.mcp.callTool("weather", "check", {
+  sessionId,
+  waitSeconds: 20,
+});
+```
+
+The peer owns this session. Follow-ups stay on the specialist and leave
+the concierge's conversation unchanged.
+
+## Call a deterministic peer tool
+
+You need a forecast for Paris, and the weather agent already has
+`get_forecast`. Host code calls that tool in the specialist's workspace
+and the forecast comes back to the concierge, with no second model turn.
+
+```ts
+const result = await ctx.host.mcp.callTool("weather", "call_tool", {
+  toolName: "get_forecast",
+  input: { city: "Paris" },
+});
+const part = result.content.find((item) => item.type === "text");
+if (part?.text === undefined) {
+  return { ok: false, forecast: null };
+}
+const payload = JSON.parse(part.text) as {
+  isError?: boolean;
+  result?: unknown;
+};
+
+return {
+  ok: result.isError !== true && payload.isError !== true,
+  forecast: payload.result ?? null,
+};
+```
+
+`call_tool` appears only when the peer declares at least one
+deterministic server tool.
+
+## Peer or subagent?
+
+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 | Peer |
+| --- | --- | --- |
+| 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 |
+
+## Affinity
+
+Follow-up `ask` and `check` calls resume the same specialist session
+and run as the caller. Those turns show up in the peer's playground;
+only that caller can continue or check the session.
+
+## Practices
+
+- Give each caller a one-way routing rule so agent A cannot send work
+  to B and receive the same request back.
+
+- Prefer `ask` when the specialist should reason. Use `call_tool` when
+  host code already knows which server tool to run.
+
+- Cursor-managed hosting deploys one agent per slug. Use
+  [subagents](../reference/subagents.md) there instead of peer
+  connections.
+
+## Other hosts
+
+Peers need the default multi-agent layout and one shared process;
+unknown slugs and self-references fail at startup.
 
-Unknown slugs and self-references fail `serve` at startup. Peers need
-the default multi-agent layout.
+For a self-hosted caller, expose the shared process with `--public-url`
+and protect it with `--bearer-token`. The
+[Deployment guide](../deployment.md) owns that hosting setup.
 
-## What's next
+## Related
 
-- [MCP connections](../reference/connections.md#peer-mcp-connection): `{ agent }`
+- [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
-- [HTTP API](../reference/http-api.md#mcp-endpoint): `/v1/mcp`
+- [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