From d28244ee1d9964838de5f8683f99ce4778719fa9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 8 May 2026 09:09:34 +0000
Subject: [PATCH] soft-trace-viewer: search across traces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a `/api/search?q=...` endpoint and a search box in the embedded
HTML so operators can find traces by content (e.g. find every run
where depot's gate denied, by querying "Deny" or "grid_budget").

Backend:

  - New `GET /api/search?q=<query>` route. Naive case-insensitive
    substring scan across each trace's serialized JSON. Returns
    `{"query": "...", "scanned": N, "results": [{run_id, snippet,
    match_offset}, ...]}`. Snippet is ~80 characters centered on the
    match, snapped to UTF-8 boundaries.
  - Empty `q` returns `{results: [], query: ""}` rather than 400 — UI
    sends the empty case during typing.
  - Minimal `application/x-www-form-urlencoded` decoder for
    `+` → space and `%XX` → byte. Sufficient for the search box;
    not a full URL parser.

For Phase 1 trace volumes (~1 KB per trace, dozens of traces) the
naive scan is fast enough. If the store grows past a few thousand
traces, this would benefit from `lex-search` (lex 0.3 #224) or a
precomputed inverted index.

Frontend:

  - Search input in the header. 200 ms debounced; calls
    `/api/search?q=<encoded>` and dims non-matching sidebar entries.
    Matching entries get a snippet line below the run-id with the
    matched substring `<mark>`-highlighted.
  - Result counter: "N / M" (matches / scanned) next to the input.

Tests (4 new in `crates/soft-trace-viewer/tests/smoke.rs`):

  - search with no `q` returns empty list
  - search on empty store returns zero results
  - URL-decoding works for both `%20` and `+`
  - end-to-end: drive a real soft-agent runner, persist a trace
    containing a known token, then verify search finds it. Negative
    case verifies an unrelated query returns zero matches.

cargo fmt clean, cargo clippy --workspace --all-targets -- -D warnings
clean, full workspace test suite: 102 passed / 0 failed.
---
 Cargo.lock                              |   1 +
 crates/soft-trace-viewer/Cargo.toml     |   6 +-
 crates/soft-trace-viewer/src/index.html |  77 +++++++++++++-
 crates/soft-trace-viewer/src/main.rs    | 129 +++++++++++++++++++++-
 crates/soft-trace-viewer/tests/smoke.rs | 136 ++++++++++++++++++++++++
 5 files changed, 342 insertions(+), 7 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 0c9f123..9ce979e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1839,6 +1839,7 @@ dependencies = [
  "lex-store",
  "serde",
  "serde_json",
+ "soft-agent",
  "tempfile",
  "tiny_http",
  "ureq 2.12.1",
diff --git a/crates/soft-trace-viewer/Cargo.toml b/crates/soft-trace-viewer/Cargo.toml
index ec9b27d..c4b2789 100644
--- a/crates/soft-trace-viewer/Cargo.toml
+++ b/crates/soft-trace-viewer/Cargo.toml
@@ -20,5 +20,7 @@ serde_json = { workspace = true }
 tiny_http  = { workspace = true }
 
 [dev-dependencies]
-tempfile = "3"
-ureq     = { workspace = true }
+tempfile   = "3"
+ureq       = { workspace = true }
+# End-to-end search test produces a real trace via soft-agent's runner.
+soft-agent = { path = "../soft-agent" }
diff --git a/crates/soft-trace-viewer/src/index.html b/crates/soft-trace-viewer/src/index.html
index 1b6491a..566113f 100644
--- a/crates/soft-trace-viewer/src/index.html
+++ b/crates/soft-trace-viewer/src/index.html
@@ -20,6 +20,12 @@
            display: flex; align-items: baseline; gap: 12px; }
   header h1 { font-size: 14px; margin: 0; font-weight: 600; }
   header .meta { color: var(--muted); font-size: 12px; }
+  header input.search { margin-left: auto; min-width: 240px; padding: 4px 8px;
+                        font-size: 12px; background: var(--bg); color: var(--fg);
+                        border: 1px solid var(--border); border-radius: 3px;
+                        font-family: monospace; }
+  header input.search:focus { outline: none; border-color: var(--accent); }
+  header .search-count { color: var(--muted); font-size: 11px; min-width: 60px; }
   main { display: grid; grid-template-columns: 280px 1fr; height: calc(100vh - 38px); }
   #sidebar { border-right: 1px solid var(--border); overflow-y: auto; padding: 8px 0;
              background: var(--panel); }
@@ -28,6 +34,11 @@
   #sidebar .trace:hover { color: var(--fg); background: rgba(88, 166, 255, 0.05); }
   #sidebar .trace.active { color: var(--accent); border-left-color: var(--accent);
                            background: rgba(88, 166, 255, 0.08); }
+  #sidebar .trace.dimmed { opacity: 0.25; }
+  #sidebar .trace .snippet { display: block; font-size: 10px; color: var(--muted);
+                             margin-top: 2px; word-break: break-all; }
+  #sidebar .trace .snippet mark { background: rgba(88, 166, 255, 0.25);
+                                  color: var(--fg); padding: 0; }
   #content { overflow-y: auto; padding: 16px 24px; }
   .placeholder { color: var(--muted); font-style: italic; }
   .node { margin: 4px 0; }
@@ -56,12 +67,19 @@
 <header>
   <h1>soft trace viewer</h1>
   <span class="meta">click a run id to load its trace</span>
+  <input class="search" id="search" type="search"
+         placeholder="search across traces (e.g. depot, gate.verdict, deny)"
+         autocomplete="off" spellcheck="false">
+  <span class="search-count" id="search-count"></span>
 </header>
 <main>
   <div id="sidebar"><div class="placeholder" style="padding: 0 16px;">loading…</div></div>
   <div id="content"><div class="placeholder">Select a trace from the sidebar.</div></div>
 </main>
 <script>
+// Track sidebar entries so search can dim non-matching ones.
+let sidebarEntries = [];   // [{ id, el }]
+
 async function loadTraces() {
   const sb = document.getElementById('sidebar');
   try {
@@ -72,13 +90,17 @@ <h1>soft trace viewer</h1>
       return;
     }
     sb.innerHTML = '';
+    sidebarEntries = [];
     data.traces.forEach(id => {
       const el = document.createElement('div');
       el.className = 'trace';
-      el.textContent = id.slice(0, 16) + (id.length > 16 ? '…' : '');
+      const head = document.createElement('span');
+      head.textContent = id.slice(0, 16) + (id.length > 16 ? '…' : '');
+      el.appendChild(head);
       el.title = id;
       el.onclick = () => selectTrace(id, el);
       sb.appendChild(el);
+      sidebarEntries.push({ id, el });
     });
   } catch (e) {
     sb.innerHTML = '<div class="placeholder" style="padding: 0 16px; color: var(--err);">'
@@ -86,6 +108,59 @@ <h1>soft trace viewer</h1>
   }
 }
 
+// --- search ---
+
+let searchTimer = null;
+
+document.getElementById('search').addEventListener('input', e => {
+  clearTimeout(searchTimer);
+  const q = e.target.value;
+  searchTimer = setTimeout(() => runSearch(q), 200);
+});
+
+async function runSearch(q) {
+  const countEl = document.getElementById('search-count');
+  // Clear any prior dim/snippet state.
+  sidebarEntries.forEach(({ el }) => {
+    el.classList.remove('dimmed');
+    const oldSnippet = el.querySelector('.snippet');
+    if (oldSnippet) oldSnippet.remove();
+  });
+  if (!q.trim()) {
+    countEl.textContent = '';
+    return;
+  }
+  countEl.textContent = 'searching…';
+  try {
+    const res = await fetch('/api/search?q=' + encodeURIComponent(q));
+    const data = await res.json();
+    const matchedIds = new Set(data.results.map(r => r.run_id));
+    const snippets = new Map(data.results.map(r => [r.run_id, r.snippet]));
+    sidebarEntries.forEach(({ id, el }) => {
+      if (matchedIds.has(id)) {
+        const s = document.createElement('span');
+        s.className = 'snippet';
+        s.innerHTML = highlightSnippet(snippets.get(id) || '', q);
+        el.appendChild(s);
+      } else {
+        el.classList.add('dimmed');
+      }
+    });
+    countEl.textContent = data.results.length + ' / ' + data.scanned;
+  } catch (e) {
+    countEl.textContent = 'err';
+  }
+}
+
+function highlightSnippet(snippet, q) {
+  // Case-insensitive highlight with HTML escape.
+  const escaped = escapeHtml(snippet);
+  const ql = escapeHtml(q);
+  if (!ql) return escaped;
+  const re = new RegExp('(' + ql.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')', 'gi');
+  return escaped.replace(re, '<mark>$1</mark>');
+}
+
 async function selectTrace(id, el) {
   document.querySelectorAll('#sidebar .trace.active').forEach(n => n.classList.remove('active'));
   el.classList.add('active');
diff --git a/crates/soft-trace-viewer/src/main.rs b/crates/soft-trace-viewer/src/main.rs
index a9f7cef..bd9aed1 100644
--- a/crates/soft-trace-viewer/src/main.rs
+++ b/crates/soft-trace-viewer/src/main.rs
@@ -1,9 +1,12 @@
 //! Tiny HTTP viewer for lex-store traces.
 //!
-//! Serves three things:
-//!   - `GET /`              → embedded `index.html` (vanilla JS, no deps)
-//!   - `GET /api/traces`    → JSON array of run IDs in the store
-//!   - `GET /api/trace/<id>`→ the full `TraceTree` as JSON
+//! Serves four things:
+//!   - `GET /`                  → embedded `index.html` (vanilla JS, no deps)
+//!   - `GET /api/traces`        → JSON array of run IDs in the store
+//!   - `GET /api/trace/<id>`    → the full `TraceTree` as JSON
+//!   - `GET /api/search?q=...`  → list of trace ids whose contents
+//!     contain the (case-insensitive) substring `q`, plus a one-line
+//!     snippet from the first matching node.
 //!
 //! Designed to be a one-process companion to `soft-run` containers
 //! sharing a `/traces` volume. No auth — assume the bind address is
@@ -119,10 +122,128 @@ fn handle(req: Request, store: &Store) {
                 Err(e) => respond_text(req, &format!("load_trace {id}: {e}"), 404),
             }
         }
+        (Method::Get, path) if path.starts_with("/api/search") => {
+            handle_search(req, store, path);
+        }
         _ => respond_text(req, "not found", 404),
     }
 }
 
+/// Naive case-insensitive substring search over each trace's
+/// serialized JSON. For Phase 1 trace volumes (~1 KB per trace,
+/// ~tens of traces) this is fast enough; if the store grows past a
+/// few thousand traces this would benefit from `lex-search` (lex 0.3
+/// #224) or a precomputed inverted index.
+fn handle_search(req: Request, store: &Store, raw_path: &str) {
+    let q = match raw_path
+        .split_once('?')
+        .and_then(|(_, qs)| query_param(qs, "q"))
+    {
+        Some(q) if !q.trim().is_empty() => q.to_lowercase(),
+        _ => {
+            respond_json(req, &json!({"results": [], "query": ""}), 200);
+            return;
+        }
+    };
+
+    let ids = match store.list_traces() {
+        Ok(ids) => ids,
+        Err(e) => {
+            respond_text(req, &format!("list_traces: {e}"), 500);
+            return;
+        }
+    };
+
+    let mut results: Vec<serde_json::Value> = Vec::new();
+    for id in &ids {
+        let tree = match store.load_trace(id) {
+            Ok(t) => t,
+            Err(_) => continue,
+        };
+        let body = match serde_json::to_string(&tree) {
+            Ok(s) => s,
+            Err(_) => continue,
+        };
+        let lower = body.to_lowercase();
+        if let Some(pos) = lower.find(&q) {
+            // Build a ~80-char snippet centered on the match.
+            let snippet_start = pos.saturating_sub(30);
+            let snippet_end = (pos + q.len() + 50).min(body.len());
+            // Snap to UTF-8 boundaries.
+            let snippet_start = body
+                .char_indices()
+                .map(|(i, _)| i)
+                .take_while(|&i| i <= snippet_start)
+                .last()
+                .unwrap_or(0);
+            let snippet_end = body
+                .char_indices()
+                .map(|(i, _)| i)
+                .find(|&i| i >= snippet_end)
+                .unwrap_or(body.len());
+            let snippet = &body[snippet_start..snippet_end];
+            results.push(json!({
+                "run_id": id,
+                "snippet": snippet,
+                "match_offset": pos,
+            }));
+        }
+    }
+
+    respond_json(
+        req,
+        &json!({
+            "query": q,
+            "results": results,
+            "scanned": ids.len(),
+        }),
+        200,
+    );
+}
+
+/// Minimal `application/x-www-form-urlencoded` query-string parser.
+/// Returns the first value for `key`, decoded for the simple
+/// `+` → space and `%XX` → byte cases. Sufficient for our search
+/// box; not a full URL parser.
+fn query_param(qs: &str, key: &str) -> Option<String> {
+    for pair in qs.split('&') {
+        let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
+        if k == key {
+            return Some(percent_decode(v));
+        }
+    }
+    None
+}
+
+fn percent_decode(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    let bytes = s.as_bytes();
+    let mut i = 0;
+    while i < bytes.len() {
+        match bytes[i] {
+            b'+' => {
+                out.push(' ');
+                i += 1;
+            }
+            b'%' if i + 2 < bytes.len() => {
+                let hex = std::str::from_utf8(&bytes[i + 1..i + 3]).unwrap_or("");
+                if let Ok(byte) = u8::from_str_radix(hex, 16) {
+                    out.push(byte as char);
+                    i += 3;
+                } else {
+                    out.push(bytes[i] as char);
+                    i += 1;
+                }
+            }
+            other => {
+                out.push(other as char);
+                i += 1;
+            }
+        }
+    }
+    out
+}
+
 fn respond_html(req: Request, body: &str, status: u16) {
     let header = Header::from_bytes(&b"Content-Type"[..], &b"text/html; charset=utf-8"[..])
         .expect("static content-type header is well-formed");
diff --git a/crates/soft-trace-viewer/tests/smoke.rs b/crates/soft-trace-viewer/tests/smoke.rs
index 5eff61b..88be4d8 100644
--- a/crates/soft-trace-viewer/tests/smoke.rs
+++ b/crates/soft-trace-viewer/tests/smoke.rs
@@ -118,3 +118,139 @@ fn unknown_path_returns_404() {
     };
     assert_eq!(status, 404);
 }
+
+#[test]
+fn search_with_no_q_returns_empty() {
+    let dir = tempdir().unwrap();
+    let port = pick_ephemeral_port();
+    let _proc = spawn(dir.path().to_str().unwrap(), port);
+
+    let url = format!("http://127.0.0.1:{port}/api/search");
+    let resp = ureq::get(&url)
+        .timeout(Duration::from_secs(2))
+        .call()
+        .expect("GET /api/search");
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.into_json().unwrap();
+    assert_eq!(body["results"], serde_json::json!([]));
+    assert_eq!(body["query"], "");
+}
+
+#[test]
+fn search_empty_store_returns_zero_results() {
+    let dir = tempdir().unwrap();
+    let port = pick_ephemeral_port();
+    let _proc = spawn(dir.path().to_str().unwrap(), port);
+
+    let url = format!("http://127.0.0.1:{port}/api/search?q=anything");
+    let resp = ureq::get(&url)
+        .timeout(Duration::from_secs(2))
+        .call()
+        .expect("GET /api/search?q=…");
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.into_json().unwrap();
+    assert_eq!(body["results"], serde_json::json!([]));
+    assert_eq!(body["scanned"], 0);
+    assert_eq!(body["query"], "anything");
+}
+
+#[test]
+fn search_url_decodes_query() {
+    let dir = tempdir().unwrap();
+    let port = pick_ephemeral_port();
+    let _proc = spawn(dir.path().to_str().unwrap(), port);
+
+    // %20 → space, + → space.
+    let url = format!("http://127.0.0.1:{port}/api/search?q=hello%20world");
+    let resp = ureq::get(&url)
+        .timeout(Duration::from_secs(2))
+        .call()
+        .expect("GET");
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.into_json().unwrap();
+    assert_eq!(body["query"], "hello world");
+
+    let url = format!("http://127.0.0.1:{port}/api/search?q=hello+world");
+    let resp = ureq::get(&url)
+        .timeout(Duration::from_secs(2))
+        .call()
+        .expect("GET");
+    let body: serde_json::Value = resp.into_json().unwrap();
+    assert_eq!(body["query"], "hello world");
+}
+
+#[test]
+fn search_finds_matching_trace_via_real_runner() {
+    // End-to-end: drive a real soft-agent runner, persist a trace,
+    // then start the viewer against the same store and verify search
+    // finds a known token from the agent's outbound message.
+    use serde_json::json;
+    use soft_agent::{A2aMessage, Action, AgentConfig, Effect, Mailbox, Runner};
+
+    let dir = tempdir().unwrap();
+    let store = lex_store::Store::open(dir.path()).unwrap();
+
+    let agent = AgentConfig::new("vehicle")
+        .peers(["depot"])
+        .effects([Effect::A2a])
+        .build()
+        .unwrap();
+    let (mailbox, sender) = Mailbox::new();
+    let mut runner = Runner::builder()
+        .agent(agent)
+        .state(json!({}))
+        .mailbox(mailbox)
+        .handle("Dispatch", |_state, msg| {
+            vec![Action::SendA2a {
+                peer: msg.from.clone(),
+                topic: "Acknowledge".into(),
+                payload: json!({"unique_token_searchable": true}),
+            }]
+        })
+        .build()
+        .unwrap();
+
+    sender
+        .send(A2aMessage {
+            from: "tester".into(),
+            topic: "Dispatch".into(),
+            payload: json!({}),
+        })
+        .unwrap();
+    runner.drain().unwrap();
+    runner.finalize(&store).unwrap();
+
+    let port = pick_ephemeral_port();
+    let _proc = spawn(dir.path().to_str().unwrap(), port);
+
+    // Search for the token we embedded in the SendA2a payload.
+    let url = format!("http://127.0.0.1:{port}/api/search?q=unique_token_searchable");
+    let resp = ureq::get(&url)
+        .timeout(Duration::from_secs(2))
+        .call()
+        .expect("GET search");
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.into_json().unwrap();
+    let results = body["results"].as_array().expect("results array");
+    assert_eq!(
+        results.len(),
+        1,
+        "expected exactly one trace to match, got: {body}"
+    );
+    let snippet = results[0]["snippet"].as_str().unwrap();
+    assert!(
+        snippet.contains("unique_token_searchable"),
+        "snippet should include the matched substring; got: {snippet}"
+    );
+
+    // Negative case: an unrelated query returns no results.
+    let url = format!("http://127.0.0.1:{port}/api/search?q=definitely_not_in_any_trace_zzz");
+    let body: serde_json::Value = ureq::get(&url)
+        .timeout(Duration::from_secs(2))
+        .call()
+        .unwrap()
+        .into_json()
+        .unwrap();
+    assert_eq!(body["results"], serde_json::json!([]));
+    assert_eq!(body["scanned"], 1);
+}