Skip to content

Commit 494f1c5

Browse files
thymikeeclaude
andauthored
Migrate audio probe to platform runtime with durable resource lifecycle (#2038)
* refactor(daemon): migrate audio onto the request-bound device runtime (R60) Wave 6 closure unit 1 of 2 for #1739. The audio probe leaves legacy execution for exact-owner runtime facts with the logs/record durable treatment: - contracts: audio-probe-runtime operations (audioProbeStart/Reattach/Cleanup for the durable host capture, audioProbeQuery for the stateless web page probe), audio-runtime-plan action-selected uses + shared positional grammar, audio-probe-runtime-host seams; two new required unavailable cells. - capture-kit: one shared host-capture implementation (descriptor codec v1 with cleanup-only recovery, start pipeline waiting on the sampler's first status publication, live handle, exact-identity recovery operations) used by both darwin-hosted owners. - owners: apple and android state their exact capture cells (macOS host only; the legacy bucket's physical-iOS over-claim becomes a stated refusal), web owns the page probe, all other families and both providers state refusals. - daemon: audio-probe.resource.json envelope via the DurableCaptureResource coordinator, fence-minting admission ledger, session slot becomes the neutral handle+envelope pair (store-owned under R7), teardown/close finish through the coordinator, startup recovery registered in the device-claim reconciler; the handler admits by facts inspection and binds once per plan. - deleted: the capability bucket, the WEB_QUERY_COMMANDS graft and its matrix pass, both supportsByDefault closures, src/daemon/audio-probe.ts, src/platforms/audio-probe-backend.ts, and the macOS backend shim. - gates: cutover row R60 (durable tier, lifecycle proof on the session slot), R7/R11 baselines moved for the slot reclassification and new subpaths. Known parity delta, itemized: status/stop with no active probe now answers without backend-specific notes (the daemon no longer knows a backend before a capture starts); the wire shape is otherwise unchanged. Co-Authored-By: Claude <[email protected]> * refactor(daemon): doctor becomes host-scoped execution behind the host-diagnostics surface (R62) Wave 6 closure unit 2 of 2 for #1739, carrying the ADR-level discriminator decision the pre-unit record names: CommandPlatformExecution gains { kind: 'host' } — host-scoped diagnostics contributed by platform families through a neutral surface, binding no device runtime of its own. 'none' remains barred as a migration target; doctor's device legs already ride the migrated inventory gateway, facts inspection, and the apps unit's use. - contracts: host-diagnostics facet (toolchain/device/ambient/warmup methods over the existing DoctorCheck vocabulary, a per-call context carrying the neutral inputs, and an opaque provider transport override the one owning family narrows back); the discriminator assert, entry gate (host is held to the same no-bucket rule as none), and error text extend to the new kind. - probes move to their owning families: apple (xcodebuild/xcode-select + runner-cache warmup), android (adb/SDK/license toolchain, Metro reverse, orphaned test-IME), harmonyos (hdc), vega (tool provider + VVD inventory read via the context), web (managed browser census); one shared first-line probe helper. Wire shapes and check ids are byte-identical. - composition: createHostDiagnostics with per-family lazy loading, injected from daemon-runtime through router/chain/session params — the daemon never imports the composition root, so no transitive platform edge returns. - daemon: session-doctor.ts keeps orchestration only; its six platform imports and the three probe-owning modules (session-doctor-{toolchain,android,web}.ts) are deleted. - gates: HostCutover row variant with a gateway-identity proof (R17's shape); R62 row; the descriptor-row completeness test now mandates rows for host descriptors; ADR 0019 rules-at-a-glance amended. Co-Authored-By: Claude <[email protected]> * refactor(audio): fold the per-family probe factories into one capture-kit operation set Post-migration fallow pass over R60/R62: apple and android carried byte-identical audio-probe operation factories, so the shared createHostAudioProbeCaptureOperations now lives in capture-kit and both bind arms call it directly; the family files keep only their stated capture facts. Also un-exports the plan/recovery symbols nothing consumes anymore, splits the durable-descriptor field validation out of the decoder, names the Linux audio refusal by its file's convention, and drops a stale session-doctor-web mock from the relocated doctor test. Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01Cd7fCKcxuDU3KrXF4MF9rN * fix(coverage): repoint platform audio/doctor coverage claims at the migrated evidence The R60/R62 rewrite renamed the daemon audio contract tests and moved the web doctor suite, which broke the macos-coverage smoke gate on CI and five sibling coverage claims that only fail on non-darwin hosts. Repoints the macOS, web, and iOS-simulator manifests at the surviving tests (adding an iOS-simulator start contract the manifest already named), converts the Linux audio row from capability-denial to a fact-owned contract backed by new stated-refusal assertions in the Linux runtime denominator test, and retires the darwin-dependent capability special-cases: audio admission is owned by the exact-owner runtime fact now, not the catalog. Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01Cd7fCKcxuDU3KrXF4MF9rN * fix(daemon): forward hostDiagnostics through the session command route Adversarial review of the R62 cutover found the wiring gap that broke every doctor request served through the daemon: handleSessionCommands re-composed its handler params without the hostDiagnostics gateway, so requireHostDiagnostics always threw. Forwards it, composes createHostDiagnostics() in the provider-scenario harness the same way the daemon runtime does (all nine doctor integration tests pass again), merges a duplicate test import that failed lint, applies oxfmt to the files the branch left unformatted, and trims blank-line residue from a deleted capabilities test. Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01Cd7fCKcxuDU3KrXF4MF9rN * fix(audio): refuse to publish a capture without an exact process identity Review P1 on the R60 unit: start permitted resolveManagedProcessIdentity to yield no marker, recovery then mapped the markerless descriptor to missing, read a possibly in-progress status file as completed, and terminalized the durable resource without proving or terminating the child. The marker is now required end to end: start terminates the helper and fails when the process exposes no identity, the descriptor codec rejects markerless bodies so a foreign or corrupted record routes to manual recovery instead of a guessed outcome, and a planted-red regression pins that a markerless record with a live status file is never read as completed or missing. Also splits the capture-kit audio-probe module along its concerns (descriptor codec / status reads / cleanup-only recovery / live-process owner) per the same review, moving the eager-closure budget rows the three new files cost. Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01Cd7fCKcxuDU3KrXF4MF9rN * fix(audio): let timed probes complete and never adopt a stale status file Live exact-head evidence on macOS surfaced two lifecycle defects: - The helper's runAudioProbe parked the CLI's main thread in a semaphore while an unstructured Task ran the capture loop; with no run loop ever spinning in the one-shot process, the loop stalled at its first Task.sleep suspension, so every timed probe froze after its first bucket and never completed on its own. The probe is now fully synchronous: ScreenCaptureKit's completion-handler APIs bridged through semaphores (the pattern the helper's screenshot path already uses in production) and a plain Thread.sleep cadence loop. - startHostAudioProbe accepted a pre-existing audio-probe.json, so restarting in a session that had already run a probe returned the previous run's snapshot as the new probe's first status. The status path is cleared before the spawn — the previous handle's finish() has already terminated and awaited its process, so any file observed after the spawn was written by the new helper. A planted-red regression pins that a stale file is neither adopted nor left behind. Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01Cd7fCKcxuDU3KrXF4MF9rN * test(audio): complete runtime host fixtures * fix(audio): surface helper death after a running checkpoint instead of completing it Review P1 on the live-evidence pass: the live handle discarded the helper's terminal result, so a sampler that died after publishing a running checkpoint read as running forever and stop fabricated a normal stopped completion; marker-missing recovery compounded it by finalizing any persisted status — a running checkpoint included — as completed. The handle now observes process.wait: a non-terminal status file plus an observed exit fails status and stop with the helper's exit detail, so the durable coordinator records the failed terminal transition and the record resolves through descriptor cleanup rather than a fabricated result. Recovery treats only a terminal stopped publication as a completion; a running checkpoint with the exact PID gone reports missing, which terminalizes the envelope as already-missing with no completion metadata. Planted-red regressions cover both: the live handle with a running checkpoint plus child exit, and a daemon-restart recovery over an orphaned running checkpoint. Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01Cd7fCKcxuDU3KrXF4MF9rN --------- Co-authored-by: Claude <[email protected]>
1 parent b40debf commit 494f1c5

110 files changed

Lines changed: 3587 additions & 1515 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apple/macos-helper/Sources/AgentDeviceMacOSHelper/AudioProbe.swift‎

Lines changed: 35 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -211,43 +211,28 @@ extension AudioProbeBucket {
211211
}
212212
}
213213

214+
// This one-shot helper keeps ScreenCaptureKit callbacks and bucket cadence synchronous.
214215
func runAudioProbe(durationMs: Int, bucketMs: Int, outPath: String) throws -> AudioProbeResponse {
215216
guard #available(macOS 13.0, *) else {
216217
throw HelperError.commandFailed("audio probe requires macOS 13 or newer")
217218
}
218-
let semaphore = DispatchSemaphore(value: 0)
219-
var response: AudioProbeResponse?
220-
var runError: Error?
221-
Task {
222-
do {
223-
response = try await runAudioProbeAsync(durationMs: durationMs, bucketMs: bucketMs, outPath: outPath)
224-
} catch {
225-
runError = error
226-
}
227-
semaphore.signal()
228-
}
229-
semaphore.wait()
230-
if let runError {
231-
throw runError
232-
}
233-
guard let response else {
234-
throw HelperError.commandFailed("audio probe failed")
235-
}
236-
return response
237-
}
238219

239-
@available(macOS 13.0, *)
240-
private func runAudioProbeAsync(durationMs: Int, bucketMs: Int, outPath: String) async throws -> AudioProbeResponse {
241-
let content: SCShareableContent
242-
do {
243-
content = try await SCShareableContent.current
244-
} catch {
220+
let contentSemaphore = DispatchSemaphore(value: 0)
221+
var contentResult: SCShareableContent?
222+
var contentError: Error?
223+
SCShareableContent.getWithCompletionHandler { content, error in
224+
contentResult = content
225+
contentError = error
226+
contentSemaphore.signal()
227+
}
228+
contentSemaphore.wait()
229+
if let contentError {
245230
throw HelperError.commandFailed(
246231
"audio probe requires Screen Recording permission on macOS",
247-
details: ["permission": "screen-recording", "error": error.localizedDescription]
232+
details: ["permission": "screen-recording", "error": contentError.localizedDescription]
248233
)
249234
}
250-
guard let display = content.displays.first else {
235+
guard let display = contentResult?.displays.first else {
251236
throw HelperError.commandFailed("audio probe could not resolve a macOS display")
252237
}
253238

@@ -267,18 +252,35 @@ private func runAudioProbeAsync(durationMs: Int, bucketMs: Int, outPath: String)
267252
let stream = SCStream(filter: filter, configuration: configuration, delegate: nil)
268253
let queue = DispatchQueue(label: "com.callstack.agent-device.audio-probe")
269254
try stream.addStreamOutput(output, type: .audio, sampleHandlerQueue: queue)
270-
try await stream.startCapture()
255+
256+
let startSemaphore = DispatchSemaphore(value: 0)
257+
var startError: Error?
258+
stream.startCapture { error in
259+
startError = error
260+
startSemaphore.signal()
261+
}
262+
startSemaphore.wait()
263+
if let startError {
264+
throw HelperError.commandFailed(
265+
"audio probe could not start the ScreenCaptureKit stream",
266+
details: ["error": startError.localizedDescription]
267+
)
268+
}
271269
try writer.flushRunning()
272270

273271
let deadline = Date().addingTimeInterval(Double(durationMs) / 1000)
274272
while Date() < deadline {
275-
let remainingMs = Int(deadline.timeIntervalSinceNow * 1000)
276-
let sleepMs = max(1, min(bucketMs, remainingMs))
277-
try await Task.sleep(nanoseconds: UInt64(sleepMs) * 1_000_000)
273+
let remainingMs = deadline.timeIntervalSinceNow * 1000
274+
let sleepMs = max(1, min(Double(bucketMs), remainingMs))
275+
Thread.sleep(forTimeInterval: sleepMs / 1000)
278276
try writer.flushRunning()
279277
}
280278

281-
try await stream.stopCapture()
279+
let stopSemaphore = DispatchSemaphore(value: 0)
280+
stream.stopCapture { _ in
281+
stopSemaphore.signal()
282+
}
283+
stopSemaphore.wait()
282284
try writer.finish(reason: "completed")
283285
let data = try Data(contentsOf: URL(fileURLWithPath: outPath))
284286
return try JSONDecoder().decode(AudioProbeResponse.self, from: data)

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,12 @@ those descriptors or authorize a second local/provider chooser.
5757
Concrete platform process objects never cross the seam.
5858
- The migration unit is one command descriptor across its full existing denominator: every inventory
5959
source or every supported device-runtime cell. A descriptor has exactly one explicitly declared
60-
platform-execution shape at every committed state — `none`, legacy, inventory-backed, or
61-
device-runtime-backed — and a migrated command has no legacy execution fallback. `none` declares
62-
the absence of platform execution and is never a migration target or source.
60+
platform-execution shape at every committed state — `none`, legacy, host-diagnostic, inventory-backed,
61+
or device-runtime-backed — and a migrated command has no legacy execution fallback. `none` declares
62+
the absence of platform execution and is never a migration target or source. `host` declares
63+
host-scoped diagnostics: platform families contribute host toolchain and environment probes through
64+
the neutral host-diagnostics surface, the command binds no device runtime as its own execution
65+
shape, and any device-runtime leg rides an already migrated command's declared use.
6366
- Broader adoption pauses after the first real slices. Evidence records one decision: continue,
6467
revise the seam and rerun the checkpoint, or stop with every landed command still coherent.
6568
- Post-checkpoint units are move-dominated: platform mechanics leave root `src/` for platform
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
import { AUDIO_PROBE_RESOURCE_KIND } from '@agent-device/contracts/audio-probe-runtime';
2+
import type { AudioProbeSource } from '@agent-device/contracts/audio-probe-result';
3+
import type {
4+
DurableDescriptorCodec,
5+
ManagedProcessIdentity,
6+
} from '@agent-device/contracts/platform';
7+
8+
/**
9+
* Stable reconstruction coordinates for one host audio capture. The helper transport cannot
10+
* reconstruct live control after daemon loss, so recovery is declared cleanup-only: the marker
11+
* proves exact process identity for termination, and the status file still yields a completed
12+
* result when the run finished on its own. The marker is required — start refuses to publish a
13+
* capture it could not identify, and a stored record without one (foreign or corrupted) decodes
14+
* as invalid so cleanup routes it to manual recovery instead of guessing at the child's fate.
15+
*/
16+
export type HostAudioProbeDescriptor = Readonly<{
17+
backend: string;
18+
source: AudioProbeSource;
19+
sourceCount: number;
20+
notes: readonly string[];
21+
statusPath: string;
22+
startedAt: number;
23+
durationMs: number;
24+
bucketMs: number;
25+
marker: ManagedProcessIdentity;
26+
}>;
27+
28+
type HostAudioProbeDescriptorDecode = DurableDescriptorCodec<
29+
HostAudioProbeDescriptor,
30+
typeof AUDIO_PROBE_RESOURCE_KIND
31+
>['decode'];
32+
33+
const hasValidHostAudioProbeFields = (body: Record<string, unknown>): boolean =>
34+
isNonEmptyString(body.backend) &&
35+
(body.source === 'system-audio' || body.source === 'media-elements') &&
36+
isBoundedInteger(body.sourceCount, 0) &&
37+
isStringArray(body.notes) &&
38+
isNonEmptyString(body.statusPath) &&
39+
isBoundedInteger(body.startedAt, 1) &&
40+
isBoundedInteger(body.durationMs, 1) &&
41+
isBoundedInteger(body.bucketMs, 1);
42+
43+
const decodeHostAudioProbeDescriptor: HostAudioProbeDescriptorDecode = (body) => {
44+
const marker = hasValidHostAudioProbeFields(body) ? decodeMarker(body.marker) : 'invalid';
45+
if (marker === 'invalid') {
46+
return { status: 'invalid', message: 'Audio probe descriptor body is invalid' };
47+
}
48+
const decoded = body as unknown as Omit<HostAudioProbeDescriptor, 'notes' | 'marker'> & {
49+
notes: readonly string[];
50+
};
51+
return {
52+
status: 'decoded',
53+
descriptor: Object.freeze({
54+
backend: decoded.backend,
55+
source: decoded.source,
56+
sourceCount: decoded.sourceCount,
57+
notes: Object.freeze([...decoded.notes]),
58+
statusPath: decoded.statusPath,
59+
startedAt: decoded.startedAt,
60+
durationMs: decoded.durationMs,
61+
bucketMs: decoded.bucketMs,
62+
marker,
63+
}),
64+
};
65+
};
66+
67+
export const hostAudioProbeDescriptorCodec: DurableDescriptorCodec<
68+
HostAudioProbeDescriptor,
69+
typeof AUDIO_PROBE_RESOURCE_KIND
70+
> = Object.freeze({
71+
resourceKind: AUDIO_PROBE_RESOURCE_KIND,
72+
version: 1,
73+
encode: (descriptor: HostAudioProbeDescriptor) => ({
74+
...descriptor,
75+
notes: [...descriptor.notes],
76+
marker: { ...descriptor.marker },
77+
}),
78+
decode: decodeHostAudioProbeDescriptor,
79+
});
80+
81+
function decodeMarker(value: unknown): ManagedProcessIdentity | 'invalid' {
82+
if (typeof value !== 'object' || value === null) return 'invalid';
83+
const marker = value as Record<string, unknown>;
84+
if (!isBoundedInteger(marker.pid, 1)) return 'invalid';
85+
if (!isNonEmptyString(marker.startTime)) return 'invalid';
86+
if (!isNonEmptyString(marker.command)) return 'invalid';
87+
return Object.freeze({
88+
pid: marker.pid,
89+
startTime: marker.startTime,
90+
command: marker.command,
91+
});
92+
}
93+
94+
function isNonEmptyString(value: unknown): value is string {
95+
return typeof value === 'string' && value.length > 0;
96+
}
97+
98+
function isBoundedInteger(value: unknown, min: number): value is number {
99+
return typeof value === 'number' && Number.isInteger(value) && value >= min;
100+
}
101+
102+
function isStringArray(value: unknown): value is readonly string[] {
103+
return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
104+
}
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import type {
2+
AudioProbeCompletion,
3+
AudioProbeLiveHandle,
4+
AudioProbeReattachInput,
5+
} from '@agent-device/contracts/audio-probe-runtime';
6+
import type { HostSystemAudioCaptureHost } from '@agent-device/contracts/audio-probe-runtime-host';
7+
import type { CleanupOutcome, ReattachOutcome } from '@agent-device/contracts/durable-resource';
8+
import { hostAudioProbeDescriptorCodec } from './audio-probe-descriptor.ts';
9+
import { finalizeStatus, readStatusFile } from './audio-probe-status.ts';
10+
import { decodeDurableDescriptor } from './durable-descriptor-codec.ts';
11+
12+
/**
13+
* Cleanup-only recovery operations shared by every darwin-hosted owner family. Reattach never
14+
* reconstructs live control: a finished run reports `completed` from the status file, a live or
15+
* uncertain sampler stays `unreattachable` for descriptor cleanup to terminate by exact identity.
16+
* The descriptor codec requires the marker, so a markerless record never reaches the liveness
17+
* probe — it decodes as invalid and cleanup routes it to manual recovery rather than reading a
18+
* possibly in-progress status file as finished.
19+
*/
20+
export function createHostAudioProbeRecoveryOperations(params: {
21+
host: Pick<HostSystemAudioCaptureHost, 'inspectProcess' | 'terminateProcess'>;
22+
}): Readonly<{
23+
audioProbeReattach(
24+
input: AudioProbeReattachInput,
25+
): Promise<ReattachOutcome<AudioProbeLiveHandle, AudioProbeCompletion>>;
26+
audioProbeCleanup(input: AudioProbeReattachInput): Promise<CleanupOutcome>;
27+
}> {
28+
const { host } = params;
29+
return Object.freeze({
30+
audioProbeReattach: async (input) => {
31+
const decoded = decodeDurableDescriptor(input.envelope, hostAudioProbeDescriptorCodec);
32+
if (decoded.status !== 'decoded') return decoded;
33+
const descriptor = decoded.descriptor;
34+
const liveness = await host.inspectProcess(descriptor.marker);
35+
if (liveness === 'owned-alive') {
36+
return { status: 'unreattachable', reason: 'transport-not-reattachable' };
37+
}
38+
if (liveness === 'ownership-lost') {
39+
return { status: 'unreattachable', reason: 'ownership-fence-lost' };
40+
}
41+
const status = await readStatusFile(descriptor);
42+
// Only a terminal publication proves the run finished: a `running` checkpoint with the
43+
// child gone means the sampler died mid-capture, and its result is lost — never finalize
44+
// that checkpoint as a completion.
45+
if (status === undefined || status.state !== 'stopped') return { status: 'missing' };
46+
return {
47+
status: 'completed',
48+
result: finalizeStatus(descriptor, status, 'daemon-recovery'),
49+
};
50+
},
51+
audioProbeCleanup: async (input) => {
52+
const decoded = decodeDurableDescriptor(input.envelope, hostAudioProbeDescriptorCodec);
53+
if (decoded.status !== 'decoded') {
54+
return {
55+
status: 'cleanup-pending',
56+
reason: 'manual-recovery-required',
57+
message: decoded.message,
58+
};
59+
}
60+
const descriptor = decoded.descriptor;
61+
const liveness = await host.inspectProcess(descriptor.marker);
62+
if (liveness === 'ownership-lost') {
63+
return { status: 'cleanup-pending', reason: 'ownership-fence-lost' };
64+
}
65+
if (liveness === 'missing') return { status: 'already-missing' };
66+
const terminated = await host.terminateProcess(descriptor.marker);
67+
if (terminated === 'ownership-lost') {
68+
return { status: 'cleanup-pending', reason: 'ownership-fence-lost' };
69+
}
70+
return { status: terminated === 'terminated' ? 'cleaned' : 'already-missing' };
71+
},
72+
});
73+
}

0 commit comments

Comments
 (0)