From 95362134aad844f88527ef0cd0984190e292d2ee Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 10:06:49 +0100 Subject: [PATCH] session export: write only session.html, retire the markdown export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A stage's session was exported twice, as session.md and session.html, and both files were presented. It is now one html file; the markdown export is retired. - internal/stage/session_export.go: ExportSession renders and writes exactly one file, session.html, via writeSessionFile; renderSessionMarkdown and its helpers are gone; SessionExportResult carries HTML/HTMLBytes only. The source read, the 8 MiB source / 2 MiB rendered bounds, the truncation banner, the never-overwrite rule and the honest empty-session handling are unchanged. - internal/protocol/runs.go: SessionExport drops markdown/markdown_bytes (a record written before the change still decodes; unknown fields are ignored), and adds LegacySessionMarkdownArtifact with RunStep.PresentedArtifacts(), the one Go rule that hides the retired session.md from every artifact listing. - internal/server/runner.go: evidence.Markdown/MarkdownBytes are no longer copied. - internal/tui: the artifacts panel, the recorded count and the per-visit summary derive from PresentedArtifacts(), so the terminal never lists session.md. - web/src/app.js: the spike's renderArtifacts applies the same filter. - android: the Session section is the html export alone in a WebView — SessionView, the Markdown/HTML toggle and the session markdown path are removed; presentedArtifacts(step) filters the retired session.md out of the per-visit gallery, the run gallery and its count, the verdict/selection lists and the timeline indicator; data/protocol SessionExport drops the markdown fields. - Tests pin the single html file, prove no session.md is written and that a pre-existing one is neither overwritten nor presented, and prove a legacy export record still loads and its session.md is hidden. The legacy session.md of an older run stays on disk (dated evidence); it is only no longer produced and no longer presented. Checks (macOS, Go 1.24, Android Gradle 8.11.1, 18 Oct 2026): gofmt -l . prints nothing; go build ./... && go vet ./... clean; go test ./internal/... ./cmd/... -> 19 packages ok, 0 failures; node --check web/src/app.js ok and node --test web/test -> 20/20; gradle --offline --no-daemon :app:assembleDebug :app:testDebugUnitTest -> BUILD SUCCESSFUL. Packaged references checked: internal/author/skill/references/delivery.md and operations.md both described the session.md+session.html pair, so both are updated here to describe the single session.html export and the retired, hidden session.md. README.md and internal/author/skill/SKILL.md carry no session.md reference and install.go's managed inventory is unchanged (no reference added or removed). docs/notes/session-html-only.md records the remaining stale shared documentation (docs/stage-artifacts.md, docs/app-integration-verification.md) for the docs-fold writer; shared docs are not edited by this item. --- .../awan/pipelines/data/protocol/Message.kt | 14 +- .../net/awan/pipelines/ui/ArtifactGroups.kt | 23 +- .../main/java/net/awan/pipelines/ui/Format.kt | 4 +- .../net/awan/pipelines/ui/graph/Artifacts.kt | 3 +- .../awan/pipelines/ui/graph/SessionExport.kt | 192 +++--------- .../pipelines/ui/graph/StageDetailPane.kt | 7 +- .../net/awan/pipelines/ui/screens/Timeline.kt | 8 +- .../awan/pipelines/ui/ArtifactGroupsTest.kt | 27 ++ .../pipelines/ui/graph/SessionExportTest.kt | 87 ++---- .../awan/pipelines/ui/screens/TimelineTest.kt | 3 + docs/notes/session-html-only.md | 148 +++++++++ internal/author/skill/references/delivery.md | 10 +- .../author/skill/references/operations.md | 20 +- internal/pipeline/runs_test.go | 39 ++- internal/protocol/runs.go | 58 +++- internal/protocol/runs_test.go | 22 ++ internal/server/runner.go | 2 - internal/server/session_export_live_test.go | 41 +-- internal/server/session_export_test.go | 68 ++--- internal/stage/session_export.go | 286 ++++-------------- internal/stage/session_export_test.go | 101 ++++--- internal/tui/artifacts.go | 9 +- internal/tui/artifacts_test.go | 47 +++ internal/tui/file_changes.go | 7 +- web/src/app.js | 11 +- 25 files changed, 666 insertions(+), 571 deletions(-) create mode 100644 docs/notes/session-html-only.md diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt index c6d3c088..0a1e2d40 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt @@ -293,20 +293,20 @@ data class SessionEvidence( /** * The recorded evidence of one stage's session file export, mirroring - * internal/protocol/runs.go SessionExport exactly: the file names written under - * the step's artifacts directory, their byte sizes, the decoded message count, - * the source, whether the export was truncated and a sanitized diagnostic. An - * absent (null) value means the step recorded no export (a non-OpenCode harness, - * a failed export or a pre-export server), so no Session section is shown. + * internal/protocol/runs.go SessionExport exactly: the html file name written + * under the step's artifacts directory, its byte size, the decoded message + * count, the source, whether the export was truncated and a sanitized + * diagnostic. An absent (null) value means the step recorded no export (a + * non-OpenCode harness, a failed export or a pre-export server), so no Session + * section is shown. A record written before the HTML-only change also carried + * markdown and markdown_bytes; unknown keys are ignored. */ @Serializable data class SessionExport( @SerialName("session_id") val sessionId: String = "", val backend: String = "", val source: String = "", - val markdown: String = "", val html: String = "", - @SerialName("markdown_bytes") val markdownBytes: Long = 0, @SerialName("html_bytes") val htmlBytes: Long = 0, val messages: Int = 0, val truncated: Boolean = false, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/ArtifactGroups.kt b/android/app/src/main/java/net/awan/pipelines/ui/ArtifactGroups.kt index b5c25394..f4e4d255 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/ArtifactGroups.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/ArtifactGroups.kt @@ -15,6 +15,25 @@ data class ArtifactGroup( val artifacts: List, ) +/** + * The retired markdown session export file name. Nothing writes it any more, but + * a run recorded before the HTML-only change still has `session.md` on disk: it + * is dated evidence that is never presented, so it is hidden from every artifact + * listing rather than shown beside the session html. + */ +const val LEGACY_SESSION_MARKDOWN_ARTIFACT = "session.md" + +/** + * The artifacts of one visit as the operator sees them: the recorded files with + * the retired markdown session export filtered out. Every artifact listing — the + * per-visit summary, the run gallery, the timeline indicator and the selection + * candidates — derives from this one function, so a stage's artifacts never show + * a session markdown beside the session html and the recorded counts can never + * disagree with the tiles. Pure, O(artifacts) per step. + */ +fun presentedArtifacts(step: RunStep): List = + step.artifacts.orEmpty().filterNot { it.name == LEGACY_SESSION_MARKDOWN_ARTIFACT } + /** * Groups a run's artifacts by stage and visit, purely and deterministically. * Order follows [runTimeline]: stages in first-appearance order and each stage's @@ -32,7 +51,7 @@ fun runArtifactGroups(steps: List): List { val groups = ArrayList() timeline.visitsByStage.forEach { (stageKey, visits) -> visits.forEach { step -> - val artifacts = step.artifacts.orEmpty() + val artifacts = presentedArtifacts(step) if (artifacts.isNotEmpty()) { val visit = visitByStageSequence[stageKey to step.sequence] ?: 1 groups += ArtifactGroup(stageKey, visit, artifacts) @@ -67,7 +86,7 @@ fun artifactsEmptyMessage(executing: Boolean): String = * disagree. Pure. */ fun runArtifactsHeader(steps: List, executing: Boolean): String { - val recorded = steps.sumOf { it.artifacts.orEmpty().size } + val recorded = steps.sumOf { presentedArtifacts(it).size } if (recorded == 0) return artifactsEmptyMessage(executing) val partial = steps.any { it.artifactsSkipped > 0 || it.artifactsTruncated > 0 } return buildString { diff --git a/android/app/src/main/java/net/awan/pipelines/ui/Format.kt b/android/app/src/main/java/net/awan/pipelines/ui/Format.kt index 09e379e5..9d11cb14 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/Format.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/Format.kt @@ -197,7 +197,7 @@ const val ARTIFACT_CAPTURE_PENDING = "capture pending" * count plus " · partial capture" when files were excluded or omitted. */ fun artifactsSummary(step: RunStep): String { - val artifacts = step.artifacts.orEmpty() + val artifacts = presentedArtifacts(step) if (artifacts.isEmpty()) { val state = if (step.status == "running") { ARTIFACT_CAPTURE_PENDING @@ -218,7 +218,7 @@ fun artifactsSummary(step: RunStep): String { * the notes never accompany the empty-state summary. */ fun artifactCaptureNotes(step: RunStep): List = buildList { - if (step.artifacts.isNullOrEmpty()) return@buildList + if (presentedArtifacts(step).isEmpty()) return@buildList if (step.artifactsSkipped > 0) add("${step.artifactsSkipped} files excluded from artifact capture.") if (step.artifactsTruncated > 0) add("${step.artifactsTruncated} files omitted by artifact capture limits.") } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/graph/Artifacts.kt b/android/app/src/main/java/net/awan/pipelines/ui/graph/Artifacts.kt index a696a709..462d4478 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/graph/Artifacts.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/graph/Artifacts.kt @@ -53,6 +53,7 @@ import net.awan.pipelines.ui.artifactsSummary import net.awan.pipelines.ui.components.copyText import net.awan.pipelines.ui.components.galleryGrid import net.awan.pipelines.ui.humanBytes +import net.awan.pipelines.ui.presentedArtifacts import net.awan.pipelines.ui.theme.ARTIFACT_BADGE_DP import net.awan.pipelines.ui.theme.ARTIFACT_PLAY_BADGE_DP import net.awan.pipelines.ui.theme.ARTIFACT_TILE_ACTION_DP @@ -85,7 +86,7 @@ internal fun ArtifactsSection( ) { val text = pipelinesText() // Derived once per data change, never per recomposition (performance requirement). - val artifacts = remember(step) { step.artifacts.orEmpty() } + val artifacts = remember(step) { presentedArtifacts(step) } val summary = remember(step) { artifactsSummary(step) } val notes = remember(step) { artifactCaptureNotes(step) } Column(modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(SPACING_XS)) { diff --git a/android/app/src/main/java/net/awan/pipelines/ui/graph/SessionExport.kt b/android/app/src/main/java/net/awan/pipelines/ui/graph/SessionExport.kt index 90d8bbe1..e56a7747 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/graph/SessionExport.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/graph/SessionExport.kt @@ -4,13 +4,10 @@ import android.webkit.WebView import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column -import androidx.compose.foundation.layout.Row import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.layout.padding import androidx.compose.material3.CircularProgressIndicator -import androidx.compose.material3.MaterialTheme -import androidx.compose.material3.OutlinedButton import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.DisposableEffect @@ -18,7 +15,6 @@ import androidx.compose.runtime.LaunchedEffect import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember -import androidx.compose.runtime.saveable.rememberSaveable import androidx.compose.runtime.setValue import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier @@ -29,115 +25,61 @@ import kotlinx.coroutines.withContext import net.awan.pipelines.data.protocol.GraphSemantics import net.awan.pipelines.data.protocol.RunStep import net.awan.pipelines.data.protocol.StageArtifact -import net.awan.pipelines.ui.chat.MarkdownBlocks -import net.awan.pipelines.ui.chat.MdBlock -import net.awan.pipelines.ui.chat.parseMarkdown import net.awan.pipelines.ui.theme.SPACING_L import net.awan.pipelines.ui.theme.SPACING_S import net.awan.pipelines.ui.theme.pipelinesText /** - * The session export's files of one visit, resolved against the visit's recorded - * artifacts. Either file may be missing (a partially exported or truncated - * listing); a visit with neither has no export to show. + * The html session export [step] recorded, resolved against the visit's recorded + * artifacts, or null when the visit has no export to open. The server writes one + * html file per session; a visit that recorded no export (a Pi harness, a failed + * export or a pre-export server) or whose file is missing from a truncated + * artifact listing yields null, so the stage pane lists no Session section for a + * visit that has nothing to show. The retired `session.md` export is never named + * by the server record and is never presented. */ -internal data class SessionExportFiles( - val markdown: StageArtifact?, - val html: StageArtifact?, -) - -/** - * The files [step]'s session export actually wrote, matched by the names the - * server recorded in `session_export` against the step's artifact listing. Null - * when the visit recorded no export, when it recorded only a limitation (a Pi - * harness, `source: "unavailable"`, or a failure with a diagnostic and no file - * names) or when the listing holds neither recorded file. The stage pane derives - * the Session section from exactly this, so a section is never listed for a visit - * that has no session file to open. - */ -internal fun sessionExportFiles(step: RunStep): SessionExportFiles? { +internal fun sessionExportFile(step: RunStep): StageArtifact? { val export = step.sessionExport ?: return null - val markdownName = export.markdown.takeIf { it.isNotBlank() } - val htmlName = export.html.takeIf { it.isNotBlank() } - if (markdownName == null && htmlName == null) return null - val artifacts = step.artifacts.orEmpty() - val markdown = markdownName?.let { name -> artifacts.firstOrNull { it.name == name } } - val html = htmlName?.let { name -> artifacts.firstOrNull { it.name == name } } - if (markdown == null && html == null) return null - return SessionExportFiles(markdown = markdown, html = html) + val name = export.html.takeIf { it.isNotBlank() } ?: return null + return step.artifacts.orEmpty().firstOrNull { it.name == name } } -/** The two ways of reading an exported session: the rendered markdown or the html document. */ -internal enum class SessionView { Markdown, Html } - /** - * The view the session section opens in: the markdown export, rendered with the - * app's existing markdown renderer, is the default. The html export is only the - * default when there is no markdown to render; otherwise it is reached through the - * section's own "HTML view" toggle and shown in a WebView for fidelity. - */ -internal fun defaultSessionView(files: SessionExportFiles): SessionView = - if (files.markdown != null) SessionView.Markdown else SessionView.Html - -/** Whether the operator can switch between the two exports (both were written). */ -internal fun sessionViewToggle(files: SessionExportFiles): Boolean = - files.markdown != null && files.html != null - -/** The file the section shows in [view], or null when that export is missing. */ -internal fun sessionArtifact(files: SessionExportFiles, view: SessionView): StageArtifact? = - when (view) { - SessionView.Markdown -> files.markdown - SessionView.Html -> files.html - } - -/** - * One exported session file, loaded: its markdown parsed into the app's shared - * blocks, its html kept as the document text, its absence a distinct error. A null - * url means no server was configured to fetch it from. + * One exported session file, loaded: its html kept as the document text, its + * absence a distinct error. A null url means no server was configured to fetch + * it from. */ internal sealed interface SessionLoad { data object Loading : SessionLoad data object Unavailable : SessionLoad data object Error : SessionLoad - data class Markdown(val blocks: List) : SessionLoad data class Html(val document: String) : SessionLoad } /** * Classifies one fetched session file: a failed fetch ([bytes] null) is a distinct * error state, never rendered as an empty session, and a fetched file decodes to - * its view. Pure, so the decode/parse and the failure branch are unit tested. + * its document text. Pure (the UTF-8 decode replaces malformed sequences rather + * than throwing), so the viewer passes it off the main thread and it is unit + * tested. */ -internal fun sessionLoad(bytes: ByteArray?, markdown: Boolean): SessionLoad = - if (bytes == null) SessionLoad.Error else decodeSessionFile(bytes, markdown) - -/** - * Decodes one session file: markdown into the shared parsed blocks, html into its - * document text. Pure (the UTF-8 decode replaces malformed sequences rather than - * throwing), so the viewer passes it off the main thread and it is unit tested. - */ -internal fun decodeSessionFile(bytes: ByteArray, markdown: Boolean): SessionLoad { - val text = bytes.toString(Charsets.UTF_8) - return if (markdown) SessionLoad.Markdown(parseMarkdown(text)) else SessionLoad.Html(text) -} +internal fun sessionLoad(bytes: ByteArray?): SessionLoad = + if (bytes == null) SessionLoad.Error else SessionLoad.Html(bytes.toString(Charsets.UTF_8)) /** * The Session section pane: the exported session of the selected visit, read like - * the artifacts beside it. The markdown export is the default and is rendered with - * the app's existing markdown renderer in a lazy list (one parsed block per item), - * so a session of several hundred kilobytes scrolls without composing every block. - * When both files were exported the section offers an "HTML view" toggle that - * swaps in the html document in a WebView for fidelity, and switches back. The - * context line stays pinned above the scroll, exactly as the other section panes - * keep their chrome. On a wide window [visitTabs] renders the pinned visit row in - * that header; on a narrow one the caller owns the visit strip below instead, so the - * header must not double it. + * the artifacts beside it. The one session export is html, shown in a WebView for + * fidelity — there is no markdown view and no view toggle. The context line stays + * pinned above the scroll, exactly as the other section panes keep their chrome. + * On a wide window [visitTabs] renders the pinned visit row in that header; on a + * narrow one the caller owns the visit strip below instead, so the header must not + * double it. * * The file is fetched once per url through the app's shared artifact byte cache and - * the fetch/parse run off the main thread, so switching views or reopening the pane - * never re-hits the network and never blocks the pane. A missing server URL shows - * that state, and a failed fetch shows its own error in this pane only: the stage - * screen and every other section are unaffected. + * the fetch runs off the main thread, so reopening the pane never re-hits the + * network and never blocks the pane. A missing server URL shows that state, and a + * failed fetch shows its own error in this pane only: the stage screen and every + * other section are unaffected. */ @Composable internal fun SessionExportSection( @@ -151,46 +93,17 @@ internal fun SessionExportSection( visitTabs: Boolean = true, modifier: Modifier = Modifier, ) { - val text = pipelinesText() - val files = remember(step) { sessionExportFiles(step) } + val file = remember(step) { sessionExportFile(step) } Column(modifier.fillMaxSize()) { - if (files == null) { + if (file == null) { SessionHeader(stageKey, runSteps, visitIndex, onVisitIndexChange, visitTabs) { - Text("No session was exported for this visit.", style = text.meta) + Text("No session was exported for this visit.", style = pipelinesText().meta) } return@Column } - var view by rememberSaveable(step.sequence, files.markdown?.url, files.html?.url) { - mutableStateOf(defaultSessionView(files)) - } - val toggle = sessionViewToggle(files) - val artifact = sessionArtifact(files, view) - val url = artifact?.let { resolvedArtifactUrl(it, configuredServerUrl) } - SessionHeader(stageKey, runSteps, visitIndex, onVisitIndexChange, visitTabs) { - Row( - modifier = Modifier.fillMaxWidth(), - verticalAlignment = Alignment.CenterVertically, - horizontalArrangement = Arrangement.spacedBy(SPACING_S), - ) { - Text( - if (view == SessionView.Markdown) "Markdown" else "HTML", - style = text.label, - color = MaterialTheme.colorScheme.primary, - modifier = Modifier.weight(1f), - ) - if (toggle) { - OutlinedButton( - onClick = { - view = if (view == SessionView.Markdown) SessionView.Html else SessionView.Markdown - }, - ) { - Text(if (view == SessionView.Markdown) "HTML view" else "Markdown view") - } - } - } - } + SessionHeader(stageKey, runSteps, visitIndex, onVisitIndexChange, visitTabs) {} SessionBody( - load = rememberSessionLoad(url, view == SessionView.Markdown, fetchArtifactBytes), + load = rememberSessionLoad(resolvedArtifactUrl(file, configuredServerUrl), fetchArtifactBytes), modifier = Modifier.weight(1f), ) } @@ -198,11 +111,11 @@ internal fun SessionExportSection( /** * The session pane's pinned header: the context line naming the stage and — on a - * wide window — the visit row, followed by the caller's [content] (the view toggle, - * or the missing-export notice). It stays above the session's own scroll, exactly as - * the other section panes keep their chrome. On a narrow window [visitTabs] is false - * and the visit selector is the caller's bottom strip instead, so the header does not - * show it twice. + * wide window — the visit row, followed by the caller's [content] (the + * missing-export notice, or nothing when a session is shown). It stays above the + * session's own scroll, exactly as the other section panes keep their chrome. On a + * narrow window [visitTabs] is false and the visit selector is the caller's bottom + * strip instead, so the header does not show it twice. */ @Composable private fun SessionHeader( @@ -227,9 +140,8 @@ private fun SessionHeader( } /** - * The loaded session file's body: the parsed markdown in a lazy list, the html in - * a WebView, or the loading/unavailable/error notice. The one branch that draws a - * session, so the markdown and html paths share the section's fetch and state. + * The loaded session's body: the html document in a WebView, or the + * loading/unavailable/error notice. The one branch that draws a session. */ @Composable private fun SessionBody(load: SessionLoad, modifier: Modifier = Modifier) { @@ -247,7 +159,6 @@ private fun SessionBody(load: SessionLoad, modifier: Modifier = Modifier) { message = "Couldn't load the exported session.", modifier = modifier, ) - is SessionLoad.Markdown -> MarkdownBlocks(blocks = load.blocks, modifier = modifier) is SessionLoad.Html -> SessionHtml(document = load.document, modifier = modifier) } } @@ -268,11 +179,10 @@ private fun SessionNotice(message: String, modifier: Modifier = Modifier, spinne } /** - * The html export in a WebView. The markdown default is rendered natively; the - * html is the fidelity fallback for the structure the app's renderer does not - * reproduce. The document is self-contained, so it is loaded with a null base URL - * (no file or network origin), scripting is off, and the view is destroyed with - * the composition. + * The html export in a WebView, the fidelity view of the one session export. The + * document is self-contained, so it is loaded with a null base URL (no file or + * network origin), scripting is off, and the view is destroyed with the + * composition. */ @Composable private fun SessionHtml(document: String, modifier: Modifier = Modifier) { @@ -296,27 +206,25 @@ private fun SessionHtml(document: String, modifier: Modifier = Modifier) { /** * Loads the resolved session [url] once and classifies it. A null url is * [SessionLoad.Unavailable] with no request attempted. The bytes are fetched - * through the app's shared [ArtifactBytesCache], so re-opening the section or - * switching views reuses them instead of loading the file a second time; the - * decode and markdown parse run off the main thread so a large session never - * blocks the UI. A canceled effect (the url or view changed) never publishes its - * stale result. + * through the app's shared [ArtifactBytesCache], so re-opening the section reuses + * them instead of loading the file a second time; the decode runs off the main + * thread so a large session never blocks the UI. A canceled effect (the url + * changed) never publishes its stale result. */ @Composable private fun rememberSessionLoad( url: String?, - markdown: Boolean, fetchBytes: suspend (String) -> ByteArray?, ): SessionLoad { if (url == null) return SessionLoad.Unavailable var load by remember(url) { mutableStateOf(SessionLoad.Loading) } - LaunchedEffect(url, markdown) { + LaunchedEffect(url) { val cached = ArtifactBytesCache.get(url) val bytes = cached ?: runCatching { withContext(Dispatchers.IO) { fetchBytes(url) } }.getOrNull() if (cached == null && bytes != null) ArtifactBytesCache.put(url, bytes) - load = withContext(Dispatchers.Default) { sessionLoad(bytes, markdown) } + load = withContext(Dispatchers.Default) { sessionLoad(bytes) } } return load } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/graph/StageDetailPane.kt b/android/app/src/main/java/net/awan/pipelines/ui/graph/StageDetailPane.kt index 418f8dc8..fb625011 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/graph/StageDetailPane.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/graph/StageDetailPane.kt @@ -59,6 +59,7 @@ import net.awan.pipelines.ui.fileChangesSummary import net.awan.pipelines.ui.formatDuration import net.awan.pipelines.ui.notificationLine import net.awan.pipelines.ui.pendingDecision +import net.awan.pipelines.ui.presentedArtifacts import net.awan.pipelines.ui.runLabel import net.awan.pipelines.ui.screens.runTimeline import net.awan.pipelines.ui.theme.SPACING_L @@ -259,7 +260,7 @@ internal fun stageSectionSpecs( // artifacts it was written with: both are the visit's recorded files, and // the operator reads them the same way. A visit without an export lists no // Session row at all, rather than an empty section. - val session = sessionExportFiles(selectedStep) != null + val session = sessionExportFile(selectedStep) != null STAGE_RESULT_SECTIONS.forEach { section -> when (section) { StageResultSection.Artifacts -> { @@ -553,7 +554,7 @@ private fun StageDetailBody( verdict = selectedStep.verdict, outcome = selectedStep.outcome, status = selectedStep.status, - artifacts = selectedStep.artifacts.orEmpty(), + artifacts = presentedArtifacts(selectedStep), configuredServerUrl = configuredServerUrl, fetchArtifactBytes = fetchArtifactBytes, ) @@ -701,7 +702,7 @@ fun StageSectionPane( val selectionState = rememberArtifactSelection(stageKey, clampedVisit) ArtifactSelectionScaffold( selectionState = selectionState, - candidates = selectedStep?.artifacts.orEmpty(), + candidates = selectedStep?.let { presentedArtifacts(it) }.orEmpty(), configuredServerUrl = configuredServerUrl, fetchArtifactBytes = fetchArtifactBytes, modifier = modifier, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/screens/Timeline.kt b/android/app/src/main/java/net/awan/pipelines/ui/screens/Timeline.kt index d41160bb..e4cb1417 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/screens/Timeline.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/screens/Timeline.kt @@ -2,6 +2,7 @@ package net.awan.pipelines.ui.screens import net.awan.pipelines.data.protocol.GraphSemantics import net.awan.pipelines.data.protocol.RunStep +import net.awan.pipelines.ui.LEGACY_SESSION_MARKDOWN_ARTIFACT import net.awan.pipelines.ui.formatDuration /** @@ -79,6 +80,9 @@ internal fun timelineDescription(step: RunStep): String { /** * Whether a visit recorded any artifacts. The single predicate behind the * timeline's subtle artifact indicator, so the timeline and the sheet never - * disagree about whether a visit produced files. + * disagree about whether a visit produced files. The retired session markdown is + * not presented, so it never counts; the check does not allocate, unlike + * [presentedArtifacts], and is safe to call on every recomposition. */ -internal fun hasArtifacts(step: RunStep): Boolean = !step.artifacts.isNullOrEmpty() +internal fun hasArtifacts(step: RunStep): Boolean = + step.artifacts.orEmpty().any { it.name != LEGACY_SESSION_MARKDOWN_ARTIFACT } diff --git a/android/app/src/test/java/net/awan/pipelines/ui/ArtifactGroupsTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/ArtifactGroupsTest.kt index 511e5619..7230d1b5 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/ArtifactGroupsTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/ArtifactGroupsTest.kt @@ -194,4 +194,31 @@ class ArtifactGroupsTest { runArtifactsHeader(steps, executing = false), ) } + + @Test + fun theLegacySessionMarkdownIsNeverPresented() { + // A run recorded before the HTML-only change still has both files: only the + // html session is presented, never a session markdown beside it. + val withBoth = step( + "implementer", + sequence = 1, + visit = 1, + artifacts = listOf( + artifact("session.md", "/artifacts/9/1/session.md"), + artifact("session.html", "/artifacts/9/1/session.html"), + ), + ) + assertEquals(listOf("session.html"), presentedArtifacts(withBoth).map { it.name }) + assertEquals("Artifacts · 1 recorded", artifactsSummary(withBoth)) + assertEquals(listOf("session.html"), runArtifactGroups(listOf(withBoth)).single().artifacts.map { it.name }) + assertEquals("Artifact · 1 recorded", runArtifactsHeader(listOf(withBoth), executing = false)) + + // A visit whose only session file is the retired markdown shows none of it: + // no tile, no group and no recorded count. + val legacyOnly = step("implementer", sequence = 1, visit = 1, artifacts = listOf(artifact("session.md"))) + assertTrue(presentedArtifacts(legacyOnly).isEmpty()) + assertTrue(runArtifactGroups(listOf(legacyOnly)).isEmpty()) + assertEquals("Artifacts · not recorded for this visit", artifactsSummary(legacyOnly)) + assertEquals(artifactsEmptyMessage(executing = false), runArtifactsHeader(listOf(legacyOnly), executing = false)) + } } diff --git a/android/app/src/test/java/net/awan/pipelines/ui/graph/SessionExportTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/graph/SessionExportTest.kt index 2ba69cf1..8972119c 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/graph/SessionExportTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/graph/SessionExportTest.kt @@ -17,20 +17,18 @@ class SessionExportTest { sessionId = "ses_1", backend = "v2", source = "native_export", - markdown = "session.md", html = "session.html", - markdownBytes = 12, htmlBytes = 34, messages = 2, ) @Test - fun aVisitWithNoSessionExportHasNoFiles() { - assertNull(sessionExportFiles(RunStep())) + fun aVisitWithNoSessionExportHasNoSessionFile() { + assertNull(sessionExportFile(RunStep())) // A limitation-only export (a Pi harness) records names for nothing and // must not produce an empty section. assertNull( - sessionExportFiles( + sessionExportFile( RunStep( sessionExport = SessionExport(source = "unavailable", diagnostic = "no native export path"), artifacts = listOf(artifact("session.md", "text/markdown")), @@ -40,42 +38,36 @@ class SessionExportTest { } @Test - fun theRecordedExportNamesResolveToTheListedArtifacts() { + fun theRecordedHTMLExportResolvesToTheListedArtifact() { val artifacts = listOf( artifact("shot.png", "image/png"), artifact("session.md", "text/markdown"), artifact("session.html", "text/html"), ) - val files = sessionExportFiles(RunStep(sessionExport = nativeExport, artifacts = artifacts)) - ?: error("expected files") - assertEquals("session.md", files.markdown?.name) - assertEquals("session.html", files.html?.name) - assertEquals(SessionView.Markdown, defaultSessionView(files)) - assertTrue(sessionViewToggle(files)) - assertEquals(files.markdown, sessionArtifact(files, SessionView.Markdown)) - assertEquals(files.html, sessionArtifact(files, SessionView.Html)) + val file = sessionExportFile(RunStep(sessionExport = nativeExport, artifacts = artifacts)) + ?: error("expected the html session file") + // The retired markdown export is never chosen: only the html is presented, + // so the operator never sees a markdown and an html session together. + assertEquals("session.html", file.name) } @Test - fun htmlIsTheDefaultAndTheOnlyViewWhenMarkdownIsMissing() { - val export = SessionExport(html = "session.html", source = "native_export") - val files = sessionExportFiles( - RunStep(sessionExport = export, artifacts = listOf(artifact("session.html", "text/html"))), - ) ?: error("expected files") - assertNull(files.markdown) - assertEquals(SessionView.Html, defaultSessionView(files)) - // The toggle only exists when both exports were written; a single export - // has nothing to switch to. - assertFalse(sessionViewToggle(files)) - assertNull(sessionArtifact(files, SessionView.Markdown)) - } - - @Test - fun aTruncatedListingOrAnAbsentOneLeavesNoFilesToShow() { - assertNull(sessionExportFiles(RunStep(sessionExport = nativeExport))) - assertNull(sessionExportFiles(RunStep(sessionExport = nativeExport, artifacts = emptyList()))) + fun aLegacyMarkdownOnlyRecordHasNothingToShow() { + // An older record that named only session.md has no html to present. + val legacy = SessionExport(sessionId = "ses_old", backend = "v2", source = "native_export") assertNull( - sessionExportFiles( + sessionExportFile( + RunStep(sessionExport = legacy, artifacts = listOf(artifact("session.md", "text/markdown"))), + ), + ) + } + + @Test + fun aTruncatedListingOrAnAbsentOneLeavesNothingToShow() { + assertNull(sessionExportFile(RunStep(sessionExport = nativeExport))) + assertNull(sessionExportFile(RunStep(sessionExport = nativeExport, artifacts = emptyList()))) + assertNull( + sessionExportFile( RunStep(sessionExport = nativeExport, artifacts = listOf(artifact("other.log", "text/plain"))), ), ) @@ -114,34 +106,15 @@ class SessionExportTest { @Test fun aFailedFetchIsItsOwnErrorAndNeverAnEmptySession() { - assertEquals(SessionLoad.Error, sessionLoad(bytes = null, markdown = true)) - assertEquals(SessionLoad.Error, sessionLoad(bytes = null, markdown = false)) + assertEquals(SessionLoad.Error, sessionLoad(bytes = null)) } @Test - fun aFetchedFileDecodesToItsView() { - val bytes = "# Title\n\nbody".toByteArray() - assertTrue(sessionLoad(bytes, markdown = true) is SessionLoad.Markdown) - val html = sessionLoad(bytes, markdown = false) - assertTrue(html is SessionLoad.Html) - assertEquals("# Title\n\nbody", (html as SessionLoad.Html).document) - } - - @Test - fun aLargeSessionParsesIntoBlocksOffTheViewer() { - // Several hundred kilobytes of markdown: the viewer parses it once into - // blocks (off the main thread) and composes them lazily, so this must not - // fail, throw or drop the document. - val large = buildString { - repeat(6_000) { index -> - append("# Heading $index\n\n") - append("A body line with *emphasis*, `code` and a [link](https://example.test/$index).\n\n") - } - } - assertTrue(large.length > 300_000) - val load = sessionLoad(large.toByteArray(), markdown = true) - assertTrue(load is SessionLoad.Markdown) - assertTrue((load as SessionLoad.Markdown).blocks.size >= 6_000) + fun aFetchedFileDecodesToItsDocument() { + val bytes = "

body

".toByteArray() + val load = sessionLoad(bytes) + assertTrue(load is SessionLoad.Html) + assertEquals("

body

", (load as SessionLoad.Html).document) } private fun artifact(name: String, contentType: String): StageArtifact = diff --git a/android/app/src/test/java/net/awan/pipelines/ui/screens/TimelineTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/screens/TimelineTest.kt index 0f6ec8a6..bf3a29f1 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/screens/TimelineTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/screens/TimelineTest.kt @@ -122,6 +122,9 @@ class TimelineTest { // An explicitly empty capture is not an artifact. assertFalse(hasArtifacts(RunStep(sequence = 1, stage = "a", artifacts = emptyList()))) assertTrue(hasArtifacts(RunStep(sequence = 1, stage = "a", artifacts = listOf(StageArtifact(name = "x.png"))))) + // The retired session markdown is not presented, so it is not an artifact. + assertFalse(hasArtifacts(RunStep(sequence = 1, stage = "a", artifacts = listOf(StageArtifact(name = "session.md"))))) + assertTrue(hasArtifacts(RunStep(sequence = 1, stage = "a", artifacts = listOf(StageArtifact(name = "session.md"), StageArtifact(name = "session.html"))))) } @Test diff --git a/docs/notes/session-html-only.md b/docs/notes/session-html-only.md new file mode 100644 index 00000000..b5cdd90b --- /dev/null +++ b/docs/notes/session-html-only.md @@ -0,0 +1,148 @@ +# Session export: html only, the markdown export retired + +## What this item changed + +A stage's session was exported twice, as `session.md` and `session.html`, and both +files were presented. It is now one html file; the markdown export is retired. + +Server side (`internal/stage`, `internal/protocol`, `internal/server`, +`internal/pipeline`): + +- `internal/stage/session_export.go` — `ExportSession` renders and writes exactly + one file, `session.html`, via `writeSessionFile`; the markdown renderer + (`renderSessionMarkdown` and its message/part/tool helpers), the + `markdownTruncationBanner` and `dynamicFence` are gone, and + `SessionExportResult` carries `HTML`/`HTMLBytes` only. `SessionMarkdownFile = + "session.md"` is kept as the single definition of the retired name. The source + read, the size bounds (`SessionExportSourceLimit`, `SessionExportFileLimit`), + the truncation banner, the never-overwrite rule and the honest empty-session + handling are unchanged. +- `internal/protocol/runs.go` — `SessionExport` drops `markdown` and + `markdown_bytes`; a record written before this change still decodes (Go's JSON + decoder ignores the unknown fields). It also carries the shared + `LegacySessionMarkdownArtifact = "session.md"` name and + `RunStep.PresentedArtifacts()`, the one Go rule that filters the retired + markdown out of every artifact listing (mirroring the app's + `presentedArtifacts`); the stored record is untouched. +- `internal/server/runner.go` — `evidence.Markdown`/`MarkdownBytes` are no longer + copied into the recorded step evidence. +- `internal/stage/session_export.go` keeps `SessionMarkdownFile = + protocol.LegacySessionMarkdownArtifact` as the single definition of the retired + name; the artifact inventory still lists whatever is on disk, so an older run's + recorded `session.md` is filtered where it is presented, not in the server's + evidence. +- `internal/tui/artifacts.go` and `internal/tui/file_changes.go` — the TUI's + artifacts panel, its recorded count and its per-visit summary + (`runArtifactVisits`, `artifactsSummary`, `artifactCaptureNotes`) all derive + from `RunStep.PresentedArtifacts()`, so the terminal never lists a session + markdown beside the session html either. +- `web/src/app.js` — the web spike's `renderArtifacts` applies the same filter, + so a legacy `session.md` is not linked beside `session.html` there either. + +App side (`android/`): + +- `ui/graph/SessionExport.kt` — the Session section is the html export alone in a + WebView. `SessionView`, the Markdown/HTML toggle, `defaultSessionView`, + `sessionViewToggle`, `sessionArtifact` and the `SessionLoad.Markdown` branch + (its use of the shared markdown renderer) are removed; `sessionExportFile` + resolves the recorded html name against the visit's artifacts. +- `data/protocol/Message.kt` — `SessionExport` drops `markdown`/`markdown_bytes` + (the app's `Json` already sets `ignoreUnknownKeys`). +- `ui/ArtifactGroups.kt` — new `presentedArtifacts(step)` filters the retired + `session.md` out of every artifact listing, and + `LEGACY_SESSION_MARKDOWN_ARTIFACT` names it. It is used by `artifactsSummary` + and `artifactCaptureNotes` (`ui/Format.kt`), the run gallery and its count + (`runArtifactGroups`, `runArtifactsHeader`), the per-visit gallery + (`ui/graph/Artifacts.kt`), the verdict block and the selection candidates + (`ui/graph/StageDetailPane.kt`) and the timeline indicator + (`ui/screens/Timeline.kt`). The app hides the legacy file because a run + recorded before the change carries it in its stored artifact list and the + server it talks to during review is not redeployed, so the list still arrives + with `session.md` in it. + +Tests were updated to pin the single html file and to prove no `session.md` is +written, a pre-existing one is neither overwritten nor presented, and a legacy +export record still loads. `internal/protocol` and `internal/tui` gained cases +proving `PresentedArtifacts` hides the retired name, leaves the stored record +untouched, and that the TUI panel, recorded count and per-visit summary hide it +(the follow-up that the review's MUST-FIX named). + +## Evidence (macOS, Go 1.24 toolchain, Android Gradle 8.11.1, 18 Oct 2026) + +- `go build ./... && go vet ./...` → clean; `gofmt -l .` → prints nothing. +- `go test ./internal/stage ./internal/pipeline ./internal/protocol` → all `ok`; + `go test ./internal/server` → `ok` (12.5 s); `go test ./...` → ok. +- Real export through the server's own live test path (a fresh OpenCode stage on + a temporary store, no inference budget beyond one stage): + `PIPELINES_SESSION_EXPORT_LIVE=1 PIPELINES_SESSION_EXPORT_MODEL=opencode-go/deepseek-v4.1-flash + go test ./internal/server -run TestSessionExportLive -v` → `PASS`, one + `session.html` (5120 bytes, 3 messages) listed and served HTTP 200, no + `session.md`. The exported document is saved as + `session-export-live-evidence.html`. +- Android: `:app:assembleDebug` and `:app:testDebugUnitTest` → both BUILD + SUCCESSFUL. +- Follow-up addressing the review's MUST-FIX (18 Oct 2026): `gofmt -l .` prints + nothing; `go build ./... && go vet ./...` → clean; + `go test ./internal/... ./cmd/...` → `GO-EXIT=0`, 19 packages `ok`, no + failures; `go test ./internal/tui ./internal/protocol` → both `ok`. The web + spike's `src/app.js` passes `node --check` and `node --test test/` → 20/20 + pass (the spike has no DOM test for its render helpers). The advisory's + non-allocating `hasArtifacts` (`ui/screens/Timeline.kt`) is applied too; the + Android `:app:assembleDebug` and `:app:testDebugUnitTest` → BUILD SUCCESSFUL + after it. +- On screen (Pixel 9 Pro XL `47241FDAS00DLK`, the deployed server at + `ws://10.0.0.75:8080/connect`, never restarted): a run recorded before the + change (run 344) shows `Artifacts · 3 recorded` where the old build showed + `5 recorded`, the committer visit shows `Artifacts · 1 recorded` listing only + `session.html 67.2 KiB` (the `session.md 60.9 KiB` tile is gone), and the + Session section renders the html document in the WebView with no + Markdown/HTML toggle. Captures are attached to this stage. The device was + contended by a concurrent lane (another build was installed over this one and + taps were interleaved), which is why some intermediate captures show the old + build; the proofs are the ones with the WIP md5 `36a6ffc7…` verified installed. + The phone was left on main's build (`deploy-app.sh main`, md5 verified). + +## Shared documents this change makes stale + +The note is written here rather than edited in place; the `docs-fold` writer +should update these. + +- `docs/stage-artifacts.md` — the "Session export" section (about lines 55–83) + says the export writes `session.md` and `session.html` "in markdown … and + html", that "the bounded inventory lists them" and that + `GET /artifacts///session.md` (or `.html`) serves them, that + "both files carry a visible truncation banner", that the step records + `session_export` with `markdown`, `html`, `markdown_bytes`, `html_bytes`, and + that an existing `session.md`/`session.html` is never overwritten. It should + say the export writes exactly one file, `session.html`; that the retired + `session.md` is no longer produced and is not presented (a run recorded before + the change still lists it in its stored artifacts, and the app hides it); that + the one rendered file carries the banner; and that the recorded + `session_export` is `session_id`, `backend`, `source`, `html`, `html_bytes`, + `messages`, `truncated`, `diagnostic`, with a record written before the change + still decoding because the retired fields are ignored. +- `internal/author/skill/references/operations.md` (around lines 235–250) and + `internal/author/skill/references/delivery.md` (around lines 20–21) — both + still describe the `session.md`+`session.html` pair, the two-file bounds and + the pair's never-overwrite rule. The brief assigns these packaged references to + the committer; they should describe the single `session.html` export, the + 2 MiB rendered-file cap, and that the retired `session.md` is neither produced + nor presented. +- `docs/app-integration-verification.md` line 38 — a dated verification record of + run 330 whose artifacts-gallery row lists `session.md 81.7 KiB` beside + `session.html`. It is a historical record for that run and date; if it is kept + as dated evidence it needs no edit, but a reader should not take it as current + behaviour. + +## Not stale + +- `README.md` and `internal/author/skill/SKILL.md` carry no `session.md` + reference. +- No reference file is added or removed, so `internal/author/install.go`'s + managed inventory is unchanged. +- `docs/cli.md` does not enumerate the `session_export` fields. +- `internal/tui`'s artifacts panel did reference the recorded artifact list, so it + was changed with this item (it and the web spike now filter the retired + `session.md` the same way the app does). +- `web/src/app.js` is a throwaway spike with no test for its render helpers; its + artifact list now applies the same filter. diff --git a/internal/author/skill/references/delivery.md b/internal/author/skill/references/delivery.md index f6d7b0af..39536633 100644 --- a/internal/author/skill/references/delivery.md +++ b/internal/author/skill/references/delivery.md @@ -17,11 +17,13 @@ with its own rules. oversized file records nothing and never changes the verdict. Never invent an artifact or claim a stage produced one — the server observes the directory after the stage. -- An OpenCode-harness stage also gets its real session exported as `session.md` and - `session.html` in the same directory: bounded (8 MiB source, 2 MiB per file), with +- An OpenCode-harness stage also gets its real session exported as one file, + `session.html`, in the same directory: bounded (8 MiB source, 2 MiB rendered), with a visible truncation banner and `session_export.truncated` when cut; the step's - `session_export` records the files. Export failures and Pi (no native export path) - record a diagnostic and never fail the run or change the stage result. + `session_export` records the file. The `session.md` export is retired — never + written, never presented (a run recorded before the change still lists it and every + listing hides it). Export failures and Pi (no native export path) record a + diagnostic and never fail the run or change the stage result. ## Publish a build to the LAN diff --git a/internal/author/skill/references/operations.md b/internal/author/skill/references/operations.md index d9414275..e379e74d 100644 --- a/internal/author/skill/references/operations.md +++ b/internal/author/skill/references/operations.md @@ -236,16 +236,22 @@ traversal, absolute paths, symlink escapes and unknown runs/steps. - When an OpenCode-harness model stage finishes, the server exports its real session read-only (v1 `opencode export `, v2 `opencode session export `) - and writes `session.md` and `session.html` into the same `/` artifacts - directory; they list and serve like any other artifact. -- The source read is capped at 8 MiB and each file at 2 MiB; a cut source or a cut - rendered file carries a visible truncation banner at both ends and + and writes exactly one file, `session.html`, into the same `/` artifacts + directory; it lists and serves like any other artifact. +- The `session.md` export is retired: nothing writes it any more and it is never + presented. A run recorded before the HTML-only change still lists `session.md` + among its stored artifacts (dated evidence kept on disk, not deleted); every + listing — app, TUI, web spike — hides it rather than showing it beside the html. +- The source read is capped at 8 MiB and the rendered file at 2 MiB; a cut source or + a cut rendered file carries a visible truncation banner at both ends and `session_export.truncated: true`, and a truncated export is never called whole. -- The step records `session_export` (`session_id`, `backend`, `source`, file names, - sizes, `messages`, `truncated`, `diagnostic`) in `inspect RUN_ID --json`. +- The step records `session_export` (`session_id`, `backend`, `source`, the html + file name, `html_bytes`, `messages`, `truncated`, `diagnostic`) in + `inspect RUN_ID --json`. A record written before the change still carried + `markdown` and `markdown_bytes`; readers ignore those fields. - A failed export, or a Pi stage with no native export path, records a diagnostic (Pi: `source: "unavailable"`) and never fails the run or changes the stage result. - An existing `session.md`/`session.html` is never overwritten. + An existing `session.html` is never overwritten. ### Operator-only retention diff --git a/internal/pipeline/runs_test.go b/internal/pipeline/runs_test.go index 043dcfd6..0cba993a 100644 --- a/internal/pipeline/runs_test.go +++ b/internal/pipeline/runs_test.go @@ -477,8 +477,7 @@ func TestSessionExportRoundTripAndAbsentEvidence(t *testing.T) { } want := &protocol.SessionExport{ SessionID: "ses_recorded", Backend: "v2", Source: "native_export", - Markdown: "session.md", HTML: "session.html", - MarkdownBytes: 1234, HTMLBytes: 2345, Messages: 9, Truncated: true, + HTML: "session.html", HTMLBytes: 2345, Messages: 9, Truncated: true, Diagnostic: "kept", } if err := store.FinishStep(ctx, withExport, protocol.RunStep{Sequence: 1, Stage: "one", Status: "completed", Outcome: "success", Output: map[string]any{}, Transcript: strings.Repeat("x", 40<<10), SessionExport: want}); err != nil { @@ -506,3 +505,39 @@ func TestSessionExportRoundTripAndAbsentEvidence(t *testing.T) { t.Fatalf("absent export evidence was fabricated: %+v", plain.Steps[0].SessionExport) } } + +// TestSessionExportIgnoresLegacyMarkdownFields proves a record written before +// the HTML-only change still loads: the retired markdown fields are ignored and +// the html evidence is read, so an older database opens cleanly. +func TestSessionExportIgnoresLegacyMarkdownFields(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "legacy-session-exports.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "legacy-exports", Template([]string{"one"}, true)); err != nil { + t.Fatal(err) + } + items, _ := store.List(ctx) + definition, _ := store.Get(ctx, items[0].ID, 1) + runID, _, err := store.CreateRun(ctx, definition, "legacy", "workspace", false, nil, map[string]any{"prompt": "task"}) + if err != nil { + t.Fatal(err) + } + if err := store.BeginStep(ctx, runID, 1, "one", map[string]any{"prompt": "task"}); err != nil { + t.Fatal(err) + } + legacy := `{"session_id":"ses_old","backend":"v2","source":"native_export","markdown":"session.md","html":"session.html","markdown_bytes":111,"html_bytes":222,"messages":3}` + if _, err := store.db.ExecContext(ctx, "INSERT INTO step_session_exports(run_id,sequence,export_json) VALUES(?,?,?)", runID, 1, legacy); err != nil { + t.Fatal(err) + } + detail, err := store.GetRun(ctx, runID) + if err != nil { + t.Fatalf("an older database must still open: %v", err) + } + got := detail.Steps[0].SessionExport + if got == nil || got.HTML != "session.html" || got.HTMLBytes != 222 || got.Messages != 3 || got.SessionID != "ses_old" { + t.Fatalf("legacy export record did not load: %+v", got) + } +} diff --git a/internal/protocol/runs.go b/internal/protocol/runs.go index ee312d0d..87d94a1e 100644 --- a/internal/protocol/runs.go +++ b/internal/protocol/runs.go @@ -101,20 +101,20 @@ type SessionEvidence struct { } // SessionExport is the recorded evidence of one stage's session file export: -// the file names written under the step's artifacts directory, their byte sizes, -// the decoded message count, the source, whether the export was truncated and a -// sanitized diagnostic. It is observed server-side evidence, not a model claim. +// the html file name written under the step's artifacts directory, its byte +// size, the decoded message count, the source, whether the export was truncated +// and a sanitized diagnostic. It is observed server-side evidence, not a model +// claim. A record written before the HTML-only change also carried markdown and +// markdown_bytes; readers ignore those fields. type SessionExport struct { - SessionID string `json:"session_id,omitempty"` - Backend string `json:"backend,omitempty"` - Source string `json:"source,omitempty"` - Markdown string `json:"markdown,omitempty"` - HTML string `json:"html,omitempty"` - MarkdownBytes int64 `json:"markdown_bytes,omitempty"` - HTMLBytes int64 `json:"html_bytes,omitempty"` - Messages int `json:"messages"` - Truncated bool `json:"truncated,omitempty"` - Diagnostic string `json:"diagnostic,omitempty"` + SessionID string `json:"session_id,omitempty"` + Backend string `json:"backend,omitempty"` + Source string `json:"source,omitempty"` + HTML string `json:"html,omitempty"` + HTMLBytes int64 `json:"html_bytes,omitempty"` + Messages int `json:"messages"` + Truncated bool `json:"truncated,omitempty"` + Diagnostic string `json:"diagnostic,omitempty"` } type RunSummary struct { @@ -197,6 +197,38 @@ type StageArtifact struct { URL string `json:"url"` } +// LegacySessionMarkdownArtifact is the retired markdown session export file name. +// Nothing writes it any more, but a run recorded before the HTML-only change +// still lists session.md among its stored artifacts: it is dated evidence that is +// never presented, so every listing hides it rather than showing it beside the +// session html. This is the one definition of the retired name, shared by the +// stage export and the clients. +const LegacySessionMarkdownArtifact = "session.md" + +// PresentedArtifacts is one step's recorded artifacts as they are presented: the +// files with the retired markdown session export filtered out. It is the single +// rule every Go artifact listing derives from, so a stage's artifacts never show +// a session markdown beside the session html and a recorded count can never +// disagree with the tiles. It never mutates the step and returns nil when nothing +// is presented; the stored record still carries the legacy file. Pure, +// O(artifacts) per step. +func (s RunStep) PresentedArtifacts() []StageArtifact { + if len(s.Artifacts) == 0 { + return nil + } + presented := make([]StageArtifact, 0, len(s.Artifacts)) + for _, artifact := range s.Artifacts { + if artifact.Name == LegacySessionMarkdownArtifact { + continue + } + presented = append(presented, artifact) + } + if len(presented) == 0 { + return nil + } + return presented +} + // StageUsage is the usage one model stage actually reported, carried from the // stage's already-measured budget accounting rather than a second measurement or // a transcript parse. TokensTotal/TokensKnown are the reported total; TokensIn diff --git a/internal/protocol/runs_test.go b/internal/protocol/runs_test.go index b5486e2c..25472b6c 100644 --- a/internal/protocol/runs_test.go +++ b/internal/protocol/runs_test.go @@ -51,3 +51,25 @@ func TestRunStepOmitsAbsentArtifacts(t *testing.T) { t.Fatalf("absent field must decode empty: %+v", decoded) } } + +func TestPresentedArtifactsHidesRetiredSessionMarkdown(t *testing.T) { + step := RunStep{Artifacts: []StageArtifact{ + {Name: "session.md", URL: "/artifacts/344/1/session.md"}, + {Name: "session.html", URL: "/artifacts/344/1/session.html"}, + {Name: "shot.png", URL: "/artifacts/344/1/shot.png"}, + }} + presented := step.PresentedArtifacts() + if len(presented) != 2 || presented[0].Name != "session.html" || presented[1].Name != "shot.png" { + t.Fatalf("presented = %+v", presented) + } + if len(step.Artifacts) != 3 { + t.Fatalf("PresentedArtifacts mutated the stored record: %+v", step.Artifacts) + } + if got := (RunStep{}).PresentedArtifacts(); got != nil { + t.Fatalf("empty step presented %+v, want nil", got) + } + onlyLegacy := RunStep{Artifacts: []StageArtifact{{Name: LegacySessionMarkdownArtifact}}} + if got := onlyLegacy.PresentedArtifacts(); got != nil { + t.Fatalf("legacy-only step presented %+v, want nil", got) + } +} diff --git a/internal/server/runner.go b/internal/server/runner.go index 6afe105a..0c532247 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -1225,9 +1225,7 @@ func (r *runner) exportStageSession(ctx context.Context, owner pipeline.SessionO return evidence } evidence.Source = result.Source - evidence.Markdown = result.Markdown evidence.HTML = result.HTML - evidence.MarkdownBytes = result.MarkdownBytes evidence.HTMLBytes = result.HTMLBytes evidence.Messages = result.Messages evidence.Truncated = result.Truncated diff --git a/internal/server/session_export_live_test.go b/internal/server/session_export_live_test.go index f6a73fe0..b05c531a 100644 --- a/internal/server/session_export_live_test.go +++ b/internal/server/session_export_live_test.go @@ -30,8 +30,8 @@ func sessionExportLiveSource(provider, model string) string { // TestSessionExportLive is an opt-in live check: it runs one real OpenCode stage // on a temporary store and artifacts root using the configured host harness, -// then proves the real session.md/session.html are written, listed and served -// 200. It is gated so the default suite never spends inference. +// then proves the real session.html is written, listed and served 200. It is +// gated so the default suite never spends inference. func TestSessionExportLive(t *testing.T) { if os.Getenv("PIPELINES_SESSION_EXPORT_LIVE") != "1" { t.Skip("set PIPELINES_SESSION_EXPORT_LIVE=1 and PIPELINES_SESSION_EXPORT_MODEL to run chargeable session-export inference") @@ -89,15 +89,18 @@ func TestSessionExportLive(t *testing.T) { t.Fatalf("live run did not succeed: %+v", detail) } step := detail.Steps[0] - if step.SessionExport == nil || step.SessionExport.Source != "native_export" || step.SessionExport.MarkdownBytes == 0 || step.SessionExport.HTMLBytes == 0 { + if step.SessionExport == nil || step.SessionExport.Source != "native_export" || step.SessionExport.HTML != "session.html" || step.SessionExport.HTMLBytes == 0 { t.Fatalf("live session export evidence missing: %+v", step.SessionExport) } if step.SessionExport.Messages == 0 || step.SessionExport.Truncated { t.Fatalf("live session export was empty or truncated: %+v", step.SessionExport) } + if _, ok := artifactNamed(step.Artifacts, stage.SessionMarkdownFile); ok { + t.Fatalf("live run produced a legacy session.md: %+v", step.Artifacts) + } srv := httptest.NewServer(handler) defer srv.Close() - for _, name := range []string{"session.md", "session.html"} { + for _, name := range []string{stage.SessionHTMLFile} { artifact, ok := artifactNamed(step.Artifacts, name) if !ok { t.Fatalf("%s not in live artifact listing: %+v", name, step.Artifacts) @@ -150,19 +153,23 @@ func TestSessionExportRecorded(t *testing.T) { if err != nil { t.Fatalf("recorded session export failed: %v", err) } - for _, name := range []string{stage.SessionMarkdownFile, stage.SessionHTMLFile} { - info, err := os.Stat(filepath.Join(dir, name)) - if err != nil { - t.Fatal(err) - } - data, _ := os.ReadFile(filepath.Join(dir, name)) - first := string(data) - if idx := strings.IndexByte(first, '\n'); idx >= 0 { - first = first[:idx] - } - t.Logf("recorded export (NOT a fresh runner stage) %s: path=%s size=%d first_line=%q", name, filepath.Join(dir, name), info.Size(), first) + if result.HTML != stage.SessionHTMLFile || result.HTMLBytes == 0 { + t.Fatalf("recorded export wrote no html: %+v", result) } - if result.MarkdownBytes == 0 || result.HTMLBytes == 0 { - t.Fatalf("recorded export wrote no files: %+v", result) + htmlPath := filepath.Join(dir, stage.SessionHTMLFile) + info, err := os.Stat(htmlPath) + if err != nil { + t.Fatal(err) + } + data, _ := os.ReadFile(htmlPath) + first := string(data) + if idx := strings.IndexByte(first, '\n'); idx >= 0 { + first = first[:idx] + } + t.Logf("recorded export (NOT a fresh runner stage) %s: path=%s size=%d first_line=%q", stage.SessionHTMLFile, htmlPath, info.Size(), first) + if _, err := os.Stat(filepath.Join(dir, stage.SessionMarkdownFile)); err == nil { + // A pre-existing session.md from an older run may sit here; the export + // must not have produced or rewritten it. + t.Logf("pre-existing %s left in place; the export writes no markdown", stage.SessionMarkdownFile) } } diff --git a/internal/server/session_export_test.go b/internal/server/session_export_test.go index fae4ad01..4aa25bba 100644 --- a/internal/server/session_export_test.go +++ b/internal/server/session_export_test.go @@ -86,11 +86,11 @@ func sessionExportRunner(t *testing.T, backend string, seam func(stage.SessionEx return handler, store, run.ID } -// TestRunnerExportsSessionFilesIntoArtifactsAndServesThem proves the real export -// path writes both files into the step's artifacts directory, lists them with -// artifact URLs and serves them 200, without changing the step's status, outcome -// or target. -func TestRunnerExportsSessionFilesIntoArtifactsAndServesThem(t *testing.T) { +// TestRunnerExportsTheHTMLSessionIntoArtifactsAndServesIt proves the real export +// path writes the one html session file into the step's artifacts directory, +// lists it with an artifact URL and serves it 200, without changing the step's +// status, outcome or target, and produces no legacy session.md. +func TestRunnerExportsTheHTMLSessionIntoArtifactsAndServesIt(t *testing.T) { sessionExportCLI(t) handler, store, runID := sessionExportRunner(t, "v2", nil) detail, err := store.GetRun(context.Background(), runID) @@ -110,45 +110,37 @@ func TestRunnerExportsSessionFilesIntoArtifactsAndServesThem(t *testing.T) { if step.SessionExport == nil || step.SessionExport.SessionID != "ses_run" || step.SessionExport.Source != "native_export" { t.Fatalf("export evidence missing: %+v", step.SessionExport) } - if step.SessionExport.Messages != 2 || step.SessionExport.MarkdownBytes == 0 || step.SessionExport.HTMLBytes == 0 { + if step.SessionExport.HTML != "session.html" || step.SessionExport.Messages != 2 || step.SessionExport.HTMLBytes == 0 { t.Fatalf("export evidence wrong: %+v", step.SessionExport) } - for _, name := range []string{"session.md", "session.html"} { - artifact, ok := artifactNamed(step.Artifacts, name) - if !ok { - t.Fatalf("%s not in the artifact listing: %+v", name, step.Artifacts) - } - wantURL := fmt.Sprintf("/artifacts/%d/1/%s", runID, name) - if artifact.URL != wantURL || artifact.SizeBytes == 0 { - t.Fatalf("%s listing wrong: %+v", name, artifact) - } + if _, ok := artifactNamed(step.Artifacts, stage.SessionMarkdownFile); ok { + t.Fatalf("legacy session.md must not be produced: %+v", step.Artifacts) + } + artifact, ok := artifactNamed(step.Artifacts, "session.html") + if !ok { + t.Fatalf("session.html not in the artifact listing: %+v", step.Artifacts) + } + wantURL := fmt.Sprintf("/artifacts/%d/1/session.html", runID) + if artifact.URL != wantURL || artifact.SizeBytes == 0 { + t.Fatalf("session.html listing wrong: %+v", artifact) } srv := httptest.NewServer(handler) defer srv.Close() - for _, name := range []string{"session.md", "session.html"} { - resp, err := http.Get(srv.URL + fmt.Sprintf("/artifacts/%d/1/%s", runID, name)) - if err != nil { - t.Fatal(err) - } - body, _ := io.ReadAll(resp.Body) - resp.Body.Close() - if resp.StatusCode != http.StatusOK || len(body) == 0 { - t.Fatalf("%s served %d (%d bytes)", name, resp.StatusCode, len(body)) - } - contentType := resp.Header.Get("Content-Type") - if name == "session.md" && !strings.HasPrefix(contentType, "text/markdown") && !strings.HasPrefix(contentType, "text/plain") { - t.Fatalf("session.md content type = %q", contentType) - } - if name == "session.html" && !strings.HasPrefix(contentType, "text/html") { - t.Fatalf("session.html content type = %q", contentType) - } - if name == "session.md" && !strings.Contains(string(body), "do the task") { - t.Fatalf("served markdown missing session text") - } - if name == "session.html" && !strings.Contains(string(body), "output here") { - t.Fatalf("served html missing tool output") - } + resp, err := http.Get(srv.URL + wantURL) + if err != nil { + t.Fatal(err) + } + body, _ := io.ReadAll(resp.Body) + resp.Body.Close() + if resp.StatusCode != http.StatusOK || len(body) == 0 { + t.Fatalf("session.html served %d (%d bytes)", resp.StatusCode, len(body)) + } + if contentType := resp.Header.Get("Content-Type"); !strings.HasPrefix(contentType, "text/html") { + t.Fatalf("session.html content type = %q", contentType) + } + if !strings.Contains(string(body), "output here") { + t.Fatal("served html missing tool output") } } diff --git a/internal/stage/session_export.go b/internal/stage/session_export.go index 4732e904..98175b71 100644 --- a/internal/stage/session_export.go +++ b/internal/stage/session_export.go @@ -16,13 +16,18 @@ import ( ) // Session file export bounds. A stage's session is written under its own -// artifacts directory in markdown and html so the existing artifact listing and +// artifacts directory as one html file so the existing artifact listing and // serving paths find it with no special casing. The source read is capped at -// SessionExportSourceLimit and each rendered file at SessionExportFileLimit, so -// the pair adds at most ~4 MiB per step, inside the artifact scan limits. +// SessionExportSourceLimit and the rendered file at SessionExportFileLimit, so +// the export adds at most ~2 MiB per step, inside the artifact scan limits. const ( - SessionMarkdownFile = "session.md" - SessionHTMLFile = "session.html" + // SessionHTMLFile is the one session export a stage writes. + SessionHTMLFile = "session.html" + // SessionMarkdownFile is the retired markdown session export name. Nothing + // writes it any more; a run recorded before the HTML-only change may still + // have it on disk, where it is dated evidence that is never presented. It is + // the protocol's one definition of the retired name, not a second copy. + SessionMarkdownFile = protocol.LegacySessionMarkdownArtifact // SessionExportSourceLimit is the native session read cap; it is the one // opencode.MaxSessionExport value, not a second copy. SessionExportSourceLimit = opencode.MaxSessionExport @@ -45,36 +50,32 @@ type SessionExportRequest struct { Model string } -// SessionExportResult is the outcome of one session export. Markdown/HTML are -// the written file names, their byte sizes, the decoded message count, the -// source, whether either file or the source was truncated and a sanitized -// diagnostic (for example a skipped overwrite). +// SessionExportResult is the outcome of one session export: the written html +// file name, its byte size, the decoded message count, the source, whether the +// source or the rendered file was truncated and a sanitized diagnostic (for +// example a skipped overwrite). type SessionExportResult struct { - Markdown string - HTML string - MarkdownBytes int64 - HTMLBytes int64 - Messages int - Source string - Truncated bool - Diagnostic string + HTML string + HTMLBytes int64 + Messages int + Source string + Truncated bool + Diagnostic string } const ( // sessionExportSource is the recorded source of a native-export readback. sessionExportSource = "native_export" - // markdownTruncationBanner and htmlTruncationBanner are the visible labels a - // truncated export carries near its start and end so it is never mistaken for - // the whole session. - markdownTruncationBanner = "\n> **TRUNCATED**: this exported session is not the whole session; it was cut at the export size cap.\n" - htmlTruncationBanner = "

TRUNCATED: this exported session is not the whole session; it was cut at the export size cap.

\n" + // htmlTruncationBanner is the visible label a truncated export carries near + // its start and end so it is never mistaken for the whole session. + htmlTruncationBanner = "

TRUNCATED: this exported session is not the whole session; it was cut at the export size cap.

\n" ) // ExportSession reads the stage's session read-only through the native export -// path, renders it to bounded markdown and html and writes both files -// atomically into the step's artifacts directory, refusing to overwrite an -// existing file. It returns a sanitized error and writes nothing when the read -// fails; it never mutates, resumes, interrupts or deletes the session. +// path, renders it to one bounded html file and writes it atomically into the +// step's artifacts directory, refusing to overwrite an existing file. It returns +// a sanitized error and writes nothing when the read fails; it never mutates, +// resumes, interrupts or deletes the session. func ExportSession(ctx context.Context, request SessionExportRequest) (SessionExportResult, error) { if !opencode.ValidSessionID(request.SessionID) { return SessionExportResult{}, fmt.Errorf("session export: invalid session ID") @@ -86,103 +87,62 @@ func ExportSession(ctx context.Context, request SessionExportRequest) (SessionEx if err != nil { return SessionExportResult{}, fmt.Errorf("session export: %s", RedactEvidence(err.Error())) } - markdown, markdownTruncated := renderSessionMarkdown(session, request) htmlDoc, htmlTruncated := renderSessionHTML(session, request) result := SessionExportResult{ - Markdown: SessionMarkdownFile, - HTML: SessionHTMLFile, - Messages: len(session.Messages), - Source: sessionExportSource, - Truncated: session.Truncated || markdownTruncated || htmlTruncated, - Diagnostic: "", + HTML: SessionHTMLFile, + Messages: len(session.Messages), + Source: sessionExportSource, + Truncated: session.Truncated || htmlTruncated, } - written, diagnostic, err := writeSessionPair(request.ArtifactsDir, []sessionFile{ - {name: SessionMarkdownFile, data: []byte(markdown)}, - {name: SessionHTMLFile, data: []byte(htmlDoc)}, - }) + written, diagnostic, err := writeSessionFile(request.ArtifactsDir, SessionHTMLFile, []byte(htmlDoc)) if err != nil { return SessionExportResult{}, fmt.Errorf("session export: %s", RedactEvidence(err.Error())) } - if written[0] { - result.MarkdownBytes = int64(len(markdown)) - } - if written[1] { + if written { result.HTMLBytes = int64(len(htmlDoc)) } result.Diagnostic = diagnostic return result, nil } -// sessionFile is one rendered file to write into the artifacts directory. -type sessionFile struct { - name string - data []byte +// writeSessionFile stages the rendered file to a temporary file, then renames it +// into place, so a failure before the rename leaves no partial session.html +// behind. An existing target is never overwritten: it is skipped and the reason +// is returned as a diagnostic. +func writeSessionFile(dir, name string, data []byte) (bool, string, error) { + target := filepath.Join(dir, name) + if _, err := os.Lstat(target); err == nil { + return false, "existing " + name + " was not overwritten", nil + } else if !os.IsNotExist(err) { + return false, "", err + } + tmp, err := os.CreateTemp(dir, "."+name+".tmp-*") + if err != nil { + return false, "", err + } + if _, err := tmp.Write(data); err != nil { + tmp.Close() + _ = os.Remove(tmp.Name()) + return false, "", err + } + if err := tmp.Close(); err != nil { + _ = os.Remove(tmp.Name()) + return false, "", err + } + if err := os.Rename(tmp.Name(), target); err != nil { + _ = os.Remove(tmp.Name()) + return false, "", err + } + return true, "", nil } -// writeSessionPair stages every rendered file to a temporary file, then renames -// each into place, so a failure before the renames leaves no partial session.md -// or session.html behind. An existing target is never overwritten: its file is -// skipped and the reason is returned as a diagnostic. -func writeSessionPair(dir string, files []sessionFile) ([]bool, string, error) { - written := make([]bool, len(files)) - temps := make([]string, len(files)) - cleanup := func() { - for _, tmp := range temps { - if tmp != "" { - _ = os.Remove(tmp) - } - } - } - var skipped []string - for i, file := range files { - target := filepath.Join(dir, file.name) - if _, err := os.Lstat(target); err == nil { - skipped = append(skipped, file.name) - continue - } else if !os.IsNotExist(err) { - cleanup() - return written, "", err - } - tmp, err := os.CreateTemp(dir, "."+file.name+".tmp-*") - if err != nil { - cleanup() - return written, "", err - } - temps[i] = tmp.Name() - if _, err := tmp.Write(file.data); err != nil { - tmp.Close() - cleanup() - return written, "", err - } - if err := tmp.Close(); err != nil { - cleanup() - return written, "", err - } - } - for i, file := range files { - if temps[i] == "" { - continue - } - if err := os.Rename(temps[i], filepath.Join(dir, file.name)); err != nil { - cleanup() - return written, "", err - } - written[i] = true - } - diagnostic := "" - if len(skipped) > 0 { - diagnostic = "existing " + strings.Join(skipped, ", ") + " was not overwritten" - } - return written, diagnostic, nil -} - -// sessionMeta is one metadata row the rendered files carry. +// sessionMeta is one metadata row the rendered file carries. type sessionMeta struct { label string value string } -// sessionMetadata is the run/step/session identity both renderers show, so a +// sessionMetadata is the run/step/session identity the html renderer shows, so a // file is self-describing without the run record. func sessionMetadata(session opencode.ExportedSession, request SessionExportRequest) []sessionMeta { meta := []sessionMeta{ @@ -205,114 +165,6 @@ func sessionMetadata(session opencode.ExportedSession, request SessionExportRequ return meta } -// renderSessionMarkdown renders the session as bounded markdown. The second -// result reports whether the rendered file itself was cut at the cap. -func renderSessionMarkdown(session opencode.ExportedSession, request SessionExportRequest) (string, bool) { - var header bytes.Buffer - header.WriteString("# Stage session export\n\n") - for _, meta := range sessionMetadata(session, request) { - fmt.Fprintf(&header, "- %s: %s\n", meta.label, meta.value) - } - header.WriteString("\n") - - var body bytes.Buffer - if len(session.Messages) == 0 { - body.WriteString("_No messages were recorded for this session._\n\n") - } - for i, message := range session.Messages { - renderMarkdownMessage(&body, i+1, message) - } - return assembleSessionFile(header.String(), body.String(), session.Truncated, markdownTruncationBanner, markdownTruncationBanner) -} - -// renderMarkdownMessage renders one turn with its role and parts. -func renderMarkdownMessage(out *bytes.Buffer, index int, message opencode.ExportedMessage) { - role := message.Role - if role == "" { - role = "unknown" - } - fmt.Fprintf(out, "## %d. %s\n\n", index, role) - var details bytes.Buffer - if message.ID != "" { - fmt.Fprintf(&details, "- id: %s\n", message.ID) - } - if message.Model != "" { - fmt.Fprintf(&details, "- model: %s\n", message.Model) - } - if message.Agent != "" { - fmt.Fprintf(&details, "- agent: %s\n", message.Agent) - } - if message.CreatedAt != 0 { - fmt.Fprintf(&details, "- created_at: %d\n", message.CreatedAt) - } - if details.Len() > 0 { - out.WriteString(details.String()) - out.WriteString("\n") - } - for _, part := range message.Parts { - renderMarkdownPart(out, part) - } -} - -// renderMarkdownPart renders one content element. Unknown types are rendered as -// their raw JSON rather than dropped. -func renderMarkdownPart(out *bytes.Buffer, part opencode.ExportedPart) { - switch part.Type { - case protocol.ChatPartText: - out.WriteString(part.Text) - out.WriteString("\n\n") - case protocol.ChatPartReasoning: - fmt.Fprintf(out, "_reasoning_\n\n%s\n\n", part.Text) - case protocol.ChatPartTool: - renderMarkdownTool(out, part) - default: - label := part.Type - if label == "" { - label = "unknown" - } - fmt.Fprintf(out, "### %s\n\n", label) - raw := part.Raw - if len(raw) == 0 { - raw = []byte("{}") - } - fence := dynamicFence(string(raw)) - fmt.Fprintf(out, "%sjson\n%s\n%s\n\n", fence, strings.TrimSpace(string(raw)), fence) - } -} - -// renderMarkdownTool renders a tool call with its name, status, input, result -// and error. -func renderMarkdownTool(out *bytes.Buffer, part opencode.ExportedPart) { - name := part.Name - if name == "" { - name = part.ID - } - status := "" - if part.State != nil { - status = part.State.Status - } - fmt.Fprintf(out, "### tool: %s (%s)\n\n", name, status) - if part.State == nil { - return - } - if len(part.State.Input) > 0 { - input := string(part.State.Input) - fence := dynamicFence(input) - fmt.Fprintf(out, "input:\n\n%sjson\n%s\n%s\n\n", fence, strings.TrimSpace(input), fence) - } - for _, content := range part.State.Content { - if content.Text != "" { - out.WriteString(content.Text) - out.WriteString("\n\n") - } else if content.URI != "" { - fmt.Fprintf(out, "- %s (%s)\n", content.URI, content.Mime) - } - } - if part.State.Error != nil { - fmt.Fprintf(out, "error: %s\n\n", part.State.Error.Message) - } -} - // renderSessionHTML renders the session as bounded html, escaping every session // text value. The second result reports whether the rendered file was cut. func renderSessionHTML(session opencode.ExportedSession, request SessionExportRequest) (string, bool) { @@ -440,13 +292,3 @@ func assembleSessionFile(header, body string, sourceTruncated bool, leading, tra } return result, rendered } - -// dynamicFence returns a run of at least three backticks longer than any run in -// text, so markdown content that itself contains a fence cannot break out. -func dynamicFence(text string) string { - fence := "```" - for strings.Contains(text, fence) { - fence += "`" - } - return fence -} diff --git a/internal/stage/session_export_test.go b/internal/stage/session_export_test.go index 73af47a3..f6318bf6 100644 --- a/internal/stage/session_export_test.go +++ b/internal/stage/session_export_test.go @@ -43,43 +43,36 @@ func sessionRequest(dir string) SessionExportRequest { } } -func TestExportSessionWritesBothFilesWithRealContent(t *testing.T) { +func TestExportSessionWritesTheHTMLFileWithRealContent(t *testing.T) { dir := t.TempDir() sessionCLI(t, "ses_ok", sessionBody()) result, err := ExportSession(context.Background(), sessionRequest(dir)) if err != nil { t.Fatal(err) } - if result.Markdown != "session.md" || result.HTML != "session.html" { - t.Fatalf("file names wrong: %+v", result) + if result.HTML != "session.html" { + t.Fatalf("file name wrong: %+v", result) } if result.Messages != 2 || result.Source != "native_export" || result.Truncated { t.Fatalf("evidence wrong: %+v", result) } - markdown, err := os.ReadFile(filepath.Join(dir, SessionMarkdownFile)) - if err != nil { - t.Fatal(err) + // The retired markdown export is never written. + if _, err := os.Stat(filepath.Join(dir, SessionMarkdownFile)); !os.IsNotExist(err) { + t.Fatalf("session.md must not be produced: %v", err) } htmlDoc, err := os.ReadFile(filepath.Join(dir, SessionHTMLFile)) if err != nil { t.Fatal(err) } - if result.MarkdownBytes != int64(len(markdown)) || result.HTMLBytes != int64(len(htmlDoc)) { - t.Fatalf("sizes wrong: %+v", result) + if result.HTMLBytes != int64(len(htmlDoc)) { + t.Fatalf("size wrong: %+v", result) } - for _, want := range []string{"hello &\" world", "thinking hard", "tool: read (completed)", "tool output", `{"path":"a.go"}`, "please run"} { - if !strings.Contains(string(markdown), want) { - t.Fatalf("markdown missing %q", want) - } - } - if !strings.Contains(string(markdown), "file:///tmp/x") { - t.Fatal("markdown dropped the unknown 'file' part") - } - // HTML must escape session text and still carry the tool detail. + // HTML must escape session text and still carry the tool detail and the + // unknown 'file' part. if strings.Contains(string(htmlDoc), "") { t.Fatal("html rendered unescaped session text") } - for _, want := range []string{"<b>", "&", "tool: read (completed)", "tool output"} { + for _, want := range []string{"<b>", "&", "tool: read (completed)", "tool output", "file:///tmp/x"} { if !strings.Contains(string(htmlDoc), want) { t.Fatalf("html missing %q", want) } @@ -91,7 +84,7 @@ func TestExportSessionWritesBothFilesWithRealContent(t *testing.T) { } } -func TestExportSessionRenderedTruncationBannerInBothFiles(t *testing.T) { +func TestExportSessionRenderedTruncationBanner(t *testing.T) { // A source under the read cap but whose rendering exceeds the file cap. huge := strings.Repeat("line of text\n", SessionExportFileLimit/7) session := opencode.ExportedSession{ @@ -102,18 +95,15 @@ func TestExportSessionRenderedTruncationBannerInBothFiles(t *testing.T) { Parts: []opencode.ExportedPart{{Type: "text", Text: huge}}, }}, } - markdown, mdTruncated := renderSessionMarkdown(session, sessionRequest(t.TempDir())) htmlDoc, htmlTruncated := renderSessionHTML(session, sessionRequest(t.TempDir())) - if !mdTruncated || !htmlTruncated { - t.Fatalf("rendered truncation not reported: md=%v html=%v", mdTruncated, htmlTruncated) + if !htmlTruncated { + t.Fatal("rendered truncation not reported") } - for name, content := range map[string]string{"markdown": markdown, "html": htmlDoc} { - if len(content) > SessionExportFileLimit { - t.Fatalf("%s exceeds cap: %d", name, len(content)) - } - if strings.Count(content, "TRUNCATED") < 2 { - t.Fatalf("%s lacks a leading and trailing truncation banner", name) - } + if len(htmlDoc) > SessionExportFileLimit { + t.Fatalf("html exceeds cap: %d", len(htmlDoc)) + } + if strings.Count(htmlDoc, "TRUNCATED") < 2 { + t.Fatal("html lacks a leading and trailing truncation banner") } } @@ -124,27 +114,52 @@ func TestExportSessionSourceTruncationIsLabelledNotWhole(t *testing.T) { Truncated: true, Messages: []opencode.ExportedMessage{{Role: "assistant", Parts: []opencode.ExportedPart{{Type: "text", Text: "partial"}}}}, } - markdown, _ := renderSessionMarkdown(session, sessionRequest(t.TempDir())) - if strings.Count(markdown, "TRUNCATED") < 2 { - t.Fatalf("source truncation must be labelled at both ends:\n%s", markdown) + htmlDoc, _ := renderSessionHTML(session, sessionRequest(t.TempDir())) + if strings.Count(htmlDoc, "TRUNCATED") < 2 { + t.Fatalf("source truncation must be labelled at both ends:\n%s", htmlDoc) } - if !strings.Contains(markdown, "truncated: true") { + if !strings.Contains(htmlDoc, "
truncated
true
") { t.Fatal("metadata must record truncation") } } func TestExportSessionEmptySessionIsHonest(t *testing.T) { session := opencode.ExportedSession{ID: "ses_ok", Backend: "v2"} - markdown, _ := renderSessionMarkdown(session, sessionRequest(t.TempDir())) - if !strings.Contains(markdown, "messages: 0") || !strings.Contains(markdown, "No messages were recorded") { - t.Fatalf("empty session must be honest, not fabricated:\n%s", markdown) + htmlDoc, _ := renderSessionHTML(session, sessionRequest(t.TempDir())) + if !strings.Contains(htmlDoc, "
messages
0
") || !strings.Contains(htmlDoc, "No messages were recorded") { + t.Fatalf("empty session must be honest, not fabricated:\n%s", htmlDoc) } } -func TestExportSessionRefusesOverwrite(t *testing.T) { +func TestExportSessionWritesNoMarkdownAndLeavesALegacyOneAlone(t *testing.T) { dir := t.TempDir() sessionCLI(t, "ses_ok", sessionBody()) - existing := filepath.Join(dir, SessionMarkdownFile) + // A pre-existing session.md from an older run is dated evidence: the export + // neither rewrites nor removes it, and writes no new markdown. + legacy := filepath.Join(dir, SessionMarkdownFile) + if err := os.WriteFile(legacy, []byte("legacy dated evidence"), 0600); err != nil { + t.Fatal(err) + } + result, err := ExportSession(context.Background(), sessionRequest(dir)) + if err != nil { + t.Fatal(err) + } + kept, err := os.ReadFile(legacy) + if err != nil || string(kept) != "legacy dated evidence" { + t.Fatalf("legacy session.md changed: %q %v", kept, err) + } + if result.HTML != SessionHTMLFile || result.HTMLBytes == 0 || result.Diagnostic != "" { + t.Fatalf("html export wrong: %+v", result) + } + if _, err := os.Stat(filepath.Join(dir, SessionHTMLFile)); err != nil { + t.Fatalf("html not written: %v", err) + } +} + +func TestExportSessionRefusesToOverwriteTheHTMLFile(t *testing.T) { + dir := t.TempDir() + sessionCLI(t, "ses_ok", sessionBody()) + existing := filepath.Join(dir, SessionHTMLFile) if err := os.WriteFile(existing, []byte("keep me"), 0600); err != nil { t.Fatal(err) } @@ -154,13 +169,13 @@ func TestExportSessionRefusesOverwrite(t *testing.T) { } kept, err := os.ReadFile(existing) if err != nil || string(kept) != "keep me" { - t.Fatalf("existing session.md was overwritten: %q %v", kept, err) + t.Fatalf("existing session.html was overwritten: %q %v", kept, err) } - if result.MarkdownBytes != 0 || !strings.Contains(result.Diagnostic, "not overwritten") { + if result.HTMLBytes != 0 || !strings.Contains(result.Diagnostic, "not overwritten") { t.Fatalf("skip reason not recorded: %+v", result) } - if _, err := os.Stat(filepath.Join(dir, SessionHTMLFile)); err != nil { - t.Fatalf("html should still be written: %v", err) + if _, err := os.Stat(filepath.Join(dir, SessionMarkdownFile)); !os.IsNotExist(err) { + t.Fatal("a skipped html export must not write a session.md") } } @@ -199,7 +214,7 @@ func TestExportSessionRejectsInvalidIDAndMissingDirectory(t *testing.T) { func TestAssembleSessionFileNeverExceedsLimit(t *testing.T) { header := strings.Repeat("h", SessionExportFileLimit+10) body := strings.Repeat("b", 100) - got, _ := assembleSessionFile(header, body, false, markdownTruncationBanner, markdownTruncationBanner) + got, _ := assembleSessionFile(header, body, false, htmlTruncationBanner, htmlTruncationBanner) if len(got) > SessionExportFileLimit { t.Fatalf("assembled file exceeds cap: %d", len(got)) } diff --git a/internal/tui/artifacts.go b/internal/tui/artifacts.go index 2088ba26..833a6601 100644 --- a/internal/tui/artifacts.go +++ b/internal/tui/artifacts.go @@ -29,8 +29,11 @@ type artifactVisit struct { // order the run produced them: stages in first-appearance order and each // stage's visits by sequence. The display visit number is the recorded control // visit when present, else the position within the stage (mirroring the app's -// runTimeline/runArtifactGroups). Pure, O(n), and it never dedupes steps, so a -// repeated stage's visits stay distinct. +// runTimeline/runArtifactGroups). A visit carries the step's presented +// artifacts (protocol.RunStep.PresentedArtifacts), so the retired session +// markdown is never listed beside the session html, exactly as the app hides it. +// Pure, O(n), and it never dedupes steps, so a repeated stage's visits stay +// distinct. func runArtifactVisits(steps []protocol.RunStep) []artifactVisit { order := make([]string, 0) index := map[string]int{} @@ -54,7 +57,7 @@ func runArtifactVisits(steps []protocol.RunStep) []artifactVisit { if step.Control != nil && step.Control.Visit > 0 { visit = step.Control.Visit } - visits = append(visits, artifactVisit{stage: stage, visit: visit, step: step, artifacts: step.Artifacts}) + visits = append(visits, artifactVisit{stage: stage, visit: visit, step: step, artifacts: step.PresentedArtifacts()}) } } return visits diff --git a/internal/tui/artifacts_test.go b/internal/tui/artifacts_test.go index 0f3001a0..0af1343c 100644 --- a/internal/tui/artifacts_test.go +++ b/internal/tui/artifacts_test.go @@ -155,6 +155,53 @@ func TestArtifactsViewEmptyRun(t *testing.T) { } } +// A run recorded before the HTML-only change still lists session.md among its +// stored artifacts. It is dated evidence that must never be presented beside the +// session html, so the panel, its recorded count and its summary all hide it, +// exactly as the app does. +func TestArtifactsViewHidesLegacySessionMarkdown(t *testing.T) { + m := New(context.Background(), "ws://127.0.0.1:8080/connect") + m.width, m.height = 120, 24 + m.runDetail = &protocol.RunDetail{ + RunSummary: protocol.RunSummary{ID: 344, Status: "succeeded"}, + Steps: []protocol.RunStep{{Sequence: 1, Stage: "committer", Status: "completed", + Artifacts: []protocol.StageArtifact{ + {Name: "session.md", SizeBytes: 62370, ContentType: "text/markdown", URL: "/artifacts/344/1/session.md"}, + {Name: "session.html", SizeBytes: 68813, ContentType: "text/html", URL: "/artifacts/344/1/session.html"}, + }}}, + } + view := ansi.Strip(m.artifactsView(20)) + if strings.Contains(view, "session.md") { + t.Fatalf("legacy session markdown presented beside the html:\n%s", view) + } + for _, want := range []string{"session.html", "Artifacts · run #344 · 1 recorded · 1 visits"} { + if !strings.Contains(view, want) { + t.Fatalf("artifacts view missing %q:\n%s", want, view) + } + } + // The step's own stored record is untouched: only the presentation filters. + if len(m.runDetail.Steps[0].Artifacts) != 2 { + t.Fatalf("presentation mutated the stored artifact record: %d", len(m.runDetail.Steps[0].Artifacts)) + } +} + +func TestArtifactsSummaryAndNotesHideLegacySessionMarkdown(t *testing.T) { + legacy := protocol.RunStep{Status: "completed", ArtifactsSkipped: 1, + Artifacts: []protocol.StageArtifact{{Name: "session.md", URL: "/artifacts/344/1/session.md"}}} + if got, want := artifactsSummary(legacy), "Artifacts · not recorded for this visit"; got != want { + t.Fatalf("summary = %q, want %q", got, want) + } + if notes := artifactCaptureNotes(legacy); len(notes) != 0 { + t.Fatalf("legacy-only visit still produced capture notes: %v", notes) + } + presented := protocol.RunStep{Status: "completed", Artifacts: []protocol.StageArtifact{ + {Name: "session.md"}, {Name: "session.html"}, + }} + if got, want := artifactsSummary(presented), "Artifacts · 1 recorded"; got != want { + t.Fatalf("summary = %q, want %q", got, want) + } +} + func artifactsScrollFixture() (Model, []string) { m := New(context.Background(), "ws://127.0.0.1:8080/connect") m.width, m.height = 80, 14 diff --git a/internal/tui/file_changes.go b/internal/tui/file_changes.go index c0d17e54..6abd7ba5 100644 --- a/internal/tui/file_changes.go +++ b/internal/tui/file_changes.go @@ -31,13 +31,14 @@ func fileChangesSummary(step protocol.RunStep) string { } func artifactsSummary(step protocol.RunStep) string { - if len(step.Artifacts) == 0 { + artifacts := step.PresentedArtifacts() + if len(artifacts) == 0 { if step.Status == "running" { return "Artifacts · capture pending" } return "Artifacts · not recorded for this visit" } - label := fmt.Sprintf("Artifacts · %d recorded", len(step.Artifacts)) + label := fmt.Sprintf("Artifacts · %d recorded", len(artifacts)) if step.ArtifactsSkipped > 0 || step.ArtifactsTruncated > 0 { label += " · partial capture" } @@ -64,7 +65,7 @@ func HumanBytes(size int64) string { // complete. A visit with no recorded artifacts yields no notes, mirroring the // app's artifactCaptureNotes, so notes never accompany an empty-state summary. func artifactCaptureNotes(step protocol.RunStep) []string { - if len(step.Artifacts) == 0 { + if len(step.PresentedArtifacts()) == 0 { return nil } var notes []string diff --git a/web/src/app.js b/web/src/app.js index c047d53e..1af401e1 100644 --- a/web/src/app.js +++ b/web/src/app.js @@ -7,6 +7,15 @@ import { validateServerUrl, resolveArtifactUrl } from "./serverUrl.js"; const STORAGE_KEY = "pipelines.web.serverUrl.v2"; +/** + * The retired markdown session export. The server no longer writes it, but a run + * recorded before the HTML-only change still lists session.md among its stored + * artifacts. It is dated evidence the operator never sees, so every artifact + * listing hides it rather than showing it beside the session html (mirroring the + * app's presentedArtifacts). + */ +const LEGACY_SESSION_MARKDOWN_ARTIFACT = "session.md"; + /** * The page is normally served by serve.mjs, which also proxies /connect to the * Pipelines server. Defaulting to this page's own origin therefore points at @@ -369,7 +378,7 @@ function renderRunDetail() { } function renderArtifacts(step) { - const artifacts = step.artifacts ?? []; + const artifacts = (step.artifacts ?? []).filter((a) => a.name !== LEGACY_SESSION_MARKDOWN_ARTIFACT); if (!artifacts.length) return null; const wrap = h("div", { class: "artifacts" }, h("span", { class: "muted", text: "Artifacts: " })); for (const a of artifacts) {