From 73f3d1cf2bf57ff63e9f761ae77852805c3e65de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:11:47 +0100 Subject: [PATCH 1/3] feat(mcp)!: advertise only agent inputs in MCP tool schemas The tool list cost about 268 KB, and clients that defer or compact large tool schemas then call tools without their arguments. Tenant, run, lease, and Android device-allowlist scope become operator-owned: MCP refuses them with the operator path, and their env and config defaults still apply. Repeated property descriptions shrink, every input schema fits under 5 KB, and the server instructions tell agents to load a deferred schema first. Co-Authored-By: Claude Opus 5.5 --- .../src/flag-definitions-target.ts | 10 +++---- .../src/flag-definitions-workflow.ts | 2 +- .../command-surface-metadata.test.ts | 6 ++--- .../src/common-input-fields.ts | 27 ++++++++++--------- .../command-surface/src/management/app.ts | 2 +- .../src/post-action-observation-grammar.ts | 2 +- packages/contracts/src/client-app.ts | 8 +++--- .../command-tools-operator-inputs.test.ts | 19 ++++++++----- src/mcp/server-guide.ts | 2 +- src/mcp/tool-control-fields.ts | 9 +++---- website/docs/docs/agent-setup.md | 2 +- 11 files changed, 47 insertions(+), 42 deletions(-) diff --git a/packages/command-registry/src/flag-definitions-target.ts b/packages/command-registry/src/flag-definitions-target.ts index ac309721e4..474fd358ff 100644 --- a/packages/command-registry/src/flag-definitions-target.ts +++ b/packages/command-registry/src/flag-definitions-target.ts @@ -60,7 +60,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend', inputDescription: - 'OS version or range for the device a proxy backend leases, for example 18.6.2 or ">=26" (Android: API level), sent as given. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: OS version or range, for example 18.6.2 or ">=26" (Android: API level). Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -72,7 +72,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: Android system image tag the backend picks the device by; refused without such a backend', inputDescription: - 'Android system image tag for the device a proxy backend leases, for example google_apis_playstore, sent as given. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: Android system image tag, for example google_apis_playstore. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -84,7 +84,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend', inputDescription: - 'iOS simulator mode for the device a proxy backend leases, slim or full, sent as given; the backend validates it. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: iOS simulator mode, slim or full. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -96,7 +96,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend', inputDescription: - 'Name of a saved, prepared device state (baseline) that a proxy backend restores on the device it leases, sent as given; the backend validates it. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. A new lease that does not report this baseline in lease.device.baseline is released and fails with reason device-spec-unsupported. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: saved device state (baseline) to restore on the leased device. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -108,7 +108,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend', inputDescription: - 'Ask a proxy backend to lease a physical device instead of a simulator or emulator. false names nothing; a non-boolean fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends true to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: a physical device instead of a simulator or emulator. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, diff --git a/packages/command-registry/src/flag-definitions-workflow.ts b/packages/command-registry/src/flag-definitions-workflow.ts index d1e82d5b67..6a9e294b4f 100644 --- a/packages/command-registry/src/flag-definitions-workflow.ts +++ b/packages/command-registry/src/flag-definitions-workflow.ts @@ -99,7 +99,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Open: wait up to n ms for a device another session is holding before failing with DEVICE_IN_USE', inputDescription: - "Block this open for up to n milliseconds (100-120000) while another session holds the device, then fail with DEVICE_IN_USE naming that session. Only session contention is waited for: a device claim held by another workspace is refused at once with its recovery command. A device that never frees, or is taken again while this open waits, costs the full budget, which extends this command's timeout envelope rather than eating into it.", + "Wait up to n milliseconds while another session holds the device, then fail with DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this command's timeout.", projectConfig: false, recorded: false, }, diff --git a/packages/command-surface/src/__tests__/command-surface-metadata.test.ts b/packages/command-surface/src/__tests__/command-surface-metadata.test.ts index bde58cad35..31e74b7f10 100644 --- a/packages/command-surface/src/__tests__/command-surface-metadata.test.ts +++ b/packages/command-surface/src/__tests__/command-surface-metadata.test.ts @@ -239,9 +239,9 @@ test('command family facets keep daemon writers as an explicit projection subset // fails instead of shipping a cross-surface mismatch. test('every emitted input schema carries the aligned device-selector descriptions', () => { const expected: Record = { - device: 'Device name selector (a UDID belongs in udid, a serial in serial).', - udid: 'Apple device or simulator UDID; the selector that pins one device when several share a name.', - serial: 'Android, HarmonyOS, or Vega VVD serial selector.', + device: 'Device name; ids go in udid or serial.', + udid: 'Apple device or simulator UDID.', + serial: 'Android, HarmonyOS, or Vega VVD serial.', }; let pinned = 0; for (const metadata of listCommandMetadata()) { diff --git a/packages/command-surface/src/common-input-fields.ts b/packages/command-surface/src/common-input-fields.ts index 14df32456c..9159585dc7 100644 --- a/packages/command-surface/src/common-input-fields.ts +++ b/packages/command-surface/src/common-input-fields.ts @@ -83,11 +83,12 @@ type CommonInputFieldSpec = { /** * The common operator shape: the value comes from the key's own environment - * variable or its `~/.agent-device/config.json` entry. It covers both kinds of + * variable or its `~/.agent-device/config.json` entry. It covers every kind of * operator-owned common key — the credential and the endpoint it is sent to * (a model-writable `daemonBaseUrl` would redirect the env-resolved - * `daemonAuthToken` to an arbitrary server), and the build and device-set paths, - * which select operator infrastructure rather than per-call work. + * `daemonAuthToken` to an arbitrary server), the build and device-set paths, + * which select operator infrastructure rather than per-call work, and the + * tenant, run, lease, and device-allowlist scope the connection is admitted under. */ const ENV_OR_OPERATOR_CONFIG = operatorAudience({ operatorConfig: true }); @@ -96,7 +97,7 @@ const RETIRED_READINESS_TIMEOUT_MESSAGE = const COMMON_INPUT_FIELDS = { session: { - schema: { type: 'string', description: 'Agent-device session name.' }, + schema: { type: 'string', description: 'Session name.' }, read: (record) => optionalString(record, 'session'), flagKey: 'session', flagIn: ['input'], @@ -105,7 +106,7 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: PLATFORM_SELECTORS, - description: 'Platform selector used to resolve a device.', + description: 'Device platform.', }, read: (record) => optionalEnum(record, 'platform', PLATFORM_SELECTORS), flagKey: 'platform', @@ -115,7 +116,7 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: DEVICE_TARGETS, - description: 'Device target form. Maps to the CLI --target flag.', + description: 'Device form factor (CLI --target).', }, read: readDeviceTarget, clientKey: 'target', @@ -127,14 +128,13 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: DEVICE_TARGETS, - description: - 'Alias for deviceTarget. Commands that take a UI target (ref, selector, or x/y) accept only deviceTarget.', + description: 'Alias for deviceTarget.', }, }, device: { schema: { type: 'string', - description: 'Device name selector (a UDID belongs in udid, a serial in serial).', + description: 'Device name; ids go in udid or serial.', }, read: (record) => optionalString(record, 'device'), flagKey: 'device', @@ -143,8 +143,7 @@ const COMMON_INPUT_FIELDS = { udid: { schema: { type: 'string', - description: - 'Apple device or simulator UDID; the selector that pins one device when several share a name.', + description: 'Apple device or simulator UDID.', }, read: (record) => optionalString(record, 'udid'), flagKey: 'udid', @@ -153,7 +152,7 @@ const COMMON_INPUT_FIELDS = { serial: { schema: { type: 'string', - description: 'Android, HarmonyOS, or Vega VVD serial selector.', + description: 'Android, HarmonyOS, or Vega VVD serial.', }, read: (record) => optionalString(record, 'serial'), flagKey: 'serial', @@ -206,6 +205,7 @@ const COMMON_INPUT_FIELDS = { description: 'Android serial allowlist used for device resolution.', }, read: (record) => optionalString(record, 'androidDeviceAllowlist'), + audience: ENV_OR_OPERATOR_CONFIG, flagKey: 'androidDeviceAllowlist', flagIn: ['input', 'selection'], }, @@ -241,14 +241,17 @@ const COMMON_INPUT_FIELDS = { tenant: { schema: { type: 'string', description: 'Remote tenant identifier.' }, read: (record) => optionalString(record, 'tenant'), + audience: ENV_OR_OPERATOR_CONFIG, }, runId: { schema: { type: 'string', description: 'Lease run identifier.' }, read: (record) => optionalString(record, 'runId'), + audience: ENV_OR_OPERATOR_CONFIG, }, leaseId: { schema: { type: 'string', description: 'Existing lease identifier.' }, read: (record) => optionalString(record, 'leaseId'), + audience: ENV_OR_OPERATOR_CONFIG, }, cwd: { schema: { type: 'string', description: 'Working directory for command execution.' }, diff --git a/packages/command-surface/src/management/app.ts b/packages/command-surface/src/management/app.ts index 4cf1ed22e2..90ac292b1f 100644 --- a/packages/command-surface/src/management/app.ts +++ b/packages/command-surface/src/management/app.ts @@ -77,7 +77,7 @@ const openCommandMetadata = defineFieldCommandMetadata( noRecord: booleanField('Do not record this action.'), metroHost: stringField('Session-scoped Metro/debug host hint applied to the opened app.'), metroPort: integerField( - 'Session-scoped Metro/debug port hint applied to the opened app. On an emulator/simulator the host defaults to the loopback alias (Android 10.0.2.2, iOS 127.0.0.1) when --metro-host is omitted; physical devices still require an explicit --metro-host.', + 'Session-scoped Metro/debug port hint applied to the opened app. Without metroHost, emulators and simulators use the loopback alias; physical devices need metroHost.', { min: 1, max: 65535, diff --git a/packages/command-surface/src/post-action-observation-grammar.ts b/packages/command-surface/src/post-action-observation-grammar.ts index 892cabed07..0b71b9f453 100644 --- a/packages/command-surface/src/post-action-observation-grammar.ts +++ b/packages/command-surface/src/post-action-observation-grammar.ts @@ -34,7 +34,7 @@ const settleFields = () => ({ 'After the action, wait for the UI to go quiet and return the settled diff vs the pre-action tree in the same response. Best-effort; never fails the action.', ), settleQuietMs: integerField( - 'Settle: quiet window in milliseconds (default 500; 300 when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the timeoutMs settle deadline; a replacement from a screen the pre-action capture read as presenting nothing, such as a tab switch, gets no 1500ms confirmation and keeps the asked window.', + 'Settle: quiet window in milliseconds (default 500). On iOS, a broad screen replacement is confirmed for at least 1500ms within the timeoutMs deadline.', { min: 0 }, ), timeoutMs: integerField('Settle: wait deadline in milliseconds (default 10000).', { min: 1 }), diff --git a/packages/contracts/src/client-app.ts b/packages/contracts/src/client-app.ts index 61add7127e..4bf7dd6bdb 100644 --- a/packages/contracts/src/client-app.ts +++ b/packages/contracts/src/client-app.ts @@ -79,11 +79,9 @@ export type AppOpenOptions = AgentDeviceRequestOverrides & /** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */ timeoutMs?: number; /** - * Block this open for up to n milliseconds (100-120000) while another session holds the device, - * then fail with DEVICE_IN_USE naming that session. Only session contention is waited for: a - * device claim held by another workspace is refused at once with its recovery command. A device - * that never frees, or is taken again while this open waits, costs the full budget, which - * extends this command's timeout envelope rather than eating into it. + * Wait up to n milliseconds while another session holds the device, then fail with + * DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this + * command's timeout. */ waitMs?: number; // Editor documentation for a public type: a `.d.ts` is read where no diff --git a/src/mcp/__tests__/command-tools-operator-inputs.test.ts b/src/mcp/__tests__/command-tools-operator-inputs.test.ts index 3dae1b2263..583ab90469 100644 --- a/src/mcp/__tests__/command-tools-operator-inputs.test.ts +++ b/src/mcp/__tests__/command-tools-operator-inputs.test.ts @@ -9,8 +9,9 @@ import { createCommandToolExecutor, listCommandTools } from '../command-tools.ts // Operator-owned inputs are never model-writable: the model reads untrusted // app UI text and picks tool arguments, so no tool schema may offer a -// parameter to write a credential, the endpoint it is sent to, or an -// operator infrastructure path into (exfiltration/redirect path). The keys +// parameter to write a credential, the endpoint it is sent to, an +// operator infrastructure path, or the tenant/lease scope a connection is +// admitted under (exfiltration/redirect path). The keys // are refused as explicit input too — fail closed with env guidance, the // same posture as retired fields — while operator env/config defaults keep // flowing outside the model-writable surface. @@ -25,6 +26,10 @@ const OPERATOR_OWNED_KEYS = [ 'iosXctestrunFile', 'iosXctestDerivedDataPath', 'iosXctestEnvDir', + 'androidDeviceAllowlist', + 'tenant', + 'runId', + 'leaseId', ] as const; // The rest of the shared common input: keys a model may write, because they @@ -37,10 +42,6 @@ const MODEL_WRITABLE_COMMON_KEYS = [ 'device', 'udid', 'serial', - 'androidDeviceAllowlist', - 'tenant', - 'runId', - 'leaseId', 'debug', ] as const; @@ -215,6 +216,9 @@ test('MCP refuses any argument the advertised schema does not list', async () => test('MCP still resolves operator env values outside the model-writable surface', async () => { vi.stubEnv('AGENT_DEVICE_DAEMON_AUTH_TOKEN', 'operator-env-token'); vi.stubEnv('AGENT_DEVICE_STATE_DIR', '/operator/state-dir'); + vi.stubEnv('AGENT_DEVICE_TENANT', 'operator-tenant'); + vi.stubEnv('AGENT_DEVICE_LEASE_ID', 'operator-lease'); + vi.stubEnv('AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST', 'emulator-5554'); const createdConfigs: Array> = []; const calls: Array<{ name: string; input: Record }> = []; const executor = createCommandToolExecutor({ @@ -232,6 +236,9 @@ test('MCP still resolves operator env values outside the model-writable surface' assert.equal(result.isError, false); assert.equal(calls[0]?.input.daemonAuthToken, 'operator-env-token'); + assert.equal(calls[0]?.input.tenant, 'operator-tenant'); + assert.equal(calls[0]?.input.leaseId, 'operator-lease'); + assert.equal(calls[0]?.input.androidDeviceAllowlist, 'emulator-5554'); assert.equal(createdConfigs[0]?.stateDir, '/operator/state-dir'); }); diff --git a/src/mcp/server-guide.ts b/src/mcp/server-guide.ts index 4f52e3ce13..ae509802cc 100644 --- a/src/mcp/server-guide.ts +++ b/src/mcp/server-guide.ts @@ -15,7 +15,7 @@ import type { ToolResult } from './command-tools.ts'; * `open`, act → settled diff → verify → `close`, ref fidelity, sparse-AX recovery, follow * error hints. Everything situational lives behind the `help` tool. */ -export const MCP_SERVER_INSTRUCTIONS = `agent-device drives iOS, Android, tvOS, Android TV, macOS, Linux, and web apps. Tools mirror CLI commands of the same name; CLI flags are camelCase properties (--settle -> settle: true). +export const MCP_SERVER_INSTRUCTIONS = `agent-device drives iOS, Android, tvOS, Android TV, macOS, Linux, and web apps. Tools mirror CLI commands of the same name; CLI flags are camelCase properties (--settle -> settle: true). If your client defers tool schemas, load a tool's schema before its first call. Start: known app -> call open {app, foreground: true} at once; do not probe with devices, apps, appstate, snapshot, or screenshot first. open returns the initial interactive snapshot with @refs. Unknown app id: devices, then apps, then open the discovered id; never invent ids. Existing session: continue from its state, do not reopen. diff --git a/src/mcp/tool-control-fields.ts b/src/mcp/tool-control-fields.ts index 768ffec2b3..fad6c6dfc9 100644 --- a/src/mcp/tool-control-fields.ts +++ b/src/mcp/tool-control-fields.ts @@ -32,23 +32,20 @@ const MCP_TOOL_CONFIG_FIELDS = { schema: { type: 'string', enum: ['optimized', 'json'], - description: - 'MCP text content format. Defaults to optimized agent-friendly text; use json for JSON text and structured content from every tool.', + description: 'Text format (default optimized); json adds structuredContent.', }, }, includeCost: { schema: { type: 'boolean', - description: - 'Include per-command agent-cost (cost.wallClockMs, …) in structuredContent. Defaults to off; the default response shape is unchanged.', + description: 'Add agent cost (cost.wallClockMs, …) to structuredContent.', }, }, responseLevel: { schema: { type: 'string', enum: ['digest', 'default', 'full'], - description: - 'Response verbosity: token-cheap digest / default (today) / full. Defaults to default; the default response shape is unchanged.', + description: 'Response verbosity (default: default).', }, }, } as const satisfies Record; diff --git a/website/docs/docs/agent-setup.md b/website/docs/docs/agent-setup.md index 89562d8218..ea9dee350f 100644 --- a/website/docs/docs/agent-setup.md +++ b/website/docs/docs/agent-setup.md @@ -53,7 +53,7 @@ Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` r `agent-device mcp` starts the stdio MCP server. It exposes installed CLI commands as structured tools. Some local workflows are CLI-only and have no MCP tool. -`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, such as its state directory, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. +`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, such as its state directory or its remote tenant, run, and lease ids, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. For web automation, MCP tools can target `platform: "web"` once the managed browser backend is set up, but `agent-device web setup` and `agent-device web doctor` are CLI-only. Run setup from a terminal that uses the same state directory as the MCP server before you ask an MCP client to drive a browser session. From 8711bed0ae0e07f877849834d5274395ce5b3d28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:11:47 +0100 Subject: [PATCH 2/3] chore(gates): cap MCP input schemas at 5 KB and keep operator keys out Derives both checks from listCommandTools() and the declared audiences, so a new oversized schema or an advertised operator-owned key fails. Co-Authored-By: Claude Opus 5.5 --- .../command-tools-schema-budget.test.ts | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 src/mcp/__tests__/command-tools-schema-budget.test.ts diff --git a/src/mcp/__tests__/command-tools-schema-budget.test.ts b/src/mcp/__tests__/command-tools-schema-budget.test.ts new file mode 100644 index 0000000000..4646afa000 --- /dev/null +++ b/src/mcp/__tests__/command-tools-schema-budget.test.ts @@ -0,0 +1,38 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import { COMMON_INPUT_AUDIENCE, listCommandMetadata } from '@agent-device/command-surface'; +import { listCommandTools } from '../command-tools.ts'; +import { MCP_TOOL_CONFIG_AUDIENCE } from '../tool-control-fields.ts'; + +// Clients that compact large tool schemas drop descriptions and nested structure above about +// 5 KB, and clients that defer tool schemas append the full schema to every error result. +const INPUT_SCHEMA_BUDGET_BYTES = 5 * 1024; + +test('every MCP tool input schema stays within the byte budget', () => { + const oversized = listCommandTools() + .map((tool) => ({ + name: tool.name, + bytes: Buffer.byteLength(JSON.stringify(tool.inputSchema)), + })) + .filter((tool) => tool.bytes > INPUT_SCHEMA_BUDGET_BYTES); + assert.deepEqual(oversized, []); +}); + +test('no MCP tool advertises an operator-owned input', () => { + const audiences = [ + COMMON_INPUT_AUDIENCE, + MCP_TOOL_CONFIG_AUDIENCE, + ...listCommandMetadata().map((metadata) => metadata.inputAudience), + ]; + const operatorKeys = new Set( + audiences.flatMap((audience) => + Object.entries(audience).flatMap(([key, entry]) => (entry.kind === 'operator' ? [key] : [])), + ), + ); + assert.ok(operatorKeys.has('tenant'), 'expected tenant to be operator-owned'); + for (const tool of listCommandTools()) { + const properties = tool.inputSchema.properties ?? {}; + const advertised = [...operatorKeys].filter((key) => Object.hasOwn(properties, key)); + assert.deepEqual(advertised, [], `${tool.name} advertises operator-owned inputs`); + } +}); From 5d4ac57c10120615c08e160deed4e694a3bdbd75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:19:12 +0100 Subject: [PATCH 3/3] fix(mcp): keep trimmed schema descriptions accurate Restores the facts the shortened descriptions dropped: the result-size effect of the MCP output controls, the waitMs range, the snapshot-bridge settle default and its non-empty-screen floor, and what physical: false selects. The config-loader audience moves beside the other MCP audiences so the schema gate reads the same declarations as admission. Co-Authored-By: Claude Opus 5.5 --- .../src/flag-definitions-target.ts | 2 +- .../src/flag-definitions-workflow.ts | 2 +- .../src/common-input-fields.ts | 2 +- .../src/post-action-observation-grammar.ts | 2 +- packages/contracts/src/client-app.ts | 4 +-- .../command-tools-operator-inputs.test.ts | 2 ++ .../command-tools-schema-budget.test.ts | 7 ++++-- src/mcp/command-tools.ts | 20 +-------------- src/mcp/tool-control-fields.ts | 25 ++++++++++++++++--- website/docs/docs/agent-setup.md | 2 +- 10 files changed, 37 insertions(+), 31 deletions(-) diff --git a/packages/command-registry/src/flag-definitions-target.ts b/packages/command-registry/src/flag-definitions-target.ts index 474fd358ff..0f774ed963 100644 --- a/packages/command-registry/src/flag-definitions-target.ts +++ b/packages/command-registry/src/flag-definitions-target.ts @@ -108,7 +108,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend', inputDescription: - 'Proxy lease: a physical device instead of a simulator or emulator. Honored only by a proxy backend that leases by spec; other daemons refuse it.', + 'Proxy lease: true requests a physical device; false selects nothing. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, diff --git a/packages/command-registry/src/flag-definitions-workflow.ts b/packages/command-registry/src/flag-definitions-workflow.ts index 6a9e294b4f..a3ce7f70cd 100644 --- a/packages/command-registry/src/flag-definitions-workflow.ts +++ b/packages/command-registry/src/flag-definitions-workflow.ts @@ -99,7 +99,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Open: wait up to n ms for a device another session is holding before failing with DEVICE_IN_USE', inputDescription: - "Wait up to n milliseconds while another session holds the device, then fail with DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this command's timeout.", + "Wait up to n milliseconds (100-120000) while another session holds the device, then fail with DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this command's timeout.", projectConfig: false, recorded: false, }, diff --git a/packages/command-surface/src/common-input-fields.ts b/packages/command-surface/src/common-input-fields.ts index 9159585dc7..1939b6011f 100644 --- a/packages/command-surface/src/common-input-fields.ts +++ b/packages/command-surface/src/common-input-fields.ts @@ -116,7 +116,7 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: DEVICE_TARGETS, - description: 'Device form factor (CLI --target).', + description: 'Device form factor.', }, read: readDeviceTarget, clientKey: 'target', diff --git a/packages/command-surface/src/post-action-observation-grammar.ts b/packages/command-surface/src/post-action-observation-grammar.ts index 0b71b9f453..9c0e4e0062 100644 --- a/packages/command-surface/src/post-action-observation-grammar.ts +++ b/packages/command-surface/src/post-action-observation-grammar.ts @@ -34,7 +34,7 @@ const settleFields = () => ({ 'After the action, wait for the UI to go quiet and return the settled diff vs the pre-action tree in the same response. Best-effort; never fails the action.', ), settleQuietMs: integerField( - 'Settle: quiet window in milliseconds (default 500). On iOS, a broad screen replacement is confirmed for at least 1500ms within the timeoutMs deadline.', + 'Settle: quiet window in milliseconds (default 500; 300 on the iOS simulator snapshot bridge). On iOS, a broad replacement of a non-empty screen holds at least 1500ms within timeoutMs.', { min: 0 }, ), timeoutMs: integerField('Settle: wait deadline in milliseconds (default 10000).', { min: 1 }), diff --git a/packages/contracts/src/client-app.ts b/packages/contracts/src/client-app.ts index 4bf7dd6bdb..a462387ed7 100644 --- a/packages/contracts/src/client-app.ts +++ b/packages/contracts/src/client-app.ts @@ -79,8 +79,8 @@ export type AppOpenOptions = AgentDeviceRequestOverrides & /** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */ timeoutMs?: number; /** - * Wait up to n milliseconds while another session holds the device, then fail with - * DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this + * Wait up to n milliseconds (100-120000) while another session holds the device, then fail + * with DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this * command's timeout. */ waitMs?: number; diff --git a/src/mcp/__tests__/command-tools-operator-inputs.test.ts b/src/mcp/__tests__/command-tools-operator-inputs.test.ts index 583ab90469..351fd32fa4 100644 --- a/src/mcp/__tests__/command-tools-operator-inputs.test.ts +++ b/src/mcp/__tests__/command-tools-operator-inputs.test.ts @@ -217,6 +217,7 @@ test('MCP still resolves operator env values outside the model-writable surface' vi.stubEnv('AGENT_DEVICE_DAEMON_AUTH_TOKEN', 'operator-env-token'); vi.stubEnv('AGENT_DEVICE_STATE_DIR', '/operator/state-dir'); vi.stubEnv('AGENT_DEVICE_TENANT', 'operator-tenant'); + vi.stubEnv('AGENT_DEVICE_RUN_ID', 'operator-run'); vi.stubEnv('AGENT_DEVICE_LEASE_ID', 'operator-lease'); vi.stubEnv('AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST', 'emulator-5554'); const createdConfigs: Array> = []; @@ -237,6 +238,7 @@ test('MCP still resolves operator env values outside the model-writable surface' assert.equal(result.isError, false); assert.equal(calls[0]?.input.daemonAuthToken, 'operator-env-token'); assert.equal(calls[0]?.input.tenant, 'operator-tenant'); + assert.equal(calls[0]?.input.runId, 'operator-run'); assert.equal(calls[0]?.input.leaseId, 'operator-lease'); assert.equal(calls[0]?.input.androidDeviceAllowlist, 'emulator-5554'); assert.equal(createdConfigs[0]?.stateDir, '/operator/state-dir'); diff --git a/src/mcp/__tests__/command-tools-schema-budget.test.ts b/src/mcp/__tests__/command-tools-schema-budget.test.ts index 4646afa000..0b50e4bdf9 100644 --- a/src/mcp/__tests__/command-tools-schema-budget.test.ts +++ b/src/mcp/__tests__/command-tools-schema-budget.test.ts @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import { COMMON_INPUT_AUDIENCE, listCommandMetadata } from '@agent-device/command-surface'; import { listCommandTools } from '../command-tools.ts'; -import { MCP_TOOL_CONFIG_AUDIENCE } from '../tool-control-fields.ts'; +import { CONFIG_LOADER_AUDIENCE, MCP_TOOL_CONFIG_AUDIENCE } from '../tool-control-fields.ts'; // Clients that compact large tool schemas drop descriptions and nested structure above about // 5 KB, and clients that defer tool schemas append the full schema to every error result. @@ -22,6 +22,7 @@ test('no MCP tool advertises an operator-owned input', () => { const audiences = [ COMMON_INPUT_AUDIENCE, MCP_TOOL_CONFIG_AUDIENCE, + CONFIG_LOADER_AUDIENCE, ...listCommandMetadata().map((metadata) => metadata.inputAudience), ]; const operatorKeys = new Set( @@ -29,7 +30,9 @@ test('no MCP tool advertises an operator-owned input', () => { Object.entries(audience).flatMap(([key, entry]) => (entry.kind === 'operator' ? [key] : [])), ), ); - assert.ok(operatorKeys.has('tenant'), 'expected tenant to be operator-owned'); + for (const key of ['tenant', 'config', 'remoteConfig']) { + assert.ok(operatorKeys.has(key), `expected ${key} to be operator-owned`); + } for (const tool of listCommandTools()) { const properties = tool.inputSchema.properties ?? {}; const advertised = [...operatorKeys].filter((key) => Object.hasOwn(properties, key)); diff --git a/src/mcp/command-tools.ts b/src/mcp/command-tools.ts index d8fded948b..755d23ba99 100644 --- a/src/mcp/command-tools.ts +++ b/src/mcp/command-tools.ts @@ -6,7 +6,6 @@ import { isCommandName, listCommandMetadata, listMcpCommandMetadata, - operatorAudience, operatorInputRefusal, type AgentDeviceClient, type BindingSettings, @@ -32,6 +31,7 @@ import { } from '@agent-device/command-registry/registry'; import { MCP_COMMAND_OUTPUT_SCHEMAS } from './mcp-output-schemas.ts'; import { + CONFIG_LOADER_AUDIENCE, MCP_TOOL_CONFIG_AUDIENCE, MCP_TOOL_CONFIG_KEYS, mcpToolConfigProperties, @@ -82,24 +82,6 @@ type McpToolConfig = { outputFormat: McpOutputFormat; }; -/** - * Config-file-loading keys. Not per-command flags but flags the MCP config - * resolver reads to load an arbitrary file; never model-writable, since that - * file can carry operator credentials and endpoints. They appear in no tool - * schema, so admission rejects them like any unadvertised key — with a message - * that points at the operator path instead of the generic unknown-key text. - */ -const CONFIG_LOADER_AUDIENCE: InputAudienceMap = { - config: operatorAudience({ - operatorPath: - 'Point the process serving these tools at a config file with the AGENT_DEVICE_CONFIG environment variable.', - }), - remoteConfig: operatorAudience({ - operatorPath: - 'Configure the remote profile on the process serving these tools, not per tool call.', - }), -}; - /** * Every `operator` key any command declares. The deny side is deliberately * global rather than per-command: a screen that steers the model into writing a diff --git a/src/mcp/tool-control-fields.ts b/src/mcp/tool-control-fields.ts index fad6c6dfc9..08dd87d9e8 100644 --- a/src/mcp/tool-control-fields.ts +++ b/src/mcp/tool-control-fields.ts @@ -32,20 +32,21 @@ const MCP_TOOL_CONFIG_FIELDS = { schema: { type: 'string', enum: ['optimized', 'json'], - description: 'Text format (default optimized); json adds structuredContent.', + description: 'Result text: compact optimized (default) or the full result as JSON (larger).', }, }, includeCost: { schema: { type: 'boolean', - description: 'Add agent cost (cost.wallClockMs, …) to structuredContent.', + description: 'Add agent cost (cost.wallClockMs, …) to the result.', }, }, responseLevel: { schema: { type: 'string', enum: ['digest', 'default', 'full'], - description: 'Response verbosity (default: default).', + description: + 'Result detail: digest (smallest) or full (largest), as JSON; default is compact text.', }, }, } as const satisfies Record; @@ -58,6 +59,24 @@ export const MCP_TOOL_CONFIG_KEYS: ReadonlySet = new Set( MCP_TOOL_CONFIG_ROWS.map(([key]) => key), ); +/** + * Config-file-loading keys. Not per-command flags but flags the MCP config + * resolver reads to load an arbitrary file; never model-writable, since that + * file can carry operator credentials and endpoints. They appear in no tool + * schema, so admission rejects them like any unadvertised key — with a message + * that points at the operator path instead of the generic unknown-key text. + */ +export const CONFIG_LOADER_AUDIENCE: InputAudienceMap = { + config: operatorAudience({ + operatorPath: + 'Point the process serving these tools at a config file with the AGENT_DEVICE_CONFIG environment variable.', + }), + remoteConfig: operatorAudience({ + operatorPath: + 'Configure the remote profile on the process serving these tools, not per tool call.', + }), +}; + export const MCP_TOOL_CONFIG_AUDIENCE: InputAudienceMap = Object.fromEntries( MCP_TOOL_CONFIG_ROWS.flatMap(([key, field]) => (field.audience ? [[key, field.audience]] : [])), ); diff --git a/website/docs/docs/agent-setup.md b/website/docs/docs/agent-setup.md index ea9dee350f..f519409b98 100644 --- a/website/docs/docs/agent-setup.md +++ b/website/docs/docs/agent-setup.md @@ -53,7 +53,7 @@ Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` r `agent-device mcp` starts the stdio MCP server. It exposes installed CLI commands as structured tools. Some local workflows are CLI-only and have no MCP tool. -`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, such as its state directory or its remote tenant, run, and lease ids, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. +`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. For example, set the state directory with `AGENT_DEVICE_STATE_DIR`, and the remote `tenant`, `runId`, and `leaseId` with `AGENT_DEVICE_TENANT`, `AGENT_DEVICE_RUN_ID`, and `AGENT_DEVICE_LEASE_ID` (or the same keys in `~/.agent-device/config.json`). Tool calls cannot pass these values. For web automation, MCP tools can target `platform: "web"` once the managed browser backend is set up, but `agent-device web setup` and `agent-device web doctor` are CLI-only. Run setup from a terminal that uses the same state directory as the MCP server before you ask an MCP client to drive a browser session.