klyro 0.1.63 → 1.0.1

package/dist/mcp/client.d.ts

@@ -0,0 +1,55 @@
+import type { McpServerSpec } from './config.js';
+export interface McpToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+export interface McpResource {
+    uri: string;
+    name?: string;
+    mimeType?: string;
+}
+export interface McpCallResult {
+    /** Normalized text payload (content blocks joined). */
+    text: string;
+    isError: boolean;
+    raw: unknown;
+}
+export interface McpClientLike {
+    listTools(signal?: AbortSignal): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
+    listResources(signal?: AbortSignal): Promise<McpResource[]>;
+    close(): Promise<void>;
+}
+export declare class McpError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+export declare class McpClient implements McpClientLike {
+    readonly name: string;
+    private readonly spec;
+    private child;
+    private nextId;
+    private readonly pending;
+    private stdoutBuf;
+    private stderrTail;
+    private dead;
+    private closed;
+    constructor(name: string, spec: McpServerSpec);
+    connect(): Promise<void>;
+    private connected;
+    listTools(signal?: AbortSignal): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
+    listResources(signal?: AbortSignal): Promise<McpResource[]>;
+    readResource(uri: string, signal?: AbortSignal): Promise<string>;
+    close(): Promise<void>;
+    /** Test hook: number of in-flight JSON-RPC requests. */
+    pendingCount(): number;
+    private timeout;
+    private assertLive;
+    private onStdout;
+    private notify;
+    private request;
+    private failAll;
+}

package/dist/mcp/client.js

@@ -0,0 +1,294 @@
+/**
+ * P1 — MCP stdio client (r-11-17.md §3.1).
+ *
+ * Minimal JSON-RPC 2.0 over newline-delimited stdio: `initialize`,
+ * `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`.
+ * Every call is bound to an `AbortSignal` and a per-call timeout; spawn
+ * failures and server errors surface as typed `McpError`s — never throws
+ * raw across the boundary.
+ */
+import { execFileSync, spawn } from 'node:child_process';
+export class McpError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'McpError';
+    }
+}
+const PROTOCOL_VERSION = '2024-11-05';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_STDERR_BYTES = 8192;
+/** Upper bound on spawn + initialize handshake; partial children are killed. */
+const CONNECT_TIMEOUT_MS = 15_000;
+/** Grace period between SIGTERM and SIGKILL in close(). */
+const CLOSE_SIGKILL_AFTER_MS = 2000;
+export class McpClient {
+    name;
+    spec;
+    child = null;
+    nextId = 1;
+    pending = new Map();
+    stdoutBuf = '';
+    stderrTail = '';
+    dead = null;
+    closed = false;
+    constructor(name, spec) {
+        this.name = name;
+        this.spec = spec;
+    }
+    async connect() {
+        if (this.child)
+            return;
+        const timeoutMs = this.spec.policy?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        await new Promise((resolve, reject) => {
+            let child;
+            try {
+                child = spawn(this.spec.command, this.spec.args ?? [], {
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    env: { ...process.env, ...(this.spec.env ?? {}) },
+                    shell: false,
+                    windowsHide: true,
+                });
+            }
+            catch (err) {
+                reject(new McpError(`mcp server "${this.name}" spawn failed: ${err instanceof Error ? err.message : String(err)}`, 'SPAWN_FAILED'));
+                return;
+            }
+            this.child = child;
+            // Swallow async stream errors (e.g. EPIPE on write-after-exit):
+            // request promises already surface failures via write callbacks and
+            // the exit handler, so these must never become uncaught exceptions.
+            child.stdin?.on('error', () => { });
+            child.stdout?.on('error', () => { });
+            child.stderr?.on('error', () => { });
+            child.on('error', (err) => {
+                this.failAll(new McpError(`mcp server "${this.name}" process error: ${err.message}`, 'SPAWN_FAILED'));
+                if (!this.connected)
+                    reject(new McpError(`mcp server "${this.name}" spawn failed: ${err.message}`, 'SPAWN_FAILED'));
+            });
+            child.stderr?.on('data', (b) => {
+                this.stderrTail = (this.stderrTail + b.toString('utf-8')).slice(-MAX_STDERR_BYTES);
+            });
+            child.stdout?.on('data', (b) => this.onStdout(b.toString('utf-8')));
+            child.on('exit', (code, signal) => {
+                if (!this.closed) {
+                    this.failAll(new McpError(`mcp server "${this.name}" exited (${signal ?? `code ${code}`})${this.stderrTail ? `: ${this.stderrTail.slice(-300)}` : ''}`, 'SERVER_EXITED'));
+                }
+            });
+            // Consider the transport up once the process is spawned; the
+            // initialize handshake below proves the protocol.
+            resolve();
+        });
+        try {
+            let connectTimer;
+            try {
+                await Promise.race([
+                    (async () => {
+                        await this.request('initialize', {
+                            protocolVersion: PROTOCOL_VERSION,
+                            capabilities: {},
+                            clientInfo: { name: 'klyro', version: '1.0.1' },
+                        }, timeoutMs);
+                        this.notify('notifications/initialized', {});
+                        this.connected = true;
+                    })(),
+                    new Promise((_resolve, reject) => {
+                        connectTimer = setTimeout(() => {
+                            reject(new McpError(`mcp server "${this.name}" connect timed out after ${CONNECT_TIMEOUT_MS}ms`, 'TIMEOUT'));
+                        }, CONNECT_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            finally {
+                if (connectTimer)
+                    clearTimeout(connectTimer);
+            }
+        }
+        catch (err) {
+            await this.close();
+            throw err;
+        }
+    }
+    connected = false;
+    async listTools(signal) {
+        this.assertLive();
+        const res = (await this.request('tools/list', {}, this.timeout(), signal));
+        return Array.isArray(res.tools) ? res.tools : [];
+    }
+    async callTool(name, args, signal) {
+        this.assertLive();
+        const res = (await this.request('tools/call', { name, arguments: args ?? {} }, this.timeout(), signal));
+        const blocks = Array.isArray(res.content) ? res.content : [];
+        const text = blocks.map((b) => (typeof b.text === 'string' ? b.text : JSON.stringify(b))).join('\n');
+        return { text, isError: res.isError === true, raw: res };
+    }
+    async listResources(signal) {
+        this.assertLive();
+        const res = (await this.request('resources/list', {}, this.timeout(), signal));
+        return Array.isArray(res.resources) ? res.resources : [];
+    }
+    async readResource(uri, signal) {
+        this.assertLive();
+        const res = (await this.request('resources/read', { uri }, this.timeout(), signal));
+        const contents = Array.isArray(res.contents) ? res.contents : [];
+        return contents.map((c) => (typeof c.text === 'string' ? c.text : JSON.stringify(c))).join('\n');
+    }
+    async close() {
+        // Idempotent vs the exit handler: closed is set FIRST (the on('exit')
+        // callback checks it before failAll), and a second close() with no child
+        // left is a no-op.
+        if (this.closed && this.child === null)
+            return;
+        this.closed = true;
+        this.failAll(new McpError(`mcp server "${this.name}" closed`, 'CLOSED'));
+        const child = this.child;
+        this.child = null;
+        if (!child)
+            return;
+        // Already reaped — no escalation timer needed.
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        if (process.platform === 'win32') {
+            try {
+                if (child.pid !== undefined) {
+                    execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+                }
+            }
+            catch { /* ignore — fall through to kill() */ }
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* already gone */ }
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        }, CLOSE_SIGKILL_AFTER_MS);
+        timer.unref?.();
+        child.once('exit', () => clearTimeout(timer));
+    }
+    /** Test hook: number of in-flight JSON-RPC requests. */
+    pendingCount() {
+        return this.pending.size;
+    }
+    /* ---------------- internals ---------------- */
+    timeout() {
+        return this.spec.policy?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    assertLive() {
+        if (this.dead)
+            throw this.dead;
+        if (!this.child || this.closed)
+            throw new McpError(`mcp server "${this.name}" is not connected`, 'NOT_CONNECTED');
+    }
+    onStdout(chunk) {
+        this.stdoutBuf += chunk;
+        let idx;
+        while ((idx = this.stdoutBuf.indexOf('\n')) >= 0) {
+            const line = this.stdoutBuf.slice(0, idx).trim();
+            this.stdoutBuf = this.stdoutBuf.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue; // server chatter — ignore, don't crash
+            }
+            if (typeof msg.id !== 'number')
+                continue; // notification — ignore
+            const pend = this.pending.get(msg.id);
+            if (!pend)
+                continue;
+            this.pending.delete(msg.id);
+            clearTimeout(pend.timer);
+            if (pend.signal && pend.onAbort)
+                pend.signal.removeEventListener('abort', pend.onAbort);
+            if (msg.error) {
+                pend.reject(new McpError(`mcp server "${this.name}" error: ${msg.error.message ?? 'unknown'}`, 'SERVER_ERROR', msg.error));
+            }
+            else {
+                pend.resolve(msg.result);
+            }
+        }
+    }
+    notify(method, params) {
+        try {
+            this.child?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+        }
+        catch { /* best-effort */ }
+    }
+    request(method, params, timeoutMs, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new McpError(`mcp call "${method}" aborted`, 'ABORTED'));
+                return;
+            }
+            if (!this.child?.stdin) {
+                reject(new McpError(`mcp server "${this.name}" has no stdin`, 'NOT_CONNECTED'));
+                return;
+            }
+            const id = this.nextId++;
+            const timer = setTimeout(() => {
+                const p = this.pending.get(id);
+                if (p?.signal && p.onAbort)
+                    p.signal.removeEventListener('abort', p.onAbort);
+                this.pending.delete(id);
+                reject(new McpError(`mcp call "${method}" timed out after ${timeoutMs}ms`, 'TIMEOUT'));
+            }, timeoutMs);
+            const pend = { resolve, reject, timer };
+            if (signal) {
+                pend.signal = signal;
+                pend.onAbort = () => {
+                    if (!this.pending.has(id))
+                        return;
+                    this.pending.delete(id);
+                    clearTimeout(timer);
+                    reject(new McpError(`mcp call "${method}" aborted`, 'ABORTED'));
+                };
+                signal.addEventListener('abort', pend.onAbort, { once: true });
+            }
+            this.pending.set(id, pend);
+            try {
+                this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', (err) => {
+                    if (err) {
+                        this.pending.delete(id);
+                        clearTimeout(timer);
+                        if (signal && pend.onAbort)
+                            signal.removeEventListener('abort', pend.onAbort);
+                        reject(new McpError(`mcp call "${method}" write failed: ${err.message}`, 'IO_ERROR'));
+                    }
+                });
+            }
+            catch (err) {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                if (signal && pend.onAbort)
+                    signal.removeEventListener('abort', pend.onAbort);
+                reject(new McpError(`mcp call "${method}" write failed: ${err instanceof Error ? err.message : String(err)}`, 'IO_ERROR'));
+            }
+        });
+    }
+    failAll(err) {
+        if (!this.dead)
+            this.dead = err;
+        for (const [id, pend] of [...this.pending]) {
+            this.pending.delete(id);
+            clearTimeout(pend.timer);
+            if (pend.signal && pend.onAbort)
+                pend.signal.removeEventListener('abort', pend.onAbort);
+            pend.reject(err);
+        }
+    }
+}

package/dist/mcp/config.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const McpServerPolicySchema: z.ZodObject<{
+    allowTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    denyTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requireApproval: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type McpServerPolicy = z.infer<typeof McpServerPolicySchema>;
+export declare const McpServerSpecSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    policy: z.ZodOptional<z.ZodObject<{
+        allowTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        denyTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        requireApproval: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpServerSpec = z.infer<typeof McpServerSpecSchema>;
+export interface McpServersConfig {
+    servers: Record<string, McpServerSpec>;
+    /** Where each server entry came from (for doctor/diagnostics). */
+    sources: Record<string, string>;
+}
+/** Upper bound for per-server timeouts — larger values are clamped, not rejected. */
+export declare const MAX_MCP_TIMEOUT_MS = 600000;
+/**
+ * Expand `${env:VAR}` references from `process.env`.
+ *
+ * A reference to an UNSET or empty variable expands to `''` (silent empty
+ * expansion): the entry is kept with the empty value rather than rejected,
+ * so callers always see the effective spec. Pure — exported for unit tests.
+ */
+export declare function expandEnv(value: string): string;
+/** Load + merge global and project MCP server specs. Invalid entries are skipped. */
+export declare function loadMcpServers(cwd: string): McpServersConfig;
+/** Servers eligible for connection (configured and not disabled). */
+export declare function enabledServers(cfg: McpServersConfig): Record<string, McpServerSpec>;

package/dist/mcp/config.js

@@ -0,0 +1,99 @@
+/**
+ * P1 — MCP server configuration (r-11-17.md §3.1).
+ *
+ * Mirrors Claude Code's project-level `.mcp.json` (`{mcpServers: {...}}`) for
+ * drop-in compatibility, and also tolerates the legacy Klyro shape
+ * (`{servers: {...}}` shown by `/mcp`). Global defaults live in
+ * `~/.klyro/mcp.json`; project config wins per-server.
+ *
+ * `${env:VAR}` references in `env` values expand from `process.env`.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { z } from 'zod';
+export const McpServerPolicySchema = z.object({
+    allowTools: z.array(z.string()).optional(),
+    denyTools: z.array(z.string()).optional(),
+    requireApproval: z.boolean().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+});
+export const McpServerSpecSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    disabled: z.boolean().optional(),
+    policy: McpServerPolicySchema.optional(),
+});
+/** Upper bound for per-server timeouts — larger values are clamped, not rejected. */
+export const MAX_MCP_TIMEOUT_MS = 600_000;
+/**
+ * Expand `${env:VAR}` references from `process.env`.
+ *
+ * A reference to an UNSET or empty variable expands to `''` (silent empty
+ * expansion): the entry is kept with the empty value rather than rejected,
+ * so callers always see the effective spec. Pure — exported for unit tests.
+ */
+export function expandEnv(value) {
+    return value.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => process.env[name] ?? '');
+}
+function normalizeRaw(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const obj = raw;
+    const servers = obj['mcpServers'] ?? obj['servers'] ?? {};
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers))
+        return {};
+    return servers;
+}
+function readJsonFile(p) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Load + merge global and project MCP server specs. Invalid entries are skipped. */
+export function loadMcpServers(cwd) {
+    const home = os.homedir() || process.cwd();
+    const globalPath = path.join(home, '.klyro', 'mcp.json');
+    const projectPath = path.join(cwd, '.mcp.json');
+    const servers = {};
+    const sources = {};
+    for (const [filePath, label] of [[globalPath, 'global'], [projectPath, 'project']]) {
+        const raw = normalizeRaw(readJsonFile(filePath));
+        for (const [name, specRaw] of Object.entries(raw)) {
+            // Empty server names can never produce a valid tool name — skip
+            // silently (shape stays `{servers, sources}`; registry reports
+            // empty TOOL names as errors at registration time).
+            if (name === '')
+                continue;
+            const parsed = McpServerSpecSchema.safeParse(specRaw);
+            if (!parsed.success)
+                continue;
+            const spec = parsed.data;
+            if (spec.policy?.timeoutMs !== undefined && spec.policy.timeoutMs > MAX_MCP_TIMEOUT_MS) {
+                spec.policy.timeoutMs = MAX_MCP_TIMEOUT_MS;
+            }
+            if (spec.env) {
+                const env = {};
+                for (const [k, v] of Object.entries(spec.env))
+                    env[k] = expandEnv(v);
+                spec.env = env;
+            }
+            servers[name] = spec;
+            sources[name] = label;
+        }
+    }
+    return { servers, sources };
+}
+/** Servers eligible for connection (configured and not disabled). */
+export function enabledServers(cfg) {
+    const out = {};
+    for (const [name, spec] of Object.entries(cfg.servers)) {
+        if (!spec.disabled)
+            out[name] = spec;
+    }
+    return out;
+}

package/dist/mcp/policy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * P1 — per-server MCP tool policy (r-11-17.md: "deny by default").
+ *
+ * A server without an explicit `allowTools` list cannot execute anything:
+ * the registration layer refuses the call before any subprocess I/O. An
+ * explicit `denyTools` entry always wins over `allowTools`.
+ */
+import type { McpServerPolicy } from './config.js';
+export interface McpPolicyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function evaluateMcpPolicy(policy: McpServerPolicy | undefined, toolName: string): McpPolicyDecision;

package/dist/mcp/policy.js

@@ -0,0 +1,12 @@
+export function evaluateMcpPolicy(policy, toolName) {
+    if (!policy || !policy.allowTools || policy.allowTools.length === 0) {
+        return { allowed: false, reason: 'mcp tool denied: server has no allowTools allowlist' };
+    }
+    if (policy.denyTools?.includes(toolName)) {
+        return { allowed: false, reason: `mcp tool denied by server denyTools: ${toolName}` };
+    }
+    if (!policy.allowTools.includes(toolName)) {
+        return { allowed: false, reason: `mcp tool not in server allowTools: ${toolName}` };
+    }
+    return { allowed: true };
+}

package/dist/mcp/registry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * P1 — MCP tool registration (r-11-17.md §3.1).
+ *
+ * Exposes MCP server tools through the {@link ToolRegistry} under
+ * `mcp__<server>__<tool>` names. Security properties (non-negotiable):
+ *
+ *   1. Deny-by-default: `evaluateMcpPolicy` runs BEFORE any client I/O; a
+ *      denied tool returns POLICY_DENIED without touching the subprocess.
+ *   2. Redact-before-transcript: every success value AND error message passes
+ *      through `redact()` before it can reach the model or trace.
+ *   3. `requireApproval` servers add an ask-rule to the PolicyEngine so the
+ *      runtime loop prompts before executing.
+ *
+ * Permission class: no code in src consumes `Tool.permission` (it is
+ * write-only metadata today), so we pick the most restrictive class,
+ * 'admin' — the same class as `spawn_agent`, since MCP tools execute
+ * arbitrary external side effects (read/write/network) outside our control.
+ */
+import { type McpClientLike } from './client.js';
+import { type McpServerSpec } from './config.js';
+import type { PolicyEngine } from '../policy/engine.js';
+import type { ToolRegistry } from '../tools/registry.js';
+export interface McpRegisterResult {
+    registered: string[];
+    errors: {
+        server: string;
+        message: string;
+    }[];
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+    closeAll: () => Promise<void>;
+}
+export interface RegisterMcpOpts {
+    registry: ToolRegistry;
+    policy?: PolicyEngine;
+    clientFactory?: (name: string, spec: McpServerSpec) => McpClientLike;
+}
+/** Success values are redacted FIRST, then truncated to this many chars. */
+export declare const MCP_SUCCESS_MAX_CHARS = 12000;
+/**
+ * `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64.
+ *
+ * No `'server'`/`'tool'` fallbacks: an empty raw part (or one that
+ * sanitizes to empty) yields an empty segment, and registration skips that
+ * tool with an `empty-name` error instead of masking a misconfiguration
+ * behind a plausible-looking name.
+ */
+export declare function sanitizeMcpName(server: string, tool: string): string;
+export declare function registerMcpServers(cfg: {
+    servers: Record<string, McpServerSpec>;
+}, opts: RegisterMcpOpts): Promise<McpRegisterResult>;
+export declare function loadAndRegisterMcp(opts: {
+    cwd: string;
+    registry: ToolRegistry;
+    policy?: PolicyEngine;
+    clientFactory?: (name: string, spec: McpServerSpec) => McpClientLike;
+    /**
+     * Consent gate for project-sourced (`.mcp.json`) servers, which can
+     * auto-spawn processes. Global-source servers connect as before; a project
+     * server connects ONLY when this callback returns true. When the callback
+     * is ABSENT, project servers are never auto-connected — each surfaces as
+     * an error (`project server requires approval (skipped)`) so the skip is
+     * visible. Callers may compose this with `McpTrust` (see `./trust.js`) to
+     * remember approvals per spec hash.
+     */
+    approveProjectServer?: (info: {
+        name: string;
+        source: 'global' | 'project';
+    }) => Promise<boolean>;
+}): Promise<McpRegisterResult>;