@cursor/july 0.1.92 → 0.1.93

package/docs/example-agents/fsd.md

@@ -1,334 +0,0 @@
----
-title: "Hand PR triage to managed remote agents"
-description: "Coordinate local chat, per-PR remote sessions, GitHub wake buffering, workflow MCP enrollment, durable affinity, findings, and reminders."
----
-
-# 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](../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.](../../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`](../../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`](../../examples/fsd/agent/instructions.md) | Separate local coordination from remote triage and define suggest/apply policy. |
-| Drive tool | [`agent/tools/drive_pr.ts`](../../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`](../../examples/fsd/agent/channels/drive.ts) | Start remote work and expose findings read/write routes. |
-| GitHub channel | [`agent/channels/github.ts`](../../examples/fsd/agent/channels/github.ts) | Buffer PR, comment, review, check, and status wakes. |
-| Slack channel | [`agent/channels/slack.ts`](../../examples/fsd/agent/channels/slack.ts) | Route Slack requests to the local coordinator. |
-| Hooks | [`agent/hooks/enroll-fsd.ts`](../../examples/fsd/agent/hooks/enroll-fsd.ts), [`agent/hooks/record-outputs.ts`](../../examples/fsd/agent/hooks/record-outputs.ts) | Bind remote identity, enroll MCP, and forward fallback findings. |
-| Affinity and buffering | [`agent/lib/pr-affinity.ts`](../../examples/fsd/agent/lib/pr-affinity.ts), [`agent/lib/webhook-buffer.ts`](../../examples/fsd/agent/lib/webhook-buffer.ts) | Persist PR identity, sticky mode, and pending wakes. |
-| Reminders | [`agent/lib/merge-conflict-watch.ts`](../../examples/fsd/agent/lib/merge-conflict-watch.ts) | Recheck merge conflicts every 30 minutes. |
-| Workflow client | [`agent/lib/fsd-platform.ts`](../../examples/fsd/agent/lib/fsd-platform.ts) | Enroll external runs and read or record findings. |
-| Storage | [`agent/storage.ts`](../../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](../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](../guides/cloud-runtime.md)
-- [GitHub](../guides/github.md)
-- [Webhooks and custom channels](../guides/webhooks.md)
-- [Schedules and reminders](../reference/schedules.md)
-- [Sessions and streaming](../reference/sessions.md)
-- [Deployment](../deployment.md)