npm - noctrace - Versions diffs - 0.2.0 → 0.3.1 - Mend

noctrace 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +18 -3
package/dist/client/assets/{index-DKj34--U.css → index-B8NjnKEc.css} +1 -1
package/dist/client/assets/{index-qeBZVwft.js → index-Cfpt-dCZ.js} +2 -2
package/dist/client/index.html +2 -2
package/dist/server/server/routes/api.js +47 -3
package/dist/server/server/watcher.js +17 -8
package/dist/server/server/ws.js +47 -4
package/dist/server/shared/drift.js +94 -0
package/dist/server/shared/parser.js +8 -3
package/package.json +1 -1

package/dist/client/index.html CHANGED Viewed

@@ -7,8 +7,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-qeBZVwft.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DKj34--U.css">
+    <script type="module" crossorigin src="/assets/index-Cfpt-dCZ.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B8NjnKEc.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/server/routes/api.js CHANGED Viewed

@@ -7,6 +7,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { parseJsonlContent, parseCompactionBoundaries, extractSessionId, extractAgentIds, parseSubAgentContent, } from '../../shared/parser';
 import { computeContextHealth } from '../../shared/health';
+import { parseAssistantTurns, computeDrift } from '../../shared/drift';
 /**
  * Read ~/.claude/sessions/*.json and return a Set of sessionIds
  * whose PID is still a running claude process.
@@ -46,6 +47,14 @@ async function getRunningSessionIds(claudeHome) {
     }
     return running;
 }
+/** Validate that a resolved path is within the allowed base directory. */
+function assertWithinBase(resolved, base) {
+    const normalizedResolved = path.resolve(resolved);
+    const normalizedBase = path.resolve(base);
+    if (!normalizedResolved.startsWith(normalizedBase + path.sep) && normalizedResolved !== normalizedBase) {
+        throw new Error('Path traversal detected');
+    }
+}
 /** Build the Express router, scoped to a given Claude home directory. */
 export function buildApiRouter(claudeHome) {
     const router = Router();
@@ -144,6 +153,13 @@ export function buildApiRouter(claudeHome) {
     router.get('/sessions/:slug', async (req, res) => {
         const { slug } = req.params;
         const projectDir = path.join(projectsDir, slug);
+        try {
+            assertWithinBase(projectDir, projectsDir);
+        }
+        catch {
+            res.status(400).json({ error: 'Invalid path' });
+            return;
+        }
         try {
             let files;
             try {
@@ -200,7 +216,7 @@ export function buildApiRouter(claudeHome) {
                             isRemoteControlled = true;
                         }
                     }
-                    rowCount = parseJsonlContent(content).length;
+                    rowCount = lines.filter((l) => l.trim()).length;
                     // Active if: live process in registry OR file modified within last 2 minutes
                     // Registry covers CLI sessions; mtime covers Desktop app sessions
                     isActive = runningSessions.has(id) || (Date.now() - stat.mtime.getTime() < 120_000);
@@ -208,6 +224,16 @@ export function buildApiRouter(claudeHome) {
                 catch {
                     // Unreadable file — still include with null startTime
                 }
+                let driftFactor = null;
+                try {
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const sessionTurns = parseAssistantTurns(content);
+                    const sessionDrift = computeDrift(sessionTurns);
+                    driftFactor = sessionTurns.length >= 5 ? sessionDrift.driftFactor : null;
+                }
+                catch {
+                    // Drift computation is best-effort — don't fail the session listing
+                }
                 sessions.push({
                     id,
                     projectSlug: slug,
@@ -218,6 +244,7 @@ export function buildApiRouter(claudeHome) {
                     isActive,
                     permissionMode,
                     isRemoteControlled,
+                    driftFactor,
                 });
             }
             // Sort by lastModified descending (most recent first)
@@ -239,6 +266,13 @@ export function buildApiRouter(claudeHome) {
     router.get('/session/:slug/:id', async (req, res) => {
         const { slug, id } = req.params;
         const filePath = path.join(projectsDir, slug, `${id}.jsonl`);
+        try {
+            assertWithinBase(filePath, projectsDir);
+        }
+        catch {
+            res.status(400).json({ error: 'Invalid path' });
+            return;
+        }
         try {
             let content;
             try {
@@ -252,6 +286,8 @@ export function buildApiRouter(claudeHome) {
             const boundaries = parseCompactionBoundaries(content);
             const health = computeContextHealth(rows, boundaries.length);
             const sessionId = extractSessionId(content) ?? id;
+            const turns = parseAssistantTurns(content);
+            const drift = computeDrift(turns);
             // Load sub-agent JSONL files and attach as children to matching agent rows
             const subagentsDir = path.join(projectsDir, slug, id, 'subagents');
             let subagentsDirExists = false;
@@ -266,6 +302,9 @@ export function buildApiRouter(claudeHome) {
                 // Build a map of tool_use_id → agentId from the parent session content
                 const agentIdMap = extractAgentIds(content);
                 for (const [toolUseId, agentId] of agentIdMap) {
+                    // Validate agentId to prevent path traversal via crafted JSONL content
+                    if (!/^[a-zA-Z0-9_-]+$/.test(agentId))
+                        continue;
                     const subAgentFile = path.join(subagentsDir, `agent-${agentId}.jsonl`);
                     let subAgentContent;
                     try {
@@ -291,13 +330,18 @@ export function buildApiRouter(claudeHome) {
             for (const row of rows) {
                 if (row.type !== 'agent' || row.children.length === 0)
                     continue;
-                const childMax = Math.max(...row.children.map((c) => c.endTime ?? c.startTime));
+                let childMax = -Infinity;
+                for (const c of row.children) {
+                    const end = c.endTime ?? c.startTime;
+                    if (end > childMax)
+                        childMax = end;
+                }
                 if (childMax > (row.endTime ?? 0)) {
                     row.endTime = childMax;
                     row.duration = childMax - row.startTime;
                 }
             }
-            res.json({ rows, compactionBoundaries: boundaries, health, sessionId });
+            res.json({ rows, compactionBoundaries: boundaries, health, sessionId, drift });
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/server/server/watcher.js CHANGED Viewed

@@ -6,6 +6,7 @@ import chokidar from 'chokidar';
 import fs from 'node:fs';
 import { parseJsonlContent, parseCompactionBoundaries } from '../shared/parser';
 import { computeContextHealth } from '../shared/health';
+import { parseAssistantTurns, computeDrift } from '../shared/drift';
 /**
  * Watch a single JSONL session file for appended content.
  * On each file change, reads only the newly appended bytes, parses them into
@@ -39,23 +40,31 @@ export function watchSession(filePath, callbacks) {
             finally {
                 fs.closeSync(fd);
             }
-            bytesRead = fileSize;
-            const newContent = buffer.toString('utf8');
-            const newRows = parseJsonlContent(newContent);
-            if (newRows.length === 0)
+            // Only advance bytesRead for complete lines to avoid partial JSONL reads
+            const raw = buffer.toString('utf8');
+            const lastNewline = raw.lastIndexOf('\n');
+            if (lastNewline === -1) {
+                // No complete line yet — wait for next change event
                 return;
-            // Re-read full file for accurate health score (it's cumulative)
+            }
+            bytesRead += Buffer.byteLength(raw.slice(0, lastNewline + 1), 'utf8');
+            // Read full file once — needed for accurate health (cumulative metrics)
+            // and to produce complete rows with correct parent-child relationships
             let fullContent = '';
             try {
                 fullContent = fs.readFileSync(filePath, 'utf8');
             }
             catch {
-                fullContent = newContent;
+                fullContent = buffer.toString('utf8');
             }
-            const boundaries = parseCompactionBoundaries(fullContent);
             const allRows = parseJsonlContent(fullContent);
+            if (allRows.length === 0)
+                return;
+            const boundaries = parseCompactionBoundaries(fullContent);
             const health = computeContextHealth(allRows, boundaries.length);
-            callbacks.onNewRows(newRows, health, boundaries);
+            const turns = parseAssistantTurns(fullContent);
+            const drift = computeDrift(turns);
+            callbacks.onNewRows(allRows, health, boundaries, drift);
         }
         catch (err) {
             console.warn('[noctrace] watcher error:', err instanceof Error ? err.message : String(err));

package/dist/server/server/ws.js CHANGED Viewed

@@ -4,6 +4,7 @@
  */
 import { WebSocketServer, WebSocket } from 'ws';
 import { spawn } from 'node:child_process';
+import chokidar from 'chokidar';
 import path from 'node:path';
 import { watchSession } from './watcher';
 // ---------------------------------------------------------------------------
@@ -30,7 +31,38 @@ function send(ws, msg) {
  * back in real time using chokidar file watching.
  */
 export function setupWebSocket(server, claudeHome) {
-    const wss = new WebSocketServer({ server, path: '/ws' });
+    const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 64 * 1024 });
+    // Watch the projects directory for new .jsonl session files.
+    // When a new file appears, broadcast to all connected clients so they
+    // can refresh their session list without a manual page reload.
+    const projectsBase = path.join(claudeHome, 'projects');
+    const dirWatcher = chokidar.watch(projectsBase, {
+        persistent: true,
+        ignoreInitial: true,
+        depth: 1,
+    });
+    dirWatcher.on('add', (filePath) => {
+        if (!filePath.endsWith('.jsonl'))
+            return;
+        // Derive the project slug from the parent directory name
+        const relative = path.relative(projectsBase, filePath);
+        const slug = path.dirname(relative);
+        if (!slug || slug === '.')
+            return;
+        const msg = { type: 'session-created', slug };
+        const payload = JSON.stringify(msg);
+        for (const client of wss.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(payload);
+            }
+        }
+    });
+    dirWatcher.on('error', (err) => {
+        console.warn('[noctrace] dir watcher error:', err instanceof Error ? err.message : String(err));
+    });
+    wss.on('close', () => {
+        dirWatcher.close().catch(() => { });
+    });
     wss.on('connection', (ws, _req) => {
         let stopWatcher = null;
         let resumeProc = null;
@@ -74,6 +106,11 @@ export function setupWebSocket(server, claudeHome) {
                     send(ws, { type: 'resume-error', message: 'resume requires sessionId and message' });
                     return;
                 }
+                // Validate sessionId format — must be a UUID-like string, no dashes-starting args
+                if (!/^[a-zA-Z0-9_-]+$/.test(sessionId) || sessionId.startsWith('-')) {
+                    send(ws, { type: 'resume-error', message: 'Invalid sessionId format' });
+                    return;
+                }
                 const args = ['--resume', sessionId, '--print', '--verbose', '--output-format', 'stream-json'];
                 if (fork)
                     args.push('--fork-session');
@@ -167,10 +204,16 @@ export function setupWebSocket(server, claudeHome) {
             }
             // Stop any existing watcher before starting a new one
             stopCurrent();
-            const filePath = path.join(claudeHome, 'projects', slug, `${id}.jsonl`);
+            const projectsBase = path.join(claudeHome, 'projects');
+            const filePath = path.join(projectsBase, slug, `${id}.jsonl`);
+            const resolved = path.resolve(filePath);
+            if (!resolved.startsWith(path.resolve(projectsBase) + path.sep)) {
+                send(ws, { type: 'error', message: 'Invalid path' });
+                return;
+            }
             const handle = watchSession(filePath, {
-                onNewRows: (rows, health, boundaries) => {
-                    send(ws, { type: 'rows', rows, health, boundaries });
+                onNewRows: (rows, health, boundaries, drift) => {
+                    send(ws, { type: 'rows', rows, health, boundaries, drift });
                 },
             });
             stopWatcher = handle.stop;

package/dist/server/shared/drift.js ADDED Viewed

@@ -0,0 +1,94 @@
+const SAMPLE_SIZE = 5;
+/**
+ * Extract per-turn token usage from raw JSONL content.
+ *
+ * Scans for assistant records and sums all token usage fields per turn.
+ * Malformed lines and records missing usage data are silently skipped.
+ * Returns an array of {@link AssistantTurn} objects sorted by timestamp.
+ */
+export function parseAssistantTurns(content) {
+    const turns = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        let record;
+        try {
+            record = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (typeof record !== 'object' ||
+            record === null ||
+            record.type !== 'assistant') {
+            continue;
+        }
+        const raw = record;
+        const usage = raw.message?.usage;
+        if (usage == null)
+            continue;
+        const inputTokens = usage.input_tokens ?? 0;
+        const outputTokens = usage.output_tokens ?? 0;
+        const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
+        const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
+        const totalTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
+        if (totalTokens === 0 || isNaN(totalTokens))
+            continue;
+        const timestamp = raw.timestamp != null
+            ? new Date(raw.timestamp).getTime()
+            : 0;
+        turns.push({ timestamp, totalTokens, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens });
+    }
+    return turns.sort((a, b) => a.timestamp - b.timestamp);
+}
+/**
+ * Compute token drift factor from assistant turns.
+ *
+ * Compares the average total tokens of the first {@link SAMPLE_SIZE} turns
+ * (baseline) against the last {@link SAMPLE_SIZE} turns (current).
+ * Returns a {@link DriftAnalysis} with `driftFactor = 1.0` when there is
+ * insufficient data or when baseline is zero (guards against division by zero).
+ */
+export function computeDrift(turns) {
+    const turnCount = turns.length;
+    const totalTokens = turns.reduce((sum, t) => sum + t.totalTokens, 0);
+    if (turnCount < SAMPLE_SIZE) {
+        return {
+            driftFactor: 1.0,
+            baselineTokens: 0,
+            currentTokens: 0,
+            turnCount,
+            totalTokens,
+            estimatedSavings: 0,
+        };
+    }
+    const firstSlice = turns.slice(0, SAMPLE_SIZE);
+    const lastSlice = turns.slice(-SAMPLE_SIZE);
+    const baselineTokens = Math.round(firstSlice.reduce((sum, t) => sum + t.totalTokens, 0) / SAMPLE_SIZE);
+    const currentTokens = Math.round(lastSlice.reduce((sum, t) => sum + t.totalTokens, 0) / SAMPLE_SIZE);
+    if (baselineTokens === 0) {
+        return {
+            driftFactor: 1.0,
+            baselineTokens,
+            currentTokens,
+            turnCount,
+            totalTokens,
+            estimatedSavings: 0,
+        };
+    }
+    const driftFactor = Math.round((currentTokens / baselineTokens) * 10) / 10;
+    let estimatedSavings = 0;
+    if (driftFactor > 2) {
+        // Tokens spent beyond a 2x drift threshold could be reclaimed by rotating the session
+        estimatedSavings = Math.max(0, totalTokens - turnCount * baselineTokens * 2);
+    }
+    return {
+        driftFactor,
+        baselineTokens,
+        currentTokens,
+        turnCount,
+        totalTokens,
+        estimatedSavings,
+    };
+}

package/dist/server/shared/parser.js CHANGED Viewed

@@ -221,7 +221,7 @@ export function parseJsonlContent(content) {
                 : (res ? res.endTime : null);
             const effectiveDuration = agentRealDuration !== null
                 ? agentRealDuration
-                : (res ? res.endTime - startTime : null);
+                : (res ? Math.max(0, res.endTime - startTime) : null);
             pending.push({
                 id: block.id,
                 toolName: block.name,
@@ -366,7 +366,12 @@ export function parseJsonlContent(content) {
     for (const row of rowById.values()) {
         if (row.type !== 'agent' || row.children.length === 0)
             continue;
-        const childMax = Math.max(...row.children.map((c) => c.endTime ?? c.startTime));
+        let childMax = -Infinity;
+        for (const c of row.children) {
+            const end = c.endTime ?? c.startTime;
+            if (end > childMax)
+                childMax = end;
+        }
         if (childMax > (row.endTime ?? 0)) {
             row.endTime = childMax;
             row.duration = childMax - row.startTime;
@@ -501,7 +506,7 @@ export function parseSubAgentContent(content) {
                 label: buildLabel(block.name, block.input),
                 startTime,
                 endTime: res ? res.endTime : null,
-                duration: res ? res.endTime - startTime : null,
+                duration: res ? Math.max(0, res.endTime - startTime) : null,
                 status: res ? (res.isError ? 'error' : 'success') : 'running',
                 parentAgentId: null,
                 input: block.input,

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "noctrace",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Chrome DevTools Network-tab-style waterfall visualizer for Claude Code agent workflows",
   "type": "module",
   "license": "MIT",