pi-para 0.5.2

package/src/context.ts

@@ -0,0 +1,390 @@
+/**
+ * Session context injection — injects relevant wiki knowledge into every agent turn.
+ *
+ * Builds a context string from schema.md, index.md, and scope-filtered page
+ * summaries, injected via the before_agent_start hook.
+ *
+ * Uses a dirty-flag caching strategy: the context string is rebuilt only when
+ * wiki_write or wiki_move modifies the wiki (or on session start). Cached
+ * context is returned on subsequent before_agent_start calls, adding <5ms.
+ */
+
+import type { QMDStore } from "qmd-engine";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  BeforeAgentStartEventResult,
+} from "@mariozechner/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";
+
+// -- Types ------------------------------------------------------------------
+
+export interface ContextOptions {
+  maxTokens?: number; // max tokens for wiki context (default 4000)
+  includeSchema?: boolean; // include schema.md (default true)
+  includeIndex?: boolean; // include index.md (default true)
+  includeSummaries?: boolean; // include page summaries (default true)
+}
+
+/** Config subset needed by context injection. */
+export interface ContextConfig {
+  contextMaxTokens?: number;
+  contextIncludeSchema?: boolean;
+  contextIncludeIndex?: boolean;
+}
+
+// -- Constants ---------------------------------------------------------------
+
+const DEFAULT_MAX_TOKENS = 4000;
+const CHARS_PER_TOKEN = 4;
+
+/** Maximum number of pages to include in context injection. */
+export const MAX_CONTEXT_PAGES = 40;
+
+// -- Schema summary ----------------------------------------------------------
+
+/**
+ * A compact conventions summary extracted from schema.md, much smaller than
+ * the full schema. Used to give the LLM essential rules without blowing the
+ * token budget.
+ */
+function buildSchemaSummary(fullSchema: string): string {
+  // If the schema is small enough, include it verbatim
+  if (fullSchema.length / CHARS_PER_TOKEN < 500) {
+    return fullSchema;
+  }
+
+  // Otherwise return a compact summary of key conventions
+  return [
+    "## Wiki Conventions (summary)",
+    "",
+    "- Pages: markdown + YAML frontmatter (title, para, scope, tags, sources, created, updated, links)",
+    "- PARA categories: **resources/** for almost everything (architecture docs, how-tos, patterns, debugging). **areas/** for ongoing responsibilities. **projects/** ONLY for actual goals with end dates. **archives/** for completed items.",
+    "- Scope: must be a kebab-case project name (e.g. `pi-para`, `qmd`). NOT topic descriptions.",
+    "- Tags: kebab-case, no spaces. Don't duplicate scope values as tags.",
+    "- Slugs: lowercase, hyphens (e.g. ssl-cert-gotchas)",
+    "- Cross-references: use [[slug]] wikilinks. Add a ## Connections section linking related pages.",
+    "- Wiki summary format sections: Topic, Key Facts, Insights, Connections, Open Questions, Sources",
+    "- Update existing pages for same concept, create new pages for distinct concepts",
+    "- Tone: technical, concise, factual",
+  ].join("\n");
+}
+
+// -- Public API --------------------------------------------------------------
+
+/**
+ * Build a context string from wiki state for injection into the system prompt.
+ *
+ * Strategy:
+ * 1. Always include schema conventions summary + index.md
+ * 2. Conditionally include first paragraph / summary of pages matching scope
+ * 3. If budget exceeded, fall back to index + page titles only
+ */
+export async function buildContext(
+  wikiDir: string,
+  _store: QMDStore,
+  scope: ProjectScope,
+  options?: ContextOptions,
+  stateDb?: StateDB,
+): Promise<string> {
+  const maxTokens = options?.maxTokens ?? DEFAULT_MAX_TOKENS;
+  const includeSchema = options?.includeSchema ?? true;
+  const includeIndex = options?.includeIndex ?? true;
+  const includeSummaries = options?.includeSummaries ?? true;
+
+  const maxChars = maxTokens * CHARS_PER_TOKEN;
+  const parts: string[] = [];
+  let usedChars = 0;
+
+  // Header
+  const header = `<wiki-context scope="${scope.name}">`;
+  const footer = "</wiki-context>";
+  usedChars += header.length + footer.length + 2; // +2 for newlines
+
+  // 1. Schema conventions summary
+  if (includeSchema) {
+    let schemaContent: string;
+    try {
+      schemaContent = await readSchema(wikiDir);
+    } catch {
+      schemaContent = "";
+    }
+    if (schemaContent) {
+      const summary = buildSchemaSummary(schemaContent);
+      if (usedChars + summary.length + 2 <= maxChars) {
+        parts.push(summary);
+        usedChars += summary.length + 2;
+      }
+    }
+  }
+
+  // 2. Index.md
+  let indexContent = "";
+  if (includeIndex) {
+    try {
+      indexContent = await readIndex(wikiDir);
+    } catch {
+      indexContent = "";
+    }
+    if (indexContent) {
+      if (usedChars + indexContent.length + 2 <= maxChars) {
+        parts.push(indexContent);
+        usedChars += indexContent.length + 2;
+      } else {
+        // Truncate index to fit
+        const available = maxChars - usedChars - 2;
+        if (available > 100) {
+          parts.push(indexContent.slice(0, available) + "\n...(truncated)");
+          usedChars = maxChars;
+        }
+      }
+    }
+  }
+
+  // 3. Scope-filtered page summaries
+  if (includeSummaries && usedChars < maxChars) {
+    // Use stateDb cache if available, otherwise fall back to disk reads
+    const scopeEntries = stateDb
+      ? await buildScopeEntriesFromCache(stateDb, scope)
+      : await buildScopeEntriesFromDisk(wikiDir, scope);
+
+    // Sort by updated date descending (most recent first)
+    scopeEntries.sort((a, b) => {
+      const dateA = new Date(a.updatedAt).getTime() || 0;
+      const dateB = new Date(b.updatedAt).getTime() || 0;
+      return dateB - dateA;
+    });
+
+    const totalScopePages = scopeEntries.length;
+
+    // Tier: only include top MAX_CONTEXT_PAGES
+    const tieredEntries = scopeEntries.slice(0, MAX_CONTEXT_PAGES);
+    const remaining = totalScopePages - tieredEntries.length;
+
+    const summaryParts: string[] = [];
+    const titleFallbacks: string[] = [];
+
+    for (const entry of tieredEntries) {
+      const summaryLine = `- **[[${entry.slug}]]** (${entry.category}): ${entry.firstParagraph}`;
+      const titleLine = `- [[${entry.slug}]] (${entry.category})`;
+
+      titleFallbacks.push(titleLine);
+
+      if (usedChars + summaryLine.length + 2 <= maxChars) {
+        summaryParts.push(summaryLine);
+        usedChars += summaryLine.length + 1;
+      }
+    }
+
+    if (summaryParts.length > 0) {
+      let summaryBlock =
+        "## Relevant Pages\n\n" + summaryParts.join("\n");
+      if (remaining > 0) {
+        summaryBlock += `\n\n*${remaining} more pages available via wiki_query*`;
+      }
+      parts.push(summaryBlock);
+    } else if (titleFallbacks.length > 0) {
+      // Budget exceeded for summaries — try titles only
+      let titlesBlock =
+        "## Relevant Pages (titles only)\n\n" + titleFallbacks.join("\n");
+      if (remaining > 0) {
+        titlesBlock += `\n\n*${remaining} more pages available via wiki_query*`;
+      }
+      const availableChars = maxChars - usedChars;
+      if (titlesBlock.length <= availableChars) {
+        parts.push(titlesBlock);
+      }
+    }
+  }
+
+  if (parts.length === 0) {
+    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."
+  );
+
+  return header + "\n" + parts.join("\n\n") + "\n" + footer;
+}
+
+// -- Caching and lifecycle ---------------------------------------------------
+
+/** Module-level dirty flag, exported for tools.ts to call after mutations. */
+let contextDirty = true;
+let cachedContext: string | null = null;
+
+/**
+ * Mark the cached context as dirty. Call this after wiki_write or wiki_move
+ * so the next before_agent_start rebuilds the context.
+ */
+export function markContextDirty(): void {
+  contextDirty = true;
+}
+
+/**
+ * Wire up context injection on the extension API.
+ *
+ * - On session_start: mark dirty so context is rebuilt for the new scope
+ * - On before_agent_start: return cached context if clean, rebuild if dirty
+ *
+ * @param pi - The extension API
+ * @param wikiDir - Path to the wiki directory
+ * @param store - qmd store instance (or getter returning one)
+ * @param getScope - Returns the current ProjectScope
+ * @param getConfig - Returns the current config values for context
+ */
+export function setupContextInjection(
+  pi: ExtensionAPI,
+  wikiDir: string,
+  store: QMDStore,
+  getScope: () => ProjectScope | null,
+  getConfig: () => ContextConfig,
+): void {
+  // Reset cache state for a fresh setup
+  contextDirty = true;
+  cachedContext = null;
+
+  pi.on("session_start", async () => {
+    contextDirty = true;
+    cachedContext = null;
+  });
+
+  pi.on(
+    "before_agent_start",
+    async (
+      event,
+      _ctx: ExtensionContext,
+    ): Promise<BeforeAgentStartEventResult | void> => {
+      const scope = getScope();
+      if (!scope) return;
+
+      if (!contextDirty && cachedContext !== null) {
+        // Return cached context
+        if (cachedContext) {
+          return {
+            systemPrompt: event.systemPrompt + "\n\n" + cachedContext,
+          };
+        }
+        return;
+      }
+
+      // Rebuild context
+      const config = getConfig();
+      const options: ContextOptions = {
+        maxTokens: config.contextMaxTokens ?? DEFAULT_MAX_TOKENS,
+        includeSchema: config.contextIncludeSchema ?? true,
+        includeIndex: true,
+      };
+
+      try {
+        cachedContext = await buildContext(wikiDir, store, scope, options);
+        contextDirty = false;
+      } catch {
+        // On error, clear cache and don't inject anything
+        cachedContext = null;
+        contextDirty = false;
+        return;
+      }
+
+      if (cachedContext) {
+        return {
+          systemPrompt: event.systemPrompt + "\n\n" + cachedContext,
+        };
+      }
+    },
+  );
+}
+
+// -- Helpers -----------------------------------------------------------------
+
+interface ScopeEntry {
+  slug: string;
+  category: string;
+  firstParagraph: string;
+  updatedAt: string;
+}
+
+/** Build scope entries from the StateDB page summary cache. */
+async function buildScopeEntriesFromCache(
+  stateDb: StateDB,
+  scope: ProjectScope,
+): Promise<ScopeEntry[]> {
+  const summaries = stateDb.getPageSummaries(scope);
+  return summaries.map((s) => ({
+    slug: s.slug,
+    category: s.category,
+    firstParagraph: s.firstParagraph || "(no summary)",
+    updatedAt: s.updatedAt,
+  }));
+}
+
+/** Build scope entries by reading all pages from disk. */
+async function buildScopeEntriesFromDisk(
+  wikiDir: string,
+  scope: ProjectScope,
+): Promise<ScopeEntry[]> {
+  const pages = await listPages(wikiDir);
+  const entries: ScopeEntry[] = [];
+
+  for (const ref of pages) {
+    const page = await readPage(wikiDir, ref.category, ref.slug);
+    if (!page) continue;
+    if (!matchesScope(page.frontmatter.scope, scope)) continue;
+
+    entries.push({
+      slug: ref.slug,
+      category: ref.category,
+      firstParagraph: extractFirstParagraph(page.body),
+      updatedAt: page.frontmatter.updated,
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Extract the first non-empty paragraph from a markdown body.
+ * Skips headings and blank lines. Returns a single line.
+ */
+export function extractFirstParagraph(body: string): string {
+  const lines = body.split("\n");
+  const paragraphLines: string[] = [];
+  let inParagraph = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip headings and empty lines before paragraph starts
+    if (!inParagraph) {
+      if (trimmed === "" || trimmed.startsWith("#")) continue;
+      inParagraph = true;
+    }
+
+    // End paragraph on blank line or heading
+    if (inParagraph && (trimmed === "" || trimmed.startsWith("#"))) {
+      break;
+    }
+
+    paragraphLines.push(trimmed);
+  }
+
+  const result = paragraphLines.join(" ");
+  // Truncate long paragraphs
+  if (result.length > 200) {
+    return result.slice(0, 197) + "...";
+  }
+  return result || "(no summary)";
+}

package/src/daemon.ts

@@ -0,0 +1,288 @@
+/**
+ * Main daemon loop — watches for completed sessions and processes them.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import type { Model } from "@mariozechner/pi-ai";
+import { openStore, closeStore } from "./store.js";
+import type { QMDStore } from "qmd-engine";
+
+import { StateDB } from "./state.js";
+import { RegistryWatcher } from "./watcher.js";
+import type { CompletedSession } from "./watcher.js";
+import { processSession } from "./processor.js";
+import { runMaintenance } from "./maintainer.js";
+import { startServer } from "./webui/server.js";
+import type { WebWikiConfig } from "./webui/server.js";
+
+export interface DaemonConfig {
+  wikiDir: string;
+  model: Model<any>;
+  getApiKey: (provider: string) => Promise<string | undefined>;
+  pollIntervalMs?: number;
+  /** How often to run link discovery + lint (ms). Default: 30 minutes */
+  maintenanceIntervalMs?: number;
+  /** Web wiki server config. If enabled, the daemon hosts the web UI. */
+  webWiki?: WebWikiConfig;
+}
+
+export class Daemon {
+  private config: DaemonConfig;
+  private state: StateDB;
+  private watcher: RegistryWatcher;
+  private store: QMDStore | null = null;
+  private queue: CompletedSession[] = [];
+  private processing = false;
+  private running = false;
+  private maintenanceTimer: ReturnType<typeof setInterval> | null = null;
+  private maintenanceRunning = false;
+  private webServer: { close: () => Promise<void>; url: string } | null = null;
+
+  constructor(config: DaemonConfig) {
+    this.config = config;
+    this.state = new StateDB(config.wikiDir);
+    this.watcher = new RegistryWatcher(
+      config.wikiDir,
+      (entries) => this.onNewEntries(entries),
+      config.pollIntervalMs ?? 5000,
+    );
+  }
+
+  /** Start the daemon. */
+  async start(): Promise<void> {
+    console.log(`[daemon] Starting — wiki: ${this.config.wikiDir}`);
+
+    // Open qmd store
+    try {
+      this.store = await openStore(this.config.wikiDir);
+      console.log("[daemon] qmd store opened");
+    } catch (err) {
+      console.error(`[daemon] Failed to open store: ${err instanceof Error ? err.message : err}`);
+      this.store = null;
+    }
+
+    this.running = true;
+    this.state.setState("daemon_started_at", new Date().toISOString());
+    this.state.setState("daemon_pid", String(process.pid));
+
+    // Start watching
+    this.watcher.start();
+
+    // Process any unprocessed sessions from registry
+    const existing = this.watcher.getAllEntries();
+    const unprocessed = existing.filter((e) => !this.state.isProcessed(e.sessionPath));
+    if (unprocessed.length > 0) {
+      console.log(`[daemon] Found ${unprocessed.length} unprocessed session(s)`);
+      this.onNewEntries(unprocessed);
+    }
+
+    // Start periodic maintenance (link discovery + lint)
+    const maintenanceMs = this.config.maintenanceIntervalMs ?? 30 * 60 * 1000;
+    this.maintenanceTimer = setInterval(() => this.runMaintenancePass(), maintenanceMs);
+    // Run first maintenance after a delay to let the store warm up
+    setTimeout(() => this.runMaintenancePass(), 60_000);
+
+    // Start web wiki server if enabled
+    if (this.config.webWiki?.enabled) {
+      try {
+        this.webServer = startServer(this.config.wikiDir, this.store, this.config.webWiki);
+        console.log(`[daemon] Web wiki: ${this.webServer.url}`);
+      } catch (err) {
+        console.error(`[daemon] Web wiki failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    console.log(`[daemon] Running (maintenance every ${Math.round(maintenanceMs / 60000)}m). Press Ctrl+C to stop.`);
+  }
+
+  /** Stop the daemon. */
+  async stop(): Promise<void> {
+    console.log("[daemon] Stopping...");
+    this.running = false;
+    this.watcher.stop();
+    if (this.maintenanceTimer) {
+      clearInterval(this.maintenanceTimer);
+      this.maintenanceTimer = null;
+    }
+
+    // Stop web wiki server
+    if (this.webServer) {
+      try {
+        await this.webServer.close();
+        console.log("[daemon] Web wiki stopped");
+      } catch {}
+      this.webServer = null;
+    }
+
+    if (this.store) {
+      try {
+        await closeStore(this.store);
+      } catch {}
+      this.store = null;
+    }
+
+    this.state.close();
+    console.log("[daemon] Stopped.");
+  }
+
+  /** Get the web server URL (if running). */
+  getWebUrl(): string | null {
+    return this.webServer?.url ?? null;
+  }
+
+  /** Process a single session file (for CLI `process` command). */
+  async processOne(sessionPath: string): Promise<void> {
+    if (!existsSync(sessionPath)) {
+      console.error(`[daemon] Session file not found: ${sessionPath}`);
+      return;
+    }
+
+    if (!this.store) {
+      try {
+        this.store = await openStore(this.config.wikiDir);
+      } catch (err) {
+        console.error(`[daemon] Failed to open store: ${err instanceof Error ? err.message : err}`);
+        return;
+      }
+    }
+
+    const scope = detectScopeFromPath(sessionPath);
+    console.log(`[daemon] Processing: ${sessionPath} (scope: ${scope})`);
+
+    try {
+      const result = await processSession(
+        sessionPath,
+        this.config.wikiDir,
+        this.store,
+        scope,
+        this.config.model,
+        this.config.getApiKey,
+      );
+
+      if (result.skipped) {
+        console.log(`[daemon] Skipped: ${result.reason}`);
+        this.state.recordSuccess(sessionPath, scope, [], []);
+      } else {
+        console.log(`[daemon] Done: ${result.pagesCreated.length} created, ${result.pagesUpdated.length} updated`);
+        this.state.recordSuccess(sessionPath, scope, result.pagesCreated, result.pagesUpdated);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[daemon] Failed: ${msg}`);
+      this.state.recordFailure(sessionPath, scope, msg);
+    }
+  }
+
+  /** Handle new entries from the registry watcher. */
+  private onNewEntries(entries: CompletedSession[]): void {
+    // Filter already-processed
+    const newEntries = entries.filter(
+      (e) => existsSync(e.sessionPath) && !this.state.isProcessed(e.sessionPath),
+    );
+
+    if (newEntries.length === 0) return;
+
+    console.log(`[daemon] Queued ${newEntries.length} session(s) for processing`);
+    this.queue.push(...newEntries);
+    this.processQueue();
+  }
+
+  /** Process queued sessions sequentially. */
+  private async processQueue(): Promise<void> {
+    if (this.processing || !this.running) return;
+    this.processing = true;
+
+    while (this.queue.length > 0 && this.running) {
+      const entry = this.queue.shift()!;
+      await this.processOne(entry.sessionPath);
+    }
+
+    this.processing = false;
+  }
+
+  /** Run periodic maintenance via LLM agent. */
+  private async runMaintenancePass(): Promise<void> {
+    if (this.maintenanceRunning || !this.running || !this.store) return;
+    this.maintenanceRunning = true;
+
+    try {
+      console.log("[daemon] Running maintenance agent...");
+      const result = await runMaintenance(
+        this.config.wikiDir,
+        this.store,
+        this.config.model,
+        this.config.getApiKey,
+      );
+      console.log(
+        `[daemon] Maintenance done: ${result.pagesUpdated} updated, ${result.pagesMerged} merged`,
+      );
+      if (result.summary) {
+        // Log first 200 chars of summary
+        console.log(`[daemon] Summary: ${result.summary.slice(0, 200)}`);
+      }
+    } catch (err) {
+      console.error(
+        `[daemon] Maintenance error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    this.maintenanceRunning = false;
+  }
+
+  /** Get processing history. */
+  getHistory(scope?: string, limit?: number) {
+    return this.state.getHistory(scope, limit);
+  }
+
+  /** Get failed sessions. */
+  getFailed() {
+    return this.state.getFailed();
+  }
+
+  /** Retry all failed sessions. */
+  async retryFailed(): Promise<void> {
+    const failed = this.state.getFailed();
+    if (failed.length === 0) {
+      console.log("[daemon] No failed sessions to retry.");
+      return;
+    }
+    console.log(`[daemon] Retrying ${failed.length} failed session(s)...`);
+    for (const session of failed) {
+      await this.processOne(session.sessionPath);
+    }
+  }
+}
+
+/** Extract project scope from session path or header. */
+function detectScopeFromPath(sessionPath: string): string {
+  // 1. Try reading the session header — most reliable, has the real cwd
+  try {
+    const { readFileSync } = require("node:fs");
+    const firstLine = readFileSync(sessionPath, "utf-8").split("\n")[0];
+    const header = JSON.parse(firstLine);
+    if (header.cwd) {
+      const parts = header.cwd.split("/");
+      return parts[parts.length - 1] ?? "unknown";
+    }
+  } catch {}
+
+  // 2. Fallback: decode from directory name
+  // Path format: ~/.pi/agent/sessions/--home-ubuntu-projects-pi-mono--/file.jsonl
+  // The dir name encodes the cwd path with / replaced by -
+  // But project names can contain hyphens, so we can't just replace all - with /
+  // Instead, find the last segment after "projects-" which is the project name
+  const dirName = sessionPath.split("/").slice(-2, -1)[0] ?? "";
+  if (dirName.startsWith("--") && dirName.endsWith("--")) {
+    const inner = dirName.slice(2, -2); // e.g. "home-ubuntu-projects-agent-board"
+    // Look for "projects-" marker — everything after it is the project name
+    const projectsIdx = inner.indexOf("projects-");
+    if (projectsIdx >= 0) {
+      return inner.slice(projectsIdx + "projects-".length); // "agent-board"
+    }
+  }
+
+  return "unknown";
+}