zeno-mobile-runner 0.1.3 → 0.2.0

package/clients/kotlin/README.md

@@ -27,7 +27,24 @@ gradle -p clients/kotlin runFakeSession \
 ```
 
 ```kotlin
-implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.1.3.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.0.jar"))
+```
+
+```kotlin
+val client = ZmrClient(listOf("zmr", "serve", "--transport", "stdio", "--config", ".zmr/config.json"))
+val out = ".zmr/discovered/kotlin-agent.json"
+val discovered = client.discoverTrace(
+    out,
+    TraceDiscoverOptions(includeActions = true, validate = true, force = true)
+)
+val explored = client.exploreTrace(
+    ".zmr/discovered/kotlin-goal.json",
+    "find a stable login smoke",
+    TraceDiscoverOptions(includeActions = true, validate = true, force = true)
+)
+val validation = client.validateScenario(out)
+val explanation = client.explainTrace()
+client.close()
 ```
 
 The Kotlin client is host-side. It is useful for Android teams that want test

package/clients/kotlin/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "dev.zmr"
-version = "0.1.3"
+version = "0.2.0"
 
 kotlin {
     jvmToolchain(17)

package/clients/kotlin/src/main/kotlin/dev/zmr/ZmrClient.kt

@@ -12,6 +12,14 @@ class ZmrRpcException(
     val publicCode: String? = null
 ) : RuntimeException(message)
 
+data class TraceDiscoverOptions(
+    val includeActions: Boolean = false,
+    val validate: Boolean = false,
+    val force: Boolean = false,
+    val name: String? = null,
+    val appId: String? = null
+)
+
 class ZmrClient(
     private val command: List<String> = listOf("zmr", "serve", "--transport", "stdio")
 ) : Closeable {
@@ -31,6 +39,34 @@ class ZmrClient(
         return call("assert.healthy", params)
     }
 
+    fun validateScenario(path: String): String =
+        call("scenario.validate", """{"path":"${escapeJson(path)}"}""")
+
+    fun explainTrace(): String = call("trace.explain")
+
+    fun discoverTrace(out: String, options: TraceDiscoverOptions = TraceDiscoverOptions()): String {
+        val fields = mutableListOf(""""out":"${escapeJson(out)}"""")
+        if (options.includeActions) fields.add(""""includeActions":true""")
+        if (options.validate) fields.add(""""validate":true""")
+        if (options.force) fields.add(""""force":true""")
+        options.name?.let { fields.add(""""name":"${escapeJson(it)}"""") }
+        options.appId?.let { fields.add(""""appId":"${escapeJson(it)}"""") }
+        return call("trace.discover", "{${fields.joinToString(",")}}")
+    }
+
+    fun exploreTrace(out: String, goal: String, options: TraceDiscoverOptions = TraceDiscoverOptions()): String {
+        val fields = mutableListOf(
+            """"out":"${escapeJson(out)}"""",
+            """"goal":"${escapeJson(goal)}""""
+        )
+        if (options.includeActions) fields.add(""""includeActions":true""")
+        if (options.validate) fields.add(""""validate":true""")
+        if (options.force) fields.add(""""force":true""")
+        options.name?.let { fields.add(""""name":"${escapeJson(it)}"""") }
+        options.appId?.let { fields.add(""""appId":"${escapeJson(it)}"""") }
+        return call("trace.explore", "{${fields.joinToString(",")}}")
+    }
+
     @Synchronized
     fun call(method: String, paramsJson: String? = null): String {
         val id = nextId++
@@ -39,7 +75,7 @@ class ZmrClient(
         input.newLine()
         input.flush()
         val response = output.readLine() ?: error("zmr closed stdout")
-        if (response.contains(""""error"""")) {
+        if (hasTopLevelKey(response, "error")) {
             throw ZmrRpcException(
                 code = extractNumber(response, "code") ?: -32000,
                 message = extractString(response, "message").ifEmpty { "ZMR JSON-RPC error" },
@@ -65,3 +101,42 @@ private fun extractNumber(json: String, key: String): Int? {
     val pattern = """"$key"\s*:\s*(-?[0-9]+)""".toRegex()
     return pattern.find(json)?.groupValues?.get(1)?.toIntOrNull()
 }
+
+private fun hasTopLevelKey(json: String, key: String): Boolean {
+    var depth = 0
+    var inString = false
+    var escaped = false
+    var stringStart = 0
+    var i = 0
+    while (i < json.length) {
+        val ch = json[i]
+        if (inString) {
+            when {
+                escaped -> escaped = false
+                ch == '\\' -> escaped = true
+                ch == '"' -> {
+                    inString = false
+                    if (depth == 1 && json.substring(stringStart, i) == key) {
+                        var j = i + 1
+                        while (j < json.length && json[j].isWhitespace()) j += 1
+                        if (j < json.length && json[j] == ':') return true
+                    }
+                }
+            }
+        } else {
+            when (ch) {
+                '"' -> {
+                    inString = true
+                    stringStart = i + 1
+                }
+                '{', '[' -> depth += 1
+                '}', ']' -> depth -= 1
+            }
+        }
+        i += 1
+    }
+    return false
+}
+
+private fun escapeJson(value: String): String =
+    value.replace("\\", "\\\\").replace("\"", "\\\"")

package/clients/python/README.md

@@ -20,8 +20,27 @@ with ZmrClient(
     zmr.wait_until({"text": "E2E auth probe"}, timeout_ms=30000)
     snapshot = zmr.snapshot()
     events = zmr.trace_events(0, limit=100)
+    explanation = zmr.explain_trace()
+    discovered = zmr.discover_trace(
+        ".zmr/discovered/agent-session.json",
+        include_actions=True,
+        validate=True,
+        force=True,
+    )
+    explored = zmr.explore_trace(
+        ".zmr/discovered/agent-goal.json",
+        "find a stable login smoke",
+        include_actions=True,
+        validate=True,
+        force=True,
+    )
+    validation = zmr.validate_scenario(discovered["out"])
     print(snapshot["nodes"])
     print(len(events["events"]))
+    print(explanation["status"])
+    print(discovered["out"])
+    print(explored["reviewRequired"])
+    print(validation["ok"])
     zmr.export_trace("traces/agent-session-redacted.zmrtrace", redact=True, omit_screenshots=True)
 ```
 

package/clients/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zmr-client"
-version = "0.1.3.dev1"
+version = "0.2.0.dev1"
 description = "Python JSON-RPC client for Zeno Mobile Runner."
 requires-python = ">=3.9"
 license = { text = "MIT" }

package/clients/python/zmr_client.py

@@ -160,6 +160,9 @@ class ZmrClient:
             params["timeoutMs"] = timeout_ms
         return self.request("assert.healthy", params)
 
+    def validate_scenario(self, path):
+        return self.request("scenario.validate", {"path": path})
+
     def export_trace(self, out, redact=False, omit_screenshots=False):
         return self.request(
             "trace.export",
@@ -176,6 +179,36 @@ class ZmrClient:
             params["limit"] = limit
         return self.request("trace.events", params)
 
+    def explain_trace(self):
+        return self.request("trace.explain")
+
+    def discover_trace(self, out, include_actions=False, validate=False, force=False, name=None, app_id=None):
+        params = {
+            "out": out,
+            "includeActions": include_actions,
+            "validate": validate,
+            "force": force,
+        }
+        if name is not None:
+            params["name"] = name
+        if app_id is not None:
+            params["appId"] = app_id
+        return self.request("trace.discover", params)
+
+    def explore_trace(self, out, goal, include_actions=False, validate=False, force=False, name=None, app_id=None):
+        params = {
+            "out": out,
+            "goal": goal,
+            "includeActions": include_actions,
+            "validate": validate,
+            "force": force,
+        }
+        if name is not None:
+            params["name"] = name
+        if app_id is not None:
+            params["appId"] = app_id
+        return self.request("trace.explore", params)
+
     def close(self):
         if self._closed:
             return

package/clients/rust/Cargo.lock

@@ -100,7 +100,7 @@ checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
 
 [[package]]
 name = "zmr-client"
-version = "0.1.3"
+version = "0.2.0"
 dependencies = [
  "serde",
  "serde_json",

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 license = "MIT"
 description = "Rust JSON-RPC client for Zeno Mobile Runner."

package/clients/rust/README.md

@@ -4,9 +4,33 @@ Small synchronous JSON-RPC client for driving `zmr serve --transport stdio`
 from Rust agents and test harnesses.
 
 ```rust
-let mut client = zmr_client::Client::start("zmr", ["serve", "--transport", "stdio"])?;
+let mut client = zmr_client::Client::start(
+    "zmr",
+    ["serve", "--transport", "stdio", "--config", ".zmr/config.json"],
+)?;
 let snapshot = client.snapshot()?;
 let healthy = client.assert_healthy(Some(1000))?;
+let explanation = client.explain_trace()?;
+let discovered = client.discover_trace(
+    ".zmr/discovered/rust-agent.json",
+    zmr_client::TraceDiscoverOptions {
+        include_actions: true,
+        validate: true,
+        force: true,
+        ..Default::default()
+    },
+)?;
+let explored = client.explore_trace(
+    ".zmr/discovered/rust-goal.json",
+    "find a stable login smoke",
+    zmr_client::TraceDiscoverOptions {
+        include_actions: true,
+        validate: true,
+        force: true,
+        ..Default::default()
+    },
+)?;
+let validation = client.validate_scenario(&discovered.out)?;
 ```
 
 Run the fake-session example from the repository root:

package/clients/rust/src/lib.rs

@@ -204,6 +204,150 @@ pub struct TraceEvents {
     pub events: Vec<Value>,
 }
 
+#[derive(Debug, Deserialize)]
+pub struct TraceDiagnostic {
+    pub kind: String,
+    #[serde(default)]
+    pub status: Option<String>,
+    #[serde(default, rename = "snapshotId")]
+    pub snapshot_id: Option<String>,
+    #[serde(default, rename = "artifactStatus")]
+    pub artifact_status: Option<String>,
+    #[serde(default, rename = "semanticStatus")]
+    pub semantic_status: Option<String>,
+    #[serde(default)]
+    pub error: Option<String>,
+    #[serde(default, rename = "screenshotArtifact")]
+    pub screenshot_artifact: Option<String>,
+    #[serde(default)]
+    pub source: Option<String>,
+    #[serde(default, rename = "activePackage")]
+    pub active_package: Option<String>,
+    #[serde(default, rename = "activeActivity")]
+    pub active_activity: Option<String>,
+    #[serde(default, rename = "visibleTexts")]
+    pub visible_texts: Vec<String>,
+    #[serde(default, rename = "nearestTextMatches")]
+    pub nearest_text_matches: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct TraceExplain {
+    pub ok: bool,
+    #[serde(rename = "traceDir")]
+    pub trace_dir: String,
+    pub scenario: String,
+    pub status: String,
+    #[serde(default, rename = "appId")]
+    pub app_id: Option<String>,
+    #[serde(default, rename = "durationMs")]
+    pub duration_ms: Option<i64>,
+    #[serde(default, rename = "eventCount")]
+    pub event_count: Option<i64>,
+    #[serde(default, rename = "snapshotCount")]
+    pub snapshot_count: Option<i64>,
+    #[serde(default, rename = "partialFailureCount")]
+    pub partial_failure_count: Option<i64>,
+    #[serde(default, rename = "failedStepIndex")]
+    pub failed_step_index: Option<i64>,
+    #[serde(default)]
+    pub error: Option<String>,
+    #[serde(default)]
+    pub diagnostic: Option<TraceDiagnostic>,
+    #[serde(default, rename = "partialFailure")]
+    pub partial_failure: Option<TraceDiagnostic>,
+    #[serde(default, rename = "lastEvent")]
+    pub last_event: Option<String>,
+    #[serde(default, rename = "nextCommands")]
+    pub next_commands: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ValidationResult {
+    pub ok: bool,
+    pub path: String,
+    #[serde(default)]
+    pub name: Option<String>,
+    #[serde(default, rename = "appId")]
+    pub app_id: Option<String>,
+    #[serde(default, rename = "stepCount")]
+    pub step_count: i64,
+    #[serde(default, rename = "errorCode")]
+    pub error_code: Option<String>,
+    #[serde(default)]
+    pub message: Option<String>,
+    #[serde(default, rename = "fieldPath")]
+    pub field_path: Option<String>,
+    #[serde(default)]
+    pub line: Option<i64>,
+    #[serde(default)]
+    pub column: Option<i64>,
+    #[serde(default, rename = "nextCommands")]
+    pub next_commands: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ReplaySummary {
+    #[serde(default)]
+    pub enabled: bool,
+    #[serde(default, rename = "eventCount")]
+    pub event_count: i64,
+    #[serde(default, rename = "stepCount")]
+    pub step_count: i64,
+    #[serde(default, rename = "skippedEventCount")]
+    pub skipped_event_count: i64,
+}
+
+#[derive(Debug, Default)]
+pub struct TraceDiscoverOptions {
+    pub include_actions: bool,
+    pub validate: bool,
+    pub force: bool,
+    pub name: Option<String>,
+    pub app_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct TraceDiscover {
+    pub ok: bool,
+    pub mode: String,
+    #[serde(rename = "schemaVersion")]
+    pub schema_version: i64,
+    #[serde(rename = "runnerVersion")]
+    pub runner_version: String,
+    #[serde(rename = "protocolVersion")]
+    pub protocol_version: String,
+    pub out: String,
+    #[serde(rename = "traceDir")]
+    pub trace_dir: String,
+    #[serde(rename = "sourceSnapshot")]
+    pub source_snapshot: String,
+    pub name: String,
+    #[serde(default, rename = "appId")]
+    pub app_id: Option<String>,
+    #[serde(rename = "selectorCount")]
+    pub selector_count: i64,
+    #[serde(rename = "stepCount")]
+    pub step_count: i64,
+    pub replay: ReplaySummary,
+    #[serde(default)]
+    pub warnings: Vec<String>,
+    #[serde(default)]
+    pub validated: bool,
+    #[serde(default)]
+    pub validation: Option<ValidationResult>,
+    #[serde(default, rename = "nextCommands")]
+    pub next_commands: Vec<String>,
+    #[serde(default)]
+    pub goal: Option<String>,
+    #[serde(default)]
+    pub autonomous: bool,
+    #[serde(default, rename = "reviewRequired")]
+    pub review_required: bool,
+    #[serde(default)]
+    pub guardrails: Vec<String>,
+}
+
 impl Client {
     pub fn start<I, S>(command: &str, args: I) -> Result<Self, Error>
     where
@@ -420,6 +564,10 @@ impl Client {
         self.request("assert.healthy", params)
     }
 
+    pub fn validate_scenario(&mut self, path: &str) -> Result<ValidationResult, Error> {
+        self.request("scenario.validate", json!({ "path": path }))
+    }
+
     pub fn export_trace(
         &mut self,
         out: &str,
@@ -443,6 +591,59 @@ impl Client {
         }
         self.request("trace.events", params)
     }
+
+    pub fn explain_trace(&mut self) -> Result<TraceExplain, Error> {
+        self.request("trace.explain", json!({}))
+    }
+
+    pub fn discover_trace(
+        &mut self,
+        out: &str,
+        options: TraceDiscoverOptions,
+    ) -> Result<TraceDiscover, Error> {
+        let mut params = json!({ "out": out });
+        if options.include_actions {
+            params["includeActions"] = json!(true);
+        }
+        if options.validate {
+            params["validate"] = json!(true);
+        }
+        if options.force {
+            params["force"] = json!(true);
+        }
+        if let Some(name) = options.name {
+            params["name"] = json!(name);
+        }
+        if let Some(app_id) = options.app_id {
+            params["appId"] = json!(app_id);
+        }
+        self.request("trace.discover", params)
+    }
+
+    pub fn explore_trace(
+        &mut self,
+        out: &str,
+        goal: &str,
+        options: TraceDiscoverOptions,
+    ) -> Result<TraceDiscover, Error> {
+        let mut params = json!({ "out": out, "goal": goal });
+        if options.include_actions {
+            params["includeActions"] = json!(true);
+        }
+        if options.validate {
+            params["validate"] = json!(true);
+        }
+        if options.force {
+            params["force"] = json!(true);
+        }
+        if let Some(name) = options.name {
+            params["name"] = json!(name);
+        }
+        if let Some(app_id) = options.app_id {
+            params["appId"] = json!(app_id);
+        }
+        self.request("trace.explore", params)
+    }
 }
 
 impl Drop for Client {

package/clients/swift/README.md

@@ -16,6 +16,24 @@ git submodule add https://github.com/johnmikel/zeno-mobile-runner.git vendor/zen
 
 Then depend on the `ZMRClient` product from `clients/swift`.
 
+```swift
+let client = ZMRClient(arguments: ["serve", "--transport", "stdio", "--config", ".zmr/config.json"])
+try client.start()
+let out = ".zmr/discovered/swift-agent.json"
+let discovered = try client.discoverTrace(
+    out: out,
+    options: TraceDiscoverOptions(includeActions: true, validate: true, force: true)
+)
+let explored = try client.exploreTrace(
+    out: ".zmr/discovered/swift-goal.json",
+    goal: "find a stable login smoke",
+    options: TraceDiscoverOptions(includeActions: true, validate: true, force: true)
+)
+let validation = try client.validateScenario(path: out)
+let explanation = try client.explainTrace()
+client.close()
+```
+
 Run the package test from this directory:
 
 ```bash

package/clients/swift/Sources/ZMRClient/ZMRClient.swift

@@ -6,6 +6,28 @@ public enum ZMRError: Error {
     case rpcError([String: Any])
 }
 
+public struct TraceDiscoverOptions {
+    public var includeActions: Bool
+    public var validate: Bool
+    public var force: Bool
+    public var name: String?
+    public var appId: String?
+
+    public init(
+        includeActions: Bool = false,
+        validate: Bool = false,
+        force: Bool = false,
+        name: String? = nil,
+        appId: String? = nil
+    ) {
+        self.includeActions = includeActions
+        self.validate = validate
+        self.force = force
+        self.name = name
+        self.appId = appId
+    }
+}
+
 public final class ZMRClient {
     private let process: Process
     private let input: FileHandle
@@ -98,6 +120,66 @@ public final class ZMRClient {
         return result
     }
 
+    public func validateScenario(path: String) throws -> [String: Any] {
+        guard let result = try call("scenario.validate", params: ["path": path]) as? [String: Any] else {
+            throw ZMRError.invalidResponse
+        }
+        return result
+    }
+
+    public func discoverTrace(out: String, options: TraceDiscoverOptions = TraceDiscoverOptions()) throws -> [String: Any] {
+        var params: [String: Any] = ["out": out]
+        if options.includeActions {
+            params["includeActions"] = true
+        }
+        if options.validate {
+            params["validate"] = true
+        }
+        if options.force {
+            params["force"] = true
+        }
+        if let name = options.name {
+            params["name"] = name
+        }
+        if let appId = options.appId {
+            params["appId"] = appId
+        }
+        guard let result = try call("trace.discover", params: params) as? [String: Any] else {
+            throw ZMRError.invalidResponse
+        }
+        return result
+    }
+
+    public func exploreTrace(out: String, goal: String, options: TraceDiscoverOptions = TraceDiscoverOptions()) throws -> [String: Any] {
+        var params: [String: Any] = ["out": out, "goal": goal]
+        if options.includeActions {
+            params["includeActions"] = true
+        }
+        if options.validate {
+            params["validate"] = true
+        }
+        if options.force {
+            params["force"] = true
+        }
+        if let name = options.name {
+            params["name"] = name
+        }
+        if let appId = options.appId {
+            params["appId"] = appId
+        }
+        guard let result = try call("trace.explore", params: params) as? [String: Any] else {
+            throw ZMRError.invalidResponse
+        }
+        return result
+    }
+
+    public func explainTrace() throws -> [String: Any] {
+        guard let result = try call("trace.explain", params: [:]) as? [String: Any] else {
+            throw ZMRError.invalidResponse
+        }
+        return result
+    }
+
     private func readLineData() throws -> Data {
         var data = Data()
         while true {

package/clients/typescript/README.md

@@ -22,8 +22,24 @@ try {
   await zmr.waitUntil({ text: "E2E auth probe" }, { timeoutMs: 30000 });
   const snapshot = await zmr.snapshot();
   const events = await zmr.traceEvents(0, { limit: 100 });
+  const explanation = await zmr.explainTrace();
+  const discovered = await zmr.discoverTrace(".zmr/discovered/agent-session.json", {
+    includeActions: true,
+    validate: true,
+    force: true,
+  });
+  const explored = await zmr.exploreTrace(".zmr/discovered/agent-goal.json", "find a stable login smoke", {
+    includeActions: true,
+    validate: true,
+    force: true,
+  });
+  const validation = await zmr.validateScenario(discovered.out);
   console.log(snapshot.nodes);
   console.log(events.events.length);
+  console.log(explanation.status);
+  console.log(discovered.out);
+  console.log(explored.reviewRequired);
+  console.log(validation.ok);
   await zmr.exportTrace("traces/agent-session-redacted.zmrtrace", { redact: true, omitScreenshots: true });
 } finally {
   await zmr.close();

package/clients/typescript/index.d.ts

@@ -99,6 +99,14 @@ export interface Capabilities {
   methods: string[];
 }
 
+export interface TraceDiscoverOptions {
+  includeActions?: boolean;
+  validate?: boolean;
+  force?: boolean;
+  name?: string;
+  appId?: string;
+}
+
 export interface DeviceInfo {
   serial: string;
   state: string;
@@ -130,8 +138,12 @@ export interface ZmrClient {
   assertVisible(selector: Selector, options?: { timeoutMs?: number }): Promise<boolean>;
   assertNotVisible(selector: Selector, options?: { timeoutMs?: number }): Promise<boolean>;
   assertHealthy(options?: { timeoutMs?: number }): Promise<boolean>;
+  validateScenario(path: string): Promise<Record<string, unknown>>;
   exportTrace(out: string, options?: { redact?: boolean; omitScreenshots?: boolean }): Promise<Record<string, unknown>>;
   traceEvents(afterSeq?: number, options?: { limit?: number }): Promise<Record<string, unknown>>;
+  explainTrace(): Promise<Record<string, unknown>>;
+  discoverTrace(out: string, options?: TraceDiscoverOptions): Promise<Record<string, unknown>>;
+  exploreTrace(out: string, goal: string, options?: TraceDiscoverOptions): Promise<Record<string, unknown>>;
   close(): Promise<void>;
 }