Skip to content

Commit 870cf66

Browse files
committed
Merge remote-tracking branch 'origin/main' into refactor/host-environment
* origin/main: fix: align replay, SDK, and session boundaries with ADRs (#3762) fix(daemon-client): document the drain timeout and tighten ensureDaemon follow-ups (#3783) # Conflicts: # CHANGELOG.md
2 parents 597f793 + a60fe5a commit 870cf66

42 files changed

Lines changed: 482 additions & 183 deletions

Some content is hidden

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

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
## Unreleased
44

55
- Behavior change: `resolveHubAppReference`, shipped through `agent-device/plugins/webdriver`, now needs `cwd` to resolve a relative app path. Without it the call fails with `INVALID_ARGS` and `details.reason: provider_app_cwd_missing`; it used to resolve against the process's working directory. Absolute paths, URLs and provider references are unaffected. The daemon fills it from the client's working directory (or its host's) for every provider lease request, so `connect` and `lease_allocate` are unchanged.
6+
- The `daemon-not-running` hint now always names `--state-dir <dir>`, and a daemon force-retired for outlasting its drain is reported as `Replaced unreachable daemon` instead of `Replaced idle daemon`. `daemon-drain-timeout` and the post-drain force retire are documented in the client API and `help`.
67
- Fix `ensureDaemon()`, the CLI and MCP killing a daemon they had just asked to leave. After the daemon answers the quiesce request with `draining`, the client now waits up to 60 s for it to exit by itself and clean up its registration, so plugin disposal and lease finalization finish (on Windows a signal ends the process outright, and on POSIX a drain longer than 3 s was killed). A daemon still running at the deadline that fails its liveness probes is force-retired; one that still answers is left running and the call fails with `details.reason: 'daemon-drain-timeout'`, with a hint naming `agent-device daemon stop --state-dir <path>`.
78
- `@agent-device/testmu` is now a version 2 provider plugin. `import testmu from '@agent-device/testmu'` gives a factory, `testmu({ credentials: { username, accessKey } })`, that reads those credentials instead of `LT_USERNAME` and `LT_ACCESS_KEY`; without options it reads the variables as before. The package still declares the version 1 plugin entry, so `agent-device plugins add @agent-device/testmu` keeps working on hosts that predate the version 2 contract.
89
- Provider plugins have a new contract. A package exports a factory at `./agent-device` that returns `{ apiVersion: 2, provider, credentials, connection?, setup(host) }`, typed by `AgentDevicePluginFactory` from `agent-device/plugins`. The store calls the factory with the package's `config.json` options, and a JavaScript host can call it directly. Version 1 plugins (`agentDevicePlugin.apiVersion: 1`) keep loading.

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The registries and tests named there are the living source of truth.
2323

2424
1. **`--update` never rewrites.**
2525
The candidate machinery of heal only ranks the bounded `suggestions` list inside a divergence report.
26-
The order is identity components, then the same `scrollRegion`, then document order.
26+
The order is identity components, then the same `scrollRegion` for a verified `target-v1` annotation, then document order.
2727
The list is deduplicated by node.
2828
No unattended repair path exists.
2929
2. **Every element resolution discloses how it resolved.**
@@ -98,7 +98,7 @@ They do not act unattended.
9898

9999
1. Candidates that satisfy more identity components rank first.
100100
A recorded-id match precedes a role+label match. A role+label match precedes a label-only match.
101-
2. Among equal candidates, candidates in the same `scrollRegion` as recorded rank before candidates in other regions.
101+
2. For a verified `target-v1` annotation, equally strong candidates in the recorded `scrollRegion` rank before candidates in other regions.
102102
3. Document order resolves the remaining ties.
103103

104104
Suggestions are deduplicated by node.

‎packages/contracts/src/client-connection.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,8 @@ export type EnsureDaemonOptions = {
5252
* usable daemon was registered; `incompatible` means a daemon this client cannot use was
5353
* replaced after it agreed to leave. `previous` is the daemon that was replaced, when there was
5454
* one: a `missing` start with a `previous` replaced a registered daemon that answered nothing,
55-
* either unreachable or hung and force-retired.
55+
* either unreachable or hung and force-retired, or one that agreed to leave but outlasted its drain
56+
* and was force-retired.
5657
*/
5758
onStart?: (reason: 'missing' | 'incompatible', previous?: DaemonIdentity) => void;
5859
};

‎packages/daemon/src/core/session-store.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import {
33
resolveSessionAppLogPath,
44
resolveSessionAppLogPidPath,
55
} from '@agent-device/daemon-contracts/session-artifact-paths';
6+
import { DAEMON_SHUTTING_DOWN_REASON } from '@agent-device/daemon-contracts/daemon-resolution';
67
import path from 'node:path';
78
import fs from 'node:fs';
89
import { AppError } from '@agent-device/kernel/errors';
@@ -74,7 +75,7 @@ export class SessionStore {
7475
assertAdmissionOpen(address: string): void {
7576
if (!this.acceptingSessions) {
7677
throw new AppError('COMMAND_FAILED', 'Daemon is shutting down', {
77-
reason: 'daemon_shutting_down',
78+
reason: DAEMON_SHUTTING_DOWN_REASON,
7879
session: address,
7980
});
8081
}

‎packages/daemon/src/server/__tests__/request-execution-scope.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ import {
2727
bindTestCommandHost,
2828
} from '@agent-device/test-kit';
2929
import { makeTestScreenRecordingResource } from '../../__tests__/support/screen-recording-live-handle.ts';
30-
import { handleSessionCloseCommands } from '../../sessions/session-lifecycle/index.ts';
30+
import { handleSessionCloseCommands } from '../../sessions/session-lifecycle/internal/session-close.ts';
3131

3232
bindTestCommandHost();
3333

‎packages/daemon/src/sessions/__tests__/replay-divergence/session-replay-divergence-suggestions.test.ts‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,78 @@ test('buildReplayFailureDivergence dedupes suggestions using the strongest basis
7373
expect(divergence.suggestions[0]?.ref).toBe('e1');
7474
expect(divergence.suggestions[0]?.basis).toBe('id');
7575
});
76+
77+
test.each(['region', 'absent', 'none', 'unverifiable'] as const)(
78+
'suggestions rank identity, recorded region, then document order (evidence: %s)',
79+
async (evidence) => {
80+
const root = mkdtempForTestSync('agent-device-replay-suggest-region-');
81+
const sessionStore = new SessionStore(path.join(root, 'sessions'));
82+
sessionStore.publish('default', makeIosSession('default', { appBundleId: 'com.example.app' }));
83+
const button = (index: number, parentIndex: number, label: string) => ({
84+
index,
85+
parentIndex,
86+
depth: 1,
87+
type: 'Button',
88+
label,
89+
rect: { x: 0, y: index * 10, width: 100, height: 44 },
90+
hittable: true,
91+
});
92+
mockDispatchCommand.mockResolvedValue({
93+
nodes: [
94+
{ index: 0, depth: 0, type: 'ScrollView', identifier: 'other' },
95+
button(1, 0, 'Other'),
96+
{ ...button(2, 0, 'Strong'), identifier: 'strong' },
97+
{ index: 3, depth: 0, type: 'ScrollView', identifier: 'recorded' },
98+
button(4, 3, 'First'),
99+
button(5, 3, 'Second'),
100+
{ ...button(6, 0, 'Outside'), parentIndex: undefined, depth: 0 },
101+
],
102+
truncated: false,
103+
backend: 'xctest',
104+
});
105+
const action = {
106+
ts: 0,
107+
command: 'click',
108+
positionals: ['label="Other"'],
109+
flags: {},
110+
result: {
111+
selectorChain: ['label="Second"', 'label="First"', 'id="strong"', 'label="Outside"'],
112+
},
113+
...(evidence !== 'absent'
114+
? {
115+
targetEvidence: {
116+
role: 'button',
117+
label: 'Original',
118+
ancestry: [],
119+
sibling: 0,
120+
viewportOrder: 0,
121+
...(evidence === 'region' || evidence === 'unverifiable'
122+
? { scrollRegion: { role: 'scrollview', id: 'recorded' } }
123+
: {}),
124+
verification:
125+
evidence === 'unverifiable' ? ('unverifiable' as const) : ('verified' as const),
126+
},
127+
}
128+
: {}),
129+
};
130+
const divergence = await buildReplayFailureDivergence({
131+
error: { code: 'COMMAND_FAILED', message: 'not hittable' },
132+
action,
133+
index: 0,
134+
sourcePath: path.join(root, 'flow.ad'),
135+
sourceLine: 1,
136+
...replayDivergenceForTest(sessionStore, 'default'),
137+
logPath: path.join(root, 'daemon.log'),
138+
responseLevel: 'full',
139+
planActions: [action],
140+
planDigest: 'test-plan-digest',
141+
});
142+
expect(divergence.suggestions.map(({ label }) => label)).toEqual(
143+
evidence === 'region'
144+
? ['Strong', 'First', 'Second', 'Other', 'Outside']
145+
: evidence === 'none'
146+
? ['Strong', 'Outside', 'Other', 'First', 'Second']
147+
: ['Strong', 'Other', 'First', 'Second', 'Outside'],
148+
);
149+
},
150+
);

‎packages/daemon/src/sessions/__tests__/replay-maestro/session-replay-maestro-failure.test.ts‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -443,6 +443,65 @@ test('typed Maestro text matching an identifier reports id basis', async () => {
443443
expect(divergence.suggestions).toEqual([expect.objectContaining({ basis: 'id' })]);
444444
});
445445

446+
test('typed Maestro failure ranks by identity and document order across scroll regions', async () => {
447+
const command = {
448+
kind: 'tapOn' as const,
449+
source: { path: '/flows/actions.yaml', line: 4 },
450+
target: { space: 'target' as const, selector: { text: 'save.*' } },
451+
} satisfies Extract<MaestroRuntimeCommand, { kind: 'tapOn' }>;
452+
const response = await buildFailureResponse(command, [
453+
{
454+
index: 0,
455+
type: 'Application',
456+
rect: { x: 0, y: 0, width: 402, height: 874 },
457+
},
458+
{
459+
index: 1,
460+
parentIndex: 0,
461+
identifier: 'actions',
462+
type: 'ScrollView',
463+
rect: { x: 0, y: 0, width: 402, height: 300 },
464+
},
465+
{
466+
index: 2,
467+
parentIndex: 1,
468+
type: 'Button',
469+
label: 'Save in list',
470+
rect: { x: 16, y: 40, width: 140, height: 44 },
471+
hittable: true,
472+
},
473+
{
474+
index: 3,
475+
parentIndex: 0,
476+
type: 'Button',
477+
label: 'Save outside',
478+
rect: { x: 16, y: 350, width: 140, height: 44 },
479+
hittable: true,
480+
},
481+
{
482+
index: 4,
483+
parentIndex: 0,
484+
type: 'Button',
485+
identifier: 'save-primary',
486+
label: 'Confirm',
487+
rect: { x: 16, y: 410, width: 140, height: 44 },
488+
hittable: true,
489+
},
490+
]);
491+
const divergence = response.error.details?.divergence as {
492+
screen: { state: string };
493+
suggestions: Array<{ basis: string; label: string }>;
494+
};
495+
496+
expect(response.error.code).toBe('REPLAY_DIVERGENCE');
497+
expect(divergence.screen.state).toBe('available');
498+
expect(divergence.suggestions.map(({ basis, label }) => [basis, label])).toEqual([
499+
['id', 'Confirm'],
500+
['label', 'Save in list'],
501+
['label', 'Save outside'],
502+
]);
503+
});
504+
446505
test('typed Maestro suggestions retain total count before the five-entry cap', async () => {
447506
const command = {
448507
kind: 'tapOn' as const,

‎packages/daemon/src/sessions/__tests__/replay-repair/session-replay-repair-record-exclusion.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ vi.mock('../../../core/snapshot-interactor-capture.ts', () => ({
4949
import fs from 'node:fs';
5050
import path from 'node:path';
5151
import { runReplayForTest } from '../replay-runtime/replay-command-fixture.ts';
52-
import { handleSessionCloseCommands as handleProductionCloseCommand } from '../../session-lifecycle/index.ts';
52+
import { handleSessionCloseCommands as handleProductionCloseCommand } from '../../session-lifecycle/internal/session-close.ts';
5353
import { SessionStore } from '../../../core/session-store.ts';
5454
import { LeaseRegistry } from '../../../resources/lease-registry.ts';
5555
import { captureSnapshotWithInteractor } from '../../../core/snapshot-interactor-capture.ts';

‎packages/daemon/src/sessions/__tests__/replay-repair/session-replay-repair-transaction.fixtures.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import {
77
makeRepairCompleteSession,
88
repairPublication,
99
} from '../../../__tests__/support/session-factories.ts';
10-
import { handleSessionCloseCommands as handleProductionCloseCommand } from '../../session-lifecycle/index.ts';
10+
import { handleSessionCloseCommands as handleProductionCloseCommand } from '../../session-lifecycle/internal/session-close.ts';
1111
import {
1212
bindLifecycleRuntime,
1313
inspectLifecycleRuntimeFacts,

‎packages/daemon/src/sessions/handlers/__tests__/session-device-claims.test.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,8 @@ import {
5757
} from '@agent-device/daemon-contracts/device-claims';
5858
import { LeaseRegistry } from '../../../resources/lease-registry.ts';
5959
import { SessionStore } from '../../../core/session-store.ts';
60-
import {
61-
handleSessionCloseCommands as handleProductionCloseCommand,
62-
handleSessionOpenCommands as handleProductionOpenCommand,
63-
} from '../../session-lifecycle/index.ts';
60+
import { handleSessionCloseCommands as handleProductionCloseCommand } from '../../session-lifecycle/internal/session-close.ts';
61+
import { handleSessionOpenCommands as handleProductionOpenCommand } from '../../session-lifecycle/internal/session-open.ts';
6462
import type { DeviceInfo } from '@agent-device/kernel/device';
6563
import { makeAuthoringSession } from '../../../__tests__/support/session-factories.ts';
6664
import { AppError } from '@agent-device/kernel/errors';

0 commit comments

Comments
 (0)