feat(integrations): hud.integrations, with Harbor as its first frontend

integrations/ becomes hud.integrations because an adapted image imports it:
the image's CMD serves hud.integrations.harbor:environment, so the module has
to ship in the wheel that image installs. Nothing in the SDK or CLI imports
it — a Harbor taskset is loaded and placed explicitly.

Harbor implements the contract:

- load() carries what a task declares, not just its identity: [metadata] as
  Task.columns (difficulty/category/tags — the platform's facets),
  [environment] cpu/memory/gpu as RuntimeConfig.resources, real descriptions
  on templates, verifier.env for the verifier. Time budgets stay off the row
  — a budget bounds the rollout, not the substrate — and agent_timeout()
  exposes them for rollout_timeout.
- adapt() packages the environment constructor into one HUD-speaking image
  per build context, whose CMD serves that constructor; rows then run on any
  container placement. Images are content-addressed and kept, built once per
  group under a lock.
- environment() is what those images serve: the workspace applies the task's
  declared network isolation, env, workdir and user, healthchecks gate
  serving, URL MCP servers are published as capabilities, and tests/test.sh
  grades in place under the task's verifier timeout.

Behaviour that cannot be reproduced faithfully is refused, not dropped:
allowlist egress, a verifier with its own environment, stdio MCP servers,
non-linux os, TPUs, and multi-step tasks (which load, but do not adapt).
Environments are grouped by build context *and* declared policy, so one
environment always serves one policy.

Container, workspace and grading mechanics were ported from #478.

Co-authored-by: Nancy <[email protected]>

Author: jdchawla29

docs/v6/advanced/harbor-convert.mdx

@@ -1,16 +1,21 @@
 ---
 title: "Harbor interop"
-description: "Load Harbor tasks into the HUD runtime or export HUD tasks to Harbor folders, with the converter CLI and a field-by-field mapping between formats."
+description: "Load Harbor tasks into the HUD runtime or export HUD tasks to Harbor folders, with a field-by-field mapping between formats."
 icon: "ship"
 ---
 
 Everything that authors tasks - HUD's own `env.py`, platform rows, **Harbor**
 task dirs - is a *frontend* that loads into the same primitives (`Environment`,
 `Task`, `Taskset`). Integrations are **loaders, not converters**: no codegen
-roundtrip to run foreign tasks. The Harbor integration lives in the SDK repo at
-[`integrations/harbor.py`](https://github.com/hud-evals/hud-python/blob/main/integrations/harbor.py)
-- a recipe built only on the public SDK surface; copy it into your project or
-run it from a checkout.
+roundtrip to run foreign tasks. Each one implements
+[`hud.environment.Integration`](https://github.com/hud-evals/hud-python/blob/main/hud/environment/integration.py)
+- `load(ref) -> Taskset` and `environment(ref) -> Environment` - and ships as
+`hud.integrations.<format>`.
+
+Harbor's agent works *inside* its container, so its environment constructor is
+only meaningful in there. `adapt()` packages it: one HUD-speaking image per
+distinct build context, whose CMD serves `hud.integrations.harbor:environment`.
+The same rows then run on any container placement.
 
 ## Prerequisites
 
@@ -24,34 +29,57 @@ directly - one row per task dir (`id` = the dir name), sharing one declarative
 `Environment` per distinct `environment/` build context:
 
 ```python
-from integrations.harbor import detect, load
+from hud.integrations import harbor
 
-assert detect("./terminal-bench")
-taskset = load("./terminal-bench")
+assert harbor.detect("./terminal-bench")
+taskset = harbor.load("./terminal-bench")
 
 for task in taskset:
-    print(task.env, task.id)
+    print(task.env, task.id, task.columns["difficulty"])
 ```
 
-Like every task row, the result carries no placement. Run it by supplying one -
-today that means a substrate already serving the control channel
-(`runtime=Runtime(url)`); a docker provider that builds and runs each task's
-`environment/` image is the planned follow-up:
+Each row carries what the task declared: `[metadata]` as `columns` (difficulty,
+category, tags - the platform's filter/leaderboard facets) and
+`[environment]` cpu/memory/gpu as `runtime_config`. Time budgets stay off the
+row, since they bound the *rollout* rather than the substrate - read one with
+`harbor.agent_timeout(task_dir)` and pass it as `rollout_timeout`.
+
+## Run Harbor tasks
+
+Build the images once, then place the rows anywhere:
 
 ```python
-from hud import Runtime
+from hud.eval import DockerRuntime
 
-job = await taskset.run(agent, runtime=Runtime("tcp://127.0.0.1:8765"))
+await harbor.adapt("./terminal-bench")            # local images
+job = await harbor.load("./terminal-bench").run(agent, runtime=DockerRuntime())
 ```
 
+`adapt(path, push="registry.io/acme")` pushes instead, and writes
+`.hud-images.json` next to the tasks so `load()` stamps each row with its image
+- from there `hud deploy` of the generated contexts under `.hud-adapt/` works
+unchanged (both run the image's own CMD). `ModalRuntime` / `DaytonaRuntime`
+replace the CMD with their `command=` - pass
+`harbor.serve_command(env_name)` to serve the group's constructor there.
+
+Tasks whose declared behaviour cannot be reproduced faithfully are refused
+rather than silently downgraded. Adaptation replaces the container's own boot
+process with the serving command, so anything depending on that boot process is
+refused: a Dockerfile `ENTRYPOINT`, `healthcheck` (nothing would start the
+services it awaits), and `mcp_servers` (nothing would start the servers they
+point at) — alongside `network_mode = "allowlist"`, a verifier with its own
+environment, non-linux `os`, TPUs, and multi-step `[[steps]]` tasks. Supported
+and applied: `no-network` isolation, `environment.env`, `workdir`, and
+`agent`/`verifier` `user`.
+
 ## Export HUD tasks to Harbor
 
 `export(source, out_dir)` goes the other way: it turns a HUD task source (a
 `.py` file/dir exposing `Task`s, or a `.json`/`.jsonl` taskset next to its
 `env.py`) into self-contained Harbor task folders:
 
 ```python
-from integrations.harbor import export
+from hud.integrations.harbor import export
 
 created = await export("tasks.py", "harbor_tasks")
 ```

hud/integrations/__init__.py

@@ -0,0 +1,9 @@
+"""Interop frontends: foreign benchmark formats as HUD primitives.
+
+Each format implements :class:`hud.environment.Integration` — see its module
+docstring for the contract (``load`` / ``environment``). Format
+modules also keep an ergonomic function surface (``harbor.load(...)``) and
+format extras: ``harbor.detect`` recognizes the layout, ``harbor.adapt``
+packages the constructor into container images, ``harbor.export`` is the
+reverse direction.
+"""

hud/integrations/harbor/__init__.py

@@ -0,0 +1,74 @@
+"""Harbor (terminal-bench layout) interop: load, adapt, export.
+
+Harbor task structure::
+
+    task_name/
+    ├── instruction.md          # agent prompt
+    ├── task.toml               # config: timeouts, metadata
+    ├── environment/Dockerfile  # container the agent works in
+    ├── tests/test.sh           # verification -> writes reward.txt / .json
+    └── solution/               # optional (ignored)
+
+Harbor's agent works *inside* its container, so :func:`environment` (the
+:class:`~hud.environment.Integration` constructor) is meaningful only in
+there — :func:`adapt` packages it: one HUD-speaking image per env group
+whose CMD serves ``harbor.environment``, and the same rows then run on any
+container placement::
+
+    await harbor.adapt("./tasks")  # local images
+    job = await harbor.load("./tasks").run(agent, runtime=DockerRuntime())
+
+    await harbor.adapt("./tasks", push="registry.io/x")  # or hud deploy the
+    job = await harbor.load("./tasks").run(agent, runtime=HUDRuntime())  # contexts
+
+Plus :func:`export`, the reverse direction (HUD tasks -> Harbor folders).
+Compose-based and prebuilt-``docker_image`` tasks are not supported yet.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hud.environment import Integration
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from hud.environment import Environment
+    from hud.eval import Taskset
+
+from ._adapt import adapt, environment, serve_command
+from ._export import ALLOWED_PROTOCOLS, CONTROL_PORT, DEFAULT_ANSWER_FILE, export
+from ._load import IMAGES_MANIFEST, agent_timeout, detect, grouped, load
+
+
+class Harbor(Integration):
+    """The :class:`~hud.environment.Integration` contract for Harbor."""
+
+    name = "harbor"
+
+    def load(self, ref: str | Path) -> Taskset:
+        return load(ref)
+
+    def environment(self, ref: str | Path, *, name: str | None = None) -> Environment:
+        return environment(ref, name=name)
+
+
+integration = Harbor()
+
+__all__ = [
+    "ALLOWED_PROTOCOLS",
+    "CONTROL_PORT",
+    "DEFAULT_ANSWER_FILE",
+    "IMAGES_MANIFEST",
+    "Harbor",
+    "adapt",
+    "agent_timeout",
+    "detect",
+    "environment",
+    "export",
+    "grouped",
+    "integration",
+    "load",
+    "serve_command",
+]