@onlooker-community/ecosystem 0.21.0 → 0.23.0

package/release-please-config.json

@@ -190,6 +190,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/historian": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "historian",
+      "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/scripts/hooks/memory-recall-tracker.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# Onlooker Memory Recall Tracker
+# Invoked by SessionStart (matcher: *) when a session boots, resumes, or
+# restarts after compaction. Emits one canonical `memory.recalled` event
+# per typed-memory file present at the project's per-checkout memory
+# store path. This approximates the substrate signal "these memories are
+# now in the model's context for the session about to begin".
+#
+# Curator's usage tracker (and any future plugin that reasons about how
+# often a memory is in scope) depends on this. The signal is coarse —
+# per-session-load rather than per-recall — but actionable in aggregate.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - No-ops when there is no project memory store, no git context, or
+#     when the source is `compact` (compaction is metadata-only; the
+#     same memories remain in scope, so re-emitting would double-count).
+
+set -uo pipefail # No -e: never block session startup
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/validate-path.sh
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+# shellcheck source=../lib/onlooker-schema.sh
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+
+# Standard hook health instrumentation. hook_register sets up the timer;
+# hook_set_context exports _HOOK_SESSION_ID + _HOOK_EVENT_NAME so failures
+# attach to the right session in ~/.onlooker/logs/hook-health.jsonl;
+# hook_success / hook_failure close the health record.
+hook_register "memory-recall-tracker" "Memory Recall Tracker" "Emits memory.recalled per typed memory file present at SessionStart"
+
+INPUT=$(cat 2>/dev/null || true)
+hook_set_context "$INPUT" "SessionStart"
+
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+SOURCE=$(printf '%s' "$INPUT" | jq -r '.source // "startup"' 2>/dev/null) || SOURCE="startup"
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+# Compaction reloads the session with the same memories still in scope.
+# Re-emitting on each compaction would inflate usage counts; skip.
+if [[ "$SOURCE" == "compact" ]]; then
+	hook_success
+	exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve project_key. Mirrors the SHA256-of-remote-URL + common-dir
+# fallback every memory plugin uses (see plugins/librarian/scripts/lib/
+# librarian-project-key.sh and friends): if there's no origin remote,
+# anchor the key on git --git-common-dir rather than --show-toplevel so
+# two worktrees of the same local-only repo share a key.
+# ---------------------------------------------------------------------------
+
+_memory_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
+}
+
+_memory_repo_root_via_common_dir() {
+	local cwd="$1"
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+	# git-common-dir may be relative; resolve relative to cwd.
+	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
+		# common_dir is typically the .git dir of the main repo; its
+		# parent is the canonical repo root (shared across worktrees).
+		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"
+}
+
+PROJECT_KEY=""
+if git -C "$CWD" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+	REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null || true)
+	if [[ -n "$REMOTE" ]]; then
+		PROJECT_KEY=$(_memory_sha256_first12 "remote:${REMOTE}")
+	else
+		ROOT=$(_memory_repo_root_via_common_dir "$CWD")
+		if [[ -n "$ROOT" ]]; then
+			PROJECT_KEY=$(_memory_sha256_first12 "root:${ROOT}")
+		fi
+	fi
+fi
+
+if [[ -z "$PROJECT_KEY" ]]; then
+	hook_success
+	exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve the per-project typed-memory store at
+# ~/.claude/projects/<encoded>/memory/. Claude Code encodes the project
+# path by replacing path separators with `-` and prepending a leading `-`.
+# Prefer $CLAUDE_PROJECT_ENCODED when the harness has populated it; fall
+# back to deriving from CWD.
+# ---------------------------------------------------------------------------
+
+ENCODED="${CLAUDE_PROJECT_ENCODED:-}"
+if [[ -z "$ENCODED" ]]; then
+	# Encode the absolute cwd: drop leading slash, swap remaining `/` for
+	# `-`, prepend the leading `-`.
+	ABS_CWD=$(cd "$CWD" 2>/dev/null && pwd -P) || ABS_CWD=""
+	if [[ -n "$ABS_CWD" ]]; then
+		ENCODED=$(printf '%s' "$ABS_CWD" | sed -E 's#/#-#g')
+	fi
+fi
+
+MEMORY_DIR="${CLAUDE_HOME}/projects/${ENCODED}/memory"
+if [[ -z "$ENCODED" || ! -d "$MEMORY_DIR" ]]; then
+	hook_success
+	exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Walk every *.md file (excluding MEMORY.md itself, which is the index, not
+# a memory). For each, parse the YAML frontmatter's `type` field. Skip
+# files whose type isn't one of the four valid enum values — emitting
+# anything else would fail schema validation and the event would be
+# silently dropped.
+# ---------------------------------------------------------------------------
+
+_extract_type() {
+	local path="$1"
+	[[ -f "$path" ]] || return 0
+	# Parse frontmatter type via awk + sed (no python dep, no yq dep).
+	awk '
+		NR == 1 && /^---/ { in_fm = 1; next }
+		in_fm && /^---/ { exit }
+		in_fm
+	' "$path" 2>/dev/null \
+		| sed -nE 's/^type:[[:space:]]*(.*)$/\1/p' \
+		| head -1 \
+		| tr -d '"' \
+		| tr -d "'"
+}
+
+position=0
+for file in "$MEMORY_DIR"/*.md; do
+	[[ -f "$file" ]] || continue
+	fname=$(basename "$file")
+	[[ "$fname" == "MEMORY.md" ]] && continue
+
+	memory_type=$(_extract_type "$file")
+	case "$memory_type" in
+		user|feedback|project|reference)
+			;;
+		*)
+			# Untyped or unknown-typed memories don't fit the schema's
+			# enum. Skip silently rather than tank schema validation.
+			continue
+			;;
+	esac
+
+	payload=$(jq -cn \
+		--arg project_key "$PROJECT_KEY" \
+		--arg memory_file "$fname" \
+		--arg memory_type "$memory_type" \
+		--argjson recall_position "$position" \
+		'{
+			project_key: $project_key,
+			memory_file: $memory_file,
+			memory_type: $memory_type,
+			recall_position: $recall_position
+		}')
+
+	# Use the canonical ecosystem plugin name (matches the
+	# `${ONLOOKER_PLUGIN_NAME:-onlooker}` default that scripts/lib/
+	# onlooker-emit.sh and onlooker-event.mjs both fall back to). Other
+	# substrate-level emissions land under "onlooker" too, so this stays
+	# consistent with the existing event stream.
+	local_plugin="${ONLOOKER_PLUGIN_NAME:-onlooker}"
+
+	params=$(jq -cn \
+		--arg plugin "$local_plugin" \
+		--arg sid "$SESSION_ID" \
+		--arg type "memory.recalled" \
+		--argjson payload "$payload" \
+		'{ plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload }')
+
+	event_json=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$local_plugin" \
+		  node "$_ONLOOKER_EVENT_JS" emit 2>/dev/null) || event_json=""
+	[[ -z "$event_json" ]] && continue
+
+	onlooker_append_event "$event_json" || true
+	position=$((position + 1))
+done
+
+hook_success
+exit 0

package/test/bats/historian-prompt-submit.bats

@@ -0,0 +1,236 @@
+#!/usr/bin/env bats
+#
+# Exercises the historian UserPromptSubmit retrieval pipeline end-to-end
+# against a synthetic ollama daemon (a fake `curl` binary on PATH that
+# returns predictable embeddings keyed on sentinel substrings in the
+# prompt). Indexing happens via the real SessionEnd hook against the
+# same stub, so the test exercises both halves of the embedder
+# integration.
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/historian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/historian-retrieval-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/historian-project-key.sh"
+  PROJECT_KEY=$(historian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  HIST_DIR="${ONLOOKER_DIR}/historian/${PROJECT_KEY}"
+  ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/curl" <<'STUB'
+#!/usr/bin/env bash
+# Mini curl stub for historian bats tests.
+# Parses just enough of the curl arg shape to find the URL and the -d
+# payload. Returns deterministic embeddings keyed on sentinel substrings
+# in the prompt.
+url=""
+payload=""
+prev=""
+for arg in "$@"; do
+  case "$prev" in
+    -d|--data|--data-raw)
+      payload="$arg"; prev=""; continue ;;
+    --max-time|-o|-H|--header)
+      prev=""; continue ;;
+  esac
+  case "$arg" in
+    -d|--data|--data-raw|--max-time|-o|-H|--header)
+      prev="$arg" ;;
+    -*)
+      ;;
+    *)
+      [[ -z "$url" ]] && url="$arg" ;;
+  esac
+done
+
+# An env var toggles the probe success so the same stub serves the
+# "embedder unavailable" test case.
+if [[ "${HISTORIAN_STUB_OLLAMA_AVAILABLE:-1}" == "0" ]]; then
+  exit 7
+fi
+
+if [[ "$url" == */api/tags ]]; then
+  exit 0
+fi
+
+if [[ "$url" == */api/embeddings ]]; then
+  prompt=$(printf '%s' "$payload" | jq -r '.prompt // ""' 2>/dev/null)
+  case "$prompt" in
+    *redash*) printf '{"embedding":[1,0,0]}' ;;
+    *kafka*)  printf '{"embedding":[0,1,0]}' ;;
+    *postgres*) printf '{"embedding":[0,0,1]}' ;;
+    *) printf '{"embedding":[0.5,0.5,0.5]}' ;;
+  esac
+  exit 0
+fi
+
+exit 1
+STUB
+  chmod +x "${STUB_BIN}/curl"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  TRANSCRIPT="${BATS_TEST_TMPDIR}/transcript.jsonl"
+  SESSION_ID="sess-retrieval"
+
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' \
+    '{"historian":{"enabled":true,"indexing":{"min_transcript_chars_to_index":50,"chunk_target_chars":400,"chunk_overlap_chars":50},"retrieval":{"cooldown_seconds":60,"max_retrievals_per_session":5,"min_prompt_chars":40,"min_similarity":0.55,"max_age_days":365}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+
+  INDEX_HOOK="${PLUGIN_ROOT}/scripts/hooks/historian-session-end.sh"
+  RETRIEVE_HOOK="${PLUGIN_ROOT}/scripts/hooks/historian-prompt-submit.sh"
+}
+
+_index_input() {
+  local sid="${1:-$SESSION_ID}"
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "$sid" --arg transcript "$TRANSCRIPT" \
+    '{cwd:$cwd, session_id:$sid, transcript_path:$transcript, hook_event_name:"SessionEnd"}'
+}
+
+_retrieve_input() {
+  local prompt="$1" sid="${2:-current}"
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "$sid" --arg prompt "$prompt" \
+    '{cwd:$cwd, session_id:$sid, prompt:$prompt, hook_event_name:"UserPromptSubmit"}'
+}
+
+_append_text_turn() {
+  local role="$1" text="$2"
+  jq -cn --arg role "$role" --arg text "$text" \
+    '{role:$role, content:$text}' >> "$TRANSCRIPT"
+}
+
+_index_session() {
+  local sid="$1"
+  shift
+  : > "$TRANSCRIPT"
+  while [ $# -gt 0 ]; do
+    _append_text_turn "user" "$1"; shift
+    [ $# -gt 0 ] && { _append_text_turn "assistant" "$1"; shift; }
+  done
+  bash -c "printf '%s' '$(_index_input "$sid")' | '$INDEX_HOOK'" >/dev/null
+}
+
+@test "retrieval no-op when historian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  run bash -c "printf '%s' '$(_retrieve_input "a prompt long enough to clear the floor and trigger retrieval but historian is off")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  [ ! -f "$ONLOOKER_EVENTS_LOG" ] || ! grep -q '"historian.retrieval' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "retrieval skipped when prompt is shorter than min_prompt_chars" {
+  run bash -c "printf '%s' '$(_retrieve_input "tiny")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "short_prompt"' >/dev/null
+}
+
+@test "indexing embeds chunks when ollama is up" {
+  _index_session "$SESSION_ID" \
+    "We are debugging a redash dashboard problem with timezone offsets and saved query parameters this morning." \
+    "Sure — the latest version always passes UTC because of a chart migration we did last week."
+
+  local jsonl="${HIST_DIR}/sessions/${SESSION_ID}.jsonl"
+  [ -f "$jsonl" ]
+  jq -e '.embedding | type == "array" and length == 3' "$jsonl" >/dev/null
+}
+
+@test "retrieval surfaces a matching past chunk" {
+  # Index a past session containing a "redash" topic.
+  _index_session "past-1" \
+    "We are debugging a redash dashboard problem with timezone offsets and saved query parameters this morning." \
+    "Sure — the latest version always passes UTC because of a chart migration we did last week."
+
+  # New session, same project, query about redash → should match.
+  run bash -c "printf '%s' '$(_retrieve_input "Hitting another redash dashboard timezone issue on the same saved query parameters again today")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Historian: a past chunk looks similar"* ]]
+  [[ "$ctx" == *"redash"* ]]
+
+  grep '"event_type":"historian.retrieval.surfaced"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.similarity >= 0.55 and .payload.source_session_id == "past-1"' >/dev/null
+}
+
+@test "retrieval returns empty when no chunk clears the similarity floor" {
+  # Past session about kafka — query about postgres falls below the
+  # 0.55 floor (the embedding vectors are orthogonal in the stub).
+  _index_session "past-2" \
+    "Investigating kafka consumer lag on the ingest pipeline today after the rebalance event yesterday." \
+    "Looks like the rebalance left a stale offset; manual reset cleared it."
+
+  run bash -c "printf '%s' '$(_retrieve_input "Working on a postgres migration plan today for our settings tables to add new columns safely")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty"' >/dev/null
+}
+
+@test "retrieval skipped on cooldown" {
+  _index_session "past-3" \
+    "Yet another redash dashboard query that we had to fix the timezone on this morning to make the report run again." \
+    "ok"
+
+  # First retrieval surfaces something.
+  run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone problem again on the saved query parameters this morning afternoon")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  grep -q '"event_type":"historian.retrieval.surfaced"' "$ONLOOKER_EVENTS_LOG"
+
+  rm -f "$ONLOOKER_EVENTS_LOG"
+
+  # Immediate second retrieval (same session) hits the cooldown gate
+  # (60s) and gets skipped without calling the embedder.
+  run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone problem follow-up just a moment after the previous prompt cleared")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "cooldown"' >/dev/null
+}
+
+@test "retrieval skipped when the embedder is unreachable" {
+  _index_session "past-4" \
+    "Yet another redash dashboard query that we had to fix the timezone on this morning to make the report run again." \
+    "ok"
+
+  # Turn off the stub so the probe fails.
+  HISTORIAN_STUB_OLLAMA_AVAILABLE=0 \
+    run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone problem long enough to clear the prompt floor for retrieval")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+
+  grep -q '"event_type":"historian.embedder.unavailable"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "embedder_unavailable"' >/dev/null
+}
+
+@test "retrieval excludes chunks from the current session id" {
+  # Index the same session id we'll then query from — should be excluded.
+  _index_session "current" \
+    "Working on a redash dashboard right now in this very session of the test framework that we are running." \
+    "ok"
+
+  run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone trouble inside this very session of the test framework")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty"' >/dev/null
+}