From 9bf575f94e81852b124c418fa415451fa458b9b2 Mon Sep 17 00:00:00 2001 From: KeiSei84 <2206745@gmail.com> Date: Wed, 27 May 2026 00:49:37 +0800 Subject: [PATCH] docs: catch up README + CHANGELOG + encyclopedia to v0.45 (mirror of keigit fdb84f24) --- CHANGELOG.md | 76 ++++++++++++++++++++++++++- README.md | 48 +++++++++++++++++ docs/encyclopedia/cross-cli-policy.md | 34 ++++++++++++ docs/encyclopedia/multi-cli-agents.md | 27 ++++++++++ 4 files changed, 184 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ec7859..833d1f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,4 +13,78 @@ All notable changes are tagged via `git tag v*`. This file tracks unreleased wor ## Released -Release notes per tag are kept in the GitHub Releases UI. See `git tag --sort=-creatordate`. +Release notes per tag are kept in the GitHub Releases UI: +https://github.com/KeiSeiLab/KeiSeiKit-1.0/releases + +Highlights below; full notes in each tag's GitHub Release page. + +### v0.45.0 — post-install onboarding wizard + 5 prod-install bug fixes (2026-05-26) + +User feedback from real curl|bash with `profile=full`: "нет выбора провайдера, нахуй не понятно что делать после установки". Closed. + +- **NEW** `kei onboard` — 4-step wizard auto-triggered at end of install (TTY only). Walks user through: pick primary CLI → kei mcp-wire → MOONSHOT_API_KEY hint → kei-doctor health check. Re-runnable any time. +- **NEW** `bin/kei onboard|setup|wizard` arm. +- **FIX** `act_runner: command not found` — resolver tries `act_runner` → `gitea-runner`; brew install switched to `gitea-runner` (functionally equivalent for Forgejo). +- **FIX** Forgejo `no such table: user` — added `forgejo migrate` before `admin user create` (idempotent). +- **FIX** `zoekt: No formulae or casks found` — graceful fallback: brew taps → `go install` → clean skip with warning. +- **DEFERRED** `kei-shared missing` + launchd `Input/output error` → v0.46. + +### v0.44.0 — pre-release audit: 1 CRITICAL + 4 HIGH + 4 MEDIUM (2026-05-26) + +Four-CLI parallel pre-release audit (Claude+Grok+Gemini+Copilot, each reviewing different angle) surfaced 9 real issues in v0.43. All patched. + +- **CRITICAL** Walk-up canonicalize for non-existent leaf paths (defeats v0.42 fix #1 when parent didn't exist either). +- **HIGH** O_NOFOLLOW open + fd-write closes TOCTOU window during hook chain await. +- **HIGH** Sanitize MOONSHOT_API_KEY pre-curl (config injection blocked). +- **HIGH** `env_clear` + whitelist on subprocess spawn (no secret leak via kei_bash). +- **HIGH** `Path::starts_with` + canonical KEI_ALLOWED_ROOTS (no prefix-bypass). +- **MED** macOS $TMPDIR carve-out (allowed_roots check FIRST; narrowed /var/ blanket). +- **MED** Timeout doc honesty (per-step not aggregate). +- **MED** cwd in hook input. +- **MED** Failure-fallback cache has full schema. + +### v0.43.0 — kei limits + 4 audit fixes (2026-05-26) + +- **NEW** `kei limits` — honest subscription-quota report. Research-grounded: 4 of 5 CLIs have no public quota API. Only Kimi balance via Moonshot `/v1/users/me/balance` (requires MOONSHOT_API_KEY). +- **NEW** Pet integration — reads cache, shows Kimi balance segment if live. +- **FIX** Atomic cache write (mktemp + atomic mv). +- **FIX** `tonumber?` swallows parse errors; `_safe_json` wrapper. +- **FIX** Token off argv (curl `--config -` via stdin). +- **FIX** `jq` runtime guard. + +### v0.42.0 — re-audit fixes: 1 CRITICAL + 5 HIGH+MED (2026-05-26) + +Re-audit found v0.41 fixes were incomplete. All patched. + +- **CRITICAL** Symlink leaf bypass — canonicalize full path + reject is_symlink leaf for new files (3-of-4 reviewers convergent). +- **HIGH** $HOME removed from default allowed_roots (was self-neuter vector — agent could overwrite `~/.claude/hooks/*`). +- **HIGH** Empty section `[bash]/[edit]/[write]` now also FAIL-CLOSED. +- **MED** `tokio::fs` in load_chain. +- **MED** process_group + killpg applied to hook subprocess too. + +### v0.41.0 — security hardening from Phase C dogfooding (2026-05-26) + +- **HIGH** Fail-CLOSED on missing config + hook (was: silent pass-through). +- **HIGH** Path-traversal guard (denylist + canonicalize). +- **MED** `tokio::fs` async I/O (was: blocking std::fs on tokio thread). +- **MED** Process-group kill on Unix. + +### v0.40.0 — Phase C: cross-CLI hook enforcement (2026-05-26) + +- **NEW** `kei_bash` / `kei_edit` / `kei_write` MCP tools in `kei-mcp`. +- **NEW** `policy-chain.toml` SSoT for which hooks gate which tool. +- **NEW** 3-tier enforcement model (Claude+Grok TIER 1, Copilot TIER 2, Agy+Kimi TIER 3). +- **NEW** `kei mcp-wire` orchestrator + 5 per-CLI wire scripts. + +### v0.39.x — multi-LLM DNA (2026-05-26) + +- **NEW** `kei pick` interactive picker. +- **NEW** `kei agent ` with DNA-driven provider resolution. +- **NEW** `kei primary` get/set default backend. +- **NEW** `spawn_agent` MCP tool — any MCP-capable CLI can spawn KeiSeiKit agents on any backend. + +### v0.38.0 — opt-in hook packs + stack profiles (2026-05-26) + +- **NEW** Hook packs (safety / evidence / observability / epistemic / orchestration / git-guard / stack-rust). +- **NEW** Stack profiles (minimal / web / ml / systems / mobile). +- **NEW** `kei configure` re-runnable. diff --git a/README.md b/README.md index b625ec2..2ba198a 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,54 @@ duplicated install logic. into client-native config — those are bridge targets, not separate profiles. +## Post-install — the `kei` CLI (v0.45+) + +After install, `kei` is the substrate entrypoint. On first interactive +run an onboarding wizard walks you through picking a primary LLM +orchestrator and wiring kei-mcp into the CLIs you have installed: + +```bash +kei # launch primary CLI (default: claude) +kei onboard # post-install wizard (re-runnable) +kei pick # interactive primary picker +kei primary [] # get/set primary LLM provider + +kei agent "" # invoke agent: backend from DNA → primary +kei agent --on=grok "..." # invoke agent on a specific backend +kei run-via "" # explicit-backend dispatch + +kei mcp-wire # wire kei-mcp into all installed CLIs +kei mcp-wire --list # show enforcement tier per CLI + +kei limits # honest subscription-quota report + # (4 of 5 CLIs have no public API) + +kei configure # re-pick hook packs + stack profile +kei message ... # cross-session mailbox +kei --status # splash with substrate health +``` + +### Multi-LLM agent dispatch + +Agents are markdown prompts that can be served by ANY of 5 supported +CLIs (Claude Code, Grok, Antigravity-Gemini, GitHub Copilot, Kimi). +Each agent's manifest may declare a `provider` field that becomes its +DNA; `kei agent ` then routes to that provider automatically. +See [`docs/encyclopedia/multi-cli-agents.md`](./docs/encyclopedia/multi-cli-agents.md). + +### Cross-CLI policy enforcement + +KeiSeiKit's safety hooks (`no-github-push`, `safety-guard`, +`destructive-guard`, `citation-verify`, `numeric-claims-guard`) extend +to non-Claude CLIs through a 3-tier enforcement model: + +- **TIER 1 — full native**: Claude (existing) + Grok (ports our hooks to `~/.grok/settings.json`) +- **TIER 2 — MCP-wrapped**: Copilot (`--excluded-tools=shell` + force `kei_bash` via MCP) +- **TIER 3 — advisory**: Agy + Kimi (cannot disable native shell; prompt-level only) + +See [`docs/encyclopedia/cross-cli-policy.md`](./docs/encyclopedia/cross-cli-policy.md) +for the full matrix + setup. + ### Outcome-only — try just the outcome loop (5 files, ~200 LOC) If you want to try only the outcome-tracking primitive without diff --git a/docs/encyclopedia/cross-cli-policy.md b/docs/encyclopedia/cross-cli-policy.md index fe862b1..165291f 100644 --- a/docs/encyclopedia/cross-cli-policy.md +++ b/docs/encyclopedia/cross-cli-policy.md @@ -116,6 +116,40 @@ The chain runs against the same hook scripts Claude uses; identical input shape, identical decisions. On block, the hook's stderr surfaces as the MCP error message so the calling agent sees exactly why. +**v0.44 hardening** (post second 4-CLI re-audit, supersedes v0.42; CURRENT): + +The second-round audit (Claude+Grok+Gemini+Copilot, each from different +angle) found 9 real issues in v0.42–v0.43. All patched. Highlights: + +- **Walk-up canonicalize** for non-existent leaf paths — closes the v0.42 + bypass where the *parent's parent* could be a symlink. validate_path + now finds the deepest existing ancestor and canonicalizes from there. +- **O_NOFOLLOW + fd-write** — closes TOCTOU window between validate_path + and `fs::write`. Concurrent symlink-swap during hook chain await is now + rejected at `open()` time. +- **`env_clear` on subprocess spawn** — `kei_bash` no longer inherits + `AWS_*`, `GITHUB_TOKEN`, `MOONSHOT_API_KEY`, etc. Whitelist forwards + PATH/HOME/USER/LANG/TERM/SHELL/PWD/TMPDIR only. Add named vars via + `KEI_SAFE_ENV_EXTRA`. +- **`Path::starts_with` + canonical KEI_ALLOWED_ROOTS** — + `KEI_ALLOWED_ROOTS=/home/u/proj` no longer matches `/home/u/proj-evil/`. + Component-aware containment + symlink resolution (so `/var → /private/var` + on macOS works for `/var/folders` $TMPDIR). +- **MOONSHOT_API_KEY sanitization** in `kei limits` — token validated + against `[A-Za-z0-9_.-]+` before being fed to `curl --config -`; blocks + config injection if env value was tampered. +- **macOS `/var/folders` carve-out** — denylist no longer blocks $TMPDIR. + allowed_roots check runs BEFORE denylist; only `/var/db/`, `/var/log/`, + `/var/root/` etc. are now blanket-denied. +- **Hook subprocess hardening** — `process_group(0)` + `killpg` now also + applied to hook spawn (was: only on bash action; v0.42 left hook + grandchildren orphan on timeout). + +**v0.43 hardening** (post first re-audit): + +- 4 audit fixes in `kei-limits.sh` (atomic cache, tonumber? parse, + off-argv token, jq runtime guard). + **v0.42 hardening** (post 4-CLI re-audit, supersedes v0.41): - **Fail-CLOSED everywhere** — missing config, missing hook, OR empty diff --git a/docs/encyclopedia/multi-cli-agents.md b/docs/encyclopedia/multi-cli-agents.md index 5a72a83..350f49b 100644 --- a/docs/encyclopedia/multi-cli-agents.md +++ b/docs/encyclopedia/multi-cli-agents.md @@ -108,6 +108,18 @@ strengths; the substrate is agnostic about which you pick. Pick by: - **Independent second opinion** — same agent, different model, see if conclusions diverge. +## First-run wizard (`kei onboard`, v0.45+) + +After install, `bootstrap.sh` auto-triggers `kei onboard` if stdin is a TTY. +The wizard walks through: + +1. Pick primary LLM orchestrator (claude / grok / agy / copilot / kimi) +2. Run `kei mcp-wire` to wire kei-mcp into all detected CLIs +3. Optional MOONSHOT_API_KEY hint for `kei limits` live polling +4. Run `kei-doctor` health check + +Re-run any time: `kei onboard`. Skip auto-trigger on install: `KEI_NO_ONBOARD=1`. + ## Orchestrator picker — `kei` no longer hardcodes claude Without args, `kei` reads `~/.claude/config/primary.toml` and execs that CLI. @@ -125,6 +137,21 @@ The splash shows `primary CLI: ` so you always know which orchestrator will start. If the chosen primary isn't installed, `kei` prints the install command and offers `kei pick` as recovery. +## Subscription quotas — `kei limits` (v0.43+) + +```bash +kei limits # human-readable report +kei limits --json # machine-readable +kei limits --quiet # cache-refresh only, no output +``` + +Research-grounded honest delivery: 4 of 5 CLIs have **no public programmatic +API for quota**. The command shows status markers + dashboard URLs for those. +Only Kimi exposes a balance API via Moonshot `/v1/users/me/balance` — +requires `MOONSHOT_API_KEY` env. The cache lives at +`~/.claude/pet/limits-cache.json`; the pet statusline reads it (does NOT +poll itself) and displays the Kimi balance segment when live. + ## Cross-CLI sub-agent spawn via MCP — `spawn_agent` `kei-mcp` exposes a built-in `spawn_agent` MCP tool. Any CLI that connects