@langchain/openai 1.1.2 → 1.2.0-dev-1765431816670

package/dist/tools/localShell.cjs

@@ -0,0 +1,145 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const __langchain_core_tools = require_rolldown_runtime.__toESM(require("@langchain/core/tools"));
+const zod_v4 = require_rolldown_runtime.__toESM(require("zod/v4"));
+
+//#region src/tools/localShell.ts
+const LocalShellExecActionSchema = zod_v4.z.object({
+	type: zod_v4.z.literal("exec"),
+	command: zod_v4.z.array(zod_v4.z.string()),
+	env: zod_v4.z.record(zod_v4.z.string(), zod_v4.z.string()).optional(),
+	working_directory: zod_v4.z.string().optional(),
+	timeout_ms: zod_v4.z.number().optional(),
+	user: zod_v4.z.string().optional()
+});
+const LocalShellActionSchema = zod_v4.z.discriminatedUnion("type", [LocalShellExecActionSchema]);
+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
+*/
+function localShell(options) {
+	const shellTool = (0, __langchain_core_tools.tool)(options.execute, {
+		name: TOOL_NAME,
+		description: "Execute shell commands locally on the machine. Commands are provided as argv tokens.",
+		schema: LocalShellActionSchema
+	});
+	shellTool.extras = {
+		...shellTool.extras ?? {},
+		providerToolDefinition: { type: "local_shell" }
+	};
+	return shellTool;
+}
+
+//#endregion
+exports.localShell = localShell;
+//# sourceMappingURL=localShell.cjs.map

package/dist/tools/localShell.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"localShell.cjs","names":["z","options: LocalShellOptions"],"sources":["../../src/tools/localShell.ts"],"sourcesContent":["import { z } from \"zod/v4\";\nimport { OpenAI as OpenAIClient } from \"openai\";\nimport { tool, type DynamicStructuredTool } from \"@langchain/core/tools\";\n\n/**\n * Re-export action type from OpenAI SDK for convenience.\n * The action contains command details like argv tokens, environment variables,\n * working directory, timeout, and user.\n */\nexport type LocalShellAction =\n  OpenAIClient.Responses.ResponseOutputItem.LocalShellCall.Action;\n\n// Zod schema for local shell exec action\nexport const LocalShellExecActionSchema = z.object({\n  type: z.literal(\"exec\"),\n  command: z.array(z.string()),\n  env: z.record(z.string(), z.string()).optional(),\n  working_directory: z.string().optional(),\n  timeout_ms: z.number().optional(),\n  user: z.string().optional(),\n});\n\n// Schema for all local shell actions (currently only exec)\nexport const LocalShellActionSchema = z.discriminatedUnion(\"type\", [\n  LocalShellExecActionSchema,\n]);\n\n/**\n * Options for the Local Shell tool.\n */\nexport interface LocalShellOptions {\n  /**\n   * Optional execute function that handles shell command execution.\n   * This function receives the action input and should return the command output\n   * (stdout + stderr combined).\n   *\n   * If not provided, you'll need to handle action execution manually by\n   * checking `local_shell_call` outputs in the response.\n   *\n   * @example\n   * ```typescript\n   * execute: async (action) => {\n   *   const result = await exec(action.command.join(' '), {\n   *     cwd: action.working_directory,\n   *     env: { ...process.env, ...action.env },\n   *     timeout: action.timeout_ms,\n   *   });\n   *   return result.stdout + result.stderr;\n   * }\n   * ```\n   */\n  execute: (action: LocalShellAction) => string | Promise<string>;\n}\n\n/**\n * OpenAI Local Shell tool type for the Responses API.\n */\nexport type LocalShellTool = OpenAIClient.Responses.Tool.LocalShell;\n\nconst TOOL_NAME = \"local_shell\";\n\n/**\n * Creates a Local Shell tool that allows models to run shell commands locally\n * on a machine you provide. Commands are executed inside your own runtime—\n * the API only returns the instructions, but does not execute them on OpenAI infrastructure.\n *\n * **Important**: The local shell tool is designed to work with\n * [Codex CLI](https://github.com/openai/codex) and the `codex-mini-latest` model.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`local_shell_call` with `exec` action)\n * 2. Your code executes the command locally\n * 3. You return the output back to the model\n * 4. Repeat until the task is complete\n *\n * **Security Warning**: Running arbitrary shell commands can be dangerous.\n * Always sandbox execution or add strict allow/deny-lists before forwarding\n * a command to the system shell.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-local-shell | OpenAI Local Shell Documentation}\n *\n * @param options - Optional configuration for the Local Shell tool\n * @returns A Local Shell tool that can be passed to `bindTools`\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n * import { exec } from \"child_process\";\n * import { promisify } from \"util\";\n *\n * const execAsync = promisify(exec);\n * const model = new ChatOpenAI({ model: \"codex-mini-latest\" });\n *\n * // With execute callback for automatic command handling\n * const shell = tools.localShell({\n *   execute: async (action) => {\n *     const { command, env, working_directory, timeout_ms } = action;\n *     const result = await execAsync(command.join(' '), {\n *       cwd: working_directory ?? process.cwd(),\n *       env: { ...process.env, ...env },\n *       timeout: timeout_ms ?? undefined,\n *     });\n *     return result.stdout + result.stderr;\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shell]);\n * const response = await llmWithShell.invoke(\n *   \"List files in the current directory\"\n * );\n * ```\n *\n * @example\n * ```typescript\n * // Without execute callback (manual handling)\n * const shell = tools.localShell();\n *\n * const response = await model.invoke(\"List files\", {\n *   tools: [shell],\n * });\n *\n * // Access the shell call from the response\n * const shellCall = response.additional_kwargs.tool_outputs?.find(\n *   (output) => output.type === \"local_shell_call\"\n * );\n * if (shellCall) {\n *   console.log(\"Command to execute:\", shellCall.action.command);\n *   // Execute the command manually, then send back the output\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Full shell loop example\n * async function shellLoop(model, task) {\n *   let response = await model.invoke(task, {\n *     tools: [tools.localShell()],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"local_shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute command (with proper sandboxing!)\n *     const output = await executeCommand(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"local_shell_call_output\",\n *         id: shellCall.call_id,\n *         output: output,\n *       },\n *     ], {\n *       tools: [tools.localShell()],\n *     });\n *   }\n *\n *   return response;\n * }\n * ```\n *\n * @remarks\n * - Only available through the Responses API (not Chat Completions)\n * - Designed for use with `codex-mini-latest` model\n * - Commands are provided as argv tokens in `action.command`\n * - Action includes: `command`, `env`, `working_directory`, `timeout_ms`, `user`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n */\nexport function localShell(options: LocalShellOptions) {\n  const shellTool = tool(options.execute, {\n    name: TOOL_NAME,\n    description:\n      \"Execute shell commands locally on the machine. Commands are provided as argv tokens.\",\n    schema: LocalShellActionSchema,\n  });\n\n  shellTool.extras = {\n    ...(shellTool.extras ?? {}),\n    providerToolDefinition: {\n      type: \"local_shell\",\n    } satisfies LocalShellTool,\n  };\n\n  return shellTool as DynamicStructuredTool<\n    typeof LocalShellActionSchema,\n    LocalShellAction,\n    unknown,\n    string\n  >;\n}\n"],"mappings":";;;;;AAaA,MAAa,6BAA6BA,SAAE,OAAO;CACjD,MAAMA,SAAE,QAAQ,OAAO;CACvB,SAASA,SAAE,MAAMA,SAAE,QAAQ,CAAC;CAC5B,KAAKA,SAAE,OAAOA,SAAE,QAAQ,EAAEA,SAAE,QAAQ,CAAC,CAAC,UAAU;CAChD,mBAAmBA,SAAE,QAAQ,CAAC,UAAU;CACxC,YAAYA,SAAE,QAAQ,CAAC,UAAU;CACjC,MAAMA,SAAE,QAAQ,CAAC,UAAU;AAC5B,EAAC;AAGF,MAAa,yBAAyBA,SAAE,mBAAmB,QAAQ,CACjE,0BACD,EAAC;AAkCF,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoHlB,SAAgB,WAAWC,SAA4B;CACrD,MAAM,6CAAiB,QAAQ,SAAS;EACtC,MAAM;EACN,aACE;EACF,QAAQ;CACT,EAAC;CAEF,UAAU,SAAS;EACjB,GAAI,UAAU,UAAU,CAAE;EAC1B,wBAAwB,EACtB,MAAM,cACP;CACF;AAED,QAAO;AAMR"}

package/dist/tools/localShell.d.cts

@@ -0,0 +1,167 @@
+import { OpenAI as OpenAI$1 } from "openai";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod/v4";
+
+//#region src/tools/localShell.d.ts
+
+/**
+ * Re-export action type from OpenAI SDK for convenience.
+ * The action contains command details like argv tokens, environment variables,
+ * working directory, timeout, and user.
+ */
+type LocalShellAction = OpenAI$1.Responses.ResponseOutputItem.LocalShellCall.Action;
+/**
+ * Options for the Local Shell tool.
+ */
+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.
+ */
+type LocalShellTool = OpenAI$1.Responses.Tool.LocalShell;
+/**
+ * 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
+ */
+declare function localShell(options: LocalShellOptions): DynamicStructuredTool<z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"exec">;
+  command: z.ZodArray<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  working_directory: z.ZodOptional<z.ZodString>;
+  timeout_ms: z.ZodOptional<z.ZodNumber>;
+  user: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>, OpenAI$1.Responses.ResponseOutputItem.LocalShellCall.Action, unknown, string>;
+//#endregion
+export { LocalShellAction, LocalShellOptions, LocalShellTool, localShell };
+//# sourceMappingURL=localShell.d.cts.map

package/dist/tools/localShell.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localShell.d.cts","names":["z","OpenAI","OpenAIClient","DynamicStructuredTool","LocalShellAction","Responses","ResponseOutputItem","LocalShellCall","Action","LocalShellExecActionSchema","ZodLiteral","ZodString","ZodArray","ZodRecord","ZodOptional","ZodNumber","core","$strip","ZodObject","LocalShellActionSchema","ZodDiscriminatedUnion","LocalShellOptions","Promise","LocalShellTool","Tool","LocalShell","localShell"],"sources":["../../src/tools/localShell.d.ts"],"sourcesContent":["import { z } from \"zod/v4\";\nimport { OpenAI as OpenAIClient } from \"openai\";\nimport { type DynamicStructuredTool } from \"@langchain/core/tools\";\n/**\n * Re-export action type from OpenAI SDK for convenience.\n * The action contains command details like argv tokens, environment variables,\n * working directory, timeout, and user.\n */\nexport type LocalShellAction = OpenAIClient.Responses.ResponseOutputItem.LocalShellCall.Action;\nexport declare const LocalShellExecActionSchema: z.ZodObject<{\n    type: z.ZodLiteral<\"exec\">;\n    command: z.ZodArray<z.ZodString>;\n    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;\n    working_directory: z.ZodOptional<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    user: z.ZodOptional<z.ZodString>;\n}, z.core.$strip>;\nexport declare const LocalShellActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{\n    type: z.ZodLiteral<\"exec\">;\n    command: z.ZodArray<z.ZodString>;\n    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;\n    working_directory: z.ZodOptional<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    user: z.ZodOptional<z.ZodString>;\n}, z.core.$strip>]>;\n/**\n * Options for the Local Shell tool.\n */\nexport interface LocalShellOptions {\n    /**\n     * Optional execute function that handles shell command execution.\n     * This function receives the action input and should return the command output\n     * (stdout + stderr combined).\n     *\n     * If not provided, you'll need to handle action execution manually by\n     * checking `local_shell_call` outputs in the response.\n     *\n     * @example\n     * ```typescript\n     * execute: async (action) => {\n     *   const result = await exec(action.command.join(' '), {\n     *     cwd: action.working_directory,\n     *     env: { ...process.env, ...action.env },\n     *     timeout: action.timeout_ms,\n     *   });\n     *   return result.stdout + result.stderr;\n     * }\n     * ```\n     */\n    execute: (action: LocalShellAction) => string | Promise<string>;\n}\n/**\n * OpenAI Local Shell tool type for the Responses API.\n */\nexport type LocalShellTool = OpenAIClient.Responses.Tool.LocalShell;\n/**\n * Creates a Local Shell tool that allows models to run shell commands locally\n * on a machine you provide. Commands are executed inside your own runtime—\n * the API only returns the instructions, but does not execute them on OpenAI infrastructure.\n *\n * **Important**: The local shell tool is designed to work with\n * [Codex CLI](https://github.com/openai/codex) and the `codex-mini-latest` model.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`local_shell_call` with `exec` action)\n * 2. Your code executes the command locally\n * 3. You return the output back to the model\n * 4. Repeat until the task is complete\n *\n * **Security Warning**: Running arbitrary shell commands can be dangerous.\n * Always sandbox execution or add strict allow/deny-lists before forwarding\n * a command to the system shell.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-local-shell | OpenAI Local Shell Documentation}\n *\n * @param options - Optional configuration for the Local Shell tool\n * @returns A Local Shell tool that can be passed to `bindTools`\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n * import { exec } from \"child_process\";\n * import { promisify } from \"util\";\n *\n * const execAsync = promisify(exec);\n * const model = new ChatOpenAI({ model: \"codex-mini-latest\" });\n *\n * // With execute callback for automatic command handling\n * const shell = tools.localShell({\n *   execute: async (action) => {\n *     const { command, env, working_directory, timeout_ms } = action;\n *     const result = await execAsync(command.join(' '), {\n *       cwd: working_directory ?? process.cwd(),\n *       env: { ...process.env, ...env },\n *       timeout: timeout_ms ?? undefined,\n *     });\n *     return result.stdout + result.stderr;\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shell]);\n * const response = await llmWithShell.invoke(\n *   \"List files in the current directory\"\n * );\n * ```\n *\n * @example\n * ```typescript\n * // Without execute callback (manual handling)\n * const shell = tools.localShell();\n *\n * const response = await model.invoke(\"List files\", {\n *   tools: [shell],\n * });\n *\n * // Access the shell call from the response\n * const shellCall = response.additional_kwargs.tool_outputs?.find(\n *   (output) => output.type === \"local_shell_call\"\n * );\n * if (shellCall) {\n *   console.log(\"Command to execute:\", shellCall.action.command);\n *   // Execute the command manually, then send back the output\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Full shell loop example\n * async function shellLoop(model, task) {\n *   let response = await model.invoke(task, {\n *     tools: [tools.localShell()],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"local_shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute command (with proper sandboxing!)\n *     const output = await executeCommand(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"local_shell_call_output\",\n *         id: shellCall.call_id,\n *         output: output,\n *       },\n *     ], {\n *       tools: [tools.localShell()],\n *     });\n *   }\n *\n *   return response;\n * }\n * ```\n *\n * @remarks\n * - Only available through the Responses API (not Chat Completions)\n * - Designed for use with `codex-mini-latest` model\n * - Commands are provided as argv tokens in `action.command`\n * - Action includes: `command`, `env`, `working_directory`, `timeout_ms`, `user`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n */\nexport declare function localShell(options: LocalShellOptions): DynamicStructuredTool<z.ZodDiscriminatedUnion<[z.ZodObject<{\n    type: z.ZodLiteral<\"exec\">;\n    command: z.ZodArray<z.ZodString>;\n    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;\n    working_directory: z.ZodOptional<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    user: z.ZodOptional<z.ZodString>;\n}, z.core.$strip>]>, OpenAIClient.Responses.ResponseOutputItem.LocalShellCall.Action, unknown, string>;\n//# sourceMappingURL=localShell.d.ts.map"],"mappings":";;;;;;;;AAQA;AAoBA;AA0BA;AAmHwB0B,KAjKZtB,gBAAAA,GAAmBF,QAAAA,CAAaG,SAAAA,CAAUC,kBAAAA,CAAmBC,cAAAA,CAAeC,MAiKtD;;;;AAAmD,UA7IpEa,iBAAAA,CA6IoE;;;;;;;;;;;;;;;;;;;;;oBAxH/DjB,8BAA8BkB;;;;;KAKxCC,cAAAA,GAAiBrB,QAAAA,CAAaG,SAAAA,CAAUmB,IAAAA,CAAKC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmHjCC,UAAAA,UAAoBL,oBAAoBlB,sBAAsBH,CAAAA,CAAEoB,uBAAuBpB,CAAAA,CAAEkB;QACvGlB,CAAAA,CAAEU;WACCV,CAAAA,CAAEY,SAASZ,CAAAA,CAAEW;OACjBX,CAAAA,CAAEc,YAAYd,CAAAA,CAAEa,UAAUb,CAAAA,CAAEW,WAAWX,CAAAA,CAAEW;qBAC3BX,CAAAA,CAAEc,YAAYd,CAAAA,CAAEW;cACvBX,CAAAA,CAAEc,YAAYd,CAAAA,CAAEe;QACtBf,CAAAA,CAAEc,YAAYd,CAAAA,CAAEW;GACvBX,CAAAA,CAAEgB,IAAAA,CAAKC,WAAWf,QAAAA,CAAaG,SAAAA,CAAUC,kBAAAA,CAAmBC,cAAAA,CAAeC"}

package/dist/tools/localShell.d.ts

@@ -0,0 +1,167 @@
+import { OpenAI as OpenAI$1 } from "openai";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod/v4";
+
+//#region src/tools/localShell.d.ts
+
+/**
+ * Re-export action type from OpenAI SDK for convenience.
+ * The action contains command details like argv tokens, environment variables,
+ * working directory, timeout, and user.
+ */
+type LocalShellAction = OpenAI$1.Responses.ResponseOutputItem.LocalShellCall.Action;
+/**
+ * Options for the Local Shell tool.
+ */
+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.
+ */
+type LocalShellTool = OpenAI$1.Responses.Tool.LocalShell;
+/**
+ * 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
+ */
+declare function localShell(options: LocalShellOptions): DynamicStructuredTool<z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"exec">;
+  command: z.ZodArray<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  working_directory: z.ZodOptional<z.ZodString>;
+  timeout_ms: z.ZodOptional<z.ZodNumber>;
+  user: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>, OpenAI$1.Responses.ResponseOutputItem.LocalShellCall.Action, unknown, string>;
+//#endregion
+export { LocalShellAction, LocalShellOptions, LocalShellTool, localShell };
+//# sourceMappingURL=localShell.d.ts.map

package/dist/tools/localShell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localShell.d.ts","names":["z","OpenAI","OpenAIClient","DynamicStructuredTool","LocalShellAction","Responses","ResponseOutputItem","LocalShellCall","Action","LocalShellExecActionSchema","ZodLiteral","ZodString","ZodArray","ZodRecord","ZodOptional","ZodNumber","core","$strip","ZodObject","LocalShellActionSchema","ZodDiscriminatedUnion","LocalShellOptions","Promise","LocalShellTool","Tool","LocalShell","localShell"],"sources":["../../src/tools/localShell.d.ts"],"sourcesContent":["import { z } from \"zod/v4\";\nimport { OpenAI as OpenAIClient } from \"openai\";\nimport { type DynamicStructuredTool } from \"@langchain/core/tools\";\n/**\n * Re-export action type from OpenAI SDK for convenience.\n * The action contains command details like argv tokens, environment variables,\n * working directory, timeout, and user.\n */\nexport type LocalShellAction = OpenAIClient.Responses.ResponseOutputItem.LocalShellCall.Action;\nexport declare const LocalShellExecActionSchema: z.ZodObject<{\n    type: z.ZodLiteral<\"exec\">;\n    command: z.ZodArray<z.ZodString>;\n    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;\n    working_directory: z.ZodOptional<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    user: z.ZodOptional<z.ZodString>;\n}, z.core.$strip>;\nexport declare const LocalShellActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{\n    type: z.ZodLiteral<\"exec\">;\n    command: z.ZodArray<z.ZodString>;\n    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;\n    working_directory: z.ZodOptional<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    user: z.ZodOptional<z.ZodString>;\n}, z.core.$strip>]>;\n/**\n * Options for the Local Shell tool.\n */\nexport interface LocalShellOptions {\n    /**\n     * Optional execute function that handles shell command execution.\n     * This function receives the action input and should return the command output\n     * (stdout + stderr combined).\n     *\n     * If not provided, you'll need to handle action execution manually by\n     * checking `local_shell_call` outputs in the response.\n     *\n     * @example\n     * ```typescript\n     * execute: async (action) => {\n     *   const result = await exec(action.command.join(' '), {\n     *     cwd: action.working_directory,\n     *     env: { ...process.env, ...action.env },\n     *     timeout: action.timeout_ms,\n     *   });\n     *   return result.stdout + result.stderr;\n     * }\n     * ```\n     */\n    execute: (action: LocalShellAction) => string | Promise<string>;\n}\n/**\n * OpenAI Local Shell tool type for the Responses API.\n */\nexport type LocalShellTool = OpenAIClient.Responses.Tool.LocalShell;\n/**\n * Creates a Local Shell tool that allows models to run shell commands locally\n * on a machine you provide. Commands are executed inside your own runtime—\n * the API only returns the instructions, but does not execute them on OpenAI infrastructure.\n *\n * **Important**: The local shell tool is designed to work with\n * [Codex CLI](https://github.com/openai/codex) and the `codex-mini-latest` model.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`local_shell_call` with `exec` action)\n * 2. Your code executes the command locally\n * 3. You return the output back to the model\n * 4. Repeat until the task is complete\n *\n * **Security Warning**: Running arbitrary shell commands can be dangerous.\n * Always sandbox execution or add strict allow/deny-lists before forwarding\n * a command to the system shell.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-local-shell | OpenAI Local Shell Documentation}\n *\n * @param options - Optional configuration for the Local Shell tool\n * @returns A Local Shell tool that can be passed to `bindTools`\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n * import { exec } from \"child_process\";\n * import { promisify } from \"util\";\n *\n * const execAsync = promisify(exec);\n * const model = new ChatOpenAI({ model: \"codex-mini-latest\" });\n *\n * // With execute callback for automatic command handling\n * const shell = tools.localShell({\n *   execute: async (action) => {\n *     const { command, env, working_directory, timeout_ms } = action;\n *     const result = await execAsync(command.join(' '), {\n *       cwd: working_directory ?? process.cwd(),\n *       env: { ...process.env, ...env },\n *       timeout: timeout_ms ?? undefined,\n *     });\n *     return result.stdout + result.stderr;\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shell]);\n * const response = await llmWithShell.invoke(\n *   \"List files in the current directory\"\n * );\n * ```\n *\n * @example\n * ```typescript\n * // Without execute callback (manual handling)\n * const shell = tools.localShell();\n *\n * const response = await model.invoke(\"List files\", {\n *   tools: [shell],\n * });\n *\n * // Access the shell call from the response\n * const shellCall = response.additional_kwargs.tool_outputs?.find(\n *   (output) => output.type === \"local_shell_call\"\n * );\n * if (shellCall) {\n *   console.log(\"Command to execute:\", shellCall.action.command);\n *   // Execute the command manually, then send back the output\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Full shell loop example\n * async function shellLoop(model, task) {\n *   let response = await model.invoke(task, {\n *     tools: [tools.localShell()],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"local_shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute command (with proper sandboxing!)\n *     const output = await executeCommand(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"local_shell_call_output\",\n *         id: shellCall.call_id,\n *         output: output,\n *       },\n *     ], {\n *       tools: [tools.localShell()],\n *     });\n *   }\n *\n *   return response;\n * }\n * ```\n *\n * @remarks\n * - Only available through the Responses API (not Chat Completions)\n * - Designed for use with `codex-mini-latest` model\n * - Commands are provided as argv tokens in `action.command`\n * - Action includes: `command`, `env`, `working_directory`, `timeout_ms`, `user`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n */\nexport declare function localShell(options: LocalShellOptions): DynamicStructuredTool<z.ZodDiscriminatedUnion<[z.ZodObject<{\n    type: z.ZodLiteral<\"exec\">;\n    command: z.ZodArray<z.ZodString>;\n    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;\n    working_directory: z.ZodOptional<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    user: z.ZodOptional<z.ZodString>;\n}, z.core.$strip>]>, OpenAIClient.Responses.ResponseOutputItem.LocalShellCall.Action, unknown, string>;\n//# sourceMappingURL=localShell.d.ts.map"],"mappings":";;;;;;;;AAQA;AAoBA;AA0BA;AAmHwB0B,KAjKZtB,gBAAAA,GAAmBF,QAAAA,CAAaG,SAAAA,CAAUC,kBAAAA,CAAmBC,cAAAA,CAAeC,MAiKtD;;;;AAAmD,UA7IpEa,iBAAAA,CA6IoE;;;;;;;;;;;;;;;;;;;;;oBAxH/DjB,8BAA8BkB;;;;;KAKxCC,cAAAA,GAAiBrB,QAAAA,CAAaG,SAAAA,CAAUmB,IAAAA,CAAKC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmHjCC,UAAAA,UAAoBL,oBAAoBlB,sBAAsBH,CAAAA,CAAEoB,uBAAuBpB,CAAAA,CAAEkB;QACvGlB,CAAAA,CAAEU;WACCV,CAAAA,CAAEY,SAASZ,CAAAA,CAAEW;OACjBX,CAAAA,CAAEc,YAAYd,CAAAA,CAAEa,UAAUb,CAAAA,CAAEW,WAAWX,CAAAA,CAAEW;qBAC3BX,CAAAA,CAAEc,YAAYd,CAAAA,CAAEW;cACvBX,CAAAA,CAAEc,YAAYd,CAAAA,CAAEe;QACtBf,CAAAA,CAAEc,YAAYd,CAAAA,CAAEW;GACvBX,CAAAA,CAAEgB,IAAAA,CAAKC,WAAWf,QAAAA,CAAaG,SAAAA,CAAUC,kBAAAA,CAAmBC,cAAAA,CAAeC"}

package/dist/tools/localShell.js

@@ -0,0 +1,144 @@
+import { tool } from "@langchain/core/tools";
+import { z } from "zod/v4";
+
+//#region src/tools/localShell.ts
+const LocalShellExecActionSchema = z.object({
+	type: z.literal("exec"),
+	command: z.array(z.string()),
+	env: z.record(z.string(), z.string()).optional(),
+	working_directory: z.string().optional(),
+	timeout_ms: z.number().optional(),
+	user: z.string().optional()
+});
+const LocalShellActionSchema = z.discriminatedUnion("type", [LocalShellExecActionSchema]);
+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
+*/
+function localShell(options) {
+	const shellTool = tool(options.execute, {
+		name: TOOL_NAME,
+		description: "Execute shell commands locally on the machine. Commands are provided as argv tokens.",
+		schema: LocalShellActionSchema
+	});
+	shellTool.extras = {
+		...shellTool.extras ?? {},
+		providerToolDefinition: { type: "local_shell" }
+	};
+	return shellTool;
+}
+
+//#endregion
+export { localShell };
+//# sourceMappingURL=localShell.js.map