mirror of
https://github.com/openai/codex.git
synced 2026-04-30 01:16:54 +00:00
Add thread/shellCommand to app server API surface (#14988)
This PR adds a new `thread/shellCommand` app server API so clients can implement `!` shell commands. These commands are executed within the sandbox, and the command text and output are visible to the model. The internal implementation mirrors the current TUI `!` behavior. - persist shell command execution as `CommandExecution` thread items, including source and formatted output metadata - bridge live and replayed app-server command execution events back into the existing `tui_app_server` exec rendering path This PR also wires `tui_app_server` to submit `!` commands through the new API.
This commit is contained in:
@@ -136,6 +136,7 @@ Example with notification opt-out:
|
||||
- `thread/name/set` — set or update a thread’s user-facing name for either a loaded thread or a persisted rollout; returns `{}` on success and emits `thread/name/updated` to initialized, opted-in clients. Thread names are not required to be unique; name lookups resolve to the most recently updated thread.
|
||||
- `thread/unarchive` — move an archived rollout file back into the sessions directory; returns the restored `thread` on success and emits `thread/unarchived`.
|
||||
- `thread/compact/start` — trigger conversation history compaction for a thread; returns `{}` immediately while progress streams through standard turn/item notifications.
|
||||
- `thread/shellCommand` — run a user-initiated `!` shell command against a thread; this runs unsandboxed with full access rather than inheriting the thread sandbox policy. Returns `{}` immediately while progress streams through standard turn/item notifications and any active turn receives the formatted output in its message stream.
|
||||
- `thread/backgroundTerminals/clean` — terminate all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`); returns `{}` when the cleanup request is accepted.
|
||||
- `thread/rollback` — drop the last N turns from the agent’s in-memory context and persist a rollback marker in the rollout so future resumes see the pruned history; returns the updated `thread` (with `turns` populated) on success.
|
||||
- `turn/start` — add user input to a thread and begin Codex generation; responds with the initial `turn` object and streams `turn/started`, `item/*`, and `turn/completed` notifications. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode".
|
||||
@@ -415,6 +416,31 @@ While compaction is running, the thread is effectively in a turn so clients shou
|
||||
{ "id": 25, "result": {} }
|
||||
```
|
||||
|
||||
### Example: Run a thread shell command
|
||||
|
||||
Use `thread/shellCommand` for the TUI `!` workflow. The request returns immediately with `{}`.
|
||||
This API runs unsandboxed with full access; it does not inherit the thread
|
||||
sandbox policy.
|
||||
|
||||
If the thread already has an active turn, the command runs as an auxiliary action on that turn. In that case, progress is emitted as standard `item/*` notifications on the existing turn and the formatted output is injected into the turn’s message stream:
|
||||
|
||||
- `item/started` with `item: { "type": "commandExecution", "source": "userShell", ... }`
|
||||
- zero or more `item/commandExecution/outputDelta`
|
||||
- `item/completed` with the same `commandExecution` item id
|
||||
|
||||
If the thread does not already have an active turn, the server starts a standalone turn for the shell command. In that case clients should expect:
|
||||
|
||||
- `turn/started`
|
||||
- `item/started` with `item: { "type": "commandExecution", "source": "userShell", ... }`
|
||||
- zero or more `item/commandExecution/outputDelta`
|
||||
- `item/completed` with the same `commandExecution` item id
|
||||
- `turn/completed`
|
||||
|
||||
```json
|
||||
{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
|
||||
{ "id": 26, "result": {} }
|
||||
```
|
||||
|
||||
### Example: Start a turn (send user input)
|
||||
|
||||
Turns attach user input (text or images) to a thread and trigger Codex generation. The `input` field is a list of discriminated unions:
|
||||
|
||||
Reference in New Issue
Block a user