oc-transcript-save 0.0.5 → 0.2.1

package/README.md

@@ -15,13 +15,19 @@ An [OpenCode](https://github.com/sst/opencode) plugin that automatically saves f
 
 ## Installation
 
-1. Install dependencies:
+Requires OpenCode v2. Add the plugin to `opencode.json(c)`:
 
-```bash
-bun install
+```jsonc
+{
+	"plugins": ["oc-transcript-save@latest"]
+}
 ```
 
-2. The plugin exports `TranscriptSavePlugin` which can be registered with your OpenCode instance.
+OpenCode installs the package and loads it automatically. Transcripts are
+written on every turn the session goes idle.
+
+> **OpenCode v1?** Pin the legacy release: `"plugin": ["oc-transcript-save@0.0.5"]`,
+> or import the V1 entrypoint explicitly via `oc-transcript-save/v1`.
 
 ## Configuration
 

package/index.ts

@@ -0,0 +1,330 @@
+/**
+ * OpenCode V2 plugin entrypoint.
+ *
+ * V2 loads this module's default export as `{ id, setup }` and expects a
+ * cleanup function from `setup`. Events arrive as `{ type, data }` wire
+ * objects on `ctx.event.subscribe()`, session data comes from
+ * `ctx.session.get()` / `ctx.session.context()`, and there is no
+ * `ctx.client.app.log` or `tui` surface on the server side, so logging is
+ * console-only behind OC_TRANSCRIPT_SAVE_DEBUG.
+ *
+ * The V1 entrypoint remains in ./transcript-save.ts (package subpath "./v1").
+ */
+
+import {
+	asArray,
+	asObject,
+	asString,
+	atomicWrite,
+	formatFilenameTimestamp,
+	formatToolCallJson,
+	normaliseNewlines,
+	renderCodeBlock,
+	renderCompactJson,
+	renderPlainText,
+	renderQuoteBlock,
+	sanitiseFilename,
+	stableJson,
+	toYaml,
+	truncateText,
+} from './transcript-save.ts'
+
+const SERVICE_NAME = 'oc-transcript-save'
+
+type UnknownRecord = Record<string, unknown>
+type AnyCtx = any
+
+type Snapshot = {
+	session: UnknownRecord
+	messages: unknown[]
+}
+
+function resolveSessionId(event: UnknownRecord): string | null {
+	const data = asObject(event.data)
+	const candidate = data.sessionID ?? data.sessionId ?? asObject(data.session).id
+	if (typeof candidate !== 'string' || candidate.trim() === '') return null
+	return candidate
+}
+
+function buildFrontmatter(session: UnknownRecord): UnknownRecord {
+	const time = asObject(session.time)
+	return {
+		session_id: session.id ?? null,
+		title: session.title ?? null,
+		created_at: asString(time.created ?? '') || null,
+		updated_at: asString(time.updated ?? '') || null,
+	}
+}
+
+function renderToolPart(content: UnknownRecord): string {
+	const state = asObject(content.state)
+	const status = asString(state.status, 'unknown')
+	const outputPayload: UnknownRecord = {}
+
+	const toolResult = state.content ?? state.output
+	if (hasContent(toolResult)) outputPayload.result = toolResult
+	if (hasContent(state.error)) outputPayload.error = state.error
+
+	const toolCall: UnknownRecord = {
+		tool: asString(content.name, 'unknown'),
+		status,
+		input: state.input ?? null,
+		output: Object.keys(outputPayload).length > 0 ? outputPayload : null,
+	}
+	return renderCodeBlock(formatToolCallJson(toolCall), 'json')
+}
+
+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 renderV2Content(content: UnknownRecord): string {
+	const type = asString(content.type, 'unknown')
+
+	if (type === 'text') {
+		const text = renderPlainText(asString(content.text, ''))
+		return text
+	}
+
+	if (type === 'reasoning') {
+		const thinking = asString(content.text, '')
+		if (thinking.trim() === '') return ''
+		return renderQuoteBlock(thinking, 12000)
+	}
+
+	if (type === 'tool') {
+		return renderToolPart(content)
+	}
+
+	return `Unknown part type \`${type}\`:\n${renderCompactJson(content, 1600)}`
+}
+
+function renderV2Message(message: UnknownRecord): string {
+	const type = asString(message.type, 'unknown')
+	const section: string[] = []
+
+	if (type === 'user') {
+		section.push('### User')
+		section.push('')
+		const text = renderPlainText(asString(message.text, ''))
+		if (text) section.push(text)
+		if (hasContent(message.files)) {
+			section.push('')
+			section.push('Attachments:')
+			section.push(renderCompactJson(message.files, 2200))
+		}
+		return section.join('\n')
+	}
+
+	if (type === 'assistant') {
+		section.push('### Agent')
+		section.push('')
+		const contents = asArray(message.content)
+		if (contents.length === 0) {
+			section.push('_No content._')
+			return section.join('\n')
+		}
+		let hasRendered = false
+		for (const item of contents) {
+			const rendered = renderV2Content(asObject(item))
+			if (!rendered) continue
+			if (hasRendered) section.push('')
+			section.push(rendered)
+			hasRendered = true
+		}
+		if (!hasRendered) section.push('_No content._')
+		return section.join('\n')
+	}
+
+	if (type === 'synthetic' || type === 'system') {
+		const description = asString(message.description, '')
+		const text = asString(message.text, '')
+		if (!description && !text) return ''
+		section.push(`### System${description ? `: ${truncateText(description, 120)}` : ''}`)
+		section.push('')
+		if (text) section.push(renderQuoteBlock(text, 6000))
+		return section.join('\n')
+	}
+
+	if (type === 'skill') {
+		section.push(`### Skill: ${asString(message.name, 'unknown')}`)
+		section.push('')
+		section.push(renderQuoteBlock(asString(message.text, ''), 6000))
+		return section.join('\n')
+	}
+
+	if (type === 'shell') {
+		section.push('### Shell')
+		section.push('')
+		section.push(renderCodeBlock(asString(message.command, ''), 'sh'))
+		if (hasContent(message.output)) {
+			section.push('')
+			section.push(`Exit: ${asString(message.exit ?? asString(message.status, 'unknown'))}`)
+			section.push('')
+			section.push(renderCodeBlock(asString(message.output, ''), 'text'))
+		}
+		return section.join('\n')
+	}
+
+	if (type === 'compaction') {
+		const status = asString(message.status, 'unknown')
+		section.push(`### Compaction (${status})`)
+		section.push('')
+		section.push(renderQuoteBlock(asString(message.summary, ''), 8000))
+		return section.join('\n')
+	}
+
+	// agent-selected / model-selected / location-switched / idle and any
+	// future event-ish records carry no conversational content.
+	return ''
+}
+
+function renderMarkdown(snapshot: Snapshot): string {
+	const content: string[] = []
+	content.push('---')
+	content.push(toYaml(buildFrontmatter(snapshot.session)))
+	content.push('---')
+
+	if (snapshot.messages.length === 0) {
+		content.push('')
+		content.push('_No messages yet._')
+	} else {
+		for (let i = 0; i < snapshot.messages.length; i += 1) {
+			const rendered = renderV2Message(asObject(snapshot.messages[i]))
+			if (!rendered) continue
+			if (content.length > 4) {
+				content.push('')
+				content.push('---')
+			}
+			content.push('')
+			content.push(rendered)
+		}
+	}
+
+	return normaliseNewlines(content.join('\n'))
+}
+
+function fingerprint(snapshot: Snapshot): string {
+	return stableJson({ session: snapshot.session, messages: snapshot.messages })
+}
+
+function resolveOutputPath(ctx: AnyCtx, snapshot: Snapshot): string {
+	const session = snapshot.session
+	const time = asObject(session.time)
+	const timestamp = formatFilenameTimestamp(time.created)
+	const id = sanitiseFilename(asString(session.id, 'unknown-session'))
+	const root = process.env.OC_TRANSCRIPT_SAVE_PATH || asString(ctx.location?.directory, '') || process.cwd()
+	return `${root.replace(/\/+$/, '')}/${timestamp}-${id}.md`
+}
+
+async function fetchSnapshot(ctx: AnyCtx, sessionID: string): Promise<Snapshot> {
+	const sessionResult = await ctx.session.get({ sessionID })
+	const session = asObject((sessionResult as UnknownRecord)?.data ?? sessionResult)
+	if (!session.id) throw new Error(`Session not found for id '${sessionID}'`)
+
+	const contextResult = await ctx.session.context({ sessionID })
+	const messages = asArray((contextResult as UnknownRecord)?.data ?? contextResult)
+
+	return { session, messages }
+}
+
+export const TranscriptSavePluginV2 = {
+	id: 'oc-transcript-save',
+	setup: async (ctx: AnyCtx) => {
+		const state = new Map<string, { running: boolean; dirty: boolean; queue: Promise<void>; lastFingerprint: string }>()
+		const debug = process.env.OC_TRANSCRIPT_SAVE_DEBUG === '1' || process.env.OC_TRANSCRIPT_SAVE_DEBUG === 'true'
+		const controller = new AbortController()
+
+		const log = (message: string) => {
+			if (debug) console.error(`[${SERVICE_NAME}] ${message}`)
+		}
+
+		function entryFor(sessionID: string) {
+			const existing = state.get(sessionID)
+			if (existing) return existing
+			const created = { running: false, dirty: false, queue: Promise.resolve(), lastFingerprint: '' }
+			state.set(sessionID, created)
+			return created
+		}
+
+		async function exportOnce(sessionID: string): Promise<void> {
+			const entry = entryFor(sessionID)
+			const snapshot = await fetchSnapshot(ctx, sessionID)
+			const next = fingerprint(snapshot)
+			if (entry.lastFingerprint === next) {
+				log(`export skipped unchanged session=${sessionID}`)
+				return
+			}
+			const filePath = resolveOutputPath(ctx, snapshot)
+			const markdown = renderMarkdown(snapshot)
+			const bytes = await atomicWrite(filePath, markdown)
+			entry.lastFingerprint = next
+			log(`export wrote session=${sessionID} file=${filePath} bytes=${bytes}`)
+		}
+
+		function schedule(sessionID: string): void {
+			const entry = entryFor(sessionID)
+			entry.dirty = true
+			if (entry.running) return
+			entry.running = true
+			entry.queue = entry.queue
+				.then(async () => {
+					while (entry.dirty) {
+						entry.dirty = false
+						try {
+							await exportOnce(sessionID)
+						} catch (error) {
+							log(`export failed session=${sessionID} error=${asString((error as Error)?.stack ?? error)}`)
+						}
+					}
+				})
+				.finally(() => {
+					entry.running = false
+				})
+		}
+
+		async function onEvent(event: UnknownRecord): Promise<void> {
+			const type = asString(event.type)
+			const sessionID = resolveSessionId(event)
+			if (!sessionID) return
+
+			// V2 replaced the ephemeral `session.status` / deprecated `session.idle`
+			// bus events (never delivered to plugins) with durable
+			// `session.execution.*` events. A turn ends in exactly one of these.
+			if (
+				type === 'session.execution.succeeded'
+				|| type === 'session.execution.failed'
+				|| type === 'session.execution.interrupted'
+			) {
+				schedule(sessionID)
+			}
+		}
+
+		const pump = (async () => {
+			try {
+				for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+					try {
+						await onEvent(asObject(event))
+					} catch (error) {
+						log(`event handler failed: ${asString((error as Error)?.stack ?? error)}`)
+					}
+				}
+			} catch (error) {
+				if (!controller.signal.aborted) {
+					log(`event stream failed: ${asString((error as Error)?.stack ?? error)}`)
+				}
+			}
+		})()
+
+		return () => {
+			controller.abort()
+			return pump
+		}
+	},
+}
+
+export default TranscriptSavePluginV2

package/package.json

@@ -1,13 +1,21 @@
 {
 	"name": "oc-transcript-save",
 	"description": "OpenCode plugin that autosaves full transcript in specified directory",
-	"version": "0.0.5",
+	"version": "0.2.1",
 	"type": "module",
-	"main": "./transcript-save.ts",
-	"module": "./transcript-save.ts",
-	"types": "./transcript-save.ts",
+	"main": "./index.ts",
+	"module": "./index.ts",
+	"types": "./index.ts",
 	"exports": {
 		".": {
+			"types": "./index.ts",
+			"import": "./index.ts"
+		},
+		"./server": {
+			"types": "./index.ts",
+			"import": "./index.ts"
+		},
+		"./v1": {
 			"types": "./transcript-save.ts",
 			"import": "./transcript-save.ts"
 		}
@@ -19,6 +27,7 @@
 		"fmt": "dprint fmt"
 	},
 	"files": [
+		"index.ts",
 		"transcript-save.ts",
 		"tsconfig.json",
 		"README.md"
@@ -34,10 +43,9 @@
 		"url": "git+https://github.com/mdrv/oc-transcript-save.git"
 	},
 	"homepage": "https://github.com/mdrv/oc-transcript-save",
-	"dependencies": {
-		"@opencode-ai/plugin": "1.17.11"
-	},
+	"dependencies": {},
 	"devDependencies": {
+		"@opencode-ai/plugin": "1.17.11",
 		"@types/bun": "latest"
 	},
 	"peerDependencies": {

package/transcript-save.ts

@@ -28,22 +28,22 @@ type SessionSnapshot = {
 	diff: unknown
 }
 
-function normaliseNewlines(value: string): string {
+export function normaliseNewlines(value: string): string {
 	return value.replace(/\r\n?/g, '\n')
 }
 
-function asString(value: unknown, fallback = ''): string {
+export 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 {
+export function asObject(value: unknown): UnknownRecord {
 	if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
 	return value as UnknownRecord
 }
 
-function asArray(value: unknown): unknown[] {
+export function asArray(value: unknown): unknown[] {
 	return Array.isArray(value) ? value : []
 }
 
@@ -54,7 +54,7 @@ function bindMethod<T extends (...args: any[]) => any>(target: unknown, key: str
 	return candidate.bind(target) as T
 }
 
-function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | null> {
+export 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)),
@@ -78,12 +78,12 @@ function parseDate(value: unknown): Date | null {
 	return null
 }
 
-function toISO(value: unknown): string | null {
+export function toISO(value: unknown): string | null {
 	const parsed = parseDate(value)
 	return parsed ? parsed.toISOString() : null
 }
 
-function formatFilenameTimestamp(value: unknown): string {
+export 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')
@@ -94,7 +94,7 @@ function formatFilenameTimestamp(value: unknown): string {
 	return `${year}-${month}-${day}-${hour}-${minute}-${second}`
 }
 
-function sanitiseFilename(value: string): string {
+export function sanitiseFilename(value: string): string {
 	const safe = value.replace(/[^a-zA-Z0-9._-]/g, '_')
 	return safe || 'unknown-session'
 }
@@ -251,7 +251,7 @@ function writeYamlArrayItem(lines: string[], value: unknown, indent: number): vo
 	}
 }
 
-function toYaml(value: UnknownRecord): string {
+export function toYaml(value: UnknownRecord): string {
 	const lines: string[] = []
 	for (const [key, child] of Object.entries(value)) {
 		writeYamlPair(lines, key, child, 0)
@@ -271,7 +271,7 @@ function sortForStableJson(value: unknown): unknown {
 	return sorted
 }
 
-function stableJson(value: unknown): string {
+export function stableJson(value: unknown): string {
 	return JSON.stringify(sortForStableJson(value), null, 2)
 }
 
@@ -291,7 +291,7 @@ function chooseTrigger(existing: string | undefined, incoming: string): string {
 	return incoming
 }
 
-function codeFence(content: string): string {
+export function codeFence(content: string): string {
 	let longest = 2
 	for (const match of content.matchAll(/`+/g)) {
 		const runLength = match[0]?.length ?? 0
@@ -300,7 +300,7 @@ function codeFence(content: string): string {
 	return '`'.repeat(longest + 1)
 }
 
-function renderCodeBlock(content: string, language = ''): string {
+export function renderCodeBlock(content: string, language = ''): string {
 	const clean = normaliseNewlines(content)
 	const fence = codeFence(clean)
 	const suffix = language ? language : ''
@@ -341,7 +341,7 @@ function buildFrontmatter(session: UnknownRecord): UnknownRecord {
 	}
 }
 
-function truncateText(value: string, maxChars = 5000): string {
+export function truncateText(value: string, maxChars = 5000): string {
 	const normalised = normaliseNewlines(value)
 	if (normalised.length <= maxChars) return normalised
 
@@ -349,7 +349,7 @@ function truncateText(value: string, maxChars = 5000): string {
 	return `${normalised.slice(0, maxChars)}\n\n... [truncated ${omitted} chars]`
 }
 
-function renderQuoteBlock(value: string, maxChars = 7000): string {
+export function renderQuoteBlock(value: string, maxChars = 7000): string {
 	const text = truncateText(value, maxChars)
 	if (text.trim() === '') return '>'
 
@@ -359,18 +359,18 @@ function renderQuoteBlock(value: string, maxChars = 7000): string {
 		.join('\n')
 }
 
-function renderPlainText(value: string, maxChars = 7000): string {
+export function renderPlainText(value: string, maxChars = 7000): string {
 	return truncateText(value, maxChars).trim()
 }
 
-function truncateInlineText(value: string, maxChars: number): string {
+export 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 {
+export function compactToolJsonValue(value: unknown, baseLimit: number, depth = 0): unknown {
 	if (value === null || value === undefined) return null
 
 	if (typeof value === 'string') {
@@ -408,7 +408,7 @@ function compactToolJsonValue(value: unknown, baseLimit: number, depth = 0): unk
 	return asString(value)
 }
 
-function formatToolCallJson(value: UnknownRecord): string {
+export 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)
@@ -420,7 +420,7 @@ function formatToolCallJson(value: UnknownRecord): string {
 	return JSON.stringify(compactToolJsonValue(value, 20), null, 2)
 }
 
-function renderCompactJson(value: unknown, maxChars = 3200): string {
+export 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)
@@ -584,7 +584,7 @@ function renderMarkdown(snapshot: SessionSnapshot, trigger: string, ctx: Unknown
 	return normaliseNewlines(content.join('\n'))
 }
 
-async function atomicWrite(filePath: string, content: string): Promise<number> {
+export async function atomicWrite(filePath: string, content: string): Promise<number> {
 	const dirPath = path.dirname(filePath)
 	await mkdir(dirPath, { recursive: true })