Skip to content

Commit 4cf36bc

Browse files
committed
refactor: adopt the best of the parallel #1653 implementation
Two sessions independently built #1638 (PR #1650 and PR #1653) and converged on the same architecture — trait in the registry, one engine with two entry points, runtime-command seam, lazy import, preserve-daemon, stored-baseline honesty. #1650 continues; this folds in what #1653 did better: - The agent-facing help core loop (cli-help.ts) now names scroll and back as settle-capable. Without this, the benchmarked closed-grammar help line kept instructing agents that --settle is only for press/click/fill/longpress — actively steering the AppControlBench models away from what #1638 shipped. - issueSettleRefs moves into session-snapshot.ts, beside the partial-frame primitive it wraps, deleting the single-function settle-ref-issuance module. - Their seam tests: back reader→writer settle plumbing, back CLI settle rendering, and a trait-less generic command (home) ignoring a stray settle flag rather than observing or rejecting. What #1650 had that #1653 lacked, for the record: the SETTLE_REF_ISSUING_TOOLS registry derivation (without it, MCP never pins a scroll/back settle diff's refs and the partial frame rejects every follow-up), BackCommandResult.settle in contracts, back's MCP output schema, paste-ready pinned diff refs, and the docs/changelog/baseline surfaces.
1 parent 8950ef3 commit 4cf36bc

8 files changed

Lines changed: 105 additions & 43 deletions

File tree

‎src/cli/parser/__tests__/cli-help-topics.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ test('usage includes agent workflows, config, environment, and examples footers'
9191
assert.match(usageText, /Default app loop: agent-device open <app>/);
9292
assert.match(
9393
usageText,
94-
/Use --settle only on planned press, click, fill, or longpress commands; never add it to open, snapshot, or close/,
94+
/Use --settle only on planned press, click, fill, longpress, scroll, or back commands; never add it to open, snapshot, or close/,
9595
);
9696
assert.match(usageText, /type never accepts --settle/);
9797
assert.match(usageText, /explicit success confirmation is visible, stop/);

‎src/cli/parser/cli-help.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ const AGENT_START_LINES = [
7979
// Haiku from 0/2 baseline to 4/4; generic structured-hint recovery passed 8/8
8080
// uncoached output cases versus 7/8 with the longer special-case prose.
8181
'Default app loop: agent-device open <app> -> agent-device snapshot -i -> mutate a current target with --settle -> continue from that settled diff -> agent-device close.',
82-
'Use --settle only on planned press, click, fill, or longpress commands; never add it to open, snapshot, or close. type never accepts --settle: run agent-device type "text", then diff snapshot if verification is needed. Once the task\'s requested end state or an explicit success confirmation is visible, stop; do not tap transient follow-up controls or navigate away only to re-verify.',
82+
'Use --settle only on planned press, click, fill, longpress, scroll, or back commands; never add it to open, snapshot, or close. type never accepts --settle: run agent-device type "text", then diff snapshot if verification is needed. Once the task\'s requested end state or an explicit success confirmation is visible, stop; do not tap transient follow-up controls or navigate away only to re-verify.',
8383
'Follow structured command hints before choosing a recovery action.',
8484
'Targets are concrete refs or selectors: @e12, label="Query", role=button label="Submit".',
8585
'Selector keys are only: id, role, text, label, value, appname, windowtitle, visible, hidden, editable, selected, focused, enabled, hittable. placeholder, index, and key are not selector keys.',

‎src/commands/system/index.test.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import {
2727
tvRemoteDaemonWriter,
2828
systemCommandFamily,
2929
} from './index.ts';
30+
import { systemCliOutputFormatters } from './output.ts';
3031

3132
function flags(overrides: Partial<CliFlags> = {}): CliFlags {
3233
return overrides as CliFlags;
@@ -118,6 +119,50 @@ describe('system command interface', () => {
118119
).toBeUndefined();
119120
});
120121

122+
// #1638: --settle has to survive BOTH back seams — the reader that builds the
123+
// input and the writer that turns it into daemon request options.
124+
test('back reader and writer carry the settle request through to daemon flags', () => {
125+
const input = backCliReader([], flags({ settle: true, settleQuietMs: 250, timeoutMs: 8_000 }));
126+
expect(input).toMatchObject({ settle: true, settleQuietMs: 250, timeoutMs: 8_000 });
127+
expect(backDaemonWriter(input).options).toMatchObject({
128+
settle: true,
129+
settleQuietMs: 250,
130+
timeoutMs: 8_000,
131+
});
132+
expect(backCliReader([], flags()).settle).toBeUndefined();
133+
});
134+
135+
test('back CLI output renders the settled observation', () => {
136+
const output = systemCliOutputFormatters.back({
137+
input: {},
138+
result: {
139+
action: 'back',
140+
mode: 'in-app',
141+
message: 'Back',
142+
settle: {
143+
settled: true,
144+
waitedMs: 300,
145+
diff: {
146+
summary: { additions: 1, removals: 2, unchanged: 5 },
147+
lines: [
148+
{ kind: 'removed', text: '@e9 [button] "Save"' },
149+
{ kind: 'added', text: '@e3 [button] "Edit"', ref: 'e3' },
150+
],
151+
},
152+
},
153+
},
154+
});
155+
156+
expect(output.text).toBe(
157+
[
158+
'Back',
159+
'settled after 300ms: +1 -2 (~5 unchanged)',
160+
'- @e9 [button] "Save"',
161+
'+ @e3 [button] "Edit"',
162+
].join('\n'),
163+
);
164+
});
165+
121166
test('orientation reader and writer normalize orientation', () => {
122167
expect(orientationCliReader(['left'], flags())).toMatchObject({
123168
orientation: 'landscape-left',

‎src/daemon/__tests__/generic-settle.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -317,6 +317,27 @@ test('a settle observation that cannot build a runtime degrades instead of faili
317317
expect(captureObservations).toEqual([]);
318318
});
319319

320+
test('a generic command without the observation trait ignores a stray settle flag', async () => {
321+
const sessionStore = makeSessionStore();
322+
const sessionName = 'generic-settle-traitless';
323+
const session = seedSession(sessionName, sessionStore);
324+
mockDispatch.mockResolvedValue({ action: 'home', message: 'Home' });
325+
326+
// A hand-built daemon request can put settle flags on any command; only the
327+
// descriptor trait admits them to the observation path. `home` has no trait,
328+
// so the flag is ignored: no captures, no settle payload, no rejection.
329+
const response = await dispatchGeneric({
330+
sessionName,
331+
sessionStore,
332+
session,
333+
command: 'home',
334+
flags: { settle: true },
335+
});
336+
337+
expect(expectOkData(response).settle).toBeUndefined();
338+
expect(captureObservations).toEqual([]);
339+
});
340+
320341
test('an orphaned --settle-quiet is rejected before the command dispatches', async () => {
321342
const sessionStore = makeSessionStore();
322343
const sessionName = 'generic-settle-orphan';

‎src/daemon/generic-settle.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ import type { ContextFromFlags } from './handlers/interaction-common.ts';
66
import { readSettleRequest, settleFlagGuardResponse } from './handlers/interaction-flags.ts';
77
import { createInteractionRuntime } from './handlers/interaction-runtime.ts';
88
import { captureSnapshotForSession } from './handlers/interaction-snapshot.ts';
9+
import { issueSettleRefs } from './session-snapshot.ts';
910
import type { SessionStore } from './session-store.ts';
10-
import { issueSettleRefs } from './settle-ref-issuance.ts';
1111
import type { DaemonRequest, DaemonResponse, SessionState } from './types.ts';
1212

1313
/**

‎src/daemon/handlers/interaction-touch.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,7 @@ import {
3838
type DirectIosSelectorTarget,
3939
} from '../direct-ios-selector.ts';
4040
import { expireRefFrame } from '../ref-frame.ts';
41-
import { resolveRefStalenessWarning } from '../session-snapshot.ts';
42-
import { issueSettleRefs } from '../settle-ref-issuance.ts';
41+
import { issueSettleRefs, resolveRefStalenessWarning } from '../session-snapshot.ts';
4342
import type { DaemonResponse, SessionState } from '../types.ts';
4443
import {
4544
assertAndroidPressStayedInApp,

‎src/daemon/session-snapshot.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { randomInt } from 'node:crypto';
2+
import type { SettleObservation } from '@agent-device/contracts/interaction';
23
import type { SnapshotState } from '@agent-device/kernel/snapshot';
34
import { activatePartialRefFrame, refFrameEpoch, refFrameState } from './ref-frame.ts';
45
import type { SessionState } from './types.ts';
@@ -120,6 +121,40 @@ export function markSessionPartialRefsIssued(session: SessionState, refs: Iterab
120121
activatePartialRefFrame(session, scope);
121122
}
122123

124+
/**
125+
* #1101 `--settle`: a settle observation carrying a diff hands the client refs
126+
* minted from the freshly stored settled tree (added lines carry them), which
127+
* makes the response ref-issuing like snapshot/find: it activates a PARTIAL
128+
* frame (ADR 0014) authorizing exactly those bodies, and returns the stored
129+
* tree's generation to ride inside the settle payload for MCP per-ref pinning.
130+
* Without a diff — never captured, or a sparse-quality capture that was not
131+
* stored — nothing was issued and the frame is left as the action's own
132+
* side-effect seam expired it.
133+
*
134+
* Every route that can attach a settle observation goes through here (the
135+
* touch commands and the generic scroll/back route, #1638), so the issuance
136+
* rule has one implementation beside the partial-frame primitive it wraps.
137+
*/
138+
export function issueSettleRefs(
139+
session: SessionState,
140+
settle: SettleObservation | undefined,
141+
): number | undefined {
142+
if (!settle?.diff) return undefined;
143+
markSessionPartialRefsIssued(session, collectSettleIssuedRefBodies(settle));
144+
return session.snapshotGeneration;
145+
}
146+
147+
/** The reusable refs a settled diff exposed: added diff lines, `refs`, `tail`. */
148+
function collectSettleIssuedRefBodies(settle: SettleObservation): string[] {
149+
const bodies: string[] = [];
150+
for (const line of settle.diff?.lines ?? []) {
151+
if (line.ref) bodies.push(line.ref);
152+
}
153+
for (const entry of settle.refs ?? []) bodies.push(entry.ref);
154+
for (const entry of settle.tail ?? []) bodies.push(entry.ref);
155+
return bodies;
156+
}
157+
123158
/**
124159
* Warning for a ref pinned to a generation (`@e12~s3`) whose epoch no longer
125160
* matches the session's current ref-frame epoch (`refFrameEpoch`) — NOT the

‎src/daemon/settle-ref-issuance.ts‎

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

0 commit comments

Comments
 (0)