@onlooker-community/ecosystem 0.21.0 → 0.23.0

package/plugins/historian/scripts/hooks/historian-session-end.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# Historian SessionEnd indexing pipeline.
+#
+# Reads the session transcript, drops tool calls / tool results, chunks
+# the remaining user + assistant turns at turn boundaries, redacts
+# secret-shaped substrings, and appends one JSONL line per surviving
+# chunk to ~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session shutdown.
+#   - No-ops when historian.enabled is not true.
+#   - No-ops when there is no project key, no transcript path, or the
+#     transcript is shorter than min_transcript_chars_to_index.
+#   - Indexing failures are fail-soft: an emitted historian.indexing.complete
+#     with outcome "skipped" + a skip_reason is the worst case.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+fi
+
+# shellcheck source=../lib/historian-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-config.sh"
+# shellcheck source=../lib/historian-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-project-key.sh"
+# shellcheck source=../lib/historian-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-ulid.sh"
+# shellcheck source=../lib/historian-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-storage.sh"
+# shellcheck source=../lib/historian-emit.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-emit.sh"
+# shellcheck source=../lib/historian-transcript.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-transcript.sh"
+# shellcheck source=../lib/historian-chunker.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-chunker.sh"
+# shellcheck source=../lib/historian-sanitizer.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-sanitizer.sh"
+# shellcheck source=../lib/historian-embedder.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-embedder.sh"
+
+INPUT=$(cat 2>/dev/null || true)
+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=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+REPO_ROOT=$(historian_project_repo_root "$CWD")
+historian_config_load "$REPO_ROOT"
+historian_config_enabled || exit 0
+
+PROJECT_KEY=$(historian_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+historian_storage_init "$PROJECT_KEY" || exit 0
+REMOTE_URL=$(historian_project_remote_url "$CWD")
+historian_storage_write_manifest "$PROJECT_KEY" "$REMOTE_URL" "$REPO_ROOT" || true
+
+# ----------------------------------------------------------------------------
+# Transcript-availability check first — emit no started/complete for the
+# transcript_unavailable path, just a complete-with-skip so the timeline
+# reads cleanly. Once we have a real char count, emit started with that
+# count (the schema requires transcript_chars on started, so emitting
+# zero before the read produced misleading telemetry).
+# ----------------------------------------------------------------------------
+
+SCAN_START_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| SCAN_START_MS=$(($(date +%s) * 1000))
+
+_emit_skip() {
+	local reason="$1"
+	local now_ms duration_ms
+	now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+		|| now_ms=$(($(date +%s) * 1000))
+	duration_ms=$((now_ms - SCAN_START_MS))
+	historian_emit "historian.indexing.complete" "$SESSION_ID" "$(jq -cn \
+		--arg outcome "skipped" \
+		--arg skip_reason "$reason" \
+		--argjson duration_ms "$duration_ms" \
+		'{ outcome: $outcome, skip_reason: $skip_reason, duration_ms: $duration_ms }')"
+}
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_emit_skip "transcript_unavailable"
+	exit 0
+fi
+
+MIN_CHARS=$(historian_config_get '.historian.indexing.min_transcript_chars_to_index')
+[[ -z "$MIN_CHARS" || "$MIN_CHARS" == "null" ]] && MIN_CHARS=1200
+
+TURNS=$(historian_transcript_load "$TRANSCRIPT_PATH")
+TRANSCRIPT_CHARS=$(historian_transcript_char_count "$TURNS")
+[[ -z "$TRANSCRIPT_CHARS" || "$TRANSCRIPT_CHARS" == "null" ]] && TRANSCRIPT_CHARS=0
+
+historian_emit "historian.indexing.started" "$SESSION_ID" "$(jq -cn \
+	--arg session_id "$SESSION_ID" \
+	--argjson transcript_chars "$TRANSCRIPT_CHARS" \
+	'{ session_id: $session_id, transcript_chars: $transcript_chars }')"
+
+if (( TRANSCRIPT_CHARS < MIN_CHARS )); then
+	_emit_skip "too_short"
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Chunker → sanitizer → JSONL store.
+# ----------------------------------------------------------------------------
+
+TARGET_CHARS=$(historian_config_get '.historian.indexing.chunk_target_chars')
+[[ -z "$TARGET_CHARS" || "$TARGET_CHARS" == "null" ]] && TARGET_CHARS=2400
+OVERLAP_CHARS=$(historian_config_get '.historian.indexing.chunk_overlap_chars')
+[[ -z "$OVERLAP_CHARS" || "$OVERLAP_CHARS" == "null" ]] && OVERLAP_CHARS=400
+
+CHUNKS=$(historian_chunker_split "$TURNS" "$TARGET_CHARS" "$OVERLAP_CHARS")
+NEVER_INDEX_PATHS=$(historian_config_get '.historian.sanitization.never_index_paths | tojson')
+[[ -z "$NEVER_INDEX_PATHS" || "$NEVER_INDEX_PATHS" == "null" ]] && NEVER_INDEX_PATHS='[]'
+
+# Honor the two on/off knobs from the config block.
+REDACT_SECRETS=$(historian_config_get '.historian.sanitization.redact_secret_patterns')
+[[ -z "$REDACT_SECRETS" || "$REDACT_SECRETS" == "null" ]] && REDACT_SECRETS="true"
+DROP_SKIP=$(historian_config_get '.historian.sanitization.drop_skip_marker')
+[[ -z "$DROP_SKIP" || "$DROP_SKIP" == "null" ]] && DROP_SKIP="true"
+
+SANITIZED=$(historian_sanitizer_run "$CHUNKS" "$NEVER_INDEX_PATHS" "$REDACT_SECRETS" "$DROP_SKIP")
+KEPT=$(printf '%s' "$SANITIZED" | jq '.kept')
+DROPPED=$(printf '%s' "$SANITIZED" | jq '.dropped')
+
+# Probe the embedder once before the chunk loop. If unavailable we
+# index without vectors. The retriever shipped today is embedding-only,
+# so chunks written without an `embedding` field are persisted but
+# invisible to retrieval until they are re-indexed against a working
+# embedder. Chunk bodies stay intact, so re-indexing is a re-embed pass
+# rather than a full re-chunk.
+EMBEDDER_READY=0
+EMBEDDER_BACKEND=$(historian_config_get '.historian.embedder.backend')
+[[ -z "$EMBEDDER_BACKEND" || "$EMBEDDER_BACKEND" == "null" ]] && EMBEDDER_BACKEND="none"
+if [[ "$EMBEDDER_BACKEND" != "none" ]]; then
+	if historian_embedder_available; then
+		EMBEDDER_READY=1
+	else
+		historian_emit "historian.embedder.unavailable" "$SESSION_ID" "$(jq -cn \
+			--arg backend "$EMBEDDER_BACKEND" \
+			'{ backend: $backend }')"
+	fi
+fi
+
+# Re-indexing replaces the existing session file rather than appending,
+# so SessionEnd is safely idempotent if re-fired against the same id.
+historian_storage_reset_session "$PROJECT_KEY" "$SESSION_ID"
+
+NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+CHUNKS_INDEXED=0
+KEPT_COUNT=$(printf '%s' "$KEPT" | jq 'length' 2>/dev/null) || KEPT_COUNT=0
+
+for ((i = 0; i < KEPT_COUNT; i++)); do
+	CHUNK=$(printf '%s' "$KEPT" | jq -c ".[$i]")
+	[[ -z "$CHUNK" || "$CHUNK" == "null" ]] && continue
+
+	CHUNK_ID=$(historian_ulid)
+	REDACTION_COUNT=$(printf '%s' "$CHUNK" | jq -r '.redaction_count // 0')
+	BODY=$(printf '%s' "$CHUNK" | jq -r '.body_redacted // ""')
+
+	# Build the base record. The embedding (if any) is added below.
+	RECORD=$(jq -cn \
+		--arg chunk_id "$CHUNK_ID" \
+		--arg session_id "$SESSION_ID" \
+		--argjson chunk_input "$CHUNK" \
+		--arg created_at "$NOW_TS" \
+		--arg source "local" \
+		'$chunk_input + {
+			chunk_id: $chunk_id,
+			session_id: $session_id,
+			created_at: $created_at,
+			source: $source
+		}')
+
+	if (( EMBEDDER_READY == 1 )) && [[ -n "$BODY" ]]; then
+		EMBEDDING=$(historian_embedder_embed "$BODY")
+		if [[ -n "$EMBEDDING" ]]; then
+			RECORD=$(printf '%s' "$RECORD" | jq -c --argjson v "$EMBEDDING" \
+				'. + { embedding: $v }')
+		fi
+	fi
+
+	if historian_storage_append_chunk "$PROJECT_KEY" "$SESSION_ID" "$RECORD"; then
+		CHUNKS_INDEXED=$((CHUNKS_INDEXED + 1))
+		if (( REDACTION_COUNT > 0 )); then
+			historian_emit "historian.chunk.sanitized" "$SESSION_ID" "$(jq -cn \
+				--arg chunk_id "$CHUNK_ID" \
+				--argjson redaction_count "$REDACTION_COUNT" \
+				'{ chunk_id: $chunk_id, redaction_count: $redaction_count }')"
+		fi
+	fi
+done
+
+# Emit one chunk.dropped event per skip reason summary (caps at the
+# number of unique reasons; per-chunk emission would spam the log).
+DROPPED_COUNT=$(printf '%s' "$DROPPED" | jq 'length' 2>/dev/null) || DROPPED_COUNT=0
+if (( DROPPED_COUNT > 0 )); then
+	for reason in $(printf '%s' "$DROPPED" | jq -r '.[].reason' | sort -u); do
+		historian_emit "historian.chunk.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "$reason" \
+			'{ reason: $reason }')"
+	done
+fi
+
+NOW_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| NOW_MS=$(($(date +%s) * 1000))
+DURATION_MS=$((NOW_MS - SCAN_START_MS))
+
+historian_emit "historian.indexing.complete" "$SESSION_ID" "$(jq -cn \
+	--arg outcome "ok" \
+	--argjson chunks_indexed "$CHUNKS_INDEXED" \
+	--argjson chunks_dropped "$DROPPED_COUNT" \
+	--argjson duration_ms "$DURATION_MS" \
+	'{
+		outcome: $outcome,
+		chunks_indexed: $chunks_indexed,
+		chunks_dropped: $chunks_dropped,
+		duration_ms: $duration_ms
+	}')"
+
+exit 0

package/plugins/historian/scripts/lib/historian-chunker.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Chunker for Historian.
+#
+# Given a JSON array of normalized turns (from historian-transcript.sh),
+# produces a JSON array of chunk records. Each chunk:
+#   - Respects turn boundaries (no mid-turn splits)
+#   - Targets `target_chars` characters with `overlap_chars` overlap
+#     (carrying the last N chars of one chunk's content as the start of
+#     the next)
+#   - Records start_turn_index, end_turn_index, body_chars
+#
+# Character-based chunking instead of token-based: tokenizers vary by
+# embedder, and the chunker shouldn't have to know which embedder will
+# run downstream. Char counts approximate token counts at ~4 chars / token
+# for English-ish prose; configs are tunable.
+
+# Usage: historian_chunker_split <turns_json> <target_chars> <overlap_chars>
+# Output: JSON array of chunks.
+historian_chunker_split() {
+	local turns="${1:-[]}"
+	local target_chars="${2:-2400}"
+	local overlap_chars="${3:-400}"
+
+	python3 - "$target_chars" "$overlap_chars" "$turns" <<'PY'
+import json, sys
+
+target = int(sys.argv[1])
+overlap = max(0, int(sys.argv[2]))
+turns = json.loads(sys.argv[3] or "[]")
+
+chunks = []
+chunk_index = 0
+buf_parts = []
+buf_chars = 0
+buf_start = None
+buf_end = None
+
+# Pending overlap text carried from the previous chunk. It seeds the next
+# chunk's body but doesn't get attributed a turn (the overlap is purely
+# textual continuity for the embedder).
+pending_overlap = ""
+
+
+def flush(force_text=None):
+    """Emit the current buffer as a chunk. force_text overrides the
+    accumulated body and is used when a single turn exceeds the target."""
+    global chunk_index, buf_parts, buf_chars, buf_start, buf_end
+    if force_text is None:
+        if not buf_parts:
+            return
+        body = "\n\n".join(buf_parts)
+    else:
+        body = force_text
+    if not body.strip():
+        # Reset and skip empty bodies (can happen with overlap-only carry).
+        buf_parts = []
+        buf_chars = 0
+        buf_start = None
+        buf_end = None
+        return
+    chunks.append({
+        "chunk_index": chunk_index,
+        "start_turn_index": buf_start,
+        "end_turn_index": buf_end,
+        "body": body,
+        "body_chars": len(body),
+    })
+    chunk_index += 1
+    buf_parts = []
+    buf_chars = 0
+    buf_start = None
+    buf_end = None
+
+
+for turn in turns:
+    role = turn.get("role", "")
+    content = turn.get("content", "")
+    if not content:
+        continue
+    rendered = f"{role}: {content}"
+    rendered_len = len(rendered)
+
+    # If this single turn exceeds the target, flush whatever's pending and
+    # emit the oversized turn as its own chunk. The next chunk's overlap
+    # carries the last `overlap` chars of this turn's body.
+    if rendered_len > target:
+        # Flush pending buffer first.
+        if buf_parts:
+            flush()
+        # Seed an oversized chunk on its own.
+        body_for_chunk = (pending_overlap + ("\n\n" if pending_overlap else "")) + rendered
+        # Set start/end markers for the standalone chunk.
+        buf_start = turn["turn_index"]
+        buf_end = turn["turn_index"]
+        flush(force_text=body_for_chunk)
+        pending_overlap = body_for_chunk[-overlap:] if overlap > 0 else ""
+        continue
+
+    candidate_len = buf_chars + rendered_len + (2 if buf_parts else 0)  # 2 for "\n\n"
+    if buf_parts and candidate_len > target:
+        # Flush the buffer; start a new chunk seeded with overlap from the
+        # body we just emitted.
+        last_body = ""
+        if chunks:
+            last_body = chunks[-1]["body"]
+        flush()
+        if overlap > 0 and last_body:
+            pending_overlap = last_body[-overlap:]
+        else:
+            pending_overlap = ""
+
+    if not buf_parts and pending_overlap:
+        buf_parts.append(pending_overlap)
+        buf_chars += len(pending_overlap)
+        pending_overlap = ""
+
+    buf_parts.append(rendered)
+    buf_chars += rendered_len + (2 if len(buf_parts) > 1 else 0)
+    if buf_start is None:
+        buf_start = turn["turn_index"]
+    buf_end = turn["turn_index"]
+
+# Final flush.
+if buf_parts:
+    flush()
+
+print(json.dumps(chunks))
+PY
+}

package/plugins/historian/scripts/lib/historian-config.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Config resolution for Historian.
+#
+# Reads three layers, latest wins:
+#   1. plugins/historian/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   historian_config_load <repo_root>    # populates _HISTORIAN_CONFIG (JSON)
+#   historian_config_get <jq-path>       # echoes string value (empty if unset)
+#   historian_config_enabled             # 0 if historian.enabled is true
+#
+# Settings overlay only touches the `historian.*` subtree of settings.json.
+
+_HISTORIAN_CONFIG="{}"
+
+historian_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ historian: (.historian // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		merged=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) || true
+	done
+
+	_HISTORIAN_CONFIG="$merged"
+}
+
+# Read a value from the loaded config. The explicit null check (instead of
+# `// empty`) preserves boolean `false` — `// empty` would treat it the same
+# as null and silently drop "explicitly disabled" settings.
+historian_config_get() {
+	local path="$1"
+	printf '%s' "$_HISTORIAN_CONFIG" \
+		| jq -r "${path} | if . == null then empty else . end" 2>/dev/null
+}
+
+historian_config_enabled() {
+	local v
+	v=$(historian_config_get '.historian.enabled')
+	[[ "$v" == "true" ]]
+}

package/plugins/historian/scripts/lib/historian-embedder.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Embedder client for Historian.
+#
+# Per ADR-001, the default backend is local ollama with the
+# `nomic-embed-text` model. The interface is intentionally a single
+# function that takes a string and returns a JSON array of floats, so
+# alternate backends (fastembed sidecar, remote API) can drop in later
+# without changing callers.
+#
+# Fail-soft: returns empty string on any failure (ollama not reachable,
+# JSON decode error, missing curl). Callers treat empty as "skip the
+# embedding and emit historian.embedder.unavailable".
+
+# Resolve config (the caller has typically run historian_config_load
+# before invoking us). We re-read the config knobs here so this lib can
+# be sourced and used outside the SessionEnd hook context.
+
+_historian_embedder_backend() {
+	local v
+	v=$(historian_config_get '.historian.embedder.backend' 2>/dev/null)
+	[[ -z "$v" ]] && v="none"
+	printf '%s' "$v"
+}
+
+_historian_embedder_ollama_host() {
+	local v
+	v=$(historian_config_get '.historian.embedder.ollama.host' 2>/dev/null)
+	[[ -z "$v" ]] && v="http://127.0.0.1:11434"
+	printf '%s' "$v"
+}
+
+_historian_embedder_ollama_model() {
+	local v
+	v=$(historian_config_get '.historian.embedder.ollama.model' 2>/dev/null)
+	[[ -z "$v" ]] && v="nomic-embed-text"
+	printf '%s' "$v"
+}
+
+_historian_embedder_ollama_timeout() {
+	local v
+	v=$(historian_config_get '.historian.embedder.ollama.request_timeout_seconds' 2>/dev/null)
+	[[ -z "$v" || "$v" == "null" ]] && v=8
+	printf '%s' "$v"
+}
+
+# Returns 0 if the currently-configured embedder is reachable and the
+# backend is something other than "none". A side-effect-free probe.
+historian_embedder_available() {
+	local backend
+	backend=$(_historian_embedder_backend)
+	case "$backend" in
+		none|"")
+			return 1
+			;;
+		ollama)
+			command -v curl >/dev/null 2>&1 || return 1
+			local host timeout
+			host=$(_historian_embedder_ollama_host)
+			timeout=$(_historian_embedder_ollama_timeout)
+			# HEAD `/api/tags` is the cheapest way to confirm the daemon
+			# is up without rendering a payload.
+			curl -fsS --max-time "$timeout" -o /dev/null "${host}/api/tags" 2>/dev/null
+			;;
+		*)
+			# fastembed / remote backends not implemented yet — treat as
+			# unavailable.
+			return 1
+			;;
+	esac
+}
+
+# Embed a single string. Prints a JSON array of floats on success
+# (e.g. `[0.123,0.456,...]`), or empty string on any error.
+# Usage: historian_embedder_embed <text>
+historian_embedder_embed() {
+	local text="${1:-}"
+	[[ -z "$text" ]] && return 0
+
+	local backend
+	backend=$(_historian_embedder_backend)
+	case "$backend" in
+		none|"")
+			return 0
+			;;
+		ollama)
+			_historian_embedder_embed_ollama "$text"
+			;;
+		*)
+			# Backend declared but not implemented — fail-soft.
+			return 0
+			;;
+	esac
+}
+
+# Internal: call ollama's /api/embeddings endpoint.
+_historian_embedder_embed_ollama() {
+	local text="$1"
+	command -v curl >/dev/null 2>&1 || return 0
+
+	local host model timeout payload response
+	host=$(_historian_embedder_ollama_host)
+	model=$(_historian_embedder_ollama_model)
+	timeout=$(_historian_embedder_ollama_timeout)
+
+	payload=$(jq -cn --arg model "$model" --arg prompt "$text" \
+		'{ model: $model, prompt: $prompt }') || return 0
+
+	response=$(curl -fsS --max-time "$timeout" \
+		-H 'Content-Type: application/json' \
+		-d "$payload" \
+		"${host}/api/embeddings" 2>/dev/null) || return 0
+	[[ -z "$response" ]] && return 0
+
+	# The ollama embeddings endpoint returns `{"embedding":[...]}`. Pull
+	# just the array and validate it parses + is non-empty.
+	local vector
+	vector=$(printf '%s' "$response" | jq -c '.embedding // empty' 2>/dev/null)
+	[[ -z "$vector" || "$vector" == "null" ]] && return 0
+
+	# Sanity: must be an array of numbers, length > 0.
+	printf '%s' "$vector" | jq -e '
+		type == "array" and length > 0 and all(.[]; type == "number")
+	' >/dev/null 2>&1 || return 0
+
+	printf '%s' "$vector"
+}

package/plugins/historian/scripts/lib/historian-emit.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Event emission helpers for Historian.
+#
+# Thin wrapper around onlooker-event.mjs `emit` mode for historian.* events.
+# Fail-soft: returns 0 on success or when the substrate is unavailable.
+
+_historian_resolve_event_js() {
+	local script_dir plugin_root ecosystem_root candidate
+	script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	plugin_root="$(cd "${script_dir}/../.." && pwd)"
+
+	ecosystem_root="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+	if [[ -z "$ecosystem_root" ]]; then
+		candidate="$(cd "${plugin_root}/../.." 2>/dev/null && pwd)"
+		if [[ -f "${candidate}/scripts/lib/onlooker-event.mjs" ]]; then
+			ecosystem_root="$candidate"
+		fi
+	fi
+
+	if [[ -n "$ecosystem_root" ]]; then
+		printf '%s/scripts/lib/onlooker-event.mjs' "$ecosystem_root"
+	fi
+}
+
+_HISTORIAN_EVENT_JS="${_HISTORIAN_EVENT_JS:-$(_historian_resolve_event_js)}"
+
+# Emit a historian.* event. Fail-soft: returns 0 on any error.
+# Usage: historian_emit <event_type> <session_id> <payload_json>
+historian_emit() {
+	local event_type="${1:-}"
+	local session_id="${2:-}"
+	local payload="${3:-{\}}"
+
+	[[ -z "$event_type" || -z "$session_id" ]] && return 0
+	[[ -z "$_HISTORIAN_EVENT_JS" || ! -f "$_HISTORIAN_EVENT_JS" ]] && return 0
+	command -v node >/dev/null 2>&1 || return 0
+	[[ -z "${ONLOOKER_EVENTS_LOG:-}" ]] && return 0
+
+	local params event_json
+	params=$(jq -cn \
+		--arg plugin "historian" \
+		--arg session_id "$session_id" \
+		--arg event_type "$event_type" \
+		--argjson payload "$payload" \
+		'{
+			plugin: $plugin,
+			session_id: $session_id,
+			event_type: $event_type,
+			payload: $payload
+		}') || return 0
+
+	event_json=$(
+		ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		ONLOOKER_PLUGIN_NAME="historian" \
+		printf '%s' "$params" | node "$_HISTORIAN_EVENT_JS" emit 2>/dev/null
+	) || return 0
+	[[ -z "$event_json" ]] && return 0
+
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")" 2>/dev/null
+	printf '%s\n' "$event_json" >> "$ONLOOKER_EVENTS_LOG" 2>/dev/null
+}