@cxi-lmai/ci-agent-platform 3.0.0

package/payload/ci-templates/scripts/lib/pipeline-common.sh

@@ -0,0 +1,280 @@
+# shellcheck shell=bash
+# Source-only library. Shared runner helpers used by every tier-1 job script:
+# variable defaults, git identity for bot commits, the claude invocation wrapper
+# (with the unprivileged-user switch the original scripts used), dotenv read/write,
+# and a metrics-event helper. No intelligence lives here, only runner plumbing.
+
+set -u
+
+SCRIPT_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./usage-capture.sh
+source "$SCRIPT_LIB_DIR/usage-capture.sh"
+# shellcheck source=./platform.sh
+source "$SCRIPT_LIB_DIR/platform.sh"
+
+# --- Defaults ---------------------------------------------------------------
+# Every PIPE_ variable has a default here so a project that overrides nothing
+# still gets a working pipeline. The CI template also carries these defaults in
+# its `variables:` block; this is the second line of defence for direct calls.
+
+pipe_defaults() {
+  pipe_detect_platform || return 1
+  : "${PIPE_PLATFORM:=gitlab}"          # final fallback for direct local calls
+  : "${PIPE_CONFIG_PATH:=.claude/pipeline-config.md}"
+  : "${PIPE_CONTEXT_DIR:=build/pipeline}"
+  : "${PIPE_METRICS_DIR:=$PIPE_CONTEXT_DIR/metrics}"
+  : "${PIPE_TARGET_BRANCH:=main}"
+  : "${PIPE_FIX_LOOP_CAP:=2}"
+  : "${PIPE_CODER_CAP:=3}"
+  : "${PIPE_ISSUE_SCAN:=20}"
+  : "${PIPE_MODEL_TRIAGE:=haiku}"
+  : "${PIPE_MODEL_CODE:=sonnet}"
+  : "${PIPE_MODEL_REVIEW:=sonnet}"
+  : "${PIPE_COMMIT_TESTFIX:=Fix test errors}"
+  : "${PIPE_COMMIT_REVIEWFIX:=Fix review findings}"
+  : "${PIPE_COMMIT_COVERAGE:=Add coverage tests}"
+  : "${PIPE_LABEL_READY:=pipe-ready}"
+  : "${PIPE_LABEL_WIP:=pipe-wip}"
+  : "${PIPE_LABEL_STUCK:=pipe-stuck}"
+  : "${PIPE_LABEL_BLOCKER:=pipe-blocker}"
+  : "${PIPE_LABEL_BLOCKED:=pipe-blocked}"
+  : "${PIPE_LABEL_DECOMPOSED:=pipe-decomposed}"
+  : "${PIPE_RESULT_REVIEW:=$PIPE_CONTEXT_DIR/code-review-result.txt}"
+  : "${PIPE_RESULT_REVIEWFIX:=$PIPE_CONTEXT_DIR/review-fix-result.json}"
+  : "${PIPE_VERIFY_CMD:=}"
+  : "${PIPE_COMPILE_CMD:=${PIPE_VERIFY_CMD}}"
+  : "${PIPE_TEST_REPORT_GLOB:=}"
+  : "${PIPE_COVERAGE_SIGNAL:=}"
+  # Spec template path. GitHub projects usually keep it under .github, GitLab
+  # under .gitlab, so the default follows the detected platform.
+  if [ "$PIPE_PLATFORM" = "github" ]; then
+    : "${PIPE_SPEC_TEMPLATE_PATH:=.github/ISSUE_TEMPLATE/spec.md}"
+  else
+    : "${PIPE_SPEC_TEMPLATE_PATH:=.gitlab/issue_templates/Spec.md}"
+  fi
+  mkdir -p "$PIPE_CONTEXT_DIR" "$PIPE_METRICS_DIR"
+  # Keep the runner's working files out of agent commits: agents commit with
+  # `git add -A`, and a repo without its own ignore rule for the context dir
+  # would pick up result files (E2E finding N-6). A `*` gitignore inside the
+  # dir hides everything in it, including itself, from any git add.
+  [ -f "$PIPE_CONTEXT_DIR/.gitignore" ] || printf '*\n' > "$PIPE_CONTEXT_DIR/.gitignore"
+  export PIPE_PLATFORM PIPE_CONFIG_PATH PIPE_CONTEXT_DIR PIPE_METRICS_DIR \
+    PIPE_TARGET_BRANCH PIPE_FIX_LOOP_CAP PIPE_CODER_CAP PIPE_ISSUE_SCAN PIPE_COMMIT_TESTFIX \
+    PIPE_COMMIT_REVIEWFIX PIPE_COMMIT_COVERAGE PIPE_LABEL_READY PIPE_LABEL_WIP \
+    PIPE_LABEL_STUCK PIPE_LABEL_BLOCKER PIPE_LABEL_BLOCKED PIPE_LABEL_DECOMPOSED \
+    PIPE_RESULT_REVIEW PIPE_RESULT_REVIEWFIX PIPE_VERIFY_CMD PIPE_COMPILE_CMD \
+    PIPE_TEST_REPORT_GLOB PIPE_COVERAGE_SIGNAL PIPE_SPEC_TEMPLATE_PATH \
+    PIPE_MODEL_TRIAGE PIPE_MODEL_CODE PIPE_MODEL_REVIEW
+}
+
+pipe_log() { echo "[pipeline] $*"; }
+
+# --- Git identity and push remote ------------------------------------------
+# Sets the bot commit identity and an authenticated push remote. The token is
+# the bot account's token, passed as PIPE_TOKEN (GitLab) or GH_TOKEN (GitHub).
+
+pipe_git_identity() {
+  git config user.email "${PIPE_GIT_EMAIL:-bot@pipeline.ci}"
+  git config user.name  "${PIPE_GIT_NAME:-Pipeline Bot}"
+  local host="${PIPE_SERVER_HOST:-}"
+  local path="${PIPE_PROJECT_PATH:-}"
+  [ -z "$host" ] || [ -z "$path" ] && return 0
+  case "$PIPE_PLATFORM" in
+    gitlab) git remote set-url origin "https://oauth2:${PIPE_TOKEN}@${host}/${path}.git" ;;
+    github) git remote set-url origin "https://x-access-token:${GH_TOKEN:-${GITHUB_TOKEN:-}}@${host}/${path}.git" ;;
+  esac
+}
+
+# Checkout the real source branch so commits land on the branch tip, not on the
+# detached MR/PR ref that can fall behind and cause non-fast-forward push errors.
+pipe_checkout_source() {
+  [ -z "${PIPE_SOURCE_BRANCH:-}" ] && return 0
+  git fetch origin "$PIPE_TARGET_BRANCH" "$PIPE_SOURCE_BRANCH" 2>/dev/null || true
+  git checkout -B "$PIPE_SOURCE_BRANCH" "origin/$PIPE_SOURCE_BRANCH" 2>/dev/null || true
+}
+
+# Rebase onto the latest remote source branch, then push. Aborts cleanly on
+# conflict (a human resolves it). Push is runner work, the agent never pushes.
+pipe_rebase_and_push() {
+  git fetch origin "$PIPE_SOURCE_BRANCH"
+  if ! git rebase "origin/$PIPE_SOURCE_BRANCH"; then
+    pipe_log "Rebase conflict, cannot auto-merge on top of remote changes"
+    git rebase --abort
+    return 1
+  fi
+  git push origin "HEAD:$PIPE_SOURCE_BRANCH"
+}
+
+# --- Cap counting -----------------------------------------------------------
+# Count consecutive commits from the tip back toward the target branch whose
+# subject matches a pattern. The skill also computes this, but the runner needs
+# it to decide whether the agent actually committed this run.
+
+pipe_count_fix_commits() {
+  local pattern="$1" count=0 subject
+  while IFS= read -r subject; do
+    if echo "$subject" | grep -qF "$pattern"; then
+      count=$((count + 1))
+    else
+      break
+    fi
+  done < <(git log "origin/$PIPE_TARGET_BRANCH..HEAD" --format="%s" 2>/dev/null)
+  echo "$count"
+}
+
+# --- Claude invocation ------------------------------------------------------
+# Runs `claude "/<skill>"` wrapped in usage-capture. Claude Code refuses to run
+# as root with --dangerously-skip-permissions, so when the runner is root we
+# create an unprivileged user and su into it. Otherwise we
+# run directly. Runtime variables are exported so the skill reads them, but
+# credentials used by the surrounding runner are removed from the model process.
+
+pipe_agent_secret_var() {
+  # Return success when an exported variable looks credential-bearing and is
+  # not explicitly required by the Claude API itself or allowlisted for a
+  # project verification command. The allowlist is comma/space separated.
+  local name="$1" allow=" ${PIPE_AGENT_ENV_ALLOWLIST:-} "
+  allow=" ${allow//,/ } "
+  # The Claude process must keep its own credential regardless of which of the
+  # three supported auth variables the project uses.
+  case "$name" in
+    ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|CLAUDE_CODE_OAUTH_TOKEN) return 1 ;;
+  esac
+  [[ "$allow" == *" $name "* ]] && return 1
+  case "$name" in
+    *TOKEN*|*SECRET*|*PASSWORD*|*PASSWD*|*PRIVATE_KEY*|*API_KEY*|*CREDENTIAL*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+pipe_scrub_agent_secrets() {
+  local v
+  while IFS= read -r v; do
+    [ -n "$v" ] && unset "$v"
+  done < <(compgen -e | while IFS= read -r v; do pipe_agent_secret_var "$v" && echo "$v"; done)
+}
+
+pipe_run_claude() {
+  # $1 = agent label for metrics, $2 = skill invocation (e.g. "/review-mr"),
+  # $3 = allowed tools (optional), $4 = model for the main loop (optional,
+  # e.g. $PIPE_MODEL_REVIEW; subagents keep their frontmatter models),
+  # stdin = extra prompt (optional, usually empty)
+  local label="$1" skill="$2" tools="${3:-Agent,Read,Write,Edit,Glob,Grep,Bash}" model="${4:-}"
+  local stdin_file; stdin_file=$(mktemp)
+  cat > "$stdin_file" || true
+
+  if [ "$(id -u)" -eq 0 ]; then
+    local runuser="pipelinebot"
+    id "$runuser" &>/dev/null || useradd -m -s /bin/bash "$runuser"
+    chown -R "$runuser:$runuser" "$PWD" "$PIPE_CONTEXT_DIR" "$stdin_file" 2>/dev/null || true
+    local runner; runner=$(mktemp)
+    {
+      printf '#!/bin/bash\nset -e\nexport HOME=/home/%s\n' "$runuser"
+      # Re-export the runtime environment the skill and usage-capture need.
+      local v
+      for v in $(compgen -v | grep -E '^(PIPE_|CI_|GH_|GITHUB_|ANTHROPIC_|CLAUDE_)'); do
+        pipe_agent_secret_var "$v" && continue
+        printf 'export %s=%q\n' "$v" "${!v}"
+      done
+      # `su -m` preserves the parent environment, so explicitly remove every
+      # detected credential after exporting the safe runtime values above.
+      for v in $(compgen -e); do
+        pipe_agent_secret_var "$v" && printf 'unset %q\n' "$v"
+      done
+      printf 'cd %q\n' "$PWD"
+      printf 'source %q\n' "$SCRIPT_LIB_DIR/usage-capture.sh"
+      # The result JSON of `claude -p` has no model field, so pass the
+      # requested model to usage-capture for the metric (E2E finding N-5).
+      printf 'export PIPE_CAPTURE_MODEL=%q\n' "$model"
+      if [ -n "$model" ]; then
+        printf 'capture_claude %q -- --dangerously-skip-permissions --model %q --allowedTools %q -p %q < %q\n' \
+          "$label" "$model" "$tools" "$skill" "$stdin_file"
+      else
+        printf 'capture_claude %q -- --dangerously-skip-permissions --allowedTools %q -p %q < %q\n' \
+          "$label" "$tools" "$skill" "$stdin_file"
+      fi
+    } > "$runner"
+    chmod +x "$runner"
+    chown "$runuser:$runuser" "$runner"
+    su -m "$runuser" -s /bin/bash "$runner" || true
+    chown -R root:root "$PWD" 2>/dev/null || true
+    rm -f "$runner"
+  else
+    (
+      pipe_scrub_agent_secrets
+      export PIPE_CAPTURE_MODEL="$model"
+      if [ -n "$model" ]; then
+        capture_claude "$label" -- --dangerously-skip-permissions --model "$model" --allowedTools "$tools" -p "$skill" < "$stdin_file"
+      else
+        capture_claude "$label" -- --dangerously-skip-permissions --allowedTools "$tools" -p "$skill" < "$stdin_file"
+      fi
+    ) || true
+  fi
+  rm -f "$stdin_file"
+}
+
+# --- dotenv -----------------------------------------------------------------
+
+# Load KEY=VALUE lines from a marker file into the current shell.
+pipe_load_env() {
+  local f="$1"
+  [ -f "$f" ] || return 0
+  set -a
+  # shellcheck disable=SC1090
+  source "$f"
+  set +a
+}
+
+pipe_get_env() {
+  # $1 = file, $2 = key. Prints the value or empty.
+  [ -f "$1" ] || return 0
+  grep -E "^$2=" "$1" | head -1 | cut -d= -f2- || true
+}
+
+# --- Escalation -------------------------------------------------------------
+# Applies the runner side of an escalation after the postmortem flow ran (either
+# inline in a fix skill or via the /postmortem-mr skill in postmortem.sh). Reads
+# the label changes and the diagnostic body the skill produced, applies labels,
+# posts the comment, and emits the dev_stuck metric. Never invokes the model.
+
+pipe_apply_escalation() {
+  local pm_env="$PIPE_CONTEXT_DIR/postmortem.env"
+  local pm_body="$PIPE_CONTEXT_DIR/postmortem.md"
+  local add remove category diag
+  add=$(pipe_get_env "$pm_env" ADD_LABELS);       add=${add:-$PIPE_LABEL_STUCK}
+  remove=$(pipe_get_env "$pm_env" REMOVE_LABELS); remove=${remove:-$PIPE_LABEL_WIP}
+  category=$(pipe_get_env "$pm_env" FAILURE_CATEGORY); category=${category:-${1:-other}}
+
+  platform_set_labels "$add" "$remove"
+
+  if [ -s "$pm_body" ]; then
+    diag=$(cat "$pm_body")
+  else
+    diag="Automated fixes were exhausted after $PIPE_FIX_LOOP_CAP attempts. A human needs to take over."
+  fi
+  platform_post_comment "🤖 **Auto-fix stuck after $PIPE_FIX_LOOP_CAP attempts. Diagnostic analysis:**
+
+$diag
+
+Human intervention needed."
+
+  pipe_metric_event postmortem dev_stuck \
+    "$(jq -n --arg c "$category" --arg ctx "${2:-unknown}" '{failure_category: $c, context: $ctx}')"
+}
+
+# --- Metrics ----------------------------------------------------------------
+
+pipe_metric_event() {
+  # $1 = agent, $2 = event, $3 = extra jq object (e.g. '{findings_total: 3}')
+  local agent="$1" event="$2" extra="${3:-{\}}"
+  local ts ts_nanos
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  ts_nanos=$(date +%s%N)
+  jq -n \
+    --arg ts "$ts" --arg agent "$agent" --arg event "$event" \
+    --argjson mr_iid "${PIPE_MR_IID:-null}" \
+    --argjson extra "$extra" \
+    '{ts: $ts, agent: $agent, event: $event, mr_iid: $mr_iid} + $extra' \
+    > "$PIPE_METRICS_DIR/${agent}-${event}-${ts_nanos}.json"
+  pipe_log "metric $event written"
+}

package/payload/ci-templates/scripts/lib/platform.sh

@@ -0,0 +1,177 @@
+# shellcheck shell=bash
+# Source-only library. Platform abstraction over the merge-request / pull-request
+# API, so the runner scripts read the same functions on GitLab and GitHub.
+#
+# Selection: $PIPE_PLATFORM is "gitlab" or "github". Each platform's CI template
+# sets it along with the runtime variables the functions below expect:
+#
+#   Common (both platforms):
+#     PIPE_MR_IID          MR iid (GitLab) or PR number (GitHub)
+#     PIPE_TARGET_BRANCH   branch the MR/PR targets
+#     PIPE_SOURCE_BRANCH   the MR/PR source branch
+#     PIPE_HEAD_SHA        current head commit under review
+#     PIPE_PROJECT_PATH    namespace/project (for git push URL)
+#     PIPE_SERVER_HOST     git host (for git push URL)
+#     PIPE_BOT_USER        bot account username (filters bot comments)
+#
+#   GitLab:
+#     PIPE_API_URL         $CI_API_V4_URL
+#     PIPE_PROJECT_ID      $CI_PROJECT_ID
+#     PIPE_TOKEN           project-access / personal token of the bot account
+#     PIPE_PREV_HEAD_SHA   (unused; GitLab computes incrementality from versions)
+#
+#   GitHub:
+#     PIPE_REPO            owner/repo (for `gh api`)
+#     GH_TOKEN / GITHUB_TOKEN   token used by the `gh` CLI
+#     PIPE_PREV_HEAD_SHA   github.event.before on a synchronize event, else empty
+#
+# All functions print to stdout and never call `exit`. On error they print an
+# empty value so the caller can decide.
+
+set -u
+
+# --- Platform autodetection -------------------------------------------------
+# Same runner scripts run on GitLab and GitHub without configuration. An
+# explicit PIPE_PLATFORM always wins; otherwise the CI runner's own signal
+# variable decides (GITLAB_CI=true or GITHUB_ACTIONS=true). Only genuine
+# ambiguity (both signals present) is a hard error. When neither is present and
+# nothing is set (a direct local call), the caller's default applies.
+pipe_detect_platform() {
+  [ -n "${PIPE_PLATFORM:-}" ] && return 0   # explicit override wins
+  local gl="${GITLAB_CI:-}" gh="${GITHUB_ACTIONS:-}"
+  if [ "$gl" = "true" ] && [ "$gh" = "true" ]; then
+    echo "[pipeline] ERROR: both GITLAB_CI and GITHUB_ACTIONS are set; set PIPE_PLATFORM to disambiguate" >&2
+    return 1
+  elif [ "$gl" = "true" ]; then
+    PIPE_PLATFORM="gitlab"
+  elif [ "$gh" = "true" ]; then
+    PIPE_PLATFORM="github"
+  fi
+  return 0
+}
+
+# --- GitLab helpers ---------------------------------------------------------
+
+_gl_get() {
+  # $1 = API path suffix under the MR, e.g. "" or "/notes?per_page=100"
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" \
+    "$PIPE_API_URL/projects/$PIPE_PROJECT_ID/merge_requests/$PIPE_MR_IID$1"
+}
+
+_gl_mr_meta()   { _gl_get "" | jq -r '{title: (.title // ""), description: (.description // ""), labels: ((.labels // []) | join(","))}'; }
+_gl_mr_labels() { _gl_get "" | jq -r '((.labels // []) | join(","))'; }
+# Callers take the LAST matching note, so the array must be chronological AND
+# must contain the newest notes. One asc page would return the oldest 100 on a
+# long MR, so fetch the newest 100 (sort=desc) and reverse back to chronological.
+_gl_notes()     { _gl_get "/notes?per_page=100&sort=desc" | jq -r '[.[] | {author: .author.username, body: .body}] | reverse'; }
+_gl_issue()     { curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$PIPE_API_URL/projects/$PIPE_PROJECT_ID/issues/$1" | jq -r '{iid: .iid, title: (.title // ""), description: (.description // "")}'; }
+
+_gl_post_comment() {
+  curl --fail-with-body -s -X POST \
+    -H "PRIVATE-TOKEN: $PIPE_TOKEN" \
+    "$PIPE_API_URL/projects/$PIPE_PROJECT_ID/merge_requests/$PIPE_MR_IID/notes" \
+    --data-urlencode "body=$1" > /dev/null
+}
+
+_gl_set_labels() {
+  # $1 = add (comma), $2 = remove (comma)
+  curl -s -X PUT -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$PIPE_API_URL/projects/$PIPE_PROJECT_ID/merge_requests/$PIPE_MR_IID" \
+    -d "{\"add_labels\":\"$1\",\"remove_labels\":\"$2\"}" > /dev/null || true
+}
+
+_gl_compute_diff_base() {
+  # Incremental re-review: use the previous push head unless the MR was rebased.
+  # After a rebase the base_commit_sha changes between versions, so the old head
+  # is on a different tree and would pull in absorbed base-branch changes.
+  local versions prev_head curr_base prev_base rebased
+  versions=$(_gl_get "/versions")
+  prev_head=$(echo "$versions" | jq -r '.[1].head_commit_sha // ""' 2>/dev/null || true)
+  curr_base=$(echo "$versions" | jq -r '.[0].base_commit_sha // ""' 2>/dev/null || true)
+  prev_base=$(echo "$versions" | jq -r '.[1].base_commit_sha // ""' 2>/dev/null || true)
+  rebased=$( [ -n "$prev_base" ] && [ "$curr_base" != "$prev_base" ] && echo true || echo false )
+  if [ -n "$prev_head" ] && [ "$rebased" = "false" ]; then
+    PIPE_DIFF_BASE="$prev_head"; PIPE_IS_INCREMENTAL="true"
+  else
+    PIPE_DIFF_BASE="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-$(git merge-base "origin/$PIPE_TARGET_BRANCH" "$PIPE_HEAD_SHA" 2>/dev/null || echo "$PIPE_TARGET_BRANCH")}"
+    PIPE_IS_INCREMENTAL="false"
+  fi
+}
+
+# --- GitHub helpers ---------------------------------------------------------
+
+_gh_get() { gh api "repos/$PIPE_REPO/$1"; }
+
+_gh_mr_meta()   { _gh_get "pulls/$PIPE_MR_IID" | jq -r '{title: (.title // ""), description: (.body // ""), labels: ((.labels // []) | map(.name) | join(","))}'; }
+_gh_mr_labels() { _gh_get "pulls/$PIPE_MR_IID" | jq -r '((.labels // []) | map(.name) | join(","))'; }
+# The per-issue comments endpoint has no sort param, so paginate all pages to
+# guarantee the newest comments are present (callers take the last match).
+_gh_notes()     { gh api --paginate "repos/$PIPE_REPO/issues/$PIPE_MR_IID/comments?per_page=100" --jq '.[] | {author: .user.login, body: .body}' | jq -s '.'; }
+_gh_issue()     { _gh_get "issues/$1" | jq -r '{iid: .number, title: (.title // ""), description: (.body // "")}'; }
+
+_gh_post_comment() {
+  gh api -X POST "repos/$PIPE_REPO/issues/$PIPE_MR_IID/comments" -f "body=$1" > /dev/null
+}
+
+_gh_set_labels() {
+  # $1 = add (comma), $2 = remove (comma)
+  local IFS=','
+  local l
+  for l in $1; do
+    [ -n "$l" ] && gh api -X POST "repos/$PIPE_REPO/issues/$PIPE_MR_IID/labels" -f "labels[]=$l" > /dev/null || true
+  done
+  for l in $2; do
+    [ -n "$l" ] && gh api -X DELETE "repos/$PIPE_REPO/issues/$PIPE_MR_IID/labels/$l" > /dev/null 2>&1 || true
+  done
+}
+
+_gh_compute_diff_base() {
+  # GitHub gives the previous head as github.event.before on a synchronize event.
+  if [ -n "${PIPE_PREV_HEAD_SHA:-}" ] && [ "$PIPE_PREV_HEAD_SHA" != "0000000000000000000000000000000000000000" ]; then
+    PIPE_DIFF_BASE="$PIPE_PREV_HEAD_SHA"; PIPE_IS_INCREMENTAL="true"
+  else
+    PIPE_DIFF_BASE="$(git merge-base "origin/$PIPE_TARGET_BRANCH" "$PIPE_HEAD_SHA" 2>/dev/null || echo "origin/$PIPE_TARGET_BRANCH")"
+    PIPE_IS_INCREMENTAL="false"
+  fi
+}
+
+# --- Bot identity -------------------------------------------------------------
+# The scripts filter MR/PR comments by the bot's username to recognise their own
+# previous output. The token already knows whose it is, so an empty
+# PIPE_BOT_USER is resolved from the API once instead of being configured.
+_gl_resolve_bot_user() { curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$PIPE_API_URL/user" | jq -r '.username // ""'; }
+# /user does not answer for the default GITHUB_TOKEN (an app token, not a
+# user); comments made with it are authored by github-actions[bot].
+_gh_resolve_bot_user() { gh api user --jq '.login' 2>/dev/null || echo "github-actions[bot]"; }
+
+platform_resolve_bot_user() {
+  [ -n "${PIPE_BOT_USER:-}" ] && return 0
+  case "$PIPE_PLATFORM" in
+    gitlab) PIPE_BOT_USER=$(_gl_resolve_bot_user) ;;
+    github) PIPE_BOT_USER=$(_gh_resolve_bot_user) ;;
+  esac
+  export PIPE_BOT_USER
+}
+
+# --- Public dispatch --------------------------------------------------------
+
+platform_mr_meta()      { case "$PIPE_PLATFORM" in gitlab) _gl_mr_meta ;; github) _gh_mr_meta ;; esac; }
+platform_mr_labels()    { case "$PIPE_PLATFORM" in gitlab) _gl_mr_labels ;; github) _gh_mr_labels ;; esac; }
+platform_notes()        { case "$PIPE_PLATFORM" in gitlab) _gl_notes ;; github) _gh_notes ;; esac; }
+platform_issue()        { case "$PIPE_PLATFORM" in gitlab) _gl_issue "$1" ;; github) _gh_issue "$1" ;; esac; }
+platform_post_comment() { case "$PIPE_PLATFORM" in gitlab) _gl_post_comment "$1" ;; github) _gh_post_comment "$1" ;; esac; }
+platform_set_labels()   { case "$PIPE_PLATFORM" in gitlab) _gl_set_labels "$1" "$2" ;; github) _gh_set_labels "$1" "$2" ;; esac; }
+
+# Sets PIPE_DIFF_BASE and PIPE_IS_INCREMENTAL. Call before building the diff.
+platform_compute_diff_base() {
+  if [ -n "${PIPE_DIFF_BASE:-}" ]; then
+    # Caller (or the CI template) already provided it; respect it.
+    PIPE_IS_INCREMENTAL="${PIPE_IS_INCREMENTAL:-false}"
+    return 0
+  fi
+  case "$PIPE_PLATFORM" in
+    gitlab) _gl_compute_diff_base ;;
+    github) _gh_compute_diff_base ;;
+  esac
+  export PIPE_DIFF_BASE PIPE_IS_INCREMENTAL
+}

package/payload/ci-templates/scripts/lib/usage-capture.sh

@@ -0,0 +1,110 @@
+# shellcheck shell=bash
+# Source-only library. Wraps a `claude` invocation, captures the stream-json
+# `result` event, writes a metrics record, and surfaces the assistant text on
+# stdout so callers behave identically.
+#
+# Taken from a single-project original (audited as 100% generic).
+# The only change is the metrics directory and the identifier fields, which now
+# read the PIPE_ runtime variables first and fall back to the GitLab CI_ names,
+# so the same wrapper works on GitLab and GitHub runners.
+#
+# Usage:   capture_claude <agent_name> -- <args to pass to `claude`...>
+# Stdin:   forwarded to `claude` stdin
+# Stdout:  concatenated text from assistant turns (drop-in for `claude`)
+# Side effect: writes one JSON record to $PIPE_METRICS_DIR
+
+set -u
+
+capture_claude() {
+  local agent="$1"; shift
+  [ "${1:-}" = "--" ] && shift
+
+  local metrics_dir="${PIPE_METRICS_DIR:-${PIPE_CONTEXT_DIR:-build/pipeline}/metrics}"
+  mkdir -p "$metrics_dir"
+
+  local job_name="${PIPE_JOB_NAME:-${CI_JOB_NAME:-job}}"
+  local job_id="${PIPE_JOB_ID:-${CI_JOB_ID:-$$}}"
+  local pipeline_id="${PIPE_PIPELINE_ID:-${CI_PIPELINE_ID:-}}"
+  local mr_iid="${PIPE_MR_IID:-${CI_MERGE_REQUEST_IID:-null}}"
+  local issue_iid="${PIPE_ISSUE_IID:-${CODER_ISSUE:-null}}"
+
+  local stream_file stderr_file
+  stream_file=$(mktemp)
+  stderr_file=$(mktemp)
+  local start_ns end_ns
+  start_ns=$(date +%s%N)
+  local exit_code=0
+
+  # Force stream-json so we always get a `result` event.
+  claude --output-format stream-json --verbose "$@" \
+    >"$stream_file" 2>"$stderr_file" || exit_code=$?
+
+  end_ns=$(date +%s%N)
+  local wall_ms=$(( (end_ns - start_ns) / 1000000 ))
+
+  # Extract the result event (last line that begins with {"type":"result")
+  local result_line
+  result_line=$(grep '^{"type":"result"' "$stream_file" | tail -1 || true)
+
+  local model input output cache_c cache_r cost duration
+  if [ -n "$result_line" ]; then
+    # The result event carries no model field (E2E finding N-5). Record the
+    # model the runner requested (PIPE_CAPTURE_MODEL). The last fallback,
+    # first key of modelUsage, is alphabetical and may name a subagent's
+    # model rather than the main loop's, so it comes last.
+    model=$(echo "$result_line"   | jq -r '.model // empty')
+    [ -n "$model" ] || model="${PIPE_CAPTURE_MODEL:-}"
+    [ -n "$model" ] || model=$(echo "$result_line" | jq -r '.modelUsage // {} | keys | first // empty')
+    input=$(echo "$result_line"   | jq -r '.usage.input_tokens // 0')
+    output=$(echo "$result_line"  | jq -r '.usage.output_tokens // 0')
+    cache_c=$(echo "$result_line" | jq -r '.usage.cache_creation_input_tokens // 0')
+    cache_r=$(echo "$result_line" | jq -r '.usage.cache_read_input_tokens // 0')
+    cost=$(echo "$result_line"    | jq -r '.total_cost_usd // 0')
+    duration=$(echo "$result_line" | jq -r '.duration_ms // 0')
+  else
+    model=""; input=0; output=0; cache_c=0; cache_r=0; cost=0; duration=$wall_ms
+  fi
+
+  # Recover the user-facing text (concatenate all assistant text blocks) so
+  # downstream consumers that read `claude`'s stdout still work.
+  grep '^{"type":"assistant"' "$stream_file" \
+    | jq -r '.message.content[]? | select(.type=="text") | .text' \
+    || true
+
+  # Write metrics record
+  local record_stamp record_file
+  record_stamp=$(date +%s%N)
+  record_file="$metrics_dir/${job_name}-${job_id}-${record_stamp}.json"
+  jq -n \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg agent "$agent" \
+    --arg event "claude_invocation" \
+    --arg model "$model" \
+    --arg pipeline_id "$pipeline_id" \
+    --arg job_id "$job_id" \
+    --arg job_name "$job_name" \
+    --argjson mr_iid "$mr_iid" \
+    --argjson issue_iid "$issue_iid" \
+    --argjson input "$input" \
+    --argjson output "$output" \
+    --argjson cache_c "$cache_c" \
+    --argjson cache_r "$cache_r" \
+    --argjson cost "$cost" \
+    --argjson duration "$duration" \
+    --argjson wall_ms "$wall_ms" \
+    --argjson exit_code "$exit_code" \
+    '{
+      ts: $ts, agent: $agent, event: $event, model: $model,
+      pipeline_id: $pipeline_id, job_id: $job_id, job_name: $job_name,
+      mr_iid: $mr_iid, issue_iid: $issue_iid,
+      input_tokens: $input, output_tokens: $output,
+      cache_creation_tokens: $cache_c, cache_read_tokens: $cache_r,
+      total_cost_usd: $cost, duration_ms: $duration, wall_ms: $wall_ms,
+      claude_exit_code: $exit_code
+    }' > "$record_file"
+
+  # If Claude failed, forward stderr so debugging still works
+  [ "$exit_code" -ne 0 ] && cat "$stderr_file" >&2
+  rm -f "$stream_file" "$stderr_file"
+  return "$exit_code"
+}