@nghyane/arcane 0.1.26 → 0.1.28

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.1.28] - 2026-03-08
+
+### Fixed
+
+- Fix edit tool: hashline delete missing `saveForUndo` causing unrecoverable file deletion
+- Fix `any` types on `EditTool` class — replaced with `EditToolDetails`
+- Fix `applyHashlineEdits` mutating caller's input array via splice
+
+## [0.1.27] - 2026-03-08
+
+### Fixed
+
+- Fix GitHub tool: typed API interfaces replacing `any`, cache key collision with different media types, 403 rate limit not retried, `retry-after` NaN crash, raw file detection returning `[object Object]` for JSON files
+- Fix bash timeout misreported as "Command aborted" instead of "Command timed out"
+- Fix unhandled promise rejection crash in interactive bash PTY finalization
+- Reorder HTML render pipeline to native-first, avoiding unnecessary network calls to jina.ai
+
+### Changed
+
+- Add GitHub tool guidance to system prompt
+- Remove dead code: `normalizeBashCommand`, `expandSkillUrls`, `BashToolOptions`, `isInteractiveResult`
+
 ## [0.1.26] - 2026-03-08
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@nghyane/arcane",
-	"version": "0.1.26",
+	"version": "0.1.28",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/nghyane/arcane",
 	"author": "Can Bölük",

package/src/exec/bash-executor.ts

@@ -27,6 +27,7 @@ export interface BashResult {
 	output: string;
 	exitCode: number | undefined;
 	cancelled: boolean;
+	timedOut: boolean;
 	truncated: boolean;
 	totalLines: number;
 	totalBytes: number;
@@ -44,11 +45,8 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	const { shell, env: shellEnv, prefix } = settings.getShellConfig();
 	const snapshotPath = shell.includes("bash") ? await getOrCreateSnapshot(shell, shellEnv) : null;
 
-	// Apply command prefix if configured
 	const prefixedCommand = prefix ? `${prefix} ${command}` : command;
-	const finalCommand = prefixedCommand;
 
-	// Create output sink for truncation and artifact handling
 	const sink = new OutputSink({
 		onChunk: options?.onChunk,
 		artifactPath: options?.artifactPath,
@@ -64,6 +62,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		return {
 			exitCode: undefined,
 			cancelled: true,
+			timedOut: false,
 			...(await sink.dump("Command cancelled")),
 		};
 	}
@@ -96,7 +95,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	try {
 		const runPromise = shellSession.run(
 			{
-				command: finalCommand,
+				command: prefixedCommand,
 				cwd: options?.cwd,
 				env: options?.env ? { ...NON_INTERACTIVE_ENV, ...options.env } : NON_INTERACTIVE_ENV,
 				timeoutMs: options?.timeout,
@@ -121,11 +120,11 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			return {
 				exitCode: undefined,
 				cancelled: true,
+				timedOut: true,
 				...(await sink.dump(`Command exceeded hard timeout after ${Math.round(hardTimeoutMs / 1000)} seconds`)),
 			};
 		}
 
-		// Handle timeout
 		if (winner.result.timedOut) {
 			const annotation = options?.timeout
 				? `Command timed out after ${Math.round(options.timeout / 1000)} seconds`
@@ -133,25 +132,26 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			resetSession = true;
 			return {
 				exitCode: undefined,
-				cancelled: true,
+				cancelled: false,
+				timedOut: true,
 				...(await sink.dump(annotation)),
 			};
 		}
 
-		// Handle cancellation
 		if (winner.result.cancelled) {
 			resetSession = true;
 			return {
 				exitCode: undefined,
 				cancelled: true,
+				timedOut: false,
 				...(await sink.dump("Command cancelled")),
 			};
 		}
 
-		// Normal completion
 		return {
 			exitCode: winner.result.exitCode,
 			cancelled: false,
+			timedOut: false,
 			...(await sink.dump()),
 		};
 	} catch (err) {

package/src/patch/edit-tool.ts

@@ -134,13 +134,21 @@ function mergeDiagnosticsWithWarnings(
 	};
 }
 
-export class EditTool implements AgentTool<TInput, any, Theme> {
+export class EditTool implements AgentTool<TInput, EditToolDetails, Theme> {
 	readonly name = "edit";
 	readonly label = "Edit";
 	readonly nonAbortable = true;
 	readonly concurrency = "exclusive";
-	readonly renderCall = editToolRenderer.renderCall as unknown as AgentTool<TInput, any, Theme>["renderCall"];
-	readonly renderResult = editToolRenderer.renderResult as unknown as AgentTool<TInput, any, Theme>["renderResult"];
+	readonly renderCall = editToolRenderer.renderCall as unknown as AgentTool<
+		TInput,
+		EditToolDetails,
+		Theme
+	>["renderCall"];
+	readonly renderResult = editToolRenderer.renderResult as unknown as AgentTool<
+		TInput,
+		EditToolDetails,
+		Theme
+	>["renderResult"];
 
 	readonly #allowFuzzy: boolean;
 	readonly #fuzzyThreshold: number;
@@ -252,6 +260,7 @@ export class EditTool implements AgentTool<TInput, any, Theme> {
 
 			if (deleteFile) {
 				if (await file.exists()) {
+					saveForUndo(absolutePath, await file.text());
 					await file.unlink();
 				}
 				invalidateFsScanAfterDelete(absolutePath);

package/src/patch/hashline.ts

@@ -592,7 +592,7 @@ function autocorrectEscapedTabs(lines: string[]): string[] {
  */
 export function applyHashlineEdits(
 	content: string,
-	edits: HashlineEdit[],
+	edits: readonly HashlineEdit[],
 ): {
 	content: string;
 	firstChangedLine: number | undefined;
@@ -603,6 +603,8 @@ export function applyHashlineEdits(
 		return { content, firstChangedLine: undefined };
 	}
 
+	const mutableEdits: HashlineEdit[] = edits.map(e => ({ ...e, content: [...e.content] }));
+
 	const fileLines = content.split("\n");
 	const hadFinalNewline = content.endsWith("\n");
 	const originalFileLines = [...fileLines];
@@ -612,7 +614,7 @@ export function applyHashlineEdits(
 	const autocorrect = Bun.env.ARCANE_HL_AUTOCORRECT === "1";
 
 	const warnings: string[] = [];
-	for (const edit of edits) {
+	for (const edit of mutableEdits) {
 		const unicodeWarning = detectUnicodeEscapePlaceholders(edit.content);
 		if (unicodeWarning && !warnings.includes(unicodeWarning)) {
 			warnings.push(unicodeWarning);
@@ -622,7 +624,7 @@ export function applyHashlineEdits(
 
 	function collectExplicitlyTouchedLines(): Set<number> {
 		const touched = new Set<number>();
-		for (const edit of edits) {
+		for (const edit of mutableEdits) {
 			switch (edit.op) {
 				case "replace":
 					touched.add(edit.target.line);
@@ -652,7 +654,7 @@ export function applyHashlineEdits(
 		mismatches.push({ line: ref.line, expected: ref.hash, actual: actualHash });
 		return false;
 	}
-	for (const edit of edits) {
+	for (const edit of mutableEdits) {
 		switch (edit.op) {
 			case "replace": {
 				if (!validateRef(edit.target)) continue;
@@ -678,8 +680,8 @@ export function applyHashlineEdits(
 	}
 	const seenEditKeys = new Map<string, number>();
 	const dedupIndices = new Set<number>();
-	for (let i = 0; i < edits.length; i++) {
-		const edit = edits[i];
+	for (let i = 0; i < mutableEdits.length; i++) {
+		const edit = mutableEdits[i];
 		let lineKey: string;
 		switch (edit.op) {
 			case "replace":
@@ -697,13 +699,13 @@ export function applyHashlineEdits(
 		}
 	}
 	if (dedupIndices.size > 0) {
-		for (let i = edits.length - 1; i >= 0; i--) {
-			if (dedupIndices.has(i)) edits.splice(i, 1);
+		for (let i = mutableEdits.length - 1; i >= 0; i--) {
+			if (dedupIndices.has(i)) mutableEdits.splice(i, 1);
 		}
 	}
 
 	// Compute sort key (descending) — bottom-up application
-	const annotated = edits.map((edit, idx) => {
+	const annotated = mutableEdits.map((edit, idx) => {
 		let sortLine: number;
 		let precedence: number;
 		switch (edit.op) {

package/src/prompts/system/system-prompt.md

@@ -182,6 +182,16 @@ Tools: `find_thread`, `read_thread`
 - Generic coding question with no project-specific history
 - User explicitly provides all needed context
 
+{{#has tools "github"}}
+### GitHub
+
+Tool: `github`
+Use for **remote** GitHub API calls — repos, issues, PRs, commits, file contents, tree listings. Never use for the local repo; use read/grep/explore for local files.
+- **Use `github`** for: reading issues/PRs, listing commits, fetching files from remote repos, searching repos, getting repo metadata.
+- **Use `librarian`** for: cross-repo exploration, understanding architectural patterns, tracing how other projects solve problems.
+- **Avoid `bash gh`** when `github` covers the action — the tool has caching, pagination, and structured output.
+{{/has}}
+
 ### Verification
 Work incrementally. Make a small change, verify it works, then continue. Prefer a sequence of small, validated edits over one large change. Use commands from AGENTS.md or the project's config to verify. Address all errors caused by your changes before yielding.
 

package/src/tools/bash-interactive.ts

@@ -303,15 +303,29 @@ export async function runInteractiveBashPty(
 				component.setComplete({ exitCode: run.exitCode, cancelled: run.cancelled, timedOut: run.timedOut });
 				tui.requestRender();
 				void (async () => {
-					await component.flushOutput();
-					await pendingChunks;
-					const summary = await sink.dump();
-					done({
-						exitCode: run.exitCode,
-						cancelled: run.cancelled,
-						timedOut: run.timedOut,
-						...summary,
-					});
+					try {
+						await component.flushOutput();
+						await pendingChunks;
+						const summary = await sink.dump();
+						done({
+							exitCode: run.exitCode,
+							cancelled: run.cancelled,
+							timedOut: run.timedOut,
+							...summary,
+						});
+					} catch {
+						done({
+							exitCode: run.exitCode,
+							cancelled: run.cancelled,
+							timedOut: run.timedOut,
+							output: "",
+							truncated: false,
+							totalLines: 0,
+							totalBytes: 0,
+							outputLines: 0,
+							outputBytes: 0,
+						});
+					}
 				})();
 			};
 			const cols = Math.max(20, tui.terminal.columns - 2);

package/src/tools/bash-interceptor.ts

@@ -82,7 +82,6 @@ export function checkBashInterception(
 	availableTools: string[],
 	rules: BashInterceptorRule[] = DEFAULT_BASH_INTERCEPTOR_RULES,
 ): InterceptionResult {
-	// Normalize command for pattern matching
 	const normalizedCommand = command.trim();
 	const compiled = compileRules(rules);
 

package/src/tools/bash-normalize.ts

@@ -1,72 +1,3 @@
-/**
- * Bash command normalizer - extracts patterns that are better handled natively.
- *
- * Detects and extracts:
- * - `| head -n N` / `| head -N` - extracted to headLines
- * - `| tail -n N` / `| tail -N` - extracted to tailLines
- */
-
-interface NormalizedCommand {
-	/** Cleaned command with patterns stripped */
-	command: string;
-	/** Extracted head line count, if any */
-	headLines?: number;
-	/** Extracted tail line count, if any */
-	tailLines?: number;
-}
-
-/**
- * Pattern to match trailing pipe to head/tail.
- * Captures: full match, command (head/tail), line count
- *
- * Matches:
- * - `| head -n 50`
- * - `| head -50`
- * - `| tail -n 100`
- * - `| tail -100`
- *
- * Does NOT match head/tail with other flags or without line count.
- */
-const TRAILING_HEAD_TAIL_PATTERN = /\|\s*(head|tail)\s+(?:-n\s*(\d+)|(-\d+))\s*$/;
-
-/**
- * Normalize a bash command by stripping patterns better handled natively.
- *
- * Extracts `| head -n N` and `| tail -n N` suffixes into separate fields
- * so they can be applied post-execution without breaking streaming.
- *
- * Strips `2>&1` since we already merge stdout/stderr.
- */
-export function normalizeBashCommand(command: string): NormalizedCommand {
-	let normalized = command;
-	let headLines: number | undefined;
-	let tailLines: number | undefined;
-
-	// Extract trailing head/tail
-	const match = normalized.match(TRAILING_HEAD_TAIL_PATTERN);
-	if (match) {
-		const [fullMatch, cmd, nValue, dashValue] = match;
-		const lineCount = nValue ? Number.parseInt(nValue, 10) : Number.parseInt(dashValue.slice(1), 10);
-
-		if (cmd === "head") {
-			headLines = lineCount;
-		} else {
-			tailLines = lineCount;
-		}
-
-		normalized = normalized.slice(0, -fullMatch.length);
-	}
-
-	// Preserve internal whitespace (important for heredocs / indentation-sensitive scripts)
-	normalized = normalized.trim();
-
-	return {
-		command: normalized,
-		headLines,
-		tailLines,
-	};
-}
-
 /**
  * Apply head/tail limits to output text.
  *
@@ -86,13 +17,11 @@ export function applyHeadTail(
 	let headApplied: number | undefined;
 	let tailApplied: number | undefined;
 
-	// Apply head first (keep first N lines)
 	if (headLines !== undefined && headLines > 0 && lines.length > headLines) {
 		lines = lines.slice(0, headLines);
 		headApplied = headLines;
 	}
 
-	// Then apply tail (keep last N lines)
 	if (tailLines !== undefined && tailLines > 0 && lines.length > tailLines) {
 		lines = lines.slice(-tailLines);
 		tailApplied = tailLines;

package/src/tools/bash-skill-urls.ts

@@ -4,9 +4,6 @@ import { validateRelativePath } from "../internal-urls/skill-protocol";
 import type { InternalResource } from "../internal-urls/types";
 import { ToolError } from "./tool-errors";
 
-/** Regex to find skill:// tokens in command text. */
-const SKILL_URL_PATTERN = /'skill:\/\/[^'\s")`\\]+'|"skill:\/\/[^"\s')`\\]+"|skill:\/\/[^\s'")`\\]+/g;
-
 /** Regex to find supported internal URL tokens in command text. */
 const INTERNAL_URL_PATTERN =
 	/'(?:skill|agent|artifact|plan|rule):\/\/[^'\s")`\\]+'|"(?:skill|agent|artifact|plan|rule):\/\/[^"\s')`\\]+"|(?:skill|agent|artifact|plan|rule):\/\/[^\s'")`\\]+/g;
@@ -133,23 +130,6 @@ async function resolveInternalUrlToPath(
 	return path.resolve(resource.sourcePath);
 }
 
-/**
- * Expand all skill:// URIs in a bash command string.
- * Returns the command with URIs replaced by shell-escaped absolute paths.
- * Throws ToolError if any URI cannot be resolved.
- */
-export function expandSkillUrls(command: string, skills: readonly Skill[]): string {
-	if (skills.length === 0 || !command.includes("skill://")) {
-		return command;
-	}
-
-	return command.replace(SKILL_URL_PATTERN, token => {
-		const url = unquoteToken(token);
-		const resolvedPath = resolveSkillUrlToPath(url, skills);
-		return shellEscape(resolvedPath);
-	});
-}
-
 /**
  * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
  * Supported schemes: skill://, agent://, artifact://, plan://, rule://

package/src/tools/bash.ts

@@ -38,20 +38,10 @@ export interface BashToolDetails {
 	meta?: OutputMeta;
 }
 
-export interface BashToolOptions {}
-
 function normalizeResultOutput(result: BashResult | BashInteractiveResult): string {
 	return result.output || "";
 }
 
-function isInteractiveResult(result: BashResult | BashInteractiveResult): result is BashInteractiveResult {
-	return "timedOut" in result;
-}
-/**
- * Bash tool implementation.
- *
- * Executes bash commands with optional timeout and working directory.
- */
 export class BashTool implements AgentTool<typeof bashSchema, BashToolDetails, Theme> {
 	readonly name = "bash";
 	readonly label = "Bash";
@@ -71,11 +61,9 @@ export class BashTool implements AgentTool<typeof bashSchema, BashToolDetails, T
 	): Promise<AgentToolResult<BashToolDetails>> {
 		let command = rawCommand;
 
-		// Only apply explicit head/tail params from tool input.
 		const headLines = head;
 		const tailLines = tail;
 
-		// Check interception if enabled and available tools are known
 		if (this.session.settings.get("bashInterceptor.enabled")) {
 			const rules = this.session.settings.getBashInterceptorRules();
 			const interception = checkBashInterception(command, ctx?.toolNames ?? [], rules);
@@ -103,14 +91,11 @@ export class BashTool implements AgentTool<typeof bashSchema, BashToolDetails, T
 			throw new ToolError(`Working directory is not a directory: ${commandCwd}`);
 		}
 
-		// Clamp to reasonable range: 1s - 3600s (1 hour)
 		const timeoutSec = Math.max(1, Math.min(3600, rawTimeout));
 		const timeoutMs = timeoutSec * 1000;
 
-		// Track output for streaming updates (tail only)
 		const tailBuffer = createTailBuffer(DEFAULT_MAX_BYTES);
 
-		// Set up artifacts environment and allocation
 		const artifactsDir = this.session.getArtifactsDir?.();
 		const extraEnv = artifactsDir ? { ARTIFACTS: artifactsDir } : undefined;
 		const { artifactPath, artifactId } = await allocateOutputArtifact(this.session, "bash");
@@ -148,16 +133,15 @@ export class BashTool implements AgentTool<typeof bashSchema, BashToolDetails, T
 						}
 					},
 				});
+		if (result.timedOut) {
+			throw new ToolError(normalizeResultOutput(result) || `Command timed out after ${timeoutSec} seconds`);
+		}
 		if (result.cancelled) {
 			if (signal?.aborted) {
 				throw new ToolAbortError(normalizeResultOutput(result) || "Command aborted");
 			}
 			throw new ToolError(normalizeResultOutput(result) || "Command aborted");
 		}
-		if (isInteractiveResult(result) && result.timedOut) {
-			throw new ToolError(normalizeResultOutput(result) || `Command timed out after ${timeoutSec} seconds`);
-		}
-		// Apply head/tail filtering if specified
 		let outputText = normalizeResultOutput(result);
 		const headTailResult = applyHeadTail(outputText, headLines, tailLines);
 		if (headTailResult.applied) {
@@ -171,7 +155,7 @@ export class BashTool implements AgentTool<typeof bashSchema, BashToolDetails, T
 		if (result.exitCode === undefined) {
 			throw new ToolError(`${outputText}\n\nCommand failed: missing exit status`);
 		}
-		if (result.exitCode !== 0 && result.exitCode !== undefined) {
+		if (result.exitCode !== 0) {
 			throw new ToolError(`${outputText}\n\nCommand exited with code ${result.exitCode}`);
 		}
 

package/src/tools/fetch.ts

@@ -399,25 +399,15 @@ async function renderHtmlToText(
 		signal,
 	};
 
-	// Try jina first (reader API)
 	try {
-		const jinaUrl = `https://r.jina.ai/${url}`;
-		const response = await fetch(jinaUrl, {
-			headers: { Accept: "text/markdown" },
-			signal,
-		});
-		if (response.ok) {
-			const content = await response.text();
-			if (content.trim().length > 100 && !isLowQualityOutput(content)) {
-				return { content, ok: true, method: "jina" };
-			}
+		const content = await htmlToMarkdown(html, { cleanContent: true });
+		if (content.trim().length > 100 && !isLowQualityOutput(content)) {
+			return { content, ok: true, method: "native" };
 		}
 	} catch {
-		// Jina failed, continue to next method
 		signal?.throwIfAborted();
 	}
 
-	// Try trafilatura (auto-install via uv/pip)
 	const trafilatura = await ensureTool("trafilatura", { signal, silent: true });
 	if (trafilatura) {
 		const result = await ptree.exec([trafilatura, "-u", url, "--output-format", "markdown"], execOptions);
@@ -426,7 +416,6 @@ async function renderHtmlToText(
 		}
 	}
 
-	// Try lynx (can't auto-install, system package)
 	const lynx = hasCommand("lynx");
 	if (lynx) {
 		const result = await ptree.exec(["lynx", "-dump", "-nolist", "-width", "250", url], execOptions);
@@ -435,14 +424,19 @@ async function renderHtmlToText(
 		}
 	}
 
-	// Fall back to native converter (fastest, no network/subprocess)
 	try {
-		const content = await htmlToMarkdown(html, { cleanContent: true });
-		if (content.trim().length > 100 && !isLowQualityOutput(content)) {
-			return { content, ok: true, method: "native" };
+		const jinaUrl = `https://r.jina.ai/${url}`;
+		const response = await fetch(jinaUrl, {
+			headers: { Accept: "text/markdown" },
+			signal,
+		});
+		if (response.ok) {
+			const content = await response.text();
+			if (content.trim().length > 100 && !isLowQualityOutput(content)) {
+				return { content, ok: true, method: "jina" };
+			}
 		}
 	} catch {
-		// Native converter failed, continue to next method
 		signal?.throwIfAborted();
 	}
 	return { content: "", ok: false, method: "none" };

package/src/tools/github.ts

@@ -6,9 +6,107 @@ import type { ToolSession } from ".";
 import { type OutputMeta, toolResult } from "./output-meta";
 
 // =============================================================================
-// Schema
+// GitHub API Types
 // =============================================================================
 
+interface GitHubUser {
+	login: string;
+}
+
+interface GitHubLabel {
+	name: string;
+}
+
+interface GitHubLicense {
+	spdx_id: string;
+}
+
+interface GitHubRepo {
+	full_name: string;
+	description: string | null;
+	default_branch: string;
+	language: string | null;
+	stargazers_count: number;
+	forks_count: number;
+	topics: string[];
+	license: GitHubLicense | null;
+	created_at: string;
+	updated_at: string;
+	homepage: string | null;
+}
+
+interface GitHubTreeEntry {
+	type: string;
+	path?: string;
+	name?: string;
+	size?: number;
+}
+
+interface GitHubIssue {
+	number: number;
+	title: string;
+	state: string;
+	user: GitHubUser | null;
+	labels: GitHubLabel[];
+	assignees: GitHubUser[];
+	body: string | null;
+	created_at: string;
+	pull_request?: unknown;
+}
+
+interface GitHubComment {
+	user: GitHubUser | null;
+	created_at: string;
+	body: string | null;
+}
+
+interface GitHubPR {
+	number: number;
+	title: string;
+	state: string;
+	merged: boolean;
+	merged_at: string | null;
+	user: GitHubUser | null;
+	base: { ref: string };
+	head: { ref: string };
+	changed_files: number | null;
+	additions: number;
+	deletions: number;
+	body: string | null;
+}
+
+interface GitHubCommitAuthor {
+	name: string;
+	email: string;
+	date: string;
+}
+
+interface GitHubCommitFile {
+	status: string;
+	filename: string;
+	additions: number;
+	deletions: number;
+}
+
+interface GitHubCommit {
+	sha: string;
+	commit: {
+		author: GitHubCommitAuthor;
+		message: string;
+	};
+	author: GitHubUser | null;
+	stats?: { total: number; additions: number; deletions: number };
+	files?: GitHubCommitFile[];
+}
+
+interface GitHubSearchResult<T> {
+	total_count: number;
+	items: T[];
+}
+
+// =============================================================================
+// Schema
+// =============================================================================
 const ActionEnum = Type.Union([
 	Type.Literal("get_repo"),
 	Type.Literal("get_file"),
@@ -55,7 +153,7 @@ export interface GitHubToolDetails {
 // Response Formatters
 // =============================================================================
 
-function formatRepo(data: any): string {
+function formatRepo(data: GitHubRepo): string {
 	return [
 		`# ${data.full_name}`,
 		data.description ? `${data.description}` : "",
@@ -72,7 +170,7 @@ function formatRepo(data: any): string {
 		.join("\n");
 }
 
-function formatTreeEntry(entry: any): string {
+function formatTreeEntry(entry: GitHubTreeEntry): string {
 	const icon = entry.type === "dir" || entry.type === "tree" ? "dir" : "file";
 	const size = entry.size ? ` (${formatSize(entry.size)})` : "";
 	const name = entry.path ?? entry.name;
@@ -85,12 +183,12 @@ function formatSize(bytes: number): string {
 	return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
 }
 
-function formatIssue(data: any, comments: any[] = []): string {
+function formatIssue(data: GitHubIssue, comments: GitHubComment[] = []): string {
 	const lines = [
 		`# #${data.number}: ${data.title}`,
 		`State: ${data.state} | Author: @${data.user?.login} | Created: ${data.created_at}`,
-		data.labels?.length ? `Labels: ${data.labels.map((l: any) => l.name).join(", ")}` : "",
-		data.assignees?.length ? `Assignees: ${data.assignees.map((a: any) => `@${a.login}`).join(", ")}` : "",
+		data.labels?.length ? `Labels: ${data.labels.map(l => l.name).join(", ")}` : "",
+		data.assignees?.length ? `Assignees: ${data.assignees.map(a => `@${a.login}`).join(", ")}` : "",
 		"",
 		data.body ?? "(no description)",
 	].filter(l => l !== "");
@@ -102,12 +200,12 @@ function formatIssue(data: any, comments: any[] = []): string {
 	return lines.join("\n");
 }
 
-function formatIssueMinimal(issue: any): string {
-	const labels = issue.labels?.length ? ` [${issue.labels.map((l: any) => l.name).join(", ")}]` : "";
+function formatIssueMinimal(issue: GitHubIssue): string {
+	const labels = issue.labels?.length ? ` [${issue.labels.map(l => l.name).join(", ")}]` : "";
 	return `#${issue.number} [${issue.state}] ${issue.title}${labels} (@${issue.user?.login}, ${issue.created_at})`;
 }
 
-function formatPR(data: any, diff?: string): string {
+function formatPR(data: GitHubPR, diff?: string): string {
 	const lines = [
 		`# PR #${data.number}: ${data.title}`,
 		`State: ${data.state}${data.merged ? " (merged)" : ""} | Author: @${data.user?.login}`,
@@ -124,12 +222,12 @@ function formatPR(data: any, diff?: string): string {
 	return lines.join("\n");
 }
 
-function formatPRMinimal(pr: any): string {
+function formatPRMinimal(pr: GitHubPR): string {
 	const merged = pr.merged_at ? " (merged)" : "";
 	return `#${pr.number} [${pr.state}${merged}] ${pr.title} (@${pr.user?.login}, ${pr.base?.ref} <- ${pr.head?.ref})`;
 }
 
-function formatCommit(data: any, diff?: string): string {
+function formatCommit(data: GitHubCommit, diff?: string): string {
 	const lines = [
 		`Commit: ${data.sha}`,
 		`Author: ${data.commit?.author?.name} <${data.commit?.author?.email}>`,
@@ -156,7 +254,7 @@ function formatCommit(data: any, diff?: string): string {
 	return lines.join("\n");
 }
 
-function formatCommitMinimal(c: any): string {
+function formatCommitMinimal(c: GitHubCommit): string {
 	const sha = (c.sha ?? "").slice(0, 7);
 	const msg = (c.commit?.message ?? "").split("\n")[0];
 	const author = c.commit?.author?.name ?? c.author?.login ?? "?";
@@ -164,7 +262,7 @@ function formatCommitMinimal(c: any): string {
 	return `${sha} ${msg} (${author}, ${date})`;
 }
 
-function formatSearchReposResult(data: any): string {
+function formatSearchReposResult(data: GitHubSearchResult<GitHubRepo>): string {
 	const items = data.items ?? [];
 	const lines = [`Found ${data.total_count} repositories (showing ${items.length}):`, ""];
 	for (const item of items) {
@@ -188,7 +286,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 
 	switch (action) {
 		case "get_repo": {
-			const res = await githubClient.request(base, opts);
+			const res = await githubClient.request<GitHubRepo>(base, opts);
 			if (!res.ok) return error(res, "repository");
 			return { text: formatRepo(res.data), url: `https://github.com/${owner}/${repo}` };
 		}
@@ -216,7 +314,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 							blobRes.data.encoding === "base64"
 								? Buffer.from(blobRes.data.content, "base64").toString("utf-8")
 								: blobRes.data.content;
-						res = { data: decoded as any, ok: true, status: 200 };
+						res = { data: decoded as string, ok: true, status: 200 };
 					}
 				}
 			}
@@ -236,10 +334,13 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const treePath = input.path ?? "";
 			if (input.recursive) {
 				const ref = input.ref ?? "HEAD";
-				const res = await githubClient.request<any>(`${base}/git/trees/${ref}?recursive=1`, opts);
+				const res = await githubClient.request<{ tree: GitHubTreeEntry[]; truncated: boolean }>(
+					`${base}/git/trees/${ref}?recursive=1`,
+					opts,
+				);
 				if (!res.ok) return error(res, "tree");
 				const entries = (res.data.tree ?? [])
-					.filter((e: any) => !treePath || e.path.startsWith(treePath))
+					.filter(e => !treePath || (e.path ?? "").startsWith(treePath))
 					.slice(0, 500);
 				return {
 					text: `# Tree: ${owner}/${repo}${treePath ? `/${treePath}` : ""} (recursive)\n\n${entries.map(formatTreeEntry).join("\n")}`,
@@ -247,7 +348,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			}
 			const ref = input.ref ? `?ref=${input.ref}` : "";
 			const endpoint = treePath ? `${base}/contents/${treePath}${ref}` : `${base}/contents${ref}`;
-			const res = await githubClient.request<any[]>(endpoint, opts);
+			const res = await githubClient.request<GitHubTreeEntry[]>(endpoint, opts);
 			if (!res.ok) return error(res, "directory");
 			const entries = Array.isArray(res.data) ? res.data : [res.data];
 			return {
@@ -258,7 +359,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 		case "search_repos": {
 			const q = input.query ?? `${owner}/${repo}`;
 			const perPage = Math.min(input.limit ?? 30, 100);
-			const res = await githubClient.request<any>(
+			const res = await githubClient.request<GitHubSearchResult<GitHubRepo>>(
 				`/search/repositories?q=${encodeURIComponent(q)}&per_page=${perPage}`,
 				opts,
 			);
@@ -270,8 +371,8 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const num = input.number;
 			if (!num) return { text: "Error: 'number' is required for get_issue" };
 			const [issueRes, commentsRes] = await Promise.all([
-				githubClient.request<any>(`${base}/issues/${num}`, opts),
-				githubClient.requestPaginated<any>(`${base}/issues/${num}/comments`, {
+				githubClient.request<GitHubIssue>(`${base}/issues/${num}`, opts),
+				githubClient.requestPaginated<GitHubComment>(`${base}/issues/${num}/comments`, {
 					...opts,
 					perPage: 100,
 					maxPages: MAX_COMMENTS_PAGES,
@@ -291,13 +392,13 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const limit = Math.min(input.limit ?? 100, 500);
 			const perPage = Math.min(limit, 100);
 			const maxPages = Math.ceil(limit / perPage);
-			const res = await githubClient.requestPaginated<any>(`${base}/issues?${params}`, {
+			const res = await githubClient.requestPaginated<GitHubIssue>(`${base}/issues?${params}`, {
 				...opts,
 				perPage,
 				maxPages,
 			});
 			if (!res.ok) return error(res, "issues");
-			const issues = (res.data ?? []).filter((i: any) => !i.pull_request).slice(0, limit);
+			const issues = (res.data ?? []).filter(i => !i.pull_request).slice(0, limit);
 			const header = `${issues.length} issue(s)${issues.length >= limit ? " (limit reached, increase limit for more)" : ""}`;
 			return {
 				text: issues.length ? `${header}\n${issues.map(formatIssueMinimal).join("\n")}` : "No issues found.",
@@ -307,7 +408,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 		case "get_pull": {
 			const num = input.number;
 			if (!num) return { text: "Error: 'number' is required for get_pull" };
-			const prRes = await githubClient.request<any>(`${base}/pulls/${num}`, opts);
+			const prRes = await githubClient.request<GitHubPR>(`${base}/pulls/${num}`, opts);
 			if (!prRes.ok) return error(prRes, `PR #${num}`);
 
 			let diff: string | undefined;
@@ -336,7 +437,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const limit = Math.min(input.limit ?? 100, 500);
 			const perPage = Math.min(limit, 100);
 			const maxPages = Math.ceil(limit / perPage);
-			const res = await githubClient.requestPaginated<any>(`${base}/pulls?${params}`, {
+			const res = await githubClient.requestPaginated<GitHubPR>(`${base}/pulls?${params}`, {
 				...opts,
 				perPage,
 				maxPages,
@@ -356,7 +457,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const limit = Math.min(input.limit ?? 100, 500);
 			const perPage = Math.min(limit, 100);
 			const maxPages = Math.ceil(limit / perPage);
-			const res = await githubClient.requestPaginated<any>(`${base}/commits?${params}`, {
+			const res = await githubClient.requestPaginated<GitHubCommit>(`${base}/commits?${params}`, {
 				...opts,
 				perPage,
 				maxPages,
@@ -372,7 +473,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 		case "get_commit": {
 			const sha = input.sha;
 			if (!sha) return { text: "Error: 'sha' is required for get_commit" };
-			const res = await githubClient.request<any>(`${base}/commits/${sha}`, opts);
+			const res = await githubClient.request<GitHubCommit>(`${base}/commits/${sha}`, opts);
 			if (!res.ok) return error(res, `commit ${sha}`);
 
 			let diff: string | undefined;
@@ -423,7 +524,8 @@ export class GitHubTool implements AgentTool<typeof schema, GitHubToolDetails, T
 	readonly name = "github";
 	readonly label = "GitHub";
 	readonly parameters = schema;
-	description = "Interact with GitHub API: repos, issues, PRs, commits";
+	description =
+		"Interact with GitHub API: repos, issues, PRs, commits. For remote repositories only — use read/grep for local files.";
 
 	constructor(readonly _session: ToolSession) {}
 

package/src/tools/index.ts

@@ -59,7 +59,6 @@ export {
 	BashTool,
 	type BashToolDetails,
 	type BashToolInput,
-	type BashToolOptions,
 } from "./bash";
 export { BrowserTool, type BrowserToolDetails } from "./browser";
 export { exploreConfig } from "./explore";

package/src/web/github-client.ts

@@ -76,8 +76,8 @@ const etagCache = new Map<string, CacheEntry>();
 const CACHE_MAX_SIZE = 200;
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 
-function getCacheKey(endpoint: string): string {
-	return endpoint;
+function getCacheKey(endpoint: string, mediaType?: string): string {
+	return mediaType ? `${endpoint}::${mediaType}` : endpoint;
 }
 
 function pruneCache(): void {
@@ -122,8 +122,7 @@ async function request<T = unknown>(endpoint: string, options: RequestOptions =
 		headers.Accept = options.mediaType;
 	}
 
-	// ETag conditional request
-	const cacheKey = getCacheKey(endpoint);
+	const cacheKey = getCacheKey(endpoint, options.mediaType);
 	const cached = etagCache.get(cacheKey);
 	if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
 		headers["If-None-Match"] = cached.etag;
@@ -177,11 +176,20 @@ async function request<T = unknown>(endpoint: string, options: RequestOptions =
 				}
 
 				// Retry on transient errors
-				if (RETRY_STATUS_CODES.has(response.status) && attempt < MAX_RETRIES) {
+				const isRateLimited =
+					response.status === 429 ||
+					(response.status === 403 && (rateLimit.remaining === 0 || response.headers.has("retry-after")));
+				const isTransient = RETRY_STATUS_CODES.has(response.status) || isRateLimited;
+
+				if (isTransient && attempt < MAX_RETRIES) {
+					await response.text().catch(() => {});
 					const retryAfter = response.headers.get("retry-after");
-					const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.min(1000 * 2 ** attempt, 10_000);
+					const retrySeconds = retryAfter ? parseInt(retryAfter, 10) : Number.NaN;
+					const waitMs = Number.isFinite(retrySeconds)
+						? retrySeconds * 1000
+						: Math.min(1000 * 2 ** attempt, 10_000);
 
-					if (response.status === 429 && rateLimit.remaining === 0) {
+					if (isRateLimited && rateLimit.remaining === 0) {
 						const resetMs = rateLimit.reset * 1000 - Date.now();
 						if (resetMs > 30_000) {
 							return { data: null as T, ok: false, status: response.status, rateLimit };
@@ -197,8 +205,8 @@ async function request<T = unknown>(endpoint: string, options: RequestOptions =
 					return { data: null as T, ok: false, status: response.status, rateLimit };
 				}
 
-				const isRaw = response.headers.get("content-type")?.includes("application/json") === false;
-				const data = (isRaw ? await response.text() : await response.json()) as T;
+				const wantsRaw = options.mediaType !== undefined;
+				const data = (wantsRaw ? await response.text() : await response.json()) as T;
 
 				// Cache with ETag
 				const etag = response.headers.get("etag");