@jeffober/thatch 0.1.28 → 0.1.29

package/src/tool-defs.ts

@@ -1,17 +1,19 @@
 import { z } from "zod";
-import type { ThatchDB, DedupCandidate } from "./db";
+import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
+import { predictionVerb } from "./prompts";
 
-// Near-duplicate thresholds for matcher/prediction dedup at creation time.
-// Matches the thatch_find_duplicates threshold (0.85).
+// Near-duplicate thresholds for matcher/prediction/behavior dedup at
+// creation time. Matches the thatch_find_duplicates threshold (0.85).
 const MATCHER_DEDUP_COSINE = 0.85;
 const PREDICTION_DEDUP_COSINE = 0.85;
+const BEHAVIOR_DEDUP_COSINE = 0.85;
 
 // 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
 // would never fire in the auto-fire.
-const PREDICTION_QUERY_THRESHOLD = 0.45;
+const PREDICTION_QUERY_THRESHOLD = 0.60;
 
 /**
  * Shared context passed to every tool's execute function. Framework-agnostic -
@@ -68,7 +70,7 @@ function formatEntry(
   return parts.join("\n");
 }
 
-function formatRecallResult(entry: any): string {
+function formatRecallResult(entry: MemoryRow & { _score: number }): string {
   let meta = `store:${entry.store}`;
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
@@ -363,25 +365,6 @@ const markCheckedDef: ToolDef = {
   },
 };
 
-/**
- * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
- *
- * Called in a PARENT session after dispatching the fact-extractor, it accepts
- * the buffer: entries move to a holding area and the nudge quiets, but they
- * are not dropped until the extractor completes. Called in a CHILD extractor
- * at the end of its run, it completes the parent's accepted entries -
- * including no-save runs that write no memory. If the child errors or is
- * deleted before either signal, the host requeues the entries so the facts
- * are not lost.
- *
- * The actual state changes happen in the host's post-tool hook
- * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) -
- * this tool's execute function is a no-op confirmation. The tool exists so
- * the model has a recognizable tool name to key on. In the MCP path the
- * file-backed queue is consumed on this call (or on any memory_remember),
- * which is durable across interruption because the queue persists on disk
- * until then.
- */
 /**
  * Fetches the queued extraction payload for a session. The sub-agent calls
  * this with the parent's session ID to retrieve the tool interactions that
@@ -493,7 +476,7 @@ const predictionQueryDef: ToolDef = {
     const scored = ctx.db.scorePredictions(matchers);
     if (scored.length === 0) return "No matching predictions found.";
     return scored.map((s) => {
-      const verb = s.evidence_count === 0 ? "you may prefer" : "you tend to";
+      const verb = predictionVerb(s.evidence_count);
       return `[${s.confidence.toFixed(2)} conf, ${s.evidence_count} tests] ` +
         `When ${s.matcher_description}: ${verb} ${s.statement}`;
     }).join("\n");
@@ -650,6 +633,166 @@ const predictionDeleteDef: ToolDef = {
   },
 };
 
+// ---------------------------------------------------------------------------
+// Behavior engine: LLM self-discipline rules with ham/spam feedback
+// ---------------------------------------------------------------------------
+
+const behaviorCodifyDef: ToolDef = {
+  name: "behavior_codify",
+  description:
+    "Codify a self-discipline rule: when situation X arises, you should " +
+    "do Y. Use when you recognize a situation you should react to in a " +
+    "specific, repeatable way that is NOT a user preference (use " +
+    "prediction_update for those). The rule is about your own operational " +
+    "discipline, not what the user wants. Examples: check the whole " +
+    "codebase for a library before importing it; investigate disabled " +
+    "tests before touching the area; read a large function fully before " +
+    "editing it.",
+  args: {
+    situation: z.string().describe(
+      "Description of the situation that triggers this behavior. What context " +
+      "or task type makes this rule apply?",
+    ),
+    behavior: z.string().describe(
+      "The behavioral rule. What should you do when this situation arises?",
+    ),
+    rationale: z.string().describe(
+      "Why you are codifying this rule. What happened that made you realize " +
+      "this behavior is worth persisting?",
+    ),
+    store: z.string().optional().describe(
+      "Store to write to. Defaults to the project store.",
+    ),
+  },
+  async execute(args, ctx) {
+    const store = (args.store as string) || ctx.defaultStore;
+    const situationText = args.situation as string;
+    const behaviorText = args.behavior as string;
+    const rationale = args.rationale as string;
+
+    const matcherEmbed = await ctx.model.passageEmbed(situationText);
+    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);
+
+      let behaviorId = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
+      if (!behaviorId) {
+        behaviorId = ctx.db.createBehavior(store, 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}"`;
+      }
+
+      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 behaviorFeedbackDef: ToolDef = {
+  name: "behavior_feedback",
+  description:
+    "Record ham/spam feedback on a surfaced behavior. When the behavior " +
+    "nudge surfaces rules and you evaluate each against the current " +
+    "situation, call this with relevant: true (ham) if the rule applies, " +
+    "or relevant: false (spam) if it does not. This trains the classifier " +
+    "so future nudges are more accurate. Also use when the user corrects " +
+    "your behavior and you realize a codified rule led you astray or " +
+    "should have been followed.",
+  args: {
+    behavior: z.string().describe(
+      "The behavior statement to provide feedback on. Use behavior_list " +
+      "to find the exact text; matching is semantic (cosine >= 0.85).",
+    ),
+    relevant: z.boolean().describe(
+      "true (ham) if the behavior is relevant to the current situation. " +
+      "false (spam) if it is not relevant.",
+    ),
+    context: z.string().describe(
+      "Brief description of the current situation, so the feedback is " +
+      "auditable in provenance.",
+    ),
+    store: z.string().optional().describe(
+      "Store to search. Defaults to the project store.",
+    ),
+  },
+  async execute(args, ctx) {
+    const store = (args.store as string) || ctx.defaultStore;
+    const behaviorText = args.behavior as string;
+    const relevant = args.relevant as boolean;
+    const contextText = args.context as string;
+
+    const behaviorEmbed = await ctx.model.passageEmbed(behaviorText);
+    const behavior = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
+    if (!behavior) return `No behavior matching "${behaviorText}" found in "${store}".`;
+
+    const signal = relevant ? "confirm" : "disconfirm";
+    ctx.db.transaction(() => {
+      ctx.db.adjustBehaviorConfidence(behavior.id, signal);
+      ctx.db.addBehaviorProvenance(behavior.id, signal, `${relevant ? "ham" : "spam"}: ${contextText}`);
+    });
+    const updated = ctx.db.getBehavior(behavior.id);
+    return `[${signal}] "${updated?.statement ?? behaviorText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
+  },
+};
+
+const behaviorListDef: ToolDef = {
+  name: "behavior_list",
+  description:
+    "List all codified behaviors with their matchers, confidence, and " +
+    "evidence count. For inspection and debugging.",
+  args: {
+    store: z.string().optional().describe(
+      "Which store to list. Defaults to the project store.",
+    ),
+  },
+  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}".`;
+    return behaviors.map((b) => {
+      const matchers = b.matchers.map((m) => `    - "${m.description}" (w:${m.weight})`).join("\n");
+      const provenance = ctx.db.getBehaviorProvenance(b.id);
+      const provLines = provenance.map((pr) => `    - [${pr.created_at.slice(0, 10)}] ${pr.signal}: ${pr.detail ?? ""}`).join("\n");
+      return `[${b.confidence.toFixed(2)} conf, ${b.evidence_count} tests] ${b.statement}` +
+        (b.rationale ? `\n  rationale: ${b.rationale}` : "") +
+        (matchers ? `\n  matchers:\n${matchers}` : "") +
+        (provLines ? `\n  provenance:\n${provLines}` : "");
+    }).join("\n\n");
+  },
+};
+
+const behaviorDeleteDef: ToolDef = {
+  name: "behavior_delete",
+  description:
+    "Delete a codified behavior. Useful when a behavior was created in " +
+    "error or is no longer relevant. Edges and provenance are deleted " +
+    "automatically (cascade).",
+  args: {
+    statement: z.string().describe(
+      "The behavior statement to delete. Use behavior_list to find the " +
+      "exact text; matching is semantic (cosine >= 0.85).",
+    ),
+    store: z.string().optional().describe(
+      "Store to delete from. Defaults to the project store.",
+    ),
+  },
+  async execute(args, ctx) {
+    const store = (args.store as string) || ctx.defaultStore;
+    const statementText = args.statement as string;
+    const behaviorEmbed = await ctx.model.passageEmbed(statementText);
+    const behavior = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
+    if (!behavior) return `No behavior matching "${statementText}" found in "${store}".`;
+    const deleted = ctx.db.deleteBehavior(behavior.id);
+    if (!deleted) return `Failed to delete behavior "${behavior.statement}".`;
+    return `[deleted] "${behavior.statement}" from "${store}"`;
+  },
+};
+
 /**
  * All tool definitions, in the order they should be presented to the agent.
  * The opencode plugin wraps each in `tool()`; the MCP server exposes them
@@ -670,4 +813,8 @@ export const TOOL_DEFS: ToolDef[] = [
   predictionUpdateDef,
   predictionListDef,
   predictionDeleteDef,
+  behaviorCodifyDef,
+  behaviorFeedbackDef,
+  behaviorListDef,
+  behaviorDeleteDef,
 ];

package/src/vector-math.ts

@@ -0,0 +1,30 @@
+/**
+ * Reconstructs a Float32Array from a stored BLOB. The Uint8Array bun:sqlite
+ * hands back may itself be a view, so honor its offset and length rather than
+ * reading the whole backing buffer.
+ */
+export function blobToVector(blob: Uint8Array): Float32Array {
+  return new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / 4);
+}
+
+/**
+ * Cosine similarity between two Float32Array vectors of equal dimension.
+ * Returns a value in [-1, 1]. Normalized embeddings will be close to [0, 1].
+ * Throws on dimension mismatch - comparing vectors from different embedding
+ * spaces is always a caller bug; callers filter by length first.
+ */
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length) {
+    throw new Error(`cosineSimilarity: dimension mismatch (${a.length} vs ${b.length})`);
+  }
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const denominator = Math.sqrt(magA) * Math.sqrt(magB);
+  return denominator === 0 ? 0 : dot / denominator;
+}

package/docs/qa/README.md

@@ -1,175 +0,0 @@
-# QA — Test Plan
-
-Thatch uses `bun:test`. The full suite runs in well under a second with no
-network access and no writes outside temp directories.
-
-## Test conventions
-
-- **DB tests** create a real SQLite file in a `mkdtempSync` temp directory,
-  removed in `afterEach`. (Real files, not `:memory:` — WAL behavior differs.)
-- **Embedding tests** use `MockEmbeddingModel`: hash-seeded deterministic
-  vectors, so identical texts embed identically and unrelated texts land
-  near-orthogonal. The real `BgeEmbeddingModel` is never instantiated in
-  tests — nothing downloads models.
-- **Git unit tests** exercise `parseGitUrl` on strings; **git integration
-  tests** create throwaway repos in temp directories and run real git.
-- **Tool tests** build tools via the factory functions with an injected temp
-  DB + mock model, then call `execute` directly.
-- **Plugin tests** call the `server` entry with a mock client and redirect
-  `THATCH_DB_PATH` and `XDG_CONFIG_HOME` into a temp directory so skill
-  installation never touches the real `~/.config`.
-
-## Running tests
-
-```bash
-bun test          # all tests
-bun test --watch  # watch mode
-mise run check       # typecheck + bun test + markdownlint (the CI gate)
-mise run typecheck   # tsc alone
-mise run lint-md     # markdownlint only
-```
-
-`mise run check` is the canonical quality gate (also run by CI on push/PR to
-`main`). Typecheck uses `tsconfig.check.json` (which includes the test files
-that the build's `tsconfig.json` excludes). Markdownlint enforces structural
-correctness on `README.md` and `docs/` excluding `docs/plans/`; see
-`.markdownlint-cli2.jsonc` for rule config.
-
-## Test files and coverage
-
-### `tests/db.test.ts`
-
-- `cosineSimilarity`: identical/orthogonal/opposite/zero vectors; throws on
-  dimension mismatch
-- Schema creation, store creation/idempotence
-- `slugify`: ASCII, unicode preservation, hash fallback for all-symbol labels
-- `remember`: insert, duplicate rejection without `overwrite`, overwrite,
-  metadata, embedding round-trip through a view with non-zero `byteOffset`
-- `recall`: ranking, multi-store, unknown store, empty store list, limit,
-  branch scoping, skipping dimension-mismatched entries
-- `listEntries`, `showEntry`, `forgetEntry`
-- Dedup: `findDuplicates` thresholding, checked-pair suppression, verdict
-  invalidation on overwrite and forget, dimension-mismatch pair skipping
-- `findSimilar`: threshold/ranking, self-exclusion, dimension skipping, no
-  telemetry side effects
-- Recall telemetry: returned rows (and only returned rows) stamped
-- Hygiene queries: stale counting with recall-refresh, branch listing/counts
-- Column migration: pre-telemetry databases gain the new columns on open
-
-### `tests/git.test.ts`
-
-- `parseGitUrl` across SSH shorthand, HTTPS/HTTP, `ssh://`, `git://`,
-  GitLab/self-hosted, hyphens/dots, trailing whitespace, unparseable input
-
-### `tests/git-integration.test.ts`
-
-- `detectRepo` against real temp git repos: HTTPS remote, SSH remote,
-  no-`.git`-suffix remote, no-remote fallback, non-git-directory fallback
-- `listBranches`: local branches listed; empty outside a git repo
-
-### `tests/embeddings.test.ts`
-
-- `MockEmbeddingModel` contract: dims, loaded, determinism, query/passage
-  equivalence, distinct texts → distinct near-orthogonal vectors, model name
-- `BgeEmbeddingModel` (with injected pipeline factory): lazy-load, loaded
-  state, concurrent load memoization, error retry, query prefix for
-  asymmetric search, passage has no prefix, model name tag, default model name
-
-### `tests/tools.test.ts`
-
-- `thatch_memory_remember`: happy path, duplicate rejection, overwrite,
-  explicit store, metadata
-- `thatch_memory_recall`: default repo+global scope, empty results, store
-  override, limit
-- `thatch_memory_list` / `show` / `forget`: found, not-found, store override
-- `thatch_store_list`
-- `thatch_find_duplicates`: surfaces similar pairs, cluster grouping,
-  no-match message, store override, skips checked pairs
-- `thatch_dedup_mark_checked`: records verdict, store override
-- Write-time collision warning: fires on similar content, silent for
-  unrelated content, never warns against itself on overwrite
-
-### `tests/plugin.test.ts`
-
-- `server` export shape: all thirteen tools, every hook present, tools carry
-  description/args/execute
-- System transform and compaction hooks append their text
-- `tool.execute.after` → `chat.message` extraction round-trip: nudge carries
-  the JSON payload, buffers are per-session, flush is one-shot, `thatch_*`
-  tools are excluded from buffering
-- Skill files land under the redirected `XDG_CONFIG_HOME`
-- `event` handler: calls `client.session.prompt` on `session.created` with
-  correct session ID and nudge text; ignores non-`session.created` events
-- `sessionStartReminder`: includes store name and recall instructions
-- Recall nudge via `chat.message`: surfaces when prompt matches a stored
-  memory, no nudge for unrelated or short prompts, extraction priority
-- Prediction auto-fire via `chat.message`: surfaces when prompt matches a
-  stored matcher, no nudge for unrelated prompts, prediction and recall
-  nudges fire independently as separate synthetic parts
-
-### `tests/tool-defs.test.ts`
-
-- Tool count (13) and name list
-- Zod schema validation for each tool's args
-- Execute functions: `memory_remember` save/duplicate/overwrite/archived,
-  `memory_recall` default/empty/archived, `memory_list`/`show`/`forget`,
-  `store_list`, `find_duplicates` clean store
-- Prediction execute functions: `prediction_update` create/confirm/disconfirm/
-  create-on-existing (dedup links without disconfirming), `prediction_query`
-  matching/unrelated, `prediction_list` with provenance, `prediction_delete`
-  found/not-found
-
-### `tests/prediction.test.ts`
-
-- Schema: tables exist, `populationP0` fallback on empty store
-- Matcher creation and lookup: `findMatchers` ranking, `findNearestMatcher`
-  threshold/dedup
-- Prediction creation: `createPrediction` seeds at p0, `adjustConfidence`
-  confirm/disconfirm/soft/multiple, non-existent ID no-op
-- Edges and scoring: `createEdge` links, `scorePredictions` empty/dedup/
-  weight-preservation, `scorePredictionNudge` threshold filtering + dedup
-- `findNearestPrediction`: store-wide search, threshold, cross-matcher
-- Provenance: `addProvenance` + `getProvenance` read-back, `deletePrediction`
-  cascade to edges and provenance
-- `listPredictions`: sorted by confidence, matchers included
-- `populationP0`: under-20 fallback, population hit rate with sufficient evidence
-
-### `tests/hygiene.test.ts`
-
-- `hygieneReport`: silent on a healthy store; counts duplicate candidates,
-  stale memories, and orphaned branch-scoped memories (against a real temp
-  git repo); skips the branch check outside a git repo
-- `sessionStartReminder` hygiene block: appended when present, omitted when
-  null, single-arg call unchanged
-
-## Known gaps
-
-- `BgeEmbeddingModel`'s default `PipelineFactory` (the real HF import) is
-  untested — exercising it means downloading the real model, which violates
-  the no-network rule. The lazy-load logic is tested with an injected mock
-  factory. The real model is exercised indirectly by any real opencode use.
-- The skill install failure path in `index.ts` has no test (would require
-  mocking `fs` to force a write error).
-- `bin/thatch` has no automated tests; it is a thin shell over `db.ts`.
-
-## QA use-case suite
-
-End-to-end QA scenarios live in `tests/qa/` as bun test files, not docs.
-Each use case is a `uc-NNN-*.test.ts` file that defines preconditions,
-steps, and expected results as string constants, then registers itself
-via `registerUseCase` from `tests/qa/runner.ts`.
-
-Most use cases shell out to `opencode run` with an isolated repo copy
-(temp DB, temp config, temp home). Automatable use cases override the
-`run` function with direct CLI/bun assertions. Manual-only use cases
-(compaction, visual TUI) are skipped automatically.
-
-Run the suite:
-
-```bash
-mise run qa          # full run (spawns opencode sessions, costs model tokens)
-mise run qa-dry-run  # list use cases without spawning sessions
-```
-
-The regular test suite (`mise run check`) excludes `tests/qa/` by using
-a flat glob (`bun test tests/*.test.ts`).