zk-data-agent/docs/openwebui-integration.md

Open WebUI integration

Responsibility split

Open WebUI is the product shell. It owns account registration, login sessions, RBAC, administrator approval, conversation history, and rendering. K1412 does not fork those responsibilities into a second authentication or chat database.

K1412 Runtime owns the only user-facing Agent loop: context selection, durable memory, planning, tool schemas, scheduling, parallel reads, child Agents, evidence gating, experiments, and run-event persistence. Workspace Gateway owns identity-bound execution policy and Docker lifecycle.

This split makes the expensive experimental surface small. A new scheduler or context policy changes Runtime, not the account system or entire frontend.

Tool and progress rendering

Open WebUI natively understands tool-call and reasoning detail blocks. It also has a richer live status mechanism for loops that execute inside its own backend. K1412 Runtime is an external OpenAI-compatible provider, so it cannot mutate Open WebUI's internal socket status objects directly.

K1412 therefore emits Open WebUI-compatible completed tool detail blocks. Each tool appears once with:

• a localized action name;
• sanitized arguments (file contents and patches are omitted);
• success or failure state;
• concise plain output instead of the internal JSON envelope.

K1412 deliberately does not expose hidden chain-of-thought. The UI shows execution progress, tool evidence, completion checks, and concise Agent summaries. This is enough to inspect behavior without treating private model reasoning as a product API.

The earlier implementation appended one unfinished and one completed <details> element for every tool call. Since standard provider streaming is append-only, Open WebUI rendered them as duplicate cards. Runtime now emits only the completed card; the normal generation indicator covers the active wait.

Patches and upgrade cost

Open WebUI is pinned to v0.9.6 and an exact commit. The web image applies a small patch set during a reproducible build. Product-specific Svelte components and the authenticated workspace router live under docker/web/.

Upgrading Open WebUI requires:

1. updating the tag and commit pin;
2. replaying every patch with git apply;
3. building the Svelte production bundle;
4. running authentication, Agent-loop, isolation, and file-browser E2E tests;
5. reviewing upstream license changes.

The K1412 Agent loop is not embedded into Open WebUI, so most Agent experiments do not incur this upgrade cost.