@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

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

@@ -0,0 +1,207 @@
+import {
+  bankConfigOverrideSummaryLines,
+  bankSettingsTargetDisplay,
+} from "../banks/bank-settings-presenter.js";
+import type { HindsightLikeClient, ResolvedConfig } from "../types.js";
+import { redactError } from "./sanitize.js";
+
+export type StatusHealthFacts = Array<[string, string]>;
+
+type BankRoute = {
+  label: "Project bank" | "User bank";
+  location: "Project" | "User";
+  bankId: string;
+};
+const STATUS_HEALTH_TIMEOUT_MS = 1_500;
+
+async function withStatusTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${STATUS_HEALTH_TIMEOUT_MS}ms`)),
+          STATUS_HEALTH_TIMEOUT_MS,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function numberField(value: unknown, key: string): number | undefined {
+  return isRecord(value) && typeof value[key] === "number" ? value[key] : undefined;
+}
+
+function dateField(value: unknown, key: string): string | undefined {
+  return isRecord(value) && typeof value[key] === "string" ? value[key] : undefined;
+}
+
+function bankRoutes(config: ResolvedConfig, projectBankId: string): BankRoute[] {
+  return [
+    ...(config.banks.project.enabled
+      ? [{ label: "Project bank" as const, location: "Project" as const, bankId: projectBankId }]
+      : []),
+    ...(config.banks.user.enabled && config.banks.user.bankId
+      ? [
+          {
+            label: "User bank" as const,
+            location: "User" as const,
+            bankId: config.banks.user.bankId,
+          },
+        ]
+      : []),
+  ];
+}
+
+function textField(value: unknown, key: string): string | undefined {
+  return isRecord(value) && typeof value[key] === "string" ? value[key] : undefined;
+}
+
+function nestedRecord(value: unknown, key: string): Record<string, unknown> | undefined {
+  return isRecord(value) && isRecord(value[key]) ? value[key] : undefined;
+}
+
+function missionSummary(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  return value.length > 90 ? `${value.slice(0, 87)}...` : value;
+}
+
+function formatMissionConfig(configResponse: unknown): string | undefined {
+  const config = nestedRecord(configResponse, "config");
+  const overrides = nestedRecord(configResponse, "overrides");
+  const retain =
+    textField(overrides, "retain_custom_instructions") ??
+    textField(overrides, "retain_mission") ??
+    textField(config, "retain_custom_instructions") ??
+    textField(config, "retain_mission");
+  const reflect = textField(overrides, "reflect_mission") ?? textField(config, "reflect_mission");
+  const observations =
+    textField(overrides, "observations_mission") ?? textField(config, "observations_mission");
+  const parts = [
+    retain ? `retain ${missionSummary(retain)}` : undefined,
+    reflect ? `reflect ${missionSummary(reflect)}` : undefined,
+    observations ? `observations ${missionSummary(observations)}` : undefined,
+  ].filter(Boolean);
+  return parts.length ? parts.join(" · ") : undefined;
+}
+
+function formatStats(stats: unknown): string | undefined {
+  const memories = numberField(stats, "total_nodes");
+  const documents = numberField(stats, "total_documents");
+  const observations = numberField(stats, "total_observations");
+  const facts = numberField(stats, "fact_count");
+  const pending = numberField(stats, "pending_consolidation");
+  const failed = numberField(stats, "failed_consolidation");
+  const last = dateField(stats, "last_consolidated_at");
+  const lastDocument = dateField(stats, "last_document_at");
+  const parts = [
+    memories !== undefined ? `memories ${memories}` : undefined,
+    documents !== undefined ? `docs ${documents}` : undefined,
+    observations !== undefined ? `observations ${observations}` : undefined,
+    facts !== undefined ? `facts ${facts}` : undefined,
+    pending !== undefined ? `pending ${pending}` : undefined,
+    failed !== undefined ? `failed ${failed}` : undefined,
+    last ? `last consolidated ${last}` : undefined,
+    lastDocument ? `last document ${lastDocument}` : undefined,
+  ].filter(Boolean);
+  return parts.length ? parts.join(" · ") : undefined;
+}
+
+async function bankFact(client: HindsightLikeClient, route: BankRoute): Promise<StatusHealthFacts> {
+  try {
+    const profile = client.getBankProfile
+      ? await withStatusTimeout(client.getBankProfile(route.bankId), `${route.label} profile`)
+      : undefined;
+    const name =
+      isRecord(profile) && typeof profile.name === "string" ? profile.name : route.bankId;
+    const target = bankSettingsTargetDisplay({ location: route.location, bankId: route.bankId });
+    const facts: StatusHealthFacts = [[route.label, `reachable · ${name} · ${target.reviewLine}`]];
+    if (client.getBankConfig) {
+      try {
+        const config = await withStatusTimeout(
+          client.getBankConfig(route.bankId),
+          `${route.label} config`,
+        );
+        const summary = formatMissionConfig(config);
+        const overrideSummary = bankConfigOverrideSummaryLines(config).join(" · ");
+        facts.push([`${route.label} config`, overrideSummary]);
+        if (summary) facts.push([`${route.label} missions`, `db · ${summary}`]);
+      } catch (error) {
+        facts.push([`${route.label} missions`, `unavailable · ${redactError(error)}`]);
+      }
+    }
+    if (client.getBankStats) {
+      try {
+        const stats = await withStatusTimeout(
+          client.getBankStats(route.bankId),
+          `${route.label} stats`,
+        );
+        const summary = formatStats(stats);
+        if (summary) facts.push([`${route.label} stats`, summary]);
+        const failed = numberField(stats, "failed_consolidation");
+        if (failed !== undefined && failed > 0)
+          facts.push([
+            `${route.label} consolidation`,
+            `failed ${failed} · run hindsight_recover_consolidation`,
+          ]);
+      } catch (error) {
+        facts.push([`${route.label} stats`, `unavailable · ${redactError(error)}`]);
+      }
+    }
+    return facts;
+  } catch (error) {
+    return [[route.label, `unreachable · ${redactError(error)}`]];
+  }
+}
+
+async function serverVersionFact(
+  client: HindsightLikeClient,
+): Promise<[string, string] | undefined> {
+  if (!client.getVersion) return undefined;
+  try {
+    const version = await withStatusTimeout(client.getVersion(), "Hindsight version");
+    const apiVersion = textField(version, "api_version");
+    if (!apiVersion) return undefined;
+    const features = nestedRecord(version, "features");
+    const enabled = features
+      ? Object.keys(features)
+          .filter((key) => features[key] === true)
+          .sort()
+      : [];
+    return [
+      "Server version",
+      enabled.length ? `${apiVersion} · features: ${enabled.join(", ")}` : apiVersion,
+    ];
+  } catch {
+    // Version endpoint is optional enrichment; older servers lack /version.
+    return undefined;
+  }
+}
+
+export async function collectStatusHealthFacts(args: {
+  client: HindsightLikeClient;
+  config: ResolvedConfig;
+  projectBankId: string;
+}): Promise<StatusHealthFacts> {
+  const facts: StatusHealthFacts = [];
+  try {
+    if (args.client.health) await withStatusTimeout(args.client.health(), "Hindsight health");
+    facts.push(["Server", "reachable"]);
+    const versionFact = await serverVersionFact(args.client);
+    if (versionFact) facts.push(versionFact);
+  } catch (error) {
+    facts.push(["Server", `unreachable · ${redactError(error)}`]);
+  }
+
+  const routes = bankRoutes(args.config, args.projectBankId);
+  if (!routes.length) return [...facts, ["Banks", "none configured"]];
+  for (const route of routes) facts.push(...(await bankFact(args.client, route)));
+  return facts;
+}

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

@@ -0,0 +1,120 @@
+import { basename } from "node:path";
+import type { ResolvedConfig, StatusStyle } from "../types.js";
+
+export type HindsightActivity =
+  | "idle"
+  | "connected"
+  | "offline"
+  | "recalling"
+  | "recalled"
+  | "recall-empty"
+  | "recall-failed"
+  | "retaining"
+  | "retained"
+  | "retain-queued"
+  | "retain-failed"
+  | "importing"
+  | "imported"
+  | "import-queued"
+  | "import-failed";
+
+export interface HindsightStatusState {
+  projectBankId: string;
+  cwd: string;
+  activity: HindsightActivity;
+  memoryCount?: number;
+  queueRemaining?: number;
+}
+
+function truncate(value: string, max: number): string {
+  if (max <= 0) return "";
+  if (value.length <= max) return value;
+  return `${value.slice(0, Math.max(1, max - 1))}…`;
+}
+
+function shortProject(cwd: string, max: number): string {
+  return truncate(basename(cwd) || "project", max);
+}
+
+function shortBank(bankId: string, max: number): string {
+  return truncate(bankId.replace(/^pi-project-/, ""), max);
+}
+
+export function formatHindsightActivity(
+  activity: HindsightActivity,
+  memoryCount?: number,
+  queueRemaining?: number,
+): string {
+  switch (activity) {
+    case "connected":
+      return "connected";
+    case "offline":
+      return "offline";
+    case "recalling":
+      return "recalling";
+    case "recalled":
+      return memoryCount !== undefined ? `recalled:${memoryCount}` : "recalled";
+    case "recall-empty":
+      return "no-memory";
+    case "recall-failed":
+      return "recall-failed";
+    case "retaining":
+      return "retaining";
+    case "retained":
+      return queueRemaining ? `queued:${queueRemaining}` : "retained";
+    case "retain-queued":
+      return queueRemaining !== undefined ? `queued:${queueRemaining}` : "queued";
+    case "retain-failed":
+      return "retain-failed";
+    case "importing":
+      return "importing";
+    case "imported":
+      return queueRemaining ? `imported+queued:${queueRemaining}` : "imported";
+    case "import-queued":
+      return queueRemaining !== undefined ? `import-queued:${queueRemaining}` : "import-queued";
+    case "import-failed":
+      return "import-failed";
+    default:
+      return "idle";
+  }
+}
+
+function prefix(style: StatusStyle, activity: HindsightActivity): string {
+  if (style === "emoji") {
+    if (activity.includes("failed") || activity === "offline") return "🤯";
+    return "🧠";
+  }
+  if (style === "nerdfont") {
+    if (activity.includes("failed") || activity === "offline") return "󰧑";
+    if (activity === "recalling" || activity === "recalled") return "󰑓";
+    if (activity === "retaining" || activity === "retained") return "󰆓";
+    if (activity === "importing" || activity === "imported" || activity === "import-queued")
+      return "󰋺";
+    return "󰍛";
+  }
+  return "mem";
+}
+
+export function formatHindsightStatus(
+  config: ResolvedConfig,
+  state: HindsightStatusState,
+): string | undefined {
+  if (!config.enabled) return undefined;
+  const { style, detail, maxLength, showActivity } = config.status;
+  if (style === "off") return undefined;
+  const p = prefix(style, state.activity);
+  const project = shortProject(state.cwd, Math.max(4, maxLength));
+  const bank = shortBank(state.projectBankId, Math.max(8, maxLength));
+  const activity = showActivity
+    ? formatHindsightActivity(state.activity, state.memoryCount, state.queueRemaining)
+    : "idle";
+
+  let body: string;
+  if (detail === "minimal") body = "";
+  else if (detail === "project") body = bank;
+  else if (detail === "activity") body = activity;
+  else body = `${project}:${bank}:${activity}`;
+
+  const separator = style === "text" ? ":" : " ";
+  return truncate(body ? `${p}${separator}${body}` : p, maxLength);
+}

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

@@ -0,0 +1,8 @@
+export const PI_HINDSIGHT_VERSION = "0.12.0"; // x-release-please-version
+export const PI_HINDSIGHT_USER_AGENT = `pi-hindsight/${PI_HINDSIGHT_VERSION}`;
+
+export const PI_HINDSIGHT_SUPPORTED_NODE = ">=20";
+export const PI_HINDSIGHT_SUPPORTED_NPM = ">=10";
+export const PI_HINDSIGHT_CLIENT_PACKAGE = "@vectorize-io/hindsight-client";
+export const PI_HINDSIGHT_CLIENT_RANGE = "^0.9.0";
+export const PI_HINDSIGHT_SUPPORTED_TYPEBOX = ">=1.1.24 <2";

package/node_modules/@luxusai/pi-hindsight/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@luxusai/pi-hindsight",
+  "version": "0.12.0",
+  "description": "Pi extension for durable Hindsight-backed long-term memory.",
+  "keywords": [
+    "hindsight",
+    "memory",
+    "pi",
+    "pi-package"
+  ],
+  "homepage": "https://luxus.github.io/pi-hindsight/",
+  "bugs": {
+    "url": "https://github.com/luxus/pi-hindsight/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luxus/pi-hindsight.git"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/adr",
+    "docs/assets",
+    "docs/compatibility.md",
+    "docs/hindsight-core-functions.md",
+    "docs/risky-memory-modes.md",
+    "docs/next-opt-out-design.md",
+    "docs/surface-reference.md",
+    "docs/starter-mental-model-suggestions.md",
+    "docs/coding-memory-evaluation.md",
+    "docs/mission-and-mental-model-quality.md",
+    "skills"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsgo -p tsconfig.json --noEmit",
+    "typecheck:tsc": "tsc --noEmit",
+    "lint": "oxlint --type-aware --type-check extensions tests",
+    "lint:fix": "oxlint --type-aware --type-check --fix extensions tests",
+    "format": "oxfmt --check --no-error-on-unmatched-pattern \"extensions/**/*.ts\" \"tests/**/*.ts\" \"tests/**/*.mjs\" \"scripts/**/*.mjs\" \"scripts/**/*.ts\" \"docs/**/*.md\" \"README.md\" \"CONTEXT.md\" \"CONTRIBUTING.md\" \"SECURITY.md\" \"package.json\" \"package-lock.json\" \"tsconfig.json\" \"vitest.config.ts\" \".oxfmtrc.json\" \".commitlintrc.json\" \"*.yml\" \".github/**/*.yml\" \".github/**/*.md\" \"docs-site/src/content/docs/**/*.md\" \"docs-site/src/content/docs/**/*.mdx\" \"astro.config.mjs\" \"docs-site/src/content.config.ts\"",
+    "format:fix": "oxfmt --write --no-error-on-unmatched-pattern \"extensions/**/*.ts\" \"tests/**/*.ts\" \"tests/**/*.mjs\" \"scripts/**/*.mjs\" \"scripts/**/*.ts\" \"docs/**/*.md\" \"README.md\" \"CONTEXT.md\" \"CONTRIBUTING.md\" \"SECURITY.md\" \"package.json\" \"package-lock.json\" \"tsconfig.json\" \"vitest.config.ts\" \".oxfmtrc.json\" \".commitlintrc.json\" \"*.yml\" \".github/**/*.yml\" \".github/**/*.md\" \"docs-site/src/content/docs/**/*.md\" \"docs-site/src/content/docs/**/*.mdx\" \"astro.config.mjs\" \"docs-site/src/content.config.ts\"",
+    "surface-reference": "tsx scripts/generate-surface-reference.ts",
+    "surface-reference:check": "tsx scripts/generate-surface-reference.ts --check",
+    "check": "npm run docs:check && npm run format && npm run lint && npm run typecheck && npm test",
+    "check:ci": "npm run check && npm run check:coverage",
+    "check:release": "npm run check && npm run check:coverage && npm run typecheck:tsc && npm run audit:signatures && npm run pack:verify && npm run smoke:hindsight",
+    "install-hooks": "node scripts/install-hooks.mjs",
+    "prepare": "npm run install-hooks",
+    "precommit": "npm run check",
+    "test": "vitest run",
+    "smoke:hindsight": "tsx scripts/smoke-hindsight.ts",
+    "bench:memory": "tsx scripts/bench-memory.ts",
+    "changelog": "node scripts/generate-changelog.mjs",
+    "version": "npm run changelog && npm run format:fix && git add CHANGELOG.md",
+    "test:coverage": "vitest run --coverage",
+    "check:coverage": "npm run test:coverage",
+    "pack:verify": "npm run release:verify && npm pack --dry-run && node scripts/install-smoke.mjs",
+    "audit:signatures": "npm audit signatures",
+    "release:verify": "node scripts/verify-release.mjs",
+    "pr:check": "node scripts/check-pr-body.mjs",
+    "docs:dev": "astro dev",
+    "docs:build": "astro build",
+    "docs:links": "node scripts/check-docs.mjs",
+    "docs:check": "npm run surface-reference:check && npm run code-map:check && npm run docs:links && npm run docs:build",
+    "code-map": "node scripts/generate-code-map.mjs",
+    "code-map:check": "node scripts/generate-code-map.mjs --check"
+  },
+  "dependencies": {
+    "@vectorize-io/hindsight-client": "^0.9.0",
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "^0.41.3",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@earendil-works/pi-agent-core": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
+    "@mermaid-js/layout-elk": "^0.2.1",
+    "@types/node": "^25.9.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitest/coverage-v8": "^4.1.5",
+    "astro": "^7.0.6",
+    "astro-mermaid": "^2.0.1",
+    "mermaid": "^11.14.0",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.61.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "starlight-llm-button": "^0.0.8",
+    "tsx": "4.23.0",
+    "typebox": "1.3.9",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": ">=1.1.24 <2"
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=10"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/node_modules/@luxusai/pi-hindsight/skills/hindsight-memory-doctor/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: hindsight-memory-doctor
+description: >
+  Self-check Pi Hindsight memory when the user is frustrated, confused, or
+  complains about memory quality (wrong prefs, missing context, "it forgot",
+  "never ask questions" vs wants questions, empty inject, wrong project).
+  Inspect status/scope/mental models/bank missions, compare to quality docs,
+  propose dry-run fixes. Trigger on memory complaints, "memory is wrong",
+  "forgot", "why did it inject", /hindsight-memory-doctor, or conflict with
+  recalled/MM content. Do NOT run every turn.
+---
+
+# Hindsight memory doctor
+
+When the user is **upset or skeptical about memory**, behave like a careful human under conflict: **stop, inspect, question the memory stack**, then propose a small fix. Do not argue from broken inject. Do not mutate banks silently.
+
+Authoritative criteria: `docs/mission-and-mental-model-quality.md` (packaged; also docs-site _Mission and mental-model quality_).
+
+## Trigger (yes)
+
+- User complains about memory / Hindsight / inject / prefs / “forgot” / wrong project context
+- Injected MM or recall **contradicts** the user (e.g. “do not ask questions” vs wants high-signal questions)
+- User asks why memory looks wrong or empty
+- Explicit `/skill:hindsight-memory-doctor`
+
+## Do not trigger
+
+- Normal coding with healthy inject
+- Single imperfect recall hit
+- Every turn “maybe refresh?”
+
+## Workflow (always)
+
+1. **Acknowledge** the complaint in one line. Treat it as a possible **system** issue, not only user error.
+2. **Inspect** (tools; no dry-run needed for reads):
+   - `hindsight_status`
+   - `hindsight_scope`
+   - `hindsight_mental_model` action=list (coding bank; life/user if enabled)
+   - `hindsight_mental_model` action=get for broken/suspicious ids
+   - `hindsight_bank` action=get for coding (and life if enabled) — missions
+3. **Score against the quality guide** (priority order):
+   1. Broken/empty MM content (`#`, empty, Generating…) — prefs MMs may need `fact_types` world+experience+observation, not observation-only
+   2. Prefs contradict the user
+   3. Missing starters for **this** `project:<id>`
+   4. Fat inject / truncation
+   5. Mission noise (only if multi-session pattern)
+   6. Polish-only → skip
+4. **Propose** a short plan (max 3 actions). Prefer:
+   - explicit retain of the **correct** durable fact
+   - refresh (or clear+refresh if delta-drift)
+   - create missing starters for this project
+   - mission patch only if extraction is systematically wrong
+5. **Dry-run first** for any mutation (`hindsight_mental_model` / `hindsight_bank` dryRun true). Apply only after user ok (`dryRun: false` or hub).
+6. **Verify** list/get again. Note inject cache may lag (`mentalModels.cacheTtlMs`, often ~5 min) — new session or wait.
+
+## Output shape
+
+```text
+Memory doctor
+- What I checked: …
+- What’s wrong (priority): …
+- Proposed fixes (dry-run): …
+- Not doing: … (noise / other projects / silent rewrite)
+```
+
+## Hard rules
+
+- Never silent create/update/delete of mental models or missions.
+- Never edit another project’s `project:<other>` models to “fix” this session.
+- Same-turn retain + rely-on-recall is invalid; refresh after retain has landed.
+- If tools unavailable / setup incomplete: say so and point to `/hindsight` setup.
+
+## Optional user invoke
+
+`/skill:hindsight-memory-doctor` — run full workflow once.