Skip to content

Commit 208e3d3

Browse files
authored
feat(record): report whether the recorder stopped beside the export (#2613)
* feat(record): report whether the recorder stopped beside the export ADR 0024 keeps two facts independent: whether a playable export exists, and whether the recorder has stopped. Only the first was answered; a stop that discards its recorder's fate still looks identical to one that watched it exit. Add `StopObservation` to contracts and have every backend's finish state its observation: `confirmed` for an exit or an acknowledged stop, `unconfirmed` for an unreadable probe or a missing exit, `lost` for a proven identity mismatch or a dead owning session. Record the disposition of the recorder's own artifact path beside it — `pending`, `retirable`, or `retired` — where a backend has a native path distinct from the export. The observation and disposition ride the completion, the durable manifest, the CLI/Node/MCP stop result (both optional, required list unchanged), and the docs. An invalidated Apple recording reports `lost` rather than claiming a stop that session could no longer have signalled. Both modules stay off the eagerly evaluated recording façade, which lists runtime exports over its sources. No stop changes outcome here: every field is additive and nothing yet decides a retry, a retention, or a deletion from it. * fix(android): drop the retired installArgs key the helper fixture still carried #2618 removed installArgs from AndroidSnapshotHelperManifest and left the annotated fixture naming it, so origin/main fails its own Typecheck job (CI run 34944609119). The reader ignores the field on older manifests; a fixture of a current manifest has no reason to carry it. * fix(android): answer a completed recording's disposition from the device The completed marker was written with nativePathDisposition 'retirable' a step before the chunks were removed, while the live result and the daemon manifest said 'retired', so the same recording reported two dispositions and a replay after a daemon restart claimed a retirement that had already happened. The disposition is now decided in one place, by looking at the device: the stop answers with it after disposal, and a replay of a completed marker re-reads that one field instead of replaying a value frozen before the removal. A device that reports a removal it did not perform stays owed. The marker keeps its pre-disposal value because publishing it before cleanup is what keeps an earned completion across a crash. Mutations proven to fail: serving the marker value unchanged fails the crash-replay and both pid-reuse replays; hardcoding 'retired' after cleanup fails the kept-artifact case. * docs(record): state which recorder and path states a stop can report today The docs, help, changelog and MCP descriptions read as if every declared state had a producer: no backend reports an unconfirmed recorder, an identity mismatch, or a pending path, so a reader expecting an export labelled unconfirmed got an error instead. Each surface now names what a stop emits today — confirmed, lost for an invalidated Apple recording, and retirable or retired for the recorder's own path — and says the rest of the vocabulary arrives with the ADR 0024 steps that gain those probes. The producer inventory itself now lives on the two vocabulary types, where the next reader meets it before writing another copy. * chore(gates): publish the two recording fact modules from contracts Adds the ./recording-stop-observation and ./recording-native-path subpaths the daemon, Android, Apple, capture-kit, and MCP surfaces read, and regenerates the contracts export snapshot package-boundaries diffs against. * fix(android): read a path's absence only from a probe that answered * test(mutation): repoint the indirect-ownership pin at a chain that still exists #2499 took `scroll-edge-state` out of the interaction runtime's imports, which left the indirect-ownership example naming a test that no longer reaches that kernel, and the model gate only noticed when a recording change made it runnable again. `back-runtime.test.ts` reaches edge detection through the daemon without importing the kernel file, so the omission this assertion exists to catch is still asserted.
1 parent 5fb2860 commit 208e3d3

39 files changed

Lines changed: 783 additions & 56 deletions

‎CHANGELOG.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,25 @@
5353
is invalidated and prepare retries with the artifact intact. Only a failure that indicts the
5454
artifact rebuilds it, so a runner that refuses the connection or never answers on any route still
5555
wipes it and rebuilds, which is what that rule is for.
56-
56+
- Added (record): `record stop` now answers the question a video cannot — whether its recorder
57+
actually stopped — beside the export. The result carries `recorder` and `nativePathDisposition` on
58+
CLI `--json`, the Node client, and MCP (ADR 0024). Today a stop says `confirmed`, or `lost` with
59+
`owner-session-lost` for an Apple recording whose session was invalidated, and names its artifact
60+
path `retirable` or `retired`; the wider vocabulary those two fields declare (`unconfirmed`, the
61+
identity-mismatch reasons, `pending`) arrives with the later ADR 0024 steps that gain the probes
62+
those states describe. Both are disclosures about the recorder and the path it writes to, not
63+
failures: the export is served either way, and a stop with nothing to report — an older session's
64+
replay, or a backend whose recorder writes the served file itself — omits them. No stop changes
65+
outcome in this release; the fields land first so the coordinator can report what it already knows
66+
before it starts acting on it.
67+
- Fixed (record): an Android stop credits the device with retiring its recording only when the
68+
device proved the chunks gone. The probe read any failed `test -e` as "not there", so an adb that
69+
timed out or a device dropped mid-call turned chunks that were still on the device into
70+
`nativePathDisposition: "retired"`, and a reattach that could not question the device at all
71+
declared the recording's artifact lost. A probe that never ran now answers uncertain: the path
72+
stays `retirable` and the recording stays finishable until the device answers.
5773
- Changed (sessions): the implicit session is now keyed by workspace **and platform**, so one checkout
74+
5875
can drive iOS and Android without inventing a `--session` name for every command (#2580). An
5976
implicit session was addressed by `cwd:<workspace>:default`, one slot per checkout, and it stayed
6077
bound to the first device it touched. A repo that tests both platforms — a visual-regression run

‎packages/capture-kit/src/screen-recording-completion.test.ts‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@ test('builds the common terminal recording result without dropping finalizer met
1616
gestureEvents: [],
1717
},
1818
{ telemetryPath: '/tmp/capture.telemetry.json' },
19-
false,
19+
{
20+
stopObservation: { recorder: 'unconfirmed', why: 'no-exit-in-budget' },
21+
showTouches: false,
22+
},
2023
),
2124
).toEqual({
2225
status: 'completed',
@@ -26,6 +29,7 @@ test('builds the common terminal recording result without dropping finalizer met
2629
clientOutPath: '/client/capture.mp4',
2730
startedAt: 100,
2831
completedAt: 200,
32+
stopObservation: { recorder: 'unconfirmed', why: 'no-exit-in-budget' },
2933
scope: 'device',
3034
showTouches: false,
3135
recordOnlySession: false,
@@ -34,3 +38,29 @@ test('builds the common terminal recording result without dropping finalizer met
3438
});
3539
vi.useRealTimers();
3640
});
41+
42+
test('records a native-path disposition only when the backend states one', () => {
43+
const snapshot = {
44+
backend: 'backend',
45+
outPath: '/tmp/capture.mp4',
46+
startedAt: 100,
47+
scope: 'device' as const,
48+
showTouches: false,
49+
recordOnlySession: false,
50+
gestureEvents: [],
51+
};
52+
expect(
53+
createScreenRecordingCompletion(snapshot, {}, { stopObservation: { recorder: 'confirmed' } })
54+
.result,
55+
).not.toHaveProperty('nativePathDisposition');
56+
expect(
57+
createScreenRecordingCompletion(
58+
snapshot,
59+
{},
60+
{
61+
stopObservation: { recorder: 'confirmed' },
62+
nativePathDisposition: 'retirable',
63+
},
64+
).result,
65+
).toMatchObject({ nativePathDisposition: 'retirable' });
66+
});

‎packages/capture-kit/src/screen-recording-completion.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,25 @@ import type {
22
ScreenRecordingCompletion,
33
ScreenRecordingLiveSnapshot,
44
} from '@agent-device/contracts/screen-recording-runtime';
5+
import type { NativePathDisposition } from '@agent-device/contracts/recording-native-path';
6+
import type { StopObservation } from '@agent-device/contracts/recording-stop-observation';
57
import type { ScreenRecordingFinalizer } from '@agent-device/contracts/screen-recording-runtime-host';
68

9+
/**
10+
* Builds the one object `record stop` answers with. Every backend states both facts a stop can
11+
* prove about itself — what became of its recorder, and what became of the path that recorder wrote
12+
* to (ADR 0024 2.2 and 2.3) — beside the media it finalized.
13+
*/
714
export function createScreenRecordingCompletion(
815
snapshot: ScreenRecordingLiveSnapshot,
916
finalization: Awaited<ReturnType<ScreenRecordingFinalizer['complete']>>,
10-
showTouches = snapshot.showTouches,
17+
facts: Readonly<{
18+
stopObservation: StopObservation;
19+
nativePathDisposition?: NativePathDisposition;
20+
showTouches?: boolean;
21+
}>,
1122
): Readonly<{ status: 'completed'; result: ScreenRecordingCompletion }> {
23+
const { stopObservation, nativePathDisposition, showTouches = snapshot.showTouches } = facts;
1224
return Object.freeze({
1325
status: 'completed',
1426
result: Object.freeze({
@@ -17,6 +29,8 @@ export function createScreenRecordingCompletion(
1729
...(snapshot.clientOutPath === undefined ? {} : { clientOutPath: snapshot.clientOutPath }),
1830
startedAt: snapshot.startedAt,
1931
completedAt: Date.now(),
32+
stopObservation,
33+
...(nativePathDisposition === undefined ? {} : { nativePathDisposition }),
2034
scope: snapshot.scope,
2135
showTouches,
2236
recordOnlySession: snapshot.recordOnlySession,

‎packages/contracts/package.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,14 @@
368368
"types": "./src/facades/recording.ts",
369369
"default": "./src/facades/recording.ts"
370370
},
371+
"./recording-native-path": {
372+
"types": "./src/recording-native-path.ts",
373+
"default": "./src/recording-native-path.ts"
374+
},
375+
"./recording-stop-observation": {
376+
"types": "./src/recording-stop-observation.ts",
377+
"default": "./src/recording-stop-observation.ts"
378+
},
371379
"./remote": {
372380
"types": "./src/facades/remote.ts",
373381
"default": "./src/facades/remote.ts"
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { describe, expect, test } from 'vitest';
2+
import {
3+
NATIVE_PATH_DISPOSITION_VALUES,
4+
isNativePathDisposition,
5+
} from './recording-native-path.ts';
6+
7+
describe('recording native-path disposition', () => {
8+
test('orders the three states a retained native artifact can be in', () => {
9+
expect(NATIVE_PATH_DISPOSITION_VALUES).toEqual(['pending', 'retirable', 'retired']);
10+
});
11+
12+
test('guards recognize a disposition and reject anything else', () => {
13+
expect(isNativePathDisposition('pending')).toBe(true);
14+
expect(isNativePathDisposition('retired')).toBe(true);
15+
expect(isNativePathDisposition('deleted')).toBe(false);
16+
expect(isNativePathDisposition(undefined)).toBe(false);
17+
});
18+
});
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
/**
2+
* What may happen to the recorder's native artifact path — the file the recorder itself writes
3+
* (the `simctl` output, the device-side chunks, the media-library item, the browser's WebM) once a
4+
* recording's export is committed (ADR 0024 2.3). This is the second of the two facts a stop
5+
* answers, and it stays independent of the recorder observation: a recorder that never confirmed
6+
* leaves its path `pending` even when the export is playable, and a `lost` identity says nothing
7+
* about who writes there now, so it never permits a deletion either.
8+
*
9+
* - `pending`: the backend has not proven the writer gone, so nothing may remove the path.
10+
* - `retirable`: the writer is proven gone; a fenced retirement is still owed.
11+
* - `retired`: retirement succeeded or the backend verified the artifact is absent.
12+
*
13+
* The bullets define the vocabulary; they are not a claim that anything emits each state. Today's
14+
* producers answer `retirable` for an Apple runner artifact left on the device and `retired` for an
15+
* Android recording whose chunks the device no longer shows or a HarmonyOS recording whose removals
16+
* were verified. A backend whose recorder writes the served export itself omits the field. `pending`
17+
* is declared ahead of the step that reports a recorder nobody proved gone, and no stop emits it yet.
18+
*/
19+
export const NATIVE_PATH_DISPOSITION_VALUES = ['pending', 'retirable', 'retired'] as const;
20+
21+
export type NativePathDisposition = (typeof NATIVE_PATH_DISPOSITION_VALUES)[number];
22+
23+
export function isNativePathDisposition(value: unknown): value is NativePathDisposition {
24+
return NATIVE_PATH_DISPOSITION_VALUES.some((disposition) => disposition === value);
25+
}
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { describe, expect, test } from 'vitest';
2+
import { RECORDER_OBSERVATION_VALUES, isStopObservation } from './recording-stop-observation.ts';
3+
4+
describe('recording stop observation', () => {
5+
test('names the three words a backend can report', () => {
6+
expect(RECORDER_OBSERVATION_VALUES).toEqual(['confirmed', 'unconfirmed', 'lost']);
7+
});
8+
9+
test('accepts a confirmed recorder with no reason and a refused one with its own reason', () => {
10+
expect(isStopObservation({ recorder: 'confirmed' })).toBe(true);
11+
expect(isStopObservation({ recorder: 'unconfirmed', why: 'identity-unreadable' })).toBe(true);
12+
expect(isStopObservation({ recorder: 'unconfirmed', why: 'no-exit-in-budget' })).toBe(true);
13+
expect(isStopObservation({ recorder: 'lost', why: 'identity-not-ours' })).toBe(true);
14+
expect(isStopObservation({ recorder: 'lost', why: 'owner-session-lost' })).toBe(true);
15+
expect(isStopObservation({ recorder: 'lost', why: 'native-artifact-absent' })).toBe(true);
16+
});
17+
18+
test('rejects a word or a reason a backend could never have reported', () => {
19+
expect(isStopObservation({ recorder: 'confirmed', why: 'no-exit-in-budget' })).toBe(false);
20+
expect(isStopObservation({ recorder: 'unconfirmed' })).toBe(false);
21+
expect(isStopObservation({ recorder: 'lost', why: 'identity-unreadable' })).toBe(false);
22+
expect(isStopObservation({ recorder: 'unconfirmed', why: 'identity-not-ours' })).toBe(false);
23+
expect(isStopObservation({ recorder: 'gone' })).toBe(false);
24+
expect(isStopObservation('confirmed')).toBe(false);
25+
expect(isStopObservation(undefined)).toBe(false);
26+
});
27+
});
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
/**
2+
* What a recording backend observed about its recorder when it was asked to stop
3+
* (ADR 0024 2.2). This is the first of the two facts a stop answers; whether a playable export
4+
* exists is answered separately by the export itself.
5+
*
6+
* The observation describes what was observed, never what identity proved. An identity probe that
7+
* could not be read is `unconfirmed`, not `lost`, and a proven mismatch is `lost` even though the
8+
* same probe found nothing.
9+
*
10+
* The variants below define the vocabulary; they are not a claim that anything emits each one.
11+
* Today's producers answer `confirmed` — an exited `simctl` process, an acknowledged runner stop,
12+
* Android recorders proven gone, a stopped HarmonyOS toggle, a stopped browser provider — and `lost`
13+
* with `owner-session-lost` for an Apple recording whose session was invalidated. The unconfirmed
14+
* reasons and the two identity reasons for `lost` arrive with the steps that gain the probe or the
15+
* retry they describe; until a step owns one, a stop that cannot prove its recorder gone reports
16+
* that as its own error rather than serving an export labelled `unconfirmed`.
17+
*/
18+
export const RECORDER_OBSERVATION_VALUES = ['confirmed', 'unconfirmed', 'lost'] as const;
19+
20+
/** The one word every backend reports, and the word the `record stop` response serves. */
21+
export type RecorderObservation = (typeof RECORDER_OBSERVATION_VALUES)[number];
22+
23+
/** The recorder was asked to stop and termination never became a fact. */
24+
const RECORDER_UNCONFIRMED_REASONS = ['identity-unreadable', 'no-exit-in-budget'] as const;
25+
26+
export type RecorderUnconfirmedReason = (typeof RECORDER_UNCONFIRMED_REASONS)[number];
27+
28+
/** The recorder the backend was told to stop is not the one it started, or no longer holds it. */
29+
const RECORDER_LOST_REASONS = [
30+
'identity-not-ours',
31+
'owner-session-lost',
32+
'native-artifact-absent',
33+
] as const;
34+
35+
export type RecorderLostReason = (typeof RECORDER_LOST_REASONS)[number];
36+
37+
export type StopObservation =
38+
/** The recorder exited or acknowledged the stop meant for this recording. */
39+
| Readonly<{ recorder: 'confirmed' }>
40+
/** A probe was unreadable, or the recorder was signalled and no exit arrived in the budget. */
41+
| Readonly<{ recorder: 'unconfirmed'; why: RecorderUnconfirmedReason }>
42+
/** Identity proved the writer is someone else, or the session holding it died. */
43+
| Readonly<{ recorder: 'lost'; why: RecorderLostReason }>;
44+
45+
/** Validates an observation that came back from persisted JSON, where a mismatched reason is possible. */
46+
export function isStopObservation(value: unknown): value is StopObservation {
47+
if (typeof value !== 'object' || value === null) return false;
48+
const candidate: { recorder?: unknown; why?: unknown } = value;
49+
if (!RECORDER_OBSERVATION_VALUES.some((word) => word === candidate.recorder)) return false;
50+
if (candidate.recorder === 'confirmed') return candidate.why === undefined;
51+
const reasons: readonly string[] =
52+
candidate.recorder === 'unconfirmed' ? RECORDER_UNCONFIRMED_REASONS : RECORDER_LOST_REASONS;
53+
return reasons.some((reason) => reason === candidate.why);
54+
}

‎packages/contracts/src/recording.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
import type { DaemonArtifact } from '@agent-device/kernel/contracts';
2+
import type { RecorderObservation } from './recording-stop-observation.ts';
3+
import type { NativePathDisposition } from './recording-native-path.ts';
24
import type { RecordingScope } from './recording-scope.ts';
35

46
export type RecordingAppIdentity = {
@@ -28,6 +30,20 @@ export type RecordingStopCommandResult = {
2830
activeSessionApp?: RecordingAppIdentity;
2931
durationMs: number;
3032
capturedDurationMs?: number;
33+
/**
34+
* What the recorder itself was observed doing when the stop was carried out (ADR 0024 2.2).
35+
* `confirmed` is the ordinary answer; `unconfirmed` and `lost` say the export was served without
36+
* proof that the recorder terminated, which is a disclosure and not a failure. Absent on a
37+
* response replayed from a manifest written before this field existed.
38+
*/
39+
recorder?: RecorderObservation;
40+
/**
41+
* What the recorder's native artifact path was left as (ADR 0024 2.3): `retired` once the backend
42+
* removed it and verified that, `retirable` when the writer is proven gone and a fenced removal is
43+
* still owed, `pending` when nothing proves the writer gone yet. Absent when the backend has no
44+
* native path of its own to keep.
45+
*/
46+
nativePathDisposition?: NativePathDisposition;
3147
showTouches: boolean;
3248
warning?: string;
3349
overlayWarning?: string;

‎packages/contracts/src/screen-recording-runtime.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import type { GestureReferenceFrame, ScrollDirection } from './scroll-gesture.ts';
22
import type { RecordingAppIdentity } from './recording.ts';
3+
import type { StopObservation } from './recording-stop-observation.ts';
4+
import type { NativePathDisposition } from './recording-native-path.ts';
35
import type { RecordingExportQuality } from './recording-export-quality.ts';
46
import type { RecordingScope } from './recording-scope.ts';
57
import type { CleanupOutcome, LiveResourceHandle, ReattachOutcome } from './durable-resource.ts';
@@ -93,6 +95,17 @@ export type ScreenRecordingCompletion = Readonly<{
9395
* timelines, which excludes whatever a chunk handover cost.
9496
*/
9597
capturedDurationMs?: number;
98+
/**
99+
* What the backend observed about its recorder when it was asked to stop (ADR 0024 2.2). The
100+
* public response serves only its `recorder` word; the reason stays here, beside the export it
101+
* explains, where recovery and diagnostics read it.
102+
*/
103+
stopObservation?: StopObservation;
104+
/**
105+
* What became of the recorder's own artifact path (ADR 0024 2.3). Recorded at commit, and the
106+
* manifest keeps its native path and recorder identity until this reaches `retired`.
107+
*/
108+
nativePathDisposition?: NativePathDisposition;
96109
scope: RecordingScope;
97110
showTouches: boolean;
98111
recordOnlySession: boolean;

0 commit comments

Comments
 (0)