xonecas.io
79113
Ma

mini-coding-agent / commit 615df27

fix(llm tools): improve descriptions, and move away from string params.

xonecas2026-10-09 615df272c922caa67185a2370cdffa0086227bfa parent 016a8a5

10 files changed

known-issues.md+0−33
@@ -1,33 +0,0 @@
1-# User reports
2-
3-These come from other people using mini. Each report keeps its text and carries
4-the state we last verified it in.
5-
6----
7-
8-> `waiting for provider` state takes longer and longer as a session progresses
9-
10-Something is greatly affecting performance, and it gets worse each subsequent turn.
11-Testes with a fresh session + small prompt and the models answers in miliseconds.
12-
13-At the same time, same model, same provider, same build, with a context of 6%, turns stay in waiting for provider for over 30 seconds at a time.
14-
15-using `btop` to monitor usage during these longs waiting for provider show almost no network activity, 0 cpu and 30mb of memory, seems like the process is just idle. But a curl to the same provider/model/key responds immediatly.
16-
17-Open, not ours. `waiting for provider` covers body build, connect and the
18-provider's time to first token; the counter next to it keeps running, so the
19-process is idle on the socket, not stuck in the agent. curl to
20-opencode-go/deepseek-v4.1-flash: 68k uncached prompt tokens, first token at 2.7s.
21-The same request in the TUI at 75k tokens (8% of 1M) leaves that state in ~2s.
22-A curl that "responds immediately" and a fresh session both carry a small prompt.
23-Pre-fill time at a given context is the provider's, and it grows with the context.
24-
25-> Ocasional TUI freeze during bash calls.
26-
27-Several reports of the TUI freezing on some bash calls not all.
28-
29-Open, not reproduced. Tool output is read with poll() on the turn thread and
30-streamed to the event queue, so the frame loop keeps running while a command is
31-alive: a 4M line `seq`, and snapshots of a 71MB tree, both stayed animated at the
32-capture rate with peak RSS at 61MB. The status line does distinguish the call from
33-the snapshot that brackets it. A report with the command and cwd would help.
src/agent.zig+1−1
@@ -2,7 +2,7 @@ const std = @import("std");
22 const types = @import("types.zig");
33 const api = @import("api.zig");
44 const platform = @import("platform.zig");
5-const tools = @import("tools/index.zig");
5+const tools = @import("tools.zig");
66 const common = @import("tools/common.zig");
77 const session = @import("session.zig");
88 const config = @import("config.zig");
src/main.zig+1−1
@@ -6,7 +6,7 @@ const models = @import("models.zig");
66 const session = @import("session.zig");
77 const types = @import("types.zig");
88 const agent = @import("agent.zig");
9-const tools = @import("tools/index.zig");
9+const tools = @import("tools.zig");
1010 const tui = @import("tui/tui.zig");
1111 const term = @import("tui/term.zig");
1212 const headless = @import("headless.zig");
src/tools.zig+42−0
@@ -0,0 +1,42 @@
1+const std = @import("std");
2+const config = @import("config.zig");
3+const common = @import("tools/common.zig");
4+const spec = @import("tools/spec.zig");
5+const read_tool = @import("tools/read.zig");
6+const edit_tool = @import("tools/edit.zig");
7+const bash_tool = @import("tools/bash.zig");
8+
9+const all = [_]spec.Descriptor{ read_tool.tool, edit_tool.tool, bash_tool.tool };
10+
11+fn byName(name: config.ToolName) ?spec.Descriptor {
12+ for (all) |tool| if (tool.name == name) return tool;
13+ return null;
14+}
15+
16+pub fn execute(a: std.mem.Allocator, scratch: std.mem.Allocator, name: []const u8, args_json: []const u8, ctx: common.Context) common.Result {
17+ for (all) |tool| {
18+ if (!std.mem.eql(u8, name, @tagName(tool.name))) continue;
19+ for (ctx.tools) |enabled| if (enabled == tool.name) return tool.run(a, scratch, args_json, ctx);
20+ break;
21+ }
22+ return .{
23+ .text = std.fmt.allocPrint(a, "unknown tool: {s}", .{name}) catch "unknown tool",
24+ .is_error = true,
25+ };
26+}
27+
28+pub fn json(a: std.mem.Allocator, names: []const config.ToolName, with_images: bool, cwd: []const u8) []const u8 {
29+ const ctx = spec.Describe{ .with_images = with_images, .cwd = cwd };
30+ var out: std.Io.Writer.Allocating = .init(a);
31+ const w = &out.writer;
32+ w.writeByte('[') catch return "[]";
33+ var first = true;
34+ for (names) |name| {
35+ const tool = byName(name) orelse continue;
36+ if (!first) w.writeByte(',') catch return out.written();
37+ first = false;
38+ spec.write(w, a, tool, ctx) catch return out.written();
39+ }
40+ w.writeByte(']') catch return out.written();
41+ return out.written();
42+}
src/tools/bash.zig+23−0
@@ -3,6 +3,7 @@ const platform = @import("../platform.zig");
33 const text = @import("../text.zig");
44 const common = @import("common.zig");
55 const snapshot = @import("snapshot.zig");
6+const spec = @import("spec.zig");
67
78 const max_head = 10_000;
89 const max_tail = 6_000;
@@ -10,6 +11,28 @@ const truncated_marker = "\n\n... output truncated ...\n\n";
1011
1112 const default_timeout_s = 120;
1213
14+const description_fmt =
15+ "Run a bash command and return its combined output.\n\n" ++
16+ "The command runs with `bash -c` starting in {s}, so pipes, redirects, globs, and && work. Use it for " ++
17+ "builds, tests, git, package managers, and file work that read and edit do not cover. The output ends " ++
18+ "with an `exit code:` line. Pass `timeout` (seconds) to change the 120-second limit.";
19+
20+const params = [_]spec.Param{
21+ .{ .name = "command", .kind = .string, .description = "Bash command line to execute." },
22+ .{ .name = "timeout", .kind = .integer, .required = false, .description = "Seconds to allow before the command is killed. Defaults to 120." },
23+};
24+
25+fn describe(a: std.mem.Allocator, ctx: spec.Describe) []const u8 {
26+ return std.fmt.allocPrint(a, description_fmt, .{ctx.cwd}) catch "Run a bash command.";
27+}
28+
29+pub const tool = spec.Descriptor{
30+ .name = .bash,
31+ .description = describe,
32+ .params = &params,
33+ .run = run,
34+};
35+
1336 const Args = struct { command: []const u8, timeout: ?u64 = null };
1437
1538 const Acc = struct {
src/tools/edit.zig+26−0
@@ -4,6 +4,7 @@ const text = @import("../text.zig");
44 const platform = @import("../platform.zig");
55 const diff = @import("../diff.zig");
66 const common = @import("common.zig");
7+const spec = @import("spec.zig");
78
89 const Args = struct {
910 path: []const u8,
@@ -11,6 +12,31 @@ const Args = struct {
1112 newText: []const u8,
1213 };
1314
15+const description =
16+ "Edit a file by replacing exact text.\n\n" ++
17+ "`oldText` must match the file byte-for-byte and occur exactly once; include surrounding lines to make " ++
18+ "it unique. `newText` replaces it. If `oldText` is missing or matches more than once, the edit fails " ++
19+ "without changing anything.\n\n" ++
20+ "To create a new file, pass an empty `oldText`; this fails if the file already exists. The result " ++
21+ "includes a unified diff of the change.";
22+
23+const params = [_]spec.Param{
24+ .{ .name = "path", .kind = .string, .description = "File to edit, or to create when `oldText` is empty." },
25+ .{ .name = "oldText", .kind = .string, .description = "Exact text to replace. Must occur exactly once. Leave empty to create a new file." },
26+ .{ .name = "newText", .kind = .string, .description = "Replacement text." },
27+};
28+
29+fn describe(_: std.mem.Allocator, _: spec.Describe) []const u8 {
30+ return description;
31+}
32+
33+pub const tool = spec.Descriptor{
34+ .name = .edit,
35+ .description = describe,
36+ .params = &params,
37+ .run = run,
38+};
39+
1440 fn fail(a: std.mem.Allocator, comptime fmt: []const u8, args: anytype) common.Result {
1541 return common.fail(a, "edit failed", fmt, args);
1642 }
src/tools/index.zig+0−70
@@ -1,70 +0,0 @@
1-const std = @import("std");
2-const config = @import("../config.zig");
3-const common = @import("common.zig");
4-const read_tool = @import("read.zig");
5-const edit_tool = @import("edit.zig");
6-const bash_tool = @import("bash.zig");
7-
8-const read_params =
9- \\{"type":"object","required":["path"],"properties":{"path":{"type":"string","description":"File path"},"offset":{"type":"integer","description":"First line to return, 1-based"},"range":{"type":"integer","description":"Number of lines to return from offset"}},"additionalProperties":false}
10-;
11-
12-const edit_params =
13- \\{"type":"object","required":["path","oldText","newText"],"properties":{"path":{"type":"string","description":"File path"},"oldText":{"type":"string","description":"Exact text to replace; empty to create a file"},"newText":{"type":"string","description":"Replacement text"}},"additionalProperties":false}
14-;
15-
16-const bash_params =
17- \\{"type":"object","required":["command"],"properties":{"command":{"type":"string","description":"Command to run"},"timeout":{"type":"integer","description":"Timeout in seconds; defaults to 120"}},"additionalProperties":false}
18-;
19-
20-const read_description = "Read a file. Returns its text. Returns the whole file unless offset and range give a line window.";
21-const read_image_description = "Read a file. Returns its text, or the image itself when the file is a png, jpg, or webp. Returns the whole file unless offset and range give a line window.";
22-const edit_description = "Edit a file by exact text replacement. oldText must occur exactly once. With empty oldText, create a new file (fails if it exists).";
23-const bash_description = "Run a bash command. Commands run in dir: {s}";
24-
25-pub fn execute(a: std.mem.Allocator, scratch: std.mem.Allocator, name: []const u8, args_json: []const u8, ctx: common.Context) common.Result {
26- const enabled = for (ctx.tools) |tool| {
27- if (std.mem.eql(u8, name, @tagName(tool))) break true;
28- } else false;
29- if (enabled) {
30- if (std.mem.eql(u8, name, "read")) return read_tool.run(a, scratch, args_json, ctx);
31- if (std.mem.eql(u8, name, "edit")) return edit_tool.run(a, scratch, args_json, ctx);
32- if (std.mem.eql(u8, name, "bash")) return bash_tool.run(a, scratch, args_json, ctx);
33- }
34- return .{
35- .text = std.fmt.allocPrint(a, "unknown tool: {s}", .{name}) catch "unknown tool",
36- .is_error = true,
37- };
38-}
39-
40-fn writeTool(w: *std.Io.Writer, name: config.ToolName, with_images: bool, bash_desc: []const u8) !void {
41- const description = switch (name) {
42- .read => if (with_images) read_image_description else read_description,
43- .edit => edit_description,
44- .bash => bash_desc,
45- };
46- try w.writeAll("{\"name\":");
47- try std.json.Stringify.encodeJsonString(@tagName(name), .{}, w);
48- try w.writeAll(",\"description\":");
49- try std.json.Stringify.encodeJsonString(description, .{}, w);
50- try w.writeAll(",\"parameters\":");
51- try w.writeAll(switch (name) {
52- .read => read_params,
53- .edit => edit_params,
54- .bash => bash_params,
55- });
56- try w.writeByte('}');
57-}
58-
59-pub fn json(a: std.mem.Allocator, names: []const config.ToolName, with_images: bool, cwd: []const u8) []const u8 {
60- const bash_desc = std.fmt.allocPrint(a, bash_description, .{cwd}) catch "Run a bash command in the current working directory.";
61- var out: std.Io.Writer.Allocating = .init(a);
62- const w = &out.writer;
63- w.writeByte('[') catch return "[]";
64- for (names, 0..) |name, i| {
65- if (i > 0) w.writeByte(',') catch return out.written();
66- writeTool(w, name, with_images, bash_desc) catch return out.written();
67- }
68- w.writeByte(']') catch return out.written();
69- return out.written();
70-}
src/tools/read.zig+31−0
@@ -3,6 +3,7 @@ const filesystem = @import("../filesystem.zig");
33 const text = @import("../text.zig");
44 const types = @import("../types.zig");
55 const common = @import("common.zig");
6+const spec = @import("spec.zig");
67
78 const Args = struct {
89 path: []const u8,
@@ -10,6 +11,36 @@ const Args = struct {
1011 range: ?usize = null,
1112 };
1213
14+const description_base =
15+ "Read a file and return its text.\n\n" ++
16+ "Relative paths resolve against the working directory. Prefer this over cat, head, or sed. The whole " ++
17+ "file is returned by default; pass `offset` (the 1-based first line) and/or `range` (the number of " ++
18+ "lines) to read part of it.";
19+
20+const text_description = description_base ++
21+ "\n\nText longer than 100,000 characters is truncated, and binary files are rejected; use bash to read those.";
22+
23+const image_description = description_base ++
24+ "\n\nImages (png, jpg, jpeg, webp) are returned as image content. Text longer than 100,000 characters is " ++
25+ "truncated.";
26+
27+const params = [_]spec.Param{
28+ .{ .name = "path", .kind = .string, .description = "File to read. Relative paths resolve against the working directory." },
29+ .{ .name = "offset", .kind = .integer, .required = false, .description = "First line to return, 1-based. Defaults to the beginning of the file." },
30+ .{ .name = "range", .kind = .integer, .required = false, .description = "Number of lines to return from `offset`. Defaults to the end of the file." },
31+};
32+
33+fn describe(_: std.mem.Allocator, ctx: spec.Describe) []const u8 {
34+ return if (ctx.with_images) image_description else text_description;
35+}
36+
37+pub const tool = spec.Descriptor{
38+ .name = .read,
39+ .description = describe,
40+ .params = &params,
41+ .run = run,
42+};
43+
1344 const image_mime = [_]struct { ext: []const u8, mime: []const u8 }{
1445 .{ .ext = ".png", .mime = "image/png" },
1546 .{ .ext = ".jpg", .mime = "image/jpeg" },
src/tools/spec.zig+50−0
@@ -0,0 +1,50 @@
1+const std = @import("std");
2+const config = @import("../config.zig");
3+const common = @import("common.zig");
4+
5+pub const Kind = enum { string, integer };
6+
7+pub const Param = struct {
8+ name: []const u8,
9+ kind: Kind,
10+ description: []const u8,
11+ required: bool = true,
12+};
13+
14+pub const Describe = struct {
15+ with_images: bool = false,
16+ cwd: []const u8 = "",
17+};
18+
19+pub const Descriptor = struct {
20+ name: config.ToolName,
21+ description: *const fn (std.mem.Allocator, Describe) []const u8,
22+ params: []const Param,
23+ run: *const fn (std.mem.Allocator, std.mem.Allocator, []const u8, common.Context) common.Result,
24+};
25+
26+pub fn write(w: *std.Io.Writer, a: std.mem.Allocator, d: Descriptor, ctx: Describe) std.Io.Writer.Error!void {
27+ try w.writeAll("{\"name\":");
28+ try std.json.Stringify.encodeJsonString(@tagName(d.name), .{}, w);
29+ try w.writeAll(",\"description\":");
30+ try std.json.Stringify.encodeJsonString(d.description(a, ctx), .{}, w);
31+ try w.writeAll(",\"parameters\":{\"type\":\"object\",\"required\":[");
32+ var first = true;
33+ for (d.params) |p| {
34+ if (!p.required) continue;
35+ if (!first) try w.writeByte(',');
36+ first = false;
37+ try std.json.Stringify.encodeJsonString(p.name, .{}, w);
38+ }
39+ try w.writeAll("],\"properties\":{");
40+ for (d.params, 0..) |p, i| {
41+ if (i > 0) try w.writeByte(',');
42+ try std.json.Stringify.encodeJsonString(p.name, .{}, w);
43+ try w.writeAll(":{\"type\":");
44+ try std.json.Stringify.encodeJsonString(@tagName(p.kind), .{}, w);
45+ try w.writeAll(",\"description\":");
46+ try std.json.Stringify.encodeJsonString(p.description, .{}, w);
47+ try w.writeByte('}');
48+ }
49+ try w.writeAll("},\"additionalProperties\":false}}");
50+}
src/tui/tui.zig+1−1
@@ -6,7 +6,7 @@ const session_mod = @import("../session.zig");
66 const types = @import("../types.zig");
77 const agent = @import("../agent.zig");
88 const models_mod = @import("../models.zig");
9-const tools_index = @import("../tools/index.zig");
9+const tools_index = @import("../tools.zig");
1010 const common = @import("../tools/common.zig");
1111 const render = @import("render.zig");
1212 const theme = @import("theme.zig");