@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/memory-lifecycle-retain.ts

@@ -0,0 +1,189 @@
+import type { AgentEndEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { projectMessages } from "../utils/messages.js";
+import { enqueueRetainFromAgentEnd } from "./retain.js";
+import {
+  advanceRetainCursor,
+  filterNewRetainMessages,
+  readSessionRetainState,
+  retainedThroughIndex,
+} from "./retain-cursor.js";
+import { stableSessionId } from "../utils/session.js";
+import {
+  clearNextSessionRetainMode,
+  getEffectiveSessionMemoryMode,
+  readSessionMemoryMeta,
+} from "../utils/session-memory-meta.js";
+import { redactError } from "../utils/sanitize.js";
+import type { HindsightLikeClient, ResolvedConfig } from "../types.js";
+import type { RuntimeSnapshot } from "./memory-lifecycle-runtime.js";
+import type { HindsightActivity } from "../utils/status.js";
+
+export type RetainStatusActivity = Extract<
+  HindsightActivity,
+  "retaining" | "retained" | "retain-queued" | "retain-failed"
+>;
+
+export interface RetainTurnPolicy {
+  retain(event: AgentEndEvent, runtime: RuntimeSnapshot): Promise<RetainTurnResult>;
+}
+
+export interface RetainTurnResult {
+  queued: boolean;
+  sent: number;
+  remaining: number;
+}
+
+export interface RetainTurnPolicyDeps {
+  getConfig(): ResolvedConfig;
+  getClient(): HindsightLikeClient;
+  getProjectBankId(): string;
+  setMemoryStatus(
+    runtime: RuntimeSnapshot,
+    activity: RetainStatusActivity,
+    queueRemaining?: number,
+  ): void;
+  notify(runtime: RuntimeSnapshot, message: string, level: "info" | "warning"): void;
+}
+
+export function createRetainTurnPolicy(deps: RetainTurnPolicyDeps): RetainTurnPolicy {
+  const retainedBySession = new Map<string, Awaited<ReturnType<typeof readSessionRetainState>>>();
+
+  const sessionRetainState = async (runtime: RuntimeSnapshot) => {
+    const sessionId = stableSessionId(runtime.sessionFile, runtime.cwd);
+    const state =
+      retainedBySession.get(sessionId) ?? (await readSessionRetainState(runtime.cwd, sessionId));
+    retainedBySession.set(sessionId, state);
+    return { sessionId, state };
+  };
+
+  const newRetainMessages = async (
+    runtime: RuntimeSnapshot,
+    messages: AgentEndEvent["messages"],
+  ): Promise<AgentEndEvent["messages"]> => {
+    const { state } = await sessionRetainState(runtime);
+    return filterNewRetainMessages(messages as AgentMessage[], state) as AgentEndEvent["messages"];
+  };
+
+  const markRetainedMessages = async (
+    runtime: RuntimeSnapshot,
+    allMessages: AgentEndEvent["messages"],
+    retainedMessages?: AgentEndEvent["messages"],
+  ): Promise<void> => {
+    const { sessionId } = await sessionRetainState(runtime);
+    const batch = retainedMessages ?? allMessages;
+    const throughIndex = retainedThroughIndex(
+      allMessages as AgentMessage[],
+      batch as AgentMessage[],
+    );
+    await advanceRetainCursor(runtime.cwd, sessionId, allMessages as AgentMessage[], throughIndex);
+    retainedBySession.set(sessionId, await readSessionRetainState(runtime.cwd, sessionId));
+  };
+
+  const retainableMessages = (messages: AgentEndEvent["messages"]): Record<string, unknown>[] =>
+    projectMessages(messages as AgentMessage[], deps.getConfig());
+
+  const retainableMessageCount = (messages: AgentEndEvent["messages"]): number =>
+    retainableMessages(messages).length;
+
+  const retainTargets = (): string[] => {
+    const config = deps.getConfig();
+    return config.banks.project.enabled ? [deps.getProjectBankId()] : [];
+  };
+
+  return {
+    async retain(event: AgentEndEvent, runtime: RuntimeSnapshot): Promise<RetainTurnResult> {
+      const config = deps.getConfig();
+      const canRetainProject = config.banks.project.enabled;
+      const canRetainGlobal = config.banks.user.enabled && Boolean(config.banks.user.bankId);
+      if (!config.enabled || !config.retain.enabled || (!canRetainProject && !canRetainGlobal))
+        return { queued: false, sent: 0, remaining: 0 };
+
+      const sessionMeta = await readSessionMemoryMeta(runtime.cwd, runtime.sessionFile);
+      const nextRetainMode = sessionMeta.nextRetainMode;
+      const sessionMemory = getEffectiveSessionMemoryMode(sessionMeta);
+      if (!sessionMemory.retain || nextRetainMode === "off") {
+        try {
+          await markRetainedMessages(runtime, event.messages);
+        } catch (error) {
+          deps.setMemoryStatus(runtime, "retain-failed");
+          deps.notify(
+            runtime,
+            `Hindsight retain cursor update failed: ${(error as Error).message}`,
+            "warning",
+          );
+          return { queued: false, sent: 0, remaining: 0 };
+        }
+        if (nextRetainMode === "off") {
+          await clearNextSessionRetainMode(runtime.cwd, runtime.sessionFile);
+          deps.notify(
+            runtime,
+            "Hindsight skipped retain for this run due to next-opt-out.",
+            "info",
+          );
+        }
+        return { queued: false, sent: 0, remaining: 0 };
+      }
+
+      const messages = await newRetainMessages(runtime, event.messages);
+      const messageCount = retainableMessageCount(messages);
+      if (!messageCount) return { queued: false, sent: 0, remaining: 0 };
+
+      try {
+        deps.setMemoryStatus(runtime, "retaining");
+        const targets = retainTargets();
+        if (targets.length === 0) {
+          await markRetainedMessages(runtime, event.messages, messages);
+          deps.setMemoryStatus(runtime, "retained", 0);
+          if (config.notifications.retain) {
+            deps.notify(
+              runtime,
+              `Hindsight skipped ${messageCount} new message${messageCount === 1 ? "" : "s"}; no automatic-retain bank enabled`,
+              "info",
+            );
+          }
+          return { queued: false, sent: 0, remaining: 0 };
+        }
+        let sent = 0;
+        let remaining = 0;
+        let queued = false;
+        let reflectError: string | undefined;
+        for (const bankId of targets) {
+          const result = await enqueueRetainFromAgentEnd({
+            event: { ...event, messages },
+            cwd: runtime.cwd,
+            ...(runtime.sessionFile ? { sessionFile: runtime.sessionFile } : {}),
+            config,
+            client: deps.getClient(),
+            bankId,
+            extraTags: sessionMemory.tags,
+          });
+          queued ||= result.queued;
+          sent += result.sent;
+          remaining = result.remaining;
+          reflectError ??= result.reflectError;
+        }
+        if (queued) await markRetainedMessages(runtime, event.messages, messages);
+        deps.setMemoryStatus(runtime, remaining > 0 ? "retain-queued" : "retained", remaining);
+        if (config.notifications.retain) {
+          deps.notify(
+            runtime,
+            `Hindsight retained ${messageCount} new message${messageCount === 1 ? "" : "s"} to ${targets.join(", ")}${remaining > 0 ? `; ${remaining} queued` : ""}`,
+            "info",
+          );
+        }
+        // Post-retain reflect is opt-in (retain.postRetainReflect, off by default); users who
+        // enable it have opted into this extra visibility, so surface failures like other
+        // opt-in feature failures in this file do, without requiring notifications.retain.
+        if (reflectError) {
+          deps.notify(runtime, `Hindsight post-retain reflect failed: ${reflectError}`, "warning");
+        }
+        return { queued, sent, remaining };
+      } catch (error) {
+        deps.setMemoryStatus(runtime, "retain-failed");
+        deps.notify(runtime, `Hindsight retain queue failed: ${redactError(error)}`, "warning");
+        return { queued: false, sent: 0, remaining: 0 };
+      }
+    },
+  };
+}

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/memory-lifecycle-runtime.ts

@@ -0,0 +1,65 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { getSessionFile } from "../utils/session.js";
+import { formatHindsightStatus, type HindsightActivity } from "../utils/status.js";
+import type { ResolvedConfig } from "../types.js";
+
+export type RuntimeCtx = {
+  cwd: string;
+  ui: {
+    setStatus(key: string, text: string | undefined): void;
+    notify(message: string, level?: string): void;
+  };
+  sessionManager?: { getSessionFile?: () => string | undefined };
+};
+
+export type RuntimeSnapshot = {
+  cwd: string;
+  ui: RuntimeCtx["ui"];
+  sessionFile?: string;
+};
+
+export type ContextEvent = { messages: AgentMessage[] };
+export type ContextPatch = { messages: AgentMessage[] };
+
+export function snapshotRuntime(ctx: RuntimeCtx): RuntimeSnapshot | undefined {
+  try {
+    const cwd = ctx.cwd;
+    const ui = ctx.ui;
+    const sessionFile = getSessionFile(ctx);
+    return { cwd, ui, ...(sessionFile ? { sessionFile } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+export function setMemoryStatus(args: {
+  runtime: RuntimeSnapshot;
+  config: ResolvedConfig;
+  projectBankId: string;
+  activity: HindsightActivity;
+  memoryCount?: number;
+  queueRemaining?: number;
+}): void {
+  try {
+    args.runtime.ui.setStatus(
+      "hindsight",
+      formatHindsightStatus(args.config, {
+        projectBankId: args.projectBankId,
+        cwd: args.runtime.cwd,
+        activity: args.activity,
+        ...(args.memoryCount !== undefined ? { memoryCount: args.memoryCount } : {}),
+        ...(args.queueRemaining !== undefined ? { queueRemaining: args.queueRemaining } : {}),
+      }),
+    );
+  } catch {
+    // Session ctx can go stale during replacement/reload; status is best effort.
+  }
+}
+
+export function notify(runtime: RuntimeSnapshot, message: string, level: string): void {
+  try {
+    runtime.ui.notify(message, level);
+  } catch {
+    // Session ctx can go stale during replacement/reload; notifications are best effort.
+  }
+}

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/memory-lifecycle.ts

@@ -0,0 +1,260 @@
+import type { AgentEndEvent } from "@earendil-works/pi-coding-agent";
+import { resolveConfig } from "../config/config.js";
+import { consumeLastConfigMigrationResults } from "../config/config.js";
+import { isMemorySetupComplete, setupRequiredMessage } from "../config/setup-gate.js";
+import { deriveProjectBankId } from "../banks/banking.js";
+import { createHindsightClient } from "../client/client.js";
+import { ensureGlobalBank, ensureProjectBank } from "../banks/bank-operations.js";
+import { flushRetainQueue, retainQueuePath } from "../queue/queue.js";
+import { recordRetainDeliveries } from "./retain.js";
+import { formatFlushRetainQueueResult } from "../queue/flush-presenter.js";
+import { bankSelectionMessage } from "../utils/diagnostics.js";
+import type { HindsightLikeClient, ResolvedConfig } from "../types.js";
+import { redactError } from "../utils/sanitize.js";
+import {
+  notify,
+  setMemoryStatus as setRuntimeMemoryStatus,
+  snapshotRuntime,
+  type ContextEvent,
+  type ContextPatch,
+  type RuntimeCtx,
+  type RuntimeSnapshot,
+} from "./memory-lifecycle-runtime.js";
+import { createRetainTurnPolicy } from "./memory-lifecycle-retain.js";
+import { createRecallTurnPolicy } from "./memory-lifecycle-recall.js";
+
+export interface InitHealthFailure {
+  subsystem: "project-bank" | "user-bank";
+  error: string;
+}
+
+export interface InitHealth {
+  checkedAt: string;
+  failures: InitHealthFailure[];
+}
+
+export interface MemoryLifecycleDeps {
+  getClient(): HindsightLikeClient;
+  getConfig(): ResolvedConfig;
+  getProjectBankId(): string;
+  getInitHealth(): InitHealth | undefined;
+  reloadConfig(cwd: string): void;
+}
+
+export interface MemoryLifecycle {
+  deps: MemoryLifecycleDeps;
+  initialize(ctx: RuntimeCtx): Promise<void>;
+  recall(event: ContextEvent, ctx: RuntimeCtx): Promise<ContextPatch | undefined>;
+  retain(
+    event: AgentEndEvent,
+    ctx: RuntimeCtx,
+  ): Promise<{ queued: boolean; sent: number; remaining: number }>;
+  shutdown(ctx: RuntimeCtx): Promise<void>;
+}
+
+export function createMemoryLifecycle(initialCwd: string = process.cwd()): MemoryLifecycle {
+  let config: ResolvedConfig = resolveConfig(initialCwd);
+  let client: HindsightLikeClient = createHindsightClient(config);
+  let projectBankId = deriveProjectBankId(initialCwd, config);
+  let initHealth: InitHealth | undefined;
+  let periodicFlush: NodeJS.Timeout | undefined;
+  let periodicFlushActive = false;
+  const stopPeriodicFlush = () => {
+    if (!periodicFlush) return;
+    clearInterval(periodicFlush);
+    periodicFlush = undefined;
+  };
+
+  const reloadConfig = (cwd: string) => {
+    stopPeriodicFlush();
+    config = resolveConfig(cwd);
+    client = createHindsightClient(config);
+    projectBankId = deriveProjectBankId(cwd, config);
+  };
+
+  const startPeriodicFlush = (runtime: RuntimeSnapshot) => {
+    stopPeriodicFlush();
+    if (!config.enabled || !config.retain.enabled || config.retain.flushIntervalMs <= 0) return;
+    if (!isMemorySetupComplete(config, runtime.cwd)) return;
+    const queuePath = retainQueuePath(runtime.cwd, config);
+    periodicFlush = setInterval(() => {
+      if (periodicFlushActive) return;
+      periodicFlushActive = true;
+      void flushRetainQueue(queuePath, client, {
+        stopOnFirstFailure: true,
+        maxJobs: config.retain.periodicFlushMaxJobs,
+        maxElapsedMs: config.retain.periodicFlushTimeoutMs,
+      })
+        .then(async (result) => {
+          await recordRetainDeliveries(runtime.cwd, config, result);
+          if (result.deadLettered || result.remaining) {
+            notify(runtime, formatFlushRetainQueueResult(result), "warning");
+          }
+        })
+        .catch((error) => {
+          notify(runtime, `Periodic retain queue flush failed: ${redactError(error)}`, "warning");
+        })
+        .finally(() => {
+          periodicFlushActive = false;
+        });
+    }, config.retain.flushIntervalMs);
+    periodicFlush.unref?.();
+  };
+
+  const setMemoryStatus = (
+    runtime: RuntimeSnapshot,
+    activity: Parameters<typeof setRuntimeMemoryStatus>[0]["activity"],
+    memoryCount?: number,
+    queueRemaining?: number,
+  ) =>
+    setRuntimeMemoryStatus({
+      runtime,
+      config,
+      projectBankId,
+      activity,
+      ...(memoryCount !== undefined ? { memoryCount } : {}),
+      ...(queueRemaining !== undefined ? { queueRemaining } : {}),
+    });
+
+  const deps: MemoryLifecycleDeps = {
+    getClient: () => client,
+    getConfig: () => config,
+    getProjectBankId: () => projectBankId,
+    getInitHealth: () => initHealth,
+    reloadConfig,
+  };
+
+  const retainPolicy = createRetainTurnPolicy({
+    getConfig: () => config,
+    getClient: () => client,
+    getProjectBankId: () => projectBankId,
+    setMemoryStatus: (runtime, activity, queueRemaining) =>
+      setMemoryStatus(runtime, activity, undefined, queueRemaining),
+    notify,
+  });
+
+  const recallPolicy = createRecallTurnPolicy({
+    getConfig: () => config,
+    getClient: () => client,
+    setMemoryStatus: (runtime, activity, memoryCount) =>
+      setMemoryStatus(runtime, activity, memoryCount),
+    notify,
+  });
+
+  return {
+    deps,
+
+    async initialize(ctx: RuntimeCtx): Promise<void> {
+      const runtime = snapshotRuntime(ctx);
+      if (!runtime) return;
+      reloadConfig(runtime.cwd);
+      const migrations = consumeLastConfigMigrationResults();
+      if (migrations.length) {
+        notify(
+          runtime,
+          `Migrated Hindsight memory config from global to user keys. Backups: ${migrations
+            .map((migration) => migration.backupPath)
+            .join(", ")}`,
+          "info",
+        );
+      }
+      if (!config.enabled) {
+        // Clear status bar when extension is disabled for this repo.
+        try {
+          runtime.ui.setStatus("hindsight", undefined);
+        } catch {
+          // Session ctx can go stale; status clear is best effort.
+        }
+        return;
+      }
+      if (!isMemorySetupComplete(config, runtime.cwd)) {
+        initHealth = { checkedAt: new Date().toISOString(), failures: [] };
+        setMemoryStatus(runtime, "idle");
+        if (config.notifications.startup) notify(runtime, setupRequiredMessage(), "warning");
+        return;
+      }
+      const failures: InitHealthFailure[] = [];
+      let ensureSucceeded = false;
+      if (config.banks.project.enabled) {
+        try {
+          await ensureProjectBank(client, projectBankId, {
+            ...config.banks.project,
+            enableObservations: config.observations.enabled,
+          });
+          ensureSucceeded = true;
+        } catch (error) {
+          failures.push({ subsystem: "project-bank", error: redactError(error) });
+          setMemoryStatus(runtime, "offline");
+          notify(runtime, `Hindsight project bank ensure failed: ${redactError(error)}`, "warning");
+        }
+      }
+      if (config.banks.user.enabled && config.banks.user.bankId) {
+        try {
+          await ensureGlobalBank(client, config.banks.user.bankId, {
+            ...config.banks.user,
+            enableObservations: config.observations.enabled,
+            agentUse: config.agentUse,
+          });
+          ensureSucceeded = true;
+        } catch (error) {
+          failures.push({ subsystem: "user-bank", error: redactError(error) });
+          setMemoryStatus(runtime, "offline");
+          notify(runtime, `Hindsight global bank ensure failed: ${redactError(error)}`, "warning");
+        }
+      }
+      initHealth = { checkedAt: new Date().toISOString(), failures };
+      startPeriodicFlush(runtime);
+      setMemoryStatus(
+        runtime,
+        failures.length ? "offline" : ensureSucceeded ? "connected" : "idle",
+      );
+      if (config.notifications.startup)
+        notify(runtime, bankSelectionMessage(projectBankId, config), "info");
+    },
+
+    async recall(event: ContextEvent, ctx: RuntimeCtx): Promise<ContextPatch | undefined> {
+      if (!config.enabled || !config.recall.enabled) return undefined;
+      const runtime = snapshotRuntime(ctx);
+      if (!runtime) return undefined;
+      if (!isMemorySetupComplete(config, runtime.cwd)) return undefined;
+      return recallPolicy.recall(event, runtime);
+    },
+
+    async retain(
+      event: AgentEndEvent,
+      ctx: RuntimeCtx,
+    ): Promise<{ queued: boolean; sent: number; remaining: number }> {
+      const canRetainProject = config.banks.project.enabled;
+      const canRetainUser = config.banks.user.enabled && Boolean(config.banks.user.bankId);
+      if (!config.enabled || !config.retain.enabled || (!canRetainProject && !canRetainUser))
+        return { queued: false, sent: 0, remaining: 0 };
+      const runtime = snapshotRuntime(ctx);
+      if (!runtime) return { queued: false, sent: 0, remaining: 0 };
+      if (!isMemorySetupComplete(config, runtime.cwd))
+        return { queued: false, sent: 0, remaining: 0 };
+      return retainPolicy.retain(event, runtime);
+    },
+
+    async shutdown(ctx: RuntimeCtx): Promise<void> {
+      stopPeriodicFlush();
+      if (!config.enabled || !config.retain.enabled) return;
+      const runtime = snapshotRuntime(ctx);
+      if (!runtime) return;
+      if (!isMemorySetupComplete(config, runtime.cwd)) return;
+      try {
+        const result = await flushRetainQueue(retainQueuePath(runtime.cwd, config), client, {
+          maxJobs: config.retain.shutdownFlushMaxJobs,
+          maxElapsedMs: config.retain.shutdownFlushTimeoutMs,
+          stopOnFirstFailure: true,
+        });
+        await recordRetainDeliveries(runtime.cwd, config, result);
+        if (result.deadLettered || result.remaining) {
+          notify(runtime, formatFlushRetainQueueResult(result), "warning");
+        }
+      } catch (error) {
+        notify(runtime, `Shutdown retain queue flush failed: ${redactError(error)}`, "warning");
+        // Keep queue on disk for next run.
+      }
+    },
+  };
+}