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

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.
This commit is contained in:
2026-10-18 10:06:49 +01:00
parent 5a4cfc2e9c
commit 95362134aa
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) {