@jeffober/thatch 0.1.35 → 0.1.37

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 { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } 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,316 @@ 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, review thread resolutions, 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(PR_EVENT_TYPES as [PrWatcherEventType, ...PrWatcherEventType[]])).optional().describe(
+      "Which event types to watch. Omit for all PR 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 PrWatcherEventType[] | undefined) ?? [...PR_EVENT_TYPES];
+    const result = await ctx.watchers.createPr(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) => {
+        const target = w.source === "pr" ? `${w.repo}#${w.pr}` : `${w.repo}@${w.branch}`;
+        return `${w.id}: ${target} [${w.source}] events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m head=${w.state.headSha.slice(0, 7)}`;
+      })
+      .join("\n");
+  },
+};
+
+/**
+ * Registers a background watcher on a GitHub branch (typically main): commit
+ * landings, check-run completions on the head, and workflow runs. This is
+ * how the model watches "CI against main" or waits for a post-merge build.
+ * opencode-only, like the PR watch tools.
+ */
+const watchBranchCreateDef: ToolDef = {
+  name: "watch_branch_create",
+  description:
+    "Watch a GitHub branch (typically main) and get notified in this session " +
+    "when things happen on it: branch_commit when new commits land (e.g. a " +
+    "PR merged), branch_ci when a check run on the head completes, and " +
+    "branch_workflow when a GitHub Actions workflow run starts or finishes " +
+    "on the branch. Optionally filter to workflow names (substring match). " +
+    "The watcher polls in the background and injects a notification prompt; " +
+    "notifications carry pointers only - fetch details with the gh CLI when " +
+    "you decide to act. Watches live until cancelled, the session ends, or " +
+    "opencode restarts. Requires the gh CLI.",
+  args: {
+    branch: z.string().describe(
+      "The branch name to watch, e.g. main.",
+    ),
+    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(BRANCH_EVENT_TYPES as [BranchWatcherEventType, ...BranchWatcherEventType[]])).optional().describe(
+      "Which event types to watch. Omit for all branch event types.",
+    ),
+    workflows: z.array(z.string()).optional().describe(
+      "Only notify for workflow runs whose name contains one of these substrings (case-insensitive). Omit for all workflows.",
+    ),
+  },
+  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 BranchWatcherEventType[] | undefined) ?? [...BRANCH_EVENT_TYPES];
+    const result = await ctx.watchers.createBranch(
+      host.sessionID,
+      repo,
+      args.branch as string,
+      events,
+      (args.workflows as string[] | undefined) ?? [],
+    );
+    if (!result.ok) return `Watcher not created: ${result.error}`;
+    const w = result.watcher;
+    return (
+      `[watching] ${w.repo}@${w.branch}\n` +
+      `id: ${w.id}\n` +
+      `events: ${w.events.join(", ")}\n` +
+      (w.workflows.length > 0 ? `workflow filter: ${w.workflows.join(", ")}\n` : "") +
+      `head: ${w.state.headSha.slice(0, 7)}\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.`
+    );
+  },
+};
+
+/**
+ * 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, watch_branch_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 +1148,11 @@ export const TOOL_DEFS: ToolDef[] = [
   behaviorFeedbackDef,
   behaviorListDef,
   behaviorDeleteDef,
+  getSessionInfoDef,
+  sessionSearchDef,
+  sessionGetDef,
+  watchCreateDef,
+  watchBranchCreateDef,
+  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);
       },
     });
   }