# K1412 Agent

K1412 Agent is a multi-user web Agent built around two deliberately different
experiences:

- **Chat** is fast, conversational, and uses Open WebUI's native tool loop.
- **Work** is a long-running coding Agent whose loop, scheduler, context,
  memory, tools, and sub-agents are owned by this repository.

A conversation may be upgraded from Chat to Work. The upgrade is intentionally
one-way so that two independent Agent loops never compete for the same
conversation state.

## Architecture

```text
browser
  |
  v
Open WebUI (auth, RBAC, chat history, UI)
  |
  v
Agent Runtime (model gateway + Work loop)
  |
  v
Workspace Gateway (identity, policy, audit)
  |
  v
one Docker workspace per Open WebUI user
```

Open WebUI is pinned and lightly patched. Its model picker is replaced by two
product-level choices: `Chat / Work` and `轻度 / 中 / 高`. Provider URLs,
provider model IDs, API keys, tool server settings, system prompts, and runtime
parameters remain server-side.

The inference mapping is fixed:

| Strength | Provider model |
| --- | --- |
| 轻度 | `ChatGPT-5.6:Luna` |
| 中 | `ChatGPT-5.6:Terra` |
| 高 | `ChatGPT-5.6:Sol` |

## Local development

1. Copy `.env.example` to `.env` and fill in the secret values. Never commit
   `.env`. Generate new values with `./scripts/init-secrets.sh`.
2. Build the user workspace image:

   ```bash
   docker compose --profile build-only build workspace-image
   ```

3. Start the stack:

   ```bash
   docker compose up --build
   ```

4. Open <http://localhost:3000>. New users register as `pending` and require
   approval by the bootstrap administrator.

The pasted provider credential from the planning conversation is intentionally
not stored here. Rotate it and place the replacement only in the protected
deployment `.env`.

## Tests

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

Run the complete local verification path, including the real Docker isolation
test, with:

```bash
./scripts/verify.sh
```

Run the disposable six-service integration stack with a deterministic fake
model provider and exercise registration approval, both Agent loops, workspace
isolation, and the one-way mode upgrade with:

```bash
./scripts/verify-e2e.sh
```

The E2E stack and its test-only volumes are removed on exit. Set
`E2E_KEEP_STACK=1` only when you need to inspect the running containers.

Audit every finished service and workspace image, requiring consistent Python
environments, zero known Python vulnerabilities, and zero fixable
High/Critical image vulnerabilities, with:

```bash
./scripts/audit-images.sh
```

## Deployment

Production uses immutable `linux/amd64` images in
`docker.k1412.top/wuyang/*`, an Unraid Compose Manager project, private
service networking, and a single public HTTPS entry at
`https://agent.k1412.top`.

See [docs/architecture.md](docs/architecture.md) and
[docs/security.md](docs/security.md).

## Open WebUI attribution

The web service is derived from Open WebUI v0.9.6. Open WebUI's copyright,
license, name, and user-facing attribution are retained. See
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).