fix(agents-core): preserve legacy ShellTool typing and strict shell pending statuses (#952)

Author: seratch

.changeset/few-comics-help.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-core': patch
+---
+
+fix: preserve ShellTool compatibility while keeping factory environment and hosted polling

packages/agents-core/src/runner/modelOutputs.ts

@@ -108,8 +108,24 @@ function resolveFunctionOrHandoff(
   return { type: 'function', tool: functionTool };
 }
 
+type ShellCallStatus = 'in_progress' | 'completed' | 'incomplete';
+
+function parseShellCallStatus(status: unknown): ShellCallStatus | undefined {
+  if (
+    status === 'in_progress' ||
+    status === 'completed' ||
+    status === 'incomplete'
+  ) {
+    return status;
+  }
+  return undefined;
+}
+
 function isShellCallPendingStatus(status: unknown): boolean {
-  return status !== 'completed' && status !== 'incomplete';
+  if (typeof status === 'undefined') {
+    return true;
+  }
+  return parseShellCallStatus(status) === 'in_progress';
 }
 
 function hasPendingShellOutputStatus(

packages/agents-core/src/tool.ts

@@ -575,10 +575,6 @@ type ShellToolBase = {
    * Public name exposed to the model. Defaults to `shell`.
    */
   name: string;
-  /**
-   * The execution environment for the shell tool.
-   */
-  environment: ShellToolEnvironment;
   /**
    * Predicate determining whether this shell action requires approval.
    */
@@ -591,13 +587,21 @@ type ShellToolBase = {
 };
 
 type LocalShellTool = ShellToolBase & {
-  environment: ShellToolLocalEnvironment;
+  /**
+   * Optional for backward compatibility with direct `ShellTool` literals.
+   * When omitted, local mode is assumed.
+   */
+  environment?: ShellToolLocalEnvironment;
   /**
    * The shell implementation to execute commands in local mode.
    */
   shell: Shell;
 };
 
+type NormalizedLocalShellTool = Omit<LocalShellTool, 'environment'> & {
+  environment: ShellToolLocalEnvironment;
+};
+
 type HostedShellTool = ShellToolBase & {
   environment: ShellToolHostedEnvironment;
   /**
@@ -721,11 +725,13 @@ function normalizeShellToolEnvironment(
   };
 }
 
-export function shellTool(options: LocalShellToolOptions): ShellTool;
-export function shellTool(options: HostedShellToolOptions): ShellTool;
+export function shellTool(
+  options: LocalShellToolOptions,
+): NormalizedLocalShellTool;
+export function shellTool(options: HostedShellToolOptions): HostedShellTool;
 export function shellTool(
   options: LocalShellToolOptions | HostedShellToolOptions,
-): ShellTool {
+): NormalizedLocalShellTool | HostedShellTool {
   const environment = normalizeShellToolEnvironment(options.environment);
   const needsApproval: ShellApprovalFunction =
     typeof options.needsApproval === 'function'

packages/agents-core/test/runner/modelOutputs.test.ts

@@ -160,6 +160,29 @@ describe('processModelResponse', () => {
     expect(result.hasToolsOrApprovalsToRun()).toBe(true);
   });
 
+  it('keeps hosted shell calls pending when status is omitted', () => {
+    const shellCall: protocol.ShellCallItem = {
+      type: 'shell_call',
+      callId: 'call_shell',
+      action: { commands: ['echo hi'] },
+    };
+    const modelResponse: ModelResponse = {
+      output: [shellCall],
+      usage: new Usage(),
+    };
+
+    const shell = shellTool({
+      environment: { type: 'container_auto' },
+    });
+    const result = processModelResponse(modelResponse, TEST_AGENT, [shell], []);
+
+    expect(result.newItems).toHaveLength(1);
+    expect(result.newItems[0]).toBeInstanceOf(ToolCallItem);
+    expect(result.shellActions).toHaveLength(0);
+    expect(result.toolsUsed).toEqual(['shell']);
+    expect(result.hasToolsOrApprovalsToRun()).toBe(true);
+  });
+
   it('does not keep hosted shell calls pending when incomplete', () => {
     const shellCall: protocol.ShellCallItem = {
       type: 'shell_call',
@@ -184,6 +207,30 @@ describe('processModelResponse', () => {
     expect(result.hasToolsOrApprovalsToRun()).toBe(false);
   });
 
+  it('does not keep hosted shell calls pending on unknown status values', () => {
+    const shellCall: protocol.ShellCallItem = {
+      type: 'shell_call',
+      callId: 'call_shell',
+      status: 'queued' as any,
+      action: { commands: ['echo hi'] },
+    };
+    const modelResponse: ModelResponse = {
+      output: [shellCall],
+      usage: new Usage(),
+    };
+
+    const shell = shellTool({
+      environment: { type: 'container_auto' },
+    });
+    const result = processModelResponse(modelResponse, TEST_AGENT, [shell], []);
+
+    expect(result.newItems).toHaveLength(1);
+    expect(result.newItems[0]).toBeInstanceOf(ToolCallItem);
+    expect(result.shellActions).toHaveLength(0);
+    expect(result.toolsUsed).toEqual(['shell']);
+    expect(result.hasToolsOrApprovalsToRun()).toBe(false);
+  });
+
   it('preserves hosted shell output items in processed run items', () => {
     const shellOutput: protocol.ShellCallResultItem = {
       type: 'shell_call_output',
@@ -239,6 +286,35 @@ describe('processModelResponse', () => {
     expect(result.hasToolsOrApprovalsToRun()).toBe(true);
   });
 
+  it('does not keep hosted shell pending on unknown shell_call_output status values', () => {
+    const shellOutput: protocol.ShellCallResultItem = {
+      type: 'shell_call_output',
+      callId: 'call_shell',
+      output: [
+        {
+          stdout: 'partial',
+          stderr: '',
+          outcome: { type: 'exit', exitCode: 0 },
+        },
+      ],
+      providerData: {
+        status: 'queued',
+      },
+    };
+    const modelResponse: ModelResponse = {
+      output: [shellOutput],
+      usage: new Usage(),
+    };
+
+    const result = processModelResponse(modelResponse, TEST_AGENT, [], []);
+
+    expect(result.newItems).toHaveLength(1);
+    expect(result.newItems[0]).toBeInstanceOf(ToolCallOutputItem);
+    expect(result.newItems[0].rawItem).toEqual(shellOutput);
+    expect(result.toolsUsed).toEqual([]);
+    expect(result.hasToolsOrApprovalsToRun()).toBe(false);
+  });
+
   it('throws when shell action emitted without shell tool', () => {
     const shellCall: protocol.ShellCallItem = {
       type: 'shell_call',

packages/agents-core/test/tool.test.ts

@@ -8,6 +8,7 @@ import {
   resolveComputer,
   disposeResolvedComputers,
 } from '../src/tool';
+import type { ShellTool } from '../src/tool';
 import { z } from 'zod';
 import { Computer } from '../src';
 import { Agent } from '../src/agent';
@@ -151,10 +152,21 @@ describe('Tool', () => {
     const t = shellTool({ shell });
     expect(t.type).toBe('shell');
     expect(t.name).toBe('shell');
+    expect(t.environment.type).toBe('local');
     expect(t.environment).toEqual({ type: 'local' });
     expect(t.shell).toBe(shell);
   });
 
+  it('ShellTool keeps local environment optional for compatibility', () => {
+    const legacyTool: ShellTool = {
+      type: 'shell',
+      name: 'shell',
+      shell: new FakeShell(),
+      needsApproval: async () => false,
+    };
+    expect(legacyTool.environment).toBeUndefined();
+  });
+
   it('shellTool supports hosted container environments without local shell', () => {
     const t = shellTool({
       environment: { type: 'container_reference', containerId: 'cont_123' },