@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.
- package/AGENTS.md +55 -0
- package/LICENSE +21 -0
- package/README.md +293 -2
- package/SPEC.md +1079 -0
- package/bin/scroll.js +8 -0
- package/docs/prompt-caching.md +128 -0
- package/index.js +33 -0
- package/lib/audit.js +358 -0
- package/lib/auth.js +849 -0
- package/lib/chat-sdk/admin-controller.js +289 -0
- package/lib/chat-sdk/debouncer.js +94 -0
- package/lib/chat-sdk/group-grants.js +150 -0
- package/lib/chat-sdk/index.js +222 -0
- package/lib/chat-sdk/long-task-runner.js +413 -0
- package/lib/chat-session.js +1788 -0
- package/lib/chat-telemetry.js +557 -0
- package/lib/codex-app-server.js +851 -0
- package/lib/digest.js +112 -0
- package/lib/effects.js +157 -0
- package/lib/eval.js +408 -0
- package/lib/grounding.js +356 -0
- package/lib/installers.js +176 -0
- package/lib/knowledge.js +335 -0
- package/lib/ledger.js +38 -0
- package/lib/loop.js +197 -0
- package/lib/mcp-client.js +926 -0
- package/lib/memory-cli.js +66 -0
- package/lib/memory-tracker.js +1472 -0
- package/lib/memory.js +1279 -0
- package/lib/people-cli.js +81 -0
- package/lib/people.js +534 -0
- package/lib/permissions.js +272 -0
- package/lib/providers.js +1572 -0
- package/lib/runtime.js +928 -0
- package/lib/sandbox.js +744 -0
- package/lib/scheduler.js +402 -0
- package/lib/scroll.js +1225 -0
- package/lib/skill-cli.js +120 -0
- package/lib/skill-eval.js +156 -0
- package/lib/skills.js +860 -0
- package/lib/style.js +126 -0
- package/lib/tool-retriever.js +489 -0
- package/lib/tools.js +1833 -0
- package/lib/user.js +711 -0
- package/lib/vault.js +151 -0
- package/package.json +88 -4
- package/templates/agent/IDENTITY.md +56 -0
- package/templates/agent/SOUL.md +23 -0
- package/templates/agent/TOOLS.md +25 -0
- package/templates/agent/evals/case-02-citation-discipline.md +29 -0
- package/templates/agent/evals/case-03-boundary.md +27 -0
- package/templates/agent/evals/case-example.md +43 -0
- package/templates/agent/hard-rules.md +11 -0
- package/templates/agent/memory/lessons.md +5 -0
- package/templates/agent/memory/log/.gitkeep +0 -0
- package/templates/external-safety-contract.md +5 -0
- package/templates/long-task-planner.md +17 -0
- package/templates/work/LOOP.md +37 -0
- package/templates/work/WORK.md +50 -0
- package/types/chat.d.ts +61 -0
- package/types/index.d.ts +112 -0
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
// SCROLL 2.5 -- permission layer (v1.4 -> v2.5). Risk-tiered, enforced at the action boundary.
|
|
2
|
+
//
|
|
3
|
+
// Five tiers, lowest -> highest consequence:
|
|
4
|
+
// read_only · reversible_write · external_comm · financial · destructive
|
|
5
|
+
// A matrix maps each tier to a policy: auto | auto-log | soft-hold | must-approve.
|
|
6
|
+
// financial + destructive additionally require a grounding check (see grounding.js).
|
|
7
|
+
//
|
|
8
|
+
// Risk is DATA, not prose: it is declared in .mcp.json (per tool) or IDENTITY.security
|
|
9
|
+
// (per capability namespace), and resolved here -- never read from a markdown body.
|
|
10
|
+
// Built-in floor tiers cannot be lowered by operator config; operators may only raise them.
|
|
11
|
+
import fs from 'node:fs';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
import { parseFrontmatter } from './scroll.js';
|
|
14
|
+
|
|
15
|
+
export const TIERS = ['read_only', 'reversible_write', 'external_comm', 'financial', 'destructive'];
|
|
16
|
+
export const TIER_RANK = Object.fromEntries(TIERS.map((t, i) => [t, i]));
|
|
17
|
+
|
|
18
|
+
export const DEFAULT_MATRIX = {
|
|
19
|
+
read_only: 'auto',
|
|
20
|
+
reversible_write: 'auto-log',
|
|
21
|
+
external_comm: 'soft-hold',
|
|
22
|
+
financial: 'must-approve',
|
|
23
|
+
destructive: 'must-approve',
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
// Built-in minimum safety floors: operator config may raise a tier, never lower below floor.
|
|
27
|
+
export const BUILTIN_TIER_FLOOR = {
|
|
28
|
+
exec: 'destructive',
|
|
29
|
+
memory_forget: 'destructive',
|
|
30
|
+
memory_remember: 'reversible_write',
|
|
31
|
+
memory_lesson: 'reversible_write',
|
|
32
|
+
memory_open_loops: 'reversible_write',
|
|
33
|
+
automations: 'reversible_write',
|
|
34
|
+
spawn_worker: 'reversible_write',
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
// Logical capability -> concrete built-in tool aliases for `security.tools_allow` matching
|
|
38
|
+
export const CAPABILITY_TOOL_ALIASES = {
|
|
39
|
+
'fs.read': ['read_file', 'list_dir'],
|
|
40
|
+
'web.search': ['web_search'],
|
|
41
|
+
'web.fetch': ['web_fetch'],
|
|
42
|
+
'shell.exec': ['exec'],
|
|
43
|
+
'skills.read': ['skill_list', 'skill_view'],
|
|
44
|
+
'knowledge.read': ['knowledge_search'],
|
|
45
|
+
'memory.read': ['memory_search', 'memory_inspect'],
|
|
46
|
+
'memory.write': ['memory_remember', 'memory_forget', 'memory_lesson', 'memory_open_loops'],
|
|
47
|
+
'schedule.manage': ['automations'],
|
|
48
|
+
'workers.spawn': ['spawn_worker'],
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
const GROUND_TIERS = new Set(['financial', 'destructive']);
|
|
52
|
+
const LEGACY_TIER = { irreversible: 'destructive', reversible: 'reversible_write' };
|
|
53
|
+
|
|
54
|
+
export function normalizeTier(t) {
|
|
55
|
+
if (!t) return null;
|
|
56
|
+
const s = String(t).trim();
|
|
57
|
+
if (TIER_RANK[s] !== undefined) return s;
|
|
58
|
+
if (LEGACY_TIER[s]) return LEGACY_TIER[s];
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function maxTier(a, b) {
|
|
63
|
+
const na = normalizeTier(a);
|
|
64
|
+
const nb = normalizeTier(b);
|
|
65
|
+
if (!na) return nb || 'destructive';
|
|
66
|
+
if (!nb) return na;
|
|
67
|
+
return TIER_RANK[na] >= TIER_RANK[nb] ? na : nb;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function enforceTierFloor(name, tier, floors = BUILTIN_TIER_FLOOR) {
|
|
71
|
+
const norm = normalizeTier(tier) || 'destructive';
|
|
72
|
+
const floor = floors && floors[name] ? normalizeTier(floors[name]) : null;
|
|
73
|
+
if (!floor) return norm;
|
|
74
|
+
return maxTier(norm, floor);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function globToRegex(pattern) {
|
|
78
|
+
const escaped = String(pattern || '').replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
|
|
79
|
+
return new RegExp(`^${escaped}$`);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// Match a tool name against a `security.tools_allow` rule array (exact, glob, or logical capability).
|
|
83
|
+
// If `allowRules` is null/undefined, returns true (not configured -> open for backwards compatibility).
|
|
84
|
+
// If `allowRules` is an array (including `[]`), deny-by-default: must match at least one rule.
|
|
85
|
+
export function matchesToolAllow(toolName, allowRules) {
|
|
86
|
+
if (allowRules == null) return true;
|
|
87
|
+
if (!Array.isArray(allowRules)) return false;
|
|
88
|
+
if (!allowRules.length) return false;
|
|
89
|
+
const target = String(toolName || '').trim();
|
|
90
|
+
if (!target) return false;
|
|
91
|
+
for (const rawRule of allowRules) {
|
|
92
|
+
const rule = String(rawRule || '').trim();
|
|
93
|
+
if (!rule) continue;
|
|
94
|
+
if (rule === '*' || rule === target) return true;
|
|
95
|
+
const aliased = CAPABILITY_TOOL_ALIASES[rule];
|
|
96
|
+
if (aliased && aliased.includes(target)) return true;
|
|
97
|
+
if (rule.includes('*') && globToRegex(rule).test(target)) return true;
|
|
98
|
+
}
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// Resolve a tool/capability name -> a tier.
|
|
103
|
+
// Precedence: explicit .mcp.json per-tool -> IDENTITY exact -> IDENTITY longest glob
|
|
104
|
+
// (e.g. `mcp.github.*` > `mcp.*` > `fs.*`) -> fallback `destructive`, then apply built-in floor.
|
|
105
|
+
export function resolveTier(name, { mcpTools = {}, riskDefaults = {}, enforceFloor = true } = {}) {
|
|
106
|
+
if (!name) return { tier: 'destructive', via: 'fallback' };
|
|
107
|
+
const sName = String(name);
|
|
108
|
+
|
|
109
|
+
let resolved = null;
|
|
110
|
+
let via = 'fallback';
|
|
111
|
+
|
|
112
|
+
const fromMcp = mcpTools[sName] && normalizeTier(mcpTools[sName].risk);
|
|
113
|
+
if (fromMcp) {
|
|
114
|
+
resolved = fromMcp;
|
|
115
|
+
via = 'mcp';
|
|
116
|
+
}
|
|
117
|
+
if (!resolved) {
|
|
118
|
+
const exact = riskDefaults[sName] && normalizeTier(riskDefaults[sName]);
|
|
119
|
+
if (exact) {
|
|
120
|
+
resolved = exact;
|
|
121
|
+
via = 'identity';
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
if (!resolved) {
|
|
125
|
+
// Support multi-segment globs (`mcp.github.*` beats `mcp.*`) as well as root globs (`fs.*`)
|
|
126
|
+
const globKeys = Object.keys(riskDefaults)
|
|
127
|
+
.filter((k) => k.endsWith('.*'))
|
|
128
|
+
.sort((a, b) => b.length - a.length);
|
|
129
|
+
for (const key of globKeys) {
|
|
130
|
+
const prefix = key.slice(0, -1); // includes trailing '.'
|
|
131
|
+
if (sName.startsWith(prefix)) {
|
|
132
|
+
const t = normalizeTier(riskDefaults[key]);
|
|
133
|
+
if (t) {
|
|
134
|
+
resolved = t;
|
|
135
|
+
via = 'identity-glob';
|
|
136
|
+
break;
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
if (!resolved) {
|
|
142
|
+
resolved = 'destructive';
|
|
143
|
+
via = 'fallback';
|
|
144
|
+
}
|
|
145
|
+
if (enforceFloor) {
|
|
146
|
+
const floored = enforceTierFloor(sName, resolved);
|
|
147
|
+
if (floored !== resolved) {
|
|
148
|
+
return { tier: floored, via: `${via}+floor` };
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
return { tier: resolved, via };
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
export const POLICY_RANK = Object.freeze({
|
|
155
|
+
auto: 0,
|
|
156
|
+
'auto-log': 1,
|
|
157
|
+
'soft-hold': 2,
|
|
158
|
+
'must-approve': 3,
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
// Minimum approval policy floors: high-risk tiers cannot silently downgrade to auto/auto-log
|
|
162
|
+
// via tampered IDENTITY.md frontmatter unless the caller explicitly passes `enforceFloor: false`.
|
|
163
|
+
export const POLICY_FLOOR = Object.freeze({
|
|
164
|
+
financial: 'must-approve',
|
|
165
|
+
destructive: 'must-approve',
|
|
166
|
+
});
|
|
167
|
+
|
|
168
|
+
export function maxPolicy(a, b) {
|
|
169
|
+
const ra = POLICY_RANK[a];
|
|
170
|
+
const rb = POLICY_RANK[b];
|
|
171
|
+
if (ra === undefined) return rb === undefined ? 'must-approve' : b;
|
|
172
|
+
if (rb === undefined) return a;
|
|
173
|
+
return ra >= rb ? a : b;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
export function policyForTier(tier, overrides = {}, { enforceFloor = true } = {}) {
|
|
177
|
+
const matrix = { ...DEFAULT_MATRIX, ...(overrides || {}) };
|
|
178
|
+
const raw = matrix[tier] || 'must-approve';
|
|
179
|
+
const normalized = POLICY_RANK[raw] !== undefined ? raw : 'must-approve';
|
|
180
|
+
if (!enforceFloor) return normalized;
|
|
181
|
+
const floor = POLICY_FLOOR[tier];
|
|
182
|
+
return floor ? maxPolicy(normalized, floor) : normalized;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export function needsGrounding(tier) {
|
|
186
|
+
return GROUND_TIERS.has(tier);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
// The single deterministic decision. Returns one of: allow | await | deny.
|
|
190
|
+
export function evaluateAction({ tier, policy, approved = false, groundingRequired = false, grounded = null }) {
|
|
191
|
+
if (groundingRequired && grounded === false) {
|
|
192
|
+
return { decision: 'deny', reason: 'grounding failed — a critical parameter could not be traced to a real source' };
|
|
193
|
+
}
|
|
194
|
+
if (policy === 'must-approve' && !approved) {
|
|
195
|
+
return { decision: 'await', reason: 'must-approve: blocked until an approval file is present' };
|
|
196
|
+
}
|
|
197
|
+
const held = policy === 'soft-hold';
|
|
198
|
+
return { decision: 'allow', reason: held ? 'soft-hold: executed and logged' : 'within policy', held };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
// Load per-tool risk from repo-level & agent-level `.mcp.json`.
|
|
202
|
+
// Stores canonical `mcp.<server>.<tool>` keys AND non-colliding short names, preserving `confirm`.
|
|
203
|
+
export function loadMcpRisk(cwd = process.cwd(), agentDir = null) {
|
|
204
|
+
const tools = {};
|
|
205
|
+
const bareOwners = new Map();
|
|
206
|
+
const files = [path.join(cwd, '.mcp.json')];
|
|
207
|
+
if (agentDir) files.push(path.join(agentDir, '.mcp.json'));
|
|
208
|
+
for (const f of files) {
|
|
209
|
+
if (!fs.existsSync(f)) continue;
|
|
210
|
+
let j; try { j = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { continue; }
|
|
211
|
+
const servers = j.mcpServers || {};
|
|
212
|
+
for (const [serverName, srv] of Object.entries(servers)) {
|
|
213
|
+
if (!srv || typeof srv !== 'object') continue;
|
|
214
|
+
for (const [toolName, meta] of Object.entries(srv.tools || {})) {
|
|
215
|
+
const entry = {
|
|
216
|
+
risk: meta?.risk || null,
|
|
217
|
+
ground: Array.isArray(meta?.ground) ? meta.ground : [],
|
|
218
|
+
confirm: meta?.confirm || null,
|
|
219
|
+
server: serverName,
|
|
220
|
+
};
|
|
221
|
+
const fullKey = `mcp.${serverName}.${toolName}`;
|
|
222
|
+
tools[fullKey] = entry;
|
|
223
|
+
if (!bareOwners.has(toolName) || bareOwners.get(toolName) === serverName) {
|
|
224
|
+
bareOwners.set(toolName, serverName);
|
|
225
|
+
tools[toolName] = entry;
|
|
226
|
+
} else {
|
|
227
|
+
// Ambiguous bare name across two servers -> remove bare key to prevent collision overwrite
|
|
228
|
+
delete tools[toolName];
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
return tools;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
// Read IDENTITY.security + top-level capabilities/budget/tools_retrieval from an agent folder.
|
|
237
|
+
export function loadAgentSecurity(agentDir) {
|
|
238
|
+
const empty = {
|
|
239
|
+
riskDefaults: {},
|
|
240
|
+
approvalOverrides: {},
|
|
241
|
+
toolsAllow: null,
|
|
242
|
+
egressAllow: null,
|
|
243
|
+
execAllow: null,
|
|
244
|
+
execDeny: null,
|
|
245
|
+
capabilities: null,
|
|
246
|
+
budget: null,
|
|
247
|
+
toolsRetrieval: null,
|
|
248
|
+
};
|
|
249
|
+
if (!agentDir) return empty;
|
|
250
|
+
try {
|
|
251
|
+
const raw = fs.readFileSync(path.join(agentDir, 'IDENTITY.md'), 'utf8');
|
|
252
|
+
const { frontmatter } = parseFrontmatter(raw);
|
|
253
|
+
const fm = frontmatter && typeof frontmatter === 'object' ? frontmatter : {};
|
|
254
|
+
const sec = (fm.security && typeof fm.security === 'object') ? fm.security : {};
|
|
255
|
+
const normalizeExecList = (list) => (Array.isArray(list)
|
|
256
|
+
? list.map((item) => (Array.isArray(item) || (item && typeof item === 'object') ? item : String(item)))
|
|
257
|
+
: null);
|
|
258
|
+
return {
|
|
259
|
+
riskDefaults: sec.risk_defaults && typeof sec.risk_defaults === 'object' ? sec.risk_defaults : {},
|
|
260
|
+
approvalOverrides: sec.approval && typeof sec.approval === 'object' ? sec.approval : {},
|
|
261
|
+
toolsAllow: Array.isArray(sec.tools_allow) ? sec.tools_allow.map(String) : null,
|
|
262
|
+
egressAllow: Array.isArray(sec.egress_allow) ? sec.egress_allow.map(String) : null,
|
|
263
|
+
execAllow: normalizeExecList(sec.exec_allow),
|
|
264
|
+
execDeny: normalizeExecList(sec.exec_deny),
|
|
265
|
+
capabilities: Array.isArray(fm.capabilities) ? fm.capabilities.map(String) : null,
|
|
266
|
+
budget: fm.budget && typeof fm.budget === 'object' ? fm.budget : null,
|
|
267
|
+
toolsRetrieval: fm.tools_retrieval && typeof fm.tools_retrieval === 'object' ? fm.tools_retrieval : null,
|
|
268
|
+
};
|
|
269
|
+
} catch {
|
|
270
|
+
return empty;
|
|
271
|
+
}
|
|
272
|
+
}
|