fix(mcp): keep 2025 revisions on the legacy wire contract and require modern metadata

Review found the era model was too loose in two ways.

Membership was one flat set, so a request declaring 2025-11-25 or
2025-06-18 through modern `_meta` was served the 2026-only envelope
(`resultType`, `serverInfo`, cache hints) — fields absent from those
revisions' schemas — and `initialize` would echo 2026-07-28, agreeing to a
revision whose handshake the modern era removed. Split modern and legacy
membership so the declared revision picks the wire contract: 2025 declared
through modern framing is answered legacy-shaped, `server/discover` requires
a modern revision because it exists in no legacy one, and `initialize`
negotiates only within the legacy set.

Modern request metadata is now required rather than guessed. `_meta`
carries `protocolVersion` and `clientCapabilities` as required fields, so
`server/discover` without them is malformed instead of being promoted to
modern, and a half-declared `_meta` is rejected as invalid params (-32602)
rather than having its lenient handling locked in by tests.

Adds black-box router cases for declared-2025 requests, initialize(2026),
`server/discover` with missing and with legacy metadata, and a declared
revision without client capabilities.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKWswqMZ6Z9UAQDAda83Xz

Author: claude

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-- `agent-device mcp` now serves the stateless MCP `2026-07-28` revision alongside the handshake-based revisions it already spoke, as the spec's "dual-era server". Modern clients probe `server/discover`, which advertises the supported revisions, the tools capability, and server identity; their requests declare a protocol version in `_meta`, and their results carry `resultType: "complete"` plus `_meta["io.modelcontextprotocol/serverInfo"]`. `tools/list` and `server/discover` now return the `ttlMs`/`cacheScope` cache hints, so a client can cache the 55-tool, ~223KB tool list for an hour instead of re-fetching it on every start; the list was already emitted in a deterministic (sorted) order, which is the other half of what makes it cacheable. A declared revision this server does not implement is rejected with `UnsupportedProtocolVersionError` (`-32022`) naming the ones it does, rather than being served under a version the client did not ask for. Responses to legacy clients are unchanged byte-for-byte — `initialize` and `ping` are still served, and no cache, `resultType`, or `_meta` field is added to their results. Nothing here affects the CLI, Node, or daemon surfaces: the stdio transport, the tool set, and every tool's input/output schema are untouched.
+- `agent-device mcp` now serves the stateless MCP `2026-07-28` revision alongside the handshake-based revisions it already spoke, as the spec's "dual-era server". Modern clients probe `server/discover`, which advertises the supported revisions, the tools capability, and server identity; their requests declare a protocol version in `_meta`, and their results carry `resultType: "complete"` plus `_meta["io.modelcontextprotocol/serverInfo"]`. `tools/list` and `server/discover` now return the `ttlMs`/`cacheScope` cache hints, so a client can cache the 55-tool, ~223KB tool list for an hour instead of re-fetching it on every start; the list was already emitted in a deterministic (sorted) order, which is the other half of what makes it cacheable. Each revision is answered on its own wire contract: a request declaring `2025-11-25` or `2025-06-18` through modern framing still gets the legacy result shape, and `initialize` never agrees to `2026-07-28`, which has no handshake to establish. A declared revision this server does not implement is rejected with `UnsupportedProtocolVersionError` (`-32022`) naming the ones it does, rather than being served under a version the client did not ask for, and modern framing that omits its required `protocolVersion`/`clientCapabilities` metadata is rejected as invalid params. Responses to legacy clients are unchanged byte-for-byte — `initialize` and `ping` are still served, and no cache, `resultType`, or `_meta` field is added to their results. Nothing here affects the CLI, Node, or daemon surfaces: the stdio transport, the tool set, and every tool's input/output schema are untouched.
 - Fixed: the MCP `initialize` handshake now answers with the protocol revision the client requested when it is one this server implements, instead of always answering `2025-11-25`. A client pinned to `2025-06-18` was told to speak a revision it had not asked for, which the lifecycle contract answers by disconnecting.
 - `agent-device help workflow` is now a compact ~8KB card instead of a ~41KB dump; the same depth still exists, split into `help scripting` (save-script, secret-safe fills, batch JSON, replay divergence/repair, recording) and `help gestures` (multi-touch shapes and platform quirks), plus a few paragraphs folded into the topics that already owned the subject (`help debugging`, `help physical-device`, `help validate`). Every `help <topic>` first line is now `agent-device <version> — <topic>` so an agent can read the installed version from its mandatory first help read instead of a separate `agent-device --version` call.
 - Cloud iOS (BrowserStack, AWS Device Farm): `snapshot` and `diff` no longer fail with `SESSION_NOT_FOUND` on a live provider session (#1658). The app-session guard they ran belongs to the local XCUITest runner, which must attach to a target app; a cloud capture reads the provider's own driver session and needs no app identity, so the guard now applies to local Apple targets only. Relatedly, a cloud iOS `open com.example.app` now records that bundle id on the session — the provider path skips local app resolution (no simctl/devicectl reaches a hosted device), and used to drop an explicitly spelled bundle id along with it, leaving the session with no app identity at all. Opening a second bundle id replaces the first, matching the local path, where an explicitly spelled target always wins over the session's current app; deep links, display names, and bare `open` still keep the app already tracked.

src/mcp/__tests__/protocol-era.test.ts

@@ -3,7 +3,9 @@ import { test } from 'vitest';
 import {
   cacheFields,
   finalizeResult,
+  LEGACY_PROTOCOL_VERSIONS,
   MODERN_PROTOCOL_VERSION,
+  MODERN_PROTOCOL_VERSIONS,
   negotiateLegacyProtocolVersion,
   PREFERRED_LEGACY_PROTOCOL_VERSION,
   resolveProtocolEra,
@@ -36,14 +38,54 @@ test('initialize falls back to the newest legacy revision for versions we do not
   assert.equal(negotiateLegacyProtocolVersion(undefined), PREFERRED_LEGACY_PROTOCOL_VERSION);
 });
 
-test('a declared protocol version selects the modern era, its absence stays legacy', () => {
+test('initialize never agrees to a modern revision, which has no handshake to establish', () => {
+  for (const version of MODERN_PROTOCOL_VERSIONS) {
+    assert.equal(
+      negotiateLegacyProtocolVersion({ protocolVersion: version }),
+      PREFERRED_LEGACY_PROTOCOL_VERSION,
+    );
+  }
+});
+
+test('the declared revision picks the era, so 2025 stays on the legacy wire contract', () => {
   assert.equal(resolveProtocolEra('tools/list', modernMeta()), 'modern');
+  for (const version of LEGACY_PROTOCOL_VERSIONS) {
+    assert.equal(resolveProtocolEra('tools/list', modernMeta(version)), 'legacy');
+  }
   assert.equal(resolveProtocolEra('tools/list', {}), 'legacy');
   assert.equal(resolveProtocolEra('tools/list', undefined), 'legacy');
 });
 
-test('server/discover is modern even without _meta, so the probe reports the real era', () => {
-  assert.equal(resolveProtocolEra('server/discover', undefined), 'modern');
+test('server/discover requires modern request metadata rather than being promoted', () => {
+  assert.equal(resolveProtocolEra('server/discover', modernMeta()), 'modern');
+  // No declared revision: malformed, not an invitation to guess the era.
+  assert.throws(() => resolveProtocolEra('server/discover', undefined), /protocolVersion/);
+  assert.throws(() => resolveProtocolEra('server/discover', { _meta: {} }), /protocolVersion/);
+  // The RPC does not exist in any legacy revision.
+  assert.throws(
+    () => resolveProtocolEra('server/discover', modernMeta(PREFERRED_LEGACY_PROTOCOL_VERSION)),
+    UnsupportedProtocolVersionError,
+  );
+});
+
+test('a declared revision without client capabilities is malformed', () => {
+  assert.throws(
+    () =>
+      resolveProtocolEra('tools/call', {
+        _meta: { 'io.modelcontextprotocol/protocolVersion': MODERN_PROTOCOL_VERSION },
+      }),
+    /clientCapabilities/,
+  );
+  assert.throws(
+    () =>
+      resolveProtocolEra('tools/call', {
+        _meta: {
+          'io.modelcontextprotocol/protocolVersion': MODERN_PROTOCOL_VERSION,
+          'io.modelcontextprotocol/clientCapabilities': 'not-an-object',
+        },
+      }),
+    /clientCapabilities/,
+  );
 });
 
 test('an unimplemented declared revision is rejected with the supported list', () => {

src/mcp/__tests__/router.test.ts

@@ -118,6 +118,73 @@ test('modern tools/list carries the cacheable-result envelope, legacy stays unch
   assert.deepEqual(Object.keys(legacy.result as object), ['tools']);
 });
 
+test('a request declaring a 2025 revision is answered on the legacy wire contract', async () => {
+  for (const version of ['2025-11-25', '2025-06-18']) {
+    const response = await handleMcpMessage({
+      jsonrpc: '2.0',
+      id: `declared-${version}`,
+      method: 'tools/list',
+      params: { _meta: { ...MODERN_META, 'io.modelcontextprotocol/protocolVersion': version } },
+    });
+
+    assert.ok(response && 'result' in response);
+    // Declaring a revision through modern framing does not opt it into the 2026 result
+    // shape: `resultType`, `serverInfo`, and the cache hints are all 2026-only fields.
+    assert.deepEqual(Object.keys(response.result as object), ['tools']);
+  }
+});
+
+test('initialize does not agree to a modern revision, which has no handshake', async () => {
+  const response = await handleMcpMessage({
+    jsonrpc: '2.0',
+    id: 'initialize-modern',
+    method: 'initialize',
+    params: {
+      protocolVersion: '2026-07-28',
+      capabilities: {},
+      clientInfo: { name: 'c', version: '1' },
+    },
+  });
+
+  assert.ok(response && 'result' in response);
+  assert.equal((response.result as { protocolVersion: string }).protocolVersion, '2025-11-25');
+});
+
+test('server/discover rejects requests missing the modern metadata it requires', async () => {
+  const noMeta = await handleMcpMessage({
+    jsonrpc: '2.0',
+    id: 'discover-no-meta',
+    method: 'server/discover',
+  });
+  assert.ok(noMeta && 'error' in noMeta);
+  assert.equal(noMeta.error.code, -32602);
+  assert.match(noMeta.error.message, /protocolVersion/);
+
+  const legacyVersion = await handleMcpMessage({
+    jsonrpc: '2.0',
+    id: 'discover-legacy',
+    method: 'server/discover',
+    params: {
+      _meta: { ...MODERN_META, 'io.modelcontextprotocol/protocolVersion': '2025-11-25' },
+    },
+  });
+  assert.ok(legacyVersion && 'error' in legacyVersion);
+  assert.equal(legacyVersion.error.code, -32022);
+});
+
+test('a declared revision without client capabilities is rejected as invalid params', async () => {
+  const response = await handleMcpMessage({
+    jsonrpc: '2.0',
+    id: 'no-capabilities',
+    method: 'tools/list',
+    params: { _meta: { 'io.modelcontextprotocol/protocolVersion': '2026-07-28' } },
+  });
+
+  assert.ok(response && 'error' in response);
+  assert.equal(response.error.code, -32602);
+  assert.match(response.error.message, /clientCapabilities/);
+});
+
 test('a protocol version this server does not implement is rejected with the supported list', async () => {
   const response = await handleMcpMessage({
     jsonrpc: '2.0',

src/mcp/protocol-era.ts

@@ -1,3 +1,4 @@
+import { AppError } from '@agent-device/kernel/errors';
 import { readVersion } from '../utils/version.ts';
 
 /**
@@ -10,40 +11,47 @@ import { readVersion } from '../utils/version.ts';
  *   and client capabilities in `_meta`, there is no handshake, and results are tagged
  *   with `resultType`.
  *
- * A request is modern exactly when it declares a protocol version in `_meta`. Legacy
- * responses stay byte-identical to what earlier releases sent, so upgrading a client is
- * the only thing that changes wire shape.
+ * Era membership follows the *declared revision*, not merely the presence of `_meta`: a
+ * revision is served on its own wire contract, so a request declaring `2025-11-25` gets
+ * the legacy result shape even though it used modern framing to say so. Legacy responses
+ * stay byte-identical to what earlier releases sent.
  */
 export type ProtocolEra = 'legacy' | 'modern';
 
-/** Newest revision we implement. Requests declaring it are served statelessly. */
+/** Newest stateless revision, and the one `server/discover` answers for. */
 export const MODERN_PROTOCOL_VERSION = '2026-07-28';
 
-/**
- * Answer for legacy clients whose requested revision we do not implement. The
- * `initialize` contract is "echo the requested version, or name one you do support".
- */
-export const PREFERRED_LEGACY_PROTOCOL_VERSION = '2025-11-25';
+/** Revisions served statelessly, newest first. */
+export const MODERN_PROTOCOL_VERSIONS: readonly string[] = [MODERN_PROTOCOL_VERSION];
 
 /**
- * Revisions we implement, newest first — the list a client may choose from.
+ * Revisions served through the `initialize` handshake, newest first.
  *
- * Scoped to what this server actually provides rather than every published revision:
- * a tools-only server's surface (`tools/list`, `tools/call`, `outputSchema`,
- * `structuredContent`) is identical across `2026-07-28`, `2025-11-25`, and `2025-06-18`.
- * Revisions before `2025-06-18` predate `outputSchema`/`structuredContent`, which every
- * typed tool here returns, so they are not claimed.
+ * Scoped to what this server actually provides rather than every published revision: a
+ * tools-only server's surface (`tools/list`, `tools/call`, `outputSchema`,
+ * `structuredContent`) is identical across these and `2026-07-28`. Revisions before
+ * `2025-06-18` predate `outputSchema`/`structuredContent`, which every typed tool here
+ * returns, so they are not claimed.
  */
+export const LEGACY_PROTOCOL_VERSIONS: readonly string[] = ['2025-11-25', '2025-06-18'];
+
+/** Answer for a handshake whose requested revision we do not serve on the legacy wire. */
+export const PREFERRED_LEGACY_PROTOCOL_VERSION = '2025-11-25';
+
+/** Every revision we implement, newest first — the list a client may choose from. */
 export const SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
-  MODERN_PROTOCOL_VERSION,
-  PREFERRED_LEGACY_PROTOCOL_VERSION,
-  '2025-06-18',
+  ...MODERN_PROTOCOL_VERSIONS,
+  ...LEGACY_PROTOCOL_VERSIONS,
 ];
 
 /** JSON-RPC error code for a declared revision this server does not implement. */
 export const UNSUPPORTED_PROTOCOL_VERSION_CODE = -32022;
 
+/** Modern-only RPC: it does not exist in any legacy revision. */
+const DISCOVER_METHOD = 'server/discover';
+
 const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
+const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities';
 const SERVER_INFO_META_KEY = 'io.modelcontextprotocol/serverInfo';
 
 const MCP_SERVER_NAME = 'agent-device';
@@ -80,29 +88,56 @@ export class UnsupportedProtocolVersionError extends Error {
 }
 
 /**
- * Classifies one request and rejects revisions we do not implement.
+ * Classifies one request, rejecting revisions we do not implement and modern framing that
+ * omits its required metadata.
  *
- * `server/discover` is a modern-only probe, so it stays modern even when a client omits
- * `_meta`: a legacy client has no reason to call it, and answering a `DiscoverResult`
- * without `resultType` would misreport this server's era.
+ * A declared revision picks the era, so `2025-*` declared through modern `_meta` is still
+ * answered on the legacy wire contract. `server/discover` exists only in the modern era,
+ * so it requires a modern revision rather than being promoted by default — leniency there
+ * would answer a `DiscoverResult` that its own schema forbids.
  */
 export function resolveProtocolEra(method: string, params: unknown): ProtocolEra {
-  const declared = declaredProtocolVersion(params);
-  if (declared !== undefined && !SUPPORTED_PROTOCOL_VERSIONS.includes(declared)) {
+  const meta = asRecord(asRecord(params)._meta);
+  const declared = stringField(meta, PROTOCOL_VERSION_META_KEY);
+
+  if (declared === undefined) {
+    if (method === DISCOVER_METHOD) {
+      throw new AppError(
+        'INVALID_ARGS',
+        `Expected _meta["${PROTOCOL_VERSION_META_KEY}"] on ${DISCOVER_METHOD}.`,
+      );
+    }
+    return 'legacy';
+  }
+
+  if (!SUPPORTED_PROTOCOL_VERSIONS.includes(declared)) {
     throw new UnsupportedProtocolVersionError(declared);
   }
-  if (declared !== undefined) return 'modern';
-  return method === 'server/discover' ? 'modern' : 'legacy';
+  // Both keys are required on a modern request; a half-declared `_meta` is malformed
+  // rather than a shape to keep working.
+  if (!isRecord(meta[CLIENT_CAPABILITIES_META_KEY])) {
+    throw new AppError(
+      'INVALID_ARGS',
+      `Expected _meta["${CLIENT_CAPABILITIES_META_KEY}"] to be an object.`,
+    );
+  }
+  if (!MODERN_PROTOCOL_VERSIONS.includes(declared)) {
+    if (method === DISCOVER_METHOD) throw new UnsupportedProtocolVersionError(declared);
+    return 'legacy';
+  }
+  return 'modern';
 }
 
 /**
- * Legacy `initialize` version negotiation: echo the client's revision when we implement
- * it, otherwise name the newest legacy revision we do. Answering with an unrequested
- * version tells a pinned client to disconnect, so the echo is the interoperable branch.
+ * Legacy `initialize` version negotiation: echo the client's revision when we serve it on
+ * this wire, otherwise name the newest legacy revision we do. Answering with an
+ * unrequested version tells a pinned client to disconnect, so the echo is the
+ * interoperable branch. Modern revisions are not echoed — they have no handshake, so
+ * agreeing to one here would promise a contract this reply cannot establish.
  */
 export function negotiateLegacyProtocolVersion(params: unknown): string {
   const requested = stringField(asRecord(params), 'protocolVersion');
-  if (requested !== undefined && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+  if (requested !== undefined && LEGACY_PROTOCOL_VERSIONS.includes(requested)) {
     return requested;
   }
   return PREFERRED_LEGACY_PROTOCOL_VERSION;
@@ -133,14 +168,12 @@ export function cacheFields(era: ProtocolEra, ttlMs: number): CacheableResultFie
   return era === 'modern' ? { ttlMs, cacheScope: 'public' } : undefined;
 }
 
-function declaredProtocolVersion(params: unknown): string | undefined {
-  const meta = asRecord(asRecord(params)._meta);
-  return stringField(meta, PROTOCOL_VERSION_META_KEY);
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
-  return value as Record<string, unknown>;
+  return isRecord(value) ? value : {};
 }
 
 function stringField(record: Record<string, unknown>, key: string): string | undefined {