✨ feat: widget-builder builtin plugin with stlite console rendering, capability gating, and SessionTool protocol

- Add `builtin_plugins/widget_builder` as a bundled plugin: `SubmitWidgetTool`, extensible
  AST lint pipeline, `st-widget-builder` agent + skill, Jinja2 prompt template, and reusable
  Streamlit component library (PlantUMLCard, GitHub repo card, stock ticker, search result card)
- Add `capabilities.py`: pure `parse_capabilities`, `filter_by_capabilities`, and
  `overlay_capabilities` helpers for frontmatter-driven capability gating across agents, skills,
  and plugins
- Add `session_tools.py`: `SessionTool` Protocol and `SessionToolRegistry`; retrofit
  `ExitPlanModeTool` to satisfy the protocol; replace single `_exit_plan_mode_tool` slot in
  `ToolUseLoop` with a `_session_tools` list built from registry + allowed_tools
- Extend `AgentRegistry.register()` with `capabilities=` and `plugin_root=` params; `get()` and
  `render_catalog()` accept `session_capabilities` for gated visibility; add `visible_for()`
- Add `substitute_agent_body()` in `spawn_agent.py` for `${SESSION_ID}` /
  `${CLAUDE_PLUGIN_ROOT}` / bash-style `${VAR:-default}` expansion in agent bodies; registered
  agent types' model is now authoritative (ignores LLM-supplied model arg)
- Auto-scan `builtin_plugins/` at plugin discovery; propagate `plugin_root` and capability
  tuples through `Orchestrator` → `AgentRegistry` / `SkillRegistry` / `SessionToolRegistry`
- Parse `X-Meeseeks-Capabilities` request header in API backend; thread `session_capabilities`
  end-to-end through `Orchestrator` → `SpawnAgentTool` → `ToolUseLoop`
- Add `StliteWidgetPanel`, `CheckAgentsCard`, `SpawnAgentCard`, `FiveLeafBloomLoader`, and
  `WidgetCard` to the console; wire `widget_ready` event parsing and render inline stlite
  widgets in the conversation timeline
- Persist completed child handles in `AgentHypervisor` so `check_agents` surfaces results;
  add `list_visible()` helper; emit structured `check_agents` payload in tool card
- Fix: skip CWD root injection for non-registry tools; thread session_capabilities into
  slash-command skill lookup; reject path traversal in `widget_id`; scope `submit_widget`
  schema to widget-builder sessions only; force full PWA refresh on service-worker update
- Migrate docs screenshots to PNG; add Capabilities, Widgets, and core-orchestration docs
  pages; refresh plugins, skills, web-api, and landing pages

Author: bearlike

.github/workflows/docs.yml

@@ -29,7 +29,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install uv
-          uv sync --group docs --extra tools --extra ha
+          uv sync --group docs --extra ha
 
       - name: Verify mkdocstrings imports
         run: .venv/bin/python -c "import meeseeks_core.common; print(meeseeks_core.common.__name__)"

README.md

@@ -23,7 +23,7 @@ https://github.com/user-attachments/assets/78754e8f-828a-4c54-9e97-29cbeacbc3bc
 
 ## Overview
 
-Meeseeks is an AI assistant modeled as a conversation state machine. A top-level session binds an LLM to a filtered tool set via `bind_tools` and advances through a `submitted → running → terminal` lifecycle. Where parallelism is useful, the session issues `spawn_agent`; the hypervisor admits child sessions under a concurrency budget, constrains their tool scope, and resolves them into one of four terminal states — `completed`, `failed`, `cancelled`, or `rejected`. Transcripts are persisted per session, long histories are compacted, and summaries are retained across compactions.
+Meeseeks is an AI assistant modeled as a conversation state machine. A top-level session binds an LLM to a filtered tool set via `bind_tools` and advances through a `submitted → running → terminal` lifecycle. Where parallelism is useful, the session issues `spawn_agent`; the hypervisor admits child sessions under a concurrency budget, constrains their tool scope, and resolves them into one of four terminal states — `completed`, `failed`, `cancelled`, or `rejected`. Transcripts are persisted per session, long histories are compacted, and summaries are retained across compactions. The plugin and skill layers follow the Claude-ecosystem Agent Skills + Plugin standard, and the console renders interactive [stlite (Streamlit-in-WASM) widgets](docs/features-widgets.md) inline in the conversation timeline via the bundled `widget-builder` plugin.
 
 ### Meeseeks Console
 
@@ -35,8 +35,8 @@ The web console provides a task orchestration frontend backed by the REST API. I
         <th>Console landing page</th>
     </tr>
     <tr>
-        <td align="center"><img src="docs/meeseeks-console-02-tasks.jpg" alt="Meeseeks task detail page" height="360px"></td>
-        <td align="center"><img src="docs/meeseeks-console-01-front.jpg" alt="Meeseeks console landing page" height="360px"></td>
+        <td align="center"><img src="docs/meeseeks-console-02-tasks.png" alt="Meeseeks task detail page" height="360px"></td>
+        <td align="center"><img src="docs/meeseeks-console-01-front.png" alt="Meeseeks console landing page" height="360px"></td>
     </tr>
 </table>
 
@@ -59,6 +59,12 @@ The web console provides a task orchestration frontend backed by the REST API. I
         <td align="center"><img src="docs/meeseeks-console-05-plugins.jpg" alt="Plugins page with installed plugins and marketplace listings" height="300px"></td>
         <td align="center"><img src="docs/meeseeks-console-06-projects.jpg" alt="Projects page showing virtual workspaces shared across sessions" height="300px"></td>
     </tr>
+    <tr>
+        <th colspan="2">Widgets inline in chat</th>
+    </tr>
+    <tr>
+        <td colspan="2" align="center"><img src="docs/meeseeks-console-07-widgets.png" alt="Stock ticker and GitHub repo card widgets rendered inline in the Meeseeks Console" width="100%"></td>
+    </tr>
 </table>
 
 ## Features
@@ -80,9 +86,10 @@ The web console provides a task orchestration frontend backed by the REST API. I
 
 ### Tooling and integrations
 - (✅) **Tool registry:** Discovers local tools and MCP tools via persistent connection pool with automatic reconnection and config change detection.
-- (✅) **Skills:** Supports the [Agent Skills](https://agentskills.io) open standard. Place `SKILL.md` files in `~/.claude/skills/` or `.claude/skills/` to teach the assistant reusable workflows. Skills can be invoked via `/skill-name` slash commands or auto-activated by the LLM.
+- (✅) **Skills:** Supports the [Agent Skills](https://agentskills.io) open standard. Place `SKILL.md` files in `~/.claude/skills/` or `.claude/skills/` to teach the assistant reusable workflows. Skills can be invoked via `/skill-name` slash commands or auto-activated by the LLM. `requires-capabilities` frontmatter gates a skill to sessions that advertise the matching capability bundle.
 - (✅) **Configurable file editing:** Two built-in edit mechanisms — Aider-style SEARCH/REPLACE blocks and per-file structured patch (`file_path` / `old_string` / `new_string`). Select via `agent.edit_tool` in config, or let the system auto-select based on model identity. Different models perform better with different formats; the choice is transparent to the rest of the stack.
-- (✅) **Plugin system:** Discover, install, and manage plugins from configured marketplaces. Plugins can provide agent definitions, skills, hooks, and MCP tool integrations. Managed via the CLI (`/plugins`), console UI, or REST API.
+- (✅) **Plugin system:** Discover, install, and manage plugins from configured marketplaces, alongside a built-in plugin scan path for first-party bundles. Plugins can provide agent definitions, skills, hooks, MCP tool integrations, and per-agent stateful session tools via the `SessionTool` protocol. `requires-capabilities` frontmatter plus the `X-Meeseeks-Capabilities` request header gate capability bundles to compatible sessions, and `${CLAUDE_PLUGIN_ROOT}` substitution lets plugins reference their own assets by absolute path. Managed via the CLI (`/plugins`), console UI, or REST API.
+- (✅) **Interactive widgets:** Inline [stlite (Streamlit-in-WASM) widgets](docs/features-widgets.md) rendered in the conversation timeline via the bundled `widget-builder` plugin. A sub-agent writes a two-file widget (`app.py` + `data.json`), calls `submit_widget`, and the console mounts the result in a sandboxed Web Worker — no server round-trip, no CORS. Ships with a component library (GitHubRepoCard, SearchResultCard, StockTickerCard) and an AST import-allowlist lint that returns line-numbered feedback to the generating agent.
 - (✅) **Native LSP integration:** Opt-in code intelligence via `lsp_tool` (pygls/lsprotocol). Supports diagnostics, go-to-definition, find-references, and hover. Built-in servers: pyright (Python), typescript-language-server (TS/JS), gopls (Go), rust-analyzer (Rust) — auto-discovered on the PATH. Passive diagnostics inject automatically after file edits. Configure via `agent.lsp` in config.
 - (✅) **Web IDE:** Opt-in per-session code-server containers for browser-based editing, accessible from the console via "Open in Web IDE".
 - (✅) **Local file + shell tools:** Built-in tools for file reads, directory listing, and shell commands (approval-gated).

apps/meeseeks_api/src/meeseeks_api/backend.py

@@ -610,6 +610,16 @@ def post(self) -> tuple[dict, int]:
         if session_tag:
             runtime.session_store.tag_session(session_id, session_tag)
         context_payload = _build_context_payload(payload)
+        # Capability header — clients may declare supported features (e.g. "stlite"
+        # for the widget builder). Parse comma-separated values and persist in the
+        # session context so the Orchestrator can conditionally enable agent types.
+        capabilities_header = request.headers.get("X-Meeseeks-Capabilities", "")
+        if capabilities_header:
+            client_capabilities = [
+                c.strip() for c in capabilities_header.split(",") if c.strip()
+            ]
+            if client_capabilities:
+                context_payload["client_capabilities"] = client_capabilities
         # Include project in context if provided
         try:
             project_cwd = _resolve_project_cwd(payload)
@@ -652,6 +662,14 @@ def post(self, session_id: str) -> tuple[dict, int]:
             return {"message": "Session is already running."}, 409
 
         context_payload = _build_context_payload(request_data)
+        # Capability header — same parsing as Sessions.post() for per-query declarations.
+        capabilities_header = request.headers.get("X-Meeseeks-Capabilities", "")
+        if capabilities_header:
+            client_capabilities = [
+                c.strip() for c in capabilities_header.split(",") if c.strip()
+            ]
+            if client_capabilities:
+                context_payload["client_capabilities"] = client_capabilities
         # Use model from context if provided, else config default
         if "model" not in context_payload:
             context_payload["model"] = get_config_value("llm", "default_model", default="unknown")

apps/meeseeks_api/tests/test_capability_header.py

@@ -0,0 +1,93 @@
+"""Tests for X-Meeseeks-Capabilities header parsing in the API."""
+
+# mypy: ignore-errors
+from meeseeks_api import backend
+from meeseeks_core.session_store import SessionStore
+
+
+def _reset_backend(tmp_path, monkeypatch):
+    backend.session_store = SessionStore(root_dir=str(tmp_path))
+    backend.runtime = backend.SessionRuntime(session_store=backend.session_store)
+    backend.notification_store = backend.NotificationStore(root_dir=str(tmp_path))
+    backend.share_store = backend.ShareStore(root_dir=str(tmp_path))
+    backend.notification_service = backend.NotificationService(
+        backend.notification_store,
+        backend.runtime.session_store,
+    )
+
+
+def test_session_create_stores_client_capabilities(monkeypatch, tmp_path):
+    """X-Meeseeks-Capabilities header is parsed and persisted in context event."""
+    _reset_backend(tmp_path, monkeypatch)
+    client = backend.app.test_client()
+
+    resp = client.post(
+        "/api/sessions",
+        json={},
+        headers={
+            "X-API-KEY": backend.MASTER_API_TOKEN,
+            "X-Meeseeks-Capabilities": "stlite, foo",
+        },
+    )
+    assert resp.status_code == 200
+    session_id = resp.get_json()["session_id"]
+
+    events = backend.session_store.load_transcript(session_id)
+    ctx_events = [e for e in events if e.get("type") == "context"]
+    caps = next(
+        (
+            e["payload"].get("client_capabilities")
+            for e in ctx_events
+            if "client_capabilities" in e.get("payload", {})
+        ),
+        None,
+    )
+    assert caps == ["stlite", "foo"]
+
+
+def test_session_create_without_header_stores_no_capabilities(monkeypatch, tmp_path):
+    """Session creation without the capabilities header writes no client_capabilities."""
+    _reset_backend(tmp_path, monkeypatch)
+    client = backend.app.test_client()
+
+    resp = client.post(
+        "/api/sessions",
+        json={},
+        headers={"X-API-KEY": backend.MASTER_API_TOKEN},
+    )
+    assert resp.status_code == 200
+    session_id = resp.get_json()["session_id"]
+
+    events = backend.session_store.load_transcript(session_id)
+    ctx_events = [e for e in events if e.get("type") == "context"]
+    for e in ctx_events:
+        assert "client_capabilities" not in e.get("payload", {})
+
+
+def test_session_create_strips_whitespace_from_capabilities(monkeypatch, tmp_path):
+    """Whitespace around capability tokens is stripped during parsing."""
+    _reset_backend(tmp_path, monkeypatch)
+    client = backend.app.test_client()
+
+    resp = client.post(
+        "/api/sessions",
+        json={},
+        headers={
+            "X-API-KEY": backend.MASTER_API_TOKEN,
+            "X-Meeseeks-Capabilities": "  stlite  ,  other-feature  ",
+        },
+    )
+    assert resp.status_code == 200
+    session_id = resp.get_json()["session_id"]
+
+    events = backend.session_store.load_transcript(session_id)
+    ctx_events = [e for e in events if e.get("type") == "context"]
+    caps = next(
+        (
+            e["payload"].get("client_capabilities")
+            for e in ctx_events
+            if "client_capabilities" in e.get("payload", {})
+        ),
+        None,
+    )
+    assert caps == ["stlite", "other-feature"]