# trustee

**Repository Path**: TrusteeAI/trustee

## Basic Information

- **Project Name**: trustee
- **Description**: 基于Rust实现的Ai agent
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Trustee

A pure Rust reimplementation of [Hermes Agent](https://github.com/NousResearch/hermes-agent) — an autonomous AI agent that runs in your terminal. Future phases target the full Harness specification.

Unchecked `[ ]` items below are planned, not yet implemented.

## Why Trustee?

Trustee is a ground-up Rust port of Hermes Agent, targeting:

- **Fast startup** — native binary, no Python startup overhead
- **Low memory** — single binary, no interpreter, no venv
- **Hermes parity** — same tool set, same UX, same workflows

## Quick Start

```bash
# Set your API key
export TRUSTEE_API_KEY="sk-..."

# Build and run interactive mode
cargo run -- -i

# Single prompt
cargo run -- -p "Explain Rust ownership"
```

## Current Status

### Phase 1 ✅ — Interactive CLI (Hermes parity)
- [x] Streaming token display with boxed output
- [x] Reasoning/thinking box (DeepSeek reasoning_content + XML tags)
- [x] Think scrubber (stateful `<think>` tag filtering across delta boundaries)
- [x] Token usage tracking
- [x] Slash commands: `/help` `/model` `/status` `/usage` `/tools` `/skills` `/memory` `/clear` `/new` `/retry` `/undo` `/title`
- [x] CJK-safe text handling

### Phase 2 ✅ — Core Tools (Hermes parity)
- [x] `delegate_task` — spawn subagents (single + batch mode)
- [x] `cronjob` — scheduled job management
- [x] `process` — background process registry
- [x] `skill_manage` — skill CRUD (create/patch/edit/delete/write_file/remove_file)
- [x] `clarify` — interactive user prompts
- [x] Existing tools: `terminal` `read_file` `write_file` `search_files` `patch` `web_search` `web_extract` `memory` `session_search` `skill_view`

### Planned

#### Phase 2.5 — Phase 2 Gap Closure (⚠️ items from Hermes parity check)
- [ ] `delegate_task`: config-driven max_concurrent_children, goal validation per task
- [ ] `cronjob`: JSON output format, job name fuzzy lookup, full param execution (deliver/skills/model/provider)
- [ ] `process`: real stdin control (write/submit/close), log offset/limit pagination
- [ ] `skill_manage`: `absorbed_into` support, write approval gate, skills cache invalidation

### Phase 3 — System Features
- [ ] Context compression (token-aware summarization)
- [ ] Memory batch operations (atomic add/replace/remove)
- [ ] Dangerous command approval (approvals.mode)
- [ ] Session persistence and management (`/sessions`)
- [ ] FTS5 session search (tantivy integration)
- [ ] Config CLI (`trustee config set/get/edit`)
- [ ] Profile system

#### Phase 4 — Gateway & Platforms
- [ ] Gateway service (background daemon)
- [ ] Telegram bot adapter
- [ ] Discord bot adapter
- [ ] Platform-agnostic message routing

#### Phase 5 — Advanced Features
- [ ] execute_code (sandboxed Python)
- [ ] browser_* (CDP browser automation)
- [ ] text_to_speech
- [ ] vision_analyze (image analysis)
- [ ] MCP server support
- [ ] Plugin system
- [ ] Desktop/TUI mode (ratatui)

## Architecture

```
src/
├── main.rs              # Entry point
├── cli/                 # CLI argument parsing (clap)
├── config/              # Configuration management (YAML/TOML)
├── core/
│   ├── mod.rs           # Agent loop, streaming, slash commands
│   ├── banner.rs        # ASCII logo + response box
│   ├── markdown.rs      # Terminal markdown renderer
│   ├── screen.rs        # TUI widget system (Buffer/Layout/Widget)
│   ├── think_scrubber.rs # Streaming XML tag filter
│   ├── cron.rs          # Job scheduler
│   └── delegation.rs    # Subagent spawning
├── transport/           # LLM API client (OpenAI-compatible SSE)
├── tools/               # Tool trait + built-in tools
│   ├── terminal.rs      #   Shell commands
│   ├── file_tools.rs    #   File read/write/search/patch
│   ├── web_search.rs    #   Web search (DDGS)
│   ├── web_extract.rs   #   Web content extraction
│   ├── memory_tool.rs   #   Persistent memory CRUD
│   ├── session_search.rs #   Session search
│   ├── skill_tools.rs   #   Skill viewing
│   ├── delegate_task.rs #   Subagent delegation
│   ├── cronjob_tool.rs  #   Cron job management
│   ├── process_tool.rs  #   Background process registry
│   ├── skill_manage.rs  #   Skill CRUD
│   └── clarify.rs       #   User prompts
├── skills/              # Skill loading (SKILL.md + YAML frontmatter)
└── memory/              # SQLite-backed persistent memory
```

## Configuration

Create `~/.trustee/config.yaml`:

```yaml
llm:
  api_base: "https://api.deepseek.com/v1"
  model: "deepseek-chat"
  provider: "deepseek"
  max_tokens: 16384
  temperature: 0.7

tools:
  allow_dangerous: true
  terminal_max_output: 51200
  terminal_timeout_secs: 180

agent:
  max_turns: 100
  compress_context: true

web:
  search_backend: "ddgs"
```

## Requirements Analysis & Implementation Plan

The following maps the Harness specification to concrete implementation steps.

### Dedicated Non-Privileged User
- Agent runs as `trustee:trustee` with no sudo privileges
- `workspace.path` defines the working directory; `workspace.allow_outside = false` blocks external I/O
- Installation script creates the user via `useradd -r`

### Privilege Escalation Gate
Operations requiring elevation SHALL NOT be executed by the agent process:

1. Backend detects privileged operation, classifies risk level
2. Risk warning displayed to user
3. User approves or denies
4. Approved operations dispatched to a **separate** sudo-capable process

**Risk levels:** Safe (direct) / Warn (log) / Gate (approval + sudo) / Block (reject)

### Harness Protocol & Frontend/Backend Separation
Frontend (CLI/TUI/API/Gateway) and backend (engine/tools/transport/scheduler) communicate through a structured protocol:

| Direction | Message | Purpose |
|-----------|---------|---------|
| Client → Server | `ChatRequest` | Submit conversation |
| Server → Client | `StreamDelta` | Token streaming |
| Server → Client | `ApprovalRequest` | Privilege escalation prompt |
| Client → Server | `ApprovalResponse` | User decision |
| Server → Client | `ChatResponse` | Final response + usage |

- `src/protocol/` — message definitions (JSON/SSE)
- Refactor `src/core/` → `src/backend/` (engine) + `src/frontend/cli/` (CLI)
- Phase 4: `src/frontend/api/`, `src/frontend/gateway/`

### Complete Harness Framework
- Backend as **library crate** (`trustee-engine`), CLI as **binary crate** (`trustee`)
- State under `~/.trustee/`, gateway as **systemd service**, profile system

## License

MIT — same as Hermes Agent. See [LICENSE](LICENSE).

Trustee is a ground-up Rust reimplementation inspired by Hermes Agent's architecture and UX. It is not a fork and does not contain any Hermes Agent source code.