ladder-mcp 1.1.2 → 1.1.4

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.4] - 2026-06-28
+
+Make the live-progress line worth watching.
+
+### Changed
+
+- Live progress now shows a readable content **preview** of the streamed
+  `message`/`thought` text (whitespace collapsed, code-point-safe truncation with
+  an ellipsis) instead of a bare `(N chars)` counter.
+- Progress emission is throttled to at most one update per ~1.2s, so the single
+  progress line stops flickering and each line stays readable. `tool_call`,
+  `tool_update`, and `plan` events remain immediate and flush any pending preview
+  first to preserve order.
+- The two per-transport coalescers (CLI and ACP) are unified into one shared
+  `createProgressCoalescer` in `src/progress.ts`; the duplicated `COALESCE_*`
+  constants are gone.
+
+### Notes
+
+- Kimi CLI 0.20.1 does not stream thinking to stderr during `-p` runs, so live
+  `thought` progress is not available on the CLI transport (documented in code).
+  The ACP transport already emits `thought`, which now gets the preview treatment.
+
+## [1.1.3] - 2026-06-28
+
+Bugfix: analysis-mode `kimi_code` was broken against Kimi CLI 0.20.1.
+
+### Fixed
+
+- `kimi_code` without `edit: true` (the default analysis mode) crashed against
+  Kimi CLI 0.20.1 with `Cannot combine --prompt with --plan`. `buildKimiArgs` no
+  longer passes `--plan` in `-p` prompt mode (the CLI rejects it, along with
+  `--auto`/`-y`).
+
+### Changed
+
+- Because Kimi 0.20.1 has no `-p`-compatible read-only flag, the `edit: false`
+  analysis-only contract is now enforced at the prompt level: `runKimi` prepends
+  a read-only guard (`applyReadOnlyGuard`) when `edit` is not `true`. This is
+  advisory (the model is instructed not to edit) rather than a hard CLI
+  guarantee; the `edit` parameter description documents the change.
+
 ## [1.1.2] - 2026-06-28
 
 Live-progress and cancellation reliability for `kimi_code`.

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.1.2** ([npm](https://www.npmjs.com/package/ladder-mcp)).
+> Status: **v1.1.4** ([npm](https://www.npmjs.com/package/ladder-mcp)).
 > Supported platform is **Windows 11 only**.
 
 ## Requirements
@@ -72,7 +72,7 @@ npm run build      # compiles src/ -> dist/ (tests excluded)
 Quick checks:
 
 ```bash
-npm test           # vitest (153 tests)
+npm test           # vitest (163 tests)
 npm run typecheck  # tsc --noEmit (incl. tests)
 npm run dev        # run the server from source via tsx
 ```

package/dist/index.js

@@ -61,7 +61,7 @@ server.tool('kimi_code', 'Agentic work in a repository: analyze and edit files.
     work_dir: z.string().describe('Absolute path to the codebase root directory.'),
     session_id: z.string().optional().describe('Explicit Kimi session id to resume.'),
     new_session: z.boolean().optional().describe('Start fresh instead of continuing the last session. Default: false.'),
-    edit: z.boolean().optional().describe('Allow file modifications. Default: false (analysis-only intent).'),
+    edit: z.boolean().optional().describe('Allow file modifications. Default: false (analysis-only intent). On Kimi 0.20.1 this is prompt-enforced (advisory): when false/omitted the prompt is prefixed with a read-only guard, but the CLI itself provides no hard read-only flag for -p mode.'),
     background: z.boolean().optional().describe('Track as a long-running background task. Every progress event (including each action) is appended to the task log, readable via kimi_tasks — the full accumulating transcript, unlike the single overwriting live-progress line of a foreground call.'),
     transport: z.enum(['cli', 'acp']).optional().describe("How the server drives Kimi. Both edit files and resume sessions; they differ in robustness and live-progress detail. 'cli' (default): one-shot process, most robust on Windows, but live progress is coarse — only streaming-output volume, no per-action lines. 'acp': persistent JSON-RPC session that emits granular live progress (tool calls, plan steps) and supports interactive permission prompts, but is heavier and more fragile. Prefer 'cli' for plain codegen/analysis; choose 'acp' when you need to watch each action live or handle mid-run prompts."),
     session_mode: z.enum(['new', 'load', 'resume']).optional().describe("ACP session mode when transport='acp'. Default: inferred from session_id/new_session."),

package/dist/kimi-runner.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import * as path from 'node:path';
 import { clampTimeout } from './transports/acp.js';
 import { buildKimiEnv, resolveKimiPaths } from './environment.js';
-import { createStallWatchdog, makeEvent } from './progress.js';
+import { createProgressCoalescer, createStallWatchdog } from './progress.js';
 const MAX_CAPTURE_CHARS = 16 * 1024 * 1024;
 const MAX_FAILURE_STREAM_CHARS = 2_000;
 // Append to a captured stream while enforcing a hard ceiling so a runaway CLI cannot
@@ -22,11 +22,21 @@ export function buildKimiArgs(config) {
     else if (config.continueLast) {
         args.push('-C');
     }
-    if (config.edit !== true) {
-        args.push('--plan');
-    }
+    // Kimi CLI 0.20.1 rejects combining --plan with -p/--prompt (non-interactive
+    // prompt mode), and the other restriction flags (--auto, -y) are also
+    // incompatible. For edit:false / omitted edit we therefore pass no restriction
+    // flag and rely on the prompt/system to avoid edits.
     return args;
 }
+const READ_ONLY_GUARD = '[READ-ONLY ANALYSIS MODE] Do not create, modify, or delete any files, directories, or repository state. Only read, analyze, explain, and report.';
+// Prepends a read-only guard to the prompt when edit mode is not explicitly
+// enabled. Kimi CLI 0.20.1 has no -p-compatible read-only flag, so this is the
+// only available enforcement mechanism for the analysis-only contract.
+export function applyReadOnlyGuard(prompt, edit) {
+    if (edit === true)
+        return prompt;
+    return `${READ_ONLY_GUARD}\n\n${prompt}`;
+}
 function contentToText(content) {
     if (typeof content === 'string')
         return content;
@@ -156,32 +166,6 @@ export function truncateAtBoundary(text, maxChars) {
     const cutPoint = Math.max(slice.lastIndexOf('\n## '), slice.lastIndexOf('\n\n'), Math.floor(maxChars * 0.8));
     return `${slice.slice(0, cutPoint).trimEnd()}\n\n---\nOutput truncated (${text.length.toLocaleString()} chars exceeded ${maxChars.toLocaleString()} char budget). Use kimi_resume with the same session for follow-up questions.`;
 }
-const COALESCE_MS = 750;
-const COALESCE_CHARS = 400;
-function createStreamCoalescer(reporter) {
-    let count = 0;
-    let timer;
-    const flush = () => {
-        if (timer) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-        if (count > 0) {
-            reporter(makeEvent('message', `streaming output… (${count} chars)`));
-            count = 0;
-        }
-    };
-    const add = (text) => {
-        count += text.length;
-        if (count >= COALESCE_CHARS) {
-            flush();
-        }
-        else if (!timer) {
-            timer = setTimeout(flush, COALESCE_MS);
-        }
-    };
-    return { add, flush, stop: flush };
-}
 function killProcessTree(pid) {
     if (!pid)
         return;
@@ -213,9 +197,10 @@ export function runKimi(config) {
             error: 'Kimi cancelled',
         });
     }
+    const guardedPrompt = applyReadOnlyGuard(config.prompt, config.edit);
     return new Promise((resolve) => {
         let settled = false;
-        const proc = spawn(paths.binaryPath, buildKimiArgs(config), {
+        const proc = spawn(paths.binaryPath, buildKimiArgs({ ...config, prompt: guardedPrompt }), {
             env: buildKimiEnv(),
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
@@ -225,7 +210,7 @@ export function runKimi(config) {
         let stderr = '';
         let timedOut = false;
         let streamBuffer = '';
-        const coalescer = config.onProgress ? createStreamCoalescer(config.onProgress) : undefined;
+        const coalescer = config.onProgress ? createProgressCoalescer(config.onProgress) : undefined;
         const watchdog = config.onProgress ? createStallWatchdog(config.onProgress) : undefined;
         let onAbort;
         const finish = (result) => {
@@ -233,7 +218,6 @@ export function runKimi(config) {
                 return;
             settled = true;
             clearTimeout(timer);
-            coalescer?.flush();
             coalescer?.stop();
             watchdog?.stop();
             config.signal?.removeEventListener('abort', onAbort);
@@ -275,18 +259,18 @@ export function runKimi(config) {
                     if (record.type === 'plan') {
                         const text = contentToText(record.content).trim();
                         if (text)
-                            config.onProgress(makeEvent('plan', text));
+                            coalescer?.add('plan', text);
                     }
                     else if (record.role === 'assistant') {
                         const text = contentToText(record.content);
                         if (text.trim())
-                            coalescer?.add(text);
+                            coalescer?.add('message', text);
                         const toolCalls = record.tool_calls;
                         if (Array.isArray(toolCalls)) {
                             for (const toolCall of toolCalls) {
                                 const toolText = formatCliToolCall(toolCall);
                                 if (toolText)
-                                    config.onProgress(makeEvent('tool_call', toolText));
+                                    coalescer?.add('tool_call', toolText);
                             }
                         }
                     }
@@ -296,7 +280,12 @@ export function runKimi(config) {
                 }
             }
         });
-        proc.stderr?.on('data', (chunk) => { stderr = appendCapped(stderr, chunk.toString('utf-8'), MAX_CAPTURE_CHARS); });
+        proc.stderr?.on('data', (chunk) => {
+            // Kimi CLI 0.20.1 does not stream thinking to stderr incrementally during a
+            // -p run; stderr is empty until process exit. We therefore do not emit live
+            // `thought` progress events here and keep the existing end-of-run capture.
+            stderr = appendCapped(stderr, chunk.toString('utf-8'), MAX_CAPTURE_CHARS);
+        });
         proc.on('error', (err) => {
             finish({ ok: false, text: '', error: err instanceof Error ? err.message : String(err) });
         });

package/dist/progress.js

@@ -21,6 +21,77 @@ export function makeEvent(kind, text) {
 export function formatProgressLine(event) {
     return `[${clockFromIso(event.at)}] ${KIND_GLYPH[event.kind]} ${event.kind}: ${event.text}`;
 }
+export const DEFAULT_DWELL_MS = 1_200;
+export const PREVIEW_MAX_CHARS = 90;
+export const TAIL_MAX_CHARS = 120;
+function sliceByCodePoints(text, maxChars) {
+    return [...text].slice(-maxChars).join('');
+}
+function collapseWhitespace(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function formatPreview(tail, maxChars) {
+    const preview = collapseWhitespace(tail);
+    if (preview.length === 0)
+        return '';
+    const codePoints = [...preview];
+    if (codePoints.length <= maxChars)
+        return preview;
+    return `…${codePoints.slice(-maxChars).join('').trimStart()}`;
+}
+// Coalesces high-frequency `message`/`thought` streaming text into a single
+// watchable preview line, emitted at most once per `dwellMs`. Action events
+// (`tool_call`, `tool_update`, `plan`) are forwarded immediately, after flushing
+// any pending preview so ordering is preserved.
+export function createProgressCoalescer(reporter, options) {
+    const dwellMs = options?.dwellMs ?? DEFAULT_DWELL_MS;
+    const previewMaxChars = options?.previewMaxChars ?? PREVIEW_MAX_CHARS;
+    const tailMaxChars = options?.tailMaxChars ?? TAIL_MAX_CHARS;
+    const tails = { message: '', thought: '' };
+    let timer;
+    const emitTails = () => {
+        for (const kind of ['message', 'thought']) {
+            const tail = tails[kind];
+            if (!tail)
+                continue;
+            const text = formatPreview(tail, previewMaxChars);
+            tails[kind] = '';
+            if (text)
+                reporter(makeEvent(kind, text));
+        }
+    };
+    const flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        emitTails();
+    };
+    const schedule = () => {
+        if (timer)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            emitTails();
+        }, dwellMs);
+        timer.unref?.();
+    };
+    const appendTail = (kind, text) => {
+        tails[kind] = sliceByCodePoints(tails[kind] + text, tailMaxChars);
+    };
+    const add = (kind, text) => {
+        if (kind === 'tool_call' || kind === 'tool_update' || kind === 'plan') {
+            flush();
+            reporter(makeEvent(kind, text));
+            return;
+        }
+        if (kind === 'message' || kind === 'thought') {
+            appendTail(kind, text);
+            schedule();
+        }
+    };
+    return { add, flush, stop: flush };
+}
 export function createStallWatchdog(reporter, stallMs = DEFAULT_STALL_MS) {
     let timer;
     let stopped = false;

package/dist/transports/acp.js

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { buildKimiEnv, resolveKimiPaths } from '../environment.js';
 import { VERSION } from '../version.js';
-import { createStallWatchdog, makeEvent } from '../progress.js';
+import { createProgressCoalescer, createStallWatchdog } from '../progress.js';
 const MAX_ACP_FRAME_BYTES = 8 * 1024 * 1024;
 const MAX_ACP_HEADER_BYTES = 16 * 1024;
 const MAX_ACP_METADATA_BYTES = 100 * 1024;
@@ -551,43 +551,6 @@ function extractSessionId(value, fallback) {
     }
     return fallback;
 }
-const COALESCE_MS = 750;
-const COALESCE_CHARS = 400;
-// Streams of message/thought tokens are far too chatty to forward one event per
-// chunk. Accumulate character counts and emit a single summarized event at most
-// every COALESCE_MS or whenever the accumulated text exceeds COALESCE_CHARS.
-// tool_call / tool_call_update / plan events are forwarded immediately.
-function createCoalescingReporter(reporter) {
-    const counts = { message: 0, thought: 0 };
-    let timer;
-    const flush = () => {
-        if (timer) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-        for (const kind of ['message', 'thought']) {
-            if (counts[kind] > 0) {
-                reporter(makeEvent(kind, `${kind === 'message' ? 'streaming output' : 'thinking'}… (${counts[kind]} chars)`));
-                counts[kind] = 0;
-            }
-        }
-    };
-    const add = (kind, text) => {
-        if (kind !== 'message' && kind !== 'thought') {
-            flush();
-            reporter(makeEvent(kind, text));
-            return;
-        }
-        counts[kind] += text.length;
-        if (counts[kind] >= COALESCE_CHARS) {
-            flush();
-        }
-        else if (!timer) {
-            timer = setTimeout(flush, COALESCE_MS);
-        }
-    };
-    return { add, flush, stop: flush };
-}
 export async function runAcpPrompt(options) {
     if (options.signal?.aborted)
         return { ok: false, text: '', error: 'ACP prompt was aborted before start.' };
@@ -605,7 +568,7 @@ export async function runAcpPrompt(options) {
     let watchdog;
     let onNotification;
     if (options.onProgress) {
-        coalescer = createCoalescingReporter(options.onProgress);
+        coalescer = createProgressCoalescer(options.onProgress);
         watchdog = createStallWatchdog(options.onProgress);
         onNotification = (message) => {
             watchdog?.ping();
@@ -676,7 +639,6 @@ export async function runAcpPrompt(options) {
     finally {
         if (onNotification)
             client.off('notification', onNotification);
-        coalescer?.flush();
         coalescer?.stop();
         watchdog?.stop();
         options.signal?.removeEventListener('abort', abort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ladder-mcp",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Windows-first MCP bridge for Kimi Code CLI v24",
   "license": "MIT",
   "type": "module",