feat: add sandbox agents with clearer PTY Python validation (#1221)

Author: seratch

packages/agents-core/src/sandbox/sandboxes/shared/pty.ts

@@ -1,7 +1,20 @@
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import {
+  spawn,
+  spawnSync,
+  type ChildProcessWithoutNullStreams,
+} from 'node:child_process';
+import { SandboxConfigurationError } from '../../errors';
 
 const PTY_BRIDGE_UID_ENV = '__OPENAI_AGENTS_PTY_UID';
 const PTY_BRIDGE_GID_ENV = '__OPENAI_AGENTS_PTY_GID';
+const PTY_BRIDGE_PYTHON_CHECK_SCRIPT = String.raw`
+import pty
+import select
+import signal
+import sys
+
+sys.exit(0 if sys.version_info[0] >= 3 else 1)
+`;
 const PTY_BRIDGE_SCRIPT = String.raw`
 import errno
 import os
@@ -95,6 +108,8 @@ except ChildProcessError:
 sys.exit(exit_status)
 `;
 
+const checkedPtyBridgePythonExecutables = new Set<string>();
+
 type PseudoTerminalSpawnOptions = {
   cwd?: string;
   env?: NodeJS.ProcessEnv;
@@ -108,6 +123,12 @@ export function spawnInPseudoTerminal(
   options: PseudoTerminalSpawnOptions = {},
 ): ChildProcessWithoutNullStreams {
   const env = { ...(options.env ?? process.env) };
+  const pythonExecutable = process.env.OPENAI_AGENTS_PYTHON ?? 'python3';
+  assertPtyBridgePythonAvailable(pythonExecutable, {
+    cwd: options.cwd,
+    env,
+  });
+
   if (typeof options.uid === 'number') {
     env[PTY_BRIDGE_UID_ENV] = String(options.uid);
   }
@@ -116,7 +137,7 @@ export function spawnInPseudoTerminal(
   }
 
   return spawn(
-    process.env.OPENAI_AGENTS_PYTHON ?? 'python3',
+    pythonExecutable,
     ['-c', PTY_BRIDGE_SCRIPT, executable, ...args],
     {
       cwd: options.cwd,
@@ -125,3 +146,42 @@ export function spawnInPseudoTerminal(
     },
   );
 }
+
+function assertPtyBridgePythonAvailable(
+  pythonExecutable: string,
+  options: {
+    cwd?: string;
+    env: NodeJS.ProcessEnv;
+  },
+): void {
+  const cacheKey = `${pythonExecutable}\0${options.cwd ?? ''}\0${options.env.PATH ?? ''}`;
+  if (checkedPtyBridgePythonExecutables.has(cacheKey)) {
+    return;
+  }
+
+  const result = spawnSync(
+    pythonExecutable,
+    ['-c', PTY_BRIDGE_PYTHON_CHECK_SCRIPT],
+    {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: 'pipe',
+    },
+  );
+  if (result.error || result.status !== 0) {
+    throw new SandboxConfigurationError(
+      'PTY support requires Python 3. Install python3 or set OPENAI_AGENTS_PYTHON to a Python 3 executable.',
+      {
+        pythonExecutable,
+        cwd: options.cwd,
+        path: options.env.PATH,
+        status: result.status,
+        signal: result.signal,
+        error: result.error?.message,
+        stderr: result.stderr?.toString('utf8').trim() ?? '',
+      },
+    );
+  }
+
+  checkedPtyBridgePythonExecutables.add(cacheKey);
+}

packages/agents-core/test/sandboxes/unixLocal.test.ts

@@ -1043,6 +1043,83 @@ describe('UnixLocalSandboxClient', () => {
     expect(output).not.toContain('tty no');
   });
 
+  it('fails tty commands clearly when the Python PTY bridge is unavailable', async () => {
+    const originalPython = process.env.OPENAI_AGENTS_PYTHON;
+    const missingPython = join(rootDir, 'missing-python3');
+    process.env.OPENAI_AGENTS_PYTHON = missingPython;
+
+    try {
+      const client = new UnixLocalSandboxClient({
+        workspaceBaseDir: rootDir,
+      });
+      const session = await client.create(new Manifest());
+
+      await expect(
+        session.execCommand({
+          cmd: 'printf "hello\\n"',
+          shell: '/bin/sh',
+          login: false,
+          tty: true,
+          yieldTimeMs: 1_000,
+        }),
+      ).rejects.toMatchObject({
+        code: 'configuration_error',
+        message:
+          'PTY support requires Python 3. Install python3 or set OPENAI_AGENTS_PYTHON to a Python 3 executable.',
+        details: expect.objectContaining({
+          pythonExecutable: missingPython,
+        }),
+      });
+    } finally {
+      if (originalPython === undefined) {
+        delete process.env.OPENAI_AGENTS_PYTHON;
+      } else {
+        process.env.OPENAI_AGENTS_PYTHON = originalPython;
+      }
+    }
+  });
+
+  it('checks relative PTY Python executables from the command cwd', async () => {
+    const originalPython = process.env.OPENAI_AGENTS_PYTHON;
+    const pythonPath = await whichPython();
+
+    try {
+      const client = new UnixLocalSandboxClient({
+        workspaceBaseDir: rootDir,
+      });
+      const session = await client.create(new Manifest());
+      await symlink(
+        pythonPath,
+        join(session.state.workspaceRootPath, 'python3'),
+      );
+      process.env.OPENAI_AGENTS_PYTHON = './python3';
+
+      const output = await session.execCommand({
+        cmd: 'test -t 0 && printf "tty yes\\n" || printf "tty no\\n"',
+        shell: '/bin/sh',
+        login: false,
+        tty: true,
+        yieldTimeMs: 1_000,
+      });
+      const finalOutput = await collectActiveCommandOutput(
+        {
+          writeStdin: (args) => session.writeStdin(args),
+        },
+        output,
+      );
+
+      expect(finalOutput).toContain('Process exited with code 0');
+      expect(finalOutput).toContain('tty yes');
+      expect(finalOutput).not.toContain('tty no');
+    } finally {
+      if (originalPython === undefined) {
+        delete process.env.OPENAI_AGENTS_PYTHON;
+      } else {
+        process.env.OPENAI_AGENTS_PYTHON = originalPython;
+      }
+    }
+  });
+
   it('accepts absolute sandbox paths when the manifest root is slash', async () => {
     const client = new UnixLocalSandboxClient({
       workspaceBaseDir: rootDir,
@@ -2160,6 +2237,11 @@ async function writeUntilExit(
   return combinedOutput;
 }
 
+async function whichPython(): Promise<string> {
+  const { stdout } = await execFileAsync('which', ['python3']);
+  return stdout.trim();
+}
+
 async function collectActiveCommandOutput(
   session: {
     writeStdin(args: {