@zosmaai/pi-llm-wiki 0.7.2 → 0.7.4

package/extensions/llm-wiki/lib/observation.ts

@@ -0,0 +1,310 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { appendEvent, rebuildMetadataLight } from "./metadata.js";
+import { type VaultPaths, fmtDate, resolveVaultPaths } from "./utils.js";
+
+// ─── Types ─────────────────────────────────────────────
+
+export interface ObservationInput {
+  /** Short descriptive title (≤80 chars) */
+  title: string;
+  /** The observation content — what happened, was decided, or was learned */
+  content: string;
+  /** Relevance level for retention priority */
+  relevance: "low" | "medium" | "high" | "critical";
+  /** Optional space-separated tags for categorization */
+  tags?: string;
+  /** Context: what was being worked on when this was observed */
+  source_context?: string;
+}
+
+export interface ObservationResult {
+  slug: string;
+  pagePath: string;
+}
+
+// ─── Save Observation ──────────────────────────────────
+
+const RELEVANCE_EMOJIS: Record<string, string> = {
+  low: "📝",
+  medium: "🔍",
+  high: "⭐",
+  critical: "🔴",
+};
+
+/**
+ * Save an observation as a wiki source page.
+ *
+ * Unlike wiki_retro (which saves atomic insights at task end),
+ * wiki_observe records timestamped observations during a session
+ * that can later be distilled into durable wiki pages.
+ *
+ * Observations are stored in wiki/sources/ with type: source and
+ * status: observation. They are searchable via wiki_recail.
+ */
+export function saveObservation(paths: VaultPaths, input: ObservationInput): ObservationResult {
+  const today = fmtDate();
+  const timestamp = new Date().toISOString();
+
+  // Generate a slug from title
+  const slugBase = input.title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
+  const slug = `obs-${today}-${slugBase}`;
+
+  // Write to wiki/sources/{slug}.md
+  const sourcePageDir = join(paths.wiki, "sources");
+  mkdirSync(sourcePageDir, { recursive: true });
+  const pagePath = join(sourcePageDir, `${slug}.md`);
+
+  const relevanceEmoji = RELEVANCE_EMOJIS[input.relevance] ?? "📝";
+  const tags = input.tags ?? "";
+  const sourceContext = input.source_context ?? "";
+
+  const pageContent = [
+    "---",
+    "type: source",
+    `title: "Observation: ${input.title}"`,
+    `slug: ${slug}`,
+    "status: observation",
+    `created: ${today}`,
+    `updated: ${today}`,
+    `relevance: ${input.relevance}`,
+    `observed_at: ${timestamp}`,
+    tags
+      ? `tags: [${tags
+          .split(/\s+/)
+          .filter(Boolean)
+          .map((t) => `"${t}"`)
+          .join(", ")}]`
+      : "",
+    sourceContext ? `source_context: "${sourceContext}"` : "",
+    "---",
+    "",
+    `# ${relevanceEmoji} Observation: ${input.title}`,
+    "",
+    input.content,
+    "",
+    `*Relevance: ${input.relevance}*`,
+    sourceContext ? `\n*Context: ${sourceContext}*` : "",
+    tags ? `\n*Tags: ${tags}*` : "",
+    "",
+    "---",
+    `*Observed: ${timestamp}*`,
+    "",
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+  writeFileSync(pagePath, pageContent, "utf-8");
+
+  // Log event
+  appendEvent(paths, {
+    kind: "observe",
+    slug,
+    title: input.title,
+    relevance: input.relevance,
+  });
+
+  // Rebuild metadata so the observation is immediately searchable
+  rebuildMetadataLight(paths);
+
+  return { slug, pagePath };
+}
+
+// ─── Shared Reminder State ────────────────────────────
+
+/**
+ * Mutable state shared between wiki_observe tool and the turn-end reminder.
+ * When the model calls wiki_observe, the tool sets observeDoneThisSession
+ * so the reminder stops nagging.
+ */
+export interface ReminderState {
+  observeDoneThisSession: boolean;
+}
+
+export function createReminderState(): ReminderState {
+  return { observeDoneThisSession: false };
+}
+
+// ─── Tool Registration ─────────────────────────────────
+
+/**
+ * Register the `wiki_observe` tool.
+ * The model calls this to record observations during a session.
+ * Observations are saved to the wiki and become searchable.
+ */
+export function registerWikiObserve(pi: ExtensionAPI, reminderState?: ReminderState): void {
+  pi.registerTool({
+    name: "wiki_observe",
+    label: "Wiki Observe",
+    description:
+      "Record an atomic observation from the current session into the wiki. " +
+      "Observations are timestamped, relevance-rated facts about decisions made, " +
+      "findings discovered, constraints established, or work completed. " +
+      "Saved observations are searchable via wiki_recall and can later be " +
+      "distilled into durable wiki pages via wiki_ensure_page. " +
+      "Call this proactively after non-trivial work — every observation " +
+      "compounds the wiki's knowledge across sessions.",
+    promptSnippet: "Record an observation about the current work",
+    promptGuidelines: [
+      "Call wiki_observe after non-trivial decisions, discoveries, or completions.",
+      "One observation per call. Use multiple calls for multiple observations.",
+      "Rate relevance honestly — most observations are medium or low, not critical.",
+      "Observations compound across sessions via wiki_recail.",
+    ],
+    parameters: Type.Object({
+      title: Type.String({
+        description:
+          "Short descriptive title (≤80 chars). Noun phrase, not a sentence. " +
+          "Example: 'JWT auth middleware added' or 'Postgres migration constraint discovered'",
+      }),
+      content: Type.String({
+        description:
+          "The observation in plain prose. What happened, was decided, or was learned. " +
+          "Preserve specific details: file paths, function names, error messages, " +
+          "quantitative results. Example: 'User decided to use JWT with refresh tokens. " +
+          "Implementation at src/auth/jwt.ts. Tests passing.'",
+      }),
+      relevance: Type.Union(
+        [
+          Type.Literal("low"),
+          Type.Literal("medium"),
+          Type.Literal("high"),
+          Type.Literal("critical"),
+        ],
+        {
+          description:
+            "Relevance level: low (routine), medium (task context), " +
+            "high (non-trivial decisions/constraints), critical (user identity, " +
+            "persistent preferences, completed work that must not be redone). " +
+            "Default: medium. Be honest — most observations are medium or low.",
+        },
+      ),
+      tags: Type.Optional(
+        Type.String({
+          description:
+            "Optional space-separated tags for categorization. " +
+            "Example: 'auth backend migration'",
+        }),
+      ),
+      source_context: Type.Optional(
+        Type.String({
+          description:
+            "What was being worked on. Example: 'Adding authentication module' or 'Debugging login timeout'",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = resolveVaultPaths(ctx.cwd ?? process.cwd());
+
+      if (!existsSync(join(paths.dotWiki, "config.json"))) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No wiki vault found at this location. Initialize one with wiki_bootstrap first.",
+            },
+          ],
+          details: { error: "no_vault" } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      const result = saveObservation(paths, {
+        title: params.title,
+        content: params.content,
+        relevance: params.relevance,
+        tags: params.tags,
+        source_context: params.source_context,
+      });
+
+      // Signal the reminder to stop nagging this session
+      if (reminderState) {
+        reminderState.observeDoneThisSession = true;
+      }
+
+      const relevanceEmoji = RELEVANCE_EMOJIS[params.relevance] ?? "📝";
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `${relevanceEmoji} **Observation saved**: ${params.title}`,
+              "",
+              `- Page: \`${result.pagePath}\``,
+              `- Relevance: ${params.relevance}`,
+              params.tags ? `- Tags: ${params.tags}` : "",
+              "",
+              "This observation is now searchable via wiki_recall. " +
+                "It will compound with future observations across sessions.",
+            ]
+              .filter((l) => l !== "")
+              .join("\n"),
+          },
+        ],
+        details: {
+          slug: result.slug,
+          title: params.title,
+          relevance: params.relevance,
+          tags: params.tags || null,
+        } as Record<string, unknown>,
+      };
+    },
+  });
+}
+
+// ─── Turn-End Reminder ─────────────────────────────────
+
+/**
+ * Track observation cadence and send turn-end reminders.
+ * After every N significant turns, reminds the model to call wiki_observe
+ * for non-trivial findings (same pattern as memex-retro reminders).
+ */
+export function registerObservationReminder(
+  pi: ExtensionAPI,
+  reminderState: ReminderState,
+  options?: { turnsBetweenReminders?: number },
+): void {
+  const REMINDER_INTERVAL = options?.turnsBetweenReminders ?? 5;
+  let turnsSinceLastReminder = 0;
+
+  pi.on("session_start", async () => {
+    turnsSinceLastReminder = 0;
+    reminderState.observeDoneThisSession = false;
+  });
+
+  // After compaction, reset the reminder state so reminders resume
+  pi.on("session_compact", async () => {
+    turnsSinceLastReminder = 0;
+    reminderState.observeDoneThisSession = false;
+  });
+
+  pi.on("agent_end", async (_event, _ctx) => {
+    turnsSinceLastReminder++;
+    if (turnsSinceLastReminder < REMINDER_INTERVAL) return;
+    if (reminderState.observeDoneThisSession) return;
+
+    pi.sendMessage(
+      {
+        customType: "wiki-observe-reminder",
+        content: [
+          "**Wiki observation reminder:** If the work in this session produced non-trivial ",
+          "decisions, findings, constraints, or completions worth preserving across sessions,",
+          "call `wiki_observe` to record them. Observations are searchable via `wiki_recall`",
+          "and compound your wiki's knowledge over time.",
+          "",
+          "One observation per call. Separate distinct findings into multiple calls.",
+        ].join(" "),
+        display: false,
+      },
+      {
+        deliverAs: "nextTurn",
+      },
+    );
+  });
+}