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 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.

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	Keep chat local, set remote-runtime defaults, disable automatic PR creation, and isolate local harness workspaces.
Root instructions	agent/instructions.md	Separate local coordination from remote triage and define suggest/apply policy.
Drive tool	agent/tools/drive_pr.ts	Hand a chat request to the drive channel and wait for remote binding.
Drive channel	agent/channels/drive.ts	Start remote work and expose findings read/write routes.
GitHub channel	agent/channels/github.ts	Buffer PR, comment, review, check, and status wakes.
Slack channel	agent/channels/slack.ts	Route Slack requests to the local coordinator.
Hooks	agent/hooks/enroll-fsd.ts, agent/hooks/record-outputs.ts	Bind remote identity, enroll MCP, and forward fallback findings.
Affinity and buffering	agent/lib/pr-affinity.ts, agent/lib/webhook-buffer.ts	Persist PR identity, sticky mode, and pending wakes.
Reminders	agent/lib/merge-conflict-watch.ts	Recheck merge conflicts every 30 minutes.
Workflow client	agent/lib/fsd-platform.ts	Enroll external runs and read or record findings.
Storage	agent/storage.ts	Persist sessions and events with cursorHostedStorage.

The coordinator has no authored skill, subagent, MCP connection, static schedule, A/B experiment, eval, custom storage definition, 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:

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

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:

agent-sdk dev examples/fsd

From chat:

Drive https://github.com/owner/repo/pull/123 in suggest mode.

Or call the coordinator tool:

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:

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:

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 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:

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
• GitHub
• Webhooks and custom channels
• Schedules and reminders
• Sessions and streaming
• Deployment