release/1.4.3

.github/WORKFLOWS.md

@@ -0,0 +1,111 @@
+# Workflow Conventions
+
+> Canonical reference for all GitHub Actions conventions in SmartHopper.
+> Every contributor and every new workflow **must** follow these rules.
+
+## Branch Protection Model
+
+| Pattern | Protection |
+|---------|-----------|
+| `main`, `main-*` | PR + codeowner approval required |
+| `dev`, `dev-*` | PR + codeowner approval required |
+| `hotfix/*` | PR + codeowner approval required |
+| `release/**` | PR + codeowner approval required |
+
+**No workflow may push directly to a protected branch.** All automated
+changes must go through a PR created by `peter-evans/create-pull-request@v6`
+(preferred) or `gh pr create`.
+
+## Action Version Pinning
+
+| Action | Pin style |
+|--------|-----------|
+| First-party (`actions/*`) | **Tag** — e.g. `actions/checkout@v4` |
+| Third-party (community) | **Tag** — e.g. `peter-evans/create-pull-request@v6` |
+| Local composite actions | **Path** — e.g. `./.github/actions/…` |
+
+Do **not** use SHA pinning (`@abc123…`). Tag pinning is easier to audit
+and auto-update with Dependabot.
+
+## PR Creation Convention
+
+Use `peter-evans/create-pull-request@v6` for chore workflows that modify
+files in the working tree. Use `gh pr create` only when constructing PRs
+from existing branches (e.g. release pipeline).
+
+Every automated PR must:
+1. Carry the `automated` label.
+2. Call `./.github/actions/milestone/assign-pr` to assign the current milestone.
+3. Call `./.github/actions/dispatch-required-pr-checks` to trigger status checks.
+
+## Concurrency & `cancel-in-progress`
+
+| Workflow type | `cancel-in-progress` | Rationale |
+|---------------|---------------------|-----------|
+| PR validation / CI checks | `true` | Superseded by newer pushes |
+| Chore (version-date, badge, manifest, …) | `false` | Must complete to avoid stale state |
+| Release pipeline (`release-1` … `release-6`) | `false` | Irreversible side-effects |
+| Issue/label management | `false` | Quick, idempotent |
+
+## Timeout Policy
+
+Every job **must** declare `timeout-minutes`. Defaults:
+
+| Job type | Timeout |
+|----------|---------|
+| Lightweight (label, comment, branch delete) | 5 min |
+| Standard (checkout + script) | 10 min |
+| Build / test (.NET CI) | 30 min |
+| Heavy (model fetch, AI generation) | 45 min |
+
+## PowerShell Conventions
+
+When a workflow step uses `shell: pwsh`, call scripts with the `&`
+(call operator), **not** by spawning a nested `pwsh` process:
+
+```yaml
+# Good
+shell: pwsh
+run: |
+  & .\tools\My-Script.ps1 -Param value
+
+# Bad — spawns a child pwsh inside the pwsh shell
+shell: pwsh
+run: |
+  pwsh -ExecutionPolicy Bypass -File .\tools\My-Script.ps1 -Param value
+```
+
+## Validation Tiers
+
+### Provider Model Validation (`Update-ProviderModels.ps1`)
+
+| Tier | Severity | Blocks merge? | Examples |
+|------|----------|---------------|----------|
+| Error | `::error::` | Yes | Invalid capability expression, realtime model in list, pending capability |
+| Warning | `::warning::` | No | Missing default for a composite capability category |
+
+### PR Validation (`pr-validation.yml`)
+
+| Check | Blocks merge? | Notes |
+|-------|---------------|-------|
+| Version format | Yes | Must be valid semver |
+| Code style | Yes | Trailing whitespace, namespace, using order |
+| Changelog | **Warning only** | Skipped for `chore/ci/style/build/revert/docs` PRs |
+| PR title | Yes | Must follow conventional commits |
+
+## Node.js Runtime
+
+Set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true` as a repository-level
+environment variable (or in individual workflows) to opt into Node.js 24
+before the June 2026 deadline.
+
+## Cross-Reference Comments
+
+When two workflows overlap in trigger or purpose, each must carry a
+header comment referencing the other. Example:
+
+```yaml
+# Related workflows:
+#   - chore-version-date.yml (updates version date on dev pushes)
+#   - chore-version-badge.yml (updates README badge on version change)
+```

.github/actions/ai/fetch-models/action.yml

@@ -0,0 +1,142 @@
+# Reusable action that delegates to tools/Update-ProviderModels.ps1.
+# OpenRouter is used as the single source of truth; the script queries
+# OpenRouter's /models endpoint, filters by provider prefix, and updates
+# the *ProviderModels.cs file with full capabilities mapped from metadata.
+#
+# Usage:
+#   - uses: ./.github/actions/ai/fetch-models
+#     with:
+#       provider: OpenAI
+#       api-key: ${{ secrets.OPENROUTER_API_KEY }}
+#       update-file: true
+
+name: 'Fetch AI Provider Models'
+description: 'Fetch model metadata from OpenRouter and update *ProviderModels.cs via the centralized Update-ProviderModels.ps1 tool'
+
+inputs:
+  provider:
+    description: 'Provider identifier (e.g. OpenAI, MistralAI, Anthropic, OpenRouter, DeepSeek)'
+    required: true
+  api-key:
+    description: 'OpenRouter API key (used as the single source of truth for all providers)'
+    required: true
+  provider-api-key:
+    description: 'Optional native API key for the target provider. When supplied, the provider''s own /models endpoint is queried as a secondary authoritative source (alias merging, deprecation flags). OpenRouter remains the metadata source of truth.'
+    required: false
+    default: ''
+  update-file:
+    description: 'When true, the script rewrites the source file: auto-inserts new models with capabilities mapped from OpenRouter metadata, updates existing model capabilities/ContextLimit, and marks disappeared or expiring models as Deprecated = true'
+    required: false
+    default: 'false'
+  fail-on-validation-errors:
+    description: 'When true, fail if updated provider models are missing required defaults, contain pending capabilities, or contain realtime models'
+    required: false
+    default: 'false'
+
+outputs:
+  models:
+    description: 'JSON array of model ID strings returned by the API'
+    value: ${{ steps.run.outputs.models }}
+  count:
+    description: 'Number of distinct models returned'
+    value: ${{ steps.run.outputs.count }}
+  success:
+    description: 'Whether the operation succeeded'
+    value: ${{ steps.run.outputs.success }}
+  error:
+    description: 'Error message if the call failed'
+    value: ${{ steps.run.outputs.error }}
+  report:
+    description: 'Full JSON report emitted by Update-ProviderModels.ps1'
+    value: ${{ steps.run.outputs.report }}
+  changed:
+    description: 'Whether the source file was modified'
+    value: ${{ steps.run.outputs.changed }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Run Update-ProviderModels.ps1
+      id: run
+      shell: pwsh
+      env:
+        API_KEY: ${{ inputs.api-key }}
+        PROVIDER_API_KEY: ${{ inputs.provider-api-key }}
+      run: |
+        $ErrorActionPreference = 'Stop'
+
+        $params = @{
+          Provider = '${{ inputs.provider }}'
+          ApiKey   = $env:API_KEY
+        }
+        if (-not [string]::IsNullOrWhiteSpace($env:PROVIDER_API_KEY)) {
+          $params['ProviderApiKey'] = $env:PROVIDER_API_KEY
+        }
+        if ('${{ inputs.update-file }}' -eq 'true') {
+          $params['UpdateFile'] = $true
+        }
+        if ('${{ inputs.fail-on-validation-errors }}' -eq 'true') {
+          $params['FailOnValidationErrors'] = $true
+        }
+
+        try {
+          $reportJson = & .\tools\Update-ProviderModels.ps1 @params
+          $scriptExit = $LASTEXITCODE
+
+          # The script emits its JSON report on stdout regardless of validation
+          # outcome. Try to parse it even on non-zero exit so we can surface the
+          # validation details (the script also writes ::error:: annotations,
+          # but exposing the structured report lets the caller decide what to do).
+          $report = $null
+          if ($reportJson) {
+            try { $report = $reportJson | ConvertFrom-Json } catch { $report = $null }
+          }
+
+          if ($scriptExit -ne 0) {
+            Write-Host "::error::Update-ProviderModels.ps1 exited with code $scriptExit"
+            "success=false" >> $env:GITHUB_OUTPUT
+            "error=Update-ProviderModels.ps1 exited with code $scriptExit" >> $env:GITHUB_OUTPUT
+            "changed=false" >> $env:GITHUB_OUTPUT
+            "count=0" >> $env:GITHUB_OUTPUT
+            "models=[]" >> $env:GITHUB_OUTPUT
+            if ($report) {
+              "report<<EOF_REPORT" >> $env:GITHUB_OUTPUT
+              "$reportJson" >> $env:GITHUB_OUTPUT
+              "EOF_REPORT" >> $env:GITHUB_OUTPUT
+            } else {
+              "report={}" >> $env:GITHUB_OUTPUT
+            }
+            exit $scriptExit
+          }
+
+          $modelsJson = ($report.apiModels | ConvertTo-Json -Compress)
+          if ($modelsJson -eq 'null') { $modelsJson = '[]' }
+
+          "success=true"   >> $env:GITHUB_OUTPUT
+          "error="         >> $env:GITHUB_OUTPUT
+          "changed=$($report.fileUpdated)" >> $env:GITHUB_OUTPUT
+          "count=$($report.apiModels.Count)" >> $env:GITHUB_OUTPUT
+
+          "models<<EOF_MODELS" >> $env:GITHUB_OUTPUT
+          "$modelsJson" >> $env:GITHUB_OUTPUT
+          "EOF_MODELS" >> $env:GITHUB_OUTPUT
+
+          "report<<EOF_REPORT" >> $env:GITHUB_OUTPUT
+          "$reportJson" >> $env:GITHUB_OUTPUT
+          "EOF_REPORT" >> $env:GITHUB_OUTPUT
+        }
+        catch {
+          # Print the failure visibly. The previous implementation wrote the
+          # message to $env:GITHUB_OUTPUT only, which hid the actual cause from
+          # the run log and made these jobs near-impossible to diagnose.
+          Write-Host "::error::Update-ProviderModels.ps1 failed: $($_.Exception.Message)"
+          if ($_.ScriptStackTrace) { Write-Host $_.ScriptStackTrace }
+
+          "success=false" >> $env:GITHUB_OUTPUT
+          "error=$($_.Exception.Message)" >> $env:GITHUB_OUTPUT
+          "changed=false" >> $env:GITHUB_OUTPUT
+          "count=0" >> $env:GITHUB_OUTPUT
+          "models=[]" >> $env:GITHUB_OUTPUT
+          "report={}" >> $env:GITHUB_OUTPUT
+          exit 1
+        }

.github/actions/ai/mistral-chat/action.yml

@@ -0,0 +1,129 @@
+# Generic, reusable Mistral AI Chat Completions API wrapper.
+# This action is a raw API client with no domain-specific logic.
+# It can be used by any workflow that needs AI text generation capabilities.
+
+name: 'Mistral AI Chat'
+description: 'Generic wrapper around the Mistral AI Chat Completions API'
+
+inputs:
+  api-key:
+    description: 'Mistral AI API key'
+    required: true
+  model:
+    description: 'Mistral model name'
+    required: false
+    default: 'mistral-medium-latest'
+  system-prompt:
+    description: 'System message content'
+    required: false
+    default: ''
+  user-prompt:
+    description: 'User message content'
+    required: true
+  temperature:
+    description: 'Sampling temperature'
+    required: false
+    default: '0.7'
+  max-tokens:
+    description: 'Maximum tokens in response'
+    required: false
+    default: '4096'
+
+outputs:
+  response:
+    description: 'Raw text content from the API response'
+    value: ${{ steps.call_api.outputs.response }}
+  usage-prompt-tokens:
+    description: 'Prompt tokens used'
+    value: ${{ steps.call_api.outputs.usage-prompt-tokens }}
+  usage-completion-tokens:
+    description: 'Completion tokens used'
+    value: ${{ steps.call_api.outputs.usage-completion-tokens }}
+  success:
+    description: 'Whether the API call succeeded'
+    value: ${{ steps.call_api.outputs.success }}
+  error:
+    description: 'Error message if the call failed'
+    value: ${{ steps.call_api.outputs.error }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Call Mistral AI API
+      id: call_api
+      shell: bash
+      env:
+        API_KEY: ${{ inputs.api-key }}
+        MODEL: ${{ inputs.model }}
+        SYSTEM_PROMPT: ${{ inputs.system-prompt }}
+        USER_PROMPT: ${{ inputs.user-prompt }}
+        TEMPERATURE: ${{ inputs.temperature }}
+        MAX_TOKENS: ${{ inputs.max-tokens }}
+      run: |
+        # Build JSON payload using jq to safely handle special characters
+        PAYLOAD=$(jq -n \
+          --arg model "$MODEL" \
+          --arg system "$SYSTEM_PROMPT" \
+          --arg user "$USER_PROMPT" \
+          --argjson temperature "$TEMPERATURE" \
+          --argjson max_tokens "$MAX_TOKENS" \
+          '{
+            model: $model,
+            messages: (
+              if ($system | length) > 0
+              then [{role: "system", content: $system}, {role: "user", content: $user}]
+              else [{role: "user", content: $user}]
+              end
+            ),
+            temperature: $temperature,
+            max_tokens: $max_tokens
+          }')
+
+        # Call the API
+        HTTP_RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "https://api.mistral.ai/v1/chat/completions" \
+          -H "Content-Type: application/json" \
+          -H "Authorization: Bearer $API_KEY" \
+          -d "$PAYLOAD")
+
+        # Split body and status code
+        HTTP_BODY=$(echo "$HTTP_RESPONSE" | sed '$d')
+        HTTP_STATUS=$(echo "$HTTP_RESPONSE" | tail -n 1)
+
+        if [ "$HTTP_STATUS" -eq 200 ]; then
+          # Extract response content
+          CONTENT=$(echo "$HTTP_BODY" | jq -r '.choices[0].message.content // empty')
+          PROMPT_TOKENS=$(echo "$HTTP_BODY" | jq -r '.usage.prompt_tokens // 0')
+          COMPLETION_TOKENS=$(echo "$HTTP_BODY" | jq -r '.usage.completion_tokens // 0')
+
+          if [ -z "$CONTENT" ]; then
+            echo "::warning::Mistral API call succeeded but returned empty content"
+            echo "success=false" >> "$GITHUB_OUTPUT"
+            echo "error=API returned empty content" >> "$GITHUB_OUTPUT"
+            echo "response=" >> "$GITHUB_OUTPUT"
+            echo "usage-prompt-tokens=0" >> "$GITHUB_OUTPUT"
+            echo "usage-completion-tokens=0" >> "$GITHUB_OUTPUT"
+          else
+            echo "success=true" >> "$GITHUB_OUTPUT"
+            echo "error=" >> "$GITHUB_OUTPUT"
+            {
+              echo "response<<EOF_MISTRAL_RESPONSE"
+              echo "$CONTENT"
+              echo "EOF_MISTRAL_RESPONSE"
+            } >> "$GITHUB_OUTPUT"
+            echo "usage-prompt-tokens=$PROMPT_TOKENS" >> "$GITHUB_OUTPUT"
+            echo "usage-completion-tokens=$COMPLETION_TOKENS" >> "$GITHUB_OUTPUT"
+          fi
+        else
+          # Error handling
+          ERROR_MSG=$(echo "$HTTP_BODY" | head -c 500)
+          echo "::warning::Mistral API call failed: HTTP $HTTP_STATUS - $ERROR_MSG"
+          echo "success=false" >> "$GITHUB_OUTPUT"
+          {
+            echo "error<<EOF_MISTRAL_ERROR"
+            echo "HTTP $HTTP_STATUS: $ERROR_MSG"
+            echo "EOF_MISTRAL_ERROR"
+          } >> "$GITHUB_OUTPUT"
+          echo "response=" >> "$GITHUB_OUTPUT"
+          echo "usage-prompt-tokens=0" >> "$GITHUB_OUTPUT"
+          echo "usage-completion-tokens=0" >> "$GITHUB_OUTPUT"
+        fi