Skip to content

Lightpanda: the headless browser designed for AI and automation

feat(agent): add assistant text streaming

Adrià Arrufat049c5f08f27a
diff --git a/build.zig.zon b/build.zig.zon
index 92f960358..2bbff77a2 100644
--- a/build.zig.zon
+++ b/build.zig.zon
@@ -35,8 +35,8 @@
.hash = "sqlite3-3.51.0-DMxLWssOAABZ8cAvU_LfBIbp0kZjm824PU8sSLXpEDdr",
},
.zenai = .{
- .url = "git+https://github.com/lightpanda-io/zenai.git#e58635146733157eb4936388b21a071fcabfa687",
- .hash = "zenai-0.0.0-iOY_VIf0BADH7PvSOlnVf564krXnAlns_1IIhh9ZDdwz",
+ .url = "git+https://github.com/lightpanda-io/zenai.git#96818eb830f8cb392cad2ce8b9d98e2289d1e29c",
+ .hash = "zenai-0.0.0-iOY_VKF1BQBCeM6sbUj2HAyHLxgJRun4NSWZfbx2IlUK",
},
.isocline = .{
.url = "git+https://github.com/arrufat/isocline?ref=lightpanda#832a9fe25f5f4458fcc47b5acc7c21db669c2f47",
diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index b923aab14..c3a321811 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -276,6 +276,15 @@ synthetic_tool_call_id: u32 = 0,
total_usage: zenai.provider.Usage = .{},
/// Set when the last turn ended in a model refusal (safety stop).
last_turn_refused: bool = false,
+/// Whether assistant text streams to the terminal as the model produces it.
+/// Toggled via `/stream`; persisted in `.lp-agent.zon`.
+stream_enabled: bool,
+/// True while assistant text is streaming to stdout (spinner paused). Cleared
+/// by `endStreamedText`, which also emits the closing newline.
+stream_active: bool = false,
+/// True when any assistant text streamed during the current turn, so `runTurn`
+/// skips the buffered `printAssistant` that would double-print it.
+streamed_text: bool = false,
available_providers: []const []const u8,
/// Cached reachability of each `local_providers` entry, so the per-keystroke
/// `/provider` hinter probes each local server at most once.
@@ -388,10 +397,11 @@ pub fn init(allocator: std.mem.Allocator, app: *App, opts: Config.Agent) !*Agent
const effort = settings.resolveEffort(opts, remembered, will_repl, if (resolved) |r| r.credentials.provider else null);
const verbosity = settings.resolveVerbosity(opts, remembered);
+ const stream_enabled = settings.resolveStream(remembered);
if (resolved) |r| {
if (r.source == .picked) {
- settings.saveRemembered(.{ .provider = r.credentials.provider, .model = model, .effort = effort, .verbosity = verbosity }) catch {};
+ settings.saveRemembered(.{ .provider = r.credentials.provider, .model = model, .effort = effort, .verbosity = verbosity, .stream = stream_enabled }) catch {};
}
// provider/model now live in the status bar; just space before the help
std.debug.print("\n", .{});
@@ -427,6 +437,7 @@ pub fn init(allocator: std.mem.Allocator, app: *App, opts: Config.Agent) !*Agent
.conversation = .init(allocator, opts.system_prompt orelse default_system_prompt),
.model = model,
.effort = effort,
+ .stream_enabled = stream_enabled,
.script_file = opts.script_file,
.one_shot_task = opts.task,
.one_shot_save = opts.save,
@@ -564,12 +575,41 @@ fn drainCancellation(self: *Agent, baseline: usize) error{UserCancelled} {
/// The side effects of `drainCancellation` without surfacing the error, for
/// void callers (e.g. `/save` synthesis) that just need to clean up.
fn resetAfterCancel(self: *Agent, baseline: usize) void {
+ self.endStreamedText();
self.conversation.rollback(baseline);
self.browser.env.cancelTerminate();
self.cancel_requested.store(false, .release);
self.http_interrupt.reset();
}
+/// On the first delta it pauses the spinner, whose stderr frames would
+/// otherwise interleave with this stdout text.
+fn streamAssistantDelta(ctx: *anyopaque, delta: []const u8) void {
+ const self: *Agent = @ptrCast(@alignCast(ctx));
+ if (delta.len == 0) return;
+ if (!self.stream_active) {
+ self.terminal.spinner.pause();
+ self.stream_active = true;
+ }
+ self.streamed_text = true;
+ self.terminal.printAssistantDelta(delta);
+}
+
+/// Close an in-progress streamed line with a newline. Idempotent, so every
+/// `runTools` exit path can call it unconditionally.
+fn endStreamedText(self: *Agent) void {
+ if (!self.stream_active) return;
+ self.terminal.printAssistantDelta("\n");
+ self.stream_active = false;
+}
+
+/// The text-delta hook, or null when `/stream off` — a null hook makes
+/// `runTools` fall back to a buffered response.
+fn streamHook(self: *Agent) ?zenai.provider.Client.TextDeltaHook {
+ if (!self.stream_enabled) return null;
+ return .{ .context = @ptrCast(self), .onText = streamAssistantDelta };
+}
+
/// One agent turn: the prompt sent to the model, plus optional context — a
/// recorder comment to write before the turn, file attachments to bundle into
/// the first user message, and a display label used in error output.
@@ -639,9 +679,11 @@ fn runTurn(self: *Agent, input: TurnInput) bool {
},
};
if (!input.suppress_answer) {
- if (text) |t|
- self.terminal.printAssistant(t)
- else if (self.last_turn_refused)
+ if (text) |t| {
+ // Streaming already emitted the text incrementally (plus a closing
+ // newline); only the buffered path needs to print it here.
+ if (!self.streamed_text) self.terminal.printAssistant(t);
+ } else if (self.last_turn_refused)
self.terminal.printInfo("(model declined to respond — safety refusal)", .{})
else
self.terminal.printInfo("(no response from model)", .{});
@@ -655,7 +697,7 @@ fn runRepl(self: *Agent) void {
if (self.ai_client != null) {
const a = Terminal.ansi;
- std.debug.print(" model: {s}{s} {s}effort: {s}{s}{s}\n", .{ a.dim, self.model, a.reset, a.dim, @tagName(self.effort), a.reset });
+ std.debug.print(" model: {s}{s} {s}effort: {s}{s} {s}stream: {s}{s}{s}\n", .{ a.dim, self.model, a.reset, a.dim, @tagName(self.effort), a.reset, a.dim, if (self.stream_enabled) "on" else "off", a.reset });
}
repl: while (true) {
@@ -762,6 +804,7 @@ fn handleMeta(self: *Agent, arena: std.mem.Allocator, meta: *const SlashCommand.
.help => self.printSlashHelp(arena, rest),
.verbosity => self.setEnumOption("verbosity", &self.terminal.verbosity, rest),
.effort => self.setEnumOption("effort", &self.effort, rest),
+ .stream => self.handleStream(rest),
.usage => self.handleUsage(),
.clear => self.handleClear(),
.reset => self.handleReset(),
@@ -790,6 +833,24 @@ fn setEnumOption(self: *Agent, comptime name: []const u8, target: anytype, rest:
self.reportSaved(name, @tagName(level));
}
+/// `/stream`: bare prints the current state; `on`/`off` sets and persists it.
+fn handleStream(self: *Agent, rest: []const u8) void {
+ if (rest.len == 0) {
+ self.terminal.printInfo("stream: {s}", .{if (self.stream_enabled) "on" else "off"});
+ return;
+ }
+ const on = if (std.ascii.eqlIgnoreCase(rest, "on") or std.ascii.eqlIgnoreCase(rest, "true"))
+ true
+ else if (std.ascii.eqlIgnoreCase(rest, "off") or std.ascii.eqlIgnoreCase(rest, "false"))
+ false
+ else {
+ self.terminal.printError("usage: /stream [on|off] (got {s})", .{rest});
+ return;
+ };
+ self.stream_enabled = on;
+ self.reportSaved("stream", if (on) "on" else "off");
+}
+
/// Print cumulative session token usage, broken down so the cache's effect is
/// visible — the REPL otherwise never surfaces the `$usage` line `--task`
/// prints. Reads `total_usage` (accumulated per turn by `processUserMessage`);
@@ -900,7 +961,7 @@ fn reportSaved(self: *Agent, label: []const u8, value: []const u8) void {
self.terminal.printInfo("{s}: {s}", .{ label, value });
return;
}
- if (settings.saveRemembered(.{ .provider = provider, .model = self.model, .effort = self.effort, .verbosity = self.terminal.verbosity })) {
+ if (settings.saveRemembered(.{ .provider = provider, .model = self.model, .effort = self.effort, .verbosity = self.terminal.verbosity, .stream = self.stream_enabled })) {
self.terminal.printInfo("{s}: {s} (saved to {s})", .{ label, value, settings.remembered_path });
} else |_| {
self.terminal.printInfo("{s}: {s}", .{ label, value });
@@ -1357,6 +1418,10 @@ fn printSlashHelp(self: *Agent, arena: std.mem.Allocator, target: []const u8) vo
"/effort " ++ Config.tagHint(Config.Effort) ++ " — set per-turn reasoning effort (currently: {s}); saved to {s}. Bare /effort prints the level.",
.{ @tagName(self.effort), settings.remembered_path },
),
+ .stream => self.terminal.printInfo(
+ "/stream [on|off] — stream assistant text as it's generated (currently: {s}); saved to {s}. Bare /stream prints the state.",
+ .{ if (self.stream_enabled) "on" else "off", settings.remembered_path },
+ ),
.usage => self.terminal.printInfo(
"/usage — show cumulative token usage and cache hit rate for this session",
.{},
@@ -1592,6 +1657,7 @@ fn formatApiError(self: *Agent, client: zenai.provider.Client, err: anyerror) []
fn processUserMessage(self: *Agent, input: TurnInput) !?[]const u8 {
const ma = self.conversation.arena.allocator();
self.api_error_detail = null;
+ self.streamed_text = false;
self.http_interrupt.reset();
try self.conversation.ensureSystemPrompt();
@@ -1637,8 +1703,10 @@ fn processUserMessage(self: *Agent, input: TurnInput) !?[]const u8 {
// non-thinking models.
.effort = self.effort,
.cancel = .{ .context = @ptrCast(self), .checkFn = checkCancel },
+ .stream = self.streamHook(),
},
) catch |err| {
+ self.endStreamedText();
self.terminal.spinner.cancel();
// Ctrl-C can land while runTools unwinds an HTTP error — surface
// UserCancelled, not ApiError, so the user sees the outcome they asked for.
@@ -1648,6 +1716,7 @@ fn processUserMessage(self: *Agent, input: TurnInput) !?[]const u8 {
self.conversation.rollback(msg_baseline);
return error.ApiError;
};
+ self.endStreamedText();
self.terminal.spinner.stop();
defer result.deinit();
self.total_usage.add(result.usage);
@@ -1721,13 +1790,16 @@ fn processUserMessage(self: *Agent, input: TurnInput) !?[]const u8 {
// `.none` stays off to opt out on models that reject it.
.effort = if (self.effort == .none) .none else .low,
.cancel = .{ .context = @ptrCast(self), .checkFn = checkCancel },
+ .stream = self.streamHook(),
},
) catch |err| {
+ self.endStreamedText();
if (self.cancel_requested.load(.acquire)) return self.drainCancellation(msg_baseline);
log.err(.app, "AI synthesis error", .{ .err = err });
self.conversation.rollback(synth_baseline);
break :blk null;
};
+ self.endStreamedText();
defer synth.deinit();
self.total_usage.add(synth.usage);
@@ -1810,6 +1882,8 @@ fn capToolOutput(allocator: std.mem.Allocator, output: []const u8) []const u8 {
fn handleToolCall(ctx: *anyopaque, allocator: std.mem.Allocator, tool_name: []const u8, arguments: ?std.json.Value) zenai.provider.Client.ToolHandler.Result {
const self: *Agent = @ptrCast(@alignCast(ctx));
+ // Close any assistant text streamed this turn before the tool spinner shows.
+ self.endStreamedText();
// The spinner doesn't render args, and `agentToolDone` skips the body line
// at low verbosity — don't pay for the stringify when nobody reads it.
const needs_args = self.terminal.spinner.isEnabled() or self.terminal.verbosity != .low;
diff --git a/src/agent/SlashCommand.zig b/src/agent/SlashCommand.zig
index 80cadf709..44da327fb 100644
--- a/src/agent/SlashCommand.zig
+++ b/src/agent/SlashCommand.zig
@@ -17,7 +17,7 @@
// along with this program. If not, see <https://www.gnu.org/licenses/>.
//! REPL-only meta slash commands (`/help`, `/quit`, `/verbosity`, `/effort`,
-//! `/usage`, `/model`, `/provider`). Not tool slash commands — handled by
+//! `/stream`, `/usage`, `/model`, `/provider`). Not tool slash commands — handled by
//! `Agent.handleMeta`, never reaching the recorder. Tool slash-command schema
//! primitives live in `lp.Schema`; import that directly.
@@ -46,7 +46,7 @@ pub const MetaCommand = struct {
/// Dispatched by `Agent.handleMeta` via an exhaustive switch, so a new meta
/// command is a compile error until it's wired up there too.
- const Tag = enum { help, quit, verbosity, effort, usage, clear, reset, save, load, model, provider };
+ const Tag = enum { help, quit, verbosity, effort, stream, usage, clear, reset, save, load, model, provider };
};
const tagNames = Config.tagNames;
@@ -57,6 +57,7 @@ pub const meta_commands = [_]MetaCommand{
.{ .tag = .quit, .name = "quit", .hint = "", .values = &.{}, .description = "Exit the REPL" },
.{ .tag = .verbosity, .name = "verbosity", .hint = tagHint(Config.AgentVerbosity), .values = tagNames(Config.AgentVerbosity), .description = "Set agent verbosity" },
.{ .tag = .effort, .name = "effort", .hint = tagHint(Config.Effort), .values = tagNames(Config.Effort), .description = "Set per-turn reasoning effort" },
+ .{ .tag = .stream, .name = "stream", .hint = "[on|off]", .values = &.{ "on", "off" }, .description = "Toggle streaming of assistant text" },
.{ .tag = .usage, .name = "usage", .hint = "", .values = &.{}, .description = "Show token usage and cache stats for this session" },
.{ .tag = .clear, .name = "clear", .hint = "", .values = &.{}, .description = "Clear conversation history and usage (keeps page/cookies)" },
.{ .tag = .reset, .name = "reset", .hint = "", .values = &.{}, .description = "Reset conversation and browser session (drops page/cookies)" },
diff --git a/src/agent/Spinner.zig b/src/agent/Spinner.zig
index 36d91381f..aa548edff 100644
--- a/src/agent/Spinner.zig
+++ b/src/agent/Spinner.zig
@@ -70,6 +70,11 @@ mu: std.Thread.Mutex = .{},
cv: std.Thread.Condition = .{},
state: State = .idle,
frame: u8 = 0,
+/// True while a caller streams assistant text to stdout: the worker stops
+/// rendering and the current frame is cleared, so the stderr spinner does not
+/// interleave with the streamed line. Turn state (timer, tool count) is
+/// preserved for the eventual `stop`.
+paused: bool = false,
tool_calls: u32 = 0,
turn_started_ns: i128 = 0,
@@ -105,6 +110,7 @@ pub fn start(self: *Spinner) void {
self.mu.lock();
defer self.mu.unlock();
self.state = .thinking;
+ self.paused = false;
self.frame = 0;
self.tool_calls = 0;
self.turn_started_ns = std.time.nanoTimestamp();
@@ -143,6 +149,7 @@ pub fn stop(self: *Spinner) void {
_ = std.posix.write(std.posix.STDERR_FILENO, summary) catch {};
self.state = .idle;
+ self.paused = false;
self.last_render_len = 0;
}
@@ -155,9 +162,25 @@ pub fn cancel(self: *Spinner) void {
if (self.state == .idle) return;
_ = std.posix.write(std.posix.STDERR_FILENO, "\r" ++ clear_eol) catch {};
self.state = .idle;
+ self.paused = false;
self.last_render_len = 0;
}
+/// Clear the current frame and stop rendering without ending the turn, so the
+/// caller can stream text to stdout. The next explicit state change
+/// (`setTool`/`stop`/`cancel`/`start`) clears `paused` and resumes the
+/// animation. No-op when idle or already paused.
+pub fn pause(self: *Spinner) void {
+ if (!self.isEnabled()) return;
+ self.mu.lock();
+ defer self.mu.unlock();
+ if (self.state == .idle or self.paused) return;
+ self.paused = true;
+ _ = std.posix.write(std.posix.STDERR_FILENO, "\r" ++ clear_eol) catch {};
+ self.last_render_len = 0;
+ self.cv.signal();
+}
+
/// Switch the indicator to "running tool <name> <args>". Counts toward the
/// turn's tool-call total. Args are truncated to `max_args_bytes`. Called
/// without a preceding `start()` (state `.idle`), the label drops the `agent:`
@@ -166,6 +189,8 @@ pub fn setTool(self: *Spinner, name: []const u8, args: []const u8) void {
if (!self.isEnabled()) return;
self.mu.lock();
defer self.mu.unlock();
+ // A tool call ends any in-progress text stream; resume normal rendering.
+ self.paused = false;
const manual = self.state == .idle;
self.tool_calls += 1;
var tool: ToolState = .{ .set_ns = std.time.nanoTimestamp(), .manual = manual };
@@ -224,7 +249,7 @@ fn workerLoop(self: *Spinner) void {
self.mu.lock();
defer self.mu.unlock();
while (!self.should_exit) {
- while (!self.should_exit and self.state == .idle) self.cv.wait(&self.mu);
+ while (!self.should_exit and (self.state == .idle or self.paused)) self.cv.wait(&self.mu);
if (self.should_exit) return;
switch (self.state) {
diff --git a/src/agent/Terminal.zig b/src/agent/Terminal.zig
index a81716bca..e5c013e62 100644
--- a/src/agent/Terminal.zig
+++ b/src/agent/Terminal.zig
@@ -1336,6 +1336,15 @@ pub fn printAssistant(_: *Terminal, text: []const u8) void {
_ = std.posix.write(fd, "\n") catch {};
}
+/// Write a streamed assistant-text delta verbatim (no trailing newline). The
+/// caller must pause the spinner first (its stderr frames would otherwise
+/// interleave with this stdout text) and emit a closing newline when the
+/// stream ends.
+pub fn printAssistantDelta(_: *Terminal, text: []const u8) void {
+ if (text.len == 0) return;
+ _ = std.posix.write(std.posix.STDOUT_FILENO, text) catch {};
+}
+
// Must exceed the downstream LLM-judge's snapshot window for full grounding
// evidence. Does not cap the agent's own LLM, which gets up to
// tool_output_max_bytes (1 MiB) via Agent.zig:capToolOutput. Bypassed in REPL
diff --git a/src/agent/settings.zig b/src/agent/settings.zig
index 5d00bd2c2..0e59b54ed 100644
--- a/src/agent/settings.zig
+++ b/src/agent/settings.zig
@@ -186,12 +186,14 @@ pub const remembered_path = ".lp-agent.zon";
/// disabled the LLM (`/provider null`), so the REPL starts in basic mode without
/// re-prompting. `effort`/`verbosity` are optional so files predating them still
/// parse; null means "use the mode default" (see `Agent.resolveEffort` /
-/// `Agent.resolveVerbosity`).
+/// `Agent.resolveVerbosity`). `stream` is likewise optional: null means "use the
+/// default" (see `resolveStream`).
pub const Remembered = struct {
provider: ?Config.AiProvider = null,
model: []const u8,
effort: ?Config.Effort = null,
verbosity: ?Config.AgentVerbosity = null,
+ stream: ?bool = null,
};
pub fn loadRemembered(allocator: std.mem.Allocator) ?Remembered {
@@ -269,6 +271,13 @@ pub fn resolveVerbosity(opts: Config.Agent, remembered: ?Remembered) Config.Agen
return Config.agentVerbosity(opts);
}
+/// Precedence: remembered `.lp-agent.zon` value > default (on). Streaming has no
+/// CLI flag — the REPL `/stream` command toggles and persists it.
+pub fn resolveStream(remembered: ?Remembered) bool {
+ if (remembered) |r| if (r.stream) |s| return s;
+ return true;
+}
+
pub const ReconciledModel = union(enum) {
/// Owned by the allocator passed to reconcileModel.
use: []u8,