Skip to content

Commit 1ac970e

Browse files
thymikeeclaude
andauthored
refactor(maestro): move the daemon-side runtime port out of src/daemon (#2652)
* refactor(maestro): move the daemon-side runtime port out of src/daemon `src/daemon/adapters/maestro/**` was package-shaped by everything except two daemon-internal types. Its only consumers are the daemon's replay runtime, and `packages/maestro` already owns the engine it adapts. The cut set was the request vocabulary. The port read one `internal` field (`publicNetworkOnly`) and wrote four others, so it could not be typed on the wire request alone. It now emits a package-owned `MaestroDaemonOperationRequest` (command, positionals, input, merged flags, and `dispatch` options) and takes the network origin as a plain boolean. The daemon's `session-replay-maestro-request.ts` folds those dispatch options into `internal`, mapped field by field so a drift on either side fails to compile. `DaemonRequestInternal` stays daemon-private; nothing under `packages/**` takes it. `touch-reference-frame.ts` (30 LOC over `@agent-device/contracts`) moves to `@agent-device/capture-kit/touch-reference-frame`, the layer both the port and the daemon's interaction code sit on. The ten-line `failure-snapshot.ts` wrapper is gone; the replay failure path calls `collectMaestroFailureSuggestions` directly. The port stays off the maestro engine entry: `./daemon-runtime-port` and `./run-script-http` are subpath exports, and the eager-closure budget gate holds `.` at its current closure, so CLI help and replay parsing never start evaluating host-kit, capture-kit, or provision-kit through the package. The tsdown `internal/run-script-http-child` entry follows the file. `src/daemon` production files: 345 -> 333; LOC: 52,729 -> 50,517. Part of #2544; umbrella #2545. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01KWx9ywGdh7yr9k774LnZzq * chore(gates): pin the maestro port subpaths and the capture-kit reference-frame export R11's maestro pin grew from `.` to the two daemon-side port subpaths and from three to six workspace dependencies; the capture-kit export list gains `./touch-reference-frame`. The maestro facade test pins the surface and names the eager-closure budget gate as what keeps the port off `.`. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01KWx9ywGdh7yr9k774LnZzq --------- Co-authored-by: Claude <[email protected]>
1 parent 5b60f30 commit 1ac970e

58 files changed

Lines changed: 643 additions & 317 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.

‎docs/dependency-graph-findings.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -248,8 +248,9 @@ becomes generic over the request type, or the request shape itself moves down.
248248

249249
> **Status after #1435:** the inventory below is historical. `SessionAction`, replay-suite results,
250250
> `DaemonLockPolicy`, and the public daemon response/artifact/runtime-hint shapes now live below
251-
> daemon. Four production files outside daemon still import `daemon/types.ts`; two are
252-
> daemon-specific Maestro adapters scheduled to move back under daemon. `DaemonRequest` itself
251+
> daemon. Four production files outside daemon still import `daemon/types.ts`; two were
252+
> the daemon-side Maestro adapters, since moved into `packages/maestro` (#2544) behind a
253+
> package-owned operation request that the daemon folds into `DaemonRequest`. `DaemonRequest` itself
253254
> intentionally remains server-private because it carries admitted leases, callbacks, replay
254255
> guards, and narrowed flags. Remove the remaining external imports through neutral caller-specific
255256
> contracts; do not move `DaemonRequest` wholesale.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@
183183
"test-app:maestro:android": "pnpm test-app:maestro --platform android",
184184
"test": "pnpm test:unit",
185185
"test:unit": "vitest run --project unit-core --project fuzz-worker",
186-
"test:maestro-compat": "vitest run --project unit-core packages/maestro src/daemon/adapters/maestro src/compat/__tests__/replay-input.test.ts",
186+
"test:maestro-compat": "vitest run --project unit-core packages/maestro src/compat/__tests__/replay-input.test.ts",
187187
"test:coverage": "vitest run --coverage --project=!fuzz-worker && pnpm test:fuzz-worker",
188188
"test:coverage:ci": "vitest run --coverage --project=!fuzz-worker && pnpm test:fuzz-worker",
189189
"test:fuzz-worker": "vitest run --project fuzz-worker",

‎packages/capture-kit/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,10 @@
213213
"./text-surface": {
214214
"types": "./src/snapshot/snapshot-presentation/text-surface.ts",
215215
"default": "./src/snapshot/snapshot-presentation/text-surface.ts"
216+
},
217+
"./touch-reference-frame": {
218+
"types": "./src/snapshot/touch-reference-frame.ts",
219+
"default": "./src/snapshot/touch-reference-frame.ts"
216220
}
217221
},
218222
"devDependencies": {

src/daemon/touch-reference-frame.ts renamed to packages/capture-kit/src/snapshot/touch-reference-frame.ts

File renamed without changes.

‎packages/maestro/package.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,29 @@
66
"type": "module",
77
"description": "Private Maestro compatibility engine for agent-device.",
88
"dependencies": {
9+
"@agent-device/capture-kit": "workspace:*",
910
"@agent-device/contracts": "workspace:*",
11+
"@agent-device/host-kit": "workspace:*",
1012
"@agent-device/kernel": "workspace:*",
13+
"@agent-device/provision-kit": "workspace:*",
1114
"@agent-device/selectors": "workspace:*"
1215
},
1316
"exports": {
1417
".": {
1518
"types": "./src/index.ts",
1619
"default": "./src/index.ts"
20+
},
21+
"./daemon-runtime-port": {
22+
"types": "./src/daemon-port/daemon-runtime-port.ts",
23+
"default": "./src/daemon-port/daemon-runtime-port.ts"
24+
},
25+
"./run-script-http": {
26+
"types": "./src/daemon-port/run-script-http.ts",
27+
"default": "./src/daemon-port/run-script-http.ts"
1728
}
1829
},
1930
"devDependencies": {
31+
"undici": "7.29.0",
2032
"yaml": "^2.9.0"
2133
}
2234
}

src/daemon/adapters/maestro/__tests__/daemon-runtime-port-email-regression.test.ts renamed to packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-email-regression.test.ts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
import { expect, test } from 'vitest';
2-
import type { DaemonRequest } from '../../../daemon-request.ts';
2+
import type { MaestroDaemonOperationRequest } from '../daemon-runtime-public-operation.ts';
33
import { createDaemonMaestroRuntimePort } from '../daemon-runtime-port.ts';
4-
import { makeBaseRequest, makeDependencies } from './daemon-runtime-port-fixtures.ts';
4+
import { makeRuntimeEnvelope, makeDependencies } from './daemon-runtime-port-fixtures.ts';
55

66
test('resolves the Email input below its caption through the runtime port', async () => {
7-
const requests: DaemonRequest[] = [];
7+
const requests: MaestroDaemonOperationRequest[] = [];
88
const port = createDaemonMaestroRuntimePort({
9-
baseReq: makeBaseRequest({ flags: { platform: 'android', replayBackend: 'maestro' } }),
9+
...makeRuntimeEnvelope({ flags: { platform: 'android', replayBackend: 'maestro' } }),
1010
invoke: async (request) => {
1111
requests.push(request);
1212
return request.command === 'snapshot'
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import type { CommandFlags } from '@agent-device/contracts/command';
2+
import type { SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
3+
import type { MaestroSourceReader } from '@agent-device/maestro';
4+
import type { CreateDaemonMaestroRuntimeOperationsOptions } from '../daemon-runtime-port.ts';
5+
6+
export function makeSnapshot(
7+
nodes: Array<Omit<SnapshotNode, 'ref'> & { ref?: string }>,
8+
): SnapshotState {
9+
return {
10+
createdAt: 0,
11+
nodes: nodes.map((node) => ({ ref: `e${node.index + 1}`, ...node })),
12+
};
13+
}
14+
15+
/** The daemon-owned half of the port options: the runtime envelope flags and the network origin. */
16+
export function makeRuntimeEnvelope(
17+
overrides: { flags?: CommandFlags; publicNetworkOnly?: boolean } = {},
18+
): Pick<CreateDaemonMaestroRuntimeOperationsOptions, 'flags' | 'publicNetworkOnly'> {
19+
return {
20+
publicNetworkOnly: false,
21+
...overrides,
22+
};
23+
}
24+
25+
export function makeDependencies(
26+
now: { value: number } = { value: 0 },
27+
): CreateDaemonMaestroRuntimeOperationsOptions['dependencies'] {
28+
return {
29+
now: () => now.value,
30+
sleep: async (milliseconds) => {
31+
now.value += milliseconds;
32+
},
33+
};
34+
}
35+
36+
/**
37+
* `readSource` for a flow that declares no `runFlow` includes: the engine must
38+
* never reach for one, so a call here means the fixture drifted rather than a
39+
* missing file.
40+
*/
41+
export const noMaestroIncludeSources: MaestroSourceReader = (resolvedPath) => {
42+
throw new Error(`unexpected Maestro include read: ${resolvedPath}`);
43+
};

src/daemon/adapters/maestro/__tests__/daemon-runtime-port-identifier-hook.test.ts renamed to packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-identifier-hook.test.ts

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
import { expect, test } from 'vitest';
22
import { executeMaestroFlow, inspectMaestroFlow } from '@agent-device/maestro';
33
import type { SnapshotNode } from '@agent-device/kernel/snapshot';
4-
import { noMaestroIncludeSources } from '../../../../__tests__/test-utils/replay-script-source.ts';
54
import { createDaemonMaestroRuntimePort } from '../daemon-runtime-port.ts';
6-
import { makeBaseRequest, makeDependencies, makeSnapshot } from './daemon-runtime-port-fixtures.ts';
5+
import {
6+
makeRuntimeEnvelope,
7+
makeDependencies,
8+
makeSnapshot,
9+
noMaestroIncludeSources,
10+
} from './daemon-runtime-port-fixtures.ts';
711

812
const ON_SCREEN = { x: 18, y: 62, width: 366, height: 144 };
913
const BELOW_VIEWPORT = { x: 18, y: 2000, width: 366, height: 144 };
@@ -36,7 +40,7 @@ async function replay(
3640
rect: typeof ON_SCREEN,
3741
) {
3842
const port = createDaemonMaestroRuntimePort({
39-
baseReq: makeBaseRequest({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
43+
...makeRuntimeEnvelope({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
4044
invoke: async (request) =>
4145
request.command === 'snapshot'
4246
? { ok: true, data: makeSnapshot(hookCapture(rect, hittable)) }

src/daemon/adapters/maestro/__tests__/daemon-runtime-port-mutations.test.ts renamed to packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-mutations.test.ts

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
import { expect, test } from 'vitest';
22
import type { MaestroRuntimeCommand } from '@agent-device/maestro';
3-
import type { DaemonRequest } from '../../../daemon-request.ts';
3+
import type { MaestroDaemonOperationRequest } from '../daemon-runtime-public-operation.ts';
44
import { createDaemonMaestroRuntimePort } from '../daemon-runtime-port.ts';
55
import { MAESTRO_OBSERVATION_POLL_MS } from '../daemon-runtime-port-observation.ts';
6-
import { makeBaseRequest, makeDependencies } from './daemon-runtime-port-fixtures.ts';
6+
import { makeRuntimeEnvelope, makeDependencies } from './daemon-runtime-port-fixtures.ts';
77

88
test.each([
99
{
@@ -25,10 +25,10 @@ test.each([
2525
] satisfies { name: string; command: MaestroRuntimeCommand }[])(
2626
'settles $name before a following gesture',
2727
async ({ command }) => {
28-
const requests: DaemonRequest[] = [];
28+
const requests: MaestroDaemonOperationRequest[] = [];
2929
const clock = { value: 0 };
3030
const port = createDaemonMaestroRuntimePort({
31-
baseReq: makeBaseRequest({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
31+
...makeRuntimeEnvelope({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
3232
invoke: async (request) => {
3333
requests.push(request);
3434
return request.command === 'snapshot'
@@ -83,11 +83,11 @@ test.each([
8383
);
8484

8585
test('preserves mutation ordering after a failed dispatch is continued', async () => {
86-
const requests: DaemonRequest[] = [];
86+
const requests: MaestroDaemonOperationRequest[] = [];
8787
const clock = { value: 0 };
8888
let swipeAttempts = 0;
8989
const port = createDaemonMaestroRuntimePort({
90-
baseReq: makeBaseRequest({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
90+
...makeRuntimeEnvelope({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
9191
invoke: async (request) => {
9292
requests.push(request);
9393
if (request.command === 'gesture' && swipeAttempts++ === 0) {
@@ -141,10 +141,10 @@ test('preserves mutation ordering after a failed dispatch is continued', async (
141141
});
142142

143143
test('defers a pending mutation boundary across non-mutating runtime commands', async () => {
144-
const requests: DaemonRequest[] = [];
144+
const requests: MaestroDaemonOperationRequest[] = [];
145145
const clock = { value: 0 };
146146
const port = createDaemonMaestroRuntimePort({
147-
baseReq: makeBaseRequest({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
147+
...makeRuntimeEnvelope({ flags: { platform: 'ios', replayBackend: 'maestro' } }),
148148
invoke: async (request) => {
149149
requests.push(request);
150150
return request.command === 'snapshot'

src/daemon/adapters/maestro/__tests__/daemon-runtime-port-observation-input.test.ts renamed to packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-observation-input.test.ts

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
import { expect, test } from 'vitest';
2-
import type { DaemonRequest } from '../../../daemon-request.ts';
2+
import type { MaestroDaemonOperationRequest } from '../daemon-runtime-public-operation.ts';
33
import { createDaemonMaestroRuntimePort } from '../daemon-runtime-port.ts';
4-
import { makeBaseRequest, makeDependencies } from './daemon-runtime-port-fixtures.ts';
4+
import { makeRuntimeEnvelope, makeDependencies } from './daemon-runtime-port-fixtures.ts';
55

66
test.each([
77
[{ kind: 'inputText', source: { line: 2 }, text: 'hello' }, 'hello'],
88
[{ kind: 'eraseText', source: { line: 2 }, charactersToErase: 3 }, '\b\b\b'],
99
] as const)('waits for a stable snapshot after a Maestro $kind mutation', async (command, text) => {
10-
const requests: DaemonRequest[] = [];
10+
const requests: MaestroDaemonOperationRequest[] = [];
1111
let snapshots = 0;
1212
const port = createDaemonMaestroRuntimePort({
13-
baseReq: makeBaseRequest({ flags: { platform: 'android', replayBackend: 'maestro' } }),
13+
...makeRuntimeEnvelope({ flags: { platform: 'android', replayBackend: 'maestro' } }),
1414
invoke: async (request) => {
1515
requests.push(request);
1616
if (request.command !== 'snapshot') return { ok: true, data: {} };
@@ -52,9 +52,9 @@ test.each([
5252
});
5353

5454
test('propagates input stabilization failures after dispatch', async () => {
55-
const requests: DaemonRequest[] = [];
55+
const requests: MaestroDaemonOperationRequest[] = [];
5656
const port = createDaemonMaestroRuntimePort({
57-
baseReq: makeBaseRequest({ flags: { platform: 'android', replayBackend: 'maestro' } }),
57+
...makeRuntimeEnvelope({ flags: { platform: 'android', replayBackend: 'maestro' } }),
5858
invoke: async (request) => {
5959
requests.push(request);
6060
if (request.command === 'snapshot') {
@@ -81,11 +81,11 @@ test('propagates input stabilization failures after dispatch', async () => {
8181
});
8282

8383
test('commits Maestro input text before dispatching an immediate tap', async () => {
84-
const requests: DaemonRequest[] = [];
84+
const requests: MaestroDaemonOperationRequest[] = [];
8585
let snapshots = 0;
8686
let textCommitted = false;
8787
const port = createDaemonMaestroRuntimePort({
88-
baseReq: makeBaseRequest({ flags: { platform: 'android', replayBackend: 'maestro' } }),
88+
...makeRuntimeEnvelope({ flags: { platform: 'android', replayBackend: 'maestro' } }),
8989
invoke: async (request) => {
9090
requests.push(request);
9191
if (request.command === 'click') {

0 commit comments

Comments
 (0)