agent-rpc
Sideboard agent control plane. Agents talk JSON-RPC over a loopback WebSocket owned by the desktop (or the drain-owner process). Do not add new Sideboard capabilities as MCP-only tools. Use when adding a host method, a harness hook, or migrating a tool off stdio MCP.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- agent-rpc
- description
- Sideboard agent control plane. Agents talk JSON-RPC over a loopback WebSocket owned by the desktop (or the drain-owner process). Do not add new Sideboard capabilities as MCP-only tools. Use when adding a host method, a harness hook, or migrating a tool off stdio MCP.
03 SKILL.md 正文
Agent RPC
MCP stdio is the legacy agent transport (Codex until a hook lands; Claude/OpenCode orchestration until those hooks land). The authority for agent host calls is JSON-RPC on a loopback WebSocket started by the desktop.
This is not an MCP shim. Do not spawn sideboard mcp to implement a
new agent method. Do not add a stdio JSON-RPC that speaks MCP on one side
and this protocol on the other.
Judge
A change is done when:
pnpm --filter @sideboard-ai/core testcovers the new method (auth, dispatch, and the harness hook if you added one).- The method lives in
packages/core/src/agent-rpc/and is registered on the dispatcher — not only inpackages/core/src/mcp/server.ts. - The harness that should use it does not expose the same name on injected Sideboard MCP (no duplicate tools).
Break the judge once: a test with a bad authToken must fail closed.
Protocol
- JSON-RPC 2.0 text frames over WebSocket (
ws://127.0.0.1:<port>/agent-rpc). - Bind loopback only. The upgrade URL must carry
authTokenas a query param (timing-safe compare againstagent-runtime.json, mode0600); every request also carriesauthToken. Missing or wrong token → 401 /Unauthorized. - Long waits hold the call and send
runtime.progressnotifications. The hold cap (AGENT_RPC_JOB_HOLD_MAX_MS) must stay under the harness's own idle guard (Cursor:CURSOR_STREAM_IDLE_MS), and the hook must feed progress back into that guard. MCPwait_*keeps the 45s cap until that harness migrates. - Methods that touch the worktree (
job.*) require an absolutecwdparam. The desktop's cwd is not the agent's. - Desktop (drain owner) writes
{appDataDir}/agent-runtime.json. Hooks attach only when that file names a live pid; otherwise the harness keeps injected MCP. There is no in-process fallback inside a hook.
Harness hooks (not MCP)
The model still sees named tools. Those tools are native to the harness
and execute is a WebSocket client.
| Harness | Hook | Status |
|---|---|---|
| Cursor worktree | @cursor/sdk customTools |
Pilot: present_artifact, wait_for_job, stop_job |
| Cursor orchestration | same | Pilot set plus wait_for_turn (turn.wait) |
| Claude | Agent SDK createSdkMcpServer (claude-runner.ts) |
Worktree pilot: same three (mcp__sideboard_rpc__*). Orchestration still MCP. |
| OpenCode | OPENCODE_CONFIG_DIR plugin (tool() execute → WebSocket) |
Worktree pilot: same three. Orchestration still MCP. |
| Codex | — | Still MCP. Codex plugins only bundle MCP/apps, not in-process execute. Do not rip MCP. |
Do not teach the model to curl the socket or Bash-out to a CLI as the
primary path. That is not a hook.
Node runners (cursor-runner, claude-runner) live at
packages/core/dist/agents/<name>.js. Resolve them like Cursor
(__dirname of the core CJS bundle, then agents/<name>.js). Never
process.cwd() — Electron's cwd is apps/desktop.
Fan-out
Migrating the remaining MCP tools is the same shape every time:
- Add handler + schema on the dispatcher.
- Expose it on every hooked harness (Cursor
customTools, Claude SDK server, OpenCode plugin). Codex stays on injected MCP until it has an in-process execute hook. - Omit that name from injected Sideboard MCP for that harness
(
SIDEBOARD_AGENT_RPC_NATIVE=1skips the pilot set andwait_for_turnon orchestration MCP; extend the omit list as names move). - Throw away any MCP-only duplicate. Two names for one method is a failed migration.
Pilot methods (ui.presentArtifact, job.wait, job.stop, turn.wait)
before porting the rest. Next batch: ask_user, present_*, run-scripts,
notify_orchestrator, then Account issue tools, then the remaining
orchestration fleet (send_to_chat, create_workspace, …).
Do not
- Rip MCP from Codex (or Claude/OpenCode orchestration) until that harness has an in-process execute hook. Shipping a socket nobody calls is fine; stripping tools with no replacement is not. Cursor worktree and Cursor orchestration already hook the RPC-covered set.
- Add a stdio MCP whose only job is to speak this WebSocket (a shim). Claude
Agent SDK in-process
createSdkMcpServeris the documented custom-tool hook, not a stdio shim. - Use vendor MCP (Linear, GitHub, PostHog) as the Sideboard control plane.
- Bind
0.0.0.0or skipauthToken. - Document this as “Sideboard is an MCP server” in new copy. User-facing
sideboard mcpstays for hosts that only speak MCP until they are gone.
04 同仓库更多 Skills
skill-improver
When a miss will recur — you made it twice, or a person told you the rule — write the lesson into the skill before the turn ends. One sentence, in the same change. Run in the turn, not on a schedule.
release
暂无简介
long-running
暂无简介
worktree-install
Reinstall dependencies in a Sideboard worktree after merge-from-main or a lockfile change. Use when `pnpm install` hangs, several worktrees install at once, or a native build is outside the permitted directory.
review
Merge-readiness review for this repository. Use when reviewing a PR, worktree diff, or Sideboard Review (Approve / Approve with nits / Request changes).
release
Cut a Sideboard version. Default: bump, README/changelog, commit, merge, then push/retarget the `v*` tag so `.github/workflows/release.yml` publishes npm (OIDC) and the signed Mac desktop. No workflow_dispatch. Do not pack Electron in a worktree turn. Use for electron release, desktop release, pnpm release, or “I’ll publish npms.”