//! docs/typ/guide.typ, Terminals : an interactive program in a //! real session's shell, driven through its pty files as an agent drives //! one (test/agent_session_test.py's interaction checks, which went through //! test/agent_session.py). const std = @import("std"); const process = @import("../process.zig"); const eh = @import("../e2e_harness.zig"); pub const cases = .{ .{ "terminals: a program's prompt shows and holds still, input sent unsubmitted shows, and ^U takes the screen back to what it was", prompt }, .{ "terminals: what a program prints past a screenful stays in the terminal's body, and its prompt after it shows", history }, .{ "terminals: a control byte through pty/data reaches a program in raw mode, which then carries on", rawKey }, }; const ready = "AGENT_READY> "; fn prompt(gpa: std.mem.Allocator, exe: [:0]const u8) !void { try drive(gpa, exe, "printf \"AGENT_READY> \"; read answer", null, 0); } fn history(gpa: std.mem.Allocator, exe: [:0]const u8) !void { try drive(gpa, exe, "printf \"AGENT_READY> \"; sleep .3; seq 1 3000; printf \"AGENT_READY> \"; read answer", null, 1000); } fn rawKey(gpa: std.mem.Allocator, exe: [:0]const u8) !void { try drive(gpa, exe, "stty raw -echo; printf \"AGENT_READY> \"; dd bs=1 count=1 of=/dev/null 2>/dev/null; stty sane; seq 1 3000; printf \"AGENT_READY> \"; read answer", 0x0f, 1000); } /// The script run in a new terminal's shell, as `/bin/sh command.sh`: its /// prompt waited for, `key` sent and the prompt waited for again, the body /// holding at least `rows` lines (and, with none asked, fewer than a /// thousand: nothing printed is nothing kept), then a probe typed and /// taken back with ^U. fn drive(gpa: std.mem.Allocator, exe: [:0]const u8, script: []const u8, key: ?u8, rows: usize) !void { var d = try process.Detached.start(gpa, exe, "agent", .{}); defer d.deinit(); const f = &d.files; try d.put("command.sh", f.at("exec /bin/sh -c '{s}'\n", .{script})); try f.write("/ctl", "Shell /bin/sh\n"); try f.write("/exec", "Tty\n"); const term = try f.focused(); const body = f.at("/pane/{d}/body", .{term}); const data = f.at("/pane/{d}/pty/data", .{term}); try until(f, body, struct { fn ok(text: []const u8) bool { return std.mem.trim(u8, text, " \n").len > 0; } }.ok); try f.write(data, f.at("/bin/sh {s}/command.sh\r", .{d.root()})); _ = try settled(f); if (key) |k| { try f.write(data, &.{k}); _ = try settled(f); } const deadline = eh.nowMs() + 10_000; while (lines(try f.read(body)) < rows) { if (eh.nowMs() > deadline) return error.ShortHistory; sleepMs(50); } if (rows == 0) try std.testing.expect(lines(try f.read(body)) < 1000); const before = try settled(f); const probe = "pq7c0ffee2b9d"; try std.testing.expect(std.mem.indexOf(u8, before, probe) == null); try f.write(data, probe); const shown_by = eh.nowMs() + 10_000; while (std.mem.indexOf(u8, try unwrapped(f), probe) == null) { if (eh.nowMs() > shown_by) return error.ProbeNotShown; sleepMs(10); } try f.write(data, "\x15"); const back_by = eh.nowMs() + 10_000; while (!std.mem.eql(u8, try f.screen(), before)) { if (eh.nowMs() > back_by) return error.ScreenNotRestored; sleepMs(10); } } /// The screen once it shows the prompt and holds still between two reads. fn settled(f: *process.Files) ![]const u8 { const deadline = eh.nowMs() + 10_000; var previous: []const u8 = ""; while (true) { const text = try f.screen(); if (std.mem.indexOf(u8, text, ready) != null and std.mem.eql(u8, text, previous)) return text; if (eh.nowMs() > deadline) { std.debug.print("no settled prompt on the screen:\n{s}\n", .{text}); return error.NotReady; } previous = text; sleepMs(50); } } fn until(f: *process.Files, path: []const u8, ok: fn ([]const u8) bool) !void { const deadline = eh.nowMs() + 10_000; while (!ok(try f.read(path))) { if (eh.nowMs() > deadline) return error.Timeout; sleepMs(10); } } /// The screen's text with its rows run together, as a long line wraps. fn unwrapped(f: *process.Files) ![]const u8 { const text = try f.screen(); const out = try f.arena.allocator().alloc(u8, text.len); var n: usize = 0; for (text) |c| if (c != '\n') { out[n] = c; n += 1; }; return out[0..n]; } fn lines(text: []const u8) usize { return std.mem.count(u8, text, "\n") + @intFromBool(text.len > 0 and text[text.len - 1] != '\n'); } fn sleepMs(ms: u32) void { var ts: std.c.timespec = .{ .sec = 0, .nsec = @as(isize, ms) * std.time.ns_per_ms }; _ = std.c.nanosleep(&ts, null); }