@clawchatsai/connector 0.1.16 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,291 @@
1
+ // SessionLens: the one place that decides which gateway sessions are ClawChats threads,
2
+ // and the filter between the gateway and the browser for session traffic.
3
+ //
4
+ // The gateway sends session-list events to every subscribed connection unfiltered, and
5
+ // the connector's single gateway connection carries everything (Discord, cron, subagents).
6
+ // The lens:
7
+ // - forwards `sessions.changed` only for visible sessions (plus key-less catalog events),
8
+ // with rows trimmed to the fields ClawChats renders;
9
+ // - drops `chat`/`agent` run events of sessions ClawChats doesn't show;
10
+ // - filters/trims the responses to browser-issued `sessions.list|subscribe|search`;
11
+ // - keeps the browser from tearing down the connector's own session subscription;
12
+ // - applies project-style side effects of browser-issued group renames/deletes;
13
+ // - fills `createdAt` on listed rows from `clawchats import-dates` when the gateway has none.
14
+ //
15
+ // Visible = a root, direct, user chat: `agent:<id>:dashboard:<id>` (gateway-created) or
16
+ // `agent:<id>:<project>:chat:<id>` (legacy ClawChats). Everything else is hidden.
17
+
18
+ const DASHBOARD_KEY = /^agent:[^:]+:dashboard:[^:]+$/;
19
+ const LEGACY_CHAT_KEY = /^agent:[^:]+:[^:]+:chat:[^:]+$/;
20
+ const UTILITY_MARK = '__clawchats_';
21
+ const MAIN_SESSION_KEY = /^agent:[^:]+:main$/;
22
+
23
+ // Session row fields the browser needs. Anything else stays on the connector side.
24
+ export const ROW_FIELDS = new Set([
25
+ 'key', 'sessionId', 'agentId', 'kind', 'chatType', 'classification', 'incognito',
26
+ 'label', 'autoLabel', 'displayName', 'derivedTitle', 'lastMessagePreview', 'icon', 'color',
27
+ 'category', 'pinned', 'pinnedAt', 'archived', 'archivedAt',
28
+ 'unread', 'lastReadAt', 'markedUnreadAt',
29
+ 'createdAt', 'updatedAt', 'lastActivityAt', 'lastInteractionAt',
30
+ 'status', 'hasActiveRun', 'activeRunIds', 'lastRunId', 'lastRunError',
31
+ 'model', 'modelProvider', 'thinkingLevel', 'contextTokens', 'totalTokens', 'totalTokensFresh',
32
+ 'inputTokens', 'outputTokens', 'permissionMode', 'contextBudgetStatus', 'fastMode', 'effectiveFastMode',
33
+ ]);
34
+
35
+ // `sessions.changed` envelope fields (snapshot fields are spread next to these).
36
+ const EVENT_ENVELOPE = new Set(['sessionKey', 'agentId', 'reason', 'phase', 'ts', 'messageId', 'catalogChanged']);
37
+
38
+ const LIST_DEFAULTS = { excludeSubagents: true, excludeCron: true, excludeSystem: true };
39
+
40
+ export function isUtilityKey(key) {
41
+ return typeof key === 'string' && key.includes(UTILITY_MARK);
42
+ }
43
+
44
+ export function isCandidateKey(key) {
45
+ return typeof key === 'string' && !isUtilityKey(key) && (DASHBOARD_KEY.test(key) || LEGACY_CHAT_KEY.test(key));
46
+ }
47
+
48
+ // ── Visibility: port of the Control UI sidebar rule ──────────────────
49
+ // ui/src/components/app-sidebar-session-parent.ts resolveSidebarSessionParentKey
50
+ // ui/src/lib/sessions/navigation.ts sessionMatchesVisibleSessionScope
51
+ // src/shared/session-list-visibility.ts isSystemCreatedSessionRow
52
+ // plus the ClawChats scope (no group conversations, no coding sessions, see grouping.ts).
53
+ // The Control UI ignores `classification`; so do we.
54
+
55
+ function hasName(row) {
56
+ return [row.label, row.displayName, row.subject].some(v => typeof v === 'string' && v.trim());
57
+ }
58
+
59
+ /** isSystemCreatedSessionRow (cron keys never reach here: not candidate-shaped). */
60
+ function isSystemCreated(row) {
61
+ if (row.classification === 'hb_signal') return !hasName(row);
62
+ if (row.createdActor?.type === 'system') return true;
63
+ if (row.createdVia !== 'run' && row.createdVia !== 'internal') return false;
64
+ if (row.createdActor?.type === 'human') return false;
65
+ return !hasName(row);
66
+ }
67
+
68
+ /**
69
+ * true = hidden, false = visible, null = undecided (partial event snapshot).
70
+ * Full rows (list rows and event snapshots, which always carry `kind`) decide everything;
71
+ * partial rows only decide on facts that can't be outweighed.
72
+ */
73
+ export function rowVerdict(row) {
74
+ if (!row || typeof row !== 'object') return null;
75
+ const parent = row.parentSessionKey || row.spawnedBy;
76
+ // Nested children (resolveSidebarSessionParentKey keeps these under their parent).
77
+ // Fork markers only matter together with a parent: a fork of a top-level chat is a
78
+ // top-level chat. ClawChats deviation: forks of main-linked chats (ClawChats edit/regen
79
+ // branches via sessions.fork) stay top level instead of nesting under the main session.
80
+ if (row.spawnedBy) return true;
81
+ if (typeof row.spawnDepth === 'number' && row.spawnDepth > 0) return true;
82
+ // sessions.fork makes the source chat the parent (Control UI nests it there). ClawChats has
83
+ // no nesting and shows edit/regenerate branches as their own chats: a fork whose parent is
84
+ // the chat it was forked from counts as a top-level chat.
85
+ const forkOfChat = !!(row.parentSessionKey && row.forkSource?.sessionKey === row.parentSessionKey && isCandidateKey(row.parentSessionKey));
86
+ if (forkOfChat) return 'kind' in row ? (row.kind === 'global' || row.kind === 'unknown' || row.kind === 'group' || !!row.worktree || !!row.execNode) : null;
87
+ if (parent && !MAIN_SESSION_KEY.test(parent)) return true;
88
+ // Out of the visible scope, or outside ClawChats' scope (Groups / Coding zones).
89
+ if (row.kind === 'global' || row.kind === 'unknown' || row.kind === 'group') return true;
90
+ if (row.worktree || row.execNode) return true;
91
+ if (!('kind' in row)) return null;
92
+ if (isSystemCreated(row)) return true;
93
+ // Main-linked roots are top level only when operator-created (older rows stay nested).
94
+ if (parent && row.createdVia !== 'operator' && !row.forkSource) return true;
95
+ return false;
96
+ }
97
+
98
+ export function trimRow(row) {
99
+ const out = {};
100
+ for (const k of Object.keys(row)) if (ROW_FIELDS.has(k)) out[k] = row[k];
101
+ return out;
102
+ }
103
+
104
+ export function trimEvent(payload) {
105
+ const out = {};
106
+ for (const k of Object.keys(payload)) {
107
+ if (EVENT_ENVELOPE.has(k) || ROW_FIELDS.has(k)) out[k] = payload[k];
108
+ }
109
+ if (payload.session && typeof payload.session === 'object') out.session = trimRow(payload.session);
110
+ return out;
111
+ }
112
+
113
+ export class SessionLens {
114
+ /**
115
+ * @param {object} opts
116
+ * @param {(data: string) => void} opts.broadcast send a frame to all browsers
117
+ * @param {(method: string, params: object, timeoutMs?: number) => Promise<any>} [opts.request] connector-originated gateway RPC
118
+ * @param {object} [opts.extras] ExtrasStore (project style side effects)
119
+ */
120
+ constructor({ broadcast, request, extras, logger = console }) {
121
+ this.broadcast = broadcast;
122
+ this.request = request;
123
+ this.extras = extras;
124
+ this.log = logger;
125
+ this.hidden = new Set(); // candidate-shaped keys a row revealed as not a user chat
126
+ this.pending = new Map(); // browser req id -> { method, params }
127
+ // Chats a browser opened with sessions.messages.subscribe (Control UI: one per selected
128
+ // chat). session.message is forwarded only for these. subscriptionId -> session key.
129
+ this.watching = new Map();
130
+ }
131
+
132
+ // ── Visibility ──────────────────────────────────────────────────────
133
+
134
+ /** Learn from a (possibly partial) row; returns whether the session is visible. */
135
+ observe(key, row) {
136
+ if (!isCandidateKey(key)) return false;
137
+ const verdict = rowVerdict(row);
138
+ if (verdict === true) this.hidden.add(key);
139
+ else if (verdict === false) this.hidden.delete(key);
140
+ return !this.hidden.has(key);
141
+ }
142
+
143
+ isVisible(key) {
144
+ return isCandidateKey(key) && !this.hidden.has(key);
145
+ }
146
+
147
+ /** chat/agent run events: visible chats plus the connector's own utility sessions. */
148
+ forwardsRunEvent(key) {
149
+ return isUtilityKey(key) || this.isVisible(key);
150
+ }
151
+
152
+ /** Seed `hidden` from a full roster so partial events of child sessions stay hidden. */
153
+ async seed() {
154
+ if (!this.request) return;
155
+ let offset = 0, rows = 0;
156
+ for (let page = 0; page < 50; page++) {
157
+ const res = await this.request('sessions.list', { archived: 'all', limit: 1000, offset }, 60000);
158
+ for (const row of res?.sessions || []) { this.observe(row.key, row); rows++; }
159
+ if (!res?.hasMore || res.nextOffset == null) break;
160
+ offset = res.nextOffset;
161
+ }
162
+ this.log.info?.(`[lens] seeded from ${rows} sessions (${this.hidden.size} hidden chat-shaped)`);
163
+ }
164
+
165
+ // ── Gateway → browser ───────────────────────────────────────────────
166
+
167
+ /** `sessions.changed`. Returns the frame to broadcast, or null to drop. */
168
+ sessionsChanged(payload) {
169
+ if (!payload || typeof payload !== 'object') return null;
170
+ const key = payload.sessionKey;
171
+ if (!key) return { type: 'event', event: 'sessions.changed', payload: trimEvent(payload) }; // catalog/groups
172
+ if (!this.observe(key, payload.session || payload)) return null;
173
+ if (payload.reason === 'delete' && this.extras) this.extras.deleteThreadExtras?.(key);
174
+ return { type: 'event', event: 'sessions.changed', payload: trimEvent(payload) };
175
+ }
176
+
177
+ /** `session.message` (live transcript entry). Forwarded only for watched visible chats. */
178
+ sessionMessage(payload) {
179
+ const key = payload?.sessionKey;
180
+ if (!key || !this.isVisible(key) || ![...this.watching.values()].includes(key)) return null;
181
+ const out = {};
182
+ for (const k of Object.keys(payload)) if (k === 'message' || k === 'messageId' || k === 'messageSeq' || k === 'runId' || EVENT_ENVELOPE.has(k) || ROW_FIELDS.has(k)) out[k] = payload[k];
183
+ return { type: 'event', event: 'session.message', payload: out };
184
+ }
185
+
186
+ // ── Browser → gateway ───────────────────────────────────────────────
187
+
188
+ /**
189
+ * Inspect a browser frame bound for the gateway. Returns the (possibly rewritten) frame
190
+ * to send, or null when the lens answered it itself.
191
+ */
192
+ outbound(frame) {
193
+ let msg;
194
+ try { msg = JSON.parse(frame); } catch { return frame; }
195
+ if (msg?.type !== 'req' || typeof msg.method !== 'string') return frame;
196
+ const { id, method } = msg;
197
+ const params = msg.params && typeof msg.params === 'object' ? msg.params : {};
198
+ switch (method) {
199
+ case 'sessions.unsubscribe':
200
+ // The gateway subscription is per connection and the connector owns it.
201
+ this.broadcast(JSON.stringify({ type: 'res', id, ok: true, payload: { subscribed: true } }));
202
+ return null;
203
+ case 'sessions.list':
204
+ case 'sessions.subscribe': {
205
+ this.pending.set(id, { method });
206
+ // A bare subscribe only toggles the subscription; don't turn it into a list call.
207
+ if (method === 'sessions.subscribe' && Object.keys(params).length === 0) return frame;
208
+ return JSON.stringify({ ...msg, params: { ...LIST_DEFAULTS, ...params } });
209
+ }
210
+ case 'sessions.messages.subscribe':
211
+ if (params.key) this.watching.set(params.subscriptionId || `key:${params.key}`, params.key);
212
+ return frame;
213
+ case 'sessions.messages.unsubscribe':
214
+ if (params.subscriptionId) this.watching.delete(params.subscriptionId);
215
+ else for (const [id, k] of this.watching) if (k === params.key) this.watching.delete(id);
216
+ return frame;
217
+ case 'sessions.search':
218
+ case 'sessions.groups.rename':
219
+ case 'sessions.groups.delete':
220
+ this.pending.set(id, { method, params });
221
+ return frame;
222
+ default:
223
+ return frame;
224
+ }
225
+ }
226
+
227
+ ownsResponse(id) {
228
+ return this.pending.has(id);
229
+ }
230
+
231
+ /** Response to a browser request the lens tracks. Returns the frame object to broadcast. */
232
+ response(msg) {
233
+ const req = this.pending.get(msg.id);
234
+ this.pending.delete(msg.id);
235
+ if (!req || !msg.ok || !msg.payload) return msg;
236
+ const p = msg.payload;
237
+ switch (req.method) {
238
+ case 'sessions.list':
239
+ return { ...msg, payload: this._filterList(p) };
240
+ case 'sessions.subscribe':
241
+ return p.list ? { ...msg, payload: { ...p, list: this._filterList(p.list) } } : msg;
242
+ case 'sessions.search': {
243
+ const results = (p.results || []).filter(r => this.isVisible(r.sessionKey));
244
+ const sessions = p.sessions ? this._visibleRows(p.sessions) : undefined;
245
+ return { ...msg, payload: { ...p, results, ...(sessions ? { sessions } : {}) } };
246
+ }
247
+ case 'sessions.groups.rename':
248
+ try { this.extras?.renameProjectStyle(req.params?.name, req.params?.to); }
249
+ catch (e) { this.log.warn?.(`[lens] style rename: ${e.message}`); }
250
+ return msg;
251
+ case 'sessions.groups.delete':
252
+ try { this.extras?.deleteProjectStyle(req.params?.name); }
253
+ catch (e) { this.log.warn?.(`[lens] style delete: ${e.message}`); }
254
+ return msg;
255
+ default:
256
+ return msg;
257
+ }
258
+ }
259
+
260
+ _visibleRows(rows) {
261
+ // Creation times of pre-gateway chats (their gateway row has no createdAt). Read per list so
262
+ // `import-dates` applies without a restart; the browser store merges rows, so filling list
263
+ // responses is enough.
264
+ let legacy = null;
265
+ try { legacy = this.extras?.getLegacyCreatedAt?.(); } catch (e) { this.log.warn?.(`[lens] legacy dates: ${e.message}`); }
266
+ const out = [];
267
+ for (const row of rows || []) {
268
+ if (!row || !this.observe(row.key, row)) continue;
269
+ const trimmed = trimRow(row);
270
+ if (!trimmed.createdAt && legacy?.has(row.key)) trimmed.createdAt = legacy.get(row.key);
271
+ out.push(trimmed);
272
+ }
273
+ return out;
274
+ }
275
+
276
+ _filterList(list) {
277
+ if (!list || !Array.isArray(list.sessions)) return list;
278
+ const sessions = this._visibleRows(list.sessions);
279
+ // Keep paging (gateway offsets stay valid) and defaults; counts/facets described the
280
+ // unfiltered roster, so `count` is recomputed and totals/owners are dropped.
281
+ const out = { sessions, count: sessions.length };
282
+ for (const k of ['ts', 'hasMore', 'nextOffset', 'limitApplied', 'defaults']) if (k in list) out[k] = list[k];
283
+ return out;
284
+ }
285
+
286
+ /** Forget request ids that never got an answer (gateway disconnect). */
287
+ reset() {
288
+ this.pending.clear();
289
+ this.watching.clear(); // gateway connection gone: browsers re-subscribe on reconnect
290
+ }
291
+ }
@@ -0,0 +1,179 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { SessionLens, isCandidateKey, trimRow } from './session-lens.js';
4
+
5
+ const CHAT = 'agent:main:dashboard:abc';
6
+ const LEGACY = 'agent:main:proxmox:chat:1234';
7
+ const CHILD = 'agent:main:dashboard:child1';
8
+ const DISCORD = 'agent:main:discord:channel:99';
9
+
10
+ function lens(extras) {
11
+ const sent = [];
12
+ const l = new SessionLens({ broadcast: d => sent.push(JSON.parse(d)), extras, logger: { info() {}, warn() {} } });
13
+ return { l, sent };
14
+ }
15
+
16
+ test('key shapes', () => {
17
+ assert.ok(isCandidateKey(CHAT));
18
+ assert.ok(isCandidateKey(LEGACY));
19
+ for (const k of [DISCORD, 'agent:main:main', 'agent:main:cron:x', 'agent:main:recovered:x', 'agent:main:__clawchats_summarizer', 'agent:main:x:chat:__clawchats_title_1', 'agent:main:node-1'])
20
+ assert.equal(isCandidateKey(k), false, k);
21
+ });
22
+
23
+ test('child sessions stay hidden once a row revealed them, even for partial events', () => {
24
+ const { l } = lens();
25
+ assert.equal(l.sessionsChanged({ sessionKey: CHILD, reason: 'create', parentSessionKey: CHAT, label: 'x' }), null);
26
+ assert.equal(l.sessionsChanged({ sessionKey: CHILD, phase: 'message', ts: 1 }), null);
27
+ assert.equal(l.forwardsRunEvent(CHILD), false);
28
+ });
29
+
30
+ test('visible change is trimmed; catalog events pass', () => {
31
+ const { l } = lens();
32
+ const f = l.sessionsChanged({ sessionKey: CHAT, reason: 'patch', ts: 5, label: 'Hi', category: 'Default', participants: [1, 2], swarm: {}, session: { key: CHAT, label: 'Hi', owner: {}, thinkingOptions: [] } });
33
+ assert.deepEqual(f.payload, { sessionKey: CHAT, reason: 'patch', ts: 5, label: 'Hi', category: 'Default', session: { key: CHAT, label: 'Hi' } });
34
+ assert.equal(l.sessionsChanged({ sessionKey: DISCORD, reason: 'send', channel: 'discord' }), null);
35
+ assert.deepEqual(l.sessionsChanged({ reason: 'groups', ts: 1 }).payload, { reason: 'groups', ts: 1 });
36
+ });
37
+
38
+ test('run events: visible chats and utility sessions only', () => {
39
+ const { l } = lens();
40
+ assert.ok(l.forwardsRunEvent(CHAT));
41
+ assert.ok(l.forwardsRunEvent('agent:main:__clawchats_semantic'));
42
+ assert.ok(l.forwardsRunEvent('agent:main:__clawchats_title_42'));
43
+ assert.equal(l.forwardsRunEvent(DISCORD), false);
44
+ assert.equal(l.forwardsRunEvent('agent:main:main'), false);
45
+ });
46
+
47
+ test('browser sessions.list gets defaults and a filtered, trimmed response', () => {
48
+ const { l } = lens();
49
+ const out = JSON.parse(l.outbound(JSON.stringify({ type: 'req', id: 'r1', method: 'sessions.list', params: { limit: 50 } })));
50
+ assert.deepEqual(out.params, { excludeSubagents: true, excludeCron: true, excludeSystem: true, limit: 50 });
51
+ assert.ok(l.ownsResponse('r1'));
52
+ const res = l.response({ type: 'res', id: 'r1', ok: true, payload: {
53
+ ts: 1, count: 4, totalCount: 4, hasMore: false, nextOffset: null, owners: [{}],
54
+ sessions: [
55
+ { key: CHAT, label: 'a', owner: {}, classification: 'direct' },
56
+ { key: LEGACY, label: 'b', classification: 'direct' },
57
+ { key: CHILD, parentSessionKey: CHAT, classification: 'direct' },
58
+ { key: DISCORD, classification: 'channel' },
59
+ ] } });
60
+ assert.deepEqual(res.payload.sessions.map(s => s.key), [CHAT, LEGACY]);
61
+ assert.equal(res.payload.count, 2);
62
+ assert.equal('owners' in res.payload, false);
63
+ assert.equal('owner' in res.payload.sessions[0], false);
64
+ assert.equal(l.ownsResponse('r1'), false);
65
+ });
66
+
67
+ test('bare sessions.subscribe passes untouched; subscribe-with-list is filtered', () => {
68
+ const { l } = lens();
69
+ const bare = JSON.stringify({ type: 'req', id: 's0', method: 'sessions.subscribe', params: {} });
70
+ assert.equal(l.outbound(bare), bare);
71
+ l.outbound(JSON.stringify({ type: 'req', id: 's1', method: 'sessions.subscribe', params: { limit: 10 } }));
72
+ const res = l.response({ type: 'res', id: 's1', ok: true, payload: { subscribed: true, list: { sessions: [{ key: CHAT }, { key: DISCORD }] } } });
73
+ assert.deepEqual(res.payload.list.sessions.map(s => s.key), [CHAT]);
74
+ });
75
+
76
+ test('sessions.unsubscribe from a browser is answered locally', () => {
77
+ const { l, sent } = lens();
78
+ assert.equal(l.outbound(JSON.stringify({ type: 'req', id: 'u1', method: 'sessions.unsubscribe' })), null);
79
+ assert.deepEqual(sent[0], { type: 'res', id: 'u1', ok: true, payload: { subscribed: true } });
80
+ });
81
+
82
+ test('search results are limited to visible sessions', () => {
83
+ const { l } = lens();
84
+ l.outbound(JSON.stringify({ type: 'req', id: 'q', method: 'sessions.search', params: { query: 'x' } }));
85
+ const res = l.response({ type: 'res', id: 'q', ok: true, payload: { results: [{ sessionKey: CHAT }, { sessionKey: DISCORD }], sessions: [{ key: CHAT }, { key: DISCORD }] } });
86
+ assert.deepEqual(res.payload.results, [{ sessionKey: CHAT }]);
87
+ assert.deepEqual(res.payload.sessions, [{ key: CHAT }]);
88
+ });
89
+
90
+ test('group rename/delete move project styles only on success', () => {
91
+ const calls = [];
92
+ const extras = { renameProjectStyle: (a, b) => calls.push(['rename', a, b]), deleteProjectStyle: a => calls.push(['delete', a]), deleteThreadExtras: k => calls.push(['thread', k]) };
93
+ const { l } = lens(extras);
94
+ l.outbound(JSON.stringify({ type: 'req', id: 'g1', method: 'sessions.groups.rename', params: { name: 'A', to: 'B' } }));
95
+ l.outbound(JSON.stringify({ type: 'req', id: 'g2', method: 'sessions.groups.delete', params: { name: 'C' } }));
96
+ l.outbound(JSON.stringify({ type: 'req', id: 'g3', method: 'sessions.groups.delete', params: { name: 'D' } }));
97
+ l.response({ type: 'res', id: 'g1', ok: true, payload: {} });
98
+ l.response({ type: 'res', id: 'g2', ok: true, payload: {} });
99
+ l.response({ type: 'res', id: 'g3', ok: false, error: { message: 'nope' } });
100
+ l.sessionsChanged({ sessionKey: CHAT, reason: 'delete' });
101
+ assert.deepEqual(calls, [['rename', 'A', 'B'], ['delete', 'C'], ['thread', CHAT]]);
102
+ });
103
+
104
+ test('trimRow keeps only allow-listed fields', () => {
105
+ assert.deepEqual(trimRow({ key: 'k', unread: true, participants: [], thinkingOptions: [] }), { key: 'k', unread: true });
106
+ });
107
+
108
+ test('chat.history passes through untouched (gateway enforces maxBytes)', () => {
109
+ const { l } = lens();
110
+ const f = JSON.stringify({ type: 'req', id: 'h', method: 'chat.history', params: { sessionKey: CHAT, limit: 80, maxBytes: 262144 } });
111
+ assert.equal(l.outbound(f), f);
112
+ assert.equal(l.ownsResponse('h'), false);
113
+ });
114
+
115
+ test('operator roots linked to the main session are visible; real children are not', () => {
116
+ const { l } = lens();
117
+ assert.ok(l.sessionsChanged({ sessionKey: CHAT, reason: 'create', parentSessionKey: 'agent:main:main', spawnDepth: 0, category: 'test' }));
118
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:k1', reason: 'create', parentSessionKey: 'agent:main:main', spawnedBy: 'agent:main:main' }), null);
119
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:k2', reason: 'create', parentSessionKey: CHAT }), null);
120
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:k3', reason: 'create', parentSessionKey: 'agent:main:main', spawnDepth: 1 }), null);
121
+ });
122
+
123
+ test('Control UI rule: classification ignored, kind/provenance decide, full rows can un-hide', () => {
124
+ const { l } = lens();
125
+ assert.ok(l.sessionsChanged({ sessionKey: CHAT, reason: 'create', classification: 'dashboard', parentSessionKey: 'agent:main:main', spawnDepth: 0 }));
126
+ const K = 'agent:main:dashboard:flip';
127
+ assert.equal(l.sessionsChanged({ sessionKey: K, reason: 'x', kind: 'group' }), null);
128
+ assert.ok(l.sessionsChanged({ sessionKey: K, reason: 'patch', kind: 'direct', createdVia: 'operator', parentSessionKey: 'agent:main:main', spawnDepth: 0 }));
129
+ // legacy main-linked row without operator provenance nests under Home
130
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:old', reason: 'patch', kind: 'direct', parentSessionKey: 'agent:main:main' }), null);
131
+ // system-created probe without a name
132
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:probe', reason: 'create', kind: 'direct', createdVia: 'internal' }), null);
133
+ // coding sessions
134
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:wt', reason: 'create', kind: 'direct', worktree: { id: 'w' } }), null);
135
+ });
136
+
137
+ test('forks of chats are chats (edit/regen branches)', () => {
138
+ const { l } = lens();
139
+ // fork of a legacy top-level chat: no parent
140
+ assert.ok(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:f1', reason: 'create', kind: 'direct', forkSource: { sessionKey: LEGACY, sessionId: 's' } }));
141
+ // fork of a dashboard chat: inherits the main link
142
+ assert.ok(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:f2', reason: 'create', kind: 'direct', createdVia: 'operator', parentSessionKey: 'agent:main:main', spawnDepth: 0, forkSource: { sessionKey: CHAT, sessionId: 's' } }));
143
+ // a fork nested under another chat is still a child
144
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:f3', reason: 'create', kind: 'direct', parentSessionKey: CHAT, forkSource: { sessionKey: LEGACY, sessionId: 's' } }), null); // parent is not the fork source
145
+ });
146
+
147
+ test('sessions.fork branches (parent = source chat) are top-level chats', () => {
148
+ const { l } = lens();
149
+ const SRC = 'agent:main:dashboard:src';
150
+ assert.ok(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:br', reason: 'create', kind: 'direct', createdVia: 'operator', parentSessionKey: SRC, forkedFromParent: true, forkSource: { sessionKey: SRC, sessionId: 's', entryId: 'e' } }));
151
+ assert.ok(l.forwardsRunEvent('agent:main:dashboard:br'));
152
+ // a child whose parent is a chat but that is not a fork of it stays nested
153
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:kid', reason: 'create', kind: 'direct', parentSessionKey: SRC }), null);
154
+ // fork of a channel session is not a chat
155
+ assert.equal(l.sessionsChanged({ sessionKey: 'agent:main:dashboard:br2', reason: 'create', kind: 'direct', parentSessionKey: DISCORD, forkSource: { sessionKey: DISCORD } }), null);
156
+ });
157
+
158
+ test('session.message only for chats a browser subscribed to', () => {
159
+ const { l } = lens();
160
+ const msg = { sessionKey: CHAT, message: { role: 'assistant', content: [] }, messageId: 'm', participants: [1] };
161
+ assert.equal(l.sessionMessage(msg), null);
162
+ l.outbound(JSON.stringify({ type: 'req', id: 's', method: 'sessions.messages.subscribe', params: { key: CHAT, subscriptionId: 'tab1' } }));
163
+ const f = l.sessionMessage(msg);
164
+ assert.deepEqual(f.payload, { sessionKey: CHAT, message: msg.message, messageId: 'm' });
165
+ assert.equal(l.sessionMessage({ ...msg, sessionKey: DISCORD }), null);
166
+ l.outbound(JSON.stringify({ type: 'req', id: 'u', method: 'sessions.messages.unsubscribe', params: { key: CHAT, subscriptionId: 'tab1' } }));
167
+ assert.equal(l.sessionMessage(msg), null);
168
+ });
169
+
170
+ test('listed rows without createdAt get the legacy creation time; gateway values win', () => {
171
+ const extras = { getLegacyCreatedAt: () => new Map([[LEGACY, 111], [CHAT, 222]]) };
172
+ const { l } = lens(extras);
173
+ l.outbound(JSON.stringify({ type: 'req', id: 'c1', method: 'sessions.list', params: {} }));
174
+ const res = l.response({ type: 'res', id: 'c1', ok: true, payload: { sessions: [
175
+ { key: LEGACY, label: 'old', kind: 'direct' },
176
+ { key: CHAT, label: 'new', kind: 'direct', createdAt: 999 },
177
+ ] } });
178
+ assert.deepEqual(res.payload.sessions.map(s => s.createdAt), [111, 999]);
179
+ });
@@ -0,0 +1,92 @@
1
+ // ExtrasStore: ClawChats-only data the gateway has no place for. Lives in the global DB.
2
+ // Registry of what belongs here: EXTRAS.md at the repo root.
3
+ //
4
+ // project_styles color/icon per gateway session group (groups are just {name, position})
5
+ // thread_extras per-session ClawChats data (Intelligence panel etc.), keyed by session key
6
+ // legacy_created creation time of chats from before the gateway recorded createdAt
7
+
8
+ export function createExtrasStore(getGlobalDb) {
9
+ let ready = false;
10
+ function db() {
11
+ const g = getGlobalDb();
12
+ if (!ready) {
13
+ g.exec(`CREATE TABLE IF NOT EXISTS project_styles (name TEXT PRIMARY KEY, color TEXT, icon TEXT, updated_at INTEGER NOT NULL)`);
14
+ g.exec(`CREATE TABLE IF NOT EXISTS legacy_created (session_key TEXT PRIMARY KEY, created_at INTEGER NOT NULL)`);
15
+ g.exec(`CREATE TABLE IF NOT EXISTS thread_extras (session_key TEXT NOT NULL, kind TEXT NOT NULL, data TEXT NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY (session_key, kind))`);
16
+ ready = true;
17
+ }
18
+ return g;
19
+ }
20
+
21
+ return {
22
+ /** { [groupName]: { color, icon } } */
23
+ getProjectStyles() {
24
+ const out = {};
25
+ for (const r of db().prepare('SELECT name, color, icon FROM project_styles').all()) out[r.name] = { color: r.color, icon: r.icon };
26
+ return out;
27
+ },
28
+
29
+ /** Set color and/or icon; absent fields keep their value, null clears. */
30
+ setProjectStyle(name, { color, icon } = {}) {
31
+ if (!name) return;
32
+ const cur = db().prepare('SELECT color, icon FROM project_styles WHERE name = ?').get(name) || {};
33
+ db().prepare('INSERT INTO project_styles (name, color, icon, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(name) DO UPDATE SET color = excluded.color, icon = excluded.icon, updated_at = excluded.updated_at')
34
+ .run(name, color !== undefined ? color : (cur.color ?? null), icon !== undefined ? icon : (cur.icon ?? null), Date.now());
35
+ },
36
+
37
+ renameProjectStyle(from, to) {
38
+ if (!from || !to || from === to) return;
39
+ const g = db();
40
+ g.exec('BEGIN');
41
+ try {
42
+ g.prepare('DELETE FROM project_styles WHERE name = ?').run(to);
43
+ g.prepare('UPDATE project_styles SET name = ?, updated_at = ? WHERE name = ?').run(to, Date.now(), from);
44
+ g.exec('COMMIT');
45
+ } catch (e) { g.exec('ROLLBACK'); throw e; }
46
+ },
47
+
48
+ deleteProjectStyle(name) {
49
+ if (name) db().prepare('DELETE FROM project_styles WHERE name = ?').run(name);
50
+ },
51
+
52
+ /**
53
+ * Copy styles of legacy projects (workspaces.json) that have none yet. Never overwrites,
54
+ * so a style set through the gateway-native UI wins over the legacy file.
55
+ */
56
+ seedFromWorkspaces(workspaces) {
57
+ const ins = db().prepare('INSERT OR IGNORE INTO project_styles (name, color, icon, updated_at) VALUES (?, ?, ?, ?)');
58
+ let n = 0;
59
+ for (const p of Object.values(workspaces?.workspaces || {})) {
60
+ if (p?.label && (p.color || p.icon)) n += ins.run(p.label, p.color || null, p.icon || null, Date.now()).changes;
61
+ }
62
+ return n;
63
+ },
64
+
65
+ /** Store legacy creation times ([{ sessionKey, createdAt }]); never overwrites. */
66
+ seedLegacyCreatedAt(rows) {
67
+ const ins = db().prepare('INSERT OR IGNORE INTO legacy_created (session_key, created_at) VALUES (?, ?)');
68
+ let n = 0;
69
+ for (const r of rows || []) if (r?.sessionKey && r.createdAt > 0) n += ins.run(r.sessionKey, r.createdAt).changes;
70
+ return n;
71
+ },
72
+
73
+ /** Map of session key -> legacy creation time (ms). */
74
+ getLegacyCreatedAt() {
75
+ return new Map(db().prepare('SELECT session_key, created_at FROM legacy_created').all().map(r => [r.session_key, r.created_at]));
76
+ },
77
+
78
+ getThreadExtra(sessionKey, kind) {
79
+ const r = db().prepare('SELECT data FROM thread_extras WHERE session_key = ? AND kind = ?').get(sessionKey, kind);
80
+ return r ? JSON.parse(r.data) : null;
81
+ },
82
+
83
+ setThreadExtra(sessionKey, kind, data) {
84
+ db().prepare('INSERT INTO thread_extras (session_key, kind, data, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(session_key, kind) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at')
85
+ .run(sessionKey, kind, JSON.stringify(data), Date.now());
86
+ },
87
+
88
+ deleteThreadExtras(sessionKey) {
89
+ if (sessionKey) db().prepare('DELETE FROM thread_extras WHERE session_key = ?').run(sessionKey);
90
+ },
91
+ };
92
+ }
@@ -0,0 +1,42 @@
1
+ // `ocplatform clawchats import-dates`: one-off migration from the pre-gateway ClawChats databases
2
+ // (one <project>.db per project in the data dir, each with a `threads` table). The gateway has no
3
+ // creation time for sessions created before it recorded `createdAt`, and `sessions.patch` can't
4
+ // set one, so the connector keeps them (ExtrasStore `legacy_created`). Safe to re-run. Once every
5
+ // install has run it, this file and the command can go; the stored dates stay.
6
+
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import { Database } from '../bootstrap/native.js';
10
+ import { createExtrasStore } from './extras-store.js';
11
+
12
+ /** [{ sessionKey, createdAt }] from every legacy project DB in `dataDir`; unreadable files are skipped. */
13
+ export function readLegacyThreadDates(dataDir, logger = console) {
14
+ const out = [];
15
+ let files = [];
16
+ try { files = fs.readdirSync(dataDir).filter(f => f.endsWith('.db') && f !== 'global.db'); } catch { return out; }
17
+ for (const f of files) {
18
+ let db;
19
+ try {
20
+ db = new Database(path.join(dataDir, f), { readOnly: true });
21
+ const hasThreads = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'threads'").get();
22
+ if (!hasThreads) continue;
23
+ for (const r of db.prepare('SELECT session_key, created_at FROM threads WHERE session_key IS NOT NULL AND created_at > 0').all()) {
24
+ out.push({ sessionKey: r.session_key, createdAt: Number(r.created_at) });
25
+ }
26
+ } catch (e) {
27
+ logger.warn?.(`[legacy] skipped ${f}: ${e.message}`);
28
+ } finally {
29
+ db?.close();
30
+ }
31
+ }
32
+ return out;
33
+ }
34
+
35
+ /** Copy legacy creation times into global.db. Returns { found, imported } (imported = new rows). */
36
+ export function importLegacyThreadDates(dataDir, logger = console) {
37
+ const rows = readLegacyThreadDates(dataDir, logger);
38
+ const db = new Database(path.join(dataDir, 'global.db'));
39
+ try {
40
+ return { found: rows.length, imported: createExtrasStore(() => db).seedLegacyCreatedAt(rows) };
41
+ } finally { db.close(); }
42
+ }
@@ -0,0 +1,50 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import fs from 'node:fs';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import { Database } from '../bootstrap/native.js';
7
+ import { readLegacyThreadDates, importLegacyThreadDates } from './legacy-threads.js';
8
+ import { createExtrasStore } from './extras-store.js';
9
+
10
+ function legacyDb(file, rows) {
11
+ const db = new Database(file);
12
+ db.exec('CREATE TABLE threads (id TEXT, session_key TEXT, created_at INTEGER)');
13
+ const ins = db.prepare('INSERT INTO threads VALUES (?, ?, ?)');
14
+ for (const r of rows) ins.run(...r);
15
+ db.close();
16
+ }
17
+
18
+ test('reads creation times from every legacy project DB; skips global.db, non-thread DBs and junk', () => {
19
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-legacy-'));
20
+ try {
21
+ legacyDb(path.join(dir, 'default.db'), [['a', 'agent:main:default:chat:a', 100], ['b', null, 200], ['c', 'agent:main:default:chat:c', 0]]);
22
+ legacyDb(path.join(dir, 'proxmox.db'), [['p', 'agent:main:proxmox:chat:p', 300]]);
23
+ legacyDb(path.join(dir, 'global.db'), [['g', 'agent:main:x:chat:g', 400]]);
24
+ new Database(path.join(dir, 'alerts.db')).close(); // no threads table
25
+ fs.writeFileSync(path.join(dir, 'broken.db'), 'not sqlite');
26
+ const rows = readLegacyThreadDates(dir, { warn() {} }).sort((x, y) => x.createdAt - y.createdAt);
27
+ assert.deepEqual(rows, [{ sessionKey: 'agent:main:default:chat:a', createdAt: 100 }, { sessionKey: 'agent:main:proxmox:chat:p', createdAt: 300 }]);
28
+ assert.deepEqual(readLegacyThreadDates(path.join(dir, 'missing')), []);
29
+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }
30
+ });
31
+
32
+ test('seeding is insert-or-ignore and readable as a map', () => {
33
+ const g = new Database(':memory:');
34
+ const extras = createExtrasStore(() => g);
35
+ assert.equal(extras.seedLegacyCreatedAt([{ sessionKey: 'k1', createdAt: 5 }, { sessionKey: 'k2', createdAt: 6 }, { sessionKey: '', createdAt: 7 }]), 2);
36
+ assert.equal(extras.seedLegacyCreatedAt([{ sessionKey: 'k1', createdAt: 99 }]), 0);
37
+ assert.deepEqual([...extras.getLegacyCreatedAt()], [['k1', 5], ['k2', 6]]);
38
+ });
39
+
40
+ test('import-dates: writes into global.db, re-running imports nothing new', () => {
41
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-legacy-'));
42
+ try {
43
+ legacyDb(path.join(dir, 'default.db'), [['a', 'agent:main:default:chat:a', 100]]);
44
+ assert.deepEqual(importLegacyThreadDates(dir), { found: 1, imported: 1 });
45
+ assert.deepEqual(importLegacyThreadDates(dir), { found: 1, imported: 0 });
46
+ const g = new Database(path.join(dir, 'global.db'));
47
+ assert.deepEqual([...createExtrasStore(() => g).getLegacyCreatedAt()], [['agent:main:default:chat:a', 100]]);
48
+ g.close();
49
+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }
50
+ });