@runcore-sh/runcore 0.1.2

package/dist/memory/visual.js

@@ -0,0 +1,218 @@
+/**
+ * Visual memory — persist images to FileManager + LTM with searchable descriptions.
+ * On retrieval, re-injects actual image data into LLM context as multimodal blocks.
+ */
+import { join } from "node:path";
+import { FileManager } from "../files/manager.js";
+import { FileSystemLongTermMemory } from "./file-backed.js";
+import { completeChat } from "../llm/complete.js";
+import { getEncryptionKey } from "../lib/key-store.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("visual-memory");
+const MEMORY_DIR = join(process.cwd(), "brain", "memory");
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/** Lazy LTM factory — same pattern as agents/memory.ts */
+function getLtm() {
+    return new FileSystemLongTermMemory(MEMORY_DIR, getEncryptionKey() ?? undefined);
+}
+/** Map mimeType to file extension. */
+function extFromMime(mime) {
+    const map = {
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/gif": "gif",
+        "image/webp": "webp",
+        "image/svg+xml": "svg",
+        "image/bmp": "bmp",
+    };
+    return map[mime] ?? "png";
+}
+// ── Type guard ──────────────────────────────────────────────────────────────
+/** Check if a memory entry is a visual memory (has fileId + source marker). */
+export function isVisualMemory(entry) {
+    return (entry.meta?.source === "visual-memory" &&
+        typeof entry.meta?.fileId === "string");
+}
+// ── Save ────────────────────────────────────────────────────────────────────
+/**
+ * Persist an image to FileManager and create a searchable episodic memory.
+ * Fire-and-forget safe — never throws, returns { ok: false } on failure.
+ */
+export async function saveVisualMemory(opts) {
+    try {
+        // 1. Validate
+        if (!opts.mimeType.startsWith("image/")) {
+            return { ok: false, error: "Not an image mimeType" };
+        }
+        const buffer = Buffer.from(opts.imageData, "base64");
+        const maxBytes = opts.maxImageBytes ?? 10 * 1024 * 1024;
+        if (buffer.length > maxBytes) {
+            return { ok: false, error: `Image too large: ${buffer.length} bytes (max ${maxBytes})` };
+        }
+        // 2. Upload to FileManager
+        const fm = FileManager.getInstance();
+        if (!fm) {
+            return { ok: false, error: "FileManager not initialized" };
+        }
+        const ext = extFromMime(opts.mimeType);
+        const ts = Date.now();
+        const uploadResult = await fm.upload({
+            buffer,
+            originalName: `chat-image-${ts}.${ext}`,
+            mimeType: opts.mimeType,
+            category: "media",
+            origin: "user-upload",
+            tags: ["visual-memory"],
+        });
+        if (!uploadResult.ok || !uploadResult.file) {
+            return { ok: false, error: `Upload failed: ${uploadResult.message}` };
+        }
+        const fileEntry = uploadResult.file;
+        // 3. Generate description via vision model
+        let description;
+        try {
+            description = await describeImage(opts.imageData, opts.mimeType, opts.userContext, opts.provider, opts.model);
+        }
+        catch (err) {
+            // Fallback if vision model unavailable
+            log.warn("Vision description failed, using fallback", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            description = opts.userContext
+                ? `Image shared by user. Context: ${opts.userContext.slice(0, 500)}`
+                : "Image shared by user (no description available).";
+        }
+        // 4. Persist to episodic memory
+        await getLtm().add({
+            type: "episodic",
+            content: description,
+            meta: {
+                source: "visual-memory",
+                fileId: fileEntry.id,
+                mimeType: opts.mimeType,
+                originalContext: opts.userContext.slice(0, 500),
+            },
+        });
+        log.info("Visual memory saved", { fileId: fileEntry.id, descLength: description.length });
+        return { ok: true, fileEntry, description };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error("saveVisualMemory failed", { error: msg });
+        return { ok: false, error: msg };
+    }
+}
+// ── Describe ────────────────────────────────────────────────────────────────
+/** Use a vision-capable model to generate a searchable text description of an image. */
+async function describeImage(imageData, mimeType, userContext, provider, model) {
+    const dataUri = `data:${mimeType};base64,${imageData}`;
+    const contextHint = userContext
+        ? `\nThe user said alongside this image: "${userContext.slice(0, 300)}"`
+        : "";
+    const response = await completeChat({
+        messages: [
+            {
+                role: "system",
+                content: "You describe images for a personal memory system. Be factual and concise.",
+            },
+            {
+                role: "user",
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Describe this image in 2-4 factual sentences for future search and retrieval.",
+                            "Cover: image type, key visual elements, any visible text or data, and apparent purpose.",
+                            contextHint,
+                        ].join("\n"),
+                    },
+                    {
+                        type: "image_url",
+                        image_url: { url: dataUri },
+                    },
+                ],
+            },
+        ],
+        provider,
+        model,
+        noCache: true,
+    });
+    return response.trim();
+}
+// ── Hydrate ─────────────────────────────────────────────────────────────────
+/**
+ * Re-hydrate visual memory entries with actual image data for LLM injection.
+ * Entries should already be relevance-sorted (from LTM search).
+ * Returns empty array on any failure — never throws.
+ */
+export async function hydrateVisualMemories(entries, maxImages = 2) {
+    const fm = FileManager.getInstance();
+    if (!fm)
+        return [];
+    const visual = entries.filter(isVisualMemory).slice(0, maxImages);
+    const results = [];
+    for (const entry of visual) {
+        try {
+            const fileId = entry.meta.fileId;
+            const readResult = await fm.read(fileId);
+            if (!readResult.ok || !readResult.data) {
+                log.debug("Skipping visual memory — file not found", { fileId });
+                continue;
+            }
+            const mimeType = entry.meta.mimeType || "image/png";
+            const dataUri = `data:${mimeType};base64,${readResult.data.toString("base64")}`;
+            results.push({
+                entry,
+                description: entry.content,
+                dataUri,
+                sizeBytes: readResult.data.length,
+            });
+        }
+        catch (err) {
+            log.debug("Skipping visual memory — read error", {
+                entryId: entry.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}
+// ── Targeted search ─────────────────────────────────────────────────────────
+/**
+ * Search LTM specifically for visual memory entries.
+ * Used as a fallback when the generic Brain.retrieve() didn't surface any
+ * visual memories (they got crowded out by other episodic entries).
+ *
+ * Two-pass strategy:
+ *  1. Try keyword match (user query) + meta filter — finds visuals relevant to what the user asked
+ *  2. If nothing, fetch ALL visual memories sorted by recency — ensures we always surface something
+ *
+ * Returns entries sorted by recency (newest first).
+ */
+export async function searchVisualMemories(query, max = 5) {
+    try {
+        const ltm = getLtm();
+        // Pass 1: keyword + meta — relevant visuals
+        const keywordHits = await ltm.search({
+            type: "episodic",
+            contentSubstring: query,
+            meta: { source: "visual-memory" },
+        });
+        const relevant = keywordHits.filter(isVisualMemory);
+        if (relevant.length > 0)
+            return relevant.slice(0, max);
+        // Pass 2: meta-only — most recent visual memories regardless of query match
+        const allVisual = await ltm.search({
+            type: "episodic",
+            meta: { source: "visual-memory" },
+        });
+        return allVisual.filter(isVisualMemory).slice(0, max);
+    }
+    catch (err) {
+        log.debug("searchVisualMemories failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return [];
+    }
+}
+//# sourceMappingURL=visual.js.map

package/dist/memory/visual.js.map

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

package/dist/memory/working.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Working memory — scratchpad for the current turn (COALA working memory).
+ * Holds perceptual input, active goal, retrieved LTM items, and scratch.
+ */
+import type { WorkingMemory } from "../types.js";
+export declare function createWorkingMemory(): WorkingMemory;
+export declare function updateWorkingMemory(current: WorkingMemory, updates: Partial<Pick<WorkingMemory, "perceptualInput" | "activeGoal" | "retrieved" | "lastThought">> & {
+    scratch?: Record<string, unknown>;
+}): WorkingMemory;
+/** Format working memory for inclusion in context (supporting content or instructions). */
+export declare function formatWorkingMemoryForContext(wm: WorkingMemory): string;
+//# sourceMappingURL=working.d.ts.map

package/dist/memory/working.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working.d.ts","sourceRoot":"","sources":["../../src/memory/working.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D,wBAAgB,mBAAmB,IAAI,aAAa,CAKnD;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,iBAAiB,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC5I,aAAa,CAOf;AAED,2FAA2F;AAC3F,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAavE"}

package/dist/memory/working.js

@@ -0,0 +1,34 @@
+/**
+ * Working memory — scratchpad for the current turn (COALA working memory).
+ * Holds perceptual input, active goal, retrieved LTM items, and scratch.
+ */
+export function createWorkingMemory() {
+    return {
+        retrieved: [],
+        scratch: {},
+    };
+}
+export function updateWorkingMemory(current, updates) {
+    const next = {
+        ...current,
+        ...updates,
+        scratch: updates.scratch !== undefined ? { ...current.scratch, ...updates.scratch } : current.scratch,
+    };
+    return next;
+}
+/** Format working memory for inclusion in context (supporting content or instructions). */
+export function formatWorkingMemoryForContext(wm) {
+    const parts = [];
+    if (wm.activeGoal)
+        parts.push(`## Active goal\n${wm.activeGoal}`);
+    if (wm.retrieved.length > 0) {
+        parts.push("## Retrieved from memory\n" +
+            wm.retrieved
+                .map((e) => `- [${e.type}] ${e.content}`)
+                .join("\n"));
+    }
+    if (wm.lastThought)
+        parts.push(`## Latest thought\n${wm.lastThought}`);
+    return parts.length > 0 ? parts.join("\n\n") : "";
+}
+//# sourceMappingURL=working.js.map

package/dist/memory/working.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"working.js","sourceRoot":"","sources":["../../src/memory/working.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,SAAS,EAAE,EAAE;QACb,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,OAAsB,EACtB,OAA6I;IAE7I,MAAM,IAAI,GAAkB;QAC1B,GAAG,OAAO;QACV,GAAG,OAAO;QACV,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO;KACtG,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,6BAA6B,CAAC,EAAiB;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,EAAE,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC;IAClE,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CACR,4BAA4B;YAC1B,EAAE,CAAC,SAAS;iBACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;iBACxC,IAAI,CAAC,IAAI,CAAC,CAChB,CAAC;IACJ,CAAC;IACD,IAAI,EAAE,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACvE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC"}

package/dist/metrics/aggregator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Tiered metrics aggregation — hourly and daily rollups.
+ * Reads raw MetricPoints from the store, buckets by time window,
+ * and writes aggregate JSON files to brain/metrics/hourly/ and brain/metrics/daily/.
+ *
+ * Metric types are inferred from name/unit:
+ * - Counters (unit "count"): summed
+ * - Gauges (unit "%", "bytes", "ms", "ratio"): averaged with min/max
+ * - All metrics get count, sum, min, max, avg, p50, p95, p99
+ *
+ * Aggregation is designed to run in the background without blocking collection.
+ */
+import type { MetricsStore } from "./store.js";
+export interface AggregateWindow {
+    start: string;
+    end: string;
+    type: "hourly" | "daily";
+}
+export interface AggregateEntry {
+    name: string;
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    unit?: string;
+    tags?: Record<string, string>;
+}
+export interface AggregateFile {
+    window: AggregateWindow;
+    metrics: AggregateEntry[];
+    pointsProcessed: number;
+    generatedAt: string;
+}
+/**
+ * Run hourly aggregation for all complete hours in the store.
+ * Skips hours that already have an aggregate file.
+ * Returns the number of new aggregate files written.
+ */
+export declare function aggregateHourly(store: MetricsStore, metricsDir: string): Promise<number>;
+/**
+ * Run daily aggregation for all complete days in the store.
+ * Skips days that already have an aggregate file.
+ * Returns the number of new aggregate files written.
+ */
+export declare function aggregateDaily(store: MetricsStore, metricsDir: string): Promise<number>;
+/**
+ * Run both hourly and daily aggregation. Safe to call frequently —
+ * already-aggregated windows are skipped.
+ * Returns total new files written.
+ */
+export declare function runAggregation(store: MetricsStore, metricsDir: string): Promise<number>;
+/** Check if aggregation is currently running. */
+export declare function isAggregating(): boolean;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/metrics/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../../src/metrics/aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO/C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAmJD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB9F;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB7F;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB7F;AAED,iDAAiD;AACjD,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}

package/dist/metrics/aggregator.js

@@ -0,0 +1,253 @@
+/**
+ * Tiered metrics aggregation — hourly and daily rollups.
+ * Reads raw MetricPoints from the store, buckets by time window,
+ * and writes aggregate JSON files to brain/metrics/hourly/ and brain/metrics/daily/.
+ *
+ * Metric types are inferred from name/unit:
+ * - Counters (unit "count"): summed
+ * - Gauges (unit "%", "bytes", "ms", "ratio"): averaged with min/max
+ * - All metrics get count, sum, min, max, avg, p50, p95, p99
+ *
+ * Aggregation is designed to run in the background without blocking collection.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("metrics.aggregator");
+// ─── Module state ────────────────────────────────────────────────────────────
+let running = false;
+// ─── Core aggregation ────────────────────────────────────────────────────────
+/**
+ * Group metric points into time buckets.
+ * Returns a map of bucket key → points in that bucket.
+ */
+function bucketPoints(points, type) {
+    const buckets = new Map();
+    for (const point of points) {
+        const dt = new Date(point.timestamp);
+        // Key format: YYYY-MM-DD-HH for hourly, YYYY-MM-DD for daily
+        const key = type === "hourly"
+            ? `${dt.getUTCFullYear()}-${pad(dt.getUTCMonth() + 1)}-${pad(dt.getUTCDate())}-${pad(dt.getUTCHours())}`
+            : `${dt.getUTCFullYear()}-${pad(dt.getUTCMonth() + 1)}-${pad(dt.getUTCDate())}`;
+        let bucket = buckets.get(key);
+        if (!bucket) {
+            bucket = [];
+            buckets.set(key, bucket);
+        }
+        bucket.push(point);
+    }
+    return buckets;
+}
+/**
+ * Compute a unique grouping key for a metric point (name + sorted tags).
+ */
+function metricKey(point) {
+    if (!point.tags || Object.keys(point.tags).length === 0) {
+        return point.name;
+    }
+    const tagStr = Object.entries(point.tags)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}=${v}`)
+        .join(",");
+    return `${point.name}{${tagStr}}`;
+}
+/**
+ * Aggregate a set of points sharing the same name+tags into a summary entry.
+ */
+function aggregateGroup(points) {
+    const values = points.map((p) => p.value).sort((a, b) => a - b);
+    const sum = values.reduce((acc, v) => acc + v, 0);
+    return {
+        name: points[0].name,
+        count: values.length,
+        sum,
+        min: values[0],
+        max: values[values.length - 1],
+        avg: Math.round((sum / values.length) * 1000) / 1000,
+        p50: percentile(values, 50),
+        p95: percentile(values, 95),
+        p99: percentile(values, 99),
+        unit: points[0].unit,
+        ...(points[0].tags && Object.keys(points[0].tags).length > 0
+            ? { tags: points[0].tags }
+            : {}),
+    };
+}
+/**
+ * Build an aggregate file from a bucket of raw points.
+ */
+function buildAggregate(bucketKey, points, type) {
+    // Determine window boundaries from bucket key
+    const { start, end } = windowFromKey(bucketKey, type);
+    // Group by metric name + tags
+    const groups = new Map();
+    for (const point of points) {
+        const key = metricKey(point);
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push(point);
+    }
+    // Aggregate each group
+    const metrics = [];
+    for (const group of groups.values()) {
+        metrics.push(aggregateGroup(group));
+    }
+    // Sort by name for stable output
+    metrics.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        window: { start, end, type },
+        metrics,
+        pointsProcessed: points.length,
+        generatedAt: new Date().toISOString(),
+    };
+}
+// ─── File I/O ────────────────────────────────────────────────────────────────
+/**
+ * Check if an aggregate file already exists.
+ */
+async function aggregateExists(dir, filename) {
+    try {
+        await readFile(join(dir, filename), "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write an aggregate file to disk.
+ */
+async function writeAggregate(dir, filename, aggregate) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, filename), JSON.stringify(aggregate, null, 2) + "\n", "utf-8");
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Run hourly aggregation for all complete hours in the store.
+ * Skips hours that already have an aggregate file.
+ * Returns the number of new aggregate files written.
+ */
+export async function aggregateHourly(store, metricsDir) {
+    const hourlyDir = join(metricsDir, "hourly");
+    const points = await store.query();
+    if (points.length === 0)
+        return 0;
+    const buckets = bucketPoints(points, "hourly");
+    const currentHourKey = getCurrentBucketKey("hourly");
+    let written = 0;
+    for (const [key, bucketPoints] of buckets) {
+        // Skip the current (incomplete) hour
+        if (key === currentHourKey)
+            continue;
+        const filename = `${key}.json`;
+        if (await aggregateExists(hourlyDir, filename))
+            continue;
+        const aggregate = buildAggregate(key, bucketPoints, "hourly");
+        await writeAggregate(hourlyDir, filename, aggregate);
+        written++;
+        log.debug(`Wrote hourly aggregate: ${filename} (${bucketPoints.length} points)`);
+    }
+    return written;
+}
+/**
+ * Run daily aggregation for all complete days in the store.
+ * Skips days that already have an aggregate file.
+ * Returns the number of new aggregate files written.
+ */
+export async function aggregateDaily(store, metricsDir) {
+    const dailyDir = join(metricsDir, "daily");
+    const points = await store.query();
+    if (points.length === 0)
+        return 0;
+    const buckets = bucketPoints(points, "daily");
+    const currentDayKey = getCurrentBucketKey("daily");
+    let written = 0;
+    for (const [key, bucketPoints] of buckets) {
+        // Skip the current (incomplete) day
+        if (key === currentDayKey)
+            continue;
+        const filename = `${key}.json`;
+        if (await aggregateExists(dailyDir, filename))
+            continue;
+        const aggregate = buildAggregate(key, bucketPoints, "daily");
+        await writeAggregate(dailyDir, filename, aggregate);
+        written++;
+        log.debug(`Wrote daily aggregate: ${filename} (${bucketPoints.length} points)`);
+    }
+    return written;
+}
+/**
+ * Run both hourly and daily aggregation. Safe to call frequently —
+ * already-aggregated windows are skipped.
+ * Returns total new files written.
+ */
+export async function runAggregation(store, metricsDir) {
+    if (running) {
+        log.debug("Aggregation already in progress, skipping");
+        return 0;
+    }
+    running = true;
+    try {
+        const hourly = await aggregateHourly(store, metricsDir);
+        const daily = await aggregateDaily(store, metricsDir);
+        const total = hourly + daily;
+        if (total > 0) {
+            log.info(`Aggregation complete: ${hourly} hourly + ${daily} daily files`);
+        }
+        return total;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`Aggregation failed: ${msg}`);
+        return 0;
+    }
+    finally {
+        running = false;
+    }
+}
+/** Check if aggregation is currently running. */
+export function isAggregating() {
+    return running;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+function getCurrentBucketKey(type) {
+    const now = new Date();
+    if (type === "hourly") {
+        return `${now.getUTCFullYear()}-${pad(now.getUTCMonth() + 1)}-${pad(now.getUTCDate())}-${pad(now.getUTCHours())}`;
+    }
+    return `${now.getUTCFullYear()}-${pad(now.getUTCMonth() + 1)}-${pad(now.getUTCDate())}`;
+}
+function windowFromKey(key, type) {
+    if (type === "hourly") {
+        // key format: YYYY-MM-DD-HH
+        const [year, month, day, hour] = key.split("-").map(Number);
+        const start = new Date(Date.UTC(year, month - 1, day, hour, 0, 0, 0));
+        const end = new Date(start.getTime() + 60 * 60 * 1000); // +1 hour
+        return { start: start.toISOString(), end: end.toISOString() };
+    }
+    // key format: YYYY-MM-DD
+    const [year, month, day] = key.split("-").map(Number);
+    const start = new Date(Date.UTC(year, month - 1, day, 0, 0, 0, 0));
+    const end = new Date(start.getTime() + 24 * 60 * 60 * 1000); // +1 day
+    return { start: start.toISOString(), end: end.toISOString() };
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const idx = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(idx);
+    const upper = Math.ceil(idx);
+    if (lower === upper)
+        return sorted[lower];
+    const result = sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
+    return Math.round(result * 1000) / 1000;
+}
+//# sourceMappingURL=aggregator.js.map

package/dist/metrics/aggregator.js.map

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

package/dist/metrics/collector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Metrics collector — background collection of system, HTTP, agent, and error metrics.
+ * Follows queue/timer.ts pattern: module-level state, idempotent start/stop, dynamic intervals.
+ */
+import { MetricsStore } from "./store.js";
+/** Record an HTTP request's latency and status. Called by the metrics middleware. */
+export declare function recordHttp(durationMs: number, statusCode: number, method?: string, endpoint?: string): void;
+/** Adjust concurrent request count. Called by the metrics middleware. */
+export declare function recordConcurrentRequests(delta: number): void;
+/** Record an agent spawn event. */
+export declare function recordAgentSpawn(): void;
+/** Record an agent completion. durationMs is startedAt→finishedAt. */
+export declare function recordAgentCompletion(durationMs: number, success: boolean): void;
+/** Record an error by source category. */
+export declare function recordError(source: string): void;
+/**
+ * Start the background metrics collector. Idempotent.
+ * Collects system, HTTP, agent, and error metrics at a fixed interval.
+ * @param brainDir - Path to the brain directory, used for aggregation output.
+ */
+export declare function startCollector(metricsStore: MetricsStore, intervalMs?: number, brainDir?: string): void;
+/** Stop the metrics collector. */
+export declare function stopCollector(): void;
+/** Check if the collector is running. */
+export declare function isCollectorRunning(): boolean;
+//# sourceMappingURL=collector.d.ts.map

package/dist/metrics/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/metrics/collector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAmR1C,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAW3G;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAK5D;AAED,mCAAmC;AACnC,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAoBhF;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAMhD;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,YAAY,EAC1B,UAAU,CAAC,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CA0BN;AAED,kCAAkC;AAClC,wBAAgB,aAAa,IAAI,IAAI,CAOpC;AAED,yCAAyC;AACzC,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C"}