@leon135/opencode-learn 0.0.0-stage → 0.1.1

package/plugins/md-link/index.ts

@@ -0,0 +1,314 @@
+/**
+ * md-link — Obsidian live-mirror (server side).
+ *
+ * Mirrors a session to `<dir>/<sessionID>_link.md` for sessions enabled in
+ * the state file (see core.ts for the contracts). Sessions are toggled
+ * exclusively by the TUI plugin — this plugin never enables anything.
+ *
+ * Mirrors are transient by default — with persistence ON (/md-link-persist),
+ * session entries survive TUI exit and this subscription resumes them on next launch.
+ *
+ * What gets mirrored (teaching-session parity with the pi md-log):
+ *   - assistant replies   → ctx.event.subscribe session.text.delta (2.5 s
+ *                           throttle while streaming) + session.text.ended
+ *   - user prompts        → session.inbox.enqueued, as `> [!quote] YOU` callouts
+ *   - quiz_ask / question → tool hooks: question callout written at
+ *                           execute.before (pre-answer, sanitized input),
+ *                           feedback callout at execute.after (quiz_grade /
+ *                           question results)
+ * The subscription is aborted by the cleanup returned from setup; an
+ * unexpected stream exit is logged and re-armed (the old poller self-recovered).
+ */
+
+import type { Plugin } from "@opencode/plugin";
+import {
+  appendMessage,
+  callout,
+  hasBlock,
+  isEnabled,
+  loadState,
+  mirrorFile,
+  touchMirror,
+  userPromptBlock,
+} from "./core.ts";
+
+/** Streaming cadence: rewrite an in-flight reply block at most this often. */
+const DELTA_WRITE_MS = 2_500;
+/** Wait before re-subscribing after the event stream exits unexpectedly. */
+const RESUBSCRIBE_MS = 5_000;
+
+/** Append one block, keeping the existing text when the key is already mirrored. */
+function mirrorBlock(
+  file: string,
+  key: string,
+  text: string,
+  keep: number | null,
+): void {
+  if (!text || hasBlock(file, key)) return;
+  appendMessage(file, { text, markerKey: key, replace: true }, keep);
+}
+
+/** Write an assistant block, rewriting the existing one in place while streaming. */
+function writeAssistant(
+  file: string,
+  key: string,
+  text: string,
+  keep: number | null,
+): void {
+  if (!text) return;
+  appendMessage(file, { text, markerKey: key, replace: true }, keep);
+}
+
+/** The subset of the session event stream this plugin mirrors. */
+type MirrorEvent =
+  | {
+      type: "session.text.delta";
+      data: {
+        sessionID: string;
+        assistantMessageID: string;
+        ordinal: number;
+        delta: string;
+      };
+    }
+  | {
+      type: "session.text.ended";
+      data: {
+        sessionID: string;
+        assistantMessageID: string;
+        ordinal: number;
+        text: string;
+      };
+    }
+  | {
+      type: "session.inbox.enqueued";
+      data: {
+        sessionID: string;
+        inboxID: string;
+        item:
+          | { type: "user"; payload: { text: string } }
+          | { type: "synthetic" | "compaction" | "move" };
+      };
+    };
+
+// ── Q&A callouts via tool hooks ─────────────────────────────────────────────
+
+/** Resolve the mirror file for a session, or null if not enabled. */
+function mirrorFor(sessionID: unknown): string | null {
+  if (typeof sessionID !== "string" || !sessionID) return null;
+  const st = loadState();
+  if (!isEnabled(st, sessionID)) return null;
+  return mirrorFile(st, sessionID, process.cwd());
+}
+
+function appendQa(
+  file: string,
+  markerKey: string,
+  text: string,
+  keep: number | null,
+): void {
+  const res = appendMessage(file, { text, markerKey, replace: true }, keep);
+  // "duplicate" is the expected steady state on service restarts / re-reads.
+  if (res === "failed") console.error("[md-link] qa append failed:", markerKey);
+}
+
+function questionCallout(
+  label: string,
+  question: string,
+  details: string | undefined,
+  options: any[],
+): string {
+  const body: string[] = [];
+  for (const line of String(question || "").split("\n")) body.push(line);
+  if (details) {
+    body.push("");
+    for (const line of details.split("\n")) body.push(line);
+  }
+  const opts = Array.isArray(options) ? options : [];
+  if (opts.length > 0) {
+    body.push("");
+    opts.forEach((o, i) => body.push(`${i + 1}. ${o?.label ?? ""}`));
+  }
+  return callout("question", label, body);
+}
+
+function resultText(result: any): string {
+  if (typeof result === "string") return result;
+  if (typeof result?.content === "string") return result.content;
+  if (Array.isArray(result?.content)) {
+    return result.content
+      .filter((c: any) => c?.type === "text")
+      .map((c: any) => c.text)
+      .join("\n");
+  }
+  return String(result?.output ?? "");
+}
+
+/** Feedback callout from quiz_grade's result text (we control that format). */
+function gradeCallout(content: string): string {
+  const lines = content
+    .split("\n")
+    .filter(
+      (l) => l.trim().length > 0 && !/^Relay the verdict/i.test(l.trim()),
+    );
+  const first = lines[0] ?? "";
+  if (/answered correctly/i.test(first)) {
+    return callout("success", "Quiz — correct ✓", lines.slice(1));
+  }
+  if (/answered incorrectly/i.test(first)) {
+    return callout("failure", "Quiz — incorrect ✗", lines.slice(1));
+  }
+  if (/...?/i.test(content)) {
+    return callout("question", "Quiz — ...?", lines.slice(1));
+  }
+  if (/dismissed|not answered in time/i.test(content)) {
+    return callout("warning", "Quiz — dismissed", ["(no answer given)"]);
+  }
+  return callout("example", "Quiz", lines);
+}
+
+export async function setupMdLink(ctx: Plugin.Context): Promise<() => void> {
+  const controller = new AbortController();
+  /** In-flight assistant text per `<messageID>#<ordinal>` and its last write time. */
+  const inflight = new Map<string, { text: string; written: number }>();
+
+  const handleEvent = (event: MirrorEvent): void => {
+    try {
+      const st = loadState();
+      const sessionID = event.data.sessionID;
+      if (!isEnabled(st, sessionID)) return;
+      // Fallback chain: recorded dir → config defaultDir → cwd (no hardcoded paths).
+      const file = mirrorFile(st, sessionID, process.cwd());
+      if (!file) return;
+      touchMirror(file);
+
+      if (event.type === "session.inbox.enqueued") {
+        const item = event.data.item;
+        if (item.type !== "user") return;
+        const text = String(item.payload.text ?? "").trim();
+        if (text)
+          mirrorBlock(
+            file,
+            `${event.data.inboxID}`,
+            userPromptBlock(text),
+            st.keep,
+          );
+        return;
+      }
+
+      const key = `${event.data.assistantMessageID}#${event.data.ordinal}`;
+      if (event.type === "session.text.delta") {
+        const entry = inflight.get(key) ?? { text: "", written: 0 };
+        entry.text += event.data.delta;
+        const now = Date.now();
+        if (now - entry.written >= DELTA_WRITE_MS) {
+          entry.written = now;
+          writeAssistant(file, key, entry.text.trim(), st.keep);
+        }
+        inflight.set(key, entry);
+        return;
+      }
+
+      // session.text.ended: final text for the part, written immediately.
+      inflight.delete(key);
+      writeAssistant(file, key, event.data.text.trim(), st.keep);
+    } catch {} // one bad event must not stop the subscription
+  };
+
+  // Re-arm after an unexpected stream exit; the old poller recovered by itself.
+  const subscribe = async (): Promise<void> => {
+    while (!controller.signal.aborted) {
+      try {
+        for await (const event of ctx.event.subscribe({
+          types: [
+            "session.text.delta",
+            "session.text.ended",
+            "session.inbox.enqueued",
+          ],
+          signal: controller.signal,
+        })) {
+          handleEvent(event);
+        }
+        if (!controller.signal.aborted)
+          console.error("[md-link] event stream ended — resubscribing");
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        console.error(
+          "[md-link] event subscription failed — resubscribing:",
+          error,
+        );
+      }
+      inflight.clear();
+      if (controller.signal.aborted) return;
+      await new Promise<void>((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          controller.signal.removeEventListener("abort", done);
+          resolve();
+        };
+        const timer = setTimeout(done, RESUBSCRIBE_MS);
+        controller.signal.addEventListener("abort", done, { once: true });
+      });
+    }
+  };
+
+  void subscribe();
+
+  // ── Q&A capture ─────────────────────────────────────────────────────────
+  // execute.before: write the question callout BEFORE the learner answers
+  // (quiz_ask/question inputs are sanitized — no answer material).
+  if (typeof ctx?.tool?.hook === "function") {
+    await ctx.tool.hook("execute.before", async (event: any) => {
+      try {
+        const file = mirrorFor(event.sessionID);
+        if (!file) return;
+        const { keep } = loadState();
+        if (event.tool === "quiz_ask") {
+          const input = event.input ?? {};
+          const block = questionCallout(
+            "Quiz",
+            input.question,
+            input.details,
+            input.options,
+          );
+          appendQa(file, `qa-ask-${event.id}`, block, keep);
+        } else if (event.tool === "question") {
+          const q = event.input?.questions?.[0] ?? {};
+          const block = questionCallout(
+            "Question",
+            q.question ?? q.header ?? "",
+            undefined,
+            q.options,
+          );
+          appendQa(file, `qa-ask-${event.id}`, block, keep);
+        }
+      } catch {}
+    });
+
+    // execute.after: write the feedback callout (answer already given).
+    await ctx.tool.hook("execute.after", async (event: any) => {
+      try {
+        const file = mirrorFor(event.sessionID);
+        if (!file) return;
+        const { keep } = loadState();
+        if (event.tool === "quiz_grade") {
+          const content = resultText(event.result);
+          if (content)
+            appendQa(file, `qa-grade-${event.id}`, gradeCallout(content), keep);
+        } else if (event.tool === "question" && event.status === "completed") {
+          const content = resultText(event.result);
+          if (content)
+            appendQa(
+              file,
+              `qa-grade-${event.id}`,
+              callout("example", "Answer", content.split("\n")),
+              keep,
+            );
+        }
+      } catch {}
+    });
+  } else {
+    console.error("[md-link] ctx.tool.hook unavailable — Q&A capture disabled");
+  }
+
+  return () => controller.abort();
+}

package/plugins/md-link/tui.ts

@@ -0,0 +1,360 @@
+/**
+ * md-link TUI plugin — silent toggle for the Obsidian live mirror.
+ *
+ * V2 loader contract: default export is { id, setup } via Plugin.define.
+ * setup may call ctx.keymap.layer() directly (the layer is removed when the
+ * plugin deactivates) and returns a cleanup that runs on deactivate/exit.
+ * Dialog API: await ctx.ui.dialog.prompt({...}) → string | undefined.
+ *
+ * Commands (all purely client-side — nothing is ever sent to the LLM):
+ *   ctrl+alt:m / /md-link [dir]   toggle mirroring for the focused session;
+ *                                 ON backfills up to 10 recent messages
+ *                                 (replies + your prompts)
+ *   /md-link-dir                  set the default output directory
+ *   /md-link-keep                 keep only the N newest replies (empty = all);
+ *                                 existing mirrors are trimmed immediately
+ *   /md-link-persist [on|off]     persistent mirrors: while ON, TUI exit keeps
+ *                                 this project's mirror files + session entries
+ *                                 and mirroring auto-resumes next launch;
+ *                                 explicit /md-link OFF still deletes at once
+ *
+ * On TUI exit, mirror files belonging to this project are deleted unless
+ * persistence (/md-link-persist) is ON. See core.ts for state/file contracts.
+ */
+
+import { accessSync, constants as fsConstants, existsSync, readFileSync, rmSync, statSync } from "fs"
+import { isAbsolute, join, normalize } from "path"
+import { homedir } from "os"
+import type { OpenCodeClient } from "@opencode/client"
+import type { Plugin } from "@opencode/plugin/tui"
+import {
+  appendMessage,
+  disableSession,
+  hasBlock,
+  isEnabled,
+  loadState,
+  messageText,
+  mirrorFile,
+  pruneMirror,
+  saveState,
+  touchMirror,
+  userPromptBlock,
+} from "./core.ts"
+
+type DirResult = { ok: true; abs: string } | { ok: false; error: string }
+type ToastVariant = "info" | "success" | "warning" | "error"
+
+/** Cap on how many historical messages a single enable may backfill (V1 parity). */
+const MAX_CATCHUP = 10
+
+/** Validate a user-supplied output dir. Must already exist and be writable. */
+function validateDir(raw: string, pwd: string): DirResult {
+  let d = String(raw ?? "").trim().replace(/^["']+|["']+$/g, "")
+  if (d.startsWith("~")) d = join(homedir(), d.slice(1))
+  if (d.length === 0) d = "."
+  if (d.includes("\0")) return { ok: false, error: "invalid path" }
+  if (d.split("/").includes("..")) return { ok: false, error: "path may not contain '..'" }
+  if (!/^[A-Za-z0-9 ._\-\/]+$/.test(d)) return { ok: false, error: `unsupported characters in "${d}"` }
+
+  const abs = isAbsolute(d) ? normalize(d) : normalize(join(pwd, d))
+  try {
+    if (!existsSync(abs)) return { ok: false, error: `directory does not exist: ${abs}` }
+    if (!statSync(abs).isDirectory()) return { ok: false, error: `not a directory: ${abs}` }
+    accessSync(abs, fsConstants.W_OK)
+  } catch (e: any) {
+    return { ok: false, error: `cannot use ${abs}: ${e?.code ?? e?.message ?? e}` }
+  }
+  return { ok: true, abs }
+}
+
+/** Pull a free-form argument out of whatever the slash/keybind run() hands us. */
+function extractArg(input: unknown): string {
+  if (typeof input === "string") return input
+  if (Array.isArray(input)) return input.map((x) => extractArg(x)).join(" ")
+  const r = input as any
+  if (r && typeof r === "object") {
+    for (const k of ["value", "arg", "args", "input", "arguments", "text", "message", "prompt"]) {
+      const v = r[k]
+      if (typeof v === "string") return v
+      if (Array.isArray(v)) return v.map((x) => extractArg(x)).join(" ")
+    }
+  }
+  return ""
+}
+
+/**
+ * Backfill recent history when mirroring is enabled for a session: up to
+ * MAX_CATCHUP newest messages, BOTH assistant replies and user prompts,
+ * appended oldest-first so the mirror stays chronological (V1 catch-up parity).
+ *
+ * The page is newest-first via the plugin client
+ * (ctx.client.message.list = GET /api/session/:id/message). Walking stops at
+ * the first already-mirrored marker, so a live event that won the race never
+ * produces a duplicate block.
+ *
+ * Replies still streaming when the toggle fires are skipped: their
+ * time.created is too recent, and live ordinals will finish them anyway.
+ */
+async function backfillLatestTurn(
+  client: OpenCodeClient,
+  sessionID: string,
+  file: string,
+  keep: number | null,
+  enabledAt: number,
+): Promise<number> {
+  let written = 0
+  try {
+    const { data: items } = await client.message.list({
+      sessionID,
+      order: "desc",
+      limit: 50,
+    })
+    const pending: { id: string; text: string }[] = []
+    for (const m of items) {
+      if (m.type !== "assistant" && m.type !== "user") continue
+      const created = Number(m.time?.created ?? 0)
+      if (m.type === "assistant" && created && enabledAt - created < 15_000) continue // likely still streaming
+      const text = messageText(m)
+      if (!text) continue
+      if (hasBlock(file, m.id)) break // already mirrored — everything older is too
+      pending.push({
+        id: `${m.id}#backfill`,
+        text: m.type === "user" ? userPromptBlock(text) : text,
+      })
+      if (pending.length >= MAX_CATCHUP) break
+    }
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const res = appendMessage(file, { text: pending[i].text, markerKey: pending[i].id, replace: true }, keep)
+      if (res === "written") written++
+    }
+  } catch {}
+  return written
+}
+
+export async function setupMdLinkTui(ctx: Plugin.Context): Promise<Plugin.Cleanup> {
+  const pwd = (): string => ctx.data.location.default().directory || process.cwd()
+
+  const toast = (message: string, variant: ToastVariant = "info") => {
+    try {
+      ctx.ui.toast.show({ title: "md-link", message, variant })
+    } catch {}
+  }
+
+  const short = (s: string) => (s.length > 28 ? s.slice(0, 28) + "…" : s)
+
+  // ——— toggle ———
+
+  /** Collapse duplicate activations: stacked layers from hot-reloads fire
+   * run() twice per keypress (ON then instantly OFF). */
+  let lastRun = 0
+  async function run(input?: unknown): Promise<void> {
+    const now = Date.now()
+    if (now - lastRun < 500) return
+    lastRun = now
+
+    try {
+      const cur = ctx.ui.router.current()
+      const sessionID = cur.type === "session" ? cur.sessionID : undefined
+      if (!sessionID || typeof sessionID !== "string") {
+        toast("No active session found", "warning")
+        return
+      }
+
+      const st = loadState()
+      const arg = extractArg(input).trim()
+      const res = validateDir(arg || st.defaultDir || pwd(), pwd())
+      if (!res.ok) {
+        toast(`Invalid dir "${arg || st.defaultDir}": ${res.error}`, "error")
+        return
+      }
+      if (arg) st.defaultDir = res.abs // remember explicitly requested dirs
+
+      const file = join(res.abs, `${sessionID}_link.md`)
+      if (isEnabled(st, sessionID)) {
+        const oldDir = st.sessions[sessionID]
+        disableSession(st, sessionID)
+        for (const dir of new Set([oldDir, res.abs])) {
+          try { rmSync(join(dir ?? "", `${sessionID}_link.md`), { force: true }) } catch {}
+        }
+        toast(`Live mirror OFF (${short(sessionID)})`, "warning")
+        return
+      }
+
+      st.sessions[sessionID] = res.abs
+      saveState(st)
+      touchMirror(file)
+      const backfilled = await backfillLatestTurn(ctx.client, sessionID, file, st.keep, Date.now())
+      const tag = st.persist ? " (persistent)" : ""
+      toast(
+        backfilled > 0
+          ? `Live mirror ON, backfilled ${backfilled} message${backfilled === 1 ? "" : "s"} → ${short(file)}${tag}`
+          : `Live mirror ON → ${file}${tag}`,
+      )
+    } catch (e: any) {
+      toast(`Failed: ${e?.message ?? e}`, "error")
+    }
+  }
+
+  // ——— dialogs ———
+
+  async function openSetDirDialog(): Promise<void> {
+    try {
+      const v = await ctx.ui.dialog.prompt({
+        title: "md-link output directory",
+        placeholder: `relative to project (${pwd()}) or absolute path`,
+        value: loadState().defaultDir ?? "",
+      })
+      if (typeof v !== "string") return // cancelled
+      const res = validateDir(v, pwd())
+      if (!res.ok) {
+        toast(`Invalid dir: ${res.error}`, "error")
+        return
+      }
+      const st = loadState()
+      st.defaultDir = res.abs
+      saveState(st)
+      toast(`Default output dir set → ${res.abs}`)
+    } catch (e: any) {
+      toast(`Cannot open dialog: ${e?.message ?? e}`, "error")
+    }
+  }
+
+  async function openKeepDialog(): Promise<void> {
+    try {
+      const cur = loadState().keep
+      const v = await ctx.ui.dialog.prompt({
+        title: "md-link: show last N messages",
+        placeholder: "number of recent messages to keep (empty = unlimited)",
+        value: cur != null ? String(cur) : "",
+      })
+      if (typeof v !== "string") return // cancelled
+      const t = v.trim()
+      let keep: number | null = null
+      if (t.length > 0) {
+        const n = Number(t)
+        if (!Number.isInteger(n) || n < 1 || n > 500) {
+          toast(`Invalid count "${t}" — use 1..500 or empty`, "error")
+          return
+        }
+        keep = n
+      }
+      const st = loadState()
+      st.keep = keep
+      saveState(st)
+      if (keep == null) {
+        toast("Mirror keeps all messages")
+        return
+      }
+      // Apply immediately: trim every enabled session's live mirror now.
+      let trimmed = 0
+      for (const sid of Object.keys(st.sessions)) {
+        const f = mirrorFile(st, sid, pwd())
+        if (!f || !existsSync(f)) continue
+        const before = readFileSync(f, "utf-8")
+        pruneMirror(f, keep)
+        if (readFileSync(f, "utf-8") !== before) trimmed++
+      }
+      toast(`Mirror shows only the last ${keep}${trimmed ? ` (${trimmed} mirror${trimmed === 1 ? "" : "s"} trimmed)` : ""}`)
+    } catch (e: any) {
+      toast(`Cannot open dialog: ${e?.message ?? e}`, "error")
+    }
+  }
+
+  // ——— persistence toggle ———
+
+  /** Flip (or force via on|off arg) persistent-mirror mode: kept mirrors
+   * survive TUI exit and their sessions auto-resume on next launch. */
+  async function togglePersistence(input?: unknown): Promise<void> {
+    try {
+      const st = loadState()
+      const arg = extractArg(input).trim().toLowerCase()
+      if (arg === "on" || arg === "true" || arg === "1") st.persist = true
+      else if (arg === "off" || arg === "false" || arg === "0") st.persist = false
+      else st.persist = !st.persist
+      saveState(st)
+      toast(
+        st.persist
+          ? "Persistent mirrors ON — survive TUI exit, resume next launch"
+          : "Persistent mirrors OFF — mirrors deleted on TUI exit",
+        st.persist ? "info" : "warning",
+      )
+    } catch (e: any) {
+      toast(`Failed: ${e?.message ?? e}`, "error")
+    }
+  }
+
+  // ——— startup notice for persistent mirrors ———
+
+  try {
+    const root = pwd()
+    const resumed = Object.values(loadState().sessions).filter((d) => root && d.startsWith(root)).length
+    if (resumed > 0) toast(`md-link: resumed ${resumed} persistent mirror${resumed === 1 ? "" : "s"}`)
+  } catch {}
+
+  // ——— cleanup on TUI close (skipped while persistence is ON) ———
+
+  let cleaned = false
+  function cleanupOnExit(): void {
+    if (cleaned) return
+    cleaned = true
+    try {
+      const root = pwd()
+      const st = loadState()
+      if (st.persist) return // persistent mode: keep files + entries, resume next launch
+      for (const [sid, dir] of Object.entries(st.sessions)) {
+        // only remove mirrors owned by THIS project — other TUIs keep theirs
+        if (root && !dir.startsWith(root)) continue
+        try { rmSync(join(dir || ".", `${sid}_link.md`), { force: true }) } catch {}
+        delete st.sessions[sid]
+      }
+      saveState(st)
+    } catch {}
+  }
+  // belt-and-braces: host cleanup covers normal exit; this covers hard exits
+  try { process.once("exit", cleanupOnExit) } catch {}
+
+  // ——— registration (callable directly from setup; removed on deactivate) ———
+
+  ctx.keymap.layer(() => ({
+    mode: "global",
+    priority: 1,
+    enabled: true,
+    commands: [
+      {
+        id: "md-link.toggle",
+        title: "Live mirror",
+        group: "md-link",
+        bind: "ctrl+alt+m",
+        palette: true,
+        slash: { name: "md-link" },
+        run,
+      },
+      {
+        id: "md-link.setdir",
+        title: "Output directory…",
+        group: "md-link",
+        palette: true,
+        slash: { name: "md-link-dir" },
+        run: () => openSetDirDialog(),
+      },
+      {
+        id: "md-link.keep",
+        title: "Keep last N",
+        group: "md-link",
+        palette: true,
+        slash: { name: "md-link-keep" },
+        run: () => openKeepDialog(),
+      },
+      {
+        id: "md-link.persist",
+        title: "Persistence",
+        group: "md-link",
+        palette: true,
+        slash: { name: "md-link-persist" },
+        run: (input?: unknown) => togglePersistence(input),
+      },
+    ],
+  }))
+
+  return cleanupOnExit
+}