pi-para 0.5.2 → 0.6.0

package/src/doctor.ts

@@ -0,0 +1,209 @@
+import { existsSync, statSync } from "node:fs";
+import { initWiki } from "./wiki.js";
+import { loadParaConfig, type ParaUserConfig } from "./config.js";
+import { readSecretStore, resolveCredentialRef } from "./credentials.js";
+import { getParaPaths } from "./paths.js";
+import { openStore, closeStore } from "./store.js";
+import type { ProviderCredentialRef } from "./config.js";
+import { createPiModelRegistry, getCaptureSelection, resolveSelectedModel } from "./model-resolver.js";
+import { SchedulerStateDB } from "./scheduler/state.js";
+import { ensureGeneratedStateGitignore, fixSecretPermissions, missingGeneratedStateGitignorePatterns } from "./repair.js";
+
+export type DoctorStatus = "ok" | "warn" | "error";
+
+export interface DoctorCheck {
+  name: string;
+  status: DoctorStatus;
+  message: string;
+  fixable?: boolean;
+}
+
+export interface DoctorOptions {
+  homeDir?: string;
+  fix?: boolean;
+  validateQmd?: boolean;
+  testCaptureModel?: boolean;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+export async function runDoctor(options: DoctorOptions = {}): Promise<DoctorResult> {
+  const checks: DoctorCheck[] = [];
+  const loaded = await loadParaConfig({ homeDir: options.homeDir, migrate: options.fix ?? false });
+  const paths = getParaPaths({ homeDir: options.homeDir, wikiDir: loaded.config.wiki.dir });
+
+  checks.push(checkExists("config", paths.userConfigPath, "warn"));
+  checks.push(checkExists("pi-settings", paths.piSettingsPath, "warn"));
+
+  if (options.fix) await initWiki(paths.wikiDir);
+  checks.push(checkExists("wiki-dir", paths.wikiDir, "warn", true));
+
+  const schedulerCheck = checkScheduler(paths.schedulerDbPath);
+  checks.push(schedulerCheck);
+
+  if (options.fix) {
+    fixSecretPermissions(paths.secretsPath);
+    await ensureGeneratedStateGitignore(paths.wikiDir);
+  }
+
+  checks.push(await checkSecrets(paths.secretsPath));
+  checks.push(await checkGeneratedStateGitignore(paths.wikiDir));
+  checks.push(...await checkProviderDiagnostics(loaded.config, paths.secretsPath, options));
+
+  if (options.validateQmd !== false) {
+    checks.push(await checkQmd(paths.wikiDir, loaded.config, paths.secretsPath));
+  }
+
+  const backlogPath = `${paths.wikiDir}/.completed-sessions`;
+  if (existsSync(backlogPath)) {
+    checks.push({
+      name: "capture-backlog",
+      status: "warn",
+      message: ".completed-sessions exists; startup catch-up will process queued entries once capture task is enabled",
+    });
+  } else {
+    checks.push({ name: "capture-backlog", status: "ok", message: "no completed-session registry found" });
+  }
+
+  return { ok: checks.every((check) => check.status !== "error"), checks };
+}
+
+export function formatDoctorResult(result: DoctorResult): string {
+  const lines = ["pi-para doctor"];
+  for (const check of result.checks) {
+    const icon = check.status === "ok" ? "✓" : check.status === "warn" ? "⚠" : "✗";
+    lines.push(`  ${icon} ${check.name}: ${check.message}`);
+  }
+  return lines.join("\n");
+}
+
+function checkExists(name: string, path: string, missingStatus: DoctorStatus, fixable = false): DoctorCheck {
+  return existsSync(path)
+    ? { name, status: "ok", message: path }
+    : { name, status: missingStatus, message: `${path} not found`, fixable };
+}
+
+function checkScheduler(dbPath: string): DoctorCheck {
+  try {
+    const db = new SchedulerStateDB(dbPath);
+    const queued = db.list("queued").length;
+    db.close();
+    return { name: "scheduler", status: "ok", message: `${dbPath} (${queued} queued)` };
+  } catch (err) {
+    return { name: "scheduler", status: "error", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function checkSecrets(secretsPath: string): Promise<DoctorCheck> {
+  try {
+    const store = await readSecretStore(secretsPath);
+    if (!existsSync(secretsPath)) return { name: "secrets", status: "ok", message: "no local pi-para secrets configured" };
+    // POSIX mode bits are meaningless on Windows/NTFS — stat reports 666 and
+    // chmod is a no-op, so a permissions warning there is a false positive.
+    if (process.platform === "win32") {
+      return { name: "secrets", status: "ok", message: `${Object.keys(store.secrets).length} local secret(s) (POSIX permission check skipped on Windows)` };
+    }
+    const mode = statSync(secretsPath).mode & 0o777;
+    if (mode & 0o077) {
+      return { name: "secrets", status: "warn", message: `${secretsPath} permissions are too open (${mode.toString(8)})`, fixable: true };
+    }
+    return { name: "secrets", status: "ok", message: `${Object.keys(store.secrets).length} local secret(s), permissions ${mode.toString(8)}` };
+  } catch (err) {
+    return { name: "secrets", status: "error", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function checkGeneratedStateGitignore(wikiDir: string): Promise<DoctorCheck> {
+  try {
+    const missing = missingGeneratedStateGitignorePatterns(wikiDir);
+    if (missing.length > 0) {
+      return { name: "gitignore", status: "warn", message: `missing generated-state ignores: ${missing.join(", ")}`, fixable: true };
+    }
+    return { name: "gitignore", status: "ok", message: "generated SQLite/state files are ignored" };
+  } catch (err) {
+    return { name: "gitignore", status: "error", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function checkProviderDiagnostics(
+  config: ParaUserConfig,
+  secretsPath: string,
+  options: DoctorOptions,
+): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+
+  if (config.qmd.providerConfig === "legacy-qmd-compatible") {
+    checks.push({ name: "qmd-providers", status: "warn", message: "using legacy QMD provider config compatibility mode" });
+  } else {
+    checks.push({ name: "qmd-providers", status: "ok", message: "using pi-para provider profiles" });
+  }
+
+  if (!config.qmd.embedEnabled) {
+    checks.push({ name: "qmd-embedding", status: "ok", message: "embedding disabled" });
+  } else if (config.qmd.embedding) {
+    checks.push(await checkCredentialProfile("qmd-embedding", config.qmd.embedding, secretsPath));
+  } else {
+    checks.push({ name: "qmd-embedding", status: "warn", message: "embedding enabled but no pi-para embedding profile is configured" });
+  }
+
+  if (config.qmd.rerank) {
+    checks.push(await checkCredentialProfile("qmd-rerank", config.qmd.rerank, secretsPath));
+  } else {
+    checks.push({ name: "qmd-rerank", status: "ok", message: "rerank disabled" });
+  }
+
+  checks.push(await checkCaptureModel(config, secretsPath, options.testCaptureModel === true));
+  return checks;
+}
+
+async function checkCredentialProfile(name: string, profile: ProviderCredentialRef, secretsPath: string): Promise<DoctorCheck> {
+  const label = `${profile.provider}/${profile.model ?? "model not set"}`;
+  if (profile.credentialRef === "none") {
+    return { name, status: "ok", message: `${label} uses no credential` };
+  }
+  const resolved = await resolveCredentialRef(profile.credentialRef, { secretsPath });
+  if (!resolved.ok) {
+    return { name, status: "warn", message: `${label} credential missing: ${resolved.error}` };
+  }
+  return { name, status: "ok", message: `${label} credential available via ${resolved.source}` };
+}
+
+async function checkCaptureModel(config: ParaUserConfig, secretsPath: string, testModel: boolean): Promise<DoctorCheck> {
+  const selection = getCaptureSelection(config);
+  if (!testModel) {
+    if (selection === "auto") return { name: "capture-model", status: "ok", message: "auto selection; run doctor --test-capture-model to resolve" };
+    return checkCredentialProfile("capture-model", selection, secretsPath);
+  }
+
+  try {
+    const registry = await createPiModelRegistry();
+    if (!registry) return { name: "capture-model", status: "warn", message: "Pi model registry unavailable" };
+    const model = resolveSelectedModel(selection, registry.modelRegistry, { preferredModelSpec: "anthropic/claude-sonnet-4-20250514" });
+    if (!model) return { name: "capture-model", status: "warn", message: "no capture model resolved" };
+    const getKey = selection === "auto"
+      ? () => registry.modelRegistry.getApiKeyForProvider(model.provider)
+      : () => resolveCredentialRef(selection.credentialRef, { secretsPath, authStorage: registry.authStorage }).then((r) => r.value);
+    const key = await getKey();
+    return key
+      ? { name: "capture-model", status: "ok", message: `${model.provider}/${model.id} credential available` }
+      : { name: "capture-model", status: "warn", message: `${model.provider}/${model.id} resolved but credential is missing` };
+  } catch (err) {
+    return { name: "capture-model", status: "warn", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function checkQmd(wikiDir: string, config: ParaUserConfig, secretsPath: string): Promise<DoctorCheck> {
+  try {
+    const store = await openStore(wikiDir, {
+      paraConfig: { ...config, qmd: { ...config.qmd, embedEnabled: false } },
+      secretsPath,
+    });
+    await closeStore(store);
+    return { name: "qmd-sdk", status: "ok", message: "store opened and updated with pi-para provider profiles" };
+  } catch (err) {
+    return { name: "qmd-sdk", status: "error", message: err instanceof Error ? err.message : String(err), fixable: false };
+  }
+}

package/src/gepa/index.ts

@@ -80,7 +80,7 @@ function findPackageRoot(): string {
     if (existsSync(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        if (pkg.name === "@picassio/pi-para") return dir;
+        if (pkg.name === "pi-para" || pkg.name === "@picassio/pi-para") return dir;
       } catch {}
     }
     dir = dirname(dir);

package/src/index.ts

@@ -4,15 +4,14 @@
  * Main extension entry point. Wires together wiki filesystem, qmd store,
  * scope detection, context injection, tools, and commands.
  *
- * Session capture is handled by a separate daemon (pi-para-daemon).
- * This extension registers completed sessions for the daemon to process.
+ * Session capture and maintenance are coordinated by an in-process scheduler.
+ * Completed-session registry entries are kept as a durable catch-up queue.
  */
 
-import { readFile, writeFile, mkdir, appendFile } from "node:fs/promises";
-import { join, dirname } from "node:path";
+import { join } from "node:path";
 import { homedir, networkInterfaces } from "node:os";
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { QMDStore } from "qmd-engine";
 
 import type { ProjectScope } from "./scope.js";
@@ -24,6 +23,15 @@ import { setupContextInjection, markContextDirty } from "./context.js";
 import type { ContextConfig } from "./context.js";
 import { registerCommands } from "./commands.js";
 import { createServer } from "node:http";
+import { startWikiScheduler, stopWikiScheduler } from "./scheduler/index.js";
+import {
+  appendCompletedSession,
+  createCaptureSessionHandler,
+  enqueueCompletedSessionsFromRegistry,
+} from "./scheduler/session-capture.js";
+import { loadParaConfig, toLegacyRuntimeConfig, type ParaUserConfig } from "./config.js";
+import { createModelApiKeyResolver, createPiModelRegistry, getCaptureSelection, resolveSelectedModel } from "./model-resolver.js";
+import { StateDB } from "./state.js";
 
 // Re-export public types for consumers
 export type { ParaCategory, WikiPage, PageFrontmatter, PageRef, LogEntry } from "./wiki.js";
@@ -48,8 +56,8 @@ interface ParaConfig {
   searchLimit: number;
   searchIncludeArchives: boolean;
   searchGraphBoost: boolean;
-  /** Daemon LLM: "provider/model-id" (e.g. "anthropic/claude-sonnet-4").
-   *  If not set, daemon auto-detects from pi env keys or qmd config. */
+  /** Legacy capture LLM: "provider/model-id" (e.g. "anthropic/claude-sonnet-4").
+   *  New config stores this as models.capture; legacy field remains for migration. */
   daemonModel: string | null;
   /** Web wiki UI settings */
   webWiki: {
@@ -108,30 +116,37 @@ function getDefaultConfig(): ParaConfig {
   };
 }
 
-async function loadConfig(): Promise<ParaConfig> {
-  const defaults = getDefaultConfig();
-  const configPath = join(defaults.wikiDir, "config.json");
+interface LoadedRuntimeConfig {
+  runtime: ParaConfig;
+  userConfig: ParaUserConfig | null;
+  secretsPath: string | null;
+}
+
+async function loadConfig(): Promise<LoadedRuntimeConfig> {
   try {
-    const raw = await readFile(configPath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<ParaConfig>;
-    const wikiDir = parsed.wikiDir
-      ? parsed.wikiDir.replace(/^~\//, `${homedir()}/`)
-      : defaults.wikiDir;
-    return { ...defaults, ...parsed, wikiDir };
+    const loaded = await loadParaConfig({ migrate: true });
+    const runtime = toLegacyRuntimeConfig(loaded.config);
+    return {
+      runtime: {
+        ...runtime,
+        gepa: {
+          ...runtime.gepa,
+          studentModel: runtime.gepa.studentModel ?? null,
+          teacherModel: runtime.gepa.teacherModel ?? null,
+          judgeModel: runtime.gepa.judgeModel ?? null,
+        },
+      },
+      userConfig: loaded.config,
+      secretsPath: loaded.paths.secretsPath,
+    };
   } catch {
-    try {
-      await mkdir(dirname(configPath), { recursive: true });
-      await writeFile(configPath, JSON.stringify(defaults, null, 2), "utf-8");
-    } catch {
-      // Non-fatal
-    }
-    return { ...defaults };
+    return { runtime: getDefaultConfig(), userConfig: null, secretsPath: null };
   }
 }
 
 // -- LAN IP detection --------------------------------------------------------
 
-/** Check if the daemon's web server is alive on the given port. */
+/** Check if the optional web wiki server is alive on the given port. */
 function checkWebServerAlive(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const req = createServer().listen(port, "127.0.0.1");
@@ -148,6 +163,10 @@ function checkWebServerAlive(port: number): Promise<boolean> {
   });
 }
 
+function isPrintModeProcess(argv = process.argv): boolean {
+  return argv.includes("-p") || argv.includes("--print") || argv.includes("--mode") && argv[argv.indexOf("--mode") + 1] === "json";
+}
+
 function getLanIp(): string | null {
   const interfaces = networkInterfaces();
   for (const name of Object.keys(interfaces)) {
@@ -184,7 +203,8 @@ function reconstructState(ctx: ExtensionContext): ParaSessionState | null {
 // -- Extension entry point ---------------------------------------------------
 
 export default async function piPara(pi: ExtensionAPI): Promise<void> {
-  const config = await loadConfig();
+  const loadedConfig = await loadConfig();
+  const config = loadedConfig.runtime;
   const wikiDir = config.wikiDir;
 
   let store: QMDStore | null = null;
@@ -221,7 +241,11 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
     if (storeRetrying) return false;
     storeRetrying = true;
     try {
-      store = await openStore(wikiDir);
+      store = await openStore(wikiDir, {
+        paraConfig: loadedConfig.userConfig ?? undefined,
+        secretsPath: loadedConfig.secretsPath ?? undefined,
+        backgroundEmbed: false,
+      });
       storeDisabled = false;
       markContextDirty(); // rebuild context now that store works
       return true;
@@ -280,7 +304,11 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
     ctx.ui.setStatus("pi-para", "wiki: indexing...");
     storeDisabled = false;
     try {
-      store = await openStore(wikiDir);
+      store = await openStore(wikiDir, {
+        paraConfig: loadedConfig.userConfig ?? undefined,
+        secretsPath: loadedConfig.secretsPath ?? undefined,
+        backgroundEmbed: false,
+      });
     } catch (err) {
       store = null;
       storeDisabled = true;
@@ -302,7 +330,60 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
       sessionFile: ctx.sessionManager.getSessionFile() ?? null,
     } satisfies ParaSessionState);
 
-    // Check if daemon's web wiki server is running (don't start our own)
+    const schedulerHandlers = {} as Record<string, any>;
+    const schedulerConfig = loadedConfig.userConfig?.scheduler;
+    const wikiConfig = loadedConfig.userConfig?.wiki;
+    const autoCaptureEnabled = wikiConfig?.autoCapture !== false;
+    const startupCatchupEnabled = autoCaptureEnabled && wikiConfig?.captureOnStartup !== false && schedulerConfig?.startupCatchup !== false;
+    try {
+      const loadedParaConfig = await loadParaConfig({ migrate: true });
+      const registry = autoCaptureEnabled ? await createPiModelRegistry() : null;
+      if (registry) {
+        const captureSelection = getCaptureSelection(loadedParaConfig.config);
+        const captureModel = resolveSelectedModel(captureSelection, registry.modelRegistry, {
+          legacyModelSpec: config.daemonModel,
+          preferredModelSpec: "anthropic/claude-sonnet-4-20250514",
+        });
+        if (captureModel) {
+          schedulerHandlers["capture-session"] = createCaptureSessionHandler({
+            wikiDir,
+            storeProvider: () => store,
+            model: captureModel,
+            getApiKey: createModelApiKeyResolver(captureSelection, registry.modelRegistry, {
+              authStorage: registry.authStorage,
+              secretsPath: loadedParaConfig.paths.secretsPath,
+            }),
+          });
+        }
+      }
+    } catch {
+      // Capture handler registration is best-effort; manual capture remains available.
+    }
+
+    const schedulerEnabled = !isPrintModeProcess() && schedulerConfig?.enabled !== false;
+    const scheduler = schedulerEnabled
+      ? startWikiScheduler({
+        wikiDir,
+        enabled: true,
+        intervalMs: (schedulerConfig?.intervalMinutes ?? 15) * 60_000,
+        storeProvider: () => store,
+        markDirty: () => markContextDirty(),
+        handlers: schedulerHandlers,
+      })
+      : null;
+
+    if (scheduler && startupCatchupEnabled) {
+      try {
+        const stateDb = new StateDB(wikiDir);
+        await enqueueCompletedSessionsFromRegistry(scheduler, wikiDir, { stateDb });
+        stateDb.close();
+        void scheduler.tick();
+      } catch {
+        // Startup capture catch-up is best-effort.
+      }
+    }
+
+    // Check if web wiki server is running (don't start our own yet)
     if (config.webWiki.enabled) {
       const port = config.webWiki.port;
       try {
@@ -312,7 +393,7 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
           const url = lanIp ? `http://${lanIp}:${port}` : `http://localhost:${port}`;
           ctx.ui.setStatus("pi-para", `wiki: ${url}`);
         } else {
-          ctx.ui.setStatus("pi-para", "wiki: ready (start daemon for web UI)");
+          ctx.ui.setStatus("pi-para", "wiki: ready (web UI disabled)");
           setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 5000);
         }
       } catch {
@@ -337,7 +418,7 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
     markContextDirty();
   });
 
-  // -- session_compact: register session for daemon capture on compaction ----
+  // -- session_compact: register session for scheduler capture on compaction --
 
   pi.on("session_compact", async (_event, ctx) => {
     // Compaction means the session has accumulated enough content that details
@@ -345,9 +426,7 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
     const sessionFile = ctx.sessionManager.getSessionFile();
     if (sessionFile) {
       try {
-        const registry = join(wikiDir, ".completed-sessions");
-        const entry = `${new Date().toISOString()}|${sessionFile}\n`;
-        await appendFile(registry, entry);
+        await appendCompletedSession(wikiDir, sessionFile);
         ctx.ui.setStatus("pi-para", "wiki: capture queued (compaction)");
         setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 5000);
       } catch {
@@ -356,22 +435,22 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
     }
   });
 
-  // -- session_shutdown: register session for daemon, close store ------------
+  // -- session_shutdown: register session for scheduler, close store ---------
 
   pi.on("session_shutdown", async (_event, ctx) => {
-    // 1. Register session as completed (for daemon to process later)
+    // 1. Register session as completed (scheduler catch-up processes later)
     const sessionFile = ctx.sessionManager.getSessionFile();
     if (sessionFile) {
       try {
-        const registry = join(wikiDir, ".completed-sessions");
-        const entry = `${new Date().toISOString()}|${sessionFile}\n`;
-        await appendFile(registry, entry);
+        await appendCompletedSession(wikiDir, sessionFile);
       } catch {
-        // Non-fatal — daemon can also discover sessions via filesystem scan
+        // Non-fatal — startup catch-up can also discover sessions via filesystem scan
       }
     }
 
-    // 2. Close the store (instant)
+    // 2. Stop scheduler and close the store (instant)
+    stopWikiScheduler(wikiDir);
+
     if (store) {
       try {
         await closeStore(store);

package/src/maintainer.ts

@@ -9,12 +9,12 @@
  * stay in code. This agent handles everything that needs intelligence.
  */
 
-import { Agent } from "@mariozechner/pi-agent-core";
-import type { AgentTool } from "@mariozechner/pi-agent-core";
-import type { Model } from "@mariozechner/pi-ai";
+import { Agent } from "@earendil-works/pi-agent-core";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { Model } from "@earendil-works/pi-ai";
 import type { QMDStore } from "qmd-engine";
 import { Type } from "typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 
 import {
   readPage,

package/src/model-resolver.ts

@@ -0,0 +1,96 @@
+import type { Model } from "@earendil-works/pi-ai";
+import type { ProviderCredentialRef, ParaUserConfig } from "./config.js";
+import { resolveCredentialRef } from "./credentials.js";
+
+export interface ModelRegistryLike {
+  getAvailable(): Model<any>[];
+  find(provider: string, modelId: string): Model<any> | undefined;
+  getApiKeyForProvider(provider: string): Promise<string | undefined>;
+}
+
+export interface AuthStorageLike {
+  getApiKey(provider: string): Promise<string | undefined>;
+}
+
+export type ModelSelection = ProviderCredentialRef | "auto";
+
+export function parseProviderModelSpec(spec: string): { provider: string; modelId: string } | null {
+  const idx = spec.indexOf("/");
+  if (idx <= 0 || idx === spec.length - 1) return null;
+  return { provider: spec.slice(0, idx), modelId: spec.slice(idx + 1) };
+}
+
+export function resolveSelectedModel(
+  selection: ModelSelection,
+  registry: ModelRegistryLike,
+  opts: { legacyModelSpec?: string | null; preferredModelSpec?: string } = {},
+): Model<any> | null {
+  if (selection !== "auto") {
+    if (selection.model) return registry.find(selection.provider, selection.model) ?? null;
+    return registry.getAvailable().find((model) => model.provider === selection.provider) ?? null;
+  }
+
+  const legacy = opts.legacyModelSpec ? parseProviderModelSpec(opts.legacyModelSpec) : null;
+  if (legacy) {
+    const model = registry.find(legacy.provider, legacy.modelId);
+    if (model) return model;
+  }
+
+  const preferred = opts.preferredModelSpec ? parseProviderModelSpec(opts.preferredModelSpec) : null;
+  if (preferred) {
+    const model = registry.find(preferred.provider, preferred.modelId);
+    if (model) return model;
+  }
+
+  return pickBestAvailableModel(registry.getAvailable());
+}
+
+export function pickBestAvailableModel(models: Model<any>[]): Model<any> | null {
+  if (models.length === 0) return null;
+  const sonnet = models.find((model) => model.provider === "anthropic" && /sonnet/i.test(model.id));
+  if (sonnet) return sonnet;
+  return [...models].sort((a, b) => (b.contextWindow ?? 0) - (a.contextWindow ?? 0))[0] ?? null;
+}
+
+export function createModelApiKeyResolver(
+  selection: ModelSelection,
+  registry: ModelRegistryLike,
+  opts: { authStorage?: AuthStorageLike; secretsPath?: string } = {},
+): (provider: string) => Promise<string | undefined> {
+  return async (provider: string) => {
+    if (selection === "auto") return registry.getApiKeyForProvider(provider);
+
+    if (selection.credentialRef.startsWith("pi-auth:")) {
+      const configuredProvider = selection.credentialRef.slice("pi-auth:".length);
+      if (configuredProvider !== provider && selection.provider !== provider) return undefined;
+      return (await opts.authStorage?.getApiKey(provider)) ?? await registry.getApiKeyForProvider(provider);
+    }
+
+    if (selection.credentialRef.startsWith("secret:")) {
+      if (selection.provider !== provider) return undefined;
+      const resolved = await resolveCredentialRef(selection.credentialRef, { secretsPath: opts.secretsPath });
+      return resolved.ok ? resolved.value : undefined;
+    }
+
+    return undefined;
+  };
+}
+
+export function getCaptureSelection(config: ParaUserConfig): ModelSelection {
+  return config.models.capture;
+}
+
+export async function createPiModelRegistry(): Promise<{ authStorage: AuthStorageLike; modelRegistry: ModelRegistryLike } | null> {
+  try {
+    const mod = await import("@earendil-works/pi-coding-agent");
+    const typed = mod as unknown as {
+      AuthStorage?: { create(): AuthStorageLike };
+      ModelRegistry?: { create(authStorage: AuthStorageLike): ModelRegistryLike };
+    };
+    if (!typed.AuthStorage || !typed.ModelRegistry) return null;
+    const authStorage = typed.AuthStorage.create();
+    return { authStorage, modelRegistry: typed.ModelRegistry.create(authStorage) };
+  } catch {
+    return null;
+  }
+}

package/src/paths.ts

@@ -0,0 +1,48 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export interface ParaPaths {
+  homeDir: string;
+  agentDir: string;
+  paraDir: string;
+  wikiDir: string;
+  userConfigPath: string;
+  secretsPath: string;
+  schedulerDbPath: string;
+  qmdDbPath: string;
+  legacyConfigPath: string;
+  legacyQmdConfigPath: string;
+  piSettingsPath: string;
+}
+
+export function expandHome(path: string, homeDir = homedir()): string {
+  if (path === "~") return homeDir;
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(homeDir, path.slice(2));
+  return path;
+}
+
+export function resolvePath(path: string, baseDir = process.cwd(), homeDir = homedir()): string {
+  const expanded = expandHome(path, homeDir);
+  return isAbsolute(expanded) ? expanded : resolve(baseDir, expanded);
+}
+
+export function getParaPaths(opts: { homeDir?: string; wikiDir?: string } = {}): ParaPaths {
+  const homeDir = opts.homeDir ?? homedir();
+  const agentDir = join(homeDir, ".pi", "agent");
+  const paraDir = join(homeDir, ".pi", "para");
+  const wikiDir = opts.wikiDir ? resolvePath(opts.wikiDir, process.cwd(), homeDir) : join(homeDir, ".pi", "wiki");
+
+  return {
+    homeDir,
+    agentDir,
+    paraDir,
+    wikiDir,
+    userConfigPath: join(paraDir, "config.jsonc"),
+    secretsPath: join(paraDir, "secrets.json"),
+    schedulerDbPath: join(wikiDir, ".pi-para.sqlite"),
+    qmdDbPath: join(wikiDir, ".qmd.sqlite"),
+    legacyConfigPath: join(wikiDir, "config.json"),
+    legacyQmdConfigPath: join(homeDir, ".config", "qmd", "index.yml"),
+    piSettingsPath: join(agentDir, "settings.json"),
+  };
+}

package/src/processor.ts

@@ -3,9 +3,9 @@
  * to extract knowledge and write wiki pages.
  */
 
-import { Agent } from "@mariozechner/pi-agent-core";
-import type { AgentMessage, AgentTool } from "@mariozechner/pi-agent-core";
-import type { Model } from "@mariozechner/pi-ai";
+import { Agent } from "@earendil-works/pi-agent-core";
+import type { AgentMessage, AgentTool } from "@earendil-works/pi-agent-core";
+import type { Model } from "@earendil-works/pi-ai";
 import type { QMDStore } from "qmd-engine";
 
 import {
@@ -25,7 +25,7 @@ import { redactSecrets } from "./redact.js";
 import { reindex, searchWiki } from "./store.js";
 import { appendSessionDigest } from "./raw.js";
 import { Type } from "typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 
 import { loadSession, createSessionTools } from "./session-tools.js";
 import type { LoadedSession } from "./session-tools.js";