@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

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

@@ -1,189 +0,0 @@
-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

@@ -1,65 +0,0 @@
-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

@@ -1,260 +0,0 @@
-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.
-      }
-    },
-  };
-}