Skip to content

Commit 8628e93

Browse files
thymikeeclaude
andauthored
feat(daemon): the runtime owns its state and never the process (#3772)
* feat(daemon): the runtime reports its shutdown instead of exiting the process startDaemonRuntime no longer calls process.exit or installs process handlers; src/daemon.ts owns signals, fatal errors and the exit code. close() is idempotent and resolves to a ShutdownReport. A runtime that fails during startup rolls back what it acquired. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * feat(daemon): per-runtime state for admission, resolution, artifacts, uploads and requests Provider admission, interactor resolution, artifact and upload tracking, resumable uploads, materialized paths, session-open locks and request cancellation are owned by the runtime instance instead of module scope. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * feat(daemon): per-runtime Apple runner state and a shared PNG worker The Apple runner's sessions, locks, recycle ledger and owner state belong to the daemon runtime that composed them. The PNG worker is held by every runtime that uses it and stops with the last one. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(daemon): drop re-exports nothing consumes yet Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(daemon): a failed shutdown step releases the rest, and dispose removes temp files Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(daemon): assert registration release on a failed close and share one removal helper Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(apple): scope start admissions, prep builds and bad-artifact marks to the runtime Closing one daemon runtime no longer retires another runtime's start admissions or signals its prep builds. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(move): keep daemon-runtime.ts under the size limit The runtime context, the per-runtime state list and the session teardown helpers move beside the other shutdown mechanics. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test: drop the empty daemon-runtime imports left by the runtime-state migration Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test: run the Limrun public HTTP test on the runtime shutdown contract Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(daemon): bound the runtime close and report work that outlives it Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(daemon): record abandoned requests in the daemon log and print unfinished shutdown work Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(daemon): report the close through one function the executable and its test share Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(android): own the snapshot-helper sessions, failed starts, retirements and shell probes per runtime Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(layering): enumerate the Android helper runtime-state subpath beside Apple's runner-owner Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(daemon): split the plugin close into its budget race and its report Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test: pin the close report beside the unfinished-work lines and drive the real entrypoint through a signal and an idle reap Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(android): keep the helper runtime state inside the adb module the helper already loads Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(android): export the per-runtime helper state from the adb host module, not a seventh subpath Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * Merge origin/main and adapt to the platform host migration * refactor(runtime): give the Android helper state to the root's slot store through the adb host port The Android package declares only its slot keys; the root keeps the one slot store (host-kit's defineRuntimeSlots) and binds its accessor into the host port. Daemon composition registers the same store's handle without loading the Android mechanics, and a composition test pins the registered handles. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(runtime): move Apple runner state and request-cancel onto defineRuntimeSlots The maintainer accepted the one-module eager-closure addition for host-kit's runtime-slots.ts, recorded as an approved closure addition (#3752) in the budget gate. The Android port drops the unused disposer parameter. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(daemon): keep the five per-runtime daemon states in defineRuntimeSlots slots Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(gate): count an approved closure addition only when it is not a rename of a base module, and require its reason Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(daemon): take RuntimeStateHandle from host-kit's runtime-slots, not the request re-export Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(android): define the helper runtime slots in the adb host module, as Apple does for the runner The root no longer keeps a store and binds its accessor into the adb host port. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(layering): let daemon composition import the adb host module for the helper runtime state Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(android): drop the host stub the shell-protocol probe test no longer needs Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent 2819be4 commit 8628e93

79 files changed

Lines changed: 2247 additions & 787 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.

‎packages/capture-kit/src/png-worker-client-unavailable.test.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,20 @@ import { PNG } from './png.ts';
55
test('a worker whose entry is missing is reported once and later registrations hear it', async () => {
66
vi.resetModules();
77
vi.doMock('./internal-entry.ts', () => ({ resolveInternalEntryModulePath: () => null }));
8-
const { decodePngAsync, prewarmPngWorker } = await import('./png-worker-client.ts');
8+
const { decodePngAsync, retainPngWorker } = await import('./png-worker-client.ts');
99
const png = PNG.sync.write(new PNG({ width: 1, height: 1 }));
1010
const first = vi.fn();
1111
const second = vi.fn();
1212

13-
prewarmPngWorker(first);
13+
const releaseFirst = retainPngWorker(first);
1414
const decoded = await decodePngAsync(png, 'fallback');
15-
prewarmPngWorker(second);
15+
const releaseSecond = retainPngWorker(second);
1616

1717
expect(decoded.width).toBe(1);
1818
expect(first.mock.calls).toEqual([[{ kind: 'entry-not-found' }]]);
1919
expect(second.mock.calls).toEqual([[{ kind: 'entry-not-found' }]]);
20+
await releaseFirst();
21+
await releaseSecond();
2022
vi.doUnmock('./internal-entry.ts');
2123
});
2224

@@ -39,10 +41,10 @@ test('a worker that dies after it started is reported once, and its pending job
3941
...(await importOriginal<typeof import('node:worker_threads')>()),
4042
Worker: FakeWorker,
4143
}));
42-
const { decodePngAsync, prewarmPngWorker } = await import('./png-worker-client.ts');
44+
const { decodePngAsync, retainPngWorker } = await import('./png-worker-client.ts');
4345
const png = PNG.sync.write(new PNG({ width: 1, height: 1 }));
4446
const unavailable = vi.fn();
45-
prewarmPngWorker(unavailable);
47+
const release = retainPngWorker(unavailable);
4648
expect(unavailable).not.toHaveBeenCalled();
4749

4850
const decoded = decodePngAsync(png, 'under-request');
@@ -53,5 +55,6 @@ test('a worker that dies after it started is reported once, and its pending job
5355

5456
expect((await decoded).width).toBe(1);
5557
expect(unavailable.mock.calls).toEqual([[{ kind: 'worker-error', detail: 'worker crashed' }]]);
58+
await release();
5659
vi.doUnmock('node:worker_threads');
5760
});

‎packages/capture-kit/src/png-worker-client.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
decodePngAsync,
1010
decodeScreenshotImageAsync,
1111
encodePngAsync,
12+
retainPngWorker,
1213
terminatePngWorker,
1314
transcodeScreenshotToPngAsync,
1415
} from './png-worker-client.ts';
@@ -225,3 +226,19 @@ test('decodeScreenshotImageAsync rejects a container it cannot read with the can
225226
},
226227
);
227228
});
229+
230+
test('the worker serves every holder and stops only when the last one lets go', async () => {
231+
const first = retainPngWorker(() => {});
232+
const second = retainPngWorker(() => {});
233+
const encoded = PNG.sync.write(buildPatternPng(5, 4, 2));
234+
235+
await first();
236+
await first();
237+
const stillServing = await runOnWorkerThread('decode after one release', () =>
238+
decodePngAsync(encoded, 'fixture'),
239+
);
240+
assert.equal(stillServing.width, 5);
241+
242+
await second();
243+
assert.equal(process.getActiveResourcesInfo().includes('MessagePort'), false);
244+
});

‎packages/capture-kit/src/png-worker-client.ts‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,15 +44,15 @@ type PendingJob = {
4444

4545
let worker: Worker | null = null;
4646
let unavailableReason: PngWorkerUnavailableReason | undefined;
47-
let reportUnavailable: ((reason: PngWorkerUnavailableReason) => void) | undefined;
47+
const unavailableSinks = new Set<(reason: PngWorkerUnavailableReason) => void>();
4848
let nextJobId = 0;
4949
const pendingJobs = new Map<number, PendingJob>();
5050

5151
/** Permanently degrades to the sync path; the daemon's sink hears each transition once. */
5252
function markWorkerUnavailable(reason: PngWorkerUnavailableReason): void {
5353
if (unavailableReason) return;
5454
unavailableReason = reason;
55-
reportUnavailable?.(reason);
55+
for (const sink of unavailableSinks) sink(reason);
5656
}
5757

5858
function handleWorkerMessage(message: PngWorkerResponse): void {
@@ -185,16 +185,29 @@ async function runPngJob<Kind extends PngWorkerJobKind>(
185185
}
186186
}
187187

188+
let pngWorkerHolds = 0;
189+
188190
/**
189-
* Daemon startup hook: spawns the worker before the first screenshot job and registers the daemon's
190-
* sink, which hears every later transition to unavailable once, inside or outside a request.
191+
* Daemon startup hook: spawns the worker before the first screenshot job and holds it for the
192+
* caller. The sink hears every transition to unavailable once, inside or outside a request, and
193+
* hears an earlier one at once. The worker is shared by every runtime in the process, so it stops
194+
* when the last holder lets go; the returned release is idempotent.
191195
*/
192-
export function prewarmPngWorker(
196+
export function retainPngWorker(
193197
onUnavailable: (reason: PngWorkerUnavailableReason) => void,
194-
): void {
195-
reportUnavailable = onUnavailable;
198+
): () => Promise<void> {
199+
unavailableSinks.add(onUnavailable);
196200
if (unavailableReason) onUnavailable(unavailableReason);
197201
else obtainWorker();
202+
pngWorkerHolds += 1;
203+
let released = false;
204+
return async () => {
205+
if (released) return;
206+
released = true;
207+
unavailableSinks.delete(onUnavailable);
208+
pngWorkerHolds -= 1;
209+
if (pngWorkerHolds === 0) await terminatePngWorker();
210+
};
198211
}
199212

200213
/** Stops the worker thread (used by tests and shutdown); later calls respawn it. */

‎packages/contracts/src/application-lifecycle-runtime.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -382,8 +382,10 @@ export type AppleApplicationTools = Readonly<{
382382
applyRuntimeHints(device: DeviceInfo, input: RuntimeHintsApplicationInput): Promise<void>;
383383
clearRuntimeHints(device: DeviceInfo, input: RuntimeHintsApplicationInput): Promise<void>;
384384
dismissCloseAlerts(device: DeviceInfo, input: CloseApplicationFinalizationInput): Promise<void>;
385-
detachRunnerSessionsForShutdown(): Promise<void>;
386-
finalizeRunnerSessionsForShutdown(): Promise<void>;
385+
/** The devices whose runner was handed to the next daemon instead of stopped. */
386+
detachRunnerSessionsForShutdown(): Promise<readonly string[]>;
387+
/** The devices whose runner this daemon stopped. */
388+
finalizeRunnerSessionsForShutdown(): Promise<readonly string[]>;
387389
}>;
388390

389391
/** Lazy Android mechanics used by the Android package's own lifecycle binding. */
@@ -413,6 +415,6 @@ export type AndroidApplicationTools = Readonly<{
413415
/** Gateway-coordinated durable phases whose concrete mechanics stay package-owned. */
414416
export type ApplicationLifecycleResourceLifecycle = Readonly<{
415417
recoverStartupResources(input: Readonly<{ stateDir: string }>): Promise<void>;
416-
detachForDaemonShutdown(): Promise<void>;
417-
finalizeDaemonShutdown(): Promise<void>;
418+
detachForDaemonShutdown(): Promise<readonly string[]>;
419+
finalizeDaemonShutdown(): Promise<readonly string[]>;
418420
}>;

‎packages/daemon/src/__tests__/support/daemon-runtime-deps-fixture.ts‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import type { ApplicationLifecycleResourceLifecycle } from '@agent-device/contracts/application-lifecycle-runtime';
22
import { createTestDeviceInventoryGateways } from '@agent-device/device-selection/inventory-gateways-fixtures';
33
import { createOwnedProcessRecordStore } from '@agent-device/host-kit/process';
4+
import type { ProviderDeviceRuntime } from '@agent-device/contracts/device';
45
import { vi } from 'vitest';
56
import type {
67
ComposeDaemonRuntimeDeps,
@@ -25,8 +26,8 @@ export function applicationLifecycleResourceFixture(
2526
): ApplicationLifecycleResourceLifecycle {
2627
return Object.freeze({
2728
recoverStartupResources: vi.fn(async () => {}),
28-
detachForDaemonShutdown: vi.fn(async () => {}),
29-
finalizeDaemonShutdown: vi.fn(async () => {}),
29+
detachForDaemonShutdown: vi.fn(async (): Promise<readonly string[]> => []),
30+
finalizeDaemonShutdown: vi.fn(async (): Promise<readonly string[]> => []),
3031
...overrides,
3132
});
3233
}
@@ -59,6 +60,7 @@ export function daemonRuntimeDepsFixture(
5960
return async (input) => {
6061
const resolved = typeof overrides === 'function' ? overrides(input) : overrides;
6162
return Object.freeze({
63+
runtimeStates: [],
6264
ownedProcessRecords: createOwnedProcessRecordStore({
6365
stateDir: input.baseDir,
6466
sessionsDir: input.sessionsDir,
@@ -94,3 +96,48 @@ export function daemonRuntimeDepsFixture(
9496
});
9597
};
9698
}
99+
100+
/**
101+
* A plugin registry over provider runtimes, as the composition hands it to the daemon: the
102+
* inventory of active plugins and the one `close` that shuts each runtime down and answers with a
103+
* per-plugin outcome.
104+
*/
105+
export function pluginRegistryFixture(
106+
runtimes: readonly Pick<ProviderDeviceRuntime, 'provider' | 'shutdown'>[],
107+
): Pick<DaemonRuntimeDeps, 'pluginInventory' | 'shutdownProviderRuntimes'> {
108+
return {
109+
pluginInventory: runtimes.map((runtime) => ({
110+
provider: runtime.provider,
111+
source: 'builtin' as const,
112+
state: 'active' as const,
113+
credentials: { variables: [], byBackend: {} },
114+
})),
115+
shutdownProviderRuntimes: async () =>
116+
await Promise.all(
117+
runtimes.map(async (runtime) => {
118+
try {
119+
await runtime.shutdown();
120+
return {
121+
provider: runtime.provider,
122+
source: 'builtin' as const,
123+
shutdown: { status: 'ok' as const },
124+
dispose: { status: 'ok' as const },
125+
};
126+
} catch (error) {
127+
return {
128+
provider: runtime.provider,
129+
source: 'builtin' as const,
130+
shutdown: {
131+
status: 'failed' as const,
132+
error: {
133+
code: 'COMMAND_FAILED',
134+
message: error instanceof Error ? error.message : String(error),
135+
},
136+
},
137+
dispose: { status: 'ok' as const },
138+
};
139+
}
140+
}),
141+
),
142+
};
143+
}

‎packages/daemon/src/core/interactor-resolution.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { defineRuntimeSlots, type RuntimeStateHandle } from '@agent-device/host-kit/runtime-slots';
12
import type { Interactor, RunnerContext } from '@agent-device/contracts/interactor-types';
23
import type { DeviceInfo } from '@agent-device/kernel/device';
34
import { AppError } from '@agent-device/kernel/errors';
@@ -27,17 +28,28 @@ const NO_INTERACTOR_RESOLUTION: InteractorResolution = {
2728
},
2829
};
2930

30-
let installedInteractorResolution: InteractorResolution = NO_INTERACTOR_RESOLUTION;
31+
type InteractorResolutionState = { resolution: InteractorResolution };
32+
33+
const interactorResolutionRuntime = defineRuntimeSlots();
34+
const INTERACTOR_RESOLUTION_SLOT = Symbol('interactorResolution');
35+
const interactorResolutionState = (): InteractorResolutionState =>
36+
interactorResolutionRuntime.slot(INTERACTOR_RESOLUTION_SLOT, (): InteractorResolutionState => ({
37+
resolution: NO_INTERACTOR_RESOLUTION,
38+
}));
39+
40+
/** The resolution one daemon runtime owns; the runtime installs its composition's into it. */
41+
export const createInteractorResolutionRuntimeState = (): RuntimeStateHandle =>
42+
interactorResolutionRuntime.createHandle();
3143

3244
/**
3345
* Root composition's installation point, beside the provider-device admission that shares the
3446
* same request-scoped provider scope: one change names both. The interactor graph stays behind
3547
* the module root composition imports, and the daemon never loads it itself.
3648
*/
3749
export function installInteractorResolution(resolution: InteractorResolution): void {
38-
installedInteractorResolution = resolution;
50+
interactorResolutionState().resolution = resolution;
3951
}
4052

4153
export function interactorResolution(): InteractorResolution {
42-
return installedInteractorResolution;
54+
return interactorResolutionState().resolution;
4355
}

‎packages/daemon/src/core/provider-device-admission.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { defineRuntimeSlots, type RuntimeStateHandle } from '@agent-device/host-kit/runtime-slots';
12
import type { DeviceInfo } from '@agent-device/kernel/device';
23

34
/**
@@ -18,17 +19,28 @@ const NO_PROVIDER_DEVICE_ADMISSION: ProviderDeviceAdmission = {
1819
isActive: () => false,
1920
};
2021

21-
let installedProviderDeviceAdmission: ProviderDeviceAdmission = NO_PROVIDER_DEVICE_ADMISSION;
22+
type ProviderAdmissionState = { admission: ProviderDeviceAdmission };
23+
24+
const providerAdmissionRuntime = defineRuntimeSlots();
25+
const PROVIDER_ADMISSION_SLOT = Symbol('providerDeviceAdmission');
26+
const providerAdmissionState = (): ProviderAdmissionState =>
27+
providerAdmissionRuntime.slot(PROVIDER_ADMISSION_SLOT, (): ProviderAdmissionState => ({
28+
admission: NO_PROVIDER_DEVICE_ADMISSION,
29+
}));
30+
31+
/** The admission one daemon runtime owns; the runtime installs its composition's into it. */
32+
export const createProviderDeviceAdmissionRuntimeState = (): RuntimeStateHandle =>
33+
providerAdmissionRuntime.createHandle();
2234

2335
/**
2436
* Root composition's installation point. The provider runtime scope is ambient per request, so
2537
* this is the one place the daemon names where the fact comes from, and the daemon never reads
2638
* provider runtime internals itself.
2739
*/
2840
export function installProviderDeviceAdmission(admission: ProviderDeviceAdmission): void {
29-
installedProviderDeviceAdmission = admission;
41+
providerAdmissionState().admission = admission;
3042
}
3143

3244
export function isActiveProviderDevice(device: DeviceInfo): boolean {
33-
return installedProviderDeviceAdmission.isActive(device);
45+
return providerAdmissionState().admission.isActive(device);
3446
}

‎packages/daemon/src/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
export { startDaemonRuntime } from './server/http/daemon-runtime.ts';
1+
export { daemonStartupExitCode, startDaemonRuntime } from './server/http/daemon-runtime.ts';
2+
export { reportDaemonClose } from './server/http/server-shutdown.ts';
23
export type {
34
ComposeDaemonRuntimeDeps,
45
DaemonRuntimeController,
56
DaemonRuntimeDeps,
6-
DaemonRuntimeDepsInput,
77
} from './server/http/daemon-runtime.ts';
88
export type { DaemonInvokeFn, DaemonRequest } from './core/daemon-request.ts';
99
export type { DaemonPlatformServices } from './core/platform-services.ts';
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
import { expect, test } from 'vitest';
4+
import { mkdtempForTestSync } from '@agent-device/test-kit';
5+
import {
6+
createArtifactTrackingRuntimeState,
7+
trackDownloadableArtifact,
8+
trackUploadedArtifact,
9+
} from './artifact-tracking.ts';
10+
11+
test('disposing a runtime removes the temporary files it still tracks', () => {
12+
const root = mkdtempForTestSync('agent-device-artifact-dispose-');
13+
const artifactPath = path.join(root, 'artifact.txt');
14+
const uploadDir = path.join(root, 'upload');
15+
fs.writeFileSync(artifactPath, 'artifact');
16+
fs.mkdirSync(uploadDir);
17+
fs.writeFileSync(path.join(uploadDir, 'payload'), 'payload');
18+
const runtime = createArtifactTrackingRuntimeState();
19+
20+
runtime.run(() => {
21+
trackDownloadableArtifact({
22+
artifactPath,
23+
artifactType: 'runtime-artifact',
24+
fileName: 'artifact.txt',
25+
});
26+
trackUploadedArtifact({ artifactPath: path.join(uploadDir, 'payload'), tempDir: uploadDir });
27+
});
28+
runtime.dispose();
29+
30+
expect(fs.existsSync(uploadDir)).toBe(false);
31+
expect(fs.existsSync(artifactPath)).toBe(false);
32+
});

0 commit comments

Comments
 (0)