Files
dev-v1/LLM.md

7.0 KiB
Raw Permalink Blame History

Hanzo Dev

dev: a coding agent for the terminal. Hanzo owns the front door; upstream owns the engines.

Shape

  • crates/hanzo-dev: the binary. main.rs is the whole command surface; each subcommand hands off to a library.
  • crates/hanzo-config: provider and product home. crates/hanzo-tui: the Hanzo account behind /login, /logout, /auth, /status and /usage (shells out to the hanzo CLI). crates/hanzo-kai: Kai, the controller.
  • upstream/codex: submodule of hanzoai/codex (openai/codex plus Hanzo's commits). The gitlink is the pin. Crates are path dependencies; the checkout stays pristine (git -C upstream/codex status --porcelain empty after build and test).
  • The cloud-driven wasm loop lives in hanzo-inc/dev; nothing here depends on it.

Working here

make build          the dev binary (must pass, no warnings)
make test           the Hanzo suite
make test-upstream  hanzoai/codex's own suite
make bump           how to move upstream/codex forward

Upstream

Never edit upstream by hand. A change upstream hard-codes is a commit on hanzoai/codex main, made in upstream/codex, pushed before the gitlink moves. Anything that need not live in upstream's crates goes in a hanzo-* crate here.

Bump = merge: in upstream/codex, git fetch upstream && git merge upstream/main; resolve in git; find new Codex strings (git diff ORIG_HEAD -G'"[^"]*Codex' -- 'codex-rs/*.rs') and new env!("CARGO_PKG_VERSION") reads (make test names them); fix as commits; make build test; push; commit the gitlink. Root Cargo.toml [workspace.dependencies]/[patch] mirror the fork's codex-rs/Cargo.toml; refresh on a bump. Dev's own additions: the hanzo-* crates, the rusqlite patch, no v8 patch.

The delta (git log --no-merges upstream/main..main in upstream/codex):

  • codex-rs/hanzo crate: names, API_BASE, DEFAULT_MODEL, is_hanzo, catalog, model::pick, the controller interface, version, pace, effort. Upstream crates read it; never the reverse.
  • Hooks, no-ops until the binary fills them: codex_app_server::register(Extension) and codex_tui::register(Account { login, logout, show, usage }). Without an account, /login and /auth are hidden and /usage needs ChatGPT.
  • Commits prefixed tui:, cli:, config:, core:, words:, brand:, version:.
  • Repeated tool-cycle guard (core/src/session/cycle.rs): an identical step answered identically fails the turn with repeated identical tool-use cycle detected; cloud's coding loop reads that mark.
  • Rate limits never surface: hanzo::pace honors x-ratelimit-* and Retry-After; 429/503/overload retry with jitter (1–60 s), no cap while the turn lives, shown as turn.waiting. Test: crates/hanzo-dev/tests/pace.rs.
  • Reasoning effort is one table, hanzo::effort (auto sends none, so the router decides). Test: tests/effort.rs.
  • TUI: /context shows window use; /usage on Hanzo runs hanzo usage summary --range (daily/weekly/cumulative → 24h/7d/30d).

Dev reads only Hanzo directories: ~/.hanzo/dev (or DEV_HOME), <repo>/.hanzo/dev/, /etc/hanzo/dev/. Never .codex. A profile with no provider gets Hanzo. Test: tests/launch.rs.

Version

Set by hand in root Cargo.toml [workspace.package], npm/package.json, and the tag; release.yml refuses a mismatch. Only hanzo-dev carries it (hanzo::version::set); every other crate asks hanzo::version::get() at run time. Dev's libraries stay 0.0.0 so a release recompiles one crate.

Release

release.yml on a pushed tag: version opens a draft; five build jobs on xl-linux-amd64 upload; publish checks 28 assets, then Homebrew and npm. Branch runs build a draft only (delete by hand). All GitHub calls go through scripts/ghapi.sh (retries rate limits and 5xx).

Cache: sccache via hanzoai/ci bin/cache (pinned CI_SHA) in the org ci-cache bucket. Key covers the upstream pin, toolchain, root Cargo.toml/Cargo.lock minus the version, and build env; not crates/. Only main and tags write. Traps: cargo-zigbuild must live at ~/.cargo/bin (its path is hashed into every object); any CARGO_* var except CARGO_BUILD_JOBS busts the cache. Warm build ≈ 5–7 min; engine moved ≈ 18; cold ≈ 25.

Review and memory models

On Hanzo, approval review and memory extraction use DEFAULT_MODEL; the reviewer takes its preferred id only when the catalog serves it, else the parent's model. Test: tests/review.rs.

Kai (controller)

Kai returns a validated operation or an explicit abstention, never advice. crates/hanzo-kai: loop (flow), ledger (ledger), tools. Search is tgrep (hanzo-trigram, in process); seams are traits (find::Finder, decide::Transport).

  • Action: typed operation (search, decide, mutate, generate, edit, test, revert), source (rule, kai, model, recover), preconditions, expected, verification. Only the verifier settles an outcome.
  • Cheapest first: an action that applies runs with no inference; else one Kai decision (fix.site@1, fix.turn@1); else low then full-effort generation; else recover. Per-program outage cooldowns.
  • Ahead: the first call starts beside the search; a settled search or moved state cancels it.
  • Revision-bound: preconditions checked just before execution; an edit invalidates pending decisions. Caches key on content, not commits.
  • Recover: fewer failing tests is progress; the same failure fingerprint with no state change picks a different action or escalates.
  • Fast path mutate: generic token transforms at top sites, eight at once, 2.5 s cap (8 s while a call is pending); slow tests narrowed to the failing ones.
  • Test runs leave nothing: untracked, unignored files a run creates are swept (tools::Litter). Hypothesis storage goes to the run's temp dir.
  • Ledger: kai/ledger.jsonl beside the trace, replayable, redacted.
  • Generation: Zen or enso-flash (kai.toml [generate]), streamed, budgeted. Edits requested as strict JSON (edits[] of file, line, old, new); reasoning calls cap at 16,384 tokens at effort low. A malformed answer gets one repair, an empty escalation one fallback.
  • Transport: HTTP POST /v1/decisions; ZAP over UDS is the planned alternative.

House rules

  • Hanzo APIs: https://api.hanzo.ai/v1/ only.
  • Keep upstream's interaction model and animation; the branding is ours.
  • Linux, macOS, Windows all work.
  • Upstream project names appear only in NOTICE.
  • just-every/code (~/work/just-every/code) is reference only; ports recorded in migration/.

2026-11-16: codex bump for the service_tier 400 (hanzo-inc/cloud#756)

upstream/codex → 6eda8a71 (hanzoai/codex#8). api.hanzo.ai refuses every service_tier with a 400 ("would buy something this model's price does not cover"). The fork no longer sends one to a Hanzo base URL and no longer offers the Fast tier for Hanzo models (hanzo::SERVICE_TIERS = false, hanzo::service_tier_for). The fix reaches users with the next tag-driven release; merging to main ships nothing on its own.