@onlooker-community/ecosystem 0.28.1 → 0.29.0

package/plugins/compass/scripts/lib/compass-gate.sh

@@ -92,21 +92,18 @@ _compass_matches_skip_glob() {
 	local globs_json="$2"
 	[[ -z "$file_path" || -z "$globs_json" ]] && return 1
 
-	# Convert JSON array to bash array and check each pattern.
-	local globs
-	mapfile -t globs < <(printf '%s' "$globs_json" | jq -r '.[]' 2>/dev/null) || return 1
-
-	local glob
-	for glob in "${globs[@]}"; do
-		# Use bash glob matching (extglob not needed for ** — use case).
-		# Convert ** to a catch-all for simple prefix/suffix matching.
-		local pattern="${glob//\*\*/DOUBLE_STAR}"
+	# Bash 3.2 (macOS) lacks mapfile, so stream via read-while.
+	local glob pattern
+	while IFS= read -r glob; do
+		[[ -z "$glob" ]] && continue
+		# Translate ** → .*  and *  → [^/]* for simple prefix/suffix matching.
+		pattern="${glob//\*\*/DOUBLE_STAR}"
 		pattern="${pattern//\*/[^/]*}"
 		pattern="${pattern//DOUBLE_STAR/.*}"
 		if [[ "$file_path" =~ $pattern ]]; then
 			return 0
 		fi
-	done
+	done < <(printf '%s' "$globs_json" | jq -r '.[]' 2>/dev/null)
 	return 1
 }
 
@@ -241,12 +238,13 @@ Choose a path:
 
 # -----------------------------------------------------------------------
 # Main gate function.
-# $1 — tool_name   (Write | Edit | MultiEdit | Bash)
-# $2 — file_path   (may be empty for Bash)
-# $3 — operation   (write | edit | multi_edit | bash_write)
-# $4 — context     (context excerpt or bash command string)
+# $1 — tool_name      (Write | Edit | MultiEdit | Bash)
+# $2 — file_path      (may be empty for Bash)
+# $3 — operation      (write | edit | multi_edit | bash_write)
+# $4 — context        (context excerpt or bash command string)
 # $5 — session_id
 # $6 — cwd
+# $7 — transcript_path (from hook JSON; may be empty)
 # -----------------------------------------------------------------------
 compass_run_gate() {
 	local tool_name="$1"
@@ -255,6 +253,7 @@ compass_run_gate() {
 	local context="$4"
 	local session_id="${5:-unknown}"
 	local cwd="${6:-}"
+	local transcript_path="${7:-}"
 
 	local _allow_exit=0
 	local _block_exit=0
@@ -348,14 +347,12 @@ compass_run_gate() {
 	_compass_increment_turn_count "$session_id" 2>/dev/null || true
 
 	# ---- Read prior assistant turn -----------------------------------
-	local prior_turn_chars_max transcript_max_age
+	local prior_turn_chars_max
 	prior_turn_chars_max=$(compass_config_get '.compass.transcript.prior_turn_chars_max')
 	prior_turn_chars_max="${prior_turn_chars_max:-800}"
-	transcript_max_age=$(compass_config_get '.compass.transcript.transcript_max_age_seconds')
-	transcript_max_age="${transcript_max_age:-300}"
 
 	local prior_turn=""
-	prior_turn=$(compass_read_prior_turn "$session_id" "$prior_turn_chars_max" "$transcript_max_age") \
+	prior_turn=$(compass_read_prior_turn "$transcript_path" "$prior_turn_chars_max") \
 		|| prior_turn=""
 
 	# ---- Symbolic skip layer -----------------------------------------

package/plugins/compass/scripts/lib/compass-sanitizer.sh

@@ -42,13 +42,13 @@ _compass_strip_control_chars() {
 }
 
 # Replace all occurrences of a literal string with [STRIPPED].
+# Uses bash native parameter expansion to avoid the sed delimiter trap —
+# needles like </prior_assistant_turn> contain '/' which breaks sed s///.
 _compass_strip_literal() {
 	local input="$1"
 	local needle="$2"
-	# Use printf + sed; escape needle for BRE (basic regex)
-	local escaped_needle
-	escaped_needle=$(printf '%s' "$needle" | sed 's/[[\.*^$()+?{|]/\\&/g' 2>/dev/null) || escaped_needle="$needle"
-	printf '%s' "$input" | sed "s/${escaped_needle}/[STRIPPED]/g" 2>/dev/null
+	[[ -z "$needle" ]] && { printf '%s' "$input"; return; }
+	printf '%s' "${input//"$needle"/[STRIPPED]}"
 }
 
 # Truncate a string to at most max_chars UTF-8 characters.

package/plugins/compass/scripts/lib/compass-transcript.sh

@@ -1,135 +1,102 @@
 #!/usr/bin/env bash
 # Prior assistant turn reader for Compass.
 #
-# Resolves the most recent assistant turn from the session transcript so
-# the evaluator can operate on the pair {prior_assistant_turn, context}
-# rather than context alone — avoiding false positives on question-answer
-# turns (see ADR-001).
+# Resolves the most recent assistant turn from the session transcript JSONL
+# so the evaluator can operate on the pair {prior_assistant_turn, context}
+# rather than context alone. Avoids false positives on question-answer
+# turns. See ADR-001 (plugins/compass/docs/adr/001-evaluate-prompts-in-context.md).
 #
-# Resolution order:
-#   1. CLAUDE_TRANSCRIPT_PATH env var → parse as JSONL, find most recent
-#      entry with role:"assistant"
-#   2. Onlooker JSONL event log (~/.onlooker/logs/onlooker-events.jsonl)
-#      filtered by session_id and event_type:"session.prompt", most recent
-#      assistant-role entry
-#   3. Empty string — degrades gracefully; evaluator runs on context alone
+# Source: the `transcript_path` field from the hook JSON payload. This is
+# the same field tribunal-stop-gate.sh reads (`jq -r '.transcript_path // ""'`).
+# When `transcript_path` is absent or unreadable, this function returns the
+# empty string and the evaluator runs on the current context alone.
 #
 # Exposes:
-#   compass_read_prior_turn <session_id> <max_chars> <max_age_seconds>
-#     Echoes the prior assistant turn text (possibly empty).
-
-_compass_transcript_from_path() {
-	local transcript_path="$1"
-	local session_id="$2"
-	local max_age_seconds="$3"
-
-	[[ -f "$transcript_path" ]] || return 1
-
-	local now
-	now=$(date +%s 2>/dev/null) || now=0
-
-	# Parse JSONL: find most recent entry with role=assistant within max_age_seconds.
-	# Each line is a JSON object. We want the last one matching our criteria.
-	local prior_turn=""
-	local line
-	while IFS= read -r line; do
-		[[ -z "$line" ]] && continue
-		local role ts content
-		role=$(printf '%s' "$line" | jq -r '.role // empty' 2>/dev/null) || continue
-		[[ "$role" == "assistant" ]] || continue
-
-		# Age check — skip entries older than max_age_seconds.
-		if [[ "$max_age_seconds" -gt 0 ]]; then
-			ts=$(printf '%s' "$line" | jq -r '.timestamp // empty' 2>/dev/null) || ts=""
-			if [[ -n "$ts" ]]; then
-				local entry_time
-				entry_time=$(date -d "$ts" +%s 2>/dev/null) \
-					|| entry_time=$(date -jf '%Y-%m-%dT%H:%M:%SZ' "$ts" +%s 2>/dev/null) \
-					|| entry_time=0
-				local age=$(( now - entry_time ))
-				[[ "$age" -gt "$max_age_seconds" ]] && continue
-			fi
-		fi
-
-		content=$(printf '%s' "$line" | jq -r '.content // .text // empty' 2>/dev/null) || continue
-		[[ -n "$content" ]] && prior_turn="$content"
-	done < "$transcript_path"
-
-	[[ -n "$prior_turn" ]] || return 1
-	printf '%s' "$prior_turn"
+#   compass_read_prior_turn <transcript_path> <max_chars>
+#     Echoes the sanitized, truncated prior assistant turn, or empty string.
+
+# Extract the text portion of a transcript line. The Claude Code session
+# transcript stores assistant messages as `{"type":"assistant","message":{...}}`
+# where `message.content` may be a string or an array of content blocks.
+_compass_transcript_extract_text() {
+	local line="$1"
+	# Prefer message.content[*].text for the array-of-blocks shape; fall back
+	# to message.content when it is already a string. Final fallback: any
+	# top-level .content or .text field (covers legacy/alternate writers).
+	printf '%s' "$line" | jq -r '
+		if (.message? // null) != null then
+			if (.message.content | type) == "array" then
+				[.message.content[]? | select(type == "object") | (.text // "")]
+				| map(select(. != "")) | join("\n")
+			elif (.message.content | type) == "string" then
+				.message.content
+			else "" end
+		else
+			(.content // .text // "")
+		end
+	' 2>/dev/null
 }
 
-_compass_transcript_from_event_log() {
-	local session_id="$1"
-	local max_age_seconds="$2"
-	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
-
-	[[ -f "$log_path" ]] || return 1
-	[[ -n "$session_id" && "$session_id" != "unknown" ]] || return 1
-
-	local now
-	now=$(date +%s 2>/dev/null) || now=0
-
-	local prior_turn=""
-	local line
-	while IFS= read -r line; do
-		[[ -z "$line" ]] && continue
-
-		local sid etype role
-		sid=$(printf '%s' "$line" | jq -r '.session_id // empty' 2>/dev/null) || continue
-		[[ "$sid" == "$session_id" ]] || continue
-
-		etype=$(printf '%s' "$line" | jq -r '.event_type // empty' 2>/dev/null) || continue
-		[[ "$etype" == "session.prompt" ]] || continue
-
-		role=$(printf '%s' "$line" | jq -r '.payload.role // empty' 2>/dev/null) || continue
-		[[ "$role" == "assistant" ]] || continue
+# Return the role for a transcript line, falling back to .message.role.
+_compass_transcript_role() {
+	local line="$1"
+	printf '%s' "$line" \
+		| jq -r '(.role // .message.role // .type // empty)' 2>/dev/null
+}
 
-		if [[ "$max_age_seconds" -gt 0 ]]; then
-			local ts entry_time
-			ts=$(printf '%s' "$line" | jq -r '.timestamp // empty' 2>/dev/null) || ts=""
-			if [[ -n "$ts" ]]; then
-				entry_time=$(date -d "$ts" +%s 2>/dev/null) \
-					|| entry_time=$(date -jf '%Y-%m-%dT%H:%M:%SZ' "$ts" +%s 2>/dev/null) \
-					|| entry_time=0
-				local age=$(( now - entry_time ))
-				[[ "$age" -gt "$max_age_seconds" ]] && continue
-			fi
-		fi
+# Walk a JSONL transcript file backwards to find the most recent assistant
+# turn with non-empty text. Avoids loading the entire file into memory by
+# streaming with `tac` when available; falls back to `tail -r` on BSD.
+_compass_transcript_read_from_file() {
+	local path="$1"
+	[[ -f "$path" ]] || return 1
+
+	local reverser=""
+	if command -v tac >/dev/null 2>&1; then
+		reverser="tac"
+	elif command -v tail >/dev/null 2>&1 && tail -r </dev/null >/dev/null 2>&1; then
+		reverser="tail -r"
+	fi
 
-		local content
-		content=$(printf '%s' "$line" | jq -r '.payload.content // .payload.text // empty' 2>/dev/null) || continue
-		[[ -n "$content" ]] && prior_turn="$content"
-	done < "$log_path"
+	local line role content
+	if [[ -n "$reverser" ]]; then
+		while IFS= read -r line; do
+			[[ -z "$line" ]] && continue
+			role=$(_compass_transcript_role "$line") || continue
+			[[ "$role" == "assistant" ]] || continue
+			content=$(_compass_transcript_extract_text "$line") || continue
+			[[ -n "$content" ]] && { printf '%s' "$content"; return 0; }
+		done < <(eval "$reverser" "\"$path\"" 2>/dev/null)
+	else
+		# Final fallback: forward scan, keep the last match.
+		local found=""
+		while IFS= read -r line; do
+			[[ -z "$line" ]] && continue
+			role=$(_compass_transcript_role "$line") || continue
+			[[ "$role" == "assistant" ]] || continue
+			content=$(_compass_transcript_extract_text "$line") || continue
+			[[ -n "$content" ]] && found="$content"
+		done < "$path"
+		[[ -n "$found" ]] && { printf '%s' "$found"; return 0; }
+	fi
 
-	[[ -n "$prior_turn" ]] || return 1
-	printf '%s' "$prior_turn"
+	return 1
 }
 
 # Read the prior assistant turn.
-#   $1 — session_id
+#   $1 — transcript_path (from hook JSON payload; may be empty)
 #   $2 — max_chars (from config: transcript.prior_turn_chars_max)
-#   $3 — max_age_seconds (from config: transcript.transcript_max_age_seconds)
-# Echoes the sanitized, truncated prior assistant turn, or empty string.
+# Echoes the sanitized, truncated prior assistant turn, or the empty string.
 compass_read_prior_turn() {
-	local session_id="${1:-unknown}"
+	local transcript_path="${1:-}"
 	local max_chars="${2:-800}"
-	local max_age_seconds="${3:-300}"
 
-	local raw=""
-
-	# Source 1: CLAUDE_TRANSCRIPT_PATH
-	if [[ -n "${CLAUDE_TRANSCRIPT_PATH:-}" ]]; then
-		raw=$(_compass_transcript_from_path "$CLAUDE_TRANSCRIPT_PATH" "$session_id" "$max_age_seconds") || raw=""
-	fi
-
-	# Source 2: Onlooker event log
-	if [[ -z "$raw" ]]; then
-		raw=$(_compass_transcript_from_event_log "$session_id" "$max_age_seconds") || raw=""
-	fi
+	[[ -z "$transcript_path" ]] && return 0
 
+	local raw=""
+	raw=$(_compass_transcript_read_from_file "$transcript_path") || raw=""
 	[[ -z "$raw" ]] && return 0
 
-	# Sanitize and truncate — compass-sanitizer.sh must be sourced by the caller.
+	# compass-sanitizer.sh is sourced by the caller (hook script).
 	compass_sanitize "$raw" "$max_chars"
 }

package/plugins/inspector/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "inspector",
+  "version": "0.1.0",
+  "description": "Per-edit lint and typecheck gate. Runs the project's configured checks on just the touched file after every Write / Edit / MultiEdit, so the agent sees its own type errors before claiming success. Cheaper than proctor (which runs project-wide verification at Stop); complements assayer (which catches the agent lying about claims). Builds on the Onlooker ecosystem plugin.",
+  "author": {
+    "name": "Onlooker Community",
+    "url": "https://onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "repository": "https://github.com/onlooker-community/ecosystem",
+  "license": "MIT",
+  "skills": [],
+  "agents": []
+}

package/plugins/inspector/README.md

@@ -0,0 +1,155 @@
+# Inspector
+
+Per-edit lint and typecheck gate for the Onlooker ecosystem — runs the project's
+configured checks on **just the touched file** after every `Write`, `Edit`, and
+`MultiEdit`, so the agent sees its own lint and type errors before it claims
+success.
+
+Inspector is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker
+observability substrate (`~/.onlooker/`) is present.
+
+## Why it exists
+
+The ecosystem already has plugins that judge agent output after the fact and
+plugins that gate ambiguous writes before they happen. What it didn't have until
+now is a fast feedback loop that runs after every edit and tells the agent
+*whether the code it just wrote actually compiles*. Inspector is that loop.
+
+- **Not [proctor]** (planned) — proctor runs the project's full verification
+  command at `Stop`. Inspector runs only on touched files, only on `PostToolUse`.
+  Cheaper, fires far more often, narrower scope.
+- **Not [assayer]** — assayer parses the agent's final message for testable
+  claims and cross-checks them against actual exit codes in the transcript.
+  Assayer catches the agent *lying* about claims. Inspector ensures the agent
+  has *accurate ground truth* to make claims from. They compose: inspector
+  emits real pass/fail signals; assayer can later confirm the agent's claims
+  line up with those signals.
+- **Not a build system** — inspector runs the configured command, captures the
+  result, emits an event, exits. No cross-file caching, no dependency graphs.
+
+## How it works
+
+| Hook | Matcher | What Inspector does |
+|------|---------|---------------------|
+| `PostToolUse` | `Edit`, `Write`, `MultiEdit` | Resolves the touched file from `tool_input.file_path`, looks up the configured checks for the file's extension, runs each check with a per-check timeout, and emits `inspector.check.passed` / `.failed` / `.skipped` plus a single `inspector.run.completed` summary. Bounded by `total_timeout_seconds`. Always exits 0 — inspector is advisory and never blocks the tool call. |
+
+The hook's stdout (the additional-context channel for `PostToolUse` hooks) is
+the agent-facing summary. By default it's quiet on clean runs:
+
+```
+inspector: src/cart.ts
+  ✗ biome (3 issues, exit 1)
+      src/cart.ts:42:5 — Unused variable 'subtotal'
+      src/cart.ts:51:3 — Missing return type annotation
+      src/cart.ts:64:9 — Unreachable code
+  ✗ tsc (1 issue(s), exit 2)
+      src/cart.ts:42:5 — Type 'string | undefined' is not assignable to 'string'
+```
+
+Set `inspector.show_clean_runs: true` to surface the file header on passing
+checks too. The agent sees this on its next turn.
+
+## Activation
+
+Inspector ships disabled. Opt in per project (or globally) by adding the
+`inspector` block to `.claude/settings.json`:
+
+```jsonc
+{
+  "inspector": {
+    "enabled": true,
+    "checks": {
+      ".ts":  [{ "name": "biome",      "kind": "lint",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "kind": "typecheck", "argv": ["tsc",   "--noEmit"] }],
+      ".tsx": [{ "name": "biome",      "kind": "lint",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "kind": "typecheck", "argv": ["tsc",   "--noEmit"] }],
+      ".py":  [{ "name": "ruff",       "kind": "lint",      "argv": ["ruff",  "check", "${file}"] }],
+      ".sh":  [{ "name": "shellcheck", "kind": "lint",      "argv": ["shellcheck", "${file}"] }]
+    }
+  }
+}
+```
+
+Each check is an `{ name, kind, argv }` object. `kind` is one of `lint` or
+`typecheck` (used for downstream grouping). `argv` is the literal argv array;
+the following placeholders are expanded before exec:
+
+| Placeholder       | Resolves to                                |
+|-------------------|--------------------------------------------|
+| `${file}`         | absolute path to the touched file          |
+| `${file_relative}`| path relative to the repo root             |
+| `${repo_root}`    | the repo's `git rev-parse --show-toplevel` |
+
+A bare argv array (`["shellcheck", "${file}"]`) is also accepted as a shorthand
+— inspector treats the first entry as the check name and the kind as `lint`.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | Master switch. |
+| `timeout_seconds_per_check` | `10` | Wall-clock cap per check. Exceeded → `inspector.check.skipped` with `reason: "timeout"`. |
+| `total_timeout_seconds` | `30` | Wall-clock cap for the whole run. Remaining checks emit `.skipped` with `reason: "total_budget_exhausted"`. |
+| `output_excerpt_max_bytes` | `4096` | Cap on captured output, both in the event and shown to the agent. Excess is replaced with `…[truncated]`. |
+| `show_clean_runs` | `false` | If `true`, the agent-facing summary includes passing checks too. Off by default to keep token usage low. |
+| `exclude_paths` | `["node_modules", ".git", "vendor", ".venv", "dist", ".next", ".nuxt", "build", "__pycache__", "target", "coverage"]` | Containment match against the file's path relative to the repo root. A match emits `inspector.check.skipped` with `reason: "excluded_path"` and runs no checks. |
+| `checks` | `{}` | Map of file extension (with leading dot) to an array of check definitions. Empty by default — opt in per project. |
+
+Config precedence: plugin defaults < `~/.claude/settings.json` (`.inspector`) <
+`<repo>/.claude/settings.json` (`.inspector`). Each layer fully replaces the
+`checks` array for a given extension; per-entry deep-merge is intentionally not
+supported because the override behavior would be unpredictable.
+
+## Events
+
+All events are registered in `@onlooker-community/schema`.
+
+| Event | When | Notable payload fields |
+|---|---|---|
+| `inspector.check.passed` | A check returned exit 0 | `file_path`, `tool_name`, `check_name`, `check_kind`, `argv`, `duration_ms` |
+| `inspector.check.failed` | A check returned non-zero | `exit_code`, `issue_count` (best-effort, may be `null`), `output_excerpt`, `output_truncated` |
+| `inspector.check.skipped` | A check or whole file was not run | `reason`: one of `disabled`, `excluded_path`, `no_extension_match`, `not_in_repo`, `tool_missing`, `timeout`, `total_budget_exhausted` |
+| `inspector.run.completed` | Once per hook fire after all checks | `checks_run`, `checks_passed`, `checks_failed`, `checks_skipped`, `duration_ms` |
+
+Downstream consumers that just want "did this edit produce broken code?" read
+`inspector.run.completed` and check `checks_failed > 0`. Consumers that want
+per-tool detail subscribe to `inspector.check.*`.
+
+## Whole-project checks (tsc, mypy, …)
+
+TypeScript's typecheck is project-scoped: `tsc --noEmit` checks every file, not
+just the touched one. There is no meaningful "tsc on one file." The supported
+pattern is to run the full project tsc and rely on its incremental cache
+(`tsBuildInfoFile`) to keep latency down. Same applies to mypy, cargo check,
+and golangci-lint.
+
+The downside is that `tsc --noEmit` reports errors in *every* file. Inspector's
+v1 surfaces all of them to the agent. A follow-up will add an opt-in filter
+that shows only errors mentioning the touched file plus a collateral-error
+count.
+
+## Failure modes
+
+Inspector is advisory — it never blocks the tool call. Specifically:
+
+- Missing tool on PATH → `.skipped` event, no agent-facing output
+- Timeout → `.skipped` event, one-line note to the agent
+- Hook script error → exit 0 with no event (last-resort path)
+- Schema validation error → logged to stderr, hook continues
+
+## Compatibility
+
+- bash 3.2+ (the macOS system bash is supported; no `mapfile` / `readarray` /
+  associative arrays)
+- `jq` is required (already a hard requirement for the ecosystem substrate)
+- `timeout` from coreutils is used when present; falls back to no-timeout mode
+  when absent (and emits a warning to the inspector hook log)
+
+## Design
+
+See [`docs/design.md`](docs/design.md) for the full design record, including
+the rationale for project-wide check semantics, output filtering, and open
+questions.
+
+[proctor]: https://github.com/onlooker-community/ecosystem#planned
+[assayer]: ../assayer

package/plugins/inspector/config.json

@@ -0,0 +1,25 @@
+{
+  "plugin_name": "inspector",
+  "storage_path": "~/.onlooker",
+  "inspector": {
+    "enabled": false,
+    "timeout_seconds_per_check": 10,
+    "total_timeout_seconds": 30,
+    "output_excerpt_max_bytes": 4096,
+    "show_clean_runs": false,
+    "exclude_paths": [
+      "node_modules",
+      ".git",
+      "vendor",
+      ".venv",
+      "dist",
+      ".next",
+      ".nuxt",
+      "build",
+      "__pycache__",
+      "target",
+      "coverage"
+    ],
+    "checks": {}
+  }
+}