Web modules and UI
Understand where Buffaly pages, module workbenches, generated JsonWs clients, static assets, wiki content, and UI-backed workflows live.
Use web modules when Buffaly needs a visual surface, local runner, OAuth flow, account configuration screen, or user-facing verification experience. Keep background-only capabilities as services, skills, or tools unless a page helps the user make a safer decision.
Quick answer
A Buffaly web module is a web-host extension boundary. The shared IBuffalyWebModule contract gives each module a name, a runtime Configure(contentRootPath, webRootPath) hook, an install-artifact hook, and a MapRoutes(WebApplication app) hook.
What a web module packages
Routes, browser pages, static assets, generated JsonWs client files, and sometimes related skill or service surfaces.
What it is not
It is not automatically a tool, action, skill, or service. The module owns web startup and UI assets; the agent calls tools and actions.
| Concept | Role |
|---|---|
| Web module | Packages and starts web/UI surfaces in the Buffaly web host. |
| Service | Owns lifecycle, identity, state, configuration, and related methods. |
| Tool or action | Provides the flat callable interface the Buffaly agent can invoke. |
| Skill | Groups related actions so Buffaly can discover and load them. |
Do not assume a module is usable just because source exists. Check the installed module manifest, running web host routes, generated JsonWs artifacts, static assets, and related configuration.
What users see in the web host
The checked-in web host registers several user-visible surfaces directly. Common examples include the main agent UI, settings, meta tools, messages, voice test, worker manager, Codex replay viewer, about page, and ProtoScript page.
/ redirects toward /buffaly-agent.html/buffaly-agent-settings opens settings/worker-manager opens worker management/protoscript opens the ProtoScript pageLocal content and diagnostics routes
/api/local-file-imagepreviews referenced local images./markdown-viewersupports local markdown viewing./api/local-text-fileserves local text references./api/diagnostics/web-modulesreports read-only module and JsonWs diagnostics.
How web modules are loaded
The host builds external web modules from the installed web-module manifest under the runtime install root:
BuffalyWebHost resolves that root from RuntimeFeature.Feature.InstallRootPath, reads manifest registrations, skips disabled entries, loads each configured assembly and type, calls Configure, and later calls each module's MapRoutes. Load failures are logged while the host continues with remaining modules.
| Evidence level | What it proves | Operator check |
|---|---|---|
| Source-present | The capability exists in source. | Find the module project, static file, or source folder. |
| Manifest-enabled | The install root declares the module as enabled. | Inspect WebModules.json for name, assembly path, type name, and page paths. |
| Runtime-loaded | The running host instantiated and configured the module. | Check /api/diagnostics/web-modules for loaded names and JsonWs root status. |
IsWebModuleFeatureEnabled appears in source, but the inspected guard around it is commented out. Use startup flow, manifest evidence, and diagnostics instead of that constant alone.Configuration and location concepts
Content root and web root
The module contract receives both host paths. Modules use them to configure services, locate generated artifacts, and serve or copy web assets.
Installed module root
<installRoot>\lib\web-modules owns installed assemblies, dependencies, generated files, assets, and WebModules.json.
Generated JsonWs artifacts
Generated contract files and browser client stubs live under host wwwroot\JsonWs so UI code can call backend JsonWs services.
Static web assets
Module-owned static files should live under wwwroot\web-modules\<ModuleName>, not arbitrary root-level folders.
Install time is not startup
Installation copies assemblies, dependencies, generated JsonWs files, static web files, ProtoScript skills, and manifest data. Startup reads WebModules.json, loads enabled assemblies, configures modules, and maps routes. Restarting the host does not necessarily recreate missing files or repair an incomplete install.
Module areas
Do not treat a short product table as the inventory. Packaged Buffaly installs can load many web modules; a given deployment only has the modules that are installed, enabled, and successfully mapped. Check /installed-modules.html and /api/diagnostics/web-modules on the running host. The Buffaly wiki ships matching operator articles under Wiki/modules/.
| Module or area | Purpose | Observed routes or paths |
|---|---|---|
| Core UI | ||
| Wiki | Checked-in Buffaly documentation surface. | /wiki |
| Sessions | Session list, messages, dashboard, usage, and process views. | /web-modules/Sessions/ sessions, messages, dashboard, usage, processes |
| Browser | Managed browser workbench for visible web navigation. | /web-modules/Browser/index.html |
| ComputerUse | Visual desktop/UI operation where the screen is the task. | /web-modules/ComputerUse/index.html |
| DesktopViewer | Desktop viewer surface for live screen inspection. | /web-modules/DesktopViewer/viewer.html |
| SkillManagement | Skill-management web/admin surface. | /skill-management |
| Heartbeat | Scheduled follow-up subscriptions for long-running agent work. | /heartbeat-subscriptions |
| RealtimeVoice | Realtime voice gateway and related host routes. May have no Pages entry. | /api/transcribe, /api/tts/stream, /voice-gateway/api/voice/realtime |
| Developer and critic | ||
| CodeReviews | Code review, diff, and check-in UI. | /code-reviews |
| OntologyWorkbench | Ontology inspection, critic settings, and prototype reuse. | launch, critic-settings, prototype-reuse |
| CodexEmbedded | Embedded Codex workbench. | /web-modules/CodexEmbedded/index.html |
| SourceViewer | Source browsing workbench. | /web-modules/SourceViewer/index.html |
| OfflineOntologyCritic | Offline ontology critic UI. | /web-modules/OfflineOntologyCritic/critic |
| DispatchTreeViewer | Agent Next session extension; often no standalone page. | session extension |
| ActionLearningCoordinator | Session work-coordinator workspaces. | coordinator workspaces |
| ErrorLogDispatch | Error-log dispatch settings. | /web-modules/ErrorLogDispatch/settings |
| Platform and catalogs | ||
| ExtensionPublishing | Publish and inspect packaged extensions. | /extension-publishing |
| ExtensionBrowser | Chrome extension browser surface. | /web-modules/ExtensionBrowser/chrome-extension |
| Workspace | Agent Next workspace scripts; often no standalone page. | empty Pages |
| GeneralSkillWorkbench | Generic skill workbench and related workspaces. | workbench, /workspaces/marketing |
| OpenAIAdmin | OpenAI admin harness. | /web-modules/OpenAIAdmin/index.html |
| OpenAIImageGeneration | Image-generation harness. | /web-modules/OpenAIImageGeneration/index.html |
| OllamaCloud / OpenRouterCloud | Headless JsonWs catalog modules, not product UI pages. | empty Pages |
| Optional integrations | ||
| GoogleWorkspace | Google account and configuration surface. | /web-modules/GoogleWorkspace/google-workspace-accounts.html |
| Office365 | Microsoft 365 account surface when that package is installed. | accounts HTML |
| LinkedIn / GoDaddy | Optional publishing and domain packages. | package-specific UI |
| Ads, Marketing Workbench, Feeding Frenzy | Optional or site-local packages. Not Buffaly core product. Do not assume they exist on a stock install. | only if installed and enabled |
How users interact safely with web and UI surfaces
Users usually open static pages, module-backed routes, generated controls that call JsonWs services, wiki/session views, or ask Buffaly to use a module-backed skill. When asking an agent to use UI, include the target route, environment/account boundary, allowed actions, and where the agent should stop for confirmation.
Verify a module is installed
Ask Buffaly to inspect lib/web-modules/WebModules.json, confirm the page path, and verify generated JsonWs files before trying the workbench.
Diagnose buttons that fail
Separate the static page from backend clients and configuration by checking wwwroot/JsonWs, the route, and runtime project-root settings.
Use UI automation with boundaries
Specify what the agent may click, whether form submission is allowed, and which destructive or persistent controls require confirmation.
Prefer typed paths first
If a typed provider settings service or JsonWs route exists, read the setting directly and use the web UI only when direct evidence is unavailable.
Troubleshooting checklist
When a web module or UI workflow fails, check evidence in this order before changing configuration or rerunning installation.
- Route or page: confirm the target static page or route exists in source or manifest.
- Install root: identify which install root the running host uses and whether it contains
lib\web-modules\WebModules.json. - Manifest: confirm the module is present, enabled, and has the expected assembly path, type name, and page paths.
- Assembly/type: verify the assembly exists under the install root and the type implements
IBuffalyWebModule. - Runtime diagnostics: check
/api/diagnostics/web-modulesfor the module name andJsonWsRootExists. - Startup: review host logs to confirm
Configureand route mapping completed without errors. - JsonWs: verify generated
.jsonand.ashx.jsfiles underwwwroot\JsonWs. - Static assets: confirm module static files are under
wwwroot\web-modules\<ModuleName>. - Skills/services: if the module provides agent capabilities, confirm related ProtoScript skills and service bindings are installed and enabled.
- Credentials: confirm provider, API, and user secrets are configured in the appropriate secret store or feature settings.
- Deployment differences: compare the running install root with the repository layout you inspected.
- Logs: check
C:\logs\Buffalyfor module load failures, JsonWs errors, and route exceptions.
Common mistakes to avoid
- Assuming source presence means the module is enabled in the running deployment.
- Treating a web module as the same thing as an agent tool or action.
- Copying static files outside module-owned
wwwroot\web-modules\<ModuleName>folders. - Restarting the host to fix an install-time file-copy or JsonWs generation problem.
- Using Browser or ComputerUse when a typed service, JsonWs route, file-system tool, SQL query, or HTTP call is safer.