// Pure, DOM-free artifact derivation for the run detail, ported from the Android // client so the browser says and does exactly the same thing: // ui/ArtifactGroups.kt presentedArtifacts, runArtifactGroups, artifactsEmptyMessage // ui/Format.kt artifactsSummary, artifactCaptureNotes, humanBytes, content-type tests // ui/graph/ArtifactType.kt artifactKind, artifactKindLabel // ui/graph/Artifacts.kt the gallery's group/visit/tile vocabulary // ui/graph/ArtifactViewer.kt pagedArtifacts, viewerIndexByUrl, pagedIndex, position label // ui/graph/SessionExport.kt sessionExportFile // ui/screens/Timeline.kt the display visit number (control.visit, else position + 1) // ui/ArtifactType.kt the file-kind classification vocabulary // // Nothing here touches the DOM or imports the app: every function is pure so the // wording, ordering, counting and formatting can be unit-tested without a browser. // The tile/overlay wiring lives in app.js. import { resolveArtifactUrl } from "./serverUrl.js"; /** * 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`: it is * dated evidence that is never presented, so it is hidden from every artifact * listing rather than shown beside the session html. Mirrors * ArtifactGroups.kt LEGACY_SESSION_MARKDOWN_ARTIFACT. */ export const LEGACY_SESSION_MARKDOWN_ARTIFACT = "session.md"; /** * The "capture pending" wording shared by a running visit's summary and the * run-level empty state, so the two never spell it differently. */ export const ARTIFACT_CAPTURE_PENDING = "capture pending"; /** * What an artifact's file type is, from the app's point of view: the two media * kinds the gallery previews (image, video) and the file kinds it labels with a * type glyph. Mirrors graph/ArtifactType.kt ArtifactKind. */ export const ArtifactKind = Object.freeze({ Image: "Image", Video: "Video", Audio: "Audio", Pdf: "Pdf", Json: "Json", Archive: "Archive", Spreadsheet: "Spreadsheet", Log: "Log", Code: "Code", Document: "Document", Other: "Other", }); const ARCHIVE_EXTENSIONS = new Set([ "zip", "tar", "gz", "tgz", "bz2", "xz", "rar", "7z", "jar", "war", ]); const ARCHIVE_MIMES = new Set([ "application/zip", "application/gzip", "application/x-tar", "application/x-7z-compressed", "application/x-rar-compressed", "application/java-archive", ]); const SPREADSHEET_EXTENSIONS = new Set(["csv", "tsv", "xls", "xlsx", "ods"]); const SPREADSHEET_MIMES = new Set([ "text/csv", "text/tab-separated-values", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ]); const CODE_EXTENSIONS = new Set([ "kt", "kts", "java", "go", "py", "rb", "php", "rs", "c", "h", "cc", "cpp", "hpp", "cs", "js", "jsx", "ts", "tsx", "mjs", "cjs", "swift", "scala", "sh", "bash", "zsh", "fish", "ps1", "sql", "yaml", "yml", "toml", "ini", "xml", "gradle", "properties", "proto", ]); const CODE_MIMES = new Set([ "application/xml", "application/x-yaml", "application/javascript", "text/javascript", "text/x-python", "text/x-java-source", "text/x-kotlin", "application/x-sh", "application/x-httpd-php", "application/sql", ]); const DOCUMENT_EXTENSIONS = new Set([ "txt", "md", "markdown", "rst", "doc", "docx", "odt", "rtf", "html", "htm", ]); /** The text file kinds the browser can render in the artifact viewer. */ const MARKDOWN_EXTENSIONS = new Set(["md", "markdown", "txt"]); const DOCUMENT_MIMES = new Set([ "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/rtf", ]); const KIND_LABELS = Object.freeze({ [ArtifactKind.Image]: "Image", [ArtifactKind.Video]: "Video", [ArtifactKind.Audio]: "Audio", [ArtifactKind.Pdf]: "PDF", [ArtifactKind.Json]: "JSON", [ArtifactKind.Archive]: "Archive", [ArtifactKind.Spreadsheet]: "Spreadsheet", [ArtifactKind.Log]: "Log", [ArtifactKind.Code]: "Code", [ArtifactKind.Document]: "Document", [ArtifactKind.Other]: "File", }); /** Whether an artifact's content type is an image the gallery can preview. */ export function isImageContentType(contentType) { return String(contentType ?? "").startsWith("image/"); } /** * Whether an artifact's content type is a video. Videos are shown in the gallery * as a poster-style tile with a play marker; they are never decoded inline and * never autoplay. */ export function isVideoContentType(contentType) { return String(contentType ?? "").startsWith("video/"); } /** * The artifacts of one visit as the operator sees them: the recorded files with * the retired markdown session export filtered out. Every artifact listing * derives from this one function, so a visit never shows a session markdown * beside the session html and the recorded counts can never disagree with the * tiles. Duplicate names are kept, not deduped: an artifact's identity is its * recorded url, not its name. Mirrors ArtifactGroups.kt presentedArtifacts. */ export function presentedArtifacts(step) { return (step?.artifacts ?? []).filter( (artifact) => artifact?.name !== LEGACY_SESSION_MARKDOWN_ARTIFACT, ); } /** * The files the turn protocol itself writes for every visit. They are audit * evidence, not stage output: the artifact surfaces lead with what the stage * actually produced, and these live behind Audit & debug. Names are the exact * server-recorded ones. */ export const SYSTEM_ARTIFACT_NAMES = Object.freeze([ "input.md", "memory.md", "output.md", "session.html", ]); /** True for a turn-owned file (input/memory/output/session). Pure. */ export function isSystemArtifact(artifact) { return SYSTEM_ARTIFACT_NAMES.includes(String(artifact?.name ?? "")); } /** A visit's stage-produced artifacts: everything except the system files. */ export function stageArtifacts(step) { const repairs = new Set((step?.session_export_repairs ?? []).map((entry) => entry?.html).filter(Boolean)); return presentedArtifacts(step).filter((artifact) => !isSystemArtifact(artifact) && !repairs.has(artifact?.name)); } /** A visit's system files, newest-listing order preserved. */ export function systemArtifacts(step) { const repairs = new Set((step?.session_export_repairs ?? []).map((entry) => entry?.html).filter(Boolean)); return presentedArtifacts(step).filter((artifact) => isSystemArtifact(artifact) || repairs.has(artifact?.name)); } /** How many files the capture excluded for `step` (absent means none). */ export function artifactsSkipped(step) { return Number(step?.artifacts_skipped ?? 0) || 0; } /** How many files the capture omitted for `step` (absent means none). */ export function artifactsTruncated(step) { return Number(step?.artifacts_truncated ?? 0) || 0; } /** The extension of `name` (lowercased), or "" when it carries none. */ function extensionOf(name) { const text = String(name ?? ""); const dot = text.lastIndexOf("."); return dot === -1 ? "" : text.slice(dot + 1).toLowerCase(); } /** * The gallery kind of an artifact from its `contentType` (server-sniffed, may * carry parameters) and its `name` (the extension is the fallback when the sniff * is a generic text/plain or application/octet-stream). Image and video come * straight from the content type; the rest match the normalised mime first, then * the name's extension. Pure and total. Mirrors graph/ArtifactType.kt artifactKind. */ export function artifactKind(contentType, name) { if (isImageContentType(contentType)) return ArtifactKind.Image; if (isVideoContentType(contentType)) return ArtifactKind.Video; const ct = String(contentType ?? ""); const mime = ct.split(";")[0].trim().toLowerCase(); const ext = extensionOf(name); if (mime.startsWith("audio/")) return ArtifactKind.Audio; if (mime === "application/pdf" || ext === "pdf") return ArtifactKind.Pdf; if (mime.includes("json") || ext === "json") return ArtifactKind.Json; if (ARCHIVE_MIMES.has(mime) || ARCHIVE_EXTENSIONS.has(ext)) return ArtifactKind.Archive; if (SPREADSHEET_MIMES.has(mime) || SPREADSHEET_EXTENSIONS.has(ext)) return ArtifactKind.Spreadsheet; if (ext === "log") return ArtifactKind.Log; if (mime === "text/html") return ArtifactKind.Document; if (CODE_MIMES.has(mime) || CODE_EXTENSIONS.has(ext)) return ArtifactKind.Code; if (mime.startsWith("text/") || DOCUMENT_MIMES.has(mime) || DOCUMENT_EXTENSIONS.has(ext)) { return ArtifactKind.Document; } return ArtifactKind.Other; } /** * The word that names `kind` where the gallery shows its glyph but must also say * the type in prose (a screen reader cannot read an icon). The same * classification `artifactKind` draws from, so glyph and word never disagree. */ export function artifactKindLabel(kind) { return KIND_LABELS[kind] ?? "File"; } /** * Whether an artifact is text the reader can render as markdown in the viewer: * `text/markdown` or `text/plain` (parameters ignored), or a `.md`, `.markdown` * or `.txt` name. The viewer uses the page's existing markdown renderer, so these * are the text files it is allowed to fetch and draw. Pure and total, mirroring * the content-type tests above. */ export function isMarkdownArtifact(contentType, name) { const mime = String(contentType ?? "").split(";")[0].trim().toLowerCase(); if (mime === "text/markdown" || mime === "text/plain") return true; return MARKDOWN_EXTENSIONS.has(extensionOf(name)); } /** * Whether an artifact opens inside the full-screen viewer: the two media kinds * the gallery already previewed, plus the markdown/text documents it now renders * itself. The kind gate keeps a `text/plain` `.log`, `.py` or `.csv` an external * file: those are evidence, not prose. This is the one predicate the grid tiles, * paging and the viewer share, so they cannot disagree about the list. */ export function isViewerArtifact(contentType, name) { if (isImageContentType(contentType) || isVideoContentType(contentType)) return true; return artifactKind(contentType, name) === ArtifactKind.Document && isMarkdownArtifact(contentType, name); } /** * Human-readable byte size, matching Android Format.kt humanBytes (and the TUI): * whole bytes under 1 KiB, otherwise one decimal with a binary unit * (KiB/MiB/GiB/TiB/PiB/EiB). */ export function humanBytes(size) { const value = Math.trunc(Number(size) || 0); const unit = 1024; if (value < unit) return `${value} B`; let div = unit; let exp = 0; let scaled = Math.trunc(value / unit); while (scaled >= unit) { div *= unit; exp++; scaled = Math.trunc(scaled / unit); } return `${(value / div).toFixed(1)} ${"KMGTPE"[exp]}iB`; } /** * The display visit number for a step at `index` within its stage's ordered * visits: the recorded control visit when positive, otherwise the position * within the stage. Mirrors Timeline.kt (`control.visit > 0 ? visit : index + 1`). */ export function displayVisit(step, index) { const visit = step?.control?.visit; return Number(visit) > 0 ? Number(visit) : index + 1; } /** True for a shared public file's recorded name (`public/...`). */ function isPublicName(name) { return String(name ?? "").startsWith("public/"); } /** * A visit's stage artifacts, with each shared public file attributed to the first * visit that recorded it. The server records the whole public directory on every * model visit so a resume can rebuild each turn's file list; the artifact surface * must not repeat every shared file once per later stage. */ export function visitArtifacts(step, runSteps) { const all = stageArtifacts(step); if (!step || !runSteps?.length) return all; const seen = new Set(); const ordered = [...runSteps].sort((a, b) => (a?.sequence ?? 0) - (b?.sequence ?? 0)); for (const candidate of ordered) { if (candidate === step || candidate?.sequence === step.sequence) break; for (const artifact of stageArtifacts(candidate)) { if (isPublicName(artifact?.name)) seen.add(artifact.name); } } return all.filter((artifact) => !isPublicName(artifact?.name) || !seen.has(artifact.name)); } /** * Groups a run's artifacts by stage and visit, attributing each shared public file * to the visit that first recorded it. Stages keep first-appearance * order and each stage's visits are ordered by sequence, with the display visit * number above. Only visits that recorded at least one presented artifact * produce a group, so an empty capture never yields an empty group and an * artifact-less run yields an empty list. Mirrors ArtifactGroups.kt * runArtifactGroups + Timeline.kt runTimeline. */ export function artifactGroups(steps) { const list = steps ?? []; if (list.length === 0) return []; // groupBy(stage) keeps first-appearance order (a Map preserves insertion // order); each stage's visits are then ordered by sequence. const orderedSteps = [...list].sort((a, b) => (a?.sequence ?? 0) - (b?.sequence ?? 0)); const attributed = new Map(); const seenPublic = new Set(); for (const step of orderedSteps) { const artifacts = stageArtifacts(step).filter((artifact) => { if (!isPublicName(artifact?.name)) return true; if (seenPublic.has(artifact.name)) return false; seenPublic.add(artifact.name); return true; }); attributed.set(step, artifacts); } const visitsByStage = new Map(); for (const step of list) { const stage = step?.stage ?? ""; if (!visitsByStage.has(stage)) visitsByStage.set(stage, []); visitsByStage.get(stage).push(step); } const groups = []; for (const [stageKey, visits] of visitsByStage) { const ordered = [...visits].sort((a, b) => (a?.sequence ?? 0) - (b?.sequence ?? 0)); ordered.forEach((step, index) => { const artifacts = attributed.get(step) ?? []; if (artifacts.length === 0) return; groups.push({ stageKey, visit: displayVisit(step, index), artifacts }); }); } return groups; } /** * The explicit message shown where the run's artifacts gallery would be when * there are none: while the run is executing it uses the same "capture pending" * wording as a running visit, otherwise it says plainly that nothing was * recorded. Mirrors ArtifactGroups.kt artifactsEmptyMessage. */ export function artifactsEmptyMessage(executing) { return executing ? `Artifacts · ${ARTIFACT_CAPTURE_PENDING}` : "No artifacts recorded for this run."; } /** * The run summary's Artifacts section header: the title, how many artifacts the * run recorded (the title takes its singular form for exactly one) and * "partial capture" when any visit excluded or omitted files. It reuses the * shared empty message, so a run with nothing recorded still gets a * self-describing header. The recorded count is exactly the number of tiles * `artifactGroups` yields. Mirrors ArtifactGroups.kt runArtifactsHeader. */ export function artifactsHeader(steps, executing) { const list = steps ?? []; const recorded = artifactGroups(list).reduce((sum, group) => sum + group.artifacts.length, 0); if (recorded === 0) return artifactsEmptyMessage(executing); const partial = list.some((step) => artifactsSkipped(step) > 0 || artifactsTruncated(step) > 0); let label = `${recorded === 1 ? "Artifact" : "Artifacts"} · ${recorded} recorded`; if (partial) label += " · partial capture"; return label; } /** * The per-visit artifacts summary label: "capture pending" while the visit runs, * "not recorded for this visit" for a finished visit with no artifacts, * otherwise the recorded count plus " · partial capture" when files were * excluded or omitted. Mirrors Format.kt artifactsSummary. */ export function artifactsSummary(step, count = null) { const recorded = count ?? stageArtifacts(step).length; if (recorded === 0) { const state = step?.status === "running" ? ARTIFACT_CAPTURE_PENDING : "not recorded for this visit"; return `Artifacts · ${state}`; } let label = `Artifacts · ${recorded} recorded`; if (artifactsSkipped(step) > 0 || artifactsTruncated(step) > 0) label += " · partial capture"; return label; } /** * The partial-capture notes, one line per non-zero count and nothing when the * capture was complete. An empty artifact list yields no notes at all, so the * notes never accompany the empty-state summary. Mirrors Format.kt * artifactCaptureNotes. */ export function artifactCaptureNotes(step) { const notes = []; if (presentedArtifacts(step).length === 0) return notes; const skipped = artifactsSkipped(step); const truncated = artifactsTruncated(step); if (skipped > 0) notes.push(`${skipped} files excluded from artifact capture.`); if (truncated > 0) notes.push(`${truncated} files omitted by artifact capture limits.`); return notes; } /** * The artifacts `groups` hold that the full-screen viewer can page through, in * the exact order the gallery draws them (group by group, each group's images, * videos and markdown/text documents in recorded order): the neighbours a * swipe/keyboard step visits, so the viewer walks the same list the grid showed. * Other artifacts open externally and are not part of it. Mirrors * ArtifactViewer.kt pagedArtifacts, extended for markdown-first stage turns. */ export function pagedArtifacts(groups) { const viewable = []; for (const group of groups ?? []) { for (const artifact of group?.artifacts ?? []) { if (isViewerArtifact(artifact?.content_type, artifact?.name)) viewable.push(artifact); } } return viewable; } /** * Each viewer-selectable artifact's url mapped to its position in * `pagedArtifacts`, the same ordered list the viewer pages through. The grid's * tiles resolve their viewer index here, so tile and viewer derive from one * source and cannot drift. The first occurrence of a url wins. Mirrors * ArtifactViewer.kt viewerIndexByUrl. */ export function viewerIndexByUrl(groups) { const indices = new Map(); pagedArtifacts(groups).forEach((artifact, index) => { if (!indices.has(artifact.url)) indices.set(artifact.url, index); }); return indices; } /** * The index paging from `current` by `delta` within a list of `count`, clamped * at both ends so a page never wraps (and an empty list is index 0). The one * paging rule the viewer's buttons share. Mirrors ArtifactViewer.kt pagedIndex. */ export function pagedIndex(current, delta, count) { if (count <= 0) return 0; return Math.min(Math.max(current + delta, 0), count - 1); } /** The viewer's position label, e.g. `2 of 5 · image/png`. Mirrors ArtifactViewer.kt. */ export function artifactViewerPositionLabel(index, count, contentType) { const type = String(contentType ?? "").split(";")[0].trim() || "artifact"; return `${index + 1} of ${count} · ${type}`; } /** * The html session export `step` recorded, matched to the visit's recorded * artifacts by exact name, or null when the visit has no export to open. A visit * that recorded no export, whose export name is blank, or whose file is missing * from a truncated listing yields null. Mirrors SessionExport.kt sessionExportFile. */ export function effectiveSessionExport(step) { const recorded = step?.session_export ?? null; const id = String(step?.session_id || recorded?.session_id || ""); const original = recorded?.session_id && id && recorded.session_id !== id ? null : recorded; const repairs = [...(step?.session_export_repairs ?? [])].reverse() .filter((entry) => id !== "" && entry?.session_id === id && (!original?.backend || entry.backend === original.backend) && (!original?.directory || entry.directory === original.directory)); const hasFile = (entry) => Boolean(entry?.html) && (step?.artifacts ?? []).some((file) => file?.name === entry.html && file.size_bytes > 0 && (!(entry.html_bytes > 0) || file.size_bytes === entry.html_bytes)); // A failed later attempt must not hide an earlier, verified full repair. const isComplete = (entry) => entry?.status === "complete" && entry.messages > 0 && entry.html_bytes > 0 && !entry.truncated && !entry.diagnostic && hasFile(entry); return repairs.find(isComplete) ?? (isComplete(original) ? original : null) ?? repairs.find(hasFile) ?? (hasFile(original) ? original : null) ?? repairs[0] ?? original ?? null; } export function sessionExportArtifact(step) { const evidence = effectiveSessionExport(step); const html = evidence?.html; if (typeof html !== "string" || html.trim() === "") return null; return (step?.artifacts ?? []).find((artifact) => artifact?.name === html && (!(evidence.html_bytes > 0) || artifact.size_bytes === evidence.html_bytes)) ?? null; } /** A recorded ID and an exported document are different facts. Never call a * recorded session "not recorded" just because its export is missing. */ export function sessionCaptureState(step) { const evidence = effectiveSessionExport(step); const sessionId = String(step?.session_id || evidence?.session_id || ""); const artifact = sessionExportArtifact(step); if (artifact) return { sessionId, evidence, artifact, message: "" }; if (sessionId) { const recovery = step?.session_export_recovery; const status = recovery?.status === "pending" || recovery?.status === "running" ? "pending recovery" : evidence?.status === "complete" ? "not available in the artifact inventory" : evidence?.status || "not yet available"; return { sessionId, evidence, artifact: null, message: `Session ${sessionId} is recorded. Its export is ${status}.${evidence?.diagnostic ? ` ${evidence.diagnostic}` : ""}` }; } const model = Boolean(step?.model || step?.provider); const skipped=step?.status==="skipped" || step?.outcome==="skipped"; const stopped=["canceled","interrupted"].includes(step?.status); return { sessionId, evidence, artifact: null, message: skipped ? "This visit was skipped; no harness session was started." : stopped ? "The stage stopped before a harness session was recorded." : model ? step?.status === "running" ? "The stage session is being created." : step?.status === "failed" ? `The stage did not create a harness session.${step?.diagnostic ? ` ${step.diagnostic}` : ""}` : "Runtime error: this model stage has no recorded session identity." : "This visit has no harness session." }; } /** * The absolute url a gallery artifact can be opened at, or null when it cannot * be resolved against the configured server (blank or invalid). The one place a * gallery artifact url is resolved, so tiles and the viewer never disagree. * Re-exported here so callers derive tiles from this module alone. */ export function resolvedArtifactUrl(artifact, configuredServerUrl) { return resolveArtifactUrl(configuredServerUrl, artifact?.url); }