Repository navigation
Expand file tree
/
Copy pathsession.ts
More file actions
1038 lines (903 loc) · 72.3 KB
/
Copy pathsession.ts
File metadata and controls
1038 lines (903 loc) · 72.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/** In-memory session state. Ports the session-tracking concepts from `session.py`: which files were read/edited this session, which hints have already fired (so they are not repeated), and the URL/command -> cache-id indexes for web-fetch and bash-output dedup. This module owns the live state in Maps/Sets, cleared between tests via {@link registerReset}. Each Claude Code hook runs as a separate `token-goat hook` process, so these Maps would not survive between tool calls on their own. `session_store.ts` persists them across processes, mirroring the JSON `SessionCache` the Python implementation kept keyed by session ID: `relay` hydrates this state via {@link importSessionState} before a hook runs and writes it back via {@link exportSessionState} afterward. */
import { randomBytes, randomUUID } from 'node:crypto'
import * as fs from 'node:fs'
import { hostPathOfIndexKey, normalizePath } from './paths.js'
import { registerReset } from './reset.js'
import { foldPath } from './util.js'
import { fingerprintContent, fingerprintFile, shortFingerprint } from './fingerprint.js'
import { redactSecrets } from './secret_redact.js'
import { clearAllReadRangeEvasion, clearReadRangeEvasion, exportReadRangeEvasion, importReadRangeEvasion, type RangeEvasionEntries } from './read_range_evasion.js'
/** What a file looked like when a line range of it was recorded: its size and mtimeMs, and, for a file small enough to hash, the SHA-256 of its bytes. Stat alone cannot tell a same-size rewrite that kept or restored the mtime (a coarse-stamp file system inside one tick, `touch -r`, `cp -p`) from no change, so only `fp` proves the bytes the model was served are still on disk. */
export interface FileRangeIdentity {
readonly size: number
readonly mtimeMs: number
readonly fp?: string
}
/** Largest file hashed for {@link FileRangeIdentity.fp}: the hash is taken once per set of recorded ranges and again by each check, on the hook path, so it is bounded; a larger file carries stat only and its equal-stat re-read is read through, never denied. */
export const RANGE_FINGERPRINT_MAX_BYTES = 2 * 1024 * 1024
/** The SHA-256 of a file's bytes on disk right now, or null when they cannot be read. */
export type CurrentFileHash = () => string | null
/** A {@link CurrentFileHash} that can take the bytes of a read the hook call made anyway, so hashing them does not read the file a second time. */
export type OnceFileHash = CurrentFileHash & { adopt: (bytes: Buffer) => void }
/** A {@link CurrentFileHash} that reads the file once and answers every later call from that read, or from bytes the caller already read and hands over with `adopt`. Made fresh by each hook decision and passed down as a parameter, never kept between calls: a later call must hash the bytes that are on disk then, or a rewrite made in between would be judged by an old hash. */
export function onceCurrentFileHash(filePath: string): OnceFileHash {
const onDisk = hostPathOfIndexKey(normalizePath(filePath))
let read = false
let hash: string | null = null
let adopted: Buffer | undefined
const current = (() => {
if (!read) {
hash = adopted !== undefined ? fingerprintContent(adopted) : fingerprintFile(onDisk)
adopted = undefined
read = true
}
return hash
}) as OnceFileHash
// Ignored once the hash is taken: it already describes the bytes of an earlier read.
current.adopt = (bytes) => {
if (!read) adopted = bytes
}
return current
}
/** Tracks reads/edits of a single file within the session. Mirrors the load-bearing fields of `session.py::FileEntry` used by the re-read dedup hint: read count, last-read timestamp, whether the file was edited (which invalidates any cached read window), and its size at last read. */
export interface FileEntry {
/** Normalized absolute path, case-preserved -- also the literal `_files` map key for this entry's first-seen casing. See {@link resolveFilesKey} for how a later read of the same physical file under different casing (case-insensitive filesystems) still resolves to this same entry. */
readonly path: string
/** Number of times Read fired for this file this session. */
readonly readCount: number
/** Unix-ms timestamp of the most recent read. */
readonly lastReadAt: number
/** Unix-ms timestamp of the most recent whole-file (unranged) read, or undefined if every read of this file so far carried an explicit offset/limit/view-range slice. A ranged read never means the model has seen the whole file, so the whole-file "unchanged since last read" denies must check this instead of `lastReadAt`, which a slice bumps too (see `wasFileFullyReadThisSession`). */
readonly lastFullReadAt?: number
/** Number of whole-file (unranged) reads this session, as opposed to `readCount`, which also counts offset/limit/view-range slices. The count-based "you've re-read this whole file N times" denies must gate on this, not `readCount`: a file touched only via a handful of narrow slices has never actually been re-read in full and must not trip a deny meant for repeated whole-file reads. */
readonly fullReadCount?: number
/** True once Write/Edit fired on this file this session. */
readonly wasEdited: boolean
/** Unix-ms of the most recent Write/Edit, so the compact manifest can tell an edit still in context from one an earlier compaction dropped. Absent on an entry saved before this field existed, which is then treated as edited in the current epoch. */
readonly lastEditedAt?: number
/** File size in bytes captured at the last read (0 if unreadable). */
readonly sizeBytes: number
/** True when the session saw this file's content delivered incompletely: a Read result carrying a `[Truncated:` marker, or a tail-style shell dump whose shown lines cannot be placed against the file. */
readonly wasTruncated?: boolean
/** Symbol/section/range tokens this file was read *surgically* by this session (via `token-goat read|section "file::symbol"` and friends), as opposed to a whole-file Read. Non-empty means the file was engaged with narrowly, which compact.ts's `computeAdaptiveBudget` rewards with a manifest-budget bonus. Populated by {@link recordSymbolRead}; never touched by {@link recordFileRead} (whole-file Read tracking is unchanged). */
readonly symbols_read?: string[]
/** Cheap file identity (size + mtimeMs) captured by statSync at the moment the most recent line range was recorded via {@link recordFileLineRange}. Lets the repeated-range deny in hooks_read.ts tell whether disk has moved since without a snapshot or a hash: if a later statSync of the same file no longer matches, an external edit landed between the two reads and the recorded ranges must not keep denying. */
readonly rangeFileIdentity?: FileRangeIdentity
/** The lifetime `readCount`/`fullReadCount` this entry carried when its first read after the compaction stamped at `at` landed, so {@link epochReadCounts} can tell the reads still in context from the ones that compaction dropped. Set by {@link recordFileRead}; absent on an entry first read in the current epoch, whose counts are already epoch counts. */
readonly epochBase?: EpochBase
}
/** See {@link FileEntry.epochBase}. */
export interface EpochBase {
readonly at: number
readonly readCount: number
readonly fullReadCount: number
}
// path -> entry. The key is the normalized absolute path so a file referenced via different relative strings collapses to one entry.
let _files = new Map<string, FileEntry>()
// Snapshot of each file's readCount at hydration time, so session_store.ts's merge can tell "this process's own genuinely new reads since load" apart from "whatever was already on disk" -- Math.max(disk, mem) silently drops a concurrent process's distinct increment whenever the two values happen to coincide (see mergeFileEntry in session_store.ts).
let _filesAtLoad = new Map<string, number>()
let _filesFullReadCountAtLoad = new Map<string, number>()
// Hint fingerprints already emitted this session (dedup, matches session.py mark_hint_seen / has_hint_fingerprint).
let _hintsShown = new Set<string>()
// sessionId -> number of scheduled prompts observed. The prompt marker is a scheduler identifier in some hosts, so it cannot reliably represent the number of deliveries.
let _scheduledPromptCounts = new Map<string, number>()
// url -> cacheId index for web-fetch dedup.
let _webFetches = new Map<string, string>()
// commandHash -> outputId index for bash-output dedup.
let _bashOutputs = new Map<string, string>()
// `${pattern}::${path}::${outputMode}::${glob}` signature -> match count, for Grep dedup-hint recall (an identical Grep repeated later in the session, above hints.grep_dedup_min_matches).
let _grepQueries = new Map<string, number>()
// `[pattern, path]` signature -> match count, for Glob dedup-hint recall (an identical Glob repeated later in the session, above hints.glob_dedup_min_matches). Mirrors _grepQueries.
let _globQueries = new Map<string, number>()
// Last-seen "Tab Context:" block text from a browser-automation MCP tool result this session, for hooks_browser_image.ts's dedup: an identical repeat gets shortened to a placeholder instead of resending the full open-tab list.
let _lastTabContext: string | null = null // fingerprint of the block, never the block; see setLastTabContext
let _seenImageHashes: string[] = []
// Test, lint, typecheck and build commands run this session, newest last, one entry per distinct command; see recordVerificationRun.
let _verificationRuns: VerificationRun[] = []
/** A currently-outstanding Agent-tool (subagent) spawn tracked for hooks_agent_spawn.ts's duplicate-brief detection: the original prompt text (before any briefing/advisory the pre-hook appends) and when it was recorded. */
export interface OutstandingAgentSpawn {
readonly prompt: string
readonly ts: number
}
// Prompts of Agent-tool spawns fired this session whose matching post_tool_use has not yet arrived. Populated by recordOutstandingAgentSpawn (pre_tool_use), cleared by removeOutstandingAgentSpawn (post_tool_use) once the corresponding spawn completes.
let _outstandingAgentSpawns: OutstandingAgentSpawn[] = []
// Snapshot of _outstandingAgentSpawns at hydration time, so session_store.ts's merge can tell "this process explicitly removed an entry that was here at load" apart from "this process never saw it" -- a plain disk-union merge (like the other pair-list fields use) would silently resurrect a removed entry from the pre-update disk snapshot, since removal, unlike every other field here, is not a monotonic set-union operation. Mirrors pendingLargeFileHintsAtLoad's role for the exact same class of problem.
let _outstandingAgentSpawnsAtLoad: OutstandingAgentSpawn[] = []
// Command hashes (same key space as _bashOutputs, i.e. the directory-scoped key hooks_bash_commands.ts::bashRecallKey builds for recordBashOutput/getBashOutputId) for which a store call overwrote an already-present entry this session -- i.e. an older cached run under this exact key was beaten by a newer one. Used only by hooks_compact.ts's SAFE_TO_DISCARD manifest section to identify raw transcript copies that are provably superseded by the surviving cached id.
let _bashReruns = new Set<string>()
// url -> saved file path for curl -o download dedup (Item 2).
let _curlDownloads = new Map<string, string>()
// Snapshot of `_curlDownloads` at hydration time, so `consumedCurlDownloadKeys` can tell "this process explicitly cleared it" apart from "this process never saw it" -- mirrors `_pendingLargeFileHintsAtLoad`/`_outstandingAgentSpawnsAtLoad`'s role for the same removal-is-not-a-union-op reason: clearCurlDownload's deletion must actually stick, so session_store.ts's merge needs this to avoid resurrecting a cleared entry from a stale disk read.
let _curlDownloadsAtLoad = new Map<string, string>()
// path (as written on the sed command line) -> served inclusive line ranges this session, for overlap detection across repeated `sed -n 'N,Mp'` reads.
let _fileLineRanges = new Map<string, Array<[number, number]>>()
// path -> bash-output cache ids whose body this session was actually shown for that file, oldest first. Distinct from `_fileLineRanges`, which stores only line numbers: numbers cannot prove a later read's bytes were already served, because a change token-goat never observed (an external editor, a pull in another terminal) leaves the recorded range in place while the lines behind it move. These ids point at the served text itself, so containment can be decided on the bytes and a stale entry simply fails to match.
let _fileServedOutputs = new Map<string, string[]>()
// Snapshots of the two maps above at hydration time, so `consumedFileLineRangeKeys`/`consumedFileServedOutputKeys` can tell "this process explicitly cleared this file's history" (recordFileEdit for the ranges, markCompacted for either) apart from "this process never touched it" -- same removal-is-not-a-union-op reason as `_curlDownloadsAtLoad`: without this, session_store.ts's plain per-file union would resurrect the cleared ranges/served ids straight off a stale disk read.
let _fileLineRangesAtLoad = new Map<string, Array<[number, number]>>()
let _fileServedOutputsAtLoad = new Map<string, string[]>()
// Folded keys whose ranges this process dropped through resetFileLineRanges. A reset followed by a fresh range for the same file in the same hook call leaves the key present, which `_fileLineRangesAtLoad` alone reads as a plain append, so session_store.ts's union put the dropped ranges straight back from disk.
let _fileLineRangesReset = new Set<string>()
// Folded path -> the file's identity (size + mtimeMs) when a range of it was last recorded, kept beside `_fileLineRanges` whether or not the file has a session entry. `FileEntry.rangeFileIdentity` is stamped only on an existing entry, and a file read only through `sed -n`/`head` has none, so nothing could tell that its ranges had outlived a change made on disk outside the session.
let _fileLineRangeIdentities = new Map<string, FileRangeIdentity>()
// Unix-ms of the most recent context compaction (0 = never compacted this session). After Claude Code compacts, the model's context no longer holds any file content it read earlier, so every read whose `lastReadAt` predates this stamp must be treated as NOT read -- see `wasFileReadThisSession`. Stored as a monotonically increasing scalar rather than resetting each entry's `readCount` to 0 because session_store.ts's `mergeFileEntry` reconciles `readCount` as "freshest disk count + this process's own increments since load", so an in-memory reset to 0 contributes a 0 delta and the disk value is handed straight back -- the reset would be silently resurrected across concurrent hook processes. A max-merged scalar has no such resurrection path.
let _compactedAt = 0
// `${sub}::${spec}` keys for `token-goat symbol|read|section` invocations already run this session (CLI-side re-read dedup).
let _cliReads = new Set<string>()
// path -> size (bytes) for a large-file hint fired but not yet resolved as followed/ignored (opt-in outcome logging, consume-on-resolve).
let _pendingLargeFileHints = new Map<string, number>()
// Snapshot of `_pendingLargeFileHints` at hydration time, so `consumedPendingLargeFileHintKeys` can tell "this process resolved it" apart from "this process never saw it" — session_store.ts's merge needs that distinction to avoid resurrecting a resolved hint from a stale disk read.
let _pendingLargeFileHintsAtLoad = new Map<string, number>()
// tool_use_id -> the cwd a Bash call's pre hook saw, which is the directory the call started in. Claude Code's main-thread PostToolUse carries the directory a `cd` left the shell in instead, so the post hook reads the start back from here: resolving the command's cd against the landed directory applies it twice.
let _bashStartCwds = new Map<string, string>()
// Snapshot of `_bashStartCwds` at hydration time, for the removal-is-not-a-union-op reason `_curlDownloadsAtLoad` gives: the post hook's take must stick against a stale disk read.
let _bashStartCwdsAtLoad = new Map<string, string>()
// The generated session id, made once per process for when `CLAUDE_CODE_SESSION_ID` is unset.
let _sessionId: string | null = null
// Set by relay.ts from the hook payload's `transcript_path`, paired with the session it arrived for. Unset (null) when the harness never sends one (e.g. a non-Claude-Code bridge), in which case getContextPressure falls back to its estimate.
let _transcriptPath: { path: string; sessionId: string } | null = null
/** Best-effort file size in bytes, or 0 when the file cannot be stat'd. Never throws: a missing/locked file simply records size 0 so the read is still tracked for dedup. */
function fileSize(absPath: string): number {
try {
return fs.statSync(hostPathOfIndexKey(absPath)).size
} catch {
return 0
}
}
/** Resolve `normalized` to the literal key already used in `_files`, falling back to a case-folded scan only when no exact match exists. `_files`'s primary key stays case-preserved (not folded) rather than folding it outright, because `getSessionFiles()` exposes the raw map and hooks_read.ts's re-read-count branch does a direct `getSessionFiles().get(normalized)` lookup with its own `normalizePath(filePath)` -- folding the stored key out from under that direct lookup would break it even for the common case of the identical path queried twice. normalizePath only lowercases the drive letter, so without this fallback, a second Read of the SAME physical file under different casing beyond the drive letter (e.g. "Worker.ts" vs "worker.ts" -- Windows/macOS filesystems are case-insensitive) would create a second, separate entry instead of being recognized as the existing one. The fallback scan is bounded by the small, capped number of files tracked per session (see session_store.ts's capFiles). */
function resolveFilesKey(normalized: string): string {
if (_files.has(normalized)) return normalized
const folded = foldPath(normalized)
if (folded === normalized) return normalized
for (const existingKey of _files.keys()) {
if (foldPath(existingKey) === folded) return existingKey
}
return normalized
}
/** The epoch snapshot for an entry created now: a file first seen after the last compaction had nothing in context before it, so its base is zero, and {@link epochReadCounts} can tell it apart from an entry a process that missed the compaction left with no base at all. */
function newEntryEpochBase(): { epochBase?: EpochBase } {
return _compactedAt > 0 ? { epochBase: { at: _compactedAt, readCount: 0, fullReadCount: 0 } } : {}
}
/** Record that `filePath` was read. First read creates an entry; subsequent reads increment `readCount` and refresh `lastReadAt` / `sizeBytes` while preserving the `wasEdited` flag. `isFullRead` (default true) marks whether this particular read carried no offset/limit/view-range slice -- callers passing an explicit slice window must pass `false` so `lastFullReadAt` (and therefore `wasFileFullyReadThisSession`) stays untouched: a ranged read still bumps `readCount`/`lastReadAt` for the count-based and range-level dedup that legitimately treats it as a read, but must never arm a whole-file "unchanged since last read" deny that assumes the model has seen content it was never sent. */
export function recordFileRead(filePath: string, isFullRead: boolean = true): void {
const normalized = normalizePath(filePath)
const key = resolveFilesKey(normalized)
const now = Date.now()
const size = fileSize(normalized)
const prev = _files.get(key)
if (prev === undefined) {
_files.set(key, {
path: key,
readCount: 1,
lastReadAt: now,
wasEdited: false,
sizeBytes: size,
...(isFullRead ? { lastFullReadAt: now, fullReadCount: 1 } : {}),
...newEntryEpochBase(),
})
return
}
// The first read since the last compaction snapshots the counts that compaction dropped from context, so the epoch's own reads can be told apart from them later.
const opensEpoch = _compactedAt > 0 && prev.lastReadAt < _compactedAt && (prev.epochBase?.at ?? 0) < _compactedAt
_files.set(key, {
...prev,
readCount: prev.readCount + 1,
lastReadAt: now,
sizeBytes: size,
...(isFullRead ? { lastFullReadAt: now, fullReadCount: (prev.fullReadCount ?? 0) + 1 } : {}),
...(opensEpoch ? { epochBase: { at: _compactedAt, readCount: prev.readCount, fullReadCount: prev.fullReadCount ?? 0 } } : {}),
})
}
/** Take back the counts {@link recordFileRead} added for a Read that was then refused without handing over the file: PostToolUse never fires for a refused call, so the model holds no more of the file than it did before. `before` is the entry as it stood before the hook ran; with none, the entry the refused read created is dropped. `lastReadAt` keeps the refused attempt, because protect_recent_reads ranks on it and the retry a refusal invites must stay protected rather than meet the same refusal. */
export function unrecordRefusedRead(filePath: string, before: FileEntry | undefined): void {
const key = resolveFilesKey(normalizePath(filePath))
const current = _files.get(key)
if (current === undefined) return
if (before === undefined) {
_files.delete(key)
return
}
// The epoch base stays as the refused read left it: either the one `before` carried, or the one that read opened from `before`'s own counts, which nets the restored counts to nothing in the epoch.
const { fullReadCount: _fullReadCount, lastFullReadAt: _lastFullReadAt, ...rest } = current
_files.set(key, {
...rest,
readCount: before.readCount,
...(before.fullReadCount !== undefined ? { fullReadCount: before.fullReadCount } : {}),
...(before.lastFullReadAt !== undefined ? { lastFullReadAt: before.lastFullReadAt } : {}),
})
}
/** Upper bound on distinct symbol tokens tracked per file, so a session that reads many symbols of one file can't grow its entry unboundedly. */
const MAX_SYMBOLS_PER_FILE = 25
/** Record that `filePath` was read *surgically* (by symbol/section/range) this session, e.g. via `token-goat read "file::symbol"`. This is deliberately separate from {@link recordFileRead}: a surgical CLI read is not a whole-file Read tool fire, so it must NOT bump `readCount` (that field means Read-tool hits). It records the narrowing token on the file's entry so the compaction manifest can reward files that were engaged with narrowly. If the file has no entry yet (surgically read but never Read-tooled), a `readCount: 0` entry is created so the read is still represented; otherwise the existing entry is annotated in place, leaving its read/edit state untouched. */
export function recordSymbolRead(filePath: string, symbol: string): void {
const normalized = normalizePath(filePath)
const key = resolveFilesKey(normalized)
const prev = _files.get(key)
if (prev === undefined) {
_files.set(key, {
path: key,
readCount: 0,
lastReadAt: Date.now(),
wasEdited: false,
sizeBytes: fileSize(normalized),
symbols_read: [symbol],
...newEntryEpochBase(),
})
return
}
const existing = prev.symbols_read ?? []
if (existing.includes(symbol)) return
const symbols_read = [...existing, symbol].slice(-MAX_SYMBOLS_PER_FILE)
_files.set(key, { ...prev, symbols_read })
}
/** Snapshot of each file's readCount exactly as it was at hydration time, before this process made any changes. session_store.ts's merge uses this to compute how many *new* reads this process actually contributed since its own load, rather than assuming the larger of the two counters reflects every read that ever happened -- two concurrent processes that both start from the same on-disk count and each record one genuine read must sum to two, not one. */
export function filesReadCountAtLoad(): ReadonlyMap<string, number> {
return _filesAtLoad
}
/** Same snapshot mechanism as {@link filesReadCountAtLoad}, but for fullReadCount: session_store.ts's merge reconciles this counter the same way, for the same reason -- a concurrent process's own genuine full read must never be dropped just because Math.max(a, b) happened to coincide with another process's count. */
export function filesFullReadCountAtLoad(): ReadonlyMap<string, number> {
return _filesFullReadCountAtLoad
}
/** Record that `filePath` was edited/written. Sets `wasEdited` true. If the file was never read this session an entry is created with `readCount` 0 so the edit is still tracked. Also drops any previously recorded sed line-range history for the file (see {@link recordFileLineRange}): an edit shifts line numbers and content, so a pre-edit range can no longer be trusted by hooks_bash.ts's overlap check. */
export function recordFileEdit(filePath: string): void {
const normalized = normalizePath(filePath)
const key = resolveFilesKey(normalized)
resetFileLineRanges(normalized)
// Deliberately NOT `_fileServedOutputs.delete(...)`: that index is matched on the served bytes, never on line position, so an edit needs no invalidation here. A line the edit rewrote stops matching on its own; a line it left alone was still served verbatim this session, and dropping the whole file's history throws that evidence away for the (usually large) untouched remainder -- measured as repeated whole re-reads of one file's opening block across an edit-read-edit loop.
const prev = _files.get(key)
const now = Date.now()
if (prev === undefined) {
_files.set(key, {
path: key,
readCount: 0,
lastReadAt: 0,
wasEdited: true,
lastEditedAt: now,
sizeBytes: fileSize(normalized),
})
return
}
_files.set(key, { ...prev, wasEdited: true, lastEditedAt: now })
}
/** Return all tracked file entries, keyed by normalized absolute path. */
export function getSessionFiles(): ReadonlyMap<string, FileEntry> {
return _files
}
/** True if `filePath` was read at least once this session (`readCount > 0`) AND that read is still in the model's context (its `lastReadAt` is at or after the last compaction epoch). A file that was only edited (never read) returns false, matching the re-read-hint semantics: there is no prior read to dedup against. This means "content is currently in the model's context", not "this session touched this file at some point" -- consumers that want the historical fact (the compact manifest's read rows, stats, hot/recent listings, edit tracking) must read `getSessionFiles()`/`readCount` directly instead of calling this, and those that want how many of its reads are still in context call {@link epochReadCounts}. */
export function wasFileReadThisSession(filePath: string): boolean {
const entry = _files.get(resolveFilesKey(normalizePath(filePath)))
return entry !== undefined && entry.readCount > 0 && entry.lastReadAt >= _compactedAt
}
/** True if `filePath` had at least one whole-file (unranged) read this session that is still in context (same compaction-epoch rule as {@link wasFileReadThisSession}). A file read only via offset/limit/view-range slices returns false here even though `wasFileReadThisSession` returns true for it -- the model has only ever seen the requested windows, never the whole file, so any deny that claims "unchanged since last read" of the *whole file* must gate on this, not on `wasFileReadThisSession`. */
export function wasFileFullyReadThisSession(filePath: string): boolean {
const entry = _files.get(resolveFilesKey(normalizePath(filePath)))
return entry !== undefined && entry.lastFullReadAt !== undefined && entry.lastFullReadAt >= _compactedAt
}
/** How many of `entry`'s reads, and of its whole-file reads, landed since the compaction stamped at `compactedAt` (default: this session's last one), i.e. are still in the model's context. Subtracts the {@link FileEntry.epochBase} taken at that epoch. An entry created after a known compaction carries a zero base for it, so one read inside the epoch with no base for it was recorded by a process that had not yet seen the compaction and could not tell how many of its counts came before: it counts as one read, which can let a re-read through but never refuses one. Whole-file reads count only while the latest one is inside the epoch. */
export function epochReadCounts(entry: FileEntry, compactedAt: number = _compactedAt): { reads: number; fullReads: number } {
if (entry.lastReadAt < compactedAt) return { reads: 0, fullReads: 0 }
const base = entry.epochBase !== undefined && entry.epochBase.at === compactedAt ? entry.epochBase : undefined
const fullInEpoch = entry.lastFullReadAt !== undefined && entry.lastFullReadAt >= compactedAt
if (base === undefined && compactedAt > 0) return { reads: Math.min(entry.readCount, 1), fullReads: fullInEpoch ? 1 : 0 }
const reads = Math.max(0, entry.readCount - (base?.readCount ?? 0))
const fullReads = fullInEpoch ? Math.max(0, (entry.fullReadCount ?? 0) - (base?.fullReadCount ?? 0)) : 0
return { reads, fullReads }
}
/** Whether `entry` was edited since the compaction stamped at `compactedAt` (default: this session's last one). An entry with no {@link FileEntry.lastEditedAt} predates that field and counts as edited in the epoch. */
export function wasEditedSinceCompaction(entry: FileEntry, compactedAt: number = _compactedAt): boolean {
return entry.wasEdited && (entry.lastEditedAt === undefined || entry.lastEditedAt >= compactedAt)
}
/** Combine two views' {@link FileEntry.epochBase}: the later epoch wins, and for the same epoch the larger snapshot, since a process only takes one while every read it has seen predates the epoch, so the larger one has seen more of the reads that compaction dropped. */
export function mergeEpochBase(a: EpochBase | undefined, b: EpochBase | undefined): EpochBase | undefined {
if (a === undefined) return b
if (b === undefined || a.at > b.at) return a
if (b.at > a.at) return b
return { at: a.at, readCount: Math.max(a.readCount, b.readCount), fullReadCount: Math.max(a.fullReadCount, b.fullReadCount) }
}
/** Unix-ms of the last context compaction this session, or 0 if none. See `_compactedAt`. */
export function getCompactedAt(): number {
return _compactedAt
}
/** Stamp a context-compaction epoch at `now`, invalidating every earlier read for context-presence purposes. Also clears the sed line-range ledger, which is the same "content is in context" assumption at sub-file granularity. Monotonic: an out-of-order or replayed stamp never moves the epoch backwards. Callers must build anything that depends on the pre-compaction read set (e.g. the compact manifest) BEFORE calling this. */
export function markCompacted(now: number = Date.now()): void {
if (now <= _compactedAt) return
_compactedAt = now
_fileLineRanges = new Map()
_fileLineRangeIdentities = new Map()
clearAllReadRangeEvasion()
// Same assumption at whole-body granularity: after compaction the served text is no longer in context, so it can no longer justify withholding a later read.
_fileServedOutputs = new Map()
// The same, for the exact-repeat CLI-read ledger: a `token-goat read` the model ran before the compaction is no longer in its context, so a repeat is not a re-run of something it still holds.
_cliReads = new Set()
}
/** Case-fold-aware lookup of a file's session entry -- resolves `filePath` through {@link resolveFilesKey} the same way `recordFileRead`/`wasFileReadThisSession` do, so a caller that only has a differently-cased path than the one first recorded (case-insensitive filesystems) still finds the existing entry instead of missing it. Use this instead of a direct `getSessionFiles().get(filePath)` for any single-entry lookup. */
export function getSessionFileEntry(filePath: string): FileEntry | undefined {
return _files.get(resolveFilesKey(normalizePath(filePath)))
}
/** True if `hintKey` has already been marked shown this session. */
export function wasHintShown(hintKey: string): boolean {
return _hintsShown.has(hintKey)
}
/** Mark `hintKey` as shown so a later {@link wasHintShown} returns true. */
export function markHintShown(hintKey: string): void {
_hintsShown.add(hintKey)
}
/** Record one scheduled-prompt delivery and return its session-local occurrence number. */
export function recordScheduledPrompt(sessionId: string): number {
const count = (_scheduledPromptCounts.get(sessionId) ?? 0) + 1
_scheduledPromptCounts.set(sessionId, count)
return count
}
/** True if `cliReadKey` (a `token-goat symbol|read|section` invocation) already ran this session. */
export function wasCliReadThisSession(cliReadKey: string): boolean {
return _cliReads.has(cliReadKey)
}
/** Record that a `token-goat symbol|read|section` invocation ran this session. */
export function recordCliRead(cliReadKey: string): void {
_cliReads.add(cliReadKey)
}
/** Record that a large-file hint fired for `filePath` (size in bytes), pending an outcome resolution. */
export function recordLargeFileHintPending(filePath: string, sizeBytes: number): void {
_pendingLargeFileHints.set(foldPath(normalizePath(filePath)), sizeBytes)
}
/** Consume and return the pending large-file-hint size for `filePath`, or null if none is pending. */
export function takePendingLargeFileHint(filePath: string): number | null {
const key = foldPath(normalizePath(filePath))
const size = _pendingLargeFileHints.get(key)
if (size === undefined) return null
_pendingLargeFileHints.delete(key)
return size
}
/** Keys pending at load but resolved (consumed) since — tombstones for session_store.ts's merge. */
export function consumedPendingLargeFileHintKeys(): string[] {
const consumed: string[] = []
for (const key of _pendingLargeFileHintsAtLoad.keys()) {
if (!_pendingLargeFileHints.has(key)) consumed.push(key)
}
return consumed
}
/** Snapshot of pending large-file hints exactly as they were at hydration time, before this process made any changes. session_store.ts's merge uses this to tell "this process merely carried the key from load, untouched" apart from "this process genuinely added or updated it": an untouched key must defer to the freshest disk read instead of being blindly resurrected if another process legitimately removed it in the meantime. */
export function pendingLargeFileHintsAtLoad(): ReadonlyMap<string, number> {
return _pendingLargeFileHintsAtLoad
}
/** Cap on start directories held for Bash calls whose post hook has not run; a call the harness never finished would otherwise keep its entry for the rest of the session. */
export const MAX_BASH_START_CWDS = 32
/** Record `cwd`, the directory Bash call `toolUseId` starts in, for the post hook of the same call. Past {@link MAX_BASH_START_CWDS} the oldest entry goes. */
export function recordBashStartCwd(toolUseId: string, cwd: string): void {
_bashStartCwds.delete(toolUseId)
_bashStartCwds.set(toolUseId, cwd)
for (const oldest of _bashStartCwds.keys()) {
if (_bashStartCwds.size <= MAX_BASH_START_CWDS) break
_bashStartCwds.delete(oldest)
}
}
/** Consume and return the directory Bash call `toolUseId` started in, or null when no pre hook recorded one for it. */
export function takeBashStartCwd(toolUseId: string): string | null {
const cwd = _bashStartCwds.get(toolUseId)
if (cwd === undefined) return null
_bashStartCwds.delete(toolUseId)
return cwd
}
/** Start directories exactly as they were at hydration time, which session_store.ts's merge compares against the way it uses {@link curlDownloadsAtLoad}. */
export function bashStartCwdsAtLoad(): ReadonlyMap<string, string> {
return _bashStartCwdsAtLoad
}
/** tool_use_ids present at load but taken or evicted since: tombstones for session_store.ts's merge, as {@link consumedCurlDownloadKeys} is for downloads. */
export function consumedBashStartCwdKeys(): string[] {
const consumed: string[] = []
for (const key of _bashStartCwdsAtLoad.keys()) {
if (!_bashStartCwds.has(key)) consumed.push(key)
}
return consumed
}
/** Field separator inside the composite webFetch session-state key. */
export const WEB_FETCH_KEY_SEP = '\x00'
/** Build the session-state key for a fetched url + prompt. The session-state file is written without storeBlob's redaction pass, so a signed url or one with an embedded api key was persisted in full -- as was the prompt, which can carry a header or token the caller pasted in. Both halves are redacted here. Redaction alone is not a safe key: two urls differing only inside the redacted span collapse to one entry, silently dropping a fetch from the compaction manifest and breaking the exact (url, prompt) lookup contract. A digest of the raw pair is appended to restore identity while the readable, redacted halves stay first -- the manifest displays those (hooks_compact.ts, compact.ts), and both read only the leading fields. */
function webFetchKey(url: string, prompt: string): string {
const digest = shortFingerprint(`${url}${WEB_FETCH_KEY_SEP}${prompt}`)
return [redactSecrets(url).text, redactSecrets(prompt).text, digest].join(WEB_FETCH_KEY_SEP)
}
/** Index a web-fetch result: (`url`, `prompt`) -> `cacheId`, so two WebFetch calls to the same url with different prompts are tracked separately instead of clobbering each other. */
export function recordWebFetch(url: string, prompt: string, cacheId: string): void {
_webFetches.set(webFetchKey(url, prompt), cacheId)
}
/** Return the cache id previously recorded for the (`url`, `prompt`) pair, or null. */
export function getWebFetchCacheId(url: string, prompt = ''): string | null {
return _webFetches.get(webFetchKey(url, prompt)) ?? null
}
/** Rewrite a persisted session-state key written by an older token-goat into the current shape. Old state files on disk hold the pre-redaction spellings: a curl key was the raw url, and a webFetch key was `url\x00prompt` with both halves unredacted. Left alone those rows are worse than useless -- they keep a signed url or an embedded api key sitting in the state file for the life of the session, and every lookup misses because the reader now computes the new key, so a cached fetch is silently re-fetched and re-billed. Migration happens at `coerce()` in session_store.ts, the single boundary every disk read passes through (including the fresh read the save path performs), so no caller has to remember it. Detection is shape-based, not versioned: a current curl key is exactly 16 hex chars, which no url can be, and a current webFetch key has three separator-delimited fields where the legacy one had two. A key already in the current shape is returned unchanged. */
export function migrateCurlDownloadKey(key: string): string {
if (/^[0-9a-f]{16}$/.test(key)) return key
return curlDownloadKey(key)
}
/** Legacy two-field `url + separator + prompt` key -> the current three-field key. See {@link migrateCurlDownloadKey}. */
export function migrateWebFetchKey(key: string): string {
const parts = key.split(WEB_FETCH_KEY_SEP)
if (parts.length !== 2) return key
return webFetchKey(parts[0] ?? '', parts[1] ?? '')
}
/** Return every web-fetch this session as a `url -> cacheId` map (insertion order). */
export function getSessionWebFetches(): ReadonlyMap<string, string> {
return _webFetches
}
/** Index a bash-output result: `commandHash` -> `outputId`. `sizeBytes` is accepted to match the spec'd signature; the size itself lives with the full entry in the bash-output cache, so it is not stored here. */
export function recordBashOutput(commandHash: string, outputId: string, _sizeBytes: number): void {
_bashOutputs.set(commandHash, outputId)
}
/** All bash-output cache entries currently tracked this session: [commandHash, outputId] pairs. */
export function getSessionBashOutputs(): Array<[string, string]> {
return Array.from(_bashOutputs.entries())
}
/** Marks `commandHash` as rerun: a store call overwrote an already-present cached entry under this exact key. */
export function recordBashRerun(commandHash: string): void {
_bashReruns.add(commandHash)
}
/** Command hashes rerun this session (see {@link recordBashRerun}). */
export function getSessionBashReruns(): string[] {
return Array.from(_bashReruns)
}
/** Return the output id previously recorded for `commandHash`, or null. */
export function getBashOutputId(commandHash: string): string | null {
return _bashOutputs.get(commandHash) ?? null
}
/** Record a Grep query's match count: `signature` -> matchCount, for dedup-hint recall. */
export function recordGrepQuery(signature: string, matchCount: number): void {
_grepQueries.set(signature, matchCount)
}
/** Return the previously recorded match count for `signature`, or null if never seen this session. */
export function getGrepMatchCount(signature: string): number | null {
return _grepQueries.get(signature) ?? null
}
/** Record a Glob query's match count: `signature` -> matchCount, for dedup-hint recall. */
export function recordGlobQuery(signature: string, matchCount: number): void {
_globQueries.set(signature, matchCount)
}
/** Return the previously recorded match count for `signature`, or null if never seen this session. */
export function getGlobMatchCount(signature: string): number | null {
return _globQueries.get(signature) ?? null
}
/** Record the most recent "Tab Context:" block seen this session, for hooks_browser_image.ts's dedup. A fingerprint is stored, never the block itself. The only question ever asked of this value is whether the next block is identical to it ({@link lastTabContextMatches}), and a fingerprint answers that exactly. The block does not: it is a list of the tabs open in the user's browser, titles and full URLs, and session state is written to disk, so keeping the text would put whatever a URL happens to carry -- a session token, a signed link, a password-reset parameter -- into a file on disk that nothing ever reads back for its content. */
export function setLastTabContext(text: string): void {
_lastTabContext = shortFingerprint(text)
}
/** Whether `text` is the same "Tab Context:" block already seen this session. */
export function lastTabContextMatches(text: string): boolean {
return _lastTabContext !== null && _lastTabContext === shortFingerprint(text)
}
/** One verification command (test, lint, typecheck, build) as the host reported it. `exitCode` is null when the host does not report a status for a call that ran. */
export interface VerificationRun {
readonly command: string
readonly exitCode: number | null
readonly at: number
}
/** Upper bound on distinct verification commands remembered per session. */
export const MAX_VERIFICATION_RUNS = 8
/** Remember a verification run, replacing an earlier run of the same command so only its latest verdict counts, and evicting the oldest past {@link MAX_VERIFICATION_RUNS}. */
export function recordVerificationRun(command: string, exitCode: number | null, at: number = Date.now()): void {
_verificationRuns = _verificationRuns.filter((r) => r.command !== command)
_verificationRuns.push({ command, exitCode, at })
if (_verificationRuns.length > MAX_VERIFICATION_RUNS) _verificationRuns = _verificationRuns.slice(-MAX_VERIFICATION_RUNS)
}
/** Upper bound on screenshot fingerprints remembered per session. Bounded for the same reason MAX_OUTSTANDING_AGENT_SPAWNS is: a long browsing session takes hundreds of screenshots and this list is written to disk on every hook. Oldest is evicted first, which is also the right policy on merit -- a screenshot from an hour ago being repeated now is a coincidence, while one from three tool calls ago is a poll loop. */
export const MAX_SEEN_IMAGE_HASHES = 16
/** True when a screenshot with this fingerprint has already been shown this session. */
export function hasSeenImage(hash: string): boolean {
return _seenImageHashes.includes(hash)
}
/** Remember a screenshot fingerprint, evicting the oldest once {@link MAX_SEEN_IMAGE_HASHES} is reached. */
export function recordSeenImage(hash: string): void {
const at = _seenImageHashes.indexOf(hash)
if (at !== -1) _seenImageHashes.splice(at, 1)
_seenImageHashes.push(hash)
if (_seenImageHashes.length > MAX_SEEN_IMAGE_HASHES) {
_seenImageHashes.splice(0, _seenImageHashes.length - MAX_SEEN_IMAGE_HASHES)
}
}
/** Upper bound on outstanding Agent-spawn prompts tracked per session; oldest recorded first once exceeded, mirroring MAX_RANGES_PER_FILE's cap-then-evict shape. A long session that spawns many subagents must not grow this list unboundedly. */
export const MAX_OUTSTANDING_AGENT_SPAWNS = 30
/** Record that an Agent-tool spawn with `prompt` (the original prompt text, before any briefing/advisory is appended) is now outstanding this session. Caps the tracked list at {@link MAX_OUTSTANDING_AGENT_SPAWNS}, evicting the oldest entries first. */
export function recordOutstandingAgentSpawn(prompt: string): void {
// Redact before storing: this prompt lands in SerializedSession.outstandingAgentSpawns and, on a later hooks_agent_spawn.ts truncateForWarning read, is echoed back model-ward -- a raw secret pasted into a spawned agent's prompt must never survive into either surface.
_outstandingAgentSpawns.push({ prompt: redactSecrets(prompt).text, ts: Date.now() })
if (_outstandingAgentSpawns.length > MAX_OUTSTANDING_AGENT_SPAWNS) {
_outstandingAgentSpawns.splice(0, _outstandingAgentSpawns.length - MAX_OUTSTANDING_AGENT_SPAWNS)
}
}
/** Every Agent-spawn prompt currently outstanding this session (insertion order). */
export function getOutstandingAgentSpawns(): ReadonlyArray<OutstandingAgentSpawn> {
return _outstandingAgentSpawns
}
/** Remove the outstanding entry whose tracked prompt is a prefix of `finishedPrompt` -- prefix, not exact equality, because preAgentHandler's rewriteInput only ever appends text (briefing/advisory) after the original prompt tracked here, so a completed spawn's actual tool_input prompt always starts with the tracked original. Removes the oldest match first (the earliest still-outstanding entry with that prefix) and is a no-op if none match. */
export function removeOutstandingAgentSpawn(finishedPrompt: string): void {
const idx = _outstandingAgentSpawns.findIndex((e) => finishedPrompt.startsWith(e.prompt))
if (idx !== -1) _outstandingAgentSpawns.splice(idx, 1)
}
/** A stable identity key for one outstanding-spawn entry (prompt + record timestamp), used by session_store.ts's merge to tell entries apart even when two distinct spawns share identical prompt text. */
export function outstandingAgentSpawnKey(prompt: string, ts: number): string {
return `${prompt} ${ts}`
}
/** Snapshot of outstanding Agent-spawn entries exactly as they were at hydration time, before this process made any changes. session_store.ts's merge uses this to compute which entries this process explicitly removed (see {@link consumedOutstandingAgentSpawnKeys}). */
export function outstandingAgentSpawnsAtLoad(): ReadonlyArray<OutstandingAgentSpawn> {
return _outstandingAgentSpawnsAtLoad
}
/** Keys (see {@link outstandingAgentSpawnKey}) present at load but removed (consumed by {@link removeOutstandingAgentSpawn}) since -- tombstones for session_store.ts's merge, mirroring {@link consumedPendingLargeFileHintKeys} for the same removal-is-not-a-union-op reason. */
export function consumedOutstandingAgentSpawnKeys(): string[] {
const currentKeys = new Set(_outstandingAgentSpawns.map((e) => outstandingAgentSpawnKey(e.prompt, e.ts)))
const consumed: string[] = []
for (const e of _outstandingAgentSpawnsAtLoad) {
const key = outstandingAgentSpawnKey(e.prompt, e.ts)
if (!currentKeys.has(key)) consumed.push(key)
}
return consumed
}
/** Record that a curl -o download saved `url` to `savedPath` this session. */
/** Key the curl-download map by a digest of the url rather than the url itself. A download url routinely carries a credential -- an `api_key=` query parameter, a signed link's `X-Amz-Signature` -- and this map is serialized verbatim into the session-state file, which is written directly rather than through storeBlob's redaction pass. web_cache.ts already redacts a url for exactly this reason. A digest rather than a redaction because the only consumer is an exact-match lookup that DENIES a repeat download: two urls differing only inside a redacted span would collide and block a legitimate fetch of a different resource. Nothing displays this key, so a digest costs nothing. */
function curlDownloadKey(url: string): string {
return shortFingerprint(url)
}
export function recordCurlDownload(url: string, savedPath: string): void {
_curlDownloads.set(curlDownloadKey(url), savedPath)
}
/** Return the file path where `url` was saved this session via curl -o, or null. */
export function getCurlDownloadPath(url: string): string | null {
return _curlDownloads.get(curlDownloadKey(url)) ?? null
}
/** Forget a recorded curl -o download for `url` (e.g. its saved file is gone). */
export function clearCurlDownload(url: string): void {
_curlDownloads.delete(curlDownloadKey(url))
}
/** Snapshot of curl-download entries exactly as they were at hydration time, before this process made any changes. session_store.ts's merge uses this to compute which entries this process explicitly cleared (see {@link consumedCurlDownloadKeys}). */
export function curlDownloadsAtLoad(): ReadonlyMap<string, string> {
return _curlDownloadsAtLoad
}
/** URLs present at load but cleared (consumed by {@link clearCurlDownload}) since -- tombstones for session_store.ts's merge, mirroring {@link consumedPendingLargeFileHintKeys} for the same removal-is-not-a-union-op reason. */
export function consumedCurlDownloadKeys(): string[] {
const consumed: string[] = []
for (const url of _curlDownloadsAtLoad.keys()) {
if (!_curlDownloads.has(url)) consumed.push(url)
}
return consumed
}
/** Folded file paths present at load but cleared (consumed by {@link recordFileEdit}) since, plus every path {@link resetFileLineRanges} cleared whether or not a range was recorded for it again afterwards -- tombstones for session_store.ts's merge, same removal-is-not-a-union-op reason as {@link consumedCurlDownloadKeys}: a per-file deletion must actually stick instead of being resurrected by a plain disk/mem union. */
export function consumedFileLineRangeKeys(): string[] {
const consumed = new Set(_fileLineRangesReset)
for (const key of _fileLineRangesAtLoad.keys()) {
if (!_fileLineRanges.has(key)) consumed.add(key)
}
return [...consumed]
}
/** Same as {@link consumedFileLineRangeKeys}, for the served-output index {@link markCompacted} clears wholesale. Unlike the line ranges, {@link recordFileEdit} does not clear this one -- it is matched on the served bytes, so a stale id simply fails to match. */
export function consumedFileServedOutputKeys(): string[] {
const consumed: string[] = []
for (const key of _fileServedOutputsAtLoad.keys()) {
if (!_fileServedOutputs.has(key)) consumed.push(key)
}
return consumed
}
/** Cap on retained line ranges per file - bounds memory if one file is paged many times. */
export const MAX_RANGES_PER_FILE = 64
/** Best-effort file identity (size + mtimeMs) for the repeated-range deny's no-snapshot fallback, or undefined when the file cannot be stat'd. */
function statIdentity(absPath: string): { size: number; mtimeMs: number } | undefined {
try {
const st = fs.statSync(hostPathOfIndexKey(absPath))
return { size: st.size, mtimeMs: st.mtimeMs }
} catch {
return undefined
}
}
/** Record that inclusive line range [start, end] of `filePath` was served via a sed line-range read this session. Deduplicates identical ranges and caps retained ranges per file. Also stamps the file's current identity (size + mtimeMs) onto its session entry, so a later repeated read of the same range can be denied even when no content snapshot exists to diff against (see `rangeFileIdentity`). */
export function recordFileLineRange(filePath: string, start: number, end: number, hashNow?: CurrentFileHash): void {
const normalized = normalizePath(filePath)
const key = foldPath(normalized)
const entryKey = resolveFilesKey(normalized)
const entry = _files.get(entryKey)
// The ranges on record were served while the file had the identity stamped beside them. Re-stamping it for this range without dropping them would let the repeated-range deny in hooks_read.ts vouch for text the model was never shown, since every later read of any other window also refreshes the snapshot it diffs against.
const identity = dropFileLineRangesIfChanged(normalized, false, hashNow)
// Ranges with no identity beside them (a session saved before identities existed) cannot be proven against any hash, so they go and this range starts a set that can.
if (identity !== undefined && getFileLineRangeIdentity(normalized) === undefined && (_fileLineRanges.get(key)?.length ?? 0) > 0) resetFileLineRanges(normalized)
const ranges = _fileLineRanges.get(key) ?? []
// The hash is taken when a set of ranges starts and kept while they stand: it must describe the bytes the first range was served from, so a set already on record never takes a newer one.
const priorFp = getFileLineRangeIdentity(normalized)?.fp
const fp = priorFp ?? (ranges.length === 0 && identity !== undefined ? boundedFingerprint(normalized, identity.size, hashNow) : undefined)
if (!ranges.some(([s, e]) => s === start && e === end)) {
ranges.push([start, end])
if (ranges.length > MAX_RANGES_PER_FILE) ranges.splice(0, ranges.length - MAX_RANGES_PER_FILE)
_fileLineRanges.set(key, ranges)
}
const stamped: FileRangeIdentity | undefined = identity === undefined ? undefined : (fp === undefined ? identity : { ...identity, fp })
if (stamped) _fileLineRangeIdentities.set(key, stamped)
if (entry && stamped) _files.set(entryKey, { ...entry, rangeFileIdentity: stamped })
}
/** SHA-256 of the file's bytes, or undefined when it is larger than {@link RANGE_FINGERPRINT_MAX_BYTES} or cannot be read. */
function boundedFingerprint(normalized: string, size: number, hashNow?: CurrentFileHash): string | undefined {
if (size > RANGE_FINGERPRINT_MAX_BYTES) return undefined
return (hashNow ?? onceCurrentFileHash(normalized))() ?? undefined
}
/** The identity recorded when `filePath`'s line ranges were last recorded: the one beside the ranges, else the one on its session entry; undefined when none was ever recorded. */
export function getFileLineRangeIdentity(filePath: string): FileRangeIdentity | undefined {
const normalized = normalizePath(filePath)
return _fileLineRangeIdentities.get(foldPath(normalized)) ?? _files.get(resolveFilesKey(normalized))?.rangeFileIdentity
}
/** Do the bytes on disk match the ones the recorded ranges of `filePath` were served from? 'same' and 'changed' are proven by the hash taken when the ranges were first recorded; 'unproven' means no hash was taken (a file past {@link RANGE_FINGERPRINT_MAX_BYTES}, or a session recorded before the hash existed) or the file cannot be read now, so a stat that still matches the record is all there is and proves nothing about a same-size rewrite. */
export function rangeContentVerdict(filePath: string, hashNow?: CurrentFileHash): 'same' | 'changed' | 'unproven' {
const normalized = normalizePath(filePath)
const recorded = getFileLineRangeIdentity(normalized)
if (recorded?.fp === undefined) return 'unproven'
const current = statIdentity(normalized)
if (current === undefined || current.size > RANGE_FINGERPRINT_MAX_BYTES) return 'unproven'
const now = (hashNow ?? onceCurrentFileHash(normalized))()
if (now === null) return 'unproven'
return now === recorded.fp ? 'same' : 'changed'
}
const SERVED_SECTION_TARGET_PREFIX = 'served-section::'
/** Record a section target against the fingerprint of its served range. */
export function recordServedSectionTarget(filePath: string, target: string): void {
const normalized = normalizePath(filePath)
if (target === '' || getFileLineRanges(normalized).length === 0) return
const fingerprint = getFileLineRangeIdentity(normalized)?.fp
if (fingerprint === undefined) return
_cliReads.add(`${SERVED_SECTION_TARGET_PREFIX}${normalized}::${JSON.stringify([target, fingerprint])}`)
}
/** Section targets whose own served-range fingerprint is still current. */
export function getConsumedSectionTargets(filePath: string): ReadonlySet<string> {
const normalized = normalizePath(filePath)
const fingerprint = getFileLineRangeIdentity(normalized)?.fp
if (getFileLineRanges(normalized).length === 0 || fingerprint === undefined || rangeContentVerdict(normalized) !== 'same') return new Set()
const prefix = `${SERVED_SECTION_TARGET_PREFIX}${normalized}::`
const consumed = new Set<string>()
for (const cliReadKey of _cliReads) {
if (!cliReadKey.startsWith(prefix)) continue
let decoded: unknown
try {
decoded = JSON.parse(cliReadKey.slice(prefix.length))
} catch {
// Invalid persisted marker data cannot prove that a target was served.
continue
}
if (!Array.isArray(decoded) || decoded.length !== 2) continue
const target: unknown = decoded[0]
const servedFingerprint: unknown = decoded[1]
if (typeof target !== 'string' || target === '' || servedFingerprint !== fingerprint) continue
consumed.add(target)
}
return consumed
}
/** Drop `filePath`'s recorded line ranges when the file no longer has the size and mtime it had when they were recorded, or holds different bytes than the hash taken then (see {@link rangeContentVerdict}), and return its current identity (undefined when it cannot be stat'd). The Bash pre hook calls this before it measures a `sed -n`/`head` read against those ranges, as {@link recordFileLineRange} does before it adds one: measured first, a re-read of lines changed outside the session was told to recall them from earlier output. With `requireProof`, ranges the bytes cannot vouch for go too -- no hash on record (a file past {@link RANGE_FINGERPRINT_MAX_BYTES}, or a session recorded before the hash existed) or no identity on record at all -- for a caller that answers "you already read this" from them: a matching stat is not proof, and unknown is read through. A caller that only counts ranges (paging) leaves it off and keeps them. */
export function dropFileLineRangesIfChanged(filePath: string, requireProof = false, hashNow?: CurrentFileHash): { size: number; mtimeMs: number } | undefined {
const normalized = normalizePath(filePath)
const identity = statIdentity(normalized)
const prior = _fileLineRangeIdentities.get(foldPath(normalized)) ?? _files.get(resolveFilesKey(normalized))?.rangeFileIdentity
if (identity === undefined) return identity
if (prior === undefined) {
if (requireProof && getFileLineRanges(normalized).length > 0) resetFileLineRanges(normalized)
return identity
}
if (prior.size !== identity.size || prior.mtimeMs !== identity.mtimeMs) {
resetFileLineRanges(normalized)
return identity
}
const verdict = rangeContentVerdict(normalized, hashNow)
if (verdict === 'changed' || (requireProof && verdict === 'unproven')) resetFileLineRanges(normalized)
return identity
}
/** Inclusive line ranges of `filePath` already served via sed this session (empty if none). */
export function getFileLineRanges(filePath: string): ReadonlyArray<readonly [number, number]> {
return _fileLineRanges.get(foldPath(normalizePath(filePath))) ?? []
}
/** Drop every recorded line range for `filePath` without marking it edited (unlike {@link recordFileEdit}, which does both): a change discovered on disk that the session itself never made -- an edit outside this session, or a Read/Write by another process -- still invalidates the ranges the exact-overlap dedup trusts, but it must not falsely mark the file as edited by this session for the compaction manifest and resume logic that read `wasEdited`. */
export function resetFileLineRanges(filePath: string): void {
const normalized = normalizePath(filePath)
const key = foldPath(normalized)
clearReadRangeEvasion(key)
_fileLineRanges.delete(key)
_fileLineRangeIdentities.delete(key)
// The identity stamped on the session entry marks the ranges just dropped, and its hash describes bytes they were served from; left in place, the next range recorded would inherit that hash for a file that has changed since.
const entryKey = resolveFilesKey(normalized)
const entry = _files.get(entryKey)
if (entry?.rangeFileIdentity !== undefined) {
const { rangeFileIdentity: _dropped, ...rest } = entry
_files.set(entryKey, rest)
}
_fileLineRangesReset.add(key)
}
/** Cap on retained served-output ids per file. Deliberately small: every id retained here is a blob the containment check may have to read from disk before it can decide, so this is a bound on that read fan-out and not just on memory. Newest ids are kept, since a later body is the more likely container of the next read of the same file. */
export const MAX_SERVED_OUTPUTS_PER_FILE = 8
// Reserved key for the session-wide served-output list a non-file-read Bash command's output is matched against and recorded into. `recordFileServedOutput`/`getFileServedOutputs` key on a path run through `foldPath(normalizePath(...))`, and no real filesystem path can begin with a NUL byte, so this can never collide with a genuine file key sharing the same store.
export const GENERIC_SERVED_OUTPUT_KEY = '\u0000<bash-generic-served>'
const GENERIC_SERVED_OUTPUT_FOLDED_KEY = foldPath(normalizePath(GENERIC_SERVED_OUTPUT_KEY))
/** Cap on retained served-output ids under the single session-wide generic (non-file) key. Unlike MAX_SERVED_OUTPUTS_PER_FILE, this key is shared by every non-file-read Bash command in the session rather than split one-per-file, so 8 would mean "only the last 8 Bash outputs in the whole session are searchable." Sized larger than the per-file cap for that reason, while still bounding the read-and-index fan-out `elideServedShellLines` pays for every id in the list on each call. */
export const MAX_GENERIC_SERVED_OUTPUTS = 32
/** Record that the body cached under `outputId` was served to this session as a read of `filePath`. */
export function recordFileServedOutput(filePath: string, outputId: string): void {
const key = foldPath(normalizePath(filePath))
const cap = key === GENERIC_SERVED_OUTPUT_FOLDED_KEY ? MAX_GENERIC_SERVED_OUTPUTS : MAX_SERVED_OUTPUTS_PER_FILE
const ids = (_fileServedOutputs.get(key) ?? []).filter((id) => id !== outputId)
ids.push(outputId)
if (ids.length > cap) ids.splice(0, ids.length - cap)
_fileServedOutputs.set(key, ids)
}
/** Cache ids whose body this session was shown as a read of `filePath`, newest last (empty if none). */
export function getFileServedOutputs(filePath: string): readonly string[] {
return _fileServedOutputs.get(foldPath(normalizePath(filePath))) ?? []
}
/** Mark `filePath` as having been delivered incompletely this session. Two callers, not one: the post_tool_use Read hook when the tool response carries a `[Truncated:` marker, and the post_tool_use Bash hook for a tail-style dump, whose shown lines cannot be placed against the file because their absolute start depends on a total line count the hook does not have. A later pre_tool_use for the same file may then deny with a skeleton/surgical-read hint rather than serve another full read. May, not will: the deny is gated on `hints.truncated_read_min_lines`, so a small file that merely tripped the token-based marker is still read normally, a redirect there costing more than it saves. Session-artifact files take a separate branch with their own recall message. */
export function markFileTruncated(filePath: string, isFullRead: boolean = true): void {
const normalized = normalizePath(filePath)
const key = resolveFilesKey(normalized)
const prev = _files.get(key)
const now = Date.now()
if (prev === undefined) {
_files.set(key, {
path: key,
readCount: 1,
lastReadAt: now,
wasEdited: false,
sizeBytes: fileSize(normalized),
wasTruncated: true,
...(isFullRead ? { lastFullReadAt: now, fullReadCount: 1 } : {}),
...newEntryEpochBase(),
})
return
}
// An existing entry already went through recordFileRead for this same read (pre_tool_use runs before post_tool_use lands here), so readCount/lastFullReadAt/fullReadCount are already correct -- only the truncation flag is new information here.
_files.set(key, { ...prev, wasTruncated: true })
}
/** True if the file was truncated during a Read this session. */
export function wasFileTruncatedThisSession(filePath: string): boolean {
const entry = _files.get(resolveFilesKey(normalizePath(filePath)))
return entry?.wasTruncated === true
}
/** Generate a random session id when `CLAUDE_CODE_SESSION_ID` is unset. Prefers `crypto.randomUUID` (Node >= 19); falls back to hex from `randomBytes` on older runtimes where `randomUUID` is unavailable. */
function generateSessionId(): string {
try {
return randomUUID()
} catch {
return randomBytes(16).toString('hex')
}
}
/** Return the session id. Uses `process.env.CLAUDE_CODE_SESSION_ID` whenever it is set and non-empty, read on every call: relay.ts re-seeds it per event in a bridge host that serves one session after another. Otherwise a generated id, cached so repeated calls return the same value. */
export function getSessionId(): string {
const fromEnv = process.env['CLAUDE_CODE_SESSION_ID']
if (fromEnv !== undefined && fromEnv !== '') return fromEnv
_sessionId ??= generateSessionId()
return _sessionId
}
/** Record the transcript path from the hook payload, paired with the session it belongs to. Under Claude Code each hook invocation is its own short-lived process, but the bridges in `src/bridges/` module-cache `relayInProcess` and can serve more than one session from one process, so a bare latch-once would let session B measure session A's transcript -- worse than the estimate it replaced, because a wrong number reads as a real one. The pairing is what {@link getTranscriptPath} checks; a later call for the same session is a harmless no-op, and one for a different session replaces it. */
export function setTranscriptPath(path: string, sessionId: string): void {
if (path === '') return
_transcriptPath = { path, sessionId }
}
/** The current session's transcript path, if the harness sent one on the hook payload (see {@link setTranscriptPath}); undefined when none was sent or the one on record belongs to a different session. */
export function getTranscriptPath(): string | undefined {
if (_transcriptPath === null) return undefined
return _transcriptPath.sessionId === getSessionId() ? _transcriptPath.path : undefined
}
/** The serializable snapshot of session state. Maps are flattened to entry arrays so the shape round-trips through JSON. Consumed by `session_store.ts` to persist state across the per-tool-call hook processes (the Python `SessionCache` JSON this port restores). */
export interface SerializedSession {
files: FileEntry[]
hintsShown: string[]
scheduledPromptCounts?: Array<[string, number]>
webFetches: Array<[string, string]>
bashOutputs: Array<[string, string]>
bashReruns?: string[]
curlDownloads: Array<[string, string]>
fileLineRanges?: Array<[string, Array<[number, number]>]>
readRangeEvasion?: RangeEvasionEntries
/** path -> the file's size and mtime when a range of it was last recorded. See `_fileLineRangeIdentities`. Optional: sessions written before this field existed simply have none. */
fileLineRangeIdentities?: Array<[string, FileRangeIdentity]>
/** path -> bash-output ids whose body this session was shown as a read of that file, oldest first. Optional: sessions written before this field existed simply have none. */
fileServedOutputs?: Array<[string, string[]]>
cliReads?: string[]
pendingLargeFileHints?: Array<[string, number]>
/** tool_use_id -> the directory that Bash call started in, held from its pre hook to its post hook. See `_bashStartCwds`. */
bashStartCwds?: Array<[string, string]>
grepQueries?: Array<[string, number]>
globQueries?: Array<[string, number]>
outstandingAgentSpawns?: Array<[string, number]>
/** Fingerprint of the last "Tab Context:" block, never the block itself. See `setLastTabContext`. */
lastTabContextDigest?: string
/** Fingerprints of screenshots already shown this session, oldest first. See `_seenImageHashes`. */
seenImageHashes?: string[]
/** Verification commands run this session, newest last. See `recordVerificationRun`. */
verificationRuns?: VerificationRun[]
/** Unix-ms of the most recent context compaction, or absent if none. Merged max-wins by session_store.ts so a stamp made by one hook process is never lost to a concurrent process that predates it. See `_compactedAt`. */
compactedAt?: number
/** Unix time in *seconds* at which this session's on-disk cache was first written. Set exactly once by `session_store.ts::saveSessionState` and preserved across every later write, so it marks cache creation, not last modification. compact.ts derives the session-age budget multiplier from it. */
created_ts?: number
}
/** Snapshot the current in-memory session state for persistence. */
export function exportSessionState(): SerializedSession {
return {
files: Array.from(_files.values()),
hintsShown: Array.from(_hintsShown),
...(_scheduledPromptCounts.size > 0 ? { scheduledPromptCounts: Array.from(_scheduledPromptCounts.entries()) } : {}),
webFetches: Array.from(_webFetches.entries()),
bashOutputs: Array.from(_bashOutputs.entries()),
bashReruns: Array.from(_bashReruns),
curlDownloads: Array.from(_curlDownloads.entries()),
fileLineRanges: Array.from(_fileLineRanges.entries()),
readRangeEvasion: exportReadRangeEvasion(),
...(_fileLineRangeIdentities.size > 0 ? { fileLineRangeIdentities: Array.from(_fileLineRangeIdentities.entries()) } : {}),
...(_fileServedOutputs.size > 0 ? { fileServedOutputs: Array.from(_fileServedOutputs.entries()) } : {}),
cliReads: Array.from(_cliReads),
pendingLargeFileHints: Array.from(_pendingLargeFileHints.entries()),
...(_bashStartCwds.size > 0 ? { bashStartCwds: Array.from(_bashStartCwds.entries()) } : {}),
grepQueries: Array.from(_grepQueries.entries()),
globQueries: Array.from(_globQueries.entries()),
outstandingAgentSpawns: _outstandingAgentSpawns.map((e) => [e.prompt, e.ts]),
...(_lastTabContext !== null ? { lastTabContextDigest: _lastTabContext } : {}),
...(_seenImageHashes.length > 0 ? { seenImageHashes: [..._seenImageHashes] } : {}),
...(_verificationRuns.length > 0 ? { verificationRuns: [..._verificationRuns] } : {}),
...(_compactedAt > 0 ? { compactedAt: _compactedAt } : {}),
}
}
/** Replace the in-memory session state with `s` (hydrate from a loaded snapshot). Called once per hook process after loading the on-disk state, before any handler runs. `FileEntry.path` is already the normalized map key, so entries re-key directly. Tolerant of a malformed `path` (skips that entry) but assumes the caller has otherwise validated the shape. */
export function importSessionState(s: SerializedSession): void {
importReadRangeEvasion(s.readRangeEvasion ?? [])
_files = new Map()
for (const e of s.files) {
if (e && typeof e.path === 'string') _files.set(e.path, e)
}
_filesAtLoad = new Map(Array.from(_files, ([key, e]) => [key, e.readCount]))
_filesFullReadCountAtLoad = new Map(Array.from(_files, ([key, e]) => [key, e.fullReadCount ?? 0]))
_hintsShown = new Set(s.hintsShown)
_scheduledPromptCounts = new Map(s.scheduledPromptCounts ?? [])
_webFetches = new Map(s.webFetches)
_bashOutputs = new Map(s.bashOutputs)
_bashReruns = new Set(s.bashReruns ?? [])
_curlDownloads = new Map(s.curlDownloads)
_curlDownloadsAtLoad = new Map(_curlDownloads)
_fileLineRanges = new Map(s.fileLineRanges ?? [])
_fileLineRangesAtLoad = new Map(_fileLineRanges)
_fileLineRangesReset = new Set()
_fileLineRangeIdentities = new Map(s.fileLineRangeIdentities ?? [])
_fileServedOutputs = new Map(s.fileServedOutputs ?? [])
_fileServedOutputsAtLoad = new Map(_fileServedOutputs)
_cliReads = new Set(s.cliReads ?? [])
_pendingLargeFileHints = new Map(s.pendingLargeFileHints ?? [])
_pendingLargeFileHintsAtLoad = new Map(_pendingLargeFileHints)
_bashStartCwds = new Map(s.bashStartCwds ?? [])
_bashStartCwdsAtLoad = new Map(_bashStartCwds)
_grepQueries = new Map(s.grepQueries ?? [])
_globQueries = new Map(s.globQueries ?? [])
_outstandingAgentSpawns = (s.outstandingAgentSpawns ?? []).map(([prompt, ts]) => ({ prompt, ts }))
_outstandingAgentSpawnsAtLoad = [..._outstandingAgentSpawns]
_lastTabContext = s.lastTabContextDigest ?? null
_seenImageHashes = [...(s.seenImageHashes ?? [])]