@nghyane/arcane 0.1.28 → 0.1.30

package/src/session/compaction/branch-summarization.ts

@@ -10,17 +10,12 @@ import { completeSimple } from "@nghyane/arcane-ai";
 import { renderPromptTemplate } from "../../config/prompt-templates";
 import branchSummaryPrompt from "../../prompts/compaction/branch-summary.md" with { type: "text" };
 import branchSummaryPreamble from "../../prompts/compaction/branch-summary-preamble.md" with { type: "text" };
-import {
-	convertToLlm,
-	createBranchSummaryMessage,
-	createCompactionSummaryMessage,
-	createCustomMessage,
-} from "../../session/messages";
+import { convertToLlm, createBranchSummaryMessage, createCustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionEntry } from "../../session/session-manager";
-import { estimateTokens } from "./compaction";
 import {
 	computeFileLists,
 	createFileOps,
+	estimateTokens,
 	extractFileOpsFromMessage,
 	type FileOperations,
 	SUMMARIZATION_SYSTEM_PROMPT,
@@ -85,7 +80,7 @@ export interface GenerateBranchSummaryOptions {
  * Collect entries that should be summarized when navigating from one position to another.
  *
  * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
- * along the way. Does NOT stop at compaction boundaries - those are included and their
+ * along the way.
  * summaries become context.
  *
  * @param session - Session manager (read-only access)
@@ -139,7 +134,7 @@ export function collectEntriesForBranchSummary(
 
 /**
  * Extract AgentMessage from a session entry.
- * Similar to getMessageFromEntry in compaction.ts but also handles compaction entries.
+ * Extract AgentMessage from a session entry.
  */
 function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 	switch (entry.type) {
@@ -154,9 +149,6 @@ function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 		case "branch_summary":
 			return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
 
-		case "compaction":
-			return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp, entry.shortSummary);
-
 		// These don't contribute to conversation content
 		case "thinking_level_change":
 		case "model_change":
@@ -216,7 +208,7 @@ export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: numbe
 		// Check budget before adding
 		if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {
 			// If this is a summary entry, try to fit it anyway as it's important context
-			if (entry.type === "compaction" || entry.type === "branch_summary") {
+			if (entry.type === "branch_summary") {
 				if (totalTokens < tokenBudget * 0.9) {
 					messages.unshift(message);
 					totalTokens += tokens;

package/src/session/compaction/index.ts

@@ -3,5 +3,4 @@
  */
 
 export * from "./branch-summarization";
-export * from "./compaction";
 export * from "./utils";

package/src/session/compaction/utils.ts

@@ -1,8 +1,8 @@
 /**
- * Shared utilities for compaction and branch summarization.
+ * Shared utilities for branch summarization.
  */
 import type { AgentMessage } from "@nghyane/arcane-agent";
-import type { Message } from "@nghyane/arcane-ai";
+import type { AssistantMessage, Message, Usage } from "@nghyane/arcane-ai";
 import { renderPromptTemplate } from "../../config/prompt-templates";
 import fileOperationsTemplate from "../../prompts/system/file-operations.md" with { type: "text" };
 import summarizationSystemPrompt from "../../prompts/system/summarization-system.md" with { type: "text" };
@@ -169,3 +169,95 @@ export function serializeConversation(messages: Message[]): string {
 // ============================================================================
 
 export const SUMMARIZATION_SYSTEM_PROMPT = renderPromptTemplate(summarizationSystemPrompt);
+
+// ============================================================================
+// Token Estimation
+// ============================================================================
+
+/**
+ * Estimate token count for a message using chars/4 heuristic.
+ * This is conservative (overestimates tokens).
+ */
+export function estimateTokens(message: AgentMessage): number {
+	let chars = 0;
+
+	switch (message.role) {
+		case "user": {
+			const content = (message as { content: string | Array<{ type: string; text?: string }> }).content;
+			if (typeof content === "string") {
+				chars = content.length;
+			} else if (Array.isArray(content)) {
+				for (const block of content) {
+					if (block.type === "text" && block.text) {
+						chars += block.text.length;
+					}
+				}
+			}
+			return Math.ceil(chars / 4);
+		}
+		case "assistant": {
+			const assistant = message as AssistantMessage;
+			for (const block of assistant.content) {
+				if (block.type === "text") {
+					chars += block.text.length;
+				} else if (block.type === "thinking") {
+					chars += block.thinking.length;
+				} else if (block.type === "toolCall") {
+					chars += block.name.length + JSON.stringify(block.arguments).length;
+				}
+			}
+			return Math.ceil(chars / 4);
+		}
+		case "hookMessage":
+		case "toolResult": {
+			if (typeof message.content === "string") {
+				chars = message.content.length;
+			} else {
+				for (const block of message.content) {
+					if (block.type === "text" && block.text) {
+						chars += block.text.length;
+					}
+					if (block.type === "image") {
+						chars += 4800; // Estimate images as 4000 chars, or 1200 tokens
+					}
+				}
+			}
+			return Math.ceil(chars / 4);
+		}
+		case "bashExecution": {
+			chars = message.command.length + message.output.length;
+			return Math.ceil(chars / 4);
+		}
+		case "branchSummary": {
+			chars = message.summary.length;
+			return Math.ceil(chars / 4);
+		}
+	}
+
+	return 0;
+}
+
+// ============================================================================
+// Context Token Calculation
+// ============================================================================
+
+/**
+ * Calculate context tokens from usage report.
+ * Uses the native totalTokens field when available, falls back to computing from components.
+ */
+export function calculateContextTokens(usage: Usage): number {
+	return usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+
+/**
+ * Get the last assistant message's usage data.
+ */
+export function getLastAssistantUsage(messages: AgentMessage[]): Usage | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			return (msg as AssistantMessage).usage;
+		}
+	}
+	return undefined;
+}

package/src/session/messages.ts

@@ -8,11 +8,9 @@ import type { AgentMessage } from "@nghyane/arcane-agent";
 import type { ImageContent, Message, TextContent, ToolResultMessage } from "@nghyane/arcane-ai";
 import { renderPromptTemplate } from "../config/prompt-templates";
 import branchSummaryContextPrompt from "../prompts/compaction/branch-summary-context.md" with { type: "text" };
-import compactionSummaryContextPrompt from "../prompts/compaction/compaction-summary-context.md" with { type: "text" };
 import type { OutputMeta } from "../tools/output-meta";
 import { formatOutputNotice } from "../tools/output-meta";
 
-const COMPACTION_SUMMARY_TEMPLATE = compactionSummaryContextPrompt;
 const BRANCH_SUMMARY_TEMPLATE = branchSummaryContextPrompt;
 
 export const SKILL_PROMPT_MESSAGE_TYPE = "skill-prompt";
@@ -97,14 +95,6 @@ export interface BranchSummaryMessage {
 	timestamp: number;
 }
 
-export interface CompactionSummaryMessage {
-	role: "compactionSummary";
-	summary: string;
-	shortSummary?: string;
-	tokensBefore: number;
-	timestamp: number;
-}
-
 /**
  * Message type for auto-read file mentions via @filepath syntax.
  */
@@ -132,7 +122,6 @@ declare module "@nghyane/arcane-agent" {
 		custom: CustomMessage;
 		hookMessage: HookMessage;
 		branchSummary: BranchSummaryMessage;
-		compactionSummary: CompactionSummaryMessage;
 		fileMention: FileMentionMessage;
 	}
 }
@@ -184,21 +173,6 @@ export function createBranchSummaryMessage(summary: string, fromId: string, time
 	};
 }
 
-export function createCompactionSummaryMessage(
-	summary: string,
-	tokensBefore: number,
-	timestamp: string,
-	shortSummary?: string,
-): CompactionSummaryMessage {
-	return {
-		role: "compactionSummary",
-		summary,
-		shortSummary,
-		tokensBefore,
-		timestamp: new Date(timestamp).getTime(),
-	};
-}
-
 /** Convert CustomMessageEntry to AgentMessage format */
 export function createCustomMessage(
 	customType: string,
@@ -267,17 +241,6 @@ export function convertToLlm(messages: AgentMessage[]): Message[] {
 						],
 						timestamp: m.timestamp,
 					};
-				case "compactionSummary":
-					return {
-						role: "user",
-						content: [
-							{
-								type: "text" as const,
-								text: renderPromptTemplate(COMPACTION_SUMMARY_TEMPLATE, { summary: m.summary }),
-							},
-						],
-						timestamp: m.timestamp,
-					};
 				case "fileMention": {
 					const fileContents = m.files
 						.map(file => {

package/src/session/retry-utils.ts

@@ -8,7 +8,7 @@
  * Matches: overloaded, rate limit, usage limit, 429, 5xx, connection errors.
  */
 export function isRetryableErrorMessage(errorMessage: string): boolean {
-	return /overloaded|rate.?limit|usage.?limit|too many requests|429|500|502|503|504|service.?unavailable|server error|internal error|connection.?error|unable to connect|fetch failed|retry delay/i.test(
+	return /overloaded|rate.?limit|usage.?limit|too many requests|429|500|502|503|504|service.?unavailable|server error|internal error|connection.?error|unable to connect|fetch failed|retry delay|json parse error/i.test(
 		errorMessage,
 	);
 }

package/src/session/session-manager.ts

@@ -11,7 +11,6 @@ import {
 	type BashExecutionMessage,
 	type CustomMessage,
 	createBranchSummaryMessage,
-	createCompactionSummaryMessage,
 	createCustomMessage,
 	type FileMentionMessage,
 	type HookMessage,
@@ -24,7 +23,6 @@ export * from "./session-types";
 
 import {
 	type BranchSummaryEntry,
-	type CompactionEntry,
 	CURRENT_SESSION_VERSION,
 	type CustomEntry,
 	type CustomMessageEntry,
@@ -85,18 +83,6 @@ function migrateV1ToV2(entries: FileEntry[]): void {
 		entry.id = generateId(ids);
 		entry.parentId = prevId;
 		prevId = entry.id;
-
-		// Convert firstKeptEntryIndex to firstKeptEntryId for compaction
-		if (entry.type === "compaction") {
-			const comp = entry as CompactionEntry & { firstKeptEntryIndex?: number };
-			if (typeof comp.firstKeptEntryIndex === "number") {
-				const targetEntry = entries[comp.firstKeptEntryIndex];
-				if (targetEntry && targetEntry.type !== "session") {
-					comp.firstKeptEntryId = targetEntry.id;
-				}
-				delete comp.firstKeptEntryIndex;
-			}
-		}
 	}
 }
 
@@ -199,20 +185,10 @@ function migrateHomeSessionDirs(): void {
 	}
 }
 
-/** Exported for compaction.test.ts */
 export function parseSessionEntries(content: string): FileEntry[] {
 	return parseJsonlLenient<FileEntry>(content);
 }
 
-export function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null {
-	for (let i = entries.length - 1; i >= 0; i--) {
-		if (entries[i].type === "compaction") {
-			return entries[i] as CompactionEntry;
-		}
-	}
-	return null;
-}
-
 function toError(value: unknown): Error {
 	return value instanceof Error ? value : new Error(String(value));
 }
@@ -220,7 +196,7 @@ function toError(value: unknown): Error {
 /**
  * Build the session context from entries using tree traversal.
  * If leafId is provided, walks from that entry to root.
- * Handles compaction and branch summaries along the path.
+ * Handles branch summaries along the path.
  */
 export function buildSessionContext(
 	entries: SessionEntry[],
@@ -261,10 +237,9 @@ export function buildSessionContext(
 		current = current.parentId ? byId.get(current.parentId) : undefined;
 	}
 
-	// Extract settings and find compaction
+	// Extract settings
 	let thinkingLevel = "off";
 	const models: Record<string, string> = {};
-	let compaction: CompactionEntry | null = null;
 	const injectedTtsrRulesSet = new Set<string>();
 	let mode = "none";
 	let modeData: Record<string, unknown> | undefined;
@@ -281,8 +256,6 @@ export function buildSessionContext(
 		} else if (entry.type === "message" && entry.message.role === "assistant") {
 			// Infer default model from assistant messages
 			models.default = `${entry.message.provider}/${entry.message.model}`;
-		} else if (entry.type === "compaction") {
-			compaction = entry;
 		} else if (entry.type === "ttsr_injection") {
 			// Collect injected TTSR rule names
 			for (const ruleName of entry.injectedRules) {
@@ -296,14 +269,10 @@ export function buildSessionContext(
 
 	const injectedTtsrRules = Array.from(injectedTtsrRulesSet);
 
-	// Build messages and collect corresponding entries
-	// When there's a compaction, we need to:
-	// 1. Emit summary first (entry = compaction)
-	// 2. Emit kept messages (from firstKeptEntryId up to compaction)
-	// 3. Emit messages after compaction
+	// Build messages
 	const messages: AgentMessage[] = [];
 
-	const appendMessage = (entry: SessionEntry) => {
+	for (const entry of path) {
 		if (entry.type === "message") {
 			messages.push(entry.message);
 		} else if (entry.type === "custom_message") {
@@ -313,44 +282,6 @@ export function buildSessionContext(
 		} else if (entry.type === "branch_summary" && entry.summary) {
 			messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
 		}
-	};
-
-	if (compaction) {
-		// Emit summary first
-		messages.push(
-			createCompactionSummaryMessage(
-				compaction.summary,
-				compaction.tokensBefore,
-				compaction.timestamp,
-				compaction.shortSummary,
-			),
-		);
-
-		// Find compaction index in path
-		const compactionIdx = path.findIndex(e => e.type === "compaction" && e.id === compaction.id);
-
-		// Emit kept messages (before compaction, starting from firstKeptEntryId)
-		let foundFirstKept = false;
-		for (let i = 0; i < compactionIdx; i++) {
-			const entry = path[i];
-			if (entry.id === compaction.firstKeptEntryId) {
-				foundFirstKept = true;
-			}
-			if (foundFirstKept) {
-				appendMessage(entry);
-			}
-		}
-
-		// Emit messages after compaction
-		for (let i = compactionIdx + 1; i < path.length; i++) {
-			const entry = path[i];
-			appendMessage(entry);
-		}
-	} else {
-		// No compaction - emit all messages, handle branch summaries and custom messages
-		for (const entry of path) {
-			appendMessage(entry);
-		}
 	}
 
 	return { messages, thinkingLevel, models, injectedTtsrRules, mode, modeData };
@@ -858,7 +789,7 @@ export async function getRecentSessions(
  * modifying history.
  *
  * Use buildSessionContext() to get the resolved message list for the LLM, which
- * handles compaction summaries and follows the path from root to current leaf.
+ * handles branch summaries and follows the path from root to current leaf.
  */
 export interface UsageStatistics {
 	input: number;
@@ -908,10 +839,6 @@ async function collectSessionsFromFiles(files: string[], storage: SessionStorage
 				for (let i = 1; i < entries.length; i++) {
 					const entry = entries[i] as { type?: string; message?: Message; shortSummary?: string };
 
-					if (entry.type === "compaction" && typeof entry.shortSummary === "string") {
-						shortSummary = entry.shortSummary;
-					}
-
 					if (entry.type === "message" && entry.message) {
 						messageCount++;
 
@@ -1448,10 +1375,10 @@ export class SessionManager {
 	}
 
 	/** Append a message as child of current leaf, then advance leaf. Returns entry id.
-	 * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
+	 * Does not allow writing BranchSummaryMessage directly.
 	 * Reason: we want these to be top-level entries in the session, not message session entries,
 	 * so it is easier to find them.
-	 * These need to be appended via appendCompaction() and appendBranchSummary() methods.
+	 * These need to be appended via appendBranchSummary() methods.
 	 */
 	appendMessage(
 		message:
@@ -1531,33 +1458,6 @@ export class SessionManager {
 		return entry.id;
 	}
 
-	/** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
-	appendCompaction<T = unknown>(
-		summary: string,
-		shortSummary: string | undefined,
-		firstKeptEntryId: string,
-		tokensBefore: number,
-		details?: T,
-		fromExtension?: boolean,
-		preserveData?: Record<string, unknown>,
-	): string {
-		const entry: CompactionEntry<T> = {
-			type: "compaction",
-			id: generateId(this.#byId),
-			parentId: this.#leafId,
-			timestamp: new Date().toISOString(),
-			summary,
-			shortSummary,
-			firstKeptEntryId,
-			tokensBefore,
-			details,
-			fromExtension,
-			preserveData,
-		};
-		this.#appendEntry(entry);
-		return entry.id;
-	}
-
 	/** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
 	appendCustomEntry(customType: string, data?: unknown): string {
 		const entry: CustomEntry = {
@@ -1726,7 +1626,7 @@ export class SessionManager {
 
 	/**
 	 * Walk from entry to root, returning all entries in path order.
-	 * Includes all entry types (messages, compaction, model changes, etc.).
+	 * Includes all entry types (messages, model changes, etc.).
 	 * Use buildSessionContext() to get the resolved messages for the LLM.
 	 */
 	getBranch(fromId?: string): SessionEntry[] {

package/src/session/session-types.ts

@@ -11,7 +11,6 @@ import type { Skill, SkillWarning } from "../extensibility/skills";
 import type { FileSlashCommand } from "../extensibility/slash-commands";
 import type { SecretObfuscator } from "../secrets/obfuscator";
 import type { TodoItem } from "../tools/todo-write";
-import type { CompactionResult } from "./compaction";
 import type { SessionManager } from "./session-manager";
 
 export const CURRENT_SESSION_VERSION = 3;
@@ -55,20 +54,6 @@ export interface ModelChangeEntry extends SessionEntryBase {
 	role?: string;
 }
 
-export interface CompactionEntry<T = unknown> extends SessionEntryBase {
-	type: "compaction";
-	summary: string;
-	shortSummary?: string;
-	firstKeptEntryId: string;
-	tokensBefore: number;
-	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
-	details?: T;
-	/** Hook-provided data to persist across compaction */
-	preserveData?: Record<string, unknown>;
-	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
-	fromExtension?: boolean;
-}
-
 export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
 	type: "branch_summary";
 	fromId: string;
@@ -154,7 +139,6 @@ export type SessionEntry =
 	| SessionMessageEntry
 	| ThinkingLevelChangeEntry
 	| ModelChangeEntry
-	| CompactionEntry
 	| BranchSummaryEntry
 	| CustomEntry
 	| CustomMessageEntry
@@ -209,18 +193,13 @@ export interface SessionInfo {
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent =
 	| AgentEvent
-	| { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
-	| {
-			type: "auto_compaction_end";
-			result: CompactionResult | undefined;
-			aborted: boolean;
-			willRetry: boolean;
-			errorMessage?: string;
-	  }
 	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
 	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
-	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number };
+	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
+	| { type: "context_warning"; percent: number; tokens: number; contextWindow: number }
+	| { type: "auto_handoff_start"; percent: number }
+	| { type: "auto_handoff_end"; success: boolean; error?: string };
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;

package/src/session/stats.ts

@@ -5,9 +5,8 @@ import { exportSessionToHtml } from "../export/html";
 import type { ContextUsage } from "../extensibility/extensions/types";
 import { getCurrentThemeName } from "../theme/theme";
 import { calculateContextTokens, estimateTokens } from "./compaction";
-import type { CompactionSummaryMessage, FileMentionMessage } from "./messages";
+import type { FileMentionMessage } from "./messages";
 import type { SessionManager } from "./session-manager";
-import { getLatestCompactionEntry } from "./session-manager";
 import type { SessionStats } from "./session-types";
 
 /**
@@ -82,42 +81,12 @@ export function getSessionStats(
 /**
  * Get current context usage statistics.
  */
-export function getContextUsage(
-	model: Model | undefined,
-	messages: AgentMessage[],
-	sessionManager: SessionManager,
-): ContextUsage | undefined {
+export function getContextUsage(model: Model | undefined, messages: AgentMessage[]): ContextUsage | undefined {
 	if (!model) return undefined;
 
 	const contextWindow = model.contextWindow ?? 0;
 	if (contextWindow <= 0) return undefined;
 
-	const branchEntries = sessionManager.getBranch();
-	const latestCompaction = getLatestCompactionEntry(branchEntries);
-
-	if (latestCompaction) {
-		const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
-		let hasPostCompactionUsage = false;
-		for (let i = compactionIndex + 1; i < branchEntries.length; i++) {
-			const entry = branchEntries[i];
-			if (entry.type === "message" && entry.message.role === "assistant") {
-				const msg = entry.message as AssistantMessage;
-				if (msg.usage) {
-					hasPostCompactionUsage = true;
-					break;
-				}
-			}
-		}
-
-		if (!hasPostCompactionUsage) {
-			return {
-				tokens: 0,
-				contextWindow,
-				percent: 0,
-			};
-		}
-	}
-
 	const { tokens } = estimateContextTokensFromMessages(messages);
 	const percent = Math.round((tokens / contextWindow) * 100);
 
@@ -374,12 +343,6 @@ export function formatCompactContext(messages: AgentMessage[]): string {
 			const paths = fileMsg.files.map(f => f.path).join(", ");
 			lines.push(`[Files referenced: ${paths}]`);
 			lines.push("");
-		} else if (msg.role === "compactionSummary") {
-			const compactMsg = msg as CompactionSummaryMessage;
-			lines.push("## Earlier Context (Summarized)");
-			lines.push("");
-			lines.push(compactMsg.summary);
-			lines.push("");
 		}
 	}
 

package/src/slash-commands/builtin-registry.ts

@@ -302,17 +302,6 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<BuiltinSlashCommandSpec> = [
 			await runtime.ctx.handleClearCommand();
 		},
 	},
-	{
-		name: "compact",
-		description: "Manually compact the session context",
-		inlineHint: "[focus instructions]",
-		allowArgs: true,
-		handle: async (command, runtime) => {
-			const customInstructions = command.args || undefined;
-			runtime.ctx.editor.setText("");
-			await runtime.ctx.handleCompactCommand(customInstructions);
-		},
-	},
 	{
 		name: "handoff",
 		description: "Hand off session context to a new session",

package/src/task/executor.ts

@@ -417,14 +417,6 @@ export async function runAgent(options: ExecutorOptions): Promise<SingleResult>
 						shutdown: () => {},
 						getContextUsage: () => session.getContextUsage(),
 						getSystemPrompt: () => session.systemPrompt,
-						compact: async instructionsOrOptions => {
-							const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
-							const compactOptions =
-								instructionsOrOptions && typeof instructionsOrOptions === "object"
-									? instructionsOrOptions
-									: undefined;
-							await session.compact(instructions, compactOptions);
-						},
 					},
 				);
 				await extensionRunner.emit({ type: "session_start" });

package/src/tools/create-tools.ts

@@ -13,6 +13,7 @@ import { FetchTool } from "./fetch";
 import { FindTool } from "./find";
 import { FindThreadTool } from "./find-thread";
 import { GitHubTool } from "./github";
+import { GitHubFsTool } from "./github-fs";
 import { GrepTool } from "./grep";
 import type { ToolSession } from "./index";
 import { librarianConfig } from "./librarian";
@@ -44,6 +45,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	find: s => new FindTool(s),
 	explore: s => new SubagentTool(s, exploreConfig),
 	github: s => new GitHubTool(s),
+	github_fs: s => new GitHubFsTool(s),
 	grep: s => new GrepTool(s),
 	librarian: s => new SubagentTool(s, librarianConfig),
 	lsp: LspTool.createIf,
@@ -132,6 +134,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "librarian") return session.settings.get("librarian.enabled");
 		if (name === "oracle") return session.settings.get("oracle.enabled");
 		if (name === "github") return session.settings.get("github.enabled");
+		if (name === "github_fs") return session.isSubagent && session.settings.get("github.enabled");
 		if (name === "search_code") return session.isSubagent;
 		if (name === "task") {
 			return !session.isSubagent;