android-midscene-automation 0.2.4 → 1.1.0

package/artemis-main/packages/artemis-accessibility-helper/app/src/main/java/com/artemis/helper/TokenReceiver.java

@@ -0,0 +1,36 @@
+package com.artemis.helper;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.util.Log;
+
+/**
+ * Receives the host's session token.
+ *
+ * The receiver is guarded in the manifest by
+ * {@code android.permission.WRITE_SECURE_SETTINGS}, a permission ordinary apps
+ * cannot hold but the adb shell user does, so only something with adb access to
+ * the device can set (or clear) the token:
+ *
+ * <pre>
+ * adb shell am broadcast -n com.artemis.helper/.TokenReceiver \
+ *     -a com.artemis.helper.SET_TOKEN --es token &lt;hex&gt;
+ * </pre>
+ */
+public class TokenReceiver extends BroadcastReceiver {
+
+    private static final String TAG = "ArtemisTokenReceiver";
+    public static final String ACTION_SET_TOKEN = "com.artemis.helper.SET_TOKEN";
+    public static final String EXTRA_TOKEN = "token";
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        if (intent == null || !ACTION_SET_TOKEN.equals(intent.getAction())) {
+            return;
+        }
+        String value = intent.getStringExtra(EXTRA_TOKEN);
+        TokenStore.set(value);
+        Log.i(TAG, TokenStore.isSet() ? "Session token set" : "Session token cleared");
+    }
+}

package/artemis-main/packages/artemis-accessibility-helper/app/src/main/java/com/artemis/helper/TokenStore.java

@@ -0,0 +1,38 @@
+package com.artemis.helper;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+
+/**
+ * The session token the host pushed for this process lifetime.
+ *
+ * The loopback server is reachable by every app on the device, so requests are
+ * only served when they carry this token. It lives in memory only: a killed or
+ * re-bound service starts without one and answers 401 until the host pushes it
+ * again (which the host does on every attach and on every 401).
+ */
+public final class TokenStore {
+
+    private static volatile String token;
+
+    private TokenStore() {}
+
+    public static void set(String value) {
+        token = (value == null || value.isEmpty()) ? null : value;
+    }
+
+    public static boolean isSet() {
+        return token != null;
+    }
+
+    /** Constant-time comparison so a local app cannot guess the token byte by byte. */
+    public static boolean matches(String candidate) {
+        String current = token;
+        if (current == null || candidate == null) {
+            return false;
+        }
+        return MessageDigest.isEqual(
+                current.getBytes(StandardCharsets.UTF_8),
+                candidate.getBytes(StandardCharsets.UTF_8));
+    }
+}

package/artemis-main/packages/artemis-accessibility-helper/app/src/main/java/com/artemis/helper/XmlUtils.java

@@ -0,0 +1,102 @@
+package com.artemis.helper;
+
+/**
+ * High-performance XML serialization and character sanitization utilities.
+ * Ensures the output strictly conforms to the W3C XML 1.0 specification,
+ * preventing XML parsing errors (such as ET.ParseError in Python) caused by
+ * unprintable control characters, NUL bytes, or unescaped entities.
+ */
+public final class XmlUtils {
+
+    private XmlUtils() {}
+
+    /**
+     * Appends an escaped attribute to the StringBuilder: {@code name="value"}.
+     * If the value is null or empty, appends {@code name=""}.
+     */
+    public static void appendAttribute(StringBuilder sb, String name, CharSequence value) {
+        sb.append(' ').append(name).append("=\"");
+        if (value != null && value.length() > 0) {
+            escapeXmlAttr(sb, value);
+        }
+        sb.append('"');
+    }
+
+    /**
+     * Appends a boolean attribute: {@code name="true"} or {@code name="false"}.
+     */
+    public static void appendBooleanAttribute(StringBuilder sb, String name, boolean value) {
+        sb.append(' ').append(name).append(value ? "=\"true\"" : "=\"false\"");
+    }
+
+    /**
+     * Appends an integer attribute: {@code name="123"}.
+     */
+    public static void appendIntAttribute(StringBuilder sb, String name, int value) {
+        sb.append(' ').append(name).append("=\"").append(value).append('"');
+    }
+
+    /**
+     * Escapes and sanitizes an attribute value according to XML 1.0 rules.
+     * Drops illegal XML characters (e.g. ASCII control characters 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F)
+     * and escapes standard entities (&, <, >, ", ').
+     */
+    public static void escapeXmlAttr(StringBuilder sb, CharSequence text) {
+        final int len = text.length();
+        for (int i = 0; i < len; i++) {
+            char c = text.charAt(i);
+            switch (c) {
+                case '&':
+                    sb.append("&amp;");
+                    break;
+                case '<':
+                    sb.append("&lt;");
+                    break;
+                case '>':
+                    sb.append("&gt;");
+                    break;
+                case '"':
+                    sb.append("&quot;");
+                    break;
+                case '\'':
+                    sb.append("&apos;");
+                    break;
+                case '\t':
+                    sb.append("&#9;");
+                    break;
+                case '\n':
+                    sb.append("&#10;");
+                    break;
+                case '\r':
+                    sb.append("&#13;");
+                    break;
+                default:
+                    // XML 1.0 legal character range check:
+                    // #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
+                    if (c >= 0x20 && c <= 0xD7FF) {
+                        sb.append(c);
+                    } else if (c >= 0xE000 && c <= 0xFFFD) {
+                        sb.append(c);
+                    } else if (Character.isHighSurrogate(c)) {
+                        if (i + 1 < len && Character.isLowSurrogate(text.charAt(i + 1))) {
+                            sb.append(c).append(text.charAt(i + 1));
+                            i++;
+                        }
+                    }
+                    // Characters outside these ranges (e.g. \u0000 through \u0008, \u000B, \u000C, \u000E-\u001F,
+                    // unpaired surrogates, \uFFFE, \uFFFF) are invalid XML 1.0 and silently omitted to guarantee well-formedness.
+                    break;
+            }
+        }
+    }
+
+    /**
+     * Sanitizes a string for safe XML attribute inclusion, returning the escaped string.
+     */
+    public static String escapeXmlAttr(CharSequence text) {
+        if (text == null || text.length() == 0) return "";
+        StringBuilder sb = new StringBuilder(text.length() + 16);
+        escapeXmlAttr(sb, text);
+        return sb.toString();
+    }
+}

package/artemis-main/packages/artemis-accessibility-helper/app/src/main/res/values/strings.xml

@@ -0,0 +1,4 @@
+<resources>
+    <string name="app_name">Artemis Accessibility Helper</string>
+    <string name="accessibility_service_description">Lightweight non-exclusive accessibility helper for Artemis UI automation and testing.</string>
+</resources>

package/artemis-main/packages/artemis-accessibility-helper/app/src/main/res/xml/accessibility_service_config.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
+    android:accessibilityEventTypes="typeWindowStateChanged"
+    android:accessibilityFeedbackType="feedbackGeneric"
+    android:notificationTimeout="100"
+    android:accessibilityFlags="flagDefault|flagRetrieveInteractiveWindows|flagReportViewIds"
+    android:canRetrieveWindowContent="true"
+    android:canPerformGestures="true"
+    android:canTakeScreenshot="true"
+    android:description="@string/accessibility_service_description" />

package/artemis-main/packages/artemis-accessibility-helper/build.gradle.kts

@@ -0,0 +1,3 @@
+plugins {
+    id("com.android.application") version "8.5.0" apply false
+}

package/artemis-main/packages/artemis-accessibility-helper/build_apk.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Standalone build for ArtemisAccessibilityHelper.apk (no Gradle daemon).
+#
+# Outputs, next to this script:
+#   ArtemisAccessibilityHelper.apk   the signed, zipaligned artifact
+#   helper_manifest.json             {version_code, version_name, sha256, built_at}
+#
+# The Python runtime (artemis/runtime/helper_manager.py) reads helper_manifest.json
+# to decide whether a device needs an install or an upgrade, so the manifest must
+# always be regenerated together with the APK. The version is sourced from
+# app/build.gradle.kts (defaultConfig.versionCode / versionName) so the Gradle
+# build and this script cannot drift.
+set -e
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$DIR"
+
+_to_posix() {
+    if command -v cygpath >/dev/null 2>&1; then
+        cygpath -u "$1"
+    else
+        printf '%s' "$1"
+    fi
+}
+
+# 1. Locate Android SDK
+SDK_ROOT="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-}}"
+if [ -n "$SDK_ROOT" ]; then
+    SDK_ROOT="$(_to_posix "$SDK_ROOT")"
+fi
+if [ -z "$SDK_ROOT" ] || [ ! -d "$SDK_ROOT" ]; then
+    for candidate in \
+        "$HOME/Library/Android/sdk" \
+        "$HOME/Android/Sdk" \
+        /opt/android-sdk \
+        /usr/local/share/android-sdk \
+        "$( [ -n "$LOCALAPPDATA" ] && _to_posix "$LOCALAPPDATA/Android/Sdk" )"; do
+        if [ -n "$candidate" ] && [ -d "$candidate" ]; then
+            SDK_ROOT="$candidate"
+            break
+        fi
+    done
+fi
+
+if [ -z "$SDK_ROOT" ] || [ ! -d "$SDK_ROOT" ]; then
+    echo "Error: Android SDK not found. Set ANDROID_HOME." >&2
+    exit 1
+fi
+
+BUILD_TOOLS="$(find "$SDK_ROOT/build-tools" -maxdepth 1 -mindepth 1 | sort -V | tail -n 1)"
+PLATFORM="$(find "$SDK_ROOT/platforms" -maxdepth 1 -mindepth 1 | sort -V | tail -n 1)"
+
+if [ -z "$BUILD_TOOLS" ] || [ ! -d "$BUILD_TOOLS" ]; then
+    echo "Error: No build-tools found under $SDK_ROOT/build-tools" >&2
+    exit 1
+fi
+
+if [ -z "$PLATFORM" ] || [ ! -f "$PLATFORM/android.jar" ]; then
+    echo "Error: android.jar not found under $SDK_ROOT/platforms" >&2
+    exit 1
+fi
+
+# 2. Locate Java compiler and runtime
+if [ -z "$JAVA_HOME" ]; then
+    for candidate in \
+        "/Applications/Android Studio.app/Contents/jbr/Contents/Home" \
+        "$(_to_posix "${PROGRAMFILES:-/c/Program Files}/Android/Android Studio/jbr")" \
+        "/opt/android-studio/jbr"; do
+        if [ -n "$candidate" ] && [ -x "$candidate/bin/javac" ] || [ -x "$candidate/bin/javac.exe" ]; then
+            export JAVA_HOME="$candidate"
+            break
+        fi
+    done
+fi
+if [ -n "$JAVA_HOME" ]; then
+    export PATH="$JAVA_HOME/bin:$PATH"
+fi
+
+if ! command -v javac >/dev/null 2>&1; then
+    echo "Error: javac not found in PATH or JAVA_HOME" >&2
+    exit 1
+fi
+
+PYTHON_BIN="${PYTHON:-}"
+if [ -z "$PYTHON_BIN" ]; then
+    # The Windows Store "python" stub is on PATH but exits 49; prefer the project venv.
+    for candidate in "$DIR/../../.venv/Scripts/python.exe" "$DIR/../../.venv/bin/python" python3 python; do
+        if "$candidate" -c "import zipfile" >/dev/null 2>&1; then
+            PYTHON_BIN="$candidate"
+            break
+        fi
+    done
+fi
+if [ -z "$PYTHON_BIN" ]; then
+    echo "Error: python3 not found (needed to package the DEX and write helper_manifest.json)" >&2
+    exit 1
+fi
+
+# Build-tools ship as .exe / .bat wrappers on Windows; resolve the right name once.
+_tool() {
+    local base="$BUILD_TOOLS/$1"
+    for suffix in "" ".exe" ".bat"; do
+        if [ -f "$base$suffix" ]; then
+            printf '%s' "$base$suffix"
+            return 0
+        fi
+    done
+    echo "Error: $1 not found under $BUILD_TOOLS" >&2
+    exit 1
+}
+AAPT2="$(_tool aapt2)"
+D8="$(_tool d8)"
+ZIPALIGN="$(_tool zipalign)"
+APKSIGNER="$(_tool apksigner)"
+
+# 3. Version: single source is app/build.gradle.kts
+VERSION_CODE="$(sed -n 's/^[[:space:]]*versionCode[[:space:]]*=[[:space:]]*\([0-9][0-9]*\).*/\1/p' app/build.gradle.kts | head -n 1)"
+VERSION_NAME="$(sed -n 's/^[[:space:]]*versionName[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' app/build.gradle.kts | head -n 1)"
+if [ -z "$VERSION_CODE" ] || [ -z "$VERSION_NAME" ]; then
+    echo "Error: could not read versionCode / versionName from app/build.gradle.kts" >&2
+    exit 1
+fi
+
+echo "=================================================="
+echo " Building ArtemisAccessibilityHelper.apk"
+echo " Version:     $VERSION_NAME (code $VERSION_CODE)"
+echo " Build Tools: $(basename "$BUILD_TOOLS")"
+echo " Platform:    $(basename "$PLATFORM")"
+echo " Java:        $(javac -version 2>&1)"
+echo "=================================================="
+
+rm -rf build
+mkdir -p build/gen build/obj build/apk build/res_compiled
+
+echo "-> Compiling resources..."
+"$AAPT2" compile --dir app/src/main/res -o build/res_compiled/res.zip
+
+echo "-> Linking APK..."
+"$AAPT2" link \
+    -I "$PLATFORM/android.jar" \
+    --manifest app/src/main/AndroidManifest.xml \
+    --min-sdk-version 24 \
+    --target-sdk-version 35 \
+    --version-code "$VERSION_CODE" \
+    --version-name "$VERSION_NAME" \
+    --java build/gen \
+    -o build/apk/unaligned.apk \
+    build/res_compiled/res.zip
+
+echo "-> Compiling Java sources..."
+JAVA_FILES="$(find build/gen app/src/main/java -name "*.java")"
+javac -encoding UTF-8 \
+    -source 8 -target 8 \
+    -Xlint:-options \
+    -cp "$PLATFORM/android.jar" \
+    -d build/obj \
+    $JAVA_FILES
+
+echo "-> Dexing with D8..."
+CLASS_FILES="$(find build/obj -name "*.class")"
+"$D8" \
+    --lib "$PLATFORM/android.jar" \
+    --output build/apk/ \
+    --min-api 24 \
+    $CLASS_FILES
+
+echo "-> Packaging DEX..."
+"$PYTHON_BIN" - <<'PY'
+import zipfile
+with zipfile.ZipFile("build/apk/unaligned.apk", "a", compression=zipfile.ZIP_DEFLATED) as apk:
+    apk.write("build/apk/classes.dex", "classes.dex")
+PY
+
+echo "-> Zipaligning..."
+"$ZIPALIGN" -f -p 4 build/apk/unaligned.apk build/apk/aligned.apk
+
+echo "-> Signing APK..."
+if [ ! -f debug.keystore ]; then
+    echo "Creating persistent debug.keystore..."
+    keytool -genkey -v -keystore debug.keystore \
+        -storepass android -alias androiddebugkey -keypass android \
+        -keyalg RSA -keysize 2048 -validity 10000 \
+        -dname "CN=Artemis Debug,O=Artemis,C=US"
+fi
+
+"$APKSIGNER" sign \
+    --ks debug.keystore \
+    --ks-pass pass:android \
+    --key-pass pass:android \
+    --ks-key-alias androiddebugkey \
+    --out ArtemisAccessibilityHelper.apk \
+    build/apk/aligned.apk
+
+echo "-> Writing helper_manifest.json..."
+VERSION_CODE="$VERSION_CODE" VERSION_NAME="$VERSION_NAME" "$PYTHON_BIN" - <<'PY'
+import datetime, hashlib, json, os
+digest = hashlib.sha256(open("ArtemisAccessibilityHelper.apk", "rb").read()).hexdigest()
+manifest = {
+    "package": "com.artemis.helper",
+    "version_code": int(os.environ["VERSION_CODE"]),
+    "version_name": os.environ["VERSION_NAME"],
+    "sha256": digest,
+    "built_at": datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0).isoformat(),
+}
+with open("helper_manifest.json", "w", encoding="utf-8", newline="\n") as fh:
+    json.dump(manifest, fh, indent=2)
+    fh.write("\n")
+print(json.dumps(manifest, indent=2))
+PY
+
+echo "=================================================="
+echo " Build SUCCESSFUL!"
+echo " Artifact: $DIR/ArtemisAccessibilityHelper.apk"
+ls -lh ArtemisAccessibilityHelper.apk
+echo "=================================================="

package/artemis-main/packages/artemis-accessibility-helper/gradle.properties

@@ -0,0 +1,2 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true

package/artemis-main/packages/artemis-accessibility-helper/helper_manifest.json

@@ -0,0 +1,7 @@
+{
+  "package": "com.artemis.helper",
+  "version_code": 6,
+  "version_name": "1.2.0",
+  "sha256": "133e373fe03615c251cd74b03a38539c844d09a074954bca2d2dde6684561969",
+  "built_at": "2026-09-10T23:13:11+00:00"
+}

package/artemis-main/packages/artemis-accessibility-helper/settings.gradle.kts

@@ -0,0 +1,17 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "artemis-accessibility-helper"
+include(":app")

package/artemis-main/packages/artemis-client/DESIGN.md

@@ -0,0 +1,89 @@
+# Artemis Thin Client Design
+
+## Goals
+
+Developer machines install only a small remote SDK, while the host connected to
+Android devices runs the full Artemis stack. The SDK must:
+
+- have no dependency on ADB, device drivers, agents, LLMs, web services, or image libraries;
+- never attempt to start a local Artemis daemon;
+- remain compatible with the existing server API;
+- allow the server to add agent and device capabilities independently; and
+- provide explicit capability negotiation and errors as the protocol evolves.
+
+## Boundary
+
+The client owns request modeling, HTTP communication, status polling, error
+normalization, and result models. Device discovery, task scheduling, concurrency
+control, model selection, execution, logs, videos, and artifact generation all
+belong to the server.
+
+The distribution is named `artemis-client`, while the Python import is
+`artemis_client`. This prevents it from shadowing the full runtime's top-level
+`artemis` package. The full runtime can depend on this package later and
+re-export the client from `artemis` for compatibility.
+
+## Phase 1: Compatibility Adapter
+
+The first release calls the current `/api/*` administration endpoints directly.
+The client generates a task ID and maps it to the server's existing `session_id`
+to make retries idempotent. While a task is queued but not yet visible in the
+session database, the client reconstructs its state from `queue` and
+`active_tasks` in `/api/status`.
+
+Experimental parameters live in `options`. Older servers ignore unknown fields,
+while newer servers can consume them without requiring an immediate SDK release.
+
+## Phase 2: Stable Remote API
+
+The server should expose versioned endpoints dedicated to remote clients:
+
+```text
+POST   /api/v1/tasks
+GET    /api/v1/tasks/{task_id}
+DELETE /api/v1/tasks/{task_id}
+GET    /api/v1/tasks/{task_id}/events
+GET    /api/v1/tasks/{task_id}/artifacts
+GET    /api/v1/devices
+GET    /api/v1/capabilities
+```
+
+The administration API and remote SDK API should remain separate. The remote API
+uses a consistent error envelope:
+
+```json
+{
+  "error": {
+    "code": "DEVICE_OFFLINE",
+    "message": "The selected device is offline",
+    "retryable": false
+  }
+}
+```
+
+## Compatibility Rules
+
+1. `/api/v1` may add optional request and response fields, but must not change existing field semantics.
+2. The client ignores unknown response fields and preserves the original response in each model's `raw` attribute.
+3. Every new request field must have a server-side default.
+4. The SDK checks `/api/v1/capabilities` before using a new feature.
+5. Breaking changes ship under `/api/v2`; they are never applied in place.
+6. The SDK and server follow semantic versioning independently.
+
+## Security
+
+The current daemon exposes administration and credential-related endpoints and
+must not listen on a public interface without protection. Use an SSH or VPN tunnel
+in the short term. In production, place a reverse proxy in front of the daemon,
+expose only the remote API, and enforce HTTPS, bearer-token authentication,
+request-size limits, rate limits, and audit logging. Tokens are accepted only
+through arguments or environment variables and are never persisted by the SDK.
+
+## Future Work
+
+- SSE event subscriptions with reconnection support;
+- artifact manifests and streaming downloads;
+- batch task submission;
+- server and API version constraints;
+- retries limited to network failures and idempotent requests; and
+- OpenAPI contract tests to prevent server and SDK drift.

package/artemis-main/packages/artemis-client/README.md

@@ -0,0 +1,112 @@
+# Artemis Client
+
+`artemis-client` is the remote Python SDK that runs on a developer machine. It
+communicates with the Artemis daemon on a device host over HTTP and contains no
+ADB, device-driver, agent, LLM, or image-processing code.
+
+Runtime dependencies: **zero**. HTTP, JSON, and asynchronous adapters use only
+the Python standard library.
+
+## Installation
+
+Install from a local checkout:
+
+```powershell
+uv add --editable C:\path\to\artemis\packages\artemis-client
+```
+
+Install from the Git repository subdirectory:
+
+```powershell
+uv add "artemis-client @ git+https://github.com/google/artemis.git#subdirectory=packages/artemis-client"
+```
+
+## Connect to a Device Host
+
+The current Artemis daemon administration API does not include built-in remote
+authentication. Do not expose its port directly to the public internet. During
+the initial rollout, connect through an SSH tunnel:
+
+```powershell
+ssh -L 8000:127.0.0.1:8000 user@artemis-host
+```
+
+Then connect the SDK to the local tunnel endpoint:
+
+```python
+from artemis_client import ArtemisClient
+
+client = ArtemisClient("http://127.0.0.1:8000")
+```
+
+For production, place a reverse proxy in front of the daemon that enforces HTTPS
+and bearer-token authentication and exposes only task-related APIs.
+
+## Usage
+
+```python
+import asyncio
+import os
+
+from artemis_client import ArtemisClient
+
+
+async def main() -> None:
+    client = ArtemisClient(
+        os.environ["ARTEMIS_BASE_URL"],
+        token=os.environ.get("ARTEMIS_TOKEN"),
+    )
+
+    handle = await client.submit(
+        "Open the Battery page in Settings and verify the battery percentage",
+        profile="flash",
+        device_serial="emulator-5554",
+    )
+    print("queued:", handle.task_id)
+
+    result = await client.wait_for_task(handle.task_id, timeout=600)
+    if not result.succeeded:
+        raise RuntimeError(result.error or result.status)
+
+
+asyncio.run(main())
+```
+
+You can also submit a task and wait for it in one call:
+
+```python
+result = await client.run("Open Android Settings and check the Wi-Fi status")
+```
+
+Main methods:
+
+- `health()` quickly checks whether the server and scheduler are alive.
+- `readiness()` runs full device and toolchain diagnostics and may take longer.
+- `capabilities()` negotiates API features and falls back for older servers.
+- `list_devices()` lists devices available on the host.
+- `submit()` submits an idempotent task and returns immediately.
+- `get_task()` retrieves a task.
+- `wait_for_task()` waits for a terminal state.
+- `run()` submits a task and waits for completion.
+- `stop()` stops one task.
+
+By default, `submit()` generates a UUID on the client and sends it as the current
+server's `session_id`. Network retries reuse the same `task_id`, preventing the
+server from creating duplicate tasks.
+
+## Compatibility
+
+Version 0.1 supports these current Artemis daemon endpoints:
+
+- `POST /api/run`
+- `GET /api/sessions/{session_id}`
+- `GET /api/status`
+- `POST /api/stop`
+- `GET /api/devices`
+- `GET /api/system/readiness`
+
+Capability discovery first attempts the future `GET /api/v1/capabilities`
+endpoint. If an older server returns 404, the SDK uses its known baseline
+capability set.
+
+See [DESIGN.md](DESIGN.md) for the architecture and protocol evolution plan.

package/artemis-main/packages/artemis-client/examples/basic.py

@@ -0,0 +1,30 @@
+"""Run one task against an Artemis host."""
+
+import asyncio
+import os
+
+from artemis_client import ArtemisClient
+
+
+async def main() -> None:
+    client = ArtemisClient(
+        os.environ.get("ARTEMIS_BASE_URL", "http://127.0.0.1:8000"),
+        token=os.environ.get("ARTEMIS_TOKEN"),
+    )
+
+    devices = await client.list_devices()
+    if not devices:
+        raise RuntimeError("The Artemis host did not report an Android device")
+
+    result = await client.run(
+        "Open the Battery page in Android Settings and verify the battery percentage.",
+        profile="flash",
+        device_serial=devices[0].serial,
+    )
+    if not result.succeeded:
+        raise RuntimeError(result.error or f"Task ended with status {result.status}")
+    print(f"Task {result.task_id} completed on {result.device_serial}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())