Core

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 page

Local content and diagnostics routes

/api/local-file-image previews referenced local images.
/markdown-viewer supports local markdown viewing.
/api/local-text-file serves local text references.
/api/diagnostics/web-modules reports 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:

<installRoot>\lib\web-modules\WebModules.json

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.

Important: a checked-in constant named 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

The development manifest and source tree identify several enabled module areas. Treat this as checked-in development evidence, not proof that every deployment has the same install root, credentials, routes, or runtime availability.

Module or area	Purpose	Observed routes or paths
Heartbeat	Health or subscription-style module with embedded assets.	`/heartbeat-subscriptions`, `/heartbeat/assets/{assetName}`
Wiki	Checked-in Buffaly documentation surface.	`buffaly.agent.web/wwwroot/Wiki`
Skill Management	Skill-management web/admin surface tied to runtime project-root configuration.	`/skill-management`
GoogleWorkspace	Account and configuration surface.	`/web-modules/GoogleWorkspace/google-workspace-accounts.html`
Browser	Workbench for visible web navigation or page-state checks.	`/web-modules/Browser/index.html`
ComputerUse	Broader UI or desktop-style operation where visual interaction is the task.	`/web-modules/ComputerUse/index.html`
OpenAIImageGeneration	Image-generation harness area.	`/web-modules/OpenAIImageGeneration/index.html`
Voice and realtime gateway	Transcription, text-to-speech, driver capability, interaction, and gateway proxy routes.	`/api/transcribe`, `/api/tts/stream`, `/voice-gateway/api/voice/realtime`
Sessions and worker UI	Worker manager, session websocket, callbacks, route resolution, and public session links.	`worker-manager.html`, `/ws/agent`, `/api/admin/sessions-web-link`

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-modules for the module name and JsonWsRootExists.
Startup: review host logs to confirm Configure and route mapping completed without errors.
JsonWs: verify generated .json and .ashx.js files under wwwroot\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\Buffaly for 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.

Services UI verification JsonWs