dsh-file-activity 0.5.7 → 0.5.9

package/lib/client.src.js

@@ -1,29 +1,30 @@
 /**
  * dsh-file-activity — client half (browser).
  *
- * Extends dsh-better-sidebar with a "文件活动 / File Activity" tab:
- *  - recent file access history (agent + sidebar operations),
- *  - per-file create/modify/read counts flattened by folder, with multi-level
- *    folders shown as dotted paths (a.b.c.d) and their files indented below,
- *  - clicking any file opens a FLOATING preview that reuses the sidebar's
- *    NATIVE viewer via `ctx.betterSidebar.matchFileViewer(path)` — its own
- *    `component` is mounted (built-in markdown / code / image / pdf / html
- *    renderers), so code gets syntax highlighting and markdown gets rendered
- *    with no hand-rolled preview; clicking outside / Esc / × closes it,
- *  - auto-opens once per session by default (toggleable in the sidebar
- *    settings, enabled by default).
+ * A native right-Sidebar tab ("文件活动 / File Activity") built on the HOST's
+ * own extension points (issue #187 batch 2 — no third-party sidebar service):
+ *  - the tab type registers into `ctx.sidebarRightTabs` (stage one) and its
+ *    body / chip title into the keyed `sidebar.right.pane.tab` and
+ *    `sidebar.right.pane.tab.title` seats (stage two);
+ *  - clicking a file opens a FLOATING preview implemented by this plugin inside
+ *    the `shell.overlay` list seat: recent access history (agent + plugin
+ *    routes), per-file create/modify/read counts flattened by folder, and the
+ *    preview window itself — clicking outside / Esc / × closes it;
+ *  - a document-preview descriptor registers with `ctx.documentPreviews`
+ *    (metadata only: the native document owner reads the bytes);
+ *  - auto-opens once per session by default, with its toggle in the Web
+ *    Settings → Plugins tab (`settings.plugins.tab`).
  *
  * Data source: the plugin host half (fs/observed for agent tools) + this
- * half's fetch interception for sidebar file operations (fs.read / fs.write /
- * /sidebar/file media opens), both persisted host-side; the tab polls
- * /file-activity/api/stats.
+ * half's fetch interception for the plugin's own file routes, both persisted
+ * host-side; the tab polls /file-activity/api/stats.
  *
- * Styling follows the dsh-better-sidebar design language: all colors ride the
- * DSH semantic tokens (--dsw-alias-*), typography rides the font roles
- * (--dsw-font-*), motion rides --ds-*. Flat surfaces (no box-shadow), hairline
- * borders, 28px circular icon controls with hover fills, and 8px-radius rows
- * with hover fills. The stylesheet is injected once per activation and torn
- * down with the fiber, so HMR/disable leaves no residue.
+ * Styling follows the DSH design language: all colors ride the DSH semantic
+ * tokens (--dsw-alias-*), typography rides the font roles (--dsw-font-*),
+ * motion rides --ds-*. Flat surfaces (no box-shadow), hairline borders, 28px
+ * circular icon controls with hover fills, and 8px-radius rows with hover
+ * fills. The stylesheet is injected once per activation and torn down with the
+ * fiber, so HMR/disable leaves no residue.
  *
  * BUILD NOTE: this file is the SOURCE TEMPLATE. scripts/build.mjs splices the
  * `lib/parts/*.part.js` pieces into the PART placeholder markers below (each
@@ -40,8 +41,11 @@ window.__ModuleLoader__.load({
     Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
     const { createElement, useEffect, useMemo, useState, useSyncExternalStore } = require('react')
 
-    const TAB_ID = 'file-activity:recent'
+    const TAB_ID = 'dsh-file-activity'
+    const TAB_KIND = 'file-activity'
+    const PREVIEW_ID = 'dsh-file-activity-preview'
     const AUTO_OPEN_KEY = 'dsh-file-activity:auto-opened:'
+    const AUTO_OPEN_PREF_KEY = 'dsh-file-activity:autoOpen'
     const POLL_MS = 6000
 
     // ── parts (injected by scripts/build.mjs; keep this exact order — the
@@ -53,11 +57,14 @@ window.__ModuleLoader__.load({
     __PART_API__
     __PART_INTERCEPTOR__
     __PART_AUTO_OPEN__
+    __PART_DOCUMENT_PREVIEWS__
     __PART_ICONS__
     __PART_STYLES__
     __PART_ROWS__
     __PART_VIEW__
+    __PART_PREVIEW_DATA__
     __PART_PREVIEW__
+    __PART_SETTINGS__
     __PART_APPLY__
 
     return module.exports

package/lib/cwd.js

@@ -4,11 +4,11 @@
  * 从 http.js 拆出（issue #45：http.js 的 JSON 工具已抽到 dsh-shared，
  * sessionCwdOf 为 file-activity 特有，保留本地）。
  */
-
-/** Session working directory, mirroring better-sidebar's resolution. */
+/** Session working directory, mirroring the host's own session resolution. */
 export function sessionCwdOf(ctx, sessionId) {
-  const session = ctx.sessions.get(sessionId)
-  const headerCwd = session?.header?.cwd
-  if (typeof headerCwd === 'string' && headerCwd !== '') return headerCwd
-  return process.cwd()
+    const session = ctx.sessions.get(sessionId);
+    const headerCwd = session?.header?.cwd;
+    if (typeof headerCwd === 'string' && headerCwd !== '')
+        return headerCwd;
+    return process.cwd();
 }

package/lib/index.js

@@ -1,116 +1,101 @@
 /**
  * dsh-file-activity — host half.
  *
- * Tracks file activity for dsh-better-sidebar:
+ * Tracks file activity for the DSH right sidebar:
  *  - agent tool file operations arrive as `fs/observed` events (read / write /
  *    edit / str_replace_editor / read_image ...), with the tool execution as
  *    the actor (name + parsed arguments + owning agent).
  *  - bash tool calls carry file-touching commands (rm/touch/mv/…): the
  *    `tools/pre-execute` observer parses them and records the intents.
- *  - sidebar operations (files opened / saved through the better-sidebar
+ *  - sidebar operations (files opened / saved through the host's own
  *    explorer & editor) are reported by our client half through the
  *    `/file-activity/api/record` route.
  *
  * State (recent history + per-file counts) is kept per session and persisted
- * to $DSH_HOME/file-activity.json (atomic tmp+rename, debounced).
+ * to $DSH_HOME/file-activity.json as **JSON Lines**: 每条记录追加一行
+ * （落盘字节 ≈ 事件本体字节），累计行数达自适应阈值时原子 compact（issue #197：
+ * 旧实现每次防抖全量重写，写放大 3,665×）。入口三维上限（会话 / 每会话路径 /
+ * 全局路径）超限按 LRU 淘汰并告警 —— 内存与状态文件均有界。
  */
-import { isTrustedApiRequest } from 'dsh-shared'
-import { createApiHandler } from './api-route.js'
-import { createMediaHandler } from './media-route.js'
-import { createFsObserver } from './observer.js'
-import { createStore } from './store.js'
-import { parseBashFileOps } from './bash-parse.js'
-import { sessionCwdOf } from './cwd.js'
-
-export const name = 'dsh-file-activity'
-
-export const inject = ['webServer', 'sessions', 'webRuntime']
-
+import { isTrustedApiRequest } from 'dsh-shared';
+import { createApiHandler } from './api-route.js';
+import { createMediaHandler } from './media-route.js';
+import { createFsObserver } from './observer.js';
+import { createStore } from './store.js';
+import { parseBashFileOps } from './bash-parse.js';
+import { sessionCwdOf } from './cwd.js';
+export const name = 'dsh-file-activity';
+export const inject = ['webServer', 'sessions', 'webRuntime'];
 /** 观察型监听：只读取 bash 命令隐含的文件操作并上报，不拦截（返回 next()）。 */
 function observeBashIntents(exec, ctx, store) {
-  const sessionId = bashSessionOf(exec)
-  const command = bashCommandOf(exec)
-  if (sessionId === '' || command === '') return
-  const baseDir = bashBaseDirOf(exec, ctx, sessionId)
-  for (const touched of parseBashFileOps(command, baseDir)) {
-    store.record(sessionId, touched.path, touched.op, Date.now())
-  }
+    const sessionId = bashSessionOf(exec);
+    const command = bashCommandOf(exec);
+    if (sessionId === '' || command === '')
+        return;
+    const baseDir = bashBaseDirOf(exec, ctx, sessionId);
+    for (const touched of parseBashFileOps(command, baseDir)) {
+        store.record(sessionId, touched.path, touched.op, Date.now());
+    }
 }
-
 /** 会话 id：仅 bash 工具、agent id 非空时返回。 */
 function bashSessionOf(exec) {
-  if (exec?.name !== 'bash') return ''
-  const id = exec.agent?.id
-  return typeof id === 'string' && id !== '' ? id : ''
+    if (exec?.name !== 'bash')
+        return '';
+    const id = exec.agent?.id;
+    return typeof id === 'string' && id !== '' ? id : '';
 }
-
 /** 命令文本：仅非空字符串时返回。 */
 function bashCommandOf(exec) {
-  const command = exec.arguments?.command
-  return typeof command === 'string' && command !== '' ? command : ''
+    const command = exec.arguments?.command;
+    return typeof command === 'string' && command !== '' ? command : '';
 }
-
 /** 相对路径基准：workdir 参数优先，否则会话 cwd。 */
 function bashBaseDirOf(exec, ctx, sessionId) {
-  const workdir = exec.arguments?.workdir
-  return typeof workdir === 'string' && workdir !== '' ? workdir : sessionCwdOf(ctx, sessionId)
+    const workdir = exec.arguments?.workdir;
+    return typeof workdir === 'string' && workdir !== '' ? workdir : sessionCwdOf(ctx, sessionId);
 }
-
 export function apply(ctx) {
-  const store = createStore(ctx)
-
-  // ── agent-side file operations ──────────────────────────────────────────
-  ctx.on('fs/observed', createFsObserver(store.record))
-  ctx.on('tools/pre-execute', (exec, next) => {
-    observeBashIntents(exec, ctx, store)
-    return next()
-  })
-
-  // ── routes ──────────────────────────────────────────────────────────────
-  const fence = (request) => isTrustedApiRequest(request, ctx.webRuntime.trustedHosts)
-
-  ctx.effect(
-    () =>
-      ctx.webServer.register({
+    const store = createStore(ctx);
+    // ── agent-side file operations ──────────────────────────────────────────
+    ctx.on('fs/observed', createFsObserver(store.record));
+    ctx.on('tools/pre-execute', (exec, next) => {
+        observeBashIntents(exec, ctx, store);
+        return next();
+    });
+    // ── routes ──────────────────────────────────────────────────────────────
+    const fence = (request) => isTrustedApiRequest(request, ctx.webRuntime.trustedHosts);
+    ctx.effect(() => ctx.webServer.register({
         kind: 'prefix',
         path: '/file-activity/api',
         handler: createApiHandler({ ctx, store, fence }),
-      }),
-    'dsh-file-activity: /file-activity/api routes',
-  )
-
-  // Media route for the floating preview (see media-route.js for the
-  // authorization model: recorded paths only, same trust fence).
-  ctx.effect(
-    () =>
-      ctx.webServer.register({
+    }), 'dsh-file-activity: /file-activity/api routes');
+    // Media route for the floating preview (see media-route.js for the
+    // authorization model: recorded paths only, same trust fence).
+    ctx.effect(() => ctx.webServer.register({
         kind: 'prefix',
         path: '/file-activity/file',
         handler: createMediaHandler({ ctx, store, fence }),
-      }),
-    'dsh-file-activity: /file-activity/file media route',
-  )
-
-  // 插件状态查询（#155 聚合层）
-  ctx.on('plugin:status-query', ({ plugin }) => {
-    if (plugin !== 'dsh-file-activity') return undefined
-    const sessions = store.state?.sessions ?? {}
-    const totalFiles = Object.values(sessions).reduce((n, s) => n + Object.keys(s.known ?? {}).length, 0)
-    const allRecent = Object.values(sessions).flatMap((s) => s.recent ?? [])
-    allRecent.sort((a, b) => (b.time ?? 0) - (a.time ?? 0))
-    const lastActions = allRecent.slice(0, 5).map((e) => ({ time: e.time, type: e.op ?? 'activity', detail: e.path }))
-    return {
-      ok: true,
-      value: {
-        plugin: 'dsh-file-activity',
-        config: { keys: [] },
-        running: true,
-        stats: { sessions: Object.keys(sessions).length, totalFiles },
-        lastActions,
-      },
-    }
-  })
-
-  // Tear down on unload: flush pending persistence.
-  ctx.effect(() => store.dispose, 'dsh-file-activity: persistence teardown')
+    }), 'dsh-file-activity: /file-activity/file media route');
+    // 插件状态查询（#155 聚合层）
+    ctx.on('plugin:status-query', ({ plugin }) => {
+        if (plugin !== 'dsh-file-activity')
+            return undefined;
+        const sessions = store.state?.sessions ?? {};
+        const totalFiles = Object.values(sessions).reduce((n, s) => n + Object.keys(s.known ?? {}).length, 0);
+        const allRecent = Object.values(sessions).flatMap((s) => s.recent ?? []);
+        allRecent.sort((a, b) => (b.time ?? 0) - (a.time ?? 0));
+        const lastActions = allRecent.slice(0, 5).map((e) => ({ time: e.time, type: e.op ?? 'activity', detail: e.path }));
+        return {
+            ok: true,
+            value: {
+                plugin: 'dsh-file-activity',
+                config: { keys: [] },
+                running: true,
+                stats: { sessions: Object.keys(sessions).length, totalFiles },
+                lastActions,
+            },
+        };
+    });
+    // Tear down on unload: flush pending persistence.
+    ctx.effect(() => store.dispose, 'dsh-file-activity: persistence teardown');
 }

package/lib/media-route.js

@@ -13,110 +13,136 @@
  * fence), the client falls back to this route and receives an fs.read-shaped
  * JSON payload ({ ok, value: { content } }) so the viewer mounts unchanged.
  */
-import { readFile, stat } from 'node:fs/promises'
-import { basename, isAbsolute, join } from 'node:path'
-import { writeJson } from 'dsh-shared'
-import { sessionCwdOf } from './cwd.js'
-import { isRecordedPath } from './state.js'
-
+import { readFile, stat } from 'node:fs/promises';
+import { basename, isAbsolute, join } from 'node:path';
+import { writeJson } from 'dsh-shared';
+import { sessionCwdOf } from './cwd.js';
+import { isRecordedPath } from './state.js';
 /** Cap for the plugin's own media route (bytes): images / PDFs only. */
-const MEDIA_LIMIT = 64 * 1024 * 1024
-
+const MEDIA_LIMIT = 64 * 1024 * 1024;
 /** Cap for `as=text` payloads (characters): text previews, not archives. */
-const TEXT_LIMIT = 2 * 1024 * 1024
-
+const TEXT_LIMIT = 2 * 1024 * 1024;
 /** Content types served by /file-activity/file (mirrors the sidebar's set). */
 const MEDIA_TYPES = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.svg': 'image/svg+xml',
-  '.bmp': 'image/bmp',
-  '.ico': 'image/x-icon',
-  '.avif': 'image/avif',
-  '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+    '.pdf': 'application/pdf',
+    // HTML documents (issue #266 C): rendered in a sandboxed iframe by the
+    // floating preview, so they must be served as documents, not as text.
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.xhtml': 'application/xhtml+xml',
+};
+/** HTML suffixes: always served through the sandboxing CSP below. */
+const HTML_TYPES = new Set(['.html', '.htm', '.xhtml']);
+/**
+ * Content-Security-Policy for a previewed HTML document (issue #266 C).
+ *
+ * `sandbox` with NO `allow-same-origin` forces an opaque origin: the document
+ * cannot read cookies, storage, or same-origin APIs, and it cannot script the
+ * embedding page. Scripts/forms stay enabled so interactive documents render.
+ * The header (not only the iframe's own `sandbox` attribute) is what keeps a
+ * DIRECT visit to this URL sandboxed too — the preview iframe is not the only
+ * way to reach it.
+ */
+const HTML_SANDBOX_CSP = 'sandbox allow-scripts allow-forms';
+/** 小写后缀（含点号；无后缀返回空串）。 */
+function suffixOf(path) {
+    const dot = path.lastIndexOf('.');
+    return dot === -1 ? '' : path.slice(dot).toLowerCase();
 }
-
 function mediaTypeForPath(path) {
-  const dot = path.lastIndexOf('.')
-  const ext = dot === -1 ? '' : path.slice(dot).toLowerCase()
-  return MEDIA_TYPES[ext] ?? 'application/octet-stream'
+    return MEDIA_TYPES[suffixOf(path)] ?? 'application/octet-stream';
 }
-
 /** Error carrying an HTTP status, for the media route's catch-all. */
 function mediaError(status, message) {
-  const error = new Error(message)
-  error.status = status
-  return error
+    const error = new Error(message);
+    error.status = status;
+    return error;
 }
-
-export function createMediaHandler({ ctx, store, fence }) {
-  return async (request, response) => {
-    if (!fence(request)) {
-      writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } })
-      return
-    }
-    if (request.method !== 'GET') {
-      writeJson(response, 405, { ok: false, error: { message: 'method not allowed' } })
-      return
-    }
-    try {
-      await serveRecordedFile(request, response, ctx, store)
-    } catch (error) {
-      const status = typeof error?.status === 'number' ? error.status : 400
-      writeJson(response, status, {
-        ok: false,
-        error: { message: error instanceof Error ? error.message : String(error) },
-      })
-    }
-  }
+export function createMediaHandler({ ctx, store, fence, }) {
+    return async (request, response) => {
+        if (!fence(request)) {
+            writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } });
+            return;
+        }
+        if (request.method !== 'GET') {
+            writeJson(response, 405, { ok: false, error: { message: 'method not allowed' } });
+            return;
+        }
+        try {
+            await serveRecordedFile(request, response, ctx, store);
+        }
+        catch (error) {
+            const status = typeof error?.status === 'number' ? error.status : 400;
+            writeJson(response, status, {
+                ok: false,
+                error: { message: error instanceof Error ? error.message : String(error) },
+            });
+        }
+    };
 }
-
 /**
  * Resolve a recorded path (authorized per session) and serve it: bytes
  * (images / PDFs, `download=1` supported) or, with `as=text`, an
  * fs.read-shaped JSON payload for the floating preview's text fallback.
  */
 async function serveRecordedFile(request, response, ctx, store) {
-  const url = new URL(request.url ?? '/', 'http://dsh.internal')
-  const sessionId = url.searchParams.get('sessionId')
-  const raw = url.searchParams.get('path')
-  assertMediaParams(sessionId, raw)
-  if (!isRecordedPath(store.state, sessionId, raw)) throw mediaError(403, "path is not in this session's file activity")
-  const abs = isAbsolute(raw) ? raw : join(sessionCwdOf(ctx, sessionId), raw)
-  if (url.searchParams.get('as') === 'text') {
-    await serveText(response, abs)
-    return
-  }
-  await serveMedia(response, abs, url)
+    const url = new URL(request.url ?? '/', 'http://dsh.internal');
+    const sessionId = url.searchParams.get('sessionId');
+    const raw = url.searchParams.get('path');
+    assertMediaParams(sessionId, raw);
+    if (!isRecordedPath(store.state, sessionId, raw))
+        throw mediaError(403, "path is not in this session's file activity");
+    const abs = isAbsolute(raw) ? raw : join(sessionCwdOf(ctx, sessionId), raw);
+    if (url.searchParams.get('as') === 'text') {
+        await serveText(response, abs);
+        return;
+    }
+    await serveMedia(response, abs, url);
 }
-
 /** Both query parameters are required for a media request. */
 function assertMediaParams(sessionId, raw) {
-  if (sessionId === null || raw === null || raw === '') throw mediaError(400, 'sessionId and path are required')
+    if (sessionId === null || raw === null || raw === '')
+        throw mediaError(400, 'sessionId and path are required');
 }
-
 /** stat + read + respond with the file's bytes (bounded by MEDIA_LIMIT). */
 async function serveMedia(response, abs, url) {
-  let info
-  try {
-    info = await stat(abs)
-  } catch {
-    throw mediaError(404, 'file not found')
-  }
-  if (!info.isFile()) throw mediaError(400, 'not a file')
-  if (info.size > MEDIA_LIMIT) throw mediaError(413, 'file too large')
-  const body = await readFile(abs)
-  const headers = { 'content-type': mediaTypeForPath(abs), 'cache-control': 'no-cache' }
-  if (url.searchParams.get('download') === '1') {
-    headers['content-disposition'] = `attachment; filename*=UTF-8''${encodeURIComponent(basename(abs))}`
-  }
-  response.writeHead(200, headers)
-  response.end(body)
+    let info;
+    try {
+        info = await stat(abs);
+    }
+    catch {
+        throw mediaError(404, 'file not found');
+    }
+    if (!info.isFile())
+        throw mediaError(400, 'not a file');
+    if (info.size > MEDIA_LIMIT)
+        throw mediaError(413, 'file too large');
+    const body = await readFile(abs);
+    const headers = {
+        'content-type': mediaTypeForPath(abs),
+        'cache-control': 'no-cache',
+    };
+    // Untrusted document: the sandboxing CSP travels with the bytes, so the
+    // protection does not depend on the caller embedding it in a sandboxed frame.
+    if (HTML_TYPES.has(suffixOf(abs))) {
+        headers['content-security-policy'] = HTML_SANDBOX_CSP;
+        headers['x-content-type-options'] = 'nosniff';
+    }
+    if (url.searchParams.get('download') === '1') {
+        headers['content-disposition'] = `attachment; filename*=UTF-8''${encodeURIComponent(basename(abs))}`;
+    }
+    response.writeHead(200, headers);
+    response.end(body);
 }
-
 /**
  * `as=text` mode: serve a recorded file's text content as an fs.read-shaped
  * JSON payload ({ ok, value: { content } }) so the floating preview's text
@@ -125,14 +151,17 @@ async function serveMedia(response, abs, url) {
  * recorded paths only.
  */
 async function serveText(response, abs) {
-  let info
-  try {
-    info = await stat(abs)
-  } catch {
-    throw mediaError(404, 'file not found')
-  }
-  if (!info.isFile()) throw mediaError(400, 'not a file')
-  if (info.size > TEXT_LIMIT) throw mediaError(413, 'file too large')
-  const content = await readFile(abs, 'utf8')
-  writeJson(response, 200, { ok: true, value: { content } })
+    let info;
+    try {
+        info = await stat(abs);
+    }
+    catch {
+        throw mediaError(404, 'file not found');
+    }
+    if (!info.isFile())
+        throw mediaError(400, 'not a file');
+    if (info.size > TEXT_LIMIT)
+        throw mediaError(413, 'file too large');
+    const content = await readFile(abs, 'utf8');
+    writeJson(response, 200, { ok: true, value: { content } });
 }

package/lib/observer.js

@@ -4,38 +4,44 @@
  * (backend displayPath preferred, falling back to the file_path argument)
  * and records it through the store's record().
  */
-import { mapOp } from './state.js'
-
+import { mapOp } from './state.js';
 export function createFsObserver(record) {
-  return (target, observation, actor) => {
-    // Only authoritative PRESENT observations mean a file was actually
-    // touched; absent observations (e.g. a failed read of a missing file)
-    // are noise.
-    if (!isPresentObservation(observation)) return
-    if (!isValidActor(actor)) return
-    const sessionId = actor.agent?.id
-    if (typeof sessionId !== 'string' || sessionId === '') return
-    // Prefer the backend-resolved absolute path; fall back to the raw argument.
-    const rawPath = resolveObservedPath(target, actor)
-    if (rawPath === '') return
-    record(sessionId, rawPath, mapOp(actor.name), Date.now())
-  }
+    return (target, observation, actor) => {
+        // Only authoritative PRESENT observations mean a file was actually
+        // touched; absent observations (e.g. a failed read of a missing file)
+        // are noise.
+        if (!isPresentObservation(observation))
+            return;
+        if (!isValidActor(actor))
+            return;
+        const sessionId = actor.agent?.id;
+        if (typeof sessionId !== 'string' || sessionId === '')
+            return;
+        // Prefer the backend-resolved absolute path; fall back to the raw argument.
+        const rawPath = resolveObservedPath(target, actor);
+        if (rawPath === '')
+            return;
+        record(sessionId, rawPath, mapOp(actor.name), Date.now());
+    };
 }
-
 /** A PRESENT observation is the only authoritative "file was touched" signal. */
 function isPresentObservation(observation) {
-  return observation !== undefined && observation !== null && observation.kind === 'present'
+    return observation !== undefined && observation !== null && observation.kind === 'present';
 }
-
 /** The actor must exist and carry a non-empty string tool name. */
 function isValidActor(actor) {
-  return actor !== undefined && actor !== null && typeof actor.name === 'string' && actor.name !== ''
+    if (actor === undefined || actor === null)
+        return false;
+    const name = actor.name;
+    return typeof name === 'string' && name !== '';
 }
-
 /** Resolve the touched path: backend displayPath preferred, else file_path. */
 function resolveObservedPath(target, actor) {
-  if (typeof target?.displayPath === 'string' && target.displayPath !== '') return target.displayPath
-  const args = actor.arguments
-  if (args !== null && typeof args === 'object' && typeof args.file_path === 'string') return args.file_path
-  return ''
+    const displayPath = target?.displayPath;
+    if (typeof displayPath === 'string' && displayPath !== '')
+        return displayPath;
+    const args = actor.arguments;
+    if (args !== null && typeof args === 'object' && typeof args.file_path === 'string')
+        return args.file_path;
+    return '';
 }