agent-optic 0.2.0

package/src/aggregations/project.ts

@@ -0,0 +1,71 @@
+import type { PrivacyConfig } from "../types/privacy.js";
+import type { Provider } from "../types/provider.js";
+import type { ProjectSummary, SessionListFilter } from "../types/aggregations.js";
+import type { SessionInfo, ToolCallSummary } from "../types/session.js";
+import { readHistory } from "../readers/history-reader.js";
+import { parseSessionDetail } from "../parsers/session-detail.js";
+import { resolveDateRange } from "../utils/dates.js";
+import { projectName } from "../utils/paths.js";
+import { estimateHours } from "./time.js";
+
+/** Build per-project summaries from session data. */
+export async function buildProjectSummaries(
+	provider: Provider,
+	filter: SessionListFilter,
+	historyFile: string,
+	paths: { projectsDir: string; sessionsDir: string },
+	privacy: PrivacyConfig,
+): Promise<ProjectSummary[]> {
+	const { from, to } = resolveDateRange(filter);
+	const sessions = await readHistory(historyFile, from, to, privacy, {
+		provider,
+		sessionsDir: paths.sessionsDir,
+	});
+
+	// Group by project
+	const byProject = new Map<string, SessionInfo[]>();
+	for (const session of sessions) {
+		const name = session.projectName;
+		if (filter.project && !name.toLowerCase().includes(filter.project.toLowerCase())) continue;
+		const existing = byProject.get(name);
+		if (existing) {
+			existing.push(session);
+		} else {
+			byProject.set(name, [session]);
+		}
+	}
+
+	const summaries: ProjectSummary[] = [];
+
+	for (const [name, projectSessions] of byProject) {
+		const allToolCalls: ToolCallSummary[] = [];
+		const allFiles: string[] = [];
+		const allBranches: string[] = [];
+		const allModels: string[] = [];
+
+		// Parse detailed sessions for rich data
+		for (const session of projectSessions) {
+			if (session.prompts.length >= 3) {
+				const detail = await parseSessionDetail(provider, session, paths, privacy);
+				allToolCalls.push(...detail.toolCalls);
+				allFiles.push(...detail.filesReferenced);
+				if (detail.gitBranch) allBranches.push(detail.gitBranch);
+				if (detail.model) allModels.push(detail.model);
+			}
+		}
+
+		summaries.push({
+			project: projectSessions[0].project,
+			projectName: name,
+			sessionCount: projectSessions.length,
+			promptCount: projectSessions.reduce((sum, s) => sum + s.prompts.length, 0),
+			estimatedHours: estimateHours(projectSessions),
+			branches: [...new Set(allBranches)],
+			filesReferenced: [...new Set(allFiles)],
+			toolCalls: allToolCalls,
+			models: [...new Set(allModels)],
+		});
+	}
+
+	return summaries.sort((a, b) => b.promptCount - a.promptCount);
+}

package/src/aggregations/time.ts

@@ -0,0 +1,44 @@
+import type { SessionInfo } from "../types/session.js";
+
+/** Gap cap in ms — if gap between consecutive prompts exceeds this, cap it. */
+const GAP_CAP_MS = 15 * 60 * 1000; // 15 minutes
+
+/**
+ * Estimate hours of active work from session timestamp data.
+ * Merges all timestamps across sessions into a single sorted timeline,
+ * then applies gap-capping. This deduplicates overlapping intervals so
+ * concurrent sessions (e.g. multiple terminal tabs) share wall-clock time
+ * instead of stacking it.
+ */
+export function estimateHours(sessions: SessionInfo[]): number {
+	if (sessions.length === 0) return 0;
+
+	// Merge all timestamps across sessions into a single timeline
+	const allTimestamps: number[] = [];
+
+	for (const session of sessions) {
+		if (session.promptTimestamps.length > 0) {
+			allTimestamps.push(...session.promptTimestamps);
+		} else {
+			// Sessions with no prompt timestamps: use start/end
+			const ts = [session.timeRange.start, session.timeRange.end].filter(t => t > 0);
+			allTimestamps.push(...ts);
+		}
+	}
+
+	if (allTimestamps.length === 0) return 0;
+
+	allTimestamps.sort((a, b) => a - b);
+
+	if (allTimestamps.length === 1) {
+		return 5 / 60; // Single timestamp → 5 minutes
+	}
+
+	let totalMs = 0;
+	for (let i = 1; i < allTimestamps.length; i++) {
+		const gap = allTimestamps[i] - allTimestamps[i - 1];
+		totalMs += Math.min(gap, GAP_CAP_MS);
+	}
+
+	return totalMs / (1000 * 60 * 60);
+}

package/src/aggregations/tools.ts

@@ -0,0 +1,60 @@
+import type { PrivacyConfig } from "../types/privacy.js";
+import type { Provider } from "../types/provider.js";
+import type { ToolUsageReport, SessionListFilter } from "../types/aggregations.js";
+import type { ToolCategory, ToolCallSummary } from "../types/session.js";
+import { readHistory } from "../readers/history-reader.js";
+import { parseSessionDetail } from "../parsers/session-detail.js";
+import { resolveDateRange } from "../utils/dates.js";
+
+/** Build a tool usage report from session data. */
+export async function buildToolUsageReport(
+	provider: Provider,
+	filter: SessionListFilter,
+	historyFile: string,
+	paths: { projectsDir: string; sessionsDir: string },
+	privacy: PrivacyConfig,
+): Promise<ToolUsageReport> {
+	const { from, to } = resolveDateRange(filter);
+	const sessions = await readHistory(historyFile, from, to, privacy, {
+		provider,
+		sessionsDir: paths.sessionsDir,
+	});
+
+	const byTool = new Map<string, number>();
+	const byCategory = new Map<ToolCategory, number>();
+	const fileCounts = new Map<string, number>();
+	const commandCounts = new Map<string, number>();
+	let total = 0;
+
+	for (const session of sessions) {
+		if (session.prompts.length < 2) continue; // skip trivial sessions
+		const detail = await parseSessionDetail(provider, session, paths, privacy);
+
+		for (const tc of detail.toolCalls) {
+			byTool.set(tc.name, (byTool.get(tc.name) ?? 0) + 1);
+			byCategory.set(tc.category, (byCategory.get(tc.category) ?? 0) + 1);
+			total++;
+
+			if (tc.target) {
+				if (tc.category === "file_read" || tc.category === "file_write") {
+					fileCounts.set(tc.target, (fileCounts.get(tc.target) ?? 0) + 1);
+				}
+				if (tc.category === "shell") {
+					commandCounts.set(tc.target, (commandCounts.get(tc.target) ?? 0) + 1);
+				}
+			}
+		}
+	}
+
+	const topFiles = [...fileCounts.entries()]
+		.sort((a, b) => b[1] - a[1])
+		.slice(0, 20)
+		.map(([path, count]) => ({ path, count }));
+
+	const topCommands = [...commandCounts.entries()]
+		.sort((a, b) => b[1] - a[1])
+		.slice(0, 20)
+		.map(([command, count]) => ({ command, count }));
+
+	return { byTool, byCategory, topFiles, topCommands, total };
+}

package/src/claude-optic.ts

@@ -0,0 +1,7 @@
+export { createClaudeHistory, createHistory } from "./agent-optic.js";
+export type {
+	ClaudeHistory,
+	ClaudeHistoryConfig,
+	History,
+	HistoryConfig,
+} from "./agent-optic.js";

package/src/cli/index.ts

@@ -0,0 +1,407 @@
+#!/usr/bin/env bun
+
+import { createHistory } from "../agent-optic.js";
+import type { PrivacyProfile } from "../types/privacy.js";
+import type { Provider } from "../types/provider.js";
+import { today } from "../utils/dates.js";
+import { defaultProviderDir, isProvider } from "../utils/providers.js";
+
+const SCHEMA_VERSION = "1.0";
+
+type OutputFormat = "json" | "jsonl";
+
+const HELP = `agent-optic — Read AI assistant session data from local provider directories
+
+USAGE
+  agent-optic <command> [options]
+
+COMMANDS
+  sessions <optional-id>   List sessions with metadata
+  detail <session-id>      Show full detail for one session
+  transcript <session-id>  Stream/print transcript entries
+  tool-usage               Show aggregated tool usage
+  projects                 List all projects
+  stats                    Show pre-computed stats
+  daily                    Show daily summary
+  export                   Export session data with privacy controls
+
+OPTIONS
+  --date YYYY-MM-DD     Filter to specific date (default: today)
+  --from YYYY-MM-DD     Start of date range
+  --to YYYY-MM-DD       End of date range
+  --project <name>      Filter by project name
+  --provider <name>     Data provider: claude (default), codex, openai, cursor, windsurf
+  --provider-dir <path> Override provider data directory (default: ~/.<provider>)
+  --privacy <profile>   Privacy profile: local (default), shareable, strict
+  --format <mode>       Output mode: json (default), jsonl
+  --fields <a,b,c>      Select object fields (top-level)
+  --limit <n>           Limit array/stream length
+  --pretty              Pretty-print JSON output
+  --raw                 Disable output envelope (data only)
+  --help                Show this help
+
+EXAMPLES
+  agent-optic sessions --provider codex --format jsonl
+  agent-optic detail 019c9aea-484d-7200-87fd-07a545276ac4 --provider openai
+  agent-optic transcript 019c9aea-484d-7200-87fd-07a545276ac4 --provider openai --format jsonl --limit 50
+  agent-optic tool-usage --provider codex --from 2026-02-01 --to 2026-02-26
+  agent-optic sessions --provider codex --date 2026-02-09
+  agent-optic sessions --provider openai --date 2026-02-09
+
+SECURITY
+  Provider home directories contain highly sensitive data including API keys, source code,
+  and personal information. See SECURITY.md for details.
+`;
+
+interface CliArgs {
+	command: string;
+	commandArg?: string;
+	date?: string;
+	from?: string;
+	to?: string;
+	project?: string;
+	provider: Provider;
+	providerDir?: string;
+	privacy: PrivacyProfile;
+	format: OutputFormat;
+	fields?: string[];
+	limit?: number;
+	pretty: boolean;
+	raw: boolean;
+	help: boolean;
+}
+
+class CliError extends Error {
+	constructor(
+		public code: string,
+		message: string,
+		public exitCode = 1,
+		public details?: Record<string, unknown>,
+	) {
+		super(message);
+	}
+}
+
+function parseArgs(args: string[]): CliArgs {
+	const result: CliArgs = {
+		command: "",
+		provider: "claude",
+		privacy: "local",
+		format: "json",
+		pretty: false,
+		raw: false,
+		help: false,
+	};
+
+	let i = 0;
+	while (i < args.length) {
+		const arg = args[i];
+
+		if (arg === "--help" || arg === "-h") {
+			result.help = true;
+		} else if (arg === "--date" && args[i + 1]) {
+			result.date = args[++i];
+		} else if (arg === "--from" && args[i + 1]) {
+			result.from = args[++i];
+		} else if (arg === "--to" && args[i + 1]) {
+			result.to = args[++i];
+		} else if (arg === "--project" && args[i + 1]) {
+			result.project = args[++i];
+		} else if (arg === "--provider" && args[i + 1]) {
+			result.provider = args[++i] as Provider;
+		} else if (arg === "--provider-dir" && args[i + 1]) {
+			result.providerDir = args[++i];
+		} else if (arg === "--privacy" && args[i + 1]) {
+			result.privacy = args[++i] as PrivacyProfile;
+		} else if (arg === "--format" && args[i + 1]) {
+			result.format = args[++i] as OutputFormat;
+		} else if (arg === "--fields" && args[i + 1]) {
+			result.fields = args[++i]
+				.split(",")
+				.map((f) => f.trim())
+				.filter(Boolean);
+		} else if (arg === "--limit" && args[i + 1]) {
+			const parsed = Number.parseInt(args[++i], 10);
+			if (Number.isFinite(parsed) && parsed > 0) {
+				result.limit = parsed;
+			}
+		} else if (arg === "--pretty") {
+			result.pretty = true;
+		} else if (arg === "--raw") {
+			result.raw = true;
+		} else if (!arg.startsWith("-") && !result.command) {
+			result.command = arg;
+		} else if (!arg.startsWith("-") && !result.commandArg) {
+			result.commandArg = arg;
+		}
+
+		i++;
+	}
+
+	return result;
+}
+
+function applyFieldSelection(data: unknown, fields?: string[]): unknown {
+	if (!fields || fields.length === 0) return data;
+
+	if (Array.isArray(data)) {
+		return data.map((item) => applyFieldSelection(item, fields));
+	}
+
+	if (!data || typeof data !== "object") return data;
+	const obj = data as Record<string, unknown>;
+	const selected: Record<string, unknown> = {};
+	for (const field of fields) {
+		if (field in obj) selected[field] = obj[field];
+	}
+	return selected;
+}
+
+function applyLimit(data: unknown, limit?: number): unknown {
+	if (!limit) return data;
+	if (Array.isArray(data)) return data.slice(0, limit);
+	return data;
+}
+
+function writeOutput(
+	command: string,
+	provider: Provider,
+	data: unknown,
+	args: CliArgs,
+): void {
+	const transformed = applyLimit(applyFieldSelection(data, args.fields), args.limit);
+	const generatedAt = new Date().toISOString();
+
+	if (args.format === "json") {
+		const payload = args.raw
+			? transformed
+			: {
+				schemaVersion: SCHEMA_VERSION,
+				command,
+				provider,
+				generatedAt,
+				data: transformed,
+			};
+		console.log(
+			JSON.stringify(payload, mapReplacer, args.pretty ? 2 : 0),
+		);
+		return;
+	}
+
+	const rows = Array.isArray(transformed) ? transformed : [transformed];
+	for (const row of rows) {
+		const payload = args.raw
+			? row
+			: {
+				schemaVersion: SCHEMA_VERSION,
+				command,
+				provider,
+				generatedAt,
+				data: row,
+			};
+		console.log(JSON.stringify(payload, mapReplacer));
+	}
+}
+
+/** JSON.stringify replacer that converts Maps to plain objects. */
+function mapReplacer(_key: string, value: unknown): unknown {
+	if (value instanceof Map) {
+		return Object.fromEntries(value);
+	}
+	return value;
+}
+
+function printError(error: CliError, args?: CliArgs): void {
+	const format = args?.format ?? "json";
+	const payload = {
+		schemaVersion: SCHEMA_VERSION,
+		error: {
+			code: error.code,
+			message: error.message,
+			details: error.details,
+		},
+	};
+	const text =
+		format === "json" && args?.pretty
+			? JSON.stringify(payload, null, 2)
+			: JSON.stringify(payload);
+	console.error(text);
+}
+
+function assertValidArgs(args: CliArgs): void {
+	if (!["local", "shareable", "strict"].includes(args.privacy)) {
+		throw new CliError(
+			"INVALID_PRIVACY_PROFILE",
+			`Invalid privacy profile: ${args.privacy}. Use: local, shareable, strict`,
+		);
+	}
+
+	if (!isProvider(args.provider)) {
+		throw new CliError(
+			"INVALID_PROVIDER",
+			`Invalid provider: ${args.provider}. Use: claude, codex, openai, cursor, windsurf`,
+		);
+	}
+
+	if (!["json", "jsonl"].includes(args.format)) {
+		throw new CliError(
+			"INVALID_FORMAT",
+			`Invalid format: ${args.format}. Use: json, jsonl`,
+		);
+	}
+}
+
+async function run(args: CliArgs): Promise<void> {
+	if (args.help || !args.command) {
+		console.log(HELP);
+		process.exit(args.help ? 0 : 1);
+	}
+
+	assertValidArgs(args);
+
+	const providerDir = args.providerDir ?? defaultProviderDir(args.provider);
+	const ch = createHistory({
+		provider: args.provider,
+		providerDir,
+		privacy: args.privacy,
+	});
+
+	const filter = {
+		date: args.date,
+		from: args.from,
+		to: args.to,
+		project: args.project,
+	};
+
+	switch (args.command) {
+		case "sessions": {
+			const sessionsFilter =
+				args.commandArg && !args.date && !args.from && !args.to
+					? { ...filter, from: "2000-01-01", to: "2099-12-31" }
+					: filter;
+			let sessions = await ch.sessions.listWithMeta(sessionsFilter);
+			if (args.commandArg) {
+				sessions = sessions.filter((s) => s.sessionId === args.commandArg);
+			}
+			writeOutput("sessions", args.provider, sessions, args);
+			return;
+		}
+
+		case "detail": {
+			if (!args.commandArg) {
+				throw new CliError(
+					"MISSING_ARGUMENT",
+					"Missing session ID. Usage: agent-optic detail <session-id>",
+				);
+			}
+			const detail = await ch.sessions.detail(args.commandArg, args.project);
+			writeOutput("detail", args.provider, detail, args);
+			return;
+		}
+
+		case "transcript": {
+			if (!args.commandArg) {
+				throw new CliError(
+					"MISSING_ARGUMENT",
+					"Missing session ID. Usage: agent-optic transcript <session-id>",
+				);
+			}
+
+			if (args.format === "jsonl") {
+				const generatedAt = new Date().toISOString();
+				let count = 0;
+				for await (const entry of ch.sessions.transcript(args.commandArg, args.project)) {
+					if (args.limit && count >= args.limit) break;
+					const transformed = applyFieldSelection(entry, args.fields);
+					const payload = args.raw
+						? transformed
+						: {
+							schemaVersion: SCHEMA_VERSION,
+							command: "transcript",
+							provider: args.provider,
+							generatedAt,
+							data: transformed,
+						};
+					console.log(JSON.stringify(payload, mapReplacer));
+					count++;
+				}
+				return;
+			}
+
+			const entries: unknown[] = [];
+			for await (const entry of ch.sessions.transcript(args.commandArg, args.project)) {
+				entries.push(entry);
+				if (args.limit && entries.length >= args.limit) break;
+			}
+			writeOutput("transcript", args.provider, entries, args);
+			return;
+		}
+
+		case "tool-usage": {
+			const usage = await ch.aggregate.toolUsage(filter);
+			writeOutput("tool-usage", args.provider, usage, args);
+			return;
+		}
+
+		case "projects": {
+			const projects = await ch.projects.list();
+			writeOutput("projects", args.provider, projects, args);
+			return;
+		}
+
+		case "stats": {
+			const stats = await ch.stats.get();
+			if (!stats) {
+				throw new CliError(
+					"STATS_NOT_FOUND",
+					`No stats cache found at ${providerDir}/stats-cache.json`,
+				);
+			}
+			writeOutput("stats", args.provider, stats, args);
+			return;
+		}
+
+		case "daily": {
+			const date = args.date ?? today();
+			const summary = await ch.aggregate.daily(date);
+			writeOutput("daily", args.provider, summary, args);
+			return;
+		}
+
+		case "export": {
+			const date = args.date;
+			const from = args.from ?? date ?? today();
+			const to = args.to ?? date ?? today();
+			const summaries = await ch.aggregate.dailyRange(from, to);
+			writeOutput("export", args.provider, summaries, args);
+			return;
+		}
+
+		default:
+			throw new CliError(
+				"UNKNOWN_COMMAND",
+				`Unknown command: ${args.command}`,
+				2,
+			);
+	}
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	try {
+		await run(args);
+	} catch (err) {
+		if (err instanceof CliError) {
+			printError(err, args);
+			process.exit(err.exitCode);
+		}
+		const fallback = new CliError(
+			"INTERNAL_ERROR",
+			err instanceof Error ? err.message : "Unknown error",
+		);
+		printError(fallback, args);
+		process.exit(fallback.exitCode);
+	}
+}
+
+main();

package/src/index.ts

@@ -0,0 +1,69 @@
+// Main factory
+export { createHistory, createClaudeHistory } from "./agent-optic.js";
+export type { History, HistoryConfig, ClaudeHistory, ClaudeHistoryConfig } from "./agent-optic.js";
+
+// Provider types and utils
+export type { Provider } from "./types/provider.js";
+export { SUPPORTED_PROVIDERS } from "./types/provider.js";
+
+// Types
+export type {
+	HistoryEntry,
+	SessionInfo,
+	SessionMeta,
+	SessionDetail,
+	ToolCategory,
+	ToolCallSummary,
+} from "./types/session.js";
+
+export type { ContentBlock, TranscriptEntry } from "./types/transcript.js";
+
+export type { TaskInfo, TodoItem } from "./types/task.js";
+
+export type { PlanInfo } from "./types/plan.js";
+
+export type { ProjectInfo, ProjectMemory } from "./types/project.js";
+
+export type { StatsCache } from "./types/stats.js";
+
+export type {
+	DailySummary,
+	ProjectSummary,
+	ToolUsageReport,
+	DateFilter,
+	SessionListFilter,
+} from "./types/aggregations.js";
+
+export type { PrivacyConfig, PrivacyProfile } from "./types/privacy.js";
+
+// Privacy profiles (runtime values, not just types)
+export { PRIVACY_PROFILES, resolvePrivacyConfig } from "./privacy/config.js";
+
+// Utilities (for advanced users)
+export {
+	encodeProjectPath,
+	decodeProjectPath,
+	projectName,
+	providerPaths,
+	claudePaths,
+} from "./utils/paths.js";
+export {
+	DEFAULT_PROVIDER,
+	defaultProviderDir,
+	providerHomeDirName,
+	isProvider,
+} from "./utils/providers.js";
+export { toLocalDate, today, formatTime, resolveDateRange } from "./utils/dates.js";
+export { parseJsonl, streamJsonl, peekJsonl, readJsonl } from "./utils/jsonl.js";
+
+// Parsers (for advanced users building custom pipelines)
+export { parseSessionDetail, parseSessions } from "./parsers/session-detail.js";
+export { categorizeToolName, toolDisplayName } from "./parsers/tool-categories.js";
+export { extractText, extractToolCalls, extractFilePaths, countThinkingBlocks } from "./parsers/content-blocks.js";
+
+// Pricing
+export type { ModelPricing } from "./pricing.js";
+export { MODEL_PRICING, getModelPricing, estimateCost, setPricing } from "./pricing.js";
+
+// Readers (for advanced users)
+export { readProjectMemories } from "./readers/project-reader.js";