@halofy/agent-connect 0.5.0 → 0.6.0

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);
+  },
+};

package/src/transcript-drivers/shared.mjs

@@ -0,0 +1,104 @@
+import { open, realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+// Windowed suffix budget per catch-up call. Successive calls drain the
+// remainder; nothing is skipped, memory stays bounded even for giant files.
+export const MAX_DRIVER_SUFFIX_BYTES = 8 * 1024 * 1024;
+
+// Host session ids are interpolated into filesystem lookups. Anything with a
+// path character is refused outright — no capture beats a contained read of
+// the wrong file (README containment commitment).
+const HOST_SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+export function boundedHostSessionId(value) {
+  const text = String(value ?? "");
+  return HOST_SESSION_ID_PATTERN.test(text) ? text : null;
+}
+
+/**
+ * Resolve `candidate` and require it to live under `root` after every
+ * symlink is followed. Index files and cached paths are untrusted input;
+ * any escape resolves to null (no capture), never an error.
+ */
+export async function containedPath(root, candidate) {
+  try {
+    const realRoot = await realpath(root);
+    const resolved = resolve(realRoot, String(candidate ?? ""));
+    if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) return null;
+    const real = await realpath(resolved);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) return null;
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+/** Positioned read of at most `maxBytes` starting at `byteOffset`. */
+export async function readSuffixWindow(path, byteOffset, maxBytes = MAX_DRIVER_SUFFIX_BYTES) {
+  const handle = await open(path, "r");
+  try {
+    const size = (await handle.stat()).size;
+    const start = Number.isSafeInteger(byteOffset) && byteOffset >= 0 && byteOffset <= size
+      ? byteOffset : 0;
+    const length = Math.min(size - start, maxBytes);
+    const buffer = Buffer.alloc(length);
+    if (length > 0) await handle.read(buffer, 0, length, start);
+    return { buffer, start };
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Yield `{ entry, byteOffset, endOffset }` for every complete JSONL line in
+ * the window. An unparseable line yields `entry: null` (drivers skip it —
+ * unlike the Claude archive, an ignored line is the norm for selective
+ * usage/metadata readers). A trailing record without its newline is left
+ * unread for the next catch-up.
+ */
+export function* completeJsonlLines(buffer, start) {
+  let position = 0;
+  while (position < buffer.length) {
+    const newline = buffer.indexOf(0x0a, position);
+    if (newline === -1) break;
+    let entry = null;
+    try {
+      const parsed = JSON.parse(buffer.subarray(position, newline).toString("utf8"));
+      entry = parsed !== null && typeof parsed === "object" ? parsed : null;
+    } catch {
+      entry = null;
+    }
+    yield { entry, byteOffset: start + position, endOffset: start + newline + 1 };
+    position = newline + 1;
+  }
+}
+
+/**
+ * End offset for a drained window. If a full window held no newline at all
+ * (pathological single-line file), advance past it rather than re-reading the
+ * same bytes forever — usage lines are tiny, so nothing real is lost.
+ */
+export function drainedEndOffset(lastEndOffset, start, bufferLength, maxBytes) {
+  if (lastEndOffset > start) return lastEndOffset;
+  if (bufferLength >= maxBytes) return start + bufferLength;
+  return start;
+}
+
+const MAX_HOST_STATE_BYTES = 1024;
+
+/** Bound the per-session driver scratch state persisted on the cursor. */
+export function boundedHostState(value) {
+  if (value === null || typeof value !== "object") return undefined;
+  const serialized = JSON.stringify(value);
+  return Buffer.byteLength(serialized, "utf8") <= MAX_HOST_STATE_BYTES ? value : undefined;
+}
+
+/**
+ * Bound for host-supplied metadata strings, mirroring collectClaudeMetadata:
+ * non-empty, capped, and free of control characters. The server rejects a
+ * whole batch over an oversized field, so bounding here is not cosmetic.
+ */
+export function boundedMetadataText(value, max) {
+  return typeof value === "string" && value.length > 0 && value.length <= max &&
+    !/[\u0000-\u001f\u007f]/.test(value) ? value : undefined;
+}

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.5.0";
-export const RUNTIME_VERSION = "0.5.0";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-29.2";
+export const INSTALLER_VERSION = "0.6.0";
+export const RUNTIME_VERSION = "0.6.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-31.2";