@n-dx/web 0.1.0

package/dist/server/concurrent-execution-metrics.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Concurrent execution metrics collection and resource utilization tracking.
+ *
+ * Collects time-series snapshots of concurrent process counts, total memory
+ * utilization across all hench processes, and per-task resource metrics.
+ * Snapshots are stored in bounded ring buffers and aggregated into patterns
+ * (peak, average) for dashboard consumption.
+ *
+ * This is the web-server counterpart to hench's own ConcurrentExecutionMetrics.
+ * Implemented separately to avoid adding a runtime dependency from
+ * @n-dx/web to hench (web reads hench data from disk, never imports it).
+ *
+ * @module @n-dx/web/server/concurrent-execution-metrics
+ */
+export interface ConcurrentExecutionMetricsConfig {
+    maxSnapshots: number;
+    maxCompletedTasks: number;
+}
+export declare const DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG: ConcurrentExecutionMetricsConfig;
+/** A single point-in-time snapshot of concurrent execution state. */
+export interface ExecutionMetricsSnapshot {
+    concurrentCount: number;
+    totalRssBytes: number;
+    systemMemoryPercent: number;
+    loadAvg1m: number;
+    timestamp: string;
+    epochMs: number;
+}
+/** Resource utilization metrics for a single task execution. */
+export interface TaskResourceMetrics {
+    taskId: string;
+    taskTitle: string;
+    pid: number;
+    startedAt: string;
+    completedAt?: string;
+    durationMs: number;
+    peakRssBytes: number;
+    avgRssBytes: number;
+    currentRssBytes: number;
+    sampleCount: number;
+    avgConcurrentDuringExecution: number;
+}
+/** Aggregated utilization patterns from time-series data. */
+export interface UtilizationPatterns {
+    peakConcurrent: number;
+    avgConcurrent: number;
+    peakTotalRssBytes: number;
+    avgTotalRssBytes: number;
+    avgSystemMemoryPercent: number;
+    peakSystemMemoryPercent: number;
+    avgLoadAvg1m: number;
+    peakLoadAvg1m: number;
+    windowDurationMs: number;
+    snapshotCount: number;
+}
+/** Full metrics summary for API response. */
+export interface ExecutionMetricsSummary {
+    current: ExecutionMetricsSnapshot;
+    patterns: UtilizationPatterns;
+    activeTasks: TaskResourceMetrics[];
+    completedTasks: TaskResourceMetrics[];
+    timestamp: string;
+}
+/**
+ * Collects and aggregates concurrent execution metrics across hench processes.
+ *
+ * Records periodic snapshots of concurrent process counts and memory utilization,
+ * tracks per-task resource usage, and computes utilization patterns.
+ */
+export declare class ConcurrentExecutionMetrics {
+    private readonly _config;
+    private readonly _snapshots;
+    private readonly _activeTasks;
+    private readonly _completedTasks;
+    private readonly _now;
+    constructor(config?: Partial<ConcurrentExecutionMetricsConfig>, overrides?: {
+        now?: () => number;
+    });
+    get config(): Readonly<ConcurrentExecutionMetricsConfig>;
+    get snapshotCount(): number;
+    get activeTaskCount(): number;
+    get completedTaskCount(): number;
+    taskStarted(taskId: string, taskTitle: string, pid: number): void;
+    taskCompleted(taskId: string): void;
+    recordSnapshot(input: {
+        concurrentCount: number;
+        totalRssBytes: number;
+        systemMemoryPercent: number;
+        loadAvg1m: number;
+        perTaskRss: Array<{
+            taskId: string;
+            rssBytes: number;
+        }>;
+    }): void;
+    getLatestSnapshot(): ExecutionMetricsSnapshot;
+    getSnapshots(): ExecutionMetricsSnapshot[];
+    computePatterns(): UtilizationPatterns;
+    getActiveTaskMetrics(): TaskResourceMetrics[];
+    getCompletedTaskMetrics(): TaskResourceMetrics[];
+    getSummary(): ExecutionMetricsSummary;
+    reset(): void;
+    private _buildTaskMetrics;
+}

package/dist/server/concurrent-execution-metrics.js

@@ -0,0 +1,253 @@
+/**
+ * Concurrent execution metrics collection and resource utilization tracking.
+ *
+ * Collects time-series snapshots of concurrent process counts, total memory
+ * utilization across all hench processes, and per-task resource metrics.
+ * Snapshots are stored in bounded ring buffers and aggregated into patterns
+ * (peak, average) for dashboard consumption.
+ *
+ * This is the web-server counterpart to hench's own ConcurrentExecutionMetrics.
+ * Implemented separately to avoid adding a runtime dependency from
+ * @n-dx/web to hench (web reads hench data from disk, never imports it).
+ *
+ * @module @n-dx/web/server/concurrent-execution-metrics
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum time-series snapshots retained (ring buffer size). */
+const DEFAULT_MAX_SNAPSHOTS = 360;
+/** Maximum completed task metrics retained for post-mortem analysis. */
+const DEFAULT_MAX_COMPLETED_TASKS = 50;
+export const DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG = {
+    maxSnapshots: DEFAULT_MAX_SNAPSHOTS,
+    maxCompletedTasks: DEFAULT_MAX_COMPLETED_TASKS,
+};
+// ---------------------------------------------------------------------------
+// ConcurrentExecutionMetrics
+// ---------------------------------------------------------------------------
+/**
+ * Collects and aggregates concurrent execution metrics across hench processes.
+ *
+ * Records periodic snapshots of concurrent process counts and memory utilization,
+ * tracks per-task resource usage, and computes utilization patterns.
+ */
+export class ConcurrentExecutionMetrics {
+    _config;
+    _snapshots = [];
+    _activeTasks = new Map();
+    _completedTasks = [];
+    _now;
+    constructor(config, overrides) {
+        this._config = { ...DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG, ...config };
+        this._now = overrides?.now ?? Date.now;
+    }
+    get config() {
+        return { ...this._config };
+    }
+    get snapshotCount() {
+        return this._snapshots.length;
+    }
+    get activeTaskCount() {
+        return this._activeTasks.size;
+    }
+    get completedTaskCount() {
+        return this._completedTasks.length;
+    }
+    // -----------------------------------------------------------------------
+    // Task lifecycle
+    // -----------------------------------------------------------------------
+    taskStarted(taskId, taskTitle, pid) {
+        const now = this._now();
+        this._activeTasks.set(taskId, {
+            taskId,
+            taskTitle,
+            pid,
+            startedAt: new Date(now).toISOString(),
+            startedEpochMs: now,
+            rssSumBytes: 0,
+            rssSampleCount: 0,
+            peakRssBytes: 0,
+            currentRssBytes: 0,
+            concurrentSum: 0,
+            concurrentSampleCount: 0,
+            active: true,
+        });
+    }
+    taskCompleted(taskId) {
+        const tracked = this._activeTasks.get(taskId);
+        if (!tracked)
+            return;
+        const now = this._now();
+        tracked.active = false;
+        tracked.completedAt = new Date(now).toISOString();
+        tracked.completedEpochMs = now;
+        this._activeTasks.delete(taskId);
+        this._completedTasks.push(tracked);
+        while (this._completedTasks.length > this._config.maxCompletedTasks) {
+            this._completedTasks.shift();
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Snapshot recording
+    // -----------------------------------------------------------------------
+    recordSnapshot(input) {
+        const now = this._now();
+        const snapshot = {
+            concurrentCount: input.concurrentCount,
+            totalRssBytes: input.totalRssBytes,
+            systemMemoryPercent: input.systemMemoryPercent,
+            loadAvg1m: input.loadAvg1m,
+            timestamp: new Date(now).toISOString(),
+            epochMs: now,
+        };
+        if (this._snapshots.length >= this._config.maxSnapshots) {
+            this._snapshots.shift();
+        }
+        this._snapshots.push(snapshot);
+        for (const { taskId, rssBytes } of input.perTaskRss) {
+            const tracked = this._activeTasks.get(taskId);
+            if (!tracked)
+                continue;
+            tracked.rssSumBytes += rssBytes;
+            tracked.rssSampleCount += 1;
+            tracked.currentRssBytes = rssBytes;
+            if (rssBytes > tracked.peakRssBytes) {
+                tracked.peakRssBytes = rssBytes;
+            }
+            tracked.concurrentSum += input.concurrentCount;
+            tracked.concurrentSampleCount += 1;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Queries
+    // -----------------------------------------------------------------------
+    getLatestSnapshot() {
+        const last = this._snapshots[this._snapshots.length - 1];
+        if (last)
+            return { ...last };
+        const now = this._now();
+        return {
+            concurrentCount: 0,
+            totalRssBytes: 0,
+            systemMemoryPercent: 0,
+            loadAvg1m: 0,
+            timestamp: new Date(now).toISOString(),
+            epochMs: now,
+        };
+    }
+    getSnapshots() {
+        return this._snapshots.map((s) => ({ ...s }));
+    }
+    computePatterns() {
+        const n = this._snapshots.length;
+        if (n === 0) {
+            return {
+                peakConcurrent: 0,
+                avgConcurrent: 0,
+                peakTotalRssBytes: 0,
+                avgTotalRssBytes: 0,
+                avgSystemMemoryPercent: 0,
+                peakSystemMemoryPercent: 0,
+                avgLoadAvg1m: 0,
+                peakLoadAvg1m: 0,
+                windowDurationMs: 0,
+                snapshotCount: 0,
+            };
+        }
+        let sumConcurrent = 0;
+        let peakConcurrent = 0;
+        let sumRss = 0;
+        let peakRss = 0;
+        let sumMemPercent = 0;
+        let peakMemPercent = 0;
+        let sumLoad = 0;
+        let peakLoad = 0;
+        for (const s of this._snapshots) {
+            sumConcurrent += s.concurrentCount;
+            if (s.concurrentCount > peakConcurrent)
+                peakConcurrent = s.concurrentCount;
+            sumRss += s.totalRssBytes;
+            if (s.totalRssBytes > peakRss)
+                peakRss = s.totalRssBytes;
+            sumMemPercent += s.systemMemoryPercent;
+            if (s.systemMemoryPercent > peakMemPercent)
+                peakMemPercent = s.systemMemoryPercent;
+            sumLoad += s.loadAvg1m;
+            if (s.loadAvg1m > peakLoad)
+                peakLoad = s.loadAvg1m;
+        }
+        const first = this._snapshots[0];
+        const last = this._snapshots[n - 1];
+        const windowDurationMs = last.epochMs - first.epochMs;
+        return {
+            peakConcurrent,
+            avgConcurrent: Math.round((sumConcurrent / n) * 100) / 100,
+            peakTotalRssBytes: peakRss,
+            avgTotalRssBytes: Math.round(sumRss / n),
+            avgSystemMemoryPercent: Math.round((sumMemPercent / n) * 100) / 100,
+            peakSystemMemoryPercent: peakMemPercent,
+            avgLoadAvg1m: Math.round((sumLoad / n) * 100) / 100,
+            peakLoadAvg1m: Math.round(peakLoad * 100) / 100,
+            windowDurationMs,
+            snapshotCount: n,
+        };
+    }
+    getActiveTaskMetrics() {
+        const now = this._now();
+        const result = [];
+        for (const t of this._activeTasks.values()) {
+            result.push(this._buildTaskMetrics(t, now));
+        }
+        return result;
+    }
+    getCompletedTaskMetrics() {
+        const now = this._now();
+        return this._completedTasks.map((t) => this._buildTaskMetrics(t, now));
+    }
+    getSummary() {
+        const now = this._now();
+        return {
+            current: this.getLatestSnapshot(),
+            patterns: this.computePatterns(),
+            activeTasks: this.getActiveTaskMetrics(),
+            completedTasks: this.getCompletedTaskMetrics(),
+            timestamp: new Date(now).toISOString(),
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Reset
+    // -----------------------------------------------------------------------
+    reset() {
+        this._snapshots.length = 0;
+        this._activeTasks.clear();
+        this._completedTasks.length = 0;
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    _buildTaskMetrics(tracked, now) {
+        const endTime = tracked.completedEpochMs ?? now;
+        const durationMs = endTime - tracked.startedEpochMs;
+        const avgRss = tracked.rssSampleCount > 0
+            ? Math.round(tracked.rssSumBytes / tracked.rssSampleCount)
+            : 0;
+        const avgConcurrent = tracked.concurrentSampleCount > 0
+            ? Math.round((tracked.concurrentSum / tracked.concurrentSampleCount) * 100) / 100
+            : 0;
+        return {
+            taskId: tracked.taskId,
+            taskTitle: tracked.taskTitle,
+            pid: tracked.pid,
+            startedAt: tracked.startedAt,
+            completedAt: tracked.completedAt,
+            durationMs,
+            peakRssBytes: tracked.peakRssBytes,
+            avgRssBytes: avgRss,
+            currentRssBytes: tracked.currentRssBytes,
+            sampleCount: tracked.rssSampleCount,
+            avgConcurrentDuringExecution: avgConcurrent,
+        };
+    }
+}
+//# sourceMappingURL=concurrent-execution-metrics.js.map

package/dist/server/concurrent-execution-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrent-execution-metrics.js","sourceRoot":"","sources":["../../src/server/concurrent-execution-metrics.ts"],"names":[],"mappings":"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"}

package/dist/server/domain-gateway.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Centralized gateway for sourcevision runtime imports.
+ *
+ * Web route handlers need the sourcevision MCP server factory to serve
+ * the `/mcp/sourcevision` endpoint. Rather than importing from "@n-dx/sourcevision"
+ * directly in route files, all web→sourcevision runtime imports pass through
+ * this single module.
+ *
+ * By concentrating all web→sourcevision runtime imports here, we ensure:
+ * - The cross-package surface is **explicit** (1 re-export, not scattered imports).
+ * - The DAG stays **acyclic** — sourcevision never imports from web.
+ * - Future changes to sourcevision's public API need only be updated here.
+ *
+ * @module web/server/domain-gateway
+ * @see packages/web/src/server/rex-gateway.ts — web's gateway for rex imports
+ * @see packages/hench/src/prd/rex-gateway.ts — hench's equivalent gateway
+ */
+export { createSourcevisionMcpServer } from "@n-dx/sourcevision";

package/dist/server/domain-gateway.js

@@ -0,0 +1,19 @@
+/**
+ * Centralized gateway for sourcevision runtime imports.
+ *
+ * Web route handlers need the sourcevision MCP server factory to serve
+ * the `/mcp/sourcevision` endpoint. Rather than importing from "@n-dx/sourcevision"
+ * directly in route files, all web→sourcevision runtime imports pass through
+ * this single module.
+ *
+ * By concentrating all web→sourcevision runtime imports here, we ensure:
+ * - The cross-package surface is **explicit** (1 re-export, not scattered imports).
+ * - The DAG stays **acyclic** — sourcevision never imports from web.
+ * - Future changes to sourcevision's public API need only be updated here.
+ *
+ * @module web/server/domain-gateway
+ * @see packages/web/src/server/rex-gateway.ts — web's gateway for rex imports
+ * @see packages/hench/src/prd/rex-gateway.ts — hench's equivalent gateway
+ */
+export { createSourcevisionMcpServer } from "@n-dx/sourcevision";
+//# sourceMappingURL=domain-gateway.js.map

package/dist/server/domain-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-gateway.js","sourceRoot":"","sources":["../../src/server/domain-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/server/incremental-task-usage.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Incremental task usage aggregator.
+ *
+ * Maintains an in-memory cache of per-task token usage aggregation.
+ * On each refresh, only processes new/modified run files using
+ * mtime+size change detection, keeping aggregation time constant
+ * regardless of total run history size.
+ *
+ * ## Design
+ *
+ * Each run file's contribution (taskId + totalTokens) is tracked
+ * individually so that modifications and deletions can be applied
+ * as incremental deltas rather than requiring a full re-scan.
+ *
+ * Change detection uses mtime + file size — the same strategy as
+ * hench's `RunChangeDetector` — to avoid reading unchanged files.
+ *
+ * @module web/server/incremental-task-usage
+ */
+import type { TaskUsageAccumulator } from "./shared-types.js";
+export type { TaskUsageAccumulator } from "./shared-types.js";
+/**
+ * Incrementally aggregates per-task token usage from `.hench/runs/` files.
+ *
+ * First call processes all existing run files (full scan). Subsequent calls
+ * detect filesystem changes via mtime+size comparison and only read the
+ * files that were added, modified, or deleted — keeping aggregation time
+ * constant regardless of total run history size.
+ *
+ * Usage:
+ * ```ts
+ * const aggregator = new IncrementalTaskUsageAggregator(runsDir);
+ * const usage = await aggregator.getTaskUsage();
+ * // { "task-123": { totalTokens: 5000, runCount: 2 }, ... }
+ * ```
+ */
+export declare class IncrementalTaskUsageAggregator {
+    private readonly runsDir;
+    /** Current snapshot of each file's mtime + size. */
+    private fileSnapshots;
+    /** Per-file contribution to the aggregation (for subtract-on-change). */
+    private fileContributions;
+    /** Aggregated usage per task ID. */
+    private taskUsage;
+    /** Whether the initial full scan has been completed. */
+    private initialized;
+    constructor(runsDir: string);
+    /**
+     * Get current per-task token usage, incrementally updating from filesystem.
+     *
+     * First call processes all files; subsequent calls only process changes.
+     * Returns a plain object keyed by task ID.
+     */
+    getTaskUsage(): Promise<Record<string, TaskUsageAccumulator>>;
+    /**
+     * Force a full rebuild on the next `getTaskUsage()` call.
+     * Useful for testing or when external state is known to have changed.
+     */
+    reset(): void;
+    /**
+     * Remove aggregation entries for task IDs not present in `validTaskIds`.
+     *
+     * Cleans up both the `taskUsage` accumulator and corresponding
+     * `fileContributions` entries. File snapshots are preserved so that
+     * the underlying run files are not re-processed on the next refresh
+     * (they are still on disk, just no longer contributing to results).
+     *
+     * Call this after `getTaskUsage()` — or let the route handler call it
+     * before returning results — to ensure the UI never sees usage data
+     * for tasks that have been deleted from the PRD.
+     *
+     * @returns The number of stale task IDs that were pruned.
+     */
+    pruneStaleEntries(validTaskIds: Set<string>): number;
+    private refresh;
+    /** Subtract a file's previously tracked contribution from the task total. */
+    private subtractContribution;
+    /** Add a file's contribution to the task total. */
+    private applyContribution;
+    /**
+     * Read a single run file (plain JSON or gzip-compressed) and extract
+     * its task usage contribution.
+     * Returns null for files that cannot be read or lack a taskId.
+     */
+    private readFileContribution;
+    /**
+     * Scan the runs directory and return a snapshot map of all run files
+     * (`.json` and `.json.gz`). Hidden files (prefixed with `.`) are
+     * excluded to avoid picking up checkpoint or metadata files.
+     */
+    private scanRunFiles;
+}