feat(openai): add support for local shell tool

Author: christian-bromann

.changeset/moody-eels-pump.md

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

libs/providers/langchain-openai/README.md

@@ -464,6 +464,50 @@ const response = await llmWithComputer.invoke(
 
 For more information, see [OpenAI's Computer Use Documentation](https://platform.openai.com/docs/guides/tools-computer-use).
 
+### Local Shell Tool
+
+The Local Shell tool allows models to run shell commands locally on a machine you provide. Commands are executed inside your own runtime—the API only returns the instructions.
+
+> **Security Warning**: Running arbitrary shell commands can be dangerous. Always sandbox execution or add strict allow/deny-lists before forwarding commands to the system shell.
+> **Note**: This tool is designed to work with [Codex CLI](https://github.com/openai/codex) and the `codex-mini-latest` model.
+
+```typescript
+import { ChatOpenAI, tools } from "@langchain/openai";
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+const model = new ChatOpenAI({ model: "codex-mini-latest" });
+
+// With execute callback for automatic command handling
+const shell = tools.localShell({
+  execute: async (action) => {
+    const { command, env, working_directory, timeout_ms } = action;
+    const result = await execAsync(command.join(" "), {
+      cwd: working_directory ?? process.cwd(),
+      env: { ...process.env, ...env },
+      timeout: timeout_ms ?? undefined,
+    });
+    return result.stdout + result.stderr;
+  },
+});
+
+const llmWithShell = model.bindTools([shell]);
+const response = await llmWithShell.invoke(
+  "List files in the current directory"
+);
+```
+
+**Action properties**: The model returns actions with these properties:
+
+- `command` - Array of argv tokens to execute
+- `env` - Environment variables to set
+- `working_directory` - Directory to run the command in
+- `timeout_ms` - Suggested timeout (enforce your own limits)
+- `user` - Optional user to run the command as
+
+For more information, see [OpenAI's Local Shell Documentation](https://platform.openai.com/docs/guides/tools-local-shell).
+
 ## Embeddings
 
 This package also adds support for OpenAI's embeddings model.

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

@@ -61,11 +61,19 @@ export type {
   ComputerUseWaitAction,
 } from "./computerUse.js";
 
+import { localShell } from "./localShell.js";
+export type {
+  LocalShellTool,
+  LocalShellOptions,
+  LocalShellAction,
+} from "./localShell.js";
+
 export const tools = {
   webSearch,
   mcp,
   codeInterpreter,
   fileSearch,
   imageGeneration,
   computerUse,
+  localShell,
 };

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

@@ -0,0 +1,185 @@
+import { OpenAI as OpenAIClient } from "openai";
+import { tool } from "@langchain/core/tools";
+
+/**
+ * Re-export action type from OpenAI SDK for convenience.
+ * The action contains command details like argv tokens, environment variables,
+ * working directory, timeout, and user.
+ */
+export type LocalShellAction =
+  OpenAIClient.Responses.ResponseOutputItem.LocalShellCall.Action;
+
+/**
+ * Options for the Local Shell tool.
+ */
+export interface LocalShellOptions {
+  /**
+   * Optional execute function that handles shell command execution.
+   * This function receives the action input and should return the command output
+   * (stdout + stderr combined).
+   *
+   * If not provided, you'll need to handle action execution manually by
+   * checking `local_shell_call` outputs in the response.
+   *
+   * @example
+   * ```typescript
+   * execute: async (action) => {
+   *   const result = await exec(action.command.join(' '), {
+   *     cwd: action.working_directory,
+   *     env: { ...process.env, ...action.env },
+   *     timeout: action.timeout_ms,
+   *   });
+   *   return result.stdout + result.stderr;
+   * }
+   * ```
+   */
+  execute: (action: LocalShellAction) => string | Promise<string>;
+}
+
+/**
+ * OpenAI Local Shell tool type for the Responses API.
+ */
+export type LocalShellTool = OpenAIClient.Responses.Tool.LocalShell;
+
+const TOOL_NAME = "local_shell";
+
+/**
+ * Creates a Local Shell tool that allows models to run shell commands locally
+ * on a machine you provide. Commands are executed inside your own runtime—
+ * the API only returns the instructions, but does not execute them on OpenAI infrastructure.
+ *
+ * **Important**: The local shell tool is designed to work with
+ * [Codex CLI](https://github.com/openai/codex) and the `codex-mini-latest` model.
+ *
+ * **How it works**:
+ * The tool operates in a continuous loop:
+ * 1. Model sends shell commands (`local_shell_call` with `exec` action)
+ * 2. Your code executes the command locally
+ * 3. You return the output back to the model
+ * 4. Repeat until the task is complete
+ *
+ * **Security Warning**: Running arbitrary shell commands can be dangerous.
+ * Always sandbox execution or add strict allow/deny-lists before forwarding
+ * a command to the system shell.
+ *
+ * @see {@link https://platform.openai.com/docs/guides/tools-local-shell | OpenAI Local Shell Documentation}
+ *
+ * @param options - Optional configuration for the Local Shell tool
+ * @returns A Local Shell tool that can be passed to `bindTools`
+ *
+ * @example
+ * ```typescript
+ * import { ChatOpenAI, tools } from "@langchain/openai";
+ * import { exec } from "child_process";
+ * import { promisify } from "util";
+ *
+ * const execAsync = promisify(exec);
+ * const model = new ChatOpenAI({ model: "codex-mini-latest" });
+ *
+ * // With execute callback for automatic command handling
+ * const shell = tools.localShell({
+ *   execute: async (action) => {
+ *     const { command, env, working_directory, timeout_ms } = action;
+ *     const result = await execAsync(command.join(' '), {
+ *       cwd: working_directory ?? process.cwd(),
+ *       env: { ...process.env, ...env },
+ *       timeout: timeout_ms ?? undefined,
+ *     });
+ *     return result.stdout + result.stderr;
+ *   },
+ * });
+ *
+ * const llmWithShell = model.bindTools([shell]);
+ * const response = await llmWithShell.invoke(
+ *   "List files in the current directory"
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Without execute callback (manual handling)
+ * const shell = tools.localShell();
+ *
+ * const response = await model.invoke("List files", {
+ *   tools: [shell],
+ * });
+ *
+ * // Access the shell call from the response
+ * const shellCall = response.additional_kwargs.tool_outputs?.find(
+ *   (output) => output.type === "local_shell_call"
+ * );
+ * if (shellCall) {
+ *   console.log("Command to execute:", shellCall.action.command);
+ *   // Execute the command manually, then send back the output
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Full shell loop example
+ * async function shellLoop(model, task) {
+ *   let response = await model.invoke(task, {
+ *     tools: [tools.localShell()],
+ *   });
+ *
+ *   while (true) {
+ *     const shellCall = response.additional_kwargs.tool_outputs?.find(
+ *       (output) => output.type === "local_shell_call"
+ *     );
+ *
+ *     if (!shellCall) break;
+ *
+ *     // Execute command (with proper sandboxing!)
+ *     const output = await executeCommand(shellCall.action);
+ *
+ *     // Send output back to model
+ *     response = await model.invoke([
+ *       response,
+ *       {
+ *         type: "local_shell_call_output",
+ *         id: shellCall.call_id,
+ *         output: output,
+ *       },
+ *     ], {
+ *       tools: [tools.localShell()],
+ *     });
+ *   }
+ *
+ *   return response;
+ * }
+ * ```
+ *
+ * @remarks
+ * - Only available through the Responses API (not Chat Completions)
+ * - Designed for use with `codex-mini-latest` model
+ * - Commands are provided as argv tokens in `action.command`
+ * - Action includes: `command`, `env`, `working_directory`, `timeout_ms`, `user`
+ * - Always sandbox or validate commands before execution
+ * - The `timeout_ms` from the model is only a hint—enforce your own limits
+ */
+export function localShell(options: LocalShellOptions) {
+  const shellTool = tool(options.execute, {
+    name: TOOL_NAME,
+    description:
+      "Execute shell commands locally on the machine. Commands are provided as argv tokens.",
+    schema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["exec"],
+        },
+      },
+      required: ["action"],
+    },
+  });
+
+  shellTool.extras = {
+    ...(shellTool.extras ?? {}),
+    providerToolDefinition: {
+      type: "local_shell",
+    } as LocalShellTool,
+  };
+
+  return shellTool;
+}

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

@@ -0,0 +1,13 @@
+import { expectTypeOf, it, describe } from "vitest";
+import { tools } from "../index.js";
+
+describe("OpenAI Local Shell Tool Tests", () => {
+  it("localShell creates valid tool definitions", () => {
+    tools.localShell({
+      execute: async (cmd) => {
+        expectTypeOf(cmd.command).toEqualTypeOf<string[]>();
+        return "output";
+      },
+    });
+  });
+});

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

@@ -0,0 +1,15 @@
+import { expect, it, describe } from "vitest";
+import { tools } from "../index.js";
+
+describe("OpenAI Local Shell Tool Tests", () => {
+  it("localShell creates valid tool definitions", () => {
+    const shell = tools.localShell({
+      execute: async () => "output",
+    });
+
+    expect(shell.name).toBe("local_shell");
+    expect(shell.extras?.providerToolDefinition).toMatchObject({
+      type: "local_shell",
+    });
+  });
+});