Repository navigation
Expand file tree
/
Copy pathskill_cache.ts
More file actions
971 lines (840 loc) · 42.1 KB
/
Copy pathskill_cache.ts
File metadata and controls
971 lines (840 loc) · 42.1 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
/** Persistent store for loaded-skill bodies. Every skill load records the body to a text file under `data_dir() / "skills"` keyed by session ID, skill name, and content hash. After compaction, the agent can recall the full body via the CLI without re-invoking the skill. Why a separate disk store: - Skill bodies can be tens of KB. Inlining into session JSON bloats round trips. - CLI retrieval can stream the file directly without re-parsing JSON. - Retention is simple to bound by total bytes via LRU eviction. - Cross-session dedup: the same skill body reuses the existing file. A later session that loads that body writes only a small `<its outputId>.load` record naming the shared body, so the load still counts as that session's own. */
import * as fs from 'fs/promises'
import { resolve } from 'path'
import { copilotSkillPath } from './copilot_skill_path.js'
import { claudeConfigDir } from './claude_config_dir.js'
import { dataDir } from './constants.js'
import { shortFingerprint } from './fingerprint.js'
import { atomicWriteText, ensureDirSync, isCodeFenceDelimiter, stripLower } from './util.js'
import { registerReset } from './reset.js'
import { readdirSync, readFileSync, existsSync, statSync, unlinkSync } from 'node:fs'
import { DEFAULT_MAX_COUNT, DEFAULT_MAX_AGE_MS } from './disk_cache.js'
import { redactSecrets } from './secret_redact.js'
import { recordStat } from './stats.js'
import { parseSkillSectionSpec } from './skill_section_spec.js'
const COMPACT_END_MARKER = '<!-- COMPACT_END -->'
// The 'skills' subdir name, exported so prune-cache/clean-cache (cache_session_commands.ts) can include it in their managed-subdirs list. Unlike the other cache subdirs, entries here are plain .txt/.meta/.hits/@compact files rather than disk_cache.ts's JSON blob envelope, so eviction is handled by this module's own pruneSkillOutputs rather than the generic pruneBlobs.
export const SKILLS_OUTPUT_SUBDIR = 'skills'
let _skillOutputsDirOverride: string | null = null
let _skillsSourceDirOverride: string | null = null
let _pluginsManifestPathOverride: string | null = null
export function setSkillOutputsDirForTesting(dir: string | null): void {
_skillOutputsDirOverride = dir
}
export function setSkillsSourceDirForTesting(dir: string | null): void {
_skillsSourceDirOverride = dir
}
export function setPluginsManifestPathForTesting(p: string | null): void {
_pluginsManifestPathOverride = p
}
registerReset(() => {
_skillOutputsDirOverride = null
_skillsSourceDirOverride = null
_pluginsManifestPathOverride = null
inProcessHitLockQueues.clear()
})
export interface SkillMeta {
readonly outputId: string
readonly skillName: string
readonly contentSha: string
readonly bodyBytes: number
readonly ts: number
readonly truncated: boolean
readonly sourcePath?: string
}
export interface CachedSkillInfo {
readonly name: string
readonly bodyLen: number
readonly compactLen: number
readonly hasMarker: boolean
readonly compactStale: boolean | null
readonly hitCount: number
readonly ageMs: number
}
export function skillOutputsDir(): string {
if (_skillOutputsDirOverride) return _skillOutputsDirOverride
return resolve(dataDir(), SKILLS_OUTPUT_SUBDIR)
}
// The on-disk source directory where Claude Code installs skills, one dir per skill containing a SKILL.md. Resolved through claudeConfigDir() rather than a bare homedir() because Claude Code installs skills under `$CLAUDE_CONFIG_DIR` when that is set, and lazily so a test override (or spy) takes effect per call. This is the install location, distinct from skillOutputsDir() which is token-goat's body cache.
function skillsSourceDir(): string {
if (_skillsSourceDirOverride) return _skillsSourceDirOverride
return resolve(claudeConfigDir(), 'skills')
}
async function ensureSkillsDir(): Promise<void> {
try {
ensureDirSync(skillOutputsDir())
} catch {
// already exists
}
}
export function contentHash(content: string): string {
return shortFingerprint(content)
}
function safeSessionFragment(sessionId: string): string {
let result = ''
for (const c of sessionId) {
if (result.length >= 16) break
if (/[a-zA-Z0-9_-]/.test(c)) {
result += c
}
}
return result.slice(0, 16)
}
export function safeSkillName(skillName: string): string | null {
if (!skillName || skillName.length > 128) return null
if (!/^[A-Za-z0-9_:-]+$/.test(skillName)) return null
return skillName.replace(/[^a-zA-Z0-9_:-]/g, '_')
}
/** Return a filename-safe version of a skill name: colons are invalid on Windows and must be replaced. Used for all on-disk compact file paths so store/get/list always agree. Substitutes ':' for '~' rather than '_': '~' falls outside safeSkillName's allowed charset (A-Za-z0-9_:-), so it can never occur in a name that reaches this function, making the substitution truly injective — a literal '_' is left untouched and can never collide with a colon-derived '~'. (A prior '_' + discriminator-suffix scheme was not injective: 'test:a' and 'test_an' both produced 'test_an'.) */
function sanitizeSkillId(name: string): string {
return name.replace(/:/g, '~')
}
function sessionSkillPrefix(sessionId: string, skillName: string): string {
const safeSession = safeSessionFragment(sessionId)
return `${safeSession}-${sanitizeSkillId(skillName)}-`
}
export function outputIdFor(sessionId: string, skillName: string, contentSha: string): string {
return `${sessionSkillPrefix(sessionId, skillName)}${contentSha}`
}
/** File extension of a session load record: see {@link SkillLoadRecord}. */
const LOAD_RECORD_EXT = '.load'
/** One session's load of a skill whose body another session already stored. storeOutput keeps one copy of an identical body across sessions, so the second session's load writes this record under its own outputId instead of a second body. Without it the second session had no entry carrying its own fragment, and the reload deny, which asks "did this session load the skill", fired only in the first session that ever loaded it. */
interface SkillLoadRecord {
readonly loadId: string
readonly skillName: string
readonly contentSha: string
readonly bodyOutputId: string
readonly bodyBytes: number
readonly ts: number
}
function readLoadRecordsSync(dir: string): SkillLoadRecord[] {
const records: SkillLoadRecord[] = []
let files: string[]
try {
files = readdirSync(dir)
} catch {
return records
}
for (const file of files) {
if (!file.endsWith(LOAD_RECORD_EXT)) continue
try {
const parsed = JSON.parse(readFileSync(resolve(dir, file), 'utf-8')) as Omit<SkillLoadRecord, 'loadId'>
if (typeof parsed.skillName !== 'string' || typeof parsed.bodyOutputId !== 'string') continue
records.push({ ...parsed, loadId: file.slice(0, -LOAD_RECORD_EXT.length) })
} catch {
continue
}
}
return records
}
/** Every load of *name* by the session whose safe fragment is *safeSession*, as `{ bodyBytes, ts }`: the session's own stored outputs, plus its load records whose shared body is still stored. A record whose body was evicted is not a load this session can recall, so it is skipped rather than reported. */
async function sessionLoads(safeSession: string, name: string): Promise<Array<{ bodyBytes: number; ts: number }>> {
const metas = await listOutputs()
const own = metas.filter(m => m.skillName === name && m.outputId.startsWith(`${safeSession}-`))
const storedIds = new Set(metas.map(m => m.outputId))
const recorded = readLoadRecordsSync(skillOutputsDir()).filter(
r => r.skillName === name && r.loadId.startsWith(`${safeSession}-`) && storedIds.has(r.bodyOutputId),
)
return [...own, ...recorded].map(e => ({ bodyBytes: e.bodyBytes, ts: e.ts }))
}
// Yields [index, trimmed-line] for every line of `lines` outside a fenced code block (fence lines themselves and everything between a pair of them are skipped). Shared by every heading/marker scanner below so the fence-toggle logic can't drift between them.
function* contentLineEntries(lines: string[]): Generator<[index: number, stripped: string]> {
let inCodeBlock = false
for (let i = 0; i < lines.length; i++) {
const stripped = lines[i]!.trim()
if (isCodeFenceDelimiter(stripped)) {
inCodeBlock = !inCodeBlock
continue
}
if (!inCodeBlock) yield [i, stripped]
}
}
// Returns the ATX heading level (1-6) for `stripped` if it is a heading line with a non-empty title, or 0 otherwise. Shared by extractNamedSection's heading matcher and collectSectionBody's boundary check so both agree on what counts as a heading.
function headingLevel(stripped: string): number {
const match = stripped.match(/^(#{1,6}) (.*)$/)
if (!match) return 0
return match[2]!.trim() ? match[1]!.length : 0
}
// Collects `lines` from `startIdx` up to (not including) the next heading whose level is <= `matchedLevel` and isn't itself inside a fenced code block, so an H2 section still contains its H3 children while stopping at the next H2 or H1. Shared by extractNamedSection/extractChecklistSection, whose "gather this section's body" loops were otherwise byte-identical apart from the start index.
function collectSectionBody(lines: string[], startIdx: number, matchedLevel: number): string[] {
const bodyLines: string[] = []
let inBodyCodeBlock = false
for (let j = startIdx; j < lines.length; j++) {
const stripped = lines[j]!.trim()
if (isCodeFenceDelimiter(stripped)) {
inBodyCodeBlock = !inBodyCodeBlock
}
if (!inBodyCodeBlock) {
const level = headingLevel(stripped)
if (level >= 1 && level <= matchedLevel) break
}
bodyLines.push(lines[j]!)
}
return bodyLines
}
export function extractCompactFromMarker(body: string): string | null {
if (!body || !body.includes(COMPACT_END_MARKER)) {
return null
}
const lines = body.split('\n')
for (const [i, stripped] of contentLineEntries(lines)) {
if (stripped === COMPACT_END_MARKER) {
const preMarker = lines.slice(0, i).join('\n').trim()
return preMarker || null
}
}
return null
}
export function extractH2Headings(body: string): string[] {
if (!body) return []
const headings: string[] = []
for (const [, stripped] of contentLineEntries(body.split('\n'))) {
if (stripped.startsWith('## ') && stripped.length > 3) {
headings.push(stripped.slice(3).trim())
}
}
return headings
}
export function extractAllHeadings(body: string, maxLevel: number = 3): Array<[level: number, title: string]> {
if (!body) return []
const headings: Array<[number, string]> = []
for (const [, stripped] of contentLineEntries(body.split('\n'))) {
if (!stripped.startsWith('#')) continue
const level = stripped.length - stripped.replace(/^#+/, '').length
if (level < 2 || level > maxLevel) {
continue
}
const title = stripped.slice(level).trim()
if (title) {
headings.push([level, title])
}
}
return headings
}
function hasLiteralSkillHeading(lines: string[], candidate: string): boolean {
const wanted = stripLower(candidate)
for (const [, stripped] of contentLineEntries(lines)) {
const level = headingLevel(stripped)
if (level >= 1 && level <= 3 && stripLower(stripped.slice(level)) === wanted) return true
}
return false
}
export function extractNamedSection(body: string, heading: string): string | null {
if (!body || !heading) return null
const lines = body.split('\n')
const [baseHeading, ordinal] = parseSkillSectionSpec(heading, (candidate) =>
hasLiteralSkillHeading(lines, candidate),
)
const headingLower = stripLower(baseHeading)
let matchCount = 0
let startIdx = -1
let matchedLevel = 0
for (const [i, stripped] of contentLineEntries(lines)) {
const level = headingLevel(stripped)
if (level >= 1 && level <= 3) {
const headingText = stripLower(stripped.slice(level))
if (headingText === headingLower) {
matchCount++
if (matchCount === ordinal) {
startIdx = i + 1
matchedLevel = level
break
}
}
}
}
if (startIdx === -1) return null
const text = collectSectionBody(lines, startIdx, matchedLevel).join('\n').trim()
return text || null
}
export function extractChecklistSection(body: string): string | null {
if (!body) return null
const checklistHeadings = ['checklist', 'check list', 'to-do', 'todo']
const lines = body.split('\n')
let bestPriority = checklistHeadings.length
let bestStart = -1
for (const [i, stripped] of contentLineEntries(lines)) {
if (stripped.startsWith('## ') && stripped.length > 3) {
const headingText = stripLower(stripped.slice(3))
for (let p = 0; p < checklistHeadings.length; p++) {
if (headingText.startsWith(checklistHeadings[p]!)) {
if (p < bestPriority) {
bestPriority = p
bestStart = i
}
break
}
}
}
}
if (bestStart === -1) return null
const bodyLines = collectSectionBody(lines, bestStart + 1, 2)
let text = bodyLines.join('\n').trim()
const maxChars = 2000
if (text.length > maxChars) {
const cut = maxChars - 1
text = text.slice(0, cut).trimEnd() + '…'
}
return text || null
}
export async function listOutputs(): Promise<SkillMeta[]> {
try {
const dir = skillOutputsDir()
const entries = await fs.readdir(dir, { withFileTypes: true })
const metas: SkillMeta[] = []
for (const entry of entries) {
if (!entry.isFile() || !entry.name.endsWith('.meta')) {
continue
}
try {
const content = await fs.readFile(resolve(dir, entry.name), 'utf-8')
const meta = JSON.parse(content) as SkillMeta
metas.push(meta)
} catch {
continue
}
}
return metas
} catch {
return []
}
}
/** Return true when a skill body for *skillName* was already cached under *sessionId* earlier this session (a stored outputId carries this session's fragment and name). The pre-skill hook uses this to advise recall over a wasteful full re-load. A body another session stored first counts through this session's load record (see {@link SkillLoadRecord}), so the dedup no longer hides a load. */
export async function hasSessionOutput(sessionId: string, skillName: string): Promise<boolean> {
try {
if (!sessionId) return false
const name = safeSkillName(skillName)
if (!name) return false
// Exact match on the stored skillName field (not a filename-derived prefix): a raw outputId.startsWith(prefix) check let a shorter name (e.g. 'ralph-loop') falsely match a differently-named skill whose outputId happens to start with the same literal text (e.g. 'ralph-loop-extended'). Comparing the structured field instead of the flattened filename eliminates that class of collision entirely.
return (await sessionLoads(safeSessionFragment(sessionId), name)).length > 0
} catch {
return false
}
}
/** Byte size of the body that a same-session re-load of *skillName* would have re-injected, or null if no matching cached output exists. Mirrors {@link hasSessionOutput}'s session+name matching exactly (same fields, same `.startsWith` prefix check) so the two never disagree on whether a match exists -- this just also returns the counterfactual byte count instead of a bare boolean. `bodyBytes` on the stored meta is the full pre-truncation size (see storeOutput), i.e. the real re-injection cost, not the on-disk cap. When multiple matches exist (e.g. the skill was reloaded with different content this session), the most recently stored one is used, since that is the body a fresh re-load would actually be recalling. */
export async function sessionOutputBodyBytes(sessionId: string, skillName: string): Promise<number | null> {
try {
if (!sessionId) return null
const name = safeSkillName(skillName)
if (!name) return null
const matches = await sessionLoads(safeSessionFragment(sessionId), name)
if (matches.length === 0) return null
matches.sort((a, b) => b.ts - a.ts)
return matches[0]!.bodyBytes
} catch {
return null
}
}
export async function findCrossSessionEntry(skillName: string, contentSha: string): Promise<SkillMeta | null> {
const name = safeSkillName(skillName)
if (!name || !contentSha) return null
try {
const metas = await listOutputs()
for (const meta of metas) {
if (meta.skillName !== name || meta.contentSha !== contentSha) {
continue
}
const dir = skillOutputsDir()
const bodyPath = resolve(dir, `${meta.outputId}.txt`)
try {
const bodyExists = await fs
.access(bodyPath)
.then(() => true)
.catch(() => false)
if (bodyExists) {
return meta
}
} catch {
continue
}
}
} catch {
return null
}
return null
}
let lastStoreTs = 0
/** Date.now(), but strictly after the previous store in this process: listSkills keeps the newest version of a skill by ts, and two versions stored in one millisecond otherwise tie and fall back to directory order. */
function nextStoreTs(): number {
lastStoreTs = Math.max(Date.now(), lastStoreTs + 1)
return lastStoreTs
}
export async function storeOutput(
sessionId: string,
skillName: string,
body: string,
opts?: { sourcePath?: string }
): Promise<SkillMeta | null> {
try {
await ensureSkillsDir()
const name = safeSkillName(skillName)
if (!name) return null
const sha = contentHash(body)
const outId = outputIdFor(sessionId, skillName, sha)
const dir = skillOutputsDir()
const ts = nextStoreTs()
const existing = await findCrossSessionEntry(skillName, sha)
if (existing) {
// The body is already stored, by this session or another. Another session's copy is reused, and this session records its own load of it so the reload deny sees this session loaded the skill.
if (existing.outputId !== outId && sessionId) {
const record: Omit<SkillLoadRecord, 'loadId'> = {
skillName: name,
contentSha: sha,
bodyOutputId: existing.outputId,
bodyBytes: Buffer.byteLength(body, 'utf-8'),
ts,
}
await atomicWriteText(resolve(dir, `${outId}${LOAD_RECORD_EXT}`), JSON.stringify(record, null, 2))
}
return existing
}
// bodyBytes is deliberately the RAW pre-redaction size, not what actually lands on disk: it feeds sessionOutputBodyBytes, whose only consumer (preSkillHandler's session_hint deny credit) prices "the load that didn't happen" -- and a real reload's live path (postSkillHandler below) hands the model the raw body unredacted, never the cached copy. Sizing this off the redacted length would understate that counterfactual whenever a secret was actually stripped.
const bodyBytes = Buffer.byteLength(body, 'utf-8')
const truncated = bodyBytes > 256 * 1024
// Defense-in-depth funnel, mirroring disk_cache.ts's storeBlob(): redact before this body ever reaches disk. Fail-safe, not fail-open -- if the redaction pass itself throws, this propagates to the function's own outer try/catch below, which returns null without having written anything, exactly like every other failure path here (oversized name, write error).
const redactedBody = redactSecrets(body)
if (redactedBody.count > 0) recordStat('secret_redacted', 0, redactedBody.count, undefined, SKILLS_OUTPUT_SUBDIR)
// Truncate the redacted text, not the raw body: truncating raw text first and redacting the slice afterward could cut a secret pattern in half at the boundary and leave the remaining fragment unmatched.
let storedBody = redactedBody.text
if (truncated) {
const buf = Buffer.from(redactedBody.text, 'utf-8')
let truncStart = Math.max(0, buf.length - 262144)
// If truncStart is in the middle of a UTF-8 character, find a safe boundary.
if (truncStart < buf.length) {
const byte = buf[truncStart]!
// If this is a continuation byte (10xxxxxx), we're in the middle of a character.
if ((byte & 0xC0) === 0x80) {
// Walk backward to find the start of this character.
let charStart = truncStart - 1
while (charStart >= 0 && (buf[charStart]! & 0xC0) === 0x80) {
charStart--
}
if (charStart >= 0) {
// Determine the character length from the leading byte.
const leadByte = buf[charStart]!
let charLen = 1
if ((leadByte & 0x80) === 0) charLen = 1 // 0xxxxxxx (ASCII)
else if ((leadByte & 0xE0) === 0xC0) charLen = 2 // 110xxxxx
else if ((leadByte & 0xF0) === 0xE0) charLen = 3 // 1110xxxx
else if ((leadByte & 0xF8) === 0xF0) charLen = 4 // 11110xxx
// Skip this partial character by advancing to the next one.
truncStart = charStart + charLen
}
}
}
const truncBuf = buf.slice(truncStart)
storedBody = truncBuf.toString('utf-8')
}
await atomicWriteText(resolve(dir, `${outId}.txt`), storedBody)
const meta: SkillMeta = {
outputId: outId,
skillName: name,
contentSha: sha,
bodyBytes,
ts,
truncated,
sourcePath: opts?.sourcePath || '',
}
await atomicWriteText(resolve(dir, `${outId}.meta`), JSON.stringify(meta, null, 2))
pruneSkillOutputs()
return meta
} catch {
return null
}
}
export async function storeCompact(
sessionId: string,
skillName: string,
compactText: string,
sourceSha?: string
): Promise<void> {
try {
await ensureSkillsDir()
const name = safeSkillName(skillName)
if (!name) return
const safeSession = safeSessionFragment(sessionId)
const fileId = `${safeSession}@${sanitizeSkillId(name)}@compact`
const dir = skillOutputsDir()
// Same funnel as storeOutput above: this slice is extracted from the same raw body (extractCompactFromMarker) and gets inlined straight into a model-visible hook reply by preSkillHandler's oversized-first-load path, so it needs the same redaction storeOutput's persisted body gets. Redact before prepending the source_sha marker, so the marker itself (a content hash, not secret-shaped) is never a redaction target.
const redacted = redactSecrets(compactText)
if (redacted.count > 0) recordStat('secret_redacted', 0, redacted.count, undefined, SKILLS_OUTPUT_SUBDIR)
let text = redacted.text
if (sourceSha) {
text = `<!-- source_sha: ${sourceSha.slice(0, 12)} -->\n${text}`
}
await atomicWriteText(resolve(dir, fileId), text)
} catch {
// fail-soft
}
}
export async function getCompact(sessionId: string, skillName: string): Promise<string | null> {
try {
const name = safeSkillName(skillName)
if (!name) return null
const safeSession = safeSessionFragment(sessionId)
const fileId = `${safeSession}@${sanitizeSkillId(name)}@compact`
const dir = skillOutputsDir()
const path = resolve(dir, fileId)
try {
const text = await fs.readFile(path, 'utf-8')
return text.trim() ? text : null
} catch {
return null
}
} catch {
return null
}
}
// Exact '@'-delimited compact-cache suffix for a skill name, or null if the name is invalid. '@' cannot occur in a sanitized name (outside safeSkillName's charset), so matching this exact suffix (not a raw substring) can never match a differently-named skill whose sanitized name merely ends with this one's text (e.g. name 'loop' must not match a stored file for 'ralph-loop'). Shared by getCompactAnySession/getCompactAnySessionSync so the collision-safe matching logic can't drift between the two.
function compactSessionSuffix(skillName: string): string | null {
const name = safeSkillName(skillName)
return name ? `@${sanitizeSkillId(name)}@compact` : null
}
function matchesCompactSuffix(entryName: string, isFile: boolean, suffix: string): boolean {
return isFile && entryName.endsWith('@compact') && entryName.endsWith(suffix)
}
export async function getCompactAnySession(skillName: string): Promise<string | null> {
try {
const suffix = compactSessionSuffix(skillName)
if (!suffix) return null
const dir = skillOutputsDir()
const entries = await fs.readdir(dir, { withFileTypes: true })
for (const entry of entries) {
if (!matchesCompactSuffix(entry.name, entry.isFile(), suffix)) continue
try {
const text = await fs.readFile(resolve(dir, entry.name), 'utf-8')
if (text.trim()) return text
} catch {
continue
}
}
return null
} catch {
return null
}
}
// Synchronous sibling of getCompactAnySession for the hot pre-read path: first non-empty cached compact body for a skill across sessions, or null.
export function getCompactAnySessionSync(skillName: string): string | null {
try {
const suffix = compactSessionSuffix(skillName)
if (!suffix) return null
const dir = skillOutputsDir()
const entries = readdirSync(dir, { withFileTypes: true })
for (const entry of entries) {
if (!matchesCompactSuffix(entry.name, entry.isFile(), suffix)) continue
try {
const text = readFileSync(resolve(dir, entry.name), 'utf-8')
if (text.trim()) return text
} catch {
continue
}
}
return null
} catch {
return null
}
}
// Extract the source SHA from a cached compact's embedded comment (<!-- source_sha: <sha12> -->), returning the 12-char hex string or null if not found.
export function extractSourceShaFromCompact(compactText: string): string | null {
if (!compactText) return null
const match = compactText.match(/<!--\s*source_sha:\s*([a-f0-9]{12})\s*-->/)
return match ? match[1]! : null
}
// Determine staleness: return true if compact is stale, false if fresh, null if indeterminate (no compact, no source SHA in it, or body can't be resolved).
export function isCompactStale(compactText: string | null, skillName: string, currentBodySha: string): boolean | null {
if (!compactText) return null
const embeddedSha = extractSourceShaFromCompact(compactText)
if (!embeddedSha) return null
const currentSha = currentBodySha.slice(0, 12)
return embeddedSha !== currentSha
}
// Read or create hit count sidecar for a skill (<skillOutputsDir>/<sanitizeSkillId(name)>.hits), returning {count, lastTs}. Routes skillName through safeSkillName like every other cache-writing path in this file, so a name with characters unsafe for a filename (or a scoped name like 'apps/web:deploy') can't bypass validation and produce a cache key inconsistent with storeOutput/storeCompact.
export async function readSkillHits(skillName: string): Promise<{ count: number; lastTs: number }> {
try {
const name = safeSkillName(skillName)
if (!name) return { count: 0, lastTs: 0 }
const dir = skillOutputsDir()
const hitsFile = resolve(dir, `${sanitizeSkillId(name)}.hits`)
const content = await fs.readFile(hitsFile, 'utf-8').catch(() => null)
if (content) {
const parsed = JSON.parse(content) as { count: number; lastTs: number }
return parsed
}
} catch {
// ignore
}
return { count: 0, lastTs: 0 }
}
// Exclusive lock for incrementSkillHit's read-modify-write, so two concurrent processes/sessions incrementing the same skill's hit count at once can't both read the same pre-increment count and silently drop one hit. Directory creation is atomic on both POSIX and Windows, so an mkdir-based lock doubles as a cross-process mutex: the loser gets EEXIST.
//
// The retry budget must comfortably outlast a legitimately-held (non-stale) lock, not just a crashed one: under N-way same-process contention, a caller can be queued behind up to N-1 other callers' full critical sections before it ever gets a turn. A budget sized only for "wait out a slow disk op" (previously 20 attempts * 5ms = 100ms) can exhaust while the holder is still doing legitimate work, sending the caller down the unlocked fallback path below and reintroducing the exact lost-update race the lock exists to prevent -- reproduced directly via tests/skill_cache.test.ts's 5-way concurrency regression test under load. Sizing the budget to match SKILL_HIT_LOCK_STALE_MS means a caller only gives up once it has waited at least as long as it would take to detect and reclaim a genuinely abandoned lock, so ordinary contention (any number of legitimate concurrent holders finishing in bounded time) is never mistaken for exhaustion.
const SKILL_HIT_LOCK_RETRY_MS = 5
const SKILL_HIT_LOCK_STALE_MS = 5000
const SKILL_HIT_LOCK_MAX_ATTEMPTS = Math.ceil(SKILL_HIT_LOCK_STALE_MS / SKILL_HIT_LOCK_RETRY_MS)
// In-process mutex, keyed by lockPath: serializes concurrent callers within THIS process before any of them touch the filesystem-based lock below. That lock's staleness check (comparing the lock directory's mtime against SKILL_HIT_LOCK_STALE_MS) exists to arbitrate between separate OS processes and recover one that crashed mid-hold -- it is inherently a wall-clock heuristic. Two same-process callers polling that same heuristic against each other is a false positive waiting to happen: under severe CPU contention (many parallel test workers, a loaded CI box) this process can be scheduled off the CPU long enough that a live in-process holder's own critical section looks "stale" to another in-process waiter, letting that waiter steal the lock mid-write and drop the first caller's increment -- reproduced directly by tests/skill_cache.test.ts's 5-way concurrency regression test under full-suite load. Routing same-process callers through this queue first means they never reach that wall-clock check against each other at all: plain JS promise chaining orders them deterministically no matter how delayed the underlying I/O or timers get. Cross-process contention (the case the mkdir lock actually exists for) is untouched -- this only removes the false-positive path this process can hit against itself.
const inProcessHitLockQueues = new Map<string, Promise<unknown>>()
function runExclusiveInProcess<T>(key: string, fn: () => Promise<T>): Promise<T> {
const prior = inProcessHitLockQueues.get(key) ?? Promise.resolve()
const run = prior.then(fn, fn)
// Swallow rejection in the queued tail so a failed caller never wedges the next one behind it; the real result/rejection still flows to this call's own caller via `run`.
inProcessHitLockQueues.set(
key,
run.then(
() => undefined,
() => undefined,
),
)
return run
}
// Acquires the lock directory for hitsFile, reclaiming a lock older than SKILL_HIT_LOCK_STALE_MS as abandoned (left behind by a crashed process) instead of wedging future increments forever. Returns false once every retry is exhausted so the caller can fall back to an unlocked increment rather than dropping the hit -- see incrementSkillHit.
async function acquireSkillHitLock(lockPath: string): Promise<boolean> {
for (let attempt = 0; attempt < SKILL_HIT_LOCK_MAX_ATTEMPTS; attempt++) {
try {
await fs.mkdir(lockPath)
return true
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return false
try {
const st = await fs.stat(lockPath)
if (Date.now() - st.mtimeMs > SKILL_HIT_LOCK_STALE_MS) {
await fs.rmdir(lockPath).catch(() => {})
continue
}
} catch {
// Lock vanished between the failed mkdir and this stat -- retry immediately.
continue
}
await new Promise((r) => setTimeout(r, SKILL_HIT_LOCK_RETRY_MS))
}
}
return false
}
// Increment hit count sidecar for a skill. Same safeSkillName routing as readSkillHits. The read-modify-write is guarded by acquireSkillHitLock; if the lock can't be acquired, the increment is skipped rather than falling back to an unprotected read-modify-write -- see acquireSkillHitLock's TOCTOU rationale below.
export async function incrementSkillHit(skillName: string): Promise<void> {
try {
const name = safeSkillName(skillName)
if (!name) return
await ensureSkillsDir()
const dir = skillOutputsDir()
const hitsFile = resolve(dir, `${sanitizeSkillId(name)}.hits`)
const lockPath = `${hitsFile}.lock`
await runExclusiveInProcess(lockPath, async () => {
const locked = await acquireSkillHitLock(lockPath)
// If the lock could not be acquired (another holder never released it, or the mkdir/rmdir pair raced on a filesystem where directory deletion isn't instantly visible to a subsequent create -- observed on Windows), skip the increment rather than falling back to an unprotected read-modify-write: that fallback was the exact TOCTOU race the lock exists to prevent, just gated behind a rarer trigger.
if (!locked) return
try {
const hits = await readSkillHits(name)
hits.count++
hits.lastTs = Date.now()
await atomicWriteText(hitsFile, JSON.stringify(hits, null, 2))
} finally {
await fs.rmdir(lockPath).catch(() => {})
}
})
} catch {
// fail-soft
}
}
// Format age in milliseconds as human-readable string (e.g., "5m", "2h", "1d").
export function formatAge(ageMs: number): string {
const s = Math.floor(ageMs / 1000)
if (s < 60) return `${s}s`
const m = Math.floor(s / 60)
if (m < 60) return `${m}m`
const h = Math.floor(m / 60)
if (h < 24) return `${h}h`
const d = Math.floor(h / 24)
return `${d}d`
}
export async function listSkills(sessionId?: string): Promise<CachedSkillInfo[]> {
try {
// Sort newest-first before the dedup pass below: fs.readdir's returned order is filesystem-dependent (commonly filename order, not chronological), and the outputId's sha suffix is unrelated to recency. Without this sort, the dedup-by-first-seen loop below could pick an arbitrary older version of a multiply-cached skill instead of the newest.
const metas = (await listOutputs()).sort((a, b) => b.ts - a.ts)
const results: CachedSkillInfo[] = []
const seen = new Set<string>()
for (const meta of metas) {
// Boundary-checked prefix match (the trailing '-' matters): without it, a session id whose safe fragment is a strict string-prefix of another session's fragment (e.g. 'sess-a' vs 'sess-ab') would conflate the two -- 'sess-ab-skill-sha'.startsWith('sess-a') is true even though they're different sessions. Mirrors hasSessionOutput's identical guard.
if (sessionId && !meta.outputId.startsWith(`${safeSessionFragment(sessionId)}-`)) {
continue
}
if (seen.has(meta.skillName)) continue
seen.add(meta.skillName)
const dir = skillOutputsDir()
// Recover the session fragment by stripping the known '-<name>-<sha>' suffix from the tail of outputId, rather than splitting on the first hyphen: a session id's safe fragment (up to 16 chars of [a-zA-Z0-9_-]) commonly contains its own hyphens (e.g. a UUID), so splitting on the first '-' truncated the fragment early and desynced compactFileId from the path storeCompact actually wrote.
const sanitizedName = sanitizeSkillId(meta.skillName)
const outputSuffix = `-${sanitizedName}-${meta.contentSha}`
const safeSession = meta.outputId.endsWith(outputSuffix)
? meta.outputId.slice(0, meta.outputId.length - outputSuffix.length)
: safeSessionFragment(meta.outputId.split('-')[0]!)
const compactFileId = `${safeSession}@${sanitizedName}@compact`
let compactLen = 0
let compactText = ''
try {
const stat = await fs.stat(resolve(dir, compactFileId))
compactLen = stat.size
compactText = await fs.readFile(resolve(dir, compactFileId), 'utf-8').catch(() => '')
} catch {
compactLen = 0
}
const hasMarker = extractCompactFromMarker(
await fs.readFile(resolve(dir, `${meta.outputId}.txt`), 'utf-8').catch(() => '')
) !== null
const compactStale = isCompactStale(compactText, meta.skillName, meta.contentSha)
const { count: hitCount } = await readSkillHits(meta.skillName)
const ageMs = Date.now() - meta.ts
results.push({
name: meta.skillName,
bodyLen: meta.bodyBytes,
compactLen,
hasMarker,
compactStale,
hitCount,
ageMs,
})
}
return results
} catch {
return []
}
}
export async function getAllCachedSkills(sessionId?: string): Promise<CachedSkillInfo[]> {
return listSkills(sessionId)
}
export async function getSkillFilePath(skillName: string): Promise<string | null> {
try {
const name = safeSkillName(skillName)
if (!name) return null
const metas = await listOutputs()
for (const meta of metas) {
if (meta.skillName === name && meta.sourcePath) {
return meta.sourcePath
}
}
// Cache miss: fall back to the on-disk skill install at ~/.claude/skills/<name>/SKILL.md,
// or Copilot CLI's project/personal skill roots (e.g. ~/.copilot/skills/<name>/SKILL.md),
// so skill-compact/skill-body/skill-section resolve for any installed skill even when it was never loaded via the Skill hook this session.
const claudePath = await installedSkillPath(name)
if (claudePath) return claudePath
return await copilotSkillPath(name, process.cwd())
} catch {
return null
}
}
// Resolve a `plugin:skill`-scoped name's on-disk SKILL.md via `~/.claude/plugins/installed_plugins.json`. Plugin skills live at `<installPath>/skills/<skillSlug>/SKILL.md`, where `<installPath>` (e.g. `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>`) is only discoverable through this manifest -- unlike ~/.claude/skills/<name>/, there is no fixed directory shape to guess. The manifest's `plugins` map is keyed `<pluginName>@<marketplace>`, one or more entries per key (one per install scope); every entry whose plugin-name segment matches is tried until one resolves. Fails soft (null) on a missing/malformed manifest or an unmatched plugin, matching every other cache-reading path in this file.
async function resolvePluginSkillPath(pluginName: string, skillSlug: string): Promise<string | null> {
const manifestPath = _pluginsManifestPathOverride ?? resolve(claudeConfigDir(), 'plugins', 'installed_plugins.json')
let raw: string
try {
raw = await fs.readFile(manifestPath, 'utf8')
} catch {
return null
}
let parsed: unknown
try {
parsed = JSON.parse(raw)
} catch {
return null
}
if (typeof parsed !== 'object' || parsed === null) return null
const plugins = (parsed as Record<string, unknown>)['plugins']
if (typeof plugins !== 'object' || plugins === null) return null
for (const [key, entries] of Object.entries(plugins as Record<string, unknown>)) {
if (key !== pluginName && !key.startsWith(pluginName + '@')) continue
if (!Array.isArray(entries)) continue
for (const entry of entries) {
if (typeof entry !== 'object' || entry === null) continue
const installPath = (entry as Record<string, unknown>)['installPath']
if (typeof installPath !== 'string' || installPath === '') continue
const diskPath = resolve(installPath, 'skills', skillSlug, 'SKILL.md')
try {
await fs.access(diskPath)
return diskPath
} catch {
continue
}
}
}
return null
}
// Resolve the on-disk install path of a skill (~/.claude/skills/<name>/SKILL.md, or a plugin-scoped `plugin:skill`'s manifest-resolved path) if it exists, else null. `name` is sanitized by safeSkillName (no slash or dot), so there is no path-traversal risk. Shared by getSkillFilePath's cache-miss fallback and the Skill hook's sourcePath resolution.
export async function installedSkillPath(skillName: string): Promise<string | null> {
const name = safeSkillName(skillName)
if (!name) return null
const colonIdx = name.indexOf(':')
if (colonIdx > 0 && colonIdx < name.length - 1) {
const pluginPath = await resolvePluginSkillPath(name.slice(0, colonIdx), name.slice(colonIdx + 1))
if (pluginPath !== null) return pluginPath
}
const diskPath = resolve(skillsSourceDir(), name, 'SKILL.md')
try {
await fs.access(diskPath)
return diskPath
} catch {
return null
}
}
/** Evict skill-output entries (paired .meta/.txt files, keyed by each entry's stored `ts`) beyond maxCount or older than maxAgeMs. Sync, matching prune-cache / clean-cache's synchronous CLI path (mirrors getCompactAnySessionSync's sync sibling pattern for the same reason). This directory doesn't use disk_cache.ts's generic pruneBlobs: that helper only recognizes single self-contained '<id>.json' blobs, but a skill output is a group of related files (.meta metadata + .txt body) that must be evicted together, so it needs its own eviction pass. Sidecar .hits/@compact files are left in place — they're small and self-heal via storeCompact/incrementSkillHit's own atomic writes on next access. Returns the number of evicted entries (not the number of files removed). */
export function pruneSkillOutputs(
maxCount: number = DEFAULT_MAX_COUNT,
maxAgeMs: number = DEFAULT_MAX_AGE_MS,
): number {
const dir = skillOutputsDir()
let removed = 0
try {
if (!existsSync(dir)) return 0
const cutoff = Date.now() - maxAgeMs
const entries: Array<{ outputId: string; ts: number }> = []
for (const file of readdirSync(dir)) {
if (!file.endsWith('.meta')) continue
const outputId = file.slice(0, -'.meta'.length)
let ts: number
try {
const parsed = JSON.parse(readFileSync(resolve(dir, file), 'utf-8')) as SkillMeta
ts = parsed.ts
} catch {
try {
ts = statSync(resolve(dir, file)).mtimeMs
} catch {
continue
}
}
entries.push({ outputId, ts })
}
const removeEntry = (outputId: string): void => {
for (const ext of ['.meta', '.txt']) {
try {
unlinkSync(resolve(dir, `${outputId}${ext}`))
} catch {
// already gone or never existed
}
}
removed++
}
const kept: Array<{ outputId: string; ts: number }> = []
for (const entry of entries) {
if (entry.ts < cutoff) {
removeEntry(entry.outputId)
} else {
kept.push(entry)
}
}
if (kept.length > maxCount) {
kept.sort((a, b) => a.ts - b.ts)
for (const entry of kept.slice(0, kept.length - maxCount)) {
removeEntry(entry.outputId)
}
}
// A session load record goes when its shared body is gone or it has aged out. It is not an entry of its own, so it neither counts toward maxCount nor adds to the returned count.
for (const record of readLoadRecordsSync(dir)) {
if (record.ts >= cutoff && existsSync(resolve(dir, `${record.bodyOutputId}.meta`))) continue
try {
unlinkSync(resolve(dir, `${record.loadId}${LOAD_RECORD_EXT}`))
} catch {
// already gone
}
}
} catch {
return removed
}
return removed
}