@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

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

@@ -0,0 +1,386 @@
+import {
+  CLIENT_VERSION,
+  HindsightClient,
+  HindsightError,
+  createClient,
+  createConfig,
+  sdk,
+} from "@vectorize-io/hindsight-client";
+import type { BankTemplateManifest, Client, ReflectRequest } from "@vectorize-io/hindsight-client";
+import { redactError } from "../utils/sanitize.js";
+import type { HindsightLikeClient, ResolvedConfig } from "../types.js";
+import { PI_HINDSIGHT_USER_AGENT } from "../version.js";
+import { withRetry } from "./client-retry.js";
+import { installFetchRequestCompat } from "./fetch-compat.js";
+import { withTimeout } from "./timeout.js";
+
+type ReflectOptions = Parameters<HindsightLikeClient["reflect"]>[2];
+type RetainOptions = Parameters<HindsightLikeClient["retain"]>[2];
+
+function sdkHeaders(config: ResolvedConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    "User-Agent": PI_HINDSIGHT_USER_AGENT,
+  };
+  if (config.hindsight.apiKey) headers.Authorization = `Bearer ${config.hindsight.apiKey}`;
+  return headers;
+}
+
+function createLowLevelClient(config: ResolvedConfig): Client {
+  return createClient(
+    createConfig({
+      baseUrl: config.hindsight.baseUrl.replace(/\/$/, ""),
+      headers: sdkHeaders(config),
+    }),
+  );
+}
+
+function unwrapSdkResponse<T>(
+  response: { data?: T; error?: unknown; response?: Response },
+  operation: string,
+): T {
+  if (response.data !== undefined) return response.data;
+  const error = response.error as { detail?: unknown; message?: string } | undefined;
+  const statusCode = response.response?.status;
+  const details = error?.detail ?? error?.message ?? error;
+  throw new HindsightError(`${operation} failed: ${JSON.stringify(details)}`, statusCode, details);
+}
+
+function reflectInclude(options: ReflectOptions): ReflectRequest["include"] | undefined {
+  if (options?.includeFacts === undefined && options?.includeToolCalls === undefined) {
+    return undefined;
+  }
+  const include: NonNullable<ReflectRequest["include"]> = {};
+  if (options?.includeFacts !== undefined) {
+    include.facts = options.includeFacts ? {} : null;
+  }
+  if (options?.includeToolCalls !== undefined) {
+    include.tool_calls = options.includeToolCalls
+      ? options.includeToolCallOutput === false
+        ? { output: false }
+        : {}
+      : null;
+  }
+  return include;
+}
+
+function reflectRequestBody(query: string, options: ReflectOptions | undefined): ReflectRequest {
+  const body: ReflectRequest = {
+    query,
+    budget: options?.budget ?? "low",
+  };
+  if (options?.context) body.context = options.context;
+  if (options?.maxTokens !== undefined) body.max_tokens = options.maxTokens;
+  if (options?.responseSchema) body.response_schema = options.responseSchema;
+  if (options?.factTypes) body.fact_types = options.factTypes;
+  if (options?.excludeMentalModels !== undefined) {
+    body.exclude_mental_models = options.excludeMentalModels;
+  }
+  if (options?.excludeMentalModelIds) {
+    body.exclude_mental_model_ids = options.excludeMentalModelIds;
+  }
+  if (options?.tagGroups) body.tag_groups = options.tagGroups;
+  else if (options?.tags) body.tags = options.tags;
+  if (!options?.tagGroups && options?.tagsMatch) body.tags_match = options.tagsMatch;
+  const include = reflectInclude(options);
+  if (include) body.include = include;
+  return body;
+}
+
+function retainBatchItem(content: string, options: RetainOptions) {
+  return {
+    content,
+    ...(options?.timestamp ? { timestamp: options.timestamp } : {}),
+    ...(options?.context ? { context: options.context } : {}),
+    ...(options?.metadata ? { metadata: options.metadata } : {}),
+    ...(options?.documentId ? { document_id: options.documentId } : {}),
+    ...(options?.entities?.length ? { entities: options.entities } : {}),
+    ...(options?.tags ? { tags: options.tags } : {}),
+    ...(options?.observationScopes?.length
+      ? { observation_scopes: options.observationScopes }
+      : {}),
+    ...(options?.updateMode ? { update_mode: options.updateMode } : {}),
+    ...(options?.strategy ? { strategy: options.strategy } : {}),
+  };
+}
+
+function retainSingle(
+  raw: HindsightClient,
+  bankId: string,
+  content: string,
+  options: RetainOptions,
+  signal: AbortSignal,
+) {
+  if (options?.documentTags?.length) {
+    return raw.retainBatch(bankId, [retainBatchItem(content, options)], {
+      ...(options.async !== undefined ? { async: options.async } : {}),
+      ...(options.async === true && options.operationId != null
+        ? { operationId: options.operationId }
+        : {}),
+      documentTags: options.documentTags,
+      signal,
+    });
+  }
+
+  const { documentTags: _documentTags, signal: _signal, ...retainOptions } = options ?? {};
+  return raw.retain(bankId, content, { ...retainOptions, signal });
+}
+
+async function reflect(
+  args: {
+    raw: HindsightClient;
+    lowLevel: Client;
+    bankId: string;
+    query: string;
+    options: ReflectOptions;
+  },
+  signal: AbortSignal,
+): Promise<unknown> {
+  if (args.options?.maxTokens !== undefined) {
+    const response = await sdk.reflect({
+      client: args.lowLevel,
+      path: { bank_id: args.bankId },
+      body: reflectRequestBody(args.query, args.options),
+      signal,
+    });
+    return unwrapSdkResponse(response, "reflect");
+  }
+
+  return args.raw.reflect(args.bankId, args.query, { ...args.options, signal });
+}
+
+async function importBankTemplate(
+  lowLevel: Client,
+  bankId: string,
+  manifest: BankTemplateManifest,
+  options: { dryRun?: boolean } | undefined,
+  signal: AbortSignal,
+): Promise<unknown> {
+  const response = await sdk.importBankTemplate({
+    client: lowLevel,
+    path: { bank_id: bankId },
+    ...(options?.dryRun ? { query: { dry_run: true } } : {}),
+    // The generated SDK types `body` as `never` for this endpoint: the OpenAPI schema
+    // declares a raw JSON object rather than a typed model. The request body is still the
+    // documented BankTemplateManifest shape (Hindsight's Bank Templates API docs).
+    body: manifest as never,
+    signal,
+  });
+  return unwrapSdkResponse(response, "importBankTemplate");
+}
+
+export function createHindsightClient(config: ResolvedConfig): HindsightLikeClient {
+  installFetchRequestCompat();
+
+  const raw = new HindsightClient({
+    baseUrl: config.hindsight.baseUrl,
+    ...(config.hindsight.apiKey ? { apiKey: config.hindsight.apiKey } : {}),
+    userAgent: PI_HINDSIGHT_USER_AGENT,
+  });
+  const lowLevel = createLowLevelClient(config);
+  const timeoutMs = config.hindsight.timeoutMs;
+
+  return {
+    retain: (bankId, content, options) =>
+      withTimeout(
+        "hindsight retain",
+        timeoutMs,
+        (signal) => retainSingle(raw, bankId, content, options, signal),
+        options?.signal,
+      ),
+    retainBatch: (...args) =>
+      withTimeout(
+        "hindsight retainBatch",
+        timeoutMs,
+        (signal) => {
+          const [bankId, items, options] = args;
+          return raw.retainBatch(bankId, items, { ...options, signal });
+        },
+        args[2]?.signal,
+      ),
+    recall: (...args) => {
+      const [bankId, query, options] = args;
+      return withTimeout(
+        "hindsight recall",
+        timeoutMs,
+        (signal) => raw.recall(bankId, query, { ...options, signal }),
+        options?.signal,
+      );
+    },
+    reflect: (bankId, query, options) =>
+      withTimeout(
+        "hindsight reflect",
+        timeoutMs,
+        (signal) => reflect({ raw, lowLevel, bankId, query, options }, signal),
+        options?.signal,
+      ),
+    createBank: (...args) =>
+      withTimeout("hindsight createBank", timeoutMs, (signal) => {
+        const [bankId, options] = args;
+        return raw.createBank(bankId, { ...options, signal });
+      }),
+    getBankProfile: (...args) =>
+      withTimeout("hindsight getBankProfile", timeoutMs, (signal) =>
+        withRetry("getBankProfile", () => raw.getBankProfile(args[0], { signal })),
+      ),
+    getBankStats: (bankId) =>
+      withTimeout("hindsight getBankStats", timeoutMs, (signal) =>
+        withRetry("getBankStats", async () => {
+          const response = await sdk.getAgentStats({
+            client: lowLevel,
+            path: { bank_id: bankId },
+            signal,
+          });
+          return unwrapSdkResponse(response, "getBankStats");
+        }),
+      ),
+    getBankConfig: (bankId) =>
+      withTimeout("hindsight getBankConfig", timeoutMs, (signal) =>
+        withRetry("getBankConfig", () => raw.getBankConfig(bankId, { signal })),
+      ),
+    importBankTemplate: (bankId, manifest, options) =>
+      withTimeout(
+        "hindsight importBankTemplate",
+        timeoutMs,
+        (signal) => importBankTemplate(lowLevel, bankId, manifest, options, signal),
+        options?.signal,
+      ),
+    listMentalModels: (bankId, options) =>
+      withTimeout(
+        "hindsight listMentalModels",
+        timeoutMs,
+        (signal) => raw.listMentalModels(bankId, { ...options, signal }),
+        options?.signal,
+      ),
+    getMentalModel: (bankId, mentalModelId, options) =>
+      withTimeout(
+        "hindsight getMentalModel",
+        timeoutMs,
+        (signal) => raw.getMentalModel(bankId, mentalModelId, { ...options, signal }),
+        options?.signal,
+      ),
+    createMentalModel: (bankId, name, sourceQuery, options) =>
+      withTimeout(
+        "hindsight createMentalModel",
+        timeoutMs,
+        (signal) => raw.createMentalModel(bankId, name, sourceQuery, { ...options, signal }),
+        options?.signal,
+      ),
+    updateMentalModel: (bankId, mentalModelId, options) =>
+      withTimeout(
+        "hindsight updateMentalModel",
+        timeoutMs,
+        (signal) => raw.updateMentalModel(bankId, mentalModelId, { ...options, signal }),
+        options?.signal,
+      ),
+    refreshMentalModel: (bankId, mentalModelId, options) =>
+      withTimeout(
+        "hindsight refreshMentalModel",
+        timeoutMs,
+        (signal) => raw.refreshMentalModel(bankId, mentalModelId, { ...options, signal }),
+        options?.signal,
+      ),
+    deleteMentalModel: (bankId, mentalModelId, options) =>
+      withTimeout(
+        "hindsight deleteMentalModel",
+        timeoutMs,
+        async (signal) => {
+          if (options?.dryRun) {
+            return { dryRun: true, bankId, mentalModelId, wouldDelete: true };
+          }
+          await raw.deleteMentalModel(bankId, mentalModelId, { signal });
+          return { deleted: true, bankId, mentalModelId };
+        },
+        options?.signal,
+      ),
+    getKnowledgeBaseTree: (bankId, options) =>
+      withTimeout(
+        "hindsight getKnowledgeBaseTree",
+        timeoutMs,
+        (signal) => raw.getKnowledgeBaseTree(bankId, { ...options, signal }),
+        options?.signal,
+      ),
+    createKnowledgeFolder: (bankId, name, options) =>
+      withTimeout(
+        "hindsight createKnowledgeFolder",
+        timeoutMs,
+        (signal) => raw.createKnowledgeFolder(bankId, name, { ...options, signal }),
+        options?.signal,
+      ),
+    createKnowledgePage: (bankId, name, sourceQuery, options) =>
+      withTimeout(
+        "hindsight createKnowledgePage",
+        timeoutMs,
+        (signal) => raw.createKnowledgePage(bankId, name, sourceQuery, { ...options, signal }),
+        options?.signal,
+      ),
+    getKnowledgePage: (bankId, pageId, options) =>
+      withTimeout(
+        "hindsight getKnowledgePage",
+        timeoutMs,
+        (signal) => raw.getKnowledgePage(bankId, pageId, { ...options, signal }),
+        options?.signal,
+      ),
+    searchKnowledgeBase: (bankId, query, options) =>
+      withTimeout(
+        "hindsight searchKnowledgeBase",
+        timeoutMs,
+        (signal) => raw.searchKnowledgeBase(bankId, query, { ...options, signal }),
+        options?.signal,
+      ),
+    updateKnowledgeNode: (bankId, nodeId, options) =>
+      withTimeout(
+        "hindsight updateKnowledgeNode",
+        timeoutMs,
+        (signal) => raw.updateKnowledgeNode(bankId, nodeId, { ...options, signal }),
+        options?.signal,
+      ),
+    deleteKnowledgeNode: (bankId, nodeId, options) =>
+      withTimeout(
+        "hindsight deleteKnowledgeNode",
+        timeoutMs,
+        (signal) => raw.deleteKnowledgeNode(bankId, nodeId, { ...options, signal }),
+        options?.signal,
+      ),
+    exportKnowledgeBase: (bankId, options) =>
+      withTimeout(
+        "hindsight exportKnowledgeBase",
+        timeoutMs,
+        (signal) => raw.exportKnowledgeBase(bankId, { ...options, signal }),
+        options?.signal,
+      ),
+    updateBankConfig: (bankId, options) =>
+      withTimeout(
+        "hindsight updateBankConfig",
+        timeoutMs,
+        (signal) => raw.updateBankConfig(bankId, { ...options, signal }),
+        options?.signal,
+      ),
+    health: () =>
+      withTimeout("hindsight health", timeoutMs, (signal) =>
+        withRetry("health", async () => {
+          const response = await sdk.healthEndpointHealthGet({ client: lowLevel, signal });
+          return unwrapSdkResponse(response, "health");
+        }),
+      ),
+    getVersion: () =>
+      withTimeout("hindsight getVersion", timeoutMs, (signal) =>
+        withRetry("getVersion", () => raw.getVersion({ signal })),
+      ),
+  };
+}
+
+export async function checkHindsight(
+  client: HindsightLikeClient,
+  bankId: string,
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    if (client.health) await client.health();
+    else if (client.getBankProfile) await client.getBankProfile(bankId);
+    else await client.recall(bankId, "health check", { maxTokens: 1, budget: "low" });
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: redactError(error) };
+  }
+}
+
+export const HINDSIGHT_CLIENT_VERSION = CLIENT_VERSION;

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

@@ -0,0 +1,39 @@
+const PATCH_MARKER: unique symbol = Symbol("@luxusai/pi-hindsight.fetch-request-compat");
+
+type FetchWithMarker = typeof fetch & { [PATCH_MARKER]?: true };
+type RequestInitWithDuplex = RequestInit & { duplex?: "half" };
+
+function isRequest(value: unknown): value is Request {
+  return typeof Request !== "undefined" && value instanceof Request;
+}
+
+function requestToInit(request: Request): RequestInitWithDuplex {
+  return {
+    method: request.method,
+    headers: request.headers,
+    body: request.body,
+    signal: request.signal,
+    redirect: request.redirect,
+    credentials: request.credentials,
+    cache: request.cache,
+    mode: request.mode,
+    referrer: request.referrer,
+    referrerPolicy: request.referrerPolicy,
+    integrity: request.integrity,
+    keepalive: request.keepalive,
+    ...(request.body ? { duplex: "half" as const } : {}),
+  };
+}
+
+export function installFetchRequestCompat(): void {
+  const currentFetch = globalThis.fetch as FetchWithMarker | undefined;
+  if (!currentFetch || currentFetch[PATCH_MARKER]) return;
+
+  const originalFetch = currentFetch.bind(globalThis) as typeof fetch;
+  const patchedFetch: FetchWithMarker = ((input: RequestInfo | URL, init?: RequestInit) => {
+    if (!isRequest(input)) return originalFetch(input, init);
+    return originalFetch(input.url, { ...requestToInit(input), ...init });
+  }) as FetchWithMarker;
+  patchedFetch[PATCH_MARKER] = true;
+  globalThis.fetch = patchedFetch;
+}

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

@@ -0,0 +1,34 @@
+export async function withTimeout<T>(
+  operation: string,
+  timeoutMs: number,
+  fn: (signal: AbortSignal) => Promise<T>,
+  parentSignal?: AbortSignal,
+): Promise<T> {
+  if (parentSignal?.aborted) throw new Error(`${operation} aborted`);
+
+  const controller = new AbortController();
+  let timer: NodeJS.Timeout | undefined;
+  let removeAbortListener: (() => void) | undefined;
+  try {
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new Error(`${operation} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+    const abort = parentSignal
+      ? new Promise<never>((_resolve, reject) => {
+          const onAbort = () => {
+            controller.abort(parentSignal.reason);
+            reject(new Error(`${operation} aborted`));
+          };
+          parentSignal.addEventListener("abort", onAbort, { once: true });
+          removeAbortListener = () => parentSignal.removeEventListener("abort", onAbort);
+        })
+      : undefined;
+    return await Promise.race([fn(controller.signal), timeout, ...(abort ? [abort] : [])]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    removeAbortListener?.();
+  }
+}

package/node_modules/@luxusai/pi-hindsight/extensions/config/config-defaults.ts

@@ -0,0 +1,140 @@
+import type { ResolvedConfig } from "../types.js";
+
+export const DEFAULT_CONFIG: ResolvedConfig = {
+  enabled: true,
+  setupComplete: false,
+  scope: {
+    mode: "domain-tagged",
+    projectIdStrategy: "remote",
+    includeSharedObservations: false,
+  },
+  hindsight: { baseUrl: "http://localhost:8888", timeoutMs: 30_000 },
+  agentUse: "coding",
+  mentalModels: {
+    inject: true,
+    maxChars: 12_000,
+    cacheTtlMs: 300_000,
+  },
+  banks: {
+    project: { enabled: true, derive: "repo" },
+    global: { enabled: false },
+    user: { enabled: false },
+  },
+  recall: {
+    enabled: true,
+    budget: "mid",
+    maxTokens: 800,
+    userMaxTokens: 400,
+    types: ["observation"],
+    includeSourceFacts: false,
+    maxSourceFactsTokens: 4096,
+    contextTurns: 2,
+    roles: ["user", "assistant"],
+    maxQueryChars: 800,
+    queryPreamble: "Pi coding task memory lookup.",
+    projectQueryPreamble:
+      "Project memory lookup for current repo architecture, tasks, bugs, decisions, and constraints.",
+    globalQueryPreamble:
+      "User memory lookup for durable user preferences, recurring workflows, coding habits, and cross-project context.",
+    userQueryPreamble:
+      "User memory lookup for durable user preferences, recurring workflows, coding habits, and cross-project context.",
+    includeDateInQuery: false,
+    includeRepoHintsInQuery: true,
+    storeLastRecall: false,
+    storeLastRecallFailures: false,
+    lastRecallPath: ".pi/hindsight/last-recall.json",
+    topK: 8,
+    timeoutMs: 40_000,
+    cacheTtlMs: 60_000,
+    injectionMode: "context",
+    injectionPosition: "append",
+    includeFactsInDebug: false,
+    preferObservations: true,
+  },
+  observations: {
+    enabled: true,
+    // Project-stable scope; {repoKey} remains a supported placeholder for legacy configs.
+    scopes: [["harness:pi"], ["project:{projectId}"]],
+  },
+  globalRetain: {
+    mode: "explicit-only",
+  },
+  userRetain: {
+    mode: "explicit-only",
+  },
+  retain: {
+    enabled: true,
+    async: true,
+    delivery: "immediate",
+    updateMode: "append",
+    content: {
+      user: ["text"],
+      assistant: ["text", "toolCall"],
+      toolResult: ["error"],
+    },
+    toolFilter: {
+      toolCall: {
+        exclude: [
+          "hindsight_retain",
+          "hindsight_retain_global",
+          "hindsight_delete_document",
+          "hindsight_retain_receipts",
+          "hindsight_route_memory",
+          "hindsight_recall",
+          "hindsight_reflect",
+        ],
+      },
+      toolResult: {
+        exclude: [
+          "hindsight_retain",
+          "hindsight_retain_global",
+          "hindsight_delete_document",
+          "hindsight_retain_receipts",
+          "hindsight_route_memory",
+          "hindsight_recall",
+          "hindsight_reflect",
+          "read",
+          "grep",
+          "find",
+          "find_files",
+          "ls",
+        ],
+      },
+    },
+    compactToolCalls: true,
+    strip: { message: ["usage", "cost", "responseId"], topLevel: ["id", "parentId"] },
+    redactSecrets: true,
+    entities: [],
+    queuePath: ".pi/hindsight/retain-queue.jsonl",
+    flushIntervalMs: 0,
+    periodicFlushMaxJobs: 1,
+    periodicFlushTimeoutMs: 2_000,
+    shutdownFlushMaxJobs: 10,
+    shutdownFlushTimeoutMs: 2_000,
+    postRetainReflect: false,
+  },
+  import: {
+    mode: "curated",
+    qualityProfile: "compatible",
+    turnsPerDocument: 12,
+    maxDocumentBytes: 80_000,
+    includeBranches: "current-only",
+    toolResults: "errors-only",
+    toolResultSummaryMaxChars: 500,
+    replaceExistingImportedDocs: true,
+    manifestPath: ".pi/hindsight/import-manifest.json",
+    checkpointPath: ".pi/hindsight/import-checkpoint.json",
+    resume: true,
+  },
+  status: {
+    style: "text",
+    detail: "activity",
+    maxLength: 24,
+    showActivity: true,
+  },
+  notifications: {
+    startup: true,
+    recall: false,
+    retain: false,
+  },
+};

package/node_modules/@luxusai/pi-hindsight/extensions/config/config-editing-model.ts

@@ -0,0 +1,61 @@
+import type { ResolvedConfig } from "../types.js";
+import { readGlobalConfig, readProjectConfig } from "./config-writer.js";
+import type {
+  ConfigEditingField,
+  ConfigEditingTab,
+  ConfigLayers,
+  TabId,
+} from "./config-editing-registry.js";
+import {
+  buildConfigEditingFieldsFromRegistry,
+  buildStatusFacts,
+} from "./config-editing-registry.js";
+
+export type {
+  ConfigEditingField,
+  ConfigEditingKind,
+  ConfigEditingTab,
+  ConfigLayers,
+  FieldId,
+  TabId,
+} from "./config-editing-registry.js";
+export {
+  enabledDisabled,
+  inputDefaultForConfigEditingField,
+  parseConfigEditingFieldInput,
+  patchForConfigEditingField,
+} from "./config-editing-registry.js";
+
+export function readConfigLayers(cwd: string): ConfigLayers {
+  return { project: readProjectConfig(cwd), global: readGlobalConfig(), env: process.env };
+}
+
+export function buildConfigEditingFields(
+  config: ResolvedConfig,
+  projectBankId: string,
+  layers: ConfigLayers,
+): ConfigEditingField[] {
+  return buildConfigEditingFieldsFromRegistry(config, projectBankId, layers);
+}
+
+export function buildConfigEditingTabs(
+  config: ResolvedConfig,
+  projectBankId: string,
+  layers: ConfigLayers,
+  statusFacts: Array<[string, string]> = [],
+  options: { showAdvanced?: boolean } = {},
+): ConfigEditingTab[] {
+  const fields = buildConfigEditingFields(config, projectBankId, layers);
+  // Default hub is Status only; advanced unlocks full settings tabs.
+  const ids: TabId[] = options.showAdvanced
+    ? ["Status", "Connection", "Banks", "Recall", "Retain", "Import", "UI"]
+    : ["Status"];
+  return ids.map((id) => ({
+    id,
+    fields:
+      id === "Status"
+        ? []
+        : fields.filter((field) => field.tab === id && (options.showAdvanced || !field.advanced)),
+    ...(id === "Status" ? { facts: buildStatusFacts(config, projectBankId, statusFacts) } : {}),
+  }));
+}