Skip to content

Commit d732e47

Browse files
authored
refactor(capture-kit): one provider app-log owner for polling, envelope, and reattach (#3620)
* refactor(capture-kit): one provider app-log owner for polling, envelope, and reattach (#2616) Limrun's app-log poller, durable envelope, reattach/cleanup, doctor, and app-log-backed network dump move into @agent-device/capture-kit/provider-app-log, parameterized by a reader port. Providers keep descriptor codecs, reader acquisition, reconnect, and device matching. The poller now advances its tail only after the output write succeeds, so a failed write is retried on the next poll instead of dropping that delta. * chore(gates): declare the capture-kit provider-app-log subpath Exports map entry and the R11 capture-kit export enumeration.
1 parent 64101c7 commit d732e47

15 files changed

Lines changed: 986 additions & 473 deletions

‎packages/capture-kit/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,10 @@
166166
"types": "./src/post-gesture-stability.ts",
167167
"default": "./src/post-gesture-stability.ts"
168168
},
169+
"./provider-app-log": {
170+
"types": "./src/provider-app-log.ts",
171+
"default": "./src/provider-app-log.ts"
172+
},
169173
"./quality-warnings": {
170174
"types": "./src/snapshot/snapshot-presentation/quality-warnings.ts",
171175
"default": "./src/snapshot/snapshot-presentation/quality-warnings.ts"

‎packages/capture-kit/src/app-log-session-artifacts.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ export type AppLogArtifactPaths = Readonly<{
77
}>;
88

99
export function appLogSessionArtifactsMatch(
10-
host: AppLogRuntimeHost,
10+
host: Pick<AppLogRuntimeHost, 'artifacts'>,
1111
sessionId: string,
1212
paths: AppLogArtifactPaths,
1313
): boolean {
@@ -19,7 +19,7 @@ export function appLogSessionArtifactsMatch(
1919
}
2020

2121
export function assertAppLogSessionArtifacts(
22-
host: AppLogRuntimeHost,
22+
host: Pick<AppLogRuntimeHost, 'artifacts'>,
2323
input: AppLogStartInput,
2424
): void {
2525
if (appLogSessionArtifactsMatch(host, input.sessionId, input)) return;
Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
import { describe, expect, test, vi } from 'vitest';
2+
import {
3+
startProviderAppLogPoller,
4+
type ProviderAppLogPollerOptions,
5+
type ProviderAppLogReader,
6+
} from './provider-app-log-poller.ts';
7+
8+
describe('provider app-log poller', () => {
9+
test('deduplicates the persisted tail and stops before disposing its resources', async () => {
10+
const sleeps = deferredSleeps();
11+
const writes: string[] = [];
12+
let outputDisposed = false;
13+
let readerDisposed = false;
14+
const reader = providerReader({
15+
readLogs: vi.fn(async () => 'old line\nshared\nnew line\n'),
16+
[Symbol.asyncDispose]: async () => {
17+
readerDisposed = true;
18+
},
19+
});
20+
const handle = await startProviderAppLogPoller(
21+
pollerOptions(reader, {
22+
existingTail: 'old line\nshared\n[agent-device][mark][time] checkpoint\n',
23+
writes,
24+
sleeps,
25+
onOutputDispose: () => {
26+
outputDisposed = true;
27+
},
28+
}),
29+
);
30+
await vi.waitFor(() => expect(writes).toEqual(['new line\n']));
31+
32+
const finishing = handle.finish();
33+
expect(readerDisposed).toBe(false);
34+
expect(outputDisposed).toBe(false);
35+
sleeps.resolveNext(1_000);
36+
await expect(finishing).resolves.toEqual({
37+
status: 'completed',
38+
result: { backend: 'ios-simulator', outputPath: '/sessions/one/app.log', completedAt: 100 },
39+
});
40+
expect(reader.readLogs).toHaveBeenCalledTimes(1);
41+
expect(readerDisposed).toBe(true);
42+
expect(outputDisposed).toBe(true);
43+
});
44+
45+
test.each(['readTail', 'openAppend'] as const)(
46+
'rolls back the reader when %s fails during acquisition',
47+
async (failure) => {
48+
const dispose = vi.fn(async () => {});
49+
const reader = providerReader({ [Symbol.asyncDispose]: dispose });
50+
await expect(
51+
startProviderAppLogPoller(
52+
pollerOptions(reader, { writes: [], sleeps: deferredSleeps(), failure }),
53+
),
54+
).rejects.toThrow(`${failure === 'readTail' ? 'tail' : 'open'} failed`);
55+
expect(dispose).toHaveBeenCalledOnce();
56+
},
57+
);
58+
59+
test('uses linear overlap matching for a near-limit tail without overlap', async () => {
60+
const sleeps = deferredSleeps();
61+
const writes: string[] = [];
62+
const reader = providerReader({ readLogs: async () => `${'b'.repeat(240_000)}\n` });
63+
const handle = await startProviderAppLogPoller(
64+
pollerOptions(reader, { existingTail: `${'a'.repeat(240_000)}\n`, writes, sleeps }),
65+
);
66+
await vi.waitFor(() => expect(writes[0]?.length).toBe(240_001));
67+
const finishing = handle.finish();
68+
sleeps.resolveNext(1_000);
69+
await finishing;
70+
});
71+
72+
test('keeps a delta whose write failed and writes it on the next poll', async () => {
73+
const sleeps = deferredSleeps();
74+
const writes: string[] = [];
75+
let failNextWrite = true;
76+
const reader = providerReader({ readLogs: async () => 'first\n' });
77+
const handle = await startProviderAppLogPoller(
78+
pollerOptions(reader, {
79+
writes,
80+
sleeps,
81+
write: (chunk) => {
82+
if (failNextWrite) {
83+
failNextWrite = false;
84+
throw new Error('disk full');
85+
}
86+
writes.push(chunk);
87+
},
88+
}),
89+
);
90+
await vi.waitFor(() => expect(sleeps.hasPending(1_000)).toBe(true));
91+
expect(handle.inspect().state).toBe('recovering');
92+
expect(writes).toEqual([]);
93+
94+
sleeps.resolveNext(1_000);
95+
await vi.waitFor(() => expect(writes).toEqual(['first\n']));
96+
expect(handle.inspect().state).toBe('active');
97+
const finishing = handle.finish();
98+
sleeps.resolveNext(1_000);
99+
await finishing;
100+
});
101+
102+
test('recovers after a rejected read and resumes appending', async () => {
103+
const sleeps = deferredSleeps();
104+
const writes: string[] = [];
105+
const readLogs = vi
106+
.fn<ProviderAppLogReader['readLogs']>()
107+
.mockRejectedValueOnce(new Error('socket closed'))
108+
.mockResolvedValue('line\n');
109+
const handle = await startProviderAppLogPoller(
110+
pollerOptions(providerReader({ readLogs }), { writes, sleeps }),
111+
);
112+
await vi.waitFor(() => expect(handle.inspect().state).toBe('recovering'));
113+
114+
sleeps.resolveNext(1_000);
115+
await vi.waitFor(() => expect(writes).toEqual(['line\n']));
116+
expect(handle.inspect().state).toBe('active');
117+
const finishing = handle.finish();
118+
sleeps.resolveNext(1_000);
119+
await finishing;
120+
});
121+
122+
test('still disposes the output when reader cleanup rejects', async () => {
123+
const sleeps = deferredSleeps();
124+
let outputDisposed = false;
125+
const reader = providerReader({
126+
[Symbol.asyncDispose]: async () => {
127+
throw new Error('reader cleanup failed');
128+
},
129+
});
130+
const handle = await startProviderAppLogPoller(
131+
pollerOptions(reader, {
132+
writes: [],
133+
sleeps,
134+
onOutputDispose: () => {
135+
outputDisposed = true;
136+
},
137+
}),
138+
);
139+
await vi.waitFor(() => expect(sleeps.hasPending(1_000)).toBe(true));
140+
const finishing = handle.finish();
141+
sleeps.resolveNext(1_000);
142+
await expect(finishing).resolves.toEqual({
143+
status: 'cleanup-pending',
144+
reason: 'transport-failed',
145+
message: 'Example app-log cleanup did not settle every owned resource',
146+
});
147+
expect(outputDisposed).toBe(true);
148+
expect(handle.inspect().state).toBe('failed');
149+
});
150+
151+
test('abandons a read that ignores its signal once the budget elapses', async () => {
152+
const sleeps = deferredSleeps();
153+
let readerDisposed = false;
154+
let readSignal: AbortSignal | undefined;
155+
const reader = providerReader({
156+
readLogs: vi.fn(async (_appBundleId, _lineLimit, signal) => {
157+
readSignal = signal;
158+
return await new Promise<string>(() => {});
159+
}),
160+
[Symbol.asyncDispose]: async () => {
161+
readerDisposed = true;
162+
},
163+
});
164+
const handle = await startProviderAppLogPoller(
165+
pollerOptions(reader, { writes: [], sleeps, backend: 'android' }),
166+
);
167+
const finishing = handle.finish();
168+
expect(readerDisposed).toBe(false);
169+
sleeps.resolveNext(5_000);
170+
await finishing;
171+
expect(reader.readLogs).toHaveBeenCalledTimes(1);
172+
expect(reader.readLogs).toHaveBeenCalledWith('com.example.app', 1_000, expect.any(AbortSignal));
173+
expect(readSignal?.aborted).toBe(true);
174+
expect(readerDisposed).toBe(true);
175+
});
176+
177+
test('keeps the rejection of an abandoned read handled', async () => {
178+
const sleeps = deferredSleeps();
179+
let rejectRead!: (error: Error) => void;
180+
const reader = providerReader({
181+
readLogs: async () =>
182+
await new Promise<string>((_resolve, reject) => {
183+
rejectRead = reject;
184+
}),
185+
});
186+
const handle = await startProviderAppLogPoller(pollerOptions(reader, { writes: [], sleeps }));
187+
await vi.waitFor(() => expect(sleeps.hasPending(5_000)).toBe(true));
188+
sleeps.resolveNext(5_000);
189+
await vi.waitFor(() => expect(handle.inspect().state).toBe('failed'));
190+
rejectRead(new Error('late provider failure'));
191+
await expect(handle.finish()).resolves.toMatchObject({ status: 'completed' });
192+
});
193+
194+
test('memoizes finish so resources are disposed once', async () => {
195+
const sleeps = deferredSleeps();
196+
const dispose = vi.fn(async () => {});
197+
const handle = await startProviderAppLogPoller(
198+
pollerOptions(providerReader({ [Symbol.asyncDispose]: dispose }), { writes: [], sleeps }),
199+
);
200+
await vi.waitFor(() => expect(sleeps.hasPending(1_000)).toBe(true));
201+
const first = handle.finish();
202+
const second = handle.finish();
203+
sleeps.resolveNext(1_000);
204+
expect(await second).toEqual(await first);
205+
expect(dispose).toHaveBeenCalledOnce();
206+
});
207+
});
208+
209+
function providerReader(overrides: Partial<ProviderAppLogReader> = {}): ProviderAppLogReader {
210+
return {
211+
readLogs: async () => '',
212+
[Symbol.asyncDispose]: async () => {},
213+
...overrides,
214+
};
215+
}
216+
217+
function pollerOptions(
218+
reader: ProviderAppLogReader,
219+
options: {
220+
existingTail?: string;
221+
writes: string[];
222+
sleeps: ReturnType<typeof deferredSleeps>;
223+
write?: (chunk: string) => void;
224+
onOutputDispose?: () => void;
225+
failure?: 'readTail' | 'openAppend';
226+
backend?: ProviderAppLogPollerOptions['backend'];
227+
},
228+
): ProviderAppLogPollerOptions {
229+
return {
230+
host: {
231+
outputs: {
232+
readTail: async () => {
233+
if (options.failure === 'readTail') throw new Error('tail failed');
234+
return options.existingTail ?? '';
235+
},
236+
openAppend: async () => {
237+
if (options.failure === 'openAppend') throw new Error('open failed');
238+
return {
239+
write: async (chunk) => {
240+
if (options.write) options.write(String(chunk));
241+
else options.writes.push(String(chunk));
242+
},
243+
[Symbol.asyncDispose]: async () => options.onOutputDispose?.(),
244+
};
245+
},
246+
},
247+
clock: {
248+
now: () => 100,
249+
sleep: async (milliseconds) => await options.sleeps.wait(milliseconds),
250+
},
251+
},
252+
provider: 'Example',
253+
backend: options.backend ?? 'ios-simulator',
254+
reader,
255+
appBundleId: 'com.example.app',
256+
outputPath: '/sessions/one/app.log',
257+
};
258+
}
259+
260+
function deferredSleeps() {
261+
const pending: Array<{ milliseconds: number; resolve: () => void }> = [];
262+
return {
263+
wait: async (milliseconds: number) =>
264+
await new Promise<void>((resolve) => pending.push({ milliseconds, resolve })),
265+
resolveNext: (milliseconds: number) => {
266+
const index = pending.findIndex((entry) => entry.milliseconds === milliseconds);
267+
if (index < 0) throw new Error(`No ${milliseconds}ms sleep is pending`);
268+
pending.splice(index, 1)[0]?.resolve();
269+
},
270+
hasPending: (milliseconds: number) =>
271+
pending.some((entry) => entry.milliseconds === milliseconds),
272+
};
273+
}

0 commit comments

Comments
 (0)