pi-continuous-learning 0.3.0

package/src/instinct-export.ts

@@ -0,0 +1,138 @@
+/**
+ * /instinct-export command for pi-continuous-learning.
+ * Exports instincts to a JSON file in the current directory.
+ * Optional args: scope (project|global) and domain filter.
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { Instinct, InstinctScope } from "./types.js";
+import { loadProjectInstincts, loadGlobalInstincts } from "./instinct-store.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const COMMAND_NAME = "instinct-export";
+const SCOPE_PROJECT: InstinctScope = "project";
+const SCOPE_GLOBAL: InstinctScope = "global";
+const VALID_SCOPES: readonly string[] = [SCOPE_PROJECT, SCOPE_GLOBAL];
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+export interface ExportArgs {
+  scope: InstinctScope | null;
+  domain: string | null;
+}
+
+/**
+ * Parses space-separated args string.
+ * If first token is "project" or "global", it is treated as scope filter.
+ * Remaining tokens (if any) are joined as domain filter.
+ */
+export function parseExportArgs(args: string): ExportArgs {
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return { scope: null, domain: null };
+  }
+
+  const first = tokens[0] ?? "";
+  const isScope = VALID_SCOPES.includes(first);
+
+  const scope = isScope ? (first as InstinctScope) : null;
+  const domainTokens = isScope ? tokens.slice(1) : tokens;
+  const domain = domainTokens.length > 0 ? domainTokens.join(" ") : null;
+
+  return { scope, domain };
+}
+
+// ---------------------------------------------------------------------------
+// Filtering
+// ---------------------------------------------------------------------------
+
+/**
+ * Filters instincts by optional scope and domain.
+ * Immutable - returns a new array.
+ */
+export function filterInstinctsForExport(
+  instincts: Instinct[],
+  scope: InstinctScope | null,
+  domain: string | null
+): Instinct[] {
+  return instincts.filter((instinct) => {
+    if (scope !== null && instinct.scope !== scope) return false;
+    if (domain !== null && instinct.domain !== domain) return false;
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Filename generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates an export filename with timestamp.
+ * Format: instincts-export-<YYYYMMDDTHHmmss>.json
+ */
+export function buildExportFilename(now: Date = new Date()): string {
+  const iso = now.toISOString(); // "2026-03-26T17:12:20.216Z"
+  // Compact: remove dashes, colons, milliseconds, and trailing Z
+  const compact = iso
+    .replace(/-/g, "")
+    .replace(/:/g, "")
+    .replace(/\.\d+Z$/, "");
+  return `instincts-export-${compact}.json`;
+}
+
+// ---------------------------------------------------------------------------
+// loadAllInstinctsForExport
+// ---------------------------------------------------------------------------
+
+/**
+ * Loads instincts from disk (project + global) for export.
+ * Does NOT apply confidence filtering - export includes everything.
+ */
+export function loadAllInstinctsForExport(
+  projectId?: string | null,
+  baseDir?: string
+): Instinct[] {
+  const projectInstincts =
+    projectId != null ? loadProjectInstincts(projectId, baseDir) : [];
+  const globalInstincts = loadGlobalInstincts(baseDir);
+  return [...projectInstincts, ...globalInstincts];
+}
+
+// ---------------------------------------------------------------------------
+// handleInstinctExport
+// ---------------------------------------------------------------------------
+
+/**
+ * Command handler for /instinct-export.
+ * Loads instincts, applies optional filters, writes JSON file to cwd.
+ */
+export async function handleInstinctExport(
+  args: string,
+  ctx: ExtensionCommandContext,
+  projectId?: string | null,
+  baseDir?: string
+): Promise<void> {
+  const { scope, domain } = parseExportArgs(args);
+
+  const all = loadAllInstinctsForExport(projectId, baseDir);
+  const filtered = filterInstinctsForExport(all, scope, domain);
+
+  const filename = buildExportFilename();
+  const outputPath = join(ctx.cwd, filename);
+
+  writeFileSync(outputPath, JSON.stringify(filtered, null, 2), "utf-8");
+
+  ctx.ui.notify(
+    `Exported ${filtered.length} instinct${filtered.length !== 1 ? "s" : ""} to ${outputPath}`,
+    "info"
+  );
+}
+
+export { COMMAND_NAME };

package/src/instinct-import.ts

@@ -0,0 +1,260 @@
+/**
+ * /instinct-import command for pi-continuous-learning.
+ * Imports instincts from a JSON file into the inherited instincts directory.
+ * Destination is determined by each instinct's scope field:
+ *   - scope "project" -> projects/<id>/instincts/inherited/
+ *   - scope "global"  -> instincts/inherited/
+ */
+
+import { readFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { Instinct } from "./types.js";
+import { saveInstinct, listInstincts } from "./instinct-store.js";
+import {
+  getProjectInstinctsDir,
+  getGlobalInstinctsDir,
+  getBaseDir,
+} from "./storage.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const COMMAND_NAME = "instinct-import";
+
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const REQUIRED_FIELDS = [
+  "id",
+  "title",
+  "trigger",
+  "action",
+  "confidence",
+  "domain",
+  "source",
+  "scope",
+  "created_at",
+  "updated_at",
+  "observation_count",
+  "confirmed_count",
+  "contradicted_count",
+  "inactive_count",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export interface ValidationError {
+  index: number;
+  reason: string;
+}
+
+/**
+ * Validates a raw JSON object as an Instinct.
+ * Returns an error string if invalid, null if valid.
+ */
+export function validateImportObject(
+  obj: unknown,
+  index: number
+): ValidationError | null {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return { index, reason: "not an object" };
+  }
+
+  const record = obj as Record<string, unknown>;
+
+  for (const field of REQUIRED_FIELDS) {
+    if (record[field] === undefined || record[field] === null) {
+      return { index, reason: `missing required field "${field}"` };
+    }
+  }
+
+  const id = String(record["id"]);
+  if (!KEBAB_RE.test(id)) {
+    return { index, reason: `invalid id "${id}" - must be kebab-case` };
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// File loading
+// ---------------------------------------------------------------------------
+
+export interface LoadResult {
+  valid: Instinct[];
+  invalid: ValidationError[];
+}
+
+/**
+ * Reads and parses the import JSON file.
+ * Returns valid instincts and validation errors separately.
+ */
+export function loadImportFile(filePath: string): LoadResult {
+  const content = readFileSync(filePath, "utf-8");
+  const parsed: unknown = JSON.parse(content);
+
+  if (!Array.isArray(parsed)) {
+    throw new Error("Import file must contain a JSON array of instinct objects.");
+  }
+
+  const valid: Instinct[] = [];
+  const invalid: ValidationError[] = [];
+
+  for (let i = 0; i < parsed.length; i++) {
+    const err = validateImportObject(parsed[i], i);
+    if (err) {
+      invalid.push(err);
+    } else {
+      valid.push(parsed[i] as Instinct);
+    }
+  }
+
+  return { valid, invalid };
+}
+
+// ---------------------------------------------------------------------------
+// Duplicate detection
+// ---------------------------------------------------------------------------
+
+export interface PartitionResult {
+  toImport: Instinct[];
+  duplicates: string[];
+}
+
+/**
+ * Partitions instincts into those to import and those skipped as duplicates.
+ * Checks existing inherited instincts in both project and global directories.
+ */
+export function partitionByDuplicates(
+  instincts: Instinct[],
+  projectId: string | null | undefined,
+  baseDir: string
+): PartitionResult {
+  const existingIds = new Set<string>();
+
+  const globalDir = getGlobalInstinctsDir("inherited", baseDir);
+  for (const inst of listInstincts(globalDir)) {
+    existingIds.add(inst.id);
+  }
+
+  if (projectId != null) {
+    const projectDir = getProjectInstinctsDir(projectId, "inherited", baseDir);
+    for (const inst of listInstincts(projectDir)) {
+      existingIds.add(inst.id);
+    }
+  }
+
+  const toImport: Instinct[] = [];
+  const duplicates: string[] = [];
+
+  for (const inst of instincts) {
+    if (existingIds.has(inst.id)) {
+      duplicates.push(inst.id);
+    } else {
+      toImport.push(inst);
+    }
+  }
+
+  return { toImport, duplicates };
+}
+
+// ---------------------------------------------------------------------------
+// Target directory resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the inherited instincts directory for the given instinct.
+ * Project-scoped instincts go into the project's inherited dir.
+ * Global instincts go into the global inherited dir.
+ */
+export function getTargetDir(
+  instinct: Instinct,
+  projectId: string | null | undefined,
+  baseDir: string
+): string {
+  if (instinct.scope === "project" && projectId != null) {
+    return getProjectInstinctsDir(projectId, "inherited", baseDir);
+  }
+  return getGlobalInstinctsDir("inherited", baseDir);
+}
+
+// ---------------------------------------------------------------------------
+// handleInstinctImport
+// ---------------------------------------------------------------------------
+
+/**
+ * Command handler for /instinct-import.
+ * Reads the JSON file at the given path, validates each instinct,
+ * skips duplicates, and saves valid instincts to inherited/ directories.
+ */
+export async function handleInstinctImport(
+  args: string,
+  ctx: ExtensionCommandContext,
+  projectId?: string | null,
+  baseDir?: string
+): Promise<void> {
+  const effectiveBase = baseDir ?? getBaseDir();
+  const filePath = resolve(ctx.cwd, args.trim());
+
+  if (!existsSync(filePath)) {
+    ctx.ui.notify(`Import failed: file not found: ${filePath}`, "error");
+    return;
+  }
+
+  let loadResult: LoadResult;
+  try {
+    loadResult = loadImportFile(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Import failed: ${msg}`, "error");
+    return;
+  }
+
+  const { valid, invalid } = loadResult;
+
+  const { toImport, duplicates } = partitionByDuplicates(
+    valid,
+    projectId,
+    effectiveBase
+  );
+
+  // Ensure target dirs exist before writing
+  const globalInheritedDir = getGlobalInstinctsDir("inherited", effectiveBase);
+  mkdirSync(globalInheritedDir, { recursive: true });
+
+  if (projectId != null) {
+    const projectInheritedDir = getProjectInstinctsDir(
+      projectId,
+      "inherited",
+      effectiveBase
+    );
+    mkdirSync(projectInheritedDir, { recursive: true });
+  }
+
+  // Save each instinct to the correct inherited directory
+  for (const instinct of toImport) {
+    const targetDir = getTargetDir(instinct, projectId, effectiveBase);
+    saveInstinct(instinct, targetDir);
+  }
+
+  // Build summary message
+  const lines: string[] = [
+    `Imported ${toImport.length} instinct${toImport.length !== 1 ? "s" : ""} from ${filePath}`,
+  ];
+
+  if (duplicates.length > 0) {
+    lines.push(
+      `Skipped ${duplicates.length} duplicate${duplicates.length !== 1 ? "s" : ""}: ${duplicates.join(", ")}`
+    );
+  }
+
+  if (invalid.length > 0) {
+    lines.push(
+      `Skipped ${invalid.length} invalid entr${invalid.length !== 1 ? "ies" : "y"}: ${invalid.map((e) => `[${e.index}] ${e.reason}`).join("; ")}`
+    );
+  }
+
+  ctx.ui.notify(lines.join("\n"), "info");
+}

package/src/instinct-injector.ts

@@ -0,0 +1,128 @@
+/**
+ * System prompt injection for pi-continuous-learning.
+ * Loads filtered instincts and appends them to the system prompt on each
+ * before_agent_start event so the agent benefits from learned behaviors.
+ * Also bridges injected instinct IDs to shared active-instincts state (US-023).
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { BeforeAgentStartEvent, AgentEndEvent } from "./prompt-observer.js";
+import type { Config, Instinct } from "./types.js";
+
+/** Subset of BeforeAgentStartEventResult used by this module. */
+export interface InjectionResult {
+  /** Replacement system prompt to use for this turn. */
+  systemPrompt?: string;
+}
+import { loadAndFilterFromConfig, inferDomains } from "./instinct-loader.js";
+import {
+  setCurrentActiveInstincts,
+  clearActiveInstincts,
+} from "./active-instincts.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const INSTINCTS_HEADER = "## Learned Behaviors (Instincts)";
+
+// ---------------------------------------------------------------------------
+// buildInjectionBlock
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the injection block string from a list of instincts.
+ * Returns null when the list is empty (no block needed).
+ */
+export function buildInjectionBlock(instincts: Instinct[], maxChars?: number): string | null {
+  if (instincts.length === 0) return null;
+
+  const headerLen = `\n\n${INSTINCTS_HEADER}\n`.length;
+  const allBullets: string[] = [];
+  let charCount = headerLen;
+  let omitted = 0;
+
+  for (const i of instincts) {
+    const bullet = `- [${i.confidence.toFixed(2)}] ${i.trigger}: ${i.action}`;
+    const bulletLen = bullet.length + 1; // +1 for newline
+
+    if (maxChars && charCount + bulletLen > maxChars) {
+      omitted = instincts.length - allBullets.length;
+      break;
+    }
+
+    allBullets.push(bullet);
+    charCount += bulletLen;
+  }
+
+  if (allBullets.length === 0) return null;
+
+  let result = `\n\n${INSTINCTS_HEADER}\n${allBullets.join("\n")}`;
+  if (omitted > 0) {
+    result += `\n(${omitted} lower-confidence instinct${omitted > 1 ? "s" : ""} omitted)`;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// injectInstincts (pure, for testing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a modified system prompt string with injected instincts,
+ * or null when no qualifying instincts were found.
+ * Pure function - no I/O.
+ */
+export function injectInstincts(
+  systemPrompt: string,
+  instincts: Instinct[]
+): string | null {
+  const block = buildInjectionBlock(instincts);
+  if (block === null) return null;
+  return systemPrompt + block;
+}
+
+// ---------------------------------------------------------------------------
+// handleBeforeAgentStartInjection
+// ---------------------------------------------------------------------------
+
+/**
+ * Handles before_agent_start events.
+ * Loads qualifying instincts, appends them to the system prompt, and stores
+ * their IDs in shared active-instincts state for observation tagging (US-023).
+ * Returns undefined when no instincts qualify (no-op).
+ */
+export function handleBeforeAgentStartInjection(
+  event: BeforeAgentStartEvent,
+  _ctx: ExtensionContext,
+  config: Config,
+  projectId?: string | null,
+  baseDir?: string
+): InjectionResult | void {
+  const relevantDomains = inferDomains(event.prompt);
+  const instincts = loadAndFilterFromConfig(config, projectId, baseDir, relevantDomains);
+
+  const block = buildInjectionBlock(instincts, config.max_injection_chars);
+  if (block === null) {
+    setCurrentActiveInstincts([]);
+    return undefined;
+  }
+
+  setCurrentActiveInstincts(instincts.map((i) => i.id));
+  return { systemPrompt: event.systemPrompt + block };
+}
+
+// ---------------------------------------------------------------------------
+// handleAgentEndClearInstincts
+// ---------------------------------------------------------------------------
+
+/**
+ * Handles agent_end events.
+ * Clears active instincts state so the next prompt starts clean (US-023).
+ */
+export function handleAgentEndClearInstincts(
+  _event: AgentEndEvent,
+  _ctx: ExtensionContext
+): void {
+  clearActiveInstincts();
+}

package/src/instinct-loader.ts

@@ -0,0 +1,146 @@
+/**
+ * Instinct loading and filtering for the injector.
+ * Loads project and global instincts, filters by confidence threshold,
+ * sorts by confidence descending, and caps to max_instincts.
+ */
+
+import type { Instinct, Config } from "./types.js";
+import { loadProjectInstincts, loadGlobalInstincts } from "./instinct-store.js";
+import { DEFAULT_CONFIG } from "./config.js";
+
+// ---------------------------------------------------------------------------
+// Domain inference
+// ---------------------------------------------------------------------------
+
+const UNIVERSAL_DOMAINS = new Set(["workflow", "git"]);
+
+const DOMAIN_KEYWORDS: Record<string, string[]> = {
+  typescript: ["typescript", ".ts", "type ", "interface ", "generic"],
+  css: ["css", "style", "tailwind", "classname", "scss", "sass"],
+  testing: ["test", "spec", "vitest", "jest", "coverage", "assert"],
+  git: ["git", "commit", "branch", "merge", "rebase", "stash"],
+  debugging: ["debug", "error", "stack trace", "exception", "breakpoint"],
+  performance: ["performance", "slow", "memory", "profil", "latency", "cache"],
+  security: ["security", "auth", "token", "secret", "csrf", "xss", "injection"],
+  documentation: ["documentation", "readme", "jsdoc", "docstring"],
+  design: ["component", "ui ", "layout", "responsive", "accessibility"],
+  workflow: ["workflow", "ci", "pipeline", "deploy", "automat"],
+};
+
+export function inferDomains(userPrompt: string): Set<string> {
+  const lower = userPrompt.toLowerCase();
+  const matched = new Set<string>();
+  for (const [domain, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
+    if (keywords.some((kw) => lower.includes(kw))) {
+      matched.add(domain);
+    }
+  }
+  return matched;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface LoadInstinctsOptions {
+  /** Project ID, or undefined/null when running outside a project. */
+  projectId?: string | null;
+  /** Minimum confidence threshold (default: DEFAULT_CONFIG.min_confidence). */
+  minConfidence?: number;
+  /** Maximum number of instincts to return (default: DEFAULT_CONFIG.max_instincts). */
+  maxInstincts?: number;
+  /** Optional base directory for storage (used in tests). */
+  baseDir?: string;
+  /** Domains relevant to the current context — matched instincts sort first. */
+  relevantDomains?: Set<string>;
+}
+
+// ---------------------------------------------------------------------------
+// filterInstincts
+// ---------------------------------------------------------------------------
+
+/**
+ * Filters, sorts, and caps a flat list of instincts.
+ * Pure function - no I/O.
+ */
+export function filterInstincts(
+  instincts: Instinct[],
+  minConfidence: number,
+  maxInstincts: number,
+  relevantDomains?: Set<string>
+): Instinct[] {
+  const eligible = instincts.filter(
+    (i) => !i.flagged_for_removal && i.confidence >= minConfidence
+  );
+
+  const sorted = [...eligible].sort((a, b) => {
+    // When relevantDomains are provided, prioritize domain-matched instincts
+    if (relevantDomains && relevantDomains.size > 0) {
+      const aRelevant = relevantDomains.has(a.domain) || UNIVERSAL_DOMAINS.has(a.domain);
+      const bRelevant = relevantDomains.has(b.domain) || UNIVERSAL_DOMAINS.has(b.domain);
+      if (aRelevant && !bRelevant) return -1;
+      if (!aRelevant && bRelevant) return 1;
+    }
+    return b.confidence - a.confidence;
+  });
+
+  return sorted.slice(0, maxInstincts);
+}
+
+// ---------------------------------------------------------------------------
+// loadAndFilterInstincts
+// ---------------------------------------------------------------------------
+
+/**
+ * Loads instincts from disk, filters by confidence threshold, sorts by
+ * confidence descending, and caps to max_instincts.
+ *
+ * When projectId is provided (and non-null), loads both project-scoped
+ * instincts and global instincts. Otherwise loads only global instincts.
+ */
+export function loadAndFilterInstincts(
+  options: LoadInstinctsOptions = {}
+): Instinct[] {
+  const {
+    projectId,
+    minConfidence = DEFAULT_CONFIG.min_confidence,
+    maxInstincts = DEFAULT_CONFIG.max_instincts,
+    baseDir,
+    relevantDomains,
+  } = options;
+
+  const projectInstincts =
+    projectId != null
+      ? loadProjectInstincts(projectId, baseDir)
+      : [];
+
+  const globalInstincts = loadGlobalInstincts(baseDir);
+
+  // Combine: project instincts first, then global (project-scoped are more specific)
+  const all = [...projectInstincts, ...globalInstincts];
+
+  return filterInstincts(all, minConfidence, maxInstincts, relevantDomains);
+}
+
+// ---------------------------------------------------------------------------
+// loadAndFilterFromConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience wrapper - uses thresholds from a Config object.
+ */
+export function loadAndFilterFromConfig(
+  config: Config,
+  projectId?: string | null,
+  baseDir?: string,
+  relevantDomains?: Set<string>
+): Instinct[] {
+  const opts: LoadInstinctsOptions = {
+    minConfidence: config.min_confidence,
+    maxInstincts: config.max_instincts,
+  };
+  if (projectId !== undefined) opts.projectId = projectId;
+  if (baseDir !== undefined) opts.baseDir = baseDir;
+  if (relevantDomains !== undefined) opts.relevantDomains = relevantDomains;
+  return loadAndFilterInstincts(opts);
+}