@cursor/july 0.1.91 → 0.1.92

package/dist/docs/example-agents/fsd.md

@@ -0,0 +1,329 @@
+# Hand PR triage to managed remote agents
+
+The remote PR coordinator keeps chat and routing on the local serve host,
+then hands each pull request to a managed remote agent with a real checkout.
+The same remote conversation resumes when a user drives the PR again, GitHub
+reports a change, or a merge-conflict reminder fires.
+
+This example is Cursor-internal. For your own repos, scaffold
+[PR autofixer](/docs/templates/pr-autofixer.md) instead.
+
+The workflow backend enrolls each remote run with a workflow MCP. Its tools
+and the host's findings routes read and write the same external findings
+service.
+
+Use this example when repository work is too heavy or concurrent for local
+worktrees, but the host should still own intake, session identity, policy, and
+bookkeeping.
+
+[Browse the current coordinator source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/fsd/)
+
+## Resume one remote agent across every PR wake
+
+The coordinator uses a hybrid runtime:
+
+- Ordinary playground and Slack chat run locally.
+- The `drive_pr` server tool creates a remote session for one PR.
+- The remote worker gets the repository and PR reference.
+- An `agent.bound` hook records the remote run id and enrolls the run into a
+  workflow MCP.
+- Webhooks and reminders resume the same remote agent through durable
+  PR-to-agent affinity.
+
+No other example moves one logical conversation across local chat, remote
+execution, event wakes, and timed follow-ups.
+
+## Follow a chat request
+
+1. A user asks local chat or Slack to drive a PR.
+2. The root model calls `drive_pr` with the PR, mode, and optional hint.
+3. The tool calls `ctx.send("drive", ...)` with a per-session `cloud` block
+   to attach the PR.
+4. The Agent SDK creates or resumes the `drive` session keyed by
+   `pr:owner/repo#N`.
+5. The remote runtime provisions the agent and emits `agent.bound`.
+6. The enrollment hook writes PR affinity and calls the workflow backend to
+   attach run-scoped MCP tools.
+7. `drive_pr` waits for remote binding, then returns the agent id and URL.
+   If binding exceeds its wait window, those fields can be `null` while work
+   continues.
+8. The remote agent reads the host-prepared PR brief, checks unresolved state,
+   and records findings through the workflow MCP.
+9. The host forwards a validated fallback output block when MCP wasn't
+   available for the turn.
+
+The local chat agent doesn't have the target checkout, `gh`, `git`, or the
+workflow MCP. Its job is coordination.
+
+A request for a merged or closed PR finishes before provisioning. That result
+has `status: "finished"` and no remote session.
+
+## Map the framework features
+
+| Capability | Source | Role |
+| --- | --- | --- |
+| Hybrid config | [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/agent.ts) | Keep chat local, set remote-runtime defaults, disable automatic PR creation, and isolate local harness workspaces. |
+| Root instructions | [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/instructions.md) | Separate local coordination from remote triage and define suggest/apply policy. |
+| Drive tool | [`agent/tools/drive_pr.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/tools/drive_pr.ts) | Hand a chat request to the `drive` channel and wait for remote binding. |
+| Drive channel | [`agent/channels/drive.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/channels/drive.ts) | Start remote work and expose findings read/write routes. |
+| GitHub channel | [`agent/channels/github.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/channels/github.ts) | Buffer PR, comment, review, check, and status wakes. |
+| Slack channel | [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/channels/slack.ts) | Route Slack requests to the local coordinator. |
+| Hooks | [`agent/hooks/enroll-fsd.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/hooks/enroll-fsd.ts), [`agent/hooks/record-outputs.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/hooks/record-outputs.ts) | Bind remote identity, enroll MCP, and forward fallback findings. |
+| Affinity and buffering | [`agent/lib/pr-affinity.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/pr-affinity.ts), [`agent/lib/webhook-buffer.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/webhook-buffer.ts) | Persist PR identity, sticky mode, and pending wakes. |
+| Reminders | [`agent/lib/merge-conflict-watch.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/merge-conflict-watch.ts) | Recheck merge conflicts every 30 minutes. |
+| Workflow client | [`agent/lib/fsd-platform.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/fsd-platform.ts) | Enroll external runs and read or record findings. |
+| Storage | [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. |
+
+The coordinator has no authored skill, subagent, MCP connection, static
+schedule, A/B experiment, eval, or tool approval.
+
+The workflow MCP is dynamic. Backend enrollment attaches it to the remote run,
+so there is no file under `agent/mcp-connections/`.
+
+## Understand local and remote workspaces
+
+The root config sets `runtime: "local"` because `drive_pr` is a server tool.
+It also supplies remote-runtime defaults through the `cloud` configuration:
+
+```ts
+local: {
+  cwd: join(homedir(), ".cache", "agent-serve", "fsd"),
+},
+cloud: {
+  env: { type: "cloud" },
+  autoCreatePR: false,
+},
+```
+
+The local cwd sits outside the monorepo, so inherited repository instructions
+don't affect coordinator chat.
+
+Remote sessions get a repository attachment with the target PR. The worker starts
+from the PR base and creates an automation side branch from the PR head only when
+code context or a fix is needed. The serve host never checks out target code.
+
+## Prepare access
+
+You need:
+
+- Node 22.13 or newer.
+- An agent-runtime user credential.
+- Access to a managed remote runtime.
+- Access to the target GitHub PR.
+- Access to the workflow backend and findings store.
+
+Keep the affinity and webhook-buffer files on durable storage for a
+long-lived host.
+
+## Validate without starting remote work
+
+```bash
+agent-sdk validate --dir examples/fsd
+agent-sdk info --dir examples/fsd --json
+agent-sdk github events --dir examples/fsd --json
+```
+
+These commands inspect discovery and declared GitHub events. They don't
+provision a remote agent.
+
+## Choose suggest or apply
+
+Every PR has a sticky mode:
+
+| Mode | Required remote behavior |
+| --- | --- |
+| `suggest` | May create verified commits on the VM's local side branch. Instructions require no pushes, comments, PR edits, or workflow actions. Records exact fixes and actions as findings for the owner. |
+| `apply` | Pushes verified fixes to the existing PR head and may update metadata, reply to threads, mark a draft ready, rebase, or rerun CI. |
+
+The remote instructions forbid merging, enabling auto-merge, force-pushing,
+and opening a new PR in both modes. `autoCreatePR: false` also disables the
+SDK's automatic PR creation. The other restrictions are prompt policy, not a
+deterministic host gate. `suggest` is the default.
+
+The selected mode is stored beside PR affinity. Webhooks and reminders reuse
+it. Re-driving a PR can change the host-side mode. Backend enrollment records
+the mode at first enrollment, so each later host prompt repeats the current
+authoritative mode.
+
+> [!CAUTION]
+> `apply` writes to the user's PR branch and triggers CI. Use `suggest` for
+> development. Both modes provision a billed remote agent and can write
+> structured findings to the findings service. `drive_pr` has no approval gate,
+> and suggest/apply restrictions depend on the remote agent following its
+> instructions.
+
+## Start a suggest-mode drive
+
+Run the host:
+
+```bash
+agent-sdk dev examples/fsd
+```
+
+From chat:
+
+> Drive https://github.com/owner/repo/pull/123 in suggest mode.
+
+Or call the coordinator tool:
+
+```bash
+agent-sdk call drive_pr \
+  --dir examples/fsd \
+  --input '{"pr":"https://github.com/owner/repo/pull/123","mode":"suggest"}'
+```
+
+For an open PR, the tool waits up to 60 seconds for remote binding and returns:
+
+- the normalized PR label,
+- session and continuation ids,
+- the remote-agent id and URL when binding completes in that window,
+- `status: "started"`, and
+- the merge-conflict reminder id.
+
+It doesn't wait for findings. A slow binding can return `null` identifiers.
+Open the returned agent URL when present to follow the remote run.
+
+## Use the HTTP drive surface
+
+The custom channel starts the same orchestration:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/fsd/v1/channels/drive/ \
+  -H 'content-type: application/json' \
+  -d '{"pr":"owner/repo#123","mode":"suggest"}'
+```
+
+This route returns as soon as the channel session exists. The remote-agent id
+can still be `null` at that point. Triage continues in the background.
+
+Read findings later:
+
+```bash
+curl -s \
+  'http://127.0.0.1:3000/fsd/v1/channels/drive/findings?pr=owner/repo%23123'
+```
+
+The external findings service is the source of truth. The local host doesn't keep a second
+findings database.
+
+The channel also exposes `POST /findings` as a testing surface. It validates
+outputs, then writes them to the findings service for a PR already bound by this
+host. The route has no approval gate. Keep it under the default loopback auth
+or another trusted boundary.
+
+## Keep one remote agent per PR
+
+Within the `drive` channel, the stable continuation token
+`pr:owner/repo#N` resumes the same session. GitHub sessions are scoped to
+another channel, so a continuation token alone can't bridge them.
+
+The enrollment hook closes that gap:
+
+1. Read the PR from the continuation token or host-authored session title.
+2. Record PR to `sdkAgentId` affinity after `agent.bound`.
+3. Seed later sessions with the same remote id.
+4. Retry workflow MCP enrollment after a completed turn when the first RPC
+   failed.
+
+This lets Slack, HTTP drive, GitHub, and reminders talk to one remote
+conversation without sharing one channel session.
+
+## Buffer GitHub wakes
+
+The GitHub channel handles pull requests, comments, reviews, check suites,
+check runs, and selected status events. It doesn't send payload details to the
+model. It asks the remote agent to refresh live source of truth.
+
+The buffer:
+
+- groups events by PR,
+- waits three seconds for a burst to settle,
+- re-buffers while CI settles,
+- skips a flush when the PR session is busy,
+- tries to write its snapshot before acknowledging a wake, and
+- restores pending entries when the channel starts.
+
+Closing a PR discards its pending entry and cancels its reminders.
+
+Snapshot persistence is best-effort. Write failures are swallowed silently,
+so a delivery can still be acknowledged without a durable snapshot.
+
+This is the high-volume counterpart to a direct `{ auth }` GitHub wake. See
+[GitHub](/docs/guides/github.md#handle-high-event-volume) for the reusable
+pattern.
+
+## Add merge-conflict checks
+
+Starting a drive arms one recurring reminder per PR. Every 30 minutes the host
+checks mergeability:
+
+- closed or merged stops the reminder,
+- clean skips delivery,
+- conflicting sends a follow-up to the owning session, and
+- a busy session skips the wake.
+
+This uses runtime reminders, not a static `agent/schedules/` file. The host
+creates, lists, replaces, and cancels reminders through `host.reminders`.
+Development mode doesn't fire reminder timers automatically. Dispatch one
+through the dev reminder endpoint for a manual proof, or use non-dev `serve`
+to run the 30-minute cadence.
+
+The reminder's `run` handler lives in memory. After a host restart, the Agent SDK
+disarms it with `handler_lost_on_restart`; a later drive or webhook path can
+arm a fresh handler. Persisted reminder metadata alone doesn't keep the check
+running.
+
+## Record findings with MCP or a fallback
+
+After enrollment, the remote agent receives workflow tools for:
+
+- recording and updating outputs,
+- listing current outputs,
+- reading PR metadata,
+- reading CI state, and
+- reading review comments.
+
+The main output is a structured workflow suggestion or code-change reference.
+The remote prompt requires findings as soon as each action becomes clear.
+
+If enrollment races or MCP is unavailable, the agent writes one fenced
+fallback JSON block. The host validates allowed kinds, actions, statuses, and
+the 140-character finding body before forwarding it to the same findings
+service. The output hook catches fallback blocks from webhook and reminder
+turns.
+
+## Verify the host logic
+
+The coordinator has no filesystem evals. Its unit tests cover mode parsing, drive
+orchestration, affinity, webhook durability, CI settlement, output parsing,
+reminders, and Slack configuration:
+
+```bash
+pnpm exec vitest run examples/fsd/agent/lib
+```
+
+Use those tests for host policy. Use a dedicated test PR and suggest mode for
+the end-to-end remote path.
+
+## Build another hybrid coordinator
+
+Use this architecture when each work item needs a real checkout:
+
+1. Keep conversational intake local.
+2. Open a remote session only after the request identifies a work item.
+3. Give the work item a stable continuation key.
+4. Persist its remote-agent id for cross-channel resume.
+5. Coalesce noisy events before spending another turn.
+6. Put the current mode and permissions in every host prompt.
+7. Record outputs incrementally in a durable sink.
+8. Add reminders for state requiring periodic rechecks.
+
+## Where to go next
+
+- [Cloud runtime](/docs/guides/cloud-runtime.md)
+- [GitHub](/docs/guides/github.md)
+- [Webhooks and custom channels](/docs/guides/webhooks.md)
+- [Schedules and reminders](/docs/reference/schedules.md)
+- [Sessions and streaming](/docs/reference/sessions.md)
+- [Deployment](/docs/deployment.md)