fix(core): make session warming observable

packages/docs/config.mdx

@@ -338,6 +338,25 @@ Control automatic context compaction and how much recent context it preserves.
 
 See the [compaction guide](/compaction) for automatic context management.
 
+### Session warming
+
+Keep recently active model sessions warm with periodic transient requests.
+Warming is disabled by default; set it to `true` to use the four-minute idle
+interval and 30-minute active window.
+
+```jsonc
+{
+  "warming": {
+    "prompt": "Do not perform any work. Reply with exactly: OK",
+    "interval": "4 minutes",
+    "duration": "30 minutes"
+  }
+}
+```
+
+See the [session warming guide](/warming) for request behavior, customization,
+and cost considerations.
+
 ### Skills
 
 Add directories or URLs that OpenCode should search for agent skills.

packages/docs/docs.json

@@ -37,6 +37,7 @@
               "mcp-servers",
               "attachments",
               "compaction",
+              "warming",
               "formatters",
               "lsp",
               "references"

packages/docs/warming.mdx

@@ -0,0 +1,76 @@
+---
+title: "Session warming"
+description: "Keep recently active model sessions warm with periodic transient requests."
+---
+
+Session warming sends periodic model requests for recently active sessions.
+This can preserve provider-side prompt caches or other short-lived session
+state while you pause between prompts.
+
+Warming is disabled by default. Enable it with the default settings in any
+[OpenCode configuration file](/config):
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "warming": true
+}
+```
+
+With the defaults, OpenCode sends a warming request after a session has made no
+model request for four minutes. It repeats this while the session remains idle,
+but stops 30 minutes after the last non-warming request. New model activity
+starts a new 30-minute window.
+
+## Configuration
+
+Use the object form to customize the prompt, idle interval, or active duration:
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "warming": {
+    "prompt": "Do not perform any work. Reply with exactly: OK",
+    "interval": "4 minutes",
+    "duration": "30 minutes"
+  }
+}
+```
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `prompt` | Keep-alive instruction | Prompt sent in each warming request. The default instructs the model to do no work and reply with `OK`. |
+| `interval` | `"4 minutes"` | Idle time between warming requests. |
+| `duration` | `"30 minutes"` | Maximum warming window after the latest non-warming model request. |
+
+`interval` and `duration` accept duration strings such as `"30 seconds"`,
+`"4 minutes"`, or `"1 hour"`. Both must be finite and greater than zero.
+
+To disable warming explicitly:
+
+```jsonc
+{
+  "warming": false
+}
+```
+
+## Request behavior
+
+A warming request uses the session's current model, agent, instructions, and
+conversation context. Tools are disabled. The configured prompt is appended as
+a transient user message, and the response is discarded.
+
+Warming does not admit input, add messages to session history, or otherwise
+mutate durable session state. A warming request resets the idle interval but
+does not extend the active duration; without new model activity, warming still
+ends when the configured duration expires.
+
+## Costs and limits
+
+Warming requests are real provider requests. They can consume tokens, incur
+costs, count against rate limits, and fail for the same reasons as other model
+requests. OpenCode logs warming failures without failing or changing the
+session, then waits for the next interval before trying again.
+
+Enable warming only when the provider-side benefit is worth the additional
+requests. A shorter interval or longer duration increases request volume.