@oyasmi/pipiclaw 0.6.3 → 0.6.5

package/dist/memory/lifecycle.js

@@ -1,23 +1,17 @@
 import * as log from "../log.js";
-import { runBackgroundMaintenance, runInlineConsolidation, } from "./consolidation.js";
+import { getDefaultChannelMemoryQueue } from "./channel-maintenance-queue.js";
+import { runInlineConsolidation, } from "./consolidation.js";
+import { appendMemoryReviewLog } from "./review-log.js";
 import { updateChannelSessionMemory } from "./session.js";
-const IDLE_CONSOLIDATION_DELAY_MS = 60_000;
 export class MemoryLifecycle {
     constructor(options) {
         this.options = options;
-        this.durableMemoryQueue = Promise.resolve();
         this.sessionRefreshQueue = Promise.resolve();
-        this.turnsSinceSessionUpdate = 0;
-        this.toolCallsSinceSessionUpdate = 0;
-        this.thresholdFailureBackoffTurnsRemaining = 0;
-        this.thresholdRefreshQueued = false;
-        this.sessionRefreshRunning = false;
         this.durableDirty = false;
         this.durableRevision = 0;
         this.lastAssistantTurnRevision = 0;
         this.lastDurableConsolidationRevision = 0;
-        this.idleConsolidationTimer = null;
-        this.idleConsolidationQueued = false;
+        this.channelMemoryQueue = options.channelMemoryQueue ?? getDefaultChannelMemoryQueue();
     }
     buildRunOptions(messages, sessionEntries) {
         return {
@@ -45,36 +39,20 @@ export class MemoryLifecycle {
         };
     }
     noteUserTurnStarted() {
-        this.clearIdleConsolidationTimer();
+        this.recordActivity("user-turn-started");
     }
     noteToolCall() {
         this.durableDirty = true;
         this.durableRevision++;
-        this.toolCallsSinceSessionUpdate++;
-        this.clearIdleConsolidationTimer();
+        this.recordActivity("tool-call");
     }
     noteCompletedAssistantTurn() {
         this.durableDirty = true;
         this.durableRevision++;
         this.lastAssistantTurnRevision = this.durableRevision;
-        const settings = this.options.getSessionMemorySettings();
-        if (settings.enabled) {
-            this.turnsSinceSessionUpdate++;
-            let canTriggerThresholdRefresh = true;
-            if (this.thresholdFailureBackoffTurnsRemaining > 0) {
-                this.thresholdFailureBackoffTurnsRemaining--;
-                canTriggerThresholdRefresh = this.thresholdFailureBackoffTurnsRemaining === 0;
-            }
-            if (canTriggerThresholdRefresh &&
-                (this.turnsSinceSessionUpdate >= settings.minTurnsBetweenUpdate ||
-                    this.toolCallsSinceSessionUpdate >= settings.minToolCallsBetweenUpdate)) {
-                this.requestThresholdSessionRefresh();
-            }
-        }
-        this.scheduleIdleConsolidation();
+        this.recordActivity("assistant-turn-completed");
     }
     async flushForShutdown() {
-        this.clearIdleConsolidationTimer();
         await this.runDurableMemoryJobSerial(async () => {
             if (!this.hasPendingAssistantSnapshot()) {
                 return;
@@ -86,13 +64,6 @@ export class MemoryLifecycle {
             await this.runPreflightConsolidationNow("shutdown", messageSnapshot, sessionEntrySnapshot, revisionSnapshot, settings);
         });
     }
-    clearIdleConsolidationTimer() {
-        if (!this.idleConsolidationTimer) {
-            return;
-        }
-        clearTimeout(this.idleConsolidationTimer);
-        this.idleConsolidationTimer = null;
-    }
     shouldForceRefreshFor(reason, settings) {
         if (!settings.enabled) {
             return false;
@@ -111,7 +82,6 @@ export class MemoryLifecycle {
             return false;
         }
         const { reason } = request;
-        this.sessionRefreshRunning = true;
         try {
             await updateChannelSessionMemory({
                 channelDir: this.options.channelDir,
@@ -120,23 +90,14 @@ export class MemoryLifecycle {
                 resolveApiKey: this.options.resolveApiKey,
                 timeoutMs: settings.timeoutMs,
             });
-            this.turnsSinceSessionUpdate = 0;
-            this.toolCallsSinceSessionUpdate = 0;
-            this.thresholdFailureBackoffTurnsRemaining = 0;
             log.logInfo(`[${this.options.channelId}] Session memory updated (${reason})`);
             return true;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            if (reason === "threshold") {
-                this.thresholdFailureBackoffTurnsRemaining = Math.max(0, settings.failureBackoffTurns);
-            }
             log.logWarning(`[${this.options.channelId}] Session memory update failed (${reason})`, message);
             return false;
         }
-        finally {
-            this.sessionRefreshRunning = false;
-        }
     }
     runSessionRefreshSerial(request) {
         const run = async () => this.refreshSessionMemory(request);
@@ -144,25 +105,8 @@ export class MemoryLifecycle {
         this.sessionRefreshQueue = resultPromise.then(() => undefined, () => undefined);
         return resultPromise;
     }
-    requestThresholdSessionRefresh() {
-        if (this.thresholdRefreshQueued || this.sessionRefreshRunning) {
-            return;
-        }
-        this.thresholdRefreshQueued = true;
-        void this.runSessionRefreshSerial({ reason: "threshold" }).finally(() => {
-            this.thresholdRefreshQueued = false;
-        });
-    }
     runDurableMemoryJobSerial(job) {
-        const resultPromise = this.durableMemoryQueue.then(job, job);
-        this.durableMemoryQueue = resultPromise.then(() => undefined, () => undefined);
-        return resultPromise;
-    }
-    enqueueDurableMemoryJob(job, failureMessage) {
-        void this.runDurableMemoryJobSerial(job).catch((error) => {
-            const message = error instanceof Error ? error.message : String(error);
-            log.logWarning(failureMessage, message);
-        });
+        return this.channelMemoryQueue.run(this.options.channelId, job);
     }
     hasPendingAssistantSnapshot() {
         return this.durableDirty && this.lastAssistantTurnRevision > this.lastDurableConsolidationRevision;
@@ -178,40 +122,41 @@ export class MemoryLifecycle {
         }
         log.logInfo(`[${this.options.channelId}] Memory consolidation finished (${reason}): memory entries=${result.appendedMemoryEntries}, history=${result.appendedHistoryBlock ? "yes" : "no"}`);
     }
-    scheduleIdleConsolidation() {
-        this.clearIdleConsolidationTimer();
-        if (!this.hasPendingAssistantSnapshot() || this.idleConsolidationQueued) {
+    async appendReviewLog(entry) {
+        try {
+            await appendMemoryReviewLog(this.options.channelDir, {
+                timestamp: new Date().toISOString(),
+                channelId: this.options.channelId,
+                ...entry,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log.logWarning(`[${this.options.channelId}] Failed to write memory review log`, message);
+        }
+    }
+    async recordConsolidationReview(reason, result) {
+        if (result.skipped) {
+            await this.appendReviewLog({
+                reason,
+                skipped: [{ target: "consolidation", reason: "no meaningful snapshot" }],
+            });
             return;
         }
-        this.idleConsolidationTimer = setTimeout(() => {
-            this.idleConsolidationTimer = null;
-            if (!this.hasPendingAssistantSnapshot() || this.idleConsolidationQueued) {
-                return;
-            }
-            this.idleConsolidationQueued = true;
-            const messageSnapshot = [...this.options.getMessages()];
-            const sessionEntrySnapshot = [...this.options.getSessionEntries()];
-            const revisionSnapshot = this.durableRevision;
-            this.enqueueDurableMemoryJob(async () => {
-                try {
-                    log.logInfo(`[${this.options.channelId}] Memory consolidation starting (idle)`);
-                    const result = await runInlineConsolidation(this.buildRunOptions(messageSnapshot, sessionEntrySnapshot));
-                    this.markDurableConsolidationCheckpoint(revisionSnapshot);
-                    this.logConsolidationResult("idle", result);
-                    const maintenance = await runBackgroundMaintenance(this.buildRunOptions(messageSnapshot, sessionEntrySnapshot));
-                    this.logBackgroundResult(maintenance);
-                }
-                finally {
-                    this.idleConsolidationQueued = false;
-                    if (this.durableDirty) {
-                        this.scheduleIdleConsolidation();
-                    }
-                }
-            }, `[${this.options.channelId}] Memory consolidation failed (idle)`);
-        }, IDLE_CONSOLIDATION_DELAY_MS);
+        const actions = [];
+        const skipped = [];
+        if (result.appendedMemoryEntries > 0) {
+            actions.push({ target: "MEMORY.md", action: "append", entries: result.appendedMemoryEntries });
+        }
+        if (result.appendedHistoryBlock) {
+            actions.push({ target: "HISTORY.md", action: "append" });
+        }
+        else if (reason === "idle") {
+            skipped.push({ target: "HISTORY.md", reason: "idle does not write HISTORY.md" });
+        }
+        await this.appendReviewLog({ reason, actions, skipped });
     }
     async runPreflightConsolidation(reason, messages, sessionEntries) {
-        this.clearIdleConsolidationTimer();
         const messageSnapshot = [...(messages ?? this.options.getMessages())];
         const sessionEntrySnapshot = sessionEntries ? [...sessionEntries] : [...this.options.getSessionEntries()];
         const revisionSnapshot = this.durableRevision;
@@ -229,20 +174,29 @@ export class MemoryLifecycle {
         }
         try {
             log.logInfo(`[${this.options.channelId}] Memory consolidation starting (${reason})`);
-            const result = await runInlineConsolidation(this.buildRunOptions(messageSnapshot, sessionEntrySnapshot));
+            const result = await runInlineConsolidation({
+                ...this.buildRunOptions(messageSnapshot, sessionEntrySnapshot),
+                mode: "boundary",
+            });
             this.markDurableConsolidationCheckpoint(revisionSnapshot);
             this.logConsolidationResult(reason, result);
+            await this.recordConsolidationReview(reason, result);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             log.logWarning(`[${this.options.channelId}] Memory consolidation failed (${reason})`, message);
+            await this.appendReviewLog({
+                reason,
+                error: message,
+                skipped: [{ target: "consolidation", reason: "failed" }],
+            });
         }
     }
     async handleSessionBeforeCompact(event) {
         await this.runPreflightConsolidation("compaction", event.preparation.messagesToSummarize);
     }
     handleSessionCompact(_event) {
-        this.enqueueBackgroundMaintenance();
+        this.recordActivity("boundary");
     }
     async handleSessionBeforeSwitch(event) {
         if (event.reason !== "new") {
@@ -254,22 +208,23 @@ export class MemoryLifecycle {
         if (event.reason !== "new") {
             return;
         }
-        this.enqueueBackgroundMaintenance();
-    }
-    enqueueBackgroundMaintenance() {
-        this.enqueueDurableMemoryJob(async () => {
-            const result = await runBackgroundMaintenance(this.buildRunOptions([], []));
-            this.logBackgroundResult(result);
-        }, `[${this.options.channelId}] Background memory maintenance failed`);
+        this.recordActivity("boundary");
     }
-    logBackgroundResult(result) {
-        if (!result.cleanedMemory && !result.foldedHistory) {
-            return;
+    recordActivity(kind) {
+        const now = new Date();
+        const latestSessionEntryId = this.options.getSessionEntries().at(-1)?.id;
+        const event = {
+            kind,
+            channelId: this.options.channelId,
+            timestamp: now.toISOString(),
+            latestSessionEntryId,
+        };
+        try {
+            void this.options.recordMemoryActivity?.(event);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log.logWarning(`[${this.options.channelId}] Failed to record memory activity`, message);
         }
-        const details = [
-            `memory cleanup=${result.cleanedMemory ? "yes" : "no"}`,
-            `history fold=${result.foldedHistory ? "yes" : "no"}`,
-        ].join(", ");
-        log.logInfo(`[${this.options.channelId}] Background memory maintenance complete: ${details}`);
     }
 }

package/dist/memory/maintenance-gates.d.ts

@@ -0,0 +1,56 @@
+import type { PipiclawMemoryGrowthSettings, PipiclawMemoryMaintenanceSettings, PipiclawSessionMemorySettings } from "../settings.js";
+import type { MemoryMaintenanceState } from "./maintenance-state.js";
+export type MaintenanceJobKind = "session-refresh" | "durable-consolidation" | "growth-review" | "structural-maintenance";
+export interface MaintenanceGateDecision {
+    allowed: boolean;
+    skipReason?: string;
+    jobKind: MaintenanceJobKind;
+}
+export interface SessionRefreshGateInput {
+    now: Date;
+    state: MemoryMaintenanceState;
+    sessionMemory: PipiclawSessionMemorySettings;
+    maintenance: PipiclawMemoryMaintenanceSettings;
+    channelActive: boolean;
+    hasNewSessionEntry: boolean;
+    hasMeaningfulMaterial: boolean;
+}
+export interface DurableConsolidationGateInput {
+    now: Date;
+    state: MemoryMaintenanceState;
+    maintenance: PipiclawMemoryMaintenanceSettings;
+    channelActive: boolean;
+    hasNewEntry: boolean;
+    hasMeaningfulExchange: boolean;
+    batchSize: number;
+    minBatchSize?: number;
+    coveredByGrowthReview?: boolean;
+}
+export interface GrowthReviewGateInput {
+    now: Date;
+    state: MemoryMaintenanceState;
+    memoryGrowth: PipiclawMemoryGrowthSettings;
+    maintenance: PipiclawMemoryMaintenanceSettings;
+    channelActive: boolean;
+    hasNewEntry: boolean;
+    hasMeaningfulMaterial: boolean;
+    hasPromotionSignal: boolean;
+}
+export interface StructuralMaintenanceGateInput {
+    now: Date;
+    state: MemoryMaintenanceState;
+    maintenance: PipiclawMemoryMaintenanceSettings;
+    channelActive: boolean;
+    memoryCleanupNeeded: boolean;
+    historyFoldingNeeded: boolean;
+    hasMemoryContent: boolean;
+    hasHistoryContent: boolean;
+}
+export interface StructuralMaintenanceGateDecision extends MaintenanceGateDecision {
+    runMemoryCleanup: boolean;
+    runHistoryFolding: boolean;
+}
+export declare function shouldRunSessionRefresh(input: SessionRefreshGateInput): MaintenanceGateDecision;
+export declare function shouldRunDurableConsolidation(input: DurableConsolidationGateInput): MaintenanceGateDecision;
+export declare function shouldRunGrowthReview(input: GrowthReviewGateInput): MaintenanceGateDecision;
+export declare function shouldRunStructuralMaintenance(input: StructuralMaintenanceGateInput): StructuralMaintenanceGateDecision;

package/dist/memory/maintenance-gates.js

@@ -0,0 +1,161 @@
+function deny(jobKind, skipReason) {
+    return { allowed: false, jobKind, skipReason };
+}
+function allow(jobKind) {
+    return { allowed: true, jobKind };
+}
+function parseTime(value) {
+    if (!value) {
+        return null;
+    }
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? time : null;
+}
+function isBeforeOptional(now, value) {
+    const time = parseTime(value ?? undefined);
+    return time !== null && now.getTime() < time;
+}
+function hasIntervalElapsed(now, lastRunAt, intervalMs) {
+    const lastRunTime = parseTime(lastRunAt);
+    return lastRunTime === null || now.getTime() - lastRunTime >= intervalMs;
+}
+function minutesToMs(minutes) {
+    return Math.max(0, minutes) * 60_000;
+}
+function hoursToMs(hours) {
+    return Math.max(0, hours) * 3_600_000;
+}
+function sessionRefreshThresholdMet(state, settings) {
+    return (state.turnsSinceSessionRefresh >= settings.minTurnsBetweenUpdate ||
+        state.toolCallsSinceSessionRefresh >= settings.minToolCallsBetweenUpdate);
+}
+function growthReviewThresholdMet(state, settings) {
+    return (state.turnsSinceGrowthReview >= settings.minTurnsBetweenReview ||
+        state.toolCallsSinceGrowthReview >= settings.minToolCallsBetweenReview);
+}
+export function shouldRunSessionRefresh(input) {
+    if (!input.sessionMemory.enabled) {
+        return deny("session-refresh", "disabled");
+    }
+    if (!input.state.dirty) {
+        return deny("session-refresh", "clean");
+    }
+    if (isBeforeOptional(input.now, input.state.eligibleAfter)) {
+        return deny("session-refresh", "not-idle-yet");
+    }
+    if (input.channelActive) {
+        return deny("session-refresh", "channel-active");
+    }
+    if (isBeforeOptional(input.now, input.state.failureBackoffUntil)) {
+        return deny("session-refresh", "backoff-active");
+    }
+    if (!hasIntervalElapsed(input.now, input.state.lastSessionRefreshAt, minutesToMs(input.maintenance.sessionRefreshIntervalMinutes))) {
+        return deny("session-refresh", "interval-not-elapsed");
+    }
+    if (!sessionRefreshThresholdMet(input.state, input.sessionMemory)) {
+        return deny("session-refresh", "threshold-not-met");
+    }
+    if (!input.hasNewSessionEntry) {
+        return deny("session-refresh", "no-new-session-entry");
+    }
+    if (!input.hasMeaningfulMaterial) {
+        return deny("session-refresh", "no-meaningful-material");
+    }
+    return allow("session-refresh");
+}
+export function shouldRunDurableConsolidation(input) {
+    if (!input.state.dirty) {
+        return deny("durable-consolidation", "clean");
+    }
+    if (isBeforeOptional(input.now, input.state.eligibleAfter)) {
+        return deny("durable-consolidation", "not-idle-yet");
+    }
+    if (input.channelActive) {
+        return deny("durable-consolidation", "channel-active");
+    }
+    if (!hasIntervalElapsed(input.now, input.state.lastDurableConsolidationAt, minutesToMs(input.maintenance.durableConsolidationIntervalMinutes))) {
+        return deny("durable-consolidation", "interval-not-elapsed");
+    }
+    if (isBeforeOptional(input.now, input.state.failureBackoffUntil)) {
+        return deny("durable-consolidation", "backoff-active");
+    }
+    if (!input.hasNewEntry) {
+        return deny("durable-consolidation", "no-new-entry");
+    }
+    if (!input.hasMeaningfulExchange) {
+        return deny("durable-consolidation", "no-meaningful-exchange");
+    }
+    if (input.coveredByGrowthReview) {
+        return deny("durable-consolidation", "covered-by-growth-review");
+    }
+    if (input.batchSize < (input.minBatchSize ?? 2)) {
+        return deny("durable-consolidation", "batch-threshold-not-met");
+    }
+    return allow("durable-consolidation");
+}
+export function shouldRunGrowthReview(input) {
+    if (!input.memoryGrowth.postTurnReviewEnabled) {
+        return deny("growth-review", "disabled");
+    }
+    if (!input.state.dirty) {
+        return deny("growth-review", "clean");
+    }
+    if (isBeforeOptional(input.now, input.state.eligibleAfter)) {
+        return deny("growth-review", "not-idle-yet");
+    }
+    if (input.channelActive) {
+        return deny("growth-review", "channel-active");
+    }
+    if (!hasIntervalElapsed(input.now, input.state.lastGrowthReviewAt, minutesToMs(input.maintenance.growthReviewIntervalMinutes))) {
+        return deny("growth-review", "interval-not-elapsed");
+    }
+    if (isBeforeOptional(input.now, input.state.failureBackoffUntil)) {
+        return deny("growth-review", "backoff-active");
+    }
+    if (!growthReviewThresholdMet(input.state, input.memoryGrowth)) {
+        return deny("growth-review", "threshold-not-met");
+    }
+    if (!input.hasNewEntry) {
+        return deny("growth-review", "no-new-entry");
+    }
+    if (!input.hasMeaningfulMaterial) {
+        return deny("growth-review", "no-meaningful-material");
+    }
+    if (!input.hasPromotionSignal) {
+        return deny("growth-review", "no-promotion-signal");
+    }
+    return allow("growth-review");
+}
+export function shouldRunStructuralMaintenance(input) {
+    const jobKind = "structural-maintenance";
+    const denyStructural = (skipReason) => ({
+        allowed: false,
+        jobKind,
+        skipReason,
+        runMemoryCleanup: false,
+        runHistoryFolding: false,
+    });
+    if (input.channelActive) {
+        return denyStructural("channel-active");
+    }
+    if (!hasIntervalElapsed(input.now, input.state.lastStructuralMaintenanceAt, hoursToMs(input.maintenance.structuralMaintenanceIntervalHours))) {
+        return denyStructural("interval-not-elapsed");
+    }
+    if (isBeforeOptional(input.now, input.state.failureBackoffUntil)) {
+        return denyStructural("backoff-active");
+    }
+    if (!input.hasMemoryContent && !input.hasHistoryContent) {
+        return denyStructural("empty-template-files");
+    }
+    const runMemoryCleanup = input.memoryCleanupNeeded;
+    const runHistoryFolding = input.historyFoldingNeeded;
+    if (!runMemoryCleanup && !runHistoryFolding) {
+        return denyStructural("nothing-to-maintain");
+    }
+    return {
+        allowed: true,
+        jobKind,
+        runMemoryCleanup,
+        runHistoryFolding,
+    };
+}

package/dist/memory/maintenance-jobs.d.ts

@@ -0,0 +1,52 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { Api, Model } from "@mariozechner/pi-ai";
+import type { SessionEntry } from "@mariozechner/pi-coding-agent";
+import type { PipiclawMemoryGrowthSettings, PipiclawMemoryMaintenanceSettings, PipiclawSessionMemorySettings } from "../settings.js";
+import { type ChannelMemoryQueue } from "./channel-maintenance-queue.js";
+import { type MaintenanceJobKind } from "./maintenance-gates.js";
+export interface MaintenanceJobSettings {
+    sessionMemory: PipiclawSessionMemorySettings;
+    memoryGrowth: PipiclawMemoryGrowthSettings;
+    memoryMaintenance: PipiclawMemoryMaintenanceSettings;
+}
+interface BaseMaintenanceJobInput {
+    appHomeDir: string;
+    channelId: string;
+    channelDir: string;
+    channelActive: boolean;
+    now?: Date;
+    settings: MaintenanceJobSettings;
+    model: Model<Api>;
+    resolveApiKey: (model: Model<Api>) => Promise<string>;
+    messages: AgentMessage[];
+    sessionEntries: SessionEntry[];
+    queue?: ChannelMemoryQueue;
+}
+export interface SessionRefreshJobInput extends BaseMaintenanceJobInput {
+}
+export interface DurableConsolidationJobInput extends BaseMaintenanceJobInput {
+}
+export interface GrowthReviewJobInput extends BaseMaintenanceJobInput {
+    workspaceDir: string;
+    workspacePath: string;
+    loadedSkills: Array<{
+        name: string;
+        description?: string;
+    }>;
+    emitNotice?: (notice: string) => Promise<void>;
+    refreshWorkspaceResources?: () => Promise<void>;
+}
+export interface StructuralMaintenanceJobInput extends BaseMaintenanceJobInput {
+}
+export interface MaintenanceJobResult {
+    jobKind: MaintenanceJobKind;
+    ran: boolean;
+    skipped: boolean;
+    skipReason?: string;
+    error?: string;
+}
+export declare function runSessionRefreshJob(input: SessionRefreshJobInput): Promise<MaintenanceJobResult>;
+export declare function runDurableConsolidationJob(input: DurableConsolidationJobInput): Promise<MaintenanceJobResult>;
+export declare function runGrowthReviewJob(input: GrowthReviewJobInput): Promise<MaintenanceJobResult>;
+export declare function runStructuralMaintenanceJob(input: StructuralMaintenanceJobInput): Promise<MaintenanceJobResult>;
+export {};