zig-mobile-runner 0.1.0

package/src/main.zig

@@ -0,0 +1,135 @@
+const std = @import("std");
+const cli_devices = @import("cli_devices.zig");
+const cli_doctor = @import("cli_doctor.zig");
+const cli_info = @import("cli_info.zig");
+const cli_init = @import("cli_init.zig");
+const cli_import = @import("cli_import.zig");
+const cli_run = @import("cli_run.zig");
+const cli_serve = @import("cli_serve.zig");
+const cli_trace = @import("cli_trace.zig");
+const cli_validate = @import("cli_validate.zig");
+const errors = @import("errors.zig");
+
+pub fn main() void {
+    mainInner() catch |err| {
+        writeTopLevelError(err);
+        std.process.exit(exitCodeForError(err));
+    };
+}
+
+fn mainInner() !void {
+    const GeneralAllocator = if (@hasDecl(std.heap, "GeneralPurposeAllocator"))
+        std.heap.GeneralPurposeAllocator
+    else
+        std.heap.DebugAllocator;
+    var gpa = GeneralAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    var args = try std.process.argsWithAllocator(allocator);
+    defer args.deinit();
+    _ = args.next();
+    const command_name = args.next() orelse {
+        try usage();
+        return;
+    };
+
+    if (std.mem.eql(u8, command_name, "devices")) {
+        try cli_devices.run(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "schemas")) {
+        try cli_info.runSchemas(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "doctor")) {
+        try cli_doctor.run(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "validate")) {
+        try cli_validate.run(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "init")) {
+        try cli_init.run(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "import")) {
+        try cli_import.run(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "run")) {
+        try cli_run.run(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "report")) {
+        try cli_trace.runReport(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "explain")) {
+        try cli_trace.runExplain(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "export")) {
+        try cli_trace.runExport(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "serve")) {
+        try cli_serve.runServe(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "mcp")) {
+        try cli_serve.runMcp(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "version") or std.mem.eql(u8, command_name, "--version")) {
+        try cli_info.runVersion(allocator, &args);
+    } else if (std.mem.eql(u8, command_name, "help") or std.mem.eql(u8, command_name, "--help")) {
+        try usage();
+    } else {
+        std.debug.print("unknown command: {s}\n\n", .{command_name});
+        try usage();
+        return error.UnknownCommand;
+    }
+}
+
+fn writeTopLevelError(err: anyerror) void {
+    const public = errors.classify(err);
+    const stderr = std.fs.File.stderr().deprecatedWriter();
+    stderr.print("error[{s}]: {s}\n", .{ public.code, public.message }) catch {};
+    if (err == error.CommandFailed) {
+        stderr.writeAll("hint: run `zmr doctor --json` for setup diagnostics.\n") catch {};
+    }
+}
+
+fn exitCodeForError(err: anyerror) u8 {
+    return switch (err) {
+        error.UnknownCommand,
+        error.UnknownFlag,
+        error.MissingScenarioPath,
+        error.MissingDeviceSerial,
+        error.MissingTraceDir,
+        error.MissingAppId,
+        error.MissingAdbPath,
+        error.MissingXcrunPath,
+        error.MissingZigPath,
+        error.MissingPlatform,
+        error.MissingIosDeviceType,
+        error.MissingParam,
+        error.UnsupportedPlatform,
+        error.UnsupportedIosDeviceType,
+        error.UnsupportedTransport,
+        => 2,
+        else => 1,
+    };
+}
+
+fn usage() !void {
+    const stdout = std.fs.File.stdout().deprecatedWriter();
+    try stdout.writeAll(
+        \\zmr - Zig Mobile Runner
+        \\
+        \\Commands:
+        \\  zmr version [--json]
+        \\  zmr schemas [--json]
+        \\  zmr devices [--json] [--platform android|ios] [--ios-device-type simulator|physical|all] [--adb <path>] [--xcrun <path>]
+        \\  zmr doctor [--json] [--strict] [--config <path>] [--zig <path>] [--adb <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\  zmr validate <scenario.json> [--json]
+        \\  zmr init [scenario.json] [--app-id <id>] [--force] [--json]
+        \\  zmr init --app [--dir <app-root>] [--app-id <id>] [--force] [--json]
+        \\  zmr import flow-yaml <flow.yaml> --out <scenario.json> [--name <name>] [--app-id <id>] [--force] [--json]
+        \\  zmr run [scenario.json] [--json] [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--android-avd <name>] [--create-avd-if-missing] [--avd-system-image <pkg>] [--avd-device <profile>] [--restore-snapshot <name>] [--reset-emulator] [--wait-emulator] [--screen-record] [--no-screen-record] [--adb <path>] [--emulator <path>] [--avdmanager <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\  zmr report <trace-or-benchmark-dir> --out <report.html>
+        \\  zmr explain <trace-dir> [--json]
+        \\  zmr export <trace-dir> --out <bundle.zmrtrace> [--redact] [--omit-screenshots]
+        \\  zmr serve --transport stdio [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--adb <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\  zmr serve --transport tcp [--port <port>] [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--adb <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\  zmr mcp [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--adb <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\
+        \\Scenario actions: launch, stop, clearState, openLink, tap, typeText,
+        \\eraseText, hideKeyboard, swipe, pressBack, waitVisible, waitNotVisible,
+        \\waitAny, whenVisible, repeat, scrollUntilVisible, assertVisible,
+        \\assertNotVisible, assertNoneVisible, assertHealthy, snapshot, sleep. Any step may use "optional": true.
+        \\
+    );
+}
+
+test {
+    _ = @import("test_harness.zig");
+}

package/src/mcp.zig

@@ -0,0 +1,234 @@
+const std = @import("std");
+const errors = @import("errors.zig");
+const mcp_protocol = @import("mcp_protocol.zig");
+const mcp_trace = @import("mcp_trace.zig");
+const runner = @import("runner.zig");
+const selector = @import("selector.zig");
+const semantic = @import("semantic.zig");
+const trace = @import("trace.zig");
+
+pub fn serveStdioWithTrace(allocator: std.mem.Allocator, device: anytype, live_trace: ?*trace.TraceWriter) !void {
+    var stdin = std.fs.File.stdin().deprecatedReader();
+    const stdout = std.fs.File.stdout().deprecatedWriter();
+
+    while (true) {
+        const line = stdin.readUntilDelimiterOrEofAlloc(allocator, '\n', 16 * 1024 * 1024) catch |err| {
+            try mcp_protocol.writeError(stdout, null, -32700, @errorName(err));
+            continue;
+        };
+        const owned_line = line orelse break;
+        defer allocator.free(owned_line);
+        const trimmed = std.mem.trim(u8, owned_line, " \t\r\n");
+        if (trimmed.len == 0) continue;
+        try dispatchLine(allocator, device, trimmed, stdout, live_trace);
+    }
+}
+
+fn dispatchLine(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    line: []const u8,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !void {
+    const parsed = std.json.parseFromSlice(std.json.Value, allocator, line, .{}) catch |err| {
+        try mcp_protocol.writeError(writer, null, -32700, @errorName(err));
+        return;
+    };
+    defer parsed.deinit();
+
+    if (parsed.value != .object) {
+        try mcp_protocol.writeError(writer, null, -32600, "request must be an object");
+        return;
+    }
+    const object = parsed.value.object;
+    const id = object.get("id");
+    const method_value = object.get("method") orelse {
+        try mcp_protocol.writeError(writer, id, -32600, "missing method");
+        return;
+    };
+    if (method_value != .string) {
+        try mcp_protocol.writeError(writer, id, -32600, "method must be a string");
+        return;
+    }
+
+    dispatchMethod(allocator, device, method_value.string, object.get("params"), id, writer, live_trace) catch |err| {
+        const classified = errors.classify(err);
+        try mcp_protocol.writeErrorWithPublicCode(writer, id, -32000, @errorName(err), classified.code);
+        return;
+    };
+}
+
+fn dispatchMethod(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !void {
+    if (std.mem.eql(u8, method, "initialize")) {
+        const protocol_version = optionalParamString(params, "protocolVersion") orelse "2024-11-05";
+        try mcp_protocol.writeInitializeResult(writer, id, protocol_version);
+        return;
+    }
+
+    if (std.mem.eql(u8, method, "ping")) {
+        try mcp_protocol.writeResultRaw(writer, id, "{}");
+        return;
+    }
+
+    if (std.mem.eql(u8, method, "tools/list")) {
+        try mcp_protocol.writeToolListResult(writer, id);
+        return;
+    }
+
+    if (std.mem.eql(u8, method, "tools/call")) {
+        const tool_name = try requiredParamString(params, "name");
+        const arguments = paramField(params, "arguments");
+        try callTool(allocator, device, tool_name, arguments, id, writer, live_trace);
+        return;
+    }
+
+    try mcp_protocol.writeError(writer, id, -32601, "method not found");
+}
+
+fn callTool(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    tool_name: []const u8,
+    arguments: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !void {
+    if (std.mem.eql(u8, tool_name, "snapshot")) {
+        var snap = try device.snapshot(live_trace);
+        defer snap.deinit(device.allocator);
+        var payload = std.ArrayList(u8).empty;
+        defer payload.deinit(allocator);
+        try trace.writeSnapshotJson(payload.writer(allocator), snap);
+        try mcp_protocol.writeToolTextResult(writer, id, payload.items);
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "semantic_snapshot")) {
+        var snap = try device.snapshot(live_trace);
+        defer snap.deinit(device.allocator);
+        if (live_trace) |tw| {
+            const path = try tw.writeSnapshot(snap);
+            defer tw.allocator.free(path);
+            try tw.recordEvent("observe.semanticSnapshot", "{\"status\":\"ok\"}");
+        }
+        var payload = std.ArrayList(u8).empty;
+        defer payload.deinit(allocator);
+        try semantic.writeSemanticSnapshotJson(payload.writer(allocator), snap);
+        try mcp_protocol.writeToolTextResult(writer, id, payload.items);
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "tap")) {
+        const wanted = try parseArgumentsSelector(allocator, arguments);
+        defer wanted.deinit(allocator);
+        try runner.tapSelector(device, wanted, live_trace, .{});
+        try mcp_protocol.writeToolTextResult(writer, id, "{\"ok\":true}");
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "type")) {
+        const text = try requiredParamString(arguments, "text");
+        if (paramField(arguments, "selector")) |selector_value| {
+            const wanted = try selector.parseFromJson(allocator, selector_value);
+            defer wanted.deinit(allocator);
+            try runner.typeTextSelector(device, wanted, text, live_trace, .{});
+        } else {
+            try device.typeText(text);
+        }
+        try mcp_protocol.writeToolTextResult(writer, id, "{\"ok\":true}");
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "press_back")) {
+        try device.pressBack();
+        try mcp_protocol.writeToolTextResult(writer, id, "{\"ok\":true}");
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "open_link")) {
+        try device.openLink(try requiredParamString(arguments, "url"));
+        try mcp_protocol.writeToolTextResult(writer, id, "{\"ok\":true}");
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "wait_visible")) {
+        const wanted = try parseArgumentsSelector(allocator, arguments);
+        defer wanted.deinit(allocator);
+        const timeout_ms = try optionalParamU64(arguments, "timeoutMs", 5000);
+        const visible = try runner.waitUntilVisible(device, wanted, timeout_ms, live_trace, .{});
+        try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+        try mcp_protocol.writeId(writer, id);
+        try writer.writeAll(",\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"{\\\"visible\\\":");
+        try writer.writeAll(if (visible) "true" else "false");
+        try writer.writeAll("}\"}]}}\n");
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "trace_events")) {
+        try mcp_trace.writeEventsToolResult(allocator, writer, id, live_trace, try optionalParamU64(arguments, "afterSeq", 0), @min(try optionalParamU64(arguments, "limit", 100), 1000));
+        return;
+    }
+
+    if (std.mem.eql(u8, tool_name, "trace_export")) {
+        const out_path = try requiredParamString(arguments, "out");
+        const omit_screenshots = try optionalParamBool(arguments, "omitScreenshots", false);
+        const redact = try optionalParamBool(arguments, "redact", false) or omit_screenshots;
+        try mcp_trace.writeExportToolResult(allocator, writer, id, live_trace, out_path, redact, omit_screenshots);
+        return;
+    }
+
+    try mcp_protocol.writeError(writer, id, -32602, "unknown tool");
+}
+
+fn parseArgumentsSelector(allocator: std.mem.Allocator, arguments: ?std.json.Value) !selector.Selector {
+    const selector_value = paramField(arguments, "selector") orelse return error.MissingSelector;
+    return try selector.parseFromJson(allocator, selector_value);
+}
+
+fn paramField(params: ?std.json.Value, key: []const u8) ?std.json.Value {
+    const value = params orelse return null;
+    if (value != .object) return null;
+    return value.object.get(key);
+}
+
+fn requiredParamString(params: ?std.json.Value, key: []const u8) ![]const u8 {
+    const value = paramField(params, key) orelse return error.MissingParam;
+    return switch (value) {
+        .string => |actual| actual,
+        else => error.ParamMustBeString,
+    };
+}
+
+fn optionalParamString(params: ?std.json.Value, key: []const u8) ?[]const u8 {
+    const value = paramField(params, key) orelse return null;
+    return switch (value) {
+        .string => |actual| actual,
+        else => null,
+    };
+}
+
+fn optionalParamU64(params: ?std.json.Value, key: []const u8, default_value: u64) !u64 {
+    const value = paramField(params, key) orelse return default_value;
+    return switch (value) {
+        .integer => |actual| @as(u64, @intCast(actual)),
+        else => error.ParamMustBeInteger,
+    };
+}
+
+fn optionalParamBool(params: ?std.json.Value, key: []const u8, default_value: bool) !bool {
+    const value = paramField(params, key) orelse return default_value;
+    return switch (value) {
+        .bool => |actual| actual,
+        else => error.ParamMustBeBool,
+    };
+}

package/src/mcp_protocol.zig

@@ -0,0 +1,64 @@
+const std = @import("std");
+const trace = @import("trace.zig");
+const version = @import("version.zig");
+
+pub fn writeInitializeResult(writer: anytype, id: ?std.json.Value, protocol_version: []const u8) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.writeAll(",\"result\":{\"protocolVersion\":");
+    try trace.writeJsonString(writer, protocol_version);
+    try writer.writeAll(",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"zmr\",\"version\":");
+    try trace.writeJsonString(writer, version.runner_version);
+    try writer.writeAll("}}}\n");
+}
+
+pub fn writeToolListResult(writer: anytype, id: ?std.json.Value) !void {
+    try writeResultRaw(writer, id, tool_list_json);
+}
+
+pub fn writeToolTextResult(writer: anytype, id: ?std.json.Value, text: []const u8) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.writeAll(",\"result\":{\"content\":[{\"type\":\"text\",\"text\":");
+    try trace.writeJsonString(writer, text);
+    try writer.writeAll("}]}}\n");
+}
+
+pub fn writeResultRaw(writer: anytype, id: ?std.json.Value, raw_json: []const u8) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.writeAll(",\"result\":");
+    try writer.writeAll(raw_json);
+    try writer.writeAll("}\n");
+}
+
+pub fn writeError(writer: anytype, id: ?std.json.Value, code: i32, message: []const u8) !void {
+    try writeErrorWithPublicCode(writer, id, code, message, null);
+}
+
+pub fn writeErrorWithPublicCode(writer: anytype, id: ?std.json.Value, code: i32, message: []const u8, public_code: ?[]const u8) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.print(",\"error\":{{\"code\":{d},\"message\":", .{code});
+    try trace.writeJsonString(writer, message);
+    if (public_code) |value| {
+        try writer.writeAll(",\"publicCode\":");
+        try trace.writeJsonString(writer, value);
+    }
+    try writer.writeAll("}}\n");
+}
+
+pub fn writeId(writer: anytype, id: ?std.json.Value) !void {
+    const value = id orelse {
+        try writer.writeAll("null");
+        return;
+    };
+    switch (value) {
+        .null => try writer.writeAll("null"),
+        .string => |actual| try trace.writeJsonString(writer, actual),
+        .integer => |actual| try writer.print("{d}", .{actual}),
+        else => try writer.writeAll("null"),
+    }
+}
+
+const tool_list_json = "{\"tools\":[" ++ "{\"name\":\"snapshot\",\"description\":\"Capture the current mobile observation snapshot as JSON.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++ "{\"name\":\"semantic_snapshot\",\"description\":\"Capture an agent-optimized mobile semantic tree with roles, names, selectors, bounds, and recommended actions.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++ "{\"name\":\"tap\",\"description\":\"Tap a visible element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"}}}}," ++ "{\"name\":\"type\",\"description\":\"Type text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"text\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"text\":{\"type\":\"string\"}}}}," ++ "{\"name\":\"press_back\",\"description\":\"Press Android back or the platform-equivalent navigation action.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++ "{\"name\":\"open_link\",\"description\":\"Open a deep link URL in the target app.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"url\"],\"properties\":{\"url\":{\"type\":\"string\"}}}}," ++ "{\"name\":\"wait_visible\",\"description\":\"Wait for an element selector to become visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++ "{\"name\":\"trace_events\",\"description\":\"Read live trace events from a traced MCP session.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"afterSeq\":{\"type\":\"integer\",\"minimum\":0},\"limit\":{\"type\":\"integer\",\"minimum\":1}}}}," ++ "{\"name\":\"trace_export\",\"description\":\"Export the active trace directory as a .zmrtrace bundle.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"out\"],\"properties\":{\"out\":{\"type\":\"string\"},\"redact\":{\"type\":\"boolean\"},\"omitScreenshots\":{\"type\":\"boolean\"}}}}" ++ "]}";

package/src/mcp_trace.zig

@@ -0,0 +1,83 @@
+const std = @import("std");
+const bundle = @import("bundle.zig");
+const mcp_protocol = @import("mcp_protocol.zig");
+const trace = @import("trace.zig");
+
+pub fn writeEventsToolResult(
+    allocator: std.mem.Allocator,
+    writer: anytype,
+    id: ?std.json.Value,
+    live_trace: ?*trace.TraceWriter,
+    after_seq: u64,
+    limit: u64,
+) !void {
+    const tw = live_trace orelse {
+        try mcp_protocol.writeToolTextResult(writer, id, "{\"traceDir\":null,\"events\":[]}");
+        return;
+    };
+
+    const events_path = try std.fs.path.join(allocator, &.{ tw.root_dir, "events.jsonl" });
+    defer allocator.free(events_path);
+    const content = std.fs.cwd().readFileAlloc(allocator, events_path, 64 * 1024 * 1024) catch |err| switch (err) {
+        error.FileNotFound => try allocator.dupe(u8, ""),
+        else => return err,
+    };
+    defer allocator.free(content);
+
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(allocator);
+    const payload_writer = payload.writer(allocator);
+    try payload_writer.writeAll("{\"traceDir\":");
+    try trace.writeJsonString(payload_writer, tw.root_dir);
+    try payload_writer.print(",\"afterSeq\":{d},\"events\":[", .{after_seq});
+    var emitted: u64 = 0;
+    var lines = std.mem.splitScalar(u8, content, '\n');
+    while (lines.next()) |raw_line| {
+        if (emitted >= limit) break;
+        const line = std.mem.trim(u8, raw_line, " \t\r\n");
+        if (line.len == 0) continue;
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, line, .{}) catch continue;
+        defer parsed.deinit();
+        if (parsed.value != .object) continue;
+        const seq_value = parsed.value.object.get("seq") orelse continue;
+        if (seq_value != .integer or seq_value.integer <= 0) continue;
+        const seq = @as(u64, @intCast(seq_value.integer));
+        if (seq <= after_seq) continue;
+        if (emitted > 0) try payload_writer.writeAll(",");
+        try payload_writer.writeAll(line);
+        emitted += 1;
+    }
+    try payload_writer.writeAll("]}");
+    try mcp_protocol.writeToolTextResult(writer, id, payload.items);
+}
+
+pub fn writeExportToolResult(
+    allocator: std.mem.Allocator,
+    writer: anytype,
+    id: ?std.json.Value,
+    live_trace: ?*trace.TraceWriter,
+    out_path: []const u8,
+    redact: bool,
+    omit_screenshots: bool,
+) !void {
+    const tw = live_trace orelse {
+        try mcp_protocol.writeToolTextResult(writer, id, "{\"traceDir\":null,\"message\":\"start zmr mcp with --trace-dir to enable export\"}");
+        return;
+    };
+
+    try tw.flushManifest();
+    try bundle.exportTraceBundleWithOptions(allocator, tw.root_dir, out_path, .{
+        .redact = redact,
+        .omit_screenshots = omit_screenshots,
+    });
+
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(allocator);
+    const payload_writer = payload.writer(allocator);
+    try payload_writer.writeAll("{\"traceDir\":");
+    try trace.writeJsonString(payload_writer, tw.root_dir);
+    try payload_writer.writeAll(",\"out\":");
+    try trace.writeJsonString(payload_writer, out_path);
+    try payload_writer.print(",\"redacted\":{},\"omitScreenshots\":{}}}", .{ redact, omit_screenshots });
+    try mcp_protocol.writeToolTextResult(writer, id, payload.items);
+}