@dex-ai/context 0.7.16

package/src/summarize.ts

@@ -0,0 +1,206 @@
+/**
+ * Tool Result Summarization — converts tool results to compact 1-line summaries.
+ *
+ * Used in the warm zone to preserve the "what happened" without the raw data.
+ * Assistant messages are kept intact — only tool results get summarized.
+ */
+
+import type { Message, Content, ToolOutput } from "@dex-ai/sdk";
+
+/**
+ * Summarize all tool results in a message to compact 1-liners.
+ * Returns a new message with tool-result content parts replaced by text summaries.
+ * Non-tool-result parts (text, reasoning) are preserved intact.
+ */
+export function summarizeToolResults(msg: Message): Message {
+	const newContent: Content[] = [];
+
+	for (const part of msg.content) {
+		if (part.type === "tool-result") {
+			// Replace with a compact text summary
+			const summary = summarizeResult(
+				part.toolName,
+				(part as any).input,
+				part.output,
+			);
+			newContent.push({
+				type: "tool-result",
+				toolCallId: part.toolCallId,
+				toolName: part.toolName,
+				output: { type: "text", value: summary },
+			} as Content);
+		} else {
+			newContent.push(part);
+		}
+	}
+
+	return { ...msg, content: newContent };
+}
+
+/**
+ * Generate a 1-line summary for a tool result.
+ */
+function summarizeResult(
+	toolName: string,
+	input: Record<string, unknown> | undefined,
+	output: ToolOutput,
+): string {
+	const text = extractText(output);
+	const isError =
+		output.type === "error-text" || output.type === "error-json";
+
+	if (isError) {
+		const errorLine = text ? firstMeaningfulLine(text) : "unknown error";
+		return `[${toolName} ERROR: ${truncate(errorLine, 80)}]`;
+	}
+
+	switch (toolName) {
+		case "read": {
+			const path = str(input?.path);
+			const lineCount = text ? text.split("\n").length : 0;
+			const range = formatRange(input);
+			return `[read ${path}${range}: ${lineCount} lines]`;
+		}
+
+		case "write": {
+			const path = str(input?.path);
+			return `[wrote ${path}]`;
+		}
+
+		case "edit": {
+			const path = str(input?.path);
+			const edits = Array.isArray(input?.edits) ? input.edits.length : 1;
+			return `[edited ${path}: ${edits} edit${edits !== 1 ? "s" : ""}]`;
+		}
+
+		case "bash": {
+			const cmd = truncate(str(input?.command), 50);
+			const outcome = summarizeBashOutput(text);
+			return `[bash: ${cmd}${outcome}]`;
+		}
+
+		case "search": {
+			const mode = str(input?.mode) || "grep";
+			const pattern = str(input?.pattern);
+			const matchCount = text ? text.split("\n").filter((l) => l.trim()).length : 0;
+			return `[search ${mode} "${truncate(pattern, 30)}": ${matchCount} results]`;
+		}
+
+		case "ast_grep_search": {
+			const pattern = str(input?.pattern);
+			const matchCount = text ? (text.match(/\d+ match/)?.[0] ?? `${text.split("\n").filter((l) => l.trim()).length} lines`) : "0 results";
+			return `[ast-grep "${truncate(pattern, 30)}": ${matchCount}]`;
+		}
+
+		case "ast_grep_replace": {
+			const pattern = str(input?.pattern);
+			const applied = input?.apply ? "applied" : "dry-run";
+			return `[ast-grep replace "${truncate(pattern, 30)}": ${applied}]`;
+		}
+
+		case "lsp_navigation": {
+			const op = str(input?.operation);
+			const file = str(input?.filePath);
+			return `[lsp:${op} ${basename(file)}]`;
+		}
+
+		case "lsp_diagnostics": {
+			const file = str(input?.filePath || (input?.filePaths as any)?.[0]);
+			const diagCount = text ? text.split("\n").filter((l) => l.trim()).length : 0;
+			return `[lsp:diagnostics ${basename(file)}: ${diagCount} issues]`;
+		}
+
+		case "cd": {
+			const path = str(input?.path);
+			return `[cd ${path}]`;
+		}
+
+		default: {
+			// Generic: show tool name + output size
+			const lines = text ? text.split("\n").length : 0;
+			return `[${toolName}: ${lines} lines output]`;
+		}
+	}
+}
+
+/* ── Helpers ───────────────────────────────────────────── */
+
+function extractText(output: ToolOutput): string | null {
+	switch (output.type) {
+		case "text":
+		case "error-text":
+			return output.value;
+		case "json":
+		case "error-json":
+			return JSON.stringify(output.value, null, 2);
+		case "content":
+			return (
+				output.value
+					.filter((p) => p.type === "text")
+					.map((p) => (p as any).text)
+					.join("\n") || null
+			);
+		default:
+			return null;
+	}
+}
+
+function str(v: unknown): string {
+	return typeof v === "string" ? v : "";
+}
+
+function truncate(s: string, max: number): string {
+	const cleaned = s.replace(/\s+/g, " ").trim();
+	return cleaned.length > max ? cleaned.slice(0, max - 1) + "…" : cleaned;
+}
+
+function basename(path: string): string {
+	if (!path) return "";
+	const parts = path.split("/");
+	return parts[parts.length - 1] || path;
+}
+
+function formatRange(input: Record<string, unknown> | undefined): string {
+	if (!input) return "";
+	const start = input.lineStart as number | undefined;
+	const end = input.lineEnd as number | undefined;
+	if (start && end) return ` L${start}-${end}`;
+	if (start) return ` L${start}+`;
+	return "";
+}
+
+function summarizeBashOutput(text: string | null): string {
+	if (!text) return "";
+
+	// Test results
+	const passMatch = text.match(/(\d+)\s*pass(?:ed|ing)?/i);
+	const failMatch = text.match(/(\d+)\s*fail(?:ed|ing|ure)?/i);
+	if (passMatch || failMatch) {
+		const parts: string[] = [];
+		if (passMatch) parts.push(`${passMatch[1]} pass`);
+		if (failMatch) parts.push(`${failMatch[1]} fail`);
+		return ` → ${parts.join(", ")}`;
+	}
+
+	// Non-zero exit
+	const exitMatch = text.match(/\[exit code: ([1-9]\d*)\]/);
+	if (exitMatch) return ` → exit=${exitMatch[1]}`;
+
+	// Short output
+	const trimmed = text.trim();
+	const lines = trimmed.split("\n");
+	if (lines.length <= 2 && trimmed.length < 60) {
+		return ` → ${trimmed}`;
+	}
+
+	return ` (${lines.length} lines)`;
+}
+
+function firstMeaningfulLine(text: string): string {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed && trimmed.length > 5) return trimmed;
+	}
+	return lines[0]?.trim() || "";
+}

package/src/tokenizer.ts

@@ -0,0 +1,20 @@
+/**
+ * Fast token estimation. Calibrated against cl100k_base.
+ * ±10% accuracy — sufficient for budget tracking.
+ */
+
+export function estimateTokens(text: string): number {
+	if (!text) return 0;
+	// Detect content density from first 500 chars
+	const sample = text.slice(0, 500);
+	const symbols = (sample.match(/[{}[\]()=;:,<>|&!@#$%^*~`"']/g) || []).length;
+	const ratio = symbols / Math.max(sample.length, 1);
+	const charsPerToken = ratio > 0.12 ? 3.2 : ratio > 0.06 ? 3.6 : 4.0;
+	return Math.ceil(text.length / charsPerToken);
+}
+
+export function estimateJsonTokens(value: unknown): number {
+	if (value == null) return 1;
+	const json = typeof value === "string" ? value : JSON.stringify(value);
+	return Math.ceil(json.length / 3);
+}

package/src/tracker.ts

@@ -0,0 +1,159 @@
+/**
+ * Context tracker — computes token usage across categories.
+ */
+
+import type { Message, Content, ToolOutput, AnyTool } from "@dex-ai/sdk";
+import type { ContextSnapshot, ContextCategory, CategoryUsage } from "./types";
+import { estimateTokens, estimateJsonTokens } from "./tokenizer";
+
+export class Tracker {
+	private maxTokens: number;
+	private _tokensSaved = 0;
+	private _compressions = 0;
+
+	constructor(maxTokens: number) {
+		this.maxTokens = maxTokens;
+	}
+
+	setMaxTokens(n: number): void {
+		this.maxTokens = n;
+	}
+
+	addSaved(tokens: number, _type: "compress"): void {
+		this._tokensSaved += tokens;
+		this._compressions++;
+	}
+
+	/**
+	 * Compute a full snapshot from current messages + tools + system prompt.
+	 */
+	compute(
+		messages: ReadonlyArray<Message>,
+		tools: ReadonlyArray<AnyTool>,
+		systemPrompt?: string,
+	): ContextSnapshot {
+		return this._compute(messages, tools, systemPrompt);
+	}
+
+	/**
+	 * Compute snapshot from an arbitrary message array (e.g., transformed request).
+	 */
+	computeFromMessages(
+		messages: ReadonlyArray<Message>,
+		tools: ReadonlyArray<AnyTool>,
+		systemPrompt?: string,
+	): ContextSnapshot {
+		return this._compute(messages, tools, systemPrompt);
+	}
+
+	private _compute(
+		messages: ReadonlyArray<Message>,
+		tools: ReadonlyArray<AnyTool>,
+		systemPrompt?: string,
+	): ContextSnapshot {
+		const systemPromptTokens = systemPrompt ? estimateTokens(systemPrompt) : 0;
+		let systemToolsTokens = 0;
+		let messagesTokens = 0;
+		let toolCallsTokens = 0;
+		let toolResultsTokens = 0;
+		let imagesTokens = 0;
+		let filesTokens = 0;
+		let reasoningTokens = 0;
+
+		// Tool definitions
+		for (const tool of tools) {
+			systemToolsTokens += estimateTokens(
+				`${tool.name}${tool.description ?? ""}`,
+			);
+			systemToolsTokens += estimateJsonTokens(tool.parameters);
+		}
+
+		// Messages
+		for (const msg of messages) {
+			for (const part of msg.content) {
+				switch (part.type) {
+					case "text":
+						messagesTokens += estimateTokens(part.text);
+						break;
+					case "reasoning":
+						reasoningTokens += estimateTokens(part.text);
+						break;
+					case "tool-call":
+						toolCallsTokens +=
+							estimateTokens(part.toolName) + estimateJsonTokens(part.input);
+						break;
+					case "tool-result":
+						toolResultsTokens += outputTokens(part.output);
+						break;
+					case "image":
+						imagesTokens += 1000;
+						break;
+					case "file":
+						filesTokens += 500;
+						break;
+				}
+			}
+		}
+
+		const total =
+			systemPromptTokens +
+			systemToolsTokens +
+			messagesTokens +
+			toolCallsTokens +
+			toolResultsTokens +
+			imagesTokens +
+			filesTokens +
+			reasoningTokens;
+
+		const categories: CategoryUsage[] = [];
+		const add = (cat: ContextCategory, tokens: number) => {
+			if (tokens > 0)
+				categories.push({
+					category: cat,
+					tokens,
+					percent: pct(tokens, this.maxTokens),
+				});
+		};
+		add("system-prompt", systemPromptTokens);
+		add("system-tools", systemToolsTokens);
+		add("tool-calls", toolCallsTokens);
+		add("tool-results", toolResultsTokens);
+		add("messages", messagesTokens);
+		add("images", imagesTokens);
+		add("files", filesTokens);
+		add("reasoning", reasoningTokens);
+
+		return {
+			timestamp: Date.now(),
+			totalTokens: total,
+			maxTokens: this.maxTokens,
+			usagePercent: pct(total, this.maxTokens),
+			categories,
+			availableTokens: Math.max(0, this.maxTokens - total),
+			tokensSaved: this._tokensSaved,
+			compressions: this._compressions,
+		};
+	}
+}
+
+function outputTokens(output: ToolOutput): number {
+	switch (output.type) {
+		case "text":
+		case "error-text":
+			return estimateTokens(output.value);
+		case "json":
+		case "error-json":
+			return estimateJsonTokens(output.value);
+		case "content":
+			return output.value.reduce(
+				(sum, p) => sum + (p.type === "text" ? estimateTokens(p.text) : 500),
+				0,
+			);
+		default:
+			return 0;
+	}
+}
+
+function pct(n: number, total: number): number {
+	return total > 0 ? Math.round((n / total) * 1000) / 10 : 0;
+}

package/src/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Types for the context management extension.
+ */
+
+/**
+ * Context budget strategy — controls compression aggressiveness.
+ *
+ * All modes use a fixed 200k context budget and 80k send cap.
+ * The tier determines HOW EARLY compression kicks in:
+ *
+ * - "aggressive" — message-count-based aging with hard delete (most compression, least re-reads)
+ * - "strict"     — same compression triggers, no hard delete
+ * - "balanced"   — wider hot zone (more messages kept intact)
+ * - "relaxed"    — widest hot zone (least compression, for short tasks)
+ */
+export type ContextBudget = "aggressive" | "strict" | "balanced" | "relaxed";
+
+export type ContextCategory =
+	| "system-prompt"
+	| "system-tools"
+	| "messages"
+	| "tool-calls"
+	| "tool-results"
+	| "images"
+	| "files"
+	| "reasoning";
+
+export interface ContextSnapshot {
+	readonly timestamp: number;
+	readonly totalTokens: number;
+	readonly maxTokens: number;
+	readonly usagePercent: number;
+	readonly categories: ReadonlyArray<CategoryUsage>;
+	readonly availableTokens: number;
+	/** Tokens saved this session by all mechanisms. */
+	readonly tokensSaved: number;
+	readonly compressions: number;
+}
+
+export interface CategoryUsage {
+	readonly category: ContextCategory;
+	readonly tokens: number;
+	readonly percent: number;
+}
+
+export interface ContextExtensionOptions {
+	/**
+	 * Context budget strategy. Default: "strict"
+	 */
+	budget?: ContextBudget;
+
+	/** Explicit context window size. Overrides budget strategy. */
+	maxTokens?: number;
+
+	/**
+	 * Number of recent turns to keep fully intact (all content preserved).
+	 * Default: 3
+	 */
+	hotTurns?: number;
+
+	/**
+	 * Number of turns in the warm zone (tool results summarized, messages kept).
+	 * Turns older than hotTurns but within hotTurns + warmTurns.
+	 * Default: 4
+	 */
+	warmTurns?: number;
+
+	/**
+	 * Number of messages in the cold zone (legacy, unused in aggressive mode).
+	 * @deprecated Use generation-aware thresholds in aggressive mode.
+	 */
+	coldMessages?: number;
+
+	/**
+	 * Total message count threshold for hard deletion (legacy, unused in aggressive mode).
+	 * @deprecated Use generation-aware thresholds in aggressive mode.
+	 */
+	deleteThreshold?: number;
+
+	/** Inject a context-awareness skill into the system prompt. Default: true */
+	injectSkill?: boolean;
+}
+
+/* ── Context Events ────────────────────────────────────── */
+
+export type ContextEventType =
+	| "compress-warm"
+	| "compress-cold"
+	| "delete"
+	| "snapshot-built"
+	| "tier-advance";
+
+export interface ContextEvent {
+	readonly type: ContextEventType;
+	readonly turn: number;
+	readonly timestamp: number;
+	readonly tokensSaved?: number;
+	readonly messagesAffected?: number;
+	readonly detail?: string;
+}