feat(metrics): broad ui/feature usage instrumentation

Adds new EVENT_TYPE entries (AI = "ai", TERMINAL = "term") and wires
metadata-only metrics across the editor's main feature surfaces. All
labels are stable enums; no user content (filenames, prompt text,
shell input/output, attached file paths) is recorded.

Coverage:

- src/view/CentralControlBar.js
  Click metrics for every CCB icon — UI/ccb/{undo,redo,save,
  designOn,designOff,sidebar,file}.

- src/view/SidebarTabs.js
  Click metric for the sidebar nav tab bar — UI/navTab/<tabId>
  (e.g. "ai", "files"). Programmatic setActiveTab calls are NOT
  metric'd; only user clicks.

- src/extensionsIntegrated/Phoenix-live-preview/main.js
  lp-edit/modeBtn/{toEdit,toPrev} on the inline edit-mode toggle
  button (previewModeLivePreviewButton). The companion
  designModeBtn already had a metric.

- src/extensionsIntegrated/Terminal/main.js
  Terminal feature usage:
    term/panel/open  — panel becomes visible
    term/new/<shell> — new tab created, shell family bucketed (bash,
                       zsh, fish, pwsh, cmd, ...)
    term/tabs/<bucket> — concurrent tab count after creation, bucketed
                         one / LTE4 / LTE9 / GT10
    term/pick/<shell> — user picked a default shell in the dropdown
    term/close/user   — terminal closed via UI
    term/exit/{ok,err} — shell process exited on its own (status
                         bucketed)

- src-node/claude-code-agent.js
  Per-turn token usage console-logs (each SDKAssistantMessage's
  message.usage) and one rolled-up usage payload per query (the
  terminal SDKResultMessage). The aggregate is forwarded to the
  browser via a new aiUsage peer event with usage / modelUsage /
  total_cost_usd / num_turns / duration_ms / duration_api_ms.

- src/utils/Metrics.js
  EVENT_TYPE.AI and EVENT_TYPE.TERMINAL added so feature areas have
  their own dimensions instead of overloading UI / PRO.

Author: abose

src-node/claude-code-agent.js

@@ -1340,6 +1340,67 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
                 _log("Session:", currentSessionId);
             }
 
+            // Per-turn token usage: each SDKAssistantMessage carries the
+            // wrapped Anthropic API message whose `.usage` reflects what
+            // that single turn consumed. Useful for diagnosing runaway
+            // loops; logged but not metric'd individually (the result
+            // message rolls up the session totals).
+            if (message.type === "assistant" &&
+                    message.message && message.message.usage) {
+                const u = message.message.usage;
+                _log("Turn usage:",
+                    "in=" + (u.input_tokens || 0),
+                    "out=" + (u.output_tokens || 0),
+                    "cacheRead=" + (u.cache_read_input_tokens || 0),
+                    "cacheCreate=" + (u.cache_creation_input_tokens || 0),
+                    message.parent_tool_use_id ? "(subagent)" : "");
+            }
+
+            // Aggregate session usage on the terminal `result` message.
+            // The SDK emits exactly one of these per query (success or
+            // error_*) with totals across all turns and the per-model
+            // breakdown.
+            if (message.type === "result") {
+                const u = message.usage || {};
+                const mu = message.modelUsage || {};
+                _log("Result:",
+                    "turns=" + (message.num_turns || 0),
+                    "in=" + (u.input_tokens || 0),
+                    "out=" + (u.output_tokens || 0),
+                    "cacheRead=" + (u.cache_read_input_tokens || 0),
+                    "cacheCreate=" + (u.cache_creation_input_tokens || 0),
+                    "cost=$" + (message.total_cost_usd || 0).toFixed(4),
+                    "ms=" + (message.duration_ms || 0),
+                    "apiMs=" + (message.duration_api_ms || 0),
+                    "subtype=" + message.subtype);
+                for (const modelName of Object.keys(mu)) {
+                    const m = mu[modelName];
+                    _log("Model usage[" + modelName + "]:",
+                        "in=" + (m.inputTokens || 0),
+                        "out=" + (m.outputTokens || 0),
+                        "cacheRead=" + (m.cacheReadInputTokens || 0),
+                        "cacheCreate=" + (m.cacheCreationInputTokens || 0),
+                        "websearch=" + (m.webSearchRequests || 0),
+                        "cost=$" + (m.costUSD || 0).toFixed(4),
+                        "ctxWindow=" + (m.contextWindow || 0));
+                }
+                // Forward to the browser so AIChatPanel can raise metrics.
+                // Stuck on its own event so the existing aiComplete handler
+                // doesn't have to change shape.
+                nodeConnector.triggerPeer("aiUsage", {
+                    requestId: requestId,
+                    sessionId: currentSessionId,
+                    subtype: message.subtype,
+                    isError: !!message.is_error,
+                    numTurns: message.num_turns || 0,
+                    durationMs: message.duration_ms || 0,
+                    durationApiMs: message.duration_api_ms || 0,
+                    totalCostUSD: message.total_cost_usd || 0,
+                    usage: u,
+                    modelUsage: mu
+                });
+            }
+
             // Handle streaming events
             if (message.type === "stream_event") {
                 const event = message.event;

src/extensionsIntegrated/Phoenix-live-preview/main.js

@@ -755,6 +755,12 @@ define(function (require, exports, module) {
      */
     function _handlePreviewBtnClick() {
         const currentMode = LiveDevelopment.getCurrentMode();
+        // Metric: which direction the user is toggling so we can see
+        // how often the inline-edit affordance is actually used vs
+        // simply opened-then-closed.
+        Metrics.countEvent(Metrics.EVENT_TYPE.LP_EDIT, "modeBtn",
+            currentMode === LiveDevelopment.CONSTANTS.LIVE_EDIT_MODE
+                ? "toPrev" : "toEdit");
         if (currentMode === LiveDevelopment.CONSTANTS.LIVE_EDIT_MODE) {
             LiveDevelopment.setMode(LiveDevelopment.CONSTANTS.LIVE_PREVIEW_MODE);
             return;

src/extensionsIntegrated/Terminal/main.js

@@ -33,6 +33,7 @@ define(function (require, exports, module) {
     const WorkspaceManager = require("view/WorkspaceManager");
     const ProjectManager = require("project/ProjectManager");
     const ExtensionUtils = require("utils/ExtensionUtils");
+    const Metrics = require("utils/Metrics");
     const NodeConnector = require("NodeConnector");
     const Mustache = require("thirdparty/mustache/mustache");
     const Dialogs = require("widgets/Dialogs");
@@ -167,6 +168,7 @@ define(function (require, exports, module) {
                     active.focus();
                 }
                 _showFocusHintToast();
+                Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "panel", "open");
             }
         });
 
@@ -199,6 +201,11 @@ define(function (require, exports, module) {
                 ShellProfiles.setDefaultShell(shell.name);
                 _populateShellDropdown();
                 _updateNewTerminalButtonLabel();
+                // Metric: which shell the user picked from the dropdown
+                // (default-shell switch). _createNewTerminalWithShell below
+                // will also raise its own "new" metric for the spawn.
+                Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "pick",
+                    _shellMetricLabel(shell.name));
                 _createNewTerminalWithShell(shell);
             });
             $shellDropdown.append($item);
@@ -290,11 +297,33 @@ define(function (require, exports, module) {
      * @param {Object} shell - Shell profile to use
      * @param {string} [cwdOverride] - Optional VFS path to use as cwd instead of project root
      */
+    /**
+     * Map an OS shell name (e.g. "powershell.exe", "bash.exe") to a short
+     * family label so the metrics server's per-event length budget stays
+     * comfortable. Strips ".exe" and lower-cases; unknown shells fall
+     * through under "other" (with their lower-cased name shown only in
+     * the cap'd 8-char form).
+     */
+    function _shellMetricLabel(shellName) {
+        if (!shellName) { return "unknown"; }
+        let n = String(shellName).toLowerCase();
+        if (n.endsWith(".exe")) { n = n.slice(0, -4); }
+        // pwsh & powershell are functionally the same family for the metric.
+        if (n === "powershell") { n = "pwsh"; }
+        // Cap so an unexpected long shell name can't blow the label cell.
+        if (n.length > 8) { n = n.slice(0, 8); }
+        return n || "unknown";
+    }
+
     async function _createNewTerminalWithShell(shell, cwdOverride) {
         if (!shell) {
             console.error("Terminal: No shell available");
+            Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "new", "noShell");
             return;
         }
+        // Metric: a new terminal session was created, keyed by shell family.
+        Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "new",
+            _shellMetricLabel(shell.name));
 
         // Get cwd: use override if provided, otherwise fall back to project root
         let cwd;
@@ -320,6 +349,16 @@ define(function (require, exports, module) {
         // Add to list
         terminalInstances.push(instance);
 
+        // Tab-count bucket metric — raised only on tab creation so we
+        // can plot how many concurrent terminal tabs users keep open.
+        // Buckets: 1 → "one", 2..4 → "LTE4", 5..9 → "LTE9", 10+ → "GT10".
+        const count = terminalInstances.length;
+        const tabsBucket = count === 1 ? "one"
+                         : count <= 4 ? "LTE4"
+                         : count <= 9 ? "LTE9"
+                                      : "GT10";
+        Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "tabs", tabsBucket);
+
         // Activate this terminal (also updates flyout)
         _activateTerminal(instance.id);
 
@@ -394,6 +433,7 @@ define(function (require, exports, module) {
         instance.dispose();
         terminalInstances.splice(idx, 1);
         delete processInfo[id];
+        Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "close", "user");
 
         // If we closed the active terminal, activate another
         if (activeTerminalId === id) {
@@ -563,6 +603,12 @@ define(function (require, exports, module) {
     function _onTerminalProcessExit(id, exitCode) {
         delete processInfo[id];
         _updateFlyout();
+        // Metric: terminal process exited on its own (e.g. user typed
+        // "exit"). Distinct from "user" close above, which records the
+        // X-button / panel-driven close path. Exit code is bucketed
+        // ok/err so cardinality stays bounded.
+        Metrics.countEvent(Metrics.EVENT_TYPE.TERMINAL, "exit",
+            exitCode === 0 ? "ok" : "err");
     }
 
     /**

src/utils/Metrics.js

@@ -129,6 +129,8 @@ define(function (require, exports, module) {
         GIT: "git",
         AUTH: "auth",
         PRO: "pro",
+        AI: "ai",
+        TERMINAL: "term",
         GUIDE: "guide"
     };
 

src/view/CentralControlBar.js

@@ -25,6 +25,7 @@ define(function (require, exports, module) {
     const Commands          = require("command/Commands");
     const DocumentManager   = require("document/DocumentManager");
     const MainViewManager   = require("view/MainViewManager");
+    const Metrics           = require("utils/Metrics");
     const Strings           = require("strings");
     const WorkspaceManager  = require("view/WorkspaceManager");
     const SidebarView       = require("project/SidebarView");
@@ -302,20 +303,41 @@ define(function (require, exports, module) {
         $btn.find("i").attr("class", isVisible ? "fa-solid fa-angles-left" : "fa-solid fa-angles-right");
     }
 
+    function _ccbClickMetric(label) {
+        Metrics.countEvent(Metrics.EVENT_TYPE.UI, "ccb", label);
+    }
+
     function _wireButtons() {
-        $("#ccbUndoBtn").on("click", function (e) { e.preventDefault(); _executeCmd(Commands.EDIT_UNDO); });
-        $("#ccbRedoBtn").on("click", function (e) { e.preventDefault(); _executeCmd(Commands.EDIT_REDO); });
-        $("#ccbSaveBtn").on("click", function (e) { e.preventDefault(); _executeCmd(Commands.FILE_SAVE); });
+        $("#ccbUndoBtn").on("click", function (e) {
+            e.preventDefault();
+            _ccbClickMetric("undo");
+            _executeCmd(Commands.EDIT_UNDO);
+        });
+        $("#ccbRedoBtn").on("click", function (e) {
+            e.preventDefault();
+            _ccbClickMetric("redo");
+            _executeCmd(Commands.EDIT_REDO);
+        });
+        $("#ccbSaveBtn").on("click", function (e) {
+            e.preventDefault();
+            _ccbClickMetric("save");
+            _executeCmd(Commands.FILE_SAVE);
+        });
         $("#ccbCollapseEditorBtn").on("click", function (e) {
             e.preventDefault();
+            // editorCollapsed reflects the state *before* the toggle
+            // executes; record which direction the user is going.
+            _ccbClickMetric(editorCollapsed ? "designOff" : "designOn");
             CommandManager.execute(Commands.VIEW_TOGGLE_DESIGN_MODE);
         });
         $("#ccbSidebarToggleBtn").on("click", function (e) {
             e.preventDefault();
+            _ccbClickMetric("sidebar");
             _executeCmd(Commands.VIEW_HIDE_SIDEBAR);
         });
         $("#ccbFileLabel").on("click", function (e) {
             e.preventDefault();
+            _ccbClickMetric("file");
             _executeCmd(Commands.NAVIGATE_SHOW_IN_FILE_TREE);
         });
     }

src/view/SidebarTabs.js

@@ -39,6 +39,7 @@ define(function (require, exports, module) {
 
     const AppInit              = require("utils/AppInit"),
         EventDispatcher      = require("utils/EventDispatcher"),
+        Metrics              = require("utils/Metrics"),
         PreferencesManager   = require("preferences/PreferencesManager");
 
     // --- Constants -----------------------------------------------------------
@@ -495,6 +496,14 @@ define(function (require, exports, module) {
         $navTabBar.on("click", ".sidebar-tab", function () {
             const tabId = $(this).attr("data-tab-id");
             if (tabId) {
+                // Track only real user clicks here (programmatic
+                // setActiveTab calls — e.g. the phoenix-tour AI peek —
+                // shouldn't inflate the click metric). Map the built-in
+                // Files tab id to a short label; pass the (already short)
+                // id for the rest. Triple stays well within the metrics
+                // server's per-event length budget.
+                const label = (tabId === SIDEBAR_TAB_FILES) ? "files" : tabId;
+                Metrics.countEvent(Metrics.EVENT_TYPE.UI, "navTab", label);
                 setActiveTab(tabId);
             }
         });