@sns-myagent/cli 0.2.0 → 0.3.0

package/src/tbm/dashboard.ts

@@ -0,0 +1,131 @@
+/**
+ * Token Dashboard — `/tokens` command implementation.
+ *
+ * Shows session stats: duration, tokens, cost, cache hit rate,
+ * pyramid level, communication mode, compression stats.
+ */
+
+import type { TbmManager } from "./index";
+
+export interface DashboardData {
+	sessionDuration: string;
+	totalInputTokens: number;
+	totalOutputTokens: number;
+	cachedTokens: number;
+	estimatedCost: string;
+	cacheHitRate: string;
+	pyramidLevel: number;
+	pyramidLabel: string;
+	commMode: string;
+	compressionRatio: string;
+	tokensSaved: string;
+	tombstonesActive: number;
+	responseCacheSize: number;
+	skillsLoaded: string;
+}
+
+/**
+ * Format a number with K/M suffix.
+ */
+function formatNumber(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+/**
+ * Format duration from milliseconds.
+ */
+function formatDuration(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	const secs = seconds % 60;
+	if (minutes < 60) return `${minutes}m ${secs}s`;
+	const hours = Math.floor(minutes / 60);
+	const mins = minutes % 60;
+	return `${hours}h ${mins}m`;
+}
+
+/**
+ * Estimate cost from token counts.
+ * Rough estimate: $3/1M input, $15/1M output (Claude Sonnet class).
+ */
+function estimateCost(inputTokens: number, outputTokens: number): string {
+	const inputCost = (inputTokens / 1_000_000) * 3;
+	const outputCost = (outputTokens / 1_000_000) * 15;
+	const total = inputCost + outputCost;
+	if (total < 0.01) return "<$0.01";
+	return `$${total.toFixed(3)}`;
+}
+
+/**
+ * Build dashboard data from TBM manager state.
+ */
+export function buildDashboard(mgr: TbmManager, sessionStartTime: number): DashboardData {
+	const deltaStats = mgr.contextDelta.stats;
+	const pyramidStats = mgr.pyramid.stats;
+	const compressStats = mgr.compressor.stats;
+	const cacheStats = mgr.responseCache.stats;
+	const tombstoneStats = mgr.tombstoner.stats;
+	const skillStats = mgr.lazySkills.stats;
+
+	const totalSaved = deltaStats.tokens_saved
+		+ compressStats.tokensSaved
+		+ tombstoneStats.tokensSaved
+		+ cacheStats.tokensSaved
+		+ skillStats.tokensSaved;
+
+	return {
+		sessionDuration: formatDuration(Date.now() - sessionStartTime),
+		totalInputTokens: deltaStats.total_input_tokens,
+		totalOutputTokens: 0, // tracked by provider
+		cachedTokens: deltaStats.tokens_saved,
+		estimatedCost: estimateCost(deltaStats.total_input_tokens, 0),
+		cacheHitRate: `${(deltaStats.cache_hits / Math.max(1, deltaStats.turns) * 100).toFixed(0)}%`,
+		pyramidLevel: pyramidStats.currentLevel,
+		pyramidLabel: pyramidStats.currentLevel.toString(),
+		commMode: mgr.commMode.effective,
+		compressionRatio: `${(compressStats.totalOutputs > 0 ? (compressStats.compressed / compressStats.totalOutputs * 100) : 0).toFixed(0)}%`,
+		tokensSaved: formatNumber(totalSaved),
+		tombstonesActive: tombstoneStats.messagesTombstoned,
+		responseCacheSize: cacheStats.cacheSize,
+		skillsLoaded: `${skillStats.loadedOnDemand}/${skillStats.totalAvailable}`,
+	};
+}
+
+/**
+ * Render dashboard as formatted text for display.
+ */
+export function renderDashboard(data: DashboardData): string {
+	return `╔══════════════════════════════════════╗
+║       🧠 Token Budget Manager       ║
+╠══════════════════════════════════════╣
+║ Session     ${data.sessionDuration.padEnd(25)}║
+║ Input       ${String(data.totalInputTokens).padEnd(25)}║
+║ Cached      ${String(data.cachedTokens).padEnd(25)}║
+║ Est. Cost   ${data.estimatedCost.padEnd(25)}║
+╠══════════════════════════════════════╣
+║ 📊 Context Delta                    ║
+║ Cache Hit   ${data.cacheHitRate.padEnd(25)}║
+╠══════════════════════════════════════╣
+║ 🔺 Pyramid                          ║
+║ Level       ${String(data.pyramidLevel).padEnd(25)}║
+╠══════════════════════════════════════╣
+║ 💬 Mode       ${data.commMode.padEnd(23)}║
+╠══════════════════════════════════════╣
+║ 🗜️  Compression ${data.compressionRatio.padEnd(22)}║
+║ 💾 Saved      ${data.tokensSaved.padEnd(23)}║
+╠══════════════════════════════════════╣
+║ 🗂  Tombstones ${String(data.tombstonesActive).padEnd(23)}║
+║ 📦 Cache Size ${String(data.responseCacheSize).padEnd(23)}║
+║ 🎯 Skills     ${data.skillsLoaded.padEnd(23)}║
+╚══════════════════════════════════════╝`;
+}
+
+/**
+ * Render dashboard as compact one-liner for status bar.
+ */
+export function renderCompactDashboard(data: DashboardData): string {
+	return `🧠 TBM | L${data.pyramidLevel} ${data.commMode} | Δ${data.cacheHitRate} | 🗜${data.compressionRatio} | 💾${data.tokensSaved}`;
+}

package/src/tbm/index.ts

@@ -0,0 +1,247 @@
+/**
+ * TBM Manager — coordinates all Token Budget Manager subsystems.
+ *
+ * Single entry point for the session/agent loop to interact with TBM.
+ * Each subsystem is independently toggleable via config.
+ *
+ * Usage:
+ *   const mgr = new TbmManager(config);
+ *   const ctx = mgr.processTurn(message, fullContext);
+ *   // use ctx.content, ctx.directive, etc.
+ */
+
+import { type TbmConfig, DEFAULT_TBM_CONFIG, resolveTbmConfig } from "./config";
+import { ContextDeltaCache, estimateTokens } from "./context-delta";
+import { ContextPyramid, type PyramidLevel } from "./context-pyramid";
+import { LazySkillLoader, type SkillEntry } from "./lazy-skills";
+import { ToolOutputCompressor } from "./tool-compress";
+import { CommunicationModeManager, type CommMode } from "./comm-modes";
+import { ConversationTombstoner } from "./tombstone";
+import { ResponseCache } from "./response-cache";
+import { buildDashboard, renderDashboard, renderCompactDashboard, type DashboardData } from "./dashboard";
+
+export type { TbmConfig } from "./config";
+export type { ContextDeltaStats } from "./context-delta";
+export type { PyramidLevel, PyramidStats } from "./context-pyramid";
+export type { SkillEntry, LazySkillStats } from "./lazy-skills";
+export type { CompressStats } from "./tool-compress";
+export type { CommMode } from "./comm-modes";
+export type { TombstoneStats } from "./tombstone";
+export type { ResponseCacheStats } from "./response-cache";
+export type { DashboardData } from "./dashboard";
+
+export interface TurnResult {
+	/** Content to send (possibly delta-compressed). */
+	content: string;
+	/** Communication mode directive to inject into system prompt. */
+	directive: string;
+	/** Current pyramid level. */
+	pyramidLevel: PyramidLevel;
+	/** Tokens saved this turn across all subsystems. */
+	tokensSavedThisTurn: number;
+	/** Whether context delta cache hit. */
+	deltaCacheHit: boolean;
+}
+
+export class TbmManager {
+	readonly #config: TbmConfig;
+	readonly #contextDelta: ContextDeltaCache;
+	readonly #pyramid: ContextPyramid;
+	readonly #lazySkills: LazySkillLoader;
+	readonly #compressor: ToolOutputCompressor;
+	readonly #commMode: CommunicationModeManager;
+	readonly #tombstoner: ConversationTombstoner;
+	readonly #responseCache: ResponseCache;
+	readonly #sessionStartTime: number;
+
+	constructor(config?: Partial<TbmConfig>) {
+		this.#config = resolveTbmConfig(config);
+		this.#contextDelta = new ContextDeltaCache();
+		this.#pyramid = new ContextPyramid(
+			this.#config.pyramid.start_level as PyramidLevel,
+			this.#config.pyramid.max_level as PyramidLevel,
+		);
+		this.#lazySkills = new LazySkillLoader();
+		this.#compressor = new ToolOutputCompressor(this.#config.compress.budgets);
+		this.#commMode = new CommunicationModeManager(this.#config.comm_mode);
+		this.#tombstoner = new ConversationTombstoner(
+			this.#config.tombstone.after_turns,
+			this.#config.tombstone.keep_recent,
+		);
+		this.#responseCache = new ResponseCache(
+			this.#config.response_cache.ttl_seconds,
+			this.#config.response_cache.max_entries,
+			this.#config.response_cache.similarity_threshold,
+		);
+		this.#sessionStartTime = Date.now();
+	}
+
+	/** Whether TBM is enabled. */
+	get enabled(): boolean {
+		return this.#config.enabled;
+	}
+
+	/** Access subsystems directly. */
+	get contextDelta(): ContextDeltaCache { return this.#contextDelta; }
+	get pyramid(): ContextPyramid { return this.#pyramid; }
+	get lazySkills(): LazySkillLoader { return this.#lazySkills; }
+	get compressor(): ToolOutputCompressor { return this.#compressor; }
+	get commMode(): CommunicationModeManager { return this.#commMode; }
+	get tombstoner(): ConversationTombstoner { return this.#tombstoner; }
+	get responseCache(): ResponseCache { return this.#responseCache; }
+	get config(): Readonly<TbmConfig> { return this.#config; }
+
+	/**
+	 * Process a new user turn — main entry point for the session loop.
+	 *
+	 * 1. Check response cache
+	 * 2. Resolve communication mode
+	 * 3. Determine pyramid level
+	 * 4. Process context delta
+	 * 5. Load relevant skills (lazy)
+	 */
+	processTurn(message: string, fullContext: string): TurnResult {
+		if (!this.#config.enabled) {
+			return {
+				content: fullContext,
+				directive: "",
+				pyramidLevel: 4 as PyramidLevel,
+				tokensSavedThisTurn: 0,
+				deltaCacheHit: false,
+			};
+		}
+
+		let totalSaved = 0;
+
+		// 1. Response cache check
+		const cached = this.#responseCache.get(message);
+		if (cached.hit && cached.response) {
+			return {
+				content: cached.response,
+				directive: `[Cache ${cached.matchType} hit]`,
+				pyramidLevel: this.#pyramid.level,
+				tokensSavedThisTurn: estimateTokens(cached.response),
+				deltaCacheHit: true,
+			};
+		}
+
+		// 2. Communication mode
+		const { directive } = this.#commMode.resolveForMessage(message);
+
+		// 3. Pyramid level
+		if (this.#config.pyramid.enabled) {
+			const level = this.#pyramid.resolveLevel(message);
+			this.#pyramid.setLevel(level);
+		}
+
+		// 4. Context delta
+		let content = fullContext;
+		let deltaCacheHit = false;
+		if (this.#config.context_delta.enabled) {
+			const delta = this.#contextDelta.processTurn(fullContext);
+			content = delta.content;
+			totalSaved += delta.tokensSaved;
+			deltaCacheHit = !delta.staticChanged;
+		}
+
+		// 5. Lazy skills
+		if (this.#config.lazy_skills.enabled) {
+			const { skillsToLoad, indexSection } = this.#lazySkills.processMessage(
+				message,
+				this.#config.lazy_skills.max_per_turn,
+			);
+			if (skillsToLoad.length > 0) {
+				content += "\n\n## Loaded Skills\n\n" + skillsToLoad.map((s) => s.fullContent).join("\n\n---\n\n");
+			}
+		}
+
+		return {
+			content,
+			directive,
+			pyramidLevel: this.#pyramid.level,
+			tokensSavedThisTurn: totalSaved,
+			deltaCacheHit,
+		};
+	}
+
+	/**
+	 * Compress tool output before adding to context.
+	 */
+	compressToolOutput(toolName: string, output: string): { output: string; compressed: boolean; tokensSaved: number } {
+		if (!this.#config.compress.enabled) {
+			return { output, compressed: false, tokensSaved: 0 };
+		}
+		return this.#compressor.compress(toolName, output);
+	}
+
+	/**
+	 * Cache a response for future exact/semantic match.
+	 */
+	cacheResponse(query: string, response: string): void {
+		if (this.#config.response_cache.enabled) {
+			this.#responseCache.set(query, response);
+		}
+	}
+
+	/**
+	 * Tombstone old conversation messages.
+	 */
+	tombstoneMessages(messages: Array<{ role: "user" | "assistant"; content: string }>): {
+		compressed: Array<{ role: "user" | "assistant"; content: string }>;
+		tombstoned: number;
+		tokensSaved: number;
+	} {
+		if (!this.#config.tombstone.enabled) {
+			return { compressed: messages, tombstoned: 0, tokensSaved: 0 };
+		}
+		return this.#tombstoner.tombstone(messages);
+	}
+
+	/**
+	 * Register skills for lazy loading.
+	 */
+	registerSkills(skills: SkillEntry[]): void {
+		this.#lazySkills.registerSkills(skills);
+	}
+
+	/**
+	 * Set communication mode explicitly.
+	 */
+	setMode(mode: CommMode | "auto"): void {
+		this.#commMode.setMode(mode);
+	}
+
+	/**
+	 * Build and render the token dashboard.
+	 */
+	getDashboard(): DashboardData {
+		return buildDashboard(this, this.#sessionStartTime);
+	}
+
+	/**
+	 * Render the dashboard as formatted text.
+	 */
+	renderDashboard(): string {
+		return renderDashboard(this.getDashboard());
+	}
+
+	/**
+	 * Render the dashboard as a compact one-liner.
+	 */
+	renderCompactDashboard(): string {
+		return renderCompactDashboard(this.getDashboard());
+	}
+
+	/**
+	 * Reset all subsystems (e.g. on session reset).
+	 */
+	reset(): void {
+		this.#contextDelta.reset();
+		this.#pyramid.reset();
+		this.#lazySkills.reset();
+		this.#compressor.reset();
+		this.#commMode.reset();
+		this.#tombstoner.reset();
+		this.#responseCache.reset();
+	}
+}

package/src/tbm/lazy-skills.ts

@@ -0,0 +1,182 @@
+/**
+ * Lazy Skill Loading — inject skill names only, load full content on-demand.
+ *
+ * Instead of loading all skills into context (~50,000+ tokens),
+ * inject only skill names (~200 tokens) and load full content
+ * when the model explicitly references a skill.
+ *
+ * Target: ~700 tokens vs 50,000+ if all loaded.
+ */
+
+export interface SkillEntry {
+	/** Skill name (kebab-case). */
+	name: string;
+	/** Short description for name-only injection. */
+	description: string;
+	/** Full content — only loaded on-demand. */
+	fullContent: string;
+	/** Approximate token count of full content. */
+	tokens: number;
+	/** Category for grouping. */
+	category?: string;
+}
+
+export interface LazySkillStats {
+	/** Total skills available. */
+	totalAvailable: number;
+	/** Skills injected as names only. */
+	namesInjected: number;
+	/** Skills fully loaded this session. */
+	loadedOnDemand: number;
+	/** Tokens saved by not loading all skills. */
+	tokensSaved: number;
+	/** Names injection token cost. */
+	nameTokens: number;
+}
+
+/**
+ * Build a compact skill-name-only prompt section.
+ * Format: "- skill-name: short description"
+ * Stays within the name_budget token limit.
+ */
+export function buildSkillNameIndex(skills: SkillEntry[], nameBudget: number): string {
+	let tokens = 0;
+	const lines: string[] = ["## Available Skills (load on-demand with skill name)"];
+
+	for (const skill of skills) {
+		const line = `- **${skill.name}**: ${skill.description}`;
+		const lineTokens = Math.ceil(line.length / 4);
+
+		if (tokens + lineTokens > nameBudget) {
+			lines.push(`- ...and ${skills.length - lines.length + 1} more`);
+			break;
+		}
+
+		lines.push(line);
+		tokens += lineTokens;
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Detect which skill names are referenced in a message.
+ * Returns names of skills that should be fully loaded.
+ */
+export function detectSkillReferences(message: string, availableSkills: SkillEntry[]): string[] {
+	const lower = message.toLowerCase();
+	const referenced: string[] = [];
+
+	for (const skill of availableSkills) {
+		// Direct name mention
+		if (lower.includes(skill.name)) {
+			referenced.push(skill.name);
+			continue;
+		}
+
+		// Description keyword match (at least 2 significant words)
+		const descWords = skill.description
+			.toLowerCase()
+			.split(/\s+/)
+			.filter((w) => w.length > 4);
+		const matchCount = descWords.filter((w) => lower.includes(w)).length;
+		if (matchCount >= 2) {
+			referenced.push(skill.name);
+		}
+	}
+
+	return referenced;
+}
+
+export class LazySkillLoader {
+	#skills: SkillEntry[] = [];
+	#loadedThisSession: Set<string> = new Set();
+	#stats: LazySkillStats = {
+		totalAvailable: 0,
+		namesInjected: 0,
+		loadedOnDemand: 0,
+		tokensSaved: 0,
+		nameTokens: 0,
+	};
+
+	/**
+	 * Register available skills (called once at session start).
+	 */
+	registerSkills(skills: SkillEntry[]): void {
+		this.#skills = skills;
+		this.#stats.totalAvailable = skills.length;
+	}
+
+	/**
+	 * Get the compact skill name index for prompt injection.
+	 * Returns the name-only section (~200 tokens).
+	 */
+	getNameIndex(nameBudget: number = 200): string {
+		const index = buildSkillNameIndex(this.#skills, nameBudget);
+		this.#stats.namesInjected = Math.min(this.#skills.length, this.#countLines(index));
+		this.#stats.nameTokens = Math.ceil(index.length / 4);
+		return index;
+	}
+
+	/**
+	 * Process a user message — detect skill references and return
+	 * full content for skills that should be loaded.
+	 */
+	processMessage(message: string, maxPerTurn: number = 3): {
+		skillsToLoad: SkillEntry[];
+		indexSection: string;
+	} {
+		const refs = detectSkillReferences(message, this.#skills);
+		const newRefs = refs.filter((r) => !this.#loadedThisSession.has(r));
+
+		// Limit per-turn loading
+		const toLoad = newRefs.slice(0, maxPerTurn);
+		const skillsToLoad: SkillEntry[] = [];
+
+		for (const name of toLoad) {
+			const skill = this.#skills.find((s) => s.name === name);
+			if (skill) {
+				skillsToLoad.push(skill);
+				this.#loadedThisSession.add(name);
+				this.#stats.loadedOnDemand++;
+				this.#stats.tokensSaved += skill.tokens - Math.ceil(skill.name.length / 4);
+			}
+		}
+
+		return {
+			skillsToLoad,
+			indexSection: this.getNameIndex(),
+		};
+	}
+
+	/** Get stats snapshot. */
+	get stats(): Readonly<LazySkillStats> {
+		return { ...this.#stats };
+	}
+
+	/** Get number of skills currently loaded in full. */
+	get loadedCount(): number {
+		return this.#loadedThisSession.size;
+	}
+
+	/** Check if a skill is already loaded. */
+	isLoaded(name: string): boolean {
+		return this.#loadedThisSession.has(name);
+	}
+
+	/** Reset loader state. */
+	reset(): void {
+		this.#loadedThisSession.clear();
+		this.#stats = {
+			totalAvailable: this.#skills.length,
+			namesInjected: 0,
+			loadedOnDemand: 0,
+			tokensSaved: 0,
+			nameTokens: 0,
+		};
+	}
+
+	#countLines(text: string): number {
+		return text.split("\n").filter((l) => l.startsWith("- **")).length;
+	}
+}