# 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

```text
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.