xonecas.io
64875
Mc

mini-coder / commit 7f3096e

feat: read tool with image input support

xonecas2026-09-22 7f3096e934b5fc48dd9ccabd2624b08b30387577 parent 66c5fd5

8 files changed

AGENTS.md+3−2
@@ -67,8 +67,9 @@ Hard constraints. Do not cross these without explicit direction:
6767 the turn.
6868 - The loop has no compaction, no retries, and no meta-messages between steps.
6969 Provider errors surface as-is, never masked or summarized.
70-- `edit` and `bash` only. No `read` tool — the model reads files through `bash`.
71- Tool arguments are untrusted and validated once at the boundary.
70+- `edit`, `read`, and `bash` only. Tool arguments are untrusted and validated
71+ once at the boundary. `read` returns image blocks only for models that declare
72+ image input.
7273 - Interruption: ESC politely pauses at the next step boundary; Ctrl+C cancels the
7374 turn (abort the request, kill the tool's process group, persist the aborted
7475 message); Ctrl+D exits on an empty draft. Completed side effects are never
src/agent.ts+3−2
@@ -12,7 +12,7 @@ import {
1212 type UserMessage,
1313 } from "@earendil-works/pi-ai";
1414 import type { Session } from "./session.ts";
15-import { executeTool, type ToolDetails, type ToolResult } from "./tools/index.ts";
15+import { acceptsImages, executeTool, type ToolDetails, type ToolResult } from "./tools/index.ts";
1616 import type { ToolName } from "./config.ts";
1717
1818 export type Phase = "preparing" | "waitingModel" | "streaming" | "runningTool" | "pausing" | "idle";
@@ -165,6 +165,7 @@ export async function runAgentTurn(run: AgentRun): Promise<void> {
165165 try {
166166 result = await executeTool(tool, call, {
167167 signal,
168+ supportsImages: acceptsImages(run.model),
168169 onOutput: (chunk) => onEvent({ type: "toolOutput", name: call.name, callId: call.id, chunk }),
169170 });
170171 } catch (error) {
@@ -176,7 +177,7 @@ export async function runAgentTurn(run: AgentRun): Promise<void> {
176177 role: "toolResult",
177178 toolCallId: call.id,
178179 toolName: call.name,
179- content: [{ type: "text", text: result.text }],
180+ content: [{ type: "text", text: result.text }, ...(result.images ?? [])],
180181 details: result.details,
181182 isError: result.isError,
182183 timestamp: Date.now(),
src/cli.ts+2−2
@@ -11,7 +11,7 @@ import type {
1111 } from "@earendil-works/pi-ai";
1212 import { loadConfig, resolveModel, type ToolName } from "./config.ts";
1313 import { buildSystemPrompt } from "./prompt.ts";
14-import { toolSchemas } from "./tools/index.ts";
14+import { acceptsImages, toolSchemas } from "./tools/index.ts";
1515 import { Session } from "./session.ts";
1616 import { NO_INTERACTION, runAgentTurn } from "./agent.ts";
1717 import { runTui } from "./tui/tui.ts";
@@ -105,7 +105,7 @@ async function main(): Promise<void> {
105105 models,
106106 model,
107107 systemPrompt: buildSystemPrompt(config),
108- tools: toolSchemas(config.tools),
108+ tools: toolSchemas(config.tools, acceptsImages(model)),
109109 toolNames: config.tools,
110110 thinkingEffort: config.thinkingEffort,
111111 session,
src/config.ts+2−2
@@ -17,7 +17,7 @@ import { googleGenerativeAIApi } from "@earendil-works/pi-ai/api/google-generati
1717 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
1818 import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
1919
20-const ToolNameSchema = Type.Union([Type.Literal("edit"), Type.Literal("bash")]);
20+const ToolNameSchema = Type.Union([Type.Literal("edit"), Type.Literal("read"), Type.Literal("bash")]);
2121 export type ToolName = Static<typeof ToolNameSchema>;
2222
2323 const CustomApiSchema = Type.Union([
@@ -47,7 +47,7 @@ const ConfigSchema = Type.Object(
4747 systemPrompt: Type.String({ default: "" }),
4848 discoverAgentFiles: Type.Boolean({ default: true }),
4949 skillsDirs: Type.Array(Type.String(), { default: [] }),
50- tools: Type.Array(ToolNameSchema, { default: ["edit", "bash"] }),
50+ tools: Type.Array(ToolNameSchema, { default: ["edit", "read", "bash"] }),
5151 provider: Type.String(),
5252 model: Type.String(),
5353 thinkingEffort: Type.Union(
src/tools/common.ts+5−1
@@ -1,8 +1,10 @@
1-import type { Static, TSchema } from "@earendil-works/pi-ai";
1+import type { ImageContent, Static, TSchema } from "@earendil-works/pi-ai";
22 import { Value } from "typebox/value";
33
44 export interface ToolContext {
55 signal: AbortSignal;
6+ /** Whether the current model accepts image input. */
7+ supportsImages: boolean;
68 onOutput?: (chunk: string) => void;
79 }
810
@@ -16,6 +18,8 @@ export interface ToolResult {
1618 text: string;
1719 isError: boolean;
1820 details?: ToolDetails;
21+ /** Image blocks appended to the tool result, after `text`. */
22+ images?: ImageContent[];
1923 }
2024
2125 export function parseArgs<T extends TSchema>(schema: T, value: unknown): Static<T> {
src/tools/index.ts+33−17
@@ -1,33 +1,49 @@
1-import type { Tool, ToolCall } from "@earendil-works/pi-ai";
1+import type { Api, Model, Tool, ToolCall } from "@earendil-works/pi-ai";
22 import type { ToolName } from "../config.ts";
33 import { parseArgs, type ToolContext, type ToolResult } from "./common.ts";
44 import { BASH_PARAMS, bash } from "./bash.ts";
55 import { EDIT_PARAMS, edit } from "./edit.ts";
6+import { READ_PARAMS, read } from "./read.ts";
67
78 export type { ToolContext, ToolDetails, ToolResult } from "./common.ts";
89
9-const TOOL_SCHEMAS: Record<ToolName, Tool> = {
10- edit: {
11- name: "edit",
12- description:
13- "Edit a file by exact text replacement. oldText must occur exactly once. " +
14- "With empty oldText, create a new file (fails if it exists).",
15- parameters: EDIT_PARAMS,
16- },
17- bash: {
18- name: "bash",
19- description: "Run a bash command in the current working directory.",
20- parameters: BASH_PARAMS,
21- },
22-};
10+/** Whether a model accepts image input. Drives `read`'s description and results. */
11+export function acceptsImages(model: Model<Api>): boolean {
12+ return model.input.includes("image");
13+}
14+
15+const READ_DESCRIPTION = "Read a file. Returns its text. Prefer bash for search, ranges, or binary files.";
16+const READ_IMAGE_DESCRIPTION =
17+ "Read a file. Returns its text, or the image itself when the file is a png, jpg, gif, or webp. " +
18+ "Prefer bash for search, ranges, or binary files.";
2319
24-export function toolSchemas(names: ToolName[]): Tool[] {
25- return names.map((name) => TOOL_SCHEMAS[name]);
20+export function toolSchemas(names: ToolName[], withImages: boolean): Tool[] {
21+ const tools: Record<ToolName, Tool> = {
22+ edit: {
23+ name: "edit",
24+ description:
25+ "Edit a file by exact text replacement. oldText must occur exactly once. " +
26+ "With empty oldText, create a new file (fails if it exists).",
27+ parameters: EDIT_PARAMS,
28+ },
29+ read: {
30+ name: "read",
31+ description: withImages ? READ_IMAGE_DESCRIPTION : READ_DESCRIPTION,
32+ parameters: READ_PARAMS,
33+ },
34+ bash: {
35+ name: "bash",
36+ description: "Run a bash command in the current working directory.",
37+ parameters: BASH_PARAMS,
38+ },
39+ };
40+ return names.map((name) => tools[name]);
2641 }
2742
2843 export function executeTool(name: ToolName, call: ToolCall, ctx: ToolContext): Promise<ToolResult> {
2944 try {
3045 if (name === "edit") return Promise.resolve(edit(parseArgs(EDIT_PARAMS, call.arguments), ctx.signal));
46+ if (name === "read") return Promise.resolve(read(parseArgs(READ_PARAMS, call.arguments), ctx));
3147 return bash(parseArgs(BASH_PARAMS, call.arguments), ctx);
3248 } catch (error) {
3349 return Promise.resolve({ text: (error as Error).message, isError: true });
src/tools/read.ts+65−0
@@ -0,0 +1,65 @@
1+import { readFileSync } from "node:fs";
2+import { extname } from "node:path";
3+import { Type, type Static } from "@earendil-works/pi-ai";
4+import type { ToolContext, ToolResult } from "./common.ts";
5+
6+export const READ_PARAMS = Type.Object(
7+ { path: Type.String({ description: "File path" }) },
8+ { additionalProperties: false },
9+);
10+export type ReadArgs = Static<typeof READ_PARAMS>;
11+
12+const IMAGE_MIME: Record<string, string> = {
13+ png: "image/png",
14+ jpg: "image/jpeg",
15+ jpeg: "image/jpeg",
16+ gif: "image/gif",
17+ webp: "image/webp",
18+};
19+
20+const MAX_TEXT_CHARS = 100_000;
21+/** Cap on the base64 payload sent to the provider, where the file inflates by 4/3. */
22+const MAX_IMAGE_BASE64_BYTES = 5 * 1024 * 1024;
23+
24+export function read(args: ReadArgs, ctx: ToolContext): ToolResult {
25+ const { path } = args;
26+
27+ let data: Buffer;
28+ try {
29+ data = readFileSync(path);
30+ } catch (error) {
31+ return { text: `read failed: ${(error as Error).message}`, isError: true };
32+ }
33+
34+ const mime = IMAGE_MIME[extname(path).slice(1).toLowerCase()];
35+ if (mime !== undefined) {
36+ if (!ctx.supportsImages) {
37+ return { text: `read failed: ${path} is an image and the current model does not accept image input`, isError: true };
38+ }
39+ const base64 = data.toString("base64");
40+ if (base64.length > MAX_IMAGE_BASE64_BYTES) {
41+ return {
42+ text: `read failed: ${path} encodes to ${base64.length} bytes, over the ${MAX_IMAGE_BASE64_BYTES} byte image limit`,
43+ isError: true,
44+ };
45+ }
46+ return {
47+ text: `read ${path} (${mime}, ${data.length} bytes)`,
48+ isError: false,
49+ images: [{ type: "image", data: base64, mimeType: mime }],
50+ };
51+ }
52+
53+ if (data.subarray(0, 8000).includes(0)) {
54+ return { text: `read failed: ${path} is binary; use bash (file, xxd)`, isError: true };
55+ }
56+
57+ const text = data.toString("utf8");
58+ if (text.length > MAX_TEXT_CHARS) {
59+ return {
60+ text: text.slice(0, MAX_TEXT_CHARS) + `\n\n... truncated ... ${path} is ${text.length} characters\n`,
61+ isError: false,
62+ };
63+ }
64+ return { text, isError: false };
65+}
src/tui/tui.ts+1−0
@@ -61,6 +61,7 @@ function completeLines(text: string): string[] {
6161 function callSummary(name: string, args: JsonObject): string {
6262 if (name === "bash" && typeof args.command === "string") return args.command.replace(/\s*\n\s*/g, " ");
6363 if (name === "edit" && typeof args.path === "string") return args.path;
64+ if (name === "read" && typeof args.path === "string") return args.path;
6465 return JSON.stringify(args);
6566 }