@dex-ai/devtools-extension 0.1.15

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dex-ai/devtools-extension",
+  "version": "0.1.15",
+  "description": "Devtools Extension for @dex-ai/sdk — logging, telemetry, and self-introspection tools for debugging the agent loop.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"(no tests)\"",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2",
+    "@dex-ai/core-extensions": "^0.1.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/bun": "latest",
+    "bun-types": "latest",
+    "@changesets/cli": "^2.29.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/introspection/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: devtools.introspection
+description: Tells the agent about available self-debugging tools.
+---
+
+## Devtools
+
+You have access to self-debugging tools prefixed with `devtools_`. Use them to:
+- Inspect your own extensions, tools, and configuration (`devtools_extensions`, `devtools_tools`, `devtools_config`)
+- Check token usage and performance telemetry (`devtools_telemetry`)
+- View recent logs and errors from your agent loop (`devtools_logs`)
+- Inspect extension state (`devtools_state`)
+- Debug session info — message count, history shape (`devtools_session`)
+- Capture what's visible on the terminal screen (`devtools_screenshot`)
+
+Call these tools when you need to understand your own runtime state, diagnose issues with tool execution, or verify your environment is configured correctly.
+
+### Terminal Screenshot
+
+Use `devtools_screenshot` to see what the user sees on their terminal. This returns the full rendered TUI frame as plain text. Useful for:
+- Verifying the UI looks correct after making TUI changes
+- Seeing info panel content, status bars, and error displays
+- Debugging layout issues in the terminal UI
+- Understanding what the user is looking at when they describe a visual issue

package/src/index.ts

@@ -0,0 +1,376 @@
+/**
+ * @dex-ai/devtools-extension — logging, telemetry, and self-introspection.
+ *
+ * Provides structured event logging, timing/usage telemetry, and tools
+ * that let the agent introspect its own loop (extensions, tools, config,
+ * session state, etc.).
+ *
+ * Integrates with @dex-ai/context when loaded — pulls live context
+ * pressure metrics, knowledge base stats, and compression activity
+ * into the unified telemetry snapshot.
+ *
+ * Usage:
+ *   import { devtoolsExtension } from '@dex-ai/devtools-extension';
+ *
+ *   const agent = await Agent.create({
+ *     extensions: [...otherExtensions, devtoolsExtension()],
+ *   });
+ */
+
+import type {
+	Extension,
+	ExtensionEvents,
+	Skill,
+	AnyTool,
+	AgentContext,
+	GenerateContext,
+	ModelRequest,
+	ToolCall,
+	ToolResult,
+	ErrorSource,
+	Message,
+} from "@dex-ai/sdk";
+import { loadSkill } from "@dex-ai/core-extensions/skills";
+import { Logger, type LogLevel, type LogOutput } from "./logger";
+import { Telemetry, type ContextStats } from "./telemetry";
+import { createDevtoolsTools } from "./tools";
+import { join } from "node:path";
+
+/* ------------------------------------------------------------------ */
+/* Public types                                                        */
+/* ------------------------------------------------------------------ */
+
+export type { LogEntry, LogLevel, LogOutput } from "./logger";
+export type { TelemetryStats, ToolStats, ContextStats } from "./telemetry";
+
+export interface DevtoolsOptions {
+	/** Minimum log level. Default: "debug". */
+	readonly logLevel?: LogLevel;
+	/** Maximum log entries in ring buffer. Default: 500. */
+	readonly maxLogEntries?: number;
+	/** Expose introspection tools to the agent. Default: true. */
+	readonly enableTools?: boolean;
+	/** Inject a skill describing devtools capabilities. Default: true. */
+	readonly enableSkill?: boolean;
+	/** Log output target. Default: "stderr". */
+	readonly output?: LogOutput;
+}
+
+/* ------------------------------------------------------------------ */
+/* Skill content                                                       */
+/* ------------------------------------------------------------------ */
+
+const DEVTOOLS_SKILL: Skill = loadSkill(
+	join(import.meta.dir, "../skills/introspection"),
+);
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                   */
+/* ------------------------------------------------------------------ */
+
+export function devtoolsExtension(opts: DevtoolsOptions = {}): Extension {
+	const logLevel = opts.logLevel ?? "debug";
+	const maxLogEntries = opts.maxLogEntries ?? 500;
+	const enableTools = opts.enableTools ?? true;
+	const enableSkill = opts.enableSkill ?? true;
+	const output = opts.output ?? "stderr";
+
+	const logger = new Logger({
+		level: logLevel,
+		maxEntries: maxLogEntries,
+		output,
+	});
+	const telemetry = new Telemetry();
+
+	// Build tools list
+	const tools: AnyTool[] = enableTools
+		? createDevtoolsTools(logger, telemetry)
+		: [];
+
+	// Build skills list
+	const skills: Skill[] = enableSkill ? [DEVTOOLS_SKILL] : [];
+
+	/* ---------------------------------------------------------------- */
+	/* Event handlers                                                    */
+	/* ---------------------------------------------------------------- */
+
+	const on: ExtensionEvents = {
+		"session-start": async (_actx: AgentContext) => {
+			logger.info("session-start", {
+				agent: _actx.name,
+				provider: _actx.providerName,
+				model: _actx.modelId,
+				extensionCount: _actx.extensions.length,
+			});
+			return undefined;
+		},
+
+		"session-stop": async (_actx: AgentContext) => {
+			logger.info("session-stop", {
+				stats: telemetry.getStats(),
+			});
+		},
+
+		"generate-start": async (gctx: GenerateContext) => {
+			telemetry.onGenerateStart();
+			logger.debug("generate-start", {
+				maxSteps: gctx.maxSteps,
+				messageCount: gctx.agent.messages.length,
+			});
+			return undefined;
+		},
+
+		"generate-stop": async (gctx: GenerateContext) => {
+			telemetry.onGenerateStop(
+				gctx.stepCount + 1,
+				gctx.usage.inputTokens,
+				gctx.usage.outputTokens,
+				gctx.usage.cachedInputTokens,
+				gctx.usage.cacheCreationInputTokens,
+			);
+			logger.debug("generate-stop", {
+				steps: gctx.stepCount + 1,
+				usage: gctx.usage,
+			});
+		},
+
+		"model-start": async (req: ModelRequest, gctx: GenerateContext) => {
+			telemetry.onModelStart();
+			logger.debug("model-start", {
+				step: gctx.stepCount,
+				messageCount: req.messages.length,
+				toolCount: req.tools?.length ?? 0,
+			});
+			return undefined;
+		},
+
+		"model-stop": async (_gctx: GenerateContext) => {
+			telemetry.onModelStop();
+			logger.debug("model-stop");
+		},
+
+		"tool-start": async (call: ToolCall, _gctx: GenerateContext) => {
+			telemetry.onToolStart(call.toolCallId, call.toolName);
+			logger.debug("tool-start", {
+				tool: call.toolName,
+				callId: call.toolCallId,
+			});
+			return undefined;
+		},
+
+		"tool-stop": async (result: ToolResult, _gctx: GenerateContext) => {
+			const isError =
+				result.output.type === "error-text" ||
+				result.output.type === "error-json";
+			telemetry.onToolStop(result.toolCallId, result.toolName, isError);
+
+			// Track context search metrics
+			if (result.toolName === "ctx_search" && !isError) {
+				const text = result.output.type === "text" ? result.output.value : "";
+				const queryCount = (text.match(/^## /gm) || []).length || 1;
+				const misses = (text.match(/No results found/g) || []).length;
+				const resultHeaders = (text.match(/^### /gm) || []).length;
+				telemetry.onContextSearch(queryCount, resultHeaders, misses);
+			}
+
+			// Track auto-indexing (pointer creation)
+			if (
+				!isError &&
+				result.output.type === "text" &&
+				result.output.value.startsWith("Indexed ") &&
+				result.output.value.includes("ctx_search")
+			) {
+				// This was a pointer-replaced result
+				const bytesMatch = result.output.value.match(
+					/Original size: ([\d.]+)KB/,
+				);
+				const bytes = bytesMatch
+					? Math.round(parseFloat(bytesMatch[1]!) * 1024)
+					: 0;
+				telemetry.onContextPointerCreated(bytes);
+			}
+
+			logger.debug("tool-stop", {
+				tool: result.toolName,
+				callId: result.toolCallId,
+				isError,
+			});
+			return undefined;
+		},
+
+		error: async (
+			error: unknown,
+			source: ErrorSource,
+			_gctx: GenerateContext,
+		) => {
+			telemetry.onError(source.kind);
+			logger.error("error", {
+				kind: source.kind,
+				message: error instanceof Error ? error.message : String(error),
+				extensionName: source.extensionName ?? undefined,
+				event: source.event ?? undefined,
+			});
+		},
+
+		"message-stop": async (message: Message, _gctx: GenerateContext) => {
+			logger.debug("message-stop", {
+				role: message.role,
+				contentParts: message.content.length,
+			});
+		},
+	};
+
+	const ext = {
+		name: "devtools",
+		description:
+			"Development tools — logging, telemetry, and self-introspection for debugging the agent loop.",
+		tools,
+		skills,
+		on,
+
+		init(actx: AgentContext) {
+			// Wire up the context state resolver so telemetry can pull live
+			// context metrics when devtools_telemetry is called.
+			telemetry.setContextStateResolver(() => {
+				return resolveContextStats(actx);
+			});
+		},
+	};
+
+	return ext as Extension;
+}
+
+/* ------------------------------------------------------------------ */
+/* Context State Resolver                                              */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Resolve live context stats from the @dex-ai/context extension's state.
+ * Returns null if the context extension isn't loaded.
+ */
+function resolveContextStats(actx: AgentContext): ContextStats | null {
+	// Get snapshot from context extension
+	const snapshotFn = actx.state.get("context:snapshot");
+	const storeFn = actx.state.get("context:store");
+	const eventsFn = actx.state.get("context:events");
+	const metricsFn = actx.state.get("context:metrics");
+
+	if (!snapshotFn || typeof snapshotFn !== "function") return null;
+
+	try {
+		const snapshot = snapshotFn() as {
+			totalTokens: number;
+			maxTokens: number;
+			usagePercent: number;
+			tokensSaved: number;
+			compressions: number;
+		} | null;
+		if (!snapshot) return null;
+
+		// Get knowledge base stats
+		let kbStats = { sources: 0, chunks: 0, totalBytes: 0 };
+		if (storeFn && typeof storeFn === "function") {
+			try {
+				const store = storeFn() as {
+					getStats(): { sources: number; chunks: number; totalBytes: number };
+				} | null;
+				if (store) kbStats = store.getStats();
+			} catch {
+				/* store not available */
+			}
+		}
+
+		// Get context metrics (auto-index, pointer, search stats)
+		let ctxMetrics = {
+			autoIndexed: 0,
+			pointersCreated: 0,
+			bytesDiverted: 0,
+			searchCalls: 0,
+			searchQueries: 0,
+			searchMisses: 0,
+			searchTotalResults: 0,
+		};
+		if (metricsFn && typeof metricsFn === "function") {
+			try {
+				const m = metricsFn() as typeof ctxMetrics | null;
+				if (m) ctxMetrics = m;
+			} catch {
+				/* metrics not available */
+			}
+		}
+
+		// Get compression events
+		let compWarm = 0,
+			compCold = 0,
+			compDelete = 0;
+		if (eventsFn && typeof eventsFn === "function") {
+			try {
+				const events = eventsFn() as Array<{
+					type: string;
+					tokensSaved?: number;
+				}> | null;
+				if (events) {
+					for (const ev of events) {
+						switch (ev.type) {
+							case "compress-warm":
+								compWarm++;
+								break;
+							case "compress-cold":
+								compCold++;
+								break;
+							case "delete":
+								compDelete++;
+								break;
+						}
+					}
+				}
+			} catch {
+				/* events not available */
+			}
+		}
+
+		const totalCompressions = compWarm + compCold + compDelete;
+		const successfulQueries =
+			ctxMetrics.searchQueries - ctxMetrics.searchMisses;
+
+		return {
+			usagePercent: snapshot.usagePercent,
+			totalTokens: snapshot.totalTokens,
+			maxTokens: snapshot.maxTokens,
+			tokensSaved: snapshot.tokensSaved,
+			compressions: totalCompressions,
+			compressionsByType: {
+				warm: compWarm,
+				cold: compCold,
+				delete: compDelete,
+			},
+			knowledgeBase: {
+				sources: kbStats.sources,
+				chunks: kbStats.chunks,
+				bytesIndexed: kbStats.totalBytes,
+				autoIndexed: ctxMetrics.autoIndexed,
+				pointersCreated: ctxMetrics.pointersCreated,
+				searchCalls: ctxMetrics.searchCalls,
+				searchQueries: ctxMetrics.searchQueries,
+				searchMisses: ctxMetrics.searchMisses,
+				avgResultsPerQuery:
+					successfulQueries > 0
+						? Math.round(
+								(ctxMetrics.searchTotalResults / successfulQueries) * 10,
+							) / 10
+						: 0,
+			},
+			bytesDiverted: ctxMetrics.bytesDiverted,
+			compressionRatio:
+				snapshot.tokensSaved > 0 && snapshot.totalTokens > 0
+					? Math.round(
+							(snapshot.tokensSaved /
+								(snapshot.totalTokens + snapshot.tokensSaved)) *
+								100,
+						) / 100
+					: 0,
+		};
+	} catch {
+		return null;
+	}
+}

package/src/logger.ts

@@ -0,0 +1,143 @@
+/**
+ * Ring-buffer logger for agent loop events.
+ *
+ * Collects structured LogEntry objects from extension event hooks.
+ * Supports level filtering, max size (ring buffer), and configurable output.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogEntry {
+  readonly timestamp: number;
+  readonly level: LogLevel;
+  readonly event: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export type LogOutput = "stderr" | "none" | ((entry: LogEntry) => void);
+
+export interface LoggerOptions {
+  readonly level: LogLevel;
+  readonly maxEntries: number;
+  readonly output: LogOutput;
+}
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  debug: "\x1b[90m", // gray
+  info: "\x1b[36m", // cyan
+  warn: "\x1b[33m", // yellow
+  error: "\x1b[31m", // red
+};
+
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+
+function formatEntry(entry: LogEntry): string {
+  const time = new Date(entry.timestamp).toISOString().slice(11, 23);
+  const color = LEVEL_COLORS[entry.level];
+  const lvl = entry.level.toUpperCase().padEnd(5);
+  const data = entry.data ? ` ${DIM}${JSON.stringify(entry.data)}${RESET}` : "";
+  return `${DIM}${time}${RESET} ${color}${lvl}${RESET} ${entry.event}${data}`;
+}
+
+/**
+ * Ring-buffer logger.
+ *
+ * Stores up to `maxEntries` log entries. When full, oldest entries are dropped.
+ */
+export class Logger {
+  private readonly entries: LogEntry[] = [];
+  private readonly level: number;
+  private readonly maxEntries: number;
+  private readonly output: LogOutput;
+
+  constructor(opts: LoggerOptions) {
+    this.level = LEVEL_ORDER[opts.level];
+    this.maxEntries = opts.maxEntries;
+    this.output = opts.output;
+  }
+
+  log(level: LogLevel, event: string, data?: Record<string, unknown>): void {
+    if (LEVEL_ORDER[level] < this.level) return;
+
+    const entry: LogEntry = {
+      timestamp: Date.now(),
+      level,
+      event,
+      ...(data !== undefined ? { data } : {}),
+    };
+
+    // Ring buffer: drop oldest when full
+    if (this.entries.length >= this.maxEntries) {
+      this.entries.shift();
+    }
+    this.entries.push(entry);
+
+    // Output
+    if (this.output === "stderr") {
+      process.stderr.write(formatEntry(entry) + "\n");
+    } else if (typeof this.output === "function") {
+      this.output(entry);
+    }
+  }
+
+  debug(event: string, data?: Record<string, unknown>): void {
+    this.log("debug", event, data);
+  }
+
+  info(event: string, data?: Record<string, unknown>): void {
+    this.log("info", event, data);
+  }
+
+  warn(event: string, data?: Record<string, unknown>): void {
+    this.log("warn", event, data);
+  }
+
+  error(event: string, data?: Record<string, unknown>): void {
+    this.log("error", event, data);
+  }
+
+  /**
+   * Query log entries with optional filtering.
+   */
+  query(opts?: {
+    level?: LogLevel;
+    event?: string;
+    last?: number;
+  }): ReadonlyArray<LogEntry> {
+    let result: LogEntry[] = [...this.entries];
+
+    if (opts?.level) {
+      const minLevel = LEVEL_ORDER[opts.level];
+      result = result.filter((e) => LEVEL_ORDER[e.level] >= minLevel);
+    }
+
+    if (opts?.event) {
+      const pattern = opts.event;
+      result = result.filter((e) => e.event.includes(pattern));
+    }
+
+    if (opts?.last !== undefined && opts.last > 0) {
+      result = result.slice(-opts.last);
+    }
+
+    return result;
+  }
+
+  /** Total entry count (may be less than all events if ring buffer has wrapped). */
+  get size(): number {
+    return this.entries.length;
+  }
+
+  /** Clear all entries. */
+  clear(): void {
+    this.entries.length = 0;
+  }
+}

package/src/telemetry.ts

@@ -0,0 +1,371 @@
+/**
+ * Telemetry — accumulates timing and usage statistics across the session.
+ *
+ * Tracks: session lifecycle, token usage, model call performance,
+ * per-tool execution stats, error counts, AND context management metrics.
+ */
+
+export interface ToolStats {
+	calls: number;
+	errors: number;
+	totalDurationMs: number;
+	avgDurationMs: number;
+}
+
+export interface ContextStats {
+	/** Current context window utilization (0-100) */
+	usagePercent: number;
+	/** Total tokens currently in context */
+	totalTokens: number;
+	/** Maximum token budget */
+	maxTokens: number;
+	/** Total tokens saved by all compression mechanisms this session */
+	tokensSaved: number;
+	/** Number of compression events fired */
+	compressions: number;
+	/** Breakdown by compression type */
+	compressionsByType: {
+		warm: number;
+		cold: number;
+		delete: number;
+	};
+	/** Knowledge base metrics */
+	knowledgeBase: {
+		/** Total sources indexed */
+		sources: number;
+		/** Total chunks in FTS5 store */
+		chunks: number;
+		/** Total bytes indexed (raw content size) */
+		bytesIndexed: number;
+		/** How many tool results were auto-indexed (>threshold) */
+		autoIndexed: number;
+		/** How many tool results were replaced with pointers (>full-replace threshold) */
+		pointersCreated: number;
+		/** Total ctx_search calls */
+		searchCalls: number;
+		/** Total search queries executed */
+		searchQueries: number;
+		/** Queries that returned 0 results */
+		searchMisses: number;
+		/** Average results per successful query */
+		avgResultsPerQuery: number;
+	};
+	/** Bytes that would have been in context but were indexed instead */
+	bytesDiverted: number;
+	/** Effective compression ratio (bytes saved / bytes that would have been used) */
+	compressionRatio: number;
+}
+
+export interface TelemetryStats {
+	session: {
+		startedAt: number;
+		generates: number;
+		totalSteps: number;
+	};
+	tokens: {
+		input: number;
+		output: number;
+		total: number;
+	};
+	cache: {
+		reads: number;
+		writes: number;
+		totalInput: number;
+		hitRate: number; // 0-1 ratio of cached reads to total input
+	};
+	models: {
+		calls: number;
+		totalDurationMs: number;
+		avgDurationMs: number;
+	};
+	tools: Record<string, ToolStats>;
+	errors: {
+		total: number;
+		byKind: Record<string, number>;
+	};
+	/** Context management and knowledge base metrics. Null if @dex-ai/context not loaded. */
+	context: ContextStats | null;
+}
+
+/**
+ * Telemetry collector. Tracks stats across the agent session.
+ */
+export class Telemetry {
+	private readonly sessionStartedAt: number;
+	private generateCount = 0;
+	private totalSteps = 0;
+
+	private inputTokens = 0;
+	private outputTokens = 0;
+
+	// Cache metrics
+	private cacheReads = 0;
+	private cacheWrites = 0;
+	private totalInputForCache = 0;
+
+	private modelCalls = 0;
+	private modelTotalDuration = 0;
+	private currentModelStart = 0;
+
+	private readonly toolStats = new Map<
+		string,
+		{ calls: number; errors: number; totalDurationMs: number }
+	>();
+	private readonly pendingTools = new Map<string, number>(); // toolCallId → startedAt
+
+	private errorTotal = 0;
+	private readonly errorsByKind = new Map<string, number>();
+
+	// Context metrics
+	private contextAutoIndexed = 0;
+	private contextPointersCreated = 0;
+	private contextSearchCalls = 0;
+	private contextSearchQueries = 0;
+	private contextSearchMisses = 0;
+	private contextSearchTotalResults = 0;
+	private contextBytesDiverted = 0;
+	private contextCompressionsWarm = 0;
+	private contextCompressionsCold = 0;
+	private contextCompressionsDelete = 0;
+
+	// External state resolver — set from extension wiring
+	private contextStateResolver: (() => ContextStats | null) | null = null;
+
+	constructor() {
+		this.sessionStartedAt = Date.now();
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Context management metrics                                           */
+	/* ------------------------------------------------------------------ */
+
+	/**
+	 * Set a resolver function that reads live context state.
+	 * Called by the devtools extension init() after the context extension
+	 * has set up its state accessors.
+	 */
+	setContextStateResolver(resolver: () => ContextStats | null): void {
+		this.contextStateResolver = resolver;
+	}
+
+	/** Track when a tool result is auto-indexed into the knowledge base. */
+	onContextAutoIndex(byteSize: number): void {
+		this.contextAutoIndexed++;
+		this.contextBytesDiverted += byteSize;
+	}
+
+	/** Track when a large tool result is replaced with a pointer. */
+	onContextPointerCreated(byteSize: number): void {
+		this.contextPointersCreated++;
+		// bytesDiverted already counted in onContextAutoIndex
+	}
+
+	/** Track a ctx_search invocation. */
+	onContextSearch(
+		queryCount: number,
+		totalResults: number,
+		misses: number,
+	): void {
+		this.contextSearchCalls++;
+		this.contextSearchQueries += queryCount;
+		this.contextSearchMisses += misses;
+		this.contextSearchTotalResults += totalResults;
+	}
+
+	/** Track a compression event. */
+	onContextCompression(
+		type: "warm" | "cold" | "delete",
+		tokensSaved: number,
+	): void {
+		switch (type) {
+			case "warm":
+				this.contextCompressionsWarm++;
+				break;
+			case "cold":
+				this.contextCompressionsCold++;
+				break;
+			case "delete":
+				this.contextCompressionsDelete++;
+				break;
+		}
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Generate lifecycle                                                   */
+	/* ------------------------------------------------------------------ */
+
+	onGenerateStart(): void {
+		this.generateCount++;
+	}
+
+	onGenerateStop(
+		steps: number,
+		inputTokens: number,
+		outputTokens: number,
+		cachedInputTokens?: number,
+		cacheCreationInputTokens?: number,
+	): void {
+		this.totalSteps += steps;
+		this.inputTokens += inputTokens;
+		this.outputTokens += outputTokens;
+		this.totalInputForCache += inputTokens;
+		if (cachedInputTokens) this.cacheReads += cachedInputTokens;
+		if (cacheCreationInputTokens) this.cacheWrites += cacheCreationInputTokens;
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Model lifecycle                                                      */
+	/* ------------------------------------------------------------------ */
+
+	onModelStart(): void {
+		this.modelCalls++;
+		this.currentModelStart = Date.now();
+	}
+
+	onModelStop(): void {
+		if (this.currentModelStart > 0) {
+			this.modelTotalDuration += Date.now() - this.currentModelStart;
+			this.currentModelStart = 0;
+		}
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Tool lifecycle                                                       */
+	/* ------------------------------------------------------------------ */
+
+	onToolStart(toolCallId: string, _toolName: string): void {
+		this.pendingTools.set(toolCallId, Date.now());
+	}
+
+	onToolStop(toolCallId: string, toolName: string, isError: boolean): void {
+		const startedAt = this.pendingTools.get(toolCallId);
+		this.pendingTools.delete(toolCallId);
+		const duration = startedAt !== undefined ? Date.now() - startedAt : 0;
+
+		let stats = this.toolStats.get(toolName);
+		if (!stats) {
+			stats = { calls: 0, errors: 0, totalDurationMs: 0 };
+			this.toolStats.set(toolName, stats);
+		}
+		stats.calls++;
+		if (isError) stats.errors++;
+		stats.totalDurationMs += duration;
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Errors                                                               */
+	/* ------------------------------------------------------------------ */
+
+	onError(kind: string): void {
+		this.errorTotal++;
+		this.errorsByKind.set(kind, (this.errorsByKind.get(kind) ?? 0) + 1);
+	}
+
+	/* ------------------------------------------------------------------ */
+	/* Snapshot                                                             */
+	/* ------------------------------------------------------------------ */
+
+	getStats(): TelemetryStats {
+		const tools: Record<string, ToolStats> = {};
+		for (const [name, s] of this.toolStats) {
+			tools[name] = {
+				calls: s.calls,
+				errors: s.errors,
+				totalDurationMs: s.totalDurationMs,
+				avgDurationMs:
+					s.calls > 0 ? Math.round(s.totalDurationMs / s.calls) : 0,
+			};
+		}
+
+		const byKind: Record<string, number> = {};
+		for (const [k, v] of this.errorsByKind) {
+			byKind[k] = v;
+		}
+
+		// Resolve live context stats
+		let contextStats: ContextStats | null = null;
+		if (this.contextStateResolver) {
+			try {
+				contextStats = this.contextStateResolver();
+			} catch {
+				// Context extension may not be loaded or state unavailable
+			}
+		}
+
+		// If resolver didn't produce live stats, build from our own counters
+		if (!contextStats && this.contextAutoIndexed > 0) {
+			const successfulQueries =
+				this.contextSearchQueries - this.contextSearchMisses;
+			contextStats = {
+				usagePercent: 0,
+				totalTokens: 0,
+				maxTokens: 0,
+				tokensSaved: 0,
+				compressions:
+					this.contextCompressionsWarm +
+					this.contextCompressionsCold +
+					this.contextCompressionsDelete,
+				compressionsByType: {
+					warm: this.contextCompressionsWarm,
+					cold: this.contextCompressionsCold,
+					delete: this.contextCompressionsDelete,
+				},
+				knowledgeBase: {
+					sources: 0,
+					chunks: 0,
+					bytesIndexed: this.contextBytesDiverted,
+					autoIndexed: this.contextAutoIndexed,
+					pointersCreated: this.contextPointersCreated,
+					searchCalls: this.contextSearchCalls,
+					searchQueries: this.contextSearchQueries,
+					searchMisses: this.contextSearchMisses,
+					avgResultsPerQuery:
+						successfulQueries > 0
+							? Math.round(
+									(this.contextSearchTotalResults / successfulQueries) * 10,
+								) / 10
+							: 0,
+				},
+				bytesDiverted: this.contextBytesDiverted,
+				compressionRatio: 0,
+			};
+		}
+
+		return {
+			session: {
+				startedAt: this.sessionStartedAt,
+				generates: this.generateCount,
+				totalSteps: this.totalSteps,
+			},
+			tokens: {
+				input: this.inputTokens,
+				output: this.outputTokens,
+				total: this.inputTokens + this.outputTokens,
+			},
+			cache: {
+				reads: this.cacheReads,
+				writes: this.cacheWrites,
+				totalInput: this.totalInputForCache,
+				hitRate:
+					this.totalInputForCache > 0
+						? Math.round((this.cacheReads / this.totalInputForCache) * 100) /
+							100
+						: 0,
+			},
+			models: {
+				calls: this.modelCalls,
+				totalDurationMs: this.modelTotalDuration,
+				avgDurationMs:
+					this.modelCalls > 0
+						? Math.round(this.modelTotalDuration / this.modelCalls)
+						: 0,
+			},
+			tools,
+			errors: {
+				total: this.errorTotal,
+				byKind,
+			},
+			context: contextStats,
+		};
+	}
+}

package/src/tools.ts

@@ -0,0 +1,338 @@
+/**
+ * Agent-facing introspection tools.
+ *
+ * These tools are exposed to the model so it can query its own runtime state.
+ * All tools are prefixed with `devtools_` to avoid collisions.
+ */
+
+import { z } from "zod";
+import { Tool } from "@dex-ai/sdk";
+import type {
+	AnyTool,
+	AgentContext,
+	GenerateContext,
+	Extension,
+} from "@dex-ai/sdk";
+import type { Logger, LogLevel } from "./logger";
+import type { Telemetry } from "./telemetry";
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+function getActx(gctx: GenerateContext): AgentContext {
+	return gctx.agent;
+}
+
+function collectAllTools(extensions: ReadonlyArray<Extension>): AnyTool[] {
+	const tools: AnyTool[] = [];
+	for (const ext of extensions) {
+		if (!ext.tools) continue;
+		const list: ReadonlyArray<AnyTool> = Array.isArray(ext.tools)
+			? ext.tools
+			: [ext.tools as AnyTool];
+		for (const t of list) {
+			tools.push(t);
+		}
+	}
+	return tools;
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool factories                                                      */
+/* ------------------------------------------------------------------ */
+
+export function createDevtoolsTools(
+	logger: Logger,
+	telemetry: Telemetry,
+): AnyTool[] {
+	/* ---------------------------------------------------------------- */
+	/* devtools_extensions                                               */
+	/* ---------------------------------------------------------------- */
+	const extensionsTool = Tool.define({
+		name: "devtools_extensions",
+		displayName: "Extensions",
+		access: "read",
+		description:
+			"List all installed extensions with their capabilities (tools, skills, events, init/dispose).",
+		parameters: z.object({}),
+		execute(_input: unknown, gctx: GenerateContext) {
+			const actx = getActx(gctx);
+			const exts = actx.extensions.map((ext) => ({
+				name: ext.name,
+				description: ext.description ?? null,
+				hasTools: ext.tools !== undefined,
+				hasSkills: ext.skills !== undefined,
+				hasEvents: ext.on !== undefined,
+				events: ext.on ? Object.keys(ext.on) : [],
+				hasInit: typeof ext.init === "function",
+				hasDispose: typeof ext.dispose === "function",
+				hasModels: ext.models !== undefined && ext.models.length > 0,
+			}));
+			return { type: "json" as const, value: exts };
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_tools                                                    */
+	/* ---------------------------------------------------------------- */
+	const toolsTool = Tool.define({
+		name: "devtools_tools",
+		displayName: "Tools",
+		access: "read",
+		description:
+			"List all registered tools across all extensions (name, description, parameter summary).",
+		parameters: z.object({}),
+		execute(_input: unknown, gctx: GenerateContext) {
+			const actx = getActx(gctx);
+			const tools = collectAllTools(actx.extensions);
+			const summary = tools.map((t) => ({
+				name: t.name,
+				description: t.description ?? null,
+				hasOutputStream: typeof t.stream === "function",
+			}));
+			return { type: "json" as const, value: summary };
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_config                                                   */
+	/* ---------------------------------------------------------------- */
+	const configTool = Tool.define({
+		name: "devtools_config",
+		displayName: "Config",
+		access: "read",
+		description:
+			"Show the merged agent configuration (provider, model, workspace, session, etc.).",
+		parameters: z.object({}),
+		execute(_input: unknown, gctx: GenerateContext) {
+			const actx = getActx(gctx);
+			const config = actx.state.get("config") ?? null;
+			const workspace = actx.state.get("workspace") ?? null;
+			const session = actx.state.get("session") ?? null;
+
+			return {
+				type: "json" as const,
+				value: {
+					agent: {
+						name: actx.name,
+						provider: actx.providerName,
+						model: actx.modelId,
+					},
+					config,
+					workspace,
+					session,
+				},
+			};
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_telemetry                                                */
+	/* ---------------------------------------------------------------- */
+	const telemetryTool = Tool.define({
+		name: "devtools_telemetry",
+		displayName: "Telemetry",
+		access: "read",
+		description:
+			"Show current session telemetry: token usage, model call performance, tool execution stats, error counts.",
+		parameters: z.object({}),
+		execute() {
+			return { type: "json" as const, value: telemetry.getStats() };
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_logs                                                     */
+	/* ---------------------------------------------------------------- */
+	const logsTool = Tool.define({
+		name: "devtools_logs",
+		displayName: "Logs",
+		access: "read",
+		description:
+			"Query recent agent loop log entries. Filter by level, event pattern, or return the last N entries.",
+		parameters: z.object({
+			level: z
+				.enum(["debug", "info", "warn", "error"])
+				.optional()
+				.describe("Minimum log level to include."),
+			event: z
+				.string()
+				.optional()
+				.describe(
+					"Filter to entries whose event name contains this substring.",
+				),
+			last: z
+				.number()
+				.int()
+				.positive()
+				.optional()
+				.describe("Return only the last N matching entries."),
+		}),
+		execute(input: { level?: LogLevel; event?: string; last?: number }) {
+			const entries = logger.query(input);
+			return { type: "json" as const, value: entries };
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_state                                                    */
+	/* ---------------------------------------------------------------- */
+	const stateTool = Tool.define({
+		name: "devtools_state",
+		displayName: "State",
+		access: "read",
+		description:
+			"Inspect the extension state map. List all keys, or dump the value for a specific key.",
+		parameters: z.object({
+			key: z
+				.string()
+				.optional()
+				.describe(
+					"If provided, dump the value stored at this key. Otherwise list all keys.",
+				),
+		}),
+		execute(input: { key?: string }, gctx: GenerateContext) {
+			const actx = getActx(gctx);
+			if (input.key !== undefined) {
+				let value = actx.state.get(input.key);
+				if (value === undefined) {
+					return {
+						type: "text" as const,
+						value: `No state found for key "${input.key}".`,
+					};
+				}
+				// Resolve thunks — extensions like context store lazy getters
+				if (typeof value === "function") {
+					try {
+						value = value();
+					} catch (err) {
+						return {
+							type: "text" as const,
+							value: `Error resolving state "${input.key}": ${err instanceof Error ? err.message : String(err)}`,
+						};
+					}
+				}
+				if (value === undefined || value === null) {
+					return {
+						type: "text" as const,
+						value: `State "${input.key}" resolved to ${String(value)}.`,
+					};
+				}
+				if (typeof value === "string") {
+					return { type: "text" as const, value };
+				}
+				try {
+					return { type: "json" as const, value };
+				} catch {
+					return { type: "text" as const, value: String(value) };
+				}
+			}
+			// List all keys
+			const keys = [...actx.state.keys()];
+			return { type: "json" as const, value: { keys, count: keys.length } };
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_session                                                  */
+	/* ---------------------------------------------------------------- */
+	const sessionTool = Tool.define({
+		name: "devtools_session",
+		displayName: "Session",
+		access: "read",
+		description:
+			"Show session info: message count, message types breakdown, history size estimate.",
+		parameters: z.object({}),
+		execute(_input: unknown, gctx: GenerateContext) {
+			const actx = getActx(gctx);
+			const messages = actx.messages;
+			const byRole: Record<string, number> = {};
+			let totalContentParts = 0;
+
+			for (const msg of messages) {
+				byRole[msg.role] = (byRole[msg.role] ?? 0) + 1;
+				totalContentParts += msg.content.length;
+			}
+
+			const session = actx.state.get("session") as
+				| { id: string; path: string }
+				| undefined;
+
+			return {
+				type: "json" as const,
+				value: {
+					sessionId: session?.id ?? null,
+					sessionPath: session?.path ?? null,
+					messageCount: messages.length,
+					byRole,
+					totalContentParts,
+					currentStep: gctx.stepCount,
+					maxSteps: gctx.maxSteps,
+					usage: gctx.usage,
+					sessionTokens: actx.tokenCount,
+				},
+			};
+		},
+	});
+
+	/* ---------------------------------------------------------------- */
+	/* devtools_screenshot                                               */
+	/* ---------------------------------------------------------------- */
+	const screenshotTool = Tool.define({
+		name: "devtools_screenshot",
+		displayName: "Screenshot",
+		access: "read",
+		description:
+			"Capture the current terminal screen content as plain text. Returns the exact text visible in the terminal UI, with ANSI formatting stripped.",
+		parameters: z.object({
+			ansi: z
+				.boolean()
+				.optional()
+				.describe(
+					"If true, preserve ANSI color codes in output. Default: false (plain text).",
+				),
+		}),
+		execute(input: { ansi?: boolean }, gctx: GenerateContext) {
+			const actx = getActx(gctx);
+			const frameGetter = actx.state.get("tui:frame");
+			if (!frameGetter || typeof frameGetter !== "function") {
+				return {
+					type: "error-text" as const,
+					value:
+						"Terminal frame not available. The TUI extension may not be loaded.",
+				};
+			}
+
+			const lines: string[] = frameGetter();
+			if (lines.length === 0) {
+				return {
+					type: "text" as const,
+					value: "(empty frame — no content rendered yet)",
+				};
+			}
+
+			if (input.ansi) {
+				return { type: "text" as const, value: lines.join("\n") };
+			}
+
+			// Strip ANSI escape codes for plain text output
+			const plain = lines.map((line) =>
+				// eslint-disable-next-line no-control-regex
+				line.replace(/\x1b\[[0-9;]*m|\x1b\][^\x1b]*\x1b\\/g, ""),
+			);
+			return { type: "text" as const, value: plain.join("\n") };
+		},
+	});
+
+	return [
+		extensionsTool,
+		toolsTool,
+		configTool,
+		telemetryTool,
+		logsTool,
+		stateTool,
+		sessionTool,
+		screenshotTool,
+	];
+}