Skip to content

Commit 86736a5

Browse files
authored
feat: versioned snapshot refs with MCP auto-pinning (#1096)
* feat: versioned snapshot refs with MCP auto-pinning Refs are positional indexes into the latest stored session tree; #1093's coarse snapshotRefsStale marker warns honestly but cannot say WHICH tree a ref came from. Give the session a monotonically increasing snapshotGeneration, advanced wherever the stored tree is replaced: the setSessionSnapshot choke point and the snapshot/diff command path that bypasses it. Token economy (non-negotiable): the snapshot tree output is unchanged — plain e12 refs on every node. Ref-issuing responses (snapshot command, find ref outputs) carry the generation ONCE as the additive refsGeneration field. Ref-consuming commands (press/click/fill/longpress/ get/wait) accept both forms: plain @E12 keeps today's behavior including the coarse #1093 warning; pinned @E12~s3 is clean when the generation matches the stored tree, gets a precise warning naming both generations when it does not, and a malformed suffix is INVALID_ARGS with a grammar hint. Warn-only this release — tightening comes later per the compat ladder. The MCP layer auto-pins at zero token cost: it sees snapshot/find responses before the model does, remembers the last refsGeneration per session name, and rewrites plain @ref tool arguments to the pinned form before forwarding. The model never sees or types suffixes; with no remembered generation, refs pass through unpinned (never guess). Replay parsing and script writing strip and IGNORE pins — generations are meaningless outside the session that minted them. Refs #1076 * docs: CONTEXT.md vocabulary for ref generation pins Moved from #1097 per the review sequencing note: the term lands with the behavior it describes. * docs: teach the ref pin syntax in CLI help MCP agents get pins transparently (auto-pinning), but CLI-driving agents only ever met the coarse warning — refsGeneration arrived in snapshot responses with nothing explaining it, making pins an undiscoverable feature on the primary agent surface. One help line in the agent loop guidance closes that; warnings stay short (they fire repeatedly, teaching belongs in once-read surfaces). * fix: per-ref MCP pin provenance and seeded generations Review findings on the first cut: 1. The MCP layer kept ONE refsGeneration per session, so after snapshot(s12) -> find(s13) a plain @e37 from the pre-find snapshot got pinned ~s13 and read as current — recreating the find-blessing hole at the pinning layer. Replace it with per-ref provenance: Map<pinScope, Map<refBody, generation>>, scoped by state dir + session name (stateDir is a per-call MCP config field, so one server process can face multiple daemons). Merge-only updates: refs present in a ref-issuing response (snapshot nodes, digest refs, the find ref) move to its generation; absent refs KEEP their older pins — an old pin on a replaced tree is what makes the daemon warn. Never-issued refs pass through unpinned; an issuing response without refsGeneration clears the scope; memory bounded to the ~1000 most recently issued pins. 2. Generations were per-lifetime counters from 1, so a reopened session's ~s1 collided silently with the previous lifetime's. Seed the first bump at a random 6-digit base (crypto randomInt): cross-lifetime collisions become ~1e-6 — probabilistic (seeded), not identity-based, documented on the field. Pin format unchanged; within-lifetime comparisons stay exact. Tests: the MCP blessing scenario (pre-find ref stays pinned to ITS generation), the daemon half in the provider scenario (find must not bless a pre-find pin), reopen/reseed at unit + handler level, state-dir scope isolation, digest-ref merging; generation fixtures made seed-agnostic (relative bumps, echo the observed seed). Refs #1076
1 parent 2557670 commit 86736a5

26 files changed

Lines changed: 1346 additions & 51 deletions

‎CONTEXT.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
- Parity table: golden JSON fixture under `contracts/fixtures/` consumed by both vitest and the runner's gated Swift tests, so a cross-language rule (e.g. tap-point policy) cannot drift silently. Change the rule only via the table.
4949
- Coverage manifest: `CONTRACT_COVERAGE` export beside each interaction contract test file claiming which matrix cells it proves; the coverage gate requires every enforced/delegated cell to be claimed and rejects overclaims of waived cells.
5050
- Delegation-on-error: a fast path falling back to the runtime path on semantic failure shapes. It closes failure-side guarantee cells only — never success-path parity.
51+
- Ref generation pin: optional `~s<n>` suffix on an @ref carrying the snapshot generation it was minted from. Accepted as input everywhere, emitted by no tree output (snapshot token budget), auto-appended by the MCP layer, stripped and ignored by replay.
5152
- Snapshot capture plan: per-strategy ordered chain of iOS snapshot capture backends (recursive tree, query sweep, private AX) run by one plan runner under a shared wall-clock budget; recovery ordering is declared data, never a per-call-site branch.
5253
- Snapshot quality verdict: structured outcome (state, backend, reason code, effective depth, collapsed leaves) computed once by the plan runner and shipped with every planned snapshot payload; the daemon and CLI render it instead of re-deriving degradation from node shapes.
5354
- AX-unavailable target invalidation: iOS/macOS runner behavior where a root accessibility snapshot failure such as `kAXErrorIllegalArgument` marks the cached `XCUIApplication` target handle suspect. The runner fails closed for degraded interactive snapshots, clears the cached target, and lets the next command reacquire the app through normal activation.

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ const AGENT_QUICKSTART_LINES = [
6262
'Default loop: devices/apps -> open -> snapshot -i -> press/fill/get/is/wait/find -> verify with diff snapshot -> close.',
6363
'Verify a mutation with diff snapshot (or diff snapshot -i), not a full snapshot: it prints only the added/removed/changed lines since the last snapshot in this session, so confirming an action costs a few lines instead of the whole tree.',
6464
'Use selectors or refs as positional targets: id="submit", label="Allow", or @e12 from snapshot -i.',
65+
'Pin a ref to the snapshot that minted it with ~s<n> (n = refsGeneration in the snapshot response): press @e12~s4. Pinned refs get exact staleness warnings instead of the coarse tree-changed one; plain refs stay valid input.',
6566
'Plain snapshot reads state; snapshot -i refreshes current interactive refs only.',
6667
'Default snapshot text is an agent-facing, token-efficient view for planning and targeting actions.',
6768
'Read-only visible/state question: use snapshot/get/is/find; use snapshot -i only when refs are needed.',

‎src/daemon/__tests__/response-views.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,3 +247,8 @@ test('find/get default and full return today’s shape unchanged (same reference
247247
expect(getView!(data, 'default')).toBe(data);
248248
expect(getView!(data, 'full')).toBe(data);
249249
});
250+
251+
test('snapshot digest preserves refsGeneration — the pinning signal for the refs it keeps (#1076)', () => {
252+
const digest = RESPONSE_VIEWS.snapshot!({ ...SNAPSHOT_DATA, refsGeneration: 7 }, 'digest');
253+
expect(digest.refsGeneration).toBe(7);
254+
});
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
import { expect, test } from 'vitest';
2+
import type { SnapshotState } from '../../kernel/snapshot.ts';
3+
import type { SessionState } from '../types.ts';
4+
import {
5+
resolveRefStalenessWarning,
6+
setSessionSnapshot,
7+
STALE_SNAPSHOT_REFS_WARNING,
8+
} from '../session-snapshot.ts';
9+
10+
function makeSession(): SessionState {
11+
return {
12+
name: 'default',
13+
device: { id: 'device-1', name: 'Test Device', platform: 'apple' },
14+
createdAt: Date.now(),
15+
actions: [],
16+
} as unknown as SessionState;
17+
}
18+
19+
function makeSnapshot(): SnapshotState {
20+
return { nodes: [], createdAt: Date.now(), backend: 'xctest' };
21+
}
22+
23+
test('setSessionSnapshot advances the generation on every tree replacement (#1076 versioned refs)', () => {
24+
const session = makeSession();
25+
expect(session.snapshotGeneration).toBeUndefined();
26+
27+
const first = makeSnapshot();
28+
setSessionSnapshot(session, first);
29+
// First bump of a lifetime is SEEDED at a random 6-digit base (see
30+
// nextSnapshotGeneration) — assert the range, not a literal.
31+
const seeded = session.snapshotGeneration!;
32+
expect(seeded).toBeGreaterThanOrEqual(100_000);
33+
expect(seeded).toBeLessThan(1_000_000);
34+
expect(session.snapshotRefsStale).toBe(true);
35+
36+
// Storing the SAME snapshot object again is not a replacement.
37+
setSessionSnapshot(session, first);
38+
expect(session.snapshotGeneration).toBe(seeded);
39+
40+
// Within a lifetime the counter is strictly monotonic.
41+
setSessionSnapshot(session, makeSnapshot());
42+
expect(session.snapshotGeneration).toBe(seeded + 1);
43+
});
44+
45+
test('a reopened session reseeds so pins from a previous lifetime do not silently collide', () => {
46+
const firstLifetime = makeSession();
47+
setSessionSnapshot(firstLifetime, makeSnapshot());
48+
const oldGeneration = firstLifetime.snapshotGeneration!;
49+
50+
// Reopen: a fresh session object restarts the counter with a NEW seed.
51+
const secondLifetime = makeSession();
52+
setSessionSnapshot(secondLifetime, makeSnapshot());
53+
secondLifetime.snapshotRefsStale = false;
54+
55+
// Probabilistic, not identity-based: the seeds collide with ~1/900000
56+
// probability (an accepted residual risk, documented on the field).
57+
expect(secondLifetime.snapshotGeneration).not.toBe(oldGeneration);
58+
// A pin minted in the previous lifetime warns instead of reading as current.
59+
expect(
60+
resolveRefStalenessWarning({
61+
session: secondLifetime,
62+
ref: '@e1',
63+
mintedGeneration: oldGeneration,
64+
}),
65+
).toContain(`minted from snapshot s${oldGeneration}`);
66+
});
67+
68+
test('resolveRefStalenessWarning: pinned-current clean, pinned-stale precise, plain coarse', () => {
69+
const session = makeSession();
70+
session.snapshotGeneration = 15;
71+
session.snapshotRefsStale = true;
72+
73+
// Pinned to the stored generation: the pin proves the ref matches the tree,
74+
// so the coarse marker is overruled.
75+
expect(
76+
resolveRefStalenessWarning({ session, ref: '@e37', mintedGeneration: 15 }),
77+
).toBeUndefined();
78+
79+
expect(resolveRefStalenessWarning({ session, ref: '@e37', mintedGeneration: 12 })).toBe(
80+
'Ref @e37 was minted from snapshot s12 but the session tree is now s15 — re-run snapshot -i.',
81+
);
82+
83+
expect(resolveRefStalenessWarning({ session, ref: '@e37', mintedGeneration: undefined })).toBe(
84+
STALE_SNAPSHOT_REFS_WARNING,
85+
);
86+
87+
session.snapshotRefsStale = false;
88+
expect(
89+
resolveRefStalenessWarning({ session, ref: '@e37', mintedGeneration: undefined }),
90+
).toBeUndefined();
91+
});
92+
93+
test('resolveRefStalenessWarning treats a missing stored generation as s0', () => {
94+
const session = makeSession();
95+
expect(resolveRefStalenessWarning({ session, ref: 'e2', mintedGeneration: 3 })).toBe(
96+
'Ref @e2 was minted from snapshot s3 but the session tree is now s0 — re-run snapshot -i.',
97+
);
98+
expect(resolveRefStalenessWarning({ session, ref: '@e2', mintedGeneration: 0 })).toBeUndefined();
99+
});

‎src/daemon/handlers/__tests__/find.test.ts‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,8 @@ test('handleFindCommands click returns deterministic metadata across locator var
9393
positionals: ['Increment', 'click'],
9494
nodes: [hittableParentNoRect, nonHittableChildWithRect],
9595
invoke: async () => ({ platformSpecificRef: 'XCUIElementTypeView' }),
96-
expectedKeys: ['locator', 'message', 'query', 'ref', 'x', 'y'],
96+
// refsGeneration rides every ref-issuing find response (#1076 versioned refs).
97+
expectedKeys: ['locator', 'message', 'query', 'ref', 'refsGeneration', 'x', 'y'],
9798
expectedLocator: 'any',
9899
expectedQuery: 'Increment',
99100
expectedCoordinates: { x: 100, y: 50 },
@@ -757,3 +758,33 @@ test('handleFindCommands click re-issues a fresh ref and clears the stale-refs m
757758
// the marker clears before the internal click @ref sub-invocation runs.
758759
expect(storedSession.snapshotRefsStale).toBe(false);
759760
});
761+
762+
test('handleFindCommands click carries refsGeneration for the freshly stored tree (#1076 versioned refs)', async () => {
763+
const sessionName = 'default';
764+
const session = makeSession(sessionName);
765+
// Two earlier tree replacements happened in this session.
766+
session.snapshotGeneration = 2;
767+
768+
const { response, session: storedSession } = await runFindClickScenario({
769+
positionals: ['Increment', 'click'],
770+
nodes: [
771+
{
772+
index: 0,
773+
type: 'Button',
774+
label: 'Increment',
775+
hittable: true,
776+
rect: { x: 50, y: 0, width: 100, height: 100 },
777+
depth: 0,
778+
},
779+
],
780+
session,
781+
});
782+
783+
expect(response.ok).toBe(true);
784+
// The find capture replaced the stored tree (generation 3) and the response
785+
// returns a ref minted from it, so it reports that generation ONCE.
786+
expect(storedSession.snapshotGeneration).toBe(3);
787+
if (response.ok) {
788+
expect((response.data as Record<string, unknown>).refsGeneration).toBe(3);
789+
}
790+
});

‎src/daemon/handlers/__tests__/interaction-touch-targets.test.ts‎

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
import { test, expect } from 'vitest';
2-
import { parseFillTarget, parseTouchTarget } from '../interaction-touch-targets.ts';
2+
import {
3+
parseFillTarget,
4+
parseLongPressTarget,
5+
parseTouchTarget,
6+
} from '../interaction-touch-targets.ts';
37

48
test('parseTouchTarget preserves ref fallback label through shared grammar', () => {
59
const parsed = parseTouchTarget(['@e4', 'Email field'], 'press');
@@ -78,3 +82,77 @@ test('parseFillTarget rejects invalid coordinates instead of treating them as a
7882
}
7983
}
8084
});
85+
86+
// --- Versioned refs (#1076): the daemon boundary splits `@e12~s3` pins ---
87+
88+
test('parseTouchTarget splits a pinned ref into plain ref + generation', () => {
89+
const parsed = parseTouchTarget(['@e4~s12', 'Email field'], 'press');
90+
91+
expect(parsed).toEqual({
92+
ok: true,
93+
target: {
94+
kind: 'ref',
95+
ref: '@e4',
96+
fallbackLabel: 'Email field',
97+
},
98+
refGeneration: 12,
99+
});
100+
});
101+
102+
test('parseTouchTarget rejects a malformed generation suffix with the grammar hint', () => {
103+
const parsed = parseTouchTarget(['@e4~s'], 'press');
104+
105+
expect(parsed.ok).toBe(false);
106+
if (!parsed.ok) {
107+
expect(parsed.response).toMatchObject({
108+
ok: false,
109+
error: {
110+
code: 'INVALID_ARGS',
111+
message: expect.stringContaining('malformed generation suffix'),
112+
details: { hint: expect.stringContaining('@e12~s3') },
113+
},
114+
});
115+
}
116+
});
117+
118+
test('parseLongPressTarget carries the pinned generation past the trailing duration', () => {
119+
const parsed = parseLongPressTarget(['@e4~s7', '800']);
120+
121+
expect(parsed).toEqual({
122+
ok: true,
123+
target: {
124+
kind: 'ref',
125+
ref: '@e4',
126+
fallbackLabel: '',
127+
},
128+
refGeneration: 7,
129+
durationMs: 800,
130+
});
131+
});
132+
133+
test('parseFillTarget splits a pinned ref and keeps the text intact', () => {
134+
const parsed = parseFillTarget(['@e4~s3', '[email protected]']);
135+
136+
expect(parsed).toEqual({
137+
ok: true,
138+
target: {
139+
kind: 'ref',
140+
ref: '@e4',
141+
fallbackLabel: '',
142+
},
143+
refGeneration: 3,
144+
145+
});
146+
});
147+
148+
test('parseFillTarget rejects a malformed pinned ref before reading text', () => {
149+
const parsed = parseFillTarget(['@e4~x3', 'text']);
150+
151+
expect(parsed.ok).toBe(false);
152+
if (!parsed.ok) {
153+
expect(parsed.response).toMatchObject({
154+
ok: false,
155+
error: { code: 'INVALID_ARGS' },
156+
});
157+
}
158+
});

0 commit comments

Comments
 (0)