Skip to content

Add surla stdio MCP transport, surla up global setup, /surla skill, and Herdr companion mod - #259

Merged
raphael merged 4 commits into
mainfrom
s2-stdio-setup
Nov 19, 2026
Merged

raphael merged 4 commits into
mainfrom
s2-stdio-setup

Conversation

@raphael

@raphael raphael commented Nov 19, 2026

Copy link
Copy Markdown
Member

Even with Herdr-optional server startup and attach_guide on the backend, developers still had no Chorus-style one-command setup (surla up / surla setup -global), no stdio MCP adapter (surla stdio) that coding agents can register globally without knowing per-project ports or bearer files in advance, no /surla ($surla) Agent Skill, and no native companion window inside Herdr.

Resulting behavior

  • surla stdio dynamic MCP transport (cmd/surla/stdio.go): Speaks newline-delimited JSON-RPC 2.0 over stdin/stdout with notifications/cancelled propagation. Resolves physical cwd once and confines any directory inside .surla-build or .surla-tests (including nested module subdirectories and leftover copies) strictly to builder or test_writer credentials without ever falling back to guide, starting servers, or handing over provider settings. Outside worker copies, initialize, ping, tools/list, and resources/list answer in memory from guide's generated MCP metadata with zero filesystem or process side effects until the first tools/call or resources/read, which starts or attaches the project server, hands over allowlisted shell provider variables, calls POST /project/attach-guide (adopting $HC_TERMINAL_ID live when inside Herdr), and relays requests to /mcp.
  • surla setup -global and surla up (cmd/surla/setup.go, cmd/surla/up.go): Registers "surla" (<executable> stdio) and installs the embedded /surla ($surla) skill (skills/surla/SKILL.md) idempotently across supported JSON and TOML coding-agent MCP configuration files (including Cursor, Windsurf, GitHub Copilot CLI, VS Code, ~/.agents, and in-place TOML table updates via github.com/pelletier/go-toml/v2). When Herdr's app directory exists, setup also installs the runtime companion mod (mods/surla/{mod.json,main.js}) and binds cmd-alt-shift-s -> mod.open:surla on macOS when free across every keymap section. surla up runs global setup (unless SURLA_NO_SETUP=1), starts chorus up with provider-scrubbed environment when chorus is installed, and degrades cleanly with a note when Chorus is absent.
  • Native Herdr companion mod (skills/herdr/surla/): Renders a 360px floating GPUI window (place: "none", overlay: { kind: "window" }) that skips remote SSH spaces, tracks active local project switches without stale cross-space state, polls read-only surla status --json every 4 seconds, focuses role terminals via pane.focus, and opens a fresh browser session via surla without holding user session tokens.

Dependencies and verification

Adds github.com/pelletier/go-toml/v2 (v2.4.3, pure Go, zero transitive dependencies) so config.toml updates preserve user comments and sibling tables at exact byte offsets. Verified with unit and race tests covering zero-side-effect tools/list, worker subtree confinement, request cancellation, rebind on server restart, JSON/TOML client config idempotency and symlinked temporary-binary refusal, Node tests for the Herdr mod across in-flight space switches, and herdr-app check.

surla setup -global registers `<surla> stdio` as the surla MCP server in
the global JSON or TOML configuration of every coding agent it finds
and installs the /surla skill next to each. JSON files keep every other
key and exact numbers; config.toml files are edited in place so comments
and other servers survive. A second run writes nothing.

When Herdr is present, setup copies the companion window's mod.json and
main.js into Herdr's mods folder and, on macOS, binds cmd-alt-shift-s when
that key is free. The window shows the shown space's project stage, what
needs the user and each role's state, focuses a role's pane, and opens the
views page by running surla. It reads only `surla status --json`.

The command is wired into the CLI with surla stdio and surla up.
…team

The companion window now shows only the result read for the folder of the
space Herdr shows: switching spaces shows "Reading the project…" at once,
reads the new folder within half a second, and drops an answer that arrives
for a folder no longer shown. An Open Page failure stays with its folder.

The /surla skill tells the guide to read its team and handle from
`surla status --json` and join `#<team>` on Chorus when available, and names
story_refresh_op_id, get_build, list_verifications and get_verification.

Setup refuses a config.toml whose mcp_servers is not a table, resolves
symlinks when refusing a temporary surla executable (including GOTMPDIR),
and writes skill and mod files atomically.
surla stdio is the MCP server every coding agent starts once setup has
registered it. The folder decides the role: inside a project's
.surla-build it is the builder, inside .surla-tests the test writer, and
anywhere else a guide. Until the first tool call or resource read it
answers initialize, ping and the tool and resource lists from the
generated catalog for that role, creating nothing. The first call binds:
a guide starts or attaches to the folder's project server, hands over the
shell's model settings and attaches as the project's guide, adopting its
Herdr terminal; a worker only reads the credential the running server
registered for it and never starts a server or attaches a guide. Later
requests are relayed to /mcp with that credential, binding again once if
the server refuses it. notifications/cancelled stops a request in flight.

surla up runs setup -global unless SURLA_NO_SETUP=1, then chorus up when
Chorus is installed, and the CLI now dispatches up, setup and stdio.
A project created in a child folder keeps its builder and test-writer
copies there, so a worker now binds to the registered agent whose working
folder holds it, falling back to the project folder's own copy only when
one agent has the role; the server's build is checked as surla does. The
guide binds from the agent's own folder rather than the process's.

Relayed requests no longer stop after ten minutes: the server bounds its
own operations, some of which run longer, and the agent cancels with
notifications/cancelled. A request is sent again only when the server
certainly did not run it (a refused credential or a refused connection),
so a tool that changes state is never sent twice.

surla up starts Chorus without the shell's model provider settings.

A new test binds a guide and both kinds of worker copy against the real
project server and control plane, including a rotated credential.
@raphael
raphael merged commit 44f46f5 into main Nov 19, 2026
25 checks passed
@raphael
raphael deleted the s2-stdio-setup branch November 19, 2026 21:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant