Upload folder using huggingface_hub (part 5)

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)

plugins/_context_window/extensions/webui/apply_snapshot_before/refresh-context-window.js

@@ -0,0 +1,42 @@
+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;
+let lastGenerationKey = "";
+
+function latestGenerationKey(logs) {
+  if (!Array.isArray(logs)) return "";
+  for (let index = logs.length - 1; index >= 0; index--) {
+    const item = logs[index];
+    if (item?.type !== "agent" || Number(item.agentno || 0) !== 0) continue;
+    return `${item.no ?? ""}:${item.id ?? ""}`;
+  }
+  return "";
+}
+
+export default async function refreshContextWindow(ctx) {
+  const snapshot = ctx?.snapshot;
+  const contextId = String(snapshot?.context || "");
+  if (!contextId) {
+    lastContextId = "";
+    lastRevision = null;
+    lastGenerationKey = "";
+    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;
+  const generationKey = latestGenerationKey(snapshot?.logs);
+  if (
+    contextId === lastContextId
+    && revision === lastRevision
+    && (!generationKey || generationKey === lastGenerationKey)
+  ) return;
+
+  lastContextId = contextId;
+  lastRevision = revision;
+  if (generationKey) lastGenerationKey = generationKey;
+  await contextWindowStore.refresh(contextId);
+}

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>

plugins/_context_window/extensions/webui/model-context-strip-end/context-window.html

@@ -0,0 +1,241 @@
+<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>
+          <div class="context-window-summary">
+            <span class="context-window-summary-tokens" x-text="$store.contextWindow.usage.summaryTokens"></span>
+            <span class="context-window-summary-percent" x-text="$store.contextWindow.usage.summaryPercent"></span>
+          </div>
+        </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 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>
+        <template x-if="$store.contextWindow.usage.provider.hasData">
+          <div class="context-window-provider">
+            <template x-if="$store.contextWindow.usage.provider.price.hasData">
+              <div class="context-window-provider-row context-window-provider-price">
+                <span>Price</span>
+                <span class="context-window-value" x-text="$store.contextWindow.usage.provider.price.label"></span>
+              </div>
+            </template>
+            <template x-if="$store.contextWindow.usage.provider.cache.hasData">
+              <div class="context-window-provider-row">
+                <span>Cache hit</span>
+                <span class="context-window-value" x-text="$store.contextWindow.usage.provider.cache.label"></span>
+              </div>
+            </template>
+            <template x-if="$store.contextWindow.usage.provider.tokens">
+              <div class="context-window-provider-row">
+                <span>Tokens In/Out</span>
+                <span class="context-window-value" x-text="$store.contextWindow.usage.provider.tokens"></span>
+              </div>
+            </template>
+          </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-main);
+    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,
+  .context-window-provider-row {
+    display: grid;
+    align-items: center;
+  }
+  .context-window-header {
+    gap: .4rem;
+    font-size: .86rem;
+  }
+  .context-window-summary,
+  .context-window-value {
+    font-family: var(--font-family-main);
+    font-variant-numeric: tabular-nums;
+  }
+  .context-window-summary {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: .75rem;
+    color: color-mix(in srgb, var(--color-text) 72%, transparent);
+    font-size: .76rem;
+  }
+  .context-window-summary-percent {
+    color: var(--color-text);
+  }
+  .context-window-summary-tokens,
+  .context-window-tokens {
+    font-family: var(--font-family-code);
+  }
+  .context-window-provider {
+    margin-top: .7rem;
+    padding-top: .7rem;
+    border-top: 1px solid var(--color-border);
+  }
+  .context-window-provider-row {
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: .75rem;
+    min-height: 1.35rem;
+    color: color-mix(in srgb, var(--color-text) 72%, transparent);
+    font-size: .76rem;
+  }
+  .context-window-provider-price {
+    margin-bottom: .25rem;
+    color: var(--color-text);
+    font-size: .82rem;
+  }
+  .context-window-provider-price .context-window-value {
+    font-size: 1rem;
+    font-weight: 600;
+  }
+  .context-window-meter {
+    height: .45rem;
+    margin: .4rem 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: 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);
+  }
+  @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>

plugins/_context_window/helpers/__init__.py

@@ -0,0 +1 @@
+

plugins/_context_window/helpers/usage.py

@@ -0,0 +1,278 @@
+import hashlib
+import math
+from typing import Any
+
+from helpers import files, history, skills, tokens
+from helpers.llm_result import result_from_metadata
+
+
+PARTS_KEY = "context_window_usage"
+CACHE_KEY = "_context_window_usage_cache"
+PROVIDER_USAGE_KEY = "context_window_provider_usage"
+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 [])
+    parts["_history_output"] = output
+    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
+
+    history_output = parts.pop("_history_output", None)
+    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 total and measured_total >= total and isinstance(history_output, list):
+        message_output = [
+            message
+            for message in history_output
+            if not skills.skill_instruction_name(message)
+        ]
+        usage["messages"] = _output_tokens(
+            agent, "history_messages", message_output
+        )
+        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 capture_provider_usage(agent: Any, result: Any) -> None:
+    if agent is None or result is None or not hasattr(result, "usage"):
+        return
+
+    snapshot = provider_usage_snapshot(getattr(result, "usage", None))
+    agent.set_data(
+        PROVIDER_USAGE_KEY,
+        snapshot if snapshot else {"available": False},
+    )
+
+
+def latest_provider_usage(agent: Any) -> dict[str, int | float]:
+    data = getattr(agent, "data", None)
+    if isinstance(data, dict) and PROVIDER_USAGE_KEY in data:
+        stored = data.get(PROVIDER_USAGE_KEY)
+        if isinstance(stored, dict) and stored.get("available") is False:
+            return {}
+        return provider_usage_snapshot(stored)
+
+    all_messages = getattr(getattr(agent, "history", None), "all_messages", None)
+    if not callable(all_messages):
+        return {}
+    for message in reversed(all_messages()):
+        if not getattr(message, "ai", False):
+            continue
+        result = result_from_metadata(getattr(message, "metadata", None))
+        if result:
+            return provider_usage_snapshot(result.usage)
+    return {}
+
+
+def provider_usage_snapshot(value: Any) -> dict[str, int | float]:
+    if not isinstance(value, dict):
+        return {}
+
+    input_details = {
+        **_mapping(value.get("prompt_tokens_details")),
+        **_mapping(value.get("input_tokens_details")),
+    }
+    result: dict[str, int | float] = {}
+    fields = {
+        "input_tokens": (value.get("input_tokens"), value.get("prompt_tokens")),
+        "cached_tokens": (
+            input_details.get("cached_tokens"),
+            input_details.get("cache_read_tokens"),
+            value.get("cache_read_input_tokens"),
+            value.get("cached_tokens"),
+        ),
+        "output_tokens": (
+            value.get("output_tokens"),
+            value.get("completion_tokens"),
+        ),
+    }
+    for key, values in fields.items():
+        number = _optional_non_negative_int(*values)
+        if number is not None:
+            result[key] = number
+
+    cost = _optional_non_negative_float(
+        value.get("cost"), value.get("response_cost")
+    )
+    if cost is not None:
+        result["cost"] = cost
+    return result
+
+
+def _parts(agent: Any) -> dict[str, Any] | 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 _mapping(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _optional_non_negative_int(*values: Any) -> int | None:
+    for value in values:
+        if value is None:
+            continue
+        try:
+            return max(int(value), 0)
+        except (TypeError, ValueError):
+            continue
+    return None
+
+
+def _optional_non_negative_float(*values: Any) -> float | None:
+    for value in values:
+        if value is None:
+            continue
+        try:
+            number = float(value)
+        except (TypeError, ValueError):
+            continue
+        if math.isfinite(number):
+            return max(number, 0)
+    return None
+
+
+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 scaled

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: true

plugins/_context_window/tests/__init__.py

@@ -0,0 +1 @@
+

plugins/_context_window/tests/test_context_window.py

@@ -0,0 +1,434 @@
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from langchain_core.messages import HumanMessage, SystemMessage
+
+
+ROOT = Path(__file__).resolve().parents[3]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import models
+from agent import Agent, LoopData
+from helpers import extension, extract_tools, history, litellm_transport
+from helpers.llm_result import LLMResult
+from plugins._context_window.api.context_window import ContextWindow
+from plugins._context_window.helpers import usage
+
+
+class _Log:
+    def set_progress(self, _message: str) -> None:
+        pass
+
+
+@pytest.mark.asyncio
+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
+    assert "history_messages" not in agent.data[usage.CACHE_KEY]
+
+
+@pytest.mark.asyncio
+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,
+        },
+        "provider_usage": {},
+    }
+    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"
+    )
+    refresh_hook = (
+        ROOT
+        / "plugins/_context_window/extensions/webui/apply_snapshot_before/refresh-context-window.js"
+    ).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 "Last model call" not in component
+    assert ">Price<" in component
+    assert ">Cache hit<" in component
+    assert ">Tokens In/Out<" in component
+    assert "context-window-cache-meter" not in component
+    assert "price: {" in context_store
+    assert "hasData: cost !== null" in context_store
+    assert 'label: cost === null ? "" : formatCost(cost)' in context_store
+    assert "usage.provider.price.hasData" in component
+    assert "usage.provider.price.label" in component
+    assert 'value < 0.001 ? "<$0.001"' in context_store
+    assert "maximumSignificantDigits: 3" in context_store
+    assert "border-top: 1px solid var(--color-border)" in component
+    assert " → " in context_store
+    assert "summaryTokens" in context_store
+    assert 'summaryPercent: `${percentLabel} used`' in context_store
+    assert "formatTokens(output)} tok" not in context_store
+    assert "context-window-summary-tokens" in component
+    assert "context-window-summary-percent" in component
+    assert "font-family: var(--font-family-main)" in component
+    assert "<details" not in component
+    assert "Reasoning" not in component
+    assert "Images sent" not in component
+    assert "provider did not split out their token cost" not in context_store
+    assert "cached / input" in context_store
+    assert "Math.round(cachePercent)" in context_store
+    assert "context-window-dot" not in component
+    assert "dotStyle" not in context_store
+    assert "Breakdown available after the next message." in component
+    assert "startswith(" not in helper
+    assert "rpartition(" not in helper
+    assert 'item?.type !== "agent"' in refresh_hook
+    assert "Number(item.agentno || 0) !== 0" in refresh_hook
+    assert "generationKey === lastGenerationKey" in refresh_hook
+
+
+def test_source_prompt_extensions_are_registered():
+    expected = {
+        "_functions/agent/Agent/prepare_prompt/start": "ResetContextUsage",
+        "_functions/agent/Agent/prepare_prompt/end": "StoreContextUsage",
+        "_functions/agent/Agent/call_chat_model_turn/end": "RecordProviderUsage",
+        "_functions/models/LiteLLMChatWrapper/unified_turn/start": "DrainProviderUsage",
+        "_functions/models/LiteLLMChatWrapper/unified_turn/end": "RestoreProviderResponse",
+        "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)
+
+
+@pytest.mark.asyncio
+async def test_chat_stream_drains_terminal_provider_usage(monkeypatch):
+    response = '{"tool_name":"response","tool_args":{"text":"done"}}'
+    chunks = [
+        {"choices": [{"delta": {"content": response}, "message": {}}]},
+        {"choices": [{"delta": {"content": " ignored"}, "message": {}}]},
+        {
+            "choices": [],
+            "usage": {
+                "prompt_tokens": 12_000,
+                "prompt_tokens_details": {"cached_tokens": 9_000},
+                "completion_tokens": 80,
+            },
+            "_hidden_params": {"response_cost": 0.0042},
+        },
+    ]
+    consumed = []
+
+    async def stream():
+        for chunk in chunks:
+            consumed.append(chunk)
+            yield chunk
+
+    async def fake_acompletion(*args, **kwargs):
+        assert kwargs["stream_options"] == {"include_usage": True}
+        return stream()
+
+    async def fake_rate_limiter(*args, **kwargs):
+        return None
+
+    callback_calls = []
+
+    async def response_callback(chunk: str, full: str):
+        callback_calls.append((chunk, full))
+        return full if extract_tools.extract_tool_request(full) else None
+
+    monkeypatch.setattr(litellm_transport, "acompletion", fake_acompletion)
+    monkeypatch.setattr(models, "apply_rate_limiter", fake_rate_limiter)
+    wrapper = models.LiteLLMChatWrapper(
+        model="test-model",
+        provider="openrouter",
+        model_config=None,
+        api_base="https://openrouter.ai/api/v1",
+    )
+
+    result = await wrapper.unified_turn(
+        messages=[
+            SystemMessage(content="stable instructions"),
+            HumanMessage(content="question"),
+        ],
+        response_callback=response_callback,
+        explicit_caching=True,
+    )
+
+    assert consumed == chunks
+    assert callback_calls == [
+        (response, response),
+        (" ignored", response + " ignored"),
+    ]
+    assert result.response == response
+    assert result.output_items[0].type == "message"
+    assert result.usage == {
+        "prompt_tokens": 12_000,
+        "prompt_tokens_details": {"cached_tokens": 9_000},
+        "completion_tokens": 80,
+        "cost": 0.0042,
+    }
+
+
+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]) == 3
+
+
+def test_rendered_history_fallback_preserves_system_prompt_bucket(monkeypatch):
+    data = {}
+    output = [{"ai": False, "content": "short message"}]
+    agent = SimpleNamespace(
+        DATA_NAME_CTX_WINDOW="ctx_window",
+        data=data,
+        loop_data=LoopData(),
+        history=SimpleNamespace(get_tokens=lambda: 10_000),
+        _build_context_message=lambda *args, **kwargs: [],
+        get_data=lambda key: data.get(key),
+        set_data=lambda key, value: data.__setitem__(key, value),
+    )
+    loop_data = SimpleNamespace(
+        history_output=output,
+        protocol_persistent={},
+        protocol_temporary={},
+        extras_persistent={},
+        extras_temporary={},
+    )
+    monkeypatch.setattr(
+        usage.tokens,
+        "approximate_prompt_tokens",
+        lambda text: len(text),
+    )
+
+    usage.reset(agent)
+    usage.capture_context(agent, loop_data)
+    data[agent.DATA_NAME_CTX_WINDOW] = {"tokens": 100}
+    usage.finalize(agent)
+
+    breakdown = data[agent.DATA_NAME_CTX_WINDOW]["usage"]
+    assert breakdown["messages"] == len("user: short message")
+    assert breakdown["system_prompt"] > 0
+    assert sum(breakdown.values()) == 100
+
+
+def test_provider_usage_is_optional():
+    data = {}
+    agent = SimpleNamespace(
+        data=data,
+        history=SimpleNamespace(all_messages=lambda: []),
+        set_data=lambda key, value: data.__setitem__(key, value),
+    )
+    result = LLMResult.from_chat(
+        response="done",
+        usage={
+            "prompt_tokens": 12_000,
+            "prompt_tokens_details": {"cached_tokens": 9_000},
+            "completion_tokens": 80,
+            "cost": 0.0123,
+        },
+    )
+
+    usage.capture_provider_usage(agent, result)
+
+    assert usage.latest_provider_usage(agent) == {
+        "input_tokens": 12_000,
+        "cached_tokens": 9_000,
+        "output_tokens": 80,
+        "cost": 0.0123,
+    }
+
+    usage.capture_provider_usage(agent, LLMResult.from_chat(response="no usage"))
+    assert usage.latest_provider_usage(agent) == {}
+    assert usage.provider_usage_snapshot(
+        {"input_tokens": 100, "cached_tokens": None, "cost": None}
+    ) == {"input_tokens": 100}

plugins/_context_window/webui/context-window-store.js

@@ -0,0 +1,160 @@
+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" },
+  { key: "system_tools", label: "System tools" },
+  { key: "skills", label: "Skills" },
+  { key: "mcp_tools", label: "MCP tools" },
+  { key: "system_prompt", label: "System prompt" },
+  { key: "extras", label: "Extras" },
+];
+const COST_FORMATTER = new Intl.NumberFormat("en-US", {
+  style: "currency",
+  currency: "USD",
+  maximumSignificantDigits: 3,
+});
+
+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 optionalNumber(value, key) {
+  if (!value || !Object.prototype.hasOwnProperty.call(value, key)) return null;
+  const number = Number(value[key]);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+function formatCost(value) {
+  if (value === 0) return "$0";
+  return value < 0.001 ? "<$0.001" : COST_FORMATTER.format(value);
+}
+
+function buildProviderUsage(value = {}) {
+  const input = optionalNumber(value, "input_tokens");
+  const cached = optionalNumber(value, "cached_tokens");
+  const output = optionalNumber(value, "output_tokens");
+  const cost = optionalNumber(value, "cost");
+
+  const tokenSummary = input === null && output === null
+    ? ""
+    : `${input === null ? "–" : formatTokens(input)} → ${output === null ? "–" : formatTokens(output)}`;
+
+  const cachePercent = input > 0 && cached !== null
+    ? Math.min((cached / input) * 100, 100)
+    : null;
+  return {
+    hasData: cost !== null || cachePercent !== null || Boolean(tokenSummary),
+    price: {
+      hasData: cost !== null,
+      label: cost === null ? "" : formatCost(cost),
+    },
+    cache: {
+      hasData: cachePercent !== null,
+      label: cachePercent === null ? "" : `${Math.round(cachePercent)}%`,
+    },
+    tokens: tokenSummary,
+  };
+}
+
+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),
+    };
+  });
+  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),
+    });
+  }
+  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`,
+    summaryTokens: `${formatTokens(tokens)}/${contextWindow ? formatTokens(contextWindow) : "–"} tokens`,
+    summaryPercent: `${percentLabel} used`,
+    meterStyle: `width:${Math.min(percent, 100)}%`,
+    provider: buildProviderUsage(data.provider_usage),
+  };
+}
+
+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);

plugins/_desktop/AGENTS.md

@@ -0,0 +1,33 @@
+# Desktop Plugin DOX
+
+## Purpose
+
+- Own the Agent Zero Linux desktop runtime, Xpra/Xfce session integration, and live desktop surface.
+
+## Ownership
+
+- `helpers/` owns desktop routes, session lifecycle, state, and prompt context.
+- `api/desktop_session.py` owns desktop session API behavior.
+- `hooks.py` owns route registration and plugin lifecycle hooks.
+- `prompts/`, `assets/`, `skills/`, `extensions/`, and `webui/` own desktop context, assets, skill guidance, hooks, and panel UI.
+
+## Local Contracts
+
+- Preserve session startup, cleanup, and route protection for desktop access.
+- Keep the Xpra server, client modules, and GTK introspection runtime present as one compatible stack; Xpra shadow sessions import all three even when users connect only through HTML5.
+- Keep desktop state injected into prompts accurate and bounded.
+- Do not expose desktop routes without the expected auth protections.
+- Keep Desktop host visibility tied to an attached modal or canvas host; modal cleanup may preserve the iframe in keepalive, but must not leave stale modal mode behind.
+- Keep LibreOffice Writer as the default handler for Markdown and plain text files; keep Agent Zero Editor available as a secondary Open With target through the desktop intent bridge.
+
+## Work Guidance
+
+- Coordinate runtime and panel changes so live UI reflects actual desktop session state.
+
+## Verification
+
+- Smoke-test desktop startup, panel connection, route access, and session cleanup after changes.
+
+## Child DOX Index
+
+No child DOX files.

plugins/_desktop/api/desktop_session.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from helpers.api import ApiHandler, Request
+from plugins._desktop.helpers import desktop_session
+from plugins._office.helpers import document_store
+from plugins._office.helpers import libreoffice
+
+
+class DesktopSession(ApiHandler):
+    async def process(self, input: dict, request: Request) -> dict:
+        action = str(input.get("action") or "desktop").lower().strip()
+
+        if action == "status":
+            return desktop_session.collect_desktop_status()
+        if action in {"desktop", "open", "session"}:
+            return self._desktop()
+        if action in {"open_document", "document"}:
+            return self._open_document(input, request)
+        if action in {"save", "desktop_save"}:
+            return self._save(input)
+        if action in {"sync", "desktop_sync", "heartbeat"}:
+            return self._sync(input)
+        if action in {"state", "desktop_state"}:
+            return self._state(input)
+        if action in {"shutdown", "desktop_shutdown"}:
+            return self._shutdown(input)
+        return {"ok": False, "error": f"Unsupported desktop session action: {action}"}
+
+    def _desktop(self) -> dict:
+        desktop = desktop_session.get_manager().ensure_system_desktop()
+        if not desktop.get("available"):
+            return {
+                "ok": False,
+                "error": desktop.get("error") or "Desktop session is unavailable.",
+                "status": desktop.get("status") or {},
+                "desktop": desktop,
+                "libreoffice": libreoffice.collect_status(),
+            }
+        document = {
+            "file_id": desktop_session.SYSTEM_FILE_ID,
+            "path": desktop["path"],
+            "basename": desktop["title"],
+            "title": desktop["title"],
+            "extension": "desktop",
+            "size": 0,
+            "version": 0,
+        }
+        return {
+            "ok": True,
+            "session_id": desktop["session_id"],
+            "desktop_session_id": desktop["session_id"],
+            "file_id": desktop_session.SYSTEM_FILE_ID,
+            "title": desktop["title"],
+            "extension": "desktop",
+            "path": desktop["path"],
+            "text": "",
+            "document": document,
+            "version": 0,
+            "desktop": desktop,
+            "store_session_id": "",
+            "mode": "desktop",
+        }
+
+    def _open_document(self, input: dict, request: Request) -> dict:
+        context_id = str(input.get("ctxid") or input.get("context_id") or "").strip()
+        file_id = str(input.get("file_id") or "").strip()
+        try:
+            doc = (
+                document_store.get_document(file_id)
+                if file_id
+                else document_store.register_document(str(input.get("path") or ""), context_id=context_id)
+            )
+        except Exception as exc:
+            return {"ok": False, "error": str(exc)}
+
+        ext = str(doc.get("extension") or "").lower()
+        if ext in document_store.EDITOR_TEXT_EXTENSIONS:
+            return {
+                "ok": False,
+                "error": "Text documents use the Editor surface.",
+                "requires_editor": True,
+                "document": _public_doc(doc),
+            }
+        if ext not in desktop_session.OFFICIAL_EXTENSIONS:
+            return {"ok": False, "error": f".{ext} documents do not use the Desktop surface."}
+
+        store_session = document_store.create_session(
+            doc["file_id"],
+            user_id=str(input.get("user_id") or "agent-zero-user"),
+            permission="write",
+            origin=self._origin(request),
+        )
+        desktop = desktop_session.get_manager().open(doc, refresh=input.get("refresh") is True)
+        if not desktop.get("available"):
+            document_store.close_session(session_id=store_session["session_id"])
+            return {
+                "ok": False,
+                "error": desktop.get("error") or desktop.get("reason") or "Desktop session is unavailable.",
+                "desktop": desktop,
+                "libreoffice": libreoffice.collect_status(),
+            }
+        return {
+            "ok": True,
+            "session_id": desktop["session_id"],
+            "desktop_session_id": desktop["session_id"],
+            "file_id": doc["file_id"],
+            "title": doc["basename"],
+            "extension": doc["extension"],
+            "path": doc["path"],
+            "text": "",
+            "document": _public_doc(doc),
+            "version": document_store.item_version(doc),
+            "desktop": desktop,
+            "store_session_id": store_session["session_id"],
+            "mode": "edit",
+        }
+
+    def _save(self, input: dict) -> dict:
+        session_id = str(input.get("desktop_session_id") or input.get("session_id") or "").strip()
+        if not session_id:
+            return {"ok": False, "error": "desktop_session_id is required."}
+        return desktop_session.get_manager().save(
+            session_id,
+            file_id=str(input.get("file_id") or ""),
+        )
+
+    def _sync(self, input: dict) -> dict:
+        return desktop_session.get_manager().sync(
+            session_id=str(input.get("desktop_session_id") or input.get("session_id") or ""),
+            file_id=str(input.get("file_id") or ""),
+        )
+
+    def _state(self, input: dict) -> dict:
+        return desktop_session.get_manager().state(
+            include_screenshot=bool(input.get("include_screenshot") is True),
+            context_id=str(input.get("ctxid") or input.get("context_id") or ""),
+        )
+
+    def _shutdown(self, input: dict) -> dict:
+        return desktop_session.get_manager().shutdown_system_desktop(
+            save_first=input.get("save_first") is not False,
+            source=str(input.get("source") or "api"),
+        )
+
+    def _origin(self, request: Request) -> str:
+        origin = request.headers.get("Origin") or request.host_url.rstrip("/")
+        return origin.rstrip("/")
+
+
+def _public_doc(doc: dict) -> dict:
+    return {
+        "file_id": doc["file_id"],
+        "path": document_store.display_path(doc["path"]),
+        "basename": doc["basename"],
+        "title": doc["basename"],
+        "extension": doc["extension"],
+        "size": doc["size"],
+        "version": document_store.item_version(doc),
+        "last_modified": doc["last_modified"],
+    }

plugins/_desktop/assets/desktop/README.md

@@ -0,0 +1,142 @@
+# Agent Zero Desktop
+
+This Desktop is Agent Zero's habitat: a visible, stateful Linux workspace where humans and agents can share files, launch tools, inspect results, and turn reasoning into observable work.
+
+You can choose your harness, but now you and A0 have a habitat.
+
+Here, the model reasons, the environment remembers, the user grants permission, and the work leaves artifacts that can be opened, tested, revised, and trusted. It is a small workshop for the larger idea: agents become more useful when they have a safe world to act in, not only more instructions to carry.
+
+With gratitude to the open-source foundations that make this affordance possible:
+
+- Xpra, for carrying a live Linux desktop through the browser, making this desktop environment usable by AI agents.
+- Kali Linux, for the practical Linux craft and tool culture that make capable workspaces feel natural.
+- LibreOffice, for giving this habitat a serious office bench: documents, spreadsheets, presentations, and decades of open document stewardship.
+- Xfce, for a fast, humane desktop that stays out of the way and lets the work breathe.
+- Jan Tomášek, for creating Agent Zero and making this whole workshop possible.
+
+Agent Zero stands on this craft with respect. Open source is not just code we consume; it is shared affordance, accumulated care, and an invitation to build systems that are powerful without becoming opaque.
+
+## Open the Terminal
+
+Double-click **Terminal** on this Desktop. You will land in the Agent Zero workdir, where agent CLIs can inspect files, edit projects, and run commands inside the Linux environment.
+
+Before installing an agent, make a small safety habit:
+
+```bash
+pwd
+node -v || true
+npm -v || true
+python3 --version || true
+curl --version | head -1 || true
+```
+
+Agent CLIs are powerful. Install from official sources, avoid `sudo npm install -g` unless the project explicitly requires it, and keep API keys in your shell or provider login flow rather than pasting secrets into documents.
+
+## Install Your Favorite Agent
+
+These commands were checked against official docs or project READMEs on 2026-05-02. Package names matter.
+
+### OpenAI Codex
+
+```bash
+npm i -g @openai/codex
+codex
+```
+
+### Claude Code
+
+Recommended native installer:
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+source ~/.bashrc
+claude
+```
+
+NPM alternative:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude
+```
+
+### Gemini CLI
+
+```bash
+npm install -g @google/gemini-cli
+gemini
+```
+
+### Aider
+
+```bash
+curl -LsSf https://aider.chat/install.sh | sh
+source ~/.bashrc
+aider
+```
+
+### OpenCode
+
+```bash
+curl -sL https://opencode.ai/install | bash
+opencode
+```
+
+NPM alternative:
+
+```bash
+npm i -g opencode
+opencode
+```
+
+### Goose
+
+```bash
+curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
+source ~/.bashrc
+goose
+```
+
+### OpenHands CLI
+
+```bash
+python3 -m pip install uv
+uv tool install openhands --python 3.12
+openhands
+```
+
+### Qwen Code
+
+```bash
+npm install -g @qwen-code/qwen-code@latest
+qwen
+```
+
+### Cursor Agent
+
+```bash
+curl https://cursor.com/install -fsS | bash
+source ~/.bashrc
+cursor-agent
+```
+
+### Hermes Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
+source ~/.bashrc
+hermes
+```
+
+### OpenClaw
+
+OpenClaw recommends Node 24, or Node 22.14+.
+
+```bash
+npm install -g openclaw@latest
+openclaw onboard --install-daemon
+```
+
+If in doubt, start with Codex or Claude Code for coding, Aider for a lighter patch-focused loop, Goose or OpenHands for a broader local agent, and Hermes or OpenClaw when you want the agent to grow into more of a persistent runtime working together with Agent Zero.
+
+Official references: [Codex](https://developers.openai.com/codex/cli), [Claude Code](https://code.claude.com/docs/en/getting-started), [Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/get-started/), [Aider](https://aider.chat/docs/install.html), [OpenCode](https://www.opencode.live/), [Goose](https://goose-docs.ai/docs/getting-started/installation/), [OpenHands](https://docs.openhands.dev/openhands/usage/cli/installation), [Qwen Code](https://github.com/QwenLM/qwen-code), [Cursor Agent](https://docs.cursor.com/en/cli/installation), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [OpenClaw](https://github.com/openclaw/openclaw).

plugins/_desktop/extensions/python/message_loop_prompts_after/_55_include_desktop_state.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agent import LoopData
+from helpers.extension import Extension
+from plugins._desktop.helpers import prompt_context
+
+
+class IncludeDesktopState(Extension):
+    async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
+        context_id = str(getattr(getattr(self.agent, "context", None), "id", "") or "")
+        context = prompt_context.build_context(context_id=context_id)
+        if not context:
+            loop_data.extras_temporary.pop("desktop_state", None)
+            return
+
+        loop_data.extras_temporary["desktop_state"] = self.agent.read_prompt(
+            "agent.extras.desktop_state.md",
+            desktop_state=context,
+        ) if self.agent else context

plugins/_desktop/extensions/python/startup_migration/_20_desktop_routes.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from helpers.extension import Extension
+from helpers.print_style import PrintStyle
+from helpers import virtual_desktop_routes
+from plugins._desktop import hooks
+
+
+_startup_preparation_thread: threading.Thread | None = None
+
+
+class DesktopStartup(Extension):
+    def execute(self, **kwargs):
+        virtual_desktop_routes.install_route_hooks()
+        _start_background_runtime_preparation()
+
+
+def _start_background_runtime_preparation() -> threading.Thread:
+    global _startup_preparation_thread
+
+    if _startup_preparation_thread and _startup_preparation_thread.is_alive():
+        return _startup_preparation_thread
+
+    _startup_preparation_thread = threading.Thread(
+        target=_prepare_runtime_safely,
+        name="a0-desktop-runtime-preparation",
+        daemon=True,
+    )
+    _startup_preparation_thread.start()
+    return _startup_preparation_thread
+
+
+def _prepare_runtime_safely() -> None:
+    try:
+        _log_runtime_preparation_result(hooks.cleanup_stale_runtime_state())
+    except Exception as exc:
+        PrintStyle.warning("Desktop runtime preparation failed:", exc)
+
+
+def _log_runtime_preparation_result(result: dict[str, Any]) -> None:
+    if result.get("errors"):
+        PrintStyle.warning("Desktop runtime preparation reported errors:", result["errors"])
+    elif result.get("warnings"):
+        PrintStyle.warning("Desktop runtime preparation reported warnings:", result["warnings"])
+    elif result.get("installed") or result.get("removed") or result.get("migrated"):
+        PrintStyle.info("Desktop runtime prepared:", result)

plugins/_desktop/extensions/webui/right-canvas-panels/desktop-panel.html

@@ -0,0 +1,15 @@
+<div
+  class="right-canvas-surface-panel desktop-canvas-surface"
+  data-surface-id="desktop"
+  :class="{
+    'is-active': $store.rightCanvas?.isSurfaceVisible('desktop'),
+    'is-mounted': $store.rightCanvas?.isSurfaceRendered('desktop')
+  }"
+  :aria-hidden="(!$store.rightCanvas?.isSurfaceVisible('desktop')).toString()"
+  x-effect="(() => {
+    const visible = Boolean($store.rightCanvas?.isSurfaceRendered('desktop'));
+    (globalThis.queueMicrotask || ((callback) => globalThis.setTimeout(callback, 0)))(() => $store.desktop?.setDesktopHostVisible?.(visible));
+  })()"
+>
+  <x-component path="/plugins/_desktop/webui/desktop-panel.html"></x-component>
+</div>

plugins/_desktop/extensions/webui/right-canvas-toolbar-start/desktop-new-menu.html

@@ -0,0 +1,38 @@
+<div
+  class="office-header-actions right-canvas-desktop-actions"
+  x-data="{ open: false }"
+  x-show="$store.rightCanvas?.isSurfaceActive('desktop')"
+  @click.outside="open = false"
+  @keydown.escape.window="open = false"
+  style="display: none;"
+>
+  <button
+    type="button"
+    class="office-header-new-button"
+    aria-haspopup="menu"
+    :aria-expanded="open.toString()"
+    @click.stop="open = !open"
+  >
+    <x-icon aria-hidden="true" name="add"></x-icon>
+    <span>New</span>
+    <x-icon class="office-new-chevron" aria-hidden="true" name="expand_more"></x-icon>
+  </button>
+  <div class="office-new-menu" role="menu" x-show="open" @click.stop style="display: none;">
+    <button type="button" class="office-new-menu-item" role="menuitem" @click="open = false; $store.desktop?.runNewMenuAction('open')">
+      <x-icon aria-hidden="true" name="folder_open"></x-icon>
+      <span>Open</span>
+    </button>
+    <button type="button" class="office-new-menu-item" role="menuitem" @click="open = false; $store.desktop?.runNewMenuAction('writer')">
+      <x-icon aria-hidden="true" name="description"></x-icon>
+      <span>Writer</span>
+    </button>
+    <button type="button" class="office-new-menu-item" role="menuitem" @click="open = false; $store.desktop?.runNewMenuAction('spreadsheet')">
+      <x-icon aria-hidden="true" name="table_chart"></x-icon>
+      <span>Spreadsheet</span>
+    </button>
+    <button type="button" class="office-new-menu-item" role="menuitem" @click="open = false; $store.desktop?.runNewMenuAction('presentation')">
+      <x-icon aria-hidden="true" name="co_present"></x-icon>
+      <span>Presentation</span>
+    </button>
+  </div>
+</div>

plugins/_desktop/extensions/webui/right_canvas_register_surfaces/register-desktop.js

@@ -0,0 +1,49 @@
+import { store as desktopStore } from "/plugins/_desktop/webui/desktop-store.js";
+
+function waitForElement(selector, timeoutMs = 10000) {
+  const found = document.querySelector(selector);
+  if (found) return Promise.resolve(found);
+  return new Promise((resolve) => {
+    const timeout = globalThis.setTimeout(() => {
+      observer.disconnect();
+      resolve(document.querySelector(selector));
+    }, timeoutMs);
+    const observer = new MutationObserver(() => {
+      const element = document.querySelector(selector);
+      if (!element) return;
+      globalThis.clearTimeout(timeout);
+      observer.disconnect();
+      resolve(element);
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  });
+}
+
+export default async function registerDesktopSurface(surfaces) {
+  surfaces.registerSurface({
+    id: "desktop",
+    title: "Desktop",
+    icon: "desktop_windows",
+    order: 20,
+    modalPath: "/plugins/_desktop/webui/main.html",
+    async beginDockHandoff() {
+      desktopStore.beforeDesktopHostHandoff?.();
+    },
+    async finishDockHandoff(payload = {}) {
+      if (payload.opened !== false) desktopStore.afterDesktopHostShown?.({ source: "dock" });
+    },
+    async cancelDockHandoff() {
+      desktopStore.cancelDesktopHostHandoff?.();
+    },
+    async open(payload = {}) {
+      const panel = await waitForElement('[data-surface-id="desktop"] .office-panel');
+      if (!panel) throw new Error("Desktop surface panel did not mount.");
+      await desktopStore.onMount?.(panel, { mode: "canvas" });
+      await desktopStore.onOpen?.(payload);
+      desktopStore.afterDesktopHostShown?.({ source: payload?.source || "canvas" });
+    },
+    async close(payload = {}) {
+      desktopStore.beforeHostHidden?.({ unloadDesktop: payload?.reason === "mobile" });
+    },
+  });
+}

plugins/_desktop/extensions/webui/surfaces_register/register-desktop.js

@@ -0,0 +1,49 @@
+import { store as desktopStore } from "/plugins/_desktop/webui/desktop-store.js";
+
+function waitForElement(selector, timeoutMs = 10000) {
+  const found = document.querySelector(selector);
+  if (found) return Promise.resolve(found);
+  return new Promise((resolve) => {
+    const timeout = globalThis.setTimeout(() => {
+      observer.disconnect();
+      resolve(document.querySelector(selector));
+    }, timeoutMs);
+    const observer = new MutationObserver(() => {
+      const element = document.querySelector(selector);
+      if (!element) return;
+      globalThis.clearTimeout(timeout);
+      observer.disconnect();
+      resolve(element);
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  });
+}
+
+export default async function registerDesktopSurface(surfaces) {
+  surfaces.registerSurface({
+    id: "desktop",
+    title: "Desktop",
+    icon: "desktop_windows",
+    order: 20,
+    modalPath: "/plugins/_desktop/webui/main.html",
+    async beginDockHandoff() {
+      desktopStore.beforeDesktopHostHandoff?.();
+    },
+    async finishDockHandoff(payload = {}) {
+      if (payload.opened !== false) desktopStore.afterDesktopHostShown?.({ source: "dock" });
+    },
+    async cancelDockHandoff() {
+      desktopStore.cancelDesktopHostHandoff?.();
+    },
+    async open(payload = {}) {
+      const panel = await waitForElement('[data-surface-id="desktop"] .office-panel');
+      if (!panel) throw new Error("Desktop surface panel did not mount.");
+      await desktopStore.onMount?.(panel, { mode: "canvas" });
+      await desktopStore.onOpen?.(payload);
+      desktopStore.afterDesktopHostShown?.({ source: payload?.source || "canvas" });
+    },
+    async close(payload = {}) {
+      desktopStore.beforeHostHidden?.({ unloadDesktop: payload?.reason === "mobile" });
+    },
+  });
+}

plugins/_desktop/helpers/desktop_routes.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from helpers.virtual_desktop_routes import VirtualDesktopGateway, install_route_hooks, is_installed
+
+
+__all__ = ["VirtualDesktopGateway", "install_route_hooks", "is_installed"]

plugins/_desktop/helpers/desktop_session.py

@@ -0,0 +1,2601 @@
+from __future__ import annotations
+
+import atexit
+import fcntl
+import hashlib
+import json
+import os
+import shutil
+import socket
+import subprocess
+import threading
+import time
+import uuid
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from helpers import files, virtual_desktop
+from helpers.localization import Localization
+from plugins._desktop.helpers import desktop_state
+from plugins._office.helpers import document_store, libreoffice
+
+
+OFFICIAL_EXTENSIONS = {"odt", "ods", "odp", "docx", "xlsx", "pptx"}
+PLUGIN_NAME = "_desktop"
+SYSTEM_SESSION_ID = "agent-zero-desktop"
+SYSTEM_FILE_ID = "system-desktop"
+SYSTEM_TITLE = "Desktop"
+STATE_DIR = Path(files.get_abs_path("usr", "plugins", PLUGIN_NAME))
+RETIRED_STATE_DIR = Path(files.get_abs_path("usr", PLUGIN_NAME))
+SESSION_DIR = STATE_DIR / "sessions"
+PROFILE_DIR = STATE_DIR / "profiles"
+LEGACY_SESSION_DIRS = (
+    RETIRED_STATE_DIR / "sessions",
+    Path(files.get_abs_path("tmp", "_office", "desktop", "sessions")),
+)
+DISPLAY_BASE = 120
+XPRA_PORT_BASE = 14500
+MAX_SESSIONS = 12
+DEFAULT_SCREEN_WIDTH = virtual_desktop.DEFAULT_WIDTH
+DEFAULT_SCREEN_HEIGHT = virtual_desktop.DEFAULT_HEIGHT
+MAX_SCREEN_WIDTH = virtual_desktop.MAX_WIDTH
+MAX_SCREEN_HEIGHT = virtual_desktop.MAX_HEIGHT
+BLOCKING_DIALOG_TITLES = ("Remote Files", "File Services")
+DISPLAY_START_TIMEOUT_SECONDS = 30.0
+PORT_START_TIMEOUT_SECONDS = 30.0
+STARTUP_GRACE_SECONDS = 45
+RUNTIME_INSTALL_MESSAGE = (
+    "Installing Agent Zero Desktop runtime dependencies. "
+    "This can take a few minutes after an update."
+)
+HIDDEN_XPRA_DESKTOP_ENTRIES = (
+    "xpra.desktop",
+    "xpra-gui.desktop",
+    "xpra-launcher.desktop",
+    "xpra-shadow.desktop",
+    "xpra-start.desktop",
+)
+HIDDEN_XFCE_MENU_ENTRIES = (
+    ("exo-mail-reader.desktop", "Mail Reader"),
+    ("exo-web-browser.desktop", "Web Browser"),
+    ("xfce4-mail-reader.desktop", "Mail Reader"),
+    ("xfce4-web-browser.desktop", "Web Browser"),
+    ("xfce4-session-logout.desktop", "Log Out"),
+    ("xfce4-lock-screen.desktop", "Lock Screen"),
+    ("xflock4.desktop", "Lock Screen"),
+    ("xfce4-switch-user.desktop", "Switch User"),
+)
+DESKTOP_README_SOURCE = Path(__file__).resolve().parents[1] / "assets" / "desktop" / "README.md"
+DESKTOP_FOLDER_LINKS = (
+    ("Projects", ("usr", "projects")),
+    ("Skills", ("usr", "skills")),
+    ("Agents", ("usr", "agents")),
+    ("Downloads", ("usr", "downloads")),
+)
+URL_INTENT_MAX_ITEMS = 50
+URL_INTENT_MAX_LENGTH = 8192
+URL_HANDLER_DESKTOP_ID = "agent-zero-browser.desktop"
+EDITOR_HANDLER_DESKTOP_ID = "agent-zero-editor.desktop"
+WRITER_HANDLER_DESKTOP_ID = "libreoffice-writer.desktop"
+SHUTDOWN_HANDLER_DESKTOP_ID = "agent-zero-shutdown.desktop"
+SHUTDOWN_PANEL_LAUNCHER_ID = SHUTDOWN_HANDLER_DESKTOP_ID
+SHUTDOWN_CONFIRM_SECONDS = 8
+OOR_NS = "http://openoffice.org/2001/registry"
+XS_NS = "http://www.w3.org/2001/XMLSchema"
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+
+
+@dataclass
+class DesktopSession:
+    session_id: str
+    file_id: str
+    extension: str
+    path: str
+    title: str
+    display: int
+    xpra_port: int
+    token: str
+    url: str
+    profile_dir: Path
+    width: int = DEFAULT_SCREEN_WIDTH
+    height: int = DEFAULT_SCREEN_HEIGHT
+    processes: dict[str, subprocess.Popen[Any]] = field(default_factory=dict)
+    process_ids: dict[str, int] = field(default_factory=dict)
+    owns_processes: bool = True
+    started_at: float = field(default_factory=time.time)
+    timezone: str = field(default_factory=lambda: Localization.get().get_timezone())
+
+    def alive(self) -> bool:
+        return _running(self.processes.get("xpra")) or _pid_is_running(self.process_ids.get("xpra", 0))
+
+    def public(self, doc: dict[str, Any] | None = None) -> dict[str, Any]:
+        title = str(doc.get("basename") or "") if doc else self.title
+        path = str(doc.get("path") or "") if doc else self.path
+        extension = str(doc.get("extension") or "") if doc else self.extension
+        file_id = str(doc.get("file_id") or "") if doc else self.file_id
+        return {
+            "available": True,
+            "session_id": self.session_id,
+            "file_id": file_id,
+            "extension": extension,
+            "title": title,
+            "path": document_store.display_path(path),
+            "url": self.url,
+            "token": self.token,
+            "display": f":{self.display}",
+            "desktop_path": virtual_desktop.SESSION_PATH,
+            "width": self.width,
+            "height": self.height,
+            "started_at": self.started_at,
+        }
+
+
+class DesktopSessionManager:
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._sessions: dict[str, DesktopSession] = {}
+
+    def ensure_system_desktop(self) -> dict[str, Any]:
+        try:
+            with self._lock:
+                self._reap_dead_locked()
+                session = self._ensure_system_desktop_locked()
+                return session.public()
+        except Exception as exc:
+            status = collect_desktop_status()
+            return {
+                "available": False,
+                "error": str(exc),
+                "status": status,
+            }
+
+    def open(self, doc: dict[str, Any], *, refresh: bool = False) -> dict[str, Any]:
+        ext = str(doc.get("extension") or "").lower()
+        if ext not in OFFICIAL_EXTENSIONS:
+            return {"available": False, "reason": f".{ext} does not use the LibreOffice desktop surface."}
+
+        with self._lock:
+            self._reap_dead_locked()
+            try:
+                session = self._ensure_system_desktop_locked()
+            except Exception as exc:
+                status = collect_desktop_status()
+                return {
+                    "available": False,
+                    "error": str(exc),
+                    "status": status,
+                }
+            refreshed = False
+            try:
+                if refresh and session.file_id == str(doc.get("file_id") or ""):
+                    refreshed = self._reload_document_locked(session, doc)
+                else:
+                    self._open_document_locked(session, doc)
+            except Exception as exc:
+                return {
+                    "available": False,
+                    "error": str(exc),
+                    "status": collect_desktop_status(),
+                }
+            session.file_id = str(doc["file_id"])
+            session.extension = ext
+            session.path = str(doc["path"])
+            session.title = str(doc["basename"])
+            self._write_manifest(session)
+            public = session.public(doc)
+            public["refreshed"] = refreshed
+            return public
+
+    def refresh_document(self, file_id: str) -> dict[str, Any]:
+        normalized = str(file_id or "").strip()
+        if not normalized:
+            return {"ok": True, "refreshed": False}
+        try:
+            doc = document_store.get_document(normalized)
+        except Exception:
+            return {"ok": False, "refreshed": False, "error": "Document not found."}
+
+        ext = str(doc.get("extension") or "").lower()
+        if ext not in OFFICIAL_EXTENSIONS:
+            return {"ok": True, "refreshed": False}
+
+        with self._lock:
+            self._reap_dead_locked()
+            session = self._find_by_file_id_locked(normalized)
+            if not session:
+                existing = self._load_system_desktop_from_manifest_locked()
+                if existing:
+                    self._sessions[existing.session_id] = existing
+                    self._register_virtual_desktop(existing)
+                    if existing.file_id == normalized:
+                        session = existing
+            if not session:
+                return {"ok": True, "refreshed": False}
+            refreshed = self._reload_document_locked(session, doc)
+            session.file_id = str(doc["file_id"])
+            session.extension = ext
+            session.path = str(doc["path"])
+            session.title = str(doc["basename"])
+            self._write_manifest(session)
+            return {"ok": True, "refreshed": refreshed, "desktop": session.public(doc)}
+
+    def save(self, session_id: str, file_id: str = "") -> dict[str, Any]:
+        with self._lock:
+            session = self.require(session_id)
+            doc = self._document_for_save(session, file_id)
+            if not doc:
+                return {
+                    "ok": True,
+                    "session_id": session.session_id,
+                    "document": None,
+                    "changed": False,
+                }
+
+            xdotool = shutil.which("xdotool")
+            if not xdotool:
+                updated = document_store.register_document(doc["path"])
+                return {
+                    "ok": False,
+                    "error": "xdotool is not installed; use LibreOffice's Save control inside the canvas.",
+                    "document": _public_doc(updated),
+                }
+
+            window_id = self._office_window_id_locked(
+                session,
+                title=str(doc.get("basename") or Path(doc["path"]).name),
+                fallback=False,
+            )
+            if not window_id:
+                return {
+                    "ok": False,
+                    "error": f"LibreOffice window not found for {doc['basename']}.",
+                    "document": _public_doc(doc),
+                }
+
+            result = subprocess.run(
+                [
+                    xdotool,
+                    "windowactivate",
+                    "--sync",
+                    window_id,
+                    "key",
+                    "--clearmodifiers",
+                    "ctrl+s",
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=8,
+                env=self._display_env(session),
+            )
+            time.sleep(0.8)
+            updated = document_store.register_document(doc["path"])
+            if result.returncode != 0:
+                detail = (result.stderr or result.stdout or "").strip()
+                return {
+                    "ok": False,
+                    "error": detail or "LibreOffice desktop save shortcut failed.",
+                    "document": _public_doc(updated),
+                }
+            return {
+                "ok": True,
+                "session_id": session.session_id,
+                "document": _public_doc(updated),
+                "changed": updated.get("sha256") != doc.get("sha256"),
+            }
+
+    def sync(self, session_id: str = "", file_id: str = "") -> dict[str, Any]:
+        session = self.get(session_id) if session_id else self._find_by_file_id(file_id)
+        if not session:
+            return {"ok": False, "error": "LibreOffice desktop session not found."}
+        if not _url_bridge_script_path(session).exists():
+            try:
+                self._prepare_desktop_url_bridge(session)
+                self._refresh_xfce_desktop(session)
+            except Exception:
+                pass
+        url_intents = self.claim_url_intents(session.session_id)
+        shutdown_request = self.claim_shutdown_request(session.session_id)
+        if shutdown_request:
+            return self.shutdown_system_desktop(
+                save_first=True,
+                source=str(shutdown_request.get("source") or "tray"),
+            )
+        doc = self._document_for_save(session, file_id)
+        if not doc:
+            return {
+                "ok": True,
+                "session_id": session.session_id,
+                "desktop": session.public(),
+                "url_intents": url_intents,
+            }
+        updated = document_store.register_document(doc["path"])
+        return {
+            "ok": True,
+            "session_id": session.session_id,
+            "document": _public_doc(updated),
+            "url_intents": url_intents,
+        }
+
+    def state(self, *, include_screenshot: bool = False, context_id: str = "") -> dict[str, Any]:
+        with self._lock:
+            self._reap_dead_locked()
+        return desktop_state.collect_state(
+            include_screenshot=include_screenshot,
+            context_id=context_id,
+        )
+
+    def claim_url_intents(self, session_id: str = SYSTEM_SESSION_ID) -> list[dict[str, Any]]:
+        session = self.get(session_id) or self.get(SYSTEM_SESSION_ID)
+        if not session:
+            return []
+        return _claim_url_intents(session)
+
+    def claim_shutdown_request(self, session_id: str = SYSTEM_SESSION_ID) -> dict[str, Any] | None:
+        session = self.get(session_id) or self.get(SYSTEM_SESSION_ID)
+        if not session:
+            return None
+        return _claim_shutdown_request(session)
+
+    def shutdown_system_desktop(self, *, save_first: bool = True, source: str = "api") -> dict[str, Any]:
+        with self._lock:
+            session = self._sessions.get(SYSTEM_SESSION_ID)
+        if not session:
+            _remove_system_manifest()
+            return {
+                "ok": True,
+                "closed": 0,
+                "session_id": SYSTEM_SESSION_ID,
+                "shutdown": True,
+                "intentional_shutdown": True,
+                "source": source,
+            }
+
+        save_result = None
+        if save_first:
+            try:
+                save_result = self.save(session.session_id)
+            except Exception as exc:
+                save_result = {"ok": False, "error": str(exc)}
+
+        with self._lock:
+            if self._sessions.get(SYSTEM_SESSION_ID) is session:
+                self._sessions.pop(SYSTEM_SESSION_ID, None)
+        virtual_desktop.unregister_session(session.token)
+        self._terminate_session(session, include_rehydrated=True)
+        self._remove_manifest(session.session_id)
+        _clear_shutdown_request(session)
+        return {
+            "ok": True,
+            "closed": 1,
+            "session_id": session.session_id,
+            "shutdown": True,
+            "intentional_shutdown": True,
+            "source": source,
+            "save": save_result,
+        }
+
+    def retarget_document(self, file_id: str, doc: dict[str, Any]) -> dict[str, Any]:
+        session = self._find_by_file_id(file_id)
+        if not session:
+            return {"ok": True, "updated": False}
+        with self._lock:
+            session.path = str(doc["path"])
+            session.title = str(doc["basename"])
+            session.extension = str(doc["extension"])
+            self._write_manifest(session)
+            return {"ok": True, "updated": True, "desktop": session.public(doc)}
+
+    def close(self, session_id: str, save_first: bool = True) -> dict[str, Any]:
+        with self._lock:
+            normalized = str(session_id or "").strip()
+            session = self._sessions.get(normalized)
+        if not session:
+            return {"ok": True, "closed": 0}
+        if session.session_id == SYSTEM_SESSION_ID:
+            save_result = None
+            if save_first:
+                try:
+                    save_result = self.save(session.session_id)
+                except Exception as exc:
+                    save_result = {"ok": False, "error": str(exc)}
+            return {
+                "ok": True,
+                "closed": 0,
+                "session_id": session.session_id,
+                "persistent": True,
+                "save": save_result,
+            }
+
+        save_result = None
+        if save_first:
+            try:
+                save_result = self.save(session.session_id)
+            except Exception as exc:
+                save_result = {"ok": False, "error": str(exc)}
+        with self._lock:
+            self._sessions.pop(session.session_id, None)
+        virtual_desktop.unregister_session(session.token)
+        self._terminate_session(session, include_rehydrated=True)
+        self._remove_manifest(session.session_id)
+        return {"ok": True, "closed": 1, "session_id": session.session_id, "save": save_result}
+
+    def close_file(self, file_id: str) -> int:
+        return 0
+
+    def resize(self, session_id: str, width: int, height: int) -> dict[str, Any]:
+        session = self.get(session_id)
+        if not session:
+            return {"ok": False, "error": "LibreOffice desktop session not found."}
+        is_system_desktop = session.session_id == SYSTEM_SESSION_ID and session.extension == "desktop"
+        if is_system_desktop:
+            width, height = virtual_desktop.normalize_desktop_display_size(width, height)
+        result = virtual_desktop.resize_display(
+            display=session.display,
+            width=width,
+            height=height,
+            max_width=MAX_SCREEN_WIDTH,
+            max_height=MAX_SCREEN_HEIGHT,
+            window_class="" if is_system_desktop else "libreoffice",
+            keys=() if is_system_desktop else ("Escape",),
+            xauthority=self._xauthority(session),
+            home=str(session.profile_dir),
+        )
+        if result.get("ok"):
+            session.width = int(result["width"])
+            session.height = int(result["height"])
+            if not is_system_desktop:
+                self._dismiss_blocking_dialogs(session)
+        return result
+
+    def proxy_for_token(self, token: str) -> tuple[str, int] | None:
+        normalized = str(token or "").strip()
+        with self._lock:
+            session = self._sessions.get(normalized)
+            if not session:
+                session = next((item for item in self._sessions.values() if item.token == normalized), None)
+            if not session or not session.alive():
+                return None
+            return ("127.0.0.1", session.xpra_port)
+
+    def resize_for_token(self, token: str, width: int, height: int) -> dict[str, Any]:
+        normalized = str(token or "").strip()
+        with self._lock:
+            session = self._sessions.get(normalized)
+            if not session:
+                session = next((item for item in self._sessions.values() if item.token == normalized), None)
+        if not session:
+            return {"ok": False, "error": "LibreOffice desktop session not found."}
+        return self.resize(session.session_id, width, height)
+
+    def get(self, session_id: str) -> DesktopSession | None:
+        with self._lock:
+            session = self._sessions.get(str(session_id or "").strip())
+            return session if session and session.alive() else None
+
+    def require(self, session_id: str) -> DesktopSession:
+        session = self.get(session_id)
+        if not session:
+            raise FileNotFoundError(f"LibreOffice desktop session not found: {session_id}")
+        return session
+
+    def shutdown(self) -> None:
+        with self._lock:
+            sessions = list(self._sessions.values())
+            self._sessions.clear()
+        for session in sessions:
+            virtual_desktop.unregister_session(session.token)
+            if session.owns_processes:
+                self._terminate_session(session)
+                self._remove_manifest(session.session_id)
+
+    def sync_timezone(self, timezone: str | None = None) -> dict[str, Any]:
+        target_timezone = str(timezone or Localization.get().get_timezone()).strip()
+        if not target_timezone:
+            target_timezone = Localization.get().get_timezone()
+
+        with self._lock:
+            self._reap_dead_locked()
+            session = self._sessions.get(SYSTEM_SESSION_ID)
+            if not session or not session.alive():
+                return {"ok": True, "restarted": False, "reason": "no_active_desktop"}
+            if session.timezone == target_timezone:
+                return {"ok": True, "restarted": False, "timezone": target_timezone}
+
+            replacement = self._restart_system_desktop_for_timezone_locked(session)
+            return {
+                "ok": True,
+                "restarted": True,
+                "session_id": replacement.session_id,
+                "timezone": replacement.timezone,
+            }
+
+    def _document_for_save(self, session: DesktopSession, file_id: str = "") -> dict[str, Any] | None:
+        normalized = str(file_id or "").strip()
+        if normalized == SYSTEM_FILE_ID:
+            return None
+        if normalized and normalized != SYSTEM_FILE_ID:
+            return document_store.get_document(normalized)
+        if session.file_id and session.file_id != SYSTEM_FILE_ID:
+            try:
+                return document_store.get_document(session.file_id)
+            except Exception:
+                path = Path(session.path)
+                if path.is_file():
+                    return document_store.register_document(path)
+        return None
+
+    def _restart_system_desktop_for_timezone_locked(self, session: DesktopSession) -> DesktopSession:
+        try:
+            doc = self._document_for_save(session, session.file_id)
+        except Exception:
+            doc = None
+        if doc:
+            try:
+                self.save(session.session_id, str(doc.get("file_id") or ""))
+            except Exception:
+                pass
+
+        virtual_desktop.unregister_session(session.token)
+        self._sessions.pop(session.session_id, None)
+        self._terminate_session(session, include_rehydrated=True)
+        self._remove_manifest(session.session_id)
+
+        replacement = self._ensure_system_desktop_locked()
+        if doc:
+            self._open_document_locked(replacement, doc)
+            replacement.file_id = str(doc["file_id"])
+            replacement.extension = str(doc["extension"])
+            replacement.path = str(doc["path"])
+            replacement.title = str(doc["basename"])
+            self._write_manifest(replacement)
+        return replacement
+
+    def _register_virtual_desktop(self, session: DesktopSession) -> None:
+        virtual_desktop.register_session(
+            token=session.token,
+            host="127.0.0.1",
+            port=session.xpra_port,
+            owner="desktop",
+            title=session.title,
+            resize=lambda width, height, session_id=session.session_id: self.resize(session_id, width, height),
+        )
+
+    def _ensure_system_desktop_locked(self) -> DesktopSession:
+        target_timezone = Localization.get().get_timezone()
+        existing = self._sessions.get(SYSTEM_SESSION_ID)
+        if existing and existing.alive():
+            if existing.timezone != target_timezone:
+                return self._restart_system_desktop_for_timezone_locked(existing)
+            self._prepare_desktop_url_bridge(existing)
+            self._refresh_xfce_desktop(existing)
+            return existing
+
+        existing = self._load_system_desktop_from_manifest_locked()
+        if existing:
+            self._sessions[existing.session_id] = existing
+            self._register_virtual_desktop(existing)
+            if existing.timezone != target_timezone:
+                return self._restart_system_desktop_for_timezone_locked(existing)
+            self._prepare_desktop_url_bridge(existing)
+            self._refresh_xfce_desktop(existing)
+            return existing
+
+        status = collect_desktop_status()
+        if not status["healthy"]:
+            raise RuntimeError(status["message"])
+
+        display, xpra_port = self._allocate_endpoint_locked()
+        profile_dir = PROFILE_DIR / SYSTEM_SESSION_ID
+        session = DesktopSession(
+            session_id=SYSTEM_SESSION_ID,
+            file_id=SYSTEM_FILE_ID,
+            extension="desktop",
+            path=str(document_store.document_binary_home()),
+            title=SYSTEM_TITLE,
+            display=display,
+            xpra_port=xpra_port,
+            token=SYSTEM_SESSION_ID,
+            url=_xpra_url(SYSTEM_SESSION_ID),
+            profile_dir=profile_dir,
+            timezone=target_timezone,
+        )
+        try:
+            self._prepare_profile(session)
+            self._prepare_desktop_launchers(session)
+            self._spawn_desktop_locked(session)
+        except Exception:
+            self._terminate_session(session)
+            raise
+        self._sessions[session.session_id] = session
+        self._register_virtual_desktop(session)
+        self._write_manifest(session)
+        return session
+
+    def _load_system_desktop_from_manifest_locked(self) -> DesktopSession | None:
+        manifest = SESSION_DIR / f"{SYSTEM_SESSION_ID}.json"
+        if not manifest.exists():
+            return None
+        try:
+            payload = json.loads(manifest.read_text(encoding="utf-8"))
+            display = int(payload.get("display") or 0)
+            xpra_port = int(payload.get("xpra_port") or 0)
+            process_ids = {
+                str(name): pid
+                for name, value in dict(payload.get("pids") or {}).items()
+                if (pid := _coerce_pid(value))
+            }
+            if not display or not xpra_port:
+                return None
+            if not _pid_is_running(process_ids.get("xpra", 0)):
+                return None
+            if not _port_is_accepting("127.0.0.1", xpra_port):
+                return None
+
+            path = str(payload.get("path") or document_store.document_binary_home())
+            file_id = str(payload.get("file_id") or SYSTEM_FILE_ID)
+            extension = str(payload.get("extension") or "").lower()
+            if not extension:
+                extension = "desktop" if file_id == SYSTEM_FILE_ID else Path(path).suffix.lower().lstrip(".")
+            title = str(payload.get("title") or "")
+            if not title:
+                title = SYSTEM_TITLE if file_id == SYSTEM_FILE_ID else Path(path).name or SYSTEM_TITLE
+            return DesktopSession(
+                session_id=SYSTEM_SESSION_ID,
+                file_id=file_id,
+                extension=extension,
+                path=path,
+                title=title,
+                display=display,
+                xpra_port=xpra_port,
+                token=SYSTEM_SESSION_ID,
+                url=_xpra_url(SYSTEM_SESSION_ID),
+                profile_dir=_state_path_from_retired_root(
+                    Path(payload.get("profile_dir") or PROFILE_DIR / SYSTEM_SESSION_ID)
+                ),
+                width=int(payload.get("width") or DEFAULT_SCREEN_WIDTH),
+                height=int(payload.get("height") or DEFAULT_SCREEN_HEIGHT),
+                process_ids=process_ids,
+                owns_processes=False,
+                started_at=float(payload.get("started_at") or time.time()),
+                timezone=str(payload.get("timezone") or Localization.get().get_timezone()),
+            )
+        except Exception:
+            return None
+
+    def _spawn_desktop_locked(self, session: DesktopSession) -> None:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        SESSION_DIR.mkdir(parents=True, exist_ok=True)
+        session.profile_dir.mkdir(parents=True, exist_ok=True)
+
+        xpra = _require_binary("xpra")
+        xvfb = _require_binary("Xvfb")
+        _require_binary("xfce4-session")
+        _require_binary("dbus-launch")
+        xfce_launcher = self._prepare_xfce_launcher(session)
+
+        session.processes["xvfb"] = subprocess.Popen(
+            _xvfb_command(xvfb, session),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=self._session_env(session),
+        )
+        self._wait_for_display(session)
+        self._set_display_size(session, session.width, session.height)
+        self._prepare_root_window(session)
+        session.processes["xfce"] = subprocess.Popen(
+            [str(xfce_launcher)],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=self._display_env(session),
+        )
+        self._wait_for_xfce(session)
+        session.processes["xpra"] = subprocess.Popen(
+            _xpra_shadow_command(xpra, session),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=self._display_env(session),
+        )
+        _wait_for_port(
+            "127.0.0.1",
+            session.xpra_port,
+            timeout=PORT_START_TIMEOUT_SECONDS,
+            process=session.processes.get("xpra"),
+        )
+        self._refresh_xfce_desktop(session)
+
+    def _restart_xpra_shadow(self, session: DesktopSession) -> None:
+        xpra = _require_binary("xpra")
+        process = session.processes.get("xpra")
+        if process:
+            _terminate_process(process)
+        session.processes["xpra"] = subprocess.Popen(
+            _xpra_shadow_command(xpra, session),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=self._display_env(session),
+        )
+        _wait_for_port(
+            "127.0.0.1",
+            session.xpra_port,
+            timeout=PORT_START_TIMEOUT_SECONDS,
+            process=session.processes.get("xpra"),
+        )
+
+    def _open_document_locked(self, session: DesktopSession, doc: dict[str, Any]) -> None:
+        soffice = libreoffice.find_soffice()
+        if not soffice:
+            raise RuntimeError("LibreOffice is not installed in this runtime.")
+        path = str(doc["path"])
+        self._remove_stale_lock_file(session, path=path)
+        process_key = f"soffice-{doc['file_id']}"
+        session.processes[process_key] = subprocess.Popen(
+            [
+                soffice,
+                "--norestore",
+                "--nofirststartwizard",
+                "--nolockcheck",
+                f"-env:UserInstallation=file://{session.profile_dir}",
+                path,
+            ],
+            cwd=str(Path(path).parent),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=self._display_env(session),
+        )
+        self._fit_office_window(session, process=session.processes[process_key])
+        window_id = self._wait_for_office_window_locked(
+            session,
+            title=str(doc.get("basename") or ""),
+            process=session.processes[process_key],
+        )
+        if not window_id:
+            raise RuntimeError(
+                f"LibreOffice did not show {doc.get('basename') or 'the document'} "
+                f"on desktop :{session.display}.",
+            )
+        self._fit_office_window_id_locked(
+            session,
+            window_id,
+            env=self._display_env(session),
+            keys=("Escape",),
+        )
+
+    def _reload_document_locked(self, session: DesktopSession, doc: dict[str, Any]) -> bool:
+        if self._close_document_window_locked(session, doc):
+            self._open_document_locked(session, doc)
+            return True
+        if self._send_reload_shortcut_locked(session, doc):
+            return True
+        self._open_document_locked(session, doc)
+        return False
+
+    def _close_document_window_locked(self, session: DesktopSession, doc: dict[str, Any]) -> bool:
+        xdotool = shutil.which("xdotool")
+        if not xdotool:
+            return False
+        title = str(doc.get("basename") or Path(str(doc.get("path") or "")).name or "").strip()
+        if not title:
+            return False
+        window_id = self._office_window_id_locked(session, title=title, fallback=False)
+        if not window_id:
+            return False
+        env = self._display_env(session)
+        self._fit_office_window_id_locked(session, window_id, env=env, keys=("Escape",))
+        for command in (
+            [xdotool, "key", "--clearmodifiers", "alt+F4"],
+            [xdotool, "windowclose", window_id],
+        ):
+            try:
+                subprocess.run(
+                    command,
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=3,
+                    env=env,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                continue
+            if self._wait_for_window_closed_locked(session, window_id):
+                return True
+        self._dismiss_blocking_dialogs(session)
+        return self._wait_for_window_closed_locked(session, window_id, timeout_seconds=1.5)
+
+    def _send_reload_shortcut_locked(self, session: DesktopSession, doc: dict[str, Any]) -> bool:
+        xdotool = shutil.which("xdotool")
+        if not xdotool:
+            return False
+        window_id = self._office_window_id_locked(
+            session,
+            title=str(doc.get("basename") or ""),
+        )
+        if not window_id:
+            return False
+        env = self._display_env(session)
+        self._fit_office_window_id_locked(session, window_id, env=env, keys=("Escape",))
+        try:
+            result = subprocess.run(
+                [xdotool, "key", "--clearmodifiers", "ctrl+shift+r"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=4,
+                env=env,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+        time.sleep(0.8)
+        self._dismiss_blocking_dialogs(session)
+        self._fit_office_window_id_locked(session, window_id, env=env, keys=("Escape",))
+        return result.returncode == 0
+
+    def _office_window_id_locked(
+        self,
+        session: DesktopSession,
+        *,
+        title: str = "",
+        fallback: bool = True,
+    ) -> str:
+        xdotool = shutil.which("xdotool")
+        if not xdotool:
+            return ""
+        env = self._display_env(session)
+        title = str(title or "").strip()
+        try:
+            result = subprocess.run(
+                [xdotool, "search", "--onlyvisible", "--class", "libreoffice"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=2,
+                env=env,
+            )
+            window_ids = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+        except (OSError, subprocess.TimeoutExpired):
+            window_ids = []
+        if title:
+            for window_id in reversed(window_ids):
+                try:
+                    result = subprocess.run(
+                        [xdotool, "getwindowname", window_id],
+                        check=False,
+                        capture_output=True,
+                        text=True,
+                        timeout=2,
+                        env=env,
+                    )
+                except (OSError, subprocess.TimeoutExpired):
+                    continue
+                if title.casefold() in result.stdout.strip().casefold():
+                    return window_id
+        if fallback and window_ids:
+            return window_ids[-1]
+        if fallback:
+            try:
+                result = subprocess.run(
+                    [xdotool, "search", "--onlyvisible", "--name", "LibreOffice"],
+                    check=False,
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                    env=env,
+                )
+                window_ids = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+            except (OSError, subprocess.TimeoutExpired):
+                window_ids = []
+            if window_ids:
+                return window_ids[-1]
+        return ""
+
+    def _wait_for_office_window_locked(
+        self,
+        session: DesktopSession,
+        *,
+        title: str = "",
+        process: subprocess.Popen[Any] | None = None,
+        timeout_seconds: float = 20.0,
+    ) -> str:
+        deadline = time.time() + timeout_seconds
+        last_fallback = ""
+        title = str(title or "").strip()
+        while time.time() < deadline:
+            window_id = self._office_window_id_locked(session, title=title, fallback=False)
+            if window_id:
+                return window_id
+            last_fallback = self._office_window_id_locked(session, fallback=True) or last_fallback
+            if last_fallback and not title:
+                return last_fallback
+            if process and process.poll() is not None and last_fallback:
+                return last_fallback
+            time.sleep(0.25)
+        return self._office_window_id_locked(session, title=title, fallback=True) or last_fallback
+
+    def _wait_for_window_closed_locked(
+        self,
+        session: DesktopSession,
+        window_id: str,
+        *,
+        timeout_seconds: float = 6.0,
+    ) -> bool:
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            if not self._window_exists_locked(session, window_id):
+                return True
+            time.sleep(0.2)
+        return not self._window_exists_locked(session, window_id)
+
+    def _window_exists_locked(self, session: DesktopSession, window_id: str) -> bool:
+        xdotool = shutil.which("xdotool")
+        if not xdotool or not window_id:
+            return False
+        try:
+            result = subprocess.run(
+                [xdotool, "getwindowname", str(window_id)],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=2,
+                env=self._display_env(session),
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+        return result.returncode == 0
+
+    def _fit_office_window_id_locked(
+        self,
+        session: DesktopSession,
+        window_id: str,
+        *,
+        env: dict[str, str],
+        keys: tuple[str, ...] = (),
+    ) -> None:
+        xdotool = shutil.which("xdotool")
+        if not xdotool or not window_id:
+            return
+        for command in (
+            [xdotool, "windowactivate", window_id],
+            [
+                xdotool,
+                "windowmove",
+                window_id,
+                "0",
+                "0",
+                "windowsize",
+                window_id,
+                str(session.width),
+                str(session.height),
+            ],
+        ):
+            try:
+                subprocess.run(
+                    command,
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=2,
+                    env=env,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                continue
+        for key in keys:
+            try:
+                subprocess.run(
+                    [xdotool, "key", "--clearmodifiers", key],
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=2,
+                    env=env,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                continue
+
+    def _prepare_profile(self, session: DesktopSession) -> None:
+        user_dir = session.profile_dir / "user"
+        user_dir.mkdir(parents=True, exist_ok=True)
+        registry = user_dir / "registrymodifications.xcu"
+        _write_libreoffice_registry_defaults(registry, document_store.document_home())
+
+    def _prepare_desktop_launchers(self, session: DesktopSession) -> None:
+        soffice = libreoffice.find_soffice()
+        if not soffice:
+            raise RuntimeError("LibreOffice is not installed in this runtime.")
+        workdir_home = document_store.document_home()
+        workdir_home.mkdir(parents=True, exist_ok=True)
+        documents_home = document_store.document_binary_home()
+        documents_home.mkdir(parents=True, exist_ok=True)
+        downloads_home = Path(files.get_abs_path("usr", "downloads"))
+        downloads_home.mkdir(parents=True, exist_ok=True)
+
+        desktop_dir = session.profile_dir / "Desktop"
+        desktop_dir.mkdir(parents=True, exist_ok=True)
+        _install_desktop_readme(desktop_dir)
+        _remove_path_if_owned(desktop_dir / "Browser.desktop")
+        _remove_path_if_owned(desktop_dir / "Files.desktop")
+        config_dir = session.profile_dir / ".config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        _remove_path_if_owned(config_dir / "xfce4" / "panel")
+        data_dir = session.profile_dir / ".local" / "share"
+        data_dir.mkdir(parents=True, exist_ok=True)
+        applications_dir = data_dir / "applications"
+        applications_dir.mkdir(parents=True, exist_ok=True)
+        cache_dir = session.profile_dir / ".cache"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        (config_dir / "user-dirs.dirs").write_text(
+            "\n".join(
+                [
+                    'XDG_DESKTOP_DIR="$HOME/Desktop"',
+                    f'XDG_DOCUMENTS_DIR="{workdir_home}"',
+                    f'XDG_DOWNLOAD_DIR="{downloads_home}"',
+                    f'XDG_TEMPLATES_DIR="{workdir_home}"',
+                    f'XDG_PUBLICSHARE_DIR="{workdir_home}"',
+                    f'XDG_MUSIC_DIR="{workdir_home}"',
+                    f'XDG_PICTURES_DIR="{downloads_home}"',
+                    f'XDG_VIDEOS_DIR="{workdir_home}"',
+                    "",
+                ],
+            ),
+            encoding="utf-8",
+        )
+        xfce_conf_dir = config_dir / "xfce4" / "xfconf" / "xfce-perchannel-xml"
+        xfce_conf_dir.mkdir(parents=True, exist_ok=True)
+        (xfce_conf_dir / "xfce4-desktop.xml").write_text(
+            f"""<?xml version="1.1" encoding="UTF-8"?>
+
+<channel name="xfce4-desktop" version="1.0">
+  <property name="last-settings-migration-version" type="uint" value="1"/>
+  <property name="backdrop" type="empty">
+    <property name="screen0" type="empty">
+      <property name="monitor0" type="empty">
+        <property name="image-path" type="string" value="{_xml_attr(str(downloads_home))}"/>
+      </property>
+    </property>
+  </property>
+  <property name="desktop-icons" type="empty">
+    <property name="style" type="int" value="2"/>
+    <property name="file-icons" type="empty">
+      <property name="show-home" type="bool" value="false"/>
+      <property name="show-filesystem" type="bool" value="false"/>
+      <property name="show-removable" type="bool" value="false"/>
+      <property name="show-trash" type="bool" value="false"/>
+    </property>
+  </property>
+</channel>
+""",
+            encoding="utf-8",
+        )
+        _write_thunar_defaults(xfce_conf_dir / "thunar.xml")
+        self._hide_xpra_desktop_entries(applications_dir)
+        self._hide_xfce_menu_entries(applications_dir)
+        self._prepare_desktop_url_bridge(session)
+
+        base_args = (
+            soffice,
+            "--norestore",
+            "--nofirststartwizard",
+            "--nolockcheck",
+            f"-env:UserInstallation=file://{session.profile_dir}",
+        )
+        office_launchers = (
+            ("LibreOffice Writer", "libreoffice-writer", "--writer", "Office;WordProcessor;"),
+            ("LibreOffice Calc", "libreoffice-calc", "--calc", "Office;Spreadsheet;"),
+            ("LibreOffice Impress", "libreoffice-impress", "--impress", "Office;Presentation;"),
+        )
+        for name, icon, mode, categories in office_launchers:
+            _write_desktop_launcher(
+                desktop_dir / f"{name}.desktop",
+                name=name,
+                exec_line=_desktop_exec(*base_args, mode),
+                icon=icon,
+                categories=categories,
+                try_exec=soffice,
+                working_dir=workdir_home,
+            )
+
+        terminal = shutil.which("xfce4-terminal") or "xfce4-terminal"
+        settings = shutil.which("xfce4-settings-manager") or "xfce4-settings-manager"
+        desktop_apps = (
+            {
+                "filename": "Terminal.desktop",
+                "name": "Terminal",
+                "exec": _desktop_exec(terminal, f"--working-directory={workdir_home}"),
+                "try_exec": terminal,
+                "icon": _desktop_icon(
+                    "/usr/share/icons/hicolor/128x128/apps/org.xfce.terminal.png",
+                    "/usr/share/icons/hicolor/scalable/apps/org.xfce.terminal.svg",
+                    "org.xfce.terminal",
+                    "utilities-terminal",
+                ),
+                "categories": "System;TerminalEmulator;",
+            },
+            {
+                "filename": "Settings.desktop",
+                "name": "Settings",
+                "exec": _desktop_exec(settings),
+                "try_exec": settings,
+                "icon": _desktop_icon(
+                    "/usr/share/icons/hicolor/128x128/apps/org.xfce.settings.manager.png",
+                    "/usr/share/icons/hicolor/scalable/apps/org.xfce.settings.manager.svg",
+                    "org.xfce.settings.manager",
+                    "preferences-system",
+                ),
+                "categories": "Settings;DesktopSettings;",
+            },
+        )
+        for app in desktop_apps:
+            _write_desktop_launcher(
+                desktop_dir / str(app["filename"]),
+                name=str(app["name"]),
+                exec_line=str(app["exec"]),
+                icon=str(app["icon"]),
+                categories=str(app["categories"]),
+                try_exec=str(app["try_exec"]),
+            )
+        _ensure_desktop_folder_link(desktop_dir, "Workdir", workdir_home)
+        for label, target_parts in DESKTOP_FOLDER_LINKS:
+            _ensure_desktop_folder_link(desktop_dir, label, Path(files.get_abs_path(*target_parts)))
+
+        self._trust_desktop_launchers(session, desktop_dir)
+        self._prepare_xfce_panel_config(session)
+        self._prepare_xfce_profile_autostart(session)
+
+    def _prepare_desktop_url_bridge(self, session: DesktopSession) -> None:
+        desktop_dir = session.profile_dir / "Desktop"
+        config_dir = session.profile_dir / ".config"
+        data_dir = session.profile_dir / ".local" / "share"
+        applications_dir = data_dir / "applications"
+        desktop_dir.mkdir(parents=True, exist_ok=True)
+        config_dir.mkdir(parents=True, exist_ok=True)
+        applications_dir.mkdir(parents=True, exist_ok=True)
+
+        browser_bridge = _write_url_bridge_script(session)
+        editor_bridge = _write_editor_bridge_script(session)
+        shutdown_bridge = _write_shutdown_bridge_script(session)
+        helpers_rc = config_dir / "xfce4" / "helpers.rc"
+        helpers_rc.parent.mkdir(parents=True, exist_ok=True)
+        helpers_rc.write_text(
+            "\n".join(
+                [
+                    "TerminalEmulator=xfce4-terminal",
+                    "FileManager=thunar",
+                    "WebBrowser=agent-zero-browser",
+                    "",
+                ],
+            ),
+            encoding="utf-8",
+        )
+        _write_xfce_browser_helper(
+            config_dir / "xfce4" / "helpers" / "agent-zero-browser.desktop",
+            browser_bridge,
+        )
+        _write_mimeapps_defaults(config_dir / "mimeapps.list", URL_HANDLER_DESKTOP_ID, EDITOR_HANDLER_DESKTOP_ID)
+        _write_mimeapps_defaults(
+            data_dir / "applications" / "mimeapps.list",
+            URL_HANDLER_DESKTOP_ID,
+            EDITOR_HANDLER_DESKTOP_ID,
+        )
+        _write_desktop_launcher(
+            applications_dir / URL_HANDLER_DESKTOP_ID,
+            name="Agent Zero Browser",
+            exec_line=_desktop_exec(browser_bridge, "%U"),
+            icon="web-browser",
+            categories="Network;WebBrowser;",
+            try_exec=str(browser_bridge),
+            mime_types=_url_handler_mime_types(),
+            no_display=True,
+        )
+        _write_desktop_launcher(
+            applications_dir / EDITOR_HANDLER_DESKTOP_ID,
+            name="Agent Zero Editor",
+            exec_line=_desktop_exec(editor_bridge, "%F"),
+            icon="accessories-text-editor",
+            categories="Utility;TextEditor;",
+            try_exec=str(editor_bridge),
+            mime_types=_editor_text_handler_mime_types(),
+        )
+        _write_desktop_launcher(
+            applications_dir / SHUTDOWN_HANDLER_DESKTOP_ID,
+            name="Shutdown Desktop",
+            exec_line=_desktop_exec(shutdown_bridge),
+            icon="system-shutdown",
+            categories="System;",
+            try_exec=str(shutdown_bridge),
+            no_display=True,
+        )
+        _write_desktop_launcher(
+            config_dir / "xfce4" / "panel" / "launcher-9" / SHUTDOWN_HANDLER_DESKTOP_ID,
+            name="Shutdown Desktop",
+            exec_line=_desktop_exec(shutdown_bridge),
+            icon="system-shutdown",
+            categories="System;",
+            try_exec=str(shutdown_bridge),
+        )
+        _write_desktop_launcher(
+            desktop_dir / "Browser.desktop",
+            name="Browser",
+            exec_line=_desktop_exec(browser_bridge),
+            icon="web-browser",
+            categories="Network;WebBrowser;",
+            try_exec=str(browser_bridge),
+        )
+        _write_desktop_launcher(
+            desktop_dir / "Editor.desktop",
+            name="Editor",
+            exec_line=_desktop_exec(editor_bridge),
+            icon="accessories-text-editor",
+            categories="Utility;TextEditor;",
+            try_exec=str(editor_bridge),
+        )
+        self._trust_desktop_launchers(session, desktop_dir)
+
+    def _hide_xpra_desktop_entries(self, applications_dir: Path) -> None:
+        for filename in HIDDEN_XPRA_DESKTOP_ENTRIES:
+            _write_hidden_application_entry(applications_dir / filename, "Xpra")
+
+    def _hide_xfce_menu_entries(self, applications_dir: Path) -> None:
+        for filename, name in HIDDEN_XFCE_MENU_ENTRIES:
+            _write_hidden_application_entry(applications_dir / filename, name)
+
+    def _prepare_xfce_panel_config(self, session: DesktopSession) -> None:
+        panel_xml = (
+            session.profile_dir
+            / ".config"
+            / "xfce4"
+            / "xfconf"
+            / "xfce-perchannel-xml"
+            / "xfce4-panel.xml"
+        )
+        panel_xml.parent.mkdir(parents=True, exist_ok=True)
+
+        root = ET.Element("channel", {"name": "xfce4-panel", "version": "1.0"})
+        ET.SubElement(root, "property", {"name": "configver", "type": "int", "value": "2"})
+
+        panels = ET.SubElement(root, "property", {"name": "panels", "type": "array"})
+        ET.SubElement(panels, "value", {"type": "int", "value": "1"})
+        panel = ET.SubElement(panels, "property", {"name": "panel-1", "type": "empty"})
+        for name, prop_type, value in (
+            ("position", "string", "p=6;x=0;y=0"),
+            ("length", "uint", "100"),
+            ("position-locked", "bool", "true"),
+            ("size", "uint", "24"),
+            ("mode", "uint", "0"),
+            ("autohide-behavior", "uint", "0"),
+            ("disable-struts", "bool", "false"),
+            ("nrows", "uint", "1"),
+        ):
+            ET.SubElement(panel, "property", {"name": name, "type": prop_type, "value": value})
+        plugin_ids = ET.SubElement(panel, "property", {"name": "plugin-ids", "type": "array"})
+        for plugin_id in ("1", "2", "3", "4", "5", "6", "7", "8", "9"):
+            ET.SubElement(plugin_ids, "value", {"type": "int", "value": plugin_id})
+
+        plugins = ET.SubElement(root, "property", {"name": "plugins", "type": "empty"})
+        ET.SubElement(plugins, "property", {"name": "plugin-1", "type": "string", "value": "applicationsmenu"})
+        ET.SubElement(plugins, "property", {"name": "plugin-2", "type": "string", "value": "tasklist"})
+        tasklist = _xfce_property(plugins, "plugin-2", "string", "tasklist")
+        ET.SubElement(tasklist, "property", {"name": "flat-buttons", "type": "bool", "value": "true"})
+        ET.SubElement(tasklist, "property", {"name": "show-handle", "type": "bool", "value": "false"})
+        ET.SubElement(tasklist, "property", {"name": "show-labels", "type": "bool", "value": "true"})
+        separator = ET.SubElement(plugins, "property", {"name": "plugin-3", "type": "string", "value": "separator"})
+        ET.SubElement(separator, "property", {"name": "expand", "type": "bool", "value": "true"})
+        ET.SubElement(separator, "property", {"name": "style", "type": "uint", "value": "0"})
+        ET.SubElement(plugins, "property", {"name": "plugin-4", "type": "string", "value": "pager"})
+        ET.SubElement(plugins, "property", {"name": "plugin-5", "type": "string", "value": "systray"})
+        ET.SubElement(plugins, "property", {"name": "plugin-6", "type": "string", "value": "separator"})
+        ET.SubElement(plugins, "property", {"name": "plugin-7", "type": "string", "value": "clock"})
+        ET.SubElement(plugins, "property", {"name": "plugin-8", "type": "string", "value": "separator"})
+        shutdown = ET.SubElement(plugins, "property", {"name": "plugin-9", "type": "string", "value": "launcher"})
+        shutdown_items = ET.SubElement(shutdown, "property", {"name": "items", "type": "array"})
+        ET.SubElement(shutdown_items, "value", {"type": "string", "value": SHUTDOWN_PANEL_LAUNCHER_ID})
+
+        tree = ET.ElementTree(root)
+        try:
+            ET.indent(tree, space="  ")
+        except AttributeError:
+            pass
+        tree.write(panel_xml, encoding="utf-8", xml_declaration=True)
+
+    def _prepare_xfce_profile_autostart(self, session: DesktopSession) -> None:
+        script = session.profile_dir / "prepare-xfce-profile.sh"
+        script.write_text(
+            """#!/bin/sh
+set -eu
+export HOME="${HOME:-%s}"
+export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
+export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
+export XDG_CONFIG_DIRS="/etc/xdg${XDG_CONFIG_DIRS:+:$XDG_CONFIG_DIRS}"
+export XDG_DATA_DIRS="/usr/local/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS}"
+export XDG_CURRENT_DESKTOP="${XDG_CURRENT_DESKTOP:-XFCE}"
+mkdir -p "$HOME/Desktop" "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_CACHE_HOME"
+if command -v xfconf-query >/dev/null 2>&1; then
+  xfconf-query -c thunar -p /last-show-hidden -n -t bool -s true >/dev/null 2>&1 || true
+  xfconf-query -c xfce4-desktop -p /desktop-icons/style -n -t int -s 2 >/dev/null 2>&1 || true
+  xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-home -n -t bool -s false >/dev/null 2>&1 || true
+  xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-filesystem -n -t bool -s false >/dev/null 2>&1 || true
+  xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-removable -n -t bool -s false >/dev/null 2>&1 || true
+  xfconf-query -c xfce4-desktop -p /desktop-icons/file-icons/show-trash -n -t bool -s false >/dev/null 2>&1 || true
+fi
+for launcher in "$HOME"/Desktop/*.desktop; do
+  [ -f "$launcher" ] || continue
+  chmod +x "$launcher" 2>/dev/null || true
+  if command -v gio >/dev/null 2>&1; then
+    checksum="$(sha256sum "$launcher" 2>/dev/null | cut -d " " -f 1)"
+    gio set "$launcher" metadata::trusted true >/dev/null 2>&1 || true
+    if [ -n "$checksum" ]; then
+      gio set -t string "$launcher" metadata::xfce-exe-checksum "$checksum" >/dev/null 2>&1 || true
+    fi
+  fi
+done
+if command -v xfdesktop >/dev/null 2>&1; then
+  timeout 4 xfdesktop --reload >/dev/null 2>&1 || true
+fi
+""" % str(session.profile_dir),
+            encoding="utf-8",
+        )
+        try:
+            script.chmod(0o700)
+        except OSError:
+            pass
+
+        autostart_dir = session.profile_dir / ".config" / "autostart"
+        autostart_dir.mkdir(parents=True, exist_ok=True)
+        autostart = autostart_dir / "agent-zero-desktop.desktop"
+        autostart.write_text(
+            "\n".join(
+                [
+                    "[Desktop Entry]",
+                    "Type=Application",
+                    "Name=Agent Zero desktop profile",
+                    f"Exec={script}",
+                    "Terminal=false",
+                    "OnlyShowIn=XFCE;",
+                    "X-GNOME-Autostart-enabled=true",
+                    "",
+                ],
+            ),
+            encoding="utf-8",
+        )
+
+    def _prepare_xfce_launcher(self, session: DesktopSession) -> Path:
+        launcher = session.profile_dir / "start-xfce.sh"
+        launcher.write_text(
+            "\n".join(
+                [
+                    "#!/bin/sh",
+                    'export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"',
+                    'export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"',
+                    'export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"',
+                    'export XDG_CONFIG_DIRS="/etc/xdg${XDG_CONFIG_DIRS:+:$XDG_CONFIG_DIRS}"',
+                    'export XDG_DATA_DIRS="/usr/local/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS}"',
+                    'export XDG_CURRENT_DESKTOP="${XDG_CURRENT_DESKTOP:-XFCE}"',
+                    (
+                        "exec dbus-launch --exit-with-session sh -c "
+                        f"'\"{session.profile_dir / 'prepare-xfce-profile.sh'}\" >/dev/null 2>&1 || true; exec xfce4-session'"
+                    ),
+                    "",
+                ],
+            ),
+            encoding="utf-8",
+        )
+        try:
+            launcher.chmod(0o700)
+        except OSError:
+            pass
+        return launcher
+
+    def _prepare_root_window(self, session: DesktopSession) -> None:
+        xsetroot = shutil.which("xsetroot")
+        if not xsetroot:
+            return
+        subprocess.run(
+            [xsetroot, "-solid", "#20242a"],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=2,
+            env=self._display_env(session),
+        )
+
+    def _fit_office_window(
+        self,
+        session: DesktopSession,
+        *,
+        process: subprocess.Popen[Any] | None = None,
+    ) -> None:
+        virtual_desktop.fit_window_until(
+            display=session.display,
+            width=session.width,
+            height=session.height,
+            window_class="libreoffice",
+            keys=("Escape",),
+            settle_seconds=4,
+            timeout_seconds=10,
+            process=process,
+            xauthority=self._xauthority(session),
+            home=str(session.profile_dir),
+        )
+        self._dismiss_blocking_dialogs(session)
+
+    def _set_display_size(self, session: DesktopSession, width: int, height: int) -> dict[str, Any]:
+        result = virtual_desktop.resize_display(
+            display=session.display,
+            width=width,
+            height=height,
+            max_width=MAX_SCREEN_WIDTH,
+            max_height=MAX_SCREEN_HEIGHT,
+            window_class="",
+            keys=(),
+            xauthority=self._xauthority(session),
+            home=str(session.profile_dir),
+        )
+        if result.get("ok"):
+            session.width = int(result["width"])
+            session.height = int(result["height"])
+        return result
+
+    def _dismiss_blocking_dialogs(self, session: DesktopSession) -> None:
+        virtual_desktop.close_windows(
+            display=session.display,
+            names=BLOCKING_DIALOG_TITLES,
+            xauthority=self._xauthority(session),
+            home=str(session.profile_dir),
+        )
+
+    def _refresh_xfce_desktop(self, session: DesktopSession) -> None:
+        xfdesktop = shutil.which("xfdesktop")
+        if not xfdesktop:
+            return
+        env = self._xfce_process_env(session, "xfdesktop")
+        try:
+            subprocess.run(
+                [xfdesktop, "--reload"],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=4,
+                env=env,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return
+
+    def _trust_desktop_launchers(self, session: DesktopSession, desktop_dir: Path) -> None:
+        gio = shutil.which("gio")
+        if not gio:
+            return
+        env = self._xfce_process_env(session, "xfdesktop")
+        for launcher in desktop_dir.glob("*.desktop"):
+            try:
+                launcher.chmod(0o755)
+                checksum = hashlib.sha256(launcher.read_bytes()).hexdigest()
+            except OSError:
+                continue
+            for command in (
+                [gio, "set", str(launcher), "metadata::trusted", "true"],
+                [gio, "set", "-t", "string", str(launcher), "metadata::xfce-exe-checksum", checksum],
+            ):
+                try:
+                    subprocess.run(
+                        command,
+                        check=False,
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        timeout=4,
+                        env=env,
+                    )
+                except (OSError, subprocess.TimeoutExpired):
+                    continue
+
+    def _xfce_process_env(self, session: DesktopSession, command_name: str) -> dict[str, str]:
+        env = self._display_env(session)
+        proc = Path("/proc")
+        for candidate in proc.iterdir():
+            if not candidate.name.isdigit():
+                continue
+            try:
+                if (candidate / "comm").read_text(encoding="utf-8").strip() != command_name:
+                    continue
+                process_env = self._read_process_env(candidate)
+            except OSError:
+                continue
+            if process_env.get("HOME") != str(session.profile_dir):
+                continue
+            if process_env.get("DISPLAY") != f":{session.display}":
+                continue
+            for key, value in process_env.items():
+                if (
+                    key in {"DBUS_SESSION_BUS_ADDRESS", "DISPLAY", "HOME", "XAUTHORITY"}
+                    or key.startswith("XDG_")
+                ):
+                    env[key] = value
+            break
+        return env
+
+    def _read_process_env(self, proc_dir: Path) -> dict[str, str]:
+        raw = (proc_dir / "environ").read_bytes()
+        env: dict[str, str] = {}
+        for item in raw.split(b"\0"):
+            if not item or b"=" not in item:
+                continue
+            key, value = item.split(b"=", 1)
+            env[key.decode("utf-8", errors="ignore")] = value.decode("utf-8", errors="ignore")
+        return env
+
+    def _session_env(self, session: DesktopSession) -> dict[str, str]:
+        env = {
+            **os.environ,
+            "HOME": str(session.profile_dir),
+            "LANG": os.environ.get("LANG") or "C.UTF-8",
+            "TZ": session.timezone or Localization.get().get_timezone(),
+        }
+        browser_bridge = _url_bridge_script_path(session)
+        if browser_bridge.exists():
+            env["BROWSER"] = str(browser_bridge)
+        env.setdefault("XDG_RUNTIME_DIR", str(STATE_DIR / "xdg-runtime"))
+        runtime_dir = Path(env["XDG_RUNTIME_DIR"])
+        runtime_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            runtime_dir.chmod(0o700)
+        except OSError:
+            pass
+        return env
+
+    def _display_env(self, session: DesktopSession) -> dict[str, str]:
+        env = {
+            **self._session_env(session),
+            "DISPLAY": f":{session.display}",
+            "SAL_USE_VCLPLUGIN": os.environ.get("SAL_USE_VCLPLUGIN") or "gtk3",
+        }
+        xauthority = self._xauthority(session)
+        if xauthority:
+            env["XAUTHORITY"] = xauthority
+        return env
+
+    def _xauthority(self, session: DesktopSession) -> str:
+        path = session.profile_dir / ".Xauthority"
+        return str(path) if path.exists() else ""
+
+    def _allocate_endpoint_locked(self) -> tuple[int, int]:
+        used_displays = {session.display for session in self._sessions.values()}
+        used_ports = {session.xpra_port for session in self._sessions.values()}
+        for offset in range(MAX_SESSIONS):
+            display = DISPLAY_BASE + offset
+            port = XPRA_PORT_BASE + offset
+            if display in used_displays or port in used_ports:
+                continue
+            if _port_is_free(port):
+                return display, port
+        raise RuntimeError("No LibreOffice desktop slots are available.")
+
+    def _find_by_file_id_locked(self, file_id: str) -> DesktopSession | None:
+        for session in self._sessions.values():
+            if session.file_id == file_id and session.alive():
+                return session
+        return None
+
+    def _find_by_file_id(self, file_id: str) -> DesktopSession | None:
+        with self._lock:
+            return self._find_by_file_id_locked(str(file_id or "").strip())
+
+    def _reap_dead_locked(self) -> None:
+        for session_id, session in list(self._sessions.items()):
+            if not session.alive():
+                self._terminate_session(session)
+                virtual_desktop.unregister_session(session.token)
+                self._sessions.pop(session_id, None)
+                self._remove_manifest(session_id)
+
+    def _wait_for_display(self, session: DesktopSession) -> None:
+        deadline = time.time() + DISPLAY_START_TIMEOUT_SECONDS
+        while time.time() < deadline:
+            process = session.processes.get("xvfb") or session.processes.get("xpra")
+            if process and process.poll() is not None:
+                raise RuntimeError("The LibreOffice X display exited before it was ready.")
+            try:
+                if virtual_desktop.current_display_size(
+                    session.display,
+                    xauthority=self._xauthority(session),
+                    home=str(session.profile_dir),
+                ):
+                    return
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+            time.sleep(0.1)
+        raise TimeoutError("Timed out waiting for the LibreOffice X display.")
+
+    def _wait_for_xfce(self, session: DesktopSession) -> None:
+        deadline = time.time() + STARTUP_GRACE_SECONDS
+        while time.time() < deadline:
+            process = session.processes.get("xfce")
+            if process and process.poll() is not None:
+                raise RuntimeError("The XFCE desktop session exited before it was ready.")
+            if virtual_desktop.has_window(
+                display=session.display,
+                name="xfce4-panel",
+                xauthority=self._xauthority(session),
+                home=str(session.profile_dir),
+            ):
+                return
+            time.sleep(0.25)
+
+    def _write_manifest(self, session: DesktopSession) -> None:
+        SESSION_DIR.mkdir(parents=True, exist_ok=True)
+        pids = dict(session.process_ids)
+        pids.update({name: process.pid for name, process in session.processes.items()})
+        payload = {
+            "session_id": session.session_id,
+            "file_id": session.file_id,
+            "extension": session.extension,
+            "path": session.path,
+            "title": session.title,
+            "display": session.display,
+            "xpra_port": session.xpra_port,
+            "profile_dir": str(session.profile_dir),
+            "width": session.width,
+            "height": session.height,
+            "started_at": session.started_at,
+            "timezone": session.timezone,
+            "owner_pid": os.getpid(),
+            "pids": pids,
+        }
+        manifest = SESSION_DIR / f"{session.session_id}.json"
+        tmp = manifest.with_name(f".{manifest.name}.{uuid.uuid4().hex}.tmp")
+        try:
+            tmp.write_text(json.dumps(payload), encoding="utf-8")
+            os.replace(tmp, manifest)
+        finally:
+            tmp.unlink(missing_ok=True)
+
+    def _remove_manifest(self, session_id: str) -> None:
+        (SESSION_DIR / f"{session_id}.json").unlink(missing_ok=True)
+
+    def _terminate_session(self, session: DesktopSession, *, include_rehydrated: bool = False) -> None:
+        process_names = [name for name in session.processes if name.startswith("soffice")]
+        process_names.extend(["xfce", "xpra", "xvfb"])
+        terminated_pids: set[int] = set()
+        for name in process_names:
+            process = session.processes.get(name)
+            if not process:
+                continue
+            if process.pid:
+                terminated_pids.add(process.pid)
+            _terminate_process(process)
+        if session.owns_processes or include_rehydrated:
+            for name, pid in session.process_ids.items():
+                if pid in terminated_pids:
+                    continue
+                if name.startswith("soffice") or name in {"xfce", "xpra", "xvfb"}:
+                    _kill_pid(pid)
+        self._remove_stale_lock_file(session)
+
+    def _remove_stale_lock_file(self, session: DesktopSession, *, path: str | Path | None = None) -> None:
+        path = Path(path or session.path)
+        if not path.name:
+            return
+        lock_file = path.with_name(f".~lock.{path.name}#")
+        try:
+            lock_file.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def collect_desktop_status() -> dict[str, Any]:
+    desktop = virtual_desktop.collect_status()
+    binaries = {
+        **desktop["binaries"],
+        "soffice": libreoffice.find_soffice(),
+        "thunar": shutil.which("thunar") or "",
+        "xfce4-terminal": shutil.which("xfce4-terminal") or "",
+        "xfce4-settings-manager": shutil.which("xfce4-settings-manager") or "",
+        "gio": shutil.which("gio") or "",
+    }
+    missing = [
+        name
+        for name in (
+            "soffice",
+            "thunar",
+            "xfce4-terminal",
+            "xfce4-settings-manager",
+            "gio",
+        )
+        if not binaries[name]
+    ]
+    missing.extend(
+        name
+        for name in ("xpra", "Xvfb", "xfce4-session", "dbus-launch", "xrandr", "xdotool")
+        if not binaries.get(name)
+    )
+    if not desktop.get("xpra_html_root"):
+        missing.append("xpra-html5")
+    if desktop.get("binaries", {}).get("xpra") and desktop.get("packages", {}).get("xpra-x11") is False:
+        missing.append("xpra-x11")
+    healthy = not missing
+    preparation = _runtime_preparation_status()
+    installing = bool(preparation.get("preparing")) and not healthy
+    return {
+        "ok": True,
+        "healthy": healthy,
+        "state": "healthy" if healthy else "installing" if installing else "missing",
+        "installing": installing,
+        "missing": missing,
+        "preparation": preparation,
+        "binaries": binaries,
+        "xpra_html_root": str(desktop.get("xpra_html_root") or ""),
+        "message": (
+            "Agent Zero Desktop sessions are available."
+            if healthy
+            else RUNTIME_INSTALL_MESSAGE
+            if installing
+            else f"Agent Zero Desktop sessions need: {', '.join(missing)}."
+        ),
+    }
+
+
+def _state_path_from_retired_root(path: Path) -> Path:
+    try:
+        relative = path.resolve(strict=False).relative_to(
+            RETIRED_STATE_DIR.resolve(strict=False)
+        )
+    except ValueError:
+        return path
+    return STATE_DIR / relative
+
+
+def _runtime_preparation_status() -> dict[str, Any]:
+    try:
+        from plugins._desktop import hooks
+
+        return hooks.runtime_preparation_status()
+    except Exception:
+        return {"preparing": False, "active_count": 0, "started_at": 0.0, "completed_at": 0.0}
+
+
+def cleanup_stale_runtime_state() -> dict[str, Any]:
+    killed: list[int] = []
+    errors: list[str] = []
+    seen_dirs: set[Path] = set()
+    for session_dir in (SESSION_DIR, *LEGACY_SESSION_DIRS):
+        if session_dir in seen_dirs:
+            continue
+        seen_dirs.add(session_dir)
+        if session_dir.exists():
+            for manifest in session_dir.glob("*.json"):
+                try:
+                    payload = json.loads(manifest.read_text(encoding="utf-8"))
+                    owner_pid = _coerce_pid(payload.get("owner_pid"))
+                    if owner_pid and _pid_is_running(owner_pid):
+                        continue
+                    for pid in dict(payload.get("pids") or {}).values():
+                        pid_int = _coerce_pid(pid)
+                        if not pid_int:
+                            continue
+                        if _kill_pid(pid_int):
+                            killed.append(pid_int)
+                    manifest.unlink(missing_ok=True)
+                except Exception as exc:
+                    errors.append(str(exc))
+    return {"ok": not errors, "killed": killed, "errors": errors}
+
+
+def get_manager() -> DesktopSessionManager:
+    global _manager
+    try:
+        return _manager
+    except NameError:
+        _manager = DesktopSessionManager()
+        atexit.register(_manager.shutdown)
+        return _manager
+
+
+def _xpra_url(token: str) -> str:
+    return virtual_desktop.session_url(token, title="Desktop")
+
+
+def _xvfb_command(xvfb: str, session: DesktopSession) -> list[str]:
+    return [
+        xvfb,
+        f":{session.display}",
+        "-screen",
+        "0",
+        f"{MAX_SCREEN_WIDTH}x{MAX_SCREEN_HEIGHT}x24",
+        "+extension",
+        "GLX",
+        "+extension",
+        "RANDR",
+        "+extension",
+        "RENDER",
+        "+extension",
+        "Composite",
+        "-extension",
+        "DOUBLE-BUFFER",
+        "-nolisten",
+        "tcp",
+        "-noreset",
+        "-ac",
+    ]
+
+
+def _xpra_shadow_command(xpra: str, session: DesktopSession) -> list[str]:
+    return [
+        xpra,
+        "shadow",
+        f":{session.display}",
+        "--daemon=no",
+        "--mdns=no",
+        "--html=on",
+        "--tray=no",
+        "--system-tray=no",
+        "--notifications=no",
+        "--clipboard=yes",
+        "--clipboard-direction=both",
+        "--file-transfer=yes",
+        "--open-files=no",
+        "--open-url=no",
+        "--printing=yes",
+        "--audio=no",
+        "--speaker=off",
+        "--microphone=off",
+        "--encoding=jpeg",
+        "--quality=85",
+        "--speed=80",
+        f"--bind-tcp=127.0.0.1:{session.xpra_port}",
+        "--resize-display=yes",
+        f"--log-dir={session.profile_dir}",
+        "--log-file=xpra.log",
+    ]
+
+
+def _desktop_exec(*args: str | Path) -> str:
+    return " ".join(_desktop_exec_arg(str(arg)) for arg in args if str(arg))
+
+
+def _desktop_icon(*candidates: str) -> str:
+    for candidate in candidates:
+        if candidate.startswith("/") and Path(candidate).exists():
+            return candidate
+    return next(
+        (candidate for candidate in candidates if not candidate.startswith("/")),
+        candidates[-1],
+    )
+
+
+def _ensure_desktop_folder_link(desktop_dir: Path, label: str, target: Path) -> None:
+    target.mkdir(parents=True, exist_ok=True)
+    link = desktop_dir / label
+    try:
+        if link.is_symlink() or link.is_file():
+            link.unlink()
+        if not link.exists():
+            link.symlink_to(target, target_is_directory=True)
+    except OSError:
+        return
+
+
+def _url_bridge_dir(session: DesktopSession) -> Path:
+    return session.profile_dir / ".agent-zero"
+
+
+def _url_bridge_script_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "open-url"
+
+
+def _editor_bridge_script_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "open-editor"
+
+
+def _url_bridge_queue_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "browser-url-intents.jsonl"
+
+
+def _url_bridge_lock_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "browser-url-intents.lock"
+
+
+def _shutdown_request_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "shutdown-request.json"
+
+
+def _shutdown_arm_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "shutdown-request.arm.json"
+
+
+def _shutdown_lock_path(session: DesktopSession) -> Path:
+    return _url_bridge_dir(session) / "shutdown-request.lock"
+
+
+def _write_url_bridge_script(session: DesktopSession) -> Path:
+    bridge_dir = _url_bridge_dir(session)
+    bridge_dir.mkdir(parents=True, exist_ok=True)
+    script = _url_bridge_script_path(session)
+    queue = _url_bridge_queue_path(session)
+    lock = _url_bridge_lock_path(session)
+    script.write_text(
+        f"""#!/usr/bin/env python3
+import fcntl
+import json
+import os
+import sys
+import time
+
+QUEUE_PATH = {str(queue)!r}
+LOCK_PATH = {str(lock)!r}
+MAX_URL_LENGTH = {URL_INTENT_MAX_LENGTH}
+
+
+def main():
+    urls = [str(arg or "").strip()[:MAX_URL_LENGTH] for arg in sys.argv[1:] if str(arg or "").strip()]
+    if not urls:
+        urls = [""]
+    os.makedirs(os.path.dirname(QUEUE_PATH), exist_ok=True)
+    with open(LOCK_PATH, "a+", encoding="utf-8") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        with open(QUEUE_PATH, "a", encoding="utf-8") as queue_file:
+            for url in urls:
+                queue_file.write(json.dumps({{
+                    "url": url,
+                    "created_at": time.time(),
+                    "source": "desktop",
+                }}, ensure_ascii=True) + "\\n")
+            queue_file.flush()
+            os.fsync(queue_file.fileno())
+        fcntl.flock(lock_file, fcntl.LOCK_UN)
+
+
+if __name__ == "__main__":
+    main()
+""",
+        encoding="utf-8",
+    )
+    try:
+        script.chmod(0o755)
+    except OSError:
+        pass
+    return script
+
+
+def _write_editor_bridge_script(session: DesktopSession) -> Path:
+    bridge_dir = _url_bridge_dir(session)
+    bridge_dir.mkdir(parents=True, exist_ok=True)
+    script = _editor_bridge_script_path(session)
+    queue = _url_bridge_queue_path(session)
+    lock = _url_bridge_lock_path(session)
+    script.write_text(
+        f"""#!/usr/bin/env python3
+import fcntl
+import json
+import os
+import sys
+import time
+from urllib.parse import quote
+
+QUEUE_PATH = {str(queue)!r}
+LOCK_PATH = {str(lock)!r}
+MAX_URL_LENGTH = {URL_INTENT_MAX_LENGTH}
+
+
+def editor_url(path):
+    path = str(path or "").strip()
+    if not path:
+        return "a0-editor://open"
+    return "a0-editor://open?path=" + quote(path[:MAX_URL_LENGTH], safe="/:")
+
+
+def main():
+    urls = [editor_url(arg) for arg in sys.argv[1:] if str(arg or "").strip()]
+    if not urls:
+        urls = [editor_url("")]
+    os.makedirs(os.path.dirname(QUEUE_PATH), exist_ok=True)
+    with open(LOCK_PATH, "a+", encoding="utf-8") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        with open(QUEUE_PATH, "a", encoding="utf-8") as queue_file:
+            for url in urls:
+                queue_file.write(json.dumps({{
+                    "url": url,
+                    "created_at": time.time(),
+                    "source": "desktop-editor",
+                }}, ensure_ascii=True) + "\\n")
+            queue_file.flush()
+            os.fsync(queue_file.fileno())
+        fcntl.flock(lock_file, fcntl.LOCK_UN)
+
+
+if __name__ == "__main__":
+    main()
+""",
+        encoding="utf-8",
+    )
+    try:
+        script.chmod(0o755)
+    except OSError:
+        pass
+    return script
+
+
+def _write_shutdown_bridge_script(session: DesktopSession) -> Path:
+    bridge_dir = _url_bridge_dir(session)
+    bridge_dir.mkdir(parents=True, exist_ok=True)
+    script = bridge_dir / "shutdown-desktop"
+    request = _shutdown_request_path(session)
+    arm = _shutdown_arm_path(session)
+    lock = _shutdown_lock_path(session)
+    script.write_text(
+        f"""#!/usr/bin/env python3
+import fcntl
+import json
+import os
+import shutil
+import subprocess
+import time
+
+REQUEST_PATH = {str(request)!r}
+ARM_PATH = {str(arm)!r}
+LOCK_PATH = {str(lock)!r}
+CONFIRM_SECONDS = {SHUTDOWN_CONFIRM_SECONDS}
+
+
+def notify(message, timeout=None):
+    if not os.environ.get("DISPLAY"):
+        return
+    xmessage = shutil.which("xmessage")
+    if not xmessage:
+        return
+    try:
+        subprocess.Popen(
+            [
+                xmessage,
+                "-buttons",
+                "",
+                "-timeout",
+                str(timeout or CONFIRM_SECONDS),
+                "-center",
+                message,
+            ],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except OSError:
+        pass
+
+
+def read_arm(now):
+    try:
+        with open(ARM_PATH, "r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    try:
+        created_at = float(payload.get("created_at"))
+    except (TypeError, ValueError):
+        return None
+    if now - created_at > CONFIRM_SECONDS:
+        return None
+    return created_at
+
+
+def write_json_atomic(path, payload):
+    tmp_path = path + ".tmp"
+    with open(tmp_path, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle, ensure_ascii=True)
+        handle.write("\\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(tmp_path, path)
+
+
+def main():
+    os.makedirs(os.path.dirname(REQUEST_PATH), exist_ok=True)
+    now = time.time()
+    with open(LOCK_PATH, "a+", encoding="utf-8") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        armed_at = read_arm(now)
+        if armed_at is None:
+            write_json_atomic(ARM_PATH, {{"created_at": now, "source": "tray"}})
+            notify(
+                f"Shutdown Desktop armed. Click Shutdown Desktop again within {{CONFIRM_SECONDS}} seconds to close it.",
+                CONFIRM_SECONDS,
+            )
+            return
+        try:
+            os.unlink(ARM_PATH)
+        except OSError:
+            pass
+        payload = {{
+            "created_at": now,
+            "armed_at": armed_at,
+            "source": "tray",
+        }}
+        write_json_atomic(REQUEST_PATH, payload)
+        notify("Shutting down Agent Zero Desktop.", 2)
+
+
+if __name__ == "__main__":
+    main()
+""",
+        encoding="utf-8",
+    )
+    try:
+        script.chmod(0o755)
+    except OSError:
+        pass
+    return script
+
+
+def _claim_url_intents(session: DesktopSession) -> list[dict[str, Any]]:
+    queue = _url_bridge_queue_path(session)
+    lock = _url_bridge_lock_path(session)
+    if not queue.exists():
+        return []
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with open(lock, "a+", encoding="utf-8") as lock_file:
+            fcntl.flock(lock_file, fcntl.LOCK_EX)
+            try:
+                raw = queue.read_text(encoding="utf-8")
+                queue.write_text("", encoding="utf-8")
+            finally:
+                fcntl.flock(lock_file, fcntl.LOCK_UN)
+    except OSError:
+        return []
+
+    intents: list[dict[str, Any]] = []
+    for line in raw.splitlines():
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        url = str(payload.get("url") or "").strip()
+        if len(url) > URL_INTENT_MAX_LENGTH:
+            url = url[:URL_INTENT_MAX_LENGTH]
+        created_at = payload.get("created_at")
+        try:
+            created_at = float(created_at)
+        except (TypeError, ValueError):
+            created_at = time.time()
+        intents.append(
+            {
+                "url": url,
+                "created_at": created_at,
+                "source": str(payload.get("source") or "desktop"),
+            },
+        )
+        if len(intents) >= URL_INTENT_MAX_ITEMS:
+            break
+    return intents
+
+
+def _claim_shutdown_request(session: DesktopSession) -> dict[str, Any] | None:
+    request = _shutdown_request_path(session)
+    if not request.exists():
+        return None
+    try:
+        raw = request.read_text(encoding="utf-8")
+        request.unlink(missing_ok=True)
+    except OSError:
+        return None
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = {}
+    created_at = payload.get("created_at")
+    try:
+        created_at = float(created_at)
+    except (TypeError, ValueError):
+        created_at = time.time()
+    return {
+        "created_at": created_at,
+        "source": str(payload.get("source") or "tray"),
+    }
+
+
+def _clear_shutdown_request(session: DesktopSession) -> None:
+    request = _shutdown_request_path(session)
+    arm = _shutdown_arm_path(session)
+    lock = _shutdown_lock_path(session)
+    request.unlink(missing_ok=True)
+    request.with_suffix(request.suffix + ".tmp").unlink(missing_ok=True)
+    arm.unlink(missing_ok=True)
+    arm.with_suffix(arm.suffix + ".tmp").unlink(missing_ok=True)
+    lock.unlink(missing_ok=True)
+
+
+def _remove_system_manifest() -> None:
+    (SESSION_DIR / f"{SYSTEM_SESSION_ID}.json").unlink(missing_ok=True)
+
+
+def _url_handler_mime_types() -> tuple[str, ...]:
+    return (
+        "x-scheme-handler/http",
+        "x-scheme-handler/https",
+        "text/html",
+        "application/xhtml+xml",
+    )
+
+
+def _editor_text_handler_mime_types() -> tuple[str, ...]:
+    return (
+        "text/markdown",
+        "text/x-markdown",
+        "text/plain",
+    )
+
+
+def _write_mimeapps_defaults(path: Path, url_desktop_id: str, editor_desktop_id: str) -> None:
+    url_associations = ";".join([url_desktop_id, ""])
+    # LibreOffice Writer stays the default so double-clicks keep the user (and
+    # agents) inside the Desktop; the Agent Zero Editor remains an "Open With"
+    # option. When Writer's desktop entry is missing, xdg falls back through
+    # the added associations to the editor.
+    text_associations = ";".join([WRITER_HANDLER_DESKTOP_ID, editor_desktop_id, ""])
+    lines = [
+        "[Default Applications]",
+        *(f"{mime_type}={url_desktop_id}" for mime_type in _url_handler_mime_types()),
+        *(f"{mime_type}={WRITER_HANDLER_DESKTOP_ID}" for mime_type in _editor_text_handler_mime_types()),
+        "",
+        "[Added Associations]",
+        *(f"{mime_type}={url_associations}" for mime_type in _url_handler_mime_types()),
+        *(f"{mime_type}={text_associations}" for mime_type in _editor_text_handler_mime_types()),
+        "",
+    ]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _write_xfce_browser_helper(path: Path, bridge_script: Path) -> None:
+    command = _desktop_exec(bridge_script)
+    command_with_parameter = _desktop_exec(bridge_script, "%s")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "\n".join(
+            [
+                "[Desktop Entry]",
+                "NoDisplay=true",
+                "Version=1.0",
+                "Type=X-XFCE-Helper",
+                "X-XFCE-Category=WebBrowser",
+                f"X-XFCE-Commands={command}",
+                f"X-XFCE-CommandsWithParameter={command_with_parameter}",
+                "Icon=web-browser",
+                "Name=Agent Zero Browser",
+                "",
+            ],
+        ),
+        encoding="utf-8",
+    )
+
+
+def _remove_path_if_owned(path: Path) -> None:
+    try:
+        if path.is_symlink() or path.is_file():
+            path.unlink()
+        elif path.is_dir():
+            shutil.rmtree(path)
+    except OSError:
+        return
+
+
+def _desktop_exec_arg(value: str) -> str:
+    if not any(char.isspace() or char in '"\\' for char in value):
+        return value
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _xml_attr(value: str) -> str:
+    return (
+        str(value)
+        .replace("&", "&amp;")
+        .replace('"', "&quot;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )
+
+
+def _oor(name: str) -> str:
+    return f"{{{OOR_NS}}}{name}"
+
+
+def _file_uri(path: str | Path) -> str:
+    return Path(path).resolve(strict=False).as_uri()
+
+
+def _write_libreoffice_registry_defaults(registry: Path, workdir: str | Path) -> None:
+    Path(workdir).mkdir(parents=True, exist_ok=True)
+    ET.register_namespace("oor", OOR_NS)
+    ET.register_namespace("xs", XS_NS)
+    ET.register_namespace("xsi", XSI_NS)
+    root = _read_libreoffice_registry(registry)
+    workdir_uri = _file_uri(workdir)
+    for path, prop, value in (
+        ("/org.openoffice.Office.Common/Misc", "FirstRun", "false"),
+        ("/org.openoffice.Setup/Office", "ooSetupInstCompleted", "true"),
+        ("/org.openoffice.Setup/Office", "MigrationCompleted", "true"),
+        ("/org.openoffice.Setup/Office", "OfficeRestartInProgress", "false"),
+        ("/org.openoffice.Setup/L10N", "ooLocale", "en-US"),
+        ("/org.openoffice.Office.Paths/Variables", "Work", workdir_uri),
+        (
+            "/org.openoffice.Office.Paths/Paths/org.openoffice.Office.Paths:NamedPath['Work']",
+            "WritePath",
+            workdir_uri,
+        ),
+    ):
+        _set_registry_prop(root, path, prop, value)
+    registry.parent.mkdir(parents=True, exist_ok=True)
+    ET.ElementTree(root).write(registry, encoding="utf-8", xml_declaration=True)
+
+
+def _read_libreoffice_registry(registry: Path) -> ET.Element:
+    if registry.exists():
+        try:
+            return ET.parse(registry).getroot()
+        except ET.ParseError:
+            pass
+    return ET.Element(
+        _oor("items"),
+        {
+            "xmlns:xs": XS_NS,
+            "xmlns:xsi": XSI_NS,
+        },
+    )
+
+
+def _set_registry_prop(root: ET.Element, item_path: str, prop_name: str, value: str) -> None:
+    item = _find_registry_item(root, item_path)
+    if item is None:
+        item = ET.SubElement(root, "item", {_oor("path"): item_path})
+    prop = next((child for child in item.findall("prop") if child.get(_oor("name")) == prop_name), None)
+    if prop is None:
+        prop = ET.SubElement(item, "prop", {_oor("name"): prop_name, _oor("op"): "fuse"})
+    else:
+        prop.set(_oor("op"), "fuse")
+    value_node = prop.find("value")
+    if value_node is None:
+        value_node = ET.SubElement(prop, "value")
+    value_node.text = str(value)
+
+
+def _find_registry_item(root: ET.Element, item_path: str) -> ET.Element | None:
+    for item in root.findall("item"):
+        if item.get(_oor("path")) == item_path:
+            return item
+    return None
+
+
+def _write_desktop_launcher(
+    path: Path,
+    *,
+    name: str,
+    exec_line: str,
+    icon: str,
+    categories: str,
+    try_exec: str = "",
+    working_dir: str | Path | None = None,
+    mime_types: tuple[str, ...] = (),
+    no_display: bool = False,
+) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        "[Desktop Entry]",
+        "Version=1.0",
+        "Type=Application",
+        f"Name={name}",
+        f"Exec={exec_line}",
+    ]
+    if try_exec:
+        lines.append(f"TryExec={try_exec}")
+    if working_dir:
+        lines.append(f"Path={working_dir}")
+    if mime_types:
+        lines.append(f"MimeType={';'.join(mime_types)};")
+    if no_display:
+        lines.append("NoDisplay=true")
+    lines.extend(
+        [
+            f"Icon={icon}",
+            "Terminal=false",
+            f"Categories={categories}",
+            "StartupNotify=true",
+            "X-XFCE-Trusted=true",
+            "",
+        ],
+    )
+    path.write_text("\n".join(lines), encoding="utf-8")
+    try:
+        path.chmod(0o755)
+    except OSError:
+        pass
+
+
+def _write_hidden_application_entry(path: Path, name: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "\n".join(
+            [
+                "[Desktop Entry]",
+                "Type=Application",
+                f"Name={name}",
+                "NoDisplay=true",
+                "Hidden=true",
+                "",
+            ],
+        ),
+        encoding="utf-8",
+    )
+
+
+def _write_thunar_defaults(path: Path) -> None:
+    root = _read_xfce_channel(path, "thunar")
+    if _find_xfce_property(root, "last-view") is None:
+        _xfce_property(root, "last-view", "string", "ThunarIconView")
+    _xfce_property(root, "last-show-hidden", "bool", "true")
+    _write_xfce_channel(path, root)
+
+
+def _read_xfce_channel(path: Path, channel_name: str) -> ET.Element:
+    if path.exists():
+        try:
+            root = ET.parse(path).getroot()
+            if root.tag == "channel" and root.get("name") == channel_name:
+                root.set("version", root.get("version") or "1.0")
+                return root
+        except (ET.ParseError, OSError):
+            pass
+    return ET.Element("channel", {"name": channel_name, "version": "1.0"})
+
+
+def _write_xfce_channel(path: Path, root: ET.Element) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tree = ET.ElementTree(root)
+    try:
+        ET.indent(tree, space="  ")
+    except AttributeError:
+        pass
+    tree.write(path, encoding="utf-8", xml_declaration=True)
+
+
+def _find_xfce_property(parent: ET.Element, name: str) -> ET.Element | None:
+    return next((child for child in parent.findall("property") if child.get("name") == name), None)
+
+
+def _install_desktop_readme(desktop_dir: Path) -> None:
+    if not DESKTOP_README_SOURCE.exists():
+        return
+    target = desktop_dir / "README.md"
+    try:
+        content = DESKTOP_README_SOURCE.read_text(encoding="utf-8")
+        if target.exists() and target.read_text(encoding="utf-8") == content:
+            return
+        target.write_text(content, encoding="utf-8")
+        target.chmod(0o644)
+    except OSError:
+        return
+
+
+def _xfce_property(parent: ET.Element, name: str, property_type: str, value: str | None = None) -> ET.Element:
+    for child in parent.findall("property"):
+        if child.get("name") == name:
+            child.set("type", property_type)
+            if value is None:
+                child.attrib.pop("value", None)
+            else:
+                child.set("value", value)
+            return child
+    attributes = {"name": name, "type": property_type}
+    if value is not None:
+        attributes["value"] = value
+    return ET.SubElement(parent, "property", attributes)
+
+
+def _public_doc(doc: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "file_id": doc["file_id"],
+        "path": document_store.display_path(doc["path"]),
+        "basename": doc["basename"],
+        "extension": doc["extension"],
+        "size": doc["size"],
+        "version": document_store.item_version(doc),
+        "last_modified": doc["last_modified"],
+    }
+
+
+def _require_binary(name: str) -> str:
+    found = shutil.which(name)
+    if not found:
+        raise RuntimeError(f"{name} is required for official LibreOffice desktop sessions.")
+    return found
+
+
+def _running(process: subprocess.Popen[Any] | None) -> bool:
+    return bool(process and process.poll() is None)
+
+
+def _wait_for_port(
+    host: str,
+    port: int,
+    timeout: float = 15.0,
+    process: subprocess.Popen[Any] | None = None,
+) -> None:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if process and process.poll() is not None:
+            raise RuntimeError(f"Xpra exited before port {port} was ready.")
+        try:
+            with socket.create_connection((host, port), timeout=0.2):
+                return
+        except OSError:
+            time.sleep(0.1)
+    raise TimeoutError(f"Timed out waiting for Xpra port {port}.")
+
+
+def _port_is_free(port: int) -> bool:
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            probe.bind(("127.0.0.1", port))
+        return True
+    except OSError:
+        return False
+
+
+def _port_is_accepting(host: str, port: int) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=0.2):
+            return True
+    except OSError:
+        return False
+
+
+def _terminate_process(process: subprocess.Popen[Any]) -> None:
+    if process.poll() is not None:
+        return
+    try:
+        process.terminate()
+        process.wait(timeout=2)
+        return
+    except Exception:
+        pass
+    try:
+        process.kill()
+        process.wait(timeout=2)
+    except Exception:
+        pass
+
+
+def _kill_pid(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 15)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return False
+
+
+def _coerce_pid(value: Any) -> int:
+    try:
+        pid = int(value)
+    except (TypeError, ValueError):
+        return 0
+    return pid if pid > 0 else 0
+
+
+def _pid_is_running(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True

plugins/_desktop/helpers/desktop_state.py

@@ -0,0 +1,893 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+
+SESSION_ID = "agent-zero-desktop"
+PLUGIN_NAME = "_desktop"
+BASE_DIR = Path(os.environ.get("A0_BASE_DIR") or ("/a0" if Path("/a0").exists() else PROJECT_ROOT))
+STATE_DIR = BASE_DIR / "usr" / "plugins" / PLUGIN_NAME
+RETIRED_STATE_DIR = BASE_DIR / "usr" / PLUGIN_NAME
+SESSION_DIR = STATE_DIR / "sessions"
+PROFILE_DIR = STATE_DIR / "profiles"
+SCREENSHOT_DIR = Path(os.environ.get("A0_DESKTOP_SCREENSHOT_DIR") or BASE_DIR / "tmp" / "desktop" / "screenshots")
+RECENT_SCREENSHOT_SECONDS = 600
+_SAFE_CONTEXT_RE = re.compile(r"[^a-zA-Z0-9_.-]+")
+_SCREENSHOT_SUFFIXES = {".png", ".jpg", ".jpeg", ".xwd"}
+
+
+def session_manifest_path(session_id: str = SESSION_ID) -> Path:
+    return Path(os.environ.get("A0_DESKTOP_MANIFEST") or SESSION_DIR / f"{session_id}.json")
+
+
+def context_screenshot_dir(context_id: str = "") -> Path:
+    return SCREENSHOT_DIR / _safe_context_id(context_id)
+
+
+def chat_screenshot_dir(context_id: str = "") -> Path:
+    return BASE_DIR / "usr" / "chats" / _safe_context_id(context_id) / "screenshots" / "desktop"
+
+
+def normalize_a0_path(path: str | Path) -> str:
+    candidate = Path(path)
+    try:
+        relative = candidate.resolve(strict=False).relative_to(BASE_DIR.resolve(strict=False))
+    except ValueError:
+        return str(candidate)
+    return "/a0/" + str(relative).replace(os.sep, "/")
+
+
+def _safe_context_id(context_id: str = "") -> str:
+    raw = str(context_id or os.environ.get("A0_DESKTOP_CONTEXT_ID") or "default")
+    return _SAFE_CONTEXT_RE.sub("_", raw).strip("._") or "default"
+
+
+def session_manifest_exists(session_id: str = SESSION_ID) -> bool:
+    return session_manifest_path(session_id).exists()
+
+
+def collect_state(
+    *,
+    include_screenshot: bool = False,
+    screenshot_path: str | Path | None = None,
+    context_id: str = "",
+    screenshot_transport: str = "ephemeral",
+) -> dict[str, Any]:
+    errors: list[str] = []
+    env_info = resolve_environment(errors=errors)
+    display = env_info["display"]
+    profile_dir = env_info["profile_dir"]
+    env = display_env(display=display, profile_dir=profile_dir)
+
+    capabilities = collect_capabilities()
+    for name in ("xdotool", "xrandr", "xwininfo", "xprop"):
+        if not capabilities.get(name):
+            errors.append(f"{name} is not installed; install Desktop runtime dependencies through the _desktop plugin hook.")
+
+    size = collect_display_size(env, capabilities, errors)
+    pointer = collect_pointer(env, capabilities, errors)
+    active_window = collect_active_window(env, capabilities, errors)
+    windows = collect_windows(env, capabilities, errors)
+    screenshot = latest_screenshot(context_id=context_id)
+
+    if include_screenshot:
+        screenshot = capture_screenshot(
+            env,
+            capabilities,
+            path=screenshot_path,
+            errors=errors,
+            context_id=context_id,
+            transport=screenshot_transport,
+        )
+
+    return stable_state(
+        context_id=context_id,
+        display=display,
+        profile_dir=profile_dir,
+        size=size,
+        pointer=pointer,
+        active_window=active_window,
+        windows=windows,
+        screenshot=screenshot,
+        capabilities=capabilities,
+        errors=errors,
+    )
+
+
+def capture_screenshot(
+    env: dict[str, str] | None = None,
+    capabilities: dict[str, str] | None = None,
+    *,
+    path: str | Path | None = None,
+    errors: list[str] | None = None,
+    context_id: str = "",
+    transport: str = "ephemeral",
+) -> dict[str, Any]:
+    local_errors = errors if errors is not None else []
+    capabilities = capabilities or collect_capabilities()
+    if not env:
+        env_errors: list[str] = []
+        env_info = resolve_environment(errors=env_errors)
+        local_errors.extend(env_errors)
+        env = display_env(display=env_info["display"], profile_dir=env_info["profile_dir"])
+
+    xwd = capabilities.get("xwd") or shutil.which("xwd") or ""
+    if not xwd:
+        message = "xwd is not installed; install x11-apps through the _desktop plugin hook."
+        local_errors.append(message)
+        return {"ok": False, "path": "", "format": "", "captured_at": "", "error": message}
+
+    explicit_path = path is not None and str(path).strip() != ""
+    transport_mode = str(transport or "").strip().lower()
+    chat_scoped = bool(not explicit_path and transport_mode == "path" and str(context_id or "").strip())
+    ephemeral_ref = not explicit_path and transport_mode != "path"
+    screenshot_dir = chat_screenshot_dir(context_id) if chat_scoped else context_screenshot_dir(context_id)
+    if not explicit_path and not chat_scoped:
+        prune_context_screenshots(context_id=context_id)
+        screenshot_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = time.strftime("%Y%m%d-%H%M%S")
+    millis = int((time.time() % 1) * 1000)
+    target = Path(path) if explicit_path else screenshot_dir / f"desktop-{timestamp}-{millis:03d}.png"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    raw_path = target.with_suffix(".xwd")
+    safe_context = _safe_context_id(context_id)
+
+    result = run([xwd, "-root", "-silent", "-out", str(raw_path)], env=env, timeout=8)
+    if result.returncode != 0:
+        detail = command_output(result) or "xwd screenshot capture failed."
+        local_errors.append(detail)
+        raw_path.unlink(missing_ok=True)
+        return {"ok": False, "path": "", "format": "", "captured_at": "", "error": detail}
+
+    if target.suffix.lower() == ".xwd":
+        if not explicit_path and not chat_scoped:
+            prune_context_screenshots(context_id=context_id, keep_path=raw_path)
+        return {
+            "ok": True,
+            "path": str(raw_path),
+            "a0_path": normalize_a0_path(raw_path),
+            "format": "xwd",
+            "captured_at": iso_now(),
+            "recent": True,
+            "ephemeral": not explicit_path and not chat_scoped,
+            "chat_scoped": chat_scoped,
+            "context_id": safe_context,
+            "error": "",
+        }
+
+    try:
+        from PIL import Image
+
+        with Image.open(raw_path) as image:
+            image.save(target)
+            width = int(image.width)
+            height = int(image.height)
+        raw_path.unlink(missing_ok=True)
+        if ephemeral_ref:
+            return ephemeral_screenshot_result(
+                target,
+                context_id=context_id,
+                image_format=target.suffix.lower().lstrip(".") or "png",
+                width=width,
+                height=height,
+            )
+        if not explicit_path and not chat_scoped:
+            prune_context_screenshots(context_id=context_id, keep_path=target)
+        return {
+            "ok": True,
+            "path": str(target),
+            "a0_path": normalize_a0_path(target),
+            "format": target.suffix.lower().lstrip(".") or "png",
+            "width": width,
+            "height": height,
+            "captured_at": iso_now(),
+            "recent": True,
+            "ephemeral": not explicit_path and not chat_scoped,
+            "chat_scoped": chat_scoped,
+            "context_id": safe_context,
+            "error": "",
+        }
+    except Exception as exc:
+        try:
+            converted = convert_xwd_to_image(raw_path, target)
+            raw_path.unlink(missing_ok=True)
+            if ephemeral_ref:
+                return ephemeral_screenshot_result(
+                    target,
+                    context_id=context_id,
+                    image_format=target.suffix.lower().lstrip(".") or "png",
+                    width=converted["width"],
+                    height=converted["height"],
+                )
+            if not explicit_path and not chat_scoped:
+                prune_context_screenshots(context_id=context_id, keep_path=target)
+            return {
+                "ok": True,
+                "path": str(target),
+                "a0_path": normalize_a0_path(target),
+                "format": target.suffix.lower().lstrip(".") or "png",
+                "width": converted["width"],
+                "height": converted["height"],
+                "captured_at": iso_now(),
+                "recent": True,
+                "ephemeral": not explicit_path and not chat_scoped,
+                "chat_scoped": chat_scoped,
+                "context_id": safe_context,
+                "error": "",
+            }
+        except Exception as fallback_exc:
+            message = f"Pillow could not convert the XWD screenshot: {exc}; fallback parser failed: {fallback_exc}"
+        local_errors.append(message)
+        if ephemeral_ref:
+            raw_path.unlink(missing_ok=True)
+            target.unlink(missing_ok=True)
+            return {
+                "ok": False,
+                "path": "",
+                "format": "",
+                "captured_at": iso_now(),
+                "recent": False,
+                "ephemeral": True,
+                "context_id": safe_context,
+                "error": message,
+            }
+        return {
+            "ok": True,
+            "path": str(raw_path),
+            "a0_path": normalize_a0_path(raw_path),
+            "format": "xwd",
+            "captured_at": iso_now(),
+            "recent": True,
+            "ephemeral": not explicit_path and not chat_scoped,
+            "chat_scoped": chat_scoped,
+            "context_id": safe_context,
+            "error": message,
+        }
+
+
+def convert_xwd_to_image(raw_path: Path, target: Path) -> dict[str, int]:
+    from PIL import Image
+
+    data = raw_path.read_bytes()
+    header, _ = parse_xwd_header(data)
+    width = header["pixmap_width"]
+    height = header["pixmap_height"]
+    bytes_per_line = header["bytes_per_line"]
+    bits_per_pixel = header["bits_per_pixel"]
+    color_table_size = header["ncolors"] * 12
+    pixel_offset = header["header_size"] + color_table_size
+    if width <= 0 or height <= 0 or bytes_per_line <= 0:
+        raise ValueError("invalid XWD dimensions")
+    pixel_size = height * bytes_per_line
+    if pixel_offset + pixel_size > len(data):
+        raise ValueError("truncated XWD pixel data")
+
+    if (header["red_mask"], header["green_mask"], header["blue_mask"]) != (
+        0x00FF0000,
+        0x0000FF00,
+        0x000000FF,
+    ):
+        raise ValueError("unsupported XWD visual masks")
+    raw_mode = {
+        (24, 0): "BGR",
+        (24, 1): "RGB",
+        (32, 0): "BGRX",
+        (32, 1): "XRGB",
+    }.get((bits_per_pixel, header["byte_order"]))
+    if not raw_mode:
+        raise ValueError(f"unsupported XWD pixel layout: {bits_per_pixel} bpp")
+
+    image = Image.frombytes(
+        "RGB",
+        (width, height),
+        data[pixel_offset : pixel_offset + pixel_size],
+        "raw",
+        raw_mode,
+        bytes_per_line,
+        1,
+    )
+    image.save(target)
+    return {"width": width, "height": height}
+
+
+def parse_xwd_header(data: bytes) -> tuple[dict[str, int], str]:
+    if len(data) < 100:
+        raise ValueError("XWD header is too short")
+    field_names = (
+        "header_size",
+        "file_version",
+        "pixmap_format",
+        "pixmap_depth",
+        "pixmap_width",
+        "pixmap_height",
+        "xoffset",
+        "byte_order",
+        "bitmap_unit",
+        "bitmap_bit_order",
+        "bitmap_pad",
+        "bits_per_pixel",
+        "bytes_per_line",
+        "visual_class",
+        "red_mask",
+        "green_mask",
+        "blue_mask",
+        "bits_per_rgb",
+        "colormap_entries",
+        "ncolors",
+        "window_width",
+        "window_height",
+        "window_x",
+        "window_y",
+        "window_bdrwidth",
+    )
+    for endian in ("big", "little"):
+        values = [int.from_bytes(data[index : index + 4], endian, signed=False) for index in range(0, 100, 4)]
+        header = dict(zip(field_names, values, strict=True))
+        if 100 <= header["header_size"] <= len(data) and header["file_version"] == 7:
+            return header, endian
+    raise ValueError("unsupported XWD header")
+
+
+def resolve_environment(*, errors: list[str] | None = None, session_id: str = SESSION_ID) -> dict[str, str]:
+    local_errors = errors if errors is not None else []
+    manifest = session_manifest_path(session_id)
+    payload: dict[str, Any] = {}
+    if manifest.exists():
+        try:
+            payload = json.loads(manifest.read_text(encoding="utf-8"))
+        except Exception as exc:
+            local_errors.append(f"Desktop session manifest is unreadable: {exc}")
+    elif not (os.environ.get("A0_DESKTOP_DISPLAY") or os.environ.get("DISPLAY")):
+        local_errors.append(f"Desktop session manifest not found at {manifest}; open the Desktop canvas before GUI control.")
+
+    display_value = str(
+        os.environ.get("A0_DESKTOP_DISPLAY")
+        or payload.get("display")
+        or os.environ.get("DISPLAY")
+        or ""
+    ).strip()
+    if display_value.startswith(":"):
+        display = display_value
+    elif display_value:
+        display = f":{display_value}"
+    else:
+        display = ""
+        local_errors.append("Desktop DISPLAY is unavailable; the persistent Desktop session is not running.")
+
+    profile_dir = _state_path_from_retired_root(
+        Path(
+            os.environ.get("A0_DESKTOP_PROFILE")
+            or os.environ.get("A0_DESKTOP_HOME")
+            or payload.get("profile_dir")
+            or os.environ.get("HOME")
+            or PROFILE_DIR / session_id
+        )
+    )
+
+    return {
+        "display": display,
+        "profile_dir": str(profile_dir),
+        "manifest": str(manifest),
+    }
+
+
+def _state_path_from_retired_root(path: Path) -> Path:
+    try:
+        relative = path.resolve(strict=False).relative_to(
+            RETIRED_STATE_DIR.resolve(strict=False)
+        )
+    except ValueError:
+        return path
+    return STATE_DIR / relative
+
+
+def display_env(*, display: str, profile_dir: str) -> dict[str, str]:
+    env = {
+        **os.environ,
+        "HOME": profile_dir,
+        "XDG_CONFIG_HOME": os.environ.get("XDG_CONFIG_HOME") or str(Path(profile_dir) / ".config"),
+        "XDG_DATA_HOME": os.environ.get("XDG_DATA_HOME") or str(Path(profile_dir) / ".local" / "share"),
+        "XDG_CACHE_HOME": os.environ.get("XDG_CACHE_HOME") or str(Path(profile_dir) / ".cache"),
+        "XDG_CURRENT_DESKTOP": os.environ.get("XDG_CURRENT_DESKTOP") or "XFCE",
+    }
+    if display:
+        env["DISPLAY"] = display
+    xauthority = os.environ.get("A0_DESKTOP_XAUTHORITY") or str(Path(profile_dir) / ".Xauthority")
+    if Path(xauthority).exists():
+        env["XAUTHORITY"] = xauthority
+    return env
+
+
+def collect_capabilities() -> dict[str, str]:
+    return {
+        name: shutil.which(name) or ""
+        for name in (
+            "xdotool",
+            "xrandr",
+            "xwininfo",
+            "xprop",
+            "xwd",
+            "xclip",
+        )
+    }
+
+
+def collect_display_size(env: dict[str, str], capabilities: dict[str, str], errors: list[str]) -> dict[str, int]:
+    if not capabilities.get("xrandr"):
+        return {"width": 0, "height": 0}
+    result = run([capabilities["xrandr"], "-q"], env=env, timeout=4)
+    if result.returncode != 0:
+        errors.append(command_output(result) or "xrandr could not read the Desktop display.")
+        return {"width": 0, "height": 0}
+    match = re.search(r"\bcurrent\s+(\d+)\s+x\s+(\d+)", result.stdout)
+    if not match:
+        errors.append("xrandr output did not include the current Desktop size.")
+        return {"width": 0, "height": 0}
+    return {"width": int(match.group(1)), "height": int(match.group(2))}
+
+
+def collect_pointer(env: dict[str, str], capabilities: dict[str, str], errors: list[str]) -> dict[str, int]:
+    if not capabilities.get("xdotool"):
+        return {"x": 0, "y": 0, "screen": 0, "window": 0}
+    result = run([capabilities["xdotool"], "getmouselocation", "--shell"], env=env, timeout=3)
+    if result.returncode != 0:
+        errors.append(command_output(result) or "xdotool could not read the pointer location.")
+        return {"x": 0, "y": 0, "screen": 0, "window": 0}
+    values = parse_shell_values(result.stdout)
+    return {
+        "x": int_value(values.get("X")),
+        "y": int_value(values.get("Y")),
+        "screen": int_value(values.get("SCREEN")),
+        "window": int_value(values.get("WINDOW")),
+    }
+
+
+def collect_active_window(env: dict[str, str], capabilities: dict[str, str], errors: list[str]) -> dict[str, Any] | None:
+    if not capabilities.get("xdotool"):
+        return None
+    result = run([capabilities["xdotool"], "getactivewindow"], env=env, timeout=3)
+    if result.returncode != 0:
+        return None
+    window_id = result.stdout.strip().splitlines()[0] if result.stdout.strip() else ""
+    if not window_id:
+        return None
+    return collect_window(env, capabilities, window_id, errors)
+
+
+def collect_windows(env: dict[str, str], capabilities: dict[str, str], errors: list[str]) -> list[dict[str, Any]]:
+    if not capabilities.get("xdotool"):
+        return []
+    result = run([capabilities["xdotool"], "search", "--onlyvisible", "--name", "."], env=env, timeout=4)
+    if result.returncode != 0:
+        detail = command_output(result)
+        if detail:
+            errors.append(detail)
+        return []
+    windows: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for window_id in result.stdout.splitlines():
+        window_id = window_id.strip()
+        if not window_id or window_id in seen:
+            continue
+        seen.add(window_id)
+        windows.append(collect_window(env, capabilities, window_id, errors))
+    return windows
+
+
+def collect_window(
+    env: dict[str, str],
+    capabilities: dict[str, str],
+    window_id: str,
+    errors: list[str],
+) -> dict[str, Any]:
+    props = collect_window_props(env, capabilities, window_id)
+    geometry = collect_window_geometry(env, capabilities, window_id)
+    return {
+        "id": str(window_id),
+        "title": props.get("title", ""),
+        "class": props.get("class", ""),
+        "name": props.get("name", ""),
+        "pid": int_value(props.get("pid")),
+        "geometry": geometry,
+    }
+
+
+def collect_window_geometry(env: dict[str, str], capabilities: dict[str, str], window_id: str) -> dict[str, int]:
+    geometry = {"x": 0, "y": 0, "width": 0, "height": 0}
+    if not capabilities.get("xwininfo"):
+        return geometry
+    result = run([capabilities["xwininfo"], "-id", str(window_id)], env=env, timeout=3)
+    if result.returncode != 0:
+        return geometry
+    patterns = {
+        "x": r"Absolute upper-left X:\s*(-?\d+)",
+        "y": r"Absolute upper-left Y:\s*(-?\d+)",
+        "width": r"Width:\s*(\d+)",
+        "height": r"Height:\s*(\d+)",
+    }
+    for key, pattern in patterns.items():
+        match = re.search(pattern, result.stdout)
+        if match:
+            geometry[key] = int(match.group(1))
+    return geometry
+
+
+def collect_window_props(env: dict[str, str], capabilities: dict[str, str], window_id: str) -> dict[str, str]:
+    props = {"title": "", "class": "", "name": "", "pid": ""}
+    xdotool = capabilities.get("xdotool")
+    if xdotool:
+        result = run([xdotool, "getwindowname", str(window_id)], env=env, timeout=3)
+        if result.returncode == 0:
+            props["title"] = result.stdout.strip()
+    xprop = capabilities.get("xprop")
+    if not xprop:
+        return props
+    result = run([xprop, "-id", str(window_id), "WM_CLASS", "WM_NAME", "_NET_WM_NAME", "_NET_WM_PID"], env=env, timeout=3)
+    if result.returncode != 0:
+        return props
+    parsed = parse_xprop(result.stdout)
+    title = parsed.get("_NET_WM_NAME") or parsed.get("WM_NAME") or props["title"]
+    props["title"] = title
+    props["class"] = parsed.get("WM_CLASS_CLASS", "")
+    props["name"] = parsed.get("WM_CLASS_NAME", "")
+    props["pid"] = parsed.get("_NET_WM_PID", "")
+    return props
+
+
+def parse_xprop(output: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for line in output.splitlines():
+        if "=" not in line:
+            continue
+        key, raw_value = line.split("=", 1)
+        key = key.strip().split("(", 1)[0]
+        raw_value = raw_value.strip()
+        quoted = re.findall(r'"([^"]*)"', raw_value)
+        if key == "WM_CLASS" and quoted:
+            values["WM_CLASS_NAME"] = quoted[0]
+            values["WM_CLASS_CLASS"] = quoted[-1]
+            continue
+        if quoted:
+            values[key] = quoted[-1]
+            continue
+        match = re.search(r"-?\d+", raw_value)
+        values[key] = match.group(0) if match else raw_value
+    return values
+
+
+def latest_screenshot(*, context_id: str = "") -> dict[str, Any]:
+    chat_dir = chat_screenshot_dir(context_id)
+    chat_latest = _latest_screenshot_from_dir(
+        chat_dir,
+        context_id=context_id,
+        ephemeral=False,
+        chat_scoped=True,
+        prune_older=False,
+    )
+    if chat_latest.get("ok"):
+        return chat_latest
+
+    prune_context_screenshots(context_id=context_id, max_age_seconds=RECENT_SCREENSHOT_SECONDS)
+    screenshot_dir = context_screenshot_dir(context_id)
+    return _latest_screenshot_from_dir(
+        screenshot_dir,
+        context_id=context_id,
+        ephemeral=True,
+        chat_scoped=False,
+        prune_older=True,
+    )
+
+
+def _latest_screenshot_from_dir(
+    screenshot_dir: Path,
+    *,
+    context_id: str = "",
+    ephemeral: bool,
+    chat_scoped: bool,
+    prune_older: bool,
+) -> dict[str, Any]:
+    if not screenshot_dir.exists():
+        return {"ok": False, "path": "", "format": "", "captured_at": "", "recent": False}
+    candidates = [
+        path
+        for path in screenshot_dir.iterdir()
+        if path.is_file() and path.suffix.lower() in _SCREENSHOT_SUFFIXES
+    ]
+    if not candidates:
+        return {"ok": False, "path": "", "format": "", "captured_at": "", "recent": False}
+    latest = max(candidates, key=lambda item: item.stat().st_mtime)
+    if prune_older:
+        for candidate in candidates:
+            if candidate != latest:
+                candidate.unlink(missing_ok=True)
+    age = max(0.0, time.time() - latest.stat().st_mtime)
+    return {
+        "ok": True,
+        "path": str(latest),
+        "a0_path": normalize_a0_path(latest),
+        "format": latest.suffix.lower().lstrip("."),
+        "captured_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(latest.stat().st_mtime)),
+        "recent": age <= RECENT_SCREENSHOT_SECONDS,
+        "ephemeral": ephemeral,
+        "chat_scoped": chat_scoped,
+        "context_id": _safe_context_id(context_id),
+    }
+
+
+def stable_state(
+    *,
+    display: str,
+    profile_dir: str,
+    context_id: str = "",
+    size: dict[str, int] | None = None,
+    pointer: dict[str, int] | None = None,
+    active_window: dict[str, Any] | None = None,
+    windows: list[dict[str, Any]] | None = None,
+    screenshot: dict[str, Any] | None = None,
+    capabilities: dict[str, str] | None = None,
+    errors: list[str] | None = None,
+) -> dict[str, Any]:
+    clean_errors = [str(error) for error in errors or [] if str(error)]
+    return {
+        "ok": not clean_errors,
+        "context_id": _safe_context_id(context_id),
+        "display": display,
+        "profile_dir": profile_dir,
+        "size": size or {"width": 0, "height": 0},
+        "pointer": pointer or {"x": 0, "y": 0, "screen": 0, "window": 0},
+        "active_window": active_window,
+        "windows": windows or [],
+        "screenshot": screenshot or {"ok": False, "path": "", "format": "", "captured_at": "", "recent": False},
+        "capabilities": capabilities or collect_capabilities(),
+        "errors": clean_errors,
+    }
+
+
+def compact_prompt_context(state: dict[str, Any] | None = None) -> str:
+    state = state if state is not None else collect_state(include_screenshot=False)
+    if not state.get("display"):
+        return ""
+    lines = ["[DESKTOP STATE]"]
+    size = state.get("size") or {}
+    pointer = state.get("pointer") or {}
+    lines.append(
+        f"- display={state.get('display', '')} size={size.get('width', 0)}x{size.get('height', 0)} "
+        f"pointer={pointer.get('x', 0)},{pointer.get('y', 0)}"
+    )
+    active = state.get("active_window") or {}
+    if active:
+        lines.append(
+            f"- active={active.get('title', '') or '<untitled>'} "
+            f"class={active.get('class', '') or active.get('name', '')}"
+        )
+    visible = []
+    for window in state.get("windows") or []:
+        title = window.get("title") or "<untitled>"
+        window_class = window.get("class") or window.get("name") or ""
+        visible.append(f"{title} ({window_class})" if window_class else title)
+        if len(visible) >= 5:
+            break
+    if visible:
+        lines.append("- visible=" + "; ".join(visible))
+    screenshot = state.get("screenshot") or {}
+    if screenshot.get("recent") and screenshot.get("path"):
+        ephemeral = " ephemeral" if screenshot.get("ephemeral") else ""
+        screenshot_ref = screenshot.get("a0_path") or screenshot["path"]
+        lines.append(f"- recent_screenshot={screenshot_ref}{ephemeral}")
+    context_id = str(state.get("context_id") or "").strip()
+    if context_id:
+        lines.append(f"- screenshot_context={context_id}")
+    context_arg = f" --context-id {context_id}" if context_id else ""
+    lines.append(
+        "- next=plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh state --json"
+        f"{context_arg} for structured checks; use observe --json --screenshot"
+        f"{context_arg} "
+        "before coordinate or visual-OCR actions; prefer sequence/focus/key/paste/save/app-native helpers first."
+    )
+    lines.append(
+        "- verify=for terminal/CLI-agent output, use the screenshot path from a fresh final "
+        "observe --json --screenshot captured after the response appears."
+    )
+    if state.get("errors"):
+        lines.append("- errors=" + "; ".join(str(item) for item in state["errors"][:2]))
+    return "\n".join(lines)
+
+
+def parse_shell_values(output: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for line in output.splitlines():
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip('"')
+    return values
+
+
+def int_value(value: Any, default: int = 0) -> int:
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return default
+
+
+def run(command: list[str], *, env: dict[str, str], timeout: float) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+    except OSError as exc:
+        return subprocess.CompletedProcess(command, 127, "", str(exc))
+    except subprocess.TimeoutExpired as exc:
+        stdout = exc.stdout.decode("utf-8", errors="replace") if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+        stderr = exc.stderr.decode("utf-8", errors="replace") if isinstance(exc.stderr, bytes) else (exc.stderr or "")
+        return subprocess.CompletedProcess(command, 124, stdout, stderr or "command timed out")
+
+
+def command_output(result: subprocess.CompletedProcess[str]) -> str:
+    return (result.stderr or result.stdout or "").strip()
+
+
+def image_width(path: Path) -> int:
+    try:
+        from PIL import Image
+
+        with Image.open(path) as image:
+            return int(image.width)
+    except Exception:
+        return 0
+
+
+def image_height(path: Path) -> int:
+    try:
+        from PIL import Image
+
+        with Image.open(path) as image:
+            return int(image.height)
+    except Exception:
+        return 0
+
+
+def ephemeral_screenshot_result(
+    path: Path,
+    *,
+    context_id: str = "",
+    image_format: str = "png",
+    width: int = 0,
+    height: int = 0,
+) -> dict[str, Any]:
+    from helpers import ephemeral_images
+
+    mime = "image/jpeg" if image_format.lower() in {"jpg", "jpeg"} else "image/png"
+    safe_context = _safe_context_id(context_id)
+    ref = ephemeral_images.put_image_bytes(
+        context_id=str(context_id or "").strip(),
+        mime=mime,
+        payload=path.read_bytes(),
+        name=path.name,
+    )
+    path.unlink(missing_ok=True)
+    prune_context_screenshots(context_id=context_id)
+    return {
+        "ok": True,
+        "path": "",
+        "format": image_format,
+        "mime": mime,
+        "width": width,
+        "height": height,
+        "captured_at": iso_now(),
+        "recent": True,
+        "ephemeral": True,
+        "ephemeral_ref": ref,
+        "context_id": safe_context,
+        "vision_load": {
+            "tool_name": "vision_load",
+            "tool_args": {"paths": [ref]},
+        },
+        "error": "",
+    }
+
+
+def prune_context_screenshots(
+    *,
+    context_id: str = "",
+    keep_path: Path | None = None,
+    max_age_seconds: float | None = None,
+) -> None:
+    screenshot_dir = context_screenshot_dir(context_id)
+    if not screenshot_dir.exists():
+        return
+    keep = keep_path.resolve(strict=False) if keep_path else None
+    now = time.time()
+    for candidate in screenshot_dir.iterdir():
+        if not candidate.is_file() or candidate.suffix.lower() not in _SCREENSHOT_SUFFIXES:
+            continue
+        if keep is not None and candidate.resolve(strict=False) == keep:
+            continue
+        if max_age_seconds is not None:
+            try:
+                if now - candidate.stat().st_mtime <= max_age_seconds:
+                    continue
+            except OSError:
+                pass
+        candidate.unlink(missing_ok=True)
+    try:
+        screenshot_dir.rmdir()
+    except OSError:
+        pass
+
+
+def iso_now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Observe the Agent Zero persistent Linux Desktop state.")
+    subparsers = parser.add_subparsers(dest="command")
+
+    state_parser = subparsers.add_parser("state")
+    state_parser.add_argument("--json", action="store_true")
+    state_parser.add_argument("--screenshot", action="store_true")
+    state_parser.add_argument("--context-id", default="")
+
+    observe_parser = subparsers.add_parser("observe")
+    observe_parser.add_argument("--json", action="store_true")
+    observe_parser.add_argument("--screenshot", action="store_true")
+    observe_parser.add_argument("--context-id", default="")
+
+    screenshot_parser = subparsers.add_parser("screenshot")
+    screenshot_parser.add_argument("path", nargs="?")
+    screenshot_parser.add_argument("--json", action="store_true")
+    screenshot_parser.add_argument("--context-id", default="")
+
+    args = parser.parse_args(argv)
+    command = args.command or "state"
+    if command in {"state", "observe"}:
+        payload = collect_state(
+            include_screenshot=bool(args.screenshot),
+            context_id=str(args.context_id or ""),
+            screenshot_transport="path",
+        )
+        print(json.dumps(payload, sort_keys=True))
+        return 0 if payload.get("ok") else 1
+
+    if command == "screenshot":
+        errors: list[str] = []
+        env_info = resolve_environment(errors=errors)
+        payload = capture_screenshot(
+            display_env(display=env_info["display"], profile_dir=env_info["profile_dir"]),
+            collect_capabilities(),
+            path=args.path,
+            errors=errors,
+            context_id=str(args.context_id or ""),
+            transport="path",
+        )
+        if args.json:
+            print(json.dumps(payload, sort_keys=True))
+        else:
+            print(payload.get("path") or payload.get("error") or "")
+        return 0 if payload.get("ok") else 1
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plugins/_desktop/helpers/prompt_context.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from plugins._desktop.helpers import desktop_state
+
+
+def build_context(context_id: str = "") -> str:
+    if not desktop_state.session_manifest_exists():
+        return ""
+    try:
+        return desktop_state.compact_prompt_context(
+            desktop_state.collect_state(include_screenshot=False, context_id=context_id),
+        )
+    except Exception as exc:
+        return (
+            "[DESKTOP STATE]\n"
+            f"- unavailable={exc}\n"
+            "- next=Open the Desktop surface manually, then run plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh observe --json."
+        )

plugins/_desktop/hooks.py

@@ -0,0 +1,456 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from helpers import files, state_migration, system_packages
+
+LIBREOFFICE_RUNTIME_PACKAGES = (
+    "libreoffice-core",
+    "libreoffice-writer",
+    "libreoffice-calc",
+    "libreoffice-impress",
+    "libreoffice-gtk3",
+    "python3-uno",
+)
+XPRA_SOURCE_FILE = Path("/etc/apt/sources.list.d/xpra.sources")
+XPRA_KEYRING_FILE = Path("/usr/share/keyrings/xpra.asc")
+XPRA_KEY_URL = "https://xpra.org/xpra.asc"
+XPRA_VERSION = "6.5.2-r0-1"
+GTK_RUNTIME_PACKAGE = "gir1.2-gtk-3.0"
+KALI_ROLLING_SOURCE = "deb http://http.kali.org/kali kali-rolling main contrib non-free non-free-firmware\n"
+XPRA_VERSIONED_RUNTIME_PACKAGES = frozenset(
+    {
+        "xpra-common",
+        "xpra-server",
+        "xpra-client",
+        "xpra-client-gtk3",
+        "xpra-x11",
+    }
+)
+RUNTIME_PACKAGES = (
+    *LIBREOFFICE_RUNTIME_PACKAGES,
+    GTK_RUNTIME_PACKAGE,
+    "xpra-common",
+    "xpra-server",
+    "xpra-client",
+    "xpra-client-gtk3",
+    "xpra-x11",
+    "xpra-html5",
+    "xfce4-session",
+    "xfwm4",
+    "xfce4-panel",
+    "xfdesktop4",
+    "xfce4-settings",
+    "thunar",
+    "gvfs",
+    "libglib2.0-bin",
+    "xfce4-terminal",
+    "x11-xserver-utils",
+    "x11-utils",
+    "x11-apps",
+    "xdotool",
+    "xclip",
+    "xauth",
+    "dbus-x11",
+    "python3-pil",
+    "fonts-dejavu",
+    "fonts-liberation",
+    "fonts-crosextra-caladea",
+    "fonts-crosextra-carlito",
+    "fonts-noto-core",
+    "fonts-noto-cjk",
+    "fonts-noto-color-emoji",
+)
+RETIRED_RUNTIME_PACKAGES = (
+    "firefox-esr",
+)
+PLUGIN_NAME = "_desktop"
+STATE_DIR = Path(files.get_abs_path("usr", "plugins", PLUGIN_NAME))
+RETIRED_STATE_DIR = Path(files.get_abs_path("usr", PLUGIN_NAME))
+_preparation_lock = threading.RLock()
+_preparation_state: dict[str, Any] = {
+    "preparing": False,
+    "active_count": 0,
+    "started_at": 0.0,
+    "completed_at": 0.0,
+    "result": None,
+    "error": "",
+}
+
+
+def cleanup_stale_runtime_state(force: bool = False) -> dict[str, Any]:
+    """Prepare the Linux Desktop runtime and reap stale Desktop sessions."""
+
+    _begin_runtime_preparation()
+    result: dict[str, Any] | None = None
+    error = ""
+    try:
+        installed: list[str] = []
+        removed: list[str] = []
+        migrated: list[str] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+
+        _migrate_retired_plugin_state(migrated, warnings, errors)
+        _remove_persisted_screenshots(warnings, errors)
+
+        retired_packages = _installed_packages(RETIRED_RUNTIME_PACKAGES)
+        if retired_packages:
+            _purge_packages(removed, errors, installed_packages=retired_packages)
+
+        _ensure_runtime_dependencies(installed, errors)
+        _cleanup_desktop_sessions(errors)
+
+        result = {
+            "ok": not errors,
+            "skipped": False,
+            "removed": removed,
+            "installed": installed,
+            "migrated": migrated,
+            "warnings": warnings,
+            "errors": errors,
+        }
+        return result
+    except Exception as exc:
+        error = str(exc)
+        raise
+    finally:
+        _finish_runtime_preparation(result=result, error=error)
+
+
+def runtime_preparation_status() -> dict[str, Any]:
+    with _preparation_lock:
+        return {
+            "preparing": bool(_preparation_state["preparing"]),
+            "active_count": int(_preparation_state["active_count"]),
+            "started_at": float(_preparation_state["started_at"]),
+            "completed_at": float(_preparation_state["completed_at"]),
+            "result": _preparation_state["result"],
+            "error": str(_preparation_state["error"]),
+        }
+
+
+def _migrate_retired_plugin_state(
+    migrated: list[str],
+    warnings: list[str],
+    errors: list[str],
+) -> None:
+    state_migration.migrate_retired_state_tree(
+        source=RETIRED_STATE_DIR,
+        destination=STATE_DIR,
+        owner="Desktop",
+        migrated=migrated,
+        warnings=warnings,
+        errors=errors,
+    )
+
+
+def _remove_persisted_screenshots(
+    warnings: list[str],
+    errors: list[str],
+) -> None:
+    screenshots_dir = STATE_DIR / "screenshots"
+    if not screenshots_dir.exists():
+        return
+    try:
+        shutil.rmtree(screenshots_dir)
+        warnings.append(f"Removed retired persistent Desktop screenshots: {screenshots_dir}")
+    except Exception as exc:
+        errors.append(f"Failed to remove retired persistent Desktop screenshots at {screenshots_dir}: {exc}")
+
+
+def _begin_runtime_preparation() -> None:
+    with _preparation_lock:
+        if not _preparation_state["active_count"]:
+            _preparation_state["preparing"] = True
+            _preparation_state["started_at"] = time.time()
+            _preparation_state["completed_at"] = 0.0
+            _preparation_state["result"] = None
+            _preparation_state["error"] = ""
+        _preparation_state["active_count"] = int(_preparation_state["active_count"]) + 1
+
+
+def _finish_runtime_preparation(
+    *,
+    result: dict[str, Any] | None = None,
+    error: str = "",
+) -> None:
+    with _preparation_lock:
+        active_count = max(0, int(_preparation_state["active_count"]) - 1)
+        _preparation_state["active_count"] = active_count
+        if result is not None:
+            _preparation_state["result"] = result
+        if error:
+            _preparation_state["error"] = error
+        if active_count:
+            return
+        _preparation_state["preparing"] = False
+        _preparation_state["completed_at"] = time.time()
+
+
+def _installed_packages(packages: tuple[str, ...]) -> list[str]:
+    if not shutil.which("dpkg-query"):
+        return []
+    return [package for package in packages if _package_installed(package)]
+
+
+def _package_installed(package: str) -> bool:
+    result = subprocess.run(
+        ["dpkg-query", "-W", "-f=${Status}", package],
+        check=False,
+        text=True,
+        capture_output=True,
+        timeout=8,
+    )
+    return result.returncode == 0 and "install ok installed" in result.stdout
+
+
+def _package_version(package: str) -> str:
+    result = subprocess.run(
+        ["dpkg-query", "-W", "-f=${Version}", package],
+        check=False,
+        text=True,
+        capture_output=True,
+        timeout=8,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _purge_packages(
+    removed: list[str],
+    errors: list[str],
+    *,
+    installed_packages: list[str] | None = None,
+) -> None:
+    if os.geteuid() != 0 or not shutil.which("apt-get") or not shutil.which("dpkg-query"):
+        return
+    installed = installed_packages if installed_packages is not None else []
+    if not installed:
+        return
+    result = _run_apt_command(["apt-get", "purge", "-y", *installed], timeout=180)
+    if result.returncode == 0:
+        removed.extend(installed)
+        return
+    errors.append((result.stderr or result.stdout or "apt-get purge failed").strip())
+
+
+def _ensure_runtime_dependencies(installed: list[str], errors: list[str]) -> None:
+    if os.geteuid() != 0 or not shutil.which("apt-get") or not shutil.which("dpkg-query"):
+        return
+    if not _ensure_kali_gtk_runtime(installed, errors):
+        return
+    missing = [package for package in RUNTIME_PACKAGES if not _package_installed(package)]
+    if not missing:
+        return
+
+    if not _apt_update(errors):
+        return
+
+    required_xpra_missing = [package for package in missing if package.startswith("xpra")]
+    if required_xpra_missing and not _package_candidates_available(required_xpra_missing):
+        previous_error_count = len(errors)
+        _ensure_xpra_repository(installed, errors)
+        if len(errors) > previous_error_count or not _apt_update(errors):
+            return
+        missing = [package for package in RUNTIME_PACKAGES if not _package_installed(package)]
+        if not missing:
+            return
+
+    if missing:
+        _install_runtime_packages(missing, installed, errors)
+
+
+def _ensure_kali_gtk_runtime(installed: list[str], errors: list[str]) -> bool:
+    if (
+        GTK_RUNTIME_PACKAGE not in RUNTIME_PACKAGES
+        or _package_installed(GTK_RUNTIME_PACKAGE)
+        or _read_os_release().get("ID") != "kali"
+    ):
+        return True
+
+    with tempfile.TemporaryDirectory(prefix="a0-desktop-apt-") as directory:
+        source = Path(directory) / "kali-rolling.list"
+        source.write_text(KALI_ROLLING_SOURCE, encoding="utf-8")
+        options = [
+            "-o",
+            f"Dir::Etc::sourcelist={source}",
+            "-o",
+            "Dir::Etc::sourceparts=-",
+        ]
+        result = _run_apt_command(["apt-get", *options, "update"], timeout=300)
+        if result.returncode == 0:
+            result = _run_apt_command(
+                [
+                    "apt-get",
+                    *options,
+                    "install",
+                    "-y",
+                    "--no-install-recommends",
+                    GTK_RUNTIME_PACKAGE,
+                ],
+                timeout=900,
+            )
+        if result.returncode == 0:
+            installed.append(GTK_RUNTIME_PACKAGE)
+            return True
+        errors.append((result.stderr or result.stdout or "GTK runtime install failed").strip())
+        return False
+
+
+def _install_runtime_packages(
+    packages: list[str],
+    installed: list[str],
+    errors: list[str],
+) -> bool:
+    xpra_version = ""
+    if any(package in XPRA_VERSIONED_RUNTIME_PACKAGES for package in packages):
+        xpra_version = _package_version("xpra-common") or XPRA_VERSION
+    package_specs = [
+        f"{package}={xpra_version}" if package in XPRA_VERSIONED_RUNTIME_PACKAGES else package
+        for package in packages
+    ]
+    result = _run_apt_command(
+        ["apt-get", "install", "-y", "--no-install-recommends", *package_specs],
+        timeout=900,
+    )
+    if result.returncode == 0:
+        installed.extend(packages)
+        return True
+    output = (result.stderr or result.stdout or "apt-get install failed").strip()
+    errors.append(output)
+    return False
+
+
+def _apt_update(errors: list[str]) -> bool:
+    result = _run_apt_command(["apt-get", "update"], timeout=300)
+    if result.returncode == 0:
+        return True
+    errors.append((result.stderr or result.stdout or "apt-get update failed").strip())
+    return False
+
+
+def _package_candidate_available(package: str) -> bool:
+    if not shutil.which("apt-cache"):
+        return True
+    result = subprocess.run(
+        ["apt-cache", "policy", package],
+        check=False,
+        text=True,
+        capture_output=True,
+        timeout=15,
+    )
+    if result.returncode != 0:
+        return True
+    if not result.stdout.strip():
+        return False
+    return "Candidate: (none)" not in result.stdout
+
+
+def _package_candidates_available(packages: list[str]) -> bool:
+    return all(_package_candidate_available(package) for package in packages)
+
+
+def _ensure_xpra_repository(installed: list[str], errors: list[str]) -> None:
+    if not _package_installed("ca-certificates"):
+        result = _run_apt_command(
+            ["apt-get", "install", "-y", "--no-install-recommends", "ca-certificates"],
+            timeout=180,
+        )
+        if result.returncode != 0:
+            errors.append((result.stderr or result.stdout or "apt-get install ca-certificates failed").strip())
+            return
+        installed.append("ca-certificates")
+
+    try:
+        key = _download(XPRA_KEY_URL)
+        XPRA_KEYRING_FILE.parent.mkdir(parents=True, exist_ok=True)
+        if not XPRA_KEYRING_FILE.exists() or XPRA_KEYRING_FILE.read_bytes() != key:
+            XPRA_KEYRING_FILE.write_bytes(key)
+
+        XPRA_SOURCE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        source = _xpra_repository_source()
+        if not XPRA_SOURCE_FILE.exists() or XPRA_SOURCE_FILE.read_text(encoding="utf-8") != source:
+            XPRA_SOURCE_FILE.write_text(source, encoding="utf-8")
+    except Exception as exc:
+        errors.append(f"Xpra repository setup failed: {exc}")
+
+
+def _download(url: str) -> bytes:
+    with urllib.request.urlopen(url, timeout=45) as response:
+        return response.read()
+
+
+def _run_apt_command(command: list[str], *, timeout: int) -> subprocess.CompletedProcess[str]:
+    return system_packages.run_apt_with_retries(
+        lambda: subprocess.run(
+            command,
+            check=False,
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            env={**os.environ, "DEBIAN_FRONTEND": "noninteractive"},
+        )
+    )
+
+
+def _xpra_repository_source() -> str:
+    os_release = _read_os_release()
+    os_id = os_release.get("ID", "")
+    codename = os_release.get("VERSION_CODENAME", "")
+    arch = _dpkg_architecture()
+
+    uri = "https://xpra.org"
+    suite = "trixie" if os_id == "kali" or codename in {"sid", "forky"} else codename or "trixie"
+
+    return (
+        f"Types: deb\n"
+        f"URIs: {uri}\n"
+        f"Suites: {suite}\n"
+        f"Components: main\n"
+        f"Signed-By: {XPRA_KEYRING_FILE}\n"
+        f"Architectures: {arch}\n"
+    )
+
+
+def _read_os_release() -> dict[str, str]:
+    path = Path("/etc/os-release")
+    if not path.exists():
+        return {}
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key] = value.strip().strip('"')
+    return values
+
+
+def _dpkg_architecture() -> str:
+    result = subprocess.run(
+        ["dpkg", "--print-architecture"],
+        check=False,
+        text=True,
+        capture_output=True,
+        timeout=8,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    return "amd64"
+
+
+def _cleanup_desktop_sessions(errors: list[str]) -> None:
+    try:
+        from plugins._desktop.helpers import desktop_session
+
+        result = desktop_session.cleanup_stale_runtime_state()
+        errors.extend(str(item) for item in result.get("errors") or [])
+    except Exception as exc:
+        errors.append(f"Desktop cleanup failed: {exc}")

plugins/_desktop/plugin.yaml

@@ -0,0 +1,5 @@
+name: _desktop
+title: Desktop
+description: Owns the Agent Zero Linux Desktop runtime, Xpra/Xfce sessions, and live Desktop surface.
+version: 1.0.0
+always_enabled: false

plugins/_desktop/prompts/agent.extras.desktop_state.md

@@ -0,0 +1 @@
+{{desktop_state}}

plugins/_desktop/skills/linux-desktop/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: linux-desktop
+description: Use only for Agent Zero's built-in Docker/Xpra Linux Desktop, XFCE apps, LibreOffice GUI apps, file manager, terminal, or visual workflows inside the Agent Zero runtime. Not for A0 CLI /computer-use or computer_use_remote host control.
+version: "0.3.0"
+author: "Agent Zero Core Team"
+tags: ["linux", "desktop", "xfce", "libreoffice", "gui", "files", "terminal"]
+triggers:
+  - "Agent Zero Desktop"
+  - "built-in Linux Desktop"
+  - "Xpra Desktop"
+  - "XFCE Desktop"
+  - "LibreOffice GUI in Desktop"
+  - "Desktop file manager"
+  - "Docker desktop terminal"
+allowed_tools:
+  - office_artifact
+  - code_execution_tool
+---
+
+# Linux Desktop Interface
+
+## Boundary With Host Computer Use
+
+This skill is only for the built-in Desktop surface running inside Agent Zero's Docker/runtime Xpra session. It does not control the user's host OS, real monitor, local Ubuntu/Wayland session, macOS desktop, or Windows desktop.
+
+If the user asks for `/computer-use`, "my computer", "host machine", "local desktop", screenshots of the user's screen, hiding/minimizing a window on their screen, or any connected A0 CLI Computer Use task, do not use this skill, `desktopctl.sh`, Xpra, `code_execution_tool`, or Docker shell commands. Load `host-computer-use` and use `computer_use_remote`; if unavailable, tell the user to enable `/computer-use on`.
+
+`desktopctl.sh` only targets the internal Agent Zero Xpra display. It cannot observe or control the user's connected host screen.
+
+Use the Desktop as a full Linux GUI when the user explicitly needs a visual workflow, an installed desktop app, or manual layout polish that is awkward through structured file edits alone. Agent Zero may warm the persistent Desktop runtime during initial startup, but visible Desktop surface use remains opt-in. The Desktop is opt-in at the UI level: do not open a surface just because the user asks for a document. Use structured tools first for deterministic content changes, then use the Desktop for inspection, GUI-only actions, and final visual confirmation.
+
+## Operating Model
+
+The Desktop is a structured-first X11 control surface. Use this decision hierarchy:
+
+1. Prefer structured tools such as `office_artifact` for deterministic Office file creation, reads, and edits.
+2. Prefer structured Desktop state and window commands: `check`, `state --json`, `windows`, `active-window`, `geometry`, and `wait-window`.
+3. Prefer app-native helpers for visible live edits, such as `desktopctl.sh calc-set-cell` for Calc/UNO spreadsheet changes.
+4. Prefer launcher commands, window focus, keyboard shortcuts, menus, paste, and save commands. Batch multi-step actions with `sequence`/`batch` so one helper process drives the flow.
+5. Use screenshots for visual inspection, OCR, coordinate work, and final evidence when the task depends on pixels. Do not take screenshots merely to learn window titles or readiness that structured state already reports.
+6. Use coordinate clicks only as a last resort, and only after a fresh screenshot observation.
+7. After any GUI action, verify through Desktop state, active window titles, screenshots when visually necessary, saved file state, or exported output.
+8. For terminal or CLI-agent work, prefer deterministic command output or saved transcripts. When exact visible terminal text matters, verify against a fresh final `observe --json --screenshot` captured after the command has finished or visibly returned to an input prompt. Agent-facing Desktop screenshots are ephemeral refs; `desktopctl` shell observations with `--context-id` return chat-scoped screenshot paths. Do not report from an earlier screenshot path.
+
+Keep these standing rules:
+
+1. Treat Markdown as first-class, but use the separate Editor surface for it. For writing, notes, reports, and drafts with no explicit binary Office requirement, create Markdown and let the user open it in Editor instead of Desktop.
+2. Treat ODF as first-class for LibreOffice office work: ODT in Writer, ODS in Calc, ODP in Impress. Use DOCX/XLSX/PPTX only for explicit OOXML compatibility.
+3. Use the Desktop only when the user asks for the Desktop, a GUI app, binary Office visual work, or visual confirmation.
+4. Never open the Desktop surface automatically from a tool result if the user has not opened it. Offer an explicit Open in Desktop action instead.
+5. Launch common apps from the Desktop icons, the header buttons, or `/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh`.
+6. Use the external Agent Zero Browser for web browsing. Do not launch an operating-system browser in this version.
+7. Verify GUI work by observing the desktop state, checking window titles, and saving the file before reporting success. If exact terminal text matters, load or inspect the screenshot path returned by the final observation, not a screenshot captured before the text appeared.
+
+## Control Flow
+
+Use the helper script when the Desktop is already open and you need reliable app launches, clicks, keystrokes, or window checks from the agent shell. In the live Agent Zero runtime, prefer the absolute path so the command works from any current directory:
+
+```bash
+DESKTOP=/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh
+$DESKTOP check
+$DESKTOP state --json
+$DESKTOP observe --json
+$DESKTOP launch calc
+$DESKTOP wait-window LibreOffice
+$DESKTOP windows LibreOffice
+$DESKTOP focus LibreOffice
+$DESKTOP key ctrl+s
+```
+
+The script targets the persistent `agent-zero-desktop` X display, sets `DISPLAY`, `XAUTHORITY`, and `HOME` to the XFCE profile, then uses `xdotool` for input. Startup normally prepares this session. If `check` fails during explicit Desktop work, report that the Desktop runtime is not ready instead of installing packages ad hoc.
+
+If `state --json` or `observe --json` shows a reachable display and visible Desktop/window entries, the Desktop is usable even when `active_window` is `null`; a bare XFCE desktop can have no active application window. Treat missing display or unavailable `xdotool` as blockers and stop with the specific readiness message instead of repeating clicks or inventing a fallback. Use `observe --json --screenshot` only when you need pixels, and treat unavailable `xwd` as a screenshot blocker rather than a general Desktop blocker. Shell screenshots captured with `--context-id` live in the owning chat's screenshot folder; screenshots without a chat context remain temporary.
+
+For direct app launches without coordinates:
+
+```bash
+DESKTOP=/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh
+$DESKTOP launch writer
+$DESKTOP launch calc
+$DESKTOP launch impress
+$DESKTOP launch terminal
+$DESKTOP launch settings
+$DESKTOP open-path /a0/usr/workdir
+$DESKTOP focus "LibreOffice"
+$DESKTOP paste-text "Text to insert"
+$DESKTOP key ctrl+s
+```
+
+For multi-step window or terminal actions, batch commands through one helper process:
+
+```bash
+DESKTOP=/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh
+$DESKTOP sequence - <<'EOF'
+focus Terminal
+paste-text echo ready
+key Return
+state --json
+EOF
+```
+
+Use one command per line. `paste-text` joins the remaining words on that line, so it is suitable for ordinary command text; for complex multiline payloads, write the payload to a file or invoke `paste-text` directly.
+
+For live spreadsheet coworking, use the Calc helper instead of hand-written UNO snippets:
+
+```bash
+DESKTOP=/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh
+$DESKTOP calc-set-cell /a0/usr/workdir/example.xlsx Sheet1 B2 "Cowork verified live"
+```
+
+This opens the workbook in the visible Desktop Calc session if needed, changes the cell through LibreOffice, saves the workbook, and verifies the `.xlsx` on disk. Because the edit happens through the running LibreOffice session, the user can see the sheet update without refreshing the Desktop surface.
+
+For coordinate actions, clicks are explicitly last resort. First try `launch`, `open-path`, `wait-window`, `focus`, `key`, `paste-text`, `save`, or an app-native helper. If a coordinate action is still necessary, base it on a fresh screenshot observation and verify immediately afterward:
+
+```bash
+DESKTOP=/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh
+$DESKTOP observe --json --screenshot
+$DESKTOP click 120 180
+$DESKTOP dblclick 120 180
+$DESKTOP right-click 120 180
+$DESKTOP drag 120 180 400 180
+$DESKTOP scroll down 3
+$DESKTOP type "Text to enter"
+$DESKTOP observe --json
+```
+
+When browser automation is available, the higher-level QA flow is:
+
+1. Open `http://127.0.0.1:32080`.
+2. Open the Desktop surface from the UI or with `Alpine.store("rightCanvas").open("desktop")`.
+3. Use browser mouse events into the Xpra iframe for real user-path testing.
+4. Cross-check with `desktopctl.sh location` and `desktopctl.sh windows PATTERN`.
+5. Capture the browser screenshot as visual evidence.
+
+## Terminal And CLI Agent Verification
+
+Terminal apps are visual state, not structured logs. When the task depends on exact terminal output, follow this stricter loop:
+
+1. Run `desktopctl.sh state --json` or `desktopctl.sh windows Terminal` before acting to confirm the target window. Add `observe --json --screenshot` only if the current prompt or screen contents must be read visually.
+2. Use `sequence`, `focus`, `paste-text` or `type`, and `key Return` to drive the terminal. Prefer CLI-native commands and keyboard input over clicks.
+3. Wait until the CLI has visibly produced a response or returned to an input prompt.
+4. If exact visible text matters and no deterministic transcript was saved, run a new final `desktopctl.sh observe --json --screenshot`.
+5. Verify exact text only from the screenshot path returned by that final observation, or from a newer screenshot. Never use an earlier screenshot path as final evidence.
+6. If the final screenshot is cropped, stale, or unreadable, capture another screenshot or report the result as unverified with that specific reason.
+
+For nested CLI agents, a successful proof requires both the input prompt and the nested agent's visible response in the final screenshot, or another deterministic saved transcript produced by the CLI itself.
+
+Guard the boundary between the shell and the target CLI carefully:
+
+- A shell prompt such as `root@...#` means the target CLI is not currently receiving chat input. Never paste natural-language text into that shell prompt unless it is deliberately quoted as an argument to a shell command.
+- If launching a CLI by name can fail, use a shell-safe fallback command and wait for the CLI's own prompt before sending the user's natural-language message.
+- After a launch failure such as `command not found`, do not continue by sending the chat message. Start the fallback CLI command or report the blocker.
+- A prompt like `>`, `Implement {feature}`, or a CLI-specific input box inside the terminal is different from a shell prompt. Only then should `paste-text "natural language"` followed by `key Return` be used as chat input.
+
+Example for a nested CLI-agent smoke test:
+
+```bash
+DESKTOP=/a0/plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh
+$DESKTOP sequence - <<'EOF'
+focus Terminal
+paste-text TARGET_CLI="example-cli-agent"; FALLBACK_CMD=""; if command -v "$TARGET_CLI" >/dev/null 2>&1; then "$TARGET_CLI"; elif [ -n "$FALLBACK_CMD" ]; then sh -lc "$FALLBACK_CMD"; else echo "CLI agent not found: $TARGET_CLI"; fi
+key Return
+EOF
+$DESKTOP observe --json --screenshot
+# Verify the screenshot shows the target CLI prompt, not a shell prompt, before sending natural language:
+$DESKTOP sequence - <<'EOF'
+paste-text Reply with exactly the requested smoke-test token.
+key Return
+EOF
+$DESKTOP observe --json --screenshot
+```
+
+## Desktop Locations
+
+The Desktop exposes stable folders for common user work:
+
+- `Workdir` -> configured Agent Zero workdir (default `/a0/usr/workdir`)
+- `Projects` -> `/a0/usr/projects`
+- `Skills` -> `/a0/usr/skills`
+- `Agents` -> `/a0/usr/agents`
+- `Downloads` -> `/a0/usr/downloads`
+
+Use these folders when the user asks to inspect or manipulate project files, skills, agent profiles, or downloaded artifacts from the GUI.
+
+## App Map
+
+- `LibreOffice Writer`: ODT word processing and DOCX compatibility layout.
+- `LibreOffice Calc`: ODS spreadsheets, formulas, tables, charts, and XLSX compatibility.
+- `LibreOffice Impress`: ODP presentations, slide polish, and PPTX compatibility.
+- `Workdir`: graphical file management with Thunar at the configured Agent Zero workdir (default `/a0/usr/workdir`).
+- `Terminal`: shell work inside the Agent Zero runtime.
+- `Settings`: XFCE system settings.
+
+## Practical Rules
+
+- Keep installs inside normal plugin hook or image install flows; do not install packages ad hoc just to complete one desktop action.
+- The persistent Desktop can be running in the background while the canvas stays closed; that is expected and still respects user ownership of the visible UI.
+- Do not treat closing a document tab as closing the whole Desktop. The Desktop is persistent while Agent Zero is running.
+- Save before sync or final verification when the GUI app has edited a file.
+- If a GUI action is flaky, switch to structured file editing for content and return to the Desktop only for visual confirmation.
+- For live Calc edits that the user should see immediately, prefer `desktopctl.sh calc-set-cell FILE SHEET CELL VALUE`.
+- For enterprise workflows, leave printing available.

plugins/_desktop/skills/linux-desktop/scripts/calc_set_cell.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Set a Calc cell through the visible LibreOffice desktop session."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import time
+import zipfile
+from pathlib import Path
+import xml.etree.ElementTree as ET
+
+for candidate in ("/usr/lib/python3/dist-packages", "/usr/lib/libreoffice/program"):
+    if candidate not in sys.path:
+        sys.path.insert(0, candidate)
+
+try:
+    import uno
+except Exception as exc:  # pragma: no cover - exercised in the container runtime.
+    raise SystemExit(f"LibreOffice UNO is not available: {exc}") from exc
+
+
+UNO_URL = "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext"
+OOXML_MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+OOXML_REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+REL_PACKAGE_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+NS = {"m": OOXML_MAIN_NS, "r": OOXML_REL_NS, "rel": REL_PACKAGE_NS}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Open an XLSX in visible LibreOffice Calc, edit one cell, save, and verify."
+    )
+    parser.add_argument("file")
+    parser.add_argument("sheet")
+    parser.add_argument("cell")
+    parser.add_argument("value", nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+    if not args.value:
+        parser.error("value is required")
+    args.value = " ".join(args.value)
+    return args
+
+
+def run_quiet(command: list[str], *, timeout: float | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        command,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+        timeout=timeout,
+    )
+
+
+def dismiss_document_in_use_dialogs() -> None:
+    xdotool = shutil.which("xdotool")
+    if not xdotool:
+        return
+    found = subprocess.run(
+        [xdotool, "search", "--onlyvisible", "--name", "Document in Use"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        check=False,
+    )
+    for window_id in found.stdout.splitlines():
+        if window_id.strip():
+            run_quiet([xdotool, "windowclose", window_id.strip()], timeout=2)
+
+
+def connect_once():
+    local_ctx = uno.getComponentContext()
+    resolver = local_ctx.ServiceManager.createInstanceWithContext(
+        "com.sun.star.bridge.UnoUrlResolver",
+        local_ctx,
+    )
+    return resolver.resolve(os.environ.get("A0_DESKTOP_UNO_URL", UNO_URL))
+
+
+def desktop_from_context(ctx):
+    return ctx.ServiceManager.createInstanceWithContext("com.sun.star.frame.Desktop", ctx)
+
+
+def component_url(component) -> str:
+    try:
+        return getattr(component, "URL", "") or ""
+    except Exception:
+        return ""
+
+
+def component_title(component) -> str:
+    try:
+        return getattr(component, "Title", "") or ""
+    except Exception:
+        return ""
+
+
+def component_has_sheets(component) -> bool:
+    try:
+        component.getSheets()
+        return True
+    except Exception:
+        return False
+
+
+def url_to_path(url: str) -> str:
+    if not url:
+        return ""
+    try:
+        return os.path.realpath(uno.fileUrlToSystemPath(url))
+    except Exception:
+        return ""
+
+
+def find_open_document(desktop, path: Path):
+    target_path = os.path.realpath(str(path))
+    target_name = path.name
+    try:
+        enum = desktop.getComponents().createEnumeration()
+    except Exception:
+        return None
+    while enum.hasMoreElements():
+        component = enum.nextElement()
+        if not component_has_sheets(component):
+            continue
+        if url_to_path(component_url(component)) == target_path:
+            return component
+        if target_name and target_name in component_title(component):
+            return component
+    return None
+
+
+def libreoffice_command(path: Path) -> list[str]:
+    soffice = os.environ.get("SOFFICE") or shutil.which("soffice") or "soffice"
+    home = os.environ.get("HOME", "")
+    user_installation = f"-env:UserInstallation=file://{home}" if home else ""
+    command = [
+        soffice,
+        "--norestore",
+        "--nofirststartwizard",
+        "--nolockcheck",
+        "--accept=socket,host=localhost,port=2002;urp;StarOffice.ComponentContext",
+        "--calc",
+        str(path),
+    ]
+    if user_installation:
+        command.insert(4, user_installation)
+    return command
+
+
+def launch_visible_calc(path: Path) -> None:
+    subprocess.Popen(
+        libreoffice_command(path),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+
+def wait_for_document(path: Path, timeout_seconds: float):
+    started = False
+    last_error: Exception | None = None
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        dismiss_document_in_use_dialogs()
+        try:
+            ctx = connect_once()
+            desktop = desktop_from_context(ctx)
+            document = find_open_document(desktop, path)
+            if document is not None:
+                return document
+            if not started:
+                launch_visible_calc(path)
+                started = True
+        except Exception as exc:
+            last_error = exc
+            if not started:
+                launch_visible_calc(path)
+                started = True
+        time.sleep(0.5)
+    detail = f": {last_error!r}" if last_error else ""
+    raise RuntimeError(f"Timed out waiting for LibreOffice Calc to open {path}{detail}")
+
+
+def focus_document_window(document) -> None:
+    try:
+        document.CurrentController.Frame.ContainerWindow.setFocus()
+    except Exception:
+        pass
+
+
+def sheet_path_for_name(zip_file: zipfile.ZipFile, sheet_name: str) -> str:
+    workbook = ET.fromstring(zip_file.read("xl/workbook.xml"))
+    rel_id = None
+    sheets = workbook.find("m:sheets", NS)
+    if sheets is None:
+        raise RuntimeError("Workbook has no sheets collection")
+    for sheet in sheets:
+        if sheet.attrib.get("name") == sheet_name:
+            rel_id = sheet.attrib.get(f"{{{OOXML_REL_NS}}}id")
+            break
+    if not rel_id:
+        raise RuntimeError(f"Sheet not found on disk: {sheet_name}")
+    rels = ET.fromstring(zip_file.read("xl/_rels/workbook.xml.rels"))
+    target = None
+    for rel in rels:
+        if rel.attrib.get("Id") == rel_id:
+            target = rel.attrib.get("Target")
+            break
+    if not target:
+        raise RuntimeError(f"Sheet relationship not found on disk: {sheet_name}")
+    target = target.lstrip("/")
+    if target.startswith("xl/"):
+        return target
+    return f"xl/{target}"
+
+
+def shared_strings(zip_file: zipfile.ZipFile) -> list[str]:
+    if "xl/sharedStrings.xml" not in zip_file.namelist():
+        return []
+    root = ET.fromstring(zip_file.read("xl/sharedStrings.xml"))
+    values: list[str] = []
+    for item in root.findall("m:si", NS):
+        parts = [
+            text_node.text or ""
+            for text_node in item.iter(f"{{{OOXML_MAIN_NS}}}t")
+        ]
+        values.append("".join(parts))
+    return values
+
+
+def read_xlsx_cell(path: Path, sheet_name: str, cell_name: str) -> str | None:
+    with zipfile.ZipFile(path) as zip_file:
+        sheet_path = sheet_path_for_name(zip_file, sheet_name)
+        sheet = ET.fromstring(zip_file.read(sheet_path))
+        strings = shared_strings(zip_file)
+        for cell in sheet.iter(f"{{{OOXML_MAIN_NS}}}c"):
+            if cell.attrib.get("r") != cell_name:
+                continue
+            cell_type = cell.attrib.get("t")
+            if cell_type == "inlineStr":
+                return "".join(
+                    text_node.text or ""
+                    for text_node in cell.iter(f"{{{OOXML_MAIN_NS}}}t")
+                )
+            value_node = cell.find("m:v", NS)
+            raw_value = "" if value_node is None or value_node.text is None else value_node.text
+            if cell_type == "s" and raw_value != "":
+                return strings[int(raw_value)]
+            return raw_value
+    return None
+
+
+def wait_for_disk_value(path: Path, sheet: str, cell: str, expected: str) -> str | None:
+    latest = None
+    for _ in range(24):
+        latest = read_xlsx_cell(path, sheet, cell)
+        if latest == expected:
+            return latest
+        time.sleep(0.25)
+    return latest
+
+
+def is_disposed_error(exc: BaseException) -> bool:
+    return "DisposedException" in type(exc).__name__ or "DisposedException" in str(exc)
+
+
+def edit_visible_calc_cell(path: Path, sheet_name: str, cell_name: str, value: str) -> tuple[str, str, str | None]:
+    last_error: Exception | None = None
+    for _ in range(4):
+        document = wait_for_document(
+            path,
+            timeout_seconds=float(os.environ.get("A0_CALC_OPEN_TIMEOUT", "30")),
+        )
+        try:
+            focus_document_window(document)
+            sheets = document.getSheets()
+            if not sheets.hasByName(sheet_name):
+                raise SystemExit(f"Sheet not found: {sheet_name}")
+            sheet = sheets.getByName(sheet_name)
+            target_cell = sheet.getCellRangeByName(cell_name)
+            before = target_cell.getString()
+            target_cell.setString(value)
+            document.store()
+            after = target_cell.getString()
+            disk_value = wait_for_disk_value(path, sheet_name, cell_name, value)
+            return before, after, disk_value
+        except Exception as exc:
+            if not is_disposed_error(exc):
+                raise
+            last_error = exc
+            time.sleep(1)
+    raise RuntimeError(f"LibreOffice UNO bridge stayed disposed while editing {path}: {last_error!r}")
+
+
+def main() -> int:
+    args = parse_args()
+    path = Path(args.file).expanduser().resolve()
+    if not path.exists():
+        raise SystemExit(f"Workbook not found: {path}")
+
+    before, after, disk_value = edit_visible_calc_cell(path, args.sheet, args.cell, args.value)
+    if after != args.value or disk_value != args.value:
+        raise SystemExit(
+            f"Calc edit verification failed: before={before!r} after={after!r} disk={disk_value!r}"
+        )
+    print(f"updated {path} {args.sheet}!{args.cell}: {before!r} -> {after!r}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plugins/_desktop/skills/linux-desktop/scripts/desktopctl.sh

@@ -0,0 +1,459 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SESSION="${A0_DESKTOP_SESSION:-agent-zero-desktop}"
+BASE_DIR="${A0_BASE_DIR:-/a0}"
+PROFILE_DIR="${A0_DESKTOP_PROFILE:-$BASE_DIR/usr/plugins/_desktop/profiles/$SESSION}"
+MANIFEST="${A0_DESKTOP_MANIFEST:-$BASE_DIR/usr/plugins/_desktop/sessions/$SESSION.json}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DESKTOP_STATE_HELPER="$SCRIPT_DIR/../../../helpers/desktop_state.py"
+DESKTOP_STATE_PYTHON="${A0_DESKTOP_STATE_PYTHON:-$(command -v /usr/bin/python3 || command -v python3 || true)}"
+
+display_from_manifest() {
+  if [ ! -f "$MANIFEST" ] || ! command -v python3 >/dev/null 2>&1; then
+    return 0
+  fi
+  python3 - "$MANIFEST" <<'PY'
+import json
+import sys
+
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as handle:
+        value = json.load(handle).get("display", "")
+except Exception:
+    value = ""
+if value != "":
+    print(value)
+PY
+}
+
+DISPLAY_VALUE="${A0_DESKTOP_DISPLAY:-$(display_from_manifest || true)}"
+DISPLAY_VALUE="${DISPLAY_VALUE:-120}"
+case "$DISPLAY_VALUE" in
+  :*) export DISPLAY="$DISPLAY_VALUE" ;;
+  *) export DISPLAY=":$DISPLAY_VALUE" ;;
+esac
+
+export XAUTHORITY="${A0_DESKTOP_XAUTHORITY:-$PROFILE_DIR/.Xauthority}"
+export HOME="${A0_DESKTOP_HOME:-$PROFILE_DIR}"
+export A0_DESKTOP_SESSION="$SESSION"
+export A0_DESKTOP_MANIFEST="$MANIFEST"
+export A0_DESKTOP_PROFILE="$PROFILE_DIR"
+export A0_DESKTOP_DISPLAY="$DISPLAY"
+export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
+export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
+export XDG_CURRENT_DESKTOP="${XDG_CURRENT_DESKTOP:-XFCE}"
+
+command_name="${1:-help}"
+shift || true
+
+usage() {
+  cat <<'EOF'
+Usage: desktopctl.sh <command> [args]
+
+Commands:
+  env                         Print the X11 environment used for the Desktop.
+  check                       Verify that xdotool can reach the Desktop display.
+  state --json [--screenshot] [--context-id ID]
+                              Return structured Desktop state as JSON.
+  observe --json [--screenshot] [--context-id ID]
+                              Return structured state, optionally with a fresh screenshot.
+  screenshot [PATH] [--context-id ID]
+                              Capture the Desktop to PATH, or to the chat screenshot directory when context-id is set.
+  active-window               Print the active window name.
+  geometry PATTERN            Print the first matching visible window geometry.
+  wait-window PATTERN         Wait for a visible matching window and print its id.
+  location                    Print the current X pointer location.
+  windows [PATTERN]           List visible window names matching PATTERN.
+  focus PATTERN               Focus the first visible window matching PATTERN.
+  scroll DIRECTION [UNITS]    Scroll up, down, left, or right; UNITS defaults to 5 clicks.
+  drag X1 Y1 X2 Y2            Drag from X1,Y1 to X2,Y2 in Desktop coordinates.
+  right-click X Y             Move and right-click at X,Y in Desktop coordinates.
+  paste-text TEXT             Put TEXT on the Desktop clipboard and paste it with an app-native shortcut.
+  sequence FILE|-             Run a newline-delimited command sequence in this process.
+  batch FILE|-                Alias for sequence.
+  key KEY...                  Send one or more xdotool key names.
+  type TEXT                   Type text into the focused window.
+  click X Y                   Move and click at X,Y in Desktop coordinates.
+  dblclick X Y                Move and double-click at X,Y in Desktop coordinates.
+  launch APP                  Launch writer, calc, impress, terminal, settings, or workdir.
+  open-path [PATH]            Open PATH in Thunar, defaulting to /a0/usr/workdir.
+  calc-set-cell FILE SHEET CELL VALUE
+                              Open FILE in visible Calc, set SHEET!CELL, save, and verify.
+  save                        Send Ctrl+S to the focused app.
+EOF
+}
+
+require_xdotool() {
+  if ! command -v xdotool >/dev/null 2>&1; then
+    echo "xdotool is required for Desktop control." >&2
+    exit 2
+  fi
+}
+
+ensure_display() {
+  require_xdotool
+  if ! xdotool getmouselocation >/dev/null 2>&1; then
+    echo "Desktop X display is not reachable. Open the Desktop surface first." >&2
+    exit 2
+  fi
+}
+
+desktop_state() {
+  if [ ! -f "$DESKTOP_STATE_HELPER" ]; then
+    echo "Desktop state helper not found: $DESKTOP_STATE_HELPER" >&2
+    exit 2
+  fi
+  "$DESKTOP_STATE_PYTHON" "$DESKTOP_STATE_HELPER" "$@"
+}
+
+run_detached() {
+  ( "$@" >/tmp/a0-desktopctl.log 2>&1 & )
+}
+
+close_blocking_dialogs() {
+  require_xdotool
+  for title in "Document in Use"; do
+    window_ids="$(xdotool search --onlyvisible --name "$title" 2>/dev/null || true)"
+    printf '%s\n' "$window_ids" | while read -r window_id; do
+      [ -n "$window_id" ] && xdotool windowclose "$window_id" >/dev/null 2>&1 || true
+    done
+  done
+}
+
+first_window() {
+  pattern="$1"
+  xdotool search --onlyvisible --name "$pattern" 2>/dev/null | head -n 1 || true
+}
+
+active_window_id() {
+  xdotool getactivewindow 2>/dev/null || true
+}
+
+active_window_class() {
+  window_id="$(active_window_id)"
+  if [ -z "$window_id" ]; then
+    return 0
+  fi
+  if command -v xprop >/dev/null 2>&1; then
+    xprop -id "$window_id" WM_CLASS 2>/dev/null | awk -F'"' '/WM_CLASS/ { print $(NF - 1); exit }'
+  fi
+}
+
+active_window_class_lower() {
+  active_window_class | tr '[:upper:]' '[:lower:]'
+}
+
+active_window_is_terminal() {
+  window_class="$(active_window_class_lower)"
+  case "$window_class" in
+    *terminal*|xterm|uxterm|rxvt|urxvt|kitty|alacritty|wezterm|konsole)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+paste_key_for_active_window() {
+  printf '%s\n' "${A0_DESKTOP_PASTE_KEY:-ctrl+v}"
+}
+
+window_geometry() {
+  window_id="$1"
+  if command -v xwininfo >/dev/null 2>&1; then
+    xwininfo -id "$window_id" 2>/dev/null | awk '
+      /Absolute upper-left X:/ { x=$4 }
+      /Absolute upper-left Y:/ { y=$4 }
+      /Width:/ { w=$2 }
+      /Height:/ { h=$2 }
+      END { if (w != "") printf "X=%s\nY=%s\nWIDTH=%s\nHEIGHT=%s\n", x, y, w, h }
+    '
+  else
+    xdotool getwindowgeometry --shell "$window_id"
+  fi
+}
+
+wait_window() {
+  pattern="$1"
+  timeout="${2:-15}"
+  end=$((SECONDS + timeout))
+  while [ "$SECONDS" -le "$end" ]; do
+    window_id="$(first_window "$pattern")"
+    if [ -n "$window_id" ]; then
+      printf '%s\n' "$window_id"
+      return 0
+    fi
+    sleep 0.25
+  done
+  echo "Timed out waiting for visible window: $pattern" >&2
+  return 1
+}
+
+scroll_desktop() {
+  direction="$1"
+  units="${2:-5}"
+  case "$direction" in
+    up) button=4 ;;
+    down) button=5 ;;
+    left) button=6 ;;
+    right) button=7 ;;
+    *)
+      echo "scroll direction must be up, down, left, or right." >&2
+      exit 2
+      ;;
+  esac
+  xdotool click --repeat "$units" "$button"
+}
+
+paste_text() {
+  text="$*"
+  if active_window_is_terminal; then
+    xdotool type --delay "${A0_DESKTOP_PASTE_TYPE_DELAY_MS:-${A0_DESKTOP_TYPE_DELAY_MS:-4}}" -- "$text"
+    return
+  fi
+  if command -v xclip >/dev/null 2>&1; then
+    printf '%s' "$text" | xclip -selection clipboard
+    xdotool key --clearmodifiers "$(paste_key_for_active_window)"
+    return
+  fi
+  xdotool type --delay "${A0_DESKTOP_TYPE_DELAY_MS:-1}" -- "$text"
+}
+
+run_sequence_line() {
+  line="$1"
+  [ -z "$line" ] && return 0
+  case "$line" in
+    \#*) return 0 ;;
+  esac
+  # shellcheck disable=SC2086
+  dispatch_command $line
+}
+
+run_sequence() {
+  source_file="$1"
+  if [ "$source_file" = "-" ]; then
+    while IFS= read -r line; do
+      run_sequence_line "$line"
+    done
+    return
+  fi
+  if [ ! -f "$source_file" ]; then
+    echo "sequence requires an existing FILE or - for stdin." >&2
+    exit 2
+  fi
+  while IFS= read -r line || [ -n "$line" ]; do
+    run_sequence_line "$line"
+  done < "$source_file"
+}
+
+launch_app() {
+  app="${1:-}"
+  soffice="${SOFFICE:-$(command -v soffice || true)}"
+  soffice="${soffice:-soffice}"
+  case "$app" in
+    writer)
+      run_detached "$soffice" --norestore --nofirststartwizard --nolockcheck "-env:UserInstallation=file://$HOME" --writer
+      ;;
+    calc|spreadsheet)
+      run_detached "$soffice" --norestore --nofirststartwizard --nolockcheck "-env:UserInstallation=file://$HOME" --calc
+      ;;
+    impress|presentation)
+      run_detached "$soffice" --norestore --nofirststartwizard --nolockcheck "-env:UserInstallation=file://$HOME" --impress
+      ;;
+    terminal)
+      run_detached xfce4-terminal --working-directory=/a0/usr/workdir
+      ;;
+    settings)
+      run_detached xfce4-settings-manager
+      ;;
+    workdir|files|file-manager)
+      run_detached thunar /a0/usr/workdir
+      ;;
+    *)
+      echo "Unknown app: ${app:-<empty>}" >&2
+      echo "Expected: writer, calc, impress, terminal, settings, or workdir." >&2
+      exit 2
+      ;;
+  esac
+}
+
+dispatch_command() {
+  local command_name="${1:-help}"
+  shift || true
+
+  case "$command_name" in
+  help|-h|--help)
+    usage
+    ;;
+  env)
+    printf 'export DISPLAY=%q\n' "$DISPLAY"
+    printf 'export XAUTHORITY=%q\n' "$XAUTHORITY"
+    printf 'export HOME=%q\n' "$HOME"
+    ;;
+  check)
+    ensure_display
+    xdotool getmouselocation --shell
+    ;;
+  state)
+    if [ "${1:-}" != "--json" ]; then
+      echo "state currently requires --json." >&2
+      exit 2
+    fi
+    shift
+    desktop_state state --json "$@"
+    ;;
+  observe)
+    if [ "${1:-}" != "--json" ]; then
+      echo "observe currently requires --json." >&2
+      exit 2
+    fi
+    shift
+    desktop_state observe --json "$@"
+    ;;
+  screenshot)
+    if [ "${1:-}" = "--json" ]; then
+      shift
+      desktop_state screenshot --json "$@"
+    elif [ "$#" -gt 0 ]; then
+      desktop_state screenshot "$@"
+    else
+      desktop_state screenshot
+    fi
+    ;;
+  active-window)
+    ensure_display
+    window_id="$(active_window_id)"
+    if [ -z "$window_id" ]; then
+      echo "No active window." >&2
+      exit 1
+    fi
+    xdotool getwindowname "$window_id"
+    ;;
+  geometry)
+    ensure_display
+    pattern="${1:?geometry requires a window name pattern}"
+    window_id="$(first_window "$pattern")"
+    if [ -z "$window_id" ]; then
+      echo "No visible window matched: $pattern" >&2
+      exit 1
+    fi
+    window_geometry "$window_id"
+    ;;
+  wait-window)
+    ensure_display
+    pattern="${1:?wait-window requires a window name pattern}"
+    wait_window "$pattern" "${2:-15}"
+    ;;
+  location)
+    ensure_display
+    xdotool getmouselocation --shell
+    ;;
+  windows)
+    ensure_display
+    pattern="${1:-.}"
+    xdotool search --onlyvisible --name "$pattern" getwindowname %@ 2>/dev/null || true
+    ;;
+  focus)
+    ensure_display
+    pattern="${1:?focus requires a window name pattern}"
+    window_id="$(first_window "$pattern")"
+    if [ -z "$window_id" ]; then
+      echo "No visible window matched: $pattern" >&2
+      exit 1
+    fi
+    xdotool windowactivate --sync "$window_id"
+    ;;
+  scroll)
+    ensure_display
+    scroll_desktop "${1:?scroll requires DIRECTION}" "${2:-5}"
+    ;;
+  drag)
+    ensure_display
+    x1="${1:?drag requires X1}"
+    y1="${2:?drag requires Y1}"
+    x2="${3:?drag requires X2}"
+    y2="${4:?drag requires Y2}"
+    xdotool mousemove --sync "$x1" "$y1" mousedown 1 mousemove --sync "$x2" "$y2" mouseup 1
+    ;;
+  right-click)
+    ensure_display
+    x="${1:?right-click requires X}"
+    y="${2:?right-click requires Y}"
+    xdotool mousemove --sync "$x" "$y" click 3
+    ;;
+  paste-text)
+    ensure_display
+    if [ "$#" -eq 0 ]; then
+      echo "paste-text requires TEXT." >&2
+      exit 2
+    fi
+    paste_text "$@"
+    ;;
+  sequence|batch)
+    source_file="${1:?sequence requires FILE or -}"
+    run_sequence "$source_file"
+    ;;
+  key)
+    ensure_display
+    if [ "$#" -eq 0 ]; then
+      echo "key requires at least one xdotool key name." >&2
+      exit 2
+    fi
+    xdotool key --clearmodifiers "$@"
+    ;;
+  type)
+    ensure_display
+    text="$*"
+    xdotool type --delay "${A0_DESKTOP_TYPE_DELAY_MS:-1}" -- "$text"
+    ;;
+  click)
+    ensure_display
+    x="${1:?click requires X}"
+    y="${2:?click requires Y}"
+    xdotool mousemove --sync "$x" "$y" click 1
+    ;;
+  dblclick)
+    ensure_display
+    x="${1:?dblclick requires X}"
+    y="${2:?dblclick requires Y}"
+    xdotool mousemove --sync "$x" "$y" click --repeat 2 --delay "${A0_DESKTOP_DBLCLICK_DELAY_MS:-150}" 1
+    ;;
+  launch)
+    ensure_display
+    launch_app "${1:-}"
+    ;;
+  open-path)
+    ensure_display
+    path="${1:-/a0/usr/workdir}"
+    run_detached thunar "$path"
+    ;;
+  calc-set-cell)
+    ensure_display
+    file="${1:?calc-set-cell requires FILE}"
+    sheet="${2:?calc-set-cell requires SHEET}"
+    cell="${3:?calc-set-cell requires CELL}"
+    shift 3
+    if [ "$#" -eq 0 ]; then
+      echo "calc-set-cell requires VALUE." >&2
+      exit 2
+    fi
+    close_blocking_dialogs
+    export PYTHONPATH="${PYTHONPATH:-/usr/lib/python3/dist-packages:/usr/lib/libreoffice/program:}"
+    python3 "$SCRIPT_DIR/calc_set_cell.py" "$file" "$sheet" "$cell" "$@"
+    ;;
+  save)
+    ensure_display
+    xdotool key --clearmodifiers ctrl+s
+    ;;
+  *)
+    echo "Unknown command: $command_name" >&2
+    usage >&2
+    exit 2
+    ;;
+  esac
+}
+
+dispatch_command "$command_name" "$@"

plugins/_desktop/webui/desktop-panel.html

@@ -0,0 +1,734 @@
+<html>
+<head>
+  <script type="module">
+    import { store } from "/plugins/_desktop/webui/desktop-store.js";
+  </script>
+</head>
+<body>
+  <div x-data>
+    <template x-if="$store.desktop">
+      <div class="office-panel" x-create="$store.desktop.onMount($el, xAttrs($el) || {})" x-destroy="$store.desktop.cleanup()">
+      <div class="office-shell">
+        <div class="office-document-header" x-show="$store.desktop.hasActiveFile()" style="display: none;">
+          <div class="office-document-title" :title="$store.desktop.tabLabel($store.desktop.session)">
+            <x-icon class="office-document-icon" aria-hidden="true" :name="$store.desktop.tabIcon($store.desktop.session)"></x-icon>
+            <span class="office-document-name" x-text="$store.desktop.tabTitle($store.desktop.session)"></span>
+            <span class="office-document-dirty" x-show="$store.desktop.dirty" aria-hidden="true">*</span>
+          </div>
+
+          <button
+            type="button"
+            class="office-icon-button office-document-save-button"
+            title="Save"
+            aria-label="Save"
+            :class="{ 'is-primary': $store.desktop.dirty }"
+            :disabled="$store.desktop.saving"
+            @click="$store.desktop.save()"
+          >
+            <x-icon :class="{ spinning: $store.desktop.saving }" :name="$store.desktop.saving ? 'progress_activity' : 'save'"></x-icon>
+          </button>
+
+          <div class="office-file-actions" x-data="{ open: false }" @click.outside="open = false" @keydown.escape.window="open = false">
+            <button
+              type="button"
+              class="office-icon-button office-file-menu-button"
+              title="File actions"
+              aria-label="File actions"
+              aria-haspopup="menu"
+              :aria-expanded="open.toString()"
+              :disabled="$store.desktop.saving"
+              @click.stop="open = !open"
+            >
+              <x-icon name="more_vert"></x-icon>
+            </button>
+            <div class="office-new-menu office-file-menu" role="menu" x-show="open" @click.stop>
+              <button type="button" class="office-new-menu-item" role="menuitem" :disabled="$store.desktop.saving" @click="open = false; $store.desktop.renameActiveFile()">
+                <x-icon aria-hidden="true" name="edit"></x-icon>
+                <span>Rename</span>
+              </button>
+              <button type="button" class="office-new-menu-item" role="menuitem" :disabled="$store.desktop.loading" @click="open = false; $store.desktop.closeActiveFile()">
+                <x-icon aria-hidden="true" name="close"></x-icon>
+                <span>Close File</span>
+              </button>
+            </div>
+          </div>
+        </div>
+
+        <div class="office-state-line" x-show="$store.desktop.message || $store.desktop.error || $store.desktop.loading" style="display: none;">
+          <x-icon :class="{ spinning: $store.desktop.loading }" :name="$store.desktop.loading ? 'progress_activity' : ($store.desktop.error ? 'error' : 'check_circle')"></x-icon>
+          <span x-text="$store.desktop.error || $store.desktop.message || 'Working'"></span>
+        </div>
+
+        <div class="office-body">
+          <div class="office-editor-wrap" x-show="$store.desktop.session" style="display: none;">
+            <div class="office-editor-scroll" :class="{ 'is-desktop': $store.desktop.hasOfficialOffice() }" @click.self="$store.desktop.focusEditor()">
+              <template x-if="$store.desktop.hasOfficialOffice()">
+                <div
+                  class="office-desktop-wrap"
+                  data-office-desktop-host
+                  x-init="$nextTick(() => $store.desktop.mountDesktopFrameHost($el))"
+                >
+                </div>
+              </template>
+            </div>
+          </div>
+
+          <div class="office-desktop-empty" x-show="$store.desktop.shouldShowDesktopEmptyState()" style="display: none;">
+            <x-icon aria-hidden="true" name="power_settings_new"></x-icon>
+            <span class="office-desktop-empty-title">Desktop is shut down</span>
+            <button type="button" class="office-icon-button office-command-button" @click="$store.desktop.restartDesktopSession()">
+              <x-icon aria-hidden="true" name="restart_alt"></x-icon>
+              <span class="office-button-label">Restart Desktop</span>
+            </button>
+          </div>
+        </div>
+      </div>
+      </div>
+    </template>
+  </div>
+
+  <style>
+    .office-panel,
+    .office-shell {
+      display: flex;
+      flex: 1 1 auto;
+      flex-direction: column;
+      width: 100%;
+      height: 100%;
+      min-width: 0;
+      min-height: 0;
+      background: var(--color-background);
+      color: var(--color-text);
+    }
+
+    .office-panel {
+      container-type: inline-size;
+    }
+
+    .modal-inner.office-modal {
+      box-sizing: border-box;
+      width: min(1120px, calc(100vw - 32px));
+      height: min(820px, calc(100vh - 32px));
+      min-width: min(720px, calc(100vw - 16px));
+      min-height: min(520px, calc(100vh - 16px));
+      max-width: none;
+      max-height: none;
+      resize: none;
+      overflow: hidden;
+      will-change: width, height, left, top;
+    }
+
+    .modal-inner.office-modal.is-resizing,
+    .modal-inner.office-modal.is-dragging {
+      user-select: none;
+    }
+
+    .modal-inner.office-modal.is-focus-mode {
+      border-radius: 6px;
+    }
+
+    .modal-inner.office-modal .modal-scroll {
+      display: flex;
+      flex: 1 1 auto;
+      min-height: 0;
+      max-height: none;
+      overflow: hidden;
+      padding: 0;
+    }
+
+    .modal-inner.office-modal .modal-header {
+      grid-template-columns: minmax(0, 1fr) auto auto;
+    }
+
+    .office-modal-input-shield {
+      position: absolute;
+      inset: 42px 0 0 0;
+      z-index: 4;
+      display: none;
+      background: transparent;
+    }
+
+    .office-modal-resizer {
+      position: absolute;
+      z-index: 5;
+      display: block;
+      touch-action: none;
+    }
+
+    .office-modal-resizer.is-right {
+      top: 42px;
+      right: -4px;
+      bottom: 12px;
+      width: 10px;
+      cursor: ew-resize;
+    }
+
+    .office-modal-resizer.is-bottom {
+      right: 12px;
+      bottom: -4px;
+      left: 0;
+      height: 10px;
+      cursor: ns-resize;
+    }
+
+    .office-modal-resizer.is-corner {
+      right: 0;
+      bottom: 0;
+      width: 22px;
+      height: 22px;
+      cursor: nwse-resize;
+    }
+
+    .office-modal-resizer.is-corner::after {
+      content: "";
+      position: absolute;
+      right: 6px;
+      bottom: 6px;
+      width: 9px;
+      height: 9px;
+      border-right: 2px solid color-mix(in srgb, var(--color-text) 42%, transparent);
+      border-bottom: 2px solid color-mix(in srgb, var(--color-text) 42%, transparent);
+      border-radius: 1px;
+    }
+
+    .modal-inner.office-modal.is-focus-mode .office-modal-resizer {
+      display: none;
+    }
+
+    .modal-inner.office-modal .modal-bd.office-modal-body,
+    .modal-inner.office-modal .modal-bd.office-modal-body > x-component,
+    .modal-inner.office-modal .modal-bd.office-modal-body > x-component > div[x-data],
+    .modal-inner.office-modal .modal-bd.office-modal-body > x-component > .office-panel,
+    .modal-inner.office-modal .modal-bd.office-modal-body > x-component > div[x-data] > .office-panel {
+      display: flex;
+      flex: 1 1 auto;
+      min-height: 0;
+      min-width: 0;
+      width: 100%;
+      height: 100%;
+      padding: 0;
+    }
+
+    .office-toolbar {
+      display: flex;
+      flex-direction: row;
+      align-items: stretch;
+      flex-wrap: nowrap;
+      min-height: 0;
+      padding: 6px 10px;
+      overflow: hidden;
+      border-bottom: 1px solid color-mix(in srgb, var(--color-border), transparent 20%);
+      background: color-mix(in srgb, var(--color-background), var(--color-panel) 48%);
+    }
+
+    .office-toolbar-row {
+      display: flex;
+      align-items: center;
+      flex: 0 0 auto;
+      flex-wrap: nowrap;
+      gap: 6px;
+      width: 100%;
+      min-width: 0;
+      min-height: 32px;
+      overflow-x: auto;
+      overflow-y: hidden;
+      scrollbar-width: thin;
+    }
+
+    .office-tool-group {
+      display: flex;
+      align-items: center;
+      flex-wrap: nowrap;
+      flex: 0 0 auto;
+      gap: 4px;
+      min-width: 0;
+    }
+
+    .office-editor-tools {
+      gap: 3px;
+    }
+
+    .office-tool-actions {
+      justify-content: flex-end;
+    }
+
+    .office-toolbar-spacer {
+      flex: 1 1 16px;
+      min-width: 8px;
+    }
+
+    .office-toolbar-divider {
+      flex: 0 0 auto;
+      width: 1px;
+      height: 22px;
+      margin-inline: 2px;
+      background: color-mix(in srgb, var(--color-border), transparent 18%);
+    }
+
+    .office-document-header {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      min-height: 38px;
+      padding: 5px 10px 5px 12px;
+      border-bottom: 1px solid color-mix(in srgb, var(--color-border), transparent 22%);
+      background: color-mix(in srgb, var(--color-panel), var(--color-background) 30%);
+    }
+
+    .office-document-title {
+      display: flex;
+      align-items: center;
+      gap: 7px;
+      min-width: 0;
+      flex: 1 1 auto;
+      color: var(--color-text);
+    }
+
+    .office-document-icon {
+      flex: 0 0 auto;
+      font-size: 19px;
+      line-height: 1;
+    }
+
+    .office-document-name {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      font-size: 13px;
+      font-weight: 750;
+      letter-spacing: 0;
+      line-height: 1.2;
+    }
+
+    .office-document-dirty {
+      flex: 0 0 auto;
+      color: #2ca58d;
+      font-size: 14px;
+      font-weight: 800;
+      line-height: 1;
+    }
+
+    .office-file-actions {
+      position: relative;
+      display: inline-flex;
+      align-items: center;
+      flex: 0 0 auto;
+    }
+
+    .office-document-save-button,
+    .office-file-menu-button {
+      width: 30px;
+      height: 30px;
+      min-width: 30px;
+    }
+
+    .office-header-actions {
+      position: relative;
+      display: inline-flex;
+      align-items: center;
+      flex: 0 0 auto;
+    }
+
+    .office-header-new-button {
+      appearance: none;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      gap: 4px;
+      height: 34px;
+      min-height: 34px;
+      padding: 0 9px 0 8px;
+      border: 1px solid transparent;
+      border-radius: 7px;
+      background: transparent;
+      color: var(--color-text);
+      cursor: pointer;
+      font: inherit;
+      font-size: 12px;
+      font-weight: 750;
+      letter-spacing: 0;
+      line-height: 1;
+      opacity: 0.82;
+      white-space: nowrap;
+      transition: background-color 0.16s ease, border-color 0.16s ease, opacity 0.16s ease;
+    }
+
+    .office-header-new-button:hover,
+    .office-header-actions.is-open .office-header-new-button {
+      opacity: 1;
+      border-color: color-mix(in srgb, var(--color-primary) 28%, var(--color-border));
+      background: color-mix(in srgb, var(--color-background-hover) 72%, transparent);
+    }
+
+    .office-header-new-button .material-symbols-outlined {
+      font-size: 18px;
+      line-height: 1;
+    }
+
+    .office-header-new-button .office-new-chevron {
+      margin-left: -2px;
+      font-size: 16px;
+      opacity: 0.8;
+    }
+
+    .office-new-menu {
+      position: absolute;
+      top: calc(100% + 6px);
+      right: 0;
+      z-index: 100;
+      min-width: 184px;
+      padding: 5px;
+      border: 1px solid color-mix(in srgb, var(--color-border), transparent 10%);
+      border-radius: 8px;
+      background: color-mix(in srgb, var(--color-panel), var(--color-background) 10%);
+      box-shadow: 0 14px 34px rgba(0, 0, 0, 0.34);
+    }
+
+    .right-canvas-desktop-actions .office-new-menu {
+      z-index: 4000;
+    }
+
+    .office-new-menu[hidden] {
+      display: none;
+    }
+
+    .office-new-menu-item {
+      appearance: none;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      width: 100%;
+      height: 32px;
+      padding: 0 8px;
+      border: 1px solid transparent;
+      border-radius: 6px;
+      background: transparent;
+      color: var(--color-text);
+      cursor: pointer;
+      font: inherit;
+      font-size: 12px;
+      font-weight: 650;
+      letter-spacing: 0;
+      line-height: 1;
+      text-align: left;
+      white-space: nowrap;
+    }
+
+    .office-new-menu-item:hover {
+      border-color: color-mix(in srgb, var(--color-primary) 22%, transparent);
+      background: color-mix(in srgb, var(--color-background-hover) 76%, transparent);
+    }
+
+    .office-new-menu-item:disabled {
+      cursor: default;
+      opacity: 0.46;
+    }
+
+    .office-new-menu-item .material-symbols-outlined {
+      flex: 0 0 auto;
+      width: 18px;
+      font-size: 18px;
+      line-height: 1;
+      text-align: center;
+    }
+
+    .office-icon-button,
+    .office-tab,
+    .office-tab-close {
+      border: 1px solid color-mix(in srgb, var(--color-border), transparent 12%);
+      border-radius: 8px;
+      background: color-mix(in srgb, var(--color-panel), var(--color-background) 16%);
+      color: inherit;
+      transition: border-color 120ms ease, background 120ms ease, transform 120ms ease;
+    }
+
+    .office-icon-button {
+      display: inline-grid;
+      place-items: center;
+      width: 32px;
+      height: 32px;
+      min-width: 32px;
+      padding: 0;
+    }
+
+    .office-command-button {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      gap: 5px;
+      width: auto;
+      max-width: 126px;
+      padding: 0 8px;
+      white-space: nowrap;
+    }
+
+    .office-command-button .office-button-label {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      font-size: 11px;
+      font-weight: 700;
+      line-height: 1;
+    }
+
+    .office-icon-button.is-primary {
+      border-color: color-mix(in srgb, #2c7be5, var(--color-border) 20%);
+      background: color-mix(in srgb, #2c7be5, var(--color-panel) 82%);
+    }
+
+    .office-icon-button.is-active {
+      border-color: color-mix(in srgb, #2ca58d, var(--color-border) 24%);
+      background: color-mix(in srgb, #2ca58d, var(--color-panel) 84%);
+    }
+
+    .office-icon-button:hover:not(:disabled),
+    .office-tab:hover,
+    .office-tab-close:hover {
+      border-color: color-mix(in srgb, #2c7be5, var(--color-border) 45%);
+      background: color-mix(in srgb, var(--color-panel), #2c7be5 8%);
+    }
+
+    .office-icon-button:disabled {
+      cursor: default;
+      opacity: 0.42;
+    }
+
+    .office-icon-button .material-symbols-outlined,
+    .office-tab-icon {
+      font-size: 19px;
+      line-height: 1;
+    }
+
+    .office-tabs {
+      display: flex;
+      gap: 6px;
+      min-height: 42px;
+      padding: 7px 10px;
+      overflow-x: auto;
+      border-bottom: 1px solid color-mix(in srgb, var(--color-border), transparent 22%);
+      background: color-mix(in srgb, var(--color-panel), var(--color-background) 28%);
+    }
+
+    .office-tab-shell {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 28px;
+      align-items: center;
+      min-width: 150px;
+      max-width: 240px;
+    }
+
+    .office-tab-shell.is-system {
+      grid-template-columns: minmax(0, 1fr);
+      min-width: 172px;
+    }
+
+    .office-tab,
+    .office-tab-close {
+      height: 28px;
+      min-height: 28px;
+      border-radius: 7px;
+    }
+
+    .office-tab {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      min-width: 0;
+      border-top-right-radius: 0;
+      border-bottom-right-radius: 0;
+      padding: 0 8px;
+      text-align: left;
+    }
+
+    .office-tab-shell.is-system .office-tab {
+      border-radius: 7px;
+    }
+
+    .office-tab-close {
+      display: grid;
+      place-items: center;
+      border-left: 0;
+      border-top-left-radius: 0;
+      border-bottom-left-radius: 0;
+      padding: 0;
+    }
+
+    .office-tab-close .material-symbols-outlined {
+      font-size: 17px;
+    }
+
+    .office-tab-shell.is-active .office-tab,
+    .office-tab-shell.is-active .office-tab-close {
+      border-color: color-mix(in srgb, #2c7be5, var(--color-border) 36%);
+      background: color-mix(in srgb, #2c7be5, var(--color-panel) 88%);
+    }
+
+    .office-tab-shell.is-dirty .office-tab-title::after {
+      content: " *";
+      color: #2ca58d;
+    }
+
+    .office-tab-title {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      font-size: 12px;
+      line-height: 1;
+    }
+
+    .office-state-line {
+      display: flex;
+      align-items: center;
+      flex: 0 0 auto;
+      gap: 8px;
+      width: 100%;
+      min-width: 0;
+      min-height: 34px;
+      box-sizing: border-box;
+      padding: 6px 12px;
+      border-bottom: 1px solid color-mix(in srgb, var(--color-border), transparent 28%);
+      color: var(--color-text-secondary);
+      font-size: 12px;
+    }
+
+    .office-state-line > .material-symbols-outlined {
+      flex: 0 0 auto;
+    }
+
+    .office-state-line > span:not(.material-symbols-outlined) {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    .office-body {
+      position: relative;
+      display: flex;
+      flex: 1 1 auto;
+      min-height: 0;
+      overflow: hidden;
+      background: var(--color-background);
+    }
+
+    .office-body.is-source {
+      background: transparent;
+    }
+
+    .office-editor-wrap {
+      display: flex;
+      flex: 1 1 auto;
+      flex-direction: column;
+      min-width: 0;
+      min-height: 0;
+    }
+
+    .office-editor-scroll {
+      flex: 1 1 auto;
+      min-height: 0;
+      overflow: auto;
+      padding: 30px 24px;
+    }
+
+    .office-editor-scroll.is-source {
+      display: flex;
+      overflow: hidden;
+      padding: var(--spacing-md);
+      background: transparent;
+    }
+
+    .office-editor-scroll.is-desktop {
+      display: flex;
+      overflow: hidden;
+      padding: 0;
+      background: #1f2329;
+    }
+
+    .office-desktop-wrap {
+      display: flex;
+      flex: 1 1 auto;
+      width: 100%;
+      height: 100%;
+      min-width: 0;
+      min-height: 0;
+      aspect-ratio: auto;
+      background: #1f2329;
+    }
+
+    .office-desktop-empty {
+      display: grid;
+      flex: 1 1 auto;
+      place-items: center;
+      align-content: center;
+      gap: 12px;
+      min-width: 0;
+      min-height: 0;
+      padding: 24px;
+      color: var(--color-text-secondary);
+      text-align: center;
+    }
+
+    .office-desktop-empty > .material-symbols-outlined {
+      font-size: 32px;
+      color: color-mix(in srgb, var(--color-text) 68%, transparent);
+    }
+
+    .office-desktop-empty-title {
+      font-size: 13px;
+      font-weight: 700;
+    }
+
+    .office-desktop-frame {
+      flex: 1 1 auto;
+      width: 100%;
+      height: 100%;
+      min-height: 0;
+      aspect-ratio: auto;
+      border: 0;
+      background: #20242a;
+    }
+
+    .office-panel .spinning {
+      animation: office-spin 0.8s linear infinite;
+    }
+
+    @keyframes office-spin {
+      to { transform: rotate(360deg); }
+    }
+
+    @container (max-width: 680px) {
+      .office-toolbar {
+        padding-inline: 8px;
+      }
+
+      .office-toolbar-row {
+        gap: 5px;
+      }
+
+      .office-command-button {
+        width: 32px;
+        max-width: 32px;
+        padding-inline: 0;
+      }
+
+      .office-command-button .office-button-label {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip: rect(0 0 0 0);
+        white-space: nowrap;
+      }
+
+    }
+
+    /* While the canvas is being resized, the left-edge drag sweeps the cursor across this
+       iframe, which captures the pointermove and freezes shrinking (widening drags away, so
+       it works). Disable hit-testing on the frame during the drag — right-canvas-store.js
+       toggles `right-canvas-resizing` on <body> for the duration of the drag. */
+    body.right-canvas-resizing .office-desktop-frame { pointer-events: none; }
+  </style>
+</body>
+</html>

plugins/_desktop/webui/main.html

@@ -0,0 +1,21 @@
+<html
+  class="surface-modal office-modal modal-no-backdrop"
+  data-surface-id="desktop"
+  data-surface-modal-path="/plugins/_desktop/webui/main.html"
+  data-surface-dock-title="Open Desktop in canvas"
+  data-surface-dock-icon="dock_to_right"
+  data-canvas-surface="desktop"
+  data-canvas-modal-path="/plugins/_desktop/webui/main.html"
+  data-canvas-dock-title="Open Desktop in canvas"
+  data-canvas-dock-icon="dock_to_right"
+>
+<head>
+  <title>Desktop</title>
+  <script type="module">
+    import { store } from "/plugins/_desktop/webui/desktop-store.js";
+  </script>
+</head>
+<body class="office-modal-body">
+  <x-component path="/plugins/_desktop/webui/desktop-panel.html" mode="modal"></x-component>
+</body>
+</html>

plugins/_discovery/AGENTS.md

@@ -0,0 +1,31 @@
+# Plugin Discovery DOX
+
+## Purpose
+
+- Own contextual plugin discovery cards and welcome-screen promotions.
+
+## Ownership
+
+- `plugin.yaml` owns metadata and always-enabled status.
+- `extensions/` owns backend or WebUI discovery contributions.
+- `webui/discovery-store.js` owns discovery UI state and actions.
+
+## Local Contracts
+
+- Discovery cards must be accurate, dismissible where appropriate, and avoid advertising already-complete setup.
+- CTA actions must match supported welcome-screen action contracts.
+- Keep card IDs unique and plugin-prefixed.
+- The Welcome screen `welcome-actions-end` surface renders feature channel cards plus the compact OAuth account-provider card; other hero discovery cards stay out of the lower welcome grid.
+- Do not hide discovery cards solely because model setup is incomplete; model setup gating belongs to the chat thread.
+
+## Work Guidance
+
+- Prefer backend status checks before surfacing setup or integration prompts.
+
+## Verification
+
+- Smoke-test welcome-screen discovery cards, ordering, dismissal, and CTA behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.

plugins/_discovery/extensions/python/banners/10_discovery_cards.py

@@ -0,0 +1,154 @@
+from helpers.extension import Extension
+from helpers import plugins
+
+
+class DiscoveryCardsExtension(Extension):
+    """Injects discovery cards into the banners list."""
+
+    def _oauth_summary(self) -> dict:
+        try:
+            from plugins._oauth.helpers.providers import provider_registry
+            from plugins._oauth.helpers.route_bootstrap import is_installed
+            from plugins._oauth.helpers.summary import build_oauth_status_summary
+
+            return build_oauth_status_summary(
+                provider_registry=provider_registry,
+                routes_installed=is_installed,
+            )
+        except Exception:
+            return {}
+
+    def _oauth_usage_windows(self, summary: dict) -> list[dict]:
+        windows: list[dict] = []
+        accounts = summary.get("oauth_accounts") if isinstance(summary, dict) else {}
+        connected = accounts.get("connected", []) if isinstance(accounts, dict) else []
+        for account in connected:
+            if not isinstance(account, dict):
+                continue
+            provider_name = account.get("short_name") or account.get("display_name") or "Account"
+            for window in account.get("usage_windows") or []:
+                if not isinstance(window, dict):
+                    continue
+                windows.append({
+                    **window,
+                    "key": f'{account.get("provider_id", "oauth")}-{window.get("key", "usage")}',
+                    "title": f'{provider_name} {window.get("title") or "Usage"}',
+                })
+        return windows[:4]
+
+    def _oauth_account_chips(self, summary: dict) -> list[dict]:
+        accounts = summary.get("oauth_accounts") if isinstance(summary, dict) else {}
+        if not isinstance(accounts, dict):
+            return []
+        connected = accounts.get("connected") or []
+        available = accounts.get("available") or []
+        source = connected if connected else available
+        chips = []
+        for account in source[:4]:
+            if not isinstance(account, dict):
+                continue
+            chips.append({
+                "provider_id": account.get("provider_id") or "",
+                "label": account.get("short_name") or account.get("display_name") or account.get("provider_id"),
+                "detail": account.get("account_label") if account.get("connected") else "Available",
+                "connected": bool(account.get("connected")),
+            })
+        return chips
+
+    async def execute(self, banners: list = [], frontend_context: dict = {}, **kwargs):
+        # Optional logic: only show specific cards if plugins aren't already configured.
+        # Telegram, Email, Whatsapp are built-in, so we only need to check if they've been configured.
+
+        telegram_config = plugins.get_plugin_config("_telegram_integration") or {}
+        email_config = plugins.get_plugin_config("_email_integration") or {}
+        whatsapp_config = plugins.get_plugin_config("_whatsapp_integration") or {}
+        oauth_summary = self._oauth_summary()
+        oauth_accounts = oauth_summary.get("oauth_accounts") if isinstance(oauth_summary, dict) else {}
+        connected_count = int(oauth_accounts.get("connected_count") or 0) if isinstance(oauth_accounts, dict) else 0
+        total_count = int(oauth_accounts.get("total_count") or 0) if isinstance(oauth_accounts, dict) else 0
+
+        # 1. Plugin Hub Hero
+        banners.append({
+            "id": "discovery-plugin-hub",
+            "type": "hero",
+            "title": "Discover the Plugin Hub",
+            "description": "Extend Agent Zero with integrations, tools, and automations from the community.",
+            "thumbnail": "/plugins/_discovery/webui/assets/hero-plugin-hub.png",
+            "icon": "extension",
+            "cta_text": "Explore Plugins",
+            "cta_action": "open-plugin-hub",
+            "dismissible": True,
+            "priority": 100,
+            "show_in_onboarding": True
+        })
+
+        # 2. Telegram
+        if not telegram_config.get("bot_token"):
+            banners.append({
+                "id": "discovery-telegram",
+                "type": "feature",
+                "title": "Telegram",
+                "description": "Chat on Telegram wherever you are.",
+                "thumbnail": "/plugins/_discovery/webui/assets/thumb-telegram.png",
+                "icon": "send",
+                "cta_text": "Connect",
+                "cta_action": "open-plugin-config:_telegram_integration",
+                "dismissible": True,
+                "priority": 50,
+                "show_in_onboarding": True
+            })
+
+        # 3. Email
+        email_handlers = email_config.get("handlers") or []
+        email_is_configured = any((handler or {}).get("username") for handler in email_handlers)
+        if not email_is_configured:
+            banners.append({
+                "id": "discovery-email",
+                "type": "feature",
+                "title": "Email",
+                "description": "Let Agent Zero read and send emails on your behalf.",
+                "thumbnail": "/plugins/_discovery/webui/assets/thumb-email.png",
+                "icon": "mail",
+                "cta_text": "Connect",
+                "cta_action": "open-plugin-config:_email_integration",
+                "dismissible": True,
+                "priority": 50,
+                "show_in_onboarding": True
+            })
+
+        # 4. WhatsApp
+        if not whatsapp_config.get("phone_number_id"):
+            banners.append({
+                "id": "discovery-whatsapp",
+                "type": "feature",
+                "title": "WhatsApp",
+                "description": "Send and receive WhatsApp messages through A0.",
+                "thumbnail": "/plugins/_discovery/webui/assets/thumb-whatsapp.png",
+                "icon": "chat",
+                "cta_text": "Connect",
+                "cta_action": "open-plugin-config:_whatsapp_integration",
+                "dismissible": True,
+                "priority": 50,
+                "show_in_onboarding": True
+            })
+
+        # 5. OAuth account providers
+        oauth_card = {
+            "id": "discovery-oauth-accounts",
+            "type": "hero",
+            "placement": "after-features",
+            "title": "Your AI accounts",
+            "description": "Use your subscription-backed logins for model access."
+            if not connected_count
+            else "",
+            "cta_text": "Connect accounts" if not connected_count else "Manage accounts",
+            "cta_action": "open-plugin-config:_oauth",
+            "dismissible": True,
+            "priority": 40,
+            "show_in_onboarding": True,
+            "account_chips": self._oauth_account_chips(oauth_summary),
+        }
+        usage_windows = self._oauth_usage_windows(oauth_summary)
+        if usage_windows:
+            oauth_card["usage_windows"] = usage_windows
+        banners.append(oauth_card)

plugins/_discovery/extensions/webui/initFw_end/auto-modal.js

@@ -0,0 +1,136 @@
+import { callJsonApi } from "/js/api.js";
+import { isModalOpen } from "/js/modals.js";
+
+const DEFAULT_SURFACE = "welcome";
+const STARTUP_DELAY_MS = 650;
+const SUPPRESSION_PREFIX = "discovery_auto_modal_closed";
+
+let initialized = false;
+let lastOpened = null;
+let checking = false;
+
+function cleanPath(path = "") {
+  return String(path || "").replace(/^\/+/, "");
+}
+
+function currentContextId(fallback = "") {
+  try {
+    return fallback || globalThis.getContext?.() || sessionStorage.getItem("lastSelectedChat") || "welcome";
+  } catch {
+    return fallback || "welcome";
+  }
+}
+
+function bannerSupportsSurface(banner, surface) {
+  const surfaces = banner?.auto_modal_surfaces;
+  return !Array.isArray(surfaces) || surfaces.length === 0 || surfaces.includes(surface);
+}
+
+function suppressionKey({ surface, ctxid, reason, path }) {
+  return `${SUPPRESSION_PREFIX}:${surface}:${ctxid || "none"}:${reason || "unknown"}:${cleanPath(path)}`;
+}
+
+function isSuppressed(item) {
+  try {
+    return sessionStorage.getItem(suppressionKey(item)) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function suppress(item) {
+  try {
+    sessionStorage.setItem(suppressionKey(item), "1");
+  } catch {
+    // no-op
+  }
+}
+
+function modalAlreadyOpen(path) {
+  return isModalOpen(path);
+}
+
+async function fetchAutoModalBanner(surface, ctxid) {
+  const response = await callJsonApi("/banners", {
+    banners: [],
+    context: {
+      is_welcome: surface === "welcome",
+      is_onboarding: document.body.dataset.mode === "onboarding",
+      surface,
+      ctxid,
+    },
+  });
+
+  const banners = Array.isArray(response?.banners) ? response.banners : [];
+  return banners
+    .filter((banner) => banner?.auto_modal_path)
+    .filter((banner) => bannerSupportsSurface(banner, surface))
+    .sort((left, right) => (Number(right.auto_modal_priority || 0) - Number(left.auto_modal_priority || 0)))[0] || null;
+}
+
+async function maybeOpenAutoModal(surface = DEFAULT_SURFACE, detail = {}) {
+  if (checking) return;
+  checking = true;
+  const ctxid = currentContextId(detail.ctxid || "");
+
+  try {
+    const banner = await fetchAutoModalBanner(surface, ctxid);
+    if (!banner?.auto_modal_path) return;
+
+    const item = {
+      surface,
+      ctxid,
+      path: banner.auto_modal_path,
+      reason: banner.auto_modal_reason || banner.id || "auto-modal",
+    };
+
+    if (isSuppressed(item) || modalAlreadyOpen(item.path)) return;
+
+    const opener = globalThis.ensureModalOpen || globalThis.openModal;
+    if (!opener) return;
+
+    lastOpened = item;
+    await opener(item.path);
+  } catch (error) {
+    console.error("Discovery auto-modal check failed:", error);
+  } finally {
+    checking = false;
+  }
+}
+
+function handleModalClosed(event) {
+  const closedPath = event?.detail?.modalPath || "";
+  if (lastOpened && cleanPath(closedPath) === cleanPath(lastOpened.path)) {
+    suppress(lastOpened);
+    const surface = lastOpened.surface;
+    const ctxid = lastOpened.ctxid;
+    lastOpened = null;
+    window.setTimeout(() => {
+      void maybeOpenAutoModal(surface, { ctxid });
+    }, 250);
+    return;
+  }
+
+  window.setTimeout(() => {
+    void maybeOpenAutoModal(DEFAULT_SURFACE);
+  }, 250);
+}
+
+function handleChatCreated(event) {
+  const ctxid = event?.detail?.ctxid || "";
+  window.setTimeout(() => {
+    void maybeOpenAutoModal("chat-created", { ctxid });
+  }, 300);
+}
+
+export default function initDiscoveryAutoModal() {
+  if (initialized) return;
+  initialized = true;
+
+  document.addEventListener("modal-closed", handleModalClosed);
+  document.addEventListener("chat-created", handleChatCreated);
+
+  window.setTimeout(() => {
+    void maybeOpenAutoModal(DEFAULT_SURFACE);
+  }, STARTUP_DELAY_MS);
+}

plugins/_discovery/extensions/webui/onboarding-success-end/discovery-cards.html

@@ -0,0 +1,597 @@
+<script type="module">
+    import { store } from "/plugins/_discovery/webui/discovery-store.js";
+</script>
+
+<div x-data>
+    <template x-if="$store.discoveryStore">
+        <div class="discovery-slot"
+             @modal-closed.window="$store.discoveryStore.refreshCards()"
+             x-create="$store.discoveryStore.refreshCards()"
+             x-show="$store.discoveryStore.cards.length > 0 || $store.discoveryStore.hasDismissedCards">
+
+            <div class="discovery-section">
+
+                <div class="discovery-features" x-show="$store.discoveryStore.featureCards.length > 0" style="text-align: left;">
+                    <template x-for="card in $store.discoveryStore.featureCards" :key="card.id">
+                        <article class="discovery-feature-card"
+                                 role="button"
+                                 tabindex="0"
+                                 @click="$store.discoveryStore.executeCta(card.cta_action)"
+                                 @keydown.enter.prevent="$store.discoveryStore.executeCta(card.cta_action)"
+                                 @keydown.space.prevent="$store.discoveryStore.executeCta(card.cta_action)">
+
+                            <div class="discovery-feature-head">
+                                <div class="discovery-feature-thumb">
+                                    <template x-if="card.thumbnail">
+                                        <img :src="card.thumbnail" :alt="card.title" loading="lazy">
+                                    </template>
+                                    <template x-if="!card.thumbnail && card.icon">
+                                        <x-icon class="discovery-feature-icon" :name="card.icon"></x-icon>
+                                    </template>
+                                </div>
+                                <h4 class="discovery-feature-title" x-text="card.title"></h4>
+                            </div>
+
+                            <button class="btn btn primary"
+                                    type="button"
+                                    @click.stop="$store.discoveryStore.executeCta(card.cta_action)">
+                                <span x-text="card.cta_text"></span>
+                                <x-icon name="arrow_forward"></x-icon>
+                            </button>
+                        </article>
+                    </template>
+                </div>
+
+
+                <template x-for="card in $store.discoveryStore.heroCards.filter(card => !['discovery-codex-oauth', 'discovery-oauth-accounts'].includes(card.id))" :key="card.id">
+                    <article class="discovery-hero"
+                             role="button"
+                             tabindex="0"
+                             @click="$store.discoveryStore.executeCta(card.cta_action)"
+                             @keydown.enter.prevent="$store.discoveryStore.executeCta(card.cta_action)"
+                             @keydown.space.prevent="$store.discoveryStore.executeCta(card.cta_action)">
+                        <button class="discovery-dismiss"
+                                type="button"
+                                x-show="card.dismissible"
+                                @click.stop="$store.discoveryStore.dismissCard(card.id)"
+                                :aria-label="`Dismiss ${card.title}`"
+                                title="Dismiss">
+                            <x-icon name="close"></x-icon>
+                        </button>
+
+                        <div class="discovery-hero-content">
+                            <h3 class="discovery-hero-title" x-text="card.title"></h3>
+                            <p class="discovery-hero-desc" x-text="card.description"></p>
+                            <button class="btn btn-ok"
+                                    type="button"
+                                    @click.stop="$store.discoveryStore.executeCta(card.cta_action)">
+                                <span x-text="card.cta_text"></span>
+                                <x-icon name="arrow_forward"></x-icon>
+                            </button>
+                        </div>
+
+                        <div class="discovery-hero-thumb">
+                            <template x-if="card.thumbnail">
+                                <img :src="card.thumbnail" :alt="card.title" loading="lazy">
+                            </template>
+                            <template x-if="!card.thumbnail && card.icon">
+                                <x-icon class="discovery-hero-icon" :name="card.icon"></x-icon>
+                            </template>
+                        </div>
+                    </article>
+                </template>
+
+                <article class="discovery-cli-card" aria-labelledby="discovery-cli-title">
+                    <div class="discovery-cli-content">
+                        <span class="discovery-cli-kicker">CLI Connector</span>
+                        <h3 class="discovery-cli-title" id="discovery-cli-title">Connect Agent Zero to your desktop</h3>
+                        <p class="discovery-cli-desc">
+                            Install the CLI Connector when you want A0 to use your host terminal,
+                            local files, and a browser from your computer.
+                        </p>
+                        <div class="discovery-cli-commands" aria-label="CLI Connector install commands">
+                            <div class="discovery-cli-command">
+                                <span class="discovery-cli-label">macOS / Linux</span>
+                                <code>curl -LsSf https://cli.agent-zero.ai/install.sh | sh</code>
+                            </div>
+                            <div class="discovery-cli-command">
+                                <span class="discovery-cli-label">Windows PowerShell</span>
+                                <code>irm https://cli.agent-zero.ai/install.ps1 | iex</code>
+                            </div>
+                        </div>
+                    </div>
+
+                    <figure class="discovery-cli-preview" aria-label="Agent Zero CLI Connector preview">
+                        <img src="/plugins/_discovery/webui/assets/cli-connector-preview.png"
+                             alt="Agent Zero CLI Connector terminal preview"
+                             loading="lazy">
+                    </figure>
+                </article>
+
+                <div class="discovery-undismiss" x-show="$store.discoveryStore.hasDismissedCards">
+                    <button type="button"
+                            class="discovery-undismiss-btn"
+                            @click="$store.discoveryStore.undismissCards()">
+                        <x-icon name="undo"></x-icon>
+                        <span>Show dismissed suggestions</span>
+                    </button>
+                </div>
+            </div>
+        </div>
+    </template>
+
+    <style>
+        .discovery-slot {
+            grid-column: 1 / -1;
+            width: 100%;
+        }
+
+        .discovery-section {
+            display: flex;
+            flex-direction: column;
+            gap: 0.75rem;
+            width: 100%;
+            margin-top: 0.85rem;
+        }
+
+        .discovery-hero,
+        .discovery-feature-card,
+        .discovery-cli-card {
+            position: relative;
+            border: 1px solid var(--color-border);
+            border-radius: 10px;
+            background: var(--color-panel);
+            text-align: left;
+            transition:
+                border-color 0.2s ease,
+                background-color 0.2s ease,
+                box-shadow 0.2s ease,
+                transform 0.2s ease;
+        }
+
+        .discovery-hero:hover,
+        .discovery-feature-card:hover,
+        .discovery-cli-card:hover,
+        .discovery-hero:focus-visible,
+        .discovery-feature-card:focus-visible,
+        .discovery-cli-card:focus-visible {
+            border-color: color-mix(in srgb, var(--color-primary) 72%, white 6%);
+            box-shadow: 0 10px 28px rgba(0, 0, 0, 0.16);
+            outline: none;
+        }
+
+        .discovery-hero {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+            min-height: 126px;
+            overflow: hidden;
+            padding: 1rem 1.15rem 1rem 1.25rem;
+            background:
+                linear-gradient(
+                    135deg,
+                    color-mix(in srgb, var(--color-primary) 10%, transparent),
+                    transparent 58%
+                ),
+                radial-gradient(
+                    circle at 92% 24%,
+                    color-mix(in srgb, var(--color-primary) 12%, transparent),
+                    transparent 42%
+                ),
+                var(--color-panel);
+        }
+
+        .discovery-hero-content,
+        .discovery-hero-thumb {
+            position: relative;
+            z-index: 1;
+        }
+
+        .discovery-hero-content {
+            flex: 1 1 auto;
+            min-width: 0;
+        }
+
+        .discovery-hero-title {
+            margin: 0 0 0.35rem;
+            color: var(--color-text);
+            font-size: 1.02rem;
+            font-weight: 600;
+            letter-spacing: 0;
+        }
+
+        .discovery-hero-desc {
+            margin: 0 0 0.75rem;
+            color: var(--color-text);
+            font-size: 0.86rem;
+            line-height: 1.42;
+            max-width: 38ch;
+        }
+
+        .discovery-cta-link,
+        .discovery-undismiss-btn {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.35rem;
+            cursor: pointer;
+            transition:
+                background-color 0.2s ease,
+                border-color 0.2s ease,
+                color 0.2s ease,
+                transform 0.2s ease;
+        }
+
+        .discovery-hero-thumb {
+            flex: 0 0 112px;
+            width: 112px;
+            height: 86px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+
+        .discovery-hero-thumb img {
+            width: 100%;
+            height: 100%;
+            object-fit: contain;
+            filter: drop-shadow(0 12px 18px rgba(0, 0, 0, 0.12));
+        }
+
+        .discovery-hero-icon {
+            font-size: 3rem;
+            color: var(--color-highlight-dark);
+        }
+
+        .discovery-features {
+            display: grid;
+            grid-template-columns: repeat(3, minmax(0, 1fr));
+            gap: 0.75rem;
+        }
+
+        .discovery-feature-card {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) auto;
+            gap: 0.75rem;
+            align-items: center;
+            padding: 0.72rem 0.9rem;
+            background:
+                linear-gradient(
+                    180deg,
+                    color-mix(in srgb, var(--color-primary) 4%, transparent),
+                    transparent 38%
+                ),
+                var(--color-panel);
+        }
+
+        .discovery-feature-head {
+            display: flex;
+            flex-direction: row;
+            align-items: center;
+            gap: 0.62rem;
+            width: 100%;
+            min-width: 0;
+        }
+
+        .discovery-feature-thumb {
+            flex: 0 0 auto;
+            width: 32px;
+            height: 32px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border-radius: 12px;
+            overflow: hidden;
+            background: color-mix(in srgb, var(--color-primary) 10%, transparent);
+            box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-primary) 10%, transparent);
+        }
+
+        .discovery-feature-thumb img {
+            width: 100%;
+            height: 100%;
+            object-fit: cover;
+        }
+
+        .discovery-feature-icon {
+            font-size: 1.45rem;
+            color: var(--color-highlight-dark);
+        }
+
+        .discovery-feature-title {
+            margin: 0;
+            flex: 1 1 auto;
+            min-width: 0;
+            color: var(--color-text);
+            font-size: 0.88rem;
+            font-weight: 600;
+            line-height: 1.25;
+        }
+
+        .discovery-feature-card > .btn {
+            min-height: 36px;
+            padding: 0.44rem 0.78rem;
+        }
+
+        .discovery-feature-card > .btn .material-symbols-outlined {
+            font-size: 1.15rem;
+        }
+
+        .discovery-cli-card {
+            display: flex;
+            align-items: center;
+            gap: 1.1rem;
+            min-height: 134px;
+            overflow: hidden;
+            padding: 1rem 1.15rem 1rem 1.25rem;
+            background:
+                linear-gradient(
+                    135deg,
+                    color-mix(in srgb, var(--color-primary) 12%, transparent),
+                    transparent 52%
+                ),
+                radial-gradient(
+                    circle at 86% 18%,
+                    color-mix(in srgb, #00b7ff 14%, transparent),
+                    transparent 34%
+                ),
+                var(--color-panel);
+        }
+
+        .discovery-cli-content {
+            flex: 1 1 auto;
+            min-width: 0;
+        }
+
+        .discovery-cli-kicker {
+            display: inline-flex;
+            width: max-content;
+            margin-bottom: 0.3rem;
+            border: 1px solid color-mix(in srgb, var(--color-primary) 34%, var(--color-border));
+            border-radius: 999px;
+            padding: 0.16rem 0.48rem;
+            color: color-mix(in srgb, var(--color-primary) 72%, white 20%);
+            font-size: 0.68rem;
+            font-weight: 700;
+            line-height: 1;
+            text-transform: uppercase;
+        }
+
+        .discovery-cli-title {
+            margin: 0 0 0.28rem;
+            color: var(--color-text);
+            font-size: 1.02rem;
+            font-weight: 700;
+            line-height: 1.2;
+        }
+
+        .discovery-cli-desc {
+            max-width: 62ch;
+            margin: 0 0 0.65rem;
+            color: var(--color-secondary);
+            font-size: 0.8rem;
+            line-height: 1.38;
+        }
+
+        .discovery-cli-commands {
+            display: grid;
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+            gap: 0.55rem;
+            max-width: 790px;
+        }
+
+        .discovery-cli-command {
+            min-width: 0;
+            border: 1px solid color-mix(in srgb, var(--color-border) 82%, transparent);
+            border-radius: 8px;
+            background: color-mix(in srgb, #05080c 86%, var(--color-panel));
+            padding: 0.48rem 0.55rem;
+        }
+
+        .discovery-cli-label {
+            display: block;
+            margin-bottom: 0.22rem;
+            color: var(--color-secondary);
+            font-size: 0.68rem;
+            font-weight: 700;
+            line-height: 1.1;
+        }
+
+        .discovery-cli-command code {
+            display: block;
+            overflow-x: auto;
+            color: #72d8ff;
+            font-family: var(--font-family-monospace, ui-monospace, SFMono-Regular, Consolas, monospace);
+            font-size: 0.72rem;
+            line-height: 1.35;
+            white-space: nowrap;
+        }
+
+        .discovery-cli-preview {
+            flex: 0 0 218px;
+            width: 218px;
+            margin: 0;
+            border: 1px solid color-mix(in srgb, #00b7ff 24%, var(--color-border));
+            border-radius: 8px;
+            background: #070b10;
+            box-shadow:
+                0 12px 28px rgba(0, 0, 0, 0.2),
+                0 0 28px color-mix(in srgb, var(--color-primary) 12%, transparent);
+            overflow: hidden;
+        }
+
+        .discovery-cli-preview img {
+            display: block;
+            width: 100%;
+            height: auto;
+        }
+
+        .discovery-cta-link {
+            margin-top: 0.95rem;
+            border: 1px solid color-mix(in srgb, var(--color-primary) 34%, var(--color-border));
+            border-radius: 8px;
+            background: transparent;
+            color: var(--color-primary);
+            padding: 0.42rem 0.72rem;
+            font-size: 0.79rem;
+            font-weight: 600;
+        }
+
+        .discovery-cta-link:hover,
+        .discovery-cta-link:focus-visible {
+            background: var(--color-primary);
+            border-color: var(--color-primary);
+            color: #fff;
+            outline: none;
+        }
+
+        .discovery-dismiss {
+            position: absolute;
+            top: 0.65rem;
+            right: 0.65rem;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            width: 28px;
+            height: 28px;
+            border: none;
+            border-radius: 8px;
+            background: transparent;
+            color: var(--color-secondary);
+            cursor: pointer;
+            opacity: 0;
+            transition:
+                opacity 0.2s ease,
+                background-color 0.2s ease,
+                color 0.2s ease;
+            z-index: 2;
+        }
+
+        .discovery-dismiss-small {
+            top: 0.55rem;
+            right: 0.55rem;
+            width: 26px;
+            height: 26px;
+        }
+
+        .discovery-hero:hover .discovery-dismiss,
+        .discovery-hero:focus-visible .discovery-dismiss,
+        .discovery-feature-card:hover .discovery-dismiss,
+        .discovery-feature-card:focus-visible .discovery-dismiss {
+            opacity: 0.68;
+        }
+
+        .discovery-dismiss:hover,
+        .discovery-dismiss:focus-visible {
+            opacity: 1;
+            color: var(--color-text);
+            background: color-mix(in srgb, var(--color-border) 84%, transparent);
+            outline: none;
+        }
+
+        .discovery-dismiss .material-symbols-outlined {
+            font-size: 1rem;
+        }
+
+        .discovery-undismiss {
+            display: flex;
+            justify-content: flex-start;
+        }
+
+        .discovery-undismiss-btn {
+            border: none;
+            background: transparent;
+            padding: 0;
+            color: var(--color-secondary);
+            font-size: 0.8rem;
+            font-weight: 500;
+        }
+
+        .discovery-undismiss-btn:hover,
+        .discovery-undismiss-btn:focus-visible {
+            color: var(--color-primary);
+            outline: none;
+        }
+
+        .discovery-cta-link .material-symbols-outlined,
+        .discovery-undismiss-btn .material-symbols-outlined {
+            font-size: 1rem;
+        }
+
+        @media (hover: none) {
+            .discovery-dismiss {
+                opacity: 0.68;
+            }
+        }
+
+        @media (max-width: 768px) {
+            .discovery-section {
+                gap: 0.85rem;
+            }
+
+            .discovery-hero {
+                min-height: 0;
+                padding: 1rem;
+            }
+
+            .discovery-hero-thumb {
+                flex-basis: 92px;
+                width: 92px;
+                height: 76px;
+            }
+
+            .discovery-features {
+                grid-template-columns: 1fr;
+                gap: 0.75rem;
+            }
+
+            .discovery-cta-link {
+                margin-top: 0;
+            }
+
+            .discovery-cli-card {
+                flex-direction: column;
+                align-items: flex-start;
+                gap: 0.75rem;
+                min-height: 0;
+                padding: 0.95rem;
+            }
+
+            .discovery-cli-commands {
+                grid-template-columns: 1fr;
+                width: 100%;
+                max-width: none;
+            }
+
+            .discovery-cli-preview {
+                flex: 0 0 auto;
+                width: min(100%, 280px);
+            }
+        }
+
+        @media (max-width: 520px) {
+            .discovery-slot {
+                margin-top: 0.15rem;
+            }
+
+            .discovery-hero {
+                padding-right: 0.95rem;
+            }
+
+            .discovery-hero-thumb {
+                display: none;
+            }
+
+            .discovery-hero-title {
+                font-size: 1rem;
+            }
+
+            .discovery-cli-title {
+                font-size: 0.98rem;
+            }
+
+            .discovery-cli-preview {
+                width: 100%;
+            }
+        }
+    </style>
+</div>

plugins/_discovery/extensions/webui/welcome-actions-end/discovery-cards.html

@@ -0,0 +1,557 @@
+<script type="module">
+    import { store } from "/plugins/_discovery/webui/discovery-store.js";
+</script>
+
+<div x-data>
+    <template x-if="$store.discoveryStore">
+        <div class="discovery-slot"
+             @modal-closed.window="$store.discoveryStore.refreshCards()"
+             x-create="$store.discoveryStore.refreshCards()"
+             x-show="$store.discoveryStore.featureCards.length > 0 || $store.discoveryStore.oauthAccountCards.length > 0 || $store.discoveryStore.hasDismissedCards">
+
+            <section class="discovery-features-panel" x-show="$store.discoveryStore.featureCards.length > 0">
+                <header class="discovery-panel-header">
+                    <div class="discovery-panel-copy">
+                        <h2>Connect Channels</h2>
+                        <p>Extend Agent Zero across your favorite platforms.</p>
+                    </div>
+                    <button class="discovery-dismiss discovery-panel-dismiss"
+                            type="button"
+                            x-show="$store.discoveryStore.featureCards.some(card => card.dismissible !== false)"
+                            @click.stop="$store.discoveryStore.dismissFeatureCards()"
+                            aria-label="Dismiss Connect Channels"
+                            title="Dismiss">
+                        <x-icon name="close"></x-icon>
+                    </button>
+                </header>
+
+                <div class="discovery-features">
+                    <template x-for="card in $store.discoveryStore.featureCards" :key="card.id">
+                        <button class="discovery-feature-card"
+                                type="button"
+                                @click="$store.discoveryStore.executeCta(card.cta_action)">
+                            <span class="discovery-feature-thumb">
+                                <template x-if="card.thumbnail">
+                                    <img :src="card.thumbnail" :alt="card.title" loading="lazy">
+                                </template>
+                                <template x-if="!card.thumbnail && card.icon">
+                                    <x-icon class="discovery-feature-icon" :name="card.icon"></x-icon>
+                                </template>
+                            </span>
+                            <span class="discovery-feature-title" x-text="`${card.cta_text || 'Connect'} ${card.title}`"></span>
+                        </button>
+                    </template>
+                </div>
+            </section>
+
+            <template x-for="card in $store.discoveryStore.oauthAccountCards" :key="card.id">
+                <article class="discovery-account-card">
+                    <button class="discovery-dismiss"
+                            type="button"
+                            x-show="card.dismissible"
+                            @click.stop="$store.discoveryStore.dismissCard(card.id)"
+                            :aria-label="`Dismiss ${card.title}`"
+                            title="Dismiss">
+                        <x-icon name="close"></x-icon>
+                    </button>
+
+                    <header class="discovery-account-header">
+                        <div class="discovery-account-copy">
+                            <h2 x-text="card.title"></h2>
+                            <p x-show="card.description" x-text="card.description"></p>
+                        </div>
+                        <button class="btn btn primary discovery-account-cta"
+                                type="button"
+                                @click="$store.discoveryStore.executeCta(card.cta_action)">
+                            <span x-text="card.cta_text"></span>
+                            <x-icon name="arrow_forward"></x-icon>
+                        </button>
+                    </header>
+
+                    <div class="discovery-account-chips" x-show="(card.account_chips || []).length > 0">
+                        <template x-for="chip in card.account_chips || []" :key="chip.provider_id || chip.label">
+                            <span class="discovery-account-chip" :class="{ 'is-connected': chip.connected }">
+                                <span class="discovery-account-chip-dot" aria-hidden="true"></span>
+                                <span class="discovery-account-chip-label" x-text="chip.label"></span>
+                                <span class="discovery-account-chip-detail" x-show="chip.detail" x-text="chip.detail"></span>
+                            </span>
+                        </template>
+                    </div>
+
+                    <div class="discovery-account-usage" x-show="(card.usage_windows || []).length > 0">
+                        <template x-for="window in card.usage_windows || []" :key="window.key || window.title">
+                            <div class="discovery-account-usage-row">
+                                <div class="discovery-account-usage-label">
+                                    <span x-text="window.title"></span>
+                                    <small x-show="$store.discoveryStore.formatReset(window)"
+                                           x-text="`Resets in ${$store.discoveryStore.formatReset(window)}`"></small>
+                                </div>
+                                <div class="discovery-account-usage-meter">
+                                    <span class="discovery-account-usage-track">
+                                        <span class="discovery-account-usage-fill"
+                                              :style="`width: ${$store.discoveryStore.usageWidth(window)}`"></span>
+                                    </span>
+                                    <span class="discovery-account-usage-value"
+                                          x-text="$store.discoveryStore.formatRemainingPercent(window)"></span>
+                                </div>
+                            </div>
+                        </template>
+                    </div>
+
+                </article>
+            </template>
+
+            <div class="discovery-undismiss" x-show="$store.discoveryStore.hasDismissedCards">
+                <button type="button"
+                        class="discovery-undismiss-btn"
+                        @click="$store.discoveryStore.undismissCards()">
+                    <x-icon name="undo"></x-icon>
+                    <span>Show dismissed suggestions</span>
+                </button>
+            </div>
+        </div>
+    </template>
+
+    <style>
+        .discovery-slot {
+            display: grid;
+            gap: 1rem;
+            min-width: 0;
+            width: 100%;
+        }
+
+        .discovery-features-panel,
+        .discovery-account-card {
+            border: 1px solid color-mix(in srgb, var(--color-border) 66%, transparent);
+            border-radius: 8px;
+            background: color-mix(in srgb, var(--color-panel) 78%, var(--color-background) 22%);
+            box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.026);
+            backdrop-filter: blur(18px);
+            text-align: left;
+        }
+
+        .discovery-features-panel {
+            min-height: 100%;
+            padding: 1.25rem 1.45rem;
+        }
+
+        .discovery-panel-header {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) auto;
+            gap: 0.7rem;
+            align-items: start;
+            margin-bottom: 1.28rem;
+        }
+
+        .discovery-panel-copy {
+            display: grid;
+            gap: 0.42rem;
+            min-width: 0;
+        }
+
+        .discovery-panel-header h2 {
+            margin: 0;
+            color: var(--color-text);
+            font-size: 1.05rem;
+            font-weight: 520;
+            line-height: 1.2;
+        }
+
+        .discovery-panel-header p {
+            margin: 0;
+            color: color-mix(in srgb, var(--color-text) 58%, transparent);
+            font-size: 0.92rem;
+            line-height: 1.35;
+        }
+
+        .discovery-features {
+            display: grid;
+            grid-template-columns: repeat(3, minmax(0, 1fr));
+            gap: 0.65rem;
+        }
+
+        .discovery-feature-card {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.5rem;
+            min-width: 0;
+            min-height: 3.1rem;
+            border: 1px solid color-mix(in srgb, var(--color-border) 52%, transparent);
+            border-radius: 8px;
+            padding: 0.56rem 0.58rem;
+            background: color-mix(in srgb, var(--color-background) 50%, transparent);
+            color: inherit;
+            cursor: pointer;
+            font-family: var(--font-family-main, "Rubik", Arial, Helvetica, sans-serif);
+            text-align: left;
+            transition:
+                border-color 0.18s ease,
+                background-color 0.18s ease;
+        }
+
+        .discovery-feature-thumb {
+            flex: 0 0 auto;
+            width: 32px;
+            height: 32px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border-radius: 999px;
+            overflow: hidden;
+            background: color-mix(in srgb, var(--color-primary) 10%, transparent);
+            box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-primary) 10%, transparent);
+        }
+
+        .discovery-feature-thumb img {
+            width: 100%;
+            height: 100%;
+            object-fit: cover;
+        }
+
+        .discovery-feature-icon {
+            font-size: 1.45rem;
+            color: var(--color-highlight-dark);
+        }
+
+        .discovery-feature-title {
+            margin: 0;
+            flex: 1 1 auto;
+            min-width: 0;
+            color: var(--color-text);
+            font-size: 0.84rem;
+            font-weight: 520;
+            line-height: 1.25;
+        }
+
+        .discovery-feature-card:hover,
+        .discovery-feature-card:focus-visible {
+            border-color: color-mix(in srgb, var(--color-border) 88%, var(--color-text) 12%);
+            background: color-mix(in srgb, var(--color-panel) 86%, var(--color-background) 14%);
+            outline: none;
+        }
+
+        .discovery-dismiss {
+            position: absolute;
+            top: 0.65rem;
+            right: 0.65rem;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            width: 28px;
+            height: 28px;
+            border: none;
+            border-radius: 8px;
+            background: transparent;
+            color: var(--color-secondary);
+            cursor: pointer;
+            opacity: 0;
+            transition:
+                opacity 0.2s ease,
+                background-color 0.2s ease,
+                color 0.2s ease;
+            z-index: 2;
+        }
+
+        .discovery-dismiss-small {
+            top: 0.55rem;
+            right: 0.55rem;
+            width: 26px;
+            height: 26px;
+        }
+
+        .discovery-panel-dismiss {
+            position: static;
+            opacity: 0.68;
+        }
+
+        .discovery-account-card > .discovery-dismiss {
+            opacity: 0.68;
+        }
+
+        .discovery-dismiss:hover,
+        .discovery-dismiss:focus-visible {
+            opacity: 1;
+            color: var(--color-text);
+            background: color-mix(in srgb, var(--color-border) 84%, transparent);
+            outline: none;
+        }
+
+        .discovery-dismiss .material-symbols-outlined {
+            font-size: 1rem;
+        }
+
+        .discovery-account-card {
+            position: relative;
+            display: grid;
+            gap: 1rem;
+            padding: 1.25rem 1.45rem 1.25rem;
+        }
+
+        .discovery-account-header {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) auto;
+            gap: 0.95rem;
+            align-items: center;
+            min-width: 0;
+            padding-right: 2.1rem;
+        }
+
+        .discovery-account-copy {
+            display: grid;
+            gap: 0.3rem;
+            min-width: 0;
+        }
+
+        .discovery-account-copy h2 {
+            margin: 0;
+            color: var(--color-text);
+            font-size: 1.05rem;
+            font-weight: 520;
+            line-height: 1.2;
+        }
+
+        .discovery-account-copy p {
+            margin: 0;
+            color: color-mix(in srgb, var(--color-text) 58%, transparent);
+            font-size: 0.9rem;
+            line-height: 1.42;
+        }
+
+        .discovery-account-chips {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 0.5rem;
+            min-width: 0;
+        }
+
+        .discovery-account-chip {
+            display: inline-grid;
+            grid-template-columns: auto auto minmax(0, auto);
+            align-items: center;
+            gap: 0.4rem;
+            max-width: 100%;
+            min-height: 2rem;
+            padding: 0.32rem 0.58rem;
+            border: 1px solid color-mix(in srgb, var(--color-border) 52%, transparent);
+            border-radius: 8px;
+            background: color-mix(in srgb, var(--color-background) 50%, transparent);
+            color: color-mix(in srgb, var(--color-text) 74%, transparent);
+            font-size: 0.8rem;
+            line-height: 1.2;
+        }
+
+        .discovery-account-chip-dot {
+            width: 0.44rem;
+            height: 0.44rem;
+            border-radius: 999px;
+            background: color-mix(in srgb, var(--color-text) 34%, transparent);
+        }
+
+        .discovery-account-chip.is-connected .discovery-account-chip-dot {
+            background: #22c55e;
+        }
+
+        .discovery-account-chip-label,
+        .discovery-account-chip-detail {
+            min-width: 0;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+        }
+
+        .discovery-account-chip-label {
+            color: var(--color-text);
+            font-weight: 500;
+        }
+
+        .discovery-account-chip-detail {
+            color: color-mix(in srgb, var(--color-text) 52%, transparent);
+        }
+
+        .discovery-account-usage {
+            display: grid;
+            gap: 0.74rem;
+            padding-top: 0.12rem;
+        }
+
+        .discovery-account-usage-row {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) minmax(8rem, 0.82fr);
+            gap: 1rem;
+            align-items: center;
+            min-width: 0;
+        }
+
+        .discovery-account-usage-label {
+            display: grid;
+            gap: 0.22rem;
+            min-width: 0;
+        }
+
+        .discovery-account-usage-label span,
+        .discovery-account-usage-label small {
+            min-width: 0;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+        }
+
+        .discovery-account-usage-label span {
+            color: color-mix(in srgb, var(--color-text) 74%, transparent);
+            font-size: 0.84rem;
+            line-height: 1.25;
+        }
+
+        .discovery-account-usage-label small {
+            color: color-mix(in srgb, var(--color-text) 44%, transparent);
+            font-size: 0.72rem;
+            line-height: 1.2;
+        }
+
+        .discovery-account-usage-meter {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) auto;
+            gap: 0.58rem;
+            align-items: center;
+            min-width: 0;
+        }
+
+        .discovery-account-usage-track {
+            height: 0.52rem;
+            overflow: hidden;
+            border-radius: 999px;
+            background: color-mix(in srgb, var(--color-border) 70%, transparent);
+        }
+
+        .discovery-account-usage-fill {
+            display: block;
+            height: 100%;
+            border-radius: inherit;
+            background: #22c55e;
+            transition: width 0.22s ease;
+        }
+
+        .discovery-account-usage-value {
+            color: color-mix(in srgb, var(--color-text) 70%, transparent);
+            font-family: var(--font-family-code, "Roboto Mono", monospace);
+            font-size: 0.74rem;
+            line-height: 1;
+            white-space: nowrap;
+        }
+
+        .discovery-account-cta {
+            justify-self: end;
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.36rem;
+            min-height: 2.35rem;
+            min-width: 8.65rem;
+            border: 0;
+            border-radius: 8px;
+            padding: 0.55rem 0.9rem;
+            background-color: #4248f1;
+            color: #fff;
+            font-family: var(--font-family-main, "Rubik", Arial, Helvetica, sans-serif);
+            font-size: 0.88rem;
+            font-weight: 460;
+            white-space: nowrap;
+            box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.2);
+        }
+
+        .discovery-account-cta:hover,
+        .discovery-account-cta:focus-visible {
+            background-color: #353bc5;
+            filter: none;
+            outline: none;
+        }
+
+        .discovery-account-cta .material-symbols-outlined {
+            font-size: 1.05rem;
+        }
+
+        .discovery-undismiss {
+            display: flex;
+            justify-content: flex-start;
+        }
+
+        .discovery-undismiss-btn {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.35rem;
+            border: none;
+            background: transparent;
+            padding: 0;
+            color: var(--color-secondary);
+            cursor: pointer;
+            font-size: 0.8rem;
+            font-weight: 500;
+            transition: color 0.2s ease;
+        }
+
+        .discovery-undismiss-btn:hover,
+        .discovery-undismiss-btn:focus-visible {
+            color: var(--color-primary);
+            outline: none;
+        }
+
+        .discovery-undismiss-btn .material-symbols-outlined {
+            font-size: 1rem;
+        }
+
+        @media (hover: none) {
+            .discovery-dismiss {
+                opacity: 0.68;
+            }
+        }
+
+        @media (max-width: 768px) {
+            .discovery-features {
+                grid-template-columns: 1fr;
+                gap: 0.75rem;
+            }
+
+            .discovery-feature-card {
+                display: inline-flex;
+                min-height: 0;
+                padding: 0.62rem 0.7rem;
+            }
+
+            .discovery-feature-thumb {
+                width: 32px;
+                height: 32px;
+            }
+
+            .discovery-account-usage-row {
+                grid-template-columns: 1fr;
+                gap: 0.45rem;
+            }
+        }
+
+        @media (max-width: 520px) {
+            .discovery-slot {
+                margin-top: 0.15rem;
+            }
+
+            .discovery-feature-card {
+                padding-right: 0.7rem;
+            }
+
+            .discovery-account-card {
+                padding: 1.05rem;
+            }
+
+            .discovery-account-header {
+                grid-template-columns: 1fr;
+                padding-right: 2.2rem;
+            }
+
+            .discovery-account-cta {
+                grid-column: 1 / -1;
+                justify-self: start;
+            }
+
+        }
+    </style>
+</div>

plugins/_discovery/plugin.yaml

@@ -0,0 +1,8 @@
+name: _discovery
+title: Plugin Discovery
+description: Contextual discovery cards on the welcome screen promoting plugins and integrations.
+version: 1.0.0
+settings_sections: []
+always_enabled: true
+per_project_config: false
+per_agent_config: false

plugins/_discovery/webui/discovery-store.js

@@ -0,0 +1,190 @@
+import { createStore } from "/js/AlpineStore.js";
+import { toastFrontendError } from "/components/notifications/notification-store.js";
+import { store as pluginListStore } from "/components/plugins/list/pluginListStore.js";
+import * as API from "/js/api.js";
+
+const STORAGE_KEY = "dismissed_discovery_cards";
+
+const model = {
+  // --- State ---
+  /** @type {any[]} */
+  cards: [],
+  hasDismissedCards: false,
+  _initialized: false,
+  _isLoading: false,
+
+  // --- Lifecycle ---
+  init() {
+    if (this._initialized) return;
+    this._initialized = true;
+  },
+
+  // --- Actions ---
+
+  async refreshCards() {
+    if (this._isLoading) return;
+    this._isLoading = true;
+    
+    try {
+      const response = await API.callJsonApi("/banners", {
+        banners: [],
+        context: {
+            is_onboarding: document.body.dataset.mode === "onboarding"
+        },
+      });
+      
+      const banners = response?.banners || [];
+      const dismissed = this._getDismissedIds();
+      
+      // Filter out standard banners, keep only hero and feature
+      // Also respect the onboarding filtering
+      const is_onboarding = document.body.dataset.mode === "onboarding";
+      
+      this.cards = banners
+        .filter((card) => card.type === "hero" || card.type === "feature")
+        .filter((card) => !is_onboarding || card.show_in_onboarding === true)
+        .filter((card) => !dismissed.has(card.id))
+        .sort((left, right) => (right.priority || 0) - (left.priority || 0));
+        
+      this.hasDismissedCards = dismissed.size > 0;
+    } catch (error) {
+      console.error("Failed to fetch discovery cards:", error);
+    } finally {
+      this._isLoading = false;
+    }
+  },
+
+  dismissCard(cardId) {
+    const dismissed = this._getDismissedIds();
+    dismissed.add(cardId);
+    this._persistDismissedIds(dismissed);
+    
+    // Optimistically update UI
+    this.cards = this.cards.filter(c => c.id !== cardId);
+    this.hasDismissedCards = true;
+  },
+
+  dismissFeatureCards() {
+    const featureIds = this.featureCards
+      .filter((card) => card.dismissible !== false)
+      .map((card) => card.id)
+      .filter(Boolean);
+
+    if (!featureIds.length) return;
+
+    const dismissed = this._getDismissedIds();
+    const dismissSet = new Set(featureIds);
+    for (const id of dismissSet) {
+      dismissed.add(id);
+    }
+    this._persistDismissedIds(dismissed);
+
+    this.cards = this.cards.filter((card) => !dismissSet.has(card.id));
+    this.hasDismissedCards = true;
+  },
+
+  undismissCards() {
+    localStorage.removeItem(STORAGE_KEY);
+    this.refreshCards();
+  },
+
+  async executeCta(action) {
+    if (!action) return;
+
+    try {
+      if (action === "open-plugin-hub") {
+        await pluginListStore.open("pluginHub");
+        return;
+      }
+
+      if (action.startsWith("open-plugin-config:")) {
+        const pluginName = action.split(":")[1];
+        await pluginListStore.openPluginConfig(pluginName);
+        return;
+      }
+
+      if (action.startsWith("open-url:")) {
+        const url = action.slice("open-url:".length);
+        if (url) {
+          window.open(url, "_blank", "noopener,noreferrer");
+        }
+        return;
+      }
+    } catch (error) {
+      console.error("Discovery action failed:", error);
+      const message = error instanceof Error ? error.message : String(error);
+      await toastFrontendError(message, "Discovery");
+    }
+  },
+
+  usageWidth(window) {
+    const value = Math.max(0, Math.min(100, this.remainingPercent(window)));
+    return `${value}%`;
+  },
+
+  remainingPercent(window) {
+    const remaining = Number(window?.remaining_percent);
+    if (Number.isFinite(remaining)) return remaining;
+    const used = Number(window?.used_percent);
+    if (Number.isFinite(used)) return 100 - used;
+    return Number.NaN;
+  },
+
+  formatRemainingPercent(window) {
+    const number = this.remainingPercent(window);
+    if (!Number.isFinite(number)) return "0%";
+    return `${Math.round(number * 10) / 10}% left`;
+  },
+
+  formatReset(window) {
+    const seconds = Number(window?.reset_at || 0);
+    if (!Number.isFinite(seconds) || seconds <= 0) return "";
+    const remainingMs = Math.max(0, seconds * 1000 - Date.now());
+    const minutes = Math.round(remainingMs / 60000);
+    if (minutes < 60) return `${minutes}m`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48) return `${hours}h`;
+    return `${Math.round(hours / 24)}d`;
+  },
+
+  // --- Helpers (Private-ish) ---
+
+  _getDismissedIds() {
+    try {
+      const raw = JSON.parse(localStorage.getItem(STORAGE_KEY) || "[]");
+      if (!Array.isArray(raw)) return new Set();
+      return new Set(raw);
+    } catch {
+      return new Set();
+    }
+  },
+
+  _persistDismissedIds(ids) {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(Array.from(ids)));
+  },
+
+  // --- Computed ---
+
+  get topHeroCards() {
+    return this.cards.filter((card) => card.type === "hero" && card.placement !== "after-features");
+  },
+
+  get bottomHeroCards() {
+    return this.cards.filter((card) => card.type === "hero" && card.placement === "after-features");
+  },
+
+  get oauthAccountCards() {
+    return this.bottomHeroCards.filter((card) => card.id === "discovery-oauth-accounts");
+  },
+
+  get heroCards() {
+    return [...this.topHeroCards, ...this.bottomHeroCards];
+  },
+
+  get featureCards() {
+    return this.cards.filter((card) => card.type === "feature");
+  },
+};
+
+const store = createStore("discoveryStore", model);
+export { store };

plugins/_document_query/AGENTS.md

@@ -0,0 +1,31 @@
+# Document Query Plugin DOX
+
+## Purpose
+
+- Own document loading, parsing, indexing, and Q&A over local and remote documents.
+
+## Ownership
+
+- `tools/document_query.py` owns the agent-facing query tool.
+- `helpers/` owns fetching, parser routing, indexing, and query orchestration.
+- `prompts/` owns document-query tool and optimization prompts.
+- `hooks.py`, `default_config.yaml`, `plugin.yaml`, `skills/`, `extensions/`, and `webui/` own dependency bootstrap, settings, metadata, skill guidance, hooks, and UI.
+
+## Local Contracts
+
+- Respect configured size, timeout, retry, parser concurrency, and OCR limits.
+- Fetch local and remote resources safely and avoid leaking document contents beyond intended prompt/tool use.
+- Keep optional dependency installation targeted to the framework runtime.
+
+## Work Guidance
+
+- Coordinate parser changes with timeout handling and fallback behavior.
+- Keep prompt and skill guidance clear that image files, screenshots, scans, charts, photos, and diagrams should go to vision tools first when available; `document_query` image OCR is a text-focused fallback when vision is unavailable or cannot read the needed text.
+
+## Verification
+
+- Smoke-test representative PDF, text/HTML, image/OCR, and remote-document queries after parser changes.
+
+## Child DOX Index
+
+No child DOX files.

plugins/_document_query/README.md

@@ -0,0 +1,62 @@
+# Document Query Plugin
+
+Load, parse, index, and Q&A over local and remote documents with configurable
+timeouts and thread-safe parsers.
+
+## Features
+
+- **Strategy-pattern parsers** - MIME-type routing to dedicated parser classes
+- **Centralized fetching** - local and HTTP(S) resources are fetched once, size-checked, then passed to parsers
+- **LiteParse first path** - fast local parsing for PDFs and supported document/image formats, with legacy fallbacks
+- **Adaptive OCR** - long PDFs skip OCR automatically to avoid pathological parse times
+- **Adaptive indexing** - very large extracted documents increase chunk size to keep embedding work bounded
+- **Bounded parser execution** - sync parsers are offloaded to asyncio.to_thread and globally capped across chats
+- **Configurable timeouts** - per-document and gather-level timeouts
+- **Expanded format support** - PDF, HTML, text, YAML, XML, TOML, JS, TS, images, and catch-all Unstructured
+
+## Configuration
+
+See default_config.yaml for all options. Key settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| fetch_timeout | 30 | HTTP fetch timeout (seconds) |
+| fetch_retries | 3 | HTTP retry attempts |
+| max_remote_bytes | 52428800 | Max remote document size |
+| per_document_timeout | 60 | Max time for a single document parse |
+| gather_timeout | 120 | Max time for all documents combined |
+| parser_concurrency | 1 | Max parser jobs running across all chats in one process |
+| context_intro_chunks | 2 | Leading chunks included per document for title/abstract grounding |
+| chunk_size | 1000 | Text splitter chunk size |
+| chunk_overlap | 100 | Text splitter overlap |
+| max_index_chunks | 1200 | Maximum indexed chunks before adaptive chunk sizing, or 0 for no cap |
+| search_threshold | 0.5 | Similarity search threshold |
+| liteparse_enabled | true | Prefer LiteParse before legacy parser fallbacks |
+| liteparse_num_workers | 2 | Max LiteParse OCR workers per parser job |
+| liteparse_ocr_auto_disable_pages | 30 | Disable OCR for PDFs at or above this effective page count |
+| thread_offload | true | Offload sync parsers to thread pool |
+
+LiteParse is installed into the Agent Zero framework runtime from hooks.py during
+plugin install/startup. If installation fails, the plugin logs the error and
+continues with the legacy parser fallbacks.
+
+LiteParse always runs in a child process so native parser and OCR failures stay
+isolated from the Web UI process.
+
+## Parsers
+
+| Parser | MIME Types | Backend |
+|--------|-----------|---------|
+| LiteParseParser | PDF, Office/OpenDocument, images | LiteParse |
+| PdfParser | application/pdf | PyMuPDF + Tesseract OCR fallback |
+| HtmlParser | text/html | Markdownify transformer |
+| TextParser | text/*, application/json, YAML, XML, TOML, JS, TS, shell | Direct read |
+| ImageParser | image/* | UnstructuredLoader |
+| UnstructuredParser | * (catch-all) | UnstructuredLoader hi-res |
+
+## Adding a new parser
+
+1. Create helpers/parsers/<format>.py extending BaseParser
+2. Set mimetypes class attribute
+3. Implement _parse_sync(document, config)
+4. Register in helpers/parsers/__init__.py