feat(lib): capture client-attested build provenance by max-parke-scale · Pull Request #454 · scaleapi/scale-agentex-python · GitHub

Adds agentex.lib.utils.build_provenance — the shared capture util for client-attested build provenance: git coordinates (repo/commit/ref/subpath), a deterministic working_tree_hash over the build inputs (not the tarball), a dirty flag (Go vcs.modified / Nix dirtyRev shape), and normalize_remote. Capture is best-effort and never raises into a build. Also makes the build archive’s member order deterministic via a sorted enumeration shared with the hash.

First of three surfaces for AGX1-418 (Phase 1, client-attested). Provenance is delivered via the build-record sink — source_* columns on POST /v5/builds (Surface C, scaleapi) consumed by the sgpctl + CI uploaders (Surface B, scaleapi/sgp). This PR lands the util + archive determinism where agentex.lib lives; the uploaders/columns follow.

Scope notes

No build-info.json / runtime sink. An earlier revision wrote build-info.json into the build context for the register_agent() → registration_metadata path. Greptile (T-Rex) correctly flagged it as dead-on-arrival (written to the archive root, which the templates’ Dockerfiles don’t COPY and locate_build_info_path() doesn’t read). It’s also redundant: AgentexCloudDeploy.build_id is an FK to AgentexCloudBuild, so a deployment’s source provenance derives from the build record over that join — the same Build→Deploy edge lineage already traverses. Dropped; can be revived (correctly placed) if a real consumer for deployment-history provenance ever appears.

Identity model

working_tree_hash is always computed (content identity); commit/ref/repo anchor it to source when in a git work tree; dirty records uncommitted changes (None outside git).

Tests

20 provenance unit tests (clean/dirty/untracked/detached-HEAD/no-remote/non-git/monorepo-subpath, hash determinism + one-byte/added/exec-bit/symlink sensitivity, and a never-raises-on-hash-failure guard). ruff/pyright clean; full lib suite green.

🧑‍💻🤖 — posted via Claude Code

Greptile Summary

Adds agentex.lib.utils.build_provenance — a best-effort utility that captures git coordinates, a deterministic working_tree_hash over the build context, and a dirty flag. The archive tarball in agent_manifest.py is updated to use the same sorted iter_context_files enumeration, ensuring member order matches the hash.

build_provenance.py: New module with BuildProvenance dataclass, capture_build_provenance entry point, normalize_remote, iter_context_files, and working_tree_hash. All error paths degrade gracefully via _safe_working_tree_hash and _git exception handling.
agent_manifest.py: Minimal change — replaces the inline rglob loop in BuildContextManager.zipped() with iter_context_files to share the deterministic sort with the hash.
Tests: 20 unit tests covering all major code paths; clean/dirty/detached/no-remote/non-git/monorepo, hash sensitivity properties, and the never-raises guard.

Confidence Score: 5/5

Safe to merge — provenance capture is fully best-effort, the tarball determinism change is a straightforward refactor, and the test coverage is comprehensive.

The two observations are minor: one method (build_info) has no callers yet, and one field key in source_fields() may have a naming inconsistency with the server API. Neither affects the correctness of the build pipeline or the provenance data Surface B will consume. The hash-failure and git-failure paths are both properly guarded.

Files Needing Attention: Confirm the working_tree_hash column name on POST /v5/builds against the Surface C spec before the Surface B uploaders land.

Important Files Changed

Filename	Overview
src/agentex/lib/utils/build_provenance.py	New module capturing git provenance (repo/commit/ref/subpath/dirty) and a deterministic content hash. Best-effort design is solid; _safe_working_tree_hash correctly wraps the hash path. Two minor issues: build_info() is dead code (no callers after build-info.json removal), and working_tree_hash key in source_fields() lacks the source_ prefix unlike all other keys.
src/agentex/lib/sdk/config/agent_manifest.py	Replaces the inline rglob loop with iter_context_files, making the archive member order deterministic and consistent with the hash computation. Change is minimal and correct.
tests/lib/test_build_provenance.py	20 well-structured unit tests covering clean/dirty/untracked/detached-HEAD/no-remote/non-git/monorepo-subpath, hash sensitivity (byte/file/exec-bit/symlink), and the never-raises guard. source_fields() and build_info() serialization methods are not directly exercised.

Reviews (8): Last reviewed commit: "Merge origin/next into maxparke/agx1-418..." | Re-trigger Greptile

Add agentex.lib.utils.build_provenance — the single producer of source identity for agent builds (git coordinates + a deterministic content hash of the build context). prepare_cloud_build_context now writes build-info.json into the staged context (populates runtime registration_metadata with no server change) and exposes provenance on CloudBuildContext so the upload can send source_* fields. Archive member order is now deterministic via a sorted enumeration shared with the hash. The hash is computed only when there is no clean commit to identify the build (dirty tree or non-git context). First of three surfaces for AGX1-418 (Phase 1, client-attested); the SGP build-record columns and the sgpctl/Gitea uploaders follow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Address Greptile review on the build-provenance capture util: - Always compute working_tree_hash (drop the "skip on clean commit" path). A `git status` clean tree can still contain .gitignore'd-but-not- .dockerignore'd files the commit can't reproduce; an always-present content hash identifies the exact shipped bytes and closes that gap. - Guard the hash (_safe_working_tree_hash) so a permission error or filesystem race degrades to None instead of aborting the build — the module contract is that capture never raises into a build. - Record dirtiness as a first-class `dirty` flag (surfaced as `source_dirty` / `dirty`) rather than overloading hash-presence, matching Go's vcs.modified and Nix's dirtyRev. None outside a git work tree. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Addressed both Greptile findings in cf9994d:

Ignored files lose hashing — fixed by removing the "skip hash on clean commit" path entirely: working_tree_hash is now always computed over the staged context, so a .gitignored-but-not-.dockerignored file is captured by the content hash regardless of git status. (Identity = the always-present hash; commit anchors it to source. Dedupe is unaffected since the hash is deterministic.)
Hash failures abort builds — wrapped the computation in _safe_working_tree_hash, which degrades to None and logs on any error, honoring the “capture never raises into a build” contract.

Also, per design discussion: dirtiness is now a first-class dirty flag (surfaced as source_dirty / dirty) rather than implied by hash-presence — matching Go’s vcs.modified and Nix’s dirtyRev; None outside a git work tree.

🧑‍💻🤖 — posted via Claude Code

Greptile (T-Rex repro) showed build-info.json was written to the archive root, which the templates' Dockerfiles don't COPY and the runtime locate_build_info_path() doesn't read — so it never reached the image and the registration_metadata sink stayed empty. Beyond the placement bug, the sink is redundant: AgentexCloudDeploy.build_id is an FK to AgentexCloudBuild, so a deployment's source provenance derives from the build record (the source_* columns this work adds, Surface C) over that join — the same Build->Deploy edge lineage already traverses. No need to denormalize provenance onto registration_metadata/DeploymentHistory (which has had no producer since its read path landed 2025-09, so its git fields have never been populated). #454 now ships only the shared capture util (agentex.lib.build_provenance) plus a deterministic build-archive ordering. Provenance is delivered via the build-record sink; the runtime sink can be revived (correctly placed) if a real consumer for deployment-history provenance ever appears. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ld-provenance-capture

#460) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…ld-provenance-capture # Conflicts: # uv.lock

…t in workflow templates

…ty trace (#465) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

One add/add conflict in obs_ids.py, which both branches created independently. Took next's side on both hunks: - `from typing import Dict, Tuple, Optional` — next's length-sorted order is what ruff's isort config wants here. This branch's alphabetical order was the I001 that had been failing the lint job, so resolving the conflict fixes it. - `from ddtrace.trace import tracer` — the path ddtrace exposes now, and the only form used elsewhere in the tree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/agentex-client@0.17.0 ⏵ 0.21.0	+1

View full report

…pping stale source The tutorial-agent build/publish pipeline could silently republish a stale image to the moving ':latest' tag. 'agentex agents build' invoked 'docker.buildx.build' with no cache control, so a cached layer could ship source that no longer matched the checkout -- e.g. the merged 'mcp<2' pin for the 020_state_machine agent never reached ':latest', leaving integration tests pulling a months-old image and failing on the mcp 2.0.0 'McpError' rename. - add a 'cache' param to build_agent() -> passes cache=False (buildx --no-cache) through to the build - expose '--cache/--no-cache' on 'agentex agents build' (default: cache on, so local dev and immutable SHA builds stay fast) - build-and-push-tutorial-agent.yml uses --no-cache only for the ':latest' publish path; SHA-tagged validation builds keep the cache Related: build-provenance work (#454) records a working-tree hash and could later provide a more surgical cache-key-based fix; this is the immediate, guaranteed prevention. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

max-parke-scale changed the base branch from main to next June 30, 2026 01:04

greptile-apps Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread src/agentex/lib/utils/build_provenance.py Outdated

Comment thread src/agentex/lib/utils/build_provenance.py Outdated

greptile-apps Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread src/agentex/lib/cli/handlers/agent_handlers.py Outdated

max-parke-scale and others added 2 commits June 29, 2026 22:32

Merge remote-tracking branch 'origin/next' into maxparke/agx1-418-bui…

904a7d5

…ld-provenance-capture

stainless-app Bot force-pushed the next branch from e855070 to 0afaae4 Compare July 10, 2026 17:46

NiteshDhanpal and others added 4 commits July 12, 2026 18:01

fix(tracing): capture span body exceptions and export SGP status=ERROR (

6c23d76

#460) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/next' into maxparke/agx1-418-bui…

22dc5b5

…ld-provenance-capture # Conflicts: # uv.lock

docs(lib): tighten provenance code comments

f42f436

Scope provenance dirtiness to build context

4fd94eb

stainless-app Bot force-pushed the next branch from 7d19ada to 90ca889 Compare July 14, 2026 21:29

stainless-app Bot added 3 commits July 17, 2026 17:23

feat(stlc): configurable CI runner and private-production-repo suppor…

23c1b6b

…t in workflow templates

codegen metadata

3c7015e

feat(api): add include_live parameter to schedules list method

199fd6a

max-parke-scale requested review from danielmillerp and declan-scale July 22, 2026 22:40

NiteshDhanpal and others added 3 commits July 23, 2026 23:18

[WIP] feat(tracing): correlate business spans with active observabili…

c67e177

…ty trace (#465) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

fix(api): remove params field from task list response

152bc75

Merge branch 'next' into maxparke/agx1-418-build-provenance-capture

bc44436

stainless-app Bot force-pushed the next branch from 0252fcc to 2b7649c Compare July 28, 2026 19:05

danielmillerp approved these changes Jul 29, 2026

View reviewed changes

max-parke-scale merged commit 8964044 into next Jul 29, 2026
48 checks passed

max-parke-scale deleted the maxparke/agx1-418-build-provenance-capture branch July 29, 2026 01:43

stainless-app Bot mentioned this pull request Jul 29, 2026

chore: release main #475

Merged

deepthi-rao-scale mentioned this pull request Jul 29, 2026

fix(lib): default 'agentex agents build' to --no-cache so stale layers can't ship stale source #476

Merged

feat(lib): capture client-attested build provenance by max-parke-scale · Pull Request #454 · scaleapi/scale-agentex-python · GitHub

Uh oh!

feat(lib): capture client-attested build provenance - #454

feat(lib): capture client-attested build provenance#454
max-parke-scale merged 15 commits into
nextfrom
maxparke/agx1-418-build-provenance-capture

max-parke-scale commented Jun 30, 2026 •
edited by greptile-apps Bot
Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

max-parke-scale commented Jun 30, 2026

Uh oh!

Uh oh!

socket-security Bot commented Jul 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(lib): capture client-attested build provenance by max-parke-scale · Pull Request #454 · scaleapi/scale-agentex-python · GitHub

Uh oh!

feat(lib): capture client-attested build provenance - #454

feat(lib): capture client-attested build provenance#454max-parke-scale merged 15 commits intonextscaleapi/scale-agentex-python:nextfrom maxparke/agx1-418-build-provenance-capturescaleapi/scale-agentex-python:maxparke/agx1-418-build-provenance-captureCopy head branch name to clipboard

Conversation

max-parke-scale commented Jun 30, 2026 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Scope notes

Identity model

Tests

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

max-parke-scale commented Jun 30, 2026

Uh oh!

Uh oh!

socket-security Bot commented Jul 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(lib): capture client-attested build provenance#454
max-parke-scale merged 15 commits into
nextfrom
maxparke/agx1-418-build-provenance-capture

max-parke-scale commented Jun 30, 2026 •
edited by greptile-apps Bot
Loading