@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/bin/scroll.js
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Prompt Caching Guide (SCROLL 2.5, §13 & §47.2)
|
|
2
|
+
|
|
3
|
+
SCROLL is designed from the ground up so LLM prompt caches hit reliably across every tick of an autonomous loop (`scroll run`) and every turn of a live conversation (`scroll chat`), even with 200+ MCP tools and alternating multi-speaker group chats.
|
|
4
|
+
|
|
5
|
+
Every provider computes prefix caches by matching exact token prefixes from byte 0. A single changing timestamp, unsorted tool list, speaker-dependent system prompt flip, or per-turn RAG snippet injected into the system prompt invalidates the entire cached prefix for the rest of the conversation.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. The §13 Three-Region Layout (with §47.2 Tool Retriever & Room-Sticky Groups)
|
|
10
|
+
|
|
11
|
+
`lib/chat-session.js` enforces a strict three-part wire layout on every turn:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
┌──────────────────────────────────────────────────────────────────────┐
|
|
15
|
+
│ REGION A -- STABLE PREFIX (byte-identical across turns & speakers) │
|
|
16
|
+
│ 1. Agent Identity (IDENTITY.md frontmatter) │
|
|
17
|
+
│ 2. Soul & Persona (SOUL.md) │
|
|
18
|
+
│ 3. Hard Rules (hard-rules.md) │
|
|
19
|
+
│ 4. L5 Procedural Lessons (agents/<agent>/memory/lessons.md, §7) │
|
|
20
|
+
│ 5. Principal / Team Profile (USER.md rendered for room audience) │
|
|
21
|
+
│ 6. Static Voice Character Preset (`voiceBefore.stableSystemBlock`) │
|
|
22
|
+
│ 7. Frozen Subject Memory (`stableMemoryBlock`, §32.4) │
|
|
23
|
+
│ 8. Frozen Skills Index (`<available_skills>`, §34) │
|
|
24
|
+
│ 9. Frozen Tool Catalog (`<available_tools>`, §47.2, <= 1,500 tok) │
|
|
25
|
+
│ 10. External Safety Contract (`templates/external-safety-contract`) │
|
|
26
|
+
│ 11. Sorted Active Tool Schemas (always-load + tool_search/invoke) │
|
|
27
|
+
├───────────────────────── CACHE BREAKPOINT 1 & 2 ─────────────────────┤
|
|
28
|
+
│ REGION B -- APPEND-ONLY CONVERSATION HISTORY │
|
|
29
|
+
│ Turn 1 (user + assistant + tool_use/tool_result) ... Turn N-1 │
|
|
30
|
+
├───────────────────────── CACHE BREAKPOINT 3 ─────────────────────────┤
|
|
31
|
+
│ REGION C -- VOLATILE SUFFIX (inside the final user message) │
|
|
32
|
+
│ - Sanitized speaker identity (`<turn_speaker ... />`) │
|
|
33
|
+
│ - Mid-session skills refresh notice (`skills.refresh().notice`) │
|
|
34
|
+
│ - Retrieved knowledge chunks (§44 `knowledgeChunks`) │
|
|
35
|
+
│ - Per-turn voice cues (`voiceBefore.volatileTurnBlock`) │
|
|
36
|
+
│ - Per-turn `contextBlocks` & `voiceBefore.extraContextBlocks` │
|
|
37
|
+
│ - Dynamic memory (`dynamicMemoryBlock`: speaker/peer/group index) │
|
|
38
|
+
│ - Current user message & multimodal attachment notes │
|
|
39
|
+
└──────────────────────────────────────────────────────────────────────┘
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Because Region A is frozen at the room/deployment level (including **Room-Sticky group posture** so alternating Owner, Teammate, and Guest turns in a shared room NEVER flip `prefixHash`) and Region B only appends at the tail, the token prefix through Turn N-1 remains byte-identical across turns — while per-speaker authorization is strictly enforced inside `tool_search` (Visible Set `V`) and `executeTool` (Executable Set `E`).
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 2. Channel-Agnostic Scoped Memory & Frozen Snapshots
|
|
47
|
+
|
|
48
|
+
`lib/memory-tracker.js` (`createScopedMemoryTracker`) provides 3-axis subject memory (`user`, `group`, `member`) plus L5 lessons for **any** surface (web chat, CLI, voice, Slack, Discord, Telegram, MCP, mobile apps, or CRM rooms) without breaking prompt caches:
|
|
49
|
+
|
|
50
|
+
- **`stableMemoryBlock`** is snapshotted once per `(conversation, day)` with `capsule_turns: 0` (live history already lives in Region B) and `excludeSession` (preventing double-injection of today's turns). It stays frozen inside Region A until a reset, compaction, explicit memory write, or day rollover.
|
|
51
|
+
- **`dynamicMemoryBlock`** holds per-turn changing context (e.g., which speaker spoke inside a multi-person room, peer digests, or owner room index) and is attached to Region C after `history`.
|
|
52
|
+
- **Voice plugins (§43)** should return `{ stableSystemBlock, volatileTurnBlock, extraContextBlocks }` from `beforeTurn()`. `stableSystemBlock` stays in Region A; `volatileTurnBlock` and `extraContextBlocks` move to Region C automatically.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 3. Six Cache-Busting Anti-Patterns (Prevented by SCROLL)
|
|
57
|
+
|
|
58
|
+
| Anti-pattern | Why it breaks caching | SCROLL safeguard |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| Putting `new Date()` / timestamps in `systemPrompt` | Changes byte 0 on every turn | Never inject wall-clock timestamps into Region A |
|
|
61
|
+
| Unsorted tool/MCP definitions | Map/discovery order shifts across restarts | `tools.listSchemas()` sorts alphabetically by `name` |
|
|
62
|
+
| Injecting RAG / knowledge chunks into `system` | Different query -> different system prompt | `knowledgeChunks` (§44) attach in Region C after `history` |
|
|
63
|
+
| Injecting live memory writes into `system` mid-session | Mutates Region A every time a fact is added | Frozen `stableMemoryBlock` (§32.4); volatile deltas go to Region C |
|
|
64
|
+
| Re-flattening full history on persistent RPC threads | Pays full re-prefill tokens on every turn | `codex-app-server` reuses persistent `threadId` per `(conversationId, prefixHash, model)` |
|
|
65
|
+
| Mutating early history turns silently | Invalidates Region B breakpoint | History is append-only; `compactSession` / `scrubHistory` explicitly reset cached threads |
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 4. Provider-Specific Mechanics (`lib/providers.js` & `lib/chat-session.js`)
|
|
70
|
+
|
|
71
|
+
### Anthropic (`anthropic`)
|
|
72
|
+
`makeAnthropicProvider` places **three** explicit `cache_control` breakpoints automatically:
|
|
73
|
+
1. **`system[0]`** — caches Region A system instructions.
|
|
74
|
+
2. **Last entry of `body.tools`** — caches the sorted tool definition block.
|
|
75
|
+
3. **Penultimate entry of `messages`** (`messages[messages.length - 2]`) — caches the entire conversation history prefix (Region B) up to the previous turn.
|
|
76
|
+
|
|
77
|
+
Optional extended TTL:
|
|
78
|
+
```js
|
|
79
|
+
const runtime = createChatSessionRuntime({
|
|
80
|
+
agentName: 'assistant',
|
|
81
|
+
providerName: 'anthropic',
|
|
82
|
+
cacheTtl: '1h', // default is Anthropic's standard 5m ephemeral TTL
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
When `cacheTtl: '1h'` is set, SCROLL attaches `{ type: 'ephemeral', ttl: '1h' }` and sends the `anthropic-beta: extended-cache-ttl-2025-04-11` header automatically.
|
|
86
|
+
|
|
87
|
+
### OpenAI (`openai` / `openai-compatible`)
|
|
88
|
+
`makeOpenAIProvider` and `makeOpenAICompatibleProvider` forward:
|
|
89
|
+
- **`prompt_cache_key`**: automatically derived as `${agentName}:${conversationId}` (truncated to 64 chars) whenever targeting `api.openai.com` or when `promptCacheKey` is explicitly passed. This routes repeat turns of the same conversation to the same cache shard.
|
|
90
|
+
- **`prompt_cache_retention: '24h'`**: sent when `cacheTtl: '24h'` is configured (for supported OpenAI models).
|
|
91
|
+
- Third-party OpenAI-compatible proxies (e.g., local vLLM / Ollama) do **not** receive `prompt_cache_key` unless `promptCacheKey` is explicitly passed, avoiding 400 validation errors on strict schemas.
|
|
92
|
+
|
|
93
|
+
### Codex App-Server (`codex-app-server`)
|
|
94
|
+
`createChatSessionRuntime` tracks persistent server-side threads per conversation (`reuseProviderThreads: true` by default):
|
|
95
|
+
- **Turn 1**: opens a persistent thread (`ephemeral: false`) with `baseInstructions = systemPrompt` and sorted `dynamicTools`, storing `{ threadId, prefixHash, model }`.
|
|
96
|
+
- **Turn 2..N**: when `prefixHash` and `model` match, SCROLL sends **only the single new user turn** (`[{ role: 'user', content: finalUserMessage }]`) on the existing `threadId`, preserving server-side KV cache and avoiding redundant history re-transmission.
|
|
97
|
+
- **Self-healing resets**: `clearSession()`, `compactSession()`, `reload()`, `scrubHistory()`, prefix changes (e.g., new L5 lesson or updated frozen memory), model switches, or stale-thread RPC errors automatically clear the thread and cleanly start a new persistent thread with full history.
|
|
98
|
+
|
|
99
|
+
### Google Gemini (`gemini`)
|
|
100
|
+
- **Implicit caching**: works automatically because Region A + Region B stay byte-identical across turns; `usage.cachedInputTokens` maps directly from `usageMetadata.cachedContentTokenCount`.
|
|
101
|
+
- **Explicit Context Caching**: pass `cachedContent: 'cachedContents/...'` either on `pickProvider('gemini', { cachedContent })` or per-call `generate(..., { cachedContent })`. When `cachedContent` is set, SCROLL omits `systemInstruction` to satisfy Gemini's API contract.
|
|
102
|
+
|
|
103
|
+
### xAI Grok & Other Compatible Endpoints
|
|
104
|
+
Automatic prefix caching benefits immediately from Region A byte-stability and alphabetically sorted tool definitions, with zero vendor lock-in.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 5. Verification & Telemetry
|
|
109
|
+
|
|
110
|
+
Inspect caching directly from `sendTurn()` results and runtime stats:
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
const turn1 = await runtime.sendTurn({ conversationId: 'room-42', text: 'Hello', sender });
|
|
114
|
+
const turn2 = await runtime.sendTurn({ conversationId: 'room-42', text: 'Follow-up', sender });
|
|
115
|
+
|
|
116
|
+
console.log({
|
|
117
|
+
prefixIdentical: turn1.prefixHash === turn2.prefixHash,
|
|
118
|
+
threadReused: turn2.threadReused,
|
|
119
|
+
cachedInputTokens: turn2.usage.cachedInputTokens,
|
|
120
|
+
uncachedInputTokens: turn2.usage.uncachedInputTokens,
|
|
121
|
+
stats: runtime.getCacheStats(),
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Expected healthy signals on Turn 2+:
|
|
126
|
+
- `turn1.prefixHash === turn2.prefixHash` (even when RAG hits, dynamic memory, or voice affect cues change!)
|
|
127
|
+
- `turn2.usage.cachedInputTokens > 0` on providers supporting prompt caching
|
|
128
|
+
- `turn2.threadReused === true` when running on `codex-app-server`
|
package/index.js
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
// SCROLL 2.5 -- Complete public programmatic API barrel.
|
|
2
|
+
export * from './lib/scroll.js';
|
|
3
|
+
export * from './lib/auth.js';
|
|
4
|
+
export * from './lib/codex-app-server.js';
|
|
5
|
+
export * from './lib/providers.js';
|
|
6
|
+
export * from './lib/mcp-client.js';
|
|
7
|
+
export * from './lib/tools.js';
|
|
8
|
+
export * from './lib/tool-retriever.js';
|
|
9
|
+
export * from './lib/sandbox.js';
|
|
10
|
+
export * from './lib/vault.js';
|
|
11
|
+
export * from './lib/chat-telemetry.js';
|
|
12
|
+
export * from './lib/scheduler.js';
|
|
13
|
+
export * from './lib/chat-session.js';
|
|
14
|
+
export * from './lib/memory.js';
|
|
15
|
+
export * from './lib/memory-tracker.js';
|
|
16
|
+
export * from './lib/user.js';
|
|
17
|
+
export * from './lib/people.js';
|
|
18
|
+
export * from './lib/knowledge.js';
|
|
19
|
+
export * from './lib/grounding.js';
|
|
20
|
+
export * from './lib/style.js';
|
|
21
|
+
export * from './lib/permissions.js';
|
|
22
|
+
export * from './lib/effects.js';
|
|
23
|
+
export * from './lib/skills.js';
|
|
24
|
+
export * from './lib/eval.js';
|
|
25
|
+
export * from './lib/audit.js';
|
|
26
|
+
export * from './lib/loop.js';
|
|
27
|
+
export * from './lib/runtime.js';
|
|
28
|
+
export * from './lib/digest.js';
|
|
29
|
+
export * from './lib/installers.js';
|
|
30
|
+
export * from './lib/ledger.js';
|
|
31
|
+
export * from './lib/skill-eval.js';
|
|
32
|
+
// Explicit disambiguation for `parseAmount` exported by both `people.js` and `grounding.js`
|
|
33
|
+
export { parseAmount } from './lib/grounding.js';
|
package/lib/audit.js
ADDED
|
@@ -0,0 +1,358 @@
|
|
|
1
|
+
// SCROLL — `scroll audit`: verify a repo actually FOLLOWS SCROLL, beyond frontmatter structure.
|
|
2
|
+
//
|
|
3
|
+
// Why: a coding agent (Claude Code / Cursor / Cowork) is told the rules in AGENTS.md, but it can
|
|
4
|
+
// improvise, fabricate, or claim "I followed SCROLL" without doing it. `scroll check` only validates
|
|
5
|
+
// an agent folder's structure. `scroll audit` adds (1) a repo-wide convention scan that catches the
|
|
6
|
+
// common deviations, and (2) a hash-bound report so a "pass" is tied to the exact file state — a claim
|
|
7
|
+
// that can't be faked. Run it in CI/pre-commit: the verdict comes from the machine, not the agent.
|
|
8
|
+
//
|
|
9
|
+
// Static + deterministic + zero model call. Semantic deviations (a subtly wrong SOUL, off-task output)
|
|
10
|
+
// are the EVAL's job (gold cases) — audit is the structural + convention + provenance layer.
|
|
11
|
+
import fs from 'node:fs';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
import crypto from 'node:crypto';
|
|
14
|
+
import { checkAgent, checkMcpConfigPinning, parseFrontmatter } from './scroll.js';
|
|
15
|
+
import { parseGoldCase } from './eval.js';
|
|
16
|
+
import { confirmRequired } from './effects.js';
|
|
17
|
+
import { checkSkills } from './skills.js';
|
|
18
|
+
import { openTeam, scanForPeople } from './people.js';
|
|
19
|
+
import { openUser } from './user.js';
|
|
20
|
+
|
|
21
|
+
// ── convention rules (high-signal, low-false-positive) ──
|
|
22
|
+
const VENDOR_MODEL_RE = /\b(claude-(?:[0-9]|3|sonnet|opus|haiku)|gpt-(?:[0-9]|4|5)|o[134](?:-mini)?\b|gemini-(?:[0-9]|1|2)|grok-[0-9])/i;
|
|
23
|
+
const PROMPT_VAR_RE = /\b(system_?prompt|persona|instructions|SYSTEM_PROMPT|systemMessage|agentPrompt)\b\s*[:=]\s*[`'"]/;
|
|
24
|
+
const PROMPT_TEXT_RE = /[`'"]\s*(you are an?\b|your role is\b|you are the\b|bạn là (?:một )?)/i;
|
|
25
|
+
const BANNED_DEPS = [
|
|
26
|
+
'langchain', '@langchain/core', 'langgraph', 'llamaindex', 'crewai',
|
|
27
|
+
'pinecone', '@pinecone-database/pinecone', 'weaviate-ts-client', 'chromadb', 'qdrant', '@qdrant/js-client-rest',
|
|
28
|
+
'kafkajs', 'amqplib', 'bullmq', 'bee-queue',
|
|
29
|
+
];
|
|
30
|
+
const SKIP_DIRS = new Set(['node_modules', '.git', 'runs', '.build', '.scroll', 'agents', 'dist', 'build', 'coverage', 'test', 'tests', '__tests__', 'eval', 'evals']);
|
|
31
|
+
|
|
32
|
+
function listCodeFiles(cwd) {
|
|
33
|
+
const out = [];
|
|
34
|
+
(function walk(d) {
|
|
35
|
+
let ents; try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
|
|
36
|
+
for (const e of ents) {
|
|
37
|
+
if (e.name !== '.' && e.name.startsWith('.')) continue;
|
|
38
|
+
if (SKIP_DIRS.has(e.name)) continue;
|
|
39
|
+
const p = path.join(d, e.name);
|
|
40
|
+
if (e.isDirectory()) walk(p);
|
|
41
|
+
else if (/\.(m?js|cjs|ts|tsx|jsx|py)$/.test(e.name)) out.push(p);
|
|
42
|
+
}
|
|
43
|
+
})(cwd);
|
|
44
|
+
return out;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export function scanConventions(cwd = process.cwd()) {
|
|
48
|
+
const issues = [];
|
|
49
|
+
const add = (rule, severity, file, line, msg) => issues.push({ rule, severity, file: path.relative(cwd, file) || file, line, msg });
|
|
50
|
+
|
|
51
|
+
// banned infra in package.json (clearest architectural violation)
|
|
52
|
+
const pkgPath = path.join(cwd, 'package.json');
|
|
53
|
+
if (fs.existsSync(pkgPath)) {
|
|
54
|
+
try {
|
|
55
|
+
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
|
|
56
|
+
const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
|
|
57
|
+
for (const d of BANNED_DEPS) if (deps[d]) add('banned-infra', 'error', pkgPath, 0, `dependency "${d}" — SCROLL coordinates through the filesystem, not an engine/DB/queue/graph framework`);
|
|
58
|
+
} catch { /* ignore unparseable package.json */ }
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// scan app code for persona/model that belongs in the agent folder
|
|
62
|
+
for (const f of listCodeFiles(cwd)) {
|
|
63
|
+
let lines; try { lines = fs.readFileSync(f, 'utf8').split('\n'); } catch { continue; }
|
|
64
|
+
lines.forEach((ln, i) => {
|
|
65
|
+
const n = i + 1;
|
|
66
|
+
if (PROMPT_VAR_RE.test(ln) || PROMPT_TEXT_RE.test(ln)) add('prompt-in-code', 'warn', f, n, 'persona/system-prompt text in code — move it to the agent SOUL.md');
|
|
67
|
+
if (VENDOR_MODEL_RE.test(ln)) add('hardcoded-model', 'warn', f, n, 'hardcoded model id in code — declare it in IDENTITY.md and pass it as a parameter (ignore if this is your provider/tool adapter)');
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
return issues;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// content hash binds a "pass" to the exact agent file state (anti-fabrication / anti-drift)
|
|
74
|
+
function agentFilesHash(dir) {
|
|
75
|
+
const h = crypto.createHash('sha256');
|
|
76
|
+
for (const f of ['IDENTITY.md', 'SOUL.md', 'TOOLS.md', 'hard-rules.md', '.mcp.json']) {
|
|
77
|
+
const p = path.join(dir, f);
|
|
78
|
+
if (fs.existsSync(p)) {
|
|
79
|
+
try { if (fs.statSync(p).isFile()) h.update(`${f}\0`).update(fs.readFileSync(p)); } catch { /* skip */ }
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
// Include custom `hard_rules` files referenced in IDENTITY.md frontmatter
|
|
83
|
+
try {
|
|
84
|
+
const idPath = path.join(dir, 'IDENTITY.md');
|
|
85
|
+
if (fs.existsSync(idPath)) {
|
|
86
|
+
const { frontmatter } = parseFrontmatter(fs.readFileSync(idPath, 'utf8'));
|
|
87
|
+
const customRules = frontmatter?.hard_rules;
|
|
88
|
+
const list = Array.isArray(customRules) ? customRules : (typeof customRules === 'string' ? [customRules] : []);
|
|
89
|
+
for (const rel of list.map(String).sort()) {
|
|
90
|
+
const p = path.resolve(dir, rel);
|
|
91
|
+
if (fs.existsSync(p) && fs.statSync(p).isFile()) {
|
|
92
|
+
h.update(`hard_rules:${rel}\0`).update(fs.readFileSync(p));
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
} catch { /* skip */ }
|
|
97
|
+
// Include memory/lessons.md if present inside the agent folder
|
|
98
|
+
const lessonsPath = path.join(dir, 'memory', 'lessons.md');
|
|
99
|
+
if (fs.existsSync(lessonsPath)) {
|
|
100
|
+
try { if (fs.statSync(lessonsPath).isFile()) h.update('memory/lessons.md\0').update(fs.readFileSync(lessonsPath)); } catch { /* skip */ }
|
|
101
|
+
}
|
|
102
|
+
// Hash evals/** recursively so nested fixtures/suites cannot be modified undetected
|
|
103
|
+
hashTree(h, path.join(dir, 'evals'), 'evals');
|
|
104
|
+
hashTree(h, path.join(dir, 'skills'), 'skills'); // v1.8: the agent's own skills are part of the agent
|
|
105
|
+
h.update('people\0').update(JSON.stringify(scanForPeople(dir))); // v1.9 §41: a card dropped in later breaks --verify
|
|
106
|
+
return h.digest('hex').slice(0, 16);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
// ── §41 privacy: nothing about a person travels inside something meant to be shared ──
|
|
110
|
+
// Shared = every agent folder, every repo skill, every plugin bundle (a folder with a manifest, or a
|
|
111
|
+
// .plugin/.zip archive). The cards themselves live in the deployment's people dir, outside all of it.
|
|
112
|
+
const PKG_SKIP = new Set(['node_modules', '.git', 'runs', '.scroll', '.build', 'agents', 'skills', 'people', 'knowledge']);
|
|
113
|
+
function findBundles(cwd, maxDepth = 3) {
|
|
114
|
+
const out = [];
|
|
115
|
+
const has = (d, f) => fs.existsSync(path.join(d, f));
|
|
116
|
+
const pluginManifest = (d) => has(d, 'plugin.json') || has(d, path.join('.claude-plugin', 'plugin.json'));
|
|
117
|
+
// a bundle: a plugin manifest, or the agent-pack shape `scroll plugin add` reads (manifest.json + agents/ or skills/)
|
|
118
|
+
const isBundle = (d) => pluginManifest(d) || (has(d, 'manifest.json') && (has(d, 'agents') || has(d, 'skills')));
|
|
119
|
+
if (pluginManifest(cwd)) out.push(cwd); // the repo itself is published as a plugin
|
|
120
|
+
(function walk(d, depth) {
|
|
121
|
+
let ents; try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
|
|
122
|
+
for (const e of ents.sort((a, b) => (a.name < b.name ? -1 : 1))) {
|
|
123
|
+
if (PKG_SKIP.has(e.name) || (e.name.startsWith('.') && e.name !== '.claude-plugin')) continue;
|
|
124
|
+
const p = path.join(d, e.name);
|
|
125
|
+
if (e.isDirectory()) { if (isBundle(p)) out.push(p); else if (depth < maxDepth) walk(p, depth + 1); }
|
|
126
|
+
else if (e.isFile() && /\.(plugin|zip)$/i.test(e.name)) out.push(p);
|
|
127
|
+
}
|
|
128
|
+
})(cwd, 1);
|
|
129
|
+
return out;
|
|
130
|
+
}
|
|
131
|
+
function privacyLabel(kind) {
|
|
132
|
+
if (kind === 'user-md') return 'a USER.md';
|
|
133
|
+
if (kind === 'people-dir') return 'a people/ folder';
|
|
134
|
+
if (kind === 'knowledge-dir') return 'a knowledge/ folder';
|
|
135
|
+
if (kind === 'card') return 'a person card';
|
|
136
|
+
return 'a person card, USER.md or knowledge/ inside the archive';
|
|
137
|
+
}
|
|
138
|
+
// §41 content-leak check: scan shareable packages (agents/, skills/, plugin bundles) for canary strings
|
|
139
|
+
export function scanCanaries(cwd, canaries = []) {
|
|
140
|
+
const tokens = [...new Set((canaries || []).map((x) => String(x || '').trim()).filter((x) => x.length >= 6))];
|
|
141
|
+
if (!tokens.length) return [];
|
|
142
|
+
const hits = [];
|
|
143
|
+
const scanFile = (file, label) => {
|
|
144
|
+
let text;
|
|
145
|
+
try { text = fs.readFileSync(file, 'utf8'); } catch { return; }
|
|
146
|
+
for (const tok of tokens) {
|
|
147
|
+
if (text.includes(tok)) hits.push({ file: label, canary: tok });
|
|
148
|
+
}
|
|
149
|
+
};
|
|
150
|
+
const walkDir = (dir, prefix, depth = 0) => {
|
|
151
|
+
if (!fs.existsSync(dir) || depth > 6) return;
|
|
152
|
+
let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
|
|
153
|
+
for (const e of ents.sort((a, b) => (a.name < b.name ? -1 : 1))) {
|
|
154
|
+
if (e.name === 'node_modules' || e.name === '.git' || e.name === '.build') continue;
|
|
155
|
+
const p = path.join(dir, e.name);
|
|
156
|
+
const rel = `${prefix}/${e.name}`;
|
|
157
|
+
if (e.isDirectory()) walkDir(p, rel, depth + 1);
|
|
158
|
+
else if (e.isFile()) scanFile(p, rel);
|
|
159
|
+
}
|
|
160
|
+
};
|
|
161
|
+
walkDir(path.join(cwd, 'agents'), 'agents');
|
|
162
|
+
walkDir(path.join(cwd, 'skills'), 'skills');
|
|
163
|
+
for (const b of findBundles(cwd)) {
|
|
164
|
+
const rel = path.relative(cwd, b) || '.';
|
|
165
|
+
if (fs.statSync(b).isDirectory()) walkDir(b, rel);
|
|
166
|
+
else scanFile(b, rel);
|
|
167
|
+
}
|
|
168
|
+
return hits;
|
|
169
|
+
}
|
|
170
|
+
export function auditPrivacy(cwd = process.cwd(), opts = {}) {
|
|
171
|
+
const issues = [];
|
|
172
|
+
const say = (where, h) => issues.push(`${where}${h.file ? '/' + h.file : ''}${h.entry ? ' → ' + h.entry : ''}: ${privacyLabel(h.kind)} — shared packages never carry people or deployment data; USER.md and knowledge/ live at deployment root (§41)`);
|
|
173
|
+
const sk = path.join(cwd, 'skills');
|
|
174
|
+
if (fs.existsSync(sk)) for (const n of fs.readdirSync(sk).sort()) for (const h of scanForPeople(path.join(sk, n))) say(`skills/${n}`, h);
|
|
175
|
+
for (const b of findBundles(cwd)) {
|
|
176
|
+
const rel = path.relative(cwd, b) || '.';
|
|
177
|
+
for (const h of scanForPeople(b)) say(rel, h);
|
|
178
|
+
}
|
|
179
|
+
const userDoc = openUser({ cwd });
|
|
180
|
+
const canaries = [...userDoc.canaries(), ...(opts.canaries || [])];
|
|
181
|
+
for (const hit of scanCanaries(cwd, canaries)) {
|
|
182
|
+
issues.push(`${hit.file}: leaked private canary "${hit.canary.slice(0, 12)}..." inside a shareable package (§41)`);
|
|
183
|
+
}
|
|
184
|
+
return issues;
|
|
185
|
+
}
|
|
186
|
+
// every file under a folder, in a fixed order (symlinks are not followed)
|
|
187
|
+
function hashTree(h, dir, label) {
|
|
188
|
+
if (!fs.existsSync(dir)) return;
|
|
189
|
+
(function walk(d, rel) {
|
|
190
|
+
let ents; try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
|
|
191
|
+
ents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
192
|
+
for (const e of ents) {
|
|
193
|
+
if (e.name === '.git' || e.name === 'node_modules') continue;
|
|
194
|
+
const p = path.join(d, e.name); const r = `${rel}/${e.name}`;
|
|
195
|
+
if (e.isDirectory()) walk(p, r);
|
|
196
|
+
else if (e.isFile()) { try { h.update(`${r}\0`).update(fs.readFileSync(p)); } catch { /* skip */ } }
|
|
197
|
+
else if (e.isSymbolicLink()) { try { h.update(`${r}\0->${fs.readlinkSync(p)}`); } catch { /* skip */ } }
|
|
198
|
+
}
|
|
199
|
+
})(dir, label);
|
|
200
|
+
}
|
|
201
|
+
function repoSkillsHash(cwd) {
|
|
202
|
+
const h = crypto.createHash('sha256');
|
|
203
|
+
hashTree(h, path.join(cwd, 'skills'), 'skills');
|
|
204
|
+
return h.digest('hex').slice(0, 16);
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
// ── §30 fixture provenance ──
|
|
208
|
+
// A suite where every precondition was hand-built is a suite that grades nothing but itself.
|
|
209
|
+
function auditFixtures(evalsDir) {
|
|
210
|
+
if (!fs.existsSync(evalsDir)) return [];
|
|
211
|
+
const files = fs.readdirSync(evalsDir).filter((f) => f.endsWith('.md') && f !== 'rubric.md');
|
|
212
|
+
if (!files.length) return [];
|
|
213
|
+
const out = [];
|
|
214
|
+
const provs = [];
|
|
215
|
+
for (const f of files) {
|
|
216
|
+
let gc; try { gc = parseGoldCase(fs.readFileSync(path.join(evalsDir, f), 'utf8'), f); } catch { continue; }
|
|
217
|
+
const fx = gc.fixture || {};
|
|
218
|
+
provs.push(fx.provenance || null);
|
|
219
|
+
for (const issue of fx.issues || []) out.push(`evals/${f}: ${issue} (§30)`);
|
|
220
|
+
}
|
|
221
|
+
const declared = provs.filter(Boolean);
|
|
222
|
+
if (declared.length && declared.every((p) => p === 'synthetic')) {
|
|
223
|
+
out.push('every gold case uses a hand-built fixture (provenance=synthetic) — the path that should CREATE these preconditions is unverified; add at least one `product-path` case covering arm/setup (§30)');
|
|
224
|
+
}
|
|
225
|
+
return out;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
// ── §28 effect confirmation ──
|
|
229
|
+
// A write nobody reads back is a write nobody has evidence of.
|
|
230
|
+
function auditConfirms(agentDir, cwd) {
|
|
231
|
+
const out = [];
|
|
232
|
+
for (const file of [path.join(agentDir, '.mcp.json'), path.join(cwd, '.mcp.json')]) {
|
|
233
|
+
if (!fs.existsSync(file)) continue;
|
|
234
|
+
let j; try { j = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
|
|
235
|
+
const servers = j.mcpServers || {};
|
|
236
|
+
for (const [srv, cfg] of Object.entries(servers)) {
|
|
237
|
+
for (const [tool, t] of Object.entries((cfg && cfg.tools) || {})) {
|
|
238
|
+
const tier = t && t.risk;
|
|
239
|
+
if (!confirmRequired(tier)) continue;
|
|
240
|
+
if (!t.confirm || !t.confirm.probe || !t.confirm.expect) {
|
|
241
|
+
out.push(`${srv}.${tool}: risk=${tier} write has no \`confirm\` { probe, expect } — a non-error response is not evidence the write happened; a conformant runner blocks it (§28)`);
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
return out;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
export function auditRepo(cwd = process.cwd(), opts = {}) {
|
|
250
|
+
const base = path.join(cwd, 'agents');
|
|
251
|
+
const names = opts.name
|
|
252
|
+
? [opts.name]
|
|
253
|
+
: (fs.existsSync(base) ? fs.readdirSync(base).filter((n) => fs.existsSync(path.join(base, n, 'IDENTITY.md'))) : []);
|
|
254
|
+
const agents = names.map((name) => {
|
|
255
|
+
const c = checkAgent(name, cwd);
|
|
256
|
+
const dir = path.join(base, name);
|
|
257
|
+
const evalsDir = path.join(dir, 'evals');
|
|
258
|
+
const evalCount = fs.existsSync(evalsDir) ? fs.readdirSync(evalsDir).filter((f) => f.endsWith('.md') && f !== 'rubric.md').length : 0;
|
|
259
|
+
const warnings = [...c.warnings];
|
|
260
|
+
if (evalCount < 3) warnings.push(`only ${evalCount} gold eval case(s) — SCROLL expects ≥3 before an agent ships`);
|
|
261
|
+
warnings.push(...auditFixtures(evalsDir)); // §30
|
|
262
|
+
warnings.push(...auditConfirms(dir, cwd)); // §28
|
|
263
|
+
const errors = [...c.errors];
|
|
264
|
+
for (const h of scanForPeople(dir)) errors.push(`agents/${name}/${h.file}: ${privacyLabel(h.kind)} — an agent folder never carries a person or deployment data (§7, §41); move USER.md and knowledge/ to deployment root`);
|
|
265
|
+
let skills = null;
|
|
266
|
+
if (!c.errors.length) { // v1.8 §36: skills the agent and repo ship
|
|
267
|
+
const sk = checkSkills(cwd, name);
|
|
268
|
+
errors.push(...sk.errors); warnings.push(...sk.warnings);
|
|
269
|
+
skills = sk.counts;
|
|
270
|
+
}
|
|
271
|
+
return { name, level: c.level, errors, warnings, evalCount, skills, filesHash: fs.existsSync(dir) ? agentFilesHash(dir) : null };
|
|
272
|
+
});
|
|
273
|
+
const conventions = scanConventions(cwd);
|
|
274
|
+
for (const errMsg of checkMcpConfigPinning(cwd)) {
|
|
275
|
+
conventions.push({ rule: 'mcp-unpinned-package', severity: 'error', file: '.mcp.json', line: 0, msg: errMsg });
|
|
276
|
+
}
|
|
277
|
+
const people = auditPeople(cwd, agents.map((a) => ({ name: a.name, identity: identityOf(path.join(base, a.name)) })), opts);
|
|
278
|
+
const errorCount = agents.reduce((s, a) => s + a.errors.length, 0) + conventions.filter((c) => c.severity === 'error').length + people.errors.length;
|
|
279
|
+
const warnCount = agents.reduce((s, a) => s + a.warnings.length, 0) + conventions.filter((c) => c.severity === 'warn').length + people.warnings.length;
|
|
280
|
+
return {
|
|
281
|
+
tool: '@agentpro/scroll audit', generatedAt: new Date().toISOString(),
|
|
282
|
+
agents, conventions, people, errorCount, warnCount, skillsHash: repoSkillsHash(cwd),
|
|
283
|
+
privacyHash: crypto.createHash('sha256').update(JSON.stringify(people.privacy)).digest('hex').slice(0, 16),
|
|
284
|
+
verdict: errorCount === 0 ? 'pass' : 'fail',
|
|
285
|
+
};
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
function identityOf(dir) {
|
|
289
|
+
try { return parseFrontmatter(fs.readFileSync(path.join(dir, 'IDENTITY.md'), 'utf8')).frontmatter || {}; } catch { return {}; }
|
|
290
|
+
}
|
|
291
|
+
// §38–§41 at the repo level: shared packages carry no people; the cards (if any) are valid; the people
|
|
292
|
+
// dir is outside agents/ and out of git unless the deployment says otherwise; person-owned WORK.md
|
|
293
|
+
// steps name people who have a card.
|
|
294
|
+
export function auditPeople(cwd = process.cwd(), agents = [], opts = {}) {
|
|
295
|
+
const errors = [], warnings = [];
|
|
296
|
+
const privacy = auditPrivacy(cwd, opts);
|
|
297
|
+
errors.push(...privacy);
|
|
298
|
+
let userDoc = null;
|
|
299
|
+
try { userDoc = openUser({ cwd }); } catch (e) { errors.push(`user: ${e.message}`); }
|
|
300
|
+
if (userDoc && userDoc.exists) {
|
|
301
|
+
const uc = userDoc.check({ agents });
|
|
302
|
+
errors.push(...uc.errors); warnings.push(...uc.warnings);
|
|
303
|
+
const inRepo = userDoc.file.startsWith(cwd + path.sep);
|
|
304
|
+
if (inRepo && !userDoc.cfg.tracked) {
|
|
305
|
+
const rel = path.relative(cwd, userDoc.file).split(path.sep).join('/');
|
|
306
|
+
const gi = fs.existsSync(path.join(cwd, '.gitignore')) ? fs.readFileSync(path.join(cwd, '.gitignore'), 'utf8').split('\n').map((l) => l.trim().replace(/^\//, '').replace(/\/$/, '')) : [];
|
|
307
|
+
if (!gi.includes(rel) && !gi.includes('USER.md')) warnings.push(`${rel} is not in .gitignore — USER.md is private by default; ignore it, or set user.tracked: true for a private repo (§41)`);
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
let team = null;
|
|
311
|
+
try { team = openTeam({ cwd }); } catch (e) { errors.push(`people: ${e.message}`); }
|
|
312
|
+
if (team) {
|
|
313
|
+
// When deployment USER.md is active, role coverage is checked against USER.md above — do not emit
|
|
314
|
+
// spurious legacy people/ "nobody holds role" warnings for an unused people/ directory (§44).
|
|
315
|
+
const chk = team.check({ agents: (userDoc && userDoc.exists) ? [] : agents });
|
|
316
|
+
errors.push(...chk.errors); warnings.push(...chk.warnings);
|
|
317
|
+
const inRepo = team.dir.startsWith(cwd + path.sep);
|
|
318
|
+
if (inRepo && fs.existsSync(team.dir) && !team.cfg.tracked) {
|
|
319
|
+
const rel = path.relative(cwd, team.dir).split(path.sep).join('/');
|
|
320
|
+
const gi = fs.existsSync(path.join(cwd, '.gitignore')) ? fs.readFileSync(path.join(cwd, '.gitignore'), 'utf8').split('\n').map((l) => l.trim().replace(/^\//, '').replace(/\/$/, '')) : [];
|
|
321
|
+
if (!gi.includes(rel)) warnings.push(`${rel}/ is not in .gitignore — person cards are private by default; ignore it, or set people.tracked: true for a private repo (§41)`);
|
|
322
|
+
}
|
|
323
|
+
const wp = path.join(cwd, 'WORK.md');
|
|
324
|
+
if (fs.existsSync(wp)) {
|
|
325
|
+
const persons = [...fs.readFileSync(wp, 'utf8').matchAll(/^\s*owner:\s*["']?person:([a-z][a-z0-9-]*)/gm)].map((m) => m[1]);
|
|
326
|
+
for (const p of [...new Set(persons)]) {
|
|
327
|
+
if (userDoc && userDoc.exists) {
|
|
328
|
+
if (!userDoc.get(p) || !userDoc.get(p).valid) errors.push(`WORK.md: step owned by person:${p}, who is not a valid entry in USER.md (§40)`);
|
|
329
|
+
} else if (!fs.existsSync(team.dir)) {
|
|
330
|
+
warnings.push(`WORK.md: step owned by person:${p}, but there is no USER.md or people dir here to check the person`);
|
|
331
|
+
} else if (!team.get(p) || !team.get(p).valid) {
|
|
332
|
+
errors.push(`WORK.md: step owned by person:${p}, who has no valid card (§40)`);
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
return { errors, warnings, privacy, cards: (userDoc && userDoc.exists ? userDoc.cards.size : 0) + (team ? team.cards.size : 0), userActive: !!(userDoc && userDoc.active) };
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// CI / anti-fabrication: compare current file state to the committed .scroll/audit.json.
|
|
341
|
+
// No report, hash drift, or a recorded failure → not trustworthy → fail.
|
|
342
|
+
export function verifyAgainstRecord(cwd, fresh) {
|
|
343
|
+
const recPath = path.join(cwd, '.scroll', 'audit.json');
|
|
344
|
+
if (!fs.existsSync(recPath)) return { ok: false, reason: 'no .scroll/audit.json — `scroll audit` was never run here (a self-claim is not evidence)' };
|
|
345
|
+
let prev; try { prev = JSON.parse(fs.readFileSync(recPath, 'utf8')); } catch { return { ok: false, reason: '.scroll/audit.json is unreadable' }; }
|
|
346
|
+
const prevHash = Object.fromEntries((prev.agents || []).map((a) => [a.name, a.filesHash]));
|
|
347
|
+
const freshNames = new Set((fresh.agents || []).map((a) => a.name));
|
|
348
|
+
const drifted = fresh.agents.filter((a) => prevHash[a.name] !== a.filesHash).map((a) => a.name);
|
|
349
|
+
for (const a of prev.agents || []) {
|
|
350
|
+
if (a?.name && !freshNames.has(a.name)) drifted.push(`${a.name} (deleted)`);
|
|
351
|
+
}
|
|
352
|
+
if (prev.skillsHash !== undefined && prev.skillsHash !== fresh.skillsHash) drifted.push('skills/');
|
|
353
|
+
if (prev.privacyHash !== undefined && prev.privacyHash !== fresh.privacyHash) drifted.push('shared packages (people)');
|
|
354
|
+
if (drifted.length) return { ok: false, reason: `files changed since the recorded audit: ${drifted.join(', ')} — re-run \`scroll audit\` (the report no longer matches the code)` };
|
|
355
|
+
if (prev.verdict !== 'pass') return { ok: false, reason: 'the recorded audit verdict was not "pass"' };
|
|
356
|
+
if (fresh.verdict !== 'pass') return { ok: false, reason: 'current audit does not pass' };
|
|
357
|
+
return { ok: true, reason: 'audit record matches current file state and passes' };
|
|
358
|
+
}
|