headlesscode 1.0.2

package/src/vendor/zoo-code/src/shared/modes.ts

@@ -0,0 +1,257 @@
+import * as vscode from "../../shim/vscode"
+
+import {
+	type GroupEntry,
+	type ModeConfig,
+	type CustomModePrompts,
+	type ToolGroup,
+	type PromptComponent,
+	DEFAULT_MODES,
+} from "../../types"
+
+import { addCustomInstructions } from "../core/prompts/sections/custom-instructions"
+
+import { TOOL_GROUPS, ALWAYS_AVAILABLE_TOOLS } from "./tools"
+
+export type Mode = string
+
+// Helper to extract group name regardless of format
+export function getGroupName(group: GroupEntry): ToolGroup {
+	if (typeof group === "string") {
+		return group
+	}
+
+	return group[0]
+}
+
+// Helper to get all tools for a mode
+export function getToolsForMode(groups: readonly GroupEntry[]): string[] {
+	const tools = new Set<string>()
+
+	// Add tools from each group (excluding customTools which are opt-in only)
+	groups.forEach((group) => {
+		const groupName = getGroupName(group)
+		const groupConfig = TOOL_GROUPS[groupName]
+		groupConfig.tools.forEach((tool: string) => tools.add(tool))
+	})
+
+	// Always add required tools
+	ALWAYS_AVAILABLE_TOOLS.forEach((tool) => tools.add(tool))
+
+	return Array.from(tools)
+}
+
+// Main modes configuration as an ordered array
+export const modes = DEFAULT_MODES
+
+// Export the default mode slug
+export const defaultModeSlug = modes[0].slug
+
+// Helper functions
+export function getModeBySlug(slug: string, customModes?: ModeConfig[]): ModeConfig | undefined {
+	// Check custom modes first
+	const customMode = customModes?.find((mode) => mode.slug === slug)
+	if (customMode) {
+		return customMode
+	}
+	// Then check built-in modes
+	return modes.find((mode) => mode.slug === slug)
+}
+
+export function getModeConfig(slug: string, customModes?: ModeConfig[]): ModeConfig {
+	const mode = getModeBySlug(slug, customModes)
+	if (!mode) {
+		throw new Error(`No mode found for slug: ${slug}`)
+	}
+	return mode
+}
+
+// Get all available modes, with custom modes overriding built-in modes
+export function getAllModes(customModes?: ModeConfig[]): ModeConfig[] {
+	if (!customModes?.length) {
+		return [...modes]
+	}
+
+	// Start with built-in modes
+	const allModes = [...modes]
+
+	// Process custom modes
+	customModes.forEach((customMode) => {
+		const index = allModes.findIndex((mode) => mode.slug === customMode.slug)
+		if (index !== -1) {
+			// Override existing mode
+			allModes[index] = customMode
+		} else {
+			// Add new mode
+			allModes.push(customMode)
+		}
+	})
+
+	return allModes
+}
+
+// Check if a mode is custom or an override
+export function isCustomMode(slug: string, customModes?: ModeConfig[]): boolean {
+	return !!customModes?.some((mode) => mode.slug === slug)
+}
+
+/**
+ * Find a mode by its slug, don't fall back to built-in modes
+ */
+export function findModeBySlug(slug: string, modes: readonly ModeConfig[] | undefined): ModeConfig | undefined {
+	return modes?.find((mode) => mode.slug === slug)
+}
+
+/**
+ * Get the mode selection based on the provided mode slug, prompt component, and custom modes.
+ * If a custom mode is found, it takes precedence over the built-in modes.
+ * If no custom mode is found, the built-in mode is used with partial merging from promptComponent.
+ * If neither is found, the default mode is used.
+ */
+export function getModeSelection(mode: string, promptComponent?: PromptComponent, customModes?: ModeConfig[]) {
+	const customMode = findModeBySlug(mode, customModes)
+	const builtInMode = findModeBySlug(mode, modes)
+
+	// If we have a custom mode, use it entirely
+	if (customMode) {
+		return {
+			roleDefinition: customMode.roleDefinition || "",
+			baseInstructions: customMode.customInstructions || "",
+			description: customMode.description || "",
+		}
+	}
+
+	// Otherwise, use built-in mode as base and merge with promptComponent
+	const baseMode = builtInMode || modes[0] // fallback to default mode
+
+	return {
+		roleDefinition: promptComponent?.roleDefinition || baseMode.roleDefinition || "",
+		baseInstructions: promptComponent?.customInstructions || baseMode.customInstructions || "",
+		description: baseMode.description || "",
+	}
+}
+
+// Custom error class for file restrictions
+export class FileRestrictionError extends Error {
+	constructor(mode: string, pattern: string, description: string | undefined, filePath: string, tool?: string) {
+		const toolInfo = tool ? `Tool '${tool}' in mode '${mode}'` : `This mode (${mode})`
+		super(
+			`${toolInfo} can only edit files matching pattern: ${pattern}${description ? ` (${description})` : ""}. Got: ${filePath}`,
+		)
+		this.name = "FileRestrictionError"
+	}
+}
+
+// Create the mode-specific default prompts
+export const defaultPrompts: Readonly<CustomModePrompts> = Object.freeze(
+	Object.fromEntries(
+		modes.map((mode) => [
+			mode.slug,
+			{
+				roleDefinition: mode.roleDefinition,
+				whenToUse: mode.whenToUse,
+				customInstructions: mode.customInstructions,
+				description: mode.description,
+			},
+		]),
+	),
+)
+
+// Helper function to get all modes with their prompt overrides from extension state
+export async function getAllModesWithPrompts(context: vscode.ExtensionContext): Promise<ModeConfig[]> {
+	const customModes = (await context.globalState.get<ModeConfig[]>("customModes")) || []
+	const customModePrompts = (await context.globalState.get<CustomModePrompts>("customModePrompts")) || {}
+
+	const allModes = getAllModes(customModes)
+	return allModes.map((mode) => ({
+		...mode,
+		roleDefinition: customModePrompts[mode.slug]?.roleDefinition ?? mode.roleDefinition,
+		whenToUse: customModePrompts[mode.slug]?.whenToUse ?? mode.whenToUse,
+		customInstructions: customModePrompts[mode.slug]?.customInstructions ?? mode.customInstructions,
+		// description is not overridable via customModePrompts, so we keep the original
+	}))
+}
+
+// Helper function to get complete mode details with all overrides
+export async function getFullModeDetails(
+	modeSlug: string,
+	customModes?: ModeConfig[],
+	customModePrompts?: CustomModePrompts,
+	options?: {
+		cwd?: string
+		globalCustomInstructions?: string
+		language?: string
+	},
+): Promise<ModeConfig> {
+	// First get the base mode config from custom modes or built-in modes
+	const baseMode = getModeBySlug(modeSlug, customModes) || modes.find((m) => m.slug === modeSlug) || modes[0]
+
+	// Check for any prompt component overrides
+	const promptComponent = customModePrompts?.[modeSlug]
+
+	// Get the base custom instructions
+	const baseCustomInstructions = promptComponent?.customInstructions || baseMode.customInstructions || ""
+	const baseWhenToUse = promptComponent?.whenToUse || baseMode.whenToUse || ""
+	const baseDescription = promptComponent?.description || baseMode.description || ""
+
+	// If we have cwd, load and combine all custom instructions
+	let fullCustomInstructions = baseCustomInstructions
+	if (options?.cwd) {
+		fullCustomInstructions = await addCustomInstructions(
+			baseCustomInstructions,
+			options.globalCustomInstructions || "",
+			options.cwd,
+			modeSlug,
+			{ language: options.language },
+		)
+	}
+
+	// Return mode with any overrides applied
+	return {
+		...baseMode,
+		roleDefinition: promptComponent?.roleDefinition || baseMode.roleDefinition,
+		whenToUse: baseWhenToUse,
+		description: baseDescription,
+		customInstructions: fullCustomInstructions,
+	}
+}
+
+// Helper function to safely get role definition
+export function getRoleDefinition(modeSlug: string, customModes?: ModeConfig[]): string {
+	const mode = getModeBySlug(modeSlug, customModes)
+	if (!mode) {
+		console.warn(`No mode found for slug: ${modeSlug}`)
+		return ""
+	}
+	return mode.roleDefinition
+}
+
+// Helper function to safely get description
+export function getDescription(modeSlug: string, customModes?: ModeConfig[]): string {
+	const mode = getModeBySlug(modeSlug, customModes)
+	if (!mode) {
+		console.warn(`No mode found for slug: ${modeSlug}`)
+		return ""
+	}
+	return mode.description ?? ""
+}
+
+// Helper function to safely get whenToUse
+export function getWhenToUse(modeSlug: string, customModes?: ModeConfig[]): string {
+	const mode = getModeBySlug(modeSlug, customModes)
+	if (!mode) {
+		console.warn(`No mode found for slug: ${modeSlug}`)
+		return ""
+	}
+	return mode.whenToUse ?? ""
+}
+
+// Helper function to safely get custom instructions
+export function getCustomInstructions(modeSlug: string, customModes?: ModeConfig[]): string {
+	const mode = getModeBySlug(modeSlug, customModes)
+	if (!mode) {
+		console.warn(`No mode found for slug: ${modeSlug}`)
+		return ""
+	}
+	return mode.customInstructions ?? ""
+}

package/src/vendor/zoo-code/src/shared/tools.ts

@@ -0,0 +1,385 @@
+import { Anthropic } from "../../shim/anthropic"
+
+import type { ClineAsk, ToolProgressStatus, ToolGroup, ToolName, GenerateImageParams } from "../../types"
+
+export type ToolResponse = string | Array<Anthropic.TextBlockParam | Anthropic.ImageBlockParam>
+
+export type AskApproval = (
+	type: ClineAsk,
+	partialMessage?: string,
+	progressStatus?: ToolProgressStatus,
+	forceApproval?: boolean,
+) => Promise<boolean>
+
+export type HandleError = (action: string, error: Error) => Promise<void>
+
+export type PushToolResult = (content: ToolResponse) => void
+
+export type AskFinishSubTaskApproval = () => Promise<boolean>
+
+export interface TextContent {
+	type: "text"
+	content: string
+	partial: boolean
+}
+
+export const toolParamNames = [
+	"command",
+	"path",
+	"content",
+	"regex",
+	"file_pattern",
+	"recursive",
+	"action",
+	"url",
+	"coordinate",
+	"text",
+	"server_name",
+	"tool_name",
+	"arguments",
+	"uri",
+	"question",
+	"result",
+	"diff",
+	"mode_slug",
+	"reason",
+	"line",
+	"mode",
+	"message",
+	"cwd",
+	"follow_up",
+	"task",
+	"size",
+	"query",
+	"args",
+	"skill", // skill tool parameter
+	"start_line",
+	"end_line",
+	"todos",
+	"prompt",
+	"image",
+	// read_file parameters (native protocol)
+	"operations", // search_and_replace parameter for multiple operations
+	"patch", // apply_patch parameter
+	"file_path", // search_replace and edit_file parameter
+	"old_string", // search_replace and edit_file parameter
+	"new_string", // search_replace and edit_file parameter
+	"replace_all", // edit tool parameter for replacing all occurrences
+	"expected_replacements", // edit_file parameter for multiple occurrences
+	"timeout", // execute_command parameter
+	"artifact_id", // read_command_output parameter
+	"search", // read_command_output parameter for grep-like search
+	"offset", // read_command_output and read_file parameter
+	"limit", // read_command_output and read_file parameter
+	// read_file indentation mode parameters
+	"indentation",
+	"anchor_line",
+	"max_levels",
+	"include_siblings",
+	"include_header",
+	"max_lines",
+	// read_file legacy format parameter (backward compatibility)
+	"files",
+	"line_ranges",
+] as const
+
+export type ToolParamName = (typeof toolParamNames)[number]
+
+/**
+ * Type map defining the native (typed) argument structure for each tool.
+ * Tools not listed here will fall back to `any` for backward compatibility.
+ */
+export type NativeToolArgs = {
+	access_mcp_resource: { server_name: string; uri: string }
+	read_file: import("../../types").ReadFileToolParams
+	read_command_output: { artifact_id: string; search?: string; offset?: number; limit?: number }
+	attempt_completion: { result: string }
+	execute_command: { command: string; cwd?: string; timeout?: number | null }
+	apply_diff: { path: string; diff: string }
+	edit: { file_path: string; old_string: string; new_string: string; replace_all?: boolean }
+	search_and_replace: { file_path: string; old_string: string; new_string: string; replace_all?: boolean }
+	search_replace: { file_path: string; old_string: string; new_string: string }
+	edit_file: { file_path: string; old_string: string; new_string: string; expected_replacements?: number }
+	apply_patch: { patch: string }
+	list_files: { path: string; recursive?: boolean }
+	new_task: { mode: string; message: string; todos?: string }
+	ask_followup_question: {
+		question: string
+		follow_up: Array<{ text: string; mode?: string }>
+	}
+	codebase_search: { query: string; path?: string }
+	generate_image: GenerateImageParams
+	run_slash_command: { command: string; args?: string }
+	skill: { skill: string; args?: string }
+	search_files: { path: string; regex: string; file_pattern?: string | null }
+	switch_mode: { mode_slug: string; reason: string }
+	update_todo_list: { todos: string }
+	use_mcp_tool: { server_name: string; tool_name: string; arguments?: Record<string, unknown> }
+	write_to_file: { path: string; content: string }
+	// Add more tools as they are migrated to native protocol
+}
+
+/**
+ * Generic ToolUse interface that provides proper typing for both protocols.
+ *
+ * @template TName - The specific tool name, which determines the nativeArgs type
+ */
+export interface ToolUse<TName extends ToolName = ToolName> {
+	type: "tool_use"
+	id?: string // Optional ID to track tool calls
+	name: TName
+	/**
+	 * The original tool name as called by the model (e.g. an alias like "edit_file"),
+	 * if it differs from the canonical tool name used for execution.
+	 * Used to preserve tool names in API conversation history.
+	 */
+	originalName?: string
+	// params is a partial record, allowing only some or none of the possible parameters to be used
+	params: Partial<Record<ToolParamName, string>>
+	partial: boolean
+	// nativeArgs is properly typed based on TName if it's in NativeToolArgs, otherwise never
+	nativeArgs?: TName extends keyof NativeToolArgs ? NativeToolArgs[TName] : never
+	/**
+	 * Flag indicating whether the tool call used a legacy/deprecated format.
+	 * Used for telemetry tracking to monitor migration from old formats.
+	 */
+	usedLegacyFormat?: boolean
+}
+
+/**
+ * Represents a native MCP tool call from the model.
+ * In native mode, MCP tools are called directly with their prefixed name (e.g., "mcp_serverName_toolName")
+ * rather than through the use_mcp_tool wrapper. This type preserves the original tool name
+ * so it appears correctly in API conversation history.
+ */
+export interface McpToolUse {
+	type: "mcp_tool_use"
+	id?: string // Tool call ID from the API
+	/** The original tool name from the API (e.g., "mcp_serverName_toolName") */
+	name: string
+	/** Extracted server name from the tool name */
+	serverName: string
+	/** Extracted tool name from the tool name */
+	toolName: string
+	/** Arguments passed to the MCP tool */
+	arguments: Record<string, unknown>
+	partial: boolean
+}
+
+export interface ExecuteCommandToolUse extends ToolUse<"execute_command"> {
+	name: "execute_command"
+	// Pick<Record<ToolParamName, string>, "command"> makes "command" required, but Partial<> makes it optional
+	params: Partial<Pick<Record<ToolParamName, string>, "command" | "cwd" | "timeout">>
+}
+
+export interface ReadFileToolUse extends ToolUse<"read_file"> {
+	name: "read_file"
+	params: Partial<
+		Pick<
+			Record<ToolParamName, string>,
+			| "args"
+			| "path"
+			| "start_line"
+			| "end_line"
+			| "mode"
+			| "offset"
+			| "limit"
+			| "indentation"
+			| "anchor_line"
+			| "max_levels"
+			| "include_siblings"
+			| "include_header"
+		>
+	>
+}
+
+export interface WriteToFileToolUse extends ToolUse<"write_to_file"> {
+	name: "write_to_file"
+	params: Partial<Pick<Record<ToolParamName, string>, "path" | "content">>
+}
+
+export interface CodebaseSearchToolUse extends ToolUse<"codebase_search"> {
+	name: "codebase_search"
+	params: Partial<Pick<Record<ToolParamName, string>, "query" | "path">>
+}
+
+export interface SearchFilesToolUse extends ToolUse<"search_files"> {
+	name: "search_files"
+	params: Partial<Pick<Record<ToolParamName, string>, "path" | "regex" | "file_pattern">>
+}
+
+export interface ListFilesToolUse extends ToolUse<"list_files"> {
+	name: "list_files"
+	params: Partial<Pick<Record<ToolParamName, string>, "path" | "recursive">>
+}
+
+export interface UseMcpToolToolUse extends ToolUse<"use_mcp_tool"> {
+	name: "use_mcp_tool"
+	params: Partial<Pick<Record<ToolParamName, string>, "server_name" | "tool_name" | "arguments">>
+}
+
+export interface AccessMcpResourceToolUse extends ToolUse<"access_mcp_resource"> {
+	name: "access_mcp_resource"
+	params: Partial<Pick<Record<ToolParamName, string>, "server_name" | "uri">>
+}
+
+export interface AskFollowupQuestionToolUse extends ToolUse<"ask_followup_question"> {
+	name: "ask_followup_question"
+	params: Partial<Pick<Record<ToolParamName, string>, "question" | "follow_up">>
+}
+
+export interface AttemptCompletionToolUse extends ToolUse<"attempt_completion"> {
+	name: "attempt_completion"
+	params: Partial<Pick<Record<ToolParamName, string>, "result">>
+}
+
+export interface SwitchModeToolUse extends ToolUse<"switch_mode"> {
+	name: "switch_mode"
+	params: Partial<Pick<Record<ToolParamName, string>, "mode_slug" | "reason">>
+}
+
+export interface NewTaskToolUse extends ToolUse<"new_task"> {
+	name: "new_task"
+	params: Partial<Pick<Record<ToolParamName, string>, "mode" | "message" | "todos">>
+}
+
+export interface RunSlashCommandToolUse extends ToolUse<"run_slash_command"> {
+	name: "run_slash_command"
+	params: Partial<Pick<Record<ToolParamName, string>, "command" | "args">>
+}
+
+export interface SkillToolUse extends ToolUse<"skill"> {
+	name: "skill"
+	params: Partial<Pick<Record<ToolParamName, string>, "skill" | "args">>
+}
+
+export interface GenerateImageToolUse extends ToolUse<"generate_image"> {
+	name: "generate_image"
+	params: Partial<Pick<Record<ToolParamName, string>, "prompt" | "path" | "image">>
+}
+
+// Define tool group configuration
+export type ToolGroupConfig = {
+	tools: readonly string[]
+	alwaysAvailable?: boolean // Whether this group is always available and shouldn't show in prompts view
+	customTools?: readonly string[] // Opt-in only tools - only available when explicitly included via model's includedTools
+}
+
+export const TOOL_DISPLAY_NAMES: Record<ToolName, string> = {
+	execute_command: "run commands",
+	read_file: "read files",
+	read_command_output: "read command output",
+	write_to_file: "write files",
+	apply_diff: "apply changes",
+	edit: "edit files",
+	search_and_replace: "apply changes using search and replace",
+	search_replace: "apply single search and replace",
+	edit_file: "edit files using search and replace",
+	apply_patch: "apply patches using codex format",
+	search_files: "search files",
+	list_files: "list files",
+	use_mcp_tool: "use mcp tools",
+	access_mcp_resource: "access mcp resources",
+	ask_followup_question: "ask questions",
+	attempt_completion: "complete tasks",
+	switch_mode: "switch modes",
+	new_task: "create new task",
+	codebase_search: "codebase search",
+	update_todo_list: "update todo list",
+	run_slash_command: "run slash command",
+	skill: "load skill",
+	generate_image: "generate images",
+	custom_tool: "use custom tools",
+} as const
+
+// Define available tool groups.
+export const TOOL_GROUPS: Record<ToolGroup, ToolGroupConfig> = {
+	read: {
+		tools: ["read_file", "search_files", "list_files", "codebase_search"],
+	},
+	edit: {
+		tools: ["apply_diff", "write_to_file", "generate_image"],
+		customTools: ["edit", "search_replace", "edit_file", "apply_patch"],
+	},
+	command: {
+		tools: ["execute_command", "read_command_output"],
+	},
+	mcp: {
+		tools: ["use_mcp_tool", "access_mcp_resource"],
+	},
+	modes: {
+		tools: ["switch_mode", "new_task"],
+		alwaysAvailable: true,
+	},
+}
+
+// Tools that are always available to all modes.
+export const ALWAYS_AVAILABLE_TOOLS: ToolName[] = [
+	"ask_followup_question",
+	"attempt_completion",
+	"switch_mode",
+	"new_task",
+	"update_todo_list",
+	"run_slash_command",
+	"skill",
+] as const
+
+/**
+ * Central registry of tool aliases.
+ * Maps alias name -> canonical tool name.
+ *
+ * This allows models to use alternative names for tools (e.g., "edit_file" instead of "apply_diff").
+ * When a model calls a tool by its alias, the system resolves it to the canonical name for execution,
+ * but preserves the alias in API conversation history for consistency.
+ *
+ * To add a new alias, simply add an entry here. No other files need to be modified.
+ */
+export const TOOL_ALIASES: Record<string, ToolName> = {
+	write_file: "write_to_file",
+	search_and_replace: "edit",
+} as const
+
+export type DiffResult =
+	| { success: true; content: string; failParts?: DiffResult[] }
+	| ({
+			success: false
+			error?: string
+			details?: {
+				similarity?: number
+				threshold?: number
+				matchedRange?: { start: number; end: number }
+				searchContent?: string
+				bestMatch?: string
+			}
+			failParts?: DiffResult[]
+	  } & ({ error: string } | { failParts: DiffResult[] }))
+
+export interface DiffItem {
+	content: string
+	startLine?: number
+}
+
+export interface DiffStrategy {
+	/**
+	 * Get the name of this diff strategy for analytics and debugging
+	 * @returns The name of the diff strategy
+	 */
+	getName(): string
+
+	/**
+	 * Apply a diff to the original content
+	 * @param originalContent The original file content
+	 * @param diffContent The diff content in the strategy's format (string for legacy, DiffItem[] for new)
+	 * @param startLine Optional line number where the search block starts. If not provided, searches the entire file.
+	 * @param endLine Optional line number where the search block ends. If not provided, searches the entire file.
+	 * @returns A DiffResult object containing either the successful result or error details
+	 */
+	applyDiff(
+		originalContent: string,
+		diffContent: string | DiffItem[],
+		startLine?: number,
+		endLine?: number,
+	): Promise<DiffResult>
+
+	getProgressStatus?(toolUse: ToolUse, result?: any): ToolProgressStatus
+}

package/src/vendor/zoo-code/src/utils/fs.ts

@@ -0,0 +1,39 @@
+/**
+ * SHIM — minimal replacement for zoo-code/src/utils/fs.ts.
+ *
+ * The original exports a large set of fs helpers (mostly for the GUI layer).
+ * The vendored core only needs `fileExistsAtPath`, whose real implementation
+ * (`zoo-code/src/utils/fs.ts`) is existence-only, regardless of file vs
+ * directory:
+ *
+ *   export async function fileExistsAtPath(filePath: string): Promise<boolean> {
+ *     try {
+ *       await fs.access(filePath)
+ *       return true
+ *     } catch {
+ *       return false
+ *     }
+ *   }
+ *
+ * This must match that exactly. An earlier version of this shim narrowed it
+ * to `stats.isFile()`, which broke every caller that checks a DIRECTORY's
+ * existence — `CustomModesManager`'s `.roo/rules-<slug>/` folder check, and
+ * (found while vendoring checkpoints) `ShadowCheckpointService#initShadowGit`'s
+ * check for whether the shadow `.git` dir already exists. With the `isFile`
+ * version, both always returned false for existing directories, so
+ * `initShadowGit` always took the "create new repo" branch — silently
+ * re-initializing (and appending a redundant empty commit to) an
+ * already-initialized shadow repo on every session, corrupting the checkpoint
+ * history's meaning of "baseline".
+ */
+
+import * as fs from "fs/promises"
+
+export async function fileExistsAtPath(filePath: string): Promise<boolean> {
+	try {
+		await fs.access(filePath)
+		return true
+	} catch {
+		return false
+	}
+}

package/src/vendor/zoo-code/src/utils/globalContext.ts

@@ -0,0 +1,22 @@
+/**
+ * SHIM — replaces zoo-code/src/utils/globalContext.ts.
+ *
+ * The original resolves the extension's global storage directory from the VS
+ * Code ExtensionContext. Headless, we use `~/.roo` (the same directory Roo Code
+ * uses for global custom modes), creating it if needed.
+ */
+
+import * as path from "path"
+import * as os from "os"
+import * as fs from "fs/promises"
+import type { ExtensionContext } from "../../shim/vscode"
+
+export async function ensureSettingsDirectoryExists(_context?: ExtensionContext): Promise<string> {
+	const dir = path.join(os.homedir(), ".roo")
+	try {
+		await fs.mkdir(dir, { recursive: true })
+	} catch {
+		// Ignore: read-only home dirs fall back to the path anyway.
+	}
+	return dir
+}