@kkelly-offical/kkcode 0.1.2 → 0.1.6

package/src/mcp/stdio-framing.mjs

@@ -1,127 +1,133 @@
-const CRLFCRLF = Buffer.from("\r\n\r\n", "utf8")
-const NEWLINE = 0x0a
-
-function toBuffer(chunk) {
-  if (Buffer.isBuffer(chunk)) return chunk
-  if (typeof chunk === "string") return Buffer.from(chunk, "utf8")
-  if (chunk instanceof Uint8Array) return Buffer.from(chunk)
-  return Buffer.from(String(chunk || ""), "utf8")
-}
-
-function parseContentLengthHeader(headerText) {
-  const match = /(?:^|\r?\n)content-length:\s*(\d+)\s*(?:\r?\n|$)/i.exec(headerText)
-  if (!match) return null
-  const len = Number(match[1])
-  if (!Number.isFinite(len) || len < 0) return null
-  return len
-}
-
-function consumeContentLengthFrame(buffer, maxFrameBytes) {
-  const headerEnd = buffer.indexOf(CRLFCRLF)
-  if (headerEnd === -1) return { type: "need_more" }
-  const headerText = buffer.subarray(0, headerEnd).toString("utf8")
-  const length = parseContentLengthHeader(headerText)
-  if (length === null) return { type: "invalid_header" }
-  if (length > maxFrameBytes) return { type: "invalid_size", size: length }
-  const total = headerEnd + CRLFCRLF.length + length
-  if (buffer.length < total) return { type: "need_more" }
-  const payload = buffer
-    .subarray(headerEnd + CRLFCRLF.length, total)
-    .toString("utf8")
-  const rest = buffer.subarray(total)
-  return { type: "ok", payload, rest }
-}
-
-function consumeNewlineFrame(buffer) {
-  const newlineIdx = buffer.indexOf(NEWLINE)
-  if (newlineIdx === -1) return { type: "need_more" }
-  const rawLine = buffer.subarray(0, newlineIdx).toString("utf8")
-  const rest = buffer.subarray(newlineIdx + 1)
-  const payload = rawLine.trim()
-  if (!payload) return { type: "empty", rest }
-  return { type: "ok", payload, rest }
-}
-
-function dropLeadingCrlf(buffer) {
-  let cursor = 0
-  while (cursor < buffer.length) {
-    const c = buffer[cursor]
-    if (c !== 0x0d && c !== 0x0a) break
-    cursor += 1
-  }
-  return cursor > 0 ? buffer.subarray(cursor) : buffer
-}
-
-function seemsContentLength(buffer) {
-  if (!buffer.length) return false
-  const probe = buffer.subarray(0, Math.min(buffer.length, 32)).toString("ascii").toLowerCase()
-  return probe.startsWith("content-length:")
-}
-
-export function encodeRpcMessage(message, framing = "content-length") {
-  const payload = JSON.stringify(message)
-  if (framing === "newline") return `${payload}\n`
-  const size = Buffer.byteLength(payload, "utf8")
-  return `Content-Length: ${size}\r\n\r\n${payload}`
-}
-
-export function createStdioFramingDecoder({ framing = "auto", maxFrameBytes = 8 * 1024 * 1024 } = {}) {
-  let buffer = Buffer.alloc(0)
-
-  function push(chunk) {
-    buffer = Buffer.concat([buffer, toBuffer(chunk)])
-    const messages = []
-
-    while (true) {
-      if (!buffer.length) break
-
-      if (framing === "content-length") {
-        const parsed = consumeContentLengthFrame(buffer, maxFrameBytes)
-        if (parsed.type === "need_more") break
-        if (parsed.type === "invalid_header") throw new Error("invalid content-length header")
-        if (parsed.type === "invalid_size") throw new Error(`content-length exceeds limit: ${parsed.size}`)
-        messages.push(parsed.payload)
-        buffer = parsed.rest
-        continue
-      }
-
-      if (framing === "newline") {
-        const parsed = consumeNewlineFrame(buffer)
-        if (parsed.type === "need_more") break
-        buffer = parsed.rest
-        if (parsed.type === "ok") messages.push(parsed.payload)
-        continue
-      }
-
-      // auto mode: prefer standard content-length frames, then fallback to newline JSON
-      buffer = dropLeadingCrlf(buffer)
-      if (!buffer.length) break
-
-      if (seemsContentLength(buffer)) {
-        const parsed = consumeContentLengthFrame(buffer, maxFrameBytes)
-        if (parsed.type === "need_more") break
-        if (parsed.type === "invalid_header") throw new Error("invalid content-length header")
-        if (parsed.type === "invalid_size") throw new Error(`content-length exceeds limit: ${parsed.size}`)
-        messages.push(parsed.payload)
-        buffer = parsed.rest
-        continue
-      }
-
-      const parsed = consumeNewlineFrame(buffer)
-      if (parsed.type === "need_more") break
-      buffer = parsed.rest
-      if (parsed.type === "ok") messages.push(parsed.payload)
-    }
-
-    return messages
-  }
-
-  function reset() {
-    buffer = Buffer.alloc(0)
-  }
-
-  return {
-    push,
-    reset
-  }
-}
+const CRLFCRLF = Buffer.from("\r\n\r\n", "utf8")
+const NEWLINE = 0x0a
+
+function toBuffer(chunk) {
+  if (Buffer.isBuffer(chunk)) return chunk
+  if (typeof chunk === "string") return Buffer.from(chunk, "utf8")
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk)
+  return Buffer.from(String(chunk || ""), "utf8")
+}
+
+function parseContentLengthHeader(headerText) {
+  const match = /(?:^|\r?\n)content-length:\s*(\d+)\s*(?:\r?\n|$)/i.exec(headerText)
+  if (!match) return null
+  const len = Number(match[1])
+  if (!Number.isFinite(len) || len < 0) return null
+  return len
+}
+
+function consumeContentLengthFrame(buffer, maxFrameBytes) {
+  const headerEnd = buffer.indexOf(CRLFCRLF)
+  if (headerEnd === -1) return { type: "need_more" }
+  const headerText = buffer.subarray(0, headerEnd).toString("utf8")
+  const length = parseContentLengthHeader(headerText)
+  if (length === null) return { type: "invalid_header" }
+  if (length > maxFrameBytes) return { type: "invalid_size", size: length }
+  const total = headerEnd + CRLFCRLF.length + length
+  if (buffer.length < total) return { type: "need_more" }
+  const payload = buffer
+    .subarray(headerEnd + CRLFCRLF.length, total)
+    .toString("utf8")
+  const rest = buffer.subarray(total)
+  return { type: "ok", payload, rest }
+}
+
+function consumeNewlineFrame(buffer) {
+  const newlineIdx = buffer.indexOf(NEWLINE)
+  if (newlineIdx === -1) return { type: "need_more" }
+  const rawLine = buffer.subarray(0, newlineIdx).toString("utf8")
+  const rest = buffer.subarray(newlineIdx + 1)
+  const payload = rawLine.trim()
+  if (!payload) return { type: "empty", rest }
+  return { type: "ok", payload, rest }
+}
+
+function dropLeadingCrlf(buffer) {
+  let cursor = 0
+  while (cursor < buffer.length) {
+    const c = buffer[cursor]
+    if (c !== 0x0d && c !== 0x0a) break
+    cursor += 1
+  }
+  return cursor > 0 ? buffer.subarray(cursor) : buffer
+}
+
+function seemsContentLength(buffer) {
+  if (!buffer.length) return false
+  const probe = buffer.subarray(0, Math.min(buffer.length, 32)).toString("ascii").toLowerCase()
+  return probe.startsWith("content-length:")
+}
+
+export function encodeRpcMessage(message, framing = "content-length") {
+  const payload = JSON.stringify(message)
+  if (framing === "newline") return `${payload}\n`
+  const size = Buffer.byteLength(payload, "utf8")
+  return `Content-Length: ${size}\r\n\r\n${payload}`
+}
+
+export function createStdioFramingDecoder({ framing = "auto", maxFrameBytes = 8 * 1024 * 1024, maxBufferBytes = 16 * 1024 * 1024 } = {}) {
+  let buffer = Buffer.alloc(0)
+
+  function push(chunk) {
+    const incoming = toBuffer(chunk)
+    if (buffer.length + incoming.length > maxBufferBytes) {
+      buffer = Buffer.alloc(0)
+      throw new Error(`stdio framing buffer exceeded limit: ${maxBufferBytes} bytes`)
+    }
+    buffer = Buffer.concat([buffer, incoming])
+    const messages = []
+
+    while (true) {
+      if (!buffer.length) break
+
+      if (framing === "content-length") {
+        const parsed = consumeContentLengthFrame(buffer, maxFrameBytes)
+        if (parsed.type === "need_more") break
+        if (parsed.type === "invalid_header") throw new Error("invalid content-length header")
+        if (parsed.type === "invalid_size") throw new Error(`content-length exceeds limit: ${parsed.size}`)
+        messages.push(parsed.payload)
+        buffer = parsed.rest
+        continue
+      }
+
+      if (framing === "newline") {
+        const parsed = consumeNewlineFrame(buffer)
+        if (parsed.type === "need_more") break
+        buffer = parsed.rest
+        if (parsed.type === "ok") messages.push(parsed.payload)
+        continue
+      }
+
+      // auto mode: prefer standard content-length frames, then fallback to newline JSON
+      buffer = dropLeadingCrlf(buffer)
+      if (!buffer.length) break
+
+      if (seemsContentLength(buffer)) {
+        const parsed = consumeContentLengthFrame(buffer, maxFrameBytes)
+        if (parsed.type === "need_more") break
+        if (parsed.type === "invalid_header") throw new Error("invalid content-length header")
+        if (parsed.type === "invalid_size") throw new Error(`content-length exceeds limit: ${parsed.size}`)
+        messages.push(parsed.payload)
+        buffer = parsed.rest
+        continue
+      }
+
+      const parsed = consumeNewlineFrame(buffer)
+      if (parsed.type === "need_more") break
+      buffer = parsed.rest
+      if (parsed.type === "ok") messages.push(parsed.payload)
+    }
+
+    return messages
+  }
+
+  function reset() {
+    buffer = Buffer.alloc(0)
+  }
+
+  return {
+    push,
+    reset,
+    bufferSize() { return buffer.length }
+  }
+}

package/src/mcp/tool-result.mjs

@@ -0,0 +1,24 @@
+import { McpError } from "../core/errors.mjs"
+
+export function normalizeToolResult(result, serverName, toolName) {
+  if (result?.isError) {
+    const text = Array.isArray(result.content)
+      ? result.content.map((item) => item?.text || "").join("\n").trim()
+      : ""
+    throw new McpError(text || "mcp tool returned isError", {
+      reason: "bad_response",
+      server: serverName,
+      action: `tools/call:${toolName}`,
+      phase: "request"
+    })
+  }
+  const content = Array.isArray(result?.content) ? result.content : null
+  const contentText = content
+    ? content.map((item) => (typeof item?.text === "string" ? item.text : "")).join("\n").trim()
+    : ""
+  const output =
+    contentText ||
+    (typeof result?.output === "string" ? result.output : "") ||
+    (typeof result === "string" ? result : JSON.stringify(result))
+  return content ? { output, raw: result, content } : { output, raw: result }
+}

package/src/observability/index.mjs

@@ -0,0 +1,42 @@
+import { createMetricsCollector } from "./metrics.mjs"
+import { createTracer } from "./tracer.mjs"
+
+let metrics = null
+let tracer = null
+let unsubscribes = []
+
+export function initialize(eventBus) {
+  if (metrics) return // idempotent
+
+  metrics = createMetricsCollector()
+  tracer = createTracer()
+
+  unsubscribes.push(
+    eventBus.registerSink(async (event) => {
+      metrics.handleEvent(event)
+      tracer.handleEvent(event)
+    })
+  )
+}
+
+export function shutdown() {
+  for (const unsub of unsubscribes) unsub()
+  unsubscribes = []
+  metrics = null
+  tracer = null
+}
+
+export function getMetrics() {
+  return metrics ? metrics.getSnapshot() : null
+}
+
+export function getTraces() {
+  return tracer ? tracer.getTraces() : []
+}
+
+export function exportReport() {
+  return {
+    metrics: metrics ? metrics.getSnapshot() : null,
+    traces: tracer ? tracer.exportTraces("json") : "[]"
+  }
+}

package/src/observability/metrics.mjs

@@ -0,0 +1,137 @@
+import { EVENT_TYPES } from "../core/constants.mjs"
+
+function createHistogram() {
+  const values = []
+  return {
+    record(v) { values.push(v) },
+    snapshot() {
+      if (values.length === 0) return { count: 0, sum: 0, min: 0, max: 0, avg: 0, p50: 0, p99: 0 }
+      const sorted = [...values].sort((a, b) => a - b)
+      const sum = sorted.reduce((s, v) => s + v, 0)
+      const count = sorted.length
+      return {
+        count,
+        sum,
+        min: sorted[0],
+        max: sorted[count - 1],
+        avg: sum / count,
+        p50: sorted[Math.max(0, Math.ceil(count * 0.5) - 1)] || 0,
+        p99: sorted[Math.max(0, Math.ceil(count * 0.99) - 1)] || 0
+      }
+    },
+    reset() { values.length = 0 }
+  }
+}
+
+export function createMetricsCollector() {
+  const counters = new Map()
+  const histograms = new Map()
+  const turnStarts = new Map()
+  const stageStarts = new Map()
+
+  function inc(name, amount = 1) {
+    counters.set(name, (counters.get(name) || 0) + amount)
+  }
+
+  function hist(name) {
+    if (!histograms.has(name)) histograms.set(name, createHistogram())
+    return histograms.get(name)
+  }
+
+  const MAX_OPEN_ENTRIES = 500
+
+  function pruneStaleMap(map) {
+    if (map.size <= MAX_OPEN_ENTRIES) return
+    const cutoff = Date.now() - 30 * 60 * 1000 // 30 min
+    for (const [k, v] of map) {
+      if (v < cutoff) map.delete(k)
+    }
+    // If still over limit, drop oldest half
+    if (map.size > MAX_OPEN_ENTRIES) {
+      let toDrop = Math.floor(map.size / 2)
+      for (const k of map.keys()) {
+        if (toDrop-- <= 0) break
+        map.delete(k)
+      }
+    }
+  }
+
+  function handleEvent(event) {
+    const { type, payload, turnId, sessionId } = event
+
+    if (type === EVENT_TYPES.TURN_START) {
+      inc("turn_count")
+      if (turnId) {
+        turnStarts.set(turnId, event.timestamp)
+        pruneStaleMap(turnStarts)
+      }
+    }
+
+    if (type === EVENT_TYPES.TURN_FINISH) {
+      if (turnId && turnStarts.has(turnId)) {
+        hist("turn_duration_ms").record(event.timestamp - turnStarts.get(turnId))
+        turnStarts.delete(turnId)
+      }
+    }
+
+    if (type === EVENT_TYPES.TURN_ERROR) {
+      inc("error_count")
+    }
+
+    if (type === EVENT_TYPES.TOOL_START) {
+      inc("tool_call_count")
+    }
+
+    if (type === EVENT_TYPES.TOOL_ERROR) {
+      inc("tool_error_count")
+    }
+
+    if (type === EVENT_TYPES.TURN_USAGE_UPDATE) {
+      if (payload?.input) inc("token_input", payload.input)
+      if (payload?.output) inc("token_output", payload.output)
+      if (payload?.cacheRead) inc("token_cache_read", payload.cacheRead)
+    }
+
+    if (type === EVENT_TYPES.LONGAGENT_STAGE_STARTED) {
+      const key = payload?.stageId || sessionId
+      if (key) {
+        stageStarts.set(key, event.timestamp)
+        pruneStaleMap(stageStarts)
+      }
+    }
+
+    if (type === EVENT_TYPES.LONGAGENT_STAGE_FINISHED) {
+      const key = payload?.stageId || sessionId
+      if (key && stageStarts.has(key)) {
+        hist("longagent_stage_duration_ms").record(event.timestamp - stageStarts.get(key))
+        stageStarts.delete(key)
+      }
+      if (payload?.retryCount > 0) {
+        inc("longagent_task_retries", payload.retryCount)
+      }
+    }
+
+    if (type === EVENT_TYPES.LONGAGENT_GATE_CHECKED) {
+      inc("gate_check_count")
+      if (payload?.status === "pass") inc("gate_pass_count")
+    }
+  }
+
+  function getSnapshot() {
+    const counterSnapshot = new Map(counters)
+    const histogramSnapshot = new Map()
+    for (const [name, h] of histograms) {
+      histogramSnapshot.set(name, h.snapshot())
+    }
+    return { counters: counterSnapshot, histograms: histogramSnapshot }
+  }
+
+  function reset() {
+    counters.clear()
+    histograms.clear()
+    turnStarts.clear()
+    stageStarts.clear()
+  }
+
+  return { handleEvent, getSnapshot, reset }
+}

package/src/observability/tracer.mjs

@@ -0,0 +1,137 @@
+import { EVENT_TYPES } from "../core/constants.mjs"
+import { randomUUID } from "node:crypto"
+
+function newSpanId() {
+  return `span_${randomUUID().slice(0, 12)}`
+}
+
+export function createTracer(options = {}) {
+  const maxTraces = options.maxTraces || 100
+  const maxOpenSpans = options.maxOpenSpans || 500
+  const traces = []
+  const openSpans = new Map()
+  const phaseSpan = { current: null }
+  let currentTraceId = null
+
+  function pruneOpenSpans() {
+    if (openSpans.size <= maxOpenSpans) return
+    // Close oldest spans as "expired"
+    let toDrop = Math.floor(openSpans.size / 2)
+    for (const [key, span] of openSpans) {
+      if (toDrop-- <= 0) break
+      closeSpan(span, "expired")
+      openSpans.delete(key)
+    }
+  }
+
+  function startSpan(name, attributes = {}, parentSpanId = null, timestamp = null) {
+    if (!currentTraceId) currentTraceId = `trace_${randomUUID().slice(0, 12)}`
+    const span = {
+      traceId: currentTraceId,
+      spanId: newSpanId(),
+      parentSpanId,
+      name,
+      startTime: timestamp || Date.now(),
+      endTime: null,
+      duration: null,
+      attributes,
+      status: "ok"
+    }
+    return span
+  }
+
+  function closeSpan(span, status = "ok", timestamp = null) {
+    span.endTime = timestamp || Date.now()
+    span.duration = span.endTime - span.startTime
+    span.status = status
+    traces.push(span)
+    if (traces.length > maxTraces) traces.shift()
+  }
+
+  function handleEvent(event) {
+    const { type, payload, turnId, sessionId, timestamp } = event
+
+    if (type === EVENT_TYPES.TURN_START) {
+      const key = `turn:${turnId}`
+      if (turnId && openSpans.has(key)) {
+        closeSpan(openSpans.get(key), "error", timestamp)
+        openSpans.delete(key)
+      }
+      const span = startSpan("turn", { turnId, sessionId }, null, timestamp)
+      if (turnId) openSpans.set(key, span)
+      pruneOpenSpans()
+    }
+
+    if (type === EVENT_TYPES.TURN_FINISH) {
+      const key = `turn:${turnId}`
+      const span = openSpans.get(key)
+      if (span) {
+        closeSpan(span, "ok", timestamp)
+        openSpans.delete(key)
+      }
+    }
+
+    if (type === EVENT_TYPES.TURN_ERROR) {
+      const key = `turn:${turnId}`
+      const span = openSpans.get(key)
+      if (span) {
+        span.attributes.error = payload?.error || "unknown"
+        closeSpan(span, "error", timestamp)
+        openSpans.delete(key)
+      }
+    }
+
+    if (type === EVENT_TYPES.LONGAGENT_STAGE_STARTED) {
+      const stageId = payload?.stageId
+      if (stageId) {
+        const span = startSpan("stage", { stageId, sessionId }, null, timestamp)
+        openSpans.set(`stage:${stageId}`, span)
+        pruneOpenSpans()
+      }
+    }
+
+    if (type === EVENT_TYPES.LONGAGENT_STAGE_FINISHED) {
+      const stageId = payload?.stageId
+      const key = `stage:${stageId}`
+      const span = openSpans.get(key)
+      if (span) {
+        span.attributes.successCount = payload?.successCount
+        span.attributes.failCount = payload?.failCount
+        closeSpan(span, payload?.allSuccess ? "ok" : "error", timestamp)
+        openSpans.delete(key)
+      }
+    }
+
+    if (type === EVENT_TYPES.LONGAGENT_PHASE_CHANGED) {
+      if (phaseSpan.current) {
+        closeSpan(phaseSpan.current, "ok", timestamp)
+      }
+      const span = startSpan("phase", {
+        phase: payload?.phase || payload?.newPhase,
+        sessionId
+      }, null, timestamp)
+      phaseSpan.current = span
+    }
+  }
+
+  function getTraces() {
+    const result = [...traces]
+    if (phaseSpan.current) result.push({ ...phaseSpan.current, status: "open" })
+    return result
+  }
+
+  function exportTraces(format = "json") {
+    const all = getTraces()
+    if (format === "json") return JSON.stringify(all, null, 2)
+    return JSON.stringify(all)
+  }
+
+  function reset() {
+    traces.length = 0
+    openSpans.clear()
+    phaseSpan.current = null
+    currentTraceId = null
+  }
+
+  return { handleEvent, getTraces, exportTraces, reset }
+}