agent-hitch 0.2.0 → 0.2.2

package/integrations/harbor/hitch_harbor_agent.py

@@ -6,7 +6,10 @@ import hashlib
 import json
 import re
 import shlex
+import stat as stat_module
 import tempfile
+import uuid
+from datetime import datetime
 from pathlib import Path
 from typing import Any
 
@@ -15,6 +18,10 @@ from harbor.environments.base import BaseEnvironment, ExecResult
 from harbor.models.agent.context import AgentContext
 
 CONTROLLER_RUNTIME_MANIFEST_VERSION = "2"
+LOCAL_GIT_TRANSPORT_MANIFEST_VERSION = "1"
+LOCAL_GIT_TRANSPORT_MAX_BYTES = 512 * 1024 * 1024
+LOCAL_GIT_REMOTE_ROOT = "/opt/hitch-local-source"
+HARNESS_ARTIFACT_REMOTE_ROOT = "/opt/hitch-harness-artifact"
 
 
 class HitchHarborAgent(BaseAgent):
@@ -28,9 +35,15 @@ class HitchHarborAgent(BaseAgent):
         hitch_runtime_dir: str,
         candidate_id: str = "candidate-1",
         controller_runtime_id: str | None = None,
+        harness_artifact: dict[str, Any] | None = None,
+        local_source_transport: dict[str, Any] | None = None,
         hitch_timeout_ms: int = 900_000,
         agent_args: list[str] | None = None,
         workdir: str = "/app",
+        eval_id: str | None = None,
+        benchmark_id: str | None = None,
+        benchmark_revision: str | None = None,
+        verifier_identity: str | None = None,
         **kwargs: Any,
     ) -> None:
         super().__init__(logs_dir=logs_dir, **kwargs)
@@ -38,12 +51,21 @@ class HitchHarborAgent(BaseAgent):
         self.revision_identity = revision_identity
         self.hitch_runtime_dir = Path(hitch_runtime_dir)
         self.controller_runtime_id = controller_runtime_id
+        self.harness_artifact = dict(harness_artifact) if harness_artifact else None
+        self.local_source_transport = dict(local_source_transport) if local_source_transport else None
         self.candidate_id = candidate_id
         self.hitch_timeout_ms = int(hitch_timeout_ms)
         self.agent_args = list(agent_args or [])
         self.workdir = workdir
+        self.eval_id = eval_id
+        self.benchmark_id = benchmark_id
+        self.benchmark_revision = benchmark_revision
+        self.verifier_identity = verifier_identity
         self._hitch_version: str | None = None
         self._entrypoint: str | None = None
+        self._artifact_manifest: dict[str, Any] | None = None
+        self._artifact_uploaded = False
+        self._local_manifest: dict[str, Any] | None = None
 
     @staticmethod
     def name() -> str:
@@ -76,6 +98,16 @@ class HitchHarborAgent(BaseAgent):
         # and the actual container upload, spec §4.6).
         self._verify_manifest_identity(manifest)
         self._verify_payload(manifest)
+        if self.harness_artifact is not None:
+            try:
+                self._artifact_manifest = self._verify_harness_artifact_host()
+            except Exception as error:
+                raise RuntimeError(f"hitch-artifact-materialize: {error}") from error
+        if self.local_source_transport is not None:
+            try:
+                self._local_manifest = self._verify_local_source_host()
+            except Exception as error:
+                raise RuntimeError(f"hitch-local-source-materialize: {error}") from error
         payload_dir = self.hitch_runtime_dir / "payload"
         if not payload_dir.is_dir():
             raise RuntimeError(f"Hitch runtime bundle has no payload directory: {self.hitch_runtime_dir}")
@@ -84,19 +116,293 @@ class HitchHarborAgent(BaseAgent):
         # bookkeeping and is not identity (spec §4.2).
         await environment.upload_dir(payload_dir, "/opt/hitch")
         await self._ensure_node(environment)
+        if self._artifact_manifest is not None:
+            platform = await self._container_platform(environment)
+            if platform == self._artifact_manifest["platform"]:
+                await environment.upload_dir(
+                    Path(str(self.harness_artifact["directory"])),
+                    HARNESS_ARTIFACT_REMOTE_ROOT,
+                )
+                self._artifact_uploaded = True
+        if self._local_manifest is not None and not self._artifact_uploaded:
+            try:
+                await self._upload_and_materialize_local_source(environment, self._local_manifest)
+            except Exception as error:
+                raise RuntimeError(f"hitch-local-source-materialize: {error}") from error
         entry = self._remote_entry(entrypoint)
         version = await self._exec(environment, f"{self._node_prefix()} node {entry} --version")
         self._hitch_version = (version.stdout or "").strip() or None
-        prepare = " ".join(
-            [
-                self._node_prefix(),
-                "HITCH_ROOT=/tmp/hitch-state",
-                f"node {entry} prepare",
-                shlex.quote(self.harness_ref),
-                "--json",
-            ]
+        if not self._artifact_uploaded:
+            prepare = " ".join(
+                [
+                    self._node_prefix(),
+                    "HITCH_ROOT=/tmp/hitch-state",
+                    *(["HITCH_HARBOR_INTERNAL=1"] if self._local_manifest is not None else []),
+                    f"node {entry} prepare",
+                    shlex.quote(self.harness_ref),
+                    *self._local_source_cli_args(),
+                    "--json",
+                ]
+            )
+            await self._exec(environment, prepare)
+
+    def _verify_harness_artifact_host(self) -> dict[str, Any]:
+        """Pin host artifact metadata before Harbor copies the directory."""
+        transport = self.harness_artifact or {}
+        required = {
+            "directory", "artifact_id", "artifact_integrity", "entrypoint_integrity",
+            "harness_id", "revision_identity", "platform", "source_type",
+        }
+        if set(transport) != required:
+            raise RuntimeError("prepared artifact handoff metadata fields are invalid")
+        directory = Path(str(transport["directory"]))
+        if not directory.is_absolute():
+            raise RuntimeError("prepared artifact host path must be absolute")
+        try:
+            directory_info = directory.lstat()
+        except OSError as error:
+            raise RuntimeError("prepared artifact directory is missing or unreadable") from error
+        if not stat_module.S_ISDIR(directory_info.st_mode) or directory.is_symlink():
+            raise RuntimeError("prepared artifact handoff must be a regular directory")
+        artifact_file = directory / "artifact.json"
+        self._assert_regular_host_file(artifact_file, "prepared artifact manifest", 1024 * 1024)
+        try:
+            manifest = json.loads(artifact_file.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as error:
+            raise RuntimeError("prepared artifact manifest is unreadable") from error
+        pinned = {
+            "artifact_id": manifest.get("artifact_id"),
+            "artifact_integrity": manifest.get("artifact_integrity"),
+            "entrypoint_integrity": manifest.get("entrypoint_integrity"),
+            "harness_id": manifest.get("harness_id"),
+            "revision_identity": manifest.get("revision_identity"),
+            "platform": manifest.get("platform"),
+            "source_type": manifest.get("source_type"),
+        }
+        if any(transport.get(key) != value for key, value in pinned.items()):
+            raise RuntimeError("prepared artifact metadata does not match its manifest")
+        if manifest.get("revision_identity") != self.revision_identity:
+            raise RuntimeError("prepared artifact revision does not match the job-pinned identity")
+        if manifest.get("source_type") == "installed":
+            raise RuntimeError("installed harness artifacts cannot cross the container boundary")
+        if not re.fullmatch(r"sha256:[0-9a-f]{64}", str(manifest.get("artifact_id", ""))):
+            raise RuntimeError("prepared artifact ID is invalid")
+        for field in ("artifact_integrity", "entrypoint_integrity", "revision_identity"):
+            if not re.fullmatch(r"sha256:[0-9a-f]{64}", str(manifest.get(field, ""))):
+                raise RuntimeError(f"prepared artifact {field} is invalid")
+        if not re.fullmatch(r"(?:linux|darwin|win32)-[a-z0-9_]+", str(manifest.get("platform", ""))):
+            raise RuntimeError("prepared artifact platform is invalid")
+        return manifest
+
+    async def _container_platform(self, environment: BaseEnvironment) -> str:
+        result = await self._exec(
+            environment,
+            f'{self._node_prefix()} node -p "process.platform + \'-\' + process.arch"',
         )
-        await self._exec(environment, prepare)
+        platform = (result.stdout or "").strip()
+        if not re.fullmatch(r"(?:linux|darwin|win32)-[a-z0-9_]+", platform):
+            raise RuntimeError("container returned an invalid Node.js platform identity")
+        return platform
+
+    def _verify_local_source_host(self) -> dict[str, Any]:
+        """Validate the independent local-source handoff immediately before upload."""
+        transport = self.local_source_transport or {}
+        required = {
+            "kind", "manifest_path", "payload_path", "locked_resolution_path", "harness_id",
+            "resolution_identity", "commit", "tree", "payload_sha256", "payload_bytes",
+            "object_count", "file_count",
+        }
+        if set(transport) != required:
+            raise RuntimeError("local source transport metadata fields are invalid")
+        manifest_path = Path(str(transport["manifest_path"]))
+        payload_path = Path(str(transport["payload_path"]))
+        resolution_path = Path(str(transport["locked_resolution_path"]))
+        if not all(candidate.is_absolute() for candidate in (manifest_path, payload_path, resolution_path)):
+            raise RuntimeError("local source transport host paths must be absolute")
+        self._assert_regular_host_file(manifest_path, "local source manifest", 64 * 1024)
+        payload_stat = self._assert_regular_host_file(payload_path, "local source payload", LOCAL_GIT_TRANSPORT_MAX_BYTES)
+        self._assert_regular_host_file(resolution_path, "local source locked resolution", 1024 * 1024)
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            resolution = json.loads(resolution_path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as error:
+            raise RuntimeError(f"local source metadata is unreadable: {error}") from error
+        self._validate_local_manifest(manifest)
+        pinned = {
+            "kind": manifest["kind"],
+            "harness_id": manifest["harness_id"],
+            "resolution_identity": manifest["resolution_identity"],
+            "commit": manifest["commit"],
+            "tree": manifest["tree"],
+            "payload_sha256": manifest["payload_sha256"],
+            "payload_bytes": manifest["payload_bytes"],
+            "object_count": manifest["object_count"],
+            "file_count": manifest["file_count"],
+        }
+        if any(transport.get(key) != value for key, value in pinned.items()):
+            raise RuntimeError("local source transport metadata does not match its manifest")
+        if manifest["resolution_identity"] != self.revision_identity:
+            raise RuntimeError("local source resolution identity does not match the job-pinned identity")
+        if self.harness_ref != f'{manifest["harness_id"]}@commit:{manifest["commit"]}':
+            raise RuntimeError("local source commit does not match the job-pinned harness ref")
+        if payload_stat.st_size != manifest["payload_bytes"]:
+            raise RuntimeError("local source payload size does not match its manifest")
+        actual_digest = self._sha256_file(payload_path)
+        if actual_digest != manifest["payload_sha256"]:
+            raise RuntimeError("local source payload digest does not match its manifest")
+        if not isinstance(resolution, dict) or (
+            resolution.get("harness_id") != manifest["harness_id"]
+            or resolution.get("identity") != manifest["resolution_identity"]
+            or resolution.get("revision", {}).get("commit") != manifest["commit"]
+            or resolution.get("source", {}).get("type") != "git"
+            or resolution.get("source", {}).get("registered") is not False
+        ):
+            raise RuntimeError("local source locked resolution does not match its manifest")
+        return manifest
+
+    @staticmethod
+    def _assert_regular_host_file(path: Path, label: str, maximum: int) -> Any:
+        try:
+            info = path.lstat()
+        except OSError as error:
+            raise RuntimeError(f"{label} is missing or unreadable") from error
+        if not stat_module.S_ISREG(info.st_mode):
+            raise RuntimeError(f"{label} must be a regular file")
+        if info.st_size > maximum:
+            raise RuntimeError(f"{label} exceeds the size limit ({maximum} bytes)")
+        return info
+
+    @staticmethod
+    def _sha256_file(path: Path) -> str:
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            while chunk := handle.read(1024 * 1024):
+                digest.update(chunk)
+        return "sha256:" + digest.hexdigest()
+
+    @staticmethod
+    def _validate_local_manifest(manifest: Any) -> None:
+        allowed = {
+            "schema_version", "kind", "harness_id", "resolution_identity", "commit", "tree",
+            "payload_sha256", "payload_bytes", "object_count", "file_count", "created_at",
+        }
+        if not isinstance(manifest, dict) or set(manifest) != allowed:
+            raise RuntimeError("local source manifest fields are invalid")
+        if manifest.get("schema_version") != LOCAL_GIT_TRANSPORT_MANIFEST_VERSION:
+            raise RuntimeError("unsupported local source transport manifest schema")
+        if manifest.get("kind") != "local-git-commit":
+            raise RuntimeError("unsupported local source transport kind")
+        if not isinstance(manifest.get("harness_id"), str) or not re.fullmatch(r"[a-z][a-z0-9-]*", manifest["harness_id"]):
+            raise RuntimeError("local source manifest harness id is invalid")
+        if not isinstance(manifest.get("resolution_identity"), str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", manifest["resolution_identity"]):
+            raise RuntimeError("local source manifest resolution identity is invalid")
+        commit = manifest.get("commit")
+        if not isinstance(commit, str) or not re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", commit):
+            raise RuntimeError("local source manifest commit is not a full lowercase OID")
+        tree = manifest.get("tree")
+        if not isinstance(tree, str) or not re.fullmatch(rf"[0-9a-f]{{{len(commit)}}}", tree):
+            raise RuntimeError("local source manifest tree is invalid")
+        if not isinstance(manifest.get("payload_sha256"), str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", manifest["payload_sha256"]):
+            raise RuntimeError("local source manifest payload digest is invalid")
+        for key, maximum in (
+            ("payload_bytes", LOCAL_GIT_TRANSPORT_MAX_BYTES),
+            ("object_count", 100_000),
+            ("file_count", 50_000),
+        ):
+            value = manifest.get(key)
+            if not isinstance(value, int) or isinstance(value, bool) or value < 0 or value > maximum:
+                raise RuntimeError(f"local source manifest {key} is invalid")
+        if not isinstance(manifest.get("created_at"), str) or not manifest["created_at"]:
+            raise RuntimeError("local source manifest created_at is invalid")
+        try:
+            datetime.fromisoformat(manifest["created_at"].replace("Z", "+00:00"))
+        except ValueError as error:
+            raise RuntimeError("local source manifest created_at is invalid") from error
+
+    async def _upload_and_materialize_local_source(
+        self,
+        environment: BaseEnvironment,
+        manifest: dict[str, Any],
+    ) -> None:
+        transport = self.local_source_transport or {}
+        await self._exec(environment, f"mkdir -p {LOCAL_GIT_REMOTE_ROOT} && chmod 700 {LOCAL_GIT_REMOTE_ROOT}")
+        await environment.upload_file(Path(str(transport["manifest_path"])), f"{LOCAL_GIT_REMOTE_ROOT}/manifest.json")
+        await environment.upload_file(Path(str(transport["payload_path"])), f"{LOCAL_GIT_REMOTE_ROOT}/payload.pack")
+        await environment.upload_file(Path(str(transport["locked_resolution_path"])), f"{LOCAL_GIT_REMOTE_ROOT}/resolution.json")
+        await self._exec(environment, f"chmod 600 {LOCAL_GIT_REMOTE_ROOT}/manifest.json {LOCAL_GIT_REMOTE_ROOT}/payload.pack {LOCAL_GIT_REMOTE_ROOT}/resolution.json")
+        # Verify both the uploaded manifest fields and payload bytes inside the
+        # trial before importing any Git object. All interpolated values passed
+        # to the shell have already been restricted to digest/OID grammars.
+        verifier = """
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const expected = JSON.parse(process.argv[1]);
+const manifest = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+if (JSON.stringify(Object.keys(manifest).sort()) !== JSON.stringify(Object.keys(expected).sort())) throw new Error('manifest fields mismatch');
+for (const key of Object.keys(expected)) if (manifest[key] !== expected[key]) throw new Error(`manifest mismatch: ${key}`);
+if (fs.statSync(process.argv[3]).size !== expected.payload_bytes) throw new Error('payload size mismatch');
+(async () => {
+  const hash = crypto.createHash('sha256');
+  for await (const chunk of fs.createReadStream(process.argv[3])) hash.update(chunk);
+  const digest = 'sha256:' + hash.digest('hex');
+  if (digest !== expected.payload_sha256) throw new Error('payload digest mismatch');
+})().catch((error) => { console.error(error.message); process.exit(1); });
+""".strip()
+        expected = {
+            "schema_version": manifest["schema_version"],
+            "kind": manifest["kind"],
+            "harness_id": manifest["harness_id"],
+            "resolution_identity": manifest["resolution_identity"],
+            "commit": manifest["commit"],
+            "tree": manifest["tree"],
+            "payload_sha256": manifest["payload_sha256"],
+            "payload_bytes": manifest["payload_bytes"],
+            "object_count": manifest["object_count"],
+            "file_count": manifest["file_count"],
+            "created_at": manifest["created_at"],
+        }
+        verify_command = " ".join([
+            self._node_prefix(),
+            "node", "-e", shlex.quote(verifier),
+            shlex.quote(json.dumps(expected, separators=(",", ":"))),
+            f"{LOCAL_GIT_REMOTE_ROOT}/manifest.json",
+            f"{LOCAL_GIT_REMOTE_ROOT}/payload.pack",
+        ])
+        await self._exec(environment, verify_command)
+        commit = manifest["commit"]
+        tree = manifest["tree"]
+        materialize = f"""
+set -eu
+git init --bare {LOCAL_GIT_REMOTE_ROOT}/repo.git >/dev/null
+git -C {LOCAL_GIT_REMOTE_ROOT}/repo.git index-pack --stdin < {LOCAL_GIT_REMOTE_ROOT}/payload.pack >/dev/null
+test "$(git -C {LOCAL_GIT_REMOTE_ROOT}/repo.git rev-parse {commit}^{{commit}})" = "{commit}"
+test "$(git -C {LOCAL_GIT_REMOTE_ROOT}/repo.git rev-parse {commit}^{{tree}})" = "{tree}"
+printf '%s\n' {commit} > {LOCAL_GIT_REMOTE_ROOT}/repo.git/shallow
+git -C {LOCAL_GIT_REMOTE_ROOT}/repo.git update-ref refs/heads/hitch-local {commit}
+"""
+        await self._exec(environment, materialize)
+
+    def _local_source_cli_args(self) -> list[str]:
+        if self._local_manifest is None or self._artifact_uploaded:
+            return []
+        return [
+            "--internal-locked-resolution", f"{LOCAL_GIT_REMOTE_ROOT}/resolution.json",
+            "--internal-local-git-manifest", f"{LOCAL_GIT_REMOTE_ROOT}/manifest.json",
+            "--internal-local-git-source", f"{LOCAL_GIT_REMOTE_ROOT}/repo.git",
+        ]
+
+    def _artifact_cli_args(self) -> list[str]:
+        if not self._artifact_uploaded or self._artifact_manifest is None:
+            return []
+        manifest = self._artifact_manifest
+        return [
+            "--internal-prepared-artifact", HARNESS_ARTIFACT_REMOTE_ROOT,
+            "--internal-artifact-id", str(manifest["artifact_id"]),
+            "--internal-artifact-integrity", str(manifest["artifact_integrity"]),
+            "--internal-artifact-entrypoint-integrity", str(manifest["entrypoint_integrity"]),
+            "--internal-artifact-revision-identity", str(manifest["revision_identity"]),
+            "--internal-artifact-platform", str(manifest["platform"]),
+        ]
 
     @staticmethod
     def _remote_entry(entrypoint: str) -> str:
@@ -196,7 +502,41 @@ class HitchHarborAgent(BaseAgent):
         context: AgentContext,
     ) -> None:
         self.logs_dir.mkdir(parents=True, exist_ok=True)
+        run_id = "run_" + uuid.uuid4().hex
+        trial_id, task_id, attempt = self._trial_identity()
+        context_payload: dict[str, Any] = {"kind": "ad_hoc"}
+        parent_payload: dict[str, Any] | None = None
+        if all((self.eval_id, self.benchmark_id, self.benchmark_revision, self.verifier_identity)):
+            workspace_digest = await self._workspace_digest(environment)
+            task_digest_input = json.dumps(
+                {
+                    "benchmark_id": self.benchmark_id,
+                    "benchmark_revision": self.benchmark_revision,
+                    "task_id": task_id,
+                    "instruction": instruction,
+                    "initial_workspace_digest": workspace_digest,
+                },
+                ensure_ascii=False,
+                separators=(",", ":"),
+                sort_keys=True,
+            ).encode("utf-8")
+            context_payload = {
+                "kind": "benchmark_task",
+                "benchmark_id": self.benchmark_id,
+                "benchmark_revision": self.benchmark_revision,
+                "task_id": task_id,
+                "task_digest": "sha256:" + hashlib.sha256(task_digest_input).hexdigest(),
+                "verifier_identity": self.verifier_identity,
+            }
+            parent_payload = {
+                "kind": "eval",
+                "eval_id": self.eval_id,
+                "trial_id": trial_id,
+                "attempt": attempt,
+            }
         temporary: Path | None = None
+        context_temporary: Path | None = None
+        parent_temporary: Path | None = None
         try:
             with tempfile.NamedTemporaryFile(
                 mode="w",
@@ -210,9 +550,18 @@ class HitchHarborAgent(BaseAgent):
                 temporary = Path(handle.name)
             remote_instruction = "/tmp/hitch-instruction.txt"
             await environment.upload_file(temporary, remote_instruction)
+            context_temporary = self._temporary_json("hitch-context-", context_payload)
+            await environment.upload_file(context_temporary, "/tmp/hitch-context.json")
+            if parent_payload is not None:
+                parent_temporary = self._temporary_json("hitch-parent-", parent_payload)
+                await environment.upload_file(parent_temporary, "/tmp/hitch-parent.json")
         finally:
             if temporary is not None:
                 temporary.unlink(missing_ok=True)
+            if context_temporary is not None:
+                context_temporary.unlink(missing_ok=True)
+            if parent_temporary is not None:
+                parent_temporary.unlink(missing_ok=True)
 
         if self._entrypoint is None:
             raise RuntimeError("Hitch agent setup() must run before run() to resolve the runtime entrypoint")
@@ -220,20 +569,31 @@ class HitchHarborAgent(BaseAgent):
         arguments = [
             self._node_prefix(),
             "HITCH_ROOT=/tmp/hitch-state",
+            *(["HITCH_HARBOR_INTERNAL=1"] if self._local_manifest is not None or self._artifact_uploaded or parent_payload is not None else []),
             f"node {entry} run",
             "--harness",
             shlex.quote(self.harness_ref),
+            *self._local_source_cli_args(),
+            *self._artifact_cli_args(),
             "--cwd",
             shlex.quote(self.workdir),
             "--workspace-mode",
             "shared",
             "--prompt-file",
             shlex.quote(remote_instruction),
+            "--context-file",
+            "/tmp/hitch-context.json",
             "--timeout",
             str(self.hitch_timeout_ms),
             "--output",
             "jsonl",
         ]
+        if parent_payload is not None:
+            arguments.extend([
+                "--parent-file", "/tmp/hitch-parent.json",
+                "--internal-run-id", run_id,
+                "--internal-defer-benchmark-observation",
+            ])
         if self.model_name:
             arguments.extend(["--model", shlex.quote(self.model_name)])
         for value in self.agent_args:
@@ -246,7 +606,9 @@ class HitchHarborAgent(BaseAgent):
         )
         execution = await environment.exec(command, cwd=self.workdir)
         events = self._events(execution.stdout or "")
-        run_id = next((event.get("run_id") for event in events if event.get("run_id")), None)
+        observed_run_id = next((event.get("run_id") for event in events if event.get("run_id")), None)
+        if observed_run_id:
+            run_id = str(observed_run_id)
         hitch_result = None
         if run_id:
             result_path = f"/tmp/hitch-state/runs/{run_id}/result.json"
@@ -255,15 +617,51 @@ class HitchHarborAgent(BaseAgent):
             )
             if result.return_code == 0 and result.stdout:
                 hitch_result = json.loads(result.stdout)
+            export = await environment.exec(
+                f"""
+set -eu
+source_dir={shlex.quote(f'/tmp/hitch-state/runs/{run_id}')}
+target_dir=/logs/agent/hitch-run-bundle
+rm -rf "$target_dir"
+mkdir -p "$target_dir"
+for name in request.json resolution.json manifest.json result.json events.jsonl stdout.log stderr.log trajectory.ref.json trajectory; do
+  if [ -e "$source_dir/$name" ]; then cp -a "$source_dir/$name" "$target_dir/$name"; fi
+done
+""".strip()
+            )
+            if export.return_code != 0:
+                raise RuntimeError("Hitch run bundle export failed before trial teardown")
         context.metadata = {
             "candidate_id": self.candidate_id,
             "harness_ref": self.harness_ref,
             "revision_identity": self.revision_identity,
             "controller_runtime_id": self.controller_runtime_id,
             "hitch_run_id": run_id,
+            "hitch_run_bundle": "hitch-run-bundle",
+            "eval_id": self.eval_id,
+            "trial_id": trial_id,
+            "task_id": task_id,
+            "attempt": attempt,
             "hitch_status": hitch_result.get("status") if hitch_result else None,
             "hitch_artifact_id": hitch_result.get("artifact_id") if hitch_result else None,
         }
+        if self._local_manifest is not None:
+            context.metadata["local_source_transport"] = {
+                "kind": self._local_manifest["kind"],
+                "commit": self._local_manifest["commit"],
+                "tree": self._local_manifest["tree"],
+                "resolution_identity": self._local_manifest["resolution_identity"],
+                "payload_sha256": self._local_manifest["payload_sha256"],
+                "payload_bytes": self._local_manifest["payload_bytes"],
+                "status": "verified",
+            }
+        if self._artifact_manifest is not None:
+            context.metadata["harness_artifact_transport"] = {
+                "artifact_id": self._artifact_manifest["artifact_id"],
+                "artifact_integrity": self._artifact_manifest["artifact_integrity"],
+                "platform": self._artifact_manifest["platform"],
+                "status": "uploaded" if self._artifact_uploaded else "incompatible_platform_fallback",
+            }
         if execution.return_code != 0:
             message = (execution.stderr or "").strip()
             if hitch_result and hitch_result.get("error", {}).get("message"):
@@ -279,6 +677,80 @@ class HitchHarborAgent(BaseAgent):
                 f"expected {self.revision_identity}, got {hitch_result.get('revision_identity')}"
             )
 
+    def _trial_identity(self) -> tuple[str, str, int]:
+        """Read Harbor's stable trial/task identity from the persisted trial state."""
+        trial_dir = self.logs_dir.parent if self.logs_dir.name == "agent" else self.logs_dir
+        trial_id = trial_dir.name or "trial__1"
+        task_id = self._locked_task_id(trial_dir)
+        match = re.fullmatch(r"(.+)__(\d+)", trial_id)
+        if match:
+            return trial_id, task_id or match.group(1), max(1, int(match.group(2)))
+        # Harbor 0.21 uses a random seven-character suffix and truncates the
+        # task portion of trial_name. It therefore cannot be used to recover
+        # task identity; the trial lock above is authoritative. Keep the split
+        # only as a compatibility fallback for older/fake Harbor runtimes.
+        fallback_task_id = trial_id.rsplit("__", 1)[0] if "__" in trial_id else trial_id
+        return trial_id, task_id or fallback_task_id, 1
+
+    @staticmethod
+    def _locked_task_id(trial_dir: Path) -> str | None:
+        lock_path = trial_dir / "lock.json"
+        if not lock_path.is_file():
+            return None
+        try:
+            lock = json.loads(lock_path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as error:
+            raise RuntimeError(f"Harbor trial lock is unreadable: {lock_path}") from error
+        task = lock.get("task") if isinstance(lock, dict) else None
+        task_id = task.get("name") if isinstance(task, dict) else None
+        if not isinstance(task_id, str) or not task_id.strip():
+            raise RuntimeError(f"Harbor trial lock has no task.name: {lock_path}")
+        return task_id.strip()
+
+    def _temporary_json(self, prefix: str, value: dict[str, Any]) -> Path:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            prefix=prefix,
+            suffix=".json",
+            dir=self.logs_dir,
+            delete=False,
+        ) as handle:
+            json.dump(value, handle, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+            handle.write("\n")
+            return Path(handle.name)
+
+    async def _workspace_digest(self, environment: BaseEnvironment) -> str:
+        script = r"""
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const hash = crypto.createHash('sha256');
+function walk(root, relative = '') {
+  const directory = path.join(root, relative);
+  for (const name of fs.readdirSync(directory).sort()) {
+    const child = relative ? path.join(relative, name) : name;
+    const absolute = path.join(root, child);
+    const info = fs.lstatSync(absolute);
+    if (info.isDirectory()) { hash.update(`d\0${child}\0${info.mode & 0o7777}\0`); walk(root, child); }
+    else if (info.isFile()) { hash.update(`f\0${child}\0${info.mode & 0o7777}\0${info.size}\0`); hash.update(fs.readFileSync(absolute)); hash.update('\0'); }
+    else if (info.isSymbolicLink()) { hash.update(`l\0${child}\0${fs.readlinkSync(absolute)}\0`); }
+  }
+}
+walk(process.argv[1]);
+process.stdout.write('sha256:' + hash.digest('hex'));
+""".strip()
+        result = await environment.exec(
+            " ".join([self._node_prefix(), "node", "-e", shlex.quote(script), shlex.quote(self.workdir)]),
+            cwd=self.workdir,
+        )
+        digest = (result.stdout or "").strip()
+        if result.return_code == 0 and re.fullmatch(r"sha256:[0-9a-f]{64}", digest):
+            return digest
+        # Older/fake Harbor environments may not expose a readable workspace
+        # during bridge tests. Keep a deterministic, visibly synthetic input.
+        return "sha256:" + hashlib.sha256(b"workspace-unavailable").hexdigest()
+
     async def _ensure_node(self, environment: BaseEnvironment) -> None:
         probe = await environment.exec(
             "node -e 'process.exit(Number(process.versions.node.split(\".\")[0]) >= 22 ? 0 : 1)'"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hitch",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Content-addressed version control and evidence storage for agent harnesses",
   "keywords": [
     "ai-agents",
@@ -18,6 +18,23 @@
     "url": "git+https://github.com/rsi-gear/agent-hitch.git"
   },
   "type": "module",
+  "exports": {
+    "./adapters": "./dist/src/adapters/index.js",
+    "./artifacts": "./dist/src/artifacts/index.js",
+    "./backends": "./dist/src/backends/index.js",
+    "./controller-runtime": "./dist/src/controller-runtime/index.js",
+    "./daemon": "./dist/src/daemon/index.js",
+    "./domain": "./dist/src/domain/index.js",
+    "./evals": "./dist/src/evals/index.js",
+    "./feedback": "./dist/src/feedback/index.js",
+    "./foundation": "./dist/src/foundation/index.js",
+    "./revisions": "./dist/src/revisions/index.js",
+    "./runs": "./dist/src/runs/index.js",
+    "./trajectories": "./dist/src/trajectories/index.js",
+    "./workspaces": "./dist/src/workspaces/index.js",
+    "./cli": "./dist/src/cli/index.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "hitch": "dist/bin/hitch.js"
   },
@@ -30,10 +47,11 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "test": "node --test \"dist/test/*.test.js\"",
     "coverage": "node --experimental-test-coverage --test-coverage-include=dist/src/**/*.js --test-coverage-lines=75 --test-coverage-branches=65 --test-coverage-functions=70 --test \"dist/test/*.test.js\"",
-    "check": "npm run typecheck && npm run build && node dist/scripts/check-syntax.js && node --test \"dist/test/*.test.js\"",
+    "check:architecture": "node dist/scripts/check-architecture.js",
+    "check": "npm run typecheck && npm run build && npm run check:architecture && node dist/scripts/check-syntax.js && node --test \"dist/test/*.test.js\"",
     "prepublishOnly": "npm run check"
   },
   "engines": {