@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/index.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTools } from "./operations/tools.js";
+import { registerCommands } from "./tui/commands.js";
+import { createMemoryLifecycle } from "./lifecycle/memory-lifecycle.js";
+
+export default function hindsightExtension(pi: ExtensionAPI) {
+  const lifecycle = createMemoryLifecycle(process.cwd());
+
+  registerTools(pi, lifecycle.deps);
+  registerCommands(pi, lifecycle.deps);
+
+  pi.on("session_start", async (_event, ctx) => {
+    await lifecycle.initialize(ctx);
+  });
+
+  pi.on("context", async (event, ctx) => lifecycle.recall(event, ctx));
+
+  pi.on("agent_end", async (event, ctx) => {
+    await lifecycle.retain(event, ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await lifecycle.shutdown(ctx);
+  });
+}

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

@@ -0,0 +1,319 @@
+/**
+ * Opt-in cold-repo gitlog seed (coding-agents-aligned, Pi-native).
+ *
+ * Seeds an aggregated commit-message history document (strategy gitlog) with a stable
+ * document id for idempotent re-runs. Does not replace live session retain; default off
+ * (explicit tool/command only — no session-start auto-seed).
+ */
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import type { HindsightLikeClient, ResolvedConfig, RetainJob } from "../types.js";
+import { baseTags } from "../banks/banking.js";
+import { createMemoryIdentity } from "../operations/memory-identity.js";
+import { buildRetainJob } from "./retain-job-builder.js";
+import { enqueueRetain, flushRetain, retainQueuePath } from "../queue/queue.js";
+import { recordRetainDeliveries } from "./retain.js";
+
+const execFileAsync = promisify(execFile);
+
+export const DEFAULT_GIT_SEED_LIMIT = 300;
+export const GIT_SEED_RECEIPT_PATH = ".pi/hindsight/git-seed-receipt.json";
+
+export interface GitSeedReceipt {
+  bankId: string;
+  documentId: string;
+  headSha: string;
+  commitCount: number;
+  seededAt: string;
+  dryRun?: boolean;
+}
+
+export interface CollectGitLogArgs {
+  cwd: string;
+  limit?: number;
+  /** Injectable for tests. */
+  execGit?: (args: string[], cwd: string) => Promise<string>;
+}
+
+export interface CollectGitLogResult {
+  headSha: string;
+  commitCount: number;
+  content: string;
+  documentId: string;
+}
+
+async function defaultExecGit(args: string[], cwd: string): Promise<string> {
+  const { stdout } = await execFileAsync("git", args, {
+    cwd,
+    maxBuffer: 8 * 1024 * 1024,
+    encoding: "utf8",
+  });
+  return stdout;
+}
+
+/** Collect newest-first commit subjects for gitlog strategy retain. */
+export async function collectGitLogForSeed(
+  args: CollectGitLogArgs,
+): Promise<CollectGitLogResult | { error: string }> {
+  const limit = Math.max(1, Math.min(args.limit ?? DEFAULT_GIT_SEED_LIMIT, 2000));
+  const execGit = args.execGit ?? defaultExecGit;
+  try {
+    const headSha = (await execGit(["rev-parse", "HEAD"], args.cwd)).trim();
+    if (!/^[0-9a-f]{7,40}$/i.test(headSha)) {
+      return { error: "Could not resolve git HEAD" };
+    }
+    const log = await execGit(["log", `-n${limit}`, "--format=%H%x09%s", "--no-merges"], args.cwd);
+    const lines = log
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+    if (lines.length === 0) {
+      return { error: "No commits found for git seed" };
+    }
+    const subjects = lines.map((line) => {
+      const tab = line.indexOf("\t");
+      if (tab === -1) return line;
+      const sha = line.slice(0, tab).slice(0, 12);
+      const subject = line.slice(tab + 1);
+      return `${sha} ${subject}`;
+    });
+    const content = [
+      `# Git commit message history (newest first, limit ${limit})`,
+      "",
+      ...subjects,
+    ].join("\n");
+    return {
+      headSha,
+      commitCount: subjects.length,
+      content,
+      // Stable id per project head so re-seed at same HEAD is idempotent; new HEAD creates a new doc.
+      documentId: `pi-gitlog:${headSha.slice(0, 12)}`,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: message.includes("not a git") ? "Not a git repository" : message };
+  }
+}
+
+export function resolveGitSeedReceiptPath(cwd: string): string {
+  return join(cwd, GIT_SEED_RECEIPT_PATH);
+}
+
+export async function readGitSeedReceipt(cwd: string): Promise<GitSeedReceipt | null> {
+  try {
+    const raw = await readFile(resolveGitSeedReceiptPath(cwd), "utf8");
+    const parsed = JSON.parse(raw) as GitSeedReceipt;
+    if (!parsed || typeof parsed.headSha !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeGitSeedReceipt(cwd: string, receipt: GitSeedReceipt): Promise<void> {
+  const path = resolveGitSeedReceiptPath(cwd);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+}
+
+export function buildGitLogRetainJob(args: {
+  config: ResolvedConfig;
+  cwd: string;
+  bankId: string;
+  content: string;
+  documentId: string;
+  headSha: string;
+}): RetainJob {
+  const identity = createMemoryIdentity(args.cwd, args.config);
+  const tags = [...baseTags(args.cwd, "git-seed", args.config), "source:git", "strategy:gitlog"];
+  return buildRetainJob({
+    config: args.config,
+    bankId: args.bankId,
+    content: args.content,
+    context: `Git commit-message seed for ${identity.projectId} (HEAD ${args.headSha.slice(0, 12)})`,
+    documentId: args.documentId,
+    // Full snapshot of the limited log window — replace keeps one doc per HEAD id.
+    updateMode: "replace",
+    tags: [...new Set(tags)],
+    metadata: {
+      cwd: args.cwd,
+      imported: "true",
+      seed: "gitlog",
+      head_sha: args.headSha,
+    },
+    strategy: "gitlog",
+  });
+}
+
+export interface SeedGitLogArgs {
+  cwd: string;
+  bankId: string;
+  config: ResolvedConfig;
+  client: HindsightLikeClient;
+  limit?: number;
+  dryRun?: boolean;
+  flush?: boolean;
+  execGit?: CollectGitLogArgs["execGit"];
+}
+
+export interface SeedGitLogResult {
+  dryRun: boolean;
+  bankId: string;
+  ok: boolean;
+  error?: string;
+  documentId?: string;
+  headSha?: string;
+  commitCount?: number;
+  queued?: boolean;
+  flushed?: number;
+  receipt?: GitSeedReceipt;
+}
+
+/** Opt-in gitlog seed: queue a retain job (and optionally flush). */
+export async function seedGitLog(args: SeedGitLogArgs): Promise<SeedGitLogResult> {
+  const dryRun = args.dryRun ?? true;
+  const collectArgs: CollectGitLogArgs = {
+    cwd: args.cwd,
+    ...(args.limit !== undefined ? { limit: args.limit } : {}),
+    ...(args.execGit ? { execGit: args.execGit } : {}),
+  };
+  const collected = await collectGitLogForSeed(collectArgs);
+  if ("error" in collected) {
+    return { dryRun, bankId: args.bankId, ok: false, error: collected.error };
+  }
+
+  const receipt: GitSeedReceipt = {
+    bankId: args.bankId,
+    documentId: collected.documentId,
+    headSha: collected.headSha,
+    commitCount: collected.commitCount,
+    seededAt: new Date().toISOString(),
+    ...(dryRun ? { dryRun: true } : {}),
+  };
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      bankId: args.bankId,
+      ok: true,
+      documentId: collected.documentId,
+      headSha: collected.headSha,
+      commitCount: collected.commitCount,
+      receipt,
+    };
+  }
+
+  const job = buildGitLogRetainJob({
+    config: args.config,
+    cwd: args.cwd,
+    bankId: args.bankId,
+    content: collected.content,
+    documentId: collected.documentId,
+    headSha: collected.headSha,
+  });
+  await enqueueRetain(args.cwd, args.config, job);
+  let flushed = 0;
+  if (args.flush !== false) {
+    const result = await flushRetain(args.cwd, args.config, args.client, {
+      maxJobs: 1,
+    });
+    await recordRetainDeliveries(args.cwd, args.config, result);
+    flushed = result.sent;
+  }
+  await writeGitSeedReceipt(args.cwd, receipt);
+  return {
+    dryRun: false,
+    bankId: args.bankId,
+    ok: true,
+    documentId: collected.documentId,
+    headSha: collected.headSha,
+    commitCount: collected.commitCount,
+    queued: true,
+    flushed,
+    receipt,
+  };
+}
+
+export interface SyncStatus {
+  ready: boolean;
+  reasons: string[];
+  queue: {
+    path: string;
+    active: number;
+    deadLetter: number;
+    malformed: number;
+  };
+  gitSeed: {
+    receipt: GitSeedReceipt | null;
+    /** True when receipt HEAD matches current git HEAD (when resolvable). */
+    headMatches?: boolean;
+    currentHead?: string;
+  };
+  knowledgePages: "unknown" | "supported" | "unavailable";
+}
+
+export async function buildSyncStatus(args: {
+  cwd: string;
+  config: ResolvedConfig;
+  client: HindsightLikeClient;
+  bankId: string;
+  execGit?: CollectGitLogArgs["execGit"];
+}): Promise<SyncStatus> {
+  const { summarizeRetainQueue } = await import("../queue/queue.js");
+  const queueSummary = await summarizeRetainQueue(retainQueuePath(args.cwd, args.config));
+  const receipt = await readGitSeedReceipt(args.cwd);
+  const reasons: string[] = [];
+
+  let currentHead: string | undefined;
+  let headMatches: boolean | undefined;
+  try {
+    const execGit = args.execGit ?? defaultExecGit;
+    currentHead = (await execGit(["rev-parse", "HEAD"], args.cwd)).trim();
+    if (receipt) {
+      headMatches = receipt.headSha === currentHead;
+      if (!headMatches) reasons.push("git_seed_stale");
+    } else {
+      reasons.push("git_seed_missing");
+    }
+  } catch {
+    // Not a git repo — seed is N/A, not a readiness failure for chat-only memory.
+    headMatches = undefined;
+  }
+
+  if (queueSummary.active.valid > 0) reasons.push("queue_pending");
+  if (queueSummary.deadLetter.valid > 0) reasons.push("queue_dead_letter");
+
+  let knowledgePages: SyncStatus["knowledgePages"] = "unknown";
+  if (!args.client.getKnowledgeBaseTree && !args.client.createKnowledgePage) {
+    knowledgePages = "unavailable";
+  } else if (args.client.getKnowledgeBaseTree) {
+    try {
+      await args.client.getKnowledgeBaseTree(args.bankId);
+      knowledgePages = "supported";
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      knowledgePages = /\b404\b|\b405\b|\b501\b|not found|unavail/i.test(msg)
+        ? "unavailable"
+        : "unknown";
+    }
+  }
+
+  return {
+    ready: reasons.length === 0,
+    reasons,
+    queue: {
+      path: queueSummary.active.path,
+      active: queueSummary.active.valid,
+      deadLetter: queueSummary.deadLetter.valid,
+      malformed: queueSummary.active.malformed,
+    },
+    gitSeed: {
+      receipt,
+      ...(headMatches !== undefined ? { headMatches } : {}),
+      ...(currentHead ? { currentHead } : {}),
+    },
+    knowledgePages,
+  };
+}

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

@@ -0,0 +1,196 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { recallForContext } from "./recall.js";
+import { redactError } from "../utils/sanitize.js";
+import { writeLastRecallSnapshot } from "./recall-visibility.js";
+import { selectMemoryScopes } from "../operations/memory-scope.js";
+import {
+  getEffectiveSessionMemoryMode,
+  readSessionMemoryMeta,
+} from "../utils/session-memory-meta.js";
+import type { HindsightActivity } from "../utils/status.js";
+import type { HindsightLikeClient, RecallBlock, RecallFailure, ResolvedConfig } from "../types.js";
+import type { ContextEvent, ContextPatch, RuntimeSnapshot } from "./memory-lifecycle-runtime.js";
+
+export type RecallStatusActivity = Extract<
+  HindsightActivity,
+  "recalling" | "recalled" | "recall-empty" | "recall-failed"
+>;
+
+export interface RecallTurnPolicy {
+  recall(event: ContextEvent, runtime: RuntimeSnapshot): Promise<ContextPatch | undefined>;
+}
+
+export interface RecallTurnPolicyDeps {
+  getConfig(): ResolvedConfig;
+  getClient(): HindsightLikeClient;
+  setMemoryStatus(
+    runtime: RuntimeSnapshot,
+    activity: RecallStatusActivity,
+    memoryCount?: number,
+  ): void;
+  notify(runtime: RuntimeSnapshot, message: string, level: "info" | "warning"): void;
+}
+
+interface RecallCacheEntry {
+  rendered: string;
+  blocks: RecallBlock[];
+  failed: number;
+  failures: RecallFailure[];
+}
+
+export function createRecallCache(ttlMs: number | (() => number) = 60000) {
+  const cache = new Map<string, { entry: RecallCacheEntry; timestamp: number }>();
+  const ttl = () => (typeof ttlMs === "function" ? ttlMs() : ttlMs);
+  return {
+    get(key: string): RecallCacheEntry | undefined {
+      const cached = cache.get(key);
+      if (!cached) return undefined;
+      if (Date.now() - cached.timestamp > ttl()) {
+        cache.delete(key);
+        return undefined;
+      }
+      return cached.entry;
+    },
+    set(key: string, entry: RecallCacheEntry) {
+      cache.set(key, { entry, timestamp: Date.now() });
+    },
+  };
+}
+
+function canAppendRecallMessage(event: ContextEvent): boolean {
+  const last = event.messages[event.messages.length - 1];
+  const lastRole = (last as unknown as { role?: string } | undefined)?.role;
+  return Boolean(last && lastRole === "user");
+}
+
+function buildRecallNotification(memoryCount: number, bankIds: string[], failed: number): string {
+  if (memoryCount > 0) {
+    return `Hindsight recalled ${memoryCount} memory item${memoryCount === 1 ? "" : "s"} from ${bankIds.join(", ")}${failed > 0 ? `; ${failed} bank${failed === 1 ? "" : "s"} failed` : ""}`;
+  }
+  if (failed > 0) return `Hindsight recall failed for ${failed} bank${failed === 1 ? "" : "s"}`;
+  return "Hindsight recalled no matching memory";
+}
+
+function patchWithRecallMessage(
+  event: ContextEvent,
+  recallMessage: AgentMessage,
+): ContextPatch | undefined {
+  const last = event.messages[event.messages.length - 1];
+  const lastRole = (last as unknown as { role?: string } | undefined)?.role;
+  if (last && lastRole === "user") {
+    return { messages: [...event.messages.slice(0, -1), recallMessage, last] };
+  }
+  return undefined;
+}
+
+export function createRecallTurnPolicy(deps: RecallTurnPolicyDeps): RecallTurnPolicy {
+  const cache = createRecallCache(() => deps.getConfig().recall.cacheTtlMs);
+  return {
+    async recall(event: ContextEvent, runtime: RuntimeSnapshot): Promise<ContextPatch | undefined> {
+      const config = deps.getConfig();
+      if (!config.enabled || !config.recall.enabled) return undefined;
+
+      const sessionMemory = getEffectiveSessionMemoryMode(
+        await readSessionMemoryMeta(runtime.cwd, runtime.sessionFile),
+      );
+      if (!sessionMemory.recall) return undefined;
+
+      const scopes = selectMemoryScopes(runtime.cwd, config);
+      if (scopes.length === 0) return undefined;
+      if (config.recall.injectionPosition === "append" && !canAppendRecallMessage(event)) {
+        return undefined;
+      }
+
+      const cacheKey = scopes.map((s) => s.bankId).join(",") + "|" + event.messages.length;
+      let recallResult = cache.get(cacheKey);
+
+      try {
+        if (!recallResult) {
+          deps.setMemoryStatus(runtime, "recalling");
+          recallResult = await recallForContext({
+            client: deps.getClient(),
+            config,
+            scopes,
+            messages: event.messages,
+            cwd: runtime.cwd,
+          });
+          cache.set(cacheKey, recallResult);
+        }
+        const { rendered, blocks, failed, failures } = recallResult;
+        const memoryCount = blocks.reduce((count, block) => count + block.memoryCount, 0);
+        deps.setMemoryStatus(
+          runtime,
+          memoryCount > 0 ? "recalled" : failed > 0 ? "recall-failed" : "recall-empty",
+          memoryCount,
+        );
+        if (config.notifications.recall) {
+          deps.notify(
+            runtime,
+            buildRecallNotification(
+              memoryCount,
+              blocks.map((block) => block.bankId),
+              failed,
+            ),
+            failed > 0 && memoryCount === 0 ? "warning" : "info",
+          );
+        }
+        if (
+          config.recall.storeLastRecall &&
+          (rendered || failed === 0 || config.recall.storeLastRecallFailures)
+        ) {
+          try {
+            await writeLastRecallSnapshot(runtime.cwd, config.recall.lastRecallPath, {
+              query: blocks[0]?.query ?? failures[0]?.query ?? "",
+              rendered,
+              blocks,
+              failed,
+              ...(failures.length ? { failures } : {}),
+            });
+          } catch (error) {
+            deps.notify(
+              runtime,
+              `Hindsight last recall snapshot write failed: ${redactError(error)}`,
+              "warning",
+            );
+          }
+        }
+        if (!rendered) return undefined;
+        const recallMessage = {
+          role: "user",
+          content: rendered,
+          timestamp: Date.now(),
+        } as AgentMessage;
+        if (config.recall.injectionPosition === "append") {
+          return patchWithRecallMessage(event, recallMessage);
+        }
+        return { messages: [recallMessage, ...event.messages] };
+      } catch (error) {
+        deps.setMemoryStatus(runtime, "recall-failed");
+        // Recall runs every turn, so this stays debug-gated behind the same opt-in flags that
+        // already gate the last-recall sidecar, instead of notifying (which would spam normal
+        // usage). Users who enabled storeLastRecall + storeLastRecallFailures can inspect the
+        // redacted cause via the opt-in last-recall sidecar under .pi/hindsight/.
+        if (config.recall.storeLastRecall && config.recall.storeLastRecallFailures) {
+          try {
+            await writeLastRecallSnapshot(runtime.cwd, config.recall.lastRecallPath, {
+              query: "",
+              rendered: "",
+              blocks: [],
+              failed: 1,
+              failures: [
+                {
+                  bankId: "pre-scope-failure",
+                  query: "",
+                  error: `Unexpected recall failure: ${redactError(error)}`,
+                },
+              ],
+            });
+          } catch {
+            // Best-effort debug snapshot; do not let a write failure mask the original recall failure.
+          }
+        }
+        return undefined;
+      }
+    },
+  };
+}