@halofy/agent-connect 0.5.1 → 0.7.0

package/src/skills-sync.mjs

@@ -0,0 +1,266 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+
+/**
+ * Badge-delivered skills (CONTRACTS-S16-SKILL-TRACKING D37–D39 on the signed
+ * badge runtime). The badge resolves, server-side, every approved and vetted
+ * skill on its team + org chain; this module mirrors that set into the host's
+ * own skills folder and keeps it there.
+ *
+ * Every managed copy is written as `<skillsRoot>/<skillKey>/SKILL.md`, the
+ * layout Claude Code and Codex both read. A manifest under the runtime home
+ * records what was written (id, sha, file digest) so the next check-in can
+ * report it, drift can be repaired, and a withdrawn skill can be quarantined
+ * — moved, never deleted (D7 on the client mirror).
+ *
+ * A folder this runtime did not create is never touched: an employee's own
+ * skill with a colliding name is reported as a conflict and left alone.
+ */
+
+export const STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+const SKILL_KEY = /^[a-z0-9][a-z0-9._-]{0,199}$/i;
+const MANAGED_MARKER = "content_sha256:";
+
+/**
+ * The user-level Agent Skills folder each host scans, `<dir>/<name>/SKILL.md`.
+ * Every host also reads a workspace folder and most read the generic
+ * `~/.agents/skills`; the badge writes the host's own brand folder so one
+ * badge maps to one host and nothing leaks into a host the badge was not
+ * issued for. Verified 2026-09-04: Claude Code + Codex by install; Gemini CLI
+ * 0.58 (`GEMINI_CLI_HOME` replaces the HOME directory, so the folder is
+ * `<home>/.gemini/skills`) and Kimi Code 0.40 (`KIMI_CODE_HOME || ~/.kimi-code`;
+ * `~/.kimi/skills` is its legacy tree) from the installed binaries; Cursor,
+ * VS Code Copilot, and Cline from their published docs.
+ */
+export function managedSkillsDirectory(clientKind, { home = homedir(), env = process.env } = {}) {
+  switch (clientKind) {
+    case "claude-code": return join(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), "skills");
+    case "codex": return join(env.CODEX_HOME || join(home, ".codex"), "skills");
+    case "cursor": return join(home, ".cursor", "skills");
+    case "gemini-cli": return join(env.GEMINI_CLI_HOME || home, ".gemini", "skills");
+    case "kimi-cli": return join(env.KIMI_CODE_HOME || join(home, ".kimi-code"), "skills");
+    case "vscode": return join(home, ".copilot", "skills");
+    case "cline": return join(home, ".cline", "skills");
+    default: return null;
+  }
+}
+
+export function skillsManifestPath(root, installationId) {
+  return join(root, `skills-${installationId}.json`);
+}
+
+function digest(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+function safeKey(skillKey) {
+  return typeof skillKey === "string" && SKILL_KEY.test(skillKey) && !skillKey.includes("..");
+}
+
+async function pathState(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function readText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** Move a managed copy aside with its bytes intact; never `rm`. */
+async function quarantine(skillsRoot, quarantineRoot, skillKey, now) {
+  const from = join(skillsRoot, skillKey);
+  if (!(await pathState(from))) return null;
+  await ensurePrivateDirectory(quarantineRoot);
+  const to = join(quarantineRoot, `${skillKey}-${now.toISOString().replace(/[:.]/g, "-")}`);
+  await rename(from, to);
+  return to;
+}
+
+/**
+ * A folder is "ours" when the manifest lists it, or when its SKILL.md carries
+ * the kernel export frontmatter. Anything else is the employee's own skill.
+ */
+async function isManaged(skillsRoot, skillKey, manifestEntry) {
+  if (manifestEntry) return true;
+  const body = await readText(join(skillsRoot, skillKey, "SKILL.md"));
+  return typeof body === "string" && body.startsWith("---\n") && body.includes(`\n${MANAGED_MARKER}`);
+}
+
+export async function loadSkillsManifest(root, installationId) {
+  const manifest = await readJson(skillsManifestPath(root, installationId), null);
+  if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.installs)) {
+    return { version: 1, installationId, installs: [], lastCheckinAt: null };
+  }
+  return manifest;
+}
+
+/**
+ * One sync pass. Never throws for server or filesystem trouble on a single
+ * skill; the summary names what happened so callers (installer, SessionStart
+ * hooks) can report it. A failed check-in leaves installed copies usable
+ * until the 7-day staleness allowance runs out, then quarantines them (D37).
+ */
+export async function syncManagedSkills({
+  connection,
+  transport,
+  root,
+  home = homedir(),
+  env = process.env,
+  now = () => new Date(),
+}) {
+  const clientKind = connection.clientKind;
+  const skillsRoot = managedSkillsDirectory(clientKind, { home, env });
+  const summary = {
+    supported: skillsRoot !== null,
+    skillsRoot,
+    checkedIn: false,
+    installed: [],
+    updated: [],
+    quarantined: [],
+    conflicts: [],
+    unchanged: [],
+    errors: [],
+  };
+  if (!skillsRoot) return summary;
+
+  const manifestPath = skillsManifestPath(root, connection.installationId);
+  const quarantineRoot = join(root, "skills-quarantine", connection.installationId);
+  const manifest = await loadSkillsManifest(root, connection.installationId);
+  const byId = new Map(manifest.installs.map((entry) => [entry.skillId, entry]));
+  const current = now();
+
+  let response;
+  try {
+    response = await transport.skillsCheckin(manifest.installs.map(({ skillId, sha }) => ({ skillId, sha })));
+    summary.checkedIn = true;
+  } catch (error) {
+    summary.errors.push({ stage: "checkin", code: error?.code || "runtime_unavailable" });
+    const last = manifest.lastCheckinAt ? Date.parse(manifest.lastCheckinAt) : NaN;
+    if (Number.isFinite(last) && current.getTime() - last > STALE_AFTER_MS) {
+      for (const entry of manifest.installs) {
+        try {
+          const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
+          if (moved) summary.quarantined.push({ skillKey: entry.skillKey, reason: "stale_checkin", to: moved });
+        } catch (fsError) {
+          summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: fsError?.code || "fs_error" });
+        }
+      }
+      manifest.installs = [];
+      await writePrivateFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    return summary;
+  }
+
+  const wanted = new Map();
+  for (const skill of Array.isArray(response?.skills) ? response.skills : []) {
+    if (safeKey(skill.skillKey)) wanted.set(skill.skillId, skill);
+  }
+
+  // 1. Withdrawn copies: revoked / unknown verdicts, and anything the manifest
+  //    lists that the badge no longer resolves.
+  const verdicts = new Map((Array.isArray(response?.items) ? response.items : []).map((item) => [item.skillId, item]));
+  const survivors = [];
+  for (const entry of manifest.installs) {
+    const verdict = verdicts.get(entry.skillId);
+    const status = verdict?.status;
+    const withdrawn = status === "revoked" || status === "unknown" || (!wanted.has(entry.skillId) && status !== "stale");
+    if (!withdrawn) { survivors.push(entry); continue; }
+    try {
+      const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
+      summary.quarantined.push({ skillKey: entry.skillKey, reason: status || "not_resolved", to: moved });
+    } catch (error) {
+      summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: error?.code || "fs_error" });
+      survivors.push(entry);
+    }
+  }
+  manifest.installs = survivors;
+
+  // 2. Missing, stale, or drifted copies: fetch through the governed export
+  //    gate and write. A stale entry keyed on a superseded row is re-keyed
+  //    to the row that replaced it.
+  for (const entry of manifest.installs) {
+    const verdict = verdicts.get(entry.skillId);
+    if (verdict?.status === "stale" && verdict.currentSkillId && !wanted.has(entry.skillId)) {
+      entry.skillId = verdict.currentSkillId;
+    }
+  }
+  const next = [];
+  for (const skill of wanted.values()) {
+    const entry = manifest.installs.find((candidate) => candidate.skillId === skill.skillId);
+    const dir = join(skillsRoot, skill.skillKey);
+    const file = join(dir, "SKILL.md");
+    const onDisk = await readText(file);
+    const intact = entry && typeof onDisk === "string" && digest(onDisk) === entry.fileSha256;
+    if (entry && entry.sha === skill.sha && intact) {
+      summary.unchanged.push(skill.skillKey);
+      next.push({ ...entry, lastCheckinAt: current.toISOString() });
+      continue;
+    }
+    if (!(await isManaged(skillsRoot, skill.skillKey, entry)) && (await pathState(dir))) {
+      summary.conflicts.push({ skillKey: skill.skillKey, reason: "unmanaged_folder" });
+      continue;
+    }
+    try {
+      const exported = await transport.skillDownload(skill.skillId);
+      const content = typeof exported?.content === "string" ? exported.content : null;
+      if (!content) throw Object.assign(new Error("skill export was empty"), { code: "empty_export" });
+      await mkdir(dir, { recursive: true });
+      await writePrivateFile(file, content);
+      const record = {
+        skillId: skill.skillId,
+        skillKey: skill.skillKey,
+        sha: skill.sha,
+        fileSha256: digest(content),
+        namespace: skill.namespace,
+        installedAt: entry?.installedAt || current.toISOString(),
+        lastCheckinAt: current.toISOString(),
+      };
+      next.push(record);
+      (entry ? summary.updated : summary.installed).push(skill.skillKey);
+    } catch (error) {
+      summary.errors.push({ stage: "download", skillKey: skill.skillKey, code: error?.code || "runtime_unavailable" });
+      if (entry) next.push(entry);
+    }
+  }
+  manifest.installs = next;
+  manifest.lastCheckinAt = current.toISOString();
+  manifest.clientKind = clientKind;
+  await writePrivateFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  // 3. Acknowledge: a second beacon carrying what is now on disk so the
+  //    console's "installed on N badges" reflects this pass, not the last.
+  if (summary.installed.length > 0 || summary.updated.length > 0 || summary.quarantined.length > 0) {
+    try {
+      await transport.skillsCheckin(manifest.installs.map(({ skillId, sha }) => ({ skillId, sha })));
+    } catch (error) {
+      summary.errors.push({ stage: "ack", code: error?.code || "runtime_unavailable" });
+    }
+  }
+  return summary;
+}
+
+/** One-line, content-free summary for installer output and hook stderr. */
+export function describeSkillSync(summary) {
+  if (!summary.supported) return "skills: not managed for this host";
+  const parts = [];
+  if (summary.installed.length) parts.push(`installed ${summary.installed.length}`);
+  if (summary.updated.length) parts.push(`updated ${summary.updated.length}`);
+  if (summary.unchanged.length) parts.push(`unchanged ${summary.unchanged.length}`);
+  if (summary.quarantined.length) parts.push(`quarantined ${summary.quarantined.length}`);
+  if (summary.conflicts.length) parts.push(`skipped ${summary.conflicts.length} unmanaged`);
+  if (summary.errors.length) parts.push(`${summary.errors.length} error${summary.errors.length === 1 ? "" : "s"}`);
+  if (!summary.checkedIn) parts.unshift("check-in unavailable");
+  return `skills (${basename(dirname(summary.skillsRoot))}/${basename(summary.skillsRoot)}): ${parts.join(", ") || "nothing to do"}`;
+}

package/src/transcript-drivers/claude.mjs

@@ -0,0 +1,33 @@
+import {
+  buildClaudeMetadataPayload,
+  claudeMetadataEvent,
+  readClaudeTranscriptSuffix,
+} from "../session.mjs";
+
+/**
+ * Thin delegation over the reviewed Claude Code adapter. The claude path is
+ * frozen — its eventKeys are pinned by the golden fixture test and must stay
+ * byte-identical for server-side dedupe history. Claude Code hooks pass the
+ * transcript path directly, so this driver has no locate step.
+ */
+export const claudeTranscriptDriver = {
+  clientKind: "claude-code",
+  eventKeyNamespace: "claude",
+  usageGapPrefix: "claude:usage-gap:",
+
+  async locate() {
+    return null;
+  },
+
+  readSuffix(path, cursor, sessionHash) {
+    return readClaudeTranscriptSuffix(path, cursor, sessionHash);
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return claudeMetadataEvent(payload);
+  },
+};

package/src/transcript-drivers/codex.mjs

@@ -0,0 +1,188 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  buildClaudeMetadataPayload,
+  hostMetadataEvent,
+  normalizedEvent,
+  usageInt,
+  USAGE_MODEL_PATTERN,
+} from "../session.mjs";
+import { codexHome } from "../host-roots.mjs";
+import {
+  boundedHostSessionId,
+  boundedHostState,
+  boundedMetadataText,
+  completeJsonlLines,
+  containedPath,
+  drainedEndOffset,
+  MAX_DRIVER_SUFFIX_BYTES,
+  readSuffixWindow,
+} from "./shared.mjs";
+
+const NAMESPACE = "codex";
+const PROVIDER_PATTERN = /^[a-z0-9-]{1,64}$/;
+
+/**
+ * Codex rollouts live at
+ * `<codexHome>/sessions/YYYY/MM/DD/rollout-<ts>-<session-id>.jsonl` — the
+ * session id is the filename suffix. The hook payload is never trusted for a
+ * path; only the validated session id is interpolated, and every result is
+ * containment-checked under the codex root.
+ */
+async function locateRollout(root, sessionId) {
+  const sessionsRoot = join(root, "sessions");
+  let names;
+  try {
+    names = await readdir(sessionsRoot, { recursive: true });
+  } catch {
+    return null;
+  }
+  const suffix = `-${sessionId}.jsonl`;
+  const matches = names.filter((name) => {
+    const base = String(name).split(/[\\/]/).pop();
+    return base.startsWith("rollout-") && base.endsWith(suffix);
+  }).sort();
+  if (matches.length === 0) return null;
+  // Timestamped names sort chronologically; take the newest.
+  return containedPath(sessionsRoot, matches[matches.length - 1]);
+}
+
+function usageEventFromTokenCount(info, { model, provider, byteOffset, endOffset, occurredAt }) {
+  const usage = info?.last_token_usage;
+  const input = usageInt(usage?.input_tokens);
+  const output = usageInt(usage?.output_tokens);
+  if (usage === null || typeof usage !== "object" || (input === null && output === null)) {
+    return normalizedEvent({
+      eventKey: `${NAMESPACE}:usage-gap:${byteOffset}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: "usage_unavailable",
+      },
+      sourceEndOffset: endOffset,
+    });
+  }
+  if (model === null) {
+    return normalizedEvent({
+      eventKey: `${NAMESPACE}:usage-gap:${byteOffset}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: "model_unknown",
+      },
+      sourceEndOffset: endOffset,
+    });
+  }
+  const cached = usageInt(usage.cached_input_tokens) ?? 0;
+  const cacheWrite = usageInt(usage.cache_write_input_tokens) ?? 0;
+  // Verified against real rollouts: input_tokens is inclusive of BOTH the
+  // cached-read and cache-write tokens (total_tokens = input + output). The
+  // server prices input, cache-read, and cache-write as disjoint buckets, so
+  // the uncached-and-unwritten remainder is what belongs in inputTokens;
+  // clamp for malformed hosts.
+  const inputTokens = input === null ? null : Math.max(0, input - cached - cacheWrite);
+  return normalizedEvent({
+    eventKey: `${NAMESPACE}:usage:${byteOffset}`,
+    type: "usage",
+    occurredAt,
+    payload: {
+      role: "assistant",
+      contentFormat: "json",
+      captureStatus: "complete",
+      provider,
+      model,
+      providerRequestId: null,
+      messageId: null,
+      stopReason: null,
+      serviceTier: null,
+      effort: null,
+      sidechain: false,
+      latencyMs: null,
+      inputTokens,
+      outputTokens: output,
+      cacheReadTokens: usageInt(usage.cached_input_tokens),
+      cacheWriteTokens: usageInt(usage.cache_write_input_tokens),
+      cacheWrite1hTokens: null,
+      cacheWrite5mTokens: null,
+      reasoningTokens: usageInt(usage.reasoning_output_tokens),
+    },
+    sourceEndOffset: endOffset,
+  });
+}
+
+export const codexTranscriptDriver = {
+  clientKind: "codex",
+  eventKeyNamespace: NAMESPACE,
+  usageGapPrefix: `${NAMESPACE}:usage-gap:`,
+
+  async locate(hostSessionId, { env = process.env } = {}) {
+    const sessionId = boundedHostSessionId(hostSessionId);
+    if (sessionId === null) return null;
+    const path = await locateRollout(codexHome(env), sessionId);
+    return path === null ? null : { path };
+  },
+
+  async readSuffix(path, cursor, _sessionHash) {
+    const { buffer, start } = await readSuffixWindow(path, cursor?.byteOffset ?? 0);
+    const priorState = cursor?.hostState !== null && typeof cursor?.hostState === "object"
+      ? cursor.hostState : {};
+    let model = typeof priorState.model === "string" && USAGE_MODEL_PATTERN.test(priorState.model)
+      ? priorState.model : null;
+    let provider = typeof priorState.provider === "string" && PROVIDER_PATTERN.test(priorState.provider)
+      ? priorState.provider : "openai";
+    const metadata = {};
+    const events = [];
+    let lastEnd = start;
+    for (const line of completeJsonlLines(buffer, start)) {
+      lastEnd = line.endOffset;
+      const entry = line.entry;
+      if (entry === null) continue;
+      const payload = entry.payload !== null && typeof entry.payload === "object" ? entry.payload : {};
+      const occurredAt = typeof entry.timestamp === "string" ? entry.timestamp : new Date().toISOString();
+      if (entry.type === "session_meta") {
+        if (typeof payload.model_provider === "string" && PROVIDER_PATTERN.test(payload.model_provider)) {
+          provider = payload.model_provider;
+        }
+        const hostVersion = boundedMetadataText(payload.cli_version, 64);
+        if (hostVersion) metadata.hostVersion = hostVersion;
+        const entrypoint = boundedMetadataText(payload.originator, 64);
+        if (entrypoint) metadata.entrypoint = entrypoint;
+        const metaCwd = boundedMetadataText(payload.cwd, 2048);
+        if (metaCwd) metadata.cwd = metaCwd;
+        continue;
+      }
+      if (entry.type === "turn_context") {
+        if (typeof payload.model === "string" && USAGE_MODEL_PATTERN.test(payload.model)) {
+          model = payload.model;
+        }
+        const turnCwd = boundedMetadataText(payload.cwd, 2048);
+        if (turnCwd) metadata.cwd = turnCwd;
+        continue;
+      }
+      if (entry.type === "event_msg" && payload.type === "token_count") {
+        events.push(usageEventFromTokenCount(payload.info, {
+          model, provider,
+          byteOffset: line.byteOffset,
+          endOffset: line.endOffset,
+          occurredAt,
+        }));
+      }
+    }
+    return {
+      events,
+      observedEndOffset: drainedEndOffset(lastEnd, start, buffer.length, MAX_DRIVER_SUFFIX_BYTES),
+      metadata,
+      hostState: boundedHostState({ ...priorState, model, provider }),
+    };
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return hostMetadataEvent(NAMESPACE, payload);
+  },
+};

package/src/transcript-drivers/index.mjs

@@ -0,0 +1,18 @@
+import { claudeTranscriptDriver } from "./claude.mjs";
+import { codexTranscriptDriver } from "./codex.mjs";
+import { kimiTranscriptDriver } from "./kimi.mjs";
+
+const DRIVERS = Object.freeze({
+  "claude-code": claudeTranscriptDriver,
+  codex: codexTranscriptDriver,
+  "kimi-cli": kimiTranscriptDriver,
+});
+
+/**
+ * The reviewed transcript driver for a client kind, or null. Hosts without a
+ * reviewed driver keep hooks-only capture — absence is a supported state,
+ * never an error.
+ */
+export function transcriptDriverFor(clientKind) {
+  return DRIVERS[String(clientKind ?? "")] ?? null;
+}

package/src/transcript-drivers/kimi.mjs

@@ -0,0 +1,180 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  buildClaudeMetadataPayload,
+  hostMetadataEvent,
+  normalizedEvent,
+  usageInt,
+  USAGE_MODEL_PATTERN,
+} from "../session.mjs";
+import { kimiHome } from "../host-roots.mjs";
+import {
+  boundedHostSessionId,
+  boundedHostState,
+  boundedMetadataText,
+  completeJsonlLines,
+  containedPath,
+  drainedEndOffset,
+  MAX_DRIVER_SUFFIX_BYTES,
+  readSuffixWindow,
+} from "./shared.mjs";
+
+const NAMESPACE = "kimi-cli";
+const MAX_INDEX_BYTES = 8 * 1024 * 1024;
+
+async function readableFile(root, candidate) {
+  const contained = await containedPath(root, candidate);
+  if (contained === null) return null;
+  try {
+    return (await stat(contained)).isFile() ? contained : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Kimi's `session_index.jsonl` maps sessionId -> sessionDir. The index is
+ * host-written but its paths are still treated as untrusted: every sessionDir
+ * is containment-checked under the kimi root before any file inside it is
+ * opened. The primary wire is `<sessionDir>/agents/main/wire.jsonl`; older
+ * layouts kept `<sessionDir>/wire.jsonl`.
+ */
+async function locateWire(root, sessionId) {
+  let indexText;
+  try {
+    indexText = await readFile(join(root, "session_index.jsonl"), "utf8");
+  } catch {
+    return null;
+  }
+  if (Buffer.byteLength(indexText, "utf8") > MAX_INDEX_BYTES) return null;
+  const wanted = new Set([sessionId, `session_${sessionId}`]);
+  let sessionDir = null;
+  let workDir = null;
+  for (const line of indexText.split("\n")) {
+    if (!line) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry !== null && typeof entry === "object" && wanted.has(entry.sessionId) &&
+        typeof entry.sessionDir === "string") {
+      sessionDir = entry.sessionDir; // keep last — the index is append-ordered
+      workDir = typeof entry.workDir === "string" ? entry.workDir : null;
+    }
+  }
+  if (sessionDir === null) return null;
+  const containedDir = await containedPath(root, sessionDir);
+  if (containedDir === null) return null;
+  const path = await readableFile(root, join(containedDir, "agents", "main", "wire.jsonl")) ||
+    await readableFile(root, join(containedDir, "wire.jsonl"));
+  if (path === null) return null;
+  const statePath = await readableFile(root, join(containedDir, "state.json"));
+  return { path, statePath, workDir };
+}
+
+function usageEventFromRecord(entry, { byteOffset, endOffset }) {
+  const usage = entry.usage !== null && typeof entry.usage === "object" ? entry.usage : null;
+  const model = typeof entry.model === "string" && USAGE_MODEL_PATTERN.test(entry.model)
+    ? entry.model : null;
+  const occurredAt = Number.isSafeInteger(entry.time) && entry.time > 0
+    ? new Date(entry.time).toISOString() : new Date().toISOString();
+  const input = usageInt(usage?.inputOther);
+  const output = usageInt(usage?.output);
+  if (usage === null || model === null || (input === null && output === null)) {
+    return normalizedEvent({
+      eventKey: `${NAMESPACE}:usage-gap:${byteOffset}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: model === null && usage !== null ? "model_unknown" : "usage_unavailable",
+      },
+      sourceEndOffset: endOffset,
+    });
+  }
+  return normalizedEvent({
+    eventKey: `${NAMESPACE}:usage:${byteOffset}`,
+    type: "usage",
+    occurredAt,
+    payload: {
+      role: "assistant",
+      contentFormat: "json",
+      captureStatus: "complete",
+      provider: "moonshot",
+      model,
+      providerRequestId: null,
+      messageId: null,
+      stopReason: null,
+      serviceTier: null,
+      effort: null,
+      sidechain: false,
+      latencyMs: null,
+      // usage.record buckets are named as disjoint shares of the prompt.
+      inputTokens: input,
+      outputTokens: output,
+      cacheReadTokens: usageInt(usage.inputCacheRead),
+      cacheWriteTokens: usageInt(usage.inputCacheCreation),
+      cacheWrite1hTokens: null,
+      cacheWrite5mTokens: null,
+      reasoningTokens: null,
+    },
+    sourceEndOffset: endOffset,
+  });
+}
+
+export const kimiTranscriptDriver = {
+  clientKind: "kimi-cli",
+  eventKeyNamespace: NAMESPACE,
+  usageGapPrefix: `${NAMESPACE}:usage-gap:`,
+
+  async locate(hostSessionId, { env = process.env } = {}) {
+    const raw = String(hostSessionId ?? "");
+    const sessionId = boundedHostSessionId(raw.startsWith("session_") ? raw.slice("session_".length) : raw);
+    if (sessionId === null) return null;
+    const located = await locateWire(kimiHome(env), sessionId);
+    if (located === null) return null;
+    const sessionFacts = {};
+    const cwd = boundedMetadataText(located.workDir, 2048);
+    if (cwd) sessionFacts.cwd = cwd;
+    if (located.statePath !== null) {
+      try {
+        const state = JSON.parse(await readFile(located.statePath, "utf8"));
+        const title = boundedMetadataText(state?.title, 512);
+        if (title) sessionFacts.title = title;
+      } catch {
+        // state.json is optional evidence, never a failure.
+      }
+    }
+    return { path: located.path, sessionFacts };
+  },
+
+  async readSuffix(path, cursor, _sessionHash) {
+    const { buffer, start } = await readSuffixWindow(path, cursor?.byteOffset ?? 0);
+    const metadata = {};
+    const events = [];
+    let lastEnd = start;
+    for (const line of completeJsonlLines(buffer, start)) {
+      lastEnd = line.endOffset;
+      const entry = line.entry;
+      if (entry === null) continue;
+      if (entry.type === "usage.record") {
+        events.push(usageEventFromRecord(entry, {
+          byteOffset: line.byteOffset,
+          endOffset: line.endOffset,
+        }));
+      }
+    }
+    return {
+      events,
+      observedEndOffset: drainedEndOffset(lastEnd, start, buffer.length, MAX_DRIVER_SUFFIX_BYTES),
+      metadata,
+      hostState: boundedHostState(cursor?.hostState),
+    };
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return hostMetadataEvent(NAMESPACE, payload);
+  },
+};