docs: document v0.21.1 runtime behavior (#4460)

Author: seratch

docs/models/index.md

@@ -494,6 +494,21 @@ english_agent = Agent(
 )
 ```
 
+## Model-call timeouts
+
+Set [`ModelSettings.timeout`][agents.model_settings.ModelSettings.timeout] to a positive number of seconds to bound each model-call attempt. The timeout applies to streaming and non-streaming calls and covers the complete attempt, including transport waits. It does not limit the full agent run, function-tool execution, or retry backoff.
+
+```python
+from agents import Agent, ModelSettings
+
+agent = Agent(
+    name="Assistant",
+    model_settings=ModelSettings(timeout=30.0),
+)
+```
+
+If an attempt exceeds the limit, the SDK cancels the attempt and waits for its cleanup to finish before raising [`ModelTimeoutError`][agents.exceptions.ModelTimeoutError]. When runner-managed retries are enabled, the SDK passes the timeout failure to the retry policy with `context.normalized.is_timeout` set to `True`; for example, `retry_policies.network_error()` matches that classification. Each permitted retry receives a new per-attempt timeout. The SDK still applies the normal [replay-safety rules](#safety-boundaries) before retrying.
+
 ## Runner-managed retries
 
 Retries are runtime-only and opt in. The SDK does not retry general model requests unless you set `ModelSettings(retry=...)` and your retry policy chooses to retry.

docs/realtime/guide.md

@@ -32,6 +32,8 @@ Unlike text-only runs, `runner.run()` does not produce a final result immediatel
 
 By default, `RealtimeRunner` uses `OpenAIRealtimeWebSocketModel`, so the default Python path is a server-side WebSocket connection to the Realtime API. If you pass a different `RealtimeModel`, the same session lifecycle and agent features still apply, while the connection mechanics can change.
 
+When the Realtime API server closes the default WebSocket connection normally, the model transport emits a `disconnected` [`RealtimeModelConnectionStatusEvent`][agents.realtime.model_events.RealtimeModelConnectionStatusEvent] followed by a [`RealtimeModelEndOfStreamEvent`][agents.realtime.model_events.RealtimeModelEndOfStreamEvent]. `RealtimeSession` forwards both inside `raw_model_event`, drains events that are already queued, and then ends asynchronous iteration without raising an exception. A caller-initiated `session.close()` does not synthesize these server-disconnect events. Unexpected WebSocket failures continue through the session's exception path instead of ending iteration as a normal server close.
+
 ## Agent and session configuration
 
 `RealtimeAgent` is intentionally narrower than the regular `Agent` type:

docs/running_agents.md

@@ -589,6 +589,7 @@ The SDK raises exceptions in certain cases. The full list is in [`agents.excepti
 
 -   [`AgentsException`][agents.exceptions.AgentsException]: This is the base class for all exceptions that the SDK raises. It serves as a generic type from which all other specific exceptions are derived.
 -   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: This exception is raised when the agent's run exceeds the `max_turns` limit passed to the `Runner.run`, `Runner.run_sync`, or `Runner.run_streamed` methods. It indicates that the agent could not complete its task within the specified number of agent-loop turns (LLM calls). Set `max_turns=None` to disable the limit.
+-   [`ModelTimeoutError`][agents.exceptions.ModelTimeoutError]: This exception is raised when a model-call attempt exceeds [`ModelSettings.timeout`][agents.model_settings.ModelSettings.timeout]. See [Model-call timeouts](models/index.md#model-call-timeouts) for scope and retry behavior.
 -   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: This exception occurs when the underlying model (LLM) produces unexpected or invalid outputs. This can include:
     -   Malformed JSON: When the model provides a malformed JSON structure for tool calls or in its direct output, especially if a specific `output_type` is defined.
     -   Unexpected tool-related failures: When the model fails to use tools in an expected manner

docs/sandbox/clients.md

@@ -54,6 +54,19 @@ run_config = RunConfig(
 
 Use this when you want container isolation or want the sandbox image to match the image used in another environment. See [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py).
 
+### Disable Docker networking
+
+Set `network_mode="none"` when a Docker sandbox must not have network access:
+
+```python
+options = DockerSandboxClientOptions(
+    image="python:3.14-slim",
+    network_mode="none",
+)
+```
+
+The only supported explicit network mode is `"none"`; omit `network_mode` to preserve Docker's default behavior. A network-disabled sandbox cannot expose ports, so combining `network_mode="none"` with a non-empty `exposed_ports` tuple fails during option validation. The setting is stored in sandbox session state and reapplied if the SDK must create a replacement container while resuming that state.
+
 ## Mounts and remote storage
 
 Mount entries describe what storage to expose; mount strategies describe how a sandbox backend attaches that storage. Import the built-in mount entries and generic strategies from `agents.sandbox.entries`. Hosted-provider strategies are available from `agents.extensions.sandbox` or the provider-specific extension package.
@@ -102,6 +115,22 @@ For provider-specific setup notes and links for the checked-in extension example
 
 </div>
 
+### Size Modal sandboxes
+
+Use `ModalSandboxClientOptions.cpu` and `ModalSandboxClientOptions.memory` to request resources for a new Modal sandbox. A single value requests that amount. A two-item `(request, limit)` tuple uses the first item as the request and the second item as the limit. Memory values are in MiB.
+
+```python
+from agents.extensions.sandbox import ModalSandboxClientOptions
+
+options = ModalSandboxClientOptions(
+    app_name="agents-sandbox",
+    cpu=(1.0, 4.0),
+    memory=(2048, 8192),
+)
+```
+
+Leave `cpu`, `memory`, or both as `None` to use Modal's default for each omitted resource. The selected values are preserved in sandbox session state so replacement sandboxes use the same resource configuration.
+
 Hosted sandbox clients expose provider-specific mount strategies. Choose the backend and mount strategy that best fit your storage provider:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">

docs/sandbox/guide.md

@@ -169,7 +169,7 @@ Good uses for `instructions` include:
 - [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) keeps the agent in one interactive process when PTY state matters.
 - [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) forbids the sandbox reviewer from answering the user directly after inspection.
 - [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) requires the final filled files to actually land in `output/`.
-- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) pins the exact verification command and clarifies workspace-root-relative patch paths.
+- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) pins the exact verification command and clarifies that patch paths are workspace-root relative when `SandboxRunConfig.cwd` is unset.
 
 Avoid copying the user's one-off task into `instructions`, embedding long reference material that belongs in the manifest, restating tool docs that built-in capabilities already inject, or mixing in local installation notes the model does not need at run time.
 
@@ -186,7 +186,7 @@ Built-in capabilities include:
 | Capability | Add it when | Notes |
 | --- | --- | --- |
 | `Shell` | The agent needs shell access. | Adds `exec_command`, plus `write_stdin` when the sandbox client supports PTY interaction. |
-| `Filesystem` | The agent needs to edit files or inspect local images. | Adds `apply_patch` and `view_image`; patch paths are workspace-root-relative. |
+| `Filesystem` | The agent needs to edit files or inspect local images. | Adds `apply_patch` and `view_image`; relative paths use the workspace root by default and `SandboxRunConfig.cwd` when configured. |
 | `Skills` | You want skill discovery and materialization in the sandbox. | Prefer this over manually mounting `.agents` or `.agents/skills`; `Skills` indexes and materializes skills into the sandbox for you. |
 | `Memory` | Follow-on runs should read or generate memory artifacts. | Requires `Shell`; updating memory artifacts during a run also requires `Filesystem`. |
 | `Compaction` | Long-running flows need context trimming after compaction items. | Adjusts model sampling and input handling. |
@@ -195,6 +195,8 @@ Built-in capabilities include:
 
 By default, `SandboxAgent.capabilities` uses `Capabilities.default()`, which includes `Filesystem()`, `Shell()`, and `Compaction()`. If you pass `capabilities=[...]`, that list replaces the default, so include any default capabilities you still want.
 
+The `view_image` tool identifies PNG, JPEG, GIF, WebP, BMP, and TIFF raster images from their file content, not from the filename extension. A filename with a raster-image extension is rejected when its content is unsupported, while supported raster content can be loaded even when the filename has no image extension. For `.svg` and `.svgz` files, the tool retains filename-based compatibility in addition to recognizing SVG markup from file content.
+
 For skills, choose the source based on how you want them materialized:
 
 - `Skills(lazy_from=LocalDirLazySkillSource(...))` is a good default for larger local skill directories because the model can discover the index first and load only what it needs.
@@ -235,7 +237,7 @@ Use manifest entries for the material the agent needs before work begins:
 
 Mount entries describe what storage to expose; mount strategies describe how a sandbox backend attaches that storage. See [Sandbox clients](clients.md#mounts-and-remote-storage) for mount options and provider support.
 
-Good manifest design usually means keeping the workspace contract narrow, putting long task recipes in workspace files such as `repo/task.md`, and using relative workspace paths in instructions, for example `repo/task.md` or `output/report.md`. If the agent edits files with the `Filesystem` capability's `apply_patch` tool, remember that patch paths are relative to the sandbox workspace root, not the shell `workdir`.
+Good manifest design usually means keeping the workspace contract narrow, putting long task recipes in workspace files such as `repo/task.md`, and using relative workspace paths in instructions, for example `repo/task.md` or `output/report.md`. If the agent edits files with the `Filesystem` capability's `apply_patch` tool, remember that patch paths use the sandbox workspace root by default or `SandboxRunConfig.cwd` when configured; they do not use the shell `workdir`.
 
 Use `extra_path_grants` only when the agent needs a concrete absolute path outside the workspace or the manifest needs to copy a trusted local source outside the SDK process working directory. Examples include `/tmp` for temporary tool output, `/opt/toolchain` for a read-only runtime, or a generated skills directory that should be materialized into the sandbox. A grant applies to local source materialization and SDK file APIs. It also applies to shell execution when the backend can enforce filesystem policy:
 
@@ -472,6 +474,31 @@ These options only matter when the runner is creating a fresh sandbox session:
 
 </div>
 
+### Model-facing working directory
+
+Set `cwd` to a POSIX workspace-relative directory when several runs should share one sandbox session but operate in separate subdirectories. The directory must exist and be accessible to the configured sandbox user when the runner validates `cwd`. For a fresh session, the runner materializes the manifest first, so the manifest can create the directory before this validation.
+
+```python
+from agents import Runner
+from agents.run import RunConfig
+from agents.sandbox import SandboxRunConfig
+
+result = await Runner.run(
+    agent,
+    "Work only on task A.",
+    run_config=RunConfig(
+        sandbox=SandboxRunConfig(
+            session=shared_sandbox,
+            cwd="tasks/task-a",
+        ),
+    ),
+)
+```
+
+Relative paths used by the built-in `exec_command`, `view_image`, and `apply_patch` tools resolve from `cwd`. For the `cwd` value itself, absolute paths, parent segments such as `..`, and empty values are rejected. String values must use forward slashes. Relative `PurePath` values are normalized to POSIX form, while absolute `PurePath` values remain invalid. Direct `BaseSandboxSession` file APIs remain workspace-root relative, so `cwd` does not change `Manifest.root` or the session's underlying workspace boundary. The setting changes relative-path resolution only: it does not confine the run to `cwd` or prevent access to other paths allowed by the shared session's workspace policy.
+
+Custom path-bearing capabilities must apply their bound [`SandboxWorkspaceScope`][agents.sandbox.workspace_paths.SandboxWorkspaceScope] when resolving model-provided relative paths. See [examples/sandbox/shared_session_workdirs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/shared_session_workdirs.py) for two concurrent runs that share one sandbox session while keeping their model-facing working directories separate.
+
 ### Materialization controls
 
 `concurrency_limits` controls how much sandbox materialization work can run in parallel. Use `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` when large manifests or local directory copies need tighter resource control. Set either value to `None` to disable that specific limit.
@@ -520,9 +547,9 @@ def build_agent(model: str) -> SandboxAgent[None]:
             "and summarize the file changes and risks. "
             "Read `repo/task.md` before editing files. Stay grounded in the repository, preserve "
             "existing behavior, and mention the exact verification command you ran. "
-            "Use the `$credit-note-fixer` skill before editing files. If the repo lives under "
-            "`repo/`, remember that `apply_patch` paths stay relative to the sandbox workspace "
-            "root, so edits still target `repo/...`."
+            "Use the `$credit-note-fixer` skill before editing files. "
+            "This example leaves `SandboxRunConfig.cwd` unset, so `apply_patch` paths stay "
+            "relative to the sandbox workspace root and edits still target `repo/...`."
         ),
         # Put repos and task files in the manifest.
         default_manifest=Manifest(

docs/sessions/index.md

@@ -276,6 +276,8 @@ print(result.final_output)
 
 By default, after each turn, the SDK checks whether the compaction candidate meets the threshold and compacts only if it does.
 
+When automatic compaction runs, the SDK waits for it before `Runner.run(...)` returns or the streamed event iterator closes. Usage reported by the compaction request contributes to that run's [`Usage`](../usage.md) totals. By default, a manual `run_compaction()` call made later has no enclosing run context and does not update the completed run's usage object.
+
 `compaction_mode="previous_response_id"` uses Responses API response IDs retained by the compaction session and works best while that response chain remains available. `compaction_mode="input"` rebuilds the compaction request from the current session items instead, which is useful when the response chain is unavailable or you want the session contents to be the source of truth. The default `"auto"` chooses the safest available option.
 
 If your agent runs with `ModelSettings(store=False)`, the Responses API does not retain the last response for later lookup. In that stateless setup, the default `"auto"` mode falls back to input-based compaction instead of relying on `previous_response_id`. See [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) for a complete example.

docs/usage.md

@@ -30,6 +30,8 @@ print("Total tokens:", usage.total_tokens)
 
 Usage is aggregated across all model calls during the run, including model calls that produce tool calls or handoffs.
 
+When an [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] automatically compacts history before the run finishes, usage reported by that `responses.compact` request is also added to the same run totals. A manual `run_compaction()` call made outside a run has no enclosing run context, so it does not update the usage object returned by an earlier run. See [OpenAI Responses compaction sessions](sessions/index.md#openai-responses-compaction-sessions).
+
 ### Enabling usage with third-party adapters
 
 Usage reporting varies across third-party adapters and provider backends. If you access models through third-party adapters and need accurate `result.context_wrapper.usage` values:

src/agents/run_config.py

@@ -224,8 +224,12 @@ class SandboxRunConfig:
 
     Relative paths used by the built-in `exec_command`, `view_image`, and `apply_patch` tools
     resolve from this directory. Custom path-bearing capabilities must apply their bound
-    `SandboxWorkspaceScope` explicitly. The directory must already exist when the run starts.
-    This setting does not change `Manifest.root` or direct `BaseSandboxSession` path behavior.
+    `SandboxWorkspaceScope` explicitly. The directory must exist and be accessible to the
+    configured sandbox user when the runner validates `cwd`; for a fresh session, the runner
+    materializes the manifest before that validation.
+    This setting changes relative-path resolution only. It does not confine the run to `cwd`,
+    prevent access to other paths allowed by the shared session's workspace policy, change
+    `Manifest.root`, or change direct `BaseSandboxSession` path behavior.
     """
 
     if TYPE_CHECKING: