@kontextmind/kxm 0.6.0

package/plugins/kxm/src/logger.ts

@@ -0,0 +1,198 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { redactSecrets } from "./redact.ts";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export const DEFAULT_LOG_MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+export const DEFAULT_LOG_MAX_FILES = 3;
+
+const SENSITIVE_KEY_PATTERN = /(?:^|_)(?:token|secret|password|apiKey|api_key|authorization|bearer)(?:$|_)/i;
+const ALLOWED_EXACT_KEYS = new Set(["auth", "authType", "authMethod", "authArgs", "canUpdate", "status"]);
+
+export function redactLogValue(val: unknown, key?: string): unknown {
+  if (val === null || val === undefined) return val;
+  if (typeof val === "string") {
+    if (key && SENSITIVE_KEY_PATTERN.test(key) && !ALLOWED_EXACT_KEYS.has(key)) {
+      return "[redacted]";
+    }
+    return redactSecrets(val);
+  }
+  if (typeof val === "number" || typeof val === "boolean") {
+    return val;
+  }
+  if (Array.isArray(val)) {
+    return val.map((item) => redactLogValue(item, key));
+  }
+  if (typeof val === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(val as Record<string, unknown>)) {
+      out[k] = redactLogValue(v, k);
+    }
+    return out;
+  }
+  return String(val);
+}
+
+export function rotateLogFiles(filePath: string, maxFiles: number): void {
+  for (let i = maxFiles; i >= 1; i--) {
+    const current = `${filePath}.${i}`;
+    if (existsSync(current)) {
+      if (i >= maxFiles) {
+        try { unlinkSync(current); } catch { /* best effort */ }
+      } else {
+        try { renameSync(current, `${filePath}.${i + 1}`); } catch { /* best effort */ }
+      }
+    }
+  }
+  if (existsSync(filePath)) {
+    try { renameSync(filePath, `${filePath}.1`); } catch { /* best effort */ }
+  }
+}
+
+export interface LogEntry {
+  timestamp?: string | undefined;
+  level?: LogLevel | string | undefined;
+  component?: string | undefined;
+  event?: string | undefined;
+  message?: string | undefined;
+  correlationId?: string | undefined;
+  requestId?: string | undefined;
+  runId?: string | undefined;
+  sessionId?: string | undefined;
+  traceId?: string | undefined;
+  [key: string]: unknown;
+}
+
+export interface LoggerOptions {
+  component: string;
+  path?: string | undefined;
+  maxBytes?: number | undefined;
+  maxFiles?: number | undefined;
+  level?: LogLevel | undefined;
+  stdout?: boolean | undefined;
+  daemon?: boolean | undefined;
+  correlation?: Record<string, string | number | undefined> | undefined;
+}
+
+export interface Logger {
+  (entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>): void;
+  info(entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>): void;
+  warn(entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>): void;
+  error(entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>): void;
+  debug(entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>): void;
+  child(context: { component?: string | undefined; correlation?: Record<string, string | number | undefined> | undefined }): Logger;
+  close(): void;
+  readonly options: Readonly<LoggerOptions>;
+}
+
+export function createLogger(options: LoggerOptions): Logger {
+  const component = options.component;
+  const filePath = options.path;
+  const maxBytes = Math.max(100, options.maxBytes ?? DEFAULT_LOG_MAX_BYTES);
+  const maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_LOG_MAX_FILES);
+  const configuredLevel: LogLevel = options.level ?? "info";
+  const isDaemon = Boolean(options.daemon ?? (process.env.KXM_DAEMON === "1" || process.env.KXM_DAEMON === "true"));
+  const shouldStdout = options.stdout ?? !isDaemon;
+  const correlationDefaults = options.correlation ?? {};
+
+  let currentSize = 0;
+  if (filePath && existsSync(filePath)) {
+    try {
+      currentSize = statSync(filePath).size;
+    } catch {
+      currentSize = 0;
+    }
+  }
+
+  function emit(level: LogLevel, entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>): void {
+    const minPriority = LOG_LEVEL_PRIORITY[configuredLevel] ?? LOG_LEVEL_PRIORITY.info;
+    const currentPriority = LOG_LEVEL_PRIORITY[level] ?? LOG_LEVEL_PRIORITY.info;
+    if (currentPriority < minPriority) return;
+
+    let base: Record<string, unknown>;
+    if (typeof entryOrEvent === "string") {
+      base = { event: entryOrEvent, ...extra };
+    } else {
+      base = { ...entryOrEvent, ...extra };
+    }
+
+    const timestamp = typeof base.timestamp === "string" ? base.timestamp : new Date().toISOString();
+    delete base.timestamp;
+    delete base.level;
+    delete base.component;
+
+    const payload: Record<string, unknown> = {
+      timestamp,
+      level,
+      component,
+      ...correlationDefaults,
+      ...base,
+    };
+
+    const sanitized = redactLogValue(payload) as Record<string, unknown>;
+    const line = `${JSON.stringify(sanitized)}\n`;
+
+    if (filePath) {
+      const lineBytes = Buffer.byteLength(line, "utf8");
+      if (currentSize + lineBytes > maxBytes) {
+        rotateLogFiles(filePath, maxFiles);
+        currentSize = 0;
+      }
+      try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        appendFileSync(filePath, line, { encoding: "utf8", mode: 0o600 });
+        currentSize += lineBytes;
+      } catch {
+        // best effort write
+      }
+    }
+
+    if (shouldStdout) {
+      process.stdout.write(line);
+    }
+  }
+
+  const logFn = ((entryOrEvent: string | Record<string, unknown>, extra?: Record<string, unknown>) => {
+    let lvl: LogLevel = "info";
+    if (typeof entryOrEvent === "object" && entryOrEvent !== null && typeof entryOrEvent.level === "string") {
+      const candidate = entryOrEvent.level.toLowerCase();
+      if (candidate === "debug" || candidate === "info" || candidate === "warn" || candidate === "error") {
+        lvl = candidate;
+      }
+    }
+    emit(lvl, entryOrEvent, extra);
+  }) as Logger;
+
+  logFn.info = (entryOrEvent, extra) => emit("info", entryOrEvent, extra);
+  logFn.warn = (entryOrEvent, extra) => emit("warn", entryOrEvent, extra);
+  logFn.error = (entryOrEvent, extra) => emit("error", entryOrEvent, extra);
+  logFn.debug = (entryOrEvent, extra) => emit("debug", entryOrEvent, extra);
+
+  logFn.child = (sub) => {
+    return createLogger({
+      ...options,
+      component: sub.component ? `${component}.${sub.component}` : component,
+      correlation: { ...correlationDefaults, ...sub.correlation },
+    });
+  };
+
+  logFn.close = () => {
+    // Synchronous file appends need no stream flush
+  };
+
+  Object.defineProperty(logFn, "options", {
+    value: Object.freeze({ ...options }),
+    writable: false,
+    enumerable: true,
+  });
+
+  return logFn;
+}

package/plugins/kxm/src/mcp-server.ts

@@ -0,0 +1,143 @@
+import { basename } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { HubClient } from "./client.ts";
+import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } from "./commands.ts";
+import { deliverInboxNotification } from "./inbox.ts";
+import type { HubEvent, MessageRecord } from "./protocol.ts";
+
+const VERSION = "0.6.0";
+const inbox = new Map<string, MessageRecord>();
+const notifiedInbox = new Set<string>();
+let meshClient: HubClient | undefined;
+let starting: Promise<HubClient> | undefined;
+
+const mcp = new Server(
+  { name: "kxm", version: VERSION },
+  {
+    capabilities: {
+      experimental: { "claude/channel": {} },
+      tools: {},
+    },
+    instructions: [
+      'KXM peer requests can arrive as <channel source="kxm" message_id="..."> events.',
+      "Handle the request using normal safety rules, then call kxm_reply with message_id and the final response.",
+      "Use kxm_inbox as a fallback when channel delivery is not enabled.",
+      "For durable workflow requests, call kxm_workflow_get, record material plans/decisions/contradictions/errors/lessons, and pass every checkpoint before replying.",
+      "If work is running in an external system, call kxm_workflow_wait and then kxm_reply so a signed callback can resume the workflow later.",
+    ].join(" "),
+  },
+);
+
+function textResult(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+async function onHubEvent(event: HubEvent): Promise<void> {
+  if (event.type === "cancelled" || event.type === "expired") {
+    inbox.delete(event.message.id);
+    notifiedInbox.delete(event.message.id);
+    return;
+  }
+  if (event.type !== "message") return;
+  const client = meshClient;
+  if (!client) return;
+  if (event.message.status === "queued") await client.acknowledge(event.message.id);
+  inbox.set(event.message.id, event.message);
+  const meta: Record<string, string> = {
+    message_id: event.message.id,
+    from_agent: event.message.fromName,
+    delivery: event.message.delivery,
+  };
+  if (event.message.correlationId) meta.correlation_id = event.message.correlationId;
+  await deliverInboxNotification(event.message.id, notifiedInbox, async () => {
+    await mcp.notification({
+      method: "notifications/claude/channel",
+      params: {
+        content: [
+          `Peer request from ${event.message.fromName}:`,
+          "",
+          event.message.content,
+          "",
+          `When complete, call kxm_reply with messageId ${event.message.id}.`,
+        ].join("\n"),
+        meta,
+      },
+    });
+  });
+}
+
+async function ensureClient(): Promise<HubClient> {
+  if (meshClient?.agent) return meshClient;
+  if (starting) return starting;
+  starting = (async () => {
+    const projectDir = process.env.KXM_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const authToken = optionalString(process.env.KXM_AUTH_TOKEN);
+    const candidate = new HubClient({
+      serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
+      name: process.env.KXM_AGENT_NAME?.trim() || `claude-${process.pid}`,
+      purpose: process.env.KXM_AGENT_PURPOSE?.trim() || "Claude Code implementation and review agent",
+      project: process.env.KXM_PROJECT?.trim() || basename(projectDir),
+      model: "claude-code",
+      ...(authToken ? { authToken } : {}),
+    });
+    try {
+      await candidate.start(onHubEvent);
+      meshClient = candidate;
+      return candidate;
+    } catch (error) {
+      await candidate.stop();
+      throw error;
+    }
+  })();
+  try {
+    return await starting;
+  } finally {
+    starting = undefined;
+  }
+}
+
+const tools = getMcpTools();
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  try {
+    const policy = enforceToolPolicy(request.params.name);
+    if (!policy.allowed) {
+      throw new Error(`tool_policy_denied: ${policy.detail ?? policy.error}`);
+    }
+    const client = await ensureClient();
+    const cmd = AGENT_COMMANDS_MAP.get(request.params.name);
+    if (!cmd) throw new Error(`unknown tool: ${request.params.name}`);
+    const args = asRecord(request.params.arguments);
+    const result = await cmd.execute(client, args, { signal: extra.signal, inbox, notifiedInbox });
+    return textResult(result);
+  } catch (error) {
+    return {
+      content: [{ type: "text" as const, text: error instanceof Error ? error.message : String(error) }],
+      isError: true,
+    };
+  }
+});
+
+await mcp.connect(new StdioServerTransport());
+
+async function shutdown(): Promise<void> {
+  await meshClient?.stop();
+  await mcp.close();
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());