feat(analytics): record the task summary alongside the declared category

name_session now attaches the PII-scrubbed task summary to the
agent_session_task_declared event so the summary is available for product
analytics, not only local audit search. The analytics catalog gains its
first free-text property: task_summary is optional (the declaration still
sends without it) and length-bounded defensively at the boundary, with the
scrub and cap already applied upstream. Update the tool description to note
the summary powers search and is recorded for analytics.

Author: DaniAkash

packages/browseros-agent/apps/claw-server-rust/src/analytics/events.rs

@@ -2,7 +2,9 @@
 //!
 //! Producers can select one of these opaque definitions, but cannot construct a
 //! new wire event or widen its property schema. Free-form input is reduced to
-//! fixed tokens here before the delivery service ever sees it.
+//! fixed tokens here before the delivery service ever sees it. The sole
+//! exception is the agent-declared `task_summary`, a free-text property that is
+//! PII-scrubbed and length-capped upstream and only bounded defensively here.
 
 use serde_json::{Map, Value};
 use std::{
@@ -12,6 +14,7 @@ use std::{
 
 const CLIENT_NAME: &str = "client_name";
 const TASK_CATEGORY: &str = "task_category";
+const TASK_SUMMARY: &str = "task_summary";
 const HARNESS: &str = "harness";
 const KIND: &str = "kind";
 const TOOL_NAME: &str = "tool_name";
@@ -34,6 +37,11 @@ const SCREENSHOT_TOKENS_PER_DISPATCH: &str = "screenshot_tokens_per_dispatch";
 
 pub(crate) const MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
 
+/// Hard cap on the free-text task summary before it leaves the machine. The
+/// summary is already PII-scrubbed and length-capped upstream; this is the
+/// final defensive bound at the analytics boundary.
+pub(crate) const TASK_SUMMARY_MAX_CHARS: usize = 200;
+
 const KNOWN_CLIENTS: [&str; 15] = [
     "claude-desktop",
     "claude-code",
@@ -95,6 +103,7 @@ pub(crate) const TASK_CATEGORY_VALUES: [&str; 11] = [
 enum PropertyKind {
     ClientName,
     TaskCategory,
+    TaskSummary,
     Harness,
     EndKind,
     ToolName,
@@ -106,11 +115,26 @@ enum PropertyKind {
 struct PropertyDefinition {
     name: &'static str,
     kind: PropertyKind,
+    /// When true, the event still validates and sends if this property is
+    /// absent; when present it must still normalize.
+    optional: bool,
 }
 
 impl PropertyDefinition {
     const fn new(name: &'static str, kind: PropertyKind) -> Self {
-        Self { name, kind }
+        Self {
+            name,
+            kind,
+            optional: false,
+        }
+    }
+
+    const fn optional(name: &'static str, kind: PropertyKind) -> Self {
+        Self {
+            name,
+            kind,
+            optional: true,
+        }
     }
 
     fn normalize(self, value: &Value) -> Option<Value> {
@@ -125,6 +149,15 @@ impl PropertyDefinition {
                 };
                 Some(Value::String(category.to_string()))
             }
+            PropertyKind::TaskSummary => {
+                // The one free-text property: the agent-authored summary is already
+                // PII-scrubbed and length-capped upstream; here it is only bounded
+                // defensively and passed through as-is.
+                let raw = value.as_str()?;
+                Some(Value::String(
+                    raw.chars().take(TASK_SUMMARY_MAX_CHARS).collect(),
+                ))
+            }
             PropertyKind::Harness => normalize_token(value, &HARNESS_VALUES),
             PropertyKind::EndKind => normalize_token(value, &END_KIND_VALUES),
             PropertyKind::ToolName => {
@@ -193,8 +226,19 @@ impl EventDefinition {
         let input = properties.as_object()?;
         let mut output = Map::new();
         for property in self.properties {
-            let value = input.get(property.name)?;
-            output.insert(property.name.to_string(), property.normalize(value)?);
+            let Some(value) = input.get(property.name) else {
+                if property.optional {
+                    continue;
+                }
+                return None;
+            };
+            let Some(normalized) = property.normalize(value) else {
+                if property.optional {
+                    continue;
+                }
+                return None;
+            };
+            output.insert(property.name.to_string(), normalized);
         }
         Some(Value::Object(output))
     }
@@ -204,10 +248,11 @@ impl EventDefinition {
         properties: &HashMap<String, Value>,
     ) -> bool {
         self.properties.iter().all(|property| {
-            let Some(current) = properties.get(property.name) else {
-                return false;
-            };
-            property.normalize(current).as_ref() == Some(current)
+            match properties.get(property.name) {
+                Some(current) => property.normalize(current).as_ref() == Some(current),
+                // Absent is acceptable only for optional properties.
+                None => property.optional,
+            }
         })
     }
 
@@ -229,6 +274,7 @@ pub const AGENT_SESSION_TASK_DECLARED: EventDefinition = EventDefinition::new(
     &[
         PropertyDefinition::new(TASK_CATEGORY, PropertyKind::TaskCategory),
         PropertyDefinition::new(CLIENT_NAME, PropertyKind::ClientName),
+        PropertyDefinition::optional(TASK_SUMMARY, PropertyKind::TaskSummary),
     ],
 );
 pub const AGENT_SESSION_ENDED: EventDefinition = EventDefinition::new(
@@ -375,7 +421,7 @@ mod tests {
         );
         assert_eq!(
             AGENT_SESSION_TASK_DECLARED.property_names(),
-            vec!["task_category", "client_name"]
+            vec!["task_category", "client_name", "task_summary"]
         );
         assert_eq!(
             AGENT_SESSION_ENDED.property_names(),
@@ -521,6 +567,47 @@ mod tests {
         );
     }
 
+    #[test]
+    fn task_declared_passes_through_the_free_text_summary() {
+        assert_eq!(
+            AGENT_SESSION_TASK_DECLARED.sanitize(&json!({
+                "task_category": "shopping",
+                "client_name": "cursor",
+                "task_summary": "Compared warranty terms across three retailers.",
+            })),
+            Some(json!({
+                "task_category": "shopping",
+                "client_name": "cursor",
+                "task_summary": "Compared warranty terms across three retailers.",
+            }))
+        );
+    }
+
+    #[test]
+    fn task_declared_still_sends_when_the_optional_summary_is_absent() {
+        assert_eq!(
+            AGENT_SESSION_TASK_DECLARED
+                .sanitize(&json!({ "task_category": "research", "client_name": "codex" })),
+            Some(json!({ "task_category": "research", "client_name": "codex" }))
+        );
+    }
+
+    #[test]
+    fn task_summary_is_capped_at_the_boundary() {
+        let long = "x".repeat(TASK_SUMMARY_MAX_CHARS + 50);
+        let sanitized = AGENT_SESSION_TASK_DECLARED.sanitize(&json!({
+            "task_category": "other",
+            "client_name": "codex",
+            "task_summary": long,
+        }));
+        let summary = sanitized
+            .as_ref()
+            .and_then(|value| value.get("task_summary"))
+            .and_then(Value::as_str)
+            .unwrap_or_default();
+        assert_eq!(summary.chars().count(), TASK_SUMMARY_MAX_CHARS);
+    }
+
     #[test]
     fn unlisted_client_names_surface_their_slug() {
         for (raw, expected) in [

packages/browseros-agent/apps/claw-server-rust/src/api/mcp/service.rs

@@ -46,7 +46,7 @@ use uuid::Uuid;
 const SERVER_NAME: &str = "browseros-neo";
 const SERVER_TITLE: &str = "BrowserOS neo";
 const NAME_SESSION_TOOL_NAME: &str = "name_session";
-const NAME_SESSION_DESCRIPTION: &str = "Name this browser session at the start of a task: a small lowercase 2-3 word label for what it is doing, e.g. \"invoice processing\", a `category` for the kind of task, and a short `summary`. Tabs are grouped as <client>/<name>; the label and summary stay on this machine (the summary makes the session findable in audit search), and only the category is used for anonymous aggregate analytics. Call again to update.";
+const NAME_SESSION_DESCRIPTION: &str = "Name this browser session at the start of a task: a small lowercase 2-3 word label for what it is doing, e.g. \"invoice processing\", a `category` for the kind of task, and a short `summary`. Tabs are grouped as <client>/<name>; the label stays on this machine, the summary powers audit search and is also recorded for analytics, and the category is used for anonymous aggregate analytics. Call again to update.";
 const NAME_SESSION_CATEGORY_DESCRIPTION: &str = "The kind of task, for anonymous aggregate analytics only; the free-form name is never sent. Pick the closest fit from the list.";
 const NAME_SESSION_SUMMARY_DESCRIPTION: &str = "One or two short lines saying what this task is, phrased so you can find it again by searching later. No names, emails, URLs, file paths, or account numbers.";
 const SUMMARY_MAX_LEN: usize = 200;
@@ -146,6 +146,14 @@ impl ClawMcpService {
                 .into_call_tool_result();
             }
         };
+        // Scrub structural PII from any provided summary before it is stored, indexed for
+        // search, or recorded on the task-declared analytics event. Last write wins locally.
+        let scrubbed_summary = raw_args
+            .get("summary")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|summary| !summary.is_empty())
+            .map(scrub_summary);
         if let Some(category) = raw_args
             .get("category")
             .and_then(Value::as_str)
@@ -155,23 +163,24 @@ impl ClawMcpService {
             // At most once per session: a later name_session rename must not
             // re-declare and overcount the category mix or the declaration rate.
             if started.session.try_mark_task_declared() {
+                let mut properties = json!({
+                    "task_category": category,
+                    "client_name": started.session.client_name(),
+                });
+                // The scrubbed summary rides along with the category declaration; the
+                // analytics layer bounds it defensively before it leaves the machine.
+                if let Some(summary) = scrubbed_summary
+                    .as_deref()
+                    .filter(|summary| !summary.is_empty())
+                {
+                    properties["task_summary"] = Value::String(summary.to_string());
+                }
                 self.state.analytics.capture(
                     crate::analytics::events::AGENT_SESSION_TASK_DECLARED,
-                    json!({
-                        "task_category": category,
-                        "client_name": started.session.client_name(),
-                    }),
+                    properties,
                 );
             }
         }
-        // Scrub structural PII from any provided summary before it is persisted or
-        // indexed for search; stored locally only, never sent to analytics. Last write wins.
-        let scrubbed_summary = raw_args
-            .get("summary")
-            .and_then(Value::as_str)
-            .map(str::trim)
-            .filter(|summary| !summary.is_empty())
-            .map(scrub_summary);
         if let Some(clean) = scrubbed_summary.as_deref()
             && !clean.is_empty()
             && let Err(error) = self

packages/browseros-agent/apps/claw-server-rust/tests/routes.rs

@@ -487,7 +487,7 @@ async fn mcp_name_session_lists_and_renames_while_disconnected() -> anyhow::Resu
         .ok_or_else(|| anyhow::anyhow!("name_session missing"))?;
     assert_eq!(
         tool["description"],
-        "Name this browser session at the start of a task: a small lowercase 2-3 word label for what it is doing, e.g. \"invoice processing\", a `category` for the kind of task, and a short `summary`. Tabs are grouped as <client>/<name>; the label and summary stay on this machine (the summary makes the session findable in audit search), and only the category is used for anonymous aggregate analytics. Call again to update."
+        "Name this browser session at the start of a task: a small lowercase 2-3 word label for what it is doing, e.g. \"invoice processing\", a `category` for the kind of task, and a short `summary`. Tabs are grouped as <client>/<name>; the label stays on this machine, the summary powers audit search and is also recorded for analytics, and the category is used for anonymous aggregate analytics. Call again to update."
     );
     assert_eq!(
         tool["inputSchema"],