@letterblack/lbe-exec 1.2.9 → 1.2.11

package/README.md

@@ -1,133 +1,19 @@
 # @letterblack/lbe-exec
 
-**Local-first execution governance for AI agents.**
+LBE puts a local policy gate between what an AI agent proposes and what the system actually executes. Every action — file write, shell command, anything — is validated locally before it runs. No cloud service. No daemon.
 
-> Use `@letterblack/lbe-exec` if you want LBE to control agent actions in a workspace.
-> Use `@letterblack/lbe-sdk` if you only need validation decisions inside your own tool.
+`lbe-exec` is the full in-process controller. It handles signing, execution, and auditing for you — your agent code just calls `lbe.writeFile()` or `lbe.runShell()`.
 
-Every action any agent proposes — file write, shell command, anything — passes
-through a local validation gate before it can execute. One package, any agent,
-zero cloud dependency, no daemon required.
+> **Used in production:** LBE is the safety engine inside [Letterblack for After Effects](https://letterblack.net) — every AI-generated script and automation command passes through it before touching a live project.
 
 ---
 
-## The problem
+## Which package do you need?
 
-AI agents are capable. They can write files, invoke tools, and change state —
-and they will, the moment they are given a reason to. The host is the only
-thing standing between a plausible-looking request and irreversible damage.
-
-That is not enough.
-
-`@letterblack/lbe-exec` puts a deterministic local gate between what the agent
-proposes and what the system actually executes — fully in-process, no cloud
-dependency, no daemon required.
-
----
-
-## How every request travels
-
-![LBE gate sequence — Request flows through Policy, Identity, and Scope gates before reaching Action. A rejected request is routed to denial before it reaches execution.](https://unpkg.com/@letterblack/lbe-exec/assets/lbe-gates.jpg)
-
-Every request the agent produces enters a 7-gate pipeline. A failure at any
-gate returns a structured denial — the remaining gates are not evaluated.
-
-```
-[1] Schema         required fields and structural validity
-        ↓
-[2] Timestamp      permitted clock-skew window (±10 minutes)
-        ↓
-[3] Key lifecycle  trusted key, active, not expired
-        ↓
-[4] Signature      Ed25519 request authenticity (signed locally, no network)
-        ↓
-[5] Rate limit     per-requester sliding-window limit
-        ↓
-[6] Nonce          single-use replay protection
-        ↓
-[7] Policy         configured authorization (deny-wins)
-        ↓
-  allow / deny / error — structured result returned to host
-```
-
-The executor signs every request with a host-held key before validation.
-No key material leaves the process.
-
----
-
-## When a request is approved
-
-![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](https://unpkg.com/@letterblack/lbe-exec/assets/story-allow.jpg)
-
-When a request clears every gate:
-
-1. The agent calls a convenience method — `lbe.writeFile()`, `lbe.runShell()`, etc.
-2. The executor constructs and signs the request locally with a host-held Ed25519 key.
-3. All seven gates pass. The project policy approves the action.
-4. The write or command executes inside the configured project root.
-5. The audit chain is extended — every approved action appends a hash-linked
-   entry to `.lbe/audit.jsonl`, permanently verifiable, impossible to silently remove.
-6. A structured result returns: whether it succeeded, which rules matched, and
-   the audit entry identifier.
-
-The application stays in control. The executor decides whether the action was
-permitted and hands the answer back.
-
----
-
-## When a request is blocked
-
-![Deny path — rogue agent bypass attempt, policy gate immediate rejection, shell untouched, filesystem unchanged, immutable audit entry written, final state clean.](https://unpkg.com/@letterblack/lbe-exec/assets/story-deny.jpg)
-
-When a request fails any gate:
-
-1. The agent attempts an action — whether by mistake, misconfiguration,
-   or a deliberate bypass attempt.
-2. The policy gate closes immediately. The request is denied before any adapter
-   is reached.
-3. The shell is untouched. The filesystem is unchanged. Nothing that should not
-   have happened, happened.
-4. The denial is written to the immutable audit log — chain sealed, evidence
-   preserved.
-5. The final state is clean, verifiable, and consistent.
-
-No partial execution. No silent failures. Denial is a first-class outcome, not
-an error.
-
----
-
-## Policy — who writes the rules
-
-Only the host application writes policy. Agents may propose a rule — the
-proposal is returned as a plain object for the host to review. Until the host
-explicitly accepts and writes it, the proposal has no effect on any gate.
-
-This separation is intentional. An agent that can write its own policy rules
-is an agent that can grant itself permission.
-
----
-
-## What this covers
-
-| Threat | Gate |
+| I want… | Package |
 |---|---|
-| Agent writes outside the project root | Scope — sandbox path check |
-| Replayed or stale request | Identity — nonce and timestamp |
-| Tampered or expired key | Identity — key lifecycle |
-| Excessive requests | Identity — rate limit |
-| Action not permitted by project policy | Policy — deny-wins evaluation |
-| Unauthorized shell command | Scope — explicit command allowlist |
-| Injected payload (eval, exec, __proto__) | Content scan before pipeline |
-
----
-
-## Observer mode — start here
-
-Not ready to block? Start in observer mode. Every request is fully validated
-and logged exactly as it would be in enforcement — but nothing is blocked.
-
-Watch what the agent is doing before you decide what to deny. Your rules take
-effect the moment you switch to enforcement.
+| LBE to handle file writes and shell commands for me (full controller) | `@letterblack/lbe-exec` ← you are here |
+| Just the allow/deny decision — I'll execute it myself | `@letterblack/lbe-sdk` |
 
 ---
 
@@ -138,39 +24,36 @@ npm install @letterblack/lbe-exec
 npx lbe-exec init
 ```
 
-`npx lbe-exec init` scans the project, writes `lbe.policy.json` in observer
-mode, generates `CLAUDE.md` and `.github/copilot-instructions.md` so every AI
-agent automatically discovers and follows governance, and creates
-`.lbe/AGENT_CONTRACT.md` as a machine-readable contract.
+`npx lbe-exec init` creates `lbe.policy.json` in observer mode, generates `CLAUDE.md` and `.github/copilot-instructions.md` so AI agents automatically discover and follow governance, and writes `.lbe/AGENT_CONTRACT.md` as a machine-readable contract.
 
 Requires Node.js ≥ 20.9.0.
 
 ---
 
-## Use in agent code
+## Quick start
 
 ```js
 import { createLocalExecutor } from '@letterblack/lbe-exec';
 
 const lbe = createLocalExecutor({ rootDir: process.cwd() });
 
-// Every call routes through the full 7-gate pipeline
+// Every call routes through the full 7-gate pipeline automatically
 await lbe.writeFile('output/report.md', content);
 await lbe.readFile('src/config.json');
 await lbe.patchFile('src/index.js', patch);
 await lbe.deleteFile('tmp/scratch.txt');
 await lbe.runShell('node', ['scripts/build.js']);
 
-// Result shape
-const result = await lbe.writeFile('output/result.md', data);
+// Result shape — same for every method
 // { ok: true,  decision: 'allow', executed: true,  auditId: '...' }
 // { ok: false, decision: 'deny',  executed: false, error: { code, message } }
 ```
 
-No knowledge of the pipeline, request format, or policy internals required.
-All signing, validation, and auditing happens automatically.
+No knowledge of the pipeline, request format, or policy internals required. All signing, validation, and auditing happens automatically.
+
+---
 
-### Options
+## Options
 
 ```js
 const lbe = createLocalExecutor({
@@ -184,7 +67,11 @@ const lbe = createLocalExecutor({
 });
 ```
 
-### Policy management
+---
+
+## Policy management
+
+Only the host application writes policy. Agents may propose a rule — the proposal is returned as a plain object for the host to review. Until the host explicitly accepts and writes it, the proposal has no effect.
 
 ```js
 // Propose a rule — returns an object for the host to review, writes nothing
@@ -207,16 +94,20 @@ lbe.audit.verify();
 
 ---
 
-## CLI reference
+## Observer mode — start here
+
+Not ready to block? Start in observer mode. Every request is fully validated and logged exactly as it would be in enforcement — but nothing is blocked. Watch what the agent is doing before you decide what to deny.
 
 ```bash
 npx lbe-exec init      # create lbe.policy.json in observer mode
-npx lbe-exec status    # show mode, rule count, and audit entry count
 npx lbe-exec enforce   # switch to blocking
 npx lbe-exec observe   # switch back to advisory
-npx lbe-exec policy    # list active rules
 ```
 
+---
+
+## CLI reference
+
 | Command | Purpose |
 |---|---|
 | `npx lbe-exec init` | Bootstrap governance — policy, keys, agent files |
@@ -228,6 +119,74 @@ npx lbe-exec policy    # list active rules
 
 ---
 
+## How the gate pipeline works
+
+![LBE gate sequence — Request flows through Policy, Identity, and Scope gates before reaching Action. A rejected request is routed to denial before it reaches execution.](https://unpkg.com/@letterblack/lbe-exec/assets/lbe-gates.jpg)
+
+Every request enters a 7-gate pipeline. A failure at any gate returns a structured denial — the remaining gates are not evaluated.
+
+```
+[1] Schema         required fields and structural validity
+        ↓
+[2] Timestamp      permitted clock-skew window (±10 minutes)
+        ↓
+[3] Key lifecycle  trusted key, active, not expired
+        ↓
+[4] Signature      Ed25519 request authenticity (signed locally, no network)
+        ↓
+[5] Rate limit     per-requester sliding-window limit
+        ↓
+[6] Nonce          single-use replay protection
+        ↓
+[7] Policy         configured authorization (deny-wins)
+        ↓
+  allow / deny / error — structured result returned to host
+```
+
+The executor signs every request with a host-held key before validation. No key material leaves the process.
+
+---
+
+## When a request is approved
+
+![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](https://unpkg.com/@letterblack/lbe-exec/assets/story-allow.jpg)
+
+1. The agent calls a convenience method — `lbe.writeFile()`, `lbe.runShell()`, etc.
+2. The executor constructs and signs the request locally with a host-held Ed25519 key.
+3. All seven gates pass. The project policy approves the action.
+4. The write or command executes inside the configured project root.
+5. The audit chain is extended — every approved action appends a hash-linked entry to `.lbe/audit.jsonl`, permanently verifiable, impossible to silently remove.
+6. A structured result returns: whether it succeeded, which rules matched, and the audit entry identifier.
+
+---
+
+## When a request is blocked
+
+![Deny path — rogue agent bypass attempt, policy gate immediate rejection, shell untouched, filesystem unchanged, immutable audit entry written, final state clean.](https://unpkg.com/@letterblack/lbe-exec/assets/story-deny.jpg)
+
+1. The agent attempts an action — whether by mistake, misconfiguration, or a deliberate bypass attempt.
+2. The policy gate closes immediately. The request is denied before any adapter is reached.
+3. The shell is untouched. The filesystem is unchanged.
+4. The denial is written to the immutable audit log — chain sealed, evidence preserved.
+
+No partial execution. No silent failures. Denial is a first-class outcome, not an error.
+
+---
+
+## What this covers
+
+| Threat | Gate |
+|---|---|
+| Agent writes outside the project root | Scope — sandbox path check |
+| Replayed or stale request | Identity — nonce and timestamp |
+| Tampered or expired key | Identity — key lifecycle |
+| Excessive requests | Identity — rate limit |
+| Action not permitted by project policy | Policy — deny-wins evaluation |
+| Unauthorized shell command | Scope — explicit command allowlist |
+| Injected payload (eval, exec, __proto__) | Content scan before pipeline |
+
+---
+
 ## What ships
 
 ```
@@ -251,8 +210,6 @@ Source code, tests, keys, and runtime state are not included.
 
 ## Limits
 
-This package governs actions routed through its executor. It does not provide
-kernel-level process isolation, network-egress control, multi-tenant separation,
-or a hosted control plane.
+This package governs actions routed through its executor. It does not provide kernel-level process isolation, network-egress control, multi-tenant separation, or a hosted control plane.
 
 For the raw WASM runtime without a controller, see `@letterblack/lbe-sdk`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letterblack/lbe-exec",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "description": "Local host-signed execution layer for LetterBlack LBE.",
   "type": "module",
   "main": "dist/index.js",