feat(tray): glance section — recent calls, connected clients, 24h histogram

.gitignore

@@ -162,3 +162,6 @@ scripts/demo/node_modules
 # Transient work artifacts (brainstorm logs, editor backups)
 *.bak
 **/execution_log.md
+
+# Subagent-driven-development scratch workspace (ledger, briefs, review packages)
+.superpowers/

docs/api/rest-api.md

@@ -927,7 +927,23 @@ Get secret metadata (not the value).
 
 #### GET /api/v1/sessions
 
-List active MCP sessions.
+List recent MCP sessions.
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | integer | Max sessions (1-100, default: 10) |
+| `offset` | integer | Pagination offset (default: 0) |
+| `status` | string | Filter by session status: `active`, `closed`. Any other value returns `400`. |
+
+The `status` filter is applied during the storage walk, **before** the `limit`
+truncation, so a long-running session that is still active is returned even when
+newer sessions would otherwise fill the page. When `status` is set, `total`
+counts the matching sessions rather than every stored session.
+
+Caveat (spec 082): handshake-only sessions are not persisted, so a connected but
+idle client does not appear until its first tool call.
 
 #### GET /api/v1/sessions/{id}
 

internal/httpapi/activity.go

@@ -144,6 +144,7 @@ func parseActivityFilters(r *http.Request) storage.ActivityFilter {
 // @Param end_time query string false "Filter activities before this time (RFC3339)"
 // @Param limit query int false "Maximum records to return (1-100, default 50)"
 // @Param offset query int false "Pagination offset (default 0)"
+// @Param exclude_payloads query bool false "Omit arguments, response and metadata (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped."
 // @Success 200 {object} contracts.APIResponse{data=contracts.ActivityListResponse}
 // @Failure 400 {object} contracts.APIResponse
 // @Failure 401 {object} contracts.APIResponse
@@ -161,10 +162,26 @@ func (s *Server) handleListActivity(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Convert storage records to contract records
+	// Convert storage records to contract records.
+	//
+	// `exclude_payloads` is a projection, not a filter: it changes what is
+	// serialised, never which records match, so it is applied here rather than
+	// in the storage filter. Arguments, Response and Metadata are unbounded in
+	// practice (only Response is truncated, at 64KB), and a client that renders
+	// summary fields alone pays for them on every poll — measured against a real
+	// log, the newest 100 tool-call records are ~848KB whole and ~30KB projected.
+	// HasSensitiveData is derived by storageToContractActivity from Metadata
+	// BEFORE it is dropped, so the flag survives its source.
+	excludePayloads := r.URL.Query().Get("exclude_payloads") == "true"
 	contractActivities := make([]contracts.ActivityRecord, len(activities))
 	for i, a := range activities {
 		contractActivities[i] = storageToContractActivity(a)
+		if excludePayloads {
+			contractActivities[i].Arguments = nil
+			contractActivities[i].Response = ""
+			contractActivities[i].ResponseTruncated = false
+			contractActivities[i].Metadata = nil
+		}
 	}
 
 	response := contracts.ActivityListResponse{

internal/httpapi/activity_handlers_test.go

@@ -204,7 +204,7 @@ func TestActivityList_SensitiveDataFilter(t *testing.T) {
 		assert.Equal(t, http.StatusOK, w.Code)
 
 		var resp struct {
-			Success bool                         `json:"success"`
+			Success bool                           `json:"success"`
 			Data    contracts.ActivityListResponse `json:"data"`
 		}
 		err := json.NewDecoder(w.Body).Decode(&resp)
@@ -231,7 +231,7 @@ func TestActivityList_SensitiveDataFilter(t *testing.T) {
 		assert.Equal(t, http.StatusOK, w.Code)
 
 		var resp struct {
-			Success bool                         `json:"success"`
+			Success bool                           `json:"success"`
 			Data    contracts.ActivityListResponse `json:"data"`
 		}
 		err := json.NewDecoder(w.Body).Decode(&resp)
@@ -249,6 +249,92 @@ func TestActivityList_SensitiveDataFilter(t *testing.T) {
 	})
 }
 
+// TestActivityList_ExcludePayloads covers the projection the tray glance asks
+// for. The glance renders summary fields only, but a full record carries
+// arguments, response and metadata — measured against a real activity log, the
+// newest 100 matching records are ~848 KB whole and ~30 KB in summary form, and
+// the tray refetches every 30 seconds.
+func TestActivityList_ExcludePayloads(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	activities := []*storage.ActivityRecord{
+		{
+			ID:           "activity-with-payload",
+			Type:         storage.ActivityTypeToolCall,
+			ServerName:   "github",
+			ToolName:     "create_issue",
+			Status:       "error",
+			ErrorMessage: "auth failed",
+			DurationMs:   42,
+			RequestID:    "req-1",
+			SessionID:    "sess-1",
+			Timestamp:    time.Date(2024, 6, 15, 12, 0, 0, 0, time.UTC),
+			Arguments:    map[string]interface{}{"title": "a very large argument blob"},
+			Response:     "a very large response body",
+			Metadata: map[string]interface{}{
+				"sensitive_data_detection": map[string]interface{}{
+					"detected": true,
+					"detections": []interface{}{
+						map[string]interface{}{"type": "github_token", "severity": "high"},
+					},
+				},
+			},
+		},
+	}
+	mockCtrl := &mockActivityController{apiKey: "test-key", activities: activities}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	get := func(t *testing.T, path string) contracts.ActivityRecord {
+		t.Helper()
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		req.Header.Set("X-API-Key", "test-key")
+		w := httptest.NewRecorder()
+		srv.ServeHTTP(w, req)
+		require.Equal(t, http.StatusOK, w.Code)
+
+		var resp struct {
+			Success bool                           `json:"success"`
+			Data    contracts.ActivityListResponse `json:"data"`
+		}
+		require.NoError(t, json.NewDecoder(w.Body).Decode(&resp))
+		require.Len(t, resp.Data.Activities, 1)
+		return resp.Data.Activities[0]
+	}
+
+	t.Run("exclude_payloads=true drops the three heavy fields", func(t *testing.T) {
+		got := get(t, "/api/v1/activity?exclude_payloads=true")
+
+		assert.Nil(t, got.Arguments, "arguments must not be serialised")
+		assert.Empty(t, got.Response, "response must not be serialised")
+		assert.Nil(t, got.Metadata, "metadata must not be serialised")
+	})
+
+	t.Run("exclude_payloads=true keeps every field the glance renders", func(t *testing.T) {
+		got := get(t, "/api/v1/activity?exclude_payloads=true")
+
+		assert.Equal(t, "activity-with-payload", got.ID)
+		assert.Equal(t, contracts.ActivityType("tool_call"), got.Type)
+		assert.Equal(t, "github", got.ServerName)
+		assert.Equal(t, "create_issue", got.ToolName)
+		assert.Equal(t, "error", got.Status)
+		assert.Equal(t, "auth failed", got.ErrorMessage)
+		assert.Equal(t, int64(42), got.DurationMs)
+		assert.Equal(t, "req-1", got.RequestID)
+		assert.Equal(t, "sess-1", got.SessionID)
+		assert.False(t, got.Timestamp.IsZero())
+		// Derived from metadata BEFORE it is dropped: the tray's row icon and
+		// the poll's late correction both key off this flag.
+		assert.True(t, got.HasSensitiveData, "the flag survives its source being dropped")
+	})
+
+	t.Run("the default response is unchanged", func(t *testing.T) {
+		got := get(t, "/api/v1/activity")
+
+		assert.NotNil(t, got.Arguments, "omitting the parameter must not change what other clients get")
+		assert.Equal(t, "a very large response body", got.Response)
+		assert.NotNil(t, got.Metadata)
+	})
+}
+
 func TestActivityList_DetectionTypeFilter(t *testing.T) {
 	logger := zap.NewNop().Sugar()
 	activities := createTestActivityRecords()
@@ -268,7 +354,7 @@ func TestActivityList_DetectionTypeFilter(t *testing.T) {
 		assert.Equal(t, http.StatusOK, w.Code)
 
 		var resp struct {
-			Success bool                         `json:"success"`
+			Success bool                           `json:"success"`
 			Data    contracts.ActivityListResponse `json:"data"`
 		}
 		err := json.NewDecoder(w.Body).Decode(&resp)
@@ -342,7 +428,7 @@ func TestActivityList_SeverityFilter(t *testing.T) {
 		assert.Equal(t, http.StatusOK, w.Code)
 
 		var resp struct {
-			Success bool                         `json:"success"`
+			Success bool                           `json:"success"`
 			Data    contracts.ActivityListResponse `json:"data"`
 		}
 		err := json.NewDecoder(w.Body).Decode(&resp)
@@ -618,7 +704,7 @@ func TestActivityResponse_SensitiveDataFields(t *testing.T) {
 			"activity-2-credit-card": "high",
 			"activity-3-multiple":    "critical", // Has both critical and high, critical is max
 			"activity-4-medium":      "medium",
-			"activity-5-clean":       "",         // No sensitive data
+			"activity-5-clean":       "", // No sensitive data
 		}
 
 		for _, activity := range resp.Data.Activities {
@@ -680,7 +766,7 @@ func TestActivityDetail_SensitiveDataFields(t *testing.T) {
 		assert.Equal(t, http.StatusOK, w.Code)
 
 		var resp struct {
-			Success bool                          `json:"success"`
+			Success bool                             `json:"success"`
 			Data    contracts.ActivityDetailResponse `json:"data"`
 		}
 		err := json.NewDecoder(w.Body).Decode(&resp)
@@ -703,7 +789,7 @@ func TestActivityDetail_SensitiveDataFields(t *testing.T) {
 		assert.Equal(t, http.StatusOK, w.Code)
 
 		var resp struct {
-			Success bool                          `json:"success"`
+			Success bool                             `json:"success"`
 			Data    contracts.ActivityDetailResponse `json:"data"`
 		}
 		err := json.NewDecoder(w.Body).Decode(&resp)

internal/httpapi/contracts_test.go

@@ -169,7 +169,7 @@ func (m *MockServerController) GetDockerRecoveryStatus() *storage.DockerRecovery
 	}
 }
 func (m *MockServerController) IsDockerAvailable() bool { return true }
-func (m *MockServerController) GetRecentSessions(_ int) ([]*contracts.MCPSession, int, error) {
+func (m *MockServerController) GetRecentSessions(_ int, _ string) ([]*contracts.MCPSession, int, error) {
 	return []*contracts.MCPSession{}, 0, nil
 }
 func (m *MockServerController) GetSessionByID(_ string) (*contracts.MCPSession, error) {

internal/httpapi/security_test.go

@@ -313,7 +313,7 @@ func (m *baseController) CallTool(ctx context.Context, toolName string, args map
 func (m *baseController) GetRuntime() *runtime.Runtime                            { return nil }
 func (m *baseController) GetSessions(limit, offset int) (interface{}, int, error) { return nil, 0, nil }
 func (m *baseController) GetSessionByID(id string) (*contracts.MCPSession, error) { return nil, nil }
-func (m *baseController) GetRecentSessions(limit int) ([]*contracts.MCPSession, int, error) {
+func (m *baseController) GetRecentSessions(limit int, status string) ([]*contracts.MCPSession, int, error) {
 	return nil, 0, nil
 }
 func (m *baseController) GetToolCallsBySession(sessionID string, limit, offset int) ([]*contracts.ToolCallRecord, int, error) {

internal/httpapi/server.go

@@ -105,8 +105,9 @@ type ServerController interface {
 	ReplayToolCall(id string, arguments map[string]interface{}) (*contracts.ToolCallRecord, error)
 	GetToolCallsBySession(sessionID string, limit, offset int) ([]*contracts.ToolCallRecord, int, error)
 
-	// Session management
-	GetRecentSessions(limit int) ([]*contracts.MCPSession, int, error)
+	// Session management. status filters on session status ("active" /
+	// "closed"); an empty string means no filter.
+	GetRecentSessions(limit int, status string) ([]*contracts.MCPSession, int, error)
 	GetSessionByID(sessionID string) (*contracts.MCPSession, error)
 
 	// Configuration management
@@ -4828,7 +4829,9 @@ func getBool(m map[string]interface{}, key string) bool {
 // @Produce      json
 // @Param        limit   query     int                               false  "Maximum number of sessions to return (1-100, default 10)"
 // @Param        offset  query     int                               false  "Number of sessions to skip for pagination (default 0)"
+// @Param        status  query     string                            false  "Filter by session status"  Enums(active, closed)
 // @Success      200     {object}  contracts.GetSessionsResponse     "Sessions retrieved successfully"
+// @Failure      400     {object}  contracts.ErrorResponse           "Invalid status filter"
 // @Failure      401     {object}  contracts.ErrorResponse           "Unauthorized - missing or invalid API key"
 // @Failure      405     {object}  contracts.ErrorResponse           "Method not allowed"
 // @Failure      500     {object}  contracts.ErrorResponse           "Failed to get sessions"
@@ -4859,8 +4862,17 @@ func (s *Server) handleGetSessions(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	// Status filter. The domain is closed ("active" / "closed"), so an unknown
+	// value is a client bug — rejecting it is honest, where silently ignoring it
+	// would return unfiltered sessions that the caller believes are filtered.
+	status := r.URL.Query().Get("status")
+	if status != "" && status != "active" && status != "closed" {
+		s.writeError(w, r, http.StatusBadRequest, "Invalid status. Use 'active' or 'closed'")
+		return
+	}
+
 	// Get recent sessions from controller
-	sessions, total, err := s.controller.GetRecentSessions(limit)
+	sessions, total, err := s.controller.GetRecentSessions(limit, status)
 	if err != nil {
 		s.logger.Error("Failed to get sessions", "error", err)
 		s.writeError(w, r, http.StatusInternalServerError, "Failed to get sessions")