@kabmo-labs/kabmo 0.14.1 → 0.16.0

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.
Files changed (76) hide show
  1. package/README.md +1 -0
  2. package/dist/client/index.html +1 -1
  3. package/dist/client/index.js +374 -356
  4. package/dist/client/static/js/{index-w6jx0h0p.js → index-cpydmygd.js} +661 -661
  5. package/dist/client/static/js/index-fjnq2z2d.css +1 -0
  6. package/marketplace/plugins/command-runner/README.md +5 -3
  7. package/marketplace/plugins/command-runner/package.json +2 -2
  8. package/marketplace/plugins/command-runner/src/app.tsx +3 -3
  9. package/marketplace/plugins/command-runner/src/panel/Groups.test.tsx +25 -21
  10. package/marketplace/plugins/command-runner/src/panel/Groups.tsx +4 -1
  11. package/marketplace/plugins/stats/README.md +27 -8
  12. package/marketplace/plugins/stats/package.json +2 -2
  13. package/marketplace/plugins/stats/src/HeaderReadout.test.tsx +2 -1
  14. package/marketplace/plugins/stats/src/HeaderReadout.tsx +6 -2
  15. package/marketplace/plugins/stats/src/KillConfirm.test.tsx +159 -0
  16. package/marketplace/plugins/stats/src/KillConfirm.tsx +145 -0
  17. package/marketplace/plugins/stats/src/ProcessTable.tsx +54 -8
  18. package/marketplace/plugins/stats/src/TotalsBar.test.tsx +5 -2
  19. package/marketplace/plugins/stats/src/TotalsBar.tsx +13 -3
  20. package/marketplace/plugins/stats/src/app.test.tsx +100 -4
  21. package/marketplace/plugins/stats/src/app.tsx +51 -4
  22. package/marketplace/plugins/stats/src/groups.test.ts +1 -1
  23. package/marketplace/plugins/stats/src/kill.test.ts +131 -0
  24. package/marketplace/plugins/stats/src/kill.ts +74 -0
  25. package/marketplace/plugins/stats/src/labels.test.ts +1 -0
  26. package/marketplace/plugins/stats/src/machine.test.ts +77 -0
  27. package/marketplace/plugins/stats/src/machine.ts +115 -0
  28. package/marketplace/plugins/stats/src/proc/darwin.ts +38 -0
  29. package/marketplace/plugins/stats/src/proc/linux.ts +4 -0
  30. package/marketplace/plugins/stats/src/proc/ps.ts +1 -0
  31. package/marketplace/plugins/stats/src/proc/types.ts +11 -0
  32. package/marketplace/plugins/stats/src/sampler.test.ts +42 -4
  33. package/marketplace/plugins/stats/src/sampler.ts +32 -18
  34. package/marketplace/plugins/stats/src/server.ts +29 -2
  35. package/marketplace/plugins/stats/src/snapshot.ts +31 -3
  36. package/package.json +3 -2
  37. package/src/client/components/common/Modal.tsx +7 -0
  38. package/src/client/components/layout/LeftDock.tsx +1 -0
  39. package/src/client/components/layout/desktop-layout/WorkspacePanels.tsx +1 -0
  40. package/src/client/components/mobile/LayoutWrapper.tsx +11 -10
  41. package/src/client/components/mobile/RightSidebar.tsx +1 -0
  42. package/src/client/components/mobile/mobile-session-sidebar/use-dock.ts +1 -0
  43. package/src/client/components/mobile/open-file-payload.test.ts +29 -1
  44. package/src/client/components/mobile/open-file-payload.ts +28 -0
  45. package/src/client/components/settings/Modal.tsx +2 -2
  46. package/src/client/components/workspace/editor/index.tsx +6 -8
  47. package/src/client/components/workspace/git-panel/branch-modal/index.tsx +4 -3
  48. package/src/client/components/workspace/git-panel/commit-modal/index.tsx +1 -1
  49. package/src/client/components/workspace/model-dropdown/Panel.tsx +7 -2
  50. package/src/client/components/workspace/model-dropdown/Section.test.tsx +13 -0
  51. package/src/client/components/workspace/model-dropdown/Section.tsx +5 -1
  52. package/src/client/components/workspace/panels/builtin.tsx +7 -0
  53. package/src/client/components/workspace/wiki-panel/NavModal.test.tsx +136 -0
  54. package/src/client/components/workspace/wiki-panel/NavModal.tsx +94 -0
  55. package/src/client/components/workspace/wiki-panel/PageView.tsx +16 -10
  56. package/src/client/components/workspace/wiki-panel/index.tsx +44 -9
  57. package/src/client/hooks/chat/timeline/index.ts +3 -6
  58. package/src/client/hooks/chat/timeline/jump-landing.ts +121 -0
  59. package/src/client/hooks/chat/timeline/jump-rail.ts +19 -10
  60. package/src/client/hooks/chat/timeline/row-window.ts +44 -4
  61. package/src/client/hooks/chat/timeline/scroll-probe.test-util.ts +23 -10
  62. package/src/client/hooks/chat/timeline/scroll.test.ts +61 -4
  63. package/src/client/hooks/chat/timeline/scroll.ts +77 -26
  64. package/src/client/hooks/workspace/missing-files.test.ts +20 -3
  65. package/src/client/hooks/workspace/missing-files.ts +41 -7
  66. package/src/client/tailwind.css +12 -1
  67. package/src/server/lib/db/schema.ts +11 -0
  68. package/src/server/lib/lifecycle/memory.test.ts +41 -1
  69. package/src/server/lib/lifecycle/memory.ts +131 -14
  70. package/src/server/lib/omp/session/subagent-presence-scan.test.ts +137 -0
  71. package/src/server/lib/omp/session/subagent-presence-scan.ts +120 -0
  72. package/src/server/lib/omp/session/subagent-presence-store.test.ts +120 -0
  73. package/src/server/lib/omp/session/subagent-presence-store.ts +65 -0
  74. package/src/server/lib/omp/session/subagent-presence.ts +52 -15
  75. package/src/server/routes/fs/exists.test.ts +26 -1
  76. package/dist/client/static/js/index-bnrrw242.css +0 -1
@@ -18,12 +18,6 @@
18
18
  * | 20 concurrent `GET /api/chat/:id` | 1.69 GB |
19
19
  * | 10 s idle afterwards | 1.13 GB |
20
20
  *
21
- * The same work with an explicit `Bun.gc(true)` in the middle measured
22
- * 319 MB → 69 MB in a standalone probe, so the memory is garbage the collector
23
- * had simply not been asked to reclaim — a young-generation collection returns
24
- * the JS objects but leaves the arena, and nothing in this process allocates
25
- * enough to force a full one.
26
- *
27
21
  * Two rules keep the sweep honest:
28
22
  *
29
23
  * 1. **It is a CEILING, not a schedule.** A full collection is stop-the-world,
@@ -32,11 +26,39 @@
32
26
  * 2. **It is observable.** `snapshot()` is what `/api/health` reports, so the
33
27
  * condition the sweep reacts to is visible from `kabmo status` rather than
34
28
  * only from Activity Monitor.
29
+ *
30
+ * ## Which number is "memory"
31
+ *
32
+ * RSS is NOT it. On macOS a Bun process that has read and dropped a large
33
+ * transcript keeps the freed pages resident: measured on a live server, RSS
34
+ * 752 MB while the operating system charged the process a 70.6 MB physical
35
+ * footprint (`vmmap -summary`), with a 24 MB JS heap — and `Bun.gc(true)`
36
+ * changed nothing (`swept 1049 MB → 1050 MB`, every minute, for hours). The
37
+ * same process's RSS fell to 134 MB on its own once the OS reclaimed the
38
+ * clean pages.
39
+ *
40
+ * So the ceiling is applied to the OS's PHYSICAL FOOTPRINT where the host can
41
+ * answer, and `rssMB` is reported beside it as a diagnostic because that is
42
+ * the number `ps`-style tools show. `footprint -p <pid>` prints it on macOS
43
+ * (78 ms, and its headline matched `vmmap`'s "Physical footprint" exactly —
44
+ * 122 MB against 121.6 MB); Linux answers from `/proc/self/smaps_rollup`
45
+ * (`Pss`, which discounts shared pages) with `VmRSS` as the fallback; Windows
46
+ * uses the runtime's own number, which is accurate there.
47
+ *
48
+ * A reading is cached for `FOOTPRINT_TTL_MS`: the probe costs a spawn, and
49
+ * `/api/health` is polled far more often than the number can move. The sweep
50
+ * always refreshes both sides, because it is reporting the effect of a
51
+ * collection it just ran.
35
52
  */
36
53
 
54
+ import { readFileSync } from 'node:fs';
55
+
37
56
  /** Bytes in a megabyte, for the MB-shaped numbers this module reports. */
38
57
  const BYTES_PER_MB = 1024 * 1024;
39
58
 
59
+ /** How long an operating-system footprint reading is reused. */
60
+ const FOOTPRINT_TTL_MS = 30_000;
61
+
40
62
  /**
41
63
  * The process's resident set, in MB, from the OPERATING SYSTEM.
42
64
  *
@@ -69,6 +91,79 @@ function residentMB(): number {
69
91
  return Math.round(process.memoryUsage().rss / BYTES_PER_MB);
70
92
  }
71
93
 
94
+ /**
95
+ * The footprint line from `footprint -p <pid>`:
96
+ * `bun [123]: 64-bit Footprint: 122 MB (16384 bytes per page)`.
97
+ *
98
+ * Exported as a pure parser so the shape is pinned without spawning anything.
99
+ */
100
+ export function footprintMBFromOutput(output: string): number | null {
101
+ const match = /Footprint:\s+([\d.]+)\s+(B|KB|MB|GB)\b/i.exec(output);
102
+ if (!match) return null;
103
+ const value = Number(match[1]);
104
+ if (!Number.isFinite(value)) return null;
105
+ const unit = match[2].toUpperCase();
106
+ const mb = unit === 'GB' ? value * 1024
107
+ : unit === 'KB' ? value / 1024
108
+ : unit === 'B' ? value / BYTES_PER_MB
109
+ : value;
110
+ return Math.round(mb);
111
+ }
112
+
113
+ /** `Pss:` from `/proc/self/smaps_rollup` — the Linux analogue of footprint. */
114
+ export function footprintMBFromSmapsRollup(text: string): number | null {
115
+ const match = /^Pss:\s+(\d+)\s+kB$/m.exec(text);
116
+ if (!match) return null;
117
+ return Math.round(Number(match[1]) / 1024);
118
+ }
119
+
120
+ /** The OS's own charge for this process, in MB, or null where it cannot answer. */
121
+ function readFootprintMB(): number | null {
122
+ if (process.platform === 'win32') {
123
+ return Math.round(process.memoryUsage().rss / BYTES_PER_MB);
124
+ }
125
+ if (process.platform === 'linux') {
126
+ try {
127
+ const pss = footprintMBFromSmapsRollup(readFileSync('/proc/self/smaps_rollup', 'utf8'));
128
+ if (pss !== null) return pss;
129
+ } catch {
130
+ // smaps_rollup is unreadable on a hardened kernel; VmRSS below.
131
+ }
132
+ try {
133
+ const match = /^VmRSS:\s+(\d+)\s+kB$/m.exec(readFileSync('/proc/self/status', 'utf8'));
134
+ if (match) return Math.round(Number(match[1]) / 1024);
135
+ } catch {
136
+ return null;
137
+ }
138
+ return null;
139
+ }
140
+ try {
141
+ const out = Bun.spawnSync(['footprint', '-p', String(process.pid)]);
142
+ return footprintMBFromOutput(out.stdout.toString());
143
+ } catch {
144
+ // No `footprint` on this host (an older macOS, another POSIX): the sweep
145
+ // falls back to RSS.
146
+ return null;
147
+ }
148
+ }
149
+
150
+ interface FootprintCache {
151
+ at: number;
152
+ mb: number | null;
153
+ }
154
+
155
+ let footprintCache: FootprintCache | null = null;
156
+
157
+ /** The cached OS charge, refreshed when `refresh` or when the reading is stale. */
158
+ function footprintMB(refresh: boolean): number | null {
159
+ if (!refresh && footprintCache && Date.now() - footprintCache.at < FOOTPRINT_TTL_MS) {
160
+ return footprintCache.mb;
161
+ }
162
+ const mb = readFootprintMB();
163
+ footprintCache = { at: Date.now(), mb };
164
+ return mb;
165
+ }
166
+
72
167
  /** Default ceiling: above this, a sweep is worth a pause. */
73
168
  const DEFAULT_CEILING_MB = 1024;
74
169
 
@@ -77,8 +172,13 @@ const DEFAULT_CEILING_MB = 1024;
77
172
  const DEFAULT_INTERVAL_MS = 60_000;
78
173
 
79
174
  export interface MemorySnapshot {
80
- /** Resident set size in MB — what a process monitor shows. */
175
+ /** Resident set size in MB — what a `ps`-style monitor shows. On macOS it
176
+ * counts freed pages Bun has not returned, so it can exceed the footprint
177
+ * many times over. Reported for diagnosis; never the sweep's input. */
81
178
  rssMB: number;
179
+ /** What the operating system actually charges this process, in MB. Null when
180
+ * the host cannot answer. This is the number the sweep reacts to. */
181
+ footprintMB: number | null;
82
182
  /** Live JS objects in MB. */
83
183
  heapUsedMB: number;
84
184
  /** Reserved JS heap in MB (what the collector has not returned). */
@@ -97,16 +197,26 @@ export interface MemoryMaintenance {
97
197
  stop: () => void;
98
198
  }
99
199
 
100
- /** The process's memory, in MB. Reads `process.memoryUsage()`, never throws. */
101
- export function snapshot(): MemorySnapshot {
200
+ function takeSnapshot(refreshFootprint: boolean): MemorySnapshot {
102
201
  const usage = process.memoryUsage();
103
202
  return {
104
203
  rssMB: residentMB(),
204
+ footprintMB: footprintMB(refreshFootprint),
105
205
  heapUsedMB: Math.round(usage.heapUsed / BYTES_PER_MB),
106
206
  heapTotalMB: Math.round(usage.heapTotal / BYTES_PER_MB),
107
207
  };
108
208
  }
109
209
 
210
+ /** The process's memory, in MB. Cached footprint, never throws. */
211
+ export function snapshot(): MemorySnapshot {
212
+ return takeSnapshot(false);
213
+ }
214
+
215
+ /** The pressure the ceiling is applied to: the OS's charge when it is known. */
216
+ function pressureMB(snap: MemorySnapshot): number {
217
+ return snap.footprintMB ?? snap.rssMB;
218
+ }
219
+
110
220
  /** The ceiling in bytes, from `KABMO_MEMORY_CEILING_MB` when set. */
111
221
  function ceilingBytes(): number {
112
222
  const raw = Number(Bun.env.KABMO_MEMORY_CEILING_MB);
@@ -121,14 +231,16 @@ function ceilingBytes(): number {
121
231
  * arena is holding it — the maintenance interval never passes it.
122
232
  */
123
233
  export function maintainMemory(force = false): SweepResult {
124
- const before = snapshot();
125
- if (!force && before.rssMB * BYTES_PER_MB < ceilingBytes()) {
234
+ // Both sides refresh the OS reading: this function exists to report what a
235
+ // collection did, and a cached number would report the state before it.
236
+ const before = takeSnapshot(true);
237
+ if (!force && pressureMB(before) * BYTES_PER_MB < ceilingBytes()) {
126
238
  return { swept: false, before, after: before };
127
239
  }
128
240
  // A full collection: the point is to release the arena, and the young
129
241
  // generation alone is what failed to do that.
130
242
  Bun.gc(true);
131
- return { swept: true, before, after: snapshot() };
243
+ return { swept: true, before, after: takeSnapshot(true) };
132
244
  }
133
245
 
134
246
  /** Where the interval lives, so a `bun --hot` reload does not install a second. */
@@ -159,7 +271,12 @@ export function installMemoryMaintenance(): MemoryMaintenance {
159
271
  try {
160
272
  const result = maintainMemory();
161
273
  if (result.swept) {
162
- console.log(`[kabmo] memory: swept ${result.before.rssMB} MB → ${result.after.rssMB} MB`);
274
+ // Footprint first: it is the number the decision used, and the one a
275
+ // reader should trust. RSS rides along because a monitor shows it.
276
+ console.log(
277
+ `[kabmo] memory: swept ${pressureMB(result.before)} MB → ${pressureMB(result.after)} MB`
278
+ + ` (rss ${result.after.rssMB} MB)`,
279
+ );
163
280
  }
164
281
  } catch (error) {
165
282
  // A sweep is maintenance, never a reason to take the server down.
@@ -170,4 +287,4 @@ export function installMemoryMaintenance(): MemoryMaintenance {
170
287
  timer.unref?.();
171
288
  host.__kabmoMemorySweep = timer;
172
289
  return { stop: stopMemoryMaintenance };
173
- }
290
+ }
@@ -0,0 +1,137 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+
6
+ /**
7
+ * The streaming presence scan: one bit, without materializing the transcript.
8
+ *
9
+ * Why it exists is in the module doc; what this file pins is the agreement
10
+ * with the roster fold (`subagent/history/fold.ts`), because a badge that
11
+ * disagrees with the panel it opens is worse than a slow badge:
12
+ *
13
+ * - a valid subagent id in `details.progress` or `details.results` is a hit;
14
+ * - an id the fold would reject (`../evil`, a dotted path fragment) is not;
15
+ * - a `task` toolResult that arrives AFTER a chunk boundary is still found —
16
+ * the scan streams, so the matching line is assembled across reads;
17
+ * - a plain tool result, an assistant toolCall without a result, and a
18
+ * lifecycle entry are not hits.
19
+ */
20
+
21
+ import { afterAll, describe, expect, test } from 'bun:test';
22
+ import fs from 'fs';
23
+ import { dirname, join } from 'path';
24
+ import { tmpdir } from 'node:os';
25
+
26
+ import { SESSION_PRESENCE_MAX_LINE_BYTES, sessionFileHasSubagents } from '@/server/lib/omp/session/subagent-presence-scan';
27
+
28
+ const tempDirs: string[] = [];
29
+
30
+ function tempDir(): string {
31
+ const dir = fs.mkdtempSync(join(tmpdir(), 'presence-scan-'));
32
+ tempDirs.push(dir);
33
+ return dir;
34
+ }
35
+
36
+ function writeLines(name: string, lines: unknown[]): string {
37
+ const file = join(tempDir(), name);
38
+ fs.mkdirSync(dirname(file), { recursive: true });
39
+ fs.writeFileSync(file, `${lines.map((line) => JSON.stringify(line)).join('\n')}\n`);
40
+ return file;
41
+ }
42
+
43
+ function header(id = 'session'): Record<string, unknown> {
44
+ return { type: 'session', version: 3, id, cwd: '/tmp/proj', timestamp: '2026-09-01T00:00:00.000Z' };
45
+ }
46
+
47
+ /** The exact shape the roster fold reads: a `task` toolResult with details. */
48
+ function taskResult(details: Record<string, unknown>): Record<string, unknown> {
49
+ return {
50
+ type: 'message',
51
+ timestamp: '2026-09-01T00:00:10.000Z',
52
+ message: { role: 'toolResult', toolName: 'task', toolCallId: 'call-1', details },
53
+ };
54
+ }
55
+
56
+ afterAll(() => {
57
+ for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
58
+ });
59
+
60
+ describe('sessionFileHasSubagents', () => {
61
+ test('a session with no task result is not a hit', async () => {
62
+ const file = writeLines('plain.jsonl', [
63
+ header(),
64
+ { type: 'message', timestamp: '2026-09-01T00:00:05.000Z', message: { role: 'user', content: 'hi' } },
65
+ {
66
+ type: 'message',
67
+ timestamp: '2026-09-01T00:00:06.000Z',
68
+ message: { role: 'toolResult', toolName: 'bash', details: { output: 'ok' } },
69
+ },
70
+ ]);
71
+ expect(await sessionFileHasSubagents(file)).toBe(false);
72
+ });
73
+
74
+ test('an assistant task toolCall without a result is not a hit', async () => {
75
+ // Presence comes from the RESULT fold, not from a call that never landed:
76
+ // an aborted launch has no roster entry to show.
77
+ const file = writeLines('call-only.jsonl', [
78
+ header(),
79
+ {
80
+ type: 'message',
81
+ timestamp: '2026-09-01T00:00:07.000Z',
82
+ message: {
83
+ role: 'assistant',
84
+ content: [{ type: 'toolCall', id: 'call-1', name: 'task', arguments: { task: 'x' } }],
85
+ },
86
+ },
87
+ ]);
88
+ expect(await sessionFileHasSubagents(file)).toBe(false);
89
+ });
90
+
91
+ test('progress naming a subagent is a hit', async () => {
92
+ const file = writeLines('progress.jsonl', [
93
+ header(),
94
+ taskResult({ progress: [{ id: 'AlphaBeta', agent: 'task', status: 'running' }] }),
95
+ ]);
96
+ expect(await sessionFileHasSubagents(file)).toBe(true);
97
+ });
98
+
99
+ test('results carrying a subagent id is a hit', async () => {
100
+ const file = writeLines('results.jsonl', [header(), taskResult({ results: [{ id: 'GammaDelta', exitCode: 0 }] })]);
101
+ expect(await sessionFileHasSubagents(file)).toBe(true);
102
+ });
103
+
104
+ test('an id the roster fold would reject is not a hit', async () => {
105
+ const file = writeLines('traversal.jsonl', [header(), taskResult({ results: [{ id: '../evil' }] })]);
106
+ expect(await sessionFileHasSubagents(file)).toBe(false);
107
+ });
108
+
109
+ test('a hit on the last line is found across chunk boundaries', async () => {
110
+ // The scan streams, so the matching line is assembled from more than one
111
+ // read. One oversized line before it proves the carry buffer survives.
112
+ const big = 'x'.repeat(512 * 1024);
113
+ const file = writeLines('streamed.jsonl', [
114
+ header(),
115
+ { type: 'message', timestamp: '2026-09-01T00:00:08.000Z', message: { role: 'toolResult', toolName: 'bash', details: { output: big } } },
116
+ taskResult({ progress: [{ id: 'OmegaSigma', agent: 'task', status: 'running' }] }),
117
+ ]);
118
+ expect(await sessionFileHasSubagents(file)).toBe(true);
119
+ });
120
+
121
+ test('an unreadable file throws, so the caller can decide whether to remember', async () => {
122
+ const missing = join(tempDir(), 'gone.jsonl');
123
+ let threw = false;
124
+ try {
125
+ await sessionFileHasSubagents(missing);
126
+ } catch {
127
+ threw = true;
128
+ }
129
+ expect(threw).toBe(true);
130
+ });
131
+
132
+ test('the oversized-line ceiling is far above a real task result', () => {
133
+ // A task result carries telemetry, not outputs; the cap exists to drop a
134
+ // tool output that would otherwise be held in full.
135
+ expect(SESSION_PRESENCE_MAX_LINE_BYTES).toBeGreaterThan(1024 * 1024);
136
+ });
137
+ });
@@ -0,0 +1,120 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+
6
+ /**
7
+ * Does a session file hold any subagent, decided WITHOUT materializing it.
8
+ *
9
+ * `extractSubagentHistory` answers the same question and is the roster source,
10
+ * but it reads the whole transcript and lenient-parses every entry — for the
11
+ * sidebar's presence badge that was measured at 1.38 GB of reads and a 900 MB
12
+ * resident-set jump on a 1349-file / 2.0 GB agent directory, because Bun keeps
13
+ * the freed arena. The badge needs one bit, so this walks the file as a stream
14
+ * and stops at the first entry that would put something in the roster.
15
+ *
16
+ * The predicate is deliberately the SAME one the roster fold applies
17
+ * (`createFolder` in `subagent/history/fold.ts`), or the badge would disagree
18
+ * with the panel it opens:
19
+ *
20
+ * - a `task` toolResult entry whose `details.progress` names a subagent id
21
+ * (`parseSubagentProgress` → `id`), or
22
+ * - a `task` toolResult entry whose `details.results` carries an id.
23
+ *
24
+ * Both are then filtered by `SUBAGENT_ID_RE` on upsert, so an id the fold would
25
+ * reject is rejected here too.
26
+ *
27
+ * Memory stays bounded: one chunk plus the line being assembled, and an
28
+ * oversized line (a tool result carrying a file read) is dropped rather than
29
+ * held. A `task` result is small — its details are telemetry, outputs are
30
+ * deliberately not copied — so the only lines this rule can lose are ones that
31
+ * could not have matched.
32
+ */
33
+
34
+ import { isRecord } from '@/shared/lib/util/guards';
35
+ import { parseSubagentProgress } from '@/shared/lib/omp/subagent/parse';
36
+ import { SUBAGENT_ID_RE } from '@/server/lib/omp/subagent/history/paths';
37
+
38
+ /** A line longer than this is not a `task` result; it is dropped unparsed. */
39
+ export const SESSION_PRESENCE_MAX_LINE_BYTES = 8 * 1024 * 1024;
40
+
41
+ /**
42
+ * A cheap reject before the parse: every entry that could match contains both
43
+ * a `task` tool name and a `toolResult` role. Skipping the other ~99% of lines
44
+ * with two `includes` calls is what keeps a 2 GB cold scan in seconds.
45
+ */
46
+ function couldBeTaskResult(line: string): boolean {
47
+ return line.includes('"task"') && line.includes('toolResult');
48
+ }
49
+
50
+ /** The roster fold's own admission test, applied to one parsed entry. */
51
+ function admitsSubagent(entry: unknown): boolean {
52
+ if (!isRecord(entry) || entry.type !== 'message') return false;
53
+ const message = entry.message;
54
+ if (!isRecord(message) || message.role !== 'toolResult' || message.toolName !== 'task') return false;
55
+ const details = isRecord(message.details) ? message.details : {};
56
+ const progress = Array.isArray(details.progress) ? details.progress : [];
57
+ for (const raw of progress) {
58
+ const id = parseSubagentProgress(raw)?.id;
59
+ if (id !== undefined && SUBAGENT_ID_RE.test(id)) return true;
60
+ }
61
+ const results = Array.isArray(details.results) ? details.results : [];
62
+ for (const raw of results) {
63
+ if (!isRecord(raw)) continue;
64
+ const id = raw.id;
65
+ if (typeof id === 'string' && SUBAGENT_ID_RE.test(id)) return true;
66
+ }
67
+ return false;
68
+ }
69
+
70
+ /** One line of the file, parsed and admitted, with a torn line answering `false`. */
71
+ function lineAdmitsSubagent(line: string): boolean {
72
+ if (!couldBeTaskResult(line)) return false;
73
+ let parsed: unknown;
74
+ try {
75
+ parsed = JSON.parse(line);
76
+ } catch {
77
+ // A torn line is not a roster entry; the fold would skip it too.
78
+ return false;
79
+ }
80
+ return admitsSubagent(parsed);
81
+ }
82
+
83
+ /**
84
+ * True when the session file holds at least one subagent entry.
85
+ *
86
+ * A read failure THROWS rather than answering `false`: presence is a badge,
87
+ * and the caller decides whether an unreadable transcript should be reported
88
+ * as absent (it is, for this call) or remembered (it must not be).
89
+ */
90
+ export async function sessionFileHasSubagents(filePath: string): Promise<boolean> {
91
+ const decoder = new TextDecoder();
92
+ // A reader rather than `for await`: Bun's stream is async-iterable at
93
+ // runtime, but the TypeScript DOM definition of `ReadableStream` is not.
94
+ const reader = Bun.file(filePath).stream().getReader();
95
+ let pending = '';
96
+ try {
97
+ for (;;) {
98
+ const { done, value } = await reader.read();
99
+ if (done) break;
100
+ pending += decoder.decode(value, { stream: true });
101
+ let newline = pending.indexOf('\n');
102
+ while (newline !== -1) {
103
+ const line = pending.slice(0, newline);
104
+ pending = pending.slice(newline + 1);
105
+ if (line.length <= SESSION_PRESENCE_MAX_LINE_BYTES && lineAdmitsSubagent(line)) return true;
106
+ newline = pending.indexOf('\n');
107
+ }
108
+ if (pending.length > SESSION_PRESENCE_MAX_LINE_BYTES) {
109
+ // An oversized line: drop what we hold and let the rest of it arrive as
110
+ // a fragment the next newline discards. See the module note.
111
+ pending = '';
112
+ }
113
+ }
114
+ } finally {
115
+ // A hit returns early; the rest of the transcript is not needed.
116
+ reader.cancel().catch(() => {});
117
+ }
118
+ pending += decoder.decode();
119
+ return lineAdmitsSubagent(pending.trim());
120
+ }
@@ -0,0 +1,120 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+
6
+ /**
7
+ * The saved presence verdict — the half of the probe that survives a restart.
8
+ *
9
+ * In-process caching already answered "cheap after the first call"; what this
10
+ * pins is the case the old module could not: a NEW process, whose sidebar load
11
+ * used to stream every transcript again (measured 1.38 GB of reads on a
12
+ * 1349-file agent directory). The verdict is only reusable for the exact file
13
+ * version that produced it, so both halves of the key are exercised:
14
+ *
15
+ * - same version, different file content → the saved answer stands (this is
16
+ * what a restart looks like);
17
+ * - new version → the transcript is read again, and the saved answer is
18
+ * replaced.
19
+ *
20
+ * The probe must also stay usable with NO database open: it runs in unit
21
+ * suites and in any caller that has not opened the store yet, and it must
22
+ * never create one.
23
+ */
24
+
25
+ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
26
+ import fs from 'fs';
27
+ import { dirname, join } from 'path';
28
+ import { tmpdir } from 'node:os';
29
+
30
+ import { closeDb, getDb } from '@/server/db.server';
31
+ import { isolateDb, releaseDb } from '@/test-support/isolated-db';
32
+ import { clearSubagentPresenceCache, sessionHasSubagents } from '@/server/lib/omp/session/subagent-presence';
33
+ import { readPresenceVerdict } from '@/server/lib/omp/session/subagent-presence-store';
34
+
35
+ const tempDirs: string[] = [];
36
+
37
+ function tempDir(): string {
38
+ const dir = fs.mkdtempSync(join(tmpdir(), 'presence-store-'));
39
+ tempDirs.push(dir);
40
+ return dir;
41
+ }
42
+
43
+ function writeSession(name: string, lines: unknown[]): string {
44
+ const file = join(tempDir(), name);
45
+ fs.mkdirSync(dirname(file), { recursive: true });
46
+ fs.writeFileSync(file, `${lines.map((line) => JSON.stringify(line)).join('\n')}\n`);
47
+ return file;
48
+ }
49
+
50
+ function header(): Record<string, unknown> {
51
+ return { type: 'session', version: 3, id: 's1', cwd: '/tmp/proj', timestamp: '2026-09-01T00:00:00.000Z' };
52
+ }
53
+
54
+ function withSubagent(): Record<string, unknown> {
55
+ return {
56
+ type: 'message',
57
+ timestamp: '2026-09-01T00:00:10.000Z',
58
+ message: { role: 'toolResult', toolName: 'task', details: { progress: [{ id: 'AlphaBeta', agent: 'task', status: 'running' }] } },
59
+ };
60
+ }
61
+
62
+ beforeEach(async () => {
63
+ await isolateDb();
64
+ // Opening is what creates the schema (and drops this suite's in-process map).
65
+ await getDb();
66
+ clearSubagentPresenceCache();
67
+ });
68
+
69
+ afterEach(async () => {
70
+ clearSubagentPresenceCache();
71
+ await releaseDb();
72
+ for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
73
+ tempDirs.length = 0;
74
+ });
75
+
76
+ describe('saved presence verdict', () => {
77
+ test('answers from the database for the same version, even when the file changed', async () => {
78
+ const file = writeSession('same-version.jsonl', [header(), withSubagent()]);
79
+ expect(await sessionHasSubagents(file, 'entry-1')).toBe(true);
80
+
81
+ // What a restart does: the in-process map is gone...
82
+ clearSubagentPresenceCache();
83
+ // ...and the file no longer holds the entry the verdict came from. Only a
84
+ // saved verdict can still answer `true` here.
85
+ fs.writeFileSync(file, `${JSON.stringify(header())}\n`);
86
+ expect(await sessionHasSubagents(file, 'entry-1')).toBe(true);
87
+ });
88
+
89
+ test('a new version re-reads the file and replaces the saved verdict', async () => {
90
+ const file = writeSession('new-version.jsonl', [header(), withSubagent()]);
91
+ expect(await sessionHasSubagents(file, 'entry-1')).toBe(true);
92
+ // The transcript loses the entry AND the version moves: only a re-read can
93
+ // answer `false`, and it must replace what the store held.
94
+ fs.writeFileSync(file, `${JSON.stringify(header())}\n`);
95
+ clearSubagentPresenceCache();
96
+ expect(await sessionHasSubagents(file, 'entry-2')).toBe(false);
97
+ // The new verdict is what a restart sees for that version.
98
+ clearSubagentPresenceCache();
99
+ fs.writeFileSync(file, `${JSON.stringify(header())}\n${JSON.stringify(withSubagent())}\n`);
100
+ expect(await sessionHasSubagents(file, 'entry-2')).toBe(false);
101
+ });
102
+
103
+ test('the false case is saved too — a restart must not re-scan a plain session', async () => {
104
+ const file = writeSession('plain.jsonl', [header()]);
105
+ expect(await sessionHasSubagents(file, 'entry-1')).toBe(false);
106
+ // Same version, now holding an entry: a saved `false` answers without
107
+ // reading the file again (this is the cheap path a restart needs).
108
+ clearSubagentPresenceCache();
109
+ fs.writeFileSync(file, `${JSON.stringify(header())}\n${JSON.stringify(withSubagent())}\n`);
110
+ expect(await sessionHasSubagents(file, 'entry-1')).toBe(false);
111
+ });
112
+
113
+ test('a probe with no database open still answers, and saves nothing', async () => {
114
+ const file = writeSession('no-db.jsonl', [header(), withSubagent()]);
115
+ await closeDb();
116
+ expect(await sessionHasSubagents(file, 'entry-1')).toBe(true);
117
+ // Asking the store again is a miss, not an error: no handle means no cache.
118
+ expect(await readPresenceVerdict(file, 'entry-1:0')).toBeNull();
119
+ });
120
+ });
@@ -0,0 +1,65 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+
6
+ /**
7
+ * The subagent-presence verdict, saved so a restart does not re-derive it.
8
+ *
9
+ * Presence is a fact about a FILE VERSION, not about a live process: the
10
+ * verdict only changes when the session gains entries or its sibling artifacts
11
+ * directory changes, and both are already encoded in the key. Deriving it
12
+ * means streaming the whole parent transcript, measured at 1.38 GB of reads on
13
+ * a 1349-file agent directory — the reason a freshly restarted server held
14
+ * ~900 MB of resident-set in freed arena after the console's sidebar load.
15
+ * An in-process map cannot survive the restart that pays that cost, so the one
16
+ * verdict the next boot would otherwise recompute lives in the database it
17
+ * already opens for the same request (AGENTS.md §6: anything that must survive
18
+ * a reload is server-side state).
19
+ *
20
+ * Two rules keep this safe for callers that are not the sidebar:
21
+ *
22
+ * 1. **It never opens a database.** `getDbSync()` answers the handle already
23
+ * open, and a probe that runs before `getDb()` (or in a test that has no
24
+ * database) simply misses the cache. Opening one here would make a badge
25
+ * read create a file and would leak the developer's real store into a test.
26
+ * 2. **A failure is a miss.** A read or write that throws costs one rescan; it
27
+ * must never fail the sidebar.
28
+ *
29
+ * Rows for sessions deleted long ago are not pruned: they are a hundred bytes
30
+ * each, they are never read (no file list entry names them), and a delete pass
31
+ * would be a write on the hot path of every boot.
32
+ */
33
+
34
+ import { getDbSync } from '@/server/db.server';
35
+
36
+ /** The saved verdict for this exact file version, or null when unknown. */
37
+ export async function readPresenceVerdict(sessionPath: string, version: string): Promise<boolean | null> {
38
+ try {
39
+ const row = await getDbSync().get<{ has_subagents: number }>(
40
+ 'SELECT has_subagents FROM session_subagent_presence WHERE session_path = ? AND version = ?',
41
+ [sessionPath, version],
42
+ );
43
+ if (!row) return null;
44
+ return row.has_subagents === 1;
45
+ } catch {
46
+ return null;
47
+ }
48
+ }
49
+
50
+ /** Replace the saved verdict for a session. Best-effort by contract. */
51
+ export async function writePresenceVerdict(sessionPath: string, version: string, hasSubagents: boolean): Promise<void> {
52
+ try {
53
+ await getDbSync().run(
54
+ `INSERT INTO session_subagent_presence (session_path, version, has_subagents, updated_at)
55
+ VALUES (?, ?, ?, ?)
56
+ ON CONFLICT(session_path) DO UPDATE SET
57
+ version = excluded.version,
58
+ has_subagents = excluded.has_subagents,
59
+ updated_at = excluded.updated_at`,
60
+ [sessionPath, version, hasSubagents ? 1 : 0, Date.now()],
61
+ );
62
+ } catch {
63
+ // A miss here is one rescan on the next start, never a failed sidebar.
64
+ }
65
+ }