Files
pipelines/internal/protocol/runs.go
T
alan 0f5a188c6a Record and serve per-stage artifacts
Every agent stage now writes into a per-run/step artifacts directory under
the data dir (<data>/artifacts/<run>/<step>), passed to Pi as
PIPELINES_ARTIFACTS_DIR, exposed on the OpenCode client env seam, and stated
in the agent prompt boilerplate so agents save images, screenshots, reports
and logs there.

After each step the server scans that directory with a bounded, symlink- and
traversal-safe inventory (os.OpenRoot + Lstat + O_NOFOLLOW) recording name,
size_bytes, content type (extension then 512-byte sniff fallback) and URL,
enforcing max files, per-file bytes and total bytes while counting skipped
and truncated entries. A missing, unreadable or oversized directory yields
only a best-effort diagnostic and never changes the step outcome.

The list is carried on protocol.RunStep as Artifacts []StageArtifact plus
skipped/truncated counters (omitempty, backwards compatible), persisted in a
new step_artifacts table keyed (run_id, sequence) alongside the
notifications/file-changes tables and loaded by GetRun.

GET /artifacts/{run}/{step}/{name} on the existing handler serves the bytes
with http.ServeContent, so Content-Type, Content-Length, HEAD and Range
(206/416) come from the stdlib; unknown runs/steps, absolute paths,
traversal, symlink escapes and non-regular files are refused.

The TUI lists each selected step's artifacts (name + human size) in the
retained-evidence section and adds an artifacts summary in the style of the
file-changes summary. Adds docs/stage-artifacts.md linked from README and an
artifacts subsection to the packaged operations skill reference.

Tests cover the scan records and caps, missing/oversized directories,
HTTP HEAD/Range/traversal/symlink/unknown refusals and protocol round-trips.
2026-10-15 17:51:18 +01:00

130 lines
4.9 KiB
Go

package protocol
const (
RunPipeline = "run_pipeline"
RunStarted = "run_started"
ListRuns = "list_runs"
Runs = "runs"
GetRun = "get_run"
Run = "run"
CancelRun = "cancel_run"
RetryRun = "retry_run"
GetRunEvidence = "get_run_evidence"
RunEvidence = "run_evidence"
)
type SessionEvidence struct {
Sequence int `json:"sequence"`
SessionID string `json:"session_id"`
Backend string `json:"backend"`
Directory string `json:"directory"`
Data string `json:"data,omitempty"`
Diagnostic string `json:"diagnostic,omitempty"`
}
type RunSummary struct {
ID int64 `json:"id"`
PipelineID int64 `json:"pipeline_id"`
Name string `json:"name"`
Version int `json:"version"`
ContentHash string `json:"content_hash"`
Status string `json:"status"`
Executing bool `json:"executing"`
Outcome string `json:"outcome"`
CurrentStage string `json:"current_stage"`
CreatedAt string `json:"created_at"`
FinishedAt string `json:"finished_at"`
Diagnostic string `json:"diagnostic"`
ResultPreview string `json:"result_preview,omitempty"`
CompletedSteps int `json:"completed_steps"`
}
type RunStep struct {
Control *ControlEvidence `json:"control,omitempty"`
FileChanges *StageFileChanges `json:"file_changes,omitempty"`
Notifications []NotificationReceipt `json:"notifications,omitempty"`
Artifacts []StageArtifact `json:"artifacts,omitempty"`
Sequence int `json:"sequence"`
Stage string `json:"stage"`
Status string `json:"status"`
Outcome string `json:"outcome"`
Target string `json:"target"`
Input map[string]any `json:"input"`
Output map[string]any `json:"output"`
Diagnostic string `json:"diagnostic"`
SessionID string `json:"session_id"`
AgentActive bool `json:"agent_active"`
Transcript string `json:"transcript"`
// ArtifactsSkipped and ArtifactsTruncated count files excluded from the
// bounded per-step scan (over the file/size cap) and by the total budget.
ArtifactsSkipped int `json:"artifacts_skipped,omitempty"`
ArtifactsTruncated int `json:"artifacts_truncated,omitempty"`
StartedAt string `json:"started_at"`
FinishedAt string `json:"finished_at"`
}
// StageArtifact is one file a stage left in its artifacts directory. It is
// observed server-side evidence, not a model's claim. An empty Artifacts slice
// means no files were recorded (including historical steps).
type StageArtifact struct {
Name string `json:"name"`
SizeBytes int64 `json:"size_bytes"`
ContentType string `json:"content_type"`
URL string `json:"url"`
}
type MemoryRead struct {
Source string `json:"source"`
Sequence int `json:"sequence"` // zero denotes original run input
}
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"`
}
// StageFileChanges is observed workspace evidence, not a model's claim of authorship.
// Nil means no capture was retained (including historical steps).
type StageFileChanges struct {
Omitted int `json:"omitted,omitempty"`
Scope string `json:"scope,omitempty"`
Status string `json:"status"` // complete, partial, unavailable
Files []FileChange `json:"files"`
Skipped int `json:"skipped"`
Diagnostic string `json:"diagnostic,omitempty"`
}
type FileChange struct {
Path string `json:"path"`
Kind string `json:"kind"` // added, modified, deleted
Patch string `json:"patch,omitempty"`
Binary bool `json:"binary,omitempty"`
Truncated bool `json:"truncated,omitempty"`
BeforeMode string `json:"before_mode,omitempty"`
AfterMode string `json:"after_mode,omitempty"`
}
type NotificationReceipt struct {
Destination string `json:"destination"`
Status string `json:"status"`
Filename string `json:"filename,omitempty"`
MessageID string `json:"message_id,omitempty"`
AttachmentURL string `json:"attachment_url,omitempty"`
Diagnostic string `json:"diagnostic,omitempty"`
}
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"`
}