trajectories 0.0.0 → 0.1.1

package/legacy/src/native/kimi.ts

@@ -0,0 +1,706 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import type { Diagnostic } from "@letta-ai/trajectory";
+import type { DiscoveredSession } from "../types.js";
+import {
+  MAX_NATIVE_BYTES, MAX_NATIVE_RECORDS, NativeInputError, nativeByteLimit, object, readBoundedText,
+  reportNativeError, safeNativeId, type NativeDiscoveryOptions, type NativeReadOptions, type NativeTranscript,
+} from "./common.js";
+
+/**
+ * Kimi CLI keeps one directory per session under
+ * `~/.kimi/sessions/<workspace-md5>/<session-uuid>/`. `wire.jsonl` is the
+ * transcript source of truth: an append-only event stream
+ * (`{timestamp, message:{type, payload}}`, protocol stamp on line 1) whose user
+ * turns are `TurnBegin`, whose prose is `ContentPart`, whose tool calls and
+ * results are `ToolCall` / `ToolResult` rows keyed by call id, and whose
+ * lifecycle rows (`StepBegin`, `StatusUpdate`, …) are state, not conversation.
+ * A session that spawned children holds them under `subagents/<agent-id>/`,
+ * each with its own `wire.jsonl` and a `meta.json`; the parent's own
+ * `SubagentEvent` rows mirror those children's streams. `state.json` is a
+ * metadata sidecar (title) and is absent on interrupted sessions;
+ * `context.jsonl` is compacted working memory, never a source.
+ * Format facts: docs/research/2026-09-16-c10-kimi.md.
+ */
+const KIMI_SESSION_FILE = "wire.jsonl";
+
+/**
+ * The pinned library has no Kimi adapter, so this reader projects the replayed
+ * wire into the Copilot CLI event contract — the documented event-per-line
+ * contract that keeps what a canonical record needs: a native per-row id, a
+ * per-event timestamp, tool calls linked to their results by call id, and a
+ * terminal outcome flag. `source_type` is restored to this source in the
+ * normalizer, so the projection stays a detail of a source the library cannot
+ * read.
+ */
+export const KIMI_PROJECTION_SOURCE = "copilot-cli";
+
+const STATE_FILE = "state.json";
+const META_FILE = "meta.json";
+const REGISTRY_DIRECTORY = "subagents";
+/** `~/.kimi/kimi.json` registers the workspace paths whose MD5 names a sessions subdirectory. */
+const WORKSPACES_FILE = "kimi.json";
+// <root>/<workspace>/<session>/wire.jsonl is the documented layout, and a child
+// adds <session>/subagents/<agent>/wire.jsonl; the spare level holds a listing
+// rooted deeper, without turning discovery into an unbounded walk.
+const MAX_DEPTH = 4;
+const MAX_SIDECAR_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Wire events Kimi writes beside the conversation: step, stream, turn boundary,
+ * and context state.
+ */
+const LIFECYCLE_KINDS: Record<string, true> = {
+  StepBegin: true,
+  StepInterrupted: true,
+  ToolCallPart: true,
+  StatusUpdate: true,
+  TurnEnd: true,
+  ApprovalRequest: true,
+  ApprovalResponse: true,
+  CompactionBegin: true,
+  CompactionEnd: true,
+};
+
+export function kimiRoots(): string[] {
+  return [join(homedir(), ".kimi", "sessions")];
+}
+
+interface KimiState {
+  title?: string;
+}
+
+function nonblank(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+/**
+ * The sidecar is metadata, not transcript: a missing, oversized, or malformed
+ * state costs the title and never the session, so every failure here degrades
+ * instead of throwing.
+ */
+function readState(path: string): { state: KimiState; unreadable: boolean } {
+  if (!existsSync(path)) return { state: {}, unreadable: false };
+  try {
+    const value: unknown = JSON.parse(readBoundedText(path, MAX_SIDECAR_BYTES));
+    if (!object(value)) return { state: {}, unreadable: true };
+    return { state: { title: nonblank(value.custom_title) }, unreadable: false };
+  } catch {
+    return { state: {}, unreadable: true };
+  }
+}
+
+/**
+ * A child agent's own directory records what the parent asked it to be:
+ * `subagent_type` and the launch `description`. Unreadable or absent, it costs
+ * the child's title and nickname, never the child.
+ */
+export function readKimiSubagentMeta(directory: string): { agentType?: string; description?: string } {
+  const path = join(directory, META_FILE);
+  if (!existsSync(path)) return {};
+  try {
+    const value: unknown = JSON.parse(readBoundedText(path, MAX_SIDECAR_BYTES));
+    if (!object(value)) return {};
+    return { agentType: nonblank(value.subagent_type), description: nonblank(value.description) };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The session's workspace path is not written in the session: the directory
+ * that holds it is the MD5 of the path Kimi was launched in, and
+ * `kimi.json` (beside the sessions root) registers those paths. Hashing each
+ * registered path finds the one this session was made from; a workspace missing
+ * from the registry (deleted, renamed, or never registered) leaves the cwd
+ * unknown instead of guessing, and the shared registry is never fatal.
+ */
+function readWorkspaceCwd(sessionPath: string): string | undefined {
+  const sessionDirectory = dirname(sessionPath);
+  // A child's directory is <session>/subagents/<agent>/; its workspace is the session's.
+  const owner = basename(dirname(sessionDirectory)) === REGISTRY_DIRECTORY
+    ? dirname(dirname(dirname(sessionDirectory)))
+    : dirname(sessionDirectory);
+  const workspace = basename(owner);
+  if (!/^[0-9a-f]{32}$/.test(workspace)) return undefined;
+  // The registry sits beside the root that holds the workspace directories.
+  const registry = join(dirname(dirname(owner)), WORKSPACES_FILE);
+  if (!existsSync(registry)) return undefined;
+  try {
+    const value: unknown = JSON.parse(readBoundedText(registry, MAX_SIDECAR_BYTES));
+    if (!object(value) || !Array.isArray(value.work_dirs)) return undefined;
+    for (const entry of value.work_dirs) {
+      if (!object(entry)) continue;
+      const path = nonblank(entry.path);
+      if (path && createHash("md5").update(path).digest("hex") === workspace) return path;
+    }
+  } catch {
+    // A registry that cannot be read costs the cwd, not the transcript.
+  }
+  return undefined;
+}
+
+export function discoverKimiSessions(roots: string[], options: NativeDiscoveryOptions): DiscoveredSession[] {
+  if (!Number.isSafeInteger(options.limit) || options.limit < 1) throw new RangeError("Kimi discovery limit must be positive.");
+  const items: DiscoveredSession[] = [];
+  const seen = new Set<string>();
+
+  function walk(path: string, depth: number): void {
+    if (seen.has(path)) return;
+    seen.add(path);
+    try {
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink() || stat.isFile()) return;
+      if (depth > MAX_DEPTH) {
+        options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Kimi discovery reached its directory depth limit." });
+        return;
+      }
+      const entries = readdirSync(path, { withFileTypes: true });
+      const names = new Set(entries.map((entry) => entry.name));
+      if (names.has(KIMI_SESSION_FILE)) {
+        // A directory reached through a `subagents/` registry is a child: the
+        // walk only gets there when its parent has no wire to list it (a partial
+        // rsync, a deleted transcript) or when the scan is rooted inside the
+        // registry. It is listed with the parent its path names, exactly as
+        // `collectChildren` lists it, so one transcript keeps one ledger id while
+        // the parent's wire comes and goes.
+        const parent = basename(dirname(path)) === REGISTRY_DIRECTORY ? nonblank(basename(dirname(dirname(path)))) : undefined;
+        const listing = sessionListing(path, options, parent ? { id: parent } : undefined);
+        if (!listing) return;
+        items.push(listing);
+        // A child's transcript is a session of its own, registered under the
+        // parent that spawned it. Discovery does not descend into a session
+        // otherwise: its other subdirectories hold that session's own files.
+        if (names.has(REGISTRY_DIRECTORY)) collectChildren(path, listing.id, options, items);
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.isDirectory()) walk(join(path, entry.name), depth + 1);
+      }
+    } catch (error) {
+      if (object(error) && error.code === "ENOENT" && depth === 0) return;
+      reportNativeError(options, path);
+    }
+  }
+
+  for (const root of roots) walk(resolve(root), 0);
+
+  const ordered = items
+    .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "") || a.path.localeCompare(b.path));
+  const nativeIds = new Set<string>();
+  const deduplicated = ordered.filter((item) => {
+    if (nativeIds.has(item.id)) return false;
+    nativeIds.add(item.id);
+    return true;
+  });
+  return options.select ? options.select(deduplicated) : deduplicated.slice(0, options.limit);
+}
+
+function sidecarSize(directory: string, name: string): number {
+  try {
+    return statSync(join(directory, name)).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * One wire-bearing directory as a listing. A session's own directory keys it by
+ * its name; a child is keyed by the parent its path names
+ * (`<parent-uuid>:<agent-id>`) because an agent id is unique only within its
+ * parent. Every file a listing's snapshot covers is counted here — the wire and
+ * the sidecars beside it, present or not — so two callers cannot disagree about
+ * a session's size, and the title comes from `state.json` when it exists and the
+ * caller's own metadata (a child's `meta.json` description) otherwise.
+ */
+function sessionListing(
+  directory: string,
+  options: NativeDiscoveryOptions,
+  parent?: { id: string; toolCallId?: string; title?: string },
+): DiscoveredSession | null {
+  const id = parent ? `${parent.id}:${basename(directory)}` : basename(directory);
+  if (!safeNativeId(id)) {
+    options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: directory, message: "Kimi session has an invalid native session ID." });
+    return null;
+  }
+  try {
+    const wire = statSync(join(directory, KIMI_SESSION_FILE));
+    const title = readState(join(directory, STATE_FILE)).state.title ?? parent?.title;
+    return {
+      id,
+      source: "kimi",
+      path: join(directory, KIMI_SESSION_FILE),
+      updatedAt: wire.mtime.toISOString(),
+      sizeBytes: wire.size + sidecarSize(directory, STATE_FILE) + sidecarSize(directory, META_FILE),
+      ...(title ? { title } : {}),
+      native: {
+        kind: "kimi-wire",
+        ...(parent ? { parentSessionId: parent.id } : {}),
+        ...(parent?.toolCallId ? { parentToolUseId: parent.toolCallId } : {}),
+      },
+    };
+  } catch (error) {
+    if (object(error) && error.code === "ENOENT") return null;
+    reportNativeError(options, directory);
+    return null;
+  }
+}
+
+/**
+ * A session's children are sessions: each `<parent>/subagents/<agent>/wire.jsonl`
+ * is listed with its own transcript, its parent from the path it is nested in
+ * (`kimi:<parent-uuid>:<agent-id>` — an agent id is short and only unique
+ * within its parent), and the tool call that spawned it when the parent's wire
+ * binds the two. The parent's `SubagentEvent` rows carry
+ * `parent_tool_call_id` → `agent_id`; that binding is read here, once per
+ * parent, so ingest never re-walks the store.
+ */
+function collectChildren(
+  parentDirectory: string,
+  parentId: string,
+  options: NativeDiscoveryOptions,
+  items: DiscoveredSession[],
+): void {
+  const registry = join(parentDirectory, REGISTRY_DIRECTORY);
+  let entries: string[];
+  try {
+    entries = readdirSync(registry);
+  } catch {
+    reportNativeError(options, registry);
+    return;
+  }
+  const bindings = readSpawnBindings(join(parentDirectory, KIMI_SESSION_FILE), new Set(entries), options);
+  for (const entry of entries) {
+    if (!safeNativeId(entry)) continue;
+    const directory = join(registry, entry);
+    try {
+      // A registry entry is read only where it really is a directory: the store
+      // walk does not follow symlinks, and neither does this.
+      const stat = lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) continue;
+      const listing = sessionListing(directory, options, {
+        id: parentId,
+        toolCallId: bindings.get(entry),
+        title: readKimiSubagentMeta(directory).description,
+      });
+      if (listing) items.push(listing);
+    } catch (error) {
+      if (object(error) && error.code === "ENOENT") continue;
+      reportNativeError(options, directory);
+    }
+  }
+}
+
+/**
+ * The parent-side binding of a spawned child to the tool call that spawned it:
+ * `SubagentEvent` rows name both `agent_id` and `parent_tool_call_id`, and the
+ * first binding for a registered child wins. Nothing else in the store carries
+ * this edge, so it is read while the store is walked; a wire too large to read
+ * or a child bound later costs the binding, not the child's parent.
+ */
+function readSpawnBindings(
+  wirePath: string,
+  agents: Set<string>,
+  options: NativeDiscoveryOptions,
+): Map<string, string> {
+  const bindings = new Map<string, string>();
+  if (agents.size === 0) return bindings;
+  let text: string;
+  try {
+    text = readBoundedText(wirePath, MAX_NATIVE_BYTES);
+  } catch {
+    options.onDiagnostic?.({
+      code: "incomplete_evidence", sourcePath: wirePath,
+      message: "Kimi subagent spawn bindings were not read: the parent's wire is unreadable or over the byte limit.",
+    });
+    return bindings;
+  }
+  for (const line of text.split("\n")) {
+    if (bindings.size === agents.size) break;
+    if (!line.includes("SubagentEvent")) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const message = object(parsed) && object(parsed.message) ? parsed.message : null;
+    const payload = message && message.type === "SubagentEvent" && object(message.payload) ? message.payload : null;
+    if (!payload) continue;
+    const agentId = nonblank(payload.agent_id);
+    const toolCallId = nonblank(payload.parent_tool_call_id);
+    if (!agentId || !toolCallId || !agents.has(agentId) || !safeNativeId(toolCallId)) continue;
+    if (!bindings.has(agentId)) bindings.set(agentId, toolCallId);
+  }
+  return bindings;
+}
+
+type Row = Record<string, unknown>;
+
+interface WireEvent {
+  /** 1-based line number: an append-only file only ever grows at its end. */
+  line: number;
+  timestamp: string | null;
+  kind: string;
+  payload: Record<string, unknown>;
+}
+
+interface Skips {
+  lifecycle: Map<string, number>;
+  mirror: number;
+  content: number;
+  unknown: Map<string, number>;
+  /** Result rows for a call whose result was already projected. */
+  repeats: number;
+  invalidLines: number;
+  malformedLines: number;
+}
+
+function isoSeconds(value: unknown): string | null {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
+  return new Date(value * 1000).toISOString();
+}
+
+/**
+ * Decode the wire's own rows. The protocol stamp on line 1
+ * (`{"type":"metadata","protocol_version":"1.10"}`) is the file's header, not an
+ * event: it is neither projected nor counted as a skip. Kimi appends while it
+ * runs, so a torn last line or a line from a newer protocol is counted, never
+ * fatal: the transcript is what the prefix holds.
+ */
+function parseWire(text: string, skips: Skips): WireEvent[] {
+  const events: WireEvent[] = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line || !line.trim()) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      skips.invalidLines += 1;
+      continue;
+    }
+    if (!object(parsed)) {
+      skips.malformedLines += 1;
+      continue;
+    }
+    if (parsed.type === "metadata") continue;
+    const message = object(parsed.message) ? parsed.message : null;
+    const kind = message ? nonblank(message.type) : undefined;
+    if (!message || !kind) {
+      skips.malformedLines += 1;
+      continue;
+    }
+    events.push({
+      line: index + 1,
+      timestamp: isoSeconds(parsed.timestamp),
+      kind,
+      payload: object(message.payload) ? message.payload : {},
+    });
+  }
+  return events;
+}
+
+function asJsonObject(text: string): Record<string, unknown> | null {
+  if (!text.trim()) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return object(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A tool call's arguments as one JSON object. Kimi announces a call with the
+ * arguments known at that moment, so the row usually holds only a *prefix* of
+ * them (220 of 309 calls on this host open an object they do not close): the
+ * remainder streams into `ToolCallPart` rows that follow, interleaved with other
+ * events. The call's arguments are therefore the *shortest prefix* of its own
+ * argument bytes — the row's text plus the fragments up to the next call — that
+ * parses as an object.
+ *
+ * Fragments carry no call id, so they are attributed *positionally*: a fragment
+ * that follows another call's row belongs to that later call's window. The rule
+ * is exact while the protocol keeps a call's fragments ahead of the next
+ * announcement — 309/309 real calls here, none starved — but a straggler that
+ * completed an earlier call after a later one was announced would be attributed
+ * to the later call, and if the join parsed, that call would carry a
+ * wrong-but-valid object. Nothing in the wire can tell the two apart; the
+ * contract is the position. A call whose window never completes keeps the prefix
+ * the row holds, and its `tool_arguments_json` stays verbatim rather than
+ * invented.
+ */
+function resolveArguments(events: WireEvent[], index: number, raw: unknown): unknown {
+  const text = typeof raw === "string" ? raw : "";
+  const announced = asJsonObject(text);
+  if (announced) return announced;
+  let joined = text;
+  for (let next = index + 1; next < events.length && events[next].kind !== "ToolCall"; next += 1) {
+    if (events[next].kind !== "ToolCallPart") continue;
+    const part = events[next].payload.arguments_part;
+    if (typeof part !== "string" || !part) continue;
+    joined += part;
+    const parsed = asJsonObject(joined);
+    if (parsed) return parsed;
+  }
+  return text || {};
+}
+
+/** A tool result's text: its output, or the message beside it when the output is empty. */
+function resultText(returned: Record<string, unknown>): string {
+  const output = typeof returned.output === "string" ? returned.output : null;
+  if (output && output.trim()) return output;
+  const message = typeof returned.message === "string" ? returned.message : null;
+  if (message && message.trim()) return message;
+  if (output) return output;
+  if (returned.output === undefined || returned.output === null) return message ?? "";
+  return typeof returned.output === "string" ? returned.output : JSON.stringify(returned.output);
+}
+
+/**
+ * Replay the wire into the projection lane, in file order.
+ *
+ * `TurnBegin` is a user turn, `ContentPart` is one complete part (a `think` part
+ * is reasoning, a `text` part is assistant prose) — unlike Grok's token
+ * fragments, these are whole blocks, so nothing is concatenated across rows —
+ * `ToolCall` is the call, and `ToolResult` is its outcome keyed by call id with
+ * `ok = !return_value.is_error`. `SubagentEvent` rows mirror a child's stream
+ * that the child's own `wire.jsonl` holds, so they are state here; lifecycle
+ * rows are state too. Every skip is typed and counted.
+ */
+function replayWire(text: string, sessionId: string, cwd: string | undefined, limit: number): {
+  rows: Row[]; skips: Skips; first: string | null;
+} {
+  const skips: Skips = {
+    lifecycle: new Map(), mirror: 0, content: 0, unknown: new Map(), repeats: 0, invalidLines: 0, malformedLines: 0,
+  };
+  const events = parseWire(text, skips);
+  const rows: Row[] = [];
+  // One result per call id: a re-emitted result row (a resumed or retried call)
+  // must not put two records behind one call.
+  const results = new Set<string>();
+  let written = 0;
+  let first: string | null = null;
+
+  function emit(row: Row): void {
+    written += Buffer.byteLength(JSON.stringify(row)) + 1;
+    if (written > limit) throw new NativeInputError("Kimi transcript exceeds the native byte limit.");
+    rows.push(row);
+  }
+
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    // A row without a wire id keeps a stable identity from its own line: the
+    // file is append-only, so a line number never moves.
+    const id = `kimi-line-${event.line}`;
+    const at = event.timestamp ? { timestamp: event.timestamp } : {};
+    first ??= event.timestamp;
+    if (event.kind === "TurnBegin") {
+      // A top-level turn carries content parts; a subagent's turn carries its
+      // whole prompt as one string (5/5 children on this host), git context and all.
+      const input = event.payload.user_input;
+      const parts = typeof input === "string"
+        ? [input]
+        : Array.isArray(input)
+          ? input
+            .map((part) => (object(part) && part.type === "text" && typeof part.text === "string" ? part.text : null))
+            .filter((part): part is string => part !== null && part.length > 0)
+          : [];
+      if (!parts.length || !parts.some((part) => part.trim().length > 0)) {
+        skips.content += 1;
+        continue;
+      }
+      emit({
+        type: "hook.start", id, ...at,
+        data: {
+          hookType: "userPromptSubmitted",
+          input: { prompt: parts.join("\n"), sessionId, ...(cwd ? { cwd } : {}) },
+        },
+      });
+      continue;
+    }
+    if (event.kind === "ContentPart") {
+      const partType = event.payload.type;
+      const raw = partType === "think" ? event.payload.think : partType === "text" ? event.payload.text : null;
+      const part = typeof raw === "string" ? raw : null;
+      if (!part || !part.trim()) {
+        skips.content += 1;
+        continue;
+      }
+      emit({
+        type: "assistant.message", id, ...at,
+        data: partType === "think" ? { reasoningText: part } : { content: part },
+      });
+      continue;
+    }
+    if (event.kind === "ToolCall") {
+      const callId = event.payload.id;
+      if (!safeNativeId(callId)) {
+        skips.unknown.set("ToolCall_without_id", (skips.unknown.get("ToolCall_without_id") ?? 0) + 1);
+        continue;
+      }
+      const fn = object(event.payload.function) ? event.payload.function : {};
+      const name = nonblank(fn.name);
+      emit({
+        type: "assistant.message", id, ...at,
+        data: {
+          toolRequests: [{
+            toolCallId: callId,
+            ...(name ? { name } : {}),
+            arguments: resolveArguments(events, index, fn.arguments),
+          }],
+        },
+      });
+      continue;
+    }
+    if (event.kind === "ToolResult") {
+      const callId = event.payload.tool_call_id;
+      if (!safeNativeId(callId)) {
+        skips.unknown.set("ToolResult_without_id", (skips.unknown.get("ToolResult_without_id") ?? 0) + 1);
+        continue;
+      }
+      if (results.has(callId)) {
+        skips.repeats += 1;
+        continue;
+      }
+      results.add(callId);
+      const returned = object(event.payload.return_value) ? event.payload.return_value : {};
+      const ok = returned.is_error !== true;
+      const output = resultText(returned);
+      emit({
+        type: "tool.execution_complete", id, ...at,
+        data: {
+          toolCallId: callId,
+          success: ok,
+          ...(ok ? { result: { content: output } } : { error: { message: output } }),
+        },
+      });
+      continue;
+    }
+    if (event.kind === "SubagentEvent") {
+      skips.mirror += 1;
+      continue;
+    }
+    if (LIFECYCLE_KINDS[event.kind] === true) {
+      skips.lifecycle.set(event.kind, (skips.lifecycle.get(event.kind) ?? 0) + 1);
+      continue;
+    }
+    skips.unknown.set(event.kind, (skips.unknown.get(event.kind) ?? 0) + 1);
+  }
+  return { rows, skips, first };
+}
+
+function tally(values: Map<string, number>): number {
+  let total = 0;
+  for (const count of values.values()) total += count;
+  return total;
+}
+
+function named(values: Map<string, number>, limit = 4): string {
+  return [...values.keys()].sort().slice(0, limit).join(", ");
+}
+
+/** Every skip is typed and counted, so a dropped wire event never vanishes silently. */
+function skipDiagnostics(skips: Skips): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  if (skips.lifecycle.size) {
+    diagnostics.push({
+      code: "noise_record_dropped",
+      message: `Skipped ${tally(skips.lifecycle)} Kimi lifecycle wire event(s) (${named(skips.lifecycle)}).`,
+      count: tally(skips.lifecycle),
+    });
+  }
+  if (skips.mirror) {
+    diagnostics.push({
+      code: "noise_record_dropped",
+      message: `Skipped ${skips.mirror} Kimi subagent event mirror(s); the child session's own wire holds that transcript.`,
+      count: skips.mirror,
+    });
+  }
+  if (skips.unknown.size) {
+    diagnostics.push({
+      code: "noise_record_dropped",
+      message: `Skipped ${tally(skips.unknown)} Kimi wire event(s) with no supported transcript shape (${named(skips.unknown)}).`,
+      count: tally(skips.unknown),
+    });
+  }
+  if (skips.repeats) {
+    diagnostics.push({
+      code: "noise_record_dropped",
+      message: `Skipped ${skips.repeats} repeated Kimi tool result row(s); the call's first result is its outcome.`,
+      count: skips.repeats,
+    });
+  }
+  if (skips.content) {
+    diagnostics.push({
+      code: "noise_record_dropped",
+      message: `Skipped ${skips.content} Kimi message event(s) with no text part.`,
+      count: skips.content,
+    });
+  }
+  if (skips.invalidLines) {
+    diagnostics.push({
+      code: "invalid_json_line",
+      message: `Skipped ${skips.invalidLines} invalid JSON line(s) in the Kimi wire protocol.`,
+      count: skips.invalidLines,
+    });
+  }
+  if (skips.malformedLines) {
+    diagnostics.push({
+      code: "invalid_json_line",
+      message: `Skipped ${skips.malformedLines} Kimi wire line(s) with no event object.`,
+      count: skips.malformedLines,
+    });
+  }
+  return diagnostics;
+}
+
+export function readKimiSession(item: DiscoveredSession, options: NativeReadOptions = {}): NativeTranscript {
+  if (!safeNativeId(item.id)) throw new NativeInputError("Unsupported Kimi native session ID.");
+  if (item.native && item.native.kind !== "kimi-wire") throw new NativeInputError("Unsupported Kimi native session.");
+  const limit = nativeByteLimit(options);
+  const text = readBoundedText(item.path, limit);
+  const directory = dirname(item.path);
+  const { state, unreadable } = readState(join(directory, STATE_FILE));
+  const cwd = readWorkspaceCwd(item.path);
+  const replay = replayWire(text, item.id, cwd, limit);
+  if (replay.rows.length > MAX_NATIVE_RECORDS) throw new NativeInputError("Kimi session exceeds the native record limit.");
+
+  // The listing's own id is stamped on the envelope, so the session keeps its
+  // group even when the wire holds nothing else this reader can project.
+  const rows: Row[] = [{
+    type: "session.start",
+    ...(replay.first ? { timestamp: replay.first } : {}),
+    data: {
+      sessionId: item.id,
+      ...(replay.first ? { startTime: replay.first } : {}),
+      context: { ...(cwd ? { cwd } : {}) },
+    },
+  }, ...replay.rows];
+
+  const diagnostics = skipDiagnostics(replay.skips);
+  if (unreadable) {
+    diagnostics.push({
+      code: "invalid_json_line",
+      message: "Ignored the Kimi session state sidecar: it is not a readable JSON object, so the title stays unset.",
+    });
+  }
+
+  const title = state.title ?? item.title;
+  return {
+    transcript: `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`,
+    ...(title ? { title } : {}),
+    ...(cwd ? { cwd } : {}),
+    ...(diagnostics.length ? { diagnostics } : {}),
+  };
+}
+
+/** The files whose change invalidates a Kimi session's snapshot. */
+export function kimiSessionFiles(item: DiscoveredSession): string[] {
+  const directory = dirname(item.path);
+  return [item.path, join(directory, STATE_FILE), join(directory, META_FILE)];
+}