chapterhouse 0.4.2 → 0.4.3

package/dist/memory/housekeeping-scheduler.js

@@ -0,0 +1,152 @@
+import { childLogger } from "../util/logger.js";
+import { isHousekeepingInFlight, runHousekeeping } from "./housekeeping.js";
+export const DEFAULT_MEMORY_HOUSEKEEP_INTERVAL_MS = 21_600_000;
+export const DEFAULT_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS = 300_000;
+function parseNonNegativeIntegerEnv(name, rawValue, defaultValue) {
+    const normalized = rawValue?.trim();
+    if (!normalized) {
+        return defaultValue;
+    }
+    const parsed = Number(normalized);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${name} must be a non-negative integer, got: "${rawValue}"`);
+    }
+    return parsed;
+}
+function toPassCounts(result) {
+    return Object.fromEntries(result.summaries.map((summary) => [
+        summary.pass,
+        {
+            examined: summary.examined,
+            modified: summary.modified,
+            errors: summary.errors,
+        },
+    ]));
+}
+export class MemoryHousekeepingScheduler {
+    env;
+    runHousekeepingImpl;
+    log;
+    setTimeoutImpl;
+    clearTimeoutImpl;
+    setIntervalImpl;
+    clearIntervalImpl;
+    timeoutHandle;
+    intervalHandle;
+    activeRun;
+    running = false;
+    started = false;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.runHousekeepingImpl = options.runHousekeeping ?? runHousekeeping;
+        this.log = options.log ?? childLogger("memory.housekeeping.scheduler");
+        this.setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+        this.clearTimeoutImpl = options.clearTimeoutImpl ?? ((handle) => clearTimeout(handle));
+        this.setIntervalImpl = options.setIntervalImpl ?? setInterval;
+        this.clearIntervalImpl = options.clearIntervalImpl ?? ((handle) => clearInterval(handle));
+    }
+    start() {
+        if (this.started) {
+            return;
+        }
+        const intervalMs = parseNonNegativeIntegerEnv("CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS", this.env.CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS, DEFAULT_MEMORY_HOUSEKEEP_INTERVAL_MS);
+        if (intervalMs === 0) {
+            this.log.info({ interval_ms: intervalMs }, "Memory housekeeping scheduler disabled");
+            return;
+        }
+        const initialDelayMs = parseNonNegativeIntegerEnv("CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS", this.env.CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS, DEFAULT_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS);
+        this.started = true;
+        this.timeoutHandle = this.setTimeoutImpl(() => {
+            this.timeoutHandle = undefined;
+            this.startScheduledRun("initial_delay");
+            this.intervalHandle = this.setIntervalImpl(() => {
+                this.startScheduledRun("interval");
+            }, intervalMs);
+            this.intervalHandle?.unref?.();
+        }, initialDelayMs);
+        this.timeoutHandle?.unref?.();
+        this.log.info({ interval_ms: intervalMs, initial_delay_ms: initialDelayMs }, "Memory housekeeping scheduler started");
+    }
+    async stop() {
+        if (this.timeoutHandle) {
+            this.clearTimeoutImpl(this.timeoutHandle);
+            this.timeoutHandle = undefined;
+        }
+        if (this.intervalHandle) {
+            this.clearIntervalImpl(this.intervalHandle);
+            this.intervalHandle = undefined;
+        }
+        this.started = false;
+        await this.activeRun;
+    }
+    startScheduledRun(trigger) {
+        const run = this.runScheduledHousekeeping(trigger);
+        const tracked = run.finally(() => {
+            if (this.activeRun === tracked) {
+                this.activeRun = undefined;
+            }
+        });
+        this.activeRun = tracked;
+        void this.activeRun;
+    }
+    async runScheduledHousekeeping(trigger) {
+        if (this.running || isHousekeepingInFlight()) {
+            this.log.warn({ trigger }, "Memory housekeeping run skipped because a previous run is still active");
+            return;
+        }
+        this.running = true;
+        try {
+            const result = await this.runHousekeepingImpl({ allScopes: true });
+            if (isHousekeepingRunResult(result)) {
+                if (isContentionResult(result)) {
+                    this.log.warn({
+                        trigger,
+                        scope_ids: result.scopeIds,
+                        summaries: result.summaries,
+                    }, "Memory housekeeping run skipped because a previous run is still active");
+                    return;
+                }
+                this.log.info({
+                    trigger,
+                    scope_ids: result.scopeIds,
+                    summaries: result.summaries,
+                    pass_counts: toPassCounts(result),
+                    total_examined: result.totalExamined,
+                    total_modified: result.totalModified,
+                    duration_ms: result.durationMs,
+                }, "Memory housekeeping scheduled run complete");
+            }
+            else {
+                this.log.info({ trigger }, "Memory housekeeping scheduled run complete");
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (this.log.error) {
+                this.log.error({ trigger, err: message }, "Memory housekeeping scheduled run failed");
+            }
+            else {
+                this.log.warn({ trigger, err: message }, "Memory housekeeping scheduled run failed");
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}
+function isContentionResult(result) {
+    return result.summaries.some((summary) => (summary.pass === "runHousekeeping"
+        && summary.errors.some((error) => /already in flight/i.test(error))));
+}
+function isHousekeepingRunResult(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return Array.isArray(candidate.scopeIds)
+        && Array.isArray(candidate.summaries)
+        && typeof candidate.totalExamined === "number"
+        && typeof candidate.totalModified === "number"
+        && typeof candidate.durationMs === "number";
+}
+//# sourceMappingURL=housekeeping-scheduler.js.map

package/dist/memory/housekeeping-scheduler.test.js

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+async function loadSchedulerModule() {
+    return await import(new URL(`./housekeeping-scheduler.js?cachebust=${Date.now()}-${Math.random()}`, import.meta.url).href);
+}
+function createTimers() {
+    let nextId = 1;
+    const timeouts = [];
+    const intervals = [];
+    return {
+        timeouts,
+        intervals,
+        setTimeoutImpl(callback, delayMs) {
+            const handle = { kind: "timeout", id: nextId++, unref() { } };
+            timeouts.push({ handle, callback, delayMs, cleared: false });
+            return handle;
+        },
+        clearTimeoutImpl(handle) {
+            const entry = timeouts.find((item) => item.handle === handle);
+            if (entry)
+                entry.cleared = true;
+        },
+        setIntervalImpl(callback, delayMs) {
+            const handle = { kind: "interval", id: nextId++, unref() { } };
+            intervals.push({ handle, callback, delayMs, cleared: false });
+            return handle;
+        },
+        clearIntervalImpl(handle) {
+            const entry = intervals.find((item) => item.handle === handle);
+            if (entry)
+                entry.cleared = true;
+        },
+    };
+}
+test("MemoryHousekeepingScheduler registers with the default 6h interval when env is unset", async () => {
+    const schedulerModule = await loadSchedulerModule();
+    const timers = createTimers();
+    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
+        env: {},
+        runHousekeeping: () => ({ scopeIds: [], summaries: [], totalExamined: 0, totalModified: 0, durationMs: 0 }),
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    scheduler.start();
+    timers.timeouts[0]?.callback();
+    assert.equal(schedulerModule.DEFAULT_MEMORY_HOUSEKEEP_INTERVAL_MS, 21_600_000);
+    assert.equal(timers.intervals.length, 1);
+    assert.equal(timers.intervals[0]?.delayMs, 21_600_000);
+});
+test("MemoryHousekeepingScheduler is disabled when CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS is 0", async () => {
+    const schedulerModule = await loadSchedulerModule();
+    const timers = createTimers();
+    let runs = 0;
+    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
+        env: { CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS: "0" },
+        runHousekeeping: () => {
+            runs += 1;
+        },
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    scheduler.start();
+    assert.equal(timers.timeouts.length, 0);
+    assert.equal(timers.intervals.length, 0);
+    assert.equal(runs, 0);
+});
+test("MemoryHousekeepingScheduler waits for the initial delay before the first run", async () => {
+    const schedulerModule = await loadSchedulerModule();
+    const timers = createTimers();
+    let runs = 0;
+    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
+        env: {},
+        runHousekeeping: () => {
+            runs += 1;
+        },
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    scheduler.start();
+    assert.equal(schedulerModule.DEFAULT_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS, 300_000);
+    assert.equal(timers.timeouts.length, 1);
+    assert.equal(timers.timeouts[0]?.delayMs, 300_000);
+    assert.equal(runs, 0);
+    timers.timeouts[0]?.callback();
+    await Promise.resolve();
+    assert.equal(runs, 1);
+});
+test("MemoryHousekeepingScheduler does not overlap runs when an interval fires during an active run", async () => {
+    const schedulerModule = await loadSchedulerModule();
+    const timers = createTimers();
+    const warnings = [];
+    let runs = 0;
+    let releaseRun;
+    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
+        env: {
+            CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS: "1",
+            CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS: "2",
+        },
+        runHousekeeping: () => {
+            runs += 1;
+            return new Promise((resolve) => {
+                releaseRun = resolve;
+            });
+        },
+        log: {
+            info: () => { },
+            warn: (_obj, msg) => warnings.push(msg),
+        },
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    scheduler.start();
+    timers.timeouts[0]?.callback();
+    await Promise.resolve();
+    timers.intervals[0]?.callback();
+    await Promise.resolve();
+    assert.equal(runs, 1);
+    assert.ok(warnings.some((entry) => entry.includes("Memory housekeeping run skipped")));
+    releaseRun?.();
+    await Promise.resolve();
+    timers.intervals[0]?.callback();
+    await Promise.resolve();
+    assert.equal(runs, 2);
+});
+test("MemoryHousekeepingScheduler stop clears pending initial-delay and active interval timers", async () => {
+    const schedulerModule = await loadSchedulerModule();
+    const timers = createTimers();
+    const beforeInitialRun = new schedulerModule.MemoryHousekeepingScheduler({
+        env: {},
+        runHousekeeping: () => { },
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    beforeInitialRun.start();
+    await beforeInitialRun.stop();
+    assert.equal(timers.timeouts[0]?.cleared, true);
+    const afterInitialRun = new schedulerModule.MemoryHousekeepingScheduler({
+        env: {},
+        runHousekeeping: () => { },
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    afterInitialRun.start();
+    timers.timeouts[1]?.callback();
+    await afterInitialRun.stop();
+    assert.equal(timers.intervals[0]?.cleared, true);
+});
+test("MemoryHousekeepingScheduler stop waits for an in-flight run to finish without aborting it", async () => {
+    const schedulerModule = await loadSchedulerModule();
+    const timers = createTimers();
+    let releaseRun;
+    let stopResolved = false;
+    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
+        env: {},
+        runHousekeeping: () => new Promise((resolve) => {
+            releaseRun = resolve;
+        }),
+        setTimeoutImpl: timers.setTimeoutImpl,
+        clearTimeoutImpl: timers.clearTimeoutImpl,
+        setIntervalImpl: timers.setIntervalImpl,
+        clearIntervalImpl: timers.clearIntervalImpl,
+    });
+    scheduler.start();
+    timers.timeouts[0]?.callback();
+    await Promise.resolve();
+    const stopped = scheduler.stop().then(() => {
+        stopResolved = true;
+    });
+    await Promise.resolve();
+    assert.equal(stopResolved, false);
+    releaseRun?.();
+    await stopped;
+    assert.equal(stopResolved, true);
+});
+//# sourceMappingURL=housekeeping-scheduler.test.js.map

package/dist/memory/index.js

@@ -1,3 +1,4 @@
+export { completeActionItem, dropActionItem, getActionItem, listActionItems, recordActionItem, snoozeActionItem, } from "./action-items.js";
 export { getActiveScope, inferScopeFromText, setActiveScope } from "./active-scope.js";
 export { recordDecision, getDecision, listDecisions, supersedeDecision } from "./decisions.js";
 export { getEntity, findEntityByName, listEntities, upsertEntity } from "./entities.js";

package/dist/memory/recall.js

@@ -169,6 +169,63 @@ function recallEntityHits(query, scopeId, options = {}) {
         snippet: `${row.name}${row.summary ? ` — ${row.summary}` : ""}`,
     }));
 }
+function recallActionItemHits(query, scopeId, options = {}) {
+    if (isFts5Available()) {
+        const ftsQuery = quoteFts5QueryTerms(query);
+        const rows = getDb().prepare(`
+      SELECT
+        a.id,
+        a.scope_id,
+        s.slug AS scope,
+        a.title,
+        a.detail,
+        a.tier,
+        -bm25(mem_action_items_fts) * CASE WHEN a.tier = 'hot' THEN ? ELSE 1 END AS score,
+        snippet(mem_action_items_fts, 0, '[', ']', '…', 8) || COALESCE(' — ' ||
+          snippet(mem_action_items_fts, 1, '[', ']', '…', 12), '') AS snippet
+      FROM mem_action_items a
+      JOIN mem_scopes s ON s.id = a.scope_id
+      JOIN mem_action_items_fts ON mem_action_items_fts.rowid = a.id
+      WHERE mem_action_items_fts MATCH ?
+        AND (? IS NULL OR a.scope_id = ?)
+        AND (? = 1 OR a.tier != 'cold')
+        AND a.status IN ('open', 'snoozed')
+      ORDER BY score DESC, a.id DESC
+    `).all(config.memoryHotRecallBoost, ftsQuery, scopeId ?? null, scopeId ?? null, options.includeCold ? 1 : 0);
+        return rows.map((row) => ({
+            kind: "action_item",
+            id: row.id,
+            scopeId: row.scope_id,
+            scope: row.scope,
+            content: `${row.title}${row.detail ? ` — ${row.detail}` : ""}`,
+            score: row.score,
+            snippet: row.snippet ?? `${row.title}${row.detail ? ` — ${row.detail}` : ""}`,
+        }));
+    }
+    const pattern = `%${query}%`;
+    const rows = getDb().prepare(`
+    SELECT a.id, a.scope_id, s.slug AS scope, a.title, a.detail, a.tier
+    FROM mem_action_items a
+    JOIN mem_scopes s ON s.id = a.scope_id
+    WHERE (? IS NULL OR a.scope_id = ?)
+      AND (? = 1 OR a.tier != 'cold')
+      AND a.status IN ('open', 'snoozed')
+      AND (a.title LIKE ? OR COALESCE(a.detail, '') LIKE ?)
+    ORDER BY
+      CASE WHEN a.due_at IS NULL THEN 1 ELSE 0 END ASC,
+      datetime(a.due_at) ASC,
+      a.id DESC
+  `).all(scopeId ?? null, scopeId ?? null, options.includeCold ? 1 : 0, pattern, pattern);
+    return rows.map((row) => ({
+        kind: "action_item",
+        id: row.id,
+        scopeId: row.scope_id,
+        scope: row.scope,
+        content: `${row.title}${row.detail ? ` — ${row.detail}` : ""}`,
+        score: row.tier === "hot" ? config.memoryHotRecallBoost : 1,
+        snippet: `${row.title}${row.detail ? ` — ${row.detail}` : ""}`,
+    }));
+}
 export function recall(input) {
     const activeScope = getActiveScope();
     const effectiveScopeId = input.scope_id ?? activeScope?.id;
@@ -180,6 +237,7 @@ export function recall(input) {
         ...(requestedKinds.has("observation") ? recallObservationHits(input.query, effectiveScopeId, input) : []),
         ...(requestedKinds.has("decision") ? recallDecisionHits(input.query, effectiveScopeId, input) : []),
         ...(requestedKinds.has("entity") ? recallEntityHits(input.query, effectiveScopeId, input) : []),
+        ...(requestedKinds.has("action_item") ? recallActionItemHits(input.query, effectiveScopeId, input) : []),
     ]
         .sort((a, b) => {
         if (b.score !== a.score)
@@ -193,6 +251,7 @@ export function recall(input) {
             observation: "mem_observations",
             decision: "mem_decisions",
             entity: "mem_entities",
+            action_item: "mem_action_items",
         };
         for (const kind of Object.keys(tables)) {
             const ids = hits.filter((hit) => hit.kind === kind).map((hit) => hit.id);

package/dist/memory/recall.test.js

@@ -96,6 +96,33 @@ test("recall returns active-scope hot-tier entries before ranked FTS hits and re
     });
     assert.equal(limited.hits.length, 1);
 });
+test("recall can opt into action item hits without adding them to default kind searches", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const recordActionItem = getFunction(memoryModule, "recordActionItem");
+    const recall = getFunction(memoryModule, "recall");
+    const chapterhouse = getScope("chapterhouse");
+    assert.ok(chapterhouse);
+    const actionItem = recordActionItem({
+        scope_id: chapterhouse.id,
+        title: "Bellonda disk alert",
+        detail: "Next time disk usage exceeds 85 percent, notify infra.",
+        source: "test",
+    });
+    const defaults = recall({ query: "Bellonda disk alert", scope_id: chapterhouse.id, limit: 10 });
+    assert.equal(defaults.hits.some((hit) => hit.kind === "action_item" && hit.id === actionItem.id), false);
+    const actionOnly = recall({
+        query: "Bellonda disk alert",
+        scope_id: chapterhouse.id,
+        kinds: ["action_item"],
+        limit: 10,
+    });
+    assert.equal(actionOnly.hits.length, 1);
+    assert.equal(actionOnly.hits[0]?.kind, "action_item");
+    assert.equal(actionOnly.hits[0]?.id, actionItem.id);
+    assert.match(actionOnly.hits[0]?.content ?? "", /Bellonda disk alert/);
+});
 test("recall excludes superseded and archived rows by default with opt-in inclusion", async () => {
     const { dbModule, memoryModule } = await loadModules();
     const db = dbModule.getDb();

package/dist/memory/tiering.js

@@ -6,6 +6,7 @@ const TABLES = {
     observation: "mem_observations",
     decision: "mem_decisions",
     entity: "mem_entities",
+    action_item: "mem_action_items",
 };
 function dbTable(table) {
     return TABLES[table];
@@ -71,8 +72,9 @@ export function tieringPass(scopeId) {
       SELECT
         (SELECT COUNT(*) FROM mem_observations WHERE scope_id = ?) AS observations,
         (SELECT COUNT(*) FROM mem_decisions WHERE scope_id = ?) AS decisions,
-        (SELECT COUNT(*) FROM mem_entities WHERE scope_id = ?) AS entities
-    `).get(scopeId, scopeId, scopeId);
+        (SELECT COUNT(*) FROM mem_entities WHERE scope_id = ?) AS entities,
+        (SELECT COUNT(*) FROM mem_action_items WHERE scope_id = ?) AS action_items
+    `).get(scopeId, scopeId, scopeId, scopeId);
         let modified = 0;
         const tx = db.transaction(() => {
             modified += updateTier(`
@@ -163,6 +165,34 @@ export function tieringPass(scopeId) {
           AND superseded_by IS NULL
           AND last_recalled_at IS NULL
           AND datetime(decided_at) < datetime('now', ?)
+      `, [scopeId, `-${config.memoryHotAgeDays} days`]);
+            modified += updateTier(`
+        UPDATE mem_action_items
+        SET tier = 'cold', tier_reason = 'resolved action item'
+        WHERE scope_id = ?
+          AND tier != 'cold'
+          AND tier_pinned_at IS NULL
+          AND status IN ('done', 'dropped')
+      `, [scopeId]);
+            modified += updateTier(`
+        UPDATE mem_action_items
+        SET tier = 'hot', tier_reason = 'open action item due soon'
+        WHERE scope_id = ?
+          AND tier != 'hot'
+          AND tier_pinned_at IS NULL
+          AND status = 'open'
+          AND due_at IS NOT NULL
+          AND datetime(due_at) <= datetime('now', '+7 days')
+      `, [scopeId]);
+            modified += updateTier(`
+        UPDATE mem_action_items
+        SET tier = 'warm', tier_reason = 'hot age threshold without recall'
+        WHERE scope_id = ?
+          AND tier = 'hot'
+          AND tier_pinned_at IS NULL
+          AND status = 'open'
+          AND last_recalled_at IS NULL
+          AND datetime(created_at) < datetime('now', ?)
       `, [scopeId, `-${config.memoryHotAgeDays} days`]);
             modified += updateTier(`
         UPDATE mem_observations
@@ -184,7 +214,7 @@ export function tieringPass(scopeId) {
       `, [scopeId]);
         });
         tx();
-        return passSummary("tieringPass", counts.observations + counts.decisions + counts.entities, modified);
+        return passSummary("tieringPass", counts.observations + counts.decisions + counts.entities + counts.action_items, modified);
     }
     catch (error) {
         return passSummary("tieringPass", 0, 0, [error instanceof Error ? error.message : String(error)]);