opencode-convodump 0.0.1

package/.opencode/plugins/convodump.ts

@@ -0,0 +1,876 @@
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+const SERVICE_NAME = "opencode-convodump"
+type UnknownRecord = Record<string, unknown>
+
+type SessionState = {
+  queue: Promise<void>
+  scheduled?: boolean
+  pendingTrigger?: string
+  lastWriteAt?: number
+  lastFingerprint?: string
+  cachedSnapshot?: SessionSnapshot
+  prefetching?: Promise<void>
+  lastPrefetchAt?: number
+}
+
+type SessionSnapshot = {
+  session: UnknownRecord
+  messages: unknown[]
+  todos: unknown
+  diff: unknown
+}
+
+function normaliseNewlines(value: string): string {
+  return value.replace(/\r\n?/g, "\n")
+}
+
+function asString(value: unknown, fallback = ""): string {
+  if (typeof value === "string") return value
+  if (value === null || value === undefined) return fallback
+  return String(value)
+}
+
+function asObject(value: unknown): UnknownRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {}
+  return value as UnknownRecord
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function bindMethod<T extends (...args: any[]) => any>(target: unknown, key: string): T | null {
+  if (!target || (typeof target !== "object" && typeof target !== "function")) return null
+  const candidate = (target as Record<string, unknown>)[key]
+  if (typeof candidate !== "function") return null
+  return candidate.bind(target) as T
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | null> {
+  return Promise.race([
+    promise.catch(() => null as T | null),
+    new Promise<null>((resolve) => setTimeout(() => resolve(null), timeoutMs)),
+  ])
+}
+
+function parseDate(value: unknown): Date | null {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    const asMillis = value < 1_000_000_000_000 ? value * 1000 : value
+    const parsed = new Date(asMillis)
+    return Number.isNaN(parsed.getTime()) ? null : parsed
+  }
+
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = new Date(value)
+    return Number.isNaN(parsed.getTime()) ? null : parsed
+  }
+
+  return null
+}
+
+function toISO(value: unknown): string | null {
+  const parsed = parseDate(value)
+  return parsed ? parsed.toISOString() : null
+}
+
+function formatFilenameTimestamp(value: unknown): string {
+  const parsed = parseDate(value) ?? new Date()
+  const year = parsed.getFullYear().toString().padStart(4, "0")
+  const month = (parsed.getMonth() + 1).toString().padStart(2, "0")
+  const day = parsed.getDate().toString().padStart(2, "0")
+  const hour = parsed.getHours().toString().padStart(2, "0")
+  const minute = parsed.getMinutes().toString().padStart(2, "0")
+  const second = parsed.getSeconds().toString().padStart(2, "0")
+  return `${year}-${month}-${day}-${hour}-${minute}-${second}`
+}
+
+function sanitiseFilename(value: string): string {
+  const safe = value.replace(/[^a-zA-Z0-9._-]/g, "_")
+  return safe || "unknown-session"
+}
+
+function quoteYamlString(value: string): string {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+  return `"${escaped}"`
+}
+
+function writeYamlPair(lines: string[], key: string, value: unknown, indent: number): void {
+  const pad = " ".repeat(indent)
+
+  if (value === null || value === undefined) {
+    lines.push(`${pad}${key}: null`)
+    return
+  }
+
+  if (typeof value === "string") {
+    if (value.includes("\n")) {
+      lines.push(`${pad}${key}: |-`)
+      for (const segment of value.split("\n")) {
+        lines.push(`${pad}  ${segment}`)
+      }
+    } else {
+      lines.push(`${pad}${key}: ${quoteYamlString(value)}`)
+    }
+    return
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    lines.push(`${pad}${key}: ${String(value)}`)
+    return
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      lines.push(`${pad}${key}: []`)
+      return
+    }
+
+    lines.push(`${pad}${key}:`)
+    for (const item of value) {
+      writeYamlArrayItem(lines, item, indent + 2)
+    }
+    return
+  }
+
+  const objectValue = asObject(value)
+  const entries = Object.entries(objectValue)
+  if (entries.length === 0) {
+    lines.push(`${pad}${key}: {}`)
+    return
+  }
+
+  lines.push(`${pad}${key}:`)
+  for (const [childKey, childValue] of entries) {
+    writeYamlPair(lines, childKey, childValue, indent + 2)
+  }
+}
+
+function writeYamlArrayItem(lines: string[], value: unknown, indent: number): void {
+  const pad = " ".repeat(indent)
+
+  if (value === null || value === undefined) {
+    lines.push(`${pad}- null`)
+    return
+  }
+
+  if (typeof value === "string") {
+    if (value.includes("\n")) {
+      lines.push(`${pad}- |-`)
+      for (const segment of value.split("\n")) {
+        lines.push(`${pad}  ${segment}`)
+      }
+    } else {
+      lines.push(`${pad}- ${quoteYamlString(value)}`)
+    }
+    return
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    lines.push(`${pad}- ${String(value)}`)
+    return
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      lines.push(`${pad}- []`)
+      return
+    }
+
+    lines.push(`${pad}-`)
+    for (const item of value) {
+      writeYamlArrayItem(lines, item, indent + 2)
+    }
+    return
+  }
+
+  const objectValue = asObject(value)
+  const entries = Object.entries(objectValue)
+  if (entries.length === 0) {
+    lines.push(`${pad}- {}`)
+    return
+  }
+
+  let first = true
+  for (const [key, child] of entries) {
+    if (first) {
+      if (
+        child === null ||
+        child === undefined ||
+        typeof child === "string" ||
+        typeof child === "number" ||
+        typeof child === "boolean"
+      ) {
+        if (typeof child === "string" && child.includes("\n")) {
+          lines.push(`${pad}- ${key}: |-`)
+          for (const segment of child.split("\n")) {
+            lines.push(`${pad}    ${segment}`)
+          }
+        } else if (child === null || child === undefined) {
+          lines.push(`${pad}- ${key}: null`)
+        } else if (typeof child === "string") {
+          lines.push(`${pad}- ${key}: ${quoteYamlString(child)}`)
+        } else {
+          lines.push(`${pad}- ${key}: ${String(child)}`)
+        }
+      } else {
+        lines.push(`${pad}- ${key}:`)
+        if (Array.isArray(child)) {
+          if (child.length === 0) {
+            lines.push(`${pad}    []`)
+          } else {
+            for (const nested of child) {
+              writeYamlArrayItem(lines, nested, indent + 4)
+            }
+          }
+        } else {
+          const nestedEntries = Object.entries(asObject(child))
+          if (nestedEntries.length === 0) {
+            lines.push(`${pad}    {}`)
+          } else {
+            for (const [nestedKey, nestedValue] of nestedEntries) {
+              writeYamlPair(lines, nestedKey, nestedValue, indent + 4)
+            }
+          }
+        }
+      }
+      first = false
+      continue
+    }
+
+    writeYamlPair(lines, key, child, indent + 2)
+  }
+}
+
+function toYaml(value: UnknownRecord): string {
+  const lines: string[] = []
+  for (const [key, child] of Object.entries(value)) {
+    writeYamlPair(lines, key, child, 0)
+  }
+  return lines.join("\n")
+}
+
+function sortForStableJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortForStableJson)
+  if (!value || typeof value !== "object") return value
+
+  const sorted: UnknownRecord = {}
+  const entries = Object.entries(value as UnknownRecord).sort(([a], [b]) => a.localeCompare(b))
+  for (const [key, child] of entries) {
+    sorted[key] = sortForStableJson(child)
+  }
+  return sorted
+}
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(sortForStableJson(value), null, 2)
+}
+
+function snapshotFingerprint(snapshot: SessionSnapshot): string {
+  return stableJson({
+    session: snapshot.session,
+    messages: snapshot.messages,
+    todos: snapshot.todos,
+    diff: snapshot.diff,
+  })
+}
+
+function chooseTrigger(existing: string | undefined, incoming: string): string {
+  if (!existing) return incoming
+  if (existing === "session.status:idle") return existing
+  if (incoming === "session.status:idle") return incoming
+  return incoming
+}
+
+function codeFence(content: string): string {
+  let longest = 2
+  for (const match of content.matchAll(/`+/g)) {
+    const runLength = match[0]?.length ?? 0
+    if (runLength > longest) longest = runLength
+  }
+  return "`".repeat(longest + 1)
+}
+
+function renderCodeBlock(content: string, language = ""): string {
+  const clean = normaliseNewlines(content)
+  const fence = codeFence(clean)
+  const suffix = language ? language : ""
+  return `${fence}${suffix}\n${clean}\n${fence}`
+}
+
+function resolveSessionIdFromEvent(event: UnknownRecord): string | null {
+  const props = asObject(event.properties)
+  const session = asObject(props.session)
+
+  const candidate =
+    props.sessionID ??
+    props.sessionId ??
+    props.id ??
+    props.session_id ??
+    session.id ??
+    session.sessionID ??
+    session.sessionId
+
+  if (typeof candidate !== "string" || candidate.trim() === "") return null
+  return candidate
+}
+
+function getMessageRole(message: unknown): string {
+  const msg = asObject(message)
+  const info = asObject(msg.info)
+  const role = msg.role ?? info.role ?? info.type
+  return asString(role, "unknown")
+}
+
+function buildFrontmatter(session: UnknownRecord): UnknownRecord {
+  const time = asObject(session.time)
+
+  return {
+    session_id: session.id ?? null,
+    title: session.title ?? null,
+    created_at: toISO(time.created ?? session.createdAt ?? session.created_at),
+    updated_at: toISO(time.updated ?? session.updatedAt ?? session.updated_at),
+  }
+}
+
+function truncateText(value: string, maxChars = 5000): string {
+  const normalised = normaliseNewlines(value)
+  if (normalised.length <= maxChars) return normalised
+
+  const omitted = normalised.length - maxChars
+  return `${normalised.slice(0, maxChars)}\n\n... [truncated ${omitted} chars]`
+}
+
+function renderQuoteBlock(value: string, maxChars = 7000): string {
+  const text = truncateText(value, maxChars)
+  if (text.trim() === "") return ">"
+
+  return text
+    .split("\n")
+    .map((line) => (line === "" ? ">" : `> ${line}`))
+    .join("\n")
+}
+
+function renderPlainText(value: string, maxChars = 7000): string {
+  return truncateText(value, maxChars).trim()
+}
+
+function truncateInlineText(value: string, maxChars: number): string {
+  const flattened = normaliseNewlines(value).replace(/\s+/g, " ").trim()
+  if (flattened.length <= maxChars) return flattened
+  if (maxChars <= 3) return "..."
+  return `${flattened.slice(0, maxChars - 3)}...`
+}
+
+function compactToolJsonValue(value: unknown, baseLimit: number, depth = 0): unknown {
+  if (value === null || value === undefined) return null
+
+  if (typeof value === "string") {
+    const maxChars = Math.max(16, baseLimit - depth * 4)
+    return truncateInlineText(value, maxChars)
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") return value
+
+  if (Array.isArray(value)) {
+    const limit = 16
+    const items = value.slice(0, limit).map((item) => compactToolJsonValue(item, baseLimit, depth + 1))
+    if (value.length > limit) {
+      items.push(`... (${value.length - limit} more items)`)
+    }
+    return items
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(asObject(value))
+    const limit = 24
+    const result: UnknownRecord = {}
+
+    for (const [key, child] of entries.slice(0, limit)) {
+      result[key] = compactToolJsonValue(child, baseLimit, depth + 1)
+    }
+
+    if (entries.length > limit) {
+      result._truncated = `${entries.length - limit} additional keys`
+    }
+
+    return result
+  }
+
+  return asString(value)
+}
+
+function formatToolCallJson(value: UnknownRecord): string {
+  for (const limit of [56, 48, 40, 32, 24]) {
+    const compact = compactToolJsonValue(value, limit)
+    const rendered = JSON.stringify(compact, null, 2)
+    if (rendered.split("\n").every((line) => line.length <= 80)) {
+      return rendered
+    }
+  }
+
+  return JSON.stringify(compactToolJsonValue(value, 20), null, 2)
+}
+
+function renderCompactJson(value: unknown, maxChars = 3200): string {
+  const raw = typeof value === "string" ? value : stableJson(value)
+  const language = typeof value === "string" ? "text" : "json"
+  return renderCodeBlock(truncateText(raw, maxChars), language)
+}
+
+function hasContent(value: unknown): boolean {
+  if (value === null || value === undefined) return false
+  if (typeof value === "string") return value.trim() !== ""
+  if (Array.isArray(value)) return value.length > 0
+  if (typeof value === "object") return Object.keys(asObject(value)).length > 0
+  return true
+}
+
+function formatRole(role: string): string {
+  if (!role) return "Unknown"
+  if (role.toLowerCase() === "assistant") return "Agent"
+  return `${role.charAt(0).toUpperCase()}${role.slice(1)}`
+}
+
+function renderPart(part: UnknownRecord): string {
+  const type = asString(part.type, "unknown")
+  const section: string[] = []
+
+  if (type === "text") {
+    const text = renderPlainText(asString(part.text ?? part.content, ""))
+    if (text) section.push(text)
+
+    const flags: string[] = []
+    if (part.synthetic === true) flags.push("synthetic")
+    if (part.ignored === true) flags.push("ignored")
+    if (flags.length > 0) {
+      section.push("")
+      section.push(`_(${flags.join(", ")})_`)
+    }
+  } else if (type === "reasoning") {
+    const thinking = asString(part.text ?? part.reasoning ?? part.content, "")
+    if (thinking.trim() !== "") {
+      section.push(renderQuoteBlock(thinking, 12000))
+    }
+  } else if (type === "tool") {
+    const state = asObject(part.state)
+    const toolInput = part.input ?? part.arguments ?? part.args ?? state.input ?? null
+    const toolResult = part.output ?? part.result ?? state.output
+    const toolError = part.error ?? state.error
+    const toolAttachments = part.attachments ?? state.attachments
+
+    const outputPayload: UnknownRecord = {}
+    if (hasContent(toolResult)) outputPayload.result = toolResult
+    if (hasContent(toolError)) outputPayload.error = toolError
+    if (hasContent(toolAttachments)) outputPayload.attachments = toolAttachments
+
+    const toolCall: UnknownRecord = {
+      tool: asString(part.tool ?? part.name ?? part.toolName, "unknown"),
+      input: toolInput,
+      output: Object.keys(outputPayload).length > 0 ? outputPayload : null,
+    }
+
+    section.push(renderCodeBlock(formatToolCallJson(toolCall), "json"))
+  } else if (type === "file") {
+    section.push(`File \`${asString(part.filename ?? part.name, "unknown")}\` (${asString(part.mime ?? part.mimeType, "unknown")})`)
+    if (part.url) section.push(`- URL: ${asString(part.url)}`)
+    if (part.source !== undefined) {
+      section.push("- Source:")
+      section.push(renderCompactJson(part.source, 1800))
+    }
+  } else if (type === "subtask") {
+    section.push(`Subtask \`${asString(part.agent, "unknown")}\` (${asString(part.model, "unknown")})`)
+
+    const command = asString(part.command, "")
+    if (command) section.push(`- Command: \`${command}\``)
+
+    if (part.description !== undefined) {
+      section.push("")
+      section.push("Description:")
+      section.push(renderQuoteBlock(asString(part.description, ""), 6000))
+    }
+
+    if (part.prompt !== undefined) {
+      section.push("")
+      section.push("Prompt:")
+      section.push(renderQuoteBlock(asString(part.prompt, ""), 6000))
+    }
+  } else if (type === "step-start" || type === "step-finish") {
+    return ""
+  } else {
+    section.push(`${type}:`)
+    section.push("")
+    section.push("Details:")
+    section.push(renderCompactJson(part, 2200))
+  }
+
+  return section.join("\n")
+}
+
+function renderMessage(message: unknown, index: number): string {
+  const msg = asObject(message)
+  const parts = asArray(msg.parts)
+  const role = getMessageRole(msg)
+  void index
+
+  const section: string[] = []
+  section.push(`### ${formatRole(role)}`)
+  section.push("")
+
+  if (parts.length === 0) {
+    section.push("_No content._")
+    return section.join("\n")
+  }
+
+  let hasRenderedPart = false
+
+  for (let i = 0; i < parts.length; i += 1) {
+    const renderedPart = renderPart(asObject(parts[i]))
+    if (!renderedPart) continue
+
+    if (hasRenderedPart) section.push("")
+    section.push(renderedPart)
+    hasRenderedPart = true
+  }
+
+  if (!hasRenderedPart) {
+    section.push("_No content._")
+  }
+
+  return section.join("\n")
+}
+
+function renderMarkdown(snapshot: SessionSnapshot, trigger: string, ctx: UnknownRecord): string {
+  const session = snapshot.session
+  const messages = snapshot.messages
+
+  void trigger
+  void ctx
+
+  const frontmatter = buildFrontmatter(session)
+
+  const content: string[] = []
+  content.push("---")
+  content.push(toYaml(frontmatter))
+  content.push("---")
+
+  if (messages.length === 0) {
+    content.push("")
+    content.push("_No messages yet._")
+  } else {
+    for (let i = 0; i < messages.length; i += 1) {
+      if (i > 0) {
+        content.push("")
+        content.push("---")
+      }
+
+      content.push("")
+      content.push(renderMessage(messages[i], i))
+    }
+  }
+
+  return normaliseNewlines(content.join("\n"))
+}
+
+async function atomicWrite(filePath: string, content: string): Promise<number> {
+  const dirPath = path.dirname(filePath)
+  await mkdir(dirPath, { recursive: true })
+
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  const normalised = normaliseNewlines(content)
+
+  await writeFile(tmpPath, normalised, "utf8")
+
+  try {
+    await rename(tmpPath, filePath)
+  } catch (error) {
+    await unlink(tmpPath).catch(() => undefined)
+    throw error
+  }
+
+  return Buffer.byteLength(normalised, "utf8")
+}
+
+async function fetchSessionSnapshot(ctx: UnknownRecord, sessionID: string): Promise<SessionSnapshot> {
+  const client = asObject(ctx.client)
+  const sessionClient = client.session
+
+  const get = bindMethod<(arg: unknown) => Promise<{ data: unknown }>>(sessionClient, "get")
+  const messages = bindMethod<(arg: unknown) => Promise<{ data: unknown }>>(sessionClient, "messages")
+  const todo = bindMethod<(arg: unknown) => Promise<{ data: unknown }>>(sessionClient, "todo")
+  const diff = bindMethod<(arg: unknown) => Promise<{ data: unknown }>>(sessionClient, "diff")
+
+  if (typeof get !== "function" || typeof messages !== "function") {
+    throw new Error("Session API unavailable on plugin context")
+  }
+
+  const [sessionResult, messagesResult, todoResult, diffResult] = await Promise.all([
+    get({ path: { id: sessionID } }),
+    messages({ path: { id: sessionID } }),
+    typeof todo === "function"
+      ? todo({ path: { id: sessionID } }).catch(() => ({ data: null }))
+      : Promise.resolve({ data: null }),
+    typeof diff === "function"
+      ? diff({ path: { id: sessionID } }).catch(() => ({ data: null }))
+      : Promise.resolve({ data: null }),
+  ])
+
+  const session = asObject(sessionResult?.data)
+  if (!session.id) {
+    throw new Error(`Session not found for id '${sessionID}'`)
+  }
+
+  return {
+    session,
+    messages: asArray(messagesResult?.data),
+    todos: todoResult?.data ?? null,
+    diff: diffResult?.data ?? null,
+  }
+}
+
+function resolveOutputRoot(ctx: UnknownRecord, session: UnknownRecord): string {
+  const sessionWorktree = asString(session.worktree, "")
+  if (sessionWorktree && sessionWorktree !== "/") return sessionWorktree
+
+  const ctxWorktree = asString(ctx.worktree, "")
+  if (ctxWorktree && ctxWorktree !== "/") return ctxWorktree
+
+  const sessionDirectory = asString(session.directory, "")
+  if (sessionDirectory) return sessionDirectory
+
+  const ctxDirectory = asString(ctx.directory, "")
+  if (ctxDirectory) return ctxDirectory
+
+  return process.cwd()
+}
+
+function resolveOutputPath(snapshot: SessionSnapshot, outputRoot: string): string {
+  const session = snapshot.session
+  const time = asObject(session.time)
+  const created = time.created ?? session.createdAt ?? session.created_at
+  const timestamp = formatFilenameTimestamp(created)
+  const id = sanitiseFilename(asString(session.id, "unknown-session"))
+
+  return path.join(outputRoot, "convos", `${timestamp}-${id}.md`)
+}
+
+async function logEvent(ctx: UnknownRecord, level: string, message: string, extra: UnknownRecord = {}): Promise<void> {
+  const client = asObject(ctx.client)
+  const logger = bindMethod<(arg: unknown) => Promise<unknown>>(client.app, "log")
+
+  if (typeof logger === "function") {
+    await logger({
+      body: {
+        service: SERVICE_NAME,
+        level,
+        message,
+        ...extra,
+      },
+    }).catch(() => undefined)
+    return
+  }
+
+  if (level === "error" || process.env.OPENCODE_CONVODUMP_DEBUG === "1" || process.env.OPENCODE_CONVODUMP_DEBUG === "true") {
+    const serialised = Object.keys(extra).length > 0 ? ` ${stableJson(extra)}` : ""
+    console.error(`[${SERVICE_NAME}] ${level} ${message}${serialised}`)
+  }
+}
+
+export const ConvoDumpPlugin = async (ctx: UnknownRecord) => {
+  const state = new Map<string, SessionState>()
+  const debug = process.env.OPENCODE_CONVODUMP_DEBUG === "1" || process.env.OPENCODE_CONVODUMP_DEBUG === "true"
+
+  if (debug) {
+    const sessionClient = asObject(ctx.client).session
+    console.error(
+      `[${SERVICE_NAME}] init hasGet=${String(Boolean(bindMethod(sessionClient, "get")))} hasMessages=${String(Boolean(bindMethod(sessionClient, "messages")))} hasTodo=${String(Boolean(bindMethod(sessionClient, "todo")))} hasDiff=${String(Boolean(bindMethod(sessionClient, "diff")))}`,
+    )
+  }
+
+  function sessionState(sessionID: string): SessionState {
+    const existing = state.get(sessionID)
+    if (existing) return existing
+
+    const created: SessionState = { queue: Promise.resolve() }
+    state.set(sessionID, created)
+    return created
+  }
+
+  function schedule(sessionID: string, trigger: string): void {
+    const entry = sessionState(sessionID)
+    entry.pendingTrigger = chooseTrigger(entry.pendingTrigger, trigger)
+    if (debug) {
+      console.error(`[${SERVICE_NAME}] schedule session=${sessionID} trigger=${trigger} pending=${entry.pendingTrigger}`)
+    }
+
+    if (entry.scheduled) return
+    entry.scheduled = true
+
+    entry.queue = entry.queue
+      .then(async () => {
+        const enqueueTrigger = entry.pendingTrigger ?? trigger
+        entry.pendingTrigger = undefined
+
+        const hold = setInterval(() => undefined, 50)
+        const start = Date.now()
+        try {
+          if (debug) {
+            console.error(`[${SERVICE_NAME}] export begin session=${sessionID} trigger=${enqueueTrigger}`)
+          }
+          void logEvent(ctx, "info", "export.started", { sessionID, trigger: enqueueTrigger })
+
+          let snapshot = entry.cachedSnapshot
+          if (snapshot) {
+            const refreshed = await withTimeout(fetchSessionSnapshot(ctx, sessionID), 120)
+            if (refreshed) {
+              snapshot = refreshed
+              entry.cachedSnapshot = refreshed
+            } else if (debug) {
+              console.error(`[${SERVICE_NAME}] export refresh timed out, using cached snapshot session=${sessionID}`)
+            }
+          } else {
+            snapshot = await fetchSessionSnapshot(ctx, sessionID)
+            entry.cachedSnapshot = snapshot
+          }
+
+          if (!snapshot) {
+            throw new Error(`No snapshot available for session '${sessionID}'`)
+          }
+
+          const fingerprint = snapshotFingerprint(snapshot)
+          if (entry.lastFingerprint === fingerprint) {
+            if (debug) {
+              console.error(`[${SERVICE_NAME}] export skipped unchanged session=${sessionID}`)
+            }
+            void logEvent(ctx, "info", "export.skipped.unchanged", {
+              sessionID,
+              trigger: enqueueTrigger,
+              duration_ms: Date.now() - start,
+            })
+            return
+          }
+
+          const outputRoot = resolveOutputRoot(ctx, snapshot.session)
+          const filePath = resolveOutputPath(snapshot, outputRoot)
+          const markdown = renderMarkdown(snapshot, enqueueTrigger, ctx)
+          const bytes = await atomicWrite(filePath, markdown)
+
+          entry.lastWriteAt = Date.now()
+          entry.lastFingerprint = fingerprint
+          if (debug) {
+            console.error(`[${SERVICE_NAME}] export wrote session=${sessionID} file=${filePath} bytes=${bytes}`)
+          }
+          void logEvent(ctx, "info", "export.completed", {
+            sessionID,
+            trigger: enqueueTrigger,
+            filePath,
+            bytes,
+            duration_ms: Date.now() - start,
+            last_write_at: entry.lastWriteAt,
+          })
+        } finally {
+          clearInterval(hold)
+          entry.scheduled = false
+          if (entry.pendingTrigger) {
+            schedule(sessionID, entry.pendingTrigger)
+          }
+        }
+      })
+      .catch(async (error) => {
+        entry.scheduled = false
+        const errorMessage = asString((error as Error)?.stack ?? (error as Error)?.message ?? error)
+        if (debug) {
+          console.error(`[${SERVICE_NAME}] export failed session=${sessionID} error=${errorMessage}`)
+        }
+        void logEvent(ctx, "error", "export.failed", {
+          sessionID,
+          trigger: entry.pendingTrigger ?? trigger,
+          error: errorMessage,
+        })
+
+        if (entry.pendingTrigger) {
+          schedule(sessionID, entry.pendingTrigger)
+        }
+      })
+  }
+
+  function prefetchSnapshot(sessionID: string, reason: string): void {
+    const entry = sessionState(sessionID)
+    const now = Date.now()
+
+    if (entry.prefetching) return
+    if (entry.lastPrefetchAt && now - entry.lastPrefetchAt < 300) return
+
+    entry.lastPrefetchAt = now
+    entry.prefetching = fetchSessionSnapshot(ctx, sessionID)
+      .then((snapshot) => {
+        entry.cachedSnapshot = snapshot
+        if (debug) {
+          console.error(`[${SERVICE_NAME}] prefetched session=${sessionID} reason=${reason}`)
+        }
+      })
+      .catch((error) => {
+        if (debug) {
+          console.error(`[${SERVICE_NAME}] prefetch failed session=${sessionID} reason=${reason} error=${asString((error as Error)?.message ?? error)}`)
+        }
+      })
+      .finally(() => {
+        entry.prefetching = undefined
+      })
+  }
+
+  return {
+    event: async (payload: unknown) => {
+      try {
+        const payloadObject = asObject(payload)
+        const nestedEvent = asObject(payloadObject.event)
+        const event = Object.keys(nestedEvent).length > 0 ? nestedEvent : payloadObject
+
+        const type = asString(event.type)
+        const sessionID = resolveSessionIdFromEvent(event)
+        if (debug) {
+          console.error(`[${SERVICE_NAME}] event type=${type} sessionID=${sessionID ?? ""}`)
+        }
+        if (!sessionID) return
+
+        if (type === "session.status") {
+          const status = asObject(asObject(event.properties).status)
+          if (debug) {
+            console.error(`[${SERVICE_NAME}] session.status state=${asString(status.type, "unknown")}`)
+          }
+          const statusType = asString(status.type)
+          if (statusType === "busy" || statusType === "retry") {
+            prefetchSnapshot(sessionID, `session.status:${statusType}`)
+          }
+          if (status.type === "idle") {
+            schedule(sessionID, "session.status:idle")
+          }
+          return
+        }
+
+        if (type === "session.idle") {
+          schedule(sessionID, "session.idle")
+          return
+        }
+
+        if (type === "session.diff" || type === "todo.updated") {
+          prefetchSnapshot(sessionID, type)
+          return
+        }
+
+        if (debug && (type === "message.updated" || type === "message.part.updated")) {
+          await logEvent(ctx, "debug", "event.observed", { type, sessionID })
+        }
+      } catch (error) {
+        await logEvent(ctx, "error", "event.handler.failed", {
+          error: asString((error as Error)?.stack ?? (error as Error)?.message ?? error),
+        })
+      }
+    },
+  }
+}
+
+export default ConvoDumpPlugin

package/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/README.md

@@ -0,0 +1,54 @@
+# opencode-convodump
+
+An OpenCode plugin that exports each conversation session to a readable
+Markdown transcript.
+
+## What it does
+
+- Listens for session idle events.
+- Fetches the latest session snapshot (session metadata + messages).
+- Writes/updates transcript files at:
+  `convos/YYYY-MM-DD-HH-mm-ss-<session-id>.md`
+- Uses a compact frontmatter and conversation-first body format.
+
+## Install from npm
+
+Add the package name to `plugin` in your OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-convodump"]
+}
+```
+
+OpenCode installs npm plugins automatically with Bun.
+
+## Local file usage (without npm)
+
+Use the plugin file directly:
+
+- Project: `.opencode/plugins/convodump.ts`
+- Global: `~/.config/opencode/plugins/convodump.ts`
+
+## Release process
+
+Publishing to npm is automated from GitHub Releases using
+`.github/workflows/publish-npm.yml`.
+
+1. Bump `version` in `package.json`.
+2. Commit and push the version change.
+3. Create a GitHub Release with tag `v<version>` (for example `v0.0.1`).
+4. The workflow publishes that version to npm.
+
+You can also run the same workflow manually from GitHub Actions using
+`workflow_dispatch` (optionally passing `release_tag`, defaulting to
+`v<package.json version>`).
+
+### One-time setup required
+
+1. Create an npm automation token for the account that will publish this
+   package.
+2. Add the token as a GitHub Actions secret named `NPM_TOKEN`.
+3. Ensure the npm account tied to `NPM_TOKEN` has publish rights to
+   `opencode-convodump`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-convodump",
+  "version": "0.0.1",
+  "description": "OpenCode plugin that exports each conversation session to a readable Markdown transcript.",
+  "type": "module",
+  "license": "CC0-1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intellectronica/opencode-convodump.git"
+  },
+  "bugs": {
+    "url": "https://github.com/intellectronica/opencode-convodump/issues"
+  },
+  "homepage": "https://github.com/intellectronica/opencode-convodump#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "transcript",
+    "markdown"
+  ],
+  "exports": {
+    ".": {
+      "import": "./.opencode/plugins/convodump.ts",
+      "types": "./.opencode/plugins/convodump.ts"
+    }
+  },
+  "files": [
+    ".opencode/plugins/convodump.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  }
+}