@jeffober/thatch 0.1.35 → 0.1.36

package/src/skills.ts

@@ -1,6 +1,5 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import pkg from "../package.json";
 
 export interface SkillFile {
   name: string;
@@ -73,46 +72,32 @@ export const OPENCODE_ONLY_SKILLS: SkillDef[] = loadOpencodeOnlySkills();
 // Stale skill cleanup - runs before install on every skillsDir
 // ---------------------------------------------------------------------------
 
-// Skills renamed from non-prefixed to thatch-prefixed in v0.1.27. The old
-// names are cleaned up during install for a limited version window because
-// non-prefixed names could be adopted by third parties after we abandon them.
-// After RENAME_MIGRATION_MAX_VERSION, the cleanup stops and leftover stale
-// files are the user's responsibility.
-const RENAMED_SKILLS = new Set([
-  "pr-description",
-  "ticket-description",
-  "split-overlarge-pr",
-]);
-
-// Last version that ships the non-prefixed-to-prefixed migration cleanup.
-// Users who upgrade to this version or earlier get automatic cleanup of the
-// old skill directories. Users who skip past this version must manually
-// delete the stale directories.
-const RENAME_MIGRATION_MAX_VERSION = "0.1.35";
-
-function compareVersions(a: string, b: string): number {
-  const [aMaj, aMin, aPatch] = a.split(".").map(Number);
-  const [bMaj, bMin, bPatch] = b.split(".").map(Number);
-  if (aMaj !== bMaj) return aMaj - bMaj;
-  if (aMin !== bMin) return aMin - bMin;
-  return aPatch - bPatch;
-}
+// ---------------------------------------------------------------------------
+// Stale skill cleanup - runs before install on every skillsDir
+// ---------------------------------------------------------------------------
+
+// Skills renamed from non-prefixed to thatch-prefixed in v0.1.27
+// (pr-description, ticket-description, split-overlarge-pr) were cleaned up
+// during install through a version-gated window that closed with v0.1.35.
+// The gate is gone because it can never reopen: package versions only grow,
+// so this code only ever runs at a version past the window. The standing
+// contract it protected remains: non-prefixed skill names belong to third
+// parties and are NEVER removed - cleanup only touches thatch-* dirs, where
+// the prefix is our namespace. Users upgrading from before v0.1.27 delete
+// the old directories manually.
 
 /**
  * Remove stale skill directories before installing the current set.
  *
- * Two cleanup rules:
+ * One rule: delete any `thatch-*` skill directory that is not in the current
+ * install set. The `thatch-` prefix is our namespace - no third party should
+ * use it, so unconditional removal is safe. This catches skills we've
+ * renamed or removed in any release.
  *
- * 1. Always: delete any `thatch-*` skill directory that is not in the current
- *    install set. The `thatch-` prefix is our namespace - no third party should
- *    use it, so unconditional removal is safe. This catches skills we've
- *    renamed or removed in any release.
- *
- * 2. Version-gated: delete directories matching old non-prefixed skill names
- *    (pr-description, ticket-description, split-overlarge-pr) through
- *    RENAME_MIGRATION_MAX_VERSION. These names lack the thatch- prefix and
- *    could be adopted by third parties after we abandon them, so the cleanup
- *    is time-boxed. Users who upgrade past the window must manually clean up.
+ * Non-prefixed directories are never touched. The v0.1.27 rename migration
+ * (pr-description -> thatch-pr-description and siblings) removed old
+ * non-prefixed dirs through a version window that closed with v0.1.35; see
+ * the block comment above.
  */
 function cleanupStaleSkills(skillsDir: string, currentNames: string[]): void {
   const currentSet = new Set(currentNames);
@@ -123,9 +108,6 @@ function cleanupStaleSkills(skillsDir: string, currentNames: string[]): void {
     return; // dir doesn't exist or isn't readable - nothing to clean
   }
 
-  const withinMigrationWindow =
-    compareVersions(pkg.version, RENAME_MIGRATION_MAX_VERSION) <= 0;
-
   for (const entry of entries) {
     // isDirectory() returns false for symlinks (even symlinked dirs), so
     // check isSymbolicLink() too - a symlinked skill dir is just as stale
@@ -149,15 +131,9 @@ function cleanupStaleSkills(skillsDir: string, currentNames: string[]): void {
       }
     };
 
-    // Rule 1: stale thatch-* dirs (our namespace, always safe to remove).
+    // Stale thatch-* dirs: our namespace, always safe to remove.
     if (name.startsWith("thatch-") && !currentSet.has(name)) {
       remove();
-      continue;
-    }
-
-    // Rule 2: renamed non-prefixed dirs (version-gated, third-party risk).
-    if (RENAMED_SKILLS.has(name) && withinMigrationWindow) {
-      remove();
     }
   }
 }

package/src/tool-defs.ts

@@ -2,6 +2,8 @@ import { z } from "zod";
 import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
 import { predictionVerb } from "./prompts";
+import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
+import { WATCHER_EVENT_TYPES, type WatcherRegistry, type WatcherEventType } from "./watchers";
 
 // Near-duplicate thresholds for matcher/prediction/behavior dedup at
 // creation time. Matches the thatch_find_duplicates threshold (0.85).
@@ -36,6 +38,21 @@ export interface CoreContext {
    *  childToParent). Called by extraction_done when the sub-agent passes
    *  the parent's session_id. */
   drainExtractionQueue?: (sessionID: string) => void;
+  /** The plugin's in-memory watcher registry. Only wired on the opencode
+   *  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;
+}
+
+/**
+ * Per-call host context identifying the session a tool call belongs to.
+ * opencode's plugin system supplies it on every tool execution; MCP servers
+ * have no session concept and omit it. Only tools that need session identity
+ * consume it - the rest ignore the third execute parameter.
+ */
+export interface HostToolContext {
+  sessionID: string;
+  agent: string;
 }
 
 /**
@@ -49,7 +66,13 @@ export interface ToolDef {
   name: string;
   description: string;
   args: Record<string, z.ZodType>;
-  execute(args: Record<string, unknown>, ctx: CoreContext): Promise<string>;
+  execute(args: Record<string, unknown>, ctx: CoreContext, host?: HostToolContext): Promise<string>;
+  /**
+   * When true, the tool exists only on the opencode plugin path and the MCP
+   * server filters it out of tools/list. Used for tools that depend on host
+   * capabilities MCP hosts lack (e.g. session identity).
+   */
+  opencodeOnly?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -795,10 +818,247 @@ const behaviorDeleteDef: ToolDef = {
   },
 };
 
+/**
+ * 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 -
+ * yet it needs the ID to call thatch_get_extraction_payload /
+ * thatch_extraction_done on the parent's behalf and for session
+ * archaeology against opencode.db. MCP hosts have no session concept,
+ * hence opencodeOnly.
+ */
+const getSessionInfoDef: ToolDef = {
+  name: "get_session_info",
+  description:
+    "Return the current session's identity: the host session ID and the " +
+    "agent name running this turn (e.g. build, plan, or a sub-agent type). " +
+    "opencode-only: MCP hosts have no session concept. Use the session ID " +
+    "when a nudge tells you to call a tool with the parent's session_id, " +
+    "or to query past sessions in ~/.local/share/opencode/opencode.db.",
+  args: {},
+  opencodeOnly: true,
+  async execute(_args, _ctx, host) {
+    if (!host) {
+      return "Session identity is unavailable: this host did not provide a session context.";
+    }
+    return `sessionID: ${host.sessionID}\nagent: ${host.agent}`;
+  },
+};
+
+/**
+ * Lets the model search its own past opencode conversations. The model only
+ * knows the current session id (via get_session_info); everything before
+ * compaction or in earlier sessions is invisible to it otherwise. Returns
+ * the same JSONL timeline shape as `thatch session search`, with previews
+ * truncated so a result set stays context-affordable; session_get fetches
+ * full content for interesting hits.
+ */
+const sessionSearchDef: ToolDef = {
+  name: "session_search",
+  description:
+    "Search past opencode session conversations by substring (or regex with " +
+    "regex: true). Matches decoded message text, tool outputs, and reasoning " +
+    "across all sessions (or one session with session_id). Returns JSONL " +
+    "entries with ids for follow-up: call session_get with a hit's part_id " +
+    "or msg_id to retrieve the full content. opencode-only.",
+  args: {
+    query: z.string().describe(
+      "Substring to find (case-insensitive), or a regular expression when regex is true.",
+    ),
+    regex: z.boolean().optional().describe(
+      "Treat query as a regular expression instead of a plain substring.",
+    ),
+    session_id: z.string().optional().describe(
+      "Narrow the search to one session. Omit to search all sessions.",
+    ),
+    limit: z.number().optional().describe(
+      "Maximum matches to return (default 200, oldest first).",
+    ),
+  },
+  opencodeOnly: true,
+  async execute(args) {
+    const dbPath = resolveOpencodeDbPath();
+    if (!dbPath) {
+      return "Session search is unavailable: no opencode database was found (set OPENCODE_DB to point at one).";
+    }
+    const db = new SessionDB(dbPath);
+    try {
+      const matches = db.search(args.query as string, {
+        regex: args.regex === true,
+        sessionID: args.session_id as string | undefined,
+        limit: typeof args.limit === "number" ? args.limit : undefined,
+      });
+      if (matches.length === 0) return `No matches for "${args.query}".`;
+      // Session titles orient cross-session results the same way the CLI
+      // search does; cached because matches cluster by session.
+      const titles = new Map<string, string | null>();
+      return matches
+        .map((part) => {
+          if (!titles.has(part.sessionId)) {
+            titles.set(part.sessionId, db.getSession(part.sessionId)?.title ?? null);
+          }
+          return JSON.stringify({
+            session_id: part.sessionId,
+            session_title: titles.get(part.sessionId),
+            ...partToTimelineEntry(part),
+          });
+        })
+        .join("\n");
+    } finally {
+      db.close();
+    }
+  },
+};
+
+/**
+ * Fetches the full, untruncated content of one part or message found via
+ * session_search. Tool parts carry their complete args and output - the
+ * detail the timeline preview truncates.
+ */
+const sessionGetDef: ToolDef = {
+  name: "session_get",
+  description:
+    "Retrieve the full content of one conversation item by id. Pass a " +
+    "part_id (from session_search or session list) for one content piece, " +
+    "or a msg_id for an entire message with all of its parts. Tool parts " +
+    "include their complete input arguments and output. opencode-only.",
+  args: {
+    id: z.string().describe(
+      "A part id (prt_...) or message id (msg_...) from session_search results.",
+    ),
+  },
+  opencodeOnly: true,
+  async execute(args) {
+    const dbPath = resolveOpencodeDbPath();
+    if (!dbPath) {
+      return "Session retrieval is unavailable: no opencode database was found (set OPENCODE_DB to point at one).";
+    }
+    const db = new SessionDB(dbPath);
+    try {
+      const id = args.id as string;
+      if (id.startsWith("msg_")) {
+        const message = db.getMessage(id);
+        if (!message) return `No message "${id}" found.`;
+        return JSON.stringify(messageToFullJson(message), null, 2);
+      }
+      const part = db.getPart(id);
+      if (!part) return `No part "${id}" found.`;
+      return JSON.stringify(partToFullJson(part), null, 2);
+    } finally {
+      db.close();
+    }
+  },
+};
+
+/**
+ * Registers a background watcher on a GitHub PR. The plugin process polls
+ * the PR (via the gh CLI, using the user's existing gh auth) and prompts the
+ * session with a synthetic notification when a watched event happens.
+ * opencode-only: MCP hosts have no poller and no proactive-prompt channel.
+ */
+const watchCreateDef: ToolDef = {
+  name: "watch_create",
+  description:
+    "Watch a GitHub PR for events and get notified in this session when they " +
+    "happen. Events: new top-level comments, new inline review comments, " +
+    "replies to review comments, new commits (head SHA change), PR status " +
+    "changes, title/description edits, and completed CI check runs. The " +
+    "watcher polls in the background and injects a notification prompt; " +
+    "notifications carry pointers only (author, URL) - fetch details yourself " +
+    "with the gh CLI when you decide to act. Watches live until cancelled, " +
+    "the session ends, or opencode restarts. Requires the gh CLI.",
+  args: {
+    pr: z.number().int().positive().describe(
+      "The PR number to watch.",
+    ),
+    repo: z.string().optional().describe(
+      "GitHub repo as owner/repo. Defaults to this project's repo from the git remote.",
+    ),
+    events: z.array(z.enum(WATCHER_EVENT_TYPES as [WatcherEventType, ...WatcherEventType[]])).optional().describe(
+      "Which event types to watch. Omit for all event types.",
+    ),
+  },
+  opencodeOnly: true,
+  async execute(args, ctx, host) {
+    if (!host) {
+      return "Watching is unavailable: this host did not provide a session context.";
+    }
+    if (!ctx.watchers) {
+      return "Watching is unavailable: no watcher registry was wired by this host.";
+    }
+    const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
+    const events = (args.events as WatcherEventType[] | undefined) ?? [...WATCHER_EVENT_TYPES];
+    const result = await ctx.watchers.create(host.sessionID, repo, args.pr as number, events);
+    if (!result.ok) return `Watcher not created: ${result.error}`;
+    const w = result.watcher;
+    return (
+      `[watching] ${w.repo}#${w.pr}\n` +
+      `id: ${w.id}\n` +
+      `events: ${w.events.join(", ")}\n` +
+      `head: ${w.state.headSha.slice(0, 7)} (${w.state.state}${w.state.merged ? ", merged" : ""})\n\n` +
+      `The baseline is captured now - only changes from this point notify. ` +
+      `You will receive a system notification in this session when a watched event happens. ` +
+      `State any handling policy for those notifications now (e.g. what to act on, what just to report), ` +
+      `since the notification itself carries only pointers.`
+    );
+  },
+};
+
+/**
+ * Lists the calling session's active watchers. opencode-only, session-scoped:
+ * a session can only ever see its own watches.
+ */
+const watchListDef: ToolDef = {
+  name: "watch_list",
+  description:
+    "List this session's active watchers with their ids, targets, watched " +
+    "event types, and remaining time. opencode-only.",
+  args: {},
+  opencodeOnly: true,
+  async execute(_args, ctx, host) {
+    if (!host) {
+      return "Watching is unavailable: this host did not provide a session context.";
+    }
+    if (!ctx.watchers) {
+      return "Watching is unavailable: no watcher registry was wired by this host.";
+    }
+    const watchers = ctx.watchers.listForSession(host.sessionID);
+    if (watchers.length === 0) return "No active watchers.";
+    const minutesLeft = (w: { expiresAt: number }) => Math.max(0, Math.round((w.expiresAt - Date.now()) / 60_000));
+    return watchers
+      .map((w) => `${w.id}: ${w.repo}#${w.pr} events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m head=${w.state.headSha.slice(0, 7)}`)
+      .join("\n");
+  },
+};
+
+/**
+ * Cancels one watcher. opencode-only, session-scoped: cancelling by id only
+ * works for the session that created it.
+ */
+const watchCancelDef: ToolDef = {
+  name: "watch_cancel",
+  description: "Cancel one of this session's watchers by id. opencode-only.",
+  args: {
+    id: z.string().describe("The watcher id from watch_create or watch_list."),
+  },
+  opencodeOnly: true,
+  async execute(args, ctx, host) {
+    if (!host) {
+      return "Watching is unavailable: this host did not provide a session context.";
+    }
+    if (!ctx.watchers) {
+      return "Watching is unavailable: no watcher registry was wired by this host.";
+    }
+    const cancelled = ctx.watchers.cancel(host.sessionID, args.id as string);
+    if (!cancelled) return `No watcher "${args.id}" in this session.`;
+    return `[cancelled] ${args.id}`;
+  },
+};
+
 /**
  * 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
- * via `tools/list` and dispatches `tools/call` to their execute functions.
+ * The opencode plugin wraps each in `tool()`; the MCP server exposes the
+ * non-opencodeOnly ones via `tools/list` and dispatches `tools/call` to
+ * their execute functions.
  */
 export const TOOL_DEFS: ToolDef[] = [
   rememberDef,
@@ -819,4 +1079,10 @@ export const TOOL_DEFS: ToolDef[] = [
   behaviorFeedbackDef,
   behaviorListDef,
   behaviorDeleteDef,
+  getSessionInfoDef,
+  sessionSearchDef,
+  sessionGetDef,
+  watchCreateDef,
+  watchListDef,
+  watchCancelDef,
 ];

package/src/tools.ts

@@ -1,7 +1,8 @@
 import { tool } from "@opencode-ai/plugin";
 import type { ThatchDB } from "./db";
 import type { EmbeddingModel } from "./embeddings";
-import { TOOL_DEFS, type CoreContext } from "./tool-defs";
+import { TOOL_DEFS, type CoreContext, type HostToolContext } from "./tool-defs";
+import type { WatcherRegistry } from "./watchers";
 
 /**
  * Builds the opencode tool map from shared tool definitions. Each definition
@@ -16,6 +17,7 @@ export function createTools(
   extensions?: {
     extractionPayloadProvider?: CoreContext["extractionPayloadProvider"];
     drainExtractionQueue?: CoreContext["drainExtractionQueue"];
+    watcherRegistry?: WatcherRegistry;
   },
 ): Record<string, ReturnType<typeof tool>> {
   const ctx: CoreContext = {
@@ -24,6 +26,7 @@ export function createTools(
     defaultStore,
     extractionPayloadProvider: extensions?.extractionPayloadProvider,
     drainExtractionQueue: extensions?.drainExtractionQueue,
+    watchers: extensions?.watcherRegistry,
   };
 
   const tools: Record<string, ReturnType<typeof tool>> = {};
@@ -31,8 +34,13 @@ export function createTools(
     tools[`thatch_${def.name}`] = tool({
       description: def.description,
       args: def.args,
-      async execute(args) {
-        return def.execute(args as Record<string, unknown>, ctx);
+      async execute(args, hostContext) {
+        // Trim opencode's ToolContext to the host-agnostic fields the shared
+        // definitions know about. Tests and MCP paths pass no host context.
+        const host: HostToolContext | undefined = hostContext
+          ? { sessionID: hostContext.sessionID, agent: hostContext.agent }
+          : undefined;
+        return def.execute(args as Record<string, unknown>, ctx, host);
       },
     });
   }