@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
@@ -0,0 +1,356 @@
1
+ // SCROLL — grounding / provenance pre-check (v1.4) + reply grounding (v1.9 §43).
2
+ //
3
+ // Why: blocks hallucination at the ACTION and REPLY boundary.
4
+ // - Action grounding (v1.4): before a financial or destructive tool runs, declared params must
5
+ // trace to prior sources.
6
+ // - Reply grounding (v1.9): before an external reply leaves, every amount, product code, date,
7
+ // and link must trace to PRINCIPAL-authored sources ONLY (retrieved knowledge chunks, USER.md
8
+ // "May say on behalf", tool outputs — NEVER customer messages). Same-line code-to-amount pairs
9
+ // must match; risky unverified claims (percentages, clock times, relative dates, inventory
10
+ // claims, spelled-out numbers) are held for human review.
11
+ //
12
+ // Deliberately DETERMINISTIC, zero dependencies, pure ASCII source. Node >= 20.
13
+
14
+ // Build the corpus a parameter may be grounded against (internal action grounding).
15
+ export function collectSources({ depSummaries = [], objective = '', steer = '', priorOutputs = [], extra = [] } = {}) {
16
+ return [objective, steer, ...depSummaries, ...priorOutputs, ...extra].filter(Boolean).join('\n');
17
+ }
18
+
19
+ // v1.9 §43: build the corpus an EXTERNAL REPLY may be grounded against.
20
+ // Principal-authored text ONLY — customer chat history is intentionally excluded so a customer
21
+ // cannot inject a price ("you quoted 90k") and make the bot's echo look grounded.
22
+ export function collectPrincipalSources({ knowledgeChunks = [], maySay = '', toolOutputs = [], extra = [] } = {}) {
23
+ const arr = (x) => (Array.isArray(x) ? x : x ? [x] : []);
24
+ return [...arr(knowledgeChunks), maySay, ...arr(toolOutputs), ...arr(extra)].filter(Boolean).join('\n');
25
+ }
26
+
27
+ // Normalize for action-param matching: lowercase, collapse to alphanumerics.
28
+ function norm(s) { return String(s).toLowerCase().replace(/[^a-z0-9]+/g, ''); }
29
+ function digitsOnly(s) { return String(s).replace(/[^0-9]/g, ''); }
30
+ function looksNumeric(v) { return /[0-9]/.test(String(v)) && /^[0-9.,\s]*[0-9][0-9.,\s]*(?:[a-z]{0,4})$/i.test(String(v).trim()); }
31
+
32
+ // Is a single value present in the source corpus?
33
+ export function isGrounded(value, sourcesText) {
34
+ if (value == null || value === '') return true;
35
+ const src = String(sourcesText || '');
36
+ const nv = norm(value);
37
+ if (nv && norm(src).includes(nv)) return true;
38
+ if (looksNumeric(value)) {
39
+ const dv = digitsOnly(value);
40
+ if (dv && digitsOnly(src).includes(dv)) return true;
41
+ }
42
+ return false;
43
+ }
44
+
45
+ // params: array of { name, value } OR a plain object { name: value }.
46
+ export function checkGrounding(params, sourcesText) {
47
+ const list = Array.isArray(params)
48
+ ? params
49
+ : Object.entries(params || {}).map(([name, value]) => ({ name, value }));
50
+ const traced = [], missing = [];
51
+ for (const { name, value } of list) {
52
+ if (isGrounded(value, sourcesText)) traced.push(name);
53
+ else missing.push(name);
54
+ }
55
+ return { ok: missing.length === 0, traced, missing };
56
+ }
57
+
58
+ // ── v1.9 §43: claims inside a free-text reply ──────────────────────────────────────────────────
59
+ export const REPLY_KINDS = ['amount', 'code', 'date', 'link'];
60
+
61
+ // Fold diacritics to ASCII so international currencies/phrases match without raw non-ASCII in code
62
+ function foldAscii(text) {
63
+ return String(text ?? '')
64
+ .normalize('NFD')
65
+ .replace(/[\u0300-\u036f]/g, '')
66
+ .replace(/\u0111/g, 'd')
67
+ .replace(/\u0110/g, 'D');
68
+ }
69
+
70
+ // "1.500.000", "1,500.50", "1,2", 1500 -> number
71
+ export function parseAmount(x) {
72
+ if (typeof x === 'number') return Number.isFinite(x) ? x : null;
73
+ if (x == null) return null;
74
+ let s = String(x).replace(/[^\d.,-]/g, '');
75
+ if (!/\d/.test(s)) return null;
76
+ const dot = s.lastIndexOf('.'), comma = s.lastIndexOf(',');
77
+ if (dot >= 0 && comma >= 0) {
78
+ const dec = dot > comma ? '.' : ',';
79
+ s = s.split(dec === '.' ? ',' : '.').join('').replace(dec, '.');
80
+ } else if (dot >= 0 || comma >= 0) {
81
+ const parts = s.split(dot >= 0 ? '.' : ',');
82
+ s = (parts.length > 2 || parts[parts.length - 1].length === 3) ? parts.join('') : parts.join('.');
83
+ }
84
+ const n = Number(s);
85
+ return Number.isFinite(n) ? n : null;
86
+ }
87
+
88
+ const NUM = String.raw`\d{1,3}(?:[.,]\d{3})+(?:[.,]\d{1,2})?|\d+(?:[.,]\d{1,2})?`;
89
+ const MULT = {
90
+ k: 1e3, thousand: 1e3, nghin: 1e3, ngan: 1e3,
91
+ tr: 1e6, trieu: 1e6, m: 1e6, million: 1e6,
92
+ };
93
+ // Currency suffixes (uses Unicode escapes \u0111 / \u20ab / \u20ac / \u00a3 for pure ASCII source)
94
+ const SUFFIX_CUR = String.raw`(?:dong|\u0111|\u20ab|vnd|usd|eur|\u20ac|\u00a3|dollars?|bucks?|k|thousand|nghin|ngan|million|trieu|tr)`;
95
+ const END = String.raw`(?![\p{L}\p{N}])`;
96
+ const START = String.raw`(?<![\p{L}\p{N}.,/:-])`;
97
+ const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
98
+ const MON = String.raw`(jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?`;
99
+
100
+ const RE = {
101
+ link: /\bhttps?:\/\/[^\s<>"')\]`]+|\bwww\.[^\s<>"')\]`]+/giu,
102
+ dateIso: new RegExp(`${START}(\\d{4})-(\\d{1,2})-(\\d{1,2})${END}`, 'gu'),
103
+ dateNum: new RegExp(`${START}(\\d{1,2})([/-])(\\d{1,2})(?:\\2(\\d{4}|\\d{2}))?${END}|${START}(\\d{1,2})\\.(\\d{1,2})\\.(\\d{4})${END}`, 'gu'),
104
+ dateFoldedVi: new RegExp(`ngay\\s+(\\d{1,2})\\s*(?:thang|/)\\s*(\\d{1,2})(?:\\s*(?:nam|/)\\s*(\\d{4}))?${END}`, 'giu'),
105
+ dateEn1: new RegExp(`${START}(\\d{1,2})(?:st|nd|rd|th)?\\s+(?:of\\s+)?${MON}(?:,?\\s+(\\d{4}))?${END}`, 'giu'),
106
+ dateEn2: new RegExp(`${START}${MON}\\s+(\\d{1,2})(?:st|nd|rd|th)?(?:,?\\s+(\\d{4}))?${END}`, 'giu'),
107
+ amountPre: new RegExp(`(?:US\\$|\\$|\u20ac|\u00a3)\\s?(${NUM})${END}`, 'gu'),
108
+ amountSuf: new RegExp(`${START}(${NUM})\\s?(${SUFFIX_CUR})${END}`, 'giu'),
109
+ amountSep: new RegExp(`${START}(\\d{1,3}(?:[.,]\\d{3})+(?:[.,]\\d{1,2})?)${END}`, 'gu'),
110
+ amountBare: new RegExp(`${START}(\\d{4,})${END}`, 'gu'),
111
+ code: /(?<![\p{L}\p{N}_-])(?:(?=[A-Z0-9_-]*\d)(?=[A-Z0-9_-]*[A-Z])[A-Z0-9]+(?:[-_][A-Z0-9]+)*|[A-Z]{2,5}(?:-[A-Z0-9]{2,6})+)(?![\p{L}\p{N}_-])/gu,
112
+ };
113
+
114
+ // Lines explicitly marked as expired/invalid/trap examples must NOT authorize quoted amounts (§44)
115
+ const EXCLUDED_AMOUNT_LINE_RE = /\b(?:expired|invalid|do\s+not\s+honor|do\s+not\s+apply|do\s+not\s+promise|never\s+offer|trap|da\s+het\s+han|het\s+han\s+tu|gia\s+mao|khong\s+ton\s+tai|tuyet\s+doi\s+khong\s+ap\s+dung|khong\s+tu\s+hua|bay\s+gia)\b/i;
116
+ const NEGATED_CLAIM_RE = /\b(?:cannot|can't|unable\s+to|not\s+offer|not\s+approve|no\s+discount|chua\s+the|khong\s+the|khong\s+ap\s+dung|khong\s+giam|chua\s+duoc\s+duyet|khong\s+duyet)\b/i;
117
+ const DISCOUNT_PERCENT_RE = /\b(?:discount|off|promo|coupon|voucher|giam(?:\s+gia|\s+ngay|\s+them)?|chiet\s+khau|uu\s+dai)\b/i;
118
+
119
+ // Risky / ungroundable claim classes held for human review (§43, source-aware time/percent in v1.10 §44)
120
+ const HOLD_PATTERNS = [
121
+ { kind: 'percent', re: /\b\d+(?:[.,]\d+)?\s*(?:%|(?:percent|pct|phan\s+tram)\b)/gi },
122
+ { kind: 'time', re: /\b(?:[01]?\d|2[0-3]):[0-5]\d(?:\s*(?:am|pm))?\b|\b(?:1[0-2]|[1-9])\s*(?:am|pm)\b|\b(?:[01]?\d|2[0-3])h(?:[0-5]\d)?\b/gi },
123
+ { kind: 'relative_date', re: /\b(?:today|tomorrow|tonight|this\s+(?:morning|afternoon|evening|week)|next\s+(?:day|week|month|monday|tuesday|wednesday|thursday|friday|saturday|sunday)|in\s+\d+\s+(?:hours?|days?|weeks?)|hom\s+nay|ngay\s+mai|ngay\s+kia|chieu\s+nay|toi\s+nay|tuan\s+sau|thang\s+sau)\b/i },
124
+ { kind: 'inventory', re: /\b(?:in\s+stock|out\s+of\s+stock|backordered|sold\s+out|only\s+\d+\s+(?:left|remaining|in\s+stock|rooms?|seats?|tables?|slots?)|still\s+available\s+in\s+stock|\d+\s+(?:rooms?|seats?|tables?|slots?)\s+(?:left|remaining|available)|con\s+hang|het\s+hang|ton\s+kho|con\s+(?:phong\s+trong|cho\s+trong)|con\s+\d+\s+(?:cai|chiec|suat|hop|phong(?:\s+trong)?|cho(?:\s+trong)?|ban(?:\s+trong)?|ve|ghe|slot))\b/i },
125
+ { kind: 'written_number', re: /\b(?:twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety|hundred|thousand|million)\s+(?:dollars?|bucks?|usd|eur|vnd|off|each|per)\b|\b(?:one|two|three|four|five|six|seven|eight|nine|ten|fifteen|twenty|fifty)\s+(?:hundred|thousand|million)\b|\b(?:mot|hai|ba|bon|nam|sau|bay|tam|chin|muoi)\s+(?:chuc|tram|nghin|ngan|trieu)\b/i },
126
+ ];
127
+
128
+ const monthNo = (s) => MONTHS.indexOf(String(s).toLowerCase().slice(0, 3)) + 1;
129
+ const fullYear = (y) => (y == null ? null : (String(y).length === 2 ? 2000 + Number(y) : Number(y)));
130
+ const okDate = (m, d) => m >= 1 && m <= 12 && d >= 1 && d <= 31;
131
+ const mask = (s, i, len) => s.slice(0, i) + ' '.repeat(len) + s.slice(i + len);
132
+
133
+ // Extract structured claims: links -> dates -> amounts -> codes (masked sequentially to prevent overlap).
134
+ export function extractClaims(text, { kinds = REPLY_KINDS, dateOrder = 'dmy' } = {}) {
135
+ const raw = String(text ?? '');
136
+ let s = raw;
137
+ const claims = [];
138
+ const take = (re, fn, target = null) => {
139
+ const src = target ?? s;
140
+ for (const m of [...src.matchAll(re)]) {
141
+ const c = fn(m);
142
+ if (c) claims.push({ ...c, text: m[0], index: m.index });
143
+ if (c !== false && !target) s = mask(s, m.index, m[0].length);
144
+ }
145
+ };
146
+ take(RE.link, (m) => ({ kind: 'link', value: m[0].replace(/[.,;:!?]+$/, '') }));
147
+ const date = (y, m, d) => (okDate(m, d) ? { kind: 'date', value: { y: fullYear(y), m, d } } : null);
148
+ take(RE.dateIso, (m) => date(m[1], +m[2], +m[3]));
149
+ // Check folded Vietnamese "ngay DD thang MM" without mutating character offsets
150
+ {
151
+ const folded = foldAscii(s);
152
+ for (const m of [...folded.matchAll(RE.dateFoldedVi)]) {
153
+ const c = date(m[3], +m[2], +m[1]);
154
+ if (c) {
155
+ claims.push({ ...c, text: raw.slice(m.index, m.index + m[0].length), index: m.index });
156
+ s = mask(s, m.index, m[0].length);
157
+ }
158
+ }
159
+ }
160
+ take(RE.dateEn1, (m) => date(m[3], monthNo(m[2]), +m[1]));
161
+ take(RE.dateEn2, (m) => date(m[3], monthNo(m[1]), +m[2]));
162
+ take(RE.dateNum, (m) => {
163
+ if (m[5]) return date(m[7], +m[6], +m[5]);
164
+ const a = +m[1], b = +m[3];
165
+ return dateOrder === 'mdy' ? date(m[4], a, b) : date(m[4], b, a);
166
+ });
167
+ const amount = (rawVal, mult = 1) => { const v = parseAmount(rawVal); return v == null ? null : { kind: 'amount', value: v * mult }; };
168
+ take(RE.amountPre, (m) => amount(m[1]));
169
+ // Match amountSuf on folded string so diacritic currency words normalize cleanly
170
+ {
171
+ const folded = foldAscii(s);
172
+ for (const m of [...folded.matchAll(RE.amountSuf)]) {
173
+ const suf = String(m[2]).toLowerCase();
174
+ const c = amount(m[1], MULT[suf] || 1);
175
+ if (c) {
176
+ claims.push({ ...c, text: raw.slice(m.index, m.index + m[0].length), index: m.index });
177
+ s = mask(s, m.index, m[0].length);
178
+ }
179
+ }
180
+ }
181
+ take(RE.amountSep, (m) => amount(m[1]));
182
+ take(RE.amountBare, (m) => { const n = Number(m[1]); return n >= 1900 && n <= 2100 ? false : amount(m[1]); });
183
+ take(RE.code, (m) => (m[0].length >= 3 ? { kind: 'code', value: m[0].toUpperCase() } : false));
184
+ return claims.filter((c) => kinds.includes(c.kind)).sort((a, b) => a.index - b.index);
185
+ }
186
+
187
+ function normPercentToken(s) {
188
+ const m = String(s ?? '').match(/(\d+(?:[.,]\d+)?)/);
189
+ return m ? String(parseAmount(m[1])) : null;
190
+ }
191
+
192
+ function normTimeToken(s) {
193
+ const raw = String(s ?? '').trim().toLowerCase();
194
+ const hm = raw.match(/^([01]?\d|2[0-3])[:h]([0-5]\d)?\s*(am|pm)?$/);
195
+ if (hm) {
196
+ let hr = Number(hm[1]);
197
+ const min = hm[2] ? Number(hm[2]) : 0;
198
+ if (hm[3] === 'pm' && hr < 12) hr += 12;
199
+ if (hm[3] === 'am' && hr === 12) hr = 0;
200
+ return `${String(hr).padStart(2, '0')}:${String(min).padStart(2, '0')}`;
201
+ }
202
+ const ap = raw.match(/^(1[0-2]|[1-9])\s*(am|pm)$/);
203
+ if (ap) {
204
+ let hr = Number(ap[1]);
205
+ if (ap[2] === 'pm' && hr < 12) hr += 12;
206
+ if (ap[2] === 'am' && hr === 12) hr = 0;
207
+ return `${String(hr).padStart(2, '0')}:00`;
208
+ }
209
+ return raw;
210
+ }
211
+
212
+ // Index source text including same-line code -> amount pairs (§43) and source-grounded times/percents (§44)
213
+ export function indexSources(text, { dateOrder = 'dmy' } = {}) {
214
+ const src = String(text ?? '');
215
+ const idx = {
216
+ amounts: new Set(), codes: new Set(), dates: [], links: new Set(),
217
+ codeAmounts: new Map(), times: new Set(), percents: new Set(),
218
+ };
219
+ const lines = src.split('\n');
220
+ const activeLines = [];
221
+ for (const line of lines) {
222
+ const foldedLine = foldAscii(line);
223
+ const isExcludedPricingLine = EXCLUDED_AMOUNT_LINE_RE.test(foldedLine);
224
+ // Dates, links, and codes still register (so the agent can accurately explain an expiry date/code)
225
+ for (const c of extractClaims(line, { kinds: isExcludedPricingLine ? ['date', 'link', 'code'] : REPLY_KINDS, dateOrder })) {
226
+ if (c.kind === 'date') idx.dates.push(c.value);
227
+ else if (c.kind === 'link') idx.links.add(c.value);
228
+ else if (c.kind === 'amount') idx.amounts.add(c.value);
229
+ }
230
+ for (const t of line.match(/[\p{L}\p{N}_-]+/gu) || []) idx.codes.add(t.toUpperCase());
231
+ if (isExcludedPricingLine) continue;
232
+ activeLines.push(line);
233
+
234
+ // Line-level pairing: only bind code -> amount when a line names exactly 1 code
235
+ // (prevents multi-code FAQ prose lines from polluting a single SKU's published tariff row)
236
+ const lc = extractClaims(line, { kinds: ['code', 'amount'], dateOrder });
237
+ const codes = [...new Set(lc.filter((c) => c.kind === 'code').map((c) => c.value))];
238
+ const amts = lc.filter((c) => c.kind === 'amount').map((c) => c.value);
239
+ if (codes.length === 1 && amts.length) {
240
+ const code = codes[0];
241
+ if (!idx.codeAmounts.has(code)) idx.codeAmounts.set(code, new Set());
242
+ for (const a of amts) idx.codeAmounts.get(code).add(a);
243
+ }
244
+ }
245
+ const activeText = foldAscii(activeLines.join('\n'));
246
+ const numRe = new RegExp(`${START}(${NUM})(?:\\s?(${SUFFIX_CUR}))?${END}`, 'giu');
247
+ for (const m of activeText.matchAll(numRe)) {
248
+ const v = parseAmount(m[1]); if (v == null) continue;
249
+ idx.amounts.add(v);
250
+ const mult = m[2] && MULT[String(m[2]).toLowerCase()];
251
+ if (mult) idx.amounts.add(v * mult);
252
+ }
253
+ for (const m of activeText.matchAll(HOLD_PATTERNS[0].re)) {
254
+ const p = normPercentToken(m[0]);
255
+ if (p) idx.percents.add(p);
256
+ }
257
+ for (const m of activeText.matchAll(HOLD_PATTERNS[1].re)) {
258
+ const t = normTimeToken(m[0]);
259
+ if (t) idx.times.add(t);
260
+ }
261
+ return idx;
262
+ }
263
+
264
+ function traced(c, idx) {
265
+ if (c.kind === 'amount') return idx.amounts.has(c.value);
266
+ if (c.kind === 'code') return idx.codes.has(c.value);
267
+ if (c.kind === 'link') return idx.links.has(c.value);
268
+ if (c.kind === 'date') return idx.dates.some((d) => d.m === c.value.m && d.d === c.value.d && (d.y == null || c.value.y == null || d.y === c.value.y));
269
+ return false;
270
+ }
271
+
272
+ // Detect same-line / same-sentence code-to-amount mismatches against source lines
273
+ function findPairMismatches(text, idx, dateOrder) {
274
+ const mismatches = [];
275
+ const clauses = String(text ?? '').split(/[\n;!?]+|(?:\.\s+)/);
276
+ for (const clause of clauses) {
277
+ const lc = extractClaims(clause, { kinds: ['code', 'amount'], dateOrder });
278
+ const codes = lc.filter((c) => c.kind === 'code');
279
+ const amts = lc.filter((c) => c.kind === 'amount');
280
+ if (codes.length !== 1 || !amts.length) continue;
281
+ const code = codes[0].value;
282
+ const allowed = idx.codeAmounts.get(code);
283
+ if (!allowed || allowed.size === 0) continue;
284
+ for (const a of amts) {
285
+ if (!allowed.has(a.value)) {
286
+ mismatches.push({ kind: 'pair_mismatch', code, amount: a.value, text: `${codes[0].text} <-> ${a.text}`, expected: [...allowed] });
287
+ }
288
+ }
289
+ }
290
+ return mismatches;
291
+ }
292
+
293
+ // Detect hold-trigger classes (percentages, clock times, relative dates, inventory, written numbers)
294
+ // When `sourceIndex` is supplied (v1.10 §44), clock times and percentages verbatim in principal
295
+ // sources (e.g., published check-in 14:00 or 8% VAT) pass without false-positive holds, and
296
+ // explicit refusals of customer-demanded percentages ("cannot approve 20%") are not false-held.
297
+ export function detectHoldClaims(text, sourceIndex = null) {
298
+ const folded = foldAscii(text);
299
+ const held = [];
300
+ for (const { kind, re } of HOLD_PATTERNS) {
301
+ if (kind === 'percent') {
302
+ for (const m of folded.matchAll(re)) {
303
+ const prefix = folded.slice(Math.max(0, m.index - 45), m.index);
304
+ if (NEGATED_CLAIM_RE.test(prefix)) continue;
305
+ const window = folded.slice(Math.max(0, m.index - 35), Math.min(folded.length, m.index + m[0].length + 25));
306
+ const isDiscountClaim = DISCOUNT_PERCENT_RE.test(window);
307
+ const tok = normPercentToken(m[0]);
308
+ if (!isDiscountClaim && sourceIndex && sourceIndex.percents && tok && sourceIndex.percents.has(tok)) continue;
309
+ held.push({ kind, text: m[0] });
310
+ break;
311
+ }
312
+ } else if (kind === 'time') {
313
+ for (const m of folded.matchAll(re)) {
314
+ const tok = normTimeToken(m[0]);
315
+ if (sourceIndex && sourceIndex.times && tok && sourceIndex.times.has(tok)) continue;
316
+ held.push({ kind, text: m[0] });
317
+ break;
318
+ }
319
+ } else {
320
+ const m = folded.match(re);
321
+ if (m) held.push({ kind, text: m[0] });
322
+ }
323
+ }
324
+ return held;
325
+ }
326
+
327
+ // Does every claim in an external reply trace to principal sources, with matching code-amount pairs
328
+ // and zero unverified hold triggers? Returns { ok, claims, missing, pairMismatches, held }.
329
+ export function groundReply(text, sourcesText, {
330
+ kinds = REPLY_KINDS,
331
+ dateOrder = 'dmy',
332
+ checkPairs = true,
333
+ checkHoldTriggers = true,
334
+ } = {}) {
335
+ const ks = kinds.filter((k) => REPLY_KINDS.includes(k));
336
+ const idx = indexSources(sourcesText, { dateOrder });
337
+ const claims = extractClaims(text, { kinds: ks, dateOrder }).map((c) => ({ kind: c.kind, value: c.value, text: c.text, traced: traced(c, idx) }));
338
+ const missing = claims.filter((c) => !c.traced);
339
+ const pairMismatches = checkPairs ? findPairMismatches(text, idx, dateOrder) : [];
340
+ const held = checkHoldTriggers ? detectHoldClaims(text, idx) : [];
341
+ const ok = missing.length === 0 && pairMismatches.length === 0 && held.length === 0;
342
+ return { ok, claims, missing, pairMismatches, held };
343
+ }
344
+
345
+ // §6b / §43 invariant: formatting / voice shaping MUST preserve the exact multiset of
346
+ // (amount, code, date, link) claims between rawText and shapedText.
347
+ function claimKey(c) {
348
+ if (c.kind === 'date') return `date:${c.value.y ?? '*'}-${c.value.m}-${c.value.d}`;
349
+ return `${c.kind}:${c.value}`;
350
+ }
351
+ export function verifyClaimsInvariant(beforeText, afterText, { dateOrder = 'dmy' } = {}) {
352
+ const before = extractClaims(beforeText, { kinds: REPLY_KINDS, dateOrder }).map(claimKey).sort();
353
+ const after = extractClaims(afterText, { kinds: REPLY_KINDS, dateOrder }).map(claimKey).sort();
354
+ const ok = before.length === after.length && before.every((v, i) => v === after[i]);
355
+ return { ok, before, after };
356
+ }
@@ -0,0 +1,176 @@
1
+ // SCROLL — extension installers (v1.4): `scroll mcp add` · `scroll skill add` · `scroll plugin add`.
2
+ //
3
+ // These are the package-manager sugar for an agent: they WIRE capabilities declaratively, they do
4
+ // not ship implementations. MCP-first — tool implementations come from the MCP server; a skill is a
5
+ // SKILL.md folder; a plugin is an agent-pack bundle. All they do is edit files (.mcp.json, skills/,
6
+ // agents/) the runtime already reads. Zero-dep (the `unzip` CLI is used only for a .plugin ZIP;
7
+ // an unpacked plugin directory needs nothing).
8
+ import fs from 'node:fs';
9
+ import os from 'node:os';
10
+ import path from 'node:path';
11
+ import { spawnSync } from 'node:child_process';
12
+ import { parseSkillMd, validateSkill, scanSkillDir } from './skills.js';
13
+ import { scanForPeople } from './people.js';
14
+
15
+ const NAME_RE = /^[a-z][a-z0-9-]*$/;
16
+ function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } }
17
+ function writeJson(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n'); }
18
+ function vaultRefs(env) {
19
+ if (!env) return [];
20
+ return Object.values(env).map(String).filter((v) => /^\$\{vault:.+\}$/.test(v)).map((v) => v.replace(/^\$\{vault:(.+)\}$/, '$1'));
21
+ }
22
+
23
+ // ── scroll mcp add <name> ─────────────────────────────────────────────────────
24
+ // Declare an MCP server / connector in .mcp.json (repo-level, or agent-level with opts.agent).
25
+ // Credentials are referenced as ${vault:KEY} (resolved at load, never written into the file).
26
+ // Per-tool risk/grounding (v1.4 §21) lives under server.tools.
27
+ export function mcpAdd(name, opts = {}, cwd = process.cwd()) {
28
+ if (!NAME_RE.test(name || '')) throw new Error(`mcp name "${name}" must match ${NAME_RE}`);
29
+ const file = opts.agent ? path.join(cwd, 'agents', opts.agent, '.mcp.json') : path.join(cwd, '.mcp.json');
30
+ if (opts.agent && !fs.existsSync(path.join(cwd, 'agents', opts.agent))) throw new Error(`agent not found: agents/${opts.agent}/`);
31
+ const json = readJson(file) || { mcpServers: {} };
32
+ json.mcpServers = json.mcpServers || {};
33
+ const existed = !!json.mcpServers[name];
34
+
35
+ let server;
36
+ if (opts.url) server = { type: opts.transport || 'http', url: opts.url };
37
+ else server = { command: opts.command || name, args: Array.isArray(opts.args) ? opts.args : [] };
38
+ if (opts.env && Object.keys(opts.env).length) server.env = opts.env;
39
+ if (opts.tools && Object.keys(opts.tools).length) server.tools = opts.tools;
40
+
41
+ // merge: keep existing fields (e.g. previously-added tools/env) unless this call overrides them
42
+ json.mcpServers[name] = { ...(json.mcpServers[name] || {}), ...server };
43
+ writeJson(file, json);
44
+ return { file: path.relative(cwd, file) || file, name, existed, server: json.mcpServers[name], vaultRefs: vaultRefs(server.env) };
45
+ }
46
+
47
+ // ── scroll skill add <ref|--new name> ─────────────────────────────────────────
48
+ // A skill is a SKILL.md folder. Install it onto the repo search path (skills/<name>/), optionally
49
+ // attach it to an agent (IDENTITY.skills). --new scaffolds a stub.
50
+ export function skillAdd(ref, opts = {}, cwd = process.cwd()) {
51
+ const skillsDir = path.join(cwd, 'skills');
52
+ fs.mkdirSync(skillsDir, { recursive: true });
53
+
54
+ if (opts.new) {
55
+ const name = ref;
56
+ if (!NAME_RE.test(name || '')) throw new Error(`skill name "${name}" must match ${NAME_RE}`);
57
+ const dest = path.join(skillsDir, name);
58
+ if (fs.existsSync(dest)) throw new Error(`skills/${name}/ already exists`);
59
+ fs.mkdirSync(dest, { recursive: true });
60
+ fs.writeFileSync(path.join(dest, 'SKILL.md'), skillStub(name));
61
+ return { name, dir: path.relative(cwd, dest) || dest, scaffolded: true, attachedToAgent: opts.agent ? attachSkillToAgent(cwd, opts.agent, name) : null };
62
+ }
63
+
64
+ const srcDir = path.resolve(cwd, ref || '');
65
+ const skillMd = path.join(srcDir, 'SKILL.md');
66
+ if (!fs.existsSync(skillMd)) throw new Error(`no SKILL.md in "${ref}" — a skill is a folder containing SKILL.md`);
67
+ // v1.8 §36: the open Agent Skills format (name + description), then the security scan. Installing
68
+ // copies the skill into the repo, so it is held to the repo's bar; --force overwrites, it never
69
+ // lets a blocked skill in.
70
+ const parsed = parseSkillMd(fs.readFileSync(skillMd, 'utf8'));
71
+ const fm = parsed.frontmatter || {};
72
+ const v = validateSkill({ dir: srcDir, frontmatter: parsed.frontmatter, body: parsed.body, parseError: parsed.error }, { strict: false });
73
+ if (v.errors.length) throw new Error(`SKILL.md is not a valid skill: ${v.errors.join('; ')}`);
74
+ const name = fm.name;
75
+ // v1.9 §41: a shared skill never carries a person (card, USER.md, people/)
76
+ const ppl = scanForPeople(srcDir);
77
+ if (ppl.length) throw new Error(`skill "${name}" carries people (${ppl.map((h) => h.file).join(', ')}) — person cards live in the deployment's people dir, never in a shared package`);
78
+ const sec = scanSkillDir(srcDir, opts.trust || 'community');
79
+ if (sec.verdict === 'block') throw new Error(`skill "${name}" failed the security scan: ${sec.blocking.map((f) => `${f.rule} at ${f.file}:${f.line}`).join(', ')}`);
80
+ const dest = path.join(skillsDir, name);
81
+ if (fs.existsSync(dest) && !opts.force) throw new Error(`skills/${name}/ already exists (use --force to overwrite)`);
82
+ fs.cpSync(srcDir, dest, { recursive: true });
83
+ return { name, dir: path.relative(cwd, dest) || dest, scaffolded: false, warnings: v.warnings, security: sec.verdict, attachedToAgent: opts.agent ? attachSkillToAgent(cwd, opts.agent, name) : null };
84
+ }
85
+
86
+ // Ensure an agent's IDENTITY frontmatter references the skill (inline `skills: [a, b]`).
87
+ export function attachSkillToAgent(cwd, agent, skillName) {
88
+ const idp = path.join(cwd, 'agents', agent, 'IDENTITY.md');
89
+ if (!fs.existsSync(idp)) throw new Error(`agent not found: agents/${agent}/IDENTITY.md`);
90
+ const raw = fs.readFileSync(idp, 'utf8');
91
+ const m = raw.match(/^(---\n)([\s\S]*?)(\n---)/);
92
+ if (!m) throw new Error(`agents/${agent}/IDENTITY.md has no frontmatter`);
93
+ let fm = m[2];
94
+ const existing = fm.match(/^skills:\s*\[([^\]]*)\]\s*$/m);
95
+ if (existing) {
96
+ const items = existing[1].split(',').map((s) => s.trim()).filter(Boolean);
97
+ if (!items.includes(skillName)) items.push(skillName);
98
+ fm = fm.replace(/^skills:\s*\[[^\]]*\]\s*$/m, `skills: [${items.join(', ')}]`);
99
+ } else {
100
+ fm = `${fm}\nskills: [${skillName}]`;
101
+ }
102
+ fs.writeFileSync(idp, raw.replace(/^---\n[\s\S]*?\n---/, `---\n${fm}\n---`));
103
+ return agent;
104
+ }
105
+
106
+ // The open Agent Skills layout (v1.8 §34.1). The description is what an agent reads to decide
107
+ // whether to use the skill: say what it does AND when, in the words a user would use.
108
+ function skillStub(name) {
109
+ return `---\nname: ${name}\ndescription: Does X for Y. Use when the user asks to … or mentions …. CHANGE ME.\n---\n\n# ${name}\n\nThe name and description sit in every agent's cached index; this body loads only when the skill is used, so keep it under 500 lines and move detail to references/ (one level deep).\n\n## Steps\n\n1. …\n\nAdd at least 3 eval cases in evals/ before relying on it: \`scroll skill eval ${name}\` runs each with and without the skill.\n`;
110
+ }
111
+
112
+ // ── scroll plugin add <ref> ───────────────────────────────────────────────────
113
+ // A plugin is an "agent-pack": agents/ + skills/ + .mcp.json (+ manifest). Unpack a directory or a
114
+ // .plugin/.zip and merge it into the repo. Existing items are skipped unless --force.
115
+ export function pluginAdd(ref, opts = {}, cwd = process.cwd()) {
116
+ let srcDir = path.resolve(cwd, ref || '');
117
+ if (!fs.existsSync(srcDir)) throw new Error(`plugin not found: ${ref}`);
118
+ let tmp = null;
119
+ if (fs.statSync(srcDir).isFile()) {
120
+ if (!/\.(plugin|zip)$/.test(srcDir)) throw new Error('a plugin file must be a .plugin or .zip (or pass an unpacked directory)');
121
+ tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'scroll-plugin-'));
122
+ const r = spawnSync('unzip', ['-q', '-o', srcDir, '-d', tmp], { encoding: 'utf8' });
123
+ if (r.status !== 0) { fs.rmSync(tmp, { recursive: true, force: true }); throw new Error('unzip failed (install the `unzip` CLI, or pass an unpacked plugin directory): ' + (r.stderr || '')); }
124
+ srcDir = pluginRoot(tmp);
125
+ }
126
+
127
+ const manifest = readJson(path.join(srcDir, 'manifest.json')) || readJson(path.join(srcDir, 'plugin.json')) || {};
128
+ const installed = { agents: [], skills: [], mcpServers: [] };
129
+
130
+ const copyTree = (subdir, listKey) => {
131
+ const base = path.join(srcDir, subdir);
132
+ if (!fs.existsSync(base)) return;
133
+ for (const n of fs.readdirSync(base)) {
134
+ const s = path.join(base, n);
135
+ if (!fs.statSync(s).isDirectory()) continue;
136
+ const d = path.join(cwd, subdir, n);
137
+ if (fs.existsSync(d) && !opts.force) { installed[listKey].push(`${n} (skipped: exists)`); continue; }
138
+ // v1.8 §36.2: a plugin's skill is scanned like any other; a blocked one is not installed
139
+ // v1.9 §41: an agent or skill that carries a person (card, USER.md, people/) is not installed
140
+ { const ppl = scanForPeople(s); if (ppl.length) { installed[listKey].push(`${n} (skipped: carries people — ${ppl.map((h) => h.file).join(', ')})`); continue; } }
141
+ if (subdir === 'skills') { const sec = scanSkillDir(s, opts.trust || 'community'); if (sec.verdict === 'block') { installed[listKey].push(`${n} (skipped: blocked by the security scan — ${sec.blocking.map((f) => f.rule).join(', ')})`); continue; } }
142
+ fs.cpSync(s, d, { recursive: true });
143
+ installed[listKey].push(n);
144
+ }
145
+ };
146
+ copyTree('agents', 'agents');
147
+ copyTree('skills', 'skills');
148
+ const ignored = [];
149
+ if (fs.existsSync(path.join(srcDir, 'people'))) ignored.push('people/ (a plugin never installs person cards — §41)');
150
+ if (fs.existsSync(path.join(srcDir, 'knowledge'))) ignored.push('knowledge/ (a plugin never installs deployment knowledge — §41)');
151
+ if (fs.existsSync(path.join(srcDir, 'USER.md'))) ignored.push('USER.md (a plugin never installs deployment USER.md — §41)');
152
+ if (ignored.length) installed.ignored = ignored;
153
+
154
+ const pmcp = readJson(path.join(srcDir, '.mcp.json'));
155
+ if (pmcp && pmcp.mcpServers) {
156
+ const dest = path.join(cwd, '.mcp.json');
157
+ const cur = readJson(dest) || { mcpServers: {} };
158
+ cur.mcpServers = cur.mcpServers || {};
159
+ for (const [k, v] of Object.entries(pmcp.mcpServers)) {
160
+ if (cur.mcpServers[k] && !opts.force) { installed.mcpServers.push(`${k} (skipped: exists)`); continue; }
161
+ cur.mcpServers[k] = v; installed.mcpServers.push(k);
162
+ }
163
+ writeJson(dest, cur);
164
+ }
165
+
166
+ if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
167
+ return { name: manifest.name || path.basename(String(ref)).replace(/\.(plugin|zip)$/, ''), installed, manifest };
168
+ }
169
+
170
+ // If a zip unpacked to a single wrapper folder (and no manifest/agents at top), descend into it.
171
+ function pluginRoot(dir) {
172
+ const top = fs.readdirSync(dir).filter((n) => !n.startsWith('.'));
173
+ const hasContent = ['manifest.json', 'plugin.json', 'agents', 'skills', '.mcp.json'].some((n) => fs.existsSync(path.join(dir, n)));
174
+ if (!hasContent && top.length === 1 && fs.statSync(path.join(dir, top[0])).isDirectory()) return path.join(dir, top[0]);
175
+ return dir;
176
+ }