# Yerin — the Void 2.0 Security Agent

> Cradle note: Yerin is the sword artist — fast, vigilant, the one who *notices the
> threat first and calls it*. In Void 1.x she already owns the 5-minute alert
> cron. In Void 2.0 she becomes a first-class **read-only security/observability
> agent**: she watches, reports, and proposes — she never silently acts.

## Design principles

1. **Read-only by capability.** Yerin's agent record gets `{ read: true }` and
   **no** `write`/`suggest`. Anything she wants changed she raises to you; she
   cannot mutate state. (If you later want her to be able to *propose* a
   remediation, add `suggest: true` and the existing pending-change flow gives
   you an approval gate for free.)
2. **Own toolset, own registry.** Security tools live in
   `lib/ai/agent/tools/security/` behind `securityRegistry` — separate from
   Dross's `companionRegistry`, so she gets investigative tools, not
   `propose_change`.
3. **No secret material, ever.** Tools project explicit columns and rely on the
   audit layer's write-time redaction. `agent_inventory` deliberately never does
   `SELECT *`.

## Built (TDD, on `main`, not deployed) — 5 tools

`lib/ai/agent/tools/security/` + `securityRegistry`, tests in
`tests/ai/security_tools.test.js`:

| Tool | What it answers |
|------|-----------------|
| `audit_log` | "Who did what, newest first?" Filter by `actor_kind` / `actor_id`. Reads the redacted audit trail. Capped at 200. |
| `agent_inventory` | "Which agents exist and what is each allowed to do?" id/slug/name/kind/model + capabilities + scopes. No token material. |
| `pending_review` | The queue of agent-proposed (suggest-tier) changes awaiting approval — where injected/misbehaving intent surfaces. |
| `resource_exposure` | Attack-surface inventory: every resource's host/url/status across spaces. No `monitoring`/`metadata` blobs, no credentials. |
| `token_audit` | Agent tokens with label/last_used/revoked_at (never the hash) — spot stale/unused credentials. |

## Roadmap — tools to add next (designed, not yet built)

- **`recent_captures`** — newly ingested refs/source_docs (untrusted external
  content entering the system), so Yerin can flag suspicious inbound material.

Stretch (needs new plumbing, your call):
- **`tls_expiry` / `service_health`** — port Void 1.x's `lib/security.js` cert
  checks + the Yerin alert cron into a tool she can call on demand.
- **Active probes** (e.g. "is this CT's admin port exposed?") would require
  network egress — must go through `safeFetch` and be owner-gated. Defer.

## Wiring Yerin up

1. ✅ **Seed the agent.** Migration `011_yerin.sql` inserts a `yerin` agent —
   `capabilities {"read":true,"suggest":false,"write":false}`, `kind:'claude'`,
   `model:NULL` (server default; flip to a local Ollama model anytime by setting
   `agents.model`). Read-only by design.
2. ✅ **Expose `securityRegistry` over MCP.** `lib/mcp/companion-stdio.js` now
   selects the registry from `VOID_TOOL_REGISTRY` (`security` → Yerin's tools;
   default → companion). Test: `tests/mcp/registry_select.test.js`.
3. ⬜ **A Yerin entry point — LEFT FOR YOU** (it's a new API/UX surface; deserves
   your attention, not an unsupervised guess). Two shapes:
   - A route (`POST /api/security/ask`) reusing the `claude_cli` driver with
     Yerin's persona + an MCP config that sets `VOID_TOOL_REGISTRY=security`.
     Mirror `lib/api/routes/companion.js` (SSE, conversation persistence).
   - Or a scheduled cron: a standing "anything suspicious in the last 24h?" pass
     that files its result as a Sacred Valley card (ties into Plan 6).
   - Either way she'll need a **persona prompt** (the Cradle Yerin voice +
     security-analyst framing) — worth writing together.

## Adjacent agent roles (so the roster stays coherent)

- **Dross** — companion/chat (Lindon's own spirit-AI; the right-rail assistant).
  Read + suggest. Already live.
- **Yerin** — security/vigilance (this doc). Read-only.
- **Orthos** — see the role proposal below.

### Proposed role: Orthos — the local-model Advisor / Council

Orthos in Cradle is the ancient dragon-turtle: a **powerful ally with long
experience and a deep spiritual (Path of Black Flame) connection** — exactly your
framing. That maps cleanly onto a specific, useful Void 2.0 role:

**Orthos = the reflective Advisor, running on the local Ollama model (free,
always-on), not Claude.** He plays to a local model's strengths (summarisation &
synthesis, not precise tool-use):

- **The long view / "council briefing."** A scheduled pass that fuses recent
  captures, open tasks, and audit highlights into a short reflective digest —
  the Void 1.x "Orthos council briefing" reborn as a Sacred Valley widget.
- **"Spiritual connection" = the knowledge graph.** Let Orthos traverse the
  embedding/RRF links to surface *non-obvious connections* across Spaces
  ("these three captures in two different Spaces are converging on X"). That's
  the literal mechanisation of his deep-sight: semantic connection-finding over
  the vector store.
- **Why local:** it's high-frequency, low-stakes, cost-sensitive reflection —
  perfect for `llama3.1:8b` on `192.168.1.185`, keeping Claude budget for Dross.
  Capability: `{ read: true }`, `kind: 'ollama'`, `model: 'llama3.1:8b'`.

So the trio reads naturally: **Dross** converses, **Yerin** guards, **Orthos**
reflects — and two of the three (Yerin alerts, Orthos council) become Plan 6
Sacred Valley widgets. See `docs/plan-6-brainstorm-brief.md`.