feat(agentic-shared-framework): resolve consumer apm.yml per gh-aw invocation via aw-resolve-apm-assets

.github/workflows/aw-prelude.yml

@@ -2,6 +2,7 @@ name: Agentic Workflow Prelude
 
 # Shared dashboard gating and optional allow-list loading for *-aw-* workflows.
 # Call this reusable workflow before agent-specific jobs in oblt-aw-* and docs-aw-* wrappers.
+# APM asset resolution lives in aw-resolve-apm-assets.yml (per gh-aw-* invocation).
 on:
   workflow_call:
     inputs:
@@ -77,6 +78,7 @@ jobs:
     timeout-minutes: 2
     outputs:
       proceed: ${{ steps.gate.outputs.proceed }}
+      compound-workflow-id: ${{ steps.resolve.outputs.compound-workflow-id }}
       allowed-pr-authors-json: ${{ steps.pack.outputs.allowed-pr-authors-json }}
       allowed-pr-authors-csv: ${{ steps.pack.outputs.allowed-pr-authors-csv }}
       allowed-issue-authors-json: ${{ steps.pack.outputs.allowed-issue-authors-json }}

.github/workflows/aw-resolve-apm-assets.yml

@@ -0,0 +1,159 @@
+name: Resolve APM Agentic Assets
+
+# Resolves consumer apm.yml assets for one agentic workflow invocation. Call immediately
+# before each job that uses a gh-aw-* reusable workflow (not from aw-prelude).
+on:
+  workflow_call:
+    inputs:
+      control-plane-workflow:
+        description: >-
+          Basename of the calling wrapper under .github/workflows/ (for example
+          oblt-aw-automerge.yml). Used to resolve the registry workflow id for apm.yml.
+        required: true
+        type: string
+      platform-additional-instructions:
+        description: >-
+          Control-plane baseline additional-instructions for this agent invocation.
+          Merged with consumer apm.yml assets (platform first, then repo assets).
+        required: false
+        type: string
+        default: ""
+      platform-inputs-json:
+        description: >-
+          JSON object of platform workflow_call inputs to merge; repo apm.yml inputs
+          override per key when an asset block is selected.
+        required: false
+        type: string
+        default: "{}"
+      install-apm-packages:
+        description: Run `apm install` when apm.yml is present in the consumer repository
+        required: false
+        type: boolean
+        default: true
+    outputs:
+      apm-manifest-present:
+        description: True when the consumer repository contains apm.yml or apm.yaml
+        value: ${{ jobs.resolve.outputs.apm-manifest-present }}
+      apm-extension-present:
+        description: True when apm.yml contains an x-oblt-aw extension block
+        value: ${{ jobs.resolve.outputs.apm-extension-present }}
+      asset-source:
+        description: none, common, or workflow (APM asset block used for resolution)
+        value: ${{ jobs.resolve.outputs.asset-source }}
+      resolved-additional-instructions:
+        description: Platform baseline plus resolved repo additional-instructions
+        value: ${{ jobs.resolve.outputs.resolved-additional-instructions }}
+      resolved-inputs-json:
+        description: JSON object of merged platform and APM workflow inputs
+        value: ${{ jobs.resolve.outputs.resolved-inputs-json }}
+      resolved-setup-commands-json:
+        description: JSON array of setup shell commands from APM assets
+        value: ${{ jobs.resolve.outputs.resolved-setup-commands-json }}
+
+permissions:
+  contents: read
+
+jobs:
+  resolve:
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    outputs:
+      apm-manifest-present: ${{ steps.resolve.outputs.apm-manifest-present }}
+      apm-extension-present: ${{ steps.resolve.outputs.apm-extension-present }}
+      asset-source: ${{ steps.resolve.outputs.asset-source }}
+      resolved-additional-instructions: ${{ steps.resolve.outputs.resolved-additional-instructions }}
+      resolved-inputs-json: ${{ steps.resolve.outputs.resolved-inputs-json }}
+      resolved-setup-commands-json: ${{ steps.resolve.outputs.resolved-setup-commands-json }}
+    steps:
+      - name: Checkout consumer repository
+        uses: actions/checkout@v6
+
+      - name: Checkout oblt-aw resolver scripts
+        uses: actions/checkout@v6
+        with:
+          repository: elastic/oblt-aw
+          ref: main
+          path: _oblt-aw
+          fetch-depth: 1
+          token: ${{ github.token }}
+          sparse-checkout: |
+            scripts/apm_agentic_assets.py
+            scripts/resolve_apm_agentic_assets.py
+            scripts/resolve_control_plane_workflow_id.py
+            scripts/workflow_registry.py
+            scripts/common.py
+            config/
+            requirements-runtime.txt
+          sparse-checkout-cone-mode: false
+
+      - name: Resolve compound workflow id from registry
+        id: registry
+        env:
+          CONTROL_PLANE_WORKFLOW: ${{ inputs.control-plane-workflow }}
+        run: python _oblt-aw/scripts/resolve_control_plane_workflow_id.py "${CONTROL_PLANE_WORKFLOW}" --config-dir _oblt-aw/config
+
+      - name: Detect apm manifest
+        id: detect
+        run: |
+          set -euo pipefail
+          if [ -f apm.yml ] || [ -f apm.yaml ]; then
+            echo "present=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "present=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: _oblt-aw/requirements-runtime.txt
+
+      - name: Install Python dependencies for resolver
+        run: pip install -r _oblt-aw/requirements-runtime.txt
+
+      - name: Install APM CLI
+        if: >-
+          inputs.install-apm-packages &&
+          steps.detect.outputs.present == 'true'
+        env:
+          APM_VERSION: "v0.16.0"
+        run: |
+          set -euo pipefail
+          OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+          ARCH="$(uname -m)"
+          case "${ARCH}" in
+            x86_64) ARCH="x86_64" ;;
+            arm64|aarch64) ARCH="arm64" ;;
+            *) echo "Unsupported architecture: ${ARCH}"; exit 1 ;;
+          esac
+          TARBALL="apm-${OS}-${ARCH}.tar.gz"
+          BASE_URL="https://github.com/microsoft/apm/releases/download/${APM_VERSION}"
+          curl -fsSL "${BASE_URL}/${TARBALL}" -o "/tmp/${TARBALL}"
+          curl -fsSL "${BASE_URL}/${TARBALL}.sha256" -o "/tmp/${TARBALL}.sha256"
+          EXPECTED="$(awk '{print $1}' "/tmp/${TARBALL}.sha256")"
+          echo "${EXPECTED}  /tmp/${TARBALL}" | sha256sum -c
+          mkdir -p "${HOME}/.local/bin"
+          tar -xzf "/tmp/${TARBALL}" -C /tmp "apm-${OS}-${ARCH}/apm"
+          install -m 0755 "/tmp/apm-${OS}-${ARCH}/apm" "${HOME}/.local/bin/apm"
+          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
+
+      - name: Install agent packages from apm.yml
+        if: >-
+          inputs.install-apm-packages &&
+          steps.detect.outputs.present == 'true'
+        run: |
+          set -euo pipefail
+          apm install
+
+      - name: Resolve agentic assets from apm.yml
+        id: resolve
+        env:
+          ENABLED_WORKFLOW_ID: ${{ steps.registry.outputs.compound-workflow-id }}
+          REPO_ROOT: ${{ github.workspace }}
+          CONTROL_PLANE_CONFIG_DIR: ${{ github.workspace }}/_oblt-aw/config
+          PLATFORM_ADDITIONAL_INSTRUCTIONS: ${{ inputs.platform-additional-instructions }}
+          PLATFORM_INPUTS_JSON: ${{ inputs.platform-inputs-json }}
+        run: python _oblt-aw/scripts/resolve_apm_agentic_assets.py

.github/workflows/ci.yml

@@ -45,7 +45,9 @@ jobs:
         with:
           python-version: "3.14"
           cache: pip
-          cache-dependency-path: requirements-ci.txt
+          cache-dependency-path: |
+            requirements-ci.txt
+            requirements-runtime.txt
 
       - name: Install Python test dependencies
         run: pip install -r requirements-ci.txt
@@ -56,6 +58,9 @@ jobs:
       - name: Validate *-aw-* workflows call aw-prelude
         run: python scripts/validate_aw_workflow_prelude.py
 
+      - name: Validate gh-aw-* workflows call resolve-apm-assets
+        run: python scripts/validate_aw_workflow_resolve_apm_assets.py
+
   typescript-tests:
     name: TypeScript tests
     runs-on: ubuntu-latest

.github/workflows/distribute-client-workflow.yml

@@ -54,6 +54,8 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-runtime.txt
 
       - name: Build target operations matrix
         id: targets

.github/workflows/docs-aw-ai-menu.yml

@@ -132,30 +132,56 @@ jobs:
             const fn = require('./oblt-aw-scripts/scripts/docs/issue-menu/refresh-after-trigger.js')
             await fn({github, context, core})
 
+  resolve-apm-assets-triage:
+    needs: [prelude, evaluate-trigger]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.triage_triggered == 'true'
+    uses: ./.github/workflows/aw-resolve-apm-assets.yml
+    with:
+      control-plane-workflow: docs-aw-ai-menu.yml
+
   run-docs-triage:
     name: Docs AI / triage
-    needs: [evaluate-trigger]
-    if: needs.evaluate-trigger.outputs.triage_triggered == 'true'
+    needs: [prelude, evaluate-trigger, resolve-apm-assets-triage]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.triage_triggered == 'true'
     permissions:
       actions: read
       contents: read
       issues: write
       pull-requests: write
     uses: elastic/docs-actions/.github/workflows/gh-aw-issue-triage.lock.yml@v1
+    with:
+      additional-instructions: ${{ needs.resolve-apm-assets-triage.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
 
+  resolve-apm-assets-issue-scope:
+    needs: [prelude, evaluate-trigger]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.issue_scope_triggered == 'true'
+    uses: ./.github/workflows/aw-resolve-apm-assets.yml
+    with:
+      control-plane-workflow: docs-aw-ai-menu.yml
+
   run-docs-issue-scope:
     name: Docs AI / issue scope
-    needs: [evaluate-trigger]
-    if: needs.evaluate-trigger.outputs.issue_scope_triggered == 'true'
+    needs: [prelude, evaluate-trigger, resolve-apm-assets-issue-scope]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.issue_scope_triggered == 'true'
     permissions:
       actions: read
       contents: read
       discussions: write
       issues: write
       pull-requests: write
     uses: elastic/docs-actions/.github/workflows/gh-aw-docs-issue-scope.lock.yml@v1
+    with:
+      additional-instructions: ${{ needs.resolve-apm-assets-issue-scope.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
 

.github/workflows/docs-aw-pr-ai-menu.yml

@@ -156,10 +156,24 @@ jobs:
             const fn = require('./oblt-aw-scripts/scripts/docs/pr-menu/refresh-after-trigger.js')
             await fn({github, context, core})
 
+  resolve-apm-assets:
+    needs: [prelude, evaluate-trigger]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.docs_review_triggered == 'true'
+    uses: ./.github/workflows/aw-resolve-apm-assets.yml
+    with:
+      control-plane-workflow: docs-aw-pr-ai-menu.yml
+      platform-additional-instructions: |
+        This repository stores documentation as markdown across the repository.
+        Prefer concise, high-signal review comments with exact replacement text when possible.
+
   run-docs-review:
     name: Docs AI / docs review
-    needs: [evaluate-trigger]
-    if: needs.evaluate-trigger.outputs.docs_review_triggered == 'true'
+    needs: [prelude, evaluate-trigger, resolve-apm-assets]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.docs_review_triggered == 'true'
     permissions:
       actions: read
       contents: read
@@ -168,9 +182,7 @@ jobs:
     uses: elastic/docs-actions/.github/workflows/gh-aw-docs-review.lock.yml@v1
     with:
       review-scope: repo-wide-markdown
-      additional-instructions: |
-        This repository stores documentation as markdown across the repository.
-        Prefer concise, high-signal review comments with exact replacement text when possible.
+      additional-instructions: ${{ needs.resolve-apm-assets.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
 

.github/workflows/get-enabled-workflows.yml

@@ -41,12 +41,15 @@ jobs:
           sparse-checkout: |
             scripts/get_enabled_workflows.py
             scripts/common.py
+            requirements-runtime.txt
           sparse-checkout-cone-mode: false
 
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
           python-version: "3.14"
+          cache: pip
+          cache-dependency-path: _oblt-aw/requirements-runtime.txt
 
       - name: Fetch dashboard, parse, and normalize enabled workflows
         id: run

.github/workflows/oblt-aw-agent-suggestions.yml

@@ -17,17 +17,13 @@ jobs:
     with:
       control-plane-workflow: oblt-aw-agent-suggestions.yml
 
-  agent-suggestions:
+  resolve-apm-assets:
     needs: prelude
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: read
     if: needs.prelude.outputs.proceed == 'true'
-    uses: elastic/ai-github-actions/.github/workflows/gh-aw-agent-suggestions.lock.yml@main
+    uses: ./.github/workflows/aw-resolve-apm-assets.yml
     with:
-      title-prefix: "[oblt-aw][agent-suggestions]"
-      additional-instructions: |
+      control-plane-workflow: oblt-aw-agent-suggestions.yml
+      platform-additional-instructions: |
         Additional requirements for this repository:
 
         - If there are no net-new recommendations, or if recommendations only suggest workflows/features already in use in this repository, call `noop` and do not create any issue.
@@ -42,4 +38,16 @@ jobs:
         When calling `create_issue`, ensure the output includes:
         - `labels`: contains `agentic-workflow`
         - `expires`: `24h`
+
+  agent-suggestions:
+    needs: [prelude, resolve-apm-assets]
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+    if: needs.prelude.outputs.proceed == 'true'
+    uses: elastic/ai-github-actions/.github/workflows/gh-aw-agent-suggestions.lock.yml@main
+    with:
+      title-prefix: "[oblt-aw][agent-suggestions]"
+      additional-instructions: ${{ needs.resolve-apm-assets.outputs.resolved-additional-instructions }}
     secrets: inherit