# Provider call timeout policy

Use this when Hermes provider calls hang for many minutes, especially non-streaming calls that eventually log messages like “No response from provider for 900s”.

## Goal

Avoid losing 15 minutes per stalled non-streaming call. Long-running reasoning is allowed, but each provider call should be bounded, logged, checkpointed, and split into smaller work units when necessary.

## Recommended defaults

```yaml
agent:
  api_max_retries: 2
  provider_call_policy:
    non_streaming_timeout_seconds: 300
    max_retries: 2
    backoff_seconds: [3, 15]
    checkpoint_before_call: true
    prefer_streaming_for_long_calls: true
    log_fields:
      - provider_request_id
      - model
      - timeout
      - attempt
      - duration
```

Set via CLI:

```bash
hermes config set agent.api_max_retries 2
hermes config set agent.provider_call_policy.non_streaming_timeout_seconds 300
hermes config set agent.provider_call_policy.max_retries 2
hermes config set agent.provider_call_policy.backoff_seconds '[3, 15]'
hermes config set agent.provider_call_policy.checkpoint_before_call true
hermes config set agent.provider_call_policy.prefer_streaming_for_long_calls true
```

Then verify `~/.hermes/config.yaml`; depending on CLI coercion, list values may need manual YAML correction from a string to `[3, 15]`.

Gateway sessions may need `/restart` before the new config is active.

## Operational pattern

Before a large provider call:

1. Checkpoint the request/prompt payload and relevant artifacts.
2. Prefer streaming if the provider supports it and the call may exceed the non-streaming timeout.
3. Log provider request ID, model, timeout, attempt, and duration.
4. On timeout, retry at most twice with exponential-ish backoff, e.g. `3s`, then `15s`.
5. After two timeouts for the same payload, stop repeating it.
6. Split the task into smaller calls or use fallback model/partial report.

Recommended decomposition for content/agent work:

```text
Research → Script → Score → ShotPlan → Keyframe Prompt → Review
```

## Pitfalls

- Do not leave 900s as the default non-streaming stall budget for ordinary gateway work.
- Do not retry the exact same large payload indefinitely.
- Do not perform long uncheckpointed prompt work when the result can be reconstructed from saved artifacts.
- Do not change config and assume an already-running gateway necessarily reloaded it; restart/reset when behavior appears stale.