Files

T

ZacharyZhang-NY 4d1e4fdc52 Add /graph G1: parallel fan-out with worktree isolation and merge-back

With KIGI_GRAPH_CONCURRENCY > 1 (default 3, clamp [1,8]) and >=2 Ready nodes,
drive_graph — the single dispatch loop shared by setup/advance/resume — runs
parallel batches: each node executes as a bounded worker<->verifier subagent
loop (KIGI_GRAPH_NODE_ROUNDS, default 3; general-purpose children with the
full implementer toolset; worktree isolation on round 1, resume keeps context
and worktree on later rounds; NODE_RESULT/NODE_VERDICT terminal contracts
parsed fail-closed with fence-stripping and line anchoring). Achieved nodes
merge back SEQUENTIALLY via kigi_workspace apply_worktree in Merge mode; a
conflict fails the node, block_dependents fires, and surviving chains keep
going. gn-final always runs serially on the full goal engine. Concurrency=1
is byte-identical to the serial G0 path; non-git projects degrade to serial.

Merge primitive hardened for real use (kigi-workspace): the 3-way apply is
now byte-safe (binary files no longer read as UTF-8 and silently deleted)
and gains the identical-content rule (ours==theirs => already present, not a
conflict) — without it, any dirty file inherited via PreserveWorkingTree
false-conflicted every node merge and multi-wave graphs self-poisoned.

Adversarial review pass (16 confirmed findings, all fixed): in-session
resume demotes orphaned Running nodes instead of wedge-pausing forever after
a mid-batch Esc; cancel re-sweeps subagents AFTER the turn abort so workers
spawned in the cancel window die too; empty child ids are never adopted as
resume targets (no unisolated escape to the shared tree); a successful
isolated round returning no worktree fails the node (soft-fallback can no
longer put N writers in one tree); main-HEAD movement during a batch aborts
merges instead of reverse-applying external commits; failed nodes still
charge the token budget; budget trips terminally fail the in-flight node;
runaway (>600s) rounds are cancelled by spawn id and retried via resume;
worker summaries are marker-sanitized before verifier embedding. Merged
worktrees are removed immediately (storage discipline); failed nodes keep
theirs for postmortem.

Tests: 4922 kigi-shell lib tests green (58 graph-specific), including
fan-out proven by a held-reply gate, real-git batch merge with cleanup
assertions, budget charging across verdicts, cap trimming, resume-after-
cancelled-batch, and backgrounded-round cancel semantics.

2026-07-20 15:32:35 -04:00

6.5 KiB

Raw Blame History

Kigi — agent/developer notes

Single source of truth for how this repository is organized and the constraints every change must respect. Update this file whenever the tech stack or product direction changes.

What this is

Kigi is an unofficial Kimi Code CLI community build: a hard fork of xai-org/grok-build (Apache-2.0, Rust) re-targeted at the Kimi Code subscription API and the Moonshot open platform. It coexists with the official kimi CLI: binary kigi, config dir ~/.kigi (KIGI_SHARE_DIR override), keyring service kigi, env prefix KIGI_*. Never read or write ~/.kimi (except the explicit one-time read-only import) or any KIMI_* env var.

Hard constraints

Zero egress: outbound connections are limited to auth.kimi.com, api.kimi.com, api.moonshot.cn, api.moonshot.ai, GitHub Releases domains, and user-configured MCP servers. No telemetry, no analytics, ever. crates/codegen/kigi-env is the single home of first-party endpoints.
Toolchain: Rust 1.97.0 (rust-toolchain.toml), edition 2024.
Gates (all must stay green): cargo check --workspace --all-targets, cargo clippy --workspace --all-targets (zero warnings), cargo fmt --all --check, cargo deny check advisories.
Observability is local: kigi-log (unified session log, --debug firehose, subsystem file logs, opt-in instrumentation) writes under ~/.kigi only. Its zero-network property is a contract.
The root Cargo.toml is hand-maintained (upstream's generator is not in this repo). Members sorted; versions inherited from workspace.package.version (0.1.0).

Layout

crates/codegen/ — the bulk of the application (62 kigi-* crates). Key ones: kigi-bin (binary kigi), kigi-tui (full-screen TUI + headless -p mode + acp/mcp commands), kigi-shell (agent runtime, leader-follower IPC, sessions), kigi-sampler (inference client; ChatCompletions/Responses/Messages backends), kigi-auth (credentials), kigi-config (config layering, ~/.kigi paths), kigi-env (endpoints), kigi-tools (tool implementations incl. codex/opencode ports — see its THIRD_PARTY_NOTICES.md), kigi-workspace (FS/VCS/exec/permissions, checkpoint/worktree), kigi-log (local observability).
crates/common/, crates/build/, prod/mc/ — shared libs, proto build, proxy wire types (the latter to be redefined against Kimi in M1).
third_party/ — vendored Mermaid rendering stack (untouched policy).
bin/protoc — dotslash launcher used by proto codegen.

Storage discipline

Tests that touch the filesystem MUST use tempfile::TempDir (drop cleans up) — never bare std::env::temp_dir() + create_dir_all, which leaks directories into the OS temp root forever.
target/ grows past 150GB across repeated full-workspace builds (incremental is already off); run cargo clean when it exceeds ~50GB and at milestone boundaries.
Graph node worktrees are removed right after a successful merge-back; only FAILED nodes keep theirs for postmortem.

Test seams

Cross-crate test hooks are behind the test-support cargo feature (kigi-workspace, kigi-pager-render, kigi-config, kigi-tui), enabled via dependents' [dev-dependencies]. Don't expose new test seams as plain #[cfg(test)] items across crate boundaries.

Graph mode (`/graph`, post-0.1.x — plan.md in the parent dir)

A deterministic DAG scheduler layered over the goal engine: /graph <objective> decomposes the objective into nodes (graph planner subagent → Agentproof-style static gate in graph_plan.rs), then executes each node as one ordinary goal — the agentic loop lives INSIDE the node; the edges stay deterministic Rust. The harness appends a terminal gn-final verification node depending on every planner node.

Feature flag KIGI_GRAPH=1 (default off); availability additionally requires the goal harness (BuiltinGate::Graph).
Key modules (kigi-shell): session/graph_tracker.rs (pure state machine; reuses GoalStatus/GoalPhase/GoalPauseReason), session/graph_plan.rs (planner-JSON contract + validation + fnv id canonicalization), session/graph_planner.rs (planner runner, reuses the goal planner spawn plumbing), session/acp_session_impl/graph.rs (orchestration seam).
Seam points: handle_prompt intercepts GraphSet/GraphResume; the in-turn loop's EndTurn arm calls run_graph_round_end() to advance nodes within the same turn; goal auto-pauses cascade to the graph in auto_pause_goal_if_active_inner; node goals are armed with the REMAINING graph budget so enforce_goal_token_budget cascades trips.
Persistence: PersistenceMsg::GraphModeState(Option<..>) → <session_dir>/graph/state.json (None tombstones after clear); immutable per-version baselines graph/graph.baseline.v{N}.json; per-node goal artifacts archived to graph/<node_id>/. Restore demotes Active→UserPaused and Running→Ready (re-run is safe: the verifier gates completion).
/goal and /graph are mutually exclusive while the graph owns the engine; e2e suite: acp_session_tests/graph/graph_e2e_tests.rs.
Parallel fan-out (G1): with KIGI_GRAPH_CONCURRENCY > 1 (default 3, clamp [1,8]) and ≥2 Ready nodes, drive_graph runs batches via acp_session_impl/graph_workers.rs — per node a bounded worker↔verifier subagent loop (KIGI_GRAPH_NODE_ROUNDS, default 3; general-purpose children; worktree isolation on round 1, resume keeps context+worktree on later rounds; NODE_RESULT: / NODE_VERDICT: terminal contracts parsed fail-closed), then SEQUENTIAL merge-back via kigi_workspace::worktree::apply_worktree (ApplyMode::Merge); a conflict fails the node and blocks its dependents while other chains continue. gn-final always runs serially on the full goal engine. Concurrency=1 is byte-identical to the serial G0 path. Ceiling: a worker round exceeding the foreground subagent await budget (600s) is cancelled and retried via resume.

Milestones (PRD §8.3)

M0 (done): rename, deletions (voice/telemetry/announcements/marketplace/ relay-gateway), toolchain, gates.
M1: Kimi device-flow auth (F1), Moonshot API-key channel (F2), inference via ChatCompletions (F3), dynamic model sync (F4). The auth stack in kigi-shell/src/auth + kigi-auth gets rewritten here; transitional grok.com references live only there and in kigi-sampler/proxy types.
M2: server-side search/fetch (F5), command parity with kimi-cli 1.49.0 (F6), one-time ~/.kimi/config.toml import (F7), F9 smoke list, perf CI.
M3: GitHub Releases distribution, install scripts, self-update (F8).

6.5 KiB Raw Blame History