Skip to main content

session_core/
inspect.rs

1//! The session inspector (`createSessionControl().inspect`, session-control-provider.ts): the read-only host
2//! requests behind RPC `inspect`, `/agents`, `/memory why|list`, `/skills`, `/experiments`, `/goals`, `/progress`
3//! and the Claude Code watch views. A request outside [`INSPECTION_REQUESTS`] is refused before it reaches the
4//! runtime, so inspecting never runs a search, starts work or changes state. Allowed requests go to the session's
5//! host stack as the root lane's requests (the worker's `host.handle(request, payload)`), outside any cell.
6
7use kernel::{HostHandler, Signal};
8use serde_json::{Map, Value};
9
10/// Read-only host requests the inspector may issue (`INSPECTION_REQUESTS` of session-control.ts, without
11/// `grants.list`: there is no grant system). None of them
12/// runs a search or starts work.
13pub const INSPECTION_REQUESTS: [&str; 25] = [
14    "agents.status",
15    "agents.list",
16    "agents.inspect",
17    "memory.why",
18    "memory.list",
19    "skills.list",
20    "skills.why",
21    "experiments.list",
22    "refinements.list",
23    "progress.history",
24    "progress.assess",
25    "schedules.list",
26    // The session's scheduled prompts (`/schedules`; Rust-only).
27    "schedule.list",
28    "goals.list",
29    "goals.get",
30    "instances.list",
31    "instances.get",
32    "gates.list",
33    "gates.history",
34    "rlm.pool",
35    "rlm.frames",
36    "ctx.state",
37    "async.pending",
38    // The root lane's detached cells with their start times, for the TUI's running-work panel (Rust-only; the
39    // worker answers it itself).
40    "rlm.detached",
41    "usage.report",
42];
43
44/// The inspections `ultron claude`'s watch viewer may make through its control socket (`READ_ONLY_INSPECTIONS` of
45/// claude/mcp-server.ts): the [`INSPECTION_REQUESTS`] the rlm-views poller sends, plus `async.pending` and
46/// `usage.report`.
47pub const VIEWER_INSPECTIONS: [&str; 8] = [
48    "agents.status",
49    "instances.list",
50    "rlm.pool",
51    "ctx.state",
52    "rlm.frames",
53    "progress.assess",
54    "async.pending",
55    "usage.report",
56];
57
58/// `inspect(request, payload)`: refuse anything but an inspection request, then ask `runtime` (none: the session
59/// has no Ultron runtime). A null payload is an empty one; any other non-object is refused.
60pub fn inspect(
61    runtime: Option<&dyn HostHandler>,
62    request: &str,
63    payload: Value,
64    signal: &Signal,
65) -> Result<Value, String> {
66    if !INSPECTION_REQUESTS.contains(&request) {
67        return Err(format!("Not an inspection request: {request}"));
68    }
69    let runtime = runtime.ok_or("This Session has no Ultron runtime to inspect")?;
70    let body = match payload {
71        Value::Null => Map::new(),
72        Value::Object(body) => body,
73        _ => return Err("Inspection payload must be an object".into()),
74    };
75    runtime.handle(request, body, signal)
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81
82    #[test]
83    fn session_core_viewer_inspections_are_inspection_requests() {
84        for request in VIEWER_INSPECTIONS {
85            assert!(INSPECTION_REQUESTS.contains(&request), "{request}");
86        }
87    }
88}