@jeffober/thatch 0.1.35 → 0.1.37

package/docs/user/watchers.md

@@ -0,0 +1,91 @@
+# Watchers
+
+Watchers monitor external sources - today, GitHub pull requests and
+branches - and inject a notification into the conversation when
+something happens. You ask the agent to watch a PR or a branch; thatch
+polls it in the background; the agent gets woken up when a watched
+event occurs. No one has to keep asking "any updates yet?"
+
+## What it does
+
+The agent calls `thatch_watch_create` to register a watcher on a PR,
+or `thatch_watch_branch_create` to register a watcher on a branch
+(typically main). thatch captures the target's current state as a
+baseline, then polls the GitHub API through the `gh` CLI once a
+minute. When the target changes in a way the watcher cares about, the
+plugin prompts the agent with a notification.
+
+PR watched events:
+
+- `pr_comment` - new top-level comments on the PR
+- `pr_review_comment` - new inline comments on the diff
+- `pr_review_reply` - replies to an existing review comment
+- `pr_review_resolved` - a review thread resolved or reopened
+- `pr_commit` - new commits (the head SHA moved)
+- `pr_status` - the PR opened, closed, or merged
+- `pr_description` - title or description edited
+- `pr_ci` - a CI check run on the head SHA completed
+
+Branch watched events:
+
+- `branch_commit` - new commits land on the branch (e.g. a PR merged)
+- `branch_ci` - a check run on the branch head completed
+- `branch_workflow` - a GitHub Actions workflow run starts or finishes
+  on the branch, optionally filtered by workflow name (substring,
+  case-insensitive)
+
+Notifications are delivered as synthetic parts: the model sees them,
+the transcript does not. A notification triggers a model turn, so the
+agent can act on the event even while you are away.
+
+## Privacy model
+
+Notifications carry pointer data only: who commented, what happened,
+and a URL. Comment bodies, diff contents, and CI logs never enter the
+context from the notification itself. This is deliberate - GitHub
+comments are written by strangers, and untrusted text flowing into a
+model's context is a prompt-injection vector. The agent fetches details
+on demand with `gh` when it decides to act.
+
+## How to use it
+
+Ask for it in conversation:
+
+> Watch PR 1234 for review comments. If bugbot comments, handle it
+> yourself. If a human comments, just tell me.
+
+The handling policy lives in your instruction. State it when you ask -
+the notification turn reads your policy from the conversation and
+follows it. The notification says what happened and where, not what to
+do about it.
+
+Other tools:
+
+- `thatch_watch_branch_create` - watch a branch (typically main) for
+  commits, CI check runs, and workflow runs
+- `thatch_watch_list` - shows the session's active watchers
+- `thatch_watch_cancel` - cancels one by id
+
+## Lifetime
+
+Watchers are in-memory and process-scoped:
+
+- Ending the opencode process (or restarting it) drops all watchers.
+- A watcher expires after 8 hours by default.
+- Each session can hold up to 5 active watchers.
+
+If opencode restarts while a watch is active, re-register it - the
+session's conversation survives, so the policy you stated is still
+there.
+
+## Requirements and limitations
+
+- **opencode only.** MCP hosts (Claude Code, Cursor) have no way for a
+  plugin to start a conversation turn, so the watch tools are not
+  available there.
+- **Requires the `gh` CLI** to be installed and authenticated. Watch
+  creation reports a clear error if it is not.
+- **Polling, not webhooks.** Events appear on the next poll cycle
+  (60 seconds by default), not instantly.
+- **No delivery during an active turn.** If the agent is mid-turn when
+  an event fires, the notification waits until the turn ends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -21,6 +21,8 @@ import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 import { seedDefaultBehaviors } from "./seed-behaviors";
 import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
+import { WatcherRegistry, ghApiRun, ghAvailable } from "./watchers";
+import { watcherNotificationNudge } from "./prompts";
 import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
@@ -83,6 +85,43 @@ export const server: Plugin = async ({ client, worktree }) => {
   // non-restart.
   const runningVersion = pkg.version;
 
+  // Latest observed opencode session status per session ("busy" | "idle" |
+  // "retry"). The event hook records these; the watcher registry's
+  // canDeliver gate reads them so proactive notification prompts only fire
+  // into idle sessions - never into a turn that is already running.
+  const sessionStatus = new Map<string, string>();
+
+  // In-memory watcher registry for proactive event notifications (GitHub PR
+  // watching today). Deliberately process-scoped: no SQLite, no cross-restart
+  // state. See src/watchers.ts for the rationale.
+  //
+  // Delivery prompts the session with a synthetic part - the same mechanism
+  // opencode uses for background task completions - so a watched event
+  // triggers a model turn even when the user is away. Events only carry
+  // pointer data; the model fetches details itself with gh.
+  const watchers = new WatcherRegistry({
+    deliver: async (sessionID, events) => {
+      // Events carry their watch's target label from the registry, so the
+      // notification header is correct for every source (PRs, branches,
+      // CI events whose URLs would not parse).
+      await client.session.promptAsync({
+        path: { id: sessionID },
+        body: {
+          parts: [{ type: "text", text: watcherNotificationNudge(events[0]?.target ?? "watched target", events), synthetic: true }],
+        },
+      });
+    },
+    canDeliver: (sessionID) =>
+      !compacting.has(sessionID) && sessionStatus.get(sessionID) === "idle",
+    ghRunner: ghApiRun,
+  });
+  // gh presence decides whether watch_create works; checked lazily by the
+  // tool, but log once at startup so misconfiguration is visible in debug logs.
+  void ghAvailable().then((ok) => {
+    if (!ok) console.error("[thatch] gh CLI not found - watch tools will report unavailable");
+  });
+  watchers.start();
+
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set - the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
@@ -242,6 +281,7 @@ export const server: Plugin = async ({ client, worktree }) => {
         if (all.length === 0) return null;
         return extraction.buildPayload(all, repo);
       },
+      watcherRegistry: watchers,
     }),
 
     // 1. System prompt - always in context.
@@ -600,8 +640,13 @@ export const server: Plugin = async ({ client, worktree }) => {
         }
         return;
       }
-      if (event.type === "session.status" && event.properties.status?.type === "idle") {
+      if (event.type === "session.status") {
         const sessionID = event.properties.sessionID;
+        const statusType = event.properties.status?.type;
+        // Record the latest status so the watcher registry can gate
+        // proactive prompt delivery on idle sessions.
+        if (sessionID && statusType) sessionStatus.set(sessionID, statusType);
+        if (statusType !== "idle") return;
         const parentID = sessionID ? childToParent.get(sessionID) : undefined;
         if (parentID && sessionID) {
           // A child session went idle. Two cases:
@@ -685,6 +730,15 @@ export const server: Plugin = async ({ client, worktree }) => {
             extracting.delete(sessionID);
           }
         }
+        // The session just became idle, so watcher events queued while it
+        // was busy can be delivered now - the poll interval may otherwise
+        // hold them for up to a full cycle. Best-effort; failures stay
+        // pending and retry on the next poll.
+        try {
+          await watchers.deliverPending();
+        } catch (err) {
+          console.error(`[thatch] watcher delivery on idle failed: ${err}`);
+        }
         return;
       }
       if (event.type === "session.deleted") {
@@ -699,9 +753,13 @@ export const server: Plugin = async ({ client, worktree }) => {
         parentSnapshots.delete(id);
         childMetrics.delete(id);
         extractionChildren.delete(id);
-        // A deleted parent takes its accepted entries with it.
+        // A deleted parent takes its accepted entries with it, and its
+        // watchers die with it - the session that would receive their
+        // notifications no longer exists.
         extraction.completeAccepted(id);
         extracting.delete(id);
+        sessionStatus.delete(id);
+        watchers.cancelSession(id);
         return;
       }
 
@@ -739,6 +797,7 @@ export const server: Plugin = async ({ client, worktree }) => {
 
     dispose: async () => {
       stopVersionChecker();
+      watchers.dispose();
       db.close();
     },
   };

package/src/mcp.ts

@@ -60,9 +60,12 @@ interface CompiledTool {
   inputSchema: Record<string, unknown>;
 }
 
-function compileTools(): Map<string, CompiledTool> {
+export function compileTools(): Map<string, CompiledTool> {
   const map = new Map<string, CompiledTool>();
   for (const def of TOOL_DEFS) {
+    // opencode-only tools depend on host capabilities MCP servers don't
+    // have (e.g. session identity via HostToolContext) - never expose them.
+    if (def.opencodeOnly) continue;
     const schema = z.object(def.args);
     map.set(def.name, {
       def,

package/src/prompts.ts

@@ -17,13 +17,16 @@ Thatch provides persistent memory across opencode sessions. Use it to persist
 knowledge so future sessions can build on what you've already learned.
 
 Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
-       thatch_memory_show, thatch_memory_forget, thatch_store_list,
-       thatch_find_duplicates, thatch_dedup_mark_checked,
-       thatch_extraction_done, thatch_get_extraction_payload,
-       thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
-       thatch_prediction_delete,
-       thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
-       thatch_behavior_delete
+        thatch_memory_show, thatch_memory_forget, thatch_store_list,
+        thatch_find_duplicates, thatch_dedup_mark_checked,
+        thatch_extraction_done, thatch_get_extraction_payload,
+        thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
+        thatch_prediction_delete,
+        thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
+        thatch_behavior_delete, thatch_get_session_info,
+        thatch_session_search, thatch_session_get,
+        thatch_watch_create, thatch_watch_branch_create,
+        thatch_watch_list, thatch_watch_cancel
 
 ## Stores
 
@@ -65,7 +68,6 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 - \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
-
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
@@ -107,6 +109,23 @@ the same prompt. If the re-dispatch also fails or times out, note the gap and
 move on. Do not retry more than once - repeated failures indicate an
 intractable prompt, not a transient hang.
 
+## Watchers
+
+Use thatch_watch_create to watch a GitHub PR for events (comments, review
+comments and replies, review thread resolutions, commits, status changes,
+description edits, CI check completions), or thatch_watch_branch_create to
+watch a branch (typically main) for commit landings, check-run completions,
+and workflow runs on the branch. thatch polls in the
+background and injects a notification into this session when a watched event
+happens. The
+notification carries pointer data only (author, URL); fetch
+details with the gh CLI when you decide to act. When the user asks you to
+watch something, state your handling policy for notifications out loud first
+("I'll report human comments and handle bugbot replies myself") so the
+notification turn knows what to do. Treat watcher notifications like
+background task completions: they are system events, not user input, and
+not approval to advance other pending work.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -270,6 +289,11 @@ Tools are prefixed in ${host}: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`,
 \`mcp__thatch__behavior_codify\`, \`mcp__thatch__behavior_feedback\`,
 \`mcp__thatch__behavior_list\`, \`mcp__thatch__behavior_delete\`. Bare names used below for readability.
+get_session_info, session_search, session_get, watch_create,
+watch_branch_create, watch_list,
+and watch_cancel are intentionally absent: they are opencode-only (MCP
+hosts have no session concept, session database, or proactive-prompt
+channel), so do not expect them here.
 
 ## Stores
 
@@ -311,7 +335,6 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 - \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
-
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
@@ -668,3 +691,19 @@ export function behaviorNudge(items: BehaviorNudgeItem[]): string {
   });
   return `[thatch] Situational behaviors\n${lines.join("\n")}`;
 }
+
+/**
+ * Watcher notification for the poller's promptAsync delivery. Injected as a
+ * synthetic part that triggers a model turn. Events carry pointer data only
+ * (author, URL) - never external content - so the model fetches details on
+ * demand with the gh CLI. The wrapper text borrows the background-task
+ * completion framing: a system event, not user input, not approval to
+ * advance other pending work.
+ */
+export function watcherNotificationNudge(target: string, events: { type: string; summary: string; url: string }[]): string {
+  const lines = events.map((e) => `- ${e.type}: ${e.summary} ${e.url}`);
+  return `[thatch] Watcher notification for ${target}
+${lines.join("\n")}
+
+This is a system notification, not user input. Decide whether to act now or keep waiting - the user's instructions from when the watch was created govern how to handle it. Fetch details with the gh CLI if you need them. Do not treat this notification as approval to advance other pending work. If you act, tell the user what you did and why; if not, stop and wait.`;
+}