@beeos-ai/device-agent 0.4.2 → 0.5.0

package/dist/mcp-client/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/mcp-client/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,mBAAmB,GAUpB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AACjD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAmBlC;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,gBAAgB,CAAC;AACjD,CAAC;AAED,MAAM,OAAO,SAAS;IACH,OAAO,CAAS;IAChB,SAAS,CAAS;IAClB,SAAS,CAAU;IACnB,SAAS,CAAe;IAEzC,YAAY,OAAyB,EAAE;QACrC,IAAI,CAAC,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,IAAI,oBAAoB,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;QACtD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IAC3C,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAiB,KAAK,EAAE,UAAU,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,mBAAmB,CAC3B,6BAA6B,IAAI,CAAC,OAAO,KAAM,CAAW,CAAC,OAAO,EAAE,EACpE,CAAC,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAAC,OAAuD,EAAE;QAC5E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,IAAI,GAAG,CAAC;QACzC,IAAI,OAAgB,CAAC;QACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC9B,IAAI,CAAC,CAAC,EAAE;oBAAE,OAAO,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,GAAG,CAAC,CAAC;YACd,CAAC;YACD,MAAM,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,IAAI,mBAAmB,CAC3B,iBAAiB,IAAI,CAAC,OAAO,+BAA+B,QAAQ,WAAW,EAC/E,OAAO,CACR,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,OAAO,CAAmB,MAAM,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,QAAQ,CACZ,IAAY,EACZ,OAAgC,EAAE;QAElC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAsB,MAAM,EAAE,iBAAiB,EAAE;YAC7E,IAAI;YACJ,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,MAAW,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;IAC1E,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,GAAG,CAAC,MAAc;QACtB,OAAO,IAAI,CAAC,OAAO,CAAc,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,UAAU;QACd,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAmB,YAAY,EAAE,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC,GAAG,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,OAAsB,EAAE;QACnC,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACtD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAe,SAAS,EAAE,IAAI,CAAC,CAAC;QAC7D,OAAO,CAAC,CAAC,GAAG,CAAC;IACf,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,IAAI;QACR,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAa,aAAa,EAAE,EAAE,CAAC,CAAC;QAC7D,OAAO,CAAC,CAAC,GAAG,CAAC;IACf,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,UAAU,CAAC,IAAY;QAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,cAAc,CAClB,IAAY,EACZ,OAA8B,EAAE;QAEhC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAuB,iBAAiB,EAAE;YACrE,IAAI;YACJ,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrD,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,GAAG,CAAC;IACf,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,wEAAwE;IAEhE,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QACnE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;QAC/E,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,SAAS,EAAE,CAAC;QAEvE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3E,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;gBACpC,MAAM;gBACN,OAAO;gBACP,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC3D,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACjD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,MAAM,GACV,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAK,MAA6B,CAAC,KAAK,CAAC;oBAC9E,QAAQ,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;gBACzC,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,OAAO,MAAM,IAAI,IAAI,YAAY,MAAM,EAAE,CAAC,CAAC;gBAChE,GAA2C,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;gBAChE,GAA2C,CAAC,IAAI,GAAG,MAAM,IAAI,IAAI,CAAC;gBACnE,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,OAAO,MAAW,CAAC;QACrB,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;CACF;AAED,SAAS,iBAAiB,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS;IACzB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/mcp-client/client.ts"],"names":[],"mappings":"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"}

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

@@ -31,4 +31,17 @@ export interface IMcpRuntime {
     installApk?(path: string): Promise<void>;
     /** Run a shell command on the sandbox. Optional. */
     executeCommand?(body: string, opts?: ExecuteCommandOptions): Promise<ExecuteCommandResult>;
+    /**
+     * Write `bytes` to an absolute device-local `path`. Optional.
+     *
+     * Used by the Resource Resolution Layer to push downloaded URL
+     * payloads onto the device before the VLM ever sees the prompt.
+     * Implementations:
+     *   - real `McpClient` → `callTool("file_write", { path, contentB64 })`
+     *   - `InProcMcpClient` is allowed to throw `"unsupported"` (the
+     *     legacy in-process bridge does not have a generic file-write
+     *     primitive; production paths always go through the sibling
+     *     `device-mcp-server` HTTP service).
+     */
+    fileWrite?(path: string, bytes: Buffer): Promise<void>;
 }

package/dist/orchestrator-system-prompt.d.ts

@@ -2,5 +2,31 @@
  * Outer orchestrator system prompts (pi-coding-agent).
  * Per-tool details live in tool `description` / schema, not here.
  * Select via ORCH_LANG env var: "cn" (default) | "en".
+ *
+ * Phase 2 (GUI-Shortcut Hybrid Plan, MAS-Bench 2025 SOTA):
+ *   The prompt below now codifies three GENERIC heuristics for
+ *   choosing between GUI primitives (`mobile_use`) and structured
+ *   shortcuts (`download_to_device`, `set_clipboard`, `open_deeplink`,
+ *   `find_app_package`):
+ *
+ *     1. **prefer-shortcut-when-applicable** — when a structured
+ *        shortcut covers the user's need, call it before resorting
+ *        to mobile_use. Shortcuts complete in O(1) ADB calls vs
+ *        mobile_use's O(N) screenshot loop.
+ *     2. **avoid-misuse** — shortcuts are not free-form. Never
+ *        invent shortcut arguments; respect the JSON schema. If a
+ *        shortcut's pre-conditions don't hold (no URL, no installed
+ *        app), fall back to mobile_use rather than fabricating an
+ *        argument.
+ *     3. **shortcut-failure-fallback-to-mobile_use** — every
+ *        shortcut returns a structured `{ok:false, code:"..."}`
+ *        result on failure (`app_not_found`, `intent_rejected`,
+ *        `timeout`, `unsupported_platform`, …). When you see one,
+ *        switch to `mobile_use` for the same goal. Do NOT retry
+ *        the same shortcut with the same args.
+ *
+ *   The prompt is **app-agnostic** by construction — no app names,
+ *   no package names, no GUI path hints. The shortcuts themselves
+ *   are also app-agnostic (e.g. `open_deeplink` accepts any URI).
  */
 export declare const ORCHESTRATOR_SYSTEM_PROMPT: string;

package/dist/orchestrator-system-prompt.js

@@ -2,7 +2,73 @@
  * Outer orchestrator system prompts (pi-coding-agent).
  * Per-tool details live in tool `description` / schema, not here.
  * Select via ORCH_LANG env var: "cn" (default) | "en".
+ *
+ * Phase 2 (GUI-Shortcut Hybrid Plan, MAS-Bench 2025 SOTA):
+ *   The prompt below now codifies three GENERIC heuristics for
+ *   choosing between GUI primitives (`mobile_use`) and structured
+ *   shortcuts (`download_to_device`, `set_clipboard`, `open_deeplink`,
+ *   `find_app_package`):
+ *
+ *     1. **prefer-shortcut-when-applicable** — when a structured
+ *        shortcut covers the user's need, call it before resorting
+ *        to mobile_use. Shortcuts complete in O(1) ADB calls vs
+ *        mobile_use's O(N) screenshot loop.
+ *     2. **avoid-misuse** — shortcuts are not free-form. Never
+ *        invent shortcut arguments; respect the JSON schema. If a
+ *        shortcut's pre-conditions don't hold (no URL, no installed
+ *        app), fall back to mobile_use rather than fabricating an
+ *        argument.
+ *     3. **shortcut-failure-fallback-to-mobile_use** — every
+ *        shortcut returns a structured `{ok:false, code:"..."}`
+ *        result on failure (`app_not_found`, `intent_rejected`,
+ *        `timeout`, `unsupported_platform`, …). When you see one,
+ *        switch to `mobile_use` for the same goal. Do NOT retry
+ *        the same shortcut with the same args.
+ *
+ *   The prompt is **app-agnostic** by construction — no app names,
+ *   no package names, no GUI path hints. The shortcuts themselves
+ *   are also app-agnostic (e.g. `open_deeplink` accepts any URI).
  */
+const HEURISTICS_CN = `\
+## Hybrid 动作空间启发式（GUI + Shortcut）
+
+工具分两类：
+- **GUI 原语**：\`mobile_use\` / \`ground\` / \`ui_xml\`（视觉推理，O(N) 步骤）
+- **Shortcut**：\`download_to_device\` / \`set_clipboard\` / \`open_deeplink\` / \`find_app_package\`（结构化输入，O(1) 调用）
+
+三条通用启发式（**与具体 App 无关**）：
+
+1. **能用 shortcut 就先用 shortcut**：
+   - 任务里出现 URL → 先 \`download_to_device\` 把文件落到设备
+   - 任务里出现长文本 / 含 emoji → 先 \`set_clipboard\` 再让 GUI 粘贴
+   - 任务里有可识别的 deeplink（\`xx://\`、\`geo:\`、\`https://\`） → 先 \`open_deeplink\`
+   - 需要包名 → 先 \`find_app_package\` 模糊查询
+   - shortcut 不成立时（无 URL、无文本、无 deeplink）→ 直接走 \`mobile_use\`
+
+2. **不要伪造 shortcut 参数**：
+   - 严格按工具 \`parameters\` schema 调用
+   - 不知道某个参数的真实值时（如不知道目标 deeplink）→ 不要瞎猜，直接 \`mobile_use\`
+
+3. **shortcut 失败 → fallback \`mobile_use\`**：
+   - shortcut 返回 \`{ok:false, code:"..."}\` 是结构化失败信号，不是异常
+   - 常见失败码：\`app_not_found\`（未安装目标应用）、\`intent_rejected\`（系统拒绝）、\`timeout\`、\`unsupported_platform\`（设备不是 Android 或 desktop 不支持）
+   - 看到失败码后**用同样的目标任务调用 \`mobile_use\`**，不要用同样参数重试 shortcut
+
+4. **「发布 / 分享 / 上传」类任务的执行路径（app-agnostic, first-principles）：**
+
+   当任务里同时出现 **「发 / 发布 / 分享 / 上传 / post / share / upload」** + **资源**（URL / 文件路径 / 长文本 / 媒体）时：
+   - **Intent = 主动创建新内容并把资源附加到目标 App 的内容流**，**不是**在已有内容里查找该资源
+   - 标准 GUI 路径（在任何 App 都通用）：\`进入目标 App → 找到「+ / 创建 / 拍摄 / 编辑 / 发布」入口 → 选择 / 插入资源 → 写文案 → 提交\`
+   - **禁止**在已有内容流（feed / timeline / 列表 / 收件箱 / 个人主页）里 swipe / 浏览 / 查找该资源——这条路径根本不会成功，资源是你刚下载的，不在任何人的 timeline 里
+   - 反复触发 \`pre-sanity blocked: blind_swipe\` 是**强信号**：你**进错了页面**，停止 swipe，立刻调用 \`ui_xml\` 看清当前 Activity，然后 \`mobile_use\` 跳到正确的「创建入口」（如长按相机图标 / 点击右上角 + 号 / 拉起底部抽屉等），而不是继续滑动
+
+   **关于资源在相册 / picker 里的位置（强约束）**：\`Resources prepared\` 块里 \`mtime=now\` 意味着该资源是**刚刚**下载到设备的（已 trigger MediaScanner 写入 MediaStore）。Android 系统的相册 / 图片 picker / 文件管理器**默认按 \`date_added\` 倒序**排列，因此该资源一定出现在**最前面（第一张 / 第一行 / 最近列表的顶部）**。
+
+   - **MUST**: 进入 picker 后**第一个动作必须是 tap 第一项**（左上角第一个缩略图 / 列表第一行）。仅当第一项明显不是目标 MIME 类型（例如期望 image/webp 但第一项是视频缩略图）才考虑后续策略。
+   - **MUST NOT — 反搜索**：**绝不**在 picker 里通过文件名 / 关键字 / 文字搜索来找该资源。资源的文件名是机器生成的 \`beeos_<时间戳>_<hash>.<扩展名>\`，picker 的搜索功能基于平台元数据索引（人脸 / 地点 / 物体 OCR），用文件名搜索必然 0 结果。
+   - **MUST NOT — 反识图**：**不要识别图片内容**（如"这看起来是蜂巢/风景/头像"）然后用关键字去搜索。**任务里的 URL 已经是 unique reference**，文件已落到 \`Resources prepared\` 块里给出的具体路径，picker 第一项就是它。"识图→搜索"是反模式，比"直接 tap 第一项"慢 10 倍且永远找不到。
+
+`;
 const CN = `\
 # Android 手机自动化编排 Agent
 
@@ -12,10 +78,15 @@ const CN = `\
 
 | 工具 | 适用场景 |
 |------|----------|
-| \`mobile_use\` | **首选**。大多数任务直接交给它；内部跑 VLM 截图→推理→执行闭环，自主完成多步操作。 |
+| \`mobile_use\` | **GUI 主路径**。多步视觉操作交给它，内部跑 VLM 截图→推理→执行闭环。 |
 | \`ground\` | 需要**精确像素坐标**时：补救 \`mobile_use\` 误触，或配合 adb 手动执行点击。 |
 | \`ui_xml\` | 需要**查看控件树**（resource-id / bounds / clickable）时：调试或确认当前页面状态。 |
+| \`download_to_device\` | 任务里带 URL，需要把文件落到设备相册 / 下载目录时使用。 |
+| \`set_clipboard\` | 长文本 / 含 emoji 的输入：写到剪贴板再让 GUI 粘贴比直接键盘输入更可靠。 |
+| \`open_deeplink\` | 已知 deeplink URI 时：直接跳转目标页，跳过多步导航。 |
+| \`find_app_package\` | 通过 App 名片段查询包名（用于生成 deeplink、\`monkey\` 启动等）。 |
 
+${HEURISTICS_CN}
 ## 调用规则
 
 **\`mobile_use\`**
@@ -39,6 +110,46 @@ const CN = `\
 ## 交流
 
 用户问你是否具备某工具（如 \`mobile_use\`）时，明确回答可否并一句话说明用途；禁止仅用「hi」等无信息回复。
+`;
+const HEURISTICS_EN = `\
+## Hybrid action-space heuristics (GUI + Shortcut)
+
+Tools split into two camps:
+- **GUI primitives** — \`mobile_use\` / \`ground\` / \`ui_xml\` (visual reasoning, O(N) steps)
+- **Shortcuts** — \`download_to_device\` / \`set_clipboard\` / \`open_deeplink\` / \`find_app_package\` (structured input, O(1) calls)
+
+Three generic heuristics (**app-agnostic**):
+
+1. **Prefer shortcuts when applicable**
+   - Task contains a URL → call \`download_to_device\` first to land the file on the device
+   - Task contains long / emoji-heavy text → use \`set_clipboard\` then have the GUI paste
+   - Task contains a recognisable deeplink URI (\`xx://\`, \`geo:\`, \`https://\`) → \`open_deeplink\` first
+   - Need a package name → \`find_app_package\` substring lookup
+   - When no shortcut applies (no URL, no text, no deeplink) → go straight to \`mobile_use\`
+
+2. **Do not fabricate shortcut arguments**
+   - Strict adherence to each tool's \`parameters\` JSON schema
+   - When a parameter's true value is unknown (e.g. you don't know the target deeplink) → do NOT guess, call \`mobile_use\` instead
+
+3. **Shortcut failure → fall back to \`mobile_use\`**
+   - A shortcut return of \`{ok:false, code:"..."}\` is a structured signal, not an exception
+   - Common codes: \`app_not_found\` (target app not installed), \`intent_rejected\` (OS refused), \`timeout\`, \`unsupported_platform\` (device is not Android, or desktop can't handle the asset)
+   - On failure, **call \`mobile_use\` for the same goal**. Never retry the same shortcut with the same arguments.
+
+4. **Intent classification for "post / share / upload" tasks (app-agnostic, first-principles):**
+
+   When the task contains **"post / share / upload / 发 / 发布 / 分享 / 上传"** + **a resource** (URL / file path / long text / media):
+   - **Intent = create new content and attach the resource to the target app's content stream**, NOT find that resource inside existing content
+   - Universal GUI path (works in every app): \`enter target app → locate "+ / create / camera / compose / publish" entry → select/insert the resource → write copy → submit\`
+   - **Never** swipe through feeds / timelines / lists / inboxes / profiles searching for the resource — that path can never succeed; the resource was just downloaded and is not in anyone's timeline
+   - Repeated \`pre-sanity blocked: blind_swipe\` is a **strong signal that you are on the wrong screen**. Stop swiping, call \`ui_xml\` to read the current Activity, then \`mobile_use\` to jump to the correct "create entry" (long-press the camera icon, tap the top-right "+", pull a bottom sheet, etc.). Do NOT keep scrolling.
+
+   **Resource position inside gallery / picker (hard constraint)**: \`mtime=now\` in the \`Resources prepared\` block means the resource was **just** downloaded to the device (MediaScanner has registered it in MediaStore). Android's gallery / image picker / file manager **sorts by \`date_added\` DESC by default**, so the resource is **always at the very top — first thumbnail / first row / top of "Recent"**.
+
+   - **MUST**: Once a picker is open, the **first action must be tap the first item** (top-left thumbnail / first list row). Only consider alternatives if the first item is obviously the wrong MIME (e.g. expected image/webp but the first slot is a video).
+   - **MUST NOT — anti-search**: **NEVER** search for the resource by filename / keyword / text inside a picker. The filename is machine-generated (\`beeos_<timestamp>_<hash>.<ext>\`), and picker search uses platform metadata indices (faces / places / object OCR), so a filename query yields 0 results.
+   - **MUST NOT — anti-vision-recognition**: **Do not look at the picture and try to recognise its content** ("this looks like a beehive / landscape / avatar") and then search by keyword. The URL in the task is already a **unique reference**, and the file is at the exact path shown in \`Resources prepared\`. The picker's first item *is* it. "Recognise → search" is an anti-pattern: 10× slower than "tap first item" and it will never succeed.
+
 `;
 const EN = `\
 # Android device orchestration agent
@@ -49,10 +160,15 @@ const EN = `\
 
 | Tool | When to use |
 |------|-------------|
-| \`mobile_use\` | **Default.** Handles most tasks; runs a VLM screenshot→reason→act loop autonomously. |
+| \`mobile_use\` | **GUI main path.** Multi-step visual operations; runs a VLM screenshot→reason→act loop autonomously. |
 | \`ground\` | When you need **exact pixel coords**: recover from a mis-tap, or feed coords to adb manually. |
 | \`ui_xml\` | When you need the **view hierarchy** (resource-id / bounds / clickable): debug or verify screen state. |
+| \`download_to_device\` | Task references a URL and the result must land on the device (image / video / pdf / apk). |
+| \`set_clipboard\` | Long / emoji-heavy text input — clipboard + GUI paste beats keystroke-by-keystroke entry. |
+| \`open_deeplink\` | Known deeplink URI — jump straight to the target screen and skip GUI navigation. |
+| \`find_app_package\` | Substring-lookup of installed package names (input for deeplink generation, \`monkey\`-launch, etc.). |
 
+${HEURISTICS_EN}
 ## Calling rules
 
 **\`mobile_use\`**

package/dist/orchestrator-system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-system-prompt.js","sourceRoot":"","sources":["../src/orchestrator-system-prompt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCV,CAAC;AAEF,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCV,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC"}
+{"version":3,"file":"orchestrator-system-prompt.js","sourceRoot":"","sources":["../src/orchestrator-system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCrB,CAAC;AAEF,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;EAiBT,aAAa;;;;;;;;;;;;;;;;;;;;;;;;CAwBd,CAAC;AAEF,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCrB,CAAC;AAEF,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;EAiBT,aAAa;;;;;;;;;;;;;;;;;;;;;;;;CAwBd,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC"}

package/dist/pi-context.d.ts

@@ -29,6 +29,7 @@
  */
 import type { IMcpRuntime } from "./mcp-client/runtime.js";
 import type { IGrounder } from "./grounding/grounder.js";
+import type { ShortcutInvoker, ShortcutResourceFacade } from "./shortcuts/index.js";
 export type { IGrounder };
 export interface PiExtensionContext {
     /**
@@ -58,6 +59,55 @@ export interface PiExtensionContext {
      * result through `formatUiXmlToolOutput`.
      */
     getUiXml(query?: string): Promise<string>;
+    /**
+     * The active shortcut invoker. The outer-LLM extension uses
+     * `getShortcutKB().registry.list()` to enumerate shortcuts (one
+     * descriptor → one outer-LLM tool) and `getShortcutKB().invoke(id, …)`
+     * to dispatch a call. Throws when no shortcut runtime is wired (e.g.
+     * tests that don't need the hybrid action space).
+     */
+    getShortcutKB(): ShortcutInvoker;
+    /**
+     * Optional resource facade for shortcut runtime callers (chiefly
+     * `download_to_device`). Implementations return `undefined` when
+     * the bootstrap layer has not wired a resolver — in that case the
+     * shortcut surfaces `permission_denied` to the LLM, which is the
+     * intended fail-soft behaviour.
+     *
+     * The .pi extension passes the result of this accessor into the
+     * `InvokeCallerContext.resources` field on every shortcut invoke,
+     * so all shortcut implementations see the *same* facade as the
+     * AgentHost auto-trigger and consequently share the same cache.
+     */
+    getShortcutResources?(): ShortcutResourceFacade | undefined;
+    /**
+     * INTERNAL-ONLY. Runs a shell command on the active device through
+     * the same MCP runtime `getMcpClient()` returns. Provided as a
+     * convenience for shortcut implementations that need a one-liner
+     * exec; calling it from a `pi.registerTool({ execute })` body is a
+     * code-review failure (see comment block above).
+     *
+     * Implementations MUST honor `abortSignal` and surface a structured
+     * `{ stdout, stderr, exitCode }` so callers can map exit codes to
+     * `ShortcutErrorCode` deterministically.
+     */
+    runShell(command: string, opts?: {
+        timeoutMs?: number;
+        abortSignal?: AbortSignal;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /**
+     * INTERNAL-ONLY. Push raw bytes to an absolute device-local path via
+     * the MCP runtime's `fileWrite`. Used by `download_to_device` (and
+     * any future shortcut that needs to materialise a file on the
+     * device) — never wrap this in an outer-LLM tool. Throws when the
+     * active runtime does not implement `fileWrite` (e.g. legacy
+     * in-process bridges).
+     */
+    pushFile(path: string, bytes: Buffer): Promise<void>;
 }
 /**
  * Install (or clear, when `ctx` is `null`) the context that

package/dist/pi-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"pi-context.js","sourceRoot":"","sources":["../src/pi-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA4CH,IAAI,MAAM,GAA8B,IAAI,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA8B;IAClE,MAAM,GAAG,GAAG,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,8FAA8F;YAC5F,6CAA6C,CAChD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"pi-context.js","sourceRoot":"","sources":["../src/pi-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+HH,IAAI,MAAM,GAA8B,IAAI,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA8B;IAClE,MAAM,GAAG,GAAG,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,8FAA8F;YAC5F,6CAA6C,CAChD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/ports/device.d.ts

@@ -50,4 +50,22 @@ export interface IDevice {
     install(path: string): Promise<void>;
     /** Run an arbitrary shell command and return stdout. */
     shell(command: string): Promise<string>;
+    /**
+     * Resolve a device-local well-known directory for a given content
+     * MIME type. Used by the Resource Resolution Layer to land
+     * downloaded URL payloads in a directory the device's gallery /
+     * file picker / installer naturally surfaces.
+     *
+     * Implementations:
+     *   - Android: `/sdcard/Pictures` (image/*), `/sdcard/Movies`
+     *     (video/*), `/sdcard/Music` (audio/*), `/sdcard/Download`
+     *     (application/*, text/*).
+     *   - Desktop: `~/Pictures`, `~/Movies`, `~/Music`, `~/Downloads`.
+     *     `application/vnd.android.package-archive` rejects with
+     *     `unsupported_platform` since desktop has no APK installer.
+     *
+     * The path returned is absolute, with no trailing slash. Callers
+     * append the filename themselves with `/`.
+     */
+    resolveWellKnownDir(mime: string): Promise<string>;
 }

package/dist/resources/augmenter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Task Context Augmenter — inject "Resources prepared" preamble into
+ * the original task without prescribing any GUI path.
+ *
+ * Output format (pinned by unit tests; do NOT change without updating
+ * `resource-augmented-prompt-contains-source-url-and-resource-identity`
+ * and the corresponding fixture):
+ *
+ *     Resources prepared:
+ *     - <remotePath> (<mime>, <humanSize>, mtime=now, source URL: <sourceUrl>)
+ *     - …
+ *
+ *     The original task references the resource(s) above by URL. The
+ *     resource(s) have been made available at the path(s) shown.
+ *
+ *     Resource usage rules (anti-pattern guard, app-agnostic):
+ *     - Do NOT search by filename or recognised content keyword. …
+ *     - The resource is at the top of any default-newest-first picker. …
+ *     - Do NOT recognise the resource visually then query its content. …
+ *
+ *     Original task: <verbatim original task>
+ *
+ * Design constraints derived from MAS-Bench / Mobile-Agent-V3.5 / Anthropic
+ * Computer Use prompt-engineering research:
+ *
+ *   - Identity-explicit: every line in `Resources prepared` MUST link
+ *     a source identifier (URL) to a device-local path. This is the
+ *     exact constraint that keeps the VLM from confusing two visually
+ *     identical resources.
+ *   - GUI-neutral (positive direction): NEVER suggest "tap the first
+ *     photo", "open the gallery", or any other concrete GUI step.
+ *     Resource preparation is an orthogonal concern from GUI execution;
+ *     coupling them collapses the layered design.
+ *   - GUI-neutral (negative direction allowed): we DO inject anti-pattern
+ *     guards — "do not search by filename", "do not recognise content
+ *     visually then search". These are NOT GUI steps (they tell the
+ *     model what *not* to do, regardless of which app it lands in),
+ *     and empirically the outer LLM ignores the equivalent rules in
+ *     system prompt because user-message priority dominates. Pinning
+ *     the guard alongside the resource line keeps it at task-priority.
+ *   - Preserve the original task verbatim: the VLM's reasoning is
+ *     calibrated against the user's exact wording. Re-paraphrasing
+ *     subtly biases the agent.
+ */
+import type { ResolvedAsset, TaskContextAugmenter } from "./types.js";
+export declare class ResourceContextAugmenter implements TaskContextAugmenter {
+    augment(originalTask: string, assets: readonly ResolvedAsset[]): string;
+}

package/dist/resources/augmenter.js

@@ -0,0 +1,126 @@
+/**
+ * Task Context Augmenter — inject "Resources prepared" preamble into
+ * the original task without prescribing any GUI path.
+ *
+ * Output format (pinned by unit tests; do NOT change without updating
+ * `resource-augmented-prompt-contains-source-url-and-resource-identity`
+ * and the corresponding fixture):
+ *
+ *     Resources prepared:
+ *     - <remotePath> (<mime>, <humanSize>, mtime=now, source URL: <sourceUrl>)
+ *     - …
+ *
+ *     The original task references the resource(s) above by URL. The
+ *     resource(s) have been made available at the path(s) shown.
+ *
+ *     Resource usage rules (anti-pattern guard, app-agnostic):
+ *     - Do NOT search by filename or recognised content keyword. …
+ *     - The resource is at the top of any default-newest-first picker. …
+ *     - Do NOT recognise the resource visually then query its content. …
+ *
+ *     Original task: <verbatim original task>
+ *
+ * Design constraints derived from MAS-Bench / Mobile-Agent-V3.5 / Anthropic
+ * Computer Use prompt-engineering research:
+ *
+ *   - Identity-explicit: every line in `Resources prepared` MUST link
+ *     a source identifier (URL) to a device-local path. This is the
+ *     exact constraint that keeps the VLM from confusing two visually
+ *     identical resources.
+ *   - GUI-neutral (positive direction): NEVER suggest "tap the first
+ *     photo", "open the gallery", or any other concrete GUI step.
+ *     Resource preparation is an orthogonal concern from GUI execution;
+ *     coupling them collapses the layered design.
+ *   - GUI-neutral (negative direction allowed): we DO inject anti-pattern
+ *     guards — "do not search by filename", "do not recognise content
+ *     visually then search". These are NOT GUI steps (they tell the
+ *     model what *not* to do, regardless of which app it lands in),
+ *     and empirically the outer LLM ignores the equivalent rules in
+ *     system prompt because user-message priority dominates. Pinning
+ *     the guard alongside the resource line keeps it at task-priority.
+ *   - Preserve the original task verbatim: the VLM's reasoning is
+ *     calibrated against the user's exact wording. Re-paraphrasing
+ *     subtly biases the agent.
+ */
+const HEADER = "Resources prepared:";
+const FOOTER = "The original task references the resource(s) above by URL. The resource(s) have been made available at the path(s) shown.";
+/**
+ * Anti-pattern guard injected next to the resource line so it inherits
+ * the task's priority (system-prompt-level rules get overridden by the
+ * user task at runtime; we observed this empirically with AutoGLM and
+ * other open-weights orchestrators).
+ *
+ * The guard is **app-agnostic** and **does not prescribe a GUI step**:
+ * it states facts about how the resource is identified, plus negative
+ * rules about which retrieval strategies will fail. The model is still
+ * free to choose the GUI path.
+ */
+const RESOURCE_USAGE_RULES = [
+    "Resource usage rules (these prepared resources, app-agnostic):",
+    "- The resource's identity is the PATH + source URL above, NOT its visual content. Do not recognise it visually (faces, objects, scenery) and then search by keyword.",
+    "- Each resource was written to the device just now (mtime=now) and the platform media index has been updated. In any media picker / gallery / file manager that uses the platform's default newest-first ordering, the resource is at the very top of the listing.",
+    "- Do NOT search inside a picker by the filename — it is machine-generated (`beeos_<ts>_<hash>.<ext>`) and will not match. Do NOT search by recognised content keywords either — picker search uses the platform's metadata index (faces / places / OCR), which the freshly-added resource is unlikely to have entries in yet.",
+    "- Do NOT browse feeds, timelines, profiles, or inboxes looking for this resource — it is not in anyone's content stream; you just placed it on the device.",
+].join("\n");
+export class ResourceContextAugmenter {
+    augment(originalTask, assets) {
+        if (!assets || assets.length === 0)
+            return originalTask;
+        const lines = [];
+        lines.push(HEADER);
+        for (const a of assets) {
+            const sizeStr = formatBytes(a.sizeBytes);
+            lines.push(`- ${a.remotePath} (${a.mime}, ${sizeStr}, mtime=now, ${formatSource(a)})`);
+        }
+        lines.push("");
+        lines.push(FOOTER);
+        lines.push("");
+        lines.push(RESOURCE_USAGE_RULES);
+        lines.push("");
+        lines.push(`Original task: ${originalTask}`);
+        return lines.join("\n");
+    }
+}
+/**
+ * Render the `source:` clause of a resource line.
+ *
+ * For pasted URL refs we keep the original wording (`source URL: <url>`)
+ * — the URL is the user's natural identifier and several existing test
+ * pins / heuristics anchor on this exact phrase.
+ *
+ * For uploaded files (`beeos-file://<fileId>`) the presigned download
+ * URL must NEVER reach the LLM context — it carries a SigV4 token that
+ * (a) leaks into logs, (b) is short-lived and meaningless to the model.
+ * We surface the opaque `beeos-file://<fileId>` identifier instead and
+ * tag it as `uploaded file` so the model understands it cannot be
+ * fetched again from a public URL.
+ */
+function formatSource(a) {
+    if (a.ref.kind === "beeos-file") {
+        return `source: uploaded file beeos-file://${a.ref.fileId}`;
+    }
+    const url = a.sourceUrl || (a.ref.kind === "url" ? a.ref.url : "");
+    return `source URL: ${url}`;
+}
+/**
+ * Format a byte count as a short human string (1024-based, two
+ * significant digits). Pinned in tests so the augmented preamble is
+ * stable across locales / Node versions.
+ */
+function formatBytes(bytes) {
+    if (!isFinite(bytes) || bytes < 0)
+        return "0B";
+    if (bytes < 1024)
+        return `${bytes}B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex++;
+    }
+    // Two significant digits, no trailing zero.
+    const formatted = value < 10 ? value.toFixed(1) : Math.round(value).toString();
+    return `${formatted}${units[unitIndex]}`;
+}
+//# sourceMappingURL=augmenter.js.map

package/dist/resources/augmenter.js.map

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

package/dist/resources/cache.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Resource Resolution Cache — keyed by SHA-256(url), value is a
+ * `ResolvedAsset`. Cache hits MUST validate the device-side file is
+ * still there before reuse.
+ *
+ * Why an in-memory cache and not skill memory?
+ *   - Skill memory is per-app GUI sequences (see ADR 001). Resolutions
+ *     are app-agnostic and have a much shorter natural lifetime
+ *     (TTL=7d) — different concern, different data shape.
+ *   - The cache lives for the AgentHost lifetime; we deliberately do
+ *     NOT persist it to disk for Phase 1. A future plan may add an FS
+ *     mirror under `~/.beeos/device-agent/resources-cache/` once the
+ *     access pattern stabilises.
+ *
+ * Cache validation:
+ *   When a hit is returned, the consumer is REQUIRED to call
+ *   `validateAlive(asset, mcp)` to confirm the device-side file still
+ *   exists (operators occasionally clear `/sdcard/Pictures/` between
+ *   tasks). On a missing file, the cache entry is invalidated and the
+ *   resolution is re-run.
+ */
+import type { IMcpRuntime } from "../mcp-client/runtime.js";
+import type { ResolvedAsset } from "./types.js";
+export interface ResourceCacheOptions {
+    /** Per-entry TTL in ms. Default 7 days. */
+    ttlMs?: number;
+    /** Soft cap on stored bytes (sum of `sizeBytes`). Default 500 MB. */
+    maxBytes?: number;
+}
+export declare class ResourceResolutionCache {
+    private readonly ttlMs;
+    private readonly maxBytes;
+    private readonly entries;
+    constructor(opts?: ResourceCacheOptions);
+    /** Stable cache key — SHA-256 of the URL. */
+    static keyForUrl(url: string): string;
+    get(key: string, now?: number): ResolvedAsset | undefined;
+    set(key: string, asset: ResolvedAsset, now?: number): void;
+    invalidate(key: string): void;
+    size(): number;
+    totalBytes(): number;
+    /** Test helper — visible-for-spec, not for production callers. */
+    __debug(): {
+        size: number;
+        totalBytes: number;
+    };
+    /**
+     * Verify the device-side file referenced by a cached entry is still
+     * present. Returns `true` iff `ls <remotePath>` succeeds with non-
+     * empty output (or an explicit success exit code).
+     *
+     * MUST be called by every consumer that hits the cache before
+     * returning the asset to upstream code.
+     */
+    static validateAlive(asset: ResolvedAsset, mcp: IMcpRuntime): Promise<boolean>;
+    private evictIfNeeded;
+}