v22.7.3: small-model AI fits + VM passthrough network-safety preflight

Two Discord-reported issues with concrete fixes.

1. Local AI: 143 KB request body overflowed FunctionGemma's context
   Reported by Gary KO4BSR 2026-05-01. The chat() path was injecting
   the full embedded knowledge base (~200 KB hand-written + generated
   product docs) into every system prompt — fine for cloud providers
   with 100K+ context windows, fatal for 4-8 K context windows on
   small local models. The model would respond with
   `finish_reason=tool_calls` and an empty/malformed tool_calls
   array because it ran out of tokens before the response could
   form, and WolfStack reported "empty response".

   Fix: new `build_compact_system_prompt` strips the KB block. The
   chat() path picks this for `provider == "local"`; cloud paths
   keep the full prompt where the KB is actually load-bearing.
   Compact prompt is comfortably under 10 KB (test pin).

   Plus: when finish_reason is `tool_calls` but nothing was
   dispatchable, the error message now lists what tool names the
   model emitted vs what WolfStack exposes — so the next "I tried
   model X and it didn't work" report carries the diagnosis on its
   face. With suggested alternatives (qwen2.5:3b, llama3.1,
   mistral-functioncalling) that align to the OpenAI tool schema
   WolfStack advertises.

2. VM start nukes the host network when passthrough takes the uplink
   Reported by PapaSchlumpf 2026-05-02. HomeAssistant VM with PCI
   passthrough of a NIC nuked DHCP for the entire network on start;
   reboot fixed, WolfStack restart didn't. Root cause is structural:
   VFIO passthrough removes the device from the host kernel
   namespace, so dnsmasq (and any default-route binding) loses its
   leg instantly. The kernel-state nature is why a reboot is
   required to recover.

   Fix: new `check_passthrough_steals_host_net` runs as part of the
   start_vm preflight (alongside the existing find_conflicts USB/PCI
   check). It returns `Some(iface)` when:
     • a NicConfig.passthrough_interface (MACVTAP-style direct bind)
       names the host's default-route interface, OR
     • a pci_devices entry's BDF resolves (via /sys/bus/pci/.../net/)
       to that same interface.
   start_vm refuses with a clear, multi-line resolution message
   listing three operator paths: switch to a virtio bridge NIC,
   move the host's primary connectivity to a different physical
   NIC, or accept the disconnection. No reboot ever needed because
   the start is blocked before the disconnection happens.

   Reads /proc/net/route directly (no shellout), maps PCI BDF →
   interface via sysfs, handles both short-form (`01:00.0`) and
   full-form (`0000:01:00.0`) BDF spellings. Fails open when the
   host has no default route (dev/lab boxes shouldn't have legitimate
   starts blocked).

5 new network_preflight_tests + 2 new content_tool_call_tests for
the compact prompt. 433/433 tests pass; full suite clean. Code-
reviewer pass on the prior delta (v22.7.2) carried both BLOCKERs
addressed; same parser hardening still in effect here.

Author: Paul C

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "wolfstack"
-version = "22.7.2"
+version = "22.7.3"
 edition = "2024"
 authors = ["Wolf Software Systems Ltd"]
 description = "Server management platform for the Wolf software suite"

src/ai/mod.rs

@@ -538,7 +538,17 @@ impl AiAgent {
             h.iter().rev().take(10).cloned().collect::<Vec<_>>().into_iter().rev().collect()
         };
 
-        let system_prompt = build_system_prompt(&self.knowledge_base, system_context);
+        // Local providers get a compact system prompt that omits the
+        // ~200 KB embedded knowledge base — small models (2-8 B)
+        // routinely have 4-8 K context windows that the full prompt
+        // can't fit. Cloud providers (Claude / Gemini / OpenAI /
+        // OpenRouter) keep the full KB; their context windows are
+        // 100K+ tokens and the KB is genuinely useful for grounding.
+        let system_prompt = if config.provider == "local" {
+            build_compact_system_prompt(system_context)
+        } else {
+            build_system_prompt(&self.knowledge_base, system_context)
+        };
 
         let mut current_msg = user_message.to_string();
         let mut final_response = String::new();
@@ -1970,6 +1980,31 @@ fn build_system_prompt(knowledge: &str, server_context: &str) -> String {
     )
 }
 
+/// Compact system prompt for local / small-context providers. Strips
+/// the embedded knowledge base (~200 KB hand-written + generated) so
+/// the request fits inside the 4-8 K context windows typical of
+/// 2-8 B local models. The model still gets the capability
+/// instructions and tool-use rules — just not the full Wolf product
+/// docs, which it usually doesn't need to answer cluster-state
+/// questions anyway.
+///
+/// Reported on Discord (Gary KO4BSR 2026-05-01): FunctionGemma's
+/// test-connection returned `finish_reason=tool_calls` with empty
+/// tool_calls and a 143 KB request body — the KB alone overflowed
+/// the model's context window and the response collapsed.
+fn build_compact_system_prompt(server_context: &str) -> String {
+    let full = build_system_prompt("", server_context);
+    // The full builder still includes the "Below is comprehensive
+    // documentation…" header even when knowledge is empty. Strip
+    // that trailing line so the model isn't told to consult docs
+    // that aren't there.
+    if let Some(idx) = full.rfind("Below is comprehensive documentation") {
+        full[..idx].trim_end().to_string()
+    } else {
+        full
+    }
+}
+
 // ─── Simple / stateless chat helper ───
 
 /// Single-shot prompt-to-response against the configured AI provider.
@@ -2443,20 +2478,57 @@ async fn call_local_inner(
     }
 
     if combined.is_empty() {
+        // Special case: model signalled `finish_reason=tool_calls`
+        // (intent to call a tool) but neither the structured
+        // `tool_calls` array nor the content fallback yielded
+        // anything dispatchable. Surface what the model actually
+        // emitted so the user can see WHY the call didn't translate
+        // — e.g., FunctionGemma calling a function name we don't
+        // expose, or a malformed tool_calls payload.
+        if finish_reason == "tool_calls" {
+            let tool_calls_preview = serde_json::to_string(&msg["tool_calls"])
+                .unwrap_or_else(|_| "<unserialisable>".into());
+            let names_seen: Vec<&str> = msg["tool_calls"].as_array()
+                .map(|a| a.iter()
+                    .filter_map(|t| t["function"]["name"].as_str())
+                    .collect())
+                .unwrap_or_default();
+            tracing::warn!(
+                target: "wolfstack::ai",
+                "call_local: model={} signalled tool_calls but nothing dispatched. \
+                 Names seen: {:?}. Allowed: {:?}. Raw tool_calls: {}",
+                model, names_seen, MAIN_AI_TOOLS,
+                tool_calls_preview.chars().take(800).collect::<String>(),
+            );
+            let names_str = if names_seen.is_empty() {
+                "(none — empty tool_calls array)".to_string()
+            } else {
+                format!("[{}]", names_seen.join(", "))
+            };
+            return Err(format!(
+                "Local AI ({}) wanted to call tools but emitted names this \
+                 build doesn't expose. Got: {}. Allowed: [{}]. \
+                 The model is most likely matching its training-time tool \
+                 catalogue rather than WolfStack's. Try a model fine-tuned \
+                 on OpenAI-style function-calling (qwen2.5:3b, llama3.1, \
+                 mistral-functioncalling) — those align to the schema \
+                 WolfStack advertises.",
+                model, names_str, MAIN_AI_TOOLS.join(", "),
+            ));
+        }
         tracing::warn!(
             target: "wolfstack::ai",
             "call_local: empty response (model={} finish_reason={} body_size={}). \
-             Common causes: model context exceeded by system prompt + tools + \
-             history; model doesn't follow instructions; server filtered the \
-             output. Body preview: {}",
+             Common causes: context exceeded; model doesn't follow instructions; \
+             server filtered the output. Body preview: {}",
             model, finish_reason, text.len(),
             text.chars().take(300).collect::<String>(),
         );
         return Err(format!(
-            "Local AI returned empty response (finish_reason={}). The request \
-             body was {} bytes — if the model has a small context window (4-8K \
-             on many small models) it may have run out of tokens. Try a model \
-             with a larger context, or simpler prompts.",
+            "Local AI returned empty response (finish_reason={}). Request body \
+             was {} bytes — if the model has a small context window (4-8 K on \
+             many small models) it may have run out of tokens. Try a smaller \
+             model prompt or a longer-context model.",
             finish_reason, body_size,
         ));
     }
@@ -2716,6 +2788,41 @@ mod content_tool_call_tests {
         assert_eq!(calls[0].1["command"], "ls");
     }
 
+    /// Compact prompt for local providers must NOT carry the
+    /// embedded knowledge base. Reported by Gary KO4BSR 2026-05-01:
+    /// 143 KB request body overflowed FunctionGemma's context.
+    /// Pin a generous upper bound (10 KB) so future additions to
+    /// the prompt-shape can't silently re-inflate it past the
+    /// 4 K-token budget of small local models.
+    #[test]
+    fn compact_system_prompt_omits_knowledge_base() {
+        let compact = build_compact_system_prompt("# Server\n(test context)");
+        assert!(
+            compact.len() < 10_000,
+            "compact prompt is {} bytes — must stay well below the 4-8 K-token \
+             window of small local models. The KB inclusion was the bug.",
+            compact.len(),
+        );
+        // Nothing in the compact prompt should mention "knowledge
+        // base" or echo the trailing "Below is comprehensive
+        // documentation" header — that text is what introduces the
+        // KB block, and an empty introduction is misleading.
+        assert!(
+            !compact.contains("Below is comprehensive documentation"),
+            "compact prompt must not include the KB-introduction header",
+        );
+    }
+
+    #[test]
+    fn full_system_prompt_does_include_knowledge_base() {
+        // Counter-test so a future refactor that "compactifies" the
+        // full prompt builder (and breaks cloud-AI grounding) trips
+        // a test instead of silently shipping.
+        let full = build_system_prompt("# KB content goes here", "# Server\n(test)");
+        assert!(full.contains("# KB content goes here"));
+        assert!(full.contains("Below is comprehensive documentation"));
+    }
+
     #[test]
     fn arguments_null_becomes_empty_object() {
         // `security_audit` is in MAIN_AI_TOOLS and takes no args —

src/vms/manager.rs

@@ -10,7 +10,10 @@ use tracing::{error, warn, info};
 use rand::Rng;
 use crate::containers;
 use crate::networking;
-use super::passthrough::{parse_libvirt_hostdevs, parse_proxmox_passthrough, find_conflicts};
+use super::passthrough::{
+    parse_libvirt_hostdevs, parse_proxmox_passthrough,
+    find_conflicts, check_passthrough_steals_host_net,
+};
 
 /// A storage volume that can be attached to a VM
 #[derive(Serialize, Deserialize, Debug, Clone)]
@@ -1402,6 +1405,40 @@ impl VmManager {
                     name, conflicts.join("; ")
                 ));
             }
+
+            // Network-safety preflight: passing a NIC through to a
+            // guest takes it OUT of the host kernel namespace. If
+            // that NIC is the host's path to the network (default-
+            // route interface), the host loses connectivity the
+            // moment the VM starts — including dnsmasq for every
+            // client on the WolfNet/LAN bridge. Reboot is required
+            // because the device disappears in a way `ip link` can't
+            // undo without re-binding from VFIO.
+            //
+            // Reported on Discord (PapaSchlumpf 2026-05-02): HomeAssistant
+            // VM with passthrough NIC nuked DHCP for the whole
+            // network on start; reboot fixed, WolfStack restart did
+            // not. The kernel-state nature is the tell.
+            if let Some(blocking_iface) = check_passthrough_steals_host_net(target) {
+                return Err(format!(
+                    "Cannot start VM '{}': its passthrough configuration would \
+                     claim the host's primary network interface '{}'. Starting \
+                     would disconnect the host from the network and break DHCP \
+                     for every client on the WolfNet bridge — recovery would \
+                     require a host reboot.\n\n\
+                     Fixes:\n\
+                     (a) Remove the PCI passthrough for that NIC and attach \
+                     a virtio bridge NIC instead — the guest gets the same \
+                     reachability without taking the host's uplink.\n\
+                     (b) Move the host's primary connectivity to a different \
+                     physical NIC (so the passed-through one is no longer the \
+                     default route).\n\
+                     (c) If you genuinely need to take that NIC and have an \
+                     out-of-band recovery path, edit the VM's PCI passthrough \
+                     list to confirm.",
+                    name, blocking_iface,
+                ));
+            }
         }
 
         // Look up the WolfStack-side config so we can re-arm the WolfNet

src/vms/passthrough.rs

@@ -1169,3 +1169,163 @@ net0: virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0
         assert!(find_conflicts(&target, &[stopped]).is_empty());
     }
 }
+
+// ─── Network-safety preflight ──────────────────────────────────────
+//
+// Reported on Discord (PapaSchlumpf 2026-05-02): an HA-OS VM with PCI
+// passthrough of a NIC nuked DHCP for the entire network the moment
+// it started. The cause is structural — VFIO passthrough removes the
+// device from the host kernel, so any service binding to it (the
+// host's default-route, dnsmasq for WolfNet clients) loses its leg
+// instantly. Reboot is required because re-attaching from VFIO
+// without one tends to leave the device in an unrecoverable state.
+//
+// `check_passthrough_steals_host_net` returns the offending interface
+// name when the VM's passthrough list would claim the host's
+// default-route interface, so the start path can refuse with a
+// clear error before the operator nukes their own connectivity.
+
+/// Returns `Some(iface_name)` if any of `vm`'s passthrough config
+/// would steal the host's default-route interface. `None` when the
+/// VM is safe to start (or when we couldn't determine the host's
+/// default route — fail open rather than block legitimate starts).
+pub fn check_passthrough_steals_host_net(vm: &VmConfig) -> Option<String> {
+    let host_default_iface = host_default_route_interface()?;
+
+    // Per-NIC `passthrough_interface` (MACVTAP-style direct bind
+    // to a host interface). Lives on each `extra_nics[i]`.
+    for nic in &vm.extra_nics {
+        if let Some(iface) = &nic.passthrough_interface {
+            if iface == &host_default_iface {
+                return Some(host_default_iface);
+            }
+        }
+    }
+
+    // PCI passthrough: walk each BDF, ask sysfs which net interface
+    // (if any) is backed by that device, and compare.
+    for dev in &vm.pci_devices {
+        if let Some(net_iface) = pci_bdf_to_net_iface(&dev.bdf) {
+            if net_iface == host_default_iface {
+                return Some(host_default_iface);
+            }
+        }
+    }
+
+    None
+}
+
+/// Read the host's IPv4 default-route interface from `/proc/net/route`.
+/// Avoids shelling out to `ip` for the hot path. Returns `None` if
+/// no default route exists (host might be a network-isolated lab box
+/// where killing connectivity isn't fatal).
+fn host_default_route_interface() -> Option<String> {
+    let text = std::fs::read_to_string("/proc/net/route").ok()?;
+    for line in text.lines().skip(1) {
+        let cols: Vec<&str> = line.split_whitespace().collect();
+        if cols.len() < 2 { continue; }
+        // Default route = destination 00000000. Field order on
+        // every Linux kernel: Iface Destination Gateway Flags ...
+        if cols[1] == "00000000" {
+            return Some(cols[0].to_string());
+        }
+    }
+    None
+}
+
+/// Map a PCI BDF (e.g. "0000:01:00.0" or "01:00.0") to the kernel
+/// network-interface name it backs, by reading
+/// `/sys/bus/pci/devices/{normalised-bdf}/net/`. Returns `None`
+/// when:
+///   • the BDF doesn't resolve in sysfs (device not present);
+///   • the device isn't a network class (the `net/` directory
+///     doesn't exist — e.g. a GPU passthrough);
+///   • the device IS a NIC but is already bound to vfio-pci (in
+///     which case the host doesn't currently use it, so it can't
+///     be the default-route interface either — safe).
+fn pci_bdf_to_net_iface(bdf: &str) -> Option<String> {
+    // Normalise short-form BDFs (`01:00.0`) to the full form sysfs
+    // uses (`0000:01:00.0`). Full-form input passes through.
+    let normalised = if bdf.matches(':').count() == 1 {
+        format!("0000:{}", bdf)
+    } else {
+        bdf.to_string()
+    };
+    let net_dir = format!("/sys/bus/pci/devices/{}/net", normalised);
+    let entries = std::fs::read_dir(&net_dir).ok()?;
+    for entry in entries.flatten() {
+        if let Some(name) = entry.file_name().to_str() {
+            return Some(name.to_string());
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod network_preflight_tests {
+    use super::*;
+    use super::super::manager::{NicConfig, VmConfig};
+
+    fn empty_vm() -> VmConfig {
+        VmConfig::new("test".to_string(), 1, 1024, 10)
+    }
+
+    fn nic_with_passthrough(iface: &str) -> NicConfig {
+        NicConfig {
+            model: "virtio".into(),
+            mac: None,
+            bridge: None,
+            passthrough_interface: Some(iface.to_string()),
+        }
+    }
+
+    #[test]
+    fn vm_with_no_passthrough_is_safe() {
+        let vm = empty_vm();
+        // A VM with no passthrough at all can never steal the host
+        // NIC, regardless of the host's actual route table.
+        assert!(check_passthrough_steals_host_net(&vm).is_none());
+    }
+
+    #[test]
+    fn passthrough_iface_matching_default_route_blocks() {
+        // We don't have a way to inject a fake default route, so
+        // pick whatever the host's actual default-route iface is
+        // (if any) and assert that a VM claiming that exact iface
+        // is flagged. Skips on hosts with no default route — those
+        // exist in CI environments without network.
+        let Some(host_iface) = host_default_route_interface() else { return; };
+        let mut vm = empty_vm();
+        vm.extra_nics.push(nic_with_passthrough(&host_iface));
+        assert_eq!(
+            check_passthrough_steals_host_net(&vm).as_deref(),
+            Some(host_iface.as_str()),
+            "passthrough_interface == default-route iface must be blocked",
+        );
+    }
+
+    #[test]
+    fn passthrough_iface_not_matching_default_route_allows() {
+        let mut vm = empty_vm();
+        // A bogus interface name that can't possibly be the host's
+        // default route. Counter-test pinning the safe path so a
+        // future false-positive bug is caught.
+        vm.extra_nics.push(nic_with_passthrough("does-not-exist-9999"));
+        assert!(check_passthrough_steals_host_net(&vm).is_none());
+    }
+
+    #[test]
+    fn pci_bdf_to_net_iface_handles_short_form() {
+        // We can't assert the actual return without a known PCI
+        // device, but we can confirm the BDF normalisation doesn't
+        // panic and returns None for a clearly-fake address.
+        assert_eq!(pci_bdf_to_net_iface("ff:ff.7"), None);
+        assert_eq!(pci_bdf_to_net_iface("0000:ff:ff.7"), None);
+    }
+
+    #[test]
+    fn host_default_route_interface_returns_string_or_none() {
+        // Smoke test — must not panic. Result depends on the host.
+        let _ = host_default_route_interface();
+    }
+}