Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions packages/command-registry/src/flag-definitions-target.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
Expand All @@ -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,
},
Expand All @@ -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,
},
Expand All @@ -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,
},
Expand All @@ -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: 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,
},
Expand Down
2 changes: 1 addition & 1 deletion packages/command-registry/src/flag-definitions-workflow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 (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,
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string> = {
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()) {
Expand Down
27 changes: 15 additions & 12 deletions packages/command-surface/src/common-input-fields.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 });

Expand All @@ -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'],
Expand All @@ -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',
Expand All @@ -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.',
},
read: readDeviceTarget,
clientKey: 'target',
Expand All @@ -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',
Expand All @@ -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',
Expand All @@ -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',
Expand Down Expand Up @@ -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'],
},
Expand Down Expand Up @@ -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.' },
Expand Down
2 changes: 1 addition & 1 deletion packages/command-surface/src/management/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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; 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 }),
Expand Down
8 changes: 3 additions & 5 deletions packages/contracts/src/client-app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 (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;
// Editor documentation for a public type: a `.d.ts` is read where no
Expand Down
21 changes: 15 additions & 6 deletions src/mcp/__tests__/command-tools-operator-inputs.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -25,6 +26,10 @@ const OPERATOR_OWNED_KEYS = [
'iosXctestrunFile',
'iosXctestDerivedDataPath',
'iosXctestEnvDir',
'androidDeviceAllowlist',
'tenant',
'runId',
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
'leaseId',
] as const;

// The rest of the shared common input: keys a model may write, because they
Expand All @@ -37,10 +42,6 @@ const MODEL_WRITABLE_COMMON_KEYS = [
'device',
'udid',
'serial',
'androidDeviceAllowlist',
'tenant',
'runId',
'leaseId',
'debug',
] as const;

Expand Down Expand Up @@ -215,6 +216,10 @@ 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_RUN_ID', 'operator-run');
vi.stubEnv('AGENT_DEVICE_LEASE_ID', 'operator-lease');
vi.stubEnv('AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST', 'emulator-5554');
const createdConfigs: Array<Record<string, unknown>> = [];
const calls: Array<{ name: string; input: Record<string, unknown> }> = [];
const executor = createCommandToolExecutor({
Expand All @@ -232,6 +237,10 @@ 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');
});

Expand Down
41 changes: 41 additions & 0 deletions src/mcp/__tests__/command-tools-schema-budget.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
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 { 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.
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,
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
MCP_TOOL_CONFIG_AUDIENCE,
CONFIG_LOADER_AUDIENCE,
...listCommandMetadata().map((metadata) => metadata.inputAudience),
];
const operatorKeys = new Set(
audiences.flatMap((audience) =>
Object.entries(audience).flatMap(([key, entry]) => (entry.kind === 'operator' ? [key] : [])),
),
);
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));
assert.deepEqual(advertised, [], `${tool.name} advertises operator-owned inputs`);
}
});
20 changes: 1 addition & 19 deletions src/mcp/command-tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ import {
isCommandName,
listCommandMetadata,
listMcpCommandMetadata,
operatorAudience,
operatorInputRefusal,
type AgentDeviceClient,
type BindingSettings,
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/mcp/server-guide.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading
Loading