ladder-mcp 1.0.2 → 1.1.2

package/CHANGELOG.md

@@ -1,115 +1,242 @@
-# Changelog
-
-All notable changes to Ladder_mcp are documented here. Format loosely follows
-[Keep a Changelog](https://keepachangelog.com/); this project uses
-[Semantic Versioning](https://semver.org/).
-
-## [1.0.2] - 2026-06-28
-
-Security and robustness patch release addressing findings from an external
-adversarial review of `src/`.
-
-### Fixed
-
-- **`isAuthenticated` false-positive on corrupt credentials** (`environment.ts`):
-  a credentials file that exists but is unreadable or invalid JSON was previously
-  reported as authenticated. It now fails closed and returns `false`, satisfying
-  NFR-5 honest diagnostics.
-- **Unbounded `stdout`/`stderr` capture in `runKimi`** (`kimi-runner.ts`): CLI
-  output is now accumulated through `appendCapped` with a hard ceiling
-  (`MAX_CAPTURE_CHARS`), preventing memory exhaustion on runaway output.
-- **Unvalidated `max_output_tokens` and `work_dir`** (`input-validation.ts`):
-  non-finite, zero, or negative token counts are clamped to the default budget;
-  `work_dir` must be an absolute path to an existing directory before Kimi is
-  spawned. Used by `kimi_analyze` and `kimi_resume`.
-
-### Security
-
-- **Arbitrary command persisted to `mcp.json`** (`kimi-mcp-config.ts`):
-  `kimi_generate_mcp_config` now validates `command` against an allow-list of
-  `node`, `npx`, or an absolute path to an existing file. Other values (e.g.
-  `powershell`) are rejected and nothing is written.
-
-## [1.0.1] - 2026-06-28
-
-Bug-fix release. Issues found by exercising all 20 tools live against a real
-Kimi CLI (the mock-only unit tests had missed them).
-
-### Fixed
-
-- **ACP responses lost spaces** (`kimi_chat`): streamed token chunks were each
-  trimmed and newline-joined, so `"Two plus two equals four."` came back as
-  `"Twoplustwoequalsfour."`. Text fragments are now concatenated as-is and only
-  the final string is trimmed. (CLI tools `kimi_analyze`/`kimi_resume` were never
-  affected.)
-- **`kimi_export_session` silently no-op'd** while reporting `ok: true`: when no
-  session id was given, `kimi export` defaults to the most recent session and asks
-  `Export previous session …? [Y/n]` — a prompt that `-y` does not suppress in Kimi
-  CLI 0.20.1, so with stdin closed it exited 0 without writing. The tool now
-  resolves the most recent session id itself and passes it explicitly (skipping the
-  prompt), always passes `-y`, and verifies the output file exists before reporting
-  success.
-
-### Changed
-
-- `kimi_acp_sessions` now accepts `limit` (default 20) and `work_dir` filters,
-  for parity with `kimi_list_sessions`; previously it dumped every ACP session
-  across all projects in one response.
-
-## [1.0.0] - 2026-06-27
-
-First release. Windows-first MCP bridge for Kimi Code CLI v24, rebuilt in a
-fresh `./src` application (package `ladder-mcp`). Logic is ported from the
-read-only `kimi-code-mcp/` reference; the legacy `CacheManager`/warmup layer is
-not carried over.
-
-### Added — v1 core (Epics 1-3)
-
-- Robust environment resolver (`environment.ts`): discovers `kimi.exe` via PATH
-  and `~/.kimi-code/bin/`, resolves the `~/.kimi-code/` catalog, credentials and
-  version with no hardcoded POSIX paths; no silent fallback to legacy `~/.kimi/`.
-- CLI adapter (`kimi-runner.ts`): correct Kimi CLI v24 arguments
-  (`-p`, `--output-format stream-json`, `-S`, `-C`, `--auto`), `stream-json`
-  parsing, native session resume, Windows process-tree termination on timeout.
-- API adapter (`kimi-api.ts`): contextless `kimi_query` / `kimi_verify` reading
-  key/endpoint from `KIMICODE_API_KEY` or `~/.kimi-code/config.toml`.
-- Six v1 MCP tools: `kimi_analyze`, `kimi_query`, `kimi_verify`, `kimi_resume`,
-  `kimi_list_sessions`, `kimi_status`.
-
-### Added — vNext expansion (Epic 4)
-
-- **CLI admin & capabilities** (`transports/cli-admin.ts`): `kimi_capabilities`,
-  `kimi_doctor`, `kimi_provider_list`, `kimi_export_session`,
-  `kimi_visualize_session`. Export requires an explicit `output_path`, is
-  confined to the working directory, and excludes the global diagnostic log by
-  default.
-- **ACP MVP over stdio** (`transports/acp.ts`): JSON-RPC client for `kimi acp`
-  with newline-delimited and `Content-Length` framing; `kimi_chat`,
-  `kimi_acp_sessions`, `kimi_cancel`.
-- **Background task lifecycle** (`task-store.ts`): in-process task store with
-  `kimi_chat background=true`, `kimi_task_status`, `kimi_task_output`,
-  `kimi_task_cancel`.
-- **Kimi-hosted MCP config + read-only desktop probes**
-  (`kimi-mcp-config.ts`, `desktop-work.ts`): `kimi_generate_mcp_config`,
-  `kimi_desktop_status`, `kimi_budget_probe`. Desktop access is
-  experimental/read-only — no token-store reads, no web-auth replay, no desktop
-  Work task submission.
-
-### Security & robustness (adversarial review)
-
-Hardened against path traversal/TOCTOU on export, writes under the read-only
-reference tree, unbounded ACP frame/task memory, process crash on malformed ACP
-JSON, non-idempotent task cancellation, and UTF-8 byte-boundary truncation.
-
-The remaining lower-risk review findings (W1-W12) were also resolved before
-release: raw ACP response-id matching (no `NaN` coercion), bounded ACP update
-buffer, clamped ACP request timeouts, smaller buffers for parallel capability
-probes, a timeout around task cancel hooks, a size cap on the desktop status
-probe body, validated `kimi_chat` timeout input, and `kimi_cancel` rejecting
-ambiguous task_id+session_id calls. Regression tests added (49 total).
-
-### Known limitations
-
-- Windows 11 only (NFR-1); POSIX branches are not a target.
-
-[1.0.0]: https://semver.org/
+# Changelog
+
+All notable changes to Ladder_mcp are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses
+[Semantic Versioning](https://semver.org/).
+
+## [1.1.2] - 2026-06-28
+
+Live-progress and cancellation reliability for `kimi_code`.
+
+### Added
+
+- The CLI transport now surfaces the running action: `stream-json` `tool_calls`
+  records emit immediate `tool_call` progress events (e.g. `Read src/types.ts`)
+  and `plan` records emit `plan` events, matching the ACP transport. A CLI job
+  no longer looks idle while it works.
+
+### Fixed
+
+- Cancelling a `kimi_code` call now actually kills the underlying `kimi.exe`
+  process in every mode (foreground CLI, background CLI, foreground ACP).
+  Previously only background ACP honored cancellation; the others leaked the
+  child until the timeout fired. `runKimi` accepts an `AbortSignal`, skips
+  spawning when already aborted, and kills the process tree on abort.
+- The ACP client is hardened against a `close()`-before-`start()` race, and an
+  aborted ACP run now reports `Kimi cancelled` instead of a raw exit code.
+
+### Changed
+
+- `kimi_code`'s `transport` and `background` parameter descriptions now explain
+  the cli/acp trade-off and where to read the full progress log, so agents pick
+  a mode deliberately.
+
+## [1.1.0] - 2026-06-28
+
+Breaking tool-surface redesign: the MCP tool list is now an intent-first set of
+6 default tools, with niche/admin features gated behind `LADDER_EXPERIMENTAL=1`.
+
+### Changed
+
+- `src/index.ts` now registers 6 default tools: `kimi_code`, `kimi_ask`,
+  `kimi_sessions`, `kimi_tasks`, `kimi_status`, `kimi_setup`.
+- `kimi_code` folds `kimi_analyze`, `kimi_resume`, and `kimi_chat`. It defaults to
+  `transport='cli'` (validated `work_dir` via `validateWorkDir`) and supports
+  `edit`, `background`, `session_id`, and `new_session`.
+- `kimi_ask` folds `kimi_query` and `kimi_verify`; providing `context` switches to
+  verify mode.
+- `kimi_sessions` folds `kimi_list_sessions` and `kimi_acp_sessions` behind the
+  `source` parameter (`cli`, `acp`, `all`).
+- `kimi_tasks` action-dispatches `status`, `output`, and `cancel` (including ACP
+  session cancellation via `session_id`).
+- `kimi_status` detail-switches between `basic` and `full`; `full` adds
+  capabilities, doctor, and provider list. `isError` is now true whenever a
+  remediation is required.
+- `kimi_setup` renames `kimi_generate_mcp_config` and resolves the default server
+  command from `process.execPath`.
+
+### Removed
+
+The 20-tool default surface is replaced by the 6 tools above. The following tool
+names are no longer registered by default:
+
+- `kimi_analyze`, `kimi_resume`, `kimi_chat`
+- `kimi_query`, `kimi_verify`
+- `kimi_list_sessions`, `kimi_acp_sessions`
+- `kimi_task_status`, `kimi_task_output`, `kimi_task_cancel`, `kimi_cancel`
+- `kimi_capabilities`, `kimi_doctor`, `kimi_provider_list`
+- `kimi_generate_mcp_config`
+
+### Migration
+
+| Old tool | New |
+|---|---|
+| `kimi_analyze` | `kimi_code` (edit=false) |
+| `kimi_resume` | `kimi_code` (session_id set) |
+| `kimi_chat` | `kimi_code` (transport='acp') |
+| `kimi_query` | `kimi_ask` |
+| `kimi_verify` | `kimi_ask` (context/role set) |
+| `kimi_list_sessions` | `kimi_sessions` (source='cli') |
+| `kimi_acp_sessions` | `kimi_sessions` (source='acp') |
+| `kimi_task_status` | `kimi_tasks` (action='status') |
+| `kimi_task_output` | `kimi_tasks` (action='output') |
+| `kimi_task_cancel` | `kimi_tasks` (action='cancel') |
+| `kimi_cancel` | `kimi_tasks` (action='cancel', task_id or session_id) |
+| `kimi_status` | `kimi_status` |
+| `kimi_capabilities` | `kimi_status` (detail='full') |
+| `kimi_doctor` | `kimi_status` (detail='full') |
+| `kimi_provider_list` | `kimi_status` (detail='full') |
+| `kimi_generate_mcp_config` | `kimi_setup` |
+| `kimi_export_session` | experimental (unchanged name) |
+| `kimi_visualize_session` | experimental |
+| `kimi_desktop_status` | experimental |
+| `kimi_budget_probe` | experimental |
+
+The 4 experimental tools (`kimi_export_session`, `kimi_visualize_session`,
+`kimi_desktop_status`, `kimi_budget_probe`) now register only when
+`process.env.LADDER_EXPERIMENTAL === '1'`.
+
+### Added
+
+- **Bidirectional ACP transport** (`transports/acp.ts`): the bridge now answers the
+  agent's client-bound JSON-RPC requests, so file edits and permission flows over
+  ACP complete instead of hanging. Includes auto-approved `session/request_permission`
+  and a `fs/read_text_file`/`fs/write_text_file`/`fs/read_directory` proxy.
+- **Live-progress visibility**: long-running `kimi_code` work surfaces progress —
+  background tasks grow a timestamped log, foreground calls emit MCP
+  `notifications/progress`, and a stall watchdog flags silent hangs. Token streams
+  are coalesced so the log is readable.
+- **Single-source versioning** (`version.ts`) read from `package.json`, plus
+  `release:patch/minor/major` scripts and a `preversion` typecheck+test gate.
+
+### Security
+
+- **ACP fs proxy is sandboxed** to the session `work_dir` with realpath-based
+  containment (blocks symlink/junction escape, case-folding bypass, drive-relative
+  and UNC paths); fails closed when the work dir is unset. Permission auto-approve
+  fails closed when no single-use option is offered. File reads are size-capped.
+- **`assertSafeCommand`** (`kimi-mcp-config.ts`) rejects PATH-resolved bare
+  `node`/`npx`, accepting only `process.execPath` or an absolute existing file;
+  `assertWritableProjectTarget` uses realpath containment instead of substring match.
+
+### Fixed
+
+- Process-tree termination on Windows (`taskkill /T /F`) for ACP close/cancel and
+  `runKimi` timeout, with awaited exit so callers don't race a dying tree.
+- Timeouts in `runKimi` and `runKimiApi` are clamped; `timeout_ms` tool args must be
+  positive integers.
+- `parseKimiStreamJson` tolerates leading whitespace; resume-hint extraction is
+  fuzzier; `contentToText` keeps placeholders for non-text parts.
+- `task-store` no longer appends to terminal tasks; `runKimi` preserves both stdout
+  and stderr on failure; disk-discovered sessions recover their real `work_dir`.
+- Capped the `readBodyCapped` non-streaming fallback (`desktop-work.ts`).
+
+## [1.0.2] - 2026-06-28
+
+Security and robustness patch release addressing findings from an external
+adversarial review of `src/`.
+
+### Fixed
+
+- **`isAuthenticated` false-positive on corrupt credentials** (`environment.ts`):
+  a credentials file that exists but is unreadable or invalid JSON was previously
+  reported as authenticated. It now fails closed and returns `false`, satisfying
+  NFR-5 honest diagnostics.
+- **Unbounded `stdout`/`stderr` capture in `runKimi`** (`kimi-runner.ts`): CLI
+  output is now accumulated through `appendCapped` with a hard ceiling
+  (`MAX_CAPTURE_CHARS`), preventing memory exhaustion on runaway output.
+- **Unvalidated `max_output_tokens` and `work_dir`** (`input-validation.ts`):
+  non-finite, zero, or negative token counts are clamped to the default budget;
+  `work_dir` must be an absolute path to an existing directory before Kimi is
+  spawned. Used by `kimi_analyze` and `kimi_resume`.
+
+### Security
+
+- **Arbitrary command persisted to `mcp.json`** (`kimi-mcp-config.ts`):
+  `kimi_generate_mcp_config` now validates `command` against an allow-list of
+  `node`, `npx`, or an absolute path to an existing file. Other values (e.g.
+  `powershell`) are rejected and nothing is written.
+
+## [1.0.1] - 2026-06-28
+
+Bug-fix release. Issues found by exercising all 20 tools live against a real
+Kimi CLI (the mock-only unit tests had missed them).
+
+### Fixed
+
+- **ACP responses lost spaces** (`kimi_chat`): streamed token chunks were each
+  trimmed and newline-joined, so `"Two plus two equals four."` came back as
+  `"Twoplustwoequalsfour."`. Text fragments are now concatenated as-is and only
+  the final string is trimmed. (CLI tools `kimi_analyze`/`kimi_resume` were never
+  affected.)
+- **`kimi_export_session` silently no-op'd** while reporting `ok: true`: when no
+  session id was given, `kimi export` defaults to the most recent session and asks
+  `Export previous session …? [Y/n]` — a prompt that `-y` does not suppress in Kimi
+  CLI 0.20.1, so with stdin closed it exited 0 without writing. The tool now
+  resolves the most recent session id itself and passes it explicitly (skipping the
+  prompt), always passes `-y`, and verifies the output file exists before reporting
+  success.
+
+### Changed
+
+- `kimi_acp_sessions` now accepts `limit` (default 20) and `work_dir` filters,
+  for parity with `kimi_list_sessions`; previously it dumped every ACP session
+  across all projects in one response.
+
+## [1.0.0] - 2026-06-27
+
+First release. Windows-first MCP bridge for Kimi Code CLI v24, rebuilt in a
+fresh `./src` application (package `ladder-mcp`). Logic is ported from the
+read-only `kimi-code-mcp/` reference; the legacy `CacheManager`/warmup layer is
+not carried over.
+
+### Added — v1 core (Epics 1-3)
+
+- Robust environment resolver (`environment.ts`): discovers `kimi.exe` via PATH
+  and `~/.kimi-code/bin/`, resolves the `~/.kimi-code/` catalog, credentials and
+  version with no hardcoded POSIX paths; no silent fallback to legacy `~/.kimi/`.
+- CLI adapter (`kimi-runner.ts`): correct Kimi CLI v24 arguments
+  (`-p`, `--output-format stream-json`, `-S`, `-C`, `--auto`), `stream-json`
+  parsing, native session resume, Windows process-tree termination on timeout.
+- API adapter (`kimi-api.ts`): contextless `kimi_query` / `kimi_verify` reading
+  key/endpoint from `KIMICODE_API_KEY` or `~/.kimi-code/config.toml`.
+- Six v1 MCP tools: `kimi_analyze`, `kimi_query`, `kimi_verify`, `kimi_resume`,
+  `kimi_list_sessions`, `kimi_status`.
+
+### Added — vNext expansion (Epic 4)
+
+- **CLI admin & capabilities** (`transports/cli-admin.ts`): `kimi_capabilities`,
+  `kimi_doctor`, `kimi_provider_list`, `kimi_export_session`,
+  `kimi_visualize_session`. Export requires an explicit `output_path`, is
+  confined to the working directory, and excludes the global diagnostic log by
+  default.
+- **ACP MVP over stdio** (`transports/acp.ts`): JSON-RPC client for `kimi acp`
+  with newline-delimited and `Content-Length` framing; `kimi_chat`,
+  `kimi_acp_sessions`, `kimi_cancel`.
+- **Background task lifecycle** (`task-store.ts`): in-process task store with
+  `kimi_chat background=true`, `kimi_task_status`, `kimi_task_output`,
+  `kimi_task_cancel`.
+- **Kimi-hosted MCP config + read-only desktop probes**
+  (`kimi-mcp-config.ts`, `desktop-work.ts`): `kimi_generate_mcp_config`,
+  `kimi_desktop_status`, `kimi_budget_probe`. Desktop access is
+  experimental/read-only — no token-store reads, no web-auth replay, no desktop
+  Work task submission.
+
+### Security & robustness (adversarial review)
+
+Hardened against path traversal/TOCTOU on export, writes under the read-only
+reference tree, unbounded ACP frame/task memory, process crash on malformed ACP
+JSON, non-idempotent task cancellation, and UTF-8 byte-boundary truncation.
+
+The remaining lower-risk review findings (W1-W12) were also resolved before
+release: raw ACP response-id matching (no `NaN` coercion), bounded ACP update
+buffer, clamped ACP request timeouts, smaller buffers for parallel capability
+probes, a timeout around task cancel hooks, a size cap on the desktop status
+probe body, validated `kimi_chat` timeout input, and `kimi_cancel` rejecting
+ambiguous task_id+session_id calls. Regression tests added (49 total).
+
+### Known limitations
+
+- Windows 11 only (NFR-1); POSIX branches are not a target.
+
+[1.0.0]: https://semver.org/

package/README.md

@@ -6,7 +6,7 @@ client like Claude Code can run codebase analysis, native sessions, API
 queries, ACP chat, background tasks, and CLI admin/diagnostics — all on Windows
 without hardcoded POSIX assumptions.
 
-> Status: **v1.0.1** ([npm](https://www.npmjs.com/package/ladder-mcp)).
+> Status: **v1.1.2** ([npm](https://www.npmjs.com/package/ladder-mcp)).
 > Supported platform is **Windows 11 only**.
 
 ## Requirements
@@ -19,7 +19,7 @@ without hardcoded POSIX assumptions.
 ## Quick start (from npm)
 
 You don't need to clone or build — the package is published on npm and your MCP
-client launches it via `npx`.
+client launches it via `npx`, or you can install the package directly.
 
 **Claude Code (one command):**
 
@@ -50,7 +50,16 @@ Then in Claude Code run `/mcp` (should show `kimi-code: connected`) and call
 Prefer a global install? `npm install -g ladder-mcp`, then use `ladder-mcp` as the
 command instead of `npx -y ladder-mcp`.
 
-To let Kimi Code itself host this server, use the `kimi_generate_mcp_config`
+Or install locally into your project:
+
+```bash
+npm install ladder-mcp
+```
+
+Then point your MCP config at `./node_modules/.bin/ladder-mcp` (or use
+`npx -y ladder-mcp`, which resolves the locally installed copy when available).
+
+To let Kimi Code itself host this server, use the `kimi_setup`
 tool to produce/merge a `.kimi-code/mcp.json` entry.
 
 ## Build from source (contributors)
@@ -63,26 +72,23 @@ npm run build      # compiles src/ -> dist/ (tests excluded)
 Quick checks:
 
 ```bash
-npm test           # vitest (50 tests)
+npm test           # vitest (153 tests)
 npm run typecheck  # tsc --noEmit (incl. tests)
 npm run dev        # run the server from source via tsx
 ```
 
 ## Tools
 
-**Core (v1)** — `kimi_analyze`, `kimi_query`, `kimi_verify`, `kimi_resume`,
-`kimi_list_sessions`, `kimi_status`
-
-**CLI admin & capabilities** — `kimi_capabilities`, `kimi_doctor`,
-`kimi_provider_list`, `kimi_export_session`, `kimi_visualize_session`
-
-**ACP (chat over stdio)** — `kimi_chat`, `kimi_acp_sessions`, `kimi_cancel`
+**Core (v1.1)** — `kimi_code`, `kimi_ask`, `kimi_sessions`, `kimi_tasks`,
+`kimi_status`, `kimi_setup`
 
-**Background tasks** — `kimi_task_status`, `kimi_task_output`, `kimi_task_cancel`
-(set `background=true` on `kimi_chat`)
+`kimi_code` supports both the native CLI transport (default) and the ACP
+JSON-RPC transport (`transport: 'acp'`); set `background=true` to track long
+work as a background task.
 
-**Kimi-hosted config & desktop (read-only)** — `kimi_generate_mcp_config`,
-`kimi_desktop_status`, `kimi_budget_probe`
+**Experimental (off by default)** — `kimi_export_session`,
+`kimi_visualize_session`, `kimi_desktop_status`, `kimi_budget_probe`. Enable
+with the environment variable `LADDER_EXPERIMENTAL=1`.
 
 ## Safety boundaries
 

package/dist/desktop-work.js

@@ -7,8 +7,16 @@ export const MAX_PROBE_BODY_BYTES = 256 * 1024;
 // The surrounding AbortController still bounds total time.
 export async function readBodyCapped(response) {
     const reader = response.body?.getReader();
-    if (!reader)
-        return { text: await response.text(), truncated: false };
+    if (!reader) {
+        // The body is not streamable; still cap the returned text so a non-streaming
+        // response cannot return an unbounded body.
+        const text = await response.text();
+        const bytes = Buffer.byteLength(text, 'utf-8');
+        if (bytes > MAX_PROBE_BODY_BYTES) {
+            return { text: Buffer.from(text, 'utf-8').subarray(0, MAX_PROBE_BODY_BYTES).toString('utf-8'), truncated: true };
+        }
+        return { text, truncated: false };
+    }
     const decoder = new TextDecoder();
     let text = '';
     let total = 0;