@fluentui-react-native/desktop-driver-mcp 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md ADDED
@@ -0,0 +1,48 @@
1
+ # Desktop Driver MCP agent instructions
2
+
3
+ This package is the Model Context Protocol adapter for the Desktop Driver agent
4
+ operations. It is the instruction root for this package and every descendant.
5
+
6
+ ## Start here
7
+
8
+ Read the [README](README.md), then the narrowest entry in the
9
+ [reference index](references/README.md). The operations themselves, their
10
+ schemas, and their failure reasons belong to `@fluentui-react-native/desktop-driver`
11
+ (its agent operations reference); this package
12
+ only maps them onto MCP.
13
+
14
+ ## Invariants
15
+
16
+ - Stay a thin client. Every tool calls the service's operation routes through
17
+ the typed client; never add a second execution path, a host, or state the
18
+ service does not own. Tool input schemas come from the driver's registered
19
+ operation schemas, so the service and the adapter cannot drift apart.
20
+ - stdout carries MCP protocol only. Diagnostics go to stderr. Never log the
21
+ grant, the descriptor contents, or application text.
22
+ - Connect only through a private connection descriptor, verified by the
23
+ installed native helper before the grant is sent. Never launch or build the
24
+ service or a helper, and never accept a URL or grant from a command line,
25
+ environment variable, or the model.
26
+ - Serialize acquisition, use, close, and disposal per MCP connection. Retain
27
+ cleanup responsibility after transport loss; reverify discovery and never
28
+ replay a failed mutation. A verified replacement invalidates old references.
29
+ Fence a lost acquisition response; disposal also cleans up late acquisitions.
30
+ - Delegate a distinct driver-only child after verified discovery. Retain it on
31
+ same-incarnation/descriptor-principal rediscovery; never share or resume another
32
+ connection's session. Disposal awaits child revocation, keeping terminal-only
33
+ cleanup proof for lost responses and failed drains; unauthorized is not cleanup.
34
+ - Tie every artifact link to its session. Artifact ids restart in each session.
35
+ - Progress ticks come from the adapter and never reach the service, so a waiting
36
+ model does not keep an idle session alive. Cancellation aborts the HTTP call,
37
+ which the service treats as the caller leaving.
38
+ - Messages the model reads are fixed or bounded. Connection failures use fixed
39
+ diagnostics on stderr too; never echo discovery exceptions or descriptor contents.
40
+
41
+ ## Validation
42
+
43
+ Run `yarn format`, `yarn lint`, `yarn build`, and `yarn test` in this package.
44
+ Changes to tool schemas also need the tool-list size bound in `src/server.test.ts`
45
+ to hold. A change to driver operations is validated in the driver package first.
46
+ JavaScript tests use the fake host and are not native qualification; record a
47
+ live run against a real application for native claims. Add a patch changeset
48
+ for this published package when its behavior or shipped guidance changes.
package/CHANGELOG.md ADDED
@@ -0,0 +1,57 @@
1
+ # @fluentui-react-native/desktop-driver-mcp
2
+
3
+ ## 0.1.1
4
+
5
+ ### Patch Changes
6
+
7
+ - bac8b51: Add the `desktop_story` tool, which lists Storybook stories and renders one through the driver's story operations.
8
+ - bac8b51: Add the Desktop Driver MCP adapter: five tools (`desktop_session`, `desktop_observe`, `desktop_act`, `desktop_check`, `desktop_capture`) over the driver's agent operations, connected through a verified private descriptor, with session-scoped capture resources, progress, and cancellation.
9
+ - bac8b51: Serialize MCP connection and session lifetimes, reverify authority after transport failures, and fence ambiguous acquisitions. Discover target launch modes, quarantine uncertain story changes, refuse ungoverned args updates on protected services, and retain workload claims after uncertain cleanup. Document the work-in-progress layering and package-owned capability, qualification, and measurement status.
10
+ - bac8b51: Add `desktop-test serve --agent`, which protects the served target with a grant authority and publishes the private connection descriptor the Desktop Driver MCP adapter reads.
11
+ - d50b1ea: Separate driver, declared-workload, and recovery grant scopes. Add bounded,
12
+ attenuated connection principals and awaitable descendant revocation with
13
+ retryable terminal-only cleanup proof. Isolate MCP sessions per connection and
14
+ keep descriptor credentials out of diagnostics.
15
+ - 0cfecf0: Add a dedicated native helper entry to desktop-driver and enforce the neutral desktop package dependency boundary with standalone consumer contracts.
16
+ - bac8b51: Add bounded observation paging and deltas; extend the prior macOS M3 evidence record.
17
+ - Updated dependencies [bac8b51]
18
+ - Updated dependencies [bac8b51]
19
+ - Updated dependencies [bac8b51]
20
+ - Updated dependencies [bac8b51]
21
+ - Updated dependencies [bac8b51]
22
+ - Updated dependencies [bac8b51]
23
+ - Updated dependencies [bac8b51]
24
+ - Updated dependencies [bac8b51]
25
+ - Updated dependencies [bac8b51]
26
+ - Updated dependencies [bac8b51]
27
+ - Updated dependencies [bac8b51]
28
+ - Updated dependencies [bac8b51]
29
+ - Updated dependencies [bac8b51]
30
+ - Updated dependencies [d50b1ea]
31
+ - Updated dependencies [0cfecf0]
32
+ - Updated dependencies [bac8b51]
33
+ - Updated dependencies [bac8b51]
34
+ - Updated dependencies [bac8b51]
35
+ - Updated dependencies [bac8b51]
36
+ - Updated dependencies [bac8b51]
37
+ - Updated dependencies [bac8b51]
38
+ - Updated dependencies [bac8b51]
39
+ - Updated dependencies [bac8b51]
40
+ - Updated dependencies [bac8b51]
41
+ - Updated dependencies [bac8b51]
42
+ - Updated dependencies [bac8b51]
43
+ - Updated dependencies [bac8b51]
44
+ - Updated dependencies [bac8b51]
45
+ - Updated dependencies [bac8b51]
46
+ - Updated dependencies [cd0ede2]
47
+ - Updated dependencies [bac8b51]
48
+ - Updated dependencies [bac8b51]
49
+ - Updated dependencies [bac8b51]
50
+ - Updated dependencies [bac8b51]
51
+ - Updated dependencies [bac8b51]
52
+ - Updated dependencies [bac8b51]
53
+ - Updated dependencies [bac8b51]
54
+ - Updated dependencies [bac8b51]
55
+ - Updated dependencies [bac8b51]
56
+ - Updated dependencies [bac8b51]
57
+ - @fluentui-react-native/desktop-driver@0.5.0
package/README.md CHANGED
@@ -1,3 +1,50 @@
1
- # Temporary Holding Version
1
+ # @fluentui-react-native/desktop-driver-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server that gives
4
+ coding agents the Desktop Driver agent operations: bounded observation,
5
+ element search, actions, checks with waits, captures, and Storybook story
6
+ selection on a native macOS or Windows application.
7
+
8
+ **Work in progress:** [current status](references/current-status.md) records
9
+ implemented connection safeguards, orchestration gaps, native qualification
10
+ requirements, and measured MCP discovery costs.
11
+
12
+ Agents working in this package start at [AGENTS.md](AGENTS.md).
13
+
14
+ ## How it connects
15
+
16
+ The adapter does not start anything. A trusted supervisor runs the Desktop
17
+ Driver service with an authority, issues the agent a grant, and publishes a
18
+ private connection descriptor. The adapter reads that descriptor, has the
19
+ installed native helper verify the listening service's process identity, and
20
+ only then sends the grant to obtain its own driver-only child principal. Two
21
+ connections reading the same descriptor cannot share sessions. Disposal revokes
22
+ and drains the child, including ambiguous acquisitions; old services without
23
+ delegation fail closed. See
24
+ [Connection and setup](references/connection.md).
25
+
26
+ ## Use it
27
+
28
+ Register the server with an MCP client that launches it over stdio:
29
+
30
+ ```json
31
+ {
32
+ "mcpServers": {
33
+ "desktop-driver": {
34
+ "command": "npx",
35
+ "args": ["desktop-driver-mcp", "--descriptor", "agent-connection.json"]
36
+ }
37
+ }
38
+ }
39
+ ```
40
+
41
+ The agent then calls `desktop_session` to list targets and open one,
42
+ `desktop_observe` to read or page an immutable observation, compare it with a
43
+ retained sample, search, or inspect the journal, `desktop_act` to change it,
44
+ `desktop_check` to verify state, and `desktop_capture` for pixels. On a
45
+ Storybook target, `desktop_story` lists the stories and renders one. See
46
+ [Tools](references/tools.md).
47
+
48
+ ## References
49
+
50
+ The [reference index](references/README.md) lists every package reference.
package/config/cli.cjs ADDED
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { version } = require('../package.json');
4
+
5
+ import('../lib/cli.js')
6
+ .then(({ runDesktopDriverMcpCli }) => runDesktopDriverMcpCli({ version }))
7
+ .catch((error) => {
8
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
9
+ process.exitCode = 1;
10
+ });
package/lib/cli.d.ts ADDED
@@ -0,0 +1,10 @@
1
+ export type DesktopDriverMcpCliOptions = {
2
+ argv?: readonly string[];
3
+ /** The package version, reported by `--version` and at MCP initialization. */
4
+ version: string;
5
+ };
6
+ /**
7
+ * Serves MCP over stdio until the client closes stdin. stdout carries protocol only; diagnostics go to stderr.
8
+ */
9
+ export declare function runDesktopDriverMcpCli({ argv, version }: DesktopDriverMcpCliOptions): Promise<void>;
10
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,IAAmB,EAAE,OAAO,EAAE,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBxH"}
package/lib/cli.js ADDED
@@ -0,0 +1,30 @@
1
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
2
+ import { Command } from 'commander';
3
+ import { connectWithDescriptor } from './connection.js';
4
+ import { createDesktopDriverMcpServer } from './server.js';
5
+ /**
6
+ * Serves MCP over stdio until the client closes stdin. stdout carries protocol only; diagnostics go to stderr.
7
+ */
8
+ export async function runDesktopDriverMcpCli({ argv = process.argv, version }) {
9
+ const program = new Command()
10
+ .name('desktop-driver-mcp')
11
+ .description('Serve Desktop Driver agent operations to an MCP client over stdio.')
12
+ .option('--descriptor <name>', 'record name of the connection descriptor a supervisor published', 'agent-connection.json')
13
+ .option('--root <path>', 'private storage root the descriptor was published under; defaults to the platform location')
14
+ .version(version)
15
+ .configureOutput({ writeOut: (value) => process.stderr.write(value) });
16
+ program.parse(argv);
17
+ const flags = program.opts();
18
+ const server = createDesktopDriverMcpServer({
19
+ connect: connectWithDescriptor({ descriptor: flags.descriptor, ...(flags.root === undefined ? {} : { root: flags.root }) }),
20
+ version,
21
+ });
22
+ await server.connect(new StdioServerTransport());
23
+ const close = () => {
24
+ void server.close();
25
+ };
26
+ process.stdin.once('end', close);
27
+ process.once('SIGINT', close);
28
+ process.once('SIGTERM', close);
29
+ }
30
+ //# sourceMappingURL=cli.js.map
package/lib/cli.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAQ3D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,EAA8B;IACvG,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;SAC1B,IAAI,CAAC,oBAAoB,CAAC;SAC1B,WAAW,CAAC,oEAAoE,CAAC;SACjF,MAAM,CAAC,qBAAqB,EAAE,iEAAiE,EAAE,uBAAuB,CAAC;SACzH,MAAM,CAAC,eAAe,EAAE,4FAA4F,CAAC;SACrH,OAAO,CAAC,OAAO,CAAC;SAChB,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAyC,CAAC;IACpE,MAAM,MAAM,GAAG,4BAA4B,CAAC;QAC1C,OAAO,EAAE,qBAAqB,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC3H,OAAO;KACR,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AACjC,CAAC"}
@@ -0,0 +1,23 @@
1
+ import type { DesktopDriverClient } from '@fluentui-react-native/desktop-driver/client';
2
+ export type DesktopDriverConnection = {
3
+ client: DesktopDriverClient;
4
+ /** The verified service incarnation. Never a URL or a credential. */
5
+ incarnation: string;
6
+ /** The non-secret grant id, not its bearer token or display label. */
7
+ principal: string;
8
+ };
9
+ /** Revalidates private discovery and returns the client and its verified authority, without launching anything. */
10
+ export type ConnectDesktopDriver = () => Promise<DesktopDriverConnection>;
11
+ export type DescriptorConnectionOptions = {
12
+ /** The record name the supervisor published the connection descriptor under, such as `agent-connection.json`. */
13
+ descriptor: string;
14
+ /** The private storage root, when the supervisor published somewhere other than the platform default. */
15
+ root?: string;
16
+ };
17
+ /**
18
+ * Connects through the private descriptor a trusted supervisor published. The service's identity is verified by the
19
+ * installed native helper before the grant is sent. Nothing is launched or built: a missing helper, descriptor, or
20
+ * service is an error.
21
+ */
22
+ export declare function connectWithDescriptor(options: DescriptorConnectionOptions): ConnectDesktopDriver;
23
+ //# sourceMappingURL=connection.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AAExF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,mHAAmH;AACnH,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAE1E,MAAM,MAAM,2BAA2B,GAAG;IACxC,iHAAiH;IACjH,UAAU,EAAE,MAAM,CAAC;IACnB,yGAAyG;IACzG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,2BAA2B,GAAG,oBAAoB,CAmBhG"}
@@ -0,0 +1,28 @@
1
+ import { resolveNativeDesktopDriver } from '@fluentui-react-native/desktop-driver/native';
2
+ import { createMacOSPrivateStorage, createMacOSServiceVerifier, createWindowsPrivateStorage, createWindowsServiceVerifier, readConnectionDescriptor, } from '@fluentui-react-native/desktop-driver/authority';
3
+ import { createDesktopDriverClient } from '@fluentui-react-native/desktop-driver/client';
4
+ /**
5
+ * Connects through the private descriptor a trusted supervisor published. The service's identity is verified by the
6
+ * installed native helper before the grant is sent. Nothing is launched or built: a missing helper, descriptor, or
7
+ * service is an error.
8
+ */
9
+ export function connectWithDescriptor(options) {
10
+ return async () => {
11
+ const platform = process.platform === 'darwin' ? 'macos' : process.platform === 'win32' ? 'windows' : undefined;
12
+ if (platform === undefined) {
13
+ throw new Error('Desktop Driver services run on macOS and Windows.');
14
+ }
15
+ const artifact = await resolveNativeDesktopDriver({ buildPolicy: 'never', platform });
16
+ const storage = platform === 'macos'
17
+ ? await createMacOSPrivateStorage(...(options.root === undefined ? [] : [options.root]))
18
+ : await createWindowsPrivateStorage({ artifact, ...(options.root === undefined ? {} : { root: options.root }) });
19
+ const verify = platform === 'macos' ? createMacOSServiceVerifier({ artifact }) : createWindowsServiceVerifier({ artifact });
20
+ const descriptor = await readConnectionDescriptor(storage, options.descriptor, verify);
21
+ return {
22
+ client: createDesktopDriverClient({ grant: descriptor.grant, url: descriptor.url }),
23
+ incarnation: descriptor.service.incarnation,
24
+ principal: descriptor.grant.split('.')[1],
25
+ };
26
+ };
27
+ }
28
+ //# sourceMappingURL=connection.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,8CAA8C,CAAC;AAC1F,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AAqBzF;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoC;IACxE,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAChH,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,0BAA0B,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtF,MAAM,OAAO,GACX,QAAQ,KAAK,OAAO;YAClB,CAAC,CAAC,MAAM,yBAAyB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACxF,CAAC,CAAC,MAAM,2BAA2B,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QACrH,MAAM,MAAM,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,0BAA0B,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,4BAA4B,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5H,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACvF,OAAO;YACL,MAAM,EAAE,yBAAyB,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC;YACnF,WAAW,EAAE,UAAU,CAAC,OAAO,CAAC,WAAW;YAC3C,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SAC1C,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,80 @@
1
+ import type { OperationCallOptions } from '@fluentui-react-native/desktop-driver/client';
2
+ import type { OperationResponse } from '@fluentui-react-native/desktop-driver/operations';
3
+ import type { ConnectDesktopDriver } from './connection.js';
4
+ /** A failure the adapter itself reports, with a machine reason as the service's own errors carry. */
5
+ export declare class AdapterError extends Error {
6
+ readonly reason: string;
7
+ constructor(reason: string, message: string);
8
+ }
9
+ export type TargetSummary = {
10
+ endpoint?: string;
11
+ id: string;
12
+ launchModes?: ('launch' | 'attach')[];
13
+ platformName?: string;
14
+ quarantined?: true;
15
+ renderer?: string;
16
+ };
17
+ export type OperationSummary = {
18
+ available: boolean;
19
+ name: string;
20
+ unavailableReason?: string;
21
+ };
22
+ export type SessionSummary = {
23
+ clickMode?: string;
24
+ id: string;
25
+ operations: OperationSummary[];
26
+ target: string;
27
+ };
28
+ export type SessionResponse<Result> = {
29
+ response: OperationResponse<Result>;
30
+ session: string;
31
+ };
32
+ export type OpenSessionRequest = {
33
+ clickMode?: 'accessibility' | 'auto' | 'physical';
34
+ launch: boolean;
35
+ target: string;
36
+ };
37
+ /**
38
+ * Serializes one MCP connection's client lifetime. Transport failure retains cleanup responsibility; only verified
39
+ * replacement or an authoritative rejection invalidates it. No failed mutation or ambiguous acquisition is replayed.
40
+ */
41
+ export declare class DesktopController {
42
+ #private;
43
+ constructor(connect: ConnectDesktopDriver);
44
+ status(): Promise<{
45
+ session?: SessionSummary;
46
+ sessionState?: 'uncertain';
47
+ targets: TargetSummary[];
48
+ }>;
49
+ open(request: OpenSessionRequest): Promise<SessionSummary>;
50
+ close(): Promise<{
51
+ closed?: string;
52
+ }>;
53
+ private closeSession;
54
+ /** Runs one operation in the open session, and names the session so a later reference can be tied to it. */
55
+ run<Result>(name: string, input: object, options?: OperationCallOptions): Promise<SessionResponse<Result>>;
56
+ private runOperation;
57
+ /**
58
+ * Reads a whole captured image by paging through `artifact`. Artifact ids restart in every session, so a reference
59
+ * from a closed session is refused rather than read from whichever session is open now.
60
+ */
61
+ readArtifact(session: string, artifact: string, signal?: AbortSignal): Promise<{
62
+ data: Buffer;
63
+ mimeType: string;
64
+ }>;
65
+ private readArtifactPages;
66
+ get session(): string | undefined;
67
+ /** Stops admissions immediately. Late acquisitions still run their cleanup after the bounded close wait expires. */
68
+ dispose(): Promise<void>;
69
+ private connection;
70
+ private enqueue;
71
+ private assertCertain;
72
+ private describe;
73
+ /** Transport errors retain ownership; authoritative invalidation never permits replaying a failed operation. */
74
+ private guard;
75
+ }
76
+ export declare function isWebDriverError(error: unknown): error is Error & {
77
+ code: string;
78
+ data?: Record<string, unknown>;
79
+ };
80
+ //# sourceMappingURL=controller.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAuB,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAC9G,OAAO,KAAK,EAAkB,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AAE1G,OAAO,KAAK,EAAE,oBAAoB,EAA2B,MAAM,iBAAiB,CAAC;AAErF,qGAAqG;AACrG,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAI1C;CACF;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG,MAAM,MAAM,cAAc,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhH,MAAM,MAAM,eAAe,CAAC,MAAM,IAAI;IAAE,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F,MAAM,MAAM,kBAAkB,GAAG;IAAE,SAAS,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AASxH;;;GAGG;AACH,qBAAa,iBAAiB;;IAW5B,YAAY,OAAO,EAAE,oBAAoB,EAExC;IAED,MAAM,IAAI,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,cAAc,CAAC;QAAC,YAAY,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC,CAQpG;IAED,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiCzD;IAED,KAAK,IAAI,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAOpC;YAEa,YAAY;IAc1B,4GAA4G;IAC5G,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAM7G;YAEa,YAAY;IAU1B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAMjH;YAEa,iBAAiB;IA8B/B,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,oHAAoH;IACpH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAgCvB;YAEa,UAAU;IAmExB,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,aAAa;YASP,QAAQ;IAgBtB,gHAAgH;YAClG,KAAK;CA0BpB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAElH"}