PR #22940 - manaflow-ai/cmux

Summary

Leo opened https://cmux.com/deeplink/agent?harness=claude&session=e8f63fd9-…&host=cosmic-gray&message=5cf944c9-…. The page answered "This link includes unsupported parameters cmux will reject: message" and printed a bare cmux://agent: one parameter it did not know threw away the session and the host with it.

Two changes:

message is a parameter of the agent link, end to end on the web side: the shared schema, the page's model, and the native URL the page builds (cmux://agent/<harness>/<session>?host=&name=&message=). It names one message in the session's transcript for the app to scroll to.
An unknown parameter never drops the valid ones. An agent link is an address, not a command, so a name cmux does not know, a repeated parameter, or a hint whose value is outside the charset is reported by name in a warning and dropped; the session still opens. Only a missing or unusable harness/session stops the link. Ignored names are printed inside the charset a parameter name may have (at most eight), and no value from the URL is ever echoed. The ssh, prompt and rules kinds carry commands and stay strict.

One schema for the emitter and the parser. schemas/deeplinks/agent-link.json is now the single source of truth: the parameters, their charsets, what happens to an unknown one, and the vectors (including Leo's link). web/tests/deeplink-agent.test.ts asserts the page's parameter list, required list, query list and charsets are the schema's, and runs its vectors, so an emitter and a parser cannot drift without a red test. The app's cmux://agent parser and the message reveal are the companion PR on feat-cmux-next (it adds the same file byte-identically, so the base merge takes it cleanly); this one is the deployed page, which is served from main.

The other emitter of these links is the agent-identity host tool (manaflow-ai/cmuxterm-hq#2555), which writes harness/session/host/name and never message. Whatever emitted &message= for Leo is not in this repo; with this change the page accepts it either way.

Testing

bun test tests/deeplink-agent.test.ts tests/deeplink-agent-page.test.tsx in web/ on big-red (Linux; no Mac work here).

Red on the base: agentLinkModel({harness:"claude",session:"e8f63fd9-…",host:"cosmic-gray",message:"5cf944c9-…"}) returns null, which is the bug. The test commit (f6e7434) fails to import AGENT_PARAM_PATTERNS; 976ea5d passes 37 tests.
tests/deeplink-agent-page.test.tsx (new) renders the page itself: Leo's link shows Open in cmux and the full native URL with message=; ?…&cwd=/home/leo shows "cmux ignores parameters it does not use: cwd. The session still opens." with Open still offered and /home/leo nowhere in the output; a link with no session shows the missing-parameter error and no Open.
bun run typecheck, bun run lint:complexity (39 findings, all grandfathered — DeeplinkPage stayed under the limit by moving the issue checks into strictIssues/firstIssue) and bunx eslint on the changed files (one pre-existing <img> warning).
0ced197 syncs the page to the app's charset: the schema (and so the page) reads a harness of 1–64 lowercase letters, digits or -, which is what the app's DeepLink.isHarness accepts; the page read 1–32 and refused links cmux opens. 40 tests pass, and the charset-parity test fails if either side moves alone.
Localization audit: one new user-facing string, deeplink.ignoredParams, translated in all 20 locales of web/i18n/routing.ts; no new bare English in the changed files; the agent detail rows and existing error copy are unchanged.

Observed / Not run

Observed: the test runs above, and the page's own rendered output for the three cases.
Not run: next build and the rest of the web suite (CI's web lane), and any Mac work.

Changelog

Fixed: cmux.com agent links keep working when they carry a message id or a parameter cmux does not know

Agent session: big-red

🤖 Generated with Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need.}

Summary by cubic

Fixes the agent deeplink page so links with a message parameter open the session instead of being rejected. Previously cmux.com/deeplink/agent?…&message=… printed a bare cmux://agent and dropped the session; now message is a valid parameter that carries through to the native URL, and any unknown, repeated, or unusable optional parameter is reported by name in a warning while the session still opens. Only a missing or invalid harness/session stops the link. The ssh, prompt, and rules kinds stay strict.

Adds schemas/deeplinks/agent-link.json as the single source of truth for parameters, charsets, and test vectors; tests assert the page stays in sync, and a valueless optional parameter (?machine or ?host=) is named as ignored while the session still opens, on both readers.
Widens the accepted harness charset to 64 characters so the page no longer rejects harnesses the app's parser opens.
Reads machine, the hint every kind of cmux link carries, and keeps it in the native URL, written last as the app writes it.
Reports a repeated required parameter as a repeat and an empty one as missing, not as invalid; the page test renders the repeated session link and requires the repeat wording.
A sanitized ignored name that the link actually used is no longer shown, so the warning never contradicts the link.
Pins the printed-name rules (32-character cut, ? when nothing printable remains) in tests, and names the schema's page vectors so a deleted case fails instead of passing green.
Adds a deeplink.ignoredParams string in all 20 locales.

Summary by CodeRabbit

New Features
- Agent deep links now support validated session, host, name, machine, and message parameters across web and native links.
- Valid sessions can open despite unsupported, duplicate, or invalid optional parameters.
- Clear feedback identifies missing, invalid, duplicate, and ignored parameters.
- Added localized messaging across supported languages.
Bug Fixes
- Invalid or missing required parameters continue to block links.
Tests
- Expanded coverage for validation, parameter handling, and URL generation.