feat(analytics): let a session declare its task category

name_session gains an optional category argument from a fixed enum. The
free-form name stays local and drives the tab group title exactly as before;
only the enum category is emitted, on a new agent_session_task_declared event
(task_category + client_name), so we can aggregate what kind of work sessions
do without any free-form text leaving the machine. An unrecognized category is
coerced to "other" so the declaration still counts; a non-string is dropped.
The prompt and skill now nudge the agent to pass a category.

Author: DaniAkash

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

@@ -11,6 +11,7 @@ use std::{
 };
 
 const CLIENT_NAME: &str = "client_name";
+const TASK_CATEGORY: &str = "task_category";
 const HARNESS: &str = "harness";
 const KIND: &str = "kind";
 const TOOL_NAME: &str = "tool_name";
@@ -72,9 +73,28 @@ pub(crate) const HARNESS_VALUES: [&str; 7] = [
 
 pub(crate) const END_KIND_VALUES: [&str; 3] = ["closed", "errored", "cancelled"];
 
+/// Fixed set of task kinds the agent may declare. Only these tokens leave the
+/// machine; the free-form session name never does. An unrecognized value is
+/// coerced to `other` rather than dropped, so the declaration still counts and a
+/// hot `other` signals a missing row.
+pub(crate) const TASK_CATEGORY_VALUES: [&str; 11] = [
+    "shopping",
+    "research",
+    "email-and-messaging",
+    "form-filling",
+    "data-extraction",
+    "testing-and-qa",
+    "dev-tools",
+    "social-media",
+    "finance-and-admin",
+    "internal-tools",
+    "other",
+];
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum PropertyKind {
     ClientName,
+    TaskCategory,
     Harness,
     EndKind,
     ToolName,
@@ -96,6 +116,15 @@ impl PropertyDefinition {
     fn normalize(self, value: &Value) -> Option<Value> {
         match self.kind {
             PropertyKind::ClientName => Some(Value::String(bucket_client_name(value.as_str()?))),
+            PropertyKind::TaskCategory => {
+                let raw = value.as_str()?;
+                let category = if TASK_CATEGORY_VALUES.contains(&raw) {
+                    raw
+                } else {
+                    "other"
+                };
+                Some(Value::String(category.to_string()))
+            }
             PropertyKind::Harness => normalize_token(value, &HARNESS_VALUES),
             PropertyKind::EndKind => normalize_token(value, &END_KIND_VALUES),
             PropertyKind::ToolName => {
@@ -195,6 +224,13 @@ pub const AGENT_SESSION_STARTED: EventDefinition = EventDefinition::new(
         PropertyKind::ClientName,
     )],
 );
+pub const AGENT_SESSION_TASK_DECLARED: EventDefinition = EventDefinition::new(
+    "agent_session_task_declared",
+    &[
+        PropertyDefinition::new(TASK_CATEGORY, PropertyKind::TaskCategory),
+        PropertyDefinition::new(CLIENT_NAME, PropertyKind::ClientName),
+    ],
+);
 pub const AGENT_SESSION_ENDED: EventDefinition = EventDefinition::new(
     "agent_session_ended",
     &[
@@ -252,9 +288,10 @@ pub const AGENT_SESSION_EFFICIENCY_COMPUTED: EventDefinition = EventDefinition::
     ],
 );
 
-pub const ALL: [EventDefinition; 7] = [
+pub const ALL: [EventDefinition; 8] = [
     SERVER_STARTED,
     AGENT_SESSION_STARTED,
+    AGENT_SESSION_TASK_DECLARED,
     AGENT_SESSION_ENDED,
     HARNESS_CONNECTED,
     HARNESS_DISCONNECTED,
@@ -322,19 +359,24 @@ mod tests {
 
     #[test]
     fn catalog_pins_wire_names_and_required_properties() {
-        assert_eq!(ALL.len(), 7);
+        assert_eq!(ALL.len(), 8);
         assert_eq!(
             ALL.map(EventDefinition::name),
             [
                 SERVER_STARTED.name(),
                 AGENT_SESSION_STARTED.name(),
+                AGENT_SESSION_TASK_DECLARED.name(),
                 AGENT_SESSION_ENDED.name(),
                 HARNESS_CONNECTED.name(),
                 HARNESS_DISCONNECTED.name(),
                 AGENT_SESSION_TOOL_USAGE.name(),
                 AGENT_SESSION_EFFICIENCY_COMPUTED.name(),
             ]
         );
+        assert_eq!(
+            AGENT_SESSION_TASK_DECLARED.property_names(),
+            vec!["task_category", "client_name"]
+        );
         assert_eq!(
             AGENT_SESSION_ENDED.property_names(),
             vec![
@@ -451,6 +493,34 @@ mod tests {
         }
     }
 
+    #[test]
+    fn known_task_categories_pass_through_and_unknown_coerces_to_other() {
+        for category in TASK_CATEGORY_VALUES {
+            assert_eq!(
+                AGENT_SESSION_TASK_DECLARED
+                    .sanitize(&json!({ "task_category": category, "client_name": "cursor" })),
+                Some(json!({ "task_category": category, "client_name": "cursor" }))
+            );
+        }
+        // Anything off-enum is coerced to `other` so the declaration still counts.
+        for raw in ["crypto-trading", "", "SHOPPING", "shopping ", "acme corp"] {
+            assert_eq!(
+                AGENT_SESSION_TASK_DECLARED
+                    .sanitize(&json!({ "task_category": raw, "client_name": "codex" })),
+                Some(json!({ "task_category": "other", "client_name": "codex" }))
+            );
+        }
+    }
+
+    #[test]
+    fn task_declared_drops_when_category_is_not_a_string() {
+        assert_eq!(
+            AGENT_SESSION_TASK_DECLARED
+                .sanitize(&json!({ "task_category": 7, "client_name": "cursor" })),
+            None
+        );
+    }
+
     #[test]
     fn unlisted_client_names_surface_their_slug() {
         for (raw, expected) in [

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

@@ -22,8 +22,8 @@ Shared with other agents:
   tabs action="new" and work on that copy; leave the original untouched.
 - Preserve useful pages: leave anything the user may want to inspect open
   instead of closing it when the task ends.
-- Rename your session early with name_session using a 2-3 word task label;
-  tabs group as <client>/<name>.
+- Name your session early with name_session: a 2-3 word task label plus the
+  category that best fits the task; tabs group as <client>/<name>.
 - The user oversees this browser from the BrowserOS neo cockpit (live view,
   audit, replay).
 

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

@@ -46,7 +46,8 @@ 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 = "Rename this browser session: a small lowercase 2-3 word label for what this session is doing, e.g. \"invoice processing\". Tabs are grouped as <client>/<name>. Call again to rename.";
+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\", plus a `category` for the kind of task. Tabs are grouped as <client>/<name>; the label stays on this machine and only 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_INPUT_MAX_LEN: usize = 64;
 const SESSION_ARG_DESCRIPTION: &str = "Opaque session handle returned by the server. Pass it back on every call to keep working in the same browser session; omit it to start a new session.";
 const SAVE_SKILL_TOOL_NAME: &str = "save_skill";
@@ -143,6 +144,20 @@ impl ClawMcpService {
                 .into_call_tool_result();
             }
         };
+        if let Some(category) = raw_args
+            .get("category")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|category| !category.is_empty())
+        {
+            self.state.analytics.capture(
+                crate::analytics::events::AGENT_SESSION_TASK_DECLARED,
+                json!({
+                    "task_category": category,
+                    "client_name": started.session.client_name(),
+                }),
+            );
+        }
         let browser = self.state.browser.session().await;
         apply_agent_tab_group_title(
             browser.as_ref(),
@@ -644,7 +659,12 @@ fn name_session_tool() -> Tool {
     let Value::Object(input_schema) = json!({
         "type": "object",
         "properties": {
-            "name": { "type": "string", "maxLength": NAME_SESSION_INPUT_MAX_LEN }
+            "name": { "type": "string", "maxLength": NAME_SESSION_INPUT_MAX_LEN },
+            "category": {
+                "type": "string",
+                "enum": crate::analytics::events::TASK_CATEGORY_VALUES,
+                "description": NAME_SESSION_CATEGORY_DESCRIPTION
+            }
         },
         "required": ["name"]
     }) else {
@@ -1095,7 +1115,7 @@ mod tests {
         assert!(instructions.contains("BrowserOS neo — the browser for agents"));
         assert!(instructions.contains("Reach for run first"));
         assert!(instructions.contains(
-            "- Rename your session early with name_session using a 2-3 word task label;\n  tabs group as <client>/<name>."
+            "- Name your session early with name_session: a 2-3 word task label plus the\n  category that best fits the task; tabs group as <client>/<name>."
         ));
         assert!(instructions.contains(
             "- If the user points you at a tab you don't own, open its URL with\n  tabs action=\"new\" and work on that copy; leave the original untouched."
@@ -1156,6 +1176,11 @@ mod tests {
                 "type": "object",
                 "properties": {
                     "name": { "type": "string", "maxLength": 64 },
+                    "category": {
+                        "type": "string",
+                        "enum": crate::analytics::events::TASK_CATEGORY_VALUES,
+                        "description": NAME_SESSION_CATEGORY_DESCRIPTION
+                    },
                     "session": { "type": "string", "description": SESSION_ARG_DESCRIPTION }
                 },
                 "required": ["name"]

packages/browseros-agent/resources/skills/browserclaw/SKILL.md

@@ -9,7 +9,7 @@ When a task needs a browser or a website (open it, read it, act on it, fill a fo
 
 ## Shared browser etiquette
 
-- Call `name_session` early with a 2-3 word task label; tabs group as `<client>/<name>` in the cockpit.
+- Call `name_session` early with a 2-3 word task label and the best-fit `category`; tabs group as `<client>/<name>` in the cockpit.
 - Open your own tab with `tabs` action `"new"`. Work only in task-owned tabs.
 - If the user points you at a tab you do not own, open its URL in your own tab and leave the original untouched.
 - Preserve useful pages that the user may want to inspect instead of closing them when the task ends.