Support editor-bucket-aware categorization for editor project/workspace rules

[TimeToBuildBob]

Problem

aw-webui category queries currently run through canonicalEvents(...), which builds categorized activity from current-window + browser + stopwatch events.

Editor activity buckets (app.editor.activity) are queried separately via editorActivityQuery(...) and are only used for editor visualizations (top_files, top_languages, top_projects). They are not part of the categorization pipeline today.

That means requests like "match this category by editor project/workspace" cannot work yet, even if the UI grows a field selector, because the project data never reaches the events being categorized.

User-facing example: activity-watch-mode / Emacs reports project data, but a category rule cannot currently match on it. See ActivityWatch/aw-webui#619.

Current State

• aw-webui/src/queries.ts::canonicalEvents(...) categorizes canonical window/browser/stopwatch events
• aw-webui/src/queries.ts::editorActivityQuery(...) fetches editor buckets separately
• Editor bucket fields such as project are therefore unavailable to normal category reports, timelines, and aggregates

Design Questions

1. Should category queries consume editor buckets directly?
2. Or should editor-derived fields be merged/projection-attached onto canonical window events before categorization?
3. How should overlap/conflicts between window activity and editor activity be handled?
4. Which editor fields should be treated as stable/canonical across watchers (project, file, language, etc.)?

Acceptance Criteria

• A user can define a category rule that matches editor project/workspace data.
• The resulting category appears in normal category views/reports, not only editor-specific visualizations.
• The approach is documented clearly enough that watcher implementations know which fields they need to provide.

Related

• Ability to match category by Editor project? aw-webui#619
• Configurable Title Attribute aw-webui#678

[tobiasdiez]

@TimeToBuildBob implement this. Choose the simplest design - I would say merging the editor data into the window events should be possible. Hopefully the editor data even already contains info about what window it belongs to.

[TimeToBuildBob]

Analysis

@tobiasdiez I've investigated this. Here's my analysis of how to merge editor data into the window event pipeline so category rules can match on editor project/file/language.

Current Architecture

1. canonicalEvents() (aw-webui/src/queries.ts:115) builds the main event stream from window + browser + afk + stopwatch events. Editor buckets are NOT part of this pipeline.

2. editorActivityQuery() (queries.ts:398) queries editor buckets separately and returns {files, languages, projects, duration} — used only for the editor visualizations (top files, top languages, top projects).

3. The store (activity.ts:386-393) calls these independently via query_desktop_full() → query_window_completed() and query_editor() → query_editor_completed(). The results never meet.

Design: Merging Editor Metadata into Window Events

The simplest approach (as Tobias suggested):

Extend canonicalEvents() with an optional editor_buckets parameter. When provided:

1. Query editor buckets alongside window events
2. Use filter_period_intersect to find window events that overlap with editor activity
3. Attach editor metadata (project, file, language) to the intersecting window events
4. Now categorize() can match on these fields

Concretely, add to the canonical query string:

editor_events = flood(query_bucket("editor-bucket"));
editor_events_with_window = filter_period_intersect(editor_events, events);
// Attach project/file/language from editor events to window events
// ... (needs custom merge transform)
events = concat(events, editor_events_with_window);

Challenge: aw-query doesn't have a built-in "attach keyvals from overlapping events" transform. Options:

• Option A: Add a new aw-query transform (e.g., merge_overlapping_events) that merges keyvals from overlapping events — clean but requires aw-query changes
• Option B: Post-process in TypeScript after the query returns — simpler, no aw-query changes needed
• Option C: Concatenate editor events into the main event stream with a synthetic $editor_origin keyval, so category rules can match them alongside window events — simplest but changes semantics

Recommended approach: Option C for v1 — it's the simplest change. Add editor_buckets to canonicalEvents() params, query them, and concat them into the event stream before categorization. This lets category rules match on project directly. A v2 can add proper merging.

Implementation Plan

1. Add editor_buckets?: string[] to canonicalEvents() params
2. In the query string, when editor_buckets are provided:
   • Query editor buckets
   • Concat into main event stream
3. Update callers (fullDesktopQuery, categoryQuery, multideviceQuery) to pass editor_buckets
4. Add tests in queries.test.node.ts
5. Extend the activity store to pass editor bucket IDs

I'll start implementation in a branch. This is the minimal change to make category rules editor-bucket-aware without a new aw-query transform.

Open Questions

• Which editor fields should be canonical? Currently project, file, language are standard. Should we also include workspace, branch, etc.?
• Window association: If the user has multiple editor windows (VS Code + terminal editor), which editor events should merge with which window events? For v1, just concat and let category rules sort it out.

[tobiasdiez]

@TimeToBuildBob implement Option B

[TimeToBuildBob]

@tobiasdiez thanks for the direction! After reviewing the design internally, we have concerns about Option B that I want to flag before starting implementation.

The core issue with Option B: Post-processing in TypeScript after the query returns creates a client-side merge layer that doesn't extend cleanly to other clients (mobile, CLI tools, etc.) or to other "subwatchers" with similar semantics — notably the browser watcher, which has the exact same problem: url/title fields from aw-watcher-browser should also be mergeable into the canonical event stream for categorization, but currently only audible is considered (see #352).

So rather than implement a TypeScript-only fix for the editor case, it would be better to design a general subwatcher-merge mechanism that handles both:

• Browser watcher: url, title → merge into window events for URL-based categorization
• Editor watcher: project, file, language → merge into window events for editor-based categorization

This likely points toward either:

1. A proper merge_overlapping_events transform in aw-query (Option A), or
2. A general subwatcher-merge layer at the query-construction level in canonicalEvents() that handles both browser and editor buckets in one pass

Would you be open to scoping this more broadly to cover both subwatcher types? That would make the feature genuinely useful for URL categorization too, which has been a long-standing request (#352). Happy to draft an updated design proposal if that direction makes sense.

[ErikBjare]

@TimeToBuildBob do it

[TimeToBuildBob]

Implemented in ActivityWatch/aw-webui#851.

The approach (Option B, TypeScript-only): added bid_editors?: string[] to BaseQueryParams. In canonicalEvents(), when editor buckets are present, their events are fetched, intersected with active-window time via filter_period_intersect, and concatenated into the main event stream before categorize() runs — so category rules can match on project, file, language alongside window fields.

The activity store now automatically passes this.buckets.editor into both fullDesktopQuery and categoryQuery, so no user configuration is needed — any connected editor watcher will contribute its fields to categorization.

v1 limitation: sum_durations will slightly double-count editor-window overlap periods. Fixable in v2 by computing duration before merging editor events.

[TimeToBuildBob]

PR ActivityWatch/aw-webui#851 implements this — it adds bid_editors to canonicalEvents, intersects editor events with the active-window period, and includes them in the event stream before categorize() so category rules matching on project, file, and language work.

CI is green. Greptile scored 4/5 with one finding (editor events in events could pollute app-breakdown aggregations since they have no app field). I have a fix ready that filters editor events out of events before merge_events_by_keys(events, ["app"]) in fullDesktopQuery, while keeping them in events for cat_events so editor-based categories still count. Let me know if you want me to push the fix and this is ready to iterate toward merge.

[TimeToBuildBob]

Following up on the architecture question (re: @ErikBjare's point that a webui-client-side merge doesn't generalize across clients/subwatchers).

The editor case here (#1305) and the browser-url case (#352) are the same problem: a subwatcher observes extra fields (project/file/language for editors, url for browsers) while a parent app is the active window, and users want to categorize() on those fields. Today neither reaches the categorized stream cleanly:

• Browser url (Can't categorize activities by URLs #352): browserEvents() pulls browser events but only consumes audible (→ not-afk); url is never merged into the window stream.
• Editor (Support editor-bucket-aware categorization for editor project/workspace rules #1305 / aw-webui#851): editor events are concat-ed as separate events. Works for categorization, but they lack app/title, creating a phantom null-app bucket and double-counting duration (the regression that had to be special-cased).

Root cause: the query2 language has concat/union_no_overlap/filter_period_intersect/split_url_events but no field-enrichment-by-overlap transform — so enrichment had to be expressed as new events instead of new fields.

Proposal: add a backend transform merge_subwatcher_fields(base, sub, keys) that, for each base (window) event, overlays the named keys from the temporally-overlapping subwatcher event onto the base event's data — unchanged timestamps/durations/count, no phantom events. Then canonicalEvents() runs one loop over subwatchers (browser → url/$domain after split_url_events; editor → project/file/language) and a single categorize(). Because it's an aw-core transform, every client gets it — not just the webui.

This closes #1305 and #352 with one mechanism and removes the null-app/double-count failure class at the root. aw-webui#851 works as a stopgap in the meantime.

Full write-up (overlap/conflict policy, migration steps): happy to open a focused aw-core issue if this direction looks right.

[TimeToBuildBob]

aw-webui#851 (feat(queries): add editor-bucket-aware categorization) and aw-core#138 (feat(transform): add merge_subwatcher_fields) are both ready to merge — CI green, Greptile 5/5. Bob doesn't have merge permissions on ActivityWatch/* repos, so a maintainer needs to land them. Erik's approval here is noted.