zeno-mobile-runner 0.1.2 → 0.1.8

package/clients/go/zmr/client.go

@@ -134,6 +134,39 @@ type TraceEvents struct {
 	Events    []map[string]interface{} `json:"events"`
 }
 
+type TraceDiagnostic struct {
+	Kind               string   `json:"kind"`
+	Status             string   `json:"status,omitempty"`
+	SnapshotID         string   `json:"snapshotId,omitempty"`
+	ArtifactStatus     string   `json:"artifactStatus,omitempty"`
+	SemanticStatus     string   `json:"semanticStatus,omitempty"`
+	Error              string   `json:"error,omitempty"`
+	ScreenshotArtifact string   `json:"screenshotArtifact,omitempty"`
+	Source             string   `json:"source,omitempty"`
+	ActivePackage      string   `json:"activePackage,omitempty"`
+	ActiveActivity     string   `json:"activeActivity,omitempty"`
+	VisibleTexts       []string `json:"visibleTexts,omitempty"`
+	NearestTextMatches []string `json:"nearestTextMatches,omitempty"`
+}
+
+type TraceExplain struct {
+	OK                  bool             `json:"ok"`
+	TraceDir            string           `json:"traceDir"`
+	Scenario            string           `json:"scenario"`
+	Status              string           `json:"status"`
+	AppID               string           `json:"appId,omitempty"`
+	DurationMS          int64            `json:"durationMs,omitempty"`
+	EventCount          int64            `json:"eventCount,omitempty"`
+	SnapshotCount       int64            `json:"snapshotCount,omitempty"`
+	PartialFailureCount int64            `json:"partialFailureCount,omitempty"`
+	FailedStepIndex     int64            `json:"failedStepIndex,omitempty"`
+	Error               string           `json:"error,omitempty"`
+	Diagnostic          *TraceDiagnostic `json:"diagnostic,omitempty"`
+	PartialFailure      *TraceDiagnostic `json:"partialFailure,omitempty"`
+	LastEvent           string           `json:"lastEvent,omitempty"`
+	NextCommands        []string         `json:"nextCommands"`
+}
+
 type TraceExport struct {
 	TraceDir        string `json:"traceDir"`
 	Out             string `json:"out"`
@@ -141,6 +174,59 @@ type TraceExport struct {
 	OmitScreenshots bool   `json:"omitScreenshots"`
 }
 
+type ValidationResult struct {
+	OK           bool     `json:"ok"`
+	Path         string   `json:"path"`
+	Name         string   `json:"name,omitempty"`
+	AppID        string   `json:"appId,omitempty"`
+	StepCount    int      `json:"stepCount,omitempty"`
+	ErrorCode    string   `json:"errorCode,omitempty"`
+	Message      string   `json:"message,omitempty"`
+	FieldPath    string   `json:"fieldPath,omitempty"`
+	Line         int      `json:"line,omitempty"`
+	Column       int      `json:"column,omitempty"`
+	NextCommands []string `json:"nextCommands,omitempty"`
+}
+
+type ReplaySummary struct {
+	Enabled           bool `json:"enabled"`
+	EventCount        int  `json:"eventCount"`
+	StepCount         int  `json:"stepCount"`
+	SkippedEventCount int  `json:"skippedEventCount"`
+}
+
+type TraceDiscoverOptions struct {
+	IncludeActions bool
+	Validate       bool
+	Force          bool
+	Name           string
+	AppID          string
+}
+
+type TraceDiscover struct {
+	OK              bool              `json:"ok"`
+	Mode            string            `json:"mode"`
+	SchemaVersion   int               `json:"schemaVersion"`
+	RunnerVersion   string            `json:"runnerVersion"`
+	ProtocolVersion string            `json:"protocolVersion"`
+	Out             string            `json:"out"`
+	TraceDir        string            `json:"traceDir"`
+	SourceSnapshot  string            `json:"sourceSnapshot"`
+	Name            string            `json:"name"`
+	AppID           string            `json:"appId,omitempty"`
+	SelectorCount   int               `json:"selectorCount"`
+	StepCount       int               `json:"stepCount"`
+	Replay          ReplaySummary     `json:"replay"`
+	Warnings        []string          `json:"warnings"`
+	Validated       bool              `json:"validated"`
+	Validation      *ValidationResult `json:"validation"`
+	NextCommands    []string          `json:"nextCommands"`
+	Goal            string            `json:"goal,omitempty"`
+	Autonomous      bool              `json:"autonomous,omitempty"`
+	ReviewRequired  bool              `json:"reviewRequired,omitempty"`
+	Guardrails      []string          `json:"guardrails,omitempty"`
+}
+
 func Start(ctx context.Context, command string, args ...string) (*Client, error) {
 	cmd := exec.CommandContext(ctx, command, args...)
 	stdin, err := cmd.StdinPipe()
@@ -415,6 +501,12 @@ func (c *Client) AssertHealthy(ctx context.Context, timeoutMS int64) (bool, erro
 	return out, err
 }
 
+func (c *Client) ValidateScenario(ctx context.Context, path string) (ValidationResult, error) {
+	var out ValidationResult
+	err := c.Request(ctx, "scenario.validate", map[string]interface{}{"path": path}, &out)
+	return out, err
+}
+
 func (c *Client) ExportTrace(ctx context.Context, outPath string, redact bool, omitScreenshots bool) (TraceExport, error) {
 	var out TraceExport
 	err := c.Request(ctx, "trace.export", map[string]interface{}{"out": outPath, "redact": redact, "omitScreenshots": omitScreenshots}, &out)
@@ -430,3 +522,53 @@ func (c *Client) TraceEvents(ctx context.Context, afterSeq int64, limit int64) (
 	err := c.Request(ctx, "trace.events", params, &out)
 	return out, err
 }
+
+func (c *Client) ExplainTrace(ctx context.Context) (TraceExplain, error) {
+	var out TraceExplain
+	err := c.Request(ctx, "trace.explain", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) DiscoverTrace(ctx context.Context, outPath string, options TraceDiscoverOptions) (TraceDiscover, error) {
+	var out TraceDiscover
+	params := map[string]interface{}{"out": outPath}
+	if options.IncludeActions {
+		params["includeActions"] = true
+	}
+	if options.Validate {
+		params["validate"] = true
+	}
+	if options.Force {
+		params["force"] = true
+	}
+	if options.Name != "" {
+		params["name"] = options.Name
+	}
+	if options.AppID != "" {
+		params["appId"] = options.AppID
+	}
+	err := c.Request(ctx, "trace.discover", params, &out)
+	return out, err
+}
+
+func (c *Client) ExploreTrace(ctx context.Context, outPath string, goal string, options TraceDiscoverOptions) (TraceDiscover, error) {
+	var out TraceDiscover
+	params := map[string]interface{}{"out": outPath, "goal": goal}
+	if options.IncludeActions {
+		params["includeActions"] = true
+	}
+	if options.Validate {
+		params["validate"] = true
+	}
+	if options.Force {
+		params["force"] = true
+	}
+	if options.Name != "" {
+		params["name"] = options.Name
+	}
+	if options.AppID != "" {
+		params["appId"] = options.AppID
+	}
+	err := c.Request(ctx, "trace.explore", params, &out)
+	return out, err
+}

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.2.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.1.8.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.2"
+version = "0.1.8"
 
 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.2.dev1"
+version = "0.1.8.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.2"
+version = "0.1.8"
 dependencies = [
  "serde",
  "serde_json",

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.1.2"
+version = "0.1.8"
 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