ladder-mcp 1.0.0

package/dist/transports/acp.js

@@ -0,0 +1,415 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { buildKimiEnv, resolveKimiPaths } from '../environment.js';
+const MAX_ACP_FRAME_BYTES = 8 * 1024 * 1024;
+const MAX_ACP_HEADER_BYTES = 16 * 1024;
+const MAX_ACP_METADATA_BYTES = 100 * 1024;
+const MAX_ACP_UPDATE_CHUNKS = 10_000;
+const DEFAULT_ACP_TIMEOUT_MS = 120_000;
+const CONTENT_LENGTH_PREFIX_BYTES = 'Content-Length:'.length;
+// Coerce an untrusted timeout into a usable positive duration. A zero/negative/NaN
+// value would otherwise make setTimeout fire (effectively) immediately and abort the
+// request before the peer can reply; fall back to a sane default in that case.
+export function clampTimeout(ms, fallback) {
+    return typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? ms : fallback;
+}
+// Locate the end of a header block, accepting both the canonical CRLF terminator
+// (`\r\n\r\n`) and a lenient LF-only terminator (`\n\n`). Returns the index of the
+// terminator and its byte length so the body offset can be computed correctly.
+// Without LF support, an LF-only `Content-Length` frame would buffer until the
+// header-size guard throws and tears down the whole client.
+function findHeaderEnd(buffer) {
+    const crlf = buffer.indexOf('\r\n\r\n');
+    const lf = buffer.indexOf('\n\n');
+    if (crlf < 0 && lf < 0)
+        return undefined;
+    if (crlf < 0)
+        return { end: lf, sep: 2 };
+    if (lf < 0)
+        return { end: crlf, sep: 4 };
+    return crlf <= lf ? { end: crlf, sep: 4 } : { end: lf, sep: 2 };
+}
+export function encodeAcpMessage(message) {
+    return Buffer.from(`${JSON.stringify(message)}\n`, 'utf-8');
+}
+export class AcpMessageParser {
+    buffer = Buffer.alloc(0);
+    recovered = [];
+    // Messages that were parsed successfully before `push` threw on a malformed frame.
+    // The caller drains these so valid frames batched in the same chunk as a bad one
+    // are still delivered before the connection is torn down.
+    takeRecovered() {
+        const recovered = this.recovered;
+        this.recovered = [];
+        return recovered;
+    }
+    push(chunk) {
+        this.buffer = Buffer.concat([this.buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        const messages = [];
+        try {
+            return this.parseFrames(messages);
+        }
+        catch (error) {
+            // Stash whatever parsed cleanly before the malformed frame so the caller can
+            // dispatch it; then rethrow to preserve the existing throw-on-malformed contract.
+            this.recovered = messages;
+            throw error;
+        }
+    }
+    parseFrames(messages) {
+        while (this.buffer.length > 0) {
+            const headerTerminator = findHeaderEnd(this.buffer);
+            if (headerTerminator) {
+                const { end: headerEnd, sep } = headerTerminator;
+                const header = this.buffer.slice(0, headerEnd).toString('ascii');
+                const lengthMatch = header.match(/^Content-Length:\s*(\d+)\s*$/im);
+                if (lengthMatch) {
+                    const bodyLength = Number(lengthMatch[1]);
+                    if (!Number.isSafeInteger(bodyLength) || bodyLength < 0 || bodyLength > MAX_ACP_FRAME_BYTES || String(bodyLength) !== lengthMatch[1]) {
+                        throw new Error(`Invalid ACP frame length: ${lengthMatch[1]}`);
+                    }
+                    const bodyStart = headerEnd + sep;
+                    const bodyEnd = bodyStart + bodyLength;
+                    if (this.buffer.length < bodyEnd)
+                        break;
+                    if (bodyLength > 0) {
+                        messages.push(parseJsonRpcMessage(this.buffer.slice(bodyStart, bodyEnd).toString('utf-8')));
+                    }
+                    this.buffer = this.buffer.slice(bodyEnd);
+                    continue;
+                }
+                // Not a valid Content-Length header block; fall through to newline handling up to the blank line.
+                const lineEnd = this.buffer.indexOf('\n');
+                if (lineEnd < 0)
+                    break;
+                const line = this.buffer.slice(0, lineEnd).toString('utf-8').trim();
+                this.buffer = this.buffer.slice(lineEnd + 1);
+                if (line.startsWith('{'))
+                    messages.push(parseJsonRpcLine(line));
+                continue;
+            }
+            const firstCrlf = this.buffer.indexOf('\r\n');
+            const looksLikeHeader = firstCrlf >= 0 && this.buffer.slice(0, firstCrlf).toString('ascii').match(/^Content-Length:/i);
+            // Only inspect the header-name prefix, not the whole (possibly multi-MB) buffer,
+            // to avoid O(n^2) re-encoding while a frame streams in many small chunks.
+            const partialHeader = this.buffer.slice(0, CONTENT_LENGTH_PREFIX_BYTES).toString('ascii').match(/^Content-Length:/i);
+            if (looksLikeHeader || partialHeader) {
+                if (this.buffer.length > MAX_ACP_HEADER_BYTES)
+                    throw new Error('ACP frame header is too large.');
+                break;
+            }
+            if (this.buffer.length > MAX_ACP_FRAME_BYTES) {
+                throw new Error('ACP newline frame is too large.');
+            }
+            const newline = this.buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = this.buffer.slice(0, newline).toString('utf-8').trim();
+            this.buffer = this.buffer.slice(newline + 1);
+            if (line.startsWith('{'))
+                messages.push(parseJsonRpcLine(line));
+        }
+        return messages;
+    }
+}
+function parseJsonRpcMessage(payload) {
+    const message = parseJsonRpcObject(payload);
+    if (message.jsonrpc !== '2.0') {
+        throw new Error('payload is not a JSON-RPC 2.0 message');
+    }
+    return message;
+}
+function parseJsonRpcLine(payload) {
+    return parseJsonRpcObject(payload);
+}
+function parseJsonRpcObject(payload) {
+    try {
+        if (payload.length === 0) {
+            throw new Error('empty ACP frame body');
+        }
+        const message = JSON.parse(payload);
+        if (!message || typeof message !== 'object' || Array.isArray(message)) {
+            throw new Error('payload is not a JSON-RPC object');
+        }
+        return message;
+    }
+    catch (error) {
+        throw new Error(`Malformed ACP JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function extractTextDeep(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (!value || typeof value !== 'object')
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap(extractTextDeep);
+    const record = value;
+    const direct = ['text', 'delta']
+        .map((key) => record[key])
+        .filter((item) => typeof item === 'string');
+    const nested = ['content', 'message', 'update', 'updates', 'result']
+        .flatMap((key) => extractTextDeep(record[key]));
+    return [...direct, ...nested];
+}
+export function extractAcpText(value) {
+    return extractTextDeep(value).map((part) => part.trim()).filter(Boolean).join('\n');
+}
+// Keep the trailing portion of `text` within a UTF-8 *byte* budget. Slicing by
+// String length (UTF-16 code units) under-counts multibyte characters, so the
+// result could still exceed `maxBytes` and could split a surrogate pair, corrupting
+// the leading character. This trims on a valid UTF-8 character boundary.
+export function truncateUtf8Tail(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf-8');
+    if (buf.length <= maxBytes)
+        return text;
+    let start = buf.length - maxBytes;
+    // Advance past any UTF-8 continuation byte (0b10xxxxxx) so we start on a char boundary.
+    while (start < buf.length && (buf[start] & 0xc0) === 0x80)
+        start++;
+    return buf.subarray(start).toString('utf-8');
+}
+export class AcpClient extends EventEmitter {
+    proc;
+    parser = new AcpMessageParser();
+    nextId = 1;
+    pending = new Map();
+    updates = [];
+    timeoutMs;
+    constructor(timeoutMs = DEFAULT_ACP_TIMEOUT_MS) {
+        super();
+        this.timeoutMs = clampTimeout(timeoutMs, DEFAULT_ACP_TIMEOUT_MS);
+    }
+    start() {
+        if (this.proc)
+            return;
+        const binary = resolveKimiPaths().binaryPath;
+        if (!binary)
+            throw new Error('Kimi CLI binary was not found on PATH or at ~/.kimi-code/bin/kimi.exe.');
+        this.proc = spawn(binary, ['acp'], {
+            env: buildKimiEnv(),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        this.proc.stdout.on('data', (chunk) => this.handleMessages(chunk));
+        this.proc.stderr.on('data', (chunk) => this.emit('stderr', chunk.toString('utf-8')));
+        this.proc.on('error', (error) => this.rejectAll(error));
+        this.proc.on('close', (code) => this.rejectAll(new Error(`kimi acp exited with code ${code}`)));
+    }
+    async request(method, params, timeoutMs = this.timeoutMs) {
+        this.start();
+        const id = this.nextId++;
+        const effectiveTimeout = clampTimeout(timeoutMs, this.timeoutMs);
+        const message = { jsonrpc: '2.0', id, method, params };
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`ACP request timed out: ${method}`));
+            }, effectiveTimeout);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        this.proc.stdin.write(encodeAcpMessage(message), (error) => {
+            if (error)
+                this.rejectPending(id, error instanceof Error ? error : new Error(String(error)));
+        });
+        return promise;
+    }
+    async initialize() {
+        return this.request('initialize', {
+            protocolVersion: 1,
+            clientInfo: { name: 'ladder-mcp', version: '1.0.0' },
+            capabilities: {},
+        }, 30_000);
+    }
+    listSessions() {
+        return this.request('session/list', {});
+    }
+    newSession(workDir) {
+        return this.request('session/new', { cwd: workDir ?? process.cwd(), mcpServers: [] });
+    }
+    loadSession(sessionId) {
+        return this.request('session/load', { sessionId });
+    }
+    resumeSession(sessionId) {
+        return this.request('session/resume', { sessionId });
+    }
+    prompt(sessionId, prompt, workDir) {
+        return this.request('session/prompt', {
+            sessionId,
+            cwd: workDir,
+            prompt: [{ type: 'text', text: prompt }],
+            text: prompt,
+        }, this.timeoutMs);
+    }
+    cancel(sessionId) {
+        return this.request('session/cancel', { sessionId }, 30_000);
+    }
+    getUpdateText() {
+        return this.updates.join('').trim();
+    }
+    close() {
+        if (!this.proc || this.proc.killed)
+            return;
+        this.proc.kill();
+    }
+    handleMessages(chunk) {
+        let messages;
+        try {
+            messages = this.parser.push(chunk);
+        }
+        catch (error) {
+            // Deliver any valid frames that parsed before the malformed one, then tear down.
+            // Without this, a single bad frame would discard legitimate responses batched in
+            // the same chunk and reject every pending request.
+            this.dispatch(this.parser.takeRecovered());
+            this.rejectAll(error instanceof Error ? error : new Error(String(error)));
+            this.close();
+            return;
+        }
+        this.dispatch(messages);
+    }
+    dispatch(messages) {
+        for (const message of messages) {
+            if (message.id !== undefined) {
+                // Look up by the raw id (number or string). Coercing to Number turned every
+                // non-numeric id into NaN, so string/UUID response ids never matched their
+                // pending request. Our own requests use numeric ids, so this is exact.
+                const pending = this.pending.get(message.id);
+                if (!pending)
+                    continue;
+                const id = message.id;
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                if (message.error) {
+                    const details = message.error.data ? `: ${JSON.stringify(message.error.data)}` : '';
+                    pending.reject(new Error(`${message.error.message ?? 'ACP request failed'}${details}`));
+                }
+                else
+                    pending.resolve(message.result);
+                continue;
+            }
+            if (message.method === 'session/update') {
+                const params = message.params;
+                if (params?.update?.sessionUpdate === 'agent_message_chunk') {
+                    const text = extractAcpText(params.update.content);
+                    if (text) {
+                        this.updates.push(text);
+                        // Bound retained streamed chunks so a very long session cannot grow the
+                        // array without limit; drop oldest chunks past the cap.
+                        if (this.updates.length > MAX_ACP_UPDATE_CHUNKS) {
+                            this.updates.splice(0, this.updates.length - MAX_ACP_UPDATE_CHUNKS);
+                        }
+                    }
+                }
+            }
+            this.emit('notification', message);
+        }
+    }
+    rejectAll(error) {
+        for (const [id, pending] of this.pending) {
+            this.pending.delete(id);
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+    }
+    rejectPending(id, error) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.reject(error);
+    }
+}
+function extractSessionId(value, fallback) {
+    if (!value || typeof value !== 'object')
+        return fallback;
+    const record = value;
+    for (const key of ['sessionId', 'session_id', 'id', 'session']) {
+        if (typeof record[key] === 'string')
+            return record[key];
+    }
+    return fallback;
+}
+export async function runAcpPrompt(options) {
+    if (options.signal?.aborted)
+        return { ok: false, text: '', error: 'ACP prompt was aborted before start.' };
+    const client = new AcpClient(options.timeoutMs);
+    const abort = () => client.close();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    // Cover the race where the signal aborts between the pre-check above and listener
+    // registration: adding a listener to an already-aborted signal never fires, so the
+    // cancellation would otherwise be silently dropped.
+    if (options.signal?.aborted) {
+        client.close();
+        return { ok: false, text: '', error: 'ACP prompt was aborted before start.' };
+    }
+    try {
+        await client.initialize();
+        let sessionId = options.sessionId;
+        if (sessionId && options.sessionMode === 'load') {
+            sessionId = extractSessionId(await client.loadSession(sessionId), sessionId);
+        }
+        else if (sessionId && options.sessionMode === 'resume') {
+            sessionId = extractSessionId(await client.resumeSession(sessionId), sessionId);
+        }
+        else if (!sessionId) {
+            sessionId = extractSessionId(await client.newSession(options.workDir));
+        }
+        const result = await client.prompt(sessionId, options.prompt, options.workDir);
+        let text = extractAcpText(result) || client.getUpdateText();
+        if (!text) {
+            try {
+                text = JSON.stringify(result, null, 2);
+            }
+            catch {
+                text = '(ACP response is not JSON-serializable)';
+            }
+        }
+        text = truncateUtf8Tail(text, MAX_ACP_METADATA_BYTES);
+        let metadata;
+        try {
+            const serialized = JSON.stringify(result);
+            metadata = serialized.length <= MAX_ACP_METADATA_BYTES ? { result } : { truncated: true, size: serialized.length };
+        }
+        catch {
+            metadata = { truncated: true, reason: 'result is not JSON-serializable' };
+        }
+        return { ok: true, text: text || '(empty ACP response from Kimi)', sessionId, metadata };
+    }
+    catch (error) {
+        return { ok: false, text: '', error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        options.signal?.removeEventListener('abort', abort);
+        client.close();
+    }
+}
+export async function listAcpSessions() {
+    const client = new AcpClient(60_000);
+    try {
+        await client.initialize();
+        const result = await client.listSessions();
+        return { ok: true, text: JSON.stringify(result, null, 2) };
+    }
+    catch (error) {
+        return { ok: false, text: '', error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        client.close();
+    }
+}
+export async function cancelAcpSession(sessionId) {
+    const client = new AcpClient(30_000);
+    try {
+        await client.initialize();
+        const result = await client.cancel(sessionId);
+        return { ok: true, text: JSON.stringify(result ?? { cancelled: true }, null, 2), sessionId };
+    }
+    catch (error) {
+        return { ok: false, text: '', error: error instanceof Error ? error.message : String(error), sessionId };
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/transports/cli-admin.js

@@ -0,0 +1,239 @@
+import { execFile, spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { buildKimiEnv, getKimiStatus, resolveKimiPaths } from '../environment.js';
+const execFileAsync = promisify(execFile);
+const ADMIN_TIMEOUT_MS = 30_000;
+// Quote a single argument for the human-readable preview command. This string is
+// display-only (never executed), but quoting anything outside a conservative safe
+// set — not just spaces — keeps the preview copy-paste-safe and unambiguous when an
+// argument contains shell metacharacters.
+export function quoteForDisplay(arg) {
+    return /^[A-Za-z0-9_\-.,:/\\=]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+function assertLocalVisualizerAddress(host, port) {
+    if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
+        throw new Error('kimi_visualize_session only supports localhost hosts.');
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error('Visualizer port must be an integer from 1 to 65535.');
+    }
+}
+// Canonicalize a path by resolving symlinks in its nearest existing ancestor and
+// re-appending the not-yet-existing tail. This lets the containment check below
+// compare like-for-like (canonical vs canonical) even when the target file does
+// not exist yet, closing the symlink-escape gap.
+function canonicalizePath(target) {
+    let current = path.resolve(target);
+    const tail = [];
+    for (;;) {
+        try {
+            const real = fs.realpathSync(current);
+            return tail.length ? path.join(real, ...tail.reverse()) : real;
+        }
+        catch (error) {
+            // Only a missing path (ENOENT) is recoverable: resolve the nearest existing
+            // ancestor and re-append the not-yet-created tail. Any other realpath failure
+            // (EACCES, ELOOP, …) means we cannot prove containment, so fail closed rather
+            // than return a non-canonical path that would defeat the symlink-escape check.
+            if (error.code !== 'ENOENT') {
+                throw new Error(`output_path could not be canonicalized: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(target);
+            tail.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+function assertSafeOutputPath(outputPath) {
+    if (outputPath.includes('\0')) {
+        throw new Error('output_path contains invalid null bytes.');
+    }
+    const cwd = canonicalizePath(process.cwd());
+    const resolved = canonicalizePath(path.resolve(process.cwd(), outputPath));
+    const relative = path.relative(cwd, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('output_path must be inside the current working directory.');
+    }
+}
+function requireBinary() {
+    const binary = resolveKimiPaths().binaryPath;
+    if (!binary)
+        throw new Error('Kimi CLI binary was not found on PATH or at ~/.kimi-code/bin/kimi.exe.');
+    return binary;
+}
+export function buildDoctorArgs(target = 'config', configPath) {
+    return ['doctor', target, ...(configPath ? [configPath] : [])];
+}
+export function buildProviderListArgs() {
+    return ['provider', 'list', '--json'];
+}
+export function buildExportArgs(options) {
+    const args = ['export'];
+    if (options.sessionId)
+        args.push(options.sessionId);
+    args.push('-o', options.outputPath);
+    if (options.overwriteExisting === true)
+        args.push('-y');
+    if (options.includeGlobalLog !== true)
+        args.push('--no-include-global-log');
+    return args;
+}
+export function buildVisualizeArgs(options) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 58628;
+    assertLocalVisualizerAddress(host, port);
+    const args = ['vis'];
+    if (options.sessionId)
+        args.push(options.sessionId);
+    args.push('--host', host, '--port', String(port), '--no-open');
+    return args;
+}
+const DEFAULT_MAX_BUFFER = 1024 * 1024 * 8;
+const PROBE_MAX_BUFFER = 1024 * 256;
+async function runKimiCommand(args, timeoutMs = ADMIN_TIMEOUT_MS, maxBuffer = DEFAULT_MAX_BUFFER) {
+    try {
+        const binary = requireBinary();
+        const child = execFileAsync(binary, args, {
+            env: buildKimiEnv(),
+            timeout: timeoutMs,
+            windowsHide: true,
+            maxBuffer,
+        });
+        // None of these admin commands read stdin. Close it so that if a TOCTOU overwrite
+        // prompt (or any other prompt) appears, the CLI receives EOF and fails fast instead
+        // of blocking on input until the timeout fires.
+        child.child.stdin?.end();
+        const { stdout, stderr } = await child;
+        return { ok: true, stdout: String(stdout), stderr: String(stderr) };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            ok: false,
+            stdout: err.stdout ? String(err.stdout) : '',
+            stderr: err.stderr ? String(err.stderr) : '',
+            error: err.message,
+        };
+    }
+}
+export async function getKimiCapabilities() {
+    const status = await getKimiStatus();
+    const commandNames = ['acp', 'doctor', 'provider', 'export', 'vis', 'server', 'web'];
+    const commands = {};
+    if (status.installed) {
+        // These seven `--help` probes run in parallel. Cap each one's buffer so the
+        // worst-case combined allocation stays small (7 * 256 KiB) instead of 7 * 8 MiB;
+        // help text is tiny, so the smaller cap never truncates real output.
+        await Promise.all(commandNames.map(async (name) => {
+            const result = await runKimiCommand([name, '--help'], 5000, PROBE_MAX_BUFFER);
+            commands[name] = result.ok || result.stdout.includes('Usage:') || result.stderr.includes('Usage:');
+        }));
+    }
+    else {
+        for (const name of commandNames)
+            commands[name] = false;
+    }
+    return {
+        cli: {
+            installed: status.installed,
+            binary: status.binPath,
+            version: status.version,
+            catalogFound: status.catalogFound,
+            authenticated: status.authenticated,
+        },
+        commands,
+        acp: { available: commands.acp === true, command: 'kimi acp' },
+        desktop: { experimental: true, readOnly: true },
+    };
+}
+export async function runKimiDoctor(target = 'config', configPath) {
+    return runKimiCommand(buildDoctorArgs(target, configPath));
+}
+export async function listKimiProviders() {
+    const result = await runKimiCommand(buildProviderListArgs());
+    if (!result.ok)
+        return result;
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return result;
+    }
+}
+export async function exportKimiSession(options) {
+    if (!options.outputPath.trim()) {
+        return { ok: false, stdout: '', stderr: '', error: 'output_path is required for kimi_export_session.' };
+    }
+    try {
+        assertSafeOutputPath(options.outputPath);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: '',
+            stderr: '',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const outputPath = path.resolve(options.outputPath);
+    let existingStat;
+    try {
+        existingStat = fs.statSync(outputPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            return {
+                ok: false,
+                stdout: '',
+                stderr: '',
+                error: `output_path could not be inspected: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    if (existingStat) {
+        if (existingStat.isDirectory()) {
+            return { ok: false, stdout: '', stderr: '', error: 'output_path must be a file, not a directory.' };
+        }
+        if (options.overwriteExisting !== true) {
+            return {
+                ok: false,
+                stdout: '',
+                stderr: '',
+                error: 'output_path already exists. Pass overwrite_existing=true to replace it explicitly.',
+            };
+        }
+    }
+    return runKimiCommand(buildExportArgs({ ...options, outputPath }), 120_000);
+}
+export function visualizeSession(options) {
+    const binary = requireBinary();
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 58628;
+    assertLocalVisualizerAddress(host, port);
+    const args = buildVisualizeArgs({ ...options, host, port });
+    const command = [binary, ...args].map(quoteForDisplay).join(' ');
+    const sessionPart = options.sessionId ? `?session=${encodeURIComponent(options.sessionId)}` : '';
+    const urlHost = host.includes(':') ? `[${host}]` : host;
+    const url = `http://${urlHost}:${port}/${sessionPart}`;
+    if (!options.launch)
+        return { command, url, launched: false };
+    const proc = spawn(binary, args, {
+        env: buildKimiEnv(),
+        stdio: 'ignore',
+        detached: true,
+        windowsHide: true,
+    });
+    // Detached fire-and-forget: spawn errors surface asynchronously and cannot be
+    // observed before this function returns, so `launched` reflects only whether a
+    // pid was assigned. Keep an 'error' listener so an async spawn failure surfaces
+    // on our stderr instead of crashing the host as an unhandled 'error' event.
+    proc.on('error', (error) => {
+        process.stderr.write(`Visualizer process failed to start: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+    proc.unref();
+    return { command, url, launched: proc.pid !== undefined, pid: proc.pid ?? undefined };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "ladder-mcp",
+  "version": "1.0.0",
+  "description": "Windows-first MCP bridge for Kimi Code CLI v24",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ladder-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
+  }
+}