chore: import upstream snapshot with attribution

This commit is contained in:
wehub-resource-sync
2026-07-13 12:39:17 +08:00
commit 4ed4e9ff99
1368 changed files with 334957 additions and 0 deletions
@@ -0,0 +1,44 @@
---
name: code-change-verification
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository.
---
# Code Change Verification
## Overview
Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack.
## Quick start
1. Keep this skill at `./.agents/skills/code-change-verification` so it loads automatically for the repository.
2. macOS/Linux: `bash .agents/skills/code-change-verification/scripts/run.sh`.
3. Windows: `powershell -ExecutionPolicy Bypass -File .agents/skills/code-change-verification/scripts/run.ps1`.
4. The scripts run `make format` first, then run `make lint`, `make typecheck`, and `make tests` in parallel with fail-fast semantics.
5. While the parallel steps are still running, the scripts emit periodic heartbeat updates so you can tell that work is still in progress.
6. If any command fails, fix the issue, rerun the script, and report the failing output.
7. Confirm completion only when all commands succeed with no remaining issues.
## Environment setup
The verification scripts assume repository dependencies are already installed. Do not run `make sync` as part of every verification pass; use it for a fresh checkout, after dependency files change, or when dependency resolution fails before the checks start.
On Linux, some Python packages with native extensions may require system packages such as `libffi-dev`, Python development headers, or build tools. If verification cannot start because one of these packages is missing, treat it as a local environment setup issue. Install the missing dependency when possible, or report the failing command and missing dependency in the PR test plan before rerunning verification in a prepared environment.
## Manual workflow
- For a fresh checkout, or if dependencies are not installed or have changed, run `make sync` first to install dev requirements via `uv`.
- Run from the repository root with `make format` first, then `make lint`, `make typecheck`, and `make tests`.
- Do not skip steps; stop and fix issues immediately when a command fails.
- If you run the steps manually, you may parallelize `make lint`, `make typecheck`, and `make tests` after `make format` completes, but you must stop the remaining steps as soon as one fails.
- Re-run the full stack after applying fixes so the commands execute in the required order.
## Resources
### scripts/run.sh
- Executes `make format` first, then runs `make lint`, `make typecheck`, and `make tests` in parallel with fail-fast semantics from the repository root. It also emits periodic heartbeat updates while the parallel steps are still running. Prefer this entry point to preserve the required ordering while reducing total runtime.
### scripts/run.ps1
- Windows-friendly wrapper that runs the same sequence with `make format` first and the remaining steps in parallel with fail-fast semantics, plus periodic heartbeat updates while work is still running. Use from PowerShell with execution policy bypass if required by your environment.
@@ -0,0 +1,4 @@
interface:
display_name: "Code Change Verification"
short_description: "Run the required local verification stack"
default_prompt: "Use $code-change-verification to run the required local verification stack and report any failures."
@@ -0,0 +1,208 @@
Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
$repoRoot = $null
try {
$repoRoot = (& git -C $scriptDir rev-parse --show-toplevel 2>$null)
} catch {
$repoRoot = $null
}
if (-not $repoRoot) {
$repoRoot = (Resolve-Path (Join-Path $scriptDir "..\\..\\..\\..")).Path
} else {
$repoRoot = ([string]$repoRoot).Trim()
}
Set-Location $repoRoot
$logDir = Join-Path ([System.IO.Path]::GetTempPath()) ("code-change-verification-" + [System.Guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $logDir | Out-Null
$steps = New-Object System.Collections.Generic.List[object]
$heartbeatIntervalSeconds = 10
if ($env:CODE_CHANGE_VERIFICATION_HEARTBEAT_SECONDS) {
$heartbeatIntervalSeconds = [int]$env:CODE_CHANGE_VERIFICATION_HEARTBEAT_SECONDS
}
function Resolve-MakeInvocation {
$command = Get-Command make -ErrorAction Stop
while ($command.CommandType -eq [System.Management.Automation.CommandTypes]::Alias) {
$command = $command.ResolvedCommand
}
if ($command.CommandType -in @(
[System.Management.Automation.CommandTypes]::Application,
[System.Management.Automation.CommandTypes]::ExternalScript
)) {
$commandPath = if ($command.Path) { $command.Path } else { $command.Source }
return [PSCustomObject]@{
FilePath = $commandPath
ArgumentList = @()
}
}
if ($command.CommandType -eq [System.Management.Automation.CommandTypes]::Function) {
$shellPath = (Get-Process -Id $PID).Path
if (-not $shellPath) {
throw "Unable to resolve the current PowerShell executable for make wrapper launches."
}
$wrapperPath = Join-Path $logDir "invoke-make.ps1"
$escapedRepoRoot = $repoRoot -replace "'", "''"
$wrapperTemplate = @'
Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"
Set-Location -LiteralPath '{0}'
function global:make {{
{1}
}}
& make @args
exit $LASTEXITCODE
'@
$wrapperScript = $wrapperTemplate -f $escapedRepoRoot, $command.Definition.TrimEnd()
Set-Content -Path $wrapperPath -Value $wrapperScript -Encoding UTF8
return [PSCustomObject]@{
FilePath = $shellPath
ArgumentList = @("-NoLogo", "-NoProfile", "-File", $wrapperPath)
}
}
throw "code-change-verification: make must resolve to an application, script, alias, or function."
}
$script:MakeInvocation = Resolve-MakeInvocation
function Invoke-MakeStep {
param(
[Parameter(Mandatory = $true)][string]$Step
)
Write-Host "Running make $Step..."
& $script:MakeInvocation.FilePath @($script:MakeInvocation.ArgumentList + $Step)
if ($LASTEXITCODE -ne 0) {
Write-Host "code-change-verification: make $Step failed with exit code $LASTEXITCODE."
return $LASTEXITCODE
}
return 0
}
function Start-MakeStep {
param(
[Parameter(Mandatory = $true)][string]$Step
)
$stdoutLogPath = Join-Path $logDir "$Step.stdout.log"
$stderrLogPath = Join-Path $logDir "$Step.stderr.log"
Write-Host "Running make $Step..."
$process = Start-Process -FilePath $script:MakeInvocation.FilePath -ArgumentList @($script:MakeInvocation.ArgumentList + $Step) -RedirectStandardOutput $stdoutLogPath -RedirectStandardError $stderrLogPath -PassThru
$steps.Add([PSCustomObject]@{
Name = $Step
Process = $process
StdoutLogPath = $stdoutLogPath
StderrLogPath = $stderrLogPath
StartTime = Get-Date
})
}
function Stop-RunningSteps {
foreach ($step in $steps) {
if ($null -eq $step.Process) {
continue
}
& taskkill /PID $step.Process.Id /T /F *> $null
}
foreach ($step in $steps) {
if ($null -eq $step.Process) {
continue
}
try {
$step.Process.WaitForExit()
} catch {
}
}
}
function Wait-ForParallelSteps {
$pending = New-Object System.Collections.Generic.List[object]
foreach ($step in $steps) {
$pending.Add($step)
}
$nextHeartbeatAt = (Get-Date).AddSeconds($heartbeatIntervalSeconds)
while ($pending.Count -gt 0) {
foreach ($step in @($pending)) {
$step.Process.Refresh()
if (-not $step.Process.HasExited) {
continue
}
$duration = [int]((Get-Date) - $step.StartTime).TotalSeconds
if ($step.Process.ExitCode -eq 0) {
Write-Host "make $($step.Name) passed in ${duration}s."
[void]$pending.Remove($step)
continue
}
Write-Host "code-change-verification: make $($step.Name) failed with exit code $($step.Process.ExitCode) after ${duration}s."
if (Test-Path $step.StderrLogPath) {
Write-Host "--- $($step.Name) stderr log (last 80 lines) ---"
Get-Content $step.StderrLogPath -Tail 80
}
if (Test-Path $step.StdoutLogPath) {
Write-Host "--- $($step.Name) stdout log (last 80 lines) ---"
Get-Content $step.StdoutLogPath -Tail 80
}
Stop-RunningSteps
return $step.Process.ExitCode
}
if ($pending.Count -gt 0) {
if ((Get-Date) -ge $nextHeartbeatAt) {
$running = @()
foreach ($step in $pending) {
$elapsed = [int]((Get-Date) - $step.StartTime).TotalSeconds
$running += "$($step.Name) (${elapsed}s)"
}
Write-Host ("code-change-verification: still running: " + ($running -join ", ") + ".")
$nextHeartbeatAt = (Get-Date).AddSeconds($heartbeatIntervalSeconds)
}
Start-Sleep -Seconds 1
}
}
return 0
}
$exitCode = 0
try {
$exitCode = Invoke-MakeStep -Step "format"
if ($exitCode -eq 0) {
Write-Host "Running make lint, make typecheck, and make tests in parallel..."
Start-MakeStep -Step "lint"
Start-MakeStep -Step "typecheck"
Start-MakeStep -Step "tests"
$exitCode = Wait-ForParallelSteps
}
} finally {
Stop-RunningSteps
Remove-Item $logDir -Recurse -Force -ErrorAction SilentlyContinue
}
if ($exitCode -ne 0) {
exit $exitCode
}
Write-Host "code-change-verification: all commands passed."
+398
View File
@@ -0,0 +1,398 @@
#!/usr/bin/env bash
# Fail fast on any error or undefined variable.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
if command -v git >/dev/null 2>&1; then
REPO_ROOT="$(git -C "${SCRIPT_DIR}" rev-parse --show-toplevel 2>/dev/null || true)"
fi
REPO_ROOT="${REPO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}"
cd "${REPO_ROOT}"
LOG_DIR="$(mktemp -d "${TMPDIR:-/tmp}/code-change-verification.XXXXXX")"
STATUS_PIPE="${LOG_DIR}/status.fifo"
HEARTBEAT_INTERVAL_SECONDS="${CODE_CHANGE_VERIFICATION_HEARTBEAT_SECONDS:-10}"
declare -a STEP_LAUNCHER=()
declare -a STEP_PIDS=()
declare -a STEP_NAMES=()
declare -a STEP_LOGS=()
declare -a STEP_STARTS=()
RUNNING_STEPS=0
EXIT_STATUS=0
resolve_executable_path() {
local name="$1"
type -P "${name}" 2>/dev/null || true
}
configure_step_launcher() {
local perl_path=""
local python_path=""
local uv_path=""
perl_path="$(resolve_executable_path perl)"
if [ -n "${perl_path}" ]; then
STEP_LAUNCHER=("${perl_path}" -MPOSIX=setsid -e 'setsid() or die $!; exec @ARGV')
return 0
fi
python_path="$(resolve_executable_path python3)"
if [ -z "${python_path}" ]; then
python_path="$(resolve_executable_path python)"
fi
if [ -n "${python_path}" ]; then
STEP_LAUNCHER=("${python_path}" -c 'import os, sys; os.setsid(); os.execvp(sys.argv[1], sys.argv[1:])')
return 0
fi
uv_path="$(resolve_executable_path uv)"
if [ -n "${uv_path}" ]; then
STEP_LAUNCHER=("${uv_path}" run --no-sync python -c 'import os, sys; os.setsid(); os.execvp(sys.argv[1], sys.argv[1:])')
return 0
fi
echo "code-change-verification: perl, python3, python, or uv is required to manage parallel step process groups." >&2
exit 1
}
configure_step_launcher
mkfifo "${STATUS_PIPE}"
exec 3<> "${STATUS_PIPE}"
cleanup() {
local trap_status="$?"
local status="${EXIT_STATUS}"
if [ "${status}" -eq 0 ]; then
status="${trap_status}"
fi
if [ "${#STEP_PIDS[@]}" -gt 0 ]; then
stop_running_steps
fi
exec 3>&- 3<&- || true
rm -rf "${LOG_DIR}"
exit "${status}"
}
on_interrupt() {
EXIT_STATUS=130
exit 130
}
on_terminate() {
EXIT_STATUS=143
exit 143
}
stop_running_steps() {
local pid=""
if [ "${#STEP_PIDS[@]}" -eq 0 ]; then
return
fi
for pid in "${STEP_PIDS[@]}"; do
if [ -n "${pid}" ]; then
kill -TERM -- "-${pid}" 2>/dev/null || true
fi
done
sleep 1
for pid in "${STEP_PIDS[@]}"; do
if [ -n "${pid}" ]; then
# A process group can remain alive after its leader exits, so escalate by group id unconditionally.
kill -KILL -- "-${pid}" 2>/dev/null || true
fi
done
for pid in "${STEP_PIDS[@]}"; do
if [ -n "${pid}" ]; then
wait "${pid}" 2>/dev/null || true
fi
done
STEP_PIDS=()
STEP_NAMES=()
STEP_LOGS=()
STEP_STARTS=()
RUNNING_STEPS=0
}
find_step_index() {
local target_name="$1"
local idx=""
for idx in "${!STEP_NAMES[@]}"; do
if [ "${STEP_NAMES[$idx]}" = "${target_name}" ]; then
echo "${idx}"
return 0
fi
done
return 1
}
clear_step() {
local idx="$1"
STEP_PIDS[$idx]=""
STEP_NAMES[$idx]=""
STEP_LOGS[$idx]=""
STEP_STARTS[$idx]=""
RUNNING_STEPS=$((RUNNING_STEPS - 1))
}
step_pid_is_alive() {
local pid="$1"
local state=""
if ! kill -0 "${pid}" 2>/dev/null; then
return 1
fi
state="$(ps -o stat= -p "${pid}" 2>/dev/null | tr -d '[:space:]')"
case "${state}" in
Z*|z*|"")
return 1
;;
esac
return 0
}
print_heartbeat() {
local now
local idx=""
local name=""
local start_time=""
local elapsed=""
local running=""
now=$(date +%s)
for idx in "${!STEP_NAMES[@]}"; do
name="${STEP_NAMES[$idx]}"
start_time="${STEP_STARTS[$idx]}"
if [ -z "${name}" ]; then
continue
fi
elapsed=$((now - start_time))
if [ -n "${running}" ]; then
running="${running}, "
fi
running="${running}${name} (${elapsed}s)"
done
if [ -n "${running}" ]; then
echo "code-change-verification: still running: ${running}."
fi
}
start_step() {
local name="$1"
shift
local log_file="${LOG_DIR}/${name}.log"
echo "Running make ${name}..."
: > "${log_file}"
# Start each step in its own process group so fail-fast cleanup can stop pytest worker trees too.
"${STEP_LAUNCHER[@]}" \
bash -c '
step_name="$1"
log_file="$2"
status_pipe="$3"
shift 3
if "$@" >"$log_file" 2>&1; then
status=0
else
status=$?
fi
printf "%s\t%s\n" "$step_name" "$status" >"$status_pipe"
exit "$status"
' \
bash "${name}" "${log_file}" "${STATUS_PIPE}" "$@" &
STEP_PIDS+=("$!")
STEP_NAMES+=("${name}")
STEP_LOGS+=("${log_file}")
STEP_STARTS+=("$(date +%s)")
RUNNING_STEPS=$((RUNNING_STEPS + 1))
}
finish_step() {
local name="$1"
local status="$2"
local idx=""
local pid=""
local log_file=""
local start_time=""
local now
idx="$(find_step_index "${name}")"
pid="${STEP_PIDS[$idx]}"
log_file="${STEP_LOGS[$idx]}"
start_time="${STEP_STARTS[$idx]}"
now=$(date +%s)
wait "${pid}" 2>/dev/null || true
if [ "${status}" -eq 0 ]; then
clear_step "${idx}"
echo "make ${name} passed in $((now - start_time))s."
return 0
fi
echo "code-change-verification: make ${name} failed with exit code ${status} after $((now - start_time))s." >&2
echo "--- ${name} log (last 80 lines) ---" >&2
tail -n 80 "${log_file}" >&2 || true
stop_running_steps
return "${status}"
}
check_for_missing_reporters() {
local idx=""
local pid=""
local name=""
local log_file=""
local start_time=""
local now
local step_status=0
for idx in "${!STEP_PIDS[@]}"; do
pid="${STEP_PIDS[$idx]}"
if [ -z "${pid}" ] || step_pid_is_alive "${pid}"; then
continue
fi
if try_finish_step_from_status_pipe 1; then
if [ "${STATUS_PIPE_DRAINED}" -eq 1 ]; then
return 0
fi
else
step_status=$?
return "${step_status}"
fi
name="${STEP_NAMES[$idx]}"
log_file="${STEP_LOGS[$idx]}"
start_time="${STEP_STARTS[$idx]}"
now=$(date +%s)
set +e
wait "${pid}" 2>/dev/null
step_status=$?
set -e
if [ "${step_status}" -eq 0 ]; then
finish_step "${name}" 0
return 0
fi
echo "code-change-verification: make ${name} exited before reporting completion status after $((now - start_time))s." >&2
echo "--- ${name} log (last 80 lines) ---" >&2
tail -n 80 "${log_file}" >&2 || true
stop_running_steps
return "${step_status}"
done
return 0
}
STATUS_PIPE_DRAINED=0
try_finish_step_from_status_pipe() {
local timeout="$1"
local name=""
local status=""
local step_status=0
STATUS_PIPE_DRAINED=0
if ! IFS=$'\t' read -r -t "${timeout}" name status <&3; then
return 0
fi
STATUS_PIPE_DRAINED=1
finish_step "${name}" "${status}"
step_status=$?
if [ "${step_status}" -ne 0 ]; then
return "${step_status}"
fi
return 0
}
wait_for_parallel_steps() {
local name=""
local status=""
local step_status=""
local next_heartbeat_at
local now
next_heartbeat_at=$(( $(date +%s) + HEARTBEAT_INTERVAL_SECONDS ))
while [ "${RUNNING_STEPS}" -gt 0 ]; do
if try_finish_step_from_status_pipe 1; then
if [ "${STATUS_PIPE_DRAINED}" -eq 1 ]; then
continue
fi
else
step_status=$?
if [ "${step_status}" -ne 0 ]; then
return "${step_status}"
fi
continue
fi
check_for_missing_reporters
step_status=$?
if [ "${step_status}" -ne 0 ]; then
return "${step_status}"
fi
now=$(date +%s)
if [ "${now}" -ge "${next_heartbeat_at}" ]; then
print_heartbeat
next_heartbeat_at=$((now + HEARTBEAT_INTERVAL_SECONDS))
fi
done
}
trap cleanup EXIT
trap on_interrupt INT
trap on_terminate TERM
echo "Running make format..."
set +e
make format
EXIT_STATUS=$?
set -e
if [ "${EXIT_STATUS}" -ne 0 ]; then
exit "${EXIT_STATUS}"
fi
echo "Running make lint, make typecheck, and make tests in parallel..."
start_step "lint" make lint
start_step "typecheck" make typecheck
start_step "tests" make tests
set +e
wait_for_parallel_steps
EXIT_STATUS=$?
set -e
if [ "${EXIT_STATUS}" -ne 0 ]; then
exit "${EXIT_STATUS}"
fi
trap - EXIT INT TERM
exec 3>&- 3<&-
rm -rf "${LOG_DIR}"
echo "code-change-verification: all commands passed."