run-agent-task.yml

name: Run Agent Task (reusable)

'on':
  workflow_call:
    inputs:
      wp_codebox_release_ref:
        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
        required: true
      runtime_sources:
        description: Versioned JSON array of trusted immutable public runtime source descriptors.
        type: string
        default: '[]'
      workload_id:
        description: Stable workload identifier for this run.
        type: string
        default: agent-task
      workload_label:
        description: Human-readable workload label for logs and review artifacts.
        type: string
        default: Run Agent Task
      component_id:
        description: Caller-owned component identifier for traceability.
        type: string
        default: agent-task
      target_repo:
        description: Target repository in OWNER/REPO format.
        type: string
        required: true
      prompt:
        description: Task instruction supplied to the selected agent bundle.
        type: string
        required: true
      writable_paths:
        description: Comma-separated repository paths the agent may edit.
        type: string
        default: ""
      provider:
        description: Model provider id selected by the caller.
        type: string
        default: openai
      model:
        description: Model id selected by the caller.
        type: string
        default: gpt-5.5
      runner_workspace:
        description: JSON runner-owned workspace publication request.
        type: string
        default: '{}'
      validation_dependencies:
        description: Optional validation dependency install command.
        type: string
        default: ""
      verification_commands:
        description: JSON array of verification commands to run after agent changes.
        type: string
        default: '[]'
      drift_checks:
        description: JSON array of drift checks for generated outputs.
        type: string
        default: '[]'
      success_requires_pr:
        description: Whether success requires a published pull request.
        type: boolean
        default: false
      access_token_repos:
        description: Comma-separated repositories for access-token scoping.
        type: string
        default: ""
      allowed_repos:
        description: JSON array of repositories the run may access.
        type: string
        default: '[]'
      max_turns:
        description: Maximum agent turns for the run.
        type: number
        default: 12
      time_budget_ms:
        description: Run time budget in milliseconds.
        type: number
        default: 600000
      output_projections:
        description: JSON object mapping workflow output names to paths or {path,required} descriptors.
        type: string
        default: '{}'
      transcript_artifact_name:
        description: Name for the transcript artifact.
        type: string
        default: agent-task-transcript
      replay_bundle_artifact_name:
        description: Optional name for the replay bundle artifact.
        type: string
        default: ""
      expected_artifacts:
        description: JSON array of expected artifact names used for collection; required outputs come from artifact_declarations.required.
        type: string
        default: '[]'
      artifact_declarations:
        description: JSON array of typed artifact declarations.
        type: string
        default: '[]'
      callback_data:
        description: JSON object passed through to the native task.
        type: string
        default: '{}'
      run_agent:
        description: When false, validate and report a skipped run.
        type: boolean
        default: true
      dry_run:
        description: Validate the task request without starting a live agent run.
        type: boolean
        default: false
    secrets:
      OPENAI_API_KEY:
        required: false
      MODEL_PROVIDER_SECRET_1:
        required: false
      MODEL_PROVIDER_SECRET_2:
        required: false
      MODEL_PROVIDER_SECRET_3:
        required: false
      MODEL_PROVIDER_SECRET_4:
        required: false
      MODEL_PROVIDER_SECRET_5:
        required: false
      ACCESS_TOKEN:
        description: Optional explicit GitHub token for an authorized cross-repository target. Same-repository publication uses the caller token.
        required: false
      EXTERNAL_PACKAGE_SOURCE_POLICY:
        description: Trusted versioned JSON policy authorizing external native package repositories and exact standalone .agent.json paths.
        required: true
    outputs:
      job_status:
        value: ${{ jobs.run-agent-task.outputs.job_status }}
      transcript_json:
        value: ${{ jobs.run-agent-task.outputs.transcript_json }}
      transcript_summary:
        value: ${{ jobs.run-agent-task.outputs.transcript_summary }}
      engine_data_json:
        value: ${{ jobs.run-agent-task.outputs.engine_data_json }}
      projected_outputs_json:
        value: ${{ jobs.run-agent-task.outputs.projected_outputs_json }}
      credential_mode:
        value: ${{ jobs.run-agent-task.outputs.credential_mode }}
      declared_artifacts_json:
        value: ${{ jobs.run-agent-task.outputs.declared_artifacts_json }}

jobs:
  run-agent-task:
    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
    outputs:
      job_status: ${{ steps.execute.outputs.job_status }}
      transcript_json: ${{ steps.execute.outputs.transcript_json }}
      transcript_summary: ${{ steps.execute.outputs.transcript_summary }}
      engine_data_json: ${{ steps.execute.outputs.engine_data_json }}
      projected_outputs_json: ${{ steps.execute.outputs.projected_outputs_json }}
      credential_mode: ${{ steps.execute.outputs.credential_mode }}
      declared_artifacts_json: ${{ steps.execute.outputs.declared_artifacts_json }}
    steps:
      - name: Validate WP Codebox release tag
        run: |
          if ! [[ "${WP_CODEBOX_RELEASE_REF}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            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_workflow_ref || inputs.wp_codebox_release_ref }}
          path: .wp-codebox-workflow

      - name: Verify WP Codebox workflow helper revision
        working-directory: .wp-codebox-workflow
        run: |
          checked_out_commit="$(git rev-parse HEAD)"
          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 '
            import { readFileSync } from "node:fs";
            const expected = process.env.EXPECTED_VERSION;
            const actual = JSON.parse(readFileSync("package.json", "utf8")).version;
            if (actual !== expected) {
              throw new Error("WP Codebox helper package version " + actual + " does not match release tag v" + expected);
            }
          '

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install WP Codebox runtime
        working-directory: .wp-codebox-workflow
        run: npm ci

      - name: Checkout target workspace
        uses: actions/checkout@v4
        with:
          repository: ${{ inputs.target_repo }}
          path: workspace
          token: ${{ secrets.ACCESS_TOKEN || github.token }}
          persist-credentials: false

      - name: Build Codebox task request
        id: plan
        env:
          EXTERNAL_PACKAGE_SOURCE: ${{ inputs.external_package_source }}
          RUNTIME_SOURCES: ${{ inputs.runtime_sources }}
          EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.EXTERNAL_PACKAGE_SOURCE_POLICY }}
          WORKLOAD_ID: ${{ inputs.workload_id }}
          WORKLOAD_LABEL: ${{ inputs.workload_label }}
          COMPONENT_ID: ${{ inputs.component_id }}
          TARGET_REPO: ${{ inputs.target_repo }}
          CALLER_REPO: ${{ github.repository }}
          PROMPT: ${{ inputs.prompt }}
          WRITABLE_PATHS: ${{ inputs.writable_paths }}
          PROVIDER: ${{ inputs.provider }}
          MODEL: ${{ inputs.model }}
          # Not `RUNNER_WORKSPACE`: that name is a reserved GitHub Actions
          # built-in (the `RUNNER_` prefix cannot be overridden), so a workflow
          # value set under it is ignored and the script receives the runner's
          # workspace path instead of this JSON config.
          RUNNER_WORKSPACE_CONFIG: ${{ inputs.runner_workspace }}
          VALIDATION_DEPENDENCIES: ${{ inputs.validation_dependencies }}
          VERIFICATION_COMMANDS: ${{ inputs.verification_commands }}
          DRIFT_CHECKS: ${{ inputs.drift_checks }}
          SUCCESS_REQUIRES_PR: ${{ inputs.success_requires_pr }}
          ACCESS_TOKEN_REPOS: ${{ inputs.access_token_repos }}
          ALLOWED_REPOS: ${{ inputs.allowed_repos }}
          MAX_TURNS: ${{ inputs.max_turns }}
          TIME_BUDGET_MS: ${{ inputs.time_budget_ms }}
          OUTPUT_PROJECTIONS: ${{ inputs.output_projections }}
          TRANSCRIPT_ARTIFACT_NAME: ${{ inputs.transcript_artifact_name }}
          REPLAY_BUNDLE_ARTIFACT_NAME: ${{ inputs.replay_bundle_artifact_name }}
          EXPECTED_ARTIFACTS: ${{ inputs.expected_artifacts }}
          ARTIFACT_DECLARATIONS: ${{ inputs.artifact_declarations }}
          CALLBACK_DATA: ${{ inputs.callback_data }}
          RUN_AGENT: ${{ inputs.run_agent }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: node .wp-codebox-workflow/.github/scripts/run-agent-task/build-codebox-task-request.mjs

      - name: Execute native agent task
        id: execute
        env:
          AGENT_TASK_REQUEST_PATH: ${{ github.workspace }}/.codebox/agent-task-request.json
          AGENT_TASK_WORKSPACE: ${{ github.workspace }}/workspace
          WP_CODEBOX_WORKFLOW_ROOT: ${{ github.workspace }}/.wp-codebox-workflow
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          MODEL_PROVIDER_SECRET_1: ${{ secrets.MODEL_PROVIDER_SECRET_1 }}
          MODEL_PROVIDER_SECRET_2: ${{ secrets.MODEL_PROVIDER_SECRET_2 }}
          MODEL_PROVIDER_SECRET_3: ${{ secrets.MODEL_PROVIDER_SECRET_3 }}
          MODEL_PROVIDER_SECRET_4: ${{ secrets.MODEL_PROVIDER_SECRET_4 }}
          MODEL_PROVIDER_SECRET_5: ${{ secrets.MODEL_PROVIDER_SECRET_5 }}
          # Runner workspace tools resolve GitHub credentials from this standard
          # environment variable. It is never written to task inputs or artifacts.
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN || github.token }}
          EXPLICIT_ACCESS_TOKEN_CONFIGURED: ${{ secrets.ACCESS_TOKEN != '' }}
          EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.EXTERNAL_PACKAGE_SOURCE_POLICY }}
        run: node .wp-codebox-workflow/.github/scripts/run-agent-task/execute-native-agent-task.mjs

      - name: Prepare Codebox task uploads
        if: always()
        run: node .wp-codebox-workflow/.github/scripts/run-agent-task/prepare-agent-task-upload.mjs
        env:
          AGENT_TASK_WORKSPACE: ${{ github.workspace }}/workspace
          AGENT_TASK_REQUEST_PATH: ${{ github.workspace }}/.codebox/agent-task-request.json
          AGENT_TASK_UPLOAD_PATH: ${{ github.workspace }}/workspace/.codebox/agent-task-upload
          WP_CODEBOX_RUNTIME_SOURCE_PREFIX: ${{ runner.temp }}/wp-codebox-runtime-sources-
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          MODEL_PROVIDER_SECRET_1: ${{ secrets.MODEL_PROVIDER_SECRET_1 }}
          MODEL_PROVIDER_SECRET_2: ${{ secrets.MODEL_PROVIDER_SECRET_2 }}
          MODEL_PROVIDER_SECRET_3: ${{ secrets.MODEL_PROVIDER_SECRET_3 }}
          MODEL_PROVIDER_SECRET_4: ${{ secrets.MODEL_PROVIDER_SECRET_4 }}
          MODEL_PROVIDER_SECRET_5: ${{ secrets.MODEL_PROVIDER_SECRET_5 }}
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN || github.token }}
          EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.EXTERNAL_PACKAGE_SOURCE_POLICY }}

      - name: Upload Codebox task request
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: codebox-agent-task-request-${{ github.run_id }}
          path: |
            workspace/.codebox/agent-task-upload
          include-hidden-files: true

      - name: Upload Codebox task result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: codebox-agent-task-result-${{ github.run_id }}
          path: |
            workspace/.codebox/agent-task-upload
          if-no-files-found: ignore
          include-hidden-files: true