Skip to content

Commit 6fa9000

Browse files
committed
fix(#2682): let the dispatcher decide where a warning lands
`getCliOutput` appended the activation warning only when `format` was neither `text` nor `attrs`, and `get`'s format is a required two-value field on every surface — so that branch was unreachable, its test passed against an `input: {}` no caller can build, and a successful `get text` after a repair printed the value alone. Four per-formatter wrappers and a settle wrapper said the same thing in four other ways, which is how one rule ended up with four exceptions. `formatCliOutput` now renders warnings once for every command, and the only opt-out is a declared `parseableOutput` trait on the command's descriptor: `get`, `find`, `clipboard` and `record` print their stdout value verbatim and warn on stderr, so `value=$(agent-device get text …)` still captures exactly the value. Formatters lost their carve-outs, the settle wrapper kept only its diff, and the generic path that `type`, `focus`, `swipe` and `gesture` answer through routes the same way — those four had no formatter and printed nothing at all. `cli-output.test.ts` pins the set and asserts the rule against every formatter's real payload shape; MCP merges the stderr half back in, because a model has one stream to read.
1 parent 00fe2cf commit 6fa9000

21 files changed

Lines changed: 545 additions & 215 deletions

‎src/cli/commands/__tests__/generic.test.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,35 @@ test('replay human output keeps the composable warnings channel (#2560)', async
9191
// The skipped optional step must be visible to the human reader, not only --json.
9292
assert.match(out, /Warning: Optional Maestro tapOn skipped at flow\.yaml:line 12/);
9393
});
94+
95+
/**
96+
* #2682: `type` has no formatter, and its target tree may have been captured after the runner
97+
* re-activated the session app. A command that answers through the generic path owes the same
98+
* disclosure as one with a formatter — otherwise the interaction that paid for the repair is the one
99+
* command that stays silent.
100+
*/
101+
test('the generic CLI path prints the response warnings', async () => {
102+
const warning =
103+
'The session app was not foreground when this command arrived (prior state runningBackground), ' +
104+
'so the runner activated it before answering (reason stale_target).';
105+
const client = createAgentDeviceClient(
106+
{ session: 'qa' },
107+
{
108+
transport: async (req): Promise<DaemonResponse> => {
109+
assert.equal(req.command, 'type');
110+
return { ok: true, data: { message: 'Typed "hi"', warnings: [warning] } };
111+
},
112+
},
113+
);
114+
115+
const out = await captureStdout(() =>
116+
runGenericClientBackedCommand({
117+
command: 'type' as ClientBackedCliCommandName,
118+
positionals: ['hi'],
119+
flags: {} as CliFlags,
120+
client,
121+
}),
122+
);
123+
124+
assert.equal(out, `Typed "hi"\nWarning: ${warning}\n`);
125+
});

‎src/cli/commands/generic.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import type { CommandRequestResult } from '../../agent-device-client.ts';
22
import { runCliCommandWithOutput } from '../../commands/cli-runner.ts';
3+
import { isParseableOutputCommand } from '../../commands/cli-output.ts';
4+
import { routeResponseWarnings } from '../../commands/output-common.ts';
35
import type { CommandName } from '../../commands/command-metadata.ts';
46
import type { CliOutput } from '../../commands/command-contract.ts';
57
import type { ReplaySuiteResult } from '@agent-device/contracts/replay';
@@ -68,8 +70,15 @@ async function writeGenericCliOutput(
6870
}),
6971
);
7072
}
71-
await writeCommandOutput(flags, data, () =>
72-
readCommandMessage(data as Record<string, unknown> | undefined),
73+
// A command with no formatter still owes the response's warnings: it renders through the same
74+
// router, on the stream its descriptor says its caller reads (#2682).
75+
await writeCliOutput(
76+
flags,
77+
routeResponseWarnings(
78+
{ data, text: readCommandMessage(data as Record<string, unknown> | undefined) },
79+
data,
80+
isParseableOutputCommand(command as CommandName) ? 'stderr' : 'text',
81+
),
7382
);
7483
return 0;
7584
}

‎src/commands/capture/settings.test.ts‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import fc from 'fast-check';
22
import { describe, expect, test } from 'vitest';
33
import type { CliFlags } from '@agent-device/contracts/command';
44
import { PROPERTY_RUNS } from '@agent-device/selectors/snapshot-geometry-fixtures';
5+
import { formatCliOutput } from '../cli-output.ts';
56
import { settingsCliReader, settingsCommandFacet, settingsDaemonWriter } from './settings.ts';
67

78
const MOBILE_TARGETS = [
@@ -55,26 +56,24 @@ describe('settings CLI', () => {
5556
});
5657
});
5758

58-
// #1796: the Android revoke warning rides `warnings`; the human CLI line must show it.
59-
test('renders response warnings after the message', () => {
59+
// #1796: the Android revoke warning rides `warnings`; the human CLI line must show it. The line is
60+
// appended by `formatCliOutput` (#2682), so that is where the guarantee is asserted; the formatter
61+
// itself only renders the response's own message.
62+
test('renders response warnings after the message', async () => {
6063
const warning = 'android.permission.CAMERA was granted before this revoke, and Android …';
61-
const output = settingsCommandFacet.cliOutputFormatter!({
62-
input: {},
63-
result: { setting: 'permission', state: 'reset', message: 'Updated setting: permission' },
64-
});
65-
expect(output.text).toBe('Updated setting: permission');
64+
const response = {
65+
setting: 'permission',
66+
state: 'reset',
67+
message: 'Updated setting: permission',
68+
warnings: [warning],
69+
};
6670

67-
const warned = settingsCommandFacet.cliOutputFormatter!({
68-
input: {},
69-
result: {
70-
setting: 'permission',
71-
state: 'reset',
72-
message: 'Updated setting: permission',
73-
warnings: [warning],
74-
},
75-
});
76-
expect(warned.text).toBe(`Updated setting: permission\nWarning: ${warning}`);
77-
expect(warned.data).toMatchObject({ warnings: [warning] });
71+
const output = await formatCliOutput({ name: 'settings', input: {}, result: response });
72+
expect(output?.text).toBe(`Updated setting: permission\nWarning: ${warning}`);
73+
expect(output?.data).toMatchObject({ warnings: [warning] });
74+
75+
const rendered = settingsCommandFacet.cliOutputFormatter!({ input: {}, result: response });
76+
expect(rendered.text).toBe('Updated setting: permission');
7877
});
7978

8079
test('keeps the documented macOS permission form in the command detail', () => {

‎src/commands/capture/settings.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ import {
2424
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
2525
import { defineCommandFacet } from '../family/types.ts';
2626
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
27-
import { messageWithWarningsOutput } from '../output-common.ts';
27+
import { messageOutput } from '../output-common.ts';
2828

2929
const SETTINGS_COMMAND_NAME = 'settings';
3030
const settingsCommandDescription =
@@ -69,7 +69,7 @@ export const settingsCommandFacet = defineCommandFacet({
6969
cliReader: settingsCliReader,
7070
daemonWriter: settingsDaemonWriter,
7171
// Android permission revokes append a relaunch warning (#1796); render it for humans too.
72-
cliOutputFormatter: messageWithWarningsOutput,
72+
cliOutputFormatter: messageOutput,
7373
});
7474

7575
// fallow-ignore-next-line complexity

‎src/commands/capture/wait.test.ts‎

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎src/commands/capture/wait.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ import {
1717
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
1818
import { defineCommandFacet } from '../family/types.ts';
1919
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
20-
import { messageWithWarningsOutput } from '../output-common.ts';
20+
import { messageOutput } from '../output-common.ts';
2121
import { WAIT_KIND_VALUES } from './wait-command-contract.ts';
2222
import { absenceCaptureOptionRefusal } from '@agent-device/selectors/absence-observation';
2323
import { absenceCaptureOptionError } from '@agent-device/selectors/absence-observation-errors';
@@ -68,7 +68,7 @@ export const waitCommandFacet = defineCommandFacet({
6868
cliSchema: waitCliSchema,
6969
cliReader: waitCliReader,
7070
daemonWriter: waitDaemonWriter,
71-
cliOutputFormatter: messageWithWarningsOutput,
71+
cliOutputFormatter: messageOutput,
7272
});
7373

7474
function waitInputToOptions(input: Record<string, unknown>): WaitCommandOptions {

‎src/commands/cli-output.test.ts‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
import { describe, expect, test } from 'vitest';
2+
import {
3+
listCommandFamilyCliOutputFormatters,
4+
listCommandFamilyMetadata,
5+
} from './family/registry.ts';
6+
import { formatCliOutput, isParseableOutputCommand } from './cli-output.ts';
7+
import type { CommandName } from './command-metadata.ts';
8+
9+
/**
10+
* #2682: one dispatcher, one warning rule. Every command that renders text owes the agent the
11+
* response's `Warning:` lines, and the ONLY way a command keeps them off stdout is the
12+
* `parseableOutput` trait on its own descriptor, because its stdout is the value a caller pipes.
13+
* A command added tomorrow inherits the rule; a command that wants out has to say so here.
14+
*/
15+
const REPAIR_WARNING =
16+
'The session app was not foreground when this command arrived (prior state runningBackground), ' +
17+
'so the runner activated it before answering (reason stale_target).';
18+
19+
const PARSEABLE_OUTPUT_COMMANDS = [
20+
'clipboard',
21+
'find',
22+
'get',
23+
'record',
24+
] as const satisfies readonly CommandName[];
25+
26+
/** Every command the registry gives a text formatter — the population the rule must cover. */
27+
const FORMATTER_COMMANDS = Object.keys(
28+
listCommandFamilyCliOutputFormatters(),
29+
).sort() as CommandName[];
30+
31+
async function render(name: CommandName, result: unknown, input = {}) {
32+
const output = await formatCliOutput({ name, input, result });
33+
expect(output, `${name} renders no CLI output`).toBeDefined();
34+
return output!;
35+
}
36+
37+
/**
38+
* The table: what each formatter owes, asserted against every formatter the registry exposes. Each
39+
* payload is the shape that command's response really has, so a formatter cannot pass by ignoring a
40+
* synthetic one. `apps`/`devices` answer with a bare array, which is why they are marked `warns:
41+
* false`: the daemon has no warnings channel onto an array payload — a fact the table names instead
42+
* of hiding behind a skipped assertion.
43+
*/
44+
const RESPONSE_FIXTURES: Partial<Record<CommandName, unknown>> = {
45+
apps: ['com.example.app'],
46+
artifacts: { source: 'daemon', artifacts: [], message: 'No daemon artifacts.' },
47+
batch: { executed: 0, total: 0, totalDurationMs: 5, results: [] },
48+
capabilities: { device: { name: 'iPhone' }, availableCommands: [] },
49+
debug: {
50+
outPath: '/tmp/debug.crash',
51+
message: 'Crash read',
52+
crash: { topFrames: [], findings: [] },
53+
matchedImages: [],
54+
},
55+
devices: [],
56+
session: { sessions: [] },
57+
};
58+
59+
type RenderCase = { name: CommandName; response: unknown; warns: boolean };
60+
61+
const RENDER_CASES: RenderCase[] = FORMATTER_COMMANDS.map((name) => {
62+
const fixture = RESPONSE_FIXTURES[name] ?? { message: 'done' };
63+
return {
64+
name,
65+
response: Array.isArray(fixture) ? fixture : { ...fixture, warnings: [REPAIR_WARNING] },
66+
warns: !Array.isArray(fixture),
67+
};
68+
});
69+
70+
test('the parseable-output set is exactly the declared exceptions', () => {
71+
expect(FORMATTER_COMMANDS.filter(isParseableOutputCommand)).toEqual(
72+
[...PARSEABLE_OUTPUT_COMMANDS].sort(),
73+
);
74+
});
75+
76+
/**
77+
* The commands with no formatter answer through the CLI's generic path, which routes the same way.
78+
* None of them may declare `parseableOutput`, because that path has no second stream to split — if
79+
* one ever does, it owes its own printer instead of silently losing the disclosure.
80+
*/
81+
test('a command with no formatter never opts out of stdout', () => {
82+
const allCommands = listCommandFamilyMetadata().map((metadata) => metadata.name);
83+
const withoutFormatter = allCommands.filter((name) => !FORMATTER_COMMANDS.includes(name));
84+
expect(withoutFormatter.length).toBeGreaterThan(0);
85+
expect(withoutFormatter.filter(isParseableOutputCommand)).toEqual([]);
86+
});
87+
88+
describe('the dispatcher appends the response warnings for every formatter', () => {
89+
for (const testCase of RENDER_CASES) {
90+
const parseable = (PARSEABLE_OUTPUT_COMMANDS as readonly string[]).includes(testCase.name);
91+
const outcome = parseable
92+
? 'keeps stdout as the value and warns on stderr'
93+
: testCase.warns
94+
? 'warns on stdout'
95+
: 'has no warnings channel on its array payload';
96+
test(`${testCase.name} ${outcome}`, async () => {
97+
const output = await render(testCase.name, testCase.response as Record<string, unknown>);
98+
if (!testCase.warns) {
99+
expect(output.stderr ?? '').not.toContain(REPAIR_WARNING);
100+
return;
101+
}
102+
if (parseable) {
103+
expect(output.text ?? '').not.toContain(REPAIR_WARNING);
104+
expect(output.stderr ?? '').toContain(`Warning: ${REPAIR_WARNING}`);
105+
} else {
106+
// A report builder may already print the warning inside its own report; what no command may
107+
// do is drop it, or put it on a stream its reader is not watching.
108+
expect(output.text ?? '').toContain(REPAIR_WARNING);
109+
expect(output.stderr ?? '').not.toContain(REPAIR_WARNING);
110+
}
111+
});
112+
}
113+
});
114+
115+
/**
116+
* A real reachable `get text` request: the CLI reader always produces `format`, so this is the input
117+
* the formatter actually receives after a capture repaired foreground. stdout stays the value a
118+
* caller can pipe; the disclosure is still there, on stderr, exactly once.
119+
*/
120+
describe('get text after a foreground repair', () => {
121+
const repaired = {
122+
text: 'General',
123+
node: { type: 'Cell', label: 'General' },
124+
warnings: [REPAIR_WARNING],
125+
};
126+
127+
test('format text prints the value alone and warns once on stderr', async () => {
128+
const output = await render('get', repaired, { format: 'text', target: { ref: '@e1' } });
129+
expect(output.text).toBe('General');
130+
expect(output.stderr).toBe(`Warning: ${REPAIR_WARNING}\n`);
131+
});
132+
133+
test('format attrs keeps its JSON parseable and warns once on stderr', async () => {
134+
const output = await render('get', repaired, { format: 'attrs', target: { ref: '@e1' } });
135+
expect(() => JSON.parse(String(output.text))).not.toThrow();
136+
expect(String(output.stderr?.match(/Warning:/g)?.length)).toBe('1');
137+
});
138+
139+
test('a read that repaired nothing stays silent on both streams', async () => {
140+
const output = await render(
141+
'get',
142+
{ text: 'General' },
143+
{ format: 'text', target: { ref: '@e1' } },
144+
);
145+
expect(output.text).toBe('General');
146+
expect(output.stderr).toBeUndefined();
147+
});
148+
});
149+
150+
/**
151+
* `find` shares `get`'s stdout rule, which is why `find <x> get text` and `get text` agree, while the
152+
* narration commands (`is`, `wait`) keep the warning on stdout after their own line.
153+
*/
154+
describe('the two stdout contracts in one run', () => {
155+
test('find get text keeps the value on stdout like get text does', async () => {
156+
const output = await render(
157+
'find',
158+
{ text: 'General', warnings: [REPAIR_WARNING] },
159+
{ query: 'General' },
160+
);
161+
expect(output.text).toBe('General');
162+
expect(output.stderr).toContain(`Warning: ${REPAIR_WARNING}`);
163+
});
164+
165+
test('is prints the disclosure after its verdict on stdout', async () => {
166+
const output = await render(
167+
'is',
168+
{ predicate: 'visible', result: true, warnings: [REPAIR_WARNING] },
169+
{
170+
predicate: 'visible',
171+
selector: 'label="General"',
172+
},
173+
);
174+
expect(output.text).toBe(`Passed: is visible\nWarning: ${REPAIR_WARNING}`);
175+
});
176+
177+
test('press keeps an Android permission-dialog warning on stdout after its tap line', async () => {
178+
const permissionWarning =
179+
'press id="request-mic" opened an Android permission dialog ' +
180+
'(com.google.android.permissioncontroller) over com.example.app.';
181+
const output = await render('press', {
182+
message: 'Tapped (278, 817)',
183+
x: 278,
184+
y: 817,
185+
warning: permissionWarning,
186+
});
187+
expect(output.text).toBe(`Tapped (278, 817)\nWarning: ${permissionWarning}`);
188+
});
189+
190+
test('wait prints the disclosure after its own line on stdout', async () => {
191+
const output = await render('wait', {
192+
message: 'Text "Receipt" appeared',
193+
warnings: [REPAIR_WARNING],
194+
});
195+
expect(output.text).toBe(`Text "Receipt" appeared\nWarning: ${REPAIR_WARNING}`);
196+
});
197+
198+
test('press keeps its settle notes and gains the disclosure once', async () => {
199+
const output = await render('press', {
200+
message: 'Tapped (10, 20)',
201+
x: 10,
202+
y: 20,
203+
warnings: [REPAIR_WARNING],
204+
settle: { settled: true, waitedMs: 400, diff: { summary: { additions: 1, removals: 0 } } },
205+
});
206+
expect(output.text).toBe(
207+
[
208+
'Tapped (10, 20)',
209+
'settled after 400ms: +1 -0 (~0 unchanged)',
210+
`Warning: ${REPAIR_WARNING}`,
211+
].join('\n'),
212+
);
213+
});
214+
});

0 commit comments

Comments
 (0)