geneseed 2.0.0

package/adapters/opencode/plugins/geneseed-learn.js

@@ -0,0 +1,396 @@
+// Geneseed — OpenCode learn plugin.
+//
+// The runtime-agnostic counterpart of the Claude Code `Stop` hook: on
+// `session.idle` it distils durable memories from the conversation and writes them
+// into the bundle's memory/ dir, maintaining MEMORY.md — exactly what the harness's
+// own `learn` verb does, but self-contained in this plugin so no separate process and
+// no model CLI are required. It distils with the SAME model the session already used
+// (read from the transcript), so it inherits your OpenCode provider config: no API
+// key, nothing to set for the model.
+//
+// TIMING — `session.idle` fires after EVERY turn (it is OpenCode's "session became
+// idle / response ready" signal), not only at the true end of a session. Distilling
+// on the first idle would therefore mine just turn 1 and miss the rest. So each idle
+// RE-ARMS a debounce timer (GENESEED_LEARN_DEBOUNCE_MS, default 60s) and the distil
+// runs once the session has been quiet for that long — i.e. at the real end. A
+// continued session simply re-arms and re-distils; slug dedup keeps writes
+// idempotent. (Trade-off: if OpenCode is killed inside the window the final distil
+// is lost — still strictly better than capturing only turn 1, and far cheaper than
+// re-distilling every turn.)
+//
+// Install (global — the bundle is used everywhere, so the plugin should be too):
+//   copy this file to  ~/.config/opencode/plugins/geneseed-learn.js
+// Or per-project: .opencode/plugins/geneseed-learn.js  (build --emit opencode
+// drops it there for you).
+//
+// Where it writes — first match wins:
+//   1. $GENESEED_MEMORY            an explicit memory dir
+//   2. $GENESEED_HARNESS/memory    (or /anamnesis for the imperial theme)
+//   3. ./memory  or  ./Harness/memory   (when the bundle is inside the project)
+// If none resolve, it logs once and does nothing — it never blocks a session.
+//
+// It is intentionally conservative: trivial sessions are skipped, each session is
+// processed at most once per process, and any error is swallowed.
+
+import { promises as fs } from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+import { homedir } from "node:os"
+
+// The plugin's own directory. In the global install the layout is
+// <cfg>/plugins/geneseed-learn.js beside <cfg>/memory, so the store can be found
+// relative to this file — no manual `export GENESEED_HARNESS` needed.
+const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url))
+
+// Sovereign-repo bypass — twin of the harness's own `sovereignBypass()`.
+// <cfg>/excludes.json (user-owned, managed by `harness exclude`) lists folders where
+// this GLOBAL install goes dormant. Any error degrades to "not excluded".
+const norm = (p) => {
+  // Expand a leading "~" / "~/…" to the home dir — a hand-edited excludes.json entry
+  // like "~/vault" must resolve the same way here as it does for the Claude/Bob
+  // hook guard.
+  let raw = String(p)
+  if (raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\")) {
+    raw = raw === "~" ? homedir() : path.join(homedir(), raw.slice(2))
+  }
+  let s = path.resolve(raw)
+  return process.platform === "win32" ? s.toLowerCase() : s
+}
+async function sovereignBypass(cwd) {
+  try {
+    const cfg = path.dirname(PLUGIN_DIR)           // plugins/ sits directly in <cfg>
+    const raw = await fs.readFile(path.join(cfg, "excludes.json"), "utf8")
+    const entries = (JSON.parse(raw).excludes) || []
+    const here = norm(cwd || process.cwd())
+    for (const e of entries) {
+      const p = typeof e === "string" ? e : e && e.path
+      if (typeof p !== "string" || !p.trim()) continue
+      const base = norm(p.trim()).replace(/[\\/]+$/, "")
+      if (here === base || here.startsWith(base + path.sep)) return true
+    }
+  } catch { /* degrade to active */ }
+  return false
+}
+
+const MAX_NOTES_CHARS = 16000          // cap the prompt; keep the most recent tail
+const MIN_NOTES_CHARS = 200            // below this, the session is too trivial to mine
+const MEMORY_DIR_NAMES = ["memory", "anamnesis"]   // neutral + imperial
+// NaN-safe: garbage in the env var would make setTimeout fire immediately (NaN
+// delay → 0), distilling after EVERY turn instead of at session end.
+const _debounceRaw = Number(process.env.GENESEED_LEARN_DEBOUNCE_MS || 60000)
+const DEBOUNCE_MS = Number.isFinite(_debounceRaw) && _debounceRaw >= 0 ? _debounceRaw : 60000
+
+// SINGLE SOURCE of the distil instructions: the harness extracts this exact
+// LEARN_PROMPT_HEAD template literal at runtime, so there is nothing to keep in sync.
+const LEARN_PROMPT_HEAD = `You are distilling durable memories from the notes below. Output zero or more
+Markdown memory files in this exact format, separated by a line containing only
+'---FILE---':
+
+---
+name: <kebab-case-slug>
+description: <one-line summary>
+type: user | feedback | project | reference
+---
+<the fact, stated plainly. For 'feedback' and 'project', add **Why:** and
+**How to apply:** lines.>
+
+DEFAULT TO 'NOTHING'. Writing a memory is the rare exception, not the norm — most
+sessions should yield zero. Emit AT MOST ONE, and only if it is a GENERAL, reusable
+principle you would want at the START of an unrelated future task.
+
+CAPTURE only (high altitude, cross-session):
+  - a stable USER preference or working style the user showed or stated;
+  - a CONVENTION or constraint that will hold across many future tasks;
+  - a durable PROJECT decision or goal that outlives this session.
+
+NEVER capture (this is the noise to cut):
+  - what was done, found, fixed, or resolved this session ("fixed X", "resolved
+    issue 7", "cleaned up the TODO", "renamed Y", "the landing screen redirects");
+  - anything tied to one file, function, ticket, bug, or feature;
+  - anything derivable from the code, the git history, or the current diff.
+
+If you can only phrase it as "this session we …", it is NOT a memory:
+  - Too specific:  "Fixed the failing test by adding await on line 42."
+  - Right (meta):  "User wants async setup helpers always awaited."
+  - Too specific:  "Resolved the magic-constants issue in config.js."  -> NO memory
+    (a closed task, not a durable lesson).
+
+When in doubt, output exactly: NOTHING.`
+
+async function isDir(p) {
+  try { return (await fs.stat(p)).isDirectory() } catch { return false }
+}
+
+async function resolveMemoryDir() {
+  const env = process.env.GENESEED_MEMORY
+  if (env && (await isDir(env))) return env
+  const harness = process.env.GENESEED_HARNESS
+  const bases = []
+  if (harness) bases.push(harness)
+  // The plugin's own dir (global install: <cfg>/plugins → <cfg>/memory) and the repo.
+  bases.push(path.resolve(PLUGIN_DIR, ".."), process.cwd(), path.join(process.cwd(), "Harness"))
+  for (const base of bases) {
+    for (const name of MEMORY_DIR_NAMES) {
+      const cand = path.join(base, name)
+      if (await isDir(cand)) return cand
+    }
+  }
+  return null
+}
+
+function partsText(parts) {
+  return (parts || [])
+    .filter((p) => p && p.type === "text" && typeof p.text === "string")
+    .map((p) => p.text)
+    .join("\n")
+}
+
+// ---- per-agent memory (memory/agents/<name>.md) ------------------------------
+// Child subagent sessions are task fragments — never mined into the main store —
+// but a lesson about how the *agent* should operate next time is durable. Kept
+// deliberately conservative, like the rest of this plugin: an unresolvable agent
+// name skips entirely. The harness's own twin is behaviour-identical
+// so claude/bob get the same loop via their Stop/SubagentStop hooks.
+const AGENT_NAME_RE = /^[a-z][a-z0-9-]{1,40}$/
+const MAX_AGENT_BULLETS = 100 // hard cap, oldest dropped; no pruning heuristics
+
+// SINGLE SOURCE — the harness extracts this exact literal (see LEARN_PROMPT_HEAD).
+export const AGENT_LESSON_PROMPT = `The notes below are one subagent dispatch ("agent run").
+Output AT MOST ONE line: a durable lesson about how this agent should operate on a
+FUTURE, unrelated dispatch (a boundary that proved wrong, an input it always needs,
+a method that worked). Task residue ("fixed X", file names, ticket detail) is NOT a
+lesson. If there is none — the overwhelmingly common case — output exactly: NOTHING.`
+
+export function resolveAgentName(meta) {
+  const raw = meta?.agent ?? meta?.agentName ?? meta?.agentID ?? null
+  const name = typeof raw === "string" ? raw.trim().toLowerCase() : null
+  return name && AGENT_NAME_RE.test(name) ? name : null
+}
+
+export async function appendAgentLesson(memDir, agent, lesson) {
+  const dir = path.join(memDir, "agents")
+  await fs.mkdir(dir, { recursive: true })
+  const file = path.join(dir, `${agent}.md`)
+  let bullets = []
+  try {
+    bullets = (await fs.readFile(file, "utf8")).split("\n").filter((l) => l.startsWith("- "))
+  } catch { /* first lesson for this agent */ }
+  const day = new Date().toISOString().slice(0, 10)
+  bullets.push(`- ${day}: ${lesson.replace(/\s+/g, " ").trim()}`)
+  bullets = bullets.slice(-MAX_AGENT_BULLETS)
+  await fs.writeFile(file, `# ${agent} — lessons\n` + bullets.join("\n") + "\n", "utf8")
+  return file
+}
+
+// Flatten a session's messages into "role: text" notes, and pick the model the
+// session actually used so we distil with the user's own provider config.
+function flatten(messages) {
+  const lines = []
+  let model = null
+  for (const m of messages) {
+    const info = m?.info ?? {}
+    const role = info.role
+    if (role !== "user" && role !== "assistant") continue
+    const text = partsText(m?.parts).trim()
+    if (text) lines.push(`${role}: ${text}`)
+    if (role === "assistant") {
+      const providerID = info.providerID ?? info.provider
+      const modelID = info.modelID ?? info.model
+      if (providerID && modelID) model = { providerID, modelID }
+    }
+  }
+  return { notes: lines.join("\n\n"), model }
+}
+
+function envModel() {
+  const v = process.env.GENESEED_MODEL // "provider/model"
+  if (v && v.includes("/")) {
+    const [providerID, ...rest] = v.split("/")
+    return { providerID, modelID: rest.join("/") }
+  }
+  return null
+}
+
+async function existingSlugs(memDir) {
+  const skip = new Set(["memory", "readme"])
+  try {
+    const entries = await fs.readdir(memDir)
+    return new Set(
+      entries
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => f.slice(0, -3))
+        .filter((s) => !skip.has(s.toLowerCase()))
+    )
+  } catch {
+    return new Set()
+  }
+}
+
+function buildPrompt(notes, existing) {
+  const parts = [LEARN_PROMPT_HEAD, ""]
+  if (existing.size) {
+    parts.push(
+      "ALREADY STORED — do NOT emit a memory matching any of these slugs " +
+        "(skip updates too; only genuinely new facts):"
+    )
+    for (const slug of [...existing].sort()) parts.push(`- ${slug}`)
+    parts.push("")
+  }
+  parts.push("NOTES:", notes)
+  return parts.join("\n")
+}
+
+function parseFrontmatter(chunk) {
+  const m = chunk.match(/^\s*---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/)
+  if (!m) return {}
+  const fm = {}
+  for (const line of m[1].split("\n")) {
+    const i = line.indexOf(":")
+    if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^"|"$/g, "")
+  }
+  return fm
+}
+
+async function writeMemories(output, memDir, existing) {
+  const written = []
+  const indexLines = []
+  for (let chunk of output.split(/^---FILE---\s*$/m)) {
+    chunk = chunk.trim()
+    if (!chunk || chunk.toUpperCase() === "NOTHING") continue
+    const fm = parseFrontmatter(chunk)
+    const name = (fm.name || "").trim()
+    if (!name || existing.has(name)) continue
+    await fs.writeFile(path.join(memDir, `${name}.md`), chunk.replace(/\n+$/, "") + "\n", "utf8")
+    existing.add(name)
+    written.push(name)
+    const desc = (fm.description || "").trim()
+    indexLines.push(`- [${name}](${name}.md)` + (desc ? ` — ${desc}` : ""))
+  }
+  if (indexLines.length) {
+    const index = path.join(memDir, "MEMORY.md")
+    let current = "# Memory Index\n"
+    try { current = (await fs.readFile(index, "utf8")).replace(/\n+$/, "") + "\n" } catch {}
+    await fs.writeFile(index, current + indexLines.join("\n") + "\n", "utf8")
+  }
+  return written
+}
+
+export const GeneseedLearn = async ({ client }) => {
+  const ours = new Set()       // throwaway distil sessions — never mine our own output
+  const timers = new Map()     // sid -> debounce timer, re-armed on each idle
+  const inFlight = new Set()   // sid currently being distilled (guards against overlap)
+  let warnedNoDir = false
+
+  async function runDistill(sid) {
+    if (await sovereignBypass(process.cwd())) return
+    if (inFlight.has(sid)) return   // a run is already underway; the next idle re-arms
+    inFlight.add(sid)
+    try {
+      // A child session (carries a parent link) is a subagent dispatch: never mined
+      // into the shared store, but distilled for ONE per-agent lesson if we can name
+      // the agent. Field absent → top-level user session, distilled the old way.
+      // Unresolvable agent on a child → skip entirely (the prior behaviour).
+      const info = await client.session.get?.({ path: { id: sid } }).catch(() => null)
+      const meta = info?.data ?? info
+      const isChild = !!(meta?.parentID ?? meta?.parentId)
+      const agentName = isChild ? resolveAgentName(meta) : null
+      if (isChild && !agentName) return
+
+      const memDir = await resolveMemoryDir()
+      if (!memDir) {
+        if (!warnedNoDir) {
+          warnedNoDir = true
+          console.error(
+            "[geneseed-learn] no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY."
+          )
+        }
+        return
+      }
+
+      const res = await client.session.messages({ path: { id: sid } })
+      const messages = Array.isArray(res) ? res : res?.data ?? []
+      let { notes, model } = flatten(messages)
+      if (notes.length < MIN_NOTES_CHARS) return
+      notes = notes.slice(-MAX_NOTES_CHARS)
+      model = model ?? envModel()
+      if (!model) {
+        console.error(
+          "[geneseed-learn] could not determine a model — set $GENESEED_MODEL=provider/model."
+        )
+        return
+      }
+
+      const existing = await existingSlugs(memDir)
+      const prompt = isChild
+        ? [AGENT_LESSON_PROMPT, "", "NOTES:", notes].join("\n")
+        : buildPrompt(notes, existing)
+
+      // Distil in a throwaway session with the session's own model, then drop it.
+      const session = await client.session.create({ body: { title: "geneseed-learn (auto)" } })
+      const newId = session?.id ?? session?.data?.id
+      if (!newId) {
+        // Prompting with {id: undefined} would 404 silently on every idle.
+        console.error("[geneseed-learn] session.create returned no id — skipping this distil.")
+        return
+      }
+      ours.add(newId)
+      let output = ""
+      try {
+        const reply = await client.session.prompt({
+          path: { id: newId },
+          body: { model, parts: [{ type: "text", text: prompt }] },
+        })
+        output = partsText(reply?.parts ?? reply?.data?.parts) || reply?.text || ""
+      } finally {
+        if (newId) await client.session.delete({ path: { id: newId } }).catch(() => {})
+      }
+
+      if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
+      if (isChild) {
+        const lesson = output.trim().split("\n")[0].replace(/^[-*]\s*/, "").trim()
+        if (lesson.length < 10 || lesson.length > 300) return // junk / truncation guard
+        const f = await appendAgentLesson(memDir, agentName, lesson)
+        console.error(`[geneseed-learn] agent lesson -> ${f}`)
+        return
+      }
+      const written = await writeMemories(output, memDir, existing)
+      if (written.length) {
+        console.error(`[geneseed-learn] wrote ${written.length} memory file(s): ${written.join(", ")}`)
+      }
+    } catch (err) {
+      // Never break the session over a memory write.
+      console.error(`[geneseed-learn] skipped: ${err?.message ?? err}`)
+    } finally {
+      inFlight.delete(sid)
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (!event) return
+      const sid =
+        event.properties?.sessionID ??
+        event.payload?.sessionID ??
+        event.properties?.info?.id ??
+        event.payload?.info?.id
+      // A deleted session must not distil later from a stale timer (and its entry
+      // must not leak in the maps for the life of the process).
+      if (event.type === "session.deleted") {
+        const t = timers.get(sid)
+        if (t) clearTimeout(t)
+        timers.delete(sid)
+        ours.delete(sid)
+        return
+      }
+      if (event.type !== "session.idle") return
+      if (!sid || ours.has(sid)) return
+      // session.idle fires after every turn — debounce so we distil once, at the real
+      // end of the session (see header note). Each idle re-arms the timer.
+      const prev = timers.get(sid)
+      if (prev) clearTimeout(prev)
+      timers.set(sid, setTimeout(() => { timers.delete(sid); runDistill(sid) }, DEBOUNCE_MS))
+    },
+  }
+}
+
+export default GeneseedLearn

package/adapters/opencode/plugins/geneseed-notify.js

@@ -0,0 +1,142 @@
+// Geneseed — OpenCode desktop-notification plugin.
+//
+// Pings the OS when the agent finishes a turn, so you can walk away from a long run
+// and be called back when it is your move again. Hooks OpenCode's `session.idle`
+// event (fired when the assistant goes quiet) the same "act, don't just instruct"
+// way the other plugins hook their events.
+//
+// ANTI-SPAM: it only fires when the turn actually took a while — the gap between the
+// session's last user prompt and now must exceed GENESEED_NOTIFY_MIN_SECONDS
+// (default 30). A two-second back-and-forth never notifies; a five-minute build or
+// test run does. Native subagent child sessions and the learn plugin's throwaway
+// `geneseed-*` distil sessions are skipped, so background machinery stays silent.
+//
+// GENESEED_NOTIFY=off               disable entirely.
+// GENESEED_NOTIFY_MIN_SECONDS=N     minimum turn length, in seconds, to notify (default 30; 0 = always).
+// GENESEED_NOTIFY_TITLE="…"         override the notification title (default "Geneseed").
+// GENESEED_DEBUG=1                  log decisions/delivery to stderr.
+//
+// DELIVERY is native and dependency-free — no npm package, nothing to install:
+//   macOS   → `osascript` (always present)
+//   Linux   → `notify-send` (from libnotify; absent → swallowed, no error)
+//   Windows → PowerShell balloon tip (System.Windows.Forms.NotifyIcon)
+// The notifier is spawned detached and unref'd; a missing binary or any failure is
+// swallowed, so it never blocks, delays, or breaks a session.
+//
+// Install: dropped into the plugins dir by `build --emit opencode[-global]` (the *.js
+// glob), exactly like the context, learn, guard, and workflow plugins.
+
+import { spawn } from "node:child_process"
+
+const MODE = (process.env.GENESEED_NOTIFY || "on").toLowerCase()
+const OFF = ["off", "0", "false", "no"].includes(MODE)
+// NaN-safe: Math.max(0, NaN) is NaN, and `elapsed >= NaN` is always false — garbage
+// in the env var would silently disable every notification.
+const _minRaw = Number(process.env.GENESEED_NOTIFY_MIN_SECONDS ?? 30)
+const MIN_MS = Math.max(0, Number.isFinite(_minRaw) ? _minRaw : 30) * 1000
+const TITLE = process.env.GENESEED_NOTIFY_TITLE || "Geneseed"
+const DEBUG = !!process.env.GENESEED_DEBUG
+function log(msg) { if (DEBUG) console.error(`[geneseed-notify] ${msg}`) }
+
+// The timestamp (ms) of the latest user prompt in a transcript — our proxy for "when
+// this turn started", so we can measure how long the agent worked. Tolerant of the
+// few shapes `info.time` takes across SDK versions. Exported for tests.
+function lastUserMs(messages) {
+  if (!Array.isArray(messages)) return null
+  let t = null
+  for (const m of messages) {
+    const info = m?.info ?? {}
+    if (info.role !== "user") continue
+    const created = info?.time?.created ?? info?.time ?? info?.created
+    if (typeof created === "number") t = created
+  }
+  return t
+}
+
+// Pure gate: notify only for a real, top-level, long-enough turn. Exported for tests.
+//   - a subagent child session (has a parent) is background work → no.
+//   - a `geneseed-*` session is the learn plugin's throwaway distil → no.
+//   - unknown turn length → yes (don't suppress an opt-in ping over a missing field).
+//   - otherwise: only if the turn ran at least `minMs`.
+function shouldNotify({ now, lastUserMs, parentID, title, minMs }) {
+  if (parentID) return false
+  if (typeof title === "string" && title.startsWith("geneseed-")) return false
+  if (lastUserMs == null) return true
+  return now - lastUserMs >= minMs
+}
+
+// AppleScript double-quoted string literal.
+function asStr(s) { return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"' }
+// PowerShell single-quoted string literal (escape ' by doubling).
+function psStr(s) { return "'" + String(s).replace(/'/g, "''") + "'" }
+
+function spawnDetached(cmd, args) {
+  const child = spawn(cmd, args, { stdio: "ignore", detached: true })
+  child.on("error", (e) => log(`spawn ${cmd} failed: ${e?.message ?? e}`))   // e.g. notifier not installed
+  child.unref()
+}
+
+// Best-effort native notification; every failure is swallowed.
+function deliver(title, body) {
+  try {
+    if (process.platform === "darwin") {
+      spawnDetached("osascript", ["-e", `display notification ${asStr(body)} with title ${asStr(title)}`])
+    } else if (process.platform === "win32") {
+      const script =
+        "Add-Type -AssemblyName System.Windows.Forms;" +
+        "Add-Type -AssemblyName System.Drawing;" +
+        "$n=New-Object System.Windows.Forms.NotifyIcon;" +
+        "$n.Icon=[System.Drawing.SystemIcons]::Information;$n.Visible=$true;" +
+        `$n.ShowBalloonTip(5000,${psStr(title)},${psStr(body)},[System.Windows.Forms.ToolTipIcon]::Info);` +
+        "Start-Sleep -Seconds 6;$n.Dispose()"
+      spawnDetached("powershell", ["-NoProfile", "-NonInteractive", "-Command", script])
+    } else {
+      spawnDetached("notify-send", [title, body])
+    }
+  } catch (err) {
+    log(`deliver failed: ${err?.message ?? err}`)
+  }
+}
+
+export const GeneseedNotify = async ({ client }) => {
+  return {
+    event: async ({ event }) => {
+      if (OFF || !event || event.type !== "session.idle") return
+      const sid =
+        event.properties?.sessionID ?? event.payload?.sessionID ??
+        event.properties?.info?.id ?? event.payload?.info?.id
+      if (!sid) return
+      try {
+        let title = "", parentID
+        try {
+          const info = await client.session.get?.({ path: { id: sid } })
+          const meta = info?.data ?? info
+          title = meta?.title ?? ""
+          parentID = meta?.parentID ?? meta?.parentId
+        } catch {}
+
+        let started = null
+        try {
+          const res = await client.session.messages({ path: { id: sid } })
+          started = lastUserMs(Array.isArray(res) ? res : res?.data ?? [])
+        } catch {}
+
+        if (!shouldNotify({ now: Date.now(), lastUserMs: started, parentID, title, minMs: MIN_MS })) {
+          log(`skipped ${sid} (child/throwaway or turn under ${MIN_MS}ms)`)
+          return
+        }
+        deliver(TITLE, title ? `Done: ${title}` : "Agent finished — your turn.")
+        log(`notified for ${sid}`)
+      } catch (err) {
+        log(`skipped: ${err?.message ?? err}`)
+      }
+    },
+  }
+}
+
+// ponytail: OpenCode treats every export as a plugin and rejects non-functions; a
+// bare helper export crashes startup or logs "not a function". Hang the test helpers
+// off the factory instead — reachable via `import`, invisible to the loader.
+Object.assign(GeneseedNotify, { lastUserMs, shouldNotify })
+
+export default GeneseedNotify