Merge main, resolve Cargo.toml conflict

Author: jamiepine

Cargo.toml

@@ -97,8 +97,6 @@ emojis = "0.8"
 
 # TLS (shared crypto backend for slack-morphism, reqwest, teloxide)
 rustls = { version = "0.23", default-features = false, features = ["ring"] }
-# slack-morphism enables tokio-tungstenite/rustls-native-certs, but tokio-tungstenite 0.28
-# restructured features — rustls-tls-native-roots is now needed to activate actual TLS.
 tokio-tungstenite = { version = "0.28", features = ["rustls-tls-native-roots"] }
 
 # Telegram

README.md

@@ -112,6 +112,7 @@ Every memory has a type, an importance score, and graph edges connecting it to r
 - **Memory import** — dump files into the `ingest/` folder and Spacebot extracts structured memories automatically. Supports text, markdown, and PDF files. Migrating from OpenClaw? Drop your markdown memory files in and walk away.
 - **Cross-channel recall** — branches can read transcripts from other conversations
 - **Memory bulletin** — the cortex generates a periodic briefing of the agent's knowledge, injected into every conversation
+- **Warmup readiness contract** — branch/worker/cron dispatch checks `ready_for_work` (warm state + embedding ready + fresh bulletin), records cold-dispatch metrics, and triggers background forced warmup without blocking channels
 
 ### Scheduling
 

docs/content/docs/(configuration)/config.mdx

@@ -91,6 +91,13 @@ worker_timeout_secs = 300
 branch_timeout_secs = 60
 circuit_breaker_threshold = 3  # consecutive failures before auto-disable
 
+# Warmup controls for cold-start behavior and manual rewarm.
+[defaults.warmup]
+enabled = true
+eager_embedding_load = true
+refresh_secs = 900
+startup_delay_secs = 5
+
 # Browser automation for workers.
 [defaults.browser]
 enabled = true
@@ -214,6 +221,7 @@ Most config values are hot-reloaded when their files change. Spacebot watches `c
 | `context_window` | Yes | Next compaction/worker check uses new size |
 | `max_concurrent_branches` | Yes | Next branch spawn checks new limit |
 | Browser config | Yes | Next worker spawn uses new config |
+| Warmup config | Yes | Next warmup pass uses new values |
 | Identity files (SOUL.md, etc.) | Yes | Next channel message renders new identity |
 | Skills (SKILL.md files) | Yes | Next message / worker spawn sees new skills |
 | Bindings | Yes | Next message routes using new bindings |
@@ -467,6 +475,23 @@ Thresholds are fractions of `context_window`.
 | `branch_timeout_secs` | integer | 60 | Branch timeout before cancellation |
 | `circuit_breaker_threshold` | integer | 3 | Consecutive failures before auto-disable |
 
+### `[defaults.warmup]`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | bool | true | Enable background warmup loop |
+| `eager_embedding_load` | bool | true | Warm embedding model before first recall/write workload |
+| `refresh_secs` | integer | 900 | Seconds between background warmup passes |
+| `startup_delay_secs` | integer | 5 | Delay before first warmup pass after boot |
+
+Dispatch readiness is derived from warmup runtime state:
+
+- warmup state must be `warm`
+- embedding must be ready
+- bulletin age must be fresh (<= `max(60s, refresh_secs * 2)`)
+
+When branch/worker/cron dispatch happens before readiness is satisfied, Spacebot still dispatches, increments cold-dispatch metrics, and queues a forced warmup pass in the background.
+
 ### `[defaults.browser]`
 
 | Key | Type | Default | Description |

docs/content/docs/(core)/cortex.mdx

@@ -161,6 +161,81 @@ branch_timeout_secs = 60
 circuit_breaker_threshold = 3
 ```
 
+## Warmup API
+
+Warmup is exposed via the agent API so you can inspect cold/warm state and trigger a re-warm pass on demand.
+
+### `GET /api/agents/warmup?agent_id=...`
+
+Returns warmup status for one agent. If `agent_id` is omitted, returns statuses for all agents.
+
+```json
+{
+  "statuses": [
+    {
+      "agent_id": "main",
+      "status": {
+        "state": "warm",
+        "embedding_ready": true,
+        "last_refresh_unix_ms": 1763935800123,
+        "last_error": null,
+        "bulletin_age_secs": 42
+      }
+    }
+  ]
+}
+```
+
+### `POST /api/agents/warmup`
+
+Triggers a one-shot warmup pass for one agent or all agents.
+
+```json
+{
+  "agent_id": "main",
+  "force": false
+}
+```
+
+- `agent_id` optional: omit to trigger all agents.
+- `force` optional: when `true`, runs the warmup pass even if warmup is disabled in config.
+
+Response:
+
+```json
+{
+  "status": "warming",
+  "forced": false,
+  "accepted_agents": ["main"]
+}
+```
+
+### Warmup States
+
+- `cold` — warmup is disabled or has not run yet.
+- `warming` — a warmup pass is currently in progress.
+- `warm` — latest warmup pass succeeded.
+- `degraded` — last warmup pass failed; `last_error` contains the reason.
+
+### Readiness Contract
+
+Branch, worker, and cron dispatch paths consult a derived `ready_for_work` signal:
+
+- warmup state is `warm`
+- embedding model is ready
+- bulletin age is fresh (<= `max(60s, refresh_secs * 2)`)
+
+If dispatch arrives while not ready, Spacebot does **not** block the channel or scheduler:
+
+- dispatch continues in degraded-safe mode
+- a forced warmup pass is queued in the background
+- readiness telemetry is emitted
+
+Metrics:
+
+- `spacebot_dispatch_while_cold_count{agent_id,dispatch_type,reason}`
+- `spacebot_warmup_recovery_latency_ms{agent_id,dispatch_type}`
+
 ## Failure Modes
 
 **What if the cortex bulletin fails?**

src/agent/channel.rs

@@ -1325,6 +1325,7 @@ pub async fn spawn_branch_from_state(
         &description,
         &system_prompt,
         &description,
+        "branch",
     )
     .await
 }
@@ -1352,10 +1353,49 @@ async fn spawn_memory_persistence_branch(
         &prompt,
         &system_prompt,
         "persisting memories...",
+        "memory_persistence_branch",
     )
     .await
 }
 
+fn ensure_dispatch_readiness(state: &ChannelState, dispatch_type: &'static str) {
+    let readiness = state.deps.runtime_config.work_readiness();
+    if readiness.ready {
+        return;
+    }
+
+    let reason = readiness
+        .reason
+        .map(|value| value.as_str())
+        .unwrap_or("unknown");
+    tracing::warn!(
+        agent_id = %state.deps.agent_id,
+        channel_id = %state.channel_id,
+        dispatch_type,
+        reason,
+        warmup_state = ?readiness.warmup_state,
+        embedding_ready = readiness.embedding_ready,
+        bulletin_age_secs = ?readiness.bulletin_age_secs,
+        stale_after_secs = readiness.stale_after_secs,
+        "dispatch requested before readiness contract was satisfied"
+    );
+
+    #[cfg(feature = "metrics")]
+    crate::telemetry::Metrics::global()
+        .dispatch_while_cold_count
+        .with_label_values(&[&*state.deps.agent_id, dispatch_type, reason])
+        .inc();
+
+    let warmup_config = **state.deps.runtime_config.warmup.load();
+    let should_trigger = readiness.warmup_state != crate::config::WarmupState::Warming
+        && (readiness.reason != Some(crate::config::WorkReadinessReason::EmbeddingNotReady)
+            || warmup_config.eager_embedding_load);
+
+    if should_trigger {
+        crate::agent::cortex::trigger_forced_warmup(state.deps.clone(), dispatch_type);
+    }
+}
+
 /// Shared branch spawning logic.
 ///
 /// Checks the branch limit, clones history, creates a Branch, spawns it as
@@ -1366,6 +1406,7 @@ async fn spawn_branch(
     prompt: &str,
     system_prompt: &str,
     status_label: &str,
+    dispatch_type: &'static str,
 ) -> std::result::Result<BranchId, AgentError> {
     let max_branches = **state.deps.runtime_config.max_concurrent_branches.load();
     {
@@ -1377,6 +1418,7 @@ async fn spawn_branch(
             });
         }
     }
+    ensure_dispatch_readiness(state, dispatch_type);
 
     let history = {
         let h = state.history.read().await;
@@ -1472,6 +1514,7 @@ pub async fn spawn_worker_from_state(
     suggested_skills: &[&str],
 ) -> std::result::Result<WorkerId, AgentError> {
     check_worker_limit(state).await?;
+    ensure_dispatch_readiness(state, "worker");
     let task = task.into();
 
     let rc = &state.deps.runtime_config;
@@ -1582,6 +1625,7 @@ pub async fn spawn_opencode_worker_from_state(
     interactive: bool,
 ) -> std::result::Result<crate::WorkerId, AgentError> {
     check_worker_limit(state).await?;
+    ensure_dispatch_readiness(state, "opencode_worker");
     let task = task.into();
     let directory = std::path::PathBuf::from(directory);