Files
dev-v1/LLM.md

7.3 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.

2026-11-16: codex bump for dev doctor's thread inventory (hanzo-inc/cloud#762)

upstream/codex → cdd641a1 (hanzoai/codex#9). When a session rolls over, the old rollout file stays on disk while the thread row points at the new one. dev doctor now counts that old file as "superseded" instead of reporting a missing row and a duplicate thread. Ships with the next tag-driven release.