@iiwish/agentrecord 0.0.1

package/src/build/report.mjs

@@ -0,0 +1,64 @@
+import path from "node:path";
+
+import { normalizeLocale, readJsonIfExists } from "../core/config.mjs";
+import { supportedLocales } from "./catalog.mjs";
+import { repoRoot } from "./paths.mjs";
+
+export function resolveReportSettings(config, stats, generatedAt) {
+  let locale = config.resolved.report.locale;
+  let languageSource = "config";
+  let confidence = locale === "auto" ? "low" : "explicit";
+
+  if (locale === "auto") {
+    const agentLocale = inferAgentConversationLocale(stats);
+    if (agentLocale) {
+      locale = agentLocale.locale;
+      languageSource = "agent_conversation_language";
+      confidence = agentLocale.confidence;
+    } else {
+      locale = normalizeLocale(Intl.DateTimeFormat().resolvedOptions().locale, config.resolved.report.fallbackLocale);
+      if (locale === "auto") locale = config.resolved.report.fallbackLocale;
+      languageSource = "system_locale";
+      confidence = "medium";
+    }
+  }
+
+  if (!supportedLocales.includes(locale)) {
+    locale = config.resolved.report.fallbackLocale;
+    languageSource = "fallback_locale";
+    confidence = "low";
+  }
+
+  return {
+    locale_requested: config.resolved.report.locale,
+    locale,
+    fallback_locale: config.resolved.report.fallbackLocale,
+    label_mode: config.resolved.report.labelMode,
+    language_source: languageSource,
+    language_confidence: confidence,
+    schema_language: "en-US",
+    audiences: config.resolved.report.audiences.filter((audience) => ["self", "share"].includes(audience)),
+    default_audience: "self",
+    supported_locales: supportedLocales,
+    agent_language_votes: stats.language_votes,
+    agent_language_sample: stats.language_sample,
+    generated_at: generatedAt
+  };
+}
+
+function inferAgentConversationLocale(stats) {
+  const zh = stats.language_votes?.["zh-CN"] || 0;
+  const en = stats.language_votes?.["en-US"] || 0;
+  const total = zh + en;
+  if (total < 3) return null;
+  const locale = zh >= en ? "zh-CN" : "en-US";
+  const share = Math.max(zh, en) / total;
+  if (share < 0.6) return null;
+  return { locale, confidence: share >= 0.8 ? "high" : "medium" };
+}
+
+export function loadLocaleBundle(locale) {
+  return readJsonIfExists(path.join(repoRoot, "locales", `${locale}.json`))
+    || readJsonIfExists(path.join(repoRoot, "locales", "en-US.json"))
+    || { ui: {}, roles: {}, abilities: {}, html_lang: "en" };
+}

package/src/build/run-context.mjs

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { readJsonIfExists } from "../core/config.mjs";
+import { ensureDir, stableTimestamp } from "./utils.mjs";
+import { sumTokenUsage, zeroTokenUsage } from "./stats.mjs";
+
+export function buildRunContext({ config, stats, generatedAt, reset }) {
+  const stateFile = path.join(config.resolved.privateStateDir, "state.json");
+  const snapshotsDir = path.join(config.resolved.privateStateDir, "snapshots");
+  const previousState = reset ? null : readJsonIfExists(stateFile);
+  const previouslyProcessed = new Set(previousState?.processed_session_ids || []);
+  const previousTokenTotals = previousState?.session_token_totals || {};
+  const hasPreviousTokenTotals = Object.keys(previousTokenTotals).length > 0;
+  const newRecords = previousState
+    ? stats.session_records.filter((record) => !previouslyProcessed.has(record.session_id))
+    : stats.session_records;
+  const updatedRecords = previousState && hasPreviousTokenTotals
+    ? stats.session_records.filter((record) => {
+        if (!previouslyProcessed.has(record.session_id)) return false;
+        const currentTokens = record.token_usage?.total_tokens || 0;
+        const previousTokens = previousTokenTotals[record.session_id]?.total_tokens || 0;
+        return currentTokens > previousTokens;
+      })
+    : [];
+  const tokenDelta = sumTokenUsage(newRecords.filter((record) => record.has_token_usage));
+  for (const record of updatedRecords) {
+    const current = record.token_usage || {};
+    const previous = previousTokenTotals[record.session_id] || {};
+    for (const key of Object.keys(tokenDelta)) tokenDelta[key] += Math.max(0, (current[key] || 0) - (previous[key] || 0));
+  }
+
+  let snapshotCreated = false;
+  const profileFile = path.join(config.resolved.profileDir, "profile.json");
+  if (fs.existsSync(profileFile)) {
+    ensureDir(snapshotsDir);
+    const previousProfile = readJsonIfExists(profileFile);
+    const snapshotName = `profile-${stableTimestamp(previousProfile?.generated_at || generatedAt)}.json`;
+    fs.copyFileSync(profileFile, path.join(snapshotsDir, snapshotName));
+    snapshotCreated = true;
+  }
+
+  const runCount = reset ? 1 : (previousState?.run_count || 0) + 1;
+  const sessionTokenTotals = Object.fromEntries(stats.session_records.map((record) => [
+    record.session_id,
+    record.token_usage || zeroTokenUsage()
+  ]));
+
+  return {
+    public: {
+      mode: previousState ? "incremental" : "initial",
+      run_count: runCount,
+      generated_at: generatedAt,
+      previous_generated_at: previousState?.generated_at || null,
+      reset,
+      new_sessions_this_run: newRecords.length,
+      updated_sessions_this_run: updatedRecords.length,
+      changed_sessions_this_run: newRecords.length + updatedRecords.length,
+      token_delta_this_run: tokenDelta,
+      total_sessions_seen: stats.files,
+      total_token_sessions_seen: stats.token_sessions,
+      private_state_present: true,
+      private_snapshot_created: snapshotCreated,
+      public_session_ids_included: false
+    },
+    privateState: {
+      schema_version: "agentrecord.state.v0",
+      owner: config.resolved.owner,
+      generated_at: generatedAt,
+      run_count: runCount,
+      reset,
+      session_roots: config.resolved.codex.sessionRoots,
+      trace_window: stats.trace_window,
+      processed_sessions_count: stats.session_records.length,
+      processed_session_ids: stats.session_records.map((record) => record.session_id).sort(),
+      session_token_totals: sessionTokenTotals,
+      last_trace_end_timestamp: stats.trace_window.end_timestamp,
+      last_profile_hash: null,
+      last_run_delta: {
+        new_sessions: newRecords.length,
+        updated_sessions: updatedRecords.length,
+        changed_sessions: newRecords.length + updatedRecords.length,
+        token_delta: tokenDelta
+      },
+      history: [
+        ...(previousState?.history || []).slice(-19),
+        {
+          generated_at: generatedAt,
+          mode: previousState ? "incremental" : "initial",
+          new_sessions: newRecords.length,
+          updated_sessions: updatedRecords.length,
+          total_sessions_seen: stats.files
+        }
+      ]
+    }
+  };
+}

package/src/build/stats.mjs

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { readJsonlLines } from "./utils.mjs";
+
+function collectRolloutFiles(rootDirs) {
+  const files = [];
+  const roots = Array.isArray(rootDirs) ? rootDirs : [rootDirs].filter(Boolean);
+
+  for (const root of roots) {
+    if (!root || !fs.existsSync(root)) continue;
+    const stack = [root];
+    while (stack.length) {
+      const current = stack.pop();
+      let entries = [];
+      try {
+        entries = fs.readdirSync(current, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        const target = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+          stack.push(target);
+        } else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name)) {
+          files.push(target);
+        }
+      }
+    }
+  }
+
+  return [...new Set(files)].sort();
+}
+
+function extractUserText(obj) {
+  if (obj.type !== "response_item" || obj.payload?.type !== "message" || obj.payload?.role !== "user") return "";
+  if (!Array.isArray(obj.payload.content)) return "";
+  return obj.payload.content
+    .filter((item) => ["input_text", "output_text", "text"].includes(item?.type))
+    .map((item) => item.text || "")
+    .join("\n");
+}
+
+function countLanguageSignal(text) {
+  const sample = String(text || "").slice(0, 12000);
+  const cjk = sample.match(/[\u3400-\u9fff]/g)?.length || 0;
+  const latinWords = sample.match(/[A-Za-z]{2,}/g)?.length || 0;
+  if (cjk >= 12 && cjk >= latinWords * 0.25) return "zh-CN";
+  if (latinWords >= 30 && cjk < 8) return "en-US";
+  return null;
+}
+
+export function sumTokenUsage(records) {
+  return records.reduce((total, record) => {
+    const usage = record.token_usage || {};
+    for (const key of Object.keys(total)) total[key] += usage[key] || 0;
+    return total;
+  }, zeroTokenUsage());
+}
+
+export function zeroTokenUsage() {
+  return {
+    total_tokens: 0,
+    input_tokens: 0,
+    cached_input_tokens: 0,
+    output_tokens: 0,
+    reasoning_output_tokens: 0
+  };
+}
+
+export function collectCodexStats(rootDirs, { publicProjectPaths }) {
+  const files = collectRolloutFiles(rootDirs);
+  const byCwd = new Map();
+  const bySource = new Map();
+  const projectTokens = new Map();
+  const sessionRecords = [];
+  const languageVotes = { "zh-CN": 0, "en-US": 0 };
+  const languageSample = { user_messages_seen: 0, sampled_characters: 0 };
+  const totals = zeroTokenUsage();
+  let tokenSessions = 0;
+  let minTs = null;
+  let maxTs = null;
+
+  for (const file of files) {
+    let meta = null;
+    let lastToken = null;
+
+    for (const line of readJsonlLines(file)) {
+      let obj;
+      try {
+        obj = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (obj.type === "session_meta" && obj.payload) meta = obj.payload;
+      if (obj.type === "event_msg" && obj.payload?.type === "token_count") {
+        lastToken = obj.payload.info?.total_token_usage || null;
+      }
+
+      if (languageSample.user_messages_seen < 500) {
+        const userText = extractUserText(obj);
+        if (userText) {
+          languageSample.user_messages_seen += 1;
+          languageSample.sampled_characters += Math.min(userText.length, 12000);
+          const detected = countLanguageSignal(userText);
+          if (detected) languageVotes[detected] += 1;
+        }
+      }
+    }
+
+    const cwd = meta?.cwd || "(unknown)";
+    const source = meta?.source || meta?.originator || "(unknown)";
+    byCwd.set(cwd, (byCwd.get(cwd) || 0) + 1);
+    bySource.set(source, (bySource.get(source) || 0) + 1);
+
+    if (meta?.timestamp) {
+      if (!minTs || meta.timestamp < minTs) minTs = meta.timestamp;
+      if (!maxTs || meta.timestamp > maxTs) maxTs = meta.timestamp;
+    }
+
+    if (lastToken?.total_tokens) {
+      tokenSessions += 1;
+      for (const key of Object.keys(totals)) totals[key] += lastToken[key] || 0;
+      projectTokens.set(cwd, (projectTokens.get(cwd) || 0) + (lastToken.total_tokens || 0));
+    }
+
+    let fileMtimeMs = 0;
+    try {
+      fileMtimeMs = Math.round(fs.statSync(file).mtimeMs);
+    } catch {
+      fileMtimeMs = 0;
+    }
+
+    sessionRecords.push({
+      session_id: meta?.id || path.basename(file).replace(/^rollout-|\.jsonl$/g, ""),
+      timestamp: meta?.timestamp || null,
+      project_path: cwd,
+      source,
+      has_token_usage: Boolean(lastToken?.total_tokens),
+      token_usage: lastToken || null,
+      file_mtime_ms: fileMtimeMs
+    });
+  }
+
+  const projectRows = [...byCwd.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12);
+  const topProjects = projectRows.map(([projectPath, sessions], index) => ({
+    project_ref: publicProjectPaths ? safeProjectName(projectPath) : `project_ref_${String(index + 1).padStart(3, "0")}`,
+    sessions,
+    total_tokens: projectTokens.get(projectPath) || 0,
+    public_project_path_included: Boolean(publicProjectPaths)
+  }));
+
+  return {
+    session_roots_count: Array.isArray(rootDirs) ? rootDirs.length : 0,
+    files: files.length,
+    token_sessions: tokenSessions,
+    trace_window: {
+      start: minTs ? minTs.slice(0, 10) : "unknown",
+      end: maxTs ? maxTs.slice(0, 10) : "unknown",
+      start_timestamp: minTs,
+      end_timestamp: maxTs
+    },
+    total_token_usage: totals,
+    language_votes: languageVotes,
+    language_sample: languageSample,
+    by_source: Object.fromEntries([...bySource.entries()].sort((a, b) => b[1] - a[1])),
+    top_projects: topProjects,
+    session_records: sessionRecords
+  };
+}
+
+function safeProjectName(projectPath) {
+  if (!projectPath || projectPath === "(unknown)") return "unknown";
+  return path.basename(projectPath);
+}

package/src/build/utils.mjs

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function readJsonlLines(file) {
+  try {
+    return fs.readFileSync(file, "utf8").split(/\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function hashObject(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+export function stableTimestamp(value) {
+  return String(value || new Date().toISOString()).replace(/[:.]/g, "-");
+}
+
+export function snakeId(value) {
+  return String(value || "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+
+export function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+export function formatNumber(value, locale = "en-US") {
+  return new Intl.NumberFormat(locale).format(value || 0);
+}
+
+export function formatCompactNumber(value, locale = "en-US") {
+  return new Intl.NumberFormat(locale, {
+    maximumFractionDigits: 1,
+    notation: "compact"
+  }).format(value || 0);
+}
+
+export function esc(value) {
+  return String(value ?? "")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("'", "&#39;");
+}

package/src/cli.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+
+import { runBuild } from "./commands/build.mjs";
+import { runDoctor } from "./commands/doctor.mjs";
+import { runInit } from "./commands/init.mjs";
+import { runOpen } from "./commands/open.mjs";
+import { runScan } from "./commands/scan.mjs";
+import { runValidate } from "./commands/validate.mjs";
+import { parseArgs } from "./core/args.mjs";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const VERSION = packageJson.version;
+
+const help = `AgentRecord ${VERSION}
+
+Local-first, auditable AI work profiles from agent traces.
+
+Usage:
+  agentrecord --help
+  agentrecord --version
+  agentrecord doctor
+  agentrecord init [--dry-run] [--owner <name>] [--profiles-dir <dir>] [--output <dir>]
+  agentrecord scan [--config <file>] [--sessions-dir <dir>]
+  agentrecord build [--config <file>] [--agent-context] [--no-account-usage]
+  agentrecord validate [--config <file>]
+  agentrecord open [--config <file>] [--owner <owner>]
+
+Commands:
+  agentrecord doctor     Check local runtime and source availability
+  agentrecord init       Create agentrecord.config.json
+  agentrecord scan       Discover local AI-agent trace sources
+  agentrecord build      Generate profile.json, evidence.jsonl, and HTML report
+  agentrecord validate   Check schema, privacy boundary, and report integrity
+  agentrecord open       Open profiles/<owner>/index.html
+
+Build options:
+  --no-account-usage                    Skip Codex CLI account usage lookup
+  --account-usage-timeout-ms <ms>       Timeout for Codex CLI account usage lookup
+`;
+
+const { options, positional } = parseArgs(process.argv.slice(2));
+const command = positional[0];
+
+if (options.version || command === "version") {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+if (options.help || !command || command === "help") {
+  console.log(help);
+  process.exit(0);
+}
+
+const commands = {
+  doctor: runDoctor,
+  init: runInit,
+  scan: runScan,
+  build: runBuild,
+  validate: runValidate,
+  open: runOpen
+};
+
+const handler = commands[command];
+
+if (handler) {
+  await handler({
+    version: VERSION,
+    options,
+    args: positional.slice(1)
+  });
+  process.exit(process.exitCode || 0);
+}
+
+console.error(`Unknown command: ${command}`);
+console.error("Run `agentrecord --help` for usage.");
+process.exit(1);

package/src/commands/build.mjs

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../core/config.mjs";
+import { writeArtifacts } from "../build/artifacts.mjs";
+import { readCodexAccountUsage } from "../build/codex-account.mjs";
+import { buildEvidenceCards, extractMemoryBlocks, loadEvidenceRules } from "../build/evidence.mjs";
+import { buildProfile } from "../build/profile.mjs";
+import { loadLocaleBundle, resolveReportSettings } from "../build/report.mjs";
+import { buildRunContext } from "../build/run-context.mjs";
+import { collectCodexStats } from "../build/stats.mjs";
+import { ensureDir, hashObject } from "../build/utils.mjs";
+
+export async function runBuild({ options }) {
+  const config = loadConfig(options);
+  const generatedAt = new Date().toISOString();
+  const agentContextEnabled = options.agentContext === true;
+  ensureDir(config.resolved.profileDir);
+  ensureDir(config.resolved.privateStateDir);
+
+  const stats = collectCodexStats(config.resolved.codex.sessionRoots, {
+    publicProjectPaths: config.resolved.privacy.publicProjectPaths
+  });
+  const codexAccountUsage = await readCodexAccountUsage(config.resolved.codex.accountUsage);
+  const report = resolveReportSettings(config, stats, generatedAt);
+  const localeBundle = loadLocaleBundle(report.locale);
+
+  let rulePaths = config.resolved.evidenceRulesPaths;
+  if (report.locale === "zh-CN") {
+    rulePaths = rulePaths.map((filePath) => {
+      const parent = path.dirname(filePath);
+      const ext = path.extname(filePath);
+      const base = path.basename(filePath, ext);
+      const zhPath = path.join(parent, `${base}.zh-CN${ext}`);
+      return fs.existsSync(zhPath) ? zhPath : filePath;
+    });
+  }
+  const rules = loadEvidenceRules(rulePaths);
+
+  const memoryBlocks = config.resolved.memory.enabled ? extractMemoryBlocks(config.resolved.memory.registryPath) : [];
+  const evidenceCards = buildEvidenceCards({ stats, rules, memoryBlocks, locale: report.locale });
+  const runContext = buildRunContext({ config, stats, generatedAt, reset: Boolean(options.reset) });
+  const profile = buildProfile({
+    config,
+    stats,
+    codexAccountUsage,
+    evidenceCards,
+    report,
+    localeBundle,
+    runMetadata: runContext.public,
+    agentContextEnabled
+  });
+
+  runContext.privateState.last_profile_hash = hashObject(profile);
+  writeArtifacts({ config, profile, evidenceCards, localeBundle, privateState: runContext.privateState, agentContextEnabled });
+
+  console.log(JSON.stringify({
+    ok: true,
+    out_dir: config.resolved.profileDir,
+    owner: config.resolved.owner,
+    schema_version: profile.schema_version,
+    sessions_scanned: stats.files,
+    codex_account_usage: codexAccountUsage.status,
+    evidence_cards: evidenceCards.length,
+    report_locale: report.locale,
+    artifacts: [
+      "profile.json",
+      "evidence.jsonl",
+      "index.html",
+      "profile.md",
+      "redaction-report.md",
+      "run-report.md",
+      ...(agentContextEnabled ? ["agent-context.md", "agent-context.json"] : [])
+    ]
+  }, null, 2));
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export async function runDoctor({ version }) {
+  const defaultCodexSessionsDir = path.join(os.homedir(), ".codex", "sessions");
+
+  console.log(JSON.stringify({
+    ok: true,
+    package: "agentrecord",
+    version,
+    node: process.version,
+    cwd: process.cwd(),
+    config_exists: fs.existsSync(path.resolve(process.cwd(), "agentrecord.config.json")),
+    codex_sessions_default: {
+      path: defaultCodexSessionsDir,
+      exists: fs.existsSync(defaultCodexSessionsDir)
+    }
+  }, null, 2));
+}

package/src/commands/init.mjs

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { CONFIG_FILE, createDefaultConfig, defaultOwnerDisplayName, safePathSegment, writeJson } from "../core/config.mjs";
+
+export async function runInit({ options }) {
+  const ownerDisplayName = options.owner || defaultOwnerDisplayName();
+  const owner = safePathSegment(ownerDisplayName);
+  const profilesDir = options.profilesDir || "profiles";
+  const profileDir = options.output || path.join(profilesDir, owner);
+  const config = createDefaultConfig({
+    owner: ownerDisplayName,
+    profilesDir,
+    locale: options.locale || "auto"
+  });
+
+  config.output.profile_dir = profileDir;
+
+  if (options.codexSessionsDir || options.sessionsDir) {
+    const sessionsDir = options.codexSessionsDir || options.sessionsDir;
+    config.codex.sessions_dir = sessionsDir;
+    config.codex.session_roots = [sessionsDir];
+  }
+
+  if (typeof options.accountUsage === "boolean") config.codex.account_usage.enabled = options.accountUsage;
+  if (options.accountUsageTimeoutMs) config.codex.account_usage.timeout_ms = Number(options.accountUsageTimeoutMs);
+
+  if (options.publicProjectPaths === true) config.privacy.public_project_paths = true;
+  if (options.publicProjectPaths === false) config.privacy.public_project_paths = false;
+  if (options.privacy) config.privacy.mode = options.privacy;
+
+  const target = path.resolve(process.cwd(), options.config || CONFIG_FILE);
+
+  if (options.dryRun) {
+    console.log(JSON.stringify({
+      ok: true,
+      dry_run: true,
+      would_write: target,
+      config
+    }, null, 2));
+    return;
+  }
+
+  if (fs.existsSync(target) && !options.force) {
+    console.log(JSON.stringify({
+      ok: true,
+      created: false,
+      exists: true,
+      path: target,
+      message: "Config already exists. Use --force to overwrite."
+    }, null, 2));
+    return;
+  }
+
+  writeJson(target, config);
+  console.log(JSON.stringify({
+    ok: true,
+    created: true,
+    path: target,
+    config
+  }, null, 2));
+}