@langchain/openai 1.2.6 → 1.2.8-dev-1771365493298

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

@@ -1 +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","ZodUnion","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.ZodUnion<readonly [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.ZodUnion<readonly [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, 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,mBAAmBpB,CAAAA,CAAEkB;QACnGlB,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"}
+{"version":3,"file":"localShell.d.ts","names":[],"sources":["../../src/tools/localShell.ts"],"mappings":";;;;;;;AASA;;;KAAY,gBAAA,GACV,QAAA,CAAa,SAAA,CAAU,kBAAA,CAAmB,cAAA,CAAe,MAAA;;AA6C3D;;UA3BiB,iBAAA;EA2BkD;;;;;;;AAsHnE;;;;;;;;;;;;;EA5HE,OAAA,GAAU,MAAA,EAAQ,gBAAA,cAA8B,OAAA;AAAA;;;;KAMtC,cAAA,GAAiB,QAAA,CAAa,SAAA,CAAU,IAAA,CAAK,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsHzC,UAAA,CAAW,OAAA,EAAS,iBAAA,GAAiB,qBAAA,CAAA,CAAA,CAAA,QAAA,WAAA,CAAA,CAAA,SAAA"}

package/dist/tools/localShell.js.map

@@ -1 +1 @@
-{"version":3,"file":"localShell.js","names":["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.union([LocalShellExecActionSchema]);\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,6BAA6B,EAAE,OAAO;CACjD,MAAM,EAAE,QAAQ,OAAO;CACvB,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;CAC5B,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAC,UAAU;CAChD,mBAAmB,EAAE,QAAQ,CAAC,UAAU;CACxC,YAAY,EAAE,QAAQ,CAAC,UAAU;CACjC,MAAM,EAAE,QAAQ,CAAC,UAAU;AAC5B,EAAC;AAGF,MAAa,yBAAyB,EAAE,MAAM,CAAC,0BAA2B,EAAC;AAkC3E,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoHlB,SAAgB,WAAWA,SAA4B;CACrD,MAAM,YAAY,KAAK,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"}
+{"version":3,"file":"localShell.js","names":[],"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.union([LocalShellExecActionSchema]);\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,6BAA6B,EAAE,OAAO;CACjD,MAAM,EAAE,QAAQ,OAAO;CACvB,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;CAC5B,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAC,UAAU;CAChD,mBAAmB,EAAE,QAAQ,CAAC,UAAU;CACxC,YAAY,EAAE,QAAQ,CAAC,UAAU;CACjC,MAAM,EAAE,QAAQ,CAAC,UAAU;CAC5B,CAAC;AAGF,MAAa,yBAAyB,EAAE,MAAM,CAAC,2BAA2B,CAAC;AAkC3E,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoHlB,SAAgB,WAAW,SAA4B;CACrD,MAAM,YAAY,KAAK,QAAQ,SAAS;EACtC,MAAM;EACN,aACE;EACF,QAAQ;EACT,CAAC;AAEF,WAAU,SAAS;EACjB,GAAI,UAAU,UAAU,EAAE;EAC1B,wBAAwB,EACtB,MAAM,eACP;EACF;AAED,QAAO"}

package/dist/tools/mcp.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.cjs","names":["filter: McpToolFilter","allowedTools: string[] | McpToolFilter | undefined","requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined","options: McpRemoteServerOptions | McpConnectorOptions","baseConfig: McpTool"],"sources":["../../src/tools/mcp.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId =\n  | \"connector_dropbox\"\n  | \"connector_gmail\"\n  | \"connector_googlecalendar\"\n  | \"connector_googledrive\"\n  | \"connector_microsoftteams\"\n  | \"connector_outlookcalendar\"\n  | \"connector_outlookemail\"\n  | \"connector_sharepoint\";\n\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n  /**\n   * List of allowed tool names.\n   */\n  toolNames?: string[];\n  /**\n   * Indicates whether or not a tool modifies data or is read-only.\n   * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n   */\n  readOnly?: boolean;\n}\n\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n  /**\n   * Tools that always require approval before execution.\n   */\n  always?: McpToolFilter;\n  /**\n   * Tools that never require approval.\n   */\n  never?: McpToolFilter;\n}\n\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n  /**\n   * A label for this MCP server, used to identify it in tool calls.\n   */\n  serverLabel: string;\n  /**\n   * List of allowed tool names or a filter object.\n   * Use this to limit which tools from the MCP server are available to the model.\n   */\n  allowedTools?: string[] | McpToolFilter;\n  /**\n   * An OAuth access token for authentication with the MCP server.\n   * Your application must handle the OAuth authorization flow and provide the token here.\n   */\n  authorization?: string;\n  /**\n   * Optional HTTP headers to send to the MCP server.\n   * Use for authentication or other purposes.\n   */\n  headers?: Record<string, string>;\n  /**\n   * Specify which of the MCP server's tools require approval before execution.\n   * - `\"always\"`: All tools require approval\n   * - `\"never\"`: No tools require approval\n   * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n   *\n   * @default \"always\" (approval required for all tools)\n   */\n  requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n  /**\n   * Optional description of the MCP server, used to provide more context to the model.\n   */\n  serverDescription?: string;\n}\n\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n  /**\n   * The URL for the MCP server.\n   * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n   */\n  serverUrl: string;\n}\n\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n  /**\n   * Identifier for the service connector.\n   * These are OpenAI-maintained MCP wrappers for popular services.\n   *\n   * Available connectors:\n   * - `connector_dropbox`: Dropbox file access\n   * - `connector_gmail`: Gmail email access\n   * - `connector_googlecalendar`: Google Calendar access\n   * - `connector_googledrive`: Google Drive file access\n   * - `connector_microsoftteams`: Microsoft Teams access\n   * - `connector_outlookcalendar`: Outlook Calendar access\n   * - `connector_outlookemail`: Outlook Email access\n   * - `connector_sharepoint`: SharePoint file access\n   */\n  connectorId: McpConnectorId;\n}\n\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n\n/**\n * Converts a McpToolFilter to the API format.\n */\nfunction convertToolFilter(\n  filter: McpToolFilter\n): OpenAIClient.Responses.Tool.Mcp.McpToolFilter {\n  return {\n    tool_names: filter.toolNames,\n    read_only: filter.readOnly,\n  };\n}\n\n/**\n * Converts allowed_tools option to API format.\n */\nfunction convertAllowedTools(\n  allowedTools: string[] | McpToolFilter | undefined\n): Array<string> | OpenAIClient.Responses.Tool.Mcp.McpToolFilter | undefined {\n  if (!allowedTools) return undefined;\n  if (Array.isArray(allowedTools)) return allowedTools;\n  return convertToolFilter(allowedTools);\n}\n\n/**\n * Converts require_approval option to API format.\n */\nfunction convertRequireApproval(\n  requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined\n):\n  | OpenAIClient.Responses.Tool.Mcp.McpToolApprovalFilter\n  | \"always\"\n  | \"never\"\n  | undefined {\n  if (!requireApproval) return undefined;\n  if (typeof requireApproval === \"string\") return requireApproval;\n  return {\n    always: requireApproval.always\n      ? convertToolFilter(requireApproval.always)\n      : undefined,\n    never: requireApproval.never\n      ? convertToolFilter(requireApproval.never)\n      : undefined,\n  };\n}\n\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n *    the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n *    Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverDescription: \"A D&D MCP server for dice rolling\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"google_calendar\",\n *     connectorId: \"connector_googlecalendar\",\n *     authorization: \"<oauth-access-token>\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     allowedTools: [\"roll\"],  // Only allow the \"roll\" tool\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"deepwiki\",\n *     serverUrl: \"https://mcp.deepwiki.com/mcp\",\n *     requireApproval: {\n *       never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n *       // All other tools will require approval\n *     },\n *   })],\n * });\n * ```\n */\nexport function mcp(options: McpRemoteServerOptions): ServerTool;\nexport function mcp(options: McpConnectorOptions): ServerTool;\nexport function mcp(\n  options: McpRemoteServerOptions | McpConnectorOptions\n): ServerTool {\n  const baseConfig: McpTool = {\n    type: \"mcp\",\n    server_label: options.serverLabel,\n    allowed_tools: convertAllowedTools(options.allowedTools),\n    authorization: options.authorization,\n    headers: options.headers,\n    require_approval: convertRequireApproval(options.requireApproval),\n    server_description: options.serverDescription,\n  };\n\n  if (\"serverUrl\" in options) {\n    return {\n      ...baseConfig,\n      server_url: options.serverUrl,\n    } satisfies McpTool;\n  }\n\n  return {\n    ...baseConfig,\n    connector_id: options.connectorId,\n  } satisfies McpTool;\n}\n"],"mappings":";;;;;AA4HA,SAAS,kBACPA,QAC+C;AAC/C,QAAO;EACL,YAAY,OAAO;EACnB,WAAW,OAAO;CACnB;AACF;;;;AAKD,SAAS,oBACPC,cAC2E;AAC3E,KAAI,CAAC,aAAc,QAAO;AAC1B,KAAI,MAAM,QAAQ,aAAa,CAAE,QAAO;AACxC,QAAO,kBAAkB,aAAa;AACvC;;;;AAKD,SAAS,uBACPC,iBAKY;AACZ,KAAI,CAAC,gBAAiB,QAAO;AAC7B,KAAI,OAAO,oBAAoB,SAAU,QAAO;AAChD,QAAO;EACL,QAAQ,gBAAgB,SACpB,kBAAkB,gBAAgB,OAAO,GACzC;EACJ,OAAO,gBAAgB,QACnB,kBAAkB,gBAAgB,MAAM,GACxC;CACL;AACF;AAoED,SAAgB,IACdC,SACY;CACZ,MAAMC,aAAsB;EAC1B,MAAM;EACN,cAAc,QAAQ;EACtB,eAAe,oBAAoB,QAAQ,aAAa;EACxD,eAAe,QAAQ;EACvB,SAAS,QAAQ;EACjB,kBAAkB,uBAAuB,QAAQ,gBAAgB;EACjE,oBAAoB,QAAQ;CAC7B;AAED,KAAI,eAAe,QACjB,QAAO;EACL,GAAG;EACH,YAAY,QAAQ;CACrB;AAGH,QAAO;EACL,GAAG;EACH,cAAc,QAAQ;CACvB;AACF"}
+{"version":3,"file":"mcp.cjs","names":[],"sources":["../../src/tools/mcp.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId =\n  | \"connector_dropbox\"\n  | \"connector_gmail\"\n  | \"connector_googlecalendar\"\n  | \"connector_googledrive\"\n  | \"connector_microsoftteams\"\n  | \"connector_outlookcalendar\"\n  | \"connector_outlookemail\"\n  | \"connector_sharepoint\";\n\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n  /**\n   * List of allowed tool names.\n   */\n  toolNames?: string[];\n  /**\n   * Indicates whether or not a tool modifies data or is read-only.\n   * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n   */\n  readOnly?: boolean;\n}\n\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n  /**\n   * Tools that always require approval before execution.\n   */\n  always?: McpToolFilter;\n  /**\n   * Tools that never require approval.\n   */\n  never?: McpToolFilter;\n}\n\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n  /**\n   * A label for this MCP server, used to identify it in tool calls.\n   */\n  serverLabel: string;\n  /**\n   * List of allowed tool names or a filter object.\n   * Use this to limit which tools from the MCP server are available to the model.\n   */\n  allowedTools?: string[] | McpToolFilter;\n  /**\n   * An OAuth access token for authentication with the MCP server.\n   * Your application must handle the OAuth authorization flow and provide the token here.\n   */\n  authorization?: string;\n  /**\n   * Optional HTTP headers to send to the MCP server.\n   * Use for authentication or other purposes.\n   */\n  headers?: Record<string, string>;\n  /**\n   * Specify which of the MCP server's tools require approval before execution.\n   * - `\"always\"`: All tools require approval\n   * - `\"never\"`: No tools require approval\n   * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n   *\n   * @default \"always\" (approval required for all tools)\n   */\n  requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n  /**\n   * Optional description of the MCP server, used to provide more context to the model.\n   */\n  serverDescription?: string;\n}\n\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n  /**\n   * The URL for the MCP server.\n   * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n   */\n  serverUrl: string;\n}\n\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n  /**\n   * Identifier for the service connector.\n   * These are OpenAI-maintained MCP wrappers for popular services.\n   *\n   * Available connectors:\n   * - `connector_dropbox`: Dropbox file access\n   * - `connector_gmail`: Gmail email access\n   * - `connector_googlecalendar`: Google Calendar access\n   * - `connector_googledrive`: Google Drive file access\n   * - `connector_microsoftteams`: Microsoft Teams access\n   * - `connector_outlookcalendar`: Outlook Calendar access\n   * - `connector_outlookemail`: Outlook Email access\n   * - `connector_sharepoint`: SharePoint file access\n   */\n  connectorId: McpConnectorId;\n}\n\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n\n/**\n * Converts a McpToolFilter to the API format.\n */\nfunction convertToolFilter(\n  filter: McpToolFilter\n): OpenAIClient.Responses.Tool.Mcp.McpToolFilter {\n  return {\n    tool_names: filter.toolNames,\n    read_only: filter.readOnly,\n  };\n}\n\n/**\n * Converts allowed_tools option to API format.\n */\nfunction convertAllowedTools(\n  allowedTools: string[] | McpToolFilter | undefined\n): Array<string> | OpenAIClient.Responses.Tool.Mcp.McpToolFilter | undefined {\n  if (!allowedTools) return undefined;\n  if (Array.isArray(allowedTools)) return allowedTools;\n  return convertToolFilter(allowedTools);\n}\n\n/**\n * Converts require_approval option to API format.\n */\nfunction convertRequireApproval(\n  requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined\n):\n  | OpenAIClient.Responses.Tool.Mcp.McpToolApprovalFilter\n  | \"always\"\n  | \"never\"\n  | undefined {\n  if (!requireApproval) return undefined;\n  if (typeof requireApproval === \"string\") return requireApproval;\n  return {\n    always: requireApproval.always\n      ? convertToolFilter(requireApproval.always)\n      : undefined,\n    never: requireApproval.never\n      ? convertToolFilter(requireApproval.never)\n      : undefined,\n  };\n}\n\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n *    the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n *    Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverDescription: \"A D&D MCP server for dice rolling\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"google_calendar\",\n *     connectorId: \"connector_googlecalendar\",\n *     authorization: \"<oauth-access-token>\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     allowedTools: [\"roll\"],  // Only allow the \"roll\" tool\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"deepwiki\",\n *     serverUrl: \"https://mcp.deepwiki.com/mcp\",\n *     requireApproval: {\n *       never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n *       // All other tools will require approval\n *     },\n *   })],\n * });\n * ```\n */\nexport function mcp(options: McpRemoteServerOptions): ServerTool;\nexport function mcp(options: McpConnectorOptions): ServerTool;\nexport function mcp(\n  options: McpRemoteServerOptions | McpConnectorOptions\n): ServerTool {\n  const baseConfig: McpTool = {\n    type: \"mcp\",\n    server_label: options.serverLabel,\n    allowed_tools: convertAllowedTools(options.allowedTools),\n    authorization: options.authorization,\n    headers: options.headers,\n    require_approval: convertRequireApproval(options.requireApproval),\n    server_description: options.serverDescription,\n  };\n\n  if (\"serverUrl\" in options) {\n    return {\n      ...baseConfig,\n      server_url: options.serverUrl,\n    } satisfies McpTool;\n  }\n\n  return {\n    ...baseConfig,\n    connector_id: options.connectorId,\n  } satisfies McpTool;\n}\n"],"mappings":";;;;;AA4HA,SAAS,kBACP,QAC+C;AAC/C,QAAO;EACL,YAAY,OAAO;EACnB,WAAW,OAAO;EACnB;;;;;AAMH,SAAS,oBACP,cAC2E;AAC3E,KAAI,CAAC,aAAc,QAAO;AAC1B,KAAI,MAAM,QAAQ,aAAa,CAAE,QAAO;AACxC,QAAO,kBAAkB,aAAa;;;;;AAMxC,SAAS,uBACP,iBAKY;AACZ,KAAI,CAAC,gBAAiB,QAAO;AAC7B,KAAI,OAAO,oBAAoB,SAAU,QAAO;AAChD,QAAO;EACL,QAAQ,gBAAgB,SACpB,kBAAkB,gBAAgB,OAAO,GACzC;EACJ,OAAO,gBAAgB,QACnB,kBAAkB,gBAAgB,MAAM,GACxC;EACL;;AAqEH,SAAgB,IACd,SACY;CACZ,MAAM,aAAsB;EAC1B,MAAM;EACN,cAAc,QAAQ;EACtB,eAAe,oBAAoB,QAAQ,aAAa;EACxD,eAAe,QAAQ;EACvB,SAAS,QAAQ;EACjB,kBAAkB,uBAAuB,QAAQ,gBAAgB;EACjE,oBAAoB,QAAQ;EAC7B;AAED,KAAI,eAAe,QACjB,QAAO;EACL,GAAG;EACH,YAAY,QAAQ;EACrB;AAGH,QAAO;EACL,GAAG;EACH,cAAc,QAAQ;EACvB"}

package/dist/tools/mcp.d.cts

@@ -2,7 +2,6 @@ import { OpenAI as OpenAI$1 } from "openai";
 import { ServerTool } from "@langchain/core/tools";
 
 //#region src/tools/mcp.d.ts
-
 /**
  * Available connector IDs for OpenAI's built-in service connectors.
  * These are OpenAI-maintained MCP wrappers for popular services.

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

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.cts","names":["OpenAI","OpenAIClient","ServerTool","McpConnectorId","McpToolFilter","McpApprovalFilter","McpBaseOptions","Record","McpRemoteServerOptions","McpConnectorOptions","McpTool","Responses","Tool","Mcp","mcp"],"sources":["../../src/tools/mcp.d.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId = \"connector_dropbox\" | \"connector_gmail\" | \"connector_googlecalendar\" | \"connector_googledrive\" | \"connector_microsoftteams\" | \"connector_outlookcalendar\" | \"connector_outlookemail\" | \"connector_sharepoint\";\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n    /**\n     * List of allowed tool names.\n     */\n    toolNames?: string[];\n    /**\n     * Indicates whether or not a tool modifies data or is read-only.\n     * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n     */\n    readOnly?: boolean;\n}\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n    /**\n     * Tools that always require approval before execution.\n     */\n    always?: McpToolFilter;\n    /**\n     * Tools that never require approval.\n     */\n    never?: McpToolFilter;\n}\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n    /**\n     * A label for this MCP server, used to identify it in tool calls.\n     */\n    serverLabel: string;\n    /**\n     * List of allowed tool names or a filter object.\n     * Use this to limit which tools from the MCP server are available to the model.\n     */\n    allowedTools?: string[] | McpToolFilter;\n    /**\n     * An OAuth access token for authentication with the MCP server.\n     * Your application must handle the OAuth authorization flow and provide the token here.\n     */\n    authorization?: string;\n    /**\n     * Optional HTTP headers to send to the MCP server.\n     * Use for authentication or other purposes.\n     */\n    headers?: Record<string, string>;\n    /**\n     * Specify which of the MCP server's tools require approval before execution.\n     * - `\"always\"`: All tools require approval\n     * - `\"never\"`: No tools require approval\n     * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n     *\n     * @default \"always\" (approval required for all tools)\n     */\n    requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n    /**\n     * Optional description of the MCP server, used to provide more context to the model.\n     */\n    serverDescription?: string;\n}\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n    /**\n     * The URL for the MCP server.\n     * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n     */\n    serverUrl: string;\n}\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n    /**\n     * Identifier for the service connector.\n     * These are OpenAI-maintained MCP wrappers for popular services.\n     *\n     * Available connectors:\n     * - `connector_dropbox`: Dropbox file access\n     * - `connector_gmail`: Gmail email access\n     * - `connector_googlecalendar`: Google Calendar access\n     * - `connector_googledrive`: Google Drive file access\n     * - `connector_microsoftteams`: Microsoft Teams access\n     * - `connector_outlookcalendar`: Outlook Calendar access\n     * - `connector_outlookemail`: Outlook Email access\n     * - `connector_sharepoint`: SharePoint file access\n     */\n    connectorId: McpConnectorId;\n}\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n *    the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n *    Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverDescription: \"A D&D MCP server for dice rolling\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"google_calendar\",\n *     connectorId: \"connector_googlecalendar\",\n *     authorization: \"<oauth-access-token>\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     allowedTools: [\"roll\"],  // Only allow the \"roll\" tool\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"deepwiki\",\n *     serverUrl: \"https://mcp.deepwiki.com/mcp\",\n *     requireApproval: {\n *       never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n *       // All other tools will require approval\n *     },\n *   })],\n * });\n * ```\n */\nexport declare function mcp(options: McpRemoteServerOptions): ServerTool;\nexport declare function mcp(options: McpConnectorOptions): ServerTool;\nexport {};\n//# sourceMappingURL=mcp.d.ts.map"],"mappings":";;;;;;;AAMA;AAIA;AAciBK,KAlBLF,cAAAA,GAkBsB,mBAIrBC,GAAAA,iBAIY,GAAA,0BAAA,GAAA,uBAAA,GAAA,0BAAA,GAAA,2BAAA,GAAA,wBAAA,GAAA,sBAAA;AACxB;;;AAgC0CC,UAvD1BD,aAAAA,CAuD0BC;EAAiB;AAS5D;AAUA;EAoBYK,SAAAA,CAAO,EAAA,MAAA,EAAA;EAiEKI;AACxB;;;;;;;;UAlJiBT,iBAAAA;;;;WAIJD;;;;UAIDA;;;;;UAKFE,cAAAA;;;;;;;;;4BASoBF;;;;;;;;;;YAUhBG;;;;;;;;;yCAS6BF;;;;;;;;;UAS1BG,sBAAAA,SAA+BF;;;;;;;;;;UAU/BG,mBAAAA,SAA4BH;;;;;;;;;;;;;;;eAe5BH;;;;;KAKLO,OAAAA,GAAUT,QAAAA,CAAaU,SAAAA,CAAUC,IAAAA,CAAKC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiE1BC,GAAAA,UAAaN,yBAAyBN;iBACtCY,GAAAA,UAAaL,sBAAsBP"}
+{"version":3,"file":"mcp.d.cts","names":[],"sources":["../../src/tools/mcp.ts"],"mappings":";;;;;;AAOA;;KAAY,cAAA;;;AAaZ;UAAiB,aAAA;;;;EAIf,SAAA;EAWgC;;;;EANhC,QAAA;AAAA;;;;UAMe,iBAAA;EAcO;;;EAVtB,MAAA,GAAS,aAAA;EAsC8B;;;EAlCvC,KAAA,GAAQ,aAAA;AAAA;;;;UAMA,cAAA;EA4BR;;;EAxBA,WAAA;EA4BiB;AAMnB;;;EA7BE,YAAA,cAA0B,aAAA;EAkCjB;AAMX;;;EAnCE,aAAA;EAmC2C;;;;EA9B3C,OAAA,GAAU,MAAA;EAmDA;;;;;;;;EA1CV,eAAA,wBAAuC,iBAAA;EA0CY;AA+GrD;;EArJE,iBAAA;AAAA;;;;UAMe,sBAAA,SAA+B,cAAA;EA+IgB;AAChE;;;EA3IE,SAAA;AAAA;;;;UAMe,mBAAA,SAA4B,cAAA;;;;;;;;;;;;;;;EAe3C,WAAA,EAAa,cAAA;AAAA;;;;KAMH,OAAA,GAAU,QAAA,CAAa,SAAA,CAAU,IAAA,CAAK,GAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+GlC,GAAA,CAAI,OAAA,EAAS,sBAAA,GAAyB,UAAA;AAAA,iBACtC,GAAA,CAAI,OAAA,EAAS,mBAAA,GAAsB,UAAA"}

package/dist/tools/mcp.d.ts

@@ -2,7 +2,6 @@ import { OpenAI as OpenAI$1 } from "openai";
 import { ServerTool } from "@langchain/core/tools";
 
 //#region src/tools/mcp.d.ts
-
 /**
  * Available connector IDs for OpenAI's built-in service connectors.
  * These are OpenAI-maintained MCP wrappers for popular services.

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

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","names":["OpenAI","OpenAIClient","ServerTool","McpConnectorId","McpToolFilter","McpApprovalFilter","McpBaseOptions","Record","McpRemoteServerOptions","McpConnectorOptions","McpTool","Responses","Tool","Mcp","mcp"],"sources":["../../src/tools/mcp.d.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId = \"connector_dropbox\" | \"connector_gmail\" | \"connector_googlecalendar\" | \"connector_googledrive\" | \"connector_microsoftteams\" | \"connector_outlookcalendar\" | \"connector_outlookemail\" | \"connector_sharepoint\";\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n    /**\n     * List of allowed tool names.\n     */\n    toolNames?: string[];\n    /**\n     * Indicates whether or not a tool modifies data or is read-only.\n     * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n     */\n    readOnly?: boolean;\n}\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n    /**\n     * Tools that always require approval before execution.\n     */\n    always?: McpToolFilter;\n    /**\n     * Tools that never require approval.\n     */\n    never?: McpToolFilter;\n}\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n    /**\n     * A label for this MCP server, used to identify it in tool calls.\n     */\n    serverLabel: string;\n    /**\n     * List of allowed tool names or a filter object.\n     * Use this to limit which tools from the MCP server are available to the model.\n     */\n    allowedTools?: string[] | McpToolFilter;\n    /**\n     * An OAuth access token for authentication with the MCP server.\n     * Your application must handle the OAuth authorization flow and provide the token here.\n     */\n    authorization?: string;\n    /**\n     * Optional HTTP headers to send to the MCP server.\n     * Use for authentication or other purposes.\n     */\n    headers?: Record<string, string>;\n    /**\n     * Specify which of the MCP server's tools require approval before execution.\n     * - `\"always\"`: All tools require approval\n     * - `\"never\"`: No tools require approval\n     * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n     *\n     * @default \"always\" (approval required for all tools)\n     */\n    requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n    /**\n     * Optional description of the MCP server, used to provide more context to the model.\n     */\n    serverDescription?: string;\n}\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n    /**\n     * The URL for the MCP server.\n     * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n     */\n    serverUrl: string;\n}\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n    /**\n     * Identifier for the service connector.\n     * These are OpenAI-maintained MCP wrappers for popular services.\n     *\n     * Available connectors:\n     * - `connector_dropbox`: Dropbox file access\n     * - `connector_gmail`: Gmail email access\n     * - `connector_googlecalendar`: Google Calendar access\n     * - `connector_googledrive`: Google Drive file access\n     * - `connector_microsoftteams`: Microsoft Teams access\n     * - `connector_outlookcalendar`: Outlook Calendar access\n     * - `connector_outlookemail`: Outlook Email access\n     * - `connector_sharepoint`: SharePoint file access\n     */\n    connectorId: McpConnectorId;\n}\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n *    the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n *    Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverDescription: \"A D&D MCP server for dice rolling\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"google_calendar\",\n *     connectorId: \"connector_googlecalendar\",\n *     authorization: \"<oauth-access-token>\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     allowedTools: [\"roll\"],  // Only allow the \"roll\" tool\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"deepwiki\",\n *     serverUrl: \"https://mcp.deepwiki.com/mcp\",\n *     requireApproval: {\n *       never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n *       // All other tools will require approval\n *     },\n *   })],\n * });\n * ```\n */\nexport declare function mcp(options: McpRemoteServerOptions): ServerTool;\nexport declare function mcp(options: McpConnectorOptions): ServerTool;\nexport {};\n//# sourceMappingURL=mcp.d.ts.map"],"mappings":";;;;;;;AAMA;AAIA;AAciBK,KAlBLF,cAAAA,GAkBsB,mBAIrBC,GAAAA,iBAIY,GAAA,0BAAA,GAAA,uBAAA,GAAA,0BAAA,GAAA,2BAAA,GAAA,wBAAA,GAAA,sBAAA;AACxB;;;AAgC0CC,UAvD1BD,aAAAA,CAuD0BC;EAAiB;AAS5D;AAUA;EAoBYK,SAAAA,CAAO,EAAA,MAAA,EAAA;EAiEKI;AACxB;;;;;;;;UAlJiBT,iBAAAA;;;;WAIJD;;;;UAIDA;;;;;UAKFE,cAAAA;;;;;;;;;4BASoBF;;;;;;;;;;YAUhBG;;;;;;;;;yCAS6BF;;;;;;;;;UAS1BG,sBAAAA,SAA+BF;;;;;;;;;;UAU/BG,mBAAAA,SAA4BH;;;;;;;;;;;;;;;eAe5BH;;;;;KAKLO,OAAAA,GAAUT,QAAAA,CAAaU,SAAAA,CAAUC,IAAAA,CAAKC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiE1BC,GAAAA,UAAaN,yBAAyBN;iBACtCY,GAAAA,UAAaL,sBAAsBP"}
+{"version":3,"file":"mcp.d.ts","names":[],"sources":["../../src/tools/mcp.ts"],"mappings":";;;;;;AAOA;;KAAY,cAAA;;;AAaZ;UAAiB,aAAA;;;;EAIf,SAAA;EAWgC;;;;EANhC,QAAA;AAAA;;;;UAMe,iBAAA;EAcO;;;EAVtB,MAAA,GAAS,aAAA;EAsC8B;;;EAlCvC,KAAA,GAAQ,aAAA;AAAA;;;;UAMA,cAAA;EA4BR;;;EAxBA,WAAA;EA4BiB;AAMnB;;;EA7BE,YAAA,cAA0B,aAAA;EAkCjB;AAMX;;;EAnCE,aAAA;EAmC2C;;;;EA9B3C,OAAA,GAAU,MAAA;EAmDA;;;;;;;;EA1CV,eAAA,wBAAuC,iBAAA;EA0CY;AA+GrD;;EArJE,iBAAA;AAAA;;;;UAMe,sBAAA,SAA+B,cAAA;EA+IgB;AAChE;;;EA3IE,SAAA;AAAA;;;;UAMe,mBAAA,SAA4B,cAAA;;;;;;;;;;;;;;;EAe3C,WAAA,EAAa,cAAA;AAAA;;;;KAMH,OAAA,GAAU,QAAA,CAAa,SAAA,CAAU,IAAA,CAAK,GAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+GlC,GAAA,CAAI,OAAA,EAAS,sBAAA,GAAyB,UAAA;AAAA,iBACtC,GAAA,CAAI,OAAA,EAAS,mBAAA,GAAsB,UAAA"}

package/dist/tools/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","names":["filter: McpToolFilter","allowedTools: string[] | McpToolFilter | undefined","requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined","options: McpRemoteServerOptions | McpConnectorOptions","baseConfig: McpTool"],"sources":["../../src/tools/mcp.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId =\n  | \"connector_dropbox\"\n  | \"connector_gmail\"\n  | \"connector_googlecalendar\"\n  | \"connector_googledrive\"\n  | \"connector_microsoftteams\"\n  | \"connector_outlookcalendar\"\n  | \"connector_outlookemail\"\n  | \"connector_sharepoint\";\n\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n  /**\n   * List of allowed tool names.\n   */\n  toolNames?: string[];\n  /**\n   * Indicates whether or not a tool modifies data or is read-only.\n   * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n   */\n  readOnly?: boolean;\n}\n\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n  /**\n   * Tools that always require approval before execution.\n   */\n  always?: McpToolFilter;\n  /**\n   * Tools that never require approval.\n   */\n  never?: McpToolFilter;\n}\n\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n  /**\n   * A label for this MCP server, used to identify it in tool calls.\n   */\n  serverLabel: string;\n  /**\n   * List of allowed tool names or a filter object.\n   * Use this to limit which tools from the MCP server are available to the model.\n   */\n  allowedTools?: string[] | McpToolFilter;\n  /**\n   * An OAuth access token for authentication with the MCP server.\n   * Your application must handle the OAuth authorization flow and provide the token here.\n   */\n  authorization?: string;\n  /**\n   * Optional HTTP headers to send to the MCP server.\n   * Use for authentication or other purposes.\n   */\n  headers?: Record<string, string>;\n  /**\n   * Specify which of the MCP server's tools require approval before execution.\n   * - `\"always\"`: All tools require approval\n   * - `\"never\"`: No tools require approval\n   * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n   *\n   * @default \"always\" (approval required for all tools)\n   */\n  requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n  /**\n   * Optional description of the MCP server, used to provide more context to the model.\n   */\n  serverDescription?: string;\n}\n\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n  /**\n   * The URL for the MCP server.\n   * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n   */\n  serverUrl: string;\n}\n\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n  /**\n   * Identifier for the service connector.\n   * These are OpenAI-maintained MCP wrappers for popular services.\n   *\n   * Available connectors:\n   * - `connector_dropbox`: Dropbox file access\n   * - `connector_gmail`: Gmail email access\n   * - `connector_googlecalendar`: Google Calendar access\n   * - `connector_googledrive`: Google Drive file access\n   * - `connector_microsoftteams`: Microsoft Teams access\n   * - `connector_outlookcalendar`: Outlook Calendar access\n   * - `connector_outlookemail`: Outlook Email access\n   * - `connector_sharepoint`: SharePoint file access\n   */\n  connectorId: McpConnectorId;\n}\n\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n\n/**\n * Converts a McpToolFilter to the API format.\n */\nfunction convertToolFilter(\n  filter: McpToolFilter\n): OpenAIClient.Responses.Tool.Mcp.McpToolFilter {\n  return {\n    tool_names: filter.toolNames,\n    read_only: filter.readOnly,\n  };\n}\n\n/**\n * Converts allowed_tools option to API format.\n */\nfunction convertAllowedTools(\n  allowedTools: string[] | McpToolFilter | undefined\n): Array<string> | OpenAIClient.Responses.Tool.Mcp.McpToolFilter | undefined {\n  if (!allowedTools) return undefined;\n  if (Array.isArray(allowedTools)) return allowedTools;\n  return convertToolFilter(allowedTools);\n}\n\n/**\n * Converts require_approval option to API format.\n */\nfunction convertRequireApproval(\n  requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined\n):\n  | OpenAIClient.Responses.Tool.Mcp.McpToolApprovalFilter\n  | \"always\"\n  | \"never\"\n  | undefined {\n  if (!requireApproval) return undefined;\n  if (typeof requireApproval === \"string\") return requireApproval;\n  return {\n    always: requireApproval.always\n      ? convertToolFilter(requireApproval.always)\n      : undefined,\n    never: requireApproval.never\n      ? convertToolFilter(requireApproval.never)\n      : undefined,\n  };\n}\n\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n *    the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n *    Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverDescription: \"A D&D MCP server for dice rolling\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"google_calendar\",\n *     connectorId: \"connector_googlecalendar\",\n *     authorization: \"<oauth-access-token>\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     allowedTools: [\"roll\"],  // Only allow the \"roll\" tool\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"deepwiki\",\n *     serverUrl: \"https://mcp.deepwiki.com/mcp\",\n *     requireApproval: {\n *       never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n *       // All other tools will require approval\n *     },\n *   })],\n * });\n * ```\n */\nexport function mcp(options: McpRemoteServerOptions): ServerTool;\nexport function mcp(options: McpConnectorOptions): ServerTool;\nexport function mcp(\n  options: McpRemoteServerOptions | McpConnectorOptions\n): ServerTool {\n  const baseConfig: McpTool = {\n    type: \"mcp\",\n    server_label: options.serverLabel,\n    allowed_tools: convertAllowedTools(options.allowedTools),\n    authorization: options.authorization,\n    headers: options.headers,\n    require_approval: convertRequireApproval(options.requireApproval),\n    server_description: options.serverDescription,\n  };\n\n  if (\"serverUrl\" in options) {\n    return {\n      ...baseConfig,\n      server_url: options.serverUrl,\n    } satisfies McpTool;\n  }\n\n  return {\n    ...baseConfig,\n    connector_id: options.connectorId,\n  } satisfies McpTool;\n}\n"],"mappings":";;;;AA4HA,SAAS,kBACPA,QAC+C;AAC/C,QAAO;EACL,YAAY,OAAO;EACnB,WAAW,OAAO;CACnB;AACF;;;;AAKD,SAAS,oBACPC,cAC2E;AAC3E,KAAI,CAAC,aAAc,QAAO;AAC1B,KAAI,MAAM,QAAQ,aAAa,CAAE,QAAO;AACxC,QAAO,kBAAkB,aAAa;AACvC;;;;AAKD,SAAS,uBACPC,iBAKY;AACZ,KAAI,CAAC,gBAAiB,QAAO;AAC7B,KAAI,OAAO,oBAAoB,SAAU,QAAO;AAChD,QAAO;EACL,QAAQ,gBAAgB,SACpB,kBAAkB,gBAAgB,OAAO,GACzC;EACJ,OAAO,gBAAgB,QACnB,kBAAkB,gBAAgB,MAAM,GACxC;CACL;AACF;AAoED,SAAgB,IACdC,SACY;CACZ,MAAMC,aAAsB;EAC1B,MAAM;EACN,cAAc,QAAQ;EACtB,eAAe,oBAAoB,QAAQ,aAAa;EACxD,eAAe,QAAQ;EACvB,SAAS,QAAQ;EACjB,kBAAkB,uBAAuB,QAAQ,gBAAgB;EACjE,oBAAoB,QAAQ;CAC7B;AAED,KAAI,eAAe,QACjB,QAAO;EACL,GAAG;EACH,YAAY,QAAQ;CACrB;AAGH,QAAO;EACL,GAAG;EACH,cAAc,QAAQ;CACvB;AACF"}
+{"version":3,"file":"mcp.js","names":[],"sources":["../../src/tools/mcp.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId =\n  | \"connector_dropbox\"\n  | \"connector_gmail\"\n  | \"connector_googlecalendar\"\n  | \"connector_googledrive\"\n  | \"connector_microsoftteams\"\n  | \"connector_outlookcalendar\"\n  | \"connector_outlookemail\"\n  | \"connector_sharepoint\";\n\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n  /**\n   * List of allowed tool names.\n   */\n  toolNames?: string[];\n  /**\n   * Indicates whether or not a tool modifies data or is read-only.\n   * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n   */\n  readOnly?: boolean;\n}\n\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n  /**\n   * Tools that always require approval before execution.\n   */\n  always?: McpToolFilter;\n  /**\n   * Tools that never require approval.\n   */\n  never?: McpToolFilter;\n}\n\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n  /**\n   * A label for this MCP server, used to identify it in tool calls.\n   */\n  serverLabel: string;\n  /**\n   * List of allowed tool names or a filter object.\n   * Use this to limit which tools from the MCP server are available to the model.\n   */\n  allowedTools?: string[] | McpToolFilter;\n  /**\n   * An OAuth access token for authentication with the MCP server.\n   * Your application must handle the OAuth authorization flow and provide the token here.\n   */\n  authorization?: string;\n  /**\n   * Optional HTTP headers to send to the MCP server.\n   * Use for authentication or other purposes.\n   */\n  headers?: Record<string, string>;\n  /**\n   * Specify which of the MCP server's tools require approval before execution.\n   * - `\"always\"`: All tools require approval\n   * - `\"never\"`: No tools require approval\n   * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n   *\n   * @default \"always\" (approval required for all tools)\n   */\n  requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n  /**\n   * Optional description of the MCP server, used to provide more context to the model.\n   */\n  serverDescription?: string;\n}\n\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n  /**\n   * The URL for the MCP server.\n   * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n   */\n  serverUrl: string;\n}\n\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n  /**\n   * Identifier for the service connector.\n   * These are OpenAI-maintained MCP wrappers for popular services.\n   *\n   * Available connectors:\n   * - `connector_dropbox`: Dropbox file access\n   * - `connector_gmail`: Gmail email access\n   * - `connector_googlecalendar`: Google Calendar access\n   * - `connector_googledrive`: Google Drive file access\n   * - `connector_microsoftteams`: Microsoft Teams access\n   * - `connector_outlookcalendar`: Outlook Calendar access\n   * - `connector_outlookemail`: Outlook Email access\n   * - `connector_sharepoint`: SharePoint file access\n   */\n  connectorId: McpConnectorId;\n}\n\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n\n/**\n * Converts a McpToolFilter to the API format.\n */\nfunction convertToolFilter(\n  filter: McpToolFilter\n): OpenAIClient.Responses.Tool.Mcp.McpToolFilter {\n  return {\n    tool_names: filter.toolNames,\n    read_only: filter.readOnly,\n  };\n}\n\n/**\n * Converts allowed_tools option to API format.\n */\nfunction convertAllowedTools(\n  allowedTools: string[] | McpToolFilter | undefined\n): Array<string> | OpenAIClient.Responses.Tool.Mcp.McpToolFilter | undefined {\n  if (!allowedTools) return undefined;\n  if (Array.isArray(allowedTools)) return allowedTools;\n  return convertToolFilter(allowedTools);\n}\n\n/**\n * Converts require_approval option to API format.\n */\nfunction convertRequireApproval(\n  requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined\n):\n  | OpenAIClient.Responses.Tool.Mcp.McpToolApprovalFilter\n  | \"always\"\n  | \"never\"\n  | undefined {\n  if (!requireApproval) return undefined;\n  if (typeof requireApproval === \"string\") return requireApproval;\n  return {\n    always: requireApproval.always\n      ? convertToolFilter(requireApproval.always)\n      : undefined,\n    never: requireApproval.never\n      ? convertToolFilter(requireApproval.never)\n      : undefined,\n  };\n}\n\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n *    the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n *    Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverDescription: \"A D&D MCP server for dice rolling\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"google_calendar\",\n *     connectorId: \"connector_googlecalendar\",\n *     authorization: \"<oauth-access-token>\",\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"dmcp\",\n *     serverUrl: \"https://dmcp-server.deno.dev/sse\",\n *     allowedTools: [\"roll\"],  // Only allow the \"roll\" tool\n *     requireApproval: \"never\",\n *   })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n *   tools: [tools.mcp({\n *     serverLabel: \"deepwiki\",\n *     serverUrl: \"https://mcp.deepwiki.com/mcp\",\n *     requireApproval: {\n *       never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n *       // All other tools will require approval\n *     },\n *   })],\n * });\n * ```\n */\nexport function mcp(options: McpRemoteServerOptions): ServerTool;\nexport function mcp(options: McpConnectorOptions): ServerTool;\nexport function mcp(\n  options: McpRemoteServerOptions | McpConnectorOptions\n): ServerTool {\n  const baseConfig: McpTool = {\n    type: \"mcp\",\n    server_label: options.serverLabel,\n    allowed_tools: convertAllowedTools(options.allowedTools),\n    authorization: options.authorization,\n    headers: options.headers,\n    require_approval: convertRequireApproval(options.requireApproval),\n    server_description: options.serverDescription,\n  };\n\n  if (\"serverUrl\" in options) {\n    return {\n      ...baseConfig,\n      server_url: options.serverUrl,\n    } satisfies McpTool;\n  }\n\n  return {\n    ...baseConfig,\n    connector_id: options.connectorId,\n  } satisfies McpTool;\n}\n"],"mappings":";;;;AA4HA,SAAS,kBACP,QAC+C;AAC/C,QAAO;EACL,YAAY,OAAO;EACnB,WAAW,OAAO;EACnB;;;;;AAMH,SAAS,oBACP,cAC2E;AAC3E,KAAI,CAAC,aAAc,QAAO;AAC1B,KAAI,MAAM,QAAQ,aAAa,CAAE,QAAO;AACxC,QAAO,kBAAkB,aAAa;;;;;AAMxC,SAAS,uBACP,iBAKY;AACZ,KAAI,CAAC,gBAAiB,QAAO;AAC7B,KAAI,OAAO,oBAAoB,SAAU,QAAO;AAChD,QAAO;EACL,QAAQ,gBAAgB,SACpB,kBAAkB,gBAAgB,OAAO,GACzC;EACJ,OAAO,gBAAgB,QACnB,kBAAkB,gBAAgB,MAAM,GACxC;EACL;;AAqEH,SAAgB,IACd,SACY;CACZ,MAAM,aAAsB;EAC1B,MAAM;EACN,cAAc,QAAQ;EACtB,eAAe,oBAAoB,QAAQ,aAAa;EACxD,eAAe,QAAQ;EACvB,SAAS,QAAQ;EACjB,kBAAkB,uBAAuB,QAAQ,gBAAgB;EACjE,oBAAoB,QAAQ;EAC7B;AAED,KAAI,eAAe,QACjB,QAAO;EACL,GAAG;EACH,YAAY,QAAQ;EACrB;AAGH,QAAO;EACL,GAAG;EACH,cAAc,QAAQ;EACvB"}

package/dist/tools/shell.cjs

@@ -1,6 +1,5 @@
-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"));
+let _langchain_core_tools = require("@langchain/core/tools");
+let zod_v4 = require("zod/v4");
 
 //#region src/tools/shell.ts
 const ShellActionSchema = zod_v4.z.object({
@@ -146,7 +145,7 @@ function shell(options) {
 			max_output_length: result.maxOutputLength
 		});
 	};
-	const shellTool = (0, __langchain_core_tools.tool)(executeWrapper, {
+	const shellTool = (0, _langchain_core_tools.tool)(executeWrapper, {
 		name: TOOL_NAME,
 		description: "Execute shell commands in a managed environment. Commands can be run concurrently.",
 		schema: ShellActionSchema

package/dist/tools/shell.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"shell.cjs","names":["z","options: ShellOptions","action: ShellAction"],"sources":["../../src/tools/shell.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 commands array, timeout, and max output length.\n */\nexport type ShellAction =\n  OpenAIClient.Responses.ResponseFunctionShellToolCall.Action;\n\n// Zod schema for shell action\nexport const ShellActionSchema = z.object({\n  commands: z.array(z.string()).describe(\"Array of shell commands to execute\"),\n  timeout_ms: z\n    .number()\n    .optional()\n    .describe(\"Optional timeout in milliseconds for the commands\"),\n  max_output_length: z\n    .number()\n    .optional()\n    .describe(\n      \"Optional maximum number of characters to return from each command\"\n    ),\n});\n\n/**\n * Result of a single shell command execution.\n * Contains stdout, stderr, and the outcome (exit code or timeout).\n */\nexport type ShellCommandOutput =\n  OpenAIClient.Responses.ResponseFunctionShellCallOutputContent;\n\n/**\n * Outcome type for shell command execution - either exit with code or timeout.\n */\nexport type ShellCallOutcome = ShellCommandOutput[\"outcome\"];\n\n/**\n * Result of executing shell commands.\n * Contains an array of outputs (one per command) and the max_output_length parameter.\n */\nexport interface ShellResult {\n  /**\n   * Array of command outputs. Each entry corresponds to a command from the action.\n   * The order should match the order of commands in the action.\n   */\n  output: ShellCommandOutput[];\n  /**\n   * The max_output_length from the action, which must be passed back to the API.\n   * If not provided in the action, can be omitted.\n   */\n  maxOutputLength?: number | null;\n}\n\n/**\n * Options for the Shell tool.\n */\nexport interface ShellOptions {\n  /**\n   * Execute function that handles shell command execution.\n   * This function receives the action input containing the commands and limits,\n   * and should return a ShellResult with stdout, stderr, and outcome for each command.\n   *\n   * @example\n   * ```typescript\n   * execute: async (action) => {\n   *   const outputs = await Promise.all(\n   *     action.commands.map(async (cmd) => {\n   *       try {\n   *         const { stdout, stderr } = await exec(cmd, {\n   *           timeout: action.timeout_ms ?? undefined,\n   *         });\n   *         return {\n   *           stdout,\n   *           stderr,\n   *           outcome: { type: \"exit\" as const, exit_code: 0 },\n   *         };\n   *       } catch (error) {\n   *         const timedOut = error.killed && error.signal === \"SIGTERM\";\n   *         return {\n   *           stdout: error.stdout ?? \"\",\n   *           stderr: error.stderr ?? String(error),\n   *           outcome: timedOut\n   *             ? { type: \"timeout\" as const }\n   *             : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n   *         };\n   *       }\n   *     })\n   *   );\n   *   return {\n   *     output: outputs,\n   *     maxOutputLength: action.max_output_length,\n   *   };\n   * }\n   * ```\n   */\n  execute: (action: ShellAction) => ShellResult | Promise<ShellResult>;\n}\n\n/**\n * OpenAI Shell tool type for the Responses API.\n */\nexport type ShellTool = OpenAIClient.Responses.FunctionShellTool;\n\nconst TOOL_NAME = \"shell\";\n\n/**\n * Creates a Shell tool that allows models to run shell commands through your integration.\n *\n * The shell tool allows the model to interact with your local computer through a controlled\n * command-line interface. The model proposes shell commands; your integration executes them\n * and returns the outputs. This creates a simple plan-execute loop that lets models inspect\n * the system, run utilities, and gather data until they can finish the task.\n *\n * **Important**: The shell tool is available through the Responses API for use with `GPT-5.1`.\n * It is not available on other models, or via the Chat Completions API.\n *\n * **When to use**:\n * - **Automating filesystem or process diagnostics** – For example, \"find the largest PDF\n *   under ~/Documents\" or \"show running gunicorn processes.\"\n * - **Extending the model's capabilities** – Using built-in UNIX utilities, python runtime\n *   and other CLIs in your environment.\n * - **Running multi-step build and test flows** – Chaining commands like `pip install` and `pytest`.\n * - **Complex agentic coding workflows** – Using other tools like `apply_patch` to complete\n *   workflows that involve complex file operations.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`shell_call` with `commands` array)\n * 2. Your code executes the commands (can be concurrent)\n * 3. You return stdout, stderr, and outcome for each command\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-shell | OpenAI Shell Documentation}\n * @see {@link https://github.com/openai/codex | Codex CLI} for reference implementation.\n *\n * @param options - Configuration for the Shell tool\n * @returns A 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/promises\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-5.1\" });\n *\n * // With execute callback for automatic command handling\n * const shellTool = tools.shell({\n *   execute: async (action) => {\n *     const outputs = await Promise.all(\n *       action.commands.map(async (cmd) => {\n *         try {\n *           const { stdout, stderr } = await exec(cmd, {\n *             timeout: action.timeout_ms ?? undefined,\n *           });\n *           return {\n *             stdout,\n *             stderr,\n *             outcome: { type: \"exit\" as const, exit_code: 0 },\n *           };\n *         } catch (error) {\n *           const timedOut = error.killed && error.signal === \"SIGTERM\";\n *           return {\n *             stdout: error.stdout ?? \"\",\n *             stderr: error.stderr ?? String(error),\n *             outcome: timedOut\n *               ? { type: \"timeout\" as const }\n *               : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n *           };\n *         }\n *       })\n *     );\n *     return {\n *       output: outputs,\n *       maxOutputLength: action.max_output_length,\n *     };\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shellTool]);\n * const response = await llmWithShell.invoke(\n *   \"Find the largest PDF file in ~/Documents\"\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.shell({ execute: myExecutor })],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute commands (with proper sandboxing!)\n *     const result = await executeCommands(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"shell_call_output\",\n *         call_id: shellCall.call_id,\n *         output: result.output,\n *         max_output_length: result.maxOutputLength,\n *       },\n *     ], {\n *       tools: [tools.shell({ execute: myExecutor })],\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 `gpt-5.1` model\n * - Commands are provided as an array of strings that can be executed concurrently\n * - Action includes: `commands`, `timeout_ms`, `max_output_length`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n * - If `max_output_length` exists in the action, always pass it back in the output\n * - Many CLI tools return non-zero exit codes for warnings; still capture stdout/stderr\n */\nexport function shell(options: ShellOptions) {\n  // Wrapper that converts ShellResult to string for LangChain tool compatibility\n  const executeWrapper = async (action: ShellAction): Promise<string> => {\n    const result = await options.execute(action);\n    // Return a JSON string representation for the tool result\n    return JSON.stringify({\n      output: result.output,\n      max_output_length: result.maxOutputLength,\n    });\n  };\n\n  const shellTool = tool(executeWrapper, {\n    name: TOOL_NAME,\n    description:\n      \"Execute shell commands in a managed environment. Commands can be run concurrently.\",\n    schema: ShellActionSchema,\n  });\n\n  shellTool.extras = {\n    ...(shellTool.extras ?? {}),\n    providerToolDefinition: {\n      type: \"shell\",\n    } satisfies ShellTool,\n  };\n\n  return shellTool as DynamicStructuredTool<\n    typeof ShellActionSchema,\n    ShellAction,\n    unknown,\n    string\n  >;\n}\n"],"mappings":";;;;;AAYA,MAAa,oBAAoBA,SAAE,OAAO;CACxC,UAAUA,SAAE,MAAMA,SAAE,QAAQ,CAAC,CAAC,SAAS,qCAAqC;CAC5E,YAAYA,SACT,QAAQ,CACR,UAAU,CACV,SAAS,oDAAoD;CAChE,mBAAmBA,SAChB,QAAQ,CACR,UAAU,CACV,SACC,oEACD;AACJ,EAAC;AAiFF,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmIlB,SAAgB,MAAMC,SAAuB;CAE3C,MAAM,iBAAiB,OAAOC,WAAyC;EACrE,MAAM,SAAS,MAAM,QAAQ,QAAQ,OAAO;AAE5C,SAAO,KAAK,UAAU;GACpB,QAAQ,OAAO;GACf,mBAAmB,OAAO;EAC3B,EAAC;CACH;CAED,MAAM,6CAAiB,gBAAgB;EACrC,MAAM;EACN,aACE;EACF,QAAQ;CACT,EAAC;CAEF,UAAU,SAAS;EACjB,GAAI,UAAU,UAAU,CAAE;EAC1B,wBAAwB,EACtB,MAAM,QACP;CACF;AAED,QAAO;AAMR"}
+{"version":3,"file":"shell.cjs","names":["z"],"sources":["../../src/tools/shell.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 commands array, timeout, and max output length.\n */\nexport type ShellAction =\n  OpenAIClient.Responses.ResponseFunctionShellToolCall.Action;\n\n// Zod schema for shell action\nexport const ShellActionSchema = z.object({\n  commands: z.array(z.string()).describe(\"Array of shell commands to execute\"),\n  timeout_ms: z\n    .number()\n    .optional()\n    .describe(\"Optional timeout in milliseconds for the commands\"),\n  max_output_length: z\n    .number()\n    .optional()\n    .describe(\n      \"Optional maximum number of characters to return from each command\"\n    ),\n});\n\n/**\n * Result of a single shell command execution.\n * Contains stdout, stderr, and the outcome (exit code or timeout).\n */\nexport type ShellCommandOutput =\n  OpenAIClient.Responses.ResponseFunctionShellCallOutputContent;\n\n/**\n * Outcome type for shell command execution - either exit with code or timeout.\n */\nexport type ShellCallOutcome = ShellCommandOutput[\"outcome\"];\n\n/**\n * Result of executing shell commands.\n * Contains an array of outputs (one per command) and the max_output_length parameter.\n */\nexport interface ShellResult {\n  /**\n   * Array of command outputs. Each entry corresponds to a command from the action.\n   * The order should match the order of commands in the action.\n   */\n  output: ShellCommandOutput[];\n  /**\n   * The max_output_length from the action, which must be passed back to the API.\n   * If not provided in the action, can be omitted.\n   */\n  maxOutputLength?: number | null;\n}\n\n/**\n * Options for the Shell tool.\n */\nexport interface ShellOptions {\n  /**\n   * Execute function that handles shell command execution.\n   * This function receives the action input containing the commands and limits,\n   * and should return a ShellResult with stdout, stderr, and outcome for each command.\n   *\n   * @example\n   * ```typescript\n   * execute: async (action) => {\n   *   const outputs = await Promise.all(\n   *     action.commands.map(async (cmd) => {\n   *       try {\n   *         const { stdout, stderr } = await exec(cmd, {\n   *           timeout: action.timeout_ms ?? undefined,\n   *         });\n   *         return {\n   *           stdout,\n   *           stderr,\n   *           outcome: { type: \"exit\" as const, exit_code: 0 },\n   *         };\n   *       } catch (error) {\n   *         const timedOut = error.killed && error.signal === \"SIGTERM\";\n   *         return {\n   *           stdout: error.stdout ?? \"\",\n   *           stderr: error.stderr ?? String(error),\n   *           outcome: timedOut\n   *             ? { type: \"timeout\" as const }\n   *             : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n   *         };\n   *       }\n   *     })\n   *   );\n   *   return {\n   *     output: outputs,\n   *     maxOutputLength: action.max_output_length,\n   *   };\n   * }\n   * ```\n   */\n  execute: (action: ShellAction) => ShellResult | Promise<ShellResult>;\n}\n\n/**\n * OpenAI Shell tool type for the Responses API.\n */\nexport type ShellTool = OpenAIClient.Responses.FunctionShellTool;\n\nconst TOOL_NAME = \"shell\";\n\n/**\n * Creates a Shell tool that allows models to run shell commands through your integration.\n *\n * The shell tool allows the model to interact with your local computer through a controlled\n * command-line interface. The model proposes shell commands; your integration executes them\n * and returns the outputs. This creates a simple plan-execute loop that lets models inspect\n * the system, run utilities, and gather data until they can finish the task.\n *\n * **Important**: The shell tool is available through the Responses API for use with `GPT-5.1`.\n * It is not available on other models, or via the Chat Completions API.\n *\n * **When to use**:\n * - **Automating filesystem or process diagnostics** – For example, \"find the largest PDF\n *   under ~/Documents\" or \"show running gunicorn processes.\"\n * - **Extending the model's capabilities** – Using built-in UNIX utilities, python runtime\n *   and other CLIs in your environment.\n * - **Running multi-step build and test flows** – Chaining commands like `pip install` and `pytest`.\n * - **Complex agentic coding workflows** – Using other tools like `apply_patch` to complete\n *   workflows that involve complex file operations.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`shell_call` with `commands` array)\n * 2. Your code executes the commands (can be concurrent)\n * 3. You return stdout, stderr, and outcome for each command\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-shell | OpenAI Shell Documentation}\n * @see {@link https://github.com/openai/codex | Codex CLI} for reference implementation.\n *\n * @param options - Configuration for the Shell tool\n * @returns A 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/promises\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-5.1\" });\n *\n * // With execute callback for automatic command handling\n * const shellTool = tools.shell({\n *   execute: async (action) => {\n *     const outputs = await Promise.all(\n *       action.commands.map(async (cmd) => {\n *         try {\n *           const { stdout, stderr } = await exec(cmd, {\n *             timeout: action.timeout_ms ?? undefined,\n *           });\n *           return {\n *             stdout,\n *             stderr,\n *             outcome: { type: \"exit\" as const, exit_code: 0 },\n *           };\n *         } catch (error) {\n *           const timedOut = error.killed && error.signal === \"SIGTERM\";\n *           return {\n *             stdout: error.stdout ?? \"\",\n *             stderr: error.stderr ?? String(error),\n *             outcome: timedOut\n *               ? { type: \"timeout\" as const }\n *               : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n *           };\n *         }\n *       })\n *     );\n *     return {\n *       output: outputs,\n *       maxOutputLength: action.max_output_length,\n *     };\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shellTool]);\n * const response = await llmWithShell.invoke(\n *   \"Find the largest PDF file in ~/Documents\"\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.shell({ execute: myExecutor })],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute commands (with proper sandboxing!)\n *     const result = await executeCommands(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"shell_call_output\",\n *         call_id: shellCall.call_id,\n *         output: result.output,\n *         max_output_length: result.maxOutputLength,\n *       },\n *     ], {\n *       tools: [tools.shell({ execute: myExecutor })],\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 `gpt-5.1` model\n * - Commands are provided as an array of strings that can be executed concurrently\n * - Action includes: `commands`, `timeout_ms`, `max_output_length`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n * - If `max_output_length` exists in the action, always pass it back in the output\n * - Many CLI tools return non-zero exit codes for warnings; still capture stdout/stderr\n */\nexport function shell(options: ShellOptions) {\n  // Wrapper that converts ShellResult to string for LangChain tool compatibility\n  const executeWrapper = async (action: ShellAction): Promise<string> => {\n    const result = await options.execute(action);\n    // Return a JSON string representation for the tool result\n    return JSON.stringify({\n      output: result.output,\n      max_output_length: result.maxOutputLength,\n    });\n  };\n\n  const shellTool = tool(executeWrapper, {\n    name: TOOL_NAME,\n    description:\n      \"Execute shell commands in a managed environment. Commands can be run concurrently.\",\n    schema: ShellActionSchema,\n  });\n\n  shellTool.extras = {\n    ...(shellTool.extras ?? {}),\n    providerToolDefinition: {\n      type: \"shell\",\n    } satisfies ShellTool,\n  };\n\n  return shellTool as DynamicStructuredTool<\n    typeof ShellActionSchema,\n    ShellAction,\n    unknown,\n    string\n  >;\n}\n"],"mappings":";;;;AAYA,MAAa,oBAAoBA,SAAE,OAAO;CACxC,UAAUA,SAAE,MAAMA,SAAE,QAAQ,CAAC,CAAC,SAAS,qCAAqC;CAC5E,YAAYA,SACT,QAAQ,CACR,UAAU,CACV,SAAS,oDAAoD;CAChE,mBAAmBA,SAChB,QAAQ,CACR,UAAU,CACV,SACC,oEACD;CACJ,CAAC;AAiFF,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmIlB,SAAgB,MAAM,SAAuB;CAE3C,MAAM,iBAAiB,OAAO,WAAyC;EACrE,MAAM,SAAS,MAAM,QAAQ,QAAQ,OAAO;AAE5C,SAAO,KAAK,UAAU;GACpB,QAAQ,OAAO;GACf,mBAAmB,OAAO;GAC3B,CAAC;;CAGJ,MAAM,4CAAiB,gBAAgB;EACrC,MAAM;EACN,aACE;EACF,QAAQ;EACT,CAAC;AAEF,WAAU,SAAS;EACjB,GAAI,UAAU,UAAU,EAAE;EAC1B,wBAAwB,EACtB,MAAM,SACP;EACF;AAED,QAAO"}

package/dist/tools/shell.d.cts

@@ -3,7 +3,6 @@ import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod/v4";
 
 //#region src/tools/shell.d.ts
-
 /**
  * Re-export action type from OpenAI SDK for convenience.
  * The action contains command details like commands array, timeout, and max output length.

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

@@ -1 +1 @@
-{"version":3,"file":"shell.d.cts","names":["z","OpenAI","OpenAIClient","DynamicStructuredTool","ShellAction","Responses","ResponseFunctionShellToolCall","Action","ShellActionSchema","ZodString","ZodArray","ZodNumber","ZodOptional","core","$strip","ZodObject","ShellCommandOutput","ResponseFunctionShellCallOutputContent","ShellCallOutcome","ShellResult","ShellOptions","Promise","ShellTool","FunctionShellTool","shell"],"sources":["../../src/tools/shell.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 commands array, timeout, and max output length.\n */\nexport type ShellAction = OpenAIClient.Responses.ResponseFunctionShellToolCall.Action;\nexport declare const ShellActionSchema: z.ZodObject<{\n    commands: z.ZodArray<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    max_output_length: z.ZodOptional<z.ZodNumber>;\n}, z.core.$strip>;\n/**\n * Result of a single shell command execution.\n * Contains stdout, stderr, and the outcome (exit code or timeout).\n */\nexport type ShellCommandOutput = OpenAIClient.Responses.ResponseFunctionShellCallOutputContent;\n/**\n * Outcome type for shell command execution - either exit with code or timeout.\n */\nexport type ShellCallOutcome = ShellCommandOutput[\"outcome\"];\n/**\n * Result of executing shell commands.\n * Contains an array of outputs (one per command) and the max_output_length parameter.\n */\nexport interface ShellResult {\n    /**\n     * Array of command outputs. Each entry corresponds to a command from the action.\n     * The order should match the order of commands in the action.\n     */\n    output: ShellCommandOutput[];\n    /**\n     * The max_output_length from the action, which must be passed back to the API.\n     * If not provided in the action, can be omitted.\n     */\n    maxOutputLength?: number | null;\n}\n/**\n * Options for the Shell tool.\n */\nexport interface ShellOptions {\n    /**\n     * Execute function that handles shell command execution.\n     * This function receives the action input containing the commands and limits,\n     * and should return a ShellResult with stdout, stderr, and outcome for each command.\n     *\n     * @example\n     * ```typescript\n     * execute: async (action) => {\n     *   const outputs = await Promise.all(\n     *     action.commands.map(async (cmd) => {\n     *       try {\n     *         const { stdout, stderr } = await exec(cmd, {\n     *           timeout: action.timeout_ms ?? undefined,\n     *         });\n     *         return {\n     *           stdout,\n     *           stderr,\n     *           outcome: { type: \"exit\" as const, exit_code: 0 },\n     *         };\n     *       } catch (error) {\n     *         const timedOut = error.killed && error.signal === \"SIGTERM\";\n     *         return {\n     *           stdout: error.stdout ?? \"\",\n     *           stderr: error.stderr ?? String(error),\n     *           outcome: timedOut\n     *             ? { type: \"timeout\" as const }\n     *             : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n     *         };\n     *       }\n     *     })\n     *   );\n     *   return {\n     *     output: outputs,\n     *     maxOutputLength: action.max_output_length,\n     *   };\n     * }\n     * ```\n     */\n    execute: (action: ShellAction) => ShellResult | Promise<ShellResult>;\n}\n/**\n * OpenAI Shell tool type for the Responses API.\n */\nexport type ShellTool = OpenAIClient.Responses.FunctionShellTool;\n/**\n * Creates a Shell tool that allows models to run shell commands through your integration.\n *\n * The shell tool allows the model to interact with your local computer through a controlled\n * command-line interface. The model proposes shell commands; your integration executes them\n * and returns the outputs. This creates a simple plan-execute loop that lets models inspect\n * the system, run utilities, and gather data until they can finish the task.\n *\n * **Important**: The shell tool is available through the Responses API for use with `GPT-5.1`.\n * It is not available on other models, or via the Chat Completions API.\n *\n * **When to use**:\n * - **Automating filesystem or process diagnostics** – For example, \"find the largest PDF\n *   under ~/Documents\" or \"show running gunicorn processes.\"\n * - **Extending the model's capabilities** – Using built-in UNIX utilities, python runtime\n *   and other CLIs in your environment.\n * - **Running multi-step build and test flows** – Chaining commands like `pip install` and `pytest`.\n * - **Complex agentic coding workflows** – Using other tools like `apply_patch` to complete\n *   workflows that involve complex file operations.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`shell_call` with `commands` array)\n * 2. Your code executes the commands (can be concurrent)\n * 3. You return stdout, stderr, and outcome for each command\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-shell | OpenAI Shell Documentation}\n * @see {@link https://github.com/openai/codex | Codex CLI} for reference implementation.\n *\n * @param options - Configuration for the Shell tool\n * @returns A 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/promises\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-5.1\" });\n *\n * // With execute callback for automatic command handling\n * const shellTool = tools.shell({\n *   execute: async (action) => {\n *     const outputs = await Promise.all(\n *       action.commands.map(async (cmd) => {\n *         try {\n *           const { stdout, stderr } = await exec(cmd, {\n *             timeout: action.timeout_ms ?? undefined,\n *           });\n *           return {\n *             stdout,\n *             stderr,\n *             outcome: { type: \"exit\" as const, exit_code: 0 },\n *           };\n *         } catch (error) {\n *           const timedOut = error.killed && error.signal === \"SIGTERM\";\n *           return {\n *             stdout: error.stdout ?? \"\",\n *             stderr: error.stderr ?? String(error),\n *             outcome: timedOut\n *               ? { type: \"timeout\" as const }\n *               : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n *           };\n *         }\n *       })\n *     );\n *     return {\n *       output: outputs,\n *       maxOutputLength: action.max_output_length,\n *     };\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shellTool]);\n * const response = await llmWithShell.invoke(\n *   \"Find the largest PDF file in ~/Documents\"\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.shell({ execute: myExecutor })],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute commands (with proper sandboxing!)\n *     const result = await executeCommands(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"shell_call_output\",\n *         call_id: shellCall.call_id,\n *         output: result.output,\n *         max_output_length: result.maxOutputLength,\n *       },\n *     ], {\n *       tools: [tools.shell({ execute: myExecutor })],\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 `gpt-5.1` model\n * - Commands are provided as an array of strings that can be executed concurrently\n * - Action includes: `commands`, `timeout_ms`, `max_output_length`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n * - If `max_output_length` exists in the action, always pass it back in the output\n * - Many CLI tools return non-zero exit codes for warnings; still capture stdout/stderr\n */\nexport declare function shell(options: ShellOptions): DynamicStructuredTool<z.ZodObject<{\n    commands: z.ZodArray<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    max_output_length: z.ZodOptional<z.ZodNumber>;\n}, z.core.$strip>, OpenAIClient.Responses.ResponseFunctionShellToolCall.Action, unknown, string, string>;\n//# sourceMappingURL=shell.d.ts.map"],"mappings":";;;;;;;;AAOA;AAUA;AAIYkB,KAdAd,WAAAA,GAAcF,QAAAA,CAAaG,SAAAA,CAAUC,6BAAAA,CAA8BC,MAc9B;;AA2DU;AAK3D;AAkIA;AAAuCa,KAtM3BJ,kBAAAA,GAAqBd,QAAAA,CAAaG,SAAAA,CAAUY,sCAsMjBG;;;;AAErBR,KApMNM,gBAAAA,GAAmBF,kBAoMbJ,CAAAA,SAAAA,CAAAA;;;;;AAECV,UAjMFiB,WAAAA,CAiMyBb;EAJYH;AAAqB;;;UAxL/Da;;;;;;;;;;UAUKI,YAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAuCKhB,gBAAgBe,cAAcE,QAAQF;;;;;KAKhDG,SAAAA,GAAYpB,QAAAA,CAAaG,SAAAA,CAAUkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkIvBC,KAAAA,UAAeJ,eAAejB,sBAAsBH,CAAAA,CAAEe;YAChEf,CAAAA,CAAEU,SAASV,CAAAA,CAAES;cACXT,CAAAA,CAAEY,YAAYZ,CAAAA,CAAEW;qBACTX,CAAAA,CAAEY,YAAYZ,CAAAA,CAAEW;GACpCX,CAAAA,CAAEa,IAAAA,CAAKC,SAASZ,QAAAA,CAAaG,SAAAA,CAAUC,6BAAAA,CAA8BC"}
+{"version":3,"file":"shell.d.cts","names":[],"sources":["../../src/tools/shell.ts"],"mappings":";;;;;;;AAQA;;KAAY,WAAA,GACV,QAAA,CAAa,SAAA,CAAU,6BAAA,CAA8B,MAAA;;;AAqBvD;;KAAY,kBAAA,GACV,QAAA,CAAa,SAAA,CAAU,sCAAA;;;;KAKb,gBAAA,GAAmB,kBAAA;;;AAA/B;;UAMiB,WAAA;EANc;;AAM/B;;EAKE,MAAA,EAAQ,kBAAA;EAAkB;;;;EAK1B,eAAA;AAAA;AAMF;;;AAAA,UAAiB,YAAA;EAuCmB;;;;;;;;;;;;;AAMpC;;;;;;;;;AAqIA;;;;;;;;;;;;;;;;EA3IE,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,WAAA,GAAc,OAAA,CAAQ,WAAA;AAAA;;;;KAM9C,SAAA,GAAY,QAAA,CAAa,SAAA,CAAU,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqI/B,KAAA,CAAM,OAAA,EAAS,YAAA,GAAY,qBAAA,CAAA,CAAA,CAAA,SAAA"}

package/dist/tools/shell.d.ts

@@ -3,7 +3,6 @@ import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod/v4";
 
 //#region src/tools/shell.d.ts
-
 /**
  * Re-export action type from OpenAI SDK for convenience.
  * The action contains command details like commands array, timeout, and max output length.

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

@@ -1 +1 @@
-{"version":3,"file":"shell.d.ts","names":["z","OpenAI","OpenAIClient","DynamicStructuredTool","ShellAction","Responses","ResponseFunctionShellToolCall","Action","ShellActionSchema","ZodString","ZodArray","ZodNumber","ZodOptional","core","$strip","ZodObject","ShellCommandOutput","ResponseFunctionShellCallOutputContent","ShellCallOutcome","ShellResult","ShellOptions","Promise","ShellTool","FunctionShellTool","shell"],"sources":["../../src/tools/shell.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 commands array, timeout, and max output length.\n */\nexport type ShellAction = OpenAIClient.Responses.ResponseFunctionShellToolCall.Action;\nexport declare const ShellActionSchema: z.ZodObject<{\n    commands: z.ZodArray<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    max_output_length: z.ZodOptional<z.ZodNumber>;\n}, z.core.$strip>;\n/**\n * Result of a single shell command execution.\n * Contains stdout, stderr, and the outcome (exit code or timeout).\n */\nexport type ShellCommandOutput = OpenAIClient.Responses.ResponseFunctionShellCallOutputContent;\n/**\n * Outcome type for shell command execution - either exit with code or timeout.\n */\nexport type ShellCallOutcome = ShellCommandOutput[\"outcome\"];\n/**\n * Result of executing shell commands.\n * Contains an array of outputs (one per command) and the max_output_length parameter.\n */\nexport interface ShellResult {\n    /**\n     * Array of command outputs. Each entry corresponds to a command from the action.\n     * The order should match the order of commands in the action.\n     */\n    output: ShellCommandOutput[];\n    /**\n     * The max_output_length from the action, which must be passed back to the API.\n     * If not provided in the action, can be omitted.\n     */\n    maxOutputLength?: number | null;\n}\n/**\n * Options for the Shell tool.\n */\nexport interface ShellOptions {\n    /**\n     * Execute function that handles shell command execution.\n     * This function receives the action input containing the commands and limits,\n     * and should return a ShellResult with stdout, stderr, and outcome for each command.\n     *\n     * @example\n     * ```typescript\n     * execute: async (action) => {\n     *   const outputs = await Promise.all(\n     *     action.commands.map(async (cmd) => {\n     *       try {\n     *         const { stdout, stderr } = await exec(cmd, {\n     *           timeout: action.timeout_ms ?? undefined,\n     *         });\n     *         return {\n     *           stdout,\n     *           stderr,\n     *           outcome: { type: \"exit\" as const, exit_code: 0 },\n     *         };\n     *       } catch (error) {\n     *         const timedOut = error.killed && error.signal === \"SIGTERM\";\n     *         return {\n     *           stdout: error.stdout ?? \"\",\n     *           stderr: error.stderr ?? String(error),\n     *           outcome: timedOut\n     *             ? { type: \"timeout\" as const }\n     *             : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n     *         };\n     *       }\n     *     })\n     *   );\n     *   return {\n     *     output: outputs,\n     *     maxOutputLength: action.max_output_length,\n     *   };\n     * }\n     * ```\n     */\n    execute: (action: ShellAction) => ShellResult | Promise<ShellResult>;\n}\n/**\n * OpenAI Shell tool type for the Responses API.\n */\nexport type ShellTool = OpenAIClient.Responses.FunctionShellTool;\n/**\n * Creates a Shell tool that allows models to run shell commands through your integration.\n *\n * The shell tool allows the model to interact with your local computer through a controlled\n * command-line interface. The model proposes shell commands; your integration executes them\n * and returns the outputs. This creates a simple plan-execute loop that lets models inspect\n * the system, run utilities, and gather data until they can finish the task.\n *\n * **Important**: The shell tool is available through the Responses API for use with `GPT-5.1`.\n * It is not available on other models, or via the Chat Completions API.\n *\n * **When to use**:\n * - **Automating filesystem or process diagnostics** – For example, \"find the largest PDF\n *   under ~/Documents\" or \"show running gunicorn processes.\"\n * - **Extending the model's capabilities** – Using built-in UNIX utilities, python runtime\n *   and other CLIs in your environment.\n * - **Running multi-step build and test flows** – Chaining commands like `pip install` and `pytest`.\n * - **Complex agentic coding workflows** – Using other tools like `apply_patch` to complete\n *   workflows that involve complex file operations.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`shell_call` with `commands` array)\n * 2. Your code executes the commands (can be concurrent)\n * 3. You return stdout, stderr, and outcome for each command\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-shell | OpenAI Shell Documentation}\n * @see {@link https://github.com/openai/codex | Codex CLI} for reference implementation.\n *\n * @param options - Configuration for the Shell tool\n * @returns A 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/promises\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-5.1\" });\n *\n * // With execute callback for automatic command handling\n * const shellTool = tools.shell({\n *   execute: async (action) => {\n *     const outputs = await Promise.all(\n *       action.commands.map(async (cmd) => {\n *         try {\n *           const { stdout, stderr } = await exec(cmd, {\n *             timeout: action.timeout_ms ?? undefined,\n *           });\n *           return {\n *             stdout,\n *             stderr,\n *             outcome: { type: \"exit\" as const, exit_code: 0 },\n *           };\n *         } catch (error) {\n *           const timedOut = error.killed && error.signal === \"SIGTERM\";\n *           return {\n *             stdout: error.stdout ?? \"\",\n *             stderr: error.stderr ?? String(error),\n *             outcome: timedOut\n *               ? { type: \"timeout\" as const }\n *               : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n *           };\n *         }\n *       })\n *     );\n *     return {\n *       output: outputs,\n *       maxOutputLength: action.max_output_length,\n *     };\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shellTool]);\n * const response = await llmWithShell.invoke(\n *   \"Find the largest PDF file in ~/Documents\"\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.shell({ execute: myExecutor })],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute commands (with proper sandboxing!)\n *     const result = await executeCommands(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"shell_call_output\",\n *         call_id: shellCall.call_id,\n *         output: result.output,\n *         max_output_length: result.maxOutputLength,\n *       },\n *     ], {\n *       tools: [tools.shell({ execute: myExecutor })],\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 `gpt-5.1` model\n * - Commands are provided as an array of strings that can be executed concurrently\n * - Action includes: `commands`, `timeout_ms`, `max_output_length`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n * - If `max_output_length` exists in the action, always pass it back in the output\n * - Many CLI tools return non-zero exit codes for warnings; still capture stdout/stderr\n */\nexport declare function shell(options: ShellOptions): DynamicStructuredTool<z.ZodObject<{\n    commands: z.ZodArray<z.ZodString>;\n    timeout_ms: z.ZodOptional<z.ZodNumber>;\n    max_output_length: z.ZodOptional<z.ZodNumber>;\n}, z.core.$strip>, OpenAIClient.Responses.ResponseFunctionShellToolCall.Action, unknown, string, string>;\n//# sourceMappingURL=shell.d.ts.map"],"mappings":";;;;;;;;AAOA;AAUA;AAIYkB,KAdAd,WAAAA,GAAcF,QAAAA,CAAaG,SAAAA,CAAUC,6BAAAA,CAA8BC,MAc9B;;AA2DU;AAK3D;AAkIA;AAAuCa,KAtM3BJ,kBAAAA,GAAqBd,QAAAA,CAAaG,SAAAA,CAAUY,sCAsMjBG;;;;AAErBR,KApMNM,gBAAAA,GAAmBF,kBAoMbJ,CAAAA,SAAAA,CAAAA;;;;;AAECV,UAjMFiB,WAAAA,CAiMyBb;EAJYH;AAAqB;;;UAxL/Da;;;;;;;;;;UAUKI,YAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAuCKhB,gBAAgBe,cAAcE,QAAQF;;;;;KAKhDG,SAAAA,GAAYpB,QAAAA,CAAaG,SAAAA,CAAUkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkIvBC,KAAAA,UAAeJ,eAAejB,sBAAsBH,CAAAA,CAAEe;YAChEf,CAAAA,CAAEU,SAASV,CAAAA,CAAES;cACXT,CAAAA,CAAEY,YAAYZ,CAAAA,CAAEW;qBACTX,CAAAA,CAAEY,YAAYZ,CAAAA,CAAEW;GACpCX,CAAAA,CAAEa,IAAAA,CAAKC,SAASZ,QAAAA,CAAaG,SAAAA,CAAUC,6BAAAA,CAA8BC"}
+{"version":3,"file":"shell.d.ts","names":[],"sources":["../../src/tools/shell.ts"],"mappings":";;;;;;;AAQA;;KAAY,WAAA,GACV,QAAA,CAAa,SAAA,CAAU,6BAAA,CAA8B,MAAA;;;AAqBvD;;KAAY,kBAAA,GACV,QAAA,CAAa,SAAA,CAAU,sCAAA;;;;KAKb,gBAAA,GAAmB,kBAAA;;;AAA/B;;UAMiB,WAAA;EANc;;AAM/B;;EAKE,MAAA,EAAQ,kBAAA;EAAkB;;;;EAK1B,eAAA;AAAA;AAMF;;;AAAA,UAAiB,YAAA;EAuCmB;;;;;;;;;;;;;AAMpC;;;;;;;;;AAqIA;;;;;;;;;;;;;;;;EA3IE,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,WAAA,GAAc,OAAA,CAAQ,WAAA;AAAA;;;;KAM9C,SAAA,GAAY,QAAA,CAAa,SAAA,CAAU,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqI/B,KAAA,CAAM,OAAA,EAAS,YAAA,GAAY,qBAAA,CAAA,CAAA,CAAA,SAAA"}

package/dist/tools/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","names":["options: ShellOptions","action: ShellAction"],"sources":["../../src/tools/shell.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 commands array, timeout, and max output length.\n */\nexport type ShellAction =\n  OpenAIClient.Responses.ResponseFunctionShellToolCall.Action;\n\n// Zod schema for shell action\nexport const ShellActionSchema = z.object({\n  commands: z.array(z.string()).describe(\"Array of shell commands to execute\"),\n  timeout_ms: z\n    .number()\n    .optional()\n    .describe(\"Optional timeout in milliseconds for the commands\"),\n  max_output_length: z\n    .number()\n    .optional()\n    .describe(\n      \"Optional maximum number of characters to return from each command\"\n    ),\n});\n\n/**\n * Result of a single shell command execution.\n * Contains stdout, stderr, and the outcome (exit code or timeout).\n */\nexport type ShellCommandOutput =\n  OpenAIClient.Responses.ResponseFunctionShellCallOutputContent;\n\n/**\n * Outcome type for shell command execution - either exit with code or timeout.\n */\nexport type ShellCallOutcome = ShellCommandOutput[\"outcome\"];\n\n/**\n * Result of executing shell commands.\n * Contains an array of outputs (one per command) and the max_output_length parameter.\n */\nexport interface ShellResult {\n  /**\n   * Array of command outputs. Each entry corresponds to a command from the action.\n   * The order should match the order of commands in the action.\n   */\n  output: ShellCommandOutput[];\n  /**\n   * The max_output_length from the action, which must be passed back to the API.\n   * If not provided in the action, can be omitted.\n   */\n  maxOutputLength?: number | null;\n}\n\n/**\n * Options for the Shell tool.\n */\nexport interface ShellOptions {\n  /**\n   * Execute function that handles shell command execution.\n   * This function receives the action input containing the commands and limits,\n   * and should return a ShellResult with stdout, stderr, and outcome for each command.\n   *\n   * @example\n   * ```typescript\n   * execute: async (action) => {\n   *   const outputs = await Promise.all(\n   *     action.commands.map(async (cmd) => {\n   *       try {\n   *         const { stdout, stderr } = await exec(cmd, {\n   *           timeout: action.timeout_ms ?? undefined,\n   *         });\n   *         return {\n   *           stdout,\n   *           stderr,\n   *           outcome: { type: \"exit\" as const, exit_code: 0 },\n   *         };\n   *       } catch (error) {\n   *         const timedOut = error.killed && error.signal === \"SIGTERM\";\n   *         return {\n   *           stdout: error.stdout ?? \"\",\n   *           stderr: error.stderr ?? String(error),\n   *           outcome: timedOut\n   *             ? { type: \"timeout\" as const }\n   *             : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n   *         };\n   *       }\n   *     })\n   *   );\n   *   return {\n   *     output: outputs,\n   *     maxOutputLength: action.max_output_length,\n   *   };\n   * }\n   * ```\n   */\n  execute: (action: ShellAction) => ShellResult | Promise<ShellResult>;\n}\n\n/**\n * OpenAI Shell tool type for the Responses API.\n */\nexport type ShellTool = OpenAIClient.Responses.FunctionShellTool;\n\nconst TOOL_NAME = \"shell\";\n\n/**\n * Creates a Shell tool that allows models to run shell commands through your integration.\n *\n * The shell tool allows the model to interact with your local computer through a controlled\n * command-line interface. The model proposes shell commands; your integration executes them\n * and returns the outputs. This creates a simple plan-execute loop that lets models inspect\n * the system, run utilities, and gather data until they can finish the task.\n *\n * **Important**: The shell tool is available through the Responses API for use with `GPT-5.1`.\n * It is not available on other models, or via the Chat Completions API.\n *\n * **When to use**:\n * - **Automating filesystem or process diagnostics** – For example, \"find the largest PDF\n *   under ~/Documents\" or \"show running gunicorn processes.\"\n * - **Extending the model's capabilities** – Using built-in UNIX utilities, python runtime\n *   and other CLIs in your environment.\n * - **Running multi-step build and test flows** – Chaining commands like `pip install` and `pytest`.\n * - **Complex agentic coding workflows** – Using other tools like `apply_patch` to complete\n *   workflows that involve complex file operations.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`shell_call` with `commands` array)\n * 2. Your code executes the commands (can be concurrent)\n * 3. You return stdout, stderr, and outcome for each command\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-shell | OpenAI Shell Documentation}\n * @see {@link https://github.com/openai/codex | Codex CLI} for reference implementation.\n *\n * @param options - Configuration for the Shell tool\n * @returns A 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/promises\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-5.1\" });\n *\n * // With execute callback for automatic command handling\n * const shellTool = tools.shell({\n *   execute: async (action) => {\n *     const outputs = await Promise.all(\n *       action.commands.map(async (cmd) => {\n *         try {\n *           const { stdout, stderr } = await exec(cmd, {\n *             timeout: action.timeout_ms ?? undefined,\n *           });\n *           return {\n *             stdout,\n *             stderr,\n *             outcome: { type: \"exit\" as const, exit_code: 0 },\n *           };\n *         } catch (error) {\n *           const timedOut = error.killed && error.signal === \"SIGTERM\";\n *           return {\n *             stdout: error.stdout ?? \"\",\n *             stderr: error.stderr ?? String(error),\n *             outcome: timedOut\n *               ? { type: \"timeout\" as const }\n *               : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n *           };\n *         }\n *       })\n *     );\n *     return {\n *       output: outputs,\n *       maxOutputLength: action.max_output_length,\n *     };\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shellTool]);\n * const response = await llmWithShell.invoke(\n *   \"Find the largest PDF file in ~/Documents\"\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.shell({ execute: myExecutor })],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute commands (with proper sandboxing!)\n *     const result = await executeCommands(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"shell_call_output\",\n *         call_id: shellCall.call_id,\n *         output: result.output,\n *         max_output_length: result.maxOutputLength,\n *       },\n *     ], {\n *       tools: [tools.shell({ execute: myExecutor })],\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 `gpt-5.1` model\n * - Commands are provided as an array of strings that can be executed concurrently\n * - Action includes: `commands`, `timeout_ms`, `max_output_length`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n * - If `max_output_length` exists in the action, always pass it back in the output\n * - Many CLI tools return non-zero exit codes for warnings; still capture stdout/stderr\n */\nexport function shell(options: ShellOptions) {\n  // Wrapper that converts ShellResult to string for LangChain tool compatibility\n  const executeWrapper = async (action: ShellAction): Promise<string> => {\n    const result = await options.execute(action);\n    // Return a JSON string representation for the tool result\n    return JSON.stringify({\n      output: result.output,\n      max_output_length: result.maxOutputLength,\n    });\n  };\n\n  const shellTool = tool(executeWrapper, {\n    name: TOOL_NAME,\n    description:\n      \"Execute shell commands in a managed environment. Commands can be run concurrently.\",\n    schema: ShellActionSchema,\n  });\n\n  shellTool.extras = {\n    ...(shellTool.extras ?? {}),\n    providerToolDefinition: {\n      type: \"shell\",\n    } satisfies ShellTool,\n  };\n\n  return shellTool as DynamicStructuredTool<\n    typeof ShellActionSchema,\n    ShellAction,\n    unknown,\n    string\n  >;\n}\n"],"mappings":";;;;AAYA,MAAa,oBAAoB,EAAE,OAAO;CACxC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,SAAS,qCAAqC;CAC5E,YAAY,EACT,QAAQ,CACR,UAAU,CACV,SAAS,oDAAoD;CAChE,mBAAmB,EAChB,QAAQ,CACR,UAAU,CACV,SACC,oEACD;AACJ,EAAC;AAiFF,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmIlB,SAAgB,MAAMA,SAAuB;CAE3C,MAAM,iBAAiB,OAAOC,WAAyC;EACrE,MAAM,SAAS,MAAM,QAAQ,QAAQ,OAAO;AAE5C,SAAO,KAAK,UAAU;GACpB,QAAQ,OAAO;GACf,mBAAmB,OAAO;EAC3B,EAAC;CACH;CAED,MAAM,YAAY,KAAK,gBAAgB;EACrC,MAAM;EACN,aACE;EACF,QAAQ;CACT,EAAC;CAEF,UAAU,SAAS;EACjB,GAAI,UAAU,UAAU,CAAE;EAC1B,wBAAwB,EACtB,MAAM,QACP;CACF;AAED,QAAO;AAMR"}
+{"version":3,"file":"shell.js","names":[],"sources":["../../src/tools/shell.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 commands array, timeout, and max output length.\n */\nexport type ShellAction =\n  OpenAIClient.Responses.ResponseFunctionShellToolCall.Action;\n\n// Zod schema for shell action\nexport const ShellActionSchema = z.object({\n  commands: z.array(z.string()).describe(\"Array of shell commands to execute\"),\n  timeout_ms: z\n    .number()\n    .optional()\n    .describe(\"Optional timeout in milliseconds for the commands\"),\n  max_output_length: z\n    .number()\n    .optional()\n    .describe(\n      \"Optional maximum number of characters to return from each command\"\n    ),\n});\n\n/**\n * Result of a single shell command execution.\n * Contains stdout, stderr, and the outcome (exit code or timeout).\n */\nexport type ShellCommandOutput =\n  OpenAIClient.Responses.ResponseFunctionShellCallOutputContent;\n\n/**\n * Outcome type for shell command execution - either exit with code or timeout.\n */\nexport type ShellCallOutcome = ShellCommandOutput[\"outcome\"];\n\n/**\n * Result of executing shell commands.\n * Contains an array of outputs (one per command) and the max_output_length parameter.\n */\nexport interface ShellResult {\n  /**\n   * Array of command outputs. Each entry corresponds to a command from the action.\n   * The order should match the order of commands in the action.\n   */\n  output: ShellCommandOutput[];\n  /**\n   * The max_output_length from the action, which must be passed back to the API.\n   * If not provided in the action, can be omitted.\n   */\n  maxOutputLength?: number | null;\n}\n\n/**\n * Options for the Shell tool.\n */\nexport interface ShellOptions {\n  /**\n   * Execute function that handles shell command execution.\n   * This function receives the action input containing the commands and limits,\n   * and should return a ShellResult with stdout, stderr, and outcome for each command.\n   *\n   * @example\n   * ```typescript\n   * execute: async (action) => {\n   *   const outputs = await Promise.all(\n   *     action.commands.map(async (cmd) => {\n   *       try {\n   *         const { stdout, stderr } = await exec(cmd, {\n   *           timeout: action.timeout_ms ?? undefined,\n   *         });\n   *         return {\n   *           stdout,\n   *           stderr,\n   *           outcome: { type: \"exit\" as const, exit_code: 0 },\n   *         };\n   *       } catch (error) {\n   *         const timedOut = error.killed && error.signal === \"SIGTERM\";\n   *         return {\n   *           stdout: error.stdout ?? \"\",\n   *           stderr: error.stderr ?? String(error),\n   *           outcome: timedOut\n   *             ? { type: \"timeout\" as const }\n   *             : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n   *         };\n   *       }\n   *     })\n   *   );\n   *   return {\n   *     output: outputs,\n   *     maxOutputLength: action.max_output_length,\n   *   };\n   * }\n   * ```\n   */\n  execute: (action: ShellAction) => ShellResult | Promise<ShellResult>;\n}\n\n/**\n * OpenAI Shell tool type for the Responses API.\n */\nexport type ShellTool = OpenAIClient.Responses.FunctionShellTool;\n\nconst TOOL_NAME = \"shell\";\n\n/**\n * Creates a Shell tool that allows models to run shell commands through your integration.\n *\n * The shell tool allows the model to interact with your local computer through a controlled\n * command-line interface. The model proposes shell commands; your integration executes them\n * and returns the outputs. This creates a simple plan-execute loop that lets models inspect\n * the system, run utilities, and gather data until they can finish the task.\n *\n * **Important**: The shell tool is available through the Responses API for use with `GPT-5.1`.\n * It is not available on other models, or via the Chat Completions API.\n *\n * **When to use**:\n * - **Automating filesystem or process diagnostics** – For example, \"find the largest PDF\n *   under ~/Documents\" or \"show running gunicorn processes.\"\n * - **Extending the model's capabilities** – Using built-in UNIX utilities, python runtime\n *   and other CLIs in your environment.\n * - **Running multi-step build and test flows** – Chaining commands like `pip install` and `pytest`.\n * - **Complex agentic coding workflows** – Using other tools like `apply_patch` to complete\n *   workflows that involve complex file operations.\n *\n * **How it works**:\n * The tool operates in a continuous loop:\n * 1. Model sends shell commands (`shell_call` with `commands` array)\n * 2. Your code executes the commands (can be concurrent)\n * 3. You return stdout, stderr, and outcome for each command\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-shell | OpenAI Shell Documentation}\n * @see {@link https://github.com/openai/codex | Codex CLI} for reference implementation.\n *\n * @param options - Configuration for the Shell tool\n * @returns A 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/promises\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-5.1\" });\n *\n * // With execute callback for automatic command handling\n * const shellTool = tools.shell({\n *   execute: async (action) => {\n *     const outputs = await Promise.all(\n *       action.commands.map(async (cmd) => {\n *         try {\n *           const { stdout, stderr } = await exec(cmd, {\n *             timeout: action.timeout_ms ?? undefined,\n *           });\n *           return {\n *             stdout,\n *             stderr,\n *             outcome: { type: \"exit\" as const, exit_code: 0 },\n *           };\n *         } catch (error) {\n *           const timedOut = error.killed && error.signal === \"SIGTERM\";\n *           return {\n *             stdout: error.stdout ?? \"\",\n *             stderr: error.stderr ?? String(error),\n *             outcome: timedOut\n *               ? { type: \"timeout\" as const }\n *               : { type: \"exit\" as const, exit_code: error.code ?? 1 },\n *           };\n *         }\n *       })\n *     );\n *     return {\n *       output: outputs,\n *       maxOutputLength: action.max_output_length,\n *     };\n *   },\n * });\n *\n * const llmWithShell = model.bindTools([shellTool]);\n * const response = await llmWithShell.invoke(\n *   \"Find the largest PDF file in ~/Documents\"\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.shell({ execute: myExecutor })],\n *   });\n *\n *   while (true) {\n *     const shellCall = response.additional_kwargs.tool_outputs?.find(\n *       (output) => output.type === \"shell_call\"\n *     );\n *\n *     if (!shellCall) break;\n *\n *     // Execute commands (with proper sandboxing!)\n *     const result = await executeCommands(shellCall.action);\n *\n *     // Send output back to model\n *     response = await model.invoke([\n *       response,\n *       {\n *         type: \"shell_call_output\",\n *         call_id: shellCall.call_id,\n *         output: result.output,\n *         max_output_length: result.maxOutputLength,\n *       },\n *     ], {\n *       tools: [tools.shell({ execute: myExecutor })],\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 `gpt-5.1` model\n * - Commands are provided as an array of strings that can be executed concurrently\n * - Action includes: `commands`, `timeout_ms`, `max_output_length`\n * - Always sandbox or validate commands before execution\n * - The `timeout_ms` from the model is only a hint—enforce your own limits\n * - If `max_output_length` exists in the action, always pass it back in the output\n * - Many CLI tools return non-zero exit codes for warnings; still capture stdout/stderr\n */\nexport function shell(options: ShellOptions) {\n  // Wrapper that converts ShellResult to string for LangChain tool compatibility\n  const executeWrapper = async (action: ShellAction): Promise<string> => {\n    const result = await options.execute(action);\n    // Return a JSON string representation for the tool result\n    return JSON.stringify({\n      output: result.output,\n      max_output_length: result.maxOutputLength,\n    });\n  };\n\n  const shellTool = tool(executeWrapper, {\n    name: TOOL_NAME,\n    description:\n      \"Execute shell commands in a managed environment. Commands can be run concurrently.\",\n    schema: ShellActionSchema,\n  });\n\n  shellTool.extras = {\n    ...(shellTool.extras ?? {}),\n    providerToolDefinition: {\n      type: \"shell\",\n    } satisfies ShellTool,\n  };\n\n  return shellTool as DynamicStructuredTool<\n    typeof ShellActionSchema,\n    ShellAction,\n    unknown,\n    string\n  >;\n}\n"],"mappings":";;;;AAYA,MAAa,oBAAoB,EAAE,OAAO;CACxC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,SAAS,qCAAqC;CAC5E,YAAY,EACT,QAAQ,CACR,UAAU,CACV,SAAS,oDAAoD;CAChE,mBAAmB,EAChB,QAAQ,CACR,UAAU,CACV,SACC,oEACD;CACJ,CAAC;AAiFF,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmIlB,SAAgB,MAAM,SAAuB;CAE3C,MAAM,iBAAiB,OAAO,WAAyC;EACrE,MAAM,SAAS,MAAM,QAAQ,QAAQ,OAAO;AAE5C,SAAO,KAAK,UAAU;GACpB,QAAQ,OAAO;GACf,mBAAmB,OAAO;GAC3B,CAAC;;CAGJ,MAAM,YAAY,KAAK,gBAAgB;EACrC,MAAM;EACN,aACE;EACF,QAAQ;EACT,CAAC;AAEF,WAAU,SAAS;EACjB,GAAI,UAAU,UAAU,EAAE;EAC1B,wBAAwB,EACtB,MAAM,SACP;EACF;AAED,QAAO"}

package/dist/tools/webSearch.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"webSearch.cjs","names":["options?: WebSearchOptions"],"sources":["../../src/tools/webSearch.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * User location configuration for geographic search refinement.\n */\nexport interface WebSearchUserLocation {\n  /**\n   * The type of location. Currently only \"approximate\" is supported.\n   */\n  type: \"approximate\";\n  /**\n   * Two-letter ISO country code (e.g., \"US\", \"GB\").\n   * @see https://en.wikipedia.org/wiki/ISO_3166-1\n   */\n  country?: string;\n  /**\n   * City name (e.g., \"San Francisco\", \"London\").\n   */\n  city?: string;\n  /**\n   * Region or state name (e.g., \"California\", \"London\").\n   */\n  region?: string;\n  /**\n   * IANA timezone (e.g., \"America/Los_Angeles\", \"Europe/London\").\n   * @see https://timeapi.io/documentation/iana-timezones\n   */\n  timezone?: string;\n}\n\n/**\n * Domain filtering configuration for web search.\n */\nexport interface WebSearchFilters {\n  /**\n   * Allow-list of up to 100 domains to limit search results.\n   * Omit the HTTP/HTTPS prefix (e.g., \"openai.com\" instead of \"https://openai.com/\").\n   * Includes subdomains automatically.\n   */\n  allowedDomains?: string[];\n}\n\n/**\n * Options for the OpenAI web search tool.\n */\nexport interface WebSearchOptions {\n  /**\n   * Domain filtering configuration.\n   * Limit results to a specific set of up to 100 domains.\n   */\n  filters?: WebSearchFilters;\n  /**\n   * Approximate user location for geographic search refinement.\n   * Not supported for deep research models.\n   */\n  userLocation?: WebSearchUserLocation;\n  /**\n   * High level guidance for the amount of context window space to use for the\n   * search. One of `low`, `medium`, or `high`. `medium` is the default.\n   */\n  search_context_size?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * OpenAI web search tool type for the Responses API.\n */\nexport type WebSearchTool = OpenAIClient.Responses.WebSearchTool;\n\n/**\n * Creates a web search tool that allows OpenAI models to search the web\n * for up-to-date information before generating a response.\n *\n * Web search supports three main types:\n * 1. **Non-reasoning web search**: Quick lookups where the model passes queries\n *    directly to the search tool.\n * 2. **Agentic search with reasoning models**: The model actively manages the\n *    search process, analyzing results and deciding whether to keep searching.\n * 3. **Deep research**: Extended investigations using models like `o3-deep-research`\n *    or `gpt-5` with high reasoning effort.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-web-search | OpenAI Web Search Documentation}\n * @param options - Configuration options for the web search tool\n * @returns A web search tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({\n *   model: \"gpt-4o\",\n * });\n *\n * // Basic usage\n * const response = await model.invoke(\"What was a positive news story from today?\", {\n *   tools: [tools.webSearch()],\n * });\n *\n * // With domain filtering\n * const filteredResponse = await model.invoke(\"Latest AI research news\", {\n *   tools: [tools.webSearch({\n *     filters: {\n *       allowedDomains: [\"arxiv.org\", \"nature.com\", \"science.org\"],\n *     },\n *   })],\n * });\n *\n * // With user location for geographic relevance\n * const localResponse = await model.invoke(\"What are the best restaurants near me?\", {\n *   tools: [tools.webSearch({\n *     userLocation: {\n *       type: \"approximate\",\n *       country: \"US\",\n *       city: \"San Francisco\",\n *       region: \"California\",\n *       timezone: \"America/Los_Angeles\",\n *     },\n *   })],\n * });\n *\n * // Cache-only mode (no live internet access)\n * const cachedResponse = await model.invoke(\"Find information about OpenAI\", {\n *   tools: [tools.webSearch({\n *     externalWebAccess: false,\n *   })],\n * });\n * ```\n */\nexport function webSearch(options?: WebSearchOptions): ServerTool {\n  return {\n    type: \"web_search\",\n    filters: options?.filters?.allowedDomains\n      ? { allowed_domains: options.filters.allowedDomains }\n      : undefined,\n    user_location: options?.userLocation,\n    search_context_size: options?.search_context_size,\n  } satisfies WebSearchTool;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgIA,SAAgB,UAAUA,SAAwC;AAChE,QAAO;EACL,MAAM;EACN,SAAS,SAAS,SAAS,iBACvB,EAAE,iBAAiB,QAAQ,QAAQ,eAAgB,IACnD;EACJ,eAAe,SAAS;EACxB,qBAAqB,SAAS;CAC/B;AACF"}
+{"version":3,"file":"webSearch.cjs","names":[],"sources":["../../src/tools/webSearch.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * User location configuration for geographic search refinement.\n */\nexport interface WebSearchUserLocation {\n  /**\n   * The type of location. Currently only \"approximate\" is supported.\n   */\n  type: \"approximate\";\n  /**\n   * Two-letter ISO country code (e.g., \"US\", \"GB\").\n   * @see https://en.wikipedia.org/wiki/ISO_3166-1\n   */\n  country?: string;\n  /**\n   * City name (e.g., \"San Francisco\", \"London\").\n   */\n  city?: string;\n  /**\n   * Region or state name (e.g., \"California\", \"London\").\n   */\n  region?: string;\n  /**\n   * IANA timezone (e.g., \"America/Los_Angeles\", \"Europe/London\").\n   * @see https://timeapi.io/documentation/iana-timezones\n   */\n  timezone?: string;\n}\n\n/**\n * Domain filtering configuration for web search.\n */\nexport interface WebSearchFilters {\n  /**\n   * Allow-list of up to 100 domains to limit search results.\n   * Omit the HTTP/HTTPS prefix (e.g., \"openai.com\" instead of \"https://openai.com/\").\n   * Includes subdomains automatically.\n   */\n  allowedDomains?: string[];\n}\n\n/**\n * Options for the OpenAI web search tool.\n */\nexport interface WebSearchOptions {\n  /**\n   * Domain filtering configuration.\n   * Limit results to a specific set of up to 100 domains.\n   */\n  filters?: WebSearchFilters;\n  /**\n   * Approximate user location for geographic search refinement.\n   * Not supported for deep research models.\n   */\n  userLocation?: WebSearchUserLocation;\n  /**\n   * High level guidance for the amount of context window space to use for the\n   * search. One of `low`, `medium`, or `high`. `medium` is the default.\n   */\n  search_context_size?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * OpenAI web search tool type for the Responses API.\n */\nexport type WebSearchTool = OpenAIClient.Responses.WebSearchTool;\n\n/**\n * Creates a web search tool that allows OpenAI models to search the web\n * for up-to-date information before generating a response.\n *\n * Web search supports three main types:\n * 1. **Non-reasoning web search**: Quick lookups where the model passes queries\n *    directly to the search tool.\n * 2. **Agentic search with reasoning models**: The model actively manages the\n *    search process, analyzing results and deciding whether to keep searching.\n * 3. **Deep research**: Extended investigations using models like `o3-deep-research`\n *    or `gpt-5` with high reasoning effort.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-web-search | OpenAI Web Search Documentation}\n * @param options - Configuration options for the web search tool\n * @returns A web search tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({\n *   model: \"gpt-4o\",\n * });\n *\n * // Basic usage\n * const response = await model.invoke(\"What was a positive news story from today?\", {\n *   tools: [tools.webSearch()],\n * });\n *\n * // With domain filtering\n * const filteredResponse = await model.invoke(\"Latest AI research news\", {\n *   tools: [tools.webSearch({\n *     filters: {\n *       allowedDomains: [\"arxiv.org\", \"nature.com\", \"science.org\"],\n *     },\n *   })],\n * });\n *\n * // With user location for geographic relevance\n * const localResponse = await model.invoke(\"What are the best restaurants near me?\", {\n *   tools: [tools.webSearch({\n *     userLocation: {\n *       type: \"approximate\",\n *       country: \"US\",\n *       city: \"San Francisco\",\n *       region: \"California\",\n *       timezone: \"America/Los_Angeles\",\n *     },\n *   })],\n * });\n *\n * // Cache-only mode (no live internet access)\n * const cachedResponse = await model.invoke(\"Find information about OpenAI\", {\n *   tools: [tools.webSearch({\n *     externalWebAccess: false,\n *   })],\n * });\n * ```\n */\nexport function webSearch(options?: WebSearchOptions): ServerTool {\n  return {\n    type: \"web_search\",\n    filters: options?.filters?.allowedDomains\n      ? { allowed_domains: options.filters.allowedDomains }\n      : undefined,\n    user_location: options?.userLocation,\n    search_context_size: options?.search_context_size,\n  } satisfies WebSearchTool;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgIA,SAAgB,UAAU,SAAwC;AAChE,QAAO;EACL,MAAM;EACN,SAAS,SAAS,SAAS,iBACvB,EAAE,iBAAiB,QAAQ,QAAQ,gBAAgB,GACnD;EACJ,eAAe,SAAS;EACxB,qBAAqB,SAAS;EAC/B"}

package/dist/tools/webSearch.d.cts

@@ -2,7 +2,6 @@ import { OpenAI as OpenAI$1 } from "openai";
 import { ServerTool } from "@langchain/core/tools";
 
 //#region src/tools/webSearch.d.ts
-
 /**
  * User location configuration for geographic search refinement.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"webSearch.d.cts","names":["OpenAI","OpenAIClient","ServerTool","WebSearchUserLocation","WebSearchFilters","WebSearchOptions","WebSearchTool","Responses","webSearch"],"sources":["../../src/tools/webSearch.d.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n/**\n * User location configuration for geographic search refinement.\n */\nexport interface WebSearchUserLocation {\n    /**\n     * The type of location. Currently only \"approximate\" is supported.\n     */\n    type: \"approximate\";\n    /**\n     * Two-letter ISO country code (e.g., \"US\", \"GB\").\n     * @see https://en.wikipedia.org/wiki/ISO_3166-1\n     */\n    country?: string;\n    /**\n     * City name (e.g., \"San Francisco\", \"London\").\n     */\n    city?: string;\n    /**\n     * Region or state name (e.g., \"California\", \"London\").\n     */\n    region?: string;\n    /**\n     * IANA timezone (e.g., \"America/Los_Angeles\", \"Europe/London\").\n     * @see https://timeapi.io/documentation/iana-timezones\n     */\n    timezone?: string;\n}\n/**\n * Domain filtering configuration for web search.\n */\nexport interface WebSearchFilters {\n    /**\n     * Allow-list of up to 100 domains to limit search results.\n     * Omit the HTTP/HTTPS prefix (e.g., \"openai.com\" instead of \"https://openai.com/\").\n     * Includes subdomains automatically.\n     */\n    allowedDomains?: string[];\n}\n/**\n * Options for the OpenAI web search tool.\n */\nexport interface WebSearchOptions {\n    /**\n     * Domain filtering configuration.\n     * Limit results to a specific set of up to 100 domains.\n     */\n    filters?: WebSearchFilters;\n    /**\n     * Approximate user location for geographic search refinement.\n     * Not supported for deep research models.\n     */\n    userLocation?: WebSearchUserLocation;\n    /**\n     * High level guidance for the amount of context window space to use for the\n     * search. One of `low`, `medium`, or `high`. `medium` is the default.\n     */\n    search_context_size?: \"low\" | \"medium\" | \"high\";\n}\n/**\n * OpenAI web search tool type for the Responses API.\n */\nexport type WebSearchTool = OpenAIClient.Responses.WebSearchTool;\n/**\n * Creates a web search tool that allows OpenAI models to search the web\n * for up-to-date information before generating a response.\n *\n * Web search supports three main types:\n * 1. **Non-reasoning web search**: Quick lookups where the model passes queries\n *    directly to the search tool.\n * 2. **Agentic search with reasoning models**: The model actively manages the\n *    search process, analyzing results and deciding whether to keep searching.\n * 3. **Deep research**: Extended investigations using models like `o3-deep-research`\n *    or `gpt-5` with high reasoning effort.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-web-search | OpenAI Web Search Documentation}\n * @param options - Configuration options for the web search tool\n * @returns A web search tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({\n *   model: \"gpt-4o\",\n * });\n *\n * // Basic usage\n * const response = await model.invoke(\"What was a positive news story from today?\", {\n *   tools: [tools.webSearch()],\n * });\n *\n * // With domain filtering\n * const filteredResponse = await model.invoke(\"Latest AI research news\", {\n *   tools: [tools.webSearch({\n *     filters: {\n *       allowedDomains: [\"arxiv.org\", \"nature.com\", \"science.org\"],\n *     },\n *   })],\n * });\n *\n * // With user location for geographic relevance\n * const localResponse = await model.invoke(\"What are the best restaurants near me?\", {\n *   tools: [tools.webSearch({\n *     userLocation: {\n *       type: \"approximate\",\n *       country: \"US\",\n *       city: \"San Francisco\",\n *       region: \"California\",\n *       timezone: \"America/Los_Angeles\",\n *     },\n *   })],\n * });\n *\n * // Cache-only mode (no live internet access)\n * const cachedResponse = await model.invoke(\"Find information about OpenAI\", {\n *   tools: [tools.webSearch({\n *     externalWebAccess: false,\n *   })],\n * });\n * ```\n */\nexport declare function webSearch(options?: WebSearchOptions): ServerTool;\n//# sourceMappingURL=webSearch.d.ts.map"],"mappings":";;;;;;;AAKA;AA2BiBI,UA3BAD,qBAAAA,CA2BgB;EAWhBE;AAoBjB;AA4DA;;;;;;;;;;;;;;;;;;;;;;;;UA3FiBD,gBAAAA;;;;;;;;;;;UAWAC,gBAAAA;;;;;YAKHD;;;;;iBAKKD;;;;;;;;;;KAUPG,aAAAA,GAAgBL,QAAAA,CAAaM,SAAAA,CAAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4D3BE,SAAAA,WAAoBH,mBAAmBH"}
+{"version":3,"file":"webSearch.d.cts","names":[],"sources":["../../src/tools/webSearch.ts"],"mappings":";;;;;;AAMA;UAAiB,qBAAA;;;;EAIf,IAAA;EASA;;;;EAJA,OAAA;EAmBe;;;EAff,IAAA;EAqBc;AAMhB;;EAvBE,MAAA;EAiCoC;;;;EA5BpC,QAAA;AAAA;;;AAuCF;UAjCiB,gBAAA;;;;;;EAMf,cAAA;AAAA;AAwFF;;;AAAA,UAlFiB,gBAAA;EAkFmB;;;;EA7ElC,OAAA,GAAU,gBAAA;;;;;EAKV,YAAA,GAAe,qBAAA;;;;;EAKf,mBAAA;AAAA;;;;KAMU,aAAA,GAAgB,QAAA,CAAa,SAAA,CAAU,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DnC,SAAA,CAAU,OAAA,GAAU,gBAAA,GAAmB,UAAA"}

package/dist/tools/webSearch.d.ts

@@ -2,7 +2,6 @@ import { OpenAI as OpenAI$1 } from "openai";
 import { ServerTool } from "@langchain/core/tools";
 
 //#region src/tools/webSearch.d.ts
-
 /**
  * User location configuration for geographic search refinement.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"webSearch.d.ts","names":["OpenAI","OpenAIClient","ServerTool","WebSearchUserLocation","WebSearchFilters","WebSearchOptions","WebSearchTool","Responses","webSearch"],"sources":["../../src/tools/webSearch.d.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n/**\n * User location configuration for geographic search refinement.\n */\nexport interface WebSearchUserLocation {\n    /**\n     * The type of location. Currently only \"approximate\" is supported.\n     */\n    type: \"approximate\";\n    /**\n     * Two-letter ISO country code (e.g., \"US\", \"GB\").\n     * @see https://en.wikipedia.org/wiki/ISO_3166-1\n     */\n    country?: string;\n    /**\n     * City name (e.g., \"San Francisco\", \"London\").\n     */\n    city?: string;\n    /**\n     * Region or state name (e.g., \"California\", \"London\").\n     */\n    region?: string;\n    /**\n     * IANA timezone (e.g., \"America/Los_Angeles\", \"Europe/London\").\n     * @see https://timeapi.io/documentation/iana-timezones\n     */\n    timezone?: string;\n}\n/**\n * Domain filtering configuration for web search.\n */\nexport interface WebSearchFilters {\n    /**\n     * Allow-list of up to 100 domains to limit search results.\n     * Omit the HTTP/HTTPS prefix (e.g., \"openai.com\" instead of \"https://openai.com/\").\n     * Includes subdomains automatically.\n     */\n    allowedDomains?: string[];\n}\n/**\n * Options for the OpenAI web search tool.\n */\nexport interface WebSearchOptions {\n    /**\n     * Domain filtering configuration.\n     * Limit results to a specific set of up to 100 domains.\n     */\n    filters?: WebSearchFilters;\n    /**\n     * Approximate user location for geographic search refinement.\n     * Not supported for deep research models.\n     */\n    userLocation?: WebSearchUserLocation;\n    /**\n     * High level guidance for the amount of context window space to use for the\n     * search. One of `low`, `medium`, or `high`. `medium` is the default.\n     */\n    search_context_size?: \"low\" | \"medium\" | \"high\";\n}\n/**\n * OpenAI web search tool type for the Responses API.\n */\nexport type WebSearchTool = OpenAIClient.Responses.WebSearchTool;\n/**\n * Creates a web search tool that allows OpenAI models to search the web\n * for up-to-date information before generating a response.\n *\n * Web search supports three main types:\n * 1. **Non-reasoning web search**: Quick lookups where the model passes queries\n *    directly to the search tool.\n * 2. **Agentic search with reasoning models**: The model actively manages the\n *    search process, analyzing results and deciding whether to keep searching.\n * 3. **Deep research**: Extended investigations using models like `o3-deep-research`\n *    or `gpt-5` with high reasoning effort.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-web-search | OpenAI Web Search Documentation}\n * @param options - Configuration options for the web search tool\n * @returns A web search tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({\n *   model: \"gpt-4o\",\n * });\n *\n * // Basic usage\n * const response = await model.invoke(\"What was a positive news story from today?\", {\n *   tools: [tools.webSearch()],\n * });\n *\n * // With domain filtering\n * const filteredResponse = await model.invoke(\"Latest AI research news\", {\n *   tools: [tools.webSearch({\n *     filters: {\n *       allowedDomains: [\"arxiv.org\", \"nature.com\", \"science.org\"],\n *     },\n *   })],\n * });\n *\n * // With user location for geographic relevance\n * const localResponse = await model.invoke(\"What are the best restaurants near me?\", {\n *   tools: [tools.webSearch({\n *     userLocation: {\n *       type: \"approximate\",\n *       country: \"US\",\n *       city: \"San Francisco\",\n *       region: \"California\",\n *       timezone: \"America/Los_Angeles\",\n *     },\n *   })],\n * });\n *\n * // Cache-only mode (no live internet access)\n * const cachedResponse = await model.invoke(\"Find information about OpenAI\", {\n *   tools: [tools.webSearch({\n *     externalWebAccess: false,\n *   })],\n * });\n * ```\n */\nexport declare function webSearch(options?: WebSearchOptions): ServerTool;\n//# sourceMappingURL=webSearch.d.ts.map"],"mappings":";;;;;;;AAKA;AA2BiBI,UA3BAD,qBAAAA,CA2BgB;EAWhBE;AAoBjB;AA4DA;;;;;;;;;;;;;;;;;;;;;;;;UA3FiBD,gBAAAA;;;;;;;;;;;UAWAC,gBAAAA;;;;;YAKHD;;;;;iBAKKD;;;;;;;;;;KAUPG,aAAAA,GAAgBL,QAAAA,CAAaM,SAAAA,CAAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4D3BE,SAAAA,WAAoBH,mBAAmBH"}
+{"version":3,"file":"webSearch.d.ts","names":[],"sources":["../../src/tools/webSearch.ts"],"mappings":";;;;;;AAMA;UAAiB,qBAAA;;;;EAIf,IAAA;EASA;;;;EAJA,OAAA;EAmBe;;;EAff,IAAA;EAqBc;AAMhB;;EAvBE,MAAA;EAiCoC;;;;EA5BpC,QAAA;AAAA;;;AAuCF;UAjCiB,gBAAA;;;;;;EAMf,cAAA;AAAA;AAwFF;;;AAAA,UAlFiB,gBAAA;EAkFmB;;;;EA7ElC,OAAA,GAAU,gBAAA;;;;;EAKV,YAAA,GAAe,qBAAA;;;;;EAKf,mBAAA;AAAA;;;;KAMU,aAAA,GAAgB,QAAA,CAAa,SAAA,CAAU,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DnC,SAAA,CAAU,OAAA,GAAU,gBAAA,GAAmB,UAAA"}

package/dist/tools/webSearch.js.map

@@ -1 +1 @@
-{"version":3,"file":"webSearch.js","names":["options?: WebSearchOptions"],"sources":["../../src/tools/webSearch.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * User location configuration for geographic search refinement.\n */\nexport interface WebSearchUserLocation {\n  /**\n   * The type of location. Currently only \"approximate\" is supported.\n   */\n  type: \"approximate\";\n  /**\n   * Two-letter ISO country code (e.g., \"US\", \"GB\").\n   * @see https://en.wikipedia.org/wiki/ISO_3166-1\n   */\n  country?: string;\n  /**\n   * City name (e.g., \"San Francisco\", \"London\").\n   */\n  city?: string;\n  /**\n   * Region or state name (e.g., \"California\", \"London\").\n   */\n  region?: string;\n  /**\n   * IANA timezone (e.g., \"America/Los_Angeles\", \"Europe/London\").\n   * @see https://timeapi.io/documentation/iana-timezones\n   */\n  timezone?: string;\n}\n\n/**\n * Domain filtering configuration for web search.\n */\nexport interface WebSearchFilters {\n  /**\n   * Allow-list of up to 100 domains to limit search results.\n   * Omit the HTTP/HTTPS prefix (e.g., \"openai.com\" instead of \"https://openai.com/\").\n   * Includes subdomains automatically.\n   */\n  allowedDomains?: string[];\n}\n\n/**\n * Options for the OpenAI web search tool.\n */\nexport interface WebSearchOptions {\n  /**\n   * Domain filtering configuration.\n   * Limit results to a specific set of up to 100 domains.\n   */\n  filters?: WebSearchFilters;\n  /**\n   * Approximate user location for geographic search refinement.\n   * Not supported for deep research models.\n   */\n  userLocation?: WebSearchUserLocation;\n  /**\n   * High level guidance for the amount of context window space to use for the\n   * search. One of `low`, `medium`, or `high`. `medium` is the default.\n   */\n  search_context_size?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * OpenAI web search tool type for the Responses API.\n */\nexport type WebSearchTool = OpenAIClient.Responses.WebSearchTool;\n\n/**\n * Creates a web search tool that allows OpenAI models to search the web\n * for up-to-date information before generating a response.\n *\n * Web search supports three main types:\n * 1. **Non-reasoning web search**: Quick lookups where the model passes queries\n *    directly to the search tool.\n * 2. **Agentic search with reasoning models**: The model actively manages the\n *    search process, analyzing results and deciding whether to keep searching.\n * 3. **Deep research**: Extended investigations using models like `o3-deep-research`\n *    or `gpt-5` with high reasoning effort.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-web-search | OpenAI Web Search Documentation}\n * @param options - Configuration options for the web search tool\n * @returns A web search tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({\n *   model: \"gpt-4o\",\n * });\n *\n * // Basic usage\n * const response = await model.invoke(\"What was a positive news story from today?\", {\n *   tools: [tools.webSearch()],\n * });\n *\n * // With domain filtering\n * const filteredResponse = await model.invoke(\"Latest AI research news\", {\n *   tools: [tools.webSearch({\n *     filters: {\n *       allowedDomains: [\"arxiv.org\", \"nature.com\", \"science.org\"],\n *     },\n *   })],\n * });\n *\n * // With user location for geographic relevance\n * const localResponse = await model.invoke(\"What are the best restaurants near me?\", {\n *   tools: [tools.webSearch({\n *     userLocation: {\n *       type: \"approximate\",\n *       country: \"US\",\n *       city: \"San Francisco\",\n *       region: \"California\",\n *       timezone: \"America/Los_Angeles\",\n *     },\n *   })],\n * });\n *\n * // Cache-only mode (no live internet access)\n * const cachedResponse = await model.invoke(\"Find information about OpenAI\", {\n *   tools: [tools.webSearch({\n *     externalWebAccess: false,\n *   })],\n * });\n * ```\n */\nexport function webSearch(options?: WebSearchOptions): ServerTool {\n  return {\n    type: \"web_search\",\n    filters: options?.filters?.allowedDomains\n      ? { allowed_domains: options.filters.allowedDomains }\n      : undefined,\n    user_location: options?.userLocation,\n    search_context_size: options?.search_context_size,\n  } satisfies WebSearchTool;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgIA,SAAgB,UAAUA,SAAwC;AAChE,QAAO;EACL,MAAM;EACN,SAAS,SAAS,SAAS,iBACvB,EAAE,iBAAiB,QAAQ,QAAQ,eAAgB,IACnD;EACJ,eAAe,SAAS;EACxB,qBAAqB,SAAS;CAC/B;AACF"}
+{"version":3,"file":"webSearch.js","names":[],"sources":["../../src/tools/webSearch.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * User location configuration for geographic search refinement.\n */\nexport interface WebSearchUserLocation {\n  /**\n   * The type of location. Currently only \"approximate\" is supported.\n   */\n  type: \"approximate\";\n  /**\n   * Two-letter ISO country code (e.g., \"US\", \"GB\").\n   * @see https://en.wikipedia.org/wiki/ISO_3166-1\n   */\n  country?: string;\n  /**\n   * City name (e.g., \"San Francisco\", \"London\").\n   */\n  city?: string;\n  /**\n   * Region or state name (e.g., \"California\", \"London\").\n   */\n  region?: string;\n  /**\n   * IANA timezone (e.g., \"America/Los_Angeles\", \"Europe/London\").\n   * @see https://timeapi.io/documentation/iana-timezones\n   */\n  timezone?: string;\n}\n\n/**\n * Domain filtering configuration for web search.\n */\nexport interface WebSearchFilters {\n  /**\n   * Allow-list of up to 100 domains to limit search results.\n   * Omit the HTTP/HTTPS prefix (e.g., \"openai.com\" instead of \"https://openai.com/\").\n   * Includes subdomains automatically.\n   */\n  allowedDomains?: string[];\n}\n\n/**\n * Options for the OpenAI web search tool.\n */\nexport interface WebSearchOptions {\n  /**\n   * Domain filtering configuration.\n   * Limit results to a specific set of up to 100 domains.\n   */\n  filters?: WebSearchFilters;\n  /**\n   * Approximate user location for geographic search refinement.\n   * Not supported for deep research models.\n   */\n  userLocation?: WebSearchUserLocation;\n  /**\n   * High level guidance for the amount of context window space to use for the\n   * search. One of `low`, `medium`, or `high`. `medium` is the default.\n   */\n  search_context_size?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * OpenAI web search tool type for the Responses API.\n */\nexport type WebSearchTool = OpenAIClient.Responses.WebSearchTool;\n\n/**\n * Creates a web search tool that allows OpenAI models to search the web\n * for up-to-date information before generating a response.\n *\n * Web search supports three main types:\n * 1. **Non-reasoning web search**: Quick lookups where the model passes queries\n *    directly to the search tool.\n * 2. **Agentic search with reasoning models**: The model actively manages the\n *    search process, analyzing results and deciding whether to keep searching.\n * 3. **Deep research**: Extended investigations using models like `o3-deep-research`\n *    or `gpt-5` with high reasoning effort.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-web-search | OpenAI Web Search Documentation}\n * @param options - Configuration options for the web search tool\n * @returns A web search tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({\n *   model: \"gpt-4o\",\n * });\n *\n * // Basic usage\n * const response = await model.invoke(\"What was a positive news story from today?\", {\n *   tools: [tools.webSearch()],\n * });\n *\n * // With domain filtering\n * const filteredResponse = await model.invoke(\"Latest AI research news\", {\n *   tools: [tools.webSearch({\n *     filters: {\n *       allowedDomains: [\"arxiv.org\", \"nature.com\", \"science.org\"],\n *     },\n *   })],\n * });\n *\n * // With user location for geographic relevance\n * const localResponse = await model.invoke(\"What are the best restaurants near me?\", {\n *   tools: [tools.webSearch({\n *     userLocation: {\n *       type: \"approximate\",\n *       country: \"US\",\n *       city: \"San Francisco\",\n *       region: \"California\",\n *       timezone: \"America/Los_Angeles\",\n *     },\n *   })],\n * });\n *\n * // Cache-only mode (no live internet access)\n * const cachedResponse = await model.invoke(\"Find information about OpenAI\", {\n *   tools: [tools.webSearch({\n *     externalWebAccess: false,\n *   })],\n * });\n * ```\n */\nexport function webSearch(options?: WebSearchOptions): ServerTool {\n  return {\n    type: \"web_search\",\n    filters: options?.filters?.allowedDomains\n      ? { allowed_domains: options.filters.allowedDomains }\n      : undefined,\n    user_location: options?.userLocation,\n    search_context_size: options?.search_context_size,\n  } satisfies WebSearchTool;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgIA,SAAgB,UAAU,SAAwC;AAChE,QAAO;EACL,MAAM;EACN,SAAS,SAAS,SAAS,iBACvB,EAAE,iBAAiB,QAAQ,QAAQ,gBAAgB,GACnD;EACJ,eAAe,SAAS;EACxB,qBAAqB,SAAS;EAC/B"}

package/dist/types.d.cts

@@ -5,7 +5,6 @@ import { ResponseFormatJSONObject, ResponseFormatJSONSchema, ResponseFormatText,
 import { TiktokenModel } from "js-tiktoken/lite";
 
 //#region src/types.d.ts
-
 /**
  * @see https://platform.openai.com/docs/models
  */