Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .changeset/explicit-sdk-hosts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
'agent-device': minor
---

Require explicit SDK host dependencies in 0.22. Part of #3759 section 3.

Pass `{ env, cwd }` to `runAndroidShell(device, words, host, options?)`, `runAndroidExecOut(device, words, host, options?)`, `resolveAndroidArchivePackageName(archivePath, host, signal?)`, `prepareMetroRuntime(options, host)`, and `new LimrunRuntime(options, host)`. For example, capture `const host = { env: { ...process.env }, cwd: process.cwd() }` in your entry point, then call `await prepareMetroRuntime(options, host)`.

`resolveRemoteConfigProfile({ configPath, cwd, env })` requires `env`, and `createLocalArtifactAdapter({ cwd })` requires `cwd`. Archive inspection resolves relative paths from the supplied host and no longer shares a cached SDK tool across hosts. The internal contracts, host-kit, remote, and platform-android packages are bundled into `agent-device`; this changeset covers their affected public APIs.

Executable captures and `startAgentDevice`'s optional-host capture remain available. See [Build an integration](/docs/build-an-integration#migrate-sdk-hosts-to-022) for migration examples.
5 changes: 2 additions & 3 deletions docs/agents/code-ownership.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,10 @@ Before you edit a module with many callers, run `pnpm depgraph affected <path>`.
| Output formatters | `packages/command-output/src/` |
| Help and progress | `src/commands/` |
| Input fields and audiences | `packages/command-surface/src/common-input-fields.ts`, `packages/command-surface/src/input-audience.ts` |
| Released SDK default hosts | `src/sdk/host.ts` |
| Released SDK command-host scopes | `src/sdk/host.ts` |
| Apple runner host port and binding | `packages/apple-runner/src/host.ts`, `packages/platform-apple/src/core/runner-client.ts` |

For SDK entries `android-adb`, `artifacts`, `limrun`, `metro`, and `remote-config`, use `captureSdkHost` for defaults.
For command-host readers, use `withSdkHost`.
For SDK command-host readers, pass the supplied host to `withSdkHost`.
Keep provider callbacks on their supplied host.
Request cancellation and progress belong in `@agent-device/host-kit/request`.
Per-call abort guards belong beside transports in `packages/daemon-client/src/daemon-client-transport.ts`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ test('runtime diff screenshot captures live current image and cleans temporary c
fs.writeFileSync(outPath, solidPngBuffer(10, 10, { r: 255, g: 255, b: 255 }));
return { path: outPath };
}),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -74,7 +74,7 @@ test('runtime diff screenshot compares supplied current image without backend ca
backend: createScreenshotBackend(() => {
throw new Error('capture should not be called');
}),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand All @@ -97,7 +97,7 @@ test('runtime diff screenshot rejects overlay refs with supplied current image',
backend: createScreenshotBackend(() => {
throw new Error('capture should not be called');
}),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -125,7 +125,7 @@ test('runtime diff screenshot enforces the normalized comparison pixel budget',
backend: createScreenshotBackend(() => {
throw new Error('capture should not be called');
}),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy({ maxImagePixels: 50 }),
});
Expand Down Expand Up @@ -172,7 +172,7 @@ test('runtime diff screenshot keeps the screen mask on current and overlay captu
: {}),
};
}),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -238,7 +238,7 @@ test('runtime diff refuses a screen mask for saved images before reading or capt
backend: createScreenshotBackend(() => {
throw new Error('must not capture');
}),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ async function captureWith(result: BackendSnapshotResult) {
};
const device = createAgentDevice({
backend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ test('runtime screenshot applies scale and forwards the capture rotation', async
return { displayRotation: 'landscape-left' };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: { get: () => undefined, set: () => {} },
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -47,7 +47,7 @@ test('runtime screenshot scales the already-cropped backend capture', async () =
);
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: { get: () => undefined, set: () => {} },
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -94,7 +94,7 @@ for (const staged of [false, true]) {
fs.writeFileSync(destination, sentinel);
const controller = new AbortController();
const cancellation = new Error('caller cancelled after capture');
const adapter = createLocalArtifactAdapter();
const adapter = createLocalArtifactAdapter({ cwd: process.cwd() });
let publications = 0;
let cleanups = 0;
if (staged) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ async function snapshotWithForeground(
...sessionApp,
}),
},
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => undefined,
set: (record) => {
Expand Down Expand Up @@ -94,7 +94,7 @@ test('a repeated unchanged snapshot of a foreign foreground app is acknowledged
appBundleId: 'com.android.settings',
}),
},
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => stored,
set: (record) => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ function snapshotDevice(
};
return createAgentDevice({
backend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: { get: () => session, set: () => {} },
policy: localCommandPolicy(),
clock: { now: () => 1_500, sleep: async () => {} },
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ test('runtime snapshot captures nodes and updates the session baseline', async (
appName: 'Demo',
appBundleId: 'com.example.demo',
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => undefined,
set: (record) => {
Expand Down Expand Up @@ -108,7 +108,7 @@ test('runtime snapshot recognizes equivalent bounds and still updates its baseli
comparisonSafe: true,
}),
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => stored,
set: (record) => {
Expand Down Expand Up @@ -165,7 +165,7 @@ test('runtime snapshot forwards interactive capture options', async () => {
};
},
},
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => undefined,
set: () => {},
Expand Down Expand Up @@ -198,7 +198,7 @@ test('runtime diff snapshot initializes and then compares against session baseli
backend: createSnapshotBackend(() => ({
snapshot: makeSnapshotState([{ index: 0, depth: 0, type: 'Window', label: 'After' }]),
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => session,
set: (record) => {
Expand All @@ -222,7 +222,7 @@ test('runtime diff snapshot initializes baseline when no previous snapshot exist
backend: createSnapshotBackend(() => ({
snapshot: makeSnapshotState([{ index: 0, depth: 0, type: 'Window', label: 'Initial' }]),
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => undefined,
set: (record) => {
Expand Down Expand Up @@ -632,7 +632,7 @@ test('runtime snapshot stale-drop warning uses the runtime clock', async () => {
createdAt: 3_500,
}),
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => session,
set: (record) => {
Expand Down Expand Up @@ -678,7 +678,7 @@ test('runtime snapshot stale-drop warning uses backend snapshot timestamps when
backend: createSnapshotBackend(() => ({
snapshot: currentSnapshot,
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => session,
set: (record) => {
Expand Down Expand Up @@ -724,7 +724,7 @@ test('runtime snapshot stale-drop warning falls back to runtime clock on backend
backend: createSnapshotBackend(() => ({
snapshot: currentSnapshot,
})),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => session,
set: (record) => {
Expand Down Expand Up @@ -759,7 +759,7 @@ function createSnapshotBackend(
function createSnapshotOnlyDevice(result: BackendSnapshotResult) {
return createAgentDevice({
backend: createSnapshotBackend(() => result),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => undefined,
set: () => {},
Expand Down Expand Up @@ -928,7 +928,7 @@ test('runtime snapshot carries backend clickability evidence through presentatio
let stored: Parameters<CommandSessionStore['set']>[0] | undefined;
const device = createAgentDevice({
backend: createSnapshotBackend(() => ({ snapshot: state })),
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: {
get: () => undefined,
set: (record) => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ export function createSettleDevice(params: {
fill: async () => ({ ok: true }),
longPress: async () => ({ ok: true }),
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([
{
name: 'default',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,7 @@ export function createInteractionDevice(
? async (...args) => (await overrides.confirmOffscreenTargetVisible?.(...args)) ?? null
: undefined,
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([
{ name: 'default', snapshot, metadata: overrides.sessionMetadata },
]),
Expand Down Expand Up @@ -636,7 +636,7 @@ export function createSelectorDevice(
options.captureSnapshot ? await options.captureSnapshot() : { snapshot },
readText: async () => ({ text: options.readText ?? '' }),
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
clock: options.clock ?? {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ function createDevice(stored: SnapshotState) {
return {};
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot: stored }]),
policy: localCommandPolicy(),
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ function deviceWithSessionTree(snapshot: ReturnType<typeof makeSnapshotState> |
taps.push(point);
},
},
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
policy: localCommandPolicy(),
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,7 @@ test('native ref fast path proceeds untouched when the session has no snapshot',
return { ref: target.ref.replace(/^@/, '') };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default' }]),
policy: localCommandPolicy(),
});
Expand All @@ -333,7 +333,7 @@ test('runtime interactions pass runtime signal to backend primitives', async ()
signal = context.signal;
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
policy: localCommandPolicy(),
signal: controller.signal,
});
Expand Down Expand Up @@ -784,7 +784,7 @@ test('coordinate tap with no session snapshot has no warning', async () => {
platform: 'ios',
tap: async () => ({ ok: true }),
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default' }]),
policy: localCommandPolicy(),
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ function createGuardedDevice(params: {
return { ok: true };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([
{
name: 'default',
Expand Down Expand Up @@ -667,7 +667,7 @@ test('a ref from a full-tree frame is re-observed in that presentation, not renu
return { ok: true };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([
{
name: 'default',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ function createAdmissionDevice(params: {
const stored = params.trees[0]!;
const device = createAgentDevice({
backend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([
{
name: 'default',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ test('runtime selectors forward public snapshot options to backend capture', asy
return { snapshot };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -54,7 +54,7 @@ test('runtime visibility predicates request snapshot rects', async () => {
return { snapshot };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -87,7 +87,7 @@ test('runtime focused predicate requests a full snapshot', async () => {
return { snapshot };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -126,7 +126,7 @@ test('runtime focused predicate reads focused Android TV nodes from the full tre
return { snapshot: options?.interactiveOnly ? interactiveSnapshot : fullSnapshot };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot: interactiveSnapshot }]),
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -189,7 +189,7 @@ test('runtime is absent uses one readAny capture without requesting rects', asyn
return { snapshot };
},
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
policy: localCommandPolicy(),
});
Expand Down Expand Up @@ -316,7 +316,7 @@ test('runtime is absent fails closed for a sparse capture and preserves the last
platform: 'ios',
captureSnapshot: async () => ({ snapshot: sparse }),
} satisfies AgentDeviceBackend,
artifacts: createLocalArtifactAdapter(),
artifacts: createLocalArtifactAdapter({ cwd: process.cwd() }),
sessions,
policy: localCommandPolicy(),
});
Expand Down
Loading
Loading