From 424a915abb7ba36a9dd3adb1b217bc816bd07dd7 Mon Sep 17 00:00:00 2001 From: Basilio Bogado <541149+basiliskus@users.noreply.github.com> Date: Wed, 30 Sep 2026 12:30:34 -0700 Subject: [PATCH 1/3] docs(failure-modes): document sse read timeouts and fix chunktimeout example Section 9 suggested "chunkTimeout": 5000 (5 seconds) and a requestTimeout key that OpenCode does not read. Copied as-is, that would abort nearly every long response with "SSE read timed out". Replace it with the timeouts the usai-provider kit actually sets, explain the SSE read timeout and its automatic retry, and show how to raise chunkTimeout per project. --- docs/KNOWN_FAILURE_MODES.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md index 86ec5ac1..8b21a679 100644 --- a/docs/KNOWN_FAILURE_MODES.md +++ b/docs/KNOWN_FAILURE_MODES.md @@ -222,6 +222,7 @@ Agent assumes host filesystem layout, not container layout. - Requests never return - Agent appears stuck - Eventually fails with timeout +- OpenCode shows `Provider retry (attempt N): SSE read timed out` ### Root Cause @@ -229,17 +230,36 @@ Agent assumes host filesystem layout, not container layout. - Network routing issues inside container - DNS resolution failures - Proxy misconfiguration +- `SSE read timed out`: the streamed response sent no data for longer than the + provider's `chunkTimeout`. Common during long reasoning or while the model + generates a large tool call (such as writing a long file), or when a hop on the + path (sandbox proxy, Zscaler, USAi, the upstream model) stalls. OpenCode retries + automatically, so an occasional one is harmless. ### Fix -Set explicit timeouts in config: +The `usai-provider` kit already sets timeouts under the provider's `options`: +`timeout` (whole request, 10 minutes) and `chunkTimeout` (gap between streamed +chunks, 2 minutes). If `SSE read timed out` recurs, raise `chunkTimeout` in the +project's `opencode.json`. A higher value makes a truly hung stream take longer to +fail over to the retry. Do not set it to a few seconds: normal model pauses would +then abort nearly every long response. + ```json { - "requestTimeout": 30000, - "chunkTimeout": 5000 + "provider": { + "usai": { + "options": { + "chunkTimeout": 300000 + } + } + } } ``` +If retries also fail, note the model, the time, and what the agent was doing, so a +slow model can be told apart from a network stall. + Check network connectivity from inside container: ```bash acq exec -- curl -I https://api.gsa.usai.gov/api/v1/models From efbbd8c423cdb0308d40b38972a7a4c146f4d02f Mon Sep 17 00:00:00 2001 From: Basilio Bogado <541149+basiliskus@users.noreply.github.com> Date: Wed, 7 Oct 2026 13:21:26 -0700 Subject: [PATCH 2/3] docs(failure-modes): correct sse timeout notice, defaults, and retry cap The quoted "Provider retry (attempt N)" text is Paseo's, not OpenCode's; describe the notice generically. State that chunkTimeout has no default before OpenCode 1.18.27 (the kit's 2 minutes is what introduces the idle timeout) and that `false` disables it. Replace "if retries also fail" with the actual behavior: capped at five since 1.18.17, unbounded before. Link the kit's opencode.jsonc for current values. Refs: GSA-TTS/agentic-coding-quickstart#521 --- docs/KNOWN_FAILURE_MODES.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md index 8b21a679..aab5d16b 100644 --- a/docs/KNOWN_FAILURE_MODES.md +++ b/docs/KNOWN_FAILURE_MODES.md @@ -222,7 +222,7 @@ Agent assumes host filesystem layout, not container layout. - Requests never return - Agent appears stuck - Eventually fails with timeout -- OpenCode shows `Provider retry (attempt N): SSE read timed out` +- OpenCode shows a retry notice carrying `SSE read timed out` ### Root Cause @@ -231,19 +231,25 @@ Agent assumes host filesystem layout, not container layout. - DNS resolution failures - Proxy misconfiguration - `SSE read timed out`: the streamed response sent no data for longer than the - provider's `chunkTimeout`. Common during long reasoning or while the model - generates a large tool call (such as writing a long file), or when a hop on the - path (sandbox proxy, Zscaler, USAi, the upstream model) stalls. OpenCode retries - automatically, so an occasional one is harmless. + provider's `chunkTimeout`. OpenCode before 1.18.27 has no default for this option + (unset means no idle timeout; 1.18.27 and later default to 5 minutes), so on those + versions the 2-minute value the `usai-provider` kit sets is what makes it fire. + Common during long reasoning or while the model generates a large tool call (such + as writing a long file), or when a hop on the path (sandbox proxy, Zscaler, USAi, + the upstream model) stalls. OpenCode retries automatically, so an occasional one + is harmless. ### Fix -The `usai-provider` kit already sets timeouts under the provider's `options`: +The `usai-provider` kit sets both timeouts under the provider's `options` in its +[`opencode.jsonc`](https://github.com/GSA-TTS/agentic-coding-patterns/blob/main/integrations/isolation/acq-kits/usai-provider/files/home/usai-config/opencode.jsonc): `timeout` (whole request, 10 minutes) and `chunkTimeout` (gap between streamed -chunks, 2 minutes). If `SSE read timed out` recurs, raise `chunkTimeout` in the -project's `opencode.json`. A higher value makes a truly hung stream take longer to -fail over to the retry. Do not set it to a few seconds: normal model pauses would -then abort nearly every long response. +chunks, 2 minutes); check that file for the current values. If `SSE read timed out` +recurs, raise `chunkTimeout` in the project's `opencode.json`. The example below +uses 5 minutes, the default OpenCode 1.18.27 and later ship; `false` disables the +idle timeout entirely. A higher value makes a truly hung stream take longer to fail +over to the retry. Do not set it to a few seconds: normal model pauses would then +abort nearly every long response. ```json { @@ -257,8 +263,9 @@ then abort nearly every long response. } ``` -If retries also fail, note the model, the time, and what the agent was doing, so a -slow model can be told apart from a network stall. +If the retries run out (OpenCode 1.18.17 and later give up after five; earlier +releases keep retrying until you abort), note the model, the time, and what the +agent was doing, so a slow model can be told apart from a network stall. Check network connectivity from inside container: ```bash From 20a904ea84c170e1f70cec3631421539defc5783 Mon Sep 17 00:00:00 2001 From: Basilio Bogado <541149+basiliskus@users.noreply.github.com> Date: Fri, 9 Oct 2026 15:38:17 -0700 Subject: [PATCH 3/3] docs(failure-modes): scope sse timeout message and retry cap by version The opencode kit now installs OpenCode 2.0.22, where a chunk timeout reports "Timed out waiting for response data" and timed-out requests get three retries (MAX_TIMEOUT_RETRIES in packages/core/src/session/runner/retry.ts). Keep the 1.18.x message and five-retry cap as the older-version case. Refs: GSA-TTS/agentic-coding-quickstart#521 --- docs/KNOWN_FAILURE_MODES.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md index d9194def..8a3cba71 100644 --- a/docs/KNOWN_FAILURE_MODES.md +++ b/docs/KNOWN_FAILURE_MODES.md @@ -222,7 +222,9 @@ Agent assumes host filesystem layout, not container layout. - Requests never return - Agent appears stuck - Eventually fails with timeout -- OpenCode shows a retry notice carrying `SSE read timed out` +- OpenCode shows a retry notice for a streamed-response read timeout: `Timed out + waiting for response data` on OpenCode 2.0.22 (the version the kit installs), + `SSE read timed out` on 1.18.x ### Root Cause @@ -230,7 +232,7 @@ Agent assumes host filesystem layout, not container layout. - Network routing issues inside container - DNS resolution failures - Proxy misconfiguration -- `SSE read timed out`: the streamed response sent no data for longer than the +- Streamed-response read timeout: the response sent no data for longer than the provider's `chunkTimeout`. OpenCode before 1.18.27 has no default for this option (unset means no idle timeout; 1.18.27 and later default to 5 minutes), so on those versions the 2-minute value the `usai-provider` kit sets is what makes it fire. @@ -244,7 +246,7 @@ Agent assumes host filesystem layout, not container layout. The `usai-provider` kit sets both timeouts under the provider's `options` in its [`opencode.jsonc`](https://github.com/GSA-TTS/agentic-coding-patterns/blob/main/integrations/isolation/acq-kits/usai-provider/files/home/usai-config/opencode.jsonc): `timeout` (whole request, 10 minutes) and `chunkTimeout` (gap between streamed -chunks, 2 minutes); check that file for the current values. If `SSE read timed out` +chunks, 2 minutes); check that file for the current values. If the read timeout recurs, raise `chunkTimeout` in the project's `opencode.json`. The example below uses 5 minutes, the default OpenCode 1.18.27 and later ship; `false` disables the idle timeout entirely. A higher value makes a truly hung stream take longer to fail @@ -263,9 +265,11 @@ abort nearly every long response. } ``` -If the retries run out (OpenCode 1.18.17 and later give up after five; earlier -releases keep retrying until you abort), note the model, the time, and what the -agent was doing, so a slow model can be told apart from a network stall. +If the retries run out (OpenCode 2.0.22 gives up after three retries of a timed-out +request, while other retryable errors follow a separate policy; 1.18.17 through the +1.18.x line stop after five; earlier releases keep retrying until you abort), note +the model, the time, and what the agent was doing, so a slow model can be told +apart from a network stall. Check network connectivity from inside container: ```bash