feat(openai): add support for apply patch tool

Author: christian-bromann

.changeset/poor-dogs-joke.md

@@ -0,0 +1,5 @@
+---
+"@langchain/openai": minor
+---
+
+feat(openai): add support for apply patch tool

libs/providers/langchain-openai/README.md

@@ -508,6 +508,70 @@ const response = await llmWithShell.invoke(
 
 For more information, see [OpenAI's Local Shell Documentation](https://platform.openai.com/docs/guides/tools-local-shell).
 
+### Apply Patch Tool
+
+The Apply Patch tool allows models to propose structured diffs that your integration applies. This enables iterative, multi-step code editing workflows where the model can create, update, and delete files in your codebase.
+
+**When to use**:
+
+- **Multi-file refactors** – Rename symbols, extract helpers, or reorganize modules
+- **Bug fixes** – Have the model both diagnose issues and emit precise patches
+- **Tests & docs generation** – Create new test files, fixtures, and documentation
+- **Migrations & mechanical edits** – Apply repetitive, structured updates
+
+> **Security Warning**: Applying patches can modify files in your codebase. Always validate paths, implement backups, and consider sandboxing.
+> **Note**: This tool is designed to work with `gpt-5.1` model.
+
+```typescript
+import { ChatOpenAI, tools } from "@langchain/openai";
+import { applyDiff } from "@openai/agents";
+import * as fs from "fs/promises";
+
+const model = new ChatOpenAI({ model: "gpt-5.1" });
+
+// With execute callback for automatic patch handling
+const patchTool = tools.applyPatch({
+  execute: async (operation) => {
+    if (operation.type === "create_file") {
+      const content = applyDiff("", operation.diff, "create");
+      await fs.writeFile(operation.path, content);
+      return `Created ${operation.path}`;
+    }
+    if (operation.type === "update_file") {
+      const current = await fs.readFile(operation.path, "utf-8");
+      const newContent = applyDiff(current, operation.diff);
+      await fs.writeFile(operation.path, newContent);
+      return `Updated ${operation.path}`;
+    }
+    if (operation.type === "delete_file") {
+      await fs.unlink(operation.path);
+      return `Deleted ${operation.path}`;
+    }
+    return "Unknown operation type";
+  },
+});
+
+const llmWithPatch = model.bindTools([patchTool]);
+const response = await llmWithPatch.invoke(
+  "Rename the fib() function to fibonacci() in lib/fib.py"
+);
+```
+
+**Operation types**: The model returns operations with these properties:
+
+- `create_file` – Create a new file at `path` with content from `diff`
+- `update_file` – Modify an existing file at `path` using V4A diff format in `diff`
+- `delete_file` – Remove a file at `path`
+
+**Best practices**:
+
+- **Path validation**: Prevent directory traversal and restrict edits to allowed directories
+- **Backups**: Consider backing up files before applying patches
+- **Error handling**: Return descriptive error messages so the model can recover
+- **Atomicity**: Decide whether you want "all-or-nothing" semantics (rollback if any patch fails)
+
+For more information, see [OpenAI's Apply Patch Documentation](https://platform.openai.com/docs/guides/tools-apply-patch).
+
 ## Embeddings
 
 This package also adds support for OpenAI's embeddings model.

libs/providers/langchain-openai/src/tools/applyPatch.ts

@@ -0,0 +1,167 @@
+import { OpenAI as OpenAIClient } from "openai";
+import { tool } from "@langchain/core/tools";
+
+/**
+ * Re-export operation types from OpenAI SDK for convenience.
+ */
+export type ApplyPatchCreateFileOperation =
+  OpenAIClient.Responses.ResponseApplyPatchToolCall.CreateFile;
+export type ApplyPatchUpdateFileOperation =
+  OpenAIClient.Responses.ResponseApplyPatchToolCall.UpdateFile;
+export type ApplyPatchDeleteFileOperation =
+  OpenAIClient.Responses.ResponseApplyPatchToolCall.DeleteFile;
+
+/**
+ * Union type of all apply patch operations from OpenAI SDK.
+ */
+export type ApplyPatchOperation = NonNullable<
+  OpenAIClient.Responses.ResponseApplyPatchToolCall["operation"]
+>;
+
+/**
+ * Options for the Apply Patch tool.
+ */
+export interface ApplyPatchOptions {
+  /**
+   * Execute function that handles patch operations.
+   * This function receives the operation input and should return a string
+   * describing the result (success or failure message).
+   *
+   * The operation types are:
+   * - `create_file`: Create a new file at the specified path with the diff content
+   * - `update_file`: Modify an existing file using V4A diff format
+   * - `delete_file`: Remove a file at the specified path
+   *
+   * @example
+   * ```typescript
+   * execute: async (operation) => {
+   *   if (operation.type === "create_file") {
+   *     const content = applyDiff("", operation.diff, "create");
+   *     await fs.writeFile(operation.path, content);
+   *     return `Created ${operation.path}`;
+   *   }
+   *   if (operation.type === "update_file") {
+   *     const current = await fs.readFile(operation.path, "utf-8");
+   *     const newContent = applyDiff(current, operation.diff);
+   *     await fs.writeFile(operation.path, newContent);
+   *     return `Updated ${operation.path}`;
+   *   }
+   *   if (operation.type === "delete_file") {
+   *     await fs.unlink(operation.path);
+   *     return `Deleted ${operation.path}`;
+   *   }
+   *   return "Unknown operation type";
+   * }
+   * ```
+   */
+  execute: (operation: ApplyPatchOperation) => string | Promise<string>;
+}
+
+/**
+ * OpenAI Apply Patch tool type for the Responses API.
+ */
+export type ApplyPatchTool = OpenAIClient.Responses.ApplyPatchTool;
+
+const TOOL_NAME = "apply_patch";
+
+/**
+ * Creates an Apply Patch tool that allows models to propose structured diffs
+ * that your integration applies. This enables iterative, multi-step code
+ * editing workflows.
+ *
+ * **Apply Patch** lets GPT-5.1 create, update, and delete files in your codebase
+ * using structured diffs. Instead of just suggesting edits, the model emits
+ * patch operations that your application applies and then reports back on.
+ *
+ * **When to use**:
+ * - **Multi-file refactors** – Rename symbols, extract helpers, or reorganize modules
+ * - **Bug fixes** – Have the model both diagnose issues and emit precise patches
+ * - **Tests & docs generation** – Create new test files, fixtures, and documentation
+ * - **Migrations & mechanical edits** – Apply repetitive, structured updates
+ *
+ * **How it works**:
+ * The tool operates in a continuous loop:
+ * 1. Model sends patch operations (`apply_patch_call` with operation type)
+ * 2. Your code applies the patch to your working directory or repo
+ * 3. You return success/failure status and optional output
+ * 4. Repeat until the task is complete
+ *
+ * **Security Warning**: Applying patches can modify files in your codebase.
+ * Always validate paths, implement backups, and consider sandboxing.
+ *
+ * @see {@link https://platform.openai.com/docs/guides/tools-apply-patch | OpenAI Apply Patch Documentation}
+ *
+ * @param options - Configuration options for the Apply Patch tool
+ * @returns An Apply Patch tool that can be passed to `bindTools`
+ *
+ * @example
+ * ```typescript
+ * import { ChatOpenAI, tools } from "@langchain/openai";
+ * import { applyDiff } from "@openai/agents";
+ * import * as fs from "fs/promises";
+ *
+ * const model = new ChatOpenAI({ model: "gpt-5.1" });
+ *
+ * // With execute callback for automatic patch handling
+ * const patchTool = tools.applyPatch({
+ *   execute: async (operation) => {
+ *     if (operation.type === "create_file") {
+ *       const content = applyDiff("", operation.diff, "create");
+ *       await fs.writeFile(operation.path, content);
+ *       return `Created ${operation.path}`;
+ *     }
+ *     if (operation.type === "update_file") {
+ *       const current = await fs.readFile(operation.path, "utf-8");
+ *       const newContent = applyDiff(current, operation.diff);
+ *       await fs.writeFile(operation.path, newContent);
+ *       return `Updated ${operation.path}`;
+ *     }
+ *     if (operation.type === "delete_file") {
+ *       await fs.unlink(operation.path);
+ *       return `Deleted ${operation.path}`;
+ *     }
+ *     return "Unknown operation type";
+ *   },
+ * });
+ *
+ * const llmWithPatch = model.bindTools([patchTool]);
+ * const response = await llmWithPatch.invoke(
+ *   "Rename the fib() function to fibonacci() in lib/fib.py"
+ * );
+ * ```
+ *
+ * @remarks
+ * - Only available through the Responses API (not Chat Completions)
+ * - Designed for use with `gpt-5.1` model
+ * - Operations include: `create_file`, `update_file`, `delete_file`
+ * - Patches use V4A diff format for updates
+ * - Always validate paths to prevent directory traversal attacks
+ * - Consider backing up files before applying patches
+ * - Implement "all-or-nothing" semantics if atomicity is required
+ */
+export function applyPatch(options: ApplyPatchOptions) {
+  const patchTool = tool(options.execute, {
+    name: TOOL_NAME,
+    description:
+      "Apply structured diffs to create, update, or delete files in the codebase.",
+    schema: {
+      type: "object",
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["create_file", "update_file", "delete_file"],
+        },
+      },
+      required: ["operation"],
+    },
+  });
+
+  patchTool.extras = {
+    ...(patchTool.extras ?? {}),
+    providerToolDefinition: {
+      type: "apply_patch",
+    } as ApplyPatchTool,
+  };
+
+  return patchTool;
+}

libs/providers/langchain-openai/src/tools/index.ts

@@ -68,6 +68,16 @@ export type {
   LocalShellAction,
 } from "./localShell.js";
 
+import { applyPatch } from "./applyPatch.js";
+export type {
+  ApplyPatchTool,
+  ApplyPatchOptions,
+  ApplyPatchOperation,
+  ApplyPatchCreateFileOperation,
+  ApplyPatchUpdateFileOperation,
+  ApplyPatchDeleteFileOperation,
+} from "./applyPatch.js";
+
 export const tools = {
   webSearch,
   mcp,
@@ -76,4 +86,5 @@ export const tools = {
   imageGeneration,
   computerUse,
   localShell,
+  applyPatch,
 };

libs/providers/langchain-openai/src/tools/tests/applyPatch.test-d.ts

@@ -0,0 +1,16 @@
+import { expectTypeOf, it, describe } from "vitest";
+import { tools } from "../index.js";
+
+describe("OpenAI Apply Patch Tool Type Tests", () => {
+  it("applyPatch execute receives correct operation types", () => {
+    tools.applyPatch({
+      execute: async (operation) => {
+        expectTypeOf(operation.type).toEqualTypeOf<
+          "create_file" | "update_file" | "delete_file"
+        >();
+        expectTypeOf(operation.path).toEqualTypeOf<string>();
+        return "done";
+      },
+    });
+  });
+});

libs/providers/langchain-openai/src/tools/tests/applyPatch.test.ts

@@ -0,0 +1,74 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { expect, it, describe } from "vitest";
+import { tools } from "../index.js";
+
+describe("OpenAI Apply Patch Tool Tests", () => {
+  it("applyPatch creates valid tool definitions", () => {
+    const patch = tools.applyPatch({
+      execute: async () => "done",
+    });
+
+    expect(patch.name).toBe("apply_patch");
+    expect(patch.extras?.providerToolDefinition).toMatchObject({
+      type: "apply_patch",
+    });
+  });
+
+  it("applyPatch execute callback receives operation correctly", async () => {
+    const operations: Array<{ type: string; path?: string; diff?: string }> =
+      [];
+
+    const patch = tools.applyPatch({
+      execute: async (operation) => {
+        operations.push(operation);
+        return `Processed ${operation.path}`;
+      },
+    });
+
+    // Directly call the execute function
+    const createOp = {
+      type: "create_file" as const,
+      path: "test.txt",
+      diff: "+hello world",
+    };
+
+    // Access the underlying execute function from the tool
+    const executeFunc = patch.func;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = await executeFunc(createOp as any);
+
+    expect(operations).toHaveLength(1);
+    expect(operations[0].type).toBe("create_file");
+    expect(operations[0].path).toBe("test.txt");
+    expect(result).toBe("Processed test.txt");
+  });
+
+  it("applyPatch handles all operation types", async () => {
+    const operations: string[] = [];
+
+    const patch = tools.applyPatch({
+      execute: async (operation) => {
+        operations.push(operation.type);
+        return "ok";
+      },
+    });
+
+    const executeFunc = patch.func;
+
+    await executeFunc({
+      type: "create_file",
+      path: "a.txt",
+      diff: "+a",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+    await executeFunc({
+      type: "update_file",
+      path: "b.txt",
+      diff: "-x\n+y",
+    } as any);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await executeFunc({ type: "delete_file", path: "c.txt" } as any);
+
+    expect(operations).toEqual(["create_file", "update_file", "delete_file"]);
+  });
+});