feat(OpenAI): add shell tool and skill attachments support by omitech · Pull Request #811 · openai-php/client

omitech · 2026-10-03T13:34:09Z

What:

Bug Fix
New Feature

Description:

Successful Responses API requests using shell currently throw when the client encounters shell tool definitions or shell_call / shell_call_output items. This change returns typed results and supports serialization across create, retrieve, stored input items and conversations.

Adds container_auto, container_reference and local environment descriptions, skill_reference and inline attachments, local skill descriptions, shell actions and output chunks, exit and timeout outcomes, and shell tool choice. Supports the five shell command/output streaming events and output item events through response.completed. Request forwarding, existing MCP support and local execution responsibilities remain unchanged.

Includes standard fake fixtures, focused regression tests and a README example. The existing Skills API resource added by #808 is reused.

Validation:

composer test passed on PHP 8.3.28 with a command-local 512 MB memory limit, Pest 3.8.7 and pest-plugin-type-coverage 3.5.1: lint, PHPStan and 100% type coverage passed; the unit suite reported 1,205 passed and 34 dependency deprecations, with exit code 0.
Replayed shell and MCP data from two previously captured live responses through CreateResponse and RetrieveResponse, including toArray(). Redacted usage fields were replaced with standard fixture metadata, and the redacted MCP headers placeholder was normalized to null for this local check.
No new live API requests were made. Successful skill_reference execution and real shell streaming remain unverified against the service; parser coverage uses the documented schemas.

fixes: #810

- Introduced ShellTool class to handle shell command execution with various environments. - Updated HostedToolChoice to include 'shell' as a valid type. - Created fixtures for shell call actions, outputs, and outcomes for testing. - Implemented streaming responses for shell commands and outputs. - Added tests for parsing and creating shell tools and outputs, ensuring proper handling of environments and execution limits. - Enhanced response handling to support shell-related events and outputs.

omitech · 2026-10-03T13:35:53Z

Fixes #810

iBotPeaches · 2026-10-03T13:54:40Z

Requesting tool:
{
    "type": "shell",
    "environment": {
        "type": "container_auto",
        "memory_limit": "1g"
    }
}

Response resp_0507d26f45f2233f006ac108dcbbc887d2bad34bd97c8683e0 (completed) from gpt-5.4-2026-03-05
shell_call call_44jYDDtkDruxik3txRRFicf8 (completed)
  command[0]: uname -sm && head -n 1 /etc/os-release
  max_output_length: 2000, timeout_ms: null
  environment: {"type":"container_reference","container_id":"cntr_6ac108dcdb3c81918c25b638d30f2bb80712057e3fcb27c2"}
shell_call_output call_44jYDDtkDruxik3txRRFicf8 (completed)
  output[0]: outcome exit 0
    stdout: Linux x86_64 PRETTY_NAME="Debian GNU/Linux 13 (trixie)" 
    stderr: 
message

Output text: The sandbox is running:
                                                                                                                                                                                                                                         
- `Linux x86_64`                                                                                                                                                                                                                         
- `PRETTY_NAME="Debian GNU/Linux 13 (trixie)"`                                                                                                                                                                                           
                                                                                                                                                                                                                                         
So this is a **Debian GNU/Linux 13 (trixie) x86_64 Linux** environment.                                                                                                                                                                  

Retrieved resp_0507d26f45f2233f006ac108dcbbc887d2bad34bd97c8683e0:
shell tool: {"type":"shell"}
The retrieved response survives a toArray() round trip.
stored input items: 1 parsed, 0 of them shell items
The stored input items survives a toArray() round trip.

Wrote a little script to test this for real, no issues. All worked. Going to add Copilot since my skimming of code seemed fine to see if it finds anything, otherwise g2g.

Copilot

Copilot review overview

🔵 Needs a closer look

The broad API surface and unverified live skill and streaming behavior require final human review.

Review effort: Lite
Findings: None

What changed in this PR

Adds typed Responses API support for the shell tool, including skills, environments, shell outputs, streaming events, and serialization across response pathways.

Changes:

Adds shell tools, skills, containers, actions, outcomes, and tool choices.
Supports shell items in responses, conversations, stored inputs, and streams.
Adds fixtures, regression tests, and README documentation.

File	Summary
`tests/Responses/Responses/Tool/ShellTool.php`	Tests shell tool parsing.
`tests/Responses/Responses/Output/OutputShellCallOutput.php`	Tests shell output parsing.
`tests/Responses/Responses/Output/OutputShellCall.php`	Tests shell call parsing.
`tests/Responses/Responses/ListInputItems.php`	Tests stored shell items.
`tests/Responses/Responses/CreateStreamedResponse.php`	Tests shell streaming.
`tests/Responses/Responses/CreateResponse.php`	Tests shell response parsing.
`tests/Responses/Conversations/ConversationItem.php`	Tests conversation shell items.
`tests/Resources/Responses.php`	Tests shell response requests.
`tests/Fixtures/Streams/ResponseShell.txt`	Provides shell stream data.
`tests/Fixtures/Responses.php`	Registers shell fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellToolFixture.php`	Provides shell tool fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellSkillReferenceFixture.php`	Provides skill reference fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellLocalSkillFixture.php`	Provides local skill fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellLocalEnvironmentFixture.php`	Provides environment fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellInlineSkillSourceFixture.php`	Provides inline source fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellInlineSkillFixture.php`	Provides inline skill fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellContainerReferenceFixture.php`	Provides container reference fixtures.
`src/Testing/Responses/Fixtures/Responses/Tool/ShellContainerAutoFixture.php`	Provides automatic container fixtures.
`src/Testing/Responses/Fixtures/Responses/Streaming/ShellCallOutputContentDoneFixture.php`	Provides completed output fixtures.
`src/Testing/Responses/Fixtures/Responses/Streaming/ShellCallOutputContentDeltaFixture.php`	Provides output delta fixtures.
`src/Testing/Responses/Fixtures/Responses/Streaming/ShellCallCommandFixture.php`	Provides command event fixtures.
`src/Testing/Responses/Fixtures/Responses/Streaming/ShellCallCommandDeltaFixture.php`	Provides command delta fixtures.
`src/Testing/Responses/Fixtures/Responses/Output/ShellCallOutcome/OutputShellCallOutcomeTimeoutFixture.php`	Provides timeout fixtures.
`src/Testing/Responses/Fixtures/Responses/Output/ShellCallOutcome/OutputShellCallOutcomeExitFixture.php`	Provides exit fixtures.
`src/Testing/Responses/Fixtures/Responses/Output/OutputShellCallOutputFixture.php`	Provides shell output fixtures.
`src/Testing/Responses/Fixtures/Responses/Output/OutputShellCallOutputContentFixture.php`	Provides output content fixtures.
`src/Testing/Responses/Fixtures/Responses/Output/OutputShellCallFixture.php`	Provides shell call fixtures.
`src/Testing/Responses/Fixtures/Responses/Output/OutputShellCallActionFixture.php`	Provides shell action fixtures.
`src/Responses/Responses/ToolChoice/HostedToolChoice.php`	Adds shell tool choice typing.
`src/Responses/Responses/Tool/ShellTool.php`	Models shell tools.
`src/Responses/Responses/Tool/ShellSkillReference.php`	Models skill references.
`src/Responses/Responses/Tool/ShellLocalSkill.php`	Models local skills.
`src/Responses/Responses/Tool/ShellLocalEnvironment.php`	Models local environments.
`src/Responses/Responses/Tool/ShellInlineSkillSource.php`	Models inline skill sources.
`src/Responses/Responses/Tool/ShellInlineSkill.php`	Models inline skills.
`src/Responses/Responses/Tool/ShellContainerReference.php`	Models container references.
`src/Responses/Responses/Tool/ShellContainerAuto.php`	Models automatic containers.
`src/Responses/Responses/Streaming/ShellCallOutputContentDone.php`	Parses completed output events.
`src/Responses/Responses/Streaming/ShellCallOutputContentDelta.php`	Parses output delta events.
`src/Responses/Responses/Streaming/ShellCallCommandDelta.php`	Parses command deltas.
`src/Responses/Responses/Streaming/ShellCallCommand.php`	Parses command events.
`src/Responses/Responses/Streaming/OutputItem.php`	Supports streamed shell items.
`src/Responses/Responses/RetrieveResponse.php`	Serializes retrieved shell responses.
`src/Responses/Responses/Output/ShellCallOutcome/OutputShellCallOutcomeTimeout.php`	Models timeout outcomes.
`src/Responses/Responses/Output/ShellCallOutcome/OutputShellCallOutcomeExit.php`	Models exit outcomes.
`src/Responses/Responses/Output/OutputToolSearchOutput.php`	Supports shell tools in tool-search output.
`src/Responses/Responses/Output/OutputShellCallOutputContent.php`	Models output chunks.
`src/Responses/Responses/Output/OutputShellCallOutput.php`	Models shell outputs.
`src/Responses/Responses/Output/OutputShellCallAction.php`	Models shell actions.
`src/Responses/Responses/Output/OutputShellCall.php`	Models shell calls.
`src/Responses/Responses/ListInputItems.php`	Supports stored shell items.
`src/Responses/Responses/CreateStreamedResponse.php`	Dispatches shell stream events.
`src/Responses/Responses/CreateResponse.php`	Supports shell response objects.
`src/Responses/Conversations/ConversationItem.php`	Supports conversation shell items.
`src/Actions/Responses/ToolObjects.php`	Parses shell tools.
`src/Actions/Responses/ToolChoiceObjects.php`	Parses shell choices.
`src/Actions/Responses/OutputObjects.php`	Parses shell outputs.
`src/Actions/Responses/ItemObjects.php`	Parses stored shell items.
`src/Actions/Conversations/ItemObjects.php`	Parses conversation shell items.
`README.md`	Documents hosted shell usage.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

iBotPeaches · 2026-10-03T14:00:59Z

Tested here - iBotPeaches/openai-php-laravel-test@d29a934

omitech mentioned this pull request Oct 3, 2026

[Bug]: Responses API fails to parse shell tools and shell output items #810

Closed

iBotPeaches requested a lite review from Copilot October 3, 2026 13:54

Copilot started reviewing on behalf of iBotPeaches October 3, 2026 13:55 View session

Copilot AI reviewed Oct 3, 2026

View reviewed changes

iBotPeaches approved these changes Oct 3, 2026

View reviewed changes

iBotPeaches merged commit 291d395 into openai-php:main Oct 3, 2026
14 checks passed

iBotPeaches added this to the v0.22.0 milestone Oct 3, 2026

Navigation Menu

Uh oh!

feat(OpenAI): add shell tool and skill attachments support - #811

feat(OpenAI): add shell tool and skill attachments support#811
iBotPeaches merged 1 commit into
openai-php:mainfrom
omitech:feat/responses-hosted-shell-skills

omitech commented Oct 3, 2026 •

edited by iBotPeaches

Loading

Uh oh!

omitech commented Oct 3, 2026

Uh oh!

iBotPeaches commented Oct 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

iBotPeaches commented Oct 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

omitech commented Oct 3, 2026 • edited by iBotPeaches Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What:

Description:

Uh oh!

omitech commented Oct 3, 2026

Uh oh!

iBotPeaches commented Oct 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🔵 Needs a closer look

Uh oh!

iBotPeaches commented Oct 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

omitech commented Oct 3, 2026 •

edited by iBotPeaches

Loading