0xKT 44309dde3a feat(cli): raven agents new scaffolds a complete agent end to end
## Summary

raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.

Key decisions:

- **Templates are real code, fire-tested before templating.** The eleven
  files under raven/templates/agents_scaffold/ pass ruff and py_compile
  like any source, ride the wheel, and their content was proven live
  before landing: discovery, handshake, and plugin tool/hook injection
  all green on a hand-assembled probe in a disposable home. A dedicated
  spike also proved the placement is invisible to the import-linter
  contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
  target is the raven home's agents/ tree, discovery's first root: a
  scaffolded folder is on the roster without any registration.
  --register mirrors the generated install.py through the same pinned
  write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
  manifest, re-parses the plugin manifest, compiles every generated
  file, and really scans discovery; smoke spawns the launcher for one
  initialize frame. Three smoke outcomes are told apart: GREEN, the
  launcher's loud no-key refusal (fail-closed design, passed through
  verbatim), and FAILED with the scene preserved. Display names are
  fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
  renders schemas/subagent.schema.json (a discriminated union on kind)
  and schemas/raven-plugin.schema.json from the pydantic models; a
  contract family holds the on-disk files byte-equal to a fresh render
  and validates every real manifest on the tree against them. Editors
  get instant validation with two settings lines, documented in the
  guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
  the from-zero developer guide (gold standard: a developer who never
  read the source reaches a green handshake in ten minutes); CONTEXT.md
  renames the category entry to Discovered agent -- agent the thing,
  harness the mechanism, subagent the protocol seat -- with product
  absorbed into Avoid; the charter gains the scaffold entry and the
  engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
  project in the working directory (pip install -e territory); --here
  lands it on the plugins-dist shelf. The launcher adopts the official
  ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
  is missing; the doctor reports that row as disabled by design with
  the install cure printed. No plugins/ directory ships beside an
  engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
  hostile lenses (filesystem edges of a command that writes into real
  raven homes; template quality as the file set every future agent
  copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
  pin an enabled row that cannot start, the name fence ignored the
  discovered tree, one installed engine wheel rode the host's and every
  sibling's turns through a fixed tool name, and crash residue was
  discovered as a hidden live agent. All fourteen close in a
  dedicated hardening commit, each with a regression test built from the review's own
  reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
  Nothing under raven/contracts/ or the agent loop changed. The branch
  carries exactly two narrow runtime fixes exposed by the review:
  discovery now skips dot-directories (crash residue is never an
  agent), and the config schema gains an engine round-trip field
  (declared as a field-level neutral seam; merge and readiness
  semantics untouched).

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- Every commit landed through a full-suite rehearsal on a clean bench
  before touching the branch; tails over the original base's 19953
  passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
  smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
  expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
  every step a pure addition, +65 tests net. The branch diff is
  fingerprint-stable across the rebase (git patch-id --stable verified
  pairwise across two clean rebases); the branch closes at 20094 passed
  / 137 skipped / exit 0 on the current main base, +80 tests net over
  whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
  end: one command scaffolds into ~/.raven/agents, the four-segment
  card runs all green, and a genuine LLM turn has the agent's own model
  call its own scaffolded hello tool through the permission gate and
  relay the exact output; the probe was then removed without touching
  the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
  four doctor lines, readiness ready, and a live ACP initialize
  handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
  passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
  tampered file each turn the family red); all six subagent manifests
  and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
  make check-large-files, make check-source-language: green at every
  step; wheel build carries all seventeen template files and none of
  schemas/.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.

## Related Issues

N/A
2026-09-10 07:07:15 +00:00
2026-07-01 21:58:09 +08:00


Raven

Raven is The Self-Improving Agent Harness, built on EverOS, with opt-in Deep Research for multi-source investigation.

Raven helps agents improve across runs by continuously refining the systems around them: tools, skills, memory, code execution, policies, and working environment. EverOS provides durable user memory, agent memory, and world knowledge across sessions, so successful workflows can evolve into reusable Agent Templates and digital workers.

Update: Raven added Deep Research. Enable it with raven deep-research enable to give the agent access to MiroThinker-backed, multi-source research when a task needs deeper investigation.

Raven is pre-alpha. Interfaces and configuration may change quickly.

Benchmarks

Benchmark Raven Result Comparison
Efficiency 56.7% at 27B; 58.1% at 397B Hermes 46.8% / 47.9%; +9.9pp at 27B
Self-evolution Ranked #1 on EvoAgentBench +6.2pp over the next result across four methods
Proactivity 0.60 F1 on ProAgentBench 2.4x Hermes/OpenClaw at 0.253

Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes.

https://github.com/user-attachments/assets/3c541dae-5852-447f-8ea6-c9877612ad57

Quick Start

Install

Linux, macOS, or WSL2:

curl -fsSL https://raven.evermind.ai/install.sh | bash

Native Windows PowerShell:

irm https://raven.evermind.ai/install.ps1 | iex

Windows PowerShell 5.1 may reject the redirect. Use the direct installer URL instead:

irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex

The agent products ship with raven itself: a wheel carries the agents/ product tree and copies it out to your raven home on first use, and a source checkout reads the tree in place. Setup asks about each product and registers the ones you take up, on the model it is tuned for or on this raven's LLM. See agents/README.md.

Onboard and run

raven

That is the whole first run: with nothing configured yet, raven walks you through setup and then opens the TUI in the same session. To reconfigure later, run raven onboard explicitly.

The bilingual onboarding wizard configures seven areas without requiring manual edits to ~/.raven/config.json:

  1. LLM provider and model
  2. Sandbox or execution location
  3. Chat channels
  4. EverOS long-term memory
  5. Web access (pick a search vendor and a page reader, give each its key)
  6. Sub-agents shipped in this checkout
  7. Cold-start import from other AI tools

Step 5 also mirrors every web vendor key into ~/.raven/env (owner-only) and offers to add one guarded source line to your shell rc, so new shells and the cli / acp sub-agents -- whose environment is captured from a login shell -- inherit them.

Provider setup includes an in-step connectivity check. Optional steps can be skipped and configured later. If setup is incomplete, run:

raven doctor

Upgrade

raven upgrade --check
raven upgrade

Upgrades preserve configuration, sessions, and memory. Raven does not update automatically.

Deep Research

Deep Research gives Raven a dedicated path for open-ended questions that require broad web search, source reading, analysis, and multi-source cross-checking. It uses MiroThinker and returns a self-contained answer with inline citations and references.

Configure it during onboarding or later:

raven deep-research enable
raven deep-research get

Once configured, Raven can invoke deep_research when a task needs more than a quick lookup. Before a paid, minute-scale run, interactive surfaces ask whether to use Deep Research or regular search for that query.

Delivery adapts to where Raven is running:

  • CLI and TUI: progress streams inline while Raven searches, reads pages, and runs analysis. The completed report is shown directly without being rewritten by the main model.
  • Gateway channels: the run continues in the background and the completed report is delivered back to the originating conversation.
  • Local archive: every completed result is saved under <workspace>/deep_research/ for later use.

Use regular search for a single fact or URL. Use Deep Research for comparisons, landscape reviews, technical investigations, and questions where source agreement matters.

Tracing

Tracing makes Raven's reasoning path inspectable without sending trace data to a hosted service. Open the local dashboard with:

raven tracing

Each session.turn becomes a trace tree containing the work that happened beneath it:

  • LLM calls, models, token usage, cost, latency, and errors
  • Tool inputs and outputs
  • Subagent runs and parent-child relationships
  • Skill reads and injections
  • Memory recall, storage, extraction, and consolidation
  • Large prompts and results stored as out-of-line artifacts

Tracing is enabled by default and is designed to never interrupt Raven's control flow. Spans are stored locally at ~/.raven/traces/logs/audit-spans.log; set RAVEN_TRACING_DIR to move the state directory or RAVEN_TRACING=0 to disable recording.

The schema follows a small, versioned semantic contract. See the Tracing Standard API for span names, attributes, artifact behavior, and extension rules.

Core Systems

System What it adds
EverOS memory Durable user memory, agent memory, and world knowledge across sessions
Context Engine Explicit token budgets and a unified assembly pipeline that preserves the most useful context
Proactivity Sentinel observations, scheduled work, nudge policy, and deferred decisions
SkillForge Built-in, workspace, EverOS, and mirrored skills with retrieval, feedback, and evolution
Evolver Reproducible evaluation loops for improving agents and reusable procedures
Agent Templates Shareable starting points for specialized digital workers built on the same harness

Providers and Gateways

Raven supports API-key, OAuth, local, and OpenAI-compatible providers. The onboarding catalog includes OpenRouter, OpenAI, Anthropic, Gemini, MiniMax, DeepSeek, Z.ai, DashScope, Moonshot, VolcEngine, SiliconFlow, Groq, AiHubMix, Azure OpenAI, GitHub Copilot OAuth, OpenAI Codex OAuth, Ollama, and hosted vLLM.

Twelve gateway adapters connect Raven to Telegram, Slack, Discord, WhatsApp, Matrix, Feishu, WeCom, Mochat, QQ, DingTalk, Email, and WeChat.

raven channels list
raven channels enable <adapter>
raven gateway

Command Reference

Command Purpose
raven or raven tui Launch the terminal UI
raven agent -m "..." Run a one-shot task
raven onboard Configure providers, sandboxing, channels, memory, web tool keys, sub-agents, and import
raven status Show configuration and runtime status
raven doctor Diagnose provider and environment problems
raven tracing Open the local trace dashboard
raven tracing compact Fold duplicate trace artifacts to reclaim disk space
raven sessions list Browse, resume, fork, export, or delete sessions
raven skill list Inspect the local SkillForge catalog
raven sentinel status Inspect proactive memory and scheduled nudges
raven cron list Inspect scheduled jobs
raven gateway Run messaging gateways
raven gateway reload / status / stop Drive a running gateway through its control plane (rebuild from config without a restart, inspect the generation, stop gracefully)
raven upgrade Upgrade a managed installation

Run raven --help or raven <command> --help for the complete CLI surface.

Documentation


Repo layout

The top-level packages under raven/, in one line each. This list is the canonical set of commit scopes (see AGENTS.md); a change living wholly in a top-level tree outside raven/ uses that tree as its scope instead (agents, evolver, ui, ...). Layer seats (which package may import which) are recorded under Layer Seats in CONTEXT.md, routed from CONTEXT-MAP.md; this section only says what each package does.

Package What it is
acp ACP server side: raven as an agent another host can talk to
acp_client ACP client side: raven driving a third-party local agent as a sub-agent backend
agent The agent loop, its tools, and sub-agent orchestration
auth Authentication and authorization primitives
browser Browser automation and its outbound-address policy
channels Per-service channel adapters (telegram, discord, feishu, ...) and the channel contract
cli The raven command-line surface
config Config schema, loader, migrations, and update helpers
contracts The papers: declared shapes, two promise tiers, no machinery
context_engine Context assembly for a turn
core Assembly root: the *_stack builders and the admission door
eval_engine Evaluation harness
gateway Daemon plumbing: channel manager, outlet, live probe, run lock
i18n User-facing text in the user's language
importer External data import
knowledge Knowledge base service
market Plugin market: catalog, trust, install, ledger
mcp MCP client machinery
memory_engine Long-term memory engine
home Where raven keeps everything: the one address resolver
observability What a raven span means: the attribute vocabulary and the usage it reports
ops Machine registry and on-call operations
permissions The gate at the tool dispatch door: which calls run, ask, or are refused
playbook Playbook runtime
plugins Plugin discovery, manifests, registry, and bundled plugins
proactive_engine Cron, heartbeat, sentinel: turns raven starts itself
providers LLM provider pool and resolution
routing Model routing
rpc The RPC surface (TUI and tools talk here)
sandbox Execution sandboxing
security Outbound address policy and prompt-injection fences
session Session export and titles
skill_hub Skill hub: client, install engine, policy and install audit
spine The kernel: submit, lanes, cancel, emit, delivery
templates Packaged data assets (no Python)
token_wise Token efficiency: cache optimizer, usage tracker
tracing Span capture: context, the instrument decorator, the store
trajectory Turn trajectory store and verdicts
updates The install's own lifecycle: release lookup, upgrade plan and handoff, update nudge
utils Shared helpers, including the atomic write primitive

Architecture

CLI / TUI / Messaging Gateways
              |
              v
          RPC / Spine
              |
              v
           Agent Loop
      +-------+-------+
      |       |       |
  Providers  Tools  Subagents
      |       |       |
      +--- Context Engine ---+
              |
      +-------+--------+
      |                |
 EverOS Memory     SkillForge
      |                |
      +--- Proactivity + Evolver

The Python runtime and React/Ink TUI communicate only through the typed RPC contract. The Spine carries runtime events, while the Agent Loop coordinates providers, tools, context, memory, skills, subagents, and proactive work.

Key directories:

raven/
├── spine/              # Per-turn backbone: submit -> lanes -> emit
├── contracts/          # Papers: the interfaces every shelf implements
├── core/               # Assembly root: build_runtime and the *_stack builders
├── agent/              # Agent loop, tools, hooks, subagents, context builder
├── channels/           # Telegram, Discord, Slack, Matrix, WhatsApp, WeCom, ...
├── gateway/            # Daemon plumbing: channel manager, outlet, generations, lock
├── rpc/                # Python side of the native TUI protocol
├── providers/          # LLM provider adapters
├── context_engine/     # Context assembly and Curator path
├── proactive_engine/   # Sentinel, scheduler, nudges, feedback
├── memory_engine/      # EverOS memory, local skills, SkillForge
├── playbook/           # Stored orchestrations: library, match funnel, executor
├── token_wise/         # Usage tracking and cache placement
├── tracing/            # Span capture (the dashboard lives in cli/tracing_viewer/)
├── observability/      # The span vocabulary a standalone kernel may not hold
├── home.py             # RAVEN_HOME and the config path, resolved once
├── sandbox/            # Isolated command execution
├── security/           # Trust boundaries and network checks
├── cli/                # `raven` command line entry point
└── config/             # Config schema and update helpers

ui-tui/                 # React/Ink native terminal UI
bridge/                 # WhatsApp TypeScript bridge
benchmarks/             # Benchmark adapters, including AppWorld evolver wiring
evolver/                # Benchmark-driven harness self-evolution: a tool over the library, not in the wheel
agents/                 # Product definitions served over ACP: launcher + rendered config + product plugins
plugins-dist/           # Standalone plugin distributions (everos-memory, ppt-engine) on the raven.plugins entry-point group
schemas/                # Editor-facing JSON Schemas exported from the pydantic models (scripts/export_agent_schemas.py)

EverMind Ecosystem

Raven is part of the EverMind open-source ecosystem. Explore EverOS, EverAlgo, HyperMem, EvoAgentBench, EverMemBench, and EverMe.


Contributing

Issues and pull requests are welcome. Start with the developer workflow, follow AGENTS.md for repository rules, and use GitHub Discussions for design conversations.

License

Apache License 2.0

Description
The Harness of Harnesses • built for RSI: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.
Readme Pixar 250 MiB
Languages
Python 76.8%
TypeScript 19.7%
JavaScript 1.9%
CSS 1.3%
Shell 0.1%