@data-matters.io/agent-harness 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-matters.io/agent-harness",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Spec-Driven Development with Claude Code: gates, task loop and standards installed into a product repository",
   "license": "UNLICENSED",
   "repository": {

package/templates/.harness/lib.sh

@@ -23,6 +23,10 @@ harness_load_env() {
   set +a
 }
 
+# The shared detection rule (ADR 0025, section 8): quota and gateway failures.
+# shellcheck source-path=SCRIPTDIR source=quota.sh
+. "$(dirname "${BASH_SOURCE[0]}")/quota.sh"
+
 # HARNESS_CLAUDE: the command that starts Claude Code for an agent session (an
 # array, so it works after `timeout`). The bot token and chat id are left out of
 # the session's environment: only notify.sh needs them, and it reads the env file
@@ -32,17 +36,39 @@ HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID -u
 
 # ------------------------------------------- optional API key (ADR 0020) --
 # harness_api_refused <session.json>: the session ended on an error that says
-# the Anthropic API key cannot serve it: no credit, a spend or usage limit, a
-# rate limit, billing, or an invalid key. Only an errored session counts, so a
-# task about authentication or billing never matches by its own words.
+# the API cannot serve it: no credit, a quota, a spend or usage limit, billing,
+# an invalid key, or the gateway itself failing (503 or another 5xx, a
+# connection failure, a timeout: ADR 0025, section 8a). A transient 429 ("try
+# again in a few seconds") is none of these. Only an errored session counts, so
+# a task about authentication or billing never matches by its own words.
 harness_api_refused() {
-  node -e "$harness_session_js"'
+  local text
+  text="$(node -e "$harness_session_js"'
     const raw = (() => { try { return require("fs").readFileSync(process.argv[1], "utf8"); } catch { return ""; } })();
     const d = session(process.argv[1]);
-    const text = Object.keys(d).length
+    process.stdout.write(Object.keys(d).length
       ? (d.is_error ? [d.result, d.api_error].filter((x) => typeof x === "string").join(" ") : "")
-      : raw;
-    process.exitCode = /credit balance|spend(ing)? limit|billing|usage limit|rate limit|out of usage|invalid api key|authentication/i.test(text) ? 0 : 1;' "$1" 2>/dev/null
+      : raw);' "$1" 2>/dev/null)" || return 1
+  [[ -n "$text" ]] || return 1
+  harness_api_unreachable "$text" && return 0
+  harness_quota_transient "$text" && return 1
+  harness_quota_exhausted "$text" && return 0
+  grep -qiE "credit balance|spend(ing)? limit|billing|usage limit|rate limit|out of usage|invalid api key|authentication" <<<"$text"
+}
+
+# ------------------------------------------------ machine mode (ADR 0025) --
+# harness_mode: api, plan or blocked, from the machine's mode file
+# (HARNESS_MODE_FILE, default ~/.local/state/harness/mode; its only writer is
+# the watchdog). A missing, unreadable or unrecognised file is api, the
+# preferred mode.
+harness_mode() {
+  local f="${HARNESS_MODE_FILE:-$HOME/.local/state/harness/mode}" line mode=api
+  if [[ -r "$f" ]]; then
+    while IFS= read -r line; do
+      [[ "$line" == mode=* ]] && mode="${line#mode=}"
+    done <"$f"
+  fi
+  case "$mode" in api|plan|blocked) echo "$mode" ;; *) echo api ;; esac
 }
 
 # harness_claude_session <timeout-seconds> <session.json> <claude args...>: runs
@@ -59,11 +85,30 @@ harness_api_refused() {
 # sees it. A key from a gateway without its base URL would be sent to the
 # Anthropic API and refused.
 harness_claude_session() {
-  local secs="$1" out="$2" key="${HARNESS_ANTHROPIC_API_KEY:-}" base="${HARNESS_ANTHROPIC_BASE_URL:-}" rc=0 prompt
+  local secs="$1" out="$2" key="${HARNESS_ANTHROPIC_API_KEY:-}" base="${HARNESS_ANTHROPIC_BASE_URL:-}" rc=0 prompt mode unset=()
   shift 2
   rm -f "$out.source"
-  if [[ -z "$key" ]]; then
-    timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
+  # The machine mode (ADR 0025) names the authentication to start on: api → the
+  # key and its base URL, plan → the account login with both removed, blocked →
+  # nothing runs. The fallback below stays as the net for a refusal that
+  # happens after the mode was read.
+  mode="$(harness_mode)"
+  if [[ "$mode" == blocked ]]; then
+    echo '{"type":"result","is_error":true,"api_error":"usage_limit_reached","result":"harness: the machine is blocked (the API does not respond and the account is out of usage); usage limit reached"}' >"$out"
+    return 1
+  fi
+  if [[ -z "$key" || "$mode" == plan ]]; then
+    # No key configured, or the API is down: the session is the account login,
+    # on the Anthropic API. A base URL left in the environment would point that
+    # login at a gateway, and a key must not reach it.
+    [[ -z "$key" ]] || unset=(-u ANTHROPIC_API_KEY)
+    [[ -z "$base" ]] || unset+=(-u ANTHROPIC_BASE_URL)
+    if (( ${#unset[@]} )); then
+      timeout "$secs" env "${unset[@]}" "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
+    else
+      timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
+    fi
+    [[ -z "$key" ]] || echo plan >"$out.source"
     return "$rc"
   fi
   prompt="$(mktemp)"
@@ -77,7 +122,7 @@ harness_claude_session() {
   K="$key" node -e 'const fs = require("fs"); const f = process.argv[1];
     try { const s = fs.readFileSync(f, "utf8"); if (s.includes(process.env.K)) fs.writeFileSync(f, s.split(process.env.K).join("[redacted]")); } catch {}' "$out" 2>/dev/null || true
   if (( rc != 124 )) && harness_api_refused "$out"; then
-    echo "harness: the API key was refused; repeating the session on the plan login" >&2
+    echo "harness: the API did not serve the session (refused, or the gateway failed); repeating it on the plan login" >&2
     rc=0
     if [[ -n "$base" ]]; then
       timeout "$secs" env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
@@ -157,9 +202,11 @@ harness_claude_flags() {
 # limit or on missing usage credits ("You're out of usage credits. Switch to
 # another model..."), not on the work. Claude Code names the window in the
 # message ("You've hit your 5-hour limit", "...your weekly limit", "...your
-# session limit") and sets api_error to usage_limit_reached, so both are matched.
+# session limit") and sets api_error to usage_limit_reached, so both are matched;
+# the gateway's Portuguese quota message is matched too, and its transient 429
+# is not (quota.sh, ADR 0025 section 8).
 harness_usage_error() {
-  grep -qiE "hit your [^\"]{0,40}limit|usage_limit_reached|usage limit reached|out of usage credits|credit balance is too low" "$1" 2>/dev/null
+  harness_quota_exhausted "$(cat -- "$1" 2>/dev/null)"
 }
 
 # harness_level_descend <level>: the level one below, for the fallback after a

package/templates/.harness/loop.sh

@@ -11,8 +11,10 @@
 # The supervisor runs run-tasks.sh --open-pr and reacts to its exit code:
 #   0  done        → notify with the PR link
 #   2  escalated   → notify; a human takes over
-#   3  paused (account usage limit; run-tasks discarded the partial attempt)
-#      → notify, wait HARNESS_RESUME_INTERVAL seconds (default 900), try again
+#   3  paused (usage limit, or the machine is blocked: the API does not respond
+#      and the account is out of usage; run-tasks discarded the partial attempt)
+#      → notify, wait HARNESS_RESUME_INTERVAL seconds (default 3600, in step
+#      with the watchdog's hourly probe, ADR 0025), try again
 #   4  stopped between two tasks (`stop --after-task`) → notify; restart later
 # run-tasks works in the change's own git worktree (ADR 0012): the checkout this
 # runs from is never switched or cleaned, so specs can be written meanwhile.
@@ -70,13 +72,20 @@ close_inherited_fds() {
 supervise() {
   local change="$1"; shift
   close_inherited_fds
-  local interval="${HARNESS_RESUME_INTERVAL:-900}" log=".harness/logs/$change/runner.log" rc pr every reason
+  local interval="${HARNESS_RESUME_INTERVAL:-3600}" log=".harness/logs/$change/runner.log" rc pr every reason
   mkdir -p ".harness/logs/$change"
   .harness/notify.sh started "Loop started for change $change"
   while true; do
     set +e
-    .harness/run-tasks.sh "$change" --open-pr "$@" >>"$log" 2>&1
-    rc=$?
+    if [[ "$(harness_mode)" == blocked ]]; then
+      # The machine is blocked (ADR 0025): pause as for a usage limit and look
+      # again after the interval, so the loop resumes when the mode changes.
+      echo "loop: the machine is blocked; not starting run-tasks" >>"$log"
+      rc=3
+    else
+      .harness/run-tasks.sh "$change" --open-pr "$@" >>"$log" 2>&1
+      rc=$?
+    fi
     set -e
     case "$rc" in
       0)
@@ -89,7 +98,7 @@ supervise() {
         break ;;
       3)
         if (( interval >= 60 )); then every="$((interval / 60)) min"; else every="${interval}s"; fi
-        .harness/notify.sh paused "Change $change paused by the account usage limit; retrying every $every"
+        .harness/notify.sh paused "Change $change paused (usage limit, or the API and the account are unavailable); retrying every $every"
         sleep "$interval"
         .harness/notify.sh resumed "Resuming change $change" ;;
       4)

package/templates/.harness/quota.sh

@@ -0,0 +1,56 @@
+# Quota and gateway-failure detection (ADR 0025, sections 5 and 8). Source it;
+# do not run it. Standalone on purpose: no dependency on lib.sh, so that a
+# wrapper can source it without pulling in the harness.
+# shellcheck shell=bash
+#
+# Two questions, answered separately:
+#   (a) did the API stop serving?   harness_api_unreachable <text>
+#       a gateway failure (5xx such as 503, a connection failure, a timeout);
+#       a quota message (below) also means the API does not serve.
+#   (b) is the message a quota exhaustion?   harness_quota_exhausted <text>
+#       a quota marker and no transient marker. A 429 alone is not enough in
+#       either direction: both gateway messages carry the same structured
+#       fields, so only the text tells them apart.
+# A transient 429 (harness_quota_transient) is neither: it may be retried and
+# changes nothing.
+#
+# Matching is accent-insensitive and case-folded: the gateway's Portuguese has
+# no accents ("Voce", "Sera", "faca"), the accented spelling is covered too.
+
+# harness_quota_normalize <text>: the text with accents stripped and case folded.
+harness_quota_normalize() {
+  local t="$1"
+  t="${t,,}"
+  local from=(á à â ã ä é è ê ë í ì î ï ó ò ô õ ö ú ù û ü ç ñ Á À Â Ã Ä É È Ê Ë Í Ì Î Ï Ó Ò Ô Õ Ö Ú Ù Û Ü Ç Ñ)
+  local to=(a a a a a e e e e i i i i o o o o o u u u u c n a a a a a e e e e i i i i o o o o o u u u u c n)
+  local i
+  for i in "${!from[@]}"; do t="${t//"${from[$i]}"/"${to[$i]}"}"; done
+  printf '%s' "$t"
+}
+
+# Quota markers, on normalized text (ADR 0025, section 8).
+harness_quota_markers='limite de uso do seu plano|cota semanal|sera resetado em|faca upgrade do plano|hit your [^"]{0,40}limit|usage limit reached|usage_limit_reached|out of usage credits|credit balance is too low|spend limit'
+
+# Transient markers, on normalized text: the request may be retried.
+harness_quota_transient_markers='o consumo da requisicao anterior esta sendo atualizado|tente novamente em alguns segundos|temporarily at capacity|repeated [0-9]+ overloaded errors'
+
+# Gateway failures, on normalized text: the API does not answer.
+harness_gateway_markers='api error:? \(?5[0-9]{2}|(status|error|http)[ :=]+5[0-9]{2}\b|"api_error_status": ?5[0-9]{2}|\b50[0-9] (service unavailable|bad gateway|gateway time-?out)|service unavailable|bad gateway|gateway time-?out|econnrefused|econnreset|etimedout|enotfound|eai_again|socket hang up|fetch failed|unable to connect|connection error|connection refused|request timed out'
+
+# harness_quota_transient <text>: a retryable condition, not a quota.
+harness_quota_transient() {
+  grep -qE -- "$harness_quota_transient_markers" <<<"$(harness_quota_normalize "$1")"
+}
+
+# harness_quota_exhausted <text>: the quota is gone (a quota marker and no
+# transient marker).
+harness_quota_exhausted() {
+  local t; t="$(harness_quota_normalize "$1")"
+  grep -qE -- "$harness_quota_markers" <<<"$t" && ! grep -qE -- "$harness_quota_transient_markers" <<<"$t"
+}
+
+# harness_api_unreachable <text>: the gateway failed (503 or another 5xx, a
+# connection failure, a timeout): the API does not answer, whatever the quota.
+harness_api_unreachable() {
+  grep -qE -- "$harness_gateway_markers" <<<"$(harness_quota_normalize "$1")"
+}