@data-matters.io/agent-harness 0.1.3 → 0.1.5

package/package.json

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

@@ -28,7 +28,57 @@ harness_load_env() {
 # the session's environment: only notify.sh needs them, and it reads the env file
 # itself. TELEGRAM_STATE_DIR from the env file is kept.
 # shellcheck disable=SC2034  # used by the scripts that source this file
-HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID claude)
+HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID -u HARNESS_ANTHROPIC_API_KEY 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() {
+  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
+      ? (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
+}
+
+# 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_claude_session() {
+  local secs="$1" out="$2" key="${HARNESS_ANTHROPIC_API_KEY:-}" rc=0 prompt
+  shift 2
+  rm -f "$out.source"
+  if [[ -z "$key" ]]; then
+    timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" >"$out" 2>&1 || rc=$?
+    return "$rc"
+  fi
+  prompt="$(mktemp)"
+  cat >"$prompt"
+  ANTHROPIC_API_KEY="$key" timeout "$secs" "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
+  # 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
+    timeout "$secs" env -u ANTHROPIC_API_KEY "${HARNESS_CLAUDE[@]}" "$@" <"$prompt" >"$out" 2>&1 || rc=$?
+    echo plan >"$out.source"
+  else
+    echo api >"$out.source"
+  fi
+  rm -f "$prompt"
+  return "$rc"
+}
 
 # 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:
@@ -158,14 +208,32 @@ harness_session_usage() {
 
 # harness_record_usage <project> <ref> <task-type> <level> <effort> <attempt> <result> <session.json>:
 # one line in the machine-wide ledger (HARNESS_USAGE_LEDGER, default
-# ~/.local/state/harness/usage.tsv); prints the session's usage columns.
+# ~/.local/state/harness/usage.tsv); prints the session's usage columns. The last
+# column, source, is api or plan (harness_claude_session); a ledger written
+# before it existed gets the column added to its header, its old rows stay empty.
 harness_record_usage() {
-  local ledger="${HARNESS_USAGE_LEDGER:-$HOME/.local/state/harness/usage.tsv}" usage
+  local ledger="${HARNESS_USAGE_LEDGER:-$HOME/.local/state/harness/usage.tsv}" usage source
   usage="$(harness_session_usage "$8")"
+  source="$(harness_session_source "$8")"
   mkdir -p "$(dirname "$ledger")"
-  [[ -s "$ledger" ]] || printf 'timestamp\tproject\tref\ttask_type\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens\tresult\tattempt\n' >"$ledger"
+  [[ -s "$ledger" ]] || printf 'timestamp\tproject\tref\ttask_type\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens\tresult\tattempt\tsource\n' >"$ledger"
+  harness_tsv_add_source "$ledger"
   IFS=$'\t' read -r model cost out cache <<<"$usage"
-  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
-    "$model" "${5:-default}" "$cost" "$out" "$cache" "$7" "$6" >>"$ledger"
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
+    "$model" "${5:-default}" "$cost" "$out" "$cache" "$7" "$6" "$source" >>"$ledger"
   printf '%s' "$usage"
 }
+
+# harness_session_source <session.json>: api or plan, as harness_claude_session
+# recorded it (plan when it did not: no API key was configured).
+harness_session_source() {
+  local s=plan
+  [[ -f "$1.source" ]] && s="$(<"$1.source")"
+  echo "$s"
+}
+
+# harness_tsv_add_source <file>: adds the source column to the header of a TSV
+# written before it existed.
+harness_tsv_add_source() {
+  [[ "$(head -n1 "$1")" == *$'\tsource' ]] || sed -i '1s/$/\tsource/' "$1"
+}

package/templates/.harness/models.conf

@@ -6,20 +6,21 @@
 #
 # Overrides, applied in this order after this file:
 #   .harness/models.local.conf   per project (project-owned, never synced)
-#   $HARNESS_MODELS_FILE         per machine (e.g. no Fable: R4="--model opus --effort xhigh")
+#   $HARNESS_MODELS_FILE         per machine (e.g. a cheaper R3: R3="--model opus --effort low")
 #
 # Rollout (decision 7): with HARNESS_MODEL_ROUTING=measure (the default) the
 # levels are computed and recorded but no flags are passed, so sessions keep
 # the account's default model; set HARNESS_MODEL_ROUTING=on (env file) to switch.
 # shellcheck shell=bash disable=SC2034
 
-R4="--model fable --effort high"   # design: specs, decisions no gate checks
-R3="--model opus --effort high"    # hard: ambiguous work, unclear diagnosis
+# No level uses Fable (amendment 2026-10-31 to ADR 0020).
+R4="--model opus --effort high"    # reserved: large product documents, last rung of the ladder
+R3="--model opus --effort medium"  # design/hard: specs, ambiguous work, unclear diagnosis
 R2="--model sonnet --effort medium" # build: a well-specified, gate-verified task
 R1="--model haiku --effort medium"  # routine: a mechanical, local edit
 
-TASK_spec_author=R4      # /opsx:propose in an interactive or channel session
-TASK_spec_adjust=R4      # spec PR review comments (watcher, ADR 0017)
+TASK_spec_author=R3      # /opsx:propose in an interactive or channel session; R4 for big product documents
+TASK_spec_adjust=R2      # spec PR review comments (watcher, ADR 0017): bounded edits to an existing spec
 TASK_impl=R2             # task loop (run-tasks.sh); tasks.md may override
 TASK_conflict=R3         # merge conflicts on a PR (watcher, ADR 0019)
 TASK_ci_fix=R2           # failing checks, clear cause (watcher, ADR 0019)
@@ -27,5 +28,5 @@ 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_archive_fix=R2      # editorial split of a merged requirement over 500 characters (ADR 0022)
+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/run-tasks.sh

@@ -207,11 +207,13 @@ trap '[[ "$run_status" == running ]] && run_status=interrupted; write_state' EXI
 write_state
 cd "$wt"
 summary="$log_dir/summary.tsv"
-summary_header=$'timestamp\ttask\tattempt\tduration_s\tresult\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens'
+summary_header=$'timestamp\ttask\tattempt\tduration_s\tresult\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens\tsource'
 if [[ ! -f "$summary" ]]; then
   printf '%s\n' "$summary_header" >"$summary"
 elif [[ "$(head -n1 "$summary")" == $'timestamp\ttask\tattempt\tduration_s\tresult' ]]; then
   sed -i "1s/.*/$summary_header/" "$summary"   # older runs: same first columns, new ones empty
+else
+  harness_tsv_add_source "$summary"
 fi
 
 next_task() { grep -n -m1 -E '^[[:space:]]*- \[ \] ' "$tasks" || true; }
@@ -297,13 +299,14 @@ warn_if_untrusted() {
 # with its level, model, effort, cost and tokens (ADR 0020); the same session
 # also goes to the machine-wide ledger.
 record() {
-  local usage effort model cost out cache
+  local usage effort model cost out cache source
   effort="$(harness_flag_value "${level_flags:-}" --effort)"
   usage="$(harness_record_usage "$(basename "$root")" "$change" impl "${level:-}" "${effort:-default}" "$2" "$4" \
     "$log_dir/task-$1-attempt-$2.json")"
   IFS=$'\t' read -r model cost out cache <<<"$usage"
-  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
-    "${level:-}" "$model" "${effort:-default}" "$cost" "$out" "$cache" >>"$summary"
+  source="$(harness_session_source "$log_dir/task-$1-attempt-$2.json")"
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
+    "${level:-}" "$model" "${effort:-default}" "$cost" "$out" "$cache" "$source" >>"$summary"
 }
 
 while line="$(next_task)"; [[ -n "$line" ]]; do
@@ -345,13 +348,12 @@ while line="$(next_task)"; [[ -n "$line" ]]; do
     session_json="$log_dir/task-$task_id-attempt-$attempt.json"
     while :; do
       # shellcheck disable=SC2086
-      build_prompt "$task" "$feedback" | timeout "$timeout_s" "${HARNESS_CLAUDE[@]}" -p \
+      build_prompt "$task" "$feedback" | harness_claude_session "$timeout_s" "$session_json" -p \
         --output-format json \
         --permission-mode "$permission_mode" \
         --disallowedTools "Bash(git commit:*)" "Bash(git push:*)" "Bash(.harness/spec-pr.sh:*)" \
           "Bash(pnpm add:*)" "Bash(pnpm remove:*)" "Bash(pnpm update:*)" "Bash(npm install:*)" \
-        ${level_flags} ${HARNESS_CLAUDE_ARGS:-} \
-        >"$session_json" 2>&1 || true
+        ${level_flags} ${HARNESS_CLAUDE_ARGS:-} || true
 
       warn_if_untrusted "$session_json"
 
@@ -462,10 +464,10 @@ if [[ -x .harness/gates.sh ]] && .harness/gates.sh --has-final; then
       session_json="$log_dir/task-final-attempt-$attempt.json"
       # shellcheck disable=SC2086
       build_prompt "make the final gates pass: .harness/gates.sh --final (end-to-end checks run once at the end of the change). Fix the code or tests the change touched; the approved spec is the reference." "$final_gate_out" \
-        | timeout "$timeout_s" "${HARNESS_CLAUDE[@]}" -p --output-format json --permission-mode "$permission_mode" \
+        | harness_claude_session "$timeout_s" "$session_json" -p --output-format json --permission-mode "$permission_mode" \
           --disallowedTools "Bash(git commit:*)" "Bash(git push:*)" "Bash(.harness/spec-pr.sh:*)" \
             "Bash(pnpm add:*)" "Bash(pnpm remove:*)" "Bash(pnpm update:*)" "Bash(npm install:*)" \
-          ${level_flags} ${HARNESS_CLAUDE_ARGS:-} >"$session_json" 2>&1 || true
+          ${level_flags} ${HARNESS_CLAUDE_ARGS:-} || true
       warn_if_untrusted "$session_json"
       if harness_usage_error "$session_json"; then
         record final "$attempt" "$(( $(date +%s) - start ))" paused