Workflow: Explicit sandbox image semantics

[robbycochran]

Summary

Establish explicit semantics for sandbox image resolution in Harness workflows:

• Standardize image specification and override behavior across all execution contexts
• Define clear precedence order for image selection (environment → explicit → versioned defaults)
• Align with validated sandbox image architecture and Agent Runtime Contract (ARC)
• Enable migration path to standardized container images across agent ecosystem

Validation Status

• Branch created from main
• Commit cherry-picked to batch3-pr
• Git status clean (changes staged and committed)
• Documentation added to cmd/sandbox_image.go
• Push to origin successful
• No pre-commit hook failures
• Full integration tests pending
• Review and acceptance pending

Files Changed

1. cmd/sandbox_image.go (37 insertions)
   • Added comprehensive documentation to resolveSandboxImage() function
   • Explicit documentation of 3-level precedence order
   • Documentation of Agent Runtime Contract (ARC) requirements
   • Added documentation to versionedImage() with example outputs

Image Resolution Precedence

1. HARNESS_OS_IMAGE environment variable (highest priority)

   • Operator override for all contexts
   • Enables local development and CI debugging

2. spec.sandbox.image explicit field (workflow-level)

   • Per-workflow image override
   • Used when environment variable not set

3. versionedImage("sandbox") default (fallback)

   • Versioned base image reference
   • Ensures stable, reproducible defaults

Execution Context Support

The documented semantics support:

• Local OpenShell - uses active gateway, environment-based overrides
• HyperShell Personal - user-authenticated gateway, explicit image selection
• HyperShell Service-Account - constrained OIDC access, consistent image defaults

Risks & Mitigations

• Integration impact: Changes affect all sandbox execution contexts
  • Mitigation: Documentation makes precedence explicit; no behavior changes
• Backward compatibility: Existing image resolution must not change
  • Mitigation: Only added documentation, no code logic changes
• Registry access: Validated image migration depends on quay.io/redhat-ai availability
  • Mitigation: Current implementation uses quay.io/rcochran/openshell; can migrate later
• Cold-start timing: Thin-flavor architecture documentation may enable performance variance
  • Mitigation: ARC documents consistent runtime contract for all images

Not Included (Future Batches)

• Provider or model image overlays
• Image caching strategy optimization
• Registry authentication changes
• Agent-specific image defaults
• Inline secrets or credential handling
• Image build and distribution pipeline changes

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[robbycochran]

Superseded by #136, which consolidates this change (and the other three batch drafts) into a single PR against main.