agentel 0.2.0

package/src/archive.js

@@ -0,0 +1,1130 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { loadConfig } = require("./config");
+const { normalizeSessionEvents } = require("./canonical-events");
+const { parserVersionForSource } = require("./parser-versions");
+const { canonicalRepo } = require("./repo");
+const { loadRedactionConfig, loadEnvValues, mergeSummaries, redactText, styleRedactionMarkersForMarkdown } = require("./redaction");
+const { ensureBaseDirs, ensureDir, paths, readJson, writeJson } = require("./paths");
+
+const SHARED_RAW_SOURCE_CACHE = new Map();
+
+function archiveRoot(env = process.env) {
+  const cfg = loadConfig(env);
+  return path.join(cfg.storage.root || paths(env).data, "agentlog");
+}
+
+function objectPathForSession(session, env = process.env) {
+  const started = new Date(session.startedAt || Date.now());
+  const year = String(started.getUTCFullYear()).padStart(4, "0");
+  const month = String(started.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(started.getUTCDate()).padStart(2, "0");
+  const root = archiveRoot(env);
+  const scopeSegment = session.scopeCanonical
+    ? `scope=${encodeSegment(session.scopeCanonical)}`
+    : `repo=${encodeSegment(session.repoCanonical)}`;
+  return path.join(
+    root,
+    "sessions",
+    scopeSegment,
+    session.provider ? `provider=${session.provider}` : "",
+    `year=${year}`,
+    `month=${month}`,
+    `day=${day}`
+  );
+}
+
+function writeSession(input, env = process.env) {
+  ensureBaseDirs(paths(env));
+  const cfg = loadConfig(env);
+  const cwd = input.scopeCanonical ? input.cwd || "" : input.cwd || process.cwd();
+  const redactionCwd = cwd || process.cwd();
+  const repoInfo = input.scopeCanonical ? null : input.repoInfo || canonicalRepo(cwd);
+  const provider = input.provider || "unknown";
+  const sourceType = input.sourceType || "import";
+  const parserVersion = input.parserVersion ?? parserVersionForSource(sourceType);
+  const messages = normalizeMessages(input.messages || []).map((message) => ({
+    ...message,
+    metadata: {
+      ...(message.metadata || {}),
+      sourceType: message.metadata?.sourceType || sourceType,
+      parserVersion: message.metadata?.parserVersion ?? parserVersion ?? undefined
+    }
+  }));
+  const startedAt = input.startedAt || messages[0]?.timestamp || new Date().toISOString();
+  const endedAt = input.endedAt || messages[messages.length - 1]?.timestamp || startedAt;
+  const sessionId = input.sessionId || stableSessionId(provider, input.sourcePath || "", startedAt, messages);
+  const repoCanonical = input.scopeCanonical ? "" : input.repoCanonical || repoInfo.key;
+  const redactionConfig = loadRedactionConfig(env);
+  const envValues = loadEnvValues(redactionCwd, redactionConfig.envVars, env);
+  const redactionSummary = {};
+  const redactedMessages = messages.map((message) => {
+    const result = redactText(message.content, {
+      config: redactionConfig,
+      cwd: redactionCwd,
+      env,
+      envValues,
+      repoCanonical
+    });
+    mergeSummaries(redactionSummary, result.summary);
+    return {
+      ...message,
+      content: result.text,
+      metadata: redactStructuredStrings(message.metadata || {}, {
+        config: redactionConfig,
+        cwd: redactionCwd,
+        env,
+        envValues,
+        repoCanonical,
+        summary: redactionSummary
+      })
+    };
+  });
+
+  const session = {
+    version: 1,
+    archiveSchemaVersion: 2,
+    sessionId,
+    provider,
+    scopeCanonical: input.scopeCanonical || "",
+    repoCanonical,
+    repoSource: input.scopeCanonical ? "scope" : repoInfo.source,
+    cwd,
+    title: input.title || "",
+    sourcePath: input.sourcePath || "",
+    sourceType,
+    parserVersion,
+    parserVersions: input.parserVersions || (parserVersion ? { [sourceType]: parserVersion } : {}),
+    storageScope: input.storageScope || (input.scopeCanonical ? cfg.privacy.webChatsDefaultScope : "repo"),
+    startedAt,
+    endedAt,
+    messageCount: redactedMessages.length,
+    userMessageCount: redactedMessages.filter((message) => message.role === "user").length,
+    redactionSummary,
+    importedAt: new Date().toISOString()
+  };
+  for (const key of [
+    "providerConversationId",
+    "chatAccountId",
+    "chatUsername",
+    "chatDisplayName",
+    "chatProjectPath",
+    "chatVirtualRepo",
+    "chatDisplayPath",
+    "conversationKind",
+    "pinned"
+  ]) {
+    if (input[key] !== undefined) session[key] = input[key];
+  }
+
+  const dir = objectPathForSession(session, env);
+  ensureDir(dir);
+  const conversationPath = path.join(dir, `session=${sessionId}.conversation.md`);
+  const metadataPath = path.join(dir, `session=${sessionId}.metadata.json`);
+  const transcriptPath = path.join(dir, `session=${sessionId}.transcript.jsonl`);
+  const eventPath = path.join(dir, `session=${sessionId}.events.jsonl`);
+  const viewPath = path.join(dir, `session=${sessionId}.view.json`);
+  const rawPath = path.join(dir, `session=${sessionId}.raw`);
+  const events = redactCanonicalEvents(
+    Array.isArray(input.events) ? normalizePrecomputedEvents(input.events, session) : normalizeSessionEvents(session, redactedMessages),
+    {
+      config: redactionConfig,
+      cwd: redactionCwd,
+      env,
+      envValues,
+      repoCanonical,
+      summary: redactionSummary
+    }
+  );
+  session.eventCount = events.length;
+  removeStaleSessionCopies(session, metadataPath, env, { replaceSourcePathCopies: input.replaceSourcePathCopies !== false });
+  const rawFiles = copyRawFiles(input, rawPath, env);
+  if (rawFiles.length) {
+    session.rawPath = rawPath;
+    session.rawFiles = rawFiles;
+    session.rawFileCount = rawFiles.length;
+  }
+  fs.writeFileSync(conversationPath, renderConversationMarkdown(session, redactedMessages, events), { mode: 0o600 });
+  fs.writeFileSync(transcriptPath, redactedMessages.map((message) => `${JSON.stringify(message)}\n`).join(""), {
+    mode: 0o600
+  });
+  fs.writeFileSync(eventPath, events.map((event) => `${JSON.stringify(event)}\n`).join(""), { mode: 0o600 });
+  writeSessionView(viewPath, computeSessionView(session, redactedMessages, events));
+  session.conversationPath = conversationPath;
+  session.transcriptPath = transcriptPath;
+  session.eventPath = eventPath;
+  session.viewPath = viewPath;
+  session.viewSchemaVersion = VIEW_SCHEMA_VERSION;
+  const usageStats = computeSessionUsage(redactedMessages);
+  if (usageStats) session.usage = usageStats;
+  const models = collectSessionModels(redactedMessages);
+  if (models.length) session.models = models;
+  writeJson(metadataPath, session);
+
+  if (cfg.privacy.revealCache && !input.scopeCanonical) {
+    const revealDir = path.join(paths(env).revealCache, provider);
+    ensureDir(revealDir);
+    fs.writeFileSync(
+      path.join(revealDir, `${sessionId}.jsonl`),
+      messages.map((message) => `${JSON.stringify(message)}\n`).join(""),
+      { mode: 0o600 }
+    );
+  }
+
+  touchManifest(session, { conversationPath, metadataPath, transcriptPath, eventPath, viewPath, rawPath: session.rawPath || "" }, env);
+  return { session, conversationPath, metadataPath, transcriptPath, eventPath, viewPath, rawPath: session.rawPath || "" };
+}
+
+function removeStaleSessionCopies(session, metadataPath, env = process.env, options = {}) {
+  const root = path.join(archiveRoot(env), "sessions");
+  const replaceSourcePathCopies = options.replaceSourcePathCopies !== false;
+  walk(root, (file) => {
+    if (!file.endsWith(".metadata.json") || path.resolve(file) === path.resolve(metadataPath)) return;
+    const metadata = readJson(file, null);
+    if (!metadata || metadata.provider !== session.provider) return;
+    const sameSession = metadata.sessionId === session.sessionId;
+    const sameSource = replaceSourcePathCopies && session.sourcePath && metadata.sourcePath === session.sourcePath;
+    if (!sameSession && !sameSource) return;
+    safeUnlink(metadata.conversationPath || file.replace(/\.metadata\.json$/, ".conversation.md"));
+    safeUnlink(metadata.transcriptPath || file.replace(/\.metadata\.json$/, ".transcript.jsonl"));
+    safeUnlink(metadata.eventPath || file.replace(/\.metadata\.json$/, ".events.jsonl"));
+    safeUnlink(metadata.viewPath || file.replace(/\.metadata\.json$/, ".view.json"));
+    safeRm(metadata.rawPath || file.replace(/\.metadata\.json$/, ".raw"));
+    safeUnlink(file);
+  });
+}
+
+function deleteSessionArchive(session, env = process.env) {
+  if (!session || typeof session !== "object") return false;
+  const metadataPath = session.metadataPath || "";
+  safeUnlink(session.conversationPath || metadataPath.replace(/\.metadata\.json$/, ".conversation.md"));
+  safeUnlink(session.transcriptPath || metadataPath.replace(/\.metadata\.json$/, ".transcript.jsonl"));
+  safeUnlink(session.eventPath || metadataPath.replace(/\.metadata\.json$/, ".events.jsonl"));
+  safeUnlink(session.viewPath || metadataPath.replace(/\.metadata\.json$/, ".view.json"));
+  safeRm(session.rawPath || metadataPath.replace(/\.metadata\.json$/, ".raw"));
+  safeUnlink(metadataPath);
+  if (session.provider && session.sessionId) {
+    safeUnlink(path.join(paths(env).revealCache, session.provider, `${session.sessionId}.jsonl`));
+  }
+  return true;
+}
+
+function copyRawFiles(input, rawPath, env = process.env) {
+  const files = rawSourceFiles(input);
+  const references = rawReferences(input);
+  if (!files.length && !references.length) {
+    safeRm(rawPath);
+    return [];
+  }
+  safeRm(rawPath);
+  ensureDir(rawPath);
+  const records = [];
+  for (const reference of references) {
+    records.push(reference);
+  }
+  if (input.sharedRawFiles) {
+    for (const file of files) {
+      const record = copySharedRawFile(file, env);
+      if (record) records.push(record);
+    }
+    if (!records.length) {
+      safeRm(rawPath);
+      return [];
+    }
+    writeJson(path.join(rawPath, "manifest.json"), {
+      version: 1,
+      copiedAt: new Date().toISOString(),
+      files: records
+    });
+    return records;
+  }
+  for (const file of files) {
+    const stat = safeStat(file);
+    if (!stat || !stat.isFile()) continue;
+    const filename = `${String(records.length + 1).padStart(3, "0")}-${safeRawFilename(path.basename(file))}`;
+    const archivedPath = path.join(rawPath, filename);
+    fs.copyFileSync(file, archivedPath);
+    fs.chmodSync(archivedPath, 0o600);
+    records.push({
+      originalPath: file,
+      filename,
+      archivedPath,
+      size: stat.size,
+      mtime: new Date(stat.mtimeMs).toISOString(),
+      sha256: fileSha256(archivedPath)
+    });
+  }
+  if (!records.length) {
+    safeRm(rawPath);
+    return [];
+  }
+  writeJson(path.join(rawPath, "manifest.json"), {
+    version: 1,
+    copiedAt: new Date().toISOString(),
+    files: records
+  });
+  return records;
+}
+
+function copySharedRawFile(file, env = process.env) {
+  const stat = safeStat(file);
+  if (!stat || !stat.isFile()) return null;
+  const resolved = path.resolve(file);
+  const cacheKey = `${resolved}:${stat.size}:${Math.floor(stat.mtimeMs)}`;
+  const cached = SHARED_RAW_SOURCE_CACHE.get(cacheKey);
+  if (cached && fs.existsSync(cached.sharedRawPath)) return { ...cached };
+  let sha256;
+  try {
+    sha256 = fileSha256(resolved);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  const filename = `${sha256}-${safeRawFilename(path.basename(file))}`;
+  const dir = path.join(archiveRoot(env), "raw-sources", sha256.slice(0, 2));
+  ensureDir(dir);
+  const sharedRawPath = path.join(dir, filename);
+  if (!fs.existsSync(sharedRawPath)) {
+    try {
+      fs.copyFileSync(resolved, sharedRawPath);
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+    fs.chmodSync(sharedRawPath, 0o600);
+  }
+  const record = {
+    reference: true,
+    originalPath: resolved,
+    filename,
+    archivedPath: sharedRawPath,
+    sharedRawPath,
+    size: stat.size,
+    mtime: new Date(stat.mtimeMs).toISOString(),
+    sha256,
+    note: "shared raw source"
+  };
+  SHARED_RAW_SOURCE_CACHE.set(cacheKey, record);
+  return { ...record };
+}
+
+function rawSourceFiles(input) {
+  const values = [
+    ...(Array.isArray(input.rawFiles) ? input.rawFiles : []),
+    ...(Array.isArray(input.sourceFiles) ? input.sourceFiles : []),
+    input.sourcePath
+  ];
+  const seen = new Set();
+  const files = [];
+  for (const value of values) {
+    const candidate = rawSourceCandidate(value);
+    if (!candidate) continue;
+    for (const file of [candidate, ...sqliteSidecarFiles(candidate)]) {
+      const stat = safeStat(file);
+      if (!stat || !stat.isFile()) continue;
+      const resolved = path.resolve(file);
+      if (seen.has(resolved)) continue;
+      seen.add(resolved);
+      files.push(resolved);
+    }
+  }
+  return files;
+}
+
+function rawReferences(input) {
+  return (Array.isArray(input.rawReferences) ? input.rawReferences : [])
+    .filter((item) => item && typeof item === "object")
+    .map((item, index) => ({
+      reference: true,
+      filename: item.filename || `reference-${String(index + 1).padStart(3, "0")}`,
+      originalPath: item.originalPath || item.sourcePath || "",
+      archivedPath: item.archivedPath || item.sharedRawPath || "",
+      sharedRawPath: item.sharedRawPath || item.archivedPath || "",
+      entryPath: item.entryPath || "",
+      conversationId: item.conversationId || "",
+      sha256: item.sha256 || "",
+      size: Number.isFinite(Number(item.size)) ? Number(item.size) : undefined,
+      mtime: item.mtime || undefined,
+      note: item.note || undefined
+    }));
+}
+
+function rawSourceCandidate(value) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  if (fs.existsSync(text)) return text;
+  const hashIndex = text.indexOf("#");
+  if (hashIndex > 0) {
+    const beforeHash = text.slice(0, hashIndex);
+    if (fs.existsSync(beforeHash)) return beforeHash;
+  }
+  return "";
+}
+
+function sqliteSidecarFiles(file) {
+  if (!/\.(sqlite|sqlite3|db|vscdb)$/i.test(file)) return [];
+  return [`${file}-wal`, `${file}-shm`];
+}
+
+function safeRawFilename(value) {
+  return (String(value || "source").replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || "source").slice(0, 180);
+}
+
+function fileSha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function safeUnlink(file) {
+  try {
+    fs.unlinkSync(file);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+function safeRm(file) {
+  try {
+    fs.rmSync(file, { recursive: true, force: true });
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+function safeStat(file) {
+  try {
+    return fs.statSync(file);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeMessages(messages) {
+  const normalized = messages
+    .map((message, index) => ({
+      type: "message",
+      index,
+      timestamp: toIso(message.timestamp) || new Date().toISOString(),
+      role: normalizeRole(message.role),
+      content: String(message.content ?? ""),
+      metadata: message.metadata || {}
+    }))
+    .filter((message) => message.content.trim() || hasStructuredMetadata(message.metadata));
+  return dedupeAdjacentMessages(normalized).map((message, index) => ({ ...message, index }));
+}
+
+function hasStructuredMetadata(metadata) {
+  return Boolean(
+    (Array.isArray(metadata?.toolCalls) && metadata.toolCalls.length) ||
+      metadata?.toolResult ||
+      metadata?.eventType ||
+      metadata?.parserVersion
+  );
+}
+
+function dedupeAdjacentMessages(messages) {
+  const result = [];
+  for (const message of messages) {
+    const previous = result[result.length - 1];
+    if (
+      previous &&
+      previous.role === message.role &&
+      normalizedContent(previous.content) === normalizedContent(message.content) &&
+      timestampsNear(previous.timestamp, message.timestamp)
+    ) {
+      continue;
+    }
+    result.push(message);
+  }
+  return result;
+}
+
+function normalizedContent(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function timestampsNear(left, right) {
+  const leftTime = Date.parse(left);
+  const rightTime = Date.parse(right);
+  if (!Number.isFinite(leftTime) || !Number.isFinite(rightTime)) return String(left || "") === String(right || "");
+  return Math.abs(leftTime - rightTime) <= 2000;
+}
+
+function normalizeRole(role) {
+  const value = String(role || "unknown").toLowerCase();
+  if (["user", "assistant", "system", "tool"].includes(value)) return value;
+  if (["human"].includes(value)) return "user";
+  if (["bot", "agent", "model"].includes(value)) return "assistant";
+  return value || "unknown";
+}
+
+function toIso(value) {
+  if (!value) return "";
+  if (typeof value === "number") {
+    const ms = value > 1e12 ? value : value * 1000;
+    return new Date(ms).toISOString();
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? "" : date.toISOString();
+}
+
+function stableSessionId(provider, sourcePath, startedAt, messages) {
+  const hash = crypto
+    .createHash("sha256")
+    .update(provider)
+    .update("\0")
+    .update(sourcePath)
+    .update("\0")
+    .update(startedAt)
+    .update("\0")
+    .update(JSON.stringify(messages.slice(0, 20)))
+    .digest("hex");
+  return hash.slice(0, 24);
+}
+
+function encodeSegment(value) {
+  return encodeURIComponent(value || "unknown").replace(/[!'()*]/g, (char) =>
+    `%${char.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+
+function decodeSegment(value) {
+  return decodeURIComponent(value);
+}
+
+const _sessionsIndex = {
+  byPath: new Map(),
+  byId: new Map()
+};
+
+function hydrateSessionMetadata(file, metadata) {
+  const conversationPath = metadata.conversationPath || file.replace(/\.metadata\.json$/, ".conversation.md");
+  const transcriptPath = metadata.transcriptPath || file.replace(/\.metadata\.json$/, ".transcript.jsonl");
+  const eventPath = metadata.eventPath || file.replace(/\.metadata\.json$/, ".events.jsonl");
+  const viewPath = metadata.viewPath || file.replace(/\.metadata\.json$/, ".view.json");
+  const derivedRawPath = file.replace(/\.metadata\.json$/, ".raw");
+  const rawPath = metadata.rawPath || (fs.existsSync(derivedRawPath) ? derivedRawPath : "");
+  return { ...metadata, conversationPath, metadataPath: file, transcriptPath, eventPath, viewPath, rawPath };
+}
+
+function listSessions(env = process.env) {
+  const root = path.join(archiveRoot(env), "sessions");
+  const seen = new Set();
+  const sessions = [];
+  walk(root, (file) => {
+    if (!file.endsWith(".metadata.json")) return;
+    seen.add(file);
+    let stat;
+    try { stat = fs.statSync(file); } catch { return; }
+    const cached = _sessionsIndex.byPath.get(file);
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+      sessions.push(cached.session);
+      return;
+    }
+    const metadata = readJson(file, null);
+    if (!metadata) return;
+    const session = hydrateSessionMetadata(file, metadata);
+    _sessionsIndex.byPath.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, session });
+    if (session.sessionId) _sessionsIndex.byId.set(session.sessionId, file);
+    sessions.push(session);
+  });
+  for (const key of [..._sessionsIndex.byPath.keys()]) {
+    if (!seen.has(key)) {
+      const dropped = _sessionsIndex.byPath.get(key);
+      if (dropped?.session?.sessionId) _sessionsIndex.byId.delete(dropped.session.sessionId);
+      _sessionsIndex.byPath.delete(key);
+    }
+  }
+  return sessions.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+}
+
+function findSessionById(sessionId, env = process.env) {
+  if (!sessionId) return null;
+  const cachedPath = _sessionsIndex.byId.get(sessionId);
+  if (cachedPath) {
+    const cached = _sessionsIndex.byPath.get(cachedPath);
+    if (cached) {
+      let stat;
+      try { stat = fs.statSync(cachedPath); } catch { stat = null; }
+      if (stat && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+        return cached.session;
+      }
+      if (stat) {
+        const metadata = readJson(cachedPath, null);
+        if (metadata) {
+          const session = hydrateSessionMetadata(cachedPath, metadata);
+          _sessionsIndex.byPath.set(cachedPath, { mtimeMs: stat.mtimeMs, size: stat.size, session });
+          if (session.sessionId) _sessionsIndex.byId.set(session.sessionId, cachedPath);
+          return session;
+        }
+      }
+      _sessionsIndex.byPath.delete(cachedPath);
+      _sessionsIndex.byId.delete(sessionId);
+    }
+  }
+  return listSessions(env).find((session) => session.sessionId === sessionId) || null;
+}
+
+function computeSessionUsage(messages) {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheInputTokens = 0;
+  let reasoningOutputTokens = 0;
+  let toolUsePromptTokens = 0;
+  let maxUndifferentiatedTotalTokens = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  const seenUsageRequests = new Set();
+  let any = false;
+  for (const message of messages || []) {
+    const usage = message && message.metadata && message.metadata.usage;
+    if (!usage || typeof usage !== "object") continue;
+    const requestId = String(message.metadata?.requestId || "").trim();
+    if (requestId) {
+      if (seenUsageRequests.has(requestId)) continue;
+      seenUsageRequests.add(requestId);
+    }
+    const summary = usageTokenSummary(usage);
+    if (!summary.hasAny) continue;
+    if (summary.inputTokens > 0) {
+      inputTokens += summary.inputTokens;
+      any = true;
+    }
+    if (summary.outputTokens > 0) {
+      outputTokens += summary.outputTokens;
+      any = true;
+    }
+    if (summary.cacheInputTokens > 0) cacheInputTokens += summary.cacheInputTokens;
+    if (summary.reasoningOutputTokens > 0) reasoningOutputTokens += summary.reasoningOutputTokens;
+    if (summary.toolUsePromptTokens > 0) toolUsePromptTokens += summary.toolUsePromptTokens;
+    if (!summary.hasSplitTokens && !summary.hasExtraTokens && summary.hasTotalTokens) {
+      maxUndifferentiatedTotalTokens = Math.max(maxUndifferentiatedTotalTokens, summary.totalTokens);
+    }
+    if (summary.totalInputTokens > totalInputTokens) totalInputTokens = summary.totalInputTokens;
+    if (summary.totalOutputTokens > totalOutputTokens) totalOutputTokens = summary.totalOutputTokens;
+  }
+  if (Number.isFinite(totalInputTokens) && totalInputTokens > 0) any = true;
+  if (Number.isFinite(totalOutputTokens) && totalOutputTokens > 0) any = true;
+  if (!any && maxUndifferentiatedTotalTokens > 0) {
+    inputTokens = maxUndifferentiatedTotalTokens;
+    any = true;
+  }
+  const cumulativeTokens = totalInputTokens + totalOutputTokens;
+  const finalTotalTokens = inputTokens + outputTokens || cumulativeTokens || maxUndifferentiatedTotalTokens;
+  if (!any && finalTotalTokens === 0) return null;
+  return {
+    inputTokens: inputTokens || totalInputTokens || (!outputTokens && finalTotalTokens ? finalTotalTokens : 0),
+    outputTokens: outputTokens || totalOutputTokens,
+    cacheInputTokens,
+    reasoningOutputTokens,
+    toolUsePromptTokens,
+    totalTokens: finalTotalTokens,
+    totalInputTokens: totalInputTokens || inputTokens,
+    totalOutputTokens: totalOutputTokens || outputTokens
+  };
+}
+
+function usageTokenSummary(usage) {
+  if (!usage || typeof usage !== "object") return emptyUsageTokenSummary();
+  const inputTokens = positiveTokenNumber(firstUsageNumber(
+    usage.inputTokens,
+    usage.input_tokens,
+    usage.promptTokens,
+    usage.prompt_tokens,
+    usage.promptTokenCount,
+    usage.prompt_token_count,
+    usage.inputTokenCount,
+    usage.input_token_count,
+    usage.prompt,
+    usage.input
+  ));
+  const outputTokens = positiveTokenNumber(firstUsageNumber(
+    usage.outputTokens,
+    usage.output_tokens,
+    usage.completionTokens,
+    usage.completion_tokens,
+    usage.completionTokenCount,
+    usage.completion_token_count,
+    usage.candidatesTokens,
+    usage.candidates_tokens,
+    usage.candidatesTokenCount,
+    usage.candidates_token_count,
+    usage.outputTokenCount,
+    usage.output_token_count,
+    usage.completion,
+    usage.output
+  ));
+  const totalInputTokens = positiveTokenNumber(firstUsageNumber(
+    usage.totalInputTokens,
+    usage.total_input_tokens,
+    usage.totalPromptTokens,
+    usage.total_prompt_tokens,
+    usage.totalPromptTokenCount,
+    usage.total_prompt_token_count
+  ));
+  const totalOutputTokens = positiveTokenNumber(firstUsageNumber(
+    usage.totalOutputTokens,
+    usage.total_output_tokens,
+    usage.totalCompletionTokens,
+    usage.total_completion_tokens,
+    usage.totalCompletionTokenCount,
+    usage.total_completion_token_count
+  ));
+  const explicitTotalTokens = positiveTokenNumber(firstUsageNumber(
+    usage.totalTokens,
+    usage.total_tokens,
+    usage.totalTokenCount,
+    usage.total_token_count,
+    usage.total
+  ));
+  const cacheInputTokens = sumPositiveTokenNumbers(
+    firstUsageNumber(usage.cacheInputTokens, usage.cache_input_tokens),
+    firstUsageNumber(usage.cacheCreationInputTokens, usage.cache_creation_input_tokens),
+    firstUsageNumber(usage.cacheReadInputTokens, usage.cache_read_input_tokens),
+    firstUsageNumber(usage.cacheReadTokens, usage.cache_read_tokens),
+    firstUsageNumber(usage.cachedContentTokenCount, usage.cached_content_token_count),
+    firstUsageNumber(usage.cachedTokens, usage.cached_tokens, usage.cacheTokens, usage.cache_tokens, usage.cached)
+  );
+  const reasoningOutputTokens = sumPositiveTokenNumbers(
+    firstUsageNumber(usage.reasoningOutputTokens, usage.reasoning_output_tokens),
+    firstUsageNumber(usage.thoughtsTokens, usage.thoughts_tokens, usage.thoughtsTokenCount, usage.thoughts_token_count),
+    firstUsageNumber(usage.reasoningTokens, usage.reasoning_tokens, usage.reasoningTokenCount, usage.reasoning_token_count)
+  );
+  const toolUsePromptTokens = sumPositiveTokenNumbers(
+    firstUsageNumber(usage.toolUsePromptTokens, usage.tool_use_prompt_tokens, usage.toolUsePromptTokenCount, usage.tool_use_prompt_token_count)
+  );
+  const extraTokens = cacheInputTokens + reasoningOutputTokens + toolUsePromptTokens;
+  const splitTokens = inputTokens + outputTokens;
+  const cumulativeTokens = totalInputTokens + totalOutputTokens;
+  const categoryTokens = splitTokens + extraTokens;
+  const totalTokens = explicitTotalTokens || categoryTokens
+    ? Math.max(explicitTotalTokens, categoryTokens)
+    : cumulativeTokens;
+  return {
+    inputTokens,
+    outputTokens,
+    totalInputTokens,
+    totalOutputTokens,
+    cacheInputTokens,
+    reasoningOutputTokens,
+    toolUsePromptTokens,
+    extraTokens,
+    totalTokens,
+    hasAny: totalTokens > 0,
+    hasSplitTokens: splitTokens > 0,
+    hasExtraTokens: extraTokens > 0,
+    hasTotalTokens: explicitTotalTokens > 0,
+    hasCumulativeTokens: cumulativeTokens > 0
+  };
+}
+
+function emptyUsageTokenSummary() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    cacheInputTokens: 0,
+    reasoningOutputTokens: 0,
+    toolUsePromptTokens: 0,
+    extraTokens: 0,
+    totalTokens: 0,
+    hasAny: false,
+    hasSplitTokens: false,
+    hasExtraTokens: false,
+    hasTotalTokens: false,
+    hasCumulativeTokens: false
+  };
+}
+
+function firstUsageNumber(...values) {
+  for (const value of values) {
+    if (value === null || value === undefined || value === "") continue;
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return 0;
+}
+
+function positiveTokenNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+function sumPositiveTokenNumbers(...values) {
+  return values.reduce((sum, value) => sum + positiveTokenNumber(value), 0);
+}
+
+function collectSessionModels(messages) {
+  const models = new Set();
+  for (const message of messages || []) {
+    const model = message && message.metadata && message.metadata.model;
+    if (typeof model === "string" && model.trim()) models.add(model.trim());
+  }
+  return Array.from(models);
+}
+
+function readTranscript(file) {
+  const messages = [];
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      messages.push(JSON.parse(line));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return messages;
+}
+
+function readEvents(sessionOrPath) {
+  const file = typeof sessionOrPath === "string"
+    ? sessionOrPath
+    : sessionOrPath?.eventPath || sessionOrPath?.metadataPath?.replace(/\.metadata\.json$/, ".events.jsonl") || "";
+  const events = [];
+  if (!file) return events;
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      events.push(JSON.parse(line));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return events;
+}
+
+function ensureConversationMarkdown(session, env = process.env) {
+  const conversationPath = session.conversationPath || session.metadataPath?.replace(/\.metadata\.json$/, ".conversation.md");
+  if (!conversationPath) return "";
+  if (fs.existsSync(conversationPath)) return conversationPath;
+  const messages = readTranscript(session.transcriptPath);
+  if (!messages.length) return "";
+  const events = readEvents(session);
+  ensureDir(path.dirname(conversationPath));
+  fs.writeFileSync(conversationPath, renderConversationMarkdown(session, messages, events), { mode: 0o600 });
+  if (session.metadataPath) {
+    const metadata = readJson(session.metadataPath, null);
+    if (metadata) writeJson(session.metadataPath, { ...metadata, conversationPath });
+  }
+  return conversationPath;
+}
+
+const VIEW_SCHEMA_VERSION = 1;
+
+function sessionViewPathFromMetadata(metadataPath) {
+  if (!metadataPath) return "";
+  return metadataPath.replace(/\.metadata\.json$/, ".view.json");
+}
+
+function sessionViewPathForSession(session) {
+  return session.viewPath || sessionViewPathFromMetadata(session.metadataPath);
+}
+
+function dedupeTranscriptMessages(messages) {
+  const result = [];
+  for (const message of messages || []) {
+    const previous = result[result.length - 1];
+    if (
+      previous &&
+      previous.role === message.role &&
+      normalizedTranscriptContent(previous.content) === normalizedTranscriptContent(message.content) &&
+      transcriptTimestampsNear(previous.timestamp, message.timestamp)
+    ) {
+      continue;
+    }
+    result.push(message);
+  }
+  return result;
+}
+
+function normalizedTranscriptContent(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function transcriptTimestampsNear(left, right) {
+  const leftTime = Date.parse(left);
+  const rightTime = Date.parse(right);
+  if (!Number.isFinite(leftTime) || !Number.isFinite(rightTime)) return String(left || "") === String(right || "");
+  return Math.abs(leftTime - rightTime) <= 2000;
+}
+
+function displayTranscriptMessages(messages, time) {
+  if (time?.status !== "recovered-time-unknown") return messages;
+  return messages.map((message) => ({ ...message, timestamp: "" }));
+}
+
+function cursorRawTimeMatchesSourceMtime(session, timestamp) {
+  const rawFiles = Array.isArray(session?.rawFiles) ? session.rawFiles : [];
+  return rawFiles.some((file) => {
+    const mtime = Date.parse(file?.mtime || "");
+    if (!Number.isFinite(mtime)) return false;
+    const near = Math.abs(timestamp - mtime) <= 2 * 60 * 60 * 1000;
+    const looksLikeCursorDb = /state\.vscdb(?:\.backup|-wal)?$/.test(String(file.originalPath || file.filename || ""));
+    return looksLikeCursorDb && near;
+  });
+}
+
+function cursorRawSyntheticTimeParts(session) {
+  const result = { startSynthetic: false, endSynthetic: false };
+  if (!session || session.provider !== "cursor") return result;
+  if (!["cursor-raw-sqlite-salvage", "cursor-workspace-sqlite"].includes(session.sourceType)) return result;
+  const started = Date.parse(session.startedAt || "");
+  const ended = Date.parse(session.endedAt || session.startedAt || "");
+  result.startSynthetic = Number.isFinite(started) && cursorRawTimeMatchesSourceMtime(session, started);
+  result.endSynthetic = Number.isFinite(ended) && cursorRawTimeMatchesSourceMtime(session, ended);
+  return result;
+}
+
+function sessionHistoryTime(session) {
+  const rawTime = cursorRawSyntheticTimeParts(session);
+  if (rawTime.startSynthetic && rawTime.endSynthetic) {
+    return { startedAt: "", endedAt: "", status: "recovered-time-unknown" };
+  }
+  if (rawTime.endSynthetic) {
+    return { startedAt: session?.startedAt || "", endedAt: "", status: "recovered-partial-time" };
+  }
+  return { startedAt: session?.startedAt || "", endedAt: session?.endedAt || "", status: "" };
+}
+
+function computeSessionView(session, transcriptMessages, canonicalEvents) {
+  const time = sessionHistoryTime(session);
+  const display = displayTranscriptMessages(dedupeTranscriptMessages(transcriptMessages || []), time);
+  return {
+    view_schema_version: VIEW_SCHEMA_VERSION,
+    session_id: session?.sessionId || "",
+    started_at: time.startedAt || "",
+    ended_at: time.endedAt || "",
+    time_status: time.status || "",
+    transcript_messages: display,
+    canonical_events: Array.isArray(canonicalEvents) ? canonicalEvents : []
+  };
+}
+
+function writeSessionView(viewPath, baked) {
+  ensureDir(path.dirname(viewPath));
+  fs.writeFileSync(viewPath, JSON.stringify(baked), { mode: 0o600 });
+}
+
+function ensureSessionView(session, env = process.env) {
+  const viewPath = sessionViewPathForSession(session);
+  if (viewPath && fs.existsSync(viewPath)) {
+    const cached = readJson(viewPath, null);
+    if (cached && cached.view_schema_version === VIEW_SCHEMA_VERSION) return cached;
+  }
+  const baked = computeSessionView(
+    session,
+    readTranscript(session.transcriptPath),
+    readEvents(session)
+  );
+  if (viewPath) {
+    try {
+      writeSessionView(viewPath, baked);
+      if (session.metadataPath) {
+        const metadata = readJson(session.metadataPath, null);
+        if (metadata && (metadata.viewPath !== viewPath || metadata.viewSchemaVersion !== VIEW_SCHEMA_VERSION)) {
+          writeJson(session.metadataPath, { ...metadata, viewPath, viewSchemaVersion: VIEW_SCHEMA_VERSION });
+        }
+      }
+    } catch (error) {
+      if (error.code !== "EACCES" && error.code !== "EROFS") throw error;
+    }
+  }
+  return baked;
+}
+
+function renderConversationMarkdown(session, messages, events = []) {
+  const title = session.title || `${session.provider || "agent"} session ${session.sessionId}`;
+  const hasRedactions =
+    messages.some((message) => /\[REDACTED:[^\]\n]+\]/.test(JSON.stringify(message))) ||
+    events.some((event) => /\[REDACTED:[^\]\n]+\]/.test(JSON.stringify(event)));
+  const frontmatter = [
+    "---",
+    `session_id: ${yamlString(session.sessionId)}`,
+    `provider: ${yamlString(session.provider)}`,
+    `repo: ${yamlString(session.repoCanonical || "")}`,
+    `scope: ${yamlString(session.scopeCanonical || "")}`,
+    `cwd: ${yamlString(session.cwd || "")}`,
+    `started_at: ${yamlString(session.startedAt || "")}`,
+    `ended_at: ${yamlString(session.endedAt || "")}`,
+    `source_type: ${yamlString(session.sourceType || "")}`,
+    `storage_scope: ${yamlString(session.storageScope || "")}`,
+    `chat_account_id: ${yamlString(session.chatAccountId || "")}`,
+    `chat_display_name: ${yamlString(session.chatDisplayName || "")}`,
+    `chat_project_path: ${yamlString(session.chatProjectPath || "")}`,
+    `conversation_kind: ${yamlString(session.conversationKind || "")}`,
+    `archive_schema_version: ${yamlString(session.archiveSchemaVersion || 1)}`,
+    `event_count: ${yamlString(events.length || session.eventCount || 0)}`,
+    `parser_versions: ${yamlString(JSON.stringify(session.parserVersions || {}))}`,
+    "---",
+    ""
+  ];
+  const body = [`# ${markdownLine(title)}`, ""];
+  if (hasRedactions) {
+    body.push(
+      "<style>",
+      ".agentlog-redaction{display:inline-block;padding:0 0.35em;border-radius:0.35em;background:#fff1f2;color:#9f1239;border:1px solid #fecdd3;font-weight:650;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:0.92em;}",
+      "</style>",
+      "",
+      "> agentlog redactions are highlighted where sensitive text was removed.",
+      ""
+    );
+  }
+  for (const message of messages) {
+    body.push(`## ${roleLabel(message.role)} - ${message.timestamp || "unknown time"}`);
+    body.push("");
+    body.push(styleRedactionMarkersForMarkdown(String(message.content || "").trim()));
+    body.push("");
+    for (const event of events.filter((item) => item.messageIndex === message.index && item.kind === "tool.called")) {
+      body.push(`### Tool Call - ${event.occurredAt || message.timestamp || "unknown time"}`);
+      body.push("");
+      body.push(styleRedactionMarkersForMarkdown(String(event.body?.text || event.indexed?.summary || "").trim()));
+      body.push("");
+    }
+    for (const event of events.filter((item) => item.messageIndex === message.index && item.kind === "tool.completed")) {
+      body.push(`### Tool Result - ${event.occurredAt || message.timestamp || "unknown time"}`);
+      body.push("");
+      body.push(styleRedactionMarkersForMarkdown(String(event.indexed?.summary || event.body?.text || "").trim()));
+      body.push("");
+    }
+  }
+  return `${frontmatter.concat(body).join("\n").trimEnd()}\n`;
+}
+
+function normalizePrecomputedEvents(events, session) {
+  return events
+    .filter((event) => event && typeof event === "object")
+    .map((event) => ({
+      ...event,
+      sessionId: event.sessionId || session.sessionId,
+      provider: event.provider || session.provider,
+      sourceType: event.sourceType || session.sourceType,
+      parserVersion: event.parserVersion ?? session.parserVersion ?? null,
+      repoCanonical: event.repoCanonical ?? session.repoCanonical ?? "",
+      scopeCanonical: event.scopeCanonical ?? session.scopeCanonical ?? ""
+    }));
+}
+
+function redactCanonicalEvents(events, options) {
+  return events.map((event) => redactStructuredStrings(event, options));
+}
+
+function redactStructuredStrings(value, options) {
+  if (typeof value === "string") {
+    const result = redactText(value, options);
+    mergeSummaries(options.summary, result.summary);
+    return result.text;
+  }
+  if (Array.isArray(value)) return value.map((item) => redactStructuredStrings(item, options));
+  if (value && typeof value === "object") {
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+      output[key] = redactStructuredStrings(item, options);
+    }
+    return output;
+  }
+  return value;
+}
+
+function yamlString(value) {
+  return JSON.stringify(String(value ?? ""));
+}
+
+function markdownLine(value) {
+  return String(value || "(untitled session)").replace(/\r?\n/g, " ").trim();
+}
+
+function roleLabel(role) {
+  const value = String(role || "unknown").trim();
+  return value ? value[0].toUpperCase() + value.slice(1) : "Unknown";
+}
+
+function touchManifest(session, pathsForSession, env = process.env) {
+  const manifestPath = path.join(archiveRoot(env), "sessions", "manifest.json");
+  const manifest = readJson(manifestPath, { sessions: [] });
+  const next = manifest.sessions.filter((item) => item.sessionId !== session.sessionId);
+  next.push({
+    sessionId: session.sessionId,
+    provider: session.provider,
+    repoCanonical: session.repoCanonical,
+    scopeCanonical: session.scopeCanonical,
+    startedAt: session.startedAt,
+    conversationPath: pathsForSession.conversationPath,
+    metadataPath: pathsForSession.metadataPath,
+    transcriptPath: pathsForSession.transcriptPath,
+    eventPath: pathsForSession.eventPath,
+    viewPath: pathsForSession.viewPath || "",
+    rawPath: pathsForSession.rawPath || ""
+  });
+  writeJson(manifestPath, { sessions: next.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt))) });
+}
+
+function countSessions(env = process.env) {
+  const sessions = listSessions(env);
+  const byProvider = {};
+  for (const session of sessions) {
+    byProvider[session.provider] = (byProvider[session.provider] || 0) + 1;
+  }
+  return { total: sessions.length, byProvider };
+}
+
+function revealSession(sessionId, env = process.env) {
+  const root = paths(env).revealCache;
+  let found = "";
+  walk(root, (file) => {
+    if (!found && path.basename(file) === `${sessionId}.jsonl`) found = file;
+  });
+  if (!found) return null;
+  return fs.readFileSync(found, "utf8");
+}
+
+function walk(dir, visit) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, visit);
+    else visit(full);
+  }
+}
+
+module.exports = {
+  archiveRoot,
+  collectSessionModels,
+  computeSessionUsage,
+  computeSessionView,
+  countSessions,
+  decodeSegment,
+  dedupeTranscriptMessages,
+  deleteSessionArchive,
+  displayTranscriptMessages,
+  encodeSegment,
+  ensureConversationMarkdown,
+  ensureSessionView,
+  findSessionById,
+  listSessions,
+  normalizeMessages,
+  objectPathForSession,
+  readEvents,
+  readTranscript,
+  renderConversationMarkdown,
+  revealSession,
+  sessionHistoryTime,
+  sessionViewPathForSession,
+  sessionViewPathFromMetadata,
+  stableSessionId,
+  toIso,
+  usageTokenSummary,
+  VIEW_SCHEMA_VERSION,
+  walk,
+  writeSession
+};