Skip to content

Commit 7c10533

Browse files
committed
refactor(host): read every configuration value from an explicit host (#3794)
Every non-test production read of the ambient command host for configuration is replaced by an explicit HostEnvironment threaded from the composing runtime (34 reads -> 0 outside the host-kit spawn domain). - Platform plugins take the host per call: createInteractor(device, runner, host); createAppleInteractor, createLinuxInteractor(host), createVegaInteractor, createWebInteractor(host, provider?) bind it into their leaves. - The Apple runner's host is per-runtime state seeded by the composition root. - Local tool providers check executables against the caller's env (whichCommand(cmd, env)); the Vega toolchain resolves and caches per env. - CLI/MCP output formatting reads color env from the client's host (AgentDeviceClient.host); formatCliOutput and doctorCliOutput take it. - platform-web fails closed (web-provider-missing) where an un-scoped process-bound fallback used to answer. - New tests: two runtimes route the same macOS device by their own host; the composed daemon route configures interactors from its host, not the process. Part of #3747. Closes #3794.
1 parent c966724 commit 7c10533

219 files changed

Lines changed: 2687 additions & 1242 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/contracts/src/debug-symbols.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ export type DebugSymbolsOptions = {
44
dsym?: string;
55
searchPath?: string;
66
out?: string;
7-
cwd?: string;
7+
/** The working directory relative paths resolve against; the caller's host owns it. */
8+
cwd: string;
89
};
910

1011
export type DebugSymbolsImage = {

‎packages/contracts/src/platform-plugin.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import type { DeviceInfo, Platform, PlatformSelector } from '@agent-device/kernel/device';
2+
import type { HostEnvironment } from '@agent-device/kernel/source-value';
23
import type { PlatformGatedProviderResolverKey } from './platform-providers.ts';
34
import type { Interactor, RunnerContext } from './interactor-types.ts';
45

@@ -31,8 +32,18 @@ export type PlatformPlugin = {
3132
readonly platforms: readonly Platform[];
3233
/** The multi-platform family selector, when the plugin owns more than one leaf (`apple`). */
3334
readonly familySelector?: PlatformSelector;
34-
/** Lazily builds the {@link Interactor} for `device` — wraps today's `getInteractor` switch arm. */
35-
createInteractor(device: DeviceInfo, runner: RunnerContext): Promise<Interactor>;
35+
/**
36+
* Lazily builds the {@link Interactor} for `device` — wraps today's `getInteractor` switch arm.
37+
* `host` is the environment the calling runtime captured at its entry point. Plugins are
38+
* module-level and shared by every runtime in a process, so the host arrives per call — never
39+
* bound at plugin construction — and is the same object the runtime's deps and request-bound
40+
* facets carry.
41+
*/
42+
createInteractor(
43+
device: DeviceInfo,
44+
runner: RunnerContext,
45+
host: HostEnvironment,
46+
): Promise<Interactor>;
3647
/**
3748
* The request-scope provider facet (issue #974). `platformGatedResolvers`
3849
* declares which PLATFORM-GATED request provider resolvers apply to this family's

‎packages/contracts/src/platform-runtime-host.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ import type { DeviceInfo, Platform } from '@agent-device/kernel/device';
22
import type { JsonObject, JsonValue } from './json.ts';
33
import type { AndroidClipboardShellSupport } from './android-clipboard-support.ts';
44

5+
// The composition root names the runtime host through this contract rather than the kernel
6+
// substrate directly (R13): one host object is the whole configuration surface a runtime reads.
7+
export type { HostEnvironment } from '@agent-device/kernel/source-value';
8+
59
export type HostCommandRequest = Readonly<{
610
executable: string;
711
args: readonly string[];

‎packages/contracts/src/platform-runtime-operations.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { AppLogRuntimeHost, AppLogRuntimeOperations } from './app-log-runtime.ts';
22
import type { AppInventoryRuntimeOperations } from './app-inventory-runtime.ts';
3+
import type { HostEnvironment } from '@agent-device/kernel/source-value';
34
import type {
45
AndroidAppDeploymentExecutor,
56
AppDeploymentRuntimeOperations,
@@ -830,6 +831,11 @@ export const keyboardRuntimePlanUses = Object.freeze([
830831
export type PlatformRuntimeHost = AppLogRuntimeHost &
831832
NetworkRuntimeHost &
832833
Readonly<{
834+
/**
835+
* The host this runtime's entry point captured. Owners read configuration from it; it is the
836+
* same object the runtime's deps carry, never a re-capture.
837+
*/
838+
hostEnvironment: HostEnvironment;
833839
/** Focused native ports; deployment semantics remain in the owning family packages. */
834840
appleDeployment: AppleAppDeploymentExecutor;
835841
androidDeployment: AndroidAppDeploymentExecutor;

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,10 @@ export function snapshotRuntimeFixture(requestId?: string): Readonly<{
113113
// runner underneath is the suite's own mock.
114114
const runnerOptions = { signal: requestSignal };
115115
const appleInteractor = isApplePlatform(device.platform)
116-
? await applePlugin.createInteractor(device, runnerOptions)
116+
? await applePlugin.createInteractor(device, runnerOptions, {
117+
env: process.env,
118+
cwd: process.cwd(),
119+
})
117120
: undefined;
118121
const alertOptions = (input: AlertRuntimeInput) => ({
119122
...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),

‎packages/platform-apple/src/__tests__/alert.test.ts‎

Lines changed: 80 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ afterEach(() => {
4343
test('a read spends the family default, not the caller window', async () => {
4444
mockRunner.mockResolvedValue({ title: 'Camera Access' });
4545

46-
await readAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 37 });
46+
await readAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 37 }, process.env);
4747

4848
assert.equal(mockRunner.mock.calls.length, 1);
4949
assert.deepEqual(mockRunner.mock.calls[0]?.[1], {
@@ -62,7 +62,12 @@ test('a wait polls until one attempt answers, and the first attempt gets the who
6262
return { title: 'Camera Access' };
6363
});
6464

65-
const result = await awaitAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 5_000 });
65+
const result = await awaitAppleAlert(
66+
IOS_SIMULATOR,
67+
runnerOptions,
68+
{ timeoutMs: 5_000 },
69+
process.env,
70+
);
6671

6772
assert.deepEqual(result, { title: 'Camera Access' });
6873
assert.equal(calls, 2);
@@ -76,7 +81,12 @@ test('a wait that never sees an alert reports the timeout rather than the last a
7681
vi.useFakeTimers();
7782
mockRunner.mockRejectedValue(runnerAbsence());
7883

79-
const outcome = awaitAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 900 }).then(
84+
const outcome = awaitAppleAlert(
85+
IOS_SIMULATOR,
86+
runnerOptions,
87+
{ timeoutMs: 900 },
88+
process.env,
89+
).then(
8090
() => undefined,
8191
(error: unknown) => error,
8292
);
@@ -93,7 +103,13 @@ test('an accept retries only while the backend says the alert is not there yet',
93103
throw new AppError('COMMAND_FAILED', 'runner crashed');
94104
});
95105

96-
const outcome = actOnAppleAlert(IOS_SIMULATOR, runnerOptions, 'accept').then(
106+
const outcome = actOnAppleAlert(
107+
IOS_SIMULATOR,
108+
runnerOptions,
109+
'accept',
110+
undefined,
111+
process.env,
112+
).then(
97113
() => undefined,
98114
(error: unknown) => error,
99115
);
@@ -107,7 +123,13 @@ test('an exhausted accept carries the scoped-snapshot fallback the agent needs n
107123
vi.useFakeTimers();
108124
mockRunner.mockRejectedValue(runnerAbsence());
109125

110-
const outcome = actOnAppleAlert(IOS_SIMULATOR, runnerOptions, 'accept').then(
126+
const outcome = actOnAppleAlert(
127+
IOS_SIMULATOR,
128+
runnerOptions,
129+
'accept',
130+
undefined,
131+
process.env,
132+
).then(
111133
() => undefined,
112134
(error: unknown) => error,
113135
);
@@ -130,7 +152,12 @@ test('a wait propagates a non-absence failure instead of spending it as poll bud
130152
throw new AppError('COMMAND_FAILED', 'runner transport closed: alert not found');
131153
});
132154

133-
const outcome = awaitAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 5_000 }).then(
155+
const outcome = awaitAppleAlert(
156+
IOS_SIMULATOR,
157+
runnerOptions,
158+
{ timeoutMs: 5_000 },
159+
process.env,
160+
).then(
134161
() => undefined,
135162
(error: unknown) => error,
136163
);
@@ -148,7 +175,13 @@ test('an action does not retry a failure that only reads like an absence', async
148175
throw new AppError('COMMAND_FAILED', 'no alert service on this runner');
149176
});
150177

151-
const outcome = actOnAppleAlert(IOS_SIMULATOR, runnerOptions, 'dismiss').then(
178+
const outcome = actOnAppleAlert(
179+
IOS_SIMULATOR,
180+
runnerOptions,
181+
'dismiss',
182+
undefined,
183+
process.env,
184+
).then(
152185
() => undefined,
153186
(error: unknown) => error,
154187
);
@@ -168,7 +201,13 @@ test('the macOS helper states absence as a typed reason, and the family retries
168201
throw helperAbsence();
169202
});
170203

171-
const outcome = actOnAppleAlert(MACOS_DEVICE, runnerOptions, 'accept').then(
204+
const outcome = actOnAppleAlert(
205+
MACOS_DEVICE,
206+
runnerOptions,
207+
'accept',
208+
undefined,
209+
process.env,
210+
).then(
172211
() => undefined,
173212
(error: unknown) => error,
174213
);
@@ -183,24 +222,37 @@ test('the macOS helper states absence as a typed reason, and the family retries
183222
test('the macOS host reads through its helper, and a frontmost-app session names no bundle', async () => {
184223
mockHelper.mockResolvedValue({ title: 'Allow access' });
185224

186-
await readAppleAlert(MACOS_DEVICE, runnerOptions, {
187-
surface: 'frontmost-app',
188-
appBundleId: 'com.example.app',
189-
});
225+
await readAppleAlert(
226+
MACOS_DEVICE,
227+
runnerOptions,
228+
{
229+
surface: 'frontmost-app',
230+
appBundleId: 'com.example.app',
231+
},
232+
process.env,
233+
);
190234

191235
assert.equal(mockRunner.mock.calls.length, 0);
192-
assert.deepEqual(mockHelper.mock.calls[0], ['get', { surface: 'frontmost-app' }]);
236+
assert.deepEqual(mockHelper.mock.calls[0], [
237+
'get',
238+
{ surface: 'frontmost-app', env: process.env },
239+
]);
193240
});
194241

195242
// The narrowing is the macOS helper's alone. A non-macOS Apple leaf keeps the session bundle
196243
// whatever the surface says, exactly as the retired route passed it to the XCTest runner.
197244
test('the XCTest runner keeps the session bundle even on a frontmost-app surface', async () => {
198245
mockRunner.mockResolvedValue({ title: 'Camera Access' });
199246

200-
await readAppleAlert(IOS_SIMULATOR, runnerOptions, {
201-
surface: 'frontmost-app',
202-
appBundleId: 'com.example.app',
203-
});
247+
await readAppleAlert(
248+
IOS_SIMULATOR,
249+
runnerOptions,
250+
{
251+
surface: 'frontmost-app',
252+
appBundleId: 'com.example.app',
253+
},
254+
process.env,
255+
);
204256

205257
assert.deepEqual(mockRunner.mock.calls[0]?.[1], {
206258
command: 'alert',
@@ -213,13 +265,19 @@ test('the XCTest runner keeps the session bundle even on a frontmost-app surface
213265
test('a macOS app session forwards the bundle its surface is scoped to', async () => {
214266
mockHelper.mockResolvedValue({ action: 'dismiss' });
215267

216-
await actOnAppleAlert(MACOS_DEVICE, runnerOptions, 'dismiss', {
217-
surface: 'app',
218-
appBundleId: 'com.example.app',
219-
});
268+
await actOnAppleAlert(
269+
MACOS_DEVICE,
270+
runnerOptions,
271+
'dismiss',
272+
{
273+
surface: 'app',
274+
appBundleId: 'com.example.app',
275+
},
276+
process.env,
277+
);
220278

221279
assert.deepEqual(mockHelper.mock.calls[0], [
222280
'dismiss',
223-
{ bundleId: 'com.example.app', surface: 'app' },
281+
{ bundleId: 'com.example.app', surface: 'app', env: process.env },
224282
]);
225283
});

‎packages/platform-apple/src/__tests__/index-runner-requests.test.ts‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -192,15 +192,17 @@ const SCOPED_SITES: Record<string, ScopedDrive> = {
192192
],
193193
'macos.screenshot-runner.fullscreen': [
194194
MACOS_DEVICE,
195-
(outPath) => captureScreenshotViaRunner(MACOS_DEVICE, outPath, APP, true),
195+
(outPath) =>
196+
captureScreenshotViaRunner(MACOS_DEVICE, outPath, APP, true, undefined, process.env),
196197
],
197198
'ios-device.physical-device-screenshot.coredevice-file': [
198199
IOS_DEVICE,
199-
(outPath) => captureScreenshotViaRunner(IOS_DEVICE, outPath, APP, true),
200+
(outPath) => captureScreenshotViaRunner(IOS_DEVICE, outPath, APP, true, undefined, process.env),
200201
],
201202
'ios-device.physical-device-screenshot.xctest-inline': [
202203
XCTEST_DEVICE,
203-
(outPath) => captureScreenshotViaRunner(XCTEST_DEVICE, outPath, APP),
204+
(outPath) =>
205+
captureScreenshotViaRunner(XCTEST_DEVICE, outPath, APP, undefined, undefined, process.env),
204206
],
205207
'ios-device.physical-device-control.activate': [
206208
XCTEST_DEVICE,
@@ -223,14 +225,20 @@ test('every Apple request site builds exactly its golden runner request', async
223225
for (const [name, [device, drive]] of Object.entries(INTERACTOR_SITES)) {
224226
const calls: RecordedRunnerCall[] = [];
225227
await drive(
226-
createAppleInteractor(device, { appBundleId: APP }, recordingRunnerProvider(calls)),
228+
createAppleInteractor(
229+
device,
230+
{ appBundleId: APP },
231+
{ env: process.env, cwd: process.cwd() },
232+
recordingRunnerProvider(calls),
233+
),
227234
);
228235
captured.push([name, onlyRequest(name, calls)]);
229236
}
230237
const observationCalls: RecordedRunnerCall[] = [];
231238
await createAppleInteractor(
232239
IOS_SIMULATOR,
233240
{ appBundleId: APP },
241+
{ env: process.env, cwd: process.cwd() },
234242
recordingRunnerProvider(observationCalls, {
235243
snapshot: {
236244
nodes: [{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } }],

‎packages/platform-apple/src/__tests__/interactor-macos-surface.test.ts‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,11 @@ function reachedBackend(): MacOsSurfaceBackend {
113113
test.each(SURFACE_ROWS)(
114114
'every macOS operation on the %s surface reaches the %s backend',
115115
async (surface, backend) => {
116-
const interactor = createAppleInteractor(macOsDevice, {});
116+
const interactor = createAppleInteractor(
117+
macOsDevice,
118+
{},
119+
{ env: process.env, cwd: process.cwd() },
120+
);
117121
const operations: Record<string, () => Promise<unknown>> = {
118122
screenshot: async () => await interactor.screenshot('/tmp/out.png', { surface }),
119123
snapshot: async () => await interactor.snapshot({ surface }),
@@ -139,7 +143,11 @@ test.each(SURFACE_ROWS)(
139143
test.each(HELPER_ROWS)(
140144
'refuses an explicit --fullscreen on the macOS %s surface before any capture',
141145
async (surface) => {
142-
const interactor = createAppleInteractor(macOsDevice, {});
146+
const interactor = createAppleInteractor(
147+
macOsDevice,
148+
{},
149+
{ env: process.env, cwd: process.cwd() },
150+
);
143151

144152
await expect(
145153
interactor.screenshot('/tmp/out.png', { surface, fullscreen: true }),
@@ -158,19 +166,27 @@ test.each(HELPER_ROWS)(
158166
test.each(HELPER_ROWS)(
159167
'captures the %s surface through the helper when --fullscreen is not requested',
160168
async (surface) => {
161-
const interactor = createAppleInteractor(macOsDevice, {});
169+
const interactor = createAppleInteractor(
170+
macOsDevice,
171+
{},
172+
{ env: process.env, cwd: process.cwd() },
173+
);
162174

163175
await interactor.screenshot('/tmp/out.png', { surface });
164176

165177
expect(runMacOsScreenshotAction).toHaveBeenCalledOnce();
166178
const [, options] = vi.mocked(runMacOsScreenshotAction).mock.calls[0]!;
167-
expect(options).toEqual({ surface });
179+
expect(options).toEqual({ surface, env: process.env });
168180
expect(Object.hasOwn(options ?? {}, 'fullscreen')).toBe(false);
169181
},
170182
);
171183

172184
test('keeps a macOS app session on the runner path with --fullscreen unchanged', async () => {
173-
const interactor = createAppleInteractor(macOsDevice, {});
185+
const interactor = createAppleInteractor(
186+
macOsDevice,
187+
{},
188+
{ env: process.env, cwd: process.cwd() },
189+
);
174190

175191
await interactor.screenshot('/tmp/out.png', { surface: 'app', fullscreen: true });
176192

0 commit comments

Comments
 (0)