zk-data-agent/docs/architecture.md

Architecture

Product modes

Chat and Work share the same authenticated user, conversation history, and workspace, but not the same Agent loop.

Concern	Chat	Work
Primary purpose	Fast conversation	Multi-step deliverables
Loop owner	Open WebUI native loop	K1412 Agent Runtime
Tools	Workspace Gateway through OpenAPI	Workspace Gateway through Runtime
Visible history	Open WebUI	Open WebUI
Run events	Open WebUI	Runtime event store
Context and memory	Open WebUI defaults are disabled by policy	Runtime policy and store

Selecting Work atomically upgrades (user_id, chat_id) in the Runtime store. Subsequent Chat requests for that conversation are rejected even if a client tries to bypass the disabled UI control.

Work loop

The first strategy is intentionally modular:

• ModelProvider owns provider transport.
• ContextPolicy owns visible-message cleanup and compaction.
• ToolRegistry owns tool schemas and dispatch.
• AgentLoop owns iteration, safe parallel scheduling, and delegation.
• RuntimeStore owns modes, events, plans, and durable Work memory.
• ExecutionProvider owns local or SSH Docker execution.

Every run records its model tier, strategy version, scheduler version, context policy, model/tool events, failures, and completion. This event stream is the foundation for replay, evaluation, and future experiment assignment.

Read-only tools and read-only child Agents may run concurrently. Workspace mutations are serialized. A child Agent cannot delegate again, and read-only children receive only read-only tools.

Execution providers

local-docker connects the Workspace Gateway to the local Docker daemon. ssh-docker connects the same Docker SDK operations to a remote physical machine through SSH. Both create the same workspace image, persistent per-user volume, and dedicated per-user bridge network, so moving execution off the web host changes configuration rather than Agent behavior.

For SSH mode, layer compose.ssh.yaml over the development Compose file, or deploy/docker-compose.ssh.yml over the two production Compose files. The override removes the local Docker socket and mounts only the selected SSH configuration directory read-only.

Only Open WebUI publishes a host port. Runtime, Gateway, Postgres, and Redis remain unpublishing services. Runtime and Gateway also join an egress-only bridge so the model API and a future SSH Docker host are reachable without exposing either service on the host.