agent-webui 1.1.0__tar.gz → 2.2.0__tar.gz

{agent_webui-1.1.0/agent/agent_webui.egg-info → agent_webui-2.2.0}/PKG-INFO

@@ -1,37 +1,39 @@
 Metadata-Version: 2.4
 Name: agent-webui
-Version: 1.1.0
+Version: 2.2.0
 Summary: Agent Web Interface for Pydantic AI Agents
-Author-email: Audel Rouhi <knucklessg1@gmail.com>
+Author-email: Project Maintainers <maintainers@users.noreply.github.com>
 License: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Environment :: Console
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Requires-Python: <3.15,>=3.11
+Requires-Python: <3.15,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastapi>=0.117.1
-Requires-Dist: langfuse>=4.5.1
-Requires-Dist: pydantic-ai-slim[ui]<3.0.0,>=2.0.0
-Requires-Dist: sse-starlette>=3.4.1
-Requires-Dist: starlette>=1.0.0
-Requires-Dist: uvicorn>=0.46.0
-Requires-Dist: watchfiles>=1.1.0
-Requires-Dist: logfire[fastapi,starlette]
+Requires-Dist: fastapi>=0.139.2
+Requires-Dist: langfuse>=4.14.1
+Requires-Dist: pydantic-ai-slim[ui]>=2.14.1
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: sse-starlette>=3.4.6
+Requires-Dist: starlette>=1.3.1
+Requires-Dist: uvicorn>=0.51.0
+Requires-Dist: watchfiles>=1.2.0
+Requires-Dist: logfire[fastapi,starlette]>=4.38.0
+Requires-Dist: joserfc>=1.7.4
 Provides-Extra: test
-Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio; extra == "test"
-Requires-Dist: pytest-cov; extra == "test"
-Requires-Dist: pytest-env; extra == "test"
-Requires-Dist: pytest-timeout; extra == "test"
-Requires-Dist: networkx; extra == "test"
-Requires-Dist: opentelemetry-instrumentation-starlette; extra == "test"
-Requires-Dist: opentelemetry-instrumentation-fastapi; extra == "test"
-Requires-Dist: opentelemetry-instrumentation-asgi; extra == "test"
-Requires-Dist: agent-utilities[agent,graph]; extra == "test"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
+Requires-Dist: pytest>=9.1.1; extra == "test"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "test"
+Requires-Dist: pytest-cov>=7.1.0; extra == "test"
+Requires-Dist: pytest-env>=1.7.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.4.0; extra == "test"
+Requires-Dist: networkx>=3.6.1; extra == "test"
+Requires-Dist: opentelemetry-instrumentation-starlette>=0.65b0; extra == "test"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0; extra == "test"
+Requires-Dist: opentelemetry-instrumentation-asgi>=0.65b0; extra == "test"
+Requires-Dist: agent-utilities[agent-runtime,graph,metrics]>=2.0.0; extra == "test"
 Dynamic: license-file
 
 # Agent WebUI
@@ -56,7 +58,7 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/agent-webui)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/agent-webui)
 
-_Version: 1.0.0_
+_Version: 2.2.0_
 
 > **Documentation** — The architecture, graph-activity event model, feature surface,
 > and ecosystem integration of Agent WebUI are maintained in the
@@ -79,6 +81,7 @@ Agent WebUI is a highly interactive, responsive chat interface designed specific
 - [Installation](#installation)
 - [Usage](#usage)
 - [Development](#development)
+- [Build & Deploy](#build--deploy)
 - [Detailed Documentation](#detailed-documentation)
 - [Documentation](#documentation)
 - [License](#license)
@@ -109,7 +112,7 @@ Agent WebUI is a highly interactive, responsive chat interface designed specific
   - Zoom/pan controls and PNG export
   - Node type filtering and detailed node inspection
   - Real-time graph statistics and relationship explorer
-- **Code Graph Navigator** (`CodeGraphView.tsx`, CONCEPT:KG-2.9g) -- navigate the
+- **Code Graph Navigator** (`CodeGraphView.tsx`, CONCEPT:AU-KG.backend.declared-columns-so-schema) -- navigate the
   resolved code-symbol graph built from your indexed GitLab instances: find a
   symbol's **definition**, its **references** (callers), trace the transitive
   **call graph**, or compute the **impact** (blast radius) of a change — scoped to
@@ -119,7 +122,7 @@ Agent WebUI is a highly interactive, responsive chat interface designed specific
 
 ### Knowledge Management
 - **Knowledge Base Management** -- comprehensive KB system with:
-  - Document ingestion from multiple sources (PDF, DOCX, EPUB, Markdown, URLs)
+  - Document ingestion from workspace-confined sources; remote URLs require a governed ingestion connector
   - Article CRUD with concept extraction and fact indexing
   - Health check monitoring with contradiction detection
   - Hybrid search across knowledge bases
@@ -163,7 +166,7 @@ Defined in `agent/agent_webui/api_extensions.py`:
 | `GET /ontology/object/{object_id}` | Full object view: properties, links, derived, markings, history, layout |
 | `POST /ontology/object/{object_id}/edit` | Record a durable edit (property_set / link_add / link_remove) |
 | `POST /ontology/object/{object_id}/revert` | Revert an edit via a compensating edit |
-| `POST /ontology/function/invoke` | Invoke a typed, versioned ontology function (audited runtime, KG-2.41) |
+| `POST /ontology/function/invoke` | Invoke a typed, versioned ontology function (audited runtime, AU-KG.ontology.default-runtime-bound-import) |
 | `POST /ontology/derive` | Compute a single derived property for an object (KG-2.40) |
 | `POST /ontology/document/process` | Process a document into Document + Chunk objects (KG-2.48) |
 | `GET /ontology/object-view/{object_type}` | Get a type's ObjectView: stored (configured) else standard (schema) |
@@ -174,7 +177,7 @@ Defined in `agent/agent_webui/api_extensions.py`:
 - **5-Domain Navigation Layout**:
   - **DevOps & Workspace**: Workspace Matrix code status, branch operations, and git pulling.
   - **Brain & Knowledge**: Visual SVG graph nodes, Cypher console, scientific literature papers explorer, and Prompts visual configurator.
-  - **Infrastructure Hub**: SSH tunnels drawer, remote terminal commands, CPU/RAM/Disk dials, active process trees, and Docker registry boards.
+  - **Infrastructure Hub**: governed SSH/container inventory, CPU/RAM/Disk dials, opaque process utilization, and delegated infrastructure actions.
   - **Lifestyle & Automation**: SmartHome device dimmers, Calendar tasks, qBittorrent torrent speedometers, and MealieScaled grocery trackers.
   - **System Config**: Scheduled crons timeline and Global settings configurator forms.
 
@@ -232,6 +235,31 @@ The WebUI backend (`agent/agent_webui/server.py`) integrates with a **Centralize
 
 All communication is fully traceable, logging session parameters, agent identities, and provenance for complete ecosystem visibility.
 
+### MCP client & MCP Apps host
+
+The browser never opens an MCP connection itself. graph-os rejects any request whose `Host`
+authority is outside `MCP_ALLOWED_HOSTS` (which a browser cannot set) and authenticates children
+with a service bearer no page may hold, so `src/lib/mcp-client.ts` calls the WebUI's own backend
+same-origin instead:
+
+| Route | Purpose |
+|-------|---------|
+| `POST /api/enhanced/mcp/tools/call` | one MCP `tools/call` through the governed delegation seam |
+| `POST /api/enhanced/mcp/apps/resource` | one MCP `resources/read` for a `ui://` MCP App |
+
+Both require `kg:admin` (invoking an arbitrary fleet tool is an admin mutation), and both delegate to
+the host-injected `call_mcp_tool` / `read_mcp_resource` workspace helpers — supplied by
+`agent_utilities.server.webui_mcp_delegation` — which own the allow-list, credentials and audit
+envelope. With no host injection they answer `501` rather than building a client of their own.
+
+`McpAppHost` (`src/components/mcp/McpAppHost.tsx`) fetches a `ui://` app's HTML and renders it in
+`McpAppFrame`. **Tool-returned HTML is untrusted**: the frame is `sandbox="allow-scripts"` with no
+`allow-same-origin` (so the app can never read this origin's document, cookies, storage, or issue a
+credentialed request of its own), gets a `no-referrer` policy, and carries a CSP built by
+intersecting the server-declared `_meta.ui.csp` against the host's own `allowedDomains` ceiling. Its
+tool-call channel is host-mediated `postMessage` only, gated by an `allowedTools` allow-list that
+`McpAppHost` requires explicitly — there is no permissive default.
+
 ### Unified Discovery Architecture
 
 ```mermaid
@@ -330,6 +358,61 @@ pnpm run dev
 
 Navigate to `http://localhost:5173` to interact with the agent.
 
+### Served security boundary
+
+The backend defaults to a loopback-only development boundary. A non-loopback
+listener fails closed unless JWT verification has a JWKS URI, issuer, and
+audience, and an explicit `ALLOWED_HOSTS` allowlist is configured. Browser
+origins are exact `http`/`https` origins; wildcard origins are rejected.
+
+All authenticated routes enforce `kg:read`, `kg:write`, or `kg:admin` from the
+server-minted graph session. State-changing tool and skill configuration
+requires `kg:admin`; the enhanced raw graph, code, KB, agent, and supervisory
+dashboard surfaces are admin-only. API responses are non-cacheable, WebSocket messages and
+HTTP request bodies are bounded, and remote KB URLs are not fetched directly
+by the WebUI. Route remote ingestion through a host connector that enforces its
+own URL, DNS, redirect, credential, timeout, and response-size policy.
+
+Startup also requires a callable
+`agent_utilities.security.request_identity.mint_graph_session`; the server will
+not fall back to an unscoped identity. Synchronous graph/backend adapters share
+a fixed four-worker, eight-slot budget. A request deadline does not release a
+slot while an underlying Python call is still running, so repeated timeouts
+cannot create unbounded threads or queued work. Saturated and timed-out calls
+return `503`; each worker receives the server-minted request identity context.
+A backend that can hang indefinitely must additionally enforce a
+native operation/socket timeout: its charged slot intentionally remains
+unavailable until that backend call exits.
+
+The browser policy defaults to `default-src 'none'`, self-hosted scripts and
+styles, no script attributes, no frames, and exact source lists. The only
+built-in exceptions are inline React **style attributes** and local
+`data:`/`blob:` image sources; the security doctor reports
+these explicitly. External previews are disabled until their exact origins are
+listed in `AGENT_WEBUI_CSP_FRAME_SOURCES`. Other exact-origin additions use the
+corresponding `AGENT_WEBUI_CSP_*_SOURCES` variables below. Wildcards, paths,
+credentials, and directive injection are rejected. Custom `html_source`
+rendering fails startup unless `AGENT_WEBUI_CSP_CUSTOM_RENDERING=1`; inline
+script/style keywords must then be separately and explicitly configured.
+
+The bundled CLI disables Uvicorn access logging because raw query strings can
+contain searches, graph symbols, or other sensitive text. A non-loopback app
+factory deployment must set `AGENT_WEBUI_ACCESS_LOG_POLICY=disabled` or
+`redacted`. `redacted` is an operator attestation, not a logger implementation:
+the embedding ASGI server or proxy must remove raw query strings and credentials
+before writing access records. Check the active contract with
+`python -m agent_webui.server --security-doctor` or the admin-only
+`GET /api/enhanced/security/doctor` endpoint. The latter also exposes bounded
+sync-work utilization and reports `degraded` while timed-out work still occupies
+capacity.
+
+The bundled browser client does not store bearer credentials and the native
+WebSocket API cannot attach an `Authorization` header. A remote deployment
+therefore needs an authentication-aware same-origin proxy that injects the
+verified upstream identity for page, API, and WebSocket requests. Configured
+allowed origins authorize request origins; they do not enable CORS response
+headers for a separately hosted frontend.
+
 ## Development
 
 ```sh
@@ -354,9 +437,104 @@ pytest agent/agent_webui/__tests__/ --cov        # With coverage
 
 ### Environment Variables
 
-| Variable          | Default | Description                                 |
-| ----------------- | ------- | ------------------------------------------- |
+| Variable | Default | Description |
+| --- | --- | --- |
 | `VITE_ENABLE_ACP` | `false` | Enable ACP protocol support alongside AG-UI |
+| `PERSISTENCE_IDENTITY_HMAC_KEY_REF` | — | Runtime secret reference used for stable, opaque durable identities |
+| `AGENT_WEBUI_ACCESS_LOG_POLICY` | loopback-only | Required as `disabled` or `redacted` for a non-loopback listener |
+| `AGENT_WEBUI_CSP_CUSTOM_RENDERING` | `false` | Explicitly acknowledge use of a custom `html_source` |
+| `AGENT_WEBUI_CSP_SCRIPT_SOURCES` | — | Extra exact script origins or CSP hashes; unsafe keywords also require the custom-rendering acknowledgement |
+| `AGENT_WEBUI_CSP_STYLE_SOURCES` | — | Extra exact style origins or CSP hashes, applied to both the fallback and element directives |
+| `AGENT_WEBUI_CSP_IMAGE_SOURCES` | — | Extra exact image origins |
+| `AGENT_WEBUI_CSP_FONT_SOURCES` | — | Extra exact font origins |
+| `AGENT_WEBUI_CSP_CONNECT_SOURCES` | — | Extra exact HTTP(S) or WebSocket API origins |
+| `AGENT_WEBUI_CSP_MEDIA_SOURCES` | — | Extra exact media origins |
+| `AGENT_WEBUI_CSP_WORKER_SOURCES` | — | Extra exact worker origins |
+| `AGENT_WEBUI_CSP_FRAME_SOURCES` | — | Exact origins allowed in the Web Preview iframe; frames are denied when unset |
+
+## Build & Deploy
+
+There is **one** way to build and ship this app's container image, and **one** way
+to deploy it. Both are scripts, not manual steps, precisely because manual/ad-hoc
+builds shipped stale code to production three separate ways in one day
+(2026-08-07) before this section existed:
+
+1. A digest-pinned Deployment + `imagePullPolicy: Always` looks safe, but the
+   pull policy is irrelevant under a digest pin -- `kubectl rollout restart`
+   re-pulls the identical bits forever. Deploying a NEW image always requires
+   `kubectl set image deploy/agent-webui agent-webui=<image>@sha256:<new-digest>`.
+2. `uv pip install agent-utilities[...]` can silently resolve from stale PyPI
+   instead of a locally built wheel -- PyPI's newest `agent-utilities` doesn't
+   have modules this app imports at startup, and the mismatch only surfaces as a
+   `ModuleNotFoundError` crash-loop in production, not at build time.
+3. The served frontend `dist/` can go stale **independently of the backend**.
+   apps/agent-webui's k8s Deployment NFS-mounts this repo's `agent/` directory
+   at `/webui-src` ahead of site-packages (so a Python edit + pod restart goes
+   live with no image rebuild) -- but that mount also shadows
+   `Path(__file__).parent / 'dist'`, so the served frontend bundle is whatever
+   `pnpm build` last produced on the **canonical checkout's disk**, independent
+   of which Docker image is running. Rolling the Deployment alone does not ship
+   a frontend change.
+
+### Local build + deploy (one command)
+
+```sh
+docker/deploy.sh
+```
+
+Builds the image on the r820 buildhost (always -- see the script's header for
+why, and why it never silently falls back to whatever daemon happens to be
+local), verifies the served bundle carries today's commit **before** pushing
+anything, pushes to Docker Hub by digest, deploys by that digest, waits out a
+60-second availability soak before Kubernetes will retire the old pod
+(`minReadySeconds: 60` on the Deployment), verifies the running pod's `imageID`
+actually changed, rebuilds the live-mounted frontend bundle on the canonical
+checkout, and verifies (via `kubectl exec`, not an HTTP guess) that the live pod
+is actually serving it. It prints the rollback digest **first**, before doing
+anything else, and again at the end alongside the exact rollback command.
+
+```sh
+docker/deploy.sh --build-only    # local build + verify only; no push, no deploy
+docker/deploy.sh --skip-deploy   # build + verify + push; does NOT touch the cluster
+```
+
+`docker/build_and_push.sh` (called internally by `deploy.sh`) is the build-only
+half, kept as its own file for a standalone build-only smoke test. Do not
+hand-roll a `docker build`/`kubectl set image` sequence outside these two
+scripts -- see their headers for the full contract, including every env var
+override (`AU_SRC_PATH`, `WHEELHOUSE_PATH`, `CANONICAL_CHECKOUT`, etc.).
+
+#### Coordinating concurrent deploys
+
+Only one apps/agent-webui Deployment exists. If another lane/session is
+actively deploying to it, use `docker/deploy.sh --skip-deploy` to build and
+push without touching the cluster, coordinate an order (message the other
+lane), and run a bare `docker/deploy.sh` (or `kubectl set image` with the
+digest `--skip-deploy` just printed) once it's clear.
+
+### Production image (GitHub CI)
+
+Pushing a `v*` tag (or a manual `workflow_dispatch`) runs
+`.github/workflows/docker-publish.yml`, which builds and publishes
+`knucklessg1/agent-webui` from the same `docker/Dockerfile` -- no second,
+divergent CI-only build definition. It builds `epistemic-graph` from source on
+a GitHub-hosted runner (no self-hosted runner is registered for this org today,
+and PyPI's `epistemic-graph` is still behind agent-utilities' floor), checks
+out `agent-utilities` from source as the `au-src` build-context (never PyPI,
+same rule as the local script), and runs the identical served-bundle
+verification before the job is considered successful. See that workflow file's
+header comments for why it can't simply call the fleet's shared
+`container_pipeline.yml` reusable workflow (that workflow's interface has no
+way to pass this Dockerfile's extra build-contexts).
+
+### k8s manifest
+
+`inventory/k8s-migration/cutover/apptier/agent-webui.yaml` (in the `inventory`
+repo) describes the Deployment's shape (env, mounts, probes, `minReadySeconds`).
+Its `image:` field is a point-in-time snapshot, **not** the source of truth --
+re-applying that file does not update the running image, and hand-editing that
+field back to a mutable tag would reopen trap #1 above. See the file's own
+header warning for the full reasoning.
 
 ## Documentation
 

agent_webui-1.1.0/PKG-INFO → agent_webui-2.2.0/README.md

@@ -1,39 +1,3 @@
-Metadata-Version: 2.4
-Name: agent-webui
-Version: 1.1.0
-Summary: Agent Web Interface for Pydantic AI Agents
-Author-email: Audel Rouhi <knucklessg1@gmail.com>
-License: MIT
-Classifier: Development Status :: 4 - Beta
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Environment :: Console
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Requires-Python: <3.15,>=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: fastapi>=0.117.1
-Requires-Dist: langfuse>=4.5.1
-Requires-Dist: pydantic-ai-slim[ui]<3.0.0,>=2.0.0
-Requires-Dist: sse-starlette>=3.4.1
-Requires-Dist: starlette>=1.0.0
-Requires-Dist: uvicorn>=0.46.0
-Requires-Dist: watchfiles>=1.1.0
-Requires-Dist: logfire[fastapi,starlette]
-Provides-Extra: test
-Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio; extra == "test"
-Requires-Dist: pytest-cov; extra == "test"
-Requires-Dist: pytest-env; extra == "test"
-Requires-Dist: pytest-timeout; extra == "test"
-Requires-Dist: networkx; extra == "test"
-Requires-Dist: opentelemetry-instrumentation-starlette; extra == "test"
-Requires-Dist: opentelemetry-instrumentation-fastapi; extra == "test"
-Requires-Dist: opentelemetry-instrumentation-asgi; extra == "test"
-Requires-Dist: agent-utilities[agent,graph]; extra == "test"
-Dynamic: license-file
-
 # Agent WebUI
 
 ![PyPI - Version](https://img.shields.io/pypi/v/agent-webui)
@@ -56,7 +20,7 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/agent-webui)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/agent-webui)
 
-_Version: 1.0.0_
+_Version: 2.2.0_
 
 > **Documentation** — The architecture, graph-activity event model, feature surface,
 > and ecosystem integration of Agent WebUI are maintained in the
@@ -79,6 +43,7 @@ Agent WebUI is a highly interactive, responsive chat interface designed specific
 - [Installation](#installation)
 - [Usage](#usage)
 - [Development](#development)
+- [Build & Deploy](#build--deploy)
 - [Detailed Documentation](#detailed-documentation)
 - [Documentation](#documentation)
 - [License](#license)
@@ -109,7 +74,7 @@ Agent WebUI is a highly interactive, responsive chat interface designed specific
   - Zoom/pan controls and PNG export
   - Node type filtering and detailed node inspection
   - Real-time graph statistics and relationship explorer
-- **Code Graph Navigator** (`CodeGraphView.tsx`, CONCEPT:KG-2.9g) -- navigate the
+- **Code Graph Navigator** (`CodeGraphView.tsx`, CONCEPT:AU-KG.backend.declared-columns-so-schema) -- navigate the
   resolved code-symbol graph built from your indexed GitLab instances: find a
   symbol's **definition**, its **references** (callers), trace the transitive
   **call graph**, or compute the **impact** (blast radius) of a change — scoped to
@@ -119,7 +84,7 @@ Agent WebUI is a highly interactive, responsive chat interface designed specific
 
 ### Knowledge Management
 - **Knowledge Base Management** -- comprehensive KB system with:
-  - Document ingestion from multiple sources (PDF, DOCX, EPUB, Markdown, URLs)
+  - Document ingestion from workspace-confined sources; remote URLs require a governed ingestion connector
   - Article CRUD with concept extraction and fact indexing
   - Health check monitoring with contradiction detection
   - Hybrid search across knowledge bases
@@ -163,7 +128,7 @@ Defined in `agent/agent_webui/api_extensions.py`:
 | `GET /ontology/object/{object_id}` | Full object view: properties, links, derived, markings, history, layout |
 | `POST /ontology/object/{object_id}/edit` | Record a durable edit (property_set / link_add / link_remove) |
 | `POST /ontology/object/{object_id}/revert` | Revert an edit via a compensating edit |
-| `POST /ontology/function/invoke` | Invoke a typed, versioned ontology function (audited runtime, KG-2.41) |
+| `POST /ontology/function/invoke` | Invoke a typed, versioned ontology function (audited runtime, AU-KG.ontology.default-runtime-bound-import) |
 | `POST /ontology/derive` | Compute a single derived property for an object (KG-2.40) |
 | `POST /ontology/document/process` | Process a document into Document + Chunk objects (KG-2.48) |
 | `GET /ontology/object-view/{object_type}` | Get a type's ObjectView: stored (configured) else standard (schema) |
@@ -174,7 +139,7 @@ Defined in `agent/agent_webui/api_extensions.py`:
 - **5-Domain Navigation Layout**:
   - **DevOps & Workspace**: Workspace Matrix code status, branch operations, and git pulling.
   - **Brain & Knowledge**: Visual SVG graph nodes, Cypher console, scientific literature papers explorer, and Prompts visual configurator.
-  - **Infrastructure Hub**: SSH tunnels drawer, remote terminal commands, CPU/RAM/Disk dials, active process trees, and Docker registry boards.
+  - **Infrastructure Hub**: governed SSH/container inventory, CPU/RAM/Disk dials, opaque process utilization, and delegated infrastructure actions.
   - **Lifestyle & Automation**: SmartHome device dimmers, Calendar tasks, qBittorrent torrent speedometers, and MealieScaled grocery trackers.
   - **System Config**: Scheduled crons timeline and Global settings configurator forms.
 
@@ -232,6 +197,31 @@ The WebUI backend (`agent/agent_webui/server.py`) integrates with a **Centralize
 
 All communication is fully traceable, logging session parameters, agent identities, and provenance for complete ecosystem visibility.
 
+### MCP client & MCP Apps host
+
+The browser never opens an MCP connection itself. graph-os rejects any request whose `Host`
+authority is outside `MCP_ALLOWED_HOSTS` (which a browser cannot set) and authenticates children
+with a service bearer no page may hold, so `src/lib/mcp-client.ts` calls the WebUI's own backend
+same-origin instead:
+
+| Route | Purpose |
+|-------|---------|
+| `POST /api/enhanced/mcp/tools/call` | one MCP `tools/call` through the governed delegation seam |
+| `POST /api/enhanced/mcp/apps/resource` | one MCP `resources/read` for a `ui://` MCP App |
+
+Both require `kg:admin` (invoking an arbitrary fleet tool is an admin mutation), and both delegate to
+the host-injected `call_mcp_tool` / `read_mcp_resource` workspace helpers — supplied by
+`agent_utilities.server.webui_mcp_delegation` — which own the allow-list, credentials and audit
+envelope. With no host injection they answer `501` rather than building a client of their own.
+
+`McpAppHost` (`src/components/mcp/McpAppHost.tsx`) fetches a `ui://` app's HTML and renders it in
+`McpAppFrame`. **Tool-returned HTML is untrusted**: the frame is `sandbox="allow-scripts"` with no
+`allow-same-origin` (so the app can never read this origin's document, cookies, storage, or issue a
+credentialed request of its own), gets a `no-referrer` policy, and carries a CSP built by
+intersecting the server-declared `_meta.ui.csp` against the host's own `allowedDomains` ceiling. Its
+tool-call channel is host-mediated `postMessage` only, gated by an `allowedTools` allow-list that
+`McpAppHost` requires explicitly — there is no permissive default.
+
 ### Unified Discovery Architecture
 
 ```mermaid
@@ -330,6 +320,61 @@ pnpm run dev
 
 Navigate to `http://localhost:5173` to interact with the agent.
 
+### Served security boundary
+
+The backend defaults to a loopback-only development boundary. A non-loopback
+listener fails closed unless JWT verification has a JWKS URI, issuer, and
+audience, and an explicit `ALLOWED_HOSTS` allowlist is configured. Browser
+origins are exact `http`/`https` origins; wildcard origins are rejected.
+
+All authenticated routes enforce `kg:read`, `kg:write`, or `kg:admin` from the
+server-minted graph session. State-changing tool and skill configuration
+requires `kg:admin`; the enhanced raw graph, code, KB, agent, and supervisory
+dashboard surfaces are admin-only. API responses are non-cacheable, WebSocket messages and
+HTTP request bodies are bounded, and remote KB URLs are not fetched directly
+by the WebUI. Route remote ingestion through a host connector that enforces its
+own URL, DNS, redirect, credential, timeout, and response-size policy.
+
+Startup also requires a callable
+`agent_utilities.security.request_identity.mint_graph_session`; the server will
+not fall back to an unscoped identity. Synchronous graph/backend adapters share
+a fixed four-worker, eight-slot budget. A request deadline does not release a
+slot while an underlying Python call is still running, so repeated timeouts
+cannot create unbounded threads or queued work. Saturated and timed-out calls
+return `503`; each worker receives the server-minted request identity context.
+A backend that can hang indefinitely must additionally enforce a
+native operation/socket timeout: its charged slot intentionally remains
+unavailable until that backend call exits.
+
+The browser policy defaults to `default-src 'none'`, self-hosted scripts and
+styles, no script attributes, no frames, and exact source lists. The only
+built-in exceptions are inline React **style attributes** and local
+`data:`/`blob:` image sources; the security doctor reports
+these explicitly. External previews are disabled until their exact origins are
+listed in `AGENT_WEBUI_CSP_FRAME_SOURCES`. Other exact-origin additions use the
+corresponding `AGENT_WEBUI_CSP_*_SOURCES` variables below. Wildcards, paths,
+credentials, and directive injection are rejected. Custom `html_source`
+rendering fails startup unless `AGENT_WEBUI_CSP_CUSTOM_RENDERING=1`; inline
+script/style keywords must then be separately and explicitly configured.
+
+The bundled CLI disables Uvicorn access logging because raw query strings can
+contain searches, graph symbols, or other sensitive text. A non-loopback app
+factory deployment must set `AGENT_WEBUI_ACCESS_LOG_POLICY=disabled` or
+`redacted`. `redacted` is an operator attestation, not a logger implementation:
+the embedding ASGI server or proxy must remove raw query strings and credentials
+before writing access records. Check the active contract with
+`python -m agent_webui.server --security-doctor` or the admin-only
+`GET /api/enhanced/security/doctor` endpoint. The latter also exposes bounded
+sync-work utilization and reports `degraded` while timed-out work still occupies
+capacity.
+
+The bundled browser client does not store bearer credentials and the native
+WebSocket API cannot attach an `Authorization` header. A remote deployment
+therefore needs an authentication-aware same-origin proxy that injects the
+verified upstream identity for page, API, and WebSocket requests. Configured
+allowed origins authorize request origins; they do not enable CORS response
+headers for a separately hosted frontend.
+
 ## Development
 
 ```sh
@@ -354,9 +399,104 @@ pytest agent/agent_webui/__tests__/ --cov        # With coverage
 
 ### Environment Variables
 
-| Variable          | Default | Description                                 |
-| ----------------- | ------- | ------------------------------------------- |
+| Variable | Default | Description |
+| --- | --- | --- |
 | `VITE_ENABLE_ACP` | `false` | Enable ACP protocol support alongside AG-UI |
+| `PERSISTENCE_IDENTITY_HMAC_KEY_REF` | — | Runtime secret reference used for stable, opaque durable identities |
+| `AGENT_WEBUI_ACCESS_LOG_POLICY` | loopback-only | Required as `disabled` or `redacted` for a non-loopback listener |
+| `AGENT_WEBUI_CSP_CUSTOM_RENDERING` | `false` | Explicitly acknowledge use of a custom `html_source` |
+| `AGENT_WEBUI_CSP_SCRIPT_SOURCES` | — | Extra exact script origins or CSP hashes; unsafe keywords also require the custom-rendering acknowledgement |
+| `AGENT_WEBUI_CSP_STYLE_SOURCES` | — | Extra exact style origins or CSP hashes, applied to both the fallback and element directives |
+| `AGENT_WEBUI_CSP_IMAGE_SOURCES` | — | Extra exact image origins |
+| `AGENT_WEBUI_CSP_FONT_SOURCES` | — | Extra exact font origins |
+| `AGENT_WEBUI_CSP_CONNECT_SOURCES` | — | Extra exact HTTP(S) or WebSocket API origins |
+| `AGENT_WEBUI_CSP_MEDIA_SOURCES` | — | Extra exact media origins |
+| `AGENT_WEBUI_CSP_WORKER_SOURCES` | — | Extra exact worker origins |
+| `AGENT_WEBUI_CSP_FRAME_SOURCES` | — | Exact origins allowed in the Web Preview iframe; frames are denied when unset |
+
+## Build & Deploy
+
+There is **one** way to build and ship this app's container image, and **one** way
+to deploy it. Both are scripts, not manual steps, precisely because manual/ad-hoc
+builds shipped stale code to production three separate ways in one day
+(2026-08-07) before this section existed:
+
+1. A digest-pinned Deployment + `imagePullPolicy: Always` looks safe, but the
+   pull policy is irrelevant under a digest pin -- `kubectl rollout restart`
+   re-pulls the identical bits forever. Deploying a NEW image always requires
+   `kubectl set image deploy/agent-webui agent-webui=<image>@sha256:<new-digest>`.
+2. `uv pip install agent-utilities[...]` can silently resolve from stale PyPI
+   instead of a locally built wheel -- PyPI's newest `agent-utilities` doesn't
+   have modules this app imports at startup, and the mismatch only surfaces as a
+   `ModuleNotFoundError` crash-loop in production, not at build time.
+3. The served frontend `dist/` can go stale **independently of the backend**.
+   apps/agent-webui's k8s Deployment NFS-mounts this repo's `agent/` directory
+   at `/webui-src` ahead of site-packages (so a Python edit + pod restart goes
+   live with no image rebuild) -- but that mount also shadows
+   `Path(__file__).parent / 'dist'`, so the served frontend bundle is whatever
+   `pnpm build` last produced on the **canonical checkout's disk**, independent
+   of which Docker image is running. Rolling the Deployment alone does not ship
+   a frontend change.
+
+### Local build + deploy (one command)
+
+```sh
+docker/deploy.sh
+```
+
+Builds the image on the r820 buildhost (always -- see the script's header for
+why, and why it never silently falls back to whatever daemon happens to be
+local), verifies the served bundle carries today's commit **before** pushing
+anything, pushes to Docker Hub by digest, deploys by that digest, waits out a
+60-second availability soak before Kubernetes will retire the old pod
+(`minReadySeconds: 60` on the Deployment), verifies the running pod's `imageID`
+actually changed, rebuilds the live-mounted frontend bundle on the canonical
+checkout, and verifies (via `kubectl exec`, not an HTTP guess) that the live pod
+is actually serving it. It prints the rollback digest **first**, before doing
+anything else, and again at the end alongside the exact rollback command.
+
+```sh
+docker/deploy.sh --build-only    # local build + verify only; no push, no deploy
+docker/deploy.sh --skip-deploy   # build + verify + push; does NOT touch the cluster
+```
+
+`docker/build_and_push.sh` (called internally by `deploy.sh`) is the build-only
+half, kept as its own file for a standalone build-only smoke test. Do not
+hand-roll a `docker build`/`kubectl set image` sequence outside these two
+scripts -- see their headers for the full contract, including every env var
+override (`AU_SRC_PATH`, `WHEELHOUSE_PATH`, `CANONICAL_CHECKOUT`, etc.).
+
+#### Coordinating concurrent deploys
+
+Only one apps/agent-webui Deployment exists. If another lane/session is
+actively deploying to it, use `docker/deploy.sh --skip-deploy` to build and
+push without touching the cluster, coordinate an order (message the other
+lane), and run a bare `docker/deploy.sh` (or `kubectl set image` with the
+digest `--skip-deploy` just printed) once it's clear.
+
+### Production image (GitHub CI)
+
+Pushing a `v*` tag (or a manual `workflow_dispatch`) runs
+`.github/workflows/docker-publish.yml`, which builds and publishes
+`knucklessg1/agent-webui` from the same `docker/Dockerfile` -- no second,
+divergent CI-only build definition. It builds `epistemic-graph` from source on
+a GitHub-hosted runner (no self-hosted runner is registered for this org today,
+and PyPI's `epistemic-graph` is still behind agent-utilities' floor), checks
+out `agent-utilities` from source as the `au-src` build-context (never PyPI,
+same rule as the local script), and runs the identical served-bundle
+verification before the job is considered successful. See that workflow file's
+header comments for why it can't simply call the fleet's shared
+`container_pipeline.yml` reusable workflow (that workflow's interface has no
+way to pass this Dockerfile's extra build-contexts).
+
+### k8s manifest
+
+`inventory/k8s-migration/cutover/apptier/agent-webui.yaml` (in the `inventory`
+repo) describes the Deployment's shape (env, mounts, probes, `minReadySeconds`).
+Its `image:` field is a point-in-time snapshot, **not** the source of truth --
+re-applying that file does not update the running image, and hand-editing that
+field back to a mutable tag would reopen trap #1 above. See the file's own
+header warning for the full reasoning.
 
 ## Documentation