Skip to main content

qualia_client_core/
browser_agent.rs

1//! **Browser agent (P2 / B4)** — page-aware helper for the Webizen browser.
2//!
3//! Scope (honest):
4//! - Structured intents: `summarise` | `trust` | `privacy` | `navigate_help` | `general`.
5//! - Always return provenance + CML signals + trust verdict.
6//! - Optionally ingest page topics into the hypermedia library.
7//! - Deterministic grounded answers (no unbounded tools; 20s fetch timeout).
8//! - Local LLM path is optional and not required for acceptance.
9
10use std::path::Path;
11use std::time::{SystemTime, UNIX_EPOCH};
12
13use serde::{Deserialize, Serialize};
14
15use crate::webizen_trust::{self, TrustStore, TrustVerdict};
16use crate::wellfair::cml_context::{build_document_context, units_from_headings, ContextUnit};
17use crate::wellfair::hypermedia_store::{
18    CommonsVisibility, HypermediaStore, LibraryEntry, LibrarySection,
19};
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(rename_all = "snake_case")]
23pub enum BrowserAgentIntent {
24    Summarise,
25    Trust,
26    Privacy,
27    NavigateHelp,
28    General,
29}
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
32pub struct BrowserAgentRequest {
33    pub url: String,
34    pub question: String,
35    /// When true, write a library entry under Work for page topics.
36    #[serde(default)]
37    pub ingest_to_library: bool,
38}
39
40#[derive(Debug, Clone, Serialize, Deserialize)]
41pub struct BrowserAgentResponse {
42    pub url: String,
43    pub answer: String,
44    pub intent: String,
45    pub trust: TrustVerdict,
46    pub cml_signals: Vec<String>,
47    pub topics: Vec<String>,
48    pub deontic_norms: usize,
49    pub privacy_hits: usize,
50    pub page_excerpt: String,
51    pub provenance: Vec<String>,
52    pub library_asset_uri: Option<String>,
53    pub curation: String,
54}
55
56fn now_unix() -> u64 {
57    SystemTime::now()
58        .duration_since(UNIX_EPOCH)
59        .map(|d| d.as_secs())
60        .unwrap_or(0)
61}
62
63/// Classify the user question into a bounded intent.
64pub fn classify_intent(question: &str) -> BrowserAgentIntent {
65    let q = question.trim().to_ascii_lowercase();
66    if q.is_empty() {
67        return BrowserAgentIntent::Summarise;
68    }
69    if q.contains("trust")
70        || q.contains("certificate")
71        || q.contains("secure")
72        || q.contains("trusted")
73        || q.contains("is this safe")
74    {
75        return BrowserAgentIntent::Trust;
76    }
77    if q.contains("privacy")
78        || q.contains("gdpr")
79        || q.contains("personal data")
80        || q.contains("cookie")
81        || q.contains("tracker")
82    {
83        return BrowserAgentIntent::Privacy;
84    }
85    if q.contains("how do i")
86        || q.contains("navigate")
87        || q.contains("where is")
88        || q.contains("open ")
89        || q.contains("bookmark")
90    {
91        return BrowserAgentIntent::NavigateHelp;
92    }
93    if q.contains("about")
94        || q.contains("summar")
95        || q.contains("what is")
96        || q.contains("page")
97        || q.contains("tell me")
98    {
99        return BrowserAgentIntent::Summarise;
100    }
101    BrowserAgentIntent::General
102}
103
104/// How agent HTTPS was configured (honesty for answers + UI).
105#[derive(Debug, Clone, Serialize, Deserialize)]
106pub struct AgentTlsStatus {
107    pub mode: String,
108    pub n_custom_roots: usize,
109    pub note: String,
110}
111
112/// Agent TLS status.
113pub fn agent_tls_status(storage_root: &Path) -> AgentTlsStatus {
114    use crate::webizen_x509::{agent_tls_mode, AgentTlsMode};
115    let store = TrustStore::load(storage_root);
116    match agent_tls_mode(&store) {
117        AgentTlsMode::CustomRootsOnly { n_roots } => AgentTlsStatus {
118            mode: "custom_enabled_pems_only".into(),
119            n_custom_roots: n_roots,
120            note: "Agent HTTPS: tls_certs_only(principal PEMs) — platform roots off; same enabled set as cert policy B.".into(),
121        },
122        AgentTlsMode::SystemDefault => AgentTlsStatus {
123            mode: "system_default".into(),
124            n_custom_roots: 0,
125            note: "No enabled PEM roots — agent uses default reqwest/rustls roots (not Webizen-custom). WebView TLS remains OS-mediated.".into(),
126        },
127    }
128}
129
130/// Build reqwest client: custom roots when enabled PEMs present; else system default.
131pub fn build_agent_http_client(
132    storage_root: &Path,
133) -> Result<(reqwest::Client, AgentTlsStatus), String> {
134    use crate::webizen_x509::{agent_tls_mode, root_cert_store_from_trust, AgentTlsMode};
135    let store = TrustStore::load(storage_root);
136    let status = agent_tls_status(storage_root);
137    let builder = reqwest::Client::builder()
138        .timeout(std::time::Duration::from_secs(20))
139        .user_agent("WebizenBrowserAgent/0.0.25 (+https://ns.webcivics.net)");
140
141    match agent_tls_mode(&store) {
142        AgentTlsMode::CustomRootsOnly { n_roots } => {
143            // Custom-only: tls_certs_only() disables platform roots (reqwest 0.13).
144            let mut certs: Vec<reqwest::Certificate> = Vec::new();
145            for a in store
146                .anchors
147                .iter()
148                .filter(|a| a.enabled && a.kind == webizen_trust::AnchorKind::PemRoot)
149            {
150                match reqwest::Certificate::from_pem(a.material.as_bytes()) {
151                    Ok(cert) => certs.push(cert),
152                    Err(_) => {
153                        if let Ok(ders) = crate::webizen_x509::pem_to_ders(&a.material) {
154                            for der in ders {
155                                let pem = der_to_pem_cert(&der);
156                                if let Ok(cert) = reqwest::Certificate::from_pem(pem.as_bytes()) {
157                                    certs.push(cert);
158                                }
159                            }
160                        }
161                    }
162                }
163            }
164            if certs.is_empty() {
165                return Err("enabled PEM roots present but none parsed into certificates".into());
166            }
167            let added = certs.len();
168            let _ = root_cert_store_from_trust(&store); // validate same path as B
169            let client = builder
170                .tls_certs_only(certs)
171                .build()
172                .map_err(|e| e.to_string())?;
173            let mut st = status;
174            st.mode = "custom_enabled_pems_only".into();
175            st.n_custom_roots = n_roots.max(added);
176            st.note = format!(
177                "Agent HTTPS: custom-only TLS with {added} principal PEM root(s) \
178                 (platform roots disabled via tls_certs_only). Same store as cert policy B. \
179                 WebView TLS remains OS + ServerCertificateErrorDetected override hook."
180            );
181            Ok((client, st))
182        }
183        AgentTlsMode::SystemDefault => {
184            let client = builder.build().map_err(|e| e.to_string())?;
185            Ok((client, status))
186        }
187    }
188}
189
190fn der_to_pem_cert(der: &[u8]) -> String {
191    let b64 = base64::Engine::encode(&base64::engine::general_purpose::STANDARD, der);
192    let mut out = String::from("-----BEGIN CERTIFICATE-----\n");
193    for chunk in b64.as_bytes().chunks(64) {
194        out.push_str(std::str::from_utf8(chunk).unwrap_or(""));
195        out.push('\n');
196    }
197    out.push_str("-----END CERTIFICATE-----\n");
198    out
199}
200
201/// Fetch page body (best-effort HTML → text). Aligns TLS policy with trust store when possible.
202pub async fn fetch_page_text(url: &str) -> Result<String, String> {
203    fetch_page_text_with_storage(
204        url,
205        &std::path::PathBuf::from(crate::state::dirs_default_path()),
206    )
207    .await
208}
209
210/// Fetches page-text-with-storage.
211pub async fn fetch_page_text_with_storage(
212    url: &str,
213    storage_root: &Path,
214) -> Result<String, String> {
215    let u = url.trim();
216    if u.starts_with("qualia://") || u.starts_with("webizen://") {
217        return Ok(format!(
218            "Local Webizen resource: {u}\n(Content is served by the desktop protocol handler, not HTTP.)"
219        ));
220    }
221    let (client, _tls) = build_agent_http_client(storage_root)?;
222    let resp = client.get(u).send().await.map_err(|e| e.to_string())?;
223    if !resp.status().is_success() {
224        return Err(format!("HTTP {}", resp.status()));
225    }
226    let html = resp.text().await.map_err(|e| e.to_string())?;
227    Ok(html_to_text(&html))
228}
229
230fn html_to_text(html: &str) -> String {
231    let mut text = String::new();
232    let doc = scraper::Html::parse_document(html);
233    let sel = scraper::Selector::parse("body").ok();
234    if let Some(sel) = sel {
235        if let Some(body) = doc.select(&sel).next() {
236            text = body.text().collect::<Vec<_>>().join(" ");
237        }
238    }
239    if text.trim().is_empty() {
240        let mut out = String::new();
241        let mut in_tag = false;
242        for c in html.chars() {
243            match c {
244                '<' => in_tag = true,
245                '>' => in_tag = false,
246                _ if !in_tag => out.push(c),
247                _ => {}
248            }
249        }
250        text = out;
251    }
252    text.split_whitespace().collect::<Vec<_>>().join(" ")
253}
254
255fn build_answer(
256    intent: BrowserAgentIntent,
257    question: &str,
258    url: &str,
259    page: &str,
260    trust: &TrustVerdict,
261    signals: &[String],
262    topics: &[String],
263) -> String {
264    let excerpt: String = page.chars().take(600).collect();
265    let signal_join = |cap: usize| {
266        if signals.is_empty() && topics.is_empty() {
267            "(none extracted)".into()
268        } else {
269            signals
270                .iter()
271                .chain(topics.iter())
272                .take(cap)
273                .cloned()
274                .collect::<Vec<_>>()
275                .join(", ")
276        }
277    };
278
279    match intent {
280        BrowserAgentIntent::Trust => {
281            let tls = agent_tls_status(Path::new(
282                &std::env::var("QUALIA_STORAGE")
283                    .unwrap_or_else(|_| crate::state::dirs_default_path()),
284            ));
285            format!(
286                "Trust verdict for {url}: **{}** — {}\n\
287                 Matching anchors: {}\n\
288                 Notes: {}\n\
289                 Cert policy: default **deny**; host-pin (A) allows; enabled PEM roots (B) only after chain verify; \
290                 never auto-allow; Allow once/Always/Deny are logged escape hatches (no WebID-TLS nag loops).\n\
291                 Agent TLS mode: {} — {}\n\
292                 (WebView TLS: OS + ServerCertificateErrorDetected hook; this verdict is Webizen policy + store.)",
293                trust.level,
294                trust.summary,
295                if trust.matching_anchors.is_empty() {
296                    "none".into()
297                } else {
298                    trust.matching_anchors.join(", ")
299                },
300                trust.notes.join(" · "),
301                tls.mode,
302                tls.note,
303            )
304        }
305        BrowserAgentIntent::Summarise => format!(
306            "Page: {url}\n\
307             Trust: {} ({})\n\
308             Topics/signals: {}\n\
309             Excerpt (grounded in fetched text):\n{excerpt}{}",
310            trust.level,
311            trust.summary,
312            signal_join(16),
313            if page.len() > 600 { "…" } else { "" }
314        ),
315        BrowserAgentIntent::Privacy => {
316            let privacy_sigs: Vec<_> = signals
317                .iter()
318                .filter(|s| s.starts_with("privacy:"))
319                .cloned()
320                .collect();
321            format!(
322                "Privacy signals on {url}: {}\n\
323                 Trust: {}.\n\
324                 Grounded excerpt: {excerpt}{}",
325                if privacy_sigs.is_empty() {
326                    "none detected by deterministic extractors (privacy:* tags)".into()
327                } else {
328                    privacy_sigs.join(", ")
329                },
330                trust.level,
331                if page.len() > 600 { "…" } else { "" }
332            )
333        }
334        BrowserAgentIntent::NavigateHelp => format!(
335            "Webizen Browser help for {url}:\n\
336             · Omnibox Go / back / forward / reload in chrome\n\
337             · 🔖 saves a bookmark (qlinks + Library purpose=bookmark)\n\
338             · Trust panel manages your DID/PEM store (agent policy; OS TLS separate)\n\
339             · Agent answers summarise / trust / privacy about the current page\n\
340             Question was: {question}\n\
341             Current trust: {} — {}",
342            trust.level, trust.summary
343        ),
344        BrowserAgentIntent::General => format!(
345            "Question: {question}\n\
346             URL: {url}\n\
347             Trust: {} — {}\n\
348             Detected: {}\n\
349             Grounded excerpt:\n{excerpt}{}\n\
350             Provenance: fetched page text + CML context extractors + Webizen trust store (cml:Proposed).",
351            trust.level,
352            trust.summary,
353            signal_join(12),
354            if page.len() > 600 { "…" } else { "" }
355        ),
356    }
357}
358
359/// Run the browser agent against the current page.
360pub async fn run_browser_agent(
361    storage_root: &Path,
362    req: BrowserAgentRequest,
363) -> Result<BrowserAgentResponse, String> {
364    let intent = classify_intent(&req.question);
365    let store = TrustStore::load(storage_root);
366    let trust = webizen_trust::evaluate_url(&store, &req.url);
367    let page = fetch_page_text(&req.url)
368        .await
369        .unwrap_or_else(|e| format!("(fetch failed: {e})"));
370
371    let units = if page.len() > 80 {
372        units_from_headings(&page)
373    } else {
374        vec![ContextUnit {
375            frag: "page".into(),
376            kind: "document".into(),
377            label: req.url.clone(),
378            text: page.clone(),
379            page: None,
380            parent: None,
381        }]
382    };
383    let g = build_document_context(&req.url, &req.url, &units);
384
385    let answer = build_answer(
386        intent,
387        &req.question,
388        &req.url,
389        &page,
390        &trust,
391        &g.signal_tags,
392        &g.topics,
393    );
394
395    let mut library_asset_uri = None;
396    if req.ingest_to_library && page.len() > 40 {
397        let store_lib = HypermediaStore::open(storage_root).map_err(|e| e.to_string())?;
398        let uri = format!("urn:webizen:browser-page:{}", short_id(req.url.as_bytes()));
399        let mut entry = LibraryEntry {
400            asset_uri: uri.clone(),
401            primary_subject: fnv60(uri.as_bytes()),
402            media_type: "text/html".into(),
403            quins: g.quins.clone(),
404            topics: g.topics.clone(),
405            projects: vec!["browser".into()],
406            purposes: {
407                let mut p = g.purposes.clone();
408                p.push("browser".into());
409                p.push("research".into());
410                p
411            },
412            place: None,
413            occurred_at: None,
414            lat: None,
415            lon: None,
416            flags: Vec::new(),
417            ingested_unix: now_unix(),
418            excerpt: page.chars().take(400).collect(),
419            sensitivity: "public".into(),
420            section: LibrarySection::Work.as_str().into(),
421            commons_visibility: CommonsVisibility::None,
422            cml_signals: g.signal_tags.clone(),
423            cml_concept_count: g.concepts.len() as u32,
424            cml_n3: g.n3.chars().take(24_000).collect(),
425            cof_html: String::new(),
426            cof_segment_count: 0,
427            cof_segment_index: 0,
428            cof_profile: String::new(),
429        };
430        entry.recompute_section();
431        store_lib.add(entry).map_err(|e| e.to_string())?;
432        library_asset_uri = Some(uri);
433    }
434
435    let intent_str = match intent {
436        BrowserAgentIntent::Summarise => "summarise",
437        BrowserAgentIntent::Trust => "trust",
438        BrowserAgentIntent::Privacy => "privacy",
439        BrowserAgentIntent::NavigateHelp => "navigate_help",
440        BrowserAgentIntent::General => "general",
441    };
442
443    Ok(BrowserAgentResponse {
444        url: req.url,
445        answer,
446        intent: intent_str.into(),
447        trust,
448        cml_signals: g.signal_tags,
449        topics: g.topics,
450        deontic_norms: g.deontic_norms,
451        privacy_hits: g.privacy_hits,
452        page_excerpt: page.chars().take(800).collect(),
453        provenance: vec![
454            "page-fetch".into(),
455            "cml_context".into(),
456            "webizen_trust".into(),
457            "cml:Proposed".into(),
458            format!("intent:{intent_str}"),
459        ],
460        library_asset_uri,
461        curation: "cml:Proposed".into(),
462    })
463}
464
465fn short_id(bytes: &[u8]) -> String {
466    use sha2::{Digest, Sha256};
467    let mut h = Sha256::new();
468    h.update(bytes);
469    hex::encode(&h.finalize()[..10])
470}
471
472fn fnv60(bytes: &[u8]) -> u64 {
473    const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
474    const FNV_PRIME: u64 = 0x100_0000_01b3;
475    let mut h = FNV_OFFSET;
476    for b in bytes {
477        h ^= u64::from(*b);
478        h = h.wrapping_mul(FNV_PRIME);
479    }
480    h & 0x0FFF_FFFF_FFFF_FFFF
481}
482
483#[cfg(test)]
484mod tests {
485    use super::*;
486
487    #[test]
488    fn intent_classify() {
489        assert_eq!(
490            classify_intent("Is this trusted?"),
491            BrowserAgentIntent::Trust
492        );
493        assert_eq!(
494            classify_intent("Privacy signals?"),
495            BrowserAgentIntent::Privacy
496        );
497        assert_eq!(
498            classify_intent("What is this page about?"),
499            BrowserAgentIntent::Summarise
500        );
501        assert_eq!(
502            classify_intent("How do I bookmark?"),
503            BrowserAgentIntent::NavigateHelp
504        );
505    }
506}