@onlooker-community/ecosystem 0.15.1 → 0.16.0

package/test/bats/governor-config.bats

@@ -0,0 +1,106 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/governor"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+}
+
+@test "governor is disabled by default" {
+	governor_config_load ""
+	run governor_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable governor" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"governor":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	governor_config_load ""
+	run governor_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"governor":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	local repo="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${repo}/.claude"
+	printf '%s\n' '{"governor":{"enabled":false}}' > "${repo}/.claude/settings.json"
+	governor_config_load "$repo"
+	run governor_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "default enforcement is soft" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_enforcement)
+	[ "$v" = "soft" ]
+}
+
+@test "enforcement can be overridden to hard" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"governor":{"enforcement":"hard"}}' > "${HOME}/.claude/settings.json"
+	governor_config_load ""
+	local v
+	v=$(governor_config_enforcement)
+	[ "$v" = "hard" ]
+}
+
+@test "default tokens budget is 100000" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.session.tokens_default')
+	[ "$v" = "100000" ]
+}
+
+@test "default cost budget is 1.0" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.session.cost_usd_default')
+	[ "$v" = "1.0" ]
+}
+
+@test "default safety margin is 1.3" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.estimation.safety_margin')
+	[ "$v" = "1.3" ]
+}
+
+@test "default hard_stop_margin is 1.5" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.estimation.hard_stop_margin')
+	[ "$v" = "1.5" ]
+}
+
+@test "default estimation method is tier_table" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.estimation.method')
+	[ "$v" = "tier_table" ]
+}
+
+@test "governor_config_get returns empty for missing key" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.no_such_key')
+	[ -z "$v" ]
+}
+
+@test "empty repo_root does not load /.claude/settings.json" {
+	# Place a settings.json at the absolute root path that an empty repo_root would produce.
+	# On a real machine this won't exist, but in CI it might; the guard should skip it.
+	# We verify that a file at / does not influence config by confirming the default holds.
+	governor_config_load ""
+	run governor_config_enabled
+	# Default is disabled — if /.claude/settings.json were loaded with {enabled:true}
+	# this would fail. We can't plant a file at / in tests, so we assert the default
+	# is intact (regression guard rather than direct injection test).
+	[ "$status" -ne 0 ]
+}

package/test/bats/governor-estimate.bats

@@ -0,0 +1,86 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/governor"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-estimate.sh"
+
+	governor_config_load ""
+}
+
+@test "governor_estimate_method returns tier_table" {
+	local m
+	m=$(governor_estimate_method)
+	[ "$m" = "tier_table" ]
+}
+
+@test "empty input returns a nonzero estimate" {
+	local t
+	t=$(governor_estimate_tokens "")
+	[ "$t" -gt 0 ]
+}
+
+@test "prose input produces a positive estimate" {
+	local input="This is a plain English sentence with no special characters at all."
+	local t
+	t=$(governor_estimate_tokens "$input" 1.0)
+	[ "$t" -gt 0 ]
+}
+
+@test "JSON input produces higher token density estimate than prose" {
+	local prose="This is a longer plain English paragraph used as baseline comparison text."
+	local json='{"key":"value","nested":{"array":[1,2,3,4,5],"flag":true},"extra":"padding"}'
+
+	local chars_prose=${#prose}
+	local chars_json=${#json}
+	local toks_prose
+	local toks_json
+	toks_prose=$(governor_estimate_tokens "$prose" 1.0)
+	toks_json=$(governor_estimate_tokens "$json" 1.0)
+
+	# JSON uses 3 chars/tok vs 4 for prose, so per char JSON should yield more tokens.
+	local ratio_prose=$(( toks_prose * 100 / chars_prose ))
+	local ratio_json=$(( toks_json * 100 / chars_json ))
+	[ "$ratio_json" -ge "$ratio_prose" ]
+}
+
+@test "safety margin multiplies the base estimate" {
+	local input="hello world this is a test sentence"
+	local base
+	local with_margin
+	base=$(governor_estimate_tokens "$input" 1.0)
+	with_margin=$(governor_estimate_tokens "$input" 1.3)
+
+	# with_margin should be >= base (margin >= 1.0)
+	[ "$with_margin" -ge "$base" ]
+}
+
+@test "estimate scales with input length" {
+	local short="short"
+	local long
+	long=$(printf 'x%.0s' {1..500})
+	local t_short t_long
+	t_short=$(governor_estimate_tokens "$short" 1.0)
+	t_long=$(governor_estimate_tokens "$long" 1.0)
+	[ "$t_long" -gt "$t_short" ]
+}
+
+@test "governor_estimate_cost returns a positive float for nonzero tokens" {
+	local cost
+	cost=$(governor_estimate_cost 10000)
+	# Should be > 0
+	awk "BEGIN { exit ($cost > 0) ? 0 : 1 }"
+}
+
+@test "governor_estimate_cost returns 0-ish for 0 tokens" {
+	local cost
+	cost=$(governor_estimate_cost 0)
+	[ "$cost" = "0.000000" ] || [ "$cost" = "0" ] || [ "$cost" = "0.0" ]
+}

package/test/bats/governor-events.bats

@@ -0,0 +1,238 @@
+#!/usr/bin/env bats
+
+# Validates that governor.* events pass @onlooker-community/schema validation.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/governor"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-events.sh"
+
+	export CLAUDE_SESSION_ID="bats-gov-session-$$"
+}
+
+_validate_latest_event() {
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ -n "$last" ] || return 1
+	printf '%s' "$last" | ONLOOKER_DIR="$ONLOOKER_DIR" \
+		node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+}
+
+SID="bats-session-000"
+AID="bats-agent-000"
+
+@test "governor.gate.checked allow validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" --arg aid "$AID" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			decision: "allow",
+			estimated_tokens: 5000,
+			tokens_available: 95000,
+			estimation_method: "tier_table",
+			safety_margin: 1.3
+		}')
+	governor_emit_event "governor.gate.checked" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.gate.checked block with reason validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" --arg aid "$AID" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			decision: "block",
+			reason: "budget_exceeded",
+			estimated_tokens: 110000,
+			tokens_available: 5000,
+			estimation_method: "tier_table",
+			safety_margin: 1.3
+		}')
+	governor_emit_event "governor.gate.checked" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.call.recorded validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" --arg aid "$AID" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			estimated_tokens: 4200,
+			cost_usd_estimated: 0.038,
+			duration_ms: 3500
+		}')
+	governor_emit_event "governor.call.recorded" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.call.recorded with actuals validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" --arg aid "$AID" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			estimated_tokens: 4200,
+			actual_tokens: 3900,
+			estimation_error_pct: 7.69,
+			cost_usd_estimated: 0.038,
+			cost_usd_actual: 0.035,
+			duration_ms: 3500,
+			tokens_returned_to_pool: 0
+		}')
+	governor_emit_event "governor.call.recorded" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.ledger.write_failed validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" --arg aid "$AID" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			error: "write failed after 3 attempts",
+			retry_count: 3,
+			ledger_poisoned: true,
+			unrecorded_tokens: 4200
+		}')
+	governor_emit_event "governor.ledger.write_failed" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.budget.warning validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" \
+		'{
+			budget_usd: 1.0,
+			spent_usd: 0.72,
+			threshold_pct: 70,
+			remaining_usd: 0.28,
+			session_id: $sid,
+			dimension: "cost_usd"
+		}')
+	governor_emit_event "governor.budget.warning" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.budget.exceeded validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" --arg aid "$AID" \
+		'{
+			budget_usd: 1.0,
+			spent_usd: 1.05,
+			blocked_operation: "Task spawn",
+			session_id: $sid,
+			agent_id: $aid,
+			dimension: "tokens",
+			estimated_call_cost: 0.08,
+			ceiling_type: "session"
+		}')
+	governor_emit_event "governor.budget.exceeded" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.session.complete validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" \
+		'{
+			total_cost_usd: 0.42,
+			budget_usd: 1.0,
+			under_budget: true,
+			session_id: $sid,
+			total_tokens: 46200,
+			total_api_calls: 11,
+			duration_ms: 0,
+			calls_blocked: 0,
+			calls_warned: 2,
+			ledger_poisoned: false
+		}')
+	governor_emit_event "governor.session.complete" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.lock.stale_cleared validates" {
+	local p
+	p=$(jq -n \
+		'{
+			lock_path: "/tmp/test.lock.d",
+			lock_age_seconds: 120.5,
+			pid_verified_dead: false
+		}')
+	governor_emit_event "governor.lock.stale_cleared" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.child.allocated validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" \
+		'{
+			session_id: $sid,
+			parent_agent_id: "parent-001",
+			child_agent_id: "child-001",
+			child_agent_type: "tribunal-actor",
+			tokens_allocated: 20000,
+			cost_usd_allocated: 0.18,
+			tokens_remaining_after_allocation: 80000,
+			conservation_check_passed: true
+		}')
+	governor_emit_event "governor.child.allocated" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor.child.returned validates" {
+	local p
+	p=$(jq -n \
+		--arg sid "$SID" \
+		'{
+			session_id: $sid,
+			parent_agent_id: "parent-001",
+			child_agent_id: "child-001",
+			tokens_allocated: 20000,
+			tokens_consumed: 14200,
+			tokens_returned: 5800
+		}')
+	governor_emit_event "governor.child.returned" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "governor_emit_event returns nonzero for unknown event type" {
+	run governor_emit_event "governor.no_such_event" '{"session_id":"x"}'
+	[ "$status" -ne 0 ]
+}

package/test/bats/governor-ledger.bats

@@ -0,0 +1,220 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/governor"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export CLAUDE_SESSION_ID="bats-ledger-$$"
+
+	# shellcheck disable=SC1091
+	source "${REPO_ROOT}/scripts/lib/portable-lock.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-events.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-ledger.sh"
+
+	export ONLOOKER_DIR="${TEST_HOME}/.onlooker"
+	SID="ledger-test-session-$$"
+}
+
+_make_record() {
+	local tokens="${1:-1000}"
+	local cost="${2:-0.009}"
+	jq -n \
+		--arg ts "2026-01-01T00:00:00Z" \
+		--arg sid "$SID" \
+		--arg aid "test-agent" \
+		--argjson est "$tokens" \
+		--argjson cost "$cost" \
+		'{
+			ts: $ts,
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			estimated_tokens: $est,
+			cost_usd_estimated: $cost,
+			duration_ms: 1000
+		}'
+}
+
+_make_reservation() {
+	local tokens="${1:-1000}"
+	local cost="${2:-0.009}"
+	jq -n \
+		--arg ts "2026-01-01T00:00:00Z" \
+		--arg sid "$SID" \
+		--arg aid "test-agent" \
+		--argjson est "$tokens" \
+		--argjson cost "$cost" \
+		'{
+			ts: $ts,
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			estimated_tokens: $est,
+			cost_usd_estimated: $cost,
+			record_type: "reservation"
+		}'
+}
+
+_make_completion() {
+	local neg_tokens="${1:--1000}"
+	local actual_tokens="${2:-900}"
+	local cost="${3:-0.009}"
+	jq -n \
+		--arg ts "2026-01-01T00:00:00Z" \
+		--arg sid "$SID" \
+		--arg aid "test-agent" \
+		--argjson est "$neg_tokens" \
+		--argjson actual "$actual_tokens" \
+		--argjson cost "$cost" \
+		'{
+			ts: $ts,
+			session_id: $sid,
+			agent_id: $aid,
+			agent_type: "Task",
+			estimated_tokens: $est,
+			actual_tokens: $actual,
+			cost_usd_estimated: $cost,
+			duration_ms: 1500
+		}'
+}
+
+@test "governor_ledger_path returns a .jsonl path under ONLOOKER_DIR" {
+	local p
+	p=$(governor_ledger_path "test-session")
+	[[ "$p" == *".jsonl" ]]
+	[[ "$p" == *"test-session"* ]]
+}
+
+@test "governor_ledger_total_tokens returns 0 for missing ledger" {
+	local total
+	total=$(governor_ledger_total_tokens "no-such-session")
+	[ "$total" = "0" ]
+}
+
+@test "governor_ledger_total_cost returns 0 for missing ledger" {
+	local total
+	total=$(governor_ledger_total_cost "no-such-session")
+	[ "$total" = "0" ]
+}
+
+@test "governor_ledger_call_count returns 0 for missing ledger" {
+	local count
+	count=$(governor_ledger_call_count "no-such-session")
+	[ "$count" = "0" ]
+}
+
+@test "governor_ledger_append writes a record and it is readable" {
+	local record
+	record=$(_make_record 5000 0.045)
+	governor_ledger_append "$SID" "$record"
+
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$SID")
+	[ -f "$ledger_path" ]
+
+	local lines
+	lines=$(awk 'END{print NR}' "$ledger_path")
+	[ "$lines" = "1" ]
+}
+
+@test "governor_ledger_total_tokens sums across multiple records" {
+	governor_ledger_append "$SID" "$(_make_record 3000 0.027)"
+	governor_ledger_append "$SID" "$(_make_record 4000 0.036)"
+	governor_ledger_append "$SID" "$(_make_record 2500 0.023)"
+
+	local total
+	total=$(governor_ledger_total_tokens "$SID")
+	[ "$total" = "9500" ]
+}
+
+@test "governor_ledger_total_cost sums across multiple records" {
+	governor_ledger_append "$SID" "$(_make_record 1000 0.01)"
+	governor_ledger_append "$SID" "$(_make_record 1000 0.02)"
+
+	local total
+	total=$(governor_ledger_total_cost "$SID")
+	# Allow slight floating-point representation variance
+	[[ "$total" =~ ^0\.03 ]]
+}
+
+@test "governor_ledger_call_count counts records" {
+	governor_ledger_append "$SID" "$(_make_record 1000 0.009)"
+	governor_ledger_append "$SID" "$(_make_record 1000 0.009)"
+	governor_ledger_append "$SID" "$(_make_record 1000 0.009)"
+
+	local count
+	count=$(governor_ledger_call_count "$SID")
+	[ "$count" = "3" ]
+}
+
+@test "governor_ledger_is_poisoned returns false for healthy ledger" {
+	governor_ledger_append "$SID" "$(_make_record 1000 0.009)"
+	run governor_ledger_is_poisoned "$SID"
+	[ "$status" -ne 0 ]
+}
+
+@test "governor_ledger_is_poisoned returns true after poison sentinel" {
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$SID")
+	mkdir -p "$(dirname "$ledger_path")"
+	touch "$(governor_ledger_poison_path "$ledger_path")"
+
+	run governor_ledger_is_poisoned "$SID"
+	[ "$status" -eq 0 ]
+}
+
+@test "governor_ledger_write_direct writes a record without acquiring the write lock" {
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$SID")
+	mkdir -p "$(dirname "$ledger_path")"
+
+	local record
+	record=$(_make_reservation 2000 0.018)
+	governor_ledger_write_direct "$ledger_path" "$record"
+
+	local lines
+	lines=$(awk 'END{print NR}' "$ledger_path")
+	[ "$lines" = "1" ]
+}
+
+@test "two-phase: reservation plus completion converges to actual tokens" {
+	# Phase 1: PreToolUse writes reservation with N_est = 5000
+	local reservation
+	reservation=$(_make_reservation 5000 0.045)
+	governor_ledger_append "$SID" "$reservation"
+
+	local mid_total
+	mid_total=$(governor_ledger_total_tokens "$SID")
+	[ "$mid_total" = "5000" ]
+
+	# Phase 2: PostToolUse writes completion with estimated=-5000, actual=4200
+	local completion
+	completion=$(_make_completion -5000 4200 0.045)
+	governor_ledger_append "$SID" "$completion"
+
+	# Net: 5000 + (-5000) + 4200 = 4200
+	local final_total
+	final_total=$(governor_ledger_total_tokens "$SID")
+	[ "$final_total" = "4200" ]
+}
+
+@test "governor_ledger_call_count excludes reservation records" {
+	governor_ledger_append "$SID" "$(_make_reservation 1000 0.009)"
+	governor_ledger_append "$SID" "$(_make_completion -1000 900 0.009)"
+	governor_ledger_append "$SID" "$(_make_completion -1000 800 0.009)"
+
+	local count
+	count=$(governor_ledger_call_count "$SID")
+	# 2 completions, 1 reservation — only completions count
+	[ "$count" = "2" ]
+}