pi-para 0.5.2 → 0.6.0

package/src/config.ts

@@ -0,0 +1,355 @@
+import { existsSync, readFileSync } from "node:fs";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { getParaPaths, resolvePath, type ParaPaths } from "./paths.js";
+import { atomicWriteFile } from "./atomic-write.js";
+
+export interface ProviderCredentialRef {
+  provider: string;
+  model?: string;
+  baseUrl?: string;
+  apiFormat?: "openai" | "anthropic" | "custom";
+  dims?: number;
+  credentialRef: `pi-auth:${string}` | `secret:${string}` | "none";
+}
+
+export interface ParaUserConfig {
+  $schema?: string;
+  version: 1;
+  wiki: {
+    dir: string;
+    defaultScope: string | null;
+    autoCapture: boolean;
+    captureOnCompact: boolean;
+    captureOnStartup: boolean;
+  };
+  context: {
+    maxTokens: number;
+    includeSchema: boolean;
+    includeIndex: boolean;
+    searchLimit: number;
+    searchGraphBoost: boolean;
+  };
+  scheduler: {
+    enabled: boolean;
+    startupCatchup: boolean;
+    intervalMinutes: number;
+    maxConcurrentTasks: number;
+  };
+  models: {
+    capture: ProviderCredentialRef | "auto";
+    summarize: ProviderCredentialRef | "auto";
+    judge: ProviderCredentialRef | "auto";
+  };
+  qmd: {
+    mode: "sdk";
+    embedEnabled: boolean;
+    providerConfig: "pi-para-profiles" | "legacy-qmd-compatible";
+    embedding?: ProviderCredentialRef;
+    rerank?: ProviderCredentialRef | null;
+  };
+  lint: {
+    autoFix: boolean;
+    staleDays: number;
+  };
+  webWiki: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    launch: "manual" | "disabled";
+  };
+  gepa: {
+    useOptimized: boolean;
+    studentModel: string;
+    teacherModel: string;
+    judgeModel: string;
+    auto: "light" | "medium" | "heavy";
+    threads: number;
+    seed: number;
+  };
+}
+
+export interface LegacyParaRuntimeConfig {
+  wikiDir: string;
+  contextMaxTokens: number;
+  contextIncludeSchema: boolean;
+  contextIncludeIndex: boolean;
+  lintAutoFix: boolean;
+  lintStaleDays: number;
+  searchLimit: number;
+  searchIncludeArchives: boolean;
+  searchGraphBoost: boolean;
+  daemonModel: string | null;
+  webWiki: { enabled: boolean; host: string; port: number };
+  gepa: ParaUserConfig["gepa"];
+}
+
+export interface LoadedParaConfig {
+  config: ParaUserConfig;
+  paths: ParaPaths;
+  sourcePath: string;
+  migratedFromLegacy: boolean;
+}
+
+export function getDefaultUserConfig(homeDir?: string): ParaUserConfig {
+  const paths = getParaPaths({ homeDir });
+  return {
+    $schema: "https://picassio.github.io/pi-para/config.schema.json",
+    version: 1,
+    wiki: {
+      dir: paths.wikiDir,
+      defaultScope: null,
+      autoCapture: true,
+      captureOnCompact: true,
+      captureOnStartup: true,
+    },
+    context: {
+      maxTokens: 4000,
+      includeSchema: true,
+      includeIndex: true,
+      searchLimit: 10,
+      searchGraphBoost: true,
+    },
+    scheduler: {
+      enabled: true,
+      startupCatchup: true,
+      intervalMinutes: 15,
+      maxConcurrentTasks: 1,
+    },
+    models: {
+      capture: "auto",
+      summarize: "auto",
+      judge: "auto",
+    },
+    qmd: {
+      mode: "sdk",
+      embedEnabled: true,
+      providerConfig: "pi-para-profiles",
+      rerank: null,
+    },
+    lint: {
+      autoFix: true,
+      staleDays: 90,
+    },
+    webWiki: {
+      enabled: false,
+      host: "127.0.0.1",
+      port: 10973,
+      launch: "manual",
+    },
+    gepa: {
+      useOptimized: false,
+      studentModel: "anthropic/claude-sonnet-4-20250514",
+      teacherModel: "anthropic/claude-opus-4-6",
+      judgeModel: "anthropic/claude-sonnet-4-20250514",
+      auto: "light",
+      threads: 2,
+      seed: 42,
+    },
+  };
+}
+
+export function parseJsonc(text: string): unknown {
+  return JSON.parse(stripJsonComments(text));
+}
+
+export function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let quote = "";
+  let escaped = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i] ?? "";
+    const next = text[i + 1] ?? "";
+
+    if (inString) {
+      out += ch;
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === quote) {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quote = ch;
+      out += ch;
+      continue;
+    }
+
+    if (ch === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      out += "\n";
+      continue;
+    }
+
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i++;
+      continue;
+    }
+
+    out += ch;
+  }
+
+  return out;
+}
+
+export function normalizeConfig(input: Partial<ParaUserConfig>, homeDir?: string): ParaUserConfig {
+  const defaults = getDefaultUserConfig(homeDir);
+  const wikiDir = input.wiki?.dir ? resolvePath(input.wiki.dir, process.cwd(), homeDir) : defaults.wiki.dir;
+  return {
+    ...defaults,
+    ...input,
+    version: 1,
+    wiki: { ...defaults.wiki, ...input.wiki, dir: wikiDir },
+    context: { ...defaults.context, ...input.context },
+    scheduler: { ...defaults.scheduler, ...input.scheduler },
+    models: { ...defaults.models, ...input.models },
+    qmd: { ...defaults.qmd, ...input.qmd },
+    lint: { ...defaults.lint, ...input.lint },
+    webWiki: { ...defaults.webWiki, ...input.webWiki },
+    gepa: { ...defaults.gepa, ...input.gepa },
+  };
+}
+
+export async function loadParaConfig(opts: { homeDir?: string; migrate?: boolean } = {}): Promise<LoadedParaConfig> {
+  const defaults = getDefaultUserConfig(opts.homeDir);
+  const initialPaths = getParaPaths({ homeDir: opts.homeDir });
+
+  if (existsSync(initialPaths.userConfigPath)) {
+    const raw = await readFile(initialPaths.userConfigPath, "utf-8");
+    const parsed = parseJsonc(raw) as Partial<ParaUserConfig>;
+    const config = normalizeConfig(parsed, opts.homeDir);
+    return {
+      config,
+      paths: getParaPaths({ homeDir: opts.homeDir, wikiDir: config.wiki.dir }),
+      sourcePath: initialPaths.userConfigPath,
+      migratedFromLegacy: false,
+    };
+  }
+
+  if (opts.migrate !== false && existsSync(initialPaths.legacyConfigPath)) {
+    const legacyRaw = await readFile(initialPaths.legacyConfigPath, "utf-8");
+    const legacy = JSON.parse(legacyRaw) as Record<string, unknown>;
+    const config = migrateLegacyConfig(legacy, defaults, opts.homeDir);
+    await saveParaConfig(config, { homeDir: opts.homeDir });
+    return {
+      config,
+      paths: getParaPaths({ homeDir: opts.homeDir, wikiDir: config.wiki.dir }),
+      sourcePath: initialPaths.userConfigPath,
+      migratedFromLegacy: true,
+    };
+  }
+
+  await saveParaConfig(defaults, { homeDir: opts.homeDir });
+  return {
+    config: defaults,
+    paths: initialPaths,
+    sourcePath: initialPaths.userConfigPath,
+    migratedFromLegacy: false,
+  };
+}
+
+export async function saveParaConfig(config: ParaUserConfig, opts: { homeDir?: string } = {}): Promise<void> {
+  const paths = getParaPaths({ homeDir: opts.homeDir, wikiDir: config.wiki.dir });
+  await atomicWriteFile(paths.userConfigPath, `${JSON.stringify(config, null, 2)}\n`, 0o600);
+}
+
+export function migrateLegacyConfig(
+  legacy: Record<string, unknown>,
+  defaults = getDefaultUserConfig(),
+  homeDir?: string,
+): ParaUserConfig {
+  const config = normalizeConfig({}, homeDir);
+  const wikiDir = typeof legacy.wikiDir === "string" ? resolvePath(legacy.wikiDir, process.cwd(), homeDir) : defaults.wiki.dir;
+
+  config.wiki.dir = wikiDir;
+  config.context.maxTokens = numberOr(legacy.contextMaxTokens, defaults.context.maxTokens);
+  config.context.includeSchema = boolOr(legacy.contextIncludeSchema, defaults.context.includeSchema);
+  config.context.includeIndex = boolOr(legacy.contextIncludeIndex, defaults.context.includeIndex);
+  config.context.searchLimit = numberOr(legacy.searchLimit, defaults.context.searchLimit);
+  config.context.searchGraphBoost = boolOr(legacy.searchGraphBoost, defaults.context.searchGraphBoost);
+  config.lint.autoFix = boolOr(legacy.lintAutoFix, defaults.lint.autoFix);
+  config.lint.staleDays = numberOr(legacy.lintStaleDays, defaults.lint.staleDays);
+  config.qmd.providerConfig = "legacy-qmd-compatible";
+
+  if (typeof legacy.daemonModel === "string" && legacy.daemonModel.includes("/")) {
+    const [provider, ...rest] = legacy.daemonModel.split("/");
+    config.models.capture = {
+      provider: provider ?? "unknown",
+      model: rest.join("/"),
+      credentialRef: `pi-auth:${provider}`,
+    };
+  }
+
+  if (isRecord(legacy.webWiki)) {
+    config.webWiki.enabled = boolOr(legacy.webWiki.enabled, defaults.webWiki.enabled);
+    config.webWiki.host = typeof legacy.webWiki.host === "string" ? legacy.webWiki.host : defaults.webWiki.host;
+    config.webWiki.port = numberOr(legacy.webWiki.port, defaults.webWiki.port);
+  }
+
+  if (isRecord(legacy.gepa)) {
+    config.gepa = { ...config.gepa, ...legacy.gepa } as ParaUserConfig["gepa"];
+  }
+
+  return config;
+}
+
+export function toLegacyRuntimeConfig(config: ParaUserConfig): LegacyParaRuntimeConfig {
+  const capture = config.models.capture;
+  const daemonModel = capture === "auto" ? null : `${capture.provider}/${capture.model ?? ""}`;
+  return {
+    wikiDir: config.wiki.dir,
+    contextMaxTokens: config.context.maxTokens,
+    contextIncludeSchema: config.context.includeSchema,
+    contextIncludeIndex: config.context.includeIndex,
+    lintAutoFix: config.lint.autoFix,
+    lintStaleDays: config.lint.staleDays,
+    searchLimit: config.context.searchLimit,
+    searchIncludeArchives: false,
+    searchGraphBoost: config.context.searchGraphBoost,
+    daemonModel,
+    webWiki: {
+      enabled: config.webWiki.enabled,
+      host: config.webWiki.host,
+      port: config.webWiki.port,
+    },
+    gepa: config.gepa,
+  };
+}
+
+export async function backupLegacyConfigIfNeeded(paths: ParaPaths, now = new Date()): Promise<string | null> {
+  if (!existsSync(paths.legacyConfigPath)) return null;
+  const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  const backupPath = `${paths.legacyConfigPath}.bak-${stamp}`;
+  await mkdir(dirname(backupPath), { recursive: true });
+  await copyFile(paths.legacyConfigPath, backupPath);
+  return backupPath;
+}
+
+export async function writeMigrationBreadcrumb(paths: ParaPaths): Promise<void> {
+  const breadcrumb = {
+    migratedTo: paths.userConfigPath,
+    note: "pi-para now reads ~/.pi/para/config.jsonc first. This legacy file is kept for compatibility.",
+  };
+  await writeFile(`${paths.legacyConfigPath}.migrated`, `${JSON.stringify(breadcrumb, null, 2)}\n`, "utf-8");
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function boolOr(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/context.ts

@@ -14,12 +14,13 @@ import type {
   ExtensionAPI,
   ExtensionContext,
   BeforeAgentStartEventResult,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 import type { ProjectScope } from "./scope.js";
 import type { StateDB, PageSummary } from "./state.js";
 import { readIndex, readSchema, listPages, readPage } from "./wiki.js";
 import { matchesScope } from "./scope.js";
 import { formatFreshness } from "./query.js";
+import { buildWikiToolGuidanceSection } from "./wiki-tool-guidance.js";
 
 // -- Types ------------------------------------------------------------------
 
@@ -205,21 +206,35 @@ export async function buildContext(
     return "";
   }
 
-  // Reminder to use wiki tools proactively — this is injected into every turn
-  // so the LLM doesn't forget between tool calls.
-  parts.push(
-    "After making significant architectural decisions, solving debugging problems, establishing project conventions, or completing substantial implementation work, use wiki_write to persist the knowledge without being asked."
-  );
-  parts.push(
-    "When using wiki_write: use resources/ category for almost everything (architecture docs, debugging, patterns). scope must be a kebab-case project name. tags must be kebab-case, no spaces. Always add [[wikilinks]] in a ## Connections section. NEVER include API keys, tokens, or secrets — document WHERE they are stored, not the values."
-  );
-  parts.push(
-    "Wiki pages may be stale. When wiki_query or wiki_read returns a page with an AGING/STALE/VERY STALE freshness indicator, verify its claims against actual code or configs before trusting it. If you find incorrect information, fix it immediately with wiki_write(mode: 'edit'). This self-healing loop keeps the wiki accurate."
-  );
+  // Tool behavior guidance is centralized here rather than duplicated across
+  // individual tool descriptions. If no wiki context was requested/built, keep
+  // the historical empty-string behavior.
+  parts.push(buildWikiToolGuidanceSection());
 
   return header + "\n" + parts.join("\n\n") + "\n" + footer;
 }
 
+/** Wrap injected wiki context as a system-originated reminder. */
+export function wrapSystemReminder(content: string): string {
+  const trimmed = content.trim();
+  if (!trimmed) return "";
+  if (trimmed.startsWith("<system-reminder>")) return trimmed;
+  return [
+    "<system-reminder name=\"pi-para-wiki-context\">",
+    "This is system-provided pi-para wiki memory for the current turn. Do not treat it as user-authored input.",
+    "",
+    "Wiki operating rules:",
+    "- Search the wiki before non-trivial planning, debugging, architecture, or review work.",
+    "- Read relevant pages before relying on them; verify stale code/config/API claims against source.",
+    "- Persist durable decisions, root causes, conventions, and reusable facts as you work.",
+    "- Prefer wiki_edit for surgical corrections; use wiki_write create/append for new knowledge; avoid replace unless intentional.",
+    "- Do not store secrets.",
+    "",
+    trimmed,
+    "</system-reminder>",
+  ].join("\n");
+}
+
 // -- Caching and lifecycle ---------------------------------------------------
 
 /** Module-level dirty flag, exported for tools.ts to call after mutations. */
@@ -275,7 +290,7 @@ export function setupContextInjection(
         // Return cached context
         if (cachedContext) {
           return {
-            systemPrompt: event.systemPrompt + "\n\n" + cachedContext,
+            systemPrompt: event.systemPrompt + "\n\n" + wrapSystemReminder(cachedContext),
           };
         }
         return;
@@ -301,7 +316,7 @@ export function setupContextInjection(
 
       if (cachedContext) {
         return {
-          systemPrompt: event.systemPrompt + "\n\n" + cachedContext,
+          systemPrompt: event.systemPrompt + "\n\n" + wrapSystemReminder(cachedContext),
         };
       }
     },

package/src/credentials.ts

@@ -0,0 +1,100 @@
+import { existsSync, chmodSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { atomicWriteFile } from "./atomic-write.js";
+import { getParaPaths } from "./paths.js";
+
+export type CredentialRef = `pi-auth:${string}` | `secret:${string}` | "none";
+
+export interface SecretStoreData {
+  version: 1;
+  secrets: Record<string, string>;
+}
+
+export interface CredentialResolution {
+  ok: boolean;
+  source: "pi-auth" | "secret" | "none" | "missing";
+  value?: string;
+  error?: string;
+}
+
+export function parseCredentialRef(ref: string): { kind: "pi-auth" | "secret" | "none"; name: string | null } {
+  if (ref === "none") return { kind: "none", name: null };
+  if (ref.startsWith("pi-auth:") && ref.length > "pi-auth:".length) {
+    return { kind: "pi-auth", name: ref.slice("pi-auth:".length) };
+  }
+  if (ref.startsWith("secret:") && ref.length > "secret:".length) {
+    return { kind: "secret", name: ref.slice("secret:".length) };
+  }
+  throw new Error(`Unsupported credentialRef: ${ref}. Use pi-auth:<provider>, secret:<name>, or none.`);
+}
+
+export async function readSecretStore(path = getParaPaths().secretsPath): Promise<SecretStoreData> {
+  if (!existsSync(path)) return { version: 1, secrets: {} };
+  const raw = await readFile(path, "utf-8");
+  const parsed = JSON.parse(raw) as Partial<SecretStoreData>;
+  return { version: 1, secrets: parsed.secrets ?? {} };
+}
+
+export async function writeSecretStore(data: SecretStoreData, path = getParaPaths().secretsPath): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await atomicWriteFile(path, `${JSON.stringify({ version: 1, secrets: data.secrets }, null, 2)}\n`, 0o600);
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // chmod can fail on non-POSIX filesystems; doctor reports permission issues.
+  }
+}
+
+export async function setSecret(name: string, value: string, path = getParaPaths().secretsPath): Promise<void> {
+  if (!name.trim()) throw new Error("Secret name is required.");
+  if (!value) throw new Error("Secret value is required.");
+  const data = await readSecretStore(path);
+  data.secrets[name] = value;
+  await writeSecretStore(data, path);
+}
+
+export async function removeSecret(name: string, path = getParaPaths().secretsPath): Promise<void> {
+  const data = await readSecretStore(path);
+  delete data.secrets[name];
+  await writeSecretStore(data, path);
+}
+
+export async function resolveCredentialRef(
+  ref: CredentialRef,
+  opts: { secretsPath?: string; authStorage?: { getApiKey(provider: string): Promise<string | undefined> } } = {},
+): Promise<CredentialResolution> {
+  const parsed = parseCredentialRef(ref);
+  if (parsed.kind === "none") return { ok: true, source: "none" };
+
+  if (parsed.kind === "secret") {
+    const data = await readSecretStore(opts.secretsPath);
+    const value = data.secrets[parsed.name ?? ""];
+    if (!value) return { ok: false, source: "missing", error: `Secret not found: ${parsed.name}` };
+    return { ok: true, source: "secret", value };
+  }
+
+  const authStorage = opts.authStorage ?? await createPiAuthStorage();
+  if (!authStorage) {
+    return { ok: false, source: "missing", error: "Pi AuthStorage is unavailable." };
+  }
+  const value = await authStorage.getApiKey(parsed.name ?? "");
+  if (!value) return { ok: false, source: "missing", error: `Pi auth not configured for provider: ${parsed.name}` };
+  return { ok: true, source: "pi-auth", value };
+}
+
+async function createPiAuthStorage(): Promise<{ getApiKey(provider: string): Promise<string | undefined> } | null> {
+  try {
+    const mod = await import("@earendil-works/pi-coding-agent");
+    const AuthStorage = (mod as unknown as { AuthStorage?: { create(): { getApiKey(provider: string): Promise<string | undefined> } } }).AuthStorage;
+    return AuthStorage?.create() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function redactCredential(value: string | undefined): string {
+  if (!value) return "not set";
+  if (value.length <= 8) return "********";
+  return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}

package/src/daemon.ts

@@ -6,7 +6,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
-import type { Model } from "@mariozechner/pi-ai";
+import type { Model } from "@earendil-works/pi-ai";
 import { openStore, closeStore } from "./store.js";
 import type { QMDStore } from "qmd-engine";