# hezor-agent **Repository Path**: hezor/hezor-agent ## Basic Information - **Project Name**: hezor-agent - **Description**: No description available - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-12 - **Last Updated**: 2026-08-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Hezor Agent 2.0 **Programmable Precision Control Layer for Coding Agents** Hezor is a native local control product that sits above coding agents such as TRAE, OpenCode, Claude Code and Codex. It does not replace their models, tools, skills, MCP runtime or sandbox. Hezor owns the engineering contract around them: intervention level, task boundaries, AON workflow, human interaction, evidence and replanning. ## Architecture ```text User ┌─────┴─────┐ │ │ Hezor TUI Host Attached │ │ └─────┬─────┘ │ authenticated local HTTP / SSE / MCP / Hooks hezord │ ┌───────────────────┼──────────────────────┐ │ │ │ Run/Contract AON 2.0 Host Bridge Task/Action Lease Parse/Validate MCP / Hook / CLI Evidence/Event Compile Adapter │ │ └───────────────────┬──────────────────────┘ ▼ Native Coding Agent ``` `hezor` is the native Windows/Linux CLI and full-screen TUI client. `hezord` is the per-project local control service and the single state owner. Attached hosts and Standalone host processes use the same typed Action protocol. ## Why Hezor exists LLMs are intentionally nondeterministic. Hezor does not try to remove that intelligence. It makes the **outer engineering structure** explicit and verifiable while leaving search, reasoning, tool selection and implementation autonomous inside each task. ```text Deterministic outer loop → Goal / Scope / Resource / Task / Evidence / Gate Agentic inner loop → Reasoning / Search / Tools / Skills / Subagents ``` ## Quick start with TRAE ```powershell hezor init --host trae hezor run --host trae --mode attached "implement the requested feature" ``` Hezor installs only the selected host projection. TRAE integration uses a project Command/Skill for bootstrap, MCP for typed bidirectional control, and optional TRAE Hooks for live tool/file/session observation and side-effect gates. Expose Hezor as an MCP stdio server: ```powershell hezor mcp --host trae --project . ``` The project can be opened from a nested directory: Hezor discovers the nearest existing `.hezor` project, otherwise the nearest Git worktree root. ## OpenCode and Claude Code ```powershell hezor init --host opencode hezor init --host claude-code ``` OpenCode receives a managed project plugin using its tool lifecycle hooks. `hezor init --host opencode` also creates a machine-local project bridge under `.hezor/bridge/` that pins the absolute native Hezor executable path. The plugin therefore does **not** depend on the PATH inherited by a long-running OpenCode process. Before an OpenCode Hezor Run becomes active, the plugin is pass-through and must not intercept Skill/Read/Glob/Bash/Task bootstrap tools; terminal stale active markers are self-healed. A live controlled Run fails closed if its bridge is unavailable. Claude Code receives a project Skill with scoped `PreToolUse`/`PostToolUse` hooks. Enforcement is upgraded only after Hezor observes a live verified hook and the local bridge is usable; the presence of a file alone is never treated as proof of E3. OpenCode hook performance is deliberately tiered: **Read/Glob/Grep/Search/Skill stay native and never enter the synchronous Hezor gate**. Potential side-effect tools such as Bash/Write/Edit/`apply_patch` enter the pre-tool gate with a 2s native latency budget. Post-tool/session telemetry is compact, bounded and best-effort; complete file bodies and tool results are not copied into the control plane. The normal bridge path performs one Hook HTTP request rather than health+lifecycle+hook round trips. ## Standalone mode When a supported Host CLI is available, Hezor can launch the real agent process itself: ```bash hezor run --mode standalone --host opencode "refactor the catalog architecture" hezor run --mode standalone --host claude-code "implement the feature" ``` Each action has a Hezor-managed action file and response file. The Host must return a typed `ActionResponse` JSON. Hezor never treats stdout prose as completion evidence. ## Native TUI Run `hezor` with no arguments. The native TUI provides a responsive Home/Run control console with semantic colors, adaptive two-column/stacked/compact layouts, arrow/PageUp/PageDown/Home/End navigation, CJK/emoji-aware width handling, live SSE events, task/evidence/uncertainty/AON views and progressive run controls. Rendering uses one terminal writer, row-level frame diffs, absolute cursor addressing, synchronized updates where supported, `state_revision`/ETag conditional snapshots and a 60ms event debounce. Identical frames produce no terminal write, which avoids the old clear/redraw flicker path. Configure the palette per project: ```bash hezor config set tui-theme auto hezor config set tui-theme dark hezor config set tui-theme light hezor config set tui-theme mono ``` `NO_COLOR=1` always disables color. When stdin/stdout is not an interactive terminal, Hezor automatically uses plain CLI mode. ## Project-local SQLite state Every `hezor init` creates an independent SQLite database for that project: ```text .hezor/ ├─ state/ │ ├─ hezor.db │ ├─ hezor.db-wal # while WAL is active │ └─ hezor.db-shm # while WAL is active ├─ cache/ │ ├─ runs//aon │ ├─ runs//host │ ├─ runner-responses │ ├─ packs │ ├─ logs │ └─ migration └─ artifacts/ ``` `hezor.db` is the canonical structured state: Run/Contract/Task/Action, Session/Lease, Event, Evidence/Uncertainty, transactions, router profile, memory, identity, governance, benchmark and registry trust metadata. Run mutations and Action consumption are committed atomically in SQLite transactions. Events use a durable SQL sequence and are replayed to SSE clients. Large or naturally file-oriented objects remain outside SQLite: AON/script source, host stdout/stderr, documents, attachments, archives, exported workflow packs and diagnostics. SQLite stores only their URI/path, digest, size, MIME type, owner and lifecycle metadata. Hezor uses WAL, foreign keys, a busy timeout and integrity checks. TUI synchronization still uses `state_revision`, ETag and SSE, but the revision is now derived from committed SQLite state rather than file snapshots. Inspect the backend with: ```bash hezor state status --json hezor state check hezor cache status ``` Pre-SQLite v3 projects are imported once during initialization/startup. Old structured JSON/JSONL state is archived under `.hezor/cache/migration/legacy-state-v3/` and is no longer runtime truth. On Windows 10+ Hezor uses the OS SQLite API exposed by `winsqlite3.dll`; the Windows binaries therefore remain CGO-free. Linux builds link the system `libsqlite3.so.0`, which must be present at runtime. ## AON 2.0 ```bash hezor aon validate workflow.aon hezor aon format workflow.aon hezor aon compile workflow.aon hezor aon graph workflow.aon hezor aon analyze workflow.aon hezor aon simulate workflow.aon ``` AON supports modules/imports, multiple workflows, tasks/calls, resources, data contracts, signals, ALL/ANY activation, bounded re-entry, policy/interaction, acceptance/evidence and explicit END conditions. Built-in workflows can be inspected or exported: ```bash hezor workflow list hezor workflow show source-sync hezor workflow export --dir ./workflows all ``` ## Build from source Requirements: **Go 1.23+**. Windows uses the OS SQLite runtime and remains CGO-free. Linux source builds require SQLite development headers/libraries (`libsqlite3-dev` on Debian/Ubuntu); Linux runtime requires `libsqlite3.so.0`. ```bash make quality make build make e2e make release ``` Release artifacts include native Linux and Windows portable products, public JSON Schemas, canonical Workflow source, formal product documents and an SPDX SBOM. ### Windows installer On Windows with Go 1.23+ and Inno Setup 6: ```powershell ./scripts/build-windows.ps1 ``` Expected installer: ```text dist/Hezor-Agent-2.0.0-Setup-x64.exe ``` If `HEZOR_SIGN_CERT_PFX` is configured, binaries and Setup EXE are Authenticode-signed. The build does not pretend an unsigned artifact is signed. ## Release quality gates Linux CI requires: ```text gofmt check go vet go test go test -race native binary E2E TRAE attached process E2E ``` Windows CI builds native PE binaries, runs native Windows E2E and builds the Inno Setup installer. ## Security model - `hezord` listens on loopback by default and refuses remote binding unless explicitly enabled. - The local API uses a per-daemon 256-bit bearer secret stored outside the project in the current user's private state directory; project plugins never read that secret directly. - A declared local Source-of-Truth must exist and be readable before PLAN/GOVERN execution; otherwise Hezor pauses with a human-resolvable `resource-unavailable` uncertainty instead of asking the Host to guess. - `.hezor` is local runtime state and is ignored by Git by a managed internal `.gitignore`. - Tool-level sandbox/permission enforcement remains owned by the Host/OS. - AON precision and Host enforcement grade are reported separately. - Invalid/stale Action IDs, response types and contract revisions fail closed. - Crash recovery never blindly replays an in-flight task. - Host integration files are SHA-managed and user modifications are preserved. - Daemon logs redact sensitive fields before disk write; diagnostic bundles apply an additional redaction pass. See [SECURITY.md](SECURITY.md). ## Product and engineering documents - [产品设计和规划白皮书](docs/01-Hezor-产品设计和规划白皮书.md) - [产品设计说明书](docs/02-Hezor-产品设计说明书.md) - [业务战略定位白皮书](docs/03-Hezor-业务战略定位白皮书.md) - [产品技术架构说明书](docs/04-Hezor-产品技术架构说明书.md) - [产品设计文档](docs/05-Hezor-产品设计文档.md) - [产品生态集成方案](docs/06-Hezor-产品生态集成方案.md) - [Native rewrite audit](docs/07-Hezor-Agent-2.0-Native-Rewrite-Audit.md) - [用户手册](docs/08-Hezor-Agent-2.0-用户手册.md) - [CLI 参考](docs/09-Hezor-Agent-2.0-CLI-参考.md) - [TUI 使用指南](docs/10-Hezor-Agent-2.0-TUI-使用指南.md) - [运行维护与故障排查](docs/11-Hezor-Agent-2.0-运行维护与故障排查.md) ## Repository layout ```text cmd/hezor native CLI/TUI client cmd/hezord native local control service internal/app run lifecycle and control loop internal/aon AON parser/validator/compiler internal/router adaptive intervention + learning profile internal/resource external source/resource resolver internal/grounding repository semantic grounding internal/host capability detection and standalone runner internal/mcp MCP stdio bridge internal/server authenticated local API/SSE internal/store versioned local persistence internal/evidence semantic/Git/source-sync evidence internal/tui native home/run consoles internal/terminal Linux/Windows raw terminal abstraction internal/install managed low-intrusion host projections internal/workflow validated built-in workflow assets pkg/api stable public wire types pkg/sdk public local control client schemas JSON contract schemas packaging/windows Inno Setup installer source scripts deterministic build/release/qualification gates ``` ## TUI keyboard model The native TUI uses semantic terminal key events instead of rune-by-rune input. On Windows Terminal and ANSI-capable Linux terminals: ```text ↑ / ↓ select Run/Task or scroll focused detail ← / → switch Host on Home; switch detail tabs in Run Console PgUp / PgDn fast navigation Home / End jump to boundaries Tab switch Tasks/Detail focus (or Attached/Standalone on Home) Enter attach/open selected Task detail F resume auto-follow of the currently running Task P/R/X pause/resume/cancel C/G/S/M constraint/goal/scope/comment Q detach/quit without cancelling the Run ``` Text entry supports cursor movement, Home/End, Backspace and Delete. Layout is CJK display-width aware and automatically changes from two-column to stacked/compact presentation on smaller terminals. ## hezord lifecycle Auto-started daemons use `managed` lifecycle. TUI, MCP and Standalone clients acquire a short-lived Client Lease and heartbeat it; the frontend records `client_pid`, `daemon_pid`, `daemon_instance_id` and `lease_id` in the user's private state directory. When all leases are released or expire, a managed daemon exits after a short idle grace. ```bash hezor daemon status hezor doctor ``` show lifecycle and client-session diagnostics. `hezor daemon start` promotes/starts the daemon as `persistent`; persistent daemons never idle-exit and require explicit `hezor daemon stop` (or OS termination). ## Typed submit protocol Attached Hosts should never infer an `ActionResponse` shape from validation failures: ```bash hezor next --json hezor submit --example hezor schema show hezor://schema/task-result/v2 hezor submit --file response.json --json ``` `hezor://schema/...` identifiers are embedded product URIs. The same JSON Schemas are shipped under `share/hezor/schemas/`. ActionResponse HTTP 409 errors include the expected response type, schema and an action-specific example. `hezor run --json` returns a compact bootstrap view by default and does not expose Git baseline file hashes. Use `hezor run --full --json` or `hezor status --json` only when the full snapshot is intentionally required. On PowerShell use native Windows paths without escaping the drive colon: ```powershell & 'D:\Software\Hezor\hezor.exe' status $RunId --json .\.hezor\bridge\hezor.cmd submit $RunId --example ``` ## Runtime TaskGraph and Run export Canonical Contract/AON remains the typed execution truth. When a Host publishes runtime plan/task changes (OpenCode uses `todo.updated`), Hezor persists a separate versioned **Runtime TaskGraph** and **Runtime AON**. The TUI follows this live graph while preserving canonical revisions for audit and Action validation. ```bash hezor export run --output hezor-run-.zip ``` The export is a single-Run audit/reproduction image containing a filtered SQLite database, readable JSON table mirrors, runtime task/AON snapshots, Run cache/Host logs and Run-owned file objects. It excludes sibling Runs and local control-plane credentials.