pi-continuous-learning 0.3.0

package/src/instinct-store.ts

@@ -0,0 +1,149 @@
+/**
+ * Instinct CRUD operations.
+ * Provides functions to load, save, list, and delete instinct files from disk.
+ * Path traversal prevention: instinct IDs must be kebab-case (no ".." possible).
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Instinct } from "./types.js";
+import { parseInstinct, serializeInstinct } from "./instinct-parser.js";
+import {
+  getBaseDir,
+  getProjectInstinctsDir,
+  getGlobalInstinctsDir,
+} from "./storage.js";
+
+const INSTINCT_EXTENSION = ".md";
+
+// ---------------------------------------------------------------------------
+// Mtime-based cache
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = 5_000;
+
+interface DirCache {
+  instincts: Instinct[];
+  maxMtime: number;
+  checkedAt: number;
+}
+
+const dirCache = new Map<string, DirCache>();
+
+export function invalidateCache(dir?: string): void {
+  if (dir) {
+    dirCache.delete(dir);
+  } else {
+    dirCache.clear();
+  }
+}
+
+function getMaxMtime(dir: string): number {
+  if (!existsSync(dir)) return 0;
+  const files = readdirSync(dir).filter((f) => f.endsWith(INSTINCT_EXTENSION));
+  let max = 0;
+  for (const file of files) {
+    try {
+      const mt = statSync(join(dir, file)).mtimeMs;
+      if (mt > max) max = mt;
+    } catch {
+      // skip files that disappeared between readdir and stat
+    }
+  }
+  return max;
+}
+
+function listInstinctsCached(dir: string): Instinct[] {
+  const now = Date.now();
+  const cached = dirCache.get(dir);
+
+  if (cached && now - cached.checkedAt < CACHE_TTL_MS) {
+    return cached.instincts;
+  }
+
+  const currentMaxMtime = getMaxMtime(dir);
+
+  if (cached && currentMaxMtime === cached.maxMtime && currentMaxMtime > 0) {
+    dirCache.set(dir, { ...cached, checkedAt: now });
+    return cached.instincts;
+  }
+
+  const instincts = listInstincts(dir);
+  dirCache.set(dir, { instincts, maxMtime: currentMaxMtime, checkedAt: now });
+  return instincts;
+}
+
+/**
+ * Guard against path traversal attacks in instinct IDs.
+ * Kebab-case validation in parseInstinct already prevents "..", but this
+ * provides an explicit defense for direct callers of save/load by file path.
+ */
+function assertNoPathTraversal(id: string): void {
+  if (id.includes("..") || id.includes("/") || id.includes("\\")) {
+    throw new Error(
+      `Invalid instinct ID "${id}": path traversal characters are not allowed.`
+    );
+  }
+}
+
+/**
+ * Load a single instinct from a .md file path.
+ */
+export function loadInstinct(filePath: string): Instinct {
+  const content = readFileSync(filePath, "utf-8");
+  return parseInstinct(content);
+}
+
+/**
+ * Save an instinct to <dir>/<id>.md.
+ * Validates the instinct ID against path traversal before writing.
+ */
+export function saveInstinct(instinct: Instinct, dir: string): void {
+  assertNoPathTraversal(instinct.id);
+  const filePath = join(dir, `${instinct.id}${INSTINCT_EXTENSION}`);
+  const content = serializeInstinct(instinct);
+  writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * List and load all instincts from a directory.
+ * Silently skips files that fail to parse (malformed instinct files).
+ */
+export function listInstincts(dir: string): Instinct[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  const files = readdirSync(dir).filter((f) => f.endsWith(INSTINCT_EXTENSION));
+  const instincts: Instinct[] = [];
+
+  for (const file of files) {
+    try {
+      const instinct = loadInstinct(join(dir, file));
+      instincts.push(instinct);
+    } catch {
+      // Skip malformed instinct files - do not crash the caller
+    }
+  }
+
+  return instincts;
+}
+
+/**
+ * Load all personal instincts for a specific project.
+ */
+export function loadProjectInstincts(
+  projectId: string,
+  baseDir = getBaseDir()
+): Instinct[] {
+  const dir = getProjectInstinctsDir(projectId, "personal", baseDir);
+  return listInstinctsCached(dir);
+}
+
+/**
+ * Load all global personal instincts.
+ */
+export function loadGlobalInstincts(baseDir = getBaseDir()): Instinct[] {
+  const dir = getGlobalInstinctsDir("personal", baseDir);
+  return listInstinctsCached(dir);
+}

package/src/instinct-tools.ts

@@ -0,0 +1,340 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Instinct } from "./types.js";
+import {
+  loadProjectInstincts,
+  loadGlobalInstincts,
+  saveInstinct,
+  loadInstinct,
+} from "./instinct-store.js";
+import {
+  getProjectInstinctsDir,
+  getGlobalInstinctsDir,
+} from "./storage.js";
+
+function getInstinctsDir(
+  scope: "project" | "global",
+  projectId: string | null,
+  baseDir?: string
+): string | null {
+  if (scope === "project") {
+    return projectId ? getProjectInstinctsDir(projectId, "personal", baseDir) : null;
+  }
+  return getGlobalInstinctsDir("personal", baseDir);
+}
+
+function findInstinctFile(
+  id: string,
+  projectId: string | null,
+  baseDir?: string
+): { path: string; scope: "project" | "global" } | null {
+  if (projectId) {
+    const projDir = getProjectInstinctsDir(projectId, "personal", baseDir);
+    const projPath = join(projDir, `${id}.md`);
+    if (existsSync(projPath)) return { path: projPath, scope: "project" };
+  }
+  const globalDir = getGlobalInstinctsDir("personal", baseDir);
+  const globalPath = join(globalDir, `${id}.md`);
+  if (existsSync(globalPath)) return { path: globalPath, scope: "global" };
+  return null;
+}
+
+function formatInstinct(i: Instinct): string {
+  return `[${i.confidence.toFixed(2)}] ${i.id} (${i.domain}, ${i.scope})\n  Trigger: ${i.trigger}\n  Action: ${i.action}`;
+}
+
+const ListParams = Type.Object({
+  scope: Type.Optional(StringEnum(["project", "global", "all"] as const)),
+  domain: Type.Optional(Type.String({ description: "Filter by domain (e.g. typescript, git, workflow)" })),
+});
+
+const ReadParams = Type.Object({
+  id: Type.String({ description: "Instinct ID (kebab-case)" }),
+});
+
+const WriteParams = Type.Object({
+  id: Type.String({ description: "Instinct ID (kebab-case)" }),
+  title: Type.String(),
+  trigger: Type.String({ description: "When this instinct should activate" }),
+  action: Type.String({ description: "What the agent should do" }),
+  confidence: Type.Number({ minimum: 0.1, maximum: 0.9 }),
+  domain: Type.String(),
+  scope: StringEnum(["project", "global"] as const),
+  observation_count: Type.Optional(Type.Number({ default: 1 })),
+  confirmed_count: Type.Optional(Type.Number({ default: 0 })),
+  contradicted_count: Type.Optional(Type.Number({ default: 0 })),
+  inactive_count: Type.Optional(Type.Number({ default: 0 })),
+  evidence: Type.Optional(Type.Array(Type.String())),
+});
+
+const DeleteParams = Type.Object({
+  id: Type.String({ description: "Instinct ID to delete" }),
+});
+
+const MergeParams = Type.Object({
+  merged: Type.Object({
+    id: Type.String(),
+    title: Type.String(),
+    trigger: Type.String(),
+    action: Type.String(),
+    confidence: Type.Number({ minimum: 0.1, maximum: 0.9 }),
+    domain: Type.String(),
+    scope: StringEnum(["project", "global"] as const),
+    evidence: Type.Optional(Type.Array(Type.String())),
+  }),
+  delete_ids: Type.Array(Type.String(), { description: "IDs of source instincts to remove after merge" }),
+});
+
+export type InstinctListInput = Static<typeof ListParams>;
+export type InstinctReadInput = Static<typeof ReadParams>;
+export type InstinctWriteInput = Static<typeof WriteParams>;
+export type InstinctDeleteInput = Static<typeof DeleteParams>;
+export type InstinctMergeInput = Static<typeof MergeParams>;
+
+export function createInstinctWriteTool(
+  projectId: string | null,
+  projectName: string | null,
+  baseDir?: string
+) {
+  return {
+    name: "instinct_write" as const,
+    label: "Write Instinct",
+    description: "Create or update a learned behavior instinct",
+    promptSnippet: "Create or update a learned behavior instinct (trigger + action pattern)",
+    parameters: WriteParams,
+    async execute(
+      _toolCallId: string,
+      params: InstinctWriteInput,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown
+    ) {
+      const dir = getInstinctsDir(params.scope, projectId, baseDir);
+      if (!dir) {
+        throw new Error("Cannot write project-scoped instinct: no project detected");
+      }
+
+      const now = new Date().toISOString();
+      const existing = findInstinctFile(params.id, projectId, baseDir);
+
+      const instinct: Instinct = {
+        id: params.id,
+        title: params.title,
+        trigger: params.trigger,
+        action: params.action,
+        confidence: params.confidence,
+        domain: params.domain,
+        source: "personal",
+        scope: params.scope,
+        ...(params.scope === "project" && projectId ? { project_id: projectId } : {}),
+        ...(params.scope === "project" && projectName ? { project_name: projectName } : {}),
+        created_at: existing ? loadInstinct(existing.path).created_at : now,
+        updated_at: now,
+        observation_count: params.observation_count ?? 1,
+        confirmed_count: params.confirmed_count ?? 0,
+        contradicted_count: params.contradicted_count ?? 0,
+        inactive_count: params.inactive_count ?? 0,
+        ...(params.evidence ? { evidence: params.evidence } : {}),
+      };
+
+      saveInstinct(instinct, dir);
+
+      return {
+        content: [{ type: "text" as const, text: `${existing ? "Updated" : "Created"} instinct: ${params.id}` }],
+        details: { id: params.id, action: existing ? "updated" : "created" },
+      };
+    },
+  };
+}
+
+export function createInstinctReadTool(
+  projectId: string | null,
+  baseDir?: string
+) {
+  return {
+    name: "instinct_read" as const,
+    label: "Read Instinct",
+    description: "Read a specific instinct by ID",
+    promptSnippet: "Read the full details of a specific learned instinct by ID",
+    parameters: ReadParams,
+    async execute(
+      _toolCallId: string,
+      params: InstinctReadInput,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown
+    ) {
+      const found = findInstinctFile(params.id, projectId, baseDir);
+      if (!found) {
+        throw new Error(`Instinct not found: ${params.id}`);
+      }
+      const instinct = loadInstinct(found.path);
+      return {
+        content: [{ type: "text" as const, text: formatInstinct(instinct) }],
+        details: instinct,
+      };
+    },
+  };
+}
+
+export function createInstinctListTool(
+  projectId: string | null,
+  baseDir?: string
+) {
+  return {
+    name: "instinct_list" as const,
+    label: "List Instincts",
+    description: "List learned behavior instincts with optional filters",
+    promptSnippet: "List all learned instincts, optionally filtered by scope or domain",
+    parameters: ListParams,
+    async execute(
+      _toolCallId: string,
+      params: InstinctListInput,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown
+    ) {
+      const scope = params.scope ?? "all";
+      let instincts: Instinct[] = [];
+
+      if ((scope === "project" || scope === "all") && projectId) {
+        instincts.push(...loadProjectInstincts(projectId, baseDir));
+      }
+      if (scope === "global" || scope === "all") {
+        instincts.push(...loadGlobalInstincts(baseDir));
+      }
+
+      if (params.domain) {
+        const domain = params.domain.toLowerCase();
+        instincts = instincts.filter((i) => i.domain.toLowerCase() === domain);
+      }
+
+      instincts.sort((a, b) => b.confidence - a.confidence);
+
+      if (instincts.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: "No instincts found matching the given filters." }],
+          details: { count: 0 },
+        };
+      }
+
+      const text = instincts.map(formatInstinct).join("\n\n");
+      return {
+        content: [{ type: "text" as const, text: `${instincts.length} instinct(s):\n\n${text}` }],
+        details: { count: instincts.length },
+      };
+    },
+  };
+}
+
+export function createInstinctDeleteTool(
+  projectId: string | null,
+  baseDir?: string
+) {
+  return {
+    name: "instinct_delete" as const,
+    label: "Delete Instinct",
+    description: "Remove a learned instinct by ID",
+    promptSnippet: "Delete a learned instinct permanently by ID",
+    parameters: DeleteParams,
+    async execute(
+      _toolCallId: string,
+      params: InstinctDeleteInput,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown
+    ) {
+      const found = findInstinctFile(params.id, projectId, baseDir);
+      if (!found) {
+        throw new Error(`Instinct not found: ${params.id}`);
+      }
+      unlinkSync(found.path);
+      return {
+        content: [{ type: "text" as const, text: `Deleted instinct: ${params.id} (was ${found.scope}-scoped)` }],
+        details: { id: params.id, scope: found.scope },
+      };
+    },
+  };
+}
+
+export function createInstinctMergeTool(
+  projectId: string | null,
+  projectName: string | null,
+  baseDir?: string
+) {
+  return {
+    name: "instinct_merge" as const,
+    label: "Merge Instincts",
+    description: "Merge multiple instincts into one, removing the originals",
+    promptSnippet: "Merge multiple related instincts into a single consolidated instinct",
+    parameters: MergeParams,
+    async execute(
+      _toolCallId: string,
+      params: InstinctMergeInput,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown
+    ) {
+      const { merged, delete_ids } = params;
+      const dir = getInstinctsDir(merged.scope, projectId, baseDir);
+      if (!dir) {
+        throw new Error("Cannot write project-scoped instinct: no project detected");
+      }
+
+      const now = new Date().toISOString();
+      const instinct: Instinct = {
+        ...merged,
+        source: "personal",
+        ...(merged.scope === "project" && projectId ? { project_id: projectId } : {}),
+        ...(merged.scope === "project" && projectName ? { project_name: projectName } : {}),
+        created_at: now,
+        updated_at: now,
+        observation_count: 0,
+        confirmed_count: 0,
+        contradicted_count: 0,
+        inactive_count: 0,
+        ...(merged.evidence ? { evidence: merged.evidence } : {}),
+      };
+
+      saveInstinct(instinct, dir);
+
+      const deleted: string[] = [];
+      for (const id of delete_ids) {
+        if (id === merged.id) continue;
+        const found = findInstinctFile(id, projectId, baseDir);
+        if (found) {
+          unlinkSync(found.path);
+          deleted.push(id);
+        }
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Merged into ${merged.id}. Deleted ${deleted.length} source instinct(s): ${deleted.join(", ")}`,
+        }],
+        details: { mergedId: merged.id, deleted },
+      };
+    },
+  };
+}
+
+export function registerAllTools(
+  pi: ExtensionAPI,
+  projectId: string | null,
+  projectName: string | null,
+  baseDir?: string
+): void {
+  const guidelines = [
+    "Use instinct tools when the user asks about learned behaviors, patterns, or instincts.",
+  ];
+
+  pi.registerTool({ ...createInstinctListTool(projectId, baseDir), promptGuidelines: guidelines });
+  pi.registerTool({ ...createInstinctReadTool(projectId, baseDir), promptGuidelines: guidelines });
+  pi.registerTool({ ...createInstinctWriteTool(projectId, projectName, baseDir), promptGuidelines: guidelines });
+  pi.registerTool({ ...createInstinctDeleteTool(projectId, baseDir), promptGuidelines: guidelines });
+  pi.registerTool({ ...createInstinctMergeTool(projectId, projectName, baseDir), promptGuidelines: guidelines });
+}

package/src/observations.ts

@@ -0,0 +1,82 @@
+/**
+ * JSONL observation file writing and archival.
+ * Appends observations to per-project observations.jsonl files,
+ * archives files at 10MB, and cleans up archives older than 30 days.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { Observation } from "./types.js";
+import { getArchiveDir, getObservationsPath } from "./storage.js";
+
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_ARCHIVE_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+function isFileSizeExceeded(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  return statSync(filePath).size >= MAX_FILE_SIZE_BYTES;
+}
+
+function archiveFile(observationsPath: string, archiveDir: string): void {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const archivePath = join(archiveDir, `${timestamp}.jsonl`);
+  renameSync(observationsPath, archivePath);
+}
+
+/**
+ * Appends one observation as a JSON line to the project's observations.jsonl.
+ * Automatically archives the file if it has grown to or beyond 10MB.
+ */
+export function appendObservation(
+  observation: Observation,
+  projectId: string,
+  baseDir?: string
+): void {
+  const observationsPath = getObservationsPath(projectId, baseDir);
+  const archiveDir = getArchiveDir(projectId, baseDir);
+
+  if (isFileSizeExceeded(observationsPath)) {
+    archiveFile(observationsPath, archiveDir);
+  }
+
+  appendFileSync(observationsPath, JSON.stringify(observation) + "\n", "utf-8");
+}
+
+/**
+ * Deletes archive files older than 30 days.
+ * Should be called once per session_start.
+ */
+/**
+ * Counts non-empty lines in the project's observations.jsonl file.
+ * Returns 0 when the file does not exist.
+ */
+export function countObservations(projectId: string, baseDir?: string): number {
+  const obsPath = getObservationsPath(projectId, baseDir);
+  if (!existsSync(obsPath)) return 0;
+  const content = readFileSync(obsPath, "utf-8") as string;
+  return content.split("\n").filter((line) => line.trim() !== "").length;
+}
+
+export function cleanOldArchives(projectId: string, baseDir?: string): void {
+  const archiveDir = getArchiveDir(projectId, baseDir);
+  if (!existsSync(archiveDir)) return;
+
+  const now = Date.now();
+  const files = readdirSync(archiveDir).filter((f) => f.endsWith(".jsonl"));
+
+  for (const file of files) {
+    const filePath = join(archiveDir, file);
+    const { mtimeMs } = statSync(filePath);
+    if (now - mtimeMs >= MAX_ARCHIVE_AGE_MS) {
+      unlinkSync(filePath);
+    }
+  }
+}

package/src/observer-guard.ts

@@ -0,0 +1,14 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LEARNING_BASE_DIR = join(homedir(), ".pi", "continuous-learning");
+const LEARNING_BASE_DIR_PREFIX = LEARNING_BASE_DIR + "/";
+
+export function shouldSkipPath(filePath: string): boolean {
+  return filePath === LEARNING_BASE_DIR || filePath.startsWith(LEARNING_BASE_DIR_PREFIX);
+}
+
+export function shouldSkipObservation(filePath?: string): boolean {
+  if (filePath !== undefined && shouldSkipPath(filePath)) return true;
+  return false;
+}

package/src/project.ts

@@ -0,0 +1,70 @@
+/**
+ * Project detection via git remote URL hashing.
+ * Scopes observations and instincts to the correct project.
+ */
+
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProjectEntry } from "./types.js";
+
+const GLOBAL_PROJECT_ID = "global";
+const HASH_LENGTH = 12;
+
+function hashString(input: string): string {
+  return createHash("sha256").update(input).digest("hex").substring(0, HASH_LENGTH);
+}
+
+/**
+ * Detect the current project by inspecting git remote URL.
+ *
+ * Resolution order:
+ *   1. git remote get-url origin  -> hash of remote URL
+ *   2. git rev-parse --show-toplevel -> hash of repo root path
+ *   3. fallback to project ID "global"
+ */
+export async function detectProject(
+  pi: ExtensionAPI,
+  cwd: string
+): Promise<ProjectEntry> {
+  const now = new Date().toISOString();
+  const name = basename(cwd);
+
+  // 1. Try remote URL
+  const remoteResult = await pi.exec("git", ["remote", "get-url", "origin"], { cwd });
+  if (remoteResult.code === 0) {
+    const remote = remoteResult.stdout.trim();
+    return {
+      id: hashString(remote),
+      name,
+      root: cwd,
+      remote,
+      created_at: now,
+      last_seen: now,
+    };
+  }
+
+  // 2. Fallback: repo root path (no remote)
+  const rootResult = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd });
+  if (rootResult.code === 0) {
+    const root = rootResult.stdout.trim();
+    return {
+      id: hashString(root),
+      name,
+      root,
+      remote: "",
+      created_at: now,
+      last_seen: now,
+    };
+  }
+
+  // 3. Fallback: not in a git repo
+  return {
+    id: GLOBAL_PROJECT_ID,
+    name,
+    root: cwd,
+    remote: "",
+    created_at: now,
+    last_seen: now,
+  };
+}