@beeos-ai/device-mcp-server 0.3.0 → 0.4.3

package/dist/util/locale.js

@@ -0,0 +1,31 @@
+/**
+ * BCP-47-ish locale-tag validation.
+ *
+ * mobile-mcp parity (round 3): mirrors `validateLocale` from
+ * `mobile-mcp/src/utils.ts` — `[a-zA-Z0-9,\- ]` only. The character class is
+ * deliberately permissive (BCP-47 allows tags like `zh-Hant-TW`, lists like
+ * `fr-FR,en-US`, and Android's `cmd locale set-app-locales` accepts space-
+ * delimited preference lists), but tight enough to keep shell metachars
+ * (`$`, `` ` ``, `;`, `|`) and path separators (`/`, `\`) out.
+ *
+ * Used at the MCP tool boundary (`launch_app({ locale })`) so a prompt-
+ * injected `locale: "$(rm -rf /)"` is rejected before reaching `adb shell`
+ * — `sh\`...\`` template literal in `android-adb.ts` already escapes the
+ * value, so this is defence-in-depth (and a faster, clearer error).
+ */
+import { DeviceError } from "@beeos-ai/device-common";
+const LOCALE_RE = /^[a-zA-Z0-9,\- ]+$/;
+const MAX_LOCALE_LENGTH = 256;
+export function assertValidLocale(s) {
+    if (typeof s !== "string" || s.length === 0) {
+        throw new DeviceError("locale must be a non-empty string", { subtype: "invalid_args", retriable: false });
+    }
+    if (s.length > MAX_LOCALE_LENGTH) {
+        throw new DeviceError(`locale '${s.slice(0, 32)}…' exceeds ${MAX_LOCALE_LENGTH} chars`, { subtype: "invalid_args", retriable: false });
+    }
+    if (!LOCALE_RE.test(s)) {
+        throw new DeviceError(`locale '${s}' contains invalid characters (allowed: a-z A-Z 0-9 , - space)`, { subtype: "invalid_args", retriable: false });
+    }
+    return s;
+}
+//# sourceMappingURL=locale.js.map

package/dist/util/locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.js","sourceRoot":"","sources":["../../src/util/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,MAAM,SAAS,GAAG,oBAAoB,CAAC;AACvC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,WAAW,CACnB,mCAAmC,EACnC,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACjC,MAAM,IAAI,WAAW,CACnB,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,iBAAiB,QAAQ,EAChE,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,WAAW,CACnB,WAAW,CAAC,gEAAgE,EAC5E,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/util/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stderr-only structured logger used by both transports.
+ *
+ * Stdio mode requires that the `stdout` channel carries ONLY MCP JSON-RPC
+ * frames — anything else corrupts the protocol. The default pino logger
+ * also writes to stdout. We pin it to stderr explicitly here and re-use
+ * the same instance from the HTTP transport so both modes log
+ * consistently.
+ *
+ * Consumers can plug in any pino-shaped logger via `BuildAppOptions.logger`
+ * / `RunStdioOptions.logger`. The bundled instance is intentionally
+ * minimal — no transports, no formatting, no rotation. Operators who
+ * want more should bring their own pino instance with the destination of
+ * their choice (also pinned to stderr — never stdout).
+ *
+ * Why not `console.error`? `console.*` ends up in different streams on
+ * different runtimes (especially when wrapped by libraries like jest /
+ * vitest) and the pino instance avoids that surprise — it always goes
+ * to fd 2 directly.
+ */
+export interface Logger {
+    info?: (obj: unknown, msg?: string) => void;
+    warn?: (obj: unknown, msg?: string) => void;
+    error?: (obj: unknown, msg?: string) => void;
+    debug?: (obj: unknown, msg?: string) => void;
+}
+export declare const stderrLogger: Logger;

package/dist/util/logger.js

@@ -0,0 +1,27 @@
+/**
+ * Stderr-only structured logger used by both transports.
+ *
+ * Stdio mode requires that the `stdout` channel carries ONLY MCP JSON-RPC
+ * frames — anything else corrupts the protocol. The default pino logger
+ * also writes to stdout. We pin it to stderr explicitly here and re-use
+ * the same instance from the HTTP transport so both modes log
+ * consistently.
+ *
+ * Consumers can plug in any pino-shaped logger via `BuildAppOptions.logger`
+ * / `RunStdioOptions.logger`. The bundled instance is intentionally
+ * minimal — no transports, no formatting, no rotation. Operators who
+ * want more should bring their own pino instance with the destination of
+ * their choice (also pinned to stderr — never stdout).
+ *
+ * Why not `console.error`? `console.*` ends up in different streams on
+ * different runtimes (especially when wrapped by libraries like jest /
+ * vitest) and the pino instance avoids that surprise — it always goes
+ * to fd 2 directly.
+ */
+import pino from "pino";
+export const stderrLogger = pino({
+    level: process.env.LOG_LEVEL ?? "info",
+    base: { component: "device-mcp-server" },
+    timestamp: pino.stdTimeFunctions.isoTime,
+}, pino.destination(2));
+//# sourceMappingURL=logger.js.map

package/dist/util/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AASxB,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CACtC;IACE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;IACtC,IAAI,EAAE,EAAE,SAAS,EAAE,mBAAmB,EAAE;IACxC,SAAS,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO;CACzC,EACD,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CACpB,CAAC"}

package/dist/util/output-path.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Output-path sandbox for tools that write to the host filesystem.
+ *
+ * `screenshot_to_file({ path })` and `screen_record_stop({ path })` accept a
+ * caller-supplied destination path and previously fed it directly to
+ * `writeFile` / `adb pull <local>`. A prompt-injected LLM could therefore
+ * write `/etc/hosts` or `~/.ssh/authorized_keys` (subject only to OS file
+ * permissions), which is not the security posture we want for a tool
+ * loaded into Cursor / Claude Desktop / production agents.
+ *
+ * The resolution mirrors mobile-mcp's `validateOutputPath` (see
+ * `mobile-mcp/src/utils.ts` L18-L87): allow the caller-supplied path only
+ * if it resolves under one of the trusted roots:
+ *
+ *   1. `process.cwd()` — the operator's working directory at server start
+ *   2. `os.tmpdir()` — the system temp directory (and its `/private/tmp`
+ *      alias on macOS, where `os.tmpdir()` reports `/var/folders/.../T/`
+ *      but `/tmp` is the symlinked entry point most users type)
+ *   3. Each comma- or colon-separated entry of `BEEOS_DEVICE_OUTPUT_DIRS`
+ *      (operator opt-in escape hatch for mounted volumes / shared dirs)
+ *
+ * Anything outside the trusted set throws a `DeviceError("invalid_args")`
+ * before the destructive operation runs.
+ */
+/**
+ * Returns the absolute, resolved form of `target` if it sits under one of
+ * the trusted roots. Otherwise throws `DeviceError("invalid_args")` —
+ * never returns a path that escaped the sandbox.
+ *
+ * Symlinks are NOT followed: we only canonicalise via `path.resolve` so a
+ * legitimate symlink under cwd that points outside is still considered
+ * inside (the kernel will enforce real permissions at write time).
+ * Following symlinks here would surprise operators who deliberately link
+ * a writable cwd entry to an external mount.
+ */
+export declare function assertSafeOutputPath(target: string, opts?: {
+    extraRoots?: string;
+}): string;
+/**
+ * Same as {@link assertSafeOutputPath}, but ALSO restricts the file
+ * extension to a fixed allow-list. Used by tools that need both sandbox
+ * and codec consistency:
+ *
+ *   - `screenshot_to_file({ path })`               — `.png` / `.jpg` / `.jpeg`
+ *   - `screen_record_start({ output })`            — `.mp4`
+ *   - `screen_record_stop({ path })`               — `.mp4`
+ *
+ * mobile-mcp parity (round 3): mirrors `validateFileExtension` from
+ * `mobile-mcp/src/utils.ts` — without it, a prompt-injected agent could
+ * write a screenshot to `~/Downloads/cute.png.exe` (cwd-relative) and
+ * have the OS treat it as an executable on platforms that key on file
+ * extension. We do the extension check AFTER the path is sandboxed, so
+ * the sandbox failure mode (clearer) still wins on outright bad paths.
+ *
+ * `allowedExts` should be lowercase and dot-prefixed (`[".png", ".jpg"]`).
+ * Comparison is case-insensitive.
+ */
+export declare function assertSafeOutputPathWithExt(target: string, allowedExts: readonly string[], opts?: {
+    extraRoots?: string;
+}): string;

package/dist/util/output-path.js

@@ -0,0 +1,123 @@
+/**
+ * Output-path sandbox for tools that write to the host filesystem.
+ *
+ * `screenshot_to_file({ path })` and `screen_record_stop({ path })` accept a
+ * caller-supplied destination path and previously fed it directly to
+ * `writeFile` / `adb pull <local>`. A prompt-injected LLM could therefore
+ * write `/etc/hosts` or `~/.ssh/authorized_keys` (subject only to OS file
+ * permissions), which is not the security posture we want for a tool
+ * loaded into Cursor / Claude Desktop / production agents.
+ *
+ * The resolution mirrors mobile-mcp's `validateOutputPath` (see
+ * `mobile-mcp/src/utils.ts` L18-L87): allow the caller-supplied path only
+ * if it resolves under one of the trusted roots:
+ *
+ *   1. `process.cwd()` — the operator's working directory at server start
+ *   2. `os.tmpdir()` — the system temp directory (and its `/private/tmp`
+ *      alias on macOS, where `os.tmpdir()` reports `/var/folders/.../T/`
+ *      but `/tmp` is the symlinked entry point most users type)
+ *   3. Each comma- or colon-separated entry of `BEEOS_DEVICE_OUTPUT_DIRS`
+ *      (operator opt-in escape hatch for mounted volumes / shared dirs)
+ *
+ * Anything outside the trusted set throws a `DeviceError("invalid_args")`
+ * before the destructive operation runs.
+ */
+import * as path from "node:path";
+import * as os from "node:os";
+import { DeviceError } from "@beeos-ai/device-common";
+/** Resolve and freeze the trusted-roots list once per call. */
+function trustedRoots(extraRootsRaw) {
+    // process.cwd() may shift across calls (rare, but tests exercise it),
+    // so we recompute on every invocation — micro-perf is negligible.
+    const cwd = path.resolve(process.cwd());
+    const tmp = path.resolve(os.tmpdir());
+    const roots = new Set([cwd, tmp]);
+    // macOS `os.tmpdir()` resolves to `/var/folders/.../T/` but the canonical
+    // user-visible path is `/private/tmp` (and the bare `/tmp` symlink). Add
+    // both aliases explicitly so `--output-dir /tmp/foo` callers don't get
+    // a misleading "outside sandbox" error on macOS.
+    if (process.platform === "darwin") {
+        roots.add("/private/tmp");
+        roots.add("/tmp");
+    }
+    // Operator opt-in extras. Comma OR colon separated to match the
+    // convention used elsewhere in BeeOS (`PATH`-like colons on POSIX,
+    // commas in env-style lists).
+    const raw = extraRootsRaw ?? process.env.BEEOS_DEVICE_OUTPUT_DIRS ?? "";
+    for (const entry of raw.split(/[,:]/)) {
+        const trimmed = entry.trim();
+        if (trimmed.length > 0)
+            roots.add(path.resolve(trimmed));
+    }
+    return [...roots];
+}
+/**
+ * Returns the absolute, resolved form of `target` if it sits under one of
+ * the trusted roots. Otherwise throws `DeviceError("invalid_args")` —
+ * never returns a path that escaped the sandbox.
+ *
+ * Symlinks are NOT followed: we only canonicalise via `path.resolve` so a
+ * legitimate symlink under cwd that points outside is still considered
+ * inside (the kernel will enforce real permissions at write time).
+ * Following symlinks here would surprise operators who deliberately link
+ * a writable cwd entry to an external mount.
+ */
+export function assertSafeOutputPath(target, opts = {}) {
+    if (typeof target !== "string" || target.length === 0) {
+        throw new DeviceError("output path must be a non-empty string", {
+            subtype: "invalid_args",
+            retriable: false,
+        });
+    }
+    const resolved = path.resolve(target);
+    const roots = trustedRoots(opts.extraRoots);
+    for (const root of roots) {
+        if (isUnder(root, resolved))
+            return resolved;
+    }
+    throw new DeviceError(`output path '${target}' is outside the sandbox (allowed roots: ${roots.join(", ")}). Set BEEOS_DEVICE_OUTPUT_DIRS to widen the allow-list.`, { subtype: "invalid_args", retriable: false });
+}
+/**
+ * Same as {@link assertSafeOutputPath}, but ALSO restricts the file
+ * extension to a fixed allow-list. Used by tools that need both sandbox
+ * and codec consistency:
+ *
+ *   - `screenshot_to_file({ path })`               — `.png` / `.jpg` / `.jpeg`
+ *   - `screen_record_start({ output })`            — `.mp4`
+ *   - `screen_record_stop({ path })`               — `.mp4`
+ *
+ * mobile-mcp parity (round 3): mirrors `validateFileExtension` from
+ * `mobile-mcp/src/utils.ts` — without it, a prompt-injected agent could
+ * write a screenshot to `~/Downloads/cute.png.exe` (cwd-relative) and
+ * have the OS treat it as an executable on platforms that key on file
+ * extension. We do the extension check AFTER the path is sandboxed, so
+ * the sandbox failure mode (clearer) still wins on outright bad paths.
+ *
+ * `allowedExts` should be lowercase and dot-prefixed (`[".png", ".jpg"]`).
+ * Comparison is case-insensitive.
+ */
+export function assertSafeOutputPathWithExt(target, allowedExts, opts = {}) {
+    const safe = assertSafeOutputPath(target, opts);
+    const ext = path.extname(safe).toLowerCase();
+    if (!allowedExts.includes(ext)) {
+        throw new DeviceError(`output path '${target}' has unsupported extension '${ext || "(none)"}' (allowed: ${allowedExts.join(", ")})`, { subtype: "invalid_args", retriable: false });
+    }
+    return safe;
+}
+/** True iff `child` is `root` or a descendant. Both inputs must be resolved. */
+function isUnder(root, child) {
+    if (child === root)
+        return true;
+    const rel = path.relative(root, child);
+    // `path.relative` returns "" for identity, "..[/...]" when `child`
+    // escapes upward, or an absolute path on Windows when crossing drive
+    // letters. All three escape cases are filtered out below.
+    if (rel === "" || rel === ".")
+        return true;
+    if (rel.startsWith(".."))
+        return false;
+    if (path.isAbsolute(rel))
+        return false;
+    return true;
+}
+//# sourceMappingURL=output-path.js.map

package/dist/util/output-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-path.js","sourceRoot":"","sources":["../../src/util/output-path.ts"],"names":[],"mappings":"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"}

package/dist/util/package-name.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Android package-name validation.
+ *
+ * mobile-mcp parity (round 3): mirrors `validatePackageName` from
+ * `mobile-mcp/src/utils.ts` — `[a-zA-Z0-9._]` only, with no leading dot
+ * relaxation since Android's own package-name grammar (RFC-1034 segments
+ * separated by `.`) maps cleanly onto this character class.
+ *
+ * Used at the MCP tool boundary (`terminate_app`, `uninstall_app`) to fail
+ * a malformed input EARLY — before it travels through the runner, gets
+ * shell-escaped by `sh\`...\``, and produces a confusing "package not
+ * found" error from `pm uninstall`. We deliberately do NOT call this in
+ * `launch_app` because that handler accepts user-friendly display names
+ * (e.g. "WeChat" -> `com.tencent.mm`) which are mapped to package ids
+ * inside the backend.
+ */
+/**
+ * Throw `DeviceError({ subtype: "invalid_args" })` if `name` doesn't match
+ * the Android package-name grammar. Returns `name` unchanged on success so
+ * callers can write `assertValidPackageName(args.pkg)` inline.
+ *
+ * Empty / non-string / over-length inputs all reject. Defaults inherit
+ * `userActionable=true` from the `invalid_args` subtype so the LLM sees a
+ * plain-text actionable response instead of an `isError` protocol failure.
+ */
+export declare function assertValidPackageName(name: string): string;

package/dist/util/package-name.js

@@ -0,0 +1,41 @@
+/**
+ * Android package-name validation.
+ *
+ * mobile-mcp parity (round 3): mirrors `validatePackageName` from
+ * `mobile-mcp/src/utils.ts` — `[a-zA-Z0-9._]` only, with no leading dot
+ * relaxation since Android's own package-name grammar (RFC-1034 segments
+ * separated by `.`) maps cleanly onto this character class.
+ *
+ * Used at the MCP tool boundary (`terminate_app`, `uninstall_app`) to fail
+ * a malformed input EARLY — before it travels through the runner, gets
+ * shell-escaped by `sh\`...\``, and produces a confusing "package not
+ * found" error from `pm uninstall`. We deliberately do NOT call this in
+ * `launch_app` because that handler accepts user-friendly display names
+ * (e.g. "WeChat" -> `com.tencent.mm`) which are mapped to package ids
+ * inside the backend.
+ */
+import { DeviceError } from "@beeos-ai/device-common";
+const PACKAGE_NAME_RE = /^[a-zA-Z0-9._]+$/;
+const MAX_PACKAGE_NAME_LENGTH = 255;
+/**
+ * Throw `DeviceError({ subtype: "invalid_args" })` if `name` doesn't match
+ * the Android package-name grammar. Returns `name` unchanged on success so
+ * callers can write `assertValidPackageName(args.pkg)` inline.
+ *
+ * Empty / non-string / over-length inputs all reject. Defaults inherit
+ * `userActionable=true` from the `invalid_args` subtype so the LLM sees a
+ * plain-text actionable response instead of an `isError` protocol failure.
+ */
+export function assertValidPackageName(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new DeviceError("package name must be a non-empty string", { subtype: "invalid_args", retriable: false });
+    }
+    if (name.length > MAX_PACKAGE_NAME_LENGTH) {
+        throw new DeviceError(`package name '${name.slice(0, 32)}…' exceeds ${MAX_PACKAGE_NAME_LENGTH} chars`, { subtype: "invalid_args", retriable: false });
+    }
+    if (!PACKAGE_NAME_RE.test(name)) {
+        throw new DeviceError(`package name '${name}' contains invalid characters (allowed: a-z A-Z 0-9 . _)`, { subtype: "invalid_args", retriable: false });
+    }
+    return name;
+}
+//# sourceMappingURL=package-name.js.map

package/dist/util/package-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-name.js","sourceRoot":"","sources":["../../src/util/package-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,WAAW,CACnB,yCAAyC,EACzC,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC1C,MAAM,IAAI,WAAW,CACnB,iBAAiB,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,uBAAuB,QAAQ,EAC/E,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,WAAW,CACnB,iBAAiB,IAAI,0DAA0D,EAC/E,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beeos-ai/device-mcp-server",
-  "version": "0.3.0",
-  "description": "In-pod HTTP MCP tool server for BeeOS device-agent (Android / desktop / mobile sandboxes).",
+  "version": "0.4.3",
+  "description": "Singleton multi-device MCP tool server for BeeOS device-agent (Android / desktop / mobile sandboxes). Implements the Model Context Protocol over Streamable HTTP and stdio.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -34,13 +34,15 @@
     "node": ">=20"
   },
   "dependencies": {
-    "fastify": "^5.8.5",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^4.22.1",
     "pino": "^10.3.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
     "@beeos-ai/device-common": "0.3.0"
   },
   "devDependencies": {
+    "@types/express": "^4.17.25",
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0",

package/dist/server/action-mapping.d.ts

@@ -1,21 +0,0 @@
-/**
- * action-mapping — translate a unified `Action` (`type+target+payload`) into
- * the matching MCP tool name + arguments.
- *
- * Used by `POST /act` so callers can hand the server a high-level Action and
- * skip wiring up a tool name themselves. Mirrors the Python reference's
- * `_action_to_call` table.
- */
-import { type Action, type ActionType } from "@beeos-ai/device-common";
-export interface ToolCall {
-    toolName: string;
-    args: Record<string, unknown>;
-}
-export interface UnsupportedActionResult {
-    /** Terminal verbs (`done`, `fail`, `wait`, `call_for_user`) — server replies
-     *  with `{ ok: true, action }` and does NOT touch the backend. */
-    terminal: true;
-    type: ActionType;
-}
-export type ActionMappingResult = ToolCall | UnsupportedActionResult;
-export declare function mapActionToTool(action: Action): ActionMappingResult;

package/dist/server/action-mapping.js

@@ -1,153 +0,0 @@
-/**
- * action-mapping — translate a unified `Action` (`type+target+payload`) into
- * the matching MCP tool name + arguments.
- *
- * Used by `POST /act` so callers can hand the server a high-level Action and
- * skip wiring up a tool name themselves. Mirrors the Python reference's
- * `_action_to_call` table.
- */
-import { TERMINAL_ACTIONS, } from "@beeos-ai/device-common";
-export function mapActionToTool(action) {
-    if (TERMINAL_ACTIONS.has(action.type) || action.type === "wait") {
-        return { terminal: true, type: action.type };
-    }
-    const target = action.target;
-    const payload = action.payload ?? {};
-    switch (action.type) {
-        case "click":
-        case "tap":
-        case "double_click":
-        case "right_click":
-        case "long_press":
-        case "move": {
-            const xy = pointFromTarget(target);
-            return {
-                toolName: action.type === "move" ? "move" : action.type,
-                args: {
-                    ...xy,
-                    ...(action.type === "click" && payload.button ? { button: payload.button } : {}),
-                    ...(action.type === "click" && payload.clicks ? { clicks: payload.clicks } : {}),
-                    ...(action.type === "long_press" && payload.durationMs
-                        ? { durationMs: payload.durationMs }
-                        : {}),
-                },
-            };
-        }
-        case "drag":
-        case "swipe": {
-            const seg = segmentFromTarget(target);
-            return {
-                toolName: action.type,
-                args: {
-                    ...seg,
-                    ...(payload.durationMs ? { durationMs: payload.durationMs } : {}),
-                },
-            };
-        }
-        case "scroll": {
-            const xy = target ? pointFromTarget(target) : { x: 0, y: 0 };
-            return {
-                toolName: "scroll",
-                args: {
-                    ...xy,
-                    direction: payload.direction ?? "down",
-                    ...(payload.amount ? { amount: payload.amount } : {}),
-                },
-            };
-        }
-        case "type":
-            return {
-                toolName: "type",
-                args: { text: payload.text ?? "" },
-            };
-        case "key":
-            return {
-                toolName: "key",
-                args: { key: payload.key ?? payload.keycode ?? "" },
-            };
-        case "hotkey":
-            return {
-                toolName: "hotkey",
-                args: { keys: payload.keys ?? [] },
-            };
-        case "back":
-            return { toolName: "back", args: {} };
-        case "home":
-            return { toolName: "home", args: {} };
-        case "navigate":
-            return {
-                toolName: "back",
-                args: {},
-            };
-        case "launch_app": {
-            const fromTarget = target && (target.kind === "text" || target.kind === "selector")
-                ? target.value
-                : undefined;
-            const pkg = fromTarget ??
-                payload.pkg ??
-                payload.appName ??
-                payload.packageOrName ??
-                payload.package ??
-                "";
-            return {
-                toolName: "launch_app",
-                args: {
-                    pkg,
-                    ...(payload.activity ? { activity: payload.activity } : {}),
-                },
-            };
-        }
-        case "screenshot":
-            return { toolName: "screenshot", args: {} };
-        case "ui_dump":
-            return {
-                toolName: "ui_dump",
-                args: {
-                    ...(payload.query ? { query: payload.query } : {}),
-                    ...(payload.format ? { format: payload.format } : {}),
-                },
-            };
-        case "execute_command":
-        case "run_code":
-            return {
-                toolName: "execute_command",
-                args: {
-                    body: payload.body ?? payload.command ?? "",
-                    ...(payload.timeoutS ? { timeoutS: payload.timeoutS } : {}),
-                    ...(payload.cwd ? { cwd: payload.cwd } : {}),
-                },
-            };
-        case "file_read": {
-            const path = payload.path ??
-                (target && (target.kind === "text" || target.kind === "selector")
-                    ? target.value
-                    : "");
-            return { toolName: "file_read", args: { path } };
-        }
-        case "file_write": {
-            const path = payload.path ??
-                (target && (target.kind === "text" || target.kind === "selector")
-                    ? target.value
-                    : "");
-            return {
-                toolName: "file_write",
-                args: { path, contentB64: payload.contentB64 ?? "" },
-            };
-        }
-        default:
-            throw new Error(`unsupported action type: ${String(action.type)}`);
-    }
-}
-function pointFromTarget(target) {
-    if (target && target.kind === "point") {
-        return { x: target.x, y: target.y };
-    }
-    throw new TypeError("action.target must be {kind:'point', x, y} for this action type");
-}
-function segmentFromTarget(target) {
-    if (target && target.kind === "box") {
-        return { x1: target.x1, y1: target.y1, x2: target.x2, y2: target.y2 };
-    }
-    throw new TypeError("action.target must be {kind:'box', x1, y1, x2, y2} for this action type");
-}
-//# sourceMappingURL=action-mapping.js.map

package/dist/server/action-mapping.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"action-mapping.js","sourceRoot":"","sources":["../../src/server/action-mapping.ts"],"names":[],"mappings":"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"}