agent-device 0.12.4 → 0.12.6

package/dist/src/818.js

@@ -1 +1 @@
-import{constants as e}from"node:fs";import{access as t,stat as r}from"node:fs/promises";import n from"node:path";import{spawn as o,spawnSync as i}from"node:child_process";let s=/(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key)/i,a=/(bearer\s+[a-z0-9._-]+|(?:api[_-]?key|token|secret|password)\s*[=:]\s*\S+)/i;function u(e){return function e(t,r,n){if(null==t)return t;if("string"==typeof t){var o=t,i=n;let e=o.trim();if(!e)return o;if(i&&s.test(i)||a.test(e))return"[REDACTED]";let r=function(e){try{let t=new URL(e);return t.search&&(t.search="?REDACTED"),(t.username||t.password)&&(t.username="REDACTED",t.password="REDACTED"),t.toString()}catch{return null}}(e);return r||(e.length>400?`${e.slice(0,200)}...<truncated>`:e)}if("object"!=typeof t)return t;if(r.has(t))return"[Circular]";if(r.add(t),Array.isArray(t))return t.map(t=>e(t,r));let u={};for(let[n,o]of Object.entries(t)){if(s.test(n)){u[n]="[REDACTED]";continue}u[n]=e(o,r,n)}return u}(e,new WeakSet)}class d extends Error{code;details;cause;constructor(e,t,r,n){super(t),this.code=e,this.details=r,this.cause=n}}function l(e){return e instanceof d?e:e instanceof Error?new d("UNKNOWN",e.message,void 0,e):new d("UNKNOWN","Unknown error",{err:e})}function c(e,t={}){let r=l(e),n=r.details?u(r.details):void 0,o=n&&"string"==typeof n.hint?n.hint:void 0,i=(n&&"string"==typeof n.diagnosticId?n.diagnosticId:void 0)??t.diagnosticId,s=(n&&"string"==typeof n.logPath?n.logPath:void 0)??t.logPath,a=o??function(e){switch(e){case"INVALID_ARGS":return"Check command arguments and run --help for usage examples.";case"SESSION_NOT_FOUND":return"Run open first or pass an explicit device selector.";case"TOOL_MISSING":return"Install required platform tooling and ensure it is available in PATH.";case"DEVICE_NOT_FOUND":return"Verify the target device is booted/connected and selectors match.";case"APP_NOT_INSTALLED":return"Run apps to discover the exact installed package or bundle id, or install the app before open.";case"UNSUPPORTED_OPERATION":return"This command is not available for the selected platform/device.";case"COMMAND_FAILED":default:return"Retry with --debug and inspect diagnostics log for details.";case"UNAUTHORIZED":return"Refresh daemon metadata and retry the command."}}(r.code),d=function(e){if(!e)return;let t={...e};return delete t.hint,delete t.diagnosticId,delete t.logPath,Object.keys(t).length>0?t:void 0}(n),f=function(e,t,r){if("COMMAND_FAILED"!==e||r?.processExitError!==!0)return t;let n=function(e){let t=[/^an error was encountered processing the command/i,/^underlying error\b/i,/^simulator device failed to complete the requested operation/i];for(let r of e.split("\n")){let e=r.trim();if(e&&!t.some(t=>t.test(e)))return e.length>200?`${e.slice(0,200)}...`:e}return null}("string"==typeof r?.stderr?r.stderr:"");return n||t}(r.code,r.message,n);return{code:r.code,message:f,hint:a,diagnosticId:i,logPath:s,details:d}}let f=/^[A-Za-z0-9][A-Za-z0-9._+-]*$/,p=[".com",".exe",".bat",".cmd"];async function m(e,t,r={}){let n=D(e);return new Promise((i,s)=>{let a=o(n,t,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"],detached:r.detached,shell:!1}),u="",l=r.binaryStdout?Buffer.alloc(0):void 0,c="",f=!1,p=T(r.timeoutMs),m=p?setTimeout(()=>{f=!0,a.kill("SIGKILL")},p):null;r.binaryStdout||a.stdout.setEncoding("utf8"),a.stderr.setEncoding("utf8"),void 0!==r.stdin&&a.stdin.write(r.stdin),a.stdin.end(),a.stdout.on("data",e=>{r.binaryStdout?l=Buffer.concat([l??Buffer.alloc(0),Buffer.isBuffer(e)?e:Buffer.from(e)]):u+=e}),a.stderr.on("data",e=>{c+=e}),a.on("error",r=>{(m&&clearTimeout(m),"ENOENT"===r.code)?s(new d("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},r)):s(new d("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},r))}),a.on("close",o=>{m&&clearTimeout(m);let a=o??1;f&&p?s(new d("COMMAND_FAILED",`${n} timed out after ${p}ms`,{cmd:e,args:t,stdout:u,stderr:c,exitCode:a,timeoutMs:p})):0===a||r.allowFailure?i({stdout:u,stderr:c,exitCode:a,stdoutBuffer:l}):s(new d("COMMAND_FAILED",`${n} exited with code ${a}`,{cmd:e,args:t,stdout:u,stderr:c,exitCode:a,processExitError:!0}))})})}async function h(e){let t=S(e);if(!t)return!1;if(n.isAbsolute(t))return y(t);let r=process.env.PATH;if(!r)return!1;let o=function(){if("win32"!==process.platform)return[""];let e=process.env.PATHEXT;if(!e)return p;let t=e.split(";").map(e=>e.trim().toLowerCase()).filter(e=>e.length>0);return t.length>0?t:p}();for(let e of r.split(n.delimiter)){let r=e.trim();if(r){for(let e of function(e,t){if("win32"!==process.platform)return[e];let r=e.toLowerCase();return t.some(e=>r.endsWith(e))?[e]:t.map(t=>`${e}${t}`)}(t,o))if(await y(n.join(r,e)))return!0}}return!1}async function w(e,t){let r=I(e,t,"executable");if(r){if(!await y(r))throw new d("TOOL_MISSING",`${t} points to a missing or non-executable file: ${r}`,{envName:t,path:r});return r}}async function E(e,t){let r=I(e,t,"file");if(r){if(!await M(r))throw new d("TOOL_MISSING",`${t} points to a missing or non-file path: ${r}`,{envName:t,path:r});return r}}function A(e,t,r={}){let n=D(e),o=i(n,t,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"],encoding:r.binaryStdout?void 0:"utf8",input:r.stdin,timeout:T(r.timeoutMs),shell:!1});if(o.error){let i=o.error.code;if("ETIMEDOUT"===i)throw new d("COMMAND_FAILED",`${n} timed out after ${T(r.timeoutMs)}ms`,{cmd:e,args:t,timeoutMs:T(r.timeoutMs)},o.error);if("ENOENT"===i)throw new d("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},o.error);throw new d("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},o.error)}let s=r.binaryStdout?Buffer.isBuffer(o.stdout)?o.stdout:Buffer.from(o.stdout??""):void 0,a=r.binaryStdout?"":"string"==typeof o.stdout?o.stdout:(o.stdout??"").toString(),u="string"==typeof o.stderr?o.stderr:(o.stderr??"").toString(),l=o.status??1;if(0!==l&&!r.allowFailure)throw new d("COMMAND_FAILED",`${n} exited with code ${l}`,{cmd:e,args:t,stdout:a,stderr:u,exitCode:l,processExitError:!0});return{stdout:a,stderr:u,exitCode:l,stdoutBuffer:s}}function g(e,t,r={}){let n=o(D(e),t,{cwd:r.cwd,env:r.env,stdio:r.stdio??"ignore",detached:!0,shell:!1});return n.unref(),n.pid??0}async function O(e,t,r={}){let n=D(e);return new Promise((i,s)=>{let a=o(n,t,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"],detached:r.detached,shell:!1});r.onSpawn?.(a);let u="",l="",c=r.binaryStdout?Buffer.alloc(0):void 0,f=!1,p=T(r.timeoutMs),m=p?setTimeout(()=>{f=!0,a.kill("SIGKILL")},p):null;r.binaryStdout||a.stdout.setEncoding("utf8"),a.stderr.setEncoding("utf8"),void 0!==r.stdin&&a.stdin.write(r.stdin),a.stdin.end(),a.stdout.on("data",e=>{if(r.binaryStdout){c=Buffer.concat([c??Buffer.alloc(0),Buffer.isBuffer(e)?e:Buffer.from(e)]);return}let t=String(e);u+=t,r.onStdoutChunk?.(t)}),a.stderr.on("data",e=>{let t=String(e);l+=t,r.onStderrChunk?.(t)}),a.on("error",r=>{(m&&clearTimeout(m),"ENOENT"===r.code)?s(new d("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},r)):s(new d("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},r))}),a.on("close",o=>{m&&clearTimeout(m);let a=o??1;f&&p?s(new d("COMMAND_FAILED",`${n} timed out after ${p}ms`,{cmd:e,args:t,stdout:u,stderr:l,exitCode:a,timeoutMs:p})):0===a||r.allowFailure?i({stdout:u,stderr:l,exitCode:a,stdoutBuffer:c}):s(new d("COMMAND_FAILED",`${n} exited with code ${a}`,{cmd:e,args:t,stdout:u,stderr:l,exitCode:a,processExitError:!0}))})})}function N(e,t,r={}){let n=D(e),i=o(n,t,{cwd:r.cwd,env:r.env,stdio:["ignore","pipe","pipe"],detached:r.detached,shell:!1}),s="",a="";i.stdout.setEncoding("utf8"),i.stderr.setEncoding("utf8"),i.stdout.on("data",e=>{s+=e}),i.stderr.on("data",e=>{a+=e});let u=new Promise((o,u)=>{i.on("error",r=>{"ENOENT"===r.code?u(new d("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},r)):u(new d("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},r))}),i.on("close",i=>{let l=i??1;0===l||r.allowFailure?o({stdout:s,stderr:a,exitCode:l}):u(new d("COMMAND_FAILED",`${n} exited with code ${l}`,{cmd:e,args:t,stdout:s,stderr:a,exitCode:l,processExitError:!0}))})});return{child:i,wait:u}}function D(e){let t=S(e);if(!t)throw new d("INVALID_ARGS",`Invalid executable command: ${JSON.stringify(e)}`,{cmd:e,hint:"Use a bare command name from PATH or an absolute executable path."});return t}function I(e,t,r){let o=e?.trim();if(o){if(!n.isAbsolute(o)||o.includes("\0"))throw new d("INVALID_ARGS",`${t} must be an absolute ${r} path, not ${JSON.stringify(e)}`,{envName:t,path:e});return o}}function S(e){let t=e.trim();return!t||t.includes("\0")?null:n.isAbsolute(t)?t:t.includes("/")||t.includes("\\")?null:f.test(t)?t:null}async function y(r){try{if(!await M(r))return!1;return await t(r,"win32"===process.platform?e.F_OK:e.X_OK),!0}catch{return!1}}async function M(e){try{return(await r(e)).isFile()}catch{return!1}}function T(e){if(!Number.isFinite(e))return;let t=Math.floor(e);if(!(t<=0))return t}export{d as AppError,l as asAppError,y as isExecutablePath,c as normalizeError,u as redactDiagnosticData,w as resolveExecutableOverridePath,E as resolveFileOverridePath,m as runCmd,N as runCmdBackground,g as runCmdDetached,O as runCmdStreaming,A as runCmdSync,h as whichCmd};
+import{constants as e}from"node:fs";import{access as t,stat as r}from"node:fs/promises";import n from"node:path";import{spawn as o,spawnSync as i}from"node:child_process";let s=/(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key)/i,a=/(bearer\s+[a-z0-9._-]+|(?:api[_-]?key|token|secret|password)\s*[=:]\s*\S+)/i;function d(e){return function e(t,r,n){if(null==t)return t;if("string"==typeof t){var o=t,i=n;let e=o.trim();if(!e)return o;if(i&&s.test(i)||a.test(e))return"[REDACTED]";let r=function(e){try{let t=new URL(e);return t.search&&(t.search="?REDACTED"),(t.username||t.password)&&(t.username="REDACTED",t.password="REDACTED"),t.toString()}catch{return null}}(e);return r||(e.length>400?`${e.slice(0,200)}...<truncated>`:e)}if("object"!=typeof t)return t;if(r.has(t))return"[Circular]";if(r.add(t),Array.isArray(t))return t.map(t=>e(t,r));let d={};for(let[n,o]of Object.entries(t)){if(s.test(n)){d[n]="[REDACTED]";continue}d[n]=e(o,r,n)}return d}(e,new WeakSet)}class u extends Error{code;details;cause;constructor(e,t,r,n){super(t),this.code=e,this.details=r,this.cause=n}}function l(e){return e instanceof u?e:e instanceof Error?new u("UNKNOWN",e.message,void 0,e):new u("UNKNOWN","Unknown error",{err:e})}function c(e,t={}){let r=l(e),n=r.details?d(r.details):void 0,o=n&&"string"==typeof n.hint?n.hint:void 0,i=(n&&"string"==typeof n.diagnosticId?n.diagnosticId:void 0)??t.diagnosticId,s=(n&&"string"==typeof n.logPath?n.logPath:void 0)??t.logPath,a=o??function(e){switch(e){case"INVALID_ARGS":return"Check command arguments and run --help for usage examples.";case"SESSION_NOT_FOUND":return"Run open first or pass an explicit device selector.";case"TOOL_MISSING":return"Install required platform tooling and ensure it is available in PATH.";case"DEVICE_NOT_FOUND":return"Verify the target device is booted/connected and selectors match.";case"APP_NOT_INSTALLED":return"Run apps to discover the exact installed package or bundle id, or install the app before open.";case"UNSUPPORTED_OPERATION":return"This command is not available for the selected platform/device.";case"NOT_IMPLEMENTED":return"This command is part of the planned API but is not implemented yet.";case"COMMAND_FAILED":default:return"Retry with --debug and inspect diagnostics log for details.";case"UNAUTHORIZED":return"Refresh daemon metadata and retry the command."}}(r.code),u=function(e){if(!e)return;let t={...e};return delete t.hint,delete t.diagnosticId,delete t.logPath,Object.keys(t).length>0?t:void 0}(n),f=function(e,t,r){if("COMMAND_FAILED"!==e||r?.processExitError!==!0)return t;let n=function(e){let t=[/^an error was encountered processing the command/i,/^underlying error\b/i,/^simulator device failed to complete the requested operation/i];for(let r of e.split("\n")){let e=r.trim();if(e&&!t.some(t=>t.test(e)))return e.length>200?`${e.slice(0,200)}...`:e}return null}("string"==typeof r?.stderr?r.stderr:"");return n||t}(r.code,r.message,n);return{code:r.code,message:f,hint:a,diagnosticId:i,logPath:s,details:u}}let f=/^[A-Za-z0-9][A-Za-z0-9._+-]*$/,p=[".com",".exe",".bat",".cmd"];async function m(e,t,r={}){let n=I(e);return new Promise((i,s)=>{let a=o(n,t,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"],detached:r.detached,shell:!1}),d="",l=r.binaryStdout?Buffer.alloc(0):void 0,c="",f=!1,p=y(r.timeoutMs),m=p?setTimeout(()=>{f=!0,a.kill("SIGKILL")},p):null;r.binaryStdout||a.stdout.setEncoding("utf8"),a.stderr.setEncoding("utf8"),void 0!==r.stdin&&a.stdin.write(r.stdin),a.stdin.end(),a.stdout.on("data",e=>{r.binaryStdout?l=Buffer.concat([l??Buffer.alloc(0),Buffer.isBuffer(e)?e:Buffer.from(e)]):d+=e}),a.stderr.on("data",e=>{c+=e}),a.on("error",r=>{(m&&clearTimeout(m),"ENOENT"===r.code)?s(new u("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},r)):s(new u("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},r))}),a.on("close",o=>{m&&clearTimeout(m);let a=o??1;f&&p?s(new u("COMMAND_FAILED",`${n} timed out after ${p}ms`,{cmd:e,args:t,stdout:d,stderr:c,exitCode:a,timeoutMs:p})):0===a||r.allowFailure?i({stdout:d,stderr:c,exitCode:a,stdoutBuffer:l}):s(new u("COMMAND_FAILED",`${n} exited with code ${a}`,{cmd:e,args:t,stdout:d,stderr:c,exitCode:a,processExitError:!0}))})})}async function h(e){let t=S(e);if(!t)return!1;if(n.isAbsolute(t))return T(t);let r=process.env.PATH;if(!r)return!1;let o=function(){if("win32"!==process.platform)return[""];let e=process.env.PATHEXT;if(!e)return p;let t=e.split(";").map(e=>e.trim().toLowerCase()).filter(e=>e.length>0);return t.length>0?t:p}();for(let e of r.split(n.delimiter)){let r=e.trim();if(r){for(let e of function(e,t){if("win32"!==process.platform)return[e];let r=e.toLowerCase();return t.some(e=>r.endsWith(e))?[e]:t.map(t=>`${e}${t}`)}(t,o))if(await T(n.join(r,e)))return!0}}return!1}async function w(e,t){let r=D(e,t,"executable");if(r){if(!await T(r))throw new u("TOOL_MISSING",`${t} points to a missing or non-executable file: ${r}`,{envName:t,path:r});return r}}async function E(e,t){let r=D(e,t,"file");if(r){if(!await M(r))throw new u("TOOL_MISSING",`${t} points to a missing or non-file path: ${r}`,{envName:t,path:r});return r}}function A(e,t,r={}){let n=I(e),o=i(n,t,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"],encoding:r.binaryStdout?void 0:"utf8",input:r.stdin,timeout:y(r.timeoutMs),shell:!1});if(o.error){let i=o.error.code;if("ETIMEDOUT"===i)throw new u("COMMAND_FAILED",`${n} timed out after ${y(r.timeoutMs)}ms`,{cmd:e,args:t,timeoutMs:y(r.timeoutMs)},o.error);if("ENOENT"===i)throw new u("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},o.error);throw new u("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},o.error)}let s=r.binaryStdout?Buffer.isBuffer(o.stdout)?o.stdout:Buffer.from(o.stdout??""):void 0,a=r.binaryStdout?"":"string"==typeof o.stdout?o.stdout:(o.stdout??"").toString(),d="string"==typeof o.stderr?o.stderr:(o.stderr??"").toString(),l=o.status??1;if(0!==l&&!r.allowFailure)throw new u("COMMAND_FAILED",`${n} exited with code ${l}`,{cmd:e,args:t,stdout:a,stderr:d,exitCode:l,processExitError:!0});return{stdout:a,stderr:d,exitCode:l,stdoutBuffer:s}}function g(e,t,r={}){let n=o(I(e),t,{cwd:r.cwd,env:r.env,stdio:r.stdio??"ignore",detached:!0,shell:!1});return n.unref(),n.pid??0}async function O(e,t,r={}){let n=I(e);return new Promise((i,s)=>{let a=o(n,t,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"],detached:r.detached,shell:!1});r.onSpawn?.(a);let d="",l="",c=r.binaryStdout?Buffer.alloc(0):void 0,f=!1,p=y(r.timeoutMs),m=p?setTimeout(()=>{f=!0,a.kill("SIGKILL")},p):null;r.binaryStdout||a.stdout.setEncoding("utf8"),a.stderr.setEncoding("utf8"),void 0!==r.stdin&&a.stdin.write(r.stdin),a.stdin.end(),a.stdout.on("data",e=>{if(r.binaryStdout){c=Buffer.concat([c??Buffer.alloc(0),Buffer.isBuffer(e)?e:Buffer.from(e)]);return}let t=String(e);d+=t,r.onStdoutChunk?.(t)}),a.stderr.on("data",e=>{let t=String(e);l+=t,r.onStderrChunk?.(t)}),a.on("error",r=>{(m&&clearTimeout(m),"ENOENT"===r.code)?s(new u("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},r)):s(new u("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},r))}),a.on("close",o=>{m&&clearTimeout(m);let a=o??1;f&&p?s(new u("COMMAND_FAILED",`${n} timed out after ${p}ms`,{cmd:e,args:t,stdout:d,stderr:l,exitCode:a,timeoutMs:p})):0===a||r.allowFailure?i({stdout:d,stderr:l,exitCode:a,stdoutBuffer:c}):s(new u("COMMAND_FAILED",`${n} exited with code ${a}`,{cmd:e,args:t,stdout:d,stderr:l,exitCode:a,processExitError:!0}))})})}function N(e,t,r={}){let n=I(e),i=o(n,t,{cwd:r.cwd,env:r.env,stdio:["ignore","pipe","pipe"],detached:r.detached,shell:!1}),s="",a="";i.stdout.setEncoding("utf8"),i.stderr.setEncoding("utf8"),i.stdout.on("data",e=>{s+=e}),i.stderr.on("data",e=>{a+=e});let d=new Promise((o,d)=>{i.on("error",r=>{"ENOENT"===r.code?d(new u("TOOL_MISSING",`${n} not found in PATH`,{cmd:e},r)):d(new u("COMMAND_FAILED",`Failed to run ${n}`,{cmd:e,args:t},r))}),i.on("close",i=>{let l=i??1;0===l||r.allowFailure?o({stdout:s,stderr:a,exitCode:l}):d(new u("COMMAND_FAILED",`${n} exited with code ${l}`,{cmd:e,args:t,stdout:s,stderr:a,exitCode:l,processExitError:!0}))})});return{child:i,wait:d}}function I(e){let t=S(e);if(!t)throw new u("INVALID_ARGS",`Invalid executable command: ${JSON.stringify(e)}`,{cmd:e,hint:"Use a bare command name from PATH or an absolute executable path."});return t}function D(e,t,r){let o=e?.trim();if(o){if(!n.isAbsolute(o)||o.includes("\0"))throw new u("INVALID_ARGS",`${t} must be an absolute ${r} path, not ${JSON.stringify(e)}`,{envName:t,path:e});return o}}function S(e){let t=e.trim();return!t||t.includes("\0")?null:n.isAbsolute(t)?t:t.includes("/")||t.includes("\\")?null:f.test(t)?t:null}async function T(r){try{if(!await M(r))return!1;return await t(r,"win32"===process.platform?e.F_OK:e.X_OK),!0}catch{return!1}}async function M(e){try{return(await r(e)).isFile()}catch{return!1}}function y(e){if(!Number.isFinite(e))return;let t=Math.floor(e);if(!(t<=0))return t}export{u as AppError,l as asAppError,T as isExecutablePath,c as normalizeError,d as redactDiagnosticData,w as resolveExecutableOverridePath,E as resolveFileOverridePath,m as runCmd,N as runCmdBackground,g as runCmdDetached,O as runCmdStreaming,A as runCmdSync,h as whichCmd};

package/dist/src/backend.d.ts

@@ -0,0 +1,527 @@
+export declare type AgentDeviceBackend = {
+    platform: AgentDeviceBackendPlatform;
+    capabilities?: BackendCapabilitySet;
+    escapeHatches?: BackendEscapeHatches;
+    captureSnapshot?(context: BackendCommandContext, options?: BackendSnapshotOptions): Promise<BackendSnapshotResult>;
+    captureScreenshot?(context: BackendCommandContext, outPath: string, options?: BackendScreenshotOptions): Promise<BackendScreenshotResult | void>;
+    readText?(context: BackendCommandContext, node: SnapshotNode): Promise<BackendReadTextResult>;
+    findText?(context: BackendCommandContext, text: string): Promise<BackendFindTextResult>;
+    tap?(context: BackendCommandContext, point: Point, options?: BackendTapOptions): Promise<BackendActionResult>;
+    fill?(context: BackendCommandContext, point: Point, text: string, options?: BackendFillOptions): Promise<BackendActionResult>;
+    typeText?(context: BackendCommandContext, text: string, options?: {
+        delayMs?: number;
+    }): Promise<BackendActionResult>;
+    focus?(context: BackendCommandContext, point: Point): Promise<BackendActionResult>;
+    longPress?(context: BackendCommandContext, point: Point, options?: BackendLongPressOptions): Promise<BackendActionResult>;
+    swipe?(context: BackendCommandContext, from: Point, to: Point, options?: BackendSwipeOptions): Promise<BackendActionResult>;
+    scroll?(context: BackendCommandContext, target: BackendScrollTarget, options: BackendScrollOptions): Promise<BackendActionResult>;
+    pinch?(context: BackendCommandContext, options: BackendPinchOptions): Promise<BackendActionResult>;
+    pressKey?(context: BackendCommandContext, key: string, options?: {
+        modifiers?: string[];
+    }): Promise<BackendActionResult>;
+    pressBack?(context: BackendCommandContext, options?: BackendBackOptions): Promise<BackendActionResult>;
+    pressHome?(context: BackendCommandContext): Promise<BackendActionResult>;
+    rotate?(context: BackendCommandContext, orientation: BackendDeviceOrientation): Promise<BackendActionResult>;
+    setKeyboard?(context: BackendCommandContext, options: BackendKeyboardOptions): Promise<BackendKeyboardResult | BackendActionResult>;
+    getClipboard?(context: BackendCommandContext): Promise<string | BackendClipboardTextResult>;
+    setClipboard?(context: BackendCommandContext, text: string): Promise<BackendActionResult>;
+    openSettings?(context: BackendCommandContext, target?: string): Promise<BackendActionResult>;
+    handleAlert?(context: BackendCommandContext, action: BackendAlertAction, options?: {
+        timeoutMs?: number;
+    }): Promise<BackendAlertResult>;
+    openAppSwitcher?(context: BackendCommandContext): Promise<BackendActionResult>;
+    openApp?(context: BackendCommandContext, target: BackendOpenTarget, options?: BackendOpenOptions): Promise<BackendActionResult>;
+    closeApp?(context: BackendCommandContext, app?: string): Promise<BackendActionResult>;
+    listApps?(context: BackendCommandContext, filter?: BackendAppListFilter): Promise<readonly BackendAppInfo[]>;
+    getAppState?(context: BackendCommandContext, app: string): Promise<BackendAppState>;
+    pushFile?(context: BackendCommandContext, input: BackendPushInput, target: string): Promise<BackendActionResult>;
+    triggerAppEvent?(context: BackendCommandContext, event: BackendAppEvent): Promise<BackendActionResult>;
+    listDevices?(context: BackendCommandContext, filter?: BackendDeviceFilter): Promise<readonly BackendDeviceInfo[]>;
+    bootDevice?(context: BackendCommandContext, target?: BackendDeviceTarget): Promise<BackendActionResult>;
+    ensureSimulator?(context: BackendCommandContext, options: BackendEnsureSimulatorOptions): Promise<BackendEnsureSimulatorResult>;
+    resolveInstallSource?(context: BackendCommandContext, source: BackendInstallSource): Promise<BackendInstallSource>;
+    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendInstallResult>;
+    reinstallApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendInstallResult>;
+    startRecording?(context: BackendCommandContext, options?: BackendRecordingOptions): Promise<BackendRecordingResult>;
+    stopRecording?(context: BackendCommandContext, options?: BackendRecordingOptions): Promise<BackendRecordingResult>;
+    startTrace?(context: BackendCommandContext, options?: BackendTraceOptions): Promise<BackendTraceResult>;
+    stopTrace?(context: BackendCommandContext, options?: BackendTraceOptions): Promise<BackendTraceResult>;
+    readLogs?(context: BackendCommandContext, options?: BackendReadLogsOptions): Promise<BackendReadLogsResult>;
+    dumpNetwork?(context: BackendCommandContext, options?: BackendDumpNetworkOptions): Promise<BackendDumpNetworkResult>;
+    measurePerf?(context: BackendCommandContext, options?: BackendMeasurePerfOptions): Promise<BackendMeasurePerfResult>;
+};
+
+export declare type AgentDeviceBackendPlatform = 'ios' | 'android' | 'macos' | 'linux';
+
+export declare const BACKEND_CAPABILITY_ESCAPE_HATCH_METHODS: {
+    readonly 'android.shell': "androidShell";
+    readonly 'ios.runnerCommand': "iosRunnerCommand";
+    readonly 'macos.desktopScreenshot': "macosDesktopScreenshot";
+};
+
+export declare const BACKEND_CAPABILITY_NAMES: readonly ["android.shell", "ios.runnerCommand", "macos.desktopScreenshot"];
+
+export declare type BackendActionResult = Record<string, unknown> | void;
+
+export declare type BackendAlertAction = 'get' | 'accept' | 'dismiss' | 'wait';
+
+export declare type BackendAlertInfo = {
+    title?: string;
+    message?: string;
+    buttons?: string[];
+};
+
+export declare type BackendAlertResult = {
+    kind: 'alertStatus';
+    alert: BackendAlertInfo | null;
+} | {
+    kind: 'alertHandled';
+    handled: boolean;
+    alert?: BackendAlertInfo;
+    button?: string;
+} | {
+    kind: 'alertWait';
+    alert: BackendAlertInfo | null;
+    waitedMs?: number;
+    timedOut?: boolean;
+};
+
+export declare type BackendAppEvent = {
+    name: string;
+    payload?: Record<string, unknown>;
+};
+
+export declare type BackendAppInfo = {
+    id: string;
+    name?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+};
+
+export declare type BackendAppListFilter = 'all' | 'user-installed';
+
+export declare type BackendAppState = {
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+    state?: 'unknown' | 'notRunning' | 'running' | 'foreground' | 'background';
+    details?: Record<string, unknown>;
+};
+
+export declare type BackendBackOptions = {
+    mode?: 'in-app' | 'system';
+};
+
+export declare type BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
+
+export declare type BackendCapabilitySet = readonly BackendCapabilityName[];
+
+export declare type BackendClipboardTextResult = {
+    text: string;
+};
+
+export declare type BackendCommandContext = {
+    session?: string;
+    requestId?: string;
+    appId?: string;
+    appBundleId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendDeviceFilter = {
+    platform?: AgentDeviceBackendPlatform | 'apple';
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+};
+
+export declare type BackendDeviceInfo = {
+    id: string;
+    name: string;
+    platform: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+    booted?: boolean;
+    details?: Record<string, unknown>;
+};
+
+export declare type BackendDeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+
+export declare type BackendDeviceTarget = {
+    id?: string;
+    name?: string;
+    platform?: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    headless?: boolean;
+};
+
+export declare type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
+    cursor?: string;
+    limit?: number;
+};
+
+export declare type BackendDiagnosticsTimeWindow = {
+    since?: string;
+    until?: string;
+};
+
+export declare type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
+    include?: BackendNetworkIncludeMode;
+};
+
+export declare type BackendDumpNetworkResult = {
+    entries: readonly BackendNetworkEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+export declare type BackendEnsureSimulatorOptions = {
+    device: string;
+    runtime?: string;
+    boot?: boolean;
+    reuseExisting?: boolean;
+};
+
+export declare type BackendEnsureSimulatorResult = {
+    udid: string;
+    device: string;
+    runtime: string;
+    created: boolean;
+    booted: boolean;
+    simulatorSetPath?: string | null;
+};
+
+export declare type BackendEscapeHatches = {
+    androidShell?(context: BackendCommandContext, args: readonly string[]): Promise<BackendShellResult>;
+    iosRunnerCommand?(context: BackendCommandContext, command: BackendRunnerCommand): Promise<BackendActionResult>;
+    macosDesktopScreenshot?(context: BackendCommandContext, outPath: string, options?: BackendScreenshotOptions): Promise<BackendScreenshotResult | void>;
+};
+
+export declare type BackendFillOptions = {
+    delayMs?: number;
+};
+
+export declare type BackendFindTextResult = {
+    found: boolean;
+};
+
+export declare type BackendInstallResult = Record<string, unknown> & {
+    appId?: string;
+    appName?: string;
+    bundleId?: string;
+    packageName?: string;
+    launchTarget?: string;
+    installablePath?: string;
+    archivePath?: string;
+};
+
+export declare type BackendInstallSource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+} | {
+    kind: 'url';
+    url: string;
+};
+
+export declare type BackendInstallTarget = {
+    app?: string;
+    source: BackendInstallSource;
+};
+
+export declare type BackendKeyboardOptions = {
+    action: 'status' | 'get' | 'dismiss';
+};
+
+export declare type BackendKeyboardResult = {
+    platform?: 'android' | 'ios' | 'macos' | 'linux';
+    action?: BackendKeyboardOptions['action'];
+    visible?: boolean;
+    inputType?: string | null;
+    type?: string | null;
+    wasVisible?: boolean;
+    dismissed?: boolean;
+    attempts?: number;
+};
+
+export declare type BackendLogEntry = {
+    timestamp?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error' | string;
+    message: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendLongPressOptions = {
+    durationMs?: number;
+};
+
+export declare type BackendMeasurePerfOptions = BackendDiagnosticsTimeWindow & {
+    sampleMs?: number;
+    metrics?: readonly string[];
+};
+
+export declare type BackendMeasurePerfResult = {
+    metrics: readonly BackendPerfMetric[];
+    startedAt?: string;
+    endedAt?: string;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+export declare type BackendNetworkEntry = {
+    timestamp?: string;
+    method?: string;
+    url?: string;
+    status?: number;
+    durationMs?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: string;
+    responseBody?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendNetworkIncludeMode = 'summary' | 'headers' | 'body' | 'all';
+
+export declare type BackendOpenOptions = {
+    relaunch?: boolean;
+};
+
+export declare type BackendOpenTarget = {
+    /**
+     * Generic app identifier accepted by the backend. Hosted adapters should
+     * prefer structured appId, bundleId, or packageName when available.
+     */
+    app?: string;
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    /**
+     * URL may be used by itself for a deep link or with an app identifier when
+     * the backend supports opening a URL in a specific app context.
+     */
+    url?: string;
+    /**
+     * Platform-specific activity override, primarily for Android app launches.
+     */
+    activity?: string;
+};
+
+export declare type BackendPerfMetric = {
+    name: string;
+    value?: number;
+    unit?: string;
+    status?: 'ok' | 'unavailable' | 'error';
+    message?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendPinchOptions = {
+    scale: number;
+    center?: Point;
+};
+
+export declare type BackendPushInput = {
+    kind: 'json';
+    payload: Record<string, unknown>;
+} | {
+    kind: 'file';
+    path: string;
+};
+
+export declare type BackendReadLogsOptions = BackendDiagnosticsPageOptions & {
+    levels?: readonly string[];
+    search?: string;
+    source?: string;
+};
+
+export declare type BackendReadLogsResult = {
+    entries: readonly BackendLogEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+export declare type BackendReadTextResult = {
+    text: string;
+};
+
+export declare type BackendRecordingOptions = {
+    outPath?: string;
+    fps?: number;
+    quality?: number;
+    showTouches?: boolean;
+};
+
+export declare type BackendRecordingResult = Record<string, unknown> & {
+    path?: string;
+    telemetryPath?: string;
+    warning?: string;
+};
+
+export declare type BackendRunnerCommand = {
+    command: string;
+    args?: readonly string[];
+    payload?: Record<string, unknown>;
+};
+
+export declare type BackendScreenshotOptions = {
+    fullscreen?: boolean;
+    overlayRefs?: boolean;
+    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+};
+
+export declare type BackendScreenshotResult = {
+    path?: string;
+    overlayRefs?: ScreenshotOverlayRef[];
+};
+
+export declare type BackendScrollOptions = {
+    direction: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+    pixels?: number;
+};
+
+export declare type BackendScrollTarget = {
+    kind: 'viewport';
+} | {
+    kind: 'point';
+    point: Point;
+};
+
+export declare type BackendShellResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+
+export declare type BackendSnapshotAnalysis = {
+    rawNodeCount?: number;
+    maxDepth?: number;
+};
+
+export declare type BackendSnapshotFreshness = {
+    action: string;
+    retryCount: number;
+    staleAfterRetries: boolean;
+    reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
+};
+
+export declare type BackendSnapshotOptions = SnapshotOptions & {
+    outPath?: string;
+};
+
+export declare type BackendSnapshotResult = {
+    nodes?: SnapshotNode[];
+    truncated?: boolean;
+    backend?: string;
+    snapshot?: SnapshotState;
+    analysis?: BackendSnapshotAnalysis;
+    freshness?: BackendSnapshotFreshness;
+    warnings?: string[];
+    appName?: string;
+    appBundleId?: string;
+};
+
+export declare type BackendSwipeOptions = {
+    durationMs?: number;
+};
+
+export declare type BackendTapOptions = {
+    button?: 'primary' | 'secondary' | 'middle';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+};
+
+export declare type BackendTraceOptions = {
+    outPath?: string;
+};
+
+export declare type BackendTraceResult = Record<string, unknown> & {
+    outPath?: string;
+};
+
+export declare function hasBackendCapability(backend: Pick<AgentDeviceBackend, 'platform' | 'capabilities'>, capability: BackendCapabilityName): boolean;
+
+export declare function hasBackendEscapeHatch(backend: Pick<AgentDeviceBackend, 'escapeHatches'>, capability: BackendCapabilityName): boolean;
+
+declare type Point = {
+    x: number;
+    y: number;
+};
+
+declare type RawSnapshotNode = {
+    index: number;
+    type?: string;
+    role?: string;
+    subrole?: string;
+    label?: string;
+    value?: string;
+    identifier?: string;
+    rect?: Rect;
+    enabled?: boolean;
+    selected?: boolean;
+    hittable?: boolean;
+    depth?: number;
+    parentIndex?: number;
+    pid?: number;
+    bundleId?: string;
+    appName?: string;
+    windowTitle?: string;
+    surface?: string;
+    hiddenContentAbove?: boolean;
+    hiddenContentBelow?: boolean;
+};
+
+declare type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+declare type ScreenshotOverlayRef = {
+    ref: string;
+    label?: string;
+    rect: Rect;
+    overlayRect: Rect;
+    center: Point;
+};
+
+declare type SnapshotBackend = 'xctest' | 'android' | 'macos-helper' | 'linux-atspi';
+
+declare type SnapshotNode = RawSnapshotNode & {
+    ref: string;
+};
+
+declare type SnapshotOptions = {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+declare type SnapshotState = {
+    nodes: SnapshotNode[];
+    createdAt: number;
+    truncated?: boolean;
+    backend?: SnapshotBackend;
+    comparisonSafe?: boolean;
+};
+
+export { }

package/dist/src/backend.js

@@ -0,0 +1 @@
+let e=["android.shell","ios.runnerCommand","macos.desktopScreenshot"],n={"android.shell":"androidShell","ios.runnerCommand":"iosRunnerCommand","macos.desktopScreenshot":"macosDesktopScreenshot"};function o(e,n){return e.capabilities?.includes(n)??!1}function a(e,o){let a=n[o];return"function"==typeof e.escapeHatches?.[a]}export{n as BACKEND_CAPABILITY_ESCAPE_HATCH_METHODS,e as BACKEND_CAPABILITY_NAMES,o as hasBackendCapability,a as hasBackendEscapeHatch};