opencode-blackhole 0.0.0-stage → 0.1.0

package/src/memory/models.ts

@@ -0,0 +1,172 @@
+/**
+ * Worker model selection: fallback chains, per-model cooldowns and a retry
+ * gate.
+ *
+ * The rules mirror pi-blackhole:
+ *  - each worker has its own chain: primary → fallbacks → (session model, only
+ *    when `sessionFallback` is on);
+ *  - a model that fails gets a cooldown and is skipped on later attempts;
+ *  - a transient failure (rate limit, timeout, an upstream error under a
+ *    router) is retried once and cooled down briefly, because it says nothing
+ *    about the model a minute later;
+ *  - a failed stage is skipped, never escalated to a paid model by accident;
+ *  - the coverage cursor never advances past what a worker actually saw.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { ModelRef } from "../config"
+
+export interface CooldownEntry {
+  until: number
+  reason: string
+}
+
+export class CooldownStore {
+  private readonly path: string
+  private state: Record<string, CooldownEntry> = {}
+
+  constructor(dir: string) {
+    this.path = join(dir, "cooldowns.json")
+    try {
+      if (existsSync(this.path)) this.state = JSON.parse(readFileSync(this.path, "utf8"))
+    } catch {
+      this.state = {}
+    }
+  }
+
+  static key(model: ModelRef): string {
+    return `${model.providerID}/${model.id}`
+  }
+
+  active(model: ModelRef, now = Date.now()): CooldownEntry | undefined {
+    const entry = this.state[CooldownStore.key(model)]
+    if (!entry) return undefined
+    if (entry.until <= now) {
+      delete this.state[CooldownStore.key(model)]
+      return undefined
+    }
+    return entry
+  }
+
+  cool(model: ModelRef, reason: string, seconds: number, now = Date.now()) {
+    this.state[CooldownStore.key(model)] = { until: now + seconds * 1000, reason }
+    this.persist()
+  }
+
+  private persist() {
+    try {
+      writeFileSync(this.path, JSON.stringify(this.state, null, 2))
+    } catch {
+      // Cooldowns are an optimization; failing to persist them is not fatal.
+    }
+  }
+}
+
+/** Errors worth retrying on another model rather than skipping the stage. */
+const RETRYABLE =
+  /rate.?limit|429|too many requests|timeout|timed out|overload|503|502|500|bad gateway|service unavailable|fetch failed|econn|network|stream (?:error|closed)|aborted|finish_reason:?\s*error|provider reported an error/i
+
+/**
+ * How long a transient failure is cooled down for.
+ *
+ * A rate limit, a timeout or an upstream error under a router says nothing
+ * about whether the model will work in a minute. Cooling it for the full hour
+ * turns one bad request into an hour of missing memory.
+ */
+export const TRANSIENT_COOLDOWN_SECONDS = 180
+
+/**
+ * A model the catalog does not know.
+ *
+ * Cooling such a model down would only clutter the store: it will still be
+ * missing next time. Upstream skips it for the same reason.
+ */
+const UNKNOWN_MODEL = /model .*(not found|does not exist|not available|unavailable|unknown)|no such model|model_not_found|modelselectionerror/i
+
+export const isRetryable = (error: unknown): boolean => {
+  const text = error instanceof Error ? `${error.message} ${error.stack ?? ""}` : String(error)
+  return RETRYABLE.test(text)
+}
+
+/** True when the model itself is unknown to the provider catalog. */
+export const isUnknownModel = (error: unknown): boolean => {
+  const text = error instanceof Error ? `${error.message} ${error.stack ?? ""}` : String(error)
+  return UNKNOWN_MODEL.test(text)
+}
+
+export interface RunResult {
+  text: string
+  model: ModelRef
+  /** Models that were tried and failed before this one. */
+  skipped: ModelRef[]
+}
+
+export interface RunOptions {
+  models: ModelRef[]
+  prompt: string
+  /** Called for each model attempt. */
+  call: (model: ModelRef, prompt: string) => Promise<string>
+  /** The session's model, used only when `sessionFallback` is on. */
+  sessionModel?: ModelRef
+  sessionFallback?: boolean
+  cooldowns: CooldownStore
+  /** How long a failed model stays in cooldown. */
+  cooldownSeconds: number
+  onAttempt?: (model: ModelRef) => void
+  onFailure?: (model: ModelRef, error: unknown, retryable: boolean) => void
+}
+
+/**
+ * Try each model in the chain until one answers.
+ *
+ * A model in cooldown is skipped. Every failure moves on to the next
+ * candidate - including a deterministic one (bad credentials, an unknown
+ * model, a rejected payload), which upstream also cools down rather than
+ * burning every cycle on a model that cannot work. That is what makes the
+ * session model a real last resort: a dead worker credential falls through to
+ * it instead of ending the stage.
+ */
+export const runWithFallbacks = async (options: RunOptions): Promise<RunResult | undefined> => {
+  const chain = [...options.models]
+  if (options.sessionFallback && options.sessionModel) chain.push(options.sessionModel)
+
+  const skipped: ModelRef[] = []
+  for (const model of chain) {
+    const cooldown = options.cooldowns.active(model)
+    if (cooldown) {
+      skipped.push(model)
+      options.onFailure?.(model, new Error(`in cooldown: ${cooldown.reason}`), true)
+      continue
+    }
+    // One immediate retry for a transient failure. A router such as
+    // openrouter/free picks a provider per request, so the second call often
+    // lands somewhere else - cheaper than losing the whole stage.
+    for (let attempt = 0; ; attempt++) {
+      options.onAttempt?.(model)
+      try {
+        const text = await options.call(model, options.prompt)
+        return { text, model, skipped }
+      } catch (error) {
+        const retryable = isRetryable(error)
+        options.onFailure?.(model, error, retryable)
+        if (isUnknownModel(error)) {
+          // Not in the catalog: skip it, but do not cool it down - it will
+          // still be missing next time.
+          skipped.push(model)
+          break
+        }
+        if (retryable && attempt === 0) continue
+        // Deterministic failures cool for the full window; transient ones
+        // come back quickly instead of costing an hour of memory.
+        options.cooldowns.cool(
+          model,
+          String(error).slice(0, 200),
+          retryable ? Math.min(options.cooldownSeconds, TRANSIENT_COOLDOWN_SECONDS) : options.cooldownSeconds,
+        )
+        skipped.push(model)
+        break
+      }
+    }
+  }
+  return undefined
+}

package/src/memory/prompts.ts

@@ -0,0 +1,145 @@
+/**
+ * Worker prompts.
+ *
+ * The observer extracts timestamped facts from a slice of the conversation;
+ * the reflector distils those into durable insights. Both are asked for JSON
+ * so a small model can be parsed reliably — the models in play here are
+ * usually free ones.
+ */
+
+export const OBSERVER_PROMPT = `You extract durable facts from a coding session transcript.
+
+Read the transcript and list only the facts that will still matter later:
+- decisions the user made, and why ("chose Postgres over SQLite because of concurrent writes")
+- stated preferences and constraints ("never log request bodies", "always use pnpm")
+- work that was completed, and where it stands ("rate limiter added in src/ratelimit.ts")
+- problems hit and how they were resolved
+- things the user explicitly asked to remember
+
+Do NOT list:
+- the assistant's plans, questions or speculation
+- transient chatter, greetings, or restatements of the request
+- anything the transcript does not actually say
+
+Rules:
+- one fact per line, each a complete sentence
+- name files, commands and identifiers exactly as the transcript does
+- no numbering, no markdown, no preamble
+- if there is nothing durable, output nothing
+
+Reply with JSON only: {"observations": ["...", "..."]}`
+
+/**
+ * The observer's second pass.
+ *
+ * Upstream's observer runs an agent loop: it records a batch, reads the tool
+ * result back, and keeps working until the chunk is covered. OpenCode's
+ * plugin API has no tool loop, so the review happens as a second call
+ * instead: the draft comes back for correction, and the corrected list
+ * replaces it.
+ */
+export const OBSERVER_REFINE_PROMPT = `You review a draft of durable facts extracted from a coding session transcript.
+
+The draft was written in one pass and may be wrong. Check it against the
+transcript and return the corrected list.
+
+Fix these, in priority order:
+- facts the transcript states that the draft missed
+- facts the draft got wrong, or attributed to the wrong person
+- facts that are not durable: plans, speculation, transient chatter
+- wording that does not match the transcript (file names, commands, identifiers)
+
+Keep a draft fact when the transcript supports it. Do not invent facts, and
+do not drop a fact merely because it is not in the draft - the draft may
+simply have missed it.
+
+Rules:
+- one fact per line, each a complete sentence
+- name files, commands and identifiers exactly as the transcript does
+- no numbering, no markdown, no preamble
+- return the complete corrected list, not just the changes
+
+Reply with JSON only: {"observations": ["...", "..."]}`
+
+/**
+ * The dropper's proposal.
+ *
+ * Upstream's dropper asks a model which observations are safe to remove, then
+ * applies a deterministic ranker and cap to whatever the model proposed. This
+ * port does the same, minus the agent loop: one call returns the ids, and the
+ * deterministic rule still decides which of them actually go.
+ */
+export const DROPPER_PROMPT = `You decide which observations to remove from a session's compacted memory.
+
+These records are the ONLY information the assistant will have about past
+interactions once the raw conversation is compacted out of context. Dropping
+the wrong observation can make future work repeat, contradict, or misremember
+the user. Take this seriously.
+
+Your job is to identify only the safest active observations to remove. The
+default action is KEEP. When uncertain, keep the observation.
+
+What to drop, in priority order:
+- Paraphrase duplicates: two or more observations stating the same fact in
+  different words. Keep the newest or most detailed one; the pool should
+  carry each fact once.
+- Redundant observations whose meaning is already captured by a current
+  reflection.
+- Superseded observations where a later observation clearly replaces the older.
+- Repeated routine acknowledgements or low-signal progress updates that carry
+  no decisions, constraints, exact errors, or user-specific facts.
+- Older observations that no longer carry working context and are covered by a
+  reflection or a newer observation.
+
+Reflection coverage is evidence, not an automatic decision:
+- none: no current reflection cites this observation.
+- partial: one current reflection cites it.
+- strong: two or more current reflections cite it.
+
+Recent observations carry working context the assistant may still need. Age
+alone is not enough to drop an important or uniquely load-bearing observation.
+
+Return the ids of the observations you would drop. Return an empty list if
+nothing is safe to drop.
+
+Reply with JSON only: {"drop": ["...", "..."]}`
+
+export const REFLECTOR_PROMPT = `You distil a list of observations into durable reflections.
+
+A reflection is a stable insight that stays true across the session: a constraint,
+a preference, a pattern in how the user wants to work, a decision that shapes
+future work. It is not a restatement of one observation.
+
+Rules:
+- one reflection per line, a single complete sentence
+- keep the original wording of identifiers and file paths
+- no numbering, no markdown, no preamble
+- if nothing rises above the individual observations, output nothing
+
+Reply with JSON only: {"reflections": ["...", "..."]}`
+
+/** Parse a JSON object out of a model reply that may be wrapped in prose. */
+export const parseJson = <T>(text: string): T | undefined => {
+  if (!text) return undefined
+  const trimmed = text.trim()
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed)
+  const candidates = [fenced?.[1], trimmed]
+  for (const candidate of candidates) {
+    if (!candidate) continue
+    try {
+      return JSON.parse(candidate) as T
+    } catch {
+      // fall through to the brace-slice attempt
+    }
+    const start = candidate.indexOf("{")
+    const end = candidate.lastIndexOf("}")
+    if (start >= 0 && end > start) {
+      try {
+        return JSON.parse(candidate.slice(start, end + 1)) as T
+      } catch {
+        // try the next candidate
+      }
+    }
+  }
+  return undefined
+}

package/src/recall/recall.ts

@@ -0,0 +1,327 @@
+/**
+ * Recall for OpenCode.
+ *
+ * The vcc core ships the search, ranking and formatting; this module wires
+ * them to OpenCode's session transcript. OpenCode has no branch/lineage model
+ * that a plugin can see, so scope handling is simplified: the transcript is
+ * the whole session, and `scope:'all'` is accepted for compatibility.
+ */
+import { expandEntryFile } from "../vcc/core/drill-down"
+import { formatRecallOutput, formatTouchedOutput, TOUCHED_PAGE_SIZE } from "../vcc/core/format-recall"
+import { loadMessages, type LoadedMessages } from "../vcc/load-messages"
+import {
+  parseCommandRequest,
+  parseToolRequest,
+  type RecallRequest,
+  type RecallToolParams,
+} from "../vcc/core/recall-request"
+import { getTouchedFiles, searchEntriesDetailed, type SearchHit } from "../vcc/core/search-entries"
+import type { TranscriptStore } from "../store/transcript"
+
+const SEARCH_PAGE_SIZE = 5
+const RANGE_PAGE_SIZE = 20
+const RECENT_COUNT = 25
+const PAIRED_RESULT_CHARS = 4000
+const WRITES_FILE = /write|edit|patch/i
+
+/**
+ * A recall response has a character budget.
+ *
+ * One stored message can be enormous (a file read, a long command output), and
+ * a recall that returns it verbatim would flood the context it was meant to
+ * help with. The budget is shared across the entries of a response, and each
+ * entry's lines share their slice of it — so a page of twenty small hits stays
+ * readable and one giant hit cannot swallow the page.
+ */
+export interface RecallOptions {
+  /** Maximum characters for the whole response. 0 disables the cap. */
+  maxChars: number
+}
+
+const clipText = (text: string, limit: number): string => {
+  if (limit <= 0 || text.length <= limit) return text
+  return `${text.slice(0, limit)}…[clipped ${text.length - limit} chars]`
+}
+
+/** Share the response budget across the entries, and each entry's lines. */
+const clipEntries = <T extends { summary: string; snippet?: string }>(
+  entries: T[],
+  budget: number,
+): T[] => {
+  if (budget <= 0 || entries.length === 0) return entries
+  const perEntry = Math.max(200, Math.floor(budget / entries.length))
+  return entries.map((entry) => {
+    const body = entry.snippet ?? entry.summary
+    if (body.length <= perEntry) return entry
+    // Give every line of the entry a slice, so one long line cannot take it
+    // all and the rest of the entry stays visible.
+    const lines = body.split("\n")
+    const perLine = Math.max(80, Math.floor(perEntry / Math.max(1, lines.length)))
+    const clipped = lines.map((line) => clipText(line, perLine)).join("\n")
+    const next = { ...entry, summary: clipText(clipped, perEntry) }
+    if (entry.snippet !== undefined) next.snippet = clipText(clipped, perEntry)
+    return next
+  })
+}
+
+/** The last line of defence: the formatted response itself never exceeds the budget. */
+const clipResponse = (text: string, budget: number): string => {
+  if (budget <= 0 || text.length <= budget) return text
+  return `${text.slice(0, budget)}\n…[response clipped at ${budget} of ${text.length} chars]`
+}
+
+/**
+ * Rendered views are cached per session.
+ *
+ * Rendering the transcript means summarizing every message, which is wasted
+ * work when the same session is recalled several times and nothing was
+ * captured in between. The store's version counter tells us when to rebuild.
+ * The cache is capped, so it cannot become a second copy of every session.
+ */
+const VIEW_CACHE_SIZE = 4
+const viewCache = new Map<string, { version: number; full: boolean; view: LoadedMessages }>()
+
+const view = (store: TranscriptStore, sessionID: string, full: boolean): LoadedMessages => {
+  const transcript = store.read(sessionID)
+  const cached = viewCache.get(sessionID)
+  if (cached && cached.version === transcript.version && cached.full === full) {
+    viewCache.delete(sessionID)
+    viewCache.set(sessionID, cached)
+    return cached.view
+  }
+  const result = loadMessages(
+    transcript.messages.map((entry) => entry.message),
+    full,
+  )
+  viewCache.delete(sessionID)
+  viewCache.set(sessionID, { version: transcript.version, full, view: result })
+  while (viewCache.size > VIEW_CACHE_SIZE) {
+    const oldest = viewCache.keys().next().value
+    if (oldest === undefined) break
+    viewCache.delete(oldest)
+  }
+  return result
+}
+
+const ignoredNote = (request: RecallRequest): string => {
+  const reasons: Record<string, string> = {
+    drill: "a #N:path query runs alone",
+    touched: "mode:'touched' runs alone",
+    expand: "expand runs alone; send the rest in a separate call",
+    range: "range runs alone; send the rest in a separate call",
+    search: "",
+    recent: "page applies to query or range results",
+  }
+  return (request.dropped?.length ? `Ignored: ${request.dropped.join(", ")}.\n\n` : "") +
+    (request.ignored?.length ? `Ignored: ${request.ignored.join(", ")} (${reasons[request.action.kind]}).\n\n` : "")
+}
+
+const runExpand = (
+  indices: number[],
+  store: TranscriptStore,
+  sessionID: string,
+  options: RecallOptions,
+): string => {
+  const { rendered, rawMessages } = view(store, sessionID, true)
+  const invalid = indices.filter((i) => !rendered.some((m) => m.index === i))
+  if (invalid.length > 0) return `Cannot expand indices outside session history: ${invalid.join(", ")}`
+
+  const out: SearchHit[] = []
+  for (const index of indices) {
+    const pos = rendered.findIndex((m) => m.index === index)
+    if (pos < 0) continue
+    const entry = rendered[pos]
+    out.push(entry)
+
+    // Bring the tool results of an expanded call along, so the agent does not
+    // have to know the result sits at a later #N.
+    const raw = rawMessages[pos] as any
+    const ids = new Set<string>(
+      Array.isArray(raw?.content)
+        ? raw.content
+            .filter((part: any) => part?.type === "toolCall" && typeof part.id === "string")
+            .map((part: any) => part.id)
+        : [],
+    )
+    if (ids.size === 0) continue
+    for (let j = pos + 1; j < rendered.length && ids.size > 0; j++) {
+      const result = rawMessages[j] as any
+      if (result?.role === "assistant") break
+      if (result?.role !== "toolResult" || !ids.has(result.toolCallId)) continue
+      ids.delete(result.toolCallId)
+      const res = rendered[j]
+      if (indices.includes(res.index)) continue
+      out.push({
+        ...res,
+        summary:
+          res.summary.length > PAIRED_RESULT_CHARS
+            ? `${res.summary.slice(0, PAIRED_RESULT_CHARS)}\n...[result of #${entry.index} clipped at ${PAIRED_RESULT_CHARS} of ${res.summary.length} chars; expand:[${res.index}] for all of it]`
+            : res.summary,
+      })
+    }
+  }
+
+  const header = `Expanded ${indices.map((i) => `#${i}`).join(", ")}`
+  return clipResponse(
+    formatRecallOutput(clipEntries(out, options.maxChars), undefined, header),
+    options.maxChars,
+  )
+}
+
+const runRange = (
+  range: unknown[],
+  page: number,
+  store: TranscriptStore,
+  sessionID: string,
+  options: RecallOptions,
+): string => {
+  const [from, to] = range
+  if (
+    range.length !== 2 ||
+    !Number.isInteger(from) ||
+    !Number.isInteger(to) ||
+    (from as number) < 0 ||
+    (from as number) > (to as number)
+  ) {
+    return `Invalid range ${JSON.stringify(range)}: use range:[from, to] with two #N indices, from <= to.`
+  }
+
+  const lo = from as number
+  const { rendered } = view(store, sessionID, false)
+  const entries = rendered.filter((m) => m.index >= lo && m.index <= (to as number))
+  if (entries.length === 0) {
+    const last = rendered[rendered.length - 1]
+    return `No messages #${lo}..#${to} in session history${last ? ` (last entry is #${last.index})` : ""}.`
+  }
+
+  const lastIndex = rendered[rendered.length - 1].index
+  const clamped = (to as number) > lastIndex
+  const hi = clamped ? lastIndex : (to as number)
+  const totalPages = Math.ceil(entries.length / RANGE_PAGE_SIZE)
+  const counts = `${entries.length} messages${clamped ? `, #${hi} is the last entry` : ""}`
+  if (page > totalPages) {
+    return `Page ${page} is outside the available range 1-${totalPages} (#${lo}..#${hi}: ${counts}). Use a page between 1 and ${totalPages}.`
+  }
+  const start = (page - 1) * RANGE_PAGE_SIZE
+  const header =
+    totalPages > 1 ? `Range #${lo}..#${hi}, page ${page}/${totalPages} (${counts})` : `Range #${lo}..#${hi} (${counts})`
+  const footer =
+    page < totalPages ? `\n--- Use range:[${lo}, ${hi}] page:${page + 1} for the next ${RANGE_PAGE_SIZE} ---` : ""
+  return (
+    clipResponse(
+      formatRecallOutput(
+        clipEntries(entries.slice(start, start + RANGE_PAGE_SIZE), options.maxChars),
+        undefined,
+        header,
+      ),
+      options.maxChars,
+    ) + footer
+  )
+}
+
+const runTouched = (
+  page: number | undefined,
+  store: TranscriptStore,
+  sessionID: string,
+  options: RecallOptions,
+): string => {
+  const { rendered, rawMessages } = view(store, sessionID, false)
+  const touched = getTouchedFiles(rawMessages, rendered)
+  const text = formatTouchedOutput(touched, page)
+  const start = (Math.max(1, page ?? 1) - 1) * TOUCHED_PAGE_SIZE
+  for (const file of touched.slice(start, start + TOUCHED_PAGE_SIZE)) {
+    const write = [...file.entries].reverse().find((entry) => WRITES_FILE.test(entry.toolName))
+    if (!write) continue
+    const name = file.path.replace(/\\/g, "/").split("/").pop()
+    return clipResponse(`${text}\n--- File content at an entry: query:'#${write.index}:${name}' ---`, options.maxChars)
+  }
+  return text
+}
+
+const runSearch = (
+  query: string,
+  page: number,
+  store: TranscriptStore,
+  sessionID: string,
+  options: RecallOptions,
+): string => {
+  const { rendered, rawMessages } = view(store, sessionID, false)
+  const { hits, totalBeforeCap, truncated } = searchEntriesDetailed(rendered, rawMessages, query)
+  const totalPages = Math.ceil(hits.length / SEARCH_PAGE_SIZE)
+  const truncationNote = truncated
+    ? ` — showing ${hits.length} of ${totalBeforeCap} matches, refine your query for more precise results`
+    : ""
+  if (hits.length > 0 && page > totalPages) {
+    return `Page ${page} is outside the available range 1-${totalPages} (${hits.length} matches${truncationNote}). Use a page between 1 and ${totalPages}.`
+  }
+  const start = (page - 1) * SEARCH_PAGE_SIZE
+  const pageHits = hits.slice(start, start + SEARCH_PAGE_SIZE)
+  const header =
+    totalPages > 1
+      ? `Page ${page}/${totalPages} (${hits.length} total matches${truncationNote})`
+      : `${hits.length} matches${truncationNote}`
+  const footer = page < totalPages ? `\n--- Next page: page:${page + 1} ---` : ""
+  return (
+    clipResponse(formatRecallOutput(clipEntries(pageHits, options.maxChars), query, header), options.maxChars) + footer
+  )
+}
+
+const runAction = (
+  request: RecallRequest,
+  store: TranscriptStore,
+  sessionID: string,
+  options: RecallOptions,
+): string => {
+  const { action } = request
+  switch (action.kind) {
+    case "drill": {
+      const { rendered } = view(store, sessionID, false)
+      const target = action.target
+      const offPath = !rendered.some((m) => m.index === target.index)
+      const messages = store.read(sessionID).messages.map((entry) => entry.message)
+      return clipResponse(
+        (offPath ? "Entry is not in the recorded session history.\n\n" : "") +
+          expandEntryFile(messages, target.index, target.pathPattern, target.full, target.offset, target.limit),
+        options.maxChars,
+      )
+    }
+    case "touched":
+      return runTouched(action.page, store, sessionID, options)
+    case "expand":
+      return runExpand(action.indices, store, sessionID, options)
+    case "range":
+      return runRange(action.range, action.page, store, sessionID, options)
+    case "search":
+      return runSearch(action.query, action.page, store, sessionID, options)
+    case "recent": {
+      const { rendered } = view(store, sessionID, false)
+      return clipResponse(
+        formatRecallOutput(clipEntries(rendered.slice(-RECENT_COUNT), options.maxChars), action.query),
+        options.maxChars,
+      )
+    }
+  }
+}
+
+export const runRecall = (
+  store: TranscriptStore,
+  sessionID: string,
+  request: RecallRequest,
+  options: RecallOptions = { maxChars: 0 },
+): string => ignoredNote(request) + runAction(request, store, sessionID, options)
+
+/** Run a recall from tool parameters. */
+export const runRecallTool = (
+  store: TranscriptStore,
+  sessionID: string,
+  params: RecallToolParams,
+  options: RecallOptions = { maxChars: 0 },
+): string => runRecall(store, sessionID, parseToolRequest(params), options)
+
+/** Run a recall from a command's argument string. */
+export const runRecallCommand = (
+  store: TranscriptStore,
+  sessionID: string,
+  args: string,
+  options: RecallOptions = { maxChars: 0 },
+): string => runRecall(store, sessionID, parseCommandRequest(args), options)

package/src/state/paths.ts

@@ -0,0 +1,42 @@
+/**
+ * Where the plugin keeps its state.
+ *
+ * The state lives next to OpenCode's own data, in the user's home directory,
+ * not inside the project — a project's transcript is derived data (OpenCode
+ * already stores the same messages in the session record), and it has no
+ * business in a repository.
+ *
+ *     ~/.local/share/opencode/blackhole/<projectID>/
+ *       transcripts/<sessionID>.jsonl
+ *       memory/<sessionID>.jsonl
+ *
+ * The per-project folder is keyed by OpenCode's `projectID`, not by the
+ * directory path: the id survives moving or renaming a project, the path does
+ * not.
+ */
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/** The root of the plugin's state, next to OpenCode's own data. */
+export const stateBase = (): string => join(homedir(), ".local", "share", "opencode", "blackhole")
+
+/** The state folder of one project. */
+export const projectStateDir = (base: string, projectID: string): string => join(base, projectID)
+
+/** A stable short id for a directory, used when a project id is unavailable. */
+export const directoryKey = (directory: string): string =>
+  `dir-${createHash("sha1").update(directory).digest("hex").slice(0, 12)}`
+
+/** The project folders that exist under the base. */
+export const listProjectDirs = (base: string): string[] => {
+  try {
+    if (!existsSync(base)) return []
+    return readdirSync(base, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(base, entry.name))
+  } catch {
+    return []
+  }
+}