feat(lib): capture client-attested build provenance

src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py

@@ -15,6 +15,7 @@
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.core.observability import tracing_metrics_recording as _metrics
 from agentex.lib.environment_variables import EnvironmentVariables
+from agentex.lib.core.tracing.span_error import get_span_error
 from agentex.lib.core.tracing.processors.tracing_processor_interface import (
     SyncTracingProcessor,
     AsyncTracingProcessor,
@@ -83,6 +84,9 @@ def _build_sgp_span(span: Span, env_vars: EnvironmentVariables) -> SGPSpan:
         ),
     )
     sgp_span.start_time = span.start_time.isoformat()  # type: ignore[union-attr]
+    error = get_span_error(span)
+    if error is not None:
+        sgp_span.set_error(error_type=error["type"], error_message=error["message"])
     return sgp_span
 
 

src/agentex/lib/core/tracing/span_error.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agentex.types.span import Span
+
+# Reserved key under ``Span.data`` carrying failure info for a span whose
+# context-manager body raised. Mirrors the existing ``__span_type__`` /
+# ``__source__`` reserved-key convention already read/written by the SGP
+# processor. Stored in ``data`` because the Span model is generated from the
+# OpenAPI spec and has no first-class status/error field; ``data`` is a real
+# field, so it survives ``model_copy(deep=True)`` and round-trips to both the
+# SGP and agentex-native span stores.
+SPAN_ERROR_KEY = "__error__"
+
+
+def set_span_error(span: Span, exc: BaseException) -> None:
+    """Record an exception on ``span`` under ``data[SPAN_ERROR_KEY]``.
+
+    No-op when ``span.data`` is a list (matching ``_add_source_to_span``, which
+    only attaches metadata to dict-shaped data).
+    """
+    error = {"type": type(exc).__name__, "message": str(exc)}
+    if span.data is None:
+        span.data = {}
+    if isinstance(span.data, dict):
+        span.data[SPAN_ERROR_KEY] = error
+
+
+def get_span_error(span: Span) -> dict[str, Any] | None:
+    """Return the error recorded by :func:`set_span_error`, or ``None``."""
+    if isinstance(span.data, dict):
+        value = span.data.get(SPAN_ERROR_KEY)
+        if isinstance(value, dict):
+            return value
+    return None

src/agentex/lib/core/tracing/trace.py

@@ -11,6 +11,7 @@
 from agentex.types.span import Span
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.model_utils import recursive_model_dump
+from agentex.lib.core.tracing.span_error import set_span_error
 from agentex.lib.core.tracing.span_queue import (
     SpanEventType,
     AsyncSpanQueue,
@@ -165,6 +166,9 @@ def span(
         span = self.start_span(name, parent_id, input, data, task_id=task_id)
         try:
             yield span
+        except Exception as exc:
+            set_span_error(span, exc)
+            raise
         finally:
             self.end_span(span)
 
@@ -321,5 +325,8 @@ async def span(
         span = await self.start_span(name, parent_id, input, data, task_id=task_id)
         try:
             yield span
+        except Exception as exc:
+            set_span_error(span, exc)
+            raise
         finally:
             await self.end_span(span)

src/agentex/lib/sdk/config/agent_manifest.py

@@ -24,6 +24,7 @@
 from agentex.lib.utils.io import load_yaml_file
 from agentex.lib.utils.logging import make_logger
 from agentex.config.agent_manifest import AgentManifest  # noqa: F401
+from agentex.lib.utils.build_provenance import iter_context_files
 
 logger = make_logger(__name__)
 
@@ -189,12 +190,11 @@ def zipped(root_path: Path | None = None) -> Iterator[IO[bytes]]:
 
         tar_buffer = io.BytesIO()
 
+        # Sorted, relpath-stable enumeration (shared with the content hash) so the
+        # archive's member order is deterministic across machines.
         with tarfile.open(fileobj=tar_buffer, mode="w:gz") as tar_file:
-            for path in Path(root_path).rglob(
-                "*"
-            ):  # Recursively add files to the tar.gz
-                if path.is_file():  # Ensure that we're only adding files
-                    tar_file.add(path, arcname=path.relative_to(root_path))
+            for path in iter_context_files(Path(root_path)):
+                tar_file.add(path, arcname=path.relative_to(root_path))
 
         tar_buffer.seek(0)  # Reset the buffer position to the beginning
         yield tar_buffer

src/agentex/lib/utils/build_provenance.py

@@ -0,0 +1,189 @@
+"""Capture client-attested source identity without failing agent builds."""
+
+from __future__ import annotations
+
+import os
+import stat
+import hashlib
+import subprocess
+from typing import Optional
+from pathlib import Path
+from datetime import datetime, timezone
+from dataclasses import dataclass
+
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+_GIT_TIMEOUT_S = 5
+_HASH_CHUNK_BYTES = 1 << 20
+
+
+@dataclass(frozen=True)
+class BuildProvenance:
+    """Source identity for one build; unavailable fields degrade to ``None``."""
+
+    repo: Optional[str] = None
+    commit: Optional[str] = None
+    ref: Optional[str] = None
+    subpath: Optional[str] = None
+    working_tree_hash: Optional[str] = None
+    dirty: Optional[bool] = None
+    author_name: Optional[str] = None
+    author_email: Optional[str] = None
+    build_timestamp: Optional[str] = None
+
+    def source_fields(self) -> dict[str, object]:
+        """The ``source_*`` form fields for the cloud-build upload (None omitted)."""
+        fields = {
+            "source_repo": self.repo,
+            "source_commit": self.commit,
+            "source_ref": self.ref,
+            "source_subpath": self.subpath,
+            "working_tree_hash": self.working_tree_hash,
+            "source_dirty": self.dirty,
+        }
+        return {key: value for key, value in fields.items() if value is not None}
+
+    def build_info(self) -> dict[str, object]:
+        """Return provenance using the runtime registration metadata field names."""
+        info = {
+            "repo": self.repo,
+            "commit_hash": self.commit,
+            "branch_name": self.ref,
+            "subpath": self.subpath,
+            "working_tree_hash": self.working_tree_hash,
+            "dirty": self.dirty,
+            "author_name": self.author_name,
+            "author_email": self.author_email,
+            "build_timestamp": self.build_timestamp,
+        }
+        return {key: value for key, value in info.items() if value is not None}
+
+
+def _git(repo_root: Path, *args: str) -> Optional[str]:
+    """Run a git command under ``repo_root``; return stripped stdout or None."""
+    try:
+        proc = subprocess.run(
+            ("git", "-C", str(repo_root), *args),
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None
+
+
+def normalize_remote(url: Optional[str]) -> Optional[str]:
+    """Strip credentials and scheme from a remote, returning ``host/path``."""
+    if not url:
+        return None
+    candidate = url.strip()
+    # scp-like syntax: git@host:org/repo(.git) — no scheme, host/path split on ':'
+    if "://" not in candidate and ":" in candidate and "/" not in candidate.split(":", 1)[0]:
+        candidate = candidate.split("@", 1)[-1].replace(":", "/", 1)
+    else:
+        if "://" in candidate:
+            candidate = candidate.split("://", 1)[1]
+        candidate = candidate.split("@", 1)[-1]
+    if candidate.endswith(".git"):
+        candidate = candidate[: -len(".git")]
+    candidate = candidate.strip("/")
+    if not candidate:
+        return None
+    host, slash, path = candidate.partition("/")
+    return f"{host.lower()}{slash}{path}"
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        while chunk := handle.read(_HASH_CHUNK_BYTES):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def iter_context_files(root: Path) -> list[Path]:
+    """Return files and symlinks under ``root``, sorted by POSIX relative path."""
+    return sorted(
+        (path for path in root.rglob("*") if path.is_symlink() or path.is_file()),
+        key=lambda path: path.relative_to(root).as_posix(),
+    )
+
+
+def working_tree_hash(root: Path) -> str:
+    """Hash sorted build inputs, normalized modes, and symlink target strings."""
+    lines: list[str] = []
+    for path in iter_context_files(root):
+        relpath = path.relative_to(root).as_posix()
+        if path.is_symlink():
+            mode = "120000"
+            content_digest = hashlib.sha256(os.readlink(path).encode("utf-8")).hexdigest()
+        else:
+            executable = bool(path.stat().st_mode & stat.S_IXUSR)
+            mode = "100755" if executable else "100644"
+            content_digest = _sha256_file(path)
+        lines.append(f"{relpath}\x00{mode}\x00{content_digest}")
+    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+def _safe_working_tree_hash(root: Path) -> Optional[str]:
+    """Compute the context hash without allowing capture to fail a build."""
+    try:
+        return working_tree_hash(root)
+    except Exception:
+        logger.warning("build-provenance: content hash failed; omitting", exc_info=True)
+        return None
+
+
+def capture_build_provenance(
+    repo_path: Path, context_root: Path, content_root: Optional[Path] = None
+) -> BuildProvenance:
+    """Capture git coordinates and the staged build-context hash."""
+    timestamp = datetime.now(timezone.utc).isoformat()
+    hash_root = content_root if content_root is not None else context_root
+    tree_hash = _safe_working_tree_hash(hash_root)
+
+    repo_root = _git(repo_path, "rev-parse", "--show-toplevel")
+    if repo_root is None:
+        # No git — the content hash is the only identity available.
+        logger.info("build-provenance: %s is not a git work tree; content hash only", repo_path)
+        return BuildProvenance(working_tree_hash=tree_hash, build_timestamp=timestamp)
+
+    repo_root_path = Path(repo_root)
+    commit = _git(repo_root_path, "rev-parse", "HEAD")
+    # symbolic-ref fails on a detached HEAD (→ None); fall back to an exact tag.
+    ref = _git(repo_root_path, "symbolic-ref", "--short", "HEAD") or _git(
+        repo_root_path, "describe", "--tags", "--exact-match"
+    )
+    remote = normalize_remote(_git(repo_root_path, "remote", "get-url", "origin"))
+    author_name = _git(repo_root_path, "log", "-1", "--format=%an")
+    author_email = _git(repo_root_path, "log", "-1", "--format=%ae")
+
+    subpath: Optional[str] = None
+    try:
+        relative = context_root.resolve().relative_to(repo_root_path.resolve()).as_posix()
+        subpath = relative if relative != "." else None
+    except ValueError:
+        subpath = None
+
+    status_args = ("status", "--porcelain")
+    if subpath is not None:
+        status_args += ("--", subpath)
+    dirty = _git(repo_root_path, *status_args) is not None
+
+    return BuildProvenance(
+        repo=remote,
+        commit=commit,
+        ref=ref,
+        subpath=subpath,
+        working_tree_hash=tree_hash,
+        dirty=dirty,
+        author_name=author_name,
+        author_email=author_email,
+        build_timestamp=timestamp,
+    )