@jeffober/thatch 0.1.38 → 0.1.40

package/src/tool-defs.ts

@@ -1,6 +1,18 @@
 import { z } from "zod";
 import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
+import {
+  CONFIG_SECTIONS,
+  loadConfig,
+  mergeNotificationPrefs,
+  notificationDefaults,
+  notificationPrefsSchema,
+  saveConfig,
+  type Config,
+  type ConfigSection,
+  type NotificationPrefs,
+} from "./config";
+import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } from "./notify";
 import { predictionVerb } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
 import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
@@ -11,6 +23,26 @@ const MATCHER_DEDUP_COSINE = 0.85;
 const PREDICTION_DEDUP_COSINE = 0.85;
 const BEHAVIOR_DEDUP_COSINE = 0.85;
 
+/**
+ * Resolves the write target for a store-scoped tool. detectRepo falls back
+ * to "unknown" when it cannot name a repo; rows written to a store called
+ * "unknown" are invisible to every auto-fire scan (which reads the project
+ * store and "global"), so an unidentified context falls back to global.
+ */
+function resolveStore(args: Record<string, unknown>, ctx: CoreContext): string {
+  const store = (args.store as string) || ctx.defaultStore;
+  return store === "unknown" ? "global" : store;
+}
+
+/**
+ * The stores whose items a write must dedup against: the target store plus
+ * global, matching the stores the auto-fire nudge scans. A duplicate in
+ * either store would otherwise surface twice every turn.
+ */
+function dedupScanStores(store: string): string[] {
+  return store === "global" ? ["global"] : [store, "global"];
+}
+
 // Minimum matcher cosine to consider a prediction relevant. Matches the
 // auto-fire threshold in index.ts (PREDICTION_THRESHOLD). The query tool
 // should not return predictions from near-zero-similarity matchers that
@@ -42,6 +74,9 @@ export interface CoreContext {
    *  path - MCP hosts have no poller, no event bus, and no way to deliver a
    *  proactive prompt, so watch tools are opencode-only. */
   watchers?: WatcherRegistry;
+  /** Injectable command runner for notify_user. Defaults to Bun.spawn.
+   *  Tests inject a mock so notifications never actually fire or speak. */
+  spawner?: Spawner;
 }
 
 /**
@@ -177,7 +212,7 @@ const rememberDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const label = args.label as string;
     const content = `# ${label}\n\n${args.content as string}`;
     const embedding = await ctx.model.passageEmbed(content);
@@ -261,7 +296,7 @@ const listDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const entries = ctx.db.listEntries(store);
 
     if (entries.length === 0) return `No memories in "${store}".`;
@@ -291,7 +326,7 @@ const showDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const entry = ctx.db.showEntry(store, args.label as string);
 
     if (!entry) return `No memory labeled "${args.label as string}" found in store "${store}".`;
@@ -312,7 +347,7 @@ const forgetDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const deleted = ctx.db.forgetEntry(store, args.label as string);
 
     if (!deleted) return `No memory labeled "${args.label as string}" found in store "${store}".`;
@@ -351,7 +386,7 @@ const findDuplicatesDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const threshold = (args.threshold as number) ?? 0.85;
     const candidates = ctx.db.findDuplicates(store, threshold);
 
@@ -379,7 +414,7 @@ const markCheckedDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     ctx.db.markPairChecked(
       store,
       ctx.db.slugify(args.label_a as string),
@@ -536,7 +571,7 @@ const predictionUpdateDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const matcherText = args.matcher as string;
     const predictionText = args.prediction as string;
     const signal = args.signal as "confirm" | "disconfirm" | "soft" | "create";
@@ -550,20 +585,23 @@ const predictionUpdateDef: ToolDef = {
     // entire operation rather than leaving orphans (matcher without
     // prediction, prediction without edge, edge without confidence).
     return ctx.db.transaction(() => {
+      // Cross-store dedup: search the target store AND global for a
+      // near-identical prediction. The auto-fire nudge scans both stores,
+      // so two copies would surface twice every turn. When the prediction
+      // already exists in the other store, that store becomes the write
+      // target ("home") and the result echoes where it landed.
+      const existing = ctx.db.findNearestPrediction(dedupScanStores(store), predEmbed, PREDICTION_DEDUP_COSINE);
+      const home = existing?.store ?? store;
+      const storeTag = home === store ? "" : ` in ${home}`;
+
       // Dedup matchers: find an existing matcher above the cosine threshold
       // rather than always creating a new one.
-      let matcherId = ctx.db.findNearestMatcher(store, matcherEmbed, MATCHER_DEDUP_COSINE)?.id;
-      if (!matcherId) matcherId = ctx.db.createMatcher(store, matcherText, matcherEmbed, ctx.model.name);
-
-      // Store-wide dedup: search the entire store for a near-identical
-      // prediction, not just this matcher's edges. If found, link this
-      // matcher to the existing prediction via an edge rather than
-      // creating a second row with the same statement.
-      let predictionId = ctx.db.findNearestPrediction(store, predEmbed, PREDICTION_DEDUP_COSINE)?.id;
+      let matcherId = ctx.db.findNearestMatcher(home, matcherEmbed, MATCHER_DEDUP_COSINE)?.id;
+      if (!matcherId) matcherId = ctx.db.createMatcher(home, matcherText, matcherEmbed, ctx.model.name);
 
-      if (!predictionId) {
+      if (!existing) {
         // No near-identical prediction exists; create one and link it.
-        predictionId = ctx.db.createPrediction(store, predictionText, rationale, predEmbed, ctx.model.name);
+        const predictionId = ctx.db.createPrediction(home, predictionText, rationale, predEmbed, ctx.model.name);
         ctx.db.createEdge(matcherId, predictionId, 1.0);
 
         // When the signal is confirm/disconfirm/soft (not create), apply
@@ -578,9 +616,11 @@ const predictionUpdateDef: ToolDef = {
           return `[created + ${signal}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
         }
         ctx.db.addProvenance(predictionId, "create", rationale);
-        return `[created] ${store} :: "${predictionText}" for "${matcherText}"`;
+        return `[created] ${home} :: "${predictionText}" for "${matcherText}"`;
       }
 
+      const predictionId = existing.id;
+
       // Ensure an edge links this matcher to the existing prediction.
       // createEdge uses ON CONFLICT DO NOTHING, so existing edge weights
       // are preserved.
@@ -592,8 +632,8 @@ const predictionUpdateDef: ToolDef = {
       // confidence-neutral, not a disconfirm.
       if (signal === "create") {
         ctx.db.addProvenance(predictionId, "create", rationale);
-        const existing = ctx.db.getPrediction(predictionId);
-        return `[linked] "${existing?.statement ?? predictionText}" for "${matcherText}" confidence=${(existing?.confidence ?? 0).toFixed(2)} (${existing?.confirm_count ?? 0}/${existing?.disconfirm_count ?? 0})`;
+        const existingItem = ctx.db.getPrediction(predictionId);
+        return `[linked${storeTag}] "${existingItem?.statement ?? predictionText}" for "${matcherText}" confidence=${(existingItem?.confidence ?? 0).toFixed(2)} (${existingItem?.confirm_count ?? 0}/${existingItem?.disconfirm_count ?? 0})`;
       }
 
       // Signal is confirm, disconfirm, or soft. Map the tool's 4-value
@@ -601,7 +641,7 @@ const predictionUpdateDef: ToolDef = {
       ctx.db.adjustConfidence(predictionId, signal === "soft" ? "soft" : signal === "confirm" ? "confirm" : "disconfirm");
       ctx.db.addProvenance(predictionId, signal, rationale);
       const updated = ctx.db.getPrediction(predictionId);
-      return `[${signal}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
+      return `[${signal}${storeTag}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
     });
   },
 };
@@ -613,13 +653,15 @@ const predictionListDef: ToolDef = {
     "confidence, and evidence count. For inspection and debugging.",
   args: {
     store: z.string().optional().describe(
-      "Which store to list. Defaults to the project store.",
+      "Which store to list. Defaults to the project store and global.",
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
-    const predictions = ctx.db.listPredictions(store);
-    if (predictions.length === 0) return `No predictions in "${store}".`;
+    const stores = args.store
+      ? [args.store as string]
+      : [ctx.defaultStore, "global"];
+    const predictions = stores.flatMap((s) => ctx.db.listPredictions(s));
+    if (predictions.length === 0) return `No predictions in "${stores.join('", "')}".`;
     return predictions.map((p) => {
       const matchers = p.matchers.map((m) => `    - "${m.description}" (w:${m.weight})`).join("\n");
       const provenance = ctx.db.getProvenance(p.id);
@@ -647,7 +689,7 @@ const predictionDeleteDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const statementText = args.statement as string;
     const predEmbed = await ctx.model.passageEmbed(statementText);
     const prediction = ctx.db.findNearestPrediction(store, predEmbed, PREDICTION_DEDUP_COSINE);
@@ -690,7 +732,7 @@ const behaviorCodifyDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const situationText = args.situation as string;
     const behaviorText = args.behavior as string;
     const rationale = args.rationale as string;
@@ -699,21 +741,28 @@ const behaviorCodifyDef: ToolDef = {
     const behaviorEmbed = await ctx.model.passageEmbed(behaviorText);
 
     return ctx.db.transaction(() => {
-      let matcherId = ctx.db.findNearestBehaviorMatcher(store, matcherEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
-      if (!matcherId) matcherId = ctx.db.createBehaviorMatcher(store, situationText, matcherEmbed, ctx.model.name);
+      // Cross-store dedup: same rationale as prediction_update. The
+      // auto-fire nudge scans the target store and global, so a duplicate
+      // in either store would surface twice every turn.
+      const existing = ctx.db.findNearestBehavior(dedupScanStores(store), behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
+      const home = existing?.store ?? store;
+      const storeTag = home === store ? "" : ` in ${home}`;
+
+      let matcherId = ctx.db.findNearestBehaviorMatcher(home, matcherEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
+      if (!matcherId) matcherId = ctx.db.createBehaviorMatcher(home, situationText, matcherEmbed, ctx.model.name);
 
-      let behaviorId = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
+      let behaviorId = existing?.id;
       if (!behaviorId) {
-        behaviorId = ctx.db.createBehavior(store, behaviorText, rationale, behaviorEmbed, ctx.model.name);
+        behaviorId = ctx.db.createBehavior(home, behaviorText, rationale, behaviorEmbed, ctx.model.name);
         ctx.db.createBehaviorEdge(matcherId, behaviorId, 1.0);
         ctx.db.addBehaviorProvenance(behaviorId, "codify", rationale);
-        return `[codified] ${store} :: "${behaviorText}" for "${situationText}"`;
+        return `[codified] ${home} :: "${behaviorText}" for "${situationText}"`;
       }
 
       ctx.db.createBehaviorEdge(matcherId, behaviorId, 1.0);
       ctx.db.addBehaviorProvenance(behaviorId, "codify", rationale);
-      const existing = ctx.db.getBehavior(behaviorId);
-      return `[linked] "${existing?.statement ?? behaviorText}" for "${situationText}" confidence=${(existing?.confidence ?? 0).toFixed(2)} (${existing?.confirm_count ?? 0}/${existing?.disconfirm_count ?? 0})`;
+      const behavior = ctx.db.getBehavior(behaviorId);
+      return `[linked${storeTag}] "${behavior?.statement ?? behaviorText}" for "${situationText}" confidence=${(behavior?.confidence ?? 0).toFixed(2)} (${behavior?.confirm_count ?? 0}/${behavior?.disconfirm_count ?? 0})`;
     });
   },
 };
@@ -746,7 +795,7 @@ const behaviorFeedbackDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const behaviorText = args.behavior as string;
     const relevant = args.relevant as boolean;
     const contextText = args.context as string;
@@ -772,13 +821,15 @@ const behaviorListDef: ToolDef = {
     "evidence count. For inspection and debugging.",
   args: {
     store: z.string().optional().describe(
-      "Which store to list. Defaults to the project store.",
+      "Which store to list. Defaults to the project store and global.",
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
-    const behaviors = ctx.db.listBehaviors(store);
-    if (behaviors.length === 0) return `No behaviors in "${store}".`;
+    const stores = args.store
+      ? [args.store as string]
+      : [ctx.defaultStore, "global"];
+    const behaviors = stores.flatMap((s) => ctx.db.listBehaviors(s));
+    if (behaviors.length === 0) return `No behaviors in "${stores.join('", "')}".`;
     return behaviors.map((b) => {
       const matchers = b.matchers.map((m) => `    - "${m.description}" (w:${m.weight})`).join("\n");
       const provenance = ctx.db.getBehaviorProvenance(b.id);
@@ -807,7 +858,7 @@ const behaviorDeleteDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const statementText = args.statement as string;
     const behaviorEmbed = await ctx.model.passageEmbed(statementText);
     const behavior = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
@@ -818,6 +869,161 @@ const behaviorDeleteDef: ToolDef = {
   },
 };
 
+// ---------------------------------------------------------------------------
+// Config and notification tools. The config is a single JSON file beside
+// thatch.db, hand-editable and also managed through these tools. notify_user
+// shells out to the platform's banner and TTS commands - see src/notify.ts.
+// ---------------------------------------------------------------------------
+
+/** Notification preference fields, in presentation order. */
+const NOTIFICATION_FIELDS = ["mode", "voice", "sound"] as const;
+
+/** Renders one section with per-field default annotations for echo output. */
+function renderNotificationSection(prefs: NotificationPrefs | undefined): string {
+  const defaults = notificationDefaults();
+  const lines = ["notifications:"];
+  for (const field of NOTIFICATION_FIELDS) {
+    const current = prefs?.[field];
+    const fallback = defaults[field];
+    lines.push(`  ${field}: ${current ?? "<unset>"}${fallback ? ` (default: ${fallback})` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+/** Drops keys explicitly set to undefined so a merge never overwrites. */
+function stripUndefined(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+
+const configGetDef: ToolDef = {
+  name: "config_get",
+  description:
+    "Read thatch's user config, optionally restricted to one section. " +
+    "Values are annotated with their defaults; unset fields show <unset>. " +
+    "The config file (~/.config/thatch/config.json, beside thatch.db) is " +
+    "also hand-editable. Call this before config_set.",
+  args: {
+    section: z.enum(["notifications"]).optional().describe(
+      "Restrict output to one section. Omit to read all sections.",
+    ),
+  },
+  async execute(args) {
+    const loaded = loadConfig();
+    const lines: string[] = [];
+    if (loaded.warning) lines.push(`[warning] ${loaded.warning}`, "");
+    const sections: ConfigSection[] = args.section
+      ? [args.section as ConfigSection]
+      : [...CONFIG_SECTIONS];
+    for (const name of sections) {
+      if (name === "notifications") {
+        lines.push(renderNotificationSection(loaded.config.notifications));
+      }
+    }
+    lines.push("", `file: ${loaded.path}`);
+    return lines.join("\n");
+  },
+};
+
+const configSetDef: ToolDef = {
+  name: "config_set",
+  description:
+    "Update thatch's user config. Field-level merge: only fields you pass " +
+    "change; omitted fields and omitted sections keep their current values. " +
+    "Returns the resulting section so you can verify the write. Call " +
+    "config_get first to see current values and defaults.",
+  args: {
+    notifications: z.strictObject({
+      mode: z.enum(["both", "banner", "voice", "none"]).optional().describe(
+        "Default channels for notify_user: both, banner only, voice only, " +
+        "or none (disable notifications entirely).",
+      ),
+      voice: z.string().optional().describe(
+        "Spoken voice name (macOS default: Zarvox). Omit to use the " +
+        "platform default.",
+      ),
+      sound: z.string().optional().describe(
+        "Banner alert sound (macOS, from /System/Library/Sounds; default: " +
+        "Submarine). Omit to use the platform default.",
+      ),
+    }).optional().describe(
+      "Notification preferences to update. Fields you omit keep their " +
+      "current values.",
+    ),
+  },
+  async execute(args) {
+    const loaded = loadConfig();
+    const config: Config = { ...loaded.config };
+    const patch = args.notifications as Record<string, unknown> | undefined;
+    if (!patch || Object.keys(stripUndefined(patch)).length === 0) {
+      return (
+        "Nothing to update: pass a section with fields to change.\n" +
+        renderNotificationSection(config.notifications)
+      );
+    }
+    config.notifications = notificationPrefsSchema.parse(
+      mergeNotificationPrefs(config.notifications, stripUndefined(patch)),
+    );
+    const path = saveConfig(config);
+    return (
+      `[saved] ${path}\n` +
+      renderNotificationSection(config.notifications)
+    );
+  },
+};
+
+const notifyUserDef: ToolDef = {
+  name: "notify_user",
+  description:
+    "Notify the user out-of-band: desktop banner and/or spoken voice " +
+    "(macOS: Notification Center + say; Linux: notify-send + spd-say/espeak). " +
+    "Use for long-running terminal-event outcomes worth interrupting for: " +
+    "CI results, merge or deploy completion, watcher events. ALWAYS include " +
+    "source: a word or two identifying the session or work item (ticket " +
+    "number or feature name) so the user knows which session spoke. Honors " +
+    "the user's configured preferences; pass channel to override for this " +
+    "call only. If the configured mode is none, the tool no-ops and says " +
+    "so. The result reports command success only - OS focus modes can " +
+    "silently suppress banners.",
+  args: {
+    message: z.string().describe(
+      "The notification text. Spell out letter sequences so " +
+      "text-to-speech pronounces them (\"C I green\", not \"CI green\").",
+    ),
+    title: z.string().optional().describe(
+      "Banner title. Defaults to source, then \"thatch\".",
+    ),
+    source: z.string().optional().describe(
+      "Short label identifying the session or work item (ticket number or " +
+      "feature name), e.g. \"PLAT-280\". Prepended to the spoken message.",
+    ),
+    channel: z.enum(["both", "banner", "voice"]).optional().describe(
+      "Override the configured mode for this call only.",
+    ),
+    voice: z.string().optional().describe(
+      "Override the configured voice for this call.",
+    ),
+  },
+  async execute(args, ctx) {
+    const loaded = loadConfig();
+    const prefs = loaded.config.notifications ?? {};
+    const mode = prefs.mode ?? "both";
+    if (mode === "none") {
+      return "[skipped] notifications are disabled (notifications.mode: none). " +
+        "Use thatch config_set to re-enable if the user asks.";
+    }
+    const channel = (args.channel as NotifyChannel | undefined) ?? (mode as NotifyChannel);
+    return sendNotification({
+      message: args.message as string,
+      title: args.title as string | undefined,
+      source: args.source as string | undefined,
+      channel,
+      voice: (args.voice as string | undefined) ?? prefs.voice,
+      sound: prefs.sound,
+    }, ctx.spawner ?? defaultSpawner);
+  },
+};
+
+
 /**
  * Reports the calling session's identity. opencode does not surface its
  * session ID to the model, so the model cannot learn it any other way -
@@ -1148,6 +1354,9 @@ export const TOOL_DEFS: ToolDef[] = [
   behaviorFeedbackDef,
   behaviorListDef,
   behaviorDeleteDef,
+  configGetDef,
+  configSetDef,
+  notifyUserDef,
   getSessionInfoDef,
   sessionSearchDef,
   sessionGetDef,