codex-work-receipt 0.3.0 → 0.4.0

package/src/core/args.mjs

@@ -1,15 +1,22 @@
+import { normalizeScope } from "./range.mjs";
+
 export function printHelp(locale = "zh-CN") {
   console.log(locale === "en" ? `
 Codex AI Work Receipt
 
 Usage:
+  npx codex-work-receipt@latest
   npx codex-work-receipt@latest --latest --lang en
   npx codex-work-receipt@latest --today --lang en
+  npx codex-work-receipt@latest --range last-7-days --lang en
+  npx codex-work-receipt@latest --range this-week --lang en
   npx codex-work-receipt@latest --install-skill --lang en
 
 Options:
+  --range <name>              Range: latest, today, last-7-days, this-week
   --latest                    Summarize the latest active Codex session (default)
   --today                     Summarize all Codex activity from today
+  --session <id>              Summarize one specific Codex session
   --timezone <name>           Use an IANA timezone, for example Asia/Shanghai
   --lang <name>               Receipt language: zh-CN, en
   --theme <name>              Default theme: classic, diner, payroll
@@ -22,13 +29,18 @@ Options:
 Codex AI 打工小票
 
 用法：
+  npx codex-work-receipt@latest
   npx codex-work-receipt@latest --latest
   npx codex-work-receipt@latest --today
+  npx codex-work-receipt@latest --range last-7-days
+  npx codex-work-receipt@latest --range this-week
   npx codex-work-receipt@latest --install-skill
 
 选项：
+  --range <name>              统计范围：latest、today、last-7-days、this-week
   --latest                    统计最近活跃的 Codex 会话（默认）
   --today                     统计本地时区今天发生的全部 Codex 活动
+  --session <id>              统计指定的 Codex 会话
   --timezone <name>           指定 IANA 时区，例如 Asia/Shanghai
   --lang <name>               小票语言：zh-CN、en
   --theme <name>              默认主题：classic、diner、payroll
@@ -43,6 +55,8 @@ Codex AI 打工小票
 export function parseArgs(argv) {
   const result = {
     mode: "latest",
+    modeExplicit: false,
+    sessionId: null,
     timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "Asia/Shanghai",
     locale: "zh-CN",
     theme: "classic",
@@ -58,19 +72,36 @@ export function parseArgs(argv) {
     ["--theme", "theme"],
     ["--output", "output"],
     ["--data-dir", "dataDir"],
+    ["--session", "sessionId"],
   ]);
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (argument === "--latest") result.mode = "latest";
-    else if (argument === "--today") result.mode = "today";
-    else if (argument === "--install-skill") result.installSkill = true;
+    if (argument === "--latest") {
+      result.mode = "latest";
+      result.modeExplicit = true;
+    } else if (argument === "--today") {
+      result.mode = "today";
+      result.modeExplicit = true;
+    } else if (argument === "--range") {
+      const value = argv[++index];
+      if (!value) throw new Error("--range 需要提供值");
+      const scope = normalizeScope(value);
+      if (!scope || scope === "session") throw new Error(`不支持的统计范围：${value}`);
+      result.mode = scope;
+      result.modeExplicit = true;
+    } else if (argument === "--install-skill") result.installSkill = true;
     else if (argument === "--no-open") result.open = false;
     else if (argument === "--help" || argument === "-h") result.help = true;
     else if (optionsWithValues.has(argument)) {
       const value = argv[++index];
       if (!value) throw new Error(`${argument} 需要提供值`);
-      result[optionsWithValues.get(argument)] = value;
+      const key = optionsWithValues.get(argument);
+      result[key] = value;
+      if (key === "sessionId") {
+        result.mode = "session";
+        result.modeExplicit = true;
+      }
     } else throw new Error(`不认识的参数：${argument}`);
   }
 

package/src/core/metrics.mjs

@@ -1,4 +1,5 @@
 import { dateKey, rowDate } from "../lib/time.mjs";
+import { calendarDayCount, isCalendarScope, isDateInRange } from "./range.mjs";
 import { selectWorkProfileId } from "./presentation.mjs";
 
 function zeroUsage() {
@@ -23,26 +24,26 @@ function addUsage(target, source) {
   for (const key of Object.keys(target)) target[key] += Number(source[key] || 0);
 }
 
-function sessionTokenUsage(rows, mode, targetDate, timezone) {
+function sessionTokenUsage(rows, range) {
   const events = rows
     .filter((row) => row.type === "event_msg" && row.payload?.type === "token_count")
     .filter((row) => row.payload?.info?.total_token_usage)
     .sort((left, right) => (rowDate(left)?.getTime() || 0) - (rowDate(right)?.getTime() || 0));
 
   if (!events.length) return zeroUsage();
-  if (mode === "latest") return { ...zeroUsage(), ...events.at(-1).payload.info.total_token_usage };
+  if (!isCalendarScope(range.scope)) {
+    return { ...zeroUsage(), ...events.at(-1).payload.info.total_token_usage };
+  }
 
-  const lastToday = events.filter((row) => {
-    const date = rowDate(row);
-    return date && dateKey(date, timezone) === targetDate;
-  }).at(-1);
-  if (!lastToday) return zeroUsage();
+  const lastInRange = events.filter((row) => isDateInRange(rowDate(row), range)).at(-1);
+  if (!lastInRange) return zeroUsage();
 
   const baseline = events.filter((row) => {
     const date = rowDate(row);
-    return date && dateKey(date, timezone) < targetDate;
+    return date && dateKey(date, range.timezone) < range.startDate;
   }).at(-1)?.payload.info.total_token_usage || zeroUsage();
-  return subtractUsage(lastToday.payload.info.total_token_usage, baseline);
+
+  return subtractUsage(lastInRange.payload.info.total_token_usage, baseline);
 }
 
 function calculateWorkPoints(metrics) {
@@ -60,8 +61,14 @@ function calculateWorkPoints(metrics) {
   return Math.max(0, Math.round(points));
 }
 
-export function collectMetrics(sessions, mode, timezone) {
-  const targetDate = dateKey(new Date(), timezone);
+function emptyRangeMessage(range) {
+  if (range.scope === "today") return `没有找到 ${range.targetDate} 的 Codex 活动`;
+  if (range.scope === "last-7-days") return `没有找到 ${range.startDate} 至 ${range.endDate} 的 Codex 活动`;
+  if (range.scope === "this-week") return `本周暂时没有找到 Codex 活动`;
+  return "没有找到可统计的 Codex 会话";
+}
+
+export function collectMetrics(sessions, range) {
   const scopedSessions = [];
   const sessionIds = [];
   const tokens = zeroUsage();
@@ -73,24 +80,25 @@ export function collectMetrics(sessions, mode, timezone) {
   let totalFirstTokenMs = 0;
   let firstTokenSamples = 0;
   const timestamps = [];
+  const activeDateKeys = new Set();
   const models = new Set();
 
   for (const session of sessions) {
-    const scopedRows = mode === "latest"
-      ? session.rows
-      : session.rows.filter((row) => {
-          const date = rowDate(row);
-          return date && dateKey(date, timezone) === targetDate;
-        });
+    const scopedRows = isCalendarScope(range.scope)
+      ? session.rows.filter((row) => isDateInRange(rowDate(row), range))
+      : session.rows;
 
     if (!scopedRows.length) continue;
     scopedSessions.push(session);
     sessionIds.push(session.sessionId);
-    addUsage(tokens, sessionTokenUsage(session.rows, mode, targetDate, timezone));
+    addUsage(tokens, sessionTokenUsage(session.rows, range));
 
     for (const row of scopedRows) {
       const date = rowDate(row);
-      if (date) timestamps.push(date);
+      if (date) {
+        timestamps.push(date);
+        activeDateKeys.add(dateKey(date, range.timezone));
+      }
 
       if (row.type === "turn_context" && row.payload?.model) models.add(row.payload.model);
       if (row.type === "event_msg") {
@@ -121,15 +129,19 @@ export function collectMetrics(sessions, mode, timezone) {
     if (fallbackModel) models.add(fallbackModel);
   }
 
-  if (!scopedSessions.length) {
-    throw new Error(mode === "today" ? `没有找到 ${targetDate} 的 Codex 活动` : "没有找到可统计的 Codex 会话");
-  }
+  if (!scopedSessions.length || !timestamps.length) throw new Error(emptyRangeMessage(range));
 
   timestamps.sort((left, right) => left - right);
+  const rangeStartDate = range.startDate || dateKey(timestamps[0], range.timezone);
+  const rangeEndDate = range.endDate || dateKey(timestamps.at(-1), range.timezone);
   const metrics = {
-    mode,
-    timezone,
-    targetDate,
+    mode: range.scope,
+    timezone: range.timezone,
+    targetDate: range.targetDate,
+    rangeStartDate,
+    rangeEndDate,
+    calendarDayCount: isCalendarScope(range.scope) ? calendarDayCount(range) : 1,
+    activeDayCount: Math.max(1, activeDateKeys.size),
     sessionIds,
     sessionCount: scopedSessions.length,
     startAt: timestamps[0],

package/src/core/presentation.mjs

@@ -88,12 +88,16 @@ const RECEIPT_COPY = {
     },
     scope: {
       latest: "最近一次会话",
+      session: "指定会话",
       today: "今日全部会话",
+      "last-7-days": "最近 7 个自然日",
+      "this-week": "本周全部会话",
     },
     modelMissing: "未记录",
     meta: {
       date: "日期",
       hours: "营业时段",
+      period: "统计周期",
       number: "小票编号",
       timezone: "时区",
     },
@@ -146,12 +150,16 @@ const RECEIPT_COPY = {
     },
     scope: {
       latest: "Latest session",
+      session: "Selected session",
       today: "All sessions today",
+      "last-7-days": "Last 7 calendar days",
+      "this-week": "All sessions this week",
     },
     modelMissing: "Not recorded",
     meta: {
       date: "Date",
       hours: "Work hours",
+      period: "Period",
       number: "Receipt No.",
       timezone: "Timezone",
     },
@@ -196,25 +204,32 @@ const RECEIPT_COPY = {
 const COMPENSATION_COPY = {
   "zh-CN": {
     latest: "本单工资",
+    session: "本单工资",
     today: "本日工资",
+    "last-7-days": "近七日工资",
+    "this-week": "本周工资",
     unit: "AI 工分",
     note: "按轮次、工具调用、Token 和改需求次数娱乐折算，不代表真实费用。",
   },
   en: {
     latest: "SHIFT PAY",
+    session: "SHIFT PAY",
     today: "TODAY'S PAY",
+    "last-7-days": "7-DAY PAY",
+    "this-week": "THIS WEEK'S PAY",
     unit: "AI work pts",
     note: "A playful score based on turns, tool calls, Tokens, and interruptions. Not a real charge.",
   },
 };
 
 export function selectWorkProfileId(metrics) {
-  if (metrics.interruptions >= 3) return "change-request-survivor";
-  if (metrics.toolCalls >= 40) return "toolchain-commander";
-  if (metrics.tokens.total_tokens >= 500_000) return "context-devouring-beast";
-  if (metrics.completedTurns >= 12) return "continuous-delivery-machine";
-  if (metrics.workDurationMs >= 60 * 60 * 1000) return "night-shift-companion";
-  if (metrics.completedTurns >= 5) return "steady-progress-partner";
+  const scale = Math.max(1, Number(metrics.activeDayCount || 1));
+  if (metrics.interruptions >= 3 * scale) return "change-request-survivor";
+  if (metrics.toolCalls >= 40 * scale) return "toolchain-commander";
+  if (metrics.tokens.total_tokens >= 500_000 * scale) return "context-devouring-beast";
+  if (metrics.completedTurns >= 12 * scale) return "continuous-delivery-machine";
+  if (metrics.workDurationMs >= 60 * 60 * 1000 * scale) return "night-shift-companion";
+  if (metrics.completedTurns >= 5 * scale) return "steady-progress-partner";
   return "temporary-hire";
 }
 
@@ -230,7 +245,7 @@ export function getReceiptCopy(locale = DEFAULT_LOCALE) {
 export function buildCompensation(scope, amount, locale = DEFAULT_LOCALE) {
   const copy = COMPENSATION_COPY[SUPPORTED_LOCALES.has(locale) ? locale : DEFAULT_LOCALE];
   return {
-    label: scope === "today" ? copy.today : copy.latest,
+    label: copy[scope] || copy.latest,
     amount: Number(amount || 0),
     unit: copy.unit,
     note: copy.note,

package/src/core/qr-payload.mjs

@@ -5,18 +5,26 @@ import { buildCompensation, getWorkProfileCopy } from "./presentation.mjs";
 
 export function compactReceipt(record) {
   const profileId = record.presentation.work_profile;
+  const scope = record.source?.scope || (record.presentation.compensation?.label === "本日工资" ? "today" : "latest");
   const mobileProfile = profileId
     ? getWorkProfileCopy(profileId, "zh-CN")
     : { title: record.presentation.work_title, review: record.presentation.review };
   const mobileCompensation = profileId
-    ? buildCompensation(record.source.scope, record.presentation.compensation?.amount, "zh-CN")
+    ? buildCompensation(scope, record.presentation.compensation?.amount, "zh-CN")
     : record.presentation.compensation;
 
   return {
     v: record.schema_version,
     i: record.id,
     g: record.generated_at,
-    d: [record.period.start_at, record.period.end_at, record.period.timezone],
+    o: scope,
+    d: [
+      record.period.start_at,
+      record.period.end_at,
+      record.period.timezone,
+      record.period.range_start_date || null,
+      record.period.range_end_date || null,
+    ],
     s: [
       record.stats.session_count,
       record.stats.completed_turns,

package/src/core/range.mjs

@@ -0,0 +1,99 @@
+import { dateKey } from "../lib/time.mjs";
+
+export const RECEIPT_SCOPES = new Set([
+  "latest",
+  "session",
+  "today",
+  "last-7-days",
+  "this-week",
+]);
+
+const SCOPE_ALIASES = new Map([
+  ["latest", "latest"],
+  ["session", "session"],
+  ["today", "today"],
+  ["7d", "last-7-days"],
+  ["last-7-days", "last-7-days"],
+  ["last7days", "last-7-days"],
+  ["week", "this-week"],
+  ["this-week", "this-week"],
+]);
+
+export function normalizeScope(value) {
+  return SCOPE_ALIASES.get(String(value || "").trim().toLowerCase()) || null;
+}
+
+export function shiftDateKey(value, days) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value));
+  if (!match) throw new Error(`无效日期：${value}`);
+  const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  date.setUTCDate(date.getUTCDate() + Number(days || 0));
+  return date.toISOString().slice(0, 10);
+}
+
+function mondayDateKey(value) {
+  const [year, month, day] = value.split("-").map(Number);
+  const weekday = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+  const daysSinceMonday = weekday === 0 ? 6 : weekday - 1;
+  return shiftDateKey(value, -daysSinceMonday);
+}
+
+export function resolveRange(scope, timezone, now = new Date(), sessionId = null) {
+  const normalizedScope = normalizeScope(scope);
+  if (!normalizedScope || !RECEIPT_SCOPES.has(normalizedScope)) {
+    throw new Error(`不支持的统计范围：${scope}`);
+  }
+
+  const targetDate = dateKey(now, timezone);
+  let startDate = null;
+  let endDate = null;
+
+  if (normalizedScope === "today") {
+    startDate = targetDate;
+    endDate = targetDate;
+  } else if (normalizedScope === "last-7-days") {
+    startDate = shiftDateKey(targetDate, -6);
+    endDate = targetDate;
+  } else if (normalizedScope === "this-week") {
+    startDate = mondayDateKey(targetDate);
+    endDate = targetDate;
+  }
+
+  return {
+    scope: normalizedScope,
+    timezone,
+    targetDate,
+    startDate,
+    endDate,
+    sessionId: sessionId || null,
+  };
+}
+
+export function isCalendarScope(scope) {
+  return scope === "today" || scope === "last-7-days" || scope === "this-week";
+}
+
+export function isDateInRange(date, range) {
+  if (!date) return false;
+  if (!isCalendarScope(range.scope)) return true;
+  const key = dateKey(date, range.timezone);
+  return key >= range.startDate && key <= range.endDate;
+}
+
+export function calendarDayCount(range) {
+  if (!range.startDate || !range.endDate) return 1;
+  let count = 1;
+  let current = range.startDate;
+  while (current < range.endDate) {
+    current = shiftDateKey(current, 1);
+    count += 1;
+  }
+  return count;
+}
+
+export function outputSlugForScope(scope) {
+  if (scope === "last-7-days") return "last-7-days";
+  if (scope === "this-week") return "this-week";
+  if (scope === "session") return "session";
+  return scope;
+}

package/src/core/receipt-record.mjs

@@ -10,7 +10,7 @@ import {
 } from "./presentation.mjs";
 
 const SCHEMA_VERSION = 1;
-const COLLECTOR_VERSION = "0.3.0";
+const COLLECTOR_VERSION = "0.4.0";
 
 function fingerprintSessionIds(sessionIds) {
   return crypto.createHash("sha256").update([...sessionIds].sort().join("|")).digest("hex").slice(0, 16);
@@ -18,9 +18,11 @@ function fingerprintSessionIds(sessionIds) {
 
 export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = DEFAULT_LOCALE) {
   const sessionFingerprint = fingerprintSessionIds(metrics.sessionIds);
-  const logicalKey = metrics.mode === "latest"
+  const logicalKey = metrics.mode === "latest" || metrics.mode === "session"
     ? `latest:${sessionFingerprint}`
-    : `today:${metrics.targetDate}:${metrics.timezone}`;
+    : metrics.mode === "this-week"
+      ? `this-week:${metrics.rangeStartDate}:${metrics.timezone}`
+      : `${metrics.mode}:${metrics.rangeStartDate}:${metrics.rangeEndDate}:${metrics.timezone}`;
   const id = `cwr_${crypto.createHash("sha256").update(logicalKey).digest("hex").slice(0, 16)}`;
   const snapshotHash = crypto.createHash("sha256").update(JSON.stringify({
     start: metrics.startAt.toISOString(),
@@ -29,6 +31,9 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
     tools: metrics.toolCalls,
     turns: metrics.completedTurns,
     interruptions: metrics.interruptions,
+    scope: metrics.mode,
+    rangeStartDate: metrics.rangeStartDate,
+    rangeEndDate: metrics.rangeEndDate,
   })).digest("hex").slice(0, 16);
   const workProfileId = metrics.workProfileId || "temporary-hire";
   const workProfile = getWorkProfileCopy(workProfileId, locale);
@@ -50,6 +55,8 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
       start_at: metrics.startAt.toISOString(),
       end_at: metrics.endAt.toISOString(),
       timezone: metrics.timezone,
+      range_start_date: metrics.rangeStartDate,
+      range_end_date: metrics.rangeEndDate,
     },
     stats: {
       session_count: metrics.sessionCount,

package/src/core/selector.mjs

@@ -0,0 +1,71 @@
+import { createInterface } from "node:readline/promises";
+
+function formatSessionDate(value, timezone, locale) {
+  return new Intl.DateTimeFormat(locale === "en" ? "en-US" : "zh-CN", {
+    timeZone: timezone,
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(value);
+}
+
+function sessionLine(session, index, timezone, locale) {
+  const start = formatSessionDate(session.startAt, timezone, locale);
+  const end = formatSessionDate(session.endAt, timezone, locale);
+  const model = session.model || (locale === "en" ? "model unknown" : "模型未记录");
+  if (locale === "en") {
+    return `${index + 1}. ${start}–${end} · ${session.completedTurns} turns · ${session.toolCalls} tool calls · ${model}`;
+  }
+  return `${index + 1}. ${start}–${end} · ${session.completedTurns} 轮 · ${session.toolCalls} 次工具调用 · ${model}`;
+}
+
+async function askForNumber(readline, prompt, minimum, maximum, fallback = null) {
+  while (true) {
+    const answer = (await readline.question(prompt)).trim();
+    if (!answer && fallback !== null) return fallback;
+    const value = Number(answer);
+    if (Number.isInteger(value) && value >= minimum && value <= maximum) return value;
+  }
+}
+
+export async function promptForRange({ locale, timezone, loadRecentSessions }) {
+  const isEnglish = locale === "en";
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    console.log(isEnglish ? "\nChoose a receipt range:\n" : "\n请选择小票统计范围：\n");
+    console.log(isEnglish ? "1. All activity today (recommended)" : "1. 今天全部活动（推荐）");
+    console.log(isEnglish ? "2. Last 7 calendar days" : "2. 最近 7 个自然日");
+    console.log(isEnglish ? "3. This week (Monday to now)" : "3. 本周（周一至今）");
+    console.log(isEnglish ? "4. Choose a specific session" : "4. 选择一个具体会话");
+
+    const choice = await askForNumber(
+      readline,
+      isEnglish ? "\nEnter 1–4 (default 1): " : "\n请输入 1–4（默认 1）：",
+      1,
+      4,
+      1,
+    );
+
+    if (choice === 1) return { mode: "today", sessionId: null };
+    if (choice === 2) return { mode: "last-7-days", sessionId: null };
+    if (choice === 3) return { mode: "this-week", sessionId: null };
+
+    const sessions = await loadRecentSessions();
+    if (!sessions.length) throw new Error(isEnglish ? "No Codex sessions found" : "没有找到可选择的 Codex 会话");
+
+    console.log(isEnglish ? "\nRecent sessions:\n" : "\n最近的会话：\n");
+    sessions.forEach((session, index) => console.log(sessionLine(session, index, timezone, locale)));
+    const sessionChoice = await askForNumber(
+      readline,
+      isEnglish ? `\nEnter 1–${sessions.length}: ` : `\n请输入 1–${sessions.length}：`,
+      1,
+      sessions.length,
+    );
+    return { mode: "session", sessionId: sessions[sessionChoice - 1].sessionId };
+  } finally {
+    readline.close();
+  }
+}

package/src/parsers/codex.mjs

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { rowDate } from "../lib/time.mjs";
+
 function walkJsonlFiles(directory, accumulator = []) {
   if (!fs.existsSync(directory)) return accumulator;
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
@@ -26,26 +28,90 @@ function readJsonl(filePath) {
   return rows;
 }
 
-export function loadCodexSessions(mode) {
+function sessionFromFile(file) {
+  const rows = readJsonl(file.filePath);
+  const meta = rows.find((row) => row.type === "session_meta")?.payload || {};
+  const timestamps = rows.map(rowDate).filter(Boolean).sort((left, right) => left - right);
+  const fallbackDate = new Date(file.modifiedAt);
+  return {
+    rows,
+    filePath: file.filePath,
+    modifiedAt: file.modifiedAt,
+    sessionId: meta.session_id || meta.id || path.basename(file.filePath, ".jsonl"),
+    startAt: timestamps[0] || fallbackDate,
+    endAt: timestamps.at(-1) || fallbackDate,
+  };
+}
+
+function codexSessionFiles() {
   const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
   const sessionsDirectory = path.join(codexHome, "sessions");
   const files = walkJsonlFiles(sessionsDirectory)
     .map((filePath) => ({ filePath, modifiedAt: fs.statSync(filePath).mtimeMs }))
     .sort((left, right) => right.modifiedAt - left.modifiedAt);
-
   if (!files.length) throw new Error(`没有在 ${sessionsDirectory} 找到 Codex 会话记录`);
+  return files;
+}
+
+function calendarCandidates(files, startDate) {
+  if (!startDate) return files;
+  const approximateStart = Date.parse(`${startDate}T00:00:00.000Z`) - 48 * 60 * 60 * 1000;
+  return files.filter((file) => file.modifiedAt >= approximateStart);
+}
+
+export function loadCodexSessions(range) {
+  const files = codexSessionFiles();
+  let candidates = files;
 
-  const selected = mode === "latest"
-    ? files.slice(0, 1)
-    : files.filter((file) => file.modifiedAt >= Date.now() - 72 * 60 * 60 * 1000);
+  if (range.scope === "latest") {
+    candidates = files.slice(0, 40);
+  } else if (range.scope === "session" && range.sessionId) {
+    const filenameMatches = files.filter((file) => path.basename(file.filePath).includes(range.sessionId));
+    candidates = filenameMatches.length ? filenameMatches : files;
+  } else {
+    candidates = calendarCandidates(files, range.startDate);
+  }
+
+  const sessions = candidates
+    .map(sessionFromFile)
+    .sort((left, right) => right.endAt - left.endAt);
+
+  if (range.scope === "latest") return sessions.slice(0, 1);
+  if (range.scope === "session") {
+    const selected = sessions.find((session) => session.sessionId === range.sessionId);
+    if (!selected) throw new Error(`没有找到指定的 Codex 会话：${range.sessionId}`);
+    return [selected];
+  }
+  return sessions;
+}
+
+export function listRecentCodexSessions(limit = 10) {
+  const sessions = codexSessionFiles()
+    .slice(0, Math.max(40, limit * 3))
+    .map(sessionFromFile)
+    .filter((session) => session.rows.length)
+    .sort((left, right) => right.endAt - left.endAt)
+    .slice(0, limit);
 
-  return selected.map((file) => {
-    const rows = readJsonl(file.filePath);
-    const meta = rows.find((row) => row.type === "session_meta")?.payload || {};
+  return sessions.map((session) => {
+    let completedTurns = 0;
+    let toolCalls = 0;
+    let model = null;
+    for (const row of session.rows) {
+      if (row.type === "turn_context" && row.payload?.model) model = row.payload.model;
+      if (row.type === "event_msg" && row.payload?.type === "task_complete") completedTurns += 1;
+      if (
+        row.type === "response_item" &&
+        (row.payload?.type === "custom_tool_call" || row.payload?.type === "function_call")
+      ) toolCalls += 1;
+    }
     return {
-      rows,
-      sessionId: meta.session_id || meta.id || path.basename(file.filePath, ".jsonl"),
+      sessionId: session.sessionId,
+      startAt: session.startAt,
+      endAt: session.endAt,
+      completedTurns,
+      toolCalls,
+      model,
     };
   });
 }
-