fix: unified system dependency check; start without Git Bash (#291)

[fancyboi999]

Related Issue

Resolves #291. Also fixes the crash in #259 and supersedes the piecemeal approaches in #261 (Git Bash) and #290 (fd).

Problem

Kimi Code CLI depends on three external command-line tools — ripgrep, fd, and a POSIX shell (Git Bash on Windows) — but they are not standard system dependencies and were handled by three inconsistent, scattered strategies:

Tool	On missing (before)
ripgrep (rg)	Robust: probe → cache → auto-download + checksum (rg-locator).
fd	Probed in fd-detect, then degraded silently — users never knew @ completion was reduced.
Shell (Git Bash)	detectEnvironment threw, so KimiCore construction failed and the whole CLI crashed at startup (#259) — even though only the Bash tool needs a shell.

There was no single place that answered "is X a dependency, and what happens when it is missing?", and the docs never declared these dependencies.

What changed

Start without Git Bash (root cause of #259)

• kaos: detectEnvironment now returns shellAvailable / shellUnavailableReason metadata instead of throwing.
• agent-core: ToolManager omits the Bash tool when the shell is unavailable; the system prompt explains the Bash tool is unavailable and to use the built-in file tools. Removed the now-dead KaosShellNotFoundError, ErrorCodes.SHELL_GIT_BASH_NOT_FOUND, and the core-impl catch that translated them.

Unified system-dependency check (the core of #291)

• New apps/kimi-code/src/cli/system-deps/: a declarative registry (single source of truth: purpose, required/optional, auto-bootstrap, fallback, fix hint, warning policy), a pure check (evaluateDependencies), and a report renderer.
• Startup now warns when fd is missing outside a git repository (inside one, the git ls-files fallback keeps it quiet) or when the shell is unavailable. /status reports the health of all three. fd absence is no longer silent.
• node-sdk: KimiHarness.getEnvironment() exposes the resolved environment over the RPC seam so the check reads the core's single source of truth instead of re-probing.

Docs

• Declared the system dependencies and their degradation behavior in getting-started (en/zh) and tools.md (en/zh).

Checklist

• I have read the CONTRIBUTING document.
• I have linked a related issue, or explained the problem above.
• I have added tests that prove my feature works.
• Ran gen-changesets skill, or this PR needs no changeset. (changeset added)
• Ran gen-docs skill, or this PR needs no doc update. (docs updated)

Validation

Verified before (baseline green) and after each layer:

• corepack pnpm exec vitest run — 5176 passed / 25 skipped (opt-in e2e) / 2 todo, zero failures.
• corepack pnpm run build:packages — exit 0 (kaos → agent-core → node-sdk compile).
• corepack pnpm --filter @moonshot-ai/kimi-code run typecheck — exit 0.
• corepack pnpm exec oxlint --type-aware on changed files — 0 warnings, 0 errors.
• Real end-to-end (code-external): on a host with fd absent and rg present, ran the real detectEnvironment(win32, no bash) → returns shellAvailable=false without throwing; a real KimiHarness.getEnvironment() round-trip succeeds; the unified check correctly produces no warning for fd inside a git repo, a warning outside one, and reports rg/shell health.

New tests: Windows shell detection (kaos), Bash-tool omission + unavailable-shell prompt rendering (agent-core), the dependency decision matrix and renderer (system-deps), and startup-warning scenarios (TUI).

[changeset-bot]

🦋 Changeset detected

Latest commit: 023a33f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@moonshot-ai/agent-core	Minor
@moonshot-ai/kaos	Minor
@moonshot-ai/kimi-code-sdk	Minor
@moonshot-ai/kimi-code	Minor
@moonshot-ai/migration-legacy	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1e58592bb9

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[fancyboi999]

Heads-up on CI: pnpm typecheck currently reports one error in apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts — that fixture is not touched by this PR and the failure is pre-existing on main, introduced by #285 (it added a required kind to BackgroundTaskInfo but missed this one fixture). I split the one-line fix into #309 to keep this PR surgical. Once #309 lands I'll rebase this branch and the typecheck will be green. Every file changed by this PR typechecks cleanly.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6db4699d94

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[fancyboi999]

Update: rebased onto latest main. The earlier pnpm typecheck failure I flagged was the pre-existing one from #285 — it's now fixed on main by #307, so this branch picks that up and typechecks cleanly. I've closed my redundant #309 (it duplicated #307). No code changes in this push, just the rebase.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ecdad282ab

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[fancyboi999]

Hi @liruifengv 👋 — a gentle ping on this one, no rush at all.

This PR takes #291 ("check system dependencies at startup") and unifies the ripgrep / fd / shell handling into one declarative registry + a startup check, and along the way fixes the #259 Windows "no Git Bash → CLI crashes at startup" issue (the CLI now starts and just omits the Bash tool).

A few questions so I can make this easy to review (or close cleanly if it's not the right fit):

1. Direction / scope — is this the kind of solution you'd want for 启动时应正确检查系统依赖 #291, or would you prefer a smaller / different approach? I'm very happy to trim scope or split it up.
2. Roadmap fit — is a change like this in scope for the current milestone, or is it out of the planned version range right now? Totally fine if it needs to wait.
3. Anything to fix — is there anything specific you'd like changed before it could be considered?
4. CI — as a first-time contributor my Actions runs are gated; whenever convenient, a maintainer "Approve and run" would let the checks show green.

Status: rebased on latest main (0.8.0), green locally (full test suite + typecheck + lint), changeset included, and all Codex review threads resolved. Thanks for the great project — happy to adjust based on your guidance. 🙏