agent-device 0.12.4 → 0.12.5

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,205 @@
+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>;
+    pressKey?(context: BackendCommandContext, key: string, options?: {
+        modifiers?: string[];
+    }): Promise<BackendActionResult>;
+    openApp?(context: BackendCommandContext, target: BackendOpenTarget): Promise<BackendActionResult>;
+    closeApp?(context: BackendCommandContext, app?: string): Promise<BackendActionResult>;
+    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendActionResult>;
+};
+
+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 BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
+
+export declare type BackendCapabilitySet = readonly BackendCapabilityName[];
+
+export declare type BackendCommandContext = {
+    session?: string;
+    requestId?: string;
+    appId?: string;
+    appBundleId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+};
+
+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 BackendInstallTarget = {
+    app: string;
+    artifactPath: string;
+};
+
+export declare type BackendOpenTarget = {
+    app?: string;
+    url?: string;
+    activity?: string;
+};
+
+export declare type BackendReadTextResult = {
+    text: 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 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 BackendTapOptions = {
+    button?: 'primary' | 'secondary' | 'middle';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+};
+
+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};