sdk: Add env parameter to client and run(), pass through to run_terminal_command impl

Author: jahooma

sdk/src/client.ts

@@ -45,6 +45,7 @@ export class CodebuffClient {
    * @param agentDefinitions - (Optional) Array of custom agent definitions. Each object should satisfy the AgentDefinition type. You can input the agent's id field into the agent parameter to run that agent.
    * @param customToolDefinitions - (Optional) Array of custom tool definitions that extend the agent's capabilities. Each tool definition includes a name, Zod schema for input validation, and a handler function. These tools can be called by the agent during execution.
    * @param maxAgentSteps - (Optional) Maximum number of steps the agent can take before stopping. Use this as a safety measure in case your agent starts going off the rails. A reasonable number is around 20.
+   * @param env - (Optional) Environment variables to pass to terminal commands executed by the agent. These will be merged with process.env, with the custom values taking precedence. Can also be provided in individual run() calls to override.
    *
    * @returns A Promise that resolves to a RunState JSON object which you can pass to a subsequent run() call to continue the run. Use result.output to get the agent's output.
    */

sdk/src/run.ts

@@ -53,6 +53,7 @@ export type CodebuffClientOptions = {
   knowledgeFiles?: Record<string, string>
   agentDefinitions?: AgentDefinition[]
   maxAgentSteps?: number
+  env?: Record<string, string>
 
   handleEvent?: (event: PrintModeEvent) => void | Promise<void>
   handleStreamChunk?: (
@@ -111,6 +112,7 @@ export async function run({
   knowledgeFiles,
   agentDefinitions,
   maxAgentSteps = MAX_AGENT_STEPS_DEFAULT,
+  env,
 
   handleEvent,
   handleStreamChunk,
@@ -227,6 +229,7 @@ export async function run({
           : {},
         cwd,
         fs,
+        env,
       })
     },
     requestMcpToolData: async ({ mcpConfig, toolNames }) => {
@@ -421,12 +424,14 @@ async function handleToolCall({
   customToolDefinitions,
   cwd,
   fs,
+  env,
 }: {
   action: ServerAction<'tool-call-request'>
   overrides: NonNullable<CodebuffClientOptions['overrideTools']>
   customToolDefinitions: Record<string, CustomToolDefinition>
   cwd?: string
   fs: CodebuffFileSystem
+  env?: Record<string, string>
 }): ReturnType<WebSocketHandler['handleToolCall']> {
   const toolName = action.toolName
   const input = action.input
@@ -468,6 +473,7 @@ async function handleToolCall({
       result = await runTerminalCommand({
         ...input,
         cwd: path.resolve(resolvedCwd, input.cwd ?? '.'),
+        env,
       } as Parameters<typeof runTerminalCommand>[0])
     } else if (toolName === 'code_search') {
       result = await codeSearch({

sdk/src/tools/run-terminal-command.ts

@@ -15,11 +15,13 @@ export function runTerminalCommand({
   process_type,
   cwd,
   timeout_seconds,
+  env,
 }: {
   command: string
   process_type: 'SYNC' | 'BACKGROUND'
   cwd: string
   timeout_seconds: number
+  env?: Record<string, string>
 }): Promise<CodebuffToolOutput<'run_terminal_command'>> {
   if (process_type === 'BACKGROUND') {
     throw new Error('BACKGROUND process_type not implemented')
@@ -37,6 +39,7 @@ export function runTerminalCommand({
       cwd: resolvedCwd,
       env: {
         ...process.env,
+        ...(env ?? {}),
         FORCE_COLOR: '1',
         CLICOLOR: '1',
         CLICOLOR_FORCE: '1',