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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-matters.io/agent-harness",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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

@@ -35,6 +35,27 @@ 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_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]);
+    process.stdout.write(Object.keys(d).length
+      ? (d.is_error ? [d.result, d.api_error].filter((x) => typeof x === "string").join(" ") : "")
+      : raw);' "$1" 2>/dev/null
+}
+
+# harness_session_api_error <session.json>: the session's api_error field, the
+# structured value the runtime sets when the API refused (usage_limit_reached).
+# Empty when the session carries none.
+harness_session_api_error() {
+  node -e "$harness_session_js"'
+    const d = session(process.argv[1]);
+    process.stdout.write(typeof d.api_error === "string" ? d.api_error : "");' "$1" 2>/dev/null
+}
+
 # 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
@@ -43,12 +64,7 @@ HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID -u
 # a task about authentication or billing never matches by its own words.
 harness_api_refused() {
   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]);
-    process.stdout.write(Object.keys(d).length
-      ? (d.is_error ? [d.result, d.api_error].filter((x) => typeof x === "string").join(" ") : "")
-      : raw);' "$1" 2>/dev/null)" || return 1
+  text="$(harness_session_error_text "$1")" || return 1
   [[ -n "$text" ]] || return 1
   harness_api_unreachable "$text" && return 0
   harness_quota_transient "$text" && return 1
@@ -56,86 +72,30 @@ harness_api_refused() {
   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
-# 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 mode unset=()
-  shift 2
-  rm -f "$out.source"
-  # 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)"
-  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 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=$?
-    else
-      timeout "$secs" env -u ANTHROPIC_API_KEY "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
-    fi
-    echo plan >"$out.source"
-  else
+# ----------------------------------- 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:
@@ -205,8 +165,30 @@ harness_claude_flags() {
 # 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).
+#
+# Only the session's own FAILURE is read: the api_error field, and the error
+# text of a session that ended with is_error (harness_session_error_text).
+# The answer of a session that ended well is never a usage error by what it
+# says: a task that explains an old quota event ("cota semanal") is a task
+# about a quota, not a quota. The one exception is the gateway's quota notice,
+# which arrives unmarked, in the body of a 200: there the whole answer IS the
+# notice, so a short answer that carries a quota marker still is a usage error
+# (harness_quota_notice_unmarked).
 harness_usage_error() {
-  harness_quota_exhausted "$(cat -- "$1" 2>/dev/null)"
+  local text reply
+  text="$(harness_session_error_text "$1")"
+  if [[ -n "$text" ]]; then
+    # The session failed: its error text (its result and its api_error) is the
+    # message the rule is about.
+    if harness_quota_exhausted "$text"; then return 0; fi
+    return 1
+  fi
+  # The session ended well: its answer is not a usage error by what it says.
+  # The api_error field still counts (usage_limit_reached), and the gateway's
+  # unmarked notice is the one answer that IS the notice.
+  if harness_quota_exhausted "$(harness_session_api_error "$1")"; then return 0; fi
+  reply="$(harness_session_reply "$1")" || return 1
+  harness_quota_notice_unmarked "$reply"
 }
 
 # harness_level_descend <level>: the level one below, for the fallback after a

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

@@ -11,6 +11,10 @@
 #       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.
+#   (c) is a session that ENDED WELL the gateway's quota notice?
+#       harness_quota_notice_unmarked <text>
+#       the gateway sometimes answers 200 with the quota notice in the body,
+#       without marking it as an error: there the whole answer is the notice.
 # A transient 429 (harness_quota_transient) is neither: it may be retried and
 # changes nothing.
 #
@@ -34,8 +38,11 @@ harness_quota_markers='limite de uso do seu plano|cota semanal|sera resetado em|
 # 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'
+# 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() {
@@ -49,8 +56,38 @@ harness_quota_exhausted() {
   grep -qE -- "$harness_quota_markers" <<<"$t" && ! grep -qE -- "$harness_quota_transient_markers" <<<"$t"
 }
 
+# The longest text that can be the gateway's quota notice. The notice arrives
+# in the body of a 200 response, without being marked as an error (the rule of
+# the watchdog, vps-bootstrap, 2026-11-11): there the whole answer IS the
+# notice. A long answer that talks about a quota is a task about a quota, not a
+# quota.
+harness_quota_notice_max_len=400
+
+# harness_quota_notice_unmarked <text>: the text is the gateway's quota notice
+# that arrived unmarked: a SHORT message (at most harness_quota_notice_max_len
+# characters) that carries a quota marker. The markers are the ones above (one
+# list, ADR 0025 section 8): this rule only says how much of the answer may
+# be the notice.
+harness_quota_notice_unmarked() {
+  local t="$1" len
+  len=${#t}
+  (( len <= harness_quota_notice_max_len )) || return 1
+  harness_quota_exhausted "$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'
+}