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

Add a dedicated native helper entry to desktop-driver and enforce the neutral desktop package dependency boundary with standalone consumer contracts.
16 changes: 9 additions & 7 deletions packages/agentic/desktop-driver-mcp/references/connection.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,13 +92,15 @@ process lives and reports to stderr. Service drain/expiry is still needed when
the adapter cannot confirm deletion. `--help` and `--version` write to stderr so stdout
carries only protocol.

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

## Connecting lazily and reconnecting

Expand Down
30 changes: 15 additions & 15 deletions packages/agentic/desktop-driver-mcp/references/current-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,21 +19,21 @@ and the generalized management facet is

## Capability matrix

| Capability | State | Boundary/remaining work |
| ------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Six tools over shared driver schemas | Done | Session, observe, act, check, capture, story. No separate execution path. |
| Private descriptor and native identity verification | Done | Verifies before sending a grant. No model URL/token/config/executable input. |
| Single-flight connection/session lifetime | Done | Serial acquisition, close, operations and resource reads; late acquisition after dispose is cleaned up. |
| 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. |
| 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. |
| 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. |
| 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. |
| Launch-mode discovery | Done | Status lists effective launch/attach modes; no predictable attach-first failure against launch-only targets. |
| Progress, cancellation, paged image resources | Done | Progress does not renew idle sessions; artifacts are session-bound and hash-checked. |
| Storybook control | Experimental | Driver selection/marker path exists; channel ingress/reconnect and full exclusive context authority remain incomplete. |
| Per-connection attenuated grants and resumable sessions | Work in progress | Current supervisor publishes one shared agent grant. Labels are not client isolation. |
| Workload/test orchestration tools | Work in progress | Belong to a future harness control/client surface; adapter never becomes the resource owner. |
| General MCP-client qualification | Work in progress | SDK stdio evidence exists; client-specific resource/image/cancellation behavior needs independent runs. |
| Capability | State | Boundary/remaining work |
| ------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Six tools over shared driver schemas | Done | Session, observe, act, check, capture, story. No separate execution path. |
| 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. |
| Single-flight connection/session lifetime | Done | Serial acquisition, close, operations and resource reads; late acquisition after dispose is cleaned up. |
| 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. |
| 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. |
| 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. |
| 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. |
| Launch-mode discovery | Done | Status lists effective launch/attach modes; no predictable attach-first failure against launch-only targets. |
| Progress, cancellation, paged image resources | Done | Progress does not renew idle sessions; artifacts are session-bound and hash-checked. |
| Storybook control | Experimental | Driver selection/marker path exists; channel ingress/reconnect and full exclusive context authority remain incomplete. |
| Per-connection attenuated grants and resumable sessions | Work in progress | Current supervisor publishes one shared agent grant. Labels are not client isolation. |
| Workload/test orchestration tools | Work in progress | Belong to a future harness control/client surface; adapter never becomes the resource owner. |
| General MCP-client qualification | Work in progress | SDK stdio evidence exists; client-specific resource/image/cancellation behavior needs independent runs. |

See [connection](connection.md) and [tools](tools.md) for exact behavior.
Native and Storybook limitations are tracked in
Expand Down
11 changes: 11 additions & 0 deletions packages/agentic/desktop-driver-mcp/src/connection.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import { connectWithDescriptor } from './connection';

jest.mock('@fluentui-react-native/desktop-driver', () => {
throw new Error('The MCP adapter must not load the desktop-driver root entry.');
});

describe('desktop-driver-mcp connection imports', () => {
test('loads its connection implementation without the desktop-driver root entry', () => {
expect(connectWithDescriptor).toEqual(expect.any(Function));
});
});
2 changes: 1 addition & 1 deletion packages/agentic/desktop-driver-mcp/src/connection.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { resolveNativeDesktopDriver } from '@fluentui-react-native/desktop-driver';
import { resolveNativeDesktopDriver } from '@fluentui-react-native/desktop-driver/native';
import {
createMacOSPrivateStorage,
createMacOSServiceVerifier,
Expand Down
1 change: 1 addition & 0 deletions packages/agentic/desktop-driver/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ The [reference index](references/README.md) describes each package-owned guide.
| `/wdio` | WebdriverIO connection, custom commands, assertions, and story-plan runner |
| `/client` | Low-level typed W3C client |
| `/authority` | Grants, private connection descriptors, and macOS owner-validated storage |
| `/native` | Native-helper build, resolution, and verification without loading the package root |
| `/server` | Embeddable remote end, session manager, and target registry |
| `/agent` | Bounded JSON-safe inspection, action, and evidence API |
| `/operations` | Versioned agent operation catalog, executor, and result types |
Expand Down
5 changes: 5 additions & 0 deletions packages/agentic/desktop-driver/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,11 @@
"import": "./lib/authority/index.js",
"default": "./src/authority/index.ts"
},
"./native": {
"types": "./lib/native/nativeDriver.d.ts",
"import": "./lib/native/nativeDriver.js",
"default": "./src/native/nativeDriver.ts"
},
"./operations": {
"types": "./lib/operations/index.d.ts",
"import": "./lib/operations/index.js",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ and its sub-issues, which record dependencies and parallel waves.
| 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. |
| Application-neutral driver | Done | No Storybook, React, or React Native dependency; package-boundary tests reject forbidden imports/dependencies. 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. |
Expand Down
6 changes: 6 additions & 0 deletions packages/agentic/desktop-driver/references/native-helpers.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@ The package ships checked-in native source and builds one small helper on the
target operating system. Native binaries are not published in npm, compiled
during installation, or downloaded automatically.

Applications that only need helper build, resolution, or verification can
import those functions from
`@fluentui-react-native/desktop-driver/native`. This entry maps directly to
the helper implementation and avoids loading the package root and its
WebdriverIO integration.

Windows and Win32 share the C++ x64 provider. macOS uses the Swift arm64
provider. Both implement the private
[FDR1 framed stdio protocol](../native/PROTOCOL.md) behind the same
Expand Down
26 changes: 26 additions & 0 deletions packages/agentic/desktop-driver/src/native/nativeExport.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import { existsSync, readFileSync } from 'node:fs';
import path from 'node:path';

type ExportConditions = {
types?: string;
import?: string;
default?: string;
};

describe('desktop-driver native entry', () => {
test('exposes the helper implementation as a dedicated package subpath', () => {
const packageRoot = path.resolve(__dirname, '../..');
const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as {
exports: Record<string, ExportConditions>;
};
const nativeEntry = manifest.exports['./native'];

expect(nativeEntry).toEqual({
types: './lib/native/nativeDriver.d.ts',
import: './lib/native/nativeDriver.js',
default: './src/native/nativeDriver.ts',
});
expect(existsSync(path.join(packageRoot, nativeEntry.default ?? ''))).toBe(true);
expect(existsSync(path.join(packageRoot, nativeEntry.types ?? ''))).toBe(true);
});
});
41 changes: 41 additions & 0 deletions packages/agentic/desktop-test/fixtures/neutral-boundary/loader.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
const workspaceEntryPoints = new Map([
['@fluentui-react-native/desktop-driver', new URL('../../../desktop-driver/lib/index.js', import.meta.url).href],
['@fluentui-react-native/desktop-test', new URL('../../../desktop-test/lib/index.js', import.meta.url).href],
['@fluentui-react-native/desktop-driver-mcp', new URL('../../../desktop-driver-mcp/lib/index.js', import.meta.url).href],
]);

const forbiddenPackages = new Set(['react', 'react-dom', 'react-native', 'storybook', '@types/react', '@types/react-native']);

function packageName(specifier) {
const segments = specifier.split('/');
return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
}

function isForbidden(specifier) {
const name = packageName(specifier);
return (
forbiddenPackages.has(name) ||
name.startsWith('@react-native/') ||
name.startsWith('@storybook/') ||
name.startsWith('@fluentui-react-native/storybook-') ||
name.startsWith('storybook-')
);
}

export async function resolve(specifier, context, nextResolve) {
if (isForbidden(specifier)) {
throw new Error(`Neutral package boundary rejected forbidden import: ${specifier}`);
}

if (specifier === '@fluentui-react-native/desktop-driver' && context.parentURL?.includes('/desktop-driver-mcp/')) {
throw new Error('Neutral package boundary rejected desktop-driver root import from the MCP adapter.');
}

const packageName = specifier.split('/').slice(0, 2).join('/');
const workspaceParentURL = workspaceEntryPoints.get(packageName);
if (workspaceParentURL) {
return nextResolve(specifier, { ...context, parentURL: workspaceParentURL });
}

return nextResolve(specifier, context);
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"dependencies": {
"react": "1.0.0",
"react-native": "1.0.0",
"@storybook/react": "1.0.0"
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
import 'react-native';
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
import 'react';
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
import '@storybook/react';
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { createDesktopDriverClient } from '@fluentui-react-native/desktop-driver/client';
import { DesktopAuthority } from '@fluentui-react-native/desktop-driver/authority';
import { resolveNativeDesktopDriver, verifyNativeDriverArtifact } from '@fluentui-react-native/desktop-driver/native';
import { describeOperations } from '@fluentui-react-native/desktop-driver/operations';
import { connectWithDescriptor } from '@fluentui-react-native/desktop-driver-mcp';
import { defineDesktopConfig } from '@fluentui-react-native/desktop-test/config';
import { startDesktopService, startNativeDesktopService } from '@fluentui-react-native/desktop-test/driver-service';

const catalog = describeOperations({ accessibilityActions: false, boundedObservation: false });

if (
typeof createDesktopDriverClient !== 'function' ||
typeof DesktopAuthority !== 'function' ||
typeof resolveNativeDesktopDriver !== 'function' ||
typeof verifyNativeDriverArtifact !== 'function' ||
catalog.schemaVersion !== 1 ||
typeof defineDesktopConfig !== 'function' ||
typeof startDesktopService !== 'function' ||
typeof startNativeDesktopService !== 'function' ||
typeof connectWithDescriptor !== 'function'
) {
throw new Error('Standalone desktop consumer did not load its declared package APIs.');
}

console.log('standalone-consumer-ok');
Loading
Loading