Agent Zero AI framework
Add context window usage indicator
Alessandrof8c96860c20e
diff --git a/helpers/settings.py b/helpers/settings.pyindex 4edd852c5..c22149dee 100644--- a/helpers/settings.py+++ b/helpers/settings.py@@ -171,6 +171,7 @@ UI_CONTROL_VISIBILITY_DEFAULTS = {"projectSelector": {"mobile": True, "desktop": True},"time": {"mobile": False, "desktop": True},"connectionStatus": {"mobile": True, "desktop": True},+ "contextWindowUsage": {"mobile": True, "desktop": True},"rightCanvasRail": {"mobile": True, "desktop": True},}diff --git a/helpers/settings.py.dox.md b/helpers/settings.py.dox.mdindex f943e25ff..1eaddd4a4 100644--- a/helpers/settings.py.dox.md+++ b/helpers/settings.py.dox.md@@ -70,7 +70,7 @@within each `Agent.prepare_prompt()` call.- Explicit reloads also refresh an active prompt snapshot.- `max_consecutive_unusable_responses` defaults to `5` and controls the cost circuit breaker for malformed or repeated main-model outputs.-- `ui_control_visibility` stores validated mobile and desktop visibility flags for the project selector, clock, connection status, and right canvas rail; missing or malformed values fall back per device.+- `ui_control_visibility` stores validated mobile and desktop visibility flags for the project selector, clock, connection status, context-window usage indicator, and right canvas rail; missing or malformed values fall back per device.- The Global default-profile selector lists only globally available profiles.A currently configured unavailable profile remains visible with an explicitunavailable label so settings can round-trip it truthfully, except that thediff --git a/plugins/AGENTS.md b/plugins/AGENTS.mdindex 3e98f0036..ddc1cf8b4 100644--- a/plugins/AGENTS.md+++ b/plugins/AGENTS.md@@ -75,6 +75,7 @@ Direct child DOX files:| [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. || [_chat_naming/AGENTS.md](_chat_naming/AGENTS.md) | Built-in manual and Utility Model-assisted chat naming. || [_commands/AGENTS.md](_commands/AGENTS.md) | Built-in slash command manager, command file discovery, and chat composer slash picker. |+| [_context_window/AGENTS.md](_context_window/AGENTS.md) | Context-window token accounting, API, composer indicator, and visibility control. || [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. || [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. || [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. |diff --git a/plugins/_context_window/AGENTS.md b/plugins/_context_window/AGENTS.mdnew file mode 100644index 000000000..a8feedb35--- /dev/null+++ b/plugins/_context_window/AGENTS.md@@ -0,0 +1,50 @@+# Context Window Plugin DOX++## Purpose++- Own context-window token accounting, the usage API, the composer indicator,+ its popover, and its Interface visibility row.++## Ownership++- `helpers/usage.py` owns per-prompt bucket measurement and reconciliation.+- `extensions/python/` records prompt parts at their source extension points.+- `api/context_window.py` exposes the active chat's token usage and effective+ model limit without returning prompt content.+- `webui/` and `extensions/webui/` own the Alpine store, indicator, popover,+ model-override refresh, and Interface visibility row.++## Local Contracts++- The six used-token buckets are `messages`, `system_tools`, `skills`,+ `mcp_tools`, `system_prompt`, and `extras`.+- Tools, MCP tools, and the available-skills catalog are measured from their+ extensible prompt builders, never inferred from rendered headings.+- Loaded skill instructions are removed from Messages and added to Skills.+- Protocol and prompt extras are reported together as Extras.+- Messages reuse the history record token ledger; independently rendered+ fragments use a bounded, content-addressed, runtime-only cache.+- Bucket totals reconcile to the already-stored prompt token total; the+ unclaimed remainder belongs to System prompt.+- Older chats without a stored breakdown show the explanatory empty state.+- `_model_config` supplies the effective model limit and the+ `model-context-strip-end` WebUI slot; it does not own this feature's state.+- The `contextWindowUsage` Interface setting defaults to visible on mobile and+ desktop.++## Work Guidance++- Keep prompt accounting out of rendered-text heuristics.+- Keep the API response limited to counts needed by the UI.+- Preserve the upward, right-aligned popover geometry used beside the model and+ profile selectors.++## Verification++- Run `conda run -n a0 pytest plugins/_context_window/tests`.+- Smoke-test the indicator, popover, chat switching, post-run refresh, and+ mobile/desktop visibility against the live WebUI.++## Child DOX Index++No child DOX files.diff --git a/plugins/_context_window/README.md b/plugins/_context_window/README.mdnew file mode 100644index 000000000..2f7859f0b--- /dev/null+++ b/plugins/_context_window/README.md@@ -0,0 +1,9 @@+# Context Window++The bundled Context Window plugin adds a compact usage ring beside the chat's+model and agent selectors. Its popover shows token counts and full-window+percentages for Messages, System tools, Skills, MCP tools, System prompt,+Extras, and Free space.++Older chats gain the detailed breakdown after their next model turn. Mobile and+desktop visibility can be changed under **Settings > Interface**.diff --git a/plugins/_context_window/__init__.py b/plugins/_context_window/__init__.pynew file mode 100644index 000000000..8b1378917--- /dev/null+++ b/plugins/_context_window/__init__.py@@ -0,0 +1 @@+diff --git a/plugins/_context_window/api/__init__.py b/plugins/_context_window/api/__init__.pynew file mode 100644index 000000000..8b1378917--- /dev/null+++ b/plugins/_context_window/api/__init__.py@@ -0,0 +1 @@+diff --git a/plugins/_context_window/api/context_window.py b/plugins/_context_window/api/context_window.pynew file mode 100644index 000000000..e42da181d--- /dev/null+++ b/plugins/_context_window/api/context_window.py@@ -0,0 +1,18 @@+from helpers.api import ApiHandler, Input, Output, Request+from plugins._context_window.helpers.usage import usage_snapshot+from plugins._model_config.helpers.model_config import get_chat_model_config+++class ContextWindow(ApiHandler):+ async def process(self, input: Input, request: Request) -> Output:+ context = self.use_context(str(input.get("context") or ""))+ agent = context.streaming_agent or context.agent0+ window = agent.get_data(agent.DATA_NAME_CTX_WINDOW)+ window = window if isinstance(window, dict) else {}+ config = get_chat_model_config(agent)++ return {+ "tokens": max(int(window.get("tokens") or 0), 0),+ "context_window": max(int(config.get("ctx_length") or 0), 0),+ "usage": usage_snapshot(window.get("usage")),+ }diff --git a/plugins/_context_window/extensions/python/_functions/_11_tools_prompt/build_prompt/end/_90_record_context_usage.py b/plugins/_context_window/extensions/python/_functions/_11_tools_prompt/build_prompt/end/_90_record_context_usage.pynew file mode 100644index 000000000..eb1549cbb--- /dev/null+++ b/plugins/_context_window/extensions/python/_functions/_11_tools_prompt/build_prompt/end/_90_record_context_usage.py@@ -0,0 +1,7 @@+from helpers.extension import Extension+from plugins._context_window.helpers.usage import record_prompt+++class RecordSystemToolsUsage(Extension):+ def execute(self, data: dict | None = None, **kwargs):+ record_prompt(self.agent, "system_tools", (data or {}).get("result"))diff --git a/plugins/_context_window/extensions/python/_functions/_12_mcp_prompt/build_prompt/end/_90_record_context_usage.py b/plugins/_context_window/extensions/python/_functions/_12_mcp_prompt/build_prompt/end/_90_record_context_usage.pynew file mode 100644index 000000000..3053de0ca--- /dev/null+++ b/plugins/_context_window/extensions/python/_functions/_12_mcp_prompt/build_prompt/end/_90_record_context_usage.py@@ -0,0 +1,7 @@+from helpers.extension import Extension+from plugins._context_window.helpers.usage import record_prompt+++class RecordMcpToolsUsage(Extension):+ def execute(self, data: dict | None = None, **kwargs):+ record_prompt(self.agent, "mcp_tools", (data or {}).get("result"))diff --git a/plugins/_context_window/extensions/python/_functions/_13_skills_prompt/build_prompt/end/_90_record_context_usage.py b/plugins/_context_window/extensions/python/_functions/_13_skills_prompt/build_prompt/end/_90_record_context_usage.pynew file mode 100644index 000000000..4f6ba837e--- /dev/null+++ b/plugins/_context_window/extensions/python/_functions/_13_skills_prompt/build_prompt/end/_90_record_context_usage.py@@ -0,0 +1,7 @@+from helpers.extension import Extension+from plugins._context_window.helpers.usage import record_prompt+++class RecordSkillsUsage(Extension):+ def execute(self, data: dict | None = None, **kwargs):+ record_prompt(self.agent, "skills", (data or {}).get("result"))diff --git a/plugins/_context_window/extensions/python/_functions/agent/Agent/prepare_prompt/end/_90_store_context_usage.py b/plugins/_context_window/extensions/python/_functions/agent/Agent/prepare_prompt/end/_90_store_context_usage.pynew file mode 100644index 000000000..ea91ab8bc--- /dev/null+++ b/plugins/_context_window/extensions/python/_functions/agent/Agent/prepare_prompt/end/_90_store_context_usage.py@@ -0,0 +1,11 @@+from helpers.extension import Extension+from plugins._context_window.helpers import usage+++class StoreContextUsage(Extension):+ def execute(self, data: dict | None = None, **kwargs):+ payload = data if isinstance(data, dict) else {}+ if payload.get("exception") or not isinstance(payload.get("result"), list):+ usage.discard(self.agent)+ return+ usage.finalize(self.agent)diff --git a/plugins/_context_window/extensions/python/_functions/agent/Agent/prepare_prompt/start/_10_reset_context_usage.py b/plugins/_context_window/extensions/python/_functions/agent/Agent/prepare_prompt/start/_10_reset_context_usage.pynew file mode 100644index 000000000..9d39393d9--- /dev/null+++ b/plugins/_context_window/extensions/python/_functions/agent/Agent/prepare_prompt/start/_10_reset_context_usage.py@@ -0,0 +1,7 @@+from helpers.extension import Extension+from plugins._context_window.helpers import usage+++class ResetContextUsage(Extension):+ def execute(self, **kwargs):+ usage.reset(self.agent)diff --git a/plugins/_context_window/extensions/python/message_loop_prompts_after/_99_capture_context_usage.py b/plugins/_context_window/extensions/python/message_loop_prompts_after/_99_capture_context_usage.pynew file mode 100644index 000000000..8b64b1071--- /dev/null+++ b/plugins/_context_window/extensions/python/message_loop_prompts_after/_99_capture_context_usage.py@@ -0,0 +1,8 @@+from agent import LoopData+from helpers.extension import Extension+from plugins._context_window.helpers.usage import capture_context+++class CaptureContextUsage(Extension):+ def execute(self, loop_data: LoopData | None = None, **kwargs):+ capture_context(self.agent, loop_data)diff --git a/plugins/_context_window/extensions/webui/apply_snapshot_before/refresh-context-window.js b/plugins/_context_window/extensions/webui/apply_snapshot_before/refresh-context-window.jsnew file mode 100644index 000000000..8bba8bb83--- /dev/null+++ b/plugins/_context_window/extensions/webui/apply_snapshot_before/refresh-context-window.js@@ -0,0 +1,24 @@+import { store as contextWindowStore } from "/plugins/_context_window/webui/context-window-store.js";++const OVERRIDE_REVISION_KEY = "_model_config_override_revision";+let lastContextId = "";+let lastRevision = null;++export default async function refreshContextWindow(ctx) {+ const snapshot = ctx?.snapshot;+ const contextId = String(snapshot?.context || "");+ if (!contextId) {+ lastContextId = "";+ lastRevision = null;+ return;+ }++ const contexts = Array.isArray(snapshot?.contexts) ? snapshot.contexts : [];+ const active = contexts.find(item => item?.id === contextId) || null;+ const revision = active?.[OVERRIDE_REVISION_KEY] || null;+ if (contextId === lastContextId && revision === lastRevision) return;++ lastContextId = contextId;+ lastRevision = revision;+ await contextWindowStore.refresh(contextId);+}diff --git a/plugins/_context_window/extensions/webui/interface-controls-end/context-window.html b/plugins/_context_window/extensions/webui/interface-controls-end/context-window.htmlnew file mode 100644index 000000000..c56aed5e8--- /dev/null+++ b/plugins/_context_window/extensions/webui/interface-controls-end/context-window.html@@ -0,0 +1,40 @@+<script type="module">+ import { store } from "/plugins/_context_window/webui/context-window-store.js";+</script>++<div x-data>+ <template x-if="$store.settings.uiVisibility">+ <div class="ui-visibility-row">+ <div class="ui-visibility-control">+ <x-icon aria-hidden="true" name="donut_large"></x-icon>+ <div>+ <div class="field-title">Context window</div>+ <div class="ui-visibility-state" x-text="$store.settings.uiControlVisibilityLabel('contextWindowUsage')"></div>+ </div>+ </div>++ <div class="ui-device-selector" aria-label="Context window visibility">+ <button type="button"+ class="ui-device-button"+ :class="{ 'is-visible': $store.settings.isUiControlVisible('contextWindowUsage', 'mobile') }"+ aria-label="Show context window on mobile"+ :aria-pressed="$store.settings.isUiControlVisible('contextWindowUsage', 'mobile').toString()"+ :title="$store.settings.isUiControlVisible('contextWindowUsage', 'mobile') ? 'Shown on mobile' : 'Hidden on mobile'"+ @click="$store.settings.toggleUiControl('contextWindowUsage', 'mobile')">+ <x-icon aria-hidden="true" name="smartphone"></x-icon>+ <span>Mobile</span>+ </button>+ <button type="button"+ class="ui-device-button"+ :class="{ 'is-visible': $store.settings.isUiControlVisible('contextWindowUsage', 'desktop') }"+ aria-label="Show context window on desktop"+ :aria-pressed="$store.settings.isUiControlVisible('contextWindowUsage', 'desktop').toString()"+ :title="$store.settings.isUiControlVisible('contextWindowUsage', 'desktop') ? 'Shown on desktop' : 'Hidden on desktop'"+ @click="$store.settings.toggleUiControl('contextWindowUsage', 'desktop')">+ <x-icon aria-hidden="true" name="desktop_windows"></x-icon>+ <span>Desktop</span>+ </button>+ </div>+ </div>+ </template>+</div>diff --git a/plugins/_context_window/extensions/webui/model-context-strip-end/context-window.html b/plugins/_context_window/extensions/webui/model-context-strip-end/context-window.htmlnew file mode 100644index 000000000..b7a4f9e6f--- /dev/null+++ b/plugins/_context_window/extensions/webui/model-context-strip-end/context-window.html@@ -0,0 +1,191 @@+<script type="module">+ import { store } from "/plugins/_context_window/webui/context-window-store.js";+</script>++<div x-data>+ <template x-if="$store.contextWindow && $store.preferences.isUiControlVisible('contextWindowUsage')">+ <div class="context-window-anchor"+ x-create="$store.contextWindow.onMount($watch)"+ x-destroy="$store.contextWindow.cleanup()"+ @click.outside="$store.contextWindow.open = false"+ @keydown.escape.window="$store.contextWindow.open = false">+ <button type="button"+ class="context-window-button"+ :aria-expanded="$store.contextWindow.open"+ :aria-label="$store.contextWindow.usage.ariaLabel"+ @click="$store.contextWindow.toggle()">+ <svg viewBox="0 0 36 36" aria-hidden="true">+ <circle class="context-window-ring-track" cx="18" cy="18" r="15.5"></circle>+ <circle class="context-window-ring-value" cx="18" cy="18" r="15.5" pathLength="100"+ :stroke-dasharray="$store.contextWindow.usage.ringDasharray"></circle>+ </svg>+ <span x-text="$store.contextWindow.usage.ringLabel"></span>+ </button>++ <div class="context-window-popover"+ x-show="$store.contextWindow.open"+ x-transition.opacity+ style="display: none;"+ role="dialog"+ aria-label="Context window usage">+ <div class="context-window-header">+ <strong>Context window</strong>+ <span x-text="$store.contextWindow.usage.summary"></span>+ </div>+ <div class="context-window-meter" aria-hidden="true">+ <span :style="$store.contextWindow.usage.meterStyle"></span>+ </div>+ <template x-if="$store.contextWindow.usage.hasBreakdown">+ <div class="context-window-rows">+ <template x-for="row in $store.contextWindow.usage.rows" :key="row.key">+ <div class="context-window-row">+ <span class="context-window-dot" :style="row.dotStyle"></span>+ <span x-text="row.label"></span>+ <span class="context-window-value context-window-tokens" x-text="row.tokensLabel"></span>+ <span class="context-window-value" x-text="row.percentLabel"></span>+ </div>+ </template>+ </div>+ </template>+ <template x-if="$store.contextWindow.usage.missingBreakdown">+ <div class="context-window-empty">Breakdown available after the next message.</div>+ </template>+ </div>+ </div>+ </template>+</div>++<style>+ .context-window-anchor {+ position: static;+ display: flex;+ align-items: center;+ }+ .context-window-button {+ position: relative;+ display: grid;+ place-items: center;+ width: 1.8rem;+ height: 1.8rem;+ padding: 0;+ border: 0;+ border-radius: 50%;+ background: transparent;+ color: var(--color-text);+ cursor: pointer;+ opacity: .82;+ }+ .context-window-button:hover {+ background: var(--color-background-hover);+ opacity: 1;+ }+ .context-window-button svg {+ position: absolute;+ inset: 2px;+ width: calc(100% - 4px);+ height: calc(100% - 4px);+ transform: rotate(-90deg);+ fill: none;+ stroke-width: 3;+ }+ .context-window-ring-track {+ stroke: color-mix(in srgb, var(--color-text) 18%, transparent);+ }+ .context-window-ring-value {+ stroke: var(--color-highlight);+ stroke-linecap: round;+ transition: stroke-dasharray .18s ease;+ }+ .context-window-button > span {+ position: relative;+ z-index: 1;+ font-family: var(--font-family-code);+ font-size: .42rem;+ font-weight: 600;+ letter-spacing: -.03em;+ }+ .context-window-popover {+ position: absolute;+ right: 0;+ bottom: calc(100% + 6px);+ z-index: 1050;+ width: min(19rem, calc(100vw - 2rem));+ padding: .9rem;+ border: 1px solid var(--color-border);+ border-radius: 12px;+ background-color: color-mix(in srgb, var(--color-panel) 90%, black 10%);+ box-shadow: 0 16px 38px rgba(0, 0, 0, .3);+ }+ .context-window-header,+ .context-window-row {+ display: grid;+ align-items: center;+ }+ .context-window-header {+ grid-template-columns: minmax(0, 1fr) auto;+ gap: .75rem;+ font-size: .86rem;+ }+ .context-window-header > span,+ .context-window-value {+ font-family: var(--font-family-code);+ font-variant-numeric: tabular-nums;+ }+ .context-window-header > span {+ color: color-mix(in srgb, var(--color-text) 72%, transparent);+ font-size: .76rem;+ }+ .context-window-meter {+ height: .45rem;+ margin: .85rem 0 .75rem;+ overflow: hidden;+ border-radius: 999px;+ background: color-mix(in srgb, var(--color-text) 9%, transparent);+ }+ .context-window-meter > span {+ display: block;+ height: 100%;+ border-radius: inherit;+ background: var(--color-highlight);+ transition: width .18s ease;+ }+ .context-window-rows {+ display: grid;+ gap: .3rem;+ }+ .context-window-empty {+ padding: .35rem 0 .15rem;+ color: color-mix(in srgb, var(--color-text) 62%, transparent);+ font-size: .8rem;+ }+ .context-window-row {+ grid-template-columns: .55rem minmax(0, 1fr) auto 3rem;+ gap: .5rem;+ min-height: 1.5rem;+ color: color-mix(in srgb, var(--color-text) 78%, transparent);+ font-size: .8rem;+ }+ .context-window-value {+ color: var(--color-text);+ text-align: right;+ }+ .context-window-tokens {+ color: color-mix(in srgb, var(--color-text) 62%, transparent);+ }+ .context-window-dot {+ width: .55rem;+ height: .55rem;+ border-radius: 50%;+ background: var(--color-highlight);+ }+ @media (max-width: 25rem) {+ .context-window-popover {+ right: 1.25rem;+ width: min(17rem, calc(100vw - 3rem));+ }+ }+ .light-mode .context-window-popover {+ background: var(--color-panel);+ box-shadow: 0 4px 14px rgba(0, 0, 0, .12);+ }+</style>diff --git a/plugins/_context_window/helpers/__init__.py b/plugins/_context_window/helpers/__init__.pynew file mode 100644index 000000000..8b1378917--- /dev/null+++ b/plugins/_context_window/helpers/__init__.py@@ -0,0 +1 @@+diff --git a/plugins/_context_window/helpers/usage.py b/plugins/_context_window/helpers/usage.pynew file mode 100644index 000000000..66a9942f0--- /dev/null+++ b/plugins/_context_window/helpers/usage.py@@ -0,0 +1,169 @@+import hashlib+from typing import Any++from helpers import files, history, skills, tokens+++PARTS_KEY = "context_window_usage"+CACHE_KEY = "_context_window_usage_cache"+USAGE_KEYS = (+ "messages",+ "system_tools",+ "skills",+ "mcp_tools",+ "system_prompt",+ "extras",+)+MEASURED_KEYS = tuple(key for key in USAGE_KEYS if key != "system_prompt")+++def reset(agent: Any) -> None:+ params = _temporary_params(agent)+ if params is not None:+ params[PARTS_KEY] = {}+++def discard(agent: Any) -> None:+ params = _temporary_params(agent)+ if params is not None:+ params.pop(PARTS_KEY, None)+++def record_prompt(agent: Any, key: str, prompt: Any) -> None:+ parts = _parts(agent)+ if parts is None or key not in MEASURED_KEYS:+ return+ text = files.remove_code_fences(str(prompt or ""), language="json")+ parts[key] = _cached_tokens(agent, f"prompt:{key}", text)+++def capture_context(agent: Any, loop_data: Any) -> None:+ parts = _parts(agent)+ if parts is None or loop_data is None:+ return++ output = list(getattr(loop_data, "history_output", None) or [])+ skill_output = [message for message in output if skills.skill_instruction_name(message)]+ skill_tokens = _output_tokens(agent, "history_skills", skill_output)+ parts["messages"] = max(_history_tokens(agent, output) - skill_tokens, 0)+ parts["skills"] = parts.get("skills", 0) + skill_tokens++ protocol_values = {+ **getattr(loop_data, "protocol_persistent", {}),+ **getattr(loop_data, "protocol_temporary", {}),+ }+ extras_values = {+ **getattr(loop_data, "extras_persistent", {}),+ **getattr(loop_data, "extras_temporary", {}),+ }+ protocol = agent._build_context_message(+ "agent.context.protocol.md",+ "protocol",+ protocol_values,+ include_empty=False,+ )+ extras = agent._build_context_message(+ "agent.context.extras.md",+ "extras",+ extras_values,+ include_empty=True,+ )+ parts["extras"] = _output_tokens(agent, "extras", protocol + extras)+++def finalize(agent: Any) -> None:+ params = _temporary_params(agent)+ parts = params.pop(PARTS_KEY, None) if params is not None else None+ window = agent.get_data(agent.DATA_NAME_CTX_WINDOW) if agent else None+ if not isinstance(parts, dict) or not isinstance(window, dict):+ return++ total = _non_negative_int(window.get("tokens"))+ usage = {key: _non_negative_int(parts.get(key)) for key in MEASURED_KEYS}+ measured_total = sum(usage.values())+ if measured_total > total and measured_total:+ usage = _scale_to_total(usage, total, measured_total)+ measured_total = total+ usage["system_prompt"] = total - measured_total+ usage = {key: usage.get(key, 0) for key in USAGE_KEYS}++ updated = dict(window)+ updated["usage"] = usage+ agent.set_data(agent.DATA_NAME_CTX_WINDOW, updated)+++def usage_snapshot(value: Any) -> dict[str, int]:+ if not isinstance(value, dict):+ return {}+ return {key: _non_negative_int(value.get(key)) for key in USAGE_KEYS}+++def _parts(agent: Any) -> dict[str, int] | None:+ params = _temporary_params(agent)+ value = params.get(PARTS_KEY) if params is not None else None+ return value if isinstance(value, dict) else None+++def _temporary_params(agent: Any) -> dict[str, Any] | None:+ loop_data = getattr(agent, "loop_data", None)+ params = getattr(loop_data, "params_temporary", None)+ return params if isinstance(params, dict) else None+++def _history_tokens(agent: Any, output: list[history.OutputMessage]) -> int:+ get_tokens = getattr(getattr(agent, "history", None), "get_tokens", None)+ if callable(get_tokens):+ return _non_negative_int(get_tokens())+ return _count_output_tokens(output)+++def _output_tokens(+ agent: Any, cache_key: str, output: list[history.OutputMessage]+) -> int:+ text = history.output_text(output, ai_label="assistant", human_label="user")+ return _cached_tokens(agent, cache_key, text)+++def _count_output_tokens(output: list[history.OutputMessage]) -> int:+ text = history.output_text(output, ai_label="assistant", human_label="user")+ return tokens.approximate_prompt_tokens(text)+++def _cached_tokens(agent: Any, key: str, text: str) -> int:+ cache = _cache(agent)+ digest = hashlib.sha256(text.encode("utf-8")).hexdigest()+ cached = cache.get(key) if cache is not None else None+ if isinstance(cached, tuple) and len(cached) == 2 and cached[0] == digest:+ return _non_negative_int(cached[1])++ count = tokens.approximate_prompt_tokens(text)+ if cache is not None:+ cache[key] = (digest, count)+ return count+++def _cache(agent: Any) -> dict[str, tuple[str, int]] | None:+ data = getattr(agent, "data", None)+ if not isinstance(data, dict):+ return None+ cache = data.get(CACHE_KEY)+ if not isinstance(cache, dict):+ cache = {}+ data[CACHE_KEY] = cache+ return cache+++def _non_negative_int(value: Any) -> int:+ try:+ return max(int(value or 0), 0)+ except (TypeError, ValueError):+ return 0+++def _scale_to_total(values: dict[str, int], total: int, current: int) -> dict[str, int]:+ scaled = {key: value * total // current for key, value in values.items()}+ remainder = total - sum(scaled.values())+ order = sorted(values, key=lambda key: values[key] * total % current, reverse=True)+ for key in order[:remainder]:+ scaled[key] += 1+ return scaleddiff --git a/plugins/_context_window/plugin.yaml b/plugins/_context_window/plugin.yamlnew file mode 100644index 000000000..b9d46289d--- /dev/null+++ b/plugins/_context_window/plugin.yaml@@ -0,0 +1,8 @@+name: _context_window+title: Context Window+description: Shows token usage for the active chat context window.+version: 0.1.0+settings_sections: []+per_project_config: false+per_agent_config: false+always_enabled: truediff --git a/plugins/_context_window/tests/__init__.py b/plugins/_context_window/tests/__init__.pynew file mode 100644index 000000000..8b1378917--- /dev/null+++ b/plugins/_context_window/tests/__init__.py@@ -0,0 +1 @@+diff --git a/plugins/_context_window/tests/test_context_window.py b/plugins/_context_window/tests/test_context_window.pynew file mode 100644index 000000000..01a7e3cf0--- /dev/null+++ b/plugins/_context_window/tests/test_context_window.py@@ -0,0 +1,250 @@+from pathlib import Path+from types import SimpleNamespace++import pytest++from agent import Agent, LoopData+from helpers import extension, history+from plugins._context_window.api.context_window import ContextWindow+from plugins._context_window.helpers import usage+++ROOT = Path(__file__).resolve().parents[3]+++class _Log:+ def set_progress(self, _message: str) -> None:+ pass+++async def test_usage_follows_prompt_sources_and_reconciles_to_total(monkeypatch):+ agent = object.__new__(Agent)+ loop_data = LoopData()+ agent.loop_data = loop_data+ agent.context = SimpleNamespace(log=_Log())+ agent.history = history.History(agent)+ agent.data = {}+ agent.history.add_message(False, "User asks a question.")+ agent.history.add_message(True, "Assistant answers.")+ agent.history.add_message(+ False,+ {+ "tool_name": "skills_tool",+ "tool_result": "Skill instructions without a special heading.",+ "skill_instructions": {+ "name": "test-skill",+ "content_included": True,+ },+ },+ )++ system_parts = {+ "system_prompt": "Main instructions without a special heading.",+ "system_tools": "Tool definitions without a special heading.",+ "mcp_tools": "Remote definitions without a special heading.",+ "skills": "Available skill names without a special heading.",+ }++ async def get_system_prompt(_loop_data):+ for key in ("system_tools", "mcp_tools", "skills"):+ usage.record_prompt(agent, key, system_parts[key])+ return list(system_parts.values())++ def read_prompt(prompt_file: str, **kwargs) -> str:+ if prompt_file == "agent.context.protocol.md":+ return "[PROTOCOL]\n" + kwargs["protocol"]+ if prompt_file == "agent.context.extras.md":+ return "[EXTRAS]\n" + kwargs["extras"]+ raise AssertionError(f"Unexpected prompt: {prompt_file}")++ async def call_extensions(extension_point: str, agent=None, **kwargs):+ if extension_point == "message_loop_prompts_after":+ current = kwargs["loop_data"]+ current.protocol_persistent["project"] = "Project instructions."+ current.extras_temporary["time"] = "Current time."+ usage.capture_context(agent, current)++ agent.get_system_prompt = get_system_prompt+ agent.read_prompt = read_prompt+ monkeypatch.setattr(extension, "call_extensions_async", call_extensions)+ monkeypatch.setattr(history.History, "_get_max_embeds", lambda self: 0)++ usage.reset(agent)+ await Agent.prepare_prompt.__wrapped__(agent, loop_data)+ usage.finalize(agent)++ window = agent.get_data(Agent.DATA_NAME_CTX_WINDOW)+ breakdown = window["usage"]+ assert tuple(breakdown) == usage.USAGE_KEYS+ assert sum(breakdown.values()) == window["tokens"]+ assert all(breakdown[key] > 0 for key in usage.USAGE_KEYS)+ assert usage.PARTS_KEY not in loop_data.params_temporary+++async def test_api_returns_only_counts_and_effective_limit(monkeypatch):+ agent = SimpleNamespace(+ DATA_NAME_CTX_WINDOW="ctx_window",+ get_data=lambda _key: {+ "text": "private prompt",+ "tokens": 120,+ "usage": {"messages": 42},+ },+ )+ handler = object.__new__(ContextWindow)+ handler.use_context = lambda _context_id: SimpleNamespace(+ streaming_agent=None,+ agent0=agent,+ )+ monkeypatch.setattr(+ "plugins._context_window.api.context_window.get_chat_model_config",+ lambda _agent: {"ctx_length": 128_000},+ )++ result = await handler.process({"context": "ctx-1"}, SimpleNamespace())++ assert result == {+ "tokens": 120,+ "context_window": 128_000,+ "usage": {+ "messages": 42,+ "system_tools": 0,+ "skills": 0,+ "mcp_tools": 0,+ "system_prompt": 0,+ "extras": 0,+ },+ }+ assert "text" not in result+++def test_webui_and_accounting_are_plugin_owned():+ model_switcher = (+ ROOT+ / "plugins/_model_config/extensions/webui/chat-input-progress-start/model-switcher.html"+ ).read_text(encoding="utf-8")+ model_store = (ROOT / "plugins/_model_config/webui/switcher-mixin.js").read_text(+ encoding="utf-8"+ )+ component = (+ ROOT+ / "plugins/_context_window/extensions/webui/model-context-strip-end/context-window.html"+ ).read_text(encoding="utf-8")+ context_store = (+ ROOT / "plugins/_context_window/webui/context-window-store.js"+ ).read_text(encoding="utf-8")+ helper = (ROOT / "plugins/_context_window/helpers/usage.py").read_text(+ encoding="utf-8"+ )++ assert 'id="model-context-strip-end"' in model_switcher+ assert "contextWindowUsage" not in model_switcher+ assert "contextUsage" not in model_store+ assert "Context window" in component+ assert "position: static" in component+ assert "width: min(19rem, calc(100vw - 2rem))" in component+ assert "right: 1.25rem" in component+ assert "width: min(17rem, calc(100vw - 3rem))" in component+ assert 'label: "Free space"' in context_store+ assert "Breakdown available after the next message." in component+ assert "startswith(" not in helper+ assert "rpartition(" not in helper+++def test_source_prompt_extensions_are_registered():+ expected = {+ "_functions/agent/Agent/prepare_prompt/start": "ResetContextUsage",+ "_functions/agent/Agent/prepare_prompt/end": "StoreContextUsage",+ "message_loop_prompts_after": "CaptureContextUsage",+ }+ for point, class_name in expected.items():+ classes = extension._get_extension_classes(point) # type: ignore[attr-defined]+ assert any(cls.__name__ == class_name for cls in classes)++ system_prompt_classes = {+ cls.__name__: cls+ for cls in extension._get_extension_classes("system_prompt") # type: ignore[attr-defined]+ }+ for owner, recorder in {+ "ToolsPrompt": "RecordSystemToolsUsage",+ "MCPToolsPrompt": "RecordMcpToolsUsage",+ "SkillsPrompt": "RecordSkillsUsage",+ }.items():+ builder = system_prompt_classes[owner].execute.__globals__["build_prompt"]+ module = builder.__wrapped__.__module__.replace(".", "/")+ point = f"_functions/{module}/build_prompt/end"+ classes = extension._get_extension_classes(point) # type: ignore[attr-defined]+ assert any(cls.__name__ == recorder for cls in classes)+++def test_prompt_fragment_cache_is_bounded_and_content_addressed(monkeypatch):+ calls = []+ agent = SimpleNamespace(data={}, loop_data=LoopData())+ monkeypatch.setattr(+ usage.tokens,+ "approximate_prompt_tokens",+ lambda text: calls.append(text) or len(text),+ )++ usage.reset(agent)+ usage.record_prompt(agent, "system_tools", "same prompt")+ usage.record_prompt(agent, "system_tools", "same prompt")+ usage.record_prompt(agent, "system_tools", "changed prompt")++ assert calls == ["same prompt", "changed prompt"]+ cache = agent.data[usage.CACHE_KEY]+ assert len(cache) == 1+ assert cache["prompt:system_tools"][1] == len("changed prompt")+ assert all(len(value[0]) == 64 for value in cache.values())+++def test_history_ledger_changes_without_invalidating_fragment_cache(monkeypatch):+ calls = []+ history_tokens = 1_000+ agent = SimpleNamespace(+ data={},+ loop_data=LoopData(),+ history=SimpleNamespace(get_tokens=lambda: history_tokens),+ _build_context_message=lambda *args, **kwargs: [],+ )+ skill_message = {+ "ai": False,+ "content": {+ "tool_name": "skills_tool",+ "tool_result": "Loaded skill body.",+ "skill_instructions": {+ "name": "test-skill",+ "content_included": True,+ },+ },+ }+ loop_data = SimpleNamespace(+ history_output=[skill_message],+ protocol_persistent={},+ protocol_temporary={},+ extras_persistent={},+ extras_temporary={},+ )+ monkeypatch.setattr(+ usage.tokens,+ "approximate_prompt_tokens",+ lambda text: calls.append(text) or len(text),+ )++ usage.reset(agent)+ usage.record_prompt(agent, "system_tools", "stable tools")+ usage.capture_context(agent, loop_data)+ first = dict(agent.loop_data.params_temporary[usage.PARTS_KEY])++ history_tokens = 400+ agent.loop_data.params_temporary = {}+ usage.reset(agent)+ usage.record_prompt(agent, "system_tools", "stable tools")+ usage.capture_context(agent, loop_data)+ second = agent.loop_data.params_temporary[usage.PARTS_KEY]++ assert first["messages"] == 1_000 - first["skills"]+ assert second["messages"] == 400 - second["skills"]+ assert calls.count("stable tools") == 1+ assert len(agent.data[usage.CACHE_KEY]) == 3diff --git a/plugins/_context_window/webui/context-window-store.js b/plugins/_context_window/webui/context-window-store.jsnew file mode 100644index 000000000..ad80f6cc0--- /dev/null+++ b/plugins/_context_window/webui/context-window-store.js@@ -0,0 +1,117 @@+import { createStore } from "/js/AlpineStore.js";+import { callJsonApi } from "/js/api.js";+import { store as chatsStore } from "/components/sidebar/chats/chats-store.js";+import { store as preferencesStore } from "/components/sidebar/bottom/preferences/preferences-store.js";++const API_PATH = "/plugins/_context_window/context_window";+const ROWS = [+ { key: "messages", label: "Messages", opacity: 1 },+ { key: "system_tools", label: "System tools", opacity: 0.88 },+ { key: "skills", label: "Skills", opacity: 0.76 },+ { key: "mcp_tools", label: "MCP tools", opacity: 0.64 },+ { key: "system_prompt", label: "System prompt", opacity: 0.52 },+ { key: "extras", label: "Extras", opacity: 0.4 },+];++preferencesStore.registerUiControlVisibility("contextWindowUsage", {+ mobile: true,+ desktop: true,+});++function formatTokens(value) {+ const amount = Math.max(Number(value) || 0, 0);+ for (const [size, suffix] of [[1_000_000, "M"], [1_000, "K"]]) {+ if (amount >= size) return `${(amount / size).toFixed(1).replace(/\.0$/, "")}${suffix}`;+ }+ return String(Math.round(amount));+}++function formatPercent(value) {+ const rounded = Math.round(Math.max(Number(value) || 0, 0) * 10) / 10;+ return `${Number.isInteger(rounded) ? rounded.toFixed(0) : rounded.toFixed(1)}%`;+}++function buildUsage(data = {}) {+ const tokens = Math.max(Number(data.tokens) || 0, 0);+ const contextWindow = Math.max(Number(data.context_window) || 0, 0);+ const breakdown = data.usage && typeof data.usage === "object" ? data.usage : {};+ const percent = contextWindow > 0 ? (tokens / contextWindow) * 100 : 0;+ const rows = ROWS.map(row => {+ const rowTokens = Math.max(Number(breakdown[row.key]) || 0, 0);+ const rowPercent = contextWindow > 0 ? (rowTokens / contextWindow) * 100 : 0;+ return {+ ...row,+ tokensLabel: formatTokens(rowTokens),+ percentLabel: formatPercent(rowPercent),+ dotStyle: `opacity:${row.opacity}`,+ };+ });+ const hasBreakdown = rows.some(row => Number(breakdown[row.key]) > 0);+ if (hasBreakdown) {+ const freeTokens = Math.max(contextWindow - tokens, 0);+ const freePercent = contextWindow > 0 ? (freeTokens / contextWindow) * 100 : 0;+ rows.push({+ key: "free_space",+ label: "Free space",+ tokensLabel: formatTokens(freeTokens),+ percentLabel: formatPercent(freePercent),+ dotStyle: "opacity:0.24",+ });+ }+ const percentLabel = formatPercent(percent);+ return {+ rows: hasBreakdown ? rows : [],+ hasBreakdown,+ missingBreakdown: !hasBreakdown,+ ariaLabel: `Context window ${percentLabel} used`,+ ringLabel: contextWindow ? `${Math.round(percent)}%` : "–",+ ringDasharray: `${Math.min(percent, 100)} 100`,+ summary: `${formatTokens(tokens)}/${contextWindow ? formatTokens(contextWindow) : "–"} (${percentLabel})`,+ meterStyle: `width:${Math.min(percent, 100)}%`,+ };+}++const model = {+ usage: buildUsage(),+ loadSeq: 0,+ open: false,++ get contextId() {+ return chatsStore?.getSelectedChatId?.() || globalThis.getContext?.() || "";+ },++ async onMount(watch) {+ await this.refresh();+ watch("$store.chats.selected", value => this.refresh(value || ""));+ watch("$store.chats.selectedContext?.running", (running, previous) => {+ if (previous && !running) void this.refresh();+ });+ },++ cleanup() {+ this.open = false;+ this.loadSeq += 1;+ },++ toggle() {+ this.open = !this.open;+ if (this.open) void this.refresh();+ },++ async refresh(contextId = this.contextId) {+ const requestSeq = ++this.loadSeq;+ if (!contextId) {+ this.usage = buildUsage();+ return this.usage;+ }+ try {+ const data = await callJsonApi(API_PATH, { context: contextId });+ if (requestSeq === this.loadSeq) this.usage = buildUsage(data);+ } catch (error) {+ if (requestSeq === this.loadSeq) console.error("Context window load failed:", error);+ }+ return this.usage;+ },+};++export const store = createStore("contextWindow", model);diff --git a/plugins/_context_window/webui/thumbnail.webp b/plugins/_context_window/webui/thumbnail.webpnew file mode 100644index 000000000..95f724c84Binary files /dev/null and b/plugins/_context_window/webui/thumbnail.webp differdiff --git a/tests/test_ui_control_visibility.py b/tests/test_ui_control_visibility.pyindex 91b57aa25..6a560503d 100644--- a/tests/test_ui_control_visibility.py+++ b/tests/test_ui_control_visibility.py@@ -18,6 +18,13 @@ def test_ui_controls_have_independent_mobile_and_desktop_visibility() -> None:interface = read("webui/components/settings/agent/interface.html")chat_top = read("webui/components/chat/top-section/chat-top.html")canvas = read("webui/components/canvas/right-canvas.html")+ context_usage = read(+ "plugins/_context_window/extensions/webui/model-context-strip-end/context-window.html"+ )+ context_settings = read(+ "plugins/_context_window/extensions/webui/interface-controls-end/context-window.html"+ )+ context_store = read("plugins/_context_window/webui/context-window-store.js")index = read("webui/index.html")ui_server = read("helpers/ui_server.py")@@ -26,6 +33,8 @@ def test_ui_controls_have_independent_mobile_and_desktop_visibility() -> None:assert control in settings_storeassert "registerUiControlVisibility" in preferences+ assert "contextWindowUsage" in context_store+ assert "contextWindowUsage" in context_settingsassert 'id="interface-controls-end"' in interfaceassert "section-interface" in settings_store@@ -43,6 +52,7 @@ def test_ui_controls_have_independent_mobile_and_desktop_visibility() -> None:assert "isUiControlVisible('time')" in chat_topassert "isUiControlVisible('connectionStatus')" in chat_topassert "isUiControlVisible('projectSelector')" in chat_top+ assert "isUiControlVisible('contextWindowUsage')" in context_usageassert "isUiControlVisible('rightCanvasRail')" in canvas@@ -60,6 +70,7 @@ normalized = settings.normalize_settings({**settings.get_default_settings(),"ui_control_visibility": {"time": {"mobile": True, "desktop": False},+ "contextWindowUsage": {"mobile": False, "desktop": True},"projectSelector": "invalid","unknown": {"mobile": False},},@@ -78,5 +89,6 @@ print(json.dumps({"defaults": defaults, "normalized": normalized}))assert defaults["time"] == {"mobile": False, "desktop": True}assert normalized["time"] == {"mobile": True, "desktop": False}+ assert normalized["contextWindowUsage"] == {"mobile": False, "desktop": True}assert normalized["projectSelector"] == {"mobile": True, "desktop": True}assert "unknown" not in normalized