session export: write only session.html, retire the markdown export

Merge session-html-only: a stage's session is exported as one html file and the
markdown export is retired from the wire, the store, the server evidence and
every listing (app, TUI, web spike). The packaged authoring references and a
docs note travel with it.
This commit is contained in:
2026-10-18 10:07:46 +01:00
25 changed files with 666 additions and 571 deletions
@@ -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,
@@ -15,6 +15,25 @@ data class ArtifactGroup(
val artifacts: List<StageArtifact>,
)
/**
* 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<StageArtifact> =
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<RunStep>): List<ArtifactGroup> {
val groups = ArrayList<ArtifactGroup>()
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<RunStep>, 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 {
@@ -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<String> = 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.")
}
@@ -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)) {
@@ -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<MdBlock>) : 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>(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
}
@@ -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,
@@ -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 }
@@ -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))
}
}
@@ -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 = "<!doctype html><p>body</p>".toByteArray()
val load = sessionLoad(bytes)
assertTrue(load is SessionLoad.Html)
assertEquals("<!doctype html><p>body</p>", (load as SessionLoad.Html).document)
}
private fun artifact(name: String, contentType: String): StageArtifact =
@@ -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
+148
View File
@@ -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/<run>/<step>/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.
+6 -4
View File
@@ -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
+13 -7
View File
@@ -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 <id>`, v2 `opencode session export <id>`)
and writes `session.md` and `session.html` into the same `<run>/<step>` 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 `<run>/<step>` 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
+37 -2
View File
@@ -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)
}
}
+45 -13
View File
@@ -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
+22
View File
@@ -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)
}
}
-2
View File
@@ -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
+24 -17
View File
@@ -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)
}
}
+30 -38
View File
@@ -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")
}
}
+64 -222
View File
@@ -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 = "<p style=\"padding:0.5rem;border:1px solid #b00;color:#900\"><strong>TRUNCATED</strong>: this exported session is not the whole session; it was cut at the export size cap.</p>\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 = "<p style=\"padding:0.5rem;border:1px solid #b00;color:#900\"><strong>TRUNCATED</strong>: this exported session is not the whole session; it was cut at the export size cap.</p>\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
}
+58 -43
View File
@@ -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 <b>&\" 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), "<b>") {
t.Fatal("html rendered unescaped session text")
}
for _, want := range []string{"&lt;b&gt;", "&amp;", "tool: read (completed)", "tool output"} {
for _, want := range []string{"&lt;b&gt;", "&amp;", "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, "<dt>truncated</dt><dd>true</dd>") {
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, "<dt>messages</dt><dd>0</dd>") || !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))
}
+6 -3
View File
@@ -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
+47
View File
@@ -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
+4 -3
View File
@@ -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
+10 -1
View File
@@ -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) {