@nghyane/arcane 0.1.25 → 0.1.27

package/src/tools/create-tools.ts

@@ -23,11 +23,10 @@ import { PythonTool } from "./python";
 import { ReadTool } from "./read";
 import { ReadThreadTool } from "./read-thread";
 import { RenderMermaidTool } from "./render-mermaid";
-import { reviewerConfig } from "./reviewer-tool";
-import { SaveMemoryTool } from "./save-memory";
+import { reviewerConfig } from "./reviewer";
 import { SearchCodeTool } from "./search-code";
 import { loadSshTool } from "./ssh";
-import { SubagentTool } from "./subagent-tool";
+import { SubagentTool } from "./subagent";
 import { TodoWriteTool } from "./todo-write";
 import { UndoEditTool } from "./undo-edit";
 import { WriteTool } from "./write";
@@ -60,7 +59,6 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	fetch: s => new FetchTool(s),
 	web_search: () => new SearchTool(),
 	search_code: () => new SearchCodeTool(),
-	save_memory: s => new SaveMemoryTool(s),
 	write: s => new WriteTool(s),
 };
 

package/src/tools/explore.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { SubagentConfig } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent";
 
 const schema = Type.Object({
 	query: Type.String({ description: "What to search for in the codebase" }),

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";
@@ -72,7 +71,6 @@ export {
 	type FindToolOptions,
 } from "./find";
 export { FindThreadTool, type FindThreadToolDetails } from "./find-thread";
-export { setPreferredImageProvider } from "./gemini-image";
 export { GitHubTool, type GitHubToolDetails } from "./github";
 export { GrepTool, type GrepToolDetails, type GrepToolInput } from "./grep";
 export { librarianConfig } from "./librarian";
@@ -86,10 +84,9 @@ export {
 export { ReadTool, type ReadToolDetails, type ReadToolInput } from "./read";
 export { ReadThreadTool, type ReadThreadToolDetails } from "./read-thread";
 export { RenderMermaidTool, type RenderMermaidToolDetails } from "./render-mermaid";
-export { reviewerConfig } from "./reviewer-tool";
-export { SaveMemoryTool, type SaveMemoryToolDetails } from "./save-memory";
+export { reviewerConfig } from "./reviewer";
 export { loadSshTool, type SSHToolDetails, SshTool } from "./ssh";
-export { type SubagentConfig, SubagentTool } from "./subagent-tool";
+export { type SubagentConfig, SubagentTool } from "./subagent";
 export {
 	type TodoItem,
 	TodoWriteTool,

package/src/tools/librarian.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { SubagentConfig } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent";
 
 const schema = Type.Object({
 	query: Type.String({ description: "What to look up across repositories" }),

package/src/tools/oracle.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { SubagentConfig } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent";
 
 const schema = Type.Object({
 	task: Type.String({ description: "Question or task for the oracle to reason about" }),

package/src/tools/render-mermaid.ts

@@ -1,6 +1,12 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
 import { type AsciiRenderOptions, renderMermaidAscii } from "@nghyane/arcane-utils";
 import { type Static, Type } from "@sinclair/typebox";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../theme/theme";
+import { renderStatusLine } from "../tui";
+import { PREVIEW_LIMITS, replaceTabs, TRUNCATE_LENGTHS, truncateToWidth } from "../ui/render-utils";
 import type { ToolSession } from "./index";
 import { allocateOutputArtifact } from "./output-utils";
 
@@ -30,14 +36,15 @@ function sanitizeRenderConfig(config: AsciiRenderOptions | undefined): AsciiRend
 }
 
 export interface RenderMermaidToolDetails {
+	ascii?: string;
 	artifactId?: string;
 }
 
-export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema, RenderMermaidToolDetails> {
+export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema, RenderMermaidToolDetails, Theme> {
 	readonly name = "render_mermaid";
 	readonly label = "RenderMermaid";
 	readonly description =
-		"Convert Mermaid graph source into ASCII diagram output. Returns ASCII diagram text. Saves full output to an artifact URL when artifact storage is available.";
+		"Convert Mermaid graph source into ASCII diagram output. Returns ASCII diagram text. Saves full output to an artifact URL when artifact storage is available. The diagram is displayed directly in the output — do not reproduce it.";
 	readonly parameters = renderMermaidSchema;
 	readonly strict = true;
 
@@ -55,10 +62,59 @@ export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema,
 			await Bun.write(artifactPath, ascii);
 		}
 
-		const artifactLine = artifactId ? `\n\nSaved artifact: artifact://${artifactId}` : "";
 		return {
-			content: [{ type: "text", text: `${ascii}${artifactLine}` }],
-			details: { artifactId },
+			content: [
+				{ type: "text", text: artifactId ? `Saved artifact: artifact://${artifactId}` : "Diagram rendered." },
+			],
+			details: { ascii, artifactId },
 		};
 	}
+
+	renderCall(_args: RenderMermaidParams, options: RenderResultOptions, uiTheme: Theme): Component {
+		const text = renderStatusLine(
+			{
+				icon: "running",
+				spinnerFrame: options.spinnerFrame,
+				title: "RenderMermaid",
+				description: "Rendering diagram…",
+			},
+			uiTheme,
+		);
+		return new Text(text, 0, 0);
+	}
+
+	renderResult(
+		result: {
+			content: Array<{ type: string; text?: string }>;
+			details?: RenderMermaidToolDetails;
+			isError?: boolean;
+		},
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		_args?: RenderMermaidParams,
+	): Component {
+		const icon = result.isError ? "error" : "success";
+		const ascii = result.details?.ascii ?? "";
+		const outputLines = ascii ? ascii.split("\n") : [];
+		const lines: string[] = [];
+
+		const meta: string[] = [];
+		if (outputLines.length > 0) meta.push(`${outputLines.length} lines`);
+		if (result.details?.artifactId) meta.push(`artifact://${result.details.artifactId}`);
+
+		lines.push(renderStatusLine({ icon, title: "RenderMermaid", meta }, uiTheme));
+
+		if (outputLines.length > 0) {
+			const maxLines = options.expanded ? PREVIEW_LIMITS.OUTPUT_EXPANDED : PREVIEW_LIMITS.OUTPUT_COLLAPSED;
+			const displayLines = outputLines.slice(0, maxLines);
+			for (const line of displayLines) {
+				lines.push(uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(line), TRUNCATE_LENGTHS.CONTENT)));
+			}
+			if (outputLines.length > maxLines) {
+				lines.push(uiTheme.fg("dim", `… (${outputLines.length - maxLines} more lines)`));
+			}
+		}
+
+		return new Text(lines.join("\n"), 0, 0);
+	}
 }

package/src/tools/{reviewer-tool.ts → reviewer.ts}

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { SubagentConfig } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent";
 
 const schema = Type.Object({
 	diff_description: Type.String({ description: "Description of the diff or change to review" }),

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");