Skip to content

Commit 0cfecf0

Browse files
JasonVMoCopilot
andauthored
feat(desktop-driver): enforce neutral package boundaries (#4454)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent ccb458e commit 0cfecf0

20 files changed

Lines changed: 260 additions & 42 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@fluentui-react-native/desktop-driver': patch
3+
'@fluentui-react-native/desktop-test': patch
4+
'@fluentui-react-native/desktop-driver-mcp': patch
5+
---
6+
7+
Add a dedicated native helper entry to desktop-driver and enforce the neutral desktop package dependency boundary with standalone consumer contracts.

‎packages/agentic/desktop-driver-mcp/references/connection.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -92,13 +92,15 @@ process lives and reports to stderr. Service drain/expiry is still needed when
9292
the adapter cannot confirm deletion. `--help` and `--version` write to stderr so stdout
9393
carries only protocol.
9494

95-
The adapter resolves the native helper with source builds disabled. The helper
96-
must already be cached by `desktop-driver resolve-driver` or `build-driver`, or
97-
named by `FURN_DESKTOP_DRIVER_HELPER_PATH` or
98-
`FURN_DESKTOP_DRIVER_INSTALL_ROOT`. The helper verifies that the process
99-
listening at the descriptor's URL is the one the supervisor described, on the
100-
same user and interactive session, before the grant leaves the adapter. The
101-
service then confirms its incarnation.
95+
The adapter imports helper resolution from the driver's `/native` entry and
96+
uses the driver's `/authority`, `/client`, and `/operations` entries rather
97+
than loading its root and WebdriverIO integration. It resolves the native
98+
helper with source builds disabled. The helper must already be cached by
99+
`desktop-driver resolve-driver` or `build-driver`, or named by
100+
`FURN_DESKTOP_DRIVER_HELPER_PATH` or `FURN_DESKTOP_DRIVER_INSTALL_ROOT`. The
101+
helper verifies that the process listening at the descriptor's URL is the one
102+
the supervisor described, on the same user and interactive session, before the
103+
grant leaves the adapter. The service then confirms its incarnation.
102104

103105
## Connecting lazily and reconnecting
104106

‎packages/agentic/desktop-driver-mcp/references/current-status.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,21 @@ and the generalized management facet is
1919

2020
## Capability matrix
2121

22-
| Capability | State | Boundary/remaining work |
23-
| ------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24-
| Six tools over shared driver schemas | Done | Session, observe, act, check, capture, story. No separate execution path. |
25-
| Private descriptor and native identity verification | Done | Verifies before sending a grant. No model URL/token/config/executable input. |
26-
| Single-flight connection/session lifetime | Done | Serial acquisition, close, operations and resource reads; late acquisition after dispose is cleaned up. |
27-
| Same-port protected restart/revocation | Done in deterministic contracts | Invalid authority is forgotten; next call re-verifies discovery. No mutation replay. Live endpoint reruns remain required. |
28-
| Same-authority transport retry | Done, bounded semantics | Retain known session cleanup responsibility and rebind only after verification of the same incarnation/principal. This is not cross-MCP-connection resume. |
29-
| Lost create response | Fenced; recovery in progress | `session-uncertain`; no repeated acquisition. Operator must revoke the old grant or replace the service. No session-enumeration shortcut. |
30-
| Failed delete/disconnect | Done with limits | Keep known-session responsibility; bounded dispose wait leaves late cleanup attached. Unreachable-service cleanup cannot be guaranteed; service drain/expiry remains necessary. |
31-
| Launch-mode discovery | Done | Status lists effective launch/attach modes; no predictable attach-first failure against launch-only targets. |
32-
| Progress, cancellation, paged image resources | Done | Progress does not renew idle sessions; artifacts are session-bound and hash-checked. |
33-
| Storybook control | Experimental | Driver selection/marker path exists; channel ingress/reconnect and full exclusive context authority remain incomplete. |
34-
| Per-connection attenuated grants and resumable sessions | Work in progress | Current supervisor publishes one shared agent grant. Labels are not client isolation. |
35-
| Workload/test orchestration tools | Work in progress | Belong to a future harness control/client surface; adapter never becomes the resource owner. |
36-
| General MCP-client qualification | Work in progress | SDK stdio evidence exists; client-specific resource/image/cancellation behavior needs independent runs. |
22+
| Capability | State | Boundary/remaining work |
23+
| ------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24+
| Six tools over shared driver schemas | Done | Session, observe, act, check, capture, story. No separate execution path. |
25+
| Private descriptor and native identity verification | Done | Verifies before sending a grant. Uses the driver's `/native`, `/authority`, and `/client` subpaths, not its WebdriverIO-heavy root; boundary tests guard this dependency. No model URL/token/config/executable input. |
26+
| Single-flight connection/session lifetime | Done | Serial acquisition, close, operations and resource reads; late acquisition after dispose is cleaned up. |
27+
| Same-port protected restart/revocation | Done in deterministic contracts | Invalid authority is forgotten; next call re-verifies discovery. No mutation replay. Live endpoint reruns remain required. |
28+
| Same-authority transport retry | Done, bounded semantics | Retain known session cleanup responsibility and rebind only after verification of the same incarnation/principal. This is not cross-MCP-connection resume. |
29+
| Lost create response | Fenced; recovery in progress | `session-uncertain`; no repeated acquisition. Operator must revoke the old grant or replace the service. No session-enumeration shortcut. |
30+
| Failed delete/disconnect | Done with limits | Keep known-session responsibility; bounded dispose wait leaves late cleanup attached. Unreachable-service cleanup cannot be guaranteed; service drain/expiry remains necessary. |
31+
| Launch-mode discovery | Done | Status lists effective launch/attach modes; no predictable attach-first failure against launch-only targets. |
32+
| Progress, cancellation, paged image resources | Done | Progress does not renew idle sessions; artifacts are session-bound and hash-checked. |
33+
| Storybook control | Experimental | Driver selection/marker path exists; channel ingress/reconnect and full exclusive context authority remain incomplete. |
34+
| Per-connection attenuated grants and resumable sessions | Work in progress | Current supervisor publishes one shared agent grant. Labels are not client isolation. |
35+
| Workload/test orchestration tools | Work in progress | Belong to a future harness control/client surface; adapter never becomes the resource owner. |
36+
| General MCP-client qualification | Work in progress | SDK stdio evidence exists; client-specific resource/image/cancellation behavior needs independent runs. |
3737

3838
See [connection](connection.md) and [tools](tools.md) for exact behavior.
3939
Native and Storybook limitations are tracked in
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import { connectWithDescriptor } from './connection';
2+
3+
jest.mock('@fluentui-react-native/desktop-driver', () => {
4+
throw new Error('The MCP adapter must not load the desktop-driver root entry.');
5+
});
6+
7+
describe('desktop-driver-mcp connection imports', () => {
8+
test('loads its connection implementation without the desktop-driver root entry', () => {
9+
expect(connectWithDescriptor).toEqual(expect.any(Function));
10+
});
11+
});

‎packages/agentic/desktop-driver-mcp/src/connection.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { resolveNativeDesktopDriver } from '@fluentui-react-native/desktop-driver';
1+
import { resolveNativeDesktopDriver } from '@fluentui-react-native/desktop-driver/native';
22
import {
33
createMacOSPrivateStorage,
44
createMacOSServiceVerifier,

‎packages/agentic/desktop-driver/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ The [reference index](references/README.md) describes each package-owned guide.
146146
| `/wdio` | WebdriverIO connection, custom commands, assertions, and story-plan runner |
147147
| `/client` | Low-level typed W3C client |
148148
| `/authority` | Grants, private connection descriptors, and macOS owner-validated storage |
149+
| `/native` | Native-helper build, resolution, and verification without loading the package root |
149150
| `/server` | Embeddable remote end, session manager, and target registry |
150151
| `/agent` | Bounded JSON-safe inspection, action, and evidence API |
151152
| `/operations` | Versioned agent operation catalog, executor, and result types |

‎packages/agentic/desktop-driver/package.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,11 @@
6868
"import": "./lib/authority/index.js",
6969
"default": "./src/authority/index.ts"
7070
},
71+
"./native": {
72+
"types": "./lib/native/nativeDriver.d.ts",
73+
"import": "./lib/native/nativeDriver.js",
74+
"default": "./src/native/nativeDriver.ts"
75+
},
7176
"./operations": {
7277
"types": "./lib/operations/index.d.ts",
7378
"import": "./lib/operations/index.js",

‎packages/agentic/desktop-driver/references/current-status.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ and its sub-issues, which record dependencies and parallel waves.
2222
| Capability | State | Boundary or remaining work |
2323
| ---------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2424
| W3C service and typed/WDIO clients | Done | Registered targets only; native browser-inapplicable commands explicitly unsupported. |
25-
| Application-neutral driver | Done | No Storybook, React, or React Native dependency. Optional story provider is injected. |
25+
| Application-neutral driver | Done | No Storybook, React, or React Native dependency; package-boundary tests reject forbidden imports/dependencies. Optional story provider is injected. |
2626
| Native sessions and command/input queues | Done | One reservation per registered target in one service. Cross-service exact-application claims remain work in progress. |
2727
| Verified private discovery and grants | Done | Native identity verified before credential transmission; all protected driver routes authenticate. Does not protect the separate Storybook channel. |
2828
| Mutation effects, settlement, quarantine | Done | Native mutations settle before advancing. Uncertain story changes now quarantine instead of assuming a later render is safe. |

‎packages/agentic/desktop-driver/references/native-helpers.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ The package ships checked-in native source and builds one small helper on the
1313
target operating system. Native binaries are not published in npm, compiled
1414
during installation, or downloaded automatically.
1515

16+
Applications that only need helper build, resolution, or verification can
17+
import those functions from
18+
`@fluentui-react-native/desktop-driver/native`. This entry maps directly to
19+
the helper implementation and avoids loading the package root and its
20+
WebdriverIO integration.
21+
1622
Windows and Win32 share the C++ x64 provider. macOS uses the Swift arm64
1723
provider. Both implement the private
1824
[FDR1 framed stdio protocol](../native/PROTOCOL.md) behind the same
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import { existsSync, readFileSync } from 'node:fs';
2+
import path from 'node:path';
3+
4+
type ExportConditions = {
5+
types?: string;
6+
import?: string;
7+
default?: string;
8+
};
9+
10+
describe('desktop-driver native entry', () => {
11+
test('exposes the helper implementation as a dedicated package subpath', () => {
12+
const packageRoot = path.resolve(__dirname, '../..');
13+
const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as {
14+
exports: Record<string, ExportConditions>;
15+
};
16+
const nativeEntry = manifest.exports['./native'];
17+
18+
expect(nativeEntry).toEqual({
19+
types: './lib/native/nativeDriver.d.ts',
20+
import: './lib/native/nativeDriver.js',
21+
default: './src/native/nativeDriver.ts',
22+
});
23+
expect(existsSync(path.join(packageRoot, nativeEntry.default ?? ''))).toBe(true);
24+
expect(existsSync(path.join(packageRoot, nativeEntry.types ?? ''))).toBe(true);
25+
});
26+
});

0 commit comments

Comments
 (0)