@ljoukov/llm 0.1.3 → 2.1.0

package/dist/index.d.cts

@@ -29,7 +29,7 @@ type LlmToolCallContext = {
 };
 declare function getCurrentToolCallContext(): LlmToolCallContext | null;
 type JsonSchema = Record<string, unknown>;
-type LlmRole = "user" | "model" | "system" | "tool";
+type LlmRole = "user" | "assistant" | "system" | "developer" | "tool";
 type LlmInlineDataPart = {
     type: "inlineData";
     data: string;
@@ -93,11 +93,45 @@ type LlmTextStream = {
     readonly result: Promise<LlmTextResult>;
     readonly abort: () => void;
 };
+type DeepPartial<T> = T extends ReadonlyArray<infer Item> ? ReadonlyArray<DeepPartial<Item>> : T extends Array<infer Item> ? Array<DeepPartial<Item>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+type LlmJsonPartialEvent<T> = {
+    readonly type: "json";
+    readonly stage: "partial";
+    readonly value: DeepPartial<T>;
+};
+type LlmJsonFinalEvent<T> = {
+    readonly type: "json";
+    readonly stage: "final";
+    readonly value: T;
+};
+type LlmJsonStreamEvent<T> = LlmStreamEvent | LlmJsonPartialEvent<T> | LlmJsonFinalEvent<T>;
+type LlmJsonStream<T> = {
+    readonly events: AsyncIterable<LlmJsonStreamEvent<T>>;
+    readonly result: Promise<{
+        readonly value: T;
+        readonly rawText: string;
+        readonly result: LlmTextResult;
+    }>;
+    readonly abort: () => void;
+};
+type LlmInputMessage = {
+    readonly role: "user" | "assistant" | "system" | "developer";
+    readonly content: string | readonly LlmContentPart[];
+};
 type LlmInput = {
-    readonly prompt: string;
-    readonly systemPrompt?: string;
-} | {
-    readonly contents: readonly LlmContent[];
+    /**
+     * OpenAI-style input:
+     * - a plain string becomes one user message
+     * - message arrays allow multi-turn + role-specific content
+     */
+    readonly input: string | readonly LlmInputMessage[];
+    /**
+     * OpenAI-style top-level instructions.
+     * Applied as a system message before input.
+     */
+    readonly instructions?: string;
 };
 type LlmBaseRequest = {
     readonly model: string;
@@ -117,6 +151,18 @@ type LlmJsonRequest<T> = LlmInput & LlmBaseRequest & {
     readonly openAiSchemaName?: string;
     readonly maxAttempts?: number;
     readonly normalizeJson?: (value: unknown) => unknown;
+    /**
+     * Optional streaming callback. Useful to surface thought deltas while still
+     * returning a single validated JSON result.
+     */
+    readonly onEvent?: (event: LlmStreamEvent) => void;
+};
+type LlmJsonStreamRequest<T> = LlmJsonRequest<T> & {
+    /**
+     * - "partial" (default): emit best-effort partial JSON snapshots while streaming.
+     * - "final": stream thought deltas but only emit the final validated JSON value.
+     */
+    readonly streamMode?: "partial" | "final";
 };
 declare class LlmJsonCallError extends Error {
     readonly attempts: ReadonlyArray<{
@@ -195,6 +241,7 @@ declare function convertGooglePartsToLlmParts(parts: readonly Part[]): LlmConten
 declare function parseJsonFromLlmText(rawText: string): unknown;
 declare function streamText(request: LlmTextRequest): LlmTextStream;
 declare function generateText(request: LlmTextRequest): Promise<LlmTextResult>;
+declare function streamJson<T>(request: LlmJsonStreamRequest<T>): LlmJsonStream<T>;
 declare function generateJson<T>(request: LlmJsonRequest<T>): Promise<{
     readonly value: T;
     readonly rawText: string;
@@ -223,6 +270,207 @@ declare function loadEnvFromFile(filePath: string, { override }?: {
     override?: boolean;
 }): void;
 
+type AgentPathKind = "file" | "directory" | "symlink" | "other";
+type AgentPathInfo = {
+    readonly kind: AgentPathKind;
+    readonly mtimeMs: number;
+};
+type AgentDirectoryEntry = {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: AgentPathKind;
+    readonly mtimeMs: number;
+};
+interface AgentFilesystem {
+    readTextFile(filePath: string): Promise<string>;
+    writeTextFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    ensureDir(directoryPath: string): Promise<void>;
+    readDir(directoryPath: string): Promise<readonly AgentDirectoryEntry[]>;
+    stat(entryPath: string): Promise<AgentPathInfo>;
+}
+declare class InMemoryAgentFilesystem implements AgentFilesystem {
+    #private;
+    constructor(initialFiles?: Record<string, string>);
+    readTextFile(filePath: string): Promise<string>;
+    writeTextFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    ensureDir(directoryPath: string): Promise<void>;
+    readDir(directoryPath: string): Promise<readonly AgentDirectoryEntry[]>;
+    stat(entryPath: string): Promise<AgentPathInfo>;
+    snapshot(): Record<string, string>;
+}
+declare function createNodeAgentFilesystem(): AgentFilesystem;
+declare function createInMemoryAgentFilesystem(initialFiles?: Record<string, string>): InMemoryAgentFilesystem;
+
+type AgentFilesystemToolProfile = "auto" | "model-agnostic" | "codex" | "gemini";
+type AgentFilesystemToolName = "apply_patch" | "read_file" | "write_file" | "replace" | "list_dir" | "list_directory" | "grep_files" | "grep_search" | "glob";
+type AgentFilesystemToolAction = "read" | "write" | "delete" | "move" | "list" | "search";
+type AgentFilesystemToolAccessContext = {
+    readonly cwd: string;
+    readonly tool: AgentFilesystemToolName;
+    readonly action: AgentFilesystemToolAction;
+    readonly path: string;
+    readonly fromPath?: string;
+    readonly toPath?: string;
+    readonly pattern?: string;
+    readonly include?: string;
+};
+type AgentFilesystemToolAccessHook = (context: AgentFilesystemToolAccessContext) => Promise<void> | void;
+type AgentFilesystemToolsOptions = {
+    readonly cwd?: string;
+    readonly fs?: AgentFilesystem;
+    readonly allowOutsideCwd?: boolean;
+    readonly checkAccess?: AgentFilesystemToolAccessHook;
+    readonly maxLineLength?: number;
+    readonly grepMaxScannedFiles?: number;
+    readonly applyPatch?: {
+        readonly maxPatchBytes?: number;
+    };
+};
+declare const codexReadFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        slice: "slice";
+        indentation: "indentation";
+    }>>;
+    indentation: z.ZodOptional<z.ZodObject<{
+        anchor_line: z.ZodOptional<z.ZodNumber>;
+        max_levels: z.ZodOptional<z.ZodNumber>;
+        include_siblings: z.ZodOptional<z.ZodBoolean>;
+        include_header: z.ZodOptional<z.ZodBoolean>;
+        max_lines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const codexListDirInputSchema: z.ZodObject<{
+    dir_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    depth: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const codexGrepFilesInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    include: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const applyPatchInputSchema: z.ZodObject<{
+    input: z.ZodString;
+}, z.core.$strip>;
+declare const geminiReadFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const geminiWriteFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+declare const geminiReplaceInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    instruction: z.ZodString;
+    old_string: z.ZodString;
+    new_string: z.ZodString;
+    expected_replacements: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const geminiListDirectoryInputSchema: z.ZodObject<{
+    dir_path: z.ZodString;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    file_filtering_options: z.ZodOptional<z.ZodObject<{
+        respect_git_ignore: z.ZodOptional<z.ZodBoolean>;
+        respect_gemini_ignore: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const geminiGrepSearchInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    dir_path: z.ZodOptional<z.ZodString>;
+    include: z.ZodOptional<z.ZodString>;
+    exclude_pattern: z.ZodOptional<z.ZodString>;
+    names_only: z.ZodOptional<z.ZodBoolean>;
+    max_matches_per_file: z.ZodOptional<z.ZodNumber>;
+    total_max_matches: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const geminiGlobInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    dir_path: z.ZodOptional<z.ZodString>;
+    case_sensitive: z.ZodOptional<z.ZodBoolean>;
+    respect_git_ignore: z.ZodOptional<z.ZodBoolean>;
+    respect_gemini_ignore: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type CodexReadFileToolInput = z.output<typeof codexReadFileInputSchema>;
+type CodexListDirToolInput = z.output<typeof codexListDirInputSchema>;
+type CodexGrepFilesToolInput = z.output<typeof codexGrepFilesInputSchema>;
+type CodexApplyPatchToolInput = z.output<typeof applyPatchInputSchema>;
+type GeminiReadFileToolInput = z.output<typeof geminiReadFileInputSchema>;
+type GeminiWriteFileToolInput = z.output<typeof geminiWriteFileInputSchema>;
+type GeminiReplaceToolInput = z.output<typeof geminiReplaceInputSchema>;
+type GeminiListDirectoryToolInput = z.output<typeof geminiListDirectoryInputSchema>;
+type GeminiGrepSearchToolInput = z.output<typeof geminiGrepSearchInputSchema>;
+type GeminiGlobToolInput = z.output<typeof geminiGlobInputSchema>;
+declare function resolveFilesystemToolProfile(model: string, profile?: AgentFilesystemToolProfile): Exclude<AgentFilesystemToolProfile, "auto">;
+declare function createFilesystemToolSetForModel(model: string, profileOrOptions?: AgentFilesystemToolProfile | AgentFilesystemToolsOptions, maybeOptions?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createCodexFilesystemToolSet(options?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createGeminiFilesystemToolSet(options?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createModelAgnosticFilesystemToolSet(options?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createCodexApplyPatchTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof applyPatchInputSchema, string>;
+declare function createCodexReadFileTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof codexReadFileInputSchema, string>;
+declare function createListDirTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof codexListDirInputSchema, string>;
+declare function createGrepFilesTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof codexGrepFilesInputSchema, string>;
+declare function createReadFileTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiReadFileInputSchema, string>;
+declare function createWriteFileTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiWriteFileInputSchema, string>;
+declare function createReplaceTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiReplaceInputSchema, string>;
+declare function createListDirectoryTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiListDirectoryInputSchema, string>;
+declare function createGrepSearchTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiGrepSearchInputSchema, string>;
+declare function createGlobTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiGlobInputSchema, string>;
+
+type AgentFilesystemToolConfig = {
+    readonly enabled?: boolean;
+    readonly profile?: AgentFilesystemToolProfile;
+    readonly options?: AgentFilesystemToolsOptions;
+};
+type AgentFilesystemToolSelection = boolean | AgentFilesystemToolProfile | AgentFilesystemToolConfig;
+type RunAgentLoopRequest = Omit<LlmToolLoopRequest, "tools"> & {
+    readonly tools?: LlmToolSet;
+    readonly filesystemTool?: AgentFilesystemToolSelection;
+    readonly filesystem_tool?: AgentFilesystemToolSelection;
+};
+declare function runAgentLoop(request: RunAgentLoopRequest): Promise<LlmToolLoopResult>;
+
+type ApplyPatchAccessContext = {
+    readonly cwd: string;
+    readonly kind: "add" | "delete" | "update" | "move";
+    readonly path: string;
+    readonly fromPath?: string;
+    readonly toPath?: string;
+};
+type ApplyPatchAccessHook = (context: ApplyPatchAccessContext) => Promise<void> | void;
+type ApplyPatchRequest = {
+    readonly patch: string;
+    readonly cwd?: string;
+    readonly fs?: AgentFilesystem;
+    readonly allowOutsideCwd?: boolean;
+    readonly checkAccess?: ApplyPatchAccessHook;
+    readonly maxPatchBytes?: number;
+};
+type ApplyPatchResult = {
+    readonly success: true;
+    readonly summary: string;
+    readonly added: readonly string[];
+    readonly modified: readonly string[];
+    readonly deleted: readonly string[];
+};
+type CreateApplyPatchToolOptions = Omit<ApplyPatchRequest, "patch"> & {
+    readonly description?: string;
+};
+declare const applyPatchToolInputSchema: z.ZodObject<{
+    input: z.ZodString;
+}, z.core.$strip>;
+type ApplyPatchToolInput = z.output<typeof applyPatchToolInputSchema>;
+declare function createApplyPatchTool(options?: CreateApplyPatchToolOptions): LlmExecutableTool<typeof applyPatchToolInputSchema, ApplyPatchResult>;
+declare function applyPatch(request: ApplyPatchRequest): Promise<ApplyPatchResult>;
+
 type ChatGptAuthProfile = {
     readonly access: string;
     readonly refresh: string;
@@ -249,4 +497,4 @@ type GeminiConfiguration = {
 };
 declare function configureGemini(options?: GeminiConfiguration): void;
 
-export { type ChatGptAuthProfile, type GeminiModelId, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, LlmJsonCallError, type LlmJsonRequest, type LlmModelEvent, type LlmProvider, type LlmStreamEvent, type LlmTextDeltaEvent, type LlmTextRequest, type LlmTextResult, type LlmTextStream, type LlmToolCallContext, type LlmToolCallResult, type LlmToolConfig, type LlmToolLoopRequest, type LlmToolLoopResult, type LlmToolLoopStep, type LlmToolSet, type LlmUsageEvent, type LlmUsageTokens, type LlmWebSearchMode, appendMarkdownSourcesSection, configureGemini, convertGooglePartsToLlmParts, encodeChatGptAuthJson, encodeChatGptAuthJsonB64, estimateCallCostUsd, exchangeChatGptOauthCode, generateImageInBatches, generateImages, generateJson, generateText, getChatGptAuthProfile, getCurrentToolCallContext, isGeminiModelId, loadEnvFromFile, loadLocalEnv, parseJsonFromLlmText, refreshChatGptOauthToken, runToolLoop, sanitisePartForLogging, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };
+export { type AgentDirectoryEntry, type AgentFilesystem, type AgentFilesystemToolAccessContext, type AgentFilesystemToolAccessHook, type AgentFilesystemToolAction, type AgentFilesystemToolConfig, type AgentFilesystemToolName, type AgentFilesystemToolProfile, type AgentFilesystemToolSelection, type AgentFilesystemToolsOptions, type AgentPathInfo, type AgentPathKind, type ApplyPatchAccessContext, type ApplyPatchAccessHook, type ApplyPatchRequest, type ApplyPatchResult, type ApplyPatchToolInput, type ChatGptAuthProfile, type CodexApplyPatchToolInput, type CodexGrepFilesToolInput, type CodexListDirToolInput, type CodexReadFileToolInput, type CreateApplyPatchToolOptions, type GeminiGlobToolInput, type GeminiGrepSearchToolInput, type GeminiListDirectoryToolInput, type GeminiModelId, type GeminiReadFileToolInput, type GeminiReplaceToolInput, type GeminiWriteFileToolInput, InMemoryAgentFilesystem, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, type LlmInputMessage, LlmJsonCallError, type LlmJsonRequest, type LlmJsonStream, type LlmJsonStreamEvent, type LlmJsonStreamRequest, type LlmModelEvent, type LlmProvider, type LlmStreamEvent, type LlmTextDeltaEvent, type LlmTextRequest, type LlmTextResult, type LlmTextStream, type LlmToolCallContext, type LlmToolCallResult, type LlmToolConfig, type LlmToolLoopRequest, type LlmToolLoopResult, type LlmToolLoopStep, type LlmToolSet, type LlmUsageEvent, type LlmUsageTokens, type LlmWebSearchMode, type RunAgentLoopRequest, appendMarkdownSourcesSection, applyPatch, configureGemini, convertGooglePartsToLlmParts, createApplyPatchTool, createCodexApplyPatchTool, createCodexFilesystemToolSet, createCodexReadFileTool, createFilesystemToolSetForModel, createGeminiFilesystemToolSet, createGlobTool, createGrepFilesTool, createGrepSearchTool, createInMemoryAgentFilesystem, createListDirTool, createListDirectoryTool, createModelAgnosticFilesystemToolSet, createNodeAgentFilesystem, createReadFileTool, createReplaceTool, createWriteFileTool, encodeChatGptAuthJson, encodeChatGptAuthJsonB64, estimateCallCostUsd, exchangeChatGptOauthCode, generateImageInBatches, generateImages, generateJson, generateText, getChatGptAuthProfile, getCurrentToolCallContext, isGeminiModelId, loadEnvFromFile, loadLocalEnv, parseJsonFromLlmText, refreshChatGptOauthToken, resolveFilesystemToolProfile, runAgentLoop, runToolLoop, sanitisePartForLogging, streamJson, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };

package/dist/index.d.ts

@@ -29,7 +29,7 @@ type LlmToolCallContext = {
 };
 declare function getCurrentToolCallContext(): LlmToolCallContext | null;
 type JsonSchema = Record<string, unknown>;
-type LlmRole = "user" | "model" | "system" | "tool";
+type LlmRole = "user" | "assistant" | "system" | "developer" | "tool";
 type LlmInlineDataPart = {
     type: "inlineData";
     data: string;
@@ -93,11 +93,45 @@ type LlmTextStream = {
     readonly result: Promise<LlmTextResult>;
     readonly abort: () => void;
 };
+type DeepPartial<T> = T extends ReadonlyArray<infer Item> ? ReadonlyArray<DeepPartial<Item>> : T extends Array<infer Item> ? Array<DeepPartial<Item>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+type LlmJsonPartialEvent<T> = {
+    readonly type: "json";
+    readonly stage: "partial";
+    readonly value: DeepPartial<T>;
+};
+type LlmJsonFinalEvent<T> = {
+    readonly type: "json";
+    readonly stage: "final";
+    readonly value: T;
+};
+type LlmJsonStreamEvent<T> = LlmStreamEvent | LlmJsonPartialEvent<T> | LlmJsonFinalEvent<T>;
+type LlmJsonStream<T> = {
+    readonly events: AsyncIterable<LlmJsonStreamEvent<T>>;
+    readonly result: Promise<{
+        readonly value: T;
+        readonly rawText: string;
+        readonly result: LlmTextResult;
+    }>;
+    readonly abort: () => void;
+};
+type LlmInputMessage = {
+    readonly role: "user" | "assistant" | "system" | "developer";
+    readonly content: string | readonly LlmContentPart[];
+};
 type LlmInput = {
-    readonly prompt: string;
-    readonly systemPrompt?: string;
-} | {
-    readonly contents: readonly LlmContent[];
+    /**
+     * OpenAI-style input:
+     * - a plain string becomes one user message
+     * - message arrays allow multi-turn + role-specific content
+     */
+    readonly input: string | readonly LlmInputMessage[];
+    /**
+     * OpenAI-style top-level instructions.
+     * Applied as a system message before input.
+     */
+    readonly instructions?: string;
 };
 type LlmBaseRequest = {
     readonly model: string;
@@ -117,6 +151,18 @@ type LlmJsonRequest<T> = LlmInput & LlmBaseRequest & {
     readonly openAiSchemaName?: string;
     readonly maxAttempts?: number;
     readonly normalizeJson?: (value: unknown) => unknown;
+    /**
+     * Optional streaming callback. Useful to surface thought deltas while still
+     * returning a single validated JSON result.
+     */
+    readonly onEvent?: (event: LlmStreamEvent) => void;
+};
+type LlmJsonStreamRequest<T> = LlmJsonRequest<T> & {
+    /**
+     * - "partial" (default): emit best-effort partial JSON snapshots while streaming.
+     * - "final": stream thought deltas but only emit the final validated JSON value.
+     */
+    readonly streamMode?: "partial" | "final";
 };
 declare class LlmJsonCallError extends Error {
     readonly attempts: ReadonlyArray<{
@@ -195,6 +241,7 @@ declare function convertGooglePartsToLlmParts(parts: readonly Part[]): LlmConten
 declare function parseJsonFromLlmText(rawText: string): unknown;
 declare function streamText(request: LlmTextRequest): LlmTextStream;
 declare function generateText(request: LlmTextRequest): Promise<LlmTextResult>;
+declare function streamJson<T>(request: LlmJsonStreamRequest<T>): LlmJsonStream<T>;
 declare function generateJson<T>(request: LlmJsonRequest<T>): Promise<{
     readonly value: T;
     readonly rawText: string;
@@ -223,6 +270,207 @@ declare function loadEnvFromFile(filePath: string, { override }?: {
     override?: boolean;
 }): void;
 
+type AgentPathKind = "file" | "directory" | "symlink" | "other";
+type AgentPathInfo = {
+    readonly kind: AgentPathKind;
+    readonly mtimeMs: number;
+};
+type AgentDirectoryEntry = {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: AgentPathKind;
+    readonly mtimeMs: number;
+};
+interface AgentFilesystem {
+    readTextFile(filePath: string): Promise<string>;
+    writeTextFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    ensureDir(directoryPath: string): Promise<void>;
+    readDir(directoryPath: string): Promise<readonly AgentDirectoryEntry[]>;
+    stat(entryPath: string): Promise<AgentPathInfo>;
+}
+declare class InMemoryAgentFilesystem implements AgentFilesystem {
+    #private;
+    constructor(initialFiles?: Record<string, string>);
+    readTextFile(filePath: string): Promise<string>;
+    writeTextFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    ensureDir(directoryPath: string): Promise<void>;
+    readDir(directoryPath: string): Promise<readonly AgentDirectoryEntry[]>;
+    stat(entryPath: string): Promise<AgentPathInfo>;
+    snapshot(): Record<string, string>;
+}
+declare function createNodeAgentFilesystem(): AgentFilesystem;
+declare function createInMemoryAgentFilesystem(initialFiles?: Record<string, string>): InMemoryAgentFilesystem;
+
+type AgentFilesystemToolProfile = "auto" | "model-agnostic" | "codex" | "gemini";
+type AgentFilesystemToolName = "apply_patch" | "read_file" | "write_file" | "replace" | "list_dir" | "list_directory" | "grep_files" | "grep_search" | "glob";
+type AgentFilesystemToolAction = "read" | "write" | "delete" | "move" | "list" | "search";
+type AgentFilesystemToolAccessContext = {
+    readonly cwd: string;
+    readonly tool: AgentFilesystemToolName;
+    readonly action: AgentFilesystemToolAction;
+    readonly path: string;
+    readonly fromPath?: string;
+    readonly toPath?: string;
+    readonly pattern?: string;
+    readonly include?: string;
+};
+type AgentFilesystemToolAccessHook = (context: AgentFilesystemToolAccessContext) => Promise<void> | void;
+type AgentFilesystemToolsOptions = {
+    readonly cwd?: string;
+    readonly fs?: AgentFilesystem;
+    readonly allowOutsideCwd?: boolean;
+    readonly checkAccess?: AgentFilesystemToolAccessHook;
+    readonly maxLineLength?: number;
+    readonly grepMaxScannedFiles?: number;
+    readonly applyPatch?: {
+        readonly maxPatchBytes?: number;
+    };
+};
+declare const codexReadFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        slice: "slice";
+        indentation: "indentation";
+    }>>;
+    indentation: z.ZodOptional<z.ZodObject<{
+        anchor_line: z.ZodOptional<z.ZodNumber>;
+        max_levels: z.ZodOptional<z.ZodNumber>;
+        include_siblings: z.ZodOptional<z.ZodBoolean>;
+        include_header: z.ZodOptional<z.ZodBoolean>;
+        max_lines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const codexListDirInputSchema: z.ZodObject<{
+    dir_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    depth: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const codexGrepFilesInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    include: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const applyPatchInputSchema: z.ZodObject<{
+    input: z.ZodString;
+}, z.core.$strip>;
+declare const geminiReadFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const geminiWriteFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+declare const geminiReplaceInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    instruction: z.ZodString;
+    old_string: z.ZodString;
+    new_string: z.ZodString;
+    expected_replacements: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const geminiListDirectoryInputSchema: z.ZodObject<{
+    dir_path: z.ZodString;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    file_filtering_options: z.ZodOptional<z.ZodObject<{
+        respect_git_ignore: z.ZodOptional<z.ZodBoolean>;
+        respect_gemini_ignore: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const geminiGrepSearchInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    dir_path: z.ZodOptional<z.ZodString>;
+    include: z.ZodOptional<z.ZodString>;
+    exclude_pattern: z.ZodOptional<z.ZodString>;
+    names_only: z.ZodOptional<z.ZodBoolean>;
+    max_matches_per_file: z.ZodOptional<z.ZodNumber>;
+    total_max_matches: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const geminiGlobInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    dir_path: z.ZodOptional<z.ZodString>;
+    case_sensitive: z.ZodOptional<z.ZodBoolean>;
+    respect_git_ignore: z.ZodOptional<z.ZodBoolean>;
+    respect_gemini_ignore: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type CodexReadFileToolInput = z.output<typeof codexReadFileInputSchema>;
+type CodexListDirToolInput = z.output<typeof codexListDirInputSchema>;
+type CodexGrepFilesToolInput = z.output<typeof codexGrepFilesInputSchema>;
+type CodexApplyPatchToolInput = z.output<typeof applyPatchInputSchema>;
+type GeminiReadFileToolInput = z.output<typeof geminiReadFileInputSchema>;
+type GeminiWriteFileToolInput = z.output<typeof geminiWriteFileInputSchema>;
+type GeminiReplaceToolInput = z.output<typeof geminiReplaceInputSchema>;
+type GeminiListDirectoryToolInput = z.output<typeof geminiListDirectoryInputSchema>;
+type GeminiGrepSearchToolInput = z.output<typeof geminiGrepSearchInputSchema>;
+type GeminiGlobToolInput = z.output<typeof geminiGlobInputSchema>;
+declare function resolveFilesystemToolProfile(model: string, profile?: AgentFilesystemToolProfile): Exclude<AgentFilesystemToolProfile, "auto">;
+declare function createFilesystemToolSetForModel(model: string, profileOrOptions?: AgentFilesystemToolProfile | AgentFilesystemToolsOptions, maybeOptions?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createCodexFilesystemToolSet(options?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createGeminiFilesystemToolSet(options?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createModelAgnosticFilesystemToolSet(options?: AgentFilesystemToolsOptions): LlmToolSet;
+declare function createCodexApplyPatchTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof applyPatchInputSchema, string>;
+declare function createCodexReadFileTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof codexReadFileInputSchema, string>;
+declare function createListDirTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof codexListDirInputSchema, string>;
+declare function createGrepFilesTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof codexGrepFilesInputSchema, string>;
+declare function createReadFileTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiReadFileInputSchema, string>;
+declare function createWriteFileTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiWriteFileInputSchema, string>;
+declare function createReplaceTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiReplaceInputSchema, string>;
+declare function createListDirectoryTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiListDirectoryInputSchema, string>;
+declare function createGrepSearchTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiGrepSearchInputSchema, string>;
+declare function createGlobTool(options?: AgentFilesystemToolsOptions): LlmExecutableTool<typeof geminiGlobInputSchema, string>;
+
+type AgentFilesystemToolConfig = {
+    readonly enabled?: boolean;
+    readonly profile?: AgentFilesystemToolProfile;
+    readonly options?: AgentFilesystemToolsOptions;
+};
+type AgentFilesystemToolSelection = boolean | AgentFilesystemToolProfile | AgentFilesystemToolConfig;
+type RunAgentLoopRequest = Omit<LlmToolLoopRequest, "tools"> & {
+    readonly tools?: LlmToolSet;
+    readonly filesystemTool?: AgentFilesystemToolSelection;
+    readonly filesystem_tool?: AgentFilesystemToolSelection;
+};
+declare function runAgentLoop(request: RunAgentLoopRequest): Promise<LlmToolLoopResult>;
+
+type ApplyPatchAccessContext = {
+    readonly cwd: string;
+    readonly kind: "add" | "delete" | "update" | "move";
+    readonly path: string;
+    readonly fromPath?: string;
+    readonly toPath?: string;
+};
+type ApplyPatchAccessHook = (context: ApplyPatchAccessContext) => Promise<void> | void;
+type ApplyPatchRequest = {
+    readonly patch: string;
+    readonly cwd?: string;
+    readonly fs?: AgentFilesystem;
+    readonly allowOutsideCwd?: boolean;
+    readonly checkAccess?: ApplyPatchAccessHook;
+    readonly maxPatchBytes?: number;
+};
+type ApplyPatchResult = {
+    readonly success: true;
+    readonly summary: string;
+    readonly added: readonly string[];
+    readonly modified: readonly string[];
+    readonly deleted: readonly string[];
+};
+type CreateApplyPatchToolOptions = Omit<ApplyPatchRequest, "patch"> & {
+    readonly description?: string;
+};
+declare const applyPatchToolInputSchema: z.ZodObject<{
+    input: z.ZodString;
+}, z.core.$strip>;
+type ApplyPatchToolInput = z.output<typeof applyPatchToolInputSchema>;
+declare function createApplyPatchTool(options?: CreateApplyPatchToolOptions): LlmExecutableTool<typeof applyPatchToolInputSchema, ApplyPatchResult>;
+declare function applyPatch(request: ApplyPatchRequest): Promise<ApplyPatchResult>;
+
 type ChatGptAuthProfile = {
     readonly access: string;
     readonly refresh: string;
@@ -249,4 +497,4 @@ type GeminiConfiguration = {
 };
 declare function configureGemini(options?: GeminiConfiguration): void;
 
-export { type ChatGptAuthProfile, type GeminiModelId, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, LlmJsonCallError, type LlmJsonRequest, type LlmModelEvent, type LlmProvider, type LlmStreamEvent, type LlmTextDeltaEvent, type LlmTextRequest, type LlmTextResult, type LlmTextStream, type LlmToolCallContext, type LlmToolCallResult, type LlmToolConfig, type LlmToolLoopRequest, type LlmToolLoopResult, type LlmToolLoopStep, type LlmToolSet, type LlmUsageEvent, type LlmUsageTokens, type LlmWebSearchMode, appendMarkdownSourcesSection, configureGemini, convertGooglePartsToLlmParts, encodeChatGptAuthJson, encodeChatGptAuthJsonB64, estimateCallCostUsd, exchangeChatGptOauthCode, generateImageInBatches, generateImages, generateJson, generateText, getChatGptAuthProfile, getCurrentToolCallContext, isGeminiModelId, loadEnvFromFile, loadLocalEnv, parseJsonFromLlmText, refreshChatGptOauthToken, runToolLoop, sanitisePartForLogging, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };
+export { type AgentDirectoryEntry, type AgentFilesystem, type AgentFilesystemToolAccessContext, type AgentFilesystemToolAccessHook, type AgentFilesystemToolAction, type AgentFilesystemToolConfig, type AgentFilesystemToolName, type AgentFilesystemToolProfile, type AgentFilesystemToolSelection, type AgentFilesystemToolsOptions, type AgentPathInfo, type AgentPathKind, type ApplyPatchAccessContext, type ApplyPatchAccessHook, type ApplyPatchRequest, type ApplyPatchResult, type ApplyPatchToolInput, type ChatGptAuthProfile, type CodexApplyPatchToolInput, type CodexGrepFilesToolInput, type CodexListDirToolInput, type CodexReadFileToolInput, type CreateApplyPatchToolOptions, type GeminiGlobToolInput, type GeminiGrepSearchToolInput, type GeminiListDirectoryToolInput, type GeminiModelId, type GeminiReadFileToolInput, type GeminiReplaceToolInput, type GeminiWriteFileToolInput, InMemoryAgentFilesystem, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, type LlmInputMessage, LlmJsonCallError, type LlmJsonRequest, type LlmJsonStream, type LlmJsonStreamEvent, type LlmJsonStreamRequest, type LlmModelEvent, type LlmProvider, type LlmStreamEvent, type LlmTextDeltaEvent, type LlmTextRequest, type LlmTextResult, type LlmTextStream, type LlmToolCallContext, type LlmToolCallResult, type LlmToolConfig, type LlmToolLoopRequest, type LlmToolLoopResult, type LlmToolLoopStep, type LlmToolSet, type LlmUsageEvent, type LlmUsageTokens, type LlmWebSearchMode, type RunAgentLoopRequest, appendMarkdownSourcesSection, applyPatch, configureGemini, convertGooglePartsToLlmParts, createApplyPatchTool, createCodexApplyPatchTool, createCodexFilesystemToolSet, createCodexReadFileTool, createFilesystemToolSetForModel, createGeminiFilesystemToolSet, createGlobTool, createGrepFilesTool, createGrepSearchTool, createInMemoryAgentFilesystem, createListDirTool, createListDirectoryTool, createModelAgnosticFilesystemToolSet, createNodeAgentFilesystem, createReadFileTool, createReplaceTool, createWriteFileTool, encodeChatGptAuthJson, encodeChatGptAuthJsonB64, estimateCallCostUsd, exchangeChatGptOauthCode, generateImageInBatches, generateImages, generateJson, generateText, getChatGptAuthProfile, getCurrentToolCallContext, isGeminiModelId, loadEnvFromFile, loadLocalEnv, parseJsonFromLlmText, refreshChatGptOauthToken, resolveFilesystemToolProfile, runAgentLoop, runToolLoop, sanitisePartForLogging, streamJson, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };