@agentpro/scroll 0.0.0-stage → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +55 -0
  2. package/LICENSE +21 -0
  3. package/README.md +293 -2
  4. package/SPEC.md +1079 -0
  5. package/bin/scroll.js +8 -0
  6. package/docs/prompt-caching.md +128 -0
  7. package/index.js +33 -0
  8. package/lib/audit.js +358 -0
  9. package/lib/auth.js +849 -0
  10. package/lib/chat-sdk/admin-controller.js +289 -0
  11. package/lib/chat-sdk/debouncer.js +94 -0
  12. package/lib/chat-sdk/group-grants.js +150 -0
  13. package/lib/chat-sdk/index.js +222 -0
  14. package/lib/chat-sdk/long-task-runner.js +413 -0
  15. package/lib/chat-session.js +1788 -0
  16. package/lib/chat-telemetry.js +557 -0
  17. package/lib/codex-app-server.js +851 -0
  18. package/lib/digest.js +112 -0
  19. package/lib/effects.js +157 -0
  20. package/lib/eval.js +408 -0
  21. package/lib/grounding.js +356 -0
  22. package/lib/installers.js +176 -0
  23. package/lib/knowledge.js +335 -0
  24. package/lib/ledger.js +38 -0
  25. package/lib/loop.js +197 -0
  26. package/lib/mcp-client.js +926 -0
  27. package/lib/memory-cli.js +66 -0
  28. package/lib/memory-tracker.js +1472 -0
  29. package/lib/memory.js +1279 -0
  30. package/lib/people-cli.js +81 -0
  31. package/lib/people.js +534 -0
  32. package/lib/permissions.js +272 -0
  33. package/lib/providers.js +1572 -0
  34. package/lib/runtime.js +928 -0
  35. package/lib/sandbox.js +744 -0
  36. package/lib/scheduler.js +402 -0
  37. package/lib/scroll.js +1225 -0
  38. package/lib/skill-cli.js +120 -0
  39. package/lib/skill-eval.js +156 -0
  40. package/lib/skills.js +860 -0
  41. package/lib/style.js +126 -0
  42. package/lib/tool-retriever.js +489 -0
  43. package/lib/tools.js +1833 -0
  44. package/lib/user.js +711 -0
  45. package/lib/vault.js +151 -0
  46. package/package.json +88 -4
  47. package/templates/agent/IDENTITY.md +56 -0
  48. package/templates/agent/SOUL.md +23 -0
  49. package/templates/agent/TOOLS.md +25 -0
  50. package/templates/agent/evals/case-02-citation-discipline.md +29 -0
  51. package/templates/agent/evals/case-03-boundary.md +27 -0
  52. package/templates/agent/evals/case-example.md +43 -0
  53. package/templates/agent/hard-rules.md +11 -0
  54. package/templates/agent/memory/lessons.md +5 -0
  55. package/templates/agent/memory/log/.gitkeep +0 -0
  56. package/templates/external-safety-contract.md +5 -0
  57. package/templates/long-task-planner.md +17 -0
  58. package/templates/work/LOOP.md +37 -0
  59. package/templates/work/WORK.md +50 -0
  60. package/types/chat.d.ts +61 -0
  61. package/types/index.d.ts +112 -0
package/lib/skills.js ADDED
@@ -0,0 +1,860 @@
1
+ // SCROLL — skills (v1.8 §34–§36). Zero-dep.
2
+ //
3
+ // A skill is a folder with a SKILL.md in the open Agent Skills format (agentskills.io): YAML
4
+ // frontmatter (`name`, `description`, optional `license`, `compatibility`, `metadata`,
5
+ // `allowed-tools`) and a markdown body, plus optional scripts/, references/, assets/.
6
+ // The same folder works in many agent runtimes, so an agent built on SCROLL can use skills written
7
+ // for other tools without copying or editing them.
8
+ //
9
+ // What this module does — all of it in code, none of it in a prompt:
10
+ // §34 load find skills in ordered sources (agent → repo → read-only external folders), resolve
11
+ // name clashes by precedence, hide what the agent cannot run, and give the agent a
12
+ // byte-stable index for the cached prefix plus two tools: skill_list and skill_view.
13
+ // §35 compat read which tools a skill names (its own declaration, or the tool names it uses),
14
+ // map foreign tool names to SCROLL capabilities, and decide ok | partial | hidden.
15
+ // A human can correct the machine in a sidecar file; the skill itself is never edited.
16
+ // §36 check validate the format; scan every text file for secrets, exfiltration, remote code,
17
+ // destructive commands, hidden text and prompt injection. A blocked skill never
18
+ // reaches the index or the tools, and there is no flag to force it in.
19
+ //
20
+ // The model only ever sees what passed. Everything the model can reach is re-checked at read time,
21
+ // so a file that changed after the session started is scanned again before it is served.
22
+ import fs from 'node:fs';
23
+ import os from 'node:os';
24
+ import path from 'node:path';
25
+ import crypto from 'node:crypto';
26
+ import { parseYaml } from './scroll.js';
27
+ import { tokens } from './memory.js';
28
+
29
+ const sha = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
30
+ const arr = (x) => (Array.isArray(x) ? x : x == null || x === '' ? [] : [x]);
31
+ const approxTokens = (s) => Math.ceil(String(s || '').length / 4);
32
+
33
+ export const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
34
+ export const LIMITS = {
35
+ name: 64, description: 1024, compatibility: 500, bodyLines: 500,
36
+ skillMdBytes: 1024 * 1024, // a SKILL.md larger than this is refused
37
+ viewBytes: 256 * 1024, // largest file skill_view serves
38
+ bodyChars: 120000, // SKILL.md body served by skill_view (truncated beyond)
39
+ scanFiles: 200, scanFileBytes: 512 * 1024,
40
+ maxDepth: 6, maxSkillsPerSource: 5000,
41
+ indexSkills: 150, indexTokens: 6000, // §34.6
42
+ };
43
+ export const TRUST_LEVELS = ['builtin', 'trusted', 'community', 'untrusted'];
44
+ const SEVERITY = { low: 0, medium: 1, high: 2, critical: 3 };
45
+ // the lowest severity that blocks a skill, per trust level (§36.2)
46
+ export const BLOCK_AT = { builtin: 'critical', trusted: 'critical', community: 'high', untrusted: 'medium' };
47
+
48
+ // ── frontmatter ───────────────────────────────────────────────────────────────────────────────
49
+ // SCROLL's own YAML reader is a deliberate subset. Real SKILL.md files use more: block scalars
50
+ // (`description: >-` then indented lines), escaped double-quoted strings, plain scalars that wrap
51
+ // onto the next line, and flow lists that span lines. Those are folded into single values here,
52
+ // then the rest goes through the shared reader.
53
+ const HOLD = (i) => `"\u0000S${i}\u0000"`;
54
+ const HELD_RE = /^\u0000S(\d+)\u0000$/;
55
+ function restore(v, held) {
56
+ if (typeof v === 'string') { const m = v.match(HELD_RE); return m ? held[Number(m[1])] : v; }
57
+ if (Array.isArray(v)) return v.map((x) => restore(x, held));
58
+ if (v && typeof v === 'object') { const o = {}; for (const [k, x] of Object.entries(v)) o[k] = restore(x, held); return o; }
59
+ return v;
60
+ }
61
+ const indentOf = (s) => s.match(/^[ \t]*/)[0].length;
62
+ function closingQuote(s, q, from) {
63
+ for (let i = from; i < s.length; i++) {
64
+ if (q === '"' && s[i] === '\\') { i++; continue; }
65
+ if (s[i] === q) { if (q === "'" && s[i + 1] === "'") { i++; continue; } return i; }
66
+ }
67
+ return -1;
68
+ }
69
+ function unquote(q, inner) {
70
+ if (q === "'") return inner.replace(/''/g, "'");
71
+ try { return JSON.parse(`"${inner.replace(/\\'/g, "'").replace(/\\\//g, '/').replace(/\t/g, '\\t')}"`); }
72
+ catch { return inner.replace(/\\"/g, '"').replace(/\\\\/g, '\\'); }
73
+ }
74
+ function balance(s) {
75
+ let d = 0, q = null;
76
+ for (let i = 0; i < s.length; i++) {
77
+ const ch = s[i];
78
+ if (q) { if (ch === '\\' && q === '"') { i++; continue; } if (ch === q) q = null; continue; }
79
+ if (ch === '"' || ch === "'") q = ch; else if (ch === '[' || ch === '{') d++; else if (ch === ']' || ch === '}') d--;
80
+ }
81
+ return d;
82
+ }
83
+ export function parseSkillYaml(src) {
84
+ const lines = String(src).split('\n');
85
+ const out = [], held = [];
86
+ const hold = (s) => { held.push(s); return HOLD(held.length - 1); };
87
+ for (let i = 0; i < lines.length; i++) {
88
+ const line = lines[i];
89
+ const m = line.match(/^([ \t]*)([A-Za-z0-9_][A-Za-z0-9_.\- ]*?):(?:[ \t]+(.*))?$/);
90
+ if (!m) { out.push(line); continue; }
91
+ const [, ind, key] = m; const kInd = ind.length;
92
+ let val = (m[3] || '').trim();
93
+ const following = () => { const got = []; let j = i + 1; while (j < lines.length && (lines[j].trim() === '' || indentOf(lines[j]) > kInd)) got.push(lines[j++]); return got; };
94
+ const blk = val.match(/^([|>])([+-]?)(\d*)[ \t]*(?:#.*)?$/);
95
+ if (blk) {
96
+ const body = following(); i += body.length;
97
+ while (body.length && body[body.length - 1].trim() === '') body.pop();
98
+ const first = body.find((l) => l.trim() !== '');
99
+ const cut = blk[3] ? kInd + Number(blk[3]) : (first ? indentOf(first) : 0);
100
+ const ls = body.map((l) => (l.trim() === '' ? '' : l.slice(Math.min(cut, indentOf(l)))));
101
+ let text;
102
+ if (blk[1] === '|') text = ls.join('\n');
103
+ else { text = ''; for (const l of ls) { if (l === '') text += '\n'; else text += (text && !text.endsWith('\n') ? ' ' : '') + l; } }
104
+ if (blk[2] !== '-') text += '\n';
105
+ out.push(`${ind}${key}: ${hold(text)}`);
106
+ continue;
107
+ }
108
+ if (val[0] === '"' || val[0] === "'") {
109
+ const q = val[0]; let acc = val; let end = closingQuote(acc, q, 1);
110
+ while (end < 0 && i + 1 < lines.length) { i++; acc += ' ' + lines[i].trim(); end = closingQuote(acc, q, 1); }
111
+ if (end < 0) throw new Error(`unterminated ${q === '"' ? 'double' : 'single'}-quoted value for "${key.trim()}"`);
112
+ out.push(`${ind}${key}: ${hold(unquote(q, acc.slice(1, end)))}`);
113
+ continue;
114
+ }
115
+ if (val[0] === '[' || val[0] === '{') {
116
+ let acc = val;
117
+ while (balance(acc) > 0 && i + 1 < lines.length) { i++; acc += ' ' + lines[i].trim(); }
118
+ out.push(`${ind}${key}: ${acc}`);
119
+ continue;
120
+ }
121
+ if (val !== '' && !val.startsWith('#')) {
122
+ const more = []; let j = i + 1;
123
+ while (j < lines.length && lines[j].trim() !== '' && indentOf(lines[j]) > kInd) more.push(lines[j++].trim());
124
+ if (more.length) { i = j - 1; out.push(`${ind}${key}: ${hold([val, ...more].join(' '))}`); continue; }
125
+ }
126
+ out.push(line);
127
+ }
128
+ const parsed = parseYaml(out.join('\n'));
129
+ return restore(parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}, held);
130
+ }
131
+
132
+ export function parseSkillMd(raw) {
133
+ const text = String(raw).replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
134
+ const m = text.match(/^---[ \t]*\n(?:([\s\S]*?)\n)?---[ \t]*(?:\n|$)/);
135
+ if (!m) return { frontmatter: null, body: text, error: 'SKILL.md has no YAML frontmatter (--- … ---)' };
136
+ const body = text.slice(m[0].length).replace(/^\n+/, '');
137
+ try { return { frontmatter: parseSkillYaml(m[1] || ''), body, error: null }; }
138
+ catch (e) { return { frontmatter: null, body, error: `frontmatter: ${e.message}` }; }
139
+ }
140
+
141
+ const oneLine = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
142
+
143
+ // ── §36.1 validation ──────────────────────────────────────────────────────────────────────────
144
+ // strict = a skill this repo ships (agent or repo source): a SHOULD of the format is an error here.
145
+ // External skills belong to someone else: the same findings are warnings, and only what makes a
146
+ // skill unusable (no name, no description, a name that cannot be addressed) keeps it out.
147
+ export function validateSkill(skill, { strict = false } = {}) {
148
+ const errors = [], warnings = [];
149
+ const should = (msg) => (strict ? errors : warnings).push(msg);
150
+ if (skill.parseError) return { errors: [skill.parseError], warnings };
151
+ const fm = skill.frontmatter || {};
152
+ const dirName = path.basename(skill.dir || '');
153
+ if (typeof fm.name !== 'string' || !fm.name.trim()) errors.push('frontmatter: `name` is required');
154
+ else if (!SKILL_NAME_RE.test(fm.name) || fm.name.length > LIMITS.name) errors.push(`name "${oneLine(fm.name).slice(0, 80)}" must be 1-${LIMITS.name} lowercase letters, digits and single hyphens`);
155
+ else if (dirName && fm.name !== dirName) should(`name "${fm.name}" differs from its folder "${dirName}"`);
156
+ if (typeof fm.description !== 'string' || !fm.description.trim()) errors.push('frontmatter: `description` is required (what the skill does and when to use it)');
157
+ else {
158
+ if (fm.description.length > LIMITS.description) should(`description is ${fm.description.length} characters (max ${LIMITS.description})`);
159
+ if (/<\/?[A-Za-z][^>]*>/.test(fm.description)) should('description contains XML/HTML tags');
160
+ }
161
+ if (fm.compatibility != null && String(fm.compatibility).length > LIMITS.compatibility) should(`compatibility is longer than ${LIMITS.compatibility} characters`);
162
+ if (fm.metadata != null && (typeof fm.metadata !== 'object' || Array.isArray(fm.metadata))) should('metadata must be a map');
163
+ if (strict && typeof fm.name === 'string' && /anthropic|claude/.test(fm.name)) warnings.push(`name "${fm.name}" uses a vendor's reserved word; some runtimes refuse it`);
164
+ const body = skill.body || '';
165
+ const nLines = body.split('\n').length;
166
+ if (nLines > LIMITS.bodyLines) warnings.push(`SKILL.md body is ${nLines} lines; keep it under ${LIMITS.bodyLines} and move detail to references/`);
167
+ if (skill.dir) {
168
+ for (const ref of fileRefs(body)) {
169
+ if (ref.includes('\\')) { warnings.push(`reference "${ref}" uses backslashes; use forward slashes`); continue; }
170
+ const target = path.resolve(skill.dir, ref);
171
+ if (!target.startsWith(path.resolve(skill.dir) + path.sep)) { should(`reference "${ref}" points outside the skill folder`); continue; }
172
+ if (!fs.existsSync(target)) { should(`reference "${ref}" does not exist`); continue; }
173
+ if (strict && /\.md$/i.test(ref)) {
174
+ let inner = ''; try { inner = fs.readFileSync(target, 'utf8'); } catch { /* unreadable */ }
175
+ const nested = fileRefs(inner).filter((r) => /\.md$/i.test(r));
176
+ if (nested.length) warnings.push(`reference "${ref}" links further files (${nested.slice(0, 3).join(', ')}); keep references one level deep from SKILL.md`);
177
+ }
178
+ }
179
+ }
180
+ return { errors, warnings };
181
+ }
182
+ // relative file references in markdown: [text](path) links and `scripts/…` / `references/…` / `assets/…` spans
183
+ function fileRefs(body) {
184
+ const out = new Set();
185
+ for (const m of String(body).matchAll(/\]\(([^)\s#?]+)(?:[#?][^)]*)?\)/g)) {
186
+ const r = m[1];
187
+ if (/^([a-z][a-z0-9+.-]*:|\/|#|~)/i.test(r) || r.includes('{') || r.includes('<')) continue;
188
+ out.add(r.replace(/^\.\//, ''));
189
+ }
190
+ for (const m of String(body).matchAll(/`((?:\.\/)?(?:scripts|references|assets)[\\/][^`\s*?<>{}$]+)`/g)) out.add(m[1].replace(/^\.\//, ''));
191
+ return [...out];
192
+ }
193
+
194
+ // ── §36.2 security scan ───────────────────────────────────────────────────────────────────────
195
+ // Rules are data. Each names what it catches; severity decides, with the source's trust, whether
196
+ // the skill is blocked or only reported. Findings never carry the matched secret itself.
197
+ const SECRET_RES = [
198
+ /\bsk-(?:ant-|proj-|live_|test_)?[A-Za-z0-9_-]{24,}/, /\bgh[pousr]_[A-Za-z0-9]{30,}/, /\bgithub_pat_[A-Za-z0-9_]{40,}/,
199
+ /\bAKIA[0-9A-Z]{16}\b/, /\bxox[abprs]-[A-Za-z0-9-]{20,}/, /\bAIza[0-9A-Za-z_-]{35}\b/, /\bglpat-[A-Za-z0-9_-]{20,}/,
200
+ ];
201
+ const PLACEHOLDER_RE = /x{4,}|X{4,}|\.\.\.|YOUR|EXAMPLE|example|REPLACE|placeholder|0{8,}|1234567|abcdef/;
202
+ function secretInLine(line, next) {
203
+ for (const re of SECRET_RES) {
204
+ const m = line.match(re);
205
+ if (!m) continue;
206
+ const v = m[0];
207
+ if (PLACEHOLDER_RE.test(v)) continue;
208
+ if ((v.match(/\d/g) || []).length < 2 || (v.match(/[A-Za-z]/g) || []).length < 8) continue;
209
+ return true;
210
+ }
211
+ if (/-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/.test(line) && /^[A-Za-z0-9+/=]{40,}$/.test(String(next || '').trim())) return true;
212
+ return false;
213
+ }
214
+ export const SECURITY_RULES = [
215
+ { id: 'secret', severity: 'critical', why: 'a live credential is written into the skill', test: (l, n) => secretInLine(l, n) },
216
+ { id: 'exfiltration', severity: 'critical', why: 'sends credentials or private files over the network',
217
+ re: /\b(curl|wget|nc|ncat|scp|rsync|Invoke-WebRequest|iwr|Invoke-RestMethod)\b[^\n]*(~\/\.ssh|\.ssh\/id_|\bid_rsa\b|\bid_ed25519\b|\.aws\/credentials|\.netrc|\.git-credentials|login\.keychain|\/etc\/shadow)/i },
218
+ { id: 'exfiltration', severity: 'critical', why: 'pipes credentials or private files to a network tool',
219
+ re: /(~\/\.ssh|\bid_rsa\b|\.aws\/credentials|\.netrc|\.env\b)[^\n|]*\|\s*(curl|nc|ncat|wget)\b/i },
220
+ { id: 'reverse-shell', severity: 'critical', why: 'opens a shell to a remote host', re: /\/dev\/tcp\/[\w.-]+\/\d+|\bnc(at)?\b[^\n]*\s-e\s|\bbash\s+-i\s+>&|\bmkfifo\b[^\n]*\bnc\b/ },
221
+ { id: 'hidden-text', severity: 'critical', why: 'contains bidirectional control characters that hide text from a reader', re: /[\u202A-\u202E\u2066-\u2069]/ },
222
+ { id: 'hidden-text', severity: 'high', why: 'contains zero-width characters that hide text from a reader', re: /[\u200B\u200C\u2060\u180E]|.\uFEFF/ },
223
+ { id: 'injection', severity: 'high', why: 'tells the model to drop earlier instructions',
224
+ re: /\b(ignore|disregard|forget|override)\b[^\n]{0,30}\b(previous|prior|above|earlier|system|developer|safety)\b[^\n]{0,20}\b(instructions?|prompts?|rules?|messages?|guidelines?)\b/i, quoted: 'medium' },
225
+ { id: 'injection', severity: 'high', why: 'tells the model to hide what it does from the user',
226
+ re: /\b(do not|don't|never)\s+(tell|inform|let)\s+the\s+user\s+(know|about|that|what|you|we)\b|\b(do not|don't|never)\s+(reveal|mention|disclose)\b[^\n]{0,30}\bto\s+the\s+user\b|\bwithout\s+(telling|informing)\s+the\s+user\b|\bhide\b[^\n]{0,20}\bfrom\s+the\s+user\b/i, quoted: 'medium' },
227
+ { id: 'injection', severity: 'high', why: 'tries to replace the model\'s instructions', re: /\byou are now\b|\bnew system prompt\b|\b(developer|DAN|jailbreak)[ -]mode\b/i, quoted: 'medium' },
228
+ { id: 'destructive', severity: 'high', why: 'deletes a home or root directory',
229
+ re: /\brm\s+-[a-zA-Z]*[rR][a-zA-Z]*\s+(?:--no-preserve-root\s+)?(?:\/|\/\*|~\/?|~\/\*|\$HOME\/?|\$\{HOME\}\/?)(?=\s|$|;|&|\|)/ },
230
+ { id: 'destructive', severity: 'high', why: 'erases a disk or exhausts the machine',
231
+ re: /\bmkfs(\.\w+)?\s|\bdd\s+[^\n]*\bof=\/dev\/(sd|disk|nvme|hd|rdisk)|:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:|\bdiskutil\s+(erase\w*|zeroDisk)\b|\bchmod\s+-R\s+777\s+\/(\s|$)/ },
232
+ { id: 'remote-code', severity: 'high', why: 'downloads code and runs it unseen',
233
+ re: /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(ba|z|da|k)?sh\b|\biex\s*\(\s*(iwr|irm|Invoke-WebRequest|Invoke-RestMethod|New-Object\s+Net\.WebClient)|\beval\s+"?\$\(\s*(curl|wget)\b/i },
234
+ { id: 'persistence', severity: 'high', why: 'adds itself to shell start-up or remote login',
235
+ re: /(>>?|\btee\s+-a)\s*["']?(~|\$HOME)?\/?[^\s"']*(\.bashrc|\.zshrc|\.bash_profile|\.profile|authorized_keys)\b/ },
236
+ { id: 'scheduler', severity: 'medium', why: 'installs a scheduled job', re: /\bcrontab\s+-[a-z]*\s|\bLaunchAgents\/[^\s]+\.plist|\bschtasks\s+\/create\b/i },
237
+ { id: 'privilege', severity: 'medium', why: 'runs commands as administrator', re: /(^|[\s;&|(`])sudo\s+\S/ },
238
+ { id: 'force-push', severity: 'medium', why: 'rewrites shared git history', re: /\bgit\s+push\s+[^\n]*(--force\b|\s-f\b)/ },
239
+ ];
240
+ const TEXT_EXT = /\.(md|markdown|txt|sh|bash|zsh|fish|py|js|mjs|cjs|ts|rb|pl|ps1|bat|cmd|json|ya?ml|toml|ini|cfg|html?|xml)$/i;
241
+ export function scanText(text, file = 'SKILL.md', rules = SECURITY_RULES) {
242
+ const findings = [];
243
+ const lines = String(text).split('\n');
244
+ for (let i = 0; i < lines.length; i++) {
245
+ const l = lines[i];
246
+ if (!l || l.length > 20000) continue;
247
+ for (const r of rules) {
248
+ if (r.test) { if (r.test(l, lines[i + 1])) findings.push({ rule: r.id, severity: r.severity, file, line: i + 1, why: r.why }); continue; }
249
+ const m = r.re.exec(l);
250
+ if (!m) continue;
251
+ // a phrase quoted as an example ("ignore previous instructions" — do not obey it) is reported, not obeyed
252
+ const quoted = r.quoted && /["'“‘«`]\s*$/.test(l.slice(Math.max(0, m.index - 3), m.index));
253
+ findings.push({ rule: r.id, severity: quoted ? r.quoted : r.severity, file, line: i + 1, why: quoted ? `${r.why} (quoted as an example)` : r.why });
254
+ }
255
+ }
256
+ return findings;
257
+ }
258
+ function skillFiles(dir, limit = LIMITS.scanFiles) {
259
+ const out = [];
260
+ (function walk(d, rel, depth) {
261
+ if (out.length >= limit || depth > 4) return;
262
+ let ents; try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
263
+ ents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
264
+ for (const e of ents) {
265
+ if (out.length >= limit) return;
266
+ if (e.name === '.git' || e.name === 'node_modules' || e.name === '__pycache__') continue;
267
+ const p = path.join(d, e.name); const r = rel ? `${rel}/${e.name}` : e.name;
268
+ let st; try { st = fs.statSync(p); } catch { continue; }
269
+ if (st.isDirectory()) { if (!e.isSymbolicLink()) walk(p, r, depth + 1); continue; }
270
+ if (st.isFile()) out.push({ rel: r, abs: p, size: st.size, mtimeMs: st.mtimeMs });
271
+ }
272
+ })(dir, '', 0);
273
+ return out;
274
+ }
275
+ export function verdictFor(findings, trust = 'community') {
276
+ const at = SEVERITY[BLOCK_AT[trust] || 'high'];
277
+ const blocking = findings.filter((f) => SEVERITY[f.severity] >= at);
278
+ return { verdict: blocking.length ? 'block' : findings.length ? 'warn' : 'clean', blocking };
279
+ }
280
+ export function scanSkillDir(dir, trust = 'community', files = null) {
281
+ const findings = [];
282
+ for (const f of files || skillFiles(dir)) {
283
+ if (!TEXT_EXT.test(f.rel) && f.rel !== 'SKILL.md') continue;
284
+ if (f.size > LIMITS.scanFileBytes) { findings.push({ rule: 'unscanned', severity: 'low', file: f.rel, line: 0, why: 'file too large to scan' }); continue; }
285
+ let text; try { text = fs.readFileSync(f.abs, 'utf8'); } catch { continue; }
286
+ findings.push(...scanText(text, f.rel));
287
+ }
288
+ return { ...verdictFor(findings, trust), findings };
289
+ }
290
+
291
+ // ── §35 tools a skill names, and what they mean here ─────────────────────────────────────────
292
+ // Foreign tool names → SCROLL capabilities. Data, not prose: extend it with config
293
+ // `skills.tool_aliases` or the `toolAliases` option. `null` = no portable equivalent; only a
294
+ // runtime that has a tool of exactly that name satisfies it.
295
+ export const TOOL_ALIASES = {
296
+ // file, shell, web
297
+ Bash: 'shell.exec', Read: 'fs.read', Write: 'fs.write', Edit: 'fs.write', MultiEdit: 'fs.write', NotebookEdit: 'fs.write',
298
+ Glob: 'fs.search', Grep: 'fs.search', LS: 'fs.read', WebSearch: 'web.search', WebFetch: 'web.read',
299
+ shell: 'shell.exec', apply_patch: 'fs.write', web_search: 'web.search', view_image: 'vision.read',
300
+ run_shell_command: 'shell.exec', read_file: 'fs.read', write_file: 'fs.write', read_many_files: 'fs.read',
301
+ google_web_search: 'web.search', web_fetch: 'web.read', search_file_content: 'fs.search',
302
+ terminal: 'shell.exec', search_files: 'fs.search', patch: 'fs.write', web_extract: 'web.read', browser_navigate: 'web.browse',
303
+ vision_analyze: 'vision.read', image_generate: 'vision.generate',
304
+ // people and other agents
305
+ AskUserQuestion: 'ask.user', clarify: 'ask.user', SendUserMessage: 'message.send', SendUserFile: 'message.file', send_message: 'message.send',
306
+ Agent: 'dispatch.agents', Task: 'dispatch.agents', delegate_task: 'dispatch.agents',
307
+ // skills, plans, memory
308
+ Skill: 'skills.read', skill_view: 'skills.read', skill_list: 'skills.read', skills_list: 'skills.read',
309
+ TodoWrite: 'tasks.track', TaskCreate: 'tasks.track', TaskUpdate: 'tasks.track', TaskList: 'tasks.track', update_plan: 'tasks.track', todo: 'tasks.track',
310
+ save_memory: 'memory.agent',
311
+ // no portable equivalent
312
+ Artifact: null,
313
+ };
314
+ // names that are ordinary words: counted only as `Name` in backticks or "Name tool"
315
+ const AMBIGUOUS = new Set(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'LS', 'Task', 'Agent', 'Skill', 'Artifact', 'shell', 'web_search', 'read_file', 'write_file', 'web_fetch', 'terminal', 'search_files', 'patch', 'clarify', 'send_message', 'todo', 'image_generate', 'view_image', 'save_memory', 'skill_list']);
316
+ const SOFT_CAPS = new Set(['tasks.track']); // a missing plan/todo tool changes nothing about what a skill can do
317
+ const CAP_SHAPE = /^[a-z]+\.[a-z_*]+$/;
318
+ const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
319
+ const NAME_RES = new Map();
320
+ function nameRe(name) {
321
+ let re = NAME_RES.get(name);
322
+ if (!re) {
323
+ const e = reEsc(name);
324
+ re = AMBIGUOUS.has(name) ? new RegExp(`\`${e}\`|\\b${e}\\s+tool\\b`) : new RegExp(`(?<![\\w.-])${e}(?![\\w-])`);
325
+ NAME_RES.set(name, re);
326
+ }
327
+ return re;
328
+ }
329
+
330
+ function aliasCap(name, aliases) { return Object.prototype.hasOwnProperty.call(aliases, name) ? aliases[name] : undefined; }
331
+ function reqFromName(raw, aliases, hard, via) {
332
+ const name = String(raw).trim().replace(/\(.*\)$/, '');
333
+ if (!name) return null;
334
+ if (CAP_SHAPE.test(name)) return { ref: name, kind: 'cap', cap: name, hard, via };
335
+ const mm = name.replace(/[_*]+$/, '').match(/^mcp__([A-Za-z0-9_.-]+?)__([A-Za-z0-9_.-]+)$/);
336
+ if (mm) return { ref: name.replace(/[_*]+$/, ''), kind: 'mcp', server: mm[1], tool: mm[2], cap: `mcp.${mm[1].toLowerCase().replace(/[^a-z0-9]+/g, '_')}`, hard, via };
337
+ const cap = aliasCap(name, aliases);
338
+ return { ref: name, kind: 'tool', cap: cap === undefined ? null : cap, hard, via };
339
+ }
340
+ function splitList(v) {
341
+ if (Array.isArray(v)) return v.map(String);
342
+ const s = String(v ?? ''); const out = []; let depth = 0, cur = '';
343
+ for (const ch of s) {
344
+ if (ch === '(') depth++; if (ch === ')') depth--;
345
+ if (depth === 0 && /[\s,]/.test(ch)) { if (cur) out.push(cur); cur = ''; continue; }
346
+ cur += ch;
347
+ }
348
+ if (cur) out.push(cur);
349
+ return out;
350
+ }
351
+ const meta = (fm, ns) => (fm && fm.metadata && typeof fm.metadata === 'object' && fm.metadata[ns] && typeof fm.metadata[ns] === 'object' ? fm.metadata[ns] : {});
352
+ export function skillRequirements(fm, body, { aliases = TOOL_ALIASES, extra = [] } = {}) {
353
+ const reqs = new Map();
354
+ const add = (r) => { if (!r) return; const k = r.ref; const cur = reqs.get(k); if (!cur || (r.hard && !cur.hard)) reqs.set(k, r); };
355
+ const sc = meta(fm, 'scroll'), hm = meta(fm, 'hermes');
356
+ for (const n of splitList(fm && fm['allowed-tools'])) add(reqFromName(n, aliases, true, 'allowed-tools'));
357
+ for (const n of splitList(sc.requires)) add(reqFromName(n, aliases, true, 'requires'));
358
+ for (const n of splitList(hm.requires_tools)) add(reqFromName(n, aliases, true, 'requires'));
359
+ for (const n of arr(extra)) add(reqFromName(n, aliases, true, 'override'));
360
+ const text = String(body || '');
361
+ for (const m of text.matchAll(/\bmcp__([A-Za-z0-9_.-]+?)__([A-Za-z0-9_-]+)/g)) add(reqFromName(m[0], aliases, false, 'body'));
362
+ for (const m of text.matchAll(/\b([A-Z][A-Za-z0-9]+):([a-z][a-z0-9]*_[a-z0-9_]+)\b/g)) add({ ref: `${m[1]}:${m[2]}`, kind: 'mcp', server: m[1], tool: m[2], cap: `mcp.${m[1].toLowerCase()}`, hard: false, via: 'body' });
363
+ for (const name of Object.keys(aliases)) {
364
+ if (!text.includes(name)) continue;
365
+ if (nameRe(name).test(text)) add(reqFromName(name, aliases, false, 'body'));
366
+ }
367
+ return [...reqs.values()].sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
368
+ }
369
+ export function normalizeAvailable(av) {
370
+ if (!av) return null;
371
+ const caps = new Set(arr(av.capabilities)); const tools = new Set(arr(av.tools)); const servers = new Set(arr(av.mcpServers || av.mcp_servers));
372
+ const capOk = (c) => {
373
+ if (!c) return false;
374
+ if (caps.has(c) || caps.has('*')) return true;
375
+ const root = c.split('.')[0];
376
+ return caps.has(`${root}.*`);
377
+ };
378
+ return { caps, tools, servers, capOk };
379
+ }
380
+ export function satisfied(req, av) {
381
+ if (!av) return true;
382
+ if (req.kind === 'cap') return av.capOk(req.cap);
383
+ if (req.kind === 'mcp') return av.servers.has(req.server) || av.tools.has(req.ref) || av.tools.has(req.tool) || av.capOk(req.cap) || av.capOk('mcp.*');
384
+ return av.tools.has(req.ref) || (req.cap != null && av.capOk(req.cap));
385
+ }
386
+ // hidden: a requirement the skill DECLARES is missing, or most of the tools its text names are
387
+ // missing (≥2, and more missing than present — a skill built around another runtime's tools).
388
+ // partial: some named tools are missing; the skill is shown and skill_view says which.
389
+ export function compatStatus(reqs, av) {
390
+ if (!av) return { status: 'unknown', unmet: [], dominant: false };
391
+ const counted = reqs.filter((r) => !(r.cap && SOFT_CAPS.has(r.cap)));
392
+ const unmet = counted.filter((r) => !satisfied(r, av));
393
+ if (unmet.some((r) => r.hard)) return { status: 'hidden', unmet, dominant: false };
394
+ const met = counted.length - unmet.length;
395
+ if (unmet.length >= 2 && unmet.length > met) return { status: 'hidden', unmet, dominant: true };
396
+ return { status: unmet.length ? 'partial' : 'ok', unmet, dominant: false };
397
+ }
398
+
399
+ // ── config, sources, layouts ──────────────────────────────────────────────────────────────────
400
+ export function expandPath(p, env = process.env) {
401
+ let s = String(p || '').trim();
402
+ s = s.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, a, b) => env[a || b] ?? '');
403
+ if (s === '~' || s.startsWith('~/')) s = path.join(os.homedir(), s.slice(1));
404
+ return s;
405
+ }
406
+ export function loadScrollConfig(cwd = process.cwd()) {
407
+ for (const f of ['scroll.config.yaml', 'scroll.config.yml', 'scroll.config.json']) {
408
+ const p = path.join(cwd, f);
409
+ if (!fs.existsSync(p)) continue;
410
+ const raw = fs.readFileSync(p, 'utf8');
411
+ try { return f.endsWith('.json') ? JSON.parse(raw) : (parseSkillYaml(raw) || {}); }
412
+ catch (e) { throw new Error(`${f}: ${e.message}`); }
413
+ }
414
+ return {};
415
+ }
416
+ // How to find skill folders inside a source. Extensible: registerSourceLayout(name, fn).
417
+ const LAYOUTS = {
418
+ // any folder: every directory that holds a SKILL.md, at any depth up to max_depth
419
+ dir: (src) => findSkillDirs(src.path, src),
420
+ // a Claude Code plugins folder: only the plugin versions installed_plugins.json says are installed
421
+ 'claude-code-plugins': (src) => {
422
+ let j; try { j = JSON.parse(fs.readFileSync(path.join(src.path, 'installed_plugins.json'), 'utf8')); } catch { return []; }
423
+ const dirs = [];
424
+ for (const installs of Object.values((j && j.plugins) || {})) {
425
+ for (const inst of arr(installs)) {
426
+ if (!inst || typeof inst.installPath !== 'string') continue;
427
+ dirs.push(...findSkillDirs(path.join(inst.installPath, 'skills'), { ...src, maxDepth: 2 }));
428
+ }
429
+ }
430
+ return dirs;
431
+ },
432
+ };
433
+ export function registerSourceLayout(name, fn) { if (typeof fn !== 'function') throw new Error('layout must be a function'); LAYOUTS[name] = fn; }
434
+ export function findSkillDirs(root, { maxDepth = LIMITS.maxDepth, maxSkills = LIMITS.maxSkillsPerSource } = {}) {
435
+ const found = []; const seen = new Set();
436
+ (function walk(dir, depth) {
437
+ if (found.length >= maxSkills) return;
438
+ let real; try { real = fs.realpathSync(dir); } catch { return; }
439
+ if (seen.has(real)) return; seen.add(real);
440
+ let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
441
+ const md = ents.find((e) => e.name === 'SKILL.md');
442
+ if (md) { try { if (fs.statSync(path.join(dir, 'SKILL.md')).isFile()) { found.push(dir); return; } } catch { /* dangling */ } }
443
+ if (depth >= maxDepth) return;
444
+ ents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
445
+ for (const e of ents) {
446
+ if (e.name === 'node_modules' || e.name === '.git' || e.name === '.build' || e.name === '.scroll' || e.name === '__pycache__') continue;
447
+ const p = path.join(dir, e.name);
448
+ let isDir = e.isDirectory();
449
+ if (!isDir && e.isSymbolicLink()) { try { isDir = fs.statSync(p).isDirectory(); } catch { isDir = false; } }
450
+ if (isDir) walk(p, depth + 1);
451
+ }
452
+ })(root, 0);
453
+ return found;
454
+ }
455
+ // Well-known skill folders of other tools. Used only by `scroll skill sources --detect`, which
456
+ // reports what exists; nothing is read unless the operator lists it in scroll.config.
457
+ export const KNOWN_SKILL_DIRS = [
458
+ { path: '~/.agents/skills', note: 'shared Agent Skills folder' },
459
+ { path: '~/.claude/skills', note: 'Claude Code user skills' },
460
+ { path: '~/.claude/plugins', layout: 'claude-code-plugins', note: 'Claude Code installed plugins' },
461
+ { path: '~/.codex/skills', note: 'Codex user skills' },
462
+ { path: '~/.hermes/skills', note: 'Hermes Agent skills' },
463
+ { path: '~/.gemini/skills', note: 'Gemini CLI skills' },
464
+ ];
465
+ export function detectSkillDirs(env = process.env) {
466
+ return KNOWN_SKILL_DIRS.map((k) => ({ ...k, abs: expandPath(k.path, env) })).filter((k) => fs.existsSync(k.abs));
467
+ }
468
+ export function resolveSources({ cwd = process.cwd(), agent = null, config = null, env = process.env, identity = null } = {}) {
469
+ const out = [];
470
+ if (agent) out.push({ id: 'agent', kind: 'agent', path: path.join(cwd, 'agents', agent, 'skills'), trust: 'trusted', layout: 'dir' });
471
+ out.push({ id: 'repo', kind: 'repo', path: path.join(cwd, 'skills'), trust: 'trusted', layout: 'dir' });
472
+ if (identity && identity.skills_external === false) return out;
473
+ const sk = ((config || loadScrollConfig(cwd)) || {}).skills || {};
474
+ const fromEnv = String(env.SCROLL_SKILLS_DIRS || '').split(path.delimiter).filter(Boolean);
475
+ [...arr(sk.external_dirs), ...fromEnv].forEach((e, i) => {
476
+ const o = typeof e === 'string' ? { path: e } : (e || {});
477
+ if (!o.path) return;
478
+ out.push({
479
+ id: o.id || `external-${i + 1}`, kind: 'external', path: expandPath(o.path, env), display: String(o.path),
480
+ trust: TRUST_LEVELS.includes(o.trust) ? o.trust : 'community', layout: o.layout || 'dir',
481
+ maxDepth: Number(o.max_depth) || LIMITS.maxDepth,
482
+ });
483
+ });
484
+ return out;
485
+ }
486
+
487
+ // ── loading one skill (cached by file state) ──────────────────────────────────────────────────
488
+ // Cached by file state (SKILL.md + every file in the folder), shared across registries. A record
489
+ // handed out is a copy: per-registry fields (state, compat, requirements) never leak back.
490
+ const CACHE = new Map();
491
+ const filesSig = (files) => files.map((f) => `${f.rel}:${f.size}:${f.mtimeMs}`).join(',');
492
+ function loadSkillAt(dir, src) {
493
+ const file = path.join(dir, 'SKILL.md');
494
+ let st; try { st = fs.statSync(file); } catch { return null; }
495
+ let realDir; try { realDir = fs.realpathSync(dir); } catch { return null; }
496
+ const files = skillFiles(dir);
497
+ const fsig = filesSig(files);
498
+ const sig = `${src.trust}|${src.kind}|${st.size}|${st.mtimeMs}|${fsig}`;
499
+ const key = `${realDir}|${dir}`;
500
+ let entry = CACHE.get(key);
501
+ if (!entry || entry.sig !== sig) {
502
+ const base = { dir, realDir, file, bytes: st.size, mtimeMs: st.mtimeMs, filesSig: fsig };
503
+ let rec;
504
+ if (st.size > LIMITS.skillMdBytes) {
505
+ rec = { ...base, name: null, description: '', frontmatter: null, hash: null, errors: [`SKILL.md is larger than ${LIMITS.skillMdBytes} bytes`], warnings: [], security: { verdict: 'clean', blocking: [], findings: [] } };
506
+ } else {
507
+ const raw = fs.readFileSync(file, 'utf8');
508
+ const parsed = parseSkillMd(raw);
509
+ const fm = parsed.frontmatter || {};
510
+ rec = { ...base, name: typeof fm.name === 'string' ? fm.name.trim() : null, description: oneLine(fm.description), frontmatter: parsed.frontmatter, parseError: parsed.error, hash: sha(raw) };
511
+ const v = validateSkill({ ...rec, body: parsed.body }, { strict: src.kind !== 'external' });
512
+ rec.errors = v.errors; rec.warnings = v.warnings;
513
+ }
514
+ entry = { sig, rec, reqs: new Map(), files, trust: src.trust, security: rec.security || null };
515
+ CACHE.set(key, entry);
516
+ }
517
+ return { ...entry.rec, source: src.id, sourceKind: src.kind, trust: src.trust, _entry: entry };
518
+ }
519
+ // The security scan reads every file of a skill, so it runs only for a skill that won its name
520
+ // (shadowed copies are never served) and is cached with the file state.
521
+ function securityOf(r) {
522
+ if (r.security) return r.security;
523
+ const e = r._entry;
524
+ if (e && !e.security) e.security = scanSkillDir(r.dir, e.trust, e.files);
525
+ r.security = e ? e.security : scanSkillDir(r.dir, r.trust);
526
+ return r.security;
527
+ }
528
+ // requirements depend on the registry's alias table and the operator's overrides: cached per key
529
+ function requirementsOf(r, aliases, aliasKey, extra) {
530
+ const k = `${aliasKey}|${JSON.stringify(extra || [])}`;
531
+ const e = r._entry;
532
+ if (e && e.reqs.has(k)) return e.reqs.get(k);
533
+ let body = ''; try { body = parseSkillMd(fs.readFileSync(r.file, 'utf8')).body; } catch { /* gone */ }
534
+ const reqs = skillRequirements(r.frontmatter || {}, body, { aliases, extra });
535
+ if (e) e.reqs.set(k, reqs);
536
+ return reqs;
537
+ }
538
+ const PLATFORM = { darwin: 'macos', linux: 'linux', win32: 'windows' };
539
+ function platformsOf(fm) {
540
+ const raw = arr(meta(fm, 'scroll').platforms).concat(arr(fm && fm.platforms), arr(meta(fm, 'hermes').platforms));
541
+ return raw.map((p) => String(p).toLowerCase()).map((p) => (/^(mac|macos|darwin|osx)$/.test(p) ? 'macos' : /^(win|windows|win32)$/.test(p) ? 'windows' : p));
542
+ }
543
+
544
+ // ── the registry ──────────────────────────────────────────────────────────────────────────────
545
+ const INDEX_HEADER = 'Skills are tested instructions for specific jobs. When a request matches one, call skill_view with its name and follow it before acting. skill_list finds skills that are not listed here.';
546
+ export function openSkills(opts = {}) {
547
+ const cwd = opts.cwd || process.cwd();
548
+ const emit = typeof opts.emit === 'function' ? opts.emit : () => {};
549
+ const platform = PLATFORM[opts.platform || process.platform] || String(opts.platform || process.platform);
550
+ let config = opts.config || null;
551
+ if (!config) { try { config = loadScrollConfig(cwd); } catch (e) { config = {}; emit('skills_config_error', { error: e.message }); } }
552
+ const skCfg = (config && config.skills) || {};
553
+ const aliases = { ...TOOL_ALIASES, ...(skCfg.tool_aliases || {}), ...(opts.toolAliases || {}) };
554
+ const aliasKey = sha(JSON.stringify(aliases));
555
+ const av = normalizeAvailable(opts.available);
556
+ const toolFor = typeof opts.toolFor === 'function' ? opts.toolFor : () => null;
557
+ const names = { list: 'skill_list', view: 'skill_view', ...(opts.toolNames || {}) };
558
+ const limits = { ...LIMITS, indexSkills: Number(skCfg.max_index) || LIMITS.indexSkills, indexTokens: Number(skCfg.max_index_tokens) || LIMITS.indexTokens, ...(opts.limits || {}) };
559
+ const compatPath = opts.compatFile === false ? null : (opts.compatFile || (opts.agent ? path.join(cwd, 'agents', opts.agent, 'skills-compat.json') : path.join(cwd, 'skills-compat.json')));
560
+ const overrides = (() => { if (!compatPath) return {}; try { return JSON.parse(fs.readFileSync(compatPath, 'utf8')).overrides || {}; } catch { return {}; } })();
561
+ const sources = opts.sources || resolveSources({ cwd, agent: opts.agent, config, env: opts.env || process.env, identity: opts.identity });
562
+ const pinned = arr(opts.pinned);
563
+ const usage = opts.usage || {};
564
+ const labels = { header: INDEX_HEADER, ...(opts.labels || {}) };
565
+
566
+ function gate(s) {
567
+ const fm = s.frontmatter || {};
568
+ const ov = overrides[s.name] || {};
569
+ const sec = securityOf(s);
570
+ if (sec.verdict === 'block') return { state: 'blocked', reason: sec.blocking.map((f) => `${f.rule} (${f.file}:${f.line})`).join(', ') };
571
+ if (fm['disable-model-invocation'] === true) return { state: 'hidden', reason: 'user-invoked only (disable-model-invocation)' };
572
+ const plats = platformsOf(fm);
573
+ if (plats.length && !plats.includes(platform)) return { state: 'hidden', reason: `not for ${platform} (platforms: ${plats.join(', ')})` };
574
+ if (ov.status === 'hidden') return { state: 'hidden', reason: `override: ${ov.reason || 'hidden by operator'}` };
575
+ const fb = [...splitList(meta(fm, 'scroll').fallback_for), ...splitList(meta(fm, 'hermes').fallback_for_tools)].map((n) => reqFromName(n, aliases, true, 'fallback')).filter(Boolean);
576
+ if (av && fb.length && fb.some((r) => satisfied(r, av))) return { state: 'hidden', reason: `fallback skill; the primary tool is present (${fb.filter((r) => satisfied(r, av)).map((r) => r.ref).join(', ')})` };
577
+ const c = compatStatus(s.requirements, av);
578
+ s.compat = c.status; s.unmet = c.unmet.map((r) => r.ref);
579
+ if (c.status === 'hidden' && ov.status !== 'ok') {
580
+ const list = (rs) => rs.slice(0, 6).map((r) => r.ref).join(', ') + (rs.length > 6 ? ', …' : '');
581
+ return { state: 'hidden', reason: c.dominant ? `most tools it names are not available here: ${list(c.unmet)}` : `needs ${list(c.unmet.filter((r) => r.hard))}` };
582
+ }
583
+ if (ov.status === 'ok') s.compat = 'ok';
584
+ return { state: 'visible', reason: '' };
585
+ }
586
+
587
+ function scan() {
588
+ const all = []; const winners = new Map(); const shadowed = [];
589
+ for (const src of sources) {
590
+ const layout = LAYOUTS[src.layout || 'dir'];
591
+ if (!layout) { emit('skills_source_error', { source: src.id, error: `unknown layout "${src.layout}"` }); continue; }
592
+ if (!fs.existsSync(src.path)) continue;
593
+ const recs = [];
594
+ for (const dir of layout(src)) {
595
+ const r = loadSkillAt(dir, src);
596
+ if (!r) continue;
597
+ recs.push(r); all.push(r);
598
+ }
599
+ // inside one source the newest copy of a name wins (plugin caches keep old versions)
600
+ const byName = new Map();
601
+ for (const r of recs) {
602
+ if (r.errors.length || !r.name) continue;
603
+ const cur = byName.get(r.name);
604
+ if (!cur || r.mtimeMs > cur.mtimeMs || (r.mtimeMs === cur.mtimeMs && r.dir < cur.dir)) { if (cur) shadowed.push({ ...cur, by: `newer copy in ${src.id}` }); byName.set(r.name, r); }
605
+ else shadowed.push({ ...r, by: `newer copy in ${src.id}` });
606
+ }
607
+ // across sources the first source wins: agent → repo → external, in config order
608
+ for (const [n, r] of byName) {
609
+ if (winners.has(n)) shadowed.push({ ...r, by: winners.get(n).source });
610
+ else winners.set(n, r);
611
+ }
612
+ }
613
+ const visible = new Map(); const gated = [];
614
+ for (const [n, r] of winners) {
615
+ r.requirements = requirementsOf(r, aliases, aliasKey, overrides[n] ? overrides[n].requires : undefined);
616
+ const g = gate(r); r.state = g.state; r.reason = g.reason;
617
+ if (g.state === 'visible') visible.set(n, r); else gated.push(r);
618
+ }
619
+ const invalid = all.filter((r) => r.errors.length || !r.name);
620
+ return { all, visible, gated, shadowed, invalid };
621
+ }
622
+
623
+ let state = scan();
624
+ let frozen = null;
625
+ emit('skills_loaded', { sources: sources.filter((s) => fs.existsSync(s.path)).map((s) => s.id), visible: state.visible.size, hidden: state.gated.filter((r) => r.state === 'hidden').length, blocked: state.gated.filter((r) => r.state === 'blocked').length, invalid: state.invalid.length, shadowed: state.shadowed.length });
626
+
627
+ const sortedVisible = () => [...state.visible.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
628
+ const srcRank = (id) => { const i = sources.findIndex((s) => s.id === id); return i < 0 ? 99 : i; };
629
+
630
+ // §34.3 / §34.6 — index: a deterministic function of (visible set, pinned, usage, limits).
631
+ function buildIndex() {
632
+ const rank = [...state.visible.values()].sort((a, b) => {
633
+ const pa = pinned.indexOf(a.name), pb = pinned.indexOf(b.name);
634
+ if ((pa >= 0) !== (pb >= 0)) return pa >= 0 ? -1 : 1;
635
+ if (pa >= 0 && pb >= 0 && pa !== pb) return pa - pb;
636
+ const ua = Number(usage[a.name]) || 0, ub = Number(usage[b.name]) || 0;
637
+ if (ua !== ub) return ub - ua;
638
+ const sa = srcRank(a.source), sb = srcRank(b.source);
639
+ if (sa !== sb) return sa - sb;
640
+ return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
641
+ });
642
+ const clean = (s) => oneLine(s).replace(/[<>]/g, '');
643
+ const shorten = (d, n) => { if (d.length <= n) return d; const cut = d.slice(0, n); const dot = cut.lastIndexOf('. '); return (dot > n * 0.5 ? cut.slice(0, dot + 1) : cut.replace(/\s+\S*$/, '')) + (dot > n * 0.5 ? '' : '…'); };
644
+ const render = (list, n) => {
645
+ const lines = [...list].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)).map((s) => `- ${s.name}: ${shorten(clean(s.description), n)}`);
646
+ return ['<available_skills>', labels.header, ...lines, '</available_skills>'].join('\n');
647
+ };
648
+ let take = rank.slice(0, limits.indexSkills);
649
+ let text = '';
650
+ for (const n of [LIMITS.description, 240, 160, 100]) { text = render(take, n); if (approxTokens(text) <= limits.indexTokens) break; }
651
+ while (take.length && approxTokens(text) > limits.indexTokens) { take = take.slice(0, -1); text = render(take, 100); }
652
+ const included = take.map((s) => s.name).sort();
653
+ const omitted = rank.map((s) => s.name).filter((n) => !included.includes(n)).sort();
654
+ return { text: take.length ? text : '', hash: sha(text), included, omitted, tokens: take.length ? approxTokens(text) : 0 };
655
+ }
656
+ function index({ rebuild = false } = {}) {
657
+ if (!frozen || rebuild) { frozen = buildIndex(); emit('skills_indexed', { count: frozen.included.length, omitted: frozen.omitted.length, tokens: frozen.tokens, hash: frozen.hash }); }
658
+ return frozen;
659
+ }
660
+
661
+ function list(query = '', { limit = 20, offset = 0 } = {}) {
662
+ const vis = sortedVisible();
663
+ const lim = Math.max(1, Math.min(50, Number(limit) || 20)); const off = Math.max(0, Number(offset) || 0);
664
+ let hits = vis;
665
+ if (String(query || '').trim()) {
666
+ const q = [...new Set(tokens(query))];
667
+ const scored = vis.map((s) => {
668
+ const nt = tokens(s.name.replace(/-/g, ' ')), dt = new Set(tokens(s.description));
669
+ let sc = 0;
670
+ for (const w of q) { if (nt.includes(w)) sc += 5; else if (nt.some((x) => x.startsWith(w) && w.length >= 3)) sc += 3; if (dt.has(w)) sc += 1; }
671
+ if (s.name === String(query).trim()) sc += 10;
672
+ return { s, sc };
673
+ }).filter((x) => x.sc > 0).sort((a, b) => b.sc - a.sc || (a.s.name < b.s.name ? -1 : 1));
674
+ hits = scored.map((x) => x.s);
675
+ }
676
+ const page = hits.slice(off, off + lim);
677
+ return { total: hits.length, offset: off, skills: page.map((s) => ({ name: s.name, description: s.description.length > 300 ? s.description.slice(0, 299) + '…' : s.description, source: s.source, compat: s.compat || 'unknown' })) };
678
+ }
679
+
680
+ // re-check a skill against the disk before serving it: changed → reload + re-scan + re-gate
681
+ function fresh(name) {
682
+ const s = state.visible.get(name);
683
+ if (!s) return null;
684
+ let raw; try { raw = fs.readFileSync(s.file, 'utf8'); } catch { return { denied: 'the skill file is gone' }; }
685
+ if (sha(raw) === s.hash && filesSig(skillFiles(s.dir)) === s.filesSig) return { s, raw };
686
+ const src = sources.find((x) => x.id === s.source);
687
+ const r = loadSkillAt(s.dir, src);
688
+ if (!r || r.errors.length || r.name !== name) { state.visible.delete(name); return { denied: 'the skill changed on disk and is no longer valid' }; }
689
+ r.requirements = requirementsOf(r, aliases, aliasKey, (overrides[name] || {}).requires);
690
+ const g = gate(r);
691
+ emit('skill_rechecked', { name, state: g.state });
692
+ r.state = g.state; r.reason = g.reason;
693
+ if (g.state !== 'visible') { state.visible.delete(name); state.gated.push(r); return { denied: `the skill changed on disk and is now ${g.state}: ${g.reason}` }; }
694
+ state.visible.set(name, r);
695
+ return { s: r, raw: fs.readFileSync(r.file, 'utf8') };
696
+ }
697
+ function whyNot(name) {
698
+ const g = state.gated.find((r) => r.name === name);
699
+ if (g) return `skill "${name}" is ${g.state}: ${g.reason}`;
700
+ if (state.invalid.some((r) => r.name === name)) return `skill "${name}" is invalid`;
701
+ return `no skill named "${name}"`;
702
+ }
703
+ function toolMap(s) {
704
+ const lines = [];
705
+ for (const r of s.requirements || []) {
706
+ if (r.cap && SOFT_CAPS.has(r.cap)) continue;
707
+ const ok = satisfied(r, av);
708
+ const local = r.cap ? toolFor(r.cap, r) : null;
709
+ const over = (overrides[s.name] && overrides[s.name].map && overrides[s.name].map[r.ref]) || null;
710
+ if (over) lines.push(`${r.ref} → ${over}`);
711
+ else if (av && !ok) lines.push(`${r.ref} → not available here`);
712
+ else if (local && local !== r.ref) lines.push(`${r.ref} → ${local}`);
713
+ }
714
+ return lines;
715
+ }
716
+ function view(name, rel = null) {
717
+ const nm = String(name || '').trim();
718
+ const f = fresh(nm);
719
+ if (!f) { emit('skill_denied', { name: nm, reason: whyNot(nm) }); return { ok: false, error: whyNot(nm) }; }
720
+ if (f.denied) { emit('skill_denied', { name: nm, reason: f.denied }); return { ok: false, error: f.denied }; }
721
+ const s = f.s;
722
+ if (!rel) {
723
+ const body = parseSkillMd(f.raw).body;
724
+ const files = skillFiles(s.dir, 100).map((x) => x.rel).filter((x) => x !== 'SKILL.md');
725
+ const map = toolMap(s);
726
+ const head = [`# Skill: ${s.name}`];
727
+ if (map.length) head.push(`Tool names in this skill, as they are here: ${map.join('; ')}.`);
728
+ if (files.length) head.push(`Files in this skill (read one with ${names.view} and path): ${files.slice(0, 60).join(', ')}${files.length > 60 ? ', …' : ''}`);
729
+ const text = `${head.join('\n')}\n\n${body.length > limits.bodyChars ? body.slice(0, limits.bodyChars) + '\n…[truncated]' : body}`;
730
+ usage[s.name] = (Number(usage[s.name]) || 0) + 1;
731
+ emit('skill_viewed', { name: s.name, source: s.source, hash: s.hash, bytes: Buffer.byteLength(text) });
732
+ return { ok: true, name: s.name, text, hash: s.hash, source: s.source };
733
+ }
734
+ const r = String(rel);
735
+ const deny = (why) => { emit('skill_denied', { name: s.name, path: r.slice(0, 200), reason: why }); return { ok: false, error: why }; };
736
+ if (path.isAbsolute(r) || /^[A-Za-z]:/.test(r) || r.split(/[\\/]/).includes('..')) return deny('path must be relative to the skill folder, without ".."');
737
+ let real; try { real = fs.realpathSync(path.join(s.dir, r)); } catch { return deny(`no file "${r}" in skill "${s.name}"`); }
738
+ if (real !== s.realDir && !real.startsWith(s.realDir + path.sep)) return deny('path leads outside the skill folder');
739
+ let st; try { st = fs.statSync(real); } catch { return deny(`no file "${r}"`); }
740
+ if (!st.isFile()) return deny(`"${r}" is not a file`);
741
+ if (st.size > limits.viewBytes) return deny(`"${r}" is larger than ${limits.viewBytes} bytes`);
742
+ const buf = fs.readFileSync(real);
743
+ if (buf.subarray(0, 8192).includes(0)) return deny(`"${r}" is a binary file`);
744
+ const text = buf.toString('utf8');
745
+ const v = verdictFor(scanText(text, r), s.trust);
746
+ if (v.verdict === 'block') return deny(`"${r}" failed the security scan: ${v.blocking.map((x) => x.rule).join(', ')}`);
747
+ emit('skill_viewed', { name: s.name, path: r, source: s.source, hash: s.hash, fileHash: sha(buf), bytes: buf.length });
748
+ return { ok: true, name: s.name, path: r, text };
749
+ }
750
+
751
+ function tools() {
752
+ return [
753
+ { name: names.list, description: 'Find skills by keyword. Returns the name and a short description of each match; with no query, lists every skill.',
754
+ parameters: { type: 'object', properties: { query: { type: 'string', description: 'words to search for' }, limit: { type: 'integer', minimum: 1, maximum: 50 }, offset: { type: 'integer', minimum: 0 } }, additionalProperties: false },
755
+ run: (a = {}) => list(a.query || '', { limit: a.limit, offset: a.offset }) },
756
+ { name: names.view, description: "Read a skill's instructions (SKILL.md). Pass path to read one file inside the skill folder, such as references/guide.md.",
757
+ parameters: { type: 'object', properties: { name: { type: 'string' }, path: { type: 'string' } }, required: ['name'], additionalProperties: false },
758
+ run: (a = {}) => view(a.name, a.path || null) },
759
+ ];
760
+ }
761
+
762
+ // §34.3 — mid-session changes: rescan, report the difference, keep the frozen index (prompt cache)
763
+ function refresh({ rebuild = false } = {}) {
764
+ const before = new Map([...state.visible].map(([n, s]) => [n, s.hash]));
765
+ state = scan();
766
+ const after = new Map([...state.visible].map(([n, s]) => [n, s.hash]));
767
+ const added = [...after.keys()].filter((n) => !before.has(n)).sort();
768
+ const removed = [...before.keys()].filter((n) => !after.has(n)).sort();
769
+ const changed = [...after.keys()].filter((n) => before.has(n) && before.get(n) !== after.get(n)).sort();
770
+ if (rebuild) index({ rebuild: true });
771
+ const parts = [];
772
+ if (added.length) parts.push(`added ${added.join(', ')}`);
773
+ if (removed.length) parts.push(`removed ${removed.join(', ')}`);
774
+ if (changed.length) parts.push(`updated ${changed.join(', ')}`);
775
+ const notice = parts.length ? `Skills changed since this session started: ${parts.join('; ')}. Use ${names.list} to see them.` : '';
776
+ if (notice) emit('skills_changed', { added, removed, changed });
777
+ return { added, removed, changed, notice };
778
+ }
779
+
780
+ function report() {
781
+ const row = (r) => ({ name: r.name, source: r.source, kind: r.sourceKind, trust: r.trust, state: r.state || (r.errors && r.errors.length ? 'invalid' : 'shadowed'), reason: r.reason || '', compat: r.compat || null, unmet: r.unmet || [], hash: r.hash, dir: r.dir, errors: r.errors || [], warnings: r.warnings || [], security: r.security ? { verdict: r.security.verdict, findings: r.security.findings.map((f) => ({ rule: f.rule, severity: f.severity, file: f.file, line: f.line })) } : { verdict: 'unscanned', findings: [] }, requires: (r.requirements || []).map((q) => ({ ref: q.ref, cap: q.cap, hard: q.hard, via: q.via })) });
782
+ return {
783
+ sources: sources.map((s) => ({ id: s.id, kind: s.kind, path: s.display || s.path, trust: s.trust, layout: s.layout || 'dir', exists: fs.existsSync(s.path) })),
784
+ visible: sortedVisible().map(row),
785
+ gated: state.gated.map(row).sort((a, b) => (a.name < b.name ? -1 : 1)),
786
+ invalid: state.invalid.map((r) => ({ ...row(r), state: 'invalid', name: r.name || path.basename(r.dir) })),
787
+ shadowed: state.shadowed.map((r) => ({ name: r.name, source: r.source, by: r.by, dir: r.dir })),
788
+ };
789
+ }
790
+
791
+ return {
792
+ sources, index, list, view, tools, refresh, report,
793
+ get: (name) => state.visible.get(name) || null,
794
+ names: () => sortedVisible().map((s) => s.name),
795
+ usage: () => ({ ...usage }),
796
+ };
797
+ }
798
+
799
+ // ── §36.1 check (what `scroll check` adds) ────────────────────────────────────────────────────
800
+ // Skills this repo ships must be valid and clean; another tool's skills only inform.
801
+ export function checkSkills(cwd = process.cwd(), agent = null, opts = {}) {
802
+ const reg = openSkills({ cwd, agent, compatFile: false, ...opts });
803
+ const rep = reg.report();
804
+ const errors = [], warnings = [];
805
+ const own = (r) => r.kind === 'agent' || r.kind === 'repo';
806
+ for (const r of rep.invalid) (own(r) ? errors : warnings).push(...r.errors.map((e) => `skill ${r.name} (${r.source}): ${e}`));
807
+ for (const r of [...rep.visible, ...rep.gated]) {
808
+ if (own(r)) {
809
+ warnings.push(...r.warnings.map((w) => `skill ${r.name}: ${w}`));
810
+ if (r.state === 'blocked') errors.push(`skill ${r.name}: blocked by the security scan — ${r.reason}`);
811
+ else for (const f of r.security.findings.filter((x) => x.severity !== 'low')) warnings.push(`skill ${r.name}: ${f.rule} (${f.severity}) at ${f.file}:${f.line}`);
812
+ }
813
+ }
814
+ for (const r of rep.visible.filter(own)) {
815
+ const n = countEvalCases(r.dir);
816
+ if (n < 3) warnings.push(`skill ${r.name}: ${n} eval case(s) in evals/ — add at least 3 and run \`scroll skill eval ${r.name}\` (§36.3)`);
817
+ }
818
+ const ext = [...rep.visible, ...rep.gated].filter((r) => !own(r));
819
+ const extBlocked = ext.filter((r) => r.state === 'blocked');
820
+ if (extBlocked.length) warnings.push(`${extBlocked.length} external skill(s) blocked by the security scan and kept out: ${extBlocked.slice(0, 5).map((r) => r.name).join(', ')}${extBlocked.length > 5 ? ', …' : ''}`);
821
+ const extInvalid = rep.invalid.filter((r) => !own(r));
822
+ if (extInvalid.length) warnings.push(`${extInvalid.length} external skill(s) invalid and kept out: ${extInvalid.slice(0, 5).map((r) => r.name).join(', ')}${extInvalid.length > 5 ? ', …' : ''}`);
823
+ return { errors, warnings, report: rep, counts: { visible: rep.visible.length, hidden: rep.gated.filter((r) => r.state === 'hidden').length, blocked: rep.gated.filter((r) => r.state === 'blocked').length, invalid: rep.invalid.length, shadowed: rep.shadowed.length } };
824
+ }
825
+
826
+ function countEvalCases(dir) {
827
+ const ev = path.join(dir, 'evals');
828
+ if (!fs.existsSync(ev)) return 0;
829
+ let n = fs.readdirSync(ev).filter((f) => f.endsWith('.md') && f !== 'rubric.md').length;
830
+ try { n += arr(JSON.parse(fs.readFileSync(path.join(ev, 'evals.json'), 'utf8')).evals).length; } catch { /* none */ }
831
+ return n;
832
+ }
833
+
834
+ // ── §35.2 the compatibility sidecar (`scroll skill scan`) ────────────────────────────────────
835
+ // Machine-written status per skill; a human's `overrides` survive every rescan.
836
+ export function writeCompatFile(file, registry, { runtime = null } = {}) {
837
+ let prev = {}; try { prev = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* new file */ }
838
+ const rep = registry.report();
839
+ const skills = {};
840
+ for (const r of [...rep.visible, ...rep.gated]) {
841
+ skills[r.name] = { source: r.source, trust: r.trust, hash: r.hash, state: r.state, compat: r.compat, reason: r.reason || undefined, unmet: r.unmet.length ? r.unmet : undefined, requires: r.requires.length ? r.requires.map((q) => q.ref) : undefined, security: r.security.verdict };
842
+ }
843
+ const out = { generatedBy: '@agentpro/scroll skill scan', runtime, skills, overrides: prev.overrides || {} };
844
+ fs.mkdirSync(path.dirname(file), { recursive: true });
845
+ fs.writeFileSync(file, JSON.stringify(out, null, 2) + '\n');
846
+ return out;
847
+ }
848
+
849
+ // Parse TOOLS.md tool_bindings (§5.2) → toolFor(capability) for one runtime.
850
+ export function bindingsToolFor(toolsMd, runtime) {
851
+ if (!toolsMd || !runtime) return () => null;
852
+ const blocks = [...String(toolsMd).matchAll(/```ya?ml\n([\s\S]*?)```/g)].map((m) => m[1]);
853
+ const map = {};
854
+ for (const b of blocks.length ? blocks : [String(toolsMd)]) {
855
+ let y; try { y = parseYaml(b); } catch { continue; }
856
+ if (!y || typeof y !== 'object') continue;
857
+ for (const [cap, v] of Object.entries(y)) if (CAP_SHAPE.test(cap) && v && typeof v === 'object' && typeof v[runtime] === 'string') map[cap] = v[runtime];
858
+ }
859
+ return (cap) => map[cap] || null;
860
+ }