@onlooker-community/ecosystem 0.15.2 → 0.17.0

package/plugins/scribe/scripts/lib/scribe-project-key.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Project key derivation for Scribe.
+#
+# Mirrors the tribunal project-key scheme so plugins partition storage
+# identically. A project key is a stable 12-char hex identifier that survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for repos
+#      without an origin remote
+#
+# Returns the first 12 hex chars. Returns empty string if neither path works.
+
+_scribe_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+scribe_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+scribe_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+scribe_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(scribe_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_scribe_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(scribe_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_scribe_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}
+
+scribe_project_dir() {
+	local project_key="${1:-}"
+	[[ -z "$project_key" ]] && return 1
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	printf '%s' "${onlooker_dir}/scribe/${project_key}"
+}

package/plugins/scribe/scripts/lib/scribe-ulid.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Scribe document and event IDs.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+
+_SCRIBE_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_scribe_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_SCRIBE_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+scribe_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		rand_hi=$((RANDOM * 32768 + RANDOM))
+		rand_lo=$((RANDOM * 32768 + RANDOM))
+		rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+		rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_scribe_ulid_encode "$now_ms" 10)
+	hi_part=$(_scribe_ulid_encode "$rand_hi" 8)
+	lo_part=$(_scribe_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/release-please-config.json

@@ -78,6 +78,54 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/governor": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "governor",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/compass": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "compass",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/scribe": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "scribe",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

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 ]
+}