@nghyane/arcane 0.1.12 → 0.1.14

package/src/session/session-types.ts

@@ -0,0 +1,312 @@
+import type { Agent, AgentEvent, AgentMessage, AgentTool, ThinkingLevel } from "@nghyane/arcane-agent";
+import type { ImageContent, Model, TextContent, ToolChoice } from "@nghyane/arcane-ai";
+import type { Rule } from "../capability/rule";
+import type { ModelRegistry, ModelRole } from "../config/model-registry";
+import type { PromptTemplate } from "../config/prompt-templates";
+import type { Settings, SkillsSettings } from "../config/settings";
+import type { TtsrManager } from "../export/ttsr";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands";
+import type { ExtensionRunner } from "../extensibility/extensions";
+import type { Skill, SkillWarning } from "../extensibility/skills";
+import type { FileSlashCommand } from "../extensibility/slash-commands";
+import type { SecretObfuscator } from "../secrets/obfuscator";
+import type { TodoItem } from "../tools/todo-write";
+import type { CompactionResult } from "./compaction";
+import type { SessionManager } from "./session-manager";
+
+export const CURRENT_SESSION_VERSION = 3;
+
+export interface SessionHeader {
+	type: "session";
+	version?: number; // v1 sessions don't have this
+	id: string;
+	title?: string; // Auto-generated title from first message
+	timestamp: string;
+	cwd: string;
+	parentSession?: string;
+}
+
+export interface NewSessionOptions {
+	parentSession?: string;
+}
+
+export interface SessionEntryBase {
+	type: string;
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+}
+
+export interface SessionMessageEntry extends SessionEntryBase {
+	type: "message";
+	message: AgentMessage;
+}
+
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+	type: "thinking_level_change";
+	thinkingLevel: string;
+}
+
+export interface ModelChangeEntry extends SessionEntryBase {
+	type: "model_change";
+	/** Model in "provider/modelId" format */
+	model: string;
+	/** Role: "default", "fast", "oracle", etc. Undefined treated as "default" */
+	role?: string;
+}
+
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+	type: "compaction";
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+	details?: T;
+	/** Hook-provided data to persist across compaction */
+	preserveData?: Record<string, unknown>;
+	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
+	fromExtension?: boolean;
+}
+
+export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
+	type: "branch_summary";
+	fromId: string;
+	summary: string;
+	/** Extension-specific data (not sent to LLM) */
+	details?: T;
+	/** True if generated by an extension, false if pi-generated */
+	fromExtension?: boolean;
+}
+
+/**
+ * Custom entry for extensions to store extension-specific data in the session.
+ * Use customType to identify your extension's entries.
+ *
+ * Purpose: Persist extension state across session reloads. On reload, extensions can
+ * scan entries for their customType and reconstruct internal state.
+ *
+ * Does NOT participate in LLM context (ignored by buildSessionContext).
+ * For injecting content into context, see CustomMessageEntry.
+ */
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+	type: "custom";
+	customType: string;
+	data?: T;
+}
+
+/** Label entry for user-defined bookmarks/markers on entries. */
+export interface LabelEntry extends SessionEntryBase {
+	type: "label";
+	targetId: string;
+	label: string | undefined;
+}
+
+/** TTSR injection entry - tracks which time-traveling rules have been injected this session. */
+export interface TtsrInjectionEntry extends SessionEntryBase {
+	type: "ttsr_injection";
+	/** Names of rules that were injected */
+	injectedRules: string[];
+}
+
+/** Session init entry - captures initial context for subagent sessions (debugging/replay). */
+export interface SessionInitEntry extends SessionEntryBase {
+	type: "session_init";
+	/** Full system prompt sent to the model */
+	systemPrompt: string;
+	/** Initial task/user message */
+	task: string;
+	/** Tools available to the agent */
+	tools: string[];
+}
+
+/** Mode change entry - tracks agent mode transitions. */
+export interface ModeChangeEntry extends SessionEntryBase {
+	type: "mode_change";
+	/** Current mode name, or "none" when exiting a mode */
+	mode: string;
+	/** Optional mode-specific data (e.g. plan file path) */
+	data?: Record<string, unknown>;
+}
+
+/**
+ * Custom message entry for extensions to inject messages into LLM context.
+ * Use customType to identify your extension's entries.
+ *
+ * Unlike CustomEntry, this DOES participate in LLM context.
+ * The content is converted to a user message in buildSessionContext().
+ * Use details for extension-specific metadata (not sent to LLM).
+ *
+ * display controls TUI rendering:
+ * - false: hidden entirely
+ * - true: rendered with distinct styling (different from user messages)
+ */
+export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
+	type: "custom_message";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	details?: T;
+	display: boolean;
+}
+
+/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
+export type SessionEntry =
+	| SessionMessageEntry
+	| ThinkingLevelChangeEntry
+	| ModelChangeEntry
+	| CompactionEntry
+	| BranchSummaryEntry
+	| CustomEntry
+	| CustomMessageEntry
+	| LabelEntry
+	| TtsrInjectionEntry
+	| SessionInitEntry
+	| ModeChangeEntry;
+
+/** Raw file entry (includes header) */
+export type FileEntry = SessionHeader | SessionEntry;
+
+/** Tree node for getTree() - defensive copy of session structure */
+export interface SessionTreeNode {
+	entry: SessionEntry;
+	children: SessionTreeNode[];
+	/** Resolved label for this entry, if any */
+	label?: string;
+}
+
+export interface SessionContext {
+	messages: AgentMessage[];
+	thinkingLevel: string;
+	/** Model roles: { default: "provider/modelId", small: "provider/modelId", ... } */
+	models: Record<string, string>;
+	/** Names of TTSR rules that have been injected this session */
+	injectedTtsrRules: string[];
+	/** Active mode (e.g. "plan") or "none" if no special mode is active */
+	mode: string;
+	/** Mode-specific data from the last mode_change entry */
+	modeData?: Record<string, unknown>;
+}
+
+export interface SessionInfo {
+	path: string;
+	id: string;
+	/** Working directory where the session was started. Empty string for old sessions. */
+	cwd: string;
+	title?: string;
+	/** Path to the parent session (if this session was forked). */
+	parentSessionPath?: string;
+	created: Date;
+	modified: Date;
+	messageCount: number;
+	firstMessage: string;
+	allMessagesText: string;
+}
+
+// ============================================================================
+// Agent Session Types (moved from agent-session.ts)
+// ============================================================================
+
+/** Session-specific events that extend the core AgentEvent */
+export type AgentSessionEvent =
+	| AgentEvent
+	| { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
+	| {
+			type: "auto_compaction_end";
+			result: CompactionResult | undefined;
+			aborted: boolean;
+			willRetry: boolean;
+			errorMessage?: string;
+	  }
+	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+	| { type: "ttsr_triggered"; rules: Rule[] }
+	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number };
+
+/** Listener function for agent session events */
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+
+export interface AgentSessionConfig {
+	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
+	/** Models to cycle through with Ctrl+P (from --models flag) */
+	scopedModels?: Array<{ model: Model; thinkingLevel: ThinkingLevel }>;
+	/** Prompt templates for expansion */
+	promptTemplates?: PromptTemplate[];
+	/** File-based slash commands for expansion */
+	slashCommands?: FileSlashCommand[];
+	/** Extension runner (created in main.ts with wrapped tools) */
+	extensionRunner?: ExtensionRunner;
+	/** Loaded skills (already discovered by SDK) */
+	skills?: Skill[];
+	/** Skill loading warnings (already captured by SDK) */
+	skillWarnings?: SkillWarning[];
+	/** Custom commands (TypeScript slash commands) */
+	customCommands?: LoadedCustomCommand[];
+	skillsSettings?: Required<SkillsSettings>;
+	/** Model registry for API key resolution and model discovery */
+	modelRegistry: ModelRegistry;
+	/** Tool registry for LSP and settings */
+	toolRegistry?: Map<string, AgentTool>;
+	/** System prompt builder that can consider tool availability */
+	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>;
+	/** TTSR manager for time-traveling stream rules */
+	ttsrManager?: TtsrManager;
+	/** Force X-Initiator: agent for GitHub Copilot model selections in this session. */
+	forceCopilotAgentInitiator?: boolean;
+	/** Secret obfuscator for deobfuscating streaming edit content */
+	obfuscator?: SecretObfuscator;
+}
+
+/** Options for AgentSession.prompt() */
+export interface PromptOptions {
+	/** Whether to expand file-based prompt templates (default: true) */
+	expandPromptTemplates?: boolean;
+	/** Image attachments */
+	images?: ImageContent[];
+	/** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). */
+	streamingBehavior?: "steer" | "followUp";
+	/** Optional tool choice override for the next LLM call. */
+	toolChoice?: ToolChoice;
+	/** Mark the user message as synthetic (system-injected). */
+	synthetic?: boolean;
+}
+
+/** Result from cycleModel() */
+export interface ModelCycleResult {
+	model: Model;
+	thinkingLevel: ThinkingLevel;
+	/** Whether cycling through scoped models (--models flag) or all available */
+	isScoped: boolean;
+}
+
+/** Result from cycleRoleModels() */
+export interface RoleModelCycleResult {
+	model: Model;
+	thinkingLevel: ThinkingLevel;
+	role: ModelRole;
+}
+
+/** Session statistics for /session command */
+export interface SessionStats {
+	sessionFile: string | undefined;
+	sessionId: string;
+	userMessages: number;
+	assistantMessages: number;
+	toolCalls: number;
+	toolResults: number;
+	totalMessages: number;
+	tokens: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		total: number;
+	};
+	cost: number;
+}
+
+/** Result from handoff() */
+export interface HandoffResult {
+	document: string;
+}

package/src/session/stats.ts

@@ -0,0 +1,387 @@
+import type { AgentMessage, AgentState } from "@nghyane/arcane-agent";
+import type { AssistantMessage, Model, Usage, UsageReport } from "@nghyane/arcane-ai";
+import type { ModelRegistry } from "../config/model-registry";
+import { exportSessionToHtml } from "../export/html";
+import type { ContextUsage } from "../extensibility/extensions/types";
+import { getCurrentThemeName } from "../theme/theme";
+import { calculateContextTokens, estimateTokens } from "./compaction";
+import type { CompactionSummaryMessage, FileMentionMessage } from "./messages";
+import type { SessionManager } from "./session-manager";
+import { getLatestCompactionEntry } from "./session-manager";
+import type { SessionStats } from "./session-types";
+
+/**
+ * Compute session statistics from messages.
+ */
+export function getSessionStats(
+	messages: AgentMessage[],
+	sessionFile: string | undefined,
+	sessionId: string,
+): SessionStats {
+	const userMessages = messages.filter(m => m.role === "user").length;
+	const assistantMessages = messages.filter(m => m.role === "assistant").length;
+	const toolResults = messages.filter(m => m.role === "toolResult").length;
+
+	let toolCalls = 0;
+	let totalInput = 0;
+	let totalOutput = 0;
+	let totalCacheRead = 0;
+	let totalCacheWrite = 0;
+	let totalCost = 0;
+
+	const getTaskToolUsage = (details: unknown): Usage | undefined => {
+		if (!details || typeof details !== "object") return undefined;
+		const record = details as Record<string, unknown>;
+		const usage = record.usage;
+		if (!usage || typeof usage !== "object") return undefined;
+		return usage as Usage;
+	};
+
+	for (const message of messages) {
+		if (message.role === "assistant") {
+			const assistantMsg = message as AssistantMessage;
+			toolCalls += assistantMsg.content.filter(c => c.type === "toolCall").length;
+			totalInput += assistantMsg.usage.input;
+			totalOutput += assistantMsg.usage.output;
+			totalCacheRead += assistantMsg.usage.cacheRead;
+			totalCacheWrite += assistantMsg.usage.cacheWrite;
+			totalCost += assistantMsg.usage.cost.total;
+		}
+
+		if (message.role === "toolResult" && message.toolName === "task") {
+			const usage = getTaskToolUsage(message.details);
+			if (usage) {
+				totalInput += usage.input;
+				totalOutput += usage.output;
+				totalCacheRead += usage.cacheRead;
+				totalCacheWrite += usage.cacheWrite;
+				totalCost += usage.cost.total;
+			}
+		}
+	}
+
+	return {
+		sessionFile,
+		sessionId,
+		userMessages,
+		assistantMessages,
+		toolCalls,
+		toolResults,
+		totalMessages: messages.length,
+		tokens: {
+			input: totalInput,
+			output: totalOutput,
+			cacheRead: totalCacheRead,
+			cacheWrite: totalCacheWrite,
+			total: totalInput + totalOutput + totalCacheRead + totalCacheWrite,
+		},
+		cost: totalCost,
+	};
+}
+
+/**
+ * Get current context usage statistics.
+ */
+export function getContextUsage(
+	model: Model | undefined,
+	messages: AgentMessage[],
+	sessionManager: SessionManager,
+): ContextUsage | undefined {
+	if (!model) return undefined;
+
+	const contextWindow = model.contextWindow ?? 0;
+	if (contextWindow <= 0) return undefined;
+
+	const branchEntries = sessionManager.getBranch();
+	const latestCompaction = getLatestCompactionEntry(branchEntries);
+
+	if (latestCompaction) {
+		const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
+		let hasPostCompactionUsage = false;
+		for (let i = compactionIndex + 1; i < branchEntries.length; i++) {
+			const entry = branchEntries[i];
+			if (entry.type === "message" && entry.message.role === "assistant") {
+				const msg = entry.message as AssistantMessage;
+				if (msg.usage) {
+					hasPostCompactionUsage = true;
+					break;
+				}
+			}
+		}
+
+		if (!hasPostCompactionUsage) {
+			return {
+				tokens: 0,
+				contextWindow,
+				percent: 0,
+			};
+		}
+	}
+
+	const { tokens } = estimateContextTokensFromMessages(messages);
+	const percent = Math.round((tokens / contextWindow) * 100);
+
+	return {
+		tokens,
+		contextWindow,
+		percent,
+	};
+}
+
+/**
+ * Estimate context tokens from messages, using the last assistant usage when available.
+ */
+export function estimateContextTokensFromMessages(messages: AgentMessage[]): { tokens: number } {
+	let lastUsageIndex: number | null = null;
+	let lastUsage: Usage | undefined;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			if (assistantMsg.usage) {
+				lastUsage = assistantMsg.usage;
+				lastUsageIndex = i;
+				break;
+			}
+		}
+	}
+
+	if (!lastUsage || lastUsageIndex === null) {
+		let estimated = 0;
+		for (const message of messages) {
+			estimated += estimateTokens(message);
+		}
+		return { tokens: estimated };
+	}
+
+	const usageTokens = calculateContextTokens(lastUsage);
+	let trailingTokens = 0;
+	for (let i = lastUsageIndex + 1; i < messages.length; i++) {
+		trailingTokens += estimateTokens(messages[i]);
+	}
+
+	return { tokens: usageTokens + trailingTokens };
+}
+
+/**
+ * Fetch usage reports from the auth storage.
+ */
+export function fetchUsageReports(modelRegistry: ModelRegistry): Promise<UsageReport[] | null> | null {
+	const authStorage = modelRegistry.authStorage;
+	if (!authStorage.fetchUsageReports) return null;
+	return authStorage.fetchUsageReports({
+		baseUrlResolver: provider => modelRegistry.getProviderBaseUrl?.(provider),
+	});
+}
+
+/**
+ * Export session to HTML.
+ */
+export async function exportToHtml(
+	sessionManager: SessionManager,
+	state: AgentState,
+	outputPath?: string,
+): Promise<string> {
+	const themeName = getCurrentThemeName();
+	return exportSessionToHtml(sessionManager, state, { outputPath, themeName });
+}
+
+/**
+ * Get text content of last assistant message.
+ */
+export function getLastAssistantText(messages: AgentMessage[]): string | undefined {
+	const lastAssistant = messages
+		.slice()
+		.reverse()
+		.find(m => {
+			if (m.role !== "assistant") return false;
+			const msg = m as AssistantMessage;
+			if (msg.stopReason === "aborted" && msg.content.length === 0) return false;
+			return true;
+		});
+
+	if (!lastAssistant) return undefined;
+
+	let text = "";
+	for (const content of (lastAssistant as AssistantMessage).content) {
+		if (content.type === "text") {
+			text += content.text;
+		}
+	}
+
+	return text.trim() || undefined;
+}
+
+/**
+ * Format the entire session as plain text for clipboard export.
+ */
+export function formatSessionAsText(state: AgentState): string {
+	const lines: string[] = [];
+
+	function formatArgsAsXml(args: Record<string, unknown>, indent = "\t"): string {
+		const parts: string[] = [];
+		for (const [key, value] of Object.entries(args)) {
+			const text = typeof value === "string" ? value : JSON.stringify(value);
+			parts.push(`${indent}<parameter name="${key}">${text}</parameter>`);
+		}
+		return parts.join("\n");
+	}
+
+	const systemPrompt = state.systemPrompt;
+	if (systemPrompt) {
+		lines.push("## System Prompt\n");
+		lines.push(systemPrompt);
+		lines.push("\n");
+	}
+
+	const model = state.model;
+	const thinkingLevel = state.thinkingLevel;
+	lines.push("## Configuration\n");
+	lines.push(`Model: ${model.provider}/${model.id}`);
+	lines.push(`Thinking Level: ${thinkingLevel}`);
+	lines.push("\n");
+
+	const tools = state.tools;
+
+	// Recursively strip all fields starting with 'TypeBox.' from an object
+	function stripTypeBoxFields(obj: unknown): unknown {
+		if (Array.isArray(obj)) {
+			return obj.map(stripTypeBoxFields);
+		}
+		if (obj && typeof obj === "object") {
+			const result: Record<string, unknown> = {};
+			for (const [k, v] of Object.entries(obj)) {
+				if (!k.startsWith("TypeBox.")) {
+					result[k] = stripTypeBoxFields(v);
+				}
+			}
+			return result;
+		}
+		return obj;
+	}
+
+	if (tools.length > 0) {
+		lines.push("## Available Tools\n");
+		for (const tool of tools) {
+			lines.push(`<tool name="${tool.name}">`);
+			lines.push(tool.description);
+			const parametersClean = stripTypeBoxFields(tool.parameters);
+			lines.push(`\nParameters:\n${formatArgsAsXml(parametersClean as Record<string, unknown>)}`);
+			lines.push("<" + "/tool>\n");
+		}
+		lines.push("\n");
+	}
+
+	for (const msg of state.messages) {
+		if (msg.role === "user") {
+			lines.push("## User\n");
+			if (typeof msg.content === "string") {
+				lines.push(msg.content);
+			} else {
+				for (const c of msg.content) {
+					if (c.type === "text") {
+						lines.push(c.text);
+					} else if (c.type === "image") {
+						lines.push("[Image]");
+					}
+				}
+			}
+			lines.push("\n");
+		} else if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			lines.push("## Assistant\n");
+
+			for (const c of assistantMsg.content) {
+				if (c.type === "text") {
+					lines.push(c.text);
+				} else if (c.type === "thinking") {
+					lines.push("<thinking>");
+					lines.push(c.thinking);
+					lines.push("</thinking>\n");
+				} else if (c.type === "toolCall") {
+					lines.push(`<tool_call name="${c.name}" id="${c.id}">`);
+					if (c.arguments && typeof c.arguments === "object") {
+						lines.push(formatArgsAsXml(c.arguments as Record<string, unknown>));
+					}
+					lines.push("<" + "/tool_call>\n");
+				}
+			}
+			lines.push("\n");
+		} else if (msg.role === "toolResult") {
+			lines.push(`## Tool Result [${msg.toolName}] (id: ${msg.toolCallId})\n`);
+			if (typeof msg.content === "string") {
+				lines.push(msg.content);
+			} else if (Array.isArray(msg.content)) {
+				for (const c of msg.content) {
+					if (c.type === "text") {
+						lines.push(c.text);
+					} else if (c.type === "image") {
+						lines.push("[Image]");
+					}
+				}
+			}
+			lines.push("\n");
+		}
+	}
+
+	return lines.join("\n").trim();
+}
+
+/**
+ * Format the conversation as compact context for subagents.
+ */
+export function formatCompactContext(messages: AgentMessage[]): string {
+	const lines: string[] = [];
+	lines.push("# Conversation Context");
+	lines.push("");
+	lines.push(
+		"This is a summary of the parent conversation. Read this if you need additional context about what was discussed or decided.",
+	);
+	lines.push("");
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			lines.push("## User");
+			lines.push("");
+			if (typeof msg.content === "string") {
+				lines.push(msg.content);
+			} else {
+				for (const c of msg.content) {
+					if (c.type === "text") {
+						lines.push(c.text);
+					} else if (c.type === "image") {
+						lines.push("[Image attached]");
+					}
+				}
+			}
+			lines.push("");
+		} else if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			const textParts: string[] = [];
+			for (const c of assistantMsg.content) {
+				if (c.type === "text" && c.text.trim()) {
+					textParts.push(c.text);
+				}
+			}
+			if (textParts.length > 0) {
+				lines.push("## Assistant");
+				lines.push("");
+				lines.push(textParts.join("\n\n"));
+				lines.push("");
+			}
+		} else if (msg.role === "fileMention") {
+			const fileMsg = msg as FileMentionMessage;
+			const paths = fileMsg.files.map(f => f.path).join(", ");
+			lines.push(`[Files referenced: ${paths}]`);
+			lines.push("");
+		} else if (msg.role === "compactionSummary") {
+			const compactMsg = msg as CompactionSummaryMessage;
+			lines.push("## Earlier Context (Summarized)");
+			lines.push("");
+			lines.push(compactMsg.summary);
+			lines.push("");
+		}
+	}
+
+	return lines.join("\n").trim();
+}