feat(harness): agent source registry and the understand-agent stage

README.md

@@ -46,6 +46,18 @@ Use it when you want one reproducible loop:
 4. Promote the result into a replayable artifact.
 5. Prove release readiness with local gates.
 
+### The harness: point it at an agent and talk to it
+
+`src/fi/alk/harness/` builds all of the above **for** an agent instead of asking you to write it.
+Point it at an agent's source and it reads what that agent verifiably is, builds a real world its
+tools act on, and writes test scenarios that are each proved before they are kept. It is driven
+as a conversation, in a terminal or on a web page.
+
+- **[Start here](src/fi/alk/harness/README.md)**: setup from nothing, then how to use it
+- **[The web page](harness-ui/README.md)**: the same harness as a chat, on `localhost:8777`
+- **[How it works](src/fi/alk/harness/HOW-IT-WORKS.md)** and
+  **[why it is shaped this way](src/fi/alk/harness/DESIGN.md)**
+
 OpenEnv/Gymnasium shapes are compatibility inputs, not the product center.
 Agent Learning Kit is the primary runtime and release contract, and the bar is
 the executable `environment_10x_robustness` release gate.

harness/.dockerignore

@@ -0,0 +1,34 @@
+# Credentials, first and deliberately. Nothing in the Dockerfile copies these today, but the
+# whole context is handed to the daemon, and the day someone adds a broad COPY is the day live
+# keys land in an image layer. Excluded here so that mistake cannot be made.
+.env
+.env.*
+*.pem
+*.key
+*-credentials.json
+service-account*.json
+
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+
+# Session artifacts: contracts, worlds, transcripts, recordings. Written at run time into a
+# mounted volume, and large enough to slow every build if they were sent as context.
+artifacts
+sessions
+
+node_modules
+dist
+build
+*.egg-info
+
+docs
+examples
+typescript
+oss

harness/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+artifacts/*
+!artifacts/.gitkeep

harness/Dockerfile

@@ -0,0 +1,52 @@
+# The harness in a container.
+#
+# Three runtimes have to be here, and each is here for a reason worth stating. Python runs the
+# harness itself. Node runs the Claude Code CLI, which the Agent SDK drives as a subprocess --
+# without it every stage fails at its first model call. The docker client is here because the
+# harness starts containers of its own: a store for a world that needs a real engine, and an
+# agent whose tools cannot be imported. It talks to a daemon over the socket proxy rather than
+# running one of its own, so there is no Docker-in-Docker and no privileged mode.
+
+FROM node:22-bookworm-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PATH="/opt/venv/bin:${PATH}"
+
+# Bookworm's python3 is 3.11, which satisfies requires-python. The venv is not isolation from
+# anything here; it is what lets pip write at all, since a Debian-managed interpreter refuses.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates curl git python3 python3-venv \
+    && rm -rf /var/lib/apt/lists/* \
+    && python3 -m venv /opt/venv
+
+# The client alone, not the daemon: the static tarball is a few megabytes where the distribution
+# package would pull in an engine this container must never run.
+ARG DOCKER_CLI_VERSION=27.3.1
+RUN curl -fsSL "https://download.docker.com/linux/static/stable/$(uname -m)/docker-${DOCKER_CLI_VERSION}.tgz" \
+      | tar -xz -C /tmp docker/docker \
+    && mv /tmp/docker/docker /usr/local/bin/docker \
+    && rm -rf /tmp/docker
+
+RUN npm install -g @anthropic-ai/claude-code
+
+WORKDIR /app
+
+# The harness has its own manifest but imports the parent checkout's public fi.simulate API.
+# Build from the parent checkout: docker build -f harness/Dockerfile .
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY harness/pyproject.toml harness/README.md ./harness/
+COPY harness/src ./harness/src
+RUN pip install -e . && pip install -e ./harness
+
+COPY harness/ui ./harness/ui
+
+# Reachable from outside the container, which loopback would not be.
+ENV HARNESS_HOST=0.0.0.0 \
+    HARNESS_PORT=8777
+EXPOSE 8777
+
+CMD ["python", "harness/ui/server.py"]