ecoportal-api-v2 3.3.2 → 3.3.3

data/scripts/auto-worker-scheduler.sh

@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+# auto-worker-scheduler.sh
+# Scheduler for auto-todo-worker. Called by the Claude Code Stop hook.
+# Reads local config, checks token budget and conflict guard, then
+# launches the worker as a background process if all gates pass.
+#
+# Log format: TIMESTAMP | ACTION | REASON
+# Log file:   .ai-assistance/local/auto-worker-changes.log
+#
+# Usage: bash scripts/auto-worker-scheduler.sh
+#        (called automatically by Stop hook — no arguments)
+#
+# Requires: jq (for JSON parsing). Falls back to grep/sed on missing jq.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Paths (all relative — script must be run from repo root)
+# ---------------------------------------------------------------------------
+TOKEN_BUDGET_JSON=".ai-assistance/token-budget.json"
+LAST_RUN_JSON=".ai-assistance/local/auto-worker-last-run.json"
+SESSION_LOCK=".ai-assistance/local/session.lock"
+CHANGES_LOG=".ai-assistance/local/auto-worker-changes.log"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# ai_log_usage <component> <action> <detail> [session_id]
+# Inline copy — scheduler is self-contained; common.sh is not sourced here.
+# Never fails fatally; all errors suppressed.
+ai_log_usage() {
+  local component="${1:-unknown}"
+  local action="${2:-run}"
+  local detail="${3:-}"
+  local session_id="${4:-}"
+  local log_dir=".ai-assistance/local/kpi"
+  local week
+  week=$(date +%Y-W%V 2>/dev/null || echo "unknown")
+  local log_file="${log_dir}/usage-${week}.jsonl"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "unknown")
+  mkdir -p "$log_dir" 2>/dev/null || true
+  printf '{"component":"%s","action":"%s","detail":"%s","ts":"%s","session_id":"%s"}\n' \
+    "$component" "$action" "$detail" "$ts" "$session_id" >> "$log_file" 2>/dev/null || true
+}
+
+log_action() {
+  local action="$1"
+  local reason="$2"
+  local ts
+  ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ")
+  mkdir -p "$(dirname "$CHANGES_LOG")"
+  printf "%s | %s | %s\n" "$ts" "$action" "$reason" >> "$CHANGES_LOG"
+}
+
+# Read a JSON field using jq if available, otherwise grep+sed fallback.
+# Usage: json_field <file> <dotted.key>   e.g. json_field config.json auto_worker.enabled
+json_field() {
+  local file="$1"
+  local key="$2"
+  if command -v jq >/dev/null 2>&1; then
+    jq -r ".${key} // empty" "$file" 2>/dev/null
+  else
+    # Minimal fallback: grep for the last segment key, extract bare value.
+    local leaf
+    leaf=$(printf '%s' "$key" | sed 's/.*\.//')
+    grep -o "\"${leaf}\"[[:space:]]*:[[:space:]]*[^,}]*" "$file" 2>/dev/null \
+      | tail -1 \
+      | sed 's/.*:[[:space:]]*//' \
+      | tr -d '"' \
+      | tr -d ' '
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Gate 1: auto_worker.enabled
+# ---------------------------------------------------------------------------
+
+if [ ! -f "$TOKEN_BUDGET_JSON" ]; then
+  log_action "SKIP" "token-budget.json not found — auto_worker not configured"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "auto_worker not enabled -- token-budget.json not found"
+  exit 0
+fi
+
+enabled=$(json_field "$TOKEN_BUDGET_JSON" "auto_worker.enabled")
+if [ "$enabled" != "true" ]; then
+  log_action "SKIP" "auto_worker.enabled is false or absent in token-budget.json"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "auto_worker not enabled"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 2: Conflict guard — check for active Claude session via session.lock
+# ---------------------------------------------------------------------------
+
+if [ -f "$SESSION_LOCK" ]; then
+  lock_content=""
+  if [ -r "$SESSION_LOCK" ]; then
+    lock_content=$(cat "$SESSION_LOCK" 2>/dev/null || true)
+  fi
+  log_action "SKIP" "Active Claude session detected (session.lock present: ${lock_content})"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "session.lock present"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 3: Token budget threshold check
+# ---------------------------------------------------------------------------
+# Find the current ISO week KPI file. Format: weekly-YYYY-WNN.json
+# We compute ISO week ourselves for portability.
+
+iso_week() {
+  # Returns YYYY-WNN string for today (ISO 8601 week numbering)
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c "
+import datetime
+today = datetime.date.today()
+iso = today.isocalendar()
+print('%04d-W%02d' % (iso[0], iso[1]))
+"
+  elif command -v python >/dev/null 2>&1; then
+    python -c "
+import datetime
+today = datetime.date.today()
+iso = today.isocalendar()
+print('%04d-W%02d' % (iso[0], iso[1]))
+"
+  else
+    # Fallback: use date command Week-of-year (not strictly ISO but close enough)
+    date +"%Y-W%V" 2>/dev/null || date +"%Y-W%U"
+  fi
+}
+
+KPI_DIR=".ai-assistance/local/kpi"
+WEEK_KEY=$(iso_week)
+KPI_FILE="${KPI_DIR}/weekly-${WEEK_KEY}.json"
+
+# Read quota and usage from KPI file (if present)
+weekly_tokens_used=0
+weekly_quota=0
+window_start_ts=""   # ISO timestamp of first session start in current 5-hour window
+
+if [ -f "$KPI_FILE" ] && command -v jq >/dev/null 2>&1; then
+  # Sum tokens_used across all sessions
+  weekly_tokens_used=$(jq '[.sessions[]?.tokens_used // 0] | add // 0' "$KPI_FILE" 2>/dev/null || echo "0")
+  weekly_quota=$(jq -r '.quota // 0' "$KPI_FILE" 2>/dev/null || echo "0")
+
+  # Find most recent session start to compute reset window
+  window_start_ts=$(jq -r '
+    [.sessions[]?.session_start // empty] | sort | last // empty
+  ' "$KPI_FILE" 2>/dev/null || true)
+fi
+
+# Read quota from token-budget.json as fallback
+if [ "$weekly_quota" = "0" ] || [ -z "$weekly_quota" ]; then
+  quota_from_config=$(json_field "$TOKEN_BUDGET_JSON" "weekly_quota.total_tokens")
+  if [ "$quota_from_config" != "null" ] && [ -n "$quota_from_config" ]; then
+    weekly_quota="$quota_from_config"
+  fi
+fi
+
+# If no quota is set (null), skip the threshold gate entirely
+if [ "$weekly_quota" = "0" ] || [ "$weekly_quota" = "null" ] || [ -z "$weekly_quota" ]; then
+  log_action "OK" "No weekly quota set — skipping token threshold gate"
+else
+  # Calculate usage percentage
+  if command -v python3 >/dev/null 2>&1; then
+    usage_pct=$(python3 -c "
+used = float('${weekly_tokens_used}' or '0')
+quota = float('${weekly_quota}')
+print('%.1f' % (used / quota * 100) if quota > 0 else '0')
+")
+  else
+    usage_pct=0
+  fi
+
+  # Determine time remaining in current 5-hour reset window
+  # 5-hour window = 18000 seconds
+  window_seconds_elapsed=0
+  if [ -n "$window_start_ts" ] && command -v python3 >/dev/null 2>&1; then
+    window_seconds_elapsed=$(python3 -c "
+import datetime, sys
+try:
+    ts = '${window_start_ts}'.replace('Z', '+00:00')
+    start = datetime.datetime.fromisoformat(ts)
+    now = datetime.datetime.now(datetime.timezone.utc)
+    elapsed = (now - start).total_seconds()
+    print(int(max(0, elapsed)))
+except Exception:
+    print(0)
+")
+  fi
+
+  WINDOW_DURATION=18000   # 5 hours in seconds
+  window_remaining=$(( WINDOW_DURATION - window_seconds_elapsed ))
+  if [ "$window_remaining" -lt 0 ]; then
+    window_remaining=0
+  fi
+  window_remaining_min=$(( window_remaining / 60 ))
+
+  # Determine threshold based on time remaining in window (ADR-007 table)
+  # >120 min -> 65%; 60-120 -> 75%; 45-60 -> 80%; 30-45 -> 90%; 15-30 -> 95%; <15 -> skip
+  if [ "$window_remaining_min" -lt 15 ]; then
+    log_action "SKIP" "Less than 15 min remaining in token reset window — will not launch"
+    ai_log_usage "script/auto-worker-scheduler" "skip" "token budget -- less than 15 min remaining in reset window"
+    exit 0
+  elif [ "$window_remaining_min" -lt 30 ]; then
+    threshold=95
+  elif [ "$window_remaining_min" -lt 45 ]; then
+    threshold=90
+  elif [ "$window_remaining_min" -lt 60 ]; then
+    threshold=80
+  elif [ "$window_remaining_min" -lt 120 ]; then
+    threshold=75
+  else
+    threshold=65
+  fi
+
+  # Compare usage_pct against threshold (integer comparison via python3)
+  if command -v python3 >/dev/null 2>&1; then
+    over_threshold=$(python3 -c "
+pct = float('${usage_pct}' or '0')
+thr = float('${threshold}')
+print('true' if pct >= thr else 'false')
+")
+  else
+    over_threshold="false"
+  fi
+
+  if [ "$over_threshold" = "true" ]; then
+    log_action "SKIP" "Token usage ${usage_pct}% >= threshold ${threshold}% (${window_remaining_min} min remaining in window)"
+    ai_log_usage "script/auto-worker-scheduler" "skip" "token budget at ${usage_pct}% (threshold ${threshold}%)"
+    exit 0
+  fi
+
+  log_action "OK" "Token gate passed: ${usage_pct}% used, threshold ${threshold}% (${window_remaining_min} min remaining)"
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 4: Determine cadence (informational — actual cron cadence managed by
+# CronCreate; this script just logs the recommendation)
+# ---------------------------------------------------------------------------
+
+recommended_cadence="2hr"
+if [ -f "$LAST_RUN_JSON" ] && command -v jq >/dev/null 2>&1; then
+  completed_count=$(jq '.completed | length' "$LAST_RUN_JSON" 2>/dev/null || echo "0")
+  if [ "$completed_count" -gt "0" ]; then
+    recommended_cadence="30min"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 5: dangerously_skip_permissions opt-in
+# ---------------------------------------------------------------------------
+
+skip_perms=$(json_field "$TOKEN_BUDGET_JSON" "auto_worker.dangerously_skip_permissions")
+AUTO_WORKER_PROMPT="Run the auto-worker for this repo.
+
+Instructions:
+1. Read TODO.md and collect all items tagged \`[auto]\` or \`[auto:last]\`.
+2. If no \`[auto]\` items exist, exit cleanly with a brief log entry.
+3. Plan execution order as a dependency graph — do NOT follow TODO list order.
+   - Items without dependencies on each other may run in parallel (branch out when the work is self-contained enough to isolate).
+   - \`[auto:last]\` items run only after all \`[auto]\` items complete or are skipped.
+4. For each item:
+   - Execute the task.
+   - Mark it \`[x]\` in TODO.md on completion.
+   - Add any discovered follow-up tasks as new TODO items; tag \`[auto]\` only if they meet the eligibility criteria in standards/tooling/auto-worker-eligibility.md.
+5. Do NOT touch items that are not tagged \`[auto]\` or \`[auto:last]\`.
+6. At the end, write a one-paragraph summary of what was done, skipped, and added to TODO."
+
+CLAUDE_FLAGS="--print \"${AUTO_WORKER_PROMPT}\""
+if [ "$skip_perms" = "true" ]; then
+  CLAUDE_FLAGS="--dangerously-skip-permissions --print \"${AUTO_WORKER_PROMPT}\""
+fi
+
+# ---------------------------------------------------------------------------
+# Launch: run auto-todo-worker as a background process
+# ---------------------------------------------------------------------------
+
+log_action "LAUNCH" "Launching auto-todo-worker (cadence recommendation: ${recommended_cadence})"
+ai_log_usage "script/auto-worker-scheduler" "launch" "launching auto-todo-worker"
+
+if [[ "${OSTYPE:-}" == "msys" ]] || [[ "${OSTYPE:-}" == "cygwin" ]] || \
+   [[ "${OS:-}" == "Windows_NT" ]]; then
+  # Windows via Git Bash / WSL
+  # Use PowerShell Start-Process to launch detached from the current terminal
+  powershell -Command "Start-Process -FilePath 'claude' \
+    -ArgumentList '${CLAUDE_FLAGS}' \
+    -WorkingDirectory '${PWD}' \
+    -NoNewWindow" &
+  launch_pid=$!
+else
+  # Unix / macOS / WSL2
+  if [ "$skip_perms" = "true" ]; then
+    nohup claude --dangerously-skip-permissions --print "run auto worker" \
+      > ".ai-assistance/local/auto-worker-stdout.log" 2>&1 &
+  else
+    nohup claude --print "run auto worker" \
+      > ".ai-assistance/local/auto-worker-stdout.log" 2>&1 &
+  fi
+  launch_pid=$!
+fi
+
+log_action "LAUNCHED" "Background PID ${launch_pid:-unknown} — flags: ${CLAUDE_FLAGS}"
+exit 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 3.3.2
+  version: 3.3.3
 platform: ruby
 authors:
 - Oscar Segura
@@ -171,6 +171,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ai-assistance/code/double_model_patterns.md"
+- ".ai-assistance/conventions/code-working-tree-protocol.md"
+- ".ai-assistance/scripts/token-logger.js"
+- ".ai-assistance/scripts/token-report.ts"
+- ".ai-assistance/scripts/token-session-start.js"
+- ".ai-assistance/skills/eP_AI_Manager/SKILL.md"
+- ".ai-assistance/token-budget.json"
+- ".claude/settings.json"
 - ".gitignore"
 - ".markdownlint.json"
 - ".rspec"
@@ -328,6 +336,7 @@ files:
 - lib/ecoportal/api/v2/s3/files/poll_status.rb
 - lib/ecoportal/api/v2/s3/upload.rb
 - lib/ecoportal/api/v2_version.rb
+- scripts/auto-worker-scheduler.sh
 homepage: https://www.ecoportal.com
 licenses:
 - MIT