agent-optic 0.2.0

package/src/readers/session-reader.ts

@@ -0,0 +1,280 @@
+import { join } from "node:path";
+import type { PrivacyConfig } from "../types/privacy.js";
+import type { Provider } from "../types/provider.js";
+import type { SessionInfo, SessionMeta } from "../types/session.js";
+import type { ContentBlock, TranscriptEntry } from "../types/transcript.js";
+import { encodeProjectPath } from "../utils/paths.js";
+import { canonicalProvider } from "../utils/providers.js";
+import { filterTranscriptEntry } from "../privacy/redact.js";
+import {
+	findRolloutFile,
+	parseCodexMessageText,
+	parseCodexToolArguments,
+} from "./codex-rollout-reader.js";
+
+/**
+ * Peek session metadata from a session JSONL file.
+ * Reads the entire file but only extracts lightweight metadata.
+ * This is the "medium" tier — slower than history.jsonl only, but still avoids full parsing.
+ */
+export async function peekSession(
+	provider: Provider,
+	session: SessionInfo,
+	paths: { projectsDir: string; sessionsDir: string },
+	privacy: PrivacyConfig,
+): Promise<SessionMeta> {
+	const normalized = canonicalProvider(provider);
+	if (normalized === "codex") {
+		return peekCodexSession(session, paths.sessionsDir);
+	}
+	return peekClaudeSession(session, paths.projectsDir);
+}
+
+async function peekClaudeSession(
+	session: SessionInfo,
+	projectsDir: string,
+): Promise<SessionMeta> {
+	const meta: SessionMeta = {
+		...session,
+		totalInputTokens: 0,
+		totalOutputTokens: 0,
+		cacheCreationInputTokens: 0,
+		cacheReadInputTokens: 0,
+		messageCount: 0,
+	};
+
+	const encoded = encodeProjectPath(session.project);
+	const filePath = join(projectsDir, encoded, `${session.sessionId}.jsonl`);
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return meta;
+
+	try {
+		const text = await file.text();
+		for (const line of text.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const entry = JSON.parse(line) as TranscriptEntry;
+
+				// Extract git branch from first occurrence
+				if (!meta.gitBranch && entry.gitBranch && entry.gitBranch !== "HEAD") {
+					meta.gitBranch = entry.gitBranch;
+				}
+
+				// Extract model from first assistant message
+				if (!meta.model && entry.message?.model) {
+					meta.model = entry.message.model;
+				}
+
+				// Accumulate token usage
+				const usage = entry.message?.usage;
+				if (usage) {
+					meta.totalInputTokens += usage.input_tokens ?? 0;
+					meta.totalOutputTokens += usage.output_tokens ?? 0;
+					meta.cacheCreationInputTokens += usage.cache_creation_input_tokens ?? 0;
+					meta.cacheReadInputTokens += usage.cache_read_input_tokens ?? 0;
+				}
+
+				// Count messages (user + assistant only)
+				if (entry.message?.role === "user" || entry.message?.role === "assistant") {
+					meta.messageCount++;
+				}
+			} catch {
+				// skip malformed
+			}
+		}
+	} catch {
+		// file unreadable
+	}
+
+	return meta;
+}
+
+async function peekCodexSession(
+	session: SessionInfo,
+	sessionsDir: string,
+): Promise<SessionMeta> {
+	const meta: SessionMeta = {
+		...session,
+		totalInputTokens: 0,
+		totalOutputTokens: 0,
+		cacheCreationInputTokens: 0,
+		cacheReadInputTokens: 0,
+		messageCount: 0,
+	};
+
+	const rolloutPath = await findRolloutFile(sessionsDir, session.sessionId);
+	if (!rolloutPath) return meta;
+
+	const file = Bun.file(rolloutPath);
+	if (!(await file.exists())) return meta;
+
+	try {
+		const text = await file.text();
+		for (const line of text.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const entry = JSON.parse(line) as any;
+
+				if (entry.type === "session_meta") {
+					const branch = entry.payload?.git?.branch;
+					if (!meta.gitBranch && typeof branch === "string" && branch !== "HEAD") {
+						meta.gitBranch = branch;
+					}
+				}
+
+				if (entry.type === "turn_context") {
+					const model = entry.payload?.model;
+					if (!meta.model && typeof model === "string") {
+						meta.model = model;
+					}
+				}
+
+				if (entry.type === "event_msg" && entry.payload?.type === "token_count") {
+					const usage = entry.payload?.info?.last_token_usage;
+					if (usage && typeof usage === "object") {
+						meta.totalInputTokens += Number(usage.input_tokens ?? 0);
+						meta.totalOutputTokens += Number(usage.output_tokens ?? 0);
+						meta.cacheReadInputTokens += Number(usage.cached_input_tokens ?? 0);
+					}
+				}
+
+				if (
+					entry.type === "response_item" &&
+					entry.payload?.type === "message" &&
+					(entry.payload?.role === "user" || entry.payload?.role === "assistant")
+				) {
+					meta.messageCount++;
+				}
+			} catch {
+				// skip malformed
+			}
+		}
+	} catch {
+		// file unreadable
+	}
+
+	return meta;
+}
+
+/**
+ * Stream transcript entries from a session JSONL file with privacy filtering.
+ */
+export async function* streamTranscript(
+	provider: Provider,
+	sessionId: string,
+	projectPath: string,
+	paths: { projectsDir: string; sessionsDir: string },
+	privacy: PrivacyConfig,
+): AsyncGenerator<TranscriptEntry> {
+	const normalized = canonicalProvider(provider);
+	if (normalized === "codex") {
+		yield* streamCodexTranscript(sessionId, paths.sessionsDir, privacy);
+		return;
+	}
+
+	yield* streamClaudeTranscript(sessionId, projectPath, paths.projectsDir, privacy);
+}
+
+async function* streamClaudeTranscript(
+	sessionId: string,
+	projectPath: string,
+	projectsDir: string,
+	privacy: PrivacyConfig,
+): AsyncGenerator<TranscriptEntry> {
+	const encoded = encodeProjectPath(projectPath);
+	const filePath = join(projectsDir, encoded, `${sessionId}.jsonl`);
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return;
+
+	const text = await file.text();
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const entry = JSON.parse(line) as TranscriptEntry;
+			const filtered = filterTranscriptEntry(entry, privacy);
+			if (filtered) yield filtered;
+		} catch {
+			// skip malformed
+		}
+	}
+}
+
+async function* streamCodexTranscript(
+	sessionId: string,
+	sessionsDir: string,
+	privacy: PrivacyConfig,
+): AsyncGenerator<TranscriptEntry> {
+	const rolloutPath = await findRolloutFile(sessionsDir, sessionId);
+	if (!rolloutPath) return;
+
+	const file = Bun.file(rolloutPath);
+	if (!(await file.exists())) return;
+
+	let currentModel: string | undefined;
+
+	const text = await file.text();
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		let raw: any;
+		try {
+			raw = JSON.parse(line);
+		} catch {
+			continue;
+		}
+
+		if (raw.type === "turn_context" && typeof raw.payload?.model === "string") {
+			currentModel = raw.payload.model;
+			continue;
+		}
+
+		let mapped: TranscriptEntry | null = null;
+
+		if (raw.type === "response_item" && raw.payload?.type === "message") {
+			const role = raw.payload.role;
+			if (role === "user" || role === "assistant") {
+				const textContent = parseCodexMessageText(raw.payload.content);
+				mapped = {
+					timestamp: raw.timestamp,
+					message: {
+						role,
+						model: currentModel,
+						content: textContent,
+					},
+				};
+			}
+		} else if (
+			raw.type === "response_item" &&
+			raw.payload?.type === "function_call" &&
+			typeof raw.payload?.name === "string"
+		) {
+			const args = parseCodexToolArguments(raw.payload.arguments);
+			const content: ContentBlock[] = [
+				{
+					type: "tool_use",
+					name: raw.payload.name,
+					input: args,
+				},
+			];
+			mapped = {
+				timestamp: raw.timestamp,
+				message: {
+					role: "assistant",
+					model: currentModel,
+					content,
+				},
+			};
+		} else if (
+			raw.type === "response_item" &&
+			raw.payload?.type === "function_call_output"
+		) {
+			mapped = {
+				timestamp: raw.timestamp,
+				toolUseResult: raw.payload?.output,
+			};
+		}
+
+		if (!mapped) continue;
+		const filtered = filterTranscriptEntry(mapped, privacy);
+		if (filtered) yield filtered;
+	}
+}

package/src/readers/skill-reader.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+/** List all skill names from provider/skills/ */
+export async function readSkills(skillsDir: string): Promise<string[]> {
+	const glob = new Bun.Glob("*/SKILL.md");
+	const skills: string[] = [];
+	try {
+		for await (const path of glob.scan({ cwd: skillsDir })) {
+			skills.push(path.split("/")[0]);
+		}
+	} catch {
+		// skills dir may not exist
+	}
+	return skills;
+}
+
+/** Read a specific skill's SKILL.md content. */
+export async function readSkillContent(
+	skillsDir: string,
+	name: string,
+): Promise<string> {
+	const filePath = join(skillsDir, name, "SKILL.md");
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) {
+		throw new Error(`Skill not found: ${name}`);
+	}
+	return file.text();
+}

package/src/readers/stats-reader.ts

@@ -0,0 +1,12 @@
+import type { StatsCache } from "../types/stats.js";
+
+/** Read the pre-computed stats cache from provider/stats-cache.json */
+export async function readStats(statsPath: string): Promise<StatsCache | null> {
+	const file = Bun.file(statsPath);
+	if (!(await file.exists())) return null;
+	try {
+		return (await file.json()) as StatsCache;
+	} catch {
+		return null;
+	}
+}

package/src/readers/task-reader.ts

@@ -0,0 +1,117 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { TaskInfo, TodoItem } from "../types/task.js";
+
+function isSameDate(fileDate: Date, targetDate: string): boolean {
+	const year = fileDate.getFullYear();
+	const month = String(fileDate.getMonth() + 1).padStart(2, "0");
+	const day = String(fileDate.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}` === targetDate;
+}
+
+function isInDateRange(fileDate: Date, from: string, to: string): boolean {
+	const year = fileDate.getFullYear();
+	const month = String(fileDate.getMonth() + 1).padStart(2, "0");
+	const day = String(fileDate.getDate()).padStart(2, "0");
+	const dateStr = `${year}-${month}-${day}`;
+	return dateStr >= from && dateStr <= to;
+}
+
+/** Read tasks from provider/tasks/{sessionDir}/*.json */
+export async function readTasks(
+	tasksDir: string,
+	from: string,
+	to: string,
+): Promise<TaskInfo[]> {
+	const tasks: TaskInfo[] = [];
+
+	let sessionDirs: string[];
+	try {
+		sessionDirs = await readdir(tasksDir);
+	} catch {
+		return tasks;
+	}
+
+	for (const sessionDir of sessionDirs) {
+		const dirPath = join(tasksDir, sessionDir);
+		const dirStat = await stat(dirPath).catch(() => null);
+		if (!dirStat?.isDirectory()) continue;
+
+		let files: string[];
+		try {
+			files = await readdir(dirPath);
+		} catch {
+			continue;
+		}
+
+		for (const file of files) {
+			if (!file.endsWith(".json")) continue;
+			const filePath = join(dirPath, file);
+
+			const fileStat = await stat(filePath).catch(() => null);
+			if (!fileStat || !isInDateRange(fileStat.mtime, from, to)) continue;
+
+			try {
+				const content = await Bun.file(filePath).json();
+				if (
+					content.subject &&
+					(content.status === "completed" || content.status === "in_progress")
+				) {
+					tasks.push({
+						id: content.id,
+						subject: content.subject,
+						description: content.description || "",
+						status: content.status,
+						sessionDir,
+						blocks: content.blocks,
+						blockedBy: content.blockedBy,
+					});
+				}
+			} catch {
+				// skip malformed
+			}
+		}
+	}
+
+	return tasks;
+}
+
+/** Read todos from provider/todos/*.json */
+export async function readTodos(
+	todosDir: string,
+	from: string,
+	to: string,
+): Promise<TodoItem[]> {
+	const todos: TodoItem[] = [];
+
+	let files: string[];
+	try {
+		files = await readdir(todosDir);
+	} catch {
+		return todos;
+	}
+
+	for (const file of files) {
+		if (!file.endsWith(".json")) continue;
+		const filePath = join(todosDir, file);
+
+		const fileStat = await stat(filePath).catch(() => null);
+		if (!fileStat || !isInDateRange(fileStat.mtime, from, to)) continue;
+
+		try {
+			const content = await Bun.file(filePath).json();
+			if (content.content) {
+				todos.push({
+					id: content.id || file.replace(".json", ""),
+					content: content.content,
+					status: content.status || "unknown",
+					sessionDir: content.sessionDir || "",
+				});
+			}
+		} catch {
+			// skip malformed
+		}
+	}
+
+	return todos;
+}

package/src/types/aggregations.ts

@@ -0,0 +1,47 @@
+import type { PlanInfo } from "./plan.js";
+import type { ProjectMemory } from "./project.js";
+import type { SessionDetail, SessionInfo, ToolCallSummary, ToolCategory } from "./session.js";
+import type { TaskInfo, TodoItem } from "./task.js";
+
+export interface DailySummary {
+	date: string;
+	sessions: SessionDetail[];
+	shortSessions: SessionInfo[];
+	tasks: TaskInfo[];
+	plans: PlanInfo[];
+	todos: TodoItem[];
+	totalPrompts: number;
+	totalSessions: number;
+	projects: string[];
+	projectMemory: Map<string, string>;
+}
+
+export interface ProjectSummary {
+	project: string;
+	projectName: string;
+	sessionCount: number;
+	promptCount: number;
+	estimatedHours: number;
+	branches: string[];
+	filesReferenced: string[];
+	toolCalls: ToolCallSummary[];
+	models: string[];
+}
+
+export interface ToolUsageReport {
+	byTool: Map<string, number>;
+	byCategory: Map<ToolCategory, number>;
+	topFiles: Array<{ path: string; count: number }>;
+	topCommands: Array<{ command: string; count: number }>;
+	total: number;
+}
+
+export interface DateFilter {
+	date?: string;
+	from?: string;
+	to?: string;
+}
+
+export interface SessionListFilter extends DateFilter {
+	project?: string;
+}

package/src/types/plan.ts

@@ -0,0 +1,6 @@
+export interface PlanInfo {
+	filename: string;
+	title: string;
+	snippet: string;
+	content?: string;
+}

package/src/types/privacy.ts

@@ -0,0 +1,18 @@
+export interface PrivacyConfig {
+	/** Replace user prompt text with [redacted] */
+	redactPrompts: boolean;
+	/** Strip absolute paths to relative */
+	redactAbsolutePaths: boolean;
+	/** Replace $HOME with ~ */
+	redactHomeDir: boolean;
+	/** Remove thinking blocks entirely */
+	stripThinking: boolean;
+	/** Skip toolUseResult content (DEFAULT: true) */
+	stripToolResults: boolean;
+	/** Custom regex patterns to redact (emails, API keys, etc.) */
+	redactPatterns: RegExp[];
+	/** Skip these projects entirely */
+	excludeProjects: string[];
+}
+
+export type PrivacyProfile = "local" | "shareable" | "strict";

package/src/types/project.ts

@@ -0,0 +1,13 @@
+export interface ProjectInfo {
+	encodedPath: string;
+	decodedPath: string;
+	name: string;
+	sessionCount: number;
+	hasMemory: boolean;
+}
+
+export interface ProjectMemory {
+	projectPath: string;
+	projectName: string;
+	content: string;
+}

package/src/types/provider.ts

@@ -0,0 +1,9 @@
+export const SUPPORTED_PROVIDERS = [
+	"claude",
+	"codex",
+	"openai",
+	"cursor",
+	"windsurf",
+] as const;
+
+export type Provider = (typeof SUPPORTED_PROVIDERS)[number];

package/src/types/session.ts

@@ -0,0 +1,56 @@
+/** One line from history.jsonl — a single user prompt. */
+export interface HistoryEntry {
+	display: string;
+	timestamp: number;
+	project: string;
+	sessionId: string;
+	pastedContents?: Record<string, unknown>;
+}
+
+/** Lightweight session info derived from history.jsonl grouping only. Fast — no file reads. */
+export interface SessionInfo {
+	sessionId: string;
+	project: string;
+	projectName: string;
+	prompts: string[];
+	promptTimestamps: number[];
+	timeRange: { start: number; end: number };
+}
+
+/** Session with metadata peeked from the session JSONL file (first+last lines). */
+export interface SessionMeta extends SessionInfo {
+	gitBranch?: string;
+	model?: string;
+	totalInputTokens: number;
+	totalOutputTokens: number;
+	cacheCreationInputTokens: number;
+	cacheReadInputTokens: number;
+	messageCount: number;
+}
+
+/** Full session detail from parsing the entire session JSONL file. */
+export interface SessionDetail extends SessionMeta {
+	assistantSummaries: string[];
+	toolCalls: ToolCallSummary[];
+	filesReferenced: string[];
+	planReferenced: boolean;
+	thinkingBlockCount: number;
+	hasSidechains: boolean;
+}
+
+export type ToolCategory =
+	| "file_read"
+	| "file_write"
+	| "shell"
+	| "search"
+	| "web"
+	| "task"
+	| "other";
+
+export interface ToolCallSummary {
+	name: string;
+	displayName: string;
+	category: ToolCategory;
+	/** e.g. file_path for Read/Write, command for Bash */
+	target?: string;
+}

package/src/types/stats.ts

@@ -0,0 +1,15 @@
+/** Pre-computed stats from provider/stats-cache.json */
+export interface StatsCache {
+	version: number;
+	lastComputedDate: string;
+	dailyActivity: Array<{
+		date: string;
+		messageCount: number;
+		sessionCount: number;
+		toolCallCount: number;
+	}>;
+	totalSessions: number;
+	totalMessages: number;
+	hourCounts: Record<string, number>;
+	modelUsage?: Record<string, number>;
+}

package/src/types/task.ts

@@ -0,0 +1,16 @@
+export interface TaskInfo {
+	id: string;
+	subject: string;
+	description: string;
+	status: string;
+	sessionDir: string;
+	blocks?: string[];
+	blockedBy?: string[];
+}
+
+export interface TodoItem {
+	id: string;
+	content: string;
+	status: string;
+	sessionDir: string;
+}

package/src/types/transcript.ts

@@ -0,0 +1,36 @@
+/** A single content block inside an assistant message. */
+export interface ContentBlock {
+	type: "text" | "thinking" | "tool_use" | "tool_result";
+	text?: string;
+	thinking?: string;
+	name?: string;
+	id?: string;
+	tool_use_id?: string;
+	input?: Record<string, unknown>;
+	content?: string | ContentBlock[];
+}
+
+/** Raw line from a session JSONL file. Union of all possible shapes. */
+export interface TranscriptEntry {
+	type?: "user" | "assistant" | "progress" | "file-history-snapshot";
+	message?: {
+		role?: "user" | "assistant";
+		content?: string | ContentBlock[];
+		model?: string;
+		usage?: {
+			input_tokens?: number;
+			output_tokens?: number;
+			cache_creation_input_tokens?: number;
+			cache_read_input_tokens?: number;
+		};
+	};
+	timestamp?: string;
+	gitBranch?: string;
+	planContent?: string;
+	cwd?: string;
+	sessionId?: string;
+	isSidechain?: boolean;
+	parentUuid?: string;
+	uuid?: string;
+	toolUseResult?: unknown;
+}