@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/utils/session-memory-meta.ts

@@ -0,0 +1,244 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { stableSessionId } from "./session.js";
+
+export type SessionMemoryMode = "normal" | "read-only" | "ignored";
+export type SessionMemorySwitch = "normal" | "off";
+export type NextRetainMode = "normal" | "off";
+
+export interface HindsightSessionMeta {
+  retained: boolean;
+  recallMode: SessionMemorySwitch;
+  retainMode: SessionMemorySwitch;
+  nextRetainMode: NextRetainMode;
+  mode: SessionMemoryMode;
+  tags: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EffectiveSessionMemoryMode {
+  recall: boolean;
+  retain: boolean;
+  mode: SessionMemoryMode;
+  tags: string[];
+}
+
+export function sessionMetaPath(cwd: string, sessionFile?: string): string {
+  return join(cwd, ".pi", "hindsight", "session-meta", `${stableSessionId(sessionFile, cwd)}.json`);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function defaultSessionMemoryMeta(): HindsightSessionMeta {
+  const now = nowIso();
+  return {
+    retained: true,
+    recallMode: "normal",
+    retainMode: "normal",
+    nextRetainMode: "normal",
+    mode: "normal",
+    tags: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function failClosedSessionMemoryMeta(): HindsightSessionMeta {
+  const now = nowIso();
+  return {
+    retained: false,
+    recallMode: "off",
+    retainMode: "off",
+    nextRetainMode: "normal",
+    mode: "ignored",
+    tags: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function isMode(value: unknown): value is SessionMemoryMode {
+  return value === "normal" || value === "read-only" || value === "ignored";
+}
+
+function isSwitch(value: unknown): value is SessionMemorySwitch {
+  return value === "normal" || value === "off";
+}
+
+function cleanTag(tag: string): string {
+  return tag.trim();
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 32 || code === 127) return true;
+  }
+  return false;
+}
+
+export function normalizeSessionTags(tags: unknown): string[] {
+  if (!Array.isArray(tags)) return [];
+  return [
+    ...new Set(
+      tags
+        .filter((tag): tag is string => typeof tag === "string")
+        .filter((tag) => !hasControlCharacter(tag))
+        .map(cleanTag)
+        .filter((tag) => tag.length > 0 && tag.length <= 80),
+    ),
+  ];
+}
+
+type SessionMemoryMetaRecord = Omit<HindsightSessionMeta, "tags"> & { tags: unknown[] };
+
+function isSessionMemoryMetaRecord(value: unknown): value is SessionMemoryMetaRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.retained === "boolean" &&
+    isSwitch(record.recallMode) &&
+    isSwitch(record.retainMode) &&
+    (record.nextRetainMode === undefined || isSwitch(record.nextRetainMode)) &&
+    isMode(record.mode) &&
+    Array.isArray(record.tags) &&
+    typeof record.createdAt === "string" &&
+    typeof record.updatedAt === "string"
+  );
+}
+
+export function normalizeSessionMemoryMeta(value: unknown): HindsightSessionMeta {
+  if (!isSessionMemoryMetaRecord(value)) return failClosedSessionMemoryMeta();
+  return {
+    retained: value.retained,
+    recallMode: value.recallMode,
+    retainMode: value.retainMode,
+    nextRetainMode: value.nextRetainMode ?? "normal",
+    mode: value.mode,
+    tags: normalizeSessionTags(value.tags),
+    createdAt: value.createdAt,
+    updatedAt: value.updatedAt,
+  };
+}
+
+export async function readSessionMemoryMeta(
+  cwd: string,
+  sessionFile?: string,
+): Promise<HindsightSessionMeta> {
+  try {
+    return normalizeSessionMemoryMeta(
+      JSON.parse(await readFile(sessionMetaPath(cwd, sessionFile), "utf8")),
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return defaultSessionMemoryMeta();
+    return failClosedSessionMemoryMeta();
+  }
+}
+
+export async function writeSessionMemoryMeta(
+  cwd: string,
+  sessionFile: string | undefined,
+  meta: HindsightSessionMeta,
+): Promise<HindsightSessionMeta> {
+  const next = { ...meta, tags: normalizeSessionTags(meta.tags), updatedAt: nowIso() };
+  const path = sessionMetaPath(cwd, sessionFile);
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  await rename(tempPath, path);
+  return next;
+}
+
+export function getEffectiveSessionMemoryMode(
+  meta: HindsightSessionMeta,
+): EffectiveSessionMemoryMode {
+  if (meta.mode === "ignored")
+    return { recall: false, retain: false, mode: meta.mode, tags: meta.tags };
+  if (meta.mode === "read-only")
+    return { recall: meta.recallMode !== "off", retain: false, mode: meta.mode, tags: meta.tags };
+  return {
+    recall: meta.recallMode !== "off",
+    retain: meta.retainMode !== "off" && meta.retained,
+    mode: meta.mode,
+    tags: meta.tags,
+  };
+}
+
+export async function setSessionMemoryMode(
+  cwd: string,
+  sessionFile: string | undefined,
+  mode: SessionMemoryMode,
+): Promise<HindsightSessionMeta> {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  const updates: Partial<HindsightSessionMeta> = { mode };
+  if (mode === "normal" || mode === "read-only") updates.recallMode = "normal";
+  const looksFailClosed =
+    meta.mode === "ignored" &&
+    meta.recallMode === "off" &&
+    meta.retainMode === "off" &&
+    !meta.retained;
+  if (mode === "normal" && looksFailClosed) {
+    updates.retained = true;
+    updates.retainMode = "normal";
+  }
+  return writeSessionMemoryMeta(cwd, sessionFile, { ...meta, ...updates });
+}
+
+export async function setSessionRetainEnabled(
+  cwd: string,
+  sessionFile: string | undefined,
+  enabled: boolean,
+): Promise<HindsightSessionMeta> {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  return writeSessionMemoryMeta(cwd, sessionFile, {
+    ...meta,
+    retained: enabled,
+    retainMode: enabled ? "normal" : "off",
+  });
+}
+
+export async function setNextSessionRetainMode(
+  cwd: string,
+  sessionFile: string | undefined,
+  nextRetainMode: NextRetainMode,
+): Promise<HindsightSessionMeta> {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  return writeSessionMemoryMeta(cwd, sessionFile, { ...meta, nextRetainMode });
+}
+
+export async function clearNextSessionRetainMode(
+  cwd: string,
+  sessionFile: string | undefined,
+): Promise<HindsightSessionMeta> {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  if (meta.nextRetainMode === "normal") return meta;
+  return writeSessionMemoryMeta(cwd, sessionFile, {
+    ...meta,
+    nextRetainMode: "normal",
+  });
+}
+
+export async function addSessionMemoryTag(
+  cwd: string,
+  sessionFile: string | undefined,
+  tag: string,
+): Promise<HindsightSessionMeta> {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  return writeSessionMemoryMeta(cwd, sessionFile, { ...meta, tags: [...meta.tags, tag] });
+}
+
+export async function removeSessionMemoryTag(
+  cwd: string,
+  sessionFile: string | undefined,
+  tag: string,
+): Promise<HindsightSessionMeta> {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  return writeSessionMemoryMeta(cwd, sessionFile, {
+    ...meta,
+    tags: meta.tags.filter((existing) => existing !== cleanTag(tag)),
+  });
+}

package/node_modules/@luxusai/pi-hindsight/extensions/utils/session-operations.ts

@@ -0,0 +1,56 @@
+import {
+  addSessionMemoryTag,
+  getEffectiveSessionMemoryMode,
+  readSessionMemoryMeta,
+  removeSessionMemoryTag,
+  setNextSessionRetainMode,
+  setSessionMemoryMode,
+  setSessionRetainEnabled,
+  type SessionMemoryMode,
+} from "./session-memory-meta.js";
+
+export async function readMemorySession(cwd: string, sessionFile?: string) {
+  const meta = await readSessionMemoryMeta(cwd, sessionFile);
+  return { meta, effective: getEffectiveSessionMemoryMode(meta) };
+}
+
+export async function setMemorySessionMode(
+  cwd: string,
+  sessionFile: string | undefined,
+  mode: SessionMemoryMode,
+) {
+  const meta = await setSessionMemoryMode(cwd, sessionFile, mode);
+  return { meta, effective: getEffectiveSessionMemoryMode(meta) };
+}
+
+export async function setMemorySessionRetain(
+  cwd: string,
+  sessionFile: string | undefined,
+  enabled: boolean,
+) {
+  const meta = await setSessionRetainEnabled(cwd, sessionFile, enabled);
+  return { meta, effective: getEffectiveSessionMemoryMode(meta) };
+}
+
+export async function setNextMemoryRetainOff(cwd: string, sessionFile: string | undefined) {
+  const meta = await setNextSessionRetainMode(cwd, sessionFile, "off");
+  return { meta, effective: getEffectiveSessionMemoryMode(meta) };
+}
+
+export async function addMemorySessionTag(
+  cwd: string,
+  sessionFile: string | undefined,
+  tag: string,
+) {
+  const meta = await addSessionMemoryTag(cwd, sessionFile, tag);
+  return { meta, effective: getEffectiveSessionMemoryMode(meta) };
+}
+
+export async function removeMemorySessionTag(
+  cwd: string,
+  sessionFile: string | undefined,
+  tag: string,
+) {
+  const meta = await removeSessionMemoryTag(cwd, sessionFile, tag);
+  return { meta, effective: getEffectiveSessionMemoryMode(meta) };
+}

package/node_modules/@luxusai/pi-hindsight/extensions/utils/session.ts

@@ -0,0 +1,50 @@
+import { createHash, randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import type { AgentUseProfile } from "../types.js";
+
+const EPHEMERAL_PROCESS_SESSION_ID = randomUUID();
+
+export function stableSessionId(sessionFile: string | undefined, cwd: string): string {
+  const basis = sessionFile || `ephemeral:${cwd}:${EPHEMERAL_PROCESS_SESSION_ID}`;
+  return createHash("sha256").update(basis).digest("hex").slice(0, 16);
+}
+
+export function liveDocumentId(sessionFile: string | undefined, cwd: string): string {
+  return `pi-session:${stableSessionId(sessionFile, cwd)}`;
+}
+
+export function importDocumentId(sessionId: string, leafId: string): string {
+  return `pi-import:${sessionId}:leaf:${leafId}`;
+}
+
+export function explicitMemoryDocumentId(args: {
+  cwd: string;
+  sessionFile?: string;
+  bankId: string;
+  content: string;
+  context: string;
+}): string {
+  const digest = createHash("sha256")
+    .update(JSON.stringify({ bankId: args.bankId, content: args.content, context: args.context }))
+    .digest("hex")
+    .slice(0, 16);
+  return `pi-explicit:${stableSessionId(args.sessionFile, args.cwd)}:${digest}`;
+}
+
+export function contextLabel(
+  cwd: string,
+  sessionFile: string | undefined,
+  agentUse: AgentUseProfile = "coding",
+): string {
+  const suffix = sessionFile ? `, session ${basename(sessionFile)}` : ", ephemeral session";
+  if (agentUse === "conversation") {
+    return `Pi conversation/task session for "${basename(cwd)}"${suffix}`;
+  }
+  return `Pi coding session for repo "${basename(cwd)}"${suffix}`;
+}
+
+export function getSessionFile(ctx: {
+  sessionManager?: { getSessionFile?: () => string | undefined };
+}): string | undefined {
+  return ctx.sessionManager?.getSessionFile?.();
+}

package/node_modules/@luxusai/pi-hindsight/extensions/utils/status-fields.ts

@@ -0,0 +1,167 @@
+import { isMemorySetupComplete } from "../config/setup-gate.js";
+import { DEFAULT_CONFIG } from "../config/config-defaults.js";
+import { formatProjectIdentityForStatus, resolveProjectIdentity } from "../banks/banking.js";
+import type { ResolvedConfig } from "../types.js";
+
+export type StatusFieldTone = "default" | "custom" | "warn" | "info";
+
+export interface StatusField {
+  key: string;
+  label: string;
+  value: string;
+  tone: StatusFieldTone;
+  source?: string;
+}
+
+export interface StatusFieldContext {
+  cwd: string;
+  projectBankId: string;
+  queueLength?: number;
+  deadLetterLength?: number;
+  healthOk?: boolean;
+  healthError?: string;
+}
+
+function eq(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Build read-only status fields with tone vs defaults (ADR-005).
+ * warn = broken/setup incomplete; custom = non-default valid; info = intentionally off; default = quiet.
+ */
+export function buildStatusFields(config: ResolvedConfig, ctx: StatusFieldContext): StatusField[] {
+  const fields: StatusField[] = [];
+  const setupOk = isMemorySetupComplete(config, ctx.cwd);
+  const project = resolveProjectIdentity(ctx.cwd, config);
+
+  fields.push({
+    key: "setup",
+    label: "Setup",
+    value: setupOk ? "complete" : "required",
+    tone: setupOk ? "default" : "warn",
+  });
+
+  fields.push({
+    key: "enabled",
+    label: "Extension",
+    value: config.enabled ? "enabled" : "disabled",
+    tone:
+      config.enabled === DEFAULT_CONFIG.enabled ? "default" : config.enabled ? "custom" : "info",
+  });
+
+  fields.push({
+    key: "baseUrl",
+    label: "Hindsight URL",
+    value: config.hindsight.baseUrl,
+    tone: config.hindsight.baseUrl === DEFAULT_CONFIG.hindsight.baseUrl ? "default" : "custom",
+  });
+
+  if (ctx.healthOk === false) {
+    fields.push({
+      key: "health",
+      label: "Server",
+      value: ctx.healthError ? `unreachable: ${ctx.healthError}` : "unreachable",
+      tone: "warn",
+    });
+  } else if (ctx.healthOk === true) {
+    fields.push({ key: "health", label: "Server", value: "reachable", tone: "default" });
+  }
+
+  fields.push({
+    key: "scopeMode",
+    label: "Scope mode",
+    value: config.scope.mode,
+    tone: config.scope.mode === DEFAULT_CONFIG.scope.mode ? "default" : "custom",
+  });
+
+  fields.push({
+    key: "sharedObservations",
+    label: "Shared observations",
+    value: config.scope.includeSharedObservations ? "include (opt-in)" : "strict project only",
+    tone: config.scope.includeSharedObservations ? "custom" : "default",
+  });
+
+  fields.push({
+    key: "projectScope",
+    label: "Project scope",
+    value: formatProjectIdentityForStatus(project),
+    tone: project.basis === "pin" ? "custom" : "default",
+  });
+
+  const codingEnabled = config.banks.project.enabled;
+  fields.push({
+    key: "codingBank",
+    label: "Coding bank",
+    value: codingEnabled
+      ? `${ctx.projectBankId}${config.banks.project.bankId ? "" : " (path-derived)"}`
+      : "disabled",
+    tone: !codingEnabled
+      ? "info"
+      : config.banks.project.bankId
+        ? "custom"
+        : setupOk
+          ? "warn"
+          : "info",
+  });
+
+  const lifeId = config.banks.user.bankId;
+  fields.push({
+    key: "lifeBank",
+    label: "Life bank",
+    value: config.banks.user.enabled ? (lifeId ?? "(no bankId)") : "disabled",
+    tone: !config.banks.user.enabled ? "info" : lifeId ? "custom" : "warn",
+  });
+
+  fields.push({
+    key: "recall",
+    label: "Auto recall",
+    value: config.recall.enabled ? "on" : "off",
+    tone: config.recall.enabled === DEFAULT_CONFIG.recall.enabled ? "default" : "custom",
+  });
+
+  fields.push({
+    key: "retain",
+    label: "Auto retain",
+    value: config.retain.enabled ? "on" : "off",
+    tone: config.retain.enabled === DEFAULT_CONFIG.retain.enabled ? "default" : "custom",
+  });
+
+  if (!eq(config.recall.maxTokens, DEFAULT_CONFIG.recall.maxTokens)) {
+    fields.push({
+      key: "recallMaxTokens",
+      label: "Recall maxTokens",
+      value: String(config.recall.maxTokens),
+      tone: "custom",
+    });
+  }
+
+  const queue = ctx.queueLength ?? 0;
+  const dead = ctx.deadLetterLength ?? 0;
+  fields.push({
+    key: "queue",
+    label: "Retain queue",
+    value: dead > 0 ? `${queue} pending, ${dead} dead-letter` : `${queue} pending`,
+    tone: dead > 0 ? "warn" : queue > 0 ? "custom" : "default",
+  });
+
+  fields.push({
+    key: "mentalModels",
+    label: "Mental model inject",
+    value: config.mentalModels.inject ? "on" : "off",
+    tone: config.mentalModels.inject === DEFAULT_CONFIG.mentalModels.inject ? "default" : "custom",
+  });
+
+  return fields;
+}
+
+/** Render fields for TUI/doctor text (tone as marker; color is TUI's job). */
+export function formatStatusFieldsText(fields: StatusField[]): string {
+  return fields
+    .map((f) => {
+      const mark =
+        f.tone === "warn" ? "!" : f.tone === "custom" ? "*" : f.tone === "info" ? "-" : " ";
+      return `${mark} ${f.label}: ${f.value}`;
+    })
+    .join("\n");
+}