@oyasmi/pipiclaw 0.6.3 → 0.6.5

package/dist/memory/maintenance-jobs.js

@@ -0,0 +1,310 @@
+import { buildStandardMessages } from "../shared/type-guards.js";
+import { getDefaultChannelMemoryQueue } from "./channel-maintenance-queue.js";
+import { cleanupChannelMemory, foldChannelHistory, getStructuralMaintenanceStats, runInlineConsolidation, } from "./consolidation.js";
+import { readChannelHistory, readChannelMemory } from "./files.js";
+import { shouldRunDurableConsolidation, shouldRunGrowthReview, shouldRunSessionRefresh, shouldRunStructuralMaintenance, } from "./maintenance-gates.js";
+import { readMemoryMaintenanceState, updateMemoryMaintenanceState } from "./maintenance-state.js";
+import { runPostTurnReview } from "./post-turn-review.js";
+import { scanPromotionSignals } from "./promotion-signals.js";
+import { appendMemoryReviewLog } from "./review-log.js";
+import { updateChannelSessionMemory } from "./session.js";
+function latestEntryId(entries) {
+    return entries.at(-1)?.id;
+}
+function entriesSince(entries, lastEntryId) {
+    if (!lastEntryId) {
+        return entries;
+    }
+    const index = entries.findIndex((entry) => entry.id === lastEntryId);
+    return index >= 0 ? entries.slice(index + 1) : entries;
+}
+function messageToText(message) {
+    if (message.role === "user") {
+        return typeof message.content === "string"
+            ? message.content
+            : message.content.map((part) => (part.type === "text" ? part.text : "[image]")).join("\n");
+    }
+    if (message.role === "assistant") {
+        return message.content
+            .map((part) => (part.type === "text" ? part.text : ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+function hasMeaningfulMessages(messages) {
+    const standardMessages = buildStandardMessages(messages);
+    let userSeen = false;
+    let assistantSeen = false;
+    for (const message of standardMessages) {
+        const text = messageToText(message).trim();
+        if (!text) {
+            continue;
+        }
+        if (message.role === "user") {
+            userSeen = true;
+        }
+        if (message.role === "assistant") {
+            assistantSeen = true;
+        }
+        if (userSeen && assistantSeen) {
+            return true;
+        }
+    }
+    return false;
+}
+function renderMessagesForSignalScan(messages) {
+    return buildStandardMessages(messages).map(messageToText).join("\n");
+}
+function makeRunOptions(input) {
+    return {
+        channelDir: input.channelDir,
+        model: input.model,
+        resolveApiKey: input.resolveApiKey,
+        messages: input.messages,
+        sessionEntries: input.sessionEntries,
+    };
+}
+function backoffUntil(now, settings) {
+    return new Date(now.getTime() + Math.max(0, settings.failureBackoffMinutes) * 60_000).toISOString();
+}
+async function appendJobReviewLog(channelDir, channelId, reason, entry, now) {
+    await appendMemoryReviewLog(channelDir, {
+        timestamp: now.toISOString(),
+        channelId,
+        reason,
+        ...entry,
+    });
+}
+function skipped(jobKind, skipReason) {
+    return { jobKind, ran: false, skipped: true, skipReason };
+}
+function ran(jobKind) {
+    return { jobKind, ran: true, skipped: false };
+}
+function failed(jobKind, error) {
+    return {
+        jobKind,
+        ran: false,
+        skipped: false,
+        error: error instanceof Error ? error.message : String(error),
+    };
+}
+async function runQueued(input, job) {
+    return (input.queue ?? getDefaultChannelMemoryQueue()).run(input.channelId, job);
+}
+export async function runSessionRefreshJob(input) {
+    return runQueued(input, async () => {
+        const now = input.now ?? new Date();
+        const state = await readMemoryMaintenanceState(input.appHomeDir, input.channelId);
+        const latestId = latestEntryId(input.sessionEntries);
+        const decision = shouldRunSessionRefresh({
+            now,
+            state,
+            sessionMemory: input.settings.sessionMemory,
+            maintenance: input.settings.memoryMaintenance,
+            channelActive: input.channelActive,
+            hasNewSessionEntry: latestId !== undefined && latestId !== state.lastSessionRefreshedEntryId,
+            hasMeaningfulMaterial: hasMeaningfulMessages(input.messages),
+        });
+        if (!decision.allowed) {
+            await appendJobReviewLog(input.channelDir, input.channelId, "session-refresh-job", { skipped: [{ target: "SESSION.md", reason: decision.skipReason }] }, now);
+            return skipped(decision.jobKind, decision.skipReason ?? "skipped");
+        }
+        try {
+            await updateChannelSessionMemory({
+                channelDir: input.channelDir,
+                messages: input.messages,
+                model: input.model,
+                resolveApiKey: input.resolveApiKey,
+                timeoutMs: input.settings.sessionMemory.timeoutMs,
+            });
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                lastSessionRefreshAt: now.toISOString(),
+                turnsSinceSessionRefresh: 0,
+                toolCallsSinceSessionRefresh: 0,
+                lastSessionRefreshedEntryId: latestId ?? current.lastSessionRefreshedEntryId,
+                lastSessionEntryId: latestId ?? current.lastSessionEntryId,
+                failureBackoffUntil: null,
+            }));
+            await appendJobReviewLog(input.channelDir, input.channelId, "session-refresh-job", { actions: [{ target: "SESSION.md", action: "rewrite" }] }, now);
+            return ran("session-refresh");
+        }
+        catch (error) {
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                failureBackoffUntil: backoffUntil(now, input.settings.memoryMaintenance),
+            }));
+            const result = failed("session-refresh", error);
+            await appendJobReviewLog(input.channelDir, input.channelId, "session-refresh-job", { error: result.error, skipped: [{ target: "SESSION.md", reason: "failed" }] }, now);
+            return result;
+        }
+    });
+}
+export async function runDurableConsolidationJob(input) {
+    return runQueued(input, async () => {
+        const now = input.now ?? new Date();
+        const state = await readMemoryMaintenanceState(input.appHomeDir, input.channelId);
+        const newEntries = entriesSince(input.sessionEntries, state.lastConsolidatedEntryId);
+        const latestId = latestEntryId(input.sessionEntries);
+        const decision = shouldRunDurableConsolidation({
+            now,
+            state,
+            maintenance: input.settings.memoryMaintenance,
+            channelActive: input.channelActive,
+            hasNewEntry: newEntries.length > 0,
+            hasMeaningfulExchange: hasMeaningfulMessages(input.messages),
+            batchSize: newEntries.length,
+            coveredByGrowthReview: Boolean(latestId && state.lastReviewedEntryId === latestId),
+        });
+        if (!decision.allowed) {
+            await appendJobReviewLog(input.channelDir, input.channelId, "durable-consolidation-job", { skipped: [{ target: "consolidation", reason: decision.skipReason }] }, now);
+            return skipped(decision.jobKind, decision.skipReason ?? "skipped");
+        }
+        try {
+            const result = await runInlineConsolidation({
+                ...makeRunOptions(input),
+                mode: "idle",
+            });
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                lastDurableConsolidationAt: now.toISOString(),
+                lastConsolidatedEntryId: latestId ?? current.lastConsolidatedEntryId,
+                failureBackoffUntil: null,
+            }));
+            await appendJobReviewLog(input.channelDir, input.channelId, "durable-consolidation-job", result.skipped
+                ? { skipped: [{ target: "consolidation", reason: "no meaningful snapshot" }] }
+                : { actions: [{ target: "MEMORY.md", action: "append", entries: result.appendedMemoryEntries }] }, now);
+            return ran("durable-consolidation");
+        }
+        catch (error) {
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                failureBackoffUntil: backoffUntil(now, input.settings.memoryMaintenance),
+            }));
+            const result = failed("durable-consolidation", error);
+            await appendJobReviewLog(input.channelDir, input.channelId, "durable-consolidation-job", { error: result.error, skipped: [{ target: "consolidation", reason: "failed" }] }, now);
+            return result;
+        }
+    });
+}
+export async function runGrowthReviewJob(input) {
+    return runQueued(input, async () => {
+        const now = input.now ?? new Date();
+        const state = await readMemoryMaintenanceState(input.appHomeDir, input.channelId);
+        const newEntries = entriesSince(input.sessionEntries, state.lastReviewedEntryId);
+        const latestId = latestEntryId(input.sessionEntries);
+        const signalScan = scanPromotionSignals(renderMessagesForSignalScan(input.messages));
+        const decision = shouldRunGrowthReview({
+            now,
+            state,
+            memoryGrowth: input.settings.memoryGrowth,
+            maintenance: input.settings.memoryMaintenance,
+            channelActive: input.channelActive,
+            hasNewEntry: newEntries.length > 0,
+            hasMeaningfulMaterial: hasMeaningfulMessages(input.messages),
+            hasPromotionSignal: signalScan.hasSignal,
+        });
+        if (!decision.allowed) {
+            await appendJobReviewLog(input.channelDir, input.channelId, "growth-review-job", { skipped: [{ target: "post-turn-review", reason: decision.skipReason }] }, now);
+            return skipped(decision.jobKind, decision.skipReason ?? "skipped");
+        }
+        try {
+            const notices = [];
+            const result = await runPostTurnReview({
+                channelId: input.channelId,
+                channelDir: input.channelDir,
+                workspaceDir: input.workspaceDir,
+                workspacePath: input.workspacePath,
+                messages: input.messages,
+                model: input.model,
+                resolveApiKey: input.resolveApiKey,
+                timeoutMs: input.settings.sessionMemory.timeoutMs,
+                autoWriteChannelMemory: input.settings.memoryGrowth.autoWriteChannelMemory,
+                autoWriteWorkspaceSkills: input.settings.memoryGrowth.autoWriteWorkspaceSkills,
+                minMemoryAutoWriteConfidence: input.settings.memoryGrowth.minMemoryAutoWriteConfidence,
+                minSkillAutoWriteConfidence: input.settings.memoryGrowth.minSkillAutoWriteConfidence,
+                loadedSkills: input.loadedSkills,
+                emitNotice: async (notice) => {
+                    notices.push(notice);
+                },
+                refreshWorkspaceResources: input.refreshWorkspaceResources,
+            });
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                lastGrowthReviewAt: now.toISOString(),
+                turnsSinceGrowthReview: 0,
+                toolCallsSinceGrowthReview: 0,
+                lastReviewedEntryId: latestId ?? current.lastReviewedEntryId,
+                failureBackoffUntil: null,
+            }));
+            if (notices.length > 0) {
+                const uniqueNotices = Array.from(new Set(notices));
+                await input.emitNotice?.(uniqueNotices.join("\n"));
+            }
+            await appendJobReviewLog(input.channelDir, input.channelId, "growth-review-job", {
+                actions: result.actions,
+                skipped: result.skipped,
+            }, now);
+            return ran("growth-review");
+        }
+        catch (error) {
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                failureBackoffUntil: backoffUntil(now, input.settings.memoryMaintenance),
+            }));
+            const result = failed("growth-review", error);
+            await appendJobReviewLog(input.channelDir, input.channelId, "growth-review-job", { error: result.error, skipped: [{ target: "post-turn-review", reason: "failed" }] }, now);
+            return result;
+        }
+    });
+}
+export async function runStructuralMaintenanceJob(input) {
+    return runQueued(input, async () => {
+        const now = input.now ?? new Date();
+        const state = await readMemoryMaintenanceState(input.appHomeDir, input.channelId);
+        const [currentMemory, currentHistory] = await Promise.all([
+            readChannelMemory(input.channelDir),
+            readChannelHistory(input.channelDir),
+        ]);
+        const stats = getStructuralMaintenanceStats(currentMemory, currentHistory);
+        const decision = shouldRunStructuralMaintenance({
+            now,
+            state,
+            maintenance: input.settings.memoryMaintenance,
+            channelActive: input.channelActive,
+            ...stats,
+        });
+        if (!decision.allowed) {
+            await appendJobReviewLog(input.channelDir, input.channelId, "structural-maintenance-job", { skipped: [{ target: "structural-maintenance", reason: decision.skipReason }] }, now);
+            return skipped(decision.jobKind, decision.skipReason ?? "skipped");
+        }
+        try {
+            const options = makeRunOptions(input);
+            const cleanedMemory = decision.runMemoryCleanup ? await cleanupChannelMemory(options, currentMemory) : false;
+            const foldedHistory = decision.runHistoryFolding ? await foldChannelHistory(options, currentHistory) : false;
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                lastStructuralMaintenanceAt: now.toISOString(),
+                failureBackoffUntil: null,
+            }));
+            await appendJobReviewLog(input.channelDir, input.channelId, "structural-maintenance-job", {
+                actions: [
+                    ...(cleanedMemory ? [{ target: "MEMORY.md", action: "rewrite" }] : []),
+                    ...(foldedHistory ? [{ target: "HISTORY.md", action: "rewrite" }] : []),
+                ],
+            }, now);
+            return ran("structural-maintenance");
+        }
+        catch (error) {
+            await updateMemoryMaintenanceState(input.appHomeDir, input.channelId, (current) => ({
+                ...current,
+                failureBackoffUntil: backoffUntil(now, input.settings.memoryMaintenance),
+            }));
+            const result = failed("structural-maintenance", error);
+            await appendJobReviewLog(input.channelDir, input.channelId, "structural-maintenance-job", { error: result.error, skipped: [{ target: "structural-maintenance", reason: "failed" }] }, now);
+            return result;
+        }
+    });
+}

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

@@ -0,0 +1,33 @@
+export interface MemoryMaintenanceState {
+    channelId: string;
+    dirty: boolean;
+    lastActivityAt?: string;
+    eligibleAfter?: string;
+    lastSessionRefreshAt?: string;
+    lastDurableConsolidationAt?: string;
+    lastGrowthReviewAt?: string;
+    lastStructuralMaintenanceAt?: string;
+    turnsSinceSessionRefresh: number;
+    toolCallsSinceSessionRefresh: number;
+    turnsSinceGrowthReview: number;
+    toolCallsSinceGrowthReview: number;
+    lastSessionEntryId?: string;
+    lastSessionRefreshedEntryId?: string;
+    lastConsolidatedEntryId?: string;
+    lastReviewedEntryId?: string;
+    failureBackoffUntil?: string | null;
+}
+export type MemoryActivityKind = "user-turn-started" | "tool-call" | "assistant-turn-completed" | "boundary";
+export interface MemoryActivityEvent {
+    kind: MemoryActivityKind;
+    channelId: string;
+    timestamp: string;
+    eligibleAfter?: string;
+    latestSessionEntryId?: string;
+}
+export declare function getMemoryMaintenanceStateDir(appHomeDir: string): string;
+export declare function getMemoryMaintenanceStatePath(appHomeDir: string, channelId: string): string;
+export declare function readMemoryMaintenanceState(appHomeDir: string, channelId: string): Promise<MemoryMaintenanceState>;
+export declare function writeMemoryMaintenanceState(appHomeDir: string, state: MemoryMaintenanceState): Promise<void>;
+export declare function updateMemoryMaintenanceState(appHomeDir: string, channelId: string, update: (state: MemoryMaintenanceState) => MemoryMaintenanceState): Promise<MemoryMaintenanceState>;
+export declare function applyMemoryActivityToState(state: MemoryMaintenanceState, event: MemoryActivityEvent): MemoryMaintenanceState;

package/dist/memory/maintenance-state.js

@@ -0,0 +1,113 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as log from "../log.js";
+import { writeFileAtomically } from "../shared/atomic-file.js";
+import { createSerialQueue } from "../shared/serial-queue.js";
+const stateUpdateQueue = createSerialQueue();
+export function getMemoryMaintenanceStateDir(appHomeDir) {
+    return join(appHomeDir, "state", "memory");
+}
+export function getMemoryMaintenanceStatePath(appHomeDir, channelId) {
+    return join(getMemoryMaintenanceStateDir(appHomeDir), `${channelId}.json`);
+}
+function createDefaultState(channelId) {
+    return {
+        channelId,
+        dirty: false,
+        turnsSinceSessionRefresh: 0,
+        toolCallsSinceSessionRefresh: 0,
+        turnsSinceGrowthReview: 0,
+        toolCallsSinceGrowthReview: 0,
+        failureBackoffUntil: null,
+    };
+}
+function normalizeOptionalString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function normalizeOptionalNullableString(value) {
+    if (value === null) {
+        return null;
+    }
+    return normalizeOptionalString(value);
+}
+function normalizeCounter(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function normalizeState(channelId, value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return createDefaultState(channelId);
+    }
+    const record = value;
+    return {
+        channelId,
+        dirty: typeof record.dirty === "boolean" ? record.dirty : false,
+        lastActivityAt: normalizeOptionalString(record.lastActivityAt),
+        eligibleAfter: normalizeOptionalString(record.eligibleAfter),
+        lastSessionRefreshAt: normalizeOptionalString(record.lastSessionRefreshAt),
+        lastDurableConsolidationAt: normalizeOptionalString(record.lastDurableConsolidationAt),
+        lastGrowthReviewAt: normalizeOptionalString(record.lastGrowthReviewAt),
+        lastStructuralMaintenanceAt: normalizeOptionalString(record.lastStructuralMaintenanceAt),
+        turnsSinceSessionRefresh: normalizeCounter(record.turnsSinceSessionRefresh),
+        toolCallsSinceSessionRefresh: normalizeCounter(record.toolCallsSinceSessionRefresh),
+        turnsSinceGrowthReview: normalizeCounter(record.turnsSinceGrowthReview),
+        toolCallsSinceGrowthReview: normalizeCounter(record.toolCallsSinceGrowthReview),
+        lastSessionEntryId: normalizeOptionalString(record.lastSessionEntryId),
+        lastSessionRefreshedEntryId: normalizeOptionalString(record.lastSessionRefreshedEntryId),
+        lastConsolidatedEntryId: normalizeOptionalString(record.lastConsolidatedEntryId),
+        lastReviewedEntryId: normalizeOptionalString(record.lastReviewedEntryId),
+        failureBackoffUntil: normalizeOptionalNullableString(record.failureBackoffUntil) ?? null,
+    };
+}
+export async function readMemoryMaintenanceState(appHomeDir, channelId) {
+    const path = getMemoryMaintenanceStatePath(appHomeDir, channelId);
+    try {
+        const raw = await readFile(path, "utf-8");
+        return normalizeState(channelId, JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return createDefaultState(channelId);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        log.logWarning(`[${channelId}] Failed to read memory maintenance state; rebuilding defaults`, message);
+        return createDefaultState(channelId);
+    }
+}
+export async function writeMemoryMaintenanceState(appHomeDir, state) {
+    const path = getMemoryMaintenanceStatePath(appHomeDir, state.channelId);
+    await stateUpdateQueue.run(path, async () => {
+        await writeFileAtomically(path, `${JSON.stringify(normalizeState(state.channelId, state), null, 2)}\n`);
+    });
+}
+export async function updateMemoryMaintenanceState(appHomeDir, channelId, update) {
+    const path = getMemoryMaintenanceStatePath(appHomeDir, channelId);
+    return stateUpdateQueue.run(path, async () => {
+        const current = await readMemoryMaintenanceState(appHomeDir, channelId);
+        const next = normalizeState(channelId, update(current));
+        await writeFileAtomically(path, `${JSON.stringify(next, null, 2)}\n`);
+        return next;
+    });
+}
+export function applyMemoryActivityToState(state, event) {
+    const next = {
+        ...state,
+        channelId: event.channelId,
+        lastActivityAt: event.timestamp,
+        eligibleAfter: event.eligibleAfter ?? state.eligibleAfter,
+        lastSessionEntryId: event.latestSessionEntryId ?? state.lastSessionEntryId,
+    };
+    if (event.kind === "tool-call") {
+        next.dirty = true;
+        next.toolCallsSinceSessionRefresh += 1;
+        next.toolCallsSinceGrowthReview += 1;
+    }
+    if (event.kind === "assistant-turn-completed") {
+        next.dirty = true;
+        next.turnsSinceSessionRefresh += 1;
+        next.turnsSinceGrowthReview += 1;
+    }
+    if (event.kind === "boundary") {
+        next.dirty = true;
+    }
+    return next;
+}

package/dist/memory/post-turn-review.d.ts

@@ -0,0 +1,32 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { Api, Model } from "@mariozechner/pi-ai";
+import { type PostTurnReviewResult } from "./promotion.js";
+export interface PostTurnReviewOptions {
+    channelId: string;
+    channelDir: string;
+    workspaceDir: string;
+    workspacePath: string;
+    messages: AgentMessage[];
+    model: Model<Api>;
+    resolveApiKey: (model: Model<Api>) => Promise<string>;
+    timeoutMs: number;
+    autoWriteChannelMemory: boolean;
+    autoWriteWorkspaceSkills: boolean;
+    minMemoryAutoWriteConfidence: number;
+    minSkillAutoWriteConfidence: number;
+    loadedSkills: Array<{
+        name: string;
+        description?: string;
+    }>;
+    emitNotice?: (notice: string) => Promise<void>;
+    refreshWorkspaceResources?: () => Promise<void>;
+}
+export interface PostTurnReviewApplyResult {
+    actions: unknown[];
+    suggestions: unknown[];
+    skipped: unknown[];
+    notices: string[];
+}
+export declare function parsePostTurnReviewResult(value: unknown): PostTurnReviewResult;
+export declare function applyPostTurnReviewResult(options: PostTurnReviewOptions, review: PostTurnReviewResult): Promise<PostTurnReviewApplyResult>;
+export declare function runPostTurnReview(options: PostTurnReviewOptions): Promise<PostTurnReviewApplyResult>;