@beeos-ai/device-agent 0.9.3 → 0.9.7

package/dist/mcp-client/client.d.ts

@@ -1,66 +1,122 @@
 /**
- * McpClient — typed HTTP wrapper around `device-mcp-server`.
+ * McpClient — typed wrapper around the official `@modelcontextprotocol/sdk`
+ * Client connected over Streamable HTTP to the sibling
+ * `device-mcp-server` (or any other MCP server speaking the same tools).
  *
- * The device-agent never talks to ADB / desktop sandboxes directly any more —
- * everything goes through this client to the sibling MCP HTTP server. The
- * client is intentionally thin: zero LLM / agent semantics, no caching, no
- * retry on tool errors (only on connection-level failures during health
- * probing).
+ * 0.4.0 reshape:
+ *   - The bespoke `/healthz` / `/mcp/tools/list` / `/mcp/tools/call` /
+ *     `/act` REST surface is gone — everything goes through the SDK
+ *     `Client.callTool` and the `initialize` handshake handled by
+ *     `Client.connect(transport)`.
+ *   - `device-mcp-server` is now a singleton multi-device process; this
+ *     client owns a `defaultDevice` (Ed25519-derived ADB serial / "desktop")
+ *     and injects it as the `device` argument on every `callTool` so the
+ *     server's `BackendRegistry.resolve(...)` always lands on the right
+ *     backend.
+ *   - `act(action)` is implemented locally by translating the Action into
+ *     the matching tool call via `mapActionToTool` and synthesising the
+ *     legacy `ActResponse` envelope on top of the SDK `CallToolResult`.
  *
  * Defaults:
- *   - baseUrl:  http://127.0.0.1:7900   (override via `MCP_URL` env)
+ *   - baseUrl:  http://127.0.0.1:7900  (override via `MCP_URL` env)
  *   - timeout:  30s per request
  *
- * Surface mirrors the Python reference's `MCPClient` plus a couple of
- * device-agent–specific conveniences (`act`, `screenshot`, `uiDump`,
- * `health`, `waitUntilReady`).
+ * Threading: `Client.connect` is invoked lazily on first call. Concurrent
+ * callers share a single in-flight connect promise so the handshake only
+ * runs once. After connect, the client is stateless from the caller's
+ * point of view — every `callTool` is an independent JSON-RPC request.
  */
-import { type Action, type ActResponse, type DeviceInfo, type ExecuteCommandResult, type HealthResponse, type ScreenshotResult, type ToolListResponse, type UiDumpResult } from "@beeos-ai/device-common";
-import type { ExecuteCommandOptions, IMcpRuntime, UiDumpOptions } from "./runtime.js";
+import { EventEmitter } from "node:events";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type Action, type AppInfo, type BackendFamily, type CrashSummary, type DeviceInfo, type ExecuteCommandResult, type Orientation, type SaveScreenshotResult, type ScreenRecordHandle, type ScreenRecordResult, type ScreenshotResult, type UiDumpResult } from "@beeos-ai/device-common";
+import type { ActResponse, CallToolOutput, ExecuteCommandOptions, IMcpRuntime, ListAppsOptions, ScreenshotToFileOptions, StartScreenRecordOptions, SwipeDirectionOptions, UiDumpOptions } from "./runtime.js";
 export interface McpClientOptions {
-    /** HTTP base URL of the sibling device-mcp-server. Falls back to MCP_URL env / 127.0.0.1:7900. */
+    /**
+     * HTTP base URL of the sibling device-mcp-server. Either the bare host
+     * (e.g. `http://127.0.0.1:7900`, in which case we append `/mcp`) or the
+     * full MCP endpoint (`http://127.0.0.1:7900/mcp`). Falls back to MCP_URL
+     * env / 127.0.0.1:7900.
+     */
     baseUrl?: string;
     /** Per-request timeout in ms. Defaults to 30s. */
     timeoutMs?: number;
+    /**
+     * Default device id passed as `device: "..."` on every tool call. Lets
+     * the singleton multi-device server route to the right backend without
+     * the caller having to thread it through every method. Empty / undefined
+     * = no implicit device (server falls back to its single-device default
+     * or to the `use_device` sticky session, neither of which apply over
+     * stateless HTTP — so production should always set this).
+     */
+    defaultDevice?: string;
     /** Optional Bearer / shared-secret auth token forwarded as `Authorization: Bearer ...`. */
     authToken?: string;
-    /** Optional fetch override (used by tests). */
-    fetchImpl?: typeof fetch;
-}
-export interface CallToolResult<T = unknown> {
-    ok: boolean;
-    raw: T;
-    durationMs: number;
+    /**
+     * Backend family of the resolved `defaultDevice`. Used by the
+     * action-mapping layer to fork desktop-only verbs (`click` /
+     * `double_click`) onto their mobile equivalents (`tap` / `double_tap`)
+     * before they hit the wire. `undefined` keeps the legacy 1:1 mapping
+     * (no rewrite) so old call sites and tests don't break.
+     */
+    backendFamily?: BackendFamily;
+    /**
+     * Test seam: inject a pre-built MCP `Transport` (e.g. one half of an
+     * `InMemoryTransport.createLinkedPair()`) instead of opening a real
+     * HTTP connection. When set, `baseUrl` / `authToken` are ignored.
+     * Production callers should never pass this.
+     */
+    transport?: Transport;
 }
 /**
  * Resolve the default MCP base URL (env-aware).
  */
 export declare function resolveDefaultMcpUrl(): string;
-export declare class McpClient implements IMcpRuntime {
-    private readonly baseUrl;
+/** Read the version string the McpClient advertises via MCP `initialize`. */
+export declare function getClientVersion(): string;
+/**
+ * Payload emitted on every `callTool` outcome (including failures from
+ * `invoke`'s try/catch). Subscribed by the device-agent's MCP health
+ * monitor so it can derive the device's connectivity state without
+ * each call site re-implementing the classification:
+ *
+ *   ok=true                                  → MCP + device reachable
+ *   ok=false, subtype="adb_unauthorized"     → device present, ADB not authorised
+ *   ok=false, subtype="mcp_unreachable"      → MCP HTTP transport down
+ *   ok=false, subtype=other / undefined      → device-level failure (treat as disconnected)
+ */
+export interface McpCallResult {
+    ok: boolean;
+    subtype?: string;
+}
+export declare class McpClient extends EventEmitter implements IMcpRuntime {
+    private readonly endpoint;
     private readonly timeoutMs;
+    private readonly defaultDevice?;
     private readonly authToken?;
-    private readonly fetchImpl;
+    private readonly backendFamily?;
+    private readonly client;
+    private readonly injectedTransport?;
+    private connectPromise?;
     constructor(opts?: McpClientOptions);
-    /** Backend health probe. Throws `McpUnreachableError` on connection failure. */
-    health(): Promise<HealthResponse>;
     /**
-     * Wait until the MCP server's `/healthz` returns `ok=true`. Used by
-     * bootstrap to gate startup on the sibling process.
+     * Wait until the MCP server's `initialize` handshake succeeds. Used by
+     * bootstrap to gate startup on the sibling process. Replaces the
+     * pre-0.4 `health()` + `/healthz` probe.
      *
      * Strategy: linear retry with `attemptDelayMs` between probes; gives up
-     * after `attempts` tries. Default: 10 × 500ms = ~5s.
+     * after `attempts` tries. Default: 30 × 500ms = ~15s — large enough to
+     * cover the cold-start window of an autospawned `device-mcp-server`
+     * binary (especially under `tsx`/Node ESM resolve on the first run)
+     * without blocking too long when the server is genuinely unreachable.
      */
     waitUntilReady(opts?: {
         attempts?: number;
         attemptDelayMs?: number;
-    }): Promise<HealthResponse>;
-    /** List all registered MCP tool descriptors. */
-    listTools(): Promise<ToolListResponse>;
-    /** Invoke a single MCP tool by name. */
-    callTool<T = unknown>(name: string, args?: Record<string, unknown>): Promise<CallToolResult<T>>;
-    /** Submit a unified Action — server maps to the right tool internally. */
-    act(action: Action): Promise<ActResponse>;
+    }): Promise<{
+        ok: true;
+    }>;
+    /** Generic MCP tool dispatch — used for tools without a typed convenience method. */
+    callTool<T = unknown>(name: string, args?: Record<string, unknown>): Promise<CallToolOutput<T>>;
     /** Convenience: take a screenshot via `tool: screenshot`. */
     screenshot(): Promise<ScreenshotResult>;
     /**
@@ -76,9 +132,49 @@ export declare class McpClient implements IMcpRuntime {
     executeCommand(body: string, opts?: ExecuteCommandOptions): Promise<ExecuteCommandResult>;
     /**
      * Convenience: push `bytes` to an absolute device-local `path` via
-     * the MCP `file_write` tool. Used by the Resource Resolution Layer
-     * to land downloaded URL payloads on-device before the VLM sees them.
+     * the MCP `file_write` tool.
      */
     fileWrite(path: string, bytes: Buffer): Promise<void>;
-    private request;
+    screenshotToFile(path: string, opts?: ScreenshotToFileOptions): Promise<SaveScreenshotResult>;
+    startScreenRecord(opts?: StartScreenRecordOptions): Promise<ScreenRecordHandle>;
+    stopScreenRecord(id: string, path?: string): Promise<ScreenRecordResult>;
+    swipeDirection(direction: "up" | "down" | "left" | "right", opts?: SwipeDirectionOptions): Promise<void>;
+    pressButton(button: string): Promise<void>;
+    terminateApp(pkg: string): Promise<void>;
+    openUrl(url: string): Promise<void>;
+    listApps(opts?: ListAppsOptions): Promise<AppInfo[]>;
+    listCrashes(): Promise<CrashSummary[]>;
+    getCrash(id: string): Promise<string>;
+    uninstallApp(pkg: string): Promise<void>;
+    setOrientation(orientation: Orientation): Promise<void>;
+    getOrientation(): Promise<Orientation>;
+    /**
+     * MCP `tools/list` — best-effort wrapper for compatibility probes
+     * (bootstrap warns when an old server is missing r3 tools). The
+     * underlying SDK call uses `client.listTools()` and fails gracefully
+     * on transport errors so the caller can decide to log-and-continue.
+     */
+    listTools(): Promise<{
+        name: string;
+    }[]>;
+    /**
+     * Read the server-advertised version (from MCP `initialize` response).
+     * `undefined` when not yet connected. The SDK `getServerVersion()`
+     * returns the full `Implementation { name, version }` shape; we only
+     * need the version string.
+     */
+    getServerVersion(): string | undefined;
+    /**
+     * Submit a unified `Action`. Implemented locally as
+     * `mapActionToTool(action)` → `callTool(...)`. Terminal verbs short-circuit
+     * with a synthetic `{ ok: true, terminal: true }` envelope so the
+     * AgentLoop / ACP handlers can keep treating `act()` as the single dispatch
+     * point.
+     */
+    act(action: Action): Promise<ActResponse>;
+    private ensureConnected;
+    private openTransport;
+    private buildHttpTransport;
+    private invoke;
+    private withDefaultDevice;
 }