@data-matters.io/agent-harness 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-matters.io/agent-harness",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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
@@ -31,72 +35,58 @@ harness_load_env() {
 HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID -u HARNESS_ANTHROPIC_API_KEY -u HARNESS_ANTHROPIC_BASE_URL claude)
 
 # ------------------------------------------- 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.
-harness_api_refused() {
+# harness_session_error_text <session.json>: the text of an errored session (its
+# result and api_error), or the raw output when it is not JSON. Empty when the
+# session did not fail.
+harness_session_error_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
 }
 
-# harness_claude_session <timeout-seconds> <session.json> <claude args...>: runs
-# one headless Claude Code session (the prompt on stdin) and writes its output
-# (stdout and stderr) to <session.json>; returns the exit status of the run
-# that produced it (124: timed out). Without HARNESS_ANTHROPIC_API_KEY this is
-# the account login, exactly as before. With it, the session runs on the API
-# first (the key goes to that process only, through its environment, never its
-# arguments or a log); when the API refuses it (harness_api_refused), the SAME
-# attempt repeats on the plan login. Which one produced the output is written to
-# <session.json>.source (api|plan), which the usage ledger reads.
-# HARNESS_ANTHROPIC_BASE_URL is the optional base URL of that key (a gateway):
-# it reaches the API run only, as ANTHROPIC_BASE_URL, and the plan run never
-# 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
-  shift 2
-  rm -f "$out.source"
-  if [[ -z "$key" ]]; then
-    # No key configured: the session is the account login, on the Anthropic API.
-    # A base URL left in the environment would point that login at a gateway.
-    if [[ -n "$base" ]]; then
-      timeout "$secs" env -u ANTHROPIC_BASE_URL "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
-    else
-      timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
-    fi
-    return "$rc"
-  fi
-  prompt="$(mktemp)"
-  cat >"$prompt"
-  if [[ -n "$base" ]]; then
-    ANTHROPIC_API_KEY="$key" ANTHROPIC_BASE_URL="$base" timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
-  else
-    ANTHROPIC_API_KEY="$key" timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
-  fi
-  # Whatever the session printed, the key itself never stays in the log.
-  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
-    rc=0
-    if [[ -n "$base" ]]; then
-      timeout "$secs" env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
-    else
-      timeout "$secs" env -u ANTHROPIC_API_KEY "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
-    fi
-    echo plan >"$out.source"
-  else
+# harness_api_refused <session.json>: the session ended on an error that says
+# 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() {
+  local text
+  text="$(harness_session_error_text "$1")" || 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 layer shim (ADR 0026, section 9) --
+# The session wrapper and the machine mode live in the machine layer,
+# machine/session.sh, in the VPS runtime (HARNESS_WATCH_RUNTIME, default
+# ~/.local/share/agent-harness/watch). HARNESS_MACHINE_API=1 is the contract.
+# Without a runtime (CI, a laptop, a clone elsewhere) a session is a plain claude
+# with the caller's own environment and the mode is api: the degraded fallback of
+# ADR 0025, section 8. A key from HARNESS_ANTHROPIC_API_KEY is not used then.
+# shellcheck disable=SC2034  # the contract marker, read by the runtime
+HARNESS_MACHINE_API=1
+harness_machine_session_file() { printf '%s' "${HARNESS_WATCH_RUNTIME:-$HOME/.local/share/agent-harness/watch}/machine/session.sh"; }
+if [[ -r "$(harness_machine_session_file)" ]]; then
+  # shellcheck source=/dev/null
+  . "$(harness_machine_session_file)"
+else
+  harness_mode() { echo api; }
+  harness_claude_session() { # <timeout-seconds> <session.json> <claude args...>
+    local secs="$1" out="$2" rc=0
+    shift 2
+    rm -f "$out.source"
+    timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
     echo api >"$out.source"
-  fi
-  rm -f "$prompt"
-  return "$rc"
-}
+    return "$rc"
+  }
+fi
 
 # Worktree where the task loop runs a change (ADR 0012), outside the checkout so
 # lint, tests and type-checks of the main checkout never see it:
@@ -163,9 +153,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/models.conf

@@ -28,5 +28,6 @@ TASK_ci_fix_retry=R3     # failing checks after a failed fix (watcher, ADR 0019)
 TASK_review_comments=R2  # owner comments on implementation/sync PRs (ADR 0019, 1b)
 TASK_diagnosis=R3        # explaining an escalation
 TASK_review=R3           # PR review
+TASK_issue_fix=R3        # a fix for an open harness-fault issue (ADR 0027, decision 5); unused until fix mode is enabled
 TASK_archive_fix=R1      # editorial split of a merged requirement over 500 characters (ADR 0022), gate-verified
 TASK_routine=R1          # hand edits around sync and archive

package/templates/.harness/quota.sh

@@ -0,0 +1,70 @@
+# 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. This is the
+# one list for the whole system (ADR 0026, section 6): the machine library
+# (vps-bootstrap) loads this file and keeps a copy only as a degraded fallback,
+# and a test there fails if the two disagree.
+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|overloaded|upstream|econnrefused|econnreset|etimedout|enotfound|eai_again|socket hang up|fetch failed|unable to connect|connection (error|refused|reset|closed)|timed? ?out|could not resolve|network error|context validation'
+
+# 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")"
+}
+
+# harness_api_fault_class <text>: how a session error counts for the machine
+# mode (ADR 0025 section 8, ADR 0026 sections 3 and 6). Prints one word:
+#   transient  a passing failure: counts only after several in a row
+#   down       the API does not serve: a quota, or a gateway failure
+#   none       not a failure of the API
+harness_api_fault_class() {
+  if harness_quota_transient "$1"; then printf 'transient'; return 0; fi
+  if harness_quota_exhausted "$1" || harness_api_unreachable "$1"; then printf 'down'; return 0; fi
+  printf 'none'
+}