headlesscode 1.0.2

package/src/vendor/zoo-code/types/tool-params.ts

@@ -0,0 +1,116 @@
+/**
+ * Tool parameter type definitions for native protocol
+ */
+
+/**
+ * Read mode for the read_file tool.
+ * - "slice": Simple offset/limit reading (default)
+ * - "indentation": Semantic block extraction based on code structure
+ */
+export type ReadFileMode = "slice" | "indentation"
+
+/**
+ * Indentation-mode configuration for the read_file tool.
+ */
+export interface IndentationParams {
+	/** 1-based line number to anchor indentation extraction (defaults to offset) */
+	anchor_line?: number
+	/** Maximum indentation levels to include above anchor (0 = unlimited) */
+	max_levels?: number
+	/** Include sibling blocks at the same indentation level */
+	include_siblings?: boolean
+	/** Include file header (imports, comments at top) */
+	include_header?: boolean
+	/** Hard cap on lines returned for indentation mode */
+	max_lines?: number
+}
+
+/**
+ * Parameters for the read_file tool (new format).
+ *
+ * NOTE: This is the canonical, single-file-per-call shape.
+ */
+export interface ReadFileParams {
+	/** Path to the file, relative to workspace */
+	path: string
+	/** Reading mode: "slice" (default) or "indentation" */
+	mode?: ReadFileMode
+	/** 1-based line number to start reading from (slice mode, default: 1) */
+	offset?: number
+	/** Maximum number of lines to read (default: 2000) */
+	limit?: number
+	/** Indentation-mode configuration (only used when mode === "indentation") */
+	indentation?: IndentationParams
+}
+
+// ─── Legacy Format Types (Backward Compatibility) ─────────────────────────────
+
+/**
+ * Line range specification for legacy read_file format.
+ * Represents a contiguous range of lines [start, end] (1-based, inclusive).
+ */
+export interface LineRange {
+	start: number
+	end: number
+}
+
+/**
+ * File entry for legacy read_file format.
+ * Supports reading multiple disjoint line ranges from a single file.
+ */
+export interface FileEntry {
+	/** Path to the file, relative to workspace */
+	path: string
+	/** Optional list of line ranges to read (if omitted, reads entire file) */
+	lineRanges?: LineRange[]
+}
+
+/**
+ * Legacy parameters for the read_file tool (pre-refactor format).
+ * Supports reading multiple files in a single call with optional line ranges.
+ *
+ * @deprecated Use ReadFileParams instead. This format is maintained for
+ * backward compatibility with existing chat histories.
+ */
+export interface LegacyReadFileParams {
+	/** Array of file entries to read */
+	files: FileEntry[]
+	/** Discriminant flag for type narrowing */
+	_legacyFormat: true
+}
+
+/**
+ * Union type for read_file tool parameters.
+ * Supports both new single-file format and legacy multi-file format.
+ */
+export type ReadFileToolParams = ReadFileParams | LegacyReadFileParams
+
+/**
+ * Type guard to check if params are in legacy format.
+ */
+export function isLegacyReadFileParams(params: ReadFileToolParams): params is LegacyReadFileParams {
+	// `NativeToolCallParser` always tags freshly parsed legacy calls with `_legacyFormat: true`.
+	// The bare-`files` fallback only matters for chat history persisted before that flag was
+	// introduced (commit cc86049f1) and re-hydrated on a later run. Note that params matched via
+	// that fallback narrow to `LegacyReadFileParams` but leave `_legacyFormat` `undefined`, so
+	// callers should branch on the presence of `files`, not on `_legacyFormat === true`.
+	const hasLegacyFlag = "_legacyFormat" in params && params._legacyFormat === true
+	const hasFilesArray = "files" in params && Array.isArray((params as unknown as Record<string, unknown>).files)
+	return hasLegacyFlag || hasFilesArray
+}
+
+export interface Coordinate {
+	x: number
+	y: number
+}
+
+export interface Size {
+	width: number
+	height: number
+}
+
+export interface GenerateImageParams {
+	prompt: string
+	path: string
+	image?: string
+}

package/src/vendor/zoo-code/types/tool.ts

@@ -0,0 +1,67 @@
+import { z } from "zod"
+
+/**
+ * ToolGroup
+ */
+
+export const toolGroups = ["read", "edit", "command", "mcp", "modes"] as const
+
+export const toolGroupsSchema = z.enum(toolGroups)
+
+/**
+ * Tool groups that have been removed but may still exist in user config files.
+ * Used by schema preprocessing to silently strip these before validation,
+ * preventing errors for users with older configs.
+ */
+export const deprecatedToolGroups: readonly string[] = ["browser"]
+
+export type ToolGroup = z.infer<typeof toolGroupsSchema>
+
+/**
+ * ToolName
+ */
+
+export const toolNames = [
+	"execute_command",
+	"read_file",
+	"read_command_output",
+	"write_to_file",
+	"apply_diff",
+	"edit",
+	"search_and_replace",
+	"search_replace",
+	"edit_file",
+	"apply_patch",
+	"search_files",
+	"list_files",
+	"use_mcp_tool",
+	"access_mcp_resource",
+	"ask_followup_question",
+	"attempt_completion",
+	"switch_mode",
+	"new_task",
+	"codebase_search",
+	"update_todo_list",
+	"run_slash_command",
+	"skill",
+	"generate_image",
+	"custom_tool",
+] as const
+
+export const toolNamesSchema = z.enum(toolNames)
+
+export type ToolName = z.infer<typeof toolNamesSchema>
+
+/**
+ * ToolUsage
+ */
+
+export const toolUsageSchema = z.record(
+	toolNamesSchema,
+	z.object({
+		attempts: z.number(),
+		failures: z.number(),
+	}),
+)
+
+export type ToolUsage = z.infer<typeof toolUsageSchema>

package/src/vendor/zoo-code/types/vscode.ts

@@ -0,0 +1,84 @@
+import { z } from "zod"
+
+/**
+ * CodeAction
+ */
+
+export const codeActionIds = ["explainCode", "fixCode", "improveCode", "addToContext", "newTask"] as const
+
+export type CodeActionId = (typeof codeActionIds)[number]
+
+export type CodeActionName = "EXPLAIN" | "FIX" | "IMPROVE" | "ADD_TO_CONTEXT" | "NEW_TASK"
+
+/**
+ * TerminalAction
+ */
+
+export const terminalActionIds = ["terminalAddToContext", "terminalFixCommand", "terminalExplainCommand"] as const
+
+export type TerminalActionId = (typeof terminalActionIds)[number]
+
+export type TerminalActionName = "ADD_TO_CONTEXT" | "FIX" | "EXPLAIN"
+
+export type TerminalActionPromptType = `TERMINAL_${TerminalActionName}`
+
+/**
+ * Command
+ */
+
+export const commandIds = [
+	"activationCompleted",
+
+	"plusButtonClicked",
+	"historyButtonClicked",
+	"marketplaceButtonClicked",
+	"popoutButtonClicked",
+	"settingsButtonClicked",
+
+	"openInNewTab",
+
+	"newTask",
+
+	"setCustomStoragePath",
+	"importSettings",
+
+	"focusInput",
+	"acceptInput",
+	"focusPanel",
+	"toggleAutoApprove",
+
+	"showRipgrepDiagnostic",
+] as const
+
+export type CommandId = (typeof commandIds)[number]
+
+/**
+ * Language
+ */
+
+export const languages = [
+	"ca",
+	"de",
+	"en",
+	"es",
+	"fr",
+	"hi",
+	"id",
+	"it",
+	"ja",
+	"ko",
+	"nl",
+	"pl",
+	"pt-BR",
+	"ru",
+	"tr",
+	"vi",
+	"zh-CN",
+	"zh-TW",
+] as const
+
+export const languagesSchema = z.enum(languages)
+
+export type Language = z.infer<typeof languagesSchema>
+
+export const isLanguage = (value: string): value is Language => languages.includes(value as Language)

package/src/vision/describe.ts

@@ -0,0 +1,242 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import type { AuxLlmUsage } from "../engine/types.js"
+
+/**
+ * Cloud vision captioning for images — the ONLY image path through this
+ * harness. This is a deliberate, narrow, standalone client (same pattern as
+ * OllamaLocalChatClient in src/engine/local-explore.ts): the main agent loop
+ * and every LlmClient are typed around the text-only ChatMessage shape, so a
+ * multimodal request cannot flow through them. Instead this module makes its
+ * OWN OpenAI-compatible chat-completions call against OpenRouter with an
+ * `image_url` content part, gets back a text description, and that text is
+ * all that ever touches the rest of the system (ToolResult content is
+ * string-only).
+ *
+ * Cost is real and tracked: each call returns the provider's token counts in
+ * AuxLlmUsage, which the executor's onAuxLlmUsage hook forwards to the
+ * session's BudgetTracker + running totals (see recordAuxLlmUsage in
+ * src/engine/loop.ts) — captioning a screenshot shows up in the session's
+ * budget/usage accounting exactly like a regular LLM call.
+ *
+ * Model default (google/gemma-3-12b-it) is the result of the real model
+ * evaluation documented in the imgsupport plan: the cheapest candidate that
+ * produced descriptions with genuinely useful detail (correctly diagnosed a
+ * broken-page screenshot) and no material quality regression vs. the
+ * gemma-3-27b-it quality anchor — which hallucinated detail on the same
+ * image. Override via HEADLESSCODE_VISION_MODEL.
+ */
+
+export const DEFAULT_VISION_MODEL = "google/gemma-3-12b-it"
+
+export const DEFAULT_VISION_TIMEOUT_MS = 60_000
+
+/** Default resolution of the base URL: same OpenRouter endpoint the main
+ *  client uses, overridable via OPENROUTER_BASE_URL like the main client. */
+export function visionBaseUrl(): string {
+	return (process.env.OPENROUTER_BASE_URL ?? "https://openrouter.ai").replace(/\/+$/, "")
+}
+
+export const VISION_SYSTEM_PROMPT = [
+	"You are an image captioning system for a coding agent. Describe the image in concrete, factual",
+	"detail a software engineer can act on. Include:",
+	"- All visible text verbatim where readable: error messages, button labels, headings, URLs, console output.",
+	"- The overall layout and every UI element present (buttons, inputs, dialogs, tables, toggles, images) and their state (disabled, checked, highlighted, empty).",
+	"- Anything that looks wrong: error states, missing content, layout breakage, misalignment, blank areas where content should be.",
+	"- Colors only when they carry meaning (red error text, green success, amber warnings).",
+	"Do not write a vague generic caption, do not speculate about what the image is 'probably' from, and do not invent text you cannot actually read",
+	"- if text is illegible, say it is illegible rather than guessing.",
+].join("\n")
+
+/** Failure from the vision captioning call. Mirrors OpenRouterError's shape
+ *  (message + optional HTTP status + raw body excerpt) so callers can
+ *  distinguish an auth/rate-limit failure from a malformed response. */
+export class VisionError extends Error {
+	constructor(
+		message: string,
+		readonly status?: number,
+		readonly body?: string,
+	) {
+		super(message)
+		this.name = "VisionError"
+	}
+}
+
+export interface DescribeImageResult {
+	description: string
+	/** Real token counts from the provider, for budget/usage accounting. */
+	usage: AuxLlmUsage
+}
+
+export interface DescribeImageOptions {
+	/** Model id. Default: HEADLESSCODE_VISION_MODEL, then DEFAULT_VISION_MODEL. */
+	model?: string
+	/** Reuses HEADLESSCODE_OPENROUTER_API_KEY when omitted. */
+	apiKey?: string
+	/** Reuses OPENROUTER_BASE_URL when omitted. */
+	baseUrl?: string
+	/** Injectable fetch (tests). Defaults to global fetch. */
+	fetchImpl?: typeof fetch
+	timeoutMs?: number
+	/** External abort (e.g. a tool-level deadline). */
+	signal?: AbortSignal
+	systemPrompt?: string
+	maxTokens?: number
+}
+
+function mimeTypeFor(filePath: string): string {
+	const ext = path.extname(filePath).toLowerCase()
+	switch (ext) {
+		case ".jpg":
+		case ".jpeg":
+			return "image/jpeg"
+		case ".webp":
+			return "image/webp"
+		case ".gif":
+			return "image/gif"
+		default:
+			return "image/png"
+	}
+}
+
+/** Caption one image file via OpenRouter's multimodal chat-completions
+ *  endpoint. Reads the file, base64-encodes it into a standard OpenAI-
+ *  compatible `image_url` content part, and returns the description plus the
+ *  real usage. Throws VisionError on any failure (missing file, network,
+ *  HTTP error, malformed response). */
+export async function describeImage(
+	imagePath: string,
+	options: DescribeImageOptions = {},
+): Promise<DescribeImageResult> {
+	const apiKey = options.apiKey ?? process.env.HEADLESSCODE_OPENROUTER_API_KEY
+	if (!apiKey) {
+		throw new VisionError(
+			"HEADLESSCODE_OPENROUTER_API_KEY is not set. Set the environment variable HEADLESSCODE_OPENROUTER_API_KEY to use describeImage (vision captioning).",
+		)
+	}
+	const model = options.model ?? process.env.HEADLESSCODE_VISION_MODEL ?? DEFAULT_VISION_MODEL
+	const baseUrl = (options.baseUrl ?? visionBaseUrl()).replace(/\/+$/, "")
+	const timeoutMs = options.timeoutMs ?? DEFAULT_VISION_TIMEOUT_MS
+	const fetchImpl = options.fetchImpl ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
+	const maxTokens = options.maxTokens ?? 1024
+
+	let imageBuffer: Buffer
+	try {
+		imageBuffer = await readFile(imagePath)
+	} catch (err) {
+		throw new VisionError(
+			`describeImage: cannot read image file ${imagePath}: ${err instanceof Error ? err.message : String(err)}`,
+		)
+	}
+	if (imageBuffer.length === 0) {
+		throw new VisionError(`describeImage: image file ${imagePath} is empty (0 bytes)`)
+	}
+
+	const imageUrl = `data:${mimeTypeFor(imagePath)};base64,${imageBuffer.toString("base64")}`
+	const body = {
+		model,
+		max_tokens: maxTokens,
+		temperature: 0.2,
+		messages: [
+			{ role: "system", content: options.systemPrompt ?? VISION_SYSTEM_PROMPT },
+			{
+				role: "user",
+				content: [
+					{ type: "text", text: "Describe this image in the detail requested." },
+					{ type: "image_url", image_url: { url: imageUrl } },
+				],
+			},
+		],
+	}
+
+	const controller = new AbortController()
+	let timedOut = false
+	const timer = setTimeout(() => {
+		timedOut = true
+		controller.abort()
+	}, timeoutMs)
+	const onExternalAbort = () => controller.abort()
+	options.signal?.addEventListener("abort", onExternalAbort, { once: true })
+
+	let response: Response
+	try {
+		response = await fetchImpl(`${baseUrl}/api/v1/chat/completions`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${apiKey}`,
+				"content-type": "application/json",
+			},
+			signal: controller.signal,
+			body: JSON.stringify(body),
+		})
+	} catch (err) {
+		if (timedOut) {
+			throw new VisionError(`Vision request to OpenRouter timed out after ${timeoutMs}ms`)
+		}
+		if (err instanceof Error && err.name === "AbortError") {
+			throw err // caller-managed external abort
+		}
+		throw new VisionError(
+			`Network error calling OpenRouter vision endpoint: ${err instanceof Error ? err.message : String(err)}`,
+		)
+	} finally {
+		clearTimeout(timer)
+		options.signal?.removeEventListener("abort", onExternalAbort)
+	}
+
+	if (!response.ok) {
+		const rawBody = await response.text().catch(() => "")
+		const excerpt = rawBody.length > 500 ? `${rawBody.slice(0, 500)}…` : rawBody
+		throw new VisionError(
+			`OpenRouter vision request returned HTTP ${response.status}: ${excerpt || "(empty)"}`,
+			response.status,
+			excerpt,
+		)
+	}
+
+	// Same raw-body-first discipline as the main OpenRouter client: 200 does
+	// not guarantee a well-formed choices[] payload.
+	const rawBody = await response.text()
+	let data:
+		| {
+				model?: string
+				choices?: Array<{ message?: { content?: string | null }; finish_reason?: string }>
+				usage?: {
+					prompt_tokens?: number
+					completion_tokens?: number
+					prompt_tokens_details?: { cached_tokens?: number }
+				}
+				error?: { message?: string; code?: unknown }
+		  }
+		| undefined
+	try {
+		data = JSON.parse(rawBody)
+	} catch {
+		const excerpt = rawBody.length > 500 ? `${rawBody.slice(0, 500)}…` : rawBody
+		throw new VisionError(`OpenRouter vision request returned HTTP 200 with a non-JSON/unparseable body: ${excerpt || "(empty)"}`)
+	}
+	if (data?.error) {
+		throw new VisionError(
+			`OpenRouter vision request returned HTTP 200 with an error envelope: ${data.error.message ?? JSON.stringify(data.error)}`,
+		)
+	}
+	const description = data?.choices?.[0]?.message?.content
+	if (!data || typeof description !== "string" || description.trim() === "") {
+		const finishReason = data?.choices?.[0]?.finish_reason
+		const excerpt = rawBody.length > 500 ? `${rawBody.slice(0, 500)}…` : rawBody
+		throw new VisionError(
+			`OpenRouter vision response contained no choices[0].message.content` +
+				(finishReason ? ` (finish_reason: ${finishReason})` : "") +
+				`. Raw body: ${excerpt || "(empty)"}`,
+		)
+	}
+
+	const usage: AuxLlmUsage = {
+		model: data.model ?? model,
+		inputTokens: data.usage?.prompt_tokens ?? 0,
+		outputTokens: data.usage?.completion_tokens ?? 0,
+		cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
+	}
+
+	return { description, usage }
+}

package/src/vision/tool.ts

@@ -0,0 +1,91 @@
+/**
+ * `describe_image` — a general-purpose captioning tool for ANY image already
+ * in the workspace (not just fresh browser screenshots): screenshots the
+ * harness or a repo already contains, dashboard-uploaded images (a follow-up
+ * feature), diagrams, design mockups. Schema is a single `path` relative to
+ * the workspace root; path safety reuses `resolveWithinWorkspace`'s existing
+ * guard (src/tools/executor.ts) rather than re-deriving it.
+ *
+ * The description is generated by the same cloud vision call as the
+ * screenshot auto-captioning (src/vision/describe.ts) and the real token/cost
+ * is reported back through `ToolContext.onAuxLlmUsage` so the session's
+ * BudgetTracker + usage accounting sees it (see recordAuxLlmUsage in
+ * src/engine/loop.ts) — an explicit describe_image call is never invisible
+ * spend.
+ */
+
+import { constants } from "node:fs"
+import { access } from "node:fs/promises"
+
+import type OpenAI from "openai"
+
+import type { ToolContext, ToolResult } from "../engine/types.js"
+import { resolveWithinWorkspace } from "../tools/executor.js"
+import { describeImage } from "./describe.js"
+
+export const DESCRIBE_IMAGE_NAME = "describe_image"
+
+const DESCRIBE_IMAGE_DESCRIPTION = `Request to describe an image file that already exists in the workspace (PNG/JPEG/WebP/GIF): reads the file and returns a detailed, factual text description generated by a cloud vision model — visible text verbatim, layout, UI element states, colors that carry meaning, and anything that looks visually wrong. This is a one-way image -> text conversion: the description is what reaches the coding model, never the raw image bytes.
+
+Use this when a task references an image already present in the repo/workspace and you need to know what it actually shows (e.g. a screenshot checked into the repo, a diagram, a broken-page capture, a design mockup). Do NOT use it for screenshots you took yourself with browser_action — those are already auto-described in the screenshot result. One describe_image call costs a small real amount of money (an LLM API call); use it deliberately, not speculatively.`
+
+const PATH_PARAMETER_DESCRIPTION = `Path to the image file, relative to the workspace root (e.g. "docs/diagram.png" or ".headlesscode/browser-screenshots/screenshot-2026-08-02T00-00-00-000Z.png").`
+
+export const describeImageTool = {
+	type: "function",
+	function: {
+		name: DESCRIBE_IMAGE_NAME,
+		description: DESCRIBE_IMAGE_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: PATH_PARAMETER_DESCRIPTION,
+				},
+			},
+			required: ["path"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+function ok(content: string): ToolResult {
+	return { content, isError: false }
+}
+
+function err(content: string): ToolResult {
+	return { content: `[Error] ${content}`, isError: true }
+}
+
+export async function describeImageHandler(
+	args: Record<string, unknown>,
+	ctx: ToolContext,
+): Promise<ToolResult> {
+	const p = args.path
+	if (typeof p !== "string" || p.trim() === "") {
+		return err(`describe_image: missing or invalid string argument 'path' (got ${JSON.stringify(p)})`)
+	}
+
+	let abs: string
+	try {
+		abs = resolveWithinWorkspace(ctx.workspaceRoot, p)
+	} catch (e) {
+		return err(`describe_image: ${e instanceof Error ? e.message : String(e)}`)
+	}
+
+	try {
+		await access(abs, constants.F_OK)
+	} catch {
+		return err(`describe_image: no such file: ${p} (resolved to ${abs})`)
+	}
+
+	try {
+		const { description, usage } = await describeImage(abs)
+		ctx.onAuxLlmUsage?.(usage)
+		return ok(`describe_image: ${p}\n${description}`)
+	} catch (e) {
+		return err(`describe_image: ${e instanceof Error ? e.message : String(e)}`)
+	}
+}