@agentpro/scroll 0.0.0-stage → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +55 -0
  2. package/LICENSE +21 -0
  3. package/README.md +293 -2
  4. package/SPEC.md +1079 -0
  5. package/bin/scroll.js +8 -0
  6. package/docs/prompt-caching.md +128 -0
  7. package/index.js +33 -0
  8. package/lib/audit.js +358 -0
  9. package/lib/auth.js +849 -0
  10. package/lib/chat-sdk/admin-controller.js +289 -0
  11. package/lib/chat-sdk/debouncer.js +94 -0
  12. package/lib/chat-sdk/group-grants.js +150 -0
  13. package/lib/chat-sdk/index.js +222 -0
  14. package/lib/chat-sdk/long-task-runner.js +413 -0
  15. package/lib/chat-session.js +1788 -0
  16. package/lib/chat-telemetry.js +557 -0
  17. package/lib/codex-app-server.js +851 -0
  18. package/lib/digest.js +112 -0
  19. package/lib/effects.js +157 -0
  20. package/lib/eval.js +408 -0
  21. package/lib/grounding.js +356 -0
  22. package/lib/installers.js +176 -0
  23. package/lib/knowledge.js +335 -0
  24. package/lib/ledger.js +38 -0
  25. package/lib/loop.js +197 -0
  26. package/lib/mcp-client.js +926 -0
  27. package/lib/memory-cli.js +66 -0
  28. package/lib/memory-tracker.js +1472 -0
  29. package/lib/memory.js +1279 -0
  30. package/lib/people-cli.js +81 -0
  31. package/lib/people.js +534 -0
  32. package/lib/permissions.js +272 -0
  33. package/lib/providers.js +1572 -0
  34. package/lib/runtime.js +928 -0
  35. package/lib/sandbox.js +744 -0
  36. package/lib/scheduler.js +402 -0
  37. package/lib/scroll.js +1225 -0
  38. package/lib/skill-cli.js +120 -0
  39. package/lib/skill-eval.js +156 -0
  40. package/lib/skills.js +860 -0
  41. package/lib/style.js +126 -0
  42. package/lib/tool-retriever.js +489 -0
  43. package/lib/tools.js +1833 -0
  44. package/lib/user.js +711 -0
  45. package/lib/vault.js +151 -0
  46. package/package.json +88 -4
  47. package/templates/agent/IDENTITY.md +56 -0
  48. package/templates/agent/SOUL.md +23 -0
  49. package/templates/agent/TOOLS.md +25 -0
  50. package/templates/agent/evals/case-02-citation-discipline.md +29 -0
  51. package/templates/agent/evals/case-03-boundary.md +27 -0
  52. package/templates/agent/evals/case-example.md +43 -0
  53. package/templates/agent/hard-rules.md +11 -0
  54. package/templates/agent/memory/lessons.md +5 -0
  55. package/templates/agent/memory/log/.gitkeep +0 -0
  56. package/templates/external-safety-contract.md +5 -0
  57. package/templates/long-task-planner.md +17 -0
  58. package/templates/work/LOOP.md +37 -0
  59. package/templates/work/WORK.md +50 -0
  60. package/types/chat.d.ts +61 -0
  61. package/types/index.d.ts +112 -0
package/AGENTS.md ADDED
@@ -0,0 +1,55 @@
1
+ <!-- This file is read automatically by AI coding tools (Claude Code, Cursor, Cowork, Codex...). It teaches the AI how to build agents the SCROLL way, so vibecoders get compliant agents by default — without reading the docs. Ship a copy of this at the root of any SCROLL repo. -->
2
+
3
+ # Working in a SCROLL repo
4
+
5
+ This repository uses **SCROLL**: AI agents are folders of markdown, not code. If you are an AI assistant editing this repo, follow these rules. They are not optional — `scroll check` runs in CI and will fail the build otherwise.
6
+
7
+ ## Where agents live
8
+ - App-specific agents: `agents/<name>/`
9
+ - Never put an agent's persona, rules, or model choice inside application code (`.js`/`.ts`/`.py`). Those belong in the agent's files.
10
+
11
+ ## An agent is exactly these files
12
+ ```
13
+ agents/<name>/
14
+ ├── IDENTITY.md # YAML frontmatter — name, version, runtimes, model, capabilities, pronoun
15
+ ├── SOUL.md # the persona in prose — voice, values, behavior
16
+ ├── TOOLS.md # capabilities (logical) + tool_bindings (per runtime)
17
+ ├── hard-rules.md # rules the agent must never break
18
+ ├── memory/ # lessons.md, log/, and private|team|global/
19
+ └── evals/ # gold test cases + rubric.md
20
+ ```
21
+
22
+ ## Hard rules when creating or editing an agent
23
+ 1. **Always start with `scroll new <name>`** — do not hand-create the folder. The scaffold is the source of correctness.
24
+ 2. **`IDENTITY.md` frontmatter must validate** against the schema: `name`, `version` (semver), `runtimes[]`, `model`, `capabilities[]` are required. Your editor will flag errors; fix them before finishing.
25
+ 3. **Put behavior in `SOUL.md`, not in code.** If you're tempted to write a prompt string in a `.ts` file, stop — it goes in `SOUL.md`.
26
+ 4. **Tools are wired in `TOOLS.md`**, declared as logical `capabilities` + per-runtime `tool_bindings`. The actual tool *implementations* stay in app code; only the *wiring* lives here.
27
+ 5. **Every agent needs at least 3 gold eval cases** in `evals/` before it ships. A gold case = a fixed input + a checklist of what a correct output must contain + at least one planted trap (a bad source or contradiction it must not fall for).
28
+ 6. **Multi-agent is opt-in.** Default to a single agent. Only introduce a controller + sub-agents (via `WORK.md`) when the task is genuinely parallel and read-heavy. Write/coupled tasks stay single-threaded.
29
+ 7. **Coordinate through files, never message-passing.** Shared findings go to `blackboard/` (one file per entry). A single controller owns `WORK.md`. Handoffs pass a summary, not full history.
30
+ 8. **Order context for caching:** stable content first (tools, hard-rules, IDENTITY, SOUL), volatile content last (current task, fresh blackboard). Never interleave.
31
+ 9. **Declare risk as data, never prose (v1.4).** A tool's risk tier goes in `.mcp.json` (per tool) or `IDENTITY.security.risk_defaults` (per capability) — never as a sentence in a markdown body, where a model can be talked out of it. Tiers: `read_only · reversible_write · external_comm · financial · destructive`. `financial`/`destructive` actions are gated and **grounding-checked**: list the parameters to ground (`ground: [...]`) so a fabricated id/amount can't execute.
32
+ 10. **For self-directed or scheduled work, write a `LOOP.md` (the outer loop).** It MUST declare at least one `stop_conditions` (a loop that can't stop is unsafe). The inner loop is `scroll run`; the outer loop is `scroll loop`. Never hand-roll a `while(true)` — it bypasses the caps, gates, and digest.
33
+ 11. **Memory about people is data the machine admits, not notes the model writes (v1.7).** Facts about the people, groups or projects an agent serves go through `lib/memory.js` (§31–33) — never into `agents/<name>/memory/`, never into the repo. Don't hand-roll a "user notes" file, a vector store, or a prompt that tells the model what to remember: propose facts with a quote and a turn reference and let the gate decide. Keep the store outside every workdir.
34
+
35
+ 12. **Skills are folders the loader admits, not text you paste into prompts (v1.8).** Use the open `SKILL.md` format (`name` + a `description` that says what and when). Put the agent's own skills in `agents/<name>/skills/`, shared ones in `skills/`, and other tools' skill folders under `skills.external_dirs` in `scroll.config.yaml` — never copy a skill's text into `SOUL.md` or code. Declare what a skill needs (`allowed-tools` or `metadata.scroll.requires`), give it ≥3 cases in its `evals/`, and run `scroll skill eval` — keep a skill only if it beats the baseline. Never weaken the scan or trust a source on a model's say-so.
36
+
37
+ 13. **Deployment `USER.md` lives outside `agents/` (v1.9).** Never put a `USER.md`, a `knowledge/` folder, a `people/` folder, or private principal canary strings inside an agent folder, a skill, or a plugin bundle — `scroll audit` fails on it. One deployment has one `USER.md` naming the principal (`principal: { kind, name, self, call_others, handoff }`) and internal team members (`people: [{ id, name, call, role, approve, max_amount }]`); frontmatter stays machine-only and never enters the prompt. Customers and external contacts belong in subject memory (§31), never in `USER.md`. An agent never edits `USER.md` (`guard()`); approvals are checked against `USER.md` in code (`canApprove`), never in prose.
38
+
39
+ ## Before you say you're done
40
+ Run, in order — and do not merely *claim* you ran them; the human/CI re-runs `scroll audit --verify`:
41
+ ```bash
42
+ scroll check <name> # structure (and the agent's skills) must pass
43
+ scroll audit # conventions + hash-bound report → writes .scroll/audit.json
44
+ scroll build <name> # must render without error
45
+ scroll eval <name> # score must not regress vs the previous run
46
+ ```
47
+ `scroll audit` is the compliance gate. It flags the things an assistant tends to improvise: persona/prompt text left in code, hardcoded model ids, banned infra (DBs, queues, graph/agent frameworks), and agents shipped without ≥3 gold evals. It writes a report **bound to a content hash**, so a "pass" can't be faked or go stale — if you edit files after auditing, `scroll audit --verify` fails. Do not mark the task complete on a failing check or audit.
48
+
49
+ ## What NOT to do
50
+ - ❌ Don't add a database, message queue, or orchestration engine. SCROLL coordinates through the filesystem.
51
+ - ❌ Don't hardcode a model vendor in app logic. The agent declares its model in `IDENTITY.md`; the runtime is swappable.
52
+ - ❌ Don't let an agent run unbounded. Long tasks are split into short, checkpointed steps with hard caps.
53
+ - ❌ Don't bypass `WORK.md` to have agents call each other directly — that creates the infinite-handoff failure mode.
54
+
55
+ Follow these and your agents are portable, gradeable, observable, and cheap by construction.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Agent Pro
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,294 @@
1
- # Temporary Holding Version
1
+ <!-- This is the PUBLIC, publishable README — the face of the framework devs see. EN by default (global dev audience). VN version available on request. -->
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # 📜 SCROLL — a harness for agentic loops
4
+
5
+ **Build AI agents as folders, not code.** A filesystem-native harness: an agent is a directory of markdown, the LLM does the work, a thin CLI coordinates. No engine, no database, no runtime lock-in. Runs the same locally and in the cloud — and gives you the **outer loop** (loop engineering) so an agent finds its own work, does it, verifies it, and remembers it, without you prompting each turn.
6
+
7
+ ```bash
8
+ npm i -g @agentpro/scroll
9
+ scroll new researcher # scaffold a compliant agent (L1-ready: hard-rules + 3 gold evals)
10
+ scroll build researcher # render it for Cowork / Codex / Gemini / voice
11
+ scroll run researcher --task "…" # inner loop: one harnessed run — capped, gated, checkpointed
12
+ scroll loop LOOP.md # outer loop: schedule + find work + stop conditions
13
+ ```
14
+
15
+ `MIT` · `Node >= 20` · **Spec v2.5** · **`@agentpro/scroll` 2.5.0** + **`@agentpro/scroll-telegram` 2.5.0** · zero runtime deps · runs on Claude · OpenAI/Codex · Gemini · Grok
16
+
17
+ > **GitHub topics:** `loop-engineering` · `agent-harness` · `agentic` · `agentic-loops` · `ai-agents` · `autonomous-agents` · `tool-retriever` · `llm` · `mcp`
18
+
19
+ ---
20
+
21
+ ## Why SCROLL
22
+
23
+ Most agent frameworks make you import a heavy runtime (graphs, schedulers, vector DBs) and lock you to one model vendor. SCROLL bets the opposite way:
24
+
25
+ | | Heavy frameworks | **SCROLL** |
26
+ |---|---|---|
27
+ | An agent is… | an object in code | **a folder of markdown** |
28
+ | State lives in… | a database / session | **the filesystem + git** |
29
+ | Orchestration | the framework runtime | **a declarative DAG you advance deterministically** |
30
+ | Safety | hope the model behaves | **risk-tiered gates + grounding, enforced in code** |
31
+ | Model | locked to one vendor | **vendor-neutral — one definition, any runtime** |
32
+ | The whole framework | a dependency tree | **a convention + one small CLI** |
33
+
34
+ The thesis in one line: **SCROLL doesn't try to make the model smarter — it makes the model's built-in weaknesses unable to cause harm.** Every mechanism below compensates for a specific model failure mode.
35
+
36
+ | Mechanism | The model weakness it neutralizes |
37
+ |---|---|
38
+ | Risk-tiered permission matrix | the model doesn't understand *consequences* |
39
+ | Grounding pre-check | *hallucination* (inventing ids / amounts) |
40
+ | Tool-boundary enforcement | *sycophancy* — it can't be trusted to stop itself |
41
+ | External eval (gold cases) | biased self-assessment |
42
+ | Comprehension digest | the *user's* passive over-delegation |
43
+
44
+ ---
45
+
46
+ ## Implementation status (2026-11-21 · v2.5)
47
+
48
+ - **§47.2 Portable Tool Retriever & Room-Sticky Group Cache (v2.5)** — zero-dep `lib/tool-retriever.js` (`C/V/E` 3-set architecture, multi-field BM25F + batch `queries[]`, host JSON Schema argument validator, Transparent Unwrap `tool_invoke`, `<available_tools>` capped `<= 1,500` tok compressing 226+ tools to `< 5K` tok across all 4 providers), Room-Sticky group posture (`prefixHash` 100% invariant across alternating Owner/Teammate/Guest turns), `.scroll/mcp.lock.json` TOFU pinning (`scroll mcp diff|approve`), ASI04 prompt-injection quarantine, and `scroll check` ban on `npx …@latest`.
49
+ - **Hardened Security Boundary, OS Sandbox & D16 Production Telemetry (v2.5)** — `lib/sandbox.js` (macOS Seatbelt / Linux Bubblewrap + sanitized env allowlist), `lib/vault.js` (AES-256-GCM encrypted vault + fail-closed `${vault:KEY}`), DNS/IPv6/CGNAT `100.64.0.0/10` + manual-redirect SSRF guard + `egress_allow`, provenance-tagged §22 grounding (anti-laundering) + buffered external streaming, single-use per-call approval tokens + `canApprove()`, fail-closed read-only `confirmEffect` probes, `lib/chat-telemetry.js` (OTel GenAI `events.jsonl`, hash-chained `audit.jsonl` + `scroll audit --verify-chain`, `IDENTITY.budget` + loop/error circuit breakers, single-writer PID lock), per-conversation mutex, per-round JSONL crash recovery, and §34 `openSkills()` wired into live chat.
50
+ - **4-Provider Parity, Streamable HTTP MCP, Compaction Recovery & Multi-Turn `pass^k` Evals (v2.5)** — real SSE streaming, parallel function calling, `thinking`/`thoughtSignature` preservation, `images`, and `authStore` failover across OpenAI, Anthropic, Gemini, and Codex App-Server (`base64` vision temp-file bridge + turn-bound RPC callbacks); Streamable HTTP MCP (`Mcp-Session-Id` + HTTP `404` re-init + `Promise.allSettled` isolation); token-aware compaction + `400 context_length_exceeded` auto-recovery; `runChatEvals()` (`scroll eval --chat --trials k`); and lockstep 2-package monorepo (`@agentpro/scroll` with `@agentpro/scroll/chat` + `@agentpro/scroll-telegram`, both `dependencies: {}`).
51
+ - **§45–§50 Interactive Chat Runtime, Unified Auth, Live Tools/MCP, Multimodal, Timezone Scheduler & Async Workers (v2.0)** — `lib/chat-session.js`, `lib/memory-tracker.js` (channel-agnostic 3-axis `user` / `group` / `member` memory + L5 lessons + nightly Dream), `lib/auth.js` (file-locked OAuth 2.0 PKCE + localhost loopback callback + Device Flow + 429 failover), `lib/codex-app-server.js`, `lib/scheduler.js`, `createWorkerPool`, and `memoryStore.searchHybrid`.
52
+ - **§44 Large deployment knowledge retrieval & source-aware grounding (v1.10)** — deterministic BM25 + heading + bigram + code retrieval over `knowledge/`, conversational deliverable mode, and source-aware grounding.
53
+ - **§42–§43 Per-turn internal/external boundary, group wall, `style:` & Voice hooks (v1.9)** — verified-ID audience classifier, group lowest-trust content wall, machine-enforced `style:` block, official Voice plugin hooks with claims-invariant protection.
54
+
55
+ **Built & tested** (`npm test` runs all 24 smoke, unit & gate suites with mutation self-tests and isolated `/tmp` tarball verification):
56
+
57
+ - **§38–41 People in the agent team** — every person gets a **card** (`people/<slug>.md`) they write themselves: how to address them, their roles, what they may approve, which channels reach them, and a short note capped by code. Cards live **outside** `agents/`, so an agent folder stays shareable. Agents bind to **roles** (`serves: [owner]`); the deployment maps roles to people, and every agent of the team — sub-agents included — loads the same card into its cached prefix, so changing how a person is addressed is one edit, not one per agent. A person can **own a step** in `WORK.md`: the run asks them, stops there, and resumes when they (and only they) mark it done. An approval **names its approver**, and the runner checks that person's card — action class, amount, the deployment's ceiling — before the gate opens; every decision goes to a hash-chained audit trail. `scroll audit` fails when a card, a `USER.md` or a `people/` folder travels inside an agent folder, a skill or a plugin. Agents never edit cards: they propose, and the person decides. The suite plants seventeen bugs in the people and runtime code and fails unless each is caught.
58
+
59
+ - **§34–36 Skills** — use the skills you already have. A SCROLL agent reads skills in the open Agent Skills format (`SKILL.md`) from its own folder, the repo, and any read-only folder you point it at — another agent tool's skills folder included — with clear precedence and no copying. **The model only sees what passed**: every skill is validated and scanned (live credentials, exfiltration, remote-code pipes, destructive commands, hidden text, prompt injection) before it reaches the index, and scanned again at read time if it changed; how strict the scan is depends on how much you trust the source, and there is no flag to force a blocked skill in. Skills built around tools the agent lacks are hidden; the rest get a map from their tool names to the agent's (`AskUserQuestion → ask_owner`) without editing a line of the skill. The index is byte-stable for the prompt cache, capped by count and tokens, and `skill_list` / `skill_view` reach the rest. `scroll skill eval` runs each case **with and without** the skill on every model you name, with a blind judge, and says whether the skill earns its tokens (`keep`, `retire-or-rewrite`, `fix`). The suite plants eight bugs in the loader and fails unless each is caught.
60
+
61
+ - **§31–33 Subject memory** — one memory per person, group, project or agent, shared by every surface that talks to it (voice, chat, messaging, other agents). **The agent proposes; the machine decides**: a fact is accepted only with a verbatim quote from a stored turn **of the person it is about**, through one five-layer gate (taxonomy · evidence · provenance floor · sensitivity + secret scan · instruction-like content). Sessions and day notes give the agent continuity across surfaces; the load contract is built by code, frozen for the session and hashed (cacheable, replayable). Search is deterministic and every read is logged. **Forget reaches every copy** — journal, checkpoints, stored turns, cards, ledgers — and a tombstone stops it from being learned again. Groups share facts by namespace; one member never sees another's. Zero dependencies, no vector DB, files only; the test suite plants six bugs in the memory code and fails unless each is caught.
62
+
63
+ - **§28 Effect confirmation** — a write is not "done" because the call returned a non-error. `lib/effects.js` re-reads the state with a **separate** probe and checks a declared predicate; a mismatch emits `effect_unconfirmed` and fails the step. `financial`/`destructive` writes with no `confirm` are blocked (fail-closed) and flagged by `scroll audit`. Corollary: an unknown input field is rejected, never dropped — silently dropping input is how a system reports success for work it never did.
64
+ - **§29 Ungraded is not pass** — `verdict` is ternary (`pass | fail | ungraded`). "No check ran" is counted separately and never folded into `ok`; a judge that could not run says nothing, so it grades `ungraded` rather than `fail`.
65
+ - **§30 Fixture provenance** — gold cases declare `fixture.provenance` (`product-path | recorded | synthetic`); `scroll eval` prints it beside every verdict and `scroll audit` flags a suite built only on hand-made fixtures — the shape where a scheduler's *execute* path is green while its *arm* path was never run once.
66
+
67
+ - **Inner loop** `scroll run` — deterministic DAG advance from `WORK.md`, single controller, cost-gate, append-only `blackboard/`, hard caps + circuit breaker, stable-prefix caching, model routing, deterministic non-LLM steps, verify-before-done, per-tick checkpoint, `events.jsonl`.
68
+ - **Risk-tiered permissions** — five tiers (`read_only · reversible_write · external_comm · financial · destructive`), enforced at the **action boundary in code** (not the prompt). Risk is declared as data in `.mcp.json` / `IDENTITY.security`, never read from prose.
69
+ - **Grounding pre-check** — before a `financial`/`destructive` action, every critical parameter must trace to a real prior source; a fabricated id/amount **never executes**.
70
+ - **Outer loop** `scroll loop` + `LOOP.md` — schedule, work-source, and stop conditions for self-directed runs. A loop with no stop condition is refused.
71
+ - **Comprehension digest** — every run writes a human-readable `digest.md` from the event stream (no model call), language-aware.
72
+ - **`scroll eval`** — gold cases run N times → machine checks + consistency (`pass^k`) + optional LLM-judge + hash-bound record. **(built — earlier docs called this roadmap; it ships.)**
73
+ - **Per-language token budgeting** — `scroll cost` / the cost gate scale by language (Vietnamese ≈ 1.8× English).
74
+ - **Worktree-lite isolation** — parallel tasks get isolated working dirs (real `git worktree` with `--worktree` on a repo) so two agents never corrupt shared state.
75
+ - **Crash-resume** — `scroll run --resume` restores completed tasks from the checkpoint and finishes the rest **without re-billing**.
76
+ - **`scroll audit`** — convention scan + hash-bound compliance report (CI; `--verify`).
77
+ - **Extension installers** — `scroll mcp add` (wire an MCP server/connector into `.mcp.json`, with `${vault:KEY}` credentials + per-tool risk tiers), `scroll skill add` (install or scaffold a `SKILL.md` skill, attach it to an agent), `scroll plugin add` (unpack an agent-pack bundle: agents + skills + merged `.mcp.json`).
78
+
79
+ Providers: `mock` (offline) · `codex` · `claude` · `openai` · `anthropic` · `gemini`. On a case-gated live A/B eval the runtime cut billable tokens **50–88%** and latency **50–75%** vs an unstructured baseline, at equal-or-better quality.
80
+
81
+ **Roadmap:** AG-UI / OpenTelemetry event emission · storage adapters (S3/GCS/repo) · registry-backed discovery for `mcp add`.
82
+
83
+ ---
84
+
85
+ ## Quickstart
86
+
87
+ **1. Install** — `npm i -g @agentpro/scroll`
88
+
89
+ **2. Create an agent** — `scroll new` scaffolds a correct, **L1-ready** folder:
90
+ ```
91
+ agents/atlas/
92
+ ├── IDENTITY.md # who it is + security (risk tiers) — machine-readable frontmatter
93
+ ├── SOUL.md # how it thinks (you write this part)
94
+ ├── TOOLS.md # what it can use
95
+ ├── hard-rules.md # rules it must never break
96
+ ├── memory/ # what it remembers
97
+ └── evals/ # 3 gold cases — graded by `scroll eval`
98
+ ```
99
+
100
+ **3. Build, run, loop:**
101
+ ```bash
102
+ scroll check atlas # validate structure (pre-commit + CI)
103
+ scroll build atlas # → Cowork / Codex / Gemini / Claude-subagent / A2A
104
+ scroll run atlas --task "…" # inner loop: deterministic, capped, gated, checkpointed
105
+ scroll loop LOOP.md # outer loop: scheduled, self-directed, with stop conditions
106
+ ```
107
+
108
+ ---
109
+
110
+ ## Inner loop vs. outer loop (loop engineering)
111
+
112
+ The shift the field is naming **loop engineering** is from writing prompts to designing the *system that prompts the agent*. SCROLL gives you both halves explicitly:
113
+
114
+ - **`scroll run` — the inner loop.** One harnessed execution of a `WORK.md`: advance the DAG, act inside a step, verify, checkpoint.
115
+ - **`LOOP.md` + `scroll loop` — the outer loop.** Defines **when** to start an inner loop (`schedule`), **where** it finds work (`work_source`), and **when to stop** (`stop_conditions` — required). It rides your host scheduler (cron / scheduled-tasks); there's no daemon engine.
116
+
117
+ ```yaml
118
+ # LOOP.md
119
+ id: market-watch-daily
120
+ controller: lead
121
+ schedule: { cron: "0 7 * * *" }
122
+ work_source: { type: work_file, query: WORK.md }
123
+ stop_conditions:{ max_runs_per_day: 4, budget_usd_per_day: 5, halt_on: [gate_denied, verify_fail] }
124
+ digest: required
125
+ ```
126
+
127
+ The outer loop **never escalates privilege** — every action inside still passes the permission matrix below — and writes a digest after every run.
128
+
129
+ ---
130
+
131
+ ## Safety: risk tiers + grounding, enforced in code
132
+
133
+ A model is sycophantic and prompt-injectable, so it can't be trusted to stop before a dangerous action. SCROLL puts the gate in **deterministic code, in front of the action**.
134
+
135
+ **Five tiers, lowest → highest consequence**, each mapped to a policy:
136
+
137
+ | tier | default policy |
138
+ |---|---|
139
+ | `read_only` | auto |
140
+ | `reversible_write` | auto + log |
141
+ | `external_comm` | soft-hold |
142
+ | `financial` | must-approve **+ grounding** |
143
+ | `destructive` | must-approve **+ grounding** |
144
+
145
+ Risk is **data, not prose** — declared per-tool in `.mcp.json` or per-namespace in `IDENTITY.security` (a label a model can read is just another prompt it can be talked out of):
146
+
147
+ ```yaml
148
+ # IDENTITY.md
149
+ security:
150
+ risk_defaults: { fs.read: read_only, shell.exec: destructive, mcp.*: external_comm }
151
+ approval: { financial: must-approve, destructive: must-approve }
152
+ ```
153
+
154
+ `must-approve` blocks until an approval file appears under `control/approvals/`. With a team configured, that file must say who approved (`scroll people approve <gate> --run <dir> --by <slug>`), and the runner checks that person's card before the gate opens — see [People](#people-in-the-agent-team). **Grounding** runs first for `financial`/`destructive`: every declared parameter (a product code, an amount, a customer id) must trace to a real source seen earlier in the run — otherwise the action is **denied and never runs, even if "approved."** An invented invoice can't be issued.
155
+
156
+ ---
157
+
158
+ ## Multi-agent, the safe way
159
+
160
+ Agents coordinate through **files**, not a message bus:
161
+
162
+ - **`WORK.md`** — the task chain as a declarative DAG. One *controller* owns it (this prevents the #1 multi-agent failure: infinite handoff loops). A deterministic runner advances it; the LLM only acts *inside* a step.
163
+ - **`blackboard/`** — a shared space where agents post discoveries (one append-only file each).
164
+ - **Worktree-lite isolation** — parallel tasks write to isolated dirs, so two agents never collide.
165
+
166
+ Default is **single-agent**. Multi-agent is opt-in and only when a task is genuinely parallel — it costs ~15× the tokens, so SCROLL estimates cost (language-aware) *before* it spawns.
167
+
168
+ ---
169
+
170
+ ## People in the agent team
171
+
172
+ Agents are folders; people are **cards** — one per person, written by that person, kept **outside** `agents/` (and out of git by default):
173
+
174
+ ```yaml
175
+ # people/ana-ruiz.md
176
+ ---
177
+ slug: ana-ruiz
178
+ name: Ana Ruiz
179
+ address: { call_them: "Ana", self: "I" } # every agent addresses her this way
180
+ roles: [owner]
181
+ authority: { approve: [send, pay, delete, publish], max_amount: 5000 } # checked by code at the gate
182
+ channels: [email, chat] # names only; addresses live in a vault/connector
183
+ ---
184
+ Runs the shop. Reports as three bullets before 9am. Never quote a price she has not confirmed.
185
+ ```
186
+
187
+ ```yaml
188
+ # scroll.config.yaml — the deployment maps roles to people
189
+ people:
190
+ roles: { owner: [ana-ruiz], staff: [ben-ode] }
191
+ authority_ceiling: { staff: { approve: [send], max_amount: 100 } }
192
+ ```
193
+
194
+ ```yaml
195
+ # agents/clerk/IDENTITY.md — the agent names a role, never a person
196
+ serves: [owner]
197
+ reports_to: role:owner
198
+ ```
199
+
200
+ - Every agent serving `owner` loads Ana's card (fixed order, frozen for the run, in the cached prefix). Change her address once; every agent follows.
201
+ - A `WORK.md` step can be hers: `owner: person:ana-ruiz`. The run asks (request file + a `notify` event naming her channels), stops at that step, and continues after `scroll people done <task> --run <dir> --by ana-ruiz` and `scroll run --resume`.
202
+ - Agents never edit a card: `scroll people propose` queues a change; the person (or an admin role) accepts it.
203
+ - `scroll check people` validates the cards; `scroll audit` fails if a card or a `USER.md` ships inside an agent, a skill or a plugin.
204
+
205
+ Spec: [§38–41](./SPEC.md).
206
+
207
+ ---
208
+
209
+ ## Skills you already have
210
+
211
+ ```yaml
212
+ # scroll.config.yaml — read-only folders; nothing else on the machine is read
213
+ skills:
214
+ external_dirs:
215
+ - { path: ~/.agents/skills, trust: trusted }
216
+ - { path: ~/.claude/plugins, layout: claude-code-plugins, trust: trusted }
217
+ - ~/shared/team-skills # trust defaults to community: stricter scan
218
+ ```
219
+
220
+ ```bash
221
+ scroll skill sources --detect # which skill folders of other tools exist here
222
+ scroll skill list --agent atlas # what atlas can use; --all shows hidden / blocked / invalid and why
223
+ scroll skill index --agent atlas # the <available_skills> block for its cached prefix
224
+ scroll skill scan --agent atlas # skills-compat.json: ok · partial · hidden, with your overrides kept
225
+ scroll skill eval report-writer --provider codex,claude --judge
226
+ ```
227
+
228
+ An agent that declares `skills.read` gets the index plus `skill_list` / `skill_view`; a `WORK.md` step can name `skills: [...]` to load them in full (and does not run if one is refused). Precedence: `agents/<name>/skills/` → `skills/` → `external_dirs` in order. Spec: [§34–36](./SPEC.md).
229
+
230
+ ---
231
+
232
+ ## Watch, control, and read back
233
+
234
+ ```
235
+ runs/<id>/events.jsonl # run_started · permission_decision · grounding_checked · cost_update · completed …
236
+ runs/<id>/digest.md # human-readable summary — what it did, which dangerous tiers it touched, cost
237
+ ```
238
+
239
+ - **Stream** the events (tail locally, or SSE/WebSocket in the cloud; types map to **AG-UI**).
240
+ - **Control** a live run by writing files: `control/pause`, `control/stop`, `control/steer.md`, or approve a gate under `control/approvals/`.
241
+ - **Read the digest** — so the owner understands the run instead of just trusting it (an antidote to passive over-delegation).
242
+
243
+ ---
244
+
245
+ ## Compliance is structural, not trust-based
246
+
247
+ SCROLL doesn't rely on you reading the docs — the correct path is the only one that works: a **scaffold** that's correct by default, a JSON **schema**, a **linter** (`scroll check`) in CI, a build that **refuses** invalid agents, an [`AGENTS.md`](./AGENTS.md) that teaches AI coding tools the rules, and **`scroll audit`** — a hash-bound report so a "pass" is tied to the exact file state and can't be faked.
248
+
249
+ ---
250
+
251
+ ## CLI reference
252
+
253
+ | Command | Does | Status |
254
+ |---|---|---|
255
+ | `scroll new <name>` | Scaffold an L1-ready agent folder | ✅ built |
256
+ | `scroll check <name>` | Validate structure (linter; pre-commit + CI) | ✅ built |
257
+ | `scroll build <name>` | Render one source → every runtime | ✅ built |
258
+ | `scroll run --work <f>` | **Inner loop** over a `WORK.md` (or `run <agent> --task`) | ✅ built |
259
+ | `scroll loop <LOOP.md>` | **Outer loop** — schedule + find work + stop conditions | ✅ built |
260
+ | `scroll eval <name>` | Gold cases N× → machine checks + consistency + judge | ✅ built |
261
+ | `scroll audit [name]` | Conventions + hash-bound report (CI; `--verify`) | ✅ built |
262
+ | `scroll registry` | Scan agents → a config/observability view | ✅ built |
263
+ | `scroll cost <task> [--language vi]` | Single vs multi token estimate (language-aware) | ✅ built |
264
+ | `scroll mcp add <name>` | Wire an MCP server / connector into `.mcp.json` (`${vault:KEY}` creds · per-tool risk) | ✅ built |
265
+ | `scroll skill add <ref>` | Install / scaffold a `SKILL.md` skill (`--agent` to attach); a skill the scan blocks is refused | ✅ built |
266
+ | `scroll skill list · view · index · scan · check · eval · sources` | Load skills from every source, see why one is hidden or blocked, write the compat sidecar, evaluate with vs without (§34–36) | ✅ built |
267
+ | `scroll plugin add <ref>` | Unpack an agent-pack bundle (agents + skills + merged `.mcp.json`) | ✅ built |
268
+ | `scroll memory <cmd>` | Subject memory: `new · link · show · snapshot · search · forget · review · member · consolidate · fsck · erase` | ✅ built |
269
+ | `scroll people <cmd>` | Person cards: `check · new · list · show · propose · review · approve · done · forget` (`scroll check people` = `scroll people check`) | ✅ built |
270
+
271
+ Useful `run` flags: `--for <slug>` (the person this step serves) · `--people <dir>` (where the cards are) · `--action <class> --amount <n>` (what an approver must cover), `--skill a,b` (load these skills in full for the task), `--subject <sid|alias> --memory-store <dir>` (load that subject's memory contract), `--resume` (crash-resume), `--worktree` (git-worktree isolation), `--risk <tier>`, `--auto-approve`, `--language <code>`, `--max-usd` / `--max-iterations`.
272
+
273
+ ---
274
+
275
+ ## Packaging
276
+
277
+ - **`@agentpro/scroll`** — the CLI + loader (npm).
278
+ - **`@agentpro/scroll-schema`** — the versioned spec + JSON Schema.
279
+ - **Storage adapters** — `@agentpro/scroll-s3`, `-gcs`, `-repo` (roadmap).
280
+
281
+ Your *agents* are never packaged — they're folders you own and version, like `AGENTS.md`.
282
+
283
+ ## Learn more
284
+ - [`SPEC.md`](./SPEC.md) — the formal agent-folder + frontmatter spec (incl. §13 prompt caching, §21 permissions, §22 grounding, §23 LOOP, §31–§33 memory, §38–41 people)
285
+ - [`docs/prompt-caching.md`](./docs/prompt-caching.md) — practical prompt caching guide across Anthropic, OpenAI, Codex App-Server, Gemini, and Grok
286
+ - [`AGENTS.md`](./AGENTS.md) — how AI coding tools follow SCROLL
287
+ - [`templates/`](./templates/) — a worked agent + a `WORK.md` + a `LOOP.md`
288
+
289
+ ## License
290
+ [MIT](./LICENSE) © 2026 Agent Pro. Use it, fork it, ship it — just keep the copyright notice.
291
+
292
+ ---
293
+
294
+ *SCROLL — a harness for agentic loops. Turn every AI subscription your team pays for into coordinated, governed, portable agents. Built by Agent Pro.*