@nikcli-ai/plugin-context-analysis 0.0.6

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from "@nikcli-ai/plugin";
+/**
+ * Context Analysis
+ *
+ * Tracks message count, estimated token usage, and per-tool call counts
+ * across the current session. Exposes a `context_stats` tool for inspection.
+ *
+ * Options:
+ *   warnAt — emit a warning in tool output when estimated tokens exceed this (default: disabled)
+ */
+export declare const ContextAnalysisPlugin: Plugin;
+declare const _default: {
+    server: Plugin;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,88 @@
+import { tool } from "@nikcli-ai/plugin";
+const stats = {
+    messageCount: 0,
+    estimatedTokens: 0,
+    toolCallCounts: {},
+    sessionStart: Date.now(),
+    lastUpdated: Date.now(),
+};
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Context Analysis
+ *
+ * Tracks message count, estimated token usage, and per-tool call counts
+ * across the current session. Exposes a `context_stats` tool for inspection.
+ *
+ * Options:
+ *   warnAt — emit a warning in tool output when estimated tokens exceed this (default: disabled)
+ */
+export const ContextAnalysisPlugin = async (_input, options) => {
+    const warnAt = options?.warnAt;
+    return {
+        "experimental.chat.messages.transform": async (_input, output) => {
+            const { messages } = output;
+            stats.messageCount = messages.length;
+            stats.lastUpdated = Date.now();
+            let totalChars = 0;
+            const toolCounts = {};
+            for (const msg of messages) {
+                for (const part of msg.parts) {
+                    const p = part;
+                    if (p.type === "text" && typeof p.text === "string") {
+                        totalChars += p.text.length;
+                    }
+                    if (p.type === "tool") {
+                        const toolName = p.tool;
+                        if (toolName) {
+                            toolCounts[toolName] = (toolCounts[toolName] ?? 0) + 1;
+                        }
+                        const state = p.state;
+                        if (state?.status === "completed" && typeof state.output === "string") {
+                            totalChars += state.output.length;
+                        }
+                        if (state?.input) {
+                            totalChars += JSON.stringify(state.input).length;
+                        }
+                    }
+                    if (p.type === "reasoning" && typeof p.text === "string") {
+                        totalChars += p.text.length;
+                    }
+                }
+            }
+            stats.estimatedTokens = estimateTokens(String(totalChars));
+            stats.toolCallCounts = toolCounts;
+        },
+        tool: {
+            context_stats: tool({
+                description: "Show current context usage statistics: message count, estimated tokens, and tool call breakdown.",
+                args: {},
+                async execute() {
+                    const elapsed = Math.floor((Date.now() - stats.sessionStart) / 1000);
+                    const topTools = Object.entries(stats.toolCallCounts)
+                        .sort(([, a], [, b]) => b - a)
+                        .slice(0, 10)
+                        .map(([name, count]) => `  ${name}: ${count}`);
+                    const lines = [
+                        `Context Analysis`,
+                        `  Messages:         ${stats.messageCount}`,
+                        `  Estimated tokens: ~${stats.estimatedTokens.toLocaleString()}`,
+                        `  Session age:      ${elapsed}s`,
+                    ];
+                    if (topTools.length > 0) {
+                        lines.push(`  Top tool calls:`);
+                        lines.push(...topTools);
+                    }
+                    if (warnAt && stats.estimatedTokens > warnAt) {
+                        lines.push(``);
+                        lines.push(`  ⚠ Token estimate (${stats.estimatedTokens.toLocaleString()}) exceeds warning threshold (${warnAt.toLocaleString()})`);
+                        lines.push(`  Consider using dynamic-context-pruning or starting a new session.`);
+                    }
+                    return lines.join("\n");
+                },
+            }),
+        },
+    };
+};
+export default { server: ContextAnalysisPlugin };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@nikcli-ai/plugin-context-analysis",
+  "version": "0.0.6",
+  "type": "module",
+  "license": "MIT",
+  "description": "Token usage analytics and context size tracking",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@tsconfig/node22": "22.0.2",
+    "@types/node": "22.13.9",
+    "typescript": "5.8.2",
+    "@nikcli-ai/plugin": "0.0.6"
+  }
+}