Separate workflow helpers from release assets

Author: chubes4

.github/workflows/run-agent-task.yml

@@ -7,6 +7,10 @@ name: Run Agent Task (reusable)
         description: Exact immutable WP Codebox release tag used for this workflow invocation, in vX.Y.Z form.
         type: string
         required: true
+      wp_codebox_workflow_ref:
+        description: Optional full commit SHA for workflow helpers; defaults to wp_codebox_release_ref.
+        type: string
+        default: ""
       external_package_source:
         description: "JSON descriptor for exactly one standalone .agent.json file: repository, immutable revision, file path, and sha256-bytes-v1 digest."
         type: string
@@ -155,6 +159,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       WP_CODEBOX_RELEASE_REF: ${{ inputs.wp_codebox_release_ref }}
+      WP_CODEBOX_WORKFLOW_REF: ${{ inputs.wp_codebox_workflow_ref || inputs.wp_codebox_release_ref }}
     permissions:
       contents: write
       pull-requests: write
@@ -173,24 +178,31 @@ jobs:
             echo "wp_codebox_release_ref must be an immutable vX.Y.Z release tag" >&2
             exit 1
           fi
+          if ! [[ "${WP_CODEBOX_WORKFLOW_REF}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$|^[0-9a-f]{40}$ ]]; then
+            echo "wp_codebox_workflow_ref must be an immutable vX.Y.Z release tag or full commit SHA" >&2
+            exit 1
+          fi
 
       - name: Checkout WP Codebox workflow helpers
         uses: actions/checkout@v4
         with:
           repository: Automattic/wp-codebox
-          ref: ${{ inputs.wp_codebox_release_ref }}
+          ref: ${{ inputs.wp_codebox_workflow_ref || inputs.wp_codebox_release_ref }}
           path: .wp-codebox-workflow
 
-      - name: Verify WP Codebox workflow helper release
+      - name: Verify WP Codebox workflow helper revision
         working-directory: .wp-codebox-workflow
         run: |
-          git ls-remote --exit-code --refs origin "refs/tags/${WP_CODEBOX_RELEASE_REF}" >/dev/null
-          remote_tag_object="$(git ls-remote --refs origin "refs/tags/${WP_CODEBOX_RELEASE_REF}" | cut -f1)"
-          remote_tag_commit="$(git ls-remote origin "refs/tags/${WP_CODEBOX_RELEASE_REF}^{}" | cut -f1)"
-          remote_tag_commit="${remote_tag_commit:-${remote_tag_object}}"
           checked_out_commit="$(git rev-parse HEAD)"
-          if [[ "${checked_out_commit}" != "${remote_tag_commit}" ]]; then
-            echo "Checked-out WP Codebox helpers do not match the remote release tag commit" >&2
+          expected_helper_commit="${WP_CODEBOX_WORKFLOW_REF}"
+          if [[ "${WP_CODEBOX_WORKFLOW_REF}" == v* ]]; then
+            git ls-remote --exit-code --refs origin "refs/tags/${WP_CODEBOX_WORKFLOW_REF}" >/dev/null
+            remote_tag_object="$(git ls-remote --refs origin "refs/tags/${WP_CODEBOX_WORKFLOW_REF}" | cut -f1)"
+            remote_tag_commit="$(git ls-remote origin "refs/tags/${WP_CODEBOX_WORKFLOW_REF}^{}" | cut -f1)"
+            expected_helper_commit="${remote_tag_commit:-${remote_tag_object}}"
+          fi
+          if [[ "${checked_out_commit}" != "${expected_helper_commit}" ]]; then
+            echo "Checked-out WP Codebox helpers do not match wp_codebox_workflow_ref" >&2
             exit 1
           fi
           EXPECTED_VERSION="${WP_CODEBOX_RELEASE_REF#v}" node --input-type=module -e '

contracts/run-agent-task-reusable-workflow-interface.v1.json

@@ -3,6 +3,7 @@
   "workflow": ".github/workflows/run-agent-task.yml",
   "inputs": {
     "wp_codebox_release_ref": { "required": true, "type": "string" },
+    "wp_codebox_workflow_ref": { "required": false, "type": "string", "default": "" },
     "external_package_source": { "required": true, "type": "string" },
     "runtime_sources": { "required": false, "type": "string", "default": "[]" },
     "workload_id": { "required": false, "type": "string", "default": "agent-task" },

docs/agent-task-reusable-workflow.md

@@ -31,19 +31,22 @@ public native package, invokes the package-declared agent through the native cha
 in a credential-free verification environment, and returns actual runtime and
 publication data.
 
-## Helper Release Tag
+## Helper Revision
 
-Callers must invoke the reusable workflow from an exact WP Codebox release tag
+By default, callers invoke the reusable workflow from an exact WP Codebox release tag
 and pass that same tag as `wp_codebox_release_ref`. For example, callers use
 `Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.3` together
 with `wp_codebox_release_ref: v0.12.3`. The accepted format is exactly
 `vX.Y.Z`; branches, commit SHAs, moving major tags, prereleases, and arbitrary
-refs are rejected.
-
-The workflow requires `wp_codebox_release_ref` to be an exact release tag. It
-always checks helpers out from `Automattic/wp-codebox`, verifies the checked-out
-commit equals the remote release tag commit, and verifies the checked-out
-`package.json` version equals the requested tag without its `v` prefix. The
+refs are rejected for the packaged release.
+
+The workflow requires `wp_codebox_release_ref` to be an exact release tag. An
+accepted workflow commit may also pass the same full SHA as `wp_codebox_workflow_ref`
+to execute helper changes independently of packaged runtime assets. When omitted,
+the helper ref defaults to the release tag. The workflow checks helpers out from
+`Automattic/wp-codebox`, verifies the checked-out commit equals the selected helper
+revision, and verifies the checked-out `package.json` version equals the requested
+release tag without its `v` prefix. The
 caller cannot select a different helper repository. GitHub nested workflows
 expose the caller's `github.workflow_ref`, and the running workflow cannot
 introspect its own `uses:` ref, so helper selection relies on the required input
@@ -54,6 +57,7 @@ This release-coherence contract fixes [#1759](https://github.com/Automattic/wp-c
 ## Inputs
 
 - `wp_codebox_release_ref`: required exact immutable WP Codebox release tag in `vX.Y.Z` form.
+- `wp_codebox_workflow_ref`: optional full immutable helper commit SHA. It defaults to `wp_codebox_release_ref` for existing callers.
 - `external_package_source`: immutable descriptor with `repository`, full commit `revision`, one package-relative `.agent.json` `path`, and `digest`. Packages are supported only from publicly accessible GitHub repositories, fetched from canonical `https://github.com/OWNER/REPOSITORY.git` without credentials. `digest` is exactly `sha256-bytes-v1:<lowercase-sha256>` over the raw file bytes; filenames and JSON content are UTF-8-safe and are not normalized before hashing.
 - `EXTERNAL_PACKAGE_SOURCE_POLICY`: required reusable-workflow secret, supplied by the caller's operator-controlled secret configuration. Its strict version 1 JSON shape is `{"version":1,"repositories":{"owner/repository":["agents/example.agent.json"]}}`. Every entry is an exact standalone `.agent.json` path. The policy is validated in runner memory, is never part of task input, and is not uploaded.
 

tests/agent-task-reusable-workflow.test.ts

@@ -15,6 +15,7 @@ const publicWorkflowSurface = workflow.slice(0, workflow.indexOf("jobs:"))
 assert.match(workflow, /^name: Run Agent Task \(reusable\)$/m)
 assert.match(workflow, /workflow_call:/)
 assert.match(workflow, /wp_codebox_release_ref:/)
+assert.match(workflow, /wp_codebox_workflow_ref:/)
 assert.match(workflow, /external_package_source:/)
 assert.match(workflow, /runtime_sources:/)
 assert.match(workflow, /EXTERNAL_PACKAGE_SOURCE_POLICY:/)
@@ -43,25 +44,29 @@ assert.match(workflow, /prepare-agent-task-upload\.mjs/)
 assert.match(workflow, /agent-task-upload/)
 assert.match(workflow, /if: always\(\)/)
 assert.match(workflow, /WP_CODEBOX_RELEASE_REF: \$\{\{ inputs\.wp_codebox_release_ref \}\}/)
+assert.match(workflow, /WP_CODEBOX_WORKFLOW_REF: \$\{\{ inputs\.wp_codebox_workflow_ref \|\| inputs\.wp_codebox_release_ref \}\}/)
 assert.match(workflow, /\^v\[0-9\]\+\\\.\[0-9\]\+\\\.\[0-9\]\+\$/)
-assert.doesNotMatch(workflow, /github\.workflow_ref|WORKFLOW_REF|expected_workflow_ref/)
+assert.doesNotMatch(workflow, /github\.workflow_ref|expected_workflow_ref/)
 assert.match(workflow, /repository: Automattic\/wp-codebox/)
-assert.match(workflow, /ref: \$\{\{ inputs\.wp_codebox_release_ref \}\}/)
-assert.match(workflow, /Verify WP Codebox workflow helper release/)
-assert.match(workflow, /git ls-remote --exit-code --refs origin "refs\/tags\/\$\{WP_CODEBOX_RELEASE_REF\}"/)
-assert.match(workflow, /checked_out_commit.*remote_tag_commit/)
+assert.match(workflow, /ref: \$\{\{ inputs\.wp_codebox_workflow_ref \|\| inputs\.wp_codebox_release_ref \}\}/)
+assert.match(workflow, /Verify WP Codebox workflow helper revision/)
+assert.match(workflow, /git ls-remote --exit-code --refs origin "refs\/tags\/\$\{WP_CODEBOX_WORKFLOW_REF\}"/)
+assert.match(workflow, /checked_out_commit.*expected_helper_commit/)
 assert.match(workflow, /JSON\.parse\(readFileSync\("package\.json", "utf8"\)\)\.version/)
 assert.doesNotMatch(workflow, /steps\.[^.]+\.outputs\.ref/)
 assert.match(workflow, /Validate WP Codebox release tag/)
 
-const parseConsumerReleaseTags = (consumer: string) => ({
+const parseConsumerRefs = (consumer: string) => ({
   workflow: consumer.match(/uses: Automattic\/wp-codebox\/\.github\/workflows\/run-agent-task\.yml@([^\s]+)/)?.[1],
-  helpers: consumer.match(/wp_codebox_release_ref: ([^\s]+)/)?.[1],
+  release: consumer.match(/wp_codebox_release_ref: ([^\s]+)/)?.[1],
+  helpers: consumer.match(/wp_codebox_workflow_ref: ([^\s]+)/)?.[1],
 })
 const isExactReleaseTag = (value: string | undefined) => /^v\d+\.\d+\.\d+$/.test(value ?? "")
+const isFullCommit = (value: string | undefined) => /^[0-9a-f]{40}$/.test(value ?? "")
 const isCoherentConsumer = (consumer: string) => {
-  const { workflow: workflowTag, helpers: helperTag } = parseConsumerReleaseTags(consumer)
-  return isExactReleaseTag(workflowTag) && workflowTag === helperTag
+  const { workflow: workflowRef, release, helpers } = parseConsumerRefs(consumer)
+  if (!isExactReleaseTag(release)) return false
+  return helpers ? isFullCommit(workflowRef) && workflowRef === helpers : workflowRef === release
 }
 const coherentConsumer = await readFile(new URL("../fixtures/agent-task-reusable-workflow-consumer.yml", import.meta.url), "utf8")
 const mismatchedConsumer = await readFile(new URL("../fixtures/agent-task-reusable-workflow-consumer-mismatched.yml", import.meta.url), "utf8")
@@ -70,6 +75,8 @@ assert.equal(isCoherentConsumer(coherentConsumer), true, "An exact matching work
 assert.equal(isCoherentConsumer(mismatchedConsumer), false, "Mismatched workflow and helper release tags must fail")
 assert.match(buildRunConsumer, /github\.workflow_ref: Automattic\/build-with-wordpress\/\.github\/workflows\/build\.yml@trunk/)
 assert.equal(isCoherentConsumer(buildRunConsumer), true, "A foreign caller workflow_ref must not affect the paired release tags")
+const commit = "0123456789abcdef0123456789abcdef01234567"
+assert.equal(isCoherentConsumer(`uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@${commit}\nwith:\n  wp_codebox_release_ref: v0.12.29\n  wp_codebox_workflow_ref: ${commit}\n`), true, "An accepted workflow commit may provide helpers independently of packaged release assets")
 for (const invalidRef of ["main", "v0", "v0.12", "v0.12.3-rc.1", "0123456789abcdef0123456789abcdef01234567"]) {
   assert.equal(isExactReleaseTag(invalidRef), false, `Non-release ref must fail: ${invalidRef}`)
 }