wispy-cli 2.7.10 → 2.7.11

package/bin/wispy.mjs

@@ -51,6 +51,9 @@ Usage:
   wispy doctor                 Check system health
   wispy browser [tabs|attach|navigate|screenshot|doctor]
                                Browser control via local-browser-bridge
+  wispy secrets [list|set|delete|get]
+                               Manage encrypted secrets & API keys
+  wispy tts "<text>"           Text-to-speech (OpenAI or macOS say)
   wispy trust [level|log]      Security level & audit
   wispy ws [start-client|run-debug]
                                WebSocket operations
@@ -338,6 +341,133 @@ if (command === "browser") {
   process.exit(0);
 }
 
+// ── Secrets ───────────────────────────────────────────────────────────────────
+
+if (command === "secrets") {
+  try {
+    const { SecretsManager } = await import(join(rootDir, "core/secrets.mjs"));
+    const sm = new SecretsManager();
+    const sub = args[1];
+
+    if (!sub || sub === "list") {
+      const keys = await sm.list();
+      if (keys.length === 0) {
+        console.log("No secrets stored. Use: wispy secrets set <key> <value>");
+      } else {
+        console.log(`\n  Stored secrets (${keys.length}):\n`);
+        for (const k of keys) {
+          console.log(`    ${k}`);
+        }
+        console.log("");
+      }
+    } else if (sub === "set") {
+      const key = args[2];
+      const value = args[3];
+      if (!key || value === undefined) {
+        console.error("Usage: wispy secrets set <key> <value>");
+        process.exit(1);
+      }
+      await sm.set(key, value);
+      console.log(`Secret '${key}' stored (encrypted).`);
+    } else if (sub === "delete") {
+      const key = args[2];
+      if (!key) {
+        console.error("Usage: wispy secrets delete <key>");
+        process.exit(1);
+      }
+      const result = await sm.delete(key);
+      if (result.success) {
+        console.log(`Secret '${key}' deleted.`);
+      } else {
+        console.error(`Secret '${key}' not found.`);
+        process.exit(1);
+      }
+    } else if (sub === "get") {
+      const key = args[2];
+      if (!key) {
+        console.error("Usage: wispy secrets get <key>");
+        process.exit(1);
+      }
+      const value = await sm.resolve(key);
+      if (value) {
+        console.log(`${key} = ***`);
+        console.log("(Use --reveal flag to show value — not recommended)");
+        if (args.includes("--reveal")) {
+          console.log(`Value: ${value}`);
+        }
+      } else {
+        console.log(`Secret '${key}' not found.`);
+      }
+    } else {
+      console.error(`Unknown secrets subcommand: ${sub}`);
+      console.log("Available: list, set <key> <value>, delete <key>, get <key>");
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error("Secrets error:", err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── TTS ───────────────────────────────────────────────────────────────────────
+
+if (command === "tts") {
+  try {
+    const { SecretsManager } = await import(join(rootDir, "core/secrets.mjs"));
+    const { TTSManager } = await import(join(rootDir, "core/tts.mjs"));
+
+    const sm = new SecretsManager();
+    const tts = new TTSManager(sm);
+
+    // Parse args: wispy tts "text" [--voice name] [--provider openai|macos] [--play]
+    let textArg = args[1];
+    if (!textArg) {
+      console.error('Usage: wispy tts "text to speak" [--voice <name>] [--provider openai|macos] [--play]');
+      process.exit(1);
+    }
+
+    const voiceIdx = args.indexOf("--voice");
+    const providerIdx = args.indexOf("--provider");
+    const shouldPlay = args.includes("--play");
+
+    const voice = voiceIdx !== -1 ? args[voiceIdx + 1] : undefined;
+    const provider = providerIdx !== -1 ? args[providerIdx + 1] : "auto";
+
+    console.log(`  Generating speech (provider: ${provider})...`);
+    const result = await tts.speak(textArg, { voice, provider });
+
+    if (result.error) {
+      console.error(`  TTS Error: ${result.error}`);
+      process.exit(1);
+    }
+
+    console.log(`  Provider: ${result.provider}`);
+    console.log(`  Voice:    ${result.voice}`);
+    console.log(`  Format:   ${result.format}`);
+    console.log(`  File:     ${result.path}`);
+
+    if (shouldPlay) {
+      const { execFile } = await import("node:child_process");
+      const { promisify } = await import("node:util");
+      const exec = promisify(execFile);
+      try {
+        if (process.platform === "darwin") {
+          await exec("afplay", [result.path]);
+        } else {
+          console.log('  Use --play flag only on macOS. Play manually with your audio player.');
+        }
+      } catch (playErr) {
+        console.error(`  Playback failed: ${playErr.message}`);
+      }
+    }
+  } catch (err) {
+    console.error("TTS error:", err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 // ── Trust ─────────────────────────────────────────────────────────────────────
 
 if (command === "trust") {

package/core/config.mjs

@@ -193,17 +193,35 @@ export async function detectProvider() {
     }
   }
 
-  // 4. macOS Keychain
-  const keychainMap = [
-    ["google-ai-key", "google"],
-    ["anthropic-api-key", "anthropic"],
-    ["openai-api-key", "openai"],
-  ];
-  for (const [service, provider] of keychainMap) {
-    const key = await tryKeychainKey(service);
-    if (key) {
-      process.env[PROVIDERS[provider].envKeys[0]] = key;
-      return { provider, key, model: process.env.WISPY_MODEL ?? PROVIDERS[provider].defaultModel };
+  // 4. macOS Keychain (via SecretsManager for unified resolution)
+  try {
+    const { getSecretsManager } = await import("./secrets.mjs");
+    const sm = getSecretsManager({ wispyDir: WISPY_DIR });
+    const keychainProviderMap = [
+      ["GOOGLE_AI_KEY", "google"],
+      ["ANTHROPIC_API_KEY", "anthropic"],
+      ["OPENAI_API_KEY", "openai"],
+    ];
+    for (const [envKey, provider] of keychainProviderMap) {
+      const key = await sm.resolve(envKey);
+      if (key) {
+        process.env[PROVIDERS[provider].envKeys[0]] = key;
+        return { provider, key, model: process.env.WISPY_MODEL ?? PROVIDERS[provider].defaultModel };
+      }
+    }
+  } catch {
+    // SecretsManager unavailable — fallback to legacy Keychain
+    const keychainMap = [
+      ["google-ai-key", "google"],
+      ["anthropic-api-key", "anthropic"],
+      ["openai-api-key", "openai"],
+    ];
+    for (const [service, provider] of keychainMap) {
+      const key = await tryKeychainKey(service);
+      if (key) {
+        process.env[PROVIDERS[provider].envKeys[0]] = key;
+        return { provider, key, model: process.env.WISPY_MODEL ?? PROVIDERS[provider].defaultModel };
+      }
     }
   }
 

package/core/features.mjs

@@ -0,0 +1,225 @@
+/**
+ * core/features.mjs — Feature flag system for Wispy
+ *
+ * Provides a registry of feature flags with stages (stable/experimental/development)
+ * and methods to enable/disable features, persisting state to config.
+ */
+
+import path from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { WISPY_DIR, CONFIG_PATH, loadConfig, saveConfig } from "./config.mjs";
+
+/**
+ * Registry of all known features.
+ * @type {Record<string, { stage: "stable"|"experimental"|"development", default: boolean, description: string }>}
+ */
+const FEATURE_REGISTRY = {
+  // ── Stable features ──────────────────────────────────────────────────────
+  smart_routing: {
+    stage: "stable",
+    default: true,
+    description: "Route tasks to optimal models",
+  },
+  task_decomposition: {
+    stage: "stable",
+    default: true,
+    description: "Split complex tasks into parallel subtasks",
+  },
+  loop_detection: {
+    stage: "stable",
+    default: true,
+    description: "Detect and break tool-call loops",
+  },
+  context_compaction: {
+    stage: "stable",
+    default: true,
+    description: "Auto-compact context when approaching token limit",
+  },
+
+  // ── Experimental features ────────────────────────────────────────────────
+  browser_integration: {
+    stage: "experimental",
+    default: false,
+    description: "Native browser control via local-browser-bridge",
+  },
+  auto_memory: {
+    stage: "experimental",
+    default: false,
+    description: "Auto-extract facts from conversations to memory",
+  },
+  tts: {
+    stage: "experimental",
+    default: false,
+    description: "Text-to-speech output",
+  },
+
+  // ── Under development ────────────────────────────────────────────────────
+  multi_agent: {
+    stage: "development",
+    default: false,
+    description: "Multi-agent orchestration patterns",
+  },
+  cloud_sync: {
+    stage: "development",
+    default: false,
+    description: "Sync sessions to cloud",
+  },
+  image_generation: {
+    stage: "development",
+    default: false,
+    description: "Generate images from prompts",
+  },
+};
+
+export class FeatureManager {
+  /**
+   * @param {string} [configPath] - Path to config.json (defaults to ~/.wispy/config.json)
+   */
+  constructor(configPath) {
+    this._configPath = configPath ?? CONFIG_PATH;
+    /** @type {Record<string, boolean>} — cached overrides from config */
+    this._overrides = null;
+  }
+
+  /**
+   * Load feature overrides from config (lazy, cached per call).
+   * @returns {Promise<Record<string, boolean>>}
+   */
+  async _loadOverrides() {
+    if (this._overrides !== null) return this._overrides;
+    try {
+      const raw = await readFile(this._configPath, "utf8");
+      const cfg = JSON.parse(raw);
+      this._overrides = cfg.features ?? {};
+    } catch {
+      this._overrides = {};
+    }
+    return this._overrides;
+  }
+
+  /** Invalidate the cache so next read picks up fresh config. */
+  _invalidate() {
+    this._overrides = null;
+  }
+
+  /**
+   * Check if a feature is enabled.
+   * Config override takes precedence over registry default.
+   * Profile-level features (passed in opts) take precedence over global config.
+   * @param {string} name
+   * @param {Record<string, boolean>} [profileFeatures] - Profile-level overrides
+   * @returns {Promise<boolean>}
+   */
+  async isEnabled(name, profileFeatures = {}) {
+    const reg = FEATURE_REGISTRY[name];
+    if (!reg) return false; // Unknown features are disabled
+
+    // Profile override first
+    if (name in profileFeatures) return Boolean(profileFeatures[name]);
+
+    // Config override second
+    const overrides = await this._loadOverrides();
+    if (name in overrides) return Boolean(overrides[name]);
+
+    // Registry default
+    return reg.default;
+  }
+
+  /**
+   * Synchronous isEnabled using pre-loaded overrides.
+   * Call _loadOverrides() first if needed.
+   * @param {string} name
+   * @param {Record<string, boolean>} [overrides]
+   * @param {Record<string, boolean>} [profileFeatures]
+   * @returns {boolean}
+   */
+  isEnabledSync(name, overrides = {}, profileFeatures = {}) {
+    const reg = FEATURE_REGISTRY[name];
+    if (!reg) return false;
+    if (name in profileFeatures) return Boolean(profileFeatures[name]);
+    if (name in overrides) return Boolean(overrides[name]);
+    return reg.default;
+  }
+
+  /**
+   * Enable a feature and persist to config.
+   * @param {string} name
+   */
+  async enable(name) {
+    if (!FEATURE_REGISTRY[name]) {
+      throw new Error(`Unknown feature: "${name}". Use "wispy features" to see available features.`);
+    }
+    const raw = await this._readConfig();
+    if (!raw.features) raw.features = {};
+    raw.features[name] = true;
+    await this._writeConfig(raw);
+    this._invalidate();
+    return { success: true, name, enabled: true };
+  }
+
+  /**
+   * Disable a feature and persist to config.
+   * @param {string} name
+   */
+  async disable(name) {
+    if (!FEATURE_REGISTRY[name]) {
+      throw new Error(`Unknown feature: "${name}". Use "wispy features" to see available features.`);
+    }
+    const raw = await this._readConfig();
+    if (!raw.features) raw.features = {};
+    raw.features[name] = false;
+    await this._writeConfig(raw);
+    this._invalidate();
+    return { success: true, name, enabled: false };
+  }
+
+  /**
+   * List all features with their current status.
+   * @returns {Promise<Array<{ name: string, stage: string, enabled: boolean, default: boolean, description: string }>>}
+   */
+  async list() {
+    const overrides = await this._loadOverrides();
+    return Object.entries(FEATURE_REGISTRY).map(([name, meta]) => ({
+      name,
+      stage: meta.stage,
+      enabled: name in overrides ? Boolean(overrides[name]) : meta.default,
+      default: meta.default,
+      description: meta.description,
+    }));
+  }
+
+  /**
+   * Get the stage of a feature.
+   * @param {string} name
+   * @returns {"stable"|"experimental"|"development"|null}
+   */
+  getStage(name) {
+    return FEATURE_REGISTRY[name]?.stage ?? null;
+  }
+
+  async _readConfig() {
+    await mkdir(WISPY_DIR, { recursive: true });
+    try {
+      return JSON.parse(await readFile(this._configPath, "utf8"));
+    } catch {
+      return {};
+    }
+  }
+
+  async _writeConfig(cfg) {
+    await mkdir(WISPY_DIR, { recursive: true });
+    await writeFile(this._configPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+  }
+}
+
+/** Singleton instance */
+let _instance = null;
+
+/** Get or create the global FeatureManager instance. */
+export function getFeatureManager(configPath) {
+  if (!_instance) _instance = new FeatureManager(configPath);
+  return _instance;
+}
+
+/** Export the registry for introspection. */
+export { FEATURE_REGISTRY };

package/core/loop-detector.mjs

@@ -0,0 +1,183 @@
+/**
+ * core/loop-detector.mjs — Tool-call loop detection for Wispy
+ *
+ * Detects four patterns:
+ *   1. Exact repeat: same tool + same args hash 3+ times in window
+ *   2. Oscillation: A→B→A→B pattern (alternating between two calls)
+ *   3. No progress: 5+ tool calls where result hash doesn't change
+ *   4. Error loop: same tool fails 3+ times in a row
+ *
+ * v1.0.0
+ */
+
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+
+/**
+ * Compute a short hash of any value.
+ */
+function hashValue(value) {
+  if (value === null || value === undefined) return "null";
+  let str;
+  try {
+    str = JSON.stringify(value);
+  } catch {
+    str = String(value);
+  }
+  return createHash("sha1").update(str).digest("hex").slice(0, 16);
+}
+
+export class LoopDetector extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {number} options.windowSize  - Look at last N calls (default 10)
+   * @param {number} options.maxRepeats  - Same call N times = loop (default 3)
+   * @param {number} options.maxNoProgress - N calls with no new output = stuck (default 5)
+   */
+  constructor(options = {}) {
+    super();
+    this.windowSize = options.windowSize ?? 10;
+    this.maxRepeats = options.maxRepeats ?? 3;
+    this.maxNoProgress = options.maxNoProgress ?? 5;
+
+    // Array of { tool, argsHash, resultHash, isError, timestamp }
+    this._history = [];
+
+    // How many warnings have been emitted (to decide force-break)
+    this._warningCount = 0;
+  }
+
+  /**
+   * Record a tool call result.
+   * @param {string} toolName
+   * @param {object} args
+   * @param {any} result  - The result (or Error/string on failure)
+   */
+  record(toolName, args, result) {
+    const argsHash = hashValue(args);
+    const isError = (result && typeof result === "object" && result.success === false)
+      || (result instanceof Error);
+
+    // Use error message as result hash if error, so errors are deduplicated
+    const resultForHash = isError
+      ? (result?.error ?? result?.message ?? "error")
+      : result;
+
+    const resultHash = hashValue(resultForHash);
+
+    this._history.push({
+      tool: toolName,
+      argsHash,
+      resultHash,
+      isError,
+      timestamp: Date.now(),
+    });
+
+    // Keep only the window
+    if (this._history.length > this.windowSize) {
+      this._history = this._history.slice(-this.windowSize);
+    }
+  }
+
+  /**
+   * Check if the agent is in a loop.
+   * @returns {{ looping: boolean, reason?: string, suggestion?: string, warningCount: number }}
+   */
+  check() {
+    const history = this._history;
+    if (history.length < 2) return { looping: false, warningCount: this._warningCount };
+
+    // ── 1. Exact repeat: same tool + same args hash N+ times in window ────────
+    const callKey = (e) => `${e.tool}:${e.argsHash}`;
+    const counts = new Map();
+    for (const entry of history) {
+      const key = callKey(entry);
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    for (const [key, count] of counts) {
+      if (count >= this.maxRepeats) {
+        const [tool] = key.split(":");
+        this._warningCount++;
+        return {
+          looping: true,
+          reason: `exact_repeat`,
+          tool,
+          count,
+          warningCount: this._warningCount,
+          suggestion: `Loop detected: you've called ${tool} with the same arguments ${count} times. Try a different approach or verify the outcome before retrying.`,
+        };
+      }
+    }
+
+    // ── 2. Oscillation: A→B→A→B pattern ─────────────────────────────────────
+    if (history.length >= 4) {
+      const last4 = history.slice(-4).map(callKey);
+      // A→B→A→B
+      if (last4[0] === last4[2] && last4[1] === last4[3] && last4[0] !== last4[1]) {
+        const toolA = history[history.length - 4].tool;
+        const toolB = history[history.length - 3].tool;
+        this._warningCount++;
+        return {
+          looping: true,
+          reason: `oscillation`,
+          tool: `${toolA}↔${toolB}`,
+          warningCount: this._warningCount,
+          suggestion: `Loop detected: oscillating between ${toolA} and ${toolB}. These calls aren't making progress. Try a different strategy.`,
+        };
+      }
+    }
+
+    // ── 3. No progress: N consecutive calls with identical result hash ────────
+    if (history.length >= this.maxNoProgress) {
+      const recent = history.slice(-this.maxNoProgress);
+      const firstHash = recent[0].resultHash;
+      // All results are the same AND none are "null" (null = tool produced nothing)
+      if (firstHash !== "null" && recent.every(e => e.resultHash === firstHash)) {
+        const tool = recent[recent.length - 1].tool;
+        this._warningCount++;
+        return {
+          looping: true,
+          reason: `no_progress`,
+          tool,
+          count: this.maxNoProgress,
+          warningCount: this._warningCount,
+          suggestion: `Loop detected: ${this.maxNoProgress} consecutive tool calls produced identical results. The agent appears to be stuck — try a different approach.`,
+        };
+      }
+    }
+
+    // ── 4. Error loop: same tool fails 3+ times in a row ─────────────────────
+    if (history.length >= 3) {
+      const recent = history.slice(-3);
+      if (recent.every(e => e.isError && e.tool === recent[0].tool)) {
+        const tool = recent[0].tool;
+        this._warningCount++;
+        return {
+          looping: true,
+          reason: `error_loop`,
+          tool,
+          count: 3,
+          warningCount: this._warningCount,
+          suggestion: `Loop detected: ${tool} has failed 3 times in a row. Stop retrying and try a different approach or report the error.`,
+        };
+      }
+    }
+
+    return { looping: false, warningCount: this._warningCount };
+  }
+
+  /**
+   * Reset the detector state (e.g., after user intervention or successful progress).
+   */
+  reset() {
+    this._history = [];
+    this._warningCount = 0;
+  }
+
+  /**
+   * Returns the number of recorded entries.
+   */
+  get size() {
+    return this._history.length;
+  }
+}

package/core/memory.mjs

@@ -293,4 +293,247 @@ ${recentUserMsgs.slice(0, 2000)}`;
       return null;
     }
   }
+
+  // ── v2.8 Enhanced Memory Methods ────────────────────────────────────────────
+
+  /**
+   * Get top N most relevant memories for a given user message.
+   * Uses keyword matching + recency scoring + frequency weighting.
+   *
+   * @param {string} userMessage
+   * @param {number} limit - max memories to return (default 3)
+   * @returns {Promise<string|null>} formatted system message injection or null
+   */
+  async getRelevantMemories(userMessage, limit = 3) {
+    if (!userMessage?.trim()) return null;
+
+    try {
+      await this._ensureDir();
+      const terms = this._extractKeywords(userMessage);
+      if (terms.length === 0) return null;
+
+      // Collect all memory files with metadata
+      const allKeys = await this.list();
+      if (allKeys.length === 0) return null;
+
+      const scored = [];
+      const now = Date.now();
+
+      for (const item of allKeys) {
+        const content = await readFile(item.path, "utf8").catch(() => "");
+        if (!content.trim()) continue;
+
+        // 1. Keyword match score
+        const lower = content.toLowerCase();
+        let matchScore = 0;
+        for (const term of terms) {
+          // Count occurrences for stronger weighting
+          const regex = new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+          const matches = (lower.match(regex) ?? []).length;
+          matchScore += matches;
+        }
+        if (matchScore === 0) continue;
+
+        // 2. Recency score (0–1, decays over 30 days)
+        const ageDays = item.updatedAt
+          ? (now - new Date(item.updatedAt).getTime()) / (1000 * 60 * 60 * 24)
+          : 30;
+        const recencyScore = Math.max(0, 1 - ageDays / 30);
+
+        // 3. Frequency score (often-accessed memories rank higher)
+        const freq = this._accessFrequency.get(item.key) ?? 0;
+        const freqScore = Math.min(freq / 10, 1); // cap at 10 accesses = 1.0
+
+        // Combined score
+        const totalScore = matchScore * 2 + recencyScore * 1.5 + freqScore;
+
+        scored.push({ key: item.key, content, score: totalScore });
+      }
+
+      if (scored.length === 0) return null;
+
+      // Sort by score descending, take top N
+      scored.sort((a, b) => b.score - a.score);
+      const top = scored.slice(0, limit);
+
+      // Format as system message injection
+      const parts = top.map(m => {
+        const snippet = m.content.trim().slice(0, 500);
+        return `### memory:${m.key}\n${snippet}`;
+      });
+
+      return parts.join("\n\n");
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Auto-extract important facts from conversation and save to memory.
+   * Triggered every AUTO_EXTRACT_INTERVAL messages.
+   *
+   * @param {Array<{role,content}>} messages - conversation history
+   * @param {Function} aiCall - async (prompt) => string
+   * @returns {Promise<string|null>} extracted facts or null
+   */
+  async autoExtractFacts(messages, aiCall) {
+    if (!messages?.length || !aiCall) return null;
+
+    // Only run every N messages to avoid excessive AI calls
+    const userMsgs = messages.filter(m => m.role === "user");
+    if (userMsgs.length % AUTO_EXTRACT_INTERVAL !== 0) return null;
+
+    const recentMsgs = messages.slice(-AUTO_EXTRACT_INTERVAL * 2);
+    const conversationText = recentMsgs
+      .map(m => `${m.role === "user" ? "User" : "Assistant"}: ${
+        typeof m.content === "string" ? m.content : JSON.stringify(m.content)
+      }`)
+      .join("\n\n");
+
+    if (!conversationText.trim()) return null;
+
+    try {
+      const prompt = `Analyze this conversation and extract key facts, preferences, or important information worth remembering for future sessions. Be specific and concise. Format as bullet points. If nothing important, reply "nothing".
+
+Conversation:
+${conversationText.slice(0, 3000)}
+
+Examples of things to extract:
+- User preferences (tools, languages, styles)
+- Project names and goals  
+- Personal context (name, location, role)
+- Decisions made
+- Important deadlines or dates`;
+
+      const result = await aiCall(prompt);
+      if (!result || result.toLowerCase().trim() === "nothing") return null;
+
+      const today = new Date().toISOString().slice(0, 10);
+
+      // Deduplicate: check if very similar content already exists
+      const existingDaily = await this.get(`daily/${today}`);
+      if (existingDaily?.content?.includes(result.slice(0, 50))) return null;
+
+      await this.append(`daily/${today}`, result.slice(0, 800));
+      return result;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Fuzzy search across all memory files.
+   * Extends base search() with recency and frequency weighting.
+   *
+   * @param {string} query
+   * @param {object} opts
+   * @param {number} [opts.limit]
+   * @param {boolean} [opts.fuzzy] - enable fuzzy matching (default true)
+   * @returns {Promise<Array>}
+   */
+  async searchEnhanced(query, opts = {}) {
+    if (!query?.trim()) return [];
+    await this._ensureDir();
+
+    const terms = this._extractKeywords(query);
+    if (terms.length === 0) return [];
+
+    const results = [];
+    await this._searchDirEnhanced(this.memoryDir, this.memoryDir, terms, results, opts.fuzzy !== false);
+
+    const now = Date.now();
+
+    // Apply recency and frequency weighting to results
+    for (const r of results) {
+      try {
+        const fileStat = await stat(r.path).catch(() => null);
+        const ageDays = fileStat?.mtime
+          ? (now - fileStat.mtime.getTime()) / (1000 * 60 * 60 * 24)
+          : 30;
+        const recencyBonus = Math.max(0, 1 - ageDays / 30) * 2;
+        const freqBonus = Math.min((this._accessFrequency.get(r.key) ?? 0) / 5, 1);
+        r.matchCount = r.matchCount + recencyBonus + freqBonus;
+      } catch { /* ignore stat errors */ }
+    }
+
+    results.sort((a, b) => b.matchCount - a.matchCount);
+    return results.slice(0, opts.limit ?? MAX_SEARCH_RESULTS);
+  }
+
+  async _searchDirEnhanced(baseDir, dir, terms, results, fuzzy = true) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this._searchDirEnhanced(baseDir, fullPath, terms, results, fuzzy);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const content = await readFile(fullPath, "utf8").catch(() => "");
+        const lines = content.split("\n");
+        const key = path.relative(baseDir, fullPath).replace(/\.md$/, "");
+
+        let matchCount = 0;
+        const matchingLines = [];
+
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          const lower = line.toLowerCase();
+
+          let lineMatches = terms.filter(t => lower.includes(t)).length;
+
+          // Fuzzy: also check for partial matches (e.g. "proj" matches "project")
+          if (fuzzy && lineMatches === 0) {
+            lineMatches = terms.filter(t =>
+              t.length >= 4 && lower.split(/\s+/).some(word => word.startsWith(t.slice(0, -1)))
+            ).length * 0.5; // partial credit
+          }
+
+          if (lineMatches > 0) {
+            matchCount += lineMatches;
+            matchingLines.push({
+              lineNumber: i + 1,
+              text: line.slice(0, MAX_SNIPPET_CHARS),
+            });
+          }
+        }
+
+        if (matchCount > 0) {
+          results.push({
+            key,
+            path: fullPath,
+            matchCount,
+            snippets: matchingLines.slice(0, 5),
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract meaningful keywords from a string for search/scoring.
+   * Filters out common stop words.
+   */
+  _extractKeywords(text) {
+    const STOP_WORDS = new Set([
+      "the", "a", "an", "is", "are", "was", "were", "be", "been",
+      "have", "has", "had", "do", "does", "did", "will", "would",
+      "could", "should", "may", "might", "can", "shall",
+      "i", "you", "he", "she", "it", "we", "they", "me", "him", "her",
+      "us", "them", "my", "your", "his", "its", "our", "their",
+      "this", "that", "these", "those", "what", "which", "who",
+      "how", "when", "where", "why", "and", "or", "but", "not",
+      "in", "on", "at", "to", "for", "of", "with", "by", "from",
+      "up", "out", "as", "if", "then", "than", "so", "just",
+    ]);
+
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter(w => w.length >= 3 && !STOP_WORDS.has(w));
+  }
 }

package/core/secrets.mjs

@@ -44,15 +44,15 @@ export class SecretsManager {
   async resolve(key) {
     if (!key) return null;
 
-    // 1. In-memory cache
-    if (this._cache.has(key)) return this._cache.get(key);
-
-    // 2. Environment variable
+    // 1. Environment variable (always takes priority — can be overridden at runtime)
     if (process.env[key]) {
       this._cache.set(key, process.env[key]);
       return process.env[key];
     }
 
+    // 2. In-memory cache (from previous keychain/secrets.json lookup)
+    if (this._cache.has(key)) return this._cache.get(key);
+
     // 3. macOS Keychain — try common service name patterns
     const keychainValue = await this._fromKeychain(key, null);
     if (keychainValue) {

package/core/session.mjs

@@ -5,6 +5,9 @@
  *   - create({ workstream?, channel?, chatId? }) → Session
  *   - get(id) → Session
  *   - list(filter?) → Session[]
+ *   - listSessions(options?) → metadata array (from disk)
+ *   - loadSession(id) → full session with messages (alias for load)
+ *   - forkSession(id) → new session copied from existing
  *   - addMessage(id, message) → void
  *   - clear(id) → void
  *   - save(id) → void
@@ -16,7 +19,7 @@
 
 import os from "node:os";
 import path from "node:path";
-import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, stat } from "node:fs/promises";
 import { SESSIONS_DIR } from "./config.mjs";
 
 export class Session {

package/lib/jsonl-emitter.mjs

@@ -0,0 +1,101 @@
+/**
+ * lib/jsonl-emitter.mjs — Structured JSONL event emitter for CI/pipeline integration
+ *
+ * When --json flag is used, all events are emitted as newline-delimited JSON
+ * to stdout. Event types: start, user_message, assistant_message,
+ * tool_call, tool_result, error, done.
+ */
+
+export class JsonlEmitter {
+  /**
+   * Emit a raw event object as a JSON line to stdout.
+   * @param {object} event
+   */
+  emit(event) {
+    process.stdout.write(JSON.stringify(event) + "\n");
+  }
+
+  /**
+   * Emit a "start" event with session metadata.
+   * @param {{ model?: string, session_id?: string, [key: string]: any }} meta
+   */
+  start(meta) {
+    this.emit({ type: "start", ...meta, timestamp: new Date().toISOString() });
+  }
+
+  /**
+   * Emit a "tool_call" event.
+   * @param {string} name - Tool name
+   * @param {object} args - Tool arguments
+   */
+  toolCall(name, args) {
+    this.emit({ type: "tool_call", name, args, timestamp: new Date().toISOString() });
+  }
+
+  /**
+   * Emit a "tool_result" event.
+   * @param {string} name - Tool name
+   * @param {string|object} result - Tool result
+   * @param {number} durationMs - Duration in milliseconds
+   */
+  toolResult(name, result, durationMs) {
+    this.emit({
+      type: "tool_result",
+      name,
+      result: typeof result === "string" ? result.slice(0, 1000) : result,
+      duration_ms: durationMs,
+    });
+  }
+
+  /**
+   * Emit a user_message or assistant_message event.
+   * @param {"user"|"assistant"} role
+   * @param {string} content
+   */
+  message(role, content) {
+    this.emit({ type: `${role}_message`, content, timestamp: new Date().toISOString() });
+  }
+
+  /**
+   * Emit an "error" event.
+   * @param {Error|string} err
+   */
+  error(err) {
+    this.emit({
+      type: "error",
+      message: err?.message ?? String(err),
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Emit a "done" event with final stats.
+   * @param {{ tokens?: { input: number, output: number }, duration_ms?: number, [key: string]: any }} stats
+   */
+  done(stats) {
+    this.emit({ type: "done", ...stats, timestamp: new Date().toISOString() });
+  }
+}
+
+/**
+ * A no-op emitter used when --json flag is not set.
+ * All methods are silent.
+ */
+export class NullEmitter {
+  emit() {}
+  start() {}
+  toolCall() {}
+  toolResult() {}
+  message() {}
+  error() {}
+  done() {}
+}
+
+/**
+ * Create the appropriate emitter based on whether JSON mode is active.
+ * @param {boolean} jsonMode
+ * @returns {JsonlEmitter|NullEmitter}
+ */
+export function createEmitter(jsonMode) {
+  return jsonMode ? new JsonlEmitter() : new NullEmitter();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wispy-cli",
-  "version": "2.7.10",
+  "version": "2.7.11",
   "description": "🌿 Wispy — AI workspace assistant with trustworthy execution (harness, receipts, approvals, diffs)",
   "license": "MIT",
   "author": "Minseo & Poropo",