agent_device library
Public API for the agent_device Dart port.
Mirrors the TypeScript src/index.ts export surface of the upstream
agent-device package. Individual symbols are added as their source
modules are ported (see PORTING_PLAN.md).
Classes
- AgentDevice
- The programmatic façade that SDK consumers drive. Construct one via AgentDevice.open; every command call resolves the currently-bound device from session state and dispatches to the underlying Backend.
- AndroidBackend
- Android platform backend.
- AppErrorCodes
-
Known error codes. Additional strings flow through verbatim so that
daemon-originated codes round-trip without a union update. Consumers
switching on
codeshould always include a default branch. - Backend
- Platform-abstract backend.
- BackendAlertHandledResult
- BackendAlertInfo
- Information about an alert.
- BackendAlertResult
- Result of an alert operation.
- BackendAlertStatusResult
- BackendAlertWaitResult
- BackendAppEvent
- Event that can be triggered on an app.
- BackendAppInfo
- Information about a single installed application.
- BackendAppState
- Current state of an application on the device.
- BackendBackOptions
- Options for back navigation.
- BackendClipboardTextResult
- Result of getting clipboard text.
- BackendCommandContext
- Context information for a backend command.
- BackendDeviceFilter
- Filter criteria for querying available devices.
- BackendDeviceInfo
- Information about a specific device that a backend can identify.
- BackendDeviceTarget
- A target device specification for operations like boot or ensure-simulator.
- BackendDiagnosticsTimeWindow
- A time window for diagnostic queries.
- BackendDumpNetworkOptions
- Options for dumping network activity.
- BackendDumpNetworkResult
- Result of dumping network activity.
- BackendEnsureSimulatorOptions
- Options for ensuring a simulator exists and is ready.
- BackendEnsureSimulatorResult
- Result of ensuring a simulator.
- BackendFillOptions
- Options for text fill operations.
- BackendFindTextResult
- Result of finding text.
- BackendInstallResult
- Result of an install operation.
- BackendInstallSource
- Source for app installation.
- BackendInstallSourcePath
- BackendInstallSourceUploadedArtifact
- BackendInstallSourceUrl
- BackendInstallTarget
- Target for installing an app.
- BackendKeyboardOptions
- Options for keyboard operations.
- BackendKeyboardResult
- Result of a keyboard operation.
- BackendLogEntry
- A single log entry.
- BackendLongPressOptions
- Options for long press gestures.
- BackendMeasurePerfOptions
- Options for measuring performance.
- BackendMeasurePerfResult
- Result of measuring performance.
- BackendNetworkEntry
- A single network request/response entry.
- BackendOpenOptions
- Options for opening an app.
- BackendOpenTarget
- Target specification for opening an app or URL.
- BackendPerfMetric
- A single performance metric.
- BackendPinchOptions
- Options for pinch gestures.
- BackendPushInput
- Input for push file operation.
- BackendPushInputFile
- BackendPushInputJson
- BackendReadLogsOptions
- Options for reading logs.
- BackendReadLogsResult
- Result of reading logs.
- BackendReadTextResult
- Result of reading text from a node.
- BackendRecordingOptions
- Options for recording video.
- BackendRecordingResult
- Result of a recording operation.
- BackendRunnerCommand
- A command to run via runner.
- BackendScreenshotOptions
- Options for capturing a screenshot.
- BackendScreenshotResult
- Result of a screenshot operation.
- BackendScrollOptions
- Options for scroll operations.
- BackendScrollTarget
- Target for scroll operations (viewport or specific point).
- BackendScrollTargetPoint
- BackendScrollTargetViewport
- BackendSnapshotAnalysis
- Analysis of a snapshot.
- BackendSnapshotOptions
- Options for capturing a snapshot.
- BackendSnapshotResult
- Result of a snapshot operation.
- BackendSwipeOptions
- Options for swipe gestures.
- BackendTapOptions
- Options for tap gestures.
- BackendTraceOptions
- Options for tracing.
- BackendTraceResult
- Result of a trace operation.
- CancelToken
- Token for canceling operations.
- CommandClock
-
Clock abstraction for tests that need to replace
DateTime.nowand sleeps. - CommandSessionRecord
- Snapshot of a single session, persisted by the runtime so subsequent commands can reference the currently-opened app, last snapshot, etc.
- CommandSessionStore
- Storage backend for CommandSessionRecords keyed by session name.
- Deadline
- Deadline for timeout-bounded retry.
- DeviceSelector
- Selector filter used by AgentDevice.open to pick which connected device to bind a session to. At least one of serial, name, or platform should be provided to narrow down multi-device setups.
- DiagnosticEvent
- A single diagnostic event.
- DiagnosticsMetadata
- Metadata about the current diagnostics scope.
- DiagnosticsScopeOptions
- Options for a diagnostics scope.
- EmitDiagnosticOptions
- Options for a diagnostic event.
- ExecBackgroundResult
- Result of background process execution.
- ExecDetachedOptions
- Options for detached process execution.
- ExecOptions
- Options for process execution.
- ExecStreamOptions
- Options for streaming process execution.
- FileSessionStore
-
Stores CommandSessionRecords as one JSON file per session under
<sessionsDir>/<safeName>.json. - IosBackend
- IosRunnerClient
- Launch + manage the XCUITest runner.
- IosRunnerSession
- Live connection to an XCUITest runner process.
- IsPredicateResult
- Result of evaluating an 'is' predicate.
- MemorySessionStore
- In-memory implementation of CommandSessionStore. Sessions live only for the lifetime of the store — callers that want persistence across process restarts should use a disk-backed store (not yet ported; Phase 6).
- NormalizedError
- Public, redacted error shape returned to SDK consumers and CLI output.
- PathResolutionOptions
- Options for path resolution.
- Point
- A point in 2D space.
- Rect
- A rectangle defined by position and size.
- ReplayScriptMetadata
- Metadata extracted from the context header of a replay script.
- RetryAttemptContext
- Context information about a retry attempt.
- RetryPolicy
- Retry policy configuration.
- RetryTelemetryEvent
- Telemetry event from a retry operation.
- RunCmdResult
- Result of a process execution.
- RunnerResponse
-
JSON envelope returned by the runner:
{ok: bool, data|error: ...}. - Selector
- A single selector expression (one alternative in a chain).
- SelectorChain
- A chain of selectors (separated by ||).
- SelectorDiagnostics
- Diagnostic information about a selector match.
- SelectorResolution
- Result of resolving a selector chain to a single node.
- SelectorTerm
- A single key-value term in a selector.
- SessionAction
-
A single action within a replay script: a command with positional args,
flags, and metadata. Mirrors TypeScript's
SessionAction. - SessionRuntimeHints
- Runtime hints passed to commands (platform, metro config, launch URL, etc.). These shape how sessions are initialized.
- SnapshotNode
- Snapshot node with an attached reference string.
- SnapshotState
- Full snapshot state including metadata.
- SnapshotVisibility
- Visibility status of a snapshot.
- StatePaths
- Paths the CLI / daemon read and write under a state directory.
- SystemClock
- Real-wall-clock implementation.
- TestRecorder
- Records video of a test session and injects chapter markers.
- TimeoutProfile
- Profile for timeout bounds (startup + operation phases).
- VideoChapter
Enums
- AgentDeviceBackendPlatform
- Supported platform identifiers for backend implementations.
- BackendAlertAction
- Alert action type.
- BackendAppListFilter
- Filter for app listing.
- BackendCapabilityName
- Known backend capability names that may be reported by a backend.
- BackendDeviceOrientation
- Possible device orientations.
- BackendNetworkIncludeMode
- Network activity detail level.
- DiagnosticLevel
- Diagnostic event severity level.
- PlatformSelector
-
Known platform targets. Mirror of TypeScript's
Platform | 'apple'. - SnapshotVisibilityReason
- Reason why snapshot visibility is partial.
Constants
- packageVersion → const String
Properties
- logger → Logger
-
The package-wide logger instance.
no setter
-
timeoutProfiles
→ Map<
String, TimeoutProfile> -
Built-in timeout profiles for common operations.
final
Functions
-
appendOpenActionScriptArgs(
List< String> parts, SessionAction action) → void -
Append open action script args to
partsbased onaction. -
asAppError(
Object? err) → AppError -
Coerces any thrown value into an AppError. Existing AppErrors pass
through; other Exception/Error instances become
UNKNOWNwith their originaltoString()as the message. -
buildSelectorChainForNode(
SnapshotNode node, String platform, {String? action}) → List< String> - Build selector chain alternatives for a node.
-
centerOfRect(
Rect rect) → Point - Calculate the center point of a rectangle.
-
createMemorySessionStore(
[Iterable< CommandSessionRecord> initial = const []]) → CommandSessionStore -
Convenience factory mirroring the TS
createMemorySessionStore. -
createRequestId(
) → String - Generates a request ID using cryptographically secure randomness.
-
decodePng(
List< int> buffer, String label) → Image - Decode a PNG from a buffer.
-
defaultHintForCode(
String code) → String? -
Default hint string for
code, or null when no default applies. -
emitDiagnostic(
EmitDiagnosticOptions options) → void - Emits a diagnostic event to the current scope.
-
evaluateIsPredicate(
{required String predicate, required SnapshotNode node, required List< SnapshotNode> nodes, String? expectedText, required String platform}) → IsPredicateResult - Evaluate an 'is' predicate against a node.
-
expandUserHomePath(
String inputPath, [PathResolutionOptions? options]) → String -
Expands the tilde (
~) prefix in a path to the user's home directory. -
findSelectorChainMatch(
List< SnapshotNode> nodes, SelectorChain chain, {required String platform, bool requireRect = false}) → ({List<SelectorDiagnostics> diagnostics, int matches, Selector selector, int selectorIndex})? - Find the first matching selector in a chain (without uniqueness requirement).
-
flushDiagnosticsToSessionFile(
{bool force = false}) → String? - Flushes accumulated diagnostic events to a session-specific log file.
-
formatReplayActionLine(
SessionAction action) → String - Format a replay action back into a script line.
-
formatScriptActionSummary(
SessionAction action) → String -
Format an action as a one-line summary:
command arg1 arg2 .... -
formatScriptArg(
String value) → String - Format a script argument, quoting as needed if it contains special chars.
-
formatScriptArgQuoteIfNeeded(
String value) → String - Format a script argument, only quoting if needed (readable for ordinary tokens).
-
formatScriptStringLiteral(
String value) → String - Format a string literal (always quoted for JSON-safe round-trip).
-
formatSelectorFailure(
SelectorChain chain, List< SelectorDiagnostics> diagnostics, {bool unique = true}) → String - Format a failure message for selector resolution.
-
getDiagnosticsMeta(
) → DiagnosticsMetadata - Returns metadata about the current diagnostics scope, or an empty object if no scope is active.
-
hasBackendCapability(
Backend backend, BackendCapabilityName capability) → bool - Check if a backend has a capability.
-
initLogger(
{required bool verbose}) → void - Initialise the logger. Call once at startup.
-
injectMp4Chapters(
String mp4Path, List< VideoChapter> chapters) → Future<String> -
Inject chapter metadata into an MP4 file using ffmpeg.
Returns the output path (same as
mp4Path— modified in place via a tmp file swap). No-ops gracefully if ffmpeg is not installed. -
isAgentDeviceError(
Object? err) → bool -
True if
erris an AppError. -
isApplePlatform(
PlatformSelector platform) → bool - True if the platform is an Apple platform (iOS or macOS).
-
isClickLikeCommand(
String command) → bool -
True if
commandis a click-like command ('click' or 'press'). -
isEnvTruthy(
String? value) → bool - Returns true if an environment variable is truthy.
-
isNodeEditable(
SnapshotNode node, String platform) → bool - Check if a node is editable (fillable type and not disabled) on a given platform.
-
isNodeVisible(
SnapshotNode node) → bool - Check if a node is visible (hittable or has a positive rect).
-
isSelectorToken(
String token) → bool - Check if a token is a valid selector token.
-
isSupportedPredicate(
String input) → bool - Check if a predicate is supported.
-
matchesSelector(
SnapshotNode node, Selector selector, String platform) → bool - Check if a node matches all terms in a selector.
-
normalizeAgentDeviceError(
Object? err, {String? diagnosticId, String? logPath}) → NormalizedError - Back-compat alias for normalizeError exposed under the longer public name.
-
normalizeError(
Object? err, {String? diagnosticId, String? logPath}) → NormalizedError -
Converts
errinto a NormalizedError with redacted details, a hint (explicit → detail-provided → code-default), and propagated diagnostic metadata. Matches the Node implementation's behavior including theCOMMAND_FAILEDstderr-excerpt enrichment. -
parsePlatformSelector(
String? value) → PlatformSelector? - Parse a string to PlatformSelector, or null if not recognized.
-
parseReplayOpenFlags(
List< String> args) → ({Map<String, Object?> flags, List<String> positionals, SessionRuntimeHints? runtime}) -
Parse open action flags from
args. Returns a tuple of (positionals, flags, runtime). -
parseReplayScript(
String script) → List< SessionAction> - Parse a replay script string into a list of SessionActions. Comments, blank lines, env directives, and context headers are skipped. Throws on misplaced env directives (must precede actions).
-
parseSelectorChain(
String expression) → SelectorChain - Parse a selector expression into a chain of alternatives.
-
platformSelectorToString(
PlatformSelector platform) → String - Convert a PlatformSelector to its string representation.
-
readReplayScriptMetadata(
String script) → ReplayScriptMetadata -
Read metadata from the leading context header + env directives in
script. The leading context line carries platform/timeout/retries kvs; standaloneenv KEY=VALUElines populate the env map. We scan the whole prelude (env directives can be interleaved with comments before the context line) but stop at the first non-comment, non-context, non-env line. -
resizePngFileToMaxSize(
String filePath, int maxSize) → Future< void> - Resize a PNG file to fit within a maximum dimension.
-
resolveExecutableOverridePath(
String? rawPath, String envName) → Future< String?> - Resolve an executable path override from an environment variable.
-
resolveFileOverridePath(
String? rawPath, String envName) → Future< String?> - Resolve a file path override from an environment variable.
-
resolveHomeDirectory(
[EnvMap? env]) → String - Resolves the home directory from the environment.
-
resolveSelectorChain(
List< SnapshotNode> nodes, SelectorChain chain, {required String platform, bool requireRect = false, bool requireUnique = true, bool disambiguateAmbiguous = false}) → SelectorResolution? - Resolve a selector chain to a single node with options.
-
resolveStatePaths(
[String? stateDir]) → StatePaths - Resolve the runtime state directory. Priority:
-
resolveTimeoutMs(
String? raw, int fallback, int min) → int - Parses a timeout string (typically from environment variables or CLI args).
-
resolveTimeoutSeconds(
String? raw, int fallback, int min) → int - Alias for resolveTimeoutMs — semantically marks the caller expects seconds. Internally works with milliseconds like resolveTimeoutMs.
-
resolveUserPath(
String inputPath, [PathResolutionOptions? options]) → String - Resolves a user-provided path to an absolute path.
-
retryWithPolicy<
T> (Future< T> fn(RetryAttemptContext context), RetryPolicy? policy, {Deadline? deadline, String? phase, CancelToken? signal, String classifyReason(Object error)?, void onEvent(RetryTelemetryEvent event)?}) → Future<T> - Retries an async operation with exponential backoff.
-
runCmd(
String cmd, List< String> args, [ExecOptions options = const ExecOptions()]) → Future<RunCmdResult> - Asynchronously run a command with the given arguments.
-
runCmdBackground(
String cmd, List< String> args, [ExecOptions options = const ExecOptions()]) → Future<ExecBackgroundResult> -
Spawn
cmdwithargsas a long-lived background process. -
runCmdDetached(
String cmd, List< String> args, [ExecDetachedOptions options = const ExecDetachedOptions()]) → Future<Process> -
Spawn
cmdwithargsdetached from the parent process. -
runCmdStreaming(
String cmd, List< String> args, [ExecStreamOptions options = const ExecStreamOptions()]) → Future<RunCmdResult> - Run a command with streaming stdout/stderr callbacks.
-
runCmdSync(
String cmd, List< String> args, [ExecOptions options = const ExecOptions()]) → RunCmdResult - Synchronously run a command with the given arguments.
-
serializeReplayScript(
List< SessionAction> actions, {String? contextLine}) → String -
Serialize a list of SessionActions back into a replay script string.
If
sessionis provided, includes a context header line. TODO(port): session parameter is not ported (SessionState is huge); callers construct the context line themselves if needed. -
sleep(
Duration duration) → Future< void> -
Pauses execution for
msmilliseconds. -
splitIsSelectorArgs(
List< String> positionals) → ({String predicate, ({List<String> rest, String selectorExpression})? split}) - Split arguments for an 'is' predicate.
-
splitSelectorFromArgs(
List< String> args, {bool preferTrailingValue = false}) → ({List<String> rest, String selectorExpression})? - Split selector from remaining arguments.
-
toAppErrorCode(
String? code, {String fallback = AppErrorCodes.commandFailed}) → String - Accepts any string so daemon-provided codes pass through. Use AppErrorCodes constants for the known set.
-
tryParseSelectorChain(
String expression) → SelectorChain? - Try to parse a selector chain, returning null on error.
-
whichCmd(
String cmd) → Future< bool> - Check whether a command exists in PATH.
-
withDiagnosticsScope<
T> (DiagnosticsScopeOptions options, Future< T> fn()) → Future<T> -
Executes
fnwithin a diagnostics scope with the givenoptions. -
withDiagnosticTimer<
T> (String phase, Future< T> fn(), [Map<String, Object?> ? data]) → Future<T> -
Executes
fnand emits a diagnostic event with timing information. -
withRetry<
T> (Future< T> fn(), {int? attempts, int? baseDelayMs, int? maxDelayMs, double? jitter, bool shouldRetry(Object error, int attempt)?}) → Future<T> - Retries an async operation with default backoff strategy.
Typedefs
- BackendActionResult = Object?
- Result type for generic actions (may be void or a map of properties).
-
BackendCapabilitySet
= List<
BackendCapabilityName> - A set of capability names that a backend reports as supported.
-
EnvMap
= Map<
String, String?> - IsPredicate = String
- Supported predicates for 'is' assertions.