@onlooker-community/ecosystem 0.3.3 → 0.4.0

package/.github/workflows/publish-npm.yml

@@ -112,7 +112,6 @@ jobs:
           cache: npm
 
       - run: npm ci
-      - run: npm run build
 
       - name: Publish
         run: |

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.3"
+  ".": "0.4.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.4.0](https://github.com/onlooker-community/ecosystem/compare/v0.3.3...v0.4.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** add SessionStart and SessionEnd session trackers ([#10](https://github.com/onlooker-community/ecosystem/issues/10)) ([a48d680](https://github.com/onlooker-community/ecosystem/commit/a48d680dd24c98e79ef1c0401b07483ecebf9e8b))
+
 ## [0.3.3](https://github.com/onlooker-community/ecosystem/compare/v0.3.2...v0.3.3) (2026-05-22)
 
 

package/hooks/hooks.json

@@ -61,6 +61,28 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-start-tracker.sh"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-end-tracker.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",

package/scripts/hooks/session-end-tracker.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Onlooker Session End Tracker
+# Invoked by SessionEnd (matcher: *) when a session ends.
+#
+# Emits session.end with duration and turn count, then cleans up hook bus dirs.
+# Default SessionEnd budget is 1.5s — keep this hook fast.
+#
+# Usage:
+#   echo "$INPUT" | session-end-tracker.sh
+
+set -uo pipefail # No -e: never block session termination
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+
+hook_register "session-end-tracker" "Session End Tracker" "Records session.end and cleans up session resources"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "SessionEnd"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+
+PAYLOAD=$(session_tracker_build_end_payload "$SESSION_ID" "$INPUT")
+if [[ -n "$PAYLOAD" ]]; then
+	session_tracker_emit "$SESSION_ID" "session.end" "$PAYLOAD" \
+		|| hook_failure "Failed to emit session.end"
+fi
+
+hook_bus_cleanup
+
+hook_success
+exit 0

package/scripts/hooks/session-start-tracker.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Onlooker Session Start Tracker
+# Invoked by SessionStart (matcher: *) when a session starts or resumes.
+#
+# Initializes per-session tracker state and emits session.start for
+# startup, resume, and clear sources (compact is metadata-only).
+#
+# Usage:
+#   echo "$INPUT" | session-start-tracker.sh
+
+set -uo pipefail # No -e: never block session startup
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+
+hook_register "session-start-tracker" "Session Start Tracker" "Records session.start and initializes session tracker"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "SessionStart"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"')
+
+session_tracker_record_start "$SESSION_ID" "$INPUT" || hook_failure "Failed to record session start metadata"
+
+# Compaction reuses the session; do not emit another session.start.
+if [[ "$SOURCE" != "compact" ]]; then
+	PAYLOAD=$(session_tracker_build_start_payload "$INPUT")
+	if [[ -n "$PAYLOAD" ]]; then
+		session_tracker_emit "$SESSION_ID" "session.start" "$PAYLOAD" \
+			|| hook_failure "Failed to emit session.start"
+	fi
+fi
+
+hook_success
+exit 0

package/scripts/lib/session-tracker.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Session lifecycle helpers — session.start / session.end canonical events.
+#
+# Source after validate-path.sh, onlooker-schema.sh, and tool-history.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/session-tracker.sh"
+
+# Milliseconds since epoch (macOS-compatible).
+session_tracker_now_ms() {
+	if [[ "$(uname)" == "Darwin" ]]; then
+		python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null || date +%s000
+	else
+		date +%s%3N 2>/dev/null || date +%s000
+	fi
+}
+
+# Optional git_branch and git_commit for a working directory (empty when not a repo).
+session_tracker_git_context() {
+	local cwd="${1:-}"
+	local branch="" commit=""
+	[[ -z "$cwd" ]] && return 0
+
+	if git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		branch=$(git -C "$cwd" branch --show-current 2>/dev/null) || branch=""
+		commit=$(git -C "$cwd" rev-parse --short HEAD 2>/dev/null) || commit=""
+	fi
+
+	printf '%s\n%s' "$branch" "$commit"
+}
+
+# Map Claude Code SessionEnd reason to schema end_reason.
+session_tracker_map_end_reason() {
+	local reason="${1:-other}"
+	case "$reason" in
+	clear | logout | prompt_input_exit) echo "user_exit" ;;
+	timeout) echo "timeout" ;;
+	error) echo "error" ;;
+	task_complete) echo "task_complete" ;;
+	*) echo "unknown" ;;
+	esac
+}
+
+# Merge session start metadata into the per-session tracker file.
+# Usage: session_tracker_record_start "$SESSION_ID" "$INPUT_JSON"
+session_tracker_record_start() {
+	local session_id="${1:-}"
+	local input_json="${2:-}"
+	[[ -z "$session_id" || "$session_id" == "null" || -z "$input_json" ]] && return 0
+
+	turn_state_ensure_session "$session_id" || return 1
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local now_ms source model cwd transcript_path agent_type
+	now_ms=$(session_tracker_now_ms)
+	source=$(echo "$input_json" | jq -r '.source // ""' 2>/dev/null) || source=""
+	model=$(echo "$input_json" | jq -r '.model // ""' 2>/dev/null) || model=""
+	cwd=$(echo "$input_json" | jq -r '.cwd // ""' 2>/dev/null) || cwd=""
+	transcript_path=$(echo "$input_json" | jq -r '.transcript_path // ""' 2>/dev/null) || transcript_path=""
+	agent_type=$(echo "$input_json" | jq -r '.agent_type // ""' 2>/dev/null) || agent_type=""
+
+	local temp_file
+	temp_file=$(mktemp)
+	if ! jq \
+		--argjson start_ms "$now_ms" \
+		--arg source "$source" \
+		--arg model "$model" \
+		--arg cwd "$cwd" \
+		--arg transcript "$transcript_path" \
+		--arg agent_type "$agent_type" \
+		'.start_time_ms = $start_ms
+		| .start_source = (if $source != "" then $source else .start_source end)
+		| .model = (if $model != "" then $model else .model end)
+		| .cwd = (if $cwd != "" then $cwd else .cwd end)
+		| .transcript_path = (if $transcript != "" then $transcript else .transcript_path end)
+		| .agent_type = (if $agent_type != "" then $agent_type else .agent_type end)' \
+		"$tracker_file" >"$temp_file" 2>/dev/null; then
+		rm -f "$temp_file"
+		return 1
+	fi
+	mv "$temp_file" "$tracker_file"
+}
+
+# Build session.start payload JSON from hook input and tracker state.
+# Usage: payload=$(session_tracker_build_start_payload "$INPUT_JSON")
+session_tracker_build_start_payload() {
+	local input_json="${1:-}"
+	local cwd
+	cwd=$(echo "$input_json" | jq -r '.cwd // ""' 2>/dev/null) || cwd=""
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local git_lines branch commit
+	git_lines=$(session_tracker_git_context "$cwd")
+	branch=$(echo "$git_lines" | sed -n '1p')
+	commit=$(echo "$git_lines" | sed -n '2p')
+
+	jq -n \
+		--arg wd "$cwd" \
+		--arg branch "$branch" \
+		--arg commit "$commit" \
+		'{
+			working_directory: $wd
+		}
+		+ (if $branch != "" then {git_branch: $branch} else {} end)
+		+ (if $commit != "" then {git_commit: $commit} else {} end)'
+}
+
+# Build session.end payload JSON from hook input and tracker file.
+# Usage: payload=$(session_tracker_build_end_payload "$SESSION_ID" "$INPUT_JSON")
+session_tracker_build_end_payload() {
+	local session_id="${1:-}"
+	local input_json="${2:-}"
+	[[ -z "$session_id" || "$session_id" == "null" ]] && return 1
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local now_ms start_ms turn_count reason end_reason duration_ms
+	now_ms=$(session_tracker_now_ms)
+	reason=$(echo "$input_json" | jq -r '.reason // "other"' 2>/dev/null) || reason="other"
+	end_reason=$(session_tracker_map_end_reason "$reason")
+
+	if [[ -f "$tracker_file" ]]; then
+		start_ms=$(jq -r '.start_time_ms // 0' "$tracker_file" 2>/dev/null) || start_ms=0
+		turn_count=$(jq -r '.turn_number // 1' "$tracker_file" 2>/dev/null) || turn_count=1
+	else
+		start_ms=0
+		turn_count=1
+	fi
+
+	if [[ "$start_ms" =~ ^[0-9]+$ ]] && (( start_ms > 0 )); then
+		duration_ms=$((now_ms - start_ms))
+	else
+		duration_ms=0
+	fi
+	(( duration_ms < 0 )) && duration_ms=0
+
+	jq -n \
+		--argjson duration_ms "$duration_ms" \
+		--argjson turn_count "$turn_count" \
+		--arg end_reason "$end_reason" \
+		'{
+			duration_ms: $duration_ms,
+			turn_count: $turn_count,
+			end_reason: $end_reason
+		}'
+}
+
+# Emit a validated canonical session event and append to logs.
+# Usage: session_tracker_emit "$SESSION_ID" "session.start" "$payload_json"
+session_tracker_emit() {
+	local session_id="${1:-}"
+	local event_type="${2:-}"
+	local payload_json="${3:-}"
+	[[ -z "$session_id" || -z "$event_type" || -z "$payload_json" ]] && return 0
+
+	local params event
+	params=$(jq -n \
+		--arg plugin "${ONLOOKER_PLUGIN_NAME:-onlooker}" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload_json" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}')
+
+	event=$(printf '%s' "$params" | ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$ONLOOKER_PLUGIN_NAME" \
+		node "${_ONLOOKER_EVENT_JS:-${CLAUDE_PLUGIN_ROOT:-}/scripts/lib/onlooker-event.mjs}" emit 2>/dev/null) || return 1
+
+	tool_history_append "$session_id" "$event" || return 1
+	onlooker_append_event "$event" || return 1
+}

package/test/bats/config.bats

@@ -84,6 +84,34 @@ setup_file() {
   [[ "$hook_cmd" == *tool-history-tracker.sh ]]
 }
 
+@test "hooks.json SessionStart references session-start-tracker" {
+  run jq -e '.hooks.SessionStart[0].matcher == "*"' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.SessionStart[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *session-start-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
+@test "hooks.json SessionEnd references session-end-tracker" {
+  run jq -e '.hooks.SessionEnd[0].matcher == "*"' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.SessionEnd[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *session-end-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
 @test "plugin.json is valid JSON" {
   run jq -e '.name and .version' "${REPO_ROOT}/.claude-plugin/plugin.json"
   [ "$status" -eq 0 ]

package/test/bats/session-tracker.bats

@@ -0,0 +1,75 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+  # shellcheck source=../../scripts/lib/session-tracker.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  source "${REPO_ROOT}/scripts/lib/session-tracker.sh"
+}
+
+@test "session-start-tracker emits session.start for startup source" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-start-startup.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/session-start-001.jsonl"
+  rm -f "$history_file"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/session-start-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+
+  [ -f "$history_file" ]
+  jq -e '.event_type == "session.start"
+    and .session_id == "session-start-001"
+    and .payload.working_directory == "/project/repo"' \
+    "$history_file" >/dev/null
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/session-start-001"
+  jq -e '.start_source == "startup" and (.start_time_ms | type) == "number"' "$tracker" >/dev/null
+}
+
+@test "session-start-tracker does not emit session.start for compact source" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-start-compact.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/session-start-002.jsonl"
+  rm -f "$history_file"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/session-start-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+  [ ! -f "$history_file" ]
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/session-start-002"
+  jq -e '.start_source == "compact"' "$tracker" >/dev/null
+}
+
+@test "session-end-tracker emits session.end with duration and turn count" {
+  local start_fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-start-startup.json"
+  local end_fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-end-other.json"
+  local session_id="session-end-001"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${session_id}.jsonl"
+
+  rm -f "$history_file" "$tracker"
+
+  # Seed tracker as if session had been running
+  turn_state_ensure_session "$session_id"
+  local past_ms
+  past_ms=$(python3 -c 'import time; print(int((time.time() - 2) * 1000))' 2>/dev/null || echo 0)
+  jq --argjson start_ms "$past_ms" '.start_time_ms = $start_ms | .turn_number = 3' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+
+  run bash -c "cat '${end_fixture}' | '${REPO_ROOT}/scripts/hooks/session-end-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+
+  jq -e '.event_type == "session.end"
+    and .session_id == "session-end-001"
+    and .payload.turn_count == 3
+    and .payload.end_reason == "unknown"
+    and (.payload.duration_ms | type) == "number"
+    and .payload.duration_ms >= 0' \
+    "$history_file" >/dev/null
+}
+
+@test "session_tracker_map_end_reason maps logout to user_exit" {
+  [ "$(session_tracker_map_end_reason logout)" = "user_exit" ]
+}

package/test/fixtures/hook-inputs/session-end-other.json

@@ -0,0 +1,7 @@
+{
+  "session_id": "session-end-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "hook_event_name": "SessionEnd",
+  "reason": "other"
+}

package/test/fixtures/hook-inputs/session-start-compact.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "session-start-002",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "hook_event_name": "SessionStart",
+  "source": "compact",
+  "model": "claude-sonnet-4-6"
+}

package/test/fixtures/hook-inputs/session-start-startup.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "session-start-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "hook_event_name": "SessionStart",
+  "source": "startup",
+  "model": "claude-sonnet-4-6"
+}