zk-data-agent/docs/architecture.md

Architecture

Single Agent path

Open WebUI owns authenticated users, conversation history, and rendering. Every normal model request is delegated to the K1412 Runtime. There is no second Chat loop and no per-conversation mode state.

Agent 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 events, plans, and durable Agent memory.
• ExecutionProvider owns local or SSH Docker execution.

Every run records its model ID, 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.

Luna, Terra, and Sol are three independent Ollama models. Each advertises boolean thinking support, but none advertises adjustable reasoning effort. DeepSeek V4 Pro is a fourth model configured with thinking enabled and maximum reasoning effort. Provider selection and credentials remain server-side. Thinking state is preserved across tool turns when the provider requires the assistant's reasoning_content to be returned with following tool results. The Agent never publishes hidden reasoning as its own user-facing output.

Completion is evidence-gated. Requests for scripts, reports, code, or other concrete artifacts are not accepted as complete until a file mutation has succeeded and a later read, diff, or command has verified the latest mutation. Bare interactive shell commands are rejected. If the iteration budget is exhausted without evidence, Runtime returns an explicit incomplete checkpoint instead of repeating an unverified model claim.

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.

Workspace file path

browser with Open WebUI session
  -> /api/v1/k1412/workspace/*
  -> Open WebUI backend verifies the user
  -> backend mints a short-lived signed identity JWT
  -> Workspace Gateway verifies service key + user JWT
  -> provider selects only that user's hashed container and volume

The file API exposes read-only browse, file download, and streamed directory archive operations. Paths pass through the same /workspace normalization as Agent tools. The browser never talks to Gateway or Docker directly.