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

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/native';
+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,381 @@
+import { createHash } from 'node:crypto';
+
+import { DesktopSessionClient } from '@fluentui-react-native/desktop-driver/client';
+import type { DesktopDriverClient, 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;
+  #binding?: { root: DesktopDriverConnection; child: 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 () => {
+        if (this.#binding) {
+          await this.#binding.child.client.revokeConnection();
+          this.#open = undefined;
+          this.#uncertain = undefined;
+          this.#binding = undefined;
+        }
+      });
+      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);
+        if (this.#binding) this.#disposing = undefined;
+      }
+    })());
+  }
+
+  private async connection(): Promise<DesktopDriverConnection> {
+    if (this.#connection) return this.#connection;
+    let connection: DesktopDriverConnection;
+    try {
+      connection = await this.#connect();
+    } catch {
+      // Discovery failures can contain descriptor credentials; neither protocol output nor diagnostics may echo them.
+      console.error('desktop-driver-mcp: connecting failed; verify private discovery and the service identity.');
+      throw new AdapterError('service-unavailable', 'The Desktop Driver service is not available. Ask the operator to start it.');
+    }
+    const binding = this.#binding;
+    if (binding && binding.root.incarnation === connection.incarnation && binding.root.principal === connection.principal) {
+      connection = binding.child;
+    } else {
+      if (binding && binding.root.incarnation === connection.incarnation) {
+        await this.guard(() => binding.child.client.revokeConnection());
+        this.#open = undefined;
+        this.#uncertain = undefined;
+      }
+      const root = connection;
+      let child: DesktopDriverClient;
+      try {
+        child = await this.guard(() => root.client.delegateConnection());
+      } catch (error) {
+        if (isWebDriverError(error) && ['unknown command', 'unsupported operation'].includes(error.code)) {
+          throw new AdapterError('connection-authority-unsupported', 'The service does not support isolated connection authority.');
+        }
+        throw error;
+      }
+      const principal = child.principalId;
+      if (!principal) throw new AdapterError('service-unavailable', 'The service does not support isolated connection authority.');
+      connection = { client: child, incarnation: root.incarnation, principal };
+      this.#binding = { child: connection, root };
+    }
+    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';

package/src/results.ts

@@ -0,0 +1,66 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+import { AdapterError, isWebDriverError } from './controller.js';
+
+type Content = CallToolResult['content'][number];
+
+const maxMessageLength = 300;
+
+/**
+ * Renders a value as the model reads it: compact JSON, with any observation outline lifted out into its own text block
+ * so its lines read as lines instead of escaped `\n` runs. Nothing is sent twice.
+ */
+export function jsonResult(value: unknown, extra: Content[] = []): CallToolResult {
+  const outlines: string[] = [];
+  const lifted = liftOutlines(value, outlines);
+  return {
+    content: [{ text: JSON.stringify(lifted), type: 'text' }, ...outlines.map((text): Content => ({ text, type: 'text' })), ...extra],
+  };
+}
+
+/** A failure the model can branch on: the WebDriver error code, the machine reason, and a bounded message. */
+export function errorResult(error: unknown): CallToolResult {
+  let failure: Record<string, unknown>;
+  if (error instanceof AdapterError) {
+    failure = { error: 'adapter', message: error.message, reason: error.reason };
+  } else if (isWebDriverError(error)) {
+    const data = error.data ?? {};
+    failure = {
+      error: error.code,
+      message: bound(error.message),
+      ...pick(data, ['reason', 'nativeCode', 'requestId', 'mutation']),
+    };
+  } else {
+    console.error(`desktop-driver-mcp: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+    failure = { error: 'adapter', message: 'The adapter failed unexpectedly.', reason: 'internal' };
+  }
+  return { content: [{ text: JSON.stringify(failure), type: 'text' }], isError: true };
+}
+
+function liftOutlines(value: unknown, outlines: string[]): unknown {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return value;
+  }
+  const copy: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'outline' && typeof child === 'string') {
+      outlines.push(child);
+      copy.outline = `(text block ${outlines.length + 1})`;
+    } else if (key === 'result' || key === 'observation') {
+      copy[key] = liftOutlines(child, outlines);
+    } else {
+      copy[key] = child;
+    }
+  }
+  return copy;
+}
+
+function pick(data: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> {
+  return Object.fromEntries(keys.filter((key) => data[key] !== undefined).map((key) => [key, data[key]]));
+}
+
+function bound(message: string): string {
+  // The service already bounds operation messages; session errors may quote provider text, so bound them here too.
+  const visible = message.replace(/\p{Cc}/gu, ' ');
+  return visible.length > maxMessageLength ? `${visible.slice(0, maxMessageLength - 1)}…` : visible;
+}