@sns-myagent/cli 0.2.0 → 0.3.1

package/src/tbm/comm-modes.ts

@@ -0,0 +1,165 @@
+/**
+ * Communication Modes — controls response verbosity.
+ *
+ * | Mode | Example | Tokens | Use Case |
+ * |------|---------|--------|----------|
+ * | Caveman | `Bug auth. Fix: token_exp < not <=.` | ~20 | Debug, quick ops |
+ * | Normal | `Found bug in auth middleware. Token expiry check uses wrong operator.` | ~60 | Daily work |
+ * | Verbose | Full explanation with context and alternatives... | ~150 | Learning, docs |
+ */
+
+export type CommMode = "caveman" | "normal" | "verbose";
+
+export interface CommModeConfig {
+	/** Mode label. */
+	name: CommMode;
+	/** Approximate target tokens per response. */
+	targetTokens: number;
+	/** System prompt addition to guide response style. */
+	systemDirective: string;
+	/** Human-readable description. */
+	description: string;
+}
+
+/** Mode definitions. */
+export const COMM_MODES: ReadonlyMap<CommMode, CommModeConfig> = new Map([
+	[
+		"caveman",
+		{
+			name: "caveman",
+			targetTokens: 20,
+			description: "Ultra-terse. Fragments only. No filler. Tech terms exact.",
+			systemDirective: `Respond in caveman style:
+- Drop articles (a/an/the), filler words, pleasantries
+- Fragments OK. Short synonyms only
+- Pattern: [thing] [action] [reason]
+- Code blocks, paths, commands, errors: keep exact
+- Security warnings: write normal, resume terse after
+- Example: "Bug in auth middleware. Token expiry check uses < not <=. Fix:"`,
+		},
+	],
+	[
+		"normal",
+		{
+			name: "normal",
+			targetTokens: 60,
+			description: "Clear and concise. Standard professional tone.",
+			systemDirective: `Respond clearly and concisely:
+- Complete sentences but no filler
+- Be direct — state the finding/answer first, then brief context if needed
+- Code blocks, paths, errors: keep exact
+- No pleasantries or hedging`,
+		},
+	],
+	[
+		"verbose",
+		{
+			name: "verbose",
+			targetTokens: 150,
+			description: "Full explanation with context, alternatives, and reasoning.",
+			systemDirective: `Respond with full detail:
+- Explain the "why" behind every recommendation
+- Include alternatives and trade-offs
+- Provide examples where helpful
+- Structure with headers/lists for readability
+- Good for learning, documentation, complex decisions`,
+		},
+	],
+]);
+
+/**
+ * Auto-detect communication mode from message characteristics.
+ */
+export function autoDetectMode(message: string): CommMode {
+	const lower = message.toLowerCase();
+	const len = message.length;
+
+	// Caveman triggers: very short, command-like, debug context
+	if (len < 30) return "caveman";
+	if (len < 80 && !lower.includes("explain") && !lower.includes("why") && !lower.includes("how")) {
+		return "caveman";
+	}
+
+	// Verbose triggers: learning/doc context
+	const verboseKeywords = ["explain", "why", "how does", "teach", "learn", "documentation", "comprehensive", "detailed", "trade-off"];
+	if (verboseKeywords.some((kw) => lower.includes(kw))) return "verbose";
+
+	// Default: normal
+	return "normal";
+}
+
+export class CommunicationModeManager {
+	#currentMode: CommMode | "auto";
+	#effectiveMode: CommMode;
+	#usage: Map<CommMode, number> = new Map([
+		["caveman", 0],
+		["normal", 0],
+		["verbose", 0],
+	]);
+
+	constructor(initialMode: CommMode | "auto" = "auto") {
+		this.#currentMode = initialMode;
+		this.#effectiveMode = initialMode === "auto" ? "normal" : initialMode;
+	}
+
+	/** Get the current mode setting (may be "auto"). */
+	get setting(): CommMode | "auto" {
+		return this.#currentMode;
+	}
+
+	/** Get the effective mode (never "auto" — resolved to concrete mode). */
+	get effective(): CommMode {
+		return this.#effectiveMode;
+	}
+
+	/** Get the system directive for the current effective mode. */
+	get directive(): string {
+		return COMM_MODES.get(this.#effectiveMode)?.systemDirective ?? "";
+	}
+
+	/** Get the target token count for the current effective mode. */
+	get targetTokens(): number {
+		return COMM_MODES.get(this.#effectiveMode)?.targetTokens ?? 60;
+	}
+
+	/**
+	 * Resolve the mode for a new message.
+	 * If mode is "auto", detects from message content.
+	 * Returns the directive to inject into system prompt.
+	 */
+	resolveForMessage(message: string): { mode: CommMode; directive: string } {
+		if (this.#currentMode === "auto") {
+			this.#effectiveMode = autoDetectMode(message);
+		}
+
+		this.#usage.set(this.#effectiveMode, (this.#usage.get(this.#effectiveMode) ?? 0) + 1);
+
+		return {
+			mode: this.#effectiveMode,
+			directive: this.directive,
+		};
+	}
+
+	/** Set mode explicitly (from /mode command). */
+	setMode(mode: CommMode | "auto"): void {
+		this.#currentMode = mode;
+		if (mode !== "auto") {
+			this.#effectiveMode = mode;
+		}
+	}
+
+	/** Get usage stats. */
+	get usage(): ReadonlyMap<CommMode, number> {
+		return this.#usage;
+	}
+
+	/** Reset state. */
+	reset(): void {
+		this.#effectiveMode = this.#currentMode === "auto" ? "normal" : this.#currentMode;
+		this.#usage = new Map([
+			["caveman", 0],
+			["normal", 0],
+			["verbose", 0],
+		]);
+	}
+}

package/src/tbm/config.ts

@@ -0,0 +1,136 @@
+/**
+ * TBM Configuration — all Token Budget Manager settings.
+ *
+ * Loaded from .sns-myagent/config.yaml under the `tbm:` key.
+ * Every subsystem reads its own section; the manager checks `tbm.enabled` first.
+ */
+
+export interface TbmConfig {
+	/** Master switch. All TBM subsystems are inactive when false. */
+	enabled: boolean;
+
+	/** Context Delta Caching — send only changed context each turn. */
+	context_delta: {
+		enabled: boolean;
+	};
+
+	/** Multi-Resolution Context Pyramid — load context in escalating levels. */
+	pyramid: {
+		enabled: boolean;
+		/** Starting pyramid level (0-4). Default 1. */
+		start_level: number;
+		/** Max level to auto-escalate to. Default 4. */
+		max_level: number;
+	};
+
+	/** Lazy Skill Loading — inject skill names only, load on-demand. */
+	lazy_skills: {
+		enabled: boolean;
+		/** Max tokens to spend on skill names in prompt. Default 200. */
+		name_budget: number;
+		/** Max full skills to load per turn. Default 3. */
+		max_per_turn: number;
+	};
+
+	/** Tool Output Auto-Compress — truncate/summarize tool output. */
+	compress: {
+		enabled: boolean;
+		/** Per-tool token budgets. */
+		budgets: {
+			terminal: number;
+			read_file: number;
+			web_extract: number;
+			search_files: number;
+			default: number;
+		};
+	};
+
+	/** Communication Mode — controls response verbosity. */
+	comm_mode: "auto" | "caveman" | "normal" | "verbose";
+
+	/** Conversation Tombstoning — compress old messages. */
+	tombstone: {
+		enabled: boolean;
+		/** Tombstone messages older than N turns. Default 20. */
+		after_turns: number;
+		/** Keep at least N recent messages untouched. Default 5. */
+		keep_recent: number;
+	};
+
+	/** Response Cache — exact and semantic match. */
+	response_cache: {
+		enabled: boolean;
+		/** Cache TTL in seconds. Default 3600. */
+		ttl_seconds: number;
+		/** Max cached responses. Default 100. */
+		max_entries: number;
+		/** Semantic similarity threshold (0-1). Default 0.95. */
+		similarity_threshold: number;
+	};
+}
+
+/** Default TBM configuration — everything enabled with sensible defaults. */
+export const DEFAULT_TBM_CONFIG: TbmConfig = {
+	enabled: true,
+	context_delta: { enabled: true },
+	pyramid: {
+		enabled: true,
+		start_level: 1,
+		max_level: 4,
+	},
+	lazy_skills: {
+		enabled: true,
+		name_budget: 200,
+		max_per_turn: 3,
+	},
+	compress: {
+		enabled: true,
+		budgets: {
+			terminal: 500,
+			read_file: 800,
+			web_extract: 1000,
+			search_files: 300,
+			default: 500,
+		},
+	},
+	comm_mode: "auto",
+	tombstone: {
+		enabled: true,
+		after_turns: 20,
+		keep_recent: 5,
+	},
+	response_cache: {
+		enabled: true,
+		ttl_seconds: 3600,
+		max_entries: 100,
+		similarity_threshold: 0.95,
+	},
+};
+
+/**
+ * Merge user config over defaults. Unknown keys are ignored.
+ * Deep-merges nested objects so partial overrides work.
+ */
+export function resolveTbmConfig(overrides?: Partial<TbmConfig>): TbmConfig {
+	if (!overrides) return { ...DEFAULT_TBM_CONFIG };
+	return deepMerge(DEFAULT_TBM_CONFIG as unknown as Record<string, unknown>, overrides as unknown as Record<string, unknown>) as unknown as TbmConfig;
+}
+
+function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = { ...base };
+	for (const key of Object.keys(over)) {
+		if (
+			over[key] !== null &&
+			typeof over[key] === "object" &&
+			!Array.isArray(over[key]) &&
+			typeof base[key] === "object" &&
+			base[key] !== null &&
+			!Array.isArray(base[key])
+		) {
+			result[key] = deepMerge(base[key] as Record<string, unknown>, over[key] as Record<string, unknown>);
+		} else if (over[key] !== undefined) {
+			result[key] = over[key];
+		}
+	}
+	return result;
+}

package/src/tbm/context-delta.ts

@@ -0,0 +1,146 @@
+/**
+ * Context Delta Caching — send only changed context each turn.
+ *
+ * Static prefix (system prompt, tools, identity) is cached at provider level.
+ * Dynamic suffix (recent messages, tool output) is sent as delta.
+ *
+ * Target: 60-80% input token savings after turn 1.
+ */
+
+import { createHash } from "node:crypto";
+
+export interface ContextDeltaStats {
+	/** Total turns processed. */
+	turns: number;
+	/** Turns where cache hit (static prefix unchanged). */
+	cache_hits: number;
+	/** Estimated tokens saved by not resending static prefix. */
+	tokens_saved: number;
+	/** Total input tokens consumed. */
+	total_input_tokens: number;
+}
+
+export interface ContextSegment {
+	/** Segment type — static rarely changes, dynamic changes every turn. */
+	kind: "static" | "dynamic";
+	/** Content hash for change detection. */
+	hash: string;
+	/** Token count estimate (chars / 4). */
+	tokens: number;
+	/** The actual content. */
+	content: string;
+}
+
+/**
+ * Hash content for change detection. Uses SHA-256 truncated to 16 hex chars.
+ */
+export function hashContent(content: string): string {
+	return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+/**
+ * Estimate token count from character count. Rule of thumb: ~4 chars per token.
+ */
+export function estimateTokens(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+/**
+ * Split full context into static and dynamic segments.
+ *
+ * Static: system prompt + tool definitions + identity.
+ * Dynamic: conversation messages + tool output.
+ */
+export function splitContext(fullContext: string): { staticPart: string; dynamicPart: string } {
+	// Look for the conversation boundary marker
+	const markers = ["<conversation>", "---\n\nUser:", "## Conversation", "Human:", "Assistant:"];
+	let splitIdx = -1;
+
+	for (const marker of markers) {
+		const idx = fullContext.indexOf(marker);
+		if (idx > 0) {
+			splitIdx = idx;
+			break;
+		}
+	}
+
+	// Fallback: split at 60% mark (static usually larger)
+	if (splitIdx < 0) {
+		splitIdx = Math.floor(fullContext.length * 0.6);
+	}
+
+	return {
+		staticPart: fullContext.slice(0, splitIdx),
+		dynamicPart: fullContext.slice(splitIdx),
+	};
+}
+
+export class ContextDeltaCache {
+	#cachedStaticHash: string | null = null;
+	#stats: ContextDeltaStats = {
+		turns: 0,
+		cache_hits: 0,
+		tokens_saved: 0,
+		total_input_tokens: 0,
+	};
+
+	/**
+	 * Process a new turn's context. Returns delta info:
+	 * - `staticChanged`: whether the static prefix needs resending
+	 * - `deltaContent`: only the dynamic part (if static unchanged)
+	 * - `fullContent`: full content (if static changed)
+	 * - `tokensSaved`: estimated tokens saved this turn
+	 */
+	processTurn(fullContext: string): {
+		staticChanged: boolean;
+		content: string;
+		tokensSaved: number;
+	} {
+		this.#stats.turns++;
+
+		const { staticPart, dynamicPart } = splitContext(fullContext);
+		const staticHash = hashContent(staticPart);
+		const dynamicTokens = estimateTokens(dynamicPart);
+		const staticTokens = estimateTokens(staticPart);
+
+		this.#stats.total_input_tokens += dynamicTokens;
+
+		if (this.#cachedStaticHash === staticHash) {
+			// Cache HIT — static prefix unchanged, send only delta
+			this.#stats.cache_hits++;
+			this.#stats.tokens_saved += staticTokens;
+			return {
+				staticChanged: false,
+				content: dynamicPart,
+				tokensSaved: staticTokens,
+			};
+		}
+
+		// Cache MISS — static prefix changed, resend everything
+		this.#cachedStaticHash = staticHash;
+		this.#stats.total_input_tokens += staticTokens;
+
+		return {
+			staticChanged: true,
+			content: fullContext,
+			tokensSaved: 0,
+		};
+	}
+
+	/** Get current stats snapshot. */
+	get stats(): Readonly<ContextDeltaStats> {
+		return { ...this.#stats };
+	}
+
+	/** Cache hit rate (0-1). */
+	get hitRate(): number {
+		if (this.#stats.turns === 0) return 0;
+		return this.#stats.cache_hits / this.#stats.turns;
+	}
+
+	/** Reset cache state (e.g. on session reset). */
+	reset(): void {
+		this.#cachedStaticHash = null;
+		this.#stats = { turns: 0, cache_hits: 0, tokens_saved: 0, total_input_tokens: 0 };
+	}
+}

package/src/tbm/context-pyramid.ts

@@ -0,0 +1,202 @@
+/**
+ * Multi-Resolution Context Pyramid — load context in escalating levels.
+ *
+ * Each level adds more context. Auto-escalates when response quality drops.
+ *
+ * Level 0: Identity only (~100 tokens) — Simple Q&A
+ * Level 1: + Last 3 messages (~500 tokens) — Continuation
+ * Level 2: + Relevant memories (~1,000 tokens) — Contextual tasks
+ * Level 3: + Relevant skills (~2,000 tokens) — Complex tasks
+ * Level 4: + Full history (~5,000 tokens) — Deep research
+ */
+
+export type PyramidLevel = 0 | 1 | 2 | 3 | 4;
+
+export interface PyramidLevelConfig {
+	level: PyramidLevel;
+	/** Human-readable label. */
+	label: string;
+	/** Approximate token budget for this level. */
+	tokenBudget: number;
+	/** What content is included at this level. */
+	includes: string[];
+}
+
+/** Pyramid level definitions. */
+export const PYRAMID_LEVELS: ReadonlyMap<PyramidLevel, PyramidLevelConfig> = new Map([
+	[0, { level: 0, label: "Identity", tokenBudget: 100, includes: ["identity"] }],
+	[1, { level: 1, label: "Continuation", tokenBudget: 500, includes: ["identity", "last_3_messages"] }],
+	[2, { level: 2, label: "Contextual", tokenBudget: 1000, includes: ["identity", "last_3_messages", "relevant_memories"] }],
+	[3, { level: 3, label: "Complex", tokenBudget: 2000, includes: ["identity", "last_3_messages", "relevant_memories", "relevant_skills"] }],
+	[4, { level: 4, label: "Deep Research", tokenBudget: 5000, includes: ["identity", "last_3_messages", "relevant_memories", "relevant_skills", "full_history"] }],
+]);
+
+export interface PyramidStats {
+	/** Current active level. */
+	currentLevel: PyramidLevel;
+	/** Total escalations this session. */
+	escalations: number;
+	/** Total de-escalations this session. */
+	deescalations: number;
+	/** Tokens consumed at each level. */
+	levelTokens: Record<PyramidLevel, number>;
+}
+
+/**
+ * Analyze task complexity to determine initial pyramid level.
+ * Returns 0-4 based on heuristics.
+ */
+export function analyzeTaskComplexity(message: string): PyramidLevel {
+	const lower = message.toLowerCase();
+	const len = message.length;
+
+	// Simple Q&A triggers
+	if (len < 50 && !lower.includes("?") && !lower.includes("how") && !lower.includes("why")) {
+		return 0;
+	}
+
+	// Complex task indicators
+	const complexKeywords = ["implement", "debug", "refactor", "architecture", "design", "explain in detail", "compare", "analyze"];
+	const hasComplexKeyword = complexKeywords.some((kw) => lower.includes(kw));
+
+	// Research indicators
+	const researchKeywords = ["research", "investigate", "comprehensive", "all options", "trade-offs", "deep dive"];
+	const hasResearchKeyword = researchKeywords.some((kw) => lower.includes(kw));
+
+	if (hasResearchKeyword && len > 200) return 4;
+	if (hasComplexKeyword && len > 100) return 3;
+	if (len > 50 || lower.includes("?")) return 2;
+	return 1;
+}
+
+export class ContextPyramid {
+	#currentLevel: PyramidLevel;
+	#maxLevel: PyramidLevel;
+	#stats: PyramidStats;
+	#recentQuality: number[] = []; // last N response quality scores (0-1)
+
+	constructor(startLevel: PyramidLevel = 1, maxLevel: PyramidLevel = 4) {
+		this.#currentLevel = startLevel;
+		this.#maxLevel = maxLevel;
+		this.#stats = {
+			currentLevel: startLevel,
+			escalations: 0,
+			deescalations: 0,
+			levelTokens: { 0: 0, 1: 0, 2: 0, 3: 0, 4: 0 },
+		};
+	}
+
+	/** Get the current pyramid level config. */
+	get current(): PyramidLevelConfig {
+		return PYRAMID_LEVELS.get(this.#currentLevel)!;
+	}
+
+	/** Get current level number. */
+	get level(): PyramidLevel {
+		return this.#currentLevel;
+	}
+
+	/** Get stats snapshot. */
+	get stats(): Readonly<PyramidStats> {
+		return { ...this.#stats };
+	}
+
+	/**
+	 * Determine context level for a new message.
+	 * Auto-escalates based on task complexity if level was set to auto.
+	 */
+	resolveLevel(message: string): PyramidLevel {
+		const suggested = analyzeTaskComplexity(message);
+		return Math.min(suggested, this.#maxLevel) as PyramidLevel;
+	}
+
+	/**
+	 * Set level explicitly (from /mode command or auto-detect).
+	 */
+	setLevel(level: PyramidLevel): void {
+		if (level < 0 || level > 4) return;
+		if (level > this.#maxLevel) level = this.#maxLevel;
+
+		if (level > this.#currentLevel) {
+			this.#stats.escalations++;
+		} else if (level < this.#currentLevel) {
+			this.#stats.deescalations++;
+		}
+
+		this.#currentLevel = level;
+		this.#stats.currentLevel = level;
+	}
+
+	/**
+	 * Report response quality to inform escalation decisions.
+	 * Quality: 0 = garbage, 1 = perfect.
+	 */
+	reportQuality(quality: number): void {
+		this.#recentQuality.push(Math.max(0, Math.min(1, quality)));
+		if (this.#recentQuality.length > 5) {
+			this.#recentQuality.shift();
+		}
+
+		// If average quality < 0.5 and not at max, escalate
+		const avg = this.#recentQuality.reduce((a, b) => a + b, 0) / this.#recentQuality.length;
+		if (avg < 0.5 && this.#currentLevel < this.#maxLevel) {
+			this.setLevel((this.#currentLevel + 1) as PyramidLevel);
+		}
+	}
+
+	/**
+	 * Record token usage at the current level.
+	 */
+	recordUsage(tokens: number): void {
+		this.#stats.levelTokens[this.#currentLevel] += tokens;
+	}
+
+	/**
+	 * Filter context content based on current pyramid level.
+	 * Returns only the content appropriate for the level.
+	 */
+	filterContext(context: {
+		identity?: string;
+		recentMessages?: string[];
+		memories?: string[];
+		skills?: string[];
+		fullHistory?: string;
+	}): string {
+		const parts: string[] = [];
+		const levelConfig = PYRAMID_LEVELS.get(this.#currentLevel)!;
+
+		if (levelConfig.includes.includes("identity") && context.identity) {
+			parts.push(context.identity);
+		}
+
+		if (levelConfig.includes.includes("last_3_messages") && context.recentMessages) {
+			parts.push(context.recentMessages.slice(-3).join("\n"));
+		}
+
+		if (levelConfig.includes.includes("relevant_memories") && context.memories) {
+			parts.push(context.memories.join("\n"));
+		}
+
+		if (levelConfig.includes.includes("relevant_skills") && context.skills) {
+			parts.push(context.skills.join("\n"));
+		}
+
+		if (levelConfig.includes.includes("full_history") && context.fullHistory) {
+			parts.push(context.fullHistory);
+		}
+
+		return parts.join("\n\n");
+	}
+
+	/** Reset pyramid state. */
+	reset(): void {
+		this.#currentLevel = 1;
+		this.#recentQuality = [];
+		this.#stats = {
+			currentLevel: 1,
+			escalations: 0,
+			deescalations: 0,
+			levelTokens: { 0: 0, 1: 0, 2: 0, 3: 0, 4: 0 },
+		};
+	}
+}