@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

package/node_modules/@luxusai/pi-hindsight/extensions/banks/knowledge-page-seed.ts

@@ -1,176 +0,0 @@
-/**
- * Idempotent knowledge-page taxonomy seeding for coding banks.
- *
- * Pages are created via the knowledge-base API (not bare mental_models in the bank template).
- * When the client/server lacks knowledge-page methods, seeding degrades cleanly.
- */
-import type { HindsightLikeClient } from "../types.js";
-import {
-  KNOWLEDGE_PAGE_MAX_TOKENS,
-  KNOWLEDGE_PAGE_SEEDS,
-  KNOWLEDGE_PAGE_TRIGGER,
-  type KnowledgePageSeed,
-} from "./retain-strategies.js";
-
-export const KNOWLEDGE_PAGES_UNAVAILABLE = "knowledge_pages_unavailable" as const;
-
-export class KnowledgePagesUnavailableError extends Error {
-  readonly code = KNOWLEDGE_PAGES_UNAVAILABLE;
-  constructor(message = "Hindsight server does not support knowledge pages") {
-    super(message);
-    this.name = "KnowledgePagesUnavailableError";
-  }
-}
-
-export interface SeedKnowledgePagesArgs {
-  client: HindsightLikeClient;
-  bankId: string;
-  /** Extra tags merged onto each page (e.g. source:pi, project:<id>). */
-  baseTags?: string[];
-  dryRun?: boolean;
-  /** Override seed list (tests). */
-  seeds?: readonly KnowledgePageSeed[];
-}
-
-export interface SeedKnowledgePagesResult {
-  bankId: string;
-  dryRun: boolean;
-  available: boolean;
-  reason?: typeof KNOWLEDGE_PAGES_UNAVAILABLE | "no_create_method";
-  wouldCreate?: Array<{ name: string; tags: string[] }>;
-  created: Array<{ name: string; result?: unknown }>;
-  skippedExisting: string[];
-  errors: Array<{ name: string; error: string }>;
-}
-
-function isNotFoundOrUnavailable(error: unknown): boolean {
-  if (error instanceof KnowledgePagesUnavailableError) return true;
-  if (typeof error !== "object" || !error) return false;
-  const fields = error as {
-    status?: unknown;
-    statusCode?: unknown;
-    code?: unknown;
-    message?: unknown;
-  };
-  const status = fields.status ?? fields.statusCode;
-  if (status === 404 || status === 405 || status === 501) return true;
-  if (fields.code === KNOWLEDGE_PAGES_UNAVAILABLE) return true;
-  const msg = typeof fields.message === "string" ? fields.message : "";
-  return /\b404\b|\b405\b|\b501\b|not found|knowledge.?pages?.*(unavail|not support)/i.test(msg);
-}
-
-function collectPageNames(tree: unknown, out = new Set<string>()): Set<string> {
-  if (!tree) return out;
-  const nodes = Array.isArray(tree)
-    ? tree
-    : typeof tree === "object" && tree !== null
-      ? ((tree as { roots?: unknown[]; children?: unknown[] }).roots ??
-        (tree as { children?: unknown[] }).children ??
-        [])
-      : [];
-  for (const node of nodes) {
-    if (!node || typeof node !== "object") continue;
-    const rec = node as { kind?: string; name?: string; children?: unknown[] };
-    if (rec.kind === "page" && typeof rec.name === "string") out.add(rec.name);
-    if (Array.isArray(rec.children)) collectPageNames(rec.children, out);
-  }
-  return out;
-}
-
-/**
- * Seed the fixed five-page knowledge taxonomy. Idempotent by page name (skips existing).
- * Never throws for capability gaps — returns available:false instead.
- */
-export async function seedKnowledgePages(
-  args: SeedKnowledgePagesArgs,
-): Promise<SeedKnowledgePagesResult> {
-  const dryRun = args.dryRun ?? false;
-  const seeds = args.seeds ?? KNOWLEDGE_PAGE_SEEDS;
-  const baseTags = args.baseTags ?? ["source:pi"];
-  const empty: SeedKnowledgePagesResult = {
-    bankId: args.bankId,
-    dryRun,
-    available: false,
-    created: [],
-    skippedExisting: [],
-    errors: [],
-  };
-
-  if (!args.client.createKnowledgePage) {
-    return { ...empty, reason: "no_create_method" };
-  }
-
-  let existing = new Set<string>();
-  if (args.client.getKnowledgeBaseTree) {
-    try {
-      const tree = await args.client.getKnowledgeBaseTree(args.bankId);
-      existing = collectPageNames(tree);
-    } catch (error) {
-      if (isNotFoundOrUnavailable(error)) {
-        return { ...empty, reason: KNOWLEDGE_PAGES_UNAVAILABLE };
-      }
-      // Tree probe failed for another reason — still try create (best effort).
-    }
-  }
-
-  const wouldCreate: Array<{ name: string; tags: string[] }> = [];
-  const created: Array<{ name: string; result?: unknown }> = [];
-  const skippedExisting: string[] = [];
-  const errors: Array<{ name: string; error: string }> = [];
-
-  for (const seed of seeds) {
-    if (existing.has(seed.name)) {
-      skippedExisting.push(seed.name);
-      continue;
-    }
-    const tags = [...new Set([...seed.tags, ...baseTags])];
-    wouldCreate.push({ name: seed.name, tags });
-    if (dryRun) continue;
-    try {
-      const result = await args.client.createKnowledgePage!(
-        args.bankId,
-        seed.name,
-        seed.source_query,
-        {
-          tags,
-          maxTokens: KNOWLEDGE_PAGE_MAX_TOKENS,
-          trigger: {
-            mode: "delta",
-            refreshAfterConsolidation: KNOWLEDGE_PAGE_TRIGGER.refresh_after_consolidation,
-            factTypes: [...KNOWLEDGE_PAGE_TRIGGER.fact_types],
-            excludeMentalModels: true,
-          },
-        },
-      );
-      created.push({ name: seed.name, result });
-      existing.add(seed.name);
-    } catch (error) {
-      if (isNotFoundOrUnavailable(error)) {
-        return {
-          bankId: args.bankId,
-          dryRun,
-          available: false,
-          reason: KNOWLEDGE_PAGES_UNAVAILABLE,
-          wouldCreate,
-          created,
-          skippedExisting,
-          errors,
-        };
-      }
-      errors.push({
-        name: seed.name,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  return {
-    bankId: args.bankId,
-    dryRun,
-    available: true,
-    ...(dryRun ? { wouldCreate } : {}),
-    created,
-    skippedExisting,
-    errors,
-  };
-}

package/node_modules/@luxusai/pi-hindsight/extensions/banks/retain-strategies.ts

@@ -1,178 +0,0 @@
-/**
- * Named retain strategies and knowledge entity-label taxonomy.
- *
- * Aligned with @vectorize-io/hindsight-coding-agents bank-template practices, adapted for Pi:
- * default strategy is conversation (live Pi sessions), not git.
- * Pages are seeded separately (knowledge-base API) — not as bare mental_models in the template.
- */
-
-/** Per-strategy retain config accepted by BankTemplateConfig.retain_strategies. */
-export type RetainStrategyConfig = {
-  retain_mission?: string;
-  retain_extraction_mode?: string;
-  retain_chunk_size?: number;
-  retain_custom_instructions?: string;
-};
-
-export const GIT_RETAIN_MISSION =
-  "You are ingesting a single git commit: its message and its full diff. Extract the concrete " +
-  "technical DECISION and the CAUSE/INVARIANT it encodes, bound to the specific code entities " +
-  "(functions, methods, files) and behaviors it changes. Preserve exact identifiers, paths, and " +
-  "literal values verbatim. Capture both WHAT changed and WHY. Issue/PR references (#123, GH-123) " +
-  "are load-bearing: keep them VERBATIM in the fact text and emit each as an ENTITY.";
-
-export const GITLOG_RETAIN_MISSION =
-  "You are ingesting an aggregated block of git commit MESSAGES ONLY (no diffs) — the project's " +
-  "recent commit-message history, newest first. Extract the project's INITIATIVES, FEATURES, " +
-  "ENHANCEMENTS, and notable themes over time. Do NOT extract per-line code detail. Group related " +
-  "commits into a coherent initiative/theme where messages make that clear; preserve exact " +
-  "identifiers and issue/PR references VERBATIM and emit each as an ENTITY.";
-
-export const CONVERSATION_RETAIN_MISSION =
-  "You are ingesting a developer conversation as a JSONL transcript (one {role, content} turn per line): the " +
-  "user's requests, the assistant's narration, and compact tool-action turns (name + target only). " +
-  "It may be a SHORT decision chat or a LONG working session — scale facts to the substance, never " +
-  "to the message count. Extract the FEWEST facts that capture the OUTCOME: settled DECISIONS and " +
-  "their exact rules/values (quote literals VERBATIM); concrete CHANGES to specific code entities; " +
-  "problems and how they were resolved; conventions or invariants established; at most one fact for " +
-  "a notable REJECTED alternative. CRITICAL: a conversation REVISES itself — record ONLY the FINAL " +
-  "state as what is in effect; a superseded proposal appears ONLY inside the rejected fact, NEVER as " +
-  "its own 'decided' fact; if the same setting changes several times keep only the LAST. Do NOT emit " +
-  "one fact per message or per intermediate proposal. Keep issue/PR references VERBATIM and emit each " +
-  "as an ENTITY. Do not invent; capture only what was actually settled.";
-
-export const DOCUMENT_RETAIN_MISSION =
-  "You are ingesting a standalone document (notes, docs, or structural findings). Extract the " +
-  "concrete facts, concepts, and structure it describes. Preserve identifiers and paths verbatim.";
-
-export const PI_RETAIN_STRATEGIES: Record<string, RetainStrategyConfig> = {
-  git: {
-    retain_mission: GIT_RETAIN_MISSION,
-    retain_extraction_mode: "verbose",
-  },
-  gitlog: {
-    retain_mission: GITLOG_RETAIN_MISSION,
-    retain_extraction_mode: "verbose",
-    retain_chunk_size: 12_000,
-  },
-  conversation: {
-    retain_mission: CONVERSATION_RETAIN_MISSION,
-    retain_extraction_mode: "verbose",
-    retain_chunk_size: 12_000,
-  },
-  document: {
-    retain_mission: DOCUMENT_RETAIN_MISSION,
-    retain_extraction_mode: "verbose",
-    retain_chunk_size: 12_000,
-  },
-  survey: {
-    retain_extraction_mode: "custom",
-    retain_custom_instructions:
-      "This document belongs to a Hindsight codebase-survey lifecycle. Apply ONE of two rules: " +
-      "(1) If the content is an internal status marker — it says it is an internal marker, or " +
-      "merely announces that a survey started/completed — extract NOTHING: return an empty list of facts. " +
-      "(2) Otherwise the content is survey FINDINGS: extract concrete structural facts (components, " +
-      "responsibilities, conventions, tech stack), preserving identifiers verbatim.",
-    retain_chunk_size: 12_000,
-  },
-};
-
-/** Fixed knowledge-tier entity labels (tag: true → knowledge:<value> on facts). */
-export const KNOWLEDGE_ENTITY_LABELS: {
-  key: string;
-  type: "multi-values";
-  optional: boolean;
-  tag: boolean;
-  description: string;
-  values: Array<{ value: string; description: string }>;
-} = {
-  key: "knowledge",
-  type: "multi-values",
-  optional: true,
-  tag: true,
-  description:
-    "Routing labels for this project's Hindsight KNOWLEDGE PAGES — curated summaries of durable " +
-    "engineering knowledge. Mark a fact only when it is durable, reusable knowledge a developer " +
-    "would still want in future sessions. Leave EMPTY for routine or transient facts. MOST facts " +
-    "should get no label here.",
-  values: [
-    {
-      value: "feature-work",
-      description:
-        "A new feature, initiative, or enhancement being planned or built — not routine bug-fixes.",
-    },
-    {
-      value: "decision",
-      description: "A technical decision that will constrain future work, with its rationale.",
-    },
-    {
-      value: "convention",
-      description:
-        "An established way this project does things — naming, structure, testing, or patterns.",
-    },
-    {
-      value: "component",
-      description:
-        "What a module, file, service, or subsystem is responsible for, or how components relate.",
-    },
-    {
-      value: "concept",
-      description:
-        "A domain concept, key abstraction, or project vocabulary a contributor must understand.",
-    },
-  ],
-};
-
-/** Seed taxonomy for knowledge pages (used by knowledge seed path; not bare mental models). */
-export interface KnowledgePageSeed {
-  name: string;
-  source_query: string;
-  tags: string[];
-}
-
-export const KNOWLEDGE_PAGE_SEEDS: readonly KnowledgePageSeed[] = [
-  {
-    name: "Component map",
-    source_query:
-      "From this project's commit history and past discussions, what are the main " +
-      "components/modules/subsystems, what is each responsible for, and how do they relate?",
-    tags: ["knowledge:component"],
-  },
-  {
-    name: "Core concepts",
-    source_query:
-      "What are the core concepts, domain abstractions, and key entities in this project — " +
-      "the vocabulary a developer must understand?",
-    tags: ["knowledge:concept"],
-  },
-  {
-    name: "Conventions and patterns",
-    source_query:
-      "What conventions, idioms, and recurring patterns does this project follow — testing, " +
-      "error handling, naming, structure, and how changes are typically made?",
-    tags: ["knowledge:convention"],
-  },
-  {
-    name: "Key decisions and rationale",
-    source_query:
-      "What are the significant technical decisions made in this project and the rationale " +
-      "behind them — the durable 'why we do it this way' a developer should know?",
-    tags: ["knowledge:decision"],
-  },
-  {
-    name: "Initiatives and enhancements",
-    source_query:
-      "Based on this repository's history and discussions, what are the major initiatives, " +
-      "features, and enhancements the project has worked on? Summarize themes over time.",
-    tags: ["knowledge:feature-work"],
-  },
-] as const;
-
-export const KNOWLEDGE_PAGE_MAX_TOKENS = 4096;
-export const KNOWLEDGE_PAGE_TRIGGER = {
-  fact_types: ["world", "experience", "observation"] as const,
-  refresh_after_consolidation: true,
-};
-
-/** Default strategy for live Pi session retains. */
-export const LIVE_SESSION_RETAIN_STRATEGY = "conversation" as const;

package/node_modules/@luxusai/pi-hindsight/extensions/client/client-retry.ts

@@ -1,41 +0,0 @@
-export interface HindsightRestError extends Error {
-  status?: number;
-  body?: unknown;
-}
-
-export function isRetryableError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  const status =
-    (error as HindsightRestError).status ?? (error as { statusCode?: number }).statusCode;
-  if (typeof status === "number" && status >= 500) return true;
-  if (error.message.includes("timed out")) return true;
-  if (error.message.includes("fetch failed")) return true;
-  if (error.message.includes("ECONNREFUSED")) return true;
-  if (error.message.includes("ENOTFOUND")) return true;
-  if (error.message.includes("ETIMEDOUT")) return true;
-  if (error.message.includes("ECONNRESET")) return true;
-  return false;
-}
-
-export async function withRetry<T>(
-  operation: string,
-  fn: () => Promise<T>,
-  maxRetries = 3,
-  baseDelayMs = 1000,
-): Promise<T> {
-  let lastError: Error | undefined;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    if (attempt > 0) {
-      const jitter = Math.random() * baseDelayMs * 0.5;
-      const delay = baseDelayMs * 2 ** (attempt - 1) + jitter;
-      await new Promise((resolve) => setTimeout(resolve, delay));
-    }
-    try {
-      return await fn();
-    } catch (error) {
-      if (!isRetryableError(error)) throw error;
-      lastError = error as Error;
-    }
-  }
-  throw lastError ?? new Error(`${operation} failed after retries`);
-}