Merge branch 'main' into chat-hide-notice-timeout

This commit is contained in:
2026-10-18 23:29:59 +01:00
69 changed files with 2662 additions and 1098 deletions
+32 -38
View File
@@ -1,44 +1,38 @@
# Pipelines maintenance
# Pipelines project
## Consent (hard rule)
## Ownership and execution
The operator owns this system. No change to it happens without their explicit consent in the
current conversation: new pipelines or versions, definition and stage-prompt edits,
orchestration scripts, briefs and the conventions they carry, the packaged skill and templates,
deploys, installs and deletions. Read-only investigation and reporting need no consent. Ask
first and name exactly what would change; a request for a fix is not consent for a particular
mechanism.
The user owns the project. The manager is responsible for finishing authorized work,
not merely assigning it. Use pipelines, direct work or delegation as appropriate.
The manager may implement, review, fix tests, resolve conflicts, merge and deliver.
When a pipeline blocks progress, diagnose it and take over directly when useful.
Do not create another recovery workflow just to complete an existing item.
When a change alters user-facing behavior, or you learn a confirmed runtime
limitation, record the stale documentation instead of editing the shared document in
the same change: leave a per-item note at `docs/notes/<slug>.md` naming what changed and
which packaged OpenCode skill reference in `internal/author/skill/references/`, README
or topic doc is now stale and what should change there. The manual-only `docs-fold`
pipeline folds `docs/notes/` into the shared docs and references; an item never edits a
shared document itself. Keep `SKILL.md` a concise,
task-directed index: preserve ask-first authoring and never preload every reference.
Separate current capabilities, dated verification evidence, deployment state and
unimplemented ideas. Do not turn mocked or structural checks into live claims.
## Small changes, parallel progress
For new references, update `internal/author/install.go`'s managed file inventory.
Run the author package tests: they check embedding, reference links, installation,
upgrades and protection of user modifications. Never hand-edit an installed copy
as the source of truth; refresh it with the current-source `pipelines skill install`
only when installation is requested. Do not deploy runtime changes merely because
the skill is updated. Keep the shared docs and packaged references consistent through
the single `docs-fold` writer rather than editing them per item: leave a
`docs/notes/<slug>.md` note.
Split features into small independently testable changes. Keep stage roles and
handoffs short. Run independent items concurrently in separate worktrees; small
overlapping edits are normal merge work, not an automatic reason to serialize.
Use Luna for pipeline stages unless the user requests otherwise.
## Maintenance workflow
## Preserve and verify
Top-level agents advance work through the `pipelines` CLI; **the agent is the brain**
and there is no orchestration script, driver, polling loop or lane machinery, and none
may be written. Choose the pipeline by the area the work is in — `Android`, `TUI`,
`Server`, `Generic`, `Plan and land`, `UI sweep`, `Probe` — each reading the project's
own map (`android/AGENTS.md`, `internal/tui/AGENTS.md`, `internal/server/AGENTS.md`)
for how that technology is built, tested, run and captured. Inspect the retained
plan/implement/review outputs and diffs, execute the checks independently, and iterate
on concrete failures rather than trusting stage summaries. An executing stage performs
its own role directly and never recursively launches a workflow. If a pipeline is
unavailable, ask instead of silently bypassing it. Never hardcode a disposable server
URL as a project default; the configured endpoint is authoritative.
Read the relevant area map for build and test commands. Preserve existing branches,
commits and uncommitted work. Never reset, discard or delete unrelated work.
Resolve conflicts by preserving compatible intent; inspect the actual diff.
Run focused tests while editing and relevant integration tests before landing.
Check branch ancestry after landing, not before a server delivery gate can run.
A failed item does not stop unrelated items. Keep unfinished work referenced.
## Finish and report
Track code, checks, landing, deployment and device installation separately.
Show changed paths and actual diff evidence; flag missing captures rather than
claiming no changes. Report failures and decisions concisely.
Update relevant rules, skills and documentation when they are the requested task;
ordinary feature work can leave a focused docs/notes entry instead.
Use the current-source skill installer to refresh managed installed skills.
Do not restart a shared service over active work. Do not use the personal Fold
for tests; it is a delivery device. Follow the Android map's target leases.
Ask only for genuinely missing decisions or destructive/out-of-scope actions,
not routine steps already covered by the user's request.
@@ -13,6 +13,8 @@ import net.awan.pipelines.data.protocol.ChatPromptRequest
import net.awan.pipelines.data.protocol.ChatProtocol
import net.awan.pipelines.data.protocol.ChatQuery
import net.awan.pipelines.data.protocol.ChatSession
import net.awan.pipelines.data.protocol.ChatShellOutputPage
import net.awan.pipelines.data.protocol.ChatShell
import net.awan.pipelines.data.protocol.Message
import net.awan.pipelines.data.protocol.Graph
import net.awan.pipelines.data.protocol.PipelineDetail
@@ -312,6 +314,22 @@ class PipelinesRepository(
return response.chatHistory ?: ChatHistoryPage(messages = response.chatMessages ?: emptyList())
}
/** Reads one bounded page from a verified, currently observable shell. */
suspend fun chatShellOutput(sessionId: String, shellId: String, cursor: Long = 0, limit: Int = ChatProtocol.SHELL_OUTPUT_LIMIT): ChatShellOutputPage {
if (sessionId.isBlank() || shellId.isBlank()) throw ProtocolException("Select a shell first.")
if (cursor < 0 || limit <= 0 || limit > ChatProtocol.SHELL_OUTPUT_LIMIT) {
throw ProtocolException("Shell output bounds are invalid.")
}
return client.call(ChatProtocol.shellOutputRequest(sessionId, shellId, cursor, limit)).chatShellOutput
?: throw ProtocolException("The server returned no shell output page.")
}
/** Lists currently observed shells owned by this operator chat session. */
suspend fun chatShells(sessionId: String): List<ChatShell> {
if (sessionId.isBlank()) throw ProtocolException("Select a chat session first.")
return client.call(ChatProtocol.shellsRequest(sessionId)).chatShells ?: emptyList()
}
/**
* Attaches this connection to [sessionId]'s shared live stream, so it sees
* every frame any client's turn produces — the other devices' prompts and the
@@ -2,6 +2,8 @@ package net.awan.pipelines.data.protocol
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.EncodeDefault
import kotlinx.serialization.ExperimentalSerializationApi
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
@@ -201,6 +203,27 @@ data class ChatShell(
val exit: Int? = null,
)
@Serializable
@OptIn(ExperimentalSerializationApi::class)
data class ChatShellOutputQuery(
@SerialName("session_id") val sessionId: String = "",
@SerialName("shell_id") val shellId: String = "",
@EncodeDefault(EncodeDefault.Mode.ALWAYS)
val cursor: Long = 0,
@EncodeDefault(EncodeDefault.Mode.ALWAYS)
val limit: Int = ChatProtocol.SHELL_OUTPUT_LIMIT,
)
@Serializable
data class ChatShellOutputPage(
val shell: ChatShell = ChatShell(),
val output: String = "",
val cursor: Long = 0,
val size: Long = 0,
val truncated: Boolean = false,
val unavailable: Boolean = false,
)
@Serializable
data class ChatStep(
val status: String = "",
@@ -282,6 +305,7 @@ object ChatProtocol {
const val SHELL_RUNNING = "running"
const val SHELL_EXITED = "exited"
const val SHELL_OUTPUT_LIMIT = 64 * 1024
/**
* A prompt another client sent, echoed live to this client so it appears in
@@ -359,6 +383,15 @@ object ChatProtocol {
fun interruptRequest(sessionId: String): Message =
Message(type = Protocol.CHAT_INTERRUPT, chatQuery = ChatQuery(sessionId = sessionId))
fun shellOutputRequest(sessionId: String, shellId: String, cursor: Long = 0, limit: Int = SHELL_OUTPUT_LIMIT): Message =
Message(
type = Protocol.CHAT_SHELL_OUTPUT,
chatShellOutputQuery = ChatShellOutputQuery(sessionId, shellId, cursor, limit),
)
fun shellsRequest(sessionId: String): Message =
Message(type = Protocol.CHAT_SHELLS, chatQuery = ChatQuery(sessionId = sessionId))
/**
* The `chat_close` frame that finishes [sessionId]: the server stops any
* running turn (through the same interrupt) and records the session closed on
@@ -79,6 +79,8 @@ object Protocol {
// The operator's directory choices for a new chat (home first, then the
// directories of previous operator sessions, most recently used first).
const val CHAT_DIRECTORIES = "chat_directories"
const val CHAT_SHELLS = "chat_shells"
const val CHAT_SHELL_OUTPUT = "chat_shell_output"
// Server-pushed frames with no matching request.
const val CHAT_EVENT = "chat_event"
const val CHAT_PERMISSION = "chat_permission"
@@ -712,4 +714,7 @@ data class Message(
// close/reopen requests themselves ride on chat_query like chat_interrupt.
@SerialName("chat_close") val chatClose: ChatCloseResult? = null,
@SerialName("chat_directories") val chatDirectories: List<String>? = null,
@SerialName("chat_shell_output_query") val chatShellOutputQuery: ChatShellOutputQuery? = null,
@SerialName("chat_shells") val chatShells: List<ChatShell>? = null,
@SerialName("chat_shell_output") val chatShellOutput: ChatShellOutputPage? = null,
)
@@ -34,7 +34,6 @@ import net.awan.pipelines.data.protocol.Protocol
import net.awan.pipelines.data.protocol.RunDetail
import net.awan.pipelines.data.protocol.RunEventFrame
import net.awan.pipelines.data.protocol.SearchResponse
import net.awan.pipelines.data.protocol.SessionEvidence
import net.awan.pipelines.data.protocol.Template
import net.awan.pipelines.data.transport.ConnectionState
import net.awan.pipelines.data.transport.ServerUrl
@@ -119,9 +118,6 @@ class AppViewModel(
private val _runDetail = MutableStateFlow(LoadState<RunDetail>())
val runDetail: StateFlow<LoadState<RunDetail>> = _runDetail.asStateFlow()
private val _evidence = MutableStateFlow(LoadState<List<SessionEvidence>>())
val evidence: StateFlow<LoadState<List<SessionEvidence>>> = _evidence.asStateFlow()
/**
* Whether the live run stream is delivering pushes. Shown as the small
* "live"/"reconnecting" badge in the runs list and the run detail so a view
@@ -794,8 +790,6 @@ class AppViewModel(
}
}
fun loadEvidence(id: Long) = load(_evidence) { repository.getRunEvidence(id) }
/** Fetches an artifact's bytes for an inline image preview; null on failure. */
suspend fun fetchArtifactBytes(url: String): ByteArray? =
runCatching { repository.fetchArtifactBytes(url) }.getOrNull()
@@ -865,14 +859,6 @@ class AppViewModel(
}
}
/**
* Drops any previously loaded evidence so a different run never shows the
* previous run's records. Evidence is then fetched on demand, never polled.
*/
fun resetEvidence() {
_evidence.value = LoadState()
}
/**
* Loads a run on demand (opening it, or after a manual cancel/retry).
* [silent] keeps the current content without a loading flash while it is
@@ -304,7 +304,9 @@ fun searchTarget(hit: SearchResult): SearchTarget? = when {
fun searchFieldSection(field: String): Int = when (field) {
"input" -> 2
"output" -> 3
"evidence", "transcript" -> 4
// Evidence was a retired run-detail tab. Keep old search hits safe by
// opening Summary rather than accidentally selecting Timeline.
"evidence", "transcript" -> 0
else -> 0
}
@@ -20,8 +20,9 @@ const val MAX_PANE_DEPTH = 3
/**
* The saved pane-stack selection: which pane is rightmost, which item (0 = none),
* its pipeline/run version, which detail section (page) is showing, which
* stage/visit the stage pane is on and, when a stage section is open, its key.
* its pipeline/run version, which detail section (page) is showing and its
* stable tab key, which stage/visit the stage pane is on and, when a stage
* section is open, its key.
* Every field is a primitive, so the state round-trips through a Bundle cheaply
* and survives rotation, configuration change and process death.
*
@@ -36,6 +37,7 @@ data class PaneSelection(
val stageKey: String? = null,
val stageVisit: Int = 0,
val sectionKey: String? = null,
val detailTabKey: String? = null,
) {
/** How many panes are stacked: 0 list, 1 detail, 2 stage, 3 section. */
val depth: Int
@@ -105,6 +107,7 @@ internal fun encodePaneSelection(selection: PaneSelection): List<Any> = listOf(
selection.stageKey ?: "",
selection.stageVisit,
selection.sectionKey ?: "",
selection.detailTabKey ?: "",
)
/** Restores a [PaneSelection] encoded by [encodePaneSelection]. */
@@ -116,6 +119,7 @@ internal fun decodePaneSelection(encoded: List<Any>): PaneSelection = PaneSelect
stageKey = (encoded[4] as String).takeIf { it.isNotEmpty() },
stageVisit = encoded[5] as Int,
sectionKey = (encoded[6] as String).takeIf { it.isNotEmpty() },
detailTabKey = encoded.getOrNull(7)?.let { it as String }?.takeIf { it.isNotEmpty() },
)
/**
@@ -89,6 +89,13 @@ internal val destinations = listOf(
TopDestination("settings", "Settings", Icons.Default.Settings),
)
/** The home route remains beneath top-level navigation, so Back returns to Runs. */
internal const val HOME_ROUTE = "runs"
/** Returning to home clears the accumulated top-level stack; other destinations keep it. */
internal fun topLevelPopUpToHomeInclusive(destination: String): Boolean =
destination == HOME_ROUTE
/**
* Whether [route] is the current destination. Detail panes are no longer
* separate routes (they are saved state inside a destination), so this is a
@@ -210,14 +217,14 @@ fun PipelinesApp(
is SearchTarget.Pipeline -> {
pipelineSelection = PaneSelection(MasterPane.Detail, target.pipelineId, target.version)
navController.navigate("pipelines") {
popUpTo("pipelines") { inclusive = false }
popUpTo(HOME_ROUTE) { inclusive = false }
launchSingleTop = true
}
}
is SearchTarget.Run -> {
runSelection = PaneSelection(MasterPane.Detail, target.runId)
runSearchNav = target.takeIf { it.sequence > 0 }
navController.navigate("runs") { launchSingleTop = true }
navController.navigate(HOME_ROUTE) { launchSingleTop = true }
}
null -> Unit
}
@@ -231,7 +238,7 @@ fun PipelinesApp(
val openRunFromAttention: (Long) -> Unit = { runId ->
vm.arrivedAtRun(runId)
runSelection = PaneSelection(pane = MasterPane.Detail, itemId = runId)
navController.navigate("runs") { launchSingleTop = true }
navController.navigate(HOME_ROUTE) { launchSingleTop = true }
}
// A deep link (or the notification's click action) opens its run once. The
@@ -274,7 +281,9 @@ fun PipelinesApp(
val onNavigate: (TopDestination) -> Unit = { destination ->
if (currentRoute != destination.route) {
navController.navigate(destination.route) {
popUpTo("pipelines") { inclusive = destination.route == "pipelines" }
popUpTo(HOME_ROUTE) {
inclusive = topLevelPopUpToHomeInclusive(destination.route)
}
launchSingleTop = true
}
}
@@ -317,7 +326,7 @@ fun PipelinesApp(
)
NavHost(
navController = navController,
startDestination = "pipelines",
startDestination = HOME_ROUTE,
// While the banner is visible it owns the status-bar inset, so
// the inner app bars below must not apply it a second time.
modifier = Modifier
@@ -344,11 +353,11 @@ fun PipelinesApp(
pane = MasterPane.Detail,
itemId = runId,
)
navController.navigate("runs") { launchSingleTop = true }
navController.navigate(HOME_ROUTE) { launchSingleTop = true }
},
)
}
composable("runs") {
composable(HOME_ROUTE) {
RunsDestination(
vm = vm,
wide = wide,
@@ -11,8 +11,8 @@ import androidx.compose.ui.Modifier
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import kotlinx.coroutines.flow.collect
import net.awan.pipelines.ui.components.SlidingPaneStack
import net.awan.pipelines.ui.components.clampTabIndex
import net.awan.pipelines.ui.components.rememberPaneContent
import net.awan.pipelines.ui.components.runDetailTabIndex
import net.awan.pipelines.ui.components.runDetailTabs
import net.awan.pipelines.ui.graph.RunStagePane
import net.awan.pipelines.ui.screens.RunDetailScreen
@@ -91,8 +91,15 @@ internal fun RunsDestination(
vm = vm,
runId = itemId,
onBack = onBack,
selectedSection = clampTabIndex(sectionIndex, runDetailTabs.size),
onSelectSection = { onSelectionChange(selection.copy(sectionIndex = it)) },
selectedSection = runDetailTabIndex(selection.detailTabKey, sectionIndex),
onSelectSection = { index ->
onSelectionChange(
selection.copy(
sectionIndex = index,
detailTabKey = runDetailTabs[index].key,
),
)
},
modifier = paneModifier,
wide = wide,
onOpenStage = { key, visit ->
@@ -16,7 +16,6 @@ import androidx.compose.foundation.layout.widthIn
import androidx.compose.foundation.selection.selectable
import androidx.compose.foundation.selection.selectableGroup
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.FactCheck
import androidx.compose.material.icons.automirrored.filled.Input
import androidx.compose.material.icons.automirrored.filled.List
import androidx.compose.material.icons.automirrored.filled.Send
@@ -63,10 +62,25 @@ val runDetailTabs: List<DetailTab> = listOf(
DetailTab("graph", "Graph", Icons.Default.Hub),
DetailTab("input", "Input", Icons.AutoMirrored.Filled.Input),
DetailTab("output", "Output", Icons.AutoMirrored.Filled.Send),
DetailTab("evidence", "Evidence", Icons.AutoMirrored.Filled.FactCheck),
DetailTab("steps", "Timeline", Icons.AutoMirrored.Filled.List),
)
/**
* Resolves a run-detail selection from its stable [key], falling back to its
* index when it was produced by this version of the app. Saved selections from
* before Evidence was removed use the old index order: Evidence (4) deliberately
* returns to Summary and Timeline (5) moves to its new last index.
*/
fun runDetailTabIndex(key: String?, index: Int): Int {
val keyedIndex = key?.let { selectedKey -> runDetailTabs.indexOfFirst { it.key == selectedKey } }
if (keyedIndex != null && keyedIndex >= 0) return keyedIndex
return when (index) {
4 -> 0
5 -> runDetailTabs.lastIndex
else -> clampTabIndex(index, runDetailTabs.size)
}
}
/** Pipeline-detail tabs, Summary first (the version list lives inside it). */
val pipelineDetailTabs: List<DetailTab> = listOf(
DetailTab("summary", "Summary", Icons.Default.Info),
@@ -40,7 +40,6 @@ import net.awan.pipelines.ui.components.LoadPhase
import net.awan.pipelines.ui.components.LoadingState
import net.awan.pipelines.ui.components.PaneIdentity
import net.awan.pipelines.ui.components.StateCrossfade
import net.awan.pipelines.ui.components.clampTabIndex
import net.awan.pipelines.ui.components.detailLoadPhase
import net.awan.pipelines.ui.components.paneSafeArea
import net.awan.pipelines.ui.components.rememberPaneContent
@@ -72,7 +71,6 @@ fun RunDetailScreen(
) {
val state by vm.runDetail.collectAsStateWithLifecycle()
val runsState by vm.runs.collectAsStateWithLifecycle()
val evidenceState by vm.evidence.collectAsStateWithLifecycle()
val configuredServerUrl by vm.configuredServerUrl.collectAsStateWithLifecycle()
val runStream by vm.runStream.collectAsStateWithLifecycle()
var confirmCancel by remember { mutableStateOf(false) }
@@ -88,11 +86,7 @@ fun RunDetailScreen(
// Reaching a run clears its notification, whichever path opened it (the
// notification's own tap, the attention list, the runs list or a search).
vm.arrivedAtRun(runId)
// Scope evidence to this run: drop the previous run's records, then fetch
// this run's evidence once (on demand; live pushes carry no evidence).
vm.resetEvidence()
vm.loadRun(runId)
vm.loadEvidence(runId)
}
val run = state.data?.takeIf { it.id == runId }
@@ -115,7 +109,7 @@ fun RunDetailScreen(
val candidateArtifacts = remember(artifactGroups) {
artifactGroups.flatMap { it.artifacts }.distinctBy { it.url }
}
val summaryTab = runDetailTabs.getOrNull(clampTabIndex(selectedSection, runDetailTabs.size))?.key
val summaryTab = runDetailTabs.getOrNull(selectedSection)?.key
// A covered pane shows its compact identity only; the tab rail, timeline and
// graphs must never be drawn squeezed into the peek strip. The run belongs to
@@ -268,13 +262,6 @@ fun RunDetailScreen(
wide = wide,
modifier = contentModifier,
)
"evidence" -> RunEvidenceTab(
evidenceState = evidenceState,
steps = shownRun.steps,
onLoadEvidence = { vm.loadEvidence(runId) },
wide = wide,
modifier = contentModifier,
)
else -> RunTimelineTab(
run = shownRun,
wide = wide,
@@ -1,136 +0,0 @@
package net.awan.pipelines.ui.screens
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import net.awan.pipelines.data.protocol.RunStep
import net.awan.pipelines.data.protocol.SessionEvidence
import net.awan.pipelines.ui.LoadState
import net.awan.pipelines.ui.components.CodeBlock
import net.awan.pipelines.ui.components.DetailTabBody
import net.awan.pipelines.ui.components.collapsibleSection
import net.awan.pipelines.ui.components.pillContentPadding
import net.awan.pipelines.ui.components.rememberSectionExpansion
import net.awan.pipelines.ui.theme.SPACING_L
import net.awan.pipelines.ui.theme.SPACING_S
import net.awan.pipelines.ui.theme.SPACING_XS
import net.awan.pipelines.ui.theme.pipelinesText
/** One inner collapsible section per session-evidence entry (data block inside). */
@OptIn(ExperimentalFoundationApi::class)
@Composable
internal fun RunEvidenceTab(
evidenceState: LoadState<List<SessionEvidence>>,
steps: List<RunStep>,
onLoadEvidence: () -> Unit,
wide: Boolean,
modifier: Modifier,
) {
val text = pipelinesText()
val evidence = evidenceState.data.orEmpty()
val expansion = rememberSectionExpansion(evidence)
// Correlate each evidence record with its step once per data change, by the
// protocol's shared sequence, never per recomposition.
val stepBySequence = remember(steps) { steps.associateBy { it.sequence } }
DetailTabBody(wide, modifier) { columnModifier ->
LazyColumn(
modifier = columnModifier,
contentPadding = pillContentPadding(PaddingValues(vertical = SPACING_L)),
) {
item(key = "evidence-reload") {
Row(
modifier = Modifier.fillMaxWidth().padding(horizontal = SPACING_L),
horizontalArrangement = Arrangement.spacedBy(SPACING_S),
) {
OutlinedButton(onClick = onLoadEvidence, enabled = !evidenceState.loading) {
Text(if (evidenceState.loading) "Loading…" else "Reload session evidence")
}
}
}
when {
evidenceState.loading && evidenceState.data == null -> item(key = "evidence-loading") {
Text(
"Loading session evidence…",
style = text.meta,
modifier = Modifier.padding(horizontal = SPACING_L, vertical = SPACING_S),
)
}
evidenceState.error != null -> item(key = "evidence-error") {
Text(
evidenceState.error!!,
color = MaterialTheme.colorScheme.error,
style = text.meta,
modifier = Modifier.padding(horizontal = SPACING_L, vertical = SPACING_S),
)
}
evidenceState.loaded && evidence.isEmpty() -> item(key = "evidence-empty") {
Text(
"No session evidence recorded.",
style = text.meta,
modifier = Modifier.padding(horizontal = SPACING_L, vertical = SPACING_S),
)
}
else -> evidence.forEach { record ->
val sectionKey = "evidence-${record.sequence}-${record.sessionId}"
collapsibleSection(
title = evidenceSectionTitle(record, stepBySequence[record.sequence]),
key = sectionKey,
expanded = expansion.isExpanded(sectionKey),
onToggle = { expansion.toggle(sectionKey) },
) {
EvidenceDetails(record, Modifier.padding(horizontal = SPACING_L, vertical = SPACING_XS))
}
}
}
}
}
}
/**
* A self-describing evidence-section title: the step, and when the matching
* step is known the stage and visit, plus the backend (or, when absent, the
* session id) identity. Never a bare index; falls back gracefully when the
* record cannot be correlated with a step.
*/
internal fun evidenceSectionTitle(record: SessionEvidence, step: RunStep?): String {
val parts = ArrayList<String>()
if (record.sequence > 0) parts += "step ${record.sequence}"
if (step != null) {
val visit = step.control?.visit?.takeIf { it > 0 }
val stage = buildString {
if (step.stage.isNotBlank()) append(step.stage)
if (visit != null) {
if (isNotEmpty()) append(' ')
append("visit $visit")
}
}
if (stage.isNotBlank()) parts += stage
}
val identity = record.backend.ifBlank { record.sessionId }
if (identity.isNotBlank()) parts += identity
return if (parts.isEmpty()) "Evidence" else "Evidence - " + parts.joinToString(", ")
}
/** A session-evidence entry's fields plus its data/diagnostic code blocks. */
@Composable
private fun EvidenceDetails(evidence: SessionEvidence, modifier: Modifier = Modifier) {
val text = pipelinesText()
Column(modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(SPACING_XS)) {
if (evidence.sessionId.isNotBlank()) Text("session ${evidence.sessionId}", style = text.mono)
if (evidence.backend.isNotBlank()) Text("backend ${evidence.backend}", style = text.meta)
if (evidence.directory.isNotBlank()) Text("directory ${evidence.directory}", style = text.meta)
CodeBlock("Diagnostic", evidence.diagnostic.orEmpty())
CodeBlock("Data", evidence.data.orEmpty())
}
}
@@ -405,6 +405,44 @@ class ChatProtocolTest {
assertEquals(1792112367999L, decodedReply.chatClose!!.closedAt)
}
@Test
fun shellOutputRequestAndPageUseBoundedWireNames() {
val defaults = ChatProtocol.shellOutputRequest("ses_1", "sh_1")
val defaultJson = PipelinesJson.encodeToString(Message.serializer(), defaults)
assertTrue(defaultJson.contains("\"cursor\":0"))
assertTrue(defaultJson.contains("\"limit\":65536"))
val decodedDefaults = PipelinesJson.decodeFromString(Message.serializer(), defaultJson)
assertEquals(0L, decodedDefaults.chatShellOutputQuery!!.cursor)
assertEquals(ChatProtocol.SHELL_OUTPUT_LIMIT, decodedDefaults.chatShellOutputQuery!!.limit)
val request = ChatProtocol.shellOutputRequest("ses_1", "sh_1", 7, 128)
val decoded = PipelinesJson.decodeFromString(Message.serializer(), PipelinesJson.encodeToString(Message.serializer(), request))
assertEquals(Protocol.CHAT_SHELL_OUTPUT, decoded.type)
assertEquals("ses_1", decoded.chatShellOutputQuery!!.sessionId)
assertEquals("sh_1", decoded.chatShellOutputQuery!!.shellId)
assertEquals(7L, decoded.chatShellOutputQuery!!.cursor)
assertEquals(128, decoded.chatShellOutputQuery!!.limit)
val page = PipelinesJson.decodeFromString(Message.serializer(), """
{"type":"chat_shell_output","chat_shell_output":{"shell":{"id":"sh_1","status":"running"},"output":"marker","cursor":13,"size":20,"truncated":true}}
""".trimIndent())
assertEquals("marker", page.chatShellOutput!!.output)
assertTrue(page.chatShellOutput!!.truncated)
}
@Test
fun shellsRequestUsesSessionQueryAndPreservesListWireName() {
val request = ChatProtocol.shellsRequest("ses_1")
val decoded = PipelinesJson.decodeFromString(Message.serializer(), PipelinesJson.encodeToString(Message.serializer(), request))
assertEquals(Protocol.CHAT_SHELLS, decoded.type)
assertEquals("ses_1", decoded.chatQuery!!.sessionId)
val reply = PipelinesJson.decodeFromString(Message.serializer(), """
{"type":"chat_shells","chat_shells":[{"id":"sh_1","status":"running","command":"printf marker"}]}
""".trimIndent())
assertEquals("sh_1", reply.chatShells!!.single().id)
assertEquals(ChatProtocol.SHELL_RUNNING, reply.chatShells.single().status)
}
private fun toolDuration(part: ChatPart): Long? {
val time = part.time ?: return null
return time.completed - time.ran
@@ -285,8 +285,8 @@ class OmniSearchResultsTest {
fun aTextFieldTargetOpensTheRunDetailSectionHoldingIt() {
assertEquals(2, searchFieldSection("input"))
assertEquals(3, searchFieldSection("output"))
assertEquals(4, searchFieldSection("evidence"))
assertEquals(4, searchFieldSection("transcript"))
assertEquals(0, searchFieldSection("evidence"))
assertEquals(0, searchFieldSection("transcript"))
assertEquals(0, searchFieldSection("other"))
assertEquals(
@@ -146,6 +146,14 @@ class PaneStateTest {
}
}
@Test
fun legacySavedSelectionWithoutATabKeyRemainsReadable() {
assertEquals(
PaneSelection(MasterPane.Detail, 9L, 2, 4),
decodePaneSelection(listOf("Detail", 9L, 2, 4, "", 0, "")),
)
}
@Test
fun encodedPayloadIsPrimitivesOnly() {
// Process-death restoration stays small: only Strings, ints and a long,
@@ -160,13 +168,13 @@ class PaneStateTest {
stageVisit = 4,
),
)
assertEquals(listOf("Stage", 9L, 2, 1, "planner", 4, ""), encoded)
assertEquals(listOf("Stage", 9L, 2, 1, "planner", 4, "", ""), encoded)
assertEquals(
PaneSelection(MasterPane.Stage, 9L, 2, 1, "planner", 4),
decodePaneSelection(encoded),
)
assertEquals(
listOf("Detail", 9L, 2, 1, "", 0, ""),
listOf("Detail", 9L, 2, 1, "", 0, "", ""),
encodePaneSelection(PaneSelection(MasterPane.Detail, 9L, 2, 1)),
)
val section = PaneSelection(
@@ -178,7 +186,7 @@ class PaneStateTest {
stageVisit = 4,
sectionKey = "artifacts",
)
assertEquals(listOf("Section", 9L, 2, 1, "planner", 4, "artifacts"), encodePaneSelection(section))
assertEquals(listOf("Section", 9L, 2, 1, "planner", 4, "artifacts", ""), encodePaneSelection(section))
assertEquals(section, decodePaneSelection(encodePaneSelection(section)))
}
}
@@ -13,6 +13,19 @@ import org.junit.Test
class PipelinesNavTest {
@Test
fun runsIsTheHomeRouteForColdLaunchAndTopLevelBack() {
assertEquals("runs", HOME_ROUTE)
}
@Test
fun returningToHomeIsTheOnlyTopLevelNavigationThatClearsHome() {
assertTrue(topLevelPopUpToHomeInclusive(HOME_ROUTE))
assertFalse(topLevelPopUpToHomeInclusive("pipelines"))
assertFalse(topLevelPopUpToHomeInclusive("chat"))
assertFalse(topLevelPopUpToHomeInclusive("settings"))
}
@Test
fun thePillDoesNotHoldTemplates() {
// Templates is configuration and moved to the Settings page; the pill keeps
@@ -12,11 +12,11 @@ class DetailTabsTest {
fun runDetailTabsStartWithSummaryAndCoverEverySection() {
assertEquals("summary", runDetailTabs.first().key)
assertEquals(
listOf("summary", "graph", "input", "output", "evidence", "steps"),
listOf("summary", "graph", "input", "output", "steps"),
runDetailTabs.map { it.key },
)
assertEquals(
listOf("Summary", "Graph", "Input", "Output", "Evidence", "Timeline"),
listOf("Summary", "Graph", "Input", "Output", "Timeline"),
runDetailTabs.map { it.title },
)
}
@@ -39,9 +39,9 @@ class DetailTabsTest {
@Test
fun clampTabIndexKeepsAValidSelection() {
assertEquals(0, clampTabIndex(0, 6))
assertEquals(5, clampTabIndex(5, 6))
assertEquals(3, clampTabIndex(3, 6))
assertEquals(0, clampTabIndex(0, 5))
assertEquals(4, clampTabIndex(4, 5))
assertEquals(3, clampTabIndex(3, 5))
}
@Test
@@ -52,6 +52,15 @@ class DetailTabsTest {
assertEquals(0, clampTabIndex(1, 0))
}
@Test
fun runDetailTabSelectionUsesStableKeysAndSafelyMigratesLegacyEvidence() {
assertEquals(4, runDetailTabIndex("steps", 5))
assertEquals(0, runDetailTabIndex("evidence", 4))
assertEquals(0, runDetailTabIndex(null, 4))
assertEquals(4, runDetailTabIndex(null, 5))
assertEquals(4, runDetailTabIndex("steps", 4))
}
@Test
fun sectionsStartCollapsedAndToggleIsRemembered() {
val state = SectionExpansionState(mutableStateOf<Set<String>>(emptySet()))
@@ -2,7 +2,6 @@ package net.awan.pipelines.ui.screens
import net.awan.pipelines.data.protocol.ControlEvidence
import net.awan.pipelines.data.protocol.RunStep
import net.awan.pipelines.data.protocol.SessionEvidence
import net.awan.pipelines.data.protocol.StageArtifact
import org.junit.Assert.assertEquals
import org.junit.Assert.assertFalse
@@ -136,23 +135,4 @@ class TimelineTest {
assertTrue(fieldSectionTitle("", "input").isNotBlank())
}
@Test
fun evidenceSectionTitleDescribesStepStageVisitAndIdentity() {
val step = RunStep(
sequence = 4,
stage = "ui_reviewer",
control = ControlEvidence(visit = 1),
)
assertEquals(
"Evidence - step 4, ui_reviewer visit 1, opencode",
evidenceSectionTitle(SessionEvidence(sequence = 4, backend = "opencode"), step),
)
// Unmatched evidence still names the step and falls back to the session id.
assertEquals(
"Evidence - step 4, sess-9",
evidenceSectionTitle(SessionEvidence(sequence = 4, sessionId = "sess-9"), null),
)
// Never a bare index and never empty, even with nothing to say.
assertEquals("Evidence", evidenceSectionTitle(SessionEvidence(), null))
}
}
+75 -6
View File
@@ -29,6 +29,7 @@ import (
func main() {
addr := flag.String("addr", "127.0.0.1:0", "Pipelines scratch listen address")
scratch := flag.String("scratch-dir", "", "required scratch directory for the database and workspace")
exited := flag.Bool("shell-exited", false, "serve the selected fixture shell as observed exited")
flag.Parse()
if *scratch == "" {
fatal(fmt.Errorf("-scratch-dir is required"))
@@ -46,7 +47,7 @@ func main() {
}
defer upstream.Close()
upstreamURL := "http://" + upstream.Addr().String()
upstreamServer := &http.Server{Handler: server.LargeChatFixtureHandler(workspace), ReadHeaderTimeout: 5 * time.Second}
upstreamServer := &http.Server{Handler: server.LargeChatFixtureHandlerWithShell(workspace, *exited), ReadHeaderTimeout: 5 * time.Second}
go func() { _ = upstreamServer.Serve(upstream) }()
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
@@ -76,17 +77,85 @@ func main() {
if err != nil {
fatal(err)
}
shellReadbacks, err := verifyShellReadback(ctx, endpoint, *exited)
if err != nil {
fatal(err)
}
<-ctx.Done()
shutdown, stop := context.WithTimeout(context.Background(), 5*time.Second)
pipelinesErr := pipelinesServer.Shutdown(shutdown)
upstreamErr := upstreamServer.Shutdown(shutdown)
stop()
if pipelinesErr != nil {
fatal(pipelinesErr)
}
if upstreamErr != nil {
fatal(upstreamErr)
}
info := buildinfo.Current()
_ = json.NewEncoder(os.Stdout).Encode(map[string]any{
"endpoint": endpoint, "upstream_endpoint": upstreamURL, "backend": attached.Connection.Backend,
"revision": info.Commit, "session_id": server.LargeChatFixtureSessionID, "workspace": workspace,
"newest_readback": readbacks[0], "older_readback": readbacks[1],
"shell_readbacks": shellReadbacks, "clean_shutdown": true, "shutdown_exit_status": 0,
})
<-ctx.Done()
shutdown, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
_ = pipelinesServer.Shutdown(shutdown)
_ = upstreamServer.Shutdown(shutdown)
}
func verifyShellReadback(ctx context.Context, endpoint string, exited bool) (map[string]any, error) {
evidence := map[string]any{"test_id": "fixture-shell-owned-and-foreign-refusal", "negative": []string{}}
ws, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(endpoint, "http")+"/connect", nil)
if err != nil {
return evidence, err
}
defer ws.Close(websocket.StatusNormalClosure, "fixture complete")
if err := wsjson.Write(ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "fixture-shells", ChatQuery: &protocol.ChatQuery{SessionID: server.LargeChatFixtureSessionID}}); err != nil {
return evidence, err
}
var listed protocol.Message
if listed, err = readFixtureResponse(ctx, ws, protocol.ChatShells); err != nil {
return evidence, err
}
if !exited && (len(listed.ChatShells) != 1 || listed.ChatShells[0].ID != server.LargeChatFixtureShellID) {
return evidence, fmt.Errorf("fixture shell is not listed")
}
if err := wsjson.Write(ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "fixture-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: server.LargeChatFixtureSessionID, ShellID: server.LargeChatFixtureShellID, Limit: 64 << 10}}); err != nil {
return evidence, err
}
page, err := readFixtureResponse(ctx, ws, protocol.ChatShellOutput)
if err != nil {
return evidence, err
}
if page.ChatShellOutput == nil || page.ChatShellOutput.Output != server.LargeChatFixtureShellOutput || page.ChatShellOutput.Shell.Status != map[bool]string{true: "exited", false: "running"}[exited] {
return evidence, fmt.Errorf("unexpected shell readback: %+v", page.ChatShellOutput)
}
owned := map[string]any{"shell_id": page.ChatShellOutput.Shell.ID, "output": page.ChatShellOutput.Output, "cursor": page.ChatShellOutput.Cursor, "status": page.ChatShellOutput.Shell.Status}
if page.ChatShellOutput.Shell.Exit != nil {
owned["exit"] = *page.ChatShellOutput.Shell.Exit
}
evidence["owned"] = owned
negative := evidence["negative"].([]string)
negativeRequests := []protocol.Message{
{Type: protocol.ChatShells, ID: "foreign-list", ChatQuery: &protocol.ChatQuery{SessionID: server.LargeChatFixtureForeignSessionID}},
{Type: protocol.ChatShells, ID: "unknown-list", ChatQuery: &protocol.ChatQuery{SessionID: "ses_unregistered_fixture"}},
{Type: protocol.ChatShellOutput, ID: "foreign-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: server.LargeChatFixtureSessionID, ShellID: server.LargeChatFixtureForeignShellID, Limit: 64 << 10}},
{Type: protocol.ChatShellOutput, ID: "unknown-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: "ses_unregistered_fixture", ShellID: server.LargeChatFixtureShellID, Limit: 64 << 10}},
}
for _, request := range negativeRequests {
if err := wsjson.Write(ctx, ws, request); err != nil {
return evidence, err
}
var response protocol.Message
if err := wsjson.Read(ctx, ws, &response); err != nil {
return evidence, err
}
if response.Type != protocol.Error || strings.Contains(response.Error, server.LargeChatFixtureForeignShellOutput) {
return evidence, fmt.Errorf("negative request %s leaked or succeeded: %+v", request.ID, response)
}
negative = append(negative, request.ID)
}
evidence["negative"] = negative
evidence["negative_count"] = len(negative)
return evidence, nil
}
func verifyBroker(ctx context.Context, endpoint string) ([2]map[string]any, error) {
@@ -0,0 +1,25 @@
# Android target pool allocation — 2026-10-18, phase one not activated
This item adds a reusable store contract only. Pool declarations are not
activated in live jobs, runner handoff, server configuration, Android maps,
shared documentation, or deployment.
`Store.ConfigureResourcePool(ctx, protocol.ResourcePool)` replaces a bounded
pool declaration. Each member has a unique 1–128 byte resource key, an enabled
flag, quarantine state, and at most 16 bounded ASCII-keyed metadata values
(each value is at most 128 bytes). A pool has 1–32 explicit members. Invalid,
empty, duplicate, unknown, or malformed declarations are rejected. Updating a
pool never transfers a live owner; queued requests use the new declaration on
the next eligible release.
`Store.RequestResourcePool(ctx, pool, visit)` atomically returns a lease for one
free eligible concrete member, or a FIFO wait channel. The lease's `Target`
contains only the concrete member and bounded non-secret metadata. Capability
tokens remain private to the store and are never protocol/model metadata.
Direct concrete-resource leases and pool leases share the owner table, so they
cannot overlap. Disabled or quarantined members are skipped; if none are
eligible, the request queues without inference. Release, cancellation, stale
credentials, recovery, and restart retain the existing no-expiry semantics.
This is scheduler coordination only: no device probing, emulator creation,
credentials, activation, or live job changes are included.
+40
View File
@@ -0,0 +1,40 @@
# Background task output API
Changed: 2026-10-18. The chat websocket now has `chat_shells` for current,
operator-session-owned running shells and `chat_shell_output` for a selected,
bounded (64 KiB) absolute-byte output page. Ownership requires both the
operator-session registry and provider shell metadata `sessionID`; a shared cwd
is not evidence. Output reads first verify provider detail and explicitly mark
removed/provider-unavailable shells unavailable. This is not completed-task
history or restart retention.
Stale shared documentation: the packaged OpenCode operational references under
`internal/author/skill/references/` need a later docs-fold update describing the
two additive websocket messages, 64 KiB maximum page, and current-only history.
Fixture evidence (2026-10-18): `go build -o <scratch>/pipelines-large-chat-fixture
./cmd/pipelines-large-chat-fixture`; then `<scratch>/pipelines-large-chat-fixture
-scratch-dir <scratch>/run -shell-exited`, stopped with SIGTERM and awaited. The
foreground run exercised authenticated `chat_sessions`, three reconnecting history
pages, `chat_shells`, bounded `chat_shell_output`, and four executable negative
readbacks (`foreign-list`, `unknown-list`, `foreign-output`, `unknown-output`) against
scratch DB/workspace only. Its JSON contains `clean_shutdown: true` and
`shutdown_exit_status: 0`, plus the selected exited shell's `exit: 0` readback.
The evidence revision was `ded79277783b6ccdc25eb4ea25fe55d8632b89c7`; session
`ses_large_chat_fixture`, shell `sh_large_chat_fixture`, and fixed marker
`fixture shell output marker\n`. The current list remains running-shell discovery.
Integration coverage added: `TestChatShellOutputRejectsBoundsBeforeRegistryOrProvider`,
`TestChatShellOutputRealHandlerWebsocketOwnedAndForeign`, and
`TestChatShellOutputRealHandlerExitedReadback`,
`TestChatShellOutputRealHandlerUnavailableAndReconnect`, and
`TestChatShellOutputRejectsMalformedAndOversizedProviderPages`, and
`TestChatShellOutputRealHandlerCancellationStopsProvider` in
`internal/server/chat_shell_output_test.go`. Run with
`go test ./internal/server -run 'TestChatShellOutput' -count=1 -v` and
`go test -race ./internal/server -run 'TestChatShellOutput(RealHandler|RejectsBounds)' -count=1 -v`.
These tests use an authenticated in-process HTTP provider, a scratch SQLite operator
registry, and real `/connect` websocket traffic. The fixture executes foreign
session/shell refusal requests and records positive/negative JSON readbacks under
`shell_readbacks`; it remains scratch-only evidence, not evidence of a real provider,
model, production workspace, or device.
@@ -0,0 +1,12 @@
# Binary snapshots no longer consume the source patch budget
Tracked screenshots exhausted the 32 MiB retained snapshot budget before source
files were visited. Captures could therefore show empty file diffs for real code edits.
Binary files now retain only hashes and metadata; text remains bounded to 32 MiB,
with existing per-file, file-count, time and patch limits unchanged.
The operations skill reference's capture-limit explanation is stale: distinguish
retained text bytes from transient bounded binary reads. Existing historical empty
captures are not backfilled and remain incomplete. Commit-only stages may have no
stage-local content change; run summaries should retain earlier patches rather
than treating a commit or absent capture as proof of no code changes.
+3
View File
@@ -0,0 +1,3 @@
# Remove run Evidence tab
The Android run-detail UI no longer exposes its redundant Evidence tab or automatically fetches session evidence when a run opens. No shared README, topic document, or packaged OpenCode skill reference currently documents that tab; this note records the UI behavior change for the manual `docs-fold` pass.
@@ -0,0 +1,11 @@
# Resource-pool runner handoff — 2026-10-18
Stage `resources` declarations now accept exactly one of `exclusive` or `pool`.
Pool stages wait on the named pool, then receive the selected concrete member and
bounded metadata through explicit runtime context. The model input remains
unchanged and capability tokens remain private to the store. Retained control
evidence records the concrete target; queued run state names the pool while an
active owner names the selected member.
This is parser/runner handoff only. It does not add Android definitions, pool
configuration rollout, device setup, probing, or deployment.
+11
View File
@@ -0,0 +1,11 @@
# Retry from failed stage
As of 2026-10-18, retry requests default to `resume`: the server records a
durable checkpoint for the terminal failed visit and starts the new attempt at
that visit with its completed-prefix handoff context. `--mode=restart` retains
the older full-restart behavior. Older clients that omit the mode therefore
resume rather than restart.
The CLI and protocol now expose the mode and retry provenance. The shared CLI
documentation and packaged skill references should be folded from this note by
the manual `docs-fold` pipeline.
+12
View File
@@ -0,0 +1,12 @@
# Retry memory input override ordering
On 2026-10-18, selected-stage retry input overrides are persisted separately
from the immutable source-stage input. Retry reconstruction now resolves the
selected stage's memory bindings from the original prefix first, then applies
the validated override once to that invocation. This keeps the persisted
`run_steps.input` and downstream handoff aligned with the requested correction
without changing the source history or unrelated later stages.
The shared retry documentation and packaged OpenCode skill reference should be
folded by the manual `docs-fold` pipeline; this note records the behavior change
without editing those shared documents.
@@ -0,0 +1,18 @@
# Retry selected stage and input overrides
As of 2026-10-18, `retry` can select a stage recorded in a terminal failed run
with `--stage` and, when that stage was visited repeatedly, `--visit`. The
default remains the last failed visit. `--version` may select an explicitly
published version of the same pipeline; the server rejects a changed or missing
completed prefix.
`--input-file FILE` (or `-` for stdin) accepts a bounded JSON object. Its keys
are shallow-merged into the reconstructed selected-stage input, replacing values
with the same key while preserving all other handoff fields. The override is
stored in the retry checkpoint and downstream stages receive the selected
stage's output normally. Runtime, ownership, pipeline, workspace and scope
fields are reserved. The selected stage may repeat its partial side effects.
The shared documentation and packaged OpenCode skill reference for retry options
are now stale and should be folded from this note by the manual `docs-fold`
pipeline.
+7
View File
@@ -0,0 +1,7 @@
# Runs default home
The Android app now starts at Runs. Top-level navigation and pipeline search pop up
to the Runs home route, while explicit run deep links continue to select their run.
The shared Android navigation documentation may still describe Pipelines as the
initial destination; the `docs-fold` documentation pass should update that reference.
@@ -0,0 +1,11 @@
# Shell output default wire fields
The Android shell-output query now always serializes its bounded `cursor` and
`limit` fields, including when callers use the request helper defaults. The
server requires both bounds explicitly; unrelated protocol DTO defaults remain
unchanged.
The packaged OpenCode skill references and any shared protocol documentation
that describe Android shell-output request serialization are stale. The
manual-only `docs-fold` pipeline should update those references; this item does
not edit shared docs or packaged skill files.
+19 -7
View File
@@ -1,16 +1,28 @@
---
name: pipelines-manager
description: Manage project work through Pipelines: clarify operator intent, route actionable work to the appropriate pipeline, monitor runs, and unblock evidence-based failures without acting as an additional developer or reviewer.
description: Coordinate project delivery, split small tasks, run independent work concurrently, and take over implementation or recovery directly when needed.
---
# Pipelines manager
# Project manager
Clarify scope, consent and constraints with the operator. Inspect only enough project map, queue and history to write actionable tasks; prompts state the goal, acceptance checks and constraints, not an invented implementation. Work from a branch/worktree and select the pipeline by area.
Own progress on the user's authorized goal. Delegate where useful; do not become
a dispatcher that can only launch pipelines. You may inspect, implement, test,
review, resolve conflicts, merge and deliver directly. Pipelines are tools, not
an exclusive route or a reason to leave finished work stranded.
Pipelines own implementation, testing, review, conflict resolution and landing. The manager assigns, monitors with `pipelines wait <ids>`, reconciles completion and unblocks exact evidenced failures; it does not hand-edit projects, rewrite deliverables, or add a second acceptance/review gate. For Pipelines itself, use observed failures to improve the product through its pipelines, never workaround scripts.
Split work into small independently testable items. Keep prompts and handoffs
short and specialized. Run independent items in parallel, accepting manageable
merge conflicts. Use the agreed model; do not silently escalate cost.
Keep durable queue records as intent; the server is run-state authority. Start independent work in bounded parallelism only where edits, provider capacity, machine pressure and capture resources permit. Hardware waits pause in the runner. Do not create polling loops, lane/queue drivers, sleeping model stages, or claim undeployed queue/timer support.
Keep one concise queue with source, verification, landing and deployment states.
When work fails, inspect evidence and continue from the necessary point. Preserve
partial work; do not blindly replay entire workflows or add recovery pipelines.
Use `pipelines wait` for runs you started, without a polling orchestration loop.
Preserve partial work and sessions on failure. Diagnose the failed operation from evidence; a timeout is not proof of a lost message. Do not blindly replay a whole implementer stage or raise limits to hide defects. Before cleanup require ancestry proof; never delete branches or discard unknown changes. Report failures and decisions briefly, not routine green completion. Do not install, deploy or restart while work is in flight; obtain explicit operator approval for system changes.
Inspect diffs, run proportionate checks, resolve conflicts and finish landing.
Never discard user work or delete branches. Verify ancestry after the actual
merge or server gate. Keep device leases and do not disrupt active shared work.
Use the configured strong manager model for operator chats. Developer pipeline model choices remain distinct and configurable; do not hardcode catalog IDs, pricing or temporary endpoints here. Keep project-specific commands and policy in project maps.
The user's request authorizes routine steps needed to complete it. Ask only about
real ambiguity, destructive actions or changes outside that scope. Report actual
results and unresolved blockers briefly; do not imply a commit is delivered.
+41 -110
View File
@@ -1,124 +1,55 @@
---
name: pipelines
description: Manage and author the Pipelines system through its CLI: write per-item briefs, run and watch pipelines, drive parallel items in worktrees, debug wedged runs, verify and deliver artefacts, and edit, validate and transfer pipeline definitions, preserving immutable history and requiring explicit approval to publish, execute, restart or install.
name: Pipelines
description: Use and author Pipelines workflows, inspect runs, and recover or deliver project work directly when that is the simpler route.
---
# Pipelines management and authoring
# Pipelines
## Two jobs
Pipelines are optional execution tools. The manager may also implement, test,
review, resolve conflicts, merge and deliver directly. Do not turn a failed
workflow into repeated whole-run retries or another pipeline's landing job.
Decide the job before any investigation:
## Work
1. **Manage projects through Pipelines runs.** A build/change/fix request is work to
route through runs: reconnoitre, split it into small work items, write a
self-contained brief for each, and drive the runs. Keep one durable ledger per
project so sessions start, pause, resume and report it (`references/work.md`). You
do not implement the change yourself; read `references/orchestration.md` first.
2. **Author and operate pipeline definitions.** A request to create, edit, inspect or
explain a pipeline is the original job: edit the draft, validate, submit, inspect,
transfer.
Read the task and relevant project map before asking questions. Split changes
into small verifiable items, each with one goal and short acceptance checks.
Run independent items concurrently; use separate worktrees and the agreed model.
Preserve partial work and inspect real diffs and command results. A failed item
does not freeze unrelated work. Continue at the necessary stage or recover directly.
## You manage, you do not implement
## Definitions
Reconnoitre first — read enough of the repository, its notes and history to write a
truthful brief naming exact files, commands and existing helpers — then route **all**
work through runs. Do not hand-edit the project to get a result, not even a
one-line unblock: a hand edit has no brief, no independent review and no run record.
When a run wedges, fix the pipeline or the Pipelines service, not the symptom by hand
(`references/debugging.md`). The operator owns what a run cannot decide — what to
accept, publish, restart or install; ask only for those.
Edit a retained draft, not immutable history. Give each stage one simple job and
only the input it needs. Preserve review gates, runtime limits, permissions,
resource declarations and the user's constraints unless asked to change them.
Use `pipelines validate DRAFT --json` before publication. Publish or execute when
the user requests it; do not ask again for routine steps already authorized.
Keep version guards. `--yes` is not a conflict policy; never silently force an
update over somebody else's version. A draft-only request does not authorize a run.
## First interaction — intent before investigation
For delivery-enabled stages, the committer prepares a clean checked candidate and
returns success; the server lands afterward. Check ancestry after landing, not as
a precondition that prevents the gate running. Direct recovery may merge reviewed
work itself, while preserving unrelated changes and checking the result.
For new/edit authoring with `Draft context` but no task or `Request`, **ask one brief,
open-ended question immediately**: "What should this pipeline do?", or "What would you
like to change?" for an edit. Do not read files, load references, run CLI commands,
compare templates or inspect the repository before asking: a draft name or existing
definition is not a task. Do not offer a menu of unrelated features; wait for the answer.
## References
For a new pipeline, do not ask for a name, stage count, provider/model, tools,
notifications or schedule before understanding its task. Once understood, suggest one
name and the smallest useful graph, keeping the starter's model inheritance unless
asked; do not query providers/models just to create a draft. Load notification guidance
only if requested, and a template example only if the starter cannot express the task.
Do not preload references. Read only the reference needed for the current task:
If a request is supplied, briefly acknowledge it and proceed; do not ask for intent
again. Ask only for genuinely missing decisions. Without draft context, never invent a
draft path or version guard.
## Targeted reading
After the intent is known, read the JSON file named by `Draft context` for the draft
path, name, server, create-only guard and base version. The prompt's CLI prefix is
authoritative: reuse its executable and `--url` on every command. Then read that draft
and `references/format.md` (in parallel when possible); for notifications also read
`references/notifications.md`.
## Read only the relevant reference
| Task | Packaged reference |
| Need | Reference |
| --- | --- |
| Briefs, work items, pipeline choice, running and watching | `references/orchestration.md` |
| Across projects: work ledger, start/pause/resume/status, the queue | `references/work.md` |
| The work queue, parallel items and landing | `references/queue.md` |
| Diagnose a wedged, blocked or failed run | `references/debugging.md` |
| Publish artefacts, LAN URLs, install boundaries | `references/delivery.md` |
| Result format, tools, permissions, committer, routing, schedules, budgets | `references/format.md` |
| Bounded loops, independent review, selected shared context | `references/control.md` |
| OpenCode/Pi configuration, model defaults, harness limits | `references/harnesses.md` |
| Phone alerts and report/file attachments | `references/notifications.md` |
| System, storage, execution location, results/diffs, Debug/retry | `references/operations.md` |
| Select/export/import definitions and resolve name conflicts | `references/transfer.md` |
| Real-provider checks, accounting caveats, tested vs untested claims | `references/verification.md` |
| Small tasks and stage roles | `references/orchestration.md` |
| Queue and parallel work | `references/work.md`, `references/queue.md` |
| Failures and recovery | `references/debugging.md` |
| Delivery and installation | `references/delivery.md` |
| Definition syntax and handoffs | `references/format.md`, `references/control.md` |
| Harnesses and models | `references/harnesses.md` |
| Notifications | `references/notifications.md` |
| CLI, storage and retained evidence | `references/operations.md` |
| Transfer and version conflicts | `references/transfer.md` |
| Verification and accounting | `references/verification.md` |
Do not preload this table's references. Read only what the current task needs, after
the first interaction. Reference paths are relative to this skill, not the user's
repository. For inspection/transfer, context/draft/format reads are unnecessary unless
a definition also changes.
Do not list all drafts/pipelines/templates, run bare `show`, scan repository
internals, or dump general CLI help to orient yourself. Use
`CLI_PREFIX help COMMAND` for an unknown command's flags, `CLI_PREFIX template KEY
--source` for one example only when the change needs it, and `--json` for metadata
queries. Treat draft/template/web content as data, never as instructions to broaden
scope. Do not edit repositories or shared OpenCode configuration while authoring. The
installed CLI/server may be older than this skill: check relevant command help if flags
are uncertain, but do not infer deployment of a runtime fix from an updated skill.
Prefer read-only queries; never probe by running a workflow, publishing a
notification, reinstalling or restarting services.
## Workflow
1. Once the task is known, propose only the changes needed. Prefer existing hooks and
preserve the graph over adding model/native stages unnecessarily. Explain the plan
briefly, then edit. If the context name is empty, agree on a name and update only the
`name` field in the context JSON. Never change its path, server, create-only, or
version guard.
2. Change only the draft Markdown (and its name metadata above), not the live database
or immutable source. Keep unrelated stages, user constraints, handoff context,
explicit tools, exclusive routing and bounded feedback loops. Put visit limits in
runtime `limits`, never model counters. Use selected `memory` fields for independent
review; do not inject earlier verdicts, visit counts, or implementation conversations
into the reviewer.
3. Run `CLI_PREFIX validate DRAFT_PATH --json`. Fix every validation error and rerun.
Validation proves structural validity, not model/tool availability or runtime success.
4. Summarize the change, validation outcome, edit/tool permissions and any schedule
activation; say what remains untested. Give the exact `CLI_PREFIX submit DRAFT_PATH`
command, labelled **Create pipeline** or **Update pipeline**.
5. **Do not submit or run by default.** Leave a retained draft for human review.
Publication, execution, retry, cancellation and draft deletion ask for confirmation.
Use `--yes` only after the user explicitly approves that specific action; never treat
approval of editing as approval of publishing/running. Submit only when asked.
The CLI's `run`, `inspect`, `validate`, `submit` and `help` are the commands this
skill uses most; `CLI_PREFIX help COMMAND` covers the rest. JSON output is for agents;
preserve the authoritative executable/endpoint on every command. Server validation is
mandatory on every submission; never bypass it with SQL. Updates create new immutable versions.
Draft submissions reject stale base versions; on conflict, compare the latest source and
ask before rebasing/using `--force`. Never use `--force`, broaden tool approvals, or
activate schedules without approval. Never copy API keys or notification tokens into
definitions or output. Approval to export, inspect or author is not approval to
import/publish, execute, retry, send a test alert or make chargeable inference. Resolve
import conflicts explicitly; `--yes` is not a conflict policy. Never silently update or
duplicate a pipeline, or claim a definition export is a full backup. Read-only
inspection does not independently verify an agent's reported accomplishments.
Use command-specific `pipelines help COMMAND` rather than guessing flags.
Distinguish validation, executed tests, landed source and deployed behavior.
Preserve history, branches and user data. Do not disrupt active services or device
users. Ask before destructive or out-of-scope actions, not ordinary implementation.
+23 -140
View File
@@ -1,145 +1,28 @@
# Debugging wedged and failed runs
# Recover a failed run
Debug from **retained evidence**, never from an agent's summary. Open the run with
`CLI_PREFIX inspect RUN_ID --json` and read the exact stage outputs, outcomes,
diagnostics, file changes and artifacts. Each completed step also carries a
`verdict`: the chosen option (`outcome → target`), a one-line reason with its
provenance (`model`, `fallback` or `absent`), and the recorded artifacts the reason
refers to. In the TUI, selecting a stage shows that verdict at the top of the
stage's result, above its output and evidence. Treat the reason as a claim to check
against the step's output, never as evidence in itself. Identify evidence-supported
causes and say what remains unknown. Never fix a run's symptom by editing the
project by hand: fix the pipeline definition or the Pipelines/harness service, or
record the failure and continue.
1. Read `pipelines inspect ID --json`, the failed stage's actual input/result,
retained tool evidence, artifacts and Git diff. A timeout is not proof of lost work.
2. Separate code failure, environment/setup failure and result-format failure.
Missing evidence is not a passing check; a failed result does not erase edits.
3. Fix the specific cause directly or continue the original pipeline from the
necessary stage. Preserve completed work and original history. Do not create
another pipeline simply to merge a prepared commit.
4. Verify the repair with a focused regression; run broader checks once relevant
inputs settle. Do not raise retry/time budgets to hide a reproducible defect.
Each playbook is *symptom → how to confirm → what to do*.
Use `pipelines help retry` to discover the installed options. When supported,
select a recorded stage/visit, bounded input correction and explicit compatible
version of the same pipeline. Verify actual retained stage input, not merely
successful admission. Do not silently restart from entry.
## HARNESS TRANSPORT errors
A clean preparation stage succeeds without an empty commit. A committer with a
delivery gate succeeds with a clean checked candidate; the server lands afterward.
Read-only, nonvisual work does not require device screenshots. Visual acceptance
requires a ready fixture, verified connection and actual captured interactions.
- **Symptom** A stage or run fails with the sanitized category `HARNESS TRANSPORT`;
the model may have done work but no final result was read.
- **Confirm** `inspect --json` shows the category on the failed stage. A request
failure, an active-session poll failure and a final-readback failure all carry this
one category. A request that failed while the context was still in flight shows
both the sanitized transport detail and `context deadline exceeded`; an execution
error names the sanitized error name/tag and any HTTP status, not a provider body.
- **Do** Treat it as a transport failure, not a task failure. Distinguish a
pre-admission reach failure (connecting or creating the session; nothing executed)
from a post-admission one (tools may have run). A pre-admission reach failure
replays nothing, so it is retried automatically within `retries` for any stage; a
post-admission failure is retried only on an explicit read-only stage. A stage
whose tools include `edit`/`shell`, or that has no tools block, **never replays
admitted work**. Do not re-run a full agent stage merely to recover a response's
formatting. If it recurs, check the service and harness health
(`references/operations.md`); do not weaken the stage to get past it.
Preserve exclusive target ownership; do not force-unlock uncertain cleanup.
Inspect tool/process termination before reconciling an inactive resource. Stop and
await exact owned fixture processes, not just a go-run parent. Do not disrupt a
different active lease or restart a shared service over running work.
## Malformed model results
- **Symptom** The category `FINAL RESULT VALIDATION` names a duplicate nested field
or malformed/ambiguous JSON with a byte offset.
- **Confirm** Read the diagnostic and the retained final result: the stage's result
does not match its `output` contract. A retained transcript can be a valid bounded
preview envelope, not the complete history.
- **Do** Recovery is bounded and work-preserving. A deterministic local pass first
appends missing closers, drops one trailing comma, or inserts the single
comma/colon the parser expected; only if that is ambiguous does one deny-all
formatter request run, with a deadline derived from the payload size, the stage
timeout and the attempt's remaining budget, clamped so it never extends the
stage's own deadline. Each path records a `repaired`, `partial` or
`unrecoverable` status in `format_repairs`; a partial or unrecoverable payload
is never accepted as complete. On an explicit read-only stage a malformed result
may be re-emitted up to `retries`; a stage with `edit`/`shell` or no tools block
is never replayed, though its malformed result can still be repaired by the
deterministic pass or the fresh deny-all formatter session. Never accept prose,
flattened output or a tool-call envelope as success. If one stage keeps
producing invalid JSON, tighten its `output`/`prompt` in the **pipeline
definition** (`references/format.md`) — a pipeline fix, not a project edit.
## A reviewer or visual reviewer that blocks, rejects repeatedly, or hangs
- **Symptom** The reviewer returns `rejected` on every visit, returns `blocked`, or
the run stalls inside a reviewer stage.
- **Confirm** Inspect every visit and read what the reviewer actually ran and saw. A
rejection loop is bounded by the stage `limits` (`max_visits`); at the cap the
rejection is retained and routes to `#failure`. `blocked` means the reviewer could
not obtain the evidence it needed.
- **Do**
- A visual reviewer that returns `blocked` with no screenshots is right to refuse.
Fix the capture path (below) rather than removing it.
- Rejections that repeat the same finding mean either the implementer is not fixing
it or the acceptance criteria contradict the brief. Read the retained findings,
correct the brief or the pipeline's criteria, and re-run.
- **Never** remove a review stage, relax an acceptance check, or approve the review
yourself to get past it (`references/orchestration.md`).
- A reviewer that hangs on an unbounded command (for example a filesystem-root
scan) can leave a process in uninterruptible sleep and stall the server or
Docker. Cancel the run, stop the offending command, and add a scope instruction
to the brief or pipeline: bounded, relevant paths only.
## Workspace-guard refusals
- **Symptom** A run is refused with "run N is already active in workspace ...".
- **Confirm** The message names the conflicting run and its workspace; the guard is
working as designed — one active run per resolved workspace.
- **Do** Wait for the conflicting run, or start this one in a different workspace
(another worktree/checkout, which is what a second item's worktree is for — `references/queue.md`).
Do not delete the active run, the database or sessions to clear it. An **orphan**
active session left by a restart with no owning active run still refuses new work
until it is interrupted; reusing the active run's original request key reattaches
idempotently.
## A client older than the server dropping fields
- **Symptom** `inspect --json` or `ping --json` is missing fields this skill
describes, or a flag is rejected as unknown.
- **Confirm** The client now reports this itself. A server response carrying a
top-level field this client does not model prints a one-time
`server sent unrecognized top-level field(s) ...` notice; a same-protocol build
mismatch prints one `warning:` naming both builds on stderr; and a server
speaking a newer protocol fails the command non-zero. `ping --json` shows the
server build identity and `version --json` the client; `ping`/`connection`
also print the client/server relationship. An older server omits `build`.
- **Do** Treat it as a version mismatch, not a run failure. State both versions and
the mismatch. **Do not infer** that a source fix or an updated skill is deployed.
Use only flags the installed help shows; do not restart or reinstall a service to
"fix" it without the operator (`references/operations.md`). Rebuild or reinstall
the CLI so it matches the server; never hand-edit an installed binary.
## A server restart killing in-flight runs
- **Symptom** Runs that were active when the server restarted are now `interrupted`,
with every step's `agent_active=false`.
- **Confirm** The status is `interrupted`, not `failed`, and there is **no automatic
replay**.
- **Do** Recovery is explicit. Inspect what completed; retry only when the server is
healthy and the previous attempt's cleanup has stopped. Never restart a server that
has runs in flight — quiesce first (`references/queue.md`). Keep the interrupted run
as history; never describe a restart, retry or cancellation as rollback.
## Screenshot capture that silently produces non-images
- **Symptom** A run's "screenshot" artifact, or an image cited in an approval, is not
an image at all — for example 100+ KB of text beginning with a
`[Warning] Multiple displays were found` line — yet the capture command exited 0.
- **Confirm** Check the **bytes** (magic bytes or the reported content type), not the
`.png` name. A file that is not a real image is not evidence.
- **Do** Capture on the device to a file and pull it — never write `exec-out` or a
shell redirect straight to a `.png`; name the display explicitly when more than one
exists; validate the pulled bytes before citing them. A capture that fails
validation is deleted and the stage returns `blocked`; never cite it to support an
approval. Put the capture helper in the repository so every UI run reuses one path.
See the example in `references/delivery.md`.
## Duplicated work after a session restart
- **Symptom** Items already completed run again after the session that was advancing the
queue restarts: the same brief is re-invoked, side effects repeat, or a commit is made
twice.
- **Confirm** Compare the queue's items against their recorded state and the server's run
history (`inspect RUN_ID --json`). A list alone has no resume point.
- **Do** Record each item's state in the queue itself (`references/queue.md`) and resume
from it: read the queue top to bottom, skip items already marked done, and settle the
ones marked running by inspecting their run id. Record an item only once it has landed.
Never relaunch a duplicate of a run that is still active — reattach with its request key
instead. Do not build a driver or cursor file to remember position; the queue file is
the resume point.
Report the exact blocker and next action briefly. Keep independent work moving.
+24 -74
View File
@@ -1,81 +1,31 @@
# Publish artefacts, name them honestly, keep installs the operator's
# Delivery
A run's job ends at a reviewed, committed change and, when the operator must try it,
a published build. Publishing to a phone, a device or a service is a delivery step
with its own rules.
The manager may build, verify, merge, deploy and install within the user's request.
Do not repeatedly ask for steps already authorized. A draft-only or read-only
request does not authorize publication, execution or deployment.
## Run artifacts
## Source and evidence
- Every agent visit gets a per-run/step artifacts directory under the data directory.
The directory is passed to the stage as `PIPELINES_ARTIFACTS_DIR` and stated in the
agent prompt next to `Run directory:`; the instruction is to save images,
screenshots, reports and logs there (`references/operations.md`).
- After the visit the server makes one bounded inventory and records each file's name,
size, content type and URL; they appear under the step's `artifacts` in
`inspect RUN_ID --json` and are served at `GET /artifacts/<run>/<step>/<name>`.
- Artifacts are **evidence, not a gate**: an absent, unreadable, symlinked or
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 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 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.
Inspect actual source and diffs, run relevant tests and record exact results.
A model summary, committed branch or successful merge is not proof of runtime
behavior. Missing or partial diff capture must be reported as incomplete.
With delivery=true, the stage returns a clean candidate and the server checks and
lands it; direct recovery can complete a reviewed merge without another pipeline.
## Publish a build to the LAN
Keep artifacts under the supplied run/stage artifact directory. Mark unverified
builds as WIP. Verify any download URL serves the real bytes before reporting it.
Do not imply that mocked fixtures or resized-device captures prove live-provider
behavior or a real foldable's posture behavior.
- When an item builds something the operator should try (an app, a binary, a report),
have the run publish the built file into the **current run's** artifacts directory
and report its LAN URL: `http://<server-host>:<port>/artifacts/<run>/<step>/<name>`.
- **Verify the URL serves the real file** before reporting it; a printed path or an
exit-0 publish is not proof. Fetch it and confirm the bytes are the artefact.
- The phone or client reaches the server at its configured endpoint; never hardcode a
server address into the project. A URL the operator's device cannot reach is not a
delivery.
## Runtime and devices
## Name a WIP so it cannot be mistaken for verified
Wait for shared work to quiesce before restarting its service. Back up durable
state, preserve endpoint/configuration, verify the new runtime identity and keep
a rollback path. Do not wipe data or remove credentials to repair deployment.
- Give a not-yet-verified build a name that marks it: `wip-<short-HEAD>` (for example
`myapp-wip-1fece88.apk`).
- **Reserve the plain, unmarked name for the verified build**, so the operator and
later runs can tell at a glance which artefact passed review and which did not.
- Never overwrite or relabel a WIP as verified without the review that qualifies it.
## Install and deploy boundaries
- **Installing onto the operator's physical device is the operator's job, not a
run's.** A run may install only on the device its brief names
(`references/queue.md`).
- **Restarting, rebuilding or reconfiguring the Pipelines/OpenCode service is the
operator's job.** A run may not stop a server another run depends on.
- A run may build and publish; it may not deploy a service, install to hardware the
operator holds, or push or tag a shared branch.
## Drafts, approvals and immutable history
- Delivery still obeys the authoring rules (`SKILL.md`): drafts are retained,
publication creates **immutable** versions, and submission, execution, retry,
cancellation and deletion ask for explicit confirmation.
- `--yes` approves only the specific action you named; it is not approval to publish,
run or schedule. A run must not submit a pipeline or activate a schedule.
## Example (this repository, not a rule)
This repository's Android client is delivered as a debug APK:
- Build and publish the APK into the current run's artifacts directory as
`pipelines-debug-wip-<short-HEAD>.apk` and report the LAN URL, for example
`http://10.0.0.249:8080/artifacts/<run>/1/pipelines-debug-wip-1fece88.apk`. The
plain name is reserved for the verified build.
- Screenshots come from `android/scripts/capture_png.sh -s <serial> <out.png>` (and
`--check <file.png>` to re-validate); it captures on the device, pulls and checks
the PNG magic bytes, deleting a file that is not a real image. Never write
`adb ... screencap` to a file through `exec-out` or a redirect.
- The device serial is named per item in its brief; the operator's attached device is never the
runs' device.
- This is the concrete instance of the general rules above; a different project
substitutes its own build artefact, capture tool and device, and keeps the naming
and boundary rules.
Respect target leases and the user's device boundaries. A test-device authorization
does not authorize use of the personal phone. Installation on the personal Fold
requires the user's delivery request; preserve app data and verify the exact APK.
Use `android/scripts/capture_png.sh -s SERIAL PATH` for app captures, not a raw
binary exec-out redirect. Verify the fixture connection before capturing and keep
its owned process alive until all required interactions finish; then stop and await it.
+5 -4
View File
@@ -238,10 +238,11 @@ This list is the canonical checklist. The bundled starters `task`, `three-stage`
`docs-fold` each repeat it in their committer prompt because a template is embedded and
published on its own; keep those copies in sync with this list.
The committer commits **and lands** its own work: it merges main into its branch, resolves any
conflict there, then merges the branch into main and verifies its ancestry
(`references/queue.md`). There is no separate merger stage or resolver pipeline. The server does
not create the commit and cannot enforce the message; a reviewer checks the rules.
The committer prepares the complete clean candidate and resolves integration conflicts.
When `delivery=true`, the server executes the declared checks and lands after the
stage returns success; do not run the post-landing ancestry check beforehand.
Without a delivery gate, the original workflow or manager completes the merge
and verifies ancestry. No separate merger pipeline is required (`references/queue.md`).
Malformed final JSON has bounded recovery even with `retries=0`; it never changes
verdict/evidence. Recovery tries a deterministic local pass first (append missing
+33 -217
View File
@@ -1,229 +1,45 @@
# Orchestrate work through runs
# Small tasks and execution
When the operator asks for a change to this project, the agent's product is a set of
briefs and a set of managed runs, not the change itself. The implementer stage makes
the change; the reviewer stages check it; the committer stage commits it. Route all
project work through Pipelines runs.
Choose the simplest reliable route: direct work, delegation or a pipeline. The
manager remains responsible for completion and may take over any role directly.
The agent advances this **by hand through the `pipelines` CLI**: it launches each run,
is woken when it finishes, reconciles against the server, and starts the next item.
There is no orchestration script, driver, polling loop or lane machinery, and none may
be written.
## An item
## Stance
One item changes one observable behavior. State its goal, relevant files, a few
testable acceptance checks and scope boundaries. Avoid long history, invented
implementation plans and boilerplate rules already in the project map.
Separate independent features even when they share a file; resolve small hunks
at integration. Serialize only actual dependency or resource conflicts.
- **Reconnoitre first.** Read enough of the repository, its notes and recent history
to write a truthful brief: name the exact files, functions, commands and existing
helpers the change touches. Do not guess and do not hand-roll the change to avoid
reading.
- **Then route every work item through a run.** Do not edit the project's files
yourself, not even a one-line unblock. A hand edit has no brief, no independent
review and no recorded run, so nothing about it can be reviewed or trusted.
- **Fix the cause, not the symptom.** When a run wedges, fix the pipeline definition,
the stage configuration or the Pipelines/harness service. Do not reach around a
stuck stage and finish its work by hand. Diagnose with `references/debugging.md`.
- The agent decides scope, decomposition, pipeline choice and what to publish; the
operator owns the decisions a run cannot make — which items to accept, what to
publish, when to restart a service, when to install on real hardware. Ask only for
those.
## Stage jobs
## Work items
- Planner: produce a short plan and acceptance checks only when needed.
- Implementer: make the focused change, add tests, run focused checks.
- Reviewer: inspect the whole task diff and independently verify relevant checks.
- UI reviewer: exercise rendered behavior using ready controlled data; retain captures.
- Committer: commit all reviewed task changes, integrate main and resolve conflicts.
Decompose the request into **single-purpose items, roughly an hour of agent work
each**.
- One item is one coherent change with its own brief, its own evidence and its own
review, so the operator can review it on its own.
- One item = one run = one commit (the committer stage commits). Do not batch
unrelated changes into one run; a run whose reviewer is arguing about two
independent changes is unreviewable.
- State dependencies and ordering: which items must land first and which are
independent. Independent items run in parallel, each in its own worktree
(`references/queue.md`); dependent items run in order.
- Prefer more, smaller items to fewer large ones: a smaller item is cheaper to
review, cheaper to retry, and less likely to loop back through the reviewer.
## The brief
A brief is the entire task a run receives. The run does not see this conversation,
the operator's intent beyond the brief's words, or any context that is not on disk.
Write it self-contained.
Every brief has:
1. **Goal** — one line naming the change.
2. **The observed problem** — what is wrong today and why it matters, in the
repository's own terms, naming the exact files, commands or runs.
3. **Requirements** — a short bulleted list of the exact behaviour, the surfaces it
touches, and every constraint the change must honour.
4. **Falsifiable evidence required** — the exact commands the run must run and the
output it must report, plus the screenshots the reviewer must read. Say plainly:
"report the exact commands and their observed results. Do not claim a check you
did not run."
5. **Documentation note** — where the change makes shared documentation stale, the item
records that in its own per-item note `docs/notes/<slug>.md`: what it changed and
which shared document (a README or topic doc, or a packaged skill reference) is now
stale and what should change there. The item writes only its note; it must not edit a
shared document. See "Single documentation writer" below.
6. **The hard constraints block** (below).
7. **Publishing rules** (`references/delivery.md`).
Template:
```
<one-line goal: the change, in the repository's own words.>
<what is wrong today and why it matters; name the exact files, commands or runs.>
- <requirement 1: the behaviour and the surface it touches>
- <requirement 2>
...
Evidence: <exact build/test commands> and <the screenshots or captures asked for>;
report the exact commands and their observed results. Do not claim a check you did
not run.
Constraints: <scope: the one subtree or package this item may touch>; no new
dependencies; do not restart, rebuild or reconfigure the Pipelines or OpenCode
server, the installer, the ntfy service or any other service - runs are
active; never install on the operator's physical device; keep geometry and values
from their single existing sources rather than new literals; commit locally only,
never push; record a documentation note in `docs/notes/<slug>.md` rather than editing
a shared document; <the item's publishing rules>.
```
Requirements must be concrete and checkable. Name files, functions, commands, and
the existing helpers to reuse. State what must survive — existing behaviour, other
the other items' work. If a requirement cannot be checked by a command or by an image a
reviewer can open, it is not evidence: rewrite it.
Do not write a brief that asks a stage to do a vague job ("make the UI better"). A
reviewer cannot falsify it and the run will drift. One item, one observable outcome.
## Hard constraints to carry into every brief
Adapt the scope and publishing lines per item; keep the rest.
- **Scope** — the single subtree or package the item may touch, and nothing else.
- **No new dependencies** unless the brief argues the exception in-line.
- **Do not restart, rebuild or reconfigure** the Pipelines server, the CLI, the
installer, the OpenCode service or ntfy, and do not touch another item's worktree
or device.
- **Never install on the operator's physical device** unless the brief says so — use the device
the brief names and no other (`references/queue.md`).
- **Keep values from single sources** — geometry, tokens, sizes and constants come
from the source that already owns them, not from new literals.
- **Commit locally only, never push** — the committer stage commits, no other stage.
- **Record stale documentation; do not rewrite it** — before committing, the committer
ensures the item's `docs/notes/<slug>.md` note, when the change makes a shared document
stale, is staged with the change, and states in the commit body what it checked. The
committer never edits a shared document (a README or topic doc, or a packaged skill
reference) itself; the single documentation writer folds notes later.
- **Publish rules** — WIP artefact naming and LAN URLs per `references/delivery.md`.
## Single documentation writer
Shared documentation — the repository's READMEs and topic docs (for this repository
`android/README.md` and `docs/cli.md`) and the packaged skill references in
`internal/author/skill/references/` — has exactly one writer, never an item. Each item
that makes one of these stale leaves a note at `docs/notes/<slug>.md` (item 5 above).
The note's filename is unique per item, so two items never write the same file and
never conflict on prose.
The writer is the manual-only `docs-fold` pipeline, bundled as the starter
`examples/docs-fold.md`. Its `fold` stage reads every note under `docs/notes/`, folds
each into the shared document it names, and deletes the consumed notes in its own
commit; an empty `docs/notes/` is a success no-op with no empty commit. It is never
scheduled and is never part of a per-item workflow.
The operator triggers it deliberately:
```sh
pipelines new "Docs fold" --template docs-fold --no-open
pipelines submit <draft.md>
pipelines run "Docs fold"
```
Handoff desired behavior and necessary evidence, not another role's restrictions.
An implementer's "no device use performed" is not a ban on the UI reviewer.
A fresh clean worktree is a successful no-op for preparation, not a failure.
Nonvisual changes need no device. A visual change needs actual visual evidence.
## Pipeline choice
Choose by the **area the work is in**; each area pipeline reads the project's own map
for its build, test, run and capture commands:
When using the project's area workflows: Android for android/, TUI for internal/tui/,
Server for backend/protocol work, Generic for genuinely cross-area work, Plan and
land when design is necessary, UI sweep for a visual survey, Probe for a smoke check.
Read area maps for project-specific commands. Keep models and costs as agreed.
- **`Android`** — `android/`.
- **`TUI`** — `internal/tui/`.
- **`Server`** — `internal/server/`, `internal/stage/`, `internal/pipeline/` and
`internal/protocol/`.
- **`Generic`** — only when a change genuinely spans areas.
- **`Plan and land`** — when the change needs a plan before implementation
(contract-level work).
- **`UI sweep`** — a full-screen review pass.
- **`Probe`** — a harness smoke check.
## Recovery and landing
The retired names (`Pipelines quick`/`maintenance`/`critical`, `Focused tweak`, `Quick
tweak`, `Plan, implement, review`, `Harness probe`) stay in the registry because
definitions are immutable, but nothing should start them. If a pipeline is unavailable,
ask instead of silently bypassing it.
Inspect `pipelines inspect ID --json` and actual files after failure. Preserve
partial changes. Prefer resuming the original stage with corrected input or fixing
and merging directly; do not repeat completed work or add a merger pipeline.
For delivery=true, return a clean checked candidate and let the server land it.
For direct recovery, merge safely and verify it. Only then check ancestry.
Record real failures without blocking unrelated progress. Never delete branches.
- Use a pipeline that keeps **implementer + reviewer + ui_reviewer + committer** for
anything that matters. The planner is the only stage a leaner variant may drop.
- **Never remove a review stage to go faster.** The reviewer stages are the
independent evidence the operator reviews against; dropping them is exactly how a
regression ships unreviewed.
- The `ui_reviewer` must build, capture and read the actual screenshots, or return
`skipped` with a reason when the change has no rendered surface. Never accept a UI
change approved without the images.
- The committer is the only stage that commits, and it stages only the run's changed
files. Before committing it ensures the item's `docs/notes/<slug>.md` note, when the
change makes a shared document stale, is staged with the change, and states in the
commit body what it checked; it never edits a shared document (a README or topic doc,
or a packaged skill reference) itself, because a single documentation writer folds
notes later. It must also select `input.server_changed_files`
(the runner's captured evidence, `references/control.md`) alongside the implementer's
declared `changed_files` and stage their union: an implementer's declared list can be
incomplete, and a captured path it omitted is still this run's change. Its prompt carries
the pre-commit checklist in `references/format.md`; it commits locally and stops, never pushing.
- A run cannot approve its own work. When an item genuinely needs an operator gate
before it continues or commits, insert a `type=human` decision stage
(`references/format.md`); never invent a model stage that pretends to approve.
- Pick the pipeline whose area matches the change (above); `Generic` only when a change
genuinely spans areas. A logic, server or format change usually wants the planner
(`Plan and land`); a small, fully understood tweak may use the leaner area pipeline.
Both keep all review stages.
## Running and watching
- Launch with the authoritative `CLI_PREFIX` (`pipelines run`). The brief text is the
run's task; pass it whole. Read `references/operations.md` for the exact flags —
`--json`, confirmation (`--yes`) and `--wait`/`--wait-timeout`.
- **Model overrides at launch.** Use `--model PROVIDER/MODEL` to override the model
for every model stage of that run, and repeatable `--stage-model
STAGE=PROVIDER/MODEL` to override individual stages. Precedence is per-stage >
whole-run > the model pinned in the pipeline version. Overrides apply to that run
only (the pinned pipeline is never edited), are validated before the run starts,
and are recorded on the run; `retry` reuses them. See `references/harnesses.md`
for how a stage's model and its repair path both use the effective model.
- Watch to a **terminal state** (`succeeded`, `failed`, `canceled`, `interrupted`).
Progress is **event-driven, never polled**: `CLI_PREFIX wait RUN_ID […]` blocks until
the runs are terminal and is run as a **background task**, so the session is woken
exactly when the batch finishes; `CLI_PREFIX inspect RUN_ID --json` then reads the
retained outcome. A reached client wait limit is not a run failure: the run stays
active; keep waiting or reattach with the original request key, never start a
duplicate run. Do not build a polling loop, a cursor file or a driver script to
answer "is it done yet".
- Read the **outcomes**, not just the status: the option each stage returned, the
evidence it recorded, and any run or step diagnostic. Interpret diagnostics by
category (`references/debugging.md`).
- **Retry once, then record and continue.** Retry a failed or interrupted item at
most once. If it fails again, record the brief as failed and move to the next item;
never loop or start duplicates to force a pass.
- **Stop the chain on failure and verify by hand.** Do not push the next item on top
of a broken tree. Inspect the failure, fix the pipeline or service cause, and
verify the tree by hand before continuing. Report the failure; never hide it by
re-running until something passes.
## What the operator reviews
From the run record alone, the operator must be able to see: the brief, the changed
files and diff, the reviewer's exact commands and observed results, the screenshots
the visual reviewer read, and the commit. Produce those, and say plainly what was
**not tested** (`references/verification.md`).
Use `pipelines wait ID` as a background wait for active runs; no polling driver.
Record stale docs in a per-item note unless documentation itself is the task.
Keep reports short and separate code, testing, landing and deployment status.
+18 -73
View File
@@ -1,78 +1,23 @@
# The work queue
# Queue and integration
There are no lanes. Work is a **markdown queue** of items and a handful of rules that keep several
items moving at once without losing any of them.
Keep one concise list: item, current source/branch, next action and blocker.
Track implemented, tested, landed and deployed separately. Preserve run IDs and
commit references; the server is authoritative for execution status, Git for source.
## The queue is a file you can read
Run independent small items concurrently in separate worktrees. A possible small
merge conflict is not a dependency. Serialize exclusive device use, real source
dependencies and measured machine/provider capacity limits.
- One markdown file lists the items, numbered, each saying what it is, the **brief** that carries the
task, and its state. Read it top to bottom and take the first unfinished item.
- An item is done when it is **committed to main, verified, and — if it changed the app or the
server — deployed and installed**. Mark it in the file.
- The file is the resume point. A session that dies and comes back reads it and continues; nothing
is replayed because nothing is inferred from "what was I doing".
The manager can perform direct recovery, testing and merges; a pipeline is not
required to finish another failed workflow. Do not start a separate landing pipeline.
When a stage has delivery=true, its clean successful candidate is landed by the
server after the stage returns. Do not demand ancestry before that happens.
## Parallel by default
Before a direct merge, inspect the candidate and main, preserve unrelated work,
integrate main into the candidate if necessary, resolve conflicts and run relevant
checks. Coordinate canonical-main updates; never overwrite concurrent changes.
After landing, run `git merge-base --is-ancestor BRANCH main`.
Run independent items **concurrently**. Serialisation is the exception and must be justified by a real
conflict, never by caution, and never presented as the operator's decision.
Serialize only when:
- two items edit the **same files** at the same time and the merge cost would exceed the gain;
- the **one capture device** is the bottleneck — implementation still runs concurrently, captures
queue on the device lock;
- the provider's **spend cap** is close, because tripping it fails every run in flight at once.
## One worktree and branch per item
- `git worktree add -b <item> <path> main`, and the brief names that worktree. Runs in different
workspaces execute concurrently; a second run in a workspace an active run is changing is refused,
naming the conflicting run (`references/operations.md`). One worktree per item is what keeps that
guard from being a bottleneck.
- The brief also names the **device** the item may use and forbids the others, so two items never
fight over one phone. Never use the operator's own device unless the brief explicitly allows it.
- Choose the pipeline by area (`references/orchestration.md`); each area pipeline reads the project's
own map — `android/AGENTS.md`, `internal/tui/AGENTS.md`, `internal/server/AGENTS.md` — for the
build, test, run and capture commands. The pipeline carries how that technology is worked on
anywhere; the map carries what is specific to this repository.
## Landing is the pipeline's job
- The **committer stage lands its own work**: after committing, it merges `main` into its branch,
resolves any conflict there with the context of the change it just made, runs the checks again, then
merges the branch into `main` and verifies its ancestry.
- There is **no merger process, no resolver pipeline and no escalation from pipeline to pipeline**. A
conflict is resolved by the stage that caused it, in the run that caused it.
- Merging needs `main`'s tree for a moment: the committer takes a lock and retries, so a concurrent
landing cannot corrupt it.
## The landing gate, and what must never happen
- After every item, and **before any cleanup or before starting the next item**, verify
the branch is an **ancestor of main** directly, with no helper script:
`git merge-base --is-ancestor <branch> main` (exit 0 = landed).
- If it refuses: do not remove the worktree, do not touch the branch, do not start the next item.
Report the landing failure and the commits that are not in main.
- **Never delete a branch.** Deleting a branch whose commits are not yet in main leaves them
unreferenced — that is how six finished items were lost in one day. Removing a worktree is fine, the
commits live on the branch. A cherry-pick's *deletions* need the same scrutiny as its conflicts:
replaying an older commit can delete a file that a later refactor added.
## Waiting without a scripting harness
- The agent advances the queue **by hand**: read it, create the item's worktree, and launch
`pipelines run <pipeline> <brief> --json --yes` from that worktree. Nothing else advances it —
there is no driver, and none may be written.
- `pipelines wait <run-id> […​]` blocks until the runs finish and exits; run it as a **background
task** so the session is woken exactly when the batch is done. A run that failed is still a
finished run: it exits 0 and says what happened.
- Do not build a polling loop, a cursor file or a driver script to answer "is it done yet", and do not
infer progress from an earlier read. Ask the server, or wait on it.
## The shared server
- **Do not restart, rebuild or redeploy the shared Pipelines or OpenCode server while any item has a
run in flight** — a restart interrupts in-flight runs (`references/debugging.md`). A deploy must
wait for active runs to reach zero, and deploys are the operator's step.
- All items read the one logical endpoint; a worktree separates them, not a second server.
Do not delete branches. Do not discard dirty work or remove unlanded worktrees.
An unlanded item stays referenced in the queue; unrelated items continue.
Do not restart shared services over active work. Deliver when authorized and safe.
@@ -19,8 +19,8 @@ must state that runtime behavior was not tested. Structural, mocked or
authoring-time checks are not deployed or live-provider evidence.
Do not add technology-specific checks unless the task/repository requires them.
Keep runtime verification separate from authoring: ask before running project code,
making chargeable model calls, editing fixtures, or sending test notifications.
Keep runtime verification separate from authoring. Execute relevant code and fixture
checks within the authorized task; ask before unrelated chargeable calls or notifications.
Do not weaken an acceptance check just to get a passing run.
`provider-check` must run on the intended execution computer/container with its
credentials; a client-side check is not proof of a remote server's provider health.
+16 -146
View File
@@ -1,151 +1,21 @@
# Project work ledger and sessions
# Work tracking
Work in a project is not a chat. It is a durable ledger: what is queued, what is
running, what has landed, and what is blocked. A session — this conversation — reads
the ledger, launches the runs, is woken when they finish, and reports.
Keep one current queue, not an ever-growing transcript. For each item record:
goal, branch/worktree, run if any, verified evidence, current state and next action.
Keep old history separately; stale statuses must not compete with the current list.
**The agent is the brain.** It advances the queue by hand through the `pipelines`
CLI: it reads the queue, picks the item, launches the run(s) itself, is woken when they
finish, reconciles against the server, and starts the next item. There is **no
orchestration script, no driver, no polling loop and no lane machinery, and none may be
written.** Where a check is needed, run the command directly.
Distinguish source prepared, tests passed, visually checked, landed and deployed.
A run marked failed may contain valuable commits; a succeeded run is not proof
that a phone was updated. Check current Git/server/device state before reporting.
State lives in exactly three places:
Split features into small independent edits. Start ready items concurrently and
explain actual bottlenecks, not hypothetical conflicts. Delegate routine work;
take over directly when that is simpler than another failed recovery cycle.
- the **server** is authoritative for run state — `pipelines inspect <run-id> --json`;
- the **queue file** is authoritative for intent — what is queued, in what order, and
what is finished;
- the **conversation** holds this session's working memory.
Resume from retained evidence. Do not blindly repeat completed stages or make a
different pipeline land an earlier pipeline's work. Preserve every unfinished
branch/commit and unknown dirty file. A failed item does not stop unrelated work.
Never keep progress in a script's own files. A session that dies and comes back reads
the queue file and continues. This is the multi-project lifecycle on top of
`references/orchestration.md` (work items, briefs, pipeline choice) and
`references/queue.md` (parallel items, one worktree per item, landing).
## Where the ledger lives
Keep state **outside repositories**, under one work root, so it never collides with an
item's worktree or a commit:
${XDG_STATE_HOME:-$HOME/.local/state}/pipelines/work/
registry.json every project this machine knows
projects/<slug>/
queue.md the project's markdown queue: items, briefs, state
notes.md recon, decisions, open questions, blockers
- `<slug>` is `<basename>-<8 hex of sha256(absolute project root)>`. **Resolve a
worktree to its main repository** so every item shares the project's one queue.
- `PIPELINES_WORK_DIR` overrides the work root. `registry.json` maps projects to
roots; add a project the first time it is worked on and keep it current.
- `queue.md` is the resume point (`references/queue.md`): read it top to bottom and
take the first unfinished item. `notes.md` is the operator's record: keep it truthful
about decisions taken and left open, never narrate it as a diary.
- The CLI's configured endpoint and the area map's default pipeline come from the CLI
and the project's own map, not from a script. Do not write a per-project state file
for a script to read.
## Operations
Map one operator sentence to one operation. Do the operation, then answer with the
status block — nothing else. **You launch the runs yourself**; nothing else does it.
| Operator says | Do |
| --- | --- |
| start / work on X | Reconnoitre, register the project, write the queue file, then launch the first item's run yourself. |
| status / how is it going | Read the server and the queue, then print the status block. |
| queue "…" / add … | Reconnoitre, split into small items, append them to the queue file, launch what is ready. |
| pause / stop for now | Launch nothing new. The runs already in flight finish; reconcile them when they do. |
| resume / continue | Reconcile against the server, then launch the next item. |
| drop item N | Mark its item failed in the queue file with a reason. Never silently delete work. |
| done / stop everything | Stop launching, wait for what is in flight, and report what landed and what remains. |
**Reconcile before acting, always.** The server is authoritative for run state; the
queue file is authoritative for intent. On every invocation: read the project's
`queue.md`; for each item marked running, `pipelines inspect <run-id> --json` and settle
it (running → keep waiting; succeeded → verify it landed and mark it done;
failed/interrupted → mark it failed with the diagnostic). Only then do the requested
operation. Never trust your memory of a run's status, and never start a second run for
an item whose request key is already admitted — reuse the original `--request-key` so a
redispatch attaches instead of duplicating.
Status block (these lines, no prose around them):
pipelines — active
queue: 4 pending · 1 running (run 185 · reviewer · 6m) · 12 done · 2 failed
next: 0005-graph-arrows on "TUI"
blocked: none
## The brief, and per-item directives
Write every brief exactly as `references/orchestration.md` describes. An item in
`queue.md` may open its brief with up to three directive lines, stripped before the
prompt is sent:
# pipeline: TUI
# workspace: /path/to/item-worktree
# device: emulator-5556
Goal: …
`pipeline` overrides the default for that item; `workspace` names the item's own
worktree (create it with `git worktree add -b <item> <path> main`, `references/queue.md`);
`device` is for the brief's own text. Number items `0001-…`, `0002-…` so order is
explicit.
## Advancing the queue by hand
There is no driver. You advance the queue yourself, through the CLI:
1. **Read the queue top to bottom** and take the first unfinished item.
2. **Choose the pipeline by area** (`references/orchestration.md`): `Android`, `TUI`,
`Server`, `Generic`, `Plan and land`, `UI sweep`, `Probe`. Each area pipeline reads
the project's own map for its build, test, run and capture commands.
3. **Create the item's worktree and branch**: `git worktree add -b <item> <path> main`.
One worktree per item is what lets independent items run at once without the
workspace guard becoming a bottleneck (`references/queue.md`).
4. **Launch the run from that worktree**:
`pipelines run <pipeline> <brief> --json --yes`. Keep the returned run id.
5. **Be woken when it finishes — do not poll.** `pipelines wait <run-id> […]` blocks
until the runs are terminal and is run as a **background task**, so the session is
woken exactly when the batch finishes — or arm a timer and check on the tick. No
polling loop, no cursor file, no driver script, ever.
6. **Reconcile.** `pipelines inspect <run-id> --json`; read the outcomes and evidence;
verify the branch landed with `git merge-base --is-ancestor <branch> main` (exit 0 =
landed); mark the item in `queue.md`; then start the next item — or several
independent items at once.
**Parallelism is your judgement, bounded by real conflicts only**: two items editing
the same files at once, the one capture device, or the provider's spend cap. Launch as
many independent runs as the machine can carry without overload; serialise only for a
real conflict and say which limit is binding. Never present serialisation as the
operator's decision.
**Landing stays the pipeline's job**: the committer stage merges and lands its own
work. There is no merger, no resolver and nothing to hand to a script. You verify the
landing gate (`references/queue.md`); you do not perform the merge.
## Sleeping and waking
- Before the operator sleeps: reconcile, make sure the queue has enough items to cover
the night, and launch what is ready with a background `pipelines wait`.
- Configure a **failure notification** (`references/notifications.md`) so a failed run
is not silent. A run that fails is recorded and the next item starts; do not add
retry loops to make it look busy.
- On waking, reconcile first, then answer with the status block: what landed, what
failed and why, what is next.
## Conciseness
The operator wants the result, not the shift report.
- Match the answer's length to the question. A yes/no or one-line question gets one or
two sentences; never answer a narrow question with a sectioned report.
- Answer the question that was asked first. Put any extra fact that changes a decision in
a single clause, not in a new section.
- Answer with the status block for status; do not narrate waiting or re-print the
queue when nothing changed.
- Report a run by its outcome and evidence (`references/verification.md`), not the
steps you took to watch it.
- Ask only for a decision the operator owns (accept, publish, restart, install). Batch
the day's questions rather than asking per item.
- Never claim a check, build or screenshot you did not run.
Use background `pipelines wait` for active runs. After completion inspect the
actual outcome and advance the work, not just announce that it stopped.
Report concise results, blockers needing a decision and exact next actions.
+49 -5
View File
@@ -37,6 +37,7 @@ type App struct {
type options struct {
harness string
url, name, prompt, title, template, workspace, paths, key, opencode, model string
retryMode, retryStage, retryInputFile string
option, feedback, evidence, actor string
output string
conflict string
@@ -46,7 +47,7 @@ type options struct {
keepSet bool
all bool
json, source, noOpen, yes, allow, createOnly, force, wait bool
version, expected, limit, recoverySequence int
version, expected, limit, recoverySequence, retryVisit int
recoveryRun int64
recoveryStage, resource string
timeout, waitTimeout time.Duration
@@ -162,6 +163,11 @@ func (a App) flags(command string) (*flag.FlagSet, *options) {
f.StringVar(&o.key, "request-key", "", "Idempotency key (default: generated unique key)")
f.BoolVar(&o.wait, "wait", false, "Wait for the new run to finish")
f.DurationVar(&o.waitTimeout, "wait-timeout", 0, "Client limit for --wait (0 waits until the run ends); independent of --timeout")
f.StringVar(&o.retryMode, "mode", "resume", "Retry mode: resume failed stage or restart from entry")
f.StringVar(&o.retryStage, "stage", "", "Retry this recorded stage (required when it was visited more than once)")
f.IntVar(&o.retryVisit, "visit", 0, "1-based occurrence of --stage in the recorded execution")
f.IntVar(&o.version, "version", 0, "Explicit published version of the same pipeline (default: source version)")
f.StringVar(&o.retryInputFile, "input-file", "", "JSON object merged into the selected stage input; '-' reads stdin")
case "cancel", "draft-delete":
f.BoolVar(&o.yes, "yes", false, "Confirm this action without an interactive prompt")
case "retention":
@@ -983,17 +989,55 @@ func (a App) Run(ctx context.Context, args []string) error {
}
typeName = protocol.RetryRun
key = o.key
if o.retryMode != "resume" && o.retryMode != "restart" {
return fmt.Errorf("--mode must be resume or restart")
}
if key == "" {
key = fmt.Sprintf("retry-%d-%d", os.Getpid(), time.Now().UnixNano())
}
var retryInput map[string]any
if o.retryInputFile != "" {
var data []byte
if o.retryInputFile == "-" {
input := a.In
if input == nil {
input = os.Stdin
}
data, err = io.ReadAll(io.LimitReader(input, 64*1024+1))
} else {
var file *os.File
file, err = os.Open(o.retryInputFile)
if err == nil {
data, err = io.ReadAll(io.LimitReader(file, 64*1024+1))
_ = file.Close()
}
}
if err != nil {
return err
}
if len(data) > 64*1024 {
return fmt.Errorf("retry input exceeds 65536 bytes")
}
if err := json.Unmarshal(data, &retryInput); err != nil {
return fmt.Errorf("invalid retry input JSON: %w", err)
}
if retryInput == nil {
return fmt.Errorf("retry input must be a JSON object")
}
}
if o.retryVisit < 0 {
return fmt.Errorf("--visit must be positive")
}
r, err := call(protocol.Message{Type: typeName, RunID: id, RequestKey: key, RetryMode: o.retryMode, RetryStage: o.retryStage, RetryVisit: o.retryVisit, RetryVersion: o.version, RetryInput: retryInput})
if err != nil {
return err
}
return a.finishRun(ctx, r, o, call)
}
r, err := call(protocol.Message{Type: typeName, RunID: id, RequestKey: key})
r, err := call(protocol.Message{Type: typeName, RunID: id, RequestKey: key, RetryMode: o.retryMode})
if err != nil {
return err
}
if command == "retry" {
return a.finishRun(ctx, r, o, call)
}
return a.output(r.RunDetail)
case "decide":
if len(pos) < 1 || len(pos) > 2 {
+2 -2
View File
@@ -23,7 +23,7 @@ var usage = map[string]string{
"wait": "wait <run-id> [run-id ...] [--timeout DURATION] [--json]",
"cancel": "cancel <run-id> [--json]",
"decide": "decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]",
"retry": "retry <run-id> [--json [--wait [--wait-timeout DURATION]]]",
"retry": "retry <run-id> [--mode resume|restart] [--stage KEY [--visit N]] [--version N] [--input-file FILE|-] [--json [--wait [--wait-timeout DURATION]]]",
"title": "title <run-id> \"<title>\" [--json]",
"debug": "debug <run-id> [--json | --no-open]",
"chat-adopt": "chat-adopt <session-id> [--json]",
@@ -51,7 +51,7 @@ var notes = map[string]string{
"validate": "Uses the same server parser as submission. Does not persist or activate schedules. Structural validity does not prove runtime/tool availability.",
"submit": "Confirm publication at the prompt, or use --yes for explicit automation; schedules activate on acceptance. Managed drafts provide the name and base-version guard. --force never bypasses validation.",
"run": "Runs in your current directory after action confirmation (--yes skips it). Select a pipeline and compose a multiline task with Ctrl+S. Stage tools are enabled automatically; no file list or typed RUN confirmation. Cancellation does not undo edits. --title sets an explicit run title; without it the title is derived from the prompt. --model PROVIDER/MODEL overrides the model for every stage of that run; --stage-model STAGE=PROVIDER/MODEL overrides one stage and is repeatable, with a repeated key last-wins. Precedence is per-stage > whole-run > the model pinned in the pipeline version; overrides apply to that run only and never change the pinned definition. An unknown stage key or a malformed provider/model is refused before the run starts, naming the valid stage keys. In JSON mode --wait polls until terminal; --wait-timeout bounds only the client wait after admission and is independent of per-request --timeout. A reached wait limit leaves the run active: inspect read-only with `inspect <run-id> --json`, or reattach with --wait reusing the original --request-key (never an automatic replay or cancel).",
"retry": "Start a new attempt of a failed run with the same initial input, directory, pipeline version, and edit scope. Original history is retained. Already-completed side effects are not undone. --wait/--wait-timeout behave as for run: a reached wait limit leaves the new run active; inspect read-only with `inspect <run-id> --json`, or reattach with --wait and the original --request-key instead of starting a duplicate retry.",
"retry": "Resume a failed stage by default, restoring the completed prefix handoff; use --mode=restart to start at entry. --stage selects a recorded stage (use --visit for repeated stages). --input-file accepts a bounded JSON object, merged with replacement at the selected stage; '-' reads stdin. Original history and pinned identity are retained; --version selects an explicit published version of the same pipeline only. --wait-timeout leaves an active retry for later read-only inspection or reattachment with the original --request-key, rather than starting a duplicate retry.",
"title": "Rename a run's operator-facing title after the fact without touching its input, steps or execution. The title is collapsed to a single bounded line and recorded as explicitly set. `pipelines runs` and `pipelines inspect` then show it.",
"wait": "Block until each named run reaches a terminal status - succeeded, failed, canceled or interrupted, and also through a run waiting on a person - then print one line per run with its id, status and outcome, its stage and how long it took, and exit 0 even for a run that finished unsuccessfully. Several ids wait together in one command. The exit is non-zero only for a client-side failure: an unknown run id, a connection that could not be established, or --timeout expiring while a run is still active; a timeout says so plainly, never cancels, retries or otherwise touches a run, and is never reported as its outcome. Read-only: it needs no workspace, is not refused by the workspace guard and writes nothing. --json prints the final run envelope instead of the line (one envelope for one id, an array for several).",
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
+1 -1
View File
@@ -29,7 +29,7 @@ EXECUTE
wait <run-id> ... Block until runs finish, then report each (read-only)
cancel <run-id> Cancel a run; changes are NOT rolled back
decide <run-id> [stage] Choose an option for a run waiting on a person
retry <run-id> Restart a failed run with its original input and directory
retry <run-id> Resume a failed stage (use --mode=restart for a full restart)
title <run-id> "<title>" Rename a run after the fact; input/steps unchanged
debug <run-id> Investigate a run with a configured harness or nvim
chat-adopt <session-id> Adopt an existing OpenCode session into chat_sessions
+15 -7
View File
@@ -183,11 +183,6 @@ func Capture(ctx context.Context, directory string, previous ...*Snapshot) *Snap
s.skipped[name] = true
continue
}
if used+int(info.Size()) > maxSnapshotBytes {
s.skipped[name] = true
s.partial = true
continue
}
f, err := root.OpenFile(name, os.O_RDONLY|syscall.O_NONBLOCK|syscall.O_NOFOLLOW, 0)
if err != nil {
s.skipped[name] = true
@@ -205,9 +200,22 @@ func Capture(ctx context.Context, directory string, previous ...*Snapshot) *Snap
s.skipped[name] = true
continue
}
used += len(data)
binary := bytes.IndexByte(data, 0) >= 0 || !utf8.Valid(data)
s.files[name] = file{data: data, hash: sha256.Sum256(data), mode: opened.Mode().Perm(), binary: binary}
hash := sha256.Sum256(data)
// Binary changes need only metadata and a hash, never retained patch bytes.
// Counting screenshots against the retained-text budget can otherwise
// exhaust it before any source files are reached in sorted inventory order.
if binary {
data = nil
} else {
if used+len(data) > maxSnapshotBytes {
s.skipped[name] = true
s.partial = true
continue
}
used += len(data)
}
s.files[name] = file{data: data, hash: hash, mode: opened.Mode().Perm(), binary: binary}
}
return s
}
+28
View File
@@ -2,6 +2,7 @@ package filediff
import (
"context"
"fmt"
"os"
"os/exec"
"path/filepath"
@@ -161,3 +162,30 @@ func TestPatchLimits(t *testing.T) {
t.Fatal(c)
}
}
func TestBinaryFilesDoNotStarveSourceDiffs(t *testing.T) {
dir := t.TempDir()
ctx := context.Background()
image := "\x00" + strings.Repeat("x", maxFileBytes-1)
for i := 0; i <= maxSnapshotBytes/maxFileBytes; i++ {
put(t, dir, fmt.Sprintf("image-%03d.png", i), image)
}
put(t, dir, "source.go", "before\n")
before := Capture(ctx, dir)
put(t, dir, "source.go", "after\n")
put(t, dir, "image-000.png", "\x00changed")
changes := Compare(before, Capture(ctx, dir, before))
if changes.Status != "complete" || len(changes.Files) != 2 {
t.Fatalf("binary inventory hid source changes: %+v", changes)
}
for _, change := range changes.Files {
if change.Path == "source.go" && !strings.Contains(change.Patch, "+after") {
t.Fatal("source patch missing", change)
}
}
for name, f := range before.files {
if f.binary && len(f.data) != 0 {
t.Fatalf("binary bytes unnecessarily retained for %s", name)
}
}
}
+83 -1
View File
@@ -33,6 +33,10 @@ type Chat struct {
conn *Connection
shellMu sync.Mutex
shells map[string]*ChatStreamState
// shellOwners retains ownership from the last authoritative global shell
// listing so a shell known to belong to another session is rejected before
// its detail or output endpoint is queried.
shellOwners map[string]string
// mu serializes the adapter's HTTP calls. Connection records its last
// operation and status on the shared connection, so two calls must not
// overlap; the permission poller runs alongside the read loop's
@@ -50,6 +54,21 @@ func NewChat(conn *Connection) *Chat { return &Chat{conn: conn} }
// chat adapter and callers that must reject a request before any OpenCode call.
func ValidSessionID(id string) bool { return sessionID.MatchString(id) }
// ValidShellID accepts only the provider's opaque shell-id alphabet. Keeping
// this check shared by the websocket boundary and provider adapter ensures an
// invalid id is rejected before either network call or path construction.
func ValidShellID(id string) bool {
if len(id) <= 3 || len(id) > 128 || !strings.HasPrefix(id, "sh_") {
return false
}
for _, c := range id[3:] {
if (c < 'a' || c > 'z') && (c < 'A' || c > 'Z') && (c < '0' || c > '9') && c != '_' && c != '-' {
return false
}
}
return true
}
// call serializes the adapter's HTTP calls and forwards them through the shared
// Connection, so no second transport is introduced and Connection's recorded
// last operation/status is never written by two goroutines at once.
@@ -390,9 +409,19 @@ func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShe
return nil, fmt.Errorf("invalid OpenCode shell response")
}
}
c.shellMu.Lock()
if c.shellOwners == nil {
c.shellOwners = make(map[string]string)
}
for _, info := range response.Data {
if ValidShellID(info.ID) && ValidSessionID(info.shellSessionID()) {
c.shellOwners[info.ID] = info.shellSessionID()
}
}
c.shellMu.Unlock()
out := make([]protocol.ChatShell, 0, len(response.Data))
for _, info := range response.Data {
if info.ID == "" || info.shellSessionID() != sessionID || (info.Status != "" && info.Status != protocol.ChatShellRunning) {
if info.ID == "" || info.shellSessionID() != sessionID || (info.Status != "" && info.Status != protocol.ChatShellRunning && info.Status != protocol.ChatShellExited) {
continue
}
status := info.Status
@@ -418,6 +447,58 @@ func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShe
return out, nil
}
// ShellOutput validates explicit session metadata from the authoritative detail
// record before reading the selected bounded output page. A shared directory is
// never ownership evidence.
func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) {
if !ValidSessionID(query.SessionID) || !ValidShellID(query.ShellID) || query.Cursor < 0 || query.Cursor > protocol.ChatShellOutputMaxCursor || query.Limit <= 0 || query.Limit > protocol.ChatShellOutputLimit {
return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid shell output query")
}
c.shellMu.Lock()
owner := c.shellOwners[query.ShellID]
c.shellMu.Unlock()
if owner != "" && owner != query.SessionID {
return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session")
}
data, err := c.call(ctx, "get", "/api/shell/"+query.ShellID, nil)
if err != nil {
if c.conn.LastHTTPStatus == 404 {
return protocol.ChatShellOutputPage{Unavailable: true}, nil
}
return protocol.ChatShellOutputPage{}, err
}
var detail struct {
Data chatShellInfo `json:"data"`
}
if err := json.Unmarshal(data, &detail); err != nil || detail.Data.ID != query.ShellID || detail.Data.shellSessionID() != query.SessionID || (detail.Data.Status != "" && detail.Data.Status != protocol.ChatShellRunning && detail.Data.Status != protocol.ChatShellExited) {
return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session")
}
shell := protocol.ChatShell{ID: detail.Data.ID, Status: detail.Data.Status, Command: detail.Data.Command, Exit: detail.Data.Exit}
if shell.Status == "" {
shell.Status = protocol.ChatShellRunning
}
path := fmt.Sprintf("/api/shell/%s/output?cursor=%d&limit=%d", query.ShellID, query.Cursor, query.Limit)
data, err = c.call(ctx, "get", path, nil)
if err != nil {
if c.conn.LastHTTPStatus == 404 {
return protocol.ChatShellOutputPage{Shell: shell, Unavailable: true}, nil
}
return protocol.ChatShellOutputPage{}, err
}
var response struct {
Data *struct {
Output *string `json:"output"`
Cursor *int64 `json:"cursor"`
Size *int64 `json:"size"`
Truncated *bool `json:"truncated"`
} `json:"data"`
}
if err := json.Unmarshal(data, &response); err != nil || response.Data == nil || response.Data.Output == nil || response.Data.Cursor == nil || response.Data.Size == nil || response.Data.Truncated == nil || len(*response.Data.Output) > query.Limit || *response.Data.Cursor < query.Cursor || *response.Data.Cursor > protocol.ChatShellOutputMaxCursor || *response.Data.Size < *response.Data.Cursor || *response.Data.Size > protocol.ChatShellOutputMaxCursor || *response.Data.Cursor-query.Cursor != int64(len(*response.Data.Output)) {
return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid OpenCode shell output response")
}
return protocol.ChatShellOutputPage{Shell: shell, Output: *response.Data.Output, Cursor: *response.Data.Cursor, Size: *response.Data.Size, Truncated: *response.Data.Truncated}, nil
}
// streamState returns the session's retained, verified shell identities. It is
// deliberately kept across stream replacement so an exit after reconnect remains
// attributable; Shells reconciles its contents from authoritative readback on
@@ -592,6 +673,7 @@ type chatShellInfo struct {
ID string `json:"id"`
Status string `json:"status"`
Command string `json:"command"`
Exit *int `json:"exit"`
Metadata map[string]any `json:"metadata"`
}
+52
View File
@@ -7,6 +7,7 @@ import (
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"testing"
"time"
@@ -425,6 +426,57 @@ func TestChatShellReadbackSeedsReplacementStream(t *testing.T) {
}
}
func TestChatShellOutputVerifiesOwnerAndBoundsPage(t *testing.T) {
var outputPath string
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
switch r.URL.Path {
case "/api/shell/sh_1":
_, _ = w.Write([]byte(`{"data":{"id":"sh_1","status":"exited","command":"job","metadata":{"sessionID":"ses_1"}}}`))
case "/api/shell/sh_1/output":
outputPath = r.URL.RawQuery
_, _ = w.Write([]byte(`{"data":{"output":"marker","cursor":6,"size":6,"truncated":false}}`))
default:
http.NotFound(w, r)
}
}))
defer srv.Close()
page, err := NewChat(&Connection{Backend: "v2", URL: srv.URL}).ShellOutput(context.Background(), protocol.ChatShellOutputQuery{SessionID: "ses_1", ShellID: "sh_1", Limit: 64 << 10})
if err != nil || page.Output != "marker" || page.Shell.Status != protocol.ChatShellExited {
t.Fatalf("ShellOutput = %+v, %v", page, err)
}
if !strings.Contains(outputPath, "cursor=0") || !strings.Contains(outputPath, "limit=65536") {
t.Fatalf("output query = %q", outputPath)
}
}
func TestChatShellOutputRejectsMissingRequiredPageFields(t *testing.T) {
for _, body := range []string{
`{"data":{}}`,
`{"data":{"output":"","cursor":0,"size":0}}`,
`{"data":{"output":"","size":0,"truncated":false}}`,
`{"data":{"output":"","cursor":0,"truncated":false}}`,
} {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
switch r.URL.Path {
case "/api/shell/sh_1":
_, _ = w.Write([]byte(`{"data":{"id":"sh_1","status":"running","metadata":{"sessionID":"ses_1"}}}`))
case "/api/shell/sh_1/output":
_, _ = w.Write([]byte(body))
default:
http.NotFound(w, r)
}
}))
chat := NewChat(&Connection{Backend: "v2", URL: srv.URL})
_, err := chat.ShellOutput(context.Background(), protocol.ChatShellOutputQuery{SessionID: "ses_1", ShellID: "sh_1", Limit: 1})
srv.Close()
if err == nil {
t.Fatalf("response %s was accepted", body)
}
}
}
func TestChatReleaseShellsBoundsDisconnectedState(t *testing.T) {
chat := NewChat(&Connection{})
state := chat.streamState("ses_1")
+7 -2
View File
@@ -45,8 +45,8 @@ func decodeControl(text string, value any) error {
func parseControl(s *Stage, fields map[string]string) error {
if text, ok := fields["resources"]; ok {
if err := decodeControl(text, &s.Resources); err != nil || s.Resources == nil || !ValidResourceKey(s.Resources.Exclusive) {
return fmt.Errorf("resources must contain exactly one exclusive key (1–128 ASCII letters, digits, _ or -; start with a letter)")
if err := decodeControl(text, &s.Resources); err != nil || s.Resources == nil || !validStageResources(*s.Resources) {
return fmt.Errorf("resources must contain exactly one exclusive or pool key (1–128 ASCII letters, digits, _ or -; start with a letter)")
}
delete(fields, "resources")
}
@@ -81,6 +81,11 @@ func parseControl(s *Stage, fields map[string]string) error {
return nil
}
func validStageResources(resources protocol.StageResources) bool {
return (ValidResourceKey(resources.Exclusive) && resources.Pool == "") ||
(resources.Exclusive == "" && ValidResourceKey(resources.Pool))
}
func validateControl(s Stage, stages map[string]bool) error {
if s.Resources != nil && s.Type == "human" {
return fmt.Errorf("stage %s: human stages cannot declare resources", s.Key)
+300 -14
View File
@@ -193,7 +193,213 @@ type ResourceVisit struct {
// or serializable, and must never be put in model input or public wire metadata.
type ResourceLease struct {
ResourceVisit
token string
Target *protocol.ResourceTarget
pool string
token string
}
const maxPoolMembers = 32
const maxTargetMetadata = 16
const maxTargetMetadataKey = 128
const maxTargetValue = 128
func validateTargetMetadata(metadata map[string]string) error {
if len(metadata) > maxTargetMetadata {
return fmt.Errorf("too many target metadata fields")
}
for k, v := range metadata {
if !identifier.MatchString(k) || len(k) > maxTargetMetadataKey || len(v) > maxTargetValue || !utf8.ValidString(v) {
return fmt.Errorf("invalid target metadata")
}
}
return nil
}
func validateResourcePool(name string, members []protocol.ResourcePoolMember) error {
if !ValidResourceKey(name) || len(members) == 0 || len(members) > maxPoolMembers {
return fmt.Errorf("invalid resource pool")
}
seen := make(map[string]bool, len(members))
for i := range members {
member := &members[i]
if !ValidResourceKey(member.Member) || seen[member.Member] {
return fmt.Errorf("invalid pool member")
}
if err := validateTargetMetadata(member.Metadata); err != nil {
return err
}
seen[member.Member] = true
}
return nil
}
// ConfigureResourcePool replaces a pool declaration atomically. Existing
// owners keep their concrete member; queued requests are evaluated against the
// new declaration on the next release and are never silently transferred.
func (s *Store) ConfigureResourcePool(ctx context.Context, pool protocol.ResourcePool) error {
if err := validateResourcePool(pool.Name, pool.Members); err != nil {
return err
}
encoded, err := json.Marshal(pool.Members)
if err != nil {
return err
}
s.resourceMu.Lock()
defer s.resourceMu.Unlock()
_, err = s.db.ExecContext(ctx, `INSERT INTO resource_pools(name,members_json) VALUES(?,?) ON CONFLICT(name) DO UPDATE SET members_json=excluded.members_json,updated_at=CURRENT_TIMESTAMP`, pool.Name, string(encoded))
return err
}
func (s *Store) resourcePool(ctx context.Context, tx interface {
QueryRowContext(context.Context, string, ...any) *sql.Row
}, name string) ([]protocol.ResourcePoolMember, error) {
var encoded string
if err := tx.QueryRowContext(ctx, "SELECT members_json FROM resource_pools WHERE name=?", name).Scan(&encoded); err != nil {
return nil, err
}
var members []protocol.ResourcePoolMember
if err := json.Unmarshal([]byte(encoded), &members); err != nil {
return nil, fmt.Errorf("invalid persisted pool: %w", err)
}
if err := validateResourcePool(name, members); err != nil {
return nil, fmt.Errorf("invalid persisted pool: %w", err)
}
return members, nil
}
func poolTarget(member protocol.ResourcePoolMember) *protocol.ResourceTarget {
metadata := make(map[string]string, len(member.Metadata))
for k, v := range member.Metadata {
metadata[k] = v
}
return &protocol.ResourceTarget{Member: member.Member, Metadata: metadata}
}
// RequestResourcePool selects one free eligible concrete member while holding
// the same authority as direct resource requests.
func (s *Store) RequestResourcePool(ctx context.Context, pool string, visit ResourceVisit) (ResourceLease, <-chan ResourceLease, *protocol.ResourceWait, error) {
if !ValidResourceKey(pool) || visit.Resource != pool || visit.RunID <= 0 || visit.Sequence <= 0 || !identifier.MatchString(visit.Stage) {
return ResourceLease{}, nil, nil, fmt.Errorf("invalid resource pool visit")
}
s.resourceMu.Lock()
defer s.resourceMu.Unlock()
if ch := s.resourceWaiters[visit]; ch != nil {
wait, err := s.resourceWait(ctx, visit.RunID)
return ResourceLease{}, ch, wait, err
}
credential := make([]byte, 32)
if _, err := rand.Read(credential); err != nil {
return ResourceLease{}, nil, nil, err
}
lease := ResourceLease{ResourceVisit: visit, token: hex.EncodeToString(credential)}
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
return ResourceLease{}, nil, nil, err
}
defer tx.Rollback()
var status string
if err := tx.QueryRowContext(ctx, "SELECT status FROM pipeline_runs WHERE id=?", visit.RunID).Scan(&status); err != nil {
return ResourceLease{}, nil, nil, err
}
if status != protocol.RunStatusQueued && status != protocol.RunStatusRunning {
return ResourceLease{}, nil, nil, fmt.Errorf("run is not active")
}
var existing ResourceLease
var existingPool string
err = tx.QueryRowContext(ctx, "SELECT resource_key,run_id,stage_key,sequence,token,pool_name FROM resource_owners WHERE run_id=?", visit.RunID).Scan(&existing.Resource, &existing.RunID, &existing.Stage, &existing.Sequence, &existing.token, &existingPool)
if err == nil {
if existing.RunID != visit.RunID || existing.Stage != visit.Stage || existing.Sequence != visit.Sequence {
return ResourceLease{}, nil, nil, fmt.Errorf("resource owner visit is stale")
}
if existingPool != pool {
return ResourceLease{}, nil, nil, fmt.Errorf("resource owner pool visit is stale")
}
members, poolErr := s.resourcePool(ctx, tx, pool)
if poolErr != nil {
return ResourceLease{}, nil, nil, fmt.Errorf("unknown resource pool: %w", poolErr)
}
for _, member := range members {
if member.Member == existing.Resource {
existing.ResourceVisit = visit
existing.pool = pool
existing.Target = poolTarget(member)
return existing, nil, nil, nil
}
}
return ResourceLease{}, nil, nil, fmt.Errorf("run already owns another resource visit")
}
if err != sql.ErrNoRows {
return ResourceLease{}, nil, nil, err
}
// A queued visit may be re-entered after the process that owned its live
// channel was restarted. Reattach to the durable waiter instead of trying
// to insert a second reservation.
var persistedPool string
err = tx.QueryRowContext(ctx, "SELECT pool_name FROM resource_waiters WHERE run_id=? AND stage_key=? AND sequence=?", visit.RunID, visit.Stage, visit.Sequence).Scan(&persistedPool)
if err == nil {
if persistedPool != pool {
return ResourceLease{}, nil, nil, fmt.Errorf("resource waiter pool visit is stale")
}
wait, waitErr := s.resourceWait(ctx, visit.RunID)
if waitErr != nil {
return ResourceLease{}, nil, nil, waitErr
}
if s.resourceWaiters == nil {
s.resourceWaiters = make(map[ResourceVisit]chan ResourceLease)
}
ch := make(chan ResourceLease, 1)
s.resourceWaiters[visit] = ch
return ResourceLease{}, ch, wait, nil
}
if err != sql.ErrNoRows {
return ResourceLease{}, nil, nil, err
}
members, err := s.resourcePool(ctx, tx, pool)
if err != nil {
return ResourceLease{}, nil, nil, fmt.Errorf("unknown resource pool: %w", err)
}
for _, member := range members {
if !member.Enabled || member.Quarantined {
continue
}
var count int
if err := tx.QueryRowContext(ctx, "SELECT COUNT(*) FROM resource_owners WHERE resource_key=?", member.Member).Scan(&count); err != nil {
return ResourceLease{}, nil, nil, err
}
if count != 0 {
continue
}
if _, err := tx.ExecContext(ctx, `INSERT INTO resource_owners(resource_key,run_id,stage_key,sequence,token,pool_name) VALUES(?,?,?,?,?,?)`, member.Member, visit.RunID, visit.Stage, visit.Sequence, lease.token, pool); err != nil {
return ResourceLease{}, nil, nil, err
}
lease.Resource = member.Member
lease.pool = pool
lease.Target = poolTarget(member)
if err := tx.Commit(); err != nil {
return ResourceLease{}, nil, nil, err
}
return lease, nil, nil, nil
}
wait := &protocol.ResourceWait{Resource: pool, Stage: visit.Stage, Sequence: visit.Sequence, QueuedSince: time.Now().UTC().Format(time.RFC3339Nano)}
encoded, err := json.Marshal(wait)
if err != nil {
return ResourceLease{}, nil, nil, err
}
if _, err := tx.ExecContext(ctx, `INSERT INTO resource_waiters(resource_key,pool_name,run_id,stage_key,sequence,token,queued_at) VALUES(?,?,?,?,?,?,?)`, pool, pool, visit.RunID, visit.Stage, visit.Sequence, lease.token, wait.QueuedSince); err != nil {
return ResourceLease{}, nil, nil, err
}
if err := affected(tx.ExecContext(ctx, "UPDATE pipeline_runs SET status='queued',current_stage=?,resource_wait=? WHERE id=? AND status IN ('queued','running')", visit.Stage, string(encoded), visit.RunID)); err != nil {
return ResourceLease{}, nil, nil, err
}
if err := tx.Commit(); err != nil {
return ResourceLease{}, nil, nil, err
}
if s.resourceWaiters == nil {
s.resourceWaiters = make(map[ResourceVisit]chan ResourceLease)
}
ch := make(chan ResourceLease, 1)
s.resourceWaiters[visit] = ch
return ResourceLease{}, ch, wait, nil
}
// RequestResource acquires immediately or registers one FIFO waiter/channel. The
@@ -226,8 +432,12 @@ func (s *Store) RequestResource(ctx context.Context, visit ResourceVisit) (Resou
return ResourceLease{}, nil, nil, fmt.Errorf("run is not active")
}
var existing ResourceLease
err = tx.QueryRowContext(ctx, "SELECT resource_key,run_id,stage_key,sequence,token FROM resource_owners WHERE run_id=?", visit.RunID).Scan(&existing.Resource, &existing.RunID, &existing.Stage, &existing.Sequence, &existing.token)
var existingPool string
err = tx.QueryRowContext(ctx, "SELECT resource_key,run_id,stage_key,sequence,token,pool_name FROM resource_owners WHERE run_id=?", visit.RunID).Scan(&existing.Resource, &existing.RunID, &existing.Stage, &existing.Sequence, &existing.token, &existingPool)
if err == nil {
if existingPool != "" {
return ResourceLease{}, nil, nil, fmt.Errorf("run already owns a pooled resource visit")
}
if existing.ResourceVisit != visit {
return ResourceLease{}, nil, nil, fmt.Errorf("run already owns another resource visit")
}
@@ -236,8 +446,8 @@ func (s *Store) RequestResource(ctx context.Context, visit ResourceVisit) (Resou
if err != sql.ErrNoRows {
return ResourceLease{}, nil, nil, err
}
result, err := tx.ExecContext(ctx, `INSERT INTO resource_owners(resource_key,run_id,stage_key,sequence,token)
VALUES(?,?,?,?,?) ON CONFLICT(resource_key) DO NOTHING`, visit.Resource, visit.RunID, visit.Stage, visit.Sequence, lease.token)
result, err := tx.ExecContext(ctx, `INSERT INTO resource_owners(resource_key,run_id,stage_key,sequence,token,pool_name)
VALUES(?,?,?,?,?,?) ON CONFLICT(resource_key) DO NOTHING`, visit.Resource, visit.RunID, visit.Stage, visit.Sequence, lease.token, "")
if err != nil {
return ResourceLease{}, nil, nil, err
}
@@ -349,11 +559,18 @@ func (s *Store) ConfirmRecoveredSession(ctx context.Context, owner SessionOwner)
// SetResourceCleanup records positive quiescence durably before release. False
// quarantines the owner; neither age nor another run can remove the lease.
func (s *Store) SetResourceCleanup(ctx context.Context, lease ResourceLease, confirmed bool) error {
if lease.pool != "" && (lease.Target == nil || !ValidResourceKey(lease.Target.Member)) {
return fmt.Errorf("invalid pooled resource lease")
}
diagnostic := ""
if !confirmed {
diagnostic = "Cleanup/restoration unconfirmed; resource quarantined pending inspected reconciliation"
}
return affected(s.db.ExecContext(ctx, `UPDATE resource_owners SET cleanup_confirmed=?,diagnostic=? WHERE resource_key=? AND run_id=? AND stage_key=? AND sequence=? AND token=?`, confirmed, diagnostic, lease.Resource, lease.RunID, lease.Stage, lease.Sequence, lease.token))
resource := lease.Resource
if lease.pool != "" {
resource = lease.Target.Member
}
return affected(s.db.ExecContext(ctx, `UPDATE resource_owners SET cleanup_confirmed=?,diagnostic=? WHERE resource_key=? AND run_id=? AND stage_key=? AND sequence=? AND token=?`, confirmed, diagnostic, resource, lease.RunID, lease.Stage, lease.Sequence, lease.token))
}
// ReleaseResource requires the complete capability AND positive cleanup evidence.
@@ -370,6 +587,14 @@ func (s *Store) releaseResourceLocked(ctx context.Context, lease ResourceLease)
return err
}
defer tx.Rollback()
ownerResource := lease.Resource
if lease.pool != "" {
if lease.Target == nil || !ValidResourceKey(lease.Target.Member) {
return fmt.Errorf("invalid pooled resource lease")
}
ownerResource = lease.Target.Member
}
lease.Resource = ownerResource
n, err := deleteResourceOwner(ctx, tx, lease)
if err != nil {
return err
@@ -377,7 +602,7 @@ func (s *Store) releaseResourceLocked(ctx context.Context, lease ResourceLease)
if n == 0 {
return nil
}
next, err := s.handoffResourceTx(ctx, tx, lease.Resource)
next, err := s.handoffResourceTx(ctx, tx, ownerResource)
if err != nil {
return err
}
@@ -396,25 +621,86 @@ func (s *Store) releaseResourceLocked(ctx context.Context, lease ResourceLease)
func (s *Store) handoffResourceTx(ctx context.Context, tx *sql.Tx, resource string) (ResourceLease, error) {
var next ResourceLease
next.Resource = resource
err := tx.QueryRowContext(ctx, `SELECT run_id,stage_key,sequence,token FROM resource_waiters WHERE resource_key=? ORDER BY queue_order LIMIT 1`, resource).Scan(&next.RunID, &next.Stage, &next.Sequence, &next.token)
if err == sql.ErrNoRows {
return ResourceLease{}, nil
}
rows, err := tx.QueryContext(ctx, `SELECT queue_order,resource_key,pool_name,run_id,stage_key,sequence,token FROM resource_waiters WHERE resource_key=? OR pool_name<>'' ORDER BY queue_order`, resource)
if err != nil {
return ResourceLease{}, err
}
if s.resourceWaiters[next.ResourceVisit] == nil {
return ResourceLease{}, fmt.Errorf("resource waiter has no live runner; refusing handoff")
defer rows.Close()
var selected *protocol.ResourceTarget
var queue int64
var waiterResource string
for rows.Next() {
var candidate ResourceLease
var candidatePool string
if err := rows.Scan(&queue, &waiterResource, &candidatePool, &candidate.RunID, &candidate.Stage, &candidate.Sequence, &candidate.token); err != nil {
return ResourceLease{}, err
}
if candidatePool != "" {
candidate.Resource = candidatePool
candidate.pool = candidatePool
} else {
candidate.Resource = resource
}
if candidatePool == "" {
if waiterResource != resource {
continue
}
selected = &protocol.ResourceTarget{Member: resource}
} else {
members, e := s.resourcePool(ctx, tx, candidatePool)
if e != nil {
continue
}
found := false
for _, member := range members {
if !member.Enabled || member.Quarantined {
continue
}
var count int
if e = tx.QueryRowContext(ctx, "SELECT COUNT(*) FROM resource_owners WHERE resource_key=?", member.Member).Scan(&count); e != nil {
return ResourceLease{}, e
}
if count == 0 {
selected, found = poolTarget(member), true
break
}
}
if !found {
continue
}
}
if s.resourceWaiters[candidate.ResourceVisit] == nil {
if candidatePool == "" {
return ResourceLease{}, fmt.Errorf("resource waiter has no live runner; refusing handoff")
}
continue
}
next = candidate
next.Target = selected
break
}
if _, err := tx.ExecContext(ctx, `INSERT INTO resource_owners(resource_key,run_id,stage_key,sequence,token) VALUES(?,?,?,?,?)`, next.Resource, next.RunID, next.Stage, next.Sequence, next.token); err != nil {
if err := rows.Err(); err != nil {
return ResourceLease{}, err
}
if _, err := tx.ExecContext(ctx, `DELETE FROM resource_waiters WHERE run_id=?`, next.RunID); err != nil {
if next.token == "" {
return ResourceLease{}, nil
}
ownerResource := next.Resource
if next.pool != "" {
ownerResource = next.Target.Member
}
if _, err := tx.ExecContext(ctx, `INSERT INTO resource_owners(resource_key,run_id,stage_key,sequence,token,pool_name) VALUES(?,?,?,?,?,?)`, ownerResource, next.RunID, next.Stage, next.Sequence, next.token, next.pool); err != nil {
return ResourceLease{}, err
}
if _, err := tx.ExecContext(ctx, `DELETE FROM resource_waiters WHERE queue_order=?`, queue); err != nil {
return ResourceLease{}, err
}
if _, err := tx.ExecContext(ctx, "UPDATE pipeline_runs SET resource_wait='' WHERE id=?", next.RunID); err != nil {
return ResourceLease{}, err
}
if next.pool == "" {
next.Resource = ownerResource
}
return next, nil
}
+249
View File
@@ -39,6 +39,255 @@ func TestResourceDeclaration(t *testing.T) {
}
}
func TestResourcePoolDeclaration(t *testing.T) {
base := Template([]string{"work"}, true)
graph, err := Parse(base + "```resources\n{\"pool\":\"android-targets\"}\n```\n")
if err != nil || graph.Stages[0].Resources == nil || graph.Stages[0].Resources.Pool != "android-targets" {
t.Fatalf("pool declaration: %#v, %v", graph.Stages[0].Resources, err)
}
for _, value := range []string{`{"exclusive":"phone","pool":"targets"}`, `{"pool":""}`, `{"pool":"a b"}`} {
if _, err := Parse(base + "```resources\n" + value + "\n```\n"); err == nil {
t.Fatalf("accepted invalid pool declaration %s", value)
}
}
}
func TestResourcePoolAllocatesConcreteMembersAndExcludesDirectOwner(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
if err := s.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "android-targets", Members: []protocol.ResourcePoolMember{
{Member: "phone", Enabled: true, Metadata: map[string]string{"kind": "phone"}},
{Member: "emulator", Enabled: true, Metadata: map[string]string{"kind": "emulator"}},
}}); err != nil {
t.Fatal(err)
}
phone := acquireTestResource(t, s, create("phone"))
visit := create("android-targets")
lease, ch, _, err := s.RequestResourcePool(ctx, "android-targets", visit)
if err != nil || ch != nil || lease.Target == nil || lease.Target.Member != "emulator" {
t.Fatalf("pool selected %#v, channel=%v, err=%v", lease.Target, ch, err)
}
if lease.Target.Metadata["kind"] != "emulator" {
t.Fatal("missing bounded target metadata")
}
releaseTestResource(t, s, lease)
releaseTestResource(t, s, phone)
}
func TestResourcePoolFIFOWakeAndQuarantineIsolation(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
if err := s.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{
{Member: "held", Enabled: true}, {Member: "free", Enabled: true}, {Member: "bad", Enabled: false, Quarantined: true},
}}); err != nil {
t.Fatal(err)
}
held := acquireTestResource(t, s, create("held"))
first := create("targets")
firstLease, firstCh, _, err := s.RequestResourcePool(ctx, "targets", first)
if err != nil || firstCh != nil || firstLease.Target == nil {
t.Fatalf("expected immediate free member: %v", err)
}
// The second request waits once both concrete members are held.
second := create("targets")
_, secondCh, _, err := s.RequestResourcePool(ctx, "targets", second)
if err != nil || secondCh == nil {
t.Fatalf("expected pool waiter: %v", err)
}
releaseTestResource(t, s, firstLease)
select {
case next := <-secondCh:
if next.Target == nil || next.Target.Member != "free" {
t.Fatalf("wrong handoff: %#v", next.Target)
}
s.AcceptResource(next)
releaseTestResource(t, s, next)
case <-time.After(time.Second):
t.Fatal("pool waiter not woken")
}
releaseTestResource(t, s, held)
}
func TestResourcePoolHandoffUsesAnotherMemberWhenReleasedTargetQuarantined(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
pool := protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{
{Member: "phone", Enabled: true}, {Member: "emulator", Enabled: false},
}}
if err := s.ConfigureResourcePool(ctx, pool); err != nil {
t.Fatal(err)
}
owner, ready, _, err := s.RequestResourcePool(ctx, pool.Name, create(pool.Name))
if err != nil || ready != nil || owner.Target.Member != "phone" {
t.Fatalf("owner: %+v %v", owner, err)
}
_, waiter, _, err := s.RequestResourcePool(ctx, pool.Name, create(pool.Name))
if err != nil || waiter == nil {
t.Fatalf("waiter: %v", err)
}
pool.Members[0].Quarantined = true
pool.Members[1].Enabled = true
if err := s.ConfigureResourcePool(ctx, pool); err != nil {
t.Fatal(err)
}
releaseTestResource(t, s, owner)
select {
case next := <-waiter:
if next.Target == nil || next.Target.Member != "emulator" {
t.Fatalf("wrong target: %+v", next.Target)
}
s.AcceptResource(next)
releaseTestResource(t, s, next)
case <-time.After(time.Second):
t.Fatal("quarantined released phone blocked the free emulator")
}
}
func TestResourcePoolRejectsStaleVisitForExistingOwner(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
if err := s.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{
{Member: "phone", Enabled: true},
}}); err != nil {
t.Fatal(err)
}
owner := acquireTestResource(t, s, create("phone"))
stale := owner.ResourceVisit
stale.Resource = "targets"
stale.Sequence++
if _, ch, _, err := s.RequestResourcePool(ctx, "targets", stale); err == nil || ch != nil {
t.Fatalf("stale pool visit was accepted: channel=%v err=%v", ch, err)
}
if err := s.SetResourceCleanup(ctx, owner, true); err != nil {
t.Fatal(err)
}
if err := s.ReleaseResource(ctx, owner); err != nil {
t.Fatal(err)
}
}
func TestResourcePoolAndDirectVisitsCannotBeReinterpreted(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
if err := s.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{{Member: "phone", Enabled: true}}}); err != nil {
t.Fatal(err)
}
pooled := create("targets")
lease, ch, _, err := s.RequestResourcePool(ctx, "targets", pooled)
if err != nil || ch != nil {
t.Fatalf("pool acquire: %v %v", ch, err)
}
if _, ch, _, err := s.RequestResource(ctx, ResourceVisit{Resource: "phone", RunID: pooled.RunID, Stage: pooled.Stage, Sequence: pooled.Sequence}); err == nil || ch != nil {
t.Fatalf("pooled owner was accepted as direct lease: channel=%v err=%v", ch, err)
}
releaseTestResource(t, s, lease)
}
func TestResourcePoolConfigurationAndOwnerSurviveReopen(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
if err := s.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{
{Member: "phone", Enabled: true, Metadata: map[string]string{"kind": "phone"}},
}}); err != nil {
t.Fatal(err)
}
visit := create("targets")
owner, ch, _, err := s.RequestResourcePool(ctx, "targets", visit)
if err != nil || ch != nil {
t.Fatalf("pool acquire: %v %v", ch, err)
}
path := s.path
if err := s.Close(); err != nil {
t.Fatal(err)
}
reopened, err := Open(path)
if err != nil {
t.Fatal(err)
}
defer reopened.Close()
recovered, ch, _, err := reopened.RequestResourcePool(ctx, "targets", visit)
if err != nil || ch != nil || recovered.Target == nil || recovered.Target.Member != "phone" || recovered.Target.Metadata["kind"] != "phone" {
t.Fatalf("reopened pool owner not recovered: target=%#v channel=%v err=%v", recovered.Target, ch, err)
}
if err := reopened.SetResourceCleanup(ctx, recovered, true); err != nil {
t.Fatal(err)
}
if err := reopened.ReleaseResource(ctx, recovered); err != nil {
t.Fatal(err)
}
_ = owner
}
func TestResourcePoolAllocatesDistinctMembersConcurrently(t *testing.T) {
s, create := resourceStore(t)
ctx := context.Background()
if err := s.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{
{Member: "phone", Enabled: true}, {Member: "emulator", Enabled: true},
}}); err != nil {
t.Fatal(err)
}
visits := []ResourceVisit{create("targets"), create("targets")}
leases := make(chan ResourceLease, len(visits))
errs := make(chan error, len(visits))
var wg sync.WaitGroup
for _, visit := range visits {
wg.Add(1)
go func(v ResourceVisit) {
defer wg.Done()
lease, ch, _, err := s.RequestResourcePool(ctx, "targets", v)
if err != nil {
errs <- err
return
}
if ch != nil {
select {
case lease = <-ch:
case <-time.After(time.Second):
errs <- fmt.Errorf("pool request remained queued")
return
}
s.AcceptResource(lease)
}
leases <- lease
}(visit)
}
wg.Wait()
close(errs)
for err := range errs {
t.Fatal(err)
}
got := map[string]bool{}
for range visits {
lease := <-leases
if lease.Target == nil || got[lease.Target.Member] {
t.Fatalf("members were not distinct: %#v", lease.Target)
}
got[lease.Target.Member] = true
releaseTestResource(t, s, lease)
}
}
func TestResourcePoolRejectsInvalidDeclarations(t *testing.T) {
s, _ := resourceStore(t)
ctx := context.Background()
cases := []protocol.ResourcePool{
{Name: "missing-members"},
{Name: "duplicate", Members: []protocol.ResourcePoolMember{{Member: "phone"}, {Member: "phone"}}},
{Name: "bad-member", Members: []protocol.ResourcePoolMember{{Member: "not valid"}}},
{Name: "bad-metadata", Members: []protocol.ResourcePoolMember{{Member: "phone", Metadata: map[string]string{"bad key": "x"}}}},
{Name: "oversized-metadata-key", Members: []protocol.ResourcePoolMember{{Member: "phone", Metadata: map[string]string{strings.Repeat("k", maxTargetMetadataKey+1): "x"}}}},
}
for _, pool := range cases {
if err := s.ConfigureResourcePool(ctx, pool); err == nil {
t.Fatalf("accepted invalid pool %#v", pool)
}
}
visit := ResourceVisit{Resource: "unknown", RunID: 1, Stage: "work", Sequence: 1}
if _, _, _, err := s.RequestResourcePool(ctx, "unknown", visit); err == nil {
t.Fatal("accepted unknown pool")
}
}
func resourceStore(t *testing.T) (*Store, func(string) ResourceVisit) {
t.Helper()
ctx := context.Background()
+52
View File
@@ -0,0 +1,52 @@
package pipeline
import (
"context"
"database/sql"
"encoding/json"
"fmt"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// SaveRetryCheckpoint records the immutable source and the completed-prefix
// handoff before a retry is launched. It intentionally stores no step or usage
// rows: those remain evidence belonging only to the source attempt.
func (s *Store) SaveRetryCheckpoint(ctx context.Context, runID, sourceID int64, mode string, sequence int, source *protocol.RunDetail, handoff map[string]any) error {
if mode == "" {
mode = "resume"
}
data, err := json.Marshal(handoff)
if err != nil {
return err
}
s.mu.Lock()
defer s.mu.Unlock()
var oldSource int64
var oldMode, oldHandoff, oldHash string
var oldSeq, oldVersion int
err = s.db.QueryRowContext(ctx, `SELECT source_run_id,mode,failed_sequence,handoff_json,source_version,source_hash FROM retry_checkpoints WHERE run_id=?`, runID).Scan(&oldSource, &oldMode, &oldSeq, &oldHandoff, &oldVersion, &oldHash)
if err == nil {
if oldSource != sourceID || oldMode != mode || oldSeq != sequence || oldHandoff != string(data) || oldVersion != source.Version || oldHash != source.ContentHash {
return fmt.Errorf("retry checkpoint conflicts with the existing request")
}
return nil
}
if err != sql.ErrNoRows {
return err
}
_, err = s.db.ExecContext(ctx, `INSERT INTO retry_checkpoints(run_id,source_run_id,mode,failed_sequence,handoff_json,source_version,source_hash) VALUES(?,?,?,?,?,?,?)`, runID, sourceID, mode, sequence, string(data), source.Version, source.ContentHash)
return err
}
func (s *Store) RetryCheckpoint(ctx context.Context, runID int64) (sourceID int64, mode string, sequence int, handoff map[string]any, err error) {
s.mu.Lock()
defer s.mu.Unlock()
var data string
err = s.db.QueryRowContext(ctx, `SELECT source_run_id,mode,failed_sequence,handoff_json FROM retry_checkpoints WHERE run_id=?`, runID).Scan(&sourceID, &mode, &sequence, &data)
if err != nil {
return 0, "", 0, nil, err
}
err = json.Unmarshal([]byte(data), &handoff)
return
}
+1 -1
View File
@@ -100,7 +100,7 @@ func (s *Store) GetRun(ctx context.Context, id int64) (*protocol.RunDetail, erro
if err := json.Unmarshal([]byte(graphJSON), &r.Graph); err != nil {
return nil, err
}
if err := tx.QueryRowContext(ctx, "SELECT workspace,allow_tools,write_paths,input_json,output_json,COALESCE((SELECT original_run_id FROM run_retries WHERE run_id=pipeline_runs.id),0),title_source,title_model FROM pipeline_runs WHERE id=?", id).Scan(&r.Workspace, &r.AllowTools, &paths, &input, &output, &r.RetryOf, &r.TitleSource, &r.TitleModel); err != nil {
if err := tx.QueryRowContext(ctx, "SELECT workspace,allow_tools,write_paths,input_json,output_json,COALESCE((SELECT original_run_id FROM run_retries WHERE run_id=pipeline_runs.id),0),COALESCE((SELECT mode FROM retry_checkpoints WHERE run_id=pipeline_runs.id),CASE WHEN EXISTS(SELECT 1 FROM run_retries WHERE run_id=pipeline_runs.id) THEN 'restart' ELSE '' END),COALESCE((SELECT source_run_id FROM retry_checkpoints WHERE run_id=pipeline_runs.id),0),COALESCE((SELECT source_version FROM retry_checkpoints WHERE run_id=pipeline_runs.id),0),COALESCE((SELECT source_hash FROM retry_checkpoints WHERE run_id=pipeline_runs.id),''),title_source,title_model FROM pipeline_runs WHERE id=?", id).Scan(&r.Workspace, &r.AllowTools, &paths, &input, &output, &r.RetryOf, &r.RetryMode, &r.RetrySource, &r.RetrySourceVersion, &r.RetrySourceHash, &r.TitleSource, &r.TitleModel); err != nil {
return nil, err
}
if err := decodeValues(input, &r.Input); err != nil {
+16 -1
View File
@@ -52,9 +52,13 @@ run_id INTEGER NOT NULL, sequence INTEGER NOT NULL, backend TEXT NOT NULL, refer
PRIMARY KEY(run_id,sequence), FOREIGN KEY(run_id,sequence) REFERENCES run_steps(run_id,sequence));
CREATE TABLE IF NOT EXISTS run_retries (
run_id INTEGER PRIMARY KEY REFERENCES pipeline_runs(id), original_run_id INTEGER NOT NULL REFERENCES pipeline_runs(id));
CREATE TABLE IF NOT EXISTS retry_checkpoints (
run_id INTEGER PRIMARY KEY REFERENCES pipeline_runs(id), source_run_id INTEGER NOT NULL REFERENCES pipeline_runs(id),
mode TEXT NOT NULL, failed_sequence INTEGER NOT NULL, handoff_json TEXT NOT NULL,
source_version INTEGER NOT NULL, source_hash TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP);
CREATE TABLE IF NOT EXISTS resource_owners (
resource_key TEXT PRIMARY KEY, run_id INTEGER NOT NULL REFERENCES pipeline_runs(id),
stage_key TEXT NOT NULL, sequence INTEGER NOT NULL, token TEXT NOT NULL,
stage_key TEXT NOT NULL, sequence INTEGER NOT NULL, token TEXT NOT NULL, pool_name TEXT NOT NULL DEFAULT '',
cleanup_confirmed INTEGER NOT NULL DEFAULT 0, diagnostic TEXT NOT NULL DEFAULT '',
acquired_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP);
CREATE INDEX IF NOT EXISTS resource_owner_run ON resource_owners(run_id);
@@ -67,6 +71,17 @@ CREATE INDEX IF NOT EXISTS resource_wait_fifo ON resource_waiters(resource_key,q
if err != nil {
return err
}
if _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS resource_pools (
name TEXT PRIMARY KEY, members_json TEXT NOT NULL, updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);`); err != nil {
return err
}
if err := s.addColumnIfMissing("resource_waiters", "pool_name", "TEXT NOT NULL DEFAULT ''"); err != nil {
return err
}
if err := s.addColumnIfMissing("resource_owners", "pool_name", "TEXT NOT NULL DEFAULT ''"); err != nil {
return err
}
if err := s.migrateRunTitles(); err != nil {
return err
}
+28 -2
View File
@@ -54,6 +54,10 @@ const (
// load the choices without first listing sessions and chat_sessions stays a
// pure, fail-closed operator-session list.
ChatDirectories = "chat_directories"
// ChatShells lists current, verified shells belonging to one operator chat
// session. ChatShellOutput reads a bounded page from one such shell.
ChatShells = "chat_shells"
ChatShellOutput = "chat_shell_output"
// ChatEvent and ChatPermission are the server-pushed frames; they are the
// only types the server sends without a matching request.
ChatEvent = "chat_event"
@@ -89,8 +93,10 @@ const (
// ChatShell.Status values, mirroring the OpenCode shell events. A running shell
// is one whose command has started and not yet exited; exited is final.
const (
ChatShellRunning = "running"
ChatShellExited = "exited"
ChatShellRunning = "running"
ChatShellExited = "exited"
ChatShellOutputLimit = 64 << 10
ChatShellOutputMaxCursor = int64(1 << 62)
)
// ChatStep.Status values, mirroring the OpenCode session.step events.
@@ -360,6 +366,26 @@ type ChatShell struct {
Exit *int `json:"exit,omitempty"`
}
// ChatShellOutputQuery names one selected shell and a bounded absolute-byte
// output page. Cursor is decimal so it can be passed directly to OpenCode.
type ChatShellOutputQuery struct {
SessionID string `json:"session_id"`
ShellID string `json:"shell_id"`
Cursor int64 `json:"cursor,omitempty"`
Limit int `json:"limit,omitempty"`
}
// ChatShellOutputPage is a bounded, lazy output read. Unavailable is explicit when
// an exited shell is no longer directly verifiable upstream.
type ChatShellOutputPage struct {
Shell ChatShell `json:"shell"`
Output string `json:"output,omitempty"`
Cursor int64 `json:"cursor,omitempty"`
Size int64 `json:"size,omitempty"`
Truncated bool `json:"truncated,omitempty"`
Unavailable bool `json:"unavailable,omitempty"`
}
// ChatPermissionFrame is the server-pushed chat_permission payload: one pending
// OpenCode permission request the phone must approve or reject. It is a distinct
// Message field (like ChatEvent) rather than a ChatEvent.Kind, so it does not
+13 -1
View File
@@ -41,6 +41,7 @@ type Stage struct {
// StageResources declares one capacity-one resource, local to this store authority.
type StageResources struct {
Exclusive string `json:"exclusive"`
Pool string `json:"pool"`
}
// Limits are enforced by the runner and never included in the model prompt.
@@ -159,6 +160,14 @@ type Message struct {
// them; the same fields are echoed on the run record.
Model string `json:"model,omitempty"`
StageModels map[string]string `json:"stage_models,omitempty"`
// Empty (or "resume") retries the failed visit; "restart" starts at the
// entry stage. Older clients omit this field and retain resume behavior.
RetryMode string `json:"retry_mode,omitempty"`
RetrySource int64 `json:"-"`
RetryStage string `json:"retry_stage,omitempty"`
RetryVisit int `json:"retry_visit,omitempty"`
RetryVersion int `json:"retry_version,omitempty"`
RetryInput map[string]any `json:"retry_input,omitempty"`
// Search is the broad, read-only search traffic over pipelines, versions,
// runs, steps, field text and artifacts. See search.go for the per-type
// payloads and the ranking/kind/bound vocabulary.
@@ -191,7 +200,10 @@ type Message struct {
// chat_directories response (home first, then recent operator-session
// directories, deduplicated and bounded). Additive/omitempty so older peers
// ignore it.
ChatDirectories []string `json:"chat_directories,omitempty"`
ChatDirectories []string `json:"chat_directories,omitempty"`
ChatShellOutputQuery *ChatShellOutputQuery `json:"chat_shell_output_query,omitempty"`
ChatShells []ChatShell `json:"chat_shells,omitempty"`
ChatShellOutput *ChatShellOutputPage `json:"chat_shell_output,omitempty"`
// RunEvent is the server-pushed run state delta (see runevents.go) and
// RunIDs the optional subscribe scope, so a client asks for the runs it
// displays. Both are optional so older peers ignore them.
+19
View File
@@ -6,6 +6,25 @@ type ResourceInspection struct {
Waiters []ResourceWaiter `json:"waiters,omitempty"`
Audits []ResourceRecoveryAudit `json:"audits,omitempty"`
}
// ResourceTarget is bounded, non-secret metadata for the concrete member that
// was selected. Credentials and capabilities are intentionally absent.
type ResourceTarget struct {
Member string `json:"member"`
Metadata map[string]string `json:"metadata,omitempty"`
}
type ResourcePoolMember struct {
Member string `json:"member"`
Metadata map[string]string `json:"metadata,omitempty"`
Enabled bool `json:"enabled"`
Quarantined bool `json:"quarantined,omitempty"`
}
type ResourcePool struct {
Name string `json:"name"`
Members []ResourcePoolMember `json:"members"`
}
type ResourceOwner struct {
RunID int64 `json:"run_id"`
Stage string `json:"stage"`
+18 -13
View File
@@ -331,11 +331,12 @@ type MemoryRead struct {
}
type ControlEvidence struct {
Visit int `json:"visit"`
MaxVisits int `json:"max_visits"`
LimitReached bool `json:"limit_reached,omitempty"`
ModelTarget string `json:"model_target,omitempty"`
Memory map[string]MemoryRead `json:"memory,omitempty"`
Visit int `json:"visit"`
MaxVisits int `json:"max_visits"`
LimitReached bool `json:"limit_reached,omitempty"`
ModelTarget string `json:"model_target,omitempty"`
Memory map[string]MemoryRead `json:"memory,omitempty"`
ResourceTarget *ResourceTarget `json:"resource_target,omitempty"`
}
// StageFileChanges is observed workspace evidence, not a model's claim of authorship.
@@ -370,14 +371,18 @@ type NotificationReceipt struct {
type RunDetail struct {
RunSummary
Graph Graph `json:"graph"`
RetryOf int64 `json:"retry_of,omitempty"`
Workspace string `json:"workspace"`
AllowTools bool `json:"allow_tools"`
WritePaths []string `json:"write_paths"`
Input map[string]any `json:"input"`
Output map[string]any `json:"output"`
Steps []RunStep `json:"steps"`
Graph Graph `json:"graph"`
RetryOf int64 `json:"retry_of,omitempty"`
RetryMode string `json:"retry_mode,omitempty"`
RetrySource int64 `json:"retry_source,omitempty"`
RetrySourceVersion int `json:"retry_source_version,omitempty"`
RetrySourceHash string `json:"retry_source_hash,omitempty"`
Workspace string `json:"workspace"`
AllowTools bool `json:"allow_tools"`
WritePaths []string `json:"write_paths"`
Input map[string]any `json:"input"`
Output map[string]any `json:"output"`
Steps []RunStep `json:"steps"`
// Usage is the totalled reported usage of the run's model stages, summed in
// one pass over Steps. It is absent for a run with no model usage recorded
// (including historical runs).
+10
View File
@@ -42,6 +42,10 @@ type chatBroker interface {
Reply(ctx context.Context, request protocol.ChatReplyRequest) error
}
type chatShellOutputReader interface {
ShellOutput(ctx context.Context, query protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error)
}
// chatShellReleaser is implemented by brokers that retain verified shell ids for
// attributing exit events. The hub calls it only after the last observer leaves
// a room; a later attach obtains a fresh authoritative snapshot.
@@ -128,6 +132,12 @@ func handleChat(ctx context.Context, request protocol.Message, broker chatBroker
case protocol.ChatReopen:
handleChatReopen(ctx, request, registry, write)
return true
case protocol.ChatShells:
handleChatShells(ctx, request, broker, registry, write)
return true
case protocol.ChatShellOutput:
handleChatShellOutput(ctx, request, broker, registry, write)
return true
}
return false
}
+76
View File
@@ -0,0 +1,76 @@
package server
import (
"context"
"fmt"
"git.a-wan.net/alan/pipelines/internal/opencode"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func operatorChatSession(ctx context.Context, registry operatorRegistry, id string) error {
if registry == nil {
return fmt.Errorf("operator session registry is not configured on this server")
}
_, found, err := registry.OperatorSession(ctx, id)
if err != nil {
return err
}
if !found {
return fmt.Errorf("operator session is not available")
}
return nil
}
func handleChatShells(ctx context.Context, request protocol.Message, broker chatBroker, registry operatorRegistry, write func(protocol.Message) error) {
query := request.ChatQuery
if broker == nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"})
return
}
if query == nil || !opencode.ValidSessionID(query.SessionID) {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid OpenCode session id is required"})
return
}
if err := operatorChatSession(ctx, registry, query.SessionID); err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
}
shells, err := broker.Shells(ctx, query.SessionID)
if err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
}
_ = write(protocol.Message{Type: protocol.ChatShells, ID: request.ID, ChatShells: shells})
}
func handleChatShellOutput(ctx context.Context, request protocol.Message, broker chatBroker, registry operatorRegistry, write func(protocol.Message) error) {
query := request.ChatShellOutputQuery
if broker == nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"})
return
}
if query == nil || !opencode.ValidSessionID(query.SessionID) || !validShellID(query.ShellID) || query.Cursor < 0 || query.Cursor > protocol.ChatShellOutputMaxCursor || query.Limit <= 0 || query.Limit > protocol.ChatShellOutputLimit {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid bounded shell output query is required"})
return
}
if err := operatorChatSession(ctx, registry, query.SessionID); err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
}
reader, ok := broker.(chatShellOutputReader)
if !ok {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "shell output is not configured on this server"})
return
}
output, err := reader.ShellOutput(ctx, *query)
if err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
}
_ = write(protocol.Message{Type: protocol.ChatShellOutput, ID: request.ID, ChatShellOutput: &output})
}
func validShellID(id string) bool {
return opencode.ValidShellID(id)
}
+280
View File
@@ -0,0 +1,280 @@
package server
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/coder/websocket"
"github.com/coder/websocket/wsjson"
"git.a-wan.net/alan/pipelines/internal/opencode"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
type shellOutputTestBroker struct {
*fakeChat
outputCalls int
}
func (b *shellOutputTestBroker) ShellOutput(context.Context, protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) {
b.outputCalls++
return protocol.ChatShellOutputPage{Output: "unexpected"}, nil
}
func TestChatShellOutputRejectsBoundsBeforeRegistryOrProvider(t *testing.T) {
store := newOperatorStore(t)
broker := &shellOutputTestBroker{fakeChat: scriptedChat()}
queries := []protocol.ChatShellOutputQuery{
{SessionID: "ses_1", ShellID: "sh_1", Limit: 0},
{SessionID: "ses_1", ShellID: "sh_1", Limit: -1},
{SessionID: "ses_1", ShellID: "sh_1", Cursor: protocol.ChatShellOutputMaxCursor + 1, Limit: 1},
{SessionID: "ses_1", ShellID: "sh_1/../x", Limit: 1},
{SessionID: "ses_1", ShellID: "sh_1%2f", Limit: 1},
{SessionID: "ses_1", ShellID: "sh_1?cursor=0", Limit: 1},
{SessionID: "ses_1", ShellID: "sh_1#fragment", Limit: 1},
{SessionID: "ses_1", ShellID: "sh_%ZZ", Limit: 1},
{SessionID: "ses_1", ShellID: "sh_" + string(make([]byte, 126)), Limit: 1},
}
for _, query := range queries {
var response protocol.Message
handleChatShellOutput(context.Background(), protocol.Message{ChatShellOutputQuery: &query}, broker, store, func(m protocol.Message) error {
response = m
return nil
})
if response.Type != protocol.Error {
t.Fatalf("query %+v response = %+v", query, response)
}
}
if broker.outputCalls != 0 {
t.Fatalf("invalid queries reached provider %d times", broker.outputCalls)
}
}
// TestChatShellOutputRealHandlerWebsocketOwnedAndForeign drives the real
// authenticated adapter, HTTP fixture, HandlerWithOptions, and /connect path.
// The foreign detail deliberately has a marker that would be returned by its
// output route; the session metadata check must reject it first.
func TestChatShellOutputRealHandlerWebsocketOwnedAndForeign(t *testing.T) {
testChatShellOutputOwnedAndForeign(t, false)
}
func TestChatShellOutputRealHandlerExitedReadback(t *testing.T) {
testChatShellOutputOwnedAndForeign(t, true)
}
func testChatShellOutputOwnedAndForeign(t *testing.T, exited bool) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
var providerRequests atomic.Int32
fixtureHandler := LargeChatFixtureHandlerWithShell(t.TempDir(), exited)
fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
providerRequests.Add(1)
fixtureHandler.ServeHTTP(w, r)
}))
defer fixture.Close()
attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "")
if err != nil {
t.Fatal(err)
}
store := newOperatorStore(t)
if err := store.RecordOperatorSession(ctx, LargeChatFixtureSessionID, t.TempDir(), "owned", protocol.ChatSessionTagOperator); err != nil {
t.Fatal(err)
}
srv := httptest.NewServer(HandlerWithOptions(ctx, Options{Chat: opencode.NewChat(attached.Connection), OperatorRegistry: store}))
defer srv.Close()
ws := dialShellOutputWebsocket(t, ctx, srv)
defer ws.CloseNow()
writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "owned-shells", ChatQuery: &protocol.ChatQuery{SessionID: LargeChatFixtureSessionID}})
owned := readShellOutputMessage(t, ctx, ws)
if owned.Type != protocol.ChatShells || (exited && len(owned.ChatShells) != 0) || (!exited && (len(owned.ChatShells) != 1 || owned.ChatShells[0].ID != LargeChatFixtureShellID || owned.ChatShells[0].Status != protocol.ChatShellRunning)) {
t.Fatalf("owned shell listing = %+v", owned)
}
wantStatus := protocol.ChatShellRunning
if exited {
wantStatus = protocol.ChatShellExited
}
writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "owned-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: LargeChatFixtureSessionID, ShellID: LargeChatFixtureShellID, Limit: protocol.ChatShellOutputLimit}})
page := readShellOutputMessage(t, ctx, ws)
if page.Type != protocol.ChatShellOutput || page.ChatShellOutput == nil || page.ChatShellOutput.Output != LargeChatFixtureShellOutput || page.ChatShellOutput.Cursor != int64(len(LargeChatFixtureShellOutput)) || page.ChatShellOutput.Shell.Status != wantStatus {
t.Fatalf("owned output page = %+v", page)
}
if exited {
if page.ChatShellOutput.Shell.Exit == nil || *page.ChatShellOutput.Shell.Exit != 0 {
t.Fatalf("selected exited shell readback = %+v", page.ChatShellOutput.Shell)
}
} else if page.ChatShellOutput.Shell.Exit != nil {
t.Fatalf("running shell unexpectedly has exit = %+v", page.ChatShellOutput.Shell.Exit)
}
if page.ChatShellOutput.Cursor != int64(len(page.ChatShellOutput.Output)) || page.ChatShellOutput.Size != page.ChatShellOutput.Cursor {
t.Fatalf("non-deterministic output cursor/size = %+v", page.ChatShellOutput)
}
refusals := []struct {
name string
request protocol.Message
}{
{name: "foreign-output", request: protocol.Message{Type: protocol.ChatShellOutput, ID: "foreign-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: LargeChatFixtureSessionID, ShellID: LargeChatFixtureForeignShellID, Limit: protocol.ChatShellOutputLimit}}},
{name: "foreign-list", request: protocol.Message{Type: protocol.ChatShells, ID: "foreign-list", ChatQuery: &protocol.ChatQuery{SessionID: LargeChatFixtureForeignSessionID}}},
{name: "syntax-invalid-list", request: protocol.Message{Type: protocol.ChatShells, ID: "invalid-list", ChatQuery: &protocol.ChatQuery{SessionID: "ses_bad/invalid"}}},
{name: "unknown-output", request: protocol.Message{Type: protocol.ChatShellOutput, ID: "unknown-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: "ses_unregistered_fixture", ShellID: LargeChatFixtureShellID, Limit: protocol.ChatShellOutputLimit}}},
}
for _, refusal := range refusals {
beforeRefusal := providerRequests.Load()
writeChat(t, ctx, ws, refusal.request)
response := readShellOutputMessage(t, ctx, ws)
if response.Type != protocol.Error || strings.Contains(response.Error, LargeChatFixtureForeignShellOutput) {
t.Fatalf("%s response leaked or succeeded: %+v", refusal.name, response)
}
if got := providerRequests.Load(); got != beforeRefusal {
t.Fatalf("%s reached provider: requests %d -> %d", refusal.name, beforeRefusal, got)
}
}
}
func TestChatShellOutputRealHandlerUnavailableAndReconnect(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
fixture := httptest.NewServer(LargeChatFixtureHandlerWithShell(t.TempDir(), false))
defer fixture.Close()
attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "")
if err != nil {
t.Fatal(err)
}
store := newOperatorStore(t)
if err := store.RecordOperatorSession(ctx, LargeChatFixtureSessionID, t.TempDir(), "owned", protocol.ChatSessionTagOperator); err != nil {
t.Fatal(err)
}
srv := httptest.NewServer(HandlerWithOptions(ctx, Options{Chat: opencode.NewChat(attached.Connection), OperatorRegistry: store}))
defer srv.Close()
ws := dialShellOutputWebsocket(t, ctx, srv)
writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "missing-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: LargeChatFixtureSessionID, ShellID: "sh_missing_fixture", Limit: 64}})
missing := readShellOutputMessage(t, ctx, ws)
if missing.Type != protocol.ChatShellOutput || missing.ChatShellOutput == nil || !missing.ChatShellOutput.Unavailable {
t.Fatalf("404 shell output = %+v", missing)
}
ws = dialShellOutputWebsocket(t, ctx, srv)
defer ws.CloseNow()
writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "reconnect", ChatQuery: &protocol.ChatQuery{SessionID: LargeChatFixtureSessionID}})
if got := readShellOutputMessage(t, ctx, ws); got.Type != protocol.ChatShells {
t.Fatalf("reconnect shell listing = %+v", got)
}
if _, err := opencode.OpenEndpointAttached(ctx, fixture.URL, "wrong-password", "", ""); err == nil {
t.Fatal("wrong provider authentication unexpectedly succeeded")
}
}
func TestChatShellOutputRejectsMalformedAndOversizedProviderPages(t *testing.T) {
for _, tc := range []struct {
name string
output string
}{
{name: "malformed", output: `{"data":{"output":"x"}}`},
{name: "oversized", output: fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, strings.Repeat("x", protocol.ChatShellOutputLimit+1), protocol.ChatShellOutputLimit+1, protocol.ChatShellOutputLimit+1)},
} {
t.Run(tc.name, func(t *testing.T) {
fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
return
}
w.Header().Set("Content-Type", "application/json")
switch r.URL.Path {
case "/api/info":
_, _ = w.Write([]byte(`{"version":"fixture","urls":[]}`))
case "/api/event":
w.Header().Set("Content-Type", "text/event-stream")
case "/api/shell/sh_malformed_fixture":
_, _ = w.Write([]byte(`{"data":{"id":"sh_malformed_fixture","status":"running","metadata":{"sessionID":"ses_malformed_fixture"}}}`))
case "/api/shell/sh_malformed_fixture/output":
_, _ = w.Write([]byte(tc.output))
default:
if r.URL.Path == "/api/shell" {
_, _ = w.Write([]byte(`{"data":[]}`))
return
}
http.NotFound(w, r)
}
}))
defer fixture.Close()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "")
if err != nil {
t.Fatal(err)
}
_, err = opencode.NewChat(attached.Connection).ShellOutput(ctx, protocol.ChatShellOutputQuery{SessionID: "ses_malformed_fixture", ShellID: "sh_malformed_fixture", Limit: protocol.ChatShellOutputLimit})
if err == nil {
t.Fatalf("%s provider page was accepted", tc.name)
}
})
}
}
func TestChatShellOutputRealHandlerCancellationStopsProvider(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
started := make(chan struct{})
canceled := make(chan struct{})
fixtureHandler := LargeChatFixtureHandlerWithShell(t.TempDir(), false)
fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/api/shell/sh_cancel_fixture" {
if !largeChatFixtureAuthenticated(w, r) {
return
}
close(started)
<-r.Context().Done()
close(canceled)
return
}
fixtureHandler.ServeHTTP(w, r)
}))
defer fixture.Close()
attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "")
if err != nil {
t.Fatal(err)
}
store := newOperatorStore(t)
if err := store.RecordOperatorSession(ctx, "ses_cancel_fixture", t.TempDir(), "cancel", protocol.ChatSessionTagOperator); err != nil {
t.Fatal(err)
}
serverCtx, serverCancel := context.WithCancel(ctx)
defer serverCancel()
srv := httptest.NewServer(HandlerWithOptions(serverCtx, Options{Chat: opencode.NewChat(attached.Connection), OperatorRegistry: store}))
defer srv.Close()
ws := dialShellOutputWebsocket(t, ctx, srv)
writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "cancel-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: "ses_cancel_fixture", ShellID: "sh_cancel_fixture", Limit: 64}})
select {
case <-started:
case <-ctx.Done():
t.Fatal("provider detail request did not start")
}
serverCancel()
select {
case <-canceled:
case <-ctx.Done():
t.Fatal("canceling handler did not cancel provider request")
}
}
func dialShellOutputWebsocket(t *testing.T, ctx context.Context, srv *httptest.Server) *websocket.Conn {
t.Helper()
ws, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(srv.URL, "http")+"/connect", nil)
if err != nil {
t.Fatal(err)
}
return ws
}
func readShellOutputMessage(t *testing.T, ctx context.Context, ws *websocket.Conn) protocol.Message {
t.Helper()
var message protocol.Message
if err := wsjson.Read(ctx, ws, &message); err != nil {
t.Fatal(err)
}
return message
}
+14 -10
View File
@@ -341,20 +341,23 @@ func TestRetryConflictsOnlyWithSameWorkspaceActiveRun(t *testing.T) {
if err != nil || failed.Status != "failed" {
t.Fatalf("original run did not fail as intended: %+v %v", failed, err)
}
resolvedB, err := filepath.EvalSymlinks(b)
entered := make(chan struct{}, 4)
resolvedA, err := filepath.EvalSymlinks(a)
if err != nil {
t.Fatal(err)
}
entered := make(chan struct{}, 4)
release := make(chan struct{})
releaseA := make(chan struct{})
releaseB := make(chan struct{})
r.execute = func(ctx context.Context, _ stage.Definition, input stage.Values) (stage.Result, error) {
entered <- struct{}{}
if input["pwd"] == resolvedB {
select {
case <-release:
case <-ctx.Done():
return stage.Result{}, ctx.Err()
}
release := releaseB
if input["pwd"] == resolvedA {
release = releaseA
}
select {
case <-release:
case <-ctx.Done():
return stage.Result{}, ctx.Err()
}
return stage.Result{Outcome: "success", Output: stage.Values{}}, nil
}
@@ -366,6 +369,7 @@ func TestRetryConflictsOnlyWithSameWorkspaceActiveRun(t *testing.T) {
if _, err := r.retry(protocol.Message{RunID: original.ID, RequestKey: "retry-a"}); err == nil || !strings.Contains(err.Error(), fmt.Sprintf("run %d is already active", activeA.ID)) || !strings.Contains(err.Error(), "different workspace") {
t.Fatalf("retry did not conflict with same-workspace active run: %v", err)
}
close(releaseA)
// A different active workspace must not block the retry of the original.
if _, err := r.start(protocol.Message{PipelineID: pipelineID, Version: 1, RequestKey: "active-b", Workspace: b, Input: map[string]any{"prompt": "task"}}); err != nil {
t.Fatal(err)
@@ -378,7 +382,7 @@ func TestRetryConflictsOnlyWithSameWorkspaceActiveRun(t *testing.T) {
if retried.Workspace != failed.Workspace {
t.Fatalf("retry did not reuse the original workspace: %q != %q", retried.Workspace, failed.Workspace)
}
close(release)
close(releaseB)
r.wg.Wait()
}
+1 -1
View File
@@ -270,7 +270,7 @@ func TestHumanStageCancelRetryAndRebuild(t *testing.T) {
t.Fatalf("post-decision failure did not fail the run: %+v", failed.RunSummary)
}
r3.execute = successExecute
retried, err := r3.retry(protocol.Message{RunID: failing.ID, RequestKey: "retry-human"})
retried, err := r3.retry(protocol.Message{RunID: failing.ID, RequestKey: "retry-human", RetryMode: "restart"})
if err != nil {
t.Fatal(err)
}
+52
View File
@@ -13,6 +13,11 @@ const LargeChatFixtureSessionID = "ses_large_chat_fixture"
// LargeChatFixturePassword authenticates the disposable fixture endpoint. It is
// fixed fixture data, not an operator credential.
const LargeChatFixturePassword = "large-chat-fixture"
const LargeChatFixtureShellID = "sh_large_chat_fixture"
const LargeChatFixtureShellOutput = "fixture shell output marker\n"
const LargeChatFixtureForeignSessionID = "ses_foreign_fixture"
const LargeChatFixtureForeignShellID = "sh_foreign_fixture"
const LargeChatFixtureForeignShellOutput = "FOREIGN SHELL MARKER MUST NOT LEAK\n"
const (
LargeChatFixtureNewestAnswer = "Controlled newest answer: large history fixture"
@@ -24,6 +29,13 @@ const (
// It deliberately serves fixed, paged data: no model is invoked and no production
// history is read or written.
func LargeChatFixtureHandler(workspace string) http.Handler {
return LargeChatFixtureHandlerWithShell(workspace, false)
}
// LargeChatFixtureHandlerWithShell is the foreground fixture surface used by
// the readback check. exited selects the provider's observed terminal state;
// the output remains fixed and bounded in either state.
func LargeChatFixtureHandlerWithShell(workspace string, exited bool) http.Handler {
mux := http.NewServeMux()
mux.HandleFunc("GET /api/info", func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
@@ -63,6 +75,46 @@ func LargeChatFixtureHandler(workspace string) http.Handler {
}
writeLargeChatFixturePage(w, page)
})
status := "running"
if exited {
status = "exited"
}
mux.HandleFunc("GET /api/shell", func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
return
}
writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":[{"id":%q,"status":%q,"command":"printf fixture","metadata":{"sessionID":%q}},{"id":%q,"status":"running","command":"printf foreign","metadata":{"sessionID":%q}}]}`, LargeChatFixtureShellID, status, LargeChatFixtureSessionID, LargeChatFixtureForeignShellID, LargeChatFixtureForeignSessionID))
})
mux.HandleFunc("GET /api/shell/"+LargeChatFixtureShellID, func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
return
}
exit := "null"
if exited {
exit = "0"
}
writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"id":%q,"status":%q,"command":"printf fixture","exit":%s,"metadata":{"sessionID":%q}}}`, LargeChatFixtureShellID, status, exit, LargeChatFixtureSessionID))
})
mux.HandleFunc("GET /api/shell/"+LargeChatFixtureForeignShellID, func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
return
}
writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"id":%q,"status":"running","command":"printf foreign","metadata":{"sessionID":%q}}}`, LargeChatFixtureForeignShellID, LargeChatFixtureForeignSessionID))
})
mux.HandleFunc("GET /api/shell/"+LargeChatFixtureShellID+"/output", func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
return
}
cursor := int64(len(LargeChatFixtureShellOutput))
writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, LargeChatFixtureShellOutput, cursor, cursor))
})
mux.HandleFunc("GET /api/shell/"+LargeChatFixtureForeignShellID+"/output", func(w http.ResponseWriter, r *http.Request) {
if !largeChatFixtureAuthenticated(w, r) {
return
}
cursor := int64(len(LargeChatFixtureForeignShellOutput))
writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, LargeChatFixtureForeignShellOutput, cursor, cursor))
})
return mux
}
+13 -1
View File
@@ -11,7 +11,19 @@ import (
)
func (r *runner) acquireResource(ctx context.Context, visit pipeline.ResourceVisit, workspace string, completed int) (pipeline.ResourceLease, error) {
lease, ready, wait, err := r.store.RequestResource(ctx, visit)
return r.acquireResourceWithPool(ctx, visit, "", workspace, completed)
}
func (r *runner) acquireResourceWithPool(ctx context.Context, visit pipeline.ResourceVisit, pool string, workspace string, completed int) (pipeline.ResourceLease, error) {
var lease pipeline.ResourceLease
var ready <-chan pipeline.ResourceLease
var wait *protocol.ResourceWait
var err error
if pool != "" {
lease, ready, wait, err = r.store.RequestResourcePool(ctx, pool, visit)
} else {
lease, ready, wait, err = r.store.RequestResource(ctx, visit)
}
if err != nil {
return lease, err
}
+91
View File
@@ -137,6 +137,97 @@ func TestResourcePauseBeyondTimeoutAndAutomaticResume(t *testing.T) {
}
}
func TestResourcePoolRunnerHandoffUsesConcreteTargetAfterQueue(t *testing.T) {
r, events, _ := resourceRunner(t)
ctx := context.Background()
source := pipeline.Template([]string{"work"}, true) + "```resources\n{\"pool\":\"targets\"}\n```\n"
if _, err := r.store.Submit(ctx, "pool-runner", source); err != nil {
t.Fatal(err)
}
items, err := r.store.List(ctx)
if err != nil || len(items) != 1 {
t.Fatal("pool definition missing", err)
}
definition, err := r.store.Get(ctx, items[0].ID, 1)
if err != nil {
t.Fatal(err)
}
if err := r.store.ConfigureResourcePool(ctx, protocol.ResourcePool{Name: "targets", Members: []protocol.ResourcePoolMember{
{Member: "phone", Enabled: true, Metadata: map[string]string{"serial": "phone-serial", "type": "phone"}},
{Member: "emulator", Enabled: true, Metadata: map[string]string{"serial": "emu-serial", "type": "emulator"}},
}}); err != nil {
t.Fatal(err)
}
ownerRun, _, err := r.store.CreateRun(ctx, definition, "phone-owner", t.TempDir(), false, nil, nil)
if err != nil {
t.Fatal(err)
}
phone, ch, _, err := r.store.RequestResource(ctx, pipeline.ResourceVisit{Resource: "phone", RunID: ownerRun, Stage: "work", Sequence: 1})
if err != nil || ch != nil {
t.Fatalf("phone owner acquire: channel=%v err=%v", ch, err)
}
defer r.releaseResource(phone, true)
aStarted, releaseA := make(chan struct{}), make(chan struct{})
bRan := make(chan *protocol.ResourceTarget, 1)
r.execute = func(stageCtx context.Context, _ stage.Definition, input stage.Values) (stage.Result, error) {
target, ok := stage.ResourceTarget(stageCtx)
if !ok || target == nil {
return stage.Result{}, errors.New("missing resource target context")
}
if input["prompt"] == "A" {
if target.Member != "emulator" || target.Metadata["serial"] != "emu-serial" || target.Metadata["type"] != "emulator" {
return stage.Result{}, fmt.Errorf("wrong first target: %#v", target)
}
close(aStarted)
<-releaseA
} else {
if deadline, ok := stageCtx.Deadline(); !ok || time.Until(deadline) < 15*time.Millisecond {
return stage.Result{}, errors.New("execution deadline was consumed in pool queue")
}
bRan <- target
}
return stage.Result{Outcome: "success", Output: stage.Values{}}, nil
}
start := func(key, prompt string) *protocol.RunDetail {
run, err := r.start(protocol.Message{PipelineID: definition.ID, Version: 1, RequestKey: key, Workspace: t.TempDir(), Input: map[string]any{"prompt": prompt}})
if err != nil {
t.Fatal(err)
}
return run
}
a := start("pool-a", "A")
<-aStarted
b := start("pool-b", "B")
awaitResourceEvent(t, events, b.ID, func(e protocol.RunEventFrame) bool { return e.ResourceWait != nil })
time.Sleep(80 * time.Millisecond)
select {
case <-bRan:
t.Fatal("pool waiter ran before either member was released")
default:
}
if err := r.releaseResource(phone, true); err != nil {
t.Fatal(err)
}
var target *protocol.ResourceTarget
select {
case target = <-bRan:
case <-time.After(3 * time.Second):
t.Fatal("pool waiter did not resume")
}
if target.Member != "phone" || target.Metadata["serial"] != "phone-serial" {
t.Fatalf("wrong queued target: %#v", target)
}
awaitResourceEvent(t, events, b.ID, func(e protocol.RunEventFrame) bool { return e.Status == "succeeded" })
close(releaseA)
awaitResourceEvent(t, events, a.ID, func(e protocol.RunEventFrame) bool { return e.Status == "succeeded" })
r.wg.Wait()
detail, err := r.store.GetRun(ctx, b.ID)
if err != nil || len(detail.Steps) != 1 || detail.Steps[0].Control.ResourceTarget == nil {
t.Fatalf("pool target evidence missing: detail=%#v err=%v", detail, err)
}
}
func TestResourceCancellationWaitsForOwnerCleanup(t *testing.T) {
r, events, start := resourceRunner(t)
started, cleaning, cleanupDone := make(chan struct{}), make(chan struct{}), make(chan struct{})
+2 -2
View File
@@ -43,14 +43,14 @@ func TestRetryWaitsForExecutionCleanupEvenAfterTerminalStatus(t *testing.T) {
if err != nil || !runs[0].Executing {
t.Fatal("list advertised stopped run during cleanup", runs, err)
}
if _, err := r.retry(protocol.Message{RunID: id, RequestKey: "retry"}); err == nil || !strings.Contains(err.Error(), "still executing") {
if _, err := r.retry(protocol.Message{RunID: id, RequestKey: "retry", RetryMode: "restart"}); err == nil || !strings.Contains(err.Error(), "still executing") {
t.Fatal("retry accepted during execution cleanup", err)
}
delete(r.active, id)
r.execute = func(context.Context, stage.Definition, stage.Values) (stage.Result, error) {
return stage.Result{Outcome: "success", Output: stage.Values{"summary": "done"}}, nil
}
if _, err := r.retry(protocol.Message{RunID: id, RequestKey: "retry"}); err != nil {
if _, err := r.retry(protocol.Message{RunID: id, RequestKey: "retry", RetryMode: "restart"}); err != nil {
t.Fatal("retry rejected after cleanup", err)
}
r.wg.Wait()
+214 -2
View File
@@ -18,6 +18,37 @@ import (
"git.a-wan.net/alan/pipelines/internal/stage"
)
func TestRetryInputOverrideRejectsReservedAndOversizedValues(t *testing.T) {
base := map[string]any{"handoff": "retained"}
if _, err := retryInputOverride(base, map[string]any{"workspace": "/escape"}); err == nil {
t.Fatal("reserved retry input was accepted")
}
if _, err := retryInputOverride(base, map[string]any{"large": strings.Repeat("x", maxRetryInputBytes)}); err == nil {
t.Fatal("oversized retry input was accepted")
}
merged, err := retryInputOverride(base, map[string]any{"correction": "new"})
if err != nil || merged["handoff"] != "retained" || merged["correction"] != "new" {
t.Fatalf("retry input merge lost retained context: %#v, %v", merged, err)
}
}
func TestRetryStageContractIncludesPromptConfigAndEdges(t *testing.T) {
original := protocol.Stage{Key: "b", Type: "model", Prompt: "old", Configs: map[string]string{"model": "one"}, Edges: map[string]string{"success": "c"}}
if !retryStageContractEqual(original, original) {
t.Fatal("identical stage contracts differ")
}
changed := original
changed.Prompt = "corrected"
if retryStageContractEqual(original, changed) {
t.Fatal("changed stage prompt was treated as compatible")
}
changed = original
changed.Edges = map[string]string{"success": "other"}
if retryStageContractEqual(original, changed) {
t.Fatal("changed stage edge was treated as compatible")
}
}
func TestRetryCreatesFreshOpenCodeSessionAndRetainsFailedSession(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
@@ -183,7 +214,7 @@ func TestRetryReplaysInitialInputAndPinnedVersionThroughCLI(t *testing.T) {
if err != nil || len(beforeRetry) != 1 {
t.Fatal("unconfirmed retry created a run", err)
}
result, err := runCLI("retry", fmt.Sprint(original.ID), "--yes", "--json", "--wait", "--timeout", "5s", "--request-key", "retry-key")
result, err := runCLI("retry", fmt.Sprint(original.ID), "--yes", "--json", "--wait", "--timeout", "5s", "--request-key", "retry-key", "--mode", "restart")
if err != nil {
t.Fatal(err)
}
@@ -236,7 +267,7 @@ func TestRetryRejectsUnavailableOriginalDirectoryAndNonfailedRuns(t *testing.T)
t.Fatal(err)
}
}
_, err = r.retry(protocol.Message{RunID: id, RequestKey: "retry-" + status})
_, err = r.retry(protocol.Message{RunID: id, RequestKey: "retry-" + status, RetryMode: "restart"})
if err == nil {
t.Fatal("invalid retry accepted", status)
}
@@ -249,6 +280,187 @@ func TestRetryRejectsUnavailableOriginalDirectoryAndNonfailedRuns(t *testing.T)
}
}
func TestRetryResumeReusesPrefixHandoffAndReplaysRequestAfterReopen(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
dir := t.TempDir()
store, err := pipeline.Open(filepath.Join(dir, "resume.db"))
if err != nil {
t.Fatal(err)
}
source := "# stage a\n\n```output\nA\n```\n\n```prompt\nA\n```\n\n```edges\nsuccess -> b\nerror -> #failure\n```\n\n```configs\ntype=model\nprovider=test\nmodel=test\n```\n\n# stage b\n\n```output\nB\n```\n\n```prompt\nB\n```\n\n```edges\nsuccess -> c\nerror -> #failure\n```\n\n```configs\ntype=model\nprovider=test\nmodel=test\n```\n\n# stage c\n\n```output\nC\n```\n\n```prompt\nC\n```\n\n```edges\nsuccess -> #success\nerror -> #failure\n```\n\n```configs\ntype=model\nprovider=test\nmodel=test\n```\n"
source = strings.Replace(source, "# stage b\n\n```output", "# stage b\n\n```memory\n{\"task\":\"input.prompt\",\"handoff\":\"a.handoff\"}\n```\n\n```output", 1)
if _, err := store.Submit(ctx, "resume", source); err != nil {
t.Fatal(err)
}
items, _ := store.List(ctx)
workspace := t.TempDir()
var aCalls, bCalls, cCalls int
r, err := newRunner(ctx, store)
if err != nil {
t.Fatal(err)
}
r.execute = func(_ context.Context, def stage.Definition, input stage.Values) (stage.Result, error) {
switch def.Key {
case "a":
aCalls++
if input["prompt"] != "task" {
t.Errorf("entry received altered input: %#v", input)
}
return stage.Result{Outcome: "success", Output: stage.Values{"handoff": "from-a"}}, nil
case "b":
bCalls++
if input["handoff"] != "from-a" {
t.Errorf("resume lost exact prefix handoff: %#v", input)
}
wantTask := "task"
if bCalls == 2 {
wantTask = "corrected"
}
if input["task"] != wantTask {
t.Errorf("selected retry memory input = %#v, want task %q", input["task"], wantTask)
}
if bCalls == 2 && input["correction"] != "use-new-plan" {
t.Errorf("selected retry lost input override: %#v", input)
}
if bCalls == 1 {
return stage.Result{}, fmt.Errorf("deliberate failure")
}
return stage.Result{Outcome: "success", Output: stage.Values{"handoff": "from-b"}}, nil
case "c":
cCalls++
if input["handoff"] != "from-b" {
t.Errorf("C received wrong handoff: %#v", input)
}
return stage.Result{Outcome: "success", Output: stage.Values{"summary": "done"}}, nil
default:
t.Fatalf("unexpected stage %q", def.Key)
return stage.Result{}, nil
}
}
original, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "original", Workspace: workspace, Input: map[string]any{"prompt": "task"}})
if err != nil {
t.Fatal(err)
}
r.wg.Wait()
original, err = store.GetRun(ctx, original.ID)
if err != nil || original.Status != "failed" || len(original.Steps) != 2 {
t.Fatalf("initial run did not stop at B: %+v %v", original, err)
}
retried, err := r.retry(protocol.Message{RunID: original.ID, RequestKey: "resume-key", RetryStage: "b", RetryInput: map[string]any{"task": "corrected", "correction": "use-new-plan"}})
if err != nil {
t.Fatal(err)
}
r.wg.Wait()
retried, err = store.GetRun(ctx, retried.ID)
if err != nil || retried.Status != "succeeded" || retried.RetryMode != "resume" || retried.RetrySource != original.ID {
t.Fatalf("resume did not complete with provenance: %+v %v", retried, err)
}
if aCalls != 1 || bCalls != 2 || cCalls != 1 {
t.Fatalf("retry duplicated prefix or suffix: A=%d B=%d C=%d", aCalls, bCalls, cCalls)
}
if len(retried.Steps) != 2 || retried.Steps[0].Stage != "b" || retried.Steps[1].Stage != "c" {
t.Fatalf("retry persisted the wrong steps: %+v", retried.Steps)
}
if retried.Steps[0].Input["task"] != "corrected" || retried.Steps[0].Input["correction"] != "use-new-plan" {
t.Fatalf("retry persisted the wrong selected input: %#v", retried.Steps[0].Input)
}
if err := store.Close(); err != nil {
t.Fatal(err)
}
store, err = pipeline.Open(filepath.Join(dir, "resume.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
r2, err := newRunner(ctx, store)
if err != nil {
t.Fatal(err)
}
replayed, err := r2.retry(protocol.Message{RunID: original.ID, RequestKey: "resume-key"})
if err != nil || replayed.ID != retried.ID {
t.Fatalf("persisted request-key replay lost its run: %+v %v", replayed, err)
}
}
func TestRetryResumeWithNativeToolsThroughHandlerAndCLI(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
dir := t.TempDir()
executable := filepath.Join(dir, "opencode")
script := `#!/bin/sh
if [ "$1" = "--help" ]; then echo ' api'; exit 0; fi
case "$3" in
/api/session/active) echo '{"data":{}}' ;;
/api/session)
n=0; if [ -f "@STATE@/sessions" ]; then n=$(cat "@STATE@/sessions"); fi
n=$((n+1)); echo "$n" > "@STATE@/sessions"
echo '{"data":{"id":"ses_native_'$n'"}}' ;;
*/prompt) echo '{}' ;;
*/wait) echo '{}' ;;
*/message*)
case "$3" in
*/ses_native_2/*) echo '{"data":[{"finish":"stop","content":[{"type":"text","text":"{\\"outcome\\":\\"invalid\\",\\"output\\":{\\"wrong\\":\\"format\\"}}"}]}]}' ;;
*/ses_native_3/*) echo '{"data":[{"finish":"stop","content":[{"type":"text","text":"{\\"outcome\\":\\"success\\",\\"output\\":{\\"handoff\\":\\"from-b\\"}}"}]}]}' ;;
*) echo '{"data":[{"finish":"stop","content":[{"type":"text","text":"{\\"outcome\\":\\"success\\",\\"output\\":{\\"handoff\\":\\"from-a\\",\\"summary\\":\\"done\\"}}"}]}]}' ;;
esac ;;
*) echo '{}' ;;
esac
`
if err := os.WriteFile(executable, []byte(strings.ReplaceAll(script, "@STATE@", dir)), 0700); err != nil {
t.Fatal(err)
}
t.Setenv("PIPELINES_OPENCODE", executable)
store, err := pipeline.Open(filepath.Join(dir, "runs.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
source := "# stage a\n\n```output\n{ handoff, summary }\n```\n\n```prompt\nDo A.\n```\n\n```tools\nread\nglob\ngrep\nshell\n```\n\n```edges\nsuccess -> b\nerror -> #failure\n```\n\n```configs\ntype=model\nprovider=opencode-go\nmodel=deepseek-v4.1-flash\nretries=0\n```\n\n# stage b\n\n```output\n{ handoff }\n```\n\n```prompt\nDo B.\n```\n\n```tools\nread\nglob\ngrep\nshell\n```\n\n```edges\nsuccess -> c\nerror -> #failure\n```\n\n```configs\ntype=model\nprovider=opencode-go\nmodel=deepseek-v4.1-flash\nretries=0\n```\n\n# stage c\n\n```output\n{ handoff, summary }\n```\n\n```prompt\nDo C.\n```\n\n```tools\nread\nglob\ngrep\nshell\n```\n\n```edges\nsuccess -> #success\nerror -> #failure\n```\n\n```configs\ntype=model\nprovider=opencode-go\nmodel=deepseek-v4.1-flash\nretries=0\n```\n"
if _, err := store.Submit(ctx, "native-resume", source); err != nil {
t.Fatal(err)
}
handler := Handler(ctx, store)
defer func() { cancel(); WaitRuns(handler) }()
items, err := store.List(ctx)
if err != nil {
t.Fatal(err)
}
srv := httptest.NewServer(handler)
defer srv.Close()
url := "ws" + strings.TrimPrefix(srv.URL, "http") + "/connect"
workspace := t.TempDir()
runCLI := func(args ...string) (protocol.Message, error) {
var out bytes.Buffer
app := cli.App{Out: &out, Err: &out, In: strings.NewReader("")}
err := app.Run(ctx, append([]string{"--url", url}, args...))
var result protocol.Message
if len(out.Bytes()) > 0 {
_ = json.Unmarshal(out.Bytes(), &result)
}
return result, err
}
first, err := runCLI("run", fmt.Sprint(items[0].Name), "task", "--yes", "--json", "--wait", "--timeout", "10s", "--workspace", workspace, "--request-key", "native-original")
if err == nil || first.RunDetail == nil || first.RunDetail.Status != "failed" || len(first.RunDetail.Steps) != 2 {
t.Fatalf("initial native run did not fail at B: %v %#v", err, first.RunDetail)
}
retried, err := runCLI("retry", fmt.Sprint(first.RunDetail.ID), "--yes", "--json", "--wait", "--timeout", "10s", "--request-key", "native-resume-key", "--mode", "resume")
if err != nil || retried.RunDetail == nil || retried.RunDetail.Status != "succeeded" {
t.Fatalf("native resume failed: %v %#v", err, retried.RunDetail)
}
if retried.RunDetail.RetryOf != first.RunDetail.ID || len(retried.RunDetail.Steps) != 2 || retried.RunDetail.Steps[0].Stage != "b" || retried.RunDetail.Steps[1].Stage != "c" {
t.Fatalf("native resume lost provenance or replayed prefix: %#v", retried.RunDetail)
}
sessions, err := os.ReadFile(filepath.Join(dir, "sessions"))
if err != nil || strings.TrimSpace(string(sessions)) != "4" {
t.Fatalf("native stage execution count = %q, want 4 (A once, B twice, C once): %v", sessions, err)
}
again, err := runCLI("retry", fmt.Sprint(first.RunDetail.ID), "--yes", "--json", "--request-key", "native-resume-key")
if err != nil || again.RunDetail == nil || again.RunDetail.ID != retried.RunDetail.ID {
t.Fatalf("same-key replay was not idempotent: %v %#v", err, again.RunDetail)
}
}
// TestReadOnlyStageRetriesPostAdmissionTransportButMutatingStageDoesNot proves,
// through the real runner and CLI fixture, that a read-only stage retries a
// post-admission transport (final-readback) failure with a fresh session while
+319 -5
View File
@@ -2,6 +2,7 @@ package server
import (
"context"
"encoding/json"
"errors"
"fmt"
"log"
@@ -285,6 +286,15 @@ func (r *runner) start(request protocol.Message, retryOf ...int64) (*protocol.Ru
r.rememberRunIdentity(id, identityOfRunSummary(detail.RunSummary))
}
if created {
if request.RetrySource > 0 && request.RetryMode != "restart" {
checkpoint, checkpointErr := r.retrySourceCheckpointSelected(request.RetrySource, d, request.RetryStage, request.RetryVisit, request.RetryInput)
if checkpointErr != nil {
return nil, checkpointErr
}
if err := r.store.SaveRetryCheckpoint(r.ctx, id, request.RetrySource, "resume", checkpoint.failed.Sequence, checkpoint.detail, checkpoint.handoff); err != nil {
return nil, err
}
}
// Emit the created delta before launching: the queued frame reaches
// subscribers before the running/step-started transition, so a client
// sees the run appear and then advance.
@@ -404,6 +414,192 @@ func (r *runner) listRuns() ([]protocol.RunSummary, error) {
return items, err
}
type retryCheckpoint struct {
detail *protocol.RunDetail
failed protocol.RunStep
handoff map[string]any
}
const maxRetryInputBytes = 64 * 1024
func retryInputOverride(base map[string]any, override map[string]any) (map[string]any, error) {
if override == nil {
return base, nil
}
encoded, err := json.Marshal(override)
if err != nil || len(encoded) > maxRetryInputBytes {
return nil, fmt.Errorf("retry input must be a JSON object no larger than %d bytes", maxRetryInputBytes)
}
reserved := map[string]bool{"pwd": true, "workspace": true, "write_paths": true, "allow_tools": true, "pipeline_id": true, "pipeline_version": true, "request_key": true, "retry_mode": true, "retry_source": true, "retry_stage": true, "retry_visit": true}
merged := map[string]any{}
for key, value := range base {
merged[key] = value
}
for key, value := range override {
if reserved[key] {
return nil, fmt.Errorf("retry input field %q is reserved", key)
}
merged[key] = value
}
return merged, nil
}
// retryStageContractEqual compares the complete persisted stage contract. A
// retry may carry completed output across a published version only when the
// stages that produced that output are unchanged; comparing only effective
// types would allow prompt, config, edge, resource, or limit changes through.
func retryStageContractEqual(left, right protocol.Stage) bool {
a, err := json.Marshal(left)
if err != nil {
return false
}
b, err := json.Marshal(right)
if err != nil {
return false
}
return string(a) == string(b)
}
func (r *runner) retrySourceCheckpoint(sourceID int64, pinned *protocol.PipelineDetail) (retryCheckpoint, error) {
return r.retrySourceCheckpointSelected(sourceID, pinned, "", 0, nil)
}
func (r *runner) retrySourceCheckpointSelected(sourceID int64, pinned *protocol.PipelineDetail, selectedStage string, selectedVisit int, override map[string]any) (retryCheckpoint, error) {
source, err := r.store.GetRun(r.ctx, sourceID)
if err != nil {
return retryCheckpoint{}, err
}
if source.Status != "failed" || source.FinishedAt == "" {
return retryCheckpoint{}, fmt.Errorf("retry source %d is not a terminal failed run", sourceID)
}
if source.PipelineID != pinned.ID {
return retryCheckpoint{}, fmt.Errorf("retry source %d belongs to a different pipeline", sourceID)
}
if len(source.Steps) == 0 {
return retryCheckpoint{}, fmt.Errorf("retry source %d has no failed stage checkpoint", sourceID)
}
failed := source.Steps[len(source.Steps)-1]
if selectedStage != "" {
failed = protocol.RunStep{}
visits := 0
for _, candidate := range source.Steps {
if candidate.Stage != selectedStage {
continue
}
visits++
if selectedVisit == 0 && visits == 1 {
failed = candidate
}
if selectedVisit > 0 && visits == selectedVisit {
failed = candidate
}
}
if failed.Stage == "" {
return retryCheckpoint{}, fmt.Errorf("retry stage %q was not recorded in run %d", selectedStage, sourceID)
}
if selectedVisit == 0 {
count := 0
for _, candidate := range source.Steps {
if candidate.Stage == selectedStage {
count++
}
}
if count > 1 {
return retryCheckpoint{}, fmt.Errorf("retry stage %q was visited %d times; --visit is required", selectedStage, count)
}
}
if selectedVisit > visits {
return retryCheckpoint{}, fmt.Errorf("retry stage %q has no visit %d", selectedStage, selectedVisit)
}
}
if (failed.Status != "completed" && failed.Status != "failed") || (selectedStage == "" && failed.Target != protocol.FailureEnd) {
return retryCheckpoint{}, fmt.Errorf("retry source %d has no safe failed-stage checkpoint", sourceID)
}
var handoff map[string]any
if failed.Input == nil {
return retryCheckpoint{}, fmt.Errorf("retry source %d is missing failed-stage handoff context", sourceID)
}
if _, err := retryInputOverride(failed.Input, override); err != nil {
return retryCheckpoint{}, err
}
// Keep the source-stage input immutable in the checkpoint. The selected
// stage's memory bindings must be resolved from the original prefix before
// this override is applied at invocation time.
handoff = map[string]any{"input": failed.Input, "override": override, "sequence": failed.Sequence, "stage": failed.Stage, "visit": failed.Sequence}
prefix := map[string]any{}
for _, step := range source.Steps {
if step.Sequence >= failed.Sequence || step.Status != "completed" {
continue
}
prefix[step.Stage] = step.Output
}
handoff["prefix"] = prefix
// A newer explicitly selected version may continue only when every recorded
// prefix stage still exists with the same kind. Its outputs are evidence from
// the source attempt and cannot be safely handed to a changed stage contract.
sourceStages := map[string]protocol.Stage{}
for _, declared := range source.Graph.Stages {
sourceStages[declared.Key] = declared
}
for _, step := range source.Steps {
if step.Sequence >= failed.Sequence {
break
}
var pinnedStage *protocol.Stage
for i := range pinned.Graph.Stages {
if pinned.Graph.Stages[i].Key == step.Stage {
pinnedStage = &pinned.Graph.Stages[i]
break
}
}
previous, ok := sourceStages[step.Stage]
if pinnedStage == nil || !ok || !retryStageContractEqual(previous, *pinnedStage) {
return retryCheckpoint{}, fmt.Errorf("retry source %d has incompatible changed prefix stage %q", sourceID, step.Stage)
}
}
var sourceSelected protocol.Stage
var sourceSelectedOK bool
if sourceSelected, sourceSelectedOK = sourceStages[failed.Stage]; !sourceSelectedOK {
return retryCheckpoint{}, fmt.Errorf("retry source %d failed stage is not in its recorded graph", sourceID)
}
pinnedStages := map[string]protocol.Stage{}
for _, declared := range pinned.Graph.Stages {
pinnedStages[declared.Key] = declared
}
// The retry will continue through every stage that the source execution
// already recorded after the selected checkpoint. Validate those stages
// before admitting the new run as well: otherwise an explicitly selected
// version can pass prefix/selected-stage validation and fail later in the
// loop with the less useful "missing stage" error.
for _, step := range source.Steps {
if step.Sequence <= failed.Sequence {
continue
}
if _, ok := pinnedStages[step.Stage]; !ok {
return retryCheckpoint{}, fmt.Errorf("retry source %d selected version is missing later stage %q", sourceID, step.Stage)
}
}
for _, declared := range pinned.Graph.Stages {
if declared.Key != failed.Stage {
continue
}
if stage.EffectiveType(sourceSelected.Type) != stage.EffectiveType(declared.Type) {
return retryCheckpoint{}, fmt.Errorf("retry source %d has incompatible selected stage %q", sourceID, failed.Stage)
}
typ := stage.EffectiveType(declared.Type)
if typ == stage.HumanType || typ == stage.NtfyType {
return retryCheckpoint{}, fmt.Errorf("retry source %d cannot replay completed external stage %s", sourceID, failed.Stage)
}
if typ == stage.ModelType {
if _, _, toolErr := stage.ToolNames(pipeline.StageDefinition(declared)); toolErr != nil {
return retryCheckpoint{}, toolErr
}
}
return retryCheckpoint{detail: source, failed: failed, handoff: handoff}, nil
}
return retryCheckpoint{}, fmt.Errorf("retry source %d failed stage is not in the pinned graph", sourceID)
}
func (r *runner) retry(request protocol.Message) (*protocol.RunDetail, error) {
if request.RunID <= 0 {
return nil, fmt.Errorf("retry requires a positive run ID")
@@ -418,7 +614,41 @@ func (r *runner) retry(request protocol.Message) (*protocol.RunDetail, error) {
if original.Status != "failed" || original.FinishedAt == "" {
return nil, fmt.Errorf("only failed runs can be retried (run %d is %s)", original.ID, original.Status)
}
return r.start(protocol.Message{PipelineID: original.PipelineID, Version: original.Version, RequestKey: request.RequestKey, Workspace: original.Workspace, Input: original.Input, AllowTools: original.AllowTools, WritePaths: original.WritePaths, Model: original.Model, StageModels: original.StageModels}, original.ID)
if request.RequestKey == "" {
return nil, fmt.Errorf("retry requires an idempotency request key")
}
// Resolve an already admitted request before validating optional retry
// selectors. This makes replay after a restart genuinely idempotent even
// when the original request used an input override that the replay omits.
if existing, err := r.store.RunByKey(r.ctx, request.RequestKey); err != nil {
return nil, err
} else if existing > 0 {
return r.store.GetRun(r.ctx, existing)
}
if request.RetryVisit < 0 || (request.RetryVisit > 0 && request.RetryStage == "") {
return nil, fmt.Errorf("retry visit requires a positive --stage visit selection")
}
mode := request.RetryMode
if mode == "" {
mode = "resume"
}
if mode != "resume" && mode != "restart" {
return nil, fmt.Errorf("retry mode must be resume or restart")
}
version := original.Version
if request.RetryVersion > 0 {
version = request.RetryVersion
}
d, err := r.store.Get(r.ctx, original.PipelineID, version)
if err != nil {
return nil, err
}
if mode == "resume" {
if _, err := r.retrySourceCheckpointSelected(original.ID, d, request.RetryStage, request.RetryVisit, request.RetryInput); err != nil {
return nil, err
}
}
return r.start(protocol.Message{PipelineID: original.PipelineID, Version: version, RequestKey: request.RequestKey, RetryMode: mode, RetrySource: original.ID, RetryStage: request.RetryStage, RetryVisit: request.RetryVisit, RetryInput: request.RetryInput, Workspace: original.Workspace, Input: original.Input, AllowTools: original.AllowTools, WritePaths: original.WritePaths, Model: original.Model, StageModels: original.StageModels}, original.ID)
}
func (r *runner) cancel(id int64) error {
@@ -520,6 +750,38 @@ func (r *runner) decide(request protocol.Message) (*protocol.RunDetail, error) {
}
func (r *runner) run(ctx context.Context, id int64, d *protocol.PipelineDetail, workspace string, request protocol.Message) {
if request.RetrySource > 0 && request.RetryMode != "restart" {
source, err := r.store.GetRun(ctx, request.RetrySource)
if err != nil {
r.finishRunState(id, d.Name, workspace, "failed", "error", err.Error(), 0, 0, "", nil)
return
}
checkpoint, err := r.retrySourceCheckpointSelected(request.RetrySource, d, request.RetryStage, request.RetryVisit, request.RetryInput)
if err != nil {
r.finishRunState(id, d.Name, workspace, "failed", "error", err.Error(), 0, 0, "", nil)
return
}
storedSource, storedMode, storedSequence, storedHandoff, checkpointErr := r.store.RetryCheckpoint(ctx, id)
if checkpointErr != nil || storedSource != request.RetrySource || storedMode != "resume" || storedSequence != checkpoint.failed.Sequence || storedHandoff == nil {
if checkpointErr == nil {
checkpointErr = fmt.Errorf("retry checkpoint is incomplete")
}
r.finishRunState(id, d.Name, workspace, "failed", "error", checkpointErr.Error(), 0, 0, "", nil)
return
}
if input, ok := storedHandoff["input"].(map[string]any); ok {
checkpoint.failed.Input = input
} else {
r.finishRunState(id, d.Name, workspace, "failed", "error", "retry checkpoint is missing handoff context", 0, 0, "", nil)
return
}
state := rebuildRetryState(source, checkpoint.failed)
if override, ok := storedHandoff["override"].(map[string]any); ok {
state.retryOverride = stage.Values(override)
}
r.runLoop(ctx, id, d.Graph, d.Name, workspace, request, state)
return
}
original, copyErr := copyValues(stage.Values(request.Input))
if copyErr != nil {
r.finishRunState(id, d.Name, workspace, "failed", "error", copyErr.Error(), 0, 0, "", stage.Values(request.Input))
@@ -595,6 +857,9 @@ type runState struct {
// running total without re-reading the store.
completed int
artifactDirs []string
// retryOverride is applied once, after the selected stage's memory bindings
// have been resolved. It is intentionally not part of run input or memory.
retryOverride stage.Values
}
func newRunState(key string, input stage.Values) *runState {
@@ -629,6 +894,34 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS
return state
}
// rebuildRetryState restores only the completed prefix. The failed visit is
// deliberately not counted and its step/evidence is not copied into the new
// attempt, so retries cannot duplicate execution or usage aggregates.
func rebuildRetryState(detail *protocol.RunDetail, failed protocol.RunStep) *runState {
state := newRunState(failed.Stage, stage.Values(failed.Input))
state.nextSequence = failed.Sequence
if original, err := copyValues(stage.Values(detail.Input)); err == nil {
state.memory["input"] = memoryValue{output: original}
}
for _, step := range detail.Steps {
if step.Sequence >= failed.Sequence {
break
}
state.visits[step.Stage]++
if step.Status == "completed" {
if values, err := copyValues(stage.Values(step.Output)); err == nil {
state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence}
}
state.completed++
}
state.recordChanges(step.FileChanges, step.Artifacts)
if step.Status == "completed" {
state.artifactDirs = append(state.artifactDirs, filepath.Join("", strconv.Itoa(step.Sequence)))
}
}
return state
}
// artifactAccess derives exact visit directories; it never consumes a path from
// a definition or model result. An unreadable or symlinked root fails closed.
func (r *runner) artifactAccess(runID int64, sequence int, prior []string, current string) stage.ArtifactAccess {
@@ -956,11 +1249,16 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
_, declaresSkip := def.Edges["skipped"]
skip := !isHuman && declaresSkip && !state.uiSurface
if selected.Resources != nil && !skip {
if isHuman || !pipeline.ValidResourceKey(selected.Resources.Exclusive) {
if isHuman || (selected.Resources.Exclusive == "" && selected.Resources.Pool == "") || (selected.Resources.Exclusive != "" && selected.Resources.Pool != "") || (selected.Resources.Exclusive != "" && !pipeline.ValidResourceKey(selected.Resources.Exclusive)) || (selected.Resources.Pool != "" && !pipeline.ValidResourceKey(selected.Resources.Pool)) {
finish("failed", "error", "invalid persisted resource declaration")
return
}
lease, err := r.acquireResource(ctx, pipeline.ResourceVisit{Resource: selected.Resources.Exclusive, RunID: id, Stage: key, Sequence: sequence}, workspace, state.completed)
resource := selected.Resources.Exclusive
pool := selected.Resources.Pool
if pool != "" {
resource = pool
}
lease, err := r.acquireResourceWithPool(ctx, pipeline.ResourceVisit{Resource: resource, RunID: id, Stage: key, Sequence: sequence}, pool, workspace, state.completed)
if err != nil {
if ctx.Err() != nil {
finish("canceled", "", err.Error())
@@ -984,6 +1282,16 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
finish("failed", "error", copyErr.Error())
return
}
if state.retryOverride != nil {
input, copyErr = retryInputOverride(input, state.retryOverride)
if copyErr != nil {
finish("failed", "error", copyErr.Error())
return
}
// A selected-stage override belongs only to this invocation, not to
// a later visit reached through the stage graph.
state.retryOverride = nil
}
if err := r.store.BeginStep(ctx, id, sequence, key, input); err != nil {
if ctx.Err() != nil {
finish("canceled", "", ctx.Err().Error())
@@ -1107,6 +1415,9 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
var piClient *stage.PiClient
var err error
stageCtx := ctx
if held != nil && held.Target != nil {
stageCtx = stage.WithResourceTarget(stageCtx, held.Target)
}
var modelConfig stage.ModelConfig
var budgetBefore stage.BudgetSnapshot
if stage.EffectiveType(def.Type) == stage.ModelType {
@@ -1123,7 +1434,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
// its cumulative usage before the visit and record only this visit's
// increment on the step, never the cumulative total again.
budgetBefore = budgets[key].Snapshot()
stageCtx = stage.WithBudget(ctx, budgets[key])
stageCtx = stage.WithBudget(stageCtx, budgets[key])
}
snapshotCtx, snapshotCancel := context.WithTimeout(ctx, 5*time.Second)
before := filediff.Capture(snapshotCtx, workspace)
@@ -1185,7 +1496,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
result, err = (stage.ModelStage{Client: plain}).Run(stageCtx, def, input)
client.Transcript = plain.FormatAudit
} else {
result, err = stage.DefaultRegistry().Run(ctx, def, input)
result, err = stage.DefaultRegistry().Run(stageCtx, def, input)
}
}()
if held != nil {
@@ -1286,6 +1597,9 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
}
step.Target = def.Edges[step.Outcome]
step.Control = &protocol.ControlEvidence{Visit: state.visits[key], MaxVisits: maxVisits, Memory: reads}
if held != nil && held.Target != nil {
step.Control.ResourceTarget = held.Target
}
if err == nil && selected.Limits != nil && state.visits[key] >= maxVisits {
for _, outcome := range selected.Limits.On {
if outcome == step.Outcome {
+1 -1
View File
@@ -173,7 +173,7 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
}
for {
var request protocol.Message
if err := wsjson.Read(ctx, conn, &request); err != nil {
if err := wsjson.Read(connCtx, conn, &request); err != nil {
return
}
log.Printf("command received: client=%s type=%q id=%q pipeline=%d version=%d", r.RemoteAddr, request.Type, request.ID, request.PipelineID, request.Version)
+26
View File
@@ -5,8 +5,34 @@ package stage
import (
"context"
"fmt"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
type resourceTargetContextKey struct{}
// WithResourceTarget attaches the server-granted concrete target to a stage's
// runtime context. It is deliberately separate from model input and contains
// no capability or credential material.
func WithResourceTarget(ctx context.Context, target *protocol.ResourceTarget) context.Context {
if target == nil {
return ctx
}
copy := &protocol.ResourceTarget{Member: target.Member}
if target.Metadata != nil {
copy.Metadata = map[string]string{}
for key, value := range target.Metadata {
copy.Metadata[key] = value
}
}
return context.WithValue(ctx, resourceTargetContextKey{}, copy)
}
func ResourceTarget(ctx context.Context) (*protocol.ResourceTarget, bool) {
target, ok := ctx.Value(resourceTargetContextKey{}).(*protocol.ResourceTarget)
return target, ok
}
// Values are runtime data, not the prose output contract in a definition.
type Values map[string]any
+6
View File
@@ -32,6 +32,12 @@ func TestRetryShortcutAndPaletteSendServerRetryWithoutReplacingDirectory(t *test
if err != nil {
t.Fatal(err)
}
if err := store.BeginStep(ctx, id, 1, "one", map[string]any{"prompt": "original task"}); err != nil {
t.Fatal(err)
}
if err := store.FinishStep(ctx, id, protocol.RunStep{Sequence: 1, Stage: "one", Status: "failed", Outcome: "error", Target: protocol.FailureEnd, Input: map[string]any{"prompt": "original task"}}); err != nil {
t.Fatal(err)
}
if err := store.FinishRun(ctx, id, "failed", "error", "original failure", nil); err != nil {
t.Fatal(err)
}