@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
package/lib/digest.js
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
// SCROLL — comprehension digest (v1.4).
|
|
2
|
+
//
|
|
3
|
+
// Why: SCROLL's users include solopreneurs who are not engineers. An unattended loop that they
|
|
4
|
+
// only "press a button" on creates comprehension debt — passive delegation that erodes their grasp
|
|
5
|
+
// of what the agent actually did. After every run, SCROLL derives a short, human-readable digest
|
|
6
|
+
// from events.jsonl (no model call) so the owner can READ what happened — what was done, which
|
|
7
|
+
// dangerous tiers were touched, what it cost, and what still needs a human.
|
|
8
|
+
//
|
|
9
|
+
// Deterministic: it is a pure transform of the event stream. Language follows IDENTITY.language.
|
|
10
|
+
import fs from 'node:fs';
|
|
11
|
+
import path from 'node:path';
|
|
12
|
+
|
|
13
|
+
const L = {
|
|
14
|
+
en: {
|
|
15
|
+
title: 'Run digest', one_line: 'If you read one line', did: 'What it did', risky: 'Dangerous actions touched',
|
|
16
|
+
cost: 'What it cost', attention: 'Needs your attention', none: 'nothing', tokens: 'tokens', verify: 'verification',
|
|
17
|
+
approved: 'approved', blocked: 'BLOCKED — waiting for approval', denied: 'DENIED (grounding failed)',
|
|
18
|
+
completed: 'completed', paused: 'paused', tasks: 'tasks', read: 'Generated by scroll — read this instead of just trusting the run.',
|
|
19
|
+
waiting_person: 'WAITING for a person', approval_rejected: 'approval REJECTED (approver lacks authority)',
|
|
20
|
+
reply_held: 'reply HELD for a person (untraced claim, style ceiling, or external approval required)',
|
|
21
|
+
},
|
|
22
|
+
vi: {
|
|
23
|
+
title: 'Tóm tắt lượt chạy', one_line: 'Nếu chỉ đọc một dòng', did: 'Đã làm gì', risky: 'Hành động nguy hiểm đã chạm',
|
|
24
|
+
cost: 'Chi phí', attention: 'Cần bạn xem', none: 'không có', tokens: 'token', verify: 'kiểm chứng',
|
|
25
|
+
approved: 'đã duyệt', blocked: 'BỊ CHẶN — chờ duyệt', denied: 'TỪ CHỐI (grounding fail)',
|
|
26
|
+
completed: 'hoàn tất', paused: 'tạm dừng', tasks: 'việc', read: 'Sinh bởi scroll — đọc cái này thay vì chỉ tin lượt chạy.',
|
|
27
|
+
waiting_person: 'ĐANG CHỜ một người', approval_rejected: 'lời duyệt BỊ TỪ CHỐI (người duyệt không có quyền)',
|
|
28
|
+
reply_held: 'câu trả lời BỊ GIỮ chờ người duyệt (thiếu nguồn, vượt trần style, hoặc cần duyệt người ngoài)',
|
|
29
|
+
},
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export function readEvents(eventsPath) {
|
|
33
|
+
if (!fs.existsSync(eventsPath)) return [];
|
|
34
|
+
return fs.readFileSync(eventsPath, 'utf8').trim().split('\n').filter(Boolean)
|
|
35
|
+
.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// Build the digest text from events. Returns a markdown string.
|
|
39
|
+
export function buildDigest(events, { language = 'en', metrics = null } = {}) {
|
|
40
|
+
const t = L[language] || L.en;
|
|
41
|
+
const completed = events.filter((e) => e.type === 'task_completed').map((e) => e.data.id);
|
|
42
|
+
const dispatched = events.filter((e) => e.type === 'task_contract');
|
|
43
|
+
const titleFor = (id) => { const d = dispatched.find((e) => e.data.taskId === id); return d ? (d.data.objective || id) : id; };
|
|
44
|
+
|
|
45
|
+
// dangerous tiers touched: from permission_decision (v1.4) or legacy gate_* events
|
|
46
|
+
const perms = events.filter((e) => e.type === 'permission_decision');
|
|
47
|
+
const risky = perms.filter((e) => ['external_comm', 'financial', 'destructive'].includes(e.data.tier));
|
|
48
|
+
const gatesLegacy = events.filter((e) => e.type === 'gate_requested');
|
|
49
|
+
const blocked = events.filter((e) => e.type === 'gate_blocked' || (e.type === 'permission_decision' && e.data.decision === 'await'));
|
|
50
|
+
const denied = events.filter((e) => e.type === 'grounding_failed' || (e.type === 'permission_decision' && e.data.decision === 'deny'));
|
|
51
|
+
|
|
52
|
+
const m = metrics || (events.find((e) => e.type === 'completed' || e.type === 'paused')?.data?.metrics) || {};
|
|
53
|
+
const status = events.some((e) => e.type === 'paused') ? t.paused : t.completed;
|
|
54
|
+
const verify = events.find((e) => e.type === 'verification');
|
|
55
|
+
|
|
56
|
+
const lines = [];
|
|
57
|
+
lines.push(`# ${t.title}`);
|
|
58
|
+
lines.push('');
|
|
59
|
+
const oneLine = denied.length
|
|
60
|
+
? `${denied.length} action(s) ${t.denied}.`
|
|
61
|
+
: blocked.length
|
|
62
|
+
? `${blocked.length} action(s) ${t.blocked}.`
|
|
63
|
+
: `${status}: ${completed.length} ${t.tasks} · ${(m.billableTokenEquivalent ?? '?')} ${t.tokens} · $${m.costUsd ?? '?'}.`;
|
|
64
|
+
lines.push(`**${t.one_line}:** ${oneLine}`);
|
|
65
|
+
lines.push('');
|
|
66
|
+
|
|
67
|
+
lines.push(`## ${t.did}`);
|
|
68
|
+
if (completed.length) for (const id of completed) lines.push(`- ${id} — ${String(titleFor(id)).slice(0, 100)}`);
|
|
69
|
+
else lines.push(`- ${t.none}`);
|
|
70
|
+
lines.push('');
|
|
71
|
+
|
|
72
|
+
lines.push(`## ${t.risky}`);
|
|
73
|
+
const riskyAll = risky.length ? risky : gatesLegacy;
|
|
74
|
+
if (riskyAll.length) {
|
|
75
|
+
for (const e of riskyAll) {
|
|
76
|
+
const tier = e.data.tier || e.data.risk || '?';
|
|
77
|
+
const state = e.data.decision === 'deny' ? t.denied : (e.data.decision === 'await' || e.type === 'gate_blocked') ? t.blocked
|
|
78
|
+
: e.data.approvedBeforeAction || e.data.decision === 'allow' ? t.approved : '?';
|
|
79
|
+
lines.push(`- [${tier}] ${e.data.tool || e.data.gateId || e.data.taskId || ''} — ${state}`);
|
|
80
|
+
}
|
|
81
|
+
} else lines.push(`- ${t.none}`);
|
|
82
|
+
lines.push('');
|
|
83
|
+
|
|
84
|
+
lines.push(`## ${t.cost}`);
|
|
85
|
+
lines.push(`- ${m.billableTokenEquivalent ?? '?'} ${t.tokens} · $${m.costUsd ?? '?'} · ${m.durationMs ?? '?'}ms · ${m.providerCalls ?? '?'} call(s)`);
|
|
86
|
+
if (verify) lines.push(`- ${t.verify}: ${verify.data.passed ? 'PASS' : 'FAIL'}`);
|
|
87
|
+
lines.push('');
|
|
88
|
+
|
|
89
|
+
lines.push(`## ${t.attention}`);
|
|
90
|
+
const att = [];
|
|
91
|
+
for (const e of blocked) att.push(`- ${t.blocked}: ${e.data.gateId || e.data.tool || e.data.taskId || ''}`);
|
|
92
|
+
for (const e of denied) att.push(`- ${t.denied}: ${e.data.tool || e.data.taskId || (e.data.missing || []).join(', ')}`);
|
|
93
|
+
// v1.9 §40 — steps a person holds, and approvals the runner refused
|
|
94
|
+
const asked = new Map(events.filter((x) => x.type === 'human_task_requested').map((e) => [e.data.taskId, e.data.person]));
|
|
95
|
+
for (const [id, who] of asked) if (!completed.includes(id)) att.push(`- ${t.waiting_person}: ${who} — ${id}`);
|
|
96
|
+
for (const e of events.filter((x) => x.type === 'reply_held')) att.push(`- ${t.reply_held}: ${e.data.taskId} (${(e.data.reasons || []).join(', ')})`);
|
|
97
|
+
for (const e of events.filter((x) => x.type === 'approval_rejected')) att.push(`- ${t.approval_rejected}: ${e.data.gateId} (${e.data.by || '?'}: ${e.data.reason})`);
|
|
98
|
+
if (verify && verify.data.passed === false) att.push('- verification did not pass — review the output before trusting it');
|
|
99
|
+
lines.push(att.length ? att.join('\n') : `- ${t.none}`);
|
|
100
|
+
lines.push('');
|
|
101
|
+
lines.push(`*${t.read}*`);
|
|
102
|
+
return lines.join('\n');
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// Write runDir/digest.md from the run's event stream. Returns the path.
|
|
106
|
+
export function writeDigest({ runDir, eventsPath, language = 'en', metrics = null } = {}) {
|
|
107
|
+
const evs = readEvents(eventsPath || path.join(runDir, 'events.jsonl'));
|
|
108
|
+
const md = buildDigest(evs, { language, metrics });
|
|
109
|
+
const out = path.join(runDir, 'digest.md');
|
|
110
|
+
fs.writeFileSync(out, md + '\n');
|
|
111
|
+
return out;
|
|
112
|
+
}
|
package/lib/effects.js
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
// SCROLL v1.6 — §28 EFFECT CONFIRMATION.
|
|
2
|
+
//
|
|
3
|
+
// A write that *reports* success is not evidence that the write *happened*.
|
|
4
|
+
//
|
|
5
|
+
// The failure this closes: an interface accepts a call, silently ignores a field it does not
|
|
6
|
+
// understand, and returns a success status. Nothing logs, nothing throws. The agent reads the
|
|
7
|
+
// success and reports it onward in perfect good faith — the agent is not lying, the interface is.
|
|
8
|
+
// Such a defect can live for weeks because every signal says "green".
|
|
9
|
+
//
|
|
10
|
+
// The rule: after a WRITE, read the state back with a SEPARATE read operation and check it.
|
|
11
|
+
// The write's own response is not admissible as its own confirmation.
|
|
12
|
+
//
|
|
13
|
+
// Declared as data next to `risk`/`ground` in .mcp.json (§21.3, §22) — never in prose:
|
|
14
|
+
// "issue_invoice": {
|
|
15
|
+
// "risk": "financial",
|
|
16
|
+
// "ground": ["product_code", "amount"],
|
|
17
|
+
// "confirm": { "probe": "lookup_invoice", "expect": "$.status == 'issued'" }
|
|
18
|
+
// }
|
|
19
|
+
|
|
20
|
+
import { normalizeTier, TIER_RANK } from './permissions.js';
|
|
21
|
+
|
|
22
|
+
// Tiers that mutate state outside the run's own memory.
|
|
23
|
+
const WRITE_TIERS = new Set(['reversible_write', 'external_comm', 'financial', 'destructive']);
|
|
24
|
+
// Tiers where a missing `confirm` is a governance defect, not a style nit.
|
|
25
|
+
const CONFIRM_REQUIRED_TIERS = new Set(['financial', 'destructive']);
|
|
26
|
+
|
|
27
|
+
export function isWriteTier(tier) {
|
|
28
|
+
return WRITE_TIERS.has(normalizeTier(tier) || 'destructive');
|
|
29
|
+
}
|
|
30
|
+
export function confirmRequired(tier) {
|
|
31
|
+
return CONFIRM_REQUIRED_TIERS.has(normalizeTier(tier) || 'destructive');
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// ── expect predicates (deterministic; no LLM in the confirmation path) ──
|
|
35
|
+
// Grammar (intentionally small — an obscure predicate is a predicate nobody trusts):
|
|
36
|
+
// $.a.b == 'x' $.a.b != 'x' $.a.b == 3 $.a.b == true
|
|
37
|
+
// $.a.b exists $.a.b contains 'x' $.a.b (truthy)
|
|
38
|
+
// Arrays: $.items[0].id
|
|
39
|
+
const PATH_RE = /^\$(\.[A-Za-z_$][\w$]*|\[\d+\])*$/;
|
|
40
|
+
|
|
41
|
+
export function readPath(obj, expr) {
|
|
42
|
+
if (!PATH_RE.test(expr)) return { ok: false, error: `bad path: ${expr}` };
|
|
43
|
+
let cur = obj;
|
|
44
|
+
const parts = expr.slice(1).match(/\.[A-Za-z_$][\w$]*|\[\d+\]/g) || [];
|
|
45
|
+
for (const p of parts) {
|
|
46
|
+
if (cur == null) return { ok: true, value: undefined };
|
|
47
|
+
cur = p[0] === '[' ? cur[Number(p.slice(1, -1))] : cur[p.slice(1)];
|
|
48
|
+
}
|
|
49
|
+
return { ok: true, value: cur };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function literal(raw) {
|
|
53
|
+
const s = raw.trim();
|
|
54
|
+
if (/^'([\s\S]*)'$/.test(s) || /^"([\s\S]*)"$/.test(s)) return s.slice(1, -1);
|
|
55
|
+
if (s === 'true') return true;
|
|
56
|
+
if (s === 'false') return false;
|
|
57
|
+
if (s === 'null') return null;
|
|
58
|
+
if (s !== '' && !isNaN(Number(s))) return Number(s);
|
|
59
|
+
return s;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function evalExpect(expr, obj) {
|
|
63
|
+
const e = String(expr || '').trim();
|
|
64
|
+
if (!e) return { ok: false, error: 'empty expect' };
|
|
65
|
+
|
|
66
|
+
let m = e.match(/^(\$[^\s]*)\s*(==|!=)\s*(.+)$/);
|
|
67
|
+
if (m) {
|
|
68
|
+
const r = readPath(obj, m[1]);
|
|
69
|
+
if (!r.ok) return { ok: false, error: r.error };
|
|
70
|
+
const want = literal(m[3]);
|
|
71
|
+
const got = r.value;
|
|
72
|
+
// eslint-disable-next-line eqeqeq
|
|
73
|
+
const eq = got == want;
|
|
74
|
+
return { ok: m[2] === '==' ? eq : !eq, observed: got, expected: want };
|
|
75
|
+
}
|
|
76
|
+
m = e.match(/^(\$[^\s]*)\s+exists$/);
|
|
77
|
+
if (m) {
|
|
78
|
+
const r = readPath(obj, m[1]);
|
|
79
|
+
if (!r.ok) return { ok: false, error: r.error };
|
|
80
|
+
return { ok: r.value !== undefined && r.value !== null, observed: r.value, expected: 'exists' };
|
|
81
|
+
}
|
|
82
|
+
m = e.match(/^(\$[^\s]*)\s+contains\s+(.+)$/);
|
|
83
|
+
if (m) {
|
|
84
|
+
const r = readPath(obj, m[1]);
|
|
85
|
+
if (!r.ok) return { ok: false, error: r.error };
|
|
86
|
+
const want = literal(m[2]);
|
|
87
|
+
const hay = r.value;
|
|
88
|
+
const ok = Array.isArray(hay) ? hay.includes(want) : String(hay ?? '').includes(String(want));
|
|
89
|
+
return { ok, observed: hay, expected: `contains ${JSON.stringify(want)}` };
|
|
90
|
+
}
|
|
91
|
+
if (PATH_RE.test(e)) {
|
|
92
|
+
const r = readPath(obj, e);
|
|
93
|
+
if (!r.ok) return { ok: false, error: r.error };
|
|
94
|
+
return { ok: !!r.value, observed: r.value, expected: 'truthy' };
|
|
95
|
+
}
|
|
96
|
+
return { ok: false, error: `unsupported expect: ${e}` };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// ── the gate ──
|
|
100
|
+
// `invoke(probeName, params)` → the probe's result (object or JSON string). Supplied by the caller
|
|
101
|
+
// so this module stays runtime-agnostic: it performs no I/O of its own.
|
|
102
|
+
export async function confirmEffect({ tool, tier, confirm, params = {}, invoke, emit } = {}) {
|
|
103
|
+
const t = normalizeTier(tier) || 'destructive';
|
|
104
|
+
const say = (ev, d) => { if (typeof emit === 'function') emit(ev, d); };
|
|
105
|
+
|
|
106
|
+
if (!isWriteTier(t)) return { checked: false, ok: true, reason: 'not a write' };
|
|
107
|
+
|
|
108
|
+
if (!confirm || !confirm.probe || !confirm.expect) {
|
|
109
|
+
// Fail-closed exactly where it matters; elsewhere report honestly as unconfirmed (§29: the
|
|
110
|
+
// absence of a check is never a pass — it is "we did not look").
|
|
111
|
+
const required = confirmRequired(t);
|
|
112
|
+
const res = { checked: false, ok: !required, unconfirmed: true, tier: t,
|
|
113
|
+
reason: `no confirm declared for a ${t} write` };
|
|
114
|
+
if (required) say('effect_unconfirmed', { tool, tier: t, reason: res.reason });
|
|
115
|
+
return res;
|
|
116
|
+
}
|
|
117
|
+
if (typeof invoke !== 'function') {
|
|
118
|
+
return { checked: false, ok: false, unconfirmed: true, tier: t, reason: 'no invoke() provided' };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
let raw;
|
|
122
|
+
try {
|
|
123
|
+
raw = await invoke(confirm.probe, confirm.params || params);
|
|
124
|
+
} catch (e) {
|
|
125
|
+
const reason = `probe "${confirm.probe}" threw: ${String((e && e.message) || e)}`;
|
|
126
|
+
say('effect_unconfirmed', { tool, tier: t, reason });
|
|
127
|
+
return { checked: true, ok: false, unconfirmed: true, tier: t, reason };
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
let observedObj = raw;
|
|
131
|
+
if (typeof raw === 'string') { try { observedObj = JSON.parse(raw); } catch { /* keep string */ } }
|
|
132
|
+
|
|
133
|
+
const r = evalExpect(confirm.expect, observedObj);
|
|
134
|
+
if (r.error) {
|
|
135
|
+
say('effect_unconfirmed', { tool, tier: t, reason: r.error });
|
|
136
|
+
return { checked: true, ok: false, unconfirmed: true, tier: t, reason: r.error };
|
|
137
|
+
}
|
|
138
|
+
if (r.ok) {
|
|
139
|
+
say('effect_confirmed', { tool, probe: confirm.probe, ok: true, observed: r.observed });
|
|
140
|
+
return { checked: true, ok: true, tier: t, observed: r.observed };
|
|
141
|
+
}
|
|
142
|
+
say('effect_unconfirmed', { tool, expected: r.expected, observed: r.observed });
|
|
143
|
+
return { checked: true, ok: false, unconfirmed: true, tier: t,
|
|
144
|
+
reason: `read-back mismatch: expected ${JSON.stringify(r.expected)}, observed ${JSON.stringify(r.observed)}`,
|
|
145
|
+
expected: r.expected, observed: r.observed };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// Corollary of §28, used by interfaces that accept structured input: an unknown field MUST be
|
|
149
|
+
// rejected, never dropped. Silently dropping input is how a system comes to report success for
|
|
150
|
+
// work it never performed.
|
|
151
|
+
export function rejectUnknownFields(body = {}, allowed = [], control = []) {
|
|
152
|
+
const ok = new Set([...allowed, ...control]);
|
|
153
|
+
const rejected = Object.keys(body || {}).filter((k) => !ok.has(k));
|
|
154
|
+
return { ok: rejected.length === 0, rejected };
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export const _internals = { WRITE_TIERS, CONFIRM_REQUIRED_TIERS, TIER_RANK };
|