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

package/references/current-status.md

@@ -0,0 +1,85 @@
+---
+id: desktop-driver-mcp.current-status
+kind: instruction-reference
+owner_paths:
+  - packages/agentic/desktop-driver-mcp
+---
+
+# Current adapter and measurement status
+
+**Work in progress, updated 2026-11-05.** The adapter is a thin client, not a
+supervisor. Keep this package name until actual harness-owned management tools
+land; a later `desktop-mcp` facade must retain driver-only use and plan published
+compatibility. Done below describes implementation, not full native qualification.
+Follow-up work is tracked in
+[desktop driver improvements (#4435)](https://github.com/microsoft/fluentui-react-native/issues/4435);
+connection isolation is [#4440](https://github.com/microsoft/fluentui-react-native/issues/4440)
+and the generalized management facet is
+[#4450](https://github.com/microsoft/fluentui-react-native/issues/4450).
+
+## 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.                                                                         |
+
+See [connection](connection.md) and [tools](tools.md) for exact behavior.
+Native and Storybook limitations are tracked in
+`@fluentui-react-native/desktop-driver/references/current-status.md`;
+supervision gaps in
+`@fluentui-react-native/desktop-test/references/current-status.md`.
+
+## Measured discovery and interaction costs
+
+Historical measurements migrated from the root capability report, **not rerun**
+by this update. `o200k_base` was used over all MCP text blocks; tokenizer package
+version/raw portable artifact locator were not retained.
+
+| Date / revision          | Measurement                            | Result                          | Boundary                                              |
+| ------------------------ | -------------------------------------- | ------------------------------- | ----------------------------------------------------- |
+| 2026-11-04 / `41fc7473f` | Six-tool `tools/list`                  | 4,688 text tokens; 20,269 bytes | Discovery once per connection; not per operation      |
+| Same                     | Server instructions                    | 120 text tokens                 | Additional discovery context                          |
+| Same                     | Named Toggle + check + closing observe | 386 text tokens; 48 ms          | One warm macOS Fabric run, not a latency distribution |
+| Same                     | Physical click + checked check         | 181 ms                          | One run                                               |
+| Same                     | Observe default                        | 29-31 ms median, max 35 ms      | 20 warm calls per button/checkbox/menu story          |
+| Same                     | Delta                                  | 32-35 ms median, max 37 ms      | Same 20-call-per-story method                         |
+
+The app was macOS Fabric Storybook at 2720 x 1988 pixels on a 2x display,
+served through `storybook driver --macos --agent`, driven by an MCP SDK stdio
+client. Operation text/scoping comparisons and their completeness are retained
+in the driver's status reference rather than duplicated here.
+
+The schema test limits serialized JavaScript string length to 22,000
+**characters**. It is not a token or UTF-8 byte limit. The earlier proposed
+8 KiB discovery budget was not achieved; measured discovery is about 20.3 KB.
+Changed descriptions/schema text invalidate an exact present-day 4,688-token
+claim: retain that number only with its historical revision.
+
+For each new run append revision, SDK/client version, platform/renderer,
+tokenizer/version, serialized UTF-8 bytes and characters, text tokens,
+instructions overhead, projection/budgets, sample count, cold/warm timing,
+success/retry/cancellation/cleanup counts, and approved artifact locator.
+Do not claim token reductions from reducing information scope or omitting
+discovery. Windows and Paper measurements are currently **not recorded here**.
+
+## Before full submission
+
+Re-run same-port replacement, revocation, dispose during open, failed delete,
+ambiguous create, and resource invalidation through the real descriptor path on
+macOS and Windows. Qualify Windows Fabric and Win32 Paper independently, with
+physical Ctrl+C and interactive input/capture cases where supported. Current
+fake-host tests validate portable controller semantics, not native ownership,
+signing, TCC, Windows ACLs, DPI, or process containment. This requalification is
+tracked in [#4441](https://github.com/microsoft/fluentui-react-native/issues/4441).

package/references/tools.md

@@ -0,0 +1,134 @@
+---
+id: desktop-driver-mcp.tools
+kind: instruction-reference
+owner_paths:
+  - packages/agentic/desktop-driver-mcp
+---
+
+# Tools
+
+Six tools group the driver's agent operations. Each operation's input schema,
+result, and failure reasons are defined once in `@fluentui-react-native/desktop-driver`
+(its agent operations reference); the tools reuse those schemas, so a field the
+service rejects is rejected here first, before anything reaches the service.
+Unknown fields are refused. The historical tool list measured about 20.3 KB;
+the test bounds serialized JavaScript **characters** at 22,000, not tokens or
+UTF-8 bytes. See [measurement history](current-status.md).
+
+| Tool              | Calls                                                               | Hints                       |
+| ----------------- | ------------------------------------------------------------------- | --------------------------- |
+| `desktop_session` | service status, session creation and deletion                       | not read-only               |
+| `desktop_observe` | `observe` (default), `delta`, `read`, `find`, `journal`, `artifact` | read-only                   |
+| `desktop_act`     | `sequence`                                                          | destructive, not idempotent |
+| `desktop_check`   | `check`                                                             | read-only                   |
+| `desktop_capture` | `capture`                                                           | read-only                   |
+| `desktop_story`   | `stories` (default), `story`                                        | destructive, not idempotent |
+
+## desktop_session
+
+`action` is `status` (the default), `open`, or `close`.
+
+- `status` lists the targets the grant allows, with their endpoint, platform,
+  renderer, effective `launchModes`, and whether a target is quarantined, plus
+  the open session. `sessionState: "uncertain"` reports an acquisition whose
+  response was lost.
+- `open` needs a `target`. It attaches to the running application unless
+  `launch` is true, and accepts a `clickMode` of `accessibility`, `auto`, or
+  `physical`. It returns the session id, the click mode in effect, and which
+  operations the target supports, with the reason for any that are unavailable.
+  One session is open at a time; opening a second fails with `session-open`.
+- `close` confirms deletion before forgetting the known session. Closing the MCP
+  connection stops admissions and attempts bounded cleanup, including late opens.
+
+## desktop_observe
+
+Give at most one of `observe`, `delta`, `read`, `find`, `journal`, or
+`artifact`, each with that operation's input; an empty call observes the
+current window. `observe` returns an opaque `next` cursor when more of the same
+sample is available. `delta` takes a `since` sample id and compares a fresh
+observation with that retained base. `read` accepts the cursor from either
+result and reads its next page without sampling again. The `artifact` form
+pages through a capture for clients that cannot read resources.
+
+## desktop_act
+
+Takes the `sequence` input: up to eight `act` and `check` steps that run in
+order and stop at the first that fails or does not pass, with an optional
+closing `observe`. Steps that ran stay done. Name a `requestId` (1 to 64
+letters, digits, or `. _ : -`) to make a retry safe: repeating it returns the
+first outcome instead of acting again while that outcome is retained in the
+same session. This is not a retry guarantee across session/service replacement.
+
+## desktop_check
+
+Takes the `check` input. A `waitMs` waits for the predicates to hold.
+
+## desktop_capture
+
+Takes the `capture` input. Every capture returns a `resource_link` to
+`desktop-driver://sessions/{session}/artifacts/{artifact}`. With `image: true`,
+a capture under 1 MiB also returns an MCP image block; a larger one reports
+`imageOmitted: "too-large"` and is read through the link.
+
+Reading the link returns the whole PNG as one blob. The adapter pages it from
+the service and checks the bytes against the recorded SHA-256. A link from a
+session that is no longer open is refused, because artifact ids restart in
+every session.
+
+## desktop_story
+
+Give at most one of `list`, with the `stories` input, or `story`, with the
+`story` input; an empty call lists the first page. `list` pages through the
+build's story catalog and names the story this session rendered. `story`
+renders a story by id (`action: "select"`, the default) or renders it again
+from its initial state (`action: "reset"`); either expires every earlier
+reference into the preview. `requestId` makes a `story` retry safe, as it does
+for `desktop_act`.
+
+The tool is always listed. On a target without Storybook, both forms fail with
+`stories-unsupported`. When `list` reports `changed: true`, another client
+rendered a story since this session's, and earlier references have expired.
+Unknown or partial story effects quarantine mutations; do not retry with a new
+request id to bypass that fence. The tool does not expose args. Protected driver
+args updates are unsupported; alternate channel ingress is not yet fully governed.
+
+## Results
+
+A successful call returns the operation's JSON envelope as one text block:
+`schemaVersion`, `requestId`, `operation`, the `session` incarnation, and the
+`result`. An observation outline is moved into its own text block, so its
+lines stay readable, and the envelope's `outline` field names that block, as in
+`"(text block 2)"`. Results carry no `structuredContent`, so nothing is sent
+twice.
+
+## Errors
+
+A tool failure is an `isError` result with one JSON text block:
+
+| Field       | Meaning                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| `error`     | The WebDriver error code, or `adapter` for a failure the adapter itself reports.                          |
+| `reason`    | The machine reason to branch on.                                                                          |
+| `message`   | A bounded message.                                                                                        |
+| `requestId` | The request id, when the service assigned or echoed one.                                                  |
+| `mutation`  | For an action, whether it was applied, rejected, or indeterminate, and whether it quarantined the target. |
+
+The adapter's own reasons are `no-session`, `session-open`,
+`session-uncertain`, `connection-closed`, `service-unavailable`, `cancelled`,
+and `internal`. A malformed call is
+refused with the schema's validation message.
+
+A failed resource read is a JSON-RPC error: `-32602` with a `data.reason` of
+`artifact-expired` or `artifact-changed`, or the service's reason for an
+invalid argument; `-32603` otherwise.
+
+## Progress and cancellation
+
+When a call carries a progress token, the adapter reports progress about once
+a second until the call ends, so a client that resets its timeout on progress
+can wait out a long check. The ticks never reach the service, so a waiting
+model does not keep an idle session alive.
+
+Cancelling a call aborts its HTTP request. The service treats that as the
+caller leaving: work not yet dispatched is cancelled and journaled with the
+reason `cancelled`, and the session stays usable.

package/src/cli.ts

@@ -0,0 +1,37 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Command } from 'commander';
+
+import { connectWithDescriptor } from './connection.js';
+import { createDesktopDriverMcpServer } from './server.js';
+
+export type DesktopDriverMcpCliOptions = {
+  argv?: readonly string[];
+  /** The package version, reported by `--version` and at MCP initialization. */
+  version: string;
+};
+
+/**
+ * Serves MCP over stdio until the client closes stdin. stdout carries protocol only; diagnostics go to stderr.
+ */
+export async function runDesktopDriverMcpCli({ argv = process.argv, version }: DesktopDriverMcpCliOptions): Promise<void> {
+  const program = new Command()
+    .name('desktop-driver-mcp')
+    .description('Serve Desktop Driver agent operations to an MCP client over stdio.')
+    .option('--descriptor <name>', 'record name of the connection descriptor a supervisor published', 'agent-connection.json')
+    .option('--root <path>', 'private storage root the descriptor was published under; defaults to the platform location')
+    .version(version)
+    .configureOutput({ writeOut: (value) => process.stderr.write(value) });
+  program.parse(argv);
+  const flags = program.opts<{ descriptor: string; root?: string }>();
+  const server = createDesktopDriverMcpServer({
+    connect: connectWithDescriptor({ descriptor: flags.descriptor, ...(flags.root === undefined ? {} : { root: flags.root }) }),
+    version,
+  });
+  await server.connect(new StdioServerTransport());
+  const close = () => {
+    void server.close();
+  };
+  process.stdin.once('end', close);
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+}

package/src/connection.ts

@@ -0,0 +1,54 @@
+import { resolveNativeDesktopDriver } from '@fluentui-react-native/desktop-driver';
+import {
+  createMacOSPrivateStorage,
+  createMacOSServiceVerifier,
+  createWindowsPrivateStorage,
+  createWindowsServiceVerifier,
+  readConnectionDescriptor,
+} from '@fluentui-react-native/desktop-driver/authority';
+import { createDesktopDriverClient } from '@fluentui-react-native/desktop-driver/client';
+import type { DesktopDriverClient } from '@fluentui-react-native/desktop-driver/client';
+
+export type DesktopDriverConnection = {
+  client: DesktopDriverClient;
+  /** The verified service incarnation. Never a URL or a credential. */
+  incarnation: string;
+  /** The non-secret grant id, not its bearer token or display label. */
+  principal: string;
+};
+
+/** Revalidates private discovery and returns the client and its verified authority, without launching anything. */
+export type ConnectDesktopDriver = () => Promise<DesktopDriverConnection>;
+
+export type DescriptorConnectionOptions = {
+  /** The record name the supervisor published the connection descriptor under, such as `agent-connection.json`. */
+  descriptor: string;
+  /** The private storage root, when the supervisor published somewhere other than the platform default. */
+  root?: string;
+};
+
+/**
+ * Connects through the private descriptor a trusted supervisor published. The service's identity is verified by the
+ * installed native helper before the grant is sent. Nothing is launched or built: a missing helper, descriptor, or
+ * service is an error.
+ */
+export function connectWithDescriptor(options: DescriptorConnectionOptions): ConnectDesktopDriver {
+  return async () => {
+    const platform = process.platform === 'darwin' ? 'macos' : process.platform === 'win32' ? 'windows' : undefined;
+    if (platform === undefined) {
+      throw new Error('Desktop Driver services run on macOS and Windows.');
+    }
+    const artifact = await resolveNativeDesktopDriver({ buildPolicy: 'never', platform });
+    const storage =
+      platform === 'macos'
+        ? await createMacOSPrivateStorage(...(options.root === undefined ? [] : [options.root]))
+        : await createWindowsPrivateStorage({ artifact, ...(options.root === undefined ? {} : { root: options.root }) });
+    const verify = platform === 'macos' ? createMacOSServiceVerifier({ artifact }) : createWindowsServiceVerifier({ artifact });
+    const descriptor = await readConnectionDescriptor(storage, options.descriptor, verify);
+    return {
+      client: createDesktopDriverClient({ grant: descriptor.grant, url: descriptor.url }),
+      incarnation: descriptor.service.incarnation,
+      principal: descriptor.grant.split('.')[1],
+    };
+  };
+}

package/src/controller.ts

@@ -0,0 +1,351 @@
+import { createHash } from 'node:crypto';
+
+import { DesktopSessionClient } from '@fluentui-react-native/desktop-driver/client';
+import type { OperationCallOptions } from '@fluentui-react-native/desktop-driver/client';
+import type { ArtifactResult, OperationResponse } from '@fluentui-react-native/desktop-driver/operations';
+
+import type { ConnectDesktopDriver, DesktopDriverConnection } from './connection.js';
+
+/** A failure the adapter itself reports, with a machine reason as the service's own errors carry. */
+export class AdapterError extends Error {
+  readonly reason: string;
+
+  constructor(reason: string, message: string) {
+    super(message);
+    this.name = 'AdapterError';
+    this.reason = reason;
+  }
+}
+
+export type TargetSummary = {
+  endpoint?: string;
+  id: string;
+  launchModes?: ('launch' | 'attach')[];
+  platformName?: string;
+  quarantined?: true;
+  renderer?: string;
+};
+
+export type OperationSummary = { available: boolean; name: string; unavailableReason?: string };
+
+export type SessionSummary = { clickMode?: string; id: string; operations: OperationSummary[]; target: string };
+
+export type SessionResponse<Result> = { response: OperationResponse<Result>; session: string };
+
+export type OpenSessionRequest = { clickMode?: 'accessibility' | 'auto' | 'physical'; launch: boolean; target: string };
+
+type OpenSession = { connection: DesktopDriverConnection; session: DesktopSessionClient; target: string };
+
+const deleteTimeoutMs = 10_000;
+const artifactPageBytes = 1024 * 1024;
+/** The service never keeps a larger capture; a larger claim is a fault, not something to buffer. */
+const maxArtifactBytes = 16 * 1024 * 1024;
+
+/**
+ * Serializes one MCP connection's client lifetime. Transport failure retains cleanup responsibility; only verified
+ * replacement or an authoritative rejection invalidates it. No failed mutation or ambiguous acquisition is replayed.
+ */
+export class DesktopController {
+  readonly #connect: ConnectDesktopDriver;
+  #connection?: DesktopDriverConnection;
+  #open?: OpenSession;
+  #uncertain?: DesktopDriverConnection;
+  #pending: Promise<unknown> = Promise.resolve();
+  #disposed = false;
+  #disposing?: Promise<void>;
+  readonly #disconnected = new AbortController();
+
+  constructor(connect: ConnectDesktopDriver) {
+    this.#connect = connect;
+  }
+
+  status(): Promise<{ session?: SessionSummary; sessionState?: 'uncertain'; targets: TargetSummary[] }> {
+    return this.enqueue(async () => {
+      const { client } = await this.connection();
+      const status = await this.guard(() => client.status());
+      const targets = Array.isArray(status.targets) ? status.targets.map(summarizeTarget) : [];
+      const session = this.#open ? await this.describe(this.#open) : undefined;
+      return { ...(session ? { session } : {}), ...(this.#uncertain ? { sessionState: 'uncertain' as const } : {}), targets };
+    });
+  }
+
+  open(request: OpenSessionRequest): Promise<SessionSummary> {
+    return this.enqueue(async () => {
+      const connection = await this.connection();
+      if (this.#disposed) throw new AdapterError('connection-closed', 'The MCP connection is closed.');
+      this.assertCertain();
+      if (this.#open) {
+        throw new AdapterError('session-open', 'A session is already open. Close it first.');
+      }
+      // A lost response can hide a successful acquisition. Retain the fence until a definitive response or replacement.
+      this.#uncertain = connection;
+      let session: DesktopSessionClient;
+      try {
+        session = await this.guard(() =>
+          connection.client.newSession({
+            alwaysMatch: {
+              'furn:launchMode': request.launch ? 'launch' : 'attach',
+              'furn:target': request.target,
+              ...(request.clickMode === undefined ? {} : { 'furn:clickMode': request.clickMode }),
+            },
+          }),
+        );
+      } catch (error) {
+        if (isWebDriverError(error)) this.#uncertain = undefined;
+        throw error;
+      }
+      this.#uncertain = undefined;
+      this.#open = { connection, session, target: request.target };
+      if (this.#disposed) {
+        await this.closeSession();
+        throw new AdapterError('connection-closed', 'The MCP connection is closed.');
+      }
+      return this.describe(this.#open);
+    });
+  }
+
+  close(): Promise<{ closed?: string }> {
+    return this.enqueue(async () => {
+      if (!this.#open && !this.#uncertain) return {};
+      await this.connection();
+      this.assertCertain();
+      return this.closeSession();
+    });
+  }
+
+  private async closeSession(): Promise<{ closed?: string }> {
+    const open = this.#open;
+    if (!open) {
+      return {};
+    }
+    try {
+      await this.guard(() => open.session.delete());
+    } catch (error) {
+      if (!isWebDriverError(error) || error.code !== 'invalid session id') throw error;
+    }
+    this.#open = undefined;
+    return { closed: open.session.id };
+  }
+
+  /** Runs one operation in the open session, and names the session so a later reference can be tied to it. */
+  run<Result>(name: string, input: object, options: OperationCallOptions = {}): Promise<SessionResponse<Result>> {
+    return this.enqueue(async () => {
+      if (this.#open || this.#uncertain) await this.connection();
+      this.assertCertain();
+      return this.runOperation<Result>(name, input, options);
+    });
+  }
+
+  private async runOperation<Result>(name: string, input: object, options: OperationCallOptions): Promise<SessionResponse<Result>> {
+    const open = this.#open;
+    if (!open) {
+      throw new AdapterError('no-session', 'No session is open. Open one with desktop_session first.');
+    }
+    const signal = AbortSignal.any([this.#disconnected.signal, ...(options.signal ? [options.signal] : [])]);
+    const response = await this.guard(() => open.session.operation<Result>(name, input, { ...options, signal }), signal);
+    return { response, session: open.session.id };
+  }
+
+  /**
+   * Reads a whole captured image by paging through `artifact`. Artifact ids restart in every session, so a reference
+   * from a closed session is refused rather than read from whichever session is open now.
+   */
+  readArtifact(session: string, artifact: string, signal?: AbortSignal): Promise<{ data: Buffer; mimeType: string }> {
+    return this.enqueue(async () => {
+      if (this.#open || this.#uncertain) await this.connection();
+      this.assertCertain();
+      return this.readArtifactPages(session, artifact, signal);
+    });
+  }
+
+  private async readArtifactPages(session: string, artifact: string, signal?: AbortSignal): Promise<{ data: Buffer; mimeType: string }> {
+    if (this.#open?.session.id !== session) {
+      throw new AdapterError('artifact-expired', 'That capture belongs to a session that is no longer open.');
+    }
+    const pages: Buffer[] = [];
+    let offset: number | undefined = 0;
+    let first: ArtifactResult | undefined;
+    let total = 0;
+    while (offset !== undefined) {
+      const { response } = await this.runOperation<ArtifactResult>('artifact', { artifact, length: artifactPageBytes, offset }, { signal });
+      const page = response.result;
+      first ??= page;
+      if (page.sha256 !== first.sha256 || page.bytes > maxArtifactBytes) {
+        throw new AdapterError('artifact-changed', 'The capture changed while it was being read.');
+      }
+      const bytes = Buffer.from(page.data, 'base64');
+      total += bytes.byteLength;
+      if (total > page.bytes || (page.next !== undefined && page.next <= offset)) {
+        throw new AdapterError('artifact-changed', 'The capture changed while it was being read.');
+      }
+      pages.push(bytes);
+      offset = page.next;
+    }
+    const data = Buffer.concat(pages);
+    if (!first || data.byteLength !== first.bytes || createHash('sha256').update(data).digest('hex') !== first.sha256) {
+      throw new AdapterError('artifact-changed', 'The capture did not match its recorded digest.');
+    }
+    return { data, mimeType: first.mimeType };
+  }
+
+  get session(): string | undefined {
+    return this.#open?.session.id;
+  }
+
+  /** Stops admissions immediately. Late acquisitions still run their cleanup after the bounded close wait expires. */
+  dispose(): Promise<void> {
+    this.#disposed = true;
+    this.#disconnected.abort();
+    return (this.#disposing ??= (async () => {
+      const cleanup = this.#pending.then(async () => {
+        await this.closeSession();
+        this.assertCertain();
+      });
+      this.#pending = cleanup.catch(() => {
+        console.error('desktop-driver-mcp: session cleanup is incomplete; the service must drain or expire the session.');
+      });
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await Promise.race([
+          this.#pending,
+          new Promise<void>((resolve) => {
+            timer = setTimeout(() => {
+              console.error('desktop-driver-mcp: session cleanup is still pending; the service must drain or expire the session.');
+              resolve();
+            }, deleteTimeoutMs);
+            timer.unref();
+          }),
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    })());
+  }
+
+  private async connection(): Promise<DesktopDriverConnection> {
+    if (this.#connection) return this.#connection;
+    let connection: DesktopDriverConnection;
+    try {
+      connection = await this.#connect();
+    } catch (error) {
+      // The cause can name machine-local paths; the operator reads it on stderr, the model reads a fixed message.
+      console.error(`desktop-driver-mcp: connecting failed: ${error instanceof Error ? error.message : String(error)}`);
+      throw new AdapterError('service-unavailable', 'The Desktop Driver service is not available. Ask the operator to start it.');
+    }
+    const previous = this.#open?.connection ?? this.#uncertain;
+    if (previous && previous.incarnation !== connection.incarnation) {
+      this.#open = undefined;
+      this.#uncertain = undefined;
+    } else if (previous && previous.principal !== connection.principal) {
+      // A new grant on the same live service does not prove that the old grant's session has ended.
+      if (this.#open) {
+        try {
+          await this.closeSession();
+        } catch (error) {
+          if (this.#open) throw error;
+        }
+      }
+      if (this.#uncertain) {
+        try {
+          await this.guard(() => previous.client.status());
+        } catch (error) {
+          if (this.#uncertain) throw error;
+        }
+      }
+      this.assertCertain();
+    } else if (this.#open) {
+      // Rebind only to the same verified service and principal. A subsequent command still validates session liveness.
+      this.#open = {
+        ...this.#open,
+        connection,
+        session: new DesktopSessionClient(connection.client, this.#open.session.id, this.#open.session.capabilities),
+      };
+    }
+    this.#connection = connection;
+    return connection;
+  }
+
+  private enqueue<T>(work: () => Promise<T>): Promise<T> {
+    const result = this.#pending.then(() => {
+      if (this.#disposed) throw new AdapterError('connection-closed', 'The MCP connection is closed.');
+      return work();
+    });
+    this.#pending = result.catch(() => undefined);
+    return result;
+  }
+
+  private assertCertain(): void {
+    if (this.#uncertain) {
+      throw new AdapterError(
+        'session-uncertain',
+        'A session acquisition lost its response. Ask the operator to revoke the old grant or restart the service before opening another.',
+      );
+    }
+  }
+
+  private async describe(open: OpenSession): Promise<SessionSummary> {
+    const catalog = await this.guard(() => open.session.operations());
+    const operations = catalog.operations.map(({ available, name, unavailableReason }) => ({
+      available,
+      name,
+      ...(unavailableReason === undefined ? {} : { unavailableReason }),
+    }));
+    const clickMode = open.session.capabilities['furn:clickMode'];
+    return {
+      ...(typeof clickMode === 'string' ? { clickMode } : {}),
+      id: open.session.id,
+      operations,
+      target: open.target,
+    };
+  }
+
+  /** Transport errors retain ownership; authoritative invalidation never permits replaying a failed operation. */
+  private async guard<T>(call: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    try {
+      return await call();
+    } catch (error) {
+      if (signal?.aborted) {
+        throw new AdapterError('cancelled', 'The call was cancelled.');
+      }
+      if (isWebDriverError(error)) {
+        if (error.code === 'invalid session id') {
+          this.#open = undefined;
+        }
+        if (error.code === 'unauthorized') {
+          this.#open = undefined;
+          this.#uncertain = undefined;
+          this.#connection = undefined;
+          throw new AdapterError(
+            'service-unavailable',
+            'The Desktop Driver authority is no longer valid. Reconnect before opening a session.',
+          );
+        }
+        throw error;
+      }
+      this.#connection = undefined;
+      throw new AdapterError('service-unavailable', 'The Desktop Driver service stopped answering. Recheck status before continuing.');
+    }
+  }
+}
+
+export function isWebDriverError(error: unknown): error is Error & { code: string; data?: Record<string, unknown> } {
+  return error instanceof Error && error.name === 'WebDriverError' && typeof (error as { code?: unknown }).code === 'string';
+}
+
+function summarizeTarget(target: Record<string, unknown>): TargetSummary {
+  const text = (value: unknown) => (typeof value === 'string' ? value : undefined);
+  const summary: TargetSummary = { id: String(target.id) };
+  for (const key of ['endpoint', 'platformName', 'renderer'] as const) {
+    const value = text(target[key]);
+    if (value !== undefined) {
+      summary[key] = value;
+    }
+  }
+  if (target.quarantine !== undefined) {
+    summary.quarantined = true;
+  }
+  if (Array.isArray(target.launchModes)) {
+    summary.launchModes = target.launchModes.filter((mode): mode is 'launch' | 'attach' => mode === 'launch' || mode === 'attach');
+  }
+  return summary;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { connectWithDescriptor } from './connection.js';
+export type { ConnectDesktopDriver, DescriptorConnectionOptions, DesktopDriverConnection } from './connection.js';
+export { createDesktopDriverMcpServer } from './server.js';
+export type { DesktopDriverMcpServerOptions } from './server.js';