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
10 changes: 10 additions & 0 deletions .changeset/shared-desktop-service-recovery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
'@fluentui-react-native/desktop-test': patch
'@fluentui-react-native/desktop-driver': patch
'@fluentui-react-native/storybook-desktop': patch
---

Share native service construction between the generic supervisor and Storybook
channel child, wiring private durable settlement recovery, exact application-exit
probes, protected descriptor lifetime and settled shutdown. Keep corrupt sibling
journal records fenced rather than allowing a valid record to mask uncertainty.
38 changes: 19 additions & 19 deletions packages/agentic/desktop-driver/references/current-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,25 +19,25 @@ and its sub-issues, which record dependencies and parallel waves.

## Capabilities

| Capability | State | Boundary or remaining work |
| ---------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| W3C service and typed/WDIO clients | Done | Registered targets only; native browser-inapplicable commands explicitly unsupported. |
| Application-neutral driver | Done | No Storybook, React, or React Native dependency. Optional story provider is injected. |
| Native sessions and command/input queues | Done | One reservation per registered target in one service. Cross-service exact-application claims remain work in progress. |
| Verified private discovery and grants | Done | Native identity verified before credential transmission; all protected driver routes authenticate. Does not protect the separate Storybook channel. |
| Mutation effects, settlement, quarantine | Done | Native mutations settle before advancing. Uncertain story changes now quarantine instead of assuming a later render is safe. |
| Durable settlement storage and trusted recovery API | Done in library; integration in progress | Requires explicit `recovery` options. Shipped generic/Storybook supervisors do not yet wire them; restart can erase uncertainty. Do not use restart as recovery evidence. |
| Bounded observation, references, paging, deltas | Done | Provider capability/budget checks, explicit completeness and truncation. Reference generation is session-local; reopen after application replacement. |
| Find, action, check, sequence | Done | Up to eight sequence steps; request-id outcomes prevent replay within their retained session history. No replay across service replacement. |
| Capture and artifact pages | Done | Session-bound bounded artifacts and hashes; pixels are opt-in. Screenshots are evidence, not visual comparison. |
| Named accessibility actions | Done in agent operations | WDIO can list actions but has no corresponding named-action invocation command. |
| Story catalog/select/reset | Done, experimental integration | Catalog-only IDs, correlated readiness and marker verification. Delayed/unknown failures fence mutations. |
| Story args on protected driver | Intentionally unsupported | `story-args-unsupported`; legacy unprotected args remain separate. |
| Exclusive Storybook control | Work in progress | Channel selection/prepare ingress can bypass driver authority; out-of-band args/context invalidation is incomplete. |
| Supervisor crash containment and automatic reclaim | Work in progress outside driver | Exact ownership ledger, surviving-resource reconciliation, and lifelines belong to desktop-test. |
| Application-exit/reconnect continuity | Work in progress | No transparent app/session or runtime bridge restoration. Events are advisory, not proof of recovery. |
| Recording/replay export, event-tail API, visual comparison | Work in progress/deferred | No agent-session-to-WDIO export; window-events still returns its full bounded ring. |
| Intel macOS and distributed/remote control | Unsupported | Current macOS helper is arm64; service is loopback-only. |
| Capability | State | Boundary or remaining work |
| ---------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| W3C service and typed/WDIO clients | Done | Registered targets only; native browser-inapplicable commands explicitly unsupported. |
| Application-neutral driver | Done | No Storybook, React, or React Native dependency. Optional story provider is injected. |
| Native sessions and command/input queues | Done | One reservation per registered target in one service. Cross-service exact-application claims remain work in progress. |
| Verified private discovery and grants | Done | Native identity verified before credential transmission; all protected driver routes authenticate. Does not protect the separate Storybook channel. |
| Mutation effects, settlement, quarantine | Done | Native mutations settle before advancing. Uncertain story changes now quarantine instead of assuming a later render is safe. |
| Durable settlement storage and trusted recovery API | Done | Generic/Storybook native paths share the harness factory's private storage and exact-incarnation probes. Direct library embedders must pass `recovery`; restart is not proof. |
| Bounded observation, references, paging, deltas | Done | Provider capability/budget checks, explicit completeness and truncation. Reference generation is session-local; reopen after application replacement. |
| Find, action, check, sequence | Done | Up to eight sequence steps; request-id outcomes prevent replay within their retained session history. No replay across service replacement. |
| Capture and artifact pages | Done | Session-bound bounded artifacts and hashes; pixels are opt-in. Screenshots are evidence, not visual comparison. |
| Named accessibility actions | Done in agent operations | WDIO can list actions but has no corresponding named-action invocation command. |
| Story catalog/select/reset | Done, experimental integration | Catalog-only IDs, correlated readiness and marker verification. Delayed/unknown failures fence mutations. |
| Story args on protected driver | Intentionally unsupported | `story-args-unsupported`; legacy unprotected args remain separate. |
| Exclusive Storybook control | Work in progress | Channel selection/prepare ingress can bypass driver authority; out-of-band args/context invalidation is incomplete. |
| Supervisor crash containment and automatic reclaim | Work in progress outside driver | Exact ownership ledger, surviving-resource reconciliation, and lifelines belong to desktop-test. |
| Application-exit/reconnect continuity | Work in progress | No transparent app/session or runtime bridge restoration. Events are advisory, not proof of recovery. |
| Recording/replay export, event-tail API, visual comparison | Work in progress/deferred | No agent-session-to-WDIO export; window-events still returns its full bounded ring. |
| Intel macOS and distributed/remote control | Unsupported | Current macOS helper is arm64; service is loopback-only. |

The approved direction is a stronger `desktop-test` workload host, with native
authority here and MCP as a client. No coordinator package or daemon is being
Expand Down
8 changes: 8 additions & 0 deletions packages/agentic/desktop-driver/references/service.md
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,11 @@ does and does not cover.

## Persist quarantines

The generic desktop-test supervisor and Storybook's native channel child use
the shared `@fluentui-react-native/desktop-test/driver-service` factory, which
wires private storage and exact application-incarnation probes by default.
The following explicit options are required only for direct driver embedders.

Pass `recovery` so a target quarantined by an unsettled mutation stays
quarantined across a service restart:

Expand All @@ -362,6 +367,9 @@ await service.recoverTarget('contoso-macos', { evidence: 'operator', quarantineI
`evidence: 'operator'` records the operator's own judgment.
- Without a probe, an attached application's quarantine lifts only through
`recoverTarget`.
- Unreadable storage prevents startup. Any corrupt record, including a corrupt
sibling of an otherwise valid record, quarantines without trusting application
identity; an exit probe cannot clear it.
- On Windows, pass `createWindowsApplicationProbe({ artifact })` and
`await createWindowsPrivateStorage({ artifact, root })` with the verified
Windows native driver artifact.
Expand Down
38 changes: 38 additions & 0 deletions packages/agentic/desktop-driver/src/server/recovery.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,44 @@ describe('Desktop Driver settlement journal', () => {
expect(storage.records.size).toBe(0);
});

test.each(['mutation', 'quarantine'])('a valid sibling cannot hide a corrupt %s record from recovery', async (kind) => {
const storage = new MemoryStorage();
const service = await startService(storage);
await quarantineByLostClick(service);
await service.harness.close();
// Lost-response quarantine normally retains only the quarantine record. Add its mutation sibling to exercise both.
const [quarantineName, contents] = [...storage.records.entries()].find(([name]) => name.startsWith('quarantine-'))!;
const record = JSON.parse(contents) as Record<string, unknown>;
const mutationName = quarantineName.replace('quarantine-', 'mutation-');
storage.records.set(
mutationName,
JSON.stringify({
application: record.application,
command: record.command,
id: record.id,
kind: 'mutation',
sessionId: record.sessionId,
since: record.since,
targetId: record.targetId,
version: 1,
}),
);
storage.records.set(kind === 'mutation' ? mutationName : quarantineName, '{"corrupt":true}');
const probe = jest.fn(async (): Promise<ApplicationState> => 'exited');
const restarted = await startService(storage, {}, probe);
await expect(restarted.open()).rejects.toMatchObject(quarantinedOnOpen);
const quarantine = restarted.harness.server.sessions.getQuarantine(restarted.harness.target.id)!;
expect(quarantine.application).toBeUndefined();
await expect(
restarted.harness.server.recoverTarget(restarted.harness.target.id, {
evidence: 'application-exited',
quarantineId: quarantine.id,
}),
).rejects.toThrow(/not proven/);
expect(probe).not.toHaveBeenCalled();
expect(storage.records.size).toBe(2);
});

test('quarantines the target when it cannot record that a mutation settled', async () => {
const storage = new MemoryStorage();
const service = await startService(storage);
Expand Down
26 changes: 13 additions & 13 deletions packages/agentic/desktop-driver/src/server/settlementJournal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -116,25 +116,25 @@ export class SettlementJournal {
return undefined;
}
this.held.set(targetId, { ...(mutation !== undefined ? { mutation } : {}), ...(quarantine !== undefined ? { quarantine } : {}) });
if (quarantine !== undefined) {
const parsed = parseRecord(quarantineSchema, quarantine, targetId);
if (parsed) {
const { kind: _kind, version: _version, ...record } = parsed;
const parsedQuarantine = quarantine === undefined ? undefined : parseRecord(quarantineSchema, quarantine, targetId);
const parsedMutation = mutation === undefined ? undefined : parseRecord(mutationSchema, mutation, targetId);
// A readable sibling cannot establish which application's effects an unreadable record represents.
const corrupt = (quarantine !== undefined && !parsedQuarantine) || (mutation !== undefined && !parsedMutation);
if (!corrupt) {
if (parsedQuarantine) {
const { kind: _kind, version: _version, ...record } = parsedQuarantine;
return record;
}
}
if (mutation !== undefined) {
const parsed = parseRecord(mutationSchema, mutation, targetId);
if (parsed) {
if (parsedMutation) {
return {
...(parsed.application ? { application: parsed.application } : {}),
command: parsed.command,
...(parsedMutation.application ? { application: parsedMutation.application } : {}),
command: parsedMutation.command,
effect: 'unknown',
id: parsed.id,
id: parsedMutation.id,
message: 'The service stopped before this mutation settled.',
origin: 'interrupted',
sessionId: parsed.sessionId,
since: parsed.since,
sessionId: parsedMutation.sessionId,
since: parsedMutation.since,
targetId,
};
}
Expand Down
2 changes: 2 additions & 0 deletions packages/agentic/desktop-test/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ and bounded structured output contract.
coverage.
- Keep published API changes explicit and update the owning reference with the
implementation.
- Keep generic and Storybook service composition in `src/driverService.ts`;
never bypass its durable recovery, descriptor lifetime or settled close.

## Validation

Expand Down
3 changes: 3 additions & 0 deletions packages/agentic/desktop-test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ when working on the package.
artifact directory.
- Native helpers are explicitly built or provisioned; normal test runs use
verified prebuilt helpers only.
- Generic and Storybook native services share one factory with durable
quarantine storage and exact application-exit probes. Restart does not clear
uncertain effects; see [lifecycle and recovery](references/lifecycle.md).

macOS RN Test App users must bundle before `prep`, then build: CocoaPods embeds
only resources that exist during `pod install`. Renderer changes require a new
Expand Down
5 changes: 5 additions & 0 deletions packages/agentic/desktop-test/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@
"import": "./lib/commands.js",
"default": "./src/commands.ts"
},
"./driver-service": {
"types": "./lib/driverService.d.ts",
"import": "./lib/driverService.js",
"default": "./src/driverService.ts"
},
"./wdio": {
"types": "./lib/wdio/index.d.ts",
"import": "./lib/wdio/index.js",
Expand Down
4 changes: 3 additions & 1 deletion packages/agentic/desktop-test/references/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ owner_paths:

Configuration and host adapters live in `src/config.ts` and `src/adapters.ts`;
CLI stages are composed in `src/cli.ts`; process ownership is in
`src/supervisor.ts`; reports are implemented in `src/reporting/`; and WDIO
`src/supervisor.ts`; shared native service, recovery, authority, descriptor and
settled shutdown composition lives in the real `src/driverService.ts` module
(also used by the Storybook channel child); reports are implemented in `src/reporting/`; and WDIO
session wiring is in `src/wdio/`.

Add contract coverage for schema, lifecycle, reporting protocol, and failure
Expand Down
Loading
Loading