Hosted shell types and streaming events missing

[Anton-Plagemann]

Confirm this is a Node library issue and not an underlying OpenAI API issue

• This is an issue with the Node library

Describe the bug

For the hosted shell tool, some streaming events are not documented and not present in the SDK but the API emits these. I've logged these events once and generated TypeScript types for it:

/**
 * Temporary types for OpenAI shell tool streaming events that are not yet
 * included in the openai SDK's `ResponseStreamEvent` union.
 *
 * These correspond to the following event types observed from the API:
 *  - response.shell_call_command.added
 *  - response.shell_call_command.delta
 *  - response.shell_call_command.done
 *  - response.shell_call_output_content.delta
 *  - response.shell_call_output_content.done
 *
 * Delete this file once the openai SDK ships these types natively.
 */
import type { OpenAI } from "openai";

// ---------------------------------------------------------------------------
// response.shell_call_command.*
// ---------------------------------------------------------------------------

/** Fired when a new shell command starts streaming. */
export interface ResponseShellCallCommandAddedEvent {
  type: "response.shell_call_command.added";
  /** The (initially empty) command text. */
  command: string;
  /** Index of this command within the shell_call's action.commands array. */
  command_index: number;
  /** Index of the parent shell_call output item. */
  output_index: number;
  sequence_number: number;
}

/** Incremental text delta for a shell command being streamed. */
export interface ResponseShellCallCommandDeltaEvent {
  type: "response.shell_call_command.delta";
  /** Index of the command within the shell_call's action.commands array. */
  command_index: number;
  /** The text chunk appended to the command. */
  delta: string;
  /** Opaque obfuscation token (unused). */
  obfuscation: string;
  /** Index of the parent shell_call output item. */
  output_index: number;
  sequence_number: number;
}

/** Fired when a shell command has finished streaming. */
export interface ResponseShellCallCommandDoneEvent {
  type: "response.shell_call_command.done";
  /** The fully-assembled command text. */
  command: string;
  /** Index of the command within the shell_call's action.commands array. */
  command_index: number;
  /** Index of the parent shell_call output item. */
  output_index: number;
  sequence_number: number;
}

// ---------------------------------------------------------------------------
// response.shell_call_output_content.*
// ---------------------------------------------------------------------------

/** Incremental delta for shell execution stdout/stderr. */
export interface ResponseShellCallOutputContentDeltaEvent {
  type: "response.shell_call_output_content.delta";
  /** Index of the command this output belongs to. */
  command_index: number;
  /** Partial stdout/stderr for this chunk. */
  delta: { stdout?: string; stderr?: string };
  /** The shell_call_output item ID. */
  item_id: string;
  /** Index of the shell_call_output item in the response output array. */
  output_index: number;
  sequence_number: number;
}

/** Fired when a shell command's output is complete. */
export interface ResponseShellCallOutputContentDoneEvent {
  type: "response.shell_call_output_content.done";
  /** Index of the command this output belongs to. */
  command_index: number;
  /** The shell_call_output item ID. */
  item_id: string;
  /** Fully-assembled output array with stdout, stderr and outcome. */
  output: OpenAI.Responses.ResponseFunctionShellCallOutputContent[];
  /** Index of the shell_call_output item in the response output array. */
  output_index: number;
  sequence_number: number;
}

// ---------------------------------------------------------------------------
// Union
// ---------------------------------------------------------------------------

/** All shell streaming event types missing from the SDK. */
export type ShellStreamEvent =
  | ResponseShellCallCommandAddedEvent
  | ResponseShellCallCommandDeltaEvent
  | ResponseShellCallCommandDoneEvent
  | ResponseShellCallOutputContentDeltaEvent
  | ResponseShellCallOutputContentDoneEvent;

To Reproduce

1. Include the hosted shell tool in an api call with instructions to use it (e.g. to generate the 100th member of the fibonacci series with the shell tool using code)
2. Watch unknown streaming events getting emitted

Code snippets

OS

Linux

Node version

v24.13.1

Library version

6.22.0

[xXMrNidaXx]

Analysis

These are the streaming events for the new Codex/shell tool — the SDK's ResponseStreamEvent union doesn't include them yet.

Missing event types:

• response.shell_call_command.added — command starts
• response.shell_call_command.delta — incremental command text
• response.shell_call_command.done — command complete
• response.shell_call_output_content.delta — output streaming
• response.shell_call_output_content.done — output complete

These follow the same pattern as other output item events (response.text.delta, response.function_call_arguments.delta, etc.), so the fix should be straightforward:

1. Add the interfaces to resources/responses.ts
2. Extend the ResponseStreamEvent discriminated union

Workaround until fixed:

import type { ResponseStreamEvent } from "openai";

type ShellStreamEvent = 
  | ResponseShellCallCommandAddedEvent
  | ResponseShellCallCommandDeltaEvent
  | ResponseShellCallCommandDoneEvent
  | ResponseShellCallOutputContentDeltaEvent
  | ResponseShellCallOutputContentDoneEvent;

type ExtendedStreamEvent = ResponseStreamEvent | ShellStreamEvent;

// In your stream handler:
for await (const event of stream as AsyncIterable<ExtendedStreamEvent>) {
  if (event.type === "response.shell_call_command.delta") {
    // TypeScript now knows the shape
    console.log(event.delta);
  }
}

The types you documented look correct based on the event structure. The obfuscation field in the delta is interesting — likely used for Codex's optional output scrubbing feature.

[theamodhshetty]

I’m checking this against the current branch and will put together a small typing fix if the hosted shell stream events are still missing there.

[theamodhshetty]

Opened a fix in #1764.

The API already emits these hosted shell events, so this patch just fills in the missing SDK types and wires them into the public responses.stream() event surface. I also added a compile-time regression test that covers both the raw event union and typed .on(...) listeners.