@leon135/opencode-learn 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# opencode-learn
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An AI teaching system packaged as an [OpenCode v2](https://opencode.ai/v2/docs/) plugin. The `teach` skill probes what you already know, plans a dependency map, then teaches node by node — checking each node lands with a graded quiz before building on top of it.
+
+## Where it comes from
+
+Three generations of the same system:
+
+1. **[amosblomqvist/learn](https://github.com/amosblomqvist/learn)** — the original, built as [pi](https://github.com/earendil-works/pi) configuration. The teaching philosophy, the skills and the system design are all his, from the video [How I Use AI to Learn Things](https://www.youtube.com/watch?v=kzcI5F4tGiU).
+2. **[FAZuH/oc-learn](https://github.com/FAZuH/oc-learn)** — a port of that system to OpenCode.
+3. **This repository** — takes FAZuH's port and brings it up to date with the current OpenCode v2 plugin API, adds [OpenChamber](https://github.com/openchamber/openchamber) support, and adds a simple cross-session memory.
+
+> [!WARNING]
+> Experimental — some things may not work or may break.
+
+## Install
+
+Requires OpenCode v2.
+
+```jsonc
+{
+  "plugins": ["@leon135/opencode-learn"],
+}
+```
+
+Visuals publish into the session project's `viz/` by default — the project dir is captured once when the plugin sets up (`ctx.location.directory`), so publishes resolve against it even if the process cwd differs. To always publish somewhere else (an Obsidian vault, say), run `/viz-dir` in the TUI — or point `~/.config/opencode/viz-state.json` at it directly; the override still wins, and empty or missing means the project dir:
+
+```json
+{ "defaultDir": "/home/you/Notes/viz" }
+```
+
+md-link keeps its own state next to it in `~/.config/opencode/md-link-state.json` (`defaultDir`, `keep`, `persist`, and the enabled sessions).
+
+## Memory
+
+Teaching spans sessions; session context does not. The `teach` skill keeps a **project-scoped learner profile** at `.memory/profile.md` — one short file, read in full at session start and updated as the session goes rather than in one dump at the end:
+
+- **Known foundations** — per subject: what you reliably hold, and where your edge is
+- **Struggles** — concepts and moves that cost visible effort
+- **Typical mistakes** — recurring slips, phrased specifically enough to quote back
+- **Practice queue** — what to drill next and why
+- **How to explain to you** — which analogies and cadence work, and which don't
+- **Active plan / where we left off** — the current plan, stuck point, next-session hook
+
+## Quiz modes
+
+**Chat-UI mode** returns the question plus a ready `openui-lang` program for `openchamber_render`; [OpenChamber](https://github.com/openchamber/openchamber) renders it, returns the chosen letter(s) and any note, and the model relays them to `quiz_grade(selected, note)`. The question, its details and the lettered option texts all render inside the callout (markdown, so LaTeX works there), while the Choice buttons stay plain letters (A, B, C…); a letter resolves to the shuffled option value through the same letter/value logic as before. Without that tool the result includes a plain-text lettered fallback.
+
+**Form mode** (TUI, and `auto` when chat detection fails) is a hybrid: the session form carries only lettered options (A, B, C…, plus "...?") and a note field, with the fixed title "Quiz — answer the question shown in chat". The full question, its details and the lettered option texts come back in the `quiz_ask` result, which tells the model to post that block as a chat message (markdown; math renders per the TUI's own pipeline). The form opens before that message can appear, so you may see the lettered form first — an accepted ordering wrinkle of the design. Form grading uses the same letter/value resolution as chat.
+
+The plugin option `mode` is `"auto"` (default), `"chat"`, or `"form"`:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@leon135/opencode-learn",
+      "options": { "mode": "auto" },
+    },
+  ],
+}
+```
+
+`auto` detects `openchamber_render` in the session's tool catalog (memoized per session): present → chat, absent → form. If detection fails or has not run yet, it degrades to chat — a plain-text question still works there, while an invisible form does not.
+
+No synchronous HTML/KaTeX transport ships: a plugin-POSTed page is never displayed (the chat draws only `openchamber_render` tool-call pages) and an inlined-KaTeX page exceeds OpenChamber's `render.html` 200 000-character page cap.
+
+## Requirements
+
+- [OpenCode v2](https://opencode.ai/v2/docs)
+- `rsvg-convert` (librsvg) or ImageMagick — SVG rendering
+- `mmdc` (`@mermaid-js/mermaid-cli`) on PATH — Mermaid rendering
+- [Bun](https://bun.sh) only for development: `bun install`, then `bun x tsc --noEmit` to typecheck
+- Subagents inherit the session's model — edit `plugins/agents.ts` to tune them
+- For quizzes: nothing extra — chat-UI mode auto-detects `openchamber_render` (OpenChamber) and otherwise uses OpenCode v2's native TUI forms. See [Quiz modes](#quiz-modes) to force one.
+
+## Notes
+
+- The teaching flow: `teach` probes your level with graded quizzes (`quiz_ask`/`quiz_grade`), plans a dependency map, then teaches node by node with a quiz check after each one. Non-graded questions use OpenCode's built-in `question` tool.
+- Visuals are never hand-faked: the skill briefs a maker subagent, which authors, renders to PNG, **looks at the result**, iterates, and only then publishes into `viz/` for embedding.
+- `md-link` mirrors only reading-relevant content: your prompts, lesson prose, and quiz Q&A. Tool noise (bash, reads, edits) is omitted. It is event-driven: assistant text is rewritten in place at most every 2.5 s while streaming, the final reply is written when the stream ends, and user prompts are mirrored as they are enqueued. Commands: `ctrl+alt:m` or `/md-link [dir]` toggles the focused session (ON backfills the last 10 messages — replies and your prompts), `/md-link-dir` sets the default output directory, `/md-link-keep` keeps only the N newest replies, and `/md-link-persist [on|off]` keeps mirrors across TUI restarts and auto-resumes them on next launch. `/md-link` OFF still deletes immediately.
+- The maker and researcher agents are registered with deny-all permissions plus only the few actions they need. Under v2's last-match-wins permission rule, a later permissive global permission can widen that sandbox; the plugin cannot pin it, so keep global `allow` rules narrow if you rely on it.
+- The makers render but the tools return a path, not an image — `render_*` returns the PNG path and the maker opens it with `read` to inspect. Same verify-by-looking loop, one extra step.
+- You can run the system without subagents: the main session does the teaching. You lose the researcher (truth verification) and the generated visuals.
+
+## Differences from the original
+
+Carried over from the OpenCode port (FAZuH's work, relative to the pi original):
+
+- **Configurable viz output** — `viz-state.json` (`defaultDir`) sends published visuals to any directory; the original always wrote to `<cwd>/viz`.
+- **md-link TUI commands** — `ctrl+alt:m` / `/md-link` with per-session enable, plus `/md-link-dir`, `/md-link-keep`, and `/md-link-persist`; the original had `/md-log` / `/md-unlog` commands only.
+- **quiz is two tools** — `quiz_ask` poses the question, `quiz_grade` carries the answer. The TUI shows raw tool arguments, so splitting at the answer boundary makes the correct answer structurally invisible until after you answer (the original hid it inside the popup renderer).
+- **No `ask-user-question` extension** — OpenCode v2's built-in `question` tool covers non-graded questions.
+- **No subagent extension** — v2's built-in `subagent` tool replaces `pi-interactive-subagents` (the original's recommended tmux-only dependency).
+- **Render-and-inspect via path** — `render_*` returns the PNG path and the maker opens it with `read` (the original returned the image inline).
+- **Linux-first rendering** — `mmdc` / `rsvg-convert` from PATH instead of a bundled mermaid-cli and macOS Chrome paths.
+
+New in this repository:
+
+- **Current OpenCode v2 plugin API** — brought up to date with the current `@opencode/plugin` surface: one package entry carrying both the server and TUI parts (replacing FAZuH's symlinking `install.sh`/`uninstall.sh`), session event subscription instead of message polling, and the plugin client instead of spawning `opencode2`. Agents and skills are registered by the plugin itself.
+- **OpenChamber support** — [OpenChamber](https://github.com/openchamber/openchamber)-aware quiz transport: chat-UI mode auto-detects `openchamber_render` and renders the question as an interactive callout with lettered buttons.
+- **Simple memory** — the project-scoped learner profile at `.memory/profile.md`, so the teacher picks up where it left off across sessions. See [Memory](#memory).
+
+## Credits
+
+- **[amosblomqvist](https://github.com/amosblomqvist)** — original system, teaching philosophy, and the video: [amosblomqvist/learn](https://github.com/amosblomqvist/learn) (pi configuration)
+- **[FAZuH](https://github.com/FAZuH)** — the OpenCode port: [FAZuH/oc-learn](https://github.com/FAZuH/oc-learn)
+- This repository — fork of that port, updated for the current OpenCode v2, with OpenChamber support and the learner profile added

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@leon135/opencode-learn",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Opencode AI learning system.",
+  "type": "module",
+  "exports": {
+    ".": "./plugins/index.ts",
+    "./tui": "./plugins/tui.ts"
+  },
+  "files": [
+    "plugins",
+    "skills",
+    "assets"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leon135/opencode-learn.git"
+  },
+  "keywords": [
+    "opencode",
+    "learn"
+  ],
+  "author": "leon135",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/leon135/opencode-learn/issues"
+  },
+  "homepage": "https://github.com/leon135/opencode-learn#readme",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode/client": "^2.2.5",
+    "@opencode/plugin": "^2.2.5"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "solid-js": "^1.9.18",
+    "typescript": "latest"
+  }
+}

package/plugins/agents.ts

@@ -0,0 +1,211 @@
+import type { Plugin } from "@opencode/plugin"
+
+type Permission = { action: string; resource: string; effect: "allow" | "deny" | "ask" }
+
+type AgentDefinition = {
+  name: string
+  description: string
+  steps: number
+  permissions: Permission[]
+  system: string
+}
+
+const AGENTS: AgentDefinition[] = [
+  {
+    name: "researcher",
+    description: "Web researcher — searches the web and synthesizes findings",
+    steps: 32,
+    permissions: [
+      { action: "*", resource: "*", effect: "deny" },
+      { action: "websearch", resource: "*", effect: "allow" },
+      { action: "webfetch", resource: "*", effect: "allow" },
+    ],
+    system: `You are a research specialist. Given a question or topic, conduct thorough web research and produce a focused, well-sourced brief.
+
+You operate in an isolated context with no knowledge of any prior conversation. All necessary context is in the task description.
+
+Process:
+1. Break the question into 2-4 searchable facets
+2. Search with \`websearch\` using varied angles
+3. Read the answers. Identify what's well-covered, what has gaps.
+4. For the 2-3 most promising source URLs, use \`webfetch\` to get full page content
+5. Synthesize everything into a brief that directly answers the question
+
+Search strategy — always vary your angles:
+- Direct answer query (the obvious one)
+- Authoritative source query (official docs, specs, primary sources)
+- Practical experience query (case studies, benchmarks, real-world usage)
+- Recent developments query (only if the topic is time-sensitive)
+
+Evaluation — what to keep vs drop:
+- Official docs and primary sources outweigh blog posts and forum threads
+- Recent sources outweigh stale ones
+- Sources that directly address the question outweigh tangentially related ones
+- Drop: SEO filler, outdated info, beginner tutorials (unless that's the audience)
+
+If the first round of searches doesn't fully answer the question, search again with refined queries targeting the gaps.
+
+Your FINAL assistant message is your entire deliverable — it must stand alone, using this format:
+
+## Summary
+2-3 sentence direct answer.
+
+## Findings
+Numbered findings with inline source citations:
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
+
+## Sources
+- Kept: Source Title (url) — why relevant
+- Dropped: Source Title — why excluded
+
+## Gaps
+What couldn't be answered. Suggested next steps.`,
+  },
+  {
+    name: "svg-maker",
+    description: "Authors ONE hand-written SVG from a brief, renders it to a PNG, LOOKS at the result, iterates until it is correct and clean, publishes the PNG into the Obsidian vault, and returns the filename. For spatial/geometric visuals Mermaid can't express — coordinate geometry, number lines, vectors, function plots, physical layouts, custom shapes with exact positions.",
+    steps: 24,
+    permissions: [
+      { action: "*", resource: "*", effect: "deny" },
+      { action: "external_directory", resource: "/tmp/opencode/**", effect: "allow" },
+      { action: "read", resource: "*", effect: "allow" },
+      { action: "write_svg", resource: "*", effect: "allow" },
+      { action: "edit_svg", resource: "*", effect: "allow" },
+      { action: "render_svg", resource: "*", effect: "allow" },
+    ],
+    system: `# SVG Maker
+
+You are a **diagram author + renderer** for spatial and geometric pictures. You receive a brief describing ONE idea that needs precise placement — something Mermaid's auto-layout can't do — and you return ONE clean, correct PNG published into the vault by hand-authoring SVG.
+
+You do NOT decide *what* idea to show — the caller (a teacher) already decided that, and you must preserve it exactly. Your job is faithful, precise composition, and — above everything — **correctness**: the picture must not assert anything false. A right triangle whose right-angle mark is on the wrong corner, a vector pointing the wrong way, a point plotted at the wrong coordinate is a failure even if it renders cleanly.
+
+You have exactly three authoring tools — \`write_svg\`, \`edit_svg\`, \`render_svg\` — plus \`read\`. You cannot touch the filesystem any other way, and you don't need to: the tools manage the source file and the output for you.
+
+## Your superpower: exact control
+
+Unlike auto-laid-out diagrams, you place every element at coordinates you choose, so what you write is exactly what appears — fully deterministic. That precision is the whole reason to use SVG. It also means correctness is entirely on you: do the geometry deliberately, and verify it by looking.
+
+## The one rule that matters most: verify by looking
+
+You are done only when you have **looked at the rendered PNG and confirmed it is true to the brief**. \`render_svg\` returns the PNG's absolute path — open it with the \`read\` tool and actually look at it. Rendering success only proves the SVG parsed; it says nothing about whether the geometry is right or the picture is readable.
+
+## Workflow (the render-and-inspect loop)
+
+1. **Plan the coordinate space.** Choose a \`viewBox\` and sketch where each element sits before drawing. Leave margins so nothing touches the edge. Keep it to ONE idea and few elements.
+2. **Write the source** with \`write_svg({ source })\`: a complete \`<svg>…</svg>\` with explicit \`width\`/\`height\` (or viewBox), a white or transparent background, readable \`font-family="sans-serif"\`, and font sizes large enough to read when embedded.
+3. **Render a preview** with \`render_svg({})\` (no \`save_as\`), then open the returned PNG path with \`read\` and look at it.
+4. **LOOK critically:**
+   - Is every coordinate, angle, direction, and proportion actually correct? Re-derive the geometry if unsure.
+   - Are labels placed clearly, not overlapping lines or each other?
+   - Is anything clipped by the viewBox, too small to read, or cramped?
+   - Would the learner instantly read the intended idea from this picture alone?
+5. **Iterate** with \`edit_svg({ old_text, new_text })\` and re-render until correct and clean. If \`render_svg\` returns an error, read it, fix the source, re-render.
+6. **Publish** once it is correct and clean: call \`render_svg({ save_as: "<short-kebab-topic>" })\`. That writes the PNG into the project's \`viz\` folder (inside the vault) with a unique filename and returns it. Open the published image with \`read\` one last time.
+
+## Your output
+
+End your response with EXACTLY this block (nothing after it):
+
+\`\`\`
+RESULT:
+filename: <the viz-...-<timestamp>.png filename returned by render_svg>
+path: <the absolute path returned by render_svg>
+\`\`\`
+
+If you genuinely cannot make a correct, sensible picture of the brief, return:
+
+\`\`\`
+RESULT:
+NONE
+\`\`\`
+
+with a one-line reason (e.g. the idea is purely relational and belongs to the mermaid-maker).
+
+## Guidelines
+
+- **Correctness is non-negotiable.** Never publish a picture you have not looked at. Do the arithmetic/geometry deliberately; don't eyeball positions that need to be exact.
+- **One idea, fewest elements.** Sparse and large beats busy and tiny.
+- **Draw only what the brief specifies.** Don't invent data points, values, or shapes to fill space.
+- **Keep type legible.** Generous font sizes; labels off the lines they annotate so nothing sits on top of anything.
+- **Prefer plain, clean styling.** A light background, dark strokes, one accent color at most. This is an explanatory diagram, not art.`,
+  },
+  {
+    name: "mermaid-maker",
+    description: "Authors ONE Mermaid diagram from a brief, renders it to a PNG, LOOKS at the result, iterates until it is correct and clean, publishes the PNG into the Obsidian vault, and returns the filename. For structural/relational visuals — dependency graphs, flows, sequences, state machines, trees, ER, timelines.",
+    steps: 24,
+    permissions: [
+      { action: "*", resource: "*", effect: "deny" },
+      { action: "external_directory", resource: "/tmp/opencode/**", effect: "allow" },
+      { action: "read", resource: "*", effect: "allow" },
+      { action: "write_mermaid", resource: "*", effect: "allow" },
+      { action: "edit_mermaid", resource: "*", effect: "allow" },
+      { action: "render_mermaid", resource: "*", effect: "allow" },
+    ],
+    system: `# Mermaid Maker
+
+You are a **diagram author + renderer**. You receive a brief describing ONE idea to visualize as a Mermaid diagram, and you return ONE clean, correct PNG published into the vault.
+
+You do NOT decide *what* idea to show — the caller (a teacher) already decided that, and you must preserve it exactly. Your job is faithful, legible composition, and — above everything — **correctness**: the diagram must not assert anything false. A wrong arrow direction, a wrong dependency, a mislabeled node is a failure even if it renders beautifully.
+
+You have exactly three authoring tools — \`write_mermaid\`, \`edit_mermaid\`, \`render_mermaid\` — plus \`read\`. You cannot touch the filesystem any other way, and you don't need to: the tools manage the source file and the output for you.
+
+## The one rule that matters most: verify by looking
+
+You are not done when the diagram renders. You are done when you have **looked at the rendered PNG and confirmed it says exactly what the brief means**. \`render_mermaid\` returns the PNG's absolute path — open it with the \`read\` tool and actually look at it. Rendering success only proves the syntax parsed; it says nothing about whether the picture is true or readable.
+
+## Workflow (the render-and-inspect loop)
+
+1. **Understand the idea, then cut.** A brief is a wish-list, not a spec. Keep the idea intact but drop any node/label that doesn't earn its place. If you're about to draw more than ~7 nodes, stop and simplify — a diagram of 4 nodes that each pull weight beats one of 12 that fight for space. Cramming is the #1 way these fail.
+2. **Write the source** with \`write_mermaid({ source })\`. Pick the diagram type that fits: \`graph TD\`/\`LR\` (dependency graphs, flows), \`sequenceDiagram\`, \`stateDiagram-v2\`, \`erDiagram\`, \`mindmap\`, \`timeline\`, \`classDiagram\`.
+3. **Render a preview** with \`render_mermaid({})\` (no \`save_as\`), then open the returned PNG path with \`read\` and look at it.
+4. **LOOK critically:**
+   - Is every arrow pointing the right way? Is every dependency/relationship actually true to the brief?
+   - Are the labels correct and unambiguous?
+   - Is anything overlapping, clipped, cramped, or unreadable? If so the fix is usually **fewer elements**, not more.
+   - Would the learner instantly read the intended idea from this picture alone?
+5. **Iterate** with \`edit_mermaid({ old_text, new_text })\` and re-render. A few passes is normal. If \`render_mermaid\` returns an error instead of a path, read it, fix the source, re-render.
+6. **Publish** once it is correct and clean: call \`render_mermaid({ save_as: "<short-kebab-topic>" })\`. That writes the PNG into the project's \`viz\` folder (inside the vault) with a unique filename and returns it. Open the published image with \`read\` one last time.
+
+## Your output
+
+End your response with EXACTLY this block (nothing after it):
+
+\`\`\`
+RESULT:
+filename: <the viz-...-<timestamp>.png filename returned by render_mermaid>
+path: <the absolute path returned by render_mermaid>
+\`\`\`
+
+If you genuinely cannot make a correct, sensible diagram of the brief, return:
+
+\`\`\`
+RESULT:
+NONE
+\`\`\`
+
+with a one-line reason (e.g. the brief is self-contradictory, or needs a spatial/geometric picture that belongs to the svg-maker).
+
+## Guidelines
+
+- **Correctness is non-negotiable.** Never publish a diagram you have not looked at. If unsure whether an edge is true, it's better to omit it than to assert something false.
+- **One idea, fewest elements.** Sparse beats busy — for both readability and layout reliability.
+- **Keep labels short.** Nodes hold a term or short phrase, not a sentence. Long labels wreck layout.
+- **Don't invent content.** Visualize only what the brief specifies. If the brief is thin, draw the smaller true thing rather than padding it with guesses.
+- **Match the pedagogy when it fits.** Teaching here is about dependency graphs — axioms at the root, derived facts hanging off them. \`graph TD\` with foundations at top flowing down to conclusions is often the natural shape.`,
+  },
+]
+
+export async function setupAgents(ctx: Plugin.Context): Promise<void> {
+  await ctx.agent.transform((editor) => {
+    for (const agent of AGENTS) {
+      editor.update(agent.name, (current) => {
+        current.description = agent.description
+        current.mode = "subagent"
+        current.steps = agent.steps
+        current.permissions = agent.permissions.map((rule) => ({ ...rule }))
+        current.system = agent.system
+      })
+    }
+  })
+}

package/plugins/index.ts

@@ -0,0 +1,23 @@
+import { Plugin } from "@opencode/plugin"
+import { setupAgents } from "./agents.ts"
+import { setupMdLink } from "./md-link/index.ts"
+import { setupQuiz } from "./quiz.ts"
+import { setupSkills } from "./skills.ts"
+import { setupViz } from "./viz/index.ts"
+
+export default Plugin.define({
+  id: "opencode-learn",
+  async setup(ctx) {
+    const cleanups: (Plugin.Cleanup | void)[] = []
+    cleanups.push(await setupAgents(ctx))
+    cleanups.push(await setupSkills(ctx))
+    cleanups.push(await setupViz(ctx))
+    cleanups.push(await setupQuiz(ctx))
+    cleanups.push(await setupMdLink(ctx))
+    return () => {
+      for (const cleanup of cleanups.reverse()) {
+        if (typeof cleanup === "function") cleanup()
+      }
+    }
+  },
+})

package/plugins/md-link/core.ts

@@ -0,0 +1,238 @@
+/**
+ * md-link core — single source of truth for the Obsidian live-mirror pair.
+ *
+ * Consumers:
+ *   plugins/md-link/index.ts (server: mirrors assistant replies)
+ *   plugins/md-link/tui.ts   (TUI: ctrl+alt+m / /md-link toggle)
+ *
+ * The package's `.` entry (plugins/index.ts) registers the server part; the
+ * TUI part loads through the package's `./tui` export (plugins/tui.ts).
+ *
+ * State file contract (~/.config/opencode/md-link-state.json):
+ *   {
+ *     "defaultDir": "/abs/dir" | null,          // fallback output dir
+ *     "keep": 25 | null,                        // prune mirrors to N newest replies
+ *     "sessions": { "<sessionID>": "/abs/dir" } // "" dir = use defaultDir
+ *     "persist": true|false                     // true = mirrors survive TUI exit
+ *   }
+ *
+ * With persist=true, TUI exit keeps this project's mirror files AND their
+ * session entries, so the event subscription resumes mirroring into the same
+ * files on the next launch. Explicit /md-link OFF always deletes regardless.
+ *
+ * Mirror file contract (<dir>/<sessionID>.md):
+ *   Contains ONLY response blocks — no frontmatter, titles, or separators:
+ *     <!-- msg:<assistantMessageID>#<ordinal> -->   (dedup marker, invisible
+ *     **HH:MM**                                      in Obsidian preview)
+ *
+ *     <reply text>
+ *
+ * The server re-reads the state file on every event so TUI toggles apply
+ * instantly; writers use read-modify-write to stay concurrency-safe.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync, appendFileSync } from "fs"
+import { dirname, join } from "path"
+import { homedir } from "os"
+
+export const STATE_FILE = join(homedir(), ".config", "opencode", "md-link-state.json")
+
+export type MdLinkState = {
+  defaultDir: string | null
+  keep: number | null
+  sessions: Record<string, string>
+  /** True = mirror files + session entries survive TUI exit (resume next launch). */
+  persist?: boolean
+}
+
+const EMPTY_STATE: MdLinkState = { defaultDir: null, keep: null, sessions: {}, persist: false }
+
+/** Read state, migrating legacy formats (plain array / {sessions:[...]}). */
+export function loadState(): MdLinkState {
+  try {
+    if (!existsSync(STATE_FILE)) return { ...EMPTY_STATE, sessions: {} }
+    const raw = JSON.parse(readFileSync(STATE_FILE, "utf-8"))
+
+    if (Array.isArray(raw)) {
+      const sessions: Record<string, string> = {}
+      for (const x of raw) if (typeof x === "string") sessions[x] = ""
+      return { ...EMPTY_STATE, sessions }
+    }
+    if (raw && typeof raw === "object") {
+      const sessions: Record<string, string> = {}
+      const s = (raw as any).sessions
+      if (s && typeof s === "object" && !Array.isArray(s)) {
+        for (const [k, v] of Object.entries(s)) {
+          if (typeof k === "string" && k && typeof v === "string") sessions[k] = v
+        }
+      } else if (Array.isArray(s)) {
+        for (const x of s) if (typeof x === "string") sessions[x] = ""
+      }
+      return {
+        defaultDir: typeof raw.defaultDir === "string" ? raw.defaultDir : null,
+        keep: typeof raw.keep === "number" && raw.keep >= 1 ? Math.floor(raw.keep) : null,
+        sessions,
+        persist: raw.persist === true,
+      }
+    }
+  } catch {}
+  return { ...EMPTY_STATE, sessions: {} }
+}
+
+/** Atomic-enough write for our scale (single writer per toggle, tiny file). */
+export function saveState(st: MdLinkState): void {
+  try {
+    mkdirSync(dirname(STATE_FILE), { recursive: true })
+    writeFileSync(STATE_FILE, JSON.stringify(st, null, 2), "utf-8")
+  } catch {}
+}
+
+export function isEnabled(st: MdLinkState, sessionID: string): boolean {
+  return sessionID in st.sessions
+}
+
+/** Add a session (read-modify-write). Preserves any dir already recorded. */
+export function enableSession(st: MdLinkState, sessionID: string, dir = ""): void {
+  if (!(sessionID in st.sessions)) st.sessions[sessionID] = dir
+  saveState(st)
+}
+
+/** Remove a session (read-modify-write). */
+export function disableSession(st: MdLinkState, sessionID: string): void {
+  delete st.sessions[sessionID]
+  saveState(st)
+}
+
+/** Resolve where a session's mirror lives. Falls back through recorded dir → defaultDir → fallbackDir. */
+export function mirrorFile(st: MdLinkState, sessionID: string, fallbackDir?: string): string | null {
+  let dir = st.sessions[sessionID] ?? ""
+  if (!dir && st.defaultDir) dir = st.defaultDir
+  if (!dir && fallbackDir) dir = fallbackDir
+  if (!dir) return null
+  return join(dir, `${sessionID}_link.md`)
+}
+
+/** Create an empty mirror file (responses only — zero boilerplate). No-op if it exists. */
+export function touchMirror(file: string): void {
+  if (existsSync(file)) return
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, "", "utf-8")
+}
+
+export type AppendResult = "written" | "updated" | "duplicate" | "failed"
+
+/** Extract full reply text from a /message item (shapes vary: content[] parts or flat text). */
+export function messageText(m: any): string {
+  let text = ""
+  if (Array.isArray(m?.content)) {
+    text = m.content
+      .filter((c: any) => c?.type === "text" && typeof c.text === "string")
+      .map((c: any) => c.text)
+      .join("\n")
+  }
+  if (!text && typeof m?.text === "string") text = m.text
+  return text.trim()
+}
+
+/** Skill declarations are system-injected context, not learner prose. */
+export function stripSkillBlocks(text: string): string {
+  return text.replace(/<skill\b([^>]*)>[\s\S]*?<\/skill>/g, (_m, attrs: string) => {
+    const name = /name="([^"]+)"/.exec(attrs)?.[1]
+    return `[SKILL loaded: ${name ?? "(unknown)"}]`
+  })
+}
+
+/** Obsidian callout block: `> [!type] title` + quoted body lines. */
+export function callout(type: string, title: string, bodyLines: string[]): string {
+  const lines = [`> [!${type}] ${title}`]
+  for (const line of bodyLines) lines.push(line.length === 0 ? ">" : `> ${line}`)
+  return lines.join("\n")
+}
+
+/** User-prompt block, identical for the live event path and history backfill. */
+export function userPromptBlock(text: string): string {
+  return callout("quote", "YOU", stripSkillBlocks(text.trim()).split("\n"))
+}
+
+/** True if the file contains a block whose marker starts with `<!-- msg:<key>` */
+export function hasBlock(file: string, key: string): boolean {
+  try {
+    return readFileSync(file, "utf-8").includes(`<!-- msg:${key}`)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Append one reply block, deduped/upserted by markerKey, then prune to `keep`.
+ * With replace=true, an existing block for the same key is rewritten when its
+ * text differs (used by the poller while replies are still streaming).
+ * Block format (see module doc): marker comment, local HH:MM, blank line, text.
+ */
+export function appendMessage(
+  file: string,
+  opts: { text: string; markerKey?: string | null; replace?: boolean },
+  keep: number | null,
+): AppendResult {
+  const key = opts.markerKey ?? null
+  try {
+    if (key && hasBlock(file, key)) {
+      if (!opts.replace) return "duplicate"
+      return replaceBlock(file, key, opts.text) ? "updated" : "duplicate"
+    }
+    if (key === null && hasBlockLoose(file, opts.text)) return "duplicate"
+    const time = clock()
+    const marker = key ? `<!-- msg:${key} -->\n` : ""
+    appendFileSync(file, `${marker}**${time}**\n\n${opts.text.trim()}\n\n`, "utf-8")
+    pruneMirror(file, keep)
+    return "written"
+  } catch {
+    return "failed"
+  }
+}
+
+function hasBlockLoose(file: string, text: string): boolean {
+  try {
+    return readFileSync(file, "utf-8").includes(text.trim().slice(0, 80))
+  } catch {
+    return false
+  }
+}
+
+function clock(): string {
+  return new Date().toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" })
+}
+
+/** Rewrite an existing block's text in place. Returns false if unchanged/not found. */
+function replaceBlock(file: string, key: string, text: string): boolean {
+  const c = readFileSync(file, "utf-8")
+  const first = c.search(/<!-- msg:/)
+  if (first === -1) return false
+  const head = c.slice(0, first)
+  const blocks = c.slice(first).split(/(?=<!-- msg:)/g).filter((b) => b.trim().length > 0)
+  const idx = blocks.findIndex((b) => b.startsWith(`<!-- msg:${key}`))
+  if (idx === -1) return false
+  const fresh = `<!-- msg:${key} -->\n**${clock()}**\n\n${text.trim()}\n\n`
+  const norm = (s: string) => s.replace(/\s+/g, " ").trim()
+  if (norm(blocks[idx]) === norm(fresh)) return false
+  blocks[idx] = fresh
+  writeFileSync(file, head + blocks.join(""), "utf-8")
+  return true
+}
+
+/** Keep only the newest `keep` reply blocks. keep <= 0/null = unlimited. */
+export function pruneMirror(file: string, keep: number | null): void {
+  try {
+    if (!keep || keep < 1) return
+    const c = readFileSync(file, "utf-8")
+    const first = c.search(/<!-- msg:/)
+    if (first === -1) return
+    const head = c.slice(0, first)
+    const blocks = c
+      .slice(first)
+      .split(/(?=<!-- msg:)/g)
+      .filter((b) => b.trim().length > 0)
+    if (blocks.length <= keep) return
+    writeFileSync(file, head + blocks.slice(-keep).join(""), "utf-8")
+  } catch {}
+}