feat(sparsekernel): add strict runtime acceptance

Author: AbrahamGreenman

crates/sparsekernel-cli/src/lib.rs

@@ -8,8 +8,8 @@ use sparsekernel_core::{
     AuditInput, BrowserBroker, CapabilityCheck, CompleteToolCallInput, CreateToolCallInput,
     EnqueueTaskInput, GrantCapabilityInput, LedgerToolBroker, ListBrowserObservationsInput,
     ListBrowserTargetsInput, LocalSandboxBroker, MockBrowserBroker, RecordBrowserObservationInput,
-    RecordBrowserTargetInput, SandboxBroker, SparseKernelDb, SparseKernelPaths, ToolBroker,
-    UpsertSessionInput, SPARSEKERNEL_PROTOCOL_VERSION,
+    RecordBrowserTargetInput, ResourceBudgetUpdateInput, SandboxBroker, SparseKernelDb,
+    SparseKernelPaths, ToolBroker, UpsertSessionInput, SPARSEKERNEL_PROTOCOL_VERSION,
 };
 use std::collections::HashMap;
 use std::error::Error;
@@ -1313,10 +1313,22 @@ pub fn handle_api_request_with_daemon_state(
                     "capabilities.v1",
                     "browser-broker.v1",
                     "sandbox-broker.v1",
-                    "sandbox-backends.probe.v1"
+                    "sandbox-backends.probe.v1",
+                    "resource-budgets.v1"
                 ],
             }),
         },
+        ("GET", "/runtime/budgets") => ApiReply {
+            status_code: 200,
+            body: serde_json::to_value(db.resource_budgets()?)?,
+        },
+        ("POST", "/runtime/budgets/update") => {
+            let input: ResourceBudgetUpdateInput = parse_body(body)?;
+            ApiReply {
+                status_code: 200,
+                body: serde_json::to_value(db.update_resource_budgets(input)?)?,
+            }
+        }
         ("GET", "/status") => ApiReply {
             status_code: 200,
             body: serde_json::to_value(db.inspect()?)?,
@@ -1975,6 +1987,30 @@ mod tests {
             .as_array()
             .unwrap()
             .contains(&json!("tasks.v1")));
+        assert!(health["features"]
+            .as_array()
+            .unwrap()
+            .contains(&json!("resource-budgets.v1")));
+    }
+
+    #[test]
+    fn runtime_budget_api_reads_and_updates_budgets() {
+        let mut db = SparseKernelDb::open(":memory:").unwrap();
+        let initial = json_call(&mut db, "GET", "/runtime/budgets", json!({}));
+        assert_eq!(initial["browser_contexts_max"], 2);
+        let updated = json_call(
+            &mut db,
+            "POST",
+            "/runtime/budgets/update",
+            json!({
+                "active_agent_steps_max": 12,
+                "browser_contexts_max": 3,
+                "heavy_sandboxes_max": 2,
+            }),
+        );
+        assert_eq!(updated["active_agent_steps_max"], 12);
+        assert_eq!(updated["browser_contexts_max"], 3);
+        assert_eq!(updated["heavy_sandboxes_max"], 2);
     }
 
     #[test]

crates/sparsekernel-core/src/lib.rs

@@ -146,6 +146,28 @@ fn task_budget_default(kind: TaskBudgetKind) -> i64 {
     }
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ResourceBudgetSnapshot {
+    pub logical_agents_max: i64,
+    pub active_agent_steps_max: i64,
+    pub model_calls_in_flight_max: i64,
+    pub file_patch_jobs_max: i64,
+    pub test_jobs_max: i64,
+    pub browser_contexts_max: i64,
+    pub heavy_sandboxes_max: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ResourceBudgetUpdateInput {
+    pub logical_agents_max: Option<i64>,
+    pub active_agent_steps_max: Option<i64>,
+    pub model_calls_in_flight_max: Option<i64>,
+    pub file_patch_jobs_max: Option<i64>,
+    pub test_jobs_max: Option<i64>,
+    pub browser_contexts_max: Option<i64>,
+    pub heavy_sandboxes_max: Option<i64>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct SparseKernelPaths {
     pub home_dir: PathBuf,
@@ -1033,6 +1055,88 @@ impl SparseKernelDb {
             .unwrap_or(fallback))
     }
 
+    fn runtime_info_integer(&self, key: &str, fallback: i64) -> Result<i64> {
+        let value: Option<String> = self
+            .conn
+            .query_row(
+                "SELECT value FROM runtime_info WHERE key = ?",
+                params![key],
+                |row| row.get(0),
+            )
+            .optional()?;
+        Ok(value
+            .as_deref()
+            .and_then(|entry| entry.trim().parse::<i64>().ok())
+            .map(|entry| entry.max(0))
+            .unwrap_or(fallback))
+    }
+
+    pub fn resource_budgets(&self) -> Result<ResourceBudgetSnapshot> {
+        Ok(ResourceBudgetSnapshot {
+            logical_agents_max: self
+                .runtime_info_integer("resource_budget.logical_agents_max", 500)?,
+            active_agent_steps_max: self
+                .runtime_info_integer("resource_budget.active_agent_steps_max", 100)?,
+            model_calls_in_flight_max: self
+                .runtime_info_integer("resource_budget.model_calls_in_flight_max", 50)?,
+            file_patch_jobs_max: self
+                .runtime_info_integer("resource_budget.file_patch_jobs_max", 16)?,
+            test_jobs_max: self.runtime_info_integer("resource_budget.test_jobs_max", 4)?,
+            browser_contexts_max: self
+                .runtime_info_integer("resource_budget.browser_contexts_max", 2)?,
+            heavy_sandboxes_max: self
+                .runtime_info_integer("resource_budget.heavy_sandboxes_max", 1)?,
+        })
+    }
+
+    pub fn update_resource_budgets(
+        &mut self,
+        input: ResourceBudgetUpdateInput,
+    ) -> Result<ResourceBudgetSnapshot> {
+        let tx = self.conn.transaction()?;
+        let now = now_iso();
+        let set_value = |key: &str, value: Option<i64>| -> Result<()> {
+            if let Some(value) = value {
+                tx.execute(
+                    "INSERT INTO runtime_info(key, value, updated_at)
+                     VALUES(?, ?, ?)
+                     ON CONFLICT(key) DO UPDATE SET
+                       value=excluded.value,
+                       updated_at=excluded.updated_at",
+                    params![key, value.max(0).to_string(), now],
+                )?;
+            }
+            Ok(())
+        };
+        set_value(
+            "resource_budget.logical_agents_max",
+            input.logical_agents_max,
+        )?;
+        set_value(
+            "resource_budget.active_agent_steps_max",
+            input.active_agent_steps_max,
+        )?;
+        set_value(
+            "resource_budget.model_calls_in_flight_max",
+            input.model_calls_in_flight_max,
+        )?;
+        set_value(
+            "resource_budget.file_patch_jobs_max",
+            input.file_patch_jobs_max,
+        )?;
+        set_value("resource_budget.test_jobs_max", input.test_jobs_max)?;
+        set_value(
+            "resource_budget.browser_contexts_max",
+            input.browser_contexts_max,
+        )?;
+        set_value(
+            "resource_budget.heavy_sandboxes_max",
+            input.heavy_sandboxes_max,
+        )?;
+        tx.commit()?;
+        self.resource_budgets()
+    }
+
     fn running_task_count_for_budget_tx(
         tx: &rusqlite::Transaction<'_>,
         kind: TaskBudgetKind,
@@ -2680,6 +2784,30 @@ impl BrowserBroker for MockBrowserBroker<'_> {
                 "no browser contexts available".to_string(),
             ));
         }
+        let budget = self.db.resource_budgets()?;
+        let active_budget: i64 = self.db.conn.query_row(
+            "SELECT COUNT(*) FROM resource_leases WHERE resource_type = 'browser_context' AND status = 'active'",
+            [],
+            |row| row.get(0),
+        )?;
+        if active_budget >= budget.browser_contexts_max {
+            self.db.record_audit(AuditInput {
+                actor_type: agent_id.map(|_| "agent".to_string()),
+                actor_id: agent_id.map(str::to_string),
+                action: "resource_lease.denied_budget_exhausted".to_string(),
+                object_type: Some("browser_context".to_string()),
+                object_id: None,
+                payload: Some(json!({
+                    "resourceType": "browser_context",
+                    "active": active_budget,
+                    "limit": budget.browser_contexts_max,
+                })),
+            })?;
+            return Err(SparseKernelError::Denied(format!(
+                "browser context budget exhausted: {}/{} active",
+                active_budget, budget.browser_contexts_max
+            )));
+        }
         let context_id = format!("browser_ctx_{}", Uuid::new_v4());
         self.db.conn.execute(
             "INSERT INTO browser_contexts(id, pool_id, agent_id, session_id, task_id, profile_mode, status, created_at)
@@ -3010,6 +3138,32 @@ impl SandboxBroker for LocalSandboxBroker<'_> {
                 }
             }
         }
+        let budget = self.db.resource_budgets()?;
+        let active_sandboxes: i64 = self.db.conn.query_row(
+            "SELECT COUNT(*) FROM resource_leases WHERE resource_type = 'sandbox' AND status = 'active'",
+            [],
+            |row| row.get(0),
+        )?;
+        if active_sandboxes >= budget.heavy_sandboxes_max {
+            self.db.record_audit(AuditInput {
+                actor_type: agent_id.map(|_| "agent".to_string()),
+                actor_id: agent_id.map(str::to_string),
+                action: "resource_lease.denied_budget_exhausted".to_string(),
+                object_type: Some("trust_zone".to_string()),
+                object_id: Some(trust_zone_id.to_string()),
+                payload: Some(json!({
+                    "trustZoneId": trust_zone_id,
+                    "resourceType": "sandbox",
+                    "budget": "heavy_sandboxes",
+                    "active": active_sandboxes,
+                    "limit": budget.heavy_sandboxes_max,
+                })),
+            })?;
+            return Err(SparseKernelError::Denied(format!(
+                "heavy sandbox budget exhausted: {}/{} active",
+                active_sandboxes, budget.heavy_sandboxes_max
+            )));
+        }
         self.db.conn.execute(
             "INSERT INTO resource_leases(id, resource_type, resource_id, owner_task_id, owner_agent_id, trust_zone_id, status, metadata_json, created_at, updated_at)
              VALUES(?, 'sandbox', ?, ?, ?, ?, 'active', ?, ?, ?)",
@@ -3333,6 +3487,68 @@ mod tests {
         }));
     }
 
+    #[test]
+    fn resource_budgets_update_and_gate_browser_contexts() {
+        let (_dir, mut db) = temp_db();
+        let budgets = db
+            .update_resource_budgets(ResourceBudgetUpdateInput {
+                browser_contexts_max: Some(1),
+                heavy_sandboxes_max: Some(2),
+                ..ResourceBudgetUpdateInput::default()
+            })
+            .unwrap();
+        assert_eq!(budgets.browser_contexts_max, 1);
+        assert_eq!(budgets.heavy_sandboxes_max, 2);
+        db.grant_capability(GrantCapabilityInput {
+            subject_type: "agent".to_string(),
+            subject_id: "agent-a".to_string(),
+            resource_type: "browser_context".to_string(),
+            resource_id: Some("public_web".to_string()),
+            action: "allocate".to_string(),
+            constraints: None,
+            expires_at: None,
+        })
+        .unwrap();
+        db.grant_capability(GrantCapabilityInput {
+            subject_type: "agent".to_string(),
+            subject_id: "agent-a".to_string(),
+            resource_type: "browser_context".to_string(),
+            resource_id: Some("authenticated_web".to_string()),
+            action: "allocate".to_string(),
+            constraints: None,
+            expires_at: None,
+        })
+        .unwrap();
+        let broker = MockBrowserBroker { db: &db };
+        assert!(broker
+            .acquire_context(Some("agent-a"), None, None, "public_web", 10, None)
+            .is_ok());
+        let denied = broker
+            .acquire_context(Some("agent-a"), None, None, "authenticated_web", 10, None)
+            .unwrap_err()
+            .to_string();
+        assert!(denied.contains("browser context budget exhausted"));
+    }
+
+    #[test]
+    fn resource_budgets_gate_heavy_sandboxes() {
+        let (_dir, mut db) = temp_db();
+        db.update_resource_budgets(ResourceBudgetUpdateInput {
+            heavy_sandboxes_max: Some(1),
+            ..ResourceBudgetUpdateInput::default()
+        })
+        .unwrap();
+        let broker = LocalSandboxBroker { db: &db };
+        assert!(broker
+            .allocate_sandbox(None, None, "code_execution", Some("local/no_isolation"))
+            .is_ok());
+        let denied = broker
+            .allocate_sandbox(None, None, "plugin_untrusted", Some("local/no_isolation"))
+            .unwrap_err()
+            .to_string();
+        assert!(denied.contains("heavy sandbox budget exhausted"));
+    }
+
     #[test]
     fn artifact_store_dedupes_and_enforces_access() {
         let (dir, db) = temp_db();

docs/architecture/browser-broker.md

@@ -17,7 +17,7 @@ The `@openclaw/sparsekernel-browser-broker` adapter materializes the ledger leas
 
 When `OPENCLAW_RUNTIME_BROWSER_BROKER=cdp` and `OPENCLAW_SPARSEKERNEL_BROWSER_CDP_ENDPOINT=<loopback endpoint>` are set, the embedded OpenClaw browser tool receives an internal SparseKernel proxy instead of raw CDP access. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=managed` to let SparseKernel ask the existing OpenClaw browser control service to start the managed browser and return its loopback CDP endpoint; `OPENCLAW_SPARSEKERNEL_BROWSER_CONTROL_URL` overrides the default `http://127.0.0.1:18791` control URL.
 
-Set `OPENCLAW_RUNTIME_BROWSER_BROKER=native` to let SparseKernel launch and supervise a local Chromium-compatible process pool by trust zone and profile. The native pool uses a loopback-only remote debugging endpoint, a runtime-owned browser profile directory, and pooled process refcounts; the leased CDP context is released first, then the browser process is stopped after the pool idle timeout. `OPENCLAW_SPARSEKERNEL_BROWSER_MAX_CONTEXTS` caps simultaneous leased contexts per native pool and defaults to `8`. Use `OPENCLAW_SPARSEKERNEL_BROWSER_EXECUTABLE` when Chrome/Chromium is not discoverable on `PATH` or a common platform path. Headless mode is on by default. `OPENCLAW_SPARSEKERNEL_BROWSER_NO_SANDBOX=1` is an explicit opt-out and should only be used when the host environment cannot run Chromium's sandbox.
+Set `OPENCLAW_RUNTIME_BROWSER_BROKER=native` to let SparseKernel launch and supervise a local Chromium-compatible process pool by trust zone and profile. The native pool uses a loopback-only remote debugging endpoint, a runtime-owned browser profile directory, and pooled process refcounts; the leased CDP context is released first, then the browser process is stopped after the pool idle timeout. `OPENCLAW_SPARSEKERNEL_BROWSER_MAX_CONTEXTS` caps simultaneous contexts per native process pool and defaults to `8`; the SparseKernel ledger also enforces the global `resource_budget.browser_contexts_max` lease cap, which defaults to `2` for small machines. Use `OPENCLAW_SPARSEKERNEL_BROWSER_EXECUTABLE` when Chrome/Chromium is not discoverable on `PATH` or a common platform path. Headless mode is on by default. `OPENCLAW_SPARSEKERNEL_BROWSER_NO_SANDBOX=1` is an explicit opt-out and should only be used when the host environment cannot run Chromium's sandbox.
 
 Use `openclaw runtime network-proxy set --trust-zone <id> --proxy-ref <loopback-url>` to attach an existing proxy to a trust-zone network policy, or `openclaw runtime egress-proxy --trust-zone <id> --attach` to start the built-in policy-checking HTTP/CONNECT proxy and attach it. The Rust daemon exposes matching local API endpoints for trust-zone proxy attachment and supervised egress proxy lifecycle; it starts the built-in proxy by default and only launches an operator command when explicitly configured. Set `OPENCLAW_RUNTIME_BROWSER_REQUIRE_PROXY=1` when a trust zone must use a proxy-backed browser egress path. The trust zone's network policy must contain a loopback `proxy_ref`, and native browser pools launch Chromium with `--proxy-server=<proxy_ref>`. Static or externally managed CDP endpoints are rejected in this mode unless `OPENCLAW_RUNTIME_BROWSER_EXTERNAL_PROXY_OK=1` asserts that the external browser process is already proxy-controlled. This protects the SparseKernel-owned browser process path; it is not host-level egress enforcement for arbitrary host processes.
 

docs/architecture/four-gb-vm-design.md

@@ -23,6 +23,6 @@ Five hundred logical agents are feasible because most are parked in SQLite as co
 
 Book-writing and file-writing agents can run at higher active counts than coding agents because they do not all need browsers, sandboxes, test runners, or heavy model contexts. Expensive work should be scarce, leased, and scheduled.
 
-Resource leases let SparseKernel answer which task owned which expensive resource and when it was released or expired. The ledger seeds small-VM resource budgets in `runtime_info` and enforces active task budgets during atomic task claiming: active steps, model calls, file patch jobs, and test jobs can be capped before a worker materializes a harness. Trust-zone budgets are enforced at lease creation for sandbox work: `max_processes` caps active sandbox leases, and `max_runtime_seconds` clamps lease runtime and expiry. This keeps a 4 GB machine from materializing more heavy execution work than its configured task and trust-zone budgets allow.
+Resource leases let SparseKernel answer which task owned which expensive resource and when it was released or expired. The ledger seeds small-VM resource budgets in `runtime_info` and enforces active task budgets during atomic task claiming: active steps, model calls, file patch jobs, and test jobs can be capped before a worker materializes a harness. Browser context and heavy sandbox budgets are enforced at resource-lease creation, so a second pool or trust zone cannot bypass the global small-VM cap. Trust-zone budgets are also enforced at lease creation for sandbox work: `max_processes` caps active sandbox leases inside the zone, and `max_runtime_seconds` clamps lease runtime and expiry. Operators can tune these values with `openclaw runtime budget set --active-agent-steps-max <n> --browser-contexts-max <n> --heavy-sandboxes-max <n>`. This keeps a 4 GB machine from materializing more heavy execution work than its configured task and trust-zone budgets allow.
 
 Browser targets and observations are compact ledger rows, not retained screenshots or traces. This lets small machines keep enough browser provenance to answer which target made a request, emitted console output, or produced an artifact while still pruning old observations with `openclaw runtime prune`.