zig-mobile-runner 0.1.0

package/src/json_rpc_methods.zig

@@ -0,0 +1,318 @@
+const std = @import("std");
+const bundle = @import("bundle.zig");
+const observation = @import("json_rpc_observation.zig");
+const params_parser = @import("json_rpc_params.zig");
+const protocol = @import("json_rpc_protocol.zig");
+const rpc_trace = @import("json_rpc_trace.zig");
+const runner = @import("runner.zig");
+const selector = @import("selector.zig");
+const trace = @import("trace.zig");
+
+pub 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 (try dispatchCoreMethod(allocator, device, method, id, writer)) return;
+    if (try dispatchAppMethod(device, method, params, id, writer)) return;
+    if (try dispatchObserveMethod(device, method, id, writer, live_trace)) return;
+    if (try dispatchUiMethod(allocator, device, method, params, id, writer, live_trace)) return;
+    if (try dispatchWaitMethod(allocator, device, method, params, id, writer, live_trace)) return;
+    if (try dispatchAssertMethod(allocator, device, method, params, id, writer, live_trace)) return;
+    if (try dispatchTraceMethod(allocator, method, params, id, writer, live_trace)) return;
+
+    try protocol.writeError(writer, id, -32601, "method not found");
+}
+
+fn dispatchCoreMethod(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    method: []const u8,
+    id: ?std.json.Value,
+    writer: anytype,
+) !bool {
+    if (std.mem.eql(u8, method, "runner.capabilities")) {
+        try protocol.writeCapabilitiesResult(writer, id);
+        return true;
+    }
+    if (std.mem.eql(u8, method, "device.list")) {
+        const devices = try device.listDevices();
+        defer {
+            for (devices) |info| info.deinit(allocator);
+            allocator.free(devices);
+        }
+        try protocol.writeDevicesResult(writer, id, devices);
+        return true;
+    }
+    if (std.mem.eql(u8, method, "session.create")) {
+        try protocol.writeResultRaw(writer, id, "{\"sessionId\":\"default\"}");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "session.close")) {
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    return false;
+}
+
+fn dispatchAppMethod(
+    device: anytype,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+) !bool {
+    if (std.mem.eql(u8, method, "app.install")) {
+        const path = try params_parser.requiredString(params, "path");
+        try device.install(path);
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "app.launch")) {
+        try device.launch();
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "app.stop")) {
+        try device.stop();
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "app.clearState")) {
+        try device.clearState();
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "app.openLink")) {
+        const url = try params_parser.requiredString(params, "url");
+        try device.openLink(url);
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    return false;
+}
+
+fn dispatchObserveMethod(
+    device: anytype,
+    method: []const u8,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !bool {
+    if (std.mem.eql(u8, method, "observe.snapshot")) {
+        var snap = try device.snapshot(live_trace);
+        defer snap.deinit(device.allocator);
+        if (live_trace) |tw| try observation.recordArtifact(tw, "observe.snapshot", snap);
+        try observation.writeResult(writer, id, snap, .raw);
+        return true;
+    }
+    if (std.mem.eql(u8, method, "observe.semanticSnapshot")) {
+        var snap = try device.snapshot(live_trace);
+        defer snap.deinit(device.allocator);
+        if (live_trace) |tw| try observation.recordArtifact(tw, "observe.semanticSnapshot", snap);
+        try observation.writeResult(writer, id, snap, .semantic);
+        return true;
+    }
+    return false;
+}
+
+fn dispatchUiMethod(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !bool {
+    if (std.mem.eql(u8, method, "ui.tap")) {
+        const wanted = try params_parser.selectorParam(allocator, params);
+        defer wanted.deinit(allocator);
+        try runner.tapSelector(device, wanted, live_trace, .{});
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "ui.type")) {
+        const text = try params_parser.requiredString(params, "text");
+        if (params_parser.field(params, "selector")) |selector_value| {
+            const wanted = try selector.parseFromJson(allocator, selector_value);
+            defer wanted.deinit(allocator);
+            try runner.typeTextSelector(device, wanted, text, live_trace, .{});
+            try protocol.writeResultRaw(writer, id, "true");
+            return true;
+        }
+        try device.typeText(text);
+        if (live_trace) |tw| try rpc_trace.recordSimplePayload(tw, "ui.type", "text", text);
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "ui.eraseText")) {
+        const max_chars = @as(u32, @intCast(try params_parser.optionalU64(params, "maxChars", 80)));
+        if (params_parser.field(params, "selector")) |selector_value| {
+            const wanted = try selector.parseFromJson(allocator, selector_value);
+            defer wanted.deinit(allocator);
+            try runner.eraseTextSelector(device, wanted, max_chars, live_trace, .{});
+            try protocol.writeResultRaw(writer, id, "true");
+            return true;
+        }
+        try device.eraseText(max_chars);
+        if (live_trace) |tw| {
+            const payload = try std.fmt.allocPrint(tw.allocator, "{{\"maxChars\":{d}}}", .{max_chars});
+            defer tw.allocator.free(payload);
+            try tw.recordEvent("ui.eraseText", payload);
+        }
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "ui.hideKeyboard")) {
+        try device.hideKeyboard();
+        if (live_trace) |tw| try tw.recordEvent("ui.hideKeyboard", "{\"status\":\"ok\"}");
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "ui.swipe")) {
+        try device.swipe(
+            try params_parser.requiredI32(params, "x1"),
+            try params_parser.requiredI32(params, "y1"),
+            try params_parser.requiredI32(params, "x2"),
+            try params_parser.requiredI32(params, "y2"),
+            @as(u32, @intCast(try params_parser.optionalU64(params, "durationMs", 300))),
+        );
+        if (live_trace) |tw| try tw.recordEvent("ui.swipe", "{\"status\":\"ok\"}");
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "ui.pressBack")) {
+        try device.pressBack();
+        if (live_trace) |tw| try tw.recordEvent("ui.pressBack", "{\"status\":\"ok\"}");
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "ui.scrollUntilVisible")) {
+        const wanted = try params_parser.selectorParam(allocator, params);
+        defer wanted.deinit(allocator);
+        const ok = try runner.scrollUntilVisible(
+            device,
+            wanted,
+            try params_parser.optionalU64(params, "timeoutMs", 5000),
+            try params_parser.optionalDirection(params, "direction", .down),
+            live_trace,
+            .{},
+        );
+        try protocol.writeResultRaw(writer, id, if (ok) "true" else "false");
+        return true;
+    }
+    return false;
+}
+
+fn dispatchWaitMethod(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !bool {
+    if (std.mem.eql(u8, method, "wait.until")) {
+        const visible_value = params_parser.field(params, "visible") orelse return error.WaitUntilNeedsVisibleSelector;
+        const wanted = try selector.parseFromJson(allocator, visible_value);
+        defer wanted.deinit(allocator);
+        const timeout_ms = try params_parser.optionalU64(params, "timeoutMs", 5000);
+        const ok = try runner.waitUntilVisible(device, wanted, timeout_ms, live_trace, .{});
+        try protocol.writeResultRaw(writer, id, if (ok) "true" else "false");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "wait.any")) {
+        const selectors = try params_parser.selectors(allocator, params);
+        defer {
+            for (selectors) |wanted| wanted.deinit(allocator);
+            allocator.free(selectors);
+        }
+        const matched = try runner.waitUntilAnyVisible(device, selectors, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{});
+        if (matched) |index| {
+            try protocol.writeMatchedIndexResult(writer, id, index);
+        } else {
+            try protocol.writeResultRaw(writer, id, "false");
+        }
+        return true;
+    }
+    if (std.mem.eql(u8, method, "wait.gone")) {
+        const wanted = try params_parser.selectorParam(allocator, params);
+        defer wanted.deinit(allocator);
+        const ok = try runner.waitUntilNotVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{});
+        try protocol.writeResultRaw(writer, id, if (ok) "true" else "false");
+        return true;
+    }
+    return false;
+}
+
+fn dispatchAssertMethod(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !bool {
+    if (std.mem.eql(u8, method, "assert.visible")) {
+        const wanted = try params_parser.selectorParam(allocator, params);
+        defer wanted.deinit(allocator);
+        if (!try runner.waitUntilVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{})) return error.AssertionFailed;
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "assert.notVisible")) {
+        const wanted = try params_parser.selectorParam(allocator, params);
+        defer wanted.deinit(allocator);
+        if (!try runner.waitUntilNotVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{})) return error.AssertionFailed;
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    if (std.mem.eql(u8, method, "assert.healthy")) {
+        if (!try runner.assertHealthy(device, try params_parser.optionalU64(params, "timeoutMs", 0), live_trace, .{})) return error.AssertionFailed;
+        try protocol.writeResultRaw(writer, id, "true");
+        return true;
+    }
+    return false;
+}
+
+fn dispatchTraceMethod(
+    allocator: std.mem.Allocator,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+    live_trace: ?*trace.TraceWriter,
+) !bool {
+    if (std.mem.eql(u8, method, "trace.events")) {
+        const after_seq = try params_parser.optionalU64(params, "afterSeq", 0);
+        const limit = @min(try params_parser.optionalU64(params, "limit", 100), 1000);
+        try rpc_trace.writeEventsResult(allocator, writer, id, live_trace, after_seq, limit);
+        return true;
+    }
+    if (std.mem.eql(u8, method, "trace.export")) {
+        const tw = live_trace orelse {
+            try protocol.writeTraceDisabledResult(writer, id);
+            return true;
+        };
+        const out_path = try params_parser.requiredString(params, "out");
+        const redact = try params_parser.optionalBool(params, "redact", false);
+        const omit_screenshots = try params_parser.optionalBool(params, "omitScreenshots", false);
+        const effective_redact = redact or omit_screenshots;
+        try tw.recordEvent("trace.export", "{\"status\":\"started\"}");
+        try tw.flushManifest();
+        try bundle.exportTraceBundleWithOptions(allocator, tw.root_dir, out_path, .{
+            .redact = effective_redact,
+            .omit_screenshots = omit_screenshots,
+        });
+        try protocol.writeTraceExportResult(writer, id, tw.root_dir, out_path, effective_redact, omit_screenshots);
+        return true;
+    }
+    return false;
+}

package/src/json_rpc_observation.zig

@@ -0,0 +1,31 @@
+const std = @import("std");
+const protocol = @import("json_rpc_protocol.zig");
+const semantic = @import("semantic.zig");
+const trace = @import("trace.zig");
+const types = @import("types.zig");
+
+pub const Format = enum { raw, semantic };
+
+pub fn writeResult(writer: anytype, id: ?std.json.Value, snap: types.ObservationSnapshot, format: Format) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try protocol.writeId(writer, id);
+    try writer.writeAll(",\"result\":");
+    switch (format) {
+        .raw => try trace.writeSnapshotJson(writer, snap),
+        .semantic => try semantic.writeSemanticSnapshotJson(writer, snap),
+    }
+    try writer.writeAll("}\n");
+}
+
+pub fn recordArtifact(tw: *trace.TraceWriter, kind: []const u8, snap: types.ObservationSnapshot) !void {
+    const path = try tw.writeSnapshot(snap);
+    defer tw.allocator.free(path);
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    try payload.writer(tw.allocator).writeAll("{\"path\":");
+    try trace.writeJsonString(payload.writer(tw.allocator), path);
+    try payload.writer(tw.allocator).writeAll(",\"snapshotId\":");
+    try trace.writeJsonString(payload.writer(tw.allocator), snap.id);
+    try payload.writer(tw.allocator).writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}

package/src/json_rpc_params.zig

@@ -0,0 +1,52 @@
+const std = @import("std");
+const json_fields = @import("json_fields.zig");
+const scenario = @import("scenario.zig");
+const selector = @import("selector.zig");
+
+pub fn field(params: ?std.json.Value, key: []const u8) ?std.json.Value {
+    return json_fields.field(params, key);
+}
+
+pub fn selectorParam(allocator: std.mem.Allocator, params: ?std.json.Value) !selector.Selector {
+    const selector_value = field(params, "selector") orelse return error.MissingSelector;
+    return try selector.parseFromJson(allocator, selector_value);
+}
+
+pub fn selectors(allocator: std.mem.Allocator, params: ?std.json.Value) ![]selector.Selector {
+    const selectors_value = field(params, "selectors") orelse return error.MissingSelectors;
+    if (selectors_value != .array) return error.SelectorsMustBeArray;
+    var parsed_selectors = std.ArrayList(selector.Selector).empty;
+    errdefer {
+        for (parsed_selectors.items) |wanted| wanted.deinit(allocator);
+        parsed_selectors.deinit(allocator);
+    }
+    for (selectors_value.array.items) |selector_value| {
+        try parsed_selectors.append(allocator, try selector.parseFromJson(allocator, selector_value));
+    }
+    if (parsed_selectors.items.len == 0) return error.SelectorsMustNotBeEmpty;
+    return try parsed_selectors.toOwnedSlice(allocator);
+}
+
+pub fn requiredString(params: ?std.json.Value, key: []const u8) ![]const u8 {
+    return try json_fields.requiredString(params, key, error.MissingParam, error.ParamMustBeString);
+}
+
+pub fn requiredI32(params: ?std.json.Value, key: []const u8) !i32 {
+    return try json_fields.requiredI32(params, key, error.MissingParam, error.ParamMustBeInteger);
+}
+
+pub fn optionalU64(params: ?std.json.Value, key: []const u8, default_value: u64) !u64 {
+    return try json_fields.optionalU64(params, key, default_value, error.ParamMustBeInteger);
+}
+
+pub fn optionalBool(params: ?std.json.Value, key: []const u8, default_value: bool) !bool {
+    return try json_fields.optionalBool(params, key, default_value, error.ParamMustBeBool);
+}
+
+pub fn optionalDirection(params: ?std.json.Value, key: []const u8, default_value: scenario.ScrollDirection) !scenario.ScrollDirection {
+    const value = field(params, key) orelse return default_value;
+    if (value != .string) return error.ParamMustBeString;
+    if (std.mem.eql(u8, value.string, "down")) return .down;
+    if (std.mem.eql(u8, value.string, "up")) return .up;
+    return error.UnknownScrollDirection;
+}

package/src/json_rpc_protocol.zig

@@ -0,0 +1,110 @@
+const std = @import("std");
+const device_registry = @import("device_registry.zig");
+const trace = @import("trace.zig");
+const types = @import("types.zig");
+const version = @import("version.zig");
+
+pub const capabilities_json =
+    "{\"name\":\"zmr\",\"version\":\"" ++ version.runner_version ++
+    "\",\"protocolVersion\":\"" ++ version.protocol_version ++
+    "\",\"protocol\":{\"version\":\"" ++ version.protocol_version ++
+    "\",\"minimumCompatibleVersion\":\"" ++ version.protocol_min_compatible_version ++
+    "\",\"stability\":\"" ++ version.protocol_stability ++
+    "\",\"breakingChangePolicy\":\"" ++ version.protocol_breaking_change_policy ++
+    "\"},\"platforms\":[\"android\",\"ios\"],\"platformSupport\":{\"android\":{\"status\":\"supported\",\"deviceTypes\":[\"emulator\",\"physical\"],\"automation\":[\"adb\",\"uiautomator\",\"android-shim\"]},\"ios\":{\"status\":\"supported\",\"deviceTypes\":[\"simulator\",\"physical\"],\"automation\":[\"simctl\",\"devicectl\",\"xctest-shim\"],\"physicalDevices\":true}},\"iosPreview\":false,\"transports\":[\"stdio\",\"tcp\"],\"methods\":[\"runner.capabilities\",\"device.list\",\"session.create\",\"session.close\",\"app.install\",\"app.launch\",\"app.stop\",\"app.openLink\",\"app.clearState\",\"observe.snapshot\",\"observe.semanticSnapshot\",\"ui.tap\",\"ui.type\",\"ui.eraseText\",\"ui.hideKeyboard\",\"ui.swipe\",\"ui.pressBack\",\"ui.scrollUntilVisible\",\"wait.until\",\"wait.any\",\"wait.gone\",\"assert.visible\",\"assert.notVisible\",\"assert.healthy\",\"trace.events\",\"trace.export\"]}";
+
+pub fn writeCapabilitiesResult(writer: anytype, id: ?std.json.Value) !void {
+    try writeResultRaw(writer, id, capabilities_json);
+}
+
+pub fn writeDevicesResult(writer: anytype, id: ?std.json.Value, devices: []const types.DeviceInfo) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.writeAll(",\"result\":[");
+    for (devices, 0..) |info, index| {
+        if (index > 0) try writer.writeAll(",");
+        try writer.writeAll("{\"serial\":");
+        try trace.writeJsonString(writer, info.serial);
+        try writer.writeAll(",\"state\":");
+        try trace.writeJsonString(writer, info.state);
+        try writer.print(",\"ready\":{}", .{device_registry.isKnownReadyState(info.state)});
+        try writer.writeAll("}");
+    }
+    try writer.writeAll("]}\n");
+}
+
+pub fn writeTraceDisabledResult(writer: anytype, id: ?std.json.Value) !void {
+    try writeResultRaw(writer, id, "{\"traceDir\":null,\"message\":\"start zmr serve with --trace-dir to enable live RPC trace export\"}");
+}
+
+pub fn writeTraceExportResult(
+    writer: anytype,
+    id: ?std.json.Value,
+    trace_dir: []const u8,
+    out_path: []const u8,
+    redacted: bool,
+    omit_screenshots: bool,
+) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.writeAll(",\"result\":{\"traceDir\":");
+    try trace.writeJsonString(writer, trace_dir);
+    try writer.writeAll(",\"out\":");
+    try trace.writeJsonString(writer, out_path);
+    try writer.writeAll(",\"redacted\":");
+    try writer.writeAll(if (redacted) "true" else "false");
+    try writer.writeAll(",\"omitScreenshots\":");
+    try writer.writeAll(if (omit_screenshots) "true" else "false");
+    try writer.writeAll("}}\n");
+}
+
+pub fn writeMatchedIndexResult(writer: anytype, id: ?std.json.Value, index: usize) !void {
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try writeId(writer, id);
+    try writer.writeAll(",\"result\":{\"matchedIndex\":");
+    try writer.print("{d}", .{index});
+    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"),
+    }
+}

package/src/json_rpc_trace.zig

@@ -0,0 +1,73 @@
+const std = @import("std");
+const protocol = @import("json_rpc_protocol.zig");
+const trace = @import("trace.zig");
+
+pub fn writeEventsResult(
+    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 writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+        try protocol.writeId(writer, id);
+        try writer.print(",\"result\":{{\"traceDir\":null,\"afterSeq\":{d},\"nextSeq\":{d},\"latestSeq\":0,\"events\":[]}}}}\n", .{ after_seq, after_seq });
+        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);
+
+    try writer.writeAll("{\"jsonrpc\":\"2.0\",\"id\":");
+    try protocol.writeId(writer, id);
+    try writer.writeAll(",\"result\":{\"traceDir\":");
+    try trace.writeJsonString(writer, tw.root_dir);
+    try writer.print(",\"afterSeq\":{d},\"nextSeq\":", .{after_seq});
+
+    var events_json = std.ArrayList(u8).empty;
+    defer events_json.deinit(allocator);
+    var events_writer = events_json.writer(allocator);
+    var next_seq = 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 events_writer.writeAll(",");
+        try events_writer.writeAll(line);
+        next_seq = seq;
+        emitted += 1;
+    }
+
+    try writer.print("{d},\"latestSeq\":{d},\"events\":[", .{ next_seq, tw.event_count });
+    try writer.writeAll(events_json.items);
+    try writer.writeAll("]}}\n");
+}
+
+pub fn recordSimplePayload(tw: *trace.TraceWriter, kind: []const u8, key: []const u8, value: []const u8) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    const writer = payload.writer(tw.allocator);
+    try writer.writeAll("{");
+    try trace.writeJsonString(writer, key);
+    try writer.writeAll(":");
+    try trace.writeJsonString(writer, value);
+    try writer.writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}