@onlooker-community/ecosystem 0.9.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "ecosystem",
       "source": "./",
       "description": "Fill this out",
-      "version": "0.9.0",
+      "version": "0.10.0",
       "author": {
         "name": "Onlooker Community"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "TODO fill this out",
   "author": {
     "name": "Onlooker Community",

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.9.0"
+  ".": "0.10.0"
 }

package/CHANGELOG.md

@@ -7,6 +7,13 @@
 
 # Changelog
 
+## [0.10.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.9.0...ecosystem-v0.10.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** enrich tool.file.read with read chunking observability ([#25](https://github.com/onlooker-community/ecosystem/issues/25)) ([8eb23c8](https://github.com/onlooker-community/ecosystem/commit/8eb23c8f4f03dfbeb701a30de1fa50c1c8ee48ac))
+
 ## [0.9.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.8.0...ecosystem-v0.9.0) (2026-05-22)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -19,7 +19,7 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^1.4.0"
+    "@onlooker-community/schema": "^1.4.1"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",

package/scripts/lib/onlooker-event.mjs

@@ -4,7 +4,7 @@
  * Uses @onlooker-community/schema for envelope shape and validation.
  */
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   createEvent,
@@ -81,6 +81,85 @@ function extractPath(toolInput, toolResponse) {
   return toolInput?.file_path ?? toolInput?.path ?? toolResponse?.filePath ?? toolResponse?.path ?? undefined;
 }
 
+/** Bytes on disk above which a full read is flagged as large_file_full_read. */
+export const LARGE_FILE_BYTES_ON_DISK = 100_000;
+
+const MAX_FILE_LINES_STAT_BYTES = 512 * 1024;
+
+function parseNonNegativeInt(value) {
+  if (value == null || value === '') return undefined;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+function parsePositiveInt(value, min = 1) {
+  if (value == null || value === '') return undefined;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) && n >= min ? n : undefined;
+}
+
+/**
+ * Derive read_mode and line range from Read tool_input (supports common field aliases).
+ */
+export function extractReadRange(toolInput) {
+  const input = toolInput ?? {};
+  const offset = parseNonNegativeInt(
+    input.offset ?? input.start_line ?? input.start_line_one_indexed ?? input.line_offset,
+  );
+  const limit = parsePositiveInt(input.limit ?? input.line_limit ?? input.num_lines ?? input.line_count);
+  const read_mode = offset != null || limit != null ? 'partial' : 'full';
+  return stripUndefined({ read_mode, offset, limit });
+}
+
+/**
+ * Stat file on disk for chunking analytics (line count omitted for very large files).
+ */
+export function measureFileOnDisk(filePath) {
+  try {
+    if (!filePath || !existsSync(filePath)) return {};
+    const st = statSync(filePath);
+    if (!st.isFile()) return {};
+    const file_bytes_on_disk = st.size;
+    let file_lines_on_disk;
+    if (st.size <= MAX_FILE_LINES_STAT_BYTES) {
+      const text = readFileSync(filePath, 'utf8');
+      file_lines_on_disk = text.split('\n').length;
+    }
+    return stripUndefined({ file_bytes_on_disk, file_lines_on_disk });
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Build tool.file.read payload from Read tool hook fields.
+ */
+export function buildToolFileReadPayload(toolInput, toolResponse, options = {}) {
+  const path = extractPath(toolInput, toolResponse);
+  if (!path) return null;
+
+  const payload = { path, ...extractReadRange(toolInput) };
+  const content = toolResponse?.content;
+  if (typeof content === 'string') {
+    payload.lines_read = content.split('\n').length;
+    payload.file_size_bytes = content.length;
+  }
+
+  if (options.measureOnDisk !== false) {
+    Object.assign(payload, measureFileOnDisk(path));
+  }
+
+  if (
+    payload.read_mode === 'full' &&
+    payload.file_bytes_on_disk != null &&
+    payload.file_bytes_on_disk >= LARGE_FILE_BYTES_ON_DISK
+  ) {
+    payload.large_file_full_read = true;
+  }
+
+  return stripUndefined(payload);
+}
+
 function stripUndefined(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null && v !== ''));
 }
@@ -279,16 +358,9 @@ export function mapHookInputToCanonical(hookInput, options) {
 
   switch (toolName) {
     case 'Read': {
-      const path = extractPath(toolInput, toolResponse);
-      if (!path) return null;
+      payload = buildToolFileReadPayload(toolInput, toolResponse);
+      if (!payload) return null;
       eventType = TOOL_FILE_READ;
-      payload = { path };
-      const content = toolResponse?.content;
-      if (typeof content === 'string') {
-        const lines = content.split('\n').length;
-        payload.lines_read = lines;
-        payload.file_size_bytes = content.length;
-      }
       break;
     }
     case 'Write': {

package/test/bats/read-chunk-tracking.bats

@@ -0,0 +1,73 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  # shellcheck source=../../scripts/lib/onlooker-schema.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  # shellcheck source=../../scripts/lib/tool-history.sh
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+
+  LARGE_FILE="${BATS_TEST_TMPDIR}/large-source.ts"
+  # > LARGE_FILE_BYTES_ON_DISK (100_000) for large_file_full_read
+  printf '%*s\n' 120000 "" >"$LARGE_FILE"
+}
+
+@test "tool_history maps full Read to read_mode full" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/post-tool-use-read.json"
+  local record
+  record=$(tool_history_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.payload.read_mode == "full"
+     and .payload.path == "/project/src/main.ts"
+     and (.payload.large_file_full_read | not)' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "tool_history maps chunked Read to read_mode partial with offset and limit" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/post-tool-use-read-chunked.json"
+  local record
+  record=$(tool_history_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.payload.read_mode == "partial"
+     and .payload.offset == 400
+     and .payload.limit == 80
+     and .payload.lines_read == 3' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "tool_history flags large_file_full_read for full read of large on-disk file" {
+  local input
+  input=$(jq -n \
+    --arg path "$LARGE_FILE" \
+    --arg content "peek\n" \
+    '{
+      session_id: "history-session-002",
+      hook_event_name: "PostToolUse",
+      tool_name: "Read",
+      tool_input: {file_path: $path},
+      tool_response: {content: $content}
+    }')
+  local record
+  record=$(tool_history_build_record "$input")
+  echo "$record" | jq -e \
+    '.payload.read_mode == "full"
+     and .payload.large_file_full_read == true
+     and .payload.file_bytes_on_disk > 100000' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "tool-history-tracker appends chunked read to session JSONL" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/post-tool-use-read-chunked.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/history-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  cat "$fixture" | "${REPO_ROOT}/scripts/hooks/tool-history-tracker.sh" >/dev/null 2>&1
+
+  tail -n 1 "$history_file" | jq -e '.payload.read_mode == "partial"' >/dev/null
+}

package/test/bats/tool-history-tracker.bats

@@ -19,6 +19,7 @@ setup() {
     '.schema_version == "1.0"
      and .event_type == "tool.file.read"
      and .payload.path == "/project/src/main.ts"
+     and .payload.read_mode == "full"
      and .session_id == "history-session-001"' \
     >/dev/null
   echo "$record" | onlooker_validate_event

package/test/bats/validate-path.bats

@@ -96,7 +96,7 @@ setup() {
   export _HOOK_SESSION_ID="emit-session"
   export ONLOOKER_HOOK_TYPE="PreToolUse"
   export ONLOOKER_TOOL_NAME="Read"
-  local payload='{"path":"/tmp/example.txt"}'
+  local payload='{"path":"/tmp/example.txt","read_mode":"full"}'
   safe_emit "tool.file.read" "$payload"
   [ "$?" -eq 0 ]
   [ -f "$ONLOOKER_EVENTS_LOG" ]

package/test/fixtures/hook-inputs/post-tool-use-read-chunked.json

@@ -0,0 +1,15 @@
+{
+  "session_id": "history-session-001",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Read",
+  "tool_use_id": "toolu_read_002",
+  "duration_ms": 18,
+  "tool_input": {
+    "file_path": "/project/src/large-module.ts",
+    "offset": 400,
+    "limit": 80
+  },
+  "tool_response": {
+    "content": "// chunk line 1\n// chunk line 2\n"
+  }
+}

package/test/node/schema-events.test.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
@@ -7,6 +7,9 @@ import { fileURLToPath } from 'node:url';
 import { validate } from '@onlooker-community/schema';
 import {
   buildCanonicalEvent,
+  buildToolFileReadPayload,
+  extractReadRange,
+  LARGE_FILE_BYTES_ON_DISK,
   mapHookInputToCanonical,
   mapSkillHookInput,
   mapTaskHookInput,
@@ -32,6 +35,43 @@ test('mapHookInputToCanonical maps PostToolUse Read to tool.file.read', () => {
   assert.equal(mapped.event.event_type, 'tool.file.read');
   assert.equal(mapped.event.schema_version, '1.0');
   assert.equal(mapped.event.payload.path, '/project/src/main.ts');
+  assert.equal(mapped.event.payload.read_mode, 'full');
+  assert.equal(validate(mapped.event).valid, true);
+});
+
+test('extractReadRange detects partial reads from offset and limit', () => {
+  const range = extractReadRange({ offset: 10, limit: 50 });
+  assert.equal(range.read_mode, 'partial');
+  assert.equal(range.offset, 10);
+  assert.equal(range.limit, 50);
+});
+
+test('buildToolFileReadPayload flags large_file_full_read', () => {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'onlooker-read-chunk-'));
+  const filePath = join(tmpDir, 'big.txt');
+  const bytes = LARGE_FILE_BYTES_ON_DISK + 1;
+  writeFileSync(filePath, 'x'.repeat(bytes), 'utf8');
+
+  const payload = buildToolFileReadPayload({ file_path: filePath }, { content: 'x\n' });
+  assert.equal(payload.read_mode, 'full');
+  assert.equal(payload.large_file_full_read, true);
+  assert.equal(payload.file_bytes_on_disk, bytes);
+
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('mapHookInputToCanonical maps chunked Read to partial read_mode', () => {
+  const hookInput = loadFixture('post-tool-use-read-chunked.json');
+  const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');
+  const mapped = mapHookInputToCanonical(hookInput, {
+    onlookerDir: tmpDir,
+    plugin: 'onlooker',
+  });
+
+  assert.equal(mapped.valid, true);
+  assert.equal(mapped.event.payload.read_mode, 'partial');
+  assert.equal(mapped.event.payload.offset, 400);
+  assert.equal(mapped.event.payload.limit, 80);
   assert.equal(validate(mapped.event).valid, true);
 });