From 6f54c78042ee04fff6200bb37349ea443c66e7bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adri=C3=A0=20Arrufat?= <adria.arrufat@gmail.com>
Date: Tue, 9 Jun 2026 08:43:40 +0200
Subject: [PATCH] agent: simplify and clean up code comments

---
 src/agent/Agent.zig        | 11 ++++-------
 src/agent/SlashCommand.zig |  3 +--
 src/agent/Spinner.zig      |  2 +-
 src/agent/Terminal.zig     |  1 -
 4 files changed, 6 insertions(+), 11 deletions(-)

diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index e200e791..ea2e834b 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -318,7 +318,7 @@ fn startSession(self: *Agent) !void {
     self.session.cancel_hook = .{ .context = @ptrCast(self), .check = checkCancel };
 }
 
-// Tool definitions are compile-time constant; project them once per process.
+// Compile-time constant; project them once per process to avoid rebuilding per call.
 var global_tools_storage: [browser_tools.tool_defs.len]ProviderTool = undefined;
 var global_tools_once = std.once(initGlobalTools);
 
@@ -494,7 +494,6 @@ fn runRepl(self: *Agent) void {
         defer arena.deinit();
         const aa = arena.allocator();
 
-        // JS mode: evaluate the whole line against the page, bypassing command parsing.
         if (self.terminal.jsMode()) {
             // `line` keeps the `$LP_*` placeholder so the secret never reaches
             // the recorder; only the evaluated copy is expanded.
@@ -835,8 +834,6 @@ fn handleSave(self: *Agent, arena: std.mem.Allocator, rest: []const u8) void {
         return;
     };
 
-    // With a client, synthesize an idiomatic script from the session intent;
-    // the trailing prompt is optional extra steering.
     if (self.ai_client != null) {
         self.synthesizeSave(arena, parsed.filename, parsed.prompt);
         return;
@@ -1362,12 +1359,12 @@ fn processUserMessage(self: *Agent, input: TurnInput) !?[]const u8 {
     try self.conversation.ensureSystemPrompt();
 
     // Attachments only ride on the very first user turn (just after the
-    // system prompt) — wired into the message's rich `parts`.
+    // system prompt).
     const turn_attachments: ?[]const []const u8 =
         if (self.conversation.messages.items.len == 1) input.attachments else null;
 
-    // Save message count so we can roll back on API failure — otherwise the
-    // failed user turn stays in history and replays on the next attempt.
+    // Roll-back baseline: on API failure the failed user turn would otherwise
+    // stay in history and replay on the next attempt.
     const msg_baseline = self.conversation.messages.items.len;
 
     if (turn_attachments) |paths| {
diff --git a/src/agent/SlashCommand.zig b/src/agent/SlashCommand.zig
index eb6c6d34..2749d347 100644
--- a/src/agent/SlashCommand.zig
+++ b/src/agent/SlashCommand.zig
@@ -27,8 +27,7 @@ const lp = @import("lightpanda");
 const Command = lp.Command;
 const Config = lp.Config;
 
-/// Shared row format for the `/help` listing — `name` is the command name
-/// (no `/`), `description` is a terse one-liner.
+/// Row format for the `/help` listing — `name` carries no leading `/`.
 pub const Help = struct {
     name: []const u8,
     description: []const u8,
diff --git a/src/agent/Spinner.zig b/src/agent/Spinner.zig
index 10256592..65ab62e3 100644
--- a/src/agent/Spinner.zig
+++ b/src/agent/Spinner.zig
@@ -99,7 +99,7 @@ pub fn deinit(self: *Spinner) void {
     }
 }
 
-/// Begin a new agent turn. Spawns the worker thread on first call.
+/// Spawns the worker thread on first call.
 pub fn start(self: *Spinner) void {
     if (!self.isEnabled()) return;
     self.mu.lock();
diff --git a/src/agent/Terminal.zig b/src/agent/Terminal.zig
index f6563b5a..65171a35 100644
--- a/src/agent/Terminal.zig
+++ b/src/agent/Terminal.zig
@@ -86,7 +86,6 @@ pub const CompletionSource = struct {
     models: *const fn (context: *anyopaque, arena: std.mem.Allocator) []const []const u8,
 };
 
-// Flat name list for the "match any slash command" search/completion paths.
 const llm_values = std.enums.values(Command.LlmCommand);
 const all_slash_names: [browser_tools.names.len + SlashCommand.meta_commands.len + llm_values.len][]const u8 = blk: {
     var arr: [browser_tools.names.len + SlashCommand.meta_commands.len + llm_values.len][]const u8 = undefined;