Accept browser session name wherever a session ID is taken

[rgarcia]

Summary

The Kernel API now resolves every /browsers/{id_or_name}/... route by session ID or session name (kernel/kernel#3731, released in @onkernel/sdk 0.98.0). This PR brings the MCP server in line so an agent can work with named sessions end to end.

• @onkernel/sdk bumped ^0.97.0 -> ^0.98.0. The sub-resource methods are positional, so the only code change the rename forced is replays.stop, whose params object field is now id_or_name.
• Every browser tool's session_id input is described as "Browser session ID or name": manage_browsers, computer_action, execute_playwright_code, execute_shell_command, browser_curl, manage_replays, plus the debug-browser-session prompt. Values were already forwarded unchanged to the SDK, so names work against the API without further changes.
• manage_browsers gains name and tags on create and update, forwarded to BrowserCreateParams / BrowserUpdateParams. On update, an empty name clears the name and {} clears tags, matching the API. Without this an agent could not create a session by name in the first place.
• Tool description for manage_browsers and the README note that sessions can be addressed by ID or name.

Testing

• New tests in browsers.test.ts: name/tags pass through create and update, and a name given as session_id reaches retrieve/deleteByID unchanged.

• bun test (280 pass), bunx tsc --noEmit, bun run check:managed-auth-app, and the OAuth Redis recordings check pass locally.

• bun.lock: besides the SDK bump, bun re-synced the workspace entry for next from 16.2.11 to ^16.2.11 to match package.json. bun install --frozen-lockfile passes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Sep 2, 2026 10:43pm UTC

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​onkernel/​sdk@​0.97.0 ⏵ 0.98.0	+1		+1	+1

View full report

[bmsaadat]

Review: request changes (two wording fixes, code is good)

Reviewed against the API at the deployed #3731 merge commit. The code change is minimal and correct: the SDK bump only renames path parameters and adds the webmcp resource, replays.stop is the sole call the rename touches, and name/tags forwarding matches how neighbouring scalar params are handled. bun test (280 pass), bunx tsc --noEmit, check:managed-auth-app, and a frozen-lockfile install all pass locally. #3731 has been live in prod since 19:05 UTC today, so there is no deploy-ordering concern.

Requested changes

1. Deleted sessions cannot be addressed by name, but the descriptions imply they can.
   src/lib/mcp/tools/browsers.ts:436 pairs "diagnose active or deleted sessions" with "addressed by ID or by name", and the debug prompt (src/lib/mcp/prompts.ts:101 plus the body) says telemetry works after deletion. On the API, the telemetry route resolves through querySessionByIDOrName, whose name branch is DeletedAtIsNil (covered by TestGetSessionByIDOrName/"telemetry read resolver accepts a name"), while the ID branch still reads the archive. So the one manage_browsers action where deleted sessions matter is exactly where a name returns a generic 404 "browser not found".
   Suggested session_id text: "Browser session ID or name. A name resolves only a live session; for a deleted session pass its ID (get_telemetry)." Same caveat on the prompt argument.

2. README over-claims name support.
   README.md:307 says every tool that takes a session_id accepts the name. manage_browser_pools release takes a session_id body field that the API matches by strict ID equality (browser_pools.go release handler), so a name is a 404 "session not found in pool". The name field text at browsers.ts:451 ("wherever a session_id is accepted") has the same problem. Suggest scoping both to the browser tools; optionally mark the pool release param as ID only.

Non-blocking

• name description could state the charset (letters, digits, ., _, -, 1-255 chars, not cuid-like) so an agent's first guess like "Checkout Flow" isn't a 400 round trip.
• Add an update test for name: "" clearing, since that's the advertised behavior; tags: {} is covered.
• tags is accepted on list and silently ignored. The SDK's list params support tags and query; wiring them would let an agent find a session by tag or name it doesn't already know. Fine as a follow-up.
• "the name given at creation" could be "or set on update".

Also verified

• Lockfile next specifier resync matches package.json on main; resolved package unchanged.
• kernel CLI v0.33.0 resolves the session argument via GET by id-or-name before every sub-resource call, so the debug prompt's CLI commands already work with a name.
• manage_replays list does resolve a deleted session's name (replay reads are deleted-inclusive on the API); get, update, delete, replay start/stop are live-only by name.
• Prettier warnings on the touched files pre-exist on main; CI doesn't run the format check.

[rgarcia]

Both requested changes and the non-blocking items are in f8b43bf.

1. Deleted sessions by name. session_id now reads: "Browser session ID or name. Required for update, get, get_telemetry, and delete actions. A name resolves only a live session; for a deleted session (get_telemetry) pass its ID." The tool description says live sessions by ID or name, deleted only by ID. The debug prompt carries the same caveat on its argument and in the telemetry section body.

2. README over-claim. Scoped to the six browser tools and states that deleted sessions and manage_browser_pools release take the ID only. The pool release session_id description now says "Must be the ID, not the session name." The name field text names the tools it works with instead of "wherever a session_id is accepted".

Non-blocking

• name description states 1-255 chars of letters, digits, ., _, -, not cuid-like.
• Added the name: "" clearing case to the update test.
• list now forwards query and tags to the SDK (with a test), so tags is no longer silently ignored on list and an agent can find a session by tag or name fragment.
• "given at creation or set on update".

bun test 281 pass, tsc clean.

[bmsaadat]

Re-review: approve

Re-checked f8b43bf against the API source rather than the summary. Everything from the last round is in and accurate:

• The live-only caveat for names is on session_id, the manage_browsers description, the debug prompt argument, and the prompt's telemetry section, and it matches how the telemetry route resolves names.
• README and the name field are scoped to the browser tools; manage_browser_pools release says ID only.
• Name charset text matches the API validator, including the cuid rule.
• Update test covers name: "" clearing; new list test covers query and tags forwarding.

Locally: bun test 281 pass, tsc clean, check:managed-auth-app pass. CI, Bugbot, and Vercel review are green.

One nit before merging: README.md:307 and the name description in src/lib/mcp/tools/browsers.ts:451 list execute_shell_command, but the tool is registered as exec_command (src/lib/mcp/tools/shell.ts:29, and the README's own standalone list uses exec_command). Rename and it's good to go.

Optional, no change needed: the README's "deleted sessions take the ID only" is slightly conservative, since manage_replays list also resolves a deleted session's name on the API. It's safe guidance as written.