agent-device 0.18.2 → 0.19.0

package/dist/src/sdk-contracts.d.ts

@@ -0,0 +1,386 @@
+//#region src/kernel/device.d.ts
+declare const APPLE_OS_VALUES: readonly ['ios', 'ipados', 'tvos', 'watchos', 'visionos', 'macos'];
+type AppleOS = (typeof APPLE_OS_VALUES)[number];
+declare const PLATFORMS: readonly ['apple', 'android', 'linux', 'web'];
+type Platform = (typeof PLATFORMS)[number];
+declare const PUBLIC_PLATFORMS: readonly ['ios', 'macos', 'android', 'linux', 'web'];
+type PublicPlatform = (typeof PUBLIC_PLATFORMS)[number];
+declare const PLATFORM_SELECTORS: readonly ["apple", "android", "linux", "web", "ios", "macos"];
+type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
+declare const DEVICE_KINDS: readonly ['simulator', 'emulator', 'device'];
+type DeviceKind = (typeof DEVICE_KINDS)[number];
+declare const DEVICE_TARGETS: readonly ['mobile', 'tv', 'desktop'];
+type DeviceTarget = (typeof DEVICE_TARGETS)[number];
+//#endregion
+//#region src/kernel/errors.d.ts
+type KnownAppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'DEVICE_IN_USE' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'AMBIGUOUS_MATCH' | 'UNKNOWN';
+type AppErrorCode = KnownAppErrorCode | (string & {});
+/**
+ * Details bag for AppError. Free-form context is allowed, but these keys carry
+ * meaning at normalize/render time and must keep their types:
+ * - `hint` — overrides `defaultHintForCode`; re-wraps preserve an existing hint.
+ * - `diagnosticId` / `logPath` — lifted onto the normalized error, stripped from details.
+ * - `processExitError` + `stdout`/`stderr`/`exitCode` — marks a wrap of a real
+ *   process exit so normalizeError can surface the first meaningful stderr line;
+ *   build these via `execFailureDetails`/`requireExecSuccess` in src/utils/exec.ts
+ *   rather than by hand.
+ * - `retriable` — typed retry signal hoisted to the wire error shape.
+ * - `reason` — machine-dispatchable sub-classification within a code.
+ */
+type AppErrorDetails = Record<string, unknown> & {
+  hint?: string;
+  diagnosticId?: string;
+  logPath?: string;
+  retriable?: boolean;
+  supportedOn?: string;
+  processExitError?: boolean;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  reason?: string;
+};
+type NormalizedError = {
+  code: string;
+  message: string;
+  hint?: string;
+  diagnosticId?: string;
+  logPath?: string;
+  /**
+   * Lifted from `details.retriable` when a throw site classified the failure as
+   * clearly transient (or clearly not). Included only when set, so the default
+   * error wire shape is unchanged.
+   */
+  retriable?: boolean;
+  supportedOn?: string;
+  details?: Record<string, unknown>;
+};
+declare class AppError extends Error {
+  code: AppErrorCode;
+  details?: AppErrorDetails;
+  cause?: unknown;
+  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
+}
+declare function isAgentDeviceError(err: unknown): err is AppError;
+declare function normalizeAgentDeviceError(err: unknown, context?: {
+  diagnosticId?: string;
+  logPath?: string;
+}): NormalizedError;
+declare function normalizeError(err: unknown, context?: {
+  diagnosticId?: string;
+  logPath?: string;
+}): NormalizedError;
+declare function defaultHintForCode(code: string): string | undefined;
+//#endregion
+//#region src/contracts/debug-symbols.d.ts
+type DebugSymbolsOptions = {
+  action?: 'symbols';
+  artifact: string;
+  dsym?: string;
+  searchPath?: string;
+  out?: string;
+  cwd?: string;
+};
+type DebugSymbolsImage = {
+  name: string;
+  uuid: string;
+  arch?: string;
+  dsymPath: string;
+  binaryPath: string;
+};
+type DebugSymbolsCrashFrame = {
+  index: number;
+  image: string;
+  address: string;
+  symbol?: string;
+};
+type DebugSymbolsCrashSummary = {
+  format: 'ips' | 'text';
+  appName?: string;
+  bundleId?: string;
+  version?: string;
+  incident?: string;
+  timestamp?: string;
+  exceptionType?: string;
+  exceptionCodes?: string;
+  terminationReason?: string;
+  crashedThread?: number;
+  topFrames: DebugSymbolsCrashFrame[];
+  findings: string[];
+};
+type DebugSymbolsResult = {
+  kind: 'debugSymbols';
+  platform: 'apple';
+  artifactPath: string;
+  outPath: string;
+  crash: DebugSymbolsCrashSummary;
+  matchedImages: DebugSymbolsImage[];
+  symbolicatedFrames: number;
+  skippedImages: number;
+  warnings?: string[];
+  message: string;
+};
+//#endregion
+//#region src/kernel/snapshot.d.ts
+/**
+ * Structured quality verdict computed once by the iOS runner's snapshot capture plan.
+ * The daemon renders it; it never re-derives degradation from node shapes.
+ *
+ * Defined here (the foundational snapshot type module) rather than in
+ * snapshot-quality.ts so SnapshotNode can reference it without a cyclic import;
+ * snapshot-quality.ts (the validation logic) re-exports it for existing callers.
+ */
+type SnapshotQualityVerdict = {
+  state: 'healthy' | 'recovered' | 'sparse';
+  backend: 'tree' | 'queries' | 'private-ax';
+  reason?: string;
+  reasonCode?: 'ax-rejected' | 'sparse-tree' | 'budget' | 'no-nodes' | 'capture-failed';
+  effectiveDepth?: number;
+  collapsedLeafIndexes?: number[];
+};
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type Point = {
+  x: number;
+  y: number;
+};
+type RawSnapshotNode = {
+  index: number;
+  type?: string;
+  role?: string;
+  subrole?: string;
+  label?: string;
+  value?: string;
+  identifier?: string;
+  rect?: Rect;
+  enabled?: boolean;
+  selected?: boolean;
+  focused?: boolean;
+  visibleToUser?: boolean;
+  hittable?: boolean;
+  depth?: number;
+  parentIndex?: number;
+  pid?: number;
+  bundleId?: string;
+  appName?: string;
+  windowTitle?: string;
+  surface?: string;
+  hiddenContentAbove?: boolean;
+  hiddenContentBelow?: boolean;
+  interactionBlocked?: 'covered';
+  presentationHints?: string[];
+};
+type SnapshotNode = RawSnapshotNode & {
+  ref: string;
+  /**
+   * Output-only marker set by client-serialization dedup (see
+   * ../snapshot/snapshot-label-dedup.ts) when `label`/`identifier` was omitted
+   * because it string-equals the nearest ancestor's value in the parent chain.
+   * Never set on the in-daemon session tree used by selectors/wait/replay.
+   */
+  inheritsLabel?: true;
+  inheritsIdentifier?: true;
+};
+type SnapshotBackend = 'xctest' | 'android' | 'macos-helper' | 'linux-atspi' | 'web';
+type SnapshotState = {
+  nodes: SnapshotNode[];
+  createdAt: number;
+  truncated?: boolean;
+  backend?: SnapshotBackend;
+  snapshotQuality?: SnapshotQualityVerdict;
+  comparisonSafe?: boolean;
+  presentationKey?: string;
+};
+type SnapshotUnchanged = {
+  ageMs: number;
+  nodeCount: number;
+  interactiveOnly?: boolean;
+  scope?: string;
+};
+type SnapshotVisibilityReason = 'offscreen-nodes' | 'scroll-hidden-above' | 'scroll-hidden-below';
+type SnapshotVisibility = {
+  partial: boolean;
+  visibleNodeCount: number;
+  totalNodeCount: number;
+  reasons: SnapshotVisibilityReason[];
+};
+type ScreenshotOverlayRef = {
+  ref: string;
+  label?: string;
+  rect: Rect;
+  overlayRect: Rect;
+  center: Point;
+};
+declare function centerOfRect(rect: Rect): Point;
+//#endregion
+//#region src/kernel/contracts.d.ts
+type SessionRuntimeHints = {
+  platform?: 'ios' | 'android';
+  metroHost?: string;
+  metroPort?: number;
+  bundleUrl?: string;
+  launchUrl?: string;
+};
+type DaemonInstallSource = {
+  kind: 'url';
+  url: string;
+  headers?: Record<string, string>;
+} | {
+  kind: 'path';
+  path: string;
+} | ({
+  kind: 'github-actions-artifact';
+  owner: string;
+  repo: string;
+} & ({
+  artifactId: number;
+} | {
+  runId: number;
+  artifactName: string;
+} | {
+  artifactName: string;
+}));
+declare const DAEMON_LOCK_POLICIES: readonly ['reject', 'strip'];
+type DaemonLockPolicy = (typeof DAEMON_LOCK_POLICIES)[number];
+declare const LEASE_BACKENDS: readonly ['ios-simulator', 'ios-instance', 'android-instance'];
+type LeaseBackend = (typeof LEASE_BACKENDS)[number];
+declare const DAEMON_SERVER_MODES: readonly ['socket', 'http', 'dual'];
+type DaemonServerMode = (typeof DAEMON_SERVER_MODES)[number];
+declare const DAEMON_TRANSPORT_PREFERENCES: readonly ['auto', 'socket', 'http'];
+type DaemonTransportPreference = (typeof DAEMON_TRANSPORT_PREFERENCES)[number];
+declare const SESSION_ISOLATION_MODES: readonly ['none', 'tenant'];
+type SessionIsolationMode = (typeof SESSION_ISOLATION_MODES)[number];
+declare const NETWORK_INCLUDE_MODES: readonly ['summary', 'headers', 'body', 'all'];
+type NetworkIncludeMode = (typeof NETWORK_INCLUDE_MODES)[number];
+declare const RESPONSE_LEVELS: readonly ['digest', 'default', 'full'];
+type ResponseLevel = (typeof RESPONSE_LEVELS)[number];
+type DaemonRequestMeta = {
+  requestId?: string;
+  debug?: boolean;
+  includeCost?: boolean;
+  responseLevel?: ResponseLevel;
+  cwd?: string;
+  sessionExplicit?: boolean;
+  tenantId?: string;
+  runId?: string;
+  leaseId?: string;
+  leaseTtlMs?: number;
+  leaseBackend?: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+  sessionIsolation?: SessionIsolationMode;
+  uploadedArtifactId?: string;
+  clientArtifactPaths?: Record<string, string>;
+  installSource?: DaemonInstallSource;
+  retainMaterializedPaths?: boolean;
+  materializedPathRetentionMs?: number;
+  materializationId?: string;
+  lockPolicy?: DaemonLockPolicy;
+  lockPlatform?: PlatformSelector;
+  requestProgress?: 'replay-test' | 'command';
+};
+type DaemonRequest = {
+  token?: string;
+  session?: string;
+  command: string;
+  positionals: string[];
+  flags?: Record<string, unknown>;
+  runtime?: SessionRuntimeHints;
+  meta?: DaemonRequestMeta;
+};
+type DaemonArtifactKnownType = 'screenshot' | 'screenshot-diff' | 'screen-recording' | 'screen-recording-chunk' | 'screen-recording-telemetry' | 'trace-log';
+type DaemonArtifactType = DaemonArtifactKnownType | (string & {});
+type DaemonArtifact = {
+  field: string;
+  artifactType?: DaemonArtifactType;
+  artifactId?: string;
+  fileName?: string;
+  localPath?: string;
+  path?: string;
+};
+type ResponseCost = {
+  wallClockMs: number;
+  runnerRoundTrips: number;
+  nodeCount?: number;
+};
+type DaemonResponseData = Record<string, unknown> & {
+  artifacts?: DaemonArtifact[];
+  cost?: ResponseCost;
+};
+type DaemonError = {
+  code: string;
+  message: string;
+  hint?: string;
+  diagnosticId?: string;
+  logPath?: string;
+  details?: Record<string, unknown>;
+  /**
+   * Machine-readable typed-error signals (Phase 2). Additive: present only when
+   * derivable, so the default error wire shape is unchanged.
+   *
+   * `retriable` flags a transient failure an agent should retry (vs. a
+   * deterministic one where a retry is wasted). `supportedOn` lists the platform
+   * families that DO support the command (derived from the capability matrix),
+   * surfaced on platform-mismatch errors so an agent self-corrects without a
+   * wasted round-trip.
+   */
+  retriable?: boolean;
+  supportedOn?: string;
+};
+type DaemonResponse = {
+  ok: true;
+  data?: DaemonResponseData;
+} | {
+  ok: false;
+  error: DaemonError;
+};
+type LeaseAllocatePayload = {
+  token?: string;
+  session?: string;
+  tenantId?: string;
+  tenant?: string;
+  runId?: string;
+  ttlMs?: number;
+  backend?: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+};
+type LeaseHeartbeatPayload = {
+  token?: string;
+  session?: string;
+  tenantId?: string;
+  tenant?: string;
+  runId?: string;
+  leaseId?: string;
+  ttlMs?: number;
+  backend?: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+};
+type LeaseReleasePayload = {
+  token?: string;
+  session?: string;
+  tenantId?: string;
+  tenant?: string;
+  runId?: string;
+  leaseId?: string;
+  backend?: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+};
+type JsonRpcId = string | number | null;
+type JsonRpcRequestEnvelope<TParams = unknown> = {
+  jsonrpc?: string;
+  id?: JsonRpcId;
+  method?: string;
+  params?: TParams;
+};
+//#endregion
+export { AppError as A, PlatformSelector as B, SnapshotQualityVerdict as C, centerOfRect as D, SnapshotVisibility as E, normalizeError as F, AppleOS as I, DeviceKind as L, defaultHintForCode as M, isAgentDeviceError as N, DebugSymbolsOptions as O, normalizeAgentDeviceError as P, DeviceTarget as R, SnapshotNode as S, SnapshotUnchanged as T, PublicPlatform as V, ResponseLevel as _, DaemonRequest as a, Point as b, DaemonServerMode as c, JsonRpcRequestEnvelope as d, LeaseAllocatePayload as f, NetworkIncludeMode as g, LeaseReleasePayload as h, DaemonLockPolicy as i, NormalizedError as j, DebugSymbolsResult as k, DaemonTransportPreference as l, LeaseHeartbeatPayload as m, DaemonError as n, DaemonResponse as o, LeaseBackend as p, DaemonInstallSource as r, DaemonResponseData as s, DaemonArtifactType as t, JsonRpcId as u, SessionIsolationMode as v, SnapshotState as w, ScreenshotOverlayRef as x, SessionRuntimeHints as y, Platform as z };

package/dist/src/sdk-contracts.js

@@ -0,0 +1,2 @@
+const e=/(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key|user[_-]?code|device[_-]?code|refresh[_-]?credential)/i,t=/\b(?:bearer\s+[a-z0-9._-]+|adc_(?:agent|live|refresh|cli)_[a-z0-9._-]+)\b/gi,n=/\b([a-z0-9_-]*(?:api[_-]?key|token|secret|password|user[_-]?code|device[_-]?code|refresh[_-]?credential)[a-z0-9_-]*)(\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gi,r=/https?:\/\/[^\s"'<>]+/gi;function i(e){return a(e,new WeakSet)}function a(t,n,r){if(t==null)return t;if(typeof t==`string`)return o(t,r);if(typeof t!=`object`)return t;if(n.has(t))return`[Circular]`;if(n.add(t),Array.isArray(t))return t.map(e=>a(e,n));let i={};for(let[r,o]of Object.entries(t)){if(e.test(r)){i[r]=`[REDACTED]`;continue}i[r]=a(o,n,r)}return i}function o(r,i){let a=r.trim();if(!a)return r;if(i&&e.test(i))return`[REDACTED]`;let o=s(a);return o=o.replace(t,`[REDACTED]`),o=o.replace(n,(e,t,n,r,i,a)=>l({key:t,separator:n,rawValue:r,offset:i,input:a})||c(r)?e:`${t}${n}[REDACTED]`),o===a?a.length>400?`${a.slice(0,200)}...<truncated>`:a:o}function s(e){return e.replace(r,e=>u(e)??e)}function c(e){return/^adc_(?:agent|live|refresh|cli)_\.\.\.$/i.test(e)}function l(e){if(e.key.toLowerCase()!==`token`||!e.separator.includes(`:`))return!1;try{return new URL(e.rawValue).pathname.replace(/\/+$/,``)===`/api-keys`?/(?:^|\b)(?:service\/)?api\s+$/i.test(e.input.slice(0,e.offset)):!1}catch{return!1}}function u(e){try{let t=new URL(e);return t.search&&=`?REDACTED`,(t.username||t.password)&&(t.username=`REDACTED`,t.password=`REDACTED`),t.toString()}catch{return null}}function d(e,t=`COMMAND_FAILED`){return typeof e==`string`&&e.length>0?e:t}var f=class extends Error{code;details;cause;constructor(e,t,n,r){super(t),this.code=e,this.details=n,this.cause=r}};function p(e,t=`UNKNOWN`){return e instanceof f?e:e instanceof Error?new f(t,e.message,void 0,e):new f(t,`Unknown error`,{err:e})}function ee(e){return e instanceof f}function m(e,t={}){return h(e,t)}function h(e,t={}){let n=p(e),r=n.details?i(n.details):void 0,a=y(r,`diagnosticId`)??t.diagnosticId,o=y(r,`logPath`)??t.logPath,s=y(r,`hint`)??x(n.code),c=re(r,`retriable`)??b(n.code),l=y(r,`supportedOn`),u=ie(r),d=ne(n.code,n.message,r);return{code:n.code,message:d,hint:s,diagnosticId:a,logPath:o,...c===void 0?{}:{retriable:c},...l===void 0?{}:{supportedOn:l},details:u}}const te=/^\S+ exited with code -?\d+$/;function ne(e,t,n){if(e!==`COMMAND_FAILED`||n?.processExitError!==!0)return t;let r=v(typeof n?.stderr==`string`?n.stderr:``);return r?te.test(t)?r:t.includes(r)?t:`${t}: ${r}`:t}const g=[/^an error was encountered processing the command/i,/^underlying error\b/i,/^simulator device failed to complete the requested operation/i],_=/^(?:(?:adb|xcrun|simctl):\s*)?(?:error:\s*)?/i;function v(e){for(let t of e.split(`
+`)){let e=t.trim();if(!e||g.some(t=>t.test(e)))continue;let n=e.replace(_,``).trim();if(n)return n.length>200?`${n.slice(0,200)}...`:n}return null}function y(e,t){let n=e?.[t];return typeof n==`string`?n:void 0}function re(e,t){let n=e?.[t];return typeof n==`boolean`?n:void 0}function ie(e){if(!e)return;let t={...e};return delete t.hint,delete t.diagnosticId,delete t.logPath,delete t.retriable,delete t.supportedOn,Object.keys(t).length>0?t:void 0}function b(e){switch(e){case`DEVICE_IN_USE`:return!0;default:return}}function x(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`UNSUPPORTED_PLATFORM`:return`This platform is not supported for the requested operation; run devices to inspect available targets.`;case`AMBIGUOUS_MATCH`:return`Multiple candidates matched. Narrow the query or pass an exact identifier.`;case`DEVICE_IN_USE`:return`The device is busy with another agent-device request; retry once it frees up.`;case`NOT_IMPLEMENTED`:return`This command is part of the planned API but is not implemented yet.`;case`COMMAND_FAILED`:return`Retry with --debug and inspect diagnostics log for details.`;case`UNAUTHORIZED`:return`Refresh daemon metadata and retry the command.`;case`UNKNOWN`:return`Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.`;default:return`Retry with --debug and inspect diagnostics log for details.`}}function ae(e){return e===`xctest`||e===`android`||e===`macos-helper`||e===`linux-atspi`||e===`web`}function oe(e){return e===void 0||e===`xctest`||e===`android`}function se(e){return e.map((e,t)=>({...e,ref:`e${t+1}`}))}const ce=/^~s(\d+)$/,le=`Refs look like @e12, optionally pinned to the snapshot generation that minted them: @e12~s3 (the ref, then "~s" and the refsGeneration reported by the issuing snapshot/find response).`;function S(e){let t=e.trim(),n=t.indexOf(`~`);if(n===-1)return{base:t};let r=ce.exec(t.slice(n));return!r||n===0?null:{base:t.slice(0,n),generation:Number(r[1])}}function ue(e){let t=S(e);if(!t)return null;let n=t.base;return n.startsWith(`@`)?n.slice(1)||null:n.startsWith(`e`)?n:null}function de(e,t){return e.find(e=>e.ref===t)??null}function fe(e){return JSON.stringify({interactiveOnly:e?.interactiveOnly===!0,depth:typeof e?.depth==`number`?e.depth:null,scope:e?.scope?.trim()||null,raw:e?.raw===!0})}function pe(e){if(e)return{depth:e.snapshotDepth,interactiveOnly:e.snapshotInteractiveOnly,raw:e.snapshotRaw,scope:e.snapshotScope}}function me(e){return{x:Math.round(e.x+e.width/2),y:Math.round(e.y+e.height/2)}}const C=[`ios`,`ipados`,`tvos`,`watchos`,`visionos`,`macos`],w=[`apple`,`android`,`linux`,`web`],T=[`ios`,`macos`,`android`,`linux`,`web`],E=[...w,`ios`,`macos`],D=[`mobile`,`tv`,`desktop`];function O(e){return e===`apple`||e===`ios`||e===`macos`}function k(e){return e.appleOs===`macos`||e.platform===`macos`}function A(e){return O(e.platform)&&!k(e)}function j(e){return e.platform===`android`||O(e.platform)&&!k(e)}function M(e){return O(e.platform)?k(e)?`macos`:`ios`:e.platform}function N(e){return e===`macos`?{platform:`apple`,appleOs:`macos`}:e===`ios`?{platform:`apple`}:{platform:e}}function P(e){return O(e.platform)&&e.target===`tv`}function F(e){return T.includes(e)}function I(e){return C.includes(e)}function L(e,t){return t?t===`apple`?O(e.platform):t===`ios`?O(e.platform)&&!k(e):t===`macos`?O(e.platform)&&k(e):e.platform===t:!0}function R(e,t){return t?z(t):e===`macos`||e===`desktop`?`macOS`:e===`tv`?`tvOS`:`iOS`}function z(e){switch(e){case`tvos`:return`tvOS`;case`macos`:return`macOS`;case`visionos`:return`visionOS`;default:return`iOS`}}function he(e){let{simulatorSetPath:t,platform:n,target:r}=e;if(t&&!(n===`macos`||r===`desktop`))return t}function B(e){return e.map((e,t)=>({device:e,index:t})).sort((e,t)=>be(e,t)).map(({device:e})=>e)}function ge(e){return!e||e===`apple`||e===`ios`}async function _e(e,t,n={}){let r=e.filter(e=>V(e,t));if(t.udid){let e=r.find(e=>e.id===t.udid&&O(e.platform));if(!e)throw new f(`DEVICE_NOT_FOUND`,`No Apple device with UDID ${t.udid}`);return e}if(t.serial){let e=r.find(e=>e.id===t.serial&&e.platform===`android`);if(!e)throw new f(`DEVICE_NOT_FOUND`,`No Android device with serial ${t.serial}`);return e}if(n.allowStoppedAndroidAvdPlaceholders!==!0&&(r=r.filter(e=>!ve(e))),t.deviceName){let e=U(t.deviceName),n=r.find(t=>U(t.name)===e);if(!n)throw new f(`DEVICE_NOT_FOUND`,`No device named ${t.deviceName}`);return n}K(r)&&(r=B(r));let i=r[0];if(i!==void 0&&r.length===1)return i;r.length===0&&H(t,n);let a=r.filter(e=>e.kind!==`device`),o=a.length>0?a:r,s=o.filter(e=>e.booted),c=s[0];if(c&&s.length===1&&!K(o))return c;let l=K(o)?o[0]:s[0]??o[0];return l||H(t,n),l}function ve(e){return e.platform===`android`&&e.kind===`emulator`&&e.booted===!1&&!/^emulator-\d+$/.test(e.id)}function V(e,t,n={}){return L(e,t.platform)&&(!t.target||(e.target??`mobile`)===t.target)&&(!n.includeExplicitSelectors||ye(e,t))}function ye(e,t){return!(t.udid&&!(e.id===t.udid&&O(e.platform))||t.serial&&!(e.id===t.serial&&e.platform===`android`)||t.deviceName&&U(e.name)!==U(t.deviceName))}function H(e,t){let n=t.simulatorSetPath;throw n&&ge(e.platform)?new f(`DEVICE_NOT_FOUND`,`No devices found in the scoped simulator set`,{simulatorSetPath:n,hint:`The simulator set at "${n}" appears to be empty. Create a compatible simulator first with xcrun simctl --set "${n}" create, or remove the scoped simulator set.`,selector:e}):new f(`DEVICE_NOT_FOUND`,`No devices found`,{selector:e})}function U(e){return e.toLowerCase().replace(/_/g,` `).replace(/\s+/g,` `).trim()}function be(e,t){return W(e.device)-W(t.device)||Number(t.device.booted===!0)-Number(e.device.booted===!0)||e.device.name.localeCompare(t.device.name)||e.index-t.index}function W(e){return e.kind===`simulator`?G(e,0,1,2,3):e.kind===`device`&&O(e.platform)&&!k(e)?G(e,10,11,12,13):14}function G(e,t,n,r,i){return{mobile:xe(e.name)?n:t,tv:r,desktop:i}[e.target??`mobile`]}function K(e){return e.length>0&&e.every(e=>O(e.platform))}function xe(e){return/\bipad\b/i.test(e)}const Se=[`summary`,`headers`,`body`,`all`],Ce=[`digest`,`default`,`full`];function we(e){return e!==void 0&&e!=="default"}function q(e){return{parse(t){return e(t,`$`)}}}function J(e,t){throw Error(`${e}: ${t}`)}function Y(e,t){return(!e||typeof e!=`object`||Array.isArray(e))&&J(t,`Expected an object`),e}function X(e,t){return typeof e!=`string`&&J(t,`Expected a string`),e}function Te(e,t){return Number.isInteger(e)||J(t,`Expected an integer`),e}function Z(e,t){return Array.isArray(e)||J(t,`Expected an array`),e}function Q(e,t,n){let r=e[t];return r===void 0?void 0:X(r,`${n}.${t}`)}function Ee(e,t,n){let r=e[t];if(r!==void 0)return Z(r,`${n}.${t}`).map((e,r)=>X(e,`${n}.${t}[${String(r)}]`))}function De(e,t,n){let r=e[t];return r===void 0?void 0:Te(r,`${n}.${t}`)}function $(e,t,n){let r=e[t];return r===void 0?void 0:Y(r,`${n}.${t}`)}function Oe(e,t,n,r){let i=e[t];if(i!==void 0)return(typeof i!=`string`||!n.includes(i))&&J(`${r}.${t}`,`Expected one of: ${n.join(`, `)}`),i}const ke=q((e,t)=>{let n=Y(e,t);return{platform:Oe(n,`platform`,[`ios`,`android`],t),metroHost:Q(n,`metroHost`,t),metroPort:De(n,`metroPort`,t),bundleUrl:Q(n,`bundleUrl`,t),launchUrl:Q(n,`launchUrl`,t)}});function Ae(e,t){let n=e.id;return n==null||typeof n!=`string`&&typeof n!=`number`&&J(`${t}.id`,`Expected a string, number, or null`),n}const je=q((e,t)=>{let n=Y(e,t);return{jsonrpc:Q(n,`jsonrpc`,t),id:Ae(n,t),method:Q(n,`method`,t),params:n.params}}),Me=q((e,t)=>{let n=Y(e,t);return{token:Q(n,`token`,t),session:Q(n,`session`,t),command:Q(n,`command`,t),positionals:Ee(n,`positionals`,t),flags:$(n,`flags`,t),runtime:$(n,`runtime`,t),meta:$(n,`meta`,t)}});export{ae as A,h as B,_e as C,fe as D,se as E,f as F,d as H,p as I,x as L,pe as M,S as N,me as O,oe as P,ee as R,he as S,le as T,i as U,b as V,P as _,we as a,M as b,w as c,I as d,O as f,F as g,j as h,ke as i,ue as j,de as k,E as l,k as m,Ce as n,je as o,A as p,Me as r,D as s,Se as t,N as u,V as v,B as w,R as x,L as y,m as z};

package/dist/src/sdk-finders.d.ts

@@ -0,0 +1,61 @@
+import { S as SnapshotNode } from "./sdk-contracts.js";
+
+//#region src/utils/selectors-parse.d.ts
+type SelectorKey = 'id' | 'role' | 'text' | 'label' | 'value' | 'appname' | 'windowtitle' | 'visible' | 'hidden' | 'editable' | 'selected' | 'enabled' | 'hittable';
+type SelectorTerm = {
+  key: SelectorKey;
+  value: string | boolean;
+};
+type Selector = {
+  raw: string;
+  terms: SelectorTerm[];
+};
+type SelectorChain = {
+  raw: string;
+  selectors: Selector[];
+};
+declare function parseSelectorChain(expression: string): SelectorChain;
+declare function tryParseSelectorChain(expression: string): SelectorChain | null;
+declare function isSelectorToken(token: string): boolean;
+//#endregion
+//#region src/utils/finders.d.ts
+declare const FIND_LOCATORS: readonly ['any', 'text', 'label', 'value', 'role', 'id'];
+type FindLocator = (typeof FIND_LOCATORS)[number];
+type FindAction = {
+  kind: 'click';
+} | {
+  kind: 'focus';
+} | {
+  kind: 'fill';
+  value: string;
+} | {
+  kind: 'type';
+  value: string;
+} | {
+  kind: 'get_text';
+} | {
+  kind: 'get_attrs';
+} | {
+  kind: 'exists';
+} | {
+  kind: 'wait';
+  timeoutMs?: number;
+};
+declare function parseFindArgs(args: string[]): {
+  locator: FindLocator;
+  query: string;
+  action: FindAction['kind'];
+  value?: string;
+  timeoutMs?: number;
+};
+//#endregion
+//#region src/finders.d.ts
+type FindMatchOptions = {
+  requireRect?: boolean;
+};
+declare function findBestMatchesByLocator(nodes: SnapshotNode[], locator: FindLocator, query: string, options?: boolean | FindMatchOptions): {
+  matches: SnapshotNode[];
+  score: number;
+};
+//#endregion
+export { Selector as a, parseSelectorChain as c, parseFindArgs as i, tryParseSelectorChain as l, findBestMatchesByLocator as n, SelectorChain as o, FindLocator as r, isSelectorToken as s, FindMatchOptions as t };

package/dist/src/sdk-finders.js

@@ -0,0 +1 @@
+import{F as e}from"./sdk-contracts.js";import{y as t}from"./sdk-batch.js";const n=[`any`,`text`,`label`,`value`,`role`,`id`],r=[`text`,`label`,`value`,`role`,`id`];function i(e,t,n,r={}){let i=c(n);if(!i)return{matches:[],score:0};let o=0,s=[];for(let n of e){if(r.requireRect&&!n.rect)continue;let e=a(n,t,i);if(!(e<=0)){if(e>o){o=e,s.length=0,s.push(n);continue}e===o&&s.push(n)}}return{matches:s,score:o}}function a(e,t,n){switch(t){case`role`:return s(e.type,n);case`label`:return o(e.label,n);case`value`:return o(e.value,n);case`id`:return o(e.identifier,n);default:return Math.max(o(e.label,n),o(e.value,n),o(e.identifier,n))}}function o(e,t){let n=c(e??``);return n?n===t?2:+!!n.includes(t):0}function s(e,t){let n=l(e??``);return n?n===t?2:+!!n.includes(t):0}function c(e){return e.trim().toLowerCase().replace(/\s+/g,` `)}function l(e){let t=e.trim();return t?(t=(t.split(`.`).pop()??t).replace(/XCUIElementType/gi,``).toLowerCase(),t):``}function u(t){let n=`any`,i=0;r.includes(t[0])&&(n=t[0],i=1);let a=t[i]??``,o=t.slice(i+1);if(o.length===0)return{locator:n,query:a,action:`click`};let s=o[0]?.toLowerCase();if(s===`get`){let t=o[1]?.toLowerCase();if(t===`text`)return{locator:n,query:a,action:`get_text`};if(t===`attrs`)return{locator:n,query:a,action:`get_attrs`};throw new e(`INVALID_ARGS`,`find get only supports text or attrs`)}if(s===`wait`){let e=f(o[1]);return{locator:n,query:a,action:`wait`,timeoutMs:e??void 0}}if(s===`exists`)return{locator:n,query:a,action:`exists`};if(s===`click`)return{locator:n,query:a,action:`click`};if(s===`focus`)return{locator:n,query:a,action:`focus`};if(s===`fill`){let e=o.slice(1).join(` `);return{locator:n,query:a,action:`fill`,value:e}}if(s===`type`){let e=o.slice(1).join(` `);return{locator:n,query:a,action:`type`,value:e}}throw new e(`INVALID_ARGS`,`Unsupported find action: ${o[0]}`)}function d(e,n){return e!==`any`||!n.includes(`=`)&&!n.includes(`||`)?null:t(n)}function f(e){if(!e)return null;let t=Number(e);return Number.isFinite(t)?t:null}function p(e,t,n,r){return i(e,t,n,typeof r==`boolean`?{requireRect:r}:r)}export{u as a,c as i,n,d as o,i as r,p as t};

package/dist/src/sdk-io.d.ts

@@ -0,0 +1,79 @@
+import { t as DaemonArtifactType } from "./sdk-contracts.js";
+
+//#region src/io.d.ts
+type FileInputRef = {
+  kind: 'path';
+  path: string;
+} | {
+  kind: 'uploadedArtifact';
+  id: string;
+};
+type FileOutputRef = {
+  kind: 'path';
+  path: string;
+} | {
+  kind: 'downloadableArtifact';
+  clientPath?: string;
+  fileName?: string;
+};
+type ArtifactDescriptor = {
+  kind: 'localPath';
+  field: string;
+  artifactType: DaemonArtifactType | undefined;
+  path: string;
+  fileName?: string;
+  metadata?: Record<string, unknown>;
+} | {
+  kind: 'artifact';
+  field: string;
+  artifactType: DaemonArtifactType | undefined;
+  artifactId: string;
+  fileName?: string;
+  url?: string;
+  clientPath?: string;
+  metadata?: Record<string, unknown>;
+};
+type OutputVisibility = 'client-visible' | 'internal';
+type ResolvedInputFile = {
+  path: string;
+  cleanup?: () => Promise<void>;
+};
+type ReservedOutputFile = {
+  path: string;
+  visibility: OutputVisibility;
+  publish: () => Promise<ArtifactDescriptor | undefined>;
+  cleanup?: () => Promise<void>;
+};
+type TemporaryFile = {
+  path: string;
+  visibility: 'internal';
+  cleanup: () => Promise<void>;
+};
+type ResolveInputOptions = {
+  usage: string;
+  field?: string;
+};
+type ReserveOutputOptions = {
+  field: string;
+  ext: string;
+  artifactType: DaemonArtifactType | undefined;
+  requestedClientPath?: string;
+  visibility?: OutputVisibility;
+};
+type CreateTempFileOptions = {
+  prefix: string;
+  ext: string;
+};
+type ArtifactAdapter = {
+  resolveInput(ref: FileInputRef, options: ResolveInputOptions): Promise<ResolvedInputFile>;
+  reserveOutput(ref: FileOutputRef | undefined, options: ReserveOutputOptions): Promise<ReservedOutputFile>;
+  createTempFile(options: CreateTempFileOptions): Promise<TemporaryFile>;
+};
+type LocalArtifactAdapterOptions = {
+  cwd?: string;
+  tempDir?: string;
+  rootDir?: string;
+};
+declare function createLocalArtifactAdapter(options?: LocalArtifactAdapterOptions): ArtifactAdapter;
+//#endregion
+export { FileOutputRef as a, ReserveOutputOptions as c, ResolvedInputFile as d, TemporaryFile as f, FileInputRef as i, ReservedOutputFile as l, ArtifactDescriptor as n, LocalArtifactAdapterOptions as o, createLocalArtifactAdapter as p, CreateTempFileOptions as r, OutputVisibility as s, ArtifactAdapter as t, ResolveInputOptions as u };

package/dist/src/sdk-io.js

@@ -0,0 +1 @@
+import{t as e}from"./rolldown-runtime.js";import{F as t}from"./sdk-contracts.js";import{promises as n}from"node:fs";import r from"node:os";import i from"node:path";var a=e({createLocalArtifactAdapter:()=>o});function o(e={}){let a=e.cwd??process.cwd(),o=e.tempDir??r.tmpdir(),c=e.rootDir?s(e.rootDir,a):void 0;return{resolveInput:async e=>{if(e.kind===`uploadedArtifact`)throw new t(`UNSUPPORTED_OPERATION`,`Uploaded artifact inputs require a custom artifact adapter`);return{path:s(e.path,a,c)}},reserveOutput:async(e,t)=>{let r,l=t.visibility??`client-visible`,u=e?.kind===`path`?s(e.path,a,c):i.join(r=await n.mkdtemp(i.join(o,`agent-device-${t.field}-`)),`${t.field}${t.ext}`);return await n.mkdir(i.dirname(u),{recursive:!0}),{path:u,visibility:l,...r?{cleanup:async()=>{await n.rm(r,{recursive:!0,force:!0})}}:{},publish:async()=>e?.kind===`downloadableArtifact`?{kind:`localPath`,field:t.field,artifactType:t.artifactType,path:u,fileName:e.fileName??i.basename(e.clientPath??u)}:void 0}},createTempFile:async e=>{let t=await n.mkdtemp(i.join(o,`${e.prefix}-`));return{path:i.join(t,`file${e.ext}`),visibility:`internal`,cleanup:async()=>{await n.rm(t,{recursive:!0,force:!0})}}}}}function s(e,n,r){let a=i.isAbsolute(e)?e:i.resolve(n,e);if(r&&!c(a,r))throw new t(`INVALID_ARGS`,`Local path is outside the artifact adapter root`,{path:a,rootDir:r});return a}function c(e,t){let n=i.relative(t,e);return n===``||!n.startsWith(`..`)&&!i.isAbsolute(n)}export{a as n,o as t};